跳至主要內容

08 · 约束执行 · 落地方案

钝悟2026/10/23大约 22 分钟

08 · 约束执行 · 落地方案

对应蓝图 §9。本文解决：如何确保 AI 在知识约束范围内行动？

状态：草案（C2.3 / C2.4 / C3.2 / C4.3 / C5.3 / C6.1 待确认）

前置依赖：05-知识检索与引用（MCP Server 是知识检索的唯一入口）· 03-知识审核（CODEOWNERS）

关联文档：02-知识验证（CI 校验）· 06-知识维护与治理（影响分析三源融合）· 07-评测与反馈闭环（工程基线与 AI 输出快照 Hook）

1. 定位与边界

约束执行是知识库的"执法系统"：它把 01–07 定义的规则从"建议"升级为"强制"。

与 02 的分工：02 在 MR 合并前校验知识本身的格式与引用（针对知识产物），本文校验 AI 生成内容是否符合知识库约束（针对 AI 输出）。

与 05 的分工：05 通过 MCP Server 提供知识检索接口，本文通过 Qoder Hook 在 AI 调用知识时强制走接口、强制带引用、强制过权限。

2. 核心设计决策

2.1 三层控制框架

蓝图 §9.1.1 定义指导、执行、裁决三层控制：

蓝图 §9.1.1 只定义了三层的划分与 Hook 形态对比；下表的**「强制程度」与「失败成本」两列、以及「层层兜底」原则均为本文补充（工程推导）**，不是蓝图结论，也不是外部标准。

层次载体强制程度失败成本
指导层AGENTS.md / Skill / 知识条目注入可靠性高、遵循可靠性低（见下注）低（生成错误可被下游拦截）
执行层Qoder Hook / 工具权限 / 人工确认中（阻断即时操作）中（打断工作流）
裁决层CI / 静态分析 / 测试 / CODEOWNERS强（阻断合并）高（返工）

设计原则：能在裁决层拦截的，不依赖执行层；能在执行层拦截的，不依赖指导层。层层兜底，但成本递增。

指导层的「弱」必须拆成两个维度，否则会与 05 §10.2 的分流判据直接冲突（后者认为「每次交互都必须遵守且违反后果严重」的内容应进 AGENTS.md，理由是「检索有失败概率，常驻才能保证 100% 生效」）：

  • 注入可靠性 = 高：常驻上下文一定被模型看到，不像检索有召回失败概率。
  • 遵循可靠性 = 低：看到不等于照做，仍依赖模型自觉，无法阻断。

两处结论并不矛盾——AGENTS.md 的价值在「一定被看到」，不在「一定被遵守」。原文只写「弱（依赖 AI 遵循）」会让读者误判为 AGENTS.md 无用，从而把本该常驻的硬约束放进检索路径。

2.2 Qoder Hook 形态差异

蓝图 §9.1.1 明确 Qoder Hook 分 CLI 与 IDE 两种形态，能力不同，落地前必须区分：

能力Qoder CLI（cli/hooks-reference）Qoder IDE 扩展（extensions/hooks）
Hook 类型command / http / prompt / agent仅 command / http
FileChanged 事件支持不支持
WorktreeCreate / WorktreeRemove支持不支持
阻断方式command 退出码 2（stderr 回灌模型）；prompt / agent 返回阻断决策command 退出码 2

关键结论（已更正）：原表述称「Worktree 隔离与基于文件变更的知识漂移触发只在 CLI 形态可用」，两处因果都不成立：

能力真实依赖形态差异
Worktree 隔离裸 git worktree 命令（见 §3.4），与 Hook 事件无关任何形态都可用。WorktreeCreate / WorktreeRemove 事件只提供生命周期自动化（自动创建/清理、自动注入 .agent-context.yaml），不提供隔离能力本身
基于文件变更的知识漂移触发06 §3.2 的 Git Diff（CI 侧）+ 06 §3.3 的定时任务与形态无关，两者都在 CI 侧运行。CLI 的 FileChanged 事件只是「本地即时提醒」的可选增强

