Claude Code Game Studios `/onboard` 技能全解析：面向新成员的上下文感知项目引导及其测试规格设计

Claude Code Game Studios/onboard技能全解析：面向新成员的上下文感知项目引导及其测试规格设计

【免费下载链接】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

导读：/onboard是 Claude Code Game Studios（CCGS）框架中的一项实用工具类技能，用于为新加入项目的成员（或 Agent）生成一份结构化的项目引导文档。本文以 CCGS Skill Testing Framework 中的 /onboard 测试规格 为主体，对照实际技能实现与仓库内相关配置，完整梳理该技能的数据来源、行为规范、五个测试用例的设计思路，以及它在整个 CCGS 质量保障体系中的定位。读完本文，你将理解如何为团队新成员快速建立项目上下文认知，以及 CCGS 是如何用"静态断言 + 行为用例"双重机制对一项只读技能进行可自动化验证的。

一、技能定位：一次阅读项目状态、零文件写入的引导工具

/onboard的核心职责是：为一名新加入的团队成员生成一份贴合项目现状的引导摘要。它不属于创作型技能，不产出设计文档，也不触发评审门禁，而是纯信息型的上下文梳理工具。

从测试规格的定义看，该技能的行为基准是：

• 读取CLAUDE.md、technical-preferences.md、当前活跃 sprint 文件、最近的 git 提交记录，以及production/stage.txt（阶段标记文件）；
• 基于以上输入，产出一份结构化的引导文档；
• 可选地接受一个角色参数（如/onboard artist），将引导内容定向到某一专业方向；
• 当项目处于早期阶段或尚未配置时，输出会自适应地反映"已知信息很少"这一现实；
• 最终结论始终是ONBOARDING COMPLETE—— 该技能是纯信息性的，不涉及成败判定。

在技能参考文档中，/onboard被归入 "Creative & Content"（创意与内容）类别，定位为"为新的贡献者或 Agent 生成贴合上下文的引导文档"。而在实际技能实现的 frontmatter 中，它的元数据为：

name: onboard description: "Generates a contextual onboarding document for a new contributor or agent joining the project. Summarizes project state, architecture, conventions, and current priorities relevant to the specified role or area." argument-hint: "[role|area]" user-invocable: true allowed-tools: Read, Glob, Grep, Write

这里有一处值得注意的差异：测试规格声称该技能是"Haiku 模型、纯只读、零文件写入、结论固定为 ONBOARDING COMPLETE"，而实际 SKILL.md 的实现中allowed-tools包含Write，并且在 Phase 4 会征询用户"May I write this to production/onboarding/..."再落盘。CCGS Skill Testing Framework 的 CLAUDE.md 中有一句重要的说明："Specs in this folder describe current behavior, not ideal behavior. They were written by reading the skills, so they may encode bugs."（规格描述的是当前行为而非理想行为，写规格时可能把技能的 bug 一并编码进去）。因此，上述差异应被理解为：测试规格代表了一种"只读引导"的理想设计约束，而实际实现沿用了创作型技能的"May I write"协作协议。阅读与测试时，应当以 .claude/skills/onboard/SKILL.md 的真实行为为准。

二、数据源与"先读后写"的信息边界

/onboard的输出质量完全取决于它读取了哪些文件。测试规格明确列出其上下文来源，这些文件在仓库中均有对应物：

其中technical-preferences.md是由/setup-engine技能写入的（该文件头部注释明确写着 "Populated by /setup-engine"），仓库自带的模板中所有字段均为[TO BE CONFIGURED]占位符，包括：

• Engine & Language：引擎、语言、渲染、物理
• Input & Platform：目标平台、输入方式、主输入、手柄/触屏支持
• Naming Conventions：类、变量、信号/事件、文件、场景/Prefab、常量的命名规范
• Performance Budgets：目标帧率、帧预算、Draw Calls、内存上限
• Testing：测试框架、最低覆盖率、必测内容
• Forbidden Patterns与Allowed Libraries / Addons（初始为空，随架构决策追加）
• Engine Specialists及文件扩展名到专家的路由表

/onboard读取该文件后，就能在引导文档的 "Tech Stack" 一节中准确说出项目用了哪个引擎、哪门语言。而[TO BE CONFIGURED]占位符本身，就是"项目尚未配置"的最强信号——这正是测试用例 Case 2 的判定依据。

从实际实现看，.claude/skills/onboard/SKILL.md 的流程比规格更细：

