Where the team's memory lives now

Engineering teams have, for a long time, kept their memory in three places. The code held the team’s decisions in compressed form — a name that means something, a structure that implies a constraint, a comment that explains a choice the reader would otherwise have to reverse-engineer. The docs held the same memory, less voluminously and more deliberately — what the team decided, what they tried, what they would rather not learn the hard way again. And the people held the rest, in their heads — the conversations from the planning meeting, the failures from the last project, the way Mike likes to be asked about the auth module before anyone touches it.

These three sources had different strengths. Code was high-fidelity but slow to read and quick to lose intent under maintenance. Docs were compressed and curated, but suffered the well-known maintenance lag. People were the highest-fidelity source — you could ask follow-ups, get the context behind the context — but they leave, forget, and are sometimes in a meeting. Together, the three covered the team’s collective memory well enough to operate on.

AI tools thinned out two of the three. The code, increasingly, does not carry intent the way it used to: the names are plausible rather than precise, the structures are idiomatic rather than chosen, the comments describe what rather than why. And the people have gotten thinner too, in a quieter way: they did not author much of what is in the codebase, so they cannot reconstruct decisions they never made. The git blame returns a name; the name does not have the answer.

That leaves docs. Of the three sources, docs are the only one whose information density did not directly degrade under AI adoption. They became, by elimination rather than by design, the team’s primary external memory — and most teams have not yet rewritten what they write down to match the new role. The cost shows up later, in the form of decisions nobody can reconstruct and conversations the team has to have a second time.

Four observations about how this reshapes documentation, in order from the documents that gained value to the documents that have to start being written.

1. The documents that gained value

The documents that gained value were the ones already carrying the kind of information the code and the people stopped carrying. Their value did not change because the docs got better; it changed because the alternatives got worse.

The most-mentioned example is the why-comment — the inline note explaining a choice the reader could not infer from the code itself. These comments were always more valuable than what-comments (which describe what the code does, and which the code does on its own); the difference is that AI tools widened the gap. What-comments are now nearly worthless, because the model produces them on demand and a team can manufacture them at no cost. Why-comments are the only inline notes that retain information the model could not regenerate, and so are the only ones worth investing in.

Less-mentioned but more important are design records. The ADR, the RFC, the long Slack message pinned to a channel — whatever a team calls the document where they record what they decided and why. These have always been undervalued; the asymmetry between writing them (slow, deliberate, costly to the writer) and reading them (rare, often years later, by someone coming to the question from a different angle) made them fall off most teams’ priorities. AI changed the math without anyone announcing it. The team’s design thinking is now durable nowhere except in these documents. If they are not written, the thinking does not survive.

The timing question matters as much as the existence question. A team that writes design records after shipping is writing reports; a team that writes them before committing to a direction is writing instruments. Reports are nice to have. Instruments shape decisions. The shift in role — from documentation as record to documentation as decision-making tool — is the real change in this category, and it requires teams to write earlier than they are used to writing.

The third underrated category is the substantive README. Not the boilerplate one that is generated from the package metadata; the curated one that explains what the codebase is for, what its conventions are, where the seams are. These have always been valuable, and they have always been underwritten because writing them costs an afternoon and reading them, for any one person, costs ten minutes. AI shifted the cost-benefit. A substantive README is now read more often, by more readers, including readers who are tools — and the audience expanded faster than most teams’ authoring habits did.

2. The documents that lost value

Some documentation got actively cheaper to skip. The model produces it on demand, in better quality than most teams produced it manually, with no maintenance cost. Continuing to invest in this category is decoration; the resources are better spent on the categories above.

The clearest example is autodoc-generated API references. Type-derived API documentation — list of functions, list of parameters, list of return types — was always low-value because it duplicated what the type system already expressed. The model can now generate it from source as needed, and read it as needed without the team curating it. Teams still maintaining a separate docs site whose content is mechanically derivable from the code are paying for an artifact whose information value is roughly zero.

Another is the framework explainer. The internal wiki page that explains how to use the team’s chosen ORM, queue library, or test framework — usually written years ago, partially out of date, partially still useful. The model knows these frameworks at the level the explainer was teaching them; juniors no longer benefit from the team’s curated version more than they would benefit from asking the model directly. The version-specific gotchas and the team-specific patterns are still valuable. The general explanation of how the framework works is no longer the team’s job.

The same applies to what-comments. The verbose docstring that paraphrases the function’s behavior in English. Worthwhile in 2015. Decoration in 2026. Teams still grading PR reviewers down for missing docstrings on internal helpers are spending review attention on the wrong artifact.

