<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/.

Validadores
o que confere a saída
Fontes
o que ela lê antes de escrever
Claude Code
o modelo e o que o configura
pedido
o prompt do operador
CLAUDE.md
como se trabalha aqui
specs/
arc42 · C4 · BDD · ADR
changes/
PRD · design · specs · tasks
src/ existente
o código que já está lá
Biome
lint e formatação
check
tipos e contratos
bun test
os *.test.js do tester
husky + lint-staged
o pre-commit
commitlint
a mensagem do commit
CI
os workflows do GitHub
Claude Code
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
Recursos do Claude Code · em .claude/
agents
11 ofícios, cada um na sua janela
skills
52 procedimentos
rules
47 defeitos proibidos
hooks
khaby-lame.sh, antes do Write
commands
/craft /ship /audit /sync /extend
MCPs
ferramentas externas
src/[contexto]/[container]/[componente]/
o código — onde a saída vira arquivo, com o teste ao lado
lê
veredito
escreve
configuram
confere

Fontes

o que ela lê antes de escrever

pedidoCLAUDE.mdspecs/changes/src/ existente
↓ lê

Claude Code

o modelo — prevê o próximo token a partir da janela

Recursos · .claude/

configuram o modelo

agents · 11skills · 52rules · 47hookscommands · 5MCPs
↓ escreve

src/[contexto]/[container]/[componente]/

onde a saída vira arquivo, com o teste ao lado

↓ confere

Validadores

o veredito volta para o modelo

Biomecheckbun testhusky + lint-stagedcommitlintCI

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.

Fonte: Stripe, The Developer Coefficient

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.

17,3h
22,7h
manutenção e dívida técnica · ~43%o resto da semana

Quase metade da semana vai para entender e consertar o que não estava escrito. É esse tempo que specs/ e changes/ devolvem.

Fonte: Stripe, The Developer Coefficient

// 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.

specs/arc42/

Como é estruturado?

12 capítulos de arquitetura: contexto, restrições, blocos, runtime, qualidade.

specs/c4/

Como visualizar?

Contexto, container e componente — os mesmos níveis que organizam src/.

specs/bdd/

Como se comporta?

Cenários em Gherkin, que viram o critério de aceite do tester.

specs/adr/

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/.

PRD.md
o quê
design.md
arquitetura
specs.md
detalhe
tasks.md
ordem
DocumentoResponde
PRD.mdO quê e por quê: problema, objetivos, metas
design.mdComo, na arquitetura: contexto, container, ADRs
specs.mdComo, em detalhe: contratos, tipos, cenários
tasks.mdEm 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.

specs/
O sistema como é
Lido no research, antes de planejar qualquer coisa
Escrito no fechamento, com o que a mudança tornou verdade
changes/
O que vai mudar
Lido no implement, tarefa a tarefa
Escrito no plan: PRD, design, specs e tasks
src/
O código que muda
Lido no verify, pelo reviewer e pelo tester
Escrito no implement, seguindo tasks.md
plan
implement
verify · de volta a specs/ — a pasta da mudança fica como histórico
.claude/

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.

TempoLêEscreve
Researchspecs/ e src/Evidência com arquivo:linha
Planspecs/changes/NNN-feature/ — PRD, design, specs, tasks
Implementchanges/NNN-feature/tasks.mdsrc/, com o teste ao lado
Verifysrc/ 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.

Fonte: Thoughtworks Technology Radar, nov/2025

01

Uma pasta por mudança

Nunca um documento gigante do sistema inteiro para revisar.

02

Tarefas atômicas

tasks.md quebra o trabalho em unidades pequenas e verificáveis.

03

O ritmo encolhe

Um typo não tem PRD. A maioria dos pedidos usa dois tempos.

04

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.

Ver src/