When you wrote code yourself, you got something for free that you did not notice you were getting. Every time you typed a function you were also reading the functions next to it. Every time you renamed a variable you were taking quiet inventory of where it was used. Every time you opened a file to add a feature you were refreshing your mental model of how that file fit into the rest of the system. You did not call it documentation. You did not call it learning. It was just a side effect of doing the work.

That side effect is gone now.

When Claude Code writes the function, you do not read the functions next to it. When the agent renames the variable across the codebase, you do not see the seventeen places it touched. When a feature gets added to a file, you may not have opened that file in months. The work still happens. The byproduct does not. The map of the territory that you used to build slowly, walk by walk, no longer builds itself.

This is the part of agentic coding I did not see coming. Not the bugs, not the hallucinations, not the runaway diffs, all of which are real but manageable. The thing that quietly erodes a codebase is that your mental model of your own software decays faster than you realize, and the tool that is supposed to help you depends entirely on the quality of the model that surrounds it.

What the Agent Actually Reads

It is worth being precise about what an agent like Claude Code is doing when you ask it to add a feature. It is reading your code. Not all of it, because no agent has infinite context, but enough of it to figure out where to put things, what to name them, which patterns to follow, which libraries are in use, and which conventions seem to hold. It is, in a very literal sense, doing what a new hire would do on their first day. Looking around. Inferring norms. Building a mental model.

The difference is that a new hire takes weeks to build that model and then gets to use it for years. Your agent rebuilds the model from scratch every session, and the only material it has to work with is the code itself, plus whatever documentation you have pointed it at. It cannot ask the founder why something was structured this way. It cannot remember a Slack conversation from six months ago. It cannot intuit your taste from your past work. All it has is what is in front of it.

This means two things, and they are the foundation of everything else in this post. First, whatever organization you have in your codebase will be amplified, in both directions. A clean structure will produce cleaner output because the agent will pattern-match on it. A messy one will produce messier output for the same reason. Second, the things that live in your head, the architectural intent, the reasons certain choices were made, the constraints that are not visible in the code, do not exist as far as the agent is concerned unless you write them down.

The Patterns You Establish, Multiplied

The first time I noticed how literally the agent imitates the code it sees, I had a small inconsistency in a Rust module at Rheon. Two adjacent files used slightly different error-handling styles. One used a custom Result alias with a project-wide error enum. The other had drifted into using anyhow because it had been written quickly during a refactor and never cleaned up. Neither was wrong on its own. The codebase had just accumulated a small inconsistency I had been meaning to fix.

I asked Claude Code to add a new function to the module. It picked one of the two styles, more or less at random based on which file it had read most recently. A week later, after several more sessions, the codebase had drifted further in both directions. The original inconsistency had become a four-way inconsistency. Nobody had decided this should happen. The agent had simply pattern-matched on whatever was nearest, and over enough iterations, the lack of a single canonical example had compounded into noise.

The lesson is that your codebase is now a teaching corpus. The agent learns from it on every invocation. If your code teaches it that there are three ways to handle errors, the agent will keep producing all three. If your code teaches it that there is one way, the agent will reinforce that. Inconsistency does not decay over time when an agent is in the loop. It grows.

Which means the cleanup work that you used to be able to defer, the small refactors that everyone agrees are good ideas but never quite urgent, are no longer optional. They are upstream of every line the agent will write next. A two-hour refactor that consolidates patterns will pay dividends across hundreds of future sessions. The leverage is not in the cleanup itself. It is in what the cleanup teaches the agent to do.

The Document That Replaces Your Head

There is a class of knowledge in every codebase that does not live in the code. It lives in the head of whoever wrote the system. It includes things like why a particular service is split off from the monolith, why the database has this particular index, why this directory exists at all, why a function signature looks deliberately ugly because it has to match a third-party API that is even uglier. None of this is in the code. The code shows the what. The code rarely shows the why.

When you were the only one writing code, you could afford to leave most of this in your head. You were the only consumer. Future you would remember, mostly, and the parts you forgot you would re-derive in an afternoon. The cost of not writing it down was low because you and the codebase were essentially the same entity.

With agents in the loop, you and the codebase are not the same entity anymore. There is a third party reading your code on every session, and that third party has no memory between sessions, and that third party is now writing meaningful portions of what gets shipped. If the architectural intent only exists in your head, the agent has no access to it. It will pattern-match on the code, infer something plausible, and produce work that looks consistent with what is there but conflicts with what you actually wanted.

This is why high-level documentation has gone from a nice-to-have to the most leveraged thing you can write. Not API docs. Not function-level comments. Those are mostly for humans, and the agent can usually figure those out. I mean the documentation that explains the shape of the system. What the modules are for. How they relate. Where the boundaries are. What the rules are. What you will accept and what you will not.

A good architecture document is now worth ten thousand lines of generated code, because it is the thing that determines whether those ten thousand lines fit together or fight each other.

CLAUDE.md and the New Top-Level Artifact

This is where the convention of a top-level instructions file comes in. Claude Code reads a CLAUDE.md at the root of your repo automatically, and other agents have similar mechanisms. The temptation is to treat this file as a place for prompt tweaks. Tell the agent to use tabs not spaces. Remind it which test runner you use. Useful, but underwhelming.

