Q00/ouroboros

Agent OS: Stop prompting. Start specifying.

GitHub에서 열기 ↗ agent-osai-agentllm-orchestrationllm-runtimepython

4,855

GitHub 스타

476

포크

Python

언어

MIT

라이선스

2026.07.09

최근 푸시

2026.04.13

별표한 날

AI 분석

설치 난이도: 보통

큐레이터 노트

명세 기반 AI 코딩 워크플로우를 체계화하려는 팀이나 개인에게 적합하며, 특히 재현 가능성과 감사 가능성이 중요한 프로젝트에 유용합니다.

강점

명세 우선 워크플로우를 통해 AI 코딩의 모호함을 줄이고 재현 가능한 결과를 제공합니다.
다양한 AI 코딩 CLI(Claude Code, Codex, Copilot 등)를 지원하며, MCP 서버를 통해 통합됩니다.
3단계 평가 게이트(기계적, 의미적, 다중 모델 합의)로 코드 품질을 자동 검증합니다.

약점

Python 3.12 이상이 필요하여 일부 환경에서 호환성 문제가 있을 수 있습니다.
설치 과정에서 여러 CLI별 설정이 필요하여 초기 진입 장벽이 다소 높습니다.
아직 초기 단계의 프로젝트로, 생태계와 문서가 완전히 성숙하지 않았을 수 있습니다.

주의사항

면책 조항에 명시된 대로, 이 프로젝트는 암호화폐나 토큰과 관련이 없으므로 관련 사칭에 주의해야 합니다.
레거시 호환성 옵션(`ouroboros-ai[dashboard]`)은 실제 기능을 제공하지 않으므로 주의가 필요합니다.
설치 후 각 CLI별 런타임 가이드를 참조하여 추가 설정이 필요할 수 있습니다.

시작 가이드

공식 설치 스크립트나 pip를 통해 Ouroboros를 설치하고 기본 설정을 완료합니다.
지원되는 AI 코딩 CLI(예: Claude Code)와 통합하여 `ooo interview` 명령어로 첫 워크플로우를 실행해 봅니다.
문서의 런타임 가이드를 참고하여 사용 중인 CLI에 맞게 추가 설정을 진행합니다.

README 한국어 번역

이 번역은 AI가 원문 README를 옮긴 것입니다. 원문이 항상 우선합니다.

English | <a href="./README.ko.md">한국어</a> | <a href="./README.zh-CN.md">简体中文</a>

◯ ─────────── ◯ <img src="./docs/images/ouroboros.png" width="520" alt="Ouroboros"> O U R O B O R O S ◯ ─────────── ◯

프롬프트를 멈추고, 명세를 시작하세요. 재현 가능하고 명세 우선인 AI 코딩 워크플로우를 위한 Agent OS

<a href="#quick-start">빠른 시작</a> · <a href="#why-ouroboros">왜 Ouroboros인가</a> · <a href="#what-you-get">결과</a> · <a href="#the-loop">작동 방식</a> · <a href="#commands">명령어</a> · <a href="#from-wonder-to-ontology">철학</a>

막연한 아이디어를 검증된 작동 코드베이스로 바꾸세요 — Claude Code, Codex CLI, OpenCode, Hermes, Gemini, Kiro, Copilot, Pi 전반에서.

Ouroboros는 AI 코딩을 위한 Agent OS입니다: 비결정적 에이전트 작업을 재현 가능하고 관찰 가능하며 정책에 바인딩된 실행 계약으로 바꾸는 로컬 우선 런타임 레이어입니다. 임시 프롬프팅을 구조화된 명세 우선 워크플로우(인터뷰, 결정화, 실행, 평가, 진화)로 대체합니다.

Ouroboros Agent OS 스택

모든 OS와 마찬가지로 Ouroboros는 안정적인 OS 레이어(기본 요소), 애플리케이션 레이어(도메인 워크플로우), 그리고 인간이 실제로 사용하는 셸로 나뉩니다. 세 개의 저장소, 하나의 스택:

레이어	저장소	역할	제공하는 것
셸 (터미널 클라이언트)	`Q00/ourocode`	하나의 세션에서 Claude / Codex / Gemini CLI 전반에서 `ooo` 워크플로우를 실행하기 위한 네이티브 터미널 UI	TUI, wonderTool 결정 선택기, MCP 창 상태, 명령어 검색
앱 (도메인 워크플로우)	`Q00/ouroboros-plugins`	UserLevel 플러그인 계약 — 핵심 기본 요소를 설치 가능한 도메인 프로그램(PR 작업, Jira 동기화, 인시던트, 릴리스)으로 구성	플러그인 매니페스트, 범위 권한, 감사/출처, 참조 플러그인
OS (이 저장소)	`Q00/ouroboros`	Agent OS 코어 — Seed, Ledger, Runtime, MCP, 안전 경계	`ooo` 명령어, 명세 우선 워크플로우 엔진, 다중 런타임 어댑터

