# 反向同步规程（Practice-as-Truth Reverse Sync）

**定位**：以"实际产出"为真相源，反向校准项目中的描述性文档。  
**适用于**：文档已存在但可能与代码漂移的场景。任何项目类型，任何语言。

---

## 为什么需要反向同步

文档漂移不是行为问题，是**热力学问题**：

- **反馈回路缺失**：改代码时编译/测试会报错, 改文档时没有任何东西失败。没有反馈回路的一侧必然腐烂。
- **决策延迟成本不对称**：发现更好方案的那一刻，认知负荷在新方案上，改文档的成本远高于"先这样"。"有空再说"永远不会到来。
- **所有权颗粒度缺失**：代码每个函数都有隐性 owner，文档段落没有。无 owner 的资产必然腐烂。

**铁律**：任何代码变更完成后，未经评估文档影响不得宣告"完成"。

---

## 核心概念

| 概念 | 定义 |
|------|------|
| **PRACTICE（实践）** | 实际产生、可被外部观察验证的成果：源代码、配置、设计稿、已写好的需求条款、运行结果、交付物 |
| **DESCRIPTION（描述）** | 用来说明、规划、记录、决策的文本：PRD、计划、架构说明、决策记录、规范、README |
| **铁律** | 当 PRACTICE 与 DESCRIPTION 不一致时，以 PRACTICE 为真相源。DESCRIPTION 服务于 PRACTICE。 |

---

## 标注规范（关键机制）

所有 AI 写入文档的内容，按可信度三级标注：

```
〔FACT｜文件路径:行号〕   从 PRACTICE 直接验证的事实，附定位
〔INFER〕                 从 PRACTICE 合理推断但未经人类确认
〔OBSERVE｜类型｜严重度〕 扫描中发现的可疑问题/缺口/风险，待人类裁决
```

示例：
- `〔FACT｜src/sync.rs:42〕采用乐观锁 + 版本号`
- `〔INFER〕该模块似乎为多用户场景预留`
- `〔OBSERVE｜矛盾｜中〕§3.2 与 §5.1 规则冲突`

人类评估后可手动调整或移除标记。本流程不主动移除既有标记。

---

## 五步执行规程

### Step 0：勘测——构建产物清单

1. 识别哪些文件是 PRACTICE，哪些是 DESCRIPTION
2. 对 DESCRIPTION 贴角色标签：
   `{需求 | 计划 | 任务 | 架构 | 决策 | 规范 | 门面 | 索引 | 经验 | 其他}`
3. 询问或推断：哪些目录/文件本次应排除（研究资料、历史归档等）
4. **输出**：产物清单表（文件路径 | 类型 | 角色标签 | 是否纳入本次扫描）

---

### Step 1：实质解析——全量审视 PRACTICE

同时产出两类记录：

**FACTS（断言事实，用于回写）**：
- 实际做了什么、对外呈现什么契约
- 依赖什么、产出什么、边界条件、隐性约定
- 每条附定位（文件路径 + 行号 / 章节锚点 / 符号名）

**OBSERVATIONS（旁路观察，按类别分流）**：

用**四个洞察视角**扫描代码，不同视角关注不同粒度的问题：

**〔宏观-架构〕** 洞察逻辑结构与依赖边界
- 识别循环依赖、层级穿透（如 controller 直接调用 model）
- 不合理的模块耦合（高扇入/高扇出、不该知道对方的两个模块互相知道）
- 标签映射：`[债务]` / `[缺陷]`

**〔中观-路径〕** 洞察功能关键路径
- 追踪核心业务主链路（从入口到落盘的完整调用栈）
- 识别被非核心逻辑阻塞或拖慢的脆弱节点（同步等待、串行加锁、N+1 查询）
- 标签映射：`[性能]` / `[风险]`

**〔微观-语义〕** 洞察模糊点与坏味道
- 魔法数字、语义模糊的命名（`flag2`、`tmp`、`process()`）
- 冗余的条件分支（永远为真/假的判断）
- 失效的注释（与代码矛盾，或描述的是"曾经的行为"）
- 标签映射：`[异味]` / `[债务]`

