gepetto

gepetto skill の概要

gepetto ができること

gepetto skill は、ざっくりした機能アイデアを、実装に着手する前の詳細な実装パッケージへ落とし込むための、構造化された計画ワークフローです。短いプロンプトからいきなりコードを書くのではなく、gepetto は調査、要件を詰めるためのヒアリング質問、仕様の統合、実装計画、外部レビュー、そしてセクション単位の分解まで、順を追って進めます。

gepetto が向いているユーザー

この gepetto skill が特にフィットするのは、次のようなケースです。

• スコープがまだ曖昧な、そこそこ複雑な機能を計画している
• backend、frontend、infra、integrations をまたいで作業する
• 実装前に手戻りを減らしたい
• AI を単なるコード生成ではなく Requirements Planning に使いたい
• markdown の spec file を用意し、追加の確認質問にも答えられる

逆に、ちょっとしたコード断片だけ欲しい場合や、1 ファイルだけの小さな修正なら、gepetto はやや重めです。

実際に解決したい仕事

多くのユーザーが欲しいのは、抽象的な意味での「もっと AI っぽい計画」ではありません。必要なのは、「build auth」「add billing」「support file sync」といった曖昧な依頼を、エッジケース、依存関係、段階的 rollout の懸念、実装順序まで含んだ計画に変換する手段です。そうした場面で、gepetto は汎用的なプロンプトより強みがあります。

gepetto が他と違う点

gepetto の差別化ポイントは、実務面ではっきりしています。

• spec file を必須にすることで、計画の基点が一時的な会話ではなく永続的に残る
• 要件が足りない場合に黙って補完せず、明示的に確認質問を返す
• 計画を固める前に調査を挟める
• 利用可能であれば、他の model CLI を使った external review を含められる
• 長い文章 1 本ではなく、実行に回しやすいセクション化された出力を作る

この組み合わせによって、gepetto skill は単なる「計画を書いて」で終わるプロンプトよりも、意思決定に使いやすい設計になっています。

インストール前に確認したいこと

gepetto を導入する前に、まず次の 4 点を確認するとよいです。

1. markdown spec file を用意できるか？ この skill はそれを前提にしています。
2. 計画用ディレクトリにファイルを書き出す運用で問題ないか？ gepetto は file-output 前提です。
3. 利用環境がワークフロー全体を支えられるか？ 手順の一部では調査や任意の external review tooling を想定しています。
4. 対象タスクが、このプロセスに見合うだけ複雑か？ 効果は機能の複雑さが増すほど大きくなります。

gepetto skill の使い方

skill 環境に gepetto をインストールする

toolkit の一般的な install パターンを使うなら、repository から skill を追加します。

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

その後、slash-skill 呼び出しに対応した agent session から起動します。repository path は次のとおりです。

skills/gepetto

利用環境で別の skill-loading mechanism を使っている場合は、repo 内のファイルを直接使い、同じ invocation contract を再現してください。

必須の input contract を理解する

導入時に最も重要なのは、gepetto は起動時に markdown spec file path を要求することです。skill は .md で終わる @file input を確認し、見つからなければそこで停止して、正しい入力を求めます。

実務上の意味としては、ふわっとした chat 依頼だけで gepetto を始めないことです。たとえば次のように開始します。

/gepetto @planning/auth-spec.md

この spec の親ディレクトリが planning workspace になり、gepetto はそこへ追加の .md 出力を書き込みます。

spec file に入れておきたい内容

最初の spec が完璧である必要はありません。ただし、入力の質が高いほど、gepetto の計画結果は明らかに良くなります。良い初期ファイルには、通常次のような内容が入ります。

• 機能の概要、または解決したい問題
• ユーザー種別と主要なワークフロー
• 既知の制約
• technology stack
• 既存システムの文脈
• 未確定事項や open questions
• 成功条件
• non-goals

曖昧な spec でも受け付けられますが、運用上の前提が具体的であるほど、gepetto が欠落した前提を埋め直す時間は減ります。

gepetto 向けの強い spec template

gepetto をよりうまく使うには、spec に次のような短いセクションを最初から入れておくのがおすすめです。

• Goal: 完了時に何が実現しているべきか
• Users: 誰がそれを使うのか
• Current system: 関連する services、repos、modules
• Constraints: 納期、compliance、performance、budget
• Interfaces: APIs、events、storage、third-party dependencies
• Risks/unknowns: まだ不確かな点
• Definition of done: 何をもって実行可能な計画とみなすか

