Why I run an interactive codebase tour after every milestone to keep my mental model current.
A milestone can be done and still not be fully installed in your head.
I’m building a sizeable software product with agents doing most of the implementation work. I’m still scoping the work, attaching it to milestones, reviewing PRs, maintaining the docs, and keeping business-critical decisions human-in-the-loop. The individual pieces generally make sense, but the whole picture still needs reassembly.
That’s why I started running a guided tour of the codebase after each development milestone.
Manual development had a hidden benefit
When implementation was slower and manual, it forced a certain kind of understanding. You touched the files yourself. You followed the call chain. You hit the strange edge case, fixed it, and remembered it because it ruined your afternoon.
The process was inefficient, but the pain was a pathway to build an intimate mental model of the system.
Agentic development compresses that implementation loop - free of pain and free of comprehension. Now that comprehension must be operationalized and become part of the new workstream.
The job moved up a layer
I spend less time thinking about every line of implementation and more time thinking about system design, milestone boundaries, trade-offs, and how to steer a group of agent workstreams without letting them invent a second product.
That requires a different kind of understanding.
I need to be able to explain how a feature works, how the pieces connect, what is complete, what remains, and where the specification still has gaps. I need enough of the current system model to make the next decision without treating the repository like a vending machine.
PR review helps. Good documentation helps. Tests help. None of those automatically reassemble the whole system in my head.
So I added a comprehension pass.
The guided-tour ritual
After a milestone is complete, I ask an agent to walk me through the current state of the codebase using a constrained format:
- One key idea at a time
- A tiny code excerpt
- A plain-English model
- A quick check-your-understanding question
- A pause for me to say
next, ask a question, or zoom in or out
The full skill is available in guided-tour/SKILL.md.
The pause does work here.
A normal agent summary tends to produce a wall of fluent text that sounds useful. I can nod along with most of it, but ten minutes later I discover that I recognized the words without building a durable model.
The guided tour makes the agent stop after one idea. I have to decide whether I understand it before moving on. If I don’t, I can ask for another example, zoom in on the implementation, or back up to a higher-level explanation.
It is closer to being shown around a building than receiving the building’s entire floor plan as a JSON blob.
Different artifacts, different jobs
This does not replace specs, documentation, tests, or PR review. Those already have jobs, and my docs hygiene is not the problem.
Specs describe intended behavior. Documentation records the structure and decisions. Tests define constraints and protect behavior. PRs explain what changed.
The guided tour handles a different job: helping the human rebuild a coherent model of the current system after a meaningful amount of work has landed.
PR-by-PR understanding is still fragmented understanding. Each PR can make sense on its own but it can be difficult to see the bigger picture - how it fits with the product, why it should exist, how it integrates with the previous 5 PRs I just reviewed.
That’s important when it’s time to steer the next phase, explain the product to another person, or find the gap between “implemented” and “actually specified.”
A guided tour has already helped surface all three kinds of gap:
- work I thought was complete but wasn’t
- behavior that existed in code but was missing from the spec
- concepts I had encountered individually but never connected into one model
- discovery that reveals a need for additional tweaking
That is useful information. It arrives before the next milestone builds on top of the misunderstanding.
Comprehension is part of the milestone
I now treat the guided tour as part of completing a milestone.
The work is not fully done for me until I can explain what changed, how the pieces fit, what still needs attention, and where I need to look more closely.
Intentional human involvement in agentic workflows, guided comprehension, and guided learning inside production codebases have become recurring themes in my work. They’re the most human parts of the workflow, and for me, they’re what keep the output connected to the original vision.
Check out some of my other posts about how I work with AI agents: