Configurando agentes de IA — CLAUDE.md, system prompt, permissões e o padrão agent-as-employee

A qualidade do output de um agente de IA é diretamente proporcional à qualidade da sua configuração. Um agente mal configurado que recebe uma boa tarefa vai produzir output inconsistente, pular etapas críticas, e tomar decisões que o engenheiro não autorizou. Um agente bem configurado que recebe a mesma tarefa executa um processo verificável, produz artefatos rastreáveis, e para nos momentos certos para pedir aprovação.

A metáfora mais útil não é "ferramenta" — é "funcionário novo". Quando você contrata um engenheiro, não basta dizer "escreva bom código". Você faz onboarding: o que a empresa faz, qual o stack, quais as convenções, como as tarefas fluem da ideia ao merge, quando escalar para o tech lead em vez de decidir sozinho. CLAUDE.md e system prompt são esse onboarding. O workflow definido é o processo. As permissões são o nível de acesso. Os hooks são os checkpoints automáticos. Um agente sem essa configuração é um funcionário sem onboarding: tecnicamente capaz, mas sem o contexto para tomar as decisões certas.

Os quatro vetores de configuração

Toda configuração de agente opera em quatro dimensões independentes. Cada uma controla um aspecto diferente do comportamento:

Vetor 1 — Instrução persistente

A instrução persistente é o que o agente sabe antes de receber qualquer tarefa: o contexto do projeto, as convenções, as restrições, o processo a seguir. No Claude Code, isso é o arquivo CLAUDE.md. Em agentes customizados via API, é o system prompt. São a mesma coisa em contextos diferentes.

A instrução persistente tem dois tipos de conteúdo com funções distintas: contexto (o que o agente precisa saber para tomar decisões — stack, arquitetura, convenções, histórico relevante) e processo (o que o agente deve fazer em cada situação — a sequência de etapas, os pontos de parada obrigatórios, as condições de escalação). Misturar os dois no mesmo documento é natural; confundi-los na escrita é o erro mais comum.

Vetor 2 — Gerenciamento de contexto

O contexto de um agente é o que ele "sabe" durante a execução — o conteúdo da janela de contexto ativa. Esse contexto cresce a cada ciclo do loop de agência e pode se degradar se não for gerenciado: contexto excessivo aumenta custo, reduz foco do modelo, e pode fazer o agente "esquecer" instruções do início da conversa.

Gerenciamento de contexto ativo inclui: compactação de histórico (resumir iterações anteriores em vez de acumulá-las integralmente), seleção explícita do que incluir (não injetar tudo que está disponível — apenas o relevante para a tarefa atual), e separação de memória de longo prazo (em arquivos persistentes) de contexto de curto prazo (no histórico de mensagens da sessão).

No Claude Code, o comando /compact resume o histórico da conversa mantendo apenas o contexto relevante para continuar. Em agentes customizados, esse processo precisa ser implementado explicitamente — geralmente como uma chamada ao LLM com prompt de sumarização antes do contexto estourar a janela.

Vetor 3 — Permissões e ferramentas disponíveis

Um agente só deve ter acesso às ferramentas que precisa para completar sua tarefa. Esse é o princípio do menor privilégio aplicado a agentes: uma ferramenta disponível que o agente não precisa é um vetor de risco — o modelo pode invocá-la de forma não intencional, e um agente comprometido (via prompt injection) pode usá-la de forma maliciosa.

A configuração de permissões tem duas dimensões: quais ferramentas estão disponíveis (allow-list de MCP servers, comandos bash permitidos, acesso a sistemas externos) e o escopo de cada ferramenta (acesso de leitura vs. escrita, quais diretórios, quais endpoints). Um agente de code review não precisa ter permissão de escrever arquivos. Um agente de documentação não precisa de acesso ao banco de dados de produção.

No Claude Code, permissões são configuradas via .claude/settings.json ou ~/.claude/settings.json, com allow-list de bash commands, allow-list de MCP servers, e configuração de quais operações de arquivo são permitidas sem confirmação humana.

Vetor 4 — Hooks de ciclo de vida

