Understanding a Codebase

Answering it means building a codebase mental model: a picture in your head of who uses the system, where its code lives, which components talk, how one feature travels through them, where decisions are made, how data changes shape, and what a change would ripple into. This episode builds that model in nine gates, on one realistic system, and only then shows where AI makes it faster.

You progressively move from what does the system do? to where does this feature live? to what could my change affect? The journey at the top of the page is the whole method. By the end, you should be able to answer these thirteen questions about any system you join:

1. 1What problem does this system solve?
2. 2Who uses it?
3. 3What are its major business workflows?
4. 4How is the repository structured?
5. 5What are the major architectural components?
6. 6How does the application start?
7. 7How does a feature travel through the system?
8. 8Where does business logic live?
9. 9How does data move through the system?
10. 10What could be affected by a change?
11. 11What should be investigated before coding?
12. 12How can AI accelerate this investigation?
13. 13How do we validate AI's findings?

The outcome: you can explain the system before you change the system.

Clearance questionCan I describe the claim workflow to a new teammate without mentioning a single file?

Clearance questionIf a type changes in packages/types, can I name every application it reaches?

Clearance questionCan I draw every component that a claim touches, including the ones outside our code?

1pnpm dev

Clearance questionIf the app fails to start tomorrow, do I know the first three places to look?

1export function ApproveClaimButton({ claimId }: { claimId: string }) {
2  const approve = useApproveClaim();
3  return (
4    <Button disabled={approve.isPending} onClick={() => approve.mutate({ claimId })}>
5      Approve
6    </Button>
7  );
8}

Clearance questionCan I name the file and function at every hop, in both directions?

Clearance questionFor the rule I am about to change, can I point at the one place that enforces it?

Receipt matches serial number

Clearance questionIf I add a field, do I know every representation that must learn about it?

Clearance questionCan I list what could break, and how I would notice if it did?

Clearance questionCan I explain this change and its impact to another developer before writing code?

AI output is a hypothesis until validated against the actual codebase.

Do not ask “explain this codebase” and paste the answer into your notes. Form your own model first, then ask narrow questions that force the assistant to cite files and symbols, and to say UNKNOWN when it does not know. Evidence you can open beats a confident paragraph.

Five prompts, one per gate family. Each forces evidence and gives the assistant permission to not know. Under each prompt: how you validate what comes back. The last one matters most. Strong engineers ask what they know, and then: what don’t I know yet?

1Analyse this repository and create a codebase map.
2
3Identify:
4
5- applications
6- modules
7- shared packages
8- database
9- integrations
10- tests
11- infrastructure
12- configuration
13
14For each area:
15
161. Explain its responsibility.
172. Reference the relevant files.
183. Identify the entry points.
194. Mark uncertain findings as UNKNOWN.
20
21Do not invent implementation details.

1Trace the implementation of:
2
3[FEATURE]
4
5Follow:
6
7UI
8→ API client
9→ HTTP endpoint
10→ controller
11→ DTO
12→ service
13→ repository / ORM
14→ database
15→ response
16→ UI
17
18For every step provide:
19
20- file path
21- class/function
22- responsibility
23- evidence connecting it to the next step
24
25Do not guess.
26Mark uncertain relationships as UNKNOWN.

1Find the business rules related to:
2
3[FEATURE]
4
5Separate the findings into:
6
71. Business rules
82. Input validation
93. Authorization
104. Database constraints
115. Technical implementation
126. Assumptions
13
14Reference the relevant file and symbol for each finding.
15
16Do not infer a business rule unless there is evidence in the code or documentation.

1I need to make this change:
2
3[CHANGE]
4
5Identify potentially affected:
6
7- frontend
8- backend
9- database
10- API contracts
11- business logic
12- integrations
13- reports
14- notifications
15- unit tests
16- E2E tests
17
18For every finding provide:
19
20- file
21- symbol
22- reason
23- confidence
24
25Do not assume every search result is affected.

1Based on the current codebase and feature investigation:
2
3What do we still NOT know?
4
5Identify unknowns that could result in:
6
7- incorrect implementation
8- missed business rules
9- broken dependencies
10- regression
11- incorrect assumptions
12
13Separate:
14
15Confirmed
16Inferred
17Unknown

The goal is not human, AI, answer. It is human, AI acceleration, human validation, understanding. The assistant shortens the search. The engineer still inspects the evidence, corrects the assumptions and owns the final model.

1. Principle 01

   Don't start with the file. Start with the system.

2. Principle 02

   Understand the business flow before the technical flow.

3. Principle 03

   Trace one feature end to end.

4. Principle 04

   Know where the business logic lives.

5. Principle 05

   Understand the data, not just the request.

6. Principle 06

   Think about impact before implementation.

7. Principle 07

   Identify what you don't know.

8. Principle 08

   Use AI to accelerate discovery, not replace understanding.