investigate

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 Spec
• 集成测试实现／审查：integration-test-reference.md
• E2E 测试实现／审查：e2e-test-reference.md
• 代码审查／审计：code-review-rules.md 以及根据变更文件选择的领域文档

不要不加区分地阅读所有文档。从 docs-index-reference.md 开始，然后只打开与任务相关的文件。

快速摘要

目标： 通过只读探索，在零改动的前提下，基于证据了解现有代码的工作方式——每项结论都追溯到 file:line，或明确标记为“推断”，让后续决策或改动建立在已验证的系统流程上，而非假设之上。

摘要：

• 目的： 以只读、基于证据的方式梳理现有代码的工作方式——让后续决策或修复建立在已验证的流程上，而非假设之上。
• 主要步骤（按顺序执行）： 阶段 0 分类（快速 / 深入 / 调试 / 建议）→ 发现（实体 > 命令 > 事件 > 控制器）→ 扩展图谱（2-3 个关键文件，仅主 Agent 执行）→ 知识图谱（逐文件编写文档）→ 流程映射（入口 → 出口 + 副作用）→ 分析（业务规则 / 验证 / 授权 / 错误路径）→ 综合（深入范围 → 分析文件）→ 呈现（结构化发现 + 提供进一步深入分析）。
• 首先分类范围（阶段 0：快速 / 深入 / 调试 / 建议）——分析深度和交付物（分析文件、验证链）都由此决定，因此绝不能跳过这一步直接开始搜索代码。
• 图谱是必需项，而非可选项：主 Agent 必须在下结论前，对 2-3 个关键文件至少运行一条 code_graph 命令——图谱可以揭示仅靠搜索代码无法发现的调用方、总线消费者和导入方（子 Agent 无法使用图谱）。
• 严格保持只读，并为每项结论注明 file:line；未经验证的陈述必须标记为“推断”；任何代码改动建议都必须执行完整验证链（所有实现 / 注册 / 用法 / 跨服务影响 + 置信度声明）。
• --mode=explain 只会改变交付物（一篇单向的开发者说明 → Git 忽略的 tmp/understand/{branch}.md 记录文件）——相同的证据门槛、图谱规则和只读限制仍然适用；深入范围会写入 .ai/workspace/analysis/[feature]-investigation.md，并且必须在呈现前完整重读。

工作流：

1. 阶段 0：分类 — 开始操作前确定范围（快速 / 深入 / 调试 / 建议）
2. 发现 — 在代码库中搜索相关文件（实体 > 命令 > 事件 > 控制器）
3. 扩展图谱 — 对 2-3 个关键文件运行图谱查询（必需项，仅主 Agent 执行）
4. 知识图谱 — 阅读并记录每个文件的用途、符号和依赖项
5. 流程映射 — 从入口点追踪整个流程直到出口点
6. 分析 — 提取业务规则、验证、授权和错误处理
7. 综合 — 将执行摘要写入 .ai/workspace/analysis/[feature]-investigation.md
8. 呈现 — 提供结构化发现，并提出可进一步深入分析

模式：

• 默认模式（分析） — 面向工程师进行调查：提供结构化发现和分析文件。以下所有内容均适用。
• --mode=explain（开发者说明）— 遵循相同的只读证据门槛，但交付物为单向开发者说明（用途 → 工作方式 → 原因 → 影响），根据编码水平调整，并写入 Git 忽略的记录文件。参见模式：Explain。如果想使用由提示词驱动的独立说明工具，而非完整调查流程，请使用 $understand [target]。

关键规则：

• 严格保持只读——绝不改动代码
• 每项结论都必须有 file:line 作为依据——未经验证的内容标记为“推断”
• 下结论前必须注意至少对关键文件运行一条图谱命令
• 必须注意规划 ToDo 任务，阅读 project-structure-reference.md（如果找不到，请搜索：项目文档、编码规范、架构文档）

阶段 0：范围分类

先分类，再行动——按正确的深度处理：

范围	信号	深度
快速	单一功能／函数，入口清晰	grep → 跟踪 → 回答（无需分析文件）
深入	多服务、跨边界、范围不明确	完整工作流 + 知识图谱模板 + 分析文件
调试	错误／崩溃／意外行为	使用上方的根因调试协议
建议	建议进行代码更改（移除、重构）	使用下方的验证链协议——必须执行
说明	--mode=explain 标志	面向开发者的调查过程说明——参见 模式：说明。单独使用 $understand，获取由提示词驱动的说明。

快速范围：跳过知识图谱模板和分析文件。Grep → 图谱跟踪 → 呈现发现。 深入范围：必须写入 .ai/workspace/analysis/[feature]-investigation.md。 说明范围：使用相同的只读证据门槛；交付内容为聊天中的开发者说明 + 被 git 忽略的记录文件（不是分析文件）。

调查思维方式（不可妥协）

保持怀疑。每项主张都需要通过 file:line 提供可追溯的证据。置信度 >80% 才能采取行动。

• 绝不假设代码如其名称所示那样工作——通过阅读实际实现来验证
• 必须为每项发现注明 file:line；未经证实的主张必须标记为“推断”
• 始终 grep 相关用法、调用方及跨服务引用——绝不假设已涵盖所有内容
• 始终根据证据跟踪实际调用路径——绝不只依赖函数签名

逻辑 ID 提取与业务意图规则（M3/M5）

阻断性标准请参见 .claude/skills/shared/sdd-artifact-contract.md → “AI-SDD Mandates (M1-M7)”。将操作、业务规则或事件提取为发现项时：

