Ouroboros, Seed 명세와 평가 루프로 고정하는 Agent OS

Ouroboros는 로컬에서 돌아가는 Agent OS다. 에이전트 세션을 대화 로그에 맡기지 않고 Seed 명세와 평가 루프로 고정한다.

먼저 요구사항을 질문으로 좁힌다. 그 답을 변경 불가능한 Seed로 남기고, 실행 결과를 자동 평가한 뒤 다음 세대 입력으로 넣는다. 어떤 모델이나 CLI를 쓰든 작업은 Seed, Ledger, Runtime, MCP, Evaluation Gate를 통과한다.

왜 프로그래머에게 의미가 있는가

“작업 관리 CLI를 만들어줘”만으로는 태스크의 상태 모델, 우선순위 규칙, 저장 방식, 동시성, 테스트 기준, 실패 처리, 배포 형태가 정해지지 않는다. Ouroboros는 이 빈칸을 코드 작성 전에 질문으로 드러낸다.

일반 AI 코딩 흐름	프로그래머가 겪는 문제	Ouroboros의 접근
프롬프트 입력 후 바로 구현	숨은 요구사항이 PR 리뷰나 QA에서 뒤늦게 드러남	Socratic interview로 가정과 제약을 먼저 질문
대화 맥락에 의존	세션이 길어질수록 아키텍처와 요구사항이 드리프트됨	Seed 명세로 목표, 제약, 수용 기준을 고정
“looks good” 수준의 수동 확인	테스트되지 않은 결과물이 병합 후보가 됨	Mechanical → Semantic → Multi-Model Consensus 평가 게이트
모델/CLI마다 다른 사용법	Claude, Codex, Gemini, Copilot 등 런타임별 워크플로우가 흩어짐	공통 Agent OS 계약 위에서 다중 런타임을 어댑터로 연결

핵심 개념

1. Interview: 코딩 전에 모호함을 줄인다

첫 단계는 질문이다. Socratic Interviewer는 만들 기능보다 지금 팀이 무엇을 가정하고 있는지를 묻는다. 태스크 관리 CLI라면 이런 질문이 먼저 나온다.

• 태스크는 삭제되는가, 아카이브되는가?
• 우선순위는 단순 문자열인가, 정렬 가능한 enum인가?
• 데이터는 로컬 파일, SQLite, 원격 API 중 어디에 저장되는가?
• 성공 기준은 CLI 명령 동작인가, 테스트 커버리지인가, 사용자 시나리오 통과인가?
• 기존 코드베이스가 있다면 어떤 설정 파일과 패턴을 따라야 하는가?

이 단계의 목적은 나중에 리팩터링 비용으로 돌아올 불명확성을 코딩 전에 없애는 것이다.

2. Seed: 요구사항을 실행 가능한 명세로 고정한다

Interview 결과는 Seed가 된다. Seed는 목표, 제약, 수용 기준, 온톨로지, 실행 범위를 담은 불변 명세다. 에이전트는 이 조건들을 만족해야 한다.

모호도 점수도 쓴다. README 기준 Greenfield에서는 목표 명확성, 제약 명확성, 성공 기준을 가중 합산하고, Ambiguity ≤ 0.2일 때 Seed 생성이 적절하다고 본다. 강제 통과도 가능하지만 기본값은 불명확하면 코딩하지 않는 것이다.

3. Execute: Double Diamond로 구현을 분해한다

실행 단계는 Discover → Define → Design → Deliver다. 파일을 수정하기 전에 문제 이해와 설계 선택을 거친다. 기존 코드베이스에서는 brownfield 탐색으로 설정 파일과 언어 생태계를 감지하고 그 프로젝트의 관례를 반영하려고 한다.

4. Evaluate: 결과물을 게이트로 통과시킨다

평가도 워크플로우 안에 들어 있다. 세 층이다.

• Mechanical evaluation: 테스트, 린트, 타입 체크처럼 비용이 낮고 결정적인 검증
• Semantic evaluation: 구현이 Seed의 의도와 수용 기준을 충족하는지 의미 단위로 확인
• Multi-Model Consensus: 필요할 때 여러 모델의 판단으로 품질과 적합성을 교차 검증

평가 명령과 기대 결과는 성공 계약에 넣지 않는다. 산출물을 채점 기준과 분리해서 검증하기 위해서다.

5. Evolve: 평가 결과를 다음 세대의 입력으로 되먹인다