Hooks são ações automáticas executadas em eventos específicos do ciclo de vida do agente. No Claude Code, os principais eventos são: PreToolCall (antes de executar uma ferramenta), PostToolCall (após a execução), Stop (quando o agente conclui ou para), e PreCompact (antes de compactar o histórico).

Hooks permitem: validação antes de ações críticas (um hook PreToolCall que verifica se o agente está tentando executar um comando destrutivo), logging de auditoria (registrar cada tool use com timestamp e parâmetros), notificações (enviar alert quando o agente parar aguardando aprovação), e integrações com sistemas externos (criar ticket no sistema de issues quando o agente conclui uma análise).

A diferença entre hooks e permissões: permissões controlam o que o agente pode fazer; hooks reagem ao que o agente faz. Permissões são preventivas; hooks são reativas (ou, via bloqueio no PreToolCall, também preventivas com lógica customizada).

O padrão agent-as-employee

O padrão agent-as-employee resolve o problema mais comum em agentes autônomos: eles pulam etapas. Um agente sem workflow explícito vai da descrição da tarefa diretamente para a implementação, ignorando refinamento de requisitos e design. O resultado pode ser funcional — mas raramente é o que o engenheiro queria, e raramente é auditável o suficiente para merecer confiança em produção.

O padrão define um workflow sequencial com gates obrigatórios — pontos onde o agente deve produzir um artefato verificável e aguardar aprovação explícita antes de prosseguir. Não é sugestão; é estrutura que o agente segue porque está definida na instrução persistente como processo obrigatório.

O workflow em quatro fases

Fase 1 — Intake e refinamento. O agente lê a descrição da tarefa completamente, identifica ambiguidades e requisitos implícitos, e tem duas saídas possíveis: se houver ambiguidade, gera uma lista de perguntas específicas e para (não prossegue sem resposta); se estiver claro, produz um documento de spec estruturado (tasks/TASK-ID/spec.md) com objetivo, comportamento esperado, edge cases, não-objetivos, e critérios de aceite. O gate: o agente aguarda aprovação do spec antes de continuar.

Fase 2 — Design. O agente lê o código existente nos módulos afetados, entende as interfaces disponíveis, e produz um documento de design (tasks/TASK-ID/design.md) contendo: abordagem escolhida, alternativas consideradas e por que foram descartadas, arquivos que serão criados ou modificados, interfaces e contratos públicos que mudarão, e riscos com mitigações. O gate: o agente aguarda aprovação do design antes de escrever qualquer linha de implementação.

Fase 3 — Implementação. O agente implementa seguindo o design aprovado. Qualquer descoberta que contradiga o design aprovado (código existente que torna a abordagem inviável, risco não identificado na fase de design) é reportada imediatamente — o agente para e descreve o problema em vez de improvisar uma solução diferente sem aprovação. Testes são escritos junto com a implementação, não depois.

Fase 4 — Conclusão. O agente produz um summary (tasks/TASK-ID/summary.md) descrevendo o que foi implementado, o que ficou de fora do escopo, e quaisquer débitos técnicos criados conscientemente. Esse artefato é o input para o code review humano.

Condições de escalação

Um agente bem configurado sabe quando parar e pedir ao humano. As condições de escalação devem ser explícitas no CLAUDE.md — não confiar no julgamento do modelo para identificar quando escalar, porque modelos tendem a resolver ambiguidades sozinhos em vez de reportá-las.

Condições típicas de escalação: o design aprovado contradiz código existente encontrado na fase de implementação; uma decisão tem impacto além do escopo definido no spec (modifica mais de N arquivos, altera interface pública, tem implicações de segurança); algo inesperado foi descoberto que muda materialmente o risco da tarefa; o agente está prestes a executar uma operação destrutiva (drop de dados, exclusão de arquivos não listados no design) não explicitamente autorizada.

A escalação não é falha — é o comportamento correto. Um agente que nunca escala é um agente que está tomando decisões que o engenheiro deveria estar tomando.

Artefatos como mecanismo de controle

