sd0x-dev-flow

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

给 Claude Code 的 harness 层。

让模型自己选路径。让「完成」可验证。

v4 在一个封闭、由测试钉住的 anchor 集合之内给予 Claude 自由裁量权；hooks 是与 digest 绑定、可跨 compaction 存续的提醒（reminders），Codex 独立审查。

完整控制平面运行在 Claude Code 上。对 Codex CLI 与其他兼容 agent 提供 skills-only 分发。

99 bundled · 99 public skills · 16 agents — 仅占 Claude context window 的 ~4%

快速开始

# Claude Code — 完整控制平面
/plugin marketplace add sd0xdev/sd0x-harness
/plugin install sd0x-dev-flow@sd0xdev-marketplace

# 配置项目
/project-setup

一个命令自动检测框架、包管理器、数据库、入口文件和脚本命令。安装部分 rules 和 hooks；完整插件包含 16 条 rules + 6 个 hooks。使用 --lite 仅配置 CLAUDE.md（跳过 rules/hooks）。

# Codex CLI / Cursor / Windsurf / Aider — 仅 skills
npx skills add sd0xdev/sd0x-harness

接着在 Codex CLI 中生成 AGENTS.md kernel 并安装 commit-msg hook。pre-push 守卫为 opt-in——要一并安装请加上 --with-push-gate：

$codex-setup init

环境要求：Claude Code 2.1+ | Node.js 18+ | jq（pre-edit-guard 与 post-edit-format 用它解析 hook payload——没有 jq 时两者都直接 exit 0，敏感路径防护与自动格式化等于悄悄关闭）| Codex MCP（安装 plugin 可不装；它是 /codex-* review gate 的默认 reviewer——Codex 不可用时，由契约感知的 fallback reviewer 以同一机制承接 gate，按 family contract fail-closed 并记录 [REVIEWER_FALLBACK]；只有当所有备用 reviewer 均无法给出有效判定时，review 才输出 ⚠️ Need Human 而非 verdict）

注册 Codex MCP

claude mcp add codex -- codex mcp-server -c 'model_reasoning_effort="high"'

-c 'model_reasoning_effort="high"' 是这里的默认值——review 正是值得投入深度的工作（rules/auto-loop.md § Review Dispatch 对 agents/ frontmatter 套用同一个原则）。它是默认值而非硬性要求，你可以按自己的 effort/latency 取舍调整或去掉。-c 放在 mcp-server 子命令前后都有效。

--profile 则完全无法与 codex mcp-server 并用，请直接在注册命令上用 -c 覆盖配置；完整错误信息见 English README。

为什么是 v4

前沿模型已经能规划、批处理，并从结构化状态中自行恢复——它们不再需要 harness 来指挥每一步下一条命令。v4 从编排（choreography）走向契约（contracts）：harness 不再为模型编排动作脚本，而是定义「宣告完成时必须为真的事」，且不放松任何一条安全或审查 anchor。

不可协商的核心放在一个封闭的 Anchor Register（rules/discretion.md）里，任何项目 override 都无法将其降级——解析以 Anchor 优先，且移除任何 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"]

一切都围绕一条规则——终态完成不变量：一项改动只有在其 change class 所要求的每一道 gate 都于该类的最后一次编辑之后通过时，才可以宣告完成。代码编辑需要一次独立的 review——默认由 Codex 执行，Codex 不可用时由通过验证的契约感知 fallback reviewer 承接——再加 /precommit；.md 文档需要 /codex-review-doc。何时执行、如何批处理编辑、审查多深，都是模型的决定——不变量约束的是终态，不是编排。

Hooks 报告的是事实，不是命令：它们打印提醒和一行 [AUTO_LOOP_STATE] 事实（change class、各 plane 的 verdict 状态），决策权归模型。什么算 blocking 由 tier 决定（fast P0 · standard P0/P1 · thorough P0/P1/P2）；低于该门槛的 findings 只记录下来，loop 继续往前，不再多开一轮。卡壳——连续三轮 review 没有关掉任何 finding，由模型自行计数——或作为兜底，触发轮次上限——会启动一次结构化自我诊断（架构问题？文档过长？注意力发散？）与一次有边界的调整，然后 loop 继续，而不是自动移交；无论由哪个 trigger 发动，人类出口都仍然有效（安全与数据完整性改动完全跳过诊断；被诊断为架构级或需求歧义的停滞交给人类）。

不存在强制执行模式（hook-lightweighting，2026-08-13）：每个审查层 hook 都是以 exit 0 结束的提醒。建立 verdict 的是 reviewer 的报告；模型再记录它（node scripts/review-state.js note <plane> <pass|fail>，与 digest 绑定——一次编辑会重新打开其 plane）让提醒退场。未被记录的 verdict 依然成立——只是提醒会一直响——而让提醒安静下来的诚实方式是把 gate 跑完并记录结果。审查层之外的守卫仍然保有约束力：pre-edit-guard 仍会阻断敏感路径编辑（需要 jq，缺 jq 时守卫不会启动），而已安装的 git 层守卫仍然是硬性的（commit-msg-guard 默认安装、pre-push-gate 为 opt-in）。

