arch-performance-optimization

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

快速概览

目标： 分析并解决数据库、API、网络和前端各层的性能瓶颈。

工作流：

1. 识别瓶颈 — 判断问题属于数据库、API、网络还是前端
2. 测量基线 — 在变更前收集指标（响应时间、查询时间、包大小）
3. 优化 — 应用针对特定层的修复（索引、缓存、延迟加载、OnPush）
4. 验证 — 再次测量并确认性能有所改善且没有回归

关键规则：

• 生产环境中只查询所需列，并限制每个结果集的大小（分页／上限）；切勿使用 SELECT * 或不设上限的查询——原因：面对真实数据量时，无限制读取会导致内存占用和延迟激增
• 始终使用异步 I/O；切勿用 .Result 阻塞线程
• 使用预加载或批量获取来消除 N+1 查询模式
• 后台任务使用有界并行（ParallelAsync 配合 maxConcurrent）

保持审慎。运用批判性思维和顺序思维。每项主张都需要可追溯的证据和置信度百分比（想法应超过 80%）。

性能优化工作流

何时使用此技能

• API 响应时间缓慢
• 数据库查询优化
• 前端渲染问题
• 内存使用方面的顾虑
• 可扩展性规划

准备检查清单

• 确认性能瓶颈
• 收集基线指标
• 确定可接受的阈值
• 规划测量方法

性能分析框架

步骤 1：识别瓶颈类型

Performance Issue
├── Database (slow queries, N+1)
├── API (serialization, processing)
├── Network (payload size, latency)
└── Frontend (rendering, bundle size)

步骤 2：测量基线

# API response time
curl -w "@curl-format.txt" -o /dev/null -s "http://api/endpoint"

# Database query time (SQL Server)
SET STATISTICS TIME ON;
SELECT * FROM Table WHERE ...;

# Frontend bundle analysis
npm run build -- --stats-json
npx webpack-bundle-analyzer stats.json

数据库优化

⚠️ 务必阅读： CLAUDE.md，了解 N+1 检测、预加载、投影、分页和并行查询模式。高级索引和查询优化请参阅 database-optimization 技能。

索引建议

-- Frequently filtered columns
CREATE INDEX IX_Employee_CompanyId ON Employees(CompanyId);
CREATE INDEX IX_Employee_Status ON Employees(Status);

-- Composite index for common queries
CREATE INDEX IX_Employee_Company_Status
ON Employees(CompanyId, Status)
INCLUDE (FullName, Email);

-- Full-text search index
CREATE FULLTEXT INDEX ON Employees(FullName, Email);

API 优化

⚠️ 务必阅读： CLAUDE.md，了解并行元组查询和响应 DTO 模式。

缓存

// Static data caching
private static readonly ConcurrentDictionary<string, LookupData> _cache = new();

public async Task<LookupData> GetLookupAsync(string key)
{
    if (_cache.TryGetValue(key, out var cached))
        return cached;

    var data = await LoadFromDbAsync(key);
    _cache.TryAdd(key, data);
    return data;
}

前端优化

包体积

// :x: Import entire library
import _ from 'lodash';

// :white_check_mark: Import specific functions
import { debounce } from 'lodash-es/debounce';

延迟加载

// :white_check_mark: Lazy load routes
const routes: Routes = [
    {
        path: 'feature',
        loadChildren: () => import('./feature/feature.module').then(m => m.FeatureModule)
    }
];

变更检测

// :white_check_mark: OnPush for performance
@Component({
  changeDetection: ChangeDetectionStrategy.OnPush
})

// :white_check_mark: Track-by for lists
trackByItem = this.ngForTrackByItemProp<Item>('id');

// Template
@for (item of items; track trackByItem)

虚拟滚动

// For large lists
import { CdkVirtualScrollViewport } from '@angular/cdk/scrolling';

<cdk-virtual-scroll-viewport itemSize="50">
  @for (item of items; track item.id) {
    <div class="item">{{ item.name }}</div>
  }
</cdk-virtual-scroll-viewport>

后台任务优化

⚠️ 务必阅读： CLAUDE.md，了解有界并行（使用 ParallelAsync 和 maxConcurrent）以及批处理（使用 UpdateManyAsync）模式。

性能监控

记录慢操作

var sw = Stopwatch.StartNew();
var result = await ExecuteOperation();
sw.Stop();

if (sw.ElapsedMilliseconds > 1000)
    Logger.LogWarning("Slow operation: {Ms}ms", sw.ElapsedMilliseconds);

数据库查询日志

// In DbContext configuration
optionsBuilder.LogTo(
    Console.WriteLine,
    new[] { DbLoggerCategory.Database.Command.Name },
    LogLevel.Information);

性能检查清单

数据库

• 在筛选列上建立索引
• 预加载关联数据
• 对部分数据使用投影
• 在数据库层进行分页
• 不存在 N+1 查询