• Phase 1（加载项目上下文）：读CLAUDE.md；若指定了角色，则读取.claude/agents/下对应的 Agent 定义文件；
• Phase 2（扫描相关领域）：按角色定向扫描——程序员扫src/、设计师扫design/、叙事扫design/narrative/、QA 扫tests/、制作扫production/，并读取 git log 了解近期动态；
• Phase 3（生成引导文档）：按固定模板输出，见下文；
• Phase 4（保存文档）：先向用户展示，再以 "May I write this toproduction/onboarding/onboard-[role]-[date].md?" 征求同意后写入；
• Phase 5（后续步骤）：给出COMPLETE结论并建议下一步技能。

需要指出的是，production/stage.txt、technical-preferences.md中的引擎配置、production/sprints/sprint-005.md等，都是测试用例中假设的 fixture 状态。当前仓库的 production/ 目录下只有session-state/，并未包含这些运行期文件——它们由/start、/setup-engine、/sprint-plan等技能在实际使用中生成。文章读者在自己的 CCGS 项目中运行/onboard时，这些文件才会出现在磁盘上。

三、静态断言（Structural Checks）：无需 fixture 的结构合规验证

测试规格将/onboard的静态检查列为五项，由/skill-test static自动验证，不需要任何测试 fixture：

• frontmatter 包含必需字段：name、description、argument-hint、user-invocable、allowed-tools
• 包含 ≥2 个阶段标题（phase headings）
• 包含结论关键词：ONBOARDING COMPLETE
• 不含 "May I write" 措辞（技能被设计为只读）
• 末尾包含指向相关后续技能的交接建议

对照技能测试规格模板中的通用静态断言（frontmatter 五字段、2+ 阶段标题、至少一个 verdict 关键词、含 Write 时须有 "May I write"、末尾有交接段），可以看出/onboard规格的第三、四条是其特化变体：它要求 verdict 必须是ONBOARDING COMPLETE，且禁止出现 "May I write" 语言——这从规范层面锁死了"纯信息性、零写入"的设计意图。

这里再次出现规格与实现的分歧：实际 SKILL.md 的 frontmatter 声明了Write工具，Phase 4 也确实包含 "May I write" 询问。因此严格按规格跑/skill-test static onboard时，"Does NOT contain 'May I write'" 与 "allowed-tools 无 Write" 两项理论上会暴露这一偏差——这正是 CCGS 测试框架存在的意义：让规格与实现之间的漂移变得可见、可修。按照 CCGS Skill Testing Framework 的 CLAUDE.md 的流程，遇到此类失败时应先修正技能本身，再同步更新规格。

四、Director Gate 检查：为什么引导类技能不需要门禁

测试规格在 "Director Gate Checks" 一节明确写：

None./onboardis a read-only orientation skill. No director gates apply.

这符合 CCGS 的门禁设计哲学。在 quality-rubric.md 中，utility分类的评判标准 U1/U2 是这样定义的：

• U1：通过全部 7 项静态检查（/skill-test static [name]返回 COMPLIANT 且 0 FAIL）
• U2：若技能会触发 director gate，则必须正确读取 review-mode 并应用 full/lean/solo 逻辑

/onboard属于"不会触发 gate"的那类 utility 技能，因此只需满足 U1。作为对照，gate-check、sprint-plan等技能在full模式下会触发CD-PHASE-GATE、PR-SPRINT等导演门禁，而/onboard从设计上就被排除在外——它只是把现状讲清楚，既不批准也不拦截任何开发阶段，自然无需导演介入。这也从侧面印证了 CCGS 的"门禁成本只花在真正影响项目走向的动作上"这一原则。

五、行为测试用例全解读（规格核心）

测试规格为/onboard设计了五个行为用例，覆盖"配置完备、全新空项目、核心文件缺失、角色定制、门禁豁免"五类场景。以下逐一解读其意图与断言要点。

Case 1：Happy Path —— 处于 Production 阶段且有活跃冲刺的已配置项目

Fixture（假设的项目状态）：

• production/stage.txt内容为Production
• technical-preferences.md已填入引擎、语言、专家信息
• production/sprints/sprint-005.md存在且包含进行中的 stories
• git log 中有最近 5 条提交

期望行为：技能读取 stage.txt、technical-preferences.md、活跃冲刺与 git log，产出一份包含Project Overview、Tech Stack、Current Stage、Active Sprint Summary、Recent Activity五个板块的引导摘要，使用标题与列表保持可读性，并根据 Production 阶段推荐合适的下一步技能（如/sprint-status、/dev-story），最后给出ONBOARDING COMPLETE结论。

关键断言：

• 输出包含 stage.txt 中的阶段名；
• 输出包含 technical-preferences.md 中的引擎与语言；
• 活跃冲刺的 stories 被逐条总结（而非只出现冲刺文件名）；
• 包含近期提交的上下文；
• verdict 为ONBOARDING COMPLETE；
• 没有任何文件被写入。

