Estruturar, organizar e padronizar o conhecimento técnico de projetos de software permite que diferentes desenvolvedores e agentes de IA trabalhem seguindo as mesmas decisões arquiteturais, convenções, contratos e procedimentos, sem precisar redescobrir o funcionamento do sistema a cada tarefa.

A proposta é estabelecer uma base de conhecimento consistente e acessível, integrada ao próprio projeto, que oriente o desenvolvimento independentemente de quem esteja executando o trabalho ou de qual ferramenta de IA esteja sendo utilizada.

1. O projeto como fonte de contexto

Um projeto preparado para trabalhar com agentes de IA deve disponibilizar suas próprias instruções e referências técnicas.

Informações como tecnologias utilizadas, arquitetura, bibliotecas adotadas, padrões de implementação, contratos e procedimentos não deveriam depender exclusivamente do conhecimento dos desenvolvedores ou de instruções fornecidas manualmente a cada sessão.

Essas informações precisam estar disponíveis no próprio repositório ou em fontes compartilhadas acessíveis aos agentes.

Isso permite que um desenvolvedor recém-integrado ao projeto utilize IA para executar tarefas sem precisar conhecer previamente todas as decisões técnicas do sistema.

O objetivo não é eliminar a necessidade de compreender o código, mas evitar que cada agente precise investigar decisões que já foram tomadas e documentadas.

O conhecimento do projeto deve ser reutilizável, independente do desenvolvedor e do agente utilizado.

2. Estrutura e hierarquia do conhecimento

Concentrar toda a documentação em um único arquivo pode dificultar a manutenção e aumentar a quantidade de informações carregadas desnecessariamente.

Uma abordagem mais eficiente é organizar o contexto em diferentes níveis.

Contexto global

Informações aplicáveis a todo o projeto:

  • Arquitetura geral e organização dos módulos.
  • Linguagens, frameworks e tecnologias.
  • Convenções compartilhadas.
  • Regras de segurança.
  • Restrições arquiteturais.
  • Ferramentas e procedimentos comuns.

Contexto específico

Informações relacionadas a determinadas áreas:

  • Frontend e bibliotecas de interface.
  • Backend, serviços e regras de negócio.
  • Banco de dados e persistência.
  • Infraestrutura e deployment.
  • Integrações externas.
  • Testes e qualidade.

Contexto dos módulos

Documentação de responsabilidades, contratos, decisões e comportamentos específicos de partes do sistema.

Essa organização permite que agentes localizem as informações relevantes para cada tarefa sem precisar carregar todo o conhecimento do projeto.

A hierarquia também facilita a manutenção: uma decisão que afeta todo o sistema deve ser documentada em uma referência compartilhada, enquanto uma convenção específica pode permanecer próxima do módulo correspondente.

3. Contratos, convenções e decisões arquiteturais

A documentação precisa registrar não apenas quais tecnologias são utilizadas, mas também as decisões que determinam como elas devem ser aplicadas.

Saber que um projeto utiliza React e TypeScript, por exemplo, não informa ao agente quais componentes reutilizar, como organizar o gerenciamento de estado ou quais padrões de comunicação com a API foram estabelecidos.

O mesmo acontece no backend: conhecer a linguagem e o framework não é suficiente para identificar onde implementar regras de negócio, quais serviços reutilizar ou como tratar autenticação e erros.

O contexto técnico deve contemplar, conforme a necessidade do projeto:

  • Tecnologias e bibliotecas aprovadas.
  • Estrutura e responsabilidades dos módulos.
  • Padrões de implementação.
  • Contratos de API e schemas.
  • Convenções de nomenclatura.
  • Decisões arquiteturais e suas justificativas.
  • Restrições e soluções que não devem ser utilizadas.

Decisões arquiteturais importantes podem ser registradas em ADRs (Architecture Decision Records) ou documentos equivalentes.

Contratos devem preferencialmente utilizar formatos verificáveis, como OpenAPI, JSON Schema ou definições de tipos compartilhadas.

O agente deve ter autonomia para implementar soluções dentro dos padrões existentes, não para redefinir a arquitetura a cada tarefa.

Quando uma mudança exige alterar uma decisão estabelecida, ela deve passar pelo processo de revisão definido pelo projeto.

4. Fontes de verdade e resolução de conflitos

