Uma IA pode abrir um repositório, encontrar arquivos e produzir código em minutos. Ainda assim, ela pode escolher a arquitetura errada, repetir um bug conhecido ou alterar um fluxo que a equipe queria preservar. O problema muitas vezes não está na capacidade do modelo; está no contexto disponível quando ele toma decisões.
Um projeto bem contextualizado explica o que está sendo construído, quais regras importam, como a equipe organiza o código e como verificar uma mudança. Isso não exige um prompt gigantesco. Exige informação confiável, fácil de localizar e atualizada junto com o software.
Contexto é mais do que uma boa instrução
Uma instrução diz à IA o que fazer nesta tarefa. Contexto inclui também o que ela precisa saber para decidir como fazer: objetivo do produto, vocabulário do domínio, limites técnicos, padrões já adotados, comandos de verificação e decisões anteriores.
A equipe da Anthropic descreve engenharia de contexto como a curadoria do conjunto de informações que o agente recebe ao longo de um trabalho, incluindo instruções, ferramentas, exemplos e dados recuperados sob demanda. O artigo Effective context engineering for AI agents também chama atenção para a atenção limitada: acrescentar mais material nem sempre melhora a resposta.
Na prática, um repositório com instruções curtas e referências para documentos específicos costuma ser mais útil do que um arquivo enorme que mistura produto, arquitetura, comandos e cada exceção histórica.
Separe as fontes de verdade
Antes de criar novos arquivos, defina onde cada tipo de informação deve viver:
- O código e a configuração mostram o estado real.
- Dependências, scripts, rotas, schemas e testes revelam o que o projeto implementa. Documentação não deve contradizer esses arquivos.
- Documentos explicam as razões e o negócio.
- Objetivos do produto, restrições, termos do domínio e decisões arquiteturais raramente ficam claros só olhando o código.
- Instruções orientam o trabalho do agente.
- Elas indicam o que ler, como seguir padrões locais e como verificar alterações. Não devem substituir a especificação nem duplicar toda a documentação.
Quando essas fontes discordam, o projeto precisa de uma regra explícita para resolver o conflito. Para detalhes atuais de uma implementação, inspecione código e testes; para a intenção de negócio, consulte a documentação responsável e confirme se ela ainda reflete o que a equipe quer.
Uma estrutura pequena que deixa o contexto encontrável
Não existe uma árvore de diretórios ideal para todos os projetos. Uma base possível para começar é:
projeto/
├── AGENTS.md
├── README.md
├── docs/
│ ├── product/
│ │ ├── PRODUCT.md
│ │ └── glossary.md
│ ├── architecture/
│ │ ├── overview.md
│ │ └── decisions/
│ ├── quality/
│ │ └── testing.md
│ └── specs/
├── src/
│ ├── features/
│ └── shared/
└── tests/O README ajuda uma pessoa a instalar e executar o projeto. PRODUCT.md explica para quem ele existe, o que precisa resolver e o que está fora do escopo. Um glossário fixa termos que não podem ser usados de maneira vaga. O overview resume os principais limites técnicos. Registros de decisão — frequentemente chamados de ADRs — guardam o problema, as opções avaliadas e o motivo de uma escolha importante.
Em produto menor, alguns desses conteúdos podem caber em menos arquivos. Em produto maior, documentação por área pode ser mais útil. A estrutura deve tornar a informação fácil de encontrar e atualizar; quantidade de pastas, por si só, não produz boa arquitetura.
Use AGENTS.md como mapa de trabalho
Para o Codex, AGENTS.md pode reunir instruções persistentes do projeto. Ele deve orientar o agente sobre tecnologia, limites importantes, comandos reais e documentos que precisa consultar para certos tipos de tarefa. O guia oficial da OpenAI explica como organizar essas instruções por escopo: regras gerais na raiz e instruções mais específicas em diretórios onde elas se aplicam.
Um exemplo curto poderia ser:
# Orientações do projeto
- Leia docs/product/PRODUCT.md antes de alterar fluxos do produto.
- Consulte docs/architecture/overview.md antes de mudar limites entre módulos.
- Siga os padrões usados nos arquivos próximos à área que estiver alterando.
- Antes de concluir, execute apenas os comandos de verificação documentados.
- Não invente regras de negócio; sinalize ambiguidades e use exemplos existentes.Para regras realmente locais, um arquivo de instruções dentro da área específica pode reduzir o excesso no documento raiz. Isso também evita que toda tarefa carregue detalhes sem relação com ela. O suporte a nomes e regras varia entre ferramentas; consulte a documentação do agente que sua equipe usa e confirme quais arquivos ele reconhece.
O GitHub também documenta instruções compartilhadas e específicas por caminho para o Copilot em instruções de repositório. Se a equipe usa ferramentas diferentes, prefira um conjunto comum de regras quando houver suporte e mantenha separadas apenas as configurações realmente específicas.
Organize o código pelas mudanças que precisam ficar isoladas
A árvore de arquivos também é contexto. Nomes como utils, common e misc podem ser convenientes no começo, mas viram lugares sem limite claro quando recebem código sem relação entre si. Para funcionalidades maiores, uma organização por capacidade do produto pode deixar o código e os testes próximos:
src/
└── features/
├── orders/
│ ├── ui/
│ ├── application/
│ ├── domain/
│ ├── data/
│ └── tests/
└── customers/
├── ui/
├── application/
├── domain/
├── data/
└── tests/Esses nomes são um exemplo, não uma obrigação. Um CRUD simples talvez não precise de quatro camadas; um produto com domínios distintos pode se beneficiar de limites por funcionalidade. O melhor sinal é prático: a equipe consegue descobrir onde uma regra mora, alterar uma área sem espalhar mudanças sem relação e encontrar os testes que validam aquele comportamento?
Peça à IA para observar a organização existente antes de adicionar pastas. Criar uma segunda arquitetura paralela pode ser pior do que seguir um padrão imperfeito, mas ainda consistente. Se a estrutura precisa mudar, documente o objetivo e faça a migração de forma incremental.
Contexto útil combina instruções estáveis com busca sob demanda
Regras que valem para quase toda tarefa pertencem às instruções persistentes: stack, comandos, convenções e limites. Regras que valem só para uma parte do produto devem ficar próximas daquela área. Decisões antigas devem ser referenciadas onde podem ser consultadas, em vez de copiadas em vários lugares.
A IA não precisa receber toda a documentação em cada tarefa. Ela precisa saber onde procurá-la. A documentação da OpenAI sobre contexto e instruções para modelos explica que contexto adicional pode restringir o trabalho a recursos relevantes; a equipe da Anthropic recomenda referências leves e carregamento progressivo de informação quando o agente precisa dela.
Um índice curto em docs/README.md pode responder “onde encontro as regras do produto?”, “qual documento explica a arquitetura?” e “como rodo os testes?”. Para uma tarefa específica, o agente consulta apenas os documentos ligados à mudança.
Descreva tarefas com objetivo e critério de aceite
“Melhore o módulo de pedidos” deixa muitas decisões em aberto. Um pedido de trabalho mais contextualizado informa:
- Resultado: o que precisa mudar do ponto de vista da pessoa usuária.
- Contexto: qual regra ou problema motivou a tarefa e quais arquivos ou documentos explicam esse comportamento.
- Limites: o que deve continuar funcionando e que partes não devem ser alteradas.
- Aceite: exemplos observáveis de comportamento correto, inclusive erros e casos-limite relevantes.
- Verificação: quais testes, checagens ou inspeções devem ser feitos antes de concluir.
Por exemplo: “Permita que uma solicitação em análise seja retomada pela equipe responsável. Consulte o fluxo de status em docs/product/PRODUCT.md e os testes atuais do módulo. Não altere as regras de aprovação; acrescente cobertura para usuário sem permissão e para solicitação já encerrada. Ao final, execute as verificações usadas pela área.” Essa forma reduz suposições sem prescrever cada linha de implementação.
Validação mantém o agente ligado ao projeto real
Um plano claro não prova que o resultado funciona. O ciclo precisa voltar ao repositório: a IA inspeciona os padrões existentes, propõe ou implementa uma mudança, executa as verificações disponíveis e relata o que não conseguiu validar. Testes, lint, checagem de tipos e revisão humana cobrem riscos diferentes; nenhum deles substitui os demais em todos os projetos.
Isso é especialmente importante para autenticação, permissões, dados pessoais, pagamentos e alterações que afetam muitas áreas. Nesses pontos, a revisão deve examinar não só se o caminho feliz funciona, mas também se o agente ampliou acessos, ignorou estados inválidos ou deixou de preservar uma regra de negócio.
Se um mesmo erro se repete, descubra a causa antes de adicionar mais uma instrução. Pode faltar um exemplo, um teste, uma descrição de regra ou uma fronteira clara no código. Corrigir a fonte costuma ser mais útil do que aumentar um prompt que já está difícil de manter.
Um projeto contextualizado continua evoluindo
Contexto envelhece. Uma dependência muda, uma decisão deixa de valer, um fluxo é simplificado e uma instrução pode começar a contradizer o código. Revise a documentação junto das mudanças importantes e remova orientações duplicadas ou sem dono.
Comece pelo mínimo: explique o produto, indique as principais fronteiras, registre decisões que ainda influenciam o trabalho, liste os comandos que realmente existem e mostre onde consultar regras mais específicas. Depois observe os erros de interpretação e melhore o contexto no ponto em que a informação deveria estar.
Uma boa base para IA também é uma boa base para a equipe: intenção visível, limites claros e informação que pode ser verificada no próprio projeto.