plan-validate

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

快速摘要

目标： 在实施前，通过向用户提出关键问题来验证假设并发现问题，强制要求用户明确确认每一项包含假设的计划决策和每一项对保留行为至关重要的内容——确保没有未经说明的假设悄然进入代码。

摘要：

• 目的： 通过关键问题访谈验证已完成的计划，确保用户在实施前明确确认每一项包含假设的决策和每一项对保留行为至关重要的内容——确保没有未经说明的假设悄然进入代码。
• 主要步骤（按顺序执行）： 阶段 0 检测计划类型 → 确定计划路径（$ARGUMENTS / ## Plan Context / 询问）→ 将 mode + questions 范围作为硬性约束加载 → 步骤 1 阅读 plan.md + 所有 phase-*.md，标记决策/假设/风险/权衡 → 步骤 2 提取 8 个类别中的主题（架构、假设、权衡、风险、范围、新技术/库、测试规范、保留行为）→ 步骤 3 生成问题（每题提供 2-4 个具体选项，揭示隐含决策）→ 步骤 4 直接向用户提问进行访谈（每次最多 4 题）→ 步骤 5 记录答案 → 提供实施/完善/跳过选项。
• 阶段 0 会影响所有环节： 计划类型（bugfix/feature/migration/refactor/other）决定哪些问题类别会触发；任何 fix/bug/regression/broken/defect 关键词都会使保留行为问题变为必答项——绝不跳过。
• 输出必须是一次真实访谈，而不是自问自答： 遵守 ## Plan Context 中 questions 的最小值和最大值范围，每个问题提供 2-4 个具体选项；若用户对保留行为回答“不确定”，则视为受阻 → 转到 $plan；如果计划引入新技术/软件包，先询问是否评估过替代方案，再接受该选择。
• 严格限定结果写入范围： 仅向 plan.md 添加 ## Validation Summary（已确认的决策 + 待办事项）——绝不编辑阶段文件；结束时直接询问用户是要实施、完善还是跳过。

工作流：

1. 检测计划类型 — 将计划归类为 bugfix/feature/migration/refactor，以决定问题类别的权重
2. 阅读计划 — 解析 plan.md + 阶段文件，查找决策、假设和风险
3. 提取主题 — 扫描架构、假设、权衡、风险和范围相关关键词
4. 生成问题 — 拟定具体问题，每题提供 2-4 个选项
5. 访谈用户 — 按配置的数量范围提出问题
6. 记录答案 — 在 plan.md 中添加 Validation Summary 章节

关键规则：

• 必须直接询问用户——绝不替用户自动做决定——原因：每一项包含假设的选择都由用户决定，而非 Agent。
• 只询问会影响实施的真实选择——绝不询问不涉及决策的问题——原因：无关问题会浪费访谈名额并损害信任。
• Bugfix 计划始终触发保留行为问题（关键词：fix、bug、regression、broken、defect）——原因：未经验证的正确性保留不变量会导致隐蔽回归。
• 通过在 plan.md 中添加 ## Validation Summary 来保存结果——绝不修改阶段文件——原因：阶段文件是计划的事实来源；验证是一次先读取、再添加注释的过程。

第一原则 — 易于修改

每项编码决策的成功指标都是_未来的变更成本_。 DRY、SRP、抽象、设计模式、命名、分层、测试——每种 技术都只为一个目标服务：降低下一次变更的成本。

评估代码、重构、测试和抽象时，问问： 这会让下一次变更更便宜还是更昂贵？

• 拒绝会增加变更成本的“最佳实践”（过早抽象、 推测性通用设计、泄漏的间接层、没有回报的繁文缛节）。
• 在问题中指出真正的敌人：耦合、隐藏状态、重复的 知识、意图不明确、过早暴露的不可逆决策。
• 易于修改的简单设计，胜过难以修改的复杂设计。

在应用下方任何具体规则、模式或检查清单之前，先用这一原则来衡量——如果后续规则会增加变更成本，以本原则为准。

---

阶段 0：检测计划类型

生成问题之前先对计划类型进行分类——这会影响各类问题的权重：

