하네스 엔지니어링 위키

통합 하네스 설계안 — 베스트 오브 베스트

Properties1
tags하네스, 설계안, 통합, 베스트오브베스트

18 min read

통합 하네스 설계안 — 베스트 오브 베스트

한 줄 요약

7개 하네스를 10축으로 분석해, 각 축에서 “가장 강한 메커니즘”만 골라 끼운 이상적 AI 코딩 에이전트 설계도다. 목표는 3대 사고 — 거짓 “다 했어요”, 모호한 지시에 엉뚱한 코드, 위험한 명령 실행 — 을 구조적으로 불가능하게 만드는 조립 원리를 익히는 것.

채택의 원칙

채택 단위는 **“코드로 강제되는 메커니즘”**이지 슬로건이 아니다. “어떤 하네스가 1등인가”가 아니라 *“그 1등을 만든 부품이 무엇인가”*를 고른다. 비교 대상 7종: Claude Code · Codex · OMC · gajae-code · ouroboros · fable-ish · 내 패턴.

그림

요구 → 검증 → 다음 세대 개선까지의 전체 생명주기다. 빨간 관문 2개(시작·끝)와 초록 봉인 1개(실행 중)가 토대, 나머지는 그 위의 증폭기다.

flowchart TB
    subgraph INTAKE["① 시작 관문"]
        U[사용자 요구] --> DI["딥 인터뷰<br/>모호성 점수 ≤ 0.2 통과 전 실행 차단"]
        DI -->|통과| SEED["불변 Seed 스펙<br/>단일 진실원천 SSoT"]
        DI -->|모호함| U
    end

    SEED --> ORCH

    subgraph ORCH["② 오케스트레이션"]
        CL["Claude 지휘자<br/>게이트·적대검증"]
        CL -->|변환할 타깃만 주입| WK["Codex 일꾼<br/>격리된 쓰기"]
        CL --> TM["팀 워크트리<br/>병렬 격리"]
    end

    WK --> TOOL["③ 도구 파이프라인<br/>등록소→라우터→실행면"]
    TM --> TOOL
    TOOL --> GUARD

    subgraph GUARD["④ 4중 가드레일 실행 봉인"]
        G1[OS 샌드박스] --> G2[실행정책] --> G3[정적 판정] --> G4["LLM 경비원<br/>실패시 차단"]
    end

    GUARD --> VERIFY

    subgraph VERIFY["⑤ 검증 관문"]
        EV["증거 계약<br/>텍스트 아닌 증거 객체"] --> COV["커버리지 확인<br/>그 파일 진짜 건드림?"]
        COV --> CR["비평가 적대검증<br/>자체승인 금지"]
        CR --> RC["sha256 영수증<br/>실패시 차단·exit 2"]
    end

    VERIFY --> STATE["⑥ 영속<br/>이벤트소싱·SQLite·위키"]
    STATE --> IMPROVE

    subgraph IMPROVE["⑦ 자기개선"]
        REFL[reflect 루프] --> TOUR["토너먼트 진화<br/>평가자 부정 차단"]
        HOOK["훅 자동생성<br/>즉시 적용"]
    end

    IMPROVE -.다음 세대 Seed.-> SEED
    HOOK -.런타임 규칙.-> GUARD

    classDef gate fill:#fdd,stroke:#c00,stroke-width:2px
    classDef safe fill:#dfd,stroke:#080,stroke-width:2px
    class INTAKE,VERIFY gate
    class GUARD safe

읽는 법: 빨간 블록(시작·검증)은 통과 못 하면 다음으로 못 가는 관문, 초록 블록(가드레일)은 실행 중 행위를 가두는 봉인, 점선은 피드백 루프다.

쉽게 풀기

AI 에이전트를 “신입 외주 개발자 한 명”으로 보면 쉽다. 일을 맡길 때 본능적으로 거는 안전장치를 코드로 자동화한 것이 이 설계다.

막으려는 3대 사고

  • 거짓 완료: “검증 다 했어요” 말만 믿었는데 실제론 안 한 경우.
  • 막연한 시작: 요구가 흐릿한데 일단 코드부터 쓴 경우.
  • 컨텍스트 오염: 대화가 길어질수록 누적 잡음이 판단을 흐리는 경우.

