樂高計畫 是做什麼的?
將一個已確定的變更轉換為從基本元件到完整功能的分層有向無環圖(DAG)。僅規劃。然後停止。
這個圖是一個金字塔:獨立區塊在底部,組合區塊在上層,一個完成節點在最頂層。後續的驅動可以平行執行同一層的節點,更新 status 狀態,並重新繪製此圖。此技能不會分派子代理,也不會載入其他技能。
使用時機
當任務是將一個已確定的變更轉換成驅動可以遵循的實作地圖時載入。
- 需求: 要建構的內容已經選定。如果對話中已有檔案列表或路徑選擇,請直接使用。如果沒有,請根據已確定的意圖和程式碼來推導。不要發明第二個系統地圖。
- 跳過: 僅修改錯字、註解、格式、不包含程式碼的文件。
- 如果意圖仍未確定: 停止。提問直到變更確定為止。不要為一個尚未選定的功能堆疊區塊。
一個節點仍然是一個 DAG。輸出完整的合約。
嚴格限制
- 僅規劃。 不要撰寫正式程式碼。不要撰寫測試。在
done when中命名檢查方式。不要在此處實作它。 - 輸出後停止。 在聊天中輸出 DAG 加上暫存檔。不要分派。不要載入下一個技能。
- 無迴圈。 如果一個區塊依賴於一個較後面的區塊,則拆分有誤。重新拆分。
- 不要等待批准。 顯示 DAG 並停止。如果規劃有誤,使用者會中斷。
- 不要為使用者開啟暫存檔。 不要在
docs/下撰寫規劃。
節點粒度
圖形節點(平行單元): 一個可以獨立交付的基本單元,子代理可以在不需要等待另一個正在進行中的節點的情況下擁有它。
範例:write fetchOrder、write OrderCard、wire fetchOrder into the loader。
太大:implement auth。拆分它。太小:rename a variable。將它合併到需要它的節點中。
零件(節點內部): 必須一起完成才能使該節點編譯的函式。一個子代理按順序處理零件。不要將零件分散到不同節點。
範例節點 fetch-order:
files:src/fetchOrder.ts、src/fetchOrder.test.tsparts:Order型別,然後fetchOrder,然後撰寫或擴充src/fetchOrder.test.ts- 這些零件不是單獨的圖形節點
圖形結構
- 第 0 層:
depends on: none的節點。驅動可以平行執行所有節點。 - 第 N 層: 所有依賴項都在較早層級的節點。
- 最後一層: 一個節點(或一組緊密相關的節點),表示功能可以端到端運作。
- 兩個彼此沒有依賴關係的節點必須共享同一層級(或位於不互相等待的層級中)。
depends on列出的是節點 id,絕不是檔案名稱。
相同檔案: 如果兩個節點建立或編輯相同路徑,它們不能共享同一層級。將它們合併,或新增一個 depends on 邊緣讓一個等待。不要為了平行執行而拆分檔案。兩個僅讀取相同路徑的節點可以共享同一層級。files 只列出建立或編輯的路徑。相同檔案的規則包含測試檔案。
節點欄位
每個節點都有全部七個:
- id: 烤串命名法,在此規劃中唯一,穩定不變(後續驅動會用此 id 標記完成)。
- name: 簡短的英文名稱。
- depends on: 其他節點的 id,或
none。 - files: 建立或編輯(路徑)。包含
done when中的測試路徑。 - parts: 有序的 C 語言列表。最後一個零件是撰寫或擴充測試。如果
done when是手動檢查且沒有測試檔案,則最後一個零件就是該檢查,且files中沒有測試路徑。 - done when: 驅動在啟動依賴節點之前可以執行的測試檔案或命令。
- status: 此技能總是寫入
pending。後續驅動可以設定為in-progress或done。此技能永遠不會寫入這兩個狀態。
請勿在規劃中放入完整原始碼。
即時看板
路徑:<repo>/.agent/scratch/lego-plan.json
與聊天區塊中相同的 JSON。代理遵循此檔案。使用者看到的產品是聊天區塊中的圖形。
- 必要時建立
.agent/scratch/。 - 總是覆寫。不要詢問,即使現有節點是
in-progress或done。 - 如果儲存庫有 git,確保
.gitignore包含.agent/scratch/。如果.gitignore存在但缺少該行,則追加它。如果.gitignore不存在,則建立它並包含該行。 - 不要開啟檔案。不要在聊天中以第二份副本的形式傾印它。JSON 區塊是使用者看到的副本。
程序
程序 1:確認變更已確定
- 如果變更已明確,繼續。
- 如果使用者仍在選擇他們想要什麼,停止。提問。確定後再回到此處。
程序 2:收集對話中已有的輸入
- 如果此對話已有完成線的檔案列表、零件或路徑選擇,則使用它們作為起始集合。
- 如果沒有,則從已確定的意圖和必須讀取以命名檔案的程式碼中推導出區塊。不要遍歷整個儲存庫。
程序 3:拆分為節點和零件
- 列出候選的基本單元(B 粒度)。
- 對於每個基本單元,列出必須一起編譯的 C 零件。以撰寫或擴充測試(或手動檢查)結束。
- 繪製
depends on:一個節點僅在其呼叫或嵌入另一個節點的結果時才依賴於該節點。 - 根據依賴關係分配層級。獨立節點 → 同一層級。
- 如果兩個節點建立或編輯相同路徑且共享同一層級,則合併它們或新增一個邊緣。然後重新分層。
- 如果出現迴圈,拆分錯誤的節點並重複此程序。
程序 4:填寫每個節點
填寫七個欄位。每個節點的 status 都是 pending。
程序 5:在聊天中顯示 DAG
按以下順序顯示:
- 層級: 從第 0 層到最後一層。在每個層級下,列出該層級的節點。
- 節點: 每個 id 的七個欄位。
- Mermaid: 總是顯示。一個
flowchart(或graph TD)。圖中的節點 id 必須與規劃 id 匹配。沒有classDef。沒有狀態顏色。每個節點都是 pending。 - JSON 區塊: 一個包含即時看板物件的
json區塊。id、依賴關係、檔案、零件、doneWhen和status的單一事實來源。層級從depends推導出來。不要儲存layer欄位。
然後執行程序 6。
Mermaid 格式:
flowchart TD
fetch-order[fetch-order]
order-card[order-card]
wire-loader[wire-loader]
fetch-order --> wire-loader
order-card --> wire-loader
同一層級的節點之間沒有邊緣。
JSON 格式:
{
"version": 1,
"nodes": [
{
"id": "fetch-order",
"name": "fetch order",
"depends": [],
"files": ["src/fetchOrder.ts", "src/fetchOrder.test.ts"],
"parts": ["Order type", "fetchOrder", "write or extend src/fetchOrder.test.ts"],
"doneWhen": "pnpm test src/fetchOrder.test.ts",
"status": "pending"
}
]
}
depends 是一個 id 陣列。空陣列表示沒有依賴。
程序 6:寫入即時看板
- 將相同的 JSON 寫入
.agent/scratch/lego-plan.json(覆寫)。 - 確保
.gitignore忽略.agent/scratch/,如同即時看板中所述。 - 不要開啟檔案。
程序 7:停止
在程序 6 之後,停止。不要撰寫程式碼。不要分派。不要載入其他技能。
決策樹
- 意圖未確定 → 程序 1。
- 變更已確定,需要實作地圖 → 程序 2 → 3 → 4 → 5 → 6 → 7。
- 只有一個節點 → 仍然是程序 2 → 7(完整的合約)。
- 僅錯字 / 格式 / 文件 → 此技能不適用。
- 依賴關係中有迴圈 → 程序 3 步驟 6。
- 兩個同一層級的節點有相同路徑 → 程序 3 步驟 5。
- 節點是「實作整個功能」→ 拆分(程序 3)。
紅旗
| 訊號 | 代表意義 | 應改為執行 |
|---|---|---|
| 在此技能中撰寫 fetch 函式 | 規劃變成了實作 | 程序 7。停止。 |
| 一個沒有層級的線性列表 | 無法分散執行 | 將獨立節點放在同一層級。 |
| 從此處分派子代理 | 葉子節點變成了驅動 | 程序 7。停止。 |
| Mermaid id 與節點 id 不同 | 驅動無法標記完成 | 兩處都使用相同的烤串命名 id。 |
| JSON 區塊與暫存檔不同 | 兩個事實來源 | 寫入一個物件。複製到兩個地方。 |
迴圈(a → b → a) | 拆分有誤 | 拆分並重新分層。 |
兩個同一層級的節點編輯 order.ts | 平行寫入衝突 | 合併或新增一個 depends on 邊緣。 |
| 為了讓兩個節點平行執行而拆分一個檔案 | 未經請求的設計 | 保留檔案。將節點排序。 |
files / 最後一個零件缺少測試路徑 | 節點無法交付 | 程序 3 步驟 2。 |
在規劃的 Mermaid 上使用 classDef 或狀態顏色 | 此技能繪製進度 | 無樣式。全部 pending。 |
| 將一個節點的零件拆分為無法單獨編譯的平行節點 | C 被當作 B 處理 | 將這些零件保留在一個節點內。 |
| 將「Implement auth」作為一個單一節點 | 太大 | 拆分為基本單元。 |
| 等待「看起來可以嗎?」 | 限制是顯示並停止 | 輸出並停止。 |
| 在覆寫暫存檔之前詢問 | 即時看板只有一個位置 | 程序 6。覆寫。 |
開啟 .agent/scratch/lego-plan.json | 使用者看到額外檔案 | 僅限聊天。檔案是給代理用的。 |
撰寫 docs/lego-plan.md | 額外的產出物 | 聊天加上暫存檔。沒有 docs 規劃檔案。 |
錯誤處理
- 對話中沒有檔案列表: 從意圖和目標讀取中推導。如果你無法命名檔案,則停止並說明缺少什麼。不要發明路徑。
- 迴圈: 透過 id 報告迴圈。拆分。重新執行程序 3。不要將有迴圈的 Mermaid 顯示為規劃。
- 最後一層不代表功能可以運作: 新增一個依賴於組合元件(接線)的完成節點,或說明為什麼目前的最後一層已經是端到端路徑。
- 使用者中斷指出某個節點有誤: 編輯該節點以及任何指向它的
depends on。如果節點仍然存在,則保持 id 穩定。如果你刪除了一個節點,也一併從 Mermaid 和 JSON 中移除它。覆寫暫存檔。再次顯示 DAG。停止。 done when太模糊(例如「it works」):用一個命令或測試路徑取代。如果專案還沒有測試命令,則用一行說明手動檢查的方式。最後一個零件就是該檢查。- 不是 git 儲存庫: 如果工作空間可寫入,仍然在
.agent/scratch/下寫入lego-plan.json。跳過 gitignore 步驟。在聊天中用一行說明。 - 暫存檔寫入失敗(權限、磁碟):仍然顯示聊天 DAG 和 JSON 區塊。說明即時看板未被寫入。不要假裝檔案存在。
- 現有暫存 JSON 無效或正在執行中: 覆寫。不要合併。不要詢問。