migration

Codex 兼容性说明：

• 在 Codex 中使用 $skill-name 调用仓库技能；此镜像副本会将旧版 Claude /skill-name 引用改写为 $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 开始，然后只打开与任务相关的文件。

快速概要

目标： 按照项目的平台模式创建数据或架构迁移。

工作流：

1. 分析 — 了解迁移要求和目标数据库
2. 创建 — 遵循平台约定生成迁移
3. 验证 — 运行并验证迁移

关键规则：

• 遵循平台迁移模式（EF 迁移或项目数据迁移执行器，参见 docs/project-reference/backend-patterns-reference.md）
• 创建迁移前始终使用先理解代码协议

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

$ARGUMENTS

⚠️ 务必阅读 references/migration-patterns.md，了解迁移模式。

重要： 创建文件前，先提交迁移设计并等待用户明确批准。

示例

$migration "Add department field to Employee entity"

---

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

前置条件： 执行前务必阅读：

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

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

防止 AI 出错 — 每项任务都应避免以下失败模式：

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

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

1. 首先获取当前任务列表。如果存在匹配的活动父工作流行，设置 nested=true 并记录 parentTaskId；否则作为独立任务运行。
2. 阶段工作开始前，为每个声明的阶段创建一个任务。嵌套时，任务主题前缀为 [N.M] $skill-name — 阶段。
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；项目约定优先于通用默认规则。

• 强制要求：父工作流中的任务行不能替代子阶段跟踪；有嵌套阶段时，展开各阶段并关联父项。

• 强制要求：协调器在调用子技能前，先展开其阶段；使用 [N.M] $skill-name — phase 前缀，并确保同一时间只有一个阶段处于 in_progress 状态。

收尾提醒

• MANDATORY IMPORTANT MUST ATTENTION 开始前必须使用任务跟踪将工作拆分为较小的待办任务
• MANDATORY IMPORTANT MUST ATTENTION 创建新代码前，必须在代码库中搜索 3 个或更多相似模式
• MANDATORY IMPORTANT MUST ATTENTION 每项论断都必须引用 file:line 证据（置信度 >80% 才可采取行动）
• MANDATORY IMPORTANT MUST ATTENTION 添加一项最终审查待办任务，以验证工作质量 MANDATORY IMPORTANT MUST ATTENTION 开始前必须阅读以下文件：
• MANDATORY IMPORTANT MUST ATTENTION 开始前必须阅读 references/migration-patterns.md

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

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

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

[WORKFLOW-EXECUTION-PROTOCOL] [BLOCKING] 工作流执行协议 — MANDATORY IMPORTANT MUST CRITICAL。无论任何原因都不得跳过。

通用可移植性边界： 可复用技能和协议文本应保持项目中立；项目专属约定应从 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："启用 [最佳匹配工作流]（推荐）"
   • 选项 2："启用自定义工作流：[步骤 1 → 步骤 2 → ...]"（附上一句理由）
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] 执行任何工作流或技能步骤之前，先为所有计划步骤创建或更新任务跟踪，然后在每个步骤开始和完成时保持任务跟踪同步。