One small AI workflow that solved our stale API documentation problem

这篇新闻最吸引人的地方是：一个简单的AI指令文件，就能让AI自动维护API文档，从此告别“先改接口、再补文档”的尴尬循环。其实原理很好懂：就像你给新来的实习生定了一条规矩——“每次改完代码，顺手更新说明书”，然后这个实习生（AI）会自动执行，不需要你每次重复提醒。团队在代码仓库里放了一个叫CLAUDE.md的特殊文件，里面就写了这一条规则。每当有人修改了接口，AI就会立刻把对应的说明文档同步更新，开发者审核后一起提交，省得后面再花时间补。更妙的是，这些文档被设计成“AI也能看懂的格式”。这意味着它不只给Claude用，以后换成其他AI，同样能直接理解所有接口、例子和规范。文档变成了人和AI都能读懂的共享资料。这个改变对普通人的影响可能很深远。想想你平时用的APP或网站，背后有大量API接口。如果文档过时，开发者容易出错，导致你遇到崩溃、加载慢或者功能不对。现在有了这套自动更新机制，开发效率更高、错误更少，你体验到的服务会更稳定。同时，这种思路也打开了新大门——未来更多AI工具可以直接看懂工程文档，帮你答疑解惑或者自动完成一些任务，就像有了一个随时了解项目全局的智能助手。

One of the most annoying parts of backend development isn't building APIs. It's keeping the documentation up to date. Everyone knows it should happen. Everyone plans to do it. But when you're trying to ship a feature or fix a production issue, documentation is usually the thing that gets pushed to "later." We had the same problem. Our backend team keeps all of our API documentation in a Voiden repository. The interesting part isn't just where the documentation lives—it's how it's maintained. Inside the repository, we have a <code>CLAUDE.md</code> that tells Claude: <blockquote> Whenever an API is added or modified, update the relevant documentation before considering the task complete. </blockquote> So when someone changes an endpoint, Claude automatically updates the docs as part of the same workflow. The developer reviews the changes, commits everything together, and moves on. No separate documentation task. No forgotten updates. No stale examples sitting around for weeks. <h2> The unexpected benefit </h2> The repository is made up of <code>.void</code> files, which are designed to be AI-readable rather than just human-readable. That means the documentation isn't tied to Claude. Today, Claude updates it because that's what our backend team uses. Tomorrow, I can point another AI at the same repository, and it immediately understands our APIs, examples, conventions, and project context without us having to rewrite everything into a new prompt. The documentation becomes shared context—not just for developers, but for AI agents too. That's something I didn't appreciate at first. We're no longer writing docs just for humans. We're writing documentation that both humans and AI can work with. <h2> It changed how I think about AI instructions </h2> Most people treat files like <code>CLAUDE.md</code> as project setup. We've started treating them as part of our engineering process. Instead of saying: <blockquote> "Don't forget to update the docs." </blockquote> We encode that rule once. Then every future task follows it automatically. It's a tiny workflow change, but it's removed one of those recurring problems every engineering team eventually runs into. I'm curious what other repetitive engineering habits people have pushed into their AI instruction files. check out more at <a href="https://voiden.md/" rel="noopener noreferrer">Voiden</a>.