# Docs Writing Protocol

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

- Skill: `z-soulx/docs-writing-protocol` (Agent Skill)
- Install (CLI): `npx skillmds@latest add z-soulx/docs-writing-protocol`
- Raw SKILL.md: https://api.skillmd.com/api/skills/z-soulx/docs-writing-protocol/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: z-soulx (https://skillmd.com/u/z-soulx)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/z-soulx/docs-writing-protocol

---


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

> 目标：只有明确指定目标文件时才写入；写入时只记录设计/契约/语义的变化，不把修 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` — 本轮强制不写入（即便命中必须更新，也只在对话说明）