文档不应是项目收尾时“补作业”的产物，而应随代码同步产出。本节只讲三件事：用什么工具、怎么省时间、哪些地方必须人工把关。
1. 技术文档：让AI当“初稿写手”，人当“校对编辑”
技术文档（部署手册、架构说明、开发规范）的核心读者是内部团队，追求准确、可追溯、好搜索。
- 先定模板，再填内容：不要用 Word。在 Git 仓库里建一个
docs/目录，统一用 Markdown 编写。提前定好三级目录（如01-环境搭建.md、02-核心模块.md、03-排障手册.md），让 AI 按模板输出，避免每次格式不一样。 - 代码即来源：把关键模块的源码 + 现有注释丢给 AI，指令写具体，例如：“根据以下 Python 类，生成一段技术说明，包含职责、依赖服务、线程安全注意事项，200 字以内。” 生成后人工核对业务逻辑，不要直接复制。
- 善用汇总脚本：如果文档分散在多个
.md文件里，可用一个简单脚本（如 Python 的mkdocs或 Node 的docsify）在 CI 流程中自动渲染成静态站点，每次合并代码后自动更新。
关键提醒：AI 生成的技术文档在“通用描述”上看起来很美，但环境变量、密钥配置、内部域名、版本差异必须人工填写，这是最容易出线上事故的地方。
2. 接口文档：代码注解为主，AI 补位为辅
接口文档（API Doc）的核心读者是前端、测试和外部合作方，追求字段精准、示例可运行、与代码版本一致。
- 首选自动生成：新项目优先使用 Swagger/OpenAPI、FastAPI、SpringDoc 等注解驱动工具。开发者在写接口时顺手写注解，部署后文档自动跟随代码版本发布，这是性价比最高的方案。
- 遗留项目补文档：如果是老项目没有注解，别手工一行行写。可先用 Apifox、Postman 或 Charles 抓包，导出 JSON，让 AI 根据请求/响应样本逆向生成 Markdown 格式的接口说明，再贴到 YApi、ShowDoc 或内部 Wiki。人工只需补充分页逻辑、错误码、鉴权方式。
- AI 润色描述：自动生成的 Swagger 文档往往字段齐全但描述空洞（如
user_name: string）。可把 JSON Schema 丢给 AI，指令为：“给以下字段补充 20 字以内的业务含义，并给出 3 条边界值示例。” 再把结果回写到代码注解里，形成正向循环。
关键提醒：接口文档里有三件事 AI 和自动化工具都做不好，必须人工写死：
- 业务错误码：HTTP 200 里包裹的业务异常码及含义；
- 权限与限流：哪些角色能调、QPS 多少、是否幂等；
- 特殊场景：字段互斥、时区处理、空值与空字符串的区别。
3. 一个可落地的最小流程
- 开发阶段：在代码里写 Swagger 注解（或 FastAPI 类型提示）；
- 联调阶段：导出 Swagger JSON，用 AI 生成接口变更摘要，发给前端；
- 发版阶段：CI 自动将 Swagger 渲染成 HTML，并把核心链路图插入
docs/发布说明.md； - 运维阶段：将生产排障日志（脱敏后）喂给 AI，更新
docs/03-排障手册.md。
一句话总结：技术文档靠“模板 + AI 初稿 + 人工填坑”产出，接口文档靠“代码注解自动生成 + AI 润色 + 人工补业务规则”维护。文档能自动化的 automate，不能自动化的不要硬编。