code-simplifier

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

快速摘要

目标： 降低下次修改的成本——通过简化和优化代码，提高其清晰度、一致性和可维护性，减少耦合、隐式状态、重复知识和模糊意图，同时不改变任何可观察到的行为。——原因：每次简化都应服务于降低未来的修改成本，而非追求美观。

摘要：（只读这一部分也能了解的摘要——目的 + 所有主要步骤）

• 目的——先怀疑、再行动的变更器，而非建议者： 修改前先 grep 所有用法并追踪使用方（存在 graph.db 时，追踪图中的下游节点），并引用 file:line；只有确信能保留行为时才进行简化，不确定时绝不动手。——原因：未经验证的“安全”改写可能悄无声息地破坏下游使用方。
• 主要步骤，按顺序执行：（1）阶段 0：检测工件类型（后端/前端/测试/配置）和范围；（2）识别目标——近期 git 变更或指定文件，严格跳过生成文件/迁移文件/vendor；（3）通过 5 个简化维度进行分析；（4）一次只应用一种重构类型（KISS/DRY/YAGNI，保持行为不变）；（5）每次变更后都验证相关测试；（6）自递归循环（分析→简化→验证），直到没有发现问题，或遇到无进展/不安全/需要负责人决策的情况而停止——不要为自己的发现另起一个全新上下文的审查者；（7）自审查关卡。
• 5 个简化维度（步骤 3）： 可读性 · DRY/抽象（≥3 处重复，需通过 YAGNI 检查）· 职责下沉至最合适的层（Entity > Domain Service > App Service > Controller）· 降低复杂度（扁平化嵌套，提取超过 20 行的方法）· 数据库分页 + 索引——每种方法都要回答同一个问题：这是否能降低下次修改的成本？
• 自审查关卡（步骤 7）——此技能负责审查自己的产出： 只要修改了任何文件，就针对仅限这些变更文件自行调用 $code-review（可安全递归的叶节点——绝不调用 $changes-review）；如果没有变更，则跳过并记录原因。——原因：简化器会在主要审查批次结束后改写代码，因此没有这个关卡，它的产出就会未经审查而交付。
• 先阅读： 修改前先阅读 docs/project-reference/code-review-rules.md（反模式/检查清单），然后阅读 project-structure-reference.md。

强制重要事项： 计划任务时必须阅读：

• docs/project-reference/code-review-rules.md — 反模式、审查检查清单 （首先阅读）
• project-structure-reference.md — 项目模式/结构

如果找不到，请搜索项目文档、编码规范、架构文档。

工作流：

1. 阶段 0：检测 — 判断工件类型（后端/前端/测试/配置）和范围
2. 识别目标 — 近期 git 变更或指定文件（跳过生成文件/vendor）
3. 分析 — 应用简化维度（见下文）
4. 应用 — 遵循 KISS/DRY/YAGNI，一次只进行一种重构
5. 验证 — 运行相关测试，确认行为未变
6. 自递归检查 — 重新运行此技能的简化分析，直到没有剩余的简化发现
7. 自审查关卡（代码有变更时必须执行） — 如果此技能修改了任何文件，就针对仅限这些变更文件自行调用 $code-review；如果没有变更，则跳过并记录原因

关键规则：

• 保留所有现有功能——不得改变行为
• 遵循项目中记载的模式（实体表达式、流畅辅助方法、存储基类、BEM）
• 对源文件而言，易于修改是首要的简化目标；只有在能减少未来的编辑位置或认知负担时，DRY、SOLID、抽象和模式才适用
• 每次变更后都要确保测试通过
• 只有确信能保留行为时才进行简化——不确定时绝不进行

阶段 0：制品检测

**务必注意：**先分类，再进行简化——检测只用于确定关注重点，以及是否需要可选升级审查：

制品类型	检测方式	重点关注
后端	当前技术栈的后端源文件（例如 .cs）	领域模型表达式、流式 API、通过面向对象编程实现 DRY、SOLID
前端	当前技术栈的前端源文件（例如 .ts、.html、.scss）	BEM、store 基类、订阅清理、组件基类
测试	当前技术栈的测试源文件（例如 *Test.cs、*.spec.ts）	断言、异步断言辅助工具（例如轮询直到条件满足的辅助工具）、数据隔离
配置/生成文件	迁移文件、生成文件/供应商文件（例如 *.generated.*）	跳过——绝不简化生成代码/迁移代码

按制品类型进行可选升级审查：

制品	仅在以下情况下升级审查
源代码/差异	简化循环完成且无问题后，才应要求全面审查
安全敏感内容	存在特定安全风险时
性能关键内容	变更涉及性能行为时
计划/文档/规范	明确要求审查该制品时

首要原则——易于变更

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

评估代码、重构、测试或抽象时，请问： 这会让下一次变更的成本更低，还是更高？

• 拒绝会提高变更成本的“最佳实践”（过早抽象、 推测性通用化、泄漏式间接层、没有收益的繁文缛节）。
• 在审查结果中指出真正的问题：耦合、隐藏状态、重复的 知识、意图不清、过早暴露的不可逆决策。
• 优先在项目与外部库之间建立由项目掌控的边界，例如组件/服务的输入输出契约， 前提是这些边界能将未来的库变更限制在局部；拒绝那些只增加繁文缛节、 却无法降低变更成本的透传包装器。
• 易于变更的简单设计，胜过难以变更的复杂设计。

