<omh-documentacao-specs-e-changes />
Documentação não é burocracia. É o contexto que a IA não tem.
O agente começa cada tarefa do zero. O que não estiver escrito, ele vai supor — e 66% dos desenvolvedores já conhecem o resultado: uma resposta quase certa.
// Onde você está no harness
Esta página explica as fontes
O que o modelo lê antes de escrever: o pedido, o CLAUDE.md, specs/ e changes/.
o prompt do operador
como se trabalha aqui
arc42 · C4 · BDD · ADR
PRD · design · specs · tasks
o código que já está lá
lint e formatação
tipos e contratos
os *.test.js do tester
o pre-commit
a mensagem do commit
os workflows do GitHub
o modelo — prevê o próximo token a partir da janela
tudo em volta decide o que entra na janela e o que sai dela
11 ofícios, cada um na sua janela
52 procedimentos
47 defeitos proibidos
khaby-lame.sh, antes do Write
/craft /ship /audit /sync /extend
ferramentas externas
o código — onde a saída vira arquivo, com o teste ao lado
Fontes
o que ela lê antes de escrever
Claude Code
o modelo — prevê o próximo token a partir da janela
Recursos · .claude/
configuram o modelo
src/[contexto]/[container]/[componente]/
onde a saída vira arquivo, com o teste ao lado
Validadores
o veredito volta para o modelo
66%
dos devs encontram respostas de IA “quase certas, mas não exatamente”. 45% dizem que depurá-las leva mais tempo.
Fonte: Stack Overflow 2025
+750%
de efeito da integração contínua em times com documentação de qualidade acima da média.
Fonte: DORA, Documentation quality
17,3h
por semana que cada desenvolvedor gasta com manutenção, dívida técnica e código ruim.
10–100x
mais caro corrigir um erro depois da entrega do que na especificação.
Fonte: Boehm, Software Engineering Economics, 1981
Documentação multiplica cada prática
Ganho de desempenho organizacional de cada capacidade técnica em times com documentação acima da média.
Trunk-based
+1525%
Integração contínua
+750%
Entrega contínua
+656%
Supply chain
+451%
SRE
+343%
Times desacoplados
+313%
Controle de versão
+278%
Fonte: DORA, Documentation quality
A semana de um desenvolvedor
Das 40 horas, quanto vai para manutenção, dívida técnica e código ruim.
Quase metade da semana vai para entender e consertar o que não estava escrito. É esse tempo que specs/ e changes/ devolvem.
// specs/
O sistema como ele é hoje
Quatro práticas consolidadas, cada uma respondendo a uma pergunta diferente. É o que o agente lê no research, antes de propor qualquer coisa.
Como é estruturado?
12 capítulos de arquitetura: contexto, restrições, blocos, runtime, qualidade.
Como visualizar?
Contexto, container e componente — os mesmos níveis que organizam src/.
Como se comporta?
Cenários em Gherkin, que viram o critério de aceite do tester.
Por que decidimos assim?
Decisões com as alternativas descartadas. O único formato que guarda o não.
// changes/
O que vai mudar, escrito antes do código
Cada mudança ganha uma pasta com quatro documentos. Eles levam o pedido de negócio até tarefas que a IA executa sem ambiguidade. Quando a mudança fecha, o que ela tornou verdade volta para specs/.
o quê
arquitetura
detalhe
ordem
| Documento | Responde |
|---|---|
| PRD.md | O quê e por quê: problema, objetivos, metas |
| design.md | Como, na arquitetura: contexto, container, ADRs |
| specs.md | Como, em detalhe: contratos, tipos, cenários |
| tasks.md | Em que ordem: tarefas atômicas, com caminho em src/ |
changes/
└── 001-cupom-de-frete/
├── PRD.md o cliente quer frete grátis
│ acima de R$ 199
├── design.md compra/checkout/cupons
│ ADR-014: regra no servidor
├── specs.md aplicarCupom(pedido, codigo)
│ cupons.feature: 4 cenários
└── tasks.md T1 · tipo Cupom
T2 · aplicar-cupom + teste
T3 · CampoDeCupom
T4 · evento de analytics
// Quatro pastas, um sistema
specs/, changes/, src/ e .claude/ trabalham juntas
Uma não faz sentido sem as outras. specs/ alimenta changes/, changes/ roteiriza src/, e o que src/ entrega volta para specs/. .claude/ conduz esse ciclo sem que o operador precise lembrar dele.
O sistema como é
Lido no research, antes de planejar qualquer coisa
Escrito no fechamento, com o que a mudança tornou verdade
O que vai mudar
Lido no implement, tarefa a tarefa
Escrito no plan: PRD, design, specs e tasks
O código que muda
Lido no verify, pelo reviewer e pelo tester
Escrito no implement, seguindo tasks.md
Quem conduz o ciclo. O CLAUDE.md anuncia o tempo, o /craft escolhe os ofícios, os agents leem specs/, escrevem changes/, implementam src/ e devolvem para specs/ — com as rules valendo em tudo e as skills ensinando o como.
| Tempo | Lê | Escreve |
|---|---|---|
| Research | specs/ e src/ | Evidência com arquivo:linha |
| Plan | specs/ | changes/NNN-feature/ — PRD, design, specs, tasks |
| Implement | changes/NNN-feature/tasks.md | src/, com o teste ao lado |
| Verify | src/ e changes/NNN-feature/ | specs/ atualizado: arc42, c4, bdd, adr |
// A objeção honesta
E se as specs ficarem longas demais?
É a crítica que a Thoughtworks faz ao spec-driven development: arquivos longos, difíceis de revisar, e regras escritas à mão que não escalam. A resposta do ecossistema está na forma, não no volume.
Uma pasta por mudança
Nunca um documento gigante do sistema inteiro para revisar.
Tarefas atômicas
tasks.md quebra o trabalho em unidades pequenas e verificáveis.
O ritmo encolhe
Um typo não tem PRD. A maioria dos pedidos usa dois tempos.
Regras que se curam
Quando você corrige uma entrega, o curator ajusta .claude/.
Documentação precisa de um código que a acompanhe
Veja como src/ espelha o C4 e deixa cada capacidade inteira numa pasta.