The real value of that file is as a place to externalize the parts of your taste and your architecture that you would otherwise keep in your head. What kind of project this is. What the major components are and how they relate. Which patterns are canonical and which are deprecated. What the rules of the codebase are, the actual rules, the ones you would tell a new senior hire over coffee on their first day. The rules that say “we never do X, even though it would be tempting, because of Y.”

These are not instructions for Claude in the sense of “please be helpful.” They are the operating manual of your codebase, and they happen to be the file the agent reads first. Writing it well is one of the highest-leverage things you can do, because every future session inherits it. Skipping it means every future session starts blind.

What I have come to do, both at AlgoCademy and at Rheon, is treat this file as a living document that I update whenever I make a real architectural decision. The decision becomes a paragraph. The paragraph goes in the file. The next time the agent works on something adjacent, the decision is already in scope. I do not have to remember to remind it. I do not have to hope it will infer correctly. The intent is written down, and the agent acts on it.

Structure as Communication

There is a related discipline that gets less discussion, which is that the structure of your repo is itself a form of documentation that the agent reads. Directory names matter. File names matter. The fact that you put auth in its own module and not in utils matters. These are signals, and the agent picks them up.

When the structure of your codebase is a clear expression of how you think about the domain, the agent’s output will tend to follow that thinking. When the structure is historical, accumulated, full of names that made sense at one point and no longer do, the agent will produce work that reflects that confusion. It will put a billing-related function in a directory called helpers because that is where it found something similar. It will name a new service after the pattern it inferred from the inconsistent ones around it.

Naming and structure used to be soft skills, mostly about making the codebase pleasant for humans. They are now hard skills, because they are also the input format for the tool that is doing more and more of your typing. A repo whose structure does not reflect its current architecture is a repo whose agent output will be subtly wrong in ways that are hard to catch in review.

You Are Not Reading Every Line

The reason all of this matters more than it used to is that you, the human, are no longer reading every line that gets written. You used to. Maybe you did not write every character yourself, but at least you read every diff seriously, because the diffs were small enough that this was possible. With agents in the loop, the diffs are bigger and more frequent and you are increasingly approving them based on a higher-level read. Does the change touch the right files. Do the tests still pass. Does the shape of the change match what I asked for. You are not, realistically, going to scrutinize every line of a five-hundred-line agent-produced PR with the same care you used to bring to a fifty-line one of your own.

This means the line-by-line review that used to be your last line of defense is no longer reliable. The defense has to move upstream. It has to live in the structure of the codebase, the conventions the agent is patterning on, and the documents that tell it what is and is not acceptable. By the time the code is in front of you, the question is not whether each line is correct. The question is whether the system the agent built itself within is one that produces correct code by default.

If the answer is yes, your loose review is mostly fine. If the answer is no, your loose review will let problems through, because nobody is reading carefully enough to catch them.

What Happens When You Skip This

The failure mode of skipping the documentation and organization work is not dramatic. It is slow. It looks like a codebase that is technically growing but feels harder to work in every month. It looks like agent sessions that produce reasonable-looking code that turns out, on closer inspection, to violate some rule you assumed everyone knew. It looks like duplicated abstractions, parallel implementations of the same idea, modules that no longer have a clear purpose because three different agents in three different sessions added things to them that did not quite belong.

It looks, in other words, like the codebase of a team that grew too fast and never wrote anything down. Which is exactly what your codebase is, now, structurally, even if you are still the only human on the project. The agent is the new hire. Many new hires, all hired this week, none of whom will be here next week. Onboarding them is now part of your job. Onboarding documentation is no longer a courtesy. It is the substrate that makes the work possible at all.

What to Actually Write Down

If I had to compress the practical version of this into a single paragraph, it would go like this. Write down what your project is and what it is not. Write down the major components and their boundaries. Write down the patterns that are canonical and the ones that are deprecated. Write down the constraints that are not obvious from the code, especially the ones that exist for external reasons. Write down the decisions you have already made that you do not want re-litigated, and the reason for each. Keep it in the place the agent will read first. Update it when the architecture changes. Treat it as production code, because for all practical purposes it now is.

Everything else, the function-level docstrings, the inline comments, the README that explains how to install dependencies, all of that still matters, but it is not where the leverage is. The leverage is in the document that explains how the system thinks. That document used to live in your head. With agents in the loop, your head is not a place the team can read from anymore.

The Job You Actually Have Now

The shift, if I had to name it, is from being the person who writes the code to being the person who maintains the conditions under which good code can be written. The agent does the typing. You do the architecture, the conventions, the boundaries, the documentation, the cleanup. These were always part of the job. They were just easier to neglect when you were also the one doing the typing, because the typing forced you to keep some of it in your head whether you wanted to or not.

That forcing function is gone. The work it was protecting is not. If you do not pick it up deliberately, it does not get done, and the codebase suffers in ways that compound quietly until they are expensive to undo.

The good news is that this is mostly a discipline problem, not a tooling problem. The documentation you should write is documentation you already know how to write. The conventions you should establish are ones you already have opinions about. The structure you should impose is one you can already see in your head. The only thing that has changed is that these artifacts are now load-bearing in a way they were not before, and the cost of not producing them is no longer paid only by future humans. It is paid, every session, by the agent that is sitting at your keyboard right now.

The map you used to build for free is the map you have to draw on purpose now. Drawing it well is the job.