因此 IDE 形态不需要把这两条降级为 CI 侧实现——它们本来就在 CI 侧。IDE 形态真正缺失的是「Worktree 生命周期自动化」与「本地即时文件变更提醒」，须由编排脚本显式承担创建与清理。

IDE 侧共 12 个事件，完整清单（原文只列了 8 个名称却断言 12 个，会误导实施者以为只需处理列出的部分）：

SessionStart、UserPromptSubmit、PreToolUse、PermissionRequest、PostToolUse、PostToolUseFailure、SubagentStart、SubagentStop、Stop、SessionEnd、PreCompact、Notification。

其中与本方案相关的为 4 个：PreToolUse（写入集校验）、PostToolUse（乐观锁校验 + AI 输出快照）、UserPromptSubmit（知识路由）、SessionStart（常驻上下文加载）。

上表能力对比与事件清单核对自 docs.qoder.com/cli/hooks-reference 与 docs.qoder.com/extensions/hooks，核对日期 2026-10。实施前须按企业实际部署版本复核：Hook 的事件名、类型集合与阻断协议都属产品能力，会随版本变化。

2.3 高价值规范编译为四件套

蓝图 §9.1.2 定义知识条目的四件套结构：

示例：

规范：Controller 不得直接依赖 DAO
知识：解释分层原因（docs/knowledge/arch/controller-dao-separation.md）
规则：ArchUnit 测试（test/ArchControllerDaoTest.java）
反例：Controller → DAO，测试失败（ArchControllerDaoTest#controllerMustNotDependOnDao）
Owner：backend-architecture（CODEOWNERS 声明）

反例引用必须用符号级（类名#方法名），不得用行号——蓝图 §7.4 明确「行号在源文件任何一次编辑后都会失效」。原示例写的是 #L25，恰好示范了被禁止的做法。

四件套的强制程度：

组件是否必须校验方式载体状态
知识条目必须02 §4.1 CI 校验 frontmatter（Error 级）✅ 已有
机器规则高价值规范必须（判定标准见 §3.2）CI 运行规则测试❌ 02 §4.1 的 8 项检查中没有「运行机器规则测试」这一项，须在 02 补检查项或在本文给出独立 Job（见下）
正反例测试有机器规则时必须（正例与反例各 ≥ 1 个）CI 运行正反例❌ 同上
Owner必须03 §3.2 CODEOWNERS 声明✅ 已有

原表的自相矛盾已修正：原文写「机器规则：高价值规范必须」+「正反例测试：必须」。但正反例的作用是证明规则的行为，非高价值条目根本没有规则可测，「正反例必须」无法成立；反之若要求所有条目都有正反例，就等于要求所有条目都有机器规则，与前一行矛盾。修正为条件式：有机器规则则正反例必须；无机器规则的知识条目以「适用范围 + 反例说明」段落替代，由 02 §4.1 的内容完整性检查（Warning 级）覆盖。

「必须」需要执行载体。02 §4.1 的检查项是格式 / 源文件 / 符号 / 结构 / 重复 / 冲突 / 可操作性 / 状态门禁，不包含规则测试与正反例执行，本文也没有给出对应 Job。缺载体时「必须」只是口头承诺。补齐方式：

# .gitlab-ci.yml（片段）
knowledge-rule-tests:
  stage: test
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
      changes:
        - docs/knowledge/**/*
        - .semgrep.yml
        - "**/test/Arch*Test.java"
  script:
    # 1. 从变更的知识条目反查其声明的机器规则（frontmatter required_tests）
    # 2. 执行对应规则测试，正例须通过、反例须失败
    - python3 scripts/knowledge-lint.py --check-rule-coverage   # 声明了规则的条目必须有正反例
    - mvn -q -Dtest='Arch*Test' test
    - semgrep --config .semgrep.yml --error

