code-parallel

Codex 兼容性说明：

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

Codex 项目参考文档加载（无钩子）

Codex 不会接收基于 Claude 钩子的文档注入。 进行编码、规划、调试、测试或审查时，请按以下路径明确打开项目文档。

始终阅读：

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

按情境阅读的文档：

• 后端／CQRS／API／领域／实体变更：backend-patterns-reference.md、domain-entities-reference.md、project-structure-reference.md
• 前端／UI／样式／设计系统：frontend-patterns-reference.md、scss-styling-guide.md、design-system/README.md
• 规格／测试用例规划或 TC 映射：feature-docs-reference.md
• 集成测试实现／审查：integration-test-reference.md
• E2E 测试实现／审查：e2e-test-reference.md
• 代码审查／审计工作：code-review-rules.md，以及根据变更文件选择的领域文档

不要盲目阅读所有文档。从 docs-index-reference.md 开始，然后只打开与任务相关的文件。

快速摘要

目标： 使用并行全栈开发人员子 Agent 执行现有计划中的实现阶段。

工作流：

1. 加载 — 阅读实现计划并识别可并行执行的阶段
2. 分派 — 按阶段启动子 Agent，并严格划分文件所有权
3. 合并 — 整合结果并进行验证

关键规则：

• 需要提供现有计划文件作为输入
• 每个子 Agent 负责指定文件；不得跨界编辑
• 顺序执行的阶段必须等待依赖项完成

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

执行计划：$ARGUMENTS

重要： 激活所需技能。确保高效使用 token。可牺牲语法以保持简洁。

工作流

1. 计划分析

• 阅读给定路径中的 plan.md
• 检查： 依赖关系图、执行策略、并行化信息、文件所有权矩阵
• 决策： 如果可并行执行 → 步骤 2A；否则 → 步骤 2B
• 外部记忆： 在分派给并行 Agent 之前，重新阅读计划中引用的任何 .ai/workspace/analysis/ 文件。
• 实现前追踪关卡： 对于 Bug 修复、验证失败、过时／不正确的最终输出、回归或行为变更修复计划，请确认计划／引用的分析包含 Debugger Trace: End -> Start、所有馈入路径、假设矩阵、负责修复的层级以及正向收敛证明。若缺少任何一项，请停止。若内容齐全，则为每个并行工作者分配追踪分支／文件所有权范围，确保馈入路径不会重复或遗漏。

2A. 并行执行

1. 解析执行策略（哪些阶段并行／串行，文件归属）
2. 同时启动多个 fullstack-developer Agent 执行并行阶段
   • 传递：阶段文件路径、环境信息、文件归属边界
3. 等待并行组完成，并确认没有冲突
4. 执行串行阶段（依赖项满足后，每个阶段由一个 Agent 执行）
5. 继续执行步骤 3

2B. 串行执行

遵循 ./.claude/workflows/primary-workflow.md：

1. 由主 Agent 逐步执行
2. 读取 plan.md，逐个阶段实现
3. 使用 project-manager 更新进度
4. 前端工作使用 ui-ux-designer
5. 每个阶段完成后运行类型检查
6. 继续执行步骤 3

3. 测试

• 使用 tester 运行完整测试套件（不得使用伪造数据／模拟对象）
• 如果失败：交由 debugger → 修复 → 重复测试

4. 代码审查

• 使用 code-reviewer 审查所有更改
• 如果有严重问题：修复 → 重新测试

5. 项目管理与文档

• 如果通过：并行使用 project-manager + docs-manager（更新计划、文档、路线图）
• 如果未通过：修复 → 重复

6. 入门指导

• 逐步引导用户（一次问 1 个问题）

7. 最终报告

• 总结、指南、后续步骤
• 询问是否提交（如果是，使用 git-manager）

示例：

• 并行：“阶段 1-3 并行，然后执行阶段 4” → 启动 3 个 Agent → 等待 → 启动 1 个 Agent
• 串行：“阶段 1 → 2 → 3” → 主 Agent 逐个阶段实现

---

后续步骤（独立执行：必须通过直接提问询问用户。若处于工作流中则跳过。）

强制重要注意事项——不得例外： 如果此技能是在工作流之外调用的，你必须通过直接提问向用户提供以下选项。不要因为任务看起来“简单”或“显而易见”而跳过——由用户决定：

• “继续执行完整工作流（推荐）”——我会从当前进度（代码已实现）开始，判断并继续执行最合适的工作流，确保不会跳过审查、测试和文档步骤。
• “$code-simplifier”——简化实现
• “$workflow-review-changes”——提交前审查更改
• “跳过，手动继续”——由用户决定

