Craft
Stop trying to remember your codebase
Stop trying to keep a large codebase in your head. You can't keep it current, and you don't need to. A repo has years of history and dependencies you didn't write, and agents can add code faster than you can read it. What you remember from the last change needs checking against what exists today.
You need two different kinds of knowledge, and it helps to keep them apart.
Broad awareness
The first kind is architecture: where the services live, which module owns auth, roughly how a request moves through the system, which parts are old and fragile. It changes slowly and it's worth keeping. It tells you where to look. It doesn't tell you what the code does today.
Current local detail
The second kind is narrow: what this function returns when the input is empty, who calls it, what it writes to, which config flag changes its behavior. It goes stale fast, and it's the kind that breaks things when you get it wrong.
So I don't try to remember it. Before every change, I ask an agent to work out what the part I'm about to change does today, from the code, the tests and the git history. Not the whole codebase, just that part, and just for this change. When I come back to it a few months later, I ask again, because the code has moved on and so has my memory of it.
That part is rarely one file. A change to one function reaches past the file it lives in, so reading that file alone won't tell you what you're about to break.
Rebuild it with an agent, one layer at a time
Here's a made-up example to work through: you're changing approvePayment() so that anything above £10,000 needs a second approver.
I don't read my way through this by hand. I ask an agent to rebuild it, and I ask in layers: the map first, then how this part behaves, then everything the change can reach. I only go deep where the change needs it.
Here's the prompt:
I'm changing approvePayment() so anything above £10,000
needs a second approver. Don't change any code yet.
Explain what this part of the system does today, in three
steps. Stop after each step and wait for my questions.
1. The map, in ten lines: what this code is for and which
modules own it.
2. A Mermaid state diagram of the payment lifecycle as it
exists now: every state, every transition, and what
triggers each one. Draw what the code does, not what
it should do.
3. Everything this change can reach: callers, including
tests, jobs and indirect imports. Dependencies that
changed recently. Everything it writes, sends or emits.
Cite the file and line for every claim. If you can't
confirm something, list it under "not checked". Don't guess.
The state chart is the part I'd keep if you only keep one. A paragraph can skip a case without you noticing. A chart has to show every state and what gets a payment out of it, so a gap has nowhere to hide.
Draw the change on top of what exists and a question shows up that the request never raised. The scheduled payments job approves on its own, with no person involved. So where does a £12,000 scheduled payment go now?
The third layer is the boundary: everything the change can reach, and so everything you need to understand.
Callers are every place that calls the function, including tests, scripts and anything that imports it indirectly. In the example, that's the approvals screen, the scheduled payments job and the partner API.
Dependencies are what the code relies on, and whether any of it changed version or behavior recently. Here it's the payment provider's SDK, which was just upgraded, and the approval limit setting.
Effects are every place it writes to a database, sends a request, emits an event, touches a cache or changes a file on disk. This function writes to the ledger, sends the payment out and notifies the finance team.
When the reason for something matters, have the agent go through the git history too, like why a strange branch exists or who added a check and what bug it fixed.
Then check what it told you
An explanation is a claim about the code. A model can be confident and wrong, and so can a teammate. So check the parts the change depends on. Open the line the explanation points to and run the test that covers it. Call the function with the edge case and look at what comes back.
Behavior you observed counts for more than behavior someone described. A summary that matches the code and the test output is something you can build on. A summary nobody checked is still a guess.
Write down what you couldn't check
Even after all that, the boundary is never complete. A caller can hide behind reflection or a string lookup. A dependency can have behavior nobody documented, a feature flag can have a different value in production than on your machine, and a function you depend on might have no test.
When you hit something you can't check, write it down. Keep a short list next to the change with the callers you checked and the ones you didn't, plus the assumptions you're making about config or data. This list is the honest part of the work. The reviewer sees where the risk sits. If something breaks later, whoever debugs it knows where to look first.
If you leave the list empty, be ready to explain what you checked.
What it looks like in a change
A change built this way ships with the evidence that was checked and a written list of what wasn't. Here's the note for the approvePayment() example, made up like the rest of it:
Require a second approver above £10,000 in approvePayment()
Checked
- 3 callers found by search, including the scheduled payments job
- approval.test.ts passes, 3 new cases around the £10,000 limit
- Approved the same payment twice by hand: second call rejected, nothing sent
- git blame on the self-approval check: added in 2024 so creators can't approve their own payments
Not checked
- Partner webhooks look handlers up by string - a 4th caller may exist
- The approval limit in production - £10,000 locally, couldn't read prod config
Assuming
- Payments already waiting for approval keep the old rule
- Scheduled payments above £10,000 wait for a person, like any other payment
The architecture knowledge got you to the right part of the repo. The rebuild told you what that part does right now. The list tells the next person, human or agent, where your understanding stopped.
When someone touches that code again in six months, they start from that list and rebuild from the code, the same way.