非代码写作：RFC、方案、周报与复盘
系列入口：如何使用 Agent。M12 第 5 篇。
一、Agent 能帮上写作，但帮不了你思考
工程师有大量时间消耗在非代码写作：写 RFC 征求意见、写技术方案、写周报对齐进展、写事故复盘、写技术博客。这类文字承载的是思考、说服和对齐，价值很高，却常因"没时间写"而被敷衍。
Agent 是极强的写作协作者：它能帮你头脑风暴、搭结构、扩展草稿、变换语气、补反面观点、润色语言。但要清醒——它能帮你把想法写清楚，却无法替你产生值得写的想法。如果你自己没想清楚，它只会帮你生产一份结构漂亮、内容空洞的八股。因此协作的重心始终是"你的思考在前，它的生成在后"。
二、先有骨架和论点，再让它扩写
最有效的协作顺序是自顶向下：你先用几句话写下这份文档真正想表达的核心观点、要支撑的关键论据、希望读者读完后做什么；然后让 Agent 基于这些要点搭出结构、并对每个论点提出可能的质疑。
骨架和观点由你定，它负责填充和展开——这样文档不会"言之无物"。切忌让它从一个标题直接自由发挥，那样你会得到一份正确但没有灵魂的通用模板。你提供"骨头和立场"，它补"血肉"，是质量的关键。
三、用它当反方和编辑，而不只是写手
Agent 在写作中最被低估的价值，是扮演批评者：让它对你的方案提出最尖锐的反对意见、找出逻辑漏洞、列出读者会问的问题——这对 RFC 和技术方案尤其重要，能在评审前暴露薄弱点。
也可让它当编辑：精简啰嗦处、统一术语、调整结构、把一段混乱的文字理顺。让它生成多个版本的开头或论证，你择优、融合。把它当作一个随时可咨询的评审团和文字打磨师，比只让它"写一版"价值大得多。
四、按文档类型与读者裁剪
不同文档目标不同，要让 Agent 按类型使用对应结构：
- RFC/技术方案：背景与问题、目标与非目标、候选方案与取舍、风险与迁移计划；重在论证"为什么选这个"。
- 周报/进展：本期完成、关键指标、风险与求助、下期计划；面向对齐，简洁具体。
- 复盘：时间线、根因、影响、改进项与负责人；遵循无指责原则（见故障修复）。
- 技术博客：钩子、问题、方案、示例、结论；面向读者认知。
核心是先想清楚读者是谁、他关心什么，让 Agent 据此裁剪详略和语气（读者意识与写测试文档相通）。
五、去 AI 腔，保留真实声音与数据
AI 生成文本常有明显的"八股腔"：堆砌"赋能、抓手、全方位"、滥用排比、空洞的总结、过度的对仗。这类文字读起来顺滑却没有信息量。
应对：要求它用具体事实、数字和例子替代抽象形容词；删掉无实质内容的过渡和总结；保留你自己的表达习惯和真实判断，而不是让全文变成一个模子。技术写作的力量来自准确、具体、有证据，不是辞藻。你写的真实数据、真实踩坑、真实取舍，是它无法虚构、也最有价值的部分。
六、事实核对：生成内容必须经你验证
和代码一样，文档草稿里也可能有它编造的"事实"、错误的数据或不成立的引用。所有关键数字、结论、外部引用都要由你核实；它整理的会议/进展内容要对照真实记录。把它的输出当草稿而非定稿，尤其对会对外发布或用于决策的文档，准确性责任完全在你。
七、一份技术方案是怎么被"质询"出来的
看一个具体协作过程，理解反方角色的价值。
某工程师要提议"把单体里的订单模块拆成独立服务"，他最初只让 Agent 帮他把想法写顺，得到一份论证"拆分能提升扩展性、便于团队并行"的漂亮文档。但他多做了一步：让 Agent 扮演最反对这个方案的架构师，列出全部质疑。Agent 提出：拆分会引入分布式事务、网络延迟和运维复杂度，团队目前单体的瓶颈真的到了需要拆的程度吗？数据一致性怎么保证？迁移期间如何双跑？
这些问题逼他回头补了关键内容：现状的真实性能数据、为什么是现在拆、候选的"先模块化再拆"方案及为何不选、分阶段迁移与回滚计划。评审时，评审者最尖锐的几个问题，文档几乎都已预先回应。这个例子说明，Agent 最大的写作价值常常不是"帮你说"，而是"在你被真实评审挑战之前，先帮你把反对意见想透"——经过对抗打磨的方案，才真正立得住。
八、写作中的"金字塔"表达
技术文档要让人快速抓到重点，一个好用的结构是先结论、后论据：开头用几句话给出核心主张，再分层展开支撑，每一层也是先给小结再给细节。
让 Agent 协助你把零散材料组织成这种自上而下的结构，忙的人只读前几句就能拿到结论，想深究的人再往下看。但要注意顺序——结论必须是你分析后真正得出的，而不是让它先编一个漂亮结论再去找材料凑，否则就本末倒置、容易滑向先有立场后找证据。金字塔是表达框架，不是思考替代品；你先想清楚，它帮你排清楚，文档才既有条理又站得住。
九、写完后做一次"冷读"检验
文档初稿完成后，别急着发，让它（或你自己）以一个毫不知情的读者视角冷读一遍：只读前几段能不能明白要解决什么？关键术语第一次出现时有没有解释？逻辑有没有跳跃？
让 Agent 标出"需要背景才能看懂"的跳跃处并补齐。这个动作能发现"作者以为显而易见、读者却完全跟不上"的鸿沟——因为你太熟悉背景，很难自查。好文档要为"冷读者"补足上下文，这与上下文工程、与面向读者裁剪本质上是同一件事，只是用在写作上。
十、用"一句话主张"约束全文
技术写作容易写着写着发散，一个有效的自我约束，是先提炼出一句话核心主张，并让全文都为它服务。
动笔前写下"这篇文章我只想让读者相信/记住 X"，然后让 Agent 检查每个段落：它是在支撑这句话、还是可有可无？删掉与主张无关的枝叶。这句话既是写作的锚、也是读者的记忆点。好的技术文档不是把知道的都堆上，而是围绕一个清晰主张做取舍。 当你能用一句话讲清文档的核心，且全文都站在这句话后面，传播力和说服力都会强很多。
十一、文档的"半衰期"与维护意识
技术文档会随代码演进而过时，一份失效的文档比没有更误导，写作时就要有维护意识。
在文档里标注关键信息的时间点和适用版本，让读者判断新鲜度；当代码发生对应改动，顺手更新相关文档（可让 Agent 在改动涉及某文档时提示）。对 RFC 尤其要记录"最终决策"——它本就是决策过程的存档。把文档当作有生命周期的资产，而非写完即永恒。 定期清理或标注过期文档，能让知识库保持可信；当人们知道"这里的文档是新的、有人维护"，才会真正依赖它，文档的协作价值才得以延续。
十二、保留"写作中的思考痕迹"
文档不必都是完美定论，适度保留你权衡方案、排除选项的思考过程，反而更可信、也更能帮后来者理解。
在技术方案里简要写出"考虑过哪些方案、为何不选"，比只呈现最终结论更有信息量，也避免后来者反复重提被否方案。让 Agent 协助你把这些权衡组织清楚。透明的取舍过程，比看似毫无疑问的结论更有说服力，它展示的是真实的工程判断，而不是事后包装的唯一正确答案——这种诚实恰恰是技术文档赢得信任的重要来源。
十三、不同读者要"分层呈现"
同一份文档常被多种人阅读——决策者只关心结论、评审者关心方案、执行者关心细节，用分层结构照顾所有人。
开头放给决策者的摘要，中间放给评审者的方案与取舍，附录放给执行者的细节和数据。让 Agent 协助把材料按这三层组织，读者各取所需，而不必在无关细节里翻找自己要的部分。好的技术文档像一座可浅可深的建筑：任何人从自己需要的层进入都能有所获，这既提升了对齐效率，也让文档在组织里真正发挥沟通枢纽的作用。
十四、让文档真正"被读、被用"
文档写得再好，若无人阅读也无法发挥价值，写完后的分发与引导同样重要。
在合适的渠道分享要点、在代码相关处留下链接、在会议中引导大家回到文档，而不是写完就丢进知识库角落。让 Agent 协助提炼适合不同渠道的摘要。文档的价值在被使用的那一刻才实现。 当文档成为团队对齐决策的共同入口、人们遇事知道去查、也愿意更新，写作投入才算真正闭环——好文档不仅要写得好，更要被找到、被阅读、被维护。
十五、常见问题
Q：写不出来、大脑空白怎么办？ 先口述或罗列哪怕粗糙的要点喂给它，让它帮你结构化；"先说清楚"往往能打破空白，但观点仍要是你的。
Q：怎么避免千篇一律的 AI 味？ 强制具体例子和数据、删套话、保留个人语气，并给它你过去的文章作风格参照。
Q：周报让它写会不会显得假？ 用真实进展和数据让它整理，而非让它编造成果；它帮你组织表达，内容必须属实。
Q：长篇文档一次写不完怎么办？ 按章节分段协作、保持大纲为稳定上下文，逐段推进、最后统一润色。
八、检查清单
- 你已先给出核心观点与立场，而非让它自由发挥。
- 已让它做反方质询并据此加固论证。
- 已按 RFC/周报/复盘/博客的目标结构和读者裁剪。
- 已去除套话、填入真实数据与例子、保留个人声音。
- 关键事实与引用均已核对。
总结
用 Agent 做非代码写作，要牢记"它能帮你写清、却替不了你思考"：先由你定下核心观点和骨架、让它搭结构并扮演最尖锐的反方找出漏洞，再分段扩写、按 RFC/方案/周报/复盘各自的目标和读者裁剪详略，随后用力去掉"赋能抓手"式的 AI 八股腔、用真实数据和例子与你自己的声音支撑内容，最后把所有草稿当待核实的初稿、逐一确认事实——这样它是放大你思考和表达的写作搭档，而不是替你批量生产结构漂亮却空洞无物、还可能夹带虚构事实的文字。