# Understand Codebase

> Maps a Python, C/C++/HIP, or CMake codebase into curated Mermaid diagrams saved as a code map under `./codemap/`. Use when a user wants to understand a codebase, map the code, see the call graph, draw a class diagram, show the build graph or CMake targets, or onboard onto an unfamiliar repo.

- Skill: `abchoudh-amd/understand-codebase` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx skillmds@latest add abchoudh-amd/understand-codebase`
- Raw SKILL.md: https://api.skillmd.com/api/skills/abchoudh-amd/understand-codebase/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: abchoudh-amd (https://skillmd.com/u/abchoudh-amd)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/abchoudh-amd/understand-codebase

---


# Understand Codebase

Turn an unfamiliar codebase into a navigable map. A bundled script
(`scripts/codemap.py`, stdlib only, no new dependencies) does exhaustive extraction
and emits raw Mermaid; you then prune it to the legible core and explain it in prose.
Output is a Markdown code map saved under `./codemap/`.

Three languages: Python via `ast`, C/C++/HIP via a source scan that needs no compiler,
and CMake for the build graph. A mixed repo is normal — `--lang auto` maps everything it
finds, which is how the Python/C++ boundary becomes visible.

## Quick start

1. Resolve the target source root. Default to the repo's `src/`; ask only if ambiguous.
2. Run the overview first to get the lay of the land:
   `python3 ~/.cursor/skills/understand-codebase/scripts/codemap.py --root <src> --mode overview`
3. Run class structure: `--mode classes` (inheritance trees) or `--mode classes --focus <Class>`.
4. For call graphs: `--mode callgraph --focus <Class|func|module> --depth <N>`.
5. For a CMake project: `--mode targets` (add `--lang cmake` when the root also holds source).
6. Curate the raw output into focused diagrams + prose, then save under `./codemap/`.

Add `--lang {python,cpp,cmake}` to restrict a mixed root to one language. The default
`auto` detects every language present and reports each on its own `info:` line.

On a Slurm host, route the `python3` invocations through `srun --jobid=$JOBID` per the
`slurm` skill.

## Modes

| Mode | Emits | Use for |
|---|---|---|
| `overview` | `graph TD` of packages → modules + cross-package edges (Python imports, C++ local includes); `add_subdirectory` tree for CMake | whole-codebase map, "how is this organized" |
| `classes` | inheritance `graph TD` (no focus) or `classDiagram` (with `--focus`) | base/subclass trees, one class's methods+attrs |
| `callgraph` | `flowchart TD` of caller → callee, BFS from `--focus` | "what does X call", tracing a flow |
| `targets` | `flowchart TD` of CMake target → linked target | build layout, "what links against what" |

Key flags: `--lang {auto,python,cpp,cmake}`, `--focus <dotted.name | Class | func | module | target>`,
`--depth N` (call BFS, default 2), `--format {mermaid,json}`, `--max-nodes N`
(renderability cap, default 200). See [REFERENCE.md](REFERENCE.md) for the full flag list
and per-language resolution caveats.

## Curation rule (the agent's job)

The script is exhaustive and blunt; raw whole-codebase graphs are too dense to read.
Always curate before saving:

1. Start from overview, then drill down with `--focus` per subsystem.
2. Prune to the spine: collapse leaf/utility nodes, keep the structural backbone.
3. Group nodes by subsystem; rename cryptic ids to readable labels where helpful.
4. Explain every diagram in surrounding prose — never drop an unexplained diagram.
5. State the resolution caveat for the language you mapped. Call edges are best-effort
   static analysis everywhere; the script reports unresolved counts per language on
   stderr, so cite the number rather than implying the graph is complete.
   - Python: dynamic dispatch and `importlib` indirection are missed.
   - C++: no preprocessor evaluation, macro-generated declarations are invisible, and
     virtual dispatch resolves to the static name.
   - CMake: `file(GLOB)` sources appear as a pattern, and a target name built from an
     unresolvable variable keeps its literal `${...}` text.
6. On a mixed repo, say which languages you mapped and which you left out. A C++ map of a
   repo that is half Python is a partial map, and the reader needs to know that.

## Output rules

1. Ensure `./codemap/` exists at the repo root; create it if missing.
2. Save as `./codemap/<name>.md` (kebab-case, e.g. `rocprofiler-compute.md`).
3. If the filename exists, auto-suffix `-v2`, `-v3`, … rather than overwriting.
4. Echo the saved path in the final response.

Document skeleton: **Overview** (what was mapped, which languages, caveats) → **Package
map** (overview diagram + prose) → **Build layout** (CMake `targets` diagram, when the
project has one) → **Class structure** (inheritance trees + key class diagrams) → **Key
call graphs** (one per important flow) → **Notes / limitations**.

## Pre-save self-check

- [ ] Every embedded Mermaid block parses (balanced `subgraph`/`end`, valid arrows).
- [ ] Every diagram is referenced by the surrounding prose.
- [ ] The best-effort/unresolved-edges caveat is stated for each language mapped.
- [ ] The languages covered — and any deliberately skipped — are named.
- [ ] Diagrams are curated, not raw dumps exceeding the node cap.

## Out of scope

- Forward-looking architecture you intend to build → `write-design`.
- Executable planning from the code map → `plan-feature` for planning only,
  `build-feature` for full delivery, `implement-feature` for one exact approved plan or a
  released `plan_ready` state. Bare implementation without an approved plan or state:
  stop and offer `plan-feature` or `build-feature`, and start neither automatically.
- Languages other than Python, C/C++/HIP, and CMake. Rust, Go, and CUDA-only `.cu` files
  outside a C++ tree have no extractor here.
- Configure-time build state: generator expressions, `file(GLOB)` expansion, and
  toolchain-conditional targets are reported as-written, not evaluated.
- Semantic C++ questions a scan cannot answer — overload resolution, template
  instantiation, and which virtual override actually runs.

## Additional resources

- [REFERENCE.md](REFERENCE.md) — script flags, resolution behavior, Mermaid cheat-sheet, pruning heuristics.
- [EXAMPLES.md](EXAMPLES.md) — worked overview and drill-down invocations.
- [writing style](../_shared/WRITING-STYLE.md) — normative prose rules and the pre-save self-check for
  every human-read artifact this skill produces.