feature-docs

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

快速摘要

[IMPORTANT] 任务跟踪 — 开始前将所有工作拆分为小任务。对于简单任务，询问用户是否跳过。

目标： 生成全面的 17 个章节的业务功能文档，并要求所有测试用例都提供代码证据。

模式：

模式	触发条件	输入	输出
init	不存在 docs/business-features/{Module}/	完整源代码	从头开始编写完整的 17 个章节文档
update	文档存在且代码已更改	Git 差异 / 明确指定的模块	按章节影响范围映射更新
audit	明确指定 --audit 标志或用户请求	源代码 + 现有文档	按章节生成过时情况报告

工作流：

1. 检测与收集 — 根据 Git 变更自动检测模块，或使用用户指定的模块；读取现有文档
2. 调查代码 — 使用 grep/glob 遍历代码库，追踪每个测试用例的证据；将其记录为 [Source: namespace/service/id] 抽象锚点（物理 file:line → 来源旁文件）
3. 编写文档 — 严格遵循 17 个章节的结构，存放在 docs/business-features/{Module}/
4. 验证 — 四轮验证系统：证据审计、领域模型、交叉引用、AI 可实现性

关键规则：

• [BLOCKING] 阅读 docs/project-reference/spec-principles.md — 规范质量标准、AI 可实现性标准、技术无关规则（§3 表层范围 + §3.2 禁用的行文标记列表）（在第 3.5 阶段验证前，先阅读第 4 节的完整性检查清单）
• [BLOCKING] 每个测试用例都必须有可验证的代码证据（FilePath:LineNumber），无一例外
• 输出必须严格包含与主模板一致的 17 个章节
• 修改文档时，始终更新 CHANGELOG.md 和版本历史（第 17 节）
• 第 15 节测试用例：IntegrationTest 字段是证据载体（实现标识符应放在此处，例如 **Evidence**）→ IntegrationTest: Orders/OrderCommandIntegrationTests.cs::{MethodName}。测试用例中的行为描述必须保持技术无关（spec-principles.md §3）；测试路径只能放在此证据字段中。尚无测试 → Status: Untested
• 确保每个 TC-{FEATURE}-{NNN} 都在集成测试中包含 [Trait("TestSpec", "TC-{FEATURE}-{NNN}")]。缺失时 → Status: Untested
• 第三轮验证发现的问题超过 5 个 → 停止并重新运行验证

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

M1-M6 合规检查清单（阻断性 — 任何违规都会导致文档不合格）

阻断性标准见 .claude/skills/shared/sdd-artifact-contract.md →“AI-SDD Mandates (M1-M6)”。输出前，每份功能文档都必须满足以下所有要求；任何违规都会导致文档不合格并必须返工：

• M1 — 与技术栈无关的正文： §1-14 的叙述、标题、表格和术语表仅描述业务能力。正文中不得出现框架、产品、语言、持久化、消息传递、身份验证相关名称，也不得出现项目内部的框架类型名称（禁用词列表：spec-principles.md §3.2）。这些术语仅允许出现在证据载体（**Evidence**、IntegrationTest、[Source:]）、YAML frontmatter 和 ```mermaid ``` 代码块中。
• M2 — 正文中不得包含源代码： 正文中不得出现类名、方法名、文件路径或命名空间。使用业务操作名称；源代码标识符只能放在证据载体中。
• M3 — 逻辑 ID 优先的可追溯性： 每个 FR / BR / 操作都必须带有逻辑 ID（FR-/BR-/OP-/TC-），作为主要脉络，并附带单独的 [Source: namespace/service/id] 可跨技术栈移植的抽象锚点证据载体（不得使用物理 file:line / src/ 路径——这些仅放在来源旁注文件中；分类法见 docs/specs/MIGRATION.md）。在规则陈述中保留逻辑 ID；叙述中不放来源链接——不得移除 [Source:]。
• M4 — 可由 AI 实现： 每项需求都必须只有一种有效解释，具有可观察的成功 / 失败结果，并明确列出失败模式——不得使用“妥善处理”之类含糊表述。
• M5 — 从零重建： 对代码库一无所知的团队，仅凭文档就能在任何技术栈上重新实现相同的业务行为。

项目模式发现

实施前，搜索代码库以查找项目特定模式：

• 搜索：business-features、detailed-features、feature-docs-template
• 查找：现有功能文档文件夹、17 节模板

[BLOCKING] 阅读 feature-docs-reference.md，了解项目特定模式。若未找到，请通过搜索进行发现。

功能文档生成与验证

按照项目约定生成功能文档。

黄金标准： 搜索现有功能文档：find docs/business-features -name "README.*.md" -type f | head -5

模板： docs/templates/detailed-feature-docs-template.md

---

[CRITICAL] 强制性代码证据规则

每个测试用例都必须有可验证的代码证据——不可妥协。

证据格式

证据是可跨技术栈移植的抽象锚点——不得使用提供方的 file:line、.cs 或 src/ 路径：

**Evidence**: `[Source: {namespace}/{service}/{id}]`

Namespace ∈ operation | event | component | schema | requirement | rule | constraint | test。Service = 所属模块（小写）。Id = 去掉代码后缀的工件概念。物理坐标只能通过来源旁注文件还原。完整约定见 docs/specs/MIGRATION.md。

有效与无效证据

有效	无效
[Source: operation/orders/CreateOrder]	ErrorMessage.cs:83（物理 file:line）
[Source: component/orders/Order]	{namespace}/{service}/{id}（模板）
[Source: event/accounts/AccountUserSaved]	“基于 CQRS 模式”（含糊）

仅限载体字段： 抽象锚点（以及 IntegrationTest 测试链接）只能出现在 **Evidence** / IntegrationTest 字段中——不得出现在测试用例的行为描述中；行为描述应与技术栈无关（spec-principles.md §3）。IntegrationTest 是唯一允许保留物理 {TestFile}::{MethodName} 链接的例外（用于运维 QA 衔接；见 tc-format.md）。

---

输出结构

所有文档都必须放在正确的文件夹结构中：