如果已经处于工作流中，则跳过——工作流会负责安排顺序。

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

• docs/project-reference/domain-entities-reference.md — 领域实体目录、关系、跨服务同步（任务涉及业务实体／模型时阅读）（相关时直接阅读；不要依赖钩子注入的对话文本）

技能变体： $code 的变体——根据计划并行执行阶段。 从终点到起点的调试追踪 — 对于复杂 Bug、验证失败、回归修复、行为变更代码或代码流向不明确的情况，请从观察到的最终状态出发，反向追踪后再提出修复方案。

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

满足以下条件前不得继续： 已指明最终状态 · 已撰写反向追踪 · 已列出所有输入路径 · 已完成假设矩阵 · 已论证负责修复的层级 · 已将正向收敛证明对应到测试。

切勿： 从第一个可疑代码路径开始。将多个生产者合并为一条“流程”。未经证明读取模型就把重复症状视为重复记录。跳过已排除的假设。

源代码／测试偏移检查。 对于编码、修复、调试、调查、测试或审查工作：当源代码行为发生变化时，检查受影响的单元／集成／E2E 测试，并依据证据判断测试应调整以符合预期行为，还是源代码变更本身是需要修复的意外 Bug。不要为迁移代码编写测试；架构／数据迁移是一次性执行路径，而非核心应用逻辑。 AI 错误预防 — 每项任务都要避免的失败模式：

删除前检查下游引用。 删除组件会导致文档和代码连锁过时。移除前，先梳理所有引用文件。 根据实际代码核实 AI 生成的内容。 AI 会幻觉出 API、类名和方法签名。记录或引用前，务必通过 grep 确认其存在。 编辑后追踪完整依赖链。 修改定义时，容易遗漏由此派生的下游变量和使用者。务必追踪完整链路。 验证正确性时追踪所有代码路径。 确认代码存在，不代表它会执行。务必追踪提前退出、错误分支和条件跳过，而不只是正常路径。 调试时，先问“由谁负责？”，再修复。 追查问题出在调用方（数据错误）还是被调用方（处理错误）。在责任所在的层修复，切勿只修补症状出现的位置。 假定现有值是有意设定的——修改前先问“为什么”。 更改任何常量、限制、标志或模式前：阅读注释、检查 git blame、查看周边代码。 核实所有受影响的输出，而不只是第一个。 涉及多个技术栈的更改，需要核实每一项输出。一个检查通过，不代表所有检查都通过。 先全局排查——避免注意力就近偏误。 调查任何故障时，先列出所有前置条件（配置、环境变量、数据库名称、端点、DI 注册、数据前提），再逐一根据证据核实，之后才能提出任何代码层面的假设。 精准修改——执行差异测试。 修复错误：每一处更改都必须能直接追溯到该错误。不要顺手调整格式或改进相邻代码。增强任务：实现改进并明确说明。 编码前明确歧义——不要默默自行选择。 如果请求有多种解释，请逐一列出并估算工作量，然后询问。切勿默认选择处理所有记录、基于文件或更复杂的路径。

