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

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-style pede "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 com code-style
• Fecha sprint com: sprint-management
• Gate de release: release-check