这个用例定义了/onboard的"信息下限"：不是复述文件名，而是消化内容。这也与规格 "Protocol Compliance" 中"输出前读取所有源文件，不臆造项目状态"的要求一一对应。

Case 2：Fresh Project —— 未配置引擎、无冲刺，推荐/start

Fixture：

• technical-preferences.md全部为[TO BE CONFIGURED]占位符
• 无production/stage.txt、无 sprint 文件、CLAUDE.md无额外覆盖

期望行为：技能检测到未配置状态，产出一份极简摘要并明确提示"This project has not been configured yet"，接着说明引导工作流/start→/setup-engine→/brainstorm，并推荐立即执行/start。verdict 仍为ONBOARDING COMPLETE——信息性结论，不是失败。

关键断言：

• 输出明确提到项目尚未配置；
• /start被推荐为下一步；
• 技能不报错，优雅处理空项目状态；
• verdict 依然是ONBOARDING COMPLETE。

这个用例的关键词是"优雅降级"。/start正是 CCGS 的官方入口技能——.claude/skills/start/SKILL.md 会在 Phase 1 静默探测引擎配置（读technical-preferences.md的 Engine 字段是否含[TO BE CONFIGURED]）、游戏概念、源码、原型、设计文档与生产产物，然后通过 AskUserQuestion 让用户选择起点并路由到对应工作流。/onboard推荐/start作为新项目第一步，与/start的"第一次使用引导"定位形成闭环。

Case 3：No CLAUDE.md Found —— 报错并给出修复路径

Fixture：CLAUDE.md不存在（被删除或从未创建），其余文件可有可无。

期望行为：

1. 技能读取 CLAUDE.md 失败；
2. 输出错误信息："CLAUDE.md not found — cannot generate onboarding summary"；
3. 给出修复建议："Run/startto initialize the project configuration"；
4. 不生成任何部分摘要。

关键断言：

• 错误消息明确指出缺失文件是 CLAUDE.md；
• 修复步骤（/start）被显式命名；
• 根配置缺失时不输出残缺内容；
• verdict 为ONBOARDING COMPLETE（带错误上下文的正常结束，而非崩溃）。

这个用例确立了一个重要边界：根配置文件是引导摘要的硬前置依赖。宁可明确报错并提供修复路径，也不输出一份缺胳膊少腿的"半引导"，防止新成员被不完整信息误导。规格的 Coverage Notes 还补充说明：technical-preferences.md整体缺失（而非仅含占位符）的情况未单独建用例，其行为沿用 Case 3 的优雅报错模式。

Case 4：Role-Specific Onboarding —— 用户指定 "artist" 角色

Fixture：已配置的 Production 项目；design/下存在art-bible.md；活跃冲刺包含动画、VFX 等视觉类 stories。

期望行为：

1. 读取全部标准文件 + 美术相关文档（art bible、资产规格）；
2. 摘要针对美术角色定制：art bible 概览、资产管线、当前冲刺中的视觉类 stories；
3. 弱化技术架构细节（代码结构、ADR）；
4. 突出美术/音频相关的专家 Agent；
5. verdict 为ONBOARDING COMPLETE。

关键断言：

• 输出承认角色参数（如 "Onboarding for: Artist"）；
• 若 art-bible 存在则包含其摘要；
• 展示当前冲刺中的视觉类 stories；
• 技术实现细节不作为重点；
• verdict 为ONBOARDING COMPLETE。

这一用例验证的是角色参数的裁剪能力。CCGS 拥有 49 个 Agent，其中与美术直接相关的不止 art-director，还有 technical-artist、world-builder 等。规格的 Coverage Notes 明确：除 "artist" 外的其他角色（programmer、designer、producer 等）遵循与 Case 4 相同的定制模式，不单独建用例。这保证了测试矩阵的收敛——一种裁剪逻辑，验证一次即可。

Case 5：Director Gate Check —— 全流程无门禁、无写入

Fixture：任意已配置的项目状态。

期望行为：技能完成完整引导摘要；全程不派生任何导演 Agent；输出中不出现任何 gate ID；不出现 "May I write" 提示。

关键断言：

• 不触发任何 director gate；
• 不调用任何写工具；
• 不出现 gate 跳过类消息；
• verdict 为ONBOARDING COMPLETE，且全程无门禁检查。

这个用例把规格中"Director Gate Checks: None"落实为可执行断言，防止未来某次修改给/onboard悄悄加上门禁逻辑而不自知。

六、Protocol Compliance：只读技能的协议红线

规格在协议合规一节列出了四项硬性要求：