docs/
├── BUSINESS-FEATURES.md              # Master index (UPDATE if new module)
├── templates/
│   └── detailed-feature-docs-template.md  # MASTER TEMPLATE
└── business-features/
    ├── {Module}/                     # One folder per service/module in your project
    │   ├── README.md                 # Complete module documentation
    │   ├── INDEX.md                  # Navigation hub
    │   ├── API-REFERENCE.md          # Endpoint documentation
    │   ├── TROUBLESHOOTING.md        # Issue resolution guide
    │   └── detailed-features/
    │       └── README.{FeatureName}.md     # Comprehensive (17-section, max 1200 lines)
    └── ...

模块映射

搜索代码库以发现模块与文件夹的映射关系：

# Find all service directories
ls -d src/Services/*/

# Find all existing feature doc modules
ls -d docs/business-features/*/

将每个模块代码映射到其文件夹名称和服务路径。示例模式：

模块代码	文件夹名称	服务路径
{Module1}	{Module1}	src/Services/{Module1}/
{Module2}	{Module2}	src/Services/{Module2}/

---

强制要求的 17 个章节结构

所有功能文档 MUST 按以下章节顺序编写：

#	章节	受众
1	标题 + 元数据（YAML frontmatter）	所有人
2	术语表	所有人
3	执行摘要	PO、BA
4	业务需求	BA、开发人员
5	领域模型	开发人员、架构师
6	业务规则	BA、开发人员
7	流程	BA、开发人员
8	命令与操作	开发人员
9	事件与后台作业	开发人员
10	UI 页面	开发人员、UX
11	API 参考（简化版）	开发人员
12	跨服务集成	架构师
13	安全与权限	开发人员、架构师
14	性能考量	开发人员、架构师
15	测试规范	QA、开发人员
16	故障排除	开发人员、QA
17	版本历史	所有人

利益相关者快速导航

受众	章节
产品负责人	执行摘要、业务需求
业务分析师	业务需求、业务规则、流程、领域模型
开发人员	领域模型、命令与操作、API 参考、事件、UI 页面
技术架构师	领域模型、跨服务集成、安全、性能
QA/QC	测试规范、业务规则、故障排除
UX 设计师	UI 页面、流程

---

步骤 0 — 模式检测（必须首先执行）

在进行任何提取之前，检测模式：

1. 检查 docs/business-features/{Module}/ 是否存在（或是否有 --audit 标志）
2. 如果自动检测到模块，检查整个 docs/business-features/ 目录树
3. 在继续操作之前，直接向用户询问并告知检测到的模式——绝不自动开始

模式路由：

条件	模式	下一步
未找到 docs/business-features/{Module}/	INIT	→ 模式：INIT
docs/business-features/{Module}/ 存在	UPDATE	→ 阶段 1.5（现有文档更新模式）
有 --audit 标志或用户请求审计	AUDIT	→ 模式：AUDIT

INIT 模式的规模门槛（仅限工作流上下文）： 如果调用方是 workflow-spec-driven-dev 且 module_count ≥ 4 → MUST 在一条消息中启动子 Agent（每个模块一个）。当 feature-docs 作为独立工具调用且仅针对单个模块时，不适用规模门槛——单模块初始化始终在单个会话中完成。

---

模式：INIT（新功能文档）— 从零开始完整提取

如果不存在文档，则在整理成 17 个章节的文档之前，先进行类似 spec-discovery 的提取。

步骤 1-INIT.1：全局侦察

在详细阅读任何文件之前，先绘制模块代码库的地图：

1. 运行 git ls-files src/Services/{Module}/（或相关路径）——获取完整文件清单
2. 识别：实体文件、命令文件、查询文件、控制器文件、事件处理器文件、前端组件
3. 构建模块提取地图：
   • 实体层：列出所有实体/聚合文件
   • 验证层：列出所有验证器文件
   • 命令层：列出所有命令处理器文件
   • API 层：列出所有控制器文件
   • 事件层：列出所有事件处理器 + 总线消费者文件
   • 前端：列出所有组件 + 服务 + 存储文件

步骤 1-INIT.1.5：用例枚举 [阻塞——必须在步骤 2 / 阶段 A 之前完成]

目标： 在规划提取任务之前统计所有操作。该数字是第 15 节 TC 数量的最低值。

写入端入口：

# CQRS command handlers
grep -r "ICommandHandler\|CommandHandler\b" src/Services/{Module}/ --include="*.cs" -l
# REST/MVC mutating endpoints
grep -r "\[HttpPost\]\|\[HttpPut\]\|\[HttpPatch\]\|\[HttpDelete\]" src/Services/{Module}/ --include="*.cs" -l
# Event consumers / background jobs
grep -r "IConsumer\|EventHandler\|IMessageConsumer\|BackgroundJob\|IHostedService" src/Services/{Module}/ --include="*.cs" -l

读取端入口：

# CQRS query handlers
grep -r "IQueryHandler\|QueryHandler\b" src/Services/{Module}/ --include="*.cs" -l
# REST/MVC GET endpoints
grep -r "\[HttpGet\]" src/Services/{Module}/ --include="*.cs" -l

参与者/角色发现（为阶段 E + 第 13 节提供信息）：

# Permission attributes and role guards
grep -r "\[Authorize\]\|RequirePermission\|IsInRole\|HasPermission" src/Services/{Module}/ --include="*.cs" -l
# Role/permission enums
grep -r "enum.*Role\|enum.*Permission" src/Services/{Module}/ --include="*.cs" -n | head -20
# Frontend route guards (if applicable)
grep -r "canActivate\|AuthGuard\|RoleGuard\|PermissionGuard" src/{frontend-root}/ --include="*.ts" -l 2>/dev/null | grep -i {module} | head -5

用例清单输出：

层级	写入操作数 (N)	读取操作数 (M)	事件驱动操作数 (K)	后台操作数 (J)	总计	参与者角色
{Module}	N	M	K	J	N+M+K+J	[从 grep 获取的角色]

[关卡——阶段 A 提取之前的阻塞项]：

• 总计 (N+M+K+J) = 第 15 节 TC 数量的最低值
• 如果总计 ≥ 20：必须将提取拆分为多个操作组（每组 ≤20 个操作）。开始任何提取阶段之前，为每个组创建一个任务跟踪项。
• 参与者目录必须至少列出 1 个角色；否则标记为“未找到角色——请手动核实授权属性”

