하네스 엔지니어링 위키

5. ouroboros

Properties2
tags프레임워크분석, ouroboros
aliasesouroboros, Q00/ouroboros, ouroboros-ai, Spec-driven Agent OS

14 min read

5. ouroboros

한 줄 요약

ouroboros는 막연한 아이디어를 소크라테스식 인터뷰 → 불변(immutable) Seed 스펙 → Double-Diamond 실행 → 3단계 평가 → 진화 루프로 돌려 “검증된 코드베이스”로 바꾸는 로컬 우선(local-first)·이벤트소싱 기반의 Agent OS다.

왜 배우나: “프롬프트 한 번 → 결과 한 번”의 한계를 넘어, 무엇을 만들지 명확해질 때까지 캐묻고 → 만들고 → 채점하고 → 스스로 고치기를 반복하는 자기개선 골격이 어떻게 코드로 구현되는지 보여주는, 에이전트 하네스의 종합 교본이기 때문이다.

그림

아래는 보조 흐름도다. 이름 그대로 자기 꼬리를 먹는 뱀(우로보로스) = 평가 결과가 다음 세대의 입력이 되는 자기개선 루프가 핵심이다.

flowchart TD
    A["아이디어<br/>(막연함)"] --> B["1. 소크라테스 인터뷰<br/>bigbang"]
    B --> G1{"Ambiguity 게이트<br/>1 - Σ(clarity·weight) ≤ 0.2 ?"}
    G1 -- "아직 모호함" --> B
    G1 -- "충분히 명확" --> C["2. 불변 Seed 스펙<br/>(YAML 단일 진실원천)"]
    C --> D["3. Double-Diamond 실행<br/>오케스트레이터·병렬·증거검증"]
    D --> E["4. 3단계 평가<br/>Mechanical → Semantic → Consensus"]
    E --> F["5. reflect 진화<br/>평가결과 → 다음 세대 Seed"]
    F --> G2{"수렴 게이트<br/>similarity ≥ 0.95 / 정체 / 최대 30세대 ?"}
    G2 -- "아직 진화 중" --> D
    G2 -- "안정됨" --> H["검증된 코드베이스"]
    subgraph 영속성["이벤트소싱 코어 (~/.ouroboros/ouroboros.db)"]
        Z["모든 상태를 불변 이벤트로 적재<br/>→ replay·resume·lineage"]
    end
    D -.기록.-> Z
    E -.기록.-> Z
    F -.재구성.-> Z

쉽게 풀기

비개발자를 위해 단계별로 풀어보자. ouroboros를 **“까다롭지만 일 잘하는 건축 사무소”**라고 생각하면 쉽다.

  1. 묻고 또 묻기 (인터뷰) — 보통 AI 도구는 “집 지어줘” 한 마디에 바로 삽을 뜬다. ouroboros는 건축가처럼 “방은 몇 개? 예산은? 햇빛 방향은?”을 충분히 명확해질 때까지 캐묻는다. 이 “명확함”을 느낌이 아니라 수학 점수로 잰다. 모호함 점수가 0.2 이하로 떨어져야만 다음 단계로 넘어간다.
  2. 설계도를 못 박기 (Seed) — 인터뷰 답을 **고치지 못하는 설계서(YAML)**로 박아둔다. 이게 단 하나의 “진실”이 되어, 작업 도중 “원래 뭘 만들기로 했더라?”가 흔들리지 않는다.
  3. 만들기 (Double-Diamond 실행) — 여러 작업자(에이전트)가 의존성 순서대로 나뉘어 일하고, 충돌이 나면 조정자(coordinator)가 검토한다. “다 했다”는 말만으로는 안 통한다 — 증거를 내야 한다.
  4. 채점하기 (3단계 평가) — ① 기계검증(lint/test 같은 자동 검사) → ② 의미검증(요구사항을 진짜 만족했나) → ③ 합의검증(여러 모델이 교차 채점). 단계 게이트를 통과해야 합격.
  5. 스스로 고치기 (reflect 진화) — 채점 결과를 다음 회차의 새 설계도로 변환해 다시 돌린다. 결과가 더 이상 좋아지지 않거나(정체) 충분히 안정되면(유사도 0.95↑) 멈춘다.

핵심 비유 한 줄

“느낌상 준비됐을 때 짓지 말고 수학이 준비됐다 할 때 짓고, 대충 됐을 때 멈추지 말고 안정됐을 때 멈춰라.” — 시작과 끝을 모두 수학적 게이트로 잠근 것이 ouroboros의 정체성이다.

