Tip: Se este repositório te ajudou, conecte-se comigo no LinkedIn: linkedin.com/in/xyj1zp3o. Se aplicar alguma prática deste playbook no seu projeto, me marque na publicação.
Diretrizes práticas para desenvolver com agentes de IA de forma governada, rastreável e sustentável.
Este documento reúne diretrizes aplicadas em desenvolvimento com agentes de IA em projetos pessoais e profissionais.
Não é um framework universal. É um conjunto de práticas que emerge da experiência real de operar sistemas multiagente.
A premissa central é simples: o maior problema do desenvolvimento agêntico não é falta de capacidade dos modelos, mas falta de estrutura para operar essa capacidade com previsibilidade.
Agentes poderosos sem perímetro claro são imprevisíveis e comprometem produtividade.
Use este playbook como ponto de partida. Adapte ao seu contexto e descarte o que não fizer sentido.
O objetivo não é seguir cada item ao pé da letra, mas mapear as decisões que precisam ser tomadas ao longo do ciclo.
Restrições vivem na configuração dos agentes, não apenas em documentos de processo.
Em situação de ambiguidade, o comportamento padrão deve ser parar.
O sistema precisa ser seguro por design, com governança embutida no desenvolvimento.
Por quê? Uma regra que depende de alguém lembrar de seguir vai ser quebrada. Se pode ser violada por cansaço, não é governável.
Nenhum agente deve receber mais recursos, ferramentas ou contexto do que seu escopo exige.
Custo por operação é um bom mecanismo de controle de escopo.
Por quê? Capacidade desnecessária é superfície de risco e custo desperdiçado. O modelo mais caro nem sempre é o melhor; tudo depende do escopo.
Toda decisão deve poder ser reconstruída, com intervenção humana em gates específicos.
A autonomia dos agentes deve crescer apenas com critérios previamente documentados.
Por quê? Log não é memória de sistema. Autonomia que cresce silenciosamente é risco acumulado.
Antes de qualquer agente operar, tome as decisões que vão governar todo o ciclo.
Esta é a única fase em que não deve haver interação com IA: as decisões são humanas.
Regra geral: um agente sem escopo declarado antes de começar não deveria existir no sistema.
Para cada agente, defina:
- Nome e responsabilidade principal
- Modelo usado e justificativa
- Ferramentas permitidas
- Ferramentas proibidas
- Orçamento esperado por operação (opcional)
Decisão crítica: modelo e ferramentas definem perímetro. Um agente que só lê código não precisa do mesmo modelo de quem escreve código.
Monte uma matriz de permissões antes do início:
| Operação | Quem pode fazer |
|---|---|
| Ler arquivos do projeto | Todos os agentes |
| Escrever e editar código | Apenas agentes de implementação |
| Executar testes e linters | Agentes de implementação e verificação |
| Fazer commits | Apenas após gate humano |
| Fazer push para branches protegidas | Nunca - humano exclusivo |
| Deploy em produção | Nunca - humano exclusivo |
Adapte para o seu contexto, mas tenha a matriz antes do primeiro agente operar.
Ponto de atenção: esta prática exige maturidade de escopo para estimativa confiável.
Defina um orçamento esperado por operação para cada agente.
Isso controla custo financeiro e indica controle de escopo.
Se uma operação consome muito acima do esperado, o escopo pode estar mal definido ou o agente pode estar fora de controle.
| Decisão | Critério |
|---|---|
| Custo dentro do esperado | Continua normalmente |
| Custo 20-50% acima do esperado | Registra e investiga antes de continuar |
| Custo acima de 50% do esperado | Para, revisa escopo e decide conscientemente |
agent: implementer
model: claude-sonnet
tools_allowed: [read_file, write_file, run_tests]
tools_denied: [git_push, deploy, delete_file]
cost_budget_usd: 0.50
scope: "Escreve e edita código dentro de feature branches"Esta é a fase produtiva. O trabalho acontece aqui, com decisões claras antes de cada passo.
Regra geral: o humano abre o ciclo e valida antes da máquina começar de fato. A partir da implementação, o papel humano é monitorar, não validar cada linha.
INTENT é exclusivamente humano.
Nenhum agente define INTENT; ele recebe INTENT.
Se o INTENT estiver mal escrito, o restante do ciclo vai otimizar para o objetivo errado.
Decisões necessárias:
| Decisão | Critério |
|---|---|
| Qual é o objetivo? | Descreva resultado esperado em 1-2 frases; evite verbos vagos sem critério mensurável |
| Quais são as restrições? | Defina o que não pode mudar, dependências proibidas e limites de performance |
| Como vou saber que funcionou? | Defina critério de sucesso antes de começar |
| Qual é o custo estimado do ciclo? | Estime custo total; se acima do budget, decida conscientemente antes de avançar |
Gate 1: só avance para SPEC com objetivo claro, restrições explícitas e critério mensurável. INTENT vago produz SPEC inútil.
O agente de SPEC lê o INTENT e detalha requisitos funcionais e não funcionais.
Seu papel é validar, não reescrever.
Se a SPEC diverge muito do esperado, o problema normalmente está no INTENT.
O que validar:
- A SPEC cobre todo o INTENT sem lacunas?
- O agente assumiu requisitos não declarados? Estão corretos?
- Requisitos não funcionais estão explícitos (performance, segurança, compatibilidade)?
- Houve expansão de escopo além do INTENT?
Decisão de aprovação:
| Decisão | Critério |
|---|---|
| SPEC aprovada | Avança para PLAN |
| SPEC com ajustes menores | Corrige e avança |
| SPEC com problema de escopo | Volta ao INTENT e reescreve antes de seguir |
O agente de PLAN lê a SPEC e gera um task graph (tarefas, ordem e dependências).
Este é o gate mais crítico em custo: último ponto de bloqueio antes do maior consumo de tokens.
O que validar:
- O task graph cobre todos os requisitos da SPEC?
- Alguma tarefa exige ferramentas fora do agent manifest?
- Dependências fazem sentido? Existem ciclos ou lacunas?
- Riscos identificados têm mitigação documentada?
- Escopo do PLAN continua alinhado ao INTENT?
Gate 2: só avance para IMPLEMENT após validar o PLAN. PLAN mal validado consome o orçamento inteiro antes do problema ficar claro.
O agente de IMPLEMENT executa o task graph.
Seu papel muda: monitorar sinais de desvio, não microgerenciar.
Sinais de desvio:
- Custo acumulando muito acima do estimado
- Solicitação de ferramenta/acesso fora do PLAN
- Implementação divergindo da arquitetura do projeto
- Loop sem convergência (reescrevendo a mesma coisa)
Como agir:
| Decisão | Critério |
|---|---|
| Desvio pequeno e justificável | Documenta e deixa continuar |
| Desvio de escopo ou arquitetura | Interrompe, avalia e decide replanejar ou ajustar INTENT |
| Agente em loop sem convergência | Interrompe, analisa o task graph e quebra tarefa em partes menores |
O agente de DOCS gera documentação técnica do que foi implementado (README, ADR, changelog).
Seu papel é garantir aderência ao que foi feito, não ao que estava planejado.
O que revisar:
- Documentação alinhada à implementação real?
- Decisões arquiteturais relevantes registradas como ADR?
- Changelog explica mudanças de forma clara para terceiros?
Esta é a fase de maior supervisão humana.
Agentes produzem dados; humano decide.
Nenhum agente autoriza avanço aqui.
Regra geral: agentes de verificação são read-only. Eles reportam, não corrigem.
O agente de VERIFY executa gates determinísticos:
- Testes automatizados
- Linters
- SAST
- Cobertura de código
Ele gera um Verification Report, e você interpreta.
O relatório deve conter:
- Resultado de todos os testes, com taxa de passagem e falhas detalhadas
- Cobertura comparada ao threshold definido na Curadoria
- Findings de segurança classificados por severidade
- Custo real do ciclo comparado ao estimado
Como interpretar:
| Decisão | Critério |
|---|---|
| Todos os testes passando, sem findings críticos | Avança para REVIEW |
| Falhas de teste isoladas e conhecidas | Documenta, avalia risco e decide conscientemente |
| Findings de segurança de alta severidade | Bloqueia: não avança sem mitigação documentada |
| Custo muito acima do estimado | Registra e investiga antes de avançar |
Gate 3: qualquer finding crítico de segurança em aberto bloqueia o avanço, sem exceções.
No REVIEW, você avalia implementação, documentação e verificação em conjunto.
A Review Decision deve estar escrita.
Sem decisão documentada, não há release.
O que registrar:
- Entrega atende ao INTENT original?
- Critérios de sucesso foram satisfeitos?
- Há ressalvas? Estão documentadas e aceitas conscientemente?
- Existe rollback plan para produção?
| Decisão | Critério |
|---|---|
| Aprovado sem ressalvas | Avança para RELEASE |
| Aprovado com ressalvas documentadas | Avança para RELEASE com registro explícito |
| Reprovado | Volta para IMPLEMENT com contexto claro |
RELEASE é exclusivamente humano.
Nenhum agente publica em produção.
Você autoriza e executa, ou delega conscientemente para pipeline sob seu controle.
Checklist antes do release:
- Review Decision documentada e aprovada
- Release log preparado (versão, ambiente, responsável, data)
- Rollback plan existente e comunicado
- Janela de deploy adequada
Gate 4: release sem Review Decision documentada é proibido.
É onde o ciclo fecha e o sistema aprende.
Também é a única fase em que o agent manifest pode ser alterado, sempre por decisão humana documentada.
Regra geral: todo ciclo que termina em ITERATE prepara o próximo INTENT.
O agente de MONITOR observa comportamento pós-release e reporta anomalias.
Seu papel é analisar, não reagir automaticamente a cada alerta.
O que observar:
- Erros e exceções não previstos nos testes
- Degradação de performance vs baseline
- Comportamento inesperado em edge cases
- Custo de infraestrutura fora do esperado
Quando agir:
| Decisão | Critério |
|---|---|
| Anomalia leve sem impacto ao usuário | Registra para o próximo ciclo |
| Degradação de performance perceptível | Avalia hotfix ou entrada no próximo ciclo |
| Erro crítico com impacto ao usuário | Aciona rollback imediatamente |
O ITERATE é a retrospectiva do ciclo.
Aqui você decide o que muda em diretrizes, agentes e gates antes do próximo ciclo.
Também é onde autonomia pode crescer, com critério documentado.
Perguntas-chave:
- O ciclo seguiu o fluxo planejado ou houve desvios? Por quê?
- Os gates bloquearam o que precisavam bloquear?
- Algum agente operou fora do escopo esperado?
- O custo real ficou dentro do orçamento?
- Alguma permissão deveria ser expandida ou reduzida?
A autonomia pode crescer, mas sempre de forma deliberada e documentada.
Antes de expandir escopo:
date: [data da decisão]
agent: [nome do agente]
change: "[o que está sendo adicionado ou removido]"
reason: "[por que essa mudança é justificada agora]"
approved_by: [quem decidiu]
review_date: [quando essa decisão será reavaliada]Regra de ouro: nenhum agente modifica a definição de outro agente. Curadoria é território humano, e ITERATE é o único caminho de volta a ela.
| Passo | O que acontece | Presença humana |
|---|---|---|
| INTENT | Define objetivo, restrições e critério de sucesso | Humano exclusivo |
| SPEC | Agente detalha requisitos | Agente propõe, humano valida |
| PLAN | Agente decompõe em tarefas e dependências | Agente propõe, humano valida |
| IMPLEMENT | Agente executa task graph | Agente executa, humano monitora |
| DOCS | Agente gera documentação técnica | Agente gera, humano revisa |
| VERIFY | Agente executa gates determinísticos | Agente executa, humano interpreta |
| REVIEW | Humano decide se entrega está pronta | Humano decide com dados do agente |
| RELEASE | Humano autoriza publicação | Humano exclusivo |
| MONITOR | Agente observa sistema em produção | Agente observa, humano analisa |
| ITERATE | Humano fecha ciclo e prepara o próximo | Humano decide próximo INTENT |
| Gate | Transição | Condição de bloqueio |
|---|---|---|
| Gate 1 | INTENT -> SPEC | INTENT vago, sem restrições ou sem critério de sucesso |
| Gate 2 | PLAN -> IMPLEMENT | Task graph com lacunas, ambiguidades ou escopo expandido |
| Gate 3 | VERIFY -> REVIEW | Testes falhando ou findings críticos de segurança em aberto |
| Gate 4 | REVIEW -> RELEASE | Review Decision ausente ou rollback plan inexistente |
Quando em dúvida: bloqueie.
Override existe, mas deixa rastro.
Ninguém passa por gate quebrado silenciosamente.
OpenRouter permite compor times de agentes onde cada agente usa um modelo diferente, otimizando custo e performance por escopo.
{
"$schema": "https://opencode.ai/config.json",
"agent": {
"planner": {
"model": "minimax/minimax-m2-text-32k",
"mode": "primary"
},
"implementer": {
"model": "minimax/minimax-m2-text-32k",
"mode": "subagent"
},
"reviewer": {
"model": "minimax/minimax-m2-text-32k",
"mode": "subagent"
}
}
}| Escopo | Modelo sugerido | Justificativa |
|---|---|---|
| Planejamento, análise | MiniMax M2 32K | Contexto longo, raciocínio em cadeia |
| Implementação simples | MiniMax M2 8K | Tarefas diretas, menor custo |
| Code review | MiniMax M2 32K | Análise de padrões, contexto de código |
| Verificação de segurança | MiniMax M2 32K | Atenção a detalhes, baixa tolerância a erro |
Cada agente opera independentemente com modelo otimizado para seu escopo:
# Exemplo: pipeline de segurança paralelo
cyber-pentester:
model: minimax/minimax-m2-text-32k
scope: "Análise SAST/DAST, busca CVE"
cyber-defender:
model: minimax/minimax-m2-text-32k
scope: "Hardening, MITRE D3FEND"
# Ambos executam em paralelo após IMPLEMENTOs mesmos princípios se aplicam independentemente do modelo:
- Permissões por agente, não por modelo
- Budget por operação é crítico quando modelos têm custos diferentes
- Log de qual modelo executou cada operação para auditoria
Este playbook é ponto de partida, não destino.
Ele deve evoluir conforme novos ciclos e aprendizados.
O que não deve mudar: disciplina de documentar decisões.
Todo desvio consciente registrado hoje vira aprendizado no próximo ciclo. Todo desvio silencioso vira risco acumulado.
Desenvolver com agentes de IA é um exercício de clareza:
- Sobre o que você quer
- Sobre o que o agente pode fazer
- Sobre onde começa sua responsabilidade
Este playbook busca tornar essa clareza estrutural.