---
date: 2026-05-10
type: process
tags: [documentation, audit, architecture, consistency]
---

# Architecture doc 写完别急着合——立刻拿来审 implementation（doc-vs-impl audit）

## 触发场景

写完一份描述系统的 doc（架构图、决策表、组件清单、验证命令、故障排查），doc 本身像 spec。**这种 doc 在写的瞬间就容易漂移**：

- 写 doc 时脑里的实现是「应该这样」，写完看代码可能差几个细节
- 写 transitional / target state 时容易把"将来要做的"误写成"已经在的"
- 引用的 input / config / API endpoint 可能不存在（虚构）
- 文字描述的 scope 名跟实际 PAT scope 字面值不一致
- mermaid / markdown 语法在目标 viewer 里实际渲染失败但你以为对了

PR #281 实际踩了——架构 doc 写完后做一轮 cross-check，发现 5 处不一致全部修齐才合。

## 5 类常见 drift（基于本次实例）

| 类型 | 表现 | 实例（PR #281） |
|---|---|---|
| **虚构 input / config** | doc 让用户用 `force-repair=true` workflow input | yml 实际只定义了 `dry-run` input |
| **transitional 当 target** | doc 段落语气说"已落地"，但实现仍是过渡态 | "1 步 yaml" vs 实际 4 步（3 步是 setup） |
| **scope / API 命名不准** | doc 用人话 / 旧名，代码 / 平台用工程名 | `labels:write` vs Gitea PAT 真实 scope `write:repository` |
| **指代过期** | 字段 / 文档说"由 X 创建"，但 X 已被 Y 取代 | issue.py 的 `LABEL_DESC` 仍指向 issue.py 自己 |
| **viewer 渲染断** | doc 语法对、后端 OK，但目标 viewer 解析失败 → 退化为 raw 代码 | mermaid `'## 候选改进'` 里的 hash 注释陷阱 |

## 审计方法（5 条 checklist）

完成架构 doc 后，**别 commit / 别开 PR**，先按这 5 条逐项对账：

### 1. 每条声明 grep 实现验证

doc 说"schedule: 周一 09:03 +0800" → 去 `.gitea/workflows/*.yml` 找 cron 字符串；doc 说"4 个分支" → 去 SKILL.md 数 `if`/`elif`。**每条声明 → 至少一个文件验证**，别相信脑里的版本。

### 2. 每个用户面命令 / 提示 / input 真敲一下

doc 让用户跑 `curl ...` 或 dispatch 加 `--force-repair=true` → 真的去敲一下、查一下 yml 有没这个 input。**虚构最容易出现在"补救流程"/"故障排查"段**——主流程会被反复跑过，补救流程可能从来没人跑过，写错了也发现不了。

### 3. transitional / target 段落特别警惕

写"当前 vs 目标"表格 = doc 自己承认有 gap → 审"当前"那栏是否真在；如果"目标"那栏即将被本 PR 落地，merge 前把那段改写为现在时（避免 doc 进库即过期）。

### 4. 每个引用 file / scope / variable / endpoint 名单独 grep

`WEEKLY_RETRO_TOKEN` / `weekly-retro-runner.sh` / `write:issue` / `/api/v1/...` ——每个去对应位置确认存在 + 拼写。**字符串一致性比设计一致性更容易出错**。

### 5. 打开实际 viewer 看一眼

mermaid / table / 内部 link / 高亮、在**目标 viewer** 里实际渲染。不要假设"语法对 = 显示对"。VS Code / Gitea web / GitHub web / 终端 cat 各打一遍——尤其当 doc 会被多种 viewer 看到时。

## 何时不做（避免过度工程）

- 5 行以下的小 README / 注释——写完 grep 一下就行
- 纯叙事文档（设计哲学 / 团队约定）没有代码 hook——audit 没意义
- 代码即将彻底重写——给即将变的代码做 audit 是浪费

## 收益

PR #281 的 audit 暴露 5 个问题，**每个单独看都很小**（一行注释、一个 input 名、一段 ASCII 字符），但合起来：reviewer 会困惑、用户会踩坑、doc 进库即过期。

Audit 本身比写 doc 便宜得多（5-10min vs 30-60min），且**审的过程会反向逼出 doc 本身的不清晰**——常常不止发现实现 drift，还会修正 doc 的措辞。

## Pattern 触发短语

写完任何 ≥1 页的「机制 / 架构 / 流程」类 doc 后，**默认下一步**：按上面 5 条 checklist 对账，**不要急着 commit**。

跟「写完代码先跑测试」是一个性质——doc 也是产物，写完也要跑一次"测试"。