performance

Codex 兼容性说明：

• 在 Codex 中使用 $skill-name 调用仓库技能；此镜像副本会将旧版 Claude /skill-name 引用改写为新格式。
• 任务跟踪要求：执行任何工作流或技能步骤之前，必须先为所有步骤创建／更新任务跟踪，并随着进度变化保持同步。
• 用户问题提示表示应直接在 Codex 中询问用户。
• 遇到 Claude 专属的模式切换指令时，请忽略。
• 严格执行约定：用户明确调用某项技能时，必须按原文执行该技能协议。
• 子 Agent 授权：用户调用或 AI 检测到某项技能，且其协议要求使用子 Agent 时，该技能的激活即授权为该任务使用所需的 spawn_agent 子 Agent。
• 除非用户事先明确批准偏离，否则不得跳过、重排或合并协议步骤。
• 对于工作流技能，必须明确执行每个列出的子技能步骤，并逐步报告依据。
• 如果必需步骤／工具在此环境中无法运行，请停止并询问用户，然后再调整方案。

Codex 项目参考资料加载（无钩子）

Codex 不会接收基于 Claude 钩子的文档注入。 进行编码、规划、调试、测试或审查时，请根据以下路由显式打开项目文档。

始终阅读：

• docs/project-config.json（项目专属路径、命令、模块以及工作流／测试设置）
• docs/project-reference/docs-index-reference.md（指向完整的 docs/project-reference/* 目录）
• docs/project-reference/lessons.md（始终适用的防护措施和反模式）

根据情况阅读文档：

• 后端／CQRS／API／领域／实体变更：backend-patterns-reference.md、domain-entities-reference.md、project-structure-reference.md
• 前端／UI／样式／设计系统：frontend-patterns-reference.md、scss-styling-guide.md、design-system/README.md
• 规格／测试用例规划或 TC 映射：feature-docs-reference.md
• 集成测试实施／审查：integration-test-reference.md
• E2E 测试实施／审查：e2e-test-reference.md
• 代码审查／审计工作：code-review-rules.md，并根据变更的文件阅读上述领域文档

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

[IMPORTANT] 必须注意：保持项目通用性；在作出判断前，先了解本地技术栈、约定、查询 API、索引定义、指标和报告路径。 [IMPORTANT] 必须注意：每项性能结论都必须有测量结果或静态依据支持：file:line、查询文本／形态、行数、查询计划／explain 输出、跟踪记录、性能分析结果或日志。 [IMPORTANT] 必须注意：数据库性能审查一次只关注一个维度：过量获取、过滤器、索引、N+1 扇出、批处理、聚合／联接形态、物化、写入、缓存。

[BLOCKING] 按声明顺序执行技能步骤。未经用户明确批准，绝不跳过、重排或合并步骤。 [BLOCKING] 在每个步骤／子技能调用之前更新任务跟踪：步骤开始时设为 in_progress，结束时设为 completed。 [BLOCKING] 每个已完成／跳过的步骤都必须附上简要依据或明确的跳过理由。 [BLOCKING] 如果任务工具不可用，请维护状态同步的等效逐步跟踪记录。

快速摘要

目标： 找出真实的性能瓶颈，尤其是数据库方面的浪费：行数过多、列数过多、索引缺失或未使用、循环内查询导致的扇出、无界物化、缓慢的联接／聚合、写入放大。

工作流：

1. 检测 - 分类范围和瓶颈类型。
2. 发现 - 阅读本地代码、指标、文档、查询／索引定义及类似模式。
3. 测量 - 获取基线，或标记为仅静态风险。
4. 分析 - 按顺序执行各维度的检查并提供证据。
5. 规划 - 提出保留行为的最小修复方案。
6. 验证 - 重新测量、运行测试，并进行独立复核。

关键规则：

• 强制要求始终测量修复前后；静态审查发现的问题必须提供明确的验证命令。
• 强制要求始终在投影／缓存之前将行筛选下推至数据源；减少行数优先于精简列数。
• 强制要求始终结合查询形态／顺序验证索引是否可用，不能仅凭索引存在与否下结论。
• 在查询形态、索引、分页、批处理和数据量尚未明确前，绝不能建议缓存。
• 对非平凡的性能工作，只经过一轮审查后绝不能宣告通过；必须进行独立复核挑战。

$ARGUMENTS

---

阶段 0：检测范围

分析前先分类。检测结果决定分析维度、证据和子 Agent 的选择。

范围	信号	主要证据
数据库读取	查询缓慢、全表扫描、排序溢出、检查行数过高	查询文本／ORM 表达式、行数、执行计划／解释结果、索引
数据库写入	保存缓慢、锁等待、逐行更新、事务膨胀	写入循环、批次大小、锁／死锁日志、事务范围
N+1／扇出	循环中包含查询／API 调用、惰性加载、逐项查找	调用方跟踪、查询次数、循环来源
API 延迟	p95／p99 过高、超时、端点／作业缓慢	跟踪／性能分析／日志、调用链
内存／OOM	大量物化、二进制大对象、无分页、缓冲	分配分析、结果大小、集合加载
前端	渲染缓慢、包体积过大、重复获取、DOM 变更频繁	浏览器性能分析、网络瀑布图、组件／渲染跟踪
分布式	消息延迟、跨服务调用链过长、重试风暴	跟踪跨度、队列指标、消费者／生产者链

只有当目标明确缩小范围且证据证明某个维度无关时，才允许跳过该维度。

---

阶段 1：发现本地上下文

得出任何发现之前，必须先完成发现工作：

• 必须搜索本地规范：performance、index、query、pagination、projection、database、profiling、contributing、style guide。
• 必须搜索至少 3 个本地类似查询／API 模式，然后再提出修复方案。
• 必须阅读目标代码，以及控制所查数据的索引／迁移／架构文件。
• 必须使用可用的图谱／调用跟踪／性能分析工具梳理调用方和调用频率；若没有此类工具，则使用 grep／导入关系／调用层级。
• 必须明确数据形态：租户／安全筛选条件、基数、预期最大行数、选中的列／字段、排序、联接、聚合／分组、缓存键。
• 绝不能硬编码项目名称、仓库路径、ID 格式、数据库引擎、ORM 或框架默认值；必须从已发现的文件中确定。

---

阶段 2：基线证据

优先采用运行时证明。如果无法获取，请将发现标记为 static risk，并提供用于验证的准确命令／查询。

数据库发现的强制基线：

• 始终记录查询来源：file:line，以及可用时生成的 SQL／查询／ORM 表达式
• 始终记录数据量：输入大小、匹配行数、返回行数、检查／扫描行数、分页大小／限制
• 始终记录访问路径：可用时提供查询计划／explain、所用索引、排序／分组策略、连接方式
• 始终记录耗时：p50/p95/p99、查询耗时、查询次数、分配量或响应大小
• 始终记录上下文：端点／作业／消费者的调用频率和最坏情况下的扇出

置信度：

置信度	操作
95%+	可直接建议修复。
80-94%	建议修复，但需说明注意事项并提供验证命令。
60-79%	先列出未知项；收集更多证据后再修复。
<60%	停止。不要提出建议。

---

阶段 3：逐项维度检查

必须注意：每次只针对一个维度进行检查。绝不可一次扫描所有维度。

1. 查询形态与数据精简

思考： 加载了哪些行／列？筛选、投影、排序和限制是否在数据源中、实例化之前执行？

必须注意以下问题：

• 不受限制的列表／读取全部 API，缺少分页、限制、游标或有界业务约束
• 实例化后才筛选（先执行 ToList／数组化／加载全部，再执行 Where／筛选）
• 实例化后才投影；列表／摘要视图加载完整实体／文档
• 未使用的 include／join／查找数据；列表查询加载大型文本／blob／json 字段
• 客户端排序／分组／去重；在更适合游标／键集分页的场景中，对非常深的页面使用偏移分页
• 热路径查询缺少租户／授权／状态／日期筛选条件

必须注意优先考虑的修复：将谓词下推至数据源，仅选择所需字段，限制结果集；对深层顺序访问使用游标／键集；将可复用谓词保留在本地发现的领域／查询所有者层附近。

2. 索引与访问路径

思考： 现有索引能否按照实际查询顺序满足等值／范围筛选、连接、排序、分组和投影？

必须注意以下问题：

• 高基数筛选条件、连接、外键、排序列或常用分组键缺少索引
• 复合索引字段顺序与等值 → 范围 → 排序的访问模式不匹配
• 索引虽存在，但查询计划未使用，因为查询对字段应用了函数／类型转换、使用了不兼容的类型／排序规则、前导通配符、宽泛的 OR、否定谓词或低选择性
• 索引顺序与筛选条件 + order by 不匹配，导致排序溢出／filesort
• 热点窄查询可使用覆盖／部分／筛选索引
• 未分析写入成本就添加每个字段，导致索引膨胀

必须注意优先考虑的修复：添加／调整最小且有用的索引；重新排列复合键以匹配查询；重写谓词，使其可进行索引查找；在修改前后通过计划／explain 验证；说明写入成本风险。

3. N+1 与扇出

思考： 工作量是否随条目数而不是请求／作业数增长？

必须注意以下问题：

• 在循环、map、序列化器、解析器、模板／渲染循环或事件处理循环中调用查询／API／缓存
• 逐条进行存在性／计数查询；逐条延迟加载关联
• 使用不同 ID 重复执行相同查找，而这些查找可以合并为一个 IN／批处理／分组查询
• 在服务、队列、作业或重试之间发生嵌套扇出
• 对彼此独立的调用使用顺序 await，而这些调用可以批处理或使用独立的安全资源进行有界并行执行

必须注意优先考虑的修复：一次性批量处理 ID；仅连接／包含所需字段；预取字典；在一个查询中汇总计数；使用有界并发；保留排序／授权语义。

4. 聚合、联接与管道形态

思考： 管道是否会在高开销的联接／展开／分组／排序／窗口阶段之前先缩减数据？

务必重点查找：

• 在选择性筛选之前进行联接／展开／分组
• 笛卡尔联接或重复扩展后未进行折叠
• 未预先筛选或缺少支持索引的分组／排序
• 实际只需判断是否存在、计数、求最小值或最大值，却聚合加载所有相关行／文档
• 数据库可以安全计算，却重复进行后处理

务必优先考虑以下修复：尽早筛选、尽早投影、在数据源处聚合、降低联接基数、使用存在性／计数查询，并在数组／子项语义有要求时，重复执行必要的扩展后筛选。

5. 物化与内存

思考： 什么内容会进入内存？读取时是否有界、采用流式处理，并且无需跟踪？

务必重点查找：

• 分页／筛选前先物化大型集合
• 只读查询不必要地跟踪实体／对象
• 为轻量响应加载 blob／文件／大型 JSON 字段
• 明明可以流式处理／分块，却缓冲整个导出／报告
• 意外进行多次枚举，导致查询重复运行

务必优先考虑以下修复：分页／分块／流式处理；当本地技术栈支持时，使用无跟踪／只读模式；投影为轻量 DTO；在加载前移动筛选条件；有意缓存计算结果。

6. 写入路径、锁与事务

思考： 写入操作是否能安全地批处理，并将锁和事务保持在较小范围内？

务必重点查找：

• 在循环中逐行保存／更新／删除
• 长事务中包含远程调用或大量读取
• 逐行执行不必要的唯一性检查，而非批量验证
• 锁升级／热点行争用／未批处理的计数器更新
• 并行写入共享不安全的会话／上下文／工作单元

务必优先考虑以下修复：批量写入、分块、缩短事务、将远程调用移到事务外、使用幂等命令，并为每个并行工作线程创建新的安全作用域／上下文。

7. 缓存与复用

思考： 重复的高开销操作是否稳定、安全且能正确失效？

务必重点查找：

• 在同一请求／作业中重复执行相同的查找
• 每次请求都获取高频引用数据
• 缓存键缺少租户／用户／授权／筛选条件／版本等维度
• 缓存掩盖了无界查询，或缓存了过时的安全敏感数据

务必优先考虑以下修复：先使用请求作用域内的记忆化，再使用有界共享缓存，并明确设置键、TTL／失效策略、大小限制、隐私约束以及命中／未命中指标。

8. API、分布式系统与前端

思考： 慢操作是否由网络瀑布、负载大小、渲染开销或后台扇出造成？

务必重点查找：

• 端点返回的负载超过视图所需
• 存在后端聚合或批量端点可用，却按顺序执行远程调用
• 消息消费者未批处理／施加背压，导致每个项目都发布一条消息
• 前端重复获取数据、缺少列表虚拟化、渲染循环开销大、缺少稳定键／track-by
• 包或资源加载占用了大部分交互时间

务必优先考虑以下修复：使用批量 API、减少负载、添加背压、对大型列表进行虚拟化、稳定渲染键、延迟加载冷资源／路由，并测量浏览器／网络跟踪数据。

---

第 4 阶段：发现与严重性

发现格式：

- [Severity] [file:line] [dimension] Problem. Evidence: metric/plan/query count. Impact: user/system effect. Fix: smallest behavior-preserving change. Verify: command/query/metric.

严重性：

• 严重：存在服务中断／OOM／数据损坏风险、无界热点路径、锁风暴或失控扇出。
• 高：存在 p95／p99 超时风险、大型／热点表或集合上的全表扫描、用户可见列表上的 N+1 问题，或缺少分页上限。
• 中：可避免的过量获取、次优索引、重复查找或中度内存浪费。
• 低：收益较小但可衡量的清理工作，或为未来做准备。

没有类生产规模／频率的证据时，绝不可夸大严重性。

---

阶段 5：优化计划

更改代码前：

• MUST ATTENTION 提供基线、拟议更改、行为不变量、风险、验证命令和回滚路径。
• MUST ATTENTION 保持功能行为、授权、排序、分页语义、一致性和幂等性。
• MUST ATTENTION 当行为、SLA、公开契约或限制发生变化时，检查受影响的测试／规范／文档。
• NEVER 仅为提升速度而更改查询语义，除非用户批准行为变更。
• NEVER 在未分析写入成本、存储成本、失效机制和隐私影响的情况下，添加宽泛索引／缓存。

---

子 Agent 路由

条件允许时，使用专门的帮助：

检测到的重点	子 Agent
DB／查询／N+1／内存／后端热点路径	performance-optimizer
身份验证、PII、租户隔离、敏感缓存键	先使用 security-auditor，然后使用 performance-optimizer
跨服务架构、缓存策略、容量／SLO 权衡	架构／性能专家
前端渲染／包体／网络瀑布流	前端或性能专家

子 Agent 提示词 MUST 包含目标、检测到的范围、本地上下文证据、所需维度、报告路径，以及“仅返回摘要；逐步写入完整报告”。

---

全新视角质量循环

1. 第 1 轮：提供带证据的发现／计划。
2. 第 2 轮：启用一位全新的审查者，或从零记忆视角重新进行审查；质疑遗漏的瓶颈、误报、错误的根因和不安全的修复。
3. 如果发现问题：修订计划 -> 由另一位全新的审查者重新审查。
4. 最多 3 轮：停止并请用户做出决定。

非简单审查要获得干净的 PASS，MANDATORY 需要进行全新视角质疑，或明确说明跳过原因。

---

输出

最终报告 MANDATORY 包含以下部分：

• 范围和检测到的瓶颈类型
• 基线证据和未知项
• 按严重程度排序的发现
• 优化计划和被否决的替代方案
• 包含前后指标的验证计划
• 测试／规范／文档影响，或明确说明跳过原因
• 置信度和假设

如果证据不足，输出：证据不足。已验证：[...]。未验证：[...]。需要的下一步证据：[...]。

---

收尾提醒

重要，强制要求，务必注意 保持项目通用性：在评判前，先了解本地技术栈、约定、查询 API、索引定义、指标和报告路径。 重要，强制要求，务必注意 每项性能主张都必须有测量结果或静态证据佐证：file:line、查询文本／形态、行数、查询计划／解释输出、跟踪记录、性能分析结果或日志。 重要，强制要求，务必注意 一次只评审一个数据库性能维度：过量读取、过滤条件、索引、N+1 扇出、批处理、聚合／连接形态、物化、写入、缓存。 重要，强制要求，务必注意 始终测量优化前后的情况；静态评审发现必须附上明确的验证命令。 重要，强制要求，务必注意 始终使用实际查询形态／顺序和查询计划／解释输出验证索引是否可用；仅有索引并不能作为证据。 重要，强制要求，务必注意 始终先将行过滤下推至数据源，再进行投影／缓存；减少行数比精简列更重要。 重要，务必注意 对于非简单的性能工作，在判定为 PASS 前进行换位审视。 重要，务必注意 添加最终评审任务，检查文档／测试／规范是否过时。

反合理化：

借口	反驳
“瓶颈很明显，跳过基线测量”	没有测量结果就只是猜测。记录指标，或将其标记为静态风险。
“索引已经存在，所以查询没问题”	展示查询计划／解释输出和访问路径。已有但未使用的索引毫无证明力。
“投影就够了”	先减少行数。从过多的行中少加载几列，仍然会浪费资源。
“直接缓存就好”	先修正查询形态／索引／范围。缓存可能掩盖过时、不安全或无界的工作。
“代码里只有一个查询”	跟踪循环、序列化器、解析器、消费者和重试逻辑。扇出问题往往隐藏在上游。

[TASK-PLANNING] 开始前将工作拆分为可跟踪的小任务；每项任务的状态都要立即更新。

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

来源：.claude/hooks/lib/prompt-injections.cjs + .claude/.ck.json

[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，然后打开其中列出的项目参考文档。只要具备此共享上下文和本地文档，任何受支持的 AI 工具都可以执行。

1. 检测： 将提示词与工作流目录进行匹配
2. 分析： 找出最匹配的工作流，并评估自定义步骤组合是否更合适
3. 询问（必需格式）： 直接向用户提问，采用以下结构；除非用户明确调用了某个工作流／技能，且本地协议将明确调用视为确认：
   • 问题："你想启用哪个工作流？"
   • 选项 1："启用 [最佳匹配工作流]（推荐）"
   • 选项 2："启用自定义工作流：[步骤 1 → 步骤 2 → ...]"（附上一句话说明理由）
4. 启用（确认后）： 标准工作流调用 $workflow-start <workflowId>；自定义步骤按顺序手动执行
5. 创建任务： 跟踪工作流的所有步骤
6. 执行： 按顺序遵循每个步骤 [CRITICAL-THINKING-MINDSET] 运用批判性思维和顺序思维。每项声明都必须有可追溯的证据；置信度超过 80% 才能采取行动。 反幻觉原则： 切勿将猜测当作事实；每项声明都要引用来源；坦率承认不确定性；自行检查输出是否有误；独立交叉核对；对自己的判断保持怀疑——没有证据的确信是所有幻觉的根源。 AI 注意力原则（首因－近因效应）： 对于较长的提示词／协议，将最关键的 3 条规则同时放在开头和结尾，以确保指令在较长上下文窗口中仍能得到遵循。 目标驱动执行： 先定义成功标准，循环执行直至验证通过，并且只有在可观察的检查均通过后才停止。 测试验证意图： 测试必须保护业务规则／不变量，并在受保护的意图被破坏时失败，而不能只照搬当前行为。

[LESSON-LEARNED-REMINDER] [BLOCKING] 任务规划与持续改进 — 强制执行。不得跳过。

开始前将工作拆分为小任务并进行跟踪。添加最终任务："分析 AI 错误与经验教训"。

提取经验教训——仅限根本原因，不处理表面症状：

1. 指明失败模式（推理／假设失误），而非症状——例如“未阅读源代码就假设 API 存在”，而不是“使用了错误的枚举值”。
2. 通用性测试：此失败模式是否适用于 ≥3 种情境／代码库？如果不适用，就再抽象一层。
3. 将其写成通用规则——去除项目特定的名称／路径／类。该规则应适用于任何代码库。
4. 合并：多个错误若有相同的失败模式 → 总结为一条经验教训。
5. 重复发生检查：“如果没有这条提醒，未来会话中还会发生这种情况吗？”——不会 → 跳过 $learn。
6. 自动修复检查：“$code-review／$code-simplifier／$security／$lint 能否发现此问题？”——能 → 改进相应的审查技能。
7. 两项检查均通过 → 请用户运行 $learn。 [TASK-PLANNING] [MANDATORY] 在执行任何工作流或技能步骤之前，先为所有计划步骤创建／更新任务跟踪；然后随着每个步骤开始／完成，持续同步任务状态。