• 为每个提取的操作／规则／事件分配逻辑 ID（操作和规则使用 FR-/BR-）作为主要标识符。将 [Source: namespace/service/id] 抽象锚点证据保留为独立载体（不得使用物理代码坐标或仓库根路径——这些只放在来源信息旁文件中），绝不能将来源链接并入规则陈述本身（M3）。
• 对每条规则，都要解释其存在的原因（它要保护的业务意图／不变量），而不仅仅是代码的行为。用与技术无关的业务术语陈述规则，以便任何技术栈上的重建团队都能复用该发现（M5）。

工作流

1. 发现 — 搜索所有相关文件。优先级：实体 > 命令/查询 > 事件处理程序 > 控制器 > 消费者 > 组件。

2. 扩展图谱（必须执行 — 不得跳过） — 你（主 Agent）必须亲自运行图谱查询，检查步骤 1 中的关键文件。子 Agent 无法使用图谱，只有你可以。选择 2-3 个关键文件（实体、命令、总线消息）：

   python .claude/scripts/code_graph connections <key_file> --json
   python .claude/scripts/code_graph query callers_of <FunctionName> --json
   python .claude/scripts/code_graph query importers_of <file_path> --json
   # “ambiguous” → 搜索以消除歧义，并使用限定名称重试
   python .claude/scripts/code_graph search <keyword> --kind Function --json
   # 跟踪两个节点之间的连接
   python .claude/scripts/code_graph find-path <source> <target> --json
   # 按服务筛选，限制结果数量
   python .claude/scripts/code_graph query callers_of <name> --limit 5 --filter "ServiceName" --json
   

   图谱能揭示 grep 单独使用时会遗漏的完整依赖网络（调用方、导入方、测试、继承）。还要运行 $graph-connect-api，映射前端到后端的 API。

3. 知识图谱 — 阅读并分析每个文件（来自 grep 和图谱结果）。记录用途、符号、依赖关系和数据流。每组处理 10 个文件；每组处理完后更新进度。每个文件使用以下模板：

4. 流程映射 — 从入口点跟踪到处理管线，再到出口点。映射数据转换、持久化、副作用和跨服务边界。

5. 分析 — 提取业务规则、验证、授权和错误处理。记录正常流程和边缘情况。

6. 综合 — 撰写执行摘要，回答原始问题。列出关键文件、使用的模式和基于文本的流程图。

7. 呈现 — 提供结构化输出（参见输出格式）。可针对子主题进一步深入分析。

如果前面有 $scout： 使用 Scout 编号文件列表作为分析目标。跳过重复的发现步骤。优先处理 HIGH PRIORITY 文件。

并行调查线程（发现 → 一轮 → 图扩展）

调查严格遵循只读原则，因此任何两个线程都不会共享写入目标——这是框架中最适合并行处理的活动，逐个线程阅读才是默认缺陷，而不是安全选择。第 1 步确定目标范围后，应先将目标拆分为相互独立的线程，再深入阅读任何内容：

拆分维度	每个线程负责……	适用场景
按模块	目标涉及的模块／有界上下文	功能跨越多个模块
按层	后端 · 前端 · 数据／持久化	全栈流程——每层读取互不重叠的文件集合
按问题	一个假设，或一个“X 如何运作？”问题	Phase 0 将任务归类为 debug，或提示词包含多个相互独立的问题
按服务	参与产生／消费该流程的每个服务	跨服务／事件驱动型目标（配合跨服务检查协议使用）

此技能特有的分派规则：

1. 先声明，再在同一条消息中启动——Parallel plan: wave 1 = [thread A, thread B, …] · SEQ = [Graph Expand, Flow Mapping, Analysis, Synthesis] (each consumes the whole wave)。
2. 按线程分派——文件／符号概况调查线程交给 scout（使用 --ext 时交给 scout-external）；根因／假设调查线程交给 debugger。两者都不要交给通用审查者。
3. 每个线程拥有独立范围和报告路径——每份任务说明都要列明确切的文件／问题，以及各自的写入目标（.ai/workspace/analysis/[feature]-{thread}.md 或 plans/reports/…）；两个线程绝不能写入同一文件，并且每个线程都应增量保存结果，而不是返回一份对话记录。
4. Graph Expand 必须由你按顺序执行——屏障解除后，亲自运行第 2 步的 code_graph 命令，针对本轮调查发现的 2-3 个关键文件执行。这一步会将各线程的独立结果整合为一个依赖网络，因此不能跳过屏障。
5. 根据返回的报告综合，不要依赖记忆——重新阅读每个线程的分析文件，然后亲自完成第 4-6 步（Flow Mapping → Analysis → Synthesis）。

**明确标出 SEQ 边界：**如果某个线程的起点是另一线程的发现，它就属于 SEQ，而不是 PAR。“追踪已发布事件的消费者”必须等到“发布了哪个事件”有结果后才能开始——将其放入第 2 轮，并注明它依赖哪项发现。仅仅主题相同（同一功能，不同层）的线程仍属于 PAR。

调查技巧

发现搜索模式

使用 Grep 搜索 {FeatureName}，并组合以下关键词：EventHandler、BackgroundJob、Consumer、Service、Component。

优先级顺序（与技术栈无关的策略）：（1）领域模型（实体／聚合）→（2）用例（命令／查询）→（3）事件处理器（副作用逻辑）→（4）入口点（控制器／API／路由处理器）→（5）跨服务消费者（消息／事件订阅者）→（6）后台任务／调度器 →（7）UI 组件／状态存储 →（8）服务／辅助工具。具体定位方式（文件夹名称、文件 glob、框架标记）因技术栈而异——请根据项目结构参考和项目配置查找。

依赖追踪

后端（追踪这些关系——定位器语法因技术栈而异）： 方法／函数调用方（grep 后端源文件）、依赖注入器（在构造函数或 DI 配置中 grep 接口／类型）、领域事件订阅者（框架的领域事件处理器类型）、跨服务消息处理器（跨服务的消息／事件契约）、仓储／数据访问用法（仓储／数据访问接口）。

