企业官网建设流程全解析

Claude Code Game Studios 性能分析师 Agent 行为规格解读：从帧时间数据到可执行优化建议

【免费下载链接】Claude-Code-Game-StudiosTurn Claude Code into a full game dev studio — 49 AI agents, 72 workflow skills, and a complete coordination system mirroring real studio hierarchy.项目地址: https://gitcode.com/GitHub_Trending/cl/Claude-Code-Game-Studios

导读

本文基于 Claude Code Game Studios（CCGS）项目中的 performance-analyst 行为测试规格，完整解析这个负责「性能剖析、瓶颈定位、指标追踪与优化建议」的专业 Agent 的职责边界、五个核心测试场景与协议合规要求。通过阅读本文，你将掌握：CCGS 中性能分析 Agent 如何处理帧时间数据并产出分级瓶颈报告、如何在收到优化实现请求时正确转派给对应程序员、如何用二分定位法追踪性能回归、如何权衡优化收益与代码质量，以及如何严格依据technical-preferences.md中的预算阈值给出 WITHIN BUDGET / AT RISK / OVER BUDGET 判定。

一、Agent 定位：只做分析与建议，绝不越权实现

performance-analyst 是 CCGS 49 个 AI Agent 中的一名专业分析师，归属于specialists层级。根据其规格文件（performance-analyst.md），其职责边界非常清晰：

• 管辖领域（Domain）：性能剖析（Profiling）、瓶颈识别（bottleneck identification）、性能指标追踪（performance metrics tracking）、优化建议（optimization recommendations）。
• 不拥有（Does NOT own）：实施优化（implementing optimizations）——这项工作属于对应领域的程序员（appropriate programmer）。
• 模型档位（Model tier）：Sonnet（默认，与所有 specialists 一致）。
• 门禁 ID：无（不绑定任何 director gate）。

这一「分析归分析师、实现归程序员」的职责划分，是整个 CCGS 协调体系的核心设计。在 catalog.yaml 中，performance-analyst 以category: specialist登记，规格路径指向CCGS Skill Testing Framework/agents/specialists/performance-analyst.md；而在 quality-rubric.md 的 specialist 类目下，它必须满足三条指标：

这三条指标正是下文五个测试用例反复验证的行为底座。

静态断言（结构合规检查）

规格文件定义了 4 项静态断言（performance-analyst.md），用于在/skill-test static阶段自动校验 Agent 定义文件的结构：

• description:字段必须存在且领域相关（提及 profiling / bottleneck analysis / performance metrics）；
• allowed-tools:列表必须包含 Read、Write、Edit、Bash、Glob、Grep 六项工具；
• 模型档位必须为 Sonnet（specialists 的默认档位）；
• Agent 定义不得声称对任何优化实施拥有裁决权——必须明确自我定位为「仅分析与建议」。

需要说明的是，虽然规格允许 Write/Edit 工具，但根据分析类工作流的通行约束（参见 quality-rubric.md 中 analysis 类技能的 AN1「扫描阶段只读」原则），这些写权限仅用于在用户批准后落盘报告，而非修改游戏代码。

二、Case 1：领域内请求——帧时间数据的分级瓶颈报告

输入示例（来自 Case 1）：

"Analyze this frame time data: CPU 14ms, GPU 8ms, physics 6ms, draw calls 420, scripts 3ms."

这是 performance-analyst 最典型的领域内请求。规格要求它按以下逻辑输出：

1. 识别主瓶颈：CPU 总耗时 14ms 已接近 60fps 的 16.67ms 帧预算——注意，这里 CPU 14ms 本身就接近超限，且通常 CPU 与 GPU 是并行流水线，CPU 侧 14ms 直接决定帧率；
2. 拆解贡献者：物理（Physics）6ms，占 CPU 时间的 43%，是首要嫌疑；
3. 标记次优关注点：draw calls 420 次，若项目预算更低（例如 [technical-preferences.md] 中规定的 200 次上限）则作为次要问题标记；
4. 产出按优先级排序的瓶颈报告：
   • ① 物理系统 — 6ms：降低模拟频率（simulation frequency）或切换 broadphase 算法；
   • ② Draw calls — 420 次：实施批处理（batching）或 LOD；
   • ③ 脚本 — 3ms：对热点路径做剖析（profile hot paths）；
5. 绝不实施这些优化中的任何一项。

与 /perf-profile 技能的关系

