Claude Code 정리 노트 (2)

작성일: 2026-06-27 이전 노트: 2026-06-20-claude-code-notes.md 의 후속편

1. Token Maxxing (토큰 맥싱)

공식 용어가 아니라 LLM/에이전트 커뮤니티 슬랭. “-maxxing”(looksmaxxing 등에서 온 말장난) = 어떤 걸 극단까지 밀어붙인다는 뜻.

개념 한 줄

토큰을 아끼지 않고 최대한 쏟아부어서 결과 품질을 끌어올리는 전략.

전통적으로 “토큰 = 비용”이라 아끼는 게 미덕이었는데, Token Maxxing은 반대 방향:

“토큰 비용보다 정답률·완성도가 훨씬 가치 있으니, 토큰을 펑펑 써서라도 최고의 결과를 뽑자.”

구체적인 행동 패턴

패턴 설명
컨텍스트 풀로 채우기 관련 파일·문서·히스토리를 최대한 많이 넣어 모델이 추측하지 않게 함
멀티 에이전트 팬아웃 한 번에 끝낼 일을 여러 에이전트로 쪼개 병렬 탐색·검증 (ultrawork, dynamic workflow가 전형)
적대적 검증 같은 문제를 여러 에이전트가 독립적으로 풀거나 반박하게 해 틀린 답을 걸러냄
반복 루프 “더 이상 새 발견이 없을 때까지” 계속 돌리기 (loop-until-dry)

도구화된 사례 (이 환경 기준)

언제 쓰나 / 주의점

구분 내용
✅ 유리 깊은 리서치, 대규모 리팩터, 보안 감사 — 비용보다 정확도가 우선일 때
⚠️ 과함 단순·일회성 작업에 멀티 에이전트는 낭비. 비용·지연(latency)만 증가

한 줄 요약: “토큰 아끼다 일 그르치지 말고, 필요하면 토큰을 최대로 써서 확실하게 끝내자.” 🔗 이전 노트의 15(dynamic workflow)·16(ultracode)번이 Token Maxxing을 실제 도구로 구현한 것.

2. SDD (Spec-Driven Development, 명세 주도 개발)

코드를 먼저 짜는 게 아니라 명세(spec)를 먼저 확정하고 거기서 코드를 파생시키는 개발 방법론. AI 코딩 시대에 재주목.

개념 한 줄

“명세가 1차 산출물(source of truth), 코드는 명세에서 파생된 것.”

기존엔 코드가 진실이고 문서가 부속물이었는데, SDD는 이를 뒤집어 명세를 살아있는 문서(living spec)로 두고 코드는 그 구현 결과물로 본다.

왜 지금 뜨는가 (AI 코딩 맥락)

AI에게 “로그인 기능 만들어줘”처럼 막연히 시키면 매번 제멋대로 만듦 → 이전 노트의 goal drift / agentic laziness(15번) 문제와 같은 맥락. SDD는 앞단에 명확한 명세를 두어 AI가 추측하지 않게 함. 즉 AI 시대엔 “정확한 명세를 쓰는 능력” = “정확한 코드를 얻는 능력”.

전형적 워크플로 (예: GitHub Spec Kit)

단계 산출물 내용
1. Specify spec.md 무엇을·왜 (요구사항, 사용자 시나리오) — 어떻게는 아직 안 적음
2. Plan plan.md 기술 스택·아키텍처·제약 등 “어떻게”
3. Tasks tasks.md 잘게 쪼갠 실행 가능한 작업 목록
4. Implement 코드 AI가 위 명세를 근거로 단계별 구현

장점 vs 주의점

구분 내용
✅ 장점 AI 결과의 일관성·검증가능성↑, 의도가 문서로 남음, 명세=테스트 기준이 됨
✅ 사람·AI가 같은 명세로 작업 → 협업·핸드오프 깔끔
⚠️ 주의 명세 작성 비용. 작고 자명한 작업엔 과함(오버엔지니어링)
⚠️ 명세와 코드가 어긋나면(drift) 오히려 혼란 → 명세 최신 유지 필수

관련 개념 구분

개념 SDD와의 관계
TDD (테스트 주도) 테스트를 먼저 → SDD의 “검증”과 닮았으나, SDD는 더 상위(요구사항/의도)부터 시작
planner/plan 스킬, deep-interview 사실상 SDD의 “Specify → Plan” 단계를 돕는 도구

한 줄 요약: “AI에게 코드를 시키기 전에, 무엇을·어떻게 만들지 명세로 먼저 못 박고, 코드는 그 명세에서 끌어내는 방식.”

3. AskUserQuestion Tool (사용자 질문 도구)