前端： 组件使用方（在模板中 grep 组件选择器）、服务导入方（在源文件中 grep 类）、存储／状态链（状态副作用 → API 调用 → 响应处理器 → 状态）、路由（在路由文件中 grep 组件）。具体文件 glob 和框架原语：参见项目的前端参考文档和配置。

数据流映射

按以下格式记录：[入口] → [验证] → [处理] → [持久化] → [副作用]

务必重点追踪：（1）入口点，（2）处理流水线，（3）数据转换，（4）持久化位置，（5）出口点／响应，（6）跨服务消息总线边界。

常见调查场景

问题类型	步骤
“X 是如何工作的？”	入口点 → 命令／查询处理器 → 实体变更 → 副作用
“Y 的逻辑在哪里？”	命令／查询／实体中的关键词 → 事件处理器 → 辅助函数 → 前端存储
“发生 Z 时会怎样？”	找出触发条件 → 追踪处理器链 → 记录副作用及错误处理
“为什么 A 的表现和 B 一样？”	查找代码路径 → 找出决策点 → 检查配置／功能标志 → 记录规则

项目模式识别

后端（在 docs/ 中搜索 backend-patterns-reference）：CQRS 命令／查询、实体事件处理器、消息总线使用者、仓储扩展、流式验证 API、授权属性。

前端（在 docs/ 中搜索 frontend-patterns-reference）：组件基类、视图模型／状态存储基类、带加载／错误状态处理的响应式数据获取副作用、API 服务基类。

图谱智能（存在 graph.db 时必须执行）

务必动态编排 grep → graph → grep：（1）grep 关键术语以查找入口文件，（2）使用 connections／batch-query／trace --direction both 扩展依赖网络，（3）再次 grep 以验证内容。trace 会追踪所有边类型，包括 MESSAGE_BUS 和 TRIGGERS_EVENT。

python .claude/scripts/code_graph connections <file> --json     # Full picture
python .claude/scripts/code_graph query callers_of <name> --json
python .claude/scripts/code_graph query importers_of <file> --json
python .claude/scripts/code_graph query tests_for <name> --json
python .claude/scripts/code_graph batch-query <f1> <f2> --json

证据收集

深度调查范围——必须执行： 将分析写入 .ai/workspace/analysis/[feature-name]-investigation.md。展示调查结果前，务必重新通读整个文件。

结构：元数据（原始问题）→ 进度 → 文件列表 → 知识图谱（根据 SYNC:knowledge-graph-template 为每个文件建立条目）→ 从结果到起点的调试追踪（适用于 Bug／修复／行为变更）→ 数据流 → 调查结果。

规则： 每检查 10 个文件后，务必更新进度，并重新确认调查方向与原始问题一致。

分析阶段

全面分析：（1）正常路径，（2）错误路径，（3）边缘情况，（4）授权检查，（5）各层验证。提取：核心业务规则、状态转换、副作用。

综合整理： 执行摘要（1 段回答、排名前 5–10 的关键文件、所用模式）＋逐步讲解，并附 file:line 引用和流程图。

输出格式

务必包含：（1）直接回答（1–2 段），（2）带 file:line 引用的“工作原理”逐步说明，（3）关键文件表格，（4）数据流图，（5）“想进一步了解？”子主题。

对于 Bug、验证失败或行为变更调查，务必另外包含：

### Debugger Trace: End -> Start

- Observed final state:
- Final reader/query/renderer/assertion:
- Backward hops: reader -> storage/projection/cache -> writer -> consumer/handler/job -> producer/origin
- Feeder paths scanned:
- Unknown or unverified paths:

### Hypothesis Matrix

| RC  | Hypothesis | Evidence for | Evidence against | Status | Verification |
| --- | ---------- | ------------ | ---------------- | ------ | ------------ |

指南

• 基于证据——每项结论都需要代码证据；未经验证的内容必须标记为“推断”
• 聚焦问题——始终将发现与原始问题联系起来
• 只读——除非用户明确要求，否则绝不建议修改
• 分层呈现——先从简单内容开始，按需提供更深入的细节

相关技能

scout（预发现）| workflow-feature（实现）| debug-investigate（调试）| graph-query（自然语言查询）

---

模式：Explain（开发者叙述）

触发方式： $investigate --mode=explain [target]。仅手动触发——绝不会自动插入工作流。独立的提示词驱动解释器请使用 $understand [target]。

与默认 investigate 模式的区别：只改变交付内容的受众、形式和写入目标。证据门槛完全相同，且不可妥协——对代码和计划严格实行只读；每项具体结论都必须引用 file:line；下结论前，必须至少对关键文件运行一条图命令；置信度必须 >80% 才能断言。Explain 模式绝不会放宽任何一项要求。如果叙述中的某个观点缺少 file:line 证据，必须像默认模式一样将其准确标记为“推断”。

目标：通过清晰、详尽、单向的解释，让开发者理解这项工作，包括它是什么、其目的（为何存在）、如何运作（机制），以及为何采用这种方式（权衡与被否决的替代方案）。AI 根据提示词推导要解释的内容。没有固定议程；范围随点名内容灵活调整。

约定（请先阅读）