在应用以下任何具体规则、模式或检查清单之前，都要先运用这一原则—— 如果后续规则会提高变更成本，则以本原则为准。

---

简化思维

**先质疑：**先验证，再简化。每项变更都必须证明其保留了原有行为。

• 绝不假设代码是冗余的——先追踪调用路径并阅读实现
• 删除或替换之前：搜索所有用法，确认没有任何内容依赖当前形式
• 指出违反约定之前：搜索至少 3 个现有示例——以代码库约定为准
• 每项简化都必须提供 file:line 证据，说明已验证的内容
• 仅在确定能够保留行为时才进行简化；如果不确定 → 不要简化

简化维度

基于维度的推理取代固定检查清单。每个维度都包含一个 Think: 提示，要求从基本原理出发进行推理。

维度 1：可读性

思考： 新工程师能在 30 秒内看懂吗？是什么导致他们必须追踪多个文件？

• 架构可见性：计算数据结构的函数需要有输出结构注释
• 不直观的管道：对于 A→B→C 转换，需要简要说明处理流程
• 自描述签名：参数应说明其作用；移除未使用的参数
• 魔法值：用具名常量替换未解释的数字或字符串
• 命名清晰：无需阅读实现即可了解名称表达的意图

维度 2：DRY 与抽象

思考： 是否有某种模式出现 ≥3 次？什么基类/泛型可以消除重复？

• 后缀相同的类（*Entity、*Dto、*Service）→ 提取共享基类
• 重复的逻辑块 → 提取为辅助方法/扩展方法
• YAGNI 门槛：绝不要为了假设的未来用途进行提取——至少需要出现 3 次

维度 3：恰当的职责归属

思考： 逻辑是否位于能够承担该职责的最低层？将它下移能否实现复用？

• Entity/Model → Domain Service → Application Service → Controller（逻辑应属于最低层）
• 控制器中的业务逻辑 → 下移
• 处理器中的映射 → 移至 DTO 方法

维度 4：降低复杂度

思考： 认知负担有多大？能否简化嵌套/条件判断？

• 嵌套 >3 层 → 重构（提前返回、提取方法）
• 方法超过 20 行 → 提取方法
• 复杂条件判断 → 简化或采用 Strategy 模式（仅在分支出现 3 次以上时）

维度 5：数据库性能

必须注意：重要，务必遵守

1. 分页： 所有列表查询都必须分页。绝不能在没有 Skip/Take 或基于游标的分页时使用无界的 GetAll()、ToList()、Find()。
2. 索引： 所有筛选字段、外键、排序列都必须有数据库索引。实体表达式必须与索引字段顺序一致。集合需要索引管理方法。

项目模式

后端

• 提取实体静态表达式（搜索：entity expression pattern）
• 使用流式辅助方法（搜索：docs/project-reference/backend-patterns-reference.md 中的 fluent helper pattern）
• 将映射移至 DTO 映射方法（搜索：DTO mapping pattern）
• 使用项目的流式验证 API（参见 docs/project-reference/backend-patterns-reference.md）
• 确认实体表达式有数据库索引
• 确认文档数据库集合有索引管理方法

前端

• 使用项目的 store 基类进行状态管理（搜索：store base class）
• 对所有订阅应用清理逻辑（搜索：subscription cleanup pattern）
• 所有模板元素都使用 BEM 类命名
• 使用项目的基类（搜索：base component class、store component base class）

图谱智能（如果存在 graph.db，则必须执行）

简化之前，追踪依赖目标代码的部分：

python .claude/scripts/code_graph trace <file> --direction downstream --json

确认简化后的代码为所有追踪到的使用方保留相同接口。跨服务的 MESSAGE_BUS 使用方尤其脆弱——它们可能依赖精确的消息结构。

其他查询：

• 确认没有调用方受到影响：python .claude/scripts/code_graph query callers_of <function> --json
• 检查依赖项：python .claude/scripts/code_graph query importers_of <module> --json
• 批量分析：python .claude/scripts/code_graph batch-query file1 file2 --json

执行

spawn_agent(agent_type="code-simplifier", prompt="Review and simplify [target files]")

示例：

// Before
function getData() {
    const result = fetchData();
    if (result !== null && result !== undefined) {
        return result;
    } else {
        return null;
    }
}

// After
function getData() {
    return fetchData() ?? null;
}

约束

• 保留功能 — 不得更改行为
• 测试通过 — 每次更改后都要验证
• 遵循模式 — 使用项目约定，切勿自行发明
• 文档过时 — 将已更改文件与功能文档、测试规范和 README 交叉核对；标记需要更新的内容
• 保留所有不变量；绝不弱化属性测试或变异测试 — 重构必须完整保留 §4 中的每条 [HARD] 规则和 §5 中的每项不变量，并且不得删除、放宽或弱化任何用于守护这些规则或不变量的属性测试或变异测试。如果简化改变了可观察行为，这就不是静默更改，而是一个双重反馈问题（反馈到规范和测试，然后重新审核）；报告该问题并停止，绝不能发布。简化后，软件包必须仍通过与之前相同的属性测试和变异测试门槛——在门槛被弱化后测试通过，不算通过。