步骤 1-INIT.2：领域模型提取（阶段 A）

对于实体层中的每个实体：

1. 阅读实体文件
2. 提取：名称、用途（1 句话）、属性（名称、是否必填、约束、业务含义）、生命周期状态、不变量
3. 识别关系：FK 字段、导航属性、集合字段 → 基数
4. 使用 [Source: component/{service}/{Entity}] 抽象锚点编写实体说明（物理坐标 → 来源旁注）
5. 收集所有实体以生成 ERD

ERD 生成（所有实体提取完成后必须执行）：

• 生成 Mermaid erDiagram 块
• 仅使用与技术无关的类型：string、number、boolean、date、list、map
• 使用 %% [AGGREGATE: ...] 标记聚合根
• 跨模块引用使用存根：%% [CROSS-REF: module-name]
• 将 ERD 保存到 .ai/workspace/analysis/{Module}-erd.md，供第 5 节使用

步骤 1-INIT.3：业务规则提取（阶段 B）

对于验证层中的每个验证器/命令处理器：

1. 阅读文件并提取验证规则（字段 → 规则 → 错误条件 → 错误消息）
2. 提取授权规则（操作 → 谁有权执行 → 条件）
3. 如果实体具有生命周期状态，则提取状态机转换
4. 为每组规则使用 [Source: rule/{service}/{RuleName}] 抽象锚点编写规则

步骤 1-INIT.4：提取 API 合约（阶段 C）

对于每个应用层入口，按以下优先级顺序读取：

1. CQRS 命令处理器（UseCaseCommands/）——每个处理器类对应一条记录。提取：处理器名称 → 业务操作名称（与技术无关）、命令字段、引用的验证规则、输出类型。
2. CQRS 查询处理器（UseCaseQueries/）——每个处理器类对应一条记录。提取：操作名称、筛选参数、返回结构、分页信息。
3. 事件消费者（UseCaseEvents/）——每个消费者对应一条记录。提取：消费的事件、产生的副作用、输出状态变化。
4. 后台作业——每个作业对应一条记录。提取：计划/触发条件、执行的操作、副作用。
5. REST 控制器——仅作补充（HTTP 适配层）。提取：上文处理器未涵盖的操作的 HTTP 方法 + 路径 + 是否需要身份验证 + DTO 结构。

仅使用业务语言编写操作说明——不要使用 C# 类型名称或类名。每条记录使用抽象锚点 [Source: operation/{service}/{Operation}]。

必须：用例清单（步骤 1-INIT.1.5）中的每个操作都必须在阶段 C 中恰好对应一条记录。 阶段 C 完成后：统计记录数。如果记录数 < 清单中的总计数 → 在阶段 D 之前创建补充任务。

步骤 1-INIT.4.5：跨服务范围的图追踪（第 12 节之前）

在提取事件和跨服务集成之前，运行图分析以发现所有消费者和生产者：

# Trace cross-service flow from the primary entity file
python .claude/scripts/code_graph trace src/Services/{Module}/{Module}.Domain/Entities/{PrimaryEntity}.cs --direction both --json

# Find all files connected to the primary service entry point
python .claude/scripts/code_graph connections src/Services/{Module}/{Module}.Service/Controllers/{PrimaryController}.cs --json

如果 .code-graph/graph.db 不可用： 改为搜索 IBusMessage、IConsumer、[IntegrationEvent] 模式：

grep -rn "IBusMessage\|IConsumer\|IntegrationEvent" src/Services/{Module}/ --include="*.cs"

使用图分析输出列举：出站事件（生产）、入站事件（消费）、跨服务命令。将所有发现纳入第 12 节和第 9 节。

步骤 1-INIT.5：提取事件与作业（阶段 D）

针对每个事件处理器和总线消费者：

1. 提取：事件名称、触发条件、负载字段、顺序保证
2. 后台作业：计划、目的、副作用、中止条件
3. 使用抽象锚点 [Source: event/{service}/{Event}]（后台作业使用 operation/{service}/{Job}）

步骤 1-INIT.6：综合用户旅程（阶段 E）

来源——以下三项都必须使用：

1. 后端操作（来自阶段 C）：每个写入操作 → 一个用户故事；每个带筛选参数的读取/查询 → 一个搜索/列表/查看故事
2. UI 路由和屏幕：前端模块中的每个独立路由/页面 = 一个屏幕故事
3. 参与者目录（来自步骤 1-INIT.1.5）：每个参与者都必须出现在至少一个故事中

用户故事格式（每个故事都必须遵循）：

"作为 {参与者目录中的参与者}，我想要 {动作动词 + 对象}，以便 {业务结果}。"

故事模板：

## Journey: {JourneyName}

- **User Story:** As a {actor}, I want to {action}, so that {outcome}.
- **Actor:** {exact role name from actor catalog}
- **Operation Type:** write | read | event-driven | background | ui-screen
- **Trigger:** {what starts this journey}
- **Preconditions:** {what must already exist}
- **Happy Path:** 1. {Step 1} ...
- **Alternative Paths:** {Condition A} → {what happens}
- **Outcome:** {what actor achieves}
- **Acceptance Criteria:**
    - GIVEN {precondition} WHEN {action} THEN {outcome}
      [Source: operation/{service}/{Operation}]

阶段 E 完整性检查清单（继续步骤 1-INIT.7 之前的阻断条件）：

• 旅程数量 ≥ 阶段 C 记录数（用例清单中的总计数）
• 参与者目录中的每个参与者都出现在至少一个旅程中
• 发现的每个 UI 路由都至少有一个屏幕故事
• 每个带筛选参数的 GET/查询都有一个搜索/列表/查看故事
• 每个故事都使用「作为 / 我想要 / 以便」格式
• 每个故事都有抽象锚点 [Source: operation/{service}/{Operation}]

步骤 1-INIT.7：转换为 17 节格式

提取完成后，将提取的内容整理为 17 节结构：

