# Codebase Map

> Codebase Map

- Skill: `yuri-semenenko/codebase-map-2` (Agent Skill)
- Install (CLI): `npx skillmds@latest add yuri-semenenko/codebase-map-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/yuri-semenenko/codebase-map-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: yuri-semenenko (https://skillmd.com/u/yuri-semenenko)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/yuri-semenenko/codebase-map-2

---


# Codebase Map

Build a fast, honest orientation to code you don't know yet, so you (or an agent you're about to point at it) can work in it safely. This is reconnaissance for comprehension: what the code is, where it starts, how it flows, and what not to touch. It is a map, not a tour — pointers over prose, evidence over guesses.

## How to run (keep main context lean)

1. **Scope it.** If a path argument was given, map that subtree; otherwise the whole repo. Read the obvious roots first: README, `package.json` (scripts + deps), the top-level layout, and any existing `AGENTS.md` / `CLAUDE.md` / architecture docs.
2. **Fan out, do not grep inline.** Per the persona's session-hygiene rule, dispatch `Explore` subagents — one per subsystem or question (entry points, data flow, domain terms, tests/tooling) — each returning a compact findings list, not file dumps. This keeps large intermediate output out of the main conversation.
3. **Assemble the map** from what came back. Merge, resolve contradictions rather than smoothing them over, and cite where each fact lives.

## What the map captures

- **What it is.** One paragraph: the purpose and the domain it serves. From the README and the shape of the code, not the marketing.
- **Entry points.** Where execution actually starts — server/main, routes or pages, CLI commands, cron/queue workers, build entry. The "start here" files.
- **Architecture sketch.** The handful of layers or modules that matter and how data flows between them. A few boxes and arrows in prose, not a file tree.
- **Domain glossary.** The ubiquitous language: the 5-15 domain nouns and verbs that recur, one line each. The vocabulary you need to read the code and talk to the team.
- **Key seams.** The stable interfaces and boundaries where behavior is substituted or extended (see /module-design for the vocabulary). Where you would attach a test or a new implementation.
- **Risky / don't-touch areas.** Load-bearing, security-sensitive, or historically fragile code, and the invariants not to regress. Mark it; do not "fix" it (Chesterton's Fence).
- **How to run and test.** Build/dev/test/single-test commands, local setup, required env vars — from repo evidence, not guesses. Say so when something is unknown.
- **Known tradeoffs.** Existing `TRADEOFF(...)` annotations, TODOs of record, and documented debt (feeds /debt-ledger).

## Skip (noise)

- Full file-tree dumps (derivable from `ls`).
- Restating the stack that `package.json` already shows.
- Generic advice ("write tests", "use strict mode").
- Line-by-line or file-by-file summaries. A map longer than the territory is useless.

## Rules

- Read evidence; do not invent structure. Flag uncertainty explicitly rather than guessing.
- Comprehension, not critique. Note over-engineering in passing, but hand a real audit to /complexity-audit.
- Respect Chesterton's Fence: unclear or load-bearing code is "risky", not "delete me".
- Keep it short and proportional — aim for a map that fits on a screen or two (~80-150 lines), longer only if the repo genuinely needs it.

## Output

A short orientation doc in the sections above, with `file:line` / path pointers throughout. End with a **Start here** shortlist (2-4 files to open first) and the **open questions** a reader would still need answered. If the run-and-test facts are worth persisting for an agent, offer to distill them into an `AGENTS.md` (that is the project-onboarding job — cross-reference it, don't duplicate it here). English prose, no em dashes, per persona.