---

自递归验证（简化后必须执行）

应用简化后，验证必须对更新后的差异执行一轮自递归简化。不要启动新的上下文审核者来重新审核此技能自己的发现。重复“分析 → 简化 → 验证”，直到此技能不再发现进一步的简化机会；若遇到不安全、无进展或需要用户决定的阻碍，则停止。

自我审核关卡（此技能更改代码时必须执行）

此技能会修改代码，因此必须审核自己的输出。 上述自递归简化循环确认无问题后，设置审核关卡：

1. 此技能是否修改了任何文件？ 确定此技能更改的确切文件集（仅包含它自己的编辑，而非整个工作树）。
   • 没有文件更改 → 跳过此关卡，并记录跳过原因（“code-simplifier 未作任何更改——无需自我审核”）。完成。
   • 有文件更改 → 继续。
2. 在限定的文件范围内自行调用 $code-review。 将明确列出的已更改文件集作为审核目标，而不是整个差异或无关文件。
3. 处理 $code-review 的发现。 如果发现由简化导致的阻塞问题，则修复这些问题（仅限不改变行为的修复），并重新运行自递归循环和此关卡。如果问题超出简化范围，则向上报告，切勿默默忽略。

递归安全性： $code-review 是一个叶子审核技能，不会反过来调用 $code-simplifier，因此不会形成循环。此处应使用 $code-review，绝不要使用 $changes-review（这个重量级工作流本身包含 $code-simplifier，会造成递归）。

设置此关卡的原因： $code-simplifier 会在主要审核批次结束后重写代码。如果没有此关卡，简化后的输出就会未经审核便发布。此关卡将审核责任交给修改代码的技能自身，因此 workflow-review-changes 工作流无需在 $code-simplifier 之后另行执行 $code-review。

单独使用（在审核工作流之外）时，此自我审核关卡足以覆盖简化器自身的更改；你仍可在最后执行 $changes-review，或通过当前工作流的审核关卡，全面审核整个变更集。

工作流建议

必须执行——无例外： 如果尚未处于工作流中，请直接询问用户。不要自行决定这件事“简单到可以跳过”——由用户决定：

1. 启用 workflow-review-changes 工作流（推荐）——完整的 changes-review 重启关卡 → 已验证的修复周期（计划 → 计划审核 → 功能实现）→ 重新审核 → 文档
2. 直接执行 $code-simplifier——独立运行（此技能通过自我审核关卡审核自身更改）

---

后续步骤

必须执行——无例外： 完成后，直接询问用户：

• “$workflow-review-changes（推荐）” — 提交前审核所有更改
• “$code-review” — 全面代码审核
• “跳过，手动继续” — 由用户决定

AI Agent 完整性门禁（不可妥协）

完成 ≠ 正确。 报告工作已完成前，必须提供证明：

1. Grep 检查所有已移除的名称。 提取／重命名／删除后 → 通过 grep 确认所有文件类型中都没有悬空引用。
2. 更改前先问 WHY。 现有值在证明并非有意设置之前，都应视为有意设置。没有可追溯的理由，就不要“修复”。
3. 验证所有输出。 一个构建通过 ≠ 所有构建都通过。检查每个受影响的技术栈。
4. 评估模式是否适用。 复制相邻代码？验证前提是否匹配——作用域、生命周期、基类和约束都相同。
5. 新建产物 = 已接入的产物。 已创建？证明它已注册、已导入，并且所有使用方都能访问。

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

前置条件： 执行前必须认真阅读：

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

外部记忆： 复杂／耗时的工作 → 将发现写入 plans/reports/。防止上下文丢失，并作为交付物。

证据门禁： 强制要求——每项声明、发现和建议都必须提供 file:line 证明或可追溯的证据（置信度 >80% 才可采取行动，<80% 时先验证）。

OOP 与 DRY 执行要求： 强制要求——标记重复模式，以提取基类。相同后缀的类（*Entity、*Dto、*Service）继承共同基类。验证技术栈是否已配置 lint 或分析器。

自递归简化循环

目的： 避免在此技能自行发现问题后，再花费 token 进行全新上下文审查。简化器负责自身的收敛循环；简化器报告无问题后，仍可运行范围更广的审查工作流。

循环：

1. 分析当前目标／差异，找出简化问题并提供 file:line 证据。
2. 仅应用满足证据门禁且不改变行为的简化。
3. 每组更改后运行针对性验证。
4. 重新阅读更新后的差异，并再次检查此技能的简化维度。
5. 重复以上步骤，直到此技能不再发现任何简化问题。

停止条件：

• 相同的简化问题连续 3 轮重复出现且没有进展。
• 简化需要产品／负责人提供意见，或存在改变行为的风险。
• 无法运行验证，或验证无法证明行为保持不变。

规则：

