--- title: "Regras de engenharia de contexto para o Claude 5" locale: pt category: ai_data category_name: "Dados de IA" translation_status: reviewed license: cc_by author: "injoys" source_url: https://injoys.com/en/articles/claude-5-context-engineering-rules published_at: 2026-07-27T05:12:07+09:00 --- # Regras de engenharia de contexto para o Claude 5 > Para modelos Claude com maior capacidade de julgamento, objetivos claros, ferramentas bem projetadas e materiais de referência adequados à tarefa são mais importantes do que muitas regras detalhadas. Este artigo explica os princípios e procedimentos de aplicação do projeto de contexto para reduzir instruções redundantes e fornecer as informações necessárias no momento certo. ## Key Points - A engenharia de contexto envolve projetar em conjunto não apenas prompts, mas também instruções de sistema, ferramentas, memória, arquivos, histórico de conversas e resultados de execução. - As regras de segurança, legislação, permissões e integridade dos dados devem permanecer rigorosas, enquanto as diretrizes de estilo que variam conforme a situação devem ser transformadas em princípios baseados no contexto. - Em vez de incluir todas as informações desde o início, elas devem ser disponibilizadas no momento necessário por meio de buscas, leitura de arquivos, Skills e subagentes. - Em vez de listar repetidamente exemplos de uso de ferramentas, devem ser projetadas interfaces com nomes claros, esquemas de entrada, definições de estado e estruturas de erros. - CLAUDE.md, memória automática, código, testes e especificações devem ter funções distintas, sem duplicar as mesmas instruções em vários locais. Para usar de forma eficaz modelos Claude com capacidade de julgamento aprimorada, não basta lapidar uma única frase do prompt. É necessário projetar como um único ambiente de informações as instruções de sistema, os arquivos do projeto, as ferramentas, a memória, o histórico da conversa e os resultados de execução que o modelo verá em uma inferência. O princípio central é simples. > Em vez de definir antecipadamente cada comportamento, forneça um objetivo claro, limites de segurança, interfaces expressivas e materiais de referência confiáveis, deixando os julgamentos detalhados a cargo do modelo. Neste artigo, `Claude 5` refere-se ao ambiente de modelos Claude de alto desempenho da próxima geração mencionado nos materiais fornecidos. O foco não está em especificações concretas do produto nem no status de lançamento, mas nos princípios de projeto de contexto aplicáveis a modelos com capacidade de julgamento aprimorada. ## Engenharia de prompts e engenharia de contexto ### Engenharia de prompts A engenharia de prompts é o trabalho de projetar como a solicitação atual será expressa. Em geral, ela aborda os seguintes itens: - Objetivo da tarefa - Escopo da execução - Restrições - Formato da saída - Critérios de sucesso - Exemplos necessários Por exemplo: ```text Implementar a funcionalidade de cancelamento de pagamento em uma API Route do Next.js. Reutilizar a camada de serviço existente e adicionar testes. Não alterar o contrato da API pública e explicar o motivo das mudanças. ``` ### Engenharia de contexto A engenharia de contexto é o trabalho de selecionar e manter todo o conjunto de informações usado no raciocínio do modelo. Em um agente de programação como o Claude Code, o contexto é composto aproximadamente pelos seguintes elementos: ```text Solicitação atual do usuário + instruções de sistema + CLAUDE.md e instruções do projeto + Skills + memória automática + código, especificações, testes e documentação + definições de ferramentas e recursos MCP + histórico da conversa + resultados da execução de ferramentas e logs de erros ``` Portanto, até mesmo um bom prompt pode perder eficácia quando fornecido junto com memórias desatualizadas, regras de projeto duplicadas ou logs extensos. Por outro lado, mesmo uma solicitação curta pode ser executada com precisão suficiente quando acompanhada de código e testes relevantes e de ferramentas claras. | Categoria | Engenharia de prompts | Engenharia de contexto | |---|---|---| | Objeto do projeto | Expressão da solicitação atual | Todo o ambiente de informações usado no raciocínio | | Pergunta principal | O que solicitar e como | O que o modelo deve ver e quando | | Elementos representativos | Objetivo, formato, restrições, exemplos | Instruções de sistema, arquivos, ferramentas, memória, histórico | | Principais falhas | Solicitação ambígua, critérios de sucesso pouco claros | Conflitos, duplicações, informações desatualizadas, logs excessivos | | Método de melhoria | Tornar a solicitação concreta e apresentar critérios de validação | Selecionar informações de alto sinal, recuperá-las no momento adequado e gerenciar seu ciclo de vida | ## Por que mais contexto nem sempre é melhor Mesmo que a janela de contexto de um LLM aumente, a atenção disponível para a tarefa não é ilimitada. Quando a quantidade de tokens pouco relevantes aumenta, podem surgir os seguintes problemas: 1. Requisitos importantes ficam escondidos em meio a explicações prolixas. 2. Instruções semelhantes em locais diferentes entram em conflitos sutis. 3. Decisões antigas ou tentativas fracassadas influenciam a tarefa atual. 4. Exemplos funcionam como se fossem a resposta correta e limitam outras abordagens de solução. 5. Logs e saídas de ferramentas ocupam o espaço necessário para código, especificações e testes. 6. O modelo gasta seu raciocínio interpretando a prioridade das instruções, em vez de executar a tarefa propriamente dita. Anthropic descreve a redução da eficiência no uso de informações em contextos longos e recomenda projetar agentes para recuperar as informações necessárias no momento adequado e compactar registros antigos. O importante não é preencher a quantidade máxima de tokens, mas aumentar a proporção de tokens de alto sinal que afetam o resultado. ## O que significa o caso de redução do prompt de sistema O caso fornecido pela Anthropic explica que, após uma revisão das instruções internas do Claude Code, o prompt de sistema foi reduzido em pelo menos 80%. Esse número não é uma regra segundo a qual os prompts de todas as aplicações devem ser reduzidos na mesma proporção. Ele deve ser entendido como um caso específico em que instruções comportamentais duplicadas e excessivamente detalhadas foram reorganizadas em determinado sistema. Por exemplo, as seguintes instruções podem ser incluídas simultaneamente em uma solicitação: ```text Instrução de sistema: deixar documentação adequada à situação. Instrução da Skill: não adicionar comentários. Solicitação do usuário: fazer com que funcione como a versão anterior. ``` Cada frase pode ser válida individualmente, mas, quando colocadas juntas, elas geram vários problemas de interpretação. - Documentação e comentários de código pertencem à mesma categoria? - A proibição de comentários é uma regra sem exceções? - O comportamento da versão anterior também inclui comentários ou a estrutura da documentação? - O que tem prioridade: a solicitação atual ou a Skill reutilizável? Nesse caso, a causa da falha não é apenas a capacidade de programação do modelo. O fato de o ambiente de informações criado por pessoas conter contradições desnecessárias também é uma causa. ## Seis novas regras de projeto de contexto | Abordagem anterior | Abordagem recomendada | |---|---| | Definir comportamentos detalhados por meio de listas de proibições | Apresentar objetivos e critérios de julgamento e utilizar o contexto | | Fornecer muitos exemplos de chamadas de ferramentas | Projetar o próprio esquema para explicar como usá-las | | Injetar todas as informações no início da tarefa | Revelar gradualmente no momento necessário | | Repetir a mesma instrução em vários locais | Definir um único local oficial de armazenamento para cada instrução | | Armazenar até memórias temporárias no CLAUDE.md | Separar as funções das políticas permanentes e da memória automática | | Depender de explicações longas em Markdown | Fornecer materiais executáveis, como código, testes, HTML e rubricas de avaliação | ### 1. Transforme listas detalhadas de proibições em princípios baseados no contexto Para evitar erros repetitivos de modelos anteriores, às vezes eram listadas regras extensas como estas: - Não escrever comentários. - Não criar docstrings com vários parágrafos. - Não gerar documentos de planejamento que não tenham sido solicitados. - Não salvar arquivos intermediários de análise. Essas regras evitam falhas específicas, mas não são princípios absolutos aplicáveis a todas as situações. Uma validação de segurança complexa ou um código de concorrência pode exigir explicações, enquanto comentários podem apenas gerar ruído em um código CRUD autoexplicativo. É melhor apresentar critérios de julgamento como os seguintes: ```text Escrever código que seja lido da mesma forma que o código ao redor. Seguir as convenções de nomenclatura, expressões idiomáticas e densidade de comentários dos arquivos existentes. Adicionar somente a documentação necessária para lógicas cuja segurança ou intenção não fique clara sem explicações. ``` No entanto, nem todas as regras devem ser suavizadas. Os itens a seguir devem continuar sendo tratados como restrições explícitas ou controles no nível das ferramentas: - Aprovação para implantação no ambiente de produção e exclusão de dados - Restrições ao tratamento de dados pessoais e informações confidenciais - Validação de autenticação e autorização - Idempotência e registros de auditoria de transações financeiras - Políticas de migração de banco de dados - Conformidade jurídica, de licenciamento e regulatória - Contratos imutáveis de APIs públicas | Tipo de regra | Forma adequada de tratamento | |---|---| | Segurança, questões jurídicas e permissões | Manter restrições explícitas e fortes | | Operações com possibilidade de perda de dados | Controlar por procedimentos de aprovação e permissões de ferramentas | | Contratos públicos e compatibilidade | Validar por testes e esquemas | | Estilo de código e comentários | Usar princípios de julgamento baseados no código ao redor | | Ordem temporária das tarefas | Gerenciar no plano atual ou na lista de tarefas | ### 2. Projete ferramentas expressivas em vez de fornecer muitos exemplos Adicionar continuamente exemplos de chamadas válidas e inválidas à descrição de uma ferramenta aumenta o contexto e pode fazer o modelo imitar a forma superficial dos exemplos. Uma abordagem melhor é fazer com que o nome da ferramenta, seus campos de entrada e suas transições de estado revelem como ela deve ser usada. ```text TodoWrite Objetivo: criar e atualizar a lista de tarefas da sessão atual status: - pending - in_progress - completed Restrição: - somente uma tarefa pode estar in_progress ao mesmo tempo ``` Uma boa ferramenta para agentes tem as seguintes características: - O nome, por si só, revela a ação e seu alvo. - Os campos obrigatórios e opcionais são diferenciados. - Os valores permitidos são limitados por enumerações. - Leitura e escrita, bem como visualização e execução, são separadas. - Os erros retornam de forma estruturada a causa e o método de recuperação. - Operações perigosas exigem um token de confirmação ou uma etapa de aprovação. - Quando os resultados são excessivamente longos, são oferecidos resumo e recursos de paginação. É recomendável adicionar exemplos somente para explicar exceções ou entradas ambíguas difíceis de expressar por meio da interface. ### 3. Não inclua todas as informações desde o início; revele-as gradualmente Não se deve injetar desde o início todo o repositório, todas as políticas e logs extensos apenas porque há a possibilidade de o agente precisar deles para executar a tarefa. Primeiro, forneça as informações mínimas necessárias para a exploração e faça com que os materiais relevantes sejam lidos à medida que a tarefa for concretizada. O fluxo recomendado é o seguinte: 1. Forneça o objetivo, os critérios de sucesso e os limites de segurança. 2. Encontre os locais relevantes por meio da estrutura do repositório ou de ferramentas de busca. 3. Leia somente os arquivos e as especificações necessários. 4. Após a implementação, execute os testes relevantes e a análise estática. 5. Em caso de falha, recupere adicionalmente apenas o erro correspondente e o código ao redor. 6. Após a conclusão, compacte ou remova logs antigos e raciocínios intermediários. A revelação gradual não significa ocultar informações. É uma abordagem que fornece caminhos de busca e uma estrutura clara de arquivos para que o modelo possa encontrar as informações necessárias. ### 4. Remova instruções duplicadas e defina um local oficial Se a mesma regra for copiada para o prompt de sistema, o CLAUDE.md, uma Skill e a descrição de uma ferramenta, os textos podem divergir com o tempo. É necessário definir um único local oficial de armazenamento para cada tipo de instrução. | Informação | Local recomendado | |---|---| | Política de segurança de toda a organização | Instruções de sistema ou hierarquia de permissões | | Comandos de compilação e teste do repositório | CLAUDE.md do projeto | | Procedimento de uma tarefa específica | Skill correspondente | | Entradas e restrições de ferramentas | Esquema e descrição da ferramenta | | Comportamento de API pública | Esquema de código, especificação e testes de contrato | | Progresso da sessão atual | Lista de tarefas ou estado da sessão | Caso a duplicação seja inevitável, é mais seguro apontar para o local oficial ou gerar o conteúdo automaticamente, em vez de copiá-lo. ### 5. Separe as funções do CLAUDE.md e da memória automática O CLAUDE.md é adequado para instruções duradouras que os integrantes do projeto podem revisar e controlar por versão. - Comandos padrão de compilação e teste - Explicações essenciais sobre a estrutura do repositório - Áreas que a equipe concordou em não modificar - Procedimentos de validação específicos do projeto - Regras difíceis de inferir com ferramentas comuns Por outro lado, as seguintes informações são mais adequadas para a memória automática ou o estado da sessão: - Preferências personalizadas descobertas em tarefas repetidas - Caminhos de exploração que foram úteis em tarefas recentes - Características temporárias do ambiente de desenvolvimento - Progresso da sessão atual Não se deve presumir que a memória automática seja sempre precisa ou permanente. Deve ser possível corrigir ou remover itens antigos, e ela não deve ser usada como o único repositório de políticas de segurança e contratos públicos. ### 6. Priorize materiais de referência executáveis em vez de documentos explicativos Especificações em linguagem natural são úteis para explicar a intenção, mas podem não expressar completamente o comportamento real. Sempre que possível, forneça também os seguintes materiais: - Implementações existentes semelhantes ao código atual - Testes unitários e testes de integração - Esquemas de API e definições de tipos - HTML real ou entregáveis de design - Arquivos de migração de banco de dados - Dados de exemplo de entrada e saída - Rubricas de avaliação e critérios de pontuação automática Também podem surgir conflitos entre os materiais de referência, portanto é necessário definir prioridades. Por exemplo, pode-se determinar que os testes de contrato são a referência oficial para a API pública e que o README é um material explicativo. ## Modelo prático de composição de contexto A estrutura a seguir é um exemplo de como organizar de forma concisa as informações necessárias para uma tarefa de programação. ```text Objetivo - Adicionar uma API de cancelamento de pagamento. Critérios de sucesso - Reutilizar a camada de serviço de pagamentos existente. - Mesmo com solicitações duplicadas, o cancelamento ocorre apenas uma vez. - Os testes de contrato relacionados são aprovados. Restrições fortes - Não alterar o esquema de resposta pública. - Não acessar dados de produção. Materiais de referência - src/payments/capture.ts - tests/contracts/payment-cancel.test.ts - openapi/payments.yaml Princípios de julgamento - Seguir o tratamento de erros e as convenções de nomenclatura do código de pagamentos ao redor. - Se houver uma suposição insegura, perguntar antes da implementação. Validação - Testes unitários do alvo - Testes de contrato - Verificação de tipos ``` Esse formato não lista antecipadamente todas as situações. Em vez disso, separa o objetivo, as condições de sucesso, os limites imutáveis, os materiais oficiais e os métodos de validação. ## Procedimento para organizar o contexto existente ### Etapa 1: liste as fontes de todas as instruções Verifique em conjunto o prompt de sistema, o CLAUDE.md, as Skills, a memória automática, as descrições de ferramentas e as configurações de CI. Ao examinar apenas um documento, é difícil identificar conflitos reais. ### Etapa 2: classifique cada instrução - Obrigatória por razões de segurança ou jurídicas - Obrigatória devido ao contrato do produto - Prática duradoura da equipe - Explicação necessária apenas para uma ferramenta específica - Regra temporária para evitar erros de modelos anteriores - Regra cuja justificativa atualmente não está clara ### Etapa 3: encontre duplicações e conflitos Agrupe frases que expressem o mesmo comportamento de maneiras diferentes. Revise primeiro, em especial, expressões como `sempre`, `nunca`, `obrigatoriamente` e `não faça`. ### Etapa 4: transfira regras para testes ou permissões Os itens cuja validação automática é mais confiável do que avisos em linguagem natural devem ser transferidos para as seguintes camadas: - Testes e linters - Sistema de tipos e esquemas - Ferramentas com privilégio mínimo - Procedimentos de aprovação - Sandbox - Políticas de CI ### Etapa 5: avalie com tarefas reais Não se deve medir apenas o tamanho do prompt. É necessário comparar os seguintes indicadores em um conjunto representativo de tarefas: - Taxa de sucesso e taxa de aprovação nos testes - Número de alterações desnecessárias em arquivos - Quantidade de correções feitas pelo usuário - Taxa de falha nas chamadas de ferramentas - Tempo e tokens gastos até a conclusão - Ocorrência de violações das políticas de segurança ### Etapa 6: complemente minimamente apenas as causas das falhas Quando ocorrer uma falha, não adicione imediatamente uma nova regra de proibição. Primeiro, determine se a causa foi um objetivo ambíguo, materiais de referência insuficientes ou um esquema de ferramenta incorreto. ## Instruções que não devem ser removidas Simplificar não significa remover indiscriminadamente. Se a resposta a qualquer uma das perguntas a seguir for `sim`, a instrução deve ser mantida ou transferida para um controle mais forte. - Uma violação pode causar perda de dados ou prejuízo financeiro? - Está relacionada a obrigações jurídicas, de privacidade ou de licenciamento? - Trata-se de uma política organizacional que o modelo não consegue identificar apenas examinando o código? - Determina a compatibilidade de uma API pública ou de um formato de dados? - Exige aprovação humana antes da execução da tarefa? - É difícil detectar completamente uma violação apenas com testes automatizados? ## Padrões comuns de falha ### Adicionar uma nova regra após cada falha Quando um único erro é generalizado e transformado em uma regra permanente, exceções e conflitos se acumulam. Primeiro, deve-se adicionar um caso de avaliação e verificar se a falha é recorrente. ### Usar exemplos longos praticamente como modelos Se um exemplo for específico demais, o modelo poderá priorizá-lo em vez da base de código atual. Os exemplos devem ser limitados ao tamanho mínimo necessário para explicar o princípio. ### Preservar logs completos sem alterações Saídas de ferramentas e logs de compilação ocupam rapidamente o contexto. É melhor manter de forma estruturada apenas a causa da falha, a stack relevante e o estado alterado. ### Usar a memória automática como repositório de políticas A memória automática é conveniente, mas seus mecanismos de revisão, implantação e auditoria podem ser frágeis. As políticas obrigatórias da organização devem ser armazenadas em instruções controladas por versão ou em uma hierarquia de permissões. ### Avaliar a redução de contexto apenas como economia de tokens Um contexto curto nem sempre é melhor. Remover testes necessários, regras de segurança ou especificações piora o resultado. O objetivo não é obter o mínimo de tokens, mas o mínimo necessário de tokens de alto sinal. ## Checklist final - O objetivo da solicitação atual está separado dos critérios de sucesso? - As regras de segurança estão separadas das preferências de estilo? - A mesma instrução não está duplicada em vários locais? - O esquema da ferramenta explica como usá-la sem exemplos longos? - É possível buscar os arquivos relevantes quando necessário? - Há uma forma de remover memórias desatualizadas e logs de execução? - É possível impor regras em linguagem natural por meio de testes ou permissões? - A prioridade entre os materiais de referência está clara? - Há tarefas de avaliação para comparar o antes e o depois das alterações nas instruções? ## Conclusão A engenharia de contexto para modelos Claude de alto desempenho não é uma técnica de simplesmente reduzir instruções. É um projeto de informações que torna claros o objetivo, os limites de segurança e as evidências necessários para que o modelo julgue a tarefa atual, ao mesmo tempo que remove informações irrelevantes e regras conflitantes. O princípio mais prático pode ser resumido da seguinte forma: > Imponha rigorosamente a segurança e os contratos, deixe o estilo a cargo do contexto, forneça as informações no momento necessário e valide os resultados com testes executáveis. ## FAQ ### Qual é a diferença entre engenharia de prompts e engenharia de contexto? A engenharia de prompts trata de como expressar o objetivo, o formato e as restrições da solicitação atual. A engenharia de contexto projeta o que mostrar ao modelo e quando, incluindo esse prompt, entre instruções do sistema, arquivos, ferramentas, memória, histórico da conversa e resultados da execução. ### Um contexto mais longo sempre melhora o desempenho do modelo? Não. Um contexto longo pode conter informações irrelevantes, registros antigos e instruções conflitantes. O importante não é o número total de tokens, mas a proporção de informações de alto valor que contribuem diretamente para a tarefa atual. ### É necessário excluir todas as regras existentes para o Claude 5? Não. Regras minuciosas que variam conforme a situação, como estilo de código ou comentários, podem ser convertidas em princípios de decisão, mas as restrições relacionadas a segurança, dados pessoais, permissões, transações financeiras, exclusão de dados e contratos de API pública devem ser mantidas ou controladas com mais rigor por meio de ferramentas e testes. ### Que tipo de conteúdo é apropriado incluir no CLAUDE.md? São apropriadas instruções duradouras e verificáveis, como comandos de compilação e teste do projeto, a estrutura do repositório, áreas que não devem ser alteradas e procedimentos de validação acordados pela equipe. Se todo progresso temporário ou descoberta personalizada for armazenado, o documento poderá ficar desatualizado rapidamente. ### A memória automática pode substituir o CLAUDE.md? Não pode substituí-lo completamente. A memória automática é útil para manter preferências ou informações de exploração descobertas em tarefas repetitivas, mas instruções que exigem auditoria e controle de versão, como políticas de segurança e contratos públicos, devem ficar no CLAUDE.md ou em uma camada separada de políticas. ### Quais características uma boa interface de ferramentas para agentes deve ter? A finalidade deve ficar evidente apenas pelo nome da ferramenta e pelo esquema de entrada, e os valores obrigatórios e estados permitidos devem ser claros. É recomendável que operações de escrita perigosas exijam uma visualização prévia ou aprovação e que os erros retornem de forma estruturada a causa e o método de recuperação. ### A divulgação progressiva significa ocultar informações do modelo? Não. É uma abordagem que fornece inicialmente o objetivo e o caminho de exploração e permite que o modelo pesquise os arquivos, as especificações e os logs necessários à medida que detalha a tarefa. O objetivo é reduzir a injeção prévia de informações desnecessárias, mantendo a possibilidade de acesso às informações. ### Como avaliar o efeito após reduzir o contexto? Em um conjunto representativo de tarefas, deve-se comparar, antes e depois da mudança, a taxa de aprovação nos testes, o número de correções feitas pelo usuário, as alterações desnecessárias, os erros de ferramentas, o uso de tokens e a ocorrência de violações das políticas de segurança. O sucesso não deve ser avaliado apenas pela redução do tamanho do prompt. ### Não é necessário fornecer nenhum exemplo de uso das ferramentas? Os exemplos nem sempre são desnecessários. Quando há casos-limite ou entradas ambíguas difíceis de representar apenas com o esquema, exemplos mínimos são úteis. No entanto, deve-se priorizar tornar a própria interface clara, em vez de listar repetidamente chamadas normais. ## Sources - [Engenharia de contexto eficaz para agentes de IA](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents) - [Construindo agentes eficazes](https://www.anthropic.com/engineering/building-effective-agents) - [Visão geral da engenharia de prompts](https://docs.anthropic.com/en/docs/build-with-claude/prompt-engineering/overview) - [Documentação de memória do Claude Code](https://docs.anthropic.com/en/docs/claude-code/memory) ## Images ![Ícones de documentos e dados passam por um funil até uma rede central de IA](https://injoys.com/rails/active_storage/blobs/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MzMzMywicHVyIjoiYmxvYl9pZCJ9fQ==--b6a9225f1d5837dd6ca93532a1e1a3388a1cc4fc/ai-e5c0c894.webp) ![Fluxo de IA com robô passando por busca, arquivos, ferramentas, código, validação e relatório até o alvo](https://injoys.com/rails/active_storage/blobs/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MzMzOSwicHVyIjoiYmxvYl9pZCJ9fQ==--c5e1421a425951ca760407e2d7b6c78654f545e5/ai-8b2296c2.webp)