Creating an Interactive Code Map with Codex

Creating an Interactive Code Map with Codex

Ask Codex to create an interactive map of your repository, and then mark which modules have changed since its generation.

By clicking on any module, you can see its calling components, dependencies, main execution flows, related tests, and supporting data from the source code.

Codex generates:

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

Full Prompt

Analyze the current codebase. Do not modify product code. Only create or update files under docs/codemap/.

Ignore vendor, build, dist, cache, and other generated directories.

If docs/codemap/ already exists, first compare the existing codemap.lock with the current repo and list the modules that changed. Then regenerate these three files together:

1. docs/codemap/codemap.html
   Build a fully self-contained interactive code map that opens directly in a browser. Include:

   • major modules, services, databases, queues, and external dependencies
   • no more than 20 primary nodes; group low-level files under their parent module
   • calls and data flows between modules
   • the 3-5 most important end-to-end flows
   • a clear dark theme by default
   • system boundaries and the most important data flows visible on the first screen
   • color-coded module types with a simple legend
   • automatic layout that minimizes crossing edges
   • clicking any module highlights its upstream callers, downstream dependencies, related tests, and the flows it belongs to
   • selecting a flow highlights its complete path
   • search, filtering, zoom, and drag controls

   At the top, show the repo name, generation time, and the commit it was generated from.

2. docs/codemap/codemap.json
   Use this structure:

   JSON

   Скопіювати

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

   Each node must include:

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

   Each edge must include:

   • from
   • to
   • type
   • evidence

   type may only be:

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

   Each flow must include:

   • trigger
   • steps
   • outcome

   Every step must reference an existing node id. Attach the matching source path and symbol to every node and edge. Mark any relationship without source evidence as unknown. Do not guess.

3. docs/codemap/codemap.lock
   Use parseable JSON to record:

   • the current commit
   • whether the working tree has uncommitted changes
   • generation time
   • scanned scope
   • excluded directories
   • the fingerprint algorithm
   • a deterministic fingerprint for each top-level module, calculated from its tracked file paths and current file contents

   If no existing codemap.lock is found, treat every module as new and generate the full map.

   When finished, verify that:

   • codemap.json parses successfully
   • every node path exists and every evidence symbol can be found in the source
   • every edge and flow step references an existing node
   • codemap.html and codemap.json use the same nodes, edges, and flows
   • codemap.lock matches the current commit, working tree state, and module fingerprints
   • every relationship without source evidence is marked unknown

   These three files must always be generated together from the current repo. Never edit only one of them manually.

Finally, show:

• files created or modified
• stale modules
• remaining unknowns
• validation results
• the complete diff

Additional Rule

Add a rule in AGENTS.md to keep the code map always synchronized with the repository:

At the start of every code-changing task, compare the current repo with docs/codemap/codemap.lock.

Before modifying a module, use docs/codemap/codemap.json to answer three questions:

1. What calls it?
2. What does it affect?
3. Which tests cover it?

If the map is stale or cannot answer those questions, regenerate codemap.html, codemap.json, and codemap.lock before changing the code.

Whenever module boundaries, dependencies, routes, databases, queues, or major data flows change, update the code map in the same commit as the code.