perf-profile

!bash "${CLAUDE_SKILL_DIR}/../../hooks/yaml-helper.sh" resolve_config --keys performance.enforce,automation,workflow

以上已解析——直接使用。若无区块 → 使用 .claude/docs/config-resolution.md 中的默认值。

性能配置

每次调用 AskUserQuestion 都遵循 .claude/docs/automation-modes.md （协作模式始终提问 · 引导模式仅在重大事项上提问 · 自主模式记录后继续； automation_always_ask 类别始终提示）。

输入不足——生成任何报告前都要先检查

如果此技能所需的输入不存在，答案就是“无法运行”—— 而不是一份填好的报告。 先检查；如果检查失败，就停止。

1. 列出此技能读取的输入（数据文件、先前的报告、分析器输出、 测试结果、注册表、源代码）。
2. 对每一项记录 FOUND 或 ABSENT——不得写“假定存在”。
3. 如果某个区段所需的输入为 ABSENT，该区段应标记为 NOT ASSESSED — NO DATA。不得估算，不得从相邻产物推断，也不得将模板中必须填写的单元格留给下一个阅读者填写。
4. 如果所有必需输入均为 ABSENT，就停止，并将 NOT ASSESSED — NO DATA 作为整体结论，说明缺少什么，以及哪个技能会生成这些内容。

NOT ASSESSED 结论是成功的。 当没有数据时，它才是对 “数据说明了什么？”这一问题正确且有用的回答。它要防止的是一种特定故障模式：如果报告的结论枚举中没有“无法运行”状态，就会产生 虚假的通过结果——例如资产审计在项目没有资产且没有标准时返回 COMPLIANT，或者性能配置在没有任何分析器数据、也从未设置预算的情况下，报告“相对于 16.67ms 预算仍有 >99% 的余量”。

没有证据不等于证明不存在。 如果没有可扫描的文件，因此扫描没有找到匹配项，这并不代表验证了任何内容。请明确说明实际发生的是哪一种情况——读者无法仅凭绿色结果判断。

---

阶段 0：解析预算强制执行设置

performance.enforce 决定本次运行中预算违规意味着什么。它 不会改变要测量哪些预算——performance.target_framerate、 frame_budget_ms、draw_call_limit 和 memory_ceiling_mb 在所有级别下都以相同方式进行分析：

值	对此配置的发现结果的影响
warn（默认值）	将违规作为发现结果报告。不会阻止执行；CI 会记录这些问题，但不会因此失败。
block	违规属于阻断项。请在报告中明确说明——将项目设为 block，表示超出预算的系统会阻止发布，而 /gate-check 会因此导致 Polish gate 失败。
off	预算仅供参考。仍需报告测量值，但不得将违规列为发现结果或修复建议。

只识别 warn、block 和 off。如遇其他值，请告知用户，并改用 warn，不要自行猜测。

该值可在本地覆盖（/settings --local performance.enforce=block）， 因此请使用上方已解析的区块，而不是读取 project.yaml——队友更严格的本地设置只应在他们自己的机器上生效。

阶段 1：确定范围

读取参数：

• 系统名称 → 将分析重点放在该特定系统上
• full → 对所有系统进行全面分析

---

阶段 2：加载性能预算

首先读取已提交的预算配置——它们记录了项目已同意的指标；设计文档是备用来源，而非首选来源：

bash "${CLAUDE_SKILL_DIR}/../../hooks/yaml-helper.sh" get_effective_yaml_key performance.target_framerate
bash "${CLAUDE_SKILL_DIR}/../../hooks/yaml-helper.sh" get_effective_yaml_key performance.frame_budget_ms
bash "${CLAUDE_SKILL_DIR}/../../hooks/yaml-helper.sh" get_effective_yaml_key performance.draw_call_limit
bash "${CLAUDE_SKILL_DIR}/../../hooks/yaml-helper.sh" get_effective_yaml_key performance.memory_ceiling_mb

将每一行作为单独的普通命令运行，每次调用只查询一个键：该辅助程序会自行切换到项目根目录，因此即使会话是在子文件夹中启动，也能正常工作；此技能只预先批准这种形式（使用 source 或 cd ... && 封装时，每次都需要询问用户）。输出为空表示未设置该预算。

从 project.yaml 解析这些预算，而非从说明文字中获取。 上文阶段 0 指出，这四项预算“在每个层级都以相同方式进行分析”。如果用户在 project.yaml 中设置了 performance.target_framerate: 60，却从设计文档或 CLAUDE.md 读取预算，那么该设置就会被忽略。

对于配置中未包含的内容，再从设计文档或 CLAUDE.md 获取：

• 目标 FPS（例如，60fps = 16.67ms 帧预算）
• 内存预算（总量及各系统预算）
• 加载时间目标
• 绘制调用预算
• 网络带宽限制（适用于多人游戏时）

