# Explore Codebase

> Use when arriving at an unfamiliar codebase, or an unfamiliar region of a known one, and the question is "what is here and how is it arranged" rather than "where is this specific thing". Trigger phrases: "help me understand this repo", "what does this project do", "where does X live", "walk me through the architecture", "I'm new to this codebase", "what are the main modules". Not for tracing one symptom to its cause — that is `debug-issue`; not for judging a diff — that is `review-changes`. Reach for this one when orienting, and switch to those once you know where to look.

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

---


# Explore codebase

Orient before reading. The failure this skill exists to prevent: opening files in the order a
search engine returned them and calling the resulting impression an understanding.

The workflow derives from the skill templates the `code-review-graph` project auto-installs
(MIT, © 2026 Tirth Kanani), rewritten here to be tool-agnostic: every step carries a baseline
that needs no graph server.

## Steps

1. **Establish the shape before the content** — how large, what languages, how many entry
   points.
   Accelerated: a graph-stats call (e.g. `list_graph_stats`-shaped; discover the real tool name
   from the server's own listing). Baseline: `git ls-files | wc -l`, `cloc` or
   `git ls-files | sed 's/.*\.//' | sort | uniq -c | sort -rn` for the language split, and the
   project's own manifest (`package.json`, `*.csproj`, `pyproject.toml`) for its declared
   dependencies and entry points.

2. **Find the module boundaries the project actually has**, not the ones its directory names
   suggest.
   Accelerated: an architecture-overview or community-listing call (e.g.
   `get_architecture_overview`-shaped) clusters by real coupling. Baseline: read the top-level
   directory tree, then check it against the imports — a directory whose files import mostly
   from one other directory is one module wearing two names.

3. **Read the entry points first.** A `main`, an HTTP route table, a CLI command registry, a
   message consumer, a scheduled job. These are where the project states what it is for.
   Accelerated: a flow listing (e.g. `list_flows`-shaped) names the paths the project itself
   considers significant. Baseline: grep for the framework's entry-point markers — route
   decorators, `if __name__ == "__main__"`, `Main(`, `.MapGet(`, a `bin` or `scripts` entry in
   the manifest.

4. **Follow one real path end to end** before reading anything else. One request, one command,
   one message — from entry point to persistence and back.
   Accelerated: a flow query (e.g. `get_flow`-shaped) returns the whole path in one call.
   Baseline: read each hop in sequence. One traced path teaches more than ten skimmed files,
   because it shows which abstractions the project actually uses rather than which it declares.

5. **Locate the tests for that path.** They are the executable description of intended
   behaviour, and their absence is itself a finding worth recording.
   Accelerated: a tests-for query (e.g. `query_graph`-shaped with a tests-for pattern).
   Baseline: search for the symbol's name under the test directory, and check whether the
   project's test command names a coverage report you can read instead.

6. **Write down what you concluded and what you did not check.** An exploration that produces
   no artifact has to be repeated by the next person, including you next week.

## Gotchas

No environment-specific gotchas known.

## Red flags — STOP

- Reading files in search-result order and calling it an understanding
- Describing the architecture from directory names, without checking the imports against them
- Skipping step 4 — a traced path is the difference between knowing the layout and knowing the
  system
- Reporting "the codebase does X" from a region you did not open; say which parts you read
- Treating a generated or vendored directory as authored code — check whether it is in
  `.gitignore` or carries a generation banner before drawing conclusions from it

An orientation is not finished until it names the entry points, one traced path, where that
path's tests live, and — explicitly — the regions left unread.