樹狀編排方法論 ： 用一棵樹拆解大型任務 — 土壤 · 根 · 幹 · 枝 · 葉 + 果園

⚠️ 閱讀前必看

下列 5 條是這套方法最容易誤解、與直覺不同的重點，建議讀完全文前先過一次：

1. 對「人」來說，過程不重要、結果才重要。 你（土壤）只給方向、只做最終驗收，不下去微操枝葉。中間怎麼拆、怎麼調度、怎麼重試，都交給樹自己長。
2. 一棵樹固定只有 4 層 agent：根 → 幹 → 枝 → 葉。 不遞迴加深。任務再大也是「開更多棵樹」（森林），不是把一棵樹疊更高。
3. 單樹上限 ≤ 64 片葉（幹→枝 ≤8、枝→葉 ≤8）。超過就拆成多棵樹，請人多開幾個對話分別種。
4. 果子（commit）全程留在本地，push 是唯一對外接縫。 push 之前整棵樹可砍可重種、零對外副作用；用「人驗收」當 push 的閘門。
5. changeset 便利貼嚴格在「人驗收完果子後」才貼。 貼完才 push、才正式進 工作流程規範 的 5-phase。

這份文件與 skill 同步。 給 AI 看的定稿在 .claude submodule 的 skills/tree-orchestration/（做事）與 skills/orchard/（出貨）；本文是給人看的同一套方法論。兩者要保持一致 — 改了一邊，記得同步另一邊。

一、為什麼需要樹狀編排

把一個大任務直接丟給單一 AI 對話，會遇到三個老問題：

• Context 爆炸：任務一大，所有細節塞進同一個 context，越塞越鈍、越貴、越容易漏。
• 過程不可控：你看不到它中途怎麼想、在哪裡卡住，只能等一坨結果，好壞全靠運氣。
• 失敗難收斂：卡住時要嘛硬撐、要嘛整個重來，沒有「換更強的腦再試一次」這種有紀律的升級路徑。

樹狀編排的解法是：把「過程」交給一棵會自己分層、調度、蒸餾、重試的樹；把「驗收」留給人。

• 每一層只處理自己該處理的抽象度，細節往下沉、精簡摘要往上浮（逐層蒸餾），context 不會在任何一層爆掉。
• 每一個子任務都帶可驗收標準，做完就能驗（成果自證），不靠「我有認真做」這種過程型藉口。
• 卡住時有固定的升級階梯（換更強的腦再試）與事不過三的上限，不會無限重試也不會默默放棄。

二、世界模型：一棵樹 + 一座果園

把一個大任務想成「種一棵樹」：

載入圖表中…

怎麼讀這張圖：左邊是一棵樹，由下而上生長 —— 土壤（人）紮根，往上經根 → 幹 → 枝 → 葉，最頂端每片葉結出 🍐 果子（commit）。果子沿虛線掉回土壤給人驗收；人點頭後，才從土壤把成果 push 向右送進果園（GitHub），由檢驗員、主管接力跑完出貨流程。幹只跟枝交流、不直接長葉（見下方 § 3.3）。

層	身份	對應的東西	一句話職責
🟫 土壤	人	你	定向、最終驗收、出貨拍板
🌱 根	Agent	與你對話的那個 AI	規劃大計畫書、把幹的報告翻成白話、與你來回
🪵 幹	主 Agent	調度中樞	把大計畫拆成多份中計畫、派工、判斷、修剪、守閘
🌿 枝	Workflow 工具	一支 JS 編排腳本	確定性地一次批次執行一叢葉、逐葉檢核
🍃 葉	subagent（專家優先）	執行單位	做單一細任務、改檔結出果子、回自評
🏡 果園	GitHub	出貨域	PR → CI/gate → 部署 bot → 出貨（見 工作流程規範）

任務與計畫的比例，從上到下逐層放大：

• 根 : 幹 = 1 : 1（一棵樹一個中軸）
• 幹 : 枝 = 1 : N（一份大計畫拆成多份中計畫，每份派一支枝）
• 枝 : 葉 = 1 : N（一份中計畫展開成多片葉；單一任務 = 一支只含 1 片葉的薄枝）

幹不直接長葉 —— 葉一律由枝產生，唯一路徑是 根 → 幹 → 枝 → 葉（詳見下方 § 3.3）。

果園對照（細節見 工作流程規範）：

比喻	真實
🍐 果子	一個 commit
🏷️ 標籤	一張 changeset（沒標籤過不了歸檔）
🧺 果籃	一條 feature / fix 分支 → PR
🔬 檢驗員	GitHub Actions（CI / changeset gate）
👔 主管	GitHub App / 部署 bot（統籌放行、auto-merge、開 Version PR、deploy；但 main 出貨最終權在人）

