learn

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

快速摘要

目标： 教 Claude 将经验教训延续到不同会话中：将每条教训归纳为可复用的失败模式，并保存到未来会话实际会读取的位置——最合适的文本参考文档；如果教训本质上是机器可读的项目事实，则保存到 docs/project-config.json。

摘要： 只读这部分也能了解主要步骤的精简指南——

• 先归纳，其他事都放在后面——从具体事件中提炼出可复用的失败模式；如果教训点名了本次工单涉及的文件、服务或工具，那它还不算一条教训。
• 先分诊（复发性 + 自动修复），再路由——如果某条教训已能被某个审查技能捕获，那它就是噪声。
• **判断应保存到哪种载体，不要默认使用文本：**描述项目事实（路径、运行命令、模块图、约定、工具选择）的教训应写入 docs/project-config.json，这是每个技能都会优先读取的机器可读映射；描述规则或模式的教训应写入相应的 docs/project-reference/ 文档。两者都适用时，可以同时写入——将事实写入配置文件，将规则写入文本。要了解配置文件包含哪些内容及其确切字段名，请阅读文件，或使用 $project-config（它会运行 --describe）。
• 评估预防深度——更新文档或配置、提示词规则、静态协议教训、钩子、测试或技能。
• 确认目标后保存，然后运行 3 个必做的结束任务——Learn Review → $why-review → $prompt-enhance。

工作流：

1. 记录 -- 从用户指示或经验中识别教训
2. 路由 -- 根据 Reference Doc Catalog 和 docs/project-config.json 分析教训内容，选择最合适的目标载体（文本、配置字段或两者）
3. 保存 -- 将教训追加到选定文件
4. 确认 -- 告知用户保存了什么内容以及保存位置
5. Learn Review -- 运行必做的两步结束检查（Learn Review + $why-review）
6. 增强 -- 对修改的文件运行 $prompt-enhance，以优化 AI 注意力锚定

关键规则：

• **先归纳（首要协议）：**提炼适用于多种情况的通用教训——绝不要原样保存具体案例。用户描述的是一次事件；你的任务是从该事件中提炼出可复用的规则。删除所有项目、文件、工具和领域名称。如果保存的内容只对这张工单有帮助，那就说明你没有做好——再抽象一层。（由下方的 Lesson Quality Gate 强制执行。）
• 用户说“记住这个”、“始终执行 X”或“绝不执行 Y”时触发
• **先分诊：**通过复发性检查和自动修复检查后，再进行路由或保存
• 智能路由到最相关的文件，而不是始终写入 docs/project-reference/lessons.md
• 每次路由决策都要考虑 docs/project-config.json——本质上属于项目事实（路径、运行命令、模块图、工具选择）的教训应写入机器可读映射，而不是文本；决定前请阅读文件或使用 $project-config 了解其架构
• 使用确切的配置架构字段名（node .claude/hooks/lib/project-config-schema.cjs --describe），并优先使用现有字段——绝不要自行创建键；通过 $project-config 写入配置
• 创建重复条目前先检查是否已有相关条目
• 写入前先与用户确认目标文件

保持审慎，运用批判性思维和顺序思维。每项声明都必须有可追溯的证据和置信度百分比（Idea 应高于 80%）。

用法

添加教训

$learn always use the validation framework fluent API instead of throwing ValidationException
$learn never call external APIs in command handlers - use Entity Event Handlers
$learn prefer async/await over .then() chains

列出教训

$learn list

删除教训

$learn remove 3

清除所有教训

$learn clear

参考文档目录（路由前请先阅读）

每个 docs/project-reference/ 文件都由 session-init-docs.cjs 钩子自动初始化，并由 /scan-* 技能填充。了解这些文件的作用对于正确路由至关重要：路由是静态的——请阅读 Read Trigger 与任务匹配的文档。

