sd0x-dev-flow

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

Claude Code를 위한 harness 레이어.

AI가 건너뛸 수 없는 품질 게이트. Claude Code를 위한 AI Agent Harness Engineering의 reference implementation — hook 강제 듀얼 리뷰, context 압축 이후에도 유지되는 state machine 게이트, 그리고 정말 중요한 지점의 fail-closed 안전장치.

96 bundled · 96 public skills · 15 agents — Claude context window의 ~4%만 사용

이 harness가 하는 일

Harness engineering은 LLM 모델 자체를 학습시키는 것이 아니라, LLM 주변의 모든 것 — tool loop, context 관리, hook, 상태 머신, 안전 레이어 — 을 엔지니어링하는 분야입니다. Mitchell Hashimoto가 2026년 2월에 이 용어를 만들었고, Anthropic engineering과 Martin Fowler가 이를 주제로 글을 발표했으며, arXiv 2603.05344가 이를 형식화합니다.

sd0x-dev-flow는 그 reference implementation입니다. 아래 각 행은 harness의 표준 하위 문제를 실제로 연구할 수 있는 코드에 매핑합니다:

대부분의 harness 프로젝트는 이 중 2~4개만 다룹니다. sd0x-dev-flow는 10개 모두를 다루므로, 단순한 도구가 아니라 연구 대상으로서의 코드로 활용할 수 있습니다.

왜 sd0x-dev-flow인가?

빠른 시작

# 플러그인 설치
/plugin marketplace add sd0xdev/sd0x-dev-flow
/plugin install sd0x-dev-flow@sd0xdev-marketplace

# 프로젝트 설정
/project-setup

하나의 명령어로 프레임워크, 패키지 매니저, 데이터베이스, 엔트리포인트, 스크립트를 자동 감지합니다. Rules와 Hooks의 서브셋을 설치합니다. 전체 플러그인에는 14개 Rules + 9개 Hooks가 포함됩니다.

--lite로 CLAUDE.md만 설정 (Rules/Hooks 스킵).

작동 원리

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"]

Auto-Loop 엔진이 품질 Gate를 자동으로 적용합니다. 코드 편집 후 리뷰 명령어가 듀얼 리뷰(Codex MCP + 보조 리뷰어 병렬 실행)를 디스패치합니다. Findings는 중복 제거, 심각도 정규화 후 단일 gate로 집계됩니다. strict 모드에서 Hooks는 fail-closed를 강제합니다: 집계 gate가 미완료이면 stop-guard가 차단합니다. 자세한 내용은 docs/hooks.md 참조.

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

    D->>C: Edit code
    H->>H: Track file change
    C->>H: emit-review-gate PENDING
    par Dual Review
        C->>X: Codex review (sandbox)
    and
        C->>T: Task(code-reviewer)
    end
    X-->>C: Findings (primary)
    T-->>C: Findings (secondary)
    C->>C: Aggregate + dedup + gate
    C->>H: emit-review-gate READY/BLOCKED

    alt Issues found
        C->>C: Fix all issues
        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

기능 하이라이트: 듀얼 리뷰어 아키텍처

v2.0은 두 개의 독립적인 리뷰어를 병렬로 디스패치합니다 — 단일 장애점 제로:

Findings는 심각도 정규화 (P0-Nit), 중복 제거 (파일 + 이슈 키, ±5줄 허용), 소스 귀속 (codex | toolkit | both)됩니다.

Gate: ✅ Ready 또는 ⛔ Blocked — strict 모드에서, 미완료 gate = blocked.

비교표

사용 시나리오

설치

Codex CLI / 기타 AI 에이전트

# Agent Skills 표준으로 개별 스킬 설치
npx skills add sd0xdev/sd0x-dev-flow

# AGENTS.md 생성 + hooks 설치 (Claude Code 내에서 실행)
/codex-setup init

요구 사항: Claude Code 2.1+ | Codex MCP（선택 — /codex-* skill에 필요; 미설치 시 싱글 리뷰어 모드로 폴백）

워크플로 트랙

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

쿡북

어떤 스킬을 어떤 순서로 조합하면 좋은지 보여주는 실전 시나리오입니다.

전체 10개 시나리오 →

포함 내용

최소한의 Context 사용량

Claude의 200k context window 중 ~4%만 사용합니다. 나머지 96%는 코드에 활용할 수 있습니다.

Skills는 온디맨드로 로드됩니다. 미사용 Skills는 토큰을 소비하지 않습니다.

스킬 레퍼런스

규칙 & Hook

14개 규칙 (상시 로드 컨벤션) + 9개 Hook (자동 가드레일).

커스터마이징: auto-loop-project.md를 편집하여 프로젝트별 auto-loop 동작을 오버라이드할 수 있습니다. 플러그인 업데이트와 충돌하지 않습니다 — Rule Override Pattern 참조.

전체 규칙, Hook, 환경 변수 레퍼런스는 docs/rules.md와 docs/hooks.md를 참조하세요.

커스터마이즈

/project-setup으로 모든 placeholder를 자동 감지/설정하거나, .claude/CLAUDE.md를 직접 편집하세요:

쇼케이스: 멀티 에이전트 리서치

/deep-research를 실행하면 2-3개의 병렬 리서치 에이전트가 웹 소스, 코드베이스, 커뮤니티 지식을 횡단 조사합니다 — claim registry 통합과 조건부 적대적 디베이트를 지원합니다.

전체 문서

아키텍처

Command (진입점) → Skill (기능) → Agent (실행 환경)

• Commands: 사용자가 /...로 실행
• Skills: 요청 시 로드되는 지식 베이스
• Agents: 전용 도구를 가진 격리된 서브에이전트
• Hooks: 자동화 가드레일 (포맷팅, 리뷰 상태, 스톱 가드)
• Rules: 항상 활성화된 컨벤션 (자동 로드)

고급 아키텍처에 대한 자세한 내용(agentic control stack, 제어 루프 이론, 샌드박스 규칙)은 docs/architecture.md를 참고하세요.

기여

PR 환영합니다. 다음 사항을 지켜주세요:

1. 기존 네이밍 컨벤션 준수 (kebab-case)
2. 스킬에 When to Use / When NOT to Use 포함
3. 위험한 작업에는 disable-model-invocation: true 추가
4. 제출 전 Claude Code로 테스트

라이선스

MIT

Star History