• 根据提示词推导范围。如果没有指定目标，则默认为当前工作上下文：进行中的任务（当前任务列表）+ 工作树更改（git diff --name-only + 通过 git ls-files --others --exclude-standard 获取的未跟踪文件）+ 当前计划 / 最新的 $watzup 摘要（如果存在）。
• **绝不向用户提问。**严格采用单向方式：不要求用户复述、不进行测验、不直接向用户提问、不提出澄清问题、不设置理解门槛。推断最可能的目标，用一句话说明假设，然后继续。（技能预处理中的工作流检测门槛是另一回事；开发者明确调用此技能时，该门槛已被豁免。）
• **选择加入，绝不阻塞。**解释后即结束。绝不让开发者陷入循环；绝不阻碍提交、实现或工作流进展。
• **始终完整解释，不受编码水平影响。**始终涵盖目的、原理和原因。编码水平只用于调整词汇和类比的密度（通俗易懂 ↔ 面向专家的简洁表达），绝不决定_是否_解释，也绝不删减这三个部分。
• **解释整个范围，优先讲不直观的内容。**涵盖范围内的所有内容，但按影响程度排序——先讲影响范围最大、未来更改成本最高或最令人意外的部分；样板代码和 CRUD 内容则简要说明。不得默默省略任何内容。
• **仅写入项目根目录下的临时文件夹。**绝不编辑源文件或计划文件；绝不写入 .ai/workspace/analysis/... 分析文件。唯一写入目标是 tmp/understand/{branch}.md 中的台账（见步骤 E3）。

步骤 E0 — 确定范围并读取风格档位

1. 根据提示推断范围：

   提示信号	要解释的范围
   直接调用，未指定目标	默认：当前工作上下文 — 活跃任务 + 工作树变更 + 活跃计划 / 最新 $watzup。
   指定变更集 / PR /“我刚做了什么”	差异及其原因。
   指定计划 /“方案” /“开始构建之前”	活跃计划：问题、方案、已否决的替代方案、风险、阶段顺序。
   指定子系统 / 文件 / 功能 /“X 是如何工作的”	对应代码路径 — 读取文件、运行图追踪、解释流程。
   指定单个决策 /“为什么选 X 而不是 Y”	该决策及其权衡。
   指定概念 / Bug / 错误	该概念或根本原因。
   含糊不清 / 有多个合理目标	不要提问。 推断最可能的目标（默认当前上下文），用一句话说明假设，然后继续。

   继续之前，用一句话说明确定的范围（例如：说明：当前工作中的变更（3 个文件）+ 活跃任务 #42）。

2. 读取风格档位（这不是跳过关卡）。 按顺序采用找到的第一个编码水平：环境变量 CK_CODING_LEVEL → .claude/.ck.json 中的 codingLevel → 默认 3。档位只调整解释的表达方式 — 绝不能省略目的、做法或原因。5/-1 上帝模式（简洁，开篇说明不直观的权衡）· 4 技术负责人（简洁，说明设计权衡）· 3 资深工程师（均衡）· 2 中级工程师（更详尽地说明机制）· 1 初级工程师（先说明原因，再说明做法，逐步讲解）· 0 ELI5（每次讲一个概念，使用类比）。用一句话说明档位，然后进行解释。不要提供跳过选项；不要提问。

步骤 E1 — 收集材料（与范围相称）

• 当前工作上下文： 当前任务列表；git diff --name-only（加上未跟踪文件）；活跃计划 + 最新 $watzup。提取：正在处理的内容、变更内容、变更原因、新行为。
• 计划： 读取 plan.md + phase-*.md。提取：问题、选定方案、已否决的替代方案、设计决策、风险、阶段顺序。
• 子系统 /“X 是如何工作的”： 读取文件；运行 python .claude/scripts/code_graph trace <file> --direction both --json。提取：入口、数据流、关键不变量。
• 单个决策： 相关代码及原因（注释、git blame、计划的替代方案部分）。

不要为了说明一个决策而读取整个仓库。

步骤 E2 — 按影响力排列主题

涵盖整个范围；这里只用于确定顺序。影响范围（运行 $graph-blast-radius 或对关键文件执行图追踪 — 影响面越大，越优先、解释越深入）· 未来变更成本（架构、公共契约、跨服务消息、共享层 / 框架层 — 优先级越高）· 意外程度（指出任何称职的工程师都不会预料到的内容）。样板代码 / 生成内容 / 机械式重命名用一句话提及。

步骤 E3 — 维护理解记录

[硬性规则] 仅将记录写入项目根目录的临时文件夹——绝不能写入 .claude/、源代码树或任何受版本控制的路径。

路径：tmp/understand/{branch}.md（如果项目已使用 temp/，则使用 temp/understand/{branch}.md）。如果 understand/ 子目录不存在，则创建它。{branch} = 当前 Git 分支名称，将 / 替换为 -。确保临时文件夹已被 Git 忽略。

[宣布——聊天内容才是交付物] 理解内容应体现在聊天中的说明，而不是文件中。每次写入或追加记录时，都要在行内说明路径（理解记录已更新 → tmp/understand/{branch}.md）。绝不能让说明内容只存在于临时文件中。

追加（绝不覆盖）一个包含以下三个分组的检查清单：问题（存在原因、此前的局限、各个分支）· 解决方案（设计、业务逻辑、边界情况、为何选择此方案而非其他方案）· 影响（变化内容和受影响对象、影响范围、后续事项）。

步骤 E4 — 说明：目的 → 运作方式 → 原因（交付物）

按以下顺序在聊天中交付，适用于每个层级（根据 E0 调整深度和术语；所有部分都必须包含）。每个具体断言都要引用 file:line。

1. 内容 — 用一句话说明对象及其所在位置。
2. 目的（存在原因） — 说明它解决的问题，以及此前的局限或促使其成为必要方案的其他分支。从这里开始。
3. 运作方式（机制） — 逐步说明流程：入口、数据流、关键不变量、调用关系（使用图谱追踪）。展示代码路径、业务逻辑以及已处理的边界情况。
4. 为何采用此方案（权衡） — 说明为何选择此方案而非显而易见的替代方案；它带来了什么成本和收益，以及现在有哪些决策已变得难以逆转。明确指出不那么显而易见的决策（“我们选择了 X 而非 Y，因为 Z”）。
5. 影响（影响范围与后续事项） — 说明变化内容和受影响对象、上游和下游影响，以及待跟进事项。

