doc-subcontext
doc-subcontext é a skill que resolve o problema de
escala apontado pela Anthropic em “How Claude Code Works in
Large Codebases”: um único CLAUDE.md no topo não carrega
contexto suficiente para um monorepo grande, mas copiar o
contexto inteiro em cada subdiretório produz N cópias que vão
divergindo.
A skill escreve um sub-context — um pequeno CLAUDE.md dentro
de um subdiretório específico que herda da cadeia pai e
captura apenas o que é único ao seu escopo.
Por que herdar em vez de duplicar
Um CLAUDE.md por módulo, feito de forma ingênua, repete
convenções de projeto (estratégia de testes, nomenclatura de
branch, formato de commit) em cada diretório. Assim que uma
dessas convenções muda, os sub-contexts divergem — alguns são
atualizados, outros não, e o agent acaba recebendo orientações
conflitantes dependendo do caminho em que está trabalhando.
Herdar resolve isso: cada sub-context começa com “herda de
../CLAUDE.md” como um ponteiro explícito, e inclui apenas o
que é único ao diretório. Quando uma convenção do projeto muda,
o pai é atualizado; os sub-contexts não precisam saber.
A disciplina da skill
Quando invocada para um subdiretório, a skill:
- Lê a cadeia pai (este diretório → pai → … →
CLAUDE.mdraiz) e mostra ao usuário o que já está herdado. - Pergunta apenas sobre convenções únicas deste subdiretório. Se a resposta de uma pergunta é a mesma do pai, ela não é feita.
- Escreve o sub-context com uma seção
## Inherits fromno topo apontando para../CLAUDE.md, seguida de um pequeno conjunto de seções específicas do subdiretório. - Mira em 50–100 linhas. Se o sub-context crescer além disso, a skill sugere dividir mais ou empurrar conteúdo comum para o pai.
O que entra em um sub-context
Bons candidatos:
- O vocabulário de domínio deste módulo (quando difere do vocabulário mais amplo do projeto)
- Arquivos que um agent deve sempre abrir primeiro ao trabalhar neste diretório
- Anti-padrões específicos do módulo (“não acesse
../../core/diretamente — use a API pública em../core/index.ts”) - Convenções de teste por módulo, se divergirem das do projeto
Maus candidatos (estes pertencem ao CLAUDE.md raiz):
- Estilo de código do projeto inteiro
- Convenções de commit
- Qualquer coisa que se aplique a mais de um módulo
Quando NÃO escrever um sub-context
Se tudo o que o agent precisa saber sobre um diretório já está no pai, não escreva um sub-context — o arquivo vazio é pior do que nenhum arquivo, porque sugere que existe algo específico do diretório quando não existe. A skill se recusa a escrever um sub-context que consistiria apenas em “herda do pai”.