Check — 变更验证与规则演进
Check 通过将 git diff 与 .hoyeon/rules/ 规则目录进行比对,捕捉遗漏的级联改动,并在检测到新的未匹配模式时提出规则更新建议。
前提条件:项目必须具有 .hoyeon/rules/ 目录,其中包含带有 YAML frontmatter 的规则文件。如果 .hoyeon/rules/ 不存在,需引导用户创建:mkdir -p .hoyeon/rules,然后帮助其按照 ${baseDir}/references/rules-authoring.md 编写第一个规则文件。
采用两阶段结构:
阶段一(始终执行):验证变更,生成 PASS/WARN 结果
阶段二(条件触发):仅在存在未匹配模式时,提出规则更新建议
阶段一:变更验证
- 收集变更文件
收集已提交 + 未提交的变更
git diff --name-only HEAD~1..HEAD git diff --name-only --cached git diff --name-only
去重后存储为 CHANGED_FILES。
- 构建规则图并匹配
读取所有 .hoyeon/rules/*.md 文件的 YAML frontmatter 来构建规则图。frontmatter 结构参见 references/rules-authoring.md 的“Structure”部分。
匹配顺序:
将 CHANGED_FILES 中的每个文件与每条规则的 triggers 模式进行 Glob 匹配
沿匹配规则的 depends_on 边引入相关规则(仅 1 层深度)
确定最终生效的规则集
将未匹配的文件单独存储为 UNMATCHED_FILES(供阶段二使用)
注意:元文档(例如 RULES.md)不参与匹配。
- 并行子代理验证
使用 Agent 工具(subagent_type="general-purpose")为每条生效规则启动一个子代理,并并行运行。
向每个子代理传入:
CHANGED_FILES 列表
规则文件正文(检查清单内容)
变更文件的实际 diff(git diff)
每个子代理需要:
将检查清单项应用于 CHANGED_FILES
识别出某个文件被修改但相关文件未被修改的情况
读取 WARN 项的实际 diff,判断遗漏是否为真实遗漏
返回分类为 PASS / WARN / Not Applicable 的结果
- 汇总并输出结果
收集所有子代理结果,按类别分组输出:先是 domain 规则,然后是 concern 规则,最后是 pipeline 规则。
阶段一:验证结果
PASS(N 项)
domain
- [billing] schema.ts 已变更 -> 迁移文件已创建
concern
- [infra] .env 已变更 -> terraform 已同步
pipeline
- [api-codegen] swagger 已变更 -> 类型已重新生成
WARN(N 项)
concern
- [ux] en.json 已变更 -> ko.json 未更新
Not Applicable(N 项)
- [docs] 无 docs/ 变更
- 执行 agents/commands
如果生效规则具有 agents 或 commands 字段:
agents:通过 Agent 工具自动运行以进行额外验证。将代理结果中的 WARN 合并到阶段一的 WARN 列表中。
commands:将命令呈现给用户手动执行(例如 pnpm generate:api)。
- 处理 WARN
针对每个 WARN 项:
读取变更的代码,判断是否确实需要改动
区分有意省略与意外遗漏
对于真实遗漏,明确指出需要修改的具体文件与位置
阶段二:规则更新提案(条件触发)
阶段二触发条件——满足以下任一条件即执行阶段二:
UNMATCHED_FILES 包含至少一个有意义源文件(.ts、.tsx、.json、.yaml、.tf 等)——排除元文件(.md、锁文件等)
阶段一中有任一 WARN 表明存在规则缺口(而非规则违规)
跳过条件:如果 UNMATCHED_FILES 为空且没有 WARN 表明规则缺口,则跳过阶段二,直接进入后续操作(第 9 步)。
区分规则缺口与规则违规:如果某个 WARN 是由于违反了现有检查清单项导致的,则属于规则违规(在阶段一处理)。如果任何地方都不存在可提前捕获该 WARN 的检查清单项,则属于规则缺口——触发阶段二。
- 分析模式并交叉比对规则
分析 UNMATCHED_FILES 和阶段一 WARN 结果,识别:
未覆盖的变更模式——未被任何规则 triggers 匹配的文件变更
接近命中的级联变更——多处存在重复逻辑,但仅部分被更新
新发现的同步点——修改一处需要更新另一处的关系
阅读 references/rules-authoring.md 获取编写指南,然后对发现进行分类:
现有规则需新增条目——建议要添加到规则文件中的具体条目
需要新规则文件——现有规则未覆盖的全新模式;包含 category 字段(domain | concern | pipeline)
- 输出规则更新提案
阶段二:规则更新提案
- [subscriptions.md] 为 3 个应用中的 URL 检测函数添加同步检查
- 原因:isSubstackUrl() 在 3 处重复,仅 2 处更新
- [新文件:webhook.md] 为 webhook 事件变更添加同步检查
- category: domain
- 原因:新领域,现有规则未覆盖
使用 AskUserQuestion 确认每个提案:
“Add”——将条目应用到规则文件
“Edit & Add”——添加前调整内容
“Skip”——不必要,跳过此项
将批准的条目应用到对应规则文件。对于新规则文件,使用 frontmatter 创建(category 和 triggers 为必填)。
添加或修改规则后,验证 frontmatter 的 triggers 模式能正确匹配合适的文件。
- 后续操作
将阶段一的 WARN 与阶段二的规则更新合并为后续变更列表。
如果存在一个或多个 WARN 项,呈现列表并使用 AskUserQuestion 询问用户:
“Fix All”——自动修复所有 WARN 项
“Select”——选择特定项修复(multiSelect)
“Ignore & Proceed”——视为有意省略,不做改动直接完成
当选择“Fix All”或“Select”时,按顺序应用修复并显示更新后的结果。
附加资源
参考文件
${baseDir}/references/rules-authoring.md——规则编写原则、frontmatter 结构、类别分类及抽象层级指南。在创建或更新规则时查阅。