对于任何较难理解的内容，主动提供更简单的表述或类比。可以回应开发者的 eli5/elii 后续请求，但禁止由你向他们提问。

步骤 E5 — 回顾并结束（不提问、不循环）

将记录条目标记为 explained。用 2–3 行进行总结（用一句话说明目的，用一句话说明关键机制，再用一句话说明影响最大的权衡或影响范围）。到此结束。不要提问，不要要求开发者复述，不要循环，也绝不要阻碍下一步。

不适用于： 没有构建或计划任何需要理解内容的调查、文档、设计或研究工作；将理解强行设为硬性门槛；代码质量审查（请使用 $code-review、$changes-review）。

反合理化：“资深开发者可以跳过”→ 无论级别如何，都绝不能跳过。·“我来考考他们”→ 只能单向说明，绝不提问。·“有歧义——我先问选哪个”→ 推断并说明假设，然后继续。·“把所有内容都倾倒出来”→ 先确定范围，再按重要性排序。·“跳过权衡”→ 必须说明为何采用此方案。·“把记录交给技能处理”→ 仅使用 tmp/understand/{branch}.md。·“写完文档就悄悄继续”→ 聊天内容才是交付物；必须告知记录路径。

---

调查与建议协议

在建议代码更改（删除、重构、替换）时适用。必须完整完成全部验证链。

验证链（绝不能跳过步骤）

完成所有步骤之前，绝不能建议更改代码：

1. 确定接口/API → 2. 找出所有实现 → 3. 追踪所有注册位置 → 4. 核实所有使用位置 → 5. 评估跨服务影响（所有服务）→ 6. 评估影响 → 7. 声明置信度 → 只有此后才能输出建议。

如果任何一步尚未完成 → 停止。 声明：“证据不足，无法提出建议。”

破坏性变更风险矩阵

风险	标准	必需证据
HIGH	移除注册项、删除类、更改接口	完整使用情况追踪 + 影响分析 + 跨服务检查（所有服务）
MEDIUM	重构方法、更改签名	使用情况追踪 + 测试验证 + 跨服务检查
LOW	重命名变量、格式调整、注释	仅需代码审查

移除检查清单（必须全部通过）

• 没有静态引用（rg "ClassName" {configured-source-roots} 未发现有效引用）
• 没有字符串字面量／动态调用（反射、工厂、消息总线）
• 没有 DI 注册项（services.Add*<ClassName>）
• 没有配置引用（appsettings、环境变量）
• 没有测试依赖
• 已检查跨服务影响（所有微服务）

检查清单未完成 → 声明： Confidence: <90% — did not verify [missing items]

证据层级

（1）代码证据（grep/read）→（2）测试证据 →（3）文档 →（4）推断。严禁仅基于推断提出建议——必须将证据升级为代码证据。

置信度等级

95-100% 完整追踪 + 所有服务 | 80-94% 已验证主要路径 | 60-79% 部分追踪 | <60% 不要提出建议

格式： Confidence: 85% — Verified main usage in ServiceC, did not check ServiceA/ServiceB

服务对比模式

找到可正常工作的参考实现 → 对比实现 → 找出差异 → 验证每项差异存在的原因 → 根据已证实的模式提出建议，绝不基于假设。

---

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

• docs/project-reference/domain-entities-reference.md — 领域实体目录、关系、跨服务同步（任务涉及业务实体／模型时）。

从结果到起点的调试追踪 — 对于复杂 Bug、验证失败、回归修复、行为变更代码或代码流不明确的情况，先从观察到的最终状态开始，反向追踪后再提出修复方案。

1. 帧 0：观察到的最终状态 — 明确指出用户可见的输出、失败的断言、日志行、持久化值、API 响应、渲染的 UI 或聚合分桶。用 file:line 证据记录生成该结果的读取器／查询／渲染器。
2. 一次反向追踪一跳 — 按以下顺序追踪：最终读取器 -> 投影／缓存／存储 -> 写入器 -> 消费者／处理器／作业 -> 生产者／调用方 -> 原始触发源。在每一跳记录：输入、转换、输出、所有者和证据。
3. 列举所有上游路径 — 找出所有可能写入最终路径的上游生产者／调用方／事件／作业，包括重试、异步、缓存、后台和其他 UI／API 路径。将每条路径标记为已验证、已排除或仍未知。
4. 建立假设矩阵 — 对每个可能的原因，列出支持证据、反对证据、如何复现／验证、影响范围和状态（primary、contributing、ruled out、latent）。在明确排除或限定其他可能原因之前，不要修复。
5. 选择修复所属层 — 确定不变量的所有者，以及能够保护所有下游消费者的最低共享层。除非症状出现的位置拥有该不变量，否则不接受在该位置修复。
6. 正向证明收敛 — 选定修复方案后，再次从起点追踪到终点，说明修正后的状态如何到达观察到的最终输出。将每个根本原因对应到修复部分，并将每个修复部分对应到测试／证明。

以下条件全部满足前不得继续： 已明确最终状态 · 已编写反向追踪 · 已列举所有上游路径 · 已完成假设矩阵 · 已论证修复所属层 · 已将正向收敛证明对应到测试。

绝不： 从第一个可疑代码路径开始。将多个生产者合并成一个“流程”。未经证明就把重复症状视为重复记录。跳过已排除的假设。

> **知识图谱模板** — 对每个分析的文件，记录：filePath、type（entity、command、query、event handler、controller、consumer、component、store、service 或存储库特定的等效类型）、architecturalPattern、content summary、symbols、dependencies、businessContext、referenceFiles、relevanceScore（1-10）、evidenceLevel（verified/inferred）、abstractions 和 moduleContext。调查字段：entryPoints、outputPoints、dataTransformations、errorScenarios。消息字段：messageName、messageProducers、crossBoundaryIntegration。UI 字段：componentHierarchy、stateManagementStores、dataBindingPatterns、validationStrategies。

