等级 L2 · 每天 15 分钟 · 场景:写文档→一、接口文档与注释,写方案→三、技术方案与设计文档
一句话：文档类活是 AI 提效最直接的一块——它擅长把已有信息换个形式表达。但注意分界：整理信息可以交出去，做决策不能。技术方案里最有价值的部分是「为什么选 A 不选 B」，那部分是你的活。
学习地图
| 你的问题 | 看哪一节 |
|---|---|
| 「接口文档懒得写」 | 一、接口文档与注释 |
| 「commit message 老是写 fix bug」 | 二、commit 与 PR 描述 |
| 「技术方案要写三天」 | 三、技术方案与设计文档 |
| 「能让它帮我做技术选型吗」 | 四、别让 AI 替你做决策 |
一、接口文档与注释
从代码生成文档，而不是凭空写
根据这个 Controller 生成接口文档（贴代码）。
格式：接口路径 / 方法 / 入参（含必填与取值范围）/ 出参 / 错误码 / 调用示例。
错误码从 BizErrorCode 枚举里取（贴枚举）。
不确定的地方标 TODO，不要猜。
最后一句很重要。不加这句，它会把没写的字段说明编出来——看着完整，实际是幻觉，比空着更糟糕。
注释：只写代码说不出来的东西
AI 写注释的通病是逐行复述代码：
// ❌ AI 默认风格
// 遍历订单列表
for (Order order : orders) {
// 判断订单状态是否为已支付
if (order.getStatus() == PAID) {这种注释是负资产——它会过期，而且什么信息都没提供。明确要求：
补注释，规则：
- 只解释「为什么这么写」，不复述「这行在做什么」
- 有业务背景/历史原因/踩过的坑才写
- 代码本身能说明白的，一律不写
// ✅ 有信息量的
// 必须先扣库存再创建订单：反过来会在库存不足时留下脏订单（2025-03 事故）判断标准：删掉这条注释，下一个人会不会踩坑？不会就删。
README 与上手文档
这类文档的价值在于「新人照着能跑起来」，AI 写初稿很合适：
根据这个项目生成 README，包含：
项目是干什么的 / 技术栈 / 本地怎么起 / 目录结构说明 / 常用命令。
命令从 pom.xml 和 Makefile 里取真实的，不要编。
写完自己照着走一遍——这是唯一的验收方式。AI 不知道你机器上装了什么，它写的「本地启动」步骤经常漏前置条件。
二、commit 与 PR 描述
commit message
根据这个 diff 生成 commit message，
Conventional Commits 格式，中文，
标题 50 字以内说清改了什么，
正文说明为什么改（我补充背景：这是修复优惠券在 199 元订单上误可用的问题）。
「为什么改」通常要你补一句背景——diff 只能告诉它改了什么，告诉不了为什么。
PR 描述
PR 描述比 commit 更值得让 AI 写，因为它信息量大、结构固定：
根据这个分支的所有提交生成 PR 描述：
【改了什么】要点式，不逐条列 commit
【为什么】（我补：优惠券门槛判断用了 >= 应该是 >）
【影响面】哪些接口/表/下游会受影响
【怎么验证】review 的人该重点看哪几处、怎么自测
「影响面」和「怎么验证」这两块最能省 reviewer 的时间，而人手写时最容易偷懒跳过。
三、技术方案与设计文档
这是本篇的重点，也是最容易用错的地方。
正确用法：让它搭骨架、列维度、当靶子
① 列对比维度
我要在 RocketMQ / Kafka / RabbitMQ 里选一个做订单事件总线。
先别推荐，列出这个场景下应该对比哪些维度，
每个维度说明为什么在「订单事件」这个场景下重要。
它列出的维度（吞吐、顺序性、事务消息、运维成本、团队熟悉度……）就是你的评估框架。框架它给，结论你填。
② 搭文档骨架
生成一份技术方案文档的大纲，主题是订单超时自动取消的实现方案。
读者是同组后端 + 一位架构师。
只要大纲和每节该写什么，别写内容。
③ 当反方辩手
这是被严重低估的用法：
这是我的方案（贴方案）。
你扮演一个挑剔的架构师，找出其中的问题：
哪里考虑不周、哪里有隐藏成本、哪里在高并发下会出问题。
不要客气，也不要为了挑而挑。
评审前先自己被挑一轮，比在评审会上被当场问住好得多。它能找出的通常是：容量估算缺失、失败路径没设计、依赖方没对齐、灰度和回滚方案没写。
④ 把方案讲给不同受众
把这段方案改写成给产品经理看的版本：去掉实现细节，
说清楚做完之后用户会有什么变化、要多久、有什么风险。
同一份内容换受众重写——这是 AI 最擅长的活，纯粹的形式转换。
四、别让 AI 替你做决策
为什么不能
技术选型和架构决策依赖三样它不知道的东西：
| 它不知道的 | 举例 |
|---|---|
| 团队现状 | 组里没人用过 Kafka；运维只维护 RocketMQ |
| 组织约束 | 中间件要走审批；预算今年冻结 |
| 历史包袱 | 上一个项目用 X 踩了坑，团队有心理阴影 |
这三样通常比技术优劣更能决定选型结果。 它给的是「教科书上的最优」，你要的是「你们这儿能落地的最优」。
更危险的一点：它给的推荐总是有理有据
它不会说「我不了解你们团队所以无法判断」，而会给一段论证充分的推荐——论证充分不等于结论适用。你把这段论证写进方案，评审时被问「为什么不用现成的 RocketMQ」，你会答不上来，因为那不是你的推理。
正确的分工
| 环节 | 谁做 |
|---|---|
| 列出候选方案 | AI（比你想得全） |
| 列出对比维度 | AI |
| 补充团队/组织约束 | 你 |
| 给每个维度打分 | 你 |
| 下结论 | 你 |
| 把结论写成文档 | AI |
| 挑战这个结论 | AI |
一句话：AI 负责让你想得更全，不负责替你拍板。
常见追问
-
让 AI 写的文档，怎么保证不过期？ 和代码一样的办法：文档进 git、改代码时一起改、能生成的就别手写（接口文档从注解生成、命令从脚本里取）。AI 只是让写初稿变快，不解决维护问题——维护靠流程，不靠工具。
-
它写的技术方案能直接发出去吗？ 结构和表达可以直接用，事实和结论必须逐条核：容量数字对不对、依赖的组件版本对不对、结论是不是你真正的判断。发出去之后，署名是你，问题也是你的。
-
写英文文档能靠它吗？ 很合适，这是它的强项之一。但技术术语和内部专有名词要给它对照表，否则会翻出各种不一致的译法。可以配合技术写作（英语域）一起看。
-
给不同受众写不同版本，会不会不一致？ 会，这是真实风险。做法：维护一份主文档（最详细的技术版），其他版本都从它派生；主文档改了，重新派生而不是各自修改。
-
能让它总结会议纪要吗？ 能，但注意两点：会议内容可能包含敏感信息，先过数据边界这一关（见 AI工程化与风险）；结论和 action item 要人来确认——它可能把讨论中被否掉的方案当成结论写进去。