ce-code-review

Code Review

使用動態選擇的審查者角色 (reviewer personas) 來審查程式碼變更。本 Skill 會分派具備明確邊界的專家子 Agent (subagent) 並回傳結構化 JSON，接著將審查發現合併與去重，統整為單一報告。

Setup

請在本次呼叫開頭、分派任何子 Agent 之前執行此初始化指令一次，並遵循其印出的指令 — 除非該指令與本 Skill 自身關於「向使用者提問」的規則相衝突（無論該規則是作用於非互動模式或適用於所有模式），此時一律以本 Skill 的規則為準，不得提出任何阻塞式問題。請勿在同一次呼叫中重複執行；後續若呼叫此 Skill 或其他 Skill，均會自行執行各自的初始化。若環境中沒有 Node 執行階段，本 Skill 將按正常流程繼續執行。

SKILL_DIR="<absolute path of the directory containing the SKILL.md you just read>";
NODE="$(for c in node nodejs; do command -v "$c" >/dev/null 2>&1 && "$c" -e '' >/dev/null 2>&1 && { echo "$c"; break; }; done)";
if [ -n "$NODE" ]; then
"$NODE" "$SKILL_DIR/scripts/context.mjs" || echo "context script failed; continue with the skill's normal behavior";
else
echo "no Node runtime; continue with the skill's normal behavior";
fi

When to Use

• 建立 PR 之前
• 迭代開發過程中完成某項任務之後
• 需要對任何程式碼變更取得回饋時
• 可獨立直接呼叫
• 可在更大的工作流程中執行；當呼叫方需要 JSON 而非 Markdown 表格時，請使用 mode:agent

Artifact Root

本 Skill 會在 <root>/plans/ 下尋找計畫，在 <root>/solutions/ 下掃描學習心得，並將解析出的根目錄傳遞給 review-scope.py (--docs-root) 以及各個 Persona 子 Agent。在首次組合 <root>/ 路徑或 --docs-root "<root>" 引數前（依據下方區塊），請先解析出 <root>，並在所有出現該路徑的地方進行替換。

<!-- ce-docs-root:start -->
在組合任何產物路徑之前，請先解析 CE 產物根目錄 <root>。

• 讀取 <repo-root>/.compound-engineering/config.local.yaml 中的 docs_root，若無則讀取 config.yaml；以第一個非空值為準 (<repo-root> = git rev-parse --show-toplevel)。若皆未設定 -> <root> 預設為 docs（與先前完全相同）。
• 驗證 已設定的值：必須是相對於儲存庫的目錄，且解析符號連結後的真實路徑需保持在儲存庫內部，既不能是儲存庫根目錄，也不能位於 .git/ 下。否則請停止執行並回報包含 docs_root 及其設定值的錯誤訊息 — 切勿退回使用 docs。
• 使用 <root> 作為唯一的產物存放位置：若不存在請建立該目錄，並將所有路徑組合成 <root>/<subdir>（搭配本 Skill 專屬的子目錄），切勿同時讀取 docs。
  <!-- ce-docs-root:end -->

Execution spine

請依序遵循以下步驟邊界；參考文件僅提供細節說明，絕不可改變執行順序：

