docs-writing-protocol

Category: Data & AI | Uploader: z-soulx | Downloads: 0 | Version: v1.0（Latest）

文档写入协议（去躁点版）。控制 AI 何时写入文档、写入什么内容。当用户说"沉淀到文件"、"记录下来"、"update: xxx.md" 时使用。

Changelog: Source: GitHub https://github.com/z-soulx/ai-toolkit

Directory Structure

Current level: skills/doc-processing/docs-writing-protocol/

📄 SKILL.md 2.7 KB

SKILL.md

---
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` — 本轮强制不写入（即便命中必须更新，也只在对话说明）

Comments 0

Latest | Hot

Please login before commenting.

No comments yet. Be the first one!

docs-writing-protocol

Directory Structure

SKILL.md

Report

Notice