<omh-codigo-src />
Uma base de código que a IA consegue navegar.
O agente não tem anos de casa — tem uma janela de contexto. Ele encontra por nome e segue o caminho que está na frente dele. A estrutura de pastas é a primeira documentação que ele lê.
// Onde você está no harness
Esta página explica o código
Onde a saída vira arquivo — e por que a organização das pastas muda o que o modelo encontra.
o prompt do operador
como se trabalha aqui
arc42 · C4 · BDD · ADR
PRD · design · specs · tasks
o código que já está lá
lint e formatação
tipos e contratos
os *.test.js do tester
o pre-commit
a mensagem do commit
os workflows do GitHub
o modelo — prevê o próximo token a partir da janela
tudo em volta decide o que entra na janela e o que sai dela
11 ofícios, cada um na sua janela
52 procedimentos
47 defeitos proibidos
khaby-lame.sh, antes do Write
/craft /ship /audit /sync /extend
ferramentas externas
o código — onde a saída vira arquivo, com o teste ao lado
Fontes
o que ela lê antes de escrever
Claude Code
o modelo — prevê o próximo token a partir da janela
Recursos · .claude/
configuram o modelo
src/[contexto]/[container]/[componente]/
onde a saída vira arquivo, com o teste ao lado
Validadores
o veredito volta para o modelo
76% → 99%
de cobertura das dependências ocultas quando a estrutura do código é navegável.
4x
mais blocos de código duplicado em 2024. Pela primeira vez, copiar superou mover e reaproveitar.
60%
das perguntas sobre uma mudança são respondidas pelo próprio código. Resumos respondem 9%.
Fonte: Sam-Bodden, arXiv 2026
87%
de precisão ao prever falhas pela estrutura da organização — melhor que métricas de código.
O agente encontra o que tem nome
Cobertura dos arquivos que importam, por tipo de dependência, em 258 ensaios.
G1 · nomeável
o nome casa com a tarefa
G2 · via imports
segue a cadeia de dependências
G3 · oculta
sem relação com o nome
Fonte: Paipuru, CodeCompass, 2026
Copiar virou o padrão
Parcela das linhas alteradas em cada ano.
Código copiado e colado
2021
8,3%
2024
12,3%
Refatoração
2021
25%
2024
<10%
Hierarquias de pastas, convenções de nome e datas dão sinais importantes para humanos e agentes.
Anthropic Engineering, Effective context engineering for AI agents (tradução livre)
// src/[contexto]/[container]/[componente]/
O C4 vira pasta
Os mesmos três níveis que specs/c4/ desenha organizam o código. O primeiro nível já é negócio — não existe hooks/, services/ ou utils/. Cada nível é um zoom da mesma história.
Contexto
Uma área do negócio: catálogo, compra, pós-venda.
Container
A fatia vertical: carrinho, checkout, pagamento.
Componente
Uma responsabilidade: cupons, cálculo do total.
src/
├── catalogo/
│ ├── vitrine/
│ └── produto/
├── compra/
│ ├── carrinho/
│ ├── checkout/
│ │ ├── calculo-do-total/
│ │ └── cupons/
│ │ ├── README.md
│ │ ├── index.ts
│ │ ├── cupom.ts
│ │ ├── cupom.schema.ts
│ │ ├── aplicar-cupom.ts
│ │ ├── aplicar-cupom.test.ts
│ │ ├── cupons.feature
│ │ ├── use-cupom.ts
│ │ ├── CampoDeCupom.tsx
│ │ └── CampoDeCupom.test.tsx
│ └── pagamento/
└── pos-venda/
├── pedidos/
└── entrega/
// Vertical slice + colocation
O que muda junto, mora junto
Uma capacidade inteira numa pasta, com o nome que produto usa. Para o agente, é a diferença entre adivinhar onde mexer e ir direto ao lugar.
Por camada técnica: o cupom em 5 lugares
Uma mudança na regra abre cinco pastas. O agente acha uma e declara pronto.
Por fatia: o cupom em 1 lugar
Uma mudança na regra abre uma pasta. Tudo o que importa está no caminho.
Co-mudança
O que aparece junto nos commits mora junto.
Teste da deleção
Remover uma capacidade é apagar uma pasta.
Recém-chegado
Produto lê os nomes sem glossário.
Distância
Nada específico sobe; nada comum desce.
Sem framework
Troque a tecnologia; nenhuma pasta mente.
| O que a IA ganha | Por quê | Evidência |
|---|---|---|
| Encontra tudo por nome | Uma tarefa em linguagem de negócio cai numa pasta com o mesmo nome | Busca cobre 100% quando o nome casa (CodeCompass) |
| Não corrige só uma cópia | Não existem duas casas para a mesma regra | Copiar já supera reaproveitar (GitClear) |
| Cabe na janela | Uma capacidade pequena é lida inteira, não pela metade | Contexto longo degrada (Chroma, Liu et al.) |
| Não sai da fatia | index.ts é a única API pública | Mudança revisável como unidade |
Veja o ritmo que conecta tudo
Research, plan, implement e verify — e o que cada tempo lê e escreve.