1. 解析待審查的 diff 內容與審查意圖。
2. 讀取 references/persona-catalog.md，接著根據風險導向選擇審查者名單，並尋找適用的規範路徑。未載入該目錄前，切勿選擇或分派任何 Persona。
3. 當針對本地端待審查程式碼樹選定對立性審查 (adversarial) 時，必須在分派任何本地 Persona 之前啟動並持久化獲准的跨模型任務 (cross-model job)。呼叫本 Skill 即代表授權其已設定/列入白名單的對等路由 (peer route)（需先揭露必要的接收者與程式碼出境資訊）；切勿要求第二次確認，也不可僅因使用者未單獨重複授權就跳過。若使用者明確禁止外部審查，則仍以使用者的禁止為準。已啟動的對等模型將取代本地對立性 Persona；只有在範圍、白名單、可用性、身分驗證或啟動確實失敗時，才退回使用本地備用方案。
4. 在進行任何本地分派前，讀取 references/dispatch-reviewers.md；若未載入，請停止並載入它。接著將實體化的本地審查名單作為前景並行批次進行分派，批次大小受限於宿主主機的活躍 Agent 上限 — 在 Harness 支援同訊息並行呼叫的情況下，於停用背景執行的單一訊息中發起多個審查者，並在統整分析前收集所有審查者的結果（在 Claude 風格的 Harness 上進行一次阻塞式等待；在非同步 spawn_agent 風格的 Harness 上進行多次非輪詢式的收集等待）；若不支援並行則降級為序列執行。禁止將本地審查拆分為輪詢式的背景任務；跨模型對等任務是唯一允許分離的作業，且與此批次重疊執行。禁止使用 Shell 空指令 (no-op) 和喚醒輪詢。
5. 當審查者的回傳結果準備就緒後，讀取 references/finish-review.md；若未載入，請停止並載入它。併入對等模型結果一次，執行文件記載的審查發現機制，執行參考文件選定的每個驗證器，最後才輸出報告。切勿直接從原始審查者產物進行統整。必須完整填寫「可行動的審查發現 (Actionable Findings)」、「覆蓋範圍 (Coverage)」與「最終裁決 (Verdict)」等完成欄位。若執行了對等模型審查，Coverage 必須記錄其路由以及產物中字面上的鍵值欄位：model_requested、model_actual、effort_requested、effort_actual、receipt_supported 與 independence_verified；切勿將此元組簡化為模型家族或模糊的「高推理能力」聲明。在多 Agent 路徑中，僅輸出本 Skill 的報告；請勿另外呼叫 Harness 原生的審查發現/報告工具。原生審查工具僅適用於明確的「快速審查簡化流程 (Quick Review Short-Circuit)」。純審查與 mode:agent 模式絕不套用修復；只有明確指定 apply:local 才能進入套用階段。

階段參考文件中隨附的輔助合約具權威性。請直接執行文件記載的指令；除非記載的指令確實因不相容而失敗，否則切勿檢查輔助程式碼來源、Grep 模型對映、預演適配器或探查 --help。

Task Visibility

對於多 Agent 路徑，一旦確定審查範圍，在平台支援任務追蹤功能時，請顯示由執行主軸衍生出的簡短使用者導向視圖。請追蹤審查結果，而非個別 Persona、設定機制或工具呼叫；僅在條件式工作的觸發條件生效時才新增該工作，並在關鍵過渡節點更新視圖。若無可用任務追蹤功能，請直接繼續進行正常的進度報告與最終報告，切勿在聊天中模擬任務清單。

Argument Parsing

解析呼叫本 Skill 時傳入的引數以取得可選 Token。在將剩餘文字解析為 PR 編號、GitHub URL 或分支名稱之前，請先去除每個已識別的 Token。

Token	範例	效果
mode:agent	mode:agent	僅輸出報告：回傳 JSON 而非 Markdown 表格，並跳過階段 5c 的套用（由呼叫方進行套用）。不會改變審查者選擇、合併邏輯或範圍規則（參閱 Output format）
mode:headless	mode:headless	mode:agent 的已停用別名
mode:report-only	mode:report-only	已停用 — 忽略。 舊版的無產物模式；預設行為即為僅審查而不切換分支
apply:local	apply:local	明確授權階段 5c 將已驗證的審查發現套用到經審查的本地工作區。此為權限授權，而非輸出模式；純審查依然保持僅輸出報告。
base:<sha-or-ref>	base:abc1234 或 base:origin/main	當前工作區的 Diff 基準（明確指定；跳過自動 Base 檢測）
plan:<path>	plan:<root>/plans/2026-03-25-001-feat-foo-plan.md	用於需求驗證的計畫檔案（明確指定）。支援 Markdown 及 HTML 整合計畫。
depth:full	depth:full	強制使用完整審查者名單 — 跳過階段 3c 的小量 Diff 輕量路徑，無論 Diff 大小為何，均執行每個常駐 Persona。當明確要求進行深入/徹底審查時使用（這是階段 3c 無法從 Diff 中推斷的唯一升級訊號）。不改變條件式選擇、合併或範圍。
depth:auto	depth:auto	預設 — 透過階段 3c 自行調整規模（對微不足道、低風險且僅限程式碼的 Diff 使用輕量名單；其餘情況使用完整名單）。
grouping:auto	grouping:auto	預設 — 當審查發現涵蓋不同關注點時建立主題分類群組（階段 5 步驟 9b）
grouping:off	grouping:off	隱藏分類群組：不顯示 Triage Groups 區塊，JSON 中的 triage_groups 為空
grouping:always	grouping:always	即使是小型審查，也始終建立分類群組

