mirror of
https://github.com/Asixa/codemap-skill.git
synced 2026-08-28 21:01:18 +00:00
Xingyu Chen
36 lines
2.0 KiB
Markdown
36 lines
2.0 KiB
Markdown
# 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 the `init / check / update / test / fix`
|
|
commands. 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`** — the `modules.json` schema (the source of truth).
|
|
|
|
## Non-negotiable rules
|
|
1. **`modules.json` is the source of truth.** The HTML and MD are generated by
|
|
`scripts/render.py` — never hand-edit them.
|
|
2. **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.
|
|
3. 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.
|