Quem escreve, quem revisa
A IA não é um agente só. São cinco, com permissões diferentes de propósito — e é a diferença de permissão, não a boa vontade do modelo, que faz a revisão valer alguma coisa.
Os cinco papéis
| Agente | Escreve? | O que ele faz |
|---|---|---|
| implementador | sim | Faz uma tarefa do plano, com TDD, começando com o contexto limpo. É o único que toca em arquivo de código. |
| revisor-conformidade | não | Compara o diff da tarefa contra os critérios de aceite da spec. Roda os testes para saber se o critério é atendido de verdade. |
| revisor-codigo | não | Lê o mesmo diff contra o architecture.md: componentes, services,
rotas, estado e os nomes do glossário. |
| auditor-final | não | No fim da história, compara o diff inteiro da branch contra a spec aprovada, ignorando o plano. |
| tutor | não | Explica. Os documentos da Fase 0, o scaffold, o que a tarefa vai construir e o que o diff fez. Não corrige e não opina sobre qualidade. |
Quem chama o revisor é o fluxo, não o implementador. Nenhum agente decide que o próprio trabalho dispensa revisão.
A trava
O revisor não pode ter permissão de escrita. Não porque ele foi instruído a não escrever, mas porque a ferramenta não deixa.
Pedir “por favor, não corrija, apenas aponte” no prompt é uma sugestão. O modelo vai obedecer na maioria das vezes e, na vez em que não obedecer, você não vai saber: o apontamento que ele consertou sozinho nunca chega até você, e é justamente esse que você precisava ver.
Por isso o revisor é somente leitura, e o parecer dele é gravado sem edição em
specs/<issue>-<slug>/reviews/. É esse arquivo que prova, na
apresentação, que a revisão aconteceu — e é a listagem dele que conta as rodadas.
Cuidado com o terminal. Um agente somente leitura que tem acesso ao
shell consegue escrever com sed -i, com > ou com
git checkout, e a trava vira ficção. Só que os revisores precisam do terminal
para rodar git diff e a suíte de testes. Há duas saídas, nesta ordem de
preferência:
1. Se a sua ferramenta permite lista de comandos liberados, libere só
git diff e o comando de teste. É a trava de verdade.
2. Se ela só liga ou desliga o terminal inteiro, escreva a proibição no prompt do
agente: o terminal existe para git diff e para rodar os testes, e é proibido
usá-lo para alterar qualquer arquivo.
As três coisas que a ferramenta precisa saber fazer
O método é mais importante que a ferramenta. Ferramenta de IA envelhece rápido; o que você leva da disciplina é o método. Se a sua ferramenta faz estas três coisas, o ciclo roda.
Regras sempre ativas
Um arquivo carregado em toda mensagem, com as regras inegociáveis do projeto: não
codificar antes da spec aprovada, TDD obrigatório, main e develop
bloqueadas, os nomes vêm do glossário. Sem isso você repete as mesmas instruções todo dia
e o agente esquece na terceira mensagem.
Um comando de fluxo
Um arquivo de instruções que você dispara com uma linha e que executa o passo inteiro:
despacha o tutor, o implementador e os dois revisores, grava os pareceres, conta a rodada,
decide. Você digita /utf-task 3; a orquestração inteira é o arquivo.
Subagentes com ferramentas restritas
É aqui que mora a parte que não pode faltar. Quase toda ferramenta moderna deixa você declarar quais ferramentas cada subagente recebe. É essa declaração que carrega a trava, e é a única coisa que não dá para compartilhar entre ferramentas.
Um método, quatro ferramentas
O template já vem configurado para quatro ferramentas. O conteúdo de verdade vive uma vez
só, em .agents/; cada ferramenta tem apenas uma casca de poucas linhas que
aponta para lá, com a sintaxe de permissão dela. Trocar de ferramenta no meio do semestre
não reescreve nada.
| Ferramenta | Regras | Comandos | Subagentes |
|---|---|---|---|
| Claude Code | CLAUDE.md | .claude/commands/ | .claude/agents/ |
| Cursor | .cursor/rules/ | .cursor/commands/ | .cursor/agents/ |
| Antigravity | .agents/rules/ | .agents/workflows/ | .agents/agents/ |
| OpenCode | AGENTS.md | .opencode/command/ | .opencode/agents/ |
Nas quatro, os revisores e o tutor nascem sem poder de escrita. A força da trava é que muda:
- Claude Code, Cursor e Antigravity negam a ferramenta de edição, mas
precisam liberar o terminal para o revisor rodar
git diff. Quem fecha a brecha ali é a proibição escrita no prompt do agente. - OpenCode fecha por configuração. É o único que libera comandos específicos em vez de ligar ou desligar o terminal inteiro. E funciona com modelos gratuitos, o que faz dele o caminho de custo zero mais completo da disciplina.
Se você usa OpenCode, ajuste a lista de comandos de teste em
.opencode/agents/ à stack do seu architecture.md. Comando que não
estiver liberado não roda, e o parecer sai incompleto sem avisar.
E se o seu OpenCode não listar os agentes ou os comandos, é diferença de versão nos
nomes das pastas: renomeie .opencode/agents/ para
.opencode/agent/ e .opencode/command/ para
.opencode/commands/. O conteúdo é o mesmo.
Sem worktree, sem ambiente isolado
Você trabalha na branch da Issue, na sua IDE, com os arquivos à vista. Worktrees e sandboxes existem para vários agentes que escrevem rodarem em paralelo sem pisar uns nos outros. Aqui há um escritor por vez e dois revisores que não escrevem: não existe colisão possível. E ver o arquivo aparecer no explorador, o teste ficar vermelho e depois verde, é parte do que você está aqui para aprender.