根本原因调试 — 采用系统化方法，绝不靠猜测和反复试错。

1. 复现 — 用证据确认问题存在（错误消息、堆栈跟踪、截图）
2. 隔离 — 使用二分查找和图追踪，将范围缩小到具体文件／函数／行
3. 追踪 — 从输入到故障点追踪数据流。阅读实际代码，不要推断。
4. 提出假设 — 提出理论并注明置信度百分比。说明支持或反驳该理论的证据
5. 验证 — 使用有针对性的 grep／读取来检验假设。一次只改变一个变量。
6. 修复 — 解决根本原因，而非症状。通过图中的 connections 验证修复不会破坏调用方

绝不： 在没有证据的情况下猜测。只修复症状而不解决原因。跳过复现步骤。 嵌套任务展开约定 — 调用工作流步骤时，[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. 首先读取 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. 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 设计、调试、架构）、高级技术（螺旋式改进、假设检验、收敛）和元策略（不确定性处理、修正级联）。 先理解代码 — 硬性门槛：阅读现有代码之前，不要编写、规划或修复。

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. 现有模式可用时，绝不要臆造新模式——严格遵循现有模式，或记录偏差。——原因：不同的模式会割裂代码库，并拖慢每位后续读者

在以下条件满足之前，禁止继续： - [ ] 已阅读目标文件 - [ ] 已搜索 3 个以上模式 - [ ] 已执行图谱追踪（如果 graph.db 存在） - [ ] 已通过证据验证假设

借助图谱进行调查 — 当 .code-graph/graph.db 存在时，必须执行。

硬性门槛： 在结束任何调查之前，必须至少对关键文件运行一条图谱命令。

模式： Grep 查找文件 → trace --direction both 揭示完整系统流程 → Grep 验证细节

任务	最低图谱操作
调查/侦察	对 2-3 个入口文件执行 trace --direction both
修复/调试	对有问题的函数执行 callers_of，并执行 tests_for
功能/增强	对要修改的文件执行 connections
代码审查	对已更改的函数执行 tests_for
影响范围	执行 trace --direction downstream

命令行： python .claude/scripts/code_graph {command} --json。先使用 --node-mode file（噪声少 10-30 倍），再使用 --node-mode function 查看细节。

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

边界	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 的默认行为：在 A 处看到错误 → 在 A 处修复。这是错误的。崩溃现场是症状，不是原因。

任何修复前，必须：

1. 追踪完整数据流——梳理数据从源头到崩溃现场经过的所有层级的完整路径（存储 → 后端 → API → 前端 → UI）。找出错误状态从哪里进入，而不是它在哪里崩溃。
2. 确定不变量的负责方——哪个层级的契约保证该值有效？该层级就负有责任。在负责该不变量的最低层级修复，而不是在使用该值的最高层级修复。
3. 一次修复，最大程度防护——问自己：“在这里修复，能否通过一次更改保护所有下游使用方？”如果修复需要修改 3 个以上文件并添加防御性检查，那说明你选错了层级——应该再往下找。
4. 确认不存在绕过路径——确认所有数据流都会经过修复点。检查以下情况：绕过工厂直接构造、克隆／展开时未重新验证、原始数据未封装到领域模型中、在模型层之外进行修改。

完成以下各项前，禁止继续： - [ ] 已追踪完整数据流（源头 → 崩溃现场） - [ ] 已根据 file:line 证据确定不变量的负责方 - [ ] 已审查所有访问点（grep 计数） - [ ] 已论证修复层级合理（能保护最多使用方的最低层级）

反模式（必须拒绝）：

• “在崩溃处修复”——崩溃现场 ≠ 原因所在。向上游追踪。

• “在每个使用方都添加防御性检查”——分散防护 = 层级错误。一个权威修复 > 多处零散防护。

• “两边都修复更安全”——选择一个权威层级。在多个层级重复检查，会让人无法明确由谁负责该不变量。

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

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

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

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

• 强制重要注意： 存在 graph.db 时，至少对关键文件运行一条图命令。模式：grep → graph trace → grep 验证。

• 强制重要注意： 每项主张都要引用 file:line 证据。置信度 >80% 才能采取行动；<60% 时，不要提出建议。

• 强制重要注意： 按文件记录：类型、模式、符号、依赖项、relevanceScore、evidenceLevel。

重要注意： 追踪完整的数据流，并在所属层修复问题，而不是在崩溃发生处修复。添加 ?. 之前，审查所有访问点。

务必注意： 运用批判性思维和顺序思维——每项主张都需要适当的追踪证据（仓库／代码主张需提供 file:line；研究、产品、内容和文档主张需提供源 URL 或产物章节）；置信度 >80% 才能采取行动，<60% 时不要提出建议。防止幻觉：绝不要把猜测说成事实；坦然承认不确定性；通过独立来源交叉核对；对自己的判断保持怀疑。

务必注意： 运用 sequential-thinking——多步骤任务使用 Thought N/M、REVISION/BRANCH/HYPOTHESIS 标记，并注明更精确的置信度百分比；参见 $sequential-thinking skill。

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

• 强制要求： 在开展目标工作前，先初始化任务跟踪；一次只推进一项任务。
• 强制要求： 将计划／审查结果逐步保存到 plans/reports/，并基于磁盘上的内容综合整理。
• 强制要求 在调查、规划或编码之前，先阅读 docs/project-config.json（项目地图：模块/路径、运行命令、约定、架构/工作流规则）以及必需的项目参考文档，并注明 Reference docs read: ...。
• 强制要求 始终包含 lessons.md；项目配置和约定优先于通用框架默认设置。
• 强制要求 如果项目配置、根目录指令文件或任何必需的参考文档缺失或已过时，须自动运行 $project-init 或范围更窄的下层流程，然后再开展常规的项目特定工作。

重要：务必注意 调试跟踪门槛：对于非简单的 Bug 修复、调查或审查工作，应从观察到的最终输出开始，沿着 reader → storage/projection → writer → consumer/job → producer/trigger 反向追踪。修复前须列出所有输入路径和假设。在跟踪、假设矩阵、负责修复的层，以及正向收敛证明全部具备之前，禁止继续。

• 强制要求 父工作流中的条目不能替代子阶段跟踪；存在嵌套时，须展开各阶段并关联父项。
• 强制要求 编排器须在调用前预先展开子技能阶段；使用 [N.M] $skill-name — phase 前缀，并遵守同一时间仅一个阶段为 in_progress 的原则。

并行子 Agent 分派 — 一旦有了任务拆解，就立即规划并行任务，且必须在执行前完成；按顺序执行可证明彼此独立的任务会浪费实际耗时。适用于所有多步骤工作：工作流步骤、规划、批量更新、调查、研究、扫描、审查、文档同步。执行计划受元数据约束，绝不默认并行——仅按照计划声明的内容（PAR/SEQ 标签和各阶段写入集）扇出；未标注的计划按顺序执行——原因：推导出的写入集无法发现级联写入或生成的写入。

1. 为每项任务标注 PAR 或 SEQ。 PAR = 输入不依赖任何待处理任务的输出，且写入集与其他所有 PAR 任务互不重叠。否则标为 SEQ——务必说明导致顺序执行的依赖关系。
2. 将 PAR 任务分组成多个波次。 同一波次中的任务之间不得存在依赖边。两个会写入同一文件的任务绝不能处于同一波次。只读工作（搜索、调查、审查、研究）可自由并行。
3. 分派前声明： Parallel plan: wave 1 = [...] · wave 2 = [...] · SEQ = [...] (reason)。
4. 在一条消息中启动每个波次——每个 spawn_agent 调用都必须位于同一条回复中，绝不能分散到多轮。根据任务将其分派给相应的专业 Agent（.claude/skills/shared/sub-agent-selection-guide.md）；绝不能把 code-reviewer 当作通用选项。
5. 为每个子 Agent 提供完整独立的任务说明： 目标 · 范围 + 负责的文件 · 参考文档 · 返回要求（摘要 + Full report: 路径，遵循 SYNC:subagent-return-contract）· 增量持久化到 plans/reports/（遵循 SYNC:incremental-persistence）。
6. 每个波次都设置屏障。 只有在所有成员都返回后才能继续（跳过的条件任务也视为已返回）。合并结果，将每项任务标记为已完成/已跳过，然后再分派下一波。修改步骤必须等待屏障。
7. 最多嵌套一层。 已分派的子 Agent 执行其自身的任务说明；除非其 .claude/agents/*.md 定义授权进一步扇出，否则后续扇出由编排器负责。

绝不要并行处理： 写入目标相同的任务 · 消费待处理任务输出的任务 · 简单的单文件工作（分派开销大于收益）· 技能或工作流明确规定顺序的任务 · 等待用户批准的门槛。

在以下条件满足前禁止继续： 务必为每项任务标注 PAR/SEQ，并为每项 SEQ 任务说明原因 · 声明各波次并检查写入集互不重叠 · 每个波次均在一条消息中启动 · 进入下一波前遵守屏障。

• MANDATORY 规划任务后，为每个 PAR/SEQ 添加标签，并在一条消息中将每个 PAR 波次作为并行子代理启动——工作流、批量更新、调查、研究、评审默认并行；计划执行仅针对计划中声明的内容展开。
• MANDATORY 每个波次的写入范围互不重叠 · 所有子代理返回后才能进入下一波次 · 按专业方向分配任务 · 除非子代理自身的 Agent 定义授权，否则绝不继续派生子代理。

Project Protocol Overlay — 执行此技能前，先解析叠加到此技能上的所有 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 纪律、评审关卡或用户确认关卡。若覆盖规则与技能规则确实冲突，或两个具体程度相同的覆盖规则直接矛盾 -> 向用户说明两者；绝不可默默自行裁决。

MUST ATTENTION 执行前必须解析此技能的项目协议覆盖规则——仅采用最具体的匹配层级（精确 > glob > *；此优先级仅用于排列各覆盖规则之间的顺序，绝不凌驾于此技能之上）；只读取 <protocols-dir>/<Name>.md 中匹配的正文；正文缺失或格式错误时必须报告，绝不可重建。覆盖规则仅可补充（绝不替换此技能自身的规则），且只是简要说明，绝不可提升权限；具体程度相同的规则若相互矛盾，则交由用户处理。

收尾提醒

IMPORTANT MUST ATTENTION Goal： 对现有代码的工作方式形成有证据支撑的理解——严格保持只读，每项陈述都必须可追溯至 file:line，或明确标记为“推断”——确保下一步决策或更改基于经验证的系统流程，而非假设。

IMPORTANT MUST ATTENTION — 当前生效的协议（此技能所含 SYNC/共享区块的简要摘要；每行仅作指引，以上规范正文具有约束力）：

• 端到端调试追踪： 从观察到的最终状态出发，反向追踪，并在修复前构建假设矩阵。
• 知识图谱模板： 按文件记录类型、模式、符号、依赖项、相关性和证据等级。
• 根因调试： 复现、隔离、追踪、提出假设、验证并修复原因——绝不靠猜测和试错。
• 嵌套任务创建： 展开子阶段任务；存在嵌套时，关联父工作流行。
• 项目参考文档指南： 先阅读必需的项目文档；项目约定优先于通用默认设置。
• 任务跟踪与外部报告： 初始化任务拆分；将计划和审查发现逐步保存到磁盘。
• 批判性思维： 追溯每项声明，置信度 >80% 才采取行动，绝不把猜测当作事实。
• 顺序思维： 采用多步 Thought N/M，并使用修订／分支／假设标记及置信度收尾。
• 先理解代码： 编写、规划或修复之前，MUST ATTENTION 阅读代码并 grep 至少 3 个模式。
• 图辅助调查： 如果 graph.db 存在，则对关键文件运行一条图命令。
• 跨服务检查： 扫描生产者、消费者、saga 和契约——缺少消费者会造成无提示回归。
• 修复层责任： 追踪完整数据流，在负责的层修复，而非在崩溃位置修复。
• 源代码／测试漂移检查： 源代码行为发生变化时，检查受影响的测试是否符合预期行为。
• 防止 AI 出错： 根据证据验证生成内容，追踪下游引用，验证所有受影响的输出，在上下文丢失后重新阅读，并明确指出歧义。
• 并行子 Agent 调度： 为任务标注 PAR／SEQ，将 PAR 任务按互不重叠的写入集分组为多个批次，在一条消息中启动每个批次，并在继续之前设置屏障。

重要：MUST ATTENTION 严格保持只读——调查期间绝不编辑代码、计划或规范；只交付发现。原因：调查一旦修改状态，就不再是调查，还会破坏后续步骤所依赖的基线。 重要：MUST ATTENTION 每项声明都要注明 file:line；将未经验证的陈述标为“推断”——置信度 >80% 才采取行动，<60% 时绝不提出建议。原因：未标注的猜测会被当作事实，并传播到下一步决策中。 重要：MUST ATTENTION 下结论前，至少对 2-3 个关键文件运行一条 code_graph 命令——图能呈现 grep 单独无法发现的调用方、总线消费者和导入方（子 Agent 不能使用图；只有主 Agent 可以）。原因：grep 只能看到文本，看不到决定实际影响范围的调用／事件／导入关系。

• 强制重要务必注意：开始前，使用任务跟踪将工作拆分为小型待办任务；将一项标记为 in_progress，并在其证据出现后立即完成该项。
• 强制重要务必注意：阶段 0：行动前先分类范围（快速／深入／调试／建议）——分析深度、分析文件和验证链都由此决定；跳过任何步骤前，必须声明范围。
• 强制重要务必注意：按顺序执行主要步骤——分类 → 探索 → 图谱扩展 → 知识图谱 → 流程映射 → 分析 → 综合 → 呈现；快速范围可以跳过分析文件，但绝不能跳过图谱命令——原因：每一步都会为下一步提供依据，跳过图谱会导致调用／事件／导入关系未得到映射。
• 强制重要务必注意：--mode=explain → 提供单向的开发者叙述（是什么 → 目的 → 如何实现 → 为何如此设计 → 影响），并根据编码水平调整；写入被 git 忽略的 tmp/understand/{branch}.md（聊天内容即为交付物——告知记录文件路径）；绝不向用户提问，绝不因编码水平而跳过步骤，绝不放宽证据／图谱／只读门槛——原因：explain 模式只改变交付物的形式，不改变证据规范。
• 强制重要务必注意：先阅读必需的项目文档（始终阅读 lessons.md；架构相关内容还需阅读 project-structure-reference.md）——项目约定优先于通用框架假设——原因：本地模式与框架默认设置不同，通用推理可能因此悄然失效。
• 强制重要务必注意：搜索至少 3 个相似模式，并在下结论前阅读实际实现——绝不假设代码会像名称所说的那样工作；务必通过阅读验证——原因：名称所承诺的行为，实际实现未必具备。
• 强制重要务必注意：复用附近示例前，先评估模式是否适用——确认新上下文具有相同的基类、范围、生命周期和前置条件——原因：最近的示例不等于约束条件匹配的示例。
• 强制重要务必注意：深入范围 → 将分析写入 .ai/workspace/analysis/[feature]-investigation.md；呈现前重新阅读整个文件（长时间处理后绝不能凭记忆作答）。
• 强制重要务必注意：建议范围 → 在提出任何代码变更建议前，完成验证链的所有步骤（实现 → 注册 → 使用情况 → 跨服务影响 → 置信度）；任何步骤未完成 → 停止并说明“证据不足，无法提出建议。”
• 强制重要务必注意：微服务／事件驱动场景 → 扫描范围内的生产者、消费者、Saga 和共享契约——遗漏下游消费者会导致静默回归。
• 强制重要务必注意：调查 Bug／行为变更 → 下结论前执行从终态到起点的调试追踪（观察到的最终状态 → 反向跳转 → 上游路径 → 假设矩阵 → 负责修复的层）；询问“由谁负责？”，并找到不变量的所有者，而不是崩溃发生的位置。

避免自我合理化：

规避理由	反驳
“简单调查，不用看图”	图能揭示调用方和总线使用者，这是 grep 找不到的。无论如何都要运行。
“已经 grep 过了，证据够了”	提供 file:line 证明。没有引用就没有证据；未经验证的内容标记为推断。
“任务简单，不用跟踪任务”	仍然需要跟踪。创建任务，并立即标记为完成。
“建议显而易见，不用走验证流程”	无论置信度如何，都适用风险矩阵。完成所有步骤，否则停止。
“这个任务做深度调查太浪费时间”	先分类。如果是快速任务，可以，但跳过步骤前必须声明范围。
“附近的示例足够接近，直接照着复制”	最接近 ≠ 前置条件匹配。先核实基类、作用域和生命周期。
“我顺手修复发现的问题就好”	只读。调查期间绝不修改；将发现交给修复步骤。

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

重要，务必注意 始终只读 · 引用 file:line，或标记为“推断” · 得出结论前运行一条图命令——这三项约束适用于所有范围和模式。

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