연결 방식:

  ourocode  ──►  ooo / ouroboros-plugins  ──►  ouroboros core (Seed · Ledger · MCP · Runtime)
   shell             user-level apps                        kernel

커널(ouroboros)은 계약을 소유합니다: 모든 행동은 어떤 LLM이 실행하든 Seed에 바인딩되고, 원장에 기록되며, 재현 가능한 이벤트가 됩니다.
플러그인(ouroboros-plugins)은 해당 계약에 대해 범위가 지정된 기능을 선언하므로, 도메인 워크플로우(PR 검토, Linear 티켓 분류, 릴리스 실행)가 일회성 프롬프트 대신 감사 가능하고 정책에 바인딩된 상태를 유지합니다.
Ourocode는 터미널 셸입니다: MCP 상태, 인터뷰 질문, wonderTool 결정을 일급 TUI 요소로 표시하여 키보드에서 떠나거나 CLI 간에 전환하지 않고도 OS를 구동할 수 있습니다.

지원되는 CLI와 함께 ouroboros만 단독으로 사용하거나, 도메인 워크플로우를 위해 플러그인을 계층화하거나, 통합 터미널 조종석을 원할 때 ourocode를 설치하세요.

면책 조항. Ouroboros 프로젝트와 커뮤니티는 어떠한 암호화폐, 토큰, 밈코인 또는 거래 커뮤니티와도 관련이 없습니다 — pump.fun 또는 기타 런치패드의 "ouroboros" 티커를 포함하되 이에 국한되지 않습니다. 이는 오픈 소스 개발자 도구입니다. 우리는 어떤 코인도 발행, 지지 또는 보유하지 않습니다. 이 프로젝트와의 연관성을 주장하는 모든 토큰은 승인되지 않았습니다.

왜 Ouroboros인가?

대부분의 AI 코딩은 출력이 아닌 입력에서 실패합니다. 병목은 AI 능력이 아니라 인간의 명확성입니다.

문제	발생 상황	Ouroboros 해결책
모호한 프롬프트	AI가 추측하고, 당신이 재작업	소크라테스식 인터뷰가 숨은 가정을 드러냄
명세 없음	아키텍처가 빌드 중에 표류	불변 시드 명세가 코드 전에 의도를 고정
수동 QA	"괜찮아 보인다"는 검증이 아님	3단계 자동 평가 게이트

빠른 시작

설치 — 한 명령어로 모든 것이 자동 감지:

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

빌드 — AI 코딩 에이전트를 열고 다음을 입력:

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

Claude Code, Codex CLI, GitHub Copilot CLI, OpenCode, Hermes, Gemini, Kiro CLI, Pi CLI와 함께 작동합니다. 설치 프로그램은 Claude Code, Codex CLI, Hermes CLI를 자동으로 감지하고 호스트가 지원하는 경우 MCP 서버를 등록합니다. OpenCode, Kiro, GitHub Copilot CLI, Gemini CLI 또는 Pi CLI의 경우 설치 후 ouroboros setup --runtime <opencode|kiro|copilot|gemini|pi>를 실행하세요. Copilot CLI 런타임은 GitHub Copilot models API를 통해 라이브로 모델 카탈로그를 검색하고 설정 중에 기본값을 선택할 수 있게 합니다.

pip install 'ouroboros-ai[claude]'
ouroboros setup            # Kiro CLI를 감지하고 MCP 서버 등록

.env에서 런타임 설정:

OUROBOROS_RUNTIME=kiro

그런 다음 Kiro CLI 세션 내에서 ooo 명령어를 사용하세요.

</details>

<details> <summary>GitHub Copilot CLI 빠른 시작</summary>

gh auth login                                # 일회성 GitHub 인증 (라이브 모델 검색에 사용)
pipx install 'ouroboros-ai[mcp]'             # 또는: uv tool install 'ouroboros-ai[mcp]'
ouroboros setup --runtime copilot            # 모델을 라이브로 검색하고 기본값을 선택하며,
                                             # ~/.copilot/mcp-config.json에 MCP 서버 등록

Copilot CLI 세션을 다시 시작한 후 내부에서 ooo 명령어를 사용하세요. 구성의 다른 곳에서 사용된 하이픈이 있는 Anthropic 모델 ID(claude-opus-4-6)는 런타임에 점이 있는 Copilot 형식(claude-opus-4.6)으로 자동 매핑되므로, 백엔드를 전환할 때 기존 구성이 계속 작동합니다.

전체 내용은 GitHub Copilot CLI 런타임 가이드를 참조하세요.

</details>

Claude Code 플러그인 전용 (시스템 패키지 없음):

claude plugin marketplace add Q00/ouroboros && claude plugin install ouroboros@ouroboros

