Claude Code Artifacts Will Replace Half Your Documentation. The Other Half Is the Whole Problem.
Mahdi Salmanzade
Co-Founder & CTO of CLRT
Engineering documentation has always been a compromise between accuracy and reality, and reality wins. The diagrams are drawn with care, the API docs are written before launch, the security decisions are recorded, and then the product ships and a week of refactors turns all of it into historical fiction. Claude Code Artifacts promise to end that, by making documentation a byproduct of the work instead of a task that waits for someone to remember it. The promise is real, and it is also where the market stops thinking. Everyone is celebrating that documentation can finally keep up with the code. Almost no one is asking the harder question, which is whether a document that maintains itself is one you can afford to trust more, or less.
Start with why documentation rots, because the reason is not laziness. Documentation fails because software changes faster than a human can describe it. An engineer ships a feature, the pull request merges, and the update to the architecture diagram is a separate act of will that competes with the next feature and usually loses. Six months later the diagram shows services that no longer exist, and the team has quietly agreed that the code is the only source of truth and the docs are a museum. What Artifacts change is the sequence. When the document is produced during the work rather than after it, the diagram of the authorization flow evolves as the flow does, and the reasoning behind a decision can stay attached to the implementation instead of dissolving into a thread nobody can find. That is a genuine shift, and it is worth being precise about what it is. Documentation stops being a chore and becomes an engineering output. The mistake is assuming that solves the problem, when it has only moved it.
Here is what the celebration misses. A stale document is a known liability, and known liabilities are cheap. Everyone on the team understands that the wiki is six months old, so they distrust it by default and check the code before they act. The distrust is the safety mechanism. An automatically maintained document removes the staleness and, with it, the distrust. It wears the authority of being current, so people stop checking, which means the failure mode is no longer an obviously old diagram that everyone discounts. It is a confidently wrong one that everyone believes. When generation is easy, the volume of documentation goes up and the scrutiny per document goes down, and the two moving in opposite directions is how a team ends up making a real decision on a fluent, plausible, automatically produced account of a system that quietly stopped being accurate three commits ago. The old problem was documentation that could not keep up. The new one is documentation you cannot tell is wrong.
This gets sharper the moment the document is load-bearing, which is exactly where the excitement points: security and compliance. A security review begins with questions like how authentication works, where secrets live, and what crosses a trust boundary, and the appeal of Artifacts is that those answers can be maintained continuously instead of reconstructed from source under deadline. But a security reviewer does not need prose that describes the authentication flow. They need an account they can trust as evidence, and an artifact generated by reading the code is not automatically that. Evidence has properties that generation does not confer: provenance, so a claim can be traced to what it came from and what it replaced; a named human who certified it rather than a model that asserted it; verification against the running system rather than against the code's intentions; and a policy for when a claim expires. A SOC 2 or ISO audit does not ask whether you have a document. It asks whether the document is true, who says so, and how you know it still is. An artifact that looks like a security design document but carries none of that is not audit evidence. It is a liability with good formatting, and the confidence it projects is precisely the danger.
So the scarce skill was never generating the documentation, and the feature that makes generation trivial is, if anything, the proof of that. The scarce skill is judgment: deciding which documentation should be continuous and which should be deliberately, expensively human, who in the organization holds the authority to certify a claim as true, how a document earns belief and how it loses it, and where the line sits between a description an engineer reads and an assertion a business acts on. None of that is a feature you install. It is the same discipline that separates a memory a company can trust from a folder it points an agent at: provenance, a maker that is not also the checker, and decay. Continuous documentation is coming, in the way continuous integration and continuous deployment came, and it will be one of the most valuable assets an engineering organization owns. It will also be worthless, or worse than worthless, for any team that mistakes the generation for the hard part and skips the governance that makes what the system remembers worth believing.
A stale document is a known liability. An automatically current one that is quietly wrong is a liability nobody is checking for.
A deeper dive
The trap that separates a working system from a convincing one is the same one that appears everywhere agents write instead of only read: the thing that produces the document cannot be the only thing that certifies it. An artifact generated by the same model that wrote the code inherits that code's assumptions, including the wrong ones, and it will describe what the implementation intends rather than what it does, in a confident and well-structured voice. A trustworthy documentation system needs a separation between the component that proposes a description and the component, or the person, that verifies it against the running behavior, the same maker-and-checker discipline that keeps a self-grading loop from believing itself. It needs provenance on every non-trivial claim, so a reviewer can challenge and trace it rather than merely trust it. And it needs a notion of decay, because a true statement about the system last quarter is a false one now, and a document that cannot tell a durable fact from a perishable one will serve last quarter's architecture with this quarter's authority. Each of those is unglamorous, none of them appears in the demo, and all of them are the actual product.
This is the angle we take into agentic engineering that most of the market does not. The race is to give agents more reach, to let them write more, generate more, maintain more, on the assumption that capability is the constraint. It is not. The constraint is trust, and trust in a document is earned exactly the way it is earned in organizational memory, through provenance, verification, scoped authority over what may be asserted, and a policy for what expires. We treat living documentation as an engineered and governed system rather than a feature you switch on, because the version you switch on is the version that fails quietly, right up until the day an engineer onboards from it, a security reviewer signs off on it, or an auditor accepts it, and builds on a confident falsehood. The point of documentation that keeps up with the code was never to make the system look documented. It was to let people decide, defend, and extend the system correctly, and that only happens when what the document says can actually be trusted.
Work with CLRT
Continuous documentation is worth building, and the teams that build it well will pull ahead. But the value was never the generation, which you can now switch on in an afternoon. It is the judgment about what deserves to be certified as true, and the engineering that makes a document trustworthy enough to onboard from, review against, and hand to an auditor. That is the work CLRT does, the same discipline of provenance, verification, and governance we bring to agentic memory and autonomous loops. Bring us the documentation you want to trust without checking it, and we will build the system that earns it.
Mahdi Salmanzade
Mahdi Salmanzade is the Co-Founder and CTO of CLRT, where he builds agentic systems, developer tools, local-first AI, and security-first infrastructure. Reach him at mahdi@clrtstudio.com or on LinkedIn.
