/codemap

name: codemap
description: Generate, update, or drift-check agent-facing CodeMaps as progressive code terrain indexes for projects, features, capabilities, functions, modules, or bug chains. Use when Codex needs to inspect an unfamiliar codebase, map a feature/capability from entry to effect, create or update `mydocs/codemap/*`, answer `create_codemap`, `MAP`, `PROJECT MAP`, code terrain, impact-map, "where should the agent look first", check whether existing CodeMaps are stale after a diff, or prepare SDD-RIPER Research without loading the whole repository into context.

Codemap

Core Position

Create CodeMaps for agents, not CodeWiki for humans.

CodeMap saves context attention, not necessarily raw token count. It does not replace source code, tests, logs, or the current Spec. It routes the agent toward the right source-linked evidence, in the right order, with progressive disclosure.

Use a CodeMap as:

• `Project CodeMap`: breadth-first project terrain, capability index, module boundaries, dependency index, and drill-down pointers.
• `Feature CodeMap`: depth-first capability terrain from entry to effect, including branches, dependencies, risks, and validation entry points.

Workflow

1. Restate the requested scope and choose mode:

• `feature`: capability, business feature, bug chain, API flow, function/class-centered investigation.
• `project`: repository, service, package, subsystem, or first-time onboarding map.
• `drift-check`: compare current diff or touched files with existing CodeMaps.
• `update-existing`: refresh an existing CodeMap after code terrain changes.

2. Before writing a durable CodeMap, tell the user why a map/update is useful, the selected mode, scope, and expected path. Do not silently write persistent maps unless current task approval already covers it. 3. Read `references/principles.md` when the output shape, boundary, or CodeWiki-vs-CodeMap distinction matters. 4. For drift checks, read `references/drift-check.md`. 5. For updating an existing map, read `references/update-existing.md`. 6. Inspect code with search first (`rg`, `rg --files`, language-aware tools if available). Prefer source facts over inferred naming matches. 7. Build progressive Context Tree Nodes:

• start with a small orientation node;
• add capability, module, entry, branch, effect, dependency, risk, and validation nodes only where they route future context;
• keep compact indexes as lookup tables, not as the main structure;
• point nodes to files, functions, classes, tests, configs, logs, and related maps;
• mark each important relationship as `confirmed`, `inferred`, or `unknown`.

8. Write the map under `mydocs/codemap/` when the user requests a durable artifact or the work feeds SDD-RIPER Research:

• feature: `mydocs/codemap/YYYY-MM-DD_hh-mm_<feature>功能.md`
• project: `mydocs/codemap/YYYY-MM-DD_hh-mm_<project>项目总图.md`

9. Keep the CodeMap narrow enough to guide the next agent action. Do not paste large source blocks or turn it into a narrative system document.

Templates

• For feature/capability maps, follow `references/feature-template.md`.
• For project/system maps, follow `references/project-template.md`.
• For drift checks, follow `references/drift-check.md`.
• For existing map updates, follow `references/update-existing.md`.
• If a task spans multiple repositories, create one Project CodeMap per relevant project, then add a separate interface or cross-service flow summary.

Output Rules

• Prefer path-linked, source-grounded bullets over prose.
• Separate `Confirmed`, `Inferred`, and `Unknown`.
• Include `Next Drill-Down` so the next agent knows what to read only if needed.
• Include `Validation Entry` so the map can feed Spec / Plan / Review.
• Treat stale or conflicting CodeMaps as indexes to re-check, not truth.
• Do not treat CodeMap as a changelog. Update only terrain-changing facts: entries, flows, module boundaries, dependencies, risks, validation entry points, or behavior rule locations.