Flow de desenvolvimento com Claude Code baseado em práticas reais documentadas por Fabio Akita e guias de Context Engineering da Anthropic.
Antes de qualquer coisa, isole o agente de IA do seu sistema.
| Ferramenta | Plataforma | Peso |
|---|---|---|
| ai-jail | Linux/macOS | Leve |
| Dev Containers | Qualquer | Pesado |
| Docker manual | Qualquer | Médio |
- Sandbox do Claude Code — permissões built-in
- ai-jail / container — isolamento de OS
- Git — rastreamento de toda mudança
- Backup — snapshots regulares
# Linux
cargo install ai-jail
# macOS — usa sandbox-exec nativomkdir meu-projeto && cd meu-projeto
git initCopie o template e adapte:
cp /path/to/CLAUDE.md.template ./CLAUDE.mdEdite preenchendo:
- Stack tecnológica
- Convenções de código
- Regras de teste
- Foco atual
O CLAUDE.md é uma especificação viva — atualize-o conforme o projeto evolui.
Objetivo: Entender o problema antes de escrever qualquer código.
> Pesquise como [X funciona] neste projeto.
> Quais arquivos são afetados por [Y]?
> Mapeie o fluxo de dados de [A] até [B].
Regras:
- Use subagents para pesquisas exploratórias (preserva contexto principal)
- Revise os resultados — este é o ponto de maior alavancagem humana
- Se a pesquisa está fundamentalmente errada, reinicie com contexto limpo
Objetivo: Especificação detalhada antes da implementação.
> Crie um plano para implementar [feature].
> Liste os arquivos que serão criados/modificados.
> Defina a estratégia de testes.
O plano deve conter:
- Passos exatos de implementação
- Arquivos afetados
- Estratégia de verificação (testes)
- Riscos e edge cases
Regras:
- O humano revisa e aprova o plano antes de executar
- Itere no plano até estar satisfeito
- Um plano ruim gera milhares de linhas de código ruins
Objetivo: Executar o plano aprovado.
> Implemente a fase 1 do plano.
> Rode os testes após cada mudança.
Regras:
- Execute fase por fase, não tudo de uma vez
- Teste após cada fase
- Compacte status de volta no plano para tasks complexas
- Mantenha contexto entre 40-60% — não encha a janela
Subagents são agentes de IA especializados que rodam em contexto isolado. Cada um tem seu próprio system prompt, ferramentas permitidas e modelo.
- São arquivos
.mdcom frontmatter YAML ~/.claude/agents/→ disponível em todos os projetos.claude/agents/→ específico do projeto (versionável no git)- Claude decide quando delegar baseado na
descriptiondo agent - Você pode pedir explicitamente: "use o researcher para..."
| Agent | Modelo | Ferramentas | Memória | Quando usar |
|---|---|---|---|---|
architect |
sonnet | Read-only + Web + Context7 | Sim (user) | Antes de implementar, pesquisar solução certa |
researcher |
haiku | Read-only | Sim (user) | Mapear codebase, arquivos e convenções |
test-runner |
haiku | Bash + Read (bypassPermissions) | Não | Rodar testes sem interrupção |
code-reviewer |
sonnet | Read-only | Sim (user) | Revisar qualidade após mudanças |
debugger |
sonnet | Read-only + Bash | Não | Diagnosticar bugs e root causes |
doc-writer |
haiku | Read + Write | Não | Criar/atualizar documentação |
committer |
haiku | Bash + Read | Não | Criar commits descritivos |
---
name: researcher
description: Quando usar este agent (Claude lê isso para decidir)
tools: Read, Grep, Glob, Bash # Ferramentas permitidas
model: haiku # haiku | sonnet | opus | inherit
memory: user # user | project | local
background: false # true = roda em paralelo
permissionMode: default # default | acceptEdits | dontAsk | plan
hooks: # hooks específicos deste agent
PreToolUse:
- matcher: "Bash"
hooks:
- type: command
command: "./scripts/validate.sh"
---
System prompt do agent vai aqui em Markdown.| Campo | O que faz |
|---|---|
tools |
Allowlist — quais ferramentas o agent pode usar |
disallowedTools |
Denylist — ferramentas bloqueadas |
model |
Qual modelo LLM usa (controla custo e capacidade) |
memory |
Diretório persistente entre sessões (aprende ao longo do tempo) |
background |
Se true, roda em paralelo sem bloquear a conversa |
isolation: worktree |
Roda num git worktree isolado |
skills |
Skills pré-carregadas no contexto do agent |
hooks |
Hooks que rodam apenas enquanto este agent está ativo |
maxTurns |
Limite de turnos antes de parar |
| Modelo | Custo | Velocidade | Use para |
|---|---|---|---|
| haiku | Baixo | Rápido | Pesquisa, testes, buscas simples |
| sonnet | Médio | Médio | Code review, análise, implementação moderada |
| opus | Alto | Lento | Arquitetura, raciocínio complexo |
| inherit | (herda) | (herda) | Quando quer o mesmo modelo da sessão principal |
# Via interface interativa (recomendado)
/agents
# Ou crie o arquivo manualmente
~/.claude/agents/meu-agent.md
# Ou via CLI (temporário, só para a sessão)
claude --agents '{"meu-agent": {"description": "...", "prompt": "...", "model": "haiku"}}'Agents com memory: user mantêm um diretório em ~/.claude/agent-memory/<nome>/
que sobrevive entre sessões. Útil para:
- Acumular conhecimento sobre padrões do projeto
- Lembrar decisões arquiteturais
- Melhorar ao longo do tempo com experiência
- Qualidade > Quantidade: menor set de tokens com maior sinal
- Compactação frequente: resuma, preserve decisões, descarte ruído
- Just-in-time: busque info quando precisar, não carregue tudo upfront
- Hierarquia de prioridade: info incorreta > info ausente > ruído
Output verboso (testes, logs, pesquisa extensa) fica isolado no contexto do subagent. Apenas o resumo volta para a conversa principal.
- Uma sessão = uma feature ou fix
- Contexto limpo para cada unidade de trabalho
- Não tente resolver tudo numa sessão gigante
docs/
├── architecture.md # Decisões que não mudam toda hora
├── plan.md # Plano atual (vive e morre com a feature)
└── research/ # Notas de pesquisa por tópico
"1.323 testes em 8 dias" — Akita, The M.Akita Chronicles
- Todo código novo tem teste — sem exceções
- Rode testes antes de considerar "pronto" — sempre
- Testes crescem com o projeto — 1.323 → 1.422 é normal e esperado
- Testes permitem iteração com confiança — este é o valor real
# Após cada implementação
> Rode os testes.
> Se falhar, corrija antes de avançar."Software 'done' não existe." — 125 commits pós-produção confirmam.
Deploy → Usuários reais → Casos não previstos → Fix/Evolve → Deploy → ...
- A implementação inicial é um ponto de partida, não o produto final
- Feedback real gera trabalho que nenhum planejamento prevê
- Cada iteração melhora a qualidade e a robustez
- O CLAUDE.md evolui junto com o projeto
| Anti-Pattern | Por que é ruim |
|---|---|
| One-shot prompt | Problemas complexos precisam de iteração |
| Encher o contexto | Degrada qualidade do output progressivamente |
| Pular pesquisa | Implementação sem entendimento = retrabalho |
| Ignorar testes | Impossível iterar com confiança |
| Over-engineering | Resolva o problema atual, não o imaginário |
| Confiar cegamente | O humano é o arquiteto, a IA é o executor |
| Rodar sem sandbox | Um comando errado pode destruir dados |
[ ] Ambiente sandboxed e seguro
[ ] CLAUDE.md atualizado com foco atual
[ ] Pesquisa feita e revisada
[ ] Plano criado e aprovado
[ ] Implementação fase por fase
[ ] Testes passando após cada fase
[ ] Commit com mensagem descritiva
[ ] CLAUDE.md atualizado se necessário