第二位 reviewer 走 /codex-review-branch --dual，默认不启用。Hook 与依赖详情见 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: Reminder state re-opens (digest changed)
    C->>X: Codex review (sandbox, researches repo itself)
    X-->>C: Findings + gate sentinel
    C->>C: note the verdict (review-state.js)
    C->>C: Gate on the tier's blocking severity

    alt Blocking findings
        C->>C: Fix them (sub-threshold: log and move on)
        alt R-a 阈值（3 次 reply；override 2–6）或 R-b 上下文过长
            C->>X: 在新 thread 上全新首次分派（冻结 baseline 随行）
            X-->>C: 全新报告
            C->>C: 在编排侧将旧 findings 对映到新报告并重新推导 gate
            C->>C: 记录 [THREAD_ROTATED]（old → new threadId）
        else 未达阈值
            C->>X: --continue threadId
            X-->>C: 重新验证
        end
        Note over C,X: 轮换保留冻结的 scope baseline；stall 连续计数与轮次上限不重置
    end

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

    Note over H: Stop: owed gates re-reminded — never blocked

功能亮点：分档 Review

默认只有一位 reviewer——Codex——在所有场景运行。tier 决定一项改动要多严格，以及一个 finding 要多严重才会重开 loop：

配置的 tier 是底线，不是上限——当改动值得时模型会升档，而安全或数据完整性改动无论配置为何，一律以 thorough 审查。

80 分就是及格。 低于该 tier blocking 门槛的 findings 会被记录（[NIT_DEFERRED]——review 报告中的一种报告惯例；没有任何东西会持久化它），loop 直接进 /precommit——不多一次修正、不多一轮 review。这些项目会在 /codex-review-branch 做深度审查时被捡回来。

上面的轮次上限是刻意放宽的，因为上限分不出正在收敛的循环和空转的循环——两者都停在同一个数字。能分出来的是证据：连续三轮 review 都没有关掉任何 finding——由模型根据 review 报告自行计数，通常比触发上限早很多轮——触发下面这套诊断。上限退居 runaway backstop。

上面的轮次上限是各 tier 的默认值——项目的 ## Max Rounds 覆写（3–50）优先。触发上限是一个诊断点，不是自动移交：模型对停滞做分类（架构、文档过长、注意力发散、未验证的断言、tier 不匹配、需求歧义），做一次有边界的调整，然后继续。无论由哪个 trigger 发动，人类出口都仍然有约束力：安全/数据完整性改动跳过诊断直接交给人类，被归类为架构级或需求歧义的停滞退出交给人类，同一改动在诊断后第二次触发上限也一律如此。（架构级变更、功能移除或用户要求停止，在任何时点都会退出交给人类——无论是否触发上限。）

第二位 reviewer 走 /codex-review-branch --dual，不加标志就不启用——它让每轮的 token 与时间成本翻倍，值得花在 release 或安全审查上，不值得花在日常修正。启用 --dual 时，findings 会做严重度正规化、去重（file + issue key，±5 行容差）与来源标记。

Gate：✅ Ready 或 ⛔ Blocked — 由模型据以行动的行为层信号；verdict 会被记录进提醒状态。

适用场景

工作流路径

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。

技能参考

规则与钩子

16 条规则 + 6 个钩子。规则是分层级的契约：discretion.md 把 13 个由插件管理的 rule 文件中的每条指令解析为 Anchor / Default / Guidance 三者中的确切一个，2 个用户自有的 override 文件则在其父规则之下以 Anchor 优先的方式解析。Hook 的组成是 4 个建议性提醒 hook，加上 1 个自动格式化与 1 个会阻断的安全守卫。提醒角色各不相同：Stop 与 post-compact hook 从与 digest 绑定的状态（review-state.js）打印待偿 gate 提醒，prompt hook 打印 [AUTO_LOOP_STATE] 事实行，post-skill hook 打印固定的 gate 顺序行，post-compact hook 另外重新注入 git 基线；审查层永不阻断——pre-edit-guard 仍会阻断敏感路径编辑（安全守卫，需要 jq，缺 jq 时不会启动），硬性 gate 位于 git 层（commit-msg-guard 默认安装；pre-push-gate 为 opt-in）。

定制化：编辑 auto-loop-project.md 可覆写项目的 auto-loop 行为。插件更新不会冲突 — 详见 Rule Override Pattern。

完整的规则、钩子与环境变量参考，请见 docs/rules.md 与 docs/hooks.md。

自定义配置

运行 /project-setup 自动检测并配置所有占位符，或手动编辑 .claude/CLAUDE.md：

Override 以 Anchor 优先解析：用户自有的 override 文件（auto-loop-project.md、testing-project.md）只能定制 Default 与 Guidance 层级的行为——任何项目 override 都无法降级 Anchor Register 中的条目，尝试这样做会被报告为冲突，而不是被采纳。

展示：多 Agent 研究

执行 /deep-research 可调度 2-3 个并行研究 agent，跨越网络来源、代码库与社区知识 — 搭配 claim registry 综合与条件式对抗辩论。

完整文档

架构

六个层，每层只负责一件事：

高级架构详情（agentic control stack、控制回路理论、沙箱规则）参见 docs/architecture.md——注意其中部分内容早于 v4，仍在描述 v3 的 choreography；当前的事实来源是 rules/auto-loop.md 与 rules/discretion.md。

贡献

欢迎 PR。请：

1. 遵循现有命名规范（kebab-case）
2. 在技能中包含 When to Use / When NOT to Use
3. 对危险操作添加 disable-model-invocation: true
4. 提交前用 Claude Code 测试

许可证

MIT

Star History