--check-rule-coverage 是待新建脚本，须与 02 §4.1 的检查项一并登记。

2.4 Impact Manifest

蓝图 §9.1.3 要求接口和 DDL 变更提交 MR 前必须生成 Impact Manifest 并随 MR 提交：

时序更正：原文写「修改前必须生成」，但 base_commit 与 changed_assets 只能在变更存在后产生，§3.3 的流程也明确是「先改再检测（Git diff）」——两处自相矛盾。正确表述是「提交 MR 前必须生成」，即生成时机在开发完成之后、合并之前。

base_commit:              # 基准 commit SHA
knowledge_revision:       # 知识版本（source_revision）
changed_assets:           # 变更资产清单
  - type: api
    path: api/order/v1/createOrder.yaml
  - type: ddl
    path: db/migration/V20261022__add_order_table.sql
affected_services:        # 受影响服务
  - order-service
  - payment-service
affected_consumers:       # 受影响调用方
  - web-frontend
  - mobile-app
compatibility_risks:      # 兼容性风险
  - type: breaking
    description: 新增必填字段 userId
    migration: 调用方需升级至 v2.1.0
migration_risks:          # 迁移风险
  - type: data
    description: 历史订单需回填 userId
    rollback: 支持回滚至 v2.0.0
required_tests:           # 必须执行的测试
  - contract-test
  - integration-test
required_approvers:       # 必须审批的角色
  - order-service-owner
  - payment-service-owner
rollback_plan:            # 回滚方案
  type: blue-green
  description: 保留 v2.0.0 路由，可随时切回

Impact Manifest 是合并的前置条件，但不能替代静态分析和测试。它只解决"变更影响是否被识别"，不解决"变更是否正确实现"。

「前置条件」必须有强制机制，否则等于靠人自觉：

要素规定
SchemaManifest 须有 JSON Schema，compatibility_risks[].type / migration_risks[].type / rollback_plan.type 用枚举而非自由文本
校验 JobMR pipeline 中的 Error 级 Job：必填字段齐全、枚举值合法、required_approvers 与 CODEOWNERS 派生结果一致
存放位置随 MR 提交，路径 docs/impact/{branch}.yaml，合并后归档；必须版本化，否则事后无法追溯当时的影响判断
分期实现P1 阶段 affected_services / affected_consumers 由人工填写 + CODEOWNERS 派生；P3 关系图谱（06 §3.4）上线后改为自动填充。原文未写这一分期，而 09 §3.4 把关系图谱排在 P3、Manifest 排在 P1，属依赖倒置——不标注分期，实施者会以为 P1 就能自动填充

2.5 Worktree 隔离

蓝图 §9.1.4 定义多 Agent 并发场景下的隔离机制：

六条约束：

  1. 每个 Agent 使用独立 Worktree 和 Branch。
  2. 记录基础 Commit 和知识版本（base_commit + knowledge_revision）。
  3. 声明读取集和写入集（哪些文件可读、哪些可写）。
  4. 公共契约采用单写者或显式串行化（避免并发修改 openapi.yaml）。
  5. 知识更新使用 expected_revision 乐观锁（避免覆盖他人更新）。
  6. 合并前统一 Rebase、冲突检测和全量测试。

六条约束的执行机制（原文六条全部只有要求、没有载体）：

