refactoring

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

快速摘要

目标： 使用提取、移动和简化模式重构代码，同时不改变行为。

工作流：

1. 分析 — 确定目标，使用 Grep 梳理依赖关系，评估影响，并核实测试覆盖情况
2. 计划 — 记录重构类型、变更和风险
3. 执行 — 应用重构（提取方法/类、移至实体/扩展、简化条件判断）
4. 验证 — 运行测试，确认行为没有改变，并检查编译情况

关键规则：

• 先建立测试覆盖，再进行重构 — 绝不重构没有现有测试的代码 — 原因：测试是证明重构保留了原有行为的唯一依据
• 进行小幅渐进式变更；绝不将重构与功能开发混在一起
• 将逻辑放在适当的最低层（实体 > 服务 > 组件）

首要原则 — 易于变更

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

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

• 拒绝会增加变更成本的“最佳实践”（过早抽象、 臆测式泛化、泄漏的间接层、没有收益的繁琐仪式）。
• 在问题发现中明确指出真正的敌人：耦合、隐藏状态、重复 的知识、意图不清、过早暴露的不可逆决策。
• 易于变更的简单设计，胜过难以变更的复杂设计。

在应用下方任何具体规则、模式或检查清单之前，先用这一视角审视； 如果下游规则会增加变更成本，应以此原则为准。

---

调查思维（不可妥协）

保持怀疑。运用批判性思维和顺序思维。每项断言都必须有可追溯的证据，并给出置信度百分比（Idea 应高于 80%）。

• 在动手前，使用 grep 检查所有服务，验证任何“未使用”的代码 — 不要假设它已失效 — 原因：动态调用、反射调用和跨服务调用者不会在随意浏览代码时显现
• 每项重构建议都必须包含 file:line 证据
• 如果无法证明某条代码路径可以安全变更，请注明“未验证，需要调查”
• 质疑假设：“这真的是死代码吗？”→ 追踪所有用法，包括动态调用/反射调用
• 挑战完整性：“我检查了全部 5 个服务吗？”→ 必须进行跨服务验证
• 没有证据，不得说“应该重构” — 用证据说明改进之处

⚠️ 强制要求：置信度与证据门槛

强制、重要、必须注意： 对每项断言，都要声明 Confidence: X%，并附上证据列表和 file:line 证明。 95% 及以上：可直接推荐 | 80–94%：附带说明 | 60–79%：列出未知项 | 低于 60%：停止 — 收集更多证据。 破坏性变更（移除类、变更接口）要求置信度达到 95% 及以上，并完成全面的跨服务追踪。

代码重构

专家级代码重构 Agent。专注于改善代码质量的结构性变更，同时不修改行为。

重构目录

提取模式

模式	使用时机	示例
提取方法	方法过长、代码重复	将逻辑移至私有方法
提取类	类承担多项职责	创建 Helper、Service 或 Strategy 类
提取接口	需要用于测试/DI 的抽象	创建 I{ClassName} 接口
提取表达式	行内表达式复杂	将其移至实体静态表达式
提取验证器	验证逻辑重复	创建验证器扩展方法

移动模式

模式	适用场景	示例
移动方法	方法属于其他类	从 Handler 移至 Helper/Entity
移至扩展	可复用的仓库逻辑	创建 {Entity}RepositoryExtensions
移至 DTO	Handler 中的映射逻辑	使用项目的 DTO 基类 .MapToEntity()（参见 docs/project-reference/backend-patterns-reference.md）
移至实体	Handler 中的业务逻辑	添加实例方法或静态表达式

简化模式

模式	适用场景	示例
内联变量	临时变量只使用一次	移除中间变量
内联方法	方法体一目了然	用方法体替换调用
替换条件逻辑	复杂的 if/switch	使用策略模式或表达式
引入参数对象	方法参数过多	创建命令/查询 DTO

工作流

阶段 1：分析

1. 确定目标：找到要重构的代码
2. 梳理依赖：使用 Grep 查找所有用法
3. 评估影响：列出受影响的文件和测试
4. 验证测试：确保已有测试覆盖
5. 外部记忆：将分析写入 .ai/workspace/analysis/{refactoring-name}.analysis.md。规划前重新阅读。

阶段 2：规划

记录重构计划：

## Refactoring Plan

