/clear ao terminar cada etapa. Por quê? Porque Claude Code mantém contexto entre prompts. Se você NÃO limpar, informações de research vazam para change, de change vazam para code, e você perde a separação de responsabilidades.
specs/ tem toda a arquitetura documentada: componentes, decisões técnicas, diagramas, e features em linguagem natural (BDD). Você nunca começa do zero.
changes/ com 4 documentos: PRD (o problema), design (como resolver), specs (detalhamento técnico), e tasks (decomposição atômica). IAs usam isso como contexto perfeito.
src/ seguindo 51 regras arquiteturais + 18 skills de código. A estrutura é sempre context/container/component (baseada no C4). Zero ambiguidade sobre onde colocar as coisas.
specs/ com o que foi feito. Novo componente? Adiciona no arc42. Nova integração? Atualiza C4. Nova regra de negócio? Adiciona cenário BDD. Documentação sempre sincronizada.
specs/ não é Wiki separada. Não é Notion esquecido. É pasta no seu repo, versionada junto com código. Código muda? Specs muda. Sempre sincronizado. Sempre verdadeiro. Impossível ficar obsoleto.
specs/
├── arc42/ # 12 capítulos
│ ├── 01-introduction.md
│ ├── 02-constraints.md
│ ├── 03-context.md
│ ├── 04-solution-strategy.md
│ ├── 05-building-blocks.md
│ └── ...
│
├── c4/ # diagramas
│ ├── context-diagram.md
│ ├── container-diagram.md
│ └── component-diagrams/
│
├── bdd/ # specs executáveis
│ ├── authentication.feature
│ └── orders.feature
│
└── adr/ # decisões
├── 0001-database-choice.md
└── 0002-auth-strategy.md
changes/. Escreva 4 docs antes de codar. Parece burocracia? É investimento. 30 minutos documentando = 85% menos retrabalho = semanas economizadas refazendo código errado.
changes/
├── 001-user-authentication/
│ ├── PRD.md # product requirements
│ ├── design.md # arquitetura
│ ├── specs.md # especificação
│ └── tasks.md # decomposição
│
├── 002-shopping-cart/
│ ├── PRD.md
│ ├── design.md
│ ├── specs.md
│ └── tasks.md
│
└── template/
├── PRD-template.md
├── design-template.md
├── specs-template.md
└── tasks-template.md
specs/ = docs, changes/ = features, src/ = código (context/container/component do C4). Qualquer dev sabe onde procurar. Qualquer IA sabe onde criar.
.claude/ configura Claude Code com 51 regras + 18 skills + 1 agent reviewer + 2 comandos + 1 hook automático. Instale uma vez. Esqueça. Bugs detectados antes do commit, não em produção.
/reviewer. Um agent analisa seu código em 2 camadas e dá um veredito: aprovado, atenção, ou rejeitado. É como ter um arquiteto sênior revisando cada PR.
changes/NNN-feature/ com os 4 documentos (PRD, design, specs, tasks). Não escreva código ainda. Esta etapa define o que construir, como construir, e por que construir.
/clear após terminartasks.md e implemente tarefa por tarefa. Cada tarefa tem ≤ 5 linhas de contexto e zero ambiguidade. IAs executam isso com 0.9% de erro. Não invente, não improvise, siga o script.
lint.sh roda bunx biome check --write. Você não precisa fazer nada. O código é formatado automaticamente segundo as convenções.
/ship. O command faz tudo: git status, git diff, gera mensagem no padrão Conventional Commits (feat/fix/refactor), adiciona arquivos, comita, e faz push. Zero esforço manual.
/sync faz fetch, pull da main, e merge na sua branch. Evita conflitos surpresa na hora do PR.
specs/. Novo componente → arc42. Nova integração → C4. Nova regra → BDD. Documentação sempre sincronizada com o código.