Cada arquivo tem uma responsabilidade.
Os nomes formam um contrato de navegação para pessoas e assistentes. O conteúdo deve representar o seu projeto.
Referência dos documentos e ferramentas
| Arquivo | Responsabilidade | Quando ler ou executar |
|---|---|---|
| PATHS.toml | Mapa de caminhos, módulos, fontes oficiais e checks. | Primeiro arquivo da leitura. |
| AGENTS.md | Regras permanentes de execução para assistentes e colaboradores. | Ao iniciar trabalho e antes de ações de risco. |
| PRD.md | Requisitos do produto, estado real e lacunas. | Ao delimitar e revisar uma entrega. |
| ESCOPO.md | Produto, fronteiras, módulos e nomenclatura. | Antes de mudar arquitetura ou responsabilidades. |
| QUALITY_ROADMAP.md | Fluxo de trabalho, SOLID, leitura por tarefa e definição de pronto. | Durante planejamento, execução e revisão. |
| GOVERNANCA.md | Riscos, prioridades, dependências e gates de release. | Em decisões de risco e publicação. |
| DEMANDAS.md | Backlog executável em pacotes e lotes. | Ao escolher, concluir ou bloquear trabalho. |
| TELAS.md | Rotas, telas, estados e separação de CRUD. | Em mudanças de experiência e navegação. |
| TESTES.md | Validação por risco, fixtures, cobertura e retestes. | Antes e depois de implementar. |
| BUGS.md | Reprodução, diagnóstico, correção e reteste. | Ao investigar e fechar defeitos. |
| DECISOES.md | Decisões relevantes, motivo, impacto e rollback. | Quando uma escolha muda arquitetura ou operação. |
| RUNBOOK.md | Setup, operação, diagnóstico, deploy, smoke e recuperação. | Para reproduzir procedimentos operacionais. |
| docs/prd-classifications.json | Classificações revisadas e evidências por item. | Após inventariar e durante reconciliação. |
| docs/PRD_RASTREABILIDADE.md | Matriz gerada de requisitos, módulos e evidências. | Para revisar cobertura e lacunas do snapshot. |
| check.sh | Orquestra validações do modelo e checks configurados. | Conforme risco e no fechamento aplicável. |
| scripts/prd_inventory.py | Descobre itens, reconcilia classificações e gera a matriz. | No bootstrap, atualização e verificação do PRD. |
Como resolver uma divergência
Use PATHS para caminhos e checks; QUALITY_ROADMAP para fluxo de trabalho e fronteiras; GOVERNANCA para riscos e operação; backlog para o trabalho executável. PRD e documentos temáticos conectam intenção e implementação. Confirme a precedência registrada no projeto consumidor.
Se o documento diz pronto e o fluxo real não funciona, registre a divergência. Não altere a classificação apenas para ocultar a falha. Preserve a distinção entre evidência local, ambiente remoto e aceite humano.
Tradução sem perder os vínculos
O kit original mantém nomes de arquivos em português. Você pode traduzir o conteúdo para seu idioma e preservar os nomes para manter referências e validadores consistentes. Se renomear arquivos, atualize PATHS, links, scripts e documentação juntos.
O que a rastreabilidade conecta
- Requisito → módulo → tela ou rota → contrato → dados → teste.
- Decisão → motivo → implementação afetada → risco → caminho de retorno.
- Bug → reprodução → causa confirmada → correção → reteste.