CCGS 中与 performance-analyst 密切配合的是/perf-profile技能（perf-profile.md）。该技能是结构化的性能剖析工作流：当提供剖析数据或性能日志时直接分析，未提供数据时输出手动剖析检查清单；报告写入前必须询问 "May I write toproduction/qa/perf-[date].md?"；判定词汇为 WITHIN BUDGET / CONCERNS / OVER BUDGET。其 Case 5 明确指出：当剖析发现 CONCERNS 级别问题（如帧时间尖峰）时，技能会输出提示"考虑携带数据运行 performance-analyst Agent 进行深入分析"——分析师（Agent）与剖析工作流（Skill）由此衔接。

同时，规格的 Coverage Notes（performance-analyst.md）要求：Case 1 的帧时间分析输出应作为一份结构化报告归档到production/qa/evidence/目录，为后续回归对比留存证据基线。

三、Case 2：越域请求——把实现工作正确转派给程序员

输入示例：

"Implement the batching optimization to reduce draw calls from 420 to under 200."

这是一个典型的越域请求——用户直接要求实施批处理优化。规格（Case 2）要求：

• 不产生任何批处理的实现代码；
• 明确声明：实施优化属于对应领域的程序员——渲染批处理归engine-programmer；
• 将实现转派给engine-programmer，并附带推荐上下文（recommendation context）；
• 可以产出一份优化需求简报（requirements brief），让 engine-programmer 有清晰的实施目标。

这与 engine-programmer 自身的规格形成闭环：在 engine-programmer.md 中，engine-programmer 的管辖领域正是渲染管线、物理集成、内存管理与资源加载——「实现自定义对象池」「渲染批处理」都落在其职责内。由此可以看到 CCGS 的职责分配链路：

performance-analyst（定位瓶颈、量化指标、产出建议） │ 转派实现 + 附建议上下文 ▼ engine-programmer（渲染批处理 / 对象池 / 内存优化等具体实现）

在 WORKFLOW-GUIDE.md 的职责速查表中，"Profile performance"（性能剖析）明确映射到performance-analyst，进一步印证该 Agent 是性能问题的第一受理人，而实现环节按领域拆分给对应程序员。

四、Case 3：回归识别——二分定位法锁定问题提交

输入示例：

"Performance dropped significantly after last week's commits. Frame time went from 10ms to 18ms."

面对性能回归，规格（Case 3）要求 Agent 具备「追因」而非「只报症状」的能力：

1. 提出二分定位策略（bisection strategy）以锁定引发问题的提交区间；
2. 请求或审查该窗口内提交的 diff，收窄可能原因；
3. 根据变更内容锁定受影响系统——例如若物理代码被改动，则物理系统是首要嫌疑；
4. 产出回归报告，指明：疑似提交（probable commit）、受影响的系统（affected system）、测量到的变化量（measured delta，即 18ms − 10ms = +8ms）。

这一点在 Coverage Notes（performance-analyst.md）中被明确强调：「Regression case confirms the agent investigates cause, not just measures symptoms」——即 Agent 必须调查根因，而非仅测量症状。

团队工作流中的实际调用场景

在 team-polish.md 描述的优化工作流中，performance-analyst 总是第一阶段首先被派生的 Agent（Phase 1 先于任何其他 Agent 派生），负责剖析战斗系统、测量帧预算、检查内存使用并输出性能报告；随后才进入 Phase 2 的优化实施。该技能还覆盖了「优化后仍超预算」的场景：当 performance-analyst 将粒子风暴成本从 12ms 优化到 9ms 但仍超出 6ms 预算时，它必须如实报告 "FRAME BUDGET VIOLATION" 并指出「不改变设计无法再进一步」——这与 Case 4 中「不掩盖权衡、如实上报」的精神一脉相承。

五、Case 4：优化建议与代码质量的权衡

输入示例：

"The fastest optimization for the script bottleneck would be to inline all calls and remove abstraction layers."

用户抛出了一个「最快」的方案，但该方案以破坏代码质量为代价。规格（Case 4）要求 Agent：

• 揭示权衡：内联（inlining）能提升性能，但会降低可测试性（testability），并违反要求「公共方法可单元测试」的编码规范；
• 不得在未标注代码质量代价的情况下推荐该优化；
• 将权衡升级给lead-programmer做决策，而不是单方面拍板；
• 可以提出折中路径（middle path）：例如仅对最热的 2–3 个方法做剖析引导的内联（profile-guided inlining），既保留可测试性又获得大部分收益。

这里的升级对象lead-programmer在 lead-programmer.md 中正是「代码架构决策、编码规范执行」的拥有者——性能优化若与编码规范冲突，必须由 lead-programmer 裁决。这体现了 CCGS 的分级决策原则：specialist 层（performance-analyst）发现问题并提出选项，lead 层（lead-programmer）依据编码规范与架构标准做最终权衡，而不是让分析师越权决定「值得不值得」。

