Communitygithub.com

樂高計畫

將已確定的變更轉換為從基本元件到完整功能的分層有向無環圖(DAG)。僅規劃,然後停止。

樂高計畫 是什麼?

這個技能(Lego Plan)專門用於將一個已確定的變更,拆解成一個有序的、分層的、無環的實作步驟圖(DAG),從最簡單的獨立區塊逐步建構到完整功能。它不適合用於意圖尚未確定、僅修改錯字、註解、格式或文件的任務。其核心價值在於為後續的執行驅動(driver)提供一個清晰、可平行處理的實作地圖,驅動可以按照圖中的層級順序,平行執行同一層的節點,並更新節點狀態。此技能僅產出規劃,不會撰寫任何實作程式碼、測試或分派子代理。它支援任何可以存取檔案系統的環境,將規劃以 JSON 格式寫入 `.agent/scratch/lego-plan.json`,同時在聊天介面中以層級列表、節點欄位和 Mermaid 流程圖的形式呈現,確保規劃的單一資訊來源。該技能內建嚴格的節點粒度規則,確保每個節點是一個可獨立交付的單元,並透過依賴關係(depends on)和檔案衝突檢測來避免平行寫入衝突,保證規劃的可行性。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/AlemTuzlak/skills/tree/HEAD/skills/lego-plan

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

樂高計畫 是做什麼的?

將一個已確定的變更轉換為從基本元件到完整功能的分層有向無環圖(DAG)。僅規劃。然後停止。

這個圖是一個金字塔:獨立區塊在底部,組合區塊在上層,一個完成節點在最頂層。後續的驅動可以平行執行同一層的節點,更新 status 狀態,並重新繪製此圖。此技能不會分派子代理,也不會載入其他技能。

使用時機

當任務是將一個已確定的變更轉換成驅動可以遵循的實作地圖時載入。

  • 需求: 要建構的內容已經選定。如果對話中已有檔案列表或路徑選擇,請直接使用。如果沒有,請根據已確定的意圖和程式碼來推導。不要發明第二個系統地圖。
  • 跳過: 僅修改錯字、註解、格式、不包含程式碼的文件。
  • 如果意圖仍未確定: 停止。提問直到變更確定為止。不要為一個尚未選定的功能堆疊區塊。

一個節點仍然是一個 DAG。輸出完整的合約。

嚴格限制

  1. 僅規劃。 不要撰寫正式程式碼。不要撰寫測試。在 done when 中命名檢查方式。不要在此處實作它。
  2. 輸出後停止。 在聊天中輸出 DAG 加上暫存檔。不要分派。不要載入下一個技能。
  3. 無迴圈。 如果一個區塊依賴於一個較後面的區塊,則拆分有誤。重新拆分。
  4. 不要等待批准。 顯示 DAG 並停止。如果規劃有誤,使用者會中斷。
  5. 不要為使用者開啟暫存檔。 不要在 docs/ 下撰寫規劃。

節點粒度

圖形節點(平行單元): 一個可以獨立交付的基本單元,子代理可以在不需要等待另一個正在進行中的節點的情況下擁有它。

範例:write fetchOrder、write OrderCard、wire fetchOrder into the loader。

太大:implement auth。拆分它。太小:rename a variable。將它合併到需要它的節點中。

零件(節點內部): 必須一起完成才能使該節點編譯的函式。一個子代理按順序處理零件。不要將零件分散到不同節點。

範例節點 fetch-order:

  • files:src/fetchOrder.ts、src/fetchOrder.test.ts
  • parts:Order 型別,然後 fetchOrder,然後撰寫或擴充 src/fetchOrder.test.ts
  • 這些零件不是單獨的圖形節點

圖形結構

  • 第 0 層: depends on: none 的節點。驅動可以平行執行所有節點。
  • 第 N 層: 所有依賴項都在較早層級的節點。
  • 最後一層: 一個節點(或一組緊密相關的節點),表示功能可以端到端運作。
  • 兩個彼此沒有依賴關係的節點必須共享同一層級(或位於不互相等待的層級中)。
  • depends on 列出的是節點 id,絕不是檔案名稱。

相同檔案: 如果兩個節點建立或編輯相同路徑,它們不能共享同一層級。將它們合併,或新增一個 depends on 邊緣讓一個等待。不要為了平行執行而拆分檔案。兩個僅讀取相同路徑的節點可以共享同一層級。files 只列出建立或編輯的路徑。相同檔案的規則包含測試檔案。

節點欄位

每個節點都有全部七個:

  1. id: 烤串命名法,在此規劃中唯一,穩定不變(後續驅動會用此 id 標記完成)。
  2. name: 簡短的英文名稱。
  3. depends on: 其他節點的 id,或 none。
  4. files: 建立或編輯(路徑)。包含 done when 中的測試路徑。
  5. parts: 有序的 C 語言列表。最後一個零件是撰寫或擴充測試。如果 done when 是手動檢查且沒有測試檔案,則最後一個零件就是該檢查,且 files 中沒有測試路徑。
  6. done when: 驅動在啟動依賴節點之前可以執行的測試檔案或命令。
  7. 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:確認變更已確定

  1. 如果變更已明確,繼續。
  2. 如果使用者仍在選擇他們想要什麼,停止。提問。確定後再回到此處。

程序 2:收集對話中已有的輸入

  1. 如果此對話已有完成線的檔案列表、零件或路徑選擇,則使用它們作為起始集合。
  2. 如果沒有,則從已確定的意圖和必須讀取以命名檔案的程式碼中推導出區塊。不要遍歷整個儲存庫。