Claude/에이전트가 작업 중 막혔을 때, 선택지 버튼이 있는 구조화된 질문 UI를 띄워 사용자 결정을 받는 도구. 텍스트로 “어떻게 할까요?” 묻는 것과 다름.

개념 한 줄

“오직 사용자만 결정할 수 있는 갈림길”일 때만 쓰는 도구.

코드·요청·합리적 기본값으로 스스로 판단할 수 있으면 쓰지 않음. 자명한 선택은 알아서 진행하고, 답에 따라 다음 행동이 실제로 달라지는 경우에만 호출.

동작 방식

항목 설명
질문 개수 한 번에 1~4개
선택지 질문당 2~4개. “Other(직접 입력)”는 자동 추가
단일/복수 multiSelect로 복수 선택 허용 가능
추천 추천 옵션을 맨 앞에 두고 라벨에 “(Recommended)” 표기
미리보기(preview) UI 목업·코드 스니펫·다이어그램을 나란히 비교 (단일 선택만 지원)

언제 쓰고 / 안 쓰나

구분 예시
✅ 쓴다 “인증을 JWT? 세션?” — 방향이 갈리고 사용자 취향·정책이 결정 요인일 때
✅ 디자인 시안 A/B/C를 미리보기로 비교시켜 고르게 할 때
❌ 안 쓴다 코드베이스를 뒤지면 나오는 사실 확인
❌ “이대로 진행할까요?”, “계획 괜찮나요?” 같은 단순 승인
❌ 관례적 기본값이 명백한 선택 (그냥 진행하고 언급만)

Plan Mode와의 관계 (헷갈리기 쉬움)

한 줄 요약: “AI가 임의로 정하면 안 되는 갈림길에서, 버튼형 선택지로 사용자에게 결정을 넘기는 구조화 질문 도구.” 🔗 2번(SDD)의 “추측 대신 명세를 명확히” 정신과 통함 — 모호하면 추측 말고 사용자에게 확인.

4. PRD (Product Requirements Document, 제품 요구사항 문서)

“무엇을, 왜, 누구를 위해 만드는가”를 정의하는 제품 기획 문서. 주로 PM이 작성, 개발·디자인·QA 전원이 같은 그림을 보게 하는 기준점.

PRD에 들어가는 것

항목 내용
배경/문제 왜 만드는가, 어떤 문제를 푸는가
목표/성공지표 무엇을 달성하면 성공인가 (KPI)
사용자/시나리오 누가, 어떤 상황에서 쓰는가
기능 요구사항 어떤 기능이 필요한가 (무엇을)
범위(scope) 할 것 / 안 할 것(out of scope)
제약/가정 일정·기술·정책 제약

핵심: PRD는 “어떻게(How)”는 거의 안 적음. 그건 설계 문서·기술 스펙의 몫.

왜 필요한가

이유 설명
정렬(alignment) PM·개발·디자인·QA가 같은 목표 공유 → 제각각 만드는 사고 방지
의사결정 기준 기능 논쟁 시 “PRD 목표에 맞나?”로 판단
범위 통제 scope를 못 박아 기능 무한증식(scope creep) 방지
검증 기준 QA·테스트가 “요구대로인가” 확인하는 근거

PRD vs 요구사항 정의서

구분 PRD 요구사항 정의서 (Requirements Spec)
관점 제품/비즈니스 (Why·What) 시스템/공학 (What을 빠짐없이)
작성자 주로 PM 분석가(BA)·SI 설계자
문화권 실리콘밸리·애자일·스타트업 전통 SI·SRS(IEEE) 계열
내용 배경·목표·지표·시나리오·범위 기능/비기능 요구를 ID 부여해 나열
상세도 서술형(narrative), 유연 항목별·형식적·추적 가능
비기능 요구 가볍게 언급 성능·보안·가용성 등 정식 명세
변경 살아있는 문서, 자주 갱신 승인 후 비교적 고정(변경관리)

SDD와의 연결

2번 SDD의 Specify 단계가 사실상 PRD/요구사항 정의서 역할.

SDD:   Specify(spec.md) → Plan → Tasks → Implement
대응:  PRD/요구사항정의서  설계   할일분해   코드

한 줄 요약: PRD = “왜·무엇을·누구를 위해”의 제품 기획서, 요구사항 정의서 = “시스템이 충족할 요구를 빠짐없이 명세한 공학 문서”. PRD가 더 상위·서술형, 요구사항 정의서가 더 형식적·추적형.

5. Meta-Prompt (메타 프롬프트)

