fix

Codex 兼容性说明：

• 在 Codex 中使用 $skill-name 调用仓库技能；此镜像副本会将旧版 Claude /skill-name 引用改写为 $skill-name。
• 任务跟踪要求：执行任何工作流或技能步骤之前，先为所有步骤创建／更新任务跟踪，并随着进度变化保持同步。
• 用户问题提示表示要在 Codex 中直接询问用户。
• 遇到 Claude 专属的模式切换说明时，请忽略。
• 严格执行约定：用户明确调用某项技能时，必须按原样执行该技能协议。
• 子 Agent 授权：用户调用或 AI 检测到某项技能，且其协议要求使用子 Agent 时，该技能的激活即授权为该任务调用所需的 spawn_agent 子 Agent。
• 除非用户事先明确批准偏离，否则不得跳过、重排或合并协议步骤。
• 对于工作流技能，必须明确执行每项列出的子技能步骤，并逐步报告证据。
• 如果在此环境中无法执行某项必需步骤／工具，请停止并先询问用户，再考虑调整做法。

Codex 项目参考资料加载（无钩子）

Codex 使用静态项目参考资料加载，而非运行时注入项目文档。 进行编码、规划、调试、测试或审查时，请按以下路由明确打开项目文档。

始终阅读：

• docs/project-config.json（项目特定路径、命令、模块以及工作流／测试设置）
• docs/project-reference/docs-index-reference.md（指向完整 docs/project-reference/* 目录的路由索引）
• docs/project-reference/lessons.md（始终适用的防护措施和反模式）

上下文缺失／过时时的处理方式： 如果缺少或过时的文件包括 docs/project-config.json、文档索引、lessons.md、CLAUDE.md、AGENTS.md，或任务所需的任何参考文档，请在进行常规项目工作前自动运行 $project-init，或运行范围更小的设置流程（$project-config、$docs-init、$scan-all、$scan --target=<key>、$claude-md-init）。如果 Codex 镜像或 AGENTS.md 缺失／过时，请要求用户运行 $sync-codex；不要自动运行。

按情境查阅文档：

• 项目结构／架构／技术栈／部署／设置（任意层：后端、前端或基础设施）：project-structure-reference.md
• 后端／CQRS／API／领域／实体变更：backend-patterns-reference.md、domain-entities-reference.md
• 前端／UI／样式／设计系统：frontend-patterns-reference.md、scss-styling-guide.md、design-system/README.md
• 编写规范、docs/specs/ 路径或 TC 格式：feature-spec-reference.md、spec-system-reference.md、spec-principles.md
• 行为／公共契约变更或规范－测试－代码同步：workflow-spec-test-code-cycle-reference.md 以及上述规范文档
• 衍生的规范索引／ERD／重新实现指南：spec-system-reference.md 以及 docs/specs/ 下的源 Feature Specs
• 集成测试的实现／审查：integration-test-reference.md
• E2E 测试的实现／审查：e2e-test-reference.md
• 代码审查／审计：code-review-rules.md，并根据变更文件查阅相应领域文档

不要不加选择地阅读所有文档。请从 docs-index-reference.md 开始，然后只打开相关文件。

[BLOCKING] 必须按声明的顺序执行技能步骤。未经用户明确批准，绝不得跳过、重排或合并步骤。 [BLOCKING] 每个步骤或子技能调用之前都必须更新任务跟踪：开始时标记为 in_progress，结束时标记为 completed。 [BLOCKING] 每个已完成／跳过的步骤都必须提供证据或明确的跳过理由。 [BLOCKING] 如果无法使用任务工具，请维护具有相同状态转换的等效逐步计划跟踪。

快速摘要

目标： 通过并行子 Agent 调查消除问题的根本原因——从终点向起点追溯，并提供 file:line 证据，在负责维护不变量的最低层修复（绝不在崩溃位置修复）——然后使用 $prove-fix 证明修复有效，彻底根治问题，而不只是解决症状。

摘要：

• 用途： 一个智能修复路由器，旨在根治问题而非解决症状——通过证据诊断根本原因，在负责维护不变量的最低层修复，使用 $prove-fix 证明修复有效，然后让规范、测试和代码保持同步。
• 先路由（--target=）： 使用 --target={ci|issue|logs|test|types|ui} 通过根本原因前置条件门，然后跳转到对应的独立内联分支（每个分支都会自行诊断并运行 $prove-fix）；不带标志 = 执行完整的诊断→修复主流程。— 原因：分支不得重新运行独立主流程的 §1/§2，但任何分支都不能免于追溯根本原因。
• 主要步骤（不带标志的主流程）： 根本原因前置条件门 → 侦察（并行子 Agent）→ 从终点向起点诊断根本原因（debug-investigate、file:line 证据、假设矩阵、正向收敛证明）→ 置信度与证据门 → 制定含影响分析的计划 → 🛑 修复前验证审批 → 在责任层实现修复 → $prove-fix → 有条件地进行 $spec 正确性检查 → $changes-review（生产代码）→ $why-review 最终签核。
• 根本原因前置条件门（阻断性，最先运行）： 直接调用 $fix 时——无标志主流程以及每个 --target= 分支——在 $debug-investigate 为本次会话中的这个问题找出根本原因之前，不得编辑代码；必须通过当前任务列表条目或书面调查报告证明（记忆不算证据；仅有父工作流条目也不能作为证明）。若未运行 → 先运行 $debug-investigate，然后从规划步骤继续。— 原因：否则第一次编辑时没有任何已追溯的原因，修复的只会是症状位置。
• 三个不可跳过的硬性门槛： 根本原因前置条件门（见上文）、置信度与证据门（声明 Confidence: X% 并提供 file:line，若低于 60% 则停止），以及 🛑 修复前验证审批（任何代码变更前，直接询问用户并呈现根本原因和计划——仅在工作流内部可跳过审批）。
• 先诊断，再打补丁： 从终点向起点追踪症状，直至负责维护不变量的层级；绝不在崩溃位置修复——崩溃位置只是症状，原因来自更低层。
• 模式与跳过规则： 默认采用 HARD 模式（完整严谨流程），除非同时满足全部 5 项简单错误豁免条件；独立执行（无父工作流）时，自行组装最小主流程 debug-investigate → fix + prove-fix → $spec correctness check → $changes-review (production code) → $why-review；在工作流内部时，整个契约都跳过——但根本原因前置条件门永不跳过：仍须提供证据，证明该流程确实针对这个问题运行了 debug-investigate。— 原因：独立执行时，没有其他流程负责提供诊断、规范同步或审查；工作流条目也不能证明其诊断步骤确实运行过。

工作流：

1. 侦察 — 使用侦察员/研究员子 Agent 并行探索问题
2. 诊断 — 通过代码路径追踪根本原因，并提供证据
3. 规划 — 制定包含影响分析的修复计划
4. 修复 — 实施并验证修复

关键规则：

• 根本原因前置条件门（阻断性）： 在 $debug-investigate 为本次会话中的这个问题完成追溯之前，不得编辑代码——依据证据，而非回忆
• 调试思维：每项论断都需要 file:line 证据
• 使用子 Agent 并行调查多个假设
• 实施复杂修复前，务必先制定计划
• 目标标志（参见目标路由）：--target={ci|issue|logs|test|types|ui} 会选择一个独立内联分支，将修复限定在对应领域。不带标志 = 执行下方完整的诊断→修复主流程。

默认模式策略

默认采用严格模式（完整严谨性）。 以下各部分均默认适用：并行侦察／研究子 Agent、通过 file:line 证据追溯根因、置信度与证据门槛、附带影响分析的修复计划，以及针对该 Bug 的保留测试。

仅当以下条件全部满足时，才可选择快速模式（Bug 确实很简单）：

• 错误消息已明确指出根因，且根因已定位（无需诊断）
• 仅需修改单个文件，改动不超过 10 行
• 不影响其他服务，也不更改契约
• 已有针对该 Bug 的测试，或者该 Bug 不影响功能（拼写错误、日志消息）
• 无需进一步调查，对修复的置信度达到 95% 以上

任何一项不满足 → 使用以下完整流程。 拿不准时，默认采用严格模式。对非简单 Bug 修复跳过诊断，只会修复症状，留下病因。

快速模式仅跳过以下事项： 并行子 Agent 调查（改为直接读取／搜索）、单独的修复计划（改为直接说明修改）、编写回归测试（仅限已有测试覆盖该问题的情况）。置信度与证据门槛、行为差异矩阵，以及运行现有测试套件均不会跳过。

🛑 根因前置条件门槛（直接调用 $fix）——阻断性

[BLOCKING] $fix 在 $debug-investigate 于本次会话中找出此问题的根本原因之前，绝不能编辑代码。 此关卡会在下方的独立模式最低契约之前、任何 --target= 分支主体之前，以及 🛑 修复前验证审批之前执行。——原因：若直接调用 $fix，它可能在完全没有追溯根本原因的情况下进行首次编辑，从而修补症状所在之处，却让病因继续存在。

1. 触发条件——所有直接调用 $fix 的情况。 用户输入的斜杠命令或模型选择的技能；每个 --target={ci|issue|logs|test|types|ui} 分支，以及无标志参数的主流程，均适用。--target= 分支不会重新执行下方契约的 §1/§2，但仍须通过此关卡。——原因：分支自身的 debugger/tester 子 Agent 步骤不构成从结果到起因的完整追溯，因此限定运行范围并不能免除追溯要求。

2. 检查——依据证据，绝不依赖记忆。 在首次编辑代码之前，确认 $debug-investigate 是否已在本次会话中针对同一问题运行。仅接受以下证据：

• 当前任务列表中针对该症状的 debug-investigate（或其阶段任务）条目，或
• 一份明确写出该症状的调查报告（例如 .ai/workspace/analysis/{issue-name}.analysis.md、plans/reports/debug-investigate-*.md），其中包含从结果到起因的追溯过程。

没有此类证据 → 视为未运行。 想起“已经知道”原因，不算证据。——原因：上下文压缩后，模型仍可能相信自己已完成调查，但实际调查结果却已不复存在。

3. 执行。 尚未运行 → 先针对该问题运行 $debug-investigate，然后使用其根本原因报告，从规划步骤恢复 $fix 主流程。这也涵盖了主流程内部的第 1 步 debugger 子 Agent（与下方契约的 §1 规则相同）。——原因：如果技能已完成追溯，再次诊断会使主流程重复运行。

4. 同一问题判定。 针对其他症状运行过的 $debug-investigate 不满足此关卡要求。是否满足取决于问题本身，而非技能名称。当当前 <issues> 中列出的症状未包含在现有报告中时，关卡就会触发。——原因：否则，只要每个会话调查一次，就能为无限次未经追溯的修复开绿灯。

5. 跳过条件——明确、严格限定并记录。 记录适用的条件及其证明；绝不能静默跳过：

条件	是否跳过？
存在符合 §2 要求的同一问题证据 → 引用 file:line / 任务条目作为证明，然后继续	是
快速模式下的简单 bug（Default Mode Policy 的全部 5 项退出条件均满足）→ 可直接写出从结果到起因的追溯过程，不必启动该技能；但追溯本身仍然必须完成	部分跳过
活跃的父级工作流条目所列顺序中，已执行针对该问题的 debug-investigate → 引用已完成的步骤	是
仅有活跃的父级工作流条目，但没有针对该问题的已完成 debug-investigate 步骤	否

最后一行正是此关卡要堵住的漏洞。 下方契约仅凭存在父级工作流条目，就会将模式判定为独立模式（Detect mode，“独立模式最低契约”）。即使有条目，其顺序中 debug-investigate 步骤也可能从未运行、针对的是不同症状，或被跳过。此关卡在该判定基础上增加更严格的要求——必须证明已针对此问题执行调查；绝不会放宽要求。——原因：存在一个容器任务，并不能证明其中的工作已经完成。

在以下条件满足之前，保持阻塞： 已说明 §2 检查及其证据（或明确的跳过条目及其证明），并且已存在针对该问题的根本原因追溯。仅凭“原因显而易见”，绝不能继续规划或编辑。

独立模式最低契约（仅限非工作流）

$fix 通常是 workflow-bugfix 中的一个步骤——在该工作流中，流程（scout → investigate → debug-investigate → spec [mode=amend] → plan → … → fix → prove-fix → … → spec [mode=sync] → workflow-review-changes）会围绕修复提供诊断、规范同步和审查。**单独调用时，没有流程会提供这些。**单独运行 $fix 只会诊断并修补代码；它本身并不能保证根因已追溯到负责该不变量的层、docs/specs/ 下的 Feature Spec 仍与实际行为一致，或更改已经过审查。单独运行时，这一缺口会导致只修补症状，并造成规范／文档偏差。

范围：本契约适用于无标志的 $fix 主流程（完整的诊断→修复路径）。--target={ci|issue|logs|test|types|ui} 分支均可独立运行——每个分支都会自行诊断并运行 $prove-fix——因此不会在这里重新运行 §1/§2；单独运行时，它们只继承作为后续关卡的 **§3（规范正确性检查）**和 §4（why-review）（而 --target=issue 自带 $changes-review 关卡——参见该分支）。

检测模式：先调用当前任务列表（依据下方的嵌套任务展开契约）。存在活跃的父工作流任务行 → 跳过本节全文（工作流负责这些步骤；重复执行会导致主流程运行两次）——但上方的根因前置条件关卡仍然适用：要跳过本节，父流程中的 debug-investigate 步骤必须已针对_当前问题_完成，而不仅仅是存在该步骤。任务行存在但未运行该步骤 → 触发关卡并先运行 $debug-investigate。**不存在父任务行 → 单独运行：**首次编辑代码前，必须由 ATTENTION 自行组装以下最小错误修复主流程，并按顺序将其作为任务跟踪待办事项：

1. $debug-investigate——_先查根因；上方的根因前置条件关卡要求执行此步骤，其 §2 证据检查会判断它是否已针对当前问题运行。_从症状开始反向追踪到负责该不变量的层，并提供 file:line 证据（假设矩阵 + 前向收敛证明）。这_就是_单独运行时的诊断——它涵盖主流程内部第 1 步的 debugger 子 Agent；根据此报告从规划步骤继续主流程。快速模式下的简单错误（满足所有默认模式策略的退出条件）可以直接内联追踪，而不启动该技能，但仍必须从症状开始反向追踪。
2. 修复主流程——执行_本技能_下方的 plan → 🛑 approve → implement → $prove-fix`` 流程。修复前验证审批关卡和 $prove-fix 保持不变。
3. $spec 规范正确性检查——_有条件执行，确保规范文档不会过时。_根据已证实的根因，判断属于以下哪种情况：
   • 规范有误／已过时——规范描述的行为从未成立，或预期行为已更改但规范未更新。规范本身（或其一部分）就是缺陷 → 运行 $spec [mode=amend] 修正 §1-§7 规范，然后运行 $spec [mode=sync]，使 §8 TC-{FEATURE}-{NNN} 与集成测试保持一致。
   • 规范正确，只是代码未达到规范要求——纯代码缺陷；§1-§7 中描述的行为现在已重新符合规范。不修订 §1-§7。但仍需检查 §8 测试用例：如果该错误复现的场景／边缘情况未被任何现有 TC-{FEATURE}-{NNN} 覆盖（规范_正确但缺少该错误场景_），则通过 $spec [mode=tests] 添加回归测试用例，以便规范记录该场景；然后运行 $spec [mode=sync]，使 §8 与新增的回归测试保持一致。只有当现有 TC 已覆盖该场景时，才记录 Spec verified correct, bug case already in §8 — no spec change (code-only defect) 并提供 file:line 证据，然后继续。绝不能修复错误后，却让其场景缺失于规范的 §8。
   • 不存在适用的规范——该错误区域在 docs/specs/ 下没有 Feature Spec。提供 file:line 证据并记录 No governing spec — nothing to amend；如果该区域现在值得编写规范，则运行 $spec [mode=init]（然后运行 [mode=tests]，将该错误场景作为回归 TC 加入 §8），而不是只提出建议。必须明确判定所属情况——只能跳过修订，不能跳过判定；如果有规范适用于该区域，绝不能让错误场景未被记录。
4. $why-review——_审查理由，最后一项待办（在修复以及任何 $changes-review 之后）。_对已收敛的更改进行最终签核：根因归属正确、在负责该不变量的最低层进行修复（而非在崩溃位置修复）、没有只修补症状、已覆盖回归测试，并且 §3 的规范判定有充分依据。通过此步骤前，不得报告“已完成”。非功能性且无关紧要的修复（拼写错误、日志／注释文本；快速模式）可以内联／简要完成此步骤，而不启动完整技能——与 §1 对称。

生产代码修复还必须在 §4 之前添加 $changes-review 待办事项（全面代码审查，其已验证的修复可能会改变差异；随后由 §4 对结果进行签核）。$changes-review 的位置以及在工作流内部跳过该步骤的规则，由下方的通用单独运行审查关卡负责——请引用该关卡，不要重述要求。单独运行时待办事项的最终顺序：debug-investigate → [fix spine + prove-fix] → spec-check → changes-review (if production code) → why-review。

调试思维（不可妥协）

保持怀疑。运用批判性思维和顺序思维。每项判断都必须有可追溯的证据，置信度 >80% 才能采取行动。

• 采取行动前，先通过实际代码追踪验证每个假设——不要认定第一个假设就是正确的。原因：第一个猜测通常只是最先引起注意的陷阱，并非真正原因。
• 每项根因判断都必须附上 file:line 证据。
• 如果无法通过代码追踪证明根因，请说明“假设，尚未确认”。
• 质疑假设：“这真的是原因吗？”→ 追踪实际执行路径。
• 挑战完整性：“还有其他影响因素吗？”→ 检查相关代码路径。
• 没有证据就不要说“应该能修好”——验证修复确实针对已追踪到的根因。

⚠️ 强制：置信度与证据门槛

必须针对每项判断声明 Confidence: X%，并提供证据列表和 file:line 证明。 95% 及以上：可自由推荐 | 80–94%：附带注意事项 | 60–79%：列出未知项 | 低于 60%：停止——收集更多证据。

深入思考，规划并开始修复这些问题；遵循编排协议、核心职责、子 Agent 团队和开发规则： $ARGUMENTS

目标路由（--target=）

$fix 是一个智能路由器。不带标志时，它会运行下方完整的诊断→修复流程。传入 --target= 可将运行范围限定为独立的内联分支：

--target	行为
types	下方的内联分支——TypeScript / 类型错误处理。
ci	下方的内联分支——CI / 流水线故障排查。
issue	下方的内联分支——已跟踪的问题 / 工单处理。
logs	下方的内联分支——基于日志 / 堆栈跟踪的调试。
test	下方的内联分支——失败测试修复。
ui	下方的内联分支——UI / 视觉缺陷修复。

不带 --target（或使用无法识别的值）→ 运行下方完整的工作流流程；根据 <issues> 推断合适的专项分支。

以前是独立技能。 --target=ci|issue|logs|test|ui 以前分别对应独立技能 /fix-ci、/fix-issue、/fix-logs、/fix-test、/fix-ui；现在它们是 $fix 的内联分支（已合并——独立名称不再存在）。

--target=types — TypeScript / 类型错误分支

运行 tsc --noEmit（或 nx build / bun run typecheck / npx tsc）收集所有类型错误，然后：

1. 收集——记录每项类型错误及其 file:line。
2. 分类——按原因分组：缺少类型、签名错误、导入 / 导出问题。
3. 从根源修复——为每个值指定真实且具体的类型（或使用 unknown + 缩窄检查）。不要用 any 来绕过检查器——any 会让底层类型缺陷随代码发布。修复根因（接口错误、缺少导出），而不是只处理症状出现的位置。——原因：any 会绕过检查器，让类型缺陷随代码发布。
4. 重复执行，直到 tsc --noEmit 检查通过——类型错误为零。
5. **🛑 修复前验证：**直接询问用户，展示错误和根因，并在修改代码前获得批准（在工作流内时可跳过）。
6. 修复后运行 $prove-fix——为每项更改构建代码证明追踪，并给出置信度评分。绝不跳过。

调试思维、置信度与证据门槛，以及下方所有 SYNC 门槛均不变，适用于此分支。

--target=ci — CI / 流水线失败分支

目标： 分析 CI/CD 流水线日志，找出并修复已配置的 CI 提供商/工具中的构建或测试失败。

关键规则：

• **基础设施上下文：**读取 docs/project-config.json 中的 infrastructure.cicd.tool，确定 CI 提供商/工具（例如 azure-devops、github-actions、gitlab-ci）；针对该提供商的流水线配置文件进行处理。
• 专注于 CI 特有的问题（环境变量、Docker、依赖项、构建顺序）。
• 验证修复不会影响本地开发。

工作流：

1. 使用 debugger 子 Agent，通过已配置的 CI 工具/API（来自 docs/project-config.json）读取 CI 日志，从后往前分析最后出现的失败日志/错误，追溯根本原因，并反馈分析结果。将发现写入 .ai/workspace/analysis/{ci-issue}.analysis.md；实施前重新阅读。
2. 🛑 呈现根本原因和建议的修复方案 → 直接询问用户 → 等待批准。
3. 根据报告实施修复。
4. 使用 tester 子 Agent 进行验证；反馈结果。
5. 如果测试失败，从第 2 步重新开始。
6. 汇总变更并建议后续步骤。然后运行 $prove-fix。

**注意：**使用已配置 CI 提供商的 CLI/API。如果使用 GitHub Actions 且无法使用 gh，请先指导用户安装并授权 GitHub CLI。

以下调试思维、信心与证据关卡以及所有 SYNC 关卡均原样适用于此分支。

--target=issue — 已跟踪问题 / 工单分支

**目标：**调查并修复已作为已跟踪问题报告的错误（例如 GitHub issues），并确保全程可追溯。

**读取当前目标（根本原因分析之前）：**根据 SYNC:goal-contract-satisfaction-loop 确定当前生效的 Goal Contract（活动计划 goal.md → plans/goals/{YYMMDD-HHmm}-{slug}/goal.md → 根据问题创建）。将工单的验收标准映射到已保存的成功标准；修复后，将证明证据和剩余差距追加到迭代日志中。只要仍有任何必需标准未通过，就不得关闭问题。

关键规则：

• 将修复关联回问题，以确保可追溯。
• 验证修复能解决问题中给出的具体复现步骤。

工作流：

1. 激活 debug-investigate 技能并遵循其工作流 — 此步骤满足此问题的根本原因前置关卡要求；将其报告路径记录为该关卡的 §2 证据。完整指南请参阅 .claude/docs/AI-DEBUGGING-PROTOCOL.md。
2. 使用 .ai/workspace/analysis/issue-[number].analysis.md 保存结构化分析。提出任何修复方案前，重新阅读整个分析文件。
3. 🛑 呈现根本原因和建议的修复方案 → 直接询问用户 → 实施前等待批准。
4. 实施修复，然后运行 $prove-fix。

独立审查关卡（仅限非工作流）：任何独立的生产代码修复 — 无标志参数主流程（上述独立模式最低契约）或 $fix --target=issue — 都要添加一个 $changes-review 任务跟踪待办事项，作为最终变更审查关卡，并放在契约 §4 $why-review 最终签核之前（规格检查 → 变更审查 → 原因审查）。在工作流中跳过 — 流程顺序已包含 $changes-review。

以下调试思维、信心与证据关卡以及所有 SYNC 关卡均原样适用于此分支。

--target=logs — 日志 / 堆栈跟踪分支

目标： 分析应用程序日志，以诊断并修复运行时错误或意外行为。

关键规则：

• 重点关注日志模式：堆栈跟踪、错误代码、时序异常。
• 将日志与源代码交叉对照，找出实际根本原因。

工作流：

1. 检查 ./logs.txt 是否存在。如果不存在，在项目的脚本配置（package.json、Makefile、pyproject.toml，……）中设置永久日志管道：Bash/Unix 追加 2>&1 | tee logs.txt；PowerShell 追加 *>&1 | Tee-Object logs.txt。运行命令以生成日志。
2. 使用 debugger 子 Agent 分析 ./logs.txt：使用 Grep 读取，设置 head_limit: 30（最后 30 行；必要时增加，避免加载整个文件）。将分析写入 .ai/workspace/analysis/{issue-name}.analysis.md；修复前重新读取。
3. 使用 scout 子 Agent 定位问题的确切源头；反馈结果。
4. 使用 planner 子 Agent 制定实施计划；反馈结果。
5. 🛑 提出根本原因和修复计划 → 直接询问用户 → 等待批准。
6. 实施修复。
7. 使用 tester 子 Agent 验证；反馈结果。
8. 使用 code-reviewer 子 Agent 审查更改；反馈结果。
9. 如果测试失败，从第 3 步开始重复。
10. 汇总结果；建议后续步骤。然后运行 $prove-fix。

下方的 Debug Mindset、Confidence & Evidence Gate 和所有 SYNC 门控均原样适用于此分支。

--target=test — 测试失败分支

目标： 运行测试套件、分析失败原因，并修复底层代码或测试问题。

读取当前目标（修复前）： 按照 SYNC:goal-contract-satisfaction-loop 解析当前有效的 Goal Contract（有效计划 goal.md → plans/goals/{YYMMDD-HHmm}-{slug}/goal.md → 根据报告的测试失败创建）。将失败测试的证据（修复前）和通过测试的证据（修复后）映射到 Iteration Log 中保存的成功标准——如果通过的测试套件未覆盖某项已保存的必要标准，则循环尚未完成。

关键规则：

• 区分代码错误与不合理的测试预期。
• 修复后重新运行测试，确认全部通过。
• 审查或编写集成测试前，先阅读 docs/project-reference/integration-test-reference.md；诊断失败原因时，查阅 docs/specs/ 以了解预期行为。

工作流：

1. 使用 tester 子 Agent 编译代码并修复任何语法错误。
2. 使用 tester 子 Agent 运行测试；反馈结果。将失败分析写入 .ai/workspace/analysis/{test-issue}.analysis.md；修复前重新读取。
3. 如果测试失败，使用 debugger 子 Agent 查找根本原因；反馈结果。
4. 使用 planner 子 Agent 制定实施计划；反馈结果。
5. 🛑 提出根本原因和修复计划 → 直接询问用户 → 等待批准。
6. 逐步实施计划。
7. 使用 tester 子 Agent 验证；反馈结果。
8. 使用 code-reviewer 子 Agent 审查更改；反馈结果。
9. 如果测试失败，从第 2 步开始重复。
10. 汇总结果；建议后续步骤。然后运行 $prove-fix。

下方的 Debug Mindset、Confidence & Evidence Gate 和所有 SYNC 门控均原样适用于此分支。

--target=ui — UI / 视觉缺陷分支

目标： 诊断并修复 UI/UX 问题，包括布局、样式、响应式设计和视觉错误。

关键规则：

• 始终在模板元素上使用 BEM 类名。
• 修复布局问题时，检查响应式断点。
• 预先阅读（设计系统）： 从 docs/project-config.json 加载 designSystem.canonicalDoc + tokenFiles，确保修复使用真实的令牌名称（--brand-*、$brand-*）和规范的组件类，而不是自行编造取值。

必需技能（优先级顺序）： ui-ux-pro-max（设计智能数据库）→ web-design-guidelines（原则）→ design --lane=marketing（实现模式）。

工作流：

首先 — 运行 ui-ux-pro-max 搜索，以了解上下文和常见问题：

python $HOME/.claude/skills/ui-ux-pro-max/scripts/search.py "<product-type>" --domain product
python $HOME/.claude/skills/ui-ux-pro-max/scripts/search.py "<style-keywords>" --domain style
python $HOME/.claude/skills/ui-ux-pro-max/scripts/search.py "accessibility" --domain ux
python $HOME/.claude/skills/ui-ux-pro-max/scripts/search.py "z-index animation" --domain ux

如果用户提供了截图或视频，请使用 visual analysis tooling 技能详细描述问题，让开发者能够推测根本原因。

🛑 找出 UI 根本原因后，向用户说明发现的问题和拟议的修复方案 → 直接询问用户 → 获得批准后再进行任何代码更改。

1. 使用 ui-ux-designer 子 Agent，按照设计指南（designSystem.canonicalDoc）逐步实施修复。
2. 截取截图（精确定位到父容器，而非整个页面），并使用适当的 Gemini 技能（visual analysis tooling、video-analysis 或 document-extraction）进行分析，确保结果符合设计指南并解决所有问题。重复此步骤，直到问题解决。
3. 使用浏览器自动化工具，验证修复是否符合设计指南。
4. 使用 tester 子 Agent 进行编译和测试，并汇报结果。重复此步骤，直到所有测试通过。
5. 如果用户批准： 并行运行 project-manager 和 docs-manager 子 Agent，更新计划进度和 ./docs；同时让 project-manager 在 ./docs/project-roadmap.md 创建或更新项目路线图。
6. 汇总结果并建议后续步骤。然后运行 $prove-fix。

下文的 Debug Mindset、Confidence & Evidence Gate 和所有 SYNC gate 均同样适用于此分支。

工作流：

如果用户提供了截图或视频，请使用 visual analysis tooling 技能详细描述问题，确保开发者能够根据描述推测根本原因。

满足请求

质疑一切： 使用 ask the user directly 工具提出深入问题，充分了解用户的请求、限制和真实目标。不要妄自假设——持续澄清，直到 100% 确定。

• 使用 ask the user directly 澄清所有未解决的问题。
• 每次只问 1 个问题；等待用户回答后再问下一个问题。
• 没有问题 → 开始下一步。

⚠️ 修复前验证（不可妥协）： 找出根本原因并制定计划后，必须通过 ask the user directly 向用户说明发现的问题和拟议的修复计划，并在进行任何代码更改之前获得用户的明确批准。不得擅自修复。 从终点到起点的追踪门槛： 对于非简单缺陷、验证失败、过时或错误的最终输出，或会改变行为的修复，根本原因计划必须包含 Debugger Trace: End -> Start、馈入路径、假设矩阵、负责修复的层级，以及前向收敛证明。如果缺少这些内容，必须停止，并在规划代码更改前运行 $debug-investigate 或 $investigate。（Root-Cause Prerequisite Gate 已在调用时强制执行此要求；此门槛会再次检查生成的追踪内容。）

修复问题

读取当前目标（开始根因分析之前）： 根据 SYNC:goal-contract-satisfaction-loop 解决当前目标契约——当前计划 goal.md → plans/goals/{YYMMDD-HHmm}-{slug}/goal.md → 根据报告的问题，通过 .claude/templates/goal-contract-template.md 创建。已保存的成功标准决定了什么才算“修复完成”——即使本地修复已验证通过，只要未满足已保存的必需标准，就不算完成。验证通过后，将根因、验证证据和目标剩余差距追加到迭代日志中。微小修复只有在目标文件中记录了用户认可的理由后，才能跳过更深入的检查门槛。

使用 sequential-thinking skill 将复杂问题拆分为一系列思考步骤。 使用 problem-solving skills 处理问题。 分析 skills 目录，并在处理过程中启用所需的其他 skills。

1. 使用 debugger 子代理查找根因，并向主 Agent 汇报。如果根因前置门槛已针对这个问题运行 $debug-investigate，则跳过此步骤——该报告已涵盖此步骤；从第 3 步（规划）继续，而不是重新追查。— 原因：重复运行诊断会导致流程重复执行。 1.5. 将调查结果写入 .ai/workspace/analysis/{issue-name}.analysis.md。规划修复前，重新通读整个文件。 1.6. 确认报告包含完整的最终症状 → 读取方 → 存储／投影 → 写入方 → 消费方／任务 → 生产方／来源链路、所有馈入路径、假设矩阵、负责的修复层，以及前向收敛证明。
2. 使用 researcher 子代理在网上调查根因（如有需要），并向主 Agent 汇报。
3. 使用 planner 子代理根据报告制定实施计划，并向主 Agent 汇报。
4. 🛑 向用户说明根因和修复计划 → 直接询问用户 → 等待用户批准。
5. 使用 $plan-execute SlashCommand 逐步实施计划。
6. 最终报告：

• 向用户汇报变更摘要；简要说明，并指导用户如何开始使用；建议后续步骤。
• 询问用户是否要提交并推送到 git；如果要，使用 git-manager 子代理。

• 重要： 撰写报告时，宁可牺牲语法，也要简洁。
• 重要： 如有未解决的问题，在报告末尾列出。

请记住：

• 按需使用 visual analysis tooling skills 生成视觉素材。

• 使用 visual analysis tooling skills 读取并分析生成的素材，确认其符合要求。

• 编辑图像（移除背景、调整、裁剪）时，按需使用媒体处理工具。

• 修复后，必须运行 $prove-fix——为每项变更构建代码验证追踪，并标注置信度。绝不可跳过。

Spec-Loop 完成门槛（规范定义：SYNC:spec-loop-discipline）。 只有受影响的不变量完成闭环，修复才算完成：(1) 对于 bug 违反的每条 §4 [HARD] 规则／§5 不变量，都要提供一个全称量化的属性 TC（“对于 {domain} 中的所有输入，{invariant} 均成立”）和边界反例——不能只有单个复现示例（这是 §3 回归 TC 必须满足的属性门槛，而不只是一个示例用例）；(2) 修复后的核心逻辑行必须被变异测试杀死——如果变异体在修改行上存活，就说明缺少杀死它的测试，bug 可能悄然复发（以变异分数为门槛，而非行覆盖率）；(3) 根据 §3 规范正确性决策，将发现同时反馈到规范和测试中，并添加守护测试（双重反馈）——只有代码补丁而没有规范和测试反馈，就会让问题本身未被记录。宣告修复完成前，必须重新验证规范、测试和代码三者的一致性。

---

后续步骤（独立模式：最低契约完成后执行。在工作流中则跳过。）

根因前置门槛和上文的独立模式最低契约都不是可选项，也不是问题 — 独立 $fix 已自动运行 debug-investigate（门槛强制执行）→ 修复主干 → $prove-fix → 有条件地检查 $spec →（生产代码需执行 $changes-review）→ $why-review 作为最终签核。不要再次询问用户是否要执行这些步骤；它们是保证的最低要求。

满足上述最低要求后， 必须注意直接询问用户，提供最低要求之外的选项（由用户决定）：

• “继续执行完整工作流（推荐）” — 从这里移交给最合适的工作流（例如 workflow-bugfix），以补上最低主干未涵盖的其余门槛 — plan-validate、integration-test 的编写／审查／验证、production-readiness-review、security-review、changelog、docs-update。
• “$test” — 运行完整测试套件，在实际情境中验证修复。
• “提交并推送” — 将已验证并审查的更改移交给 git-manager 子 Agent。
• “到此为止” — 最低契约已满足；后续由用户处理。

如果已经在工作流中，则跳过契约和此菜单 — 工作流顺序会处理诊断、规范同步、审查和后续步骤。

[IMPORTANT] 开始前使用任务跟踪，将所有工作拆分为小任务 — 包括为每个文件的读取创建任务。这样可避免长文件导致上下文丢失。对于简单任务，必须注意询问用户是否跳过。

• docs/project-reference/domain-entities-reference.md — 领域实体目录、关系、跨服务同步（任务涉及业务实体／模型时阅读）

从结果反向追踪调试 — 对于非简单 Bug、验证失败、回归修复、会改变行为的代码或不清楚的代码流，提出修复方案前，先从观察到的最终状态开始反向追踪。

1. 帧 0：观察到的最终状态 — 明确指出用户可见的输出、失败断言、日志行、持久化值、API 响应、渲染后的 UI 或聚合桶。记录生成该结果的读取器／查询／渲染器，并提供 file:line 证据。
2. 逐跳反向追踪 — 按以下顺序追踪：最终读取器 -> 投影／缓存／存储 -> 写入器 -> 消费者／处理器／任务 -> 生产者／调用方 -> 原始触发。每一跳都记录：输入、转换、输出、负责人和证据。
3. 列出所有上游路径 — 找出所有可能写入最终路径的上游生产者／调用方／事件／任务，包括重试、异步、缓存、后台以及其他 UI／API 路径。将每条路径标记为已验证、已排除或仍未知。
4. 构建假设矩阵 — 对每个合理的原因，列出支持证据、反对证据、复现／验证方法、影响范围和状态（primary、contributing、ruled out、latent）。在明确排除或界定其他可能原因前，不要修复。
5. 选择负责的修复层 — 找出不变量的负责人，以及能保护所有下游消费者的最低共享位置。除非症状所在位置负责该不变量，否则应拒绝在症状出现处修复。
6. 正向证明收敛 — 选定修复方案后，再次从起点追踪到终点，说明修正后的状态如何到达观察到的最终输出。将每个根因对应到修复部分，并将每个修复部分对应到测试／证明。

以下各项完成前必须阻塞： 明确最终状态 · 完成反向追踪 · 列出所有上游路径 · 完成假设矩阵 · 论证负责的修复层 · 将正向收敛证明映射到测试。

绝不： 从第一个可疑代码路径开始。将多个生产者合并成一个“流程”。未经证明读取模型就把重复症状视为重复记录。跳过已排除的假设。 根因调试——采用系统化方法，绝不靠猜测和反复试错。

1. 复现——通过证据（错误消息、堆栈跟踪、截图）确认问题确实存在
2. 隔离——使用二分查找和图追踪，将范围缩小到具体的文件、函数或代码行
3. 追踪——从输入开始，沿数据流追踪到故障点。阅读实际代码，不要自行推断。
4. 提出假设——提出理论并给出置信度百分比。说明哪些证据支持或反驳该假设
5. 验证——通过针对性的 grep/读取来检验假设。每次只改动一个变量。
6. 修复——解决根因，而非表面症状。通过图中的 connections 验证修复没有破坏调用方

**绝不：**在没有证据时猜测。只修复表面症状而不解决根因。跳过复现步骤。

嵌套任务展开约定——对于工作流步骤调用，[Workflow] ... 行仅是父容器；子技能仍须创建可见的阶段任务。

1. 首先调用当前任务列表。如果存在匹配的活动父工作流行，设置 nested=true 并记录 parentTaskId；否则独立运行。
2. 在开始阶段工作之前，为声明的每个阶段创建一个任务。嵌套时，任务主题前缀为 [N.M] $skill-name — phase。
3. 嵌套时，使用 TaskUpdate(parentTaskId, addBlockedBy: [childIds]) 关联父任务。
4. 编排器必须预先展开子技能的阶段列表，并在调用该子技能或子 Agent 之前关联工作流行。
5. 工作前恰好将一个子任务标记为 in_progress，并在证据写入后立即标记为 completed。
6. 只有在所有子任务均已完成，或已明确取消并说明原因后，才能完成父任务。

**解除阻塞前提：**完成当前任务列表、创建子阶段任务、在嵌套时关联父任务，并将第一个子任务标记为 in_progress。

项目参考文档门禁——在任务跟踪初始化之后，以及读取目标文件/源文件、执行 grep、编辑或分析之前运行。项目文档优先于通用框架假设。

1. 确定范围：文件类型、领域和操作。
2. **首先读取 docs/project-config.json——项目的机器可读映射。**它是本仓库唯一可信的数据来源（模块/路径、框架及搜索关键词、测试/E2E/集成运行命令、设计系统、架构规则、工作流模式）；必须先依据它确认准确路径、运行命令和约定，再进行调查、规划或编码——绝不要假设框架默认值（CLAUDE.md 和参考文档均由它派生）。如果该文件、文档索引、lessons.md、CLAUDE.md、AGENTS.md 或任何必需参考文档缺失或过时，先自动运行 $project-init 或更精简的对应流程（$project-config、$docs-init、$scan-all、$scan --target=<key>、$claude-md-init）；如果 Codex 镜像或 AGENTS.md 过时，请让用户运行 $sync-codex（切勿自动运行）。
3. 根据触发条件读取必需文档：始终读取 docs/project-reference/lessons.md；文档查找：docs-index-reference.md；审查：code-review-rules.md；后端/CQRS/API：backend-patterns-reference.md；领域/实体：domain-entities-reference.md；前端/UI：frontend-patterns-reference.md；样式/设计：scss-styling-guide.md + design-system/design-system-canonical.md；集成测试：integration-test-reference.md；E2E：e2e-test-reference.md；功能文档/规格：feature-spec-reference.md + spec-system-reference.md + spec-principles.md；行为/公共契约/规格-测试-代码同步：workflow-spec-test-code-cycle-reference.md；派生规格索引/ERD/重新实现指南：spec-system-reference.md + docs/specs/ 下的源 Feature Specs；架构/新领域：project-structure-reference.md。
4. 读取所有必需文档，然后在开始目标工作之前声明：Reference docs read: ... | Not applicable: ...。

**满足就绪条件的标准：**已评估范围、查阅 docs/project-config.json、检查/读取必需文档或完成设置流程、确认 lessons.md，并输出引用。 任务跟踪与外部报告持久化 — 在开始执行前完成初始化；然后在处理目标文件/源码之前，先预取项目参考文档。

1. 在读取目标文件、搜索、编辑或分析之前，先创建一份简短的任务拆解。上下文丢失时，先检查当前任务列表。
2. 开始工作前，将一项任务标记为 in_progress；取得证据后立即标记为 completed；绝不要批量转换状态。
3. 对于计划/审查工作，在发现首个问题之前创建 plans/reports/{skill}-{YYMMDD}-{HHmm}-{slug}.md。
4. 每检查完一个文件/章节或作出一个决定后，追加记录发现，并在最后依据报告文件综合整理。
5. 最终输出引用：Full report: plans/reports/{filename}。

在以下条件完成前不得开始： 已创建任务拆解；计划/审查工作已声明报告路径；已持久化记录首个发现，然后才能记录下一个发现。

批判性思维 — 运用批判性思维和顺序思维。每项断言都必须有可追溯的证据，置信度须高于 80% 才能采取行动。 反幻觉： 绝不将猜测当作事实陈述——每项断言都要引用来源；坦然承认不确定性；自行检查输出中的错误；独立交叉验证；对自己的判断保持怀疑——没有证据支撑的确定性是幻觉的根源。

先理解代码 — 严格门槛：未阅读现有代码前，不得编写、规划或修复。

1. 搜索 3 个或更多相似模式（grep/glob）——引用 file:line 证据
2. 阅读目标区域中的现有文件——理解其结构、基类和惯例
3. 如果 .code-graph/graph.db 存在，则运行 python .claude/scripts/code_graph trace <file> --direction both --json
4. 通过 connections 或 callers_of 梳理依赖关系——了解哪些内容依赖你的目标
5. 对于非简单任务（涉及 3 个或更多文件），将调查记录写入 .ai/workspace/analysis/
6. 实施前重新阅读分析文件——绝不要仅凭记忆工作。— 原因：长上下文会偏离文件；文件才是事实依据
7. 绝不在现有模式可用时另创模式——严格遵循现有模式，或记录偏离原因。— 原因：不同模式会割裂代码库，并拖慢今后的每位读者

在以下条件完成前不得开始： - [ ] 已阅读目标文件 - [ ] 已搜索 3 个或更多模式 - [ ] 已追踪图（如果 graph.db 存在）- [ ] 假设已通过证据验证

基于证据的推理 — 严禁猜测。每项断言都必须有证据。

1. 每项断言都要引用 file:line、搜索结果或框架文档
2. 声明置信度：高于 80% 时可直接行动；60%–80% 时先验证；低于 60% 时不得建议
3. 架构变更必须进行跨服务验证
4. “证据不足”是有效且符合预期的输出

在以下条件完成前不得开始： - [ ] 证据文件路径（file:line）- [ ] 已执行搜索 - [ ] 已找到 3 个或更多相似模式 - [ ] 已声明置信度

无证据时禁止使用： “显而易见”“我认为”“应该”“大概”“这是因为” 如果条件未满足 → 输出："Insufficient evidence. Verified: [...]. Not verified: [...]." 修复层级责任——绝不要在崩溃现场修复。追踪完整流程，在负责该不变量的层级修复。

AI 的默认行为：在 A 处看到错误 → 在 A 处修复。这是错误的。崩溃现场是症状，不是原因。

任何修复前，必须：

1. 追踪完整数据流——梳理数据从源头到崩溃现场经过的所有层级的完整路径（存储 → 后端 → API → 前端 → UI）。找出错误状态从哪里进入，而不是它在哪里崩溃。
2. 确定不变量的负责方——哪个层级的契约保证该值有效？该层级就负有责任。在负责该不变量的最低层级修复，而不是在使用该值的最高层级修复。
3. 一次修复，最大程度防护——问自己：“在这里修复，能否通过一次更改保护所有下游使用方？”如果修复需要修改 3 个以上文件并添加防御性检查，那说明你选错了层级——应该再往下找。
4. 确认不存在绕过路径——确认所有数据流都会经过修复点。检查以下情况：绕过工厂直接构造、克隆／展开时未重新验证、原始数据未封装到领域模型中、在模型层之外进行修改。

完成以下各项前，禁止继续： - [ ] 已追踪完整数据流（源头 → 崩溃现场） - [ ] 已根据 file:line 证据确定不变量的负责方 - [ ] 已审查所有访问点（grep 计数） - [ ] 已论证修复层级合理（能保护最多使用方的最低层级）

反模式（必须拒绝）：

• “在崩溃处修复”——崩溃现场 ≠ 原因所在。向上游追踪。

• “在每个使用方都添加防御性检查”——分散防护 = 层级错误。一个权威修复 > 多处零散防护。

• “两边都修复更安全”——选择一个权威层级。在多个层级重复检查，会让人无法明确由谁负责该不变量。

源代码／测试漂移检查。 对于编码、修复、调试、调查、测试或评审工作：当源代码行为发生变化时，检查受影响的单元／集成／E2E 测试，并根据证据判断应修改测试以匹配预期行为，还是源代码更改本身是意外 bug、需要修复。不要为迁移代码编写测试；架构／数据迁移是一次性执行路径，不属于核心应用逻辑。

测试失败故障判定 — 测试失败时（或你正在调试或修复失败问题时），任务是判断 责任在谁——源代码还是测试代码。正确判定比让测试套件全部通过更重要。所有调试／修复／测试技能都必须遵循同一规则。

1. 在动任何一方之前先作出暂定判定。 将观察到的证据归类为 SOURCE-WRONG、TEST-WRONG、TEST-NOT-OPTIMAL、ENVIRONMENT-BLOCKED 或 AMBIGUOUS；然后运行 $debug-investigate，从结果追溯到起因，再进行编辑。让测试套件重新全绿不是目标。
2. 对照规范和源代码进行交叉验证。 如果有适用于该行为的 Feature Spec（例如 docs/specs/** — §3 ACs／§4 BRs／§5 invariants／§8 TCs），它就是判定_预期_行为的依据——同时对照生产源代码和失败的测试。如果没有规范，则以文档说明的意图／验收标准／调用方契约为准。根据这些证据，判定 SOURCE 是否有错，或 TEST 是否有错。
3. 判定责任方，然后从根源修复错误的一方：
   • SOURCE-WRONG — 生产代码违反了规范的预期行为或明确的不变量 → 在所属层修复源代码；保留或强化发现问题的测试。
   • TEST-WRONG — 测试包含过时或错误的断言、设置或预期，与预期行为相矛盾 → 从根源修复测试。绝不要削弱断言、添加跳过，或放宽超时来强行让测试通过。
   • TEST-NOT-OPTIMAL — 预期行为合理，但测试切入点、时序或断言信号不够稳健 → 改进测试，但不得削弱不变量。
   • ENVIRONMENT-BLOCKED — 基础设施或外部状态使源代码／测试无法判定 → 保留诊断信息，并在环境恢复正常前停止修改。
   • AMBIGUOUS — 证据或预期行为不足以安全地确定责任方 → 编辑前先询问用户或规范的权威负责人。
   • 绝不要为了匹配有问题的源代码而修改测试，也绝不要为了满足有问题的测试而修改源代码。（迁移代码除外——架构／数据迁移是一次性执行路径，不属于核心应用逻辑。）
4. 预期行为不明确时询问用户。 如果没有涵盖该行为的规范、规范对此保持沉默，或规范无法明确哪一方正确，则停止操作，并直接询问用户（或咨询规范的权威负责人），再修改任一方——绝不要为了让测试套件通过而默默选择修改源代码或测试。

应与预期行为保持一致，而不是与当前恰好通过的一方保持一致——全绿也可能掩盖问题本身。 AI 错误预防 — 每项任务都要避免的失败模式：

上下文变化后重新阅读文件。 上下文压缩、恢复工作或长时间运行的任务可能导致记忆过时；采取行动前，请核实当前文件。 根据源证据核实生成的内容。 AI 会幻觉出 API、名称、主张和文档事实。记录或引用之前，请检查相关来源。 删除或重命名之前检查下游引用。 移除某个产物可能导致文档、生成的镜像、配置和调用方过时；请先梳理引用。 编辑后追踪完整影响链。 修改定义可能会遗漏派生输出和使用方。宣布完成前，请追踪受影响的链路。 核实所有受影响的输出，而不只是第一个。 一项检查通过不等于所有检查都通过；请验证变更可能影响的每个输出界面。 假设现有值是有意设置的——在修改或指出缺陷之前，先询问原因。 修改或报告常量、限制、标志、阈值、措辞或模式之前，请阅读附近的上下文和历史、调用方的排序方式，以及 2 个以上采用相同约定的同类调用点。文档只说明是什么、却未说明为什么，这表示缺少理由，并不能证明缺少保护措施。 行动前明确指出歧义——不要默默选择。 多种解释均有效时，必须明确提问，或说明假设及其风险。 断言系统负责的最终结果，而非基础设施负责的中间状态。 验证异步工作时，应断言最终业务状态，绝不要断言由共享基础设施维护的投递／重试记录，因为任何并行运行的进程都可能写入这些记录。这类检查单独运行时会通过，但只要有其他进程共用该基础设施，就会变得不稳定。 共享指南应与接收者的角色相关。 通用指南必须对每个接收该指南的技能或 Agent 都有帮助；代码专属要求只能放在代码专属协议中。

重要：务必注意追踪完整的数据流，并在负责该逻辑的层级修复，而不是在崩溃发生处修复。添加 ?. 之前，请审查所有访问点。

重要：务必注意任何修改之前，都要搜索 3 种以上现有模式并阅读代码。如果存在 graph.db，请运行图谱追踪。

重要：务必注意每项主张都要引用 file:line 证据。置信度 >80% 才能采取行动；置信度 <60% 时，切勿提出建议。

务必注意运用批判性与顺序性思维——每项主张都需要适当的追踪证据（仓库／代码主张需提供 file:line；研究、产品、内容和文档主张需提供来源 URL 或产物章节）；置信度 >80% 才能采取行动，置信度 <60% 时切勿提出建议。防止幻觉：切勿将猜测当作事实陈述，坦诚承认不确定性，独立交叉核对，并对自己的判断保持审慎。

务必注意落实 AI 错误预防——根据证据核实生成的内容，删除或重命名前追踪下游引用，核实所有受影响的输出，上下文丢失后重新阅读文件，并在行动前明确指出歧义。

• 强制要求在开始目标工作前初始化任务跟踪；每次只转换一个任务的状态。

• 强制要求将计划／审查发现逐步保存到 plans/reports/，并根据磁盘上的内容综合整理。

• 强制要求在调查、规划或编码之前，阅读 docs/project-config.json（项目地图：模块／路径、运行命令、约定、架构／工作流规则）以及必需的项目参考文档，并注明 Reference docs read: ...。

• 强制要求始终包含 lessons.md；项目配置和约定优先于通用框架默认设置。

• 强制要求如果项目配置、根指令文件或任何必需参考文档缺失或过时，必须自动运行 $project-init 或更精简的下级路径，然后才能开展常规的项目专属工作。 重要，务必注意 调试追踪门禁：对于非琐碎的 Bug、修复、调查或审查工作，从观察到的最终输出开始，沿着 reader → storage/projection → writer → consumer/job → producer/trigger 反向追踪。修复前，列出所有供给路径和假设。只有在追踪、假设矩阵、负责修复的层级和正向收敛证明都齐备后，才能继续。

• 强制要求 父工作流行不能替代子阶段跟踪；展开各阶段，并在嵌套时链接父项。

• 强制要求 编排器必须在调用前预先展开子技能阶段；使用 [N.M] $skill-name — phase 前缀，并遵循同时仅有一个 in_progress 的纪律。

• 强制要求 开始工作前，先确定当前有效的目标契约（有效计划 goal.md → plans/goals/{YYMMDD-HHmm}-{slug}/goal.md → 根据当前请求创建），并在编辑前阅读已保存的成功标准。

• 强制要求 执行后追加迭代证据；报告 PASS 前，输出目标达成矩阵（PASS/FAIL/BLOCKED）；对已验证的 FAIL 继续循环处理；遇到重复的无进展情况或阻塞时升级处理。切勿在目标文件中存储机密。

项目协议覆盖规则 — 执行此技能前，先解析适用于本技能的项目覆盖规则：根据项目技能协议索引中的 Target 列匹配此技能名称（默认路径为 docs/project-reference/skill-protocols-reference.md；docs/project-config.json 中的 referenceDocs 条目可覆盖该路径），并且只采用最具体匹配层级：精确名称 > glob > *。此优先级仅用于排列覆盖规则彼此之间的优先顺序，绝不能凌驾于本技能之上。 只读取匹配项的正文，并解析为 <protocols-dir>/<Name>.md；行中的 Body 链接仅为显示文本，绝不是读取路径。若匹配的正文缺失或格式不正确，则报告并跳过，绝不能根据索引中的 Description 重建。没有索引或没有匹配项时，不应用覆盖规则并静默继续。完整约定见 .claude/skills/project-skill-protocol/references/registry.md。

覆盖规则仅可叠加：它们只能在本技能自身协议之上增加规则，绝不能替代、覆盖、禁用或重新解释本技能已有的规则——移除所有覆盖规则后，本技能必须恢复为与文档所述完全一致的行为。覆盖规则只是简报，不是权限升级：它绝不能豁免工作流门禁、Git 纪律、审查门禁或用户确认门禁。若覆盖规则与技能本身确实冲突，或两个具体程度相同的覆盖规则直接矛盾，则将两者都告知用户；绝不能静默裁决。

务必注意 执行前先解析适用于本技能的项目协议覆盖规则——只采用最具体的匹配层级（精确名称 > glob > *；此顺序仅用于排列覆盖规则彼此之间的优先级，绝不能凌驾于本技能之上），只读取 <protocols-dir>/<Name>.md 中匹配的正文；若正文缺失或格式不正确，必须报告，绝不能重建。覆盖规则仅可叠加（绝不能替代本技能自身规则），且只是简报，绝不是权限升级；具体程度相同的规则若相互矛盾，须交由用户处理。

收尾提醒

重要，务必注意目标： 找出问题的根本原因——从末端到起点追踪，并提供 file:line 证据，在拥有最低层级不变量的层级修复（绝不能只在崩溃位置修复）——然后通过 $prove-fix 证明修复有效，彻底治愈问题，而不只是消除症状。

务必注意——当前生效的协议（本技能包含的 SYNC/共享区块简明摘要）：

• 端到端调试追踪： 从观察到的最终输出开始，在修复前沿每条输入路径反向追踪。
• 根因调试： 复现 → 隔离 → 追踪 → 提出假设 → 验证 → 修复根因，而非症状。
• 嵌套任务创建： 父工作流行不能取代对子阶段的跟踪；应展开并关联各阶段。
• 项目参考文档指南： 在开展目标工作前，阅读必需的项目参考文档（始终包括 lessons.md）。
• 任务跟踪与外部报告： 初始化任务跟踪；逐步将计划和审查结果保存到 plans/reports/。
• 批判性思维： 运用批判性和顺序性思维；每项主张都要有追踪证据，置信度 >80% 才采取行动。
• 先理解代码： 修改前搜索 3 种以上模式并阅读代码。
• 基于证据的推理： 每项主张都引用 file:line；置信度 <60% 时，切勿提出建议。
• 修复层责任： 追踪完整的数据流，在所属层修复，而非在崩溃位置修复。
• 源码与测试偏差检查： 源码行为变化时，根据证据判断是否需要调整受影响的测试。
• 防止 AI 犯错： 根据证据验证生成的内容，追踪下游引用，验证所有受影响的输出，在上下文丢失后重新阅读，并明确指出歧义。 IMPORTANT MUST ATTENTION 根因前置门槛（阻塞，优先执行）——在 $fix 直接调用（无标志主流程以及每个 --target= 分支）之前，必须先在本次会话中用 $debug-investigate 追查当前问题，并通过当前任务列表中的条目或书面调查报告证明；回忆不算证据，对不同症状的先前调查不算数，父工作流条目本身也不能证明其诊断步骤已运行——未满足时，先运行 $debug-investigate，然后从规划步骤继续——原因：否则第一次编辑时根本没有追查过原因，只会修补症状出现的位置 IMPORTANT MUST ATTENTION 从头到尾追查症状，直至找到拥有该不变量的层，并在那里修复——绝不在崩溃位置修复——原因：崩溃位置只是症状；错误状态从更低层进入，在那里修复一次就能保护所有下游使用方 IMPORTANT MUST ATTENTION 每项主张都要注明 Confidence: X%，并提供 file:line 证据——建议置信度达到 95% 以上；80–94% 时说明注意事项；60–79% 时列出未知项；低于 60% 时停止——原因：猜测会让你修错层，并将病灶一并交付 IMPORTANT MUST ATTENTION 🛑 修复前确认——直接询问用户，说明根因和计划，并在任何代码变更前取得批准（仅在工作流内部可以跳过）——原因：未经告知的修复会绕过不可逆代码变更所需的人工把关 IMPORTANT MUST ATTENTION 优先按 --target= 分流——每个 {ci|issue|logs|test|types|ui} 分支均为独立流程（包含自身诊断和 $prove-fix）；无标志时执行完整的诊断→修复主流程——原因：这些分支不应重新执行独立主流程的 §1/§2 IMPORTANT MUST ATTENTION 默认模式为 HARD（完整严谨模式）——仅当确实是非常简单的 bug 且满足默认模式策略的全部 5 项条件时，才可选择快速模式；拿不准时默认使用 HARD——原因：对非简单 bug 跳过诊断，只会修补症状，留下病灶 IMPORTANT MUST ATTENTION 独立执行（无父工作流）时，自行组装主流程：debug-investigate → fix + prove-fix → $spec correctness check → $changes-review (production code) → $why-review；在工作流内部时，跳过该流程约定——但绝不能跳过根因前置门槛，该门槛仍要求提供证据，证明本次问题已运行该序列中的 debug-investigate 步骤——原因：独立执行时没有序列来提供诊断、规范同步或评审；而容器条目也不能证明其诊断步骤已运行 IMPORTANT MUST ATTENTION 修复后运行 $prove-fix——为每项变更生成带置信度评分的代码证明追踪；绝不跳过——原因：只说“应该能修好”却没有证明正向收敛，就意味着未经验证 IMPORTANT MUST ATTENTION 规范闭环完成条件——只有满足以下条件，修复才算完成：为被违反的 §4/§5 不变量编写普遍量化的属性测试用例（TC）和边界用例；对修改行进行变异测试并将其杀死；并将该问题反馈给规范和测试（双向反馈，Dual-Feedback）——原因：只修改代码会让该 bug 情形缺少文档记录，并可能悄然复发 IMPORTANT MUST ATTENTION 开始前将工作拆分为小型任务跟踪待办事项（一次读取对应一个任务）；上下文丢失时，先查看当前任务列表以恢复进度，绝不重复创建任务——原因：较长的调试文件会耗尽上下文并导致发现结果悄然丢失 IMPORTANT MUST ATTENTION 开始目标工作前，阅读必需的项目参考文档（始终阅读 lessons.md；测试分支阅读 integration-test-reference.md；行为相关内容阅读 docs/specs/）——原因：项目约定优先于通用调试假设 IMPORTANT MUST ATTENTION 遇到测试失败（--target=test 或任何测试失败）时，首先阅读 $integration-test-review 技能协议（断言质量、覆盖率以及规范↔测试↔代码故障门槛），以确定修复方向——判断故障根因在源代码，还是测试代码的设置／断言存在问题——原因：未先作出判断就修复，会修错一侧，还可能让违反不变量的代码通过测试 IMPORTANT MUST ATTENTION 修复前搜索至少 3 个类似模式并阅读现有代码；复制附近模式前先评估其是否适用——原因：最近的示例不一定满足相同的前提条件 IMPORTANT MUST ATTENTION 添加最终评审待办事项以验证工作质量；如果不加提醒该故障模式会再次出现，则提取根因经验教训（$learn） 反合理化：

逃避说辞	反驳
“根本原因显而易见，直接修补就行”	先从末端追溯到开头，找到负责不变量的层，并提供 file:line ——显而易见的位置只是症状。
“我已经调查过了”	请展示针对这一症状的当前任务列表条目或调查报告。记忆不算证据——压缩后，判断还在，调查结果却不在。
“工作流正在运行，已经完成诊断”	父级条目只是容器，并非证据。请引用针对这个问题的_已完成_ debug-investigate 步骤，否则就会触发门禁。
“--target= 已限定范围，所以不需要追溯”	每个分支都必须通过根因前置条件门禁。debugger/tester 子 Agent 步骤不等于从末端追溯到开头。
“在崩溃处修复”	崩溃位置 ≠ 原因位置。在负责不变量并保护所有使用方的最低层修复。
“加个 ?. / 守卫条件就继续”	到处散布防御性检查 = 层级错误。一个权威修复胜过许多守卫条件。
“把握够大了，跳过证据”	没有 file:line + 置信度 % = 不得提出结论。如果 <60%，就停止并收集证据。
“改动很小，跳过审批门禁”	🛑 修复前验证不可妥协，即使单独处理也必须执行——提交根因 + 计划并获得批准。
“测试通过了，修复就完成了”	只有在存在属性 TC + 边界用例、变更行通过变异测试验证，且规范 ↔ 测试完成双向反馈后，才算完成。
“已经搜索过代码库了”	请提供 file:line 证据。没有证明 = 没有搜索。

重要，必须注意 在 $debug-investigate 于本次会话中追溯此问题之前，绝不编辑代码——必须提供证据（任务条目 / 报告），不能凭记忆。 重要，必须注意 绝不在崩溃位置修复——从末端追溯到开头，找到负责不变量的层并在那里修复。 重要，必须注意 每个结论都要声明 Confidence: X% + file:line；如果 <60%，立即停止。 重要，必须注意 任何代码变更之前都必须先获得 🛑 修复前验证的批准，然后执行 $prove-fix——两者绝不能跳过。

[TASK-PLANNING] 行动前，分析任务范围，并通过任务跟踪系统将任务系统地拆分为小型待办任务和子任务。

无钩子提示词协议镜像（自动同步）

来源：.claude/.ck.json + .claude/skills/shared/sync-inline-versions.md（:full 块）+ .claude/scripts/lib/hookless-prompt-protocol.cjs

[WORKFLOW-EXECUTION-PROTOCOL] [BLOCKING] 工作流执行协议 — 强制要求，重要，必须执行，关键。任何情况下都不得跳过。

**通用可移植性边界：**可复用技能和协议文本应保持项目中立；从 docs/project-config.json 和 docs/project-reference/ 中了解项目特定约定。应用 shared/sdd-artifact-contract.md 中的共享 AI-SDD。阅读 docs/project-config.json 和 docs/project-reference/docs-index-reference.md，然后打开其中列出的项目参考文档。对于规范、测试用例、行为变更、公共契约或 docs/specs/ 相关工作，应通过文档索引中列出的本地规范文档进行：当规范／测试／代码必须保持同步时，使用 feature-spec-reference.md、spec-system-reference.md、spec-principles.md 和 workflow-spec-test-code-cycle-reference.md。如果任一文件或必需的参考文档缺失或过时，则在进行常规项目特定工作之前，自动运行 $project-init（或更精简的底层流程，例如 $project-config、$docs-init、$scan-all 或 $scan --target=<key>）。只要具备此共享上下文和本地文档，任何受支持的 AI 工具都可以执行。

1. **检测：**如果提示以明确的斜杠技能／工作流命令开头，则直接执行。否则，根据工作流目录和技能列表匹配提示。
2. **分析：**选择最佳方案：直接执行、调用技能、启动标准工作流，或组合自定义步骤。
3. **自动选择：**自行选择最佳方案。不要让用户在直接执行、技能、标准工作流或自定义工作流之间做选择。
4. **启动：**对于选定的工作流，调用 $start-workflow <workflowId>；对于选定的技能，调用该技能；对于自定义工作流，直接按顺序执行自定义步骤；对于直接执行，继续处理任务。
5. **创建任务：**如果选定路径包含多个步骤，则在执行前为所有工作流／技能／自定义步骤创建任务跟踪。
6. **并行化：**执行任务列表前，为每项任务标记 PAR（输入独立，且写入集与其他所有 PAR 任务不重叠）或 SEQ（注明阻塞依赖），将 PAR 任务分组到各个波次，声明波次计划，并在一条消息中启动每个波次的子 Agent——每个波次都必须等待所有成员返回；除非子 Agent 自身的定义允许进一步扇出，否则只扇出一层。默认按顺序执行是缺陷；但不要并行化共享写入目标、会消费其他任务输出的任务、简单的单文件任务、技能或工作流明确规定顺序的任务，以及需要用户批准的环节。
7. **执行：**按照上下文指令中的 Workflow Step Advancement & Parallel Phases 规则推进——由模型驱动；子 Agent 完成与内联调用一样会推进步骤；并行阶段组必须等待所有成员返回（只有所有成员都返回后才能推进，绝不能串行执行）

共享 AI-SDD 协议标记

来源：.claude/skills/shared/sync-inline-versions.md

SYNC:ai-sdd-artifact-contract

AI-SDD 工件契约 — 共享的规范驱动开发规则应保持可移植，并由源文件管理。

1. 将可复用的 AI-SDD 原则保存在 .claude 中；将特定于仓库的路径、命令、负责人、产品和格式放在项目配置／参考文档中。
2. 保持以下周期：spec -> plan -> tasks -> implement -> verify -> update spec/docs。
3. 通过决策、任务、TC／测试、源证据以及文档／规范更新，追踪每项要求或不变量。
4. 将从代码提取规范的内容仅视为参考，直到规范的权威负责人接受为止。
5. 任何受支持的 AI 工具都可基于同步的上下文进行规划、实现、审查或验证；使用多个工具是可选的。
6. 先更新 .claude 源文件，再同步生成的镜像；不要手动编辑 .agents、.codex 或 AGENTS.md。— 原因：镜像是生成的工件；下次同步时，手动修改会被覆盖
7. 如果 docs/project-config.json、根目录指令文件或必需的项目参考文档缺失或过时，则在进行常规项目特定工作之前，自动运行 $project-init 或范围更窄的底层流程。

当前参考文档： 当前技能根目录中的 shared/sdd-artifact-contract.md。

---

SYNC:ai-sdd-artifact-contract:reminder

• MANDATORY 应用 shared/sdd-artifact-contract.md；将可复用的 AI-SDD 保存在 .claude 中，并将本地规则保存在项目文档中。
• MANDATORY 从代码提取的规范仅供参考，直到权威规范获批；任何受支持的 AI 工具都可基于同步的上下文执行工作。
• MANDATORY 先更新 .claude 源文件，再同步生成的镜像；不要手动编辑 .agents、.codex 或 AGENTS.md。
• MANDATORY 如果项目配置、根目录指令文件或必需的参考文档缺失或过时，则应自动通过 $project-init 或范围更窄的设置流程来处理项目特定工作。 [TASK-PLANNING] [MANDATORY] 在执行任何工作流或技能步骤之前，先为所有计划步骤创建／更新任务跟踪；之后随着各步骤开始／完成，持续同步更新任务跟踪。

[LESSON-LEARNED-REMINDER] [BLOCKING] 任务规划与持续改进 — MANDATORY。不得跳过。

开始前将工作拆分为小任务（任务跟踪）。添加最终任务：“分析 AI 错误与经验教训”。

提取经验教训——仅关注根本原因，而非修复表象：

1. 指明失败模式（推理／假设失误），而非表面症状——“未阅读源代码就假设 API 存在”，而不是“使用了错误的枚举值”。
2. 通用性测试：此失败模式是否适用于 ≥3 种情境／代码库？如果不适用，则再向上抽象一层。
3. 写成通用规则——去除特定于项目的名称／路径／类。规则应适用于任何代码库。
4. 合并：多个错误若属于同一种失败模式，则合并为一条经验教训。
5. 复发门槛：“如果没有这条提醒，未来会话中是否会再次出现此问题？”——不会 → 跳过 $learn。
6. 自动修复门槛：“$code-review／$code-simplifier／$security-review／$lint 能否发现此问题？”——能 → 改进审查技能。
7. 两个门槛都通过 → 请用户运行 $learn。 [CRITICAL-THINKING-MINDSET] 运用批判性思维和序贯思维。每项断言都需要可追溯的证据；采取行动前，置信度须 >80%。 **反幻觉原则：**绝不将猜测当作事实——为每项断言引用来源，坦诚承认不确定性，自行检查输出错误，独立交叉核对，并对自己的信心保持怀疑——缺乏证据的确信是所有幻觉的根源。 **AI 注意力原则（首因－近因效应）：**在较长提示词／协议的开头和结尾都放置最关键的 3 条规则，以确保指令在较长的上下文窗口中仍能得到遵循。 **目标驱动执行：**先定义成功标准，持续循环直至验证完成；仅当可观察的检查均通过后才停止。 **测试验证意图：**测试必须保护业务规则／不变量，并在受保护的意图遭到破坏时失败，而不只是复现当前行为。

常见 AI 错误预防（系统经验）

• 上下文压缩后重新读取文件。 编辑前必须在同一上下文中先读取文件；上下文压缩会清除读取状态。编辑前重新读取。
• 批量替换后 grep 旧术语。 AI 过度相信查找/替换已覆盖所有内容。批量编辑后，对整个仓库执行 grep，检查文档/配置/目录中遗漏的引用。
• 删除前检查下游引用。 删除会连带导致文档/代码过时。移除前先梳理引用文件。
• 丢失记忆后，创建新内容前先检查现有状态。 上下文压缩会清除先前工作的记忆。查询当前状态以便继续——绝不要盲目重复创建。
• 根据实际代码验证 AI 生成的内容。 AI 会幻觉出 API、类名和方法签名。记录/引用前先用 grep 确认其确实存在。
• 编辑后追踪完整依赖链。 更改定义却漏掉下游使用方。追踪完整链路。
• 重命名时，对所有使用方文件类型执行 grep。 某些文件类型会静默忽略缺失的引用（不会产生编译错误）。搜索代码、模板、配置和生成文件。
• 验证正确性时追踪所有代码路径。 代码存在 ≠ 代码会执行。追踪提前退出、错误分支和条件跳过——不要只看正常路径。
• 源数据变更时，更新包含规范数据的文档。 内嵌派生数据（工作流、架构、配置）的文档会静默过时。源数据变更时，同时更新所有内嵌该数据的文档。
• 恢复上下文后验证子 Agent 的结果。 父 Agent 压缩上下文期间，后台 Agent 可能已经完成——用 grep 验证输出，不要相信对任务已完成的假设。
• 将完整目标列表与子 Agent 的分配任务交叉核对。 按类别并行分配子 Agent 会漏掉边界项。继续前，将各分配任务的并集与目标列表核对。
• 子 Agent 只能从其 Agent 的 .md 定义继承知识——使用自定义 Agent 类型，不要使用内置 Explore。 采用工具 = 权限 + 知识 + 执行（编号工作流步骤）。
• 逐步记录子 Agent 的发现，不要等最后一次性提交。 长时间运行的子 Agent 可能在最终写入前达到截断限制——导致发现丢失。指示其按章节追加到报告文件。
• 调试时，修复前先问“责任在谁？” 追踪调用方（数据错误）还是被调用方（处理错误）。在责任层修复——绝不要只修补症状出现的位置。
• 测试失败 → 先记录暂定结论，再追踪/编辑，然后调查。 使用完整的五类分类：SOURCE-WRONG（生产代码违背意图）、TEST-WRONG（断言/设置已过时）、TEST-NOT-OPTIMAL（测试有效但脆弱或信号弱）、ENVIRONMENT-BLOCKED（外部状态阻止得出结论），或 AMBIGUOUS（意图/证据不足以安全判断）。然后追踪根因，并对照规范依据（如果存在，查看 docs/specs/**）和源代码进行交叉验证。绝不要只为让测试变绿而削弱断言、添加跳过、放宽超时或更改源代码。
• 提取/重构后，对所有已移除名称执行 grep。 主文件“完成” ≠ 次要文件干净。宣布完成前，在整个范围内搜索每个已移除的符号。
• 假定现有值是有意设定的——更改或将其标记为缺陷前先问为什么。 仅凭模式匹配判定“错误”会忽略上下文。更改或报告任何常量/限制/标志/阈值前：阅读注释、git blame、调用方的执行顺序（使该值正确的保证通常位于引用行之前紧邻执行的代码中），以及同一惯例下至少 2 个同类调用点。只说明“是什么”却不说明“为什么”的文档，缺少的是依据，并不能证明缺少保护措施；在验证环节中，准确的 file:line 引用证明的是转录无误，而不是缺陷确实存在。
• 验证所有受影响的输出，而不只是第一个。 一个构建成功 ≠ 全部成功。涉及多个技术栈的变更（后端/前端/测试/文档）要求验证每一项输出。
• 复制相近模式前，先评估是否适用。 最接近的示例 ≠ 前提相同——确认新上下文具有相同的约束、基类、作用域和生命周期。
• 整体优先的调试方式——抵制注意力就近陷阱。 不要一头扎进第一个看似合理的原因。列出所有前提（配置、环境变量、路径、数据库、端点、凭据、版本、DI、数据）。用证据（grep/查询——而非推理）逐项验证。问“什么证据可以推翻这个假设？”——如果没有，那就不是假设。代价最高的失败：在“显而易见”的层继续深挖，而 Bug 实际位于从未质疑过的层。
• 精准修改——应用 diff 测试（结合上下文判断）。 两种模式：（1）Bug 修复 → 每一行都能追溯到该 Bug；不做样式调整；只清理因你的修改而变得未使用的孤立内容。（2）审查/增强 → 实施改进，并声明为“超出主要请求的增强：[内容]”。绝不要悄悄扩大范围。Diff 测试：“如果我没有被要求做 X，这一行还会存在吗？”——如果不会，就删除或明确说明。
• 编码前先指出歧义——不要默默自行选择。 存在多种有效解释时，逐一列出并说明工作量：“[请求] 可能指 (1) [N 小时]、(2) [N 小时]。哪一个更重要？”先列出范围/格式/数量/约束方面的假设。如果有更简单的方案，也要说明。绝不要默默自行选择。
• [MANDATORY FIRST ACTION] 回复前务必先启用合适的技能或工作流。 将任务与工作流目录和技能列表进行匹配；通过技能调用或 $start-workflow <workflowId> 启用。检查之前绝不要回答或编写代码。跳过 = 违反协议。
• Why-Review 对抗性思维——审查任何计划、决策或设计时都要运用。 默认持怀疑态度，而非验证者态度：充分论证被否决的替代方案，将每项既定理由反向审视（“它牺牲了什么？”），对最重要的 2-3 项假设进行压力测试，开展事前验尸（“已发布，3 个月后失败——什么会出问题？”），并指出作者遗漏的 1-2 种替代方案。章节齐全 ≠ 质量过关；质量取决于因果推理、具体缓解措施和证据，而不是“这样更好”或“密切关注”。
• 大型审查的子 Agent 提示词应优先安排报告写入。 处理许多文件的子 Agent 可能在最终写入前耗尽预算——导致发现丢失。设计提示词时应确保：（1）报告写入是第一个明确的交付项，（2）按文件/章节逐项追加（不要批量写入），（3）限定范围，避免读取耗尽预算。若输出在句中被截断且没有报告文件 → 启动范围更窄的任务，不要原样重试相同提示词。
• 上下文压缩后，继续前重新验证此前各阶段的所有结果。 摘要描述的是意图，不是环境状态（git 索引、文件系统、进程）。恢复时，首先审查：git status、重新读取修改过的文件、验证文件系统。每一项“已完成”的声明，在证据确认前都是未经验证的假设。
• OOM/内存：先检查行数，再检查行大小。 排查顺序：（1）无界查询——触发条件是否没有数据库筛选？将筛选推到数据库端；这可消除 OOM。（2）行是否很大？投影可按比例减少数据量。减少行数比投影的收益更大。
• 断言系统自身负责的结果，绝不要断言基础设施负责的中间状态。 测试任何异步行为（队列/代理传递、重试、后台任务、缓存、复制）时，应断言最终业务/实体状态。绝不要断言传递记录——消费/发送状态、尝试次数、最后错误、代理、调度程序或 outbox/inbox 表中的行存在与否或数量。这些记录属于共享基础设施，任何同时运行的进程（同伴 Worker、第二个副本、遗留的本地容器）都可能写入，且通常使用确定性的共享键；因此，断言会悄悄测试开发者的环境，而不是系统：单独运行时通过，一旦有其他进程共享该代理和数据库就会不稳定。每个断言都要问：“无论哪个进程执行了这项工作，该断言都会成立吗？”——如果不会，就改为断言已收敛的数据状态。推论：进程本地的故障注入和进程内遥测不能用于控制任何进程都可能执行的工作——将它们用作压力放大器（启用 → 限定时间窗口 → 停用 → 断言收敛），绝不要用作前置条件。
• 不要让领域概念进入通用/共享/基础设施层。 可复用层（共享库、框架、基础设施模块）不得引用任何特定使用方的领域概念——租户/客户/产品 ID、业务实体、功能规则。泄漏进来后，代码能够编译并运行，因此会悄无声息地通过审查，同时让“可复用”层与某个使用方耦合。保持共享类型与领域无关；通过子类/组合将领域字段/逻辑下放到使用方。——原因：与某个使用方的领域耦合的层不再可复用。