create-feature

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 开始，再打开与任务相关的文件。

快速摘要

**目标：**搭建一个包含后端（实体、CQRS、控制器）和前端（Angular 组件、服务）的全栈新功能。

工作流：

1. 分析 — 分解需求，确定范围（后端／前端／全栈）
2. 识别 — 确定目标微服务和 Angular 应用／模块
3. 规划 — 梳理实体、命令／查询、端点、组件和 DTO
4. 批准 — 呈现计划，在创建文件前等待用户明确批准
5. 创建 — 按顺序搭建文件：实体 → 应用层 → DTO → 控制器 → 前端

关键规则：

• 继续之前，先等待用户明确批准
• 遵循 CLAUDE.md 和 .github/prompts/ 模板中的平台模式
• 构建顺序：领域 → 应用层 → API → 前端
• 创建后使用 dotnet build 和 nx build 验证

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

M1-M6 合规门禁（任何一项违规都必须停止并返工）

有关阻断性标准，请参阅 .claude/skills/shared/sdd-artifact-contract.md → “AI-SDD Mandates (M1-M6)”。此技能生成的任何需求/规范文本在搭建脚手架之前都必须通过此门禁：

• **M1/M2：**需求和设计说明仅描述业务行为——不得出现框架/产品/语言名称，也不得在叙述中引用类/方法/文件；源标识符应保留在证据载体中（[Source:]、**Evidence**）。
• **M3：**每条功能规则都必须带有逻辑 ID（FR-/BR-/OP-）以及独立的 [Source: namespace/service/id] 抽象锚点证据载体（不得使用物理 file:line/src/ 路径）——两者都要保留。
• **M4/M5：**每项需求只能有一种解释，必须明确命名成功/失败结果，并且仅凭规范文本即可在任何技术栈上重新实现其行为。
• 在说明中引用实现模式时，使用抽象模式（模式 ID 或业务术语，例如“操作处理器”“持久化层”“事件总线”）——不得使用框架/产品名称。具体模式/库名称只能出现在搭建脚手架步骤和证据字段中，绝不能出现在规范叙述里。

如果任何需求/设计文本会违反某项规定，请停止并返工，然后再继续搭建脚手架。

创建一项新功能：$ARGUMENTS

步骤：

1. 分析需求

   • 拆解功能需求
   • 确定范围（仅后端、仅前端或全栈）

2. 确定服务位置

   • 确定后端适用的微服务
   • 确定前端的 Angular 应用/模块

3. 规划实现

   • 所需领域实体
   • CQRS 命令/查询
   • API 端点（控制器）
   • Angular 组件和服务
   • DTO 和验证

4. 使用项目模式

   • 参考 CLAUDE.md 中的模式
   • 使用 .github/prompts/ 模板搭建脚手架：
     • create-cqrs-command.prompt.md
     • create-cqrs-query.prompt.md
     • create-entity-event.prompt.md
     • create-angular-component.prompt.md
     • create-api-service.prompt.md

5. 等待批准

   • 提交实现计划
   • 未经明确批准，不得继续

6. 创建文件（获得批准后） 按以下顺序执行：

   1. 领域实体（.Domain/Entities/）
   2. 应用层（.Application/UseCaseCommands/、.Application/UseCaseQueries/）
   3. 实体 DTO（.Application/EntityDtos/）
   4. API 控制器（.Api/Controllers/）
   5. 前端组件和服务

7. 验证

   • 构建后端：dotnet build
   • 构建前端：nx build <app-name>

---

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

先决条件：执行前必须特别阅读以下内容：

源代码/测试偏差检查。 对于编码、修复、调试、调查、测试或审查工作：当源代码行为发生变化时，检查受影响的单元/集成/E2E 测试，并根据证据判断应修改测试以匹配预期行为，还是源代码变更属于应修复的意外错误。不要为迁移代码编写测试；架构/数据迁移是一次性执行路径，不属于核心应用程序逻辑。 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；项目约定优先于通用默认规则。

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

• 强制要求：协调器在调用子技能前，先展开其阶段；使用 [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：“启用 [最佳匹配工作流]（推荐）”
   • 选项 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] 执行任何工作流或技能步骤之前，先为所有计划步骤创建或更新任务跟踪，然后在每个步骤开始和完成时保持任务跟踪同步。