gepetto

gepetto skill 概览

gepetto 的作用

gepetto skill 是一套结构化的规划工作流，目的是在真正开始写代码之前，把一个模糊的功能想法整理成可执行度很高的实施包。它不会从一句简短提示直接跳到代码，而是先经过调研、澄清式提问、规格整合、实施规划、外部评审，以及按章节拆分的过程。

gepetto skill 最适合谁

如果你符合下面这些情况，这个 gepetto skill 会特别适合：

• 正在规划一个范围不清、复杂度不低的功能
• 需要同时覆盖 backend、frontend、infra 或 integrations
• 希望在实施前先尽量减少返工
• 使用 AI 的重点是 Requirements Planning，而不只是代码生成
• 愿意提供一个 markdown spec 文件，并回答后续澄清问题

如果你只是想要一个快速代码片段，或者改一个很小的单文件逻辑，那 gepetto 往往就偏重了。

用户真正要解决的问题

大多数用户并不是抽象地需要“更强的 AI 规划”。他们真正需要的是：把“做个 auth”“加 billing”“支持文件同步”这类模糊需求，转成一份能覆盖边界情况、依赖关系、发布风险和实施顺序的计划。gepetto 相比普通 prompt 的优势，恰恰就在这里。

gepetto 的差异化在哪里

gepetto 的主要区别，都是很实际的：

• 它要求提供 spec 文件，让整个流程有一个可持续引用的规划锚点
• 它会明确提出澄清问题，而不是默默假设缺失需求
• 它可以在敲定计划前先做 research
• 如果环境支持，它还包含使用其他 model CLI 的 external review 步骤
• 它输出的是按章节组织、便于执行的结果，而不是一篇很长的大而全说明文

这套组合让 gepetto skill 比普通“帮我写个计划”的 prompt 更偏向决策与落地。

安装前用户最关心什么

在决定采用 gepetto 之前，大多数用户最好先确认这四件事：

1. 你是否已经有一个 markdown spec 文件？ 这个 skill 会直接依赖它。
2. 你是否接受把文件写入某个 planning 目录？ gepetto 是面向文件输出的。
3. 你的环境能否支持完整工作流？ 某些步骤默认你能做 research，以及可选的 external review。
4. 你的任务是否足够复杂，值得走这套流程？ 功能越复杂，收益越明显。

如何使用 gepetto skill

在你的 skill 环境中安装 gepetto

如果你使用的是这套 toolkit 的标准安装方式，可以从仓库中添加这个 skill：

npx skills add softaworks/agent-toolkit --skill gepetto

然后在支持 slash-skill 调用的 agent 会话里使用它。该 skill 在仓库中的路径是：

skills/gepetto

如果你的环境采用的是另一套 skill 加载机制，就直接使用 repo 里的文件，并保持相同的调用约定即可。

先理解 gepetto 的必需输入契约

采用 gepetto 时，最关键的一点是：调用时必须传入一个 markdown spec 文件路径。这个 skill 会检查是否提供了以 .md 结尾的 @file 输入；如果没有，它会停止执行并要求你补上正确输入。

实际上的意思就是：不要只丢一句宽泛的聊天式需求就启动 gepetto。更推荐像这样开始：

/gepetto @planning/auth-spec.md

这个 spec 所在的父目录，会成为 gepetto 写入后续 .md 输出的 planning workspace。

你的 spec 文件应该包含什么

起始 spec 不需要写得完美，但输入质量越高，规划结果通常越好。一份合格的初始文件一般至少应包含：

• 功能目标或问题描述
• 用户类型与关键流程
• 已知约束
• 技术栈
• 现有系统背景
• 未知项或开放问题
• 成功标准
• 非目标范围

即使 spec 还比较粗，也可以用；但你的业务与运行上下文越具体，gepetto 就越不用花时间去补猜隐藏前提。

一个更好用的 gepetto spec 模板

为了更顺畅地使用 gepetto，你可以先在 spec 里放一些简短章节，比如：

• Goal: 完成后应该具备什么
• Users: 谁会与它交互
• Current system: 相关 services、repos 或 modules
• Constraints: deadline、compliance、performance、budget
• Interfaces: APIs、events、storage、third-party dependencies
• Risks/unknowns: 目前不确定的地方
• Definition of done: 什么程度才算计划可执行

通常这些内容，就足够让 gepetto 产出一版质量很高的初稿。

gepetto 工作流里会发生什么

从仓库里的实现线索来看，gepetto 的流程非常清晰：