한마디로 “프롬프트를 위한 프롬프트”. AI에게 직접 일을 시키는 대신, 좋은 프롬프트를 만들어달라 / 프롬프트를 다루는 규칙을 정해달라고 시키는 상위(上位) 프롬프트.

개념 한 줄

대상이 내용(content)이 아니라 프롬프트 그 자체라는 게 핵심.

주요 쓰임새

용도 설명 예시
프롬프트 생성 다른 AI(또는 자신)에게 줄 프롬프트 작성 “전문 카피라이터용 시스템 프롬프트 만들어줘”
프롬프트 개선 기존 프롬프트 약점 찾아 다시 씀 “이 프롬프트 모호한 부분 고쳐 다시 써줘”
틀/템플릿 정의 답변 형식·규칙·사고 절차를 먼저 규정 “모든 답은 [요약→근거→결론] 순서로”
자동화 파이프라인 LLM이 LLM에게 줄 지시를 동적 생성 에이전트가 서브에이전트용 프롬프트 즉석 작성

왜 쓰는가

이전 노트 개념과의 연결

사례 어떻게 메타 프롬프트인가
서브에이전트 정의(이전 10번) 메인이 서브에이전트에게 줄 시스템 프롬프트를 작성
dynamic workflow(이전 15번) agent(prompt, ...)의 prompt를 코드가 동적 생성
CLAUDE.md / 규칙 “앞으로 이렇게 답하라”는 답변 틀 규정
deep-interview, planner 좋은 명세를 끌어내기 위한 질문 자체를 설계

주의점

한 줄 요약: 메타 프롬프트 = “무엇을 하라”가 아니라 “어떻게 시킬지(=프롬프트)를 만들어내거나 규정하는” 한 단계 위의 프롬프트.

6. Context Engineering (컨텍스트 엔지니어링)

LLM에게 “무엇을·어떤 형태로·얼마나” 컨텍스트를 넣어줄지 설계·관리하는 기술. 좋은 답의 핵심이 “프롬프트 문장 잘 쓰기” → “컨텍스트 창을 잘 채우고 관리하기”로 옮겨가며 부상.

프롬프트 엔지니어링과의 차이

구분 프롬프트 엔지니어링 컨텍스트 엔지니어링
초점 지시문(질문) 문장 잘 쓰기 컨텍스트 창 전체 설계·관리
단위 한 번의 프롬프트 시스템 프롬프트+도구+메모리+검색+히스토리
비유 “질문을 잘 던지기” “책상 위에 필요한 자료만 딱 깔아두기”

프롬프트 엔지니어링은 컨텍스트 엔지니어링의 부분집합.

왜 중요한가

LLM은 컨텍스트 창에 들어온 것만 보고 답함.

구성 요소

요소 내용
시스템 프롬프트 역할·규칙·출력 형식
지식 주입 RAG(검색 증강), 문서, 코드 파일
메모리 세션 넘는 영구 기억 (이전 5번)
도구(tools) 모델이 쓸 함수·API 정의
히스토리 관리 압축(compaction)·요약·잘라내기
순서·배치 무엇을 앞/뒤에 둘지 (이전 4번 로드 순서)

주요 기법

기법 설명
Retrieval (RAG) 필요한 문서만 그때그때 검색해 주입
Compaction (압축) 긴 대화를 요약해 핵심만 유지 (/compact)
Isolation (격리) 서브에이전트로 분리 → 메인 컨텍스트 안 더럽힘 (이전 10번)
Lazy loading (지연 로드) 필요할 때만 메모리·규칙 로드 (이전 4번)
Structured output 스키마로 출력 형태 고정 (workflow의 schema)

이전 노트와의 연결 (이 환경이 통째로 컨텍스트 엔지니어링)

한 줄 요약: 컨텍스트 엔지니어링 = “모델의 제한된 컨텍스트 창에, 꼭 필요한 정보만 적절한 형태·순서·시점으로 채워 최상의 답을 끌어내는 설계 기술.” 프롬프트 엔지니어링의 확장판.

7. Claude 권한 모드 (Permission Modes)

“Claude가 도구를 실행할 때 사용자에게 얼마나 물어보는가”를 정하는 설정. 자유도 ↔ 안전성 트레이드오프.

모드별 특징

모드 한 줄 정의 물어보는 정도 코드 수정
default (기본) 매 작업마다 허락받음 높음 (매번) 매번 승인
plan (플랜) 읽기만, 수정 금지 계획 제시 후 승인 ❌ 차단
acceptEdits (수락) 파일 편집은 자동 승인 중간 자동 (편집류만)
auto (자동) 대부분 자동 진행 낮음 자동
dontAsk 거의 안 물어봄 매우 낮음 자동
bypassPermissions (우회) 모든 권한 검사 건너뜀 없음 전부 자동

