test

Codex 兼容性说明：

• 在 Codex 中使用 $skill-name 调用仓库技能；此镜像副本会改写旧版 Claude /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] 如果任务工具不可用，请创建并维护等效的逐步计划跟踪，并使用相同的状态转换。

快速摘要

目标： 通过使用 tester 子 Agent 在本地运行测试并分析摘要报告，给出准确的只读通过/失败判定，并提供精确数量、失败测试名称、报告路径和目标契约证据，让用户了解真实的测试状态，且不应用任何修复。

摘要：

• 目的： 让用户了解真实的测试状态——准确的通过/失败判定、精确数量、失败测试名称、报告路径——且不应用任何修复。
• 主要步骤（按顺序执行）： (1) 委派——根据参数中的测试范围启动 tester 子 Agent；绝不直接调用测试命令。(2) 分析——审查子 Agent 的摘要报告；识别失败项和模式。(3) 报告——总结通过/失败数量，指出失败测试，并引用报告路径。(4) 目标证据——解析当前有效的目标契约，追加验证证据，并更新目标满足情况矩阵。
• 只读：报告结果后立即停止；绝不开始实施修复——原因：修复是 $fix 的工作，将修复混入报告会掩盖真实的测试状态。
• 运行后，将验证证据（命令、精确数量、报告路径）追加到目标文件的迭代日志，并更新目标满足情况矩阵；如果没有有效目标，则记录“没有有效目标——仅在此处报告证据。”；绝不将敏感的测试夹具数据复制到目标文件中——原因：目标文件是持久的通过/失败记录，而不是秘密存储库。

工作流：

1. 委派——根据参数中的测试范围启动 tester 子 Agent
2. 分析——审查测试结果，识别失败项和模式
3. 报告——总结通过/失败数量，指出失败测试

关键规则：

• 只读：不要实施修复，只报告结果
• 过程中根据需要，从目录中启用相关技能
• 始终使用 tester 子 Agent，不要直接运行测试命令
• 间歇性失败（一次运行失败，另一次运行通过）尚不能认定为产品缺陷——在将其报告为产品缺陷前，按 $integration-test-verify 使用的相同判定流程处理：(a) 场景不切实际／参与者节奏过快；(b) 测试框架拓扑放大效应（共享基础设施、扇出消费者、套件并行运行、冷启动）；或 (c) 真正的产品竞态。报告判定及其证据，或者将失败报告为尚未判定——绝不能仅凭一次失败运行就认定为产品缺陷

保持怀疑。运用批判性思维和序列化思维。每项主张都必须有可追溯的证据，并给出置信度百分比（想法应超过 80%）。

使用 tester 子 Agent 在本地运行测试并分析摘要报告。

重要：报告结果后立即停止——不要开始实施。

**重要：**分析技能目录，并在过程中启用任务所需的技能。

**目标契约证据（测试运行后）：**按照目标契约满足循环协议解析当前有效的目标契约（有效计划 goal.md → plans/goals/{YYMMDD-HHmm}-{slug}/goal.md）。如果存在，则将验证证据追加到目标文件的迭代日志——测试命令、精确的通过/失败数量、报告路径——并关联到本次运行验证的已保存成功标准；同时更新这些标准对应的目标满足情况矩阵行（PASS/FAIL/BLOCKED）。如果没有有效目标，则记录 No active goal — evidence reported inline only.。绝不将原始敏感测试夹具数据复制到目标文件中。

第一原则 — 易于更改

每项编码决策的成功指标都是_未来的更改成本_。 DRY、SRP、抽象、设计模式、命名、分层、测试——每种 技术都服务于一个目标：让下一次更改成本更低。

评估代码、重构、测试或抽象时，请问： 这会让下一次更改成本更低还是更高？

• 拒绝会增加更改成本的“最佳实践”（过早抽象、 推测性泛化、泄漏的间接层、没有收益的繁琐仪式）。
• 在发现中指出真正的敌人：耦合、隐藏状态、重复的 知识、意图不明确、过早暴露且不可逆的决策。
• 易于更改的简单设计，胜过难以更改的复杂设计。

在应用以下任何具体规则、模式或清单之前，先用这一原则进行判断——如果后续规则会增加更改成本，应以此原则为准。

---

工作流建议

