AI大模型在文档生成方面速度惊人，然而生成内容的真实性、可靠性与可验证性始终是核心挑战。本文记录了我们团队一次真实的工程化转型实践：从最初的“AI聊天生成+人工修补”作坊模式，升级为由Rules、Skills、验证Harness与人工审阅协同构建的可验证、可复用的文档生产流水线。
项目早期，为追赶交付周期，产品与研发团队将PRD、原型图等资料直接输入大模型，快速产出了一批初稿。在内部对齐场景中，这一单点尝试效率尚可。
然而，当产品正式上线（GA）面向外部客户，初稿移交至文档团队后，深层问题逐渐暴露。原先单篇投喂的方式过于碎片化，模型容易陷入代码与PRD的实现视角，无法自然构建用户理解路径，也缺乏全局的渐进式披露。更关键的是，操作步骤与API调用未经过真实验证，一旦发布可能给用户带来使用风险。
我们尝试过常规解法，例如编写更长的Prompt，或安排专人逐篇校对。但面对大量配置参数与复杂业务逻辑，单纯依赖提示词工程或人工排查迅速遇到瓶颈。AI仍会不经意地编造配置项、弱化关键限制，甚至将内部实现细节包装成对外能力。
这促使我们重新思考：问题并非AI写不出好文档，而是我们试图用一个松散的黑盒解决需要高确定性的工程问题。既然AI容易在边界上犯错，我们就应优先设计边界与证据机制；既然过往项目积累了诸多教训，就不应每次都从零开始教授。
因此，我们决定暂缓大规模内容生成，先退一步，将团队过往积累的隐性经验显性化，作为约束后续所有生成动作的基石。
第一步：沉淀历史经验，构建文档生成基线
构建工作流的首要步骤，并非急于让AI撰写新文档，而是建立约束框架。
我们并未为新项目凭空设定规则，而是将团队在多个项目中总结的经验转化为代码仓库中的两类核心资产，作为新项目的启动基线：
- Rules（规则）：定义基础边界，涵盖Markdown结构校验、敏感信息拦截、术语库、对外内容白名单等基础红线。
- Skills（领域技能）：沉淀特定场景的写作规范与GEO（生成式引擎优化）策略，以更好地服务读者与AI爬虫。例如，
technical-writing规范概念与操作的差异化表达；saas-english-translation负责翻译时的文风，避免机器翻译痕迹并对齐UI文案；此外，配合geo-optimizationSkill，主动添加页面元数据、明确的否定声明（Negative Constraints），防止AI产生过度推断的幻觉。
当然，这些Rules和Skills也会随项目进展持续演进。自动化流程捕获到新的边界情况或误报后，我们会反向补充到资产库中，使团队经验转化为可复用的数字资产。
第二步：受控内容生成，从单点投喂到结构化组装
有了规则基线，我们摒弃了将一堆材料扔给AI自由发挥的模式，转而采用受控的结构化生成工作流。
- 构建产品能力地图
在生成具体文档前，先让AI阅读PRD、原型图及测试环境页面，输出产品功能点的结构化能力地图，作为后续内容生成的总纲。例如，目标用户是谁、核心任务路径是什么、哪些能力已就绪、哪些内容仍需确认。 - 基于 Diátaxis 框架分类
根据能力地图，参考Diátaxis框架（Tutorials, How-to Guides, Reference, Explanation）将任务拆解为概念、教程、操作指南和参考信息等不同类型。生成概念时关注业务背景，生成操作时挂载真实截图与预期结果，生成参考时对齐后续Harness验证通过的API、参数或用例。 - Skills 实时动态挂载
在每一次生成任务中，我们根据文档类型显式挂载对应的Skills，使生成内容从第一稿起就尽量符合人类易读与机器可解析的双重标准。
第三步：自动化编排，确保文档迭代确定性
内容生成仅是起点，确保文档在持续迭代中保持准确，才是工程化的核心。
为实现这一目标，我们将代码变更纳入文档触发机制：当研发提交PR时，系统分析变更范围，并自动路由至对应的验证Harness（借鉴软件工程中Test Harness测试线束理念）。由AI Agent自动执行验证任务并输出报告。以复杂软件类产品为例，该机制可覆盖以下场景：
- UI 变更的多维捕获
产品界面迭代频繁，仅靠人工比对极易遗漏。为此，我们建立了UI与文档的映射基线，当页面结构、路由或关键文案代码发生变化时，自动触发验证。结合Playwright真实登录产品进行操作，采集DOM树、Accessibility Tree和关键截图，再交由AI与历史文档进行多模态比对，精准定位需要更新的路径与描述。 - 核心能力的回归验证
当识别到API签名、参数或底层逻辑变更时，AI Agent调用测试实例，执行预设的正反例请求。利用真实运行结果，反向验证当前文档中的接口描述、参数边界与错误处理是否依然可信。同样的思路也可用于验证数据库SQL、SDK示例代码或连接配置流程。 - 参数与错误码的高效溯源
当配置类注解或异常抛出逻辑发生变化时，系统从源码或规范文件中提取最新的默认值、取值范围、生效规则及错误码，直接与文档描述进行Diff。这极大减少了人工抄写带来的滞后与偏差。
具体的验证逻辑需根据不同产品特性定制，但核心原则不变：基于代码变更进行分类与路由，使文档准确性校验从纯人工抽检逐步升级为基于运行结果的自动化证据链。
流程固化后，文档工程师的价值何在？
当Rules、Skills、Harness及执行边界逐渐固化，基础生成与校验由系统承担，文档工程师的价值不仅未被削弱，反而更具前瞻性与工程属性。
过去，我们关于自动化校验的构想常受限于代码能力；如今，AI辅助编程抹平了这一门槛，使我们能直接将隐性经验转化为可运行的工具代码。工作重心正从内容交付者向以下三个高价值象限转移：
- 构建可复用的文档质量基础设施
将对文档场景的理解转化为自动化防线，将踩过的坑固化为CI/CD管道中的验证Harness，使内容质量不再完全依赖发布前的人工抽检。 - 面向人与机器的双重知识架构设计（GEO 实践）
AI时代的文档也是RAG系统与AI助手的“语料”。需通过严格的标题层级、一致的术语表、前置的限制说明以及标准的Problem-Cause-Solution结构，降低AI问答的幻觉，实现生成式引擎优化（GEO）。 - 把控对客边界，反推产品体验闭环（DX）
AI擅长堆砌信息，但无法替代业务敏感度。需要判断哪些内部细节应隐藏、哪些复杂API会引发误解。同时，将编写Harness时发现的模糊错误码或不友好流程直接反馈给研发，将文档侧的反馈链路前置，成为提升开发者体验（DX）的核心推动力。
AI并未让我们退至流程末端，而是赋予我们用工程化思维重塑文档工作流的能力，使我们真正成为内容规则设计者与知识架构师。
未竟之事与下一步演进方向
工程化永远在路上。目前虽已构建基础验证闭环，但仍有几个核心方向正在推进：
- 从发现错误到推荐规则：目前排障后仍需人工更新规则，后续需Agent根据失败报告自动反向推导并生成Rules/Skills更新建议，人工仅需Review并合并。
- 从单点验证到链路验证：目前的Harness多聚焦单点API、UI、SQL参考等，未来将尝试在沙箱中模拟业务全链路（如：创建资源→触发任务→状态断言），验证复杂教程的端到端准确性。
- 从本地分析到沙箱归因：对于高风险操作（如删除资源、全局配置）或复杂SDK编译错误，将其抛入隔离的云端沙箱复现。Agent在沙箱内收集日志并整理修复建议，做到安全与效率兼顾。
- 从构建侧验证到消费侧反馈：探索在对客站点引入搜索词、高频错误码等遥测数据。在做好脱敏合规的前提下，将用户的真实阻塞点自动转化为文档优化Issue。
无论系统如何演进，边界必须清晰：模型仅负责差异分析与建议，敏感凭证绝不入库，最终内容是否需要修改的决定权始终掌握在文档工程师手中。
结语与思考
回顾此次实践，我们对“文档即代码”（Docs as Code）有了更具象的体感。
将AI引入文档工程，绝不仅仅是更换更聪明的写作工具，而是让知识生产真正具备工程化的确定性。模型确实压缩了草稿撰写时间，但其深层价值在于倒逼我们重新审视业务：哪些隐性经验可以被结构化？哪些事实断言能够被自动化验证？
当繁琐的文字搬运与格式校验被系统接管，文档工程师终于可将精力倾注于那些真正需要人类智慧的环节：洞察用户心智、设计信息架构、定义验证标准、把控对客边界。
AI正从文本生成器进化为可执行的Agent，但这一跨越离不开CI管道、Guardrails（护栏）、沙箱与Human Review的严密配合。在此过程中，我们将经验转化为规则，将猜测转化为证据，用系统的确定性对冲大模型的随机性。
最终，我们不再只是撰写文档，而是用工程化手段让文档像现代软件一样被构建、测试、审阅与持续进化。
延伸阅读
- 技术文档AI审核实践：从本地轻量校验到Codex Code Review：结合本地小模型LLM轻量校验、Codex Local与Codex Cloud，分享一套适用于Doc-as-Code技术文档的AI审校流程及AGENTS.md规则设计的落地经验。
- 从零构建本地AI内容审校系统：小模型推理到工程化落地：从技术文档审校中的错别字、术语误写与误报问题出发，分享一套本地中文AI文档纠错系统的设计思路，包括规则引擎、小模型、保护机制、Web管理界面和持续反馈。
- Diátaxis：从用户需求区分tutorials、how-to guides、reference和explanation的经典信息架构理论。
- Google Developer Documentation Style Guide：开发者文档的语气、术语、格式与项目优先原则。
- Docusaurus Documentation：Markdown/MDX文档站点的构建、版本化与国际化工程。
- Vale Documentation：将术语、风格与Prose Lint规则彻底工程化的开源方案。
- OpenHands（原名OpenDevin）：了解AI Agent如何在隔离沙箱中执行复杂软件工程任务的开源实践。