嵌套任务展开约定 — 对工作流步骤的调用而言，[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-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-docs-reference.md；架构／新领域相关工作需要 project-structure-reference.md。
3. 阅读所有存在的必需文档；缺少的文档视为不适用并跳过。不要相信对话中的 [Injected: <path>] 等文本能证明当前上下文包含该文档。
4. 开始目标工作前，声明：Reference docs read: ... | Missing/not applicable: ...。

**解除阻塞的条件：**已评估范围、已检查／阅读必需文档、已确认 lessons.md、已注明引用。

批判性思维 — 运用批判性思维和顺序思维。每项断言都必须有可追溯的证据，置信度超过 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. 如果现有模式可用，绝不发明新模式——完全遵循现有模式，或说明偏离原因。——原因：不一致的模式会割裂代码库，让后续每位读者都更难理解

解除阻塞的条件：- [ ] 已阅读目标文件 - [ ] 已 grep 3 个以上模式 - [ ] 已执行图追踪（如果 graph.db 存在）- [ ] 已用证据验证假设

• 必须注意：任何修改前，搜索 3 个以上现有模式并阅读代码。如果 graph.db 存在，则运行图追踪。

必须注意：运用批判性思维——每项断言都必须有可追溯的证据，置信度超过 80% 才能采取行动。防止幻觉：绝不将猜测当作事实。

必须注意：采取措施防止 AI 出错——优先整体排查，在责任层修复，编码前明确指出模糊之处，压缩上下文后重新阅读文件。

• 必须在完成任务跟踪初始化后、开始目标工作／源文件相关工作前，阅读必需的项目参考文档，并注明 Reference docs read: ...。
• 必须始终包含 lessons.md；项目约定优先于通用默认做法。

重要，必须注意：调试器追踪门禁：对于非简单的 Bug／修复／调查／审查工作，从观察到的最终输出入手，沿着 reader -> storage/projection -> writer -> consumer/job -> producer/trigger 的路径反向追踪。修复前列出所有上游路径和假设。**解除阻塞的条件：**必须先完成追踪、假设矩阵、责任修复层的判定以及正向收敛证明。

• 必须 父工作流行不能取代子阶段跟踪；展开各阶段，并在嵌套时关联父项。
• 必须 编排器在调用前预先展开子技能阶段；使用 [N.M] $skill-name — phase 前缀，并严格遵守同一时间仅有一个 in_progress 的规则。

收尾提醒

• 必须 重要 必须 注意 开始前使用任务跟踪，将工作拆分为小型待办任务
• 必须 重要 必须 注意 编写新代码前，在代码库中搜索至少 3 个相似模式
• 必须 重要 必须 注意 每项声明都要引用 file:line 作为证据（置信度 >80% 才采取行动）
• 必须 重要 必须 注意 添加最终审核待办任务，以验证工作质量
• 必须 重要 必须 注意 通过直接向用户提问来验证决策——绝不自动决定 必须 重要 必须 注意 开始前阅读以下文件：

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

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

来源：.claude/hooks/lib/prompt-injections.cjs + .claude/.ck.json

[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，然后打开其中列出的项目参考文档。只要有共享上下文和本地文档，任何受支持的 AI 工具都可以执行。

1. 检测： 将提示词与工作流目录进行匹配
2. 分析： 找出最匹配的工作流，并评估自定义步骤组合是否更合适
3. 提问（必需格式）： 使用直接提问，并采用以下结构；除非用户明确调用了某个工作流／技能，且本地协议将其视为已确认：
   • 问题：“你想启用哪个工作流？”
   • 选项 1：“启用 [BestMatch Workflow]（推荐）”
   • 选项 2：“启用自定义工作流：[step1 → step2 → ...]”（附上一句话说明理由）
4. 启用（确认后）： 标准工作流调用 $workflow-start <workflowId>；自定义步骤则手动按顺序执行
5. 创建任务： 使用任务跟踪，为工作流的所有步骤创建任务
6. 执行： 按顺序遵循每个步骤 [CRITICAL-THINKING-MINDSET] 运用批判性思维和顺序思维。每项声明都需要可追溯的证据，置信度 >80% 才采取行动。 反幻觉原则： 绝不将猜测当作事实——每项声明都要引用来源；坦然承认不确定性；自行检查输出中的错误；独立交叉核对；对自己的判断保持怀疑——没有证据的确信是所有幻觉的根源。 AI 注意力原则（首因—近因效应）： 对于较长的提示词／协议，将最关键的 3 条规则同时放在开头和结尾，确保指令在较长的上下文窗口中仍能得到遵循。 目标驱动执行： 先定义成功标准，持续循环直至验证完成；只有在可观察的检查全部通过后才停止。 测试验证意图： 测试必须保护业务规则／不变量，并在受保护的意图被破坏时失败，而不能只复现当前行为。

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

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

提取经验教训——只分析根本原因，不要只修复症状：

1. 指明失败模式（推理或假设错误），而不是症状——“假设 API 存在，却没有阅读源代码”，而不是“使用了错误的枚举值”。
2. 通用性测试：此失败模式是否适用于 ≥3 种情境或代码库？如果不适用，就再抽象一个层次。
3. 将其写成普遍规则——去掉特定于项目的名称、路径和类。确保规则适用于任何代码库。
4. 合并：多个错误若具有相同的失败模式，则合并为一条经验教训。
5. 复发检查：“如果没有此提醒，这种情况会在未来的会话中再次发生吗？”——不会 → 跳过 $learn。
6. 自动修复检查：“$code-review/$code-simplifier/$security/$lint 能否发现此问题？”——能 → 改进审查技能。
7. 两项检查均通过 → 请用户运行 $learn。 [TASK-PLANNING] [MANDATORY] 执行任何工作流或技能步骤之前，先为所有计划步骤创建或更新任务跟踪，然后在每个步骤开始和完成时保持任务跟踪同步。