API

• 尽可能并行执行操作
• 使用响应 DTO（而非实体）
• 对静态数据进行缓存
• 对列表进行分页

前端

• 对路由进行延迟加载
• 使用 OnPush 变更检测
• 对列表使用 track-by
• 对大型列表使用虚拟滚动
• 对导入进行摇树优化

后台任务

• 有界并行
• 批量操作
• 分页处理
• 合理安排调度

要避免的反模式

:x: 在生产环境中使用 SELECT *

var all = await context.Table.ToListAsync();

:x: 同步 I/O

var result = asyncOperation.Result;  // Blocks thread

:x: 无界结果集

await repo.GetAllAsync();  // Could be millions

:x: 在循环中重复调用数据库

foreach (var id in ids)
    await repo.GetByIdAsync(id);  // N queries

验证检查清单

• 已记录基准指标
• 已识别并解决瓶颈
• 已根据基准测量变更效果
• 未引入新的性能问题
• 已设置监控

相关内容

• arch-security-review
• database-optimization

---

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

• docs/project-reference/domain-entities-reference.md — 领域实体目录、关系、跨服务同步（任务涉及业务实体/模型时阅读）（相关时直接阅读；不要依赖钩子注入的对话文本）

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

删除前检查下游引用。 删除组件会导致文档和代码连锁过时。移除前，先梳理所有引用该组件的文件。 根据实际代码核实 AI 生成的内容。 AI 会幻觉出 API、类名和方法签名。记录或引用前，务必通过 grep 确认它们确实存在。 编辑后追踪完整依赖链。 更改定义时，可能会遗漏由此派生的下游变量和使用方。务必追踪完整链条。 核实正确性时追踪所有代码路径。 确认代码存在不等于确认它会执行。务必追踪提前退出、错误分支和条件跳过，而不仅仅是正常路径。 调试时，修复前先问「谁该负责？」 追踪 bug 是在调用方（数据错误）还是被调用方（处理错误）。在负有责任的层修复，绝不要只修补症状出现的位置。 假设现有值是有意设置的——更改前先问为什么。 更改任何常量、限制、标志或模式前：阅读注释、检查 git blame，并查看周边代码。 核实所有受影响的输出，而不只是第一个。 涉及多个技术栈的更改，必须核实每一项输出。一次检查通过不代表所有检查都通过。 整体优先的调试方式——避免被最近关注点误导。 调查任何故障时，先列出所有前置条件（配置、环境变量、数据库名称、端点、DI 注册、数据前置条件），再逐项根据证据核实，然后才能形成任何代码层面的假设。 精准修改——执行差异测试。 修复 bug 时，每一行更改都必须能直接追溯到该 bug。不要顺手调整相邻代码的样式或加以改进。增强任务：实现改进，并明确说明。 编码前指出歧义——不要默默做选择。 如果请求有多种解释，应逐一说明并估算工作量，然后询问。绝不要擅自假设要处理所有记录、采用基于文件的方案或选择更复杂的路径。

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

基于证据的推理 — 禁止推测。每项主张都必须有证据。

1. 每项主张都要引用 file:line、grep 结果或框架文档
2. 声明置信度：>80% 可直接行动，60-80% 先核实，<60% 不要提出建议
3. 架构更改必须进行跨服务验证
4. 「证据不足」是有效且符合预期的输出

以下条件满足前不得继续： - [ ] 证据文件路径（file:line）- [ ] 已执行 grep 搜索 - [ ] 已找到 3 个以上相似模式 - [ ] 已说明置信度

未经证明禁止使用： “显然”“我认为”“应该是”“可能是”“这是因为” 如果未完成 → 输出："证据不足。已核实：[...。]未核实：[...。]"

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

必须注意： 运用批判性思维——每项主张都需要可追溯的证据，置信度必须高于 80% 才能采取行动。反幻觉：绝不要把猜测说成事实。

必须注意： 遵循防止 AI 犯错的原则——整体优先地调试，在负有责任的层修复，编码前指出歧义，并在上下文压缩后重新阅读文件。

收尾提醒

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

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

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

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

[WORKFLOW-EXECUTION-PROTOCOL] [BLOCKING] 工作流执行协议 — 强制 重要 必须 关键。无论任何原因，都不得跳过。

通用可移植性边界： 可复用技能和协议文本应保持项目中立；项目专属约定应从 docs/project-config.json 和 docs/project-reference/ 中查明。应用共享 AI-SDD，参见 shared/sdd-artifact-contract.md。阅读 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. 执行： 按顺序完成每个步骤 [关键思维模式] 运用批判性思维和顺序思维。每项断言都需要可追溯的证据；置信度 >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] 执行任何工作流或技能步骤之前，先为所有计划步骤创建或更新任务跟踪，然后在每个步骤开始和完成时保持任务跟踪同步。