程序 3:拆分為節點和零件

  1. 列出候選的基本單元(B 粒度)。
  2. 對於每個基本單元,列出必須一起編譯的 C 零件。以撰寫或擴充測試(或手動檢查)結束。
  3. 繪製 depends on:一個節點僅在其呼叫或嵌入另一個節點的結果時才依賴於該節點。
  4. 根據依賴關係分配層級。獨立節點 → 同一層級。
  5. 如果兩個節點建立或編輯相同路徑且共享同一層級,則合併它們或新增一個邊緣。然後重新分層。
  6. 如果出現迴圈,拆分錯誤的節點並重複此程序。

程序 4:填寫每個節點

填寫七個欄位。每個節點的 status 都是 pending。

程序 5:在聊天中顯示 DAG

按以下順序顯示:

  1. 層級: 從第 0 層到最後一層。在每個層級下,列出該層級的節點。
  2. 節點: 每個 id 的七個欄位。
  3. Mermaid: 總是顯示。一個 flowchart(或 graph TD)。圖中的節點 id 必須與規劃 id 匹配。沒有 classDef。沒有狀態顏色。每個節點都是 pending。
  4. 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:寫入即時看板

  1. 將相同的 JSON 寫入 .agent/scratch/lego-plan.json(覆寫)。
  2. 確保 .gitignore 忽略 .agent/scratch/,如同即時看板中所述。
  3. 不要開啟檔案。

程序 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 無效或正在執行中: 覆寫。不要合併。不要詢問。

Individual skills in this repo

This repo contains 14 individual skills — each has its own dedicated page.

AlemTuzlak/skills

Use when the user wants to write a blog post about a feature, product change, PR, git diff, or any technical topic - accepts marketing briefs, PRs, git refs, codebase paths, or freeform descriptions as input

AlemTuzlak/skills

Use when the user wants to generate a changelog, release notes, or document what changed between versions, tags, or PRs

AlemTuzlak/skills

Use when writing, editing, or organizing documentation, when planning what docs a feature needs, and whenever planning or implementing a new feature or change in a repo (docs ship with the code). Also use when tempted to write docs without showing the discovered readers to the user, without asking for tone, or without loading simple-english and i-have-adhd. Triggers on "write docs for X", "document this feature", "add a guide", "update the docs", "reorganize the docs", "plan feature X", "implement X", or /docs.

AlemTuzlak/skills

Use when a bug is in play: a test fails, CI is red, an API returns the wrong result, a stack trace appears, or the user says it is broken or fix this. Don't use for a new feature with no failure, for types-only work, or for docs.

AlemTuzlak/skills

Use when the user invokes /i-have-adhd, says they have ADHD, or asks for ADHD-friendly output. Also used as a required writing filter by the docs skill. Don't use for marketing copy or after the user says "stop adhd mode" or "normal mode".

AlemTuzlak/skills

Use when the user wants to write a product update email, feature announcement newsletter, or digest email for users or subscribers

AlemTuzlak/skills

Use when the user wants to turn a raw talking-head / screen-share recording into a finished, edited, annotated video plus a full content package. Removes silences, flags mistakes for the user to cut, transcribes, adds transcript-synced overlays (code, on-screen code highlights, word highlights, lists, comparisons, diagrams, section labels, punch-in zooms), renders with original audio, then generates blog/socials/YouTube content. Triggers on "produce a video", "edit my video", "annotate my recording", "/produce-video".

AlemTuzlak/skills

Use when the user runs /prove-it or says prove it, prove the changes, show me in the browser, or asks to prove a UI or API change. Don't use only because the agent is about to say done, for types-only work, or for docs with no behavior to prove.

AlemTuzlak/skills

Use when the user wants to write, draft, or author an RFC (Request for Comments) / technical design doc for a feature, change, or architectural decision. Interactively interviews the user, grounds the proposal in the actual codebase, presents 2-3 concrete API/code-snippet approaches to choose from, then writes a review-ready RFC. Triggers on "write an RFC", "draft an RFC", "RFC for X", "design doc for X", or /rfc.

AlemTuzlak/skills

Use when the user wants to deeply learn a new topic from scratch. Runs a pre-interview (current knowledge, end-goal proficiency, depth, practice load, background, scope), researches online (articles, niche-influencer blogs, canonical docs, subtopic landscape), then produces a structured markdown course with mandatory visual diagrams, evidence-based learning-science features (retrieval practice, spaced callbacks, worked-example fading, concept ledger, jargon gate, analogy hygiene), and a self-contained interactive HTML mini-course. Triggers on /teach-me, "teach me about X", "I want to learn X", "deep dive on X", "create a course on X", "study X with me".

AlemTuzlak/skills

Use when the change intent is already settled and the agent must map what a behavior change touches before an implementation plan or any code. Use for new features, bug fixes, and refactors that move a boundary. Don't use for typos, comments, formatting, lockfile-only diffs, docs with no code, or while the user is still deciding what they want.

AlemTuzlak/skills

Use when the user wants to transcribe a video or audio file to text with word-level timestamps — spins up a self-contained local Whisper (whisper.cpp) Docker service bundled in this skill and returns transcript.txt, transcript.srt, and word-level transcript.words.json. Also used as a building block by /produce-video. Triggers on "transcribe this video", "get a transcript", "transcribe-video".

AlemTuzlak/skills

Use when the user wants to write a video script for a product demo, feature walkthrough, launch video, or social media video about a feature or product change

AlemTuzlak/skills

Use when the user wants YouTube metadata for a video — a click-worthy title, an SEO/above-the-fold description, tags, and timestamped chapters. Accepts a transcript (ideally timestamped SRT), a topic, a PR, or a freeform description. Used standalone and by /produce-video. Triggers on "youtube title", "youtube description", "youtube chapters", "youtube tags", "youtube metadata", "youtube-copy".

相關技能