Criando um Mapa de Código Interativo com Codex

Criando um Mapa de Código Interativo com Codex

Solicite ao Codex que crie um mapa interativo do seu repositório e marque quais módulos foram alterados desde a sua geração.

Ao clicar em qualquer módulo, você pode visualizar seus componentes chamadores, dependências, principais fluxos de execução, testes relacionados e dados de suporte do código-fonte.

O Codex gera:

• docs/codemap/codemap.html
• docs/codemap/codemap.json
• docs/codemap/codemap.lock

Prompt Completo

Analise a base de código atual. Não modifique o código do produto. Crie ou atualize apenas arquivos sob docs/codemap/.

Ignore diretórios de vendor, build, dist, cache e outros gerados.

Se docs/codemap/ já existir, compare primeiro o codemap.lock existente com o repositório atual e liste os módulos que mudaram. Em seguida, regenere estes três arquivos juntos:

1. docs/codemap/codemap.html
   Construa um mapa de código interativo totalmente autossuficiente que abre diretamente em um navegador. Inclua:

   • Módulos principais, serviços, bancos de dados, filas e dependências externas
   • Não mais que 20 nós primários; agrupe arquivos de baixo nível sob seu módulo pai
   • Chamadas e fluxos de dados entre módulos
   • Os 3-5 fluxos end-to-end mais importantes
   • Um tema escuro claro por padrão
   • Limites do sistema e os fluxos de dados mais importantes visíveis na primeira tela
   • Tipos de módulos codificados por cores com uma legenda simples
   • Layout automático que minimiza arestas cruzadas
   • Clicar em qualquer módulo destaca seus chamadores upstream, dependências downstream, testes relacionados e os fluxos aos quais pertence
   • Selecionar um fluxo destaca seu caminho completo
   • Controles de busca, filtragem, zoom e arrastar

   No topo, mostre o nome do repositório, hora da geração e o commit a partir do qual foi gerado.

2. docs/codemap/codemap.json
   Use esta estrutura:

   JSON

   Скопіювати

   {
     "generated_at": "",
     "generated_from_commit": "",
     "scope": [],
     "nodes": [],
     "edges": [],
     "flows": []
   }
   

   Cada nó deve incluir:

   • id
   • path
   • role
   • entrypoints
   • tests
   • constraints
   • evidence

   Cada aresta deve incluir:

   • from
   • to
   • type
   • evidence

   O tipo só pode ser:

   • imports
   • calls
   • reads
   • writes
   • publishes
   • subscribes

   Cada fluxo deve incluir:

   • trigger
   • steps
   • outcome

   Cada passo deve referenciar um id de nó existente. Anexe o caminho do código-fonte correspondente e o símbolo a cada nó e aresta. Marque qualquer relação sem evidência de fonte como desconhecida. Não chute.

3. docs/codemap/codemap.lock
   Use JSON analisável para registrar:

   • O commit atual
   • Se a árvore de trabalho tem alterações não confirmadas
   • Hora da geração
   • Escopo varrido
   • Diretórios excluídos
   • O algoritmo de fingerprint
   • Um fingerprint determinístico para cada módulo de nível superior, calculado a partir de seus caminhos de arquivo rastreados e conteúdos atuais dos arquivos

   Se nenhum codemap.lock existente for encontrado, trate todos os módulos como novos e gere o mapa completo.

   Ao terminar, verifique se:

   • codemap.json é analisado com sucesso
   • Todos os caminhos de nó existem e todos os símbolos de evidência podem ser encontrados no código-fonte
   • Todas as arestas e passos de fluxo referenciam um nó existente
   • codemap.html e codemap.json usam os mesmos nós, arestas e fluxos
   • codemap.lock corresponde ao commit atual, estado da árvore de trabalho e fingerprints dos módulos
   • Todas as relações sem evidência de fonte são marcadas como desconhecidas

   Estes três arquivos devem sempre ser gerados juntos a partir do repositório atual. Nunca edite apenas um deles manualmente.

Finalmente, mostre:

• Arquivos criados ou modificados
• Módulos obsoletos
• Desconhecidos restantes
• Resultados da validação
• A diff completa

Regra Adicional

Adicione uma regra em AGENTS.md para manter o mapa de código sempre sincronizado com o repositório:

No início de cada tarefa que altera código, compare o repositório atual com docs/codemap/codemap.lock.

Antes de modificar um módulo, use docs/codemap/codemap.json para responder a três perguntas.