Grouping 屬於呈現方式，而非運作模式。 grouping: Token 僅改變審查發現集合在分類時的組織方式 — 絕不改變審查者選擇、合併邏輯、範圍規則或階段 5c 的套用決策。

模式別名： mode:headless 會正規化為 mode:agent。同時傳入 mode:agent + mode:headless 不算衝突。

衝突引數： 當出現以下情況時，請停止執行且不要分派審查者：

• 同時出現多個不相容的範圍選擇器（例如 base: 搭配 PR 編號/分支目標 — base: 代表「針對此 Base 審查當前工作區」）
• 除了 mode:agent/mode:headless 別名組合之外，同時出現多個不同的 mode: Token
• apply:local 與 mode:agent 同時出現 — 管線接力 (pipeline handoff) 永遠只能是僅輸出報告
• 同時出現多個不同的 grouping: Token（例如 grouping:off 與 grouping:always）

已廢棄的 mode:autofix 不屬於 衝突 — 請忽略該 Token 並按正常流程繼續進行（參閱下文）。

輸出單行的失敗原因。在 mode:agent 模式下，回傳 JSON：{"status":"failed","reason":"..."}。

Operating principles

預設模式與 mode:agent 採用相同的審查管線：

• 預設僅輸出報告；絕不 Push。 單純呼叫 ce-code-review 僅會產生審查發現，不會套用修復。本地變更需要傳入 apply:local 或在呼叫提示詞中明確要求套用/修復本次審查的發現。mode:agent 絕不修改程式碼樹，即使嵌套在後續會套用發現的工作流程中亦然。在任何模式下均不得 Push、建立 PR 或開單 (file tickets)。
• 無阻塞式提示。 切勿使用 AskUserQuestion、request_user_input、ask_user 或其他阻塞式提問工具。請從明確的 Token、Git 狀態、PR 中元資料及對話中推斷意圖、計畫與範圍。在覆蓋範圍或裁決中註明不確定之處 — 請勿停下來提問。
• 僅限明確的分支與變更操作。 切勿執行 gh pr checkout、git checkout、git switch 或類似的分支切換指令。傳入 PR 編號、URL 或分支名稱僅代表選擇審查範圍，而非取得修改工作區的權限。若要審查 Feature 分支上本地未 Commit 的工作，請自行切換到該分支（或保持在該分支上）並傳入 base: 或不傳入目標。
• 智慧預設值。 未追蹤的檔案：僅審查已追蹤的變更，並在 Coverage 中列出排除的路徑。計畫 (Plan)：傳入 plan: 時使用該路徑；否則保守地從 PR 內文或分支關鍵字尋找。僅因測試/可維護性所產生的弱建議性 P2/P3：依據階段 5 降級為 testing_gaps / residual_risks。
• 回報結果，而非揭露內部機制。 向使用者展示的內容應著重於審查本身：正在審查什麼（PR/分支）、包含哪些覆蓋範圍以及各個條件式視角的單行理由、獨立的跨模型審查及其執行的模型，以及審查發現。請勿在面向使用者的文字中提及 Skill 的內部細節 — 模型層級指派、原始範圍模式代號 (local-aligned/pr-remote)、將 Diff 暫存至磁碟、載入 Persona 檔案、平行分派的帳務紀錄，以及您自身設定過程的逐步旁白。請使用使用者能識別的名稱（PR 編號、審查者關注點、對等模型），而非內部管道用語。這決定了您應該浮出水面或隱藏哪些內容；並非限定具體字眼 — 請使用您自己的語氣表達。

Output format

Invocation	Deliverable
Default	僅輸出報告的 Markdown（管道符號分隔的審查發現表格）+ Actionable Findings 摘要
Explicit local apply	相同的 Markdown 報告，加上經驗證的本地修復以及 Applied 區塊
mode:agent	單一