Engenharia de contexto

Problema: O Claude Code oscila constantemente entre ser brilhante e frustrante. Numa sessão, resolve a tarefa na perfeição. Na seguinte, perde-se com o mesmo pedido. Não dá para prever qual das versões vais ter.

Solução rápida: Pára de colocar tudo no prompt logo de início. Em vez disso, passa a informação ao Claude por etapas:

# Bad: dump everything upfront
claude "Here's my entire codebase architecture, all conventions,
every pattern we use, plus the task..."
 
# Good: let Skills load what's needed, when needed
claude "Build the auth module"
# Skills load authentication patterns only when Claude needs them

A engenharia de prompts tem a ver com formular bem uma pergunta. A engenharia de contexto tem a ver com garantir que o Claude tem os factos certos no momento certo.

Isso também marca a fronteira com as páginas vizinhas. Lê esta página quando o problema de design for o fluxo de informação: o que pré-carregar, o que adiar e como manter o contexto irrelevante fora. Se precisares de regras de recuperação de sessão, lê Gestão de Contexto. Se quiseres uma forma específica para a tarefa de pré-carregar o pacote certo no início da sessão, lê Contexto de Início Dinâmico.

O que é engenharia de contexto?

A engenharia de contexto é a forma como projetas o fluxo de informação para o modelo. Se acertares, o Claude Code começa a comportar-se como um parceiro de programação que compreende a tua intenção. Se errares, passas a sessão a lutar contra ele.

Eis o problema. Uma janela de contexto é um espaço de trabalho limitado, medido em tokens. Instruções, documentos recuperados, resultados de ferramentas e histórico de conversas partilham esse espaço. Atinge o limite e o conteúdo mais antigo desaparece. Organiza-o mal e o Claude perde o fio à meada.

O que significa que o contexto é um recurso escasso. A forma como o estruturas é o que distingue uma compilação que entrega a funcionalidade que tinhas em mente de uma compilação que quase lá chega.

O Desafio da Janela de Contexto

Quando o contexto fica fora de controlo, o Claude Code tende a falhar de quatro formas repetíveis:

Aprende a identificar os quatro. São o padrão contra o qual estás a lutar.

A Estrutura dos Seis Pilares

A engenharia de contexto assenta em seis ideias interligadas. Eis como cada uma delas se insere no Claude Code:

1. Agentes

Um agente do AI é um LLM ligado a ferramentas, memória e raciocínio para que possa perseguir um objetivo. Os agentes decidem o que entra no contexto, o que fica e o que é descartado.

O Claude Code passou de um único agente para vários agentes assim que os subagentes foram lançados. A implicação na engenharia de contexto é direta:

# Single agent: one context window handles everything
claude "Research, plan, build, test, and deploy the payment system"
 
# Multi-agent: specialized contexts, distributed load
# Central AI delegates to focused subagents
claude "Build the payment system"
# → Research agent gathers requirements
# → Backend agent builds Stripe integration
# → Frontend agent creates checkout UI
# → Each agent has clean, focused context

As configurações multiagente evitam a confusão de contexto ao atribuir a cada subagente um mandato mais específico. O teu AIe central torna-se o CTO, distribuindo tarefas especializadas ao especialista certo.

2. Aumento de consultas

As solicitações reais dos utilizadores são um pouco imprecisas. O aumento de consultas aperfeiçoa-as antes do trabalho começar.

Se a tua sessão central do Claude Code estiver configurada como cofundador ou gestor de desenvolvimento, o aumento surge naturalmente desse enquadramento:

Your input: "fix the auth bug"

Central AI refinement: → Analyze recent changes to auth module → Identify error patterns in logs → Scope to affected files (src/lib/auth.ts) → Generate targeted fix with test coverage

Subagent receives: Clear, scoped task with context 

A tua frase mal formulada passa primeiro pelo AI central. Quando chega a um subagente, já é uma tarefa delimitada, e não a tua frase crua de uma linha.

3. Recuperação

A recuperação é a forma como a informação externa é trazida para a janela quando solicitada. A contrapartida é o tamanho dos blocos. Blocos pequenos são precisos, mas perdem o contexto circundante. Blocos grandes trazem um contexto rico, mas a custo de tokens.

O Claude Code não tem recuperação nativa atualmente. Existem soluções parciais através das ferramentas MCPs e CLI, mas ainda não é um ponto forte da plataforma. Por enquanto, o teu CLAUDE.md e as Skills são a camada de recuperação:

# CLAUDE.md - Your retrieval substitute
 
## Architecture (always loaded)
 
- Next.js 15, App Router, TypeScript strict

 
## Patterns (reference when needed)
 
See /docs/patterns/ for component conventions

4. Técnicas de prompt

Esta é a parte que a maioria das pessoas ignora. Despejar informação na janela não garante um resultado forte. O que importa é a ordem, o timing e o canal.

As pesquisas continuam a chegar à mesma conclusão: o início e o fim da janela de contexto recebem mais atenção do que o meio. É por isso que as Skills funcionam tão bem:

Conversation start:
├── CLAUDE.md (beginning of context - high attention)
├── Your initial prompt
├── ... conversation history ...
├── Claude's work
└── Skill loads HERE (end of context - high attention)
    └── Fresh, relevant instructions at peak attention

Até a skill carregar, o Claude funciona de forma enxuta. Assim que é ativada a meio da sessão, as suas instruções caem na parte inferior da janela, mesmo na zona de maior atenção, exatamente quando o conhecimento especializado é necessário. Isso é divulgação progressiva, e recupera tokens que um CLAUDE.md com carga inicial de outra forma desperdiçaria.

5. Memória