또 하나의 숨은 무기는 **모든 작업을 일기처럼 적어둔다(이벤트소싱)**는 점이다. 컴퓨터를 껐다 켜도 일기장(EventStore)을 다시 읽어 “어디까지 했는지”를 복원하고 이어간다. 이것이 무상태 Ralph 루프의 토대다.

핵심 정리

구성정체한 줄 역할
커널Python ≥3.12 (약 926파일)핵심 로직·이벤트소싱·평가
라우터router/dispatch.pyooo 명령을 SKILL.md+MCP로 결정적 매핑
프로바이더providers/factory.py9개 백엔드 + gjc + LiteLLM 폴백
영속성persistence/event_store.py불변 이벤트 적재 → replay/resume
MCP 서버evolve/evaluate/auto/ralph/qa기능을 도구로 노출

3-repo OS 스택 & 언어

  • 스택: shell(ourocode) · apps(ouroboros-plugins) · kernel(이 리포). “replayable, observable, policy-bound execution contract” 표방.
  • 언어: Python(커널) · Rust(crates/ouroboros-tui 보조 TUI) · YAML(Seed·설정) · Markdown(SKILL/agents/commands) · TOML(pyproject·config).

10축 평가 — 강축/주의축만 추려서

  • 만점(5) 축: 아키텍처/포지셔닝 · 컨텍스트 엔지니어링 · 툴/확장 · 오케스트레이션 · 상태/영속성 · 철학/차별점 — 코드 근거가 슬로건을 뒷받침(특히 EventStore replay 구조).
  • 가드레일/안전 = 3 — 보안등급 MEDIUM, 구현 역할 UNRESTRICTED, 일부 provider soft enforcement. 파괴적 셸 차단막 약함, 샌드박싱은 호스트 위임.
  • 검증 루프 = 4 — 3단계 게이트는 강하나, 기계검증 명령 기본값이 None이면 skip/pass, consensus도 OPENROUTER_API_KEY 없으면 단일모델 폴백(환경 의존적).
  • 자기개선/반복 = 4 — reflect/수렴은 본질적 강점이나 “8+ 종료신호”는 gate+stop 혼합 표현이라 살짝 과장.
  • 배포/DX = 4 — 설치·훅·테스트(526개)는 우수하나 README가 routing/·execution/을 말하는데 실제는 router/·orchestrator/로 drift.

독창적 아이디어 3선

  • Ambiguity 게이팅: 1 - Σ(clarity·weight) ≤ 0.2 통과해야만 Seed 생성(greenfield/brownfield 가중치 분리).
  • typed evidence contract: evidence_schema.py + verifier.py + claim_term_guard.py가 결합 — “했다”는 말 대신 구조화된 증거를 요구(LLM 없이 결정적 검증). 가장 저평가된 핵심.
  • ControlContract = OS 시스템콜 패턴: 제어 결정을 검증된 불변 페이로드로 표준화, is_terminal을 directive에서 파생해 caller 위조 불가.

약점 요약

실행 권한 경계가 느슨함 · 핵심 검증이 환경 의존적 · 임계값(0.2/0.95/30세대)이 LLM 점수 휴리스틱 의존 · 표면 복잡도가 매우 큼 · 세대마다 다수 LLM 호출로 비용/지연 · 문서-코드 drift.

실제 예시

(1) 두 개의 수학적 게이트 — 시작과 끝을 잠그는 코드 개념

# src/ouroboros/evolution/convergence.py (개념 요약)
# 끝 게이트: 온톨로지가 안정되면 멈춘다
def is_converged(history) -> bool:
    if similarity(history[-1], history[-2]) >= 0.95:   # 유사도 수렴
        return True
    if detect_period_2_oscillation(history):           # 양반주기 진동
        return True
    if generation >= 30:                               # 최대 세대
        return True
    if evolution_count == 0:                           # evolution gate:
        return False                                   #   실제 진화가 0회면 수렴 거부
    return stagnation_detected(history)
# src/ouroboros/mcp/tools/authoring_handlers.py (개념 요약)
# 시작 게이트: 모호함이 충분히 낮아야 Seed 생성
ambiguity = 1 - sum(clarity_i * weight_i for ...)      # 0~1
if ambiguity <= 0.2:                                   # 게이트 통과
    create_immutable_seed(answers)                     # 불변 Seed 박기