Evaluate 결과는 Reflect/Wonder를 거쳐 다음 Seed나 다음 세대 실행의 입력이 된다. 온톨로지 유사도가 안정되면 수렴으로 본다. README는 임계값을 0.95로 적는다.

아키텍처

README는 스택을 세 층으로 나눈다.

레이어	역할	실제로 하는 일
Shell	터미널 UI와 사용자 조작면	Claude, Codex, Gemini 등 여러 CLI를 하나의 조작 경험으로 묶음
Apps / Plugins	PR, Jira, incident, release 같은 도메인 워크플로우	권한, 감사, provenance가 있는 재사용 가능한 자동화 단위
OS Core	Seed, Ledger, Runtime, MCP, safety boundary	실행 계약, 이벤트 기록, 런타임 추상화, 검증 흐름을 담당하는 커널

execution은 Double Diamond 실행을 담당한다. evaluation은 Mechanical/Semantic/Consensus 게이트다. persistence는 이벤트 소싱과 체크포인트다. orchestrator는 Claude Code, Codex CLI, OpenCode, Gemini, Kiro, Copilot 같은 런타임 백엔드를 추상화한다.

설치와 첫 실행 예시

README Quick Start는 다음과 같다.

curl -fsSL https://raw.githubusercontent.com/Q00/ouroboros/main/scripts/install.sh | OUROBOROS_INSTALL_REF=readme bash

에이전트 세션 안에서는 다음처럼 쓴다.

ooo setup
ooo interview "I want to build a task management CLI"

일반 터미널에서는 다음처럼 쓴다.

ouroboros init start --orchestrator "I want to build a task management CLI tool"

지원 런타임은 Claude Code, Codex CLI, GitHub Copilot CLI, OpenCode, Hermes, Gemini, Kiro CLI, Pi CLI, Zcode, Goose, GJC, Antigravity CLI, Grok Build CLI 등이다. 설치할 때 사용 가능한 런타임을 감지하고, MCP를 받을 수 있는 호스트에는 MCP 구성을 연결한다.

사용 시나리오

시나리오 A: 새 CLI 도구 만들기

1. ooo interview "Build a task management CLI"로 요구사항을 질문받는다.
2. 태스크 모델, 명령어, 저장소, 테스트 기준을 답한다.
3. Ouroboros가 Seed를 생성하고 모호도 기준을 통과했는지 확인한다.
4. ooo run 또는 대응 CLI 명령으로 구현을 실행한다.
5. ooo evaluate로 테스트와 의미 검증을 통과시키고, 실패하면 다음 루프에 반영한다.

시나리오 B: 기존 저장소에 기능 추가하기

Brownfield 작업에서는 현재 코드베이스 구조가 먼저다. Ouroboros는 설정 파일과 프로젝트 생태계를 탐색한 뒤 기존 패턴을 반영하는 쪽으로 Seed와 실행 계획을 잡는다. 고칠 파일 이름보다 이 저장소에서 지켜야 할 관례를 알려 주는 쪽이 안전하다.

시나리오 C: PR 리뷰와 릴리즈 자동화

코어 위에 플러그인을 올리면 PR 운영, Jira 동기화, incident 처리, release 같은 반복 작업을 명세 기반으로 자동화할 수 있다. 플러그인은 선언된 권한 범위와 감사 가능한 이벤트 기록 위에서 동작한다.

기대 효과

• 요구사항을 코드 작성 전에 정리하면 리뷰 단계에서 방향을 뒤집는 일이 줄어든다.
• Seed와 Ledger로 에이전트 작업을 기록하고 다시 실행할 수 있다.
• 테스트, 의미 검증, 다중 모델 합의가 워크플로우에 포함된다.
• 특정 AI CLI에 묶이지 않고 공통 계약 위에서 여러 런타임을 쓸 수 있다.
• 플러그인과 MCP로 PR, 이슈, 릴리즈 같은 개발 운영까지 확장할 수 있다.

유의할 점

• 오타 수정이나 작은 스크립트에는 인터뷰와 Seed가 부담일 수 있다.
• Python 버전, uv/pipx, 각 런타임 CLI, MCP 등록 같은 초기 설정이 필요하다.
• 질문은 도구가 돕지만 답의 품질은 사용자와 팀에게 달려 있다.
• Mechanical 검증은 싸지만 Semantic이나 Multi-Model Consensus는 모델 호출 비용과 시간이 크다.