각 모드 상세

전환 / 적용

방법 설명
Shift+Tab 세션 중 모드 순환 전환
CLI 플래그 claude --permission-mode plan
서브에이전트별 정의의 permissionMode 필드 (이전 10번)
settings.json 기본 모드 설정

안전 ↔ 자유도 스펙트럼

안전·확인많음 ←──────────────────────────→ 빠름·확인적음
 plan → default → acceptEdits → auto → dontAsk → bypassPermissions
 (수정X)  (매번)   (편집자동)  (대부분자동)      (전부 무확인⚠️)

한 줄 요약: plan=구경만, default=매번 확인, acceptEdits=편집 자동(위험작업은 확인), auto/dontAsk=거의 자동, bypass=무조건 실행(위험). 보통 default 시작 → 신뢰되면 acceptEdits가 권장 흐름.

8. Ultra Plan (ultrathink·ralplan)

⚠️ 딱 떨어지는 공식 기능명은 아님. 보통 “계획 단계에 최대 사고력 또는 멀티 에이전트 합의를 투입하는 것”을 가리킴.

1) ultrathink + 플랜 = 최대 사고력으로 계획

Claude의 사고(thinking) 예산 키우는 키워드: think < think hard < think harder < ultrathink(최대). 플랜에 ultrathink를 같이 쓰면 → 답하기 전 훨씬 길고 깊게 추론 후 계획 산출.

왜 쓰나 설명
계획 오류 비용이 큼 방향 잘못 잡으면 구현 전체가 헛수고 → 앞단에 사고력 집중
복잡한 아키텍처 결정 트레이드오프·엣지케이스 깊게 따질 때
한 번에 제대로 얕은 계획으로 여러 번 고치느니 깊게 한 번

2) OMC ralplan = 합의 기반 계획

이 환경(OMC) 전용 스킬. 모호한 ralph/autopilot/team 요청을 여러 관점으로 계획→합의(consensus) 본 뒤 실행으로 넘기는 게이트. 더 견고하지만 토큰 더 씀.

토큰 많이 먹나? → 네, 더 먹음

무엇이 토큰을 먹나 정도
ultrathink (깊은 사고) 사고 토큰 대량 생성 → 비용·지연 ↑
plan 모드 자체 거의 안 먹음 (그냥 “수정금지+계획제시” 모드)
ralplan (멀티 에이전트) 에이전트 여러 개 → 많이 씀 (1번 Token Maxxing 맥락)

토큰을 먹는 건 plan 모드가 아니라 “깊은 사고·멀티 에이전트” 쪽. 플랜 모드만 켜는 건 비용 거의 0.

언제 쓰고 / 아끼나

상황 권장
크고 위험하고 되돌리기 어려운 작업 ✅ 깊게 계획 — 비용 < 실수 비용
아키텍처·설계 갈림길 ✅ 가치 있음
작고 자명한 작업 / 단순 수정 ❌ 과함. 돈·시간 낭비

한 줄 요약: “ultra plan” = 계획에 최대 사고력(ultrathink) 또는 멀티 에이전트 합의(ralplan)를 투입. 토큰은 깊은 사고·에이전트 때문에 많이 먹지, 플랜 모드 자체는 거의 안 먹음. 고위험·복잡 작업에만 효율적.

9. Harness Engineering (하네스 엔지니어링)

모델 자체가 아니라, 모델을 둘러싼 “작업 골격(harness)”을 설계하는 기술. 모델은 그대로 두고, 잘 일하도록 감싸는 제어흐름·도구·검증 장치를 어떻게 짜느냐가 핵심.

“하네스”란?

원래 말 안장·등반 안전벨트처럼 “무언가를 붙잡아 제어하는 장치”. AI에선 → 모델을 감싸 “입력 주고 → 도구 쓰게 하고 → 출력 받고 → 검증·반복”하는 실행 골격. 똑똑한 엔진(모델)을 레일 위에 올려놓는 장치. (혼자 두면 goal drift·agentic laziness)

구성 요소

요소 내용
제어 흐름 루프·조건·팬아웃을 모델 즉흥 아닌 코드로 확정
작업 분해 큰 일을 잘게 쪼개 독립 컨텍스트로 분배
도구 연결 모델이 쓸 함수·API·파일 접근 정의
검증 루프 적대적 검증·재시도·”끝날 때까지 반복”
출력 구조화 스키마로 결과 형태 강제

왜 중요한가

같은 모델이라도 하네스 설계에 따라 품질이 크게 갈림.

이전 노트와 연결 (이 환경이 곧 하네스)

