prioritize

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] 如果任务工具不可用，请创建并维护等效的逐步计划跟踪，并使用相同的状态转换。

快速摘要

目标： 使用 RICE、MoSCoW 或价值-工作量框架，为 3 个或更多待办事项给出有依据的排序，让团队优先处理价值最高的事项；每个排名都必须有分数和与技术无关的理由（价值/工作量/风险/影响）。

摘要： 目的——为 3 个或更多待办事项排序，让团队优先处理价值最高的事项；每个排名 = 分数 + 与技术无关的理由。主要步骤/任务如下，按顺序执行：

• 步骤 1-2 收集并选择——首先要求至少 3 个事项（少于 3 个 → 直接讨论，绝不强行套用框架）；通过决策树选择框架——RICE = 存在量化数据，MoSCoW = 利益相关者对必须/应该/可以做的事项达成一致，价值-工作量 2x2 = 快速决策；不确定时默认使用 RICE。
• 步骤 3 评分——严格应用框架公式（RICE = Reach×Impact×Confidence ÷ Effort，采用固定的 Impact/Confidence 量表，以故事点衡量 Effort）；绝不编造临时分数。
• 步骤 4-5 排序并输出——按降序排列（RICE）/按等级排列（MoSCoW）/按象限排列（价值-工作量）；输出优先级表格，包含分数及“优先执行/后续计划/延期”建议。
• 步骤 6 写回（存在 PBI 文件时为强制要求）——将排名（1-999，升序）+ 优先级标签写回每个 PBI 的 frontmatter；pbi-mockup/feature-presentation 会从中读取优先级。
• 贯穿全程——与技术无关（M1）： 每个排名都必须从价值/工作量/风险/业务影响角度说明理由，绝不依据具名技术栈/框架/模式。平局判断： 接近持平（排名前两位的 RICE 相差在 15% 以内、MoSCoW 同等级重叠、利益相关者意见分歧明显）→ 直接询问用户，并提供 $llm-council 选项；否则结束时不再提示。

工作流：

1. 收集事项——从文件读取或解析内联列表（至少 3 个事项）
2. 选择框架——RICE（量化）、MoSCoW（利益相关者达成一致）、价值-工作量（快速决策）
3. 为每个事项评分——应用框架标准并计算分数
4. 排序并报告——输出优先级表格，附带理由和建议
5. 写回优先级——如果存在 PBI 文件 → 强制要求： 将 rank + priority 标签写回每个 PBI 的 frontmatter
6. 平局判断——接近持平 → 直接询问用户（使用 $llm-council 还是接受结果）；否则结束时不再提示

关键规则：

• 至少需要 3 个事项；少于 3 个应直接讨论
• 不确定时默认使用 RICE；存在歧义时询问用户
• 排序后可选择更新 PBI 文件中的优先级字段
• 与技术无关的理由（M1）： 请参阅 .claude/skills/shared/sdd-artifact-contract.md → “AI-SDD Mandates (M1-M7)”中的阻断性标准。每个排名都必须从价值、工作量、风险和业务影响角度说明理由，而不是依据实现技术。根据 docs/project-reference/spec-principles.md §3，理由文本必须与技术无关：不得出现框架/产品/语言/设计模式名称；工作量可以引用故事点和相对复杂度，但不得提及具名技术栈。

保持审慎。运用批判性思维和顺序思维。每项主张都必须有可追溯的依据和置信度百分比（Idea 应高于 80%）。

待办事项优先级排序

使用数据驱动框架排列待办事项 → 输出带有分数和理由的排序列表。

适用场景

• Sprint 计划需要排列待办事项（至少对 3 个事项排序）
• 利益相关者需要有依据的优先级排序
• 使用客观标准安排功能路线图顺序
• 比较相互竞争的功能或计划

不适用场景

• 少于 3 个事项（直接讨论）
• 创建 PBI 或编写故事——使用 product-owner 或 story
• 制定完整的产品战略——使用 product-owner
• 跟踪项目状态——使用 project-manager

前置条件

