lglucas Codemap
Antes de procurar, leia o mapa
Se você está prestes a varrer o projeto atrás de um arquivo — pare e leia o CODEMAP.md primeiro. É uma leitura contra dezenas. É literalmente para isso que ele existe.
Se o arquivo não existir, verifique o marcador .aios-self antes de estranhar: dentro do repositório do próprio AI Dev OS não há mapa por design (veja Escopo), e nesse caso procurar direto é o certo. Em projeto derivado, mapa ausente significa que ninguém rodou o gerador ainda — rode.
Se o mapa existe mas não responde, aí sim procure. E quando achar, considere se a descrição daquele arquivo estava ruim: o conserto é melhorar o cabeçalho Purpose: dele.
Regenerar
node scripts/codemap.js
Sobrescreve o CODEMAP.md inteiro. Nunca edite o arquivo à mão — a próxima geração desfaz.
Para verificar sem escrever, como o CI faz:
node scripts/codemap.js --check
Quando regenerar
| Momento | Por quê |
|---|---|
| Criou, removeu, renomeou ou moveu arquivo de código | a lista fica errada na hora |
Mudou o Purpose: de um arquivo |
a descrição no mapa fica velha |
| Mudou o número de linhas de um arquivo | o mapa grava a contagem exata |
| Ao fechar sprint | sprint-management já toca changelog e docs; o mapa vai junto |
| Antes de release | release-check delega para cá |
| Depois de refatoração que moveu arquivos | é quando o mapa mais diverge |
A terceira linha é a que pega desprevenido: como o mapa grava a contagem exata, editar o corpo de um arquivo já mapeado costuma bastar para o --check acusar divergência. Regenere junto com a mudança e comite os dois — é mais barato que descobrir pelo CI vermelho.
O limite de 200 linhas continua sendo só um aviso no mapa, não o gatilho da regeneração. O gatilho é a contagem mudar, qualquer que seja o valor.
De onde vem a descrição
Do cabeçalho que a code-style já exige:
/**
* Purpose: o que este arquivo resolve, em uma frase.
* Version: v0.1.0
* Sprint: 01
*/
Ordem de fallback: Purpose: → primeira frase do bloco de comentário → primeiro comentário de linha → ⚠️ sem cabeçalho.
Esse último caso é intencional. Arquivo sem cabeçalho aparece marcado no mapa, ou seja, o codemap acaba fiscalizando a regra de cabeçalho como efeito colateral. Se a descrição de um arquivo ficou ruim, o defeito está no cabeçalho, não no script.
Os dois avisos que o mapa emite
- Acima de 200 linhas — a
code-stylepede "under 200 where practical". O mapa lista quem passou, para você decidir se separa ou aceita. - Sem cabeçalho
Purpose:— cada um é uma linha ruim no mapa.
Nenhum dos dois bloqueia. O que bloqueia é o mapa estar desatualizado.
Por que isso importa mais do que parece
Arquivo curto e mapa de uma linha por arquivo servem à mesma coisa: menos token lido por tarefa. Sem o mapa, a IA abre dez arquivos para achar um. Com o mapa, abre um.
É por isso que o CI falha quando ele diverge. Codemap desatualizado é pior que nenhum — a IA confia, pula a leitura, e age sobre informação errada.
Escopo
Mapeia o código do projeto derivado. Dentro do repositório do AI Dev OS o script se desliga e sai com 0: o OS entrega a maquinaria, o projeto é que tem o código.
Related
- Script:
scripts/codemap.js - Regra:
codemap· par comcode-style - Fecha sprint com:
sprint-management - Gate de release:
release-check