Part 3: What Claude Code Actually Reads
This is part 3 of Converge or Diverge, a three-part series about AI coding agents in a large codebase: Part 1: Maintaining Long-Term Code Quality With Agentic AI · Part 2: The Antipattern That Makes a Codebase Diverge · Part 3: What Claude Code Actually Reads (you are here)
(TLDR? Click here to jump directly to the takeaways.)
A week ago I published Part 1. Its thesis is that an AI coding agent multiplies whatever it finds in your codebase. In a healthy codebase the series is telescopic: each change is checked, framed and shaped by what’s already there, and the codebase converges on the quality of its foundation. In an unhealthy one the series is geometric, and each error becomes the example for the next one. The next day, Part 2 supplied the antithesis: the antipattern that starts a geometric series, caught already growing at agent speed in the very codebase I had just called healthy, and the four steps that put it back on course.
Both articles turned on one question, which the first one asked in so many words: what does the agent find when it goes looking? Both answered it with judgment. This one answers it with data.
Claude Code keeps a transcript of every session, and every transcript records every file it opened, every search it ran, every skill it loaded and every test it executed. I had it go back through three weeks of its own transcripts in the Smarter repository and count. The result is a ranked list of the sources that an agent actually uses, how often, and which of them push the series toward convergence. For the avoidance of the same doubt as last time: Claude Code drafted this post, from my notes and from those transcripts, which seems only fitting given the subject.
237 sessions in three weeks
The transcripts cover September 28 to October 17, 2026, on my development machine. That’s the window in which the roadmap shipped, then v0.21 through v0.32, the API contract, the SDKs and the web console’s translations.
| Measure | Count |
|---|---|
| Sessions | 237 |
| Sessions with real work (five or more tool calls) | 212 |
| Sessions that changed source code | 94 |
| Tool calls | 19,327 |
| Of which shell commands | 16,846 |
| Files read before the first edit, median per code-changing session | 8 |
| Files read over a whole code-changing session, median | about 60 |
Two things stand out before we get to the ranking. First, the agent reads mostly through the shell. Only 327 of those calls were the dedicated file-reading tool. The rest of the reading was sed, cat, git grep and git log, which is why the numbers below come from classifying commands, not from counting file opens. Second, it reads a lot more than it writes. A typical code change touched a handful of files, and it was preceded by eight files read and followed by dozens more.
The 94 sessions that changed source code are the fair denominator, because they’re the ones where a source could change what got built. Everything below is measured against them.
The ranking, measured
My notes for this post ranked the sources by judgment, in two lists: guidance, which tells the agent what to do, and feedback, which tells it whether it worked. Here is what the transcripts say. Reach is the share of the 94 code-changing sessions that used the source at least once.
| Source | Kind | Reach | Calls |
|---|---|---|---|
| Searching the existing code | Guidance | 99% | 3,737 |
| Running the unit tests | Feedback | 97% | 1,573 |
| Reading test modules | Guidance | 95% | 3,255 |
| Pre-commit hooks | Feedback | 93% | 903 |
| The Docker runtime | Feedback | 93% | 2,551 |
| Reading the existing source code | Guidance | 92% | 1,045 |
| CLAUDE.md | Guidance | 100%, loaded automatically | n/a |
| Skills | Guidance | 80% | 1,144 |
| git log, git show and git blame | Guidance | 73% | 569 |
| Makefile, docker-compose.yml and CI workflows | Guidance | 63% | 623 |
| The Sphinx docs source | Guidance | 61% | 1,270 |
| The running dev server | Feedback | 61% | 324 |
| Example SAM manifests | Guidance | 30% | 206 |
| YAML test data | Guidance | 30% | 96 |
| Architecture decision records | Guidance | 10% | 71 |
| The sibling repositories (CLI, SDKs) | Guidance | 9% | 495 |
| CI results | Feedback | 7% | 37 |
| Web search and web pages | Guidance | 5% | 23 |
| IDE diagnostics | Feedback | 1% | 1 |
| The Smarter MCP server | Guidance | 0% | 0 |
The judgment held up remarkably well. The sources my notes put in the first group are at the top of the measured list, and the ones it put in the last group are at the bottom. But the measurements do say three things that judgment didn’t: how lopsided the distribution is, how much of the top of the list is feedback rather than guidance, and how much the middle of the list was written by the agent itself.
Guidance: what the agent copies
The existing code, first and always
Smarter’s convention is “pattern first”: find two or three existing implementations of the same kind of change, prefer the newest, read them in full, and copy their structure. The transcripts show that convention isn’t aspirational. Code search appears in 99% of code-changing sessions, source and test reads in more than 90%, and the median session reads eight files before it changes one.
This is the telescope at its most literal. A new resource kind that starts from Guardrail and Secret inherits their ownership checks, their error handling and their logging, so it adds only its difference.
It’s also the geometric series at its most literal. The cache mistake in the second article was pattern-first working exactly as designed: the agent read the nearest example, which happened to be a hand-rolled cache, and faithfully made a fourth one. The existing code is the most powerful source an agent has, and it has no opinion about whether it deserves to be copied. Docstrings ride along with it. The transcripts can’t separate them, because they’re read in the same breath as the function they describe. But that’s also why they matter. A docstring says what a function is meant to do, and it’s the only thing the agent reads that can disagree with what the function actually does.
Whatever the code says is normal, the agent makes more of.
CLAUDE.md and the skills
CLAUDE.md is 151 lines, and it’s loaded into every session automatically, so its reach is 100% by construction. The agent opened it explicitly in only 12 code-changing sessions, which is the point: it never needs to go looking for it. Its most important sentence is the one that tells the agent to load smarter-development first, a skill whose table says which narrower skill covers each kind of work.
Did it? Here’s where the measurement gets interesting. CLAUDE.md was only added on October 7, nine days into the window, so the window holds a natural before and after.
| Code-changing sessions | Loaded smarter-development | Share |
|---|---|---|
| Started before CLAUDE.md existed | 5 of 33 | 15% |
| Started after | 47 of 61 | 77% |
A 151-line file raised the rate at which the agent consulted the project’s know-how from about one session in seven to about three in four. Whenever the skill was loaded, it was loaded before the first edit, which is exactly when it can still change the design. Fourteen sessions after October 7 skipped it anyway, and I’ll come back to those.
The skills themselves grew quickly. They moved into a single skills/ folder on October 5:
| Date | Skills | Lines in SKILL.md files |
|---|---|---|
| October 5 | 14 | 1,418 |
| October 10 | 15 | 1,617 |
| October 12 | 17 | 2,199 |
| October 17 | 24 | 3,341 |
Including their reference files and helper scripts, they’re now about 5,800 lines. The most-used skill isn’t about code at all. It’s smarter-git-commits, loaded in 102 sessions, followed by smarter-development in 84, the Sphinx docs skill in 24 and the Docker skill in 17.
Who writes the skills?
This deserves a precise answer, because it’s the crux of the whole matter. I decide whether a skill should exist and what territory it covers. Claude Code writes it, and it writes it from its own experience of doing that task, usually more than once, after the fact. A skill isn’t a specification written up front by someone imagining the work. It’s an account of the work by the one who did it, including the traps it fell into. Git agrees: 38 of the 45 commits that touched skills/ are authored by Claude, and git blame credits it with about 57% of their lines today. The remainder is committed under my name, which, as in the earlier articles, understates the agent’s share.
The skills also keep changing. Since October 5, 111 commits changed Smarter’s source code, and 33 of them, nearly a third, updated a skill in the same commit. That’s the cancellation step from the second article, institutionalized: a fix lands together with the written rule that prevents its next copy.
A skill is the agent’s experience, written down where the next agent will read it before it starts.
Commit history, which the agent is mostly writing for itself
git log, git show and git blame appear in 73% of code-changing sessions. They answer the question that code can’t: why is it like this? And they’re only as good as the commit bodies they find.
Here the numbers are frankly a little embarrassing. Of the 3,973 commits between January 2025 and September 27, 2026, 160, or 4%, have a body of five lines or more. Of the 448 commits since, 44% do. The median body went from zero lines to three, and the long ones, which explain what was wrong, what changed, how it was tested and what was left undone, now run to dozens of lines. Most of them were written by Claude Code, for a reader who is mostly Claude Code. 😬
That’s a telescoping term the agent is writing for its own future. When it runs git blame on a line next month, it will most likely find an explanation that it wrote today.
The middle and the bottom of the list
The Sphinx source in docs/source was touched in 61% of code-changing sessions, but much of that is the agent writing documentation: it read the docs in 57 sessions, wrote them in 34, and read them without writing anything in 23. Example SAM manifests reached 30%, which fits my notes exactly: essential when the work is on a resource, irrelevant otherwise.
The bottom of the list surprised me more:
- Architecture decision records were read in 9 code-changing sessions. Across all 237 sessions, 36 read an ADR, and 20 of those were writing or revising ADRs at the time. Over the window, the agent edited ADRs more often than it read them. My notes said ADRs had “not yet observed in use”, and that’s essentially right. Their decisions have been distilled into the skills and CLAUDE.md, and that’s where the agent actually reads them.
- Web search and web pages were used in 5 sessions, 23 calls in all. The model’s training covers Django, DRF, Pydantic and Celery well enough that it rarely needs to look anything up.
- The self-hosted Smarter MCP server, which exists as a fallback for the sibling repositories, was called zero times. The local checkouts of the CLI and SDKs were always there, and the agent read them directly in 8 sessions.
The pattern is consistent. The agent reads what is close, current and specific. A source that’s far away, or general, or a step removed from the code, doesn’t get read, however good it is.
Feedback: what tells the agent it’s wrong
Three of the six most-used sources are feedback, and that’s the finding I didn’t expect.
The unit tests ran in 97% of code-changing sessions, 1,573 times in three weeks. The Docker runtime that they need appeared in 93%, and the pre-commit hooks in 93%, 903 times. Those three are effectively one capability: an agent that can sync its edit into the container, run the suite and the linters, and read the result, all without asking anyone.
The running dev server reached 61%, mostly for React and API work where the tests can’t see the page. CI results, 7%, are read but never triggered, because CI is started by hand. IDE diagnostics were used once. The tests already say everything the diagnostics would.
Guidance sets the direction of each term. Feedback is what makes it cancel. A test that fails says exactly what was wrong, the agent fixes it, and the error never becomes an example. It’s no coincidence that the sources the agent relies on most are the ones that can tell it no.
Sources can diverge too
Here’s the part that’s easy to miss. The sources are code, and code can go stale. A stale source is worse than a missing one, because the agent copies it with full confidence.
On October 16, Claude Code moved some notes out of its local memory and into the repository. The commit body is a short catalog of how guidance decays:
- Some facts lived only in the agent’s local memory directory, on one machine. An agent on another machine, or one run by another contributor, never saw them. Memory that isn’t in the repository is a source that only some of your agents have.
- The rule against building the Sphinx docs locally gave a 20-minute build as its only reason. A parallel build had since cut that to about 60 seconds, so an agent could reasonably reason its way around the rule. The skill now gives the real reason.
- The git-commit skill now says that emphatic or frustrated phrasing still asks for the commit command as text, never for running it, because agents had broken that rule in exactly that situation several times.
The DNS outage in the first article was the same failure from the other side: no accurate source of host data, so the agent filled the blank with a plausible guess. And the fourteen sessions after October 7 that never loaded smarter-development are its quieter cousin. Most were small, but a rule that’s skipped one time in four is a rule that’s occasionally not there.
A source that’s wrong is a term in the series with the agent’s full confidence behind it.
Is the measurement any good?
First, it’s one machine and three weeks. Sessions on any other machine aren’t in the transcripts, and neither is the long history of Copilot and human work that built the foundation. These numbers describe how an agent uses a mature codebase, not how it got mature.
Second, the classification is by pattern matching on commands. A sed that prints a test file counts as reading a test, and a grep in the middle of a pipeline doesn’t count as searching code. I tightened the two rules that overcounted, but every number here is an approximation, and the reach of a source says that it was used, not that it changed the outcome.
Third, use isn’t value. The ADRs are rarely read because their content has migrated into the skills, not because they don’t matter, and CLAUDE.md is barely opened because it doesn’t need to be. The judgment-based ranking in my notes is still the better guide to what matters. The transcripts are the better guide to what the agent actually does.
How to measure your own codebase
In rough order of payoff:
- Count what your agent reads. Claude Code’s transcripts are JSON lines on your disk. A short script that classifies tool calls by path and command will tell you which of your sources are carrying the weight and which are decoration.
- Put feedback first. Make the tests, the linters and the runtime something the agent can run alone, in seconds. In Smarter, three of the six most-used sources are feedback.
- Keep the patterns the agent will copy worth copying. It reads eight files before it writes one. Make sure the nearest example is the best one.
- Have the agent write its skills after it does the work, not before. Decide which skills should exist, then let the one who did the task write down how it went, traps included.
- Keep a short, always-loaded file that points to the rest. CLAUDE.md is 151 lines, and it took skill loading from 15% of sessions to 77%.
- Write commit bodies for your agent. It runs git log in three sessions out of four. Give it the reason, not just the diff.
- Move knowledge into the repository. Local agent memory, a pin in your head and a stale reason in a rule are all sources that some of your agents don’t see, or see wrong.
Closing thoughts
The first article said that you choose the ratio of the series over the years before you start the agent. Three weeks of transcripts show where that choice actually lives: in the eight files the agent reads before it writes, in the tests it runs fifteen hundred times, and in a skills folder that it writes for itself, one lesson at a time. The sources aren’t fixed. They’re part of the series, and they converge or diverge with everything else.
Which suggests a small, practical habit. Every so often, count what your agent reads. If its sources are getting better faster than its code is getting bigger, the series is still converging.
Until then, happy Smartering!