たいていは、これだけで質の高い first pass が得られます。

gepetto ワークフローで実際に起きること

repository の内容を見る限り、gepetto は明確な流れで進みます。

1. spec file input を検証する
2. planning session をセットアップする
3. 調査が必要かどうかを判断する
4. 調査を実行し、結果を統合する
5. 焦点の合った質問でユーザーにヒアリングする
6. 統合された implementation plan を書く
7. その plan に external review をかける
8. 実装作業を implementation sections に分割する

このため gepetto は、隠れたエッジケースやアーキテクチャ上のトレードオフを含みやすい要件に特に向いています。

粗い目標を使える invocation に変える方法

弱い出発点:

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.

これがうまく機能する理由:

• 調査対象が明確になる
• integration points が表に出る
• compliance や migration の懸念が見える
• ヒアリング質問の精度が上がる
• 中身の薄い generic な計画を減らせる

Requirements Planning での gepetto の最適な進め方

gepetto for Requirements Planning を使うなら、基本の流れは次の形が最も実用的です。

1. ラフでも実態のある spec file を書く
2. その file に対して gepetto を実行する
3. 確認質問にはスローガンではなく運用の実態で答える
4. 生成された plan を見て、抜けている business rules を確認する
5. section 出力を implementation unit や ticket として使う
6. 要件が大きく変わったら rerun または resume する

一度で巨大な最終 spec を作らせようとするより、こちらのほうがはるかに効果的です。

最初に読むべき repository files

本格導入の前に 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

この順で読むと、main README をざっと眺めるだけよりも、実際の挙動がかなりよく見えてきます。

output files と、それが重要な理由

gepetto は単なる conversational prompt ではありません。選んだ directory に planning artifacts を書き出す前提で設計されています。repo から読み取れる出力には、たとえば次のようなものがあります。

• research notes
• main implementation plan
• sections/index.md
• 個別の section files

ここが重要なのは、workflow を途中から再開しやすく、また一時的な chat 出力よりも引き継ぎしやすいからです。

external review は実用上かなり有効だが必須ではない

gepetto の特に優れた発想の 1 つが external review です。references を見ると、生成した plan を Gemini や Codex など、他の model CLI でレビューすることを想定しています。これにより、次のような論点が表面化しやすくなり、plan の質が実際に上がる可能性があります。

• security の抜け
• edge cases
• performance 上の懸念
• 曖昧な requirements
• architectural footguns

ただしそのぶん、gepetto をフルに活かせるかは環境依存でもあります。そうした外部ツールがなくても planning workflow 自体は有用ですが、この review layer は別の形に調整が必要になるかもしれません。

初回実行の質を上げる実践的なコツ

いくつかのポイントだけで、gepetto の結果はかなり変わります。

• 既存 codebase があるなら、既存パターンや file paths を含める
• 想定 scale、traffic、failure handling を書く
• 変えてはいけないものを明記する
• compliance、privacy、audit の要件を列挙する
• interview の質問には「whatever is standard」ではなく具体的に答える
• 実行前に、生成された sections の dependency order を確認する

gepetto は、曖昧さを隠すより早い段階で露出させたほうが、いちばん力を発揮します。

gepetto skill FAQ

gepetto は普通の planning prompt より優れている？

単純な作業なら、必ずしもそうとは限りません。ただ、複数段階にまたがる機能では、gepetto のほうが強いことが多いです。理由は、spec validation、research、interview、synthesis、review、sectioning という planning process を強制できるからです。普通の prompt のほうが速く感じることはありますが、そのぶん見えない前提を飛ばしやすくなります。

gepetto は初心者でも使いやすい？

はい。基本的な markdown spec を書けて、follow-up questions に答えられるなら使えます。最初から完璧な spec は不要です。ただし、完成した plan が実際の engineering constraints に合っているかを判断する点では、完全な初心者にはまだ補助が必要なことがあります。

gepetto skill を使わないほうがいいのはいつ？

次のような場合は gepetto を見送るのが適切です。

• タスクが小さく、リスクも低い
• すでに承認済みの implementation plan がある
• spec file を用意できない
• file-based outputs を使いたくない
• 必要な workflow を環境が支えられない

