Документация к программному коду теперь становится строгой дисциплиной благодаря агентам ИИ

Writing software docs can now be a rigorous discipline. Here is a mundane question that came up in an agentic coding session: How do I convert a select widget to a radio group? I was working on Bram, a desktop app that harnesses coding agents to a GitHub-backed workflow. Bram’s UI is made with XMLUI, a framework that wraps a simple declarative syntax around React and CSS. Agents using the XMLUI Model Context Protocol (MCP) server are instructed to prefer How To examples that provide verified working patterns. In this case Claude didn’t find one, fell back to the documentation for the RadioGroup component, and after a bit of fumbling figured it out. All good, right? Nope. Claude should have found a How To and solved the problem immediately. The absence of that document was a bug, and this new How To document is the fix. This particular bug didn’t bite too hard, but the How To catalog is full of complex and hard-won patterns that agents can struggle to rediscover. To ensure that XMLUI is reliably learnable by agents, we continually expand that catalog. How documentation becomes testable We’ve always said documentation is integral to software products. Now that we write for both people and agents, the need to make good on that promise is more obvious. What’s less obvious is that we can now bring systematic rigor to documentation. We needn’t only write what we imagine people want to read; we can also write what agents provably need to read. As a co-maintainer of XMLUI I am acutely sensitive to agents fumbling as they build XMLUI apps. When something that should be a no-brainer isn’t, because the MCP search didn’t find the answer it should have, I file an issue and then direct an agent to write the missing document. That new doc is a testable fix. For example, I asked Claude to find its failed searches for the select-to-radio conversion in the MCP log. The response: Two how-to searches, both at 21:12, both misses: “radio group mutually exclusive choice change value form input” — top hits: use-a-custom-formitem, prefill-a-form-from-an-api-response, use-regex-validation-in-formitem. Form-adjacent noise, zero radio content. “choose one of two options horizontal selector” — the rephrase moments later, attacking from the UX side instead of the component side. Also nothing. The failing searches had returned only weak matches with a top relevance score around 0.7. After adding the new doc I asked it to repeat the search and compare. The new document surfaced at #1 with a 4.2 score, six times higher than anything else. (Because the MCP server can pin the version of the docs it consults, direct A/B comparison is possible.) I also tried a handful of synthetic queries, like “radio buttons for a small set of options”. These confirmed the result. Scaling the discipline When I’m in the thick of the action and see an agent miss finding a document that should exist, I can respond with focused precision. But that’s just me, working in an app that only exercises a subset of XMLUI’s capabilities. To automate the discovery of missing documents across a portfolio of apps, three sources of information come into play. MCP logs You can’t improve what you can’t measure, so the MCP server logs the queries that agents make plus the results they see. That has driven several rounds of iterative improvement. Application code A portfolio of real apps is an inventory of patterns that someone needed to discover and use. So reverse-engineer the process: what search would lead to a working recipe? Here’s a powerful prompt: Fan out subagents across these five apps. Return the top patterns that a developer would search a How To catalog to find. Then run the MCP searches that should find those patterns. The MCP logs directly measure documentation gaps. Session logs A missing doc is only a problem if somebody needed it and didn’t find it. Session logs correlated by timestamp with MCP logs can surface moments where a developer/agent team flailed and hit dead ends doing things that should have been easy. Doing that correlation reliably is easier said than done. Although it helps to make full-text search available to agents, as Bram does, I haven’t yet gotten agents to reliably surface episodes of struggle. The signals they find in the logs can be useful, though, and may improve. Doc writing reimagined Like other humanities majors, I found my way into tech as a writer of software documentation, then moved on to other roles as soon as I could. But after decades as a developer and tech journalist/editor I’ve returned to the role, first as a contributor to Turbot’s docs, then XMLUI’s. My identity as a writer is not bound to these docs. They are not literary works. They are what we always said the docs should be: integral components of software products. As with all software components now, we direct agents to build them. In this case the work requires both editorial and engineering chops. When you bring both disciplines to bear, doc writing becomes more interesting, fun, and impactful than it ever has been.