Docs-as-code was already the right idea before any of this. Put the documentation in the repo, change it through pull requests, review it next to the code, run it through CI. Docs on the same track as the code, so they move together instead of drifting into a wiki nobody trusts. If you were doing it, you were ahead.
Then the reader changed. Your docs are no longer read only by humans onboarding or looking something up. They are read by agents, before those agents write a single line, to decide what to build and how. That one change turns docs-as-code from a healthy discipline into part of the build, and treating it as anything less is how agents end up confidently building the wrong thing.
Docs-as-code, quickly, because the reader is smart
The mechanics are not the interesting part, so I will be brief. Documentation lives beside the code it describes. It changes in the same pull request that changes the code. A reviewer sees both diffs together. CI can lint it, check links, build the site. Nothing exotic. The whole value is a single track: when the code moves, the doc is right there in the same change, hard to forget.
The alternative, docs in a separate system updated whenever someone remembers, is the one that rots. Everyone has read a wiki page that describes a system two rewrites out of date and had to reverse-engineer the truth from the code. Docs-as-code exists to make that failure harder.
The reader is now a machine, and it does what the docs say
Here is what genuinely changed. A stale doc used to cost a human a confused hour before they checked the code and figured out the truth. Annoying, survivable, self-correcting, because humans distrust docs and verify.
An agent does not verify by default. It reads your AGENTS.md, your CLAUDE.md, your architecture notes, and it treats them as instructions. AGENTS.md is emerging as a shared convention precisely for this: a predictable place to put the setup steps, conventions and constraints an agent should follow. That is powerful and it is a loaded gun. If the file says the auth service lives at a path it no longer lives at, or that you use a library you migrated off two months ago, the agent does not shrug and check. It builds on the lie, confidently, at speed.
So the stakes flipped. Docs used to be output, a thing you produced for humans after the work. Now a chunk of your docs are input, a thing agents consume before the work. Output can be a little stale and merely embarrassing. Input that is stale is a defect that ships.
And it compounds. One agent reads the wrong path, builds against it, and leaves behind code and commits that quietly ratify the mistake. The next agent reads that as confirmation. A single stale line does not stay a single stale line, it seeds a small pile of work that all agrees with itself and all points the wrong way, and unwinding it costs far more than the doc fix would have.
The docs pipeline belongs in the build
If agents depend on the docs, then keeping the docs true is a build concern, not a documentation-team chore. Two moves follow from that.
Generate what you can from the code. Anything that can be read off the source, the module map, the routes, the public interfaces, the list of services, should be generated, not hand-maintained. Hand-maintained facts drift the instant someone is in a hurry. Generated facts cannot lie about the code, because they are read from it. This is the same spirit as code as documentation: the closer the doc sits to the source of truth, the less room there is for it to quietly diverge.
Gate on drift for the rest. Not everything can be generated. The “why,” the constraints, the decisions still need to be written. For those, the build should fail when a documented fact and a real fact disagree. If a doc claims a file exists and it does not, break the build. If it references an endpoint that was deleted, break the build. You already gate on tests. Gate on the docs your agents are about to trust, for the same reason: to stop a false statement from reaching production. This is docs-as-code taken to its conclusion, where the docs pipeline runs on the same track and fails on the same standard as the code.
None of this asks anyone to write more prose. It asks the pipeline to stop letting the prose lie.
Your rules files are the highest-leverage docs you own
Not all docs carry the same weight now. A tutorial that goes stale wastes a newcomer’s morning. A stale line in CLAUDE.md or AGENTS.md is executed by every agent on every run, silently, at scale. The blast radius is completely different, and the maintenance priority should be too.
I treat those files the way I treat configuration that ships to production, because functionally that is what they are. Every claim in them is an instruction some agent will act on without checking. So the bar is not “is this roughly accurate.” It is “would I be comfortable if an agent followed this literally at 2am with nobody watching,” which is exactly what happens.
That reframing changes what belongs in them. Vague aspirations and half-true conventions are worse than nothing, because an agent cannot tell an aspiration from a rule. Concrete, current, verifiable statements earn their place. Everything else is a landmine you wrote yourself. The discipline is not writing more of these files. It is keeping the few lines in them ruthlessly true, and letting the build catch you when they are not.
Living, not just versioned
Versioned docs are not automatically alive. A doc can be in the repo, reviewed, in CI, and still describe a system that changed in a commit that did not touch it. Docs-as-code gets docs onto the same track as the code. It does not guarantee they move.
What moves them is a connection to the code that keeps the two in sync, so a change in one surfaces staleness in the other. That is the difference between a doc that is merely versioned and one that is living documentation, docs that stop rotting because the system notices when they no longer match. And it is the same engine behind a product brain that maintains itself: the knowledge updates as the code moves, rather than waiting for a human to remember. Quality internal documentation is one of the practices that most reliably predicts whether a team handles change well, and “reliably predicts” only holds when the docs are true, which is the whole problem the pipeline has to solve.
Where PaellaDoc fits
PaellaDoc builds the connection docs-as-code is missing. It reads your repo into a graph of code, decisions and criteria, keeps it current as the code moves, and can surface when a documented fact no longer matches the source, so the instructions your agents read are the ones that are still true. The docs stop being a thing you maintain out of guilt and become an input the build can actually trust.
Local-first and free, no cloud and no account, against the repo you already have.
What is the stalest line in your AGENTS.md that an agent would follow anyway? Tell me on the forum.
Frequently asked questions
What is docs-as-code?
Treating documentation like source code: it lives in the repository, changes through pull requests, gets reviewed alongside the code it describes, and passes through CI. The point is that docs move on the same track as the code, so they change together instead of drifting apart.
How does the agent era change docs-as-code?
Docs stop being only human-facing output and become machine-facing input. Files like AGENTS.md and CLAUDE.md are read by agents to decide how to build. That flips the priority: stale docs no longer just confuse a new hire, they actively steer an agent to build the wrong thing, so keeping them true becomes a build concern.
Should the docs pipeline be part of the build?
Yes, when agents depend on the docs. If instructions can drift from the code with nothing to catch it, they will, and an agent will trust the drifted version. Generating docs from the code where possible, and gating the build when documented facts and real facts disagree, is how you keep the contract true at machine speed.