Deixo os agentes de IA planejarem, escreverem, testarem e revisarem código. O que não entrego são as aprovações e tudo o que sai com meu nome. E quero ver cada decisão que um agente toma por mim. Essa divisão está escrita em regras. O meu ai-dotfiles instala essas regras no Claude Code, no Copilot e no Cursor, e os agentes as carregam antes de editar qualquer coisa.
Nada é construído antes de existir um plano
A primeira regra é planejar primeiro e construir depois. Construir inclui escrever código de produto, montar a estrutura do projeto, instalar dependências, criar um projeto e acionar uma skill de implementação. Ler e explorar não contam, então o agente pode investigar à vontade antes de ter um plano.
Quando falo em spec, falo desse plano escrito: o que vai ser construído, as restrições que ele precisa respeitar e como cada parte vai ser conferida. Numa mudança pequena, cabe numa mensagem do chat. Neste site, é um arquivo no repositório, e eu o aprovei antes de qualquer linha de código. O site que saiu dele tem post próprio.
Uma mensagem de chat e um arquivo pedem esforços bem diferentes. A regra seguinte decide qual dos dois cada pedido recebe.
Três caminhos, as mesmas checagens
Antes do plano, o agente diz qual dos três caminhos o pedido vai seguir:
- Spike: uma pergunta de viabilidade cujo resultado vai para o lixo. Duas ou três frases sobre a pergunta e o teste, um sinal verde meu, e ele executa.
- Delimitado: uma mudança bem definida num fluxo que já é conhecido. Um design curto no chat, minha aprovação, e então a mudança. Sem arquivo de spec.
- Arquitetural: componentes novos, um subsistema novo ou uma interface pública alterada. Design escrito, plano escrito, critérios de aceite para cada TODO e especialistas em cada parte.
O caminho muda a quantidade de papelada, não as checagens. Nos três valem do mesmo jeito a aprovação antes de qualquer ação externa, os TODOs de teste e a evidência de conclusão. A etapa de documentação e as revisões finais de segurança e de documentação também não mudam.
Mais duas regras: se dois caminhos servem, o agente pega o mais pesado, e a classificação só sobe. Se uma tarefa delimitada vira arquitetural no meio, o agente avisa e troca de caminho. Ela nunca desce.
Todo TODO diz como vai ser conferido
Toda mudança de código vira uma lista de TODOs em três classes: implementação, teste e checagem final. Teste nunca é opcional. Cada TODO tem dono, escopo, critérios de aceite e um passo de verificação.
Um agente que recebe uma tarefa trabalha a partir do briefing dela. Por isso o plano tem três partes feitas para esse briefing, e o plano deste site tem as três:
- Um bloco
## Global Constraints, com esse título exato, reúne os requisitos do projeto inteiro (versões mínimas, regras de nomes, limites de plataforma) para que entrem no briefing de cada tarefa. No plano deste site, é ali que ficam a regra de não ter analytics nem cookies e a de não chamar serviço de terceiros em tempo de execução. - Cada TODO diz o que recebe dos anteriores e o que entrega aos seguintes, para que os nomes de uma tarefa batam com os da próxima. Neste site, isso é uma coluna da tabela de TODOs, com entradas como o componente
ProfileCard. - Uma seção Review Focus lista as entradas que a spec sugere, mas que nenhum teste cobre ainda. Uma delas: um post que só existe em português não pode aparecer no blog em inglês nem deixar link alternativo quebrado.
"Pronto" é só uma afirmação até eu ver a evidência
Esta é a parte que eu mais vigio. Um TODO só está concluído com evidência produzida na mesma sessão:
| Afirmação | Evidência | Não é evidência |
|---|---|---|
| Os testes passam | A saída do próprio comando de teste, sem falhas | Uma execução anterior, "deve passar" |
| O build funciona | O comando de build, com código de saída 0 | Linter limpo, log com cara de normal |
| O bug foi corrigido | O sintoma original, testado de novo | Código alterado, falha dada como resolvida |
| O trabalho delegado entrou | Um diff no controle de versão | O agente dizendo que deu certo |
A última linha pesa mais quando um agente delega para outro. O "pronto" de um subagente é uma afirmação. Eu leio o diff.
O agente também roda a suíte de testes inteira do projeto, não só a dos arquivos que tocou. Toda falha que aparece entra no relatório com nome, inclusive as que a mudança dele não causou.
Revisão uma vez só, no fim
A revisão de segurança e a de documentação rodam uma vez, depois que implementação e testes terminaram, e não a cada TODO. Os revisores são consultivos: um apontamento que interpreta mal o código recebe uma contestação fundamentada em vez de correção, e essa contestação fica registrada.
As correções vão para um único agente, que recebe a lista inteira de apontamentos. Nunca um agente por apontamento. Uma rodada é uma correção mais uma nova revisão limitada ao que ficou em aberto. Em três casos o agente para e a decisão vem para mim: cinco rodadas, o mesmo ponto contestado três vezes ou duas revisões fora do formato exigido.
Duas regras sobre o código que já existe
Antes de apagar ou simplificar código, o agente aplica a cerca de Chesterton: primeiro descobre por que aquilo foi escrito. Ele precisa de pelo menos uma fonte concreta da intenção original (histórico do git, uma issue, como o código é chamado). Precisa também dizer qual comportamento continua igual e ter um teste, ou verificação equivalente, nesse caminho. Se não consegue explicar o código, não remove.
Os arquivos também ficam pequenos. Um arquivo de lógica com até 300 linhas passa. Entre 301 e 500, o agente divide o arquivo na mesma tarefa. Acima de 500, nada sem relação entra até existir um plano de divisão.
O que nunca sai da minha mão
Tudo o que leva meu nome
Push, comentário em pull request, revisão, mensagem, release: o agente escreve o rascunho localmente, me entrega e diz com clareza que nada foi enviado. Escrever o rascunho é livre. Enviar espera por mim. Uma autorização precisa nomear a ação, vale só para aquela vez e perde a validade se o rascunho mudar depois. Ela também não passa de um agente para outro: um subagente não envia nada só porque quem o chamou achou que podia.
E um "pode seguir" genérico não chega tão longe. Por conta própria, o agente nunca faz push na branch principal, nunca responde a um revisor humano e nunca publica num registro de pacotes. Aprovar ou fazer merge do trabalho que ele mesmo produziu está fora de questão.
As decisões que os agentes tomam por mim
Quando um agente decide algo por mim, ele registra uma linha Ruling: com o que decidiu, por quê e quanto custa se estiver errado. Essas linhas voltam no relatório final.
Onde as regras estão
Se quiser testar essas regras nos seus agentes, elas vêm com o ai-dotfiles, e estão todas na pasta static/ do repositório.