文件	作用与内容	Read Trigger（静态）	扫描技能
project-structure-reference.md	架构、目录树、技术栈、模块注册表、服务映射	新领域 / 架构工作	$scan --target=project-structure
backend-patterns-reference.md	后端 / 钩子模式：CJS 模块、CQRS、存储库、验证、消息总线、后台作业	编辑后端 / CQRS / API 文件	$scan --target=backend-patterns
seed-test-data-reference.md	种子 / 开发数据模式：环境门控、幂等循环、DI 作用域安全、命令分派	编辑 Seeder / DataSeeder 文件	$scan --target=seed-test-data
frontend-patterns-reference.md	前端模式：组件、状态管理、API 服务、样式约定、指令	编辑前端 / UI 文件	$scan --target=frontend-patterns
integration-test-reference.md	测试架构：基类、固定装置、辅助工具、特定服务的设置、测试运行器	编辑集成测试文件	$scan --target=integration-tests
feature-spec-reference.md	功能文档模板、应用到服务的映射、文档结构约定	编写 / 阅读功能规格说明	$scan --target=feature-spec
code-review-rules.md	审查规则、约定、反模式、决策树、检查清单	激活任何审查技能	$scan --target=code-review-rules
lessons.md	通用经验——兜底汇总。每项任务都要阅读（根据 project-reference-docs 门控要求）	每项任务	由 $learn 管理
scss-styling-guide.md	SCSS/CSS：BEM 方法、混合宏、变量、主题、响应式模式	样式 / SCSS 文件编辑	$scan --target=scss-styling
design-system/README.md	设计系统：令牌概览、组件清单、应用到文档的映射	设计 / UI 文件编辑	$scan --target=design-system
e2e-test-reference.md	E2E 测试模式：框架、页面对象、配置、最佳实践	E2E 文件编辑	$scan --target=e2e-tests
domain-entities-reference.md	领域实体、数据模型、DTO、聚合边界、ER 图、跨服务同步	后端 / 前端领域工作	$scan --target=domain-entities
docs-index-reference.md	文档树、文件数量、文档关系、关键词到文档的查找	文档查找 / 导航	$scan --target=docs-index

关键见解： lessons.md 和 code-review-rules.md 是复用频率最高的路由目标——每项相关任务都要阅读。将高频经验放在与之匹配的 Read Trigger 所保证的文档中，确保后续会话能够打开这些文档。

另一个路由目标：docs/project-config.json（机器可读，非说明文）

