Delimitando uma Tarefa Para Que Ela Não Se Perca

Um agente autônomo falha de uma maneira específica: ele se desvia. Você pede uma coisa, ele "gentilmente" refatora mais três, mexe em arquivos que você nunca mencionou, e volta com um diff que você não consegue nem ler. O conserto não é um agente mais inteligente — é um briefing mais rígido.

Uma boa tarefa autônoma tem quatro partes: uma meta clara, restrições explícitas, um critério de pronto concreto, e guardrails (barreiras de proteção) que o próprio agente consegue verificar. Os guardrails são a parte mais importante, porque são a cerca que o agente não consegue pular sem que você perceba.

Goal: Make the failing tests in tests/checkout/ pass.

Constraints:
- Only edit files under src/checkout/. Do not touch src/auth/,
  the database schema, or anything in config/.
- Do not add new dependencies.
- Do not change the tests themselves — the tests define correct behavior.

Done when:
- `npm test tests/checkout/` is fully green.
- `npm run typecheck` passes.
- `git diff --stat` shows changes only under src/checkout/.

If you get stuck after two real attempts, stop and report what you
tried and what's still failing. Don't paper over a failure to make
the suite go green.

O briefing funciona porque encaixota o agente: as restrições isolam o que ele pode tocar, o critério de pronto é um comando que ele consegue rodar, e o laço de verificação o mantém honesto:

 ┌───────────────────────── SCOPE FENCE ─────────────────────────┐
 │  may edit:  src/checkout/                                      │
 │  ✗ off-limits: src/auth/ · db schema · config/ · the tests    │
 │                                                               │
 │     ┌─────────┐   edit    ┌──────────────┐                    │
 │     │  AGENT  │──────────▶│ src/checkout/ │                   │
 │     │         │◀──────────┤              │                    │
 │     └────┬────┘  run test └──────────────┘                    │
 │          │                                                    │
 │          ▼  npm test + typecheck                              │
 │     ┌─────────────┐   green ──▶ DONE                          │
 │     │ VERIFY LOOP │   red   ──▶ retry (max 2)                 │
 │     └─────────────┘   stuck ──▶ STOP & report ────────────────┼─▶ you
 └───────────────────────────────────────────────────────────────┘

Três coisas tornam esse briefing difícil de desviar. As restrições desenham uma parede ao redor dos arquivos que o agente pode tocar. O critério de pronto é um comando que qualquer um consegue rodar, não uma sensação. E o último parágrafo dá permissão para parar e perguntar em vez de sair se debatendo — o que evita o desastre em câmera lenta em que um agente fica "consertando" coisas por vinte minutos e deixa a árvore pior do que encontrou.

Os testes são a cerca de verdade. Um agente que consegue rodar seus próprios testes tem um laço de retorno apertado e honesto e, na maior parte do tempo, fica dentro dele; um sem forma de checar seu próprio trabalho vai te entregar, com toda a confiança, algo quebrado. Se você levar um único hábito deste capítulo: dê ao agente uma forma de se verificar, e faça de passar nela a definição de pronto.