• 输出前读取全部源文件（不臆造项目状态）
• 输出适配项目阶段（Production 与 Concept 的引导不同）
• 尊重角色参数（若提供）
• 不写任何文件
• 所有路径都以ONBOARDING COMPLETE结论收尾

对照 templates/skill-test-spec.md 的通用协议（"May I write" 前置、先展示草稿再请求批准、结尾给出下一步建议、未经批准不自动建文件），/onboard规格的协议清单是一份特化的"减法"清单：它把通用协议中关于写入的部分整体移除，同时追加了"读取完整性"与"阶段适配性"两条信息质量约束。从源码结构看，实际实现选择了保留写入能力（Phase 4 的 "May I write" 落盘到production/onboarding/），这属于实现与规格之间的设计分歧，测试框架的价值正在于暴露并推动解决这类分歧。

七、Coverage Notes：已知的测试盲区

规格末尾诚实地列出了三个未覆盖场景，这本身就是质量工程中"显式声明边界"的良好实践：

1. technical-preferences.md整体缺失（区别于仅含占位符）未被单独测试——行为沿用 Case 3 的优雅报错模式；
2. Git 历史读取被假设为可用——离线或无 git 的场景未测试；
3. artist 之外的角色（programmer、designer、producer 等）遵循 Case 4 的同一套裁剪模式，未逐一测试。

这些盲区意味着：/onboard的测试矩阵在"输入完整性"和"角色多样性"两个维度上依赖模式复用而非穷举，这是测试成本与覆盖收益之间的理性取舍。

八、在 CCGS 测试体系中的坐标

/onboard的规格文件位于 CCGS Skill Testing Framework/skills/utility/onboard.md，它在整个测试框架中的坐标如下：

• catalog.yaml 登记：该规格在 catalog.yaml 中有条目，spec:字段指向本规格文件——catalog 是"哪个技能对应哪份规格"的权威索引；
• 分类：utility类别，评判标准见 quality-rubric.md 的 U1/U2 两条指标；
• 测试命令：/skill-test static onboard（7 项结构检查）、/skill-test spec onboard（按本规格逐用例评估）、/skill-test category onboard（对照 utility 分类指标）、/skill-test audit（整体覆盖视图）；
• 改进回路：若onboard未通过，可用/skill-improve onboard走"测试 → 诊断 → 提议修复 → 重写 → 重测 → 保留或回退"的闭环。

CCGS 的核心主张是"72 个技能、49 个 Agent 组成的完整工作室协作系统"。而 CCGS Skill Testing Framework 的 README 明确指出：这套框架测试的是技能与 Agent 本身，而非用它们开发的游戏。/onboard规格正是这一理念的缩影——即便是最不起眼的只读引导工具，也拥有一份包含静态断言、五个行为用例、协议合规清单与已知盲区说明的完整测试规格。这种"为流程本身建立质量保障"的做法，让整个工作室框架的每个零件都可验证、可回归、可持续演进。

九、如何实际使用与验证/onboard

对于 CCGS 使用者，/onboard的实战路径如下：

1. 新成员/新 Agent 加入时，在 Claude Code 中直接输入/onboard（全项目通用引导）或/onboard artist、/onboard programmer（角色定向引导）；
2. 技能会读取CLAUDE.md、.claude/docs/technical-preferences.md、活跃冲刺与 git log，输出结构化的引导文档——实际模板包含 Project Summary、Your Role、Project Architecture（含 Key Directories 与 Key Files 表格）、Current Standards and Conventions、Current State of Your Area、Current Sprint Context、Key Dependencies、Common Pitfalls、First Tasks、Questions to Ask 等完整板块；
3. 若项目尚未配置（technical-preferences.md全为占位符），引导会退化为一句话提示并推荐/start→/setup-engine→/brainstorm的初始化路径；
4. 若CLAUDE.md缺失，则明确报错并指引运行/start初始化；
5. 引导结束后，可继续运行/sprint-status向新成员展示当前进度，或/help提供后续指引。

对框架维护者而言，规格文档是验证脚本：/skill-test spec onboard会按五个用例逐一评估行为，/skill-test static onboard会检查结构合规。由于规格文件与实现文件分处两处（规格在CCGS Skill Testing Framework/skills/utility/，实现在.claude/skills/onboard/），且规格明确声明"描述的是当前行为而非理想行为"，任何规格与实现的偏离都应触发"先修技能、再同步规格"的处理流程，而不是反过来将规格当作不可变教条。

关联文档：CCGS Skill Testing Framework/skills/utility/onboard.md · 实现：.claude/skills/onboard/SKILL.md · 测试框架入口：CCGS Skill Testing Framework/README.md

【免费下载链接】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