技能包

GAIA：面向 Claude Code 的规格先行开发骨架

最适合用 Claude Code 做正式软件开发、并希望提交与合并都有质量约束的开发者：GAIA 强制规格先行，为每次提交设置质量门禁，每次合并引入代码审计；使用前需要 Node.js >= 22.22.0，且官方要求用 npx 命令创建项目而不是克隆或 fork。

官方来源 · GAIA

安装

npx create-gaia@latest my-app

适合谁

GAIA 自述为 "A serious harness for Claude Code"：给 Claude Code 的一套严肃工程骨架。它把"先想清楚再动手"固化成流程——编码前先写规格（Specs before code），每次提交设质量门禁，每次合并引入 Code Audit Team 审计。它适合这样的开发者：

  • 用 Claude Code 做真实的软件开发，希望每笔改动先有规格依据、提交可验证、合并可审计，而不是一次对话就产出未经检查的代码。
  • 愿意接受流程约束：提交前要通过类型检查、lint、单元与 Storybook 测试、Playwright E2E 和开发服务器冒烟测试，全部通过才算过关。
  • 满足运行前提：Node.js >= 22.22.0。

以下情况不适合或需要先确认：

  • 不使用 Claude Code 的环境：官方只把它描述为 Claude Code 的骨架，能否用于其他 agent 未说明。
  • 只想快速生成脚本、不需要规格与测试流程的场景：它要求先写规格，前置成本更高。
  • 期望通用聊天或纯写作辅助的场景：官方对它的描述全部围绕开发流程约束，没有提及其他用途。
  • 除 Node.js >= 22.22.0 外，官方未列出其他环境限制，系统兼容性在确认前应视为未知。

3 分钟完成第一次尝试

推荐主路径只有一条：先用官方命令创建项目，再到 Claude Code 里触发规格撰写。

前提：本机已安装 Node.js >= 22.22.0，并可以使用 Claude Code。

安装：在终端执行

npx create-gaia@latest my-app

官方明确要求以这种方式开始项目，而不是克隆（clone）或 fork 仓库。命令里的 my-app 是新项目的名字，第一次尝试保持这个名字即可，避免与已有目录混淆。

触发任务：进入新建的 my-app 目录，在 Claude Code 中输入 /gaia-spec。官方描述该操作通过苏格拉底式提问（Socratic discovery）撰写一份不可变的 SPEC 工件。也就是说，它不会一上来就生成文档，而是围绕需求逐项追问，等你回答后再把结论收敛成规格。副作用与确认点：它会生成规格工件，且一经生成为不可变（immutable），因此回答提问时要把需求确认清楚再收尾；建议第一次就在这个全新项目里进行，不触及已有代码。

成功信号：提问结束后拿到生成的 SPEC 工件，说明规格撰写流程已经完成。如果中途看到的是一轮轮收敛式的追问而不是立刻产出全文，这正是该操作的设计——它靠提问澄清需求。

使用案例

案例一：新项目动工前固定需求。 场景：要启动一个新项目，担心口头需求在多轮对话中漂移，不同轮次得到的实现方向不一致。 发起：在 npx create-gaia@latest my-app 创建的项目里，向 Claude Code 发出 /gaia-spec。 过程与结果：agent 以苏格拉底式提问逐项澄清需求，最终产出不可变的 SPEC 工件；由于规格先行是这套骨架的工作方式，这份工件会成为后续写代码前的一致基准。工件不可变，生成前的提问环节就是唯一的确认点，回答前把关键决策想清楚。SPEC 工件的文件名与存放位置官方未写明，可确认的终点是"生成不可变工件"这一步。

案例二：提交一处小改动，体验提交前质量门禁。 场景：你在 GAIA 项目里修改了一处代码，准备提交。 发起：按日常流程执行一次提交。 过程与结果：提交前会运行质量门禁——类型检查（Typecheck）、lint、单元与 Storybook 测试、Playwright E2E、开发服务器冒烟测试——全部通过提交才能继续，任何一项未通过，提交都无法完成。建议选一处影响小的改动，便于观察门禁运行的全过程；门禁包含 E2E 与冒烟测试，会实际运行，第一次执行通常比没有门禁的提交更花时间，本地环境也需要能启动开发服务器。是否存在跳过门禁的方式，官方未说明。

使用边界

  • 运行环境：官方确认的要求只有 Node.js >= 22.22.0，其余系统层面的限制未给出，使用前请自行核实环境。
  • 客户端前提：GAIA 面向 Claude Code；能否配合其他 agent 使用，官方未说明。
  • 副作用与确认点：/gaia-spec 生成不可变的 SPEC 工件，生成前有提问确认环节；提交触发的门禁会实际运行测试、E2E 和开发服务器冒烟测试。
  • 门禁范围：官方列出的检查项目就是类型检查、lint、单元与 Storybook 测试、Playwright E2E 与开发服务器冒烟测试这些；除此之外是否还有其他检查未说明。
  • 沙箱限制：官方写明沙箱规则会阻止读取 .env 文件、密钥与证书文件、凭据命名文件（block reads of .env files, key and certificate files, credential-named files），用于减少 agent 接触敏感凭据的机会。
  • 合并约束：每次合并都有 Code Audit Team 审计；审计的具体产出形式与耗时官方未说明。
  • 尚未确认：除 /gaia-spec 外还有哪些操作、SPEC 的存储位置、有无图形界面、支持的语言范围，官方页面均未给出，请以项目内的实际说明为准。