---
title: "Spec-first com IA: o que delego e o que fica comigo"
date: 2026-11-19
summary: Agentes de IA planejam, escrevem, testam e revisam meu código. Aprovações e o que sai em meu nome ficam comigo. Veja as regras e a evidência que peço.
tags:
  - ai-agents
  - spec-first
  - code-review
  - claude-code
  - workflow
language: pt-BR
author: Rafael Carvalho Monteiro
canonical: https://rafaelcmm.dev/pt-br/blog/spec-first-with-ai-agents/
url: https://rafaelcmm.dev/pt-br/blog/spec-first-with-ai-agents/index.md
alternates:
  - language: en
    url: https://rafaelcmm.dev/en/blog/spec-first-with-ai-agents/index.md
---

# Spec-first com IA: o que delego e o que fica comigo

Cópia em Markdown do post publicado em https://rafaelcmm.dev/pt-br/blog/spec-first-with-ai-agents/.

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](https://rafaelcmm.dev/pt-br/blog/one-ai-setup-claude-copilot-cursor/) 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](https://rafaelcmm.dev/pt-br/blog/cv-site-ai-recruiters-can-read/).

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](https://rafaelcmm.dev/pt-br/blog/one-ai-setup-claude-copilot-cursor/), e estão todas na pasta `static/` do repositório.
