Escrever e revisar documentação de segurança para desenvolvedores

## Escrever conselhos que desenvolvedores possam aplicar, sem sair da segurança Escreva para desenvolvedores, e não para especialistas em segurança. As orientações devem ser precisas, práticas, concisas e apresentar uma posição clara. Prefira bons conselhos que um desenvolvedor consiga aplicar a conselhos teoricamente ideais, mas complexos demais para serem seguidos. Mantenha todas as recomendações dentro do modelo de ameaças de segurança do documento. Conselhos gerais sobre qualidade do código, desempenho e arquitetura devem ser tratados em outro lugar, a menos que controlem diretamente um risco de segurança. Considere as regras de contribuição obrigatórias para todas as ferramentas de autoria. Preserve o processo humano oficial e os guias de redação do repositório, e use o guia mais curto para agentes apenas como um resumo operacional. ## Ler cada fonte citada e conferir se ela sustenta a afirmação Acesse e leia todas as fontes citadas e, em seguida, confirme que elas sustentam a afirmação exata. Nunca invente nem adivinhe uma URL, cite uma página que redirecione para uma página de destino sem relação com o assunto, nem dependa da memória de treinamento ou de um resumo. Crie um link para a página ou seção específica que contenha a evidência de apoio. Verifique as referências cruzadas internas antes de usá-las. Não aponte para um documento ou uma âncora inexistente. Quando forem aplicáveis verificações de densidade de citações, inclua pelo menos uma citação HTTPS incorporada em cada nova seção H2. Forneça apoio separado para afirmações novas, surpreendentes, específicas de parâmetros ou contestáveis; práticas comuns consolidadas não precisam de uma citação em cada frase. As fontes podem aparecer incorporadas ao texto ou reunidas em uma seção de Referências. Prefira normas, orientações de segurança governamentais ou setoriais, documentação oficial de projetos e fornecedores, referências de plataformas bem mantidas, repositórios de origem canônicos e pesquisas revisadas por pares. Evite fazendas de conteúdo publicitário otimizadas para mecanismos de busca. As verificações de citações estabelecem apenas um patamar mínimo; elas não provam que o conteúdo está correto. ## Dar uma medida para cada ameaça e dizer o que ela não impede As citações são necessárias, mas não são suficientes. Associe cada ameaça a uma contramedida concreta e declare explicitamente contra o que o controle protege e contra o que não protege. Não introduza ataques fora do modelo de ameaças declarado sem uma ressalva clara. Um controle para uma camada não deve ser apresentado como proteção contra o comprometimento de outra camada. Acrescente somente orientações que realmente constituam um controle ou um risco de segurança. Analise separadamente a correção, a viabilidade para desenvolvedores e a relevância para o tema; uma recomendação incorreta deve ser rejeitada mesmo que esteja bem referenciada. ## Manter cada mudança pequena e usar links em vez de copiar Limite cada alteração a um único documento de orientação ou a um conjunto pequeno e claramente coordenado. Quando esses forem os limites declarados pelo repositório, não ultrapasse três documentos de conteúdo nem 1.500 linhas líquidas adicionadas sem uma ocorrência de acompanhamento aprovada. Mantenha as alterações de dependências, automação e somente correções de digitação sujeitas às próprias regras de escopo. Comece em uma ramificação limpa baseada na ramificação padrão e mantenha um tema por ramificação. Nunca abra duas solicitações de alteração a partir da mesma ramificação, pois alterações sem relação podem vazar de uma para a outra. Exija uma ocorrência aprovada antes de propor um documento de orientação novo ou substancialmente reescrito. Não agrupe ajustes oportunistas de formatação, edições em massa nem correções sem relação com o tema. Antes de acrescentar uma seção, pesquise no documento atual, nos documentos relacionados e no índice do repositório. Crie links para orientações existentes em vez de reproduzi-las. Preserve famílias documentais com arquitetura radial criadas de forma intencional. Referências cruzadas coordenadas são válidas; copiar a orientação de outro documento não é. Se um conteúdo pertencer a outro tema, transfira-o para o documento existente ou novo apropriado, em vez de ampliar à força o escopo atual. ## Explicar primeiro o design e usar código só quando o tema pedir Para temas gerais, priorize padrões de arquitetura, princípios de projeto e decisões de segurança em vez de código específico de uma linguagem. O código envelhece rapidamente, e trechos isolados podem se tornar inseguros quando copiados sem o contexto original. Use código livremente quando o tema for inerentemente específico de uma linguagem, centrado em injeção ou parametrização, ou relacionado a um reforço concreto. Uma alta densidade de código é adequada quando os detalhes executáveis constituem a orientação de segurança, em vez de serem código padronizado incidental. Mantenha curto o código ilustrativo, identifique os blocos delimitados com uma linguagem quando for viável e não apresente exemplos como prontos para produção, a menos que tenham sido projetados e revisados segundo esse padrão. ## Cortar o enchimento e recomendar uma abordagem clara Corte preâmbulos genéricos, contexto repetido, listas exaustivas de opções e introduções em voga, mas vazias. Recomende uma abordagem específica e explique apenas o contexto necessário para um desenvolvedor aplicá-la com segurança. Use inglês dos Estados Unidos, execute verificações de ortografia e terminologia e mantenha as frases acessíveis a leitores não nativos. Defina siglas não evidentes na primeira utilização, mas deixe sem explicação as abreviações de protocolos e localizadores conhecidas universalmente quando o guia de estilo permitir. Reescreva ou descarte trechos que pareçam texto automatizado genérico. A concisão não deve apagar restrições, exceções, limites das ameaças nem o motivo pelo qual uma recomendação é mais segura. ## Seguir as regras do repositório para Markdown e imagens Use Markdown e evite HTML bruto, exceto pelos elementos permitidos explicitamente, como `details` e `summary`. Use de forma consistente hifens em listas, negrito de Markdown e citações em bloco. Deixe uma linha em branco depois de cada título. Um documento típico começa com um H1 e uma Introdução, segue com seções H2 focadas e pode terminar com Referências. De três a seis seções H2 é uma orientação padrão útil, não um limite máximo rígido. Não acrescente um sumário manual quando as ferramentas de publicação o gerarem. Siga o contrato de nomes de arquivo do repositório. Use somente letras, números, hifens e sublinhados, e mantenha qualquer sufixo obrigatório, como `_Cheat_Sheet.md`. Inicie novos documentos a partir do modelo aprovado. Armazene os recursos no diretório de recursos designado. Use o formato de imagem aprovado, forneça um texto alternativo significativo e referencie os recursos pelo caminho relativo correto. Escreva links incorporados com rótulos descritivos e use HTTPS sempre que possível. ## Executar o lint e a verificação de links antes de pedir revisão Execute a verificação de Markdown, a verificação de terminologia e o verificador de links definidos pelo repositório antes de propor alterações. Execute também as verificações de escopo, densidade de citações e outras políticas aplicáveis ao conteúdo modificado. Trate uma verificação local ou de integração contínua que falhou como um defeito a investigar, não como um motivo para contornar a verificação. Analise a diferença final para que alterações geradas ou automatizadas não ocultem edições sem relação. Entenda o limite da automação. Verificações mecânicas podem detectar Markdown malformado, terminologia proibida, links inativos, escopo excessivo e padrões de citação ausentes, mas não podem determinar se uma fonte sustenta uma afirmação, se um conselho está correto, se o tema pertence ao documento ou se o conteúdo duplica orientações existentes. ## Declarar o uso de IA e revisar por vários ângulos Divulgue o uso relevante de assistência de IA na descrição da solicitação de alteração. Registre o nome da ferramenta, a versão conhecida e a instrução fornecida na seção de divulgação designada do repositório. Esse requisito se aplica a todas as ferramentas de IA; a omissão pode invalidar a contribuição. Revise as orientações de segurança em dimensões separadas: correção de segurança, viabilidade para desenvolvedores, qualidade das fontes e dos links, duplicação e localização do conteúdo, e qualidade da linguagem. Revisores especializados podem trabalhar de forma independente, mas suas conclusões devem ser consolidadas em um único parecer baseado em evidências. Use resultados explícitos, como aceitar, solicitar alterações ou encerrar. Cite evidências concretas para constatações que impeçam a aprovação, diferencie falhas mecânicas de falhas de julgamento e não aprove apenas porque existem citações ou verificações automatizadas.