Map an Unfamiliar Codebase

Before you change code you have never seen, learn how the project builds, tests and hangs together, and record it so neither you nor a teammate has to rediscover it. The standard: every command in your map has been run by you with its exit code noted, every claim about the code cites a file path, and the baseline test result is written down before you touch anything.

When to use

• "Take a look at this repo", "get familiar with the codebase", "how does checkout work in here?"
• You are about to make your first change in a repository.
• A teammate hands you a project and you do not yet know its test command.
• You came back to a repo after a long gap and the tooling may have changed.

What you need

• The code. Repository access comes from the owner's GitHub or GitLab connected app (Connections page) or a git credential the owner set up on your computer. If neither is there, ask the owner with clarify to connect one or to send an archive of the code. Never paste tokens into commands, URLs or notes.
• Somewhere safe to run it: your own computer, never a production server.
• Any notes from earlier work: check memory and session_search for this repo's name first.

Method

1. Get a clean checkout and its state.

   git clone <url> && cd <repo>          # or cd into the existing checkout
   git status --short; git branch --show-current; git log --oneline -15; git remote -v
   

   If the working tree is dirty and the changes are not yours, stop and ask before touching it.

2. Read the house rules first. read_file the README, CONTRIBUTING, any agent or contributor instructions file at the root (for example AGENTS.md), docs/development*, and the pull request template. These often name the one true test command and things you must never do.

3. Identify the stack from manifests. Use search_files with target='files' for pyproject.toml, requirements*.txt, package.json, lockfiles, go.mod, Cargo.toml, pom.xml, build.gradle*, Gemfile, composer.json, Makefile, justfile, Taskfile.yml, Dockerfile, compose*.yml, .tool-versions, .nvmrc, .python-version. The lockfile tells you the package manager (package-lock.json npm, pnpm-lock.yaml pnpm, yarn.lock yarn, bun.lockb bun, uv.lock uv, poetry.lock poetry). A monorepo has several manifests: note which directory each command must run from.

4. Find the real commands, in this order of trust.

   1. CI config (.github/workflows/*.yml, .gitlab-ci.yml, .circleci/config.yml): what CI runs is what counts.
   2. Task runners: Makefile targets, package.json "scripts", tox.ini, noxfile.py, justfile, [tool.*] tables in pyproject.toml.
   3. Contributor docs.
   4. Stack conventions from references/stack-commands.md. Write down install, run, test-all, test-one, lint, format-check, type-check and build. Include how to run a single test: you will need it constantly.

5. Check before you run. Look at .env*, config files and test settings for real credentials or production URLs. Tests must point at local or throwaway services. If a test suite would touch a real database, payment provider or email sender, stop and ask.

6. Establish the baseline. Install dependencies in a project-local environment (uv sync, python -m venv .venv, npm ci, go mod download, cargo fetch), then run the full test suite, linter and type checker once:

   <test command>; echo "exit=$?"
   

   Record pass and fail counts, duration and every pre-existing failure by name. Later you will compare against this, so a failure that was already there is never blamed on your change. Long suites: run with terminal(background=true, notify_on_complete=true) and keep reading code meanwhile.

7. Map the layout. List top-level directories and give each a one-line job.

   git ls-files | awk -F/ '{print $1}' | sort | uniq -c | sort -rn | head -20
   git ls-files | sed -n 's/.*\.//p' | sort | uniq -c | sort -rn | head -10
   

   Skip generated and vendored trees (node_modules, vendor, dist, build, .venv, target) in every search.

8. Find the entry points. main functions, cmd/ folders, [project.scripts] in pyproject.toml, "bin"/"main" in package.json, app factories, route tables, job and queue workers, cron definitions, CLI parsers. search_files for patterns such as if __name__ == "__main__", func main(), app = , createServer, @app.route|router\., fn main().

9. Trace one real flow end to end. Pick one user-visible action and follow it from entry point to storage and back with read_file, writing down each hop as file:function. One honest trace teaches more than skimming fifty files.

10. Learn the conventions to copy. Error handling, logging, config loading, naming, test layout and fixtures, formatter and linter settings (.editorconfig, ruff.toml, .eslintrc*, .prettierrc*, rustfmt.toml). Read the last three meaningful commits to see what a normal change looks like:

    git log -3 --stat --no-merges
    git show <sha> --stat
    

    Do changes ship with tests? With changelog entries? With migrations?

11. Find the risky ground. Hot files and owners:

    git log --since=6.months --name-only --format= | sort | uniq -c | sort -rn | head -15
    git shortlog -sn --since=1.year -- <path>
    

    Read CODEOWNERS if present. Hot, large, untested files are where changes break things.

12. Split big repos. For a large monorepo, delegate_task one subsystem per subagent with explicit questions ("What are the entry points of services/billing, how are its tests run, what does it depend on? Cite file paths."). Then spot-check their claims by reading the cited lines before you put them in your map.

13. Save what lasts. Write durable facts (commands, quirks, pre-existing failures, where things live) to memory under the repo's name. Do not store secrets or anything that will be stale next week.

Output

A code map in the shape of references/codemap-template.md: purpose, stack and versions, a commands table with exit codes, the baseline, layout, entry points, one traced flow, conventions, risky areas and open questions. Keep it under two screens. If the owner asked a specific question ("how does checkout work?"), answer that first in a few sentences with file paths, then attach the map. Use show_card for the commands table when the owner is watching.

Checks before you finish

• Every command in the map was run by you, and its exit code is recorded.
• The baseline lists pre-existing failures by name, or says "none".
• Every statement about behaviour cites at least one file path.
• Tests did not touch any real external service.
• Durable facts are saved to memory; secrets are not.

Pitfalls

• Trusting the README over CI. READMEs rot; workflows run on every push. When they disagree, CI wins, and note the drift.
• Running the suite against real services. Read the test config first. One test that sends real email or charges a real card is one too many.
• Installing globally. Use a virtualenv, npm ci into the project, or the version the project pins. Global installs make "works on my machine" bugs.
• Searching vendored code. Results from node_modules or vendor drown the real answer. Exclude them.
• Assuming the framework from one file. Confirm with the manifest and an entry point.
• Skimming instead of tracing. A list of directories is not understanding. Trace one flow.
• Forgetting the monorepo root. A command that works in one package may fail at the root, or vice versa. Note the working directory for each command.