Get a map of a codebase you have never opened before

Generate an annotated map of any codebase in under an hour, showing what runs where and who owns what.

For anyone joining a project or inheriting one · 8 steps · 7 min

How it works today.

You clone the repository and open the README. It was last updated eighteen months ago and points to a deployment script that no longer exists. You grep for 'main' and get forty-seven matches. You open what looks like an entry point, follow three imports, and realize you still don't know if this is a monolith, a set of services, or something in between. By day two you have a Notion page of guesses and a list of people to ask when they're not in back-to-back meetings.

The person who built this has a map in their head: which folders matter, which ones are abandoned experiments, where the business logic lives versus where the framework boilerplate lives. You are reverse-engineering that map by reading code you do not yet understand, and every guess costs you thirty minutes. If the project has multiple services, you are also guessing at deploy order and which API calls which. The README tells you how to run tests, not how the system thinks.

Before you start.

All of it has to be true, or step one fails in a way that is annoying to debug.

Read access to the repository, including any submodules or linked repos
An LLM agent with code-reading capability (Claude, GPT-4, or a vertical coding agent like Cursor or Cody)
Write access to a shared doc or wiki where you will publish the map
A list of the three most common user actions in the product, so you can trace real paths instead of theoretical ones

The steps.

Generate a static dependency graph of the entire codebase
Use a tool like Sourcegraph, GitHub's dependency graph, or a language-specific analyzer (madge for JavaScript, pydeps for Python, go mod graph for Go). Export the result as JSON or a visual SVG. If your repo has multiple languages, run one tool per language and note where they call across boundaries. You are looking for the shape of the system, not reading code yet.
02
Ask the agent to identify entry points and label the dependency graph
Paste the dependency graph and the README into the agent. Ask it to mark which files are entry points (servers, CLI commands, background workers) and which are likely dead code. If the agent cannot distinguish, ask it to list files modified in the last six months and cross-reference. Save the annotated graph as a markdown file with a sentence per entry point.
Paste this
```
Here is the dependency graph for this codebase: [paste graph]. Here is the README: [paste README]. Identify all entry points—files that start a server, handle a request, run a scheduled job, or execute as a CLI command. For each entry point, write one sentence explaining what it does. Flag any files in the graph that have no incoming edges and have not been modified in six months.
```
03
Trace one user action end-to-end through the code
Pick the most common user action from your prerequisites list. Ask the agent to trace the path from HTTP request (or CLI invocation) to database write, listing every file and function in order. If the agent halts at a service boundary, note the API call and repeat the trace in the next service. You are building a vertical slice, not documenting every branch.
Paste this
```
Trace the path through this codebase when a user [describes action, e.g., 'uploads a file']. Start at the entry point and list every file and function called, in order, until the action completes or data is persisted. If the code calls an external service or API, name the endpoint and stop. Show me the sequence as a numbered list.
```
04
Extract configuration and environment assumptions
Ask the agent to list every environment variable, config file, and external service the codebase expects. Include database connection strings, API keys, feature flags, and third-party SaaS endpoints. If the agent finds hardcoded values, flag them. This step reveals what must be true in production for the code to run.
Paste this
```
List every environment variable, configuration file, and external dependency this codebase requires to run. Include database URLs, API keys, feature flags, and any third-party services it calls. If you find hardcoded credentials or endpoints, flag them separately.
```
Map ownership and recent change hotspots
Run git log --format='%an' --numstat and pipe it to a script that counts lines changed per author per directory. Alternatively, use GitHub's contributor insights. Identify the top three contributors per major directory. Cross-reference with your annotated dependency graph to see who owns which entry points. If a critical path has no active maintainer, note it.
06
Ask the agent to describe the data model in plain language
Paste your ORM models, database schema file, or migration history into the agent. Ask it to explain each table or collection in one sentence, then describe the relationships. If the schema and the ORM disagree, the agent should flag it. Save this as a separate markdown file titled 'Data Model'.
Paste this
```
Here is the database schema: [paste schema or ORM models]. For each table or collection, write one sentence explaining what it stores. Then describe the foreign key relationships or references between them. If any model in the code references a table that does not exist in the schema, flag it.
```
07
Generate a deployment and build order diagram
Ask the agent to read CI/CD config files (GitHub Actions, GitLab CI, Jenkinsfile, Dockerfile, docker-compose.yml) and describe the build and deploy sequence. If multiple services exist, ask which must start first. If the config references scripts not in the repo, note them as missing. This step maps the gap between code and running system.
Paste this
```
Read these CI/CD and deployment files: [paste or link to .github/workflows, Dockerfile, docker-compose.yml, etc.]. Describe the build process in order: what gets built, what gets tested, what gets deployed, and in what sequence. If multiple services are deployed, specify the order and any dependencies between them.
```
Compile the map into a single onboarding document
Combine the annotated dependency graph, the user action trace, the config requirements, the ownership map, the data model, and the deploy sequence into one markdown file. Add a table of contents. At the top, write three sentences summarizing what this codebase does, what it depends on, and who to ask when something breaks. Publish it to your team wiki and link it from the README.

What you keep.

Automating the typing does not move the accountability. These stay with a person.

Deciding which user action to trace first, because the agent does not know what matters to your users or your business
Validating that the agent's entry point list is complete, especially if the codebase has undocumented background jobs or webhooks
Reaching out to the top contributors identified in the ownership map to confirm they are still the right people to ask
Updating the map when the architecture changes, because the agent only sees the code as it is today

Once it works.

The first run is the demo. These are where the time actually comes back.

Put it on a schedule

Run the dependency graph and ownership analysis every two weeks, diffing the output to catch when a critical path loses its maintainer or a new entry point appears.

Fire it from an event

Trigger the user action trace automatically when a new route or CLI command is added, so the onboarding doc updates itself when the architecture changes.

Hand off to another agent

Hand the agent a Sentry error trace or log snippet and ask it to map the error back to the relevant section of your codebase map, turning a stack trace into a starting point.

Scale it wider

Once you have mapped one codebase, apply the same sequence of prompts to every repository your team owns, building a cross-repo atlas of how services call each other.