개념 하네스에서의 역할
dynamic workflow(이전 15번) 하네스를 JS 코드로 즉석 작성 = 정수
서브에이전트(이전 10번) 하네스 안의 일꾼
Agent Teams(이전 13번) 협업형 하네스
ultracode / Token Maxxing(이전 16·1번) “맞춤 하네스 알아서 짜라”는 모드
컨텍스트 엔지니어링(6번) 각 단계에 무엇을 컨텍스트로 줄지

블로그 “A harness for every task” = 작업마다 맞춤 하네스를 짠다.

세 가지 “엔지니어링” 비교

구분 다루는 대상
프롬프트 엔지니어링 지시문 문장
컨텍스트 엔지니어링 모델에 넣는 정보(컨텍스트 창)
하네스 엔지니어링 모델을 감싸는 실행 골격 전체

→ 점점 바깥 레이어로 확장. 하네스가 최상위 골격, 그 안에서 컨텍스트·프롬프트를 다룸.

한 줄 요약: 하네스 엔지니어링 = “모델은 그대로, 모델이 일을 잘하도록 감싸는 제어흐름·도구·검증·반복 골격을 설계하는 기술.” dynamic workflow가 이를 코드로 즉석 구현한 형태.

10. MCP (Model Context Protocol)

AI 모델이 외부 도구·데이터에 연결하는 표준 규약. Anthropic이 2024년 공개. 흔히 “AI 앱을 위한 USB-C 포트”로 비유 — 어떤 도구든 같은 규격으로 꽂으면 AI가 쓸 수 있음.

MCP 호스트·클라이언트·서버 관계도

그림: MCP host ↔ MCP client(1:1) ↔ MCP server 관계. 출처: Wikimedia Commons — “Model Context Protocol Component diagram” (CC BY-SA).

왜 필요한가 (M×N 문제)

없을 때 있을 때
앱마다·도구마다 제각각 연동 (M앱 × N도구 = M×N) 표준 하나로 통일 → M+N개만
GitHub용·Slack용·DB용 다 따로 MCP 서버 하나면 어떤 MCP 호환 AI든 사용

핵심: “한 번 만들면 어디서나 꽂힌다” — 연동의 표준화.

구조 (Client ↔ Server)

[AI 앱 = MCP 호스트/클라이언트]  ←─ MCP 규약 ─→  [MCP 서버]
 예: Claude Code, 데스크탑                       예: GitHub, DB, 파일시스템
구성 역할
Host (호스트) MCP를 쓰는 AI 앱 (Claude Code 등)
Client (클라이언트) 호스트 안에서 서버와 1:1 연결
Server (서버) 실제 도구·데이터를 MCP 규약으로 노출

MCP 서버가 제공하는 3가지

종류 설명 예시
Tools (도구) AI가 호출하는 함수·액션 “이슈 생성”, “DB 쿼리”
Resources (리소스) AI가 읽는 데이터 파일 내용, DB 레코드
Prompts (프롬프트) 미리 정의된 프롬프트 템플릿 “코드 리뷰용 프롬프트”

이 환경의 MCP (연결됨)

서버 용도
context7 라이브러리·프레임워크 최신 공식 문서 조회
claude_ai 커넥터 Notion·Linear·Asana·Figma 등 SaaS 연동
oh-my-claudecode OMC 전용 도구(메모리·LSP·상태관리 등)

도구 이름이 mcp__<서버>__<도구> 형식인 게 증거 (이전 9번 MCP 도구 훅 이름 규칙과 동일).

연결 방식 (Transport)

방식 설명
stdio 로컬에서 프로세스로 실행 (표준입출력)
HTTP/SSE 원격 서버에 네트워크로 연결

이전 노트와 연결

한 줄 요약: MCP = “AI와 외부 도구·데이터를 잇는 표준 규약(=AI용 USB-C).” 서버 한 번 만들면 어떤 MCP 호환 AI든 사용 → M×N 연동 지옥을 M+N으로 축소. 제공물은 Tools·Resources·Prompts 3가지.

11. Superpowers 플러그인 & Visual Companion

출처: github.com/obra/superpowers, mindstudio.ai/blog/what-is-superpowers-plugin-claude-code 등

Superpowers란?

Jesse Vincent(obra)가 만든 오픈소스 Claude Code 플러그인 — 에이전트 스킬 모음(한 번에 14개 설치). Claude를 5단계 규율로 강제해 “일단 코딩부터” 하는 실패 모드를 차단:

clarify(명확화) → design(설계) → plan(계획) → code(구현) → verify(검증)

Visual Companion이 하는 일