没有已提交预算的指标应标记为 NOT ASSESSED，而不是通过。 不要对照模板中的 [16.67ms] 占位值进行测量——未设置的预算不等于已达成的预算；声称相对于无人选择的数值有剩余空间，正是此技能自身标题所警告的捏造行为。

---

阶段 3：分析代码库

CPU 分析目标：

• _process() / Update() / Tick() 函数——列出所有函数并估算其开销
• 遍历大型集合的嵌套循环
• 热路径中的字符串操作
• 逐帧代码中的分配模式
• 对游戏实体进行未经优化的搜索或排序
• 每帧执行的昂贵物理查询（射线检测、重叠检测）

内存分析目标：

• 大型数据结构及其增长模式
• 纹理/资源内存占用估算
• 对象池与实例化/销毁模式
• 泄漏的引用（应释放却未释放的对象）
• 缓存大小和淘汰策略

渲染目标（如适用）：

• 绘制调用估算
• 重叠透明对象造成的过度绘制
• 着色器复杂度
• 未经优化的粒子系统
• 缺少 LOD 或遮挡剔除

I/O 目标：

• 保存/加载性能
• 资源加载模式（同步还是异步）
• 网络消息的频率和大小

---

阶段 4：生成性能分析报告

将报告写入 production/polish/[scope]-report-[date].md，并遵循协作协议事先询问：“我可以将此性能分析报告写入 production/polish/[scope]-report-[date].md 吗？” 如果目录不存在，则创建该目录。

明确指定目标位置——不要只在对话中呈现模板。 仅存在于对话记录中的分析结果会在会话结束时消失，也无法比较两次运行的结果。production/polish/ 与 /team-polish 写入的位置相同，这是有意为之：通过任一路径进行的分析都应归档在同一位置，否则便无法进行此技能旨在支持的比较。

如果报告中仍有 NOT ASSESSED 部分，请将其保留在写入的文件中。如果在写入磁盘前删掉分析中的缺漏，之后看来就像是完成了全面测量。

## Performance Profile: [System or Full]
Generated: [Date]

### Performance Budgets
| Metric | Budget | Estimated Current | Status |
|--------|--------|-------------------|--------|
| Frame time | [16.67ms] | [estimate] | [OK/WARNING/OVER/NOT ASSESSED] |
| Memory | [target] | [estimate] | [OK/WARNING/OVER/NOT ASSESSED] |
| Load time | [target] | [estimate] | [OK/WARNING/OVER/NOT ASSESSED] |
| Draw calls | [target] | [estimate] | [OK/WARNING/OVER/NOT ASSESSED] |

### Hotspots Identified
| # | Location | Issue | Estimated Impact | Fix Effort |
|---|----------|-------|------------------|------------|

### Optimization Recommendations (Priority Order)
1. **[Title]** — [Description]
   - Location: [file:line]
   - Expected gain: [estimate]
   - Risk: [Low/Med/High]
   - Approach: [How to implement]

### Quick Wins (< 1 hour each)
- [Simple optimization 1]

### Requires Investigation
- [Area that needs actual runtime profiling to confirm impact]

输出报告时附上摘要：最突出的 3 个瓶颈、相对于每项已设置预算的预计余量——对于未设置预算的指标，写明 no budget set — headroom not assessed——以及建议采取的下一步行动。

---

阶段 5：范围和时间线决策

仅当任一热点的修复工作量评级为 M 或 L 时，才启用此阶段。

展示需要付出大量工作量的项目，并要求用户逐项选择：

• A）实施优化（立即进行修复或安排修复——对于没有冲刺的 workflow: minimal，将其加入简报的构建顺序）
• B）缩减功能范围（运行 /scope-check [feature] 分析权衡）
• C）接受性能损失并推迟到润色阶段（记录为已知问题）
• D）提交给 technical-director 做出架构决策（运行 /architecture-decision）

如果多个项目被推迟到润色阶段（选项 C），请将它们记录在 ### 推迟到润色阶段 下。

---

结论

每次生成报告的运行结束时都要给出结论——无论是否执行了阶段 5： 结论：已完成 — 已生成性能档案（如果获准写入，则保存到 production/polish/[scope]-report-[date].md）。唯一的其他结果是上述 未评估 — 无数据路径。

---

阶段 6：后续步骤

• 如果瓶颈需要架构调整：运行 /architecture-decision。
• 如果需要缩减范围：运行 /scope-check [feature]。
• 要安排优化：运行 /sprint-plan update（对于没有冲刺的 workflow: minimal，将其加入简报的构建顺序）。

规则

• 未先进行测量，切勿优化——对性能的直觉并不可靠
• 建议必须包含预估影响——“让它更快”并非可执行的建议
• 应在目标硬件上进行性能分析，而不只是开发机器
• 静态分析（此技能）用于识别候选项；运行时性能分析用于确认