Prefixer: escopo primeiro, amplie ao errar, registre o delta
Um agente que pesquisa o repositório inteiro paga por cada resultado irrelevante em tokens. Um mapa de namespaces, uma dúzia de linhas dizendo o que vive onde, permite que ele pesquise dentro da área certa desde a primeira chamada. Este skill constrói esse mapa, mantém-no atualizado e obriga o agente a pesquisar com escopo primeiro. Ele faz um trabalho: busca de código mais barata e melhor.
Limite de tamanho. Abaixo de aproximadamente cem arquivos, ou quando a estrutura do repositório é óbvia à primeira vista, pule o mapa e defina o escopo por nomes de diretório; o mapa passa a ser útil a partir desse ponto.
Como trabalhar
- Oriente-se uma vez. Verifique se existe
.prefixer/namespaces.md. Se não existir e a tarefa exigir mais de duas buscas, mapeie o segmento em que você está trabalhando (§1 a §3) e então pesquise dentro dele. Se um mapa existir, leia-o e comece com escopo. - Pesquise com escopo, amplie ao errar. A primeira busca vai para o namespace mais restrito plausível, não para a raiz do repositório (§4 a §6).
- Registre. Termine a tarefa com uma linha em
.prefixer/metrics.jsonl, e um delta quando existir uma linha de base (§7 a §8). Saída obrigatória, não opcional.
Onde ele se paga
- Primeira sessão em um repositório grande ou desconhecido. Leia doze linhas do mapa em vez de escanear a árvore; a primeira busca já é com escopo.
- Monorepos. Um namespace por pacote: as buscas param de puxar ruído de pacotes irmãos para o contexto.
- Múltiplos codebases. Um mapa de nível organizacional escolhe o codebase, o mapa do repositório escolhe o namespace dentro dele. Dois níveis, nunca uma varredura de união.
- Exploração repetida. "Onde fica X", refatorações, áreas de funcionalidades desconhecidas; a taxa de acerto na primeira tentativa é onde o mapa se paga.
- Repositórios que você revisitara. O mapa persiste entre sessões; todo agente futuro começa orientado em vez de reescanear.
A. O mapa de namespaces
1. Mapeie o segmento, não o mundo
Regra: Quando um repositório não tem .prefixer/namespaces.md e o trabalho precisa de mais de duas buscas, mapeie a parte do repositório que esta tarefa toca: três a cinco namespaces; não a árvore inteira. Um mapa parcial que define escopo para as buscas de hoje é melhor do que um mapa completo que levou uma hora. Cresça-o quando uma busca real cair fora dele, nunca em antecipação. Execute bash scripts/init_namespaces.sh (no diretório deste skill) para obter um esqueleto, depois corrija seus palpites: nomeie para que serve cada namespace.
Por que: a adoção é incremental por design. O mapa é um arquivo de trabalho, não um censo; ele ganha uma linha quando uma busca precisa daquela linha.
Rascunhos não são mapas. Qualquer linha cujo prefixo ou contains ainda diga TODO está inacabada; termine-a ou corte-a antes de confiar no mapa. O esqueleto informa quantas linhas de rascunho restam.
Documentos existentes primeiro. Se AGENTS.md, CLAUDE.md ou o README já descrevem a estrutura, preencha contains a partir deles (o esqueleto faz isso) e trate namespaces.md como canônico para escopo de busca; não mantenha duas tabelas de conteúdo divergentes.
Início de sessão supera memorização. Ler o mapa uma vez por sessão é a etapa mais provável de ser pulada. Se o mecanismo de execução puder injetar arquivos no início da sessão, faça-o emitir namespaces.md: toda busca então começa com escopo, sem necessidade de disciplina. Conexão fornecida: scripts/install_hook.sh escreve o hook para você (scripts/session_start.sh emite o mapa mais um veredito de saúde); trechos manuais estão em integrations/. Receita e fundamentação: references/namespaces.md.
2. Mantenha-o pequeno e baseado em globs
Regra: 5 a 12 namespaces. Cada linha é um prefixo curto, um glob de caminho e uma finalidade de uma linha escrita para desambiguação. Se duas linhas corresponderem à mesma busca com igual frequência, mescle-as. Se uma linha nunca define escopo para uma busca real, corte-a.
Formato:
# namespaces
repo: acme-payments
| prefix | scope | contains |
|--------|--------------------|-----------------------------|
| api: | src/api/** | Manipuladores REST, rotas |
| auth: | src/auth/** | login, sessões, tokens |
| sso: | src/auth/sso/** | Área da subequipe SSO |
| test: | tests/**, **/*.test.* | Suítes, fixtures |
O cabeçalho repo: é o qualificador único deste codebase (a partir do remoto git); ele torna cada prefixo globalmente único quando uma organização executa muitos codebases: acme-payments:auth: nunca pode colidir com checkout-service:auth:.
As linhas aninham: uma linha recuada pertence ao namespace acima dela, para subequipes dentro de um módulo ou pacotes dentro de um serviço. A tag se compõe, auth:sso:, para que o mesmo nome sob dois pais permaneça distinto (orders:checkout: vs payments:checkout:).
Nomes são derivados, não declarados. Prefixos e texto contains vêm do vocabulário do próprio codebase: nomes de diretório, os termos dominantes nos arquivos que uma linha define escopo, nunca de categorias que você inventa. Nomes derivados acompanham o repositório conforme ele evolui; inventados derivam. O esqueleto faz isso por você: corrija o que ele erra, mantenha o que acertou.
Detalhes do formato e mapas para outras formas de repositório: references/namespaces.md.
3. Atualize, nunca regenere
Regra: Quando o mapa estiver desatualizado, edite as linhas desatualizadas. Não reescreva o arquivo. A regeneração em massa perde o detalhe acumulado que o tornou útil. Pode linhas mortas, adicione as que faltam, mantenha o resto byte-idêntico; um mapa reescrito também quebra o prefixo do cache de prompt de toda sessão que o carregou. Após a curadoria, execute bash scripts/check_namespaces.sh: uma linha cujos glogs não resolvem para nada é uma mentira que o mapa está contando para toda sessão futura. Quando o mapa parecer desatualizado ou o log tiver crescido, execute bash scripts/suggest_map.sh: ele lê metrics.jsonl e a árvore e propõe as linhas que as buscas reais já solicitaram.
Muitos codebases: o mesmo truque se acumula. Um mapa de nível organizacional escolhe o codebase (pay: services/payments/**), o mapa do repositório escolhe o namespace dentro dele. Cada cabeçalho repo: do mapa mantém prefixos únicos entre codebases; quarenta serviços podem todos ter um auth/ porque uma tag qualificada payments:auth: nomeia exatamente um. Nunca una todo repositório em uma busca que é a falha do grep raiz em escala organizacional. Veja references/namespaces.md.
B. Escopo de busca
4. Mais restrito primeiro
Regra: Toda busca começa no namespace mais restrito que poderia conter a resposta. grep "expire" src/auth/ vence grep "expire" .. Um erro custa uma chamada; uma busca ampla custa toda a lista de resultados em tokens.
Deixe o script carregar a regra: bash scripts/search.sh auth "expire" resolve a tag para seus globs, pesquisa dentro deles, amplia um nível em caso de erro e registra a linha de métricas; §4 a §8 são executados sozinhos. --scope <ns> imprime a lista de globs, --paths <ns> os arquivos resolvidos, --list todas as tags; o mapa como um índice que outros comandos podem consultar.
Cuidado com: pesquisar a raiz do repositório "só por garantia", padrões glob como **/* sem restrição de caminho, find usado onde um glob de namespace resolveria.
5. Amplie um nível ao errar
Regra: Errou dentro de um namespace? Amplie um nível: namespace, então sua área pai, então o repositório, então diretórios de terceiros e gerados. Não pule de um erro direto para uma varredura de repositório inteiro, e não pesquise node_modules, vendor, dist, build ou arquivos de bloqueio a menos que a tarefa seja sobre eles.
6. Responda com tags de namespace
Regra: Relate descobertas como prefix:path:line (auth:src/auth/session.ts:42). A próxima busca, sua ou de uma sessão futura, então começa já com escopo. Quando um arquivo resistir a todos os namespaces, isso é sinal de que o mapa tem uma lacuna; mencione-o em vez de inventar uma tag.
C. Rastreamento
7. Linha de base antes de afirmações
Regra: Antes de recomendar mudanças na busca, conte o comportamento atual: buscas por tarefa, chamadas de ferramenta por tarefa, taxa de acerto na primeira tentativa. Sem uma linha de base não há delta, apenas uma história. Registre uma executando uma sonda fixa: bash scripts/measure_search.sh --baseline orientation -- grep -rn "TODO" . na raiz do repositório, ou contando as primeiras tarefas antes da existência do mapa. Veja references/metrics.md para o que registrar e como pontuar.
8. Registre toda tarefa
Regra: Acrescente uma linha JSON a .prefixer/metrics.jsonl ao final de cada tarefa:
{"ts":"2026-10-26T14:03:11Z","task":"find-session-expiry","searches":3,"tool_calls":4,"first_try_hit":true,"est_tokens":1400}
est_tokens é chars/4, uma estimativa; mantenha o campo mesmo quando não puder medir exatamente. Ao final da sessão, reporte o delta contra a linha de base. scripts/measure_search.sh envolve uma busca e registra uma linha por busca na raiz do repositório (hits, scope; --baseline marca a sonda, --hit|--miss registra first_try_hit). Linhas de tarefa escritas à mão adicionam tool_calls e first_try_hit. Um esquema, campos opcionais; references/metrics.md os lista. scripts/report_metrics.sh lê o log de volta: taxa de acerto, gasto por escopo, delta com escopo versus linha de base.
Manuseio com Git. Faça commit de namespaces.md: é o prefixo compartilhado do qual toda sessão futura se beneficia. metrics.jsonl é telemetria local; o esqueleto escreve um .prefixer/.gitignore para ele. Faça commit apenas se a equipe quiser dados de tendência.
Bandeiras vermelhas
Esses pensamentos significam pare. Você está racionalizando.
| Pensamento | Realidade |
|---|---|
| "Um grep amplo não vai doer" | O grep amplo é o custo que este skill existe para remover. Escope-o. |
| "Eu sei onde provavelmente está" | Verifique no namespace. Um palpite errado custa mais do que uma verificação com escopo. |
| "Mapeie o repositório inteiro primeiro" | Mapeie o segmento em que você está. O resto ganha linhas quando as buscas precisarem delas. |
| "O mapa é exagero para esta tarefa" | Um mapa parcial ainda se paga na terceira busca. |
| "Pule a linha de base, apenas aplique" | Sem linha de base não há evidência. Meça primeiro. |
| "Vou regenerar o mapa inteiro, é mais rápido" | Regeneração descarta detalhes curados e quebra o cache. Edite as linhas desatualizadas. |
| "Um mapa esqueleto conta" | Um mapa cheio de linhas TODO é um rascunho, não um mapa. Termine ou corte-os. |
| "Pesquise diretórios vendor para ser completo" | Código gerado é onde os tokens vão morrer. Pesquise-o apenas quando for o assunto. |
Quando não prefixar
- Scripts de arquivo único e repositórios descartáveis: não há nada para escopar.
- Tarefas com um arquivo óbvio: abra-o, não construa infraestrutura para ele.
- Quando o caminho já diz: uma busca dentro de
src/auth/não precisa de cerimôniaauth:em torno dela. - Código de terceiros ou gerado, a menos que seja o assunto da tarefa.
- Repositórios com menos de ~100 arquivos cuja estrutura é óbvia: defina escopo por nomes de diretório e pule o mapa.
Referências
references/namespaces.md: formato do mapa, formas de repositório, empilhamento multi-repositórioreferences/metrics.md: definições de métricas, esquema JSONL, relatório de deltascripts/init_namespaces.sh: criar esqueleto de mapa de namespace para o repositório atualscripts/check_namespaces.sh: lint em um mapa: escopos mortos, tags duplicadas, rascunhosscripts/search.sh: busca com escopo como comando: resolver, pesquisar, ampliar, registrarscripts/suggest_map.sh: ler o log + a árvore, propor edições no mapascripts/measure_search.sh: executar uma busca e registrá-la em uma etapascripts/report_metrics.sh: ler o log de volta: taxa de acerto, gasto de escopo, deltascripts/session_start.sh: emitir o mapa (+ saúde) para hooks de início de sessãoscripts/install_hook.sh: conectar o hook SessionStart para devin/claudescripts/doctor.sh: verificar saúde da configuração de um repositório: mapa, lint, hook, selos de instalaçãoscripts/eval_scope.sh: medir o delta de tokens de uma busca com escopo versus raizscripts/eval_repo.sh: lint + avaliar cada namespace em um mapa, média % economizadascripts/visualize.py: renderizar o mapa na árvore de arquivos + as economias medidas como um relatório HTMLSPEC.md: o contrato de formato namespaces.md, para ferramentas que leem ou escrevem mapasintegrations/: trechos de hook de início de sessão + um workflow de lint de PR para repositórios consumidores
Manuais adjacentes mantidos para autores de pipeline e prompt (fora do trabalho principal deste skill): references/index-prefixes.md, references/prefix-library.md, references/cache-ordering.md.