AI SPEC-FIRST WORKFLOW
Ouroboros 완벽 가이드
AI가 원하는 결과를 못 낼 때,
프롬프트보다 명세를 먼저 만드는 법
안녕하세요, SCV입니다.
AI에게 같은 요구를 몇 번씩 다시 설명하고 있나요? 모델을 바꾸고 “전문적으로”, “완벽하게”, “단계별로” 같은 말을 더 붙여도 결과가 계속 어긋난다면 문제는 출력보다 입력에서 아직 결정되지 않은 것에 있을 가능성이 큽니다.
Ouroboros는 이 지점을 다루는 명세 우선 AI 개발 시스템입니다. 정확한 이름은 uroboros가 아니라 Ouroboros이며, 실제 워크플로우 명령은 짧게 ooo를 사용합니다. 이 글은 공식 한국어 README를 기준으로 설치와 설정, 작동 원리, 올바른 시작 프롬프트, 기존 프로젝트 적용법, 주의점까지 한 번에 정리합니다.
“AI가 알아서 잘 만들어 줘”를 반복하는 대신, 질문→명세→실행→평가를 분리하고 완료 조건을 검증 가능하게 만드는 도구입니다.
01 · DEFINITION
만능 프롬프트가 아니라
명세를 만드는 엔진
Ouroboros는 멋진 문장을 대신 써 주는 프롬프트 모음이 아닙니다. 막연한 아이디어를 소크라테스식 인터뷰로 넓게 탐색하고, 목표·제약·성공 기준이 들어간 Seed로 좁힌 뒤 실행과 평가를 반복하는 워크플로우입니다.
중요한 차이는 “어떻게 만들까?”보다 먼저 “우리가 만들려는 것이 정확히 무엇인가?”를 묻는 데 있습니다. 예를 들어 “할 일 관리 앱”이라는 말만으로는 Task가 삭제 가능한지, 보관 가능한지, 개인용인지 협업용인지, 오프라인에서도 동작해야 하는지 알 수 없습니다. 이 정의를 건너뛰면 데이터 모델부터 다시 뜯는 재작업이 생깁니다.
빈칸을 AI가 추측한다.
빈칸을 먼저 결정한다.
02 · WHY
원하는 결과가 안 나오는 진짜 이유
“쇼핑몰 만들어 줘”, “로그인 버그 고쳐 줘”, “예쁘고 전문적인 글을 써 줘”는 결과의 방향만 말합니다. 대상 사용자, 현재 시스템, 바꾸지 않을 경계, 실패 조건, 완료 판정이 빠져 있습니다. 모델은 빈칸을 그럴듯하게 채울 수 있지만 그럴듯함과 정확함은 다릅니다.
누구의 어떤 문제를 어느 수준까지 해결해야 하는가?
기술, 시간, 비용, 보안, 호환성에서 무엇을 지켜야 하는가?
어떤 테스트와 관찰 결과가 나오면 완료인가?
Ouroboros가 특히 유용한 상황은 신규 제품, 기존 코드베이스 변경, 여러 이해관계자가 있는 기능, 완료 기준이 주관적인 작업입니다. 반대로 오탈자 한 글자 수정처럼 범위와 정답이 이미 명확한 작업에는 전체 루프가 과할 수 있습니다.
03 · WORKFLOW
뱀은 반복하지 않고 진화한다
Interview는 답을 서둘러 만들지 않고 가정을 찾습니다. Seed는 대화를 목표, 제약, 성공 기준, 범위, 위험, 검증 방법이 담긴 명세로 정리합니다. Execute는 발견→정의→설계→전달의 Double Diamond로 실행합니다. Evaluate는 기계적 검사, 의미 검사, 다중 모델 합의로 결과를 판정합니다. 평가 결과는 다시 다음 Seed로 들어가 Evolve됩니다.
숫자로 보는 멈춤 기준
| 기준 | 공식 문서의 조건 | 뜻 |
|---|---|---|
| 모호성 | Ambiguity ≤ 0.2 | 구현 전 필요한 명확도가 확보됨 |
| 온톨로지 유사도 | Similarity ≥ 0.95 | 연속 세대의 핵심 구조가 안정됨 |
| 안전 상한 | 최대 30세대 | 끝없는 반복을 막는 제한 |
신규 프로젝트의 명확도는 목표 40%, 제약 30%, 성공 기준 30%로 계산합니다. 기존 프로젝트는 목표 35%, 제약 25%, 성공 기준 25%, 코드베이스 맥락 15%를 반영합니다. 즉 기존 저장소에서는 “무엇을 바꿀지”뿐 아니라 현재 구조를 얼마나 이해했는지도 관문이 됩니다.
04 · SETUP
설치와 초기 설정
방법 A. 공식 자동 설치
Claude Code, Codex CLI, Kiro CLI 감지와 MCP 서버 등록, 스킬 설치를 한 번에 처리하는 공식 경로입니다. 원격 스크립트를 곧바로 실행하는 방식이므로 조직 보안 정책이 있다면 URL의 스크립트 내용을 먼저 검토하세요.
curl -fsSL https://raw.githubusercontent.com/Q00/ouroboros/main/scripts/install.sh | bash방법 B. pip 계열 설치
pip install ouroboros-ai
ouroboros setup기본 및 비-LiteLLM 설치는 Python 3.12~3.14를 지원합니다. [litellm] 또는 [all] extra는 Python 3.12~3.13을 지원하므로 여러 기능을 함께 쓸 계획이라면 Python 3.13이 무난합니다.
pip install "ouroboros-ai[mcp]" # MCP 지원
pip install "ouroboros-ai[tui]" # 터미널 UI
pip install "ouroboros-ai[litellm]" # 멀티 프로바이더
pip install "ouroboros-ai[all]" # 전체 기능
ouroboros setup방법 C. Claude Code 플러그인만
claude plugin marketplace add Q00/ouroboros
claude plugin install ouroboros@ouroboros그다음 Claude Code 세션 안에서 ooo setup을 실행합니다. 모든 ooo 명령은 설치 후 Claude Code나 Codex CLI 같은 AI 코딩 에이전트 세션 안에서 사용하는 흐름으로 설명됩니다.
설치 직후 점검
- Python 버전과 설치 환경이 일치하는지 확인
- 에이전트 세션에서
ooo setup1회 실행 ooo help또는ooo tutorial로 통합 확인- 기존 저장소라면 루트에서 세션을 열고
ooo brownfield고려 - 비밀 키는 값이 아니라 환경 변수 이름만 전달
pip install ouroboros-ai 후 ouroboros setup을 실행하고, 필요하면 .env에 OUROBOROS_RUNTIME=kiro를 지정합니다.
05 · PROMPT DESIGN
좋은 시작 프롬프트의 8요소
- 목표어떤 변화를 만들려는가
- 사용자누가 어떤 맥락에서 쓰는가
- 현재 상태새 프로젝트인지 기존 시스템인지
- 필수 제약기술·시간·비용·보안·호환성
- 제외 범위이번에 하지 않을 일
- 성공 기준테스트 가능한 완료 조건
- 미정 사항내가 아직 모르는 결정
- 대화 규칙질문 수, 승인 지점, 추측 표기
처음부터 모든 답을 억지로 채울 필요는 없습니다. 모르는 부분은 “미정”이라고 표시하고 비교 가능한 선택지를 질문하게 하세요. 좋은 인터뷰 요청은 완성된 명세가 아니라 좋은 명세를 함께 만들 수 있는 출발점입니다.
나쁜 예시
할 일 관리 앱 만들어 줘. 예쁘고 빠르게.올바른 예시
개인 개발자가 터미널에서 쓰는 오프라인 우선 할 일 관리 CLI를 만들고 싶다.
Python 3.13과 SQLite를 사용하고 Windows와 macOS를 지원한다.
우선 구현하지 말고 사용자·Task·상태·우선순위·보관의 정의,
제외 범위, 실패 복구, 성능과 테스트 기준에서 내가 아직 정하지 않은 가정을 질문해 달라.
질문은 한 번에 3개 이하로 하고 답이 충돌하면 충돌을 지적해 달라.에이전트 세션에서는 다음처럼 시작할 수 있습니다.
ooo interview "개인 개발자용 오프라인 우선 Task CLI를 만들고 싶다. 구현 전에 숨은 가정을 질문해 달라."06 · REAL CASES
실전 프롬프트 3개
예시 1. 기존 쇼핑몰 전환 개선
기존 Next.js 쇼핑몰의 결제 이탈률을 낮추고 싶다.
결제 제공자는 바꾸지 않고 모바일 결제 흐름만 다룬다.
현재 이탈률과 이벤트 스키마는 첨부 문서에 있다.
먼저 brownfield 관점에서 코드와 분석 이벤트를 읽고,
이탈의 증상과 원인을 구분하는 인터뷰를 진행해 달라.
개인정보나 카드 데이터는 새로 수집하지 않는다.
완료 기준은 핵심 결제 경로 E2E 통과, 접근성 위반 0건,
기존 결제 API 계약 유지, 측정 가능한 실험 계획 작성이다.
구현 전 Seed를 보여 주고 내 승인을 기다려라.바꿀 지표와 바꾸지 않을 경계가 함께 있고, 기존 맥락을 읽도록 하며, 구현 전 승인 게이트가 있습니다. “전환율을 최대한 올려 줘”보다 재작업과 데이터 위험이 작습니다.
예시 2. 간헐적 로그인 버그
로그인 후 가끔 다시 로그인 화면으로 돌아오는 문제가 있다.
원인을 단정하지 말고 증상과 근본 원인을 분리해 인터뷰해 달라.
환경은 Chrome 최신 버전, 세션 쿠키 방식, 프록시 뒤의 스테이징이다.
토큰이나 쿠키 원문은 출력하지 않는다.
성공 기준은 재현 테스트 추가, 원인 설명, 최소 수정,
보안 회귀 테스트, 기존 정상 로그인 흐름 유지다.
먼저 조사 계획과 필요한 증거 목록을 Seed로 만들고,
증거가 없으면 추측이라고 표시하라.해결책을 “쿠키 만료”로 미리 고정하지 않고 증상, 환경, 보안 경계, 증거 기준을 제공합니다. Ontologist와 Researcher 관점이 빛나는 유형입니다.
예시 3. 기술 블로그 글
AI 결과가 요구와 어긋나는 개발자를 독자로 삼아
Ouroboros 한국어 실전 가이드를 작성한다.
공식 README를 1차 출처로 사용하고 설치·설정·명령어,
좋은 프롬프트 3개, 실패 패턴, FAQ를 포함한다.
과장된 효능을 피하고 공식 기능과 작성자의 해석을 구분한다.
독자가 15분 안에 설치 여부를 결정하고
첫 interview 명령을 실행할 수 있으면 성공이다.Ouroboros는 개발 시스템이 중심이지만, 명세 우선 사고는 기획서와 글쓰기에도 적용할 수 있습니다. 다만 일반 대화 앱의 모든 글쓰기 작업을 자동화하는 범용 플러그인으로 과장해서는 안 됩니다.
SEED REVIEW
좋은 Seed인지 판별하는 방법
인터뷰가 끝났다고 바로 실행 버튼을 누르지 마세요. Seed는 단순한 대화 요약이 아니라 사람과 AI가 같은 완료 상태를 바라보게 만드는 계약서에 가깝습니다. 아래 항목을 소리 내어 읽었을 때 서로 다른 해석이 가능하다면 아직 인터뷰가 끝난 것이 아닙니다.
| 검토 항목 | 확인 질문 | 나쁜 신호 |
|---|---|---|
| 문제 정의 | 누구의 어떤 불편을 해결하는가? | 기능 이름만 있고 사용자의 변화가 없음 |
| 범위 | 포함과 제외가 파일·화면·행동 단위로 나뉘는가? | “필요한 것은 전부”처럼 끝이 열려 있음 |
| 제약 | 반드시 지킬 계약과 선호 사항이 구분되는가? | 선호 기술을 절대 조건처럼 취급함 |
| 성공 기준 | 테스트나 관찰로 참과 거짓을 판정할 수 있는가? | 좋은 UX, 충분히 빠름 같은 형용사만 있음 |
| 증거 | 기존 코드와 데이터에 근거한 사실이 표시되는가? | 추측이 사실처럼 문서에 섞여 있음 |
| 승인 지점 | 어떤 행동 전에 사람에게 멈춰야 하는가? | 배포·삭제·외부 전송까지 자동으로 열려 있음 |
모호한 성공 기준을 고치는 예
어디서, 얼마나, 무엇을 기준으로 빠른지 알 수 없습니다.
스테이징 100회 측정, 실패율 1% 미만, 기존 보안 테스트 통과로 정합니다.
또한 사실, 가정, 결정, 미정을 구분하면 Seed의 품질이 크게 좋아집니다. “현재 세션은 쿠키를 사용한다”는 확인된 사실일 수 있지만 “리다이렉트 원인은 쿠키 만료다”는 아직 가정입니다. “이번 수정에서 인증 제공자는 바꾸지 않는다”는 결정이고, “모바일 앱도 같은 세션을 공유할지”는 미정일 수 있습니다. 네 종류를 섞지 않아야 평가 실패가 발생했을 때 어느 지점으로 되돌아갈지 알 수 있습니다.
질문에 답할 때도 결론만 주기보다 이유와 우선순위를 함께 알려 주세요. 예를 들어 “SQLite를 써야 한다”보다 “오프라인 단일 사용자 도구이고 별도 서버 운영을 피하는 것이 1순위라 SQLite를 선호한다. 단, 동시 편집이 필수로 확인되면 재검토한다”가 더 좋은 입력입니다. 이런 조건부 결정은 Contrarian이나 Architect가 새로운 증거를 발견했을 때 무리 없이 수정할 수 있습니다.
마지막으로 Seed에 검증 명령과 기대 결과를 함께 적어 두세요. 테스트를 누가 실행해도 같은 판정을 내릴 수 있어야 다음 세대의 평가가 문장 취향이 아니라 증거를 기준으로 움직입니다.
07 · COMMAND MAP
지금 병목에 맞는 명령 하나를 고르세요
| 상황 | 명령 | 역할 |
|---|---|---|
| 요구가 막연함 | ooo interview | 숨은 가정 질문 |
| 대화를 명세로 확정 | ooo seed | 검증 가능한 Seed 작성 |
| 자동으로 Seed 수렴 후 실행 | ooo auto | 목표 하나에서 A-grade Seed까지 진행 |
| 실행 | ooo run | Double Diamond 수행 |
| 결과 판정 | ooo evaluate | 3단계 검증 게이트 |
| 평가를 반영해 반복 | ooo evolve | 온톨로지 수렴 루프 |
| 세션을 넘어 계속 | ooo ralph | 수렴까지 지속 실행 |
| 막힘 | ooo unstuck | 5가지 수평적 사고 관점 |
| 기존 저장소 분석 | ooo brownfield | 환경과 기본값 스캔 |
| 상태와 드리프트 | ooo status | 목표 이탈과 세션 확인 |
| PM 인터뷰와 PRD | ooo pm | 제품 요구 정리 |
| 범용 품질 판정 | ooo qa | QA 게이트 |
ooo ralph 주의“무제한 자율 실행”으로 쓰지 마세요. 최대 세대, 비용, 수정 디렉터리, 사용할 도구, 외부 네트워크와 배포 권한, 사람 승인 지점을 먼저 Seed에 넣는 편이 안전합니다.
08 · NINE MINDS
한 모델보다 중요한 것은
서로 다른 사고 역할
이 역할들은 처음부터 모두 상시 실행되는 군단이 아닙니다. 필요한 순간에 맞는 관점을 불러오는 구조입니다. 요구가 충돌할 때는 Contrarian, 복잡성이 불어날 때는 Simplifier, 근거 없는 추측이 늘 때는 Researcher가 유용합니다.
09 · FAILURE MODES
자주 실패하는 6가지 패턴
바로 코드를 요구하면 명세 우선의 장점이 사라집니다. 최소한 목표·제약·판정 기준은 Seed로 확인하세요.
“빠르고 깔끔하게”는 평가할 수 없습니다. 응답 시간, 테스트, 관찰 가능한 행동으로 바꾸세요.
해야 할 것, 하면 안 되는 것, 이번에 하지 않을 것을 각각 분리하세요.
저장소 루트, 실행 명령, 관련 파일, 현재 테스트, 변경 금지 계약을 알려야 새 프로젝트처럼 오판하지 않습니다.
시간, 비용, 세대 수, 도구와 권한을 제한하지 않으면 변경량이 커질 수 있습니다.
통과 문구를 만드는 대신 틀린 가정을 찾아 Seed로 되돌리세요.
실행 전 안전 체크리스트
- 작업 트리와 브랜치 상태를 확인했다.
- 비밀 키·토큰·운영 데이터 원문을 입력하지 않는다.
- 삭제·배포·결제·외부 메시지는 명시적 승인 뒤에 둔다.
- 자동 실행의 시간·비용·세대·수정 범위를 제한했다.
- Seed의 목표, 제외 범위, 성공 기준을 사람이 읽었다.
- 테스트뿐 아니라 처음 목표에서 드리프트했는지 확인한다.
10 · FAQ
자주 묻는 질문
Q1. 일반 ChatGPT 대화에도 바로 쓸 수 있나요?+
명세 우선 질문법은 응용할 수 있지만, 공식 ooo 명령과 통합은 Claude Code, Codex CLI, Kiro CLI 같은 AI 코딩 에이전트 워크플로우를 중심으로 설명됩니다. 일반 채팅용 범용 프롬프트 플러그인과는 다릅니다.
Q2. 모든 작업에 interview부터 해야 하나요?+
아닙니다. 오탈자나 명확한 한 줄 수정에는 과할 수 있습니다. 요구가 복잡하거나 실패 비용이 크고, AI가 계속 다른 방향으로 가거나, 기존 코드 맥락이 중요한 작업에서 효과가 큽니다.
Q3. 설치할 때 어떤 Python 버전이 좋은가요?+
기본 설치는 Python 3.12~3.14를 지원합니다. LiteLLM 또는 전체 extra까지 고려한다면 공식 문서의 지원 범위가 3.12~3.13이므로 Python 3.13이 가장 호환성이 좋습니다.
Q4. ooo auto와 ooo ralph의 차이는 무엇인가요?+
ooo auto는 목표 하나에서 A-grade Seed까지 자동 수렴한 뒤 실행을 시작합니다. ooo ralph는 세션 경계를 넘어 수렴할 때까지 진화 루프를 지속합니다. 후자는 비용, 세대 수, 권한과 승인 지점을 더 엄격하게 정해야 합니다.
Q5. 결과가 나쁜데 프롬프트를 더 길게 쓰면 되나요?+
길이보다 구조가 중요합니다. 목표, 사용자, 현재 상태, 제약, 제외 범위, 성공 기준, 미정 사항을 분리하세요. 모르는 것을 억지로 채우지 말고 인터뷰에서 질문하게 하는 편이 낫습니다.
Q6. 완전히 삭제하려면 어떻게 하나요?+
공식 문서는 ouroboros uninstall을 안내합니다. 설정, MCP 등록, 데이터를 제거하므로 필요한 Seed와 결과물을 먼저 백업하고 공식 UNINSTALL.md도 확인하세요.
CONCLUSION
프롬프트를 길게 쓰는 것보다
판정 가능하게 만드세요
Ouroboros를 써야 할 때는 AI가 약해서가 아니라 내가 원하는 결과를 아직 검증 가능한 언어로 설명하지 못했을 때입니다. 단순한 작업에는 좋은 프롬프트 하나면 충분할 수 있습니다. 하지만 요구가 복잡하고 실패 비용이 크며 재작업이 반복된다면 interview로 숨은 가정을 드러내고, Seed를 승인한 뒤, run과 evaluate로 실행과 판정을 분리하는 습관이 강력합니다.
ooo interview "만들고 싶은 것을 설명하고, 구현 전에 숨은 가정을 질문해 달라."'AI' 카테고리의 다른 글
| 조코딩 AX 인재전쟁 신청 후기 및 결과: 5,300명 중 메디테라피 본선 예비 후보가 되기까지 (0) | 2026.07.16 |
|---|---|
| NotebookLM으로 영상 만들기: 실제 품질 후기와 간단한 사용법 (1) | 2026.07.15 |
| Cerebras, Upstage와 파트너십 체결 (0) | 2026.07.14 |
| Orca 사용 가이드: 설치부터 모바일 페어링과 병렬 agent 실행까지 (1) | 2026.07.08 |
| 달라진 검색엔진 SEO, GEO 알고 대응하자 (2) | 2026.07.07 |
