Claude Code 정리 노트 — SDD·컨텍스트 엔지니어링·MCP·Ouroboros

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

1. Token Maxxing (토큰 맥싱)

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

개념 한 줄

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

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

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

구체적인 행동 패턴

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

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

dynamic workflow(이전 노트 15번) — JS 코드로 수십~수백 서브에이전트를 결정론적 조율
ultracode(이전 노트 16번) — effort=xhigh + 워크플로 자동 사용. 사실상 “Token Maxxing 스위치”
Agent Teams(이전 노트 13번) — 팀원끼리 소통하며 병렬 작업
토큰 예산 지정 가능: 프롬프트에 +500k 같은 식으로 한도 부여

언제 쓰나 / 주의점

구분	내용
✅ 유리	깊은 리서치, 대규모 리팩터, 보안 감사 — 비용보다 정확도가 우선일 때
⚠️ 과함	단순·일회성 작업에 멀티 에이전트는 낭비. 비용·지연(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” 단계를 돕는 도구

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

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

개념 한 줄

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

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

동작 방식

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

언제 쓰고 / 안 쓰나

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

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

플랜 모드 진입은 이 도구가 아니라 별도 EnterPlanMode를 씀
플랜 모드 안에서 요구사항을 좁히거나 접근법을 고를 때 이 도구를 사용
“계획 다 됐나요?”처럼 계획 자체를 묻는 데는 쓰면 안 됨 → 그건 ExitPlanMode로 승인

한 줄 요약: “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), 유연	항목별·형식적·추적 가능
비기능 요구	가볍게 언급	성능·보안·가용성 등 정식 명세
변경	살아있는 문서, 자주 갱신	승인 후 비교적 고정(변경관리)

PRD = “왜·무엇을·누구를 위해” (제품 관점, 상위)
요구사항 정의서 = “시스템이 충족할 요구를 빠짐없이·추적 가능하게” (공학 관점, 하위)
실무 흐름: PRD → 요구사항 정의서 → 설계서 → 코드

SDD와의 연결

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

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

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

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

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

개념 한 줄

일반 프롬프트: “이 글을 요약해줘”
메타 프롬프트: “이 작업을 가장 잘 시킬 프롬프트를 네가 작성해줘”

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

주요 쓰임새

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

왜 쓰는가

프롬프트 작성 부담을 AI에 위임 — “잘 시키는 법”을 AI가 더 잘 알 때가 많음
일관성·재사용 — 한 번 잘 만든 메타 프롬프트로 비슷한 프롬프트 양산
자기개선 루프 — AI가 자기 출력을 보고 프롬프트를 다듬어 품질 향상

이전 노트 개념과의 연결

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

주의점

추상 한 겹 더 — 잘못 쓰면 AI가 “프롬프트 얘기”만 하고 정작 일을 안 함 → 목적 분명히
단순 작업엔 과함. 반복·대량·고품질이 필요할 때 진가

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

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

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

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

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

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

왜 중요한가

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

부족 → 추측·환각 (goal drift)
과다 → Context Rot(컨텍스트 부패): 토큰 많아질수록 중간 정보 놓치고 정확도·속도↓, 비용↑
핵심은 양이 아니라 신호 대 잡음비 — 꼭 필요한 정보만 적시에

구성 요소

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

주요 기법

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

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

메모리·MEMORY.md 인덱스 + 지연 로드(5번) = 컨텍스트 가볍게 유지
서브에이전트 격리(10번) = 잡음 격리
Rewind의 Summarize(11번) = 히스토리 압축
dynamic workflow / Token Maxxing(15·1번) = 작업을 쪼개 각 컨텍스트를 깨끗하게

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

7. Claude 권한 모드 (Permission Modes)

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

모드별 특징

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

각 모드 상세

