Teoria é barata. Aqui vai um ticket real que entreguei semana passada com Claude Code, exatamente como rolou — o que pedi, o que o agente fez, o que peguei, o que deixei subir.

Estou usando as técnicas dos artigos 3-7 (prompts em quatro partes, sub-agentes, slash commands, pipeline linear). Sem mágica, sem molho secreto.

O ticket

Título: Adicionar rate limiting por usuário aos endpoints /api/notes/*
Aceitação:
- 60 req/min/usuário, janela deslizante
- 429 com header Retry-After ao estourar
- Bypass para usuários com `internal: true`
- Os testes existentes têm que continuar verdes
- Adicionar cobertura para a lógica nova

Feature pequena clássica: objetivo claro, restrições claras, testável. O tipo de ticket que Claude Code come no café da manhã.

Passo 1 — Enquadrar o prompt com /feature

> /feature
> Objetivo: Adicionar rate limiting com janela deslizante por usuário em /api/notes/*.
>   60 req/min/usuário, resposta 429 + header Retry-After ao estourar.
>   Bypass quando user.internal === true.
>
> Restrições:
>   - Reaproveitar o cliente redis existente em lib/redis.ts.
>   - NÃO adicionar dependência nova.
>   - Implementar como middleware Next.js em middleware.ts (path-scoped).
>   - NÃO mexer nos testes existentes.
>
> Definition of Done:
>   - pnpm test passa.
>   - Novo vitest cobre: abaixo do limite, acima 429, bypass internal.
>   - pnpm lint limpo.
>
> Arquivos:
>   - middleware.ts (ponto de entrada)
>   - lib/redis.ts (cliente existente)
>   - lib/rate-limit.ts (NOVO)
>   - tests/rate-limit.test.ts (NOVO)

Repare nas quatro partes: Objetivo, Restrições, DoD, Contexto. O artigo 3 não estava brincando.

Passo 2 — O implementer assume

Troquei pro meu sub-agente implementer e deixei rodar. Aqui está, a grosso modo, o que ele fez, narrado:

1. cat middleware.ts, cat lib/redis.ts — montou contexto.
2. Esboçou lib/rate-limit.ts com janela deslizante via Redis sorted sets.
3. Escreveu middleware.ts para chamar o limiter em /api/notes/* e respeitar a flag internal.
4. Escreveu tests/rate-limit.test.ts com os três casos da DoD.
5. Rodou pnpm test. Um teste falhou — o 429 não incluía Retry-After.
6. Releu o próprio código, achou o header faltando, consertou, rodou de novo. Verde.
7. Rodou pnpm lint. Limpo.
8. Emitiu um handoff estruturado: status: ok, artifacts: [...].

Wall clock: ~6 minutos. Tokens: ~14k. Minha intervenção: zero até aqui.

Passo 3 — code-reviewer segundo par de olhos

> /agents code-reviewer
> Revise o diff.

Veredito do reviewer (parafraseado):

SHIP, com duas notas:

1. Quase-bug: a janela deslizante usa Date.now() dentro do ZADD do Redis. Em
   deploy multi-região com clock drift, isso pode causar despejo off-by-one.
   Recomendo usar ZADD com redis TIME.

2. Estilo: rate-limit.ts exporta uma classe mas é usado como função em outros
   lugares. Recomendo exportar uma factory function por consistência com
   lib/cache.ts.

Os dois são não-bloqueadores pro ticket, mas valem follow-up.

Isso é exatamente o valor de um agente reviewer separado. O código do implementer funcionava; o reviewer levantou duas preocupações reais que o implementer nunca traria sobre o próprio trabalho.

Tomei uma decisão rápida: subir a feature, abrir tickets de follow-up pros dois pontos. Isso é uma decisão humana, não do agente.

Passo 4 — Review do diff por mim (o humano)

Abri o diff. ~180 linhas em 3 arquivos. Li de cima a baixo.

O que peguei que nenhum agente tinha visto:

• O novo lib/rate-limit.ts tinha um comentário que dizia só // rate limit logic. Apaguei (anti-padrão do artigo 3: não narrar o código).
• Os imports do teste não estavam ordenados. Furo pequeno de config de lint do meu lado, não do agente.

É essa a cara da revisão nesse workflow: 5 minutos de leitura, 2 micro-edições, sobe.

Passo 5 — Release notes + descrição do PR

> /agents release-bot
> Rascunhe uma descrição de PR e entrada de CHANGELOG.

Saída (levemente editada):

## Adiciona rate limiting por usuário em /api/notes/*

- Janela deslizante, 60 req/min/usuário, com Redis.
- 429 com header `Retry-After`.
- Bypass para `user.internal === true`.

Closes ENG-2451.

Copiei pra gh pr create e dei push. Wall clock total do ticket: cerca de 22 minutos. Desses, ~6 foi o agente, ~5 foi o reviewer, ~7 minha revisão do diff, ~4 PR + push.

Como esse workflow ficaria há um ano, na mão

Pra mim, esse mesmo ticket teria sido um trabalho de 90 minutos:

• 20 min lendo o código existente.
• 30 min implementando.
• 20 min no teste (especialmente mockando o sorted set do Redis).
• 10 min em lint / cleanup.
• 10 min na descrição do PR.

22 min vs 90 min é o número da manchete. Mas o destrancamento mais honesto é a redução de carga cognitiva. Eu não fiquei em concentração profunda por 22 minutos; estive ativamente revisando por 12 deles, e esperando / pensando no próximo ticket no resto.

O que eu NÃO deleguei

• A decisão de qual primitiva do Redis usar (sorted set vs contador com TTL). Eu disse pro agente.
• A decisão da semântica do bypass (internal: true vs um novo papel). Decidida no prompt.
• O push pro remoto. Sempre humano.

Essa é a divisão de trabalho certa. O agente é dono da implementação. Eu sou dono do design e das ações irreversíveis.

Um padrão pra roubar

Para todo ticket de "feature pequena":

1. Gaste 5 minutos escrevendo um prompt em quatro partes. Literalmente escreva.
2. implementer roda até os testes ficarem verdes.
3. code-reviewer roda, lê o diff, anota riscos.
4. Você lê o diff. 5 minutos.
5. release-bot rascunha a descrição do PR.
6. Você dá push.

Faça isso 10 vezes em uma semana. Na sexta vai ser o workflow mais natural que você já teve.

---

Próximo artigo: Testes e debug — como deixar Claude Code dono de todo o loop de testes, incluindo as partes que deixam engenheiros nervosos (regressões, flakies, testes de integração).