Capítulo 9 — Repositório intencional: transforme o projeto em ambiente legível

O agente não deveria depender da conversa

Uma conversa é transitória. O repositório deveria sobreviver a ela.

Quando a única forma de explicar um projeto é reconstruir uma sequência de prompts, mensagens e decisões dispersas, o sistema depende de memória informal. Isso cria fragilidade: uma nova sessão pode perder decisões importantes, outro agente pode receber contexto diferente e uma instrução antiga pode continuar circulando depois de ficar obsoleta.

O problema não é apenas falta de documentação. É falta de arquitetura de informação operacional.

A pergunta deste capítulo é:

como fazer o projeto explicar a si mesmo sem exigir uma conversa infinita?

Repositório como parte do sistema

Código não é o único artefato que precisa de engenharia. O ambiente em que o código é modificado também precisa ser projetado.

Para trabalho agêntico, o repositório passa a cumprir pelo menos quatro funções:

1. armazenar o produto;
2. preservar decisões;
3. orientar a execução;
4. fornecer evidência verificável. Isso muda a função de arquivos como README, AGENTS.md, ADRs, scripts, schemas, testes e runbooks. Eles deixam de ser apenas documentação de apoio e passam a compor o ambiente de execução cognitiva do projeto.

Instruções persistentes precisam morar perto da fonte de verdade

García descreve contexto artifacts como arquivos legíveis pelo agente que armazenam orientação durável ligada ao projeto, repositório ou ambiente de trabalho. Exemplos como AGENTS.md e CLAUDE.md podem registrar convenções, comandos, validações, restrições de segurança e expectativas de workflow, evitando repetir a mesma orientação em cada prompt. ¹

A consequência prática é importante. Se uma regra é estável, ela não deveria depender da memória de quem abre a sessão. Ela deve ser recuperável e, quando possível, versionada junto com o sistema que governa.

Exemplos:

• comando oficial de teste;
• política de migrations;
• limites de escrita;
• diretórios proibidos;
• convenções de commit;
• critérios para aceitar uma mudança;
• sequência de validação;
• regra para secrets;
• procedimento de rollback.

A conversa pode apontar para essas regras. Não precisa reinventá-las.

AGENTS.md não é um prompt gigante

Um erro fácil é transformar o arquivo de instruções em um depósito universal. Tudo entra e nada sai.

Depois de algum tempo, o agente recebe regras atuais, regras antigas, exceções locais, comandos duplicados, preferências pessoais, decisões já revogadas e detalhes de tarefas encerradas. Isso recria, dentro do repositório, o mesmo problema do contexto excessivo. No método deste livro, um arquivo persistente deve conter apenas o que merece sobreviver à tarefa.

A pergunta é:

esta instrução ainda será válida quando a sessão atual terminar?

Se a resposta for não, provavelmente ela pertence à Spec, ao Context Pack ou ao Change Episode — não ao AGENTS.md. Persistência é uma escolha de arquitetura.

Hierarquia de instruções

Um repositório legível precisa declarar precedência. Sem isso, duas instruções podem ser verdadeiras isoladamente e incompatíveis juntas.

O método deste livro usa a seguinte ordem operacional:

1. políticas e restrições organizacionais;
2. instruções persistentes do repositório;
3. instruções locais de uma área ou componente;
4. Spec da mudança;
5. contexto transitório da tarefa;
6. pedido interativo atual.

Essa hierarquia é método deste livro. Ela não é apresentada como taxonomia universal. Sua função é permitir que conflitos sejam resolvidos de forma explícita.

Por exemplo: a Spec pode pedir deploy, mas a política do repositório pode proibir deploy automático. O agente deve obedecer ao limite superior e escalar. A ausência de precedência transforma contexto em disputa silenciosa.

Source of truth não é “o arquivo mais completo”

Uma fonte de verdade é a autoridade escolhida para uma classe de informação. Ela pode ser pequena. O importante é que outras representações apontem para ela em vez de competirem com ela. Exemplos no nosso método:

• regras de domínio → DOMAIN.md ou modelo canônico equivalente;
• arquitetura → ADRs e documentação arquitetural;
• mudança → SPEC.md;
• instruções persistentes → AGENTS.md;
• estado de entrega → telemetria e status canônico;
• evidência longitudinal → Change Episode;
• claims editoriais → Claim Ledger.

O objetivo é evitar dois documentos igualmente plausíveis descrevendo estados diferentes.

Duplicação de informação não é sempre erro. Duplicação de autoridade quase sempre é risco.

