mirror of
https://github.com/Asixa/codemap-skill.git
synced 2026-08-28 23:01:22 +00:00
Xingyu Chen
2.0 KiB
2.0 KiB
codemap — agent instructions
This repository is the codemap tool: it builds and incrementally maintains an interactive architecture map + per-module code-quality audit for any codebase. It is a Claude Code skill, but the engine is tool-agnostic — Codex, Cursor, Aider, or any agent that can read instructions and spawn sub-tasks can drive it.
Read these first
SKILL.md— the full workflow and theinit / check / update / test / fixcommands. Follow it exactly.reference/STANDARDS.md— the fixed scoring rubric, smell taxonomy (with per-language equivalents), severity levels, and the exact per-module audit prompt.reference/DATA_MODEL.md— themodules.jsonschema (the source of truth).
Non-negotiable rules
modules.jsonis the source of truth. The HTML and MD are generated byscripts/render.py— never hand-edit them.- Every module's score comes from a separate, independent sub-task (one module per
sub-task), using the prompt in
reference/STANDARDS.md. Never score many modules in one pass; never reuse one module's score for another. - For
fix: keep the four roles separate — test-author, fixer, acceptance/verifier, auditor. A fix is accepted only when an independent acceptance step shows the pre-fix green tests are still green and the build is clean.
The scripts (deterministic, Python 3 stdlib, no install)
python scripts/scan.py --root <proj> --state <state> [--write] # LoC + hash + staleness
python scripts/query.py --state <state> --max-grade C --format ids # pick targets cheaply
python scripts/apply_audit.py --state <state> --id <id> --json '<result>'
python scripts/render.py --state <state> --template assets/template.html \
--out-html <html> --out-md <md>
Use query.py (--format ids|paths|findings) to target work without reading the whole
modules.json. Only scoring / fixing / test-writing need the model; everything else is
a plain script call.