gepetto

gepetto skill 概覽

gepetto 的用途

gepetto skill 是一套結構化的規劃工作流程，目的是在真正開始寫程式前，把一個模糊的功能想法整理成可執行的實作套件。它不是讓你從一段簡短提示直接跳到程式碼，而是會依序經過研究、釐清問題訪談、規格整合、實作規劃、外部審查，以及按章節拆分輸出。

哪些人最適合使用 gepetto

如果你符合以下情況，這個 gepetto skill 會特別適合你：

• 正在規劃一個不算簡單、範圍也還不明確的功能
• 需要跨 backend、frontend、infra 或各種 integrations 協作
• 想在實作前先降低返工成本
• 使用 AI 的重點是 Requirements Planning，不只是產生程式碼
• 願意提供一份 markdown spec 檔，並回答後續釐清問題

如果你只是想要一小段程式碼，或是改一個很小、只碰到單一檔案的變更，那 gepetto 多半比實際需要來得重。

真正要解決的工作問題

大多數使用者其實不是抽象地需要「更多 AI 規劃」。他們真正需要的是：把像「做登入驗證」、「加上 billing」、「支援檔案同步」這類模糊需求，轉成一份有把邊界情況、相依性、上線考量與實作順序都納入的計畫。這正是 gepetto 比一般泛用 prompt 更有優勢的地方。

gepetto 有什麼不同

gepetto 的主要差異點都很實際：

• 它要求先提供 spec file，讓整個流程有一個可持續追蹤的規劃錨點
• 它會明確提出釐清問題，而不是默默假設缺漏需求
• 它可以在定稿前先做研究
• 若環境允許，它包含使用其他 model CLI 的 external review 步驟
• 它輸出的是可拿來執行的分段結果，而不是只有一篇很長的說明文

這樣的組合，讓 gepetto skill 比一般「幫我寫份計畫」的 prompt 更偏向決策與落地。

安裝前使用者最在意的事

在採用 gepetto 前，多數人應該先確認四件事：

1. 你有 markdown spec file 嗎？ 這個 skill 預設會要求它。
2. 你希望規劃檔寫入某個 planning directory 嗎？ gepetto 是以檔案輸出為核心。
3. 你的環境能支援完整流程嗎？ 有些步驟預設會用到研究與可選的 external review 工具。
4. 你的任務夠複雜，值得走這套流程嗎？ 功能越複雜，回報越明顯。

如何使用 gepetto skill

在你的 skill 環境中安裝 gepetto

如果你使用 toolkit 的安裝模式，可以從 repository 加入這個 skill：

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

接著在支援 slash-skill 用法的 agent session 中呼叫它。對應的 repository 路徑是：

skills/gepetto

如果你的環境採用不同的 skill 載入方式，就直接使用 repo 裡的檔案，並維持相同的 invocation contract。

先理解必須遵守的輸入格式

採用 gepetto 時最重要的一點是：呼叫時必須提供 markdown spec file path。這個 skill 會檢查是否有一個以 .md 結尾的 @file 輸入；如果沒有，它就會中止並要求你改用正確格式。

實務上的意思是：不要只用一句鬆散的聊天需求就啟動 gepetto。請像這樣開始：

/gepetto @planning/auth-spec.md

該 spec 所在的上層目錄，會成為 gepetto 寫入其他 .md 輸出的 planning workspace。

你的 spec file 應該包含什麼

起始 spec 不必完美，但輸入越扎實，gepetto 產出的規劃品質通常越高。一份好的初始檔通常會包含：

• 功能或問題陳述
• 使用者類型與關鍵流程
• 已知限制
• 技術堆疊
• 既有系統脈絡
• 未知事項或待釐清問題
• 成功標準
• 非目標

即使 spec 還很粗略也可以，但 operational context 越具體，gepetto 就越不需要花時間補猜那些缺漏前提。

一個好用的 gepetto spec 範本

如果想讓 gepetto 更容易產生高品質結果，可以先在 spec 中放入這類簡短段落：

• Goal: 完成後應該具備什麼
• Users: 誰會與它互動
• Current system: 相關服務、repos 或 modules
• Constraints: 時程、合規、效能、預算
• Interfaces: APIs、events、storage、第三方依賴
• Risks/unknowns: 目前還不確定的地方
• Definition of done: 什麼條件代表這份計畫可執行

通常這樣就足以讓第一輪輸出達到不錯的品質。

gepetto 工作流程中會發生什麼

從 repository 內容來看，gepetto 的流程相當清楚，會依序進行：

1. 驗證 spec file 輸入
2. 建立 planning session
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.

為什麼這樣更有效：

• 它提供了可研究的目標
• 它把整合點直接攤開
• 它揭露了合規與 migration 顧慮
• 它能引出更有價值的訪談問題
• 它能減少空泛的規劃廢話

用 gepetto 做 Requirements Planning 的最佳流程

如果你是把 gepetto for Requirements Planning 當成主要用途，通常最有效的做法是：

1. 先寫一份粗略但真實的 spec file
2. 用 gepetto 跑這份檔案
3. 回答釐清問題時提供 operational detail，而不是口號
4. 檢查產出的 plan 是否漏掉商業規則
5. 把 section 輸出當成實作單位或 tickets
6. 在需求大幅變更後重新執行或續跑

這種做法通常遠比一次要求它產出一份龐大的最終 spec 更有效。

優先該讀哪些 repository 檔案

如果你想在全面採用前先判斷這個 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 不只是對話式 prompt。它本來就是設計成會把 planning artifacts 寫進你指定的目錄。從 repo 內容可看出，輸出可能包括：

• research notes
• 主 implementation plan
• sections/index.md
• 各個獨立的 section files

這點很重要，因為這樣的工作流程可續跑、可交接，也比短暫存在聊天視窗裡的輸出更容易管理。

External review 很有價值，但實務上屬於可選

gepetto 最強的一個設計點，就是 external review 這一輪。從 references 看得出來，它預期會透過其他 model CLI（例如 Gemini 與 Codex）來審視生成出的 plan。這能很實際地提升計畫品質，因為它常能補出：

• security 缺口
• edge cases
• performance 顧慮
• 含糊不清的需求
• 架構上的 footguns

但這也代表，若要把 gepetto 的價值吃滿，你的環境條件很關鍵。假如你沒有這些 external tools，其餘規劃流程仍然有用，只是這一層 review 可能需要自行調整做法。

提升第一次執行品質的實用建議

以下幾個細節，會明顯影響你的 gepetto 結果：

• 如果你已經有 codebase，請附上既有模式或 file paths
• 說明預期規模、流量與 failure handling
• 明確指出哪些東西不能改
• 列出所有 compliance、privacy 或 audit 需求
• 回答訪談問題時務必具體，不要只說「照標準做」
• 在開始執行前，先檢查產生的 sections 是否有相依順序問題

當 gepetto 可以在前期把模糊處攤出來，而不是把它們掩蓋掉時，它的表現通常最好。

gepetto skill 常見問題

gepetto 會比一般規劃 prompt 更好嗎？

對簡單工作來說，不一定。但對多步驟、牽涉面較廣的功能，gepetto 通常更強，因為它強制走完一套規劃流程：spec 驗證、research、interview、synthesis、review 與 sectioning。一般 prompt 表面上看起來比較快，但也更容易跳過隱藏假設。

gepetto 對新手友善嗎？

算友善，只要你能寫一份基本的 markdown spec，並願意回答後續問題即可。你不需要一開始就有完美 spec。不過，如果是完全新手，仍可能需要有人協助判斷輸出的 plan 是否真的符合工程上的現實限制。

什麼情況不該用 gepetto skill？

遇到以下情況就可以跳過 gepetto：

• 任務很小、風險也低
• 你已經有一份核准過的 implementation plan
• 你無法提供 spec file
• 你不希望輸出以檔案形式保存
• 你的環境無法支援你需要的流程

這套流程的額外成本是刻意設計的，所以它不適合一次性、隨手做完就丟的任務。

gepetto 一定要能讀 codebase 嗎？

不一定，但有會更好。這個 skill 也可以只根據產品型 requirements 文件運作。不過，當它能結合真實 repo 或專案脈絡，研究既有模式與架構時，價值會更高。

最大的採用障礙是什麼？

通常是輸入品質與呼叫格式。很多人會把 gepetto 當成自由對話 chatbot 來啟動，但它不是。這個 skill 預期收到的是 markdown spec path，以及一個可寫入 planning files 的目錄脈絡。

gepetto 主要是拿來做 Requirements Planning，還是 implementation？

它最核心的強項是 貼近 implementation 的 Requirements Planning。它不是純產品探索，也不是純程式碼生成，而是站在中間：把需求與限制整理成開發者可以實際執行、而且比較不容易踩雷的計畫。

如何改善 gepetto skill 的使用效果

先改善 spec 品質，不是把它寫得更長

想提升 gepetto 輸出，最有效的方法通常是提高輸入 spec 的訊號品質，而不是堆更多字。真正有幫助的是具體資訊，不是填充內容。以下幾類細節特別重要：

• 目前架構
• 受影響系統
• 預期規模
• security/compliance 需求
• migration 或 rollout 限制
• 你在意的 failure modes

一份只有一頁、但資訊具體的 spec，通常會比五頁空泛簡報更有用。

把 gepetto 無法自行推斷的限制直接講清楚

gepetto 可以提釐清問題，但它無法可靠地推斷那些藏起來的 business rules。像下面這種限制，應該直接寫明：

• 「必須維持既有 API clients 的 backward compatibility」
• 「Admin actions 需要保留 1 年 audit logs」
• 「本季不得新增新的 infrastructure vendors」
• 「當 provider X 掛掉時，功能必須能 gracefully degrade」

這類限制能大幅提升計畫的真實性與可執行性。

在訪談步驟給出更有力的回答

interview protocol 是 gepetto 最有價值的部分之一，請認真對待。回答太弱，產出的 plan 就會很泛；回答夠精準，section 才會接近可直接執行。

較沒幫助的回答：

• 「standard auth」
• 「make it scalable」
• 「just follow best practices」

較有幫助的回答：

• 「password reset 後，session invalidation 必須立即生效」
• 「org admins 可以邀請使用者，但只有 owners 能修改 billing」
• 「我們預期 6 個月內會有 50k monthly active users」

檢查計畫是否漏掉營運層面的細節

完成第一輪 gepetto 輸出後，請檢查 plan 是否涵蓋以下內容：

• monitoring and alerting
• rollback 或 migration strategy
• data model 變更
• 權限與 abuse cases
• test strategy
• deployment sequencing
• 文件更新

當原始提示太聚焦在功能本身時，這些往往就是最常被漏掉的盲點。

把 section files 當成執行單位來用

sectioning system 是 gepetto 最實用的部分之一。想讓結果更好，請確認 sections 具備以下特性：

• 命名清楚
• 有考慮相依關係
• 大小是為了實作而切，不只是為了寫文件
• 能平行就盡量平行

如果某個 section 卡住太多其他工作，或混入彼此無關的議題，就應該在交給 coding agents 前先拆開。

讓 external review 配合你的實際工具鏈

references 預設 external review 是透過 CLI tools 完成。如果你的環境不同，也應保留同樣的 review 目的，即使執行方式改了也沒關係。重點不是特定工具，而是在 implementation 開始前，讓生成出的 plan 先經過一輪獨立批判與檢視。

gepetto 使用時常見的失敗模式

最常見的問題其實都很可預期：

• 沒有 .md spec file 就直接開始
• 只給一句口號式功能需求
• 在 interview 階段跳過具體回答
• 把第一版 plan 直接當最終版
• 忽略 sections 的相依關係
• 沒有提供 repo-specific conventions

其中大多數問題，靠的是更好的前置設定，不是調更好的 model temperature。

第一次拿到 gepetto 輸出後，該怎麼迭代

一個好的第二輪，通常會長這樣：

1. 在 plan 裡標出不清楚或錯誤的假設
2. 把漏掉的 business rules 補進 spec
3. 重新執行或續跑 gepetto
4. 把修正版 sections 與實際 implementation 條件對照
5. 確認後再把 sections 轉成 tickets 或 coding tasks

這個迴圈，才是 gepetto 指南真正變得有價值的地方：它能在 build work 開始前，先把昂貴的模糊地帶縮小。

如何從 gepetto 長期拿到最大價值

不要只把 gepetto 當成一次性的 ideation 工具。更好的方式，是把它當成中大型功能的可重複規劃標準。團隊通常會在以下幾點標準化後，拿到最大價值：

• specs 應該放在哪裡
• 一份 spec 至少要包含哪些最基本資訊
• review comments 要如何回饋進原計畫
• section files 要如何對應到實作工作

做到這一步，gepetto 就不再只是個聰明的 prompt，而會變成一套可靠的規劃工作流程。