Documentação perto do código

“Perto” não significa necessariamente no mesmo diretório. Significa perto o suficiente para que a relação seja encontrável e mantida.

Uma API pode ter schema, testes de contrato, exemplos, instruções de geração, runbook e política de compatibilidade. Se esses artefatos vivem em lugares sem conexão explícita, o agente precisa adivinhar a relação.

Um repositório intencional cria ponteiros. Pode usar links relativos, índices, manifests, metadados, nomes previsíveis, scripts de descoberta e validações de drift.

A legibilidade não depende de colocar tudo no README. Depende de tornar a estrutura navegável.

Exemplos executáveis são documentação verificável

Texto explica intenção. Um exemplo executável também produz comportamento observável.

Por isso, quando uma regra puder ser expressa por teste, fixture, script, schema, comando reproduzível ou health check, o projeto ganha uma forma de documentação que pode falhar quando deixa de corresponder à realidade. Isso não elimina documentação narrativa. Complementa-a com evidência mecânica.

Skills como procedimentos versionados

Uma skill é útil quando existe um procedimento recorrente que merece ser reutilizado.

No método deste livro, uma skill pode empacotar objetivo, pré-condições, sequência de ações, ferramentas permitidas, checks, critérios de parada, escalonamento e formato de saída.

A skill não deve esconder a fonte de verdade. Ela deve apontar para ela.

Se o procedimento de deploy depende de compose, health endpoint e política de aprovação, a skill deve referenciar esses artefatos, não copiar uma versão congelada deles para dentro do próprio texto. Caso contrário, surge drift.

Memória operacional não é chat arquivado

Memória operacional é informação que continua útil porque influencia decisões futuras.

Exemplos:

• uma incompatibilidade conhecida;
• um runbook validado;
• uma decisão arquitetural;
• um incidente com consequência recorrente;
• uma restrição de infraestrutura.

O histórico bruto pode ser evidência, mas não deve automaticamente virar instrução.

No nosso método, a promoção de informação transitória para memória persistente exige uma pergunta:

qual decisão futura esta informação melhora?

Se não houver resposta, ela pode permanecer apenas como registro.

Evite documentação órfã

Documentação órfã é aquela que existe, mas não participa de nenhum fluxo. Ninguém sabe quem mantém, quando atualizar, o que ela governa, qual sistema a consome ou se ainda é confiável.

Uma forma de combater isso é associar cada artefato a pelo menos um destes elementos:

• owner;
• consumer;
• trigger de atualização;
• validação;
• source of truth;
• lifecycle.

Exemplo para AGENTS.md:

• consumer: agentes e desenvolvedores;
• trigger: mudança de workflow, tooling ou política;
• validação: revisão + CI quando possível;
• source of truth: repositório.

Repository Context Pack

O artefato operacional deste capítulo é o Repository Context Pack.

Ele não é um arquivo gigante. É um mapa legível do ambiente.

Estrutura sugerida:

Repository Context Pack
├── Identity
├── Source of Truth Map
├── Persistent Instructions
├── Architecture Pointers
├── Commands
├── Validation
├── Tools & Permissions
├── Operational Surfaces
├── Recovery
└── Update Triggers

Identity

Nome, propósito e limites do repositório.

Source of Truth Map

Qual artefato é autoridade para domínio, arquitetura, especificação, delivery, evidência e operação.

Persistent Instructions

Ponteiro para AGENTS.md, skills e políticas locais.

Commands

Comandos canônicos para instalar, testar, validar, executar, empacotar e inspecionar saúde.

Validation

Quais gates provam que uma mudança está pronta.

Tools & Permissions

Quais superfícies existem e quais exigem confirmação.

Operational Surfaces

Onde encontrar logs, métricas, estado de CI e status de deploy.

Recovery

Como voltar para um estado conhecido.

Update Triggers

Quais mudanças obrigam atualizar o pack.

O pack é um índice. As fontes continuam sendo as fontes.

Machine-readable quando houver valor

Nem toda documentação precisa virar JSON. Mas alguns contratos ficam mais úteis quando também possuem uma representação legível por máquina.

Exemplos: manifests, schemas, status contracts, inventories, ownership maps e capability declarations.

O critério não é “agentes gostam de JSON”. O critério é:

há alguma verificação, descoberta ou automação que fica mais confiável com estrutura explícita?

Se sim, uma representação estruturada pode valer o custo. O texto continua útil para intenção e explicação; a estrutura ajuda a execução e validação.

