18 第四篇 · 长期：让项目越用越聪明

从规则到机器检查

文字规则可以解释意图和取舍，却不能保证每次都被读到和执行。能够确定判断对错的约束，应尽量写成类型、测试、lint 规则或检查脚本，再接到合适的执行位置。只有检查确实运行，并且失败会阻止目标动作时，它才形成门禁。

机器化不是让每条 lesson 依次经过 steering、skill、hook、lint 和 CI。应根据约束能否确定判断、违反后的风险和检查成本，直接选择成本最低且足够可靠的控制。仍然需要取舍的事项留给评审和人工判断。

18.1 机器检查的三个组成部分

一条机器规则能否生效，要分别看它怎样表达、何时执行，以及失败后阻断什么：

检测器和门禁不是一回事。写出一条 lint 规则，只解决了”能不能发现”；把它接进必需 CI，并让失败返回非零状态，才解决”能不能阻止合并”。提交钩子能提前反馈，但每个克隆仓库都要安装，也可能被绕过；需要强制执行的检查还要在 CI 中运行。

类型和数据结构可以让一部分非法状态无法表达，但不是所有架构边界都能靠类型保证。跨模块依赖、文件布局或禁止调用某个接口，可能需要结构检查；产品取舍、风险接受和可维护性判断仍要由人处理。机器检查给出可重复的结果，但也可能误报、漏报或只报告失败而不说明修法。

文字规则仍有作用。它说明为什么存在这条约束、适用范围是什么、失败后去哪里修；机器负责重复判断和执行阻断。两者可以共同存在，不必互相取代。

反复出现是评估机器化的信号，不是唯一判据。决定是否建立检查前，先回答下面几个问题：

第一次出现的普通问题可以先记成踩坑记录，复发后再评估是否值得机器化。“第三次出现”可以作为启动评估的提醒，不能代替上面的判断。高严重度问题不必等待复发；只要边界明确，一次事故也可以直接推动测试、安全扫描或 CI 门禁。反过来，需要人工取舍的问题出现很多次，也不应勉强写成不可靠的检查。

skill 也不是必经的升级层。它适合封装需要按步骤执行、要读取材料或调用工具的工作流；能由一个确定命令判断的规则，可以直接写成检查并接进门禁。环境或工具链能够解决的问题，优先修环境和检查，不在提示词中反复追加同义提醒。

把一条已有规则改造成机器门禁，可以按下面的顺序进行：

通过标准：坏样例稳定失败，合法样例通过；检查会在约定事件中实际运行；需要阻断时，失败确实会阻止提交或合并；输出能指向违反位置和修复入口；对应的文字规则没有与机器逻辑形成两份可能漂移的真相源。

本手册的配套方案提供了三类基础部件，但没有预置适用于所有技术栈的完整门禁：

hook 配置展示了如何在指定事件上执行命令。支持哪些事件、能否阻断以及输入格式，要按当前客户端和版本验证。
check-steering.sh 检查 steering ID、重复规则编号、残留占位符和基线文件是否缺失。它不判断跨文件语义是否一致，部分项目状态只报告警告。
ast-grep 可以按语法结构搜索和改写代码。它本身不是门禁；项目要把具体模式写成规则，让失败状态可被调用方识别，再接入 hook 或 CI。

语言相关的 formatter、linter、类型检查、测试和安全扫描由项目按技术栈配置。template 提供接入位置和通用纪律，项目负责选择检查器、写规则、建立正反样例，并把必须执行的检查设为合并门槛。

机器门禁由约束表达、执行位置和失败处置共同组成，写出检查器不等于已经强制执行。反复发生是机器化信号，高严重度问题可以直接建立门禁；能否稳定判断、检查成本和风险共同决定落点。检查上线前要用正反样例验证，接入后仍要复测和清理过期规则；文字只保留机器无法表达的理由、范围和修复入口。