heuristic-to-deterministic

从启发式到确定性

将会话中的经验教训和反复出现的审查启发式转化为可重复的检查、规范化器、生成器、测试样例、CI 作业和可用于钩子的工作流。

决策树

你要转换的是哪类启发式？

• 关于必须或禁止的结构的规则 使用或扩展验证器。如果需要详细了解如何选择产物，请参阅 references/conversion-patterns.md。

• 关于规范格式、图像形状、生成输出或元数据清理的规则 有现成规范化器时优先复用，然后验证其后置条件。

• 反复出现的脚手架或生成文件布局 根据清单或明确的计划使用或扩展生成器。只修正输出契约所要求的结构；将附带的文件组织方式留作可编辑项。

• 不稳定的环境或跨平台故障 针对故障选择运行时发现、版本检查、测试样例或 CI 覆盖。如果需要详细了解验证深度，请参阅 references/verification.md。

• 针对生成媒体或模型输出的提示词指南 保留提示词框架作为源文件，然后针对脚本可检查的属性添加确定性的后置检查。

• 没有可衡量信号的品味或判断 不要假装它是确定性的。记录示例、征求验收标准，或将其留作审查指南。

快速参考

需求	产物	首要操作
防止缺少文件、README 区块、钩子或配置	验证器	编码不变量，并在失败时输出可操作的信息
让不同机器上的输出保持一致	规范化器	在验证前清除元数据、对键排序、调整大小、格式化或规范化
避免手动复制脚手架	生成器	使用清单或计划文件作为事实来源
阻止重复回归	测试样例或黄金测试	添加修复前会失败的正反示例
在钩子和 CI 中复用检查	轻量包装器	保持核心命令可移植，并可由多个适配器调用
转换模型艺术作品或文本规则	提示词框架加后置检查	保存提示词，然后验证尺寸、路径、格式或必需的元数据

操作约定

1. 从经验教训出发，而不是从工具出发。先用一句话写出观察到的故障，再选择产物。
2. 只转换稳定的论断。对于相关但不稳定的 API 或产品论断，提供适当的权威依据：带版本的文档、已安装工具的帮助信息、功能探测或当前的一手文档。当规则依赖时效性时，及时更新依据。
3. 将判断与执行分开。在小型计划中由人或 Agent 决定策略；由脚本执行结构、路径、架构、大小和兼容性检查。
4. 在预期范围内保持检查的可移植性。复用工具的项目根目录发现机制，或接受目标路径；避免使用特定于机器的绝对路径。
5. 遵循工具文档规定的退出语义和调用方契约。仅当调用方有此要求时，才对阻止钩子继续执行的失败使用退出代码 2；必要时在边界处转换代码。
6. 输出修复方法。确定性检查失败时，应告知下一个 Agent 哪条命令或哪个文件可以修复偏差。

工作流

1. 梳理启发式规则。

   • 我们学到了什么？
   • 它能避免哪些反复出现的错误或偏差？
   • 哪些内容足够稳定，可以强制执行？
   • 哪些内容仍带有主观性？

2. 选择能够可靠强制执行稳定不变量，同时让无关选择保持开放的最小机制。

   • 验证器：用于判断结构是否符合要求。
   • 规范化器：用于生成规范表示。
   • 生成器：用于可重复地创建内容。
   • 测试样例：用于回归验证。
   • 清单：用于提供共享的事实来源。
   • CI 或钩子适配器：用于确定强制执行的时机。

3. 优先复用，再考虑构建。

   • 检查仓库现有的格式化工具、检查器、架构或生成器是否能处理该不变量。
   • 如果现有工具足够，就配置或扩展它；只为缺失的行为编写代码。
   • 保持新增代码可移植，并避免隐藏的全局状态。
   • 在输出约定允许的情况下，让生成器和规范化器保持幂等。

4. 提供验证依据。

   • 根据风险和产物选择检查项；使用现有测试或添加针对性测试样例。
   • 证明该不变量检查通过，并能检测到相关违规情况。
   • 对写入类工具检查重复运行的结果；若声称兼容 macOS/Ubuntu，也要进行相应检查。

5. 如果强制执行时机在范围内，就接入适配器。

   • 停止钩子、Git 钩子和 GitHub Actions 应调用同一个核心命令。
   • 让适配器文件保持精简，避免行为因环境而分化。

确定性阶梯

使用此阶梯，避免过度承诺：

1. 结构性：文件存在、JSON 架构匹配、README 代码块存在。
2. 规范性：键排序、PNG 规范化、代码格式化、元数据剥离。
3. 行为性：测试样例输入产生预期输出或退出代码。
4. 环境性：使用前检测依赖版本和功能标志。
5. 外部性：在固定对规范敏感的规则之前，使用权威证据确立受支持的约定；需要保持信息最新时，检查实时来源。
6. 主观性：仅使用示例和评审标准；除非评判标准变得可衡量，否则不应导致硬性失败。

辅助工具

使用 scripts/classify_conversion.py 进行快速、确定性的初步判断：

python3 scripts/classify_conversion.py "README cards must be below install commands and hooks should block drift"

该分类器有意保持简单。应将其视为规划辅助工具，而非所选产物已足够的证明。

指引不再适用时

如果拟议的不变量与仓库行为或当前工具约定冲突，请先检查已安装的工具和与其版本匹配的官方来源，再将其写入规则。不要把过时的变通方案固定到验证器中。请提出规范技能修正，并附上失效的建议、来源/版本和能区分情况的测试样例；不要擅自更新已安装的副本，也不要声称已验证无法获取的证据。

参考指南

需求	阅读
产物模式及各自的适用场景	references/conversion-patterns.md
验证深度、测试样例、CI、钩子和退出代码	references/verification.md
确定性检查变得脆弱的常见原因	references/gotchas.md

易错点

1. 不要把变通方案当作事实。如果某种行为取决于工具版本，请检查版本或探测该功能。
2. 可以确定性地约束生成的资源，而不必让其创作内容也变得确定。验证尺寸、格式、提示词文件偏差、大小和位置。
3. 避免重复实现强制逻辑。钩子、CI 和本地命令应调用同一个脚本。
4. 仅检查当前脏工作树的验证器，在 CI 中仍可能因文件未跟踪或被全局忽略而失败。打包事项相关时，应加入 Git 可见性检查。
5. 没有修复命令的严格检查会促使 Agent 绕过检查。让失败信息具有可操作性。