• 不要仅因为应用了简化就启动全新上下文审查。
• 修复已知问题前，不要在全新上下文中重新审查。
• 自递归检查发现的问题全部清零之前，不要移交并声称已无问题。
• 自递归循环通过后，运行 自我审查门禁——如果更改了任何文件，就对这些文件调用 $code-review（可安全递归的叶技能）；如果没有更改，则跳过并记录。

子 Agent 返回约定 — 此技能启动子 Agent 时，子 Agent MUST 仅返回以下结构。主 Agent 只读取此摘要，绝不在内联内容中请求子 Agent 的完整输出。

## 子 Agent 结果：[skill-name]

状态：✅ 通过 | ⚠️ 部分通过 | ❌ 失败
置信度：[0-100]%

### 发现（仅限严重/高严重性 — 最多 10 条）

- [严重性] [文件:行号] [发现]

### 已采取的操作

- [已更改的文件] [更改内容]

### 阻碍（如有）

- [阻碍说明]

完整报告：plans/reports/[skill-name]-[date]-[slug].md

仅在以下情况下，主 Agent 才会读取 Full report 文件：(a) 解决特定阻碍，或 (b) 制定修复计划。 子 Agent 按照 SYNC:incremental-persistence 的要求增量写入完整报告，而非将其保存在内存中。

上下文预算 — 返回内容是摘要，不是逐字记录：发现条目不超过 10 条，不得在内联内容中放入原始文件内容/完整差异/逐字日志，也不得重新粘贴源内容。摘要之外的所有内容都保存在磁盘上的 Full report 中。如果子 Agent 的回复超出摘要结构 MUST 将详细信息写入报告，并且只返回报告位置——整个 MapReduce 流程要保护的稀缺资源正是编排器的上下文。

UI 系统上下文 — 对于涉及 .ts、.html、.scss 或 .css 文件的任何任务：

实现前 MUST 仔细阅读：

1. docs/project-reference/frontend-patterns-reference.md — 组件基类、存储、表单
2. docs/project-reference/scss-styling-guide.md — BEM 方法、SCSS 变量、混入、响应式设计
3. docs/project-reference/design-system/README.md — 设计令牌、组件清单、图标

请参阅 docs/project-config.json，了解项目专属路径。

共享协议重复策略 — 技能中的内联协议内容（用 `` 包裹）是有意重复。请勿提取、去重或替换为文件引用。若协议需要通过读取文件才能访问，AI 的遵循度会显著下降。要更新协议：先编辑 .claude/skills/shared/sync-inline-versions.md，然后搜索 SYNC:protocol-name 并更新所有匹配项。

源代码/测试漂移检查。 对于编码、修复、调试、调查、测试或审查工作：当源代码行为发生变化时，检查受影响的单元/集成/E2E 测试，并根据证据判断测试是否应更新以匹配预期行为，或源代码变更是否属于需要修复的意外缺陷。不要为迁移代码编写测试；架构/数据迁移是一次性执行路径，并非核心应用逻辑。 AI 错误预防 — 每项任务都应避免以下失误：

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

批判性思维方式 — 运用批判性思维和顺序思维。每项断言都需要可追溯的证据，采取行动前置信度必须 >80%。 反幻觉： 绝不要把猜测说成事实——每项断言都要引用来源，坦然承认不确定性，自行检查输出是否有误，独立交叉引用，并对自己的信心保持怀疑——缺乏证据的确信是所有幻觉的根源。

先理解代码 — 硬性门槛：阅读现有代码之前，不要编写、规划或修复。

1. 搜索 3 个或更多相似模式（grep/glob）——引用 file:line 证据
2. 阅读目标区域中的现有文件——理解其结构、基类和约定
3. 当 .code-graph/graph.db 存在时，运行 python .claude/scripts/code_graph trace <file> --direction both --json
4. 通过 connections 或 callers_of 梳理依赖关系——弄清哪些内容依赖目标
5. 对非简单任务（涉及 3 个或更多文件），将调查记录写入 .ai/workspace/analysis/
6. 实施前重新阅读分析文件——绝不要只凭记忆开展工作。——原因：长上下文会偏离文件；文件才是事实依据
7. 如果现有模式可用，绝不要另创模式——严格遵循现有模式，否则说明偏离原因。——原因：模式不一致会割裂代码库，并拖慢之后每位读者的工作

解除阻塞前，必须完成： - [ ] 已阅读目标文件 - [ ] 已搜索 3 个或更多模式 - [ ] 已进行图谱追踪（如果 graph.db 存在）- [ ] 已通过证据核实假设 设计模式质量 — 每次代码更改都要进行的优先检查：

1. 通过 OOP 实现 DRY： 找出用途、命名模式或生命周期相同的类／模块。运用你对项目语言／框架的了解，确定符合惯用方式的抽象（基类、混入、trait、协议、装饰器）。存在 3 个或更多相似模式时 → 提取为共享抽象。
2. 职责恰当： 将逻辑放在最低层（实体 > 领域服务 > 应用服务 > 控制器）。绝不在控制器中编写业务逻辑。
3. SOLID： 单一职责（只有一个变更原因）。开闭原则（扩展，而非修改）。里氏替换（子类型可替换）。接口隔离（接口应小而精）。依赖倒置（依赖抽象）。
4. 提取／移动／重命名后： 使用 Grep 检查整个范围内是否存在悬空引用。绝不容忍遗漏。
5. YAGNI 门槛： 除非存在 3 个或更多实例，否则绝不推荐设计模式。不要为了假设的未来用途进行提取。

