夜雨聆风很多企业不是不会写文档。
真正的问题是：文档没有进入软件交付流程。
开发改了接口，API 文档还停在旧版本。 数据库字段变了，数据字典没人同步。 部署方式调整了，运维手册仍然是几个月前那一套。
时间一长，团队真正敢相信的只剩代码。 文档反而变成“仅供参考”。
所以这篇文章想讲的不是“用 AI 多写几篇文档”。
而是另一件更实际的事：
让 Hermes 监听代码变化，判断文档是否受影响，再把文档更新变成一次可追踪、可审查、可回滚的研发任务。
一、文档失效，通常不是写作问题
在真实项目里，代码和文档往往是两套节奏。
代码每天都在变：
修改 API
↓
提交 Git
↓
Pull Request
↓
Merge
但文档没有对应动作。
于是几个月以后，团队看到的是三套版本：
代码：最新版
文档：旧版本
实际部署：又是另一套
这不是某个开发人员不负责。
而是流程设计上缺了一环：
代码变更没有自动触发文档同步。
二、正确做法：先判断，再更新
我不建议让 Hermes 每天扫描整个项目，然后重新生成所有文档。
这样成本高，也容易覆盖人工维护内容。
更合理的链路是：
代码发生变化
↓
Hermes 接收事件
↓
文档影响分析
↓
是否需要更新文档
↓
创建文档任务
↓
Document Agent 更新
↓
自动校验
↓
创建 Docs PR
↓
人工 Review
这条链路里，最关键的不是“写”。
而是：
先判断这次代码变化到底影不影响文档。
例如：
修改内部变量名 → 通常不需要
调整内部算法 → 可能不需要
新增 API → 需要
修改 API 参数 → 需要
新增数据库字段 → 需要
修改部署方式 → 需要
新增配置项 → 需要
只有这样，自动化才不会变成新的噪音。
三、Hermes 在这里不是“写文档工具”
这个场景里，Hermes 更像一个调度器。
它把几件事串起来：
Git / Webhook
↓
Hermes Gateway
↓
Kanban
↓
Document Profile
↓
MCP 工具集
↓
文档仓库
每一层都有边界：
Gateway 负责接收 GitHub、GitLab、Gitee、Jenkins 等事件。
Kanban 负责把一次文档同步变成可追踪任务。
Document Profile 负责让专门的文档 Agent 执行分析、生成和校验。
MCP 工具集 负责读取代码仓库、文件系统、文档仓库、数据库知识和配置文件。
最后，变更不是直接写进主分支。
而是生成一次文档 PR。
四、最关键的一步：文档影响分析
不要让 Agent 一看到 PR 就改 Markdown。
先让它产出一份：
Document Impact Report
它至少要回答三个问题：
这次代码变更属于什么类型？ 哪些文档可能受影响？ 建议怎么处理？
例如某次提交是：
feat: 增加用户登录失败重试机制
代码变化集中在：
auth/login.ts
auth/retry.ts
tests/login.test.ts
Hermes 分析后可能得出：
API 文档 → 无影响
架构文档 → 无影响
部署文档 → 无影响
认证设计文档 → 有影响
故障排查手册 → 有影响
于是它只创建两个文档更新任务。
这比“重新生成整个项目文档”靠谱得多。
五、Document Agent 只能按规则更新
进入更新阶段以后，也不能让 Agent 自由发挥。
它应该按固定流程执行：
读取上下文
定位修改点
生成更新内容
内容校验
生成 PR
这里有一个底线：
AI 只能修改应该修改的部分，不能覆盖人工维护内容。
比如这些内容默认应该被保护：
人工维护章节
重要业务规则
公司制度说明
安全与合规内容
历史记录与决策
这也是企业落地时必须坚持的一条边界。
AI 可以同步信息。
但企业知识库不能被 AI 随意重写。
六、文档同步任务要进入 Kanban
文档同步不应该是一次“黑盒执行”。
它应该有生命周期：
Backlog
Ready
In Progress
Review
Done
Blocked
这样团队至少能看清楚：
哪些文档任务刚被创建； 哪些任务已经完成影响分析； 哪些任务正在更新； 哪些任务在等待人工 Review； 哪些任务因为信息不足被阻塞。
这一步很重要。
因为自动化不是为了让人完全不管。
而是让人只管真正需要判断的地方。
七、自动校验决定这件事能不能长期跑
文档 PR 创建前，至少要做几类检查：
格式校验
链接校验
示例校验
内容一致性校验
规范校验
尤其是示例和链接。
很多文档失效，表面上是“内容过期”。
实际打开一看，是命令跑不通、链接打不开、API 示例和真实接口不一致。
如果这一步不做，自动生成只会加速制造新问题。
八、为什么一定要保留人工 Review
我不建议让 AI 直接改 main 分支。
特别是这些文档：
架构文档
接口规范
生产部署文档
安全合规说明
业务规则说明
更稳妥的方式是：
代码变化
↓
Hermes 分析
↓
Document Agent 修改
↓
自动检查
↓
创建 Documentation PR
↓
人工 Review
↓
Merge
人审的重点也不是逐字改文案。
而是确认三件事：
AI 为什么改； AI 改了什么； 有没有漏掉或误改。
九、企业先从 5 类文档落地
不要一开始让 Hermes 管所有文档。
优先做这五类：
① API 文档
② 数据字典
③ 架构说明
④ 部署手册
⑤ 故障排查手册
原因很简单。
它们和代码、数据库、配置、部署环境关联最强。
会议纪要、产品规划、制度文件这类内容，不一定适合由代码变化直接驱动。
先把高频失效的技术文档接住，收益更直接。
写在最后
很多企业做知识库，最后都会遇到同一个问题：
知识库不是没有内容，而是没有人维护。
Hermes 在这个场景里的价值，不是“替人写更多 Markdown”。
而是把文档更新接入研发流程：
Git
↓
Issue / PR
↓
Kanban
↓
Document Profile
↓
MCP
↓
文档影响分析
↓
自动更新
↓
质量校验
↓
Documentation PR
↓
人工 Review
最终实现的不是“AI 写文档”。
而是：
代码和文档一起演进。
这才是企业真正值得落地的 AI 文档管理。