Cocos 游戏项目的 Claude Code 配置实践(7)：Agents

系列文章目录：总览 → CLAUDE.md → Rules → Skills → MCP → Hooks → [Agents]

朋友们大家好，我是 bit老宫 呀，一个拥有12年一线开发经验的CocosCreator游戏开发者，代表作 《比特小队》 《宫爆老奶奶家族篇》

这是系列的最后一篇。

前五层各司其职：CLAUDE.md 建立项目认知，Rules 按场景注入规范，Skills 自动化重复流程，MCP 提供 API 知识库，Hooks 在系统层面兜底。但还有一类任务，这些工具都覆盖不到——需要深度分析和专业判断的任务。

比如代码 review。你不是要 AI 检查「有没有 console.log」（Hooks 能做），而是要它判断「这个系统缓存了组件引用，违反了 ECS 无状态原则」。这需要理解项目架构、掌握领域规范、具备推理能力。

Agents 就是为这类任务设计的。

Agent 和 Skills 的区别

这两个概念容易搞混，先厘清：

  Skills Agents
本质 步骤固化的流水线 有专业背景的子 AI
执行方式 按预定步骤顺序执行 自主分析、判断、决策
适用场景 流程清晰的重复任务 需要推理的复杂任务
典型例子 创建窗口、生成组件 代码 review、架构分析
灵活性 低（步骤固定） 高（根据输入自主决策）

简单说：Skills 是 SOP，Agents 是专家。SOP 告诉你「第一步做什么、第二步做什么」；专家拿到任务后自己分析怎么做。

Agent 文件结构

Agent 定义文件放在 .claude/agents/ 目录，格式是带 YAML frontmatter 的 Markdown：

---
name: game-reviewer
description: 游戏代码审查员，审查 ECS/UI/FGUI 代码的架构合规性
model: sonnet
---

（系统提示内容……）

关键配置：

  • name：Agent 的标识符，主对话中用这个名字调度
  • description：描述 Agent 的能力和触发条件
  • model：指定使用的模型（可以用更快的 sonnet 来降低成本）

我的 game-reviewer Agent

这是我项目里最核心的 Agent，完整展示它的设计思路。

定位

通用的 code reviewer 不懂游戏 ECS 架构，只能做表面检查（命名规范、格式问题）。game-reviewer 是游戏项目专属的代码审查员，它深度理解 bit-framework 的架构规则，可以做到架构层面的审查。

系统提示设计

你是 bit-framework 游戏项目的代码审查员，精通 Cocos Creator 3.8.8
+ TypeScript + FairyGUI + ECS 架构。

审查风格：直接指出问题，保持简洁，不需要先肯定做得好的地方。

开头两句话定义了 Agent 的身份和风格。「不需要先肯定」很重要——AI 默认会先说「代码写得不错，但是……」，review 不需要这种客套。

审查流程

Agent 的系统提示里定义了完整的审查流程：

第一步：确定审查范围

  • 读取 git diff 或最近修改的文件
  • 如果有计划文档，读取并对照

第二步：计划对齐检查

  • 实现是否覆盖了计划中的所有功能点
  • 是否有偏离计划的改动

第三步：项目规范检查

这是核心部分，包含四大类检查项：

#### 命名规范
- [ ] 类名 PascalCase、接口 I 前缀、类型别名 T 前缀
- [ ] 私有属性 _ 前缀，私有方法不加 _ 前缀
- [ ] 布尔类型必须用语义前缀：is / has / should / can ...
- [ ] 所有成员显式声明 public / protected / private

#### ECS 规范（当变更涉及 ecs/ 目录时）
- [ ] 组件只存储数据，禁止包含业务逻辑
- [ ] 组件必须实现 reset() 方法
- [ ] 系统禁止存储持久状态
- [ ] 装饰器通过解构获取

#### UI 窗口规范
- [ ] 窗口继承 Window 基类，使用 @uiclass 装饰
- [ ] @uiprop 属性使用 _ 前缀，类型用 FGUI 命名空间
- [ ] 禁止直接操作 FGUI 原始节点路径

#### 事件通信规范
- [ ] 跨模块通信使用 GlobalEvent
- [ ] 销毁时清理监听
- [ ] 事件参数有明确类型，禁止 any

第四步：架构合规检查

  • 无循环依赖
  • 模块间通过 header.ts 统一导入
  • 不存在跨模块直接调用

输出格式

Agent 的输出也有严格定义——按严重级别分类：

# 代码审查报告

## 概览
- 变更范围：[涉及的文件和模块]
- 计划对齐：[符合 / 有偏离 / 无计划文档]

## 问题清单

### Critical（必须修复）
- **[文件:行号]** 问题描述 → 修复建议

### Important（应该修复）
- **[文件:行号]** 问题描述 → 修复建议

### Suggestion（建议改进）
- **[文件:行号]** 问题描述 → 改进建议

