watzup

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

快速摘要

目标： 向开发者交付一份完整且有证据支撑的收尾报告——通过审查当前分支的更改并总结其影响和质量，提供更改摘要、文档／规范过时标记、根因经验，以及一份 $understand 审查指南（图表、用户故事、审查路径，以及如何测试／演示），同时不修改任何文件，让开发者基于完整背景决定下一步。

摘要：

• 只读约定——只审查／总结当前分支的提交并标记发现；绝不编辑、修复、实现或更新标记为过时的文档／规范——原因：watzup 是交接，而不是编辑环节。
• 主要步骤，按顺序执行：（1）审查近期提交——有哪些更改／新增／删除；（2）总结影响和质量；（3）文档过时检查——路径→文档映射表；（4）规范驱动的健康检查——功能规范根目录 → 规范过时情况 → 功能文档时效性（仅在业务代码有更改时）；（5）提取根因经验——指出错误 → 命名失败模式（而非症状）→ 提炼通用规则 → 询问用户；（6）$understand 交接——完整的审查指南，必须作为最后一项；（7）直接询问用户下一步计划。
• 成本，已明确说明： $understand 交接现在生成的内容比以前更详尽——它会推导图表、解析实际测试用例 ID，并构建有序的审查路径，因此会阅读更多仓库内容，也会撰写更长的报告。对于一份以引导开发者进入工作内容而非仅复述工作的收尾报告来说，这是有意承担的代价；在此说明，是为了让人主动选择，而不是事后才发现。
• 更改摘要之后必须经过三个关卡：文档过时检查、规范驱动的健康检查（仅限业务代码）、根因经验提取——绝不能因为更改“看起来很小”就跳过任何关卡。
• 只有用户确认后，才能将经验交给 $learn；“务必检查文件 X”这类表面笔记只是噪音，不算经验。
• $understand 是必须完成的最后一项交接，必须在“直接询问用户下一步计划”之前运行——如果不可用，停止并报告阻碍，绝不能跳过——原因：开发者离开时需要的是解释，而不是原始差异。

工作流：

1. 审查 — 分析近期提交：修改、新增、删除了哪些内容
2. 总结 — 提供详细的更改摘要和质量评估
3. 文档检查 — 将更改文件与 docs/ 交叉核对，检查文档是否过时
4. 经验总结 — 分析任务期间 AI 犯下的错误／遇到的问题，并记录经验
5. 理解交接 — 将 $understand 作为最后一项必须完成的任务调用，让开发者获得有关已完成工作的完整审查指南，先概览，再详述，分为四部分：定位 → 路径 → 深入分析 → 验证并提出异议。各部分的约定见 understand/SKILL.md Step 4，本文不再重复列出——如果此文件复制一份该约定，下次约定更改时副本可能悄然过时。写入 plans/reports/understand-*.md——如果没有可用于存放该文件的 git 忽略目录，则在聊天中完整交付——并在聊天中概述

关键规则：

• 只读：仅标记发现，绝不实现或修复任何内容
• 必须进行文档过时检查（见下方映射表）
• 必须进行经验总结分析（见下方章节）
• 最终审查任务必须包含文档过时检查、经验总结分析和最终的 $understand 交接
• 必须在 watzup 摘要／文档／错误分析之后、最终的下一步计划提示之前调用 $understand

保持怀疑，运用批判性思维和顺序思维。每项主张都需要有可追溯的证据和置信度百分比（Idea 应高于 80%）。

审查我当前的分支和最近的提交。 详细总结所有更改，包括修改、新增或删除的内容。 分析这些更改的整体影响和质量。

重要： 只审查和总结，绝不要开始实现。

文档过时情况检查（必需）

完成变更摘要后，运行 git diff --name-only（与基准分支或近期提交进行比较），并对照相关文档检查变更文件：