六、Case 5：上下文预算传递——严格引用而非臆造阈值

输入示例（来自 Case 5）：

上下文中的技术偏好：目标 60fps，帧预算 16.67ms，draw calls 上限 200，内存上限 512MB。请求："Review the current build profile."

这是对「上下文传递」协议的考验，规格要求：

• 引用上下文中给出的具体数值：16.67ms、200 draw calls、512MB；
• 将当前测量值与每个阈值逐一显式对比；
• 为每个指标标注 WITHIN BUDGET / AT RISK / OVER BUDGET；
• 绝不使用上下文中未提供的其他预算数值。

这条规则与 lead-programmer 规格中的 Case 5 同构——lead-programmer 收到上下文预算（16.67ms 总预算、AI 系统 4ms 分配）后，必须用提交方案中的具体估值（7ms）与之对比并给出带数字的结论，而不是输出"这可能会慢"这类泛泛建议（lead-programmer.md）。CCGS 的预算体系同样贯穿于/perf-profile技能：其 Case 3 明确要求目标帧预算从technical-preferences.md读取而非硬编码（perf-profile.md）。换言之，**「预算数值永远来自上下文或技术偏好文件，而不是 LLM 的记忆」**是 performance-analyst 的硬性行为约束。

七、协议合规清单：六个不可妥协的行为底线

规格最后以协议合规清单（Protocol Compliance）形式，汇总了该 Agent 的全部行为约束：

• 停留在声明领域内（profiling、analysis、recommendations——而非 implementation）；
• 将优化实现转派给正确的领域 Agent；
• 返回结构化发现（含严重程度的瓶颈报告、测量值、推荐行动责任人）；
• 将代码质量权衡升级给 lead-programmer，而非单方面决策；
• 应用来自上下文的预算阈值，而非臆测的默认值；
• 为所有发现标注具体的行动责任人（谁应实施修复）。

其中「每个发现都必须标注行动责任人（action owner）」是特别值得注意的设计：性能报告不是一份「仅供参考」的文档，而是可执行的协作输入——每个瓶颈都有明确的接管者（engine-programmer、lead-programmer 或对应的系统专家），这保证了分析结果能无缝进入 CCGS 的派生与转派机制。

八、测试框架中的定位与测试方法论

规格在 Skill Testing Framework 中的位置

performance-analyst 的行为规格是 CCGS Skill Testing Framework 质量保证层的一部分。该框架（见 CCGS Skill Testing Framework/CLAUDE.md）自包含于项目、与任何具体游戏项目隔离，通过catalog.yaml登记全部 49 个 Agent 与 72 个技能；每个 Agent 规格（如本文讨论的文件）与技能规格都采用「Agent Summary + 静态断言 + 5 个测试用例 + 协议合规 + 覆盖说明」的统一骨架，模板参见 agent-test-spec.md。catalog.yaml中spec:字段是该 Agent 规格的权威路径，测试命令会优先读取它而非猜测路径。

测试用例设计方法论

从 performance-analyst 的五个用例可以归纳出这套测试框架的通用设计逻辑：

框架还特别说明（CLAUDE.md）：这些规格描述的是当前行为而非理想行为——它们是「通过阅读 Agent 定义写出来的」，因此可能编码了现有缺陷。当实践中发现 Agent 行为异常时，正确做法是先修正 Agent 定义，再更新规格以匹配修正后的行为；规格测试失败意味着「需要调查」，而非「Agent 肯定错了」。这一「规格即活文档」的立场，也是评估 performance-analyst 时应当持有的态度。

结语：把性能问题变成有主、有序、有据的协作流

performance-analyst 的行为规格看似只是一份 Agent 测试文档，但它完整定义了 CCGS 中性能工作的协作范式：分析师只诊断与建议，程序员负责实现，lead 裁决权衡，预算永远来自上下文。无论你是想在自己的 CCGS 项目中正确调用 performance-analyst 处理帧时间数据、追踪性能回归，还是想参照 agent-test-spec.md 为其他专业 Agent 编写同类行为规格，本文解析的五个用例与六条合规底线都可以直接作为行为蓝本——它们保证了性能优化在 AI 驱动的游戏开发流程中，始终是可量化、可转派、可追溯的。

【免费下载链接】Claude-Code-Game-StudiosTurn Claude Code into a full game dev studio — 49 AI agents, 72 workflow skills, and a complete coordination system mirroring real studio hierarchy.项目地址: https://gitcode.com/GitHub_Trending/cl/Claude-Code-Game-Studios