1. 校验 spec 文件输入
2. 初始化规划会话
3. 判断是否需要 research
4. 执行 research 并整合结果
5. 通过聚焦问题采访用户
6. 写出汇总后的 implementation plan
7. 对计划执行 external review
8. 将工作拆成多个 implementation sections

因此，gepetto 特别适合那些隐藏边界条件多、架构权衡复杂的需求。

如何把模糊目标变成可用的 gepetto 调用

弱一些的起点：

Build authentication

更适合 gepetto 的起点：

Create email/password and Google OAuth login for our SaaS app. Stack: Next.js, Postgres, Stripe, existing RBAC. Need session handling, audit logging, admin user provisioning, password reset, account lockout, and migration plan from legacy auth. Must support SOC 2 audit needs. Unknown: whether to use our current session store or move to JWT.

为什么这种写法更有效：

• 它明确了 research 方向
• 它暴露了 integration points
• 它提前带出了合规和迁移问题
• 它能催生更有质量的 interview questions
• 它能减少空泛的规划废话

用于 Requirements Planning 的 gepetto 最佳工作流

如果你是把 gepetto for Requirements Planning 作为主要用途，通常最有效的流程是：

1. 先写一个粗糙但真实的 spec 文件
2. 在这个文件上运行 gepetto
3. 回答澄清问题时给出运营和业务细节，不要只给口号
4. 检查生成的计划是否遗漏业务规则
5. 把 section 输出直接作为 implementation units 或 tickets
6. 在需求出现重大变化后重新运行或继续补做

相比一次性要求它产出一份“大而全最终 spec”，这种方式通常有效得多。

优先阅读哪些仓库文件

如果你想在全面采用前先判断这个 skill 是否合适，建议按这个顺序读：

1. skills/gepetto/SKILL.md
2. skills/gepetto/README.md
3. skills/gepetto/references/research-protocol.md
4. skills/gepetto/references/interview-protocol.md
5. skills/gepetto/references/external-review.md
6. skills/gepetto/references/section-index.md
7. skills/gepetto/references/section-splitting.md

光看主 README 的快速浏览，远不如这条阅读路径更能帮你判断 gepetto 的真实行为方式。

输出文件是什么，为什么重要

gepetto 不只是一个对话式 prompt。它的设计目标，是把规划产物直接写入你指定的目录。仓库里显示的输出包括：

• research notes
• 主 implementation plan
• sections/index.md
• 各个独立的 section 文件

这点很重要，因为这意味着整个工作流是可恢复的，也比一次性聊天输出更容易交接给别人继续推进。

External review 很有价值，但在实际使用中是可选的

gepetto 最强的一点之一，就是 external review 这一层。参考文件显示，它希望通过 Gemini、Codex 这类其他 model CLI 来审查生成的计划。这能显著提升计划质量，比如更容易发现：

• security gaps
• edge cases
• performance concerns
• ambiguous requirements
• architectural footguns

但这也意味着，想把 gepetto 的价值吃满，你的环境配置会很关键。如果你没有这些外部工具，前面的规划流程依然值得用，只是这一层 review 可能需要你自己调整实现方式。

能明显提升首次运行质量的实用建议

下面这些细节，会明显影响你的 gepetto 结果：

• 如果已经有 codebase，就把现有模式或 file paths 一起写进去
• 说明预期规模、流量和故障处理方式
• 明确什么东西绝对不能改
• 列出任何合规、隐私或审计要求
• 回答 interview questions 时尽量具体，不要只说“按标准做”
• 在执行前先检查生成 sections 的依赖顺序

gepetto 的最佳状态，是尽早把模糊性暴露出来，而不是把它藏起来。

gepetto skill 常见问题

gepetto 比普通 planning prompt 更好吗？

对简单任务来说，不一定。对多步骤、多依赖的功能来说，gepetto 通常更强，因为它强制执行了一套规划流程：spec 校验、research、interview、synthesis、review 和 sectioning。普通 prompt 可能表面上更快，但也更容易漏掉隐藏前提。

gepetto 对新手友好吗？

是的，只要你能写一个基础的 markdown spec，并回答后续问题。你一开始不需要提供完美 spec。不过，如果是完全没有经验的新手，仍然可能需要有人帮忙判断生成出来的计划是否符合真实工程约束。

什么情况下不应该使用 gepetto skill？

以下场景建议跳过 gepetto：

• 任务非常小，且风险很低
• 你已经有经过批准的 implementation plan
• 你无法提供 spec 文件
• 你不希望输出落到文件里
• 当前环境无法支持你需要的那套工作流

gepetto 的流程开销是有意设计出来的，所以它并不适合一次性、随手做完就丢的任务。

gepetto 需要访问 codebase 吗？