코드를 한 줄도 짜기 전에, 브라우저에 임시 HTML 대시보드를 띄워 디자인 시안을 미리 보여주는 스킬.

clarify/brainstorming 단계에서 자동 발동.

보여주는 것 설명
레이아웃 목업 화면 배치 시안 여러 개
색상 팔레트 컬러 옵션들
컴포넌트 대안 UI 요소 후보들
인터랙티브 프리뷰 즉석 생성된 미리보기

→ 실제 프로젝트 코드가 생기기 전에 브라우저에서 즉석으로 띄워 시각적으로 합의.

왜 좋은가

이전 노트 개념과 연결

Visual Companion만 단독(standalone) 사용

Superpowers 플러그인 전체(5단계 규율 등)를 안 깔아도 이 기능만 단독으로 쓸 수 있음. 실제로 이 환경엔 visual-companion이 독립 실행형 스킬로 이미 제공됨 (인터랙티브 목업·다이어그램·와이어프레임·레이아웃 비교·시각 브레인스토밍·클릭형 옵션 선택).

쓰는 법

방법 설명
자연어 요청 “와이어프레임 시안 3개 보여줘”, “이 화면 목업 브라우저로 띄워줘” → Claude가 스킬 발동
명시 호출 스킬을 직접 지정 (/visual-companion 류)

플러그인에서 스킬 하나만 빼기 (일반론)

한 줄 요약: Visual Companion = “코딩 전에 레이아웃·색상·컴포넌트 시안을 브라우저 대시보드로 미리 보여줘 스타일 재작업을 없애주는” Superpowers의 디자인 미리보기 스킬. 이 환경에선 단독 스킬로도 사용 가능.

12. Socratic Reasoning & Ouroboros (MCP)

둘은 밀접 — Ouroboros가 Socratic Reasoning을 핵심 엔진으로 씀. 출처: github.com/Q00/ouroboros

A. Socratic Reasoning (소크라테스식 추론)

답을 바로 주는 대신 “질문을 던져” 숨은 전제·모호함을 드러내며 진실에 다가가는 추론법. 소크라테스 문답법에서 유래. 핵심은 “질문만으로(questions-only)” 말 안 한 가정을 끄집어내는 것.

단계 내용
전제 드러내기 “그게 왜 그렇다고 생각하죠?”
모호함 추궁 “여기서 ‘X’는 정확히 뭘 의미하나요?”
반례 탐색 “이게 안 통하는 경우는?”
합의 도달 답이 충분히 명확해질 때까지 반복

AI 코딩에서 왜 쓰나: “대부분의 AI 코딩 실패는 코드가 아니라 입력(요구사항)에서 발생”. 막연한 요구를 그대로 받으면 추측(환각·goal drift) → Socratic 질문으로 코드 전에 모호함을 0에 가깝게 제거.

🔗 SDD Specify 단계(2번), deep-interview 스킬이 바로 이 방식.

B. Ouroboros (MCP) — “Agent OS”

AI 코딩의 비결정적 작업을 재현·관찰 가능한 실행 계약으로 바꾸는 로컬 런타임 계층. 이름(자기 꼬리 무는 뱀) = “출력이 다시 입력으로 순환하는 진화 루프”. 태그라인: “Stop prompting. Start specifying.”

핵심 워크플로 (순환 루프)

Interview → Seed → Execute → Evaluate → Evolve → (다시 Interview...)
단계 내용
Interview Socratic 질문으로 가정·모호함 노출 (모호함 수학적 점수화, ≤0.2 명확도 임계)
Seed 답변을 불변 명세 문서 + 인수 기준으로 결정화
Execute “Double Diamond” 분해 모델로 구현
Evaluate 3단계 검증 게이트 (기계적→의미적→합의)
Evolve 출력을 다음 세대 입력으로 피드백 → 수렴까지 반복

MCP 서버로 노출하는 도구

도구 역할
evaluate 결과 검증
evolve 다음 세대로 진화
unstuck 측면적 사고 페르소나로 막힘 해소
ralph 지속 루프 (OMC ralph와 같은 발상)
pm 제품 관리(PM) 인터뷰

특징: 멀티 런타임(Claude Code·Codex·Gemini 등, ooo <cmd> 호출) · 수렴 감지(95% 유사도) · 정체(stagnation) 4패턴 감지 · 이벤트 소싱 영속화 · PAL Router 비용 최적화

둘의 관계 + 이전 노트 연결

Socratic Reasoning = 추론 "방법론" (질문으로 모호함 제거)
        │ (Interview 단계에 탑재)
        ▼
Ouroboros (MCP)    = 그 방법론을 SDD·진화루프로 제품화한 "Agent OS"

