optimize-rules

name	optimize-rules
description	分析并优化 .omp/rules/ 文件，修复过时内容、缺失覆盖、冗余规则和未记录的约束。在重构后规则与代码脱节时使用，或当 Claude 开始忽略/误用规则时使用。
argument-hint	[范围: all | <规则文件名>]

用途

审计并更新 .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