Um dos principais riscos da documentação utilizada por agentes é a existência de informações contraditórias ou desatualizadas.

Um documento pode determinar o uso de determinada biblioteca enquanto outro recomenda uma alternativa. Um contrato de API pode apresentar campos que já foram modificados. Uma instrução antiga pode orientar um padrão que não é mais utilizado.

Nessas situações, o agente pode seguir uma referência incorreta e produzir alterações incompatíveis com o sistema.

Para reduzir esse problema, é importante estabelecer fontes de verdade para cada categoria de informação.

Por exemplo:

  • Contratos de API mantidos em especificações próprias.
  • Decisões arquiteturais registradas em documentos específicos.
  • Convenções organizadas por área ou módulo.
  • Instruções gerais centralizadas em um ponto de entrada.
  • Requisitos de uma entrega associados ao respectivo ticket.

Sempre que possível, evite duplicar regras. Documentos específicos devem referenciar informações compartilhadas em vez de reproduzi-las.

Também é necessário definir como tratar conflitos.

Uma instrução específica pode complementar uma regra global dentro de seu escopo, mas não deve contradizer uma restrição obrigatória sem uma decisão explícita.

Quando duas fontes apresentam informações incompatíveis e não existe uma regra de precedência válida, o agente deve sinalizar a divergência em vez de escolher arbitrariamente uma delas.

Contexto confiável depende não apenas da disponibilidade das informações, mas também de sua consistência e autoridade.

5. AGENTS.md como ponto de entrada

O arquivo AGENTS.md pode funcionar como ponto de entrada para agentes de desenvolvimento, reunindo instruções gerais e referências para o restante do conhecimento do projeto.

Seu papel não deve ser concentrar toda a documentação técnica.

Ele deve orientar o agente sobre como trabalhar no repositório, quais regras precisam ser respeitadas e onde encontrar informações específicas.

Entre os elementos que podem fazer parte desse arquivo estão:

  • Visão geral da arquitetura e das tecnologias.
  • Localização da documentação técnica.
  • Convenções obrigatórias.
  • Restrições e práticas proibidas.
  • Referências para contratos e schemas.
  • Skills e procedimentos disponíveis.
  • Comandos de validação.
  • Regras para alterações arquiteturais.
  • Procedimentos de atualização do contexto.

Um agente que recebe uma tarefa no frontend, por exemplo, deve conseguir identificar pelo AGENTS.md onde encontrar as instruções de interface, os componentes disponíveis, os contratos de API e os procedimentos de teste.

Isso evita que ele precise explorar indiscriminadamente o repositório para descobrir convenções que já poderiam estar documentadas.

Atualização obrigatória do contexto

Uma regra especialmente importante é estabelecer que alterações no código devem ser acompanhadas da atualização das informações de contexto afetadas.

O AGENTS.md deve orientar o agente a verificar, antes de concluir qualquer implementação, se suas alterações impactaram:

  • Arquitetura ou organização dos módulos.
  • Contratos de API e schemas.
  • Convenções e padrões de implementação.
  • Regras de negócio.
  • Procedimentos operacionais.
  • Instruções e skills existentes.

Quando houver impacto, os documentos correspondentes devem ser atualizados como parte da própria entrega.

Isso inclui revisar ou remover instruções que se tornaram obsoletas e verificar possíveis contradições com outras referências.

Não significa modificar a documentação em toda alteração de código. Significa que toda alteração deve passar por uma verificação de impacto sobre o contexto.

Essa regra também deve fazer parte dos critérios de conclusão das tarefas.

6. Contexto específico por área e tarefa

Depois de identificar as instruções gerais, o agente deve recuperar o conhecimento relacionado à tarefa que vai executar.

Um trabalho no frontend pode exigir contexto sobre componentes, design system, gerenciamento de estado, rotas e contratos de API.

Uma alteração no backend pode precisar de informações sobre serviços, persistência, autenticação e regras de negócio.

Uma operação de infraestrutura pode depender de procedimentos de deployment, configuração de ambientes e restrições de segurança.

Esses conjuntos de informações não precisam ser carregados simultaneamente.

Uma estratégia é manter referências por área ou módulo, permitindo que o agente consulte o contexto correspondente ao identificar o escopo da tarefa.

Também é possível utilizar instruções específicas em diretórios do projeto, dependendo dos recursos oferecidos pela ferramenta de desenvolvimento.