한 줄 요약: Socratic Reasoning = 질문으로 숨은 전제를 드러내 모호함을 없애는 추론법. Ouroboros = 그걸 Interview 단계에 탑재해 “인터뷰→명세→실행→검증→진화”를 순환시키는 SDD형 Agent OS(MCP 서버).

13. Interview 모드

📊 시각 다이어그램(Artifact): https://claude.ai/code/artifact/4077f859-0c24-416b-9dd7-cf259a85098b (A. 모호함 깔때기: 요청→질문 게이트→명세→구현 / D. 우로보로스 진화 루프)

AI가 곧장 작업에 들어가는 대신, 먼저 “질문을 던지며” 요구사항을 캐내는 동작 모드. Socratic Reasoning(12번)을 실제 도구로 구현한 형태. 핵심은 “실행 전 질문 단계를 강제”해 추측·goal drift를 차단.

일반 모드 vs Interview 모드

일반 모드 Interview 모드
요청 받으면 바로 코드/답 생성 요청 받으면 먼저 되묻는다
모호하면 알아서 추측 모호함이 충분히 줄 때까지 질문 반복
빠르지만 빗나갈 위험 느리지만 의도에 정확히 정렬

Ouroboros의 Interview 모드 (구체 사례)

순환 루프의 첫 단계 (12번): [Interview] → Seed → Execute → Evaluate → Evolve

특징 설명
questions-only 답 대신 질문만 던져 숨은 가정 노출
모호함 점수화 명확도를 수학적으로 측정, ≤0.2 도달해야 다음 단계
게이트 역할 임계값 못 넘으면 코드 생성으로 못 넘어감
Seed로 결정화 답변 → 불변 명세 문서 + 인수 기준
pm 도구 제품 관리(PM) 관점 인터뷰 별도 제공

→ Ouroboros Interview 모드 = “모호함이 수학적으로 충분히 낮아질 때까지 질문으로 잠가두는 게이트”.

다른 Interview 모드 비교

도구 방식 특징
Ouroboros Interview Socratic 질문 + 모호함 ≤0.2 게이트 수학적 임계값으로 진입 차단
OMC deep-interview Socratic 딥 인터뷰 + 수학적 게이팅 실행 승인 전 명시적 게이트
OMC planner 인터뷰 워크플로로 계획 수립 전략 계획 상담
Claude Plan Mode(7번) 질문보다 “계획 제시 후 승인” 인터뷰라기보단 승인 게이트

공통점: 모두 “실행 전에 의도를 확정” — SDD(2번) Specify, Socratic Reasoning(12번)을 모드로 구현.

이전 노트 연결

Socratic Reasoning (방법론, 12번)
        │ 모드로 구현
        ▼
Interview 모드 ──→ Ouroboros Interview / deep-interview / planner
        │ 결과물
        ▼
명세(Spec) = SDD Specify(2번) / PRD(4번)

한 줄 요약: Interview 모드 = “AI를 질문만 하는 상태로 잠가, 실행 전 요구사항의 모호함을 충분히 없애는 동작 모드.” Ouroboros는 “모호함 ≤0.2 수학적 게이트”로 엄격히 구현한 사례.

14. Ouroboros 사용법

출처: github.com/Q00/ouroboros 📊 진화 루프 다이어그램(D): https://claude.ai/code/artifact/4077f859-0c24-416b-9dd7-cf259a85098b ⚠️ 명령어는 /ouroboros:interview(슬래시)가 아니라 ooo <명령> 형식.

설치 (Claude Code)

# 1) 마켓플레이스 추가 + 플러그인 설치
claude plugin marketplace add Q00/ouroboros && claude plugin install ouroboros@ouroboros

# 2) Claude Code 세션 안에서 셋업
ooo setup

대안 (pip):

pip install ouroboros-ai[claude]
ouroboros setup

명령어 (세션 안에서 ooo <command>)

명령 역할
ooo interview "<목표>" Socratic 질문으로 숨은 가정 노출 (모호함 <0.2까지)
ooo seed 답변을 불변 명세(Spec)로 결정화
ooo run Double Diamond 분해로 실행
ooo evaluate 3단계 검증 게이트
ooo evolve 온톨로지 수렴까지 진화 루프
ooo ralph 검증될 때까지 지속 루프 (세션 경계 넘음)
ooo unstuck 막힐 때 5가지 측면적 사고 페르소나
ooo pm PM 인터뷰 + PRD 생성 (4번 PRD와 연결)
ooo status 세션 추적·드리프트 감지
ooo auto 목표 → A등급 Seed까지 자동(경계 루프)

사용 예시 — 인사/조직 관리 시스템

