code-ai-template AGENTS.md

AGENTS.md

Instruções para o agente de código deste projeto. Núcleo agnóstico de ferramenta — vale em qualquer stack e qualquer agente. Use como está.

• Mecânica por ferramenta: CLAUDE.md (Claude Code), .cursor/rules/metodo.mdc (Cursor).
• Convenções de código/UI deste projeto: CONVENCOES.md. Linguagem ubíqua do domínio: CONTEXT.md.
• Projeto de LLM/agentes: acople o add-on opcional e referencie aqui (ex.: PERFIL-LLM.md). Instruções no README.

O loop — plan e code

Uma superfície, dois modos — os dois são você, os dois com o repo na mão:

• Plan mode (raciocínio): lê os docs vivos e audita o código real, discute o aberto com o dono (uma pergunta por vez), e grava a spec da fase no docs/SETUP.md — e para aí. Ler código é o trabalho desta passada; escrever código é da outra.
• Code mode (execução): em sessão nova (contexto limpo), lê a spec do SETUP.md, implementa aterrado no código, roda os critérios de sucesso na mesma resposta, e atualiza os docs vivos numa única passada antes de encerrar.

Entre os dois, uma fronteira dura: é o dono que limpa o contexto e abre a execução. Cada fase é tarefa independente — o contexto mora nos docs vivos, não na sessão.

Como o planejador tem o repo, a spec nasce confirmada contra o código: nomes de arquivo e símbolo são verificados no plan mode, não "hipóteses a confirmar". Ainda assim a verdade é o código — se em code mode a realidade diverge da spec, implemente o que é correto e registre a divergência (nota na fase, ou ADR se for decisão de arquitetura).

• Audite o estado antes de modelar. Fase que mexe em schema, enum ou estado persistido: no plan mode, audite o código real (migrations, tipos, dados) antes de escrever a spec. Barato, e evita spec que presume estado que não existe.
• Uma fase de cada vez. docs/SETUP.md tem uma spec, e as fases entram na ordem do ROADMAP. Implemente, atualize os vivos, pare, resuma ao dono e peça aprovação pra próxima.
• Fique no modo até a fase fechar. Se, em code mode, a conversa puxa pra fora do escopo da spec atual (nova ideia, decisão de arquitetura, refatoração não pedida), pare e pergunte ao dono: seguir no code, dentro do escopo, ou voltar pro plan pra tratar aquilo como fase própria? É o mesmo princípio de "sem refatoração de carona", aplicado à troca de modo.
• Revisão de fecho com contexto fresco. Ao fechar a fase em code mode — depois de rodar os critérios, antes do commit — dispare um subagente sem o contexto da sessão, que recebe só os docs vivos + o diff e confere se o entregue bate com a intenção da spec. Limpo → passada única de docs + commit. Divergiu → corrija antes. Fase que não toca código pode pular.
• O plano durável é a spec. A spec no docs/SETUP.md é o plano canônico (o porquê arquitetural distila em ADR; a narrativa de implementação, ao fechar, no SETUP-HISTORICO). O arquivo de plano nativo da ferramenta (Claude Code ~/.claude/plans, Cursor) é rascunho efêmero — fica fora do git.