<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.

Validadores
o que confere a saída
Fontes
o que ela lê antes de escrever
Claude Code
o modelo e o que o configura
pedido
o prompt do operador
CLAUDE.md
como se trabalha aqui
specs/
arc42 · C4 · BDD · ADR
changes/
PRD · design · specs · tasks
src/ existente
o código que já está lá
Biome
lint e formatação
check
tipos e contratos
bun test
os *.test.js do tester
husky + lint-staged
o pre-commit
commitlint
a mensagem do commit
CI
os workflows do GitHub
Claude Code
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
Recursos do Claude Code · em .claude/
agents
11 ofícios, cada um na sua janela
skills
52 procedimentos
rules
47 defeitos proibidos
hooks
khaby-lame.sh, antes do Write
commands
/craft /ship /audit /sync /extend
MCPs
ferramentas externas
src/[contexto]/[container]/[componente]/
o código — onde a saída vira arquivo, com o teste ao lado
lê
veredito
escreve
configuram
confere

Fontes

o que ela lê antes de escrever

pedidoCLAUDE.mdspecs/changes/src/ existente
↓ lê

Claude Code

o modelo — prevê o próximo token a partir da janela

Recursos · .claude/

configuram o modelo

agents · 11skills · 52rules · 47hookscommands · 5MCPs
↓ escreve

src/[contexto]/[container]/[componente]/

onde a saída vira arquivo, com o teste ao lado

↓ confere

Validadores

o veredito volta para o modelo

Biomecheckbun testhusky + lint-stagedcommitlintCI

76% → 99%

de cobertura das dependências ocultas quando a estrutura do código é navegável.

Fonte: Paipuru, CodeCompass, 258 ensaios, 2026

4x

mais blocos de código duplicado em 2024. Pela primeira vez, copiar superou mover e reaproveitar.

Fonte: GitClear, 211 mi de linhas, 2025

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.

Fonte: Nagappan et al., Microsoft, ICSE 2008

O agente encontra o que tem nome

Cobertura dos arquivos que importam, por tipo de dependência, em 258 ensaios.

90,0
100,0
88,9
79,7
85,1
76,4
76,2
78,2
99,4

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

agente purobusca por palavraestrutura navegável

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%

Fonte: GitClear, 211 mi de linhas, 2025

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.

C1

Contexto

Uma área do negócio: catálogo, compra, pós-venda.

C2

Container

A fatia vertical: carrinho, checkout, pagamento.

C3

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

components/CampoDeCupom.tsx
hooks/useCupom.ts
services/cupomService.ts
utils/validarCupom.ts
__tests__/cupom.test.ts

Uma mudança na regra abre cinco pastas. O agente acha uma e declara pronto.

Por fatia: o cupom em 1 lugar

src/compra/checkout/cupons/ index.tsaplicar-cupom.tsaplicar-cupom.test.tsuse-cupom.tsCampoDeCupom.tsx

Uma mudança na regra abre uma pasta. Tudo o que importa está no caminho.

01

Co-mudança

O que aparece junto nos commits mora junto.

02

Teste da deleção

Remover uma capacidade é apagar uma pasta.

03

Recém-chegado

Produto lê os nomes sem glossário.

04

Distância

Nada específico sobe; nada comum desce.

05

Sem framework

Troque a tecnologia; nenhuma pasta mente.

O que a IA ganhaPor quêEvidência
Encontra tudo por nomeUma tarefa em linguagem de negócio cai numa pasta com o mesmo nomeBusca cobre 100% quando o nome casa (CodeCompass)
Não corrige só uma cópiaNão existem duas casas para a mesma regraCopiar já supera reaproveitar (GitClear)
Cabe na janelaUma capacidade pequena é lida inteira, não pela metadeContexto longo degrada (Chroma, Liu et al.)
Não sai da fatiaindex.ts é a única API públicaMudança revisável como unidade

Veja o ritmo que conecta tudo

Research, plan, implement e verify — e o que cada tempo lê e escreve.

Ver o fluxo