Template de onboarding para novos projetos. Não traz stack nem framework — traz um método de trabalho que alterna dois modos do mesmo agente, raciocínio (plan) e execução (code), com docs vivos servindo de memória compartilhada entre os modos e entre sessões.
É agnóstico de ferramenta. O núcleo funciona com qualquer agente de código (Claude Code, Cursor, Copilot, Codex, etc.) via AGENTS.md. Flavors finos por ferramenta em CLAUDE.md (Claude Code) e .cursor/rules/metodo.mdc (Cursor).
Uma superfície, dois modos — os dois no agente, os dois com o repo na mão:
- Plan mode (raciocínio): lê os docs vivos e audita o código real, discute, decide, e grava a spec da fase. Não coda. Nomes de arquivo/símbolo nascem verificados, não hipóteses. Uma fase só, com nada em execução: a spec fica no
SETUP.md, como sempre. Várias fases que não se tocam: uma spec e um worktree cada (docs/reference/integracao.md). - Code mode (execução): em sessão nova (contexto limpo), lê a spec, implementa aterrado, e atualiza os docs vivos numa passada. Ao fechar, uma revisão de contexto fresco (subagente que só vê docs vivos + diff) confere entregue-vs-spec antes do commit. O merge é
scripts/integrar-fase.sh: uma fase por vez, conflito de lógica para.
A fronteira entre planejar e executar — com o contexto limpo no meio — impede o agente de arrastar o raciocínio pra dentro da execução e entupir a janela, e mantém cada fase como tarefa independente. O handoff entre os modos, e a continuidade entre sessões, acontece pelos docs vivos.
Doc vivo responde onde estamos / pra onde vamos / o que está aberto, no menor número de palavras. Todo o resto — como chegamos aqui — vai pra histórico ou fica atrás de um ponteiro. Cada doc vivo fica curto por um de dois mecanismos:
- expulsa conteúdo quando ele fecha (SETUP, DEBITO-TECNICO), ou é um ledger: 1 linha por evento, com o detalhe pesado offloaded em outro arquivo (CHANGELOG → SETUP-HISTORICO; DECISOES → docs/adr).
Resumir só é seguro com ponteiro: cada linha resumida referencia onde está o detalhe. Resumo sem ponteiro é perda; resumo com ponteiro é compressão.
O "como/por quê" de uma fase tem quatro destinos por tipo: decisão de arquitetura → ADR (só o que passa no teste "ADR ou regra?" do AGENTS.md); regra de comportamento → R-NNN em docs/reference/; narrativa de implementação (desvios, soluções não-óbvias) → bloco "Notas de implementação" no arquivo da fase em docs/history/fases/; o diff literal → git. As regras mecânicas de migração (quando mover o quê pra onde) estão em AGENTS.md.
AGENTS.md instruções do agente (núcleo agnóstico) — use como está
CLAUDE.md flavor Claude Code (mecânica do loop) → aponta pro AGENTS.md
.cursor/rules/metodo.mdc flavor Cursor (mesma mecânica) → aponta pro AGENTS.md
CONVENCOES.md padrões de código/UI DESTE projeto (preencha; estável)
CONTEXT.md linguagem ubíqua: 1 termo por conceito (preencha; cresce sozinho)
.claude/ mecânica executável do loop (Claude Code)
├─ skills/ rituais: planejar-fase, fechar-fase, integrar-fase, verificar-referencia, grilling
├─ agents/ varredura.md — varre o código em modelo leve e devolve só arquivo:linha
│ revisor-fecho.md — a revisão de fecho de contexto fresco, com o checklist da casa
├─ hooks/ block-dangerous-git.sh — git destrutivo e commit no main viram erro (+ .test.sh)
│ block-comandos-do-dono.sh — git add cego (+ exemplos comentados)
└─ settings.json registra os hooks como PreToolUse/Bash e as permissões dos scripts do método
scripts/ abrir, listar e integrar fases; o fecho comum (fechar-pr, conferir-fecho); o aviso do canal
(canal-avisar, canal-esperar, disparar-trilha) e o deploy segurado, opcionais; a validação é scripts/validar.sh (bash 3.2)
docs/ ← só arquivos VIVOS na raiz (estado atual)
├─ ROADMAP.md fases futuras + a atual; 1 linha por fase
├─ CHANGELOG.md 1 linha por fase entregue (ledger, append-only)
├─ DECISOES.md índice de ADRs; 1 linha por decisão (ledger)
├─ DEBITO-TECNICO.md só débito ABERTO
├─ SETUP.md spec da fase solitária neste checkout — exatamente uma
├─ fases-ativas/ registro por fase paralela, na branch dela; no main só o LEIA.md
├─ changes/ fragmento dos ledgers por fase paralela; no main só o LEIA.md
├─ adr/ referência: texto cheio dos ADRs (imutável por entrada)
│ ├─ TEMPLATE.md modelo de ADR
│ └─ ADR-000.md convenção de numeração
├─ history/ arquivado (imutável)
│ ├─ SETUP-HISTORICO.md índice: 1 linha por fase concluída
│ ├─ fases/F-xxx.md spec concluída + notas de implementação, um arquivo por fase
│ └─ DEBITO-RESOLVIDO.md débito fechado, com nota de resolução
├─ reference/ (sob demanda) referência durável: how-to, deploy, prompts…
│ ├─ referencias.md repos externos vigiados + o SHA até onde já revisamos
│ ├─ canal.md contrato v1 do canal de bots (add-on opcional)
│ └─ integracao.md fases paralelas: registro, fragmento, fila, trava (R-001…R-006)
└─ scratch/ (ignorado no git) investigações/spikes efêmeros
templates/ scaffolding reutilizável
├─ spec-fase.md formato de uma spec de fase (lido pelo plan mode)
├─ fase-ativa.md modelo do registro (paralela)
├─ fragmento-fase.md modelo do fragmento de ledgers (paralela)
└─ canal/ modelos do canal de bots (add-on; copiar para fora do git)
examples/ PREENCHIDO — leia pra ver o método rodando
├─ docs/ espelho de docs/ com o projeto-brinquedo "Recados"
├─ CONVENCOES.md exemplo de convenções (stack TypeScript)
├─ CONTEXT.md exemplo de linguagem ubíqua (projeto "Recados")
└─ perfil-llm-agente.md add-on opcional pra projetos de LLM/agentes (ver abaixo)
Os arquivos em docs/ e o CONVENCOES.md vêm vazios (só estrutura + comentário).
Os de examples/ vêm preenchidos com um projeto-brinquedo coerente ("Recados", uma API de notas) pra você ver como cada doc fica em uso e como as migrações acontecem.
docs/raiz = só docs vivos. Os 5 vivos são um conjunto fixo.fases-ativas/echanges/não são vivos: nomainsó têm oLEIA.md. Doc auxiliar roteia por balde (decisão→ADR, convenção→CONVENCOES, referência durável→docs/reference/, investigação efêmera→docs/scratch/). Regra e tabela completa emAGENTS.md.
- Use este repo como template no GitHub (botão Use this template) ou clone e
rm -rf .git && git init. - Leia
examples/uma vez pra entender o método em uso. - Configure o agente: o
AGENTS.mdé o núcleo — use como está, ajuste só a seção de stack/comandos. A mecânica por ferramenta já vem pronta:CLAUDE.md(Claude Code) e.cursor/rules/metodo.mdc(Cursor). - Preencha o
CONVENCOES.mdcom os padrões de código/UI do seu projeto (useexamples/CONVENCOES.mdcomo molde). Sem convenções fortes ainda? Deixe mínimo e cresça depois. - Defina o ROADMAP: preencha
docs/ROADMAP.mdcom as fases de um MVP enxuto, 1 linha cada. - Rode o loop: plan mode audita o código e grava a spec da fase em
docs/SETUP.md→ você aprova e escolhe como executar (aqui sem limpar, agente gerenciado ou à mão com/clearno Claude Code / New Chat no Cursor) → code mode executa, roda a revisão de fecho e atualiza os vivos → você aprova a fase → repete. No Claude Code, os rituais já vêm como skills:/planejar-fasee/fechar-fase. Se o planejamento cortar fases que não se tocam, cada uma ganha worktree e a integração entra uma por vez (/integrar-fase). Uma fase só, com nada no ar, não muda esse passo. - (Opcional) apague
examples/quando não precisar mais da referência.
O loop é um lugar só: você alterna plan e code com o mesmo agente (Claude Code ou Cursor). Abaixo, uma sequência real de arranque (ajuste os ‹trechos›).
1) Plan mode — definir o ROADMAP e a primeira spec. Não há docs vivos ainda; você começa descrevendo o projeto:
Estou começando um projeto novo. Projeto: ‹uma API self-hosted pra gerenciar meus links salvos›. Stack: ‹Bun + Hono + SQLite›.
Entre em plan mode: primeiro me proponha as fases de um MVP enxuto (YAGNI), uma linha cada, pro ROADMAP. Quando eu aprovar, audite o repo e grave a spec só da primeira fase em docs/SETUP.md.
2) Execute. Aprovada a spec, escolha no menu do planejamento (executar aqui, agente gerenciado ou fazer nada). Fazendo à mão, dê /clear (Claude Code) ou abra um New Chat (Cursor), e rode:
Leia e execute a fase atual do docs/SETUP.md, seguindo o AGENTS.md.
O agente implementa, roda a revisão de fecho (subagente de contexto fresco) e atualiza os docs vivos, parando pra você aprovar a fase.
Daí em diante, cada fase é esse par curto — o contexto está nos docs, não no prompt:
planeja a próxima fase → aprovo e escolho no menu (ou /clear) → executa a fase do SETUP
O que é. Um perfil de princípios extras pra quem constrói software com LLM — orquestração de agentes, integração com modelos, custo de inferência. Fica em examples/perfil-llm-agente.md.
Por que está separado do núcleo. O AGENTS.md é agnóstico de domínio: não assume que você usa IA. Regras como "toda chamada de LLM grava tokens e custo" são valiosas num projeto de IA e puro ruído num site estático ou numa CLI. Por isso o perfil é opt-in, não default.
Atenção — este é o único arquivo de examples/ feito pra copiar e manter. O resto de examples/ é referência pra ler e (se quiser) apagar. Este você tira de lá e incorpora ao seu repo. Pra acoplar:
- Copie
examples/perfil-llm-agente.mdpra raiz do seu repo, com um nome próprio — ex.:PERFIL-LLM.md. - Abra seu
AGENTS.mde adicione uma linha apontando pra ele, na lista do topo: "Projeto de LLM/agentes — veja tambémPERFIL-LLM.md." (já há um lembrete lá). O plan mode lê o arquivo direto do repo quando a fase discute arquitetura de agente.
O que tem dentro (pra você julgar se precisa):
- Cost-aware — toda chamada de LLM captura tokens in/out e custo; estimativa por execução nos comentários.
- Human-in-the-loop por padrão — ação que gasta dinheiro ou mexe em recurso externo (email, post) pede aprovação por default.
- Config-as-Code — config de agente/tool persistida tem representação serializável; delete faz export antes.
- Composability — sem hardcode de prompt/modelo/tool; use registries; tool genérica > one-off.
- Observability built-in — cada chamada passa por uma camada de observability; cada execução grava input/output/tokens/custo/modelo/duração.
- Eval antes de promover — mudou system prompt em produção? roda eval de regressão (ou ao menos 3–5 inputs conhecidos) antes de marcar como ativo.
- Custo em dois eixos — separe custo cobrado por API de custo coberto por assinatura; conflar os dois engana.
As instruções de acoplamento também estão no topo do próprio arquivo, pra quem abrir ele direto sem passar pelo README.
O que é. Um contrato para o agente de código consultar bots (ou um humano no lugar deles) durante o planejamento, a codificação ou uma dúvida. Sem bot declarado, o loop não muda.
Onde está. A regra curta é AGENTS.md §Bots. O contrato v1 é docs/reference/canal.md. A issue de trabalho é .github/ISSUE_TEMPLATE/trabalho.md (a seção ## Bots é a que a spec herda). Os modelos para copiar para ~/.canal/<projeto>/ estão em templates/canal/. A decisão é a ADR-001. Fase paralela usa a mesma pasta por id de fase (R-006).
Como o time abre a issue. Template Trabalho: objetivo, contexto, critério de pronto e uma linha por bot (slug, modos, para quê). Nenhum bot na seção = execução só code. Etiqueta bot:<slug> é opcional e só serve para filtrar.
O template traz as skills do loop (planejar, fechar, integrar, vigiar a referência, grilling) e para aí de propósito: ele é um método, não uma caixa de ferramentas. Pro trabalho de engenharia dentro de uma fase — escrever teste antes, caçar bug, revisar código, prototipar, pesquisar — vale instalar uma biblioteca pronta em vez de escrever a sua.
A recomendação é o plugin mattpocock-skills (mattpocock/skills), de onde parte do método daqui já foi portada:
claude plugins install mattpocock-skillsVale por tdd, diagnosing-bugs, code-review, prototype e research — todas encaixam dentro de uma fase, no code mode, sem competir com o loop. É opcional e não é dependência: nada aqui deixa de funcionar sem ele, e o método não referencia nenhuma skill dele. O repo fica registrado em docs/reference/referencias.md e é revisitado pela skill /verificar-referencia.
O template nasce single-repo de propósito (YAGNI). Se um dia o projeto virar vários repos que publicam e consomem entre si, duas coisas entram em cena — e só então:
publica → consome: mudança de contrato vai do produtor pro consumidor em sequência, nunca em paralelo (paralelo recria drift). O consumidor compila contra o artefato publicado, não contra um link em disco.- Namespace de ADR por repo: cada repo ganha um prefixo próprio (
SDK-ADR-NNN,APP-ADR-NNN) pra não colidir numeração. Referência cruzada sempre com prefixo completo. Vejadocs/adr/ADR-000.md.
Não monte isso antes de ter o segundo repo de verdade.