变更文件模式	需要检查是否过时的文档
.claude/hooks/**	.claude/docs/hooks/README.md、.claude/docs/hooks/*.md 中的 hook 数量表
.claude/skills/**	.claude/docs/skills/README.md、技能数量／目录表
.claude/workflows/**	CLAUDE.md 工作流目录表、.claude/docs/ 中的工作流引用
{configured-service-source-root}/**	受影响服务对应的 docs/specs/ 文档（路径来自 docs/project-config.json）
{configured-frontend-source-root}/**	docs/project-reference/frontend-patterns-reference.md、相关业务功能文档
CLAUDE.md	.claude/docs/README.md（导航中心必须保持同步）

输出以下其中一项：

• 可能需要更新的文档列表，并简要说明可能过时的内容（例如：“hook 数量从 31 增至 32”）。
• No doc updates needed — 如果没有变更文件模式对应到文档。

不要在 watzup 期间编辑文档。 只标记问题，由用户决定是否修复。

---

规范驱动开发健康检查（业务代码变更时必需）

当 git diff --name-only 包含后端服务源代码路径或前端应用／领域源代码路径下的任何变更时，运行此检查（从项目结构参考文档／docs/project-config.json 中解析具体路径）。

第 1 步 — 功能规范根目录检查

ls docs/specs/ 2>/dev/null

**注意：**结果是 app-bucket 名称。要查找特定功能规范，请检查 ls docs/specs/{app-bucket}/，以确认规范的 README.{Feature}.md 文件以及派生的分桶索引／ERD。

结果	操作
目录不存在或为空	⚠️ 标记："No Feature Specs found under docs/specs/. Consider running $workflow-code-to-spec (mode: init-full) to bootstrap spec-driven documentation for this codebase."
存在功能规范	继续第 2 步

第 2 步 — 规范过时情况检查（仅在存在规范包时）

针对 docs/specs/ 中的每个规范文件：

git log --since="30 days ago" --name-only -- docs/specs/ | head -10

结果	操作
过去 30 天内没有提交，且本会话中业务代码有变更	⚠️ 标记："Engineering spec bundle may be stale (no updates in >30 days). Consider running $workflow-code-to-spec (mode: audit) to verify freshness."
找到近期提交	✅ 规范包正在维护中

步骤 3 — 功能文档时效性检查

git log --since="30 days ago" --name-only -- docs/specs/ | head -10

结果	操作
过去 30 天内没有提交，且业务代码有变更	⚠️ 标记："Business feature docs may be stale. Consider running $docs-update to sync."
找到近期提交	✅ 功能文档正在维护

仅输出适用的标记。如果业务代码没有变更，则完全跳过本节。

---

AI 错误与经验教训分析（必需）

完成文档时效性检查后，回顾整个会话，分析 AI 的错误和经验教训。

步骤 1 — 列出所有错误

列出会话期间发生的每个错误。对于每个错误，注明：

• 发生了什么（可观察到的症状——构建失败、测试失败、输出错误）
• 发生在哪里（如适用，注明文件:行号）

常见错误类别：

• 未查看源代码，就假定某个 API／类型／枚举值存在
• 未检查要求，就假定基础设施可用
• 混淆“代码存在”和“代码会执行”——遗漏了路径追踪
• 未确认新上下文具备相同前置条件，就使用某种模式
• 未验证所有技术栈中受影响的输出，就报告“已完成”
• 臆造方法名、类名或文件路径

步骤 2 — 提炼根因教训（而非症状修复）

对每个错误，按照以下 3 个步骤进行提炼：

2a. 指出失败模式——不是症状，而是推理错误：

症状（不好的教训）	失败模式（好的教训）
“使用了错误的枚举值”	“未经源代码验证就假定 API 存在，并据此生成代码”
“using 中的命名空间错误”	“未先查看项目特定的配置文件，就假定项目的设置方式”
“CI 中的正常路径断言失败”	“编写断言时，未追踪处理程序在运行时依赖的基础设施”
“设置了查询中不存在的属性”	“未阅读基类，就假定层次结构中的所有类型都共享相同接口”

2b. 找出适用范围——这种相同的失败模式还可能出现在哪里？

如果失败模式只适用于某个特定文件或情况，就提升一个抽象层级，直到它具有普遍适用性。好的教训应适用于至少 3 种不同的情境。

2c. 写成通用规则——删除所有项目特定名称：

• 不要包含文件路径、特定于此代码库的类名或工具名
• 必须是对使用不同语言的完全不同代码库也有用的建议
• 如果多个错误有相同的失败模式，则合并为一条教训
• 检验：“这条教训能否避免 Java、Go 或 Python 项目中同类错误的发生？”如果可以，就是好的教训；否则请重写。

步骤 3 — 询问用户是否要保存

“找到 [N] 条根因教训。我是否应使用 $learn 保存它们，以供今后的会话使用？”

调用 $learn 前，等待用户确认。

以下内容任选其一输出：

• 编号列表：失败模式 → 通用教训 → 建议的 $learn 文本
• 本次会话中未发现 AI 错误——仅在确实未发现错误时使用

保持诚实并进行自我反省。 表层症状修复（例如“始终检查文件 X”）只适用于此代码库，不属于教训，而是噪声。目的：提炼能在多个会话中不断累积效果的根因预防措施。

---

后续步骤

强制重要必须注意——不得例外 在展示这些选项之前，必须将 $understand 作为最后一个强制待办任务调用，并以 watzup 摘要和当前变更集为范围。如果 $understand 不可用，请停止并报告该阻碍，不要默默跳过交接。

$understand 完成后，必须注意直接询问用户是否要展示这些选项。绝不能因为任务看起来“简单”或“显而易见”而跳过——由用户决定：

• "$workflow-end (Recommended)" — 完成并关闭当前工作流
• "$commit" — 如果未使用工作流，则提交更改
• "Skip, continue manually" — 由用户决定

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

外部记忆： 对于复杂或耗时的工作（研究、分析、扫描、审查），请将中间发现和最终结果写入 plans/reports/ 中的报告文件，以防止上下文丢失，并作为交付成果。

证据门槛： 强制重要必须注意——每项声明、发现和建议都必须提供 file:line 证明或可追溯的证据，并标注置信度百分比（>80% 才能采取行动，<80% 必须先核实）。

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

1. 首先调用当前任务列表。如果存在匹配的活动父工作流行，则设置 nested=true 并记录 parentTaskId；否则独立运行。
2. 在阶段工作开始前，为声明的每个阶段创建一个任务。嵌套时，任务主题前缀使用 [N.M] $skill-name — 阶段。
3. 嵌套时，使用 TaskUpdate(parentTaskId, addBlockedBy: [childIds]) 关联父任务。
4. 协调者必须在调用子技能或子代理之前，预先展开子技能的阶段列表，并关联工作流行。
5. 工作开始前，恰好将一个子任务标记为 in_progress；证据写入后立即将其标记为 completed。
6. 只有在所有子任务都已完成，或已明确说明原因并取消后，才能完成父任务。

解除阻塞条件： 完成当前任务列表、创建子阶段任务、在嵌套时关联父任务，并将第一个子任务标记为 in_progress。 项目参考文档门禁 — 在任务跟踪初始化之后、读取目标文件或源文件、搜索、编辑或分析之前运行。项目文档优先于通用框架假设。

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/ 下的源功能规格说明；架构/新领域需要 project-structure-reference.md。
4. 阅读所有必需文档，然后在开展目标工作之前说明：Reference docs read: ... | Not applicable: ...。

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

任务跟踪与外部报告持久化 — 执行前完成此初始化；随后在处理目标/源文件之前预先读取项目参考文档。

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

未满足以下条件前禁止继续： 已创建任务拆分；规划/审查工作已声明报告路径；已在记录下一项发现前持久化首项发现。

批判性思维准则 — 运用批判性思维和顺序思维。每项主张都需要可追溯的证据，置信度须高于 80% 才能采取行动。 反幻觉： 切勿将猜测当作事实陈述——每项主张都要引用来源，坦诚承认不确定性，自查输出中的错误，独立交叉验证，并对自己的判断保持审慎——缺乏证据的确信是一切幻觉的根源。 基于证据的推理 — 禁止猜测。每项声明都必须有证据。

1. 每项声明都必须引用 file:line、grep 结果或框架文档
2. 声明置信度：>80% 可直接采取行动，60-80% 先核实，<60% 切勿推荐
3. 架构变更必须进行跨服务验证
4. “证据不足”是有效且预期的输出

以下事项完成前禁止继续： - [ ] 证据文件路径（file:line） - [ ] 已执行 grep 搜索 - [ ] 找到 3+ 个类似模式 - [ ] 已声明置信度

未经证据证明，禁止使用： “显然”“我认为”“应该是”“可能是”“这是因为” 如果未完成 → 输出："证据不足。已核实：[...]. 尚未核实：[...]."

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

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

重要，必须注意 每项声明都要引用 file:line 证据（置信度 >80% 才能采取行动）。绝不要在没有证据的情况下猜测。

务必注意 运用批判性与顺序性思维——每项声明都需要适当的可追溯证据（关于仓库/代码的声明使用 file:line；关于研究、产品、内容和文档的声明使用源 URL 或材料章节）；置信度 >80% 才能采取行动，<60% 时切勿推荐。防止幻觉：绝不要把猜测说成事实，坦然承认不确定性，独立交叉核对，并对自己的判断保持怀疑。

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

• 必须 在开始目标工作前启动任务跟踪；一次只推进一项任务。

• 必须 将计划/审查发现逐步保存到 plans/reports/，并根据磁盘上的内容进行汇总。

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

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

• 强制要求 如果缺少项目配置、根目录指令文件或任何必需的参考文档，或者这些内容已过时，则自动运行 $project-init 或更精简的下级流程，然后再开展常规的项目专属工作。

• 强制要求 父级工作流条目不能替代子级阶段跟踪；如有嵌套，展开各阶段并关联父级。

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

提示词增强收尾锚点

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

项目协议叠加规则 — 执行此技能之前，先解析叠加到此技能上的任何 PROJECT 规则：将此技能名称与项目技能协议索引的 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 中匹配的正文；若正文缺失或格式错误，则报告，绝不重建。叠加规则仅可附加（绝不替代此技能自身的规则），且只是简要说明，绝不能提升权限；若具体程度相同的规则相互矛盾，则告知用户。

收尾提醒

重要：务必注意 目标： 在不修改任何文件的前提下，为开发者提供完整且有证据支持的收尾总结——包括变更摘要、文档／规范过时标记、根因经验，以及 $understand 审查指南——以便他们基于完整上下文决定下一步。

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

• 嵌套任务创建： 展开子阶段，关联父任务，并将一个任务设为进行中。
• 项目参考文档指南： 开始工作前，阅读必需的项目参考文档（始终包括 lessons.md）。
• 任务跟踪外部报告： 初始化任务跟踪；逐步将发现保存到 plans/reports/。
• 批判性思维： 批判性且按顺序思考；追溯证据，不把猜测当作事实。
• 证据： 每项结论都引用 file:line；绝不猜测。
• 防止 AI 出错： 根据证据核验生成的内容，追溯下游引用，核验所有受影响的输出，在上下文丢失后重新阅读，并明确指出歧义。

重要，务必注意 保持只读——仅标记发现；绝不编辑、修复、实现或更新你标记的文档/规范——原因：watzup 是审查/交接流程，不是编辑环节；先标记再修复会悄然违反只读约定。 重要，务必注意 在变更摘要之后运行所有三个必需关卡——文档过时检查（路径→文档表）、规范驱动的健康检查（仅在业务代码发生变更时）和根因经验提取——绝不因变更“看起来很小”而跳过任何关卡——原因：过时文档和遗漏的经验会在多个会话中悄然累积。 重要，务必注意 在询问用户“后续步骤”之前，将 $understand 作为最终必需交接步骤调用；如果 $understand 不可用，请停止并报告阻碍——绝不悄悄跳过交接——原因：开发者的退出上下文才是解释，而不是原始差异。

重要，务必注意 按根因（推理/假设失误）提取经验，而非症状；将每条经验写成适用于 ≥3 个代码库的通用规则；“始终检查文件 X”这类表层说明毫无价值——原因：只有根因预防才能在多个会话中持续发挥作用。 重要，务必注意 仅在用户明确确认后，才将经验发送给 $learn——绝不自动持久化，也绝不自行编辑指令文件——原因：经验记录会持久改变指令，必须由用户掌控。 重要，务必注意 通过直接询问用户来决定“后续步骤”——绝不擅自决定流程，即使路线“看起来很明显”也不例外——原因：用户负责选择结束工作流、提交还是继续。 重要，务必注意 开始前，将工作拆分成小型待办任务并启用任务跟踪（每个文件读取对应一个任务），始终恰好保持一个 in_progress 任务，并添加最终审查待办以核验工作质量——原因：长文件会耗尽上下文；细粒度任务在上下文压缩后仍能保留。 重要，务必注意 每项结论/发现都要引用 file:line 证据或可追溯证据，并注明置信度百分比（>80% 才能采取行动，<80% 时先核验）——绝不把猜测说成事实——原因：未经核验的文档过时/经验标记会误导开发者的后续决策。 重要，务必注意 标记任何引用的文档、路径或 API 之前，先用 grep/glob 核实其确实存在——绝不臆造文档映射或数量——原因：AI 会编造文件路径和方法名；变更摘要必须与实际差异相符。 重要，务必注意 收尾前阅读 CLAUDE.md 和项目参考文档关卡内容（始终包括 lessons.md）——原因：项目约定优先于通用的文档过时假设。

防止自我合理化：

规避做法	反驳
“文档看起来没问题，跳过过时检查门禁”	仍然运行路径→文档对照表 — 过时问题不会显现；请标记，或输出 No doc updates needed。
“本次会话没有真正的错误，跳过经验教训”	仍然运行检查门禁 — 只有在诚实地完成自我审查后，才输出 No AI mistakes identified。
“显然他们接下来想要提交，直接做吧”	绝不能自动决定 — 直接向用户提出选项；由用户决定后续路径。
“我顺手就能修复这份过时文档”	只读 — 仅标记。在这里修复会违反约定；由用户决定。
“改动很小，跳过 $understand”	$understand 是强制交接步骤 — 执行它，或报告阻碍；绝不能跳过。

重要：务必注意目标复述： 有证据支撑的只读总结 — 变更摘要 + 文档／规范过时标记 + 根因经验教训 + 强制 $understand 交接，不修改任何内容，由用户决定下一步。

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