分级很重要。Critical 是架构层面的硬伤（组件里写了业务逻辑、跨模块直接调用），必须修；Suggestion 只是「可以更好」的建议，不强制。

重要原则

系统提示的最后写了几条硬性原则：

  • 只报告置信度 > 80% 的问题：不确定的不报，减少误报噪音
  • 读完整文件再评判：不要只看 diff 片段就下结论
  • 严重级别定义清晰：Critical 是架构违规和安全问题，不是格式不好看

自动触发 vs 手动触发

Agent 的 description 字段可以声明触发条件。我的 game-reviewer 配置了：

PROACTIVELY dispatch this agent after writing or editing TypeScript files
under assets/script/. Do NOT wait for the user to ask.

这意味着主对话的 AI 在写完游戏代码后，会自动调度 game-reviewer 做审查，不需要用户手动触发。写完代码 → 自动 review → 发现问题 → 自动修复，形成闭环。

探索型 Agent — 保护主对话上下文

除了 review，Agent 还有另一个重要用途：把大量搜索和探索任务外包出去，不占用主对话的上下文窗口。

比如 /project-info all 需要扫描整个项目的窗口、组件、系统、实体配置。如果在主对话里做，几十个文件的内容会塞满上下文，后续对话质量下降。派给探索型 Agent，它在独立的上下文里扫描，只返回最终结果——主对话保持干净。

这对长对话尤其重要。游戏开发经常是连续几个小时的长会话，上下文管理直接影响 AI 后半程的表现。

Agent 设计技巧

技巧一：用更便宜的模型

不是每个 Agent 都需要最强的模型。我的 game-reviewer 用的是 sonnet（model: sonnet），比 opus 便宜很多，但对于按规则检查代码这类任务完全够用。只有需要深度推理的任务才用 opus。

技巧二：系统提示要具体

Agent 的系统提示就是它的「专业背景」。写得越具体，表现越稳定。不要写「请审查代码质量」这种模糊指令，要写「检查组件是否只存储数据、系统是否存储了持久状态、销毁时是否清理了监听」——具体到每一个检查项。

技巧三：定义输出格式

不定义输出格式，Agent 每次返回的结构都不一样，主对话的 AI 难以解析。我给 game-reviewer 定义了严格的 Markdown 格式（概览 → Critical → Important → Suggestion），每次输出结构一致。

踩坑经验

坑一：Agent 和主对话的规范不同步

Agent 的系统提示是独立的，它不会自动读取 CLAUDE.md 和 Rules。如果项目规范更新了（比如新增了一个 ECS 组件分类），必须同步更新 Agent 的系统提示，否则 review 结果会和最新规范矛盾。

坑二：Agent 返回太多内容

Agent 的返回会注入主对话的上下文。如果 Agent 返回了一份 500 行的审查报告，主对话的上下文会被大量占用。我的做法是在 Agent 系统提示里限制：「问题清单每个级别最多 5 条，通过的检查项只列关键项」。

坑三：自动触发频率太高

game-reviewer 配置了「写完 .ts 文件自动触发」，但如果 AI 连续编辑 10 个文件，会触发 10 次 review。实际上应该等一组编辑完成后统一 review 一次。这个目前靠主对话的 AI 自行判断「一批修改是否完成」，还不完美。

六层体系回顾

七篇文章写完了，回顾一下整套体系：

层级 定位 一句话总结
CLAUDE.md 项目说明书 告诉 AI 你的项目用什么、怎么组织
Rules 场景规范 写什么代码就自动加载什么规范
Skills 自动化流程 重复任务一句命令搞定
MCP API 知识库 AI 不认识的 API 随时查
Hooks 系统守卫 写完代码自动检查，兜底 AI 的疏忽
Agents 专属专家 需要分析判断的任务交给专家

这六层不是一天建起来的。我的建议还是那句话：从 CLAUDE.md 开始，遇到什么问题就加什么层。

最开始只写了 CLAUDE.md，发现规范太多装不下 → 拆出 Rules。发现创建窗口每次要解释 → 封装 Skills。发现 AI 猜 API 老猜错 → 建了 MCP。发现 AI 偶尔忘记规范 → 加了 Hooks。发现代码 review 需要专业判断 → 配了 Agent。

每一层都是被实际问题「逼出来」的，不是提前规划好的。这也是我想表达的核心观点：没有万能配置，只有适合你项目的配置。

最后

这套配置体系的本质，是把你作为「游戏开发者」的经验持续固化输入给 AI。你越了解自己的项目，配置就越精准，AI 的表现也越稳定。

鼓吹 AI 万能的文章不少，但 AI 终究是工具——工具好不好用，80% 取决于你怎么配它。

以上就是我目前在游戏项目里的全部配置实践，不一定是最优解，但确实是一线开发中实际跑通的方案。如果你也在游戏项目里用 AI 编程，不管是 Cocos、Unity 还是其他引擎，欢迎交流你的经验——说不定你踩过的坑能帮我省一天，我踩过的坑也能帮你少走一段弯路。