Os artefatos de cada fase (spec.md, design.md, summary.md) não são apenas documentação — são o mecanismo que torna o workflow auditável. Antes de aprovar um design, o engenheiro pode verificar se o agente entendeu o problema corretamente lendo o spec. Antes de aprovar o merge, pode verificar se a implementação está alinhada com o design aprovado. Se algo deu errado, os artefatos mostram exatamente em qual fase o problema foi introduzido.

Esse nível de rastreabilidade não existe em agentes sem workflow estruturado. "O agente fez algo errado" é muito mais difícil de diagnosticar quando não há artefatos intermediários que mostrem o raciocínio em cada etapa.

CLAUDE.md eficaz

Um CLAUDE.md eficaz tem estrutura clara e separa quatro tipos de conteúdo: contexto (o que o agente precisa saber), processo (como o agente deve trabalhar), regras (constraints não-negociáveis), e escalação (quando parar e perguntar).

O que colocar: stack e versões relevantes, convenções de código não óbvias, decisões arquiteturais que afetam como o agente deve implementar, o workflow obrigatório para tarefas novas, anti-padrões específicos do projeto (não só genéricos), e as condições exatas de escalação. Quanto mais específico, mais útil.

O que não colocar: instruções genéricas que qualquer modelo já seguiria sem instrução explícita ("escreva código limpo", "adicione comentários úteis"), regras que são responsabilidade de linters ou ferramentas automáticas, contexto que muda com frequência e vai ficar desatualizado. Um CLAUDE.md com ruído de instruções genéricas dilui as instruções específicas que realmente importam.

Tamanho: mais curto é melhor, até o ponto onde o contexto crítico está presente. Um CLAUDE.md de 50 linhas denso é mais eficaz que um de 300 linhas com metade de instruções genéricas. O modelo lê o arquivo inteiro, mas prioriza instruções recentes e salientes — instruções importantes afogadas em texto genérico têm menos impacto do que instrução destacada em documento conciso.

System prompt para agentes customizados

Agentes customizados via API têm mais flexibilidade no system prompt do que o CLAUDE.md do Claude Code, porque você controla completamente a estrutura e o conteúdo. As mesmas regras se aplicam (contexto + processo + regras + escalação), mas há padrões adicionais relevantes:

Persona e escopo — definir explicitamente o que o agente é e o que está fora do seu escopo. "Você é um agente de análise de segurança. Sua função é identificar vulnerabilidades no código fornecido e descrever o risco. Você não implementa correções — apenas reporta." O escopo explícito evita que o agente expanda sua atuação para além do que foi projetado.

Formato de output — para agentes que produzem output estruturado (relatórios, specs, diffs), definir o formato esperado explicitamente no system prompt produz resultados muito mais consistentes do que confiar na interpretação do modelo. Se o agente precisa produzir um JSON com campos específicos, o schema vai no system prompt.

Comportamento em edge cases — explicitar o que o agente deve fazer quando não tem informação suficiente, quando encontra algo contraditório, ou quando a tarefa está fora do seu escopo. Sem essa instrução, modelos tendem a improvisar — às vezes de forma útil, às vezes de forma problemática.

Composição: CLAUDE.md + Skills + MCP

Em projetos com uso intenso de agentes, os três mecanismos de configuração se complementam: CLAUDE.md define o contexto e processo global do projeto; Skills encapsulam workflows específicos e reutilizáveis; MCP servers fornecem as ferramentas que os workflows precisam.

A decomposição correta: CLAUDE.md é o onboarding que todo agente no projeto recebe. Skills são as SOP (Standard Operating Procedures) — o processo padrão para tarefas recorrentes específicas. MCP servers são as integrações de sistema — acesso ao ticket system, ao repositório, ao banco de dados de staging. Um agente operando um workflow de feature development usa os três em conjunto: CLAUDE.md diz como trabalhar no projeto, a skill /feature define o processo específico, e os MCP servers de GitHub e Linear fornecem as ferramentas de integração.

Exemplos de configuração

# Projeto: API de Pagamentos

## Contexto
Stack: .NET 8 + PostgreSQL + Redis. Domínio financeiro — precisão decimal obrigatória
em todos os cálculos monetários (nunca float). Serviço processa ~50k transações/dia.
Cobertura de testes atual: 87% (não reduzir). Deploys via GitHub Actions, trunk-based.