不一定，但有会更好。即使只有一份偏产品视角的需求文档，这个 skill 仍然能工作。不过当它能结合真实 repo 或项目上下文去研究现有模式和架构时，价值会明显更高。

采用 gepetto 最大的阻碍是什么？

通常是输入质量和调用格式。很多用户会把 gepetto 当成一个自由聊天机器人来启动，但它不是。这个 skill 期望拿到的是一个 markdown spec 路径，以及一个可写入 planning 文件的目录。

gepetto 主要用于 Requirements Planning，还是 implementation？

它的核心优势是贴近 implementation 的 Requirements Planning。它既不只是做 product discovery，也不只是代码生成，而是处在中间这一层：把需求和约束转成开发者能真正执行、并且更少踩坑的计划。

如何改进 gepetto skill 的使用效果

先把 spec 写得更好，而不是写得更长

想提升 gepetto 输出质量，最有效的办法通常不是把 spec 写得更长，而是把信息密度写得更高。多加具体信息，而不是填充废话。最有帮助的通常是这些内容：

• 当前架构
• 受影响系统
• 预期规模
• security/compliance 要求
• migration 或 rollout 约束
• 你关心的 failure modes

一页纸但足够具体的 spec，通常胜过五页空泛的说明。

把 gepetto 无法自行推断的约束直接喂给它

gepetto 虽然会提澄清问题，但它并不能稳定地推断隐藏的业务规则。像下面这类限制，最好明确写出来：

• “Must preserve backward compatibility for existing API clients”
• “Admin actions need audit logs retained for 1 year”
• “No new infrastructure vendors this quarter”
• “Feature must degrade gracefully when provider X is down”

这些约束会显著提升计划的现实可行性。

在 interview 阶段给出更强的回答

interview protocol 是 gepetto 最有价值的部分之一，要认真对待。回答太弱，会得到泛泛而谈的计划；回答越精确，section 就越接近可直接执行。

不太有用的回答：

• “standard auth”
• “make it scalable”
• “just follow best practices”

更有用的回答：

• “session invalidation must be immediate after password reset”
• “org admins can invite users, but only owners can change billing”
• “we expect 50k monthly active users within 6 months”

检查计划是否缺少关键的运营细节

完成第一轮 gepetto 之后，重点看看计划里是否覆盖了这些内容：

• monitoring and alerting
• rollback 或 migration strategy
• data model changes
• permissions 和 abuse cases
• test strategy
• deployment sequencing
• documentation updates

当初始输入过于聚焦“功能本身”时，这些往往是最容易被漏掉的盲点。

把 section 文件当作执行单元来使用

sectioning system 是 gepetto 最实用的组成之一。为了让结果更好，你需要确保这些 section：

• 命名清晰
• 依赖关系明确
• 大小适合 implementation，而不只是适合写文档
• 在可能的情况下可以并行推进

如果某个 section 卡住了太多其他部分，或者把无关问题混在一起，那就在交给 coding agents 之前先拆开。

按你的真实工具链调整 external review

参考文档默认 external review 是通过 CLI 工具完成的。如果你的环境不一样，也应该尽量保留同样的 review 意图，即便实现方式不同。关键不在具体用哪个工具，而在于：在真正开始 implementation 之前，让生成出来的计划先接受一轮独立批评。

gepetto 使用中的常见失败模式

最常见的问题其实都很典型：

• 没有 .md spec 文件就直接启动
• 只提供一句口号级的需求
• interview 阶段跳过具体回答
• 把第一版计划当成最终版
• 忽略 section 之间的依赖关系
• 没有写明 repo 特定的约定

这些问题大多靠更好的前期设置就能修正，而不是靠调模型 temperature。

拿到第一轮 gepetto 输出后，应该如何继续迭代

一轮高质量的第二次迭代，通常会像这样：

1. 在计划里标出不清楚或不正确的假设
2. 把缺失的业务规则补回 spec
3. 重新运行或继续使用 gepetto
4. 对照真实 implementation 情况检查修订后的 sections
5. 到这一步，再把 sections 转成 tickets 或 coding tasks

真正让 gepetto 变得有价值的，往往就是这个循环：在正式开工前，把代价高昂的模糊性先消掉。

长期用好 gepetto 的最佳方式

不要只把 gepetto 用在一次性的灵感整理上。更好的方式，是把它当成中大型功能的可复用规划标准。团队通常会在这些方面获得最大收益：

• specs 放在哪里
• 一份 spec 至少要包含哪些信息
• review comments 如何回灌进计划
• section 文件如何映射到 implementation work

这样，gepetto 才会从一个“挺聪明的 prompt”，真正变成一套可靠的 planning workflow。