提取的阶段	目标章节
阶段 A 实体	第 5 节（领域模型）——附 ERD + [Source: component/{service}/{Entity}]
阶段 B 规则	第 6 节（业务规则）+ 第 4 节（业务需求 FR-XX）
阶段 C 操作	第 8 节（命令）+ 第 11 节（API 参考）
阶段 D 事件	第 9 节（事件与后台作业）+ 第 12 节（跨服务）
阶段 E 流程	第 10 节（UI 页面）+ 第 15 节（含 TC-XX ID 的测试规范）
身份验证规则	第 13 节（安全与权限）

[BLOCKING] 第 15 节就绪门槛——编写第 15 节之前，请确认基础章节已完成：

章节	编写 TC 是否必需？	检查项
S4 业务需求	是——TC 映射到 FR-XX	至少有 1 项 FR-XX
S6 业务规则	是——TC 引用 BR-XX	至少有 1 项含错误条件的 BR-XX
S8 命令	是——TC 需要操作目标	至少有 1 项命令
S13 安全	是——TC 必须包含身份验证检查	权限矩阵已提供

如果其中 2 个或更多章节缺失或为空，请直接询问用户是要使用占位 TC 继续，还是暂停并先完成基础章节。

[BLOCKING] 第 15 节数量门槛（在就绪门槛之后运行）：

编写任何 TC 之前，请确认计划的 TC 数量覆盖 Use Case Inventory：

检查项	要求	计划数量	状态
CRUD/核心 TC	≥ 清单中的写入操作数（N）	{n}	PASS/FAIL
读取/查看 TC	≥ 带筛选条件的读取操作数（M）	{n}	PASS/FAIL
事件/后台 TC	≥ 事件驱动数（K）+ 后台数（J）	{n}	PASS/FAIL
权限 TC	≥ 参与者数量 × 2	{n}	PASS/FAIL
总计	≥ 总数（N+M+K+J）	{n}	PASS/FAIL

如果任意一行 FAIL，或计划数量小于总数：将 TC 生成拆分为按操作分组的批次（每项任务跟踪 ≤20 个操作）。在规划好所有批次任务且总数 ≥ 总数之前，不要编写 TC。

[REQUIRED] TC ID 冲突预防：

grep -n "TC-{FEATURE}-" docs/business-features/{Module}/detailed-features/README.*.md 2>/dev/null | sort | tail -10

分配新 ID 前，请记录现有的最高 ID。范围规则请参阅 .claude/skills/shared/tc-format.md — 基于十位区间的编号规则。

[REQUIRED] 文档网络步骤（INIT 模式 — INSERT；UPDATE 模式 — VERIFY）：

INIT 模式： 完成 INIT 前，在功能文档中插入 ## Related Documentation 部分。 将其放在 frontmatter 标题之后（第 1 节内容之前）。 注意：此步骤在 INIT 工作流的后期触发——保存前，需追溯性地将其插入文档顶部。

UPDATE 模式： 如果此部分已存在，请勿重新插入——而是验证链接是否为最新 （路径是否符合当前模块结构，是否存在失效引用）。如果旧文档缺少此部分，请立即添加。

## Related Documentation

| Type              | Path                                                         | Description                                              |
| ----------------- | ------------------------------------------------------------ | -------------------------------------------------------- |
| Engineering Spec  | `docs/specs/{app-bucket}/{system-name}/`                     | 技术栈无关的规范文档集（通过 $spec-discovery 创建）   |
| QA Test Dashboard | `docs/specs/README.md` + `docs/specs/PRIORITY-INDEX.md`      | 所有 TC、执行状态、集成测试可追溯性 |
| Integration Tests | `src/Services/{ServiceName}/{ServiceName}.IntegrationTests/` | 测试代码；通过 [Trait("TestSpec", "TC-...")] 关联       |
| Parent Feature    | _(if sub-feature)_                                           |                                                          |
| Child Features    | _(if this doc is a parent)_                                  |                                                          |

根据当前模块上下文填写 {app-bucket}、{system-name}、{Module} 和 {ServiceName}。 对于尚不存在的路径，请使用 (not yet created)——它们可作为导航意图标记。

原因： 此部分是所有使用者浏览此功能领域的导航中心。缺少此部分时， 每个 AI 会话都必须扫描整个文档树，才能找到相关资料。

---

模式：AUDIT（过时检测）

触发审计模式时：

1. 读取 docs/business-features/{Module}/detailed-features/README.{Feature}.md frontmatter 中的 last_updated

2. 运行 git log --since="{last_updated}" --name-only -- src/Services/{Module}/

3. 如果发现有文件变更 → 使用 Phase 1.5 影响映射表标记相关章节

4. 输出 docs/business-features/{Module}/AUDIT-{date}.md：

   # 功能文档审计 — {date}
   
   ## {FeatureName}
   
   | 章节                       | 状态       | 已变更的源文件                  | 操作                |
   | -------------------------- | ---------- | ------------------------------- | ------------------- |
   | 第 5 节（领域模型）        | ⚠️ 过时   | EntityX.cs（于 2026-04-18 变更） | 重新提取实体        |
   | 第 6 节（业务规则）        | ✅ 当前 | —                               | —                   |
   

---

第 1 阶段：模块检测与上下文收集

步骤 1.0：根据 Git 更改自动检测模块（默认）

未指定模块时，根据 Git 更改自动检测：

1. git diff --name-only HEAD（已暂存 + 未暂存）；如果没有结果 → git diff --name-only HEAD~1
2. 使用模块映射表提取不重复的模块名称
3. 对每个模块：检查 docs/business-features/{Module}/ 是否存在
4. 文档存在 → 阶段 1.5（更新模式）；不存在 → 跳过（未经用户请求，不创建草稿）
5. 仅更改了 .claude/、docs/、配置文件 → 报告“No business feature docs impacted”并退出

路径到模块的检测规则：

搜索代码库以构建路径到模块的映射。常见模式：