## Convenções
- Handlers em `/src/Handlers/`, queries em `/src/Queries/`, domínio em `/src/Domain/`
- Todos os endpoints retornam `Result<T, Error>` — nunca throw para erros de negócio
- Testes de integração usam banco real (TestContainers) — sem mock da camada de dados
- Commits: conventional commits (feat/fix/docs/refactor/test/chore)
- PRs: sempre com description explicando o "por quê", não o "o quê"

## Workflow Obrigatório para Tarefas Novas

### FASE 1 — INTAKE E REFINAMENTO
1. Leia a descrição completa da tarefa
2. Se houver ambiguidade: liste as perguntas em tasks/TASK-ID/questions.md e PARE
   Não prossiga sem respostas — a ambiguidade resolve antes, não durante a implementação
3. Se estiver claro: crie tasks/TASK-ID/spec.md com:
   - Objetivo: o que deve ser feito e por quê
   - Comportamento esperado: fluxo normal + edge cases
   - Não-objetivos: o que explicitamente fica de fora
   - Critérios de aceite: como verificar que está pronto
4. AGUARDE aprovação do spec antes de continuar

### FASE 2 — DESIGN
1. Leia o código dos módulos que serão afetados
2. Crie tasks/TASK-ID/design.md com:
   - Abordagem escolhida (e por que)
   - Alternativas consideradas e por que foram descartadas
   - Arquivos que serão criados ou modificados (lista exaustiva)
   - Mudanças em interfaces ou contratos públicos
   - Riscos identificados e mitigações
3. AGUARDE aprovação do design antes de implementar

### FASE 3 — IMPLEMENTAÇÃO
1. Implemente seguindo o design aprovado
2. Se encontrar algo que contradiga o design: PARE e reporte — não improvise
3. Escreva testes junto com o código, não depois
4. Ao concluir: crie tasks/TASK-ID/summary.md com o que foi feito e o que ficou de fora

## Regras Não-Negociáveis
- Nunca use float para valores monetários — apenas decimal
- Nunca execute migrations diretamente — gere o script e aguarde aprovação
- Nunca modifique arquivos em /infra/ sem aprovação explícita
- Nunca reduza cobertura de testes abaixo de 87%

## Condições de Escalação (pare e pergunte)
- O design aprovado contradiz código existente que você encontrou
- Uma decisão impacta mais de 5 arquivos não listados no design
- Você está prestes a modificar uma interface pública usada por outros serviços
- Você encontrou algo que sugere um risco de segurança ou consistência de dados

Você é um agente de análise de pull requests para a equipe de pagamentos.

## Seu papel
Analisar PRs e produzir um relatório estruturado identificando:
- Riscos de segurança (injection, autenticação, autorização, exposição de dados)
- Problemas de corretude em lógica de negócio financeiro
- Violações de convenções do projeto
- Gaps de cobertura de testes

## Fora do seu escopo
- Você NÃO aprova ou reprova PRs — apenas reporta
- Você NÃO sugere refatorações estilísticas — apenas problemas de risco
- Você NÃO comenta sobre nomes de variáveis ou formatação (isso é responsabilidade do linter)

## Formato de output obrigatório
Produza sempre um JSON com a seguinte estrutura:

{
  "risk_level": "low" | "medium" | "high" | "critical",
  "summary": "resumo em 2-3 frases do que a PR faz",
  "findings": [
    {
      "severity": "info" | "warning" | "error" | "critical",
      "category": "security" | "correctness" | "convention" | "coverage",
      "file": "caminho/do/arquivo.cs",
      "line": 42,
      "description": "descrição do problema",
      "recommendation": "o que fazer para corrigir"
    }
  ],
  "coverage_delta": "+2.3%" | "-1.1%" | "n/a",
  "requires_human_review": true | false,
  "review_reason": "motivo se requires_human_review for true"
}

## Comportamento em edge cases
- Se o diff for muito grande para analisar completamente: analise os arquivos de maior
  risco (autenticação, pagamento, acesso a dados) e indique no summary que a análise
  é parcial