이 3대 사고가 7단계 봉인으로 어떻게 막히는지, 그 흐름은 이렇다.

flowchart LR
    A["①계약서 먼저<br/>(모호성 게이트+Seed)"] --> B["②책상 정리<br/>(fresh exec)"]
    B --> C["③역할 분리<br/>(지휘자/일꾼)"]
    C --> D["④단일 출입구<br/>(도구 파이프)"]
    D --> E["⑤겹겹 자물쇠<br/>(4중 가드레일)"]
    E --> F["⑥실물 영수증<br/>(검증 관문)"]
    F --> G["⑦기억과 성장<br/>(영속+진화)"]
    G -.경험 환류.-> A
단계비유핵심
① 시작 관문계약서 먼저모호성 ≤0.2 전엔 착수 차단, 합의는 못 바꾸는 Seed로 박음
② 컨텍스트 엔진책상 정리작업당 1회 실행·누적 0, 시스템 지시문 동결(캐시 적중), 압축 전 메모 flush
③ 오케스트레이션역할 분리Claude=지휘자, Codex=일꾼, 모델 경계가 방화벽, 일꾼엔 “고칠 대상”만 주입
④ 도구 파이프라인단일 출입구모든 도구가 등록소→라우터→실행면 한 줄 통과, 검문소는 하나
⑤ 4중 가드레일겹겹 자물쇠OS샌드박스→명령분해→정적판정→LLM경비원, 헷갈리면 차단(fail-closed)
⑥ 검증 관문실물 영수증증거 객체+커버리지+비평가 적대검증+sha256, 못 맞으면 exit 2
⑦ 영속+자기개선기억과 성장이벤트소싱 복원 + 토너먼트 진화 + 불만 신호→재발방지 훅 자동생성

핵심 정리

3대 실패와 봉인

실패 패턴봉인 메커니즘
거짓 완료 (fable-ish, ralph, OMC)증거 계약 + sha256 영수증 + 자체승인 금지
막연한 시작 (단일 에이전트 일반)모호성 게이트(≤0.2 통과 전 차단)
컨텍스트 오염 (장기 세션)fresh exec + StablePrefix + PreCompact flush

왜 충돌 없이 합산되나

직교하는 부품만 골랐기 때문이다. 같은 위협을 서로 다른 차원에서 덮으면 겹치지 않고 곱해진다.

flowchart TB
    subgraph CTX["컨텍스트 4부품 = 4차원 분담"]
        c1["공간·캐시"] --- c2["오염·누적0"] --- c3["손실·압축보존"] --- c4["시간·재현"]
    end
    subgraph GRD["가드레일 4중 = 독립 레이어의 곱"]
        g1[OS] --> g2[정책] --> g3[정적] --> g4[LLM]
    end
    subgraph VFY["검증 4부품 = 누수 3종 차단"]
        v1["자기보고→증거"] --- v2["자기승인→critic"] --- v3["미반영→coverage"]
    end
    OPEN["개방 vs 통제 모순<br/>정의는 자유·실행은 단일게이트"]

채택하지 않은 것 (안티-패턴)

  • fable-ish fail-open(훅 예외 시 exit 0) → fail-closed로 뒤집어 채택
  • OMC 짧은 timeout + {continue:true} → 타임아웃 길게, 실패 시 차단
  • Codex OpenAI 생태계 종속 → provider 어댑터로 모델 중립 유지
  • 거대 사양 복잡도(gajae 수백 줄, ouroboros 926 py) → “코드로 강제·프롬프트는 짧게” 정신만
  • ralph promise 자기신고 종료 → 다중신호 수렴(진화 0회면 수렴 거부)으로 대체

실제 예시

내 환경에서 현실적으로 구현 가능한 버전

제약: 실제로 쓰는 것은 Claude Code(호스트) + Codex(워커) + OMC(디스트리뷰션) 3종뿐. ouroboros/gajae의 Rust 크레이트·이벤트소싱·Starlark·OS 샌드박스 자체구현은 이식 비용이 비현실적. 따라서 그 정신을 기존 3종의 표면으로 근사한다.

