docs-writing-protocol

---

name: docs-writing-protocol description: 文档写入协议（去躁点版）。控制 AI 何时写入文档、写入什么内容。当用户说"沉淀到文件"、"记录下来"、"update: xxx.md" 时使用。 user-invocable: true metadata: short-description: 按需写入文档，纠错不记账，只记契约/流程/规则/语义变更 version: v1.0

文档写入协议（去躁点版）

目标：只有明确指定目标文件时才写入；写入时只记录设计/契约/语义的变化，不把修 bug、重试、风格调整等噪声落进文档。

---

核心原则（两句口诀）

• 写入门槛：没点名文件，就不写入（只在对话里回答）。
• 去躁点：纠错不记账；改契约/改流程/改规则/改语义，就记账。

---

1. 写入门槛

只有满足任一条件，才允许对 md 文件做持久化更新：

1. 明确指定目标文件路径，例：update: docs/xxx.md

2. 明确要求"生成/落地到某个文件路径"的文档产物

3. 语义上表达"需要沉淀/记录/落地到文件"，例：

   • "这个需求沉淀到文件"
   • "把这个记录下来"
   • "落地到文档"
   • "需要持久化"
   • "写进 xxx.md"

   → 若未指定文件名，先询问目标文件路径，确认后再写入。

否则：只在对话中输出，不创建、不修改任何文件。

---

2. 目标文件绑定

当用户第一次点名 X.md，设置 DocTarget = X.md，后续交互默认继续更新 DocTarget（仍遵守去躁点规则）。

• 切换目标：switch: Y.md
• 停止写入：stop writing

---

3. 去躁点判定

不写入

满足任一条：不写入 DocTarget

• 修复编译/语法/单测
• 修正 AI 理解偏差，但不改变既定设计
• 重试/提示词调整/代码风格/重构不改外部行为

口诀：纠错不记账

必须写入

满足任一条：写入 DocTarget

• 对外契约变了（接口字段、枚举、返回码、回调语义）
• 流程变了（状态机、时序、重试策略）
• 规则变了（优先级、分支条件、开关含义）
• 数据含义变了（字段意义、来源、映射、默认值）

口诀：改契约/改流程/改规则/改语义，就记账

---

4. 写入格式（强制最小化）

每次写入只允许：

• What changed：变化点（1~3 条）
• Why：一句原因
• Impact：对外影响（可选）

实现过程、排障、试错、重构细节一律不写入。

---

5. 交互指令

• update: path/to/doc.md — 指定写入目标
• switch: path/to/another.md — 切换目标
• stop writing — 停止写入
• no-record — 本轮强制不写入（即便命中必须更新，也只在对话说明）