A memória é o que transforma um modelo sem estado em algo que se lembra do que fizeste com ele.

A verdadeira memória do Claude Code surge:

Combina o acompanhamento da sessão com documentos dinâmicos e obténs uma camada de memória adaptada a este repositório. O Claude grava nela à medida que as decisões são tomadas e lê-a quando voltas no dia seguinte. Ao longo de semanas, o teu assistente aprende a tua base de código.

6. Ferramentas

As ferramentas são a forma como o raciocínio chega ao mundo real. O Claude Code vem com o básico: Ler, Escrever, Editar, Bash e MCP para serviços externos.

As Skills acrescentaram algo diferente. O Claude consegue executar um script executável sem carregar a sua implementação no contexto. Essa é a ideia do MCP -S CLI: o Claude segue um protocolo e os detalhes internos permanecem invisíveis.

Exemplo: uma skill de pesquisa de documentação construída sobre o Context7 MCP:

# .claude/skills/documentation-research/SKILL.md
 
---
 
name: documentation-research
description: Fetch library docs using Context7 API
 
---
 
## When to Use
 
User needs current documentation for any library
 
## Workflow
 
1. Resolve library ID via Context7
2. Fetch relevant documentation
3. Apply to current task

 
## Tools Available
 
- mcp**context7**resolve-library-id
- mcp**context7**get-library-docs

O Claude acede às ferramentas do MCP através da interface da skill. Orientado por protocolo, eficiente em termos de contexto, sem necessidade de ler o código-fonte.

Exemplos reais que tornam a diferença óbvia

A maneira mais fácil de entender a engenharia de contexto é comparar a mesma tarefa com um contexto ruim e um contexto otimizado.

Exemplo 1: Triagem de segurança

Versão incorreta:

claude "check if this auth flow is secure"

Esse prompt é demasiado abrangente. O Claude não tem um modelo de ameaças, não tem limites do sistema e não faz ideia de qual o código que importa.

Versão otimizada:

claude "Review the password reset flow for account-takeover risk.

Scope: - src/auth/reset.ts
- app/api/reset-password/route.ts
- middleware/session.ts

 Focus: - token generation and expiry
- user enumeration
- rate limiting
- replay risk

 Output: 1. concrete issues
2. exploit path
3. exact fix
4. regression test plan"

O mesmo modelo. Resultado diferente. A segunda versão dá ao Claude um limite do sistema, uma perspetiva de ataque e um contrato de saída. Isso é engenharia de contexto.

Exemplo 2: Grande refatoração

Versão ruim:

claude "migrate our forms to the new validation layer"

Versão otimizada:

claude "Migrate signup + billing forms from ad-hoc validation to Zod.

Read first: - docs/forms/validation-plan.md
- components/forms/*

 Do not touch: - admin flows
- onboarding wizard

 Definition of done: - shared schema extracted
- client + server validation aligned
- error copy preserved
- tests updated for changed messages"

A diferença não está no polimento da formulação do prompt. Está no âmbito controlado. O Claude agora sabe o que ler, o que não deve tocar e o que conta como concluído.

Exemplo 3: Pipeline de produção de conteúdo

Versão incorreta:

claude "write a post about Claude Code hooks"

Versão otimizada:

claude "Write a hooks article for technical readers evaluating Claude Code.

Use: - existing hooks-guide.mdx
- permission-hook-guide.mdx
- session-lifecycle-hooks.mdx

 Must include: - one production workflow
- one failure mode
- one copy-paste config example
- internal links to the three related guides

 Avoid: - generic 'AI changes everything' framing
- repeating definitions already covered in the linked pages"

Agora o Claude não está a escrever no vazio. Está a escrever num sistema de conteúdo real, com elementos vizinhos conhecidos, restrições de sobreposição e requisitos de qualidade.

Onde a Engenharia de Contexto compensa mais

O retorno é maior quando a tarefa é de alto risco ou alta ambiguidade:

Quando a tarefa é barata, imprecisa e reversível, um contexto descuidado é tolerável. Quando a tarefa é cara ou arriscada, é o contexto descuidado que cria uma falsa confiança.

Implementar a estrutura

Hoje: revê o teu CLAUDE.md. Está organizado para facilitar a pesquisa? Os padrões que te interessam estão num local onde o Claude os consiga encontrar?

Esta semana: cria competências para os fluxos de trabalho que repetes. Cada competência é uma proteção contra a confusão de contexto, porque o conhecimento especializado é carregado quando necessário.

De forma contínua: fica atento aos quatro modos de falha. No momento em que o Claude repete erros antigos ou ignora o que disseste, a contaminação já se instalou. Começa de novo.

Conclusão

Uma saída fiável não é um problema de modelos maiores. É um problema de fluxo de informação.

Os seis pilares encaixam-se:

• Os agentes distribuem o contexto entre especialistas
• O aumento de consultas refina entradas desorganizadas
• A recuperação (via CLAUDE.md/Skills) traz à tona informações relevantes
• As camadas de prompts organizam a informação estrategicamente
• A memória mantém o estado entre sessões
• As ferramentas ampliam as capacidades de forma eficiente

Acertes nisto e o Claude Code torna-se um parceiro de programação a quem podes entregar qualquer ideia e confiar a construção.

Próximos passos:

• Guia da janela de contexto de 1M para as últimas novidades sobre disponibilidade GA e preços unificados
• Gestão do buffer de contexto para compreender a reserva de 33K
• Gestão de contexto para otimização de tokens
• Otimização de memória para estratégias de persistência
• Guia de competências para carregamento de conhecimentos especializados sob demanda
• Conceção de subagentes para arquiteturas multiagente