文档生成
从代码 + 意图生成面向用户文档；通过重新生成检查保持同步。
文档与重构进阶
为什么
GitHub 2024 调查发现 81% 的开发者预期 AI 工具未来一年在代码文档中更深度集成，为所有工作流中最高。文档写完即与代码漂移。
从代码 + 小意图提示生成并在漂移时 CI 失败，保持文档准确无需人工劳作。
何时使用
用于镜像代码的参考文档（API、CLI、配置）。概念/散文文档跳过。
如何做
1. 选镜像代码的文档（API 参考、CLI 用法）。
2. 提示："从这些文件生成文档；每导出一节；含类型 + 示例"。
3. 提交；加重新生成并在 diff 失败的 CI 检查。
4. 在 PR 中审查生成 diff。
5. 仅手改简介/示例，非参考正文。
示例
提示："@folder src/api 生成 API 参考；每路由一节；
方法、路径、body schema、响应 schema、示例请求/响应。"
输出：docs/api.md 含 12 节。加路由未更新文档则 CI 重新生成检查失败。
常见问题
- ⚠重构后 Error: Cannot find module 'xxx' → 重跑 `npm install` 和 `npx tsc --noEmit`；重构常丢或重命名 import。
- ⚠错误：重构后 "Cannot read properties of undefined" → 跑测试套件（`npm test`）捕获行为变更；重构须保持行为。
- ⚠错误：文档漂移：示例无法运行 → 在 CI 执行示例（`npm run docs:check`）；被测示例不会漂移。
最佳实践
- ✓提交文档与重新生成不同则 CI 失败。
- ✓手写内容（简介、指南）与生成参考分开。
- ✓用具体指标衡量结果（节省时间、缺陷率、测试覆盖率），使实践可被论证和改进。
常见问题解答
什么是文档生成？
从代码 + 意图生成面向用户文档；通过重新生成检查保持同步。 它可帮助开发者快速理解 文档生成 的核心价值与适用场景。
如何开始使用文档生成？
开始使用 文档生成，建议先掌握以下要点：选镜像代码的文档（API 参考、CLI 用法）。
文档生成 的常见误区有哪些？
使用 文档生成 时常遇到的问题包括：重构后 Error: Cannot find module 'xxx' → 重跑 `npm install` 和 `npx tsc --noEmit`；重构常丢或重命名 import。；错误：重构后 "Cannot read properties of undefined" → 跑测试套件（`npm test`）捕获行为变更；重构须保持行为。；错误：文档漂移：示例无法运行 → 在 CI 执行示例（`npm run docs:check`）；被测示例不会漂移。。
文档生成 的最佳实践是什么？
文档生成 的最佳实践包括：提交文档与重新生成不同则 CI 失败。；手写内容（简介、指南）与生成参考分开。；用具体指标衡量结果（节省时间、缺陷率、测试覆盖率），使实践可被论证和改进。。
如何深入学习文档生成？
从官方文档入手，再在 GitHub 上搜索真实示例；先在小实验仓库验证模式，再应用到生产代码。