Criação de Documentação Técnica
Compile a documentação técnica em um repositório de conhecimento estável, de fácil manutenção e navegação. Primeiro, decida a qual lugar um fato pertence e o que o leitor precisa; depois, organize o conteúdo; por fim, refine a expressão.
Princípios fundamentais
- Antes de escrever, identifique o tipo de informação; não transforme o processo de descoberta diretamente na estrutura do artigo.
- Cada fato persistente tem um único proprietário canônico; o proprietário pode ser código-fonte, configuração, schema, gerador, documento ou registro de decisão.
- Escolha o tipo de documento com base na intenção do leitor (reader intent), e não no nome do arquivo ou no material já existente.
- Antes de começar a escrever, estabeleça um Contrato de Documento: leitor, objetivo, tópico, escopo, exclusões, fontes autoritativas e teto de detalhamento.
- O tipo de documento não pode expandir o escopo; o documento de nível superior resume os filhos diretos e linka para o proprietário dos detalhes.
- Organize o conteúdo por pré-condições, dependências e resultados verificáveis, e não pela ordem de investigação, implementação ou commit.
- Coloque o estado atual, a justificativa do design e a narrativa histórica em responsabilidades de documentos diferentes.
- Ao cruzar fronteiras, linke para os detalhes autoritativos; mantenha apenas o conteúdo que está dentro do escopo atual e é suficientemente estável.
- Antes de decidir delegar, o agente principal deve congelar o plano de criação; agentes secundários executam apenas tarefas de escrita local com limites claros.
Contrato de trabalho
Antes de executar escrita, reescrita, divisão, mesclagem ou revisão estrutural, forme um Contrato de Documento breve. Pode ser feito internamente; torne-o um artefato visível apenas quando a tarefa precisar de alinhamento.
Registre os seguintes campos:
- Intenção do leitor: O leitor quer aprender, concluir uma tarefa, consultar, entender, rastrear ou seguir regras.
- Tipo de documento: O tipo principal de documento que corresponde à intenção; um documento mantém apenas uma intenção principal.
- Tópico: O tópico ou nível do sistema pelo qual o documento é diretamente responsável.
- Escopo: Objetos, comportamentos e profundidade incluídos.
- Exclusões: Conteúdo explicitamente deixado para outros documentos ou fontes autoritativas.
- Autoridades: Código-fonte, configuração, arquivos gerados, registros de decisão ou documentos existentes que sustentam os fatos atuais.
- Teto de detalhamento: O nível máximo de detalhe permitido para o tópico e os objetivos do leitor atuais.
Se não for possível determinar o proprietário, a intenção do leitor, o escopo ou as fontes autoritativas, mantenha a incerteza e relate as lacunas; não invente decisões de produto ou comportamento atual com base em experiência.
Fluxo de trabalho de criação
1. Localize a tarefa e a posição do documento
Identifique se é uma criação, atualização, divisão, mesclagem ou revisão estrutural. Leia os arquivos aplicáveis AGENTS.md, CLAUDE.md, CONTEXT.md, índices de documentação e documentos adjacentes para confirmar a hierarquia, nomenclatura e convenções de link existentes no repositório.
Se o documento de destino não existir, trate a tarefa como documentação greenfield: a partir dos diretórios de código, APIs públicas, schemas de configuração, testes, exemplos, comandos e arquivos gerados, construa um mapa candidato de documentação. Primeiro, decida se é necessário um documento de entrada ou um conjunto de documentos divididos por proprietário e intenção do leitor; não comprima todo o arcabouço de código em um único documento abrangente.
Condição de conclusão: quando já existir documentação, saiba o caminho de destino, o documento pai, os filhos diretos e as regras locais aplicáveis; quando não houver documentação existente, saiba os principais limites do arcabouço de código, o conjunto candidato de documentos, o proprietário preliminar de cada documento e as fontes autoritativas.
2. Faça um inventário e classifique as informações
Liste os fatos, explicações, etapas, exemplos, limitações e materiais históricos que pretende manter. Classifique por tipo de informação e diferencie estado atual, justificativa persistente, procedimentos operacionais, materiais de consulta, regras, incidentes e conteúdo gerado.
Se precisar de uma tabela de classificação detalhada, leia references/information-and-ownership.md.
Condição de conclusão: cada bloco de conteúdo candidato tem um tipo de informação; não misture materiais de tipos diferentes em um parágrafo não definido.
3. Roteie os fatos para o proprietário canônico
Para cada fato persistente, procure um proprietário existente. Priorize código-fonte, configuração, schema, geradores e registros de decisão existentes como fontes autoritativas; o documento possui apenas as explicações, procedimentos ou contratos estáveis que estão dentro de sua responsabilidade.
Conteúdo que já tem um proprietário mantenha apenas um resumo necessário e um link para o proprietário. Se encontrar vários proprietários conflitantes, primeiro relate o conflito e registre a questão de autoridade que precisa ser resolvida.
Condição de conclusão: cada fato não trivial tem um e apenas um proprietário; o documento atual não duplica detalhes autoritativos de outro lugar.
4. Selecione o tipo de documento com base na intenção do leitor
Com base no objetivo do leitor, escolha entre Tutorial, How-to, Reference, Explanation, ADR, Policy ou Postmortem. Não atribua vários tipos principais a um arquivo só porque ele contém vários tipos de conteúdo; divida o documento quando a intenção mista prejudicar a navegação ou a manutenção.
Leia references/document-types-and-composition.md para obter padrões de seleção de tipo e estrutura.
Condição de conclusão: seja capaz de dizer em uma frase "quem lê este documento para quê" e identificar um tipo de documento principal.
5. Fixe o escopo e o teto de detalhamento
Escreva o tópico, público, objetivo, itens incluídos, exclusões, fontes autoritativas e teto de detalhamento. Limite o documento ao seu tópico, nível e responsabilidades dos filhos diretos; mova mecanismos de nível inferior, testes, listas de verificação e detalhes de implementação para o proprietário.
O tipo de documento não pode expandir o escopo. O documento pai descreve composição, responsabilidades e comportamento de alto nível; os documentos filhos possuem definições de tipo, parâmetros, mecanismos de teste ou operações específicas.
Condição de conclusão: cada seção pode responder "como ela atende ao objetivo atual do leitor e ao escopo"; o material que ultrapassa os limites já tem um destino ou link.
6. Forme um plano de criação executável
Primeiro, organize os conceitos pré-requisito que o leitor precisa conhecer; depois, organize as operações, explicações ou consultas que dependem deles. Use a estrutura correspondente ao tipo de documento; não transforme a ordem de investigação, implementação, discussão ou commit em ordem pedagógica.
Para documentos grandes, registre a árvore de seções, proprietário dos fatos, dependências entre seções, arquivos de destino, exclusões e critérios de aceitação de cada seção. O plano deve permitir que outro agente conclua uma tarefa local sem redesenhar a estrutura global.
Condição de conclusão: o leitor não precisa pular para seções posteriores para entender termos necessários, pré-condições ou ações das seções anteriores; cada parágrafo principal atende a uma pergunta clara; cada unidade do plano tem escopo e critérios de conclusão únicos.
7. Escolha o modo de execução e delegue
Por padrão, adote o caminho de agente único. Inicie subagentes apenas quando as seguintes condições forem atendidas simultaneamente:
- O plano já foi congelado e não há conflitos não resolvidos sobre intenção do leitor, tipo de documento, escopo, proprietário e estrutura principal.
- Existem pelo menos duas unidades de trabalho que podem ser lidas, escritas e aceitas de forma independente.
- Cada unidade de trabalho tem um arquivo de destino ou proprietário de seção único, e as tarefas não editarão concorrentemente o mesmo texto.
- As dependências foram registradas explicitamente; fatos que precisam ser compartilhados já têm uma fonte autoritativa, em vez de depender de suposições entre subagentes.
- O custo de delegar e mesclar é menor que o custo do agente principal carregar continuamente todo o contexto do documento.
Quando as condições forem atendidas, leia references/orchestration-and-delegation.md. O agente principal gera um briefing de delegação e invoca os subagentes. O agente principal mantém o plano global, a atribuição de fatos, os links entre seções, as decisões de mesclagem e a aprovação final. Os subagentes não redesenham o tipo de documento, não modificam outras unidades de trabalho e não escrevem fatos não comprovados como conclusões.
Se as condições não forem atendidas, o agente principal continua a escrever sozinho. Complementações locais de arquivo único, revisões de poucos parágrafos, atualizações de Reference com um único proprietário e dependências fortemente sequenciais são caminhos de agente único.
Condição de conclusão: a escolha entre single-agent ou delegated execution já está clara; se delegar, todas as tarefas têm limites, dependências, formato de saída e critérios de aceitação.
8. Escreva contratos e comportamento observável diretamente
Expresse o conteúdo com sujeitos, ações, APIs, opções e resultados concretos. Primeiro, escreva o estado atual e o comportamento observável pelo leitor; depois, complemente valores padrão, limitações, exceções, justificativas e trade-offs. Diferencie claramente entre "deve", "padrão", "recomendado" e "pode".
Tutoriais e How-tos podem centralizar a explicação em exemplos mínimos; References focam em definições pesquisáveis e seus limites; ADRs e Postmortems mantêm a justificativa ou linha do tempo necessária.
Para regras completas e listas de verificação, leia references/writing-and-validation.md.
Condição de conclusão: o corpo do texto declara fatos, contratos ou etapas sustentáveis, e não raciocínios, diários de implementação ou metalinguagem vaga; a saída das tarefas delegadas já foi recolhida pelo agente principal.
9. Mescle e uniformize
Se usar subagentes, o agente principal verifica cada saída item por item em relação ao plano de criação. Resolva fatos duplicados, deriva de terminologia, limites de seção, links cruzados e inconsistências de estilo; registre centralizadamente os problemas não resolvidos, sem permitir que agentes locais inventem decisões globais. Não incorpore o processo dos subagentes diretamente no texto principal; mescle apenas os resultados sustentáveis.
Condição de conclusão: cada unidade delegada tem um resultado ou motivo claro de bloqueio; o mesmo fato não tem vários proprietários; o sumário global, links, terminologia e caminho do leitor são consistentes.
10. Linke, contraia e valide
Remova fatos duplicados, listas copiadas, antecedentes irrelevantes e detalhes acima do teto de detalhamento. Linke para proprietários, documentos filhos, código-fonte e registros de decisão com links que expliquem o objetivo. Conclua as validações estruturais e linguísticas na ordem dos arquivos de referência.
Condição de conclusão: proprietário, tipo, escopo, ordem de dependência, limites atuais/históricos, links e regras de expressão foram verificados; não há conflitos ou incertezas não tratados.
Limites
Não transforme hierarquias de arquivos específicas do repositório, comandos de script, orçamento de palavras, regras de compilação de blocos de código, processos bilíngues ou terminologia específica em regras gerais. Leia as convenções locais do projeto e obedeça a elas; esta Skill fornece apenas um framework de decisão de documentação estável entre projetos.
Não trate README, architecture.md ou AGENTS.md como tipos de documento fixos e gerais. Primeiro, julgue a intenção do leitor; depois, siga as convenções específicas do projeto para esses artefatos.
Entrega final
Ao concluir, explique brevemente: o tipo de documento e a intenção do leitor, o tratamento dos proprietários canônicos, os limites de escopo, os links ou divisões envolvidos, e os conflitos factuais que ainda precisam de decisão humana. Não disfarce problemas não resolvidos como estado atual.