计划类型	判定依据	必需的额外类别
Bugfix	标题/前言：fix、bug、regression、broken、defect	Preservation（阻断项）
Feature	新功能，不含修复相关关键词	Architecture、Assumptions、Test Specs
Migration	架构变更、EF 迁移、数据迁移	Risks、Preservation、Scope
Refactor	重组/清理，不改变行为	Preservation、Tradeoffs
Other	以上皆非	Architecture、Scope

Bugfix 检测是阻断项——只要出现 fix/bug/regression/broken/defect 关键词，绝不可跳过 Preservation 问题。

计划解析

1. 提供了 $ARGUMENTS → 使用该路径
2. 检查 ## Plan Context 部分 → 使用当前计划路径
3. 未找到计划 → 请用户指定路径或先运行 $plan

配置（来自注入的上下文）

检查 ## Plan Context 部分：

• mode — auto/prompt/off 行为
• questions — 范围，例如 3-8（最小值-最大值）

将其作为硬性约束。

工作流

步骤 1：读取计划文件

读取计划目录：

• plan.md — 概览 + 阶段列表
• phase-*.md — 所有阶段文件
• 标记：决策点、假设、风险、权衡

步骤 2：提取问题主题

类别	关键词
Architecture	approach、pattern、design、structure、database、API
Assumptions	assume、expect、should、will、must、default
Tradeoffs	tradeoff、vs、alternative、option、choice、either/or
Risks	risk、might、could fail、dependency、blocker、concern
Scope	phase、MVP、future、out of scope、nice to have
New Tech/Lib	install、add package、new dependency、npm install、dotnet add、不熟悉的框架名称
Test Specs	TC-、test case、coverage、TDD、test specification
Preservation	标题/前言中出现 bugfix 关键词时自动触发——扫描 Preservation Inventory 部分

第 3 步：生成问题

格式规则：

• 每个问题提供 2-4 个具体选项
• 在推荐选项后添加 "(Recommended)" 后缀
• 自动提供 "Other" 选项——请勿添加
• 明确提出隐含的决策

示例：

Category: Architecture
Question: "How should validation results be persisted?"
Options:
1. Save to plan.md frontmatter (Recommended) — updates existing plan
2. Create validation-answers.md — separate answers file
3. Don't persist — ephemeral validation only

Category: Assumptions
Question: "Plan assumes API rate limiting not needed. Correct?"
Options:
1. Yes, not needed for MVP
2. No, add basic rate limiting now (Recommended)
3. Defer to Phase 2

Category: Preservation (MANDATORY when title/frontmatter: fix, bug, regression, broken, defect)
Question: "List 2-3 inputs where CURRENT code is correct. Will fix change behavior on any?"
Options (multi-select):
1. "Current code correct on: {input A}. Fix preserves behavior." (Recommended)
2. "Current code correct on: {input B}. Fix CHANGES behavior because: {justification}"
3. "Current code has NO preserved-correctness inputs — every input was broken" (rare; requires confirmation)
4. "Unsure — need to investigate" (STOP: run $plan preservation analysis)

后续跟进规则：

• 选择选项 2 → plan.md 中的 Preservation Inventory 必须引用一条 Preservation TC，声明新行为符合预期
• 选择选项 4 → 返回 BLOCKED 状态，建议先执行 $plan
• 选择选项 3 → 直接向用户提出后续问题："确认：当前代码没有任何保留的不变量？[是，每个输入都已损坏 / 否，遗漏了一些——重新调查]"

第 4 步：访谈用户

使用直接询问用户的方式——绝不跳过或自动作答。

规则：

• 使用 ## Plan Context 中的提问数量 → Validation: mode=X, questions=MIN-MAX
• 将相关问题分组（每次工具调用最多 4 个）
• 重点关注：假设、风险、权衡、架构
• 强制重要必须注意：如果计划引入新技术/软件包，询问："计划使用 {lib}。是否评估过替代方案？请确认选择或进一步研究。"

第 5 步：记录答案

在 plan.md 中添加 ## Validation Summary：

## Validation Summary

**Validated:** {date}
**Questions asked:** {count}

### Confirmed Decisions

- {decision 1}: {user choice}
- {decision 2}: {user choice}

### Action Items

- [ ] {changes needed based on answers}

绝不修改阶段文件——只记录需要更新的内容。

