Creación de un Mapa de Código Interactivo con Codex

Creación de un Mapa de Código Interactivo con Codex

Pida a Codex que cree un mapa interactivo de su repositorio y luego marque qué módulos han cambiado desde su generación.

Al hacer clic en cualquier módulo, puede ver sus componentes de llamada, dependencias, flujos de ejecución principales, pruebas relacionadas y datos de respaldo del código fuente.

Codex genera:

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

Prompt Completo

Analice la base de código actual. No modifique el código del producto. Solo cree o actualice archivos en docs/codemap/.

Ignore los directorios vendor, build, dist, cache y otros directorios generados.

Si docs/codemap/ ya existe, primero compare el codemap.lock existente con el repositorio actual y enumere los módulos que han cambiado. Luego regenere estos tres archivos juntos:

1. docs/codemap/codemap.html
   Construya un mapa de código interactivo completamente autónomo que se abra directamente en un navegador. Incluya:

   • módulos principales, servicios, bases de datos, colas y dependencias externas
   • no más de 20 nodos principales; agrupe archivos de bajo nivel bajo su módulo principal
   • llamadas y flujos de datos entre módulos
   • los 3-5 flujos de extremo a extremo más importantes
   • un tema oscuro claro por defecto
   • límites del sistema y los flujos de datos más importantes visibles en la primera pantalla
   • codificación de colores de tipos de módulos con una leyenda simple
   • diseño automático que minimiza el cruce de bordes
   • hacer clic en cualquier módulo resalta sus llamadores ascendentes, dependencias descendentes, pruebas relacionadas y los flujos a los que pertenece
   • seleccionar un flujo resalta su ruta completa
   • controles de búsqueda, filtrado, zoom y arrastre

   En la parte superior, muestre el nombre del repositorio, el tiempo de generación y el commit del que se generó.

2. docs/codemap/codemap.json
   Utilice esta estructura:

   JSON

   Скопіювати

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

   Cada nodo debe incluir:

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

   Cada borde debe incluir:

   • from
   • to
   • type
   • evidence

   type puede ser solo:

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

   Cada flujo debe incluir:

   • trigger
   • steps
   • outcome

   Cada paso debe hacer referencia a un id de nodo existente. Adjunte la ruta de origen y el símbolo coincidente a cada nodo y borde. Marque cualquier relación sin evidencia de origen como desconocida. No adivine.

3. docs/codemap/codemap.lock
   Utilice JSON parseable para registrar:

   • el commit actual
   • si el árbol de trabajo tiene cambios no confirmados
   • tiempo de generación
   • alcance escaneado
   • directorios excluidos
   • el algoritmo de huella digital
   • una huella digital determinista para cada módulo de nivel superior, calculada a partir de sus rutas de archivos rastreados y el contenido actual de los archivos

   Si no se encuentra un codemap.lock existente, trate cada módulo como nuevo y genere el mapa completo.

   Al finalizar, verifique que:

   • codemap.json se analiza correctamente
   • cada ruta de nodo existe y cada símbolo de evidencia se puede encontrar en la fuente
   • cada borde y paso de flujo hace referencia a un nodo existente
   • codemap.html y codemap.json utilizan los mismos nodos, bordes y flujos
   • codemap.lock coincide con el commit actual, el estado del árbol de trabajo y las huellas digitales de los módulos
   • cada relación sin evidencia de origen se marca como desconocida

   Estos tres archivos siempre deben generarse juntos desde el repositorio actual. Nunca edite solo uno de ellos manualmente.

Finalmente, muestre:

• archivos creados o modificados
• módulos obsoletos
• desconocidos restantes
• resultados de validación
• el diff completo

Regla Adicional

Agregue una regla en AGENTS.md para mantener el mapa de código siempre sincronizado con el repositorio:

Al comienzo de cada tarea que cambie el código, compare el repositorio actual con docs/codemap/codemap.lock.

Antes de modificar un módulo, use docs/codemap/codemap.json para responder a tres preguntas:

1. ¿Qué lo llama?
2. ¿Qué afecta?
3. ¿Qué pruebas lo cubren?

Si el mapa está obsoleto o no puede responder a esas preguntas, regenere codemap.html, codemap.json y codemap.lock antes de cambiar el código.

Siempre que cambien los límites de los módulos, las dependencias, las rutas, las bases de datos, las colas o los flujos de datos importantes, actualice el mapa de código en el mismo commit que el código.