三、五層職責

每一層各司其職，只跟相鄰層說話，不越級指揮。

3.1 🟫 土壤 = 人

	內容
職責	提供意圖與方向；最終驗收掉回土壤的果子；決定是否送果園出貨
✅ 可做	否決任何枝/葉；批准 merge 進 main；改變大方向；決定種樹（開新對話）的順序與時機
⛔ 不做	不親自執行細任務；不下沉微操枝/葉
介面	只跟「根」來回；不直接指揮幹/枝/葉

森林是人持有的：一棵樹裝不下（>64 葉）就種多棵，全紮在同一片土壤（同一個你）。樹與樹零交互，整合點是 GitHub main。

3.2 🌱 根 = Agent（與人對話的最強腦）

	內容
職責	與你頻繁來回制定方向 → 產出大計畫書 → 交給幹執行 → 幹回報後翻成最白話、通俗的話回報給你
✅ 可做	規劃 / 反覆驗證大計畫書；判斷任務規模；要求你多開對話（多棵樹）；重評幹升級上來的問題
⛔ 不做	不自己執行細任務；不跳過幹直接指揮枝葉；不擅自改你給的方向（要回土壤確認）
腦力配置	最重的判斷在這層（最高規格模型 + 最深思考）

根的開場閘（種樹前必做）：把大計畫書交給幹之前，先兩問 —

1. 會超過 64 葉嗎？（粗估 N 枝 × M 葉）
2. 切得開嗎？（有沒有乾淨接縫）

判斷	動作
≤ 64 葉	種一棵樹，交給幹
> 64 葉 且切得開	給你切分建議 + 新樹種子（提示詞）：「先專注這棵，其餘交給另一棵樹」
> 64 葉 但緊耦合（切不開）	不可硬拆成多樹；重找乾淨接縫，或壓進單棵 64 葉內

3.3 🪵 幹 = 主 Agent（自適應指揮官）

全樹唯一中軸，編排狀態、計畫、再規劃都在這層。

	內容
職責	收根的大計畫書 → 拆成 ≤8 份中計畫書 → 每份派一支枝（Workflow） → 讀自評做判斷 → 修剪 / 再長 / 升級 → 逐層蒸餾匯總成精簡報告回根
✅ 可做	建立 / 呼叫 Workflow（枝）；一律透過枝調度葉、不直接 spawn 葉；砍爛枝、對殘留長新枝；在分支逐枝 commit；守深度 / 寬度 / 預算閘
⛔ 不做	不可改變計畫意圖（這類問題一律升級給根）；不可直接長葉（一律經枝）；不可超閘；不可默默改計畫；不可直推 main / preview

派工前先驗（上層先驗原則）：拆出每份中計畫書、扇出之前先做兩件事 —

1. 可行性：這份計畫一眼可行嗎？不可行 → 零成本立刻彈回根，不浪費枝葉。
2. 供給檢查：執行需要的專家都到位嗎？缺專家就真造一個專家或升級給人/根造 — 絕不拿通用 agent 充當專家。

讀自評後的三軸決策（自評 schema 見 第六節）：

結果	意思	動作
met	達標	✅ 收果子
partial	地基對、沒做完	🌿 再長枝（保留好的，只對未完成項長新枝）
unsound	做了但地基錯	🔪 砍枝（丟掉，修正中計畫書重發）
blocked	做不下去	進失敗分診（見 第七節）

3.4 🌿 枝 = Workflow 工具

枝 = 一支 JS 腳本，背景確定性地照腳本一次長出一叢葉。它有物理限制：

• ❌ 不收中途輸入（不能臨場問人、改主意）
• ❌ 不能無限疊深（枝不長子枝；要更深的判斷 → 交回幹）
• ✅ 並行上限 16、單次最多 1000 片葉

	內容
職責	拿中計畫書 → 派 ≤8 片葉 → 逐葉比對「指派的任務 vs 葉的自評」→ 整理成自評回幹
✅ 可做（有界、確定性自修）	葉品質不對時自審重派 1 次；列舉型任務 loop-until-dry（連 2 輪無新增即停，≤3 輪）
⛔ 不做	不長子枝；不臨場改計畫；需要判斷 / 重規劃就立刻彈回幹

「枝自己修」與「彈回幹」的分界：技術性卡住（逾時、品質微調、列舉收斂）→ 枝在腳本內有界處理；需要換方法、範圍定錯、要改計畫意圖 → 枝做不到判斷，立刻彈回幹。

