Your AI Wrote the Code. Who Understands It Now?

From the team behind aidrop.it — one workspace to build, host, and keep changing your code.

An agent can produce a working application in an afternoon. It picks a structure, names things, chooses a storage approach, and leaves a README that reads like the work of a careful team.

Six weeks later somebody needs to change one behaviour in it. They open the repository and find code nobody in the room wrote, arranged by decisions nobody in the room remembers making — sometimes two applications sharing it, for reasons equally unrecorded.

This is the comprehension gap, and it is different from technical debt. The code is not bad. It is unexplained. Every question that a original author would have answered in a sentence — why this queue, why this table shape, what the retry is protecting against — now costs an hour of reading, or a guess.

Generated code is not self-documenting, however clean it looks

Readable code tells you what happens. It does not tell you what was considered and rejected, which constraint forced an awkward shape, or which part is load-bearing versus incidental.

A human author carries that context and hands it over in review, in a hallway, in a commit message written while the reason is fresh. An agent produces the artefact and the reasoning evaporates with the session. What survives is output without argument — the hardest kind of code to change safely.

The gap widens with every session. A second agent, given the same repository and no record, re-derives an answer that may not match the first one, and now the codebase disagrees with itself in a way no test will catch.

The question is not "can AI maintain it" but "what does it read first"

An agent can maintain code it did not write, and does it well when it starts from more than the files. It needs the same things a new engineer needs: what this project is for, which decisions are settled, what must not change, and where the sharp edges are.

Without that, each session begins by reconstructing context from source — expensively, and often wrongly. This is the ceiling that file-based agent memory runs into: a rules file helps until the project outgrows what one file can hold, and it never records why a rule exists.

Retrieval matters more than volume here. Feeding a whole repository into a window is the approach that makes a bigger context window backfire — the relevant fact gets buried among thousands of irrelevant ones.

Record the decision at the moment it is made

The cheapest time to capture why is while the reason is still in someone's head. The most expensive is six weeks later, from the code, by inference.

Three habits close most of the gap:

• Write down what was rejected, not only what was chosen. "We use an outbox table because the broker was not on the plan" prevents a future agent from helpfully replacing it.
• Make the rules a project owns explicit and versioned. Skills give an agent a repeatable procedure instead of a fresh opinion each time, and a versioned rule leaves a trail when it changes.
• Keep the record where the next reader will look. A decision in a chat log is a decision that is gone. What is deployed right now is not a decision, though: the next session should read that from the host, not from a note.

None of this slows the build much. It changes who can pick the project up afterwards — which, for software that outlives the session that created it, is the only property that compounds.

FAQ

Is AI-generated code harder to maintain than human-written code? Not inherently. It is harder to maintain when the reasoning behind it was never recorded, which is the common case — the artefact is kept and the argument is discarded.

Should I just ask the agent to explain the code later? It will produce a plausible explanation from the source. That is a reconstruction, not a record, and it can be confidently wrong about intent.

What is the minimum worth writing down? The constraint that forced an unusual shape, the thing that must not change, and the owner. Everything else can be re-derived; those three cannot.

Where should that record live? Somewhere both people and agents read on the way in, versioned so a change leaves a trail. A shared project context — the approach aidrop.it takes — keeps it retrievable across tools rather than trapped in one client's session.

Does this apply to small projects? More, if anything. Small projects are the ones handed off casually, with no team around them to remember — see inheriting a codebase you did not write.

Cover: https://unsplash.com/photos/PlBsJ5MybGc by Tolu Olubode on Unsplash. Alt text: A concrete building under construction, its floors and orange support props exposed before the walls go up.