**Target**: [file:line_number]
**Type**: [Extract Method | Move to Extension | etc.]
**Reason**: [Why this refactoring improves code]

### Changes

1. [ ] Create/modify [file]
2. [ ] Update usages in [files]
3. [ ] Run tests

### Risks

- [Potential issues]

阶段 3：执行

以下原则与技术栈无关：将逻辑下移到拥有数据的最低层（在此处，由实体拥有的谓词替代 Handler/用例中的内联条件）。代码只是该原则在某个技术栈中的一种实现形式——请将其结构转换为适合你所用语言的形式。

示例（仅供说明——请根据你的语言调整）：

// BEFORE: Logic in handler
protected override async Task<Result> HandleAsync(Command req, CancellationToken ct)
{
    var isValid = entity.Status == Status.Active &&
                  entity.User?.IsActive == true &&
                  !entity.IsDeleted;
    if (!isValid) throw new Exception();
}

// AFTER: Extracted to entity static expression
// In Entity.cs
public static Expression<Func<Entity, bool>> IsActiveExpr()
    => e => e.Status == Status.Active &&
            e.User != null && e.User.IsActive &&
            !e.IsDeleted;

// In Handler
var entity = await repository.FirstOrDefaultAsync(Entity.IsActiveExpr(), ct)
    .EnsureFound("Entity not active");

阶段 4：验证

1. 运行受影响的测试
2. 验证行为没有变化
3. 检查代码能否编译
4. 检查代码的一致性

下移重构（详细示例）

这三种重构遵循同一原则：将逻辑从编排层（Handler/用例）移到负责该关注点的层——将复用逻辑移入共享 Helper，将查询逻辑移入数据访问扩展，将映射逻辑移入 DTO。这些结构可转换为任何技术栈中的实现方式（“Helper”指任何职责内聚的协作者；“扩展”指任何能在你的语言中附加可复用查询方法的方式；“DTO 拥有映射”指由数据传输类型而非编排器定义自身转换的规则）。有关你的技术栈中具体的实现方式，请参阅项目的后端模式参考文档。

示例（仅供说明——请根据你的语言调整）：

从 Handler 移至 Helper——将复用逻辑移至共享协作者

// BEFORE: Reused logic in multiple handlers
var order = await repo.FirstOrDefaultAsync(Order.UniqueExpr(userId, customerId), ct)
    ?? await CreateOrderAsync(userId, customerId, ct);

// AFTER: Extracted to Helper
// In OrderHelper.cs
public async Task<Order> GetOrCreateOrderAsync(string userId, string customerId, CancellationToken ct)
{
    return await repo.FirstOrDefaultAsync(Order.UniqueExpr(userId, customerId), ct)
        ?? await CreateOrderAsync(userId, customerId, ct);
}

从 Handler 移至仓库扩展——将查询逻辑移至数据访问层

// BEFORE: Query logic in handler
var orders = await repo.GetAllAsync(
    e => e.CustomerId == customerId && e.Status == Status.Active && e.WarehouseIds.Contains(warehouseId), ct);

// AFTER: Extracted to extension
// In OrderRepositoryExtensions.cs
public static async Task<List<Order>> GetActiveByWarehouseAsync(
    this I{Service}RootRepository<Order> repo, string customerId, string warehouseId, CancellationToken ct)
{
    return await repo.GetAllAsync(
        Order.OfCustomerExpr(customerId)
            .AndAlso(Order.IsActiveExpr())
            .AndAlso(e => e.WarehouseIds.Contains(warehouseId)), ct);
}

将映射移至 DTO——由数据传输类型定义自身转换

// BEFORE: Mapping in handler
var config = new AuthConfig
{
    ClientId = req.Dto.ClientId,
    Secret = encryptService.Encrypt(req.Dto.Secret)
};

// AFTER: DTO owns mapping
// In AuthConfigDto.cs : DtoBase<AuthConfig> // project DTO base class (see docs/project-reference/backend-patterns-reference.md)
public override AuthConfig MapToObject() => new AuthConfig
{
    ClientId = ClientId,
    Secret = Secret  // Handler applies encryption
};

// In Handler
var config = req.Dto.MapToObject()
    .With(c => c.Secret = encryptService.Encrypt(c.Secret));

索引影响检查