**强制重要必须注意——无一例外：**如果你当前尚未处于工作流中，就必须注意直接询问用户。不要判断任务复杂程度，也不要擅自决定任务“足够简单，可以跳过”——是否使用工作流由用户决定，而不是你：

1. 启用 testing 工作流（推荐）——测试
2. 直接执行 $test——独立运行此技能

---

后续步骤

完成此技能后，强制重要必须注意——无一例外，你必须注意直接询问用户并提供以下选项。不要因为任务看起来“简单”或“显而易见”而跳过——由用户决定：

• "$docs-update (Recommended)" — 测试通过后更新文档
• "$fix" — 如果测试发现需要修复的问题
• "$watzup" — 结束会话并审查所有更改
• "Skip, continue manually" — 由用户决定

[IMPORTANT] 使用任务跟踪，在开始前将所有工作拆分为小任务——包括每个文件读取任务。这可以防止因文件过长而丢失上下文。对于简单任务，AI 必须注意询问用户是否跳过。

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

**外部记忆：**对于复杂或耗时较长的工作（研究、分析、扫描、审查），请将中间发现和最终结果写入 plans/reports/ 中的报告文件，以防丢失上下文，并作为交付物。

**证据门槛：**强制重要必须注意——每项声明、发现和建议都需要 file:line 证明或可追溯的证据，并注明置信度百分比（>80% 才能采取行动，<80% 必须先核实）。

批判性思维——运用批判性思维和顺序思维。每项声明都需要可追溯的证据，采取行动的置信度必须 >80%。 **反幻觉：**绝不可将猜测当作事实——每项声明都要引用来源，自由承认不确定性，自查输出错误，独立交叉验证，并对自己的判断保持怀疑——没有证据的确信是所有幻觉的根源。

基于证据的推理——禁止推测。每项声明都需要证据。

1. 为每项声明引用 file:line、grep 结果或框架文档
2. 声明置信度：>80% 可直接采取行动，60-80% 先核实，<60% 不要建议
3. 架构更改必须进行跨服务验证
4. “证据不足”是有效且预期的输出

以下条件满足前不得继续： - [ ] 证据文件路径（file:line） - [ ] 已执行 grep 搜索 - [ ] 找到 3 个或更多相似模式 - [ ] 已说明置信度

未经证实不得使用：“显然”“我认为”“应该是”“可能是”“这是因为” 如果未完成 → 输出："证据不足。已核实：[...]。未核实：[...]。" 源码与测试漂移检查。 对于编码、修复、调试、调查、测试或审查工作：当源码行为发生变化时，检查受影响的单元／集成／E2E 测试，并根据证据判断是应修改测试以匹配预期行为，还是源码变更引入了意外错误，需要修复。不要为迁移代码编写测试；架构／数据迁移是一次性执行路径，不属于核心应用逻辑。

测试失败归责判定 — 当测试失败时（或正在调试或修复失败），任务是判断_过错在谁——源码还是测试代码_。正确作出判定比让测试套件重新通过更重要。所有调试／修复／测试技能均须遵循此规则。

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

应以预期行为为准，不要迁就当前能通过的一方——通过的测试也可能掩盖问题本身。 真实场景还原门槛 — 编写、审查或修复任何集成测试／端到端测试／系统测试时，必须遵守。

只有复现系统在生产环境中确实可能遇到的情况，测试才值得信赖。现实中绝不可能发生的场景，即使测试通过也毫无证明力；测试失败时还会浪费数小时。

