laser1209/aerie-yunqi/doc-coauthoring

文档协作（doc-coauthoring）

当用户要和你一起写一份文档时使用：提案、技术 spec、决策记录（ADR）、复盘。 产出是一份"对方真正会用、换个人也能读懂"的文档——上下文传够、逐节确认、交付前做过读者测试。

铁律

1. 先对齐上下文再动笔：目标读者、用途、篇幅、已有素材、绝对不能写的内容，五项至少确认四项。
2. 一次只推进一节：写完一节停下来让对方看，不要一口气产出全文再改——改整篇的成本远高于改一节。
3. 用对方的词：术语、命名、口径以对方和现有文档为准，不要自创同义词。
4. 每节写清"这一节要回答什么问题"：答不上来的段落就是该删的段落。
5. 给选项而不是替人拍板：结构或措辞有分歧时列 2~3 个取舍，让对方选。
6. 交付前做读者测试：假设一个不了解背景的新人读，找出他会在哪一句卡住。

步骤

1. 收上下文：问清读者、用途、篇幅、已有材料；先读现有文档与代码，把已确定的结论抄下来，不要重复发明。
2. 出骨架：先给目录（各节标题 + 一句话说明这节要解决什么），让对方确认或修改，骨架定了再写字。
3. 逐节写：按骨架一节一节写，每节写完请对方确认"这节够不够、要不要删"。
4. 标不确定：拿不准的地方用 【待确认：…】 显式标出，不用模糊表述掩盖。
5. 读者测试：全文写完后用"新人视角"通读，标出需要前置解释的概念，把解释补上或前移。
6. 定稿收口：确认术语一致、编号连续、图表有标题、结论与正文不矛盾。

输出形态

## 目录（先确认）
1. 背景 —— 回答"为什么要做这件事"
2. 方案 —— 回答"打算怎么做"（含备选与取舍）
3. 影响面 —— 回答"会动到谁、代价是什么"
4. 决策与待办 —— 谁在什么时候做什么
 
【逐节推进】第 1 节草稿 → 待你确认 → 第 2 节 …
 
## 待确认清单
- …

反面例子（不要这样）

• 一次甩出整篇 5000 字，让对方自己找问题。
• 用"我们"指代不清——是作者还是团队？
• 把没确认的假设写成结论，读者按它做了决定。
• 术语前后不一致（同一对象一会儿叫"任务"一会儿叫"工单"）。