需要标记的反模式： 上帝对象、复制粘贴式继承、循环依赖、抽象泄漏。

通过串行检查关注设计质量 — 每次只检查一个质量维度（分轮检查），不要一次检查所有问题。——原因：注意力分散会漏掉单一焦点检查能够发现的问题。

1. 确定适用维度 — 根据代码的语言、领域和模式，判断适用哪些质量维度：DRY、SOLID 原则（SRP／OCP／LSP／ISP／DIP）、OOP 惯用方式、内聚／耦合、GRASP、迪米特法则、CQRS 不变量等。维度列表并非固定，应根据代码的实际功能推导。

2. 针对每个维度进行一次专注检查 — 按顺序逐一专注检查每个维度。不要在不同轮次中混合检查事项。

3. 门槛：3 个或更多相似模式 = 必须提取 — 这不是可选建议，而是必须采取行动的结构性修复。

4. 同类违规达到 2 个或更多 = 结构性发现 — 将其报告为需要通过架构解决的“模式问题”，而不是列出各个单独实例。 复杂度预防（Ousterhout）——必须遵守。以变更成本衡量代码：一项业务变更应对应一处代码变更。审查时标记以下所有问题：

5. 变更放大——小型业务变更迫使你在 >3 处修改代码 → 结构性缺陷。针对一个合理的未来变更（添加变体、添加字段、添加授权），统计编辑位置。>3 处 = 拒绝。

6. 认知负担——读者必须记住过多上下文才能安全地修改代码。标记深层继承、过长的参数列表、布尔陷阱、隐式顺序依赖。

7. 入口处的横切重复——在每个控制器/处理器/路由中重新实现日志记录、错误处理、验证、身份验证、事务处理。提取到中间件 / 拦截器 / 过滤器 / 装饰器 / 切面。

8. 泄漏实现技术——仓储向调用方返回 IQueryable/QuerySet/Criteria/原始游标/ORM 实体。返回已完成的结果和能明确表达意图的方法（GetActiveVipUsers()，而不是 Query()）。

9. 类型判断分散——在 >1 处通过 switch/if 链判断枚举/判别符。新增变体 = 新增一个文件，而不是修改 N 处。边界处有一个工厂/注册表 switch 可以接受；分散的 switch = 拒绝。

10. 贫血模型——领域对象只有 getter/setter，逻辑散落在服务中。将不变量/行为移到对象上（order.Checkout()，而不是 order.Status = ...）。

11. 基本类型痴迷——账户号码、电子邮件、金额、百分比、日期范围使用原始 string/int/decimal，并在每个入口重复验证。使用值对象 / 记录 / 结构体封装，并在构造时验证一次。

12. 内联横切关注点——在每个处理器顶部手写授权/租户隔离/审计/净化逻辑。使用声明式标记表达意图（@RequirePermission("Order.Delete")），并在中心位置统一执行。

13. 浅层模块——小类、大接口（许多公共方法、许多标志、许多构造函数参数），但封装的逻辑很少。如果一个小接口隐藏了大量实现，那么这个模块就是深的。如果学习接口所需的成本 ≈ 学习实现的成本 → 内联。

14. 重复组件/处理器生命周期缺少基类——3 个或更多表单/CRUD 处理器/列表视图重复实现加载/脏状态/提交/分页逻辑 → 提取为基类 / 钩子 / 可组合对象 / 混入 / 特征。

15. 过早或延迟抽象——遵循三次法则。第一次出现：直接编写。第二次：注意到重复。第三次：提取。不要在出现真实差异前构建通用框架；也不要复制粘贴到第 4 次。

16. 未将内嵌工具逻辑提取为辅助函数——内联分页循环（while (hasMore) { skip += take; ... }）、临时日期时间运算、字符串解析/格式化、集合分区、重试/退避循环、URL/查询字符串构建。如果算法非平凡且与业务无关、可跨栈复用，就提取到 util/helper/extensions，让调用方用一行代码调用。内联重复 → 扩大重复缺陷的影响范围。

17. 逻辑位于错误的（更高）层——下移至被调用方——当被调用方拥有数据时，调用方却编写业务/派生逻辑。默认情况：应该属于应用服务的控制器代码；应该属于领域服务或实体的应用服务代码；应该属于视图模型/存储的组件代码/服务。调用方深入被调用方的数据结构来进行计算 → 将计算移至被调用方上明确表达意图的方法中。由最低的合适层负责（实体 > 领域服务 > 应用服务 > 控制器 · 模型/VM > 存储 > 组件）。将逻辑放在更高层 = 当同级调用方需要相同逻辑时产生重复。

