Inicialização da documentação
Esta é uma tarefa única e volumosa. Para alterações posteriores, use engineering:documentation-sync.
1. Faça um inventário
Liste os documentos que existem e marque cada um como presente, fino (existe, mas está quase vazio ou desatualizado) ou ausente. Verifique pelo menos:
README.md, CONTRIBUTING.md, CHANGELOG.md, ARCHITECTURE.md ou docs/architecture/, registros de decisão, CLAUDE.md, SECURITY.md, LICENSE, a referência da API, a referência de configuração, runbooks.
git ls-files '*.md' | grep -v node_modules
2. Deixe o usuário escolher
Mostre o menu de resources/doc-catalog.md. Marque cada tipo como presente, fino ou ausente. Marque os tipos que você recomenda para este tipo de projeto.
- Documentos presentes não são reescritos. O usuário pode escolher "revisar" para um documento fino.
- O usuário escolhe. Não escreva um tipo que o usuário não escolheu.
3. Construa a ficha técnica
Antes de alguém escrever, colete os fatos que mais de um documento usará. Extraia-os do código e do git, não da memória. Escreva-os em um arquivo temporário.
| Fato | Fonte |
|---|---|
| Nome do projeto e propósito em uma frase | README, manifesto, o usuário |
| Versão atual | manifesto, última tag (git describe --tags --abbrev=0) |
| Linguagens, frameworks e suas versões | manifestos e arquivos de bloqueio |
| Comandos de instalação, teste, lint, compilação e execução | engineering:development-commands |
| Componentes e seus nomes | estrutura de diretórios, pontos de entrada, arquivos compose |
| Variáveis de ambiente e configurações | .env.example, e o código que lê configurações (procure por process.env, os.environ, getenv) |
| Datas importantes | o primeiro commit (git log --reverse), as tags |
| O que funciona hoje, o que não funciona | o usuário, issues abertas |
Se duas fontes discordarem, pergunte ao usuário. Não escolha uma silenciosamente. Todo escritor usa apenas a ficha técnica e o código.
4. Escreva
- Três documentos ou menos: escreva você mesmo, um após o outro.
- Mais de três: inicie um subagente para cada documento ou pequeno grupo, no máximo quatro por vez. Dê a cada subagente:
- o(s) arquivo(s) exato(s) de sua responsabilidade, e a regra de que não pode alterar nenhum outro arquivo;
- a ficha técnica;
- o esboço de seções para seu tipo, de
resources/doc-catalog.md; - a instrução para escrever em Inglês Técnico Simplificado (a habilidade
simple-english, se instalada); - a instrução para relatar fatos que precisou e não encontrou, em vez de inventá-los.
Não invente histórico, números, usuários ou funcionalidades. Escreva "TBD" e liste para o usuário.
5. Verifique o conjunto
Siga resources/consistency-check.md. Corrija todo problema antes de continuar.
6. Faça commit
Coloque os documentos em um branch (engineering:git-branching) e abra um PR (engineering:github-pr-merge). No corpo do PR, liste cada novo documento e cada "TBD" que precisa de uma resposta do usuário.
Habilidades relacionadas
engineering:documentation-sync: mantém esses documentos corretos após esta inicialização.gener8v:brownfield: integra uma base de código existente ao pipeline gener8v. Ela escreve o contexto.gener8v/, não estes documentos de projeto.