documentação-técnica

Documentação Técnica

Propósito

Produzir e revisar documentação técnica clara, acionável e de fácil manutenção, tanto para humanos quanto para agentes, incluindo arquivos de governança para contribuidores e arquivos de instrução para agentes.

Quando usar

• Criar ou reformular documentação em um produto/base de código existente (brownfield).
• Construir documentação perene, projetada para permanecer precisa e reutilizável ao longo do tempo.
• Revisar diffs de documentação quanto à estrutura, clareza e correção operacional.
• Realizar auditorias completas de documentação em todo o repositório, que devem incluir tanto arquivos de governança quanto superfícies de documentação do produto (docs/, README*, .md/.mdx/.mdc, fontes no estilo Fern/Sphinx/Mintlify).
• Atualizar ou revisar AGENTS.md e/ou CONTRIBUTING.md para manter os fluxos de trabalho do agente e do contribuidor alinhados com as práticas atuais do repositório.
• Melhorar a documentação de integração/onboarding do repositório, que inclui instruções de contribuição, templates de issues, fluxo de PR e portões de revisão.
• Projetar estratégia de documentação de governança para repositórios com arquivos de instrução de alias (por exemplo CLAUDE.md, AGENT.md, .cursorrules, .cursor/rules/*, .agent/, .agents/, .pi/) onde AGENTS.md é tratado como canônico quando presente e os aliases devem ser mantidos como superfícies de compatibilidade.
• Diagnosticar desvios em arquivos de agente quando equipes precisaram fazer perguntas iterativas para descobrir arquivos ausentes, comandos quebrados ou conflitos de política.
• Aplicar sobreposições de documentação específicas do repositório, incluindo tipo de página OpenClaw, arquitetura da informação (IA) de docs, preservação e regras de validação quando presentes.

Fluxo de trabalho

1. Classificar tarefa: build ou review; contexto: brownfield ou evergreen.
2. Fazer inventário do arquivo, diretório ou escopo de diff solicitado no início. Incluir governança e documentação do produto para trabalhos que envolvam documentação. O tamanho do repositório, por si só, não amplia uma revisão com escopo definido.
3. Detectar escopo multilíngue (README/documentação em vários idiomas) e definir o nível de paridade necessário.
4. Ler references/agent-and-contributing.md para instruções de agente e regras de fluxo de trabalho do CONTRIBUTING.md (inventário, mapeamento canônico/alias, equilíbrio de modo duplo, padrões de entrega e precedência/tratamento de conflitos).
5. Ler references/principles.md para o conjunto de regras vigentes (Matt Palmer e OpenAI).
6. Para trabalhos com docs do OpenClaw, ler references/openclaw.md antes do manual de construção/revisão.
7. Para tarefas de build, seguir references/build.md.
8. Para tarefas de review, seguir references/review.md e detectar problemas proativamente sem esperar por prompts repetidos.
9. Para tarefas complexas ou de alto risco (build ou review), é aceitável realizar investigações mais longas, profundas e exaustivas quando necessário para obter confiança.
10. Quando disponível, usar sub-agentes para trabalho paralelo delimitado de descoberta/revisão e depois mesclar as saídas em uma única entrega final coerente.
11. Usar references/tooling.md quando escolhas de plataforma/ferramentas afetarem as recomendações.
12. Executar varredura proativa de problemas dentro do escopo solicitado. Corrigir defeitos de alta confiança na mesma passada, a menos que o modo report-only seja solicitado.
13. No modo brownfield, priorizar compatibilidade com a arquitetura da informação (IA) atual dos docs, ferramentas e estado de lançamento.
14. No modo evergreen, priorizar redação atemporal, estratégia de atualização e estrutura durável.
15. Retornar entregáveis, além de notas de validação, status de paridade e lacunas restantes.

Orientações para orquestração de sub-agentes

Prefira sub-agentes quando o repositório for grande ou o conjunto de alterações solicitado for amplo; use-os por padrão para trabalhos em todo o repositório, com múltiplos frameworks ou de alto conflito.

• inventory-agent -> agents/inventory-agent.md (fast / Claude haiku): descoberta de arquivos/configuração, mapa de cobertura e verificações de caminhos ausentes.
• governance-agent -> agents/governance-agent.md (thinking / Claude sonnet): precedência AGENTS/CONTRIBUTING/alias, conflitos e desvios de política.
• docs-framework-agent -> agents/docs-framework-agent.md (thinking / Claude sonnet): configuração de framework, base de caminho relativo e verificações de mapeamento caminho-de-arquivo vs. caminho-de-URL.
• synthesis-agent -> agents/synthesis-agent.md (long / Claude opus): mesclar saídas dos sub-agentes em um único plano de correção priorizado e modelo de precedência unificado.

Entradas

• Tipo de documento (tutorial, instrução prática, referência, explicação) e público-alvo.
• Escopo de arquivo ou escopo de diff.
• Restrições de framework/ferramentas de docs (Fern, Mintlify, Sphinx, etc.).
• Modo de construção/revisão e intenção brownfield/evergreen.
• Intenção de compatibilidade alvo para agente e humano.
• Superfícies de framework de docs no escopo (por exemplo Fern, Sphinx, Mintlify, arquivos Markdown/MDX/MDC/RST/RSC).
• Profundidade de investigação/orçamento de tempo desejados (passagem rápida vs. revisão exaustiva).
• Modo de execução (single-agent ou sub-agent-assisted quando disponível).
• Modo de remediação (apply-fixes por padrão, ou report-only quando solicitado).
• Escopo multilíngue: idioma fonte da verdade, localidades alvo e expectativas de paridade.
• Restrições de sobreposição específicas do repositório, se houver.

Saídas

• Rascunho atualizado ou resultados de revisão com próximas ações claras.
• Notas de validação (o que foi verificado, o que resta).
• Recomendações de navegação/manutenção para qualidade de longo prazo.
• Resumo de alinhamento de documentos de governança quando AGENTS/CONTRIBUTING foram alterados.
• Mapa da superfície de instruções do agente (arquivo principal, arquivos alias, plano de tratamento Codex/Claude/Cursor).
• Mapa de cobertura da superfície de documentação (o que foi revisado em /docs, hierarquia README e árvores de origem específicas do framework).
• Lista de problemas autodetectados com correções aplicadas (ou achados explícitos no modo report-only).
• Notas de delegação quando sub-agentes foram usados (escopo delegado e como os achados foram mesclados).
• Nota de paridade multilíngue (sincronizado, parcial com justificativa, ou intencionalmente divergente).
• Notas de sobreposição específicas do repositório quando uma foi usada.