(2) 증거 계약 — “했다”는 말이 아니라 구조화된 증거를 요구

# src/ouroboros/harness/claim_term_guard.py (개념 요약)
# deliver 주장의 key=value term이 인용 증거에 실재하는지 LLM 없이 결정적 검증
for term in claim.terms:                  # 예: status=passed, file=app.py
    if term not in cited_evidence:        # 증거에 없으면
        reject(claim)                     # 환각으로 간주, 거부

(3) 설치 — curl 원커맨드

# 로컬 우선 설치 (pip/uv/pipx extras 도 지원)
curl -fsSL https://ouroboros.ai/install.sh | sh
ooo --help            # 결정적 router 진입점

요약 & 셀프체크

3줄 요약

  1. ouroboros는 인터뷰→불변 Seed→실행→3단계 평가→reflect 진화를 반복하는 이벤트소싱 기반 Agent OS다.
  2. 시작은 Ambiguity≤0.2, 끝은 Similarity≥0.95라는 두 수학적 게이트로 잠그고, 모든 상태를 불변 이벤트로 적재해 replay/resume한다.
  3. 진짜 차별점은 소크라테스 인터뷰가 아니라 LLM 자기보고를 typed evidence contract로 바꾸는 실행 경계다.

스스로 답해보기

  • Q1. ouroboros가 “느낌”이 아니라 “수학”으로 시작·종료를 결정한다는 말은 구체적으로 어떤 두 수식/임계값을 가리키는가?
  • Q2. “3단계 평가가 강하다”는 평가가 환경 의존적으로 헐거워질 수 있는 두 가지 경우는?
  • Q3. claim_term_guard가 막으려는 것은 무엇이며, 왜 LLM 없이도 결정적으로 검증이 가능한가?

연결

기능별 분해 노트(번호순) — 각 기능을 코드 근거와 함께 분해:

관련 인덱스: _분석축_루브릭 · HOME · _비교매트릭스

핵심 파일(근거)

  • /mnt/d/6study/_소스레포/ouroboros/README.md · project-context.md · pyproject.toml
  • src/ouroboros/evolution/reflect.py · convergence.py
  • src/ouroboros/evaluation/pipeline.py · mechanical.py · consensus.py · trigger.py
  • src/ouroboros/persistence/event_store.py
  • src/ouroboros/core/control_contract.py · security.py
  • src/ouroboros/orchestrator/policy.py · parallel_executor.py · coordinator.py · evidence_schema.py · verifier.py
  • src/ouroboros/harness/claim_term_guard.py · deliver_gate.py
  • src/ouroboros/router/dispatch.py · providers/factory.py
  • src/ouroboros/mcp/tools/authoring_handlers.py · scripts/keyword-detector.py · hooks/hooks.json

Claude ↔ Codex 교차검증 (메타검증 보존)

Codex가 실제 코드를 직접 확인(rg, 파일 라인 인용)해 Claude 초안의 과장·낡은 설명을 정정했다. 불일치 = 학습 포인트.

  • 사실 오류 정정: Python 파일 수 “383개”→실제 926개(rg --files -g '*.py') · 구조 drift(routing/·execution/→실제 router/·orchestrator/) · “항상 lint/build/test” 과장(기계검증 기본값 None→skip/pass, mechanical.py:67-71,286) · “multi-model consensus 무조건” 오류(키 없으면 단일모델 폴백, consensus.py:252-295) · deliver gate는 AC 의미를 바꾸지 않는 read-only bridge(deliver_gate.py:4,139,256).
  • 빠뜨린 포인트: provider에 gjc+LiteLLM 폴백(factory.py:265-292) · 역할별 capability/sandbox 정책(구현=UNRESTRICTED, 인터뷰/평가=READ_ONLY, policy.py) · 병렬=dependency stage+충돌 리뷰+evidence 검증 · 인터뷰 completion guard가 user/safe-default provenance를 봄(authoring_handlers.py:234).
  • 점수 보정 수용: 가드레일 4→3, 검증 루프 5→4, 자기개선 5→4, 배포/DX 5→4, 나머지 6축 5 유지.
  • 가장 저평가된 핵심: “Socratic interview”가 아니라 LLM 자기보고를 typed evidence contract로 바꾸는 실행 경계(evidence_schema + verifier + claim_term_guard).

그래프 뷰

백링크