세션에서 이렇게 입력하면 Interview가 시작됨:

ooo interview "사내 인사/조직 관리 통합 시스템을 만들고 싶다.
필요 기능:
 1) 직원 관리  2) 조직 관리  3) 휴가 신청
 4) 근태 관리  5) 온보딩 관리  6) 퇴사 프로세스
 7) 모든 시스템에 접근 가능한 관리자 시스템
이 7개가 통합된 하나의 시스템으로."

→ Ouroboros가 곧장 코딩하지 않고 되물음: 권한 모델(관리자/일반 직원 구분?), 휴가 정책(연차 자동계산?), 근태 수집 방식(출퇴근 태그/지문/앱?), 온보딩 단계 정의, 조직도 변경 이력 보존 여부 등 → 모호함 <0.2 되면 자동으로 seed(명세) 생성.

전형적 흐름

ooo interview "<목표>"   → 질문으로 요구사항 확정
        ↓ (모호함 <0.2)
ooo seed                 → 불변 명세 문서 생성
        ↓
ooo run                  → 구현
        ↓
ooo evaluate / evolve    → 검증·진화 반복

💡 빠르게 가려면 ooo auto "<목표>" 하나로 목표→고품질 Seed까지 자동 진행 가능.

한 줄 요약: 설치 후 ooo interview "목표"로 시작 → 질문으로 요구사항을 확정(<0.2) → seed로 명세화 → run/evaluate/evolve로 구현·검증·진화. 슬래시가 아니라 ooo 프리픽스.

15. 우로보로스 ↔ MCP 관계 & “규약 vs 허브”

📊 시각 다이어그램(Artifact): https://claude.ai/code/artifact/41103e60-b1c9-4086-a35e-c0fc6862bb7d (① MCP 기본구조 ② 우로보로스 매핑 ③ 규약/서버/허브 3층 — 한 장 도식) 10번(MCP)·12~14번(Ouroboros)을 잇는 정리.

A. 우로보로스를 MCP 구조에 끼우면

[Claude Code]  ←─ MCP 규약 ─→  [Ouroboros MCP 서버]
 = MCP 호스트/클라이언트          = 도구 제공자
 (당신이 ooo 명령 입력)           (interview·evaluate·evolve... 노출)
MCP 구성 우로보로스에서는
Host (호스트) Claude Code
Server (서버) Ouroboros — “Agent OS” 런타임
Tools (도구) interview·seed·run·evaluate·evolve·unstuck·ralph·pm ← MCP Tools로 노출

→ 우로보로스의 워크플로 단계들(12·13·14번)이 사실 MCP Tools. Claude Code가 MCP 규약으로 호출.

B. ooo 명령 ↔ MCP (두 겹 구조)

겹 정체 사용자가 보는 것
표면 (플러그인/스킬) ooo interview 같은 명령어 타이핑하는 인터페이스
내부 (MCP 서버) 그 명령 = 실제로는 MCP Tool 호출 설치 시 호스트에 MCP 서버 등록

ooo 명령은 사람용 껍데기, 그 밑에서 MCP 프로토콜로 Claude Code ↔ Ouroboros가 대화. MCP 표준 덕에 Claude뿐 아니라 Codex·Gemini·Copilot에서도 동일 동작.

C. MCP = “규약”이지 “허브”가 아님 (헷갈림 주의)

MCP 자체는 규약(프로토콜)이고, 서버를 모아둔 허브(마켓플레이스)는 별개 층.

비유 MCP는 이것 허브/마켓은 이것
USB USB 규격(포트·통신 방식) USB 기기 파는 상점
콘센트 220V 콘센트 표준 전자제품 매장
층 정체 예
규약 (MCP) 어떻게 통신할지 표준 Model Context Protocol
서버 그 규약으로 만든 도구 Ouroboros, GitHub MCP, context7
허브/마켓 서버를 모아둔 카탈로그 Claude plugin marketplace, MCP 디렉토리

14번의 claude plugin marketplace add ...의 marketplace가 “허브”, MCP는 그 안 서버들이 따르는 규격. 쉽게: MCP=콘센트 규격, 마켓플레이스=전자제품 매장, Ouroboros=그 콘센트에 꽂는 가전.

한 줄 요약: 우로보로스 = MCP 서버로 구현된 Agent OS. Claude Code(호스트)가 MCP 규약으로 우로보로스 도구(interview·evaluate·evolve…)를 호출. ooo는 그 사람용 껍데기. MCP는 “규약”이지 “허브”가 아님 — 허브는 서버를 모아 파는 별도 마켓.

참고: 각 CLAUDE.md 파일은 200줄 이하로 유지하는 것을 권장