default: 가장 안전, 민감 작업마다 확인. 작업 많으면 느림
plan: 읽기·탐색만, 변경·실행 차단. 계획 보여주고 ExitPlanMode 승인해야 실행
acceptEdits: 편집(Edit/Write)은 자동, rm 등 위험 명령·새 유형은 여전히 확인 → 실무 균형점
auto / dontAsk: 대부분 자동 진행, 개입↓ 위험↑
bypassPermissions: 전부 무확인 ⚠️ 가장 위험. 격리 환경(컨테이너·CI)에서만 권장

전환 / 적용

방법	설명
`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·파일 접근 정의
검증 루프	적대적 검증·재시도·“끝날 때까지 반복”
출력 구조화	스키마로 결과 형태 강제

왜 중요한가

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

모델 성능 향상 = 비싸고 느림(재학습)
하네스 개선 = 즉시·저렴 → “모델 그대로, 골격만 바꿔 성능↑”
AI 엔지니어링 무게중심이 모델 튜닝 → 하네스 설계로 이동

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

개념	하네스에서의 역할
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 도구 훅(이전 9번) — MCP 호출 가로채기 / 훅이 MCP 도구 부르기
서브에이전트 mcpServers 필드(이전 10번) — 전용 MCP 서버 지정
하네스 엔지니어링(9번) — MCP는 하네스의 “도구 연결” 부품

한 줄 요약: 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(검증)

"using superpowers" 마스터 디스패처가 대화 시작 시 자동 활성화 → 작업에 맞는 스킬로 라우팅

Visual Companion이 하는 일

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

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

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

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

왜 좋은가

핵심 효과: “스타일 관련 재시도를 기능당 평균 4회 → 0회” (테스트 결과)
“만들고 → 이거 아닌데 → 다시”의 비싼 왕복을 앞단에서 시각 합의로 제거 → 토큰·비용 절감

이전 노트 개념과 연결

SDD / Specify 단계(2번) — “코드 전에 명세·디자인 먼저”의 시각화 버전
AskUserQuestion의 preview(3번) — 시안을 나란히 비교시켜 고르게 하는 발상과 동일
Artifact — HTML 아티팩트 발행 기능 활용

Visual Companion만 단독(standalone) 사용

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

쓰는 법

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

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

Superpowers 스킬들은 그냥 마크다운 스킬 파일 → 원하는 스킬 폴더(visual-companion)만 복사
~/.claude/skills/(유저 전역) 또는 프로젝트 .claude/skills/에 두면 단독 동작
즉 플러그인 통째 설치 없이 개별 스킬만 추출 가능

한 줄 요약: 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"

SDD(2번): “Stop prompting. Start specifying.” = 명세 주도 그 자체
하네스 엔지니어링(9번): Interview~Evolve를 강제하는 완성형 하네스
ralph/deep-interview(OMC): Ouroboros의 ralph·Interview와 같은 계보

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

13. Interview 모드

A. 모호함 깔때기 (Ambiguity Funnel)

모호함 깔때기 다이어그램

D. 우로보로스 진화 루프 (Ouroboros Evolution Loop)

우로보로스 진화 루프 다이어그램

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 ⚠️ 명령어는 /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 허브”

10번(MCP)·12~14번(Ouroboros)을 잇는 정리.

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

우로보로스 ↔ MCP 매핑 — 워크플로 단계 = MCP Tools

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 규약 vs 허브 — 3층 구조와 USB/콘센트 비유

비유	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는 “규약”이지 “허브”가 아님 — 허브는 서버를 모아 파는 별도 마켓.

16. 플랜 접근법 선택 가이드 (내 사용 기준)

계획 단계에서 “무엇으로 시작할지” 고르는 개인 기준 정리. 오늘 노트의 7·8·11·12·13번을 실전 선택지로 묶음.

한눈 선택표

접근법	언제 쓰나	비고
기본 플랜모드	일반적인 계획	Claude Code 표준(수정 전 계획 승인). 7번
울트라플랜	초기 큰 작업	깊은 사고(ultrathink)·멀티에이전트. 토큰↑. 8번
우로보로스	완전히 빈 상태 / 첫 프로젝트 세팅	greenfield에 아주 강함. 12·14번
딥인터뷰	가벼운 요구 명확화 (우로보로스의 경량판)	세부 조절은 OMC 딥인터뷰로. 13번
딥다이브	딥인터뷰인데 내용을 더 깊이 살피고 싶을 때	trace(원인 조사)+딥인터뷰. 더 철저
비주얼 컴패니언	위 인터뷰를 시각적으로 보고 싶을 때	⚠️ 인터뷰 자체가 아니라 인터뷰 인터페이스(시각화 레이어). 11번

핵심 메모 (내 관점)

우로보로스 = 0→1: 아무것도 없는 빈 상태·첫 세팅에 최고. 질문으로 바닥부터 명세를 세움
딥인터뷰 = 우로보로스 약소(경량) 버전: 더 가볍게 요구 명확화. 조절·튜닝이 필요하면 OMC에 있는 딥인터뷰를 씀 (--quick/--standard/--deep, 임계값 조정 — 14번)
딥다이브 > 딥인터뷰: 딥인터뷰를 쓰되 내용을 더 꼼꼼히 파고들고 싶으면 딥다이브가 낫다 (코드/원인 trace 먼저)
비주얼 컴패니언은 “인터뷰”가 아님: 인터뷰 내용을 눈으로 비교·선택하게 해주는 시각 인터페이스. 인터뷰 로직과 별개 레이어

고르는 흐름

빈 상태·첫 프로젝트 세팅?     → 우로보로스
초기 큰 작업?                → 울트라플랜
가볍게 요구만 명확히?         → 딥인터뷰 (조절은 OMC 딥인터뷰)
내용 더 깊이 살펴야?          → 딥다이브
시각적으로 보며 고르고 싶다?  → 비주얼 컴패니언 (인터페이스로 얹기)
그 외 일반 계획?             → 기본 플랜모드

한 줄 요약: 빈 상태=우로보로스, 큰 초기작업=울트라플랜, 가벼운 명확화=딥인터뷰(조절은 OMC), 더 깊게=딥다이브, 시각화=비주얼 컴패니언(인터뷰 아님·인터페이스), 일반=기본 플랜모드.

17. Loop Engineering (루프 엔지니어링)

출처: Addy Osmani “Loop Engineering”, LangChain/O’Reilly 등 (2026년 6월 명명 — Peter Steinberger 제기 → Addy Osmani 정립)

개념 한 줄

AI 에이전트를 “행동→관찰→결정→반복” 순환으로 굴리는 시스템을 설계하는 기술. 매 단계 사람이 손으로 프롬프트하는 대신, 에이전트를 계속 굴리는 루프 자체를 짠다.

핵심 전환

기존: 내가 턴마다 에이전트에게 프롬프트 입력
루프 엔지니어링: “에이전트를 프롬프트하는 시스템”을 내가 설계 → 그 시스템이 일을 발굴하고 → 서브에이전트에 분배하고 → 결과 검증하고 → 상태 저장하고 → 다음 행동 결정 (스케줄대로 또는 목표 달성까지)

네 가지 “엔지니어링” 확장 (6·9번 연장선)

단계	다루는 대상
프롬프트 엔지니어링	보내는 문장
컨텍스트 엔지니어링(6번)	모델이 보는 모든 정보
하네스 엔지니어링(9번)	에이전트가 도는 환경(1회 실행 골격)
루프 엔지니어링	에이전트를 목표까지 반복 구동하는 순환

관계: 하네스 = 한 번의 실행을 갖춰줌 / 루프 = 스케줄대로 계속 에이전트를 찌르고, 헬퍼를 띄우고, 스스로에게 피드백. 하네스의 바깥을 한 겹 더 감싼 것.

루프가 하는 일 (구성)

요소	설명
일 발굴(discover)	무엇을 할지 스스로 찾음
분배(delegate)	서브에이전트에 태스크 위임
검증(verify)	결과가 맞는지 확인
상태 저장(persist)	세션 넘어 진행 상태 보존
종료 판단	목표 충족/조건까지 반복할지 결정

이전 노트·OMC와 연결

Token Maxxing(1번)·dynamic workflow: 루프를 코드로 굴리는 구현체
OMC ralph/ultragoal/autoresearch: 전형적 루프 엔지니어링 — “될 때까지/목표까지” 반복(OMC 노트 11번)
Claude /loop·/goal: 루프를 스케줄·완료조건으로 돌리는 기능
우로보로스 진화 루프(12·14번): Interview→…→Evolve 자기참조 루프 = 루프 엔지니어링의 한 형태

한 줄 요약: 루프 엔지니어링 = “내가 매번 프롬프트하는 사람”에서 “에이전트를 반복 구동하는 시스템을 설계하는 사람”으로의 전환. 프롬프트→컨텍스트→하네스 다음의 가장 바깥 레이어 — 발굴·분배·검증·상태저장·종료판단을 묶은 순환을 짜는 일.

18. Pencil.dev (디자인-투-코드 도구)

출처: pencil.dev. 슬로건 “Design on canvas. Land in code.”

정체 한 줄

IDE 안에 들어오는 디자인 캔버스. 캔버스에서 그리면 즉시 프로덕션 코드(HTML/CSS/React)로 변환되고, AI 코딩 에이전트(Claude Code·Cursor)가 MCP로 그 캔버스를 직접 조작할 수 있는 도구.

핵심 기능

기능	설명
Infinite Canvas	IDE 안 무한 캔버스 — 자연어 프롬프트로 UI를 그려 코드로 변환
MCP 연동	AI 에이전트가 사람 디자이너처럼 캔버스를 “보고” 그리고·옮기고·스타일 수정 (10번 MCP)
Git-native `.pen`	디자인을 JSON `.pen` 파일로 `/design` 폴더에 저장 → 코드처럼 git 버전관리, AI가 읽는 명세
Figma 복붙	Figma 벡터·스타일을 복사→붙여넣기로 가져와 작업
디자인 시스템 4종	Shadian · Halo · Lunarus · Nitro (토큰·패턴·반응형 규칙 내장)
가격	얼리액세스 100% 무료 (제한 없음)

코드 Export (상세)

캔버스 디자인을 여러 스택으로 코드 생성. 방식은 AI 채팅(Cmd/Ctrl + K)에 자연어로 요청 → 채팅으로 코드 산출.

분류	지원
프레임워크	React · Next.js · Vue · Svelte · 순수 HTML/CSS
스타일링	Tailwind CSS · CSS Modules · Styled Components · 바닐라 CSS
컴포넌트 라이브러리	shadcn/ui · Radix UI · Chakra UI · Material UI · 커스텀
아이콘	Lucide · Heroicons · FontAwesome · React Icons + 내장(Material Symbols·Feather·Phosphor)

Export 절차: ① 캔버스에서 디자인 → ② .pen 저장 → ③ Cmd/Ctrl + K로 AI 채팅 → ④ 자연어 요청 예시 프롬프트:

"이 버튼을 React 컴포넌트로 만들어줘"
"이 디자인을 Tailwind 쓰는 Next.js 페이지로 생성해줘"
"Shadcn UI 컴포넌트로 export 해줘"

양방향 동기화 (Design ↔ Code)

Design → Code: 캔버스 디자인 → 컴포넌트 코드 생성
Code → Design: "src/components/Button.tsx의 Button을 캔버스로 복원해줘" → 기존 코드를 캔버스로 가져옴
반복 사이클: 코드 import → 시각적으로 수정 → 다시 코드로 sync → 디자인/구현 drift 없음

변수·토큰 동기화

CSS → Pencil: "내 globals.css로 Pencil 변수 만들어줘"
Pencil → CSS: "이 디자인 토큰을 내 CSS로 sync해줘"
Pencil 변수가 CSS 변수에 매핑 → 공유 디자인 토큰 시스템 구축·유지에 실용적

설치·환경

VS Code / Cursor에 직접 설치 → 디자인과 코딩을 한 곳(IDE)에서
실행 시 로컬 MCP 서버 기동 → Claude Code·Cursor·Codex CLI·Claude Desktop·Windsurf 등 MCP 지원 도구가 캔버스를 직접 조작 (원격 API 거치지 않음)
AI에게 “이 컴포넌트 만들어”라고 하면 .pen의 정확한 좌표·토큰·구조를 읽어 코드 생성
Git-native: .pen을 코드 옆에 두고 commit·branch·merge. 롤백하면 디자인도 함께 롤백
Figma 복붙: 프레임 복사→붙여넣기로 레이어·오토레이아웃·스타일 보존

왜 의미 있나

디자인↔코드 사이 “전달(handoff)” 단절을 없앰 — 디자인이 곧 코드, 코드가 곧 디자인
AI 에이전트가 시각적으로 컴포넌트 단위로 만들며 즉시 피드백 → 텍스트만으로 UI 지시할 때의 오차 감소

이전 노트와의 연결 (이게 핵심)

개념	Pencil과의 관계
Visual Companion(11번)	둘 다 “코딩 전 시각화” — VC는 임시 미리보기, Pencil은 캔버스가 곧 산출물(.pen→코드)
MCP(10번)	Pencil은 MCP 서버로 캔버스를 노출 → AI가 도구로 조작 (우로보로스가 MCP인 것과 같은 구조)
SDD/명세(2번)	`.pen` = AI가 읽는 디자인 명세 → 시각 버전의 Spec
Figma 커넥터	오늘 환경의 claude_ai Figma MCP와 같은 디자인 연동 계보

한 줄 요약: Pencil.dev = IDE 안 무한 캔버스에서 디자인하면 코드로 떨어지고, AI 에이전트가 MCP로 그 캔버스를 직접 조작하는 디자인-투-코드 도구. .pen(git-native) 파일이 디자인 명세 역할. Visual Companion이 “미리보기”라면 Pencil은 “캔버스=산출물”.

19. DESIGN.md — 의의 · 오해 · 한계점

출처: designmd.app, Google Stitch, “DESIGN.md Explained” 등 (2026) 정체: 프로젝트 루트의 .md 파일로, AI 에이전트가 읽는 “디자인 시스템 명세”. 상단=기계가 읽는 토큰(YAML: 색·폰트·간격·radius·컴포넌트), 하단=사람이 읽는 근거(왜 이 값인지).

의의 (왜 쓰나)

AI는 내 디자인 시스템을 모른다 — 구조화된 참조가 없으면 매번 제멋대로(AI slop) UI 생성
DESIGN.md 하나면 Claude Code·Cursor·v0 등이 같은 브랜드·토큰으로 일관되게 UI 생성
CLAUDE.md가 DESIGN.md를 자동 참조하도록 설정 가능 → AI 지시의 3계층화:

파일	담당
AGENTS.md	행동(어떻게 일하나)
SKILL.md	작업(특정 절차)
DESIGN.md	외형(어떻게 보이나)

포터블·git-native·도구 중립 → 한 번 쓰면 여러 AI 도구에서 재사용 (이전 노트 SDD·명세 철학의 “디자인판”)

오해 (흔한 착각)

오해	실제
”Figma·디자인 툴을 대체한다”	❌ 디자인 캔버스가 아니라 명세(spec). 그리는 도구가 아님 (Pencil/Figma와 역할 다름, 18번)
“넣으면 픽셀 퍼펙트 보장”	❌ AI는 여전히 해석함 — 일관성을 높일 뿐 보장은 아님
”토큰만 덤프하면 끝”	❌ 근거(rationale)와 적용 규칙이 있어야 AI가 올바르게 적용
”디자인 시스템 그 자체다”	❌ 컴포넌트 코드가 아니라 그것을 기술한 문서 (Claude Design 같은 실제 컴포넌트와 구분)

한계점

강제력 없음 — CLAUDE.md·메모리처럼 “지시일 뿐 보장 아님”. AI가 무시·이탈(drift) 가능 (런타임 검증 게이트 아님)
동기화 문제 — 실제 코드/디자인이 바뀌면 DESIGN.md도 갱신해야. 어긋나면 오히려 혼란
컨텍스트 비용 — 너무 크면 컨텍스트 창을 잡아먹음 (6번 컨텍스트 엔지니어링 트레이드오프)
표현 한계 — 토큰·정적 규칙 중심. 복잡한 인터랙션·모션·“브랜드 감성”은 텍스트로 다 담기 어려움
품질 의존 — 잘 쓰여야 효과. 모호하면 AI도 모호하게 적용
검증 부재 — 결과가 명세대로인지 자동 확인 안 됨 → 별도 시각 QA 필요 (visual-verdict 같은 것, OMC 13번)

이전 노트와 연결

CLAUDE.md / 메모리(메인 노트): “지시 vs 강제”의 한계 동일 — 확실히 하려면 훅/검증 필요
Context Engineering(6번): DESIGN.md를 컨텍스트에 어떻게·얼마나 넣을지가 곧 품질
Visual Companion·Pencil(11·18번): 시각 생성/미리보기, DESIGN.md는 그 기준이 되는 명세 → 짝
SDD(2번): DESIGN.md = “디자인의 Specify”

한 줄 요약: DESIGN.md = AI가 읽는 디자인 시스템 명세(토큰+근거)로, 도구 중립적으로 일관된 UI를 만들게 하는 “외형 계층” 파일. 단, 디자인 툴 대체도·픽셀 보장도 아니고, 강제력 없음·동기화·컨텍스트 비용·검증 부재가 한계.

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

Claude Code 정리 노트 — SDD·컨텍스트 엔지니어링·MCP·Ouroboros

1. Token Maxxing (토큰 맥싱)

개념 한 줄

구체적인 행동 패턴

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

언제 쓰나 / 주의점

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

개념 한 줄

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

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

장점 vs 주의점

관련 개념 구분

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

개념 한 줄

동작 방식

언제 쓰고 / 안 쓰나

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

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

PRD에 들어가는 것

왜 필요한가

PRD vs 요구사항 정의서

SDD와의 연결

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

개념 한 줄

주요 쓰임새

왜 쓰는가

이전 노트 개념과의 연결

주의점

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

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

왜 중요한가

구성 요소

주요 기법

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

7. Claude 권한 모드 (Permission Modes)

모드별 특징

각 모드 상세

전환 / 적용

안전 ↔ 자유도 스펙트럼

8. Ultra Plan (ultrathink·ralplan)

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

2) OMC ralplan = 합의 기반 계획

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

언제 쓰고 / 아끼나

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

”하네스”란?

구성 요소

왜 중요한가

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

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

10. MCP (Model Context Protocol)

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

구조 (Client ↔ Server)

MCP 서버가 제공하는 3가지

이 환경의 MCP (연결됨)

연결 방식 (Transport)

이전 노트와 연결

11. Superpowers 플러그인 & Visual Companion

Superpowers란?

Visual Companion이 하는 일

왜 좋은가

이전 노트 개념과 연결

Visual Companion만 단독(standalone) 사용

12. Socratic Reasoning & Ouroboros (MCP)

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

B. Ouroboros (MCP) — “Agent OS”

둘의 관계 + 이전 노트 연결

13. Interview 모드

일반 모드 vs Interview 모드

Ouroboros의 Interview 모드 (구체 사례)

다른 Interview 모드 비교

이전 노트 연결

14. Ouroboros 사용법

설치 (Claude Code)

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

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

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

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

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

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

2) OMC `ralplan` = 합의 기반 계획

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

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