1. 编写测试设置之前，先确认场景还原度： “这套操作顺序、时序和数据在生产环境中真的可能出现吗？” 如果不可能，说明测试场景定义有误——修正场景，绝不要修改断言。
2. 按照真实节奏模拟参与者的操作。 生产环境中相隔几秒、几分钟或几小时的两个不同操作，绝不能在同一毫秒内连续触发。把操作间隔压缩会制造出系统从未设计来应对的竞态，然后把它们报告为产品缺陷。
3. 等待真实信号，绝不盲目休眠。 找到能证明上一步已完成的可观测信号——例如已持久化的状态变更、审计／版本戳、队列／工作线程空闲标记或完成事件——并持续轮询，直到状态稳定（在较短的稳定观察窗口内保持不变）。仅当不存在可观测信号时才使用固定延迟，并在注释中说明原因。
4. 屏障应放在 ARRANGE 阶段，绝不能放在 ASSERT 阶段。 等待前置条件是还原真实场景；延长断言超时时间、放宽比较条件、在失败的断言外添加重试或跳过测试，都是掩盖问题。绝不能用这些方式强行让测试通过。
5. 区分测试框架放大效应与真实问题。 测试拓扑（共享基础设施、扇出消费者、并行测试套件、冷启动）可能让生产环境中罕见的竞态在本地频繁发生。在提交产品缺陷前，说明生产环境中是否存在触发条件，以及触发概率。
6. 保持受保护的不变量不变。 提高场景还原度绝不能削弱测试的保护范围。如果真实场景无法再检验该规则，就需要为该规则设计另一个真实场景，而不是放宽断言。
7. 允许专门测试不可能状态，但必须明确标注。 修复损坏数据、迁移和故障安全测试会有意构造生产环境本不应出现的状态；请在注释中说明该状态为何仍有可能出现（上游错误、部分写入、遗留数据），以免与不真实的测试设置混淆。 AI 错误预防 — 每项任务都要避免的失败模式：

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

重要，务必注意：每项主张都要引用 file:line 证据（行动置信度 >80%）。

绝不在没有证据的情况下猜测。

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

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

• 强制要求：开始工作前，先确定当前有效的目标契约（有效计划 goal.md → plans/goals/{YYMMDD-HHmm}-{slug}/goal.md → 根据当前请求创建），并在编辑前阅读已保存的成功标准。
• 强制要求：执行后追加迭代证据；报告通过前，输出目标满足度矩阵（PASS/FAIL/BLOCKED）；针对经验证的失败继续迭代；多次没有进展或遇到阻碍时升级处理。绝不要在目标文件中存储机密。

提示词增强收尾锚点

重要，务必注意：遵循此技能声明的步骤顺序；未经用户明确批准，绝不跳过、调整顺序或合并步骤。 重要，务必注意：对于每个步骤／子技能调用，执行前设为 in_progress，执行后设为 completed。 重要，务必注意：每个跳过的步骤都必须说明明确原因；每个已完成的步骤都必须提供简明证据。 重要，务必注意：如果 Task 工具不可用，请维护一个状态同步的逐步计划跟踪器，作为等效方案。

并行子 Agent 调度 — 一旦有了任务拆分，就立即规划并行执行，必须在执行前完成；按顺序执行已明确互不依赖的任务会浪费实际耗时。适用于所有多步骤工作：工作流步骤、规划、批量更新、调查、研究、扫描、审查、文档同步。计划执行由元数据控制，绝不默认并行——仅根据计划声明的内容（PAR/SEQ 标签和各阶段的写入集）进行扇出；未标记的计划按顺序执行。原因：推导出的写入集无法识别级联写入或生成的写入。

