blueprint

blueprint skill 概覽

blueprint 的功能是什麼

blueprint skill 會把一句話目標轉成適合複雜工程工作的逐步建置計畫。它是為多個 session、跨多個 PR 的任務而設計，讓新的 agent 接手時有足夠上下文可延續工作，不必靠猜。若你需要的是 Project Setup 的 blueprint、遷移 roadmap，或帶有相依關係的重構計畫，這個 skill 會很適合。

哪些人適合安裝 blueprint

如果你經常在不同 session 之間交接工作、需要協調可平行進行的子任務，或需要一份在上下文遺失後仍能繼續使用的計畫，就值得安裝 blueprint。它特別適合在既有 repo 內工作的 agent，因為真正的難點往往不是想點子，而是如何安全安排工作順序。

blueprint 與一般提示有何不同

和通用 prompt 不同，blueprint 內建了觸發規則、相依順序安排、平行步驟偵測、對抗式檢查關卡，以及計畫修訂協議。當主要風險不是寫程式，而是做錯順序、把步驟切得太粗、或漏掉 rollback 路徑時，這些差異就很重要。

如何使用 blueprint skill

正確安裝並觸發 blueprint

用目錄既有的 skill installer 安裝 blueprint skill，並只在任務真的屬於多階段時才觸發。這個 repo 自帶的觸發規則刻意設得很窄：只有在工作很可能需要多個 session 或多個 PR，且你要的是 plan、blueprint 或 roadmap 時才使用；如果只是一次就能完成的小改動，就不要用它。

提供 blueprint 正確的來源輸入

當你的輸入明確寫出目標、目標 repo、限制條件，以及完成定義時，blueprint 效果最好。弱的 prompt 像是「plan the refactor」。更強的 prompt 會像：「Create a blueprint for Project Setup: move config loading into a shared module, keep backward compatibility for two releases, and separate UI changes from backend migration.」範圍越具體，產生出的相依圖和步驟切分通常越準確。

先讀這些檔案

先從 SKILL.md 開始，再查看 repo 內任何描述 workflow、慣例或既有計畫的文件。在這個 repository 裡，skill 本體是自包含的，所以最需要抽出的重點是它的流程：research、design、review，以及 mutation 規則。若目標 codebase 有 memory files、架構文件，或過去的 migration notes，這些都能明顯提升 blueprint 的輸出品質。

能產出更好 blueprint 的工作流程

使用 blueprint 最好分三輪：先產生計畫，再檢查各步驟是否真的能獨立執行，最後針對遺漏的相依關係或不安全的平行安排做修訂。特別留意那些會碰到同一批檔案、共享狀態，或受 release 順序限制的步驟；這些情況最容易讓看似漂亮的計畫在實作時失敗。blueprint 最好的使用方式，不是「寫得更細」，而是「順序正確，且上下文足夠讓人冷啟動執行」。

blueprint skill 常見問題

blueprint 只適合大型專案嗎？

大致上是。這個 skill 是為了那些大到無法用單一 PR 解決，或如果沒有計畫就會有明顯風險的工作而設計。若任務很小、很直接，或只需少量 tool calls 就能完成，一般 prompt 通常會更快。

blueprint 和一般 prompt 有什麼差別？

一般 prompt 也能要求產出計畫，但 blueprint 多了一層結構：步驟相依、平行工作偵測、rollback 思維，以及一個會嘗試抓出薄弱假設的 review 層。當你需要的是 Project Setup 的 blueprint，或任何對順序與交接品質要求高的任務時，這會讓它更可靠。

blueprint 適合初學者嗎？

適合，前提是你的目標是學會如何把專案拆成可管理的階段。如果你連任務本身是什麼都還沒想清楚，那它就沒那麼有用，因為這個 skill 預設你已經有明確的工程目標、限制條件，以及可完成的路徑。

什麼情況不該使用 blueprint？

當工作小到可以直接做完、使用者明確表示「just do it」，或任務本身沒有實質的相依結構時，就不該用 blueprint。這些情況下，規劃帶來的額外成本只會拖慢進度，卻不一定改善結果。

如何改進 blueprint skill

明確寫出邊界

最好的 blueprint 輸出，來自清楚的範圍界線：哪些一定要改、哪些必須維持穩定、哪些不在範圍內，以及成功的判準是什麼。如果你要的是 Project Setup 的 blueprint，請直接說明你要動的是 repo bootstrapping、environment config、CI setup，還是三者都要。範圍模糊，是最容易讓計畫變得過大或過淺的原因。

一開始就提供相依線索

當 blueprint 事先知道哪些部分會卡住其他部分時，表現會最好。請先提到 migrations、shared modules、feature flags、API contracts、release order，以及任何必須先落地、後續步驟才能開始的事項。這能幫助 skill 產出真正可用的相依圖，而不是一串彼此脫節的任務清單。

要求可直接執行的步驟

如果你想讓 blueprint skill 的輸出更好，請要求它把步驟寫成新的 agent 能在冷啟動狀態下直接執行的形式。也就是說，每一步都應該帶有足夠的上下文、預期結果與風險說明，避免接手的人還得重讀整個 repo。這點對多 agent 協作尤其重要，因為模糊的步驟標題很容易導致重工。

針對第一版 blueprint 持續迭代

把第一份 blueprint 當成草稿，檢查是否漏掉限制條件、是否有互相衝突的平行工作，或是否有大到無法塞進單一 PR 的步驟，再進一步收斂。如果計畫太寬，就把它拆開；如果太細，就把重複的 setup 工作合併。目標不是做出更漂亮的大綱，而是做出一份能降低執行風險的 blueprint。