이상안 메커니즘내 환경 대응물액션
모호성 게이트OMC /deep-interview비자명 작업 진입 의무화(ralplan)
불변 Seed SSoT헌법형 SSoT 문서.omc/SEED.md 고정, 직접편집 금지
증거+critic 분리OMC critic+/verify+gate.mjs자체승인 금지 게이트 의무 경유
sha256 영수증내 패턴 영수증 회로gate.mjs에 canonical-JSON sha256, exit 2
이중모델 분업운영 중(Claude=게이트, Codex=워커)edge-map 타깃 주입 규약 문서화
이벤트소싱 lineageOMC state_*+session_searchtrace_timeline로 근사
LLM Wiki 메모리OMC wiki_*+MEMORY.mdsupersedes 보존(valid_to) 규약
토너먼트 진화OMC /self-improve하네스 규율 개선에 주기 적용
hookify 런타임 규칙settings.json hooks(미활용)최대 갭 — 아래 참조

가장 큰 갭 = 하네스 레벨 자동 강제. 내 패턴의 핵심 약점은 “규율이 산문에 의존, settings.json에 차단 훅이 전무”였다. 단일 최고 레버리지 액션은 비어 있는 settings.json 훅을 채우는 것.

현실판 아키텍처 (3종으로 근사)

flowchart LR
    U[요구] --> RP["OMC /ralplan<br/>= 시작 게이트"]
    RP --> SEED[".omc/SEED.md SSoT"]
    SEED --> CL[Claude 오케스트레이터]
    CL -->|edge-map| CX[Codex 워커]
    CX --> HK["settings.json hooks<br/>PreToolUse 차단<br/>= 가드레일 근사"]
    HK --> VF["OMC critic + /verify<br/>+ gate.mjs sha256<br/>= 검증 폐루프"]
    VF -->|exit2 block| CL
    VF --> ST["OMC wiki + state<br/>= 영속"]
    ST -.주기.-> SI["OMC /self-improve<br/>= 진화"]
    SI -.규율 개선.-> SEED

구현 순서 (우선순위 백로그)

  1. [즉시·최대효과] settings.json 훅 3종(PreToolUse/Stop/PreCompact) — 산문 규율을 코드 강제로.
  2. [즉시] config.toml 전역 안전 조임 + trusted 경로 축소.
  3. [단기] gate.mjs에 sha256 canonical 영수증 + critic 의무 경유 회로.
  4. [단기] 비자명 작업 /deep-interview//ralplan 진입 의무화.
  5. [중기] wiki supersedes 보존(valid_to) + state_* 기반 lineage 근사.
  6. [중기] Codex 단일계정 단일장애점 완화 — refresh_token 자동갱신 + 대량생성 watchdog.
  7. [장기] /self-improve를 하네스 규율 자체에 주기 적용, sealed_files로 평가자 봉인.

요약 & 셀프체크

3줄 요약:

  • 시작(모호성 게이트)·실행(4중 가드레일)·완료(증거+영수증+critic)의 세 봉인이 토대, 나머지는 그 위의 증폭기다.
  • 채택 단위는 슬로건이 아니라 코드로 강제되는 메커니즘이며, 직교 부품만 골라야 충돌 없이 합산된다.
  • 내 환경에서 이상안의 90%는 새 도구가 아니라 이미 깔린 OMC 스킬 + Claude Code 훅을 실제로 켜는 것으로 달성된다 — 최대 미실현 가치는 비어 있는 settings.json 훅 하나에 집중돼 있다.

스스로 답해보기:

  1. “검증 다 했어요” 한 줄을 통과시키지 않으려면 어떤 4개 부품이 동시에 필요한가? (증거 객체·커버리지·critic 분리·영수증)
  2. 가드레일은 왜 “가장 센 자물쇠 하나”가 아니라 “겹친 자물쇠”여야 하는가?
  3. 내 환경에서 단일 최고 레버리지 액션 하나는? 왜 그것인가?

연결

그래프 뷰

백링크