---
name: standards-audit
description: >
  当用户刚写完一份项目规则 / 标准文档（docs/standards/*.md / .agents/skills/<x>/references/*.md /
  CLAUDE.md / AGENTS.md 改动段），merge 前需要做"事实准确性 + 跨文档一致性 + 漂移"审计时使用。
  与 doc-review 的"够不够实现"正交，本 skill 关注"写的对不对、跟代码一致不一致、跟入口文档漂移没有"。
  8 个 Lens 检查（事实/内部/入口一致性/完整性/可执行性/链接/过期/格式），任一个挂掉都不该 merge。
  触发短语：审一下规则文档、standards 审计、事实准确性审、刚写完的 reference 文档审一下、
  8 角度审、merge 前再审一遍、standards review、rules audit、检查文档对不对。
  不触发：审 PRD 实现就绪度（用 doc-review）、审实施方案（用 plan-review）、审 skill 本身（用 skill-audit）、
  审 PR 代码（用 code-review）、写文档时的一致性检查（用 docs-main §3 五 cell 矩阵）。
---

> **最后更新**: 2026-05-16
> **下次复查触发条件**: doc-review skill 的 Lens 数量变更 / CLAUDE.md「核心不变量」段大改 / 出现 8 个 Lens 之外的新审计角度 / 季度复查

# 标准文档审计技能（standards-audit）

## 定位

对**刚写完的项目规则 / 标准类文档**做 merge 前最后一道事实审计。覆盖范围：

- `docs/standards/<N>-*.md`（项目级标准）
- `.agents/skills/<skill>/references/*.md`（skill 参考资料）
- `CLAUDE.md` / `AGENTS.md` 的规则段改动
- `docs/ops/*.md`（运维事实源）
- learning 升级类 PR（多条 `.learnings/` 整合成事实源）

**核心问题**：写得对不对、跟当前代码状态一致不一致、跟项目入口文档（CLAUDE.md/AGENTS.md）漂移没有。

**不审**：PRD 完整度（用 `doc-review`）、实施方案合理性（用 `plan-review`）、skill 设计合理性（用 `skill-audit`）、PR 代码（用 `code-review`）。

## 何时使用 / 不该使用

**使用本 skill**：

- 新写一份 `docs/standards/<N>-*.md`，准备 commit + PR
- 写完 `.agents/skills/<x>/references/<y>.md`，准备 merge
- 改了 CLAUDE.md / AGENTS.md 的规则段（特别是引用 API 配置、文件路径、命令的段）
- 跨多条 learning 沉淀出的事实源文档（典型场景：本 skill 诞生的场景——165 条 learning → 3 份 standards 升级）
- 用户说"审一下这份规则文档"、"事实准确性再核一下"、"merge 前最后一道关"

**不要用本 skill**：

- 写模块 PRD / data-model / API / UI 文档审实现就绪度 → `doc-review`
- 审实施方案是否合理 → `plan-review`
- 审 skill 自身（`SKILL.md` 怎么写）→ `skill-audit`
- 单字段 tweak / 单文档小改 → `docs-main` §3 五 cell 矩阵
- 审 PR 代码改动 → `code-review`

## 与现有 skill 的边界

| Skill | 审什么 | 跟本 skill 的差 |
|---|---|---|
| `doc-review` | PRD / data-model / API / UI 实现就绪度（5-lens 含 Lens E DR/灾备） | doc-review 问"够不够实现"，本 skill 问"写的对不对" |
| `plan-review` | 实施方案 / 架构 / 数据流合理性 | plan-review 是写文档前，本 skill 是写完文档后 |
| `skill-audit` | skill 本身（`SKILL.md` 是否有效） | skill-audit 审 skill 设计，本 skill 审任意 standards 文档 |
| `code-review` | PR 代码 | code-review 不审文档 |
| `docs-main` §3 五 cell 矩阵 | 跨 5 份模块文档的字段一致性 | 五 cell 是单字段维度，本 skill 是整段事实维度 |
| `contract-check` | 改动是否触碰契约面 | contract-check 是开工前判定，本 skill 是收尾审计 |

## 核心工作流

### Step 0 — 确认审计目标

- 列出要审的文档清单（绝对路径）
- 读全文（不要只读 diff —— 事实准确性可能在未改的段落里也漂移）
- 列出"这份文档引用的代码 / API / 文件"清单，作为 Lens A/E 的核对源

### Step 1 — 8 Lens 顺序检查

Lens 之间独立但有强弱：**A + C + E 是硬性的，任一挂掉禁止 merge**；B/D/F/G/H 是建议级。

按 A → C → E → B → D → F → G → H 顺序跑，效率最高（前 3 个最容易抓真错）。

#### Lens A — 事实准确性（硬性）

**问题**：文档每条 claim 跟当前代码 / API / 文件状态是否一致？

**怎么做**：

```bash
# 1. 抽出所有"具体"claim：路径、API 字段、行为、配置值
# 2. 对每条 claim 跑一次校验：

# 路径类 → 直接 ls / find
ls <path-claimed-in-doc>

# 代码行为类 → grep 实际代码
grep -nE 'pattern' <file>

# API 配置类 → 真实调用
curl -H "Authorization: token $X" <api> | jq '<field>'

# 命令 / 脚本类 → 真敲一遍
bash <script> --dry-run
```

**示例**（本项目）：
- doc 写"`required_approvals=1` 在三个分支"→ 真调 `/branch_protections/<branch>` API 拉实际值
- doc 写"`scripts/ops/gitea promote` 子命令支持 `--dry-run`" → `grep -n 'dry-run' scripts/ops/gitea`
- doc 写"`@SkipTransform` 在 `backend/src/common/decorators/`" → `ls backend/src/common/decorators/skip-transform.decorator.ts`

**输出**：每条 claim 标 ✓ / 🔴 / 🟡。🔴 必须修。

#### Lens B — 内部一致性

**问题**：文档内 §X 跟 §Y 是否自相矛盾？

**怎么做**：

- 列出所有数字、字段名、文件路径、规则陈述
- 跨章节扫看是否同一概念多种说法
- 表格里写的状态跟正文描述是否一致

**示例**：§3.2 说"5 req/30s"，§5.1 表格写"limit=5 ttl=30000ms" —— 必须用同一个标号风格，不能一处秒一处毫秒。

#### Lens C — 跟入口文档一致性（硬性，双向检查）

**问题**：文档跟 CLAUDE.md / AGENTS.md / 已有 `docs/standards/` 是否漂移？

**怎么做**：

- grep 入口文档里跟本文档主题相关的段
- 对比"两边说法"
- **漂移时不静默改一边**——要么两边同步，要么显式标注

**双向规则**：

| 情况 | 处理 |
|---|---|
| 本文档对 + 入口文档错 | 同步修入口文档（CLAUDE.md + AGENTS.md 必须一起改，按 CLAUDE.md §定位段的硬规则）+ 本文档加 timestamp |
| 本文档错 + 入口文档对 | 修本文档 |
| 两边都跟代码漂移 | 跑 Lens A 确定真实状态，**两边同步到真实状态** |
| 两边一致但都过期 | 同上 |

**反模式**：发现漂移后偷偷改其中一边让它跟另一边一致——违反 CLAUDE.md 不变量 #2「禁止静默决策」。

**示例**（本 skill 诞生场景）：写 `docs/standards/16-gitea-actions-platform-semantics.md` 时发现 CLAUDE.md line 272 写"三分支 `required_approvals=1`"，但 API 实测 develop=0。**正确做法**：先把 develop=0 写进 16-...md（实测为准）+ 显式标 "⚠️ CLAUDE.md 漂移"，然后单独修 CLAUDE.md + AGENTS.md 两段。

#### Lens D — 完整性

**问题**：跟源 learning / 用户需求 / 历史踩坑清单对比，是否漏？

**怎么做**：

- 如果是 learning 升级：列出原 N 条 learning，逐条核对是否在文档里有归属
- 如果是新规则：列出预期覆盖的子主题，逐项确认在文档里有段落
- 如果是 CLAUDE.md / AGENTS.md 改动：检查并行入口文档是否同步（强规则）

**示例**：本项目把 28 条 Gitea Actions learning 沉淀到 `16-...md`，最后必须列出 28 条 learning 索引段确认每条都有 §X 归属，不能丢条。

#### Lens E — 可执行性（硬性）

**问题**：文档里给的命令 / API 调用 / 代码示例真敲一遍能跑吗？

**怎么做**：

- 命令类：复制到 shell 跑
- API 类：复制 curl 跑
- 代码示例类：放到一个小项目里 build

**为什么硬性**：standards 文档的可执行示例往往是 readers 第一次接触某机制时复制粘贴的入口。"看起来对但跑不通"会直接误导。本项目踩过的（learnings 里有）：
- `ai-review-runner.sh` 文档里写的 grep 命令在新版 grep 上 exit 1（learning 在 `2026-05-11-ai-review-runner-first-pr-no-prior-comment.md`）
- `git diff-tree --stdin` 必须末尾 newline，文档写漏的话静默 drop 最后一行

#### Lens F — 链接有效性

**问题**：所有 `]()` / `<path>` 引用能解析到真实文件吗？

**怎么做**：

```bash
# 抽文档里所有 markdown link
grep -oE '\]\([^)]*\.md[^)]*\)' <doc> | sed 's/.*(\(.*\))/\1/' | sort -u

# 逐条 ls 验证
for p in <list>; do [ -e "$p" ] && echo "✓ $p" || echo "✗ MISSING: $p"; done
```

**注意点**：

- 相对路径要按文档自身位置解析（`.agents/skills/X/references/Y.md` 引用 `../../Z/references/W.md` 要算对）
- 外部仓库引用不要用本仓库相对路径——用纯文字描述
- 跨仓库 / 跨平台链接（如 Gitea / GitHub）保留全 URL

#### Lens G — 过期信息

**问题**：claim 跟当前代码 state 比对，"上次写时对、现在还对吗"？

**怎么做**：

- 看 doc 顶部的"最后更新"日期跟引用代码的 git log 对比
- 检查 doc 引用的脚本 / 配置自上次更新后是否被改过
- 特别关注：分支保护规则、API endpoint 路径、文件位置（容易被重构）、版本号

**与 Lens A 的差**：A 是"现在对不对"（绝对真假），G 是"上次写时对、现在变了没"（time drift）。两者结合用。

**输出**：建议在文档头部加"下次复查日期"约定（如 N 个月 / 触发条件）。

#### Lens H — 格式 / 标题层级 / Markdown

**问题**：标题层级一致？表格能渲染？code block 有 language tag？

**怎么做**：

```bash
# 检查 H2/H3 一致性
grep -nE '^## |^### ' <doc>
# 检查 code block 是否标 language
grep -nE '^```$' <doc>   # 应为 0 行；裸 ``` 没有 language 不利于 syntax highlight
# 检查表格分隔符列数一致
```

**特殊**：mermaid diagram 节点标签里有 `#` 会被当注释（参考 `.learnings/2026-05-10-mermaid-hash-comment-trap.md`），用双引号包。

### Step 2 — 输出审计报告

格式（按本 skill 诞生场景示范——见下方）：

```markdown
# 🔍 多角度审计报告

## 验证维度（8 角度全跑过）

| 角度 | 方法 | 结果 |
|---|---|---|
| A 事实准确性 | API + grep + 代码读 | 🔴 X 错（已修 / 待修） |
| B 内部一致性 | ... | ✅ 无矛盾 |
| C 跟入口文档一致性 | grep + 对比 | 🟡 CLAUDE.md 漂移（已 surface / 已同步修） |
| D 完整性 | 列表对照 | ✅ 全覆盖 |
| E 可执行性 | 真敲一遍 | ✅ 全通过 |
| F 链接有效性 | for ls | 🔴 X 失效（已修 / 待修） |
| G 过期信息 | git log + 对比 | ✅ 全 fresh |
| H 格式 / 标题层级 | grep | ✅ 一致 |

## 发现的错误（按严重度）

| # | 严重度 | 位置 | 问题 | 修法 |
|---|---|---|---|---|
| 1 | 🔴 | ... | ... | ... |

## 验证通过的关键 claim（确认无误）
- ✅ ...
- ✅ ...

## 重要发现（需要用户处理）

> ⚠️ CLAUDE.md / AGENTS.md / 其它入口文档 也漂移的情况：surface 出来，不静默改

## 最终规模
```

### Step 3 — 收敛建议

跑完后给用户：

1. **必须修**（🔴 Lens A/C/E 任一）：列出来，等用户确认后再修
2. **建议修**（🟡 Lens B/D/F/G/H）：列出来，用户决定批量修还是只挑重要的
3. **跟入口文档的同步动作**：如果发现入口文档漂移，明确告诉用户要不要顺手修，**两份入口文档必须同步**

## 输入要求

调用本 skill 时用户应提供：

- 要审的文档路径清单（一份或多份）
- （可选）源 learning / 需求清单（如果是 learning 升级场景）
- （可选）特别关注的 Lens（默认 8 个全跑）

## 输出要求

- 中文报告
- 每个 🔴 错误必须给出具体修法（不只是"不对"）
- 每个 🟡 给优先级建议
- 跟入口文档漂移**必须显式标注并 surface 给用户**，不静默修

## 反模式（避免）

| ❌ 反模式 | ✅ 正确做法 |
|---|---|
| 凭印象审"看起来差不多" | 每条 claim 都要 grep / curl / ls 验证 |
| 发现 CLAUDE.md 漂移就偷偷按 CLAUDE.md 改文档 | surface 出来让用户决定，必要时反向修 CLAUDE.md |
| 只审改动段不审全文 | 全文审——事实漂移可能在未改段落 |
| 跳过 Lens E（可执行性）"应该没问题" | 命令真敲一遍，AI 生成的命令经常有微妙错误 |
| 漏 Lens F 链接有效性"看着对" | 跑一次 `for f in <links>; do ls $f; done` |
| 写完不加复查日期约定 | doc 头部加"最后更新 + 下次复查触发条件" |

## 触发关联

- **强烈建议触发**：写完 `docs/standards/<N>-*.md` / `.agents/skills/<x>/references/*.md` / 改 CLAUDE.md / AGENTS.md 规则段后
- **必须触发**：learning 升级 PR（多条 learning 整合）
- **不要触发**：写 PRD / data-model / API / UI（用 doc-review）

## 参考

- [`doc-review/SKILL.md`](../doc-review/SKILL.md)（PRD 实现就绪度审，跟本 skill 互补）
- [`skill-audit/SKILL.md`](../skill-audit/SKILL.md)（审 skill 自身，跟本 skill 边界）
- CLAUDE.md / AGENTS.md 「核心不变量」段（Lens C 双向同步规则的底层依据）
- 本 skill 诞生场景：2026-05-16 整理 165 条 learning → 3 份 standards 升级时发现"事实源文档自身漂移"，反推出 8 角度审计模式