update-codemaps

Generate and maintain codemaps/*.md as a compact, high-signal view of repository architecture.

Language Policy

• Default output language: Chinese (简体中文)
• Keep code symbols, file paths, command names, and API/variable identifiers in their original form.
• If the user explicitly requests another language (for example English), follow the user request.

Purpose

• Provide a fast, token-efficient architecture overview
• Keep docs synchronized with code changes
• Offer stable onboarding context for humans and agents

Outputs

codemaps/
├── architecture.md
├── backend.md        # if backend exists
├── frontend.md       # if frontend exists
├── data.md
└── index.md

Usage

• /update-codemaps - full refresh
• /update-codemaps --check - show drift/diff summary only, do not rewrite
• /update-codemaps --force - refresh without confirmation prompts

Workflow

1. Detect stack and project shape

   • Use signals such as go.mod, pyproject.toml, requirements.txt, package.json, Cargo.toml.

2. Scan source tree

   • Include core source files (.go, .py, .ts, .js, etc.).
   • Exclude node_modules, vendor, .git, caches, generated output, and test-only files.

3. Extract architectural signals

   • Entrypoints/modules
   • Routes/endpoints
   • Services/components
   • Data entities/schemas
   • Main dependency flow

4. Generate/update codemap files

   • Prefer concise tables and short bullets over long prose.
   • Use real paths from the current repository.
   • Generate document content in Chinese by default.
   • Add freshness metadata to each file:
     • Last Updated
     • Generated By: update-codemaps skill

5. Drift detection before overwrite

   • Compare with existing codemap files.
   • If estimated change is large (default: >30%), show summary and ask confirmation unless --force.
   • If --check, report what would change and stop.

Quality Bar

• Keep each codemap file focused and scannable.
• Favor architecture/relationships over implementation details.
• Keep docs consistent with current code layout.
• Avoid placeholders when concrete values are available.

Integration

• Run after major refactors or feature batches.
• Commit with a docs message (for example: docs: update codemaps).
• Pair with /code-invs when deeper traceability is required.