그런 다음 Claude Code 세션 내에서 ooo setup을 실행하세요.

pip / uv / pipx:

pip install ouroboros-ai                # 기본
pip install ouroboros-ai[claude]        # + Claude Code 종속성
pip install ouroboros-ai[litellm]       # + LiteLLM 다중 제공자
pip install ouroboros-ai[mcp]           # + MCP 서버/클라이언트 지원
pip install ouroboros-ai[tui]           # + Textual 터미널 UI
pip install ouroboros-ai[all]           # 모든 것 (claude + litellm + mcp + tui)
ouroboros setup                         # 런타임 구성

레거시 호환성: ouroboros-ai[dashboard]는 여전히 호환성 별칭/무연산으로 허용됩니다. 대시보드 런타임 페이로드를 설치하지 않습니다. ouroboros-ai[all]은 호환성을 위해서만 해당 무연산 별칭을 포함합니다.

런타임 가이드 참조: Claude Code · Codex CLI · Hermes · OpenCode · Kiro CLI · Gemini CLI · GitHub Copilot CLI · Pi JSON 모드

</details>

ouroboros uninstall

모든 구성, MCP 등록 및 데이터를 제거합니다. 자세한 내용은 UNINSTALL.md를 참조하세요.

</details>

Python >= 3.12 필요. 전체 종속성 목록은 pyproject.toml을 참조하세요.

결과

Ouroboros 사이클을 한 번 돌린 후, 막연한 아이디어는 검증된 코드베이스가 됩니다:

단계	이전	이후
인터뷰	"Build me a task CLI"	12개의 숨은 가정이 드러나고, 모호성이 0.19로 점수화됨
시드	명세 없음	수용 기준, 온톨로지, 제약 조건이 포함된 불변 명세
평가	수동 검토	3단계 게이트: 기계적(무료) -> 의미적 -> 다중 모델 합의

<details> <summary>무슨 일이 일어났나요?</summary>

interview  ->  소크라테스식 질문이 12개의 숨은 가정을 드러냄
seed       ->  답변이 불변 명세로 결정화됨 (모호성: 0.15)
run        ->  Double Diamond 분해를 통해 실행됨
evaluate   ->  3단계 검증: 기계적 -> 의미적 -> 합의

AI 코딩 에이전트 세션 내에서 ooo <cmd>를 사용하거나, 터미널에서 ouroboros init start, ouroboros run seed.yaml 등을 사용하세요.

뱀이 한 바퀴를 완료했습니다. 각 바퀴마다 이전보다 더 많은 것을 알게 됩니다.

</details>

비교

AI 코딩 도구는 강력하지만 — 입력이 불명확할 때 잘못된 문제를 해결합니다.

	일반 AI 코딩	Ouroboros
모호한 프롬프트	AI가 의도를 추측하고 가정 위에 빌드	소크라테스식 인터뷰가 코드 전에 명확성을 강제
명세 검증	명세 없음 — 아키텍처가 빌드 중에 표류	불변 시드 명세가 의도를 고정; 모호성 게이트(<= 0.2)가 조기 코드를 차단
평가	"괜찮아 보인다" / 수동 QA	3단계 자동 게이트: 기계적 -> 의미적 -> 다중 모델 합의
재작업 비율	높음 — 잘못된 가정이 늦게 드러남	낮음 — 가정이 PR 검토가 아닌 인터뷰에서 드러남

루프

우로보로스 — 자기 꼬리를 삼키는 뱀 — 은 장식이 아닙니다. 그것이 바로 아키텍처입니다:

    Interview -> Seed -> Execute -> Evaluate
        ^                           |
        +---- 진화 루프 ------------+

각 사이클은 반복되지 않습니다 — 진화합니다. 평가의 출력은 다음 세대의 입력으로 피드백되어, 시스템이 진정으로 무엇을 구축하고 있는지 알 때까지 계속됩니다.

	단계	발생 상황
	인터뷰	소크라테스식 질문이 숨은 가정을 드러냄
	시드	답변이 불변 명세로 결정화됨
	실행	Double Diamond: 발견 -> 정의 -> 설계 -> 전달
	평가	3단계 게이트: 기계적($0) -> 의미적 -> 다중 모델 합의
	진화	Wonder ("우리가 아직 모르는 것은 무엇인가?") -> 반영 -> 다음 세대

"이것이 Ouroboros가 자기 꼬리를 먹는 곳입니다: 평가의 출력이

다음 세대의 시드 명세를 위한 입력이 됩니다."

-- reflect.py

온톨로지 유사도가 >= 0.95에 도달하면 수렴됩니다 — 시스템이 자신이 구축하는 것을 진정으로 알게 될 때입니다.

원본 저장소: Q00/ouroboros

라이선스: MIT

게재 제외를 원하시면 삭제 요청을 보내주세요.