1. 为每项任务标记 PAR 或 SEQ。 PAR = 输入不包含任何待处理任务的输出，且写入集与其他所有 PAR 任务互不重叠。否则标记为 SEQ——必须明确说明导致该依赖的原因。
2. 将 PAR 任务分组成多个波次。 同一波次的成员之间不得有依赖关系。两个会写入同一文件的任务绝不能位于同一波次。只读工作（搜索、调查、审查、研究）可自由并行。
3. 派发前声明： Parallel plan: wave 1 = [...] · wave 2 = [...] · SEQ = [...] (reason)。
4. 在一条消息中启动每个波次——一条回复中的所有 spawn_agent 调用必须一次发出，绝不能分多轮逐个发送。将每项任务分配给对应的专业 Agent（.claude/skills/shared/sub-agent-selection-guide.md）；绝不能把 code-reviewer 当作通用 Agent。
5. 为每个子 Agent 提供完整的独立说明： 目标 · 范围及负责的文件 · 参考文档 · 返回要求（摘要 + Full report: 路径，遵循 SYNC:subagent-return-contract）· 持续保存进展到 plans/reports/（遵循 SYNC:incremental-persistence）。
6. 每个波次都设置屏障。 仅在该波次的所有成员都返回后才能继续（跳过的条件任务也视为已返回）。合并结果，将每项任务标记为已完成/已跳过，然后再派发下一波。修改性步骤必须等待屏障解除。
7. 仅限一层深度。 已派发的子 Agent 执行自己的说明；除非其 .claude/agents/*.md 定义授权，否则进一步扇出仍由编排者负责。

绝不并行执行： 共享写入目标的任务 · 消耗待处理任务输出的任务 · 微不足道的单文件工作（派发开销大于收益）· 技能或工作流明确规定顺序的任务 · 等待用户批准的关卡。

解除阻塞的条件： 必须为每项标记为 PAR/SEQ 的任务标明原因，SEQ 尤其如此 · 声明波次并检查写入集互不重叠 · 每个波次都在一条消息中启动 · 在进入下一波前遵守屏障要求。

• 强制要求 规划任务后，为每项任务标记 PAR/SEQ，并在一条消息中将每个 PAR 波次作为并行子 Agent 启动——工作流、批量更新、调查、研究、审查默认并行；计划执行仅依据计划声明的内容进行扇出。
• 强制要求 每个波次的写入集必须互不重叠 · 进入下一波前必须等待所有成员返回 · 分配给专业 Agent · 除非子 Agent 自身的定义授权，否则绝不能进一步扇出。

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

叠加规则仅可添加内容：它们只能在此技能自身的协议之上添加规则，绝不能替换、覆盖、禁用或重新解释已有规则 — 移除所有叠加规则后，此技能必须完全恢复为其文档所述的行为。叠加规则是简报，不是权限升级：它绝不能豁免任何工作流关卡、Git 规范、审查关卡或用户确认关卡。若叠加规则与技能之间确实冲突，或两个具体程度相同的叠加规则直接矛盾 -> 向用户说明两者；绝不可静默解决。

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

收尾提醒

**重要，务必注意目标：**提供准确、只读的通过/失败判定 — 通过 tester 子代理运行测试，并分析其摘要报告 — 提供精确数量、失败测试名称、报告路径和目标约定的证据，让用户了解真实的测试状态，且不应用任何修复。

生效协议（此技能所含 SYNC/共享内容块的简明摘要）：

• **批判性思维：**始终运用批判性与顺序思维；提供可追溯的证明，置信度 >80%。
• **证据：**每项结论始终引用 file:line；绝不可在没有证据时猜测。
• **源码/测试漂移：**源码发生变更时，根据证据判断是测试还是源码有误；绝不可想当然。
• **真实场景还原：**生产环境不可能出现的场景，既不能证明测试通过，也不能据此判定产品失败；在认定间歇性失败为产品缺陷前，区分是测试框架放大效应还是真实问题。
• **防止 AI 出错：**根据证据核验生成内容，追踪下游引用，核验所有受影响的输出，在上下文丢失后重新阅读，并指出歧义。 强制重要注意 只读——运行测试，报告通过/失败数量、失败测试名称和报告路径；绝不要在此处实施修复，到报告为止——原因：修复是 $fix 的工作；把两者混在一起会掩盖真实的测试状态。 强制重要注意 始终通过 tester 子代理运行测试；绝不要直接调用测试命令——原因：子代理会隔离运行过程，并生成本技能要分析的规范摘要报告。 强制重要注意 运行后解析当前有效的目标契约；将验证证据（测试命令、准确的通过/失败数量、报告路径）追加到目标文件的迭代日志，并更新目标满足度矩阵；如果不存在活动目标，则记录 No active goal — evidence reported inline only.；绝不要将原始敏感测试夹具数据复制到目标文件中——原因：目标文件是持久的通过/失败记录，不是秘密存储库。 强制重要注意 对每一项关于失败的说法，都要引用 file:line 证据（置信度 >80% 时采取行动，<80% 时先核实）；绝不要猜测哪个测试失败或失败原因——请阅读报告——原因：猜错失败结论会让用户修复错误的问题。 强制重要注意 间歇性失败属于未裁定，而非产品缺陷——在将其作为缺陷报告前，须根据证据将其归类为：（a）不现实的场景／压缩的参与者节奏，（b）测试框架拓扑放大效应（共享基础设施、多路扇出消费者、套件并行、冷启动），或（c）真实的产品竞争条件；证据不足时，将其报告为未裁定——原因：将测试保真度缺陷报告为产品缺陷，会让团队去修复原本没有问题的代码。 强制重要注意 在断言测试与源代码之间存在关联之前，先 grep 3 个或更多类似测试并匹配本地模式；执行源代码／测试漂移检查——根据证据判断是失败测试在保护预期行为，还是源代码存在问题——原因：错误的假设会把真正的缺陷误判为不稳定测试。 强制重要注意 开始前，使用任务跟踪将工作拆分为小型待办任务；将一项标为 in_progress，并在取得证据后立即完成；添加一项最终审查待办任务，以验证工作质量。 强制重要注意 直接询问用户，以确认路由／决策——绝不要自动决定采用工作流运行还是独立运行。 重要注意 开始前阅读 CLAUDE.md。

反合理化：

逃避说法	反驳
“测试显然通过了，跳过运行吧”	无论如何都要通过 tester 运行——猜测的结论不算结论。报告实际数量。
“我可以直接运行测试命令”	绝不可以——始终委派给 tester 子代理；直接运行会绕过规范报告。
“失败看起来很简单，我来修复吧”	停在报告阶段。修复是 $fix 的工作；本技能严格遵循只读原则。
“没有目标文件，就跳过证据步骤”	记录 No active goal — evidence reported inline only.。绝不要悄悄跳过目标契约。
“我知道哪个测试失败了”	提供 file:line 和报告路径。没有证据 = 不得声称。
“只失败过一次——这就是产品缺陷”	间歇性失败 = 未裁定。先根据证据排除不现实的场景和测试框架放大效应。

[IMPORTANT] 开始前，分析任务规模，并系统地将其拆分成多个小型待办任务——这非常重要。 结束提醒——易于更改是成功指标。 每项发现、测试、重构和抽象都必须回答一个问题：这会让下一次更改变得更便宜，还是更昂贵？ 如果它不能降低未来的更改成本，就拒绝它。耦合、隐藏状态、重复知识和意图不清才是真正的敌人——请明确指出它们。

重要，务必注意 只读——报告通过／失败，绝不要在此处修复（这是 $fix 的工作）。 重要，务必注意 始终通过 tester 子代理运行；每项失败声明都必须引用 file:line 和报告路径（置信度 >80%）。 重要，务必注意目标： 给出准确的只读通过／失败结论，列出精确计数、失败测试名称、报告路径和目标契约证据——让用户了解真实的测试状态，且不进行任何修复。

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

来源：.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/ 中查找。应用共享 AI-SDD，参阅 shared/sdd-artifact-contract.md。阅读 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 任务分组为多个波次，声明波次计划，并在一条消息中启动每个波次的所有子代理——每个波次须等待所有子代理返回；默认只向下分发一层，除非子代理自身定义允许进一步分发。默认顺序执行是缺陷；但对于共享写入目标、依赖其他任务输出的任务、简单的单文件工作、技能或工作流明确规定的顺序，以及需要用户批准的环节，不要并行化。
7. 执行： 按照上下文说明中的 工作流步骤推进与并行阶段 规则推进——由模型驱动；子代理完成与内联调用具有相同的步骤推进效果；并行阶段组必须等待所有成员返回（仅在所有成员都返回后推进，绝不串行执行）

共享 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

• 强制要求 应用 shared/sdd-artifact-contract.md；将可复用的 AI-SDD 内容保存在 .claude 中，并将本地规则放在项目文档中。
• 强制要求 从代码提取规范内容仅可作为参考，须经规范的权威所有者接受后方可采用；任何受支持的 AI 工具都可以使用同步后的上下文执行任务。
• 强制要求 先更新 .claude 源文件，再同步生成的镜像；不要手动编辑 .agents、.codex 或 AGENTS.md。
• 强制要求 如果项目配置、根目录指令文件或必需的参考文档缺失或已过时，应自动通过 $project-init 或更精简的设置流程处理项目专属工作。 [TASK-PLANNING] [MANDATORY] 在执行任何工作流或技能步骤之前，先为所有计划步骤创建/更新任务跟踪，然后在每个步骤开始/完成时保持其同步。

[LESSON-LEARNED-REMINDER] [BLOCKING] 任务规划与持续改进——必须遵守。请勿跳过。

开始前，将工作拆分为小任务（任务跟踪）。添加最后一项任务：“分析 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、业务实体、功能规则。泄漏进来后，代码能够编译并运行，因此会悄无声息地通过审查，同时让“可复用”层与某个使用方耦合。保持共享类型与领域无关；通过子类/组合将领域字段/逻辑下放到使用方。——原因：与某个使用方的领域耦合的层不再可复用。