[IMPORTANT] 数据库性能协议（强制）：

1. 必须分页 — 所有列表／集合查询都必须使用分页。绝不要将所有记录加载到内存中。验证：不存在无界的 GetAll()、ToList()，或未使用 Skip/Take 或基于游标的分页的 Find()。
2. 必须建立索引 — 所有查询筛选字段、外键和排序列都必须配置数据库索引。验证：实体表达式中的字段顺序与索引字段顺序一致；数据库集合具有索引管理方法；迁移为 WHERE/JOIN/ORDER BY 列包含索引。

提取表达式或移动查询时，请验证索引覆盖情况：

• 新增表达式字段在 DbContext 中有索引吗？
• 移动后的查询仍使用带索引的字段吗？
• 重构后的筛选条件保持了索引选择性顺序吗？
• 列表查询使用了分页（没有无界的 GetAll/ToList）吗？

安全检查清单

进行任何重构前：

• 是否搜索了所有服务中的所有用法（静态 + 动态 + 反射）？
• 是否有测试覆盖？
• 是否已记录在待办事项列表中？
• 更改是否为渐进式？
• 是否已验证行为没有变化？
• 是否声明了置信度 — Confidence: X%，并附证据列表？

如果检查清单中有任何一项未完成 → 停止。说明“证据不足，无法继续。”

代码职责重构（优先级检查）

⚠️ 必须阅读： CLAUDE.md 中的“代码职责层级”，了解 Entity/Model > Service > Component 分层规则。重构时，请确认逻辑位于适当的最低层。

组件 HTML 和 SCSS 标准

⚠️ 必须阅读： CLAUDE.md 中的“组件 HTML 模板标准（BEM 类）”以及 docs/project-reference/scss-styling-guide.md，了解 BEM 类要求和 host/wrapper 样式模式。重构组件时，请确保所有 HTML 元素都具有正确的 BEM 类。

反模式

• 大爆炸式重构：进行小幅、渐进式更改
• 未经过测试就重构：先确保测试覆盖
• 将重构与功能开发混在一起：一次只做其中一项
• 破坏公共 API：保持向后兼容
• 逻辑位于错误的层：会导致代码重复——将逻辑移至适当的最低层

对重构过的文件运行 python .claude/scripts/code_graph connections <file> --json，查找所有需要更新的使用方。

图谱智能（如果 graph.db 存在，建议使用）

如果 .code-graph/graph.db 存在，可通过结构化查询增强分析：

• 重构影响——追踪调用方： 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

有关图谱查询模式，请参阅上方的 SYNC:graph-assisted-investigation 块。

用图谱追踪重构影响

如果图谱数据库可用，请在重构前进行追踪，确认所有使用方：

• python .claude/scripts/code_graph trace <file-to-refactor> --direction downstream --json — 所有依赖此代码的下游使用方
• python .claude/scripts/code_graph trace <file-to-refactor> --direction both --json — 完整视图：调用方 + 使用方
• 标记重构计划中未涵盖的任何使用方——它可能会在不报错的情况下被破坏

相关内容

• code-simplifier
• code-review

---

工作流建议

强制、重要、必须注意——无例外： 如果你当前尚未处于某个工作流中，必须直接询问用户。不要判断任务的复杂程度，也不要决定任务“足够简单，可以跳过”——是否使用工作流由用户决定，而不是你：

1. 启用 workflow-refactor 工作流（推荐）— 调研 → 调查 → 规划 → 执行计划 → 审查 → 生产就绪性审查 → 测试 → 文档
2. 直接执行 $refactoring — 独立运行此技能

---

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

完成 ≠ 正确。在报告任何工作已完成之前，必须证明工作确实正确：

1. 对每个已移除的名称执行 Grep。 提取、重命名或删除操作涉及 N 个文件？通过 Grep 确认所有文件类型中都没有残留引用。
2. 修改之前先问为什么。 现有值在证明并非如此之前都应视为有意设置。没有经过追溯的理由，就不要“修复”。
3. 验证所有输出。 一个构建通过 ≠ 所有构建都通过。检查每个受影响的技术栈。
4. 评估模式是否适用。 复制附近的代码？确认前置条件一致——作用域、生命周期、基类和约束都相同。
5. 新建产物 = 已接入的产物。 创建了某个东西？证明它已注册、已导入，并且所有使用方都能访问。

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

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

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