• 至少 3 个待办事项的列表（PBI、功能、用户故事）
• 如果事项以文件形式存在：从 team-artifacts/pbis/ 或用户提供的路径读取
• 如果事项以内联方式提供：使用所提供的描述

工作流

1. 收集待排序项目

   • 如果提供了文件路径 -> 从文件中读取项目
   • 如果提供了内联列表 -> 从用户消息中解析项目
   • 如果项目少于 3 个 -> 请用户补充，或建议直接讨论

2. 使用决策树选择框架：

   如果有定量数据（覆盖人数、指标）  -> RICE
   如果需要利益相关方达成一致（必须/应该/可以） -> MoSCoW
   如果需要快速决策（仅 2 个维度）            -> 价值-投入 2x2
   如果用户指定了框架                       -> 使用该框架
   如果不确定                              -> 询问用户，默认使用 RICE
   

3. 使用选定的框架为每个项目评分：

   RICE：

   分数 =（覆盖人数 x 影响力 x 信心度）/ 投入
   
   覆盖人数：每季度受影响的用户数（数字）
   影响力：  0.25（极低）| 0.5（低）| 1（中）| 2（高）| 3（极高）
   信心度：  0.5（低）| 0.8（中）| 1.0（高）
   投入：    故事点数（1、2、3、5、8、13、21）
   

   MoSCoW：

   必须有：   对发布至关重要，不可妥协
   应该有：   重要但非关键，存在变通方案
   可以有：   值得实现，容量允许时纳入
   不会有：   不在本周期范围内
   

   价值-投入 2x2：

   高价值 + 低投入 = 快速见效项（优先处理）
   高价值 + 高投入 = 战略项（谨慎规划）
   低价值 + 低投入 = 填充项（时间允许时处理）
   低价值 + 高投入 = 时间黑洞（避免）
   

4. 对项目排序：RICE 按分数降序排列，MoSCoW 按类别排列，V-E 按象限排列

5. 输出包含分数和理由的优先级列表

6. 如果存在 PBI 文件 -> 必须将优先级写回：将最终优先级写入每个 PBI 的 frontmatter，包括数值型 rank（1-999，升序）和 priority 标签（例如 Must Have / Should Have / Could Have / Won't Have，或框架对应的类别）。存在 PBI 文件时，此项绝不能视为可选：缺少优先级的 PBI 并不完整，下游使用方（pbi-mockup 标题徽章、feature-presentation 范围与待办列表幻灯片）会从 PBI frontmatter 中读取优先级。更新所有已排序的 PBI，而不只是单独的待办列表文件。

输出格式

## Prioritized Backlog

**Framework:** [RICE | MoSCoW | Value-Effort]
**Date:** [YYMMDD]
**Items scored:** [count]

### Rankings

| Rank | Item      | Score | Rationale                                           |
| ---- | --------- | ----- | --------------------------------------------------- |
| 1    | Feature A | 45.0  | High reach (5000), high impact (3), high confidence |
| 2    | Feature B | 12.0  | Medium reach (2000), medium impact, low effort      |
| 3    | Feature C | 2.5   | Low reach, minimal impact, high effort              |

### Recommendations

- **Do first:** [top items]
- **Plan next:** [medium items]
- **Defer:** [low items with reasoning]

示例

示例 1：为 5 个功能进行 RICE 评分

输入：“确定以下项目的优先级：SSO 登录、深色模式、导出为 PDF、电子邮件通知、批量导入”

输出：

排名	功能	覆盖人数	影响力	信心度	投入	RICE
1	电子邮件通知	5000	2	0.8	1	8000
2	SSO 登录	2000	3	0.8	3	1600
3	批量导入	500	2	1.0	1	1000
4	导出为 PDF	1000	1	0.8	2	400
5	深色模式	3000	0.5	0.5	2	375

示例 2：使用 MoSCoW 分类

输入：“为 Q1 发布分类：支付网关、管理仪表板重新设计、API 速率限制、用户头像、审计日志”

输出：

