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.