📦 Escopo: feature/refactor de 4–8h humanas
Escolha algo do seu backlog real que levaria 4–8 horas de trabalho humano. Pequeno demais não exercita; grande demais vira projeto eterno.
✓ Bons candidatos
- • Feature nova com 2–4 arquivos novos + testes
- • Refactor de módulo médio (500–1500 LoC)
- • Migração de API v1 → v2 em 3–5 handlers
- • Novo dashboard com 3–4 widgets + data layer
- • Integração com SDK externo + wrapper + tests
❌ Escopos errados
- • "Corrigir typo" — pequeno demais
- • "Reescrever todo o backend" — grande demais
- • "Adicionar feature sem tests" — sem sinal objetivo
- • "Algo que mudou muito no repo ontem" — baseline ruim
📐 Briefing ICCA completo do projeto
Template a preencher. Se não soa natural, revisite T2.
# ICCA Briefing — [Nome do Projeto]
## I — Intent
[1–3 frases: o que quero ao final. Estado final observável.]
Ex: "Adicionar export CSV no dashboard /reports, funcional para
os 3 tenants existentes, disponível via botão na UI,
processado em < 5s para 10k rows."
## C — Context
- Repo: path/to/repo
- Branch base: main (commit abc123)
- Stack: Next.js 15, Prisma, PostgreSQL, Vitest
- Arquivos relevantes:
- src/app/reports/page.tsx (UI)
- src/server/reports/queries.ts (data)
- src/lib/csv.ts (se existir; senão criar)
- Convenções: claude.md no repo, seguir
- Tests atuais: passam em main (baseline)
## C — Constraints
- NÃO tocar autenticação
- NÃO refatorar queries.ts além do necessário
- Max 1 nova dependência (papaparse OK, outras discutir)
- Bundle size: não exceder +20KB gzipped
- A11y: botão precisa ter aria-label apropriado
- Tests: coverage >= 85% no novo código
## A — Artifacts (saída esperada)
1. PR com diff coerente, commits pequenos e descritivos
2. Novos tests: src/server/reports/__tests__/export.test.ts
3. Entrada no CHANGELOG.md
4. Screenshot da UI (antes/depois) no description do PR
5. Relatório de uso no final (turnos, tokens, rewind/compact usados)
## Success criteria
- `pnpm test` passa
- `pnpm lint` passa sem novos warnings
- Feature manual-testada em dev com 3 tenants
- PR review approvado automaticamente pelo harness (4.4)🗂️ Scaffold agêntico: init.sh + tests.json + spec.md
3 arquivos mínimos para rodar auto mode com segurança.
📄 init.sh
#!/usr/bin/env bash
set -euo pipefail
# Prep do ambiente para auto mode
# 1) Confirma branch
git checkout -b feat/csv-export main
# 2) Instala deps
pnpm install --frozen-lockfile
# 3) Valida baseline
pnpm test --run
pnpm lint
# 4) Marca o tempo de início
echo "$(date -Iseconds)" > .agent-start
echo "READY. Ambiente limpo, tests pass. Proceed with spec.md."📄 tests.json (success criteria objetivo)
{
"must_pass": [
"pnpm test --run --reporter=json",
"pnpm lint --max-warnings=0",
"pnpm build"
],
"coverage_target": 85,
"budget": {
"max_tokens": 500000,
"max_turns": 8,
"max_time_minutes": 180
},
"forbidden_changes": [
"src/auth/**",
"prisma/migrations/**",
".github/**"
]
}📄 spec.md
# Spec — CSV Export
## Goal
Export selected report rows as CSV from /reports page.
## Behavior
- Button "Export CSV" next to existing filters
- Respects current filter state
- Streams if > 1000 rows (não carrega tudo em memória)
- Filename: reports-{tenant}-{YYYY-MM-DD}.csv
## Acceptance tests (pre-written)
(listagem detalhada de casos que devem passar)
## Anti-scope
- Não adicionar outros formatos (xlsx, pdf)
- Não mexer em permissions
- Não refatorar a query builder🎛️ Execução em xhigh + auto mode + notificação
Setup de execução. Libera você para outras tarefas enquanto roda.
1. Inicie sessão Claude Code no repo
2. /effort xhigh (confirma)
3. Cole o briefing ICCA + peça: "Play a sound and show a
system notification when you finish or need input."
4. Shift+Tab (ativa auto mode)
5. Envia o primeiro prompt com referência a spec.md
6. Vá fazer outra coisa. Som vai tocar quando terminar.Observe: 4.7 cria os hooks próprios no settings.json local — incluindo o trigger de som via afplay (macOS) ou paplay (Linux).
👥 ≥1 subagente + ≥1 rewind + ≥1 compact
Requisito explícito do projeto final. Cada um deve ser usado deliberadamente, não aleatoriamente.
👥 Subagente
Use para: investigar arquivos sem poluir contexto principal, validar em paralelo.
Ex: "Use um subagente para mapear todos os tenants configurados. Só me retorne a lista."
⏪ Rewind
Use para: retomar de ponto válido quando direção atual virou dead-end.
Ex: abordagem de streaming via Node ReadableStream não encaixa no Next handler — rewind para antes dessa decisão.
📦 Compact
Use para: quando contexto inflar após 200k tokens. Sempre com hint.
Ex: "Compact. Hint: mantenha spec, decisões arquiteturais e tests atuais. Descarte chat sobre opções descartadas."
🔎 Code review com coverage prompt
Antes de abrir PR final, rode o harness do módulo 4.4 no seu próprio diff.
# Nova sessão (contexto limpo)
claude
# Cole o harness pr-review.md do módulo 4.4
# + o diff: git diff main...feat/csv-export
# Output: JSON de findings
# Filtre: confidence > 0.6 OU severity = high
# Endereçe findings restantes ANTES de abrir PRDocumente no relatório: quantos findings vieram, quantos você corrigiu, quantos descartou e por quê.
📊 Relatório + rubrica 100 pontos + certificação
Preencha honestamente. ≥80 = certificação aprovada.
| # | Critério | Máx | Meu |
|---|---|---|---|
| 1 | Briefing ICCA completo (I+C+C+A preenchidos, success criteria concreto) | 10 | ____ |
| 2 | Scaffold agêntico (init.sh + tests.json + spec.md + anti-scope) | 10 | ____ |
| 3 | Execução em xhigh + auto mode + notificação real | 5 | ____ |
| 4 | Uso explícito de ≥1 subagente (documentado) | 10 | ____ |
| 5 | Uso explícito de ≥1 rewind + ≥1 compact com hint | 10 | ____ |
| 6 | Snippets aplicados: anti-overengineering + anti-hardcoding + investigate | 15 | ____ |
| 7 | Code review com coverage rodado; findings triados e documentados | 15 | ____ |
| 8 | Entrega funcional: todos success criteria passam (tests/lint/build) | 15 | ____ |
| 9 | Diff coerente com escopo (sem over-engineer nem unrelated changes) | 5 | ____ |
| 10 | Relatório final escrito: turnos, tokens, surpresas, o que melhoraria | 5 | ____ |
| TOTAL | 100 | ____ |
PARABÉNS!
Você concluiu o curso Opus 4.7 completo.
Ao chegar aqui, você:
Você completou
4 trilhas · 28 módulos · ~20h
O contrato mudou. Você mudou com ele.
Vá adiante — delegue, confie, meça. E compartilhe o que aprendeu.