このプロセスのオーバーヘッドは意図的なものなので、使い捨てタスクには向きません。

gepetto は codebase access を必要とする？

必須ではありませんが、あると有利です。product-style の requirements document だけでも skill は機能します。ただし、実在する repo や project context の中で既存パターンや architecture を調査できると、価値はかなり高まります。

導入時の最大のつまずきポイントは？

多くの場合、input quality と invocation format です。gepetto を freeform chatbot のように始めようとしてしまうユーザーは少なくありません。しかし、そういう使い方の skill ではありません。gepetto は markdown spec path と、planning files を書き込める directory を前提にしています。

gepetto は Requirements Planning 向け？ それとも implementation 向け？

中核の強みは、implementation に近い Requirements Planning にあります。単なる product discovery でもなく、単なる code generation でもありません。その中間で、requirements と constraints を、開発者がより少ない想定漏れで実行できる plan に変換するのが役割です。

gepetto skill を改善する方法

長い spec より、良い spec から始める

gepetto の出力を改善するいちばんの方法は、入力 spec の情報密度を上げることです。文章を水増しするのではなく、具体性を足してください。特に効くのは次の情報です。

• current architecture
• affected systems
• expected scale
• security/compliance needs
• migration や rollout の制約
• 気にしている failure modes

曖昧な 5 ページより、具体的な 1 ページの spec のほうがたいてい優秀です。

gepetto が推測できない制約を先に渡す

gepetto は確認質問を返せますが、隠れた business rules を確実に推測できるわけではありません。たとえば次のような条件は明示してください。

• “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”

こうした制約があるだけで、plan の現実味は大きく上がります。

interview step では、より強い回答を返す

interview protocol は、gepetto の中でも特に価値の高い部分です。ここは本気で扱うべきです。弱い回答からは generic な計画しか出ませんが、精度の高い回答を返せば execution-ready な sections になります。

あまり役に立たない例:

• “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”

plan に運用面の詳細が抜けていないか確認する

gepetto の first pass のあと、plan に次の観点が入っているかを確認してください。

• monitoring and alerting
• rollback または migration strategy
• data model changes
• permissions と abuse cases
• test strategy
• deployment sequencing
• documentation updates

最初のプロンプトが feature 中心だと、こうした点は抜けやすいです。

section files を execution units として使う

sectioning system は、gepetto の中でも特に実践的な部分です。結果を良くするには、sections が次の状態になっているかを確認してください。

• 名前が明確である
• dependency-aware である
• documentation 用ではなく implementation 向けの粒度になっている
• 可能なら parallelize しやすい

1 つの section が多くをブロックしたり、無関係な関心事を混在させたりしているなら、coding agents に渡す前に分割したほうがよいです。

external review は実際の toolchain に合わせて調整する

references では CLI tools を使った external review を想定しています。手元の構成が違う場合でも、仕組みが変わるだけで review の意図は維持してください。重要なのは特定の tool そのものではなく、実装を始める前に、生成された plan に独立した批判を入れることです。

gepetto 利用で起きやすい失敗パターン

よくある問題は、だいたい予測できます。

• .md spec file なしで始める
• スローガン程度の feature request しか渡さない
• interview phase で具体的に答えない
• 最初の plan draft を最終版として扱う
• section dependencies を無視する
• repo 固有の conventions を省く

これらの多くは、model temperature ではなく setup を改善すれば直せます。

最初の gepetto output のあと、どう反復するか

良い second pass は、通常次の流れになります。

1. plan の中で不明瞭な前提や誤った前提に印を付ける
2. 抜けていた business rules を spec に追記する
3. gepetto を rerun または resume する
4. 修正版の sections を実装の現実と照らし合わせる
5. その後で初めて sections を tickets や coding tasks に変換する

gepetto guide が本当に役立つのは、このループです。build work を始める前に、高コストな曖昧さを減らせます。

gepetto から長期的な価値を引き出す最善の方法

gepetto を一発限りの ideation 用としてだけ使わないでください。中規模〜大規模機能に対する、再現可能な planning standard として使うのが最も効果的です。チームで次の点を標準化すると、価値が最大化します。

• specs をどこに置くか
• spec に最低限必要な情報は何か
• review comments をどう反映するか
• section files を implementation work にどう対応付けるか

そうすることで、gepetto は「気の利いた prompt」ではなく、信頼して回せる planning workflow になります。