**〔纵深-隐患〕** 洞察副作用与边界防线
- 隐蔽的副作用：全局状态污染、入参被意外篡改、不可变数据被破坏
- 异常处理盲区：吞掉异常、未兜底的空值/越界、异步竞态条件
- 资源泄漏风险：未关闭的连接/句柄、未卸载的监听器、无限增长的缓存
- 标签映射：`[缺陷]` / `[风险]`

OBSERVATIONS 标签体系：

| 标签 | 含义 | 对应洞察视角 |
|------|------|------------|
| `[缺陷]` | 逻辑错误、内部矛盾、违反自身约束 | 宏观、纵深 |
| `[债务]` | TODO/FIXME、临时方案、过时引用 | 宏观、微观 |
| `[缺口]` | 声明了但未落实；落实了一半 | — |
| `[异味]` | 结构/风格上值得改进但不阻塞 | 微观 |
| `[风险]` | 运维、安全、合规、可持续性隐患 | 中观、纵深 |
| `[性能]` | 效率可疑点 | 中观 |

每条 OBSERVATION 包含：标签、严重度（高/中/低）、定位、现象、建议。无把握时写"待人工判断"。

---

### Step 2：差异对照——FACTS × DESCRIPTION，三态分类

| 状态 | 含义 | 处理方式 |
|------|------|---------|
| **一致** | 描述与实际相符 | 跳过 |
| **漂移（DRIFT）** | 描述与实际不符 | 以 PRACTICE 为准，更新描述 |
| **缺失（MISSING）** | 已落实但无描述 | 找归宿，补写 |
| **僵尸（ZOMBIE）** | 描述了但未落实 | 标记为移除候选，请用户确认 |

**归宿路由原则**（不预设具体文件名，沿用项目既有归类）：

| 内容类型 | 归宿 |
|---------|------|
| 需求/规则 | 需求类文档 |
| 进度/任务 | 计划任务类文档 |
| 结构/依赖 | 架构类文档（若无 → 进入待裁决） |
| 决策/经验 | 决策类文档（若无 → 进入待裁决） |
| 入口/定位 | README 或等价门面文档 |
| 通用经验 | 项目内最契合的经验类文档（若无 → 进入待裁决） |

---

### Step 3：回写——按归宿合并修订/补充/移除

- 保留每份文档原有的写作风格与结构，不重排，不改版式
- 所有 AI 新增内容按标注规范打 `〔FACT〕` 或 `〔INFER〕` 标记
- 对明显的历史快照（旧版本、已归档），仅在顶部追加"已被 X 取代"声明，正文不动
- 移除 ZOMBIE 内容前必须告知用户并请求确认

---

### Step 4：观察沉淀——OBSERVATIONS 回写为可追踪资产

1. 在项目根或文档根创建 / 更新 `OBSERVATIONS.md`
2. 按严重度分章，章内按类别分组
3. 每条带 `〔OBSERVE〕` 标记、定位、扫描日期
4. 维护"处理状态"列：`待裁决 / 已确认 / 已修复 / 已忽略`
5. **下次扫描必须读取本文件**，跳过"已忽略"项，避免噪音重复

关于决策记录：
- 本流程不主动生成决策条目（决策需要历史背景，AI 推断不准）
- 但若发现"明显是有意为之的反直觉设计"，在 `OBSERVATIONS.md` 末尾列出"疑似决策点"清单，由人类判断是否补写到决策类文档

---

### Step 5：去水校验——全量复审

- 删除低信息密度段落、模糊修饰词、与实际不符的过时描述
- 每段保留内容须对应至少一条 FACTS 或一条决策依据
- 检查项目入口文档（README/INDEX 等）是否反映结构性变更

---

## 输出格式

每次执行反向同步，必须输出以下四项：

| 输出项 | 内容 |
|--------|------|
| **A. 产物清单表** | Step 0 结果（文件 / 类型 / 是否扫描 / 角色标签） |
| **B. 变更摘要** | 按文档分组，列出 [新增/修订/删除]，每条附定位与标注级别 |
| **C. OBSERVATIONS 摘要** | 按类别统计数量，按严重度列出 Top 10 |
| **D. 待裁决项** | 归宿冲突、语义存疑、ZOMBIE 候选、需用户拍板的条目 |