输出

验证后：

• 提问数量
• 已确认的关键决策
• 标记为需要修订计划的事项
• 建议：开始实施，还是先修订计划

后续步骤

强制重要必须注意——无一例外 完成后，使用直接询问用户的方式展示：

• "$feature-implement (Recommended)" — 根据已验证的计划开始实施
• "$refine" — 如果计划需要先进行 PBI 优化
• "Skip, continue manually" — 由用户决定

---

[BLOCKING] 必须注意：使用直接询问用户的方式进行访谈。未提问至少 1 个问题就完成任务 = 违规。

[IMPORTANT] 使用任务跟踪，在开始前将所有工作拆分为小任务——包括每个文件读取对应的任务。对于简单任务，AI 必须注意询问用户是否跳过。

外部记忆： 对于复杂/耗时的工作 → 将发现和结果写入 plans/reports/ — 防止上下文丢失。

证据门槛： 强制重要必须注意——每项声明都需要 file:line 证明或带置信度百分比的追踪证据（>80% 执行，<80% 先验证）。

嵌套任务扩展约定 — 对于工作流步骤调用，[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。 任务跟踪与外部报告持久化 — 在执行前完成初始化；然后在处理目标文件或源文件前，预取项目参考文档。

1. 在读取目标文件、搜索、编辑或分析前，先创建简短的任务拆分。上下文丢失时，先检查当前任务列表。
2. 工作前将一个任务标记为 in_progress，并在获得证据后立即标记为 completed；切勿批量转换状态。
3. 对于计划或审查工作，在发现首个问题前创建 plans/reports/{skill}-{YYMMDD}-{HHmm}-{slug}.md。
4. 每完成一个文件、章节或决策后，就将发现追加到报告中，并在最后根据报告文件综合总结。
5. 最终输出注明：Full report: plans/reports/{filename}。

开始工作的前提： 已创建任务拆分；计划或审查工作已声明报告路径；已在发现下一个问题前持久化首个发现。

批判性思维 — 运用批判性思维和顺序思维。每项主张都必须有可追溯的证据，且置信度须高于 80% 才能采取行动。 防止幻觉： 切勿将猜测当作事实陈述 — 为每项主张引用来源；坦诚承认不确定之处；自行检查输出中的错误；独立交叉核对；对自己的判断保持怀疑 — 缺乏证据支撑的确信是所有幻觉的根源。

顺序思维协议 — 对复杂或模糊的工作采用结构化、多步骤推理。在规划、审查、调试或完善想法时，若一次性推理不安全，则使用此协议。

适用情形： 复杂问题拆解 · 需要调整的自适应计划 · 需要修正方向的分析 · 范围不明确或不断变化 · 多步骤解决方案 · 基于假设的调试 · 跨领域权衡评估。

格式（显式模式 — 展示思路过程）：

1. Thought N/M: [aspect] — 每条思路只讨论一个方面，并说明假设或不确定性
2. Thought N/M [REVISION of Thought K]: ... — 先前推理被推翻时使用；说明原内容 / 修正原因 / 影响
3. Thought N/M [BRANCH A from Thought K]: ... — 探索替代方案；通过说明决策依据得出结论
4. Thought N/M [HYPOTHESIS]: ... 然后是 [VERIFICATION]: ... — 行动前进行测试
5. Thought N/N [FINAL] — 仅在验证完成、所有关键方面均已处理且置信度高于 80% 时使用

必须包含的结尾信息： 置信度百分比 · 假设列表 · 尚待解决的问题 · 明确的下一步行动。

停止条件： 对任何关键决策的置信度低于 80% → 直接向用户提问并升级处理 · 同一条思路修正达到 3 次或以上 → 重新界定问题 · 分支数量超过 3 个 → 拆分为子任务。

隐式模式： 当添加标记会使回复显得冗长时（例如有助于准确性的常规工作），在内部应用此方法，不显示标记。

深入了解： 参阅 $sequential-thinking 技能（.claude/skills/sequential-thinking/SKILL.md），了解详细示例（API 设计、调试、架构）、高级技术（螺旋式改进、假设检验、收敛）和元策略（不确定性处理、修正级联）。 项目参考文档门禁 — 在任务跟踪初始化之后、读取目标文件或源文件、执行 grep、编辑或分析之前运行。项目文档优先于通用框架假设。

1. 确定范围：文件类型、领域范围和操作。
2. 首先阅读 docs/project-config.json — 项目的机器可读映射。 它是本仓库的唯一事实来源（模块/路径、框架 + 搜索关键词、测试/E2E/集成运行命令、设计系统、架构规则、工作流模式）；在调查、规划或编码之前，以它为依据确认准确路径、运行命令和约定 — 切勿假设框架默认设置（CLAUDE.md + 参考文档均由它派生）。如果它 — 或文档索引、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（切勿自动运行）。
3. 按触发条件查阅必需文档：始终查阅 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-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；架构/新领域查阅 project-structure-reference.md。
4. 阅读所有必需文档，然后在处理目标内容之前声明：Reference docs read: ... | Not applicable: ...。

准备就绪的条件： 已评估范围、已查阅 docs/project-config.json、已检查/阅读必需文档或已完成初始化流程、已确认 lessons.md、已给出引用声明。

先理解代码 — 严格门禁：在阅读现有代码之前，不得编写、规划或修复。

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 存在）- [ ] 已通过证据验证假设

计划质量 — 每个计划阶段都必须特别包含测试规格。

1. 在每个阶段文件中添加 ## Test Specifications 部分，并使用 TC-{FEATURE}-{NNN} ID
2. 将每项功能需求映射到至少 1 个 TC（或附带理由明确标记为 TBD）
3. TC ID 遵循 TC-{FEATURE}-{NNN} 格式 — 通过 ID 引用，切勿嵌入完整内容
4. 开始任何新的工作流步骤前：调用当前任务列表并重新阅读阶段文件
5. 上下文压缩时：首先调用当前任务列表 — 切勿创建重复任务
6. 完成阶段之前验证 TC 是否满足（证据必须为 file:line，不能是 TBD）

模式： TDD 优先 → 引用现有 TC 并标记 Evidence: TBD。实现优先 → 使用 TBD → $spec [mode=tests] 之后补充。 跨服务检查 — 微服务／事件驱动架构：在结束调查、计划、规范或功能文档前，必须执行。遗漏下游使用方 = 无声回归。

边界	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 · 已审查契约 · 已标记破坏性变更风险

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

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

重要，务必注意：进行任何修改前，搜索至少 3 个现有模式并阅读代码。若存在 graph.db，则运行图追踪。

• 必须注意，至关重要：每项声明都要引用 file:line 证据。置信度 >80% 才可采取行动；<60% 时，不要提出建议。

必须注意，至关重要：每个阶段都要包含带 TC ID 的 ## Test Specifications。创建新任务前，先查看当前任务列表。

必须注意，至关重要：微服务／事件驱动架构：扫描任务范围内的生产者、消费者、Saga 和契约。每个接触点：所属服务 · 消息 · 消费者 · 风险（NONE/ADDITIVE/BREAKING）。遗漏消费者 = 无声回归。 必须注意：应用批判性思维和顺序思维——每项断言都需要适当的可追溯证据（代码库/代码相关断言需提供 file:line；研究、产品、内容和文档相关断言需提供来源 URL 或材料章节）；置信度 >80% 才可采取行动，<60% 时不要提出建议。防止幻觉：绝不把猜测当作事实；坦诚承认不确定性；独立交叉核对；对自己的判断保持怀疑。

必须注意：应用顺序思维——分步标记 Thought N/M、REVISION/BRANCH/HYPOTHESIS，并注明更具体的置信度百分比；参见 $sequential-thinking 技能。

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

• 强制要求：在处理目标任务前启动任务跟踪；一次只推进一个任务。

• 强制要求：将计划/审查结果逐步保存到 plans/reports/，并依据磁盘上的内容综合整理。

• 强制要求：调查、规划或编码前，先阅读 docs/project-config.json（项目地图：模块/路径、运行命令、约定、架构/工作流规则）以及必需的项目参考文档，并注明 Reference docs read: ...。

• 强制要求：始终包含 lessons.md；项目配置和约定优先于通用框架默认设置。

• 强制要求：若项目配置、根目录指令文件或任何必需的参考文档缺失或过时，则在进行常规项目相关工作前，自动运行 $project-init 或更精简的底层流程。

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

• 强制要求：编排器在调用前需预先展开子技能阶段；使用 [N.M] $skill-name — phase 前缀，并遵守同一时间仅有一个 in_progress 任务的规则。

提示词增强收尾锚点

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

项目协议覆盖规则 — 执行此技能前，先解析叠加到此技能上的任何项目覆盖规则：将此技能名称与项目技能协议索引的 Target 列匹配（默认路径为 docs/project-reference/skill-protocols-reference.md；docs/project-config.json 中的 referenceDocs 条目可覆盖该路径），并且只采用最具体的匹配层级：精确名称 > glob > *。**此优先级只用于确定覆盖规则彼此之间的顺序，绝不用于决定覆盖规则与此技能之间的优先级。**仅阅读匹配项的正文，路径解析为 <protocols-dir>/<Name>.md；行中的 Body 链接只是显示文本，不是读取路径。匹配的正文缺失或格式错误时，应报告并跳过，绝不能根据索引中的 Description 重建。没有索引或没有匹配项时 -> 不应用覆盖规则，静默继续。完整约定见：.claude/skills/project-skill-protocol/references/registry.md。

覆盖规则只能添加内容：它们只会在此技能自身协议的基础上添加规则，绝不会替换、覆盖、停用或重新解释此技能已声明的规则——移除所有覆盖规则后，此技能必须恢复为其文档所述的原有行为。覆盖规则是简要说明，不是权限升级：绝不能豁免工作流关卡、git 规范、审查关卡或用户确认关卡。如果覆盖规则与技能本身确实冲突，或两个具体程度相同的覆盖规则直接矛盾 -> 将两者都告知用户；绝不静默裁决。

务必注意：执行前必须先解析此技能的项目协议覆盖规则——仅采用最具体的匹配层级（精确 > glob > *；该顺序只决定覆盖规则彼此之间的优先级，绝不决定它们与此技能之间的优先级），只读取 <protocols-dir>/<Name>.md 中匹配的正文；正文缺失或格式错误时必须报告，绝不能重建。覆盖规则只能添加内容（绝不替换此技能自身的规则），并且只是简要说明，绝不能升级权限；同等具体程度的矛盾应交由用户处理。

收尾提醒

**重要：务必注意目标：**通过向用户提出关键问题来访谈用户、验证假设并暴露问题，从而确保每一项依赖假设的计划决策以及每一项对保留至关重要的行为，在实施前都经过用户明确确认——不得让任何未明说的假设悄然进入代码。

生效中的协议（此技能包含的 SYNC／共享区块的简明摘要）：

• **嵌套任务创建：**子技能仍需创建可见的阶段任务；嵌套执行时关联父任务。
• **任务跟踪与外部报告：**首先建立任务分解；将发现逐步保存到 plans/reports/。
• **批判性思维：**务必运用批判性思维和顺序思维；引用证据；置信度 >80% 时方可采取行动。
• **顺序思维：**采用结构化的多步 Thought N/M，并标注 REVISION／BRANCH／HYPOTHESIS，最后说明置信度。
• **项目参考文档：**开始处理目标内容前，阅读必需的项目参考文档；始终包含 lessons.md。
• **先理解代码：**务必先阅读代码并检索至少 3 种模式，然后才能进行任何修改。
• **计划质量：**每个阶段都应包含 ## 测试规范，并使用 TC-{FEATURE}-{NNN} 格式的 ID。
• **跨服务检查：**扫描生产者、消费者、saga 和契约；指出破坏性变更风险。
• **防止 AI 出错：**依据证据核验生成的内容，追踪下游引用，核验所有受影响的输出；上下文丢失后重新阅读，并明确指出歧义。 重要：务必注意 按顺序执行主要步骤——阶段 0 检测计划类型 → 解析计划路径 → 加载 mode + questions 范围 → 步骤 1 阅读 plan.md + 所有 phase-*.md（标记决策／假设／风险／权衡）→ 步骤 2 提取主题（8 个类别）→ 步骤 3 生成问题（每题 2-4 个选项）→ 步骤 4 直接向用户提问进行访谈（每次 ≤4 个问题）→ 步骤 5 记录答案 → 提供实施／完善／跳过的选项——原因：这套流程本身就是工作；绝不能凭记忆合并或跳过任何步骤

重要：务必注意 直接向用户提问，验证各项决策——绝不能自动做决定或自行作答；未至少提出 1 个问题就完成，属于违反协议——原因：每一项涉及假设的选择都由用户决定，而非 Agent 重要：务必注意 生成问题前，务必先检测计划类型（阶段 0）——修复类关键词（fix、bug、regression、broken、defect）会使 Preservation 问题成为必答项，绝不能跳过——原因：检测结果决定触发哪些类别及 Preservation 关卡 重要：务必注意 绝不能修改阶段文件——仅通过在 plan.md 中添加 ## Validation Summary（已确认的决策 + 待办事项）来保存结果——原因：阶段文件是计划的事实来源，而验证是先读取再添加注释的过程

• 强制重要：务必注意 开始前使用任务跟踪将工作拆分为小型待办任务（包括为每个待读取文件单独创建任务）；上下文丢失时，先调用当前任务列表，绝不重复创建——原因：应恢复现有任务，而不是在上下文压缩后重新规划
• 强制重要：务必注意 将 ## Plan Context 中的 questions 最小值-最大值范围和 mode 视为硬性约束；每个问题提供 2-4 个具体选项，绝不能低于最小值——原因：访谈预算是预先配置的，不能临时决定
• 强制重要：务必注意 将 Preservation 问题的“不确定”回答视为已阻塞 → 返回 BLOCKED 状态，并在任何实施前转交 $plan 进行 Preservation 分析——原因：未经验证的正确性保持不变量会带来隐蔽的回归风险
• 强制重要：务必注意 如果计划引入新技术／软件包，在接受该选择前，先探查是否评估过替代方案——原因：未经评估的依赖选择会增加未来的变更成本
• 强制重要：务必注意 每项主张都要引用 file:line 证据或追踪到的证据，并标注置信度百分比（>80% 时执行，<80% 时先验证）；应承认不确定性，不要把猜测说成事实——原因：猜测会导致验证问题出错
• 强制重要：务必注意 生成问题前，搜索至少 3 种现有模式，并阅读计划和阶段文件——优先遵循代码库的本地惯例，而非通用框架默认设置——原因：基于实际代码表面的问题能揭示真正的决策，而不是凭空捏造
• 强制重要：务必注意 应用 Easy-to-Change 视角后，再遵循以下任何规则——标记会增加未来变更成本的决策（耦合、隐藏状态、知识重复、意图不明确、过早做出不可逆选择）
• 强制重要：务必注意 添加最终审查任务，以验证工作质量

防止自我合理化：

规避说法	反驳
“计划很简单，跳过验证”	简单的计划仍包含隐式决策。无论如何都要应用验证。
“我已经知道答案了”	展示用户的回答作为依据。没有回答 = 未验证。
“这里不适用保留流程”	如果标题含有 fix/bug/regression/broken/defect → 始终适用。
“不需要 Phase 0”	检测结果决定是否进入保留流程关卡。绝不跳过。
“只问几个问题就好”	使用 Plan Context 中的 questions 范围。绝不能低于最小值。
“我直接替用户回答就好”	必须直接询问用户。自行回答 = 未验证。
“新库显然没问题”	接受之前，先探查是否评估过其他方案。
“我直接在阶段文件中编辑”	绝对不行。只能向 plan.md 添加 ## Validation Summary。

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

重要：必须注意 首先检测计划类型（Phase 0）——含有 bugfix 关键词时，保留流程为阻断性要求。 重要：必须注意 必须直接询问用户进行验证——绝不能自动做决定。 重要：必须注意 绝不能修改阶段文件——只能向 plan.md 添加 ## Validation Summary。

---

最后提醒——易于更改才是成功指标。 每项发现、测试、重构和抽象都必须回答一个问题：这会让下一次更改成本更低，还是更高？ 如果无法降低未来的更改成本，就应予以拒绝。耦合、隐藏状态、重复的知识和不明确的意图才是真正的敌人——要明确指出它们。

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

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