The documentation is lying to you
Every system you build starts with a moment of clarity. You write it down: this agent does X, triggered by Y, outputting Z. The documentation is accurate. For about a week.
Then you change a data source. You adjust the trigger schedule. You add an error-handling step. You swap a dependency. Each change is small, each change is urgent, and each change happens without touching the documentation. After six months, the documentation describes a system that no longer exists. It is not merely incomplete. It is wrong. And wrong documentation is worse than no documentation, because no documentation signals "you need to investigate." Wrong documentation signals "you already know" — and sends you investigating in the wrong direction.
This is not a hypothetical problem. GitHub's 2017 Open Source Survey, sampling over 5,500 participants across 3,800+ projects, found that 93% of respondents identified incomplete or outdated documentation as a pervasive problem in software — yet 60% of contributors said they rarely or never contribute to documentation. The gap between documentation's acknowledged importance and the effort actually invested in maintaining it is one of the most consistent findings in software engineering research.
For agents — automated systems that run without you watching — the problem compounds. Code you execute manually gets a human review at every invocation. Agents run on schedules, in response to triggers, in the background. When an agent's behavior drifts from its documentation, no one notices until something breaks. And when it breaks, the first instinct is to consult the documentation, which now actively misleads.
Documentation decay is not entropy. It is a design failure.
The natural framing is that documentation "rots" — that it degrades passively, the way food spoils on a counter. This framing is comforting because it implies the decay is inevitable, something you manage rather than prevent. But documentation does not decay on its own. It decays because the system that creates it and the system that maintains it are disconnected.
When you change an agent's behavior in one place (the code, the configuration, the schedule) and record that behavior in a separate place (a README, a wiki, a comment block), you have created two sources of truth that must be manually synchronized. Every manual synchronization step that can be skipped will eventually be skipped. This is not laziness. It is the predictable result of a system design that treats documentation as a separate artifact from the thing it documents.
Tom Preston-Werner, the co-founder of GitHub, proposed an inversion of this pattern in 2010 with what he called README-Driven Development. The core idea: write the README first, before you write any code. "By writing your README first you give yourself a chance to think through the project without the overhead of having to change code every time you change your mind about how something should be organized or what should be included in the Public API." The README is not a record of what you built. It is the design document that shapes what you build. When the documentation comes first, the code follows the documentation rather than the other way around.
This matters for agent lifecycle because agents are systems you design, deploy, and then step away from. The moment of design — when you are thinking clearly about what the agent should do, under what conditions, with what safeguards — is the moment of maximum clarity. If that clarity is not captured in documentation at the point of creation, it will never be captured at all. You will not remember your design rationale three months later. You will only remember the behavior you observe, and you will confuse current behavior with intended behavior.
The docs-as-code principle: documentation lives where the code lives
The software industry converged on a pattern called docs-as-code, formalized by the Write the Docs community: documentation is stored in the same repository as the code, written in plain text (Markdown, reStructuredText), version-controlled with the same tools (Git), reviewed through the same process (pull requests), and deployed through the same pipeline (CI/CD). The documentation and the code share a lifecycle because they share an infrastructure.
This is not just a tooling preference. It is a structural defense against documentation decay. When documentation lives in the same repository as the agent's code, a change to the agent's behavior and a change to the agent's documentation can exist in the same commit. Code review can enforce the requirement: if you changed what the agent does, show me the corresponding documentation change. The pull request becomes a synchronization mechanism, not because humans are disciplined enough to always remember, but because the process makes the gap visible.
For personal agents — the kind you build for yourself, running in your own infrastructure — the principle still applies even without formal code review. The practice is: never change an agent's behavior without updating its documentation in the same action. Not "after." Not "when I get to it." In the same commit, the same file save, the same editing session. The documentation update is part of the change, not a follow-up task.
What agent documentation must contain — and when to update it
Most documentation fails because it captures the wrong things at the wrong time. A README that describes what the agent does at creation but never mentions what changed, why, or what was tried and abandoned is a snapshot, not a living record. Agent documentation that evolves with the agent needs to cover multiple layers, each updated at different lifecycle stages.
At creation: purpose (why does this agent exist?), behavior (what does it do, specifically?), triggers (what causes it to run?), dependencies (what does it need — data sources, APIs, credentials, other agents?), outputs (what does it produce, where does it go?), failure modes (what happens when things go wrong?), and owner (who is responsible for this agent?).
At every modification: what changed, when, and why. Not just the new behavior — the rationale for the change. Three months from now, you will not remember why you switched from daily to weekly triggers. The commit message might say "changed schedule." The documentation should say "switched from daily to weekly because the upstream data source only refreshes on Mondays, making daily runs redundant and increasing API costs without benefit."
At periodic review: is the agent still serving its original purpose? Have its dependencies changed? Are its failure modes still accurate? Is the owner still the owner? This is the maintenance window described in the previous lessons — and the documentation review is a core part of that window.
At retirement: what happened, why the agent was retired, where its responsibilities went (if anywhere), and what can be learned from its lifecycle. This is the archaeological record that makes agent succession (L-0590) possible rather than accidental.
Model cards: documentation that discloses limitations
The machine learning community encountered the documentation lifecycle problem at scale and developed a structured response. In 2019, Margaret Mitchell, Timnit Gebru, and colleagues at Google published "Model Cards for Model Reporting" in the proceedings of the Conference on Fairness, Accountability, and Transparency. Model cards are standardized documentation that accompanies a trained ML model, disclosing not just what the model does but its intended use cases, evaluated performance across demographic groups, limitations, and ethical considerations.
The key insight from model cards is that documentation should disclose constraints, not just capabilities. Most agent documentation describes what the agent does when everything works. Model cards require you to document where the model fails, which populations it underserves, and what conditions produce unreliable results. Applied to personal agents, this means documenting not just "this agent summarizes my weekly reading" but also "this agent performs poorly on technical papers longer than 20 pages, tends to miss nuance in non-English sources, and occasionally hallucinates citations when the input is ambiguous."
Documenting limitations is uncomfortable because it forces you to confront the boundaries of a system you built. But those boundaries exist whether you document them or not. The only question is whether the person relying on the agent — including future you — discovers the limitations through documentation or through failure.
Evergreen documentation: the Matuschak principle applied to agents
Andy Matuschak's concept of evergreen notes offers a useful model for how agent documentation should work. Matuschak describes evergreen notes as "written and organized to evolve, contribute, and accumulate over time, across projects." They are not transient records of what you thought at one moment. They are living artifacts that you return to, refine, and connect to other artifacts as your understanding deepens.
Most documentation is transient by design. You write it once, at the point of creation, and treat it as finished. Evergreen documentation is designed to be revisited. The format invites revision: short, atomic sections rather than monolithic blocks. Each section can be updated independently. Each section is dated, so you know when it was last verified. The document as a whole is a living record, not a historical snapshot.
For agents, this means structuring documentation as a set of discrete, updatable claims rather than a narrative essay. Instead of a flowing paragraph that describes the agent's behavior, use a structured format where each aspect — purpose, triggers, dependencies, failure modes, changelog — has its own section that can be independently verified and updated. When you review an agent during a maintenance window, you can walk through each section and confirm or correct it without having to re-read or re-write the entire document.
The deeper principle from Matuschak is that the act of maintaining documentation is itself a thinking practice. When you revisit an agent's documentation and discover that three claims are outdated, you are not just fixing text. You are confronting the gap between your mental model of the agent and its actual behavior. That gap is valuable information. It tells you how much the agent has drifted since you last paid attention — and, by extension, how much of your cognitive infrastructure may be running on stale assumptions.
Self-documenting systems are a myth — but self-revealing systems are possible
There is a persistent belief in software engineering that code can be "self-documenting" — that with clear naming conventions, small functions, and good structure, documentation becomes unnecessary. Hillel Wayne, a formal methods consultant and writer, addressed this directly: "Self-documenting code is a myth. Code tells you what a system does. It cannot tell you why it does it, what alternatives were considered, what constraints shaped the design, or what the system is not supposed to do."
Donald Knuth proposed a more radical alternative in 1984: literate programming, where the primary artifact is a document that explains the program's logic in natural language, with code woven in as supporting detail. The documentation is not a supplement to the code. The code is a supplement to the documentation. This inverts the typical priority and ensures that the explanation of intent is always the primary artifact.
For agents, neither pure self-documenting code nor full literate programming is practical. But the principle of self-revealing systems is. A self-revealing agent is one that emits structured metadata about its own state: when it last ran, what inputs it consumed, what outputs it produced, whether it encountered errors, and how its current behavior maps to its documented purpose. This metadata does not replace documentation. It supplements it by making the gap between documented behavior and actual behavior automatically visible.
The simplest version: every agent run produces a log entry that includes not just "success" or "failure" but a summary of what actually happened. When the log summary and the documentation summary diverge, you know the documentation needs attention. The system reveals its own documentation debt.
The documentation lifecycle mirrors the agent lifecycle
Documentation is not a separate artifact that happens to be associated with an agent. It is a structural component of the agent itself — as essential as the code, the configuration, and the trigger schedule. An agent without documentation is an agent that will become a legacy agent (L-0596), because the institutional knowledge about what it does and why it exists lives only in the memory of its creator, and memory is unreliable and temporary.
The documentation lifecycle has the same stages as the agent lifecycle: creation, deployment, active maintenance, periodic review, evolution, and retirement. At each stage, the documentation changes in a specific way. At creation, it captures intent and design. During active maintenance, it records modifications and rationale. During periodic review, it is verified against reality. At retirement, it becomes the archaeological record.
When documentation fails to keep pace with the agent, the result is not just inconvenience. It is the precondition for agent sprawl — the subject of the next lesson. You cannot prune what you cannot understand. You cannot evaluate what you cannot describe. And you cannot describe what you never documented, or documented once and then forgot. The cost of agent sprawl (L-0598) is, in large part, the accumulated cost of documentation that stopped evolving when the agent did not.
Every agent you maintain is making a bet: that future-you will remember what present-you knows. Documentation is how you hedge that bet. And like all hedges, it only works if you maintain it.