18. 规则归其所有者——首次编写时就提取——如果调用方内联了从另一类型的数据派生、规范化、验证或计算而来的逻辑，就将它移到拥有该数据的类型中。即使只使用一次也足够——触发条件是职责错误，而非重复。同级调用方总会出现；内联副本会悄然偏离，既不会导致编译错误，也没有可搜索的名称。常见问题：后端——应用层处理器 / 命令 / 查询 / 服务 / 控制器中的内联规则，实际应属于领域实体 / 值对象 / 领域服务。前端——组件中的内联派生逻辑 / 格式化 / 验证，实际应属于模型 / 存储 / 视图模型 / API 服务。**修复方法：**在拥有该规则的类型上将其命名为一个方法（静态或实例方法）；调用方按名称调用。未来出现变体时 → 在所有者上新增第二个命名方法，绝不编写近似的内联副本。先明确职责；复用是随之而来的结果。

提取目标——命名规则应放在哪里：

规则形式	应放在
对实体自身数据执行的纯函数	实体上的静态方法
修改 / 保护实体状态的行为	实体上的实例方法
对基本类型值始终成立的不变量	值对象构造函数
需要 DI（仓储 / 设置 / 时钟）	在 DI 中注册的辅助类
跨类型复用且与领域无关的算法	util / 扩展方法
纯粹的形状 / 投影转换	DTO 映射

提交前编辑位置测试（如果答案是“很多”，则拒绝）：

变更场景	应修改
添加新变体（客户类型、支付方式）	1 个新文件
更改 HTTP 错误响应格式	1 个中间件/过滤器
为每个持久化实体添加时间戳字段	1 个基实体/拦截器
为新端点添加授权	1 个声明式标记
更换数据库/ORM	仅数据层
更改业务计算规则	所属实体上的 1 个方法
为表单添加加载指示器模式	1 个基组件/钩子
为领域基本类型添加验证规则	1 个值对象构造函数
更改分页/重试/日期时间算法	1 个辅助函数/util 函数
更改实体数据的派生逻辑	实体上的 1 个方法

操作准则：

• 先编写调用点。
• 针对合理的未来变更统计编辑位置。
• 优先删除代码，而不是添加代码。
• 在边界处显式呈现假设，在内部隐藏细节。
• 复用前扫描——编写非平凡代码块之前，先搜索类似算法（while.*skip、DateTime.*Add、split/join 链、分页循环、重试循环）。找到匹配的现有辅助函数 → 调用它。如果没有，但模式与业务无关、可跨栈复用 → 在出现第二个调用方之前提取到 util。
• 层级放置测试——问自己：“如果明天有同级调用方需要这个逻辑，他们是否会重新推导？”如果会，那么逻辑就位于错误的层级。将其下移。
• 为未来复用预留空间——如果审查者发现某个代码块很可能出现在另一项功能中（与领域无关的算法、共享生命周期、重复出现的派生逻辑），不要用纯粹的 YAGNI 来合理化。要么现在提取（如果成本低），要么创建一条待跟踪的 TODO，明确写出提取目标，以免第二个调用方悄然复制。悄然重复是默认的失败模式。
• 犹豫不决时，问：“如果需求发生变化，需要修改什么？”

衡量好代码的标准是变更成本。 不是最短。不是最巧妙。不是抽象最多。读过一小部分局部代码后，能够以最低成本安全修改。 严重性标准 — 根据每项发现可能造成的后果进行分类，而不是根据修复难易程度。所有评审使用同一套标准，确保“高”在任何地方含义一致。

严重性	操作	定义
CRITICAL	阻止合并	静默运行时故障、数据损坏、绕过验证、安全漏洞
HIGH	必须修复	行为不正确、不变量缺失、违反架构约束
MEDIUM	应当修复	设计债务、可维护性问题、可能导致未来出现 Bug
LOW	修复更好	约定、文档、轻微的清晰度问题

基于评分的技能将其数值刻度映射到这些等级——不要另创一套术语：

• 0-2 标准评分（例如 production-readiness-review）：0 = CRITICAL/HIGH（未满足标准，阻碍生产就绪），1 = MEDIUM（部分满足，应当修复），2 = 通过（无发现）。
• 双轴评分（例如 performance-review、影响 × 可能性）：将结果单元格映射到最接近的等级——高影响 + 高可能性 → CRITICAL/HIGH；低影响或低可能性 → MEDIUM/LOW。

发现的等级决定了关卡要求：在 PASS 之前，必须解决 CRITICAL/HIGH，或由负责人明确接受；MEDIUM/LOW 可以随附已跟踪的后续事项一起发布。

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

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

务必注意 防止复杂度增加——一次业务变更 = 一次代码变更。标记变更扩散（未来变更需修改 >3 处）、散落的类型切换、贫血模型、基本类型偏执、技术细节通过抽象泄漏、浅层模块、未提取的实用逻辑（分页/日期时间/字符串/重试 → 辅助函数），以及位于错误高层的逻辑（下移至被调用方/实体/VM）。不要以纯粹的 YAGNI 为由，合理化隐性的重复。

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

• 强制 根据后果将发现分为 Critical/High/Medium/Low；在修复或由负责人接受之前，Critical/High 会阻止 PASS。
• 强制 基于评分的技能（sre 0-2、perf 双轴）必须映射到同一套四级标准——不得使用另一套严重性术语。