• **必须有：**支付网关（对收入至关重要）、API 速率限制（安全性）
• **应该有：**审计日志（合规要求，可通过手动导出变通）
• **可以有：**管理仪表板重新设计（可提高效率，但当前版本仍可用）
• **不会有：**用户头像（锦上添花，推迟到 Q2）

可选升级：遇到平局时使用 $llm-council

**门控评估：**生成已排序的待办事项列表（按 ## Workflow 步骤的输出）后，检查排序结果：

• 前 2 名的 RICE 评分相差不超过 15% → 触发门控
• 明确出现 MoSCoW 平局（同一 Must/Should/Could 优先级中有 ≥2 个项目，且范围存在实质性重叠）→ 触发门控
• 输入中标记了多方利益相关者意见不一致 → 触发门控
• 以上情况均未出现 → 不触发门控；技能结束，不提示用户

必须注意——触发门控时，你必须直接询问用户并提供以下选项（前导语模式与 architecture-design 的 ## Next Steps 中的“必须注意”部分一致）：

• “升级到 $llm-council（推荐）”——检测到平局或意见不一致。运行由 11 个子 Agent 组成的委员会（5 位顾问 + 5 位审查员 + 1 位主席）。委员会的 Contrarian + Outsider 视角非常适合处理多个 PBI 排序时的平局。成本更低的替代方案：$why-review、$plan-validate（如果平局范围较小且风险属于常规水平，请改用这些方案）。
• “跳过——接受当前排序”——确认存在平局；继续采用当前排序。

如果未触发门控，则优先级决策维持不变；不要提示用户。

相关技能

技能	何时改用
product-owner	完整的产品管理工作流
story	将 PBI 拆分为用户故事
refine	将想法细化为 PBI
project-manager	Sprint/项目状态与跟踪

---

Prompt-Enhance 结束锚点

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

项目协议覆盖层 — 执行此技能之前，先解析叠加在此技能上的任何项目覆盖规则：将此技能名称与项目技能协议索引（默认路径为 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 中匹配到的正文；若正文缺失或格式错误，则报告，绝不重新构造。覆盖层仅可增补（绝不替代此技能自身规则），且只是简报，绝不能提升权限；具体程度相同的覆盖层若相互矛盾，则告知用户。

结束提醒

• **重要：务必注意目标：**通过 RICE／MoSCoW／价值-工作量方法，为 3 项或更多待办事项排出有依据的优先级，让团队优先处理价值最高的事项——每个排名都必须有分数和不依赖技术的理由（价值／工作量／风险／影响）

生效中的协议（此技能所携带的 SYNC／共享区块的简要摘要）：