- Se você não tiver contexto suficiente para avaliar um trecho: indique como "info"
  com description explicando o que está faltando para avaliar
- Se encontrar algo que parece crítico mas não tem certeza: use severity "warning"
  com recommendation "revisar com engenheiro sênior antes de aprovar"

{
  "permissions": {
    "allow": [
      "Bash(dotnet build)",
      "Bash(dotnet test*)",
      "Bash(dotnet run*)",
      "Bash(git status)",
      "Bash(git diff*)",
      "Bash(git log*)",
      "Bash(git add*)",
      "Bash(git commit*)"
    ],
    "deny": [
      "Bash(git push --force*)",
      "Bash(git reset --hard*)",
      "Bash(rm -rf*)",
      "Bash(DROP TABLE*)",
      "Bash(DELETE FROM*)"
    ]
  },
  "hooks": {
    "PostToolCall": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "node scripts/audit-log.js \"$CLAUDE_TOOL_NAME\" \"$CLAUDE_TOOL_INPUT\""
          }
        ]
      }
    ],
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "curl -s -X POST $WEBHOOK_URL -H 'Content-Type: application/json' -d '{\"event\": \"agent_stopped\", \"reason\": \"$CLAUDE_STOP_REASON\"}'"
          }
        ]
      }
    ],
    "PreToolCall": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "node scripts/validate-command.js \"$CLAUDE_TOOL_INPUT\""
          }
        ]
      }
    ]
  }
}

Iteração e manutenção da configuração

CLAUDE.md e system prompts não são write-once. Eles precisam evoluir à medida que o projeto evolui e à medida que você observa comportamentos problemáticos ou desejados no agente. O ciclo de manutenção saudável: usar o agente em tarefas reais, observar onde ele desvia do comportamento esperado, identificar se o desvio é por instrução insuficiente ou por limitação do modelo, e atualizar a instrução persistente quando for o primeiro caso.

Versione o CLAUDE.md junto com o código do projeto. Mudanças no CLAUDE.md são mudanças no comportamento do agente — tratá-las com o mesmo rigor de code review que qualquer outra mudança é a prática correta. Um CLAUDE.md mal revisado que introduce uma instrução ambígua pode criar comportamentos inesperados em todas as tarefas subsequentes.

Para equipes com múltiplos agentes (diferentes skills, diferentes contextos de uso), considere um CLAUDE.md raiz com o contexto global do projeto e skills com instruções específicas de cada workflow. A herança de contexto evita duplicação e garante consistência — cada agente sabe quem ele é no projeto antes de receber qualquer tarefa.

Exercícios práticos

1. Audite o CLAUDE.md do seu projeto atual: Se você já tem um CLAUDE.md (ou crie um agora para um projeto real), analise cada linha: ela é contexto, processo, regra, ou aspiração genérica? Remova todas as aspirações genéricas. Para cada instrução de processo, verifique: existe um artefato verificável que confirma que o agente seguiu essa instrução? Se não existe, a instrução provavelmente não será seguida de forma consistente. Reescreva o CLAUDE.md com foco em instruções verificáveis e artefatos concretos.
2. Implemente o workflow de quatro fases: Escolha um projeto real e adicione ao CLAUDE.md as quatro fases descritas neste conceito (intake/spec, design, implementação, summary). Use o Claude Code para executar uma tarefa não trivial seguindo esse workflow. Observe: o agente parou nos gates? Os artefatos produzidos (spec.md, design.md) eram suficientemente detalhados para você verificar e aprovar? Onde o processo quebrou? Ajuste o CLAUDE.md com base nas quebras observadas.
3. Configure hooks de auditoria: Adicione ao .claude/settings.json do seu projeto um hook PostToolCall que registra em arquivo local cada tool invocada (nome, timestamp, parâmetros resumidos). Execute o Claude Code em uma tarefa e analise o log produzido. Perguntas a responder: quantos ciclos de tool use a tarefa envolveu? Quais tools foram mais usadas? Houve alguma invocação inesperada? Como esse log mudaria seu diagnóstico de problemas se a tarefa tivesse produzido output incorreto?