A documentação deve indicar quais informações são obrigatórias para determinadas operações e quais podem ser consultadas conforme a necessidade.

O objetivo é permitir que o agente encontre rapidamente os padrões aplicáveis, sem precisar reconstruí-los por meio de uma análise extensa do código.

Isso não elimina a leitura dos arquivos envolvidos na implementação. O código continua sendo necessário para compreender o estado atual da funcionalidade.

A documentação fornece as decisões e referências; a análise do código fornece o contexto concreto da alteração.

7. Skills e ferramentas como recursos complementares

Skills não são uma estrutura para organizar o contexto do projeto. Elas disponibilizam instruções, procedimentos e recursos especializados para executar determinadas tarefas.

Por exemplo, um agente pode utilizar uma Skill para executar testes em navegador, preparar uma migração ou gerar um artefato em um formato específico. A documentação do projeto, por sua vez, informa quais contratos, padrões e restrições devem ser respeitados durante essas operações.

O AGENTS.md pode indicar as Skills disponíveis, sem reproduzir suas instruções. Quando a ferramenta permitir, o agente carrega a Skill aplicável apenas quando precisar utilizá-la.

Ferramentas e integrações também são complementares: permitem consultar sistemas e executar ações, mas não substituem as fontes de verdade sobre a arquitetura e o comportamento do projeto.

Para aprofundar essa distinção, consulte Harnesses, skills, ferramentas e MCP.

8. Recuperação seletiva e continuidade do contexto

Mesmo com uma estrutura bem organizada, carregar toda a documentação em cada execução pode ser desnecessário.

A engenharia de contexto deve permitir localizar e recuperar as informações relevantes conforme o trabalho avança.

Essa recuperação pode ocorrer por referências diretas, navegação em diretórios, ferramentas de busca ou mecanismos de indexação.

A estratégia depende do tamanho do projeto e da infraestrutura disponível.

Para projetos menores, uma estrutura clara de documentos e arquivos de entrada pode ser suficiente.

Projetos extensos ou distribuídos entre vários repositórios podem se beneficiar de mecanismos adicionais para localizar informações e relacionar documentos.

Continuidade entre sessões

Outro desafio é preservar informações importantes quando uma execução é interrompida, o contexto é compactado ou o trabalho passa para outro agente.

Decisões tomadas, alterações realizadas, problemas encontrados e pendências não devem depender exclusivamente do histórico de uma conversa.

Essas informações podem ser registradas em arquivos de planejamento, estado ou acompanhamento da execução.

É importante, entretanto, separar o conhecimento permanente do projeto das informações temporárias de um trabalho.

Uma decisão arquitetural aprovada pertence ao contexto persistente do sistema.

Já o progresso de uma implementação específica pertence ao contexto daquela execução.

Misturar esses dois tipos de informação pode gerar documentação excessiva e dificultar a identificação das referências que continuam válidas.

9. Abordagens relacionadas de organização e execução

Existem propostas que ajudam a aplicar princípios semelhantes em diferentes partes do trabalho:

  • CHAOS: convenção para estruturar e manter o conhecimento técnico persistente de projetos, incluindo arquitetura, regras, contratos e decisões.
  • Spec-Driven Development (SDD): utiliza especificações como referência para planejar, implementar e validar mudanças.
  • File-System-Based (FSB): utiliza arquivos para manter planos, progresso, checkpoints e outras informações necessárias à continuidade das execuções de agentes.

FSB é usado aqui como uma descrição da persistência em arquivos, não como o nome de uma metodologia padronizada. Arquivos também podem armazenar memória reutilizável e conhecimento permanente; sua finalidade depende do conteúdo e das regras de manutenção.

As abordagens podem coexistir, mas cumprem funções diferentes. O contexto canônico descreve o sistema; as especificações descrevem o que deve ser entregue; os registros de execução acompanham o trabalho em andamento.

Não é necessário adotar nenhuma delas como requisito para organizar o contexto do projeto. O importante é manter referências confiáveis, acessíveis e atualizadas, sem duplicar informações.

10. Exemplo de organização de um repositório

Uma estrutura simples pode reunir um ponto de entrada para agentes e referências técnicas organizadas por área, sem exigir uma convenção específica:

project/
├── README.md
├── AGENTS.md
├── docs/
│   ├── architecture/
│   │   └── overview.md
│   ├── contracts/
│   │   └── openapi.yaml
│   ├── frontend/
│   │   └── guidelines.md
│   └── backend/
│       └── guidelines.md
├── frontend/
├── backend/
└── tests/

Os nomes e diretórios são ilustrativos. Uma organização equivalente pode utilizar documentos existentes, referências externas ou convenções como CHAOS, sem duplicar contratos e regras.

Exemplo: implementação no frontend

Ao receber uma tarefa para desenvolver um componente, o agente pode:

  1. Consultar o AGENTS.md para localizar regras e referências aplicáveis.
  2. Ler a documentação de frontend e os contratos necessários.
  3. Analisar o código existente e implementar a alteração.
  4. Utilizar ferramentas ou Skills específicas quando a tarefa exigir.
  5. Executar testes e verificar se algum documento técnico foi afetado.

Essa sequência é adaptável ao projeto; o essencial é consultar as fontes corretas antes de alterar o sistema.

11. Atualização do contexto durante o desenvolvimento

A documentação tende a perder confiabilidade quando sua manutenção depende de iniciativas ocasionais.

Em projetos com agentes, esse problema pode ser ampliado: uma instrução desatualizada pode ser reutilizada em diversas implementações antes que alguém identifique a divergência.

Por isso, a atualização do contexto deve fazer parte do fluxo normal de desenvolvimento.

Sempre que uma entrega modificar decisões, contratos, comportamentos ou procedimentos documentados, as referências afetadas devem ser atualizadas junto com a implementação.

Essa responsabilidade pode ser estabelecida por meio de instruções persistentes no AGENTS.md, critérios de aceite e verificações durante a revisão de código.

Uma regra prática é:

Nenhuma implementação deve ser considerada concluída sem verificar se o contexto técnico afetado continua correto.

Isso não exige novos documentos para cada alteração. Muitas vezes, basta atualizar uma referência existente.

Também é importante evitar que informações temporárias sejam incorporadas indiscriminadamente à documentação permanente.

Planos descartados, tentativas de implementação e descobertas sem relevância futura não precisam necessariamente fazer parte do conhecimento canônico do projeto.

A atualização deve preservar aquilo que será útil e confiável para os próximos trabalhos.

12. Validação e governança do conhecimento

Manter documentos organizados não garante que suas informações permaneçam corretas.

O contexto também precisa de mecanismos de revisão e validação.

Algumas verificações podem ser automatizadas:

  • Identificação de links e referências inexistentes.
  • Validação de schemas e contratos.
  • Verificação de exemplos e comandos documentados.
  • Detecção de referências a arquivos removidos.
  • Comparação entre contratos e implementações, quando houver ferramentas adequadas.
  • Identificação de documentação afetada por alterações em módulos relevantes.

Outras verificações dependem de revisão técnica, especialmente quando envolvem decisões arquiteturais ou regras de negócio.

Também vale estabelecer responsáveis por documentos ou áreas de conhecimento, particularmente em projetos com múltiplas equipes.

Quando uma alteração modifica uma fonte de verdade, é necessário avaliar quais outras referências dependem dela.

A governança não deve tornar a documentação burocrática. Seu objetivo é preservar a confiabilidade das instruções utilizadas durante o desenvolvimento.

Conclusão

A arquitetura de contexto define como o conhecimento técnico do projeto é organizado e relacionado.

A engenharia de contexto determina como essas informações são localizadas, selecionadas e disponibilizadas aos agentes.

A documentação mantém as decisões, regras, contratos e procedimentos que orientam as implementações.

Com uma estrutura consistente, desenvolvedores de diferentes níveis de experiência podem utilizar agentes de IA sem depender exclusivamente de conhecimento informal ou de longas investigações sobre o funcionamento do sistema.

Abordagens como CHAOS, SDD e FSB podem complementar essa organização em finalidades distintas. Skills e ferramentas apoiam a execução de tarefas, sem substituir a documentação técnica do sistema.

Entretanto, a estrutura só permanece útil quando é atualizada junto com o código e quando existem mecanismos para identificar informações contraditórias ou obsoletas.

O objetivo é transformar o contexto técnico em parte permanente da arquitetura do projeto: organizado, acessível, verificável e continuamente atualizado, para que humanos e agentes trabalhem seguindo os mesmos padrões e decisões.

Leituras relacionadas

Fontes e leituras adicionais