The reflex against this is but documentation is good. In a generic sense, sure. In an opportunity-cost sense, no — the time spent maintaining what-comments and autodoc sites is time not spent maintaining the design records and trust maps that actually carry information now. Pretending all docs are equally valuable is the documentation equivalent of pretending all metrics are equally calibrated.

3. The documents that have to start being written

Some documents that no team kept five years ago are now structurally required, because the work that produced them was previously absorbed by the code and the people, and is now absorbed by neither.

The most important is the acceptance rationale — a short note attached to AI-authored merges explaining what was accepted, what alternatives the model proposed that were rejected, and what constraint dictated the chosen direction. This is the artifact that compensates for the I accepted, I did not author gap. Teams that build the habit of writing it embed design thinking into the merge record itself, where it is found by every future reader of the code. Teams that don’t transfer the cost forward, into onboarding sessions and incidents and the senior engineer’s slow rebuild of why decisions were made.

A close second is the trust map — a team-level document marking which regions of the codebase the team has high, medium, or low confidence in, and why. It does not need to be elegant; a directory-by-directory annotation in a single page is enough. It exists to short-circuit the folklore that would otherwise carry this information from senior to senior, and to give new joiners and the on-call rotation a navigable view of where the patina is thinnest. Most teams have this knowledge somewhere in their collective head. Putting it on a page costs an afternoon and saves quarters of work later.

A useful third is the disagreement log — a running record of moments where the team explicitly chose not to follow the model’s suggestion, with the reasoning. Each entry is short; the value is cumulative. The log doubles as a calibration aid for new team members (here is what we have learned to push back on) and as a pattern catalog for senior reviewers (these are the failure modes our codebase tends to exhibit). It is a unique artifact: there is no pre-AI equivalent because there was nothing to disagree with at this scale. Teams that start one early build a quiet competitive advantage in the form of accumulated calibration that does not exist on dashboards or in code.

There are others — failure-mode catalogs specific to the codebase, spec histories that track what was specified versus what got built, integration-contract logs for cross-team systems — but the three above are where the gap is widest and the cost of writing is lowest. A team adopting AI tools meaningfully should treat these as starter artifacts, not optional ones.

4. The new reader

The audience for documentation expanded, quietly. Documents now have three classes of reader: humans on the team (the same as before), humans not yet on the team (the same as before, but more frequent because onboarding got harder), and models — the AI tools that read documents to inform what they generate.

The model-as-reader is a category most teams have not yet thought about. The reflex is to write docs the way they have always been written, for human readers. The model reads them anyway, and what it generates next reflects what it found. A team’s coding style, naming conventions, error-handling patterns, integration norms — all of these get reinforced or eroded depending on whether the model has clear documentation of them or has to infer them from the codebase’s accumulated patina. Documentation is now, partially, prompt engineering for the team’s own AI usage.

This sounds reductive and is not. Writing for a model-reader is not different in kind from writing for a careful human reader: in both cases the doc benefits from being explicit, organized, and situated. The shift is that the team has more incentive than it used to have to write docs that spell out the conventions the codebase is supposed to exhibit, because those docs now influence what the codebase becomes. A team that writes “we handle errors this way, not that way” gets, on average, more code that handles errors that way. Pre-AI, the convention was transferred via review and apprenticeship. Post-AI, it is partially transferred via what the model finds when it goes looking.

The teams that internalize this start writing a different kind of document — explicit conventions, explicit anti-patterns, explicit examples of what good looks like in this codebase. Not because the human readers needed them more (they didn’t), but because the model reader needed them, and the team is the audience that benefits from the model’s improved output.

Closing

A team’s memory used to be redundant — code, docs, and people held overlapping copies, and the loss of any one was buffered by the other two. AI tools thinned that redundancy. Code and people both got worse at carrying intent, and the burden landed on docs without anyone making the assignment explicit. The teams that have noticed are restructuring what they write down — investing in the documents that gained value, retiring the ones that lost it, and starting on the artifacts that did not exist as a category five years ago.

The conversation about what to write down now, deliberately, is one of the cheapest interventions a team can make. It does not require new tooling, new headcount, or leadership endorsement. It requires three things: a list of what each existing document is currently doing, a decision about which to keep and which to retire, and a commitment to start the artifacts that did not exist as a category five years ago — acceptance rationales, trust maps, disagreement logs. The conversation takes an afternoon. The artifacts take, in aggregate, a few weeks of work spread across a quarter. The teams that have it accumulate a memory architecture that holds up under the new conditions; the teams that don’t are still operating on the documentation habits of a different decade, with the predictable result of having to relearn, again, things they decided once and forgot they had decided.