---

## 红线（绝对禁止）

1. **只读 PRACTICE，绝对禁止修改任何实践产物**（代码、配置、设计稿等）
2. 沿用项目既有的描述产物结构与命名，禁止臆造新文件（确无归宿且必要时允许新增，需显式声明理由）
3. 不臆造未落实的内容；不保留已被实践淘汰的描述
4. 所有 AI 推断未经人类确认的内容，必须按标注规范标记
5. **禁止"待定"**：任何不确定项必须三选一：①文档一致 ②立即更新 ③升级裁决——"待定"是文档腐烂的庇护所  
   > **升级裁决**：指将该不确定项标记为待人类决策的问题，明确列出分歧点（"代码实现是 X，文档描述是 Y，需要确认哪个是意图"），提交给代码 owner 或 tech lead 做权威裁定，而非 AI 自行推断后静默填入。与 `〔INFER〕` 的区别：`〔INFER〕` 是 AI 有把握推断但需核实；升级裁决是 AI 无法判断、必须由人决定的分歧。

---

## 文档同步铁律（嵌入所有代码变更任务）

> **适用范围**：任何代码变更任务，无论是否进入完整反向同步流程，都必须执行此铁律。  
> 完整反向同步任务（模式 B）在此铁律之外，还需额外执行下方**六项收尾清单**。

即使不是专门执行反向同步，每次代码变更后也必须：

1. 以被改动的函数/模块名为关键词，搜索 `docs/[项目名]` 全文
2. 命中的段落逐一评估，输出三选一结论：
   - ①文档与新实现一致 → 无需变更
   - ②文档落后于实现 → 立即更新
   - ③实现偏离了原设计意图 → 告知用户，请求裁决
3. 在变更摘要中说明"此次同步修订了哪些文档段落、原因是什么"——这条记录本身就是最轻量的 ADR
4. **不允许产出"已修改代码，文档待后续更新"**

---

## 任务收尾强制清单（六项，逐项确认）

> **设计原则**：开放式收尾让 AI 倾向于挑最轻的做——能被省略的步骤必然被省略。固定六项、逐项打勾，是在剥夺"跳过"的选项。把必做项钉死，而不是依赖自律。

每次反向同步或代码变更任务完成前，必须逐项回答：

```
① 产物清单已确认
   PRACTICE 与 DESCRIPTION 已区分，扫描范围已声明（含"排除了什么、为什么"）。

② 差异已三选一处理（不允许"待定"）
   每处差异已明确输出：
     一致  → 跳过，原因记录
     落后  → 已更新文档，附定位
     偏离  → 已告知用户请求裁决，偏离点已用 〔FACT〕 写入，而非无声覆盖旧描述
   ⚠️ "偏离"最容易被误判为"落后"——开发者常把"我改得更好了"当成"这就是原计划"，
      悄悄把文档改成与新实现一致，丢失"这里发生过设计变更"的信息。
      偏离点 ≠ 文档错误；它是一条新的设计决策，应写入决策类文档。

③ OBSERVATIONS 已沉淀
   所有发现的问题已写入 OBSERVATIONS.md，带严重度、定位、处理状态。

④ 经验自问（反思，不是填表）
   回答一个问题：「如果再做一次这个任务，我希望提前知道什么？」
   ——这个问题会自然筛掉"其实没什么可沉淀的"场景，避免经验文档被灌水稀释。
   有答案 → 写入项目经验类文档（1-3条，不强求数量）
   无答案 → 显式写"本次无新洞察"，而不是跳过这一项

⑤ 待裁决项已显式列出
   所有归宿冲突、语义存疑、ZOMBIE 候选、需用户拍板的条目，已整理成清单告知用户。
   不允许含糊带过，不允许延期。

⑥ 入口文档已检查
   README / INDEX / 等价门面文档是否需要反映本次结构性变更。
   （不是每次都需要改，但必须有意识地检查过。）
```