Repositório legível também precisa ser pequeno o suficiente

Legibilidade não aumenta com a quantidade de arquivos. Um repositório com centenas de documentos sem hierarquia pode ser menos legível que um com poucos artefatos bem conectados.

Por isso, organização precisa incluir poda.

Perguntas de manutenção:

• este documento ainda governa algo?
• existe fonte mais autoritativa?
• há duplicação?
• há link quebrado?
• existe owner?
• existe consumidor?
• há instrução revogada?
• o arquivo aparece no Context Pack?
• o agente precisa realmente lê-lo?

A mesma disciplina usada para código deve ser aplicada ao contexto persistente.

Falha típica: instrução válida, lugar errado

Imagine uma regra temporária: “durante esta migração, não execute writes em produção.”

Ela é crítica, mas não precisa viver para sempre no AGENTS.md. Se persistir depois da migração, pode bloquear trabalho legítimo.

O lugar correto pode ser Spec, runbook da migração, Change Episode ou gate temporário. A qualidade do contexto depende também do lifecycle.

Persistir tudo é outra forma de esquecer.

Falha típica: documentação correta, descoberta impossível

Outro problema aparece quando a documentação está certa, mas ninguém encontra.

Isso acontece quando o nome é imprevisível, não existe índice, o README não aponta, a estrutura muda sem atualização ou o agente recebe apenas uma subpasta sem saber das regras superiores.

A solução não é necessariamente adicionar mais texto. Pode ser criar melhor navegação.

No método deste livro, cada repositório deveria oferecer uma rota curta para responder:

1. o que é este sistema?
2. onde estão as regras?
3. onde está a arquitetura?
4. como testar?
5. como saber se está saudável?
6. quais ações são proibidas?
7. como recuperar?

Se essas respostas exigem arqueologia, o ambiente ainda não está pronto para delegação confiável.

Do ambiente legível à superfície de ação

Um repositório intencional resolve o problema de descoberta: torna regras, comandos, ownership e procedimentos encontráveis sem depender da conversa.

Ele não resolve autoridade.

Saber que existe um banco não significa poder escrever nele; conhecer o processo de deploy não significa poder promover uma release; conhecer o nome de um secret não significa poder lê-lo.

O próximo capítulo separa essas duas dimensões:

• legibilidade — o que o agente consegue descobrir e compreender;
• capability — o que o agente está autorizado a fazer.

Essa passagem evita um erro perigoso: transformar contexto disponível em permissão implícita.

Fronteira de confiança

Arquivos persistentes podem alterar comportamento de agentes por longos períodos. Mudanças em AGENTS.md, skills, runbooks, manifests e políticas devem ter autoria rastreável, precedência definida e revisão compatível com o impacto. Conteúdo externo não deve ganhar autoridade apenas por estar dentro do repositório.

Evidência exigida

Uma instrução persistente deve apontar para evidência verificável quando governa comportamento técnico: comandos executáveis, testes, schemas, CI, health checks ou artefatos canônicos. O Repository Context Pack deve permitir reconstruir por que determinada regra existe e qual fonte a sustenta.

Rollback e recuperação

Contexto persistente precisa ser reversível. Instruções versionadas, skills e documentos operacionais devem poder retornar a um estado conhecido quando uma alteração causar comportamento incorreto. O rollback deve restaurar tanto o código quanto o ambiente de orientação que governa a mudança.

Proveniência das fontes

Rastreabilidade deste capítulo:

• CLM-037 — García, contexto artifacts como orientação durável ligada ao projeto/repositório, incluindo AGENTS.md/CLAUDE.md, convenções, comandos, validações, segurança e workflows.

A hierarquia de instruções, o Repository Context Pack, o mapa de source of truth e os critérios de lifecycle apresentados neste capítulo são método deste livro.

O comparável de Jayaratchagan aparece apenas como fonte limitada no mapa competitivo e não foi usado como autoridade factual.

Fontes de acesso limitado não foram usadas como autoridade factual neste capítulo.

Recursos complementares

Recursos relacionados:

• Repository Context Pack;
• AGENTS.md template;
• Source of Truth Map;
• Artifact Library;
• Context Pack Builder;
• futura checagem de documentação órfã;
• futura validação de drift entre instruções persistentes e artefatos executáveis.

---

Footnotes

1. Boni García, Context Engineering (MEAP, 2026), 1.5.1 Instructions / 1.5.2 External knowledge, p. 27. Rastreabilidade interna: CLM-037. ↩