用 AI 写文档与提交信息：README、注释与 commit message
文档与提交信息是 AI 产出里最容易被高估的一类：文字通顺、格式整齐，挑不出语法毛病，但可能整段都是编的。把它当成「有事实来源的转写」而不是「自由创作」，产物才可信。
先给事实来源，再要文字
| 产出 | 必须提供的事实来源 | 典型幻觉 |
|---|---|---|
| README 快速开始 | 真实构建脚本、Makefile、流水线配置 | 编造一个并不存在的 make dev |
| 配置项说明 | 配置结构体、环境变量解析代码、示例文件 | 凭字段名猜语义与默认值 |
| 代码注释 | 该函数、它的调用方、相关工单 | 把 if 复述成业务规则 |
| 提交信息（commit message） | git diff 原文与需求/故障编号 | 「顺便重构了缓存层」这类没做的事 |
一句话原则：AI 只能转写你给它的东西。没打开过文件，就不要问「这个配置项怎么配」。
README 结构模板
# 项目名 —— 一句话定位（解决什么问题、给谁用）
## 快速开始
前置条件：语言版本、依赖服务、可选组件
三道命令内跑起来：clone → 配置 .env → 启动
跑通后应看到什么输出（用于自检）
## 配置项
| 变量 | 默认值 | 是否必填 | 说明 |
## 常用命令
构建 / 测试 / 数据迁移 / 代码生成 / 本地调试
## 目录结构
只列 5~8 个关键目录，每个标出「改这里会影响什么」
## 架构与数据流
一张简图 + 上下游依赖清单
## 部署与回滚
镜像构建、环境差异、回滚命令
## 排错
最常见的 5 个报错 → 原因 → 处置
## 贡献与许可：分支规范、提交规范、许可协议
写完逐段核对事实来源，别只看排版：
| 段落 | 核对方式 |
|---|---|
| 快速开始 | 在干净目录里照抄执行一遍，报错就改文档 |
| 配置项 | 与配置读取代码逐字段对照，默认值以代码为准 |
| 目录结构 | 与真实目录树对比，删掉已不存在的路径 |
| 排错 | 每一条都要有真实 issue 或日志关键字支撑 |
注释：写「为什么与约束」，不写「是什么」
// 差：复述代码，读代码本身就知道
// 遍历 users 并累加 age
for _, u := range users { total += u.Age }
// 好：写约束、原因与失效条件
// 只统计已激活用户：归档数据里 age 为 0，计入会拉低指标口径（见 SPEC-118）。
// 若归档策略调整，这里的分组口径需同步修改。
for _, u := range activeUsers { total += u.Age }
值得写注释的四种情况：
| 类型 | 写什么 | 例子 |
|---|---|---|
| 不变量与约束 | 调用方必须保证的前提 | 必须在事务内调用，否则会出现重复扣款 |
| 反直觉选择 | 为什么不用更直白的写法 | 这里不用索引是因为写入量远大于读 |
| 外部系统怪癖 | 对端接口的隐藏行为 | 对端在超时后仍可能成功，故重试需幂等键 |
| 临时兜底 | 为什么这么做 + 失效条件 | 灰度期强制走旧逻辑，清理条件见 TICKET-902 |
不该写进注释的：变更历史（交给版本控制）、代码字面含义、没有负责人和条件的过期 TODO。
commit message：Conventional Commits
<type>(<scope>): <一句话说清做了什么>
为什么：背景与动机，附需求/故障编号
怎么做：关键取舍，尤其是被否掉的方案
影响面：接口、配置、数据、兼容性
Refs: #2317
BREAKING CHANGE: /v1/orders 的 status 由数字改为字符串，调用方需更新解析逻辑
| type | 用途 | 对语义化版本（SemVer）的影响 |
|---|---|---|
| feat | 新功能 | 次版本号（minor） |
| fix | 缺陷修复 | 修订号（patch） |
| docs | 文档 | 无 |
| refactor | 重构，行为不变 | 无 |
| perf | 性能优化 | 无 |
| test | 测试补充或修正 | 无 |
| build / ci / chore | 构建、流水线、杂项维护 | 无 |
| revert | 回滚某次提交 | 视被回滚内容而定 |
从 diff 生成变更说明
基于下面的 git diff，生成一条 Conventional Commits 格式的提交信息。
约束：
1. 只描述 diff 中真实存在的改动，diff 里没有的一律不写；
2. 不要出现「顺便」「同时优化」「也修复了」这类无法在 diff 中对应的表述；
3. 不确定的推断单独放在「待确认」小节，不要混进正文；
4. 指出破坏性变更（公开接口、配置项、数据格式），并给一句迁移提示；
5. 正文不超过 5 行，动词开头，不要罗列文件名清单。
diff：
<paste git diff --stat 与关键文件 diff>
交付前自检
| 检查项 | 判断方法 |
|---|---|
| 每条说明都能在 diff 中找到 | 逐条搜索对应文件与符号 |
| 没有编造的改动 | 搜「顺便」「同时」「also」等连接词再核对 |
| 快速开始真能跑 | 干净目录照抄执行一遍 |
| 破坏性变更已标注 | 搜公开接口签名、配置项、数据库字段变更 |
| 无敏感信息 | 搜主机名、内网地址、令牌、账号，链接逐个点开验证 |
小结：文档类产出的质量取决于事实来源，而不是文采。给 AI 真实的脚本、代码与 diff，明确要求它不编造未做的改动，再逐条回查，README、注释与提交信息才能从「看起来不错」变成「经得起核对」。