3.5 🍃 葉 = subagent（執行單位）

一片葉 = 執行單一、無法再細分的小任務的 subagent。

	內容
職責	在自己 context 內執行單一細任務（光合）；改檔則結果子（commit 級變更）；回自評
✅ 可做	讀寫跑（自己 context）；專長任務優先用專家 agent（如無障礙稽核、UI 元件、changeset 撰寫等）
⛔ 不做	不決策方向；不開枝；不污染上層 context（只回精簡自評 + 報告路徑）

成果自證：每片葉派出前帶一條可驗收標準，且只看交付物就能判定：

• 改檔（結果子）→ 機器可驗（對齊果園 Actions 會檢的，如「typecheck 過」）
• 不改檔（探索 / 分析）→ 自帶複驗證據（問句清單 + 重現步驟 / 搜尋 pattern / 檔案:行號）
• ⛔ 禁過程型標準（「有認真找」「翻過很多資料」不算）

四、七條碎形原則

這套方法是碎形的：同一組原則在每一層重複套用，只是抽象度不同。

1. 成果自證：每個任務都帶可驗收標準；結果子的 → 機器可驗，不結果子的 → 自帶複驗證據；禁過程型標準。
2. 上層先驗，不行就彈：扇出前先驗計畫可行性 + 供給檢查（缺專家就造 / 強化）；不可行立刻往上彈，不浪費下層。
3. 升級 = 換更強的腦：葉 → 枝 → 幹 → 根 → 人，逐級升級；同一層內則升「模型 × 思考強度」。
4. 重試需「兩次之間有變數改變」：純重 roll 最多 1 次；依失敗原因分診；事不過三為上限、任務本身有誤則短路（不浪費重試）。
5. 逐層蒸餾：精簡摘要往上浮（有界），完整細節留在硬碟報告（按需下鑽），任何一層 context 都不爆。
6. 檢核歸幹（自動）、驗收歸人：「做得對不對」由幹自動較驗；「要不要的就是這個」由人驗收。
7. 通用紀律入 Skill、領域專長掛 Agent：流程紀律寫進 skill 全樹共用；專業能力做成專家 agent 按需掛載。

五、規模與閘

閘	值	超過怎麼辦
深度	固定 4 層（根→幹→枝→葉）	不加深，改開新樹
寬度 K	幹→枝 ≤8、枝→葉 ≤8	分波次，或先拆成 ≤8 份中計畫各自展開
單樹葉數	≤ 64（= 8 × 8）	開新樹（森林）
重試 R	3（且付得起）	升級給上一層
預算	估算 × 1.5 為 backstop	碰到 = 升級，不靜默停

森林：一棵樹裝不下時

超過 64 葉，不加深也不加寬，改開新樹。多棵樹紮在同一片土壤（同一個你），整合點是 GitHub 的 main 分支：

載入圖表中…

跨樹規範：

• 樹與樹過程零交互；唯一整合點 = GitHub main。
• 新樹只從當下的 main 長出去。
• 只允許並行樹（彼此獨立） 或 乾淨序列樹（B 從 A 已 merge 的 main 長）；緊耦合禁止硬拆成多樹。
• 序列樹之間夾一次「人的 merge」——人的 merge = 森林心跳。

一棵樹 = 一條 repo 分支 = 一個 PR = 一張 changeset。 森林 = 多分支 = 多 PR，各自獨立過關。

六、自評契約 — 逐層蒸餾的載體

葉、枝、幹回報時用同一個自評格式（碎形契約），上層只讀這個就能判斷，不用把細節吸進 context：

{
  "task_id":      "string",          // 對應收到的（子）計畫
  "outcome":      "met | partial | unsound | blocked",
  "failure_mode": "none | transient | quality | missing_setup | task_invalid | budget",
  "confidence":   "high | medium | low",   // 對 outcome 的把握；low → 上層下鑽讀報告
  "evidence":     "string",          // 成果自證：outcome 怎麼驗的（一行）
  "unresolved":   ["string"],        // 殘留待辦；partial 時 = 再長枝的輸入
  "fruit":        "{ commits:[], files:[] } | null",  // 結的果子；不結果子 = null
  "report_path":  "string",          // 完整細節落地的報告路徑（細節不進 context）
  "summary":      "string",          // 唯一往上進 parent context 的散文 → 強制蒸餾、必須有界
  "children":     "[ 自評... ] | []"  // 碎形 roll-up：葉層為空；枝=葉自評群；幹=枝自評群
}

關鍵設計：

