interview -> Seed -> AC tree -> execution/evaluation/evolution -> runtime harness
· 인터랙티브 학습 가이드
usefullabs(쓸모랩) 교육자료Ouroboros는 코딩 에이전트 자체가 아니라, 요구사항을 Seed로 고정하고 여러 런타임에 실행을 위임한 뒤 검증과 진화를 반복하는 워크플로 엔진입니다. 같은 Seed contract가 CLI, MCP, runtime adapter, plugin surface를 관통합니다.
Ouroboros는 단순 CLI가 아니라 상위 프로그램 표면을 둔 Agent OS 구조입니다. first-party 프로그램은 core 위의 제품 레이어이고, installable third-party plugin은 accepted RFC contract와 구현 모듈을 함께 확인해야 합니다.
요구사항은 바로 실행되지 않습니다. interview state, ambiguity scorer, seed generator가 먼저 요구사항을 Seed-ready 상태로 만듭니다.
Seed는 workflow의 헌법입니다. goal, constraints, acceptance criteria, ontology, evaluation principles, exit conditions를 frozen model로 고정합니다.
Seed는 AC tree로 쪼개지고, 각 acceptance criterion은 Double Diamond 실행 사이클과 evaluation gate를 통과합니다.
실행 결과는 mechanical, semantic, consensus evaluation을 통과해야 하고, evolve loop는 Wonder/Reflect/Seed regeneration으로 다음 세대를 만듭니다.
핵심 workflow는 runtime-agnostic입니다. 실제 작업 실행만 Claude, Codex, OpenCode, Hermes, Gemini, Kiro, Copilot adapter로 위임됩니다.
| Phase | Source surface | 실제 역할 |
|---|---|---|
| Big Bang | interview, ambiguity, seed_generator | 모호한 요청을 질문/답변 이력으로 축적하고 ambiguity gate를 통과한 Seed로 변환합니다. |
| PAL Router | ontology, policy, capability routing | Seed contract, ontology lens, available capabilities를 기준으로 실행 경로와 tool exposure를 정합니다. |
| Double Diamond | Discover -> Define -> Design -> Deliver | 각 AC를 충분히 이해한 뒤 해결안을 수렴하고 구현합니다. child AC dependency level은 병렬 실행 후보가 됩니다. |
| Resilience | checkpoint, recovery, retry, watchdog | 중단, timeout, partial failure를 event stream과 checkpoint로 복구 가능한 상태로 유지합니다. |
| Evaluation | mechanical -> semantic -> consensus | 기계적 검증을 먼저 통과하고, 의미 평가와 필요 시 multi-model consensus로 승인 여부를 결정합니다. |
| Secondary Loop | evolve_step, ralph, convergence | 한 번의 실행으로 끝내지 않고, drift와 convergence를 감시하면서 다음 generation으로 개선합니다. |
실행은 “Seed를 모델에게 던지고 기다리는 것”이 아닙니다. AC tree, decomposition, Double Diamond, evaluation pipeline, convergence gate가 함께 움직입니다.
Acceptance criteria는 immutable ACNode로 관리됩니다. event replay로 tree를 복원할 수 있고, HUD는 이 tree를 live progress surface로 보여줍니다.
복잡한 AC는 LLM decomposition으로 2-5개 child AC가 됩니다. 각 child는 independently verifiable해야 하며 sibling dependency를 zero-based index로 선언합니다.
각 AC는 문제 이해와 해결 설계를 분리합니다. Discover/Define은 정확한 문제 수렴, Design/Deliver는 구현 수렴입니다.
평가는 세 단계입니다. Stage 1은 비용이 낮고 결정적인 검증, Stage 2는 semantic judgement, Stage 3는 불확실성이 높을 때 consensus입니다.
Ralph는 evolve_step을 반복하는 MCP-owned background loop입니다. QA pass, convergence, terminal action, max generation, timeout, oscillation, grade regression을 종료 조건으로 둡니다.
| 도구군 | 대표 tools | 역할 |
|---|---|---|
| run | ouroboros_execute_seed, ouroboros_start_execute_seed | Seed를 실제 runtime adapter에 넘겨 실행합니다. start variant는 background job으로 반환됩니다. |
| status | ouroboros_session_status, ouroboros_ac_tree_hud, ouroboros_query_events | session, AC tree, event history를 조회해 현재 진행 상태와 근거를 확인합니다. |
| jobs | ouroboros_job_status, ouroboros_job_wait, ouroboros_job_result, ouroboros_cancel_job | background job lifecycle을 조회하고, wait/result/cancel을 MCP 표면에서 처리합니다. |
| cancel | ouroboros_cancel_execution | 실행 세션을 안전하게 cancel_requested/cancelled 흐름으로 전환합니다. |
| 도구군 | 대표 tools | 역할 |
|---|---|---|
| evaluate | ouroboros_evaluate, ouroboros_start_evaluate | mechanical, semantic, consensus pipeline으로 artifact가 AC와 goal에 맞는지 판정합니다. |
| qa | ouroboros_qa, ouroboros_checklist_verify | artifact 일반 품질 판정과 checklist-style AC 검증을 수행합니다. |
| drift | ouroboros_measure_drift | goal drift, constraint drift, ontology drift를 가중 합산해 Seed 대비 이탈을 측정합니다. |
| unstuck | ouroboros_lateral_think | hacker, researcher, simplifier, architect, contrarian 관점으로 막힌 문제를 분해합니다. |
| 도구군 | 대표 tools | 역할 |
|---|---|---|
| evolve | ouroboros_evolve_step, ouroboros_start_evolve_step | 한 generation만 실행합니다. Gen 1은 Seed를 받고 Gen 2 이후는 event lineage에서 상태를 복원합니다. |
| ralph | ouroboros_ralph | evolve_step을 QA/convergence/timeout까지 반복하는 durable background loop입니다. |
| lineage | ouroboros_lineage_status, ouroboros_evolve_rewind | lineage 상태를 조회하거나 특정 generation으로 되감습니다. |
runtime backend는 스펙을 바꾸지 않습니다. Claude, Codex, OpenCode, Hermes, Gemini, Kiro, Copilot은 같은 Seed와 event model을 다른 도구, 권한, 세션 UX로 실행합니다.
create_agent_runtime은 config/env/explicit option을 정규화한 뒤 backend별 AgentRuntime을 반환합니다. runtime backend가 workflow 스펙을 바꾸지는 않습니다.
get_ouroboros_tools는 실행, authoring, evaluation, evolution, job, brownfield, PM, QA handler를 하나의 handler tuple로 조립합니다.
OpenCode plugin mode에서는 MCP tool이 _subagent envelope를 내보내고, bridge plugin이 tool.execute.after hook에서 child session Task pane으로 dispatch합니다.
Codex와 Hermes는 CLI subprocess harness입니다. 각각 session parsing, permission, skill dispatch, stdout idle timeout 같은 런타임별 작업을 adapter가 책임집니다.
Ouroboros MCP server는 upstream MCP servers를 읽어 child agent tool catalog에 병합할 수 있습니다. evolve_step과 unstuck도 bridge context를 이어받습니다.
| Backend | Adapter | 운영 포인트 |
|---|---|---|
| Claude Code | ClaudeAgentAdapter | Claude Code 권한/세션 모델을 쓰는 기본 에이전트 런타임입니다. |
| Codex CLI | CodexCliRuntime | Codex CLI subprocess, session handle, permission args, skill dispatcher, MCP handler를 엮습니다. |
| OpenCode | OpenCodeRuntime | subprocess 모드는 headless/CI용, plugin 모드는 OpenCode Task pane bridge용으로 분리됩니다. |
| Hermes | HermesCliRuntime | Hermes CLI quiet output에서 session_id를 파싱하고 reasoning/banner noise를 정리합니다. |
| Gemini | GeminiCLIRuntime | Gemini CLI adapter를 runtime_factory에서 lazy import해 선택적으로 연결합니다. |
| Kiro | KiroAgentAdapter | Kiro CLI headless 흐름과 trust-tools permission model을 감쌉니다. |
| Copilot | CopilotCliRuntime | GitHub Copilot CLI tool allowlist와 live model discovery 흐름을 runtime backend로 제공합니다. |
| Step | Mechanism | 결과 |
|---|---|---|
| 1. Envelope | _subagent / _subagents | Python MCP handler가 OpenCode plugin 조건에서 직접 실행 대신 dispatch envelope를 반환합니다. |
| 2. Hook | tool.execute.after | bridge plugin이 tool output metadata와 JSON payload를 읽어 child task 생성 대상으로 파싱합니다. |
| 3. Child Session | client.session.create | payload마다 fresh child session을 생성해 독립 context로 실행합니다. main session context는 가벼워집니다. |
| 4. Subtask Part | HTTP PATCH | 원래 tool assistant-message part를 running subtask로 PATCH해 inline Task pane을 보여줍니다. |
| 5. Fire and Forget | client.session.prompt | child prompt는 await하지 않고 실행됩니다. 완료/실패 시 completed/error 상태로 다시 PATCH합니다. |
| 6. Response Shape | metadata.ouroboros_response_shape | job_id, session_id, status 같은 원래 tool contract key는 metadata에 보존됩니다. |
장기 실행 시스템의 신뢰성은 상태를 어떻게 남기고, 중단을 어떻게 복구하고, 확장 계약을 어디서 차단하는지에 달려 있습니다. Ouroboros는 event sourcing, checkpoint, job manager, UserLevel plugin RFC contract를 명시적으로 둡니다.
| Surface | Storage/contract | 운영 의미 |
|---|---|---|
| Event Store | SQLite events table | aggregate_type, aggregate_id, event_type, payload, timestamp, consensus_id를 저장하고 replay/query를 지원합니다. |
| Session Repository | event-sourced session tracker | session status를 running, paused, completed, failed, cancelled로 재구성합니다. |
| Job Manager | background job events | queued, running, cancel_requested, completed, failed, cancelled, interrupted lifecycle을 관리합니다. |
| Checkpoint | JSON + SHA-256 integrity | phase boundary에서 상태를 저장하고 rollback 가능한 checkpoint chain을 만듭니다. |
| Unit of Work | pending events + checkpoint | 작업 단위가 commit되기 전 pending event를 묶고, 실패 시 append-before-commit을 방지합니다. |
| Control Bus | cancel/recovery signals | 장기 실행 중 cancel, watchdog, recovery protocol 같은 runtime control signal을 전달합니다. |
| Layer | Contract | 차단하는 위험 |
|---|---|---|
| First-party programs | core-shipped UserLevel layer | ooo auto, run, pm 같은 제품 workflow는 core primitive 위에 올라간 first-party 프로그램으로 봅니다. |
| Plugin-aware dispatch | unknown top-level command fallback | CLI group은 등록된 command가 없을 때 plugin dispatch command를 조회합니다. 실제 사용 가능 여부는 설치/신뢰 상태와 runtime packaging에 달려 있습니다. |
| Manifest contract | schema_version, name, version, source, commands, capabilities, permissions, entrypoint | RFC가 고정한 installable plugin 계약입니다. 구현 모듈이 있더라도 문서의 target/shipped caveat를 같이 확인해야 합니다. |
| Lockfile contract | ~/.ouroboros/plugins.lock | third-party 신뢰 상태를 고정하기 위한 RFC 계약입니다. first-party 프로그램은 lockfile이 아니라 override model을 따릅니다. |
| Trust store contract | trusted source identity | first-party는 release artifact 기반 implicit trust, installable plugin은 explicit trust/confirmation 경계를 가집니다. |
| Firewall contract | single invocation choke point | permission check, confirmation, subprocess launch, audit event, secret argv redaction을 한곳에 모으는 accepted design입니다. |
ooo auto --runtime codex는 전체 pipeline을 Codex가 실행한다는 뜻이 아닙니다. interview, seed generation, seed repair는 Ouroboros MCP server 안에서 in-process로 돌고, 마지막 run handoff만 선택한 runtime adapter가 맡습니다.
| 상황 | 추천 surface | 판단 기준 |
|---|---|---|
| 요구사항이 흐리다 | interview -> generate_seed | 바로 run하지 말고 ambiguity를 낮춘 뒤 Seed를 만듭니다. brownfield면 repo context를 먼저 붙입니다. |
| 스펙은 명확하고 실행만 필요하다 | execute_seed / start_execute_seed | Seed YAML 또는 Seed content를 넘겨 runtime adapter에 실행을 맡깁니다. |
| 완성될 때까지 반복해야 한다 | ralph | QA pass, convergence, regression/oscillation gate까지 evolve_step을 반복합니다. |
| 현재 결과가 맞는지 모르겠다 | evaluate / qa / checklist_verify | mechanical evidence와 semantic judgement를 분리해서 승인 여부를 확인합니다. |
| OpenCode에서 독립 작업창이 필요하다 | opencode plugin mode | bridge plugin이 child sessions를 만들어 Task pane으로 팬아웃합니다. headless/CI는 subprocess mode를 씁니다. |
| 설치된 확장 프로그램을 실행한다 | UserLevel plugin dispatch | first-party 프로그램과 installable plugin을 구분합니다. installable plugin은 RFC contract와 현재 구현/설치 상태를 확인해야 합니다. |