decision-layering

决策分层：新规则该落哪一层

一条新约束，先判断它该落到哪一层（或哪几层组合）。AI 让结构性退化加速（一下午能改几十个文件），所以判断、检测、解释三件事要分层并存。

先查已有规则

别急着新建规则。先交叉检查：

• 入口规则文件：CLAUDE.md / AGENTS.md / README 等
• ADR：是否已有决策、被拒绝方案、Superseded 记录
• 模块文档：业务不变量、状态机、边界说明
• 测试：是否已有架构测试、回归测试、命名约定
• hook / CI：是否已有守门机制

已有规则没被看见 → 优先改善可发现性或引用路径；规则不存在 → 再按决策树分层。老项目没有 ADR / spec 时，先把事实依据列出来（调用方、数据结构、兼容行为、线上约束），不要把猜测直接固化成规则。

三层

┌─ Constraints 约束 — 告诉 AI 不能做什么 / 边界在哪
│   项目入口规则文件（CLAUDE.md 等）/ 主题约束文档 / 模块边界 / ADR
├─ Conformance 合规 — 检查产出违反了哪条约束
│   编辑期 hook（即时反馈）/ CI 测试（包边界、命名、分层、文件扫描）
└─ Knowledge 知识 — 把"为什么"喂回给 AI
    ADR（代码读不出的决定 + 拒绝原因）/ 模块文档（业务规则、状态机、取舍）/ 代码注释

决策树

新规则 / 约束
├─ 是"决定 / 取舍"（选了 X 不选 Y）？
│   → ADR（必，见下方"建 ADR 前先探测"）+ 视影响面在入口规则 / 模块文档引用一句
├─ 是"语法 / 结构 / 字符串模式"（正则或 AST 可表达）？
│   ├─ 想编辑瞬间反馈 → 编辑期 hook
│   │   ├─ fail-open（非阻塞，报 stderr 给 AI 自判）← 默认
│   │   └─ fail-close（阻塞）← 仅当误报率 <0.1% 且违反代价极高
│   ├─ CI 要兜底（绕过 hook 的路径也得拦）→ 架构测试 / 文件扫描
│   └─ 两者通常并存：hook 快、CI 全
├─ 是"语义 / 跨模块 / 业务不变量"（正则讲不清）？
│   → ADR + 模块文档 + 代码注释（让 AI 看见 why）+ 针对性测试
│   → 对外行为 / 跨模块接口若绑定租户、权限、状态、数据归属、幂等键、外部系统契约等，
│     先写清语义边界和拒绝原因；能机械识别的路径再进 hook / CI
└─ 是"操作流程 / 工作步骤"？
    → skill（用 writing-skills 起步）

决策矩阵：违反代价 × 检测难度

代价 \ 检测	正则可表达	仅 AST	仅文档可解释
高（产线事故 / 数据丢失 / 安全）	hook + CI + ADR	架构测试 + ADR	ADR + 强文档 + 针对性测试
中（逻辑 bug / 维护成本）	hook 或 CI + ADR	架构测试 + ADR	ADR + 模块文档
低（风格 / 命名 / 提示）	hook 即可	不值得加测试	一句文档或代码注释

即便高代价规则也尽量避免阻塞式 hook（误报会卡住 AI 主流程），用 fail-open + 强 CI 兜底替代。

建 ADR / 加 hook 前——先探测基建

这套理念落到任意项目，不能假设人家已有 ADR 体系或 hook 架构：

• 要建 ADR 时：先看项目有没有 ADR 目录（docs/adr/ / doc/adr/ / adr/ 等）。
  • 没有 → 先问用户："这项目还没有 ADR 体系，要不要建立（一个 ADR 目录 + README 索引 + 0001 起始记录 + 编号模板）？" 同意再建，之后按统一格式加。
  • 有 → 直接按现有编号和格式加，别另起一套。
• 要加 hook / 自动守门时：先看有没有 hook 架构（.claude/hooks/ 或项目既有的 hook 配置）。
  • 没有 → 先问"要不要引入 hook 守门机制"，讲清 fail-open 默认。同意再建。
  • 有 → 跟随现有约定加（同样的非阻塞/反馈风格）。

不要这么搞

• ❌ prompt 式 AI hook 当默认：只在"正则/AST 查不出 + 文档讲不清 + 高频违反"三条同时满足时才考虑，否则误报噪音拖慢 AI。
• ❌ 硬规则只写文档：纯文档约 80% 跟随率，配 hook + CI 才接近 100%。硬规则必须配 enforcement。
• ❌ 入口规则文件写 step-by-step 操作：操作类内容进 skill。
• ❌ 文档重复代码已表达的内容：判断标准见 doc-or-not。
• ❌ 改已生效 ADR 的决策内容：被取代时新建一篇、把老的 Status 标 Superseded，决策内容不动。
• ❌ 阻塞式 hook 当默认：误报卡 AI。
• ❌ skill 泛滥：触发词太少或长期没被触发的 skill 该合并 / 删。

落每条新约束时自问 6 问

1. 它住在哪层？（按决策树）
2. 怎么 enforce？（hook / CI / 还是只靠 review）
3. AI 在哪看到它？（入口规则 / 模块文档 / ADR / 代码注释 / skill 描述）
4. 失败模式？（违反时报错够不够明确；fail-open 还是 fail-close）
5. 关联哪条 ADR？（没 ADR 的硬约束不稳）
6. 它是机械可检，还是语义不变量？（机械可检才进 hook / CI；语义不变量先落 ADR / 模块文档 / 测试）

何时跳过这套

bug 修复 / 在既定约定内的功能实现 / 原型实验 / 临时脚本 / 只影响单个模块的内部规则（直接改那篇文档）/ 紧急修复（先修事后补）。判断标准：这条约束 6 个月后还在吗？在 → 走分层；否 → 跳过。