• summary 是唯一往上進 parent context 的散文，必須有界；完整過程一律留 report_path（落在硬碟，按需下鑽）。
• confidence: low → 上層會下鑽讀報告確認再判（全覆蓋摘要 + 抽查細節）。
• failure_mode 驅動上層的分診（見下一節）。

這就是為什麼「上百片葉」也不會壓垮整理它們的那一層：每片葉只交一句有界 summary + 一個路徑，細節全留硬碟。

七、失敗處理：分診 + Retry Ladder

讀到 blocked 或失敗時，先看 failure_mode 分診，不要無腦重試：

失敗原因	槓桿（該動什麼）	燒重試次數？
transient（環境 / 連線）	不變，純重試	是
quality（推理不足）	升思考強度 → 升模型（Retry Ladder）	是
missing_setup（缺工具 / 權限 / 輸入）	修 setup 再試；補不了 → 升級	視情況
task_invalid（任務本身有誤）	立刻升級給根，不燒重試（短路）	否
budget（預算耗盡）	升級給人（要預算）	否

Retry Ladder（重試階梯）：同一份計畫每重試一次就升一級腦力 —

sonnet / 低思考  →  sonnet / 高思考  →  opus / 高思考

• 上限 R = 3（事不過三），且付得起。
• 同一層升到頂還不行 → 升級給上一層。
• 升級給人的條件：重試耗盡 或 問題出在計畫本身（這時應該由人重新給方向）。

八、果子離開樹：push 接縫 → 進果園

樹在本地長完、人驗收後，果子才離開樹、跨進 GitHub 工作流（果園）。時間軸：

🌱 開 feature/<tree> 分支              ← 一棵樹 = 一條分支
🌿🍃 樹生長（全程本地，不 push）：
     每支枝通過幹的檢核 → 幹在分支逐枝 commit 該枝果子
     並行沿「不同檔」的乾淨接縫切，避免互撞
🪵 樹長完 → 幹匯總 → 根翻白話 → 人
🟫 人驗收：
   ✅ 接受 → 貼 changeset 便利貼（驗收後才貼）→ commit changeset
           → push  ←━━ 唯一接縫，跨進果園（GitHub 工作流）
   ❌ 退回 → 砍樹 / 重種，不 push、不貼 changeset（零對外副作用）

三條鐵則：

1. commit 在本地、逐枝（由幹做，過程中絕不 push）。
2. push = 唯一接縫：push 前整棵樹本地可砍可重種、零對外副作用；push 後果園機械（CI / bot / deploy）才啟動 → 故用「人驗收」當 push 的閘。
3. changeset 嚴格在「人驗收後」貼，每個 PR 一張真便利貼，不接受空 changeset。

九、人（土壤）的操作指南

你是土壤。整套方法裡，你只需要做四件事：

1. 給方向：把「想要什麼」「為什麼」講清楚給根（與你對話的 AI）。不用講「怎麼做」—— 那是樹的事。
2. 回應開場雙問：根可能會問「這任務會不會超過 64 葉？切得開嗎？」。若它建議拆成多棵樹，照建議多開幾個對話，一棵一棵種。
3. 驗收果子：樹長完後，根會用白話跟你報告做了什麼、達標沒。你只看結果對不對、要不要的就是這個，不用檢查它中間怎麼拆怎麼試。
   • ✅ 接受 → 授權貼 changeset + push（進果園）。
   • ❌ 不對 → 退回。樹還沒 push，砍掉重種零副作用。
4. 出貨拍板：果子進果園、跑完 5-phase 到 main 後，production deploy 的那一下由你按（見 工作流程規範 Phase 5）。

十、與「工作流程規範」的關係

主題	在哪份文件
怎麼把大任務拆解、調度、執行、蒸餾、重試（做事）	✅ 本文（樹狀編排）
commit / push / changeset / CI / 部署 / 5-phase（出貨）	→ 工作流程規範
repo 分支保護、Lib vs App 流程差異、緊急回滾	→ 工作流程規範
新 repo 建置 SOP	→ Repo 建置與設定

一句話分工：樹 = 本地端「怎麼把事做好」；果園 = GitHub 端「怎麼把成果檢驗出貨」。兩者在 push 這個接縫交接。

版本與維護

• v0.1.0（初版 / research preview）：經 grill 拷問收斂後落地。後續隨真實任務遇到的問題再優化。
• 同步來源（source of truth）：給 AI 看的定稿在 .claude submodule 的 skills/tree-orchestration/（做事）與 skills/orchard/（出貨）。本文是給人看的同一套方法論，改動需兩邊同步。