Nova

Posted on Mar 13

The Dependency Map Prompt: Understand a Codebase in 20 Minutes (Before You Touch Anything)

#devworkflow #productivity #promptengineering #engineering

Most “AI-assisted coding” failures aren’t really model failures.

They’re map failures.

You ask for a change in a repo you (and your assistant) don’t understand yet, and the output looks plausible… but it quietly violates one of the project’s invisible rules:

there’s a shared “domain” package you’re supposed to import from
side effects must go through a queue, not direct DB writes
the UI uses a custom form layer, not raw inputs
tests rely on factory helpers, not hand-rolled fixtures

When you don’t have that map, you get the classic symptoms:

“Why did it change 20 files?”
“Why is it adding a new library?”
“Why does this feel like it was written for a different codebase?”

This post is a practical pattern I use before asking for meaningful changes:

The Dependency Map Prompt — a structured request that produces a quick, high-signal mental model of a repo: entrypoints, key modules, data flow, and the constraints that matter.

It’s deliberately lightweight: 20 minutes, not a week-long archaeology project.

The Dependency Map Prompt (template)

Copy/paste this and fill in what you know.

You are helping me build a dependency map of this codebase so I can make safe changes.

Context
- Repo purpose: <1 sentence>
- My goal: <the change I eventually want>
- Allowed time: 20 minutes

Inputs I can provide
- File tree (top 3 levels)
- package.json / pyproject / go.mod
- A few key files (you pick which)

Task
1) Ask for the MINIMUM set of files you need to read to build a map.
2) Produce a dependency map with:
   - Entry points
   - Core modules and responsibilities
   - Data flow (request → domain → persistence → side effects)
   - External integrations
   - Configuration + environment variables
   - Testing strategy + where fixtures live
3) Identify “constraints” (project rules) that changes must respect.
4) List 5 high-leverage follow-up questions you’d ask before implementing my goal.

Output format
- Start with a 10-line summary.
- Then a bullet map grouped by layer.
- Then the constraints.
- Then the follow-up questions.

Hard rules
- Do NOT propose any code changes yet.
- If something is unknown, say "unknown" and tell me exactly what file would confirm it.

Two things make this work:

1) Timeboxing forces prioritization.
2) “Don’t change anything yet” prevents premature solutions.

A concrete example (Node/TypeScript API)

Say you want to add a new endpoint: POST /invoices/:id/send.

If you ask for that directly, you’ll often get a naive implementation:

controller calls a mailer directly
it queries the DB in the controller
it bypasses the existing job queue
it ignores the existing “billing domain” package

Instead, start with the map.

Step 1: Provide a tiny repo snapshot

Paste a trimmed file tree (top few levels):

src/
  api/
    routes.ts
    controllers/
  domain/
    invoices/
  infra/
    db/
    queue/
    email/
  config/
  workers/
  index.ts
package.json

And share the “obvious” entrypoints you think matter:

src/index.ts
src/api/routes.ts
one representative domain module (e.g. src/domain/invoices/*)

Then let the prompt ask for the minimum additional files.

Step 2: The dependency map you want back

A good map looks like this (abridged):

Entrypoints
- src/index.ts starts the HTTP server, loads config, wires DI
- src/workers/*.ts starts background job consumers
API layer
- src/api/routes.ts defines REST routes
- src/api/controllers/* contains request parsing + auth checks
Domain layer
- src/domain/invoices/* contains business rules and state transitions
- domain emits events like InvoiceSentRequested
Infrastructure
- src/infra/db/* repositories (domain-facing DB access)
- src/infra/queue/* job producer/consumer
- src/infra/email/* email provider adapter
Data flow
- HTTP request → controller → domain service → repository → emits event → queue → worker → email adapter
Constraints (rules)
- controllers never talk to the DB directly
- email must be sent via queue worker
- all side effects behind adapters in infra/
- tests use test/factories/* and test/helpers/*

Notice how the map naturally suggests the correct design without implementing anything yet.

What to do with the map (turn it into a “safe change” prompt)

Once you have the dependency map, you can write a follow-up request that’s much harder to mess up.

Here’s the next prompt I use:

Using the dependency map above, propose an implementation plan for:
POST /invoices/:id/send

Constraints to respect
- Controllers do not call repositories directly.
- Sending email is a background job.
- Domain logic lives in src/domain/invoices.

Deliverables
1) A step-by-step plan (max 12 steps)
2) The minimal file list to touch
3) A risk list (what could break)
4) A test plan (which tests to add/update)

Do not write code yet.

If the plan looks good, then ask for a patch/diff.

This sequence is boring on purpose:

1) map → 2) plan → 3) patch → 4) verify

Boring is how you ship.

Practical tips (things that keep this fast)

1) Ask for the “minimum file set” first

You don’t need to dump the entire repo.

If the assistant asks for 30 files, push back:

“Pick the smallest set that answers the map questions.”

2) Always request “unknown + confirmation file”

This prevents confident guesses.

Example:

“Auth is probably middleware-based.” ← useless
“Auth mechanism: unknown. Confirm by checking src/api/auth/* or src/middleware/auth.ts.” ← actionable

3) Treat constraints as acceptance criteria

The map isn’t just documentation — it’s the contract.

I’ll often copy the constraints into a checklist for every follow-up prompt:

[ ] no new deps
[ ] no DB calls in controllers
[ ] side effects via queue
[ ] use existing factories

4) Keep one “golden map” in the repo

If you’re doing repeat work in the same codebase, save the map:

docs/dependency-map.md

Then your future prompts can reference it instead of re-discovering everything.

When this pattern is especially worth it

Use Dependency Map Prompting when:

you’re new to a codebase
the change touches money/auth/permissions
there’s a layered architecture (domain/infra)
the repo has multiple entrypoints (workers, CLI, web)
you’ve been burned by “looks right, breaks prod” outputs

Skip it when:

you’re renaming a variable
the change is truly local (one file)

Wrap-up

If you want AI help to feel like a senior teammate instead of a clever autocomplete, start by giving it a map—or better, make it build the map with you.

The Dependency Map Prompt is my go-to for that: