sd0x-dev-flow

語言: English | 繁體中文 | 简体中文 | 日本語 | 한국어 | Español

給 Claude Code 的 harness 層。

讓模型自己選路，讓「完成」可被驗證。

v4 讓 Claude 在一組封閉、由測試釘死的 anchor 集合內擁有裁量權；hooks 在 compaction 之後仍保留 gate 憑證，Codex 則獨立進行 review。

在 Claude Code 上提供完整 control plane；對 Codex CLI 與其他相容 agent 則以 skills-only 形式發佈。

96 bundled · 96 public skills · 15 agents — 僅佔 Claude context window 的 ~4%

快速開始

# Claude Code — 完整 control plane
/plugin marketplace add sd0xdev/sd0x-dev-flow
/plugin install sd0x-dev-flow@sd0xdev-marketplace

# 設定你的專案
/project-setup

一個指令自動偵測 framework、package manager、資料庫、entry point 和 script 指令。安裝部分 rules 與 hooks；完整 plugin 包含 15 條 rules + 8 個 hooks。使用 --lite 僅設定 CLAUDE.md（跳過 rules/hooks）。

# Codex CLI / Cursor / Windsurf / Aider — 僅 skills
npx skills add sd0xdev/sd0x-dev-flow

# 產生 AGENTS.md + 安裝 git hooks（在 Claude Code 內執行）
/codex-setup init

需求：Claude Code 2.1+ | Codex MCP（安裝 plugin 可不裝，但 /codex-* review gate 必須有——Codex 本身就是那位唯一的 reviewer，未安裝時 review 會直接輸出 ⛔ Blocked + ⚠️ Need Human，沒有可降級的對象）

為什麼是 v4

前沿模型已經能規劃、批次處理，並從結構化狀態中復原——它們不再需要 harness 指定下一步要執行哪個指令。v4 從編排（choreography）走向契約（contracts）：harness 不再替模型編排每一步動作，而是定義「宣告完成」時必須為真的條件，同時不放鬆任何一條安全或 review anchor。

不可協商的核心放在一個封閉的 Anchor Register（rules/discretion.md）裡，任何專案覆寫都無法將其降級——解析採 Anchor-first，而且移除任何一條 Register 條目都會讓測試套件刻意失敗。在這個邊界之內，所有權是明確的：

模型擁有路徑。Harness 擁有證據與不可協商的邊界。人類保留不可逆的權力。

這個 harness 做了什麼

Harness engineering 是一門工程學科,處理 LLM 周圍的所有東西 — tool loops、context management、hooks、state machines、safety layers — 而不是訓練模型本身。Mitchell Hashimoto 在 2026 年 2 月提出這個名詞;Anthropic engineering 與 Martin Fowler 都發表過相關文章;arXiv 2603.05344 則將其形式化。

sd0x-dev-flow 是一個 reference implementation。下表每一列都將一個經典的 harness 子問題對應到你可以實際研究的程式碼:

大多數 harness 專案只涵蓋其中的 2–4 項,sd0x-dev-flow 把 10 項全部做齊 — 這也是為什麼它的程式碼不只是工具,更值得當成學習對象。

運作方式

flowchart LR
    P["🎯 Plan"] --> B["🔨 Build"]
    B --> G["🛡️ Gate"]
    G --> S["🚀 Ship"]

    P -.- P1["/codex-brainstorm<br/>/feasibility-study<br/>/tech-spec"]
    B -.- B1["/feature-dev<br/>/bug-fix<br/>/codex-implement"]
    G -.- G1["/codex-review-fast<br/>/precommit<br/>/codex-test-review"]
    S -.- S1["/smart-commit<br/>/push-ci<br/>/create-pr<br/>/pr-review"]

一切繞著一條規則運轉——terminal completion invariant：唯有當某項改動的 change class 所需的每個 gate，都在該 class 的最後一次編輯之後通過，這項改動才能被宣告完成。程式碼編輯需要一次獨立的 Codex review，接著 /precommit；.md 文件需要 /codex-review-doc。何時執行、如何批次編輯、review 要多深，都是模型的決定——invariant 約束的是終點狀態，不是編排過程。

Hooks 回報的是事實，不是命令：它們發出 [AUTO_LOOP_STATE] 區塊（change class、gate 憑證、round/cap、tier），決定權在模型。什麼算 blocking 由 tier 決定（fast P0 · standard P0/P1 · thorough P0/P1/P2）；低於該門檻的 findings 只記錄下來，loop 繼續往前，不再多開一輪。觸及輪次上限會觸發結構化的自我診斷（架構問題？文件太長？注意力發散？）與一次有界調整，然後 loop 繼續——而不是自動交接；但 cap 專屬的人類出口仍然有效（安全性與資料完整性改動完全跳過診斷；被診斷為架構層級或需求歧義的停滯則交給人類）。

強制執行有兩種模式：

第二位 reviewer 走 /codex-review-branch --dual，預設不啟用。模式與相依細節詳見 docs/hooks.md。

sequenceDiagram
    participant D as Developer
    participant C as Claude
    participant X as Codex MCP
    participant H as Hooks

    D->>C: Edit code
    H->>H: Track file change
    C->>X: Codex review (sandbox, researches repo itself)
    X-->>C: Findings + gate sentinel
    H->>H: Parse sentinel into code_review.passed
    C->>C: Gate on the tier's blocking severity

    alt Blocking findings
        C->>C: Fix them (sub-threshold: log and move on)
        C->>X: --continue threadId
        X-->>C: Re-verify
    end

    C->>C: /precommit (auto)
    C-->>D: ✅ All gates passed

    Note over H: Strict mode: incomplete gate → blocked

功能亮點：分檔 Review

預設只有一位 reviewer——Codex。tier 決定一項改動要多嚴格，以及一個 finding 要多嚴重才會重開 loop：

設定的 tier 是底線，不是天花板——當改動的性質需要時，模型會往上升級；而安全性或資料完整性改動無論設定為何，一律以 thorough 進行 review。

80 分就是及格。 低於該 tier blocking 門檻的 findings 會被記錄（[NIT_DEFERRED]，帶 TTL 持久化，下次 session 不會重複被提），loop 直接進 /precommit——不多一次修正、不多一輪 review。這些項目會在 /codex-review-branch 做深度審查時被撿回來。

上表的輪次上限是各 tier 的預設值——專案的 ## Max Rounds 覆寫（3–50）優先。觸頂是一個診斷點，不是自動交接：模型會分類停滯原因（架構、文件太長、注意力發散、未驗證的宣稱、tier 不匹配、需求歧義），做一次有界調整後繼續。cap 專屬的人類出口仍然具約束力：安全性／資料完整性改動跳過診斷直接交給人類；被分類為架構層級或需求歧義的停滯會退出交給人類；同一改動在診斷後第二次觸頂也一律交給人類。（架構層級變更、功能移除、或使用者要求停止，在任何時點都會退出交給人類——無論是否觸頂。）

第二位 reviewer 走 /codex-review-branch --dual，不加旗標就不啟用——它讓每輪的 token 與時間成本翻倍，值得花在 release 或安全審查上，不值得花在日常修正。啟用 --dual 時，findings 會做嚴重度正規化、去重（file + issue key，±5 行容差）與來源標記。

Gate：✅ Ready 或 ⛔ Blocked — strict 模式下，未完成 gate = blocked。

適用場景

Workflow Tracks

flowchart TD
    subgraph feat ["🔨 Feature Development"]
        F1["/feature-dev"] --> F2["Code + Tests"]
        F2 --> F3["/verify"]
        F3 --> F4["/codex-review-fast"]
        F4 --> F5["/precommit"]
        F5 --> F6["/update-docs"]
    end

    subgraph fix ["🐛 Bug Fix"]
        B1["/issue-analyze"] --> B2["/bug-fix"]
        B2 --> B3["Fix + Regression test"]
        B3 --> B4["/verify"]
        B4 --> B5["/codex-review-fast"]
        B5 --> B6["/precommit"]
    end

    subgraph docs ["📝 Docs Only"]
        D1["Edit .md"] --> D2["/codex-review-doc"]
        D2 --> D3["Done"]
    end

    subgraph plan ["🎯 Planning"]
        P1["/codex-brainstorm"] --> P2["/feasibility-study"]
        P2 --> P3["/tech-spec"]
        P3 --> P4["/codex-architect"]
        P4 --> P5["Implementation ready"]
    end

    subgraph ops ["⚙️ Operations"]
        O1["/project-setup"] --> O2["/repo-intake"]
        O2 --> O3["Develop"]
        O3 --> O4["/project-audit"]
        O3 --> O7["/best-practices"]
        O3 --> O5["/risk-assess"]
        O4 --> O6["/next-step --go"]
        O5 --> O6
        O7 --> O6
    end

實戰指南（Cookbook）

真實情境示範——哪些技能要搭配使用、按什麼順序執行。

全部 10 個情境 →

包含內容

極小的 Context 佔用

~4% 的 Claude 200k context window——96% 留給你的程式碼。

Skills 按需載入。閒置 Skill 不佔用任何 Token。

技能參考

Rules & Hooks

15 條 rules + 8 個 hooks。Rules 是分層的契約：discretion.md 把 12 個 plugin 管理的 rule 檔中的每一條指示解析為 Anchor / Default / Guidance 三者之一，2 個使用者擁有的 override 檔則在其父規則之下以 Anchor-first 解析。Hooks 是事實發布者與護欄：它們記錄 gate 憑證並在 compaction 後重新注入狀態；stop-guard 在 strict 模式下阻擋 review 未完成的停止，pre-edit-guard 則在任何模式下拒絕敏感路徑的編輯。

客製化：編輯 auto-loop-project.md 可覆寫專案的 auto-loop 行為。Plugin 更新不會衝突 — 詳見 Rule Override Pattern。

完整的 rules、hooks 與環境變數參考，請見 docs/rules.md 與 docs/hooks.md。

自訂設定

執行 /project-setup 自動偵測並設定所有 placeholder，或手動編輯 .claude/CLAUDE.md：

覆寫採 Anchor-first 解析：使用者擁有的 override 檔（auto-loop-project.md、testing-project.md）只能客製 Default 與 Guidance 層級的行為——任何專案覆寫都無法降級 Anchor Register 中的條目，嘗試這麼做會被回報為衝突，而不是被接受。

展示：多 Agent 研究

執行 /deep-research 可調度 2-3 個並行研究 agent，跨越網路來源、程式碼庫與社群知識 — 搭配 claim registry 綜合與條件式對抗辯論。

完整文件

架構

六個層，每層各自擁有一項關注點：

進階架構細節（agentic control stack、控制迴圈理論、sandbox 規則）請參閱 docs/architecture.md——注意其中部分內容早於 v4，仍在描述 v3 的 choreography；rules/auto-loop.md 與 rules/discretion.md 才是目前的 source of truth。

貢獻

歡迎 PR。請：

1. 遵循現有命名慣例（kebab-case）
2. 在 skill 中包含 When to Use / When NOT to Use
3. 對危險操作加上 disable-model-invocation: true
4. 提交前用 Claude Code 測試

License

MIT

Star History