AI 辅助开发中的项目文档维护

AI 辅助开发时，文档既帮助人理解项目，也为下一次修改提供上下文。如果新旧规则混在一起，工具可能沿着过时命令继续工作。与其不断增加说明，不如先明确每份资料负责什么，以及什么时候必须同步。

下面的方法结合本站仓库的实际入口整理，不代表对某种工具效率的测评，也没有用未经采集的数据判断效果。

入口只负责把人带到正确位置

本站从 README 说明项目用途和运行命令，再由 docs/README.md 指向当前有效的主题说明。开发者处理内容集合时读内容说明，修改部署时读部署说明，不需要默认加载所有历史材料。

入口应当短而明确。将完整设计、所有字段和每次排查经过都塞进 README，会让最常用的启动信息变得难找。更适合的做法是保留任务导航，让细节回到主要维护位置。

分清规范、计划和历史

本站把三类资料放在不同目录：

• docs/ 保存当前生效的设计、接口、命令和维护规则。
• plan-docs/ 保存正在执行的方案、步骤、清单与阶段状态。
• draft-docs/ 保存需要保留的草稿和历史参考。

候选方案可以帮助讨论，但不能自动变成正式规则。已完成任务中的长期约束，则应整理回对应主题；日常开发和构建不应依赖某一份临时计划文件。

这种划分也帮助控制 AI 的读取范围。资料不足时，先按主题和路径查找当前说明，不能因为搜索命中了旧文档，就把历史建议当成现行要求。

以实际变化决定同步范围

文档同步不等于每次都改 README。可以先看变化属于哪一类：

1. 只是内部函数整理，对外行为与命令没变，原说明可能仍然准确。
2. 修改了集合字段、公开路径或构建命令，需要更新对应主题。
3. 删除或移动文件，需要检查仍在使用的入口与引用。

例如，把双语品牌模板改为中文笔记站后，旧文档中的产品 YAML、语言切换和 Cloudflare 发布命令已经不适用。此时应替换旧段落，而不是在末尾追加“现在改用另一套方案”，留下互相冲突的操作方式。

先辨明冲突，再修改正文

代码和文档不一致时，不能一律让文档追随代码。先判断：是说明过时、实现有缺陷，还是缺少事实依据。

如果需求明确要求草稿不公开，而构建产物里出现草稿，应该修复公开查询或路由生成。把文档改成“草稿也会发布”，并没有解决问题。服务器地址和备案信息等无法由源码证明的事实，则需要真实资料，不用推测填空。

用验证结束一次修改

同步后检查命令是否存在、链接能否找到文件、字段是否符合 schema。涉及交互时走一次真实流程，涉及构建时执行对应检查；仅修改文字时核对相关页面即可。

交付时也应区分“已经实现”“本地验证通过”和“线上尚未执行”。这些表述让后续开发者知道下一步从哪里开始，而不是面对一句范围不明的“全部完成”。

一份有用的项目文档，不在于记录了多少过程，而在于读者能够根据它采取正确的下一步。