上面的目录是说明文。docs/project-config.json 是项目的机器可读映射——模块/路径、框架 + 搜索关键词、测试/E2E/集成运行命令、设计系统、架构规则、工作流模式——CLAUDE.md 和 docs/project-reference/** 文档均由它生成。每项技能都会被要求在调查、规划或编码之前先读取它，因此，记录在其中的事实会被更多会话获取，而写在某一篇说明文档中的同一事实则不会。

读取触发条件： 每项任务，优先于说明文档。负责方： $project-config。

在将任何内容路由到其中之前，先了解其结构——可以直接读取 docs/project-config.json，也可以调用 $project-config，它了解该架构及其准确字段名称：

node .claude/hooks/lib/project-config-schema.cjs --describe   # exact field names + per-field derivation notes

经验确实是……	承载位置
架构字段已有对应模型的项目事实——路径、glob、运行命令、模块/服务映射、框架或工具选择、文档根目录、测试/E2E/集成设置、启动或健康检查命令	docs/project-config.json（通过 $project-config）
Agent 必须据以判断的规则、模式或反模式	对应的 docs/project-reference/ 文档
两者兼有——新的事实以及使用该事实的规则	将事实写入配置，将规则写入说明文档

规则：

• 每次进行路由决策时，都必须检查 docs/project-config.json 是否适合承载内容——原因：仅以说明文形式记录的项目事实，对于读取配置的工具不可见，而且下次从配置重新生成文档时会被静默覆盖。
• 必须使用准确的架构字段名称（通过 --describe 查看，并原样复制），并优先使用现有字段而不是新字段——原因：未知键只会产生警告（project-config-schema.cjs:618,688），因此自创的键看似生效，实际上没有任何使用方会读取它。
• 没有适用的现有字段 → 不要悄悄新建顶层键。将经验路由到说明文档，并将此缺口作为建议的架构新增项告知用户——原因：架构变更属于框架决策，不应成为 $learn 的副作用。
• 优先通过 $project-config 路由配置写入（Plan → Review → Execute + 验证），而不是手动编辑 JSON——原因：它会在每个阶段后验证，并了解此技能原本只能靠猜测获取的字段名称。
• 配置仅承载事实，绝不承载说明文中的经验——绝不要将叙述性经验粘贴到配置字符串字段中。——原因：工具和每项技能的预取都会读取配置；将说明文写入其中会使每个会话都变得臃肿，而这类内容应放在参考文档中。

---

智能文件路由（关键）

经验教训分流关卡（必须执行 — 在分流或保存之前首先运行）

关卡	问题	通过	未通过 → 操作
重复发生性	“如果没有这条提醒，这个错误会在未来的会话中再次发生吗？”	是 → 继续	否 → 跳过 $learn；该错误属于情境性错误
自动修复	“$code-review、$code-simplifier、$security-review 或 $lint 能自动发现这个问题吗？”	否 → 继续	是 → 跳过 $learn；改为更新审查技能

两个关卡都必须通过。 将审查技能已经能发现的问题记录为经验教训，只会增加噪声而没有价值。一次性的情境性错误无法通过持久化规则来避免。

---

分流表

根据经验教训的内容，将其分流到最相关的文件：

如果经验涉及……	路由至	章节提示
代码审查规则、反模式、审查清单、YAGNI/KISS/DRY、命名约定、审查流程	docs/project-reference/code-review-rules.md	添加到最相关的章节（反模式、规则、清单）
后端/钩子模式：模块、CQRS、仓储、实体、验证、消息总线、后台作业、迁移、配置的持久化	docs/project-reference/backend-patterns-reference.md	添加到相关章节或反模式章节
前端模式：组件、状态存储、表单、API 服务、样式约定、指令、管道	docs/project-reference/frontend-patterns-reference.md	添加到相关章节或反模式章节
集成/单元测试：测试基类、夹具、测试辅助工具、测试模式、断言、测试运行器	docs/project-reference/integration-test-reference.md	添加到相关章节
E2E 测试：Playwright、Cypress、Selenium、页面对象、E2E 配置、浏览器自动化、视觉回归	docs/project-reference/e2e-test-reference.md	添加到相关章节
领域实体、数据模型、DTO、聚合、实体关系、跨服务数据同步、ER 图	docs/project-reference/domain-entities-reference.md	添加到实体目录或关系章节
项目结构、目录组织、模块边界、技术栈选择、服务架构	docs/project-reference/project-structure-reference.md	添加到相关架构章节
SCSS/CSS 样式、BEM 方法、混入、变量、主题、响应式设计、CSS 约定	docs/project-reference/scss-styling-guide.md	添加到相关样式章节
设计系统、设计令牌、组件库、UI 工具包约定、Figma 到代码的模式	docs/project-reference/design-system/README.md	添加到相关设计章节
功能文档、文档模板、文档结构约定、应用到服务的文档映射	docs/project-reference/feature-spec-reference.md	添加到相关约定章节
文档索引、文档组织、文档与代码的关系、文档查找模式	docs/project-reference/docs-index-reference.md	添加到相关章节
**配置中建模的项目事实：**源码/模块路径、glob、服务或应用映射、框架和搜索关键词、测试/E2E/集成运行命令、系统启动或健康检查命令、文档根目录、设计系统或样式位置、工具选择	docs/project-config.json 通过 $project-config	现有架构字段，使用 --describe 中的确切名称——绝不可自创键
通用经验、工作流技巧、工具、AI 行为、项目约定，以及任何不符合上述类别的内容	docs/project-reference/lessons.md	以带日期的列表条目追加

---

预防深度评估（保存前必须执行）

保存任何经验教训前，务必批判性评估：仅更新文档是否足够，还是需要更深层的预防机制：

预防层级	使用时机	示例
仅更新文档	一次性提醒、罕见边缘情况、团队约定	“始终使用流式验证 API” → docs/project-reference/backend-patterns-reference.md
项目配置字段（docs/project-config.json）	该经验是机器可读的项目事实，所有技能在行动前都应以此为依据	“集成测试需要先启动系统” → 通过 $project-config 配置 integrationTestVerify.startupScript / systemCheckCommand
提示词规则（development-rules.md）	所有 Agent 在每项任务中都必须遵循的规则	“批量编辑后执行 Grep” → .claude/docs/development-rules.md
静态协议经验（sync-inline-versions.md）	通用的 AI 错误、频繁发生、会导致静默失败，适用于任何项目	“上下文压缩后重新读取文件” → .claude/skills/shared/sync-inline-versions.md
Hook（.claude/hooks/）	自动化强制执行、绝不能忘记的要求	“去重标记必须匹配” → lib/dedup-constants.cjs + 一致性测试
测试（.claude/hooks/tests/）	防止回归、可验证的不变量	“所有 Hook 都从共享模块导入” → 在 test-all-hooks.cjs 中测试
技能更新（.claude/skills/）	工作流中应始终包含此检查的步骤	“审查更改时必须检查文档是否过时” → 更新技能 SKILL.md

决策流程：

1. 记录经验教训
2. 询问：“如果 AI 忘记了这条经验，这个错误还会再次发生吗？”如果会 → 需要的不只是更新文档
3. 询问：“能否通过测试或 Hook 自动捕获这个问题？”如果可以 → 建议添加 Hook/测试
4. 评估是否提升为静态协议经验（见下文）
5. 向用户列出选项，并直接询问用户：
   • “仅更新文档”——保存到最合适的参考文件（大多数经验的默认选项）
   • “文档 + 提示词规则”——同时添加到 development-rules.md，以便所有 Agent 都能看到
   • “文档 + 静态协议经验”——同时添加到共享协议经验中（见下方标准）
   • “全面预防”——规划 Hook、测试或共享模块，以便自动强制执行
6. 执行所选选项。对于“全面预防”，通过 $plan 制定计划，而不是直接保存。

静态协议经验教训推广（必须评估）

对经验教训进行概括后，评估其是否符合 .claude/skills/shared/sync-inline-versions.md 中的静态协议经验教训标准。静态协议经验教训会写入 CLAUDE.md，同步到 AGENTS.md，并通过项目初始化／同步工具同步到 Codex 载体。

符合标准的条件（必须全部满足）：

1. 通用性 — 适用于任何 AI 编码项目，而不仅限于此代码库
2. 高复现率 — 若没有提醒，AI Agent 会在多个会话中反复犯此错误
3. 无声失败 — 此错误不会产生错误／警告，而是悄无声息地降低输出质量
4. 尚未覆盖 — 没有现有的静态协议经验教训针对相同的根本原因

静态协议经验教训 — 写入静态载体、用于防止 AI 常见错误的通用规则。存储在 .claude/skills/shared/sync-inline-versions.md 的 ai-mistake-prevention 和 ai-mistake-prevention:full SYNC 块中。每条经验教训都必须具备通用性、高复现率，并且针对无声失败。 添加前，请阅读 .claude/skills/shared/sync-inline-versions.md，检查是否有重复内容。

如果符合标准： 推荐“文档 + 静态协议经验教训”方案。获得用户批准后，将此经验教训作为新项目添加到相关的共享 SYNC 块中，然后运行项目初始化／同步流程，使 CLAUDE.md、AGENTS.md 和 Codex 载体从共享源重新生成。

如果不符合标准： 说明原因（例如：“过于特定于项目”“已有针对 X 的静态协议经验教训”“复现率低——只会在罕见边缘情况下发生”）。继续采用仅编写文档或提示词规则的方案。

经验教训质量门禁（阻塞性——保存前先泛化）

核心协议——不可跳过：$learn 请求始终以一个具体案例的形式出现（“不要通过总线迁移并向 Elasticsearch 发送垃圾数据”）。照原样保存是最常见的失败方式。写入前，必须将具体内容转化为通用规则：指出错误所属的类别，删去事件中的名词，并写出一条适用于许多未来场景的规则（“迁移应直接写入数据库，绝不可通过消息总线——适用于所有迁移”）。如果不提及此工单中的文件、服务或工具就无法表述这条经验教训，那么它还不够通用——再提升一个抽象层级。如有疑问，保存更通用的版本；过于具体的经验教训会成为每次提示词中注入的无用负担。

每条经验教训都必须达到根因层级，并适用于任何代码库。保存前，请按以下 3 个步骤提炼：

步骤 1——指出失败模式，而非症状：

失败模式是出错的推理或假设，而不是输出看起来是什么样子。

症状（错误——应拒绝）	失败模式（正确——应保存）
“使用了错误的枚举值”	“生成代码时假设某个 API 存在，却未在源代码中核实”
“命名空间／导入错误”	“未先阅读项目专属配置文件，就根据惯例假设项目设置”
“正常路径测试在 CI 中失败”	“编写断言时未追踪代码路径所需的运行时基础设施”
“设置了不存在的属性”	“未阅读基类，就假设层级结构中的所有类型都共享同一接口”
“始终要在读取 Y 前读取文件 X”	“未阅读所属层的契约，就假设执行上下文——在症状出现处修补，而非解决根因”

步骤 2——验证通用性：

此失败模式是否适用于 ≥3 种不同情境或代码库？如果只适用于一个文件或某个特定案例，就再提升一个抽象层级。一条好的经验教训可以避免一整类错误。

步骤 3——写成普遍适用的规则：

• 删除所有项目专属名称、文件路径、类名和工具名称
• 必须适用于任何代码库、任何语言和任何任务类型
• 如果多种错误具有相同的失败模式，就整合为一条经验教训，而非多条
• 测试：“在另一个项目中使用 Java、Go 或 Python 的 AI 是否能从中受益？”如果能，就是好的经验教训；如果不能，就重写。

反模式示例：

• 错误：“始终检查 lib/dedup-constants.cjs 中的标记字符串” → 项目专属路径
• 正确：“整合模块时，确保共享常量从唯一真实来源导入——绝不在代码中重复定义。”
• 错误：“删除钩子后更新 .claude/docs/hooks/README.md” → 项目专属文件
• 正确：“删除组件会导致文档逐渐过时——删除前，先找出所有引用该组件的文档。”
• 错误：“在 *.IntegrationTests 中添加 using 前先阅读 GlobalUsings.cs” → 项目专属文件
• 正确：“生成遵循项目惯例（导入、命名空间、注解）的代码前，先阅读该层的项目引导／配置文件——惯例文件会静默覆盖框架默认设置。”

阶段结束时的经验复盘关卡（标记完成前必须执行）

每次 $learn 操作结束时运行以下 2 项任务：

任务 1 — 经验复盘（价值 + 通用性 + 复现频率）：

• 仅保留具有明确预防价值的经验。
• 经验必须满足以下任一条件：
  • 适用于许多项目/代码库，或
  • 是稳定的项目级原则（架构不变量、命名不变量、工作流不变量）。
• 以下经验应予以拒绝：
  • 仅针对当前工单/变更/文件，
  • 复现频率低的罕见边缘情况，
  • 已由现有经验或审查技能涵盖。
• 如果目标是 docs/project-reference/lessons.md（每次提示都会注入），则应采用更严格的标准：仅保留影响大且复现频率高的经验。

任务 2 — 运行 $why-review（对抗性质疑）：

• 使用 $why-review 质疑这条经验是否值得长期记忆。
• 验证：
  • 这条经验为何能防止重复犯错，
  • 为何应将其作为经验，而不是一次性备注，
  • 为何自动检查（$code-review、$code-simplifier、$security-review、$lint、钩子/测试）不足以解决问题。
• 如果理由不充分，则提高抽象层次后重写，或跳过 $learn。

路由决策流程

1. 运行分流关卡 — 检查复现频率和自动修复筛选；任一项不通过即停止
2. 阅读经验文本 — 识别关键词和领域
3. 应用经验质量关卡 — 分析根因、进行概括并验证普适性
4. 对载体分类 — 事实还是规则（必须在路由表之前完成）。 问自己：“这是机器可读的项目事实，还是 Agent 必须推理的规则？” 事实 → docs/project-config.json；规则 → 说明性参考文档；两者皆是 → 两者都写入。为作出判断，请阅读配置文件或使用 $project-config（--describe），以实际架构为依据，绝不能凭猜测判断配置中包含什么。— 原因：跳过此步骤，就会导致项目事实被写成工具无法读取的说明文字，下一次重新生成时还会与之矛盾。
5. 运行预防深度评估 — 判断是否仅需文档/配置，或需要更深入的预防措施
6. 对照路由表 — 选择最合适的文件（或配置字段）
7. 告知用户：“这条经验最适合写入 docs/{file}。确认吗？[Y/n]”
8. 确认后 — 阅读目标文件，找到合适的章节，并追加经验（配置目标 → 通过 $project-config 路由）
9. 拒绝后 — 询问用户改用哪个文件

按目标文件选择格式

对于 docs/project-reference/lessons.md（通用经验）：

- [YYYY-MM-DD] <lesson text>

对于模式/规则文件（code-review-rules、backend-patterns、frontend-patterns、integration-test）：

• 在文件中找到最相关的现有章节
• 将经验作为规则、反模式条目或代码示例追加
• 使用文件现有的格式（表格、代码块、项目符号列表）
• 如果没有合适的章节，则追加到反模式或通用规则章节

预算控制（对 docs/project-reference/lessons.md 强制执行）

docs/project-reference/lessons.md 是一个静态项目参考载体，会在项目工作期间读取。必须控制 Token 预算。

硬性上限： 20000 个字符（约 6666 个 Token）。保存任何新经验前都必须检查。

向 docs/project-reference/lessons.md 添加内容时的工作流：

1. 读取文件并统计字符数（wc -c docs/project-reference/lessons.md）
2. 如果当前内容 + 新经验超过 20000 个字符 → 保存前触发预算精简
3. 如果未超出预算 → 正常保存

预算精简流程：

1. 显示所有现有经验，并分别列出字符数
2. 从以下两个维度评估每条经验：
   • 普遍性——适用频率如何？（每次会话都适用，还是罕见边缘情况）
   • 复发风险——没有提醒时，AI 重犯此错误的可能性有多大？
3. 分别评分：高（原样保留）、中（可考虑精简）、低（可考虑删除）
4. 向用户展示结果，并直接询问：“已超出预算。建议删除/精简以下低/中优先级条目：[列表]。是否批准？”
5. 获得批准后：精简中优先级条目（缩短措辞），删除低优先级条目，然后保存新经验
6. 如果用户拒绝：询问用户要删除/精简哪些条目

精简规则：

• 删除示例，保留规则："Patterns like X break Y syntax" → 仅保留规则本身
• 如果多条经验根源相同，则合并为一条
• 目标：每条经验 ≤ 250 个字符（一句简洁陈述 + 粗体标题）

不适用范围： 其他路由目标（backend-patterns-reference.md、code-review-rules.md 等）——这些文件有各自的大小限制，并会按上下文注入，而不是在每次提示中注入。

行为

1. $learn <text> — 将经验路由并追加到最匹配的文件（如果目标是 lessons.md，则检查预算）
2. $learn list — 读取并显示全部 12 个目标文件中的经验（按文件分组显示；同时显示 lessons.md 的字符数）
3. $learn remove <N> — 按行号从 docs/project-reference/lessons.md 中删除经验
4. $learn clear — 仅清除 docs/project-reference/lessons.md 中的所有经验（先确认）
5. $learn trim — 手动触发对 docs/project-reference/lessons.md 的预算精简
6. 文件创建 — 如果目标文件不存在，则仅创建文件头

自动推断激活

当 Claude 检测到对话中的纠正措辞（例如“始终使用 X”“记住这个”“绝不做 Y”“从现在起”）时，此技能会自动激活。通过自动推断激活（而非显式 $learn）时，保存前先向用户确认：“要将此内容保存为经验吗？[Y/n]”

经验如何传递给 AI

根据 CLAUDE.md 中的 project-reference-docs 门控，经验和模式参考会以静态方式读取：

• docs/project-reference/lessons.md — 每项任务都会读取（门控始终会包含此文件）。
• 模式/规则参考（backend-patterns-reference.md、code-review-rules.md 等）——由相应的触发条件读取（参见上方的 Reference Doc Catalog 表）。

由于路由内容是静态文本，无钩子的运行环境（Codex）会加载与 Claude Code 相同的经验和模式。

提示词增强（最后一步，强制执行）

将经验保存到任何目标文件后，对修改的文件运行 $prompt-enhance，以优化 AI 注意力锚定和 Token 质量。

运行时机：

• 每次成功保存经验后都运行（无论目标文件是什么）
• 传入具体的修改文件路径

执行内容：

• 确保新经验融入现有的顶部/底部摘要锚定
• 优化 Token 用量——收紧措辞、合并冗余内容
• 验证保存操作没有造成内容丢失

调用方式：

$prompt-enhance docs/project-reference/<modified-file>.md

跳过条件（此时不要运行 prompt-enhance）：

• 保存目标为 lessons.md 且文件不足 1500 个字符（文件太小，不值得优化）
• 用户明确要求“仅保存，不做增强”

---

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

必须执行的收尾任务始终按以下顺序进行：

1. “运行 Learn Review（课程价值 + 通用性 + 复现频率门槛）。”
2. “运行 $why-review，质疑这条课程是否值得纳入持久记忆。”
3. “运行 $prompt-enhance <modified-file>，优化课程内容，使其能锚定 AI 的注意力。”

在运行完全部 3 项任务之前，不要将技能标记为完成。

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

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

批判性思维 — 运用批判性思维和顺序思维。每项主张都需要有可追溯的证据，置信度必须 >80% 才能采取行动。 反幻觉： 绝不要把猜测说成事实——每项主张都要注明来源；坦承不确定性；自行检查输出中的错误；独立交叉核实；对自己的判断保持怀疑——缺乏证据的确信是一切幻觉的根源。

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

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

项目协议叠加规则 — 执行此技能前，先解析叠加在此技能之上的所有项目叠加规则：将此技能的名称与项目技能协议索引（默认位于 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 中匹配的正文；正文缺失或格式错误时应报告，绝不能重建。叠加规则仅可增加规则（绝不能替换此技能自身的规则），且只是简报，绝不是权限升级；具体程度相同的规则若相互矛盾，应提交给用户处理。

收尾提醒

**重要，务必注意：**先进行泛化——提炼适用于多种情形的通用规则；绝不能按原样保存具体事件。保存前，删除所有工单、文件、服务和工具名称。

务必注意：生效中的协议（此技能携带的 SYNC/共享内容的简要摘要——以上完整正文为准）：

• **防止 AI 出错：**依据证据核验生成内容，追踪下游引用，核验所有受影响的输出，在上下文丢失后重新阅读，并指出歧义。
• **批判性思维：**进行批判性和顺序性思考，追溯证明过程，置信度 >80%，绝不能将猜测当作事实。

**重要，务必注意：目标：**按故障模式层级，将每条经验保存到未来会话实际读取的载体中——最合适的说明文档，或在经验实际属于机器可读项目事实时保存到 docs/project-config.json。 重要，务必注意 主要步骤，按顺序：泛化 → Triage Gate → Lesson Quality Gate → 分类载体（FACT → 配置 · RULE → 正文 · 两者兼有 → 两者都写） → Prevention Depth Assessment → Routing Table → 与用户确认 → 保存 → Learn Review → $why-review → $prompt-enhance。 重要，务必注意 首先运行 Triage Gate——如果复发概率低，或审查技能能够发现问题，则完全跳过 $learn 重要，务必注意 检查 Reference Doc Catalog，找到最合适的目标文件——不一定总是 lessons.md 重要，务必注意 每次决定路由时，都要将 docs/project-config.json 与正文文档一并考虑为候选载体——先直接读取，或使用 $project-config 了解其章节和准确字段名——原因：只以正文形式写下的项目事实，配置读取工具无法看到；下次根据配置重新生成文档时，还会与之矛盾。 重要，务必注意 路由到配置时，从 node .claude/hooks/lib/project-config-schema.cjs --describe 原样复制字段名，优先使用现有字段，并通过 $project-config 写入；如果没有合适字段，则向用户提出新增架构字段的建议，而不是自行发明键——原因：未知键只会触发警告（project-config-schema.cjs:618,688），因此自行发明的键看似已应用，实际上没有任何使用方会读取它。 重要，务必注意 配置中只保留事实——绝不能将叙述性的经验教训粘贴到配置字符串字段中；规则应写入对应的正文参考文档。 重要，务必注意 必须完成的收尾任务始终是：Learn Review → $why-review → $prompt-enhance <modified-file>（按顺序） 重要，务必注意 开始前使用任务跟踪，将工作拆分为小型待办任务 重要，务必注意 高频复发的经验教训应优先使用自动注入的文件，以提高可见性

防止自我合理化：

逃避说法	反驳
“这是经验教训，所以应该放进 lessons 文档”	先区分 FACT 与 RULE。路径、运行命令或模块映射属于配置数据——写在正文里会让所有读取配置的使用方都看不到它。
“我大致知道配置里有什么”	读取配置，或运行 $project-config（--describe）。基于猜测的架构进行路由，会写入无人读取的字段。
“没有合适字段，我就加个合理的键”	未知键只会触发警告。应向用户提出新增架构字段的建议——绝不默默自行发明。
“原样保存用户的措辞才最忠实”	默认逐字照搬就是失败模式。应追溯到失败模式；删掉这张工单中的具体名词。
“这只是个小经验教训，跳过收尾检查吧”	每次保存都要运行 Learn Review → $why-review → $prompt-enhance，没有例外。

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

Hookless Prompt Protocol Mirror（自动同步）

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