Source: https://aiprimetech.io/pt/blog/claude-code-system-prompt-lessons/ Jul 6, 2026 · 7 min · Engenharia # Prompt de sistema do Claude Code: lições de engenharia para desenvolvedores de agentes A Por [AI Prime Tech](https://aiprimetech.io/pt/) · Com auxílio de IA No mês passado, vi um agente interno de programação excluir o arquivo gerado errado, “corrigir” a falha de teste que ele causou e, em seguida, relatar com confiança que tudo havia dado certo. A causa raiz do problema não era a qualidade do modelo. Era um limite mal definido: o agente tinha permissão para editar coisas demais, regras vagas sobre artefatos gerados e nenhuma exigência de confirmação antes de ações destrutivas. É por isso que a recente discussão pública sobre os prompts de sistema do Claude e do Claude Code é útil, mesmo que você não deva tratar prompts vazados ou coletados como verdade absoluta. Esses conjuntos de prompts costumam ser não oficiais, incompletos, desatualizados ou extraídos de um estado do produto que já não existe. O próprio Claude Code evolui rapidamente, e a linha atual do Claude — Opus 4.8, Sonnet 4.6, Haiku 4.5 e Fable 5 com contexto de 1M — oferece aos criadores de agentes vantagens e limitações muito diferentes das gerações anteriores. Mas a lição interessante não é “copie este prompt”. A lição útil é arquitetural: agentes de programação maduros incorporam limites operacionais, prioridade de instruções, regras de confirmação, disciplina de acesso a arquivos e comportamento em caso de falha ao sistema que envolve o modelo. Este artigo trata dessas lições. ## Lições do prompt de sistema do Claude Code sem copiar o prompt A expressão “prompt de sistema do Claude Code” virou uma forma abreviada de perguntar “como um agente de programação robusto orienta o modelo a se comportar?”. Essa é a pergunta errada se levar à arqueologia de prompts, mas a pergunta certa se levar a um projeto melhor de agentes. Na prática, o prompt de sistema é apenas uma camada. Um agente pronto para produção geralmente tem pelo menos cinco mecanismos de controle que trabalham em conjunto: | Camada | O que controla | Exemplo | Instruções de sistema | Contrato comportamental estável | “Prefira alterações mínimas; não faça commits a menos que seja solicitado.” | Política do desenvolvedor | Regras específicas do produto | “Use apply_patch; nunca execute comandos destrutivos sem aprovação.” | Esquema da ferramenta | O que o modelo realmente pode fazer | read_file, edit_file, run_shell, update_plan | Permissões de execução | O que o processo tem permissão para acessar | Sandbox, diretório de trabalho, política de rede | Instruções do usuário | Objetivo específico da tarefa | “Corrija o teste de autenticação que está falhando.” O erro que vejo em muitos agentes desenvolvidos internamente é reunir tudo isso em um único prompt grande. Isso funciona em demonstrações. Falha sob pressão. Uma abordagem melhor é usar o prompt para explicar a intenção e o ambiente de execução para impor os limites de capacidade. Por exemplo, não se limite a dar esta instrução no prompt: ``` Do not delete files unless the user asks. ``` Transforme a exclusão em uma ferramenta distinta que exija confirmação: ``` { "name": "delete_file", "description": "Delete a file from the workspace.", "input_schema": { "type": "object", "properties": { "path": { "type": "string" }, "reason": { "type": "string" }, "user_confirmed": { "type": "boolean" } }, "required": ["path", "reason", "user_confirmed"] } } ``` Em seguida, imponha essa exigência fora do modelo: ``` def delete_file(path: str, reason: str, user_confirmed: bool): if not user_confirmed: raise PermissionError("delete_file requires explicit user confirmation") if not path.startswith(WORKSPACE_ROOT): raise PermissionError("cannot delete files outside workspace") os.remove(path) ``` O prompt diz ao agente como pensar. O limite da ferramenta decide o que pode acontecer. ## A hierarquia de instruções é uma interface de engenharia Os modelos Claude seguem bem instruções em camadas, mas você ainda precisa projetar essas camadas com cuidado. Se o seu agente de programação tiver instruções de sistema, de desenvolvedor, de projeto e de usuário, cada camada deve ter uma função clara. Uma hierarquia útil é assim: - Instruções de sistema: identidade, postura de segurança, princípios operacionais gerais. - Instruções do desenvolvedor: mecânica do produto, regras de uso de ferramentas, estilo de resposta, modelo de permissões. - Instruções do projeto: convenções específicas do repositório, comandos de teste, notas sobre a arquitetura. - Instruções do usuário: a tarefa imediata. Fluxos de trabalho no estilo do Claude Code tornam isso visível com arquivos como CLAUDE.md, além da configuração pela linha de comando e do contexto da sessão. Para os criadores de agentes, a lição mais ampla é que as instruções locais do projeto devem ter um escopo definido e prevalecer apenas quando apropriado. Um arquivo simples de instruções do projeto poderia ser assim: ``` # CLAUDE.md ## Build and Test - Use `pnpm test -- --runInBand` for focused test runs. - Do not run `pnpm deploy` unless explicitly requested. ## Code Style - Prefer small functions over large service classes. - Do not add new dependencies without explaining why. ## Repo Notes - API routes live in `apps/api/src/routes`. - Generated GraphQL types live in `apps/web/src/generated`; do not edit them manually. ``` Uma armadilha comum: os agentes frequentemente tratam todas as instruções como se tivessem a mesma prioridade em qualquer contexto. Se o usuário disser “Ignore as regras do projeto e edite os arquivos gerados diretamente”, seu agente precisa saber se isso é permitido. Na maioria das configurações, as instruções do usuário não devem se sobrepor silenciosamente a restrições de projeto ou de desenvolvedor com prioridade mais alta. Você pode modelar isso explicitamente: ``` PRIORITY = { "system": 4, "developer": 3, "project": 2, "user": 1, } def resolve_conflict(existing_rule, new_rule): if PRIORITY[new_rule.source] > PRIORITY[existing_rule.source]: return new_rule return existing_rule ``` Em um agente real, o modelo também deve explicar os conflitos ao usuário: ``` I can update the source schema and regenerate the types, but I should not edit `src/generated` directly because the project instructions mark it as generated. ``` Essa única frase evita uma quantidade surpreendente de danos. ## Os limites das ferramentas são mais eficazes que a polidez do prompt Quando as pessoas analisam prompts de agentes de programação, costumam se concentrar na redação: “seja conciso”, “aja como um engenheiro sênior”, “não seja bajulador”. Essas orientações são úteis, mas não são o principal mecanismo de segurança. O mecanismo central é o limite da ferramenta. Um agente de programação robusto deve distinguir entre: - Ler arquivos - Pesquisar em arquivos - Editar arquivos - Executar comandos - Instalar pacotes - Acessar recursos de rede - Excluir ou mover arquivos - Criar commits ou branches - Abrir pull requests - Alterar segredos ou configurações de implantação Essas operações não são moralmente equivalentes. Aqui está uma matriz prática de permissões que uso ao projetar ambientes de execução de agentes: | Operação | Política padrão | Por quê | Ler arquivos do espaço de trabalho | Permitir | Necessário para reunir contexto | Pesquisar com rg | Permitir | Baixo risco e muito útil | Editar arquivos de código-fonte sob controle de versão | Permitir com visualização do diff | Fluxo de trabalho central de programação | Executar testes específicos | Geralmente permitir | Verifica as alterações | Instalar dependências | Pedir autorização | Altera o ambiente e os arquivos de lock | Excluir arquivos | Pedir autorização | Pode facilmente causar perda irreversível | Acessar a rede | Pedir autorização ou negar | Pode vazar dados ou gerar comportamento não determinístico | Editar segredos | Negar por padrão | Grande alcance de impacto | Fazer commit das alterações | Pedir autorização | O histórico do repositório pertence ao usuário | Implantar | Negar, a menos que seja explicitamente solicitado | Impacto em produção É também aqui que a escolha do modelo importa. Gosto de modelos da classe Sonnet para a maioria dos ciclos de agentes de programação porque equilibram bem latência, custo e raciocínio. Opus 4.8 é o modelo que eu escolheria quando o agente precisa de uma síntese arquitetural mais profunda ou de depuração complexa. Haiku 4.5 é adequado para classificação rápida e análise leve de repositórios. O contexto de 1M do Fable 5 é interessante para compreender grandes bases de código, mas um contexto longo não elimina a necessidade de boa recuperação de informações, leituras com escopo definido e disciplina no uso de ferramentas. Um milhão de tokens de contexto ainda pode conter o arquivo errado. ## A confirmação do usuário deve ser específica, não cerimonial Uma experiência ruim de confirmação se parece com isto: ``` May I proceed? ``` Prosseguir com o quê? Editar um arquivo? Executar migrações? Excluir um diretório? Uma boa confirmação é concreta: ``` I need confirmation before running: `rm -rf apps/web/.next` Reason: remove a stale Next.js build cache that may be causing the local runtime error. This deletes only generated build output and does not touch source files. ``` Para agentes semelhantes ao Claude Code, isso importa porque o modelo pode inferir corretamente o próximo passo e ainda assim precisar de autorização humana. Se cada solicitação pedir uma aprovação vaga, os usuários desenvolvem fadiga de aprovação e confirmam sem prestar atenção. Se apenas operações de alto risco exigirem confirmação precisa, os usuários continuam atentos. Recomendo representar a confirmação como um estado estruturado, não como texto corrido: ``` { "action": "run_shell", "command": "rm -rf apps/web/.next", "risk": "destructive_generated_artifact", "requires_confirmation": true, "confirmation_prompt": "Delete generated Next.js cache at apps/web/.next?" } ``` Assim, seu executor de comandos shell pode exigir essa confirmação: ``` def run_shell(command, confirmed=False): risk = classify_command(command) if risk.requires_confirmation and not confirmed: return { "status": "needs_confirmation", "message": risk.prompt } return subprocess.run(command, shell=True, cwd=WORKSPACE_ROOT) ``` Na prática, a classificação de comandos nunca será perfeita. Tudo bem. Use padrões conservadores. Se o classificador não tiver certeza de que um comando é destrutivo, pergunte. ### Comandos que merecem cuidado Estes merecem uma política explícita: ``` rm -rf path git reset --hard git clean -fd git push --force npm install some-package pip install -r requirements.txt docker compose down -v kubectl delete ... terraform apply ``` Alguns são inofensivos no contexto certo. Outros são catastróficos no contexto errado. O agente deve saber que a diferença depende do contexto e perguntar quando o alcance do impacto não estiver claro. ## Acesso a arquivos é engenharia de contexto A parte mais subestimada do projeto de agentes de programação é o acesso a arquivos. O prompt pode dizer “inspecione primeiro os arquivos relevantes”, mas o ambiente de execução deve facilitar esse comportamento. No mínimo, dê ao modelo ferramentas para: - Localizar rapidamente nomes de arquivos - Pesquisar texto - Ler trechos delimitados de arquivos - Visualizar diffs do git - Aplicar patches de forma atômica Um conjunto mínimo de ferramentas poderia ser assim: ``` [ { "name": "search_files", "input_schema": { "type": "object", "properties": { "query": { "type": "string" }, "glob": { "type": "string" } }, "required": ["query"] } }, { "name": "read_file", "input_schema": { "type": "object", "properties": { "path": { "type": "string" }, "start_line": { "type": "integer" }, "limit": { "type": "integer" } }, "required": ["path"] } }, { "name": "apply_patch", "input_schema": { "type": "object", "properties": { "patch": { "type": "string" } }, "required": ["patch"] } } ] ``` Leituras delimitadas importam. Se o agente ler todos os arquivos de um monorepo, desperdiçará contexto e frequentemente terá um desempenho pior. Se ler pouco demais, fará suposições. O equilíbrio ideal está na aquisição iterativa de contexto: ``` rg "createSession|verifySession|SessionStore" apps packages sed -n '1,220p' apps/api/src/auth/session.ts sed -n '1,180p' apps/api/src/routes/login.ts git diff -- apps/api/src/auth/session.ts ``` Os usuários do Claude Code reconhecerão esse ritmo: pesquisar, inspecionar, editar, verificar. Quem cria agentes deve incorporar esse ciclo ao comportamento padrão. Uma armadilha comum: as ferramentas de arquivos precisam preservar os finais de linha, as permissões e a codificação esperada. Já vi agentes reescreverem scripts shell “com sucesso” e removerem os bits de permissão de execução, ou normalizarem arquivos de maneiras que geram diffs cheios de alterações irrelevantes. Sua camada de edição deve ser previsível e conservadora. ## Modos de falha: o que realmente acontece quando agentes dão errado A maioria dos agentes de programação não falha de forma dramática. Eles falham de maneiras plausíveis. Estes são os modos de falha que vejo com mais frequência. ### 1. O agente resolve o sintoma O teste falha porque uma API retorna 401. O agente altera o teste para esperar 401. Build aprovado, produto quebrado. Mitigação: - Exija que o agente explique a cadeia causal. - Peça testes específicos antes de reescritas abrangentes. - Prefira correções no código-fonte a atualizações de snapshots, a menos que o usuário tenha solicitado uma mudança de comportamento. ### 2. O agente edita demais O usuário pede uma pequena correção de bug. O agente reformata cinco arquivos, renomeia variáveis e altera APIs públicas. Mitigação: ``` Make the minimal change that fixes the issue. Do not perform opportunistic refactors unless they are necessary for correctness. ``` Mas também exija a revisão do diff. Mostre os arquivos alterados e as contagens de linhas antes de finalizar: ``` git diff --stat git diff -- apps/api/src/auth/session.ts ``` ### 3. O agente confia em contexto desatualizado Sessões longas acumulam suposições desatualizadas. O usuário altera um arquivo externamente, os testes passam a falhar de outra maneira e o agente continua usando o modelo mental antigo. Mitigação: - Releia os arquivos antes de editá-los se houver possibilidade de terem sido alterados. - Verifique git diff antes de aplicar patches. - Trate a saída das ferramentas como mais atual do que a memória da conversa. ### 4. O agente mascara a falha de uma ferramenta Um comando shell falha, mas o agente prossegue como se tivesse sido bem-sucedido. Mitigação: os resultados das ferramentas devem ser estruturados e difíceis de ignorar. ``` { "tool": "run_shell", "command": "pnpm test auth", "exit_code": 1, "stdout": "...", "stderr": "Cannot find module '@repo/config'", "status": "failed" } ``` Em seguida, instrua o agente: ``` If a tool call fails, do not claim success. Diagnose the failure or clearly report the blocker. ``` ### 5. O agente grava segredos no contexto Se o agente puder ler .env, dumps de falhas ou configurações de produção, poderá incluir acidentalmente segredos em resumos, logs ou prompts. Mitigação: - Bloqueie por padrão arquivos conhecidos por conter segredos. - Oculte valores que se pareçam com tokens na saída das ferramentas. - Exija aprovação explícita do usuário para caminhos que contenham segredos. Exemplo de política de caminhos: ``` DENY_PATTERNS = [ ".env", ".env.*", "**/secrets/**", "**/*.pem", "**/*.key", ] def can_read(path): return not any(fnmatch(path, pattern) for pattern in DENY_PATTERNS) ``` Instruir o modelo a não vazar segredos é bom. Impedir que o modelo veja segredos desnecessários é melhor. ## Projetando um ciclo de agente com a API do Claude Se você estiver desenvolvendo diretamente com a API do Claude, o ciclo útil mais simples é: - Envie as instruções de sistema e de desenvolvedor. - Forneça a tarefa do usuário. - Deixe o Claude solicitar ferramentas. - Execute as ferramentas no seu ambiente de execução. - Retorne os resultados das ferramentas. - Repita até que o modelo produza uma resposta final. Uma estrutura simplificada de requisição se parece com isto: ``` { "model": "claude-sonnet-4-6", "max_tokens": 4096, "system": "You are a coding agent. Make minimal, correct changes...", "messages": [ { "role": "user", "content": "Fix the auth timeout bug and add a regression test." } ], "tools": [ { "name": "read_file", "description": "Read a bounded section of a workspace file.", "input_schema": { "type": "object", "properties": { "path": { "type": "string" }, "start_line": { "type": "integer" }, "limit": { "type": "integer" } }, "required": ["path"] } } ] } ``` Conceitualmente, uma resposta de uso de ferramenta se parece com isto: ``` { "role": "assistant", "content": [ { "type": "text", "text": "I’ll inspect the auth timeout path first." }, { "type": "tool_use", "name": "read_file", "id": "toolu_123", "input": { "path": "apps/api/src/auth/session.ts", "start_line": 1, "limit": 220 } } ] } ``` Seu ambiente de execução então retorna o resultado: ``` { "role": "user", "content": [ { "type": "tool_result", "tool_use_id": "toolu_123", "content": "export function createSession(...) { ... }" } ] } ``` A sintaxe exata do SDK depende da versão do seu cliente, mas o princípio de projeto é estável: o Claude propõe ações, seu ambiente de execução as executa ou rejeita, e o próximo turno do modelo recebe o resultado. Essa separação é o que mantém o sistema compreensível. ## Comandos e configurações do Claude Code que vale a pena estudar Mesmo que você não use o Claude Code diretamente, seu fluxo de trabalho oferece padrões úteis de produto. Inicialização típica de um projeto: ``` claude /init ``` Isso cria ou atualiza as orientações do projeto para que sessões futuras entendam as convenções específicas do repositório. Uma sessão prática costuma ser assim: ``` claude "Find why the billing webhook test is flaky. Do not edit files yet." claude "Patch the smallest fix and run the focused test." claude "Show me the diff and summarize remaining risks." ``` Gosto desse estilo porque ele separa investigação, alteração e verificação. Quem cria agentes pode reproduzir essa separação na forma de modos: ``` { "mode": "investigate", "can_edit": false, "can_run_tests": true, "requires_confirmation_for": ["network", "delete", "install"] } ``` Em seguida, alterne os modos explicitamente: ``` { "mode": "implement", "can_edit": true, "can_run_tests": true, "requires_confirmation_for": ["network", "delete", "install", "commit"] } ``` O que importa não é o comando específico. É o contrato de interação. Os usuários devem saber quando o agente está apenas lendo, quando está alterando arquivos e quando está prestes a fazer algo com efeitos colaterais. ## Por que dumps de prompts são frágeis O repositório do GitHub que reuniu prompts de sistema e configurações de modelos se tornou popular porque engenheiros têm uma curiosidade natural sobre como ferramentas reais são instruídas. Entendo o apelo. Ler prompts pode revelar a visão de produto: quais riscos preocupam os criadores, quais fluxos de trabalho eles otimizam e como se comunicam com o modelo. Mas prompts copiados são frágeis por vários motivos: - Eles podem não ser oficiais. Talvez você não saiba como foram extraídos ou se estão completos. - Eles podem estar desatualizados. Os prompts de agentes mudam conforme os modelos, as ferramentas e as políticas do produto mudam. - Eles dependem de comportamentos ocultos do ambiente de execução. Um prompt que menciona uma ferramenta é inútil sem a implementação dessa ferramenta. - Eles incorporam escolhas e concessões específicas do produto. As restrições do Claude Code podem não corresponder ao modelo de ameaças do seu agente. - Eles podem criar uma falsa sensação de confiança. Um prompt bem elaborado não impõe permissões. Use esses artefatos como inspiração para o projeto, não como dependências. Um exercício melhor é perguntar: que problema esta instrução resolve? Em seguida, resolva esse problema na sua própria stack, com suporte tanto do prompt quanto do ambiente de execução. ## Recomendações Práticas - Trate a Claude Code system prompt conversa como uma discussão de arquitetura, não como uma oportunidade de copiar e colar. - Coloque comportamentos estáveis nas instruções de sistema e de desenvolvedor, convenções do repositório nos arquivos do projeto e objetivos da tarefa nas mensagens do usuário. - Imponha limites para operações de alto risco nas ferramentas e nas permissões do ambiente de execução, não apenas no texto. - Exija confirmação específica para ações destrutivas, que envolvam acesso à rede, alterem dependências ou afetem a produção. - Dê ao agente acesso delimitado a arquivos, pesquisa rápida, aplicação atômica de patches e informações estruturadas sobre falhas de ferramentas. - Otimize para o ciclo que funciona na prática: inspecionar, planejar, editar o mínimo necessário, verificar e resumir os riscos. - Pressuponha que prompts copiados possam estar desatualizados ou incompletos; construa um comportamento duradouro para o agente com base em capacidades explícitas e tratamento claro de falhas. [Programação](/pt/blog/tag/coding/)[Claude](/pt/blog/tag/claude/)[Prompts](/pt/blog/tag/prompts/)[Agentes](/pt/blog/tag/agents/) A [AI Prime Tech](https://aiprimetech.io/pt/) A AI Prime Tech publica este blog. Os artigos são redigidos com assistência de IA; confira detalhes específicos de cada versão, como IDs de modelos, preços e limites, na documentação oficial antes de se basear neles. Obtenha acesso mais barato à API do Claude Uma única chave de API para Claude Opus 5.5, Sonnet 5, Haiku 4.5 e Fable 5.1, além de GPT-6 modelos. Pague conforme o uso, sem assinatura. [Obtenha Sua Chave de API →](/register) A AI Prime Tech é um gateway de API independente de terceiros. Claude™ e Anthropic® são marcas comerciais da Anthropic, PBC. Não há afiliação nem endosso implícitos.