#约束机制载体触发条件失败处置责任人
1独立 Worktree 和 Branch编排脚本 git worktree add（§3.4）Agent 任务启动创建失败则不启动任务（不得回落到共享目录）平台组
2记录 base_commit + 条目级 revision.agent-context.yamlWorktree 创建后文件缺失则 PreToolUse 阻断全部写入编排脚本
3声明读取集和写入集.agent-context.yaml 的 writable_paths / readable_paths + PreToolUse Hook每次写入操作越界写入 → 退出码 2 阻断。根治须 OS 级只读挂载（见 §3.1）编排脚本
4公共契约单写者或显式串行化待决策（C6.1）：单写者选举 / 租约 / 文件级锁三者均未设计并发修改 openapi.yaml 等契约文件当前无检测手段，只能靠 §3.4 第 4 步 rebase 时发现冲突平台组
5expected_revision 乐观锁knowledge-update-with-lock.py（§3.4 第 3 步）知识条目更新冲突 → 退出码 2 + stderr 说明，不自动合并Agent
6合并前 Rebase + 冲突检测 + 全量测试§3.4 第 4 步提交 MR 前Rebase 冲突由发起该任务的 Agent 所属团队解决；解不了则关闭 MR 并记录原因，不得强推任务发起团队

约束 4 是本节最大的空白：「单写者或显式串行化」既没有说明单写者如何选举、租约如何实现，也没有冲突检测手段。在 P0/P1 阶段 Agent 并发量低时可暂缓，但必须在 C6.1 中显式登记为待决策，不能以「已写入约束清单」当作已实现。

关键约束：不允许多个 Agent 并发覆盖同一工作目录。该约束只能由编排脚本（约束 1）保证，CI 侧只能事后发现。

CLI vs IDE 形态差异（已更正，见 §2.2）：隔离能力本身与 Hook 形态无关，由编排脚本用 git worktree 实现，两种形态都可用。差异只在生命周期自动化：CLI 形态可用 WorktreeCreate / WorktreeRemove 事件自动注入 .agent-context.yaml 与自动清理；IDE 形态须由编排脚本或 CI 显式承担这两件事。

CI 侧只能做冲突检测，不具备预防能力：CI 在 push 之后运行，只能发现多个 Agent 覆盖了同一目录，无法阻止。因此「不允许多个 Agent 并发覆盖同一工作目录」这条关键约束只能在编排脚本层实现，CI 是兜底而非替代。

3. 实施细节

3.1 Qoder Hook 配置示例

配置位置与格式（已更正）：CLI 与 IDE 两种形态的 Hook 都配置在 settings.json 的 hooks 键下，为 JSON 结构——以事件名为键，用 matcher 匹配工具名，真正的执行体嵌在内层 hooks 数组中并带 type 字段。原文写的独立 YAML 文件 .qoder/hooks/knowledge-constraints.yaml 与 event: / tool: / command: 三字段结构在两种形态下都不成立，照抄会得到「配置无效、Hook 静默不触发」——而静默失效恰好是最危险的失败模式：所有约束看起来都存在，实际全部落空。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write|NotebookEdit|Bash",
        "hooks": [
          { "type": "command", "command": "python3 scripts/hook-check-knowledge-writable.py" }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write|NotebookEdit|Bash",
        "hooks": [
          { "type": "command", "command": "python3 scripts/hook-check-knowledge-revision.py" },
          { "type": "command", "command": "python3 scripts/hook-snapshot-ai-output.py" }
        ]
      }
    ],
    "UserPromptSubmit": [
      {
        "hooks": [
          { "type": "command", "command": "python3 scripts/hook-check-knowledge-routing.py" }
        ]
      }
    ],
    "SessionStart": [
      {
        "hooks": [
          { "type": "command", "command": "python3 scripts/hook-load-knowledge-context.py" }
        ]
      }
    ]
  }
}
Hook事件matcher作用
hook-check-knowledge-writable.pyPreToolUseEdit / Write / NotebookEdit / Bash检查目标文件是否在 Agent 的写入集内
hook-check-knowledge-revision.pyPostToolUse同上检查知识更新是否使用 expected_revision 乐观锁
hook-snapshot-ai-output.pyPostToolUse同上新增：落盘 AI 原始输出快照，是 07 §2.4.1「人工重写比例」的唯一数据源
hook-check-knowledge-routing.pyUserPromptSubmit—检查 prompt 是否触发知识路由（分流判据见 05 §10.2）
hook-load-knowledge-context.pySessionStart—加载常驻上下文，范围严格受限，见下

