# Optimize Rules

> 分析并优化 .omp/rules/ 文件，修复过时内容、缺失覆盖、冗余规则和未记录的约束。在重构后规则与代码脱节时使用，或当 Claude 开始忽略/误用规则时使用。

- Skill: `ghost-him/optimize-rules` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add ghost-him/optimize-rules`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ghost-him/optimize-rules/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: ghost-him (https://skillmd.com/u/ghost-him)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ghost-him/optimize-rules

---


## 用途

审计并更新 `.omp/rules/` 文件，使其保持准确、精准、精简。本技能会在规则文本与实际代码之间进行系统性的交叉比对，然后应用修复。

## 触发时机

在重大重构之后、规则文件长期未更新时，或 Claude 报告"找不到 X"但规则声称 X 存在时调用。

## TTSR 规则结构

本技能审计的 `.omp/rules/*.md` 文件是 TTSR（Time-Traveling Stream Rules）规则，通过 frontmatter 中的 `condition`（触发正则）和 `scope`（流范围）决定**何时触发**和**在哪触发**。

### 数据流向

```
助手在"说话"（生成回复）
     │
     ├─ 写自然语言（text）──→  text 缓冲区
     ├─ 思考过程（thinking）──→  thinking 缓冲区
     └─ 调用工具（tool）──→  tool 缓冲区
                                │
                                ▼
                  每个缓冲区的内容不断累积，
                  每来一段新内容就拿 condition 正则去匹配
                                │
                          匹配上了？
                           ├─ 否 → 继续流
                           └─ 是 → scope 允许在这个场景触发吗？
                                      ├─ 否 → 继续流
                                      └─ 是 → 中断助手 → 注入规则内容 → 重试
```

### 关键术语

- **"流"（stream）**：助手生成回复不是一次性给的，是一段一段（像水流一样）陆续产生的。规则检查在流中进行。
- **三种流来源（source）**：
  - `text` — 助手写的自然语言正文
  - `thinking` — 模型的思考过程
  - `tool` — 助手调用工具时传的参数（如 `edit` 工具传的补丁内容、`write` 工具传的文件内容）
- **condition（触发正则）**：正则表达式，匹配流缓冲区内容。命中时触发规则检查（如果 scope 也允许）。审计时重点验证：(a) condition 是否实际匹配它声称要约束的代码模式，(b) condition 是否过于宽泛导致误触发
- **scope（流范围）**：定义哪些流来源（`text`/`thinking`/`tool`）在哪些路径上允许触发。审计时重点验证 scope 是否覆盖了规则约束的所有文件路径

有关 TTSR 规则的完整设计指南，参见 `skill://add-rule`。

## 执行流程

### 第一阶段：并行发现（6 个 agent）

如果传入了 `args`（如 `".omp/RULES.md"` 或 `"plugin-system.md"`），则所有 Agent **只分析指定的规则文件**。如果 `args` 为 `"all"` 或未传入，则分析全部 `.omp/rules/*.md` 文件。

同时启动六个 Explore agent，各负责一个维度：

**Agent 0 — Frontmatter 覆盖分析**

- 逐一分析每个规则文件的 `scope` 和 `condition` frontmatter，验证两者是否准确覆盖规则所约束的领域
- **scope 检查**：用 Glob 展开 `scope` 中所有通配符得到实际覆盖的文件集合，与规则正文提及的路径比对：
  - 明确引用的文件路径（如 `core/config/manager.rs`）
  - 明确引用的目录（如 `builtin_plugin/config/`）
  - 明确引用的 crate（如 `plugin-api`、`plugin-protocol`、`platform-windows`）
  - **主题隐含范围**：从规则标题和核心内容推断该规则所约束的代码领域（如 `sdk.md` 主题是整个 SDK 层，约束范围 = trait 定义 `crates/plugin-api/src/` + 平台实现 `crates/platform-windows/src/` + re-export 桥 `src-tauri/src/sdk.rs`）
  - **核心检验**：如果规则说"X 定义在 Y"或"在 Z 目录下添加"但 Y/Z 不在 `scope` 里 → 编辑 Y/Z 时该规则**不会被触发** → 覆盖缺失
- **condition 检查**：
  - 验证 condition 正则是有效且合理的：无空串、无纯空白、`|` 分割的每个原子项本身是合法正则
  - 对每个原子项，在代码库中搜索其是否真实出现（grep），判断 condition 是否实际匹配它声称要约束的代码模式
  - 判断 condition 是否过于宽泛导致大量误触发（如 `File|file` 这种常见词），或过于狭窄漏掉常见变体
- 报告：(a) `scope` 条目覆盖不足的路径，(b) 规则约束的整个域完全不在 `scope` 中，(c) 过宽或过窄的 scope 模式，(d) condition 无效正则或空字符串，(e) condition 原子项在代码中无匹配（规则声称约束但 condition 永远触不发），(f) condition 过于宽泛常见（高误报风险）
- 严重程度分级：
  - **高**：规则约束的核心域超过 50% 不在 `scope` 内；condition 永远无法触发（未匹配任何代码）
  - **中**：规则引用了次要依赖但未覆盖；condition 过于宽泛可能误触发
  - **低**：单一边缘路径遗漏；condition 缺少一两个常见变体
- 报告格式：
  ```
  ## Agent 0 报告 — Frontmatter 覆盖分析
  ### 发现
  - **<严重程度: 高/中/低>** | <规则文件> | <问题字段: scope/condition> | <当前值> | <问题描述> | <建议修复>
  ```

**Agent 1 — 结构覆盖**

- 通读目标规则文件的全部内容
- 对规则中声称的每个文件路径、目录树和模块清单，通过 Glob 验证磁盘上是否存在
- 报告：(a) 规则**正文**中存在的路径在磁盘上 **不存在**，(b) 磁盘上存在但规则**正文**中 **缺失** 的路径，(c) 数值声明（文件数/插件数/命令数）与实际情况不符的地方
- **注意**：此 Agent 只检查规则**正文**中提到的路径是否正确，**不**检查 `scope` frontmatter 的覆盖范围（由 Agent 0 专门负责）
- 报告格式：
  ```
  ## Agent 1 报告 — 结构覆盖
  ### 发现
  - **<严重程度: 高/中/低>** | <规则文件> | <规则声称 X，实际是 Y> | <建议修复>
  ```

**Agent 2 — 代码与规则匹配**

- 通读目标规则文件的全部内容
- 对每条行为约束（如"使用 X 模式"、"禁止 Y"、"必须 Z"），通过 Grep 和 `codegraph_explore` 与实际代码进行比对验证
- **condition 模式验证**：取规则 `condition` 的每个原子项，在代码库中搜索是否存在匹配——如果 condition 声明的模式在代码中找不到匹配，说明该 condition 实际无法触发，规则成为"死规则"
- 报告：(a) 规则声称的模式在代码中被违反，(b) 规则声称的模式已不再适用（相关代码已被重构），(c) 规则引用了已删除的类型/函数/模块，(d) condition 原子项在代码中无任何匹配（死规则）
- 报告格式：
  ```
  ## Agent 2 报告 — 代码与规则匹配
  ### 发现
  - **<严重程度: 高/中/低>** | <规则文件> | <约束原文> | <代码现状> | <建议修复>
  ```

**Agent 3 — 新模式发现**

- 运行 `.omp/skills/optimize-rules/scripts/git-changes.sh` 识别近期的结构变更（优先找与远程默认分支的 merge-base → 显示分支全量变更；找不到时回退到最近 15 个提交）
- 通过 `codegraph_explore` 搜索新引入的模块、新 trait、新事件通道、新依赖方向等
- 报告：需要文档化的新约束/新模式（重构中产生但尚未在规则中体现的架构约定）
- 报告格式：
  ```
  ## Agent 3 报告 — 新模式发现
  ### 发现
  - **<严重程度: 高/中/低>** | <涉及的规则文件或建议新建> | <新模式描述> | <建议添加的规则内容>
  ```

**Agent 4 — 最佳实践审计**

- 通读目标规则文件的全部内容，按以下清单逐项审计：
  1. **长度**：是否有规则文件超过 200 行？（超过则建议拆分）
  2. **模糊规则**：是否使用"注意""合理""适当"等模糊词汇而无具体、可验证的标准？
  3. **有禁无导**："不要做 X"但没有给出"应该做 Y"的替代方案？
  4. **冗余**：规则是否重复了 linter/formatter（rustfmt、clippy、ESLint）已经能强制的内容？
  5. **无因规则**：约束陈述了但没有解释**为什么**？
- 报告：违反最佳实践、应收紧或删除的规则。对每条问题规则给出具体的替换文本或删除建议。
- 报告格式：
  ```
  ## Agent 4 报告 — 最佳实践审计
  ### 发现
  - **<严重程度: 高/中/低>** | <规则文件> | <违反的检查项> | <原文摘录> | <建议修复或删除>
  ```

**Agent 5 — Condition 触发重叠与同质/异质判定**

- 术语前提：检查对象是 `condition`（触发正则）+ `scope`（适用路径），即规则文件实际 frontmatter
- 扫描所有规则 `condition`，按 `|` 切成原子项，构建"原子项 → 命中规则"映射
- 找出 `condition` 交集非空的规则对，**先判性质再定处理**：
  1. **同质** —— 小规则是大规则主题的子方面（描述同一条规则，离开大规则主题无独立意义）→ **合并**：删小规则，大规则 `condition` 保留完整并集
  2. **异质** —— 大规则由多个完全不同/不相关/方向不一样的规则用 `condition` 并集捆绑，小规则是可独立成立的不同关切点 → **拆分**：保留/恢复小规则，大规则移除对应 `condition` 原子项与正文段落
  3. **语义冲突** —— 同一触发点给出相反指导 → 删其一，保留正确方
- 判定准则（内嵌，不依赖执行者另查原则）：触发重叠 ≠ 内容冗余；判定顺序是"先同质/异质，再决定合并/拆分"，禁止一见重叠就删小规则。区分关键：小规则是"大规则主题的子方面"（同质）还是"可独立成立的不同关切点"（异质）
- 报告格式：
  ```
  ## Agent 5 报告 — Condition 触发重叠与同质/异质判定
  ### 发现
  - **<严重程度: 高/中/低>** | <规则对> | <性质: 同质/异质/语义冲突> | <重叠的原子项> | <建议: 合并/拆分/删其一>
  ```

### 第二阶段：综合发现

阅读六份 agent 报告，产出一份合并差异清单：

1. **需要修改的文件** — 按严重程度排序（最严重排最前）
2. **每个文件的具体改动** — 增、删、改的具体内容
3. **需要新增的规则** — 重构中产生但尚未文档化的模式
4. **违反最佳实践** — 按 `.omp/RULES.md`（工程纪律）和 `.omp/rules/`（条件规则）的最佳实践需要收紧、拆分或删除的规则
5. **冲突规则** — 两条或多条规则之间存在矛盾，需要再次审查，决定保留哪条、删除哪条

### 第三阶段：呈现计划

进入 plan 模式，将综合发现以结构化计划形式呈现，计划必须：

- 按规则文件分组，严重程度排序
- 每处改动说明具体的失配（规则说 X，代码实际是 Y）
- 对每条过时/错误的规则给出具体的替换文本
- 按"缓慢添加，果断删除"原则，标记应该 **删除**（而非仅更新）的规则

### 第四阶段：执行（用户批准后）

应用所有已批准的改动，然后验证：

1. `cargo check` 通过（本技能专用于 ZeroLaunch-rs Rust 项目）
2. 更新后的规则中提到的每个文件路径在磁盘上确实存在（逐个 Glob 验证）
3. 快速一致性检查：是否有两条规则现在互相矛盾？
4. **并集守恒**（仅适用于拆分组）：拆分后小规则 `condition` ∪ 大规则(新) `condition` == 原大规则 `condition`，触发覆盖不丢失
5. **零重叠**（仅适用于拆分组）：拆分后两规则 `condition` 交集为空，不再重复触发
6. **同质/异质复核**：对每对重叠规则，确认"小规则是大规则主题子方面（同质）还是独立关切点（异质）"的判定成立

## 核心原则（适用于规则文件）

以下原则指导本技能的所有判断：

1. **"如果删掉这条规则，AI agent 会不会更容易犯错？"** — 唯一的试金石。如果删掉一条规则不会改变 agent 的行为，立即删除。
2. **有原因的规则才具有泛化能力** — 每条约束必须解释为什么。"不要做 X，遇到这种情况应该做 Y"是禁止性规则的标准格式。
3. **不要记录工具已经能强制执行的内容** — 如果 ESLint/rustfmt/clippy 已经能捕获，就不要写进规则。
4. **缓慢添加，果断删除** — 每次出错就加一条规则是膨胀之路。等同一类错误重复出现 2-3 次再固化为规则。
5. **积极使用 scope 限定作用域** — 如果规则只适用于 `commands/` 或 `plugin_system/`，用 `scope` frontmatter 限定。不要全局加载。
6. **目标每个文件不超过 200 行** — 超过则按主题或路径拆分。
7. **具体优于模糊** — 将"注意性能"替换为具体、可验证的标准。
8. **审计冲突** — 两条规则说相反的话 = 两条都不会被遵循。积极消解冲突。

## 参考资料

- OMP 官方文档: https://omp.sh/docs
- OMP TTSR 规则: https://omp.sh/docs/customization/ttsr-rules
- 规则文件最佳实践: https://omp.sh/docs/customization/context-files