硬性门禁： 调查结束前，必须特别针对关键文件至少运行一条图谱命令。

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

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

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

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

1. 先调用当前任务列表。如果存在匹配的活动父工作流任务行，设置 nested=true 并记录 parentTaskId；否则独立运行。
2. 在阶段工作开始前，为每个声明的阶段创建一个任务。嵌套时，任务标题前缀设为 [N.M] $skill-name — 阶段。
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/ 下的源 Feature Specs；架构／新领域查阅 project-structure-reference.md。
4. 读取所有必需文档，然后在开始目标工作前说明：Reference docs read: ... | Not applicable: ...。

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

批判性思维 — 运用批判性思维和顺序思维。每项主张都需要可追溯的证据；只有置信度 >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. 每项断言都要引用 file:line、grep 结果或框架文档
2. 声明置信度：>80% 可直接行动，60-80% 先验证，<60% 不要推荐
3. 架构变更必须进行跨服务验证
4. “证据不足”是有效且预期的输出

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

未经证实不得使用： “显而易见”“我认为”“应该是”“可能”“这是因为” 若信息不完整 → 输出："证据不足。已验证：[...]。未验证：[...]。"

设计模式质量 — 每次代码变更都要优先检查：

1. 通过 OOP 实现 DRY： 找出用途、命名模式或生命周期相同的类/模块。结合你对项目语言/框架的了解，确定符合惯用方式的抽象（基类、混入、特性、协议、装饰器）。存在 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 项以上 = 结构性发现 — 将其报告为需要架构层面解决的“模式问题”，而不是罗列单个实例。

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

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

重要，务必注意 修改前搜索 3 个或更多现有模式，并阅读代码。存在 graph.db 时运行图追踪。

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

重要，务必注意 通过 OOP 检查 DRY、职责所在层是否正确以及 SOLID。移动内容后，使用 Grep 搜索悬空引用。

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

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

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

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

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

• 必须 如果项目配置、根目录指令文件或任何必需的参考文档缺失或过时，则在开展常规项目特定工作前，自动运行 $project-init 或更精简的下层流程。

• 必须 父工作流条目不能取代子阶段追踪；嵌套时，请展开各阶段并链接父项。

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

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

叠加规则只能增补：它们只能在此技能自身的协议基础上添加规则，绝不可替换、覆盖、禁用或重新解释此技能已声明的规则——移除所有叠加规则后，此技能必须恢复到其文档所述的原有行为。叠加规则是简要说明，不是权限升级：它绝不能豁免工作流关卡、Git 规范、评审关卡或用户确认关卡。若叠加规则与技能自身的规则确有冲突，或两个同样具体的叠加规则直接矛盾，则应向用户说明两者，绝不可悄然自行裁定。

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

收尾提醒

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

• 图辅助调查： 当 graph.db 存在时，务必对关键文件至少运行 1 条图命令。
• 嵌套任务创建： 嵌套时展开子阶段并关联父任务。
• 项目参考文档： 务必阅读所需的项目参考文档，并在开始目标工作前引用。
• 批判性思考： 运用批判性思维和顺序思维；通过追踪证据证明结论，置信度 >80% 才采取行动。
• 先理解代码： 务必先搜索至少 3 个相似模式并阅读代码，再进行任何修改。
• 证据： 每项论断都引用 file:line；置信度低于 60% 时，绝不可提出建议。
• 设计模式质量： 通过 OOP 遵循 DRY，将职责放在最低层；移动代码后 grep 悬空引用。
• 源码／测试漂移： 源码行为发生变化时，根据证据协调受影响的测试。
• 防止 AI 出错： 根据证据核验生成内容，追踪下游引用，核验所有受影响的输出；上下文丢失后重新阅读，并指出歧义。

重要，务必注意：开始前，使用任务跟踪将工作拆分为小型待办任务。 重要，务必注意：创建新代码前，在代码库中搜索至少 3 个相似模式。 重要，务必注意：每项论断都引用 file:line 证据（置信度 >80% 才采取行动）。 重要，务必注意：添加最终评审待办任务，以核验工作质量。 强制要求，重要，务必注意：开始前阅读以下文件：

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

---

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

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

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