写入集校验的 matcher 必须覆盖全部可变工具。原文只对 Edit 做前置校验，任何其它写入路径（Write、NotebookEdit、Bash 里的 sed -i / > 重定向 / git apply / 脚本生成文件）都不经过该 matcher → §2.5 约束 3「声明读取集和写入集」形同装饰，且与 §2.1「能在执行层拦截的不依赖指导层」的自我要求矛盾。对 Bash 仅靠工具名匹配仍不够（命令内容任意），根治方式是 OS 级隔离：Worktree 文件系统只读挂载 + 白名单路径可写，而不是依赖工具名枚举。

SessionStart 预加载必须严格限定范围。原文写「加载 AGENTS.md / Skill / 相关知识条目到会话上下文」，这构成一条具体的越权与不可追溯路径：由本地脚本在会话启动时直接把知识条目塞进上下文，不经过 MCP Server，因此既不按 classification / ACL 过滤（违反 05 §9.1 的三条硬性要求），也不产生 trace_id / retrieved_chunks 审计记录（违反 05 §9.3），与 09 §3.1 把「检索前密级过滤」「全链路审计」列为 P0 硬门禁直接冲突；同时也违反 05 §10.2 的分流判据与蓝图 §6.3 的渐进式加载原则。修正为：

  • SessionStart 只加载 AGENTS.md 与 _index.yaml（L0 路由地图），且 _index.yaml 须限定为 classification: public 的部分。
  • 知识条目一律通过 MCP search_knowledge 按需获取，走同一权限过滤与审计链路。
  • 若确有预加载需求，必须改为调用 MCP Server（而非本地读文件），并记录 trace_id。

Hook 的失败与性能策略（原文完全缺失，按 Fail-Closed 原则必须显式规定）：

情形行为
脚本抛异常 / 返回非 0 非 2 的退出码Fail-Closed：视为阻断（退出码 2），不得静默放行。依据：05 §9.2 映射的 OWASP 第 14 类 Fail-Closed Design
脚本超时设上限（待实测）；超时按 Fail-Closed 处理并告警
幂等性所有 Hook 必须幂等——PostToolUse 会被重复触发
延迟影响PreToolUse 挂在每次编辑上，脚本必须只做本地判定（读 .agent-context.yaml + 路径匹配），不得调网络
依赖与可移植性示例用 python3，Windows 环境须确认命令名（可能是 python 或 py）；脚本存放位置须在仓库内固定路径
生效自检SessionStart 打点 + CI 校验配置可加载（settings.json 能被解析、command 路径存在）。没有自检就无法区分「AI 行为变好」与「Hook 已失效」，§4 的「Hook 拦截率趋势下降」因此不可解释

3.2 高价值规范编译流程

高价值规范的判定标准（满足任一即纳入）：

类别判定标准示例
架构约束违反会导致系统不可用或数据丢失Controller 不得直接依赖 DAO
安全约束违反会导致安全漏洞用户输入不得拼接 SQL
性能约束可静态判定的结构性反模式（原文「性能劣化 > 50%」不可判定：未定义基线、负载与测量方，且示例与该阈值无关）循环体内出现 JDBC / ORM 调用（N+1 查询）；循环内远程调用
合规约束违反会导致合规风险敏感数据不得明文日志

3.3 Impact Manifest 生成流程

两处更正：

  1. 契约测试必须在合并前执行。原文写「合并后触发契约测试」，但 §2.1 明确裁决层的价值是阻断合并——合并后才跑的测试无法阻断任何事，只能事后告警，required_tests 字段因此没有强制力。改为：合并前作为 Error 级门禁，合并后再跑一次作为回归确认，两者职责分开。
  2. 审批被拒应回到「开发者修改变更」而不是「生成草稿」。原图 A9 -->|拒绝| A4 会让开发者重新生成一份 Manifest 草稿，但审批被拒的原因通常是变更本身有问题（影响面判断错误、迁移方案不可行），须回到 A1 修改变更。