Prompt-Enhance 收尾锚点

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

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

1. 为每项任务标记 PAR 或 SEQ。 PAR = 输入不包含任何待处理任务的输出，且写入集与其他所有 PAR 任务互不相交。否则标记为 SEQ——必须明确说明迫使其按顺序执行的依赖。
2. 将 PAR 任务分组成多个波次。 波次成员之间不得存在依赖边。两个写入同一文件的任务绝不能处于同一波次。只读工作（搜索、调查、审查、研究）可自由并行。
3. 派发前声明： Parallel plan: wave 1 = [...] · wave 2 = [...] · SEQ = [...] (reason)。
4. 在一条消息中派发每个波次 — 在同一条回复中调用所有 spawn_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 执行自己的任务说明；除非该 Agent 的 .claude/agents/*.md 定义授权，否则进一步扇出仍由编排器负责。

绝不并行执行： 共享写入目标的任务 · 使用待处理任务输出的任务 · 琐碎的单文件工作（派发开销大于收益）· 技能或工作流明确固定顺序的操作 · 等待用户批准的关卡。

阻塞条件： 必须为每项标记为 PAR/SEQ 的任务明确说明原因（SEQ 任务必须说明）· 声明波次并检查写入集互不相交 · 在一条消息中派发每个波次 · 在进入下一波前遵守屏障。

• 强制要求 规划任务后，为每项任务标记 PAR/SEQ，并在一条消息中将每个 PAR 波次作为并行子 Agent 派发——工作流、批量更新、调查、研究、审查默认并行；计划执行仅按照计划声明的内容扇出。
• 强制要求 每个波次的写入集互不相交 · 进入下一波前等待所有任务返回 · 交由专家处理 · 除非子 Agent 自身的定义授权，否则子 Agent 绝不进一步扇出。

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

叠加规则只能追加：它们只能在此技能自身的协议上增加规则，绝不可替换、覆盖、禁用或重新解释此技能已有的规则；移除所有叠加规则后，此技能必须完全恢复为其文档所述的行为。叠加规则只是简报，绝不是权限升级：它绝不可豁免工作流关卡、Git 规范、审查关卡或用户确认关卡。若叠加规则与技能本身确实冲突，或两个具体程度相同的叠加规则直接矛盾 -> 向用户指出两者；绝不可静默解决。

务必注意：执行前，必须先解析此技能的项目协议叠加规则——仅采用最具体的匹配层级（精确 > glob > *；这只决定叠加规则彼此之间的优先顺序，绝不高于此技能本身），且仅读取 <protocols-dir>/<Name>.md 下的匹配正文；正文缺失或格式错误时须报告，绝不可重建。叠加规则只能追加（绝不替换此技能自身的规则），且只是简报，绝不是权限升级；具体程度相同的规则若相互矛盾，应交由用户处理。

收尾提醒

**重要，务必注意目标：**降低后续变更的成本——通过简化和改进代码，减少耦合、隐藏状态、重复知识和模糊意图，以提升清晰度、一致性和可维护性，同时不改变任何可观察行为。——原因：每次简化都应服务于降低未来变更成本，而非追求美观。

重要，务必注意主要步骤（按声明顺序执行，绝不跳过或合并）：（1）阶段 0：检测产物类型和范围 →（2）识别目标（跳过生成文件/迁移文件/供应商代码）→（3）通过 5 个维度进行分析 →（4）每次只应用一种重构类型 →（5）每次更改后验证测试 →（6）自递归循环，直到没有发现项 →（7）自我审查关卡（对更改的文件执行 $code-review）。——原因：AI 总是会忘记此技能自身的步骤；在此重申是为了强化近期记忆。

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

• 子 Agent 返回约定： 子 Agent 只返回摘要格式；完整细节写入报告文件。
• UI 系统上下文： 修改 UI 文件前，先阅读 frontend-patterns、scss-styling-guide 和 design-system。
• 共享协议重复策略： 内联 SYNC 重复是有意为之——绝不要将其提取到文件引用后。
• 源代码/测试漂移检查： 源代码行为变更时，根据证据判断是测试需要跟进，还是源代码存在缺陷。
• 防止 AI 出错： 根据证据核验生成内容，追踪下游引用，核验所有受影响的输出，在上下文丢失后重新阅读，并明确指出模糊之处。
• 批判性思维： 每项主张都要有可追溯的证据，置信度 >80% 才采取行动，绝不要把猜测说成事实。
• 先理解代码： 写代码或修复前，阅读目标内容、grep 至少 3 种模式，并追踪调用关系图。
• 设计模式质量： 通过 OOP 遵循 DRY 原则，职责置于最低层，遵循 SOLID，每个维度只进行一轮串行处理。
• 防止复杂化： 一项业务变更对应一项代码变更；标出变更放大和逻辑位于错误层级的问题。
• 严重性分级标准： 按后果将问题分为 Critical/High/Medium/Low；Critical/High 会阻止 PASS。
• 并行子 Agent 调度： 为任务标记 PAR/SEQ，将 PAR 任务按互不重叠的写入集分组为多个波次，每个波次用一条消息启动，并在进入下一波次前设置屏障。

重要，必须注意 只有确定简化不会改变行为时才应用简化——先 grep 所有用法并追踪使用方（当 graph.db 存在时，追踪图中的下游关系），并在动手前引用 file:line；如果不确定 → 不要应用。——原因：未经验证的“安全”改写会悄无声息地破坏下游使用方。 重要，必须注意 绝不要简化生成文件、迁移文件或供应商文件——在 Phase 0 中彻底跳过这些文件。——原因：重新生成的输出会覆盖修改；迁移是一次性执行路径，不是核心逻辑。 重要，必须注意 运行自递归循环（分析 → 简化 → 验证），直到简化问题归零；不要为这项技能自身发现的问题启动全新上下文的审查者。——原因：在全新上下文中重新审查自己的发现，会浪费本可由收敛循环处理的 token。

• MANDATORY 证据门槛 — 每项发现／建议都必须有 file:line 证据或可追溯的调用链；置信度 >80% 才可采取行动，60-80% 先核实，<60% 切勿建议。没有证据时，绝不使用“显而易见”“我认为”或“应该”等说法。
• MANDATORY 开始前，先通过任务跟踪将工作拆分为小型待办任务（每个文件读取对应一个任务）；始终只保留一个 in_progress；完成后立即标记为 completed；添加最终审查任务。上下文丢失时，先查看当前任务列表——接着处理，不要重复创建任务。
• MANDATORY 首先阅读 docs/project-reference/code-review-rules.md，然后阅读 project-structure-reference.md；搜索至少 3 个现有模式，并在修改前阅读目标代码。若存在 graph.db，运行图追踪。
• MANDATORY 复制附近代码前，先评估模式是否适用——核实作用范围、生命周期、基类和约束是否相同；最近的示例 ≠ 前置条件匹配。——原因：复制前置条件不匹配的模式虽然能编译，但结果是错误的。
• MANDATORY 按 5 个简化维度进行推理——可读性、DRY／抽象（≥3 次出现，应用 YAGNI 门槛）、职责放在恰当的最低层级（Entity > Domain Service > App Service > Controller）、降低复杂度、数据库分页 + 索引；每种技巧都必须回答同一个问题：这能让下一次修改更省力吗？
• MANDATORY IMPORTANT MUST ATTENTION 检查 OOP 中的 DRY（后缀相同 → 基类）、职责是否恰当（最低层级）和 SOLID；每次抽取／移动／重命名后，使用 grep 检查整个范围内是否存在悬空引用——零容忍。——原因：“主文件已完成” ≠ 次要文件也已清理干净。
• MANDATORY IMPORTANT MUST ATTENTION 保留所有不变量——绝不削弱、删除或简化任何保护 [HARD] §4 规则或 §5 不变量的属性测试／变更测试；行为变更属于双重反馈发现（反馈给规范和测试，重新审查）——必须报告并停止，绝不能悄然交付。——原因：放宽标准后测试通过，不等于真正通过。
• MANDATORY IMPORTANT MUST ATTENTION 每次修改后，验证所有受影响的输出和测试均通过（每次只应用一种重构类型）——一个构建通过 ≠ 全部通过。——原因：多技术栈变更会导致未检查的技术栈出现回归。
• MANDATORY IMPORTANT MUST ATTENTION 自我审查门槛——此技能修改了代码时，对仅包含已修改文件的范围自行调用 $code-review（可安全递归的叶子技能；绝不调用 $changes-review——它会递归调用 $code-simplifier）；若未发生修改，则跳过并记录原因。简化器负责审查自己的输出。——原因：简化器会在主要审查批次之后重写代码；没有此门槛，其输出就会未经审查而交付。
• MANDATORY 不在工作流内时，通过直接询问用户来确认路由决策——绝不自动判断“足够简单，可以跳过”。

反合理化：

逃避说法	反驳
“图追踪太简单了”	错误的假设会浪费更多时间。如果存在 graph.db，仍要运行追踪。
“已经搜索过了”	给出 file:line 证据。没有证据 = 没有搜索。
“只是做了个小简化”	在错误层级进行的小改动会产生连锁影响。先追踪使用方。
“代码不言自明”	未来的读者需要证据链。记录不明显的意图。
“简化是安全的”	绝不要想当然地认为安全——先 grep 所有用法；置信度 <80% = 不要应用。
“最佳实践要求抽象”	只有在能降低未来变更成本时才进行抽象；仅用于转发的间接层是复杂性，不是简化。
“到处都在用这种模式”	模式适用 ≠ 模式存在。复制之前，先确认作用域、生命周期、基类和约束都相同。
“测试仍然通过，可以发布了”	你降低了标准吗？放宽属性测试或变异测试后通过，并不算通过。保持相同的不变量标准。
“修复后跳过递归检查”	每次简化都会改变差异。重新运行此技能自身的简化分析，直到不再发现任何简化问题。
“生成文件也很乱”	绝不要修改生成文件／迁移文件／供应商文件——严格跳过。重新生成会覆盖你的改动。

[TASK-PLANNING] 行动之前，分析任务范围，并使用任务跟踪系统地拆分为小型待办任务。

---

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

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