更改的文件路径模式	检测到的模块
src/Services/{Module}/**	{Module}
{frontend-apps-dir}/{app-name}/**	{Module}（将应用名称映射到模块）
{frontend-libs-dir}/{domain-lib}/src/{feature}/**	{Module}（将功能映射到模块）

检查以下内容，构建项目专属映射：

ls -d src/Services/*/
ls -d {frontend-apps-dir}/*/

步骤 1.1：确定目标模块

模块来源优先级：（1）用户指定 →（2）领域隐含（通过 grep 验证）→（3）根据 git diff 自动检测（步骤 1.0）

步骤 1.2：阅读现有文档

1. docs/BUSINESS-FEATURES.md（主索引）
2. docs/business-features/{Module}/INDEX.md（如果存在）
3. docs/business-features/{Module}/README.md（如果存在）

步骤 1.3：代码库分析

从源代码中 grep 证据：

• 实体：{Module}.Domain/Entities/
• 命令：{Module}.Application/UseCaseCommands/
• 查询：{Module}.Application/UseCaseQueries/
• 控制器：{Module}.Service/Controllers/
• 前端：{frontend-apps-dir}/{app}/ 或 {frontend-libs-dir}/{lib}/

步骤 1.4：功能分析

在 .ai/workspace/analysis/[feature-name].md 中构建知识模型。查找：实体/枚举、命令/查询/事件/作业、控制器/DTO、前端组件、跨服务总线消息。

---

阶段 1.5：更新模式（更新现有文档时）

更新现有功能文档（而非从头创建）时：

步骤 1.5.0：同步工程规范（如果 docs/specs/{app-bucket}/{system-name}/ 存在）

1. 检查 docs/specs/{app-bucket}/{system-name}/ 是否存在
2. 如果存在：记录 git diff 中与规范注册表重叠的模块
3. 标记输出：“Engineering spec sync required for modules: {list}”——不要直接触发 spec-discovery（职责分离）

步骤 1.5.1：差异分析

1. 确定来源（git diff、分支、提交）
2. 对更改分类：实体、命令、查询、前端、i18n
3. 将每项更改映射到受影响的章节（见下表）

步骤 1.5.2：章节影响映射

更改类型	受影响的章节
新增实体属性	4（业务需求）、5（领域模型）、11（API 参考）
新增 API 端点	11（API 参考）、13（安全与权限）
新增前端组件	10（UI 页面）
新增筛选器/查询	4（业务需求）、11（API 参考）
任何新增功能	15（测试规范）——必须更新
任何更改	3（执行摘要）、17（版本历史）——始终更新

步骤 1.5.3：强制测试覆盖（第 15 节）

重要：记录任何新功能时，必须更新：

• 第 15 节（测试规范）：为新功能添加测试用例（TC-{FEATURE}-{NNN}）。

[BLOCKING] TC 格式： 使用 .claude/skills/shared/tc-format.md 中的规范格式。绝不能使用简化的扁平 GIVEN/WHEN/THEN 格式——必须使用包含所有必填字段的完整模板（Objective、Preconditions、GWT 步骤、Acceptance Criteria、Test Data、Edge Cases、Evidence、IntegrationTest、Status）。第 15 节仅由 $tdd-spec 负责——feature-docs 仅在 INIT 期间填充。UPDATE 模式下绝不能覆盖现有 TC。

[BLOCKING] 防止 TC ID 冲突： 分配新 TC ID 前，检查现有 ID 中的最大值：

grep -n "TC-{FEATURE}-" docs/business-features/{Module}/detailed-features/README.*.md | sort | tail -5

分配下一个连续 ID。有关范围规则，请参阅 .claude/skills/shared/tc-format.md 中的 Decade-Based Numbering 部分。

未更新第 15 节 = 阻断性质量问题。

步骤 1.5.4：CHANGELOG 条目

始终按照 Keep a Changelog 格式，在 [Unreleased] 下创建/更新 CHANGELOG.md 条目。

---

阶段 2：生成文档

生成至 docs/business-features/{Module}/detailed-features/README.{FeatureName}.md。

关键格式示例

业务需求（FR-XX）：

#### FR-{MOD}-01: {Requirement Title}

| Aspect          | Details                                |
| --------------- | -------------------------------------- |
| **Description** | {What this requirement enables}        |
| **Scope**       | {Who can use / affected entities}      |
| **Evidence**    | `[Source: {namespace}/{service}/{id}]` |

用户故事（US-XX）：

#### US-{MOD}-01: {Story Title}

**As a** {role}
**I want** {goal/desire}
**So that** {benefit/value}

**Acceptance Criteria**:

- [ ] AC-01: {Criterion with evidence reference}
- [ ] AC-02: {Criterion with evidence reference}

**Related Requirements**: FR-{MOD}-01, FR-{MOD}-02
**Evidence**: `[Source: {namespace}/{service}/{id}]`

测试摘要表（强制）：

| Category    | P0 (Critical) | P1 (High) | P2 (Medium) | P3 (Low) |  Total  |
| ----------- | :-----------: | :-------: | :---------: | :------: | :-----: |
| {Category1} |      {N}      |    {N}    |     {N}     |   {N}    |   {N}   |
| **Total**   |    **{N}**    |  **{N}**  |   **{N}**   | **{N}**  | **{N}** |

测试用例格式（TC-XX）：

[BLOCKING] 规范 TC 格式依据： .claude/skills/shared/tc-format.md——完整 TC 模板始终以此为准。以下是功能文档第 15 节要求的最低格式。

#### TC-{FEATURE}-001: {Test Name} [P0]

**Objective:** {One sentence: what behavior this TC verifies}

**Preconditions:**

- {Required system state}

**GIVEN** {initial context}
**WHEN** {action performed}
**THEN** {expected outcome}

**Acceptance Criteria:**

- Success: {observable outcome}
- Failure: {error condition + message}

**Test Data:** `{ "field": "value" }`

**Edge Cases:**

- {Invalid scenario} → {Expected error/behavior}

**Evidence:** `[Source: {namespace}/{service}/{id}]`
**IntegrationTest:** `{TestFile}::{MethodName}` (or `Untested`)
**Status:** Tested | Untested | Planned

故障排除格式：

#### {Issue Title}

**Symptoms**: {Observable problem}

**Causes**:

1. {Cause 1}
2. {Cause 2}

**Resolution**:

- {Step 1}
- {Step 2}

权限矩阵：

| Role  | View | Create | Edit | Delete | Special     |
| ----- | :--: | :----: | :--: | :----: | ----------- |
| Admin |  ✅  |   ✅   |  ✅  |   ✅   | Full access |

领域模型 ERD（第 5 节强制要求）

每份功能文档都必须在第 5 节中包含 Mermaid erDiagram：

erDiagram
    {EntityA} {
        string id PK
        string name
        string status
    }
    {EntityB} {
        string id PK
        string entityAId FK
    }
    {EntityA} ||--o{ {EntityB} : "contains"

ERD 规则（与 spec-discovery 标准相同）：

• 仅使用与技术无关的类型：string、number、boolean、date、list、map
• 不使用 C# 类名或 ORM 类型
• 标记聚合根：%% [AGGREGATE: EntityName]
• 跨模块存根：%% [CROSS-REF: module-name]

ERD 块后必须包含抽象锚点 [Source: component/{service}/{Entity}]。

业务规则（第 6 节）格式：

每组规则都必须包含 [Source: rule/{service}/{RuleName}]：

### BR-{MOD}-01: {Rule Group Name}

| Field/Operation | Rule         | Error Condition | Error Message      |
| --------------- | ------------ | --------------- | ------------------ |
| {field}         | {constraint} | {when violated} | {message constant} |

[Source: rule/{service}/{RuleName}]

---

注意：AI Companion 文件已弃用

不再使用 .ai.md 配套文件。仅输出单个 README.{Feature}.md。模板：docs/templates/detailed-feature-docs-template.md（权威模板）。

关键原则（v4.0）

• 第 1-14 节和第 16 节不得包含代码细节——不得包含文件路径、C# 类型或 API 结构
• 证据仅放在第 15 节——使用 [Source: namespace/service/id] 抽象锚点引用
• 命令必须交叉引用 BR-XXX——每条命令都要列出已验证的业务规则
• 每份文档最多 1500 行（目标为 500-800 行）。接近上限时，拆分为子功能：
  1. 创建 README.{FeatureName}-Part1.md 和 README.{FeatureName}-Part2.md
  2. 在 Part1 中保留领域模型（S5）和业务规则（S6）；次要操作/边界情况移至 Part2
  3. 保持 TC ID 连续性——两部分共用 TC-{FEATURE}- 前缀；绝不能重新编号
  4. 添加交叉引用：每部分都在标题中包含 "另请参阅： README.{FeatureName}-Part{N}.md"
  5. 更新 INDEX.md 和 BUSINESS-FEATURES.md，使其链接到两部分
• 必须包含 YAML frontmatter：module、service、feature_code、entities[]、status、last_updated
• 审计模式生成 AUDIT-{date}.md——绝不修改现有文档
• Init 模式使用 spec-discovery 提取阶段——写入前必须从源文件中读取所有实体、规则和 API

第 3 阶段：更新主索引

创建或更新模块文档后，更新 docs/BUSINESS-FEATURES.md：

1. 阅读当前内容
2. 确认模块已列在“Detailed Module Documentation”表格中
3. 如缺少链接，则添加：

   | **{Module}** | [Description] | [View Details](./business-features/{Module}/README.md) |
   

步骤 3.5：更新模块 CHANGELOG.md

每次运行 feature-docs（初始化或更新）后，在 docs/business-features/{Module}/CHANGELOG.md 中追加：

## [Unreleased] — {date}

### Updated

- {FeatureName}: updated sections {list of section numbers} — triggered by {git ref or user request}
- Reason: {brief description of change}

如果 docs/business-features/{Module}/CHANGELOG.md 不存在，则创建该文件。

---

防幻觉协议

文档准确性检查点

编写文档之前，请确认：

• 是否已阅读实现该功能的实际代码？
• 行号引用是否准确且为最新？
• 是否有可用的代码片段作为证据？

测试用例证据验证

每个测试用例都必须：

1. 阅读证据文件中所标行号处的内容
2. 验证该行代码是否支持测试断言
3. 检查边界情况：在 ErrorMessage.cs 中查找错误常量
4. 如果行号有误，立即修正

---

第 3.5 阶段：验证（4 轮）

第一轮——测试用例证据审查（第 15 节）

每个测试用例都必须：

1. 阅读证据文件中所标行号处的内容
2. 验证该行代码是否支持测试断言？
3. 检查边界情况：在 ErrorMessage.cs 中查找错误常量
4. 如果行号有误，立即修正

第二轮——领域模型验证

• 阅读第 5 节中引用的每个实体文件
• 验证属性名称和业务含义是否准确（不要使用实现类型——使用业务含义列）
• 检查枚举值是否存在于实际源代码中
• 删除源代码中不存在的已记录属性

第三轮——交叉引用审查

• 17 个章节均存在且顺序正确
• 测试摘要中的数量与第 15 节中的实际 TC 数量一致
• 所有内部链接均有效
• 不留模板占位符（{namespace}、{service}、{id}）
• ErrorMessage 常量与边界情况消息一致
• YAML frontmatter 存在且完整

关键：任何一轮发现幻觉内容 → 重新调查并修正后再完成。

第四轮——AI 可实现性检查

标记需要依赖实现假设的项目：

• S4（功能需求）： 每个 FR-XX 都需要明确的成功和失败结果。FR 含糊 → 不完整。
• S6（业务规则）： 每个 BR-XX 都需要包含：触发条件、规则内容、错误消息、[Source: rule/{service}/{RuleName}]。缺少字段 → 标记。
• S8（命令/操作）： 每个命令至少引用 1 个已验证的 BR-XX。未引用 BR 的命令 → 标记。
• S13（授权）： 权限矩阵中需明确填写角色 × 操作 × 条件单元格。单元格为空 → 标记。
• 具体示例： 每个核心操作至少提供 1 个示例（输入 + 预期输出）。只有抽象描述 → 低。

如果不完整项目超过 3 项 → 停止，并直接询问用户以提供缺口列表，再继续完成。

参考：docs/project-reference/spec-principles.md 第 4 节（AI 可实现性检查清单）。

M5 — 从零重建测试

关于阻断性标准，请参阅 .claude/skills/shared/sdd-artifact-contract.md → “AI-SDD Mandates (M1-M6)”。完成前，请针对整份文档回答：

一个对该代码库毫无了解的团队，能否仅凭 §1-14 的正文，在任何技术栈上重新实现完全相同的业务行为——并去除所有 [Source:] 证据？

如果答案为否，且原因是正文依赖框架/产品/语言措辞、类或文件引用，或单一隐藏解读 → 文档未通过 M5（且很可能也未通过 M1/M2/M4）。在标记为完成之前，将有问题的章节改写为与技术无关、解读唯一的业务行为。

---

质量检查清单

指令合规性（M1-M6）

关于阻断性标准，请参阅 .claude/skills/shared/sdd-artifact-contract.md → “AI-SDD Mandates (M1-M6)”。

• 指令质量检查：§1-14 的正文中不含任何禁用技术术语（spec-principles.md §3.2），且在证据载体（M1/M2）之外不含任何代码标识符（类／方法名称、文件路径、命名空间）
• 每个 FR / BR / 操作都带有逻辑 ID（FR-/BR-/OP-/TC-）以及单独的 [Source: namespace/service/id] 抽象锚点证据载体（绝不使用物理 file:line／src/）——保留 [Source:]，不得并入正文（M3）
• 每项需求都可测试，且只有一种解释，并明确列出成功／失败结果（M4）
• 从头重建测试的回答为 YES——仅凭 §1-14 的正文，即可在任意技术栈上重新实现本文档（M5）

结构

• 文档置于正确的文件夹结构中
• README.md 遵循模板格式（17 个章节）
• 存在包含 module、service、feature_code、entities[] 的 YAML frontmatter
• 已创建包含导航链接的 INDEX.md
• 已更新主索引（BUSINESS-FEATURES.md）
• 存在利益相关者导航表
• 已在 [Unreleased] 下的条目中更新 CHANGELOG.md
• 文档总长度 最多 1500 行（若接近上限，请遵循关键原则中的拆分流程）
• 第 1-14、16 节中 没有代码细节（没有文件路径、C# 类型）
• 命令引用其所验证的 BR-XXX ID

测试用例证据（强制要求）

• 每个测试用例都包含 Evidence 字段，格式为 [Source: namespace/service/id] 的抽象锚点（绝不使用 file:line）
• 没有遗留模板占位符（{namespace}、{service}、{id}）
• 已通过阅读实际源文件验证行号
• 边界情况错误与 ErrorMessage.cs 中的常量一致
• 测试摘要中的计数与第 15 节的实际测试用例数一致

防止幻觉

• 已根据源代码验证所有实体属性
• 已根据实际枚举定义验证所有枚举值
• 没有虚构的方法、属性或模型
• 所有代码片段均复制自实际文件

第 5 节（领域模型）

• 存在包含所有实体的 Mermaid erDiagram
• ERD 仅使用与技术无关的类型
• 每个实体定义后以及 ERD 块后均有 [Source: component/{service}/{Entity}] 抽象锚点
• 聚合根标记为 %% [AGGREGATE: ...]

第 6 节（业务规则）

• 每个规则组表格后均有 [Source: rule/{service}/{RuleName}] 抽象锚点
• 已根据 ErrorMessage.cs 或等效常量文件验证错误消息

初始化模式检查清单

• 在生成 ERD 前完成阶段 A 的提取
• 在编写第 6 节前完成阶段 B 的提取
• 在编写第 8、11 节前完成阶段 C 的提取
• 在编写第 9 节前完成阶段 D 的提取
• 在编写第 10、15 节前完成阶段 E 的提取
• 已为模块创建 CHANGELOG.md

完整性关卡（初始化模式）

• [C-gate] 阶段 C 条目数 ≥ 用例清单总计（步骤 1-INIT.1.5）
• [E-gate] 阶段 E 流程数 ≥ 阶段 C 条目数
• [Actor-gate] 参与者目录中的每个参与者至少出现在 1 个阶段 E 流程中
• [TC-gate] 第 15 节 TC 数 ≥ 用例清单总计
• [Source-gate] 每个阶段 C 条目和阶段 E 流程都有 [Source: namespace/service/id] 抽象锚点

相关

• documentation
• feature-implementation

---

工作流建议

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

1. 激活 tdd-feature 工作流（推荐）——scout → investigate → domain-analysis → tdd-spec → tdd-spec-review → plan → plan-review → plan-validate → why-review → cook → review-domain-entities → integration-test → integration-test-review → integration-test-verify → test → workflow-review-changes → sre-review → changelog → docs-update → watzup → workflow-end
2. 直接执行 $feature-docs——单独运行此技能

---

后续步骤

[阻塞] 完成后，直接向用户提问并提供选项。不要跳过——由用户决定：

• "$tdd-spec（推荐）"——为已记录的功能生成／更新测试规范
• "$tdd-spec [direction=sync]"——将测试规范同步到仪表板
• "跳过，手动继续"——由用户决定

---

相关技能

技能	关联关系	调用时机
$spec-discovery	生产者——提取工程规范包，供此技能的 INIT 模式使用	首次创建文档时，先运行 spec-discovery；将其输出用作第 12 节的来源
$tdd-spec	使用者——读取第 15 节以生成／验证 TC	创建／更新功能文档后，调用 tdd-spec 填充或审查第 15 节
$tdd-spec-review	审查者——审查第 15 节中的 TC 覆盖情况	在 tdd-spec 之后调用，用于验证 TC 的完整性以及 GIVEN/WHEN/THEN 的质量
$tdd-spec [direction=sync]	仪表板——根据第 15 节同步 docs/specs/README.md 和 docs/specs/PRIORITY-INDEX.md	更新 tdd-spec 后调用，以保持 QA 仪表板为最新状态
$integration-test	最终使用者——根据第 15 节中的 TC 生成测试代码	在 tdd-spec 之后调用，以生成实际的集成测试文件
$docs-update	编排器——将此技能作为第 2 阶段调用	运行 $docs-update 以同步完整链路；它会在内部调用 $feature-docs
$review-changes	触发器——检测功能文档是否过时	当业务文档相对于代码变更已过时，调用 $docs-update

独立链路

在工作流之外调用时，遵循此链路，确保所有规范层保持同步。 跳过本次会话中已完成的步骤。

feature-docs (you are here)
  │
  ├─ BEFORE this skill (if doc doesn't exist yet):
  │    [REQUIRED] → $spec-discovery [init mode]
  │          Extracts engineering spec bundle. Provides basis for Sections 1-14 accuracy.
  │          Skip if: feature docs updating existing content, or small feature with no domain model.
  │
  ├─ AFTER this skill:
  │
  ├─ [REQUIRED] → $tdd-spec [CREATE or UPDATE mode]
  │     Section 15 is incomplete without explicit tdd-spec run.
  │     CREATE: new feature doc just created → write TCs from spec.
  │     UPDATE: existing doc updated → update TCs to match changed behavior.
  │
  ├─ [REQUIRED] → $tdd-spec-review
  │     Validates TC coverage, GIVEN/WHEN/THEN completeness, no duplicate TC codes.
  │
  ├─ [REQUIRED] → $tdd-spec [direction=sync]
  │     Syncs Section 15 TCs to QA dashboard indexes at docs/specs/README.md and docs/specs/PRIORITY-INDEX.md.
  │
  ├─ [RECOMMENDED] → $integration-test [from-changes or from-prompt mode]
  │     Generates/updates integration test files from changed TCs.
  │
  └─ [RECOMMENDED] → $docs-update
        If code changes triggered this doc update, run $docs-update for full chain including
        spec-discovery (Phase 2.5) and tdd-spec (Phase 3).

文档网络原则

[必需] 此技能管理的每份功能文档都必须包含 ## Related Documentation 章节：

**INIT 模式：**插入该章节（紧接 frontmatter 之后，位于第 1 节内容之前） **UPDATE 模式：**确认该章节存在且链接为最新；如果旧版文档缺少该章节，则添加

如果该章节已存在，请勿重复添加。将此技能标记为完成前，先进行检查。

要插入或确认的模板，位于 docs/business-features/{Module}/README.md：

## Related Documentation

| Type              | Link                                                                                                          | Description                                                    |
| ----------------- | ------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
| Engineering Spec  | [docs/specs/{app-bucket}/{system-name}/](../../specs/{app-bucket}/{system-name}/)                             | Tech-agnostic spec bundle (domain model, rules, API contracts) |
| QA Test Dashboard | [docs/specs/README.md](../../specs/README.md) + [docs/specs/PRIORITY-INDEX.md](../../specs/PRIORITY-INDEX.md) | All TCs, execution status, integration test links              |
| Integration Tests | `src/Services/{ServiceName}/{ServiceName}.IntegrationTests/`                                                  | Test code linked to TCs via [Trait("TestSpec", "TC-...")]      |
| Related Modules   | _(list any cross-module dependencies here)_                                                                   |                                                                |

根据上下文填写 {app-bucket}、{system-name}、{Module}、{ServiceName}。 如果 docs/specs/{app-bucket}/{system-name}/ 尚不存在，请写入：(spec bundle not yet created — run $spec-discovery init)。

本节旨在：

• 帮助人们从业务文档 → 工程细节 → 测试证据逐步查阅
• 让 $docs-update 检测到规范包已更新，但业务文档尚未更新
• 让未来的 AI 会话无需完整扫描，就能了解现有内容

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

跨服务检查 — 微服务／事件驱动场景：在结束调查、计划、规范或功能文档编写之前，必须执行此检查。遗漏下游消费者会导致静默回归。

边界	Grep 搜索词
事件生产者	Publish、Dispatch、Send、emit、EventBus、outbox、IntegrationEvent
事件消费者	Consumer、EventHandler、Subscribe、@EventListener、inbox
Saga／编排	Saga、ProcessManager、Choreography、Workflow、Orchestrator
同步服务调用	与其他服务之间的 HTTP／gRPC 调用
共享契约	OpenAPI 规范、proto、共享 DTO——标记破坏性变更
数据所有权	其他服务读写同一张表／集合 → 共享数据库反模式

每个接触点： 所属服务 · 消息名称 · 消费者 · 风险（NONE / ADDITIVE / BREAKING）。

解除阻塞前必须完成： 扫描生产者 · 扫描消费者 · 检查 Saga · 审查契约 · 标记破坏性变更风险

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

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

解除阻塞前必须完成： - [ ] 证据文件路径（file:line）- [ ] 已执行 Grep 搜索 - [ ] 已找到 3 个以上相似模式 - [ ] 已说明置信度

未经证实不得使用： “显而易见”“我认为”“应该是”“可能是”“这是因为” 如果未完成 → 输出："Insufficient evidence. Verified: [...]. Not verified: [...]."

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

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

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

重要，务必注意 每项陈述都要引用 file:line 证据。置信度 >80% 才采取行动，<60% 时不得提出建议。

务必注意 运用批判性思维——每项陈述都需要可追溯的证据，置信度 >80% 才采取行动。防止幻觉：绝不要把猜测说成事实。

务必注意 落实 AI 错误预防措施——整体优先地调试，在负责的层级修复，编码前指出歧义，并在上下文压缩后重新阅读文件。

收尾提醒

• 重要，务必注意 [阻塞] 开始前将工作拆分为小型任务跟踪任务——没有任务列表时，不得输出任何内容
• 重要，务必注意 [阻塞] 每个测试用例都必须有可核实的代码证据（FilePath:LineNumber）——无一例外
• 重要，务必注意 [阻塞] 提取任何内容之前，先运行用例枚举（步骤 1-INIT.1.5）——最低 TC 数量由此清单推导
• 重要，务必注意 [阻塞] 更新模式下不得覆盖现有 TC——INIT 之后，第 15 节由 $tdd-spec 负责
• 重要，务必注意 [必须] 17 个章节必须严格按照主模板的顺序排列
• 重要，务必注意 [必须] 修改文档时，务必更新 CHANGELOG.md 和第 17 节（版本历史）
• 重要，务必注意 [必须] 创建新代码前，在代码库中搜索至少 3 个类似模式
• 重要，务必注意 [必须] 添加最终审查任务以核实工作质量

[任务规划] 务必注意：行动前分析任务范围，并通过任务跟踪将工作拆分为小型待办任务和子任务。

---

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

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

[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，然后打开其中列出的项目参考文档。只要具备此共享上下文和本地文档，任何受支持的 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] 在执行任何工作流或技能步骤之前，先为所有计划步骤创建／更新任务跟踪；然后随着每个步骤开始／完成，持续同步任务状态。