• **批判性思维：**始终为每项声明追溯 file:line 证据；采取行动的置信度须 >80%；绝不将猜测当作事实。
• **AI 错误预防：**依据证据核验生成内容，追溯下游引用，核验所有受影响的输出，在上下文丢失后重新阅读，并指出模糊之处。
• 重要，必须注意 排序前要求至少 3 个事项；少于 3 个 → 直接讨论，绝不强行套用框架——原因：给 1～2 个事项排序只会徒增形式，无法提供有效信息
• 重要，必须注意 根据决策树选择框架——定量数据用 RICE，利益相关者需对必须/应该/可以做的事项达成一致时用 MoSCoW，需快速决策时用 Value-Effort 2x2；不确定时默认使用 RICE，有歧义时询问用户——原因：让框架与决策类型匹配，才能使排序站得住脚
• 重要，必须注意 输出优先级表（含评分和理由）以及“先做／接下来计划／暂缓”建议——绝不止步于原始评分——原因：可直接使用的输出应包含排序表和行动建议，而不是只有一列数字
• 重要，必须注意 根据 M1，所有理由都必须与技术无关——应以价值／投入／风险／业务影响为依据，绝不能提及具体技术栈／框架／产品／语言／设计模式；投入只能引用故事点和相对复杂度——原因：规范原则 §3 的硬性要求，基于技术名称的理由会把实现细节带入优先级判断
• 重要，必须注意 使用框架的确切公式评分（RICE = Reach×Impact×Confidence ÷ Effort，Impact/Confidence 使用固定量表，Effort 使用故事点），然后按降序排列（RICE）／按级别排列（MoSCoW）／按象限排列（V-E）——绝不临时编造评分——原因：可复现的数字才能支撑站得住脚的排序
• 重要，必须注意 出现接近持平的情况时（RICE 前 2 名相差在 15% 以内、MoSCoW 同级重叠、存在已标记的利益相关者分歧），必须触发关卡——直接询问用户是升级至 $llm-council，还是接受当前排序；若未触发关卡，结束时不要提示用户——原因：如何打破平局由用户判断，但明显胜出的情况无需打断用户
• 重要，必须注意 开始前使用任务跟踪将工作拆分为小型待办任务；将其中一项标记为 in_progress，并在获得证据后立即标记为 completed
• 重要，必须注意 创建新结构前，在代码库／制品中搜索至少 3 个相似模式；复制附近示例前，先评估模式是否适用（约束／范围是否相同）——原因：最接近的示例 ≠ 具备相同的适用前提
• 重要，必须注意 每项判断都引用 file:line 证据（置信度 >80% 才可采取行动，<60% 时绝不可提出建议）；绝不把猜测说成事实
• 重要，必须注意 存在 PBI 文件时，必须将排序结果同步到每个 PBI 的 frontmatter（数值 rank 为 1～999，另含 priority 标签），不可省略——在排序后执行；修改任何优先级字段前，先 grep 下游使用方——原因：下游使用方（pbi-mockup 页眉、feature-presentation 的 Scope & backlog 幻灯片）会读取 PBI frontmatter 中的优先级，过时或缺失的优先级引用会无声地连锁传播
• 重要，必须注意 添加最后一项审查待办任务，以验证工作质量

反合理化：

规避说法	反驳
“只有 2 个条目，直接排序就行”	少于 3 个条目的最低要求 → 直接讨论；框架只会增加繁文缛节，而不会提供更多信号
“我会在理由中引用框架”	根据 M1，保持技术无关性——只能依据价值／工作量／风险进行论证，绝不能提及具体技术栈
“分数差不多，我来选一个”	接近并列时会触发门槛 → 直接询问用户是否选择 $llm-council，绝不能悄悄打破平局
“RICE 感觉合适，不用公式了”	使用固定量表套用 EXACT 公式——有依据的排序需要数字
“待办列表文件里有排序，PBI 不需要”	存在 PBI 文件时，必须将优先级写回每个 PBI 的 frontmatter——mockup 和 presentation 从 PBI 而非待办列表中读取优先级
“我已经了解这些模式了”	提供 file:line 证据——没有证明 = 不搜索

务必注意 采用批判性和顺序性思维——每项主张都需要相应的可追溯证据（关于代码库／代码的主张需提供 file:line；关于研究、产品、内容和文档的主张需提供源 URL 或制品中的章节）；置信度 >80% 才采取行动，<60% 时切勿推荐。防止幻觉：绝不把猜测当作事实，坦诚承认不确定性，独立交叉核验，并对自己的信心保持审慎。

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

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

[IMPORTANT] 开始前，分析任务规模并系统地拆分为许多小型待办任务——这非常重要。

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

批判性思维模式——运用批判性思维和顺序性思维。每项主张都需要可追溯的证明，置信度 >80% 才采取行动。 防止幻觉： 绝不把猜测当作事实——为每项主张引用来源，坦诚承认不确定性，自查输出中的错误，独立交叉核验，并对自己的信心保持审慎——缺乏证据却确信无疑，是一切幻觉的根源。 防止 AI 犯错 — 执行每项任务时都要避免以下失误：

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

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

来源：.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、业务实体、功能规则。泄漏进来后，代码能够编译并运行，因此会悄无声息地通过审查，同时让“可复用”层与某个使用方耦合。保持共享类型与领域无关；通过子类/组合将领域字段/逻辑下放到使用方。——原因：与某个使用方的领域耦合的层不再可复用。