# Codemap

> Mantém o CODEMAP.md — o índice de todo arquivo de código do projeto com uma linha sobre o núcleo de cada um, para achar arquivo sem ler o repositório inteiro. Regenere sempre que a lista, a descrição ou a contagem de linhas mudar — na prática, junto com qualquer edição de código —, ao fechar sprint e antes de release. Use quando o usuário disser "onde fica o arquivo de X?", "que arquivos mexem com Y?", "atualiza o mapa", "cadê o código que faz isso?" — ou quando você mesmo estiver prestes a varrer o repo procurando alguma coisa.

- Skill: `lglucas/codemap` (Agent Skill)
- Install (CLI): `npx skillmds@latest add lglucas/codemap`
- Raw SKILL.md: https://api.skillmd.com/api/skills/lglucas/codemap/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: lglucas (https://skillmd.com/u/lglucas)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/lglucas/codemap

---


# 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](#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

```bash
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:

```bash
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`](../../rules/code-style.md) já exige:

```js
/**
 * 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`](../../rules/codemap.md) · par com [`code-style`](../../rules/code-style.md)
- Fecha sprint com: [`sprint-management`](../sprint-management/SKILL.md)
- Gate de release: [`release-check`](../release-check/SKILL.md)