3.4 Worktree 隔离实施

# 1. 创建 Worktree
git worktree add ../agent-worktree-1 -b feature/agent-1-task
cd ../agent-worktree-1

# 2. 记录基线
cat > .agent-context.yaml <<EOF
base_commit: $(git rev-parse HEAD)
# 注意：不要写 knowledge_revision: $(git log -1 --format=%H -- docs/knowledge/)
# 那是「整个知识目录的最近一次提交」，任何 Agent 提交任何一条知识都会改变它，
# 用它做乐观锁会导致：(a) 与 K001 无关的变更让 K001 假冲突；
# (b) 无法区分「别人改了 K001」和「别人改了 K002」。
# 乐观锁必须是条目级：取该条目自身的 source_revision（或其文件的 blob hash）。
agent_id: agent-1
writable_paths:
  - src/main/java/com/example/order/
  - docs/knowledge/order/
readable_paths:
  - src/main/java/com/example/**
  - docs/knowledge/**
EOF

# 3. 知识更新乐观锁（条目级）
python3 scripts/knowledge-update-with-lock.py \
  --knowledge-id K001 \
  --expected-revision "$(python3 scripts/knowledge-get-revision.py --knowledge-id K001)" \
  --new-content "..."
# --expected-revision 取该条目自身的 source_revision（蓝图 §5.2 / §7.1 用的就是条目级），
# 比较对象为该条目文件的 git blob hash。
# 冲突时的输出协议：退出码 2 + stderr 写明「K001 已被 {commit} 修改，当前基线 {rev}」，
# 由 Agent 决定重读后重试还是放弃；不得自动合并（C5.3 已定 A）。

# 4. 合并前 Rebase
git fetch origin
git rebase origin/main
python3 scripts/worktree-conflict-check.py

# 5. 清理 Worktree
cd ../main-repo
git worktree remove ../agent-worktree-1

4. 度量指标

指标计算方式目标性质
一次 CI 通过率AI 代码首次通过确定性门禁的比例≥ 80%阈值待实测
返工率AI 结果被人工大幅修改的比例≤ 15%阈值待实测（口径见 07 §2.4.1：行级 diff + 归一化编辑距离 > 30%；原文指向 07 §2.4.1 属错误引用，该节是金标集标注流程，未定义返工口径）
Hook 配置加载成功率可成功解析且 command 路径存在的 Hook 数 / 声明的 Hook 数= 100%机制保证（CI 校验 settings.json，见 §3.1 生效自检）
Hook 执行成功率正常返回（含退出码 2）的执行数 / 总执行数= 100%机制保证（异常与超时按 Fail-Closed 计入失败并告警）
Hook 拦截率被 Qoder Hook 阻断的操作 / 总操作数趋势下降趋势指标，且单独不可解释：下降有两种成因——AI 行为变好，或 Hook 被禁用/失效（§3.1 的静默失效风险）。必须与上两行护栏指标联立判读：只有「拦截率下降 + 两个成功率 = 100%」才说明行为变好
影响分析覆盖率抽样审计：每季度抽 N 个已合并的 API/DDL 变更，人工核对 Manifest 与实际受影响资产的吻合率≥ 90%阈值待实测。原定义「识别到相关资产的比例」不可计算——分母「全部相关资产」需要人工真值，而真值来源未定义。改为抽样审计后须注明抽样方法（分层：按变更类型）与责任人（Steward）

5. 决策点清单

5.1 已确认决策

编号决策点选定方案依据
C1.1控制是否分层是，指导/执行/裁决三层蓝图 §9.1.1
C1.2三层是否层层兜底是，成本递增但强制程度递增本文自拟（工程推导）。蓝图 §9.1.1 只定义三层划分与 Hook 形态对比，没有「强制程度」「失败成本」两列，也没有「能在裁决层拦截的不依赖执行层」这条原则。原文标注为蓝图依据属挂名式引用（蓝图附录明令禁止）
C2.1Qoder Hook 是否区分 CLI 与 IDE 形态是，能力不同蓝图 §9.1.1
C2.2Worktree 隔离是否只在 CLI 形态可用否（原结论错误，已更正）：隔离由裸 git worktree 实现，与 Hook 形态无关；CLI 的 WorktreeCreate/Remove 只提供生命周期自动化本文 §2.2 / §3.4
C3.1高价值规范是否编译为四件套是，知识/规则/测试/Owner蓝图 §9.1.2
C4.1接口/DDL 修改前是否生成 Impact Manifest是，作为继续执行的前置条件蓝图 §9.1.3
C4.2Impact Manifest 是否替代静态分析和测试否，只解决影响识别蓝图 §9.1.3
C5.1多 Agent 并发是否使用 Worktree 隔离是，CLI 形态蓝图 §9.1.4
C5.2知识更新是否使用乐观锁是，expected_revision蓝图 §9.1.4

5.2 待确认决策

编号决策点候选方案建议
C2.3团队当前使用的是 CLI 还是 IDE 形态A. CLI / B. IDE / C. 混合需调研后确认
C2.4IDE 形态下 Worktree 生命周期的承担方A. 编排脚本级隔离（首选） / B. CI 侧冲突检测（兜底）A。原选项写「A. CI 侧实现，保留隔离能力」不成立——CI 在 push 之后运行，只能发现冲突，无法阻止并发覆盖同一工作目录，不具备预防能力。B 只能作为 A 的兜底，不得单独使用
C6.1公共契约的并发写入如何串行化A. 单写者选举 / B. 租约（lease）/ C. 文件级锁须在多 Agent 并发上线前决策。§2.5 约束 4 当前无任何机制载体
C3.2高价值规范的判定标准A. 架构/安全/性能/合规四类 / B. 增加成本类A，四类足够
C4.3Impact Manifest 的审批人是否自动添加A. 是，按 CODEOWNERS / B. 否，手动指定A，减少遗漏
C5.3Worktree 乐观锁冲突时的处理策略A. 拒绝并提示 / B. 自动合并A，避免数据丢失

6. 待实测项

  • 一次 CI 通过率的基线值
  • 返工率的「大幅修改」阈值（口径已在 07 §2.4.1 定义，阈值待实测）
  • Hook 拦截率的初始值
  • Hook 脚本的超时上限与对单次编辑的延迟影响
  • 影响分析覆盖率的初始值与季度抽样量 N
  • 团队当前使用的 Qoder 形态（CLI / IDE / 混合）
  • 高价值规范判定的「性能约束」结构性反模式清单

7. 与其他文档的接口

接口方接口内容方向
02 知识验证CI 校验四件套（frontmatter / 源文件 / 符号 / 结构）作为裁决层实现02 → 本文
03 知识审核CODEOWNERS 作为 Owner 声明的机制载体03 → 本文
05 检索与引用MCP Server 作为知识检索的唯一入口（禁止直接读文件）05 → 本文
06 知识维护文件变更触发漂移检测在 CI 侧（06 §3.2 / §3.3），与 Hook 形态无关；Worktree 隔离由本文编排脚本承担06 ↔ 本文
07 评测与反馈一次 CI 通过率、返工率作为工程基线指标；本文 §3.1 须新增 hook-snapshot-ai-output.py，它是 07 §2.4.1 返工口径的唯一数据源07 ↔ 本文
09 度量与落地路径Impact Manifest 在 P1、关系图谱在 P3，affected_consumers 的自动填充分期见 §2.409 ← 本文
Copyright © 2026 钝悟