[Claude] Claude Code 정리 노트 — 제품 명세 문서와 멀티 에이전트 오케스트레이션(Ralph)
목차
Claude Code 정리 노트 — 제품 명세 문서와 멀티 에이전트 오케스트레이션(Ralph)
작성일: 2026-07-04 이전 노트: 2026-06-27-Claude-Code-정리-노트.md 의 후속편
들어가며 — AI 에이전트 시대, 사람은 무엇을 할 것인가?
AI가 코드를 대신 짜주는 시대가 되면서 자연스럽게 드는 질문: 그럼 사람은 이제 뭘 하나?
답은 대체로 한 방향으로 수렴한다 — 사람의 일은 “코드를 손으로 치는 것”에서 무엇을·어떻게 만들지 명세하고, 여러 AI를 조율하는 것으로 옮겨간다. 이번 노트는 그 두 축을 다룬다.
| 축 | 질문 | 이번 노트에서 |
|---|---|---|
| A. 제품 문서 | ”무엇을 만들 것인가”를 어떻게 정확히 적을 것인가 | 1~7번 |
| B. 멀티 에이전트 오케스트레이션 | ”어떻게 여러 AI를 굴려 그것을 만들게 할 것인가” | 8~17번 |
🔗 이 두 축은 이전 노트의 SDD(2026-06-27 노트 2번) — “명세가 먼저, 코드는 명세에서 파생” — 를 실무 문서(A)와 실행 방식(B)으로 구체화한 것에 가깝다.
1. 화면 흐름도 (User Flow / Screen Flow)
화면과 화면 사이의 이동·분기를 그린 다이어그램. 코드도 디자인도 아니고, “사용자가 어디서 어디로 가는지”만 다룬다.
개념 한 줄
“이 화면 다음엔 뭐가 나오는가”를 박스와 화살표로 미리 정하는 지도.
담는 내용
| 항목 | 예시 |
|---|---|
| 화면(노드) | 로그인, 홈, 상세, 결제 |
| 전환(엣지) | 버튼 클릭, 폼 제출, 뒤로가기 |
| 분기 | 로그인 성공/실패, 권한 있음/없음 |
| 진입·이탈점 | 앱 시작 지점, 외부 링크로 들어오는 지점 |
왜 필요한가 (AI 시대 맥락)
막연히 “쇼핑몰 만들어줘”라고 하면 AI는 화면 개수·이동 경로를 임의로 정해버린다. 화면 흐름도로 경로를 먼저 확정해두면 AI가 추측할 여지가 줄어든다 — 이전 노트의 goal drift(2026-06-27 노트 2번 배경)를 화면 구조 단계에서 미리 막는 것.
한 줄 요약: 화면 흐름도 = “사용자가 화면 사이를 어떻게 이동하는가”를 코드 짜기 전에 확정하는 지도. 이후 나올 기능 명세·와이어프레임의 뼈대가 된다.
2. 기능 명세서 (Functional Specification)
각 화면·기능이 무엇을 하는지를 서술한 문서. “어떻게 구현하는지(기술 설계)“는 다루지 않는다.
개념 한 줄
“이 버튼을 누르면 무슨 일이 일어나야 하는가”를 빠짐없이 적은 문서.
담는 내용
| 항목 | 내용 |
|---|---|
| 기능 ID·이름 | FR-01: 회원가입 |
| 입력/출력 | 입력: 이메일·비밀번호 / 출력: 계정 생성, 인증 메일 발송 |
| 검증 규칙 | 이메일 형식, 비밀번호 길이·중복 체크 |
| 예외·엣지케이스 | 이미 가입된 이메일일 때 동작 |
| 연관 화면 | 1번 화면 흐름도의 어느 화면과 연결되는지 |
PRD와 뭐가 다른가
| 구분 | PRD(2026-06-27 노트 4번) | 기능 명세서 |
|---|---|---|
| 관점 | 왜·무엇을·누구를 위해 (상위) | 각 기능이 정확히 무엇을 하는지 (하위) |
| 상세도 | 서술형, 목표·시나리오 중심 | 기능 단위로 조각내 입출력·규칙까지 |
실무 흐름: PRD(상위 목표) → 기능 명세서(기능 단위 상세) → 와이어프레임/설계.
한 줄 요약: 기능 명세서 = “무엇을 하는가”를 기능 단위로 쪼개 입력·출력·규칙·예외까지 적은 문서. PRD보다 한 단계 더 구체적.
3. 와이어프레임 (Wireframe) — Low-Fi / High-Fi
화면의 레이아웃(무엇이 어디에 있는가)을 그린 시안. 색·폰트 같은 최종 디자인이 아니라 구조에 집중.
충실도(fidelity)에 따른 구분
| 구분 | Low-Fi (저충실도) | High-Fi (고충실도) |
|---|---|---|
| 표현 수준 | 박스·회색조·자리표시(placeholder) 텍스트 | 실제 색·타이포·컴포넌트에 가까움 |
| 목적 | 레이아웃·정보 구조 합의 | 최종 룩앤필 검증, 클릭 가능한 프로토타입 |
| 제작 비용 | 낮음, 빠르게 여러 안 시도 | 높음, 수정 비용 큼 |
| 적합 시점 | 초기 아이디어 확정 단계 | 개발 직전, 디자인 승인 단계 |
왜 순서가 중요한가
Low-Fi로 구조를 먼저 합의하지 않고 바로 High-Fi(또는 실제 코드)로 가면, 나중에 레이아웃이 잘못됐을 때 디자인·코드를 통째로 다시 만들어야 한다. 저비용 단계에서 먼저 걸러내는 게 핵심.
AI 시대 맥락
- Low-Fi: AI에게 “이 화면 레이아웃 후보 3개 보여줘” 요청 → 2026-06-27 노트 11번 Visual Companion이 정확히 이 역할(코드 전에 브라우저로 시안 비교)
- High-Fi: 실제 색·컴포넌트까지 가려면 DESIGN.md(2026-06-27 노트 19번, 디자인 토큰 명세)를 참조시켜야 AI가 일관되게 만듦
- 캔버스에서 그려 바로 코드로 뽑는 도구로는 Pencil.dev(2026-06-27 노트 18번) 사례가 있음
한 줄 요약: 와이어프레임 = 레이아웃 시안. Low-Fi(박스 수준, 구조 합의용) → High-Fi(실제 색·컴포넌트, 승인용) 순으로 충실도를 높여가며 재작업 비용을 줄인다.
4. 권한 정책 (Permission / Authorization Policy)
누가 무엇에 접근·조작할 수 있는가를 정의한 문서. 흔히 역할 기반 접근 제어(RBAC, Role-Based Access Control) 형태로 정리.
개념 한 줄
역할(role) × 자원(resource) × 행동(action) 조합으로 접근 가능 여부를 표로 못 박은 것.
예시 표 (권한 매트릭스)
| 역할 \ 자원·행동 | 게시글 조회 | 게시글 작성 | 게시글 삭제 | 회원 관리 |
|---|---|---|---|---|
| 일반 사용자 | O | O | 본인 글만 | X |
| 운영자 | O | O | O | X |
| 관리자 | O | O | O | O |
왜 앞단에서 정해야 하는가
권한 정책이 없으면 AI가 “일단 다 열어두거나” “일단 다 막아버리는” 식으로 임의 판단한다. 특히 삭제·결제·개인정보 같은 민감 기능은 권한 누락이 곧 보안 사고로 이어짐 — 이전 노트의 **권한 모드(Permission Modes, 2026-06-27 노트 7번)**가 “AI 실행 권한”을 다루는 것과는 결이 다른, 애플리케이션 자체의 사용자 권한 개념임에 주의.
한 줄 요약: 권한 정책 = 역할별로 무엇을 할 수 있고 없는지를 명세한 문서. ERD의 사용자·역할 테이블, API 명세서의 인가(authorization) 규칙과 직접 연결된다.
5. ERD (Entity-Relationship Diagram, 개체-관계도)
데이터가 무엇으로 이루어져 있고 서로 어떻게 연결되는지를 그린 다이어그램. DB 설계의 기본 뼈대.
개념 한 줄
이 서비스가 다루는 데이터 개체들과, 그것들 사이의 관계를 도식화한 것.
구성 요소
| 요소 | 설명 | 예시 |
|---|---|---|
| 엔티티(Entity) | 데이터 개체(=대략 테이블) | User, Order, Product |
| 속성(Attribute) | 엔티티가 가진 값 | User.email, Order.created_at |
| 관계(Relationship) | 엔티티 간 연결과 다중성 | User 1 : N Order |
| 키(Key) | 식별자·참조 | User.id (PK), Order.user_id (FK) |
왜 API 명세서보다 먼저인가
API는 결국 데이터를 주고받는 창구다. 데이터 모델(ERD)이 흔들리면 API 스펙도 계속 바뀐다. 순서상 ERD → API 명세서가 자연스러운 이유.
한 줄 요약: ERD = 데이터의 뼈대. 권한 정책의 “역할·사용자” 테이블, API 명세서의 요청·응답 구조가 모두 여기서 파생된다.
6. API 명세서 (API Specification)
프론트엔드와 백엔드(혹은 서비스 간)가 주고받는 요청·응답의 계약서. 흔히 OpenAPI(Swagger) 같은 형식으로 작성.
개념 한 줄
“이 엔드포인트를 이렇게 부르면 이런 응답이 온다”를 정확히 약속한 문서.
담는 내용
| 항목 | 예시 |
|---|---|
| 엔드포인트 | POST /api/orders |
| 요청 스키마 | { userId, productId, quantity } |
| 응답 스키마 | { orderId, status, createdAt } |
| 상태 코드 | 200(성공), 400(잘못된 요청), 401(미인증), 403(권한없음) |
| 인증/인가 요구사항 | 로그인 필요 여부, 필요한 역할(4번 권한 정책과 연결) |
AI 시대 맥락
API 명세서는 사람과 사람 사이의 계약을 넘어, 이제 AI가 프론트/백엔드 코드를 각각 생성할 때 기준으로 삼는 명세가 된다. 명세가 명확하면 서로 다른 세션·에이전트가 만든 프론트/백엔드도 어긋나지 않고 맞물린다.
한 줄 요약: API 명세서 = 요청·응답의 계약. ERD(데이터)와 권한 정책(접근 규칙)을 실제 호출 가능한 인터페이스로 구체화한 최종 산출물.
7. 제품 문서들의 흐름 — 아이디어에서 API까지
1~6번 문서가 어떤 순서·관계로 이어지는지 한 번에 정리.
흐름도
막연한 아이디어
│
▼
① 화면 흐름도(User Flow) — 화면 간 이동 구조 확정
│
▼
② 기능 명세서(Functional Spec) — 각 화면·기능이 "무엇을" 하는지
│
▼
③ 와이어프레임(Low-Fi → High-Fi) — 화면을 "어떻게 보여줄지" 레이아웃→룩앤필
│
├──▶ ④ 권한 정책(Permission) ─┐
│ ├─▶ ⑥ API 명세서 — 최종 계약
└──▶ ⑤ ERD(데이터 모델) ─┘
│
▼
구현(코드) — 사람 또는 AI 에이전트가 작성SDD·이전 노트 개념과의 연결
| SDD 단계(2026-06-27 노트 2번) | 대응하는 제품 문서 |
|---|---|
| Specify (무엇을·왜) | PRD(4번, 6/27 노트) + 화면 흐름도(1) + 기능 명세서(2) |
| Plan (어떻게, 기술 결정) | ERD(5) + API 명세서(6) + 권한 정책(4) |
| (디자인 계층) | 와이어프레임(3) + DESIGN.md(6/27 노트 19번) |
| Tasks / Implement | 위 문서들을 근거로 AI/사람이 구현 |
- planner·deep-interview(6/27 노트 13·16번)는 질문을 통해 이 문서들의 초안을 뽑아내는 도구
- 즉, 1~6번 문서 전체가 SDD의 “명세(spec)” 산출물을 화면·데이터·API 관점으로 구체화한 것
한 줄 요약: 아이디어 → 화면 흐름 → 기능 명세 → 와이어프레임 → (권한 정책 + ERD) → API 명세 순으로 구체화하며, 이 전체가 SDD의 Specify/Plan 단계를 실제 문서로 채운 것이다.
8. 멀티 에이전트란?
여러 개의 AI 에이전트가 각자 역할을 맡아 하나의 목표를 위해 협업하는 방식. 하나의 거대한 에이전트가 모든 걸 처리하는 단일 에이전트(single-agent) 방식과 대비된다.
그림: 한 에이전트가 해석→추론→결정→실행을 혼자 담당하는 단일 방식 vs 분류/조율→전문 에이전트 분담→결과 통합으로 나눠 처리하는 멀티 방식.
단일 에이전트 vs 멀티 에이전트
| 구분 | 단일 에이전트 | 멀티 에이전트 |
|---|---|---|
| 비유 | 혼자 다 하는 만능 직원 | 역할 나눠 일하는 팀 |
| 컨텍스트 | 하나의 긴 컨텍스트에 모든 게 누적 | 에이전트별로 독립된 컨텍스트 |
| 실패 양상 | Goal drift, agentic laziness(6/20 노트 15번) | 병렬 검증·반박으로 실패 완화 가능 |
| 비용 | 상대적으로 낮음 | 에이전트 수만큼 증가 |
한 줄 요약: 멀티 에이전트 = 한 명의 만능 일꾼 대신, 역할을 나눈 여러 AI가 협업해 결과를 만드는 방식.
9. 하네스 엔지니어링 다시보기
상세 개념은 2026-06-27 노트 9번에서 이미 다룸. 여기서는 멀티 에이전트의 “기반 층”으로서 위치만 재정리.
개념 한 줄
모델 자체가 아니라, 모델을 감싸 “입력→도구 사용→검증→반복”을 시키는 실행 골격(harness)을 설계하는 기술.
그림: 대화형(Ping-Pong) 프롬프트 엔지니어링 → 스킬형(Skills/Harness) 하네스 엔지니어링 → 시스템형(System Design) 루프 엔지니어링으로의 진화. “프롬프트를 잘 쓰는 단계 → skills를 설계하는 단계 → AI를 움직이는 시스템을 설계하는 단계.” (이 노트가 짚는 거시 진화 축이며, 아래 표는 각 계층의 포함 관계를 따로 정리한다.)
세 엔지니어링의 포함 관계
| 계층 | 다루는 대상 |
|---|---|
| 프롬프트 엔지니어링 | 한 번의 지시문 |
| 컨텍스트 엔지니어링(6/27 노트 6번) | 모델이 보는 정보 전체 |
| 하네스 엔지니어링 | 모델을 감싸는 실행 골격 전체(제어흐름·도구·검증) |
→ 멀티 에이전트 시스템은 하네스 엔지니어링의 대표적인 산출물 중 하나다. 에이전트를 여러 개 두고 어떻게 소통·검증시킬지가 곧 하네스 설계.
한 줄 요약: 하네스 엔지니어링 = 프롬프트·컨텍스트 엔지니어링의 상위 개념으로, 모델을 감싸는 실행 골격 자체를 설계하는 것. 멀티 에이전트 시스템은 그 골격이 “여러 에이전트”로 확장된 형태.
10. 멀티 에이전트 시스템이란?
여러 자율 에이전트가 **통신·조율(때로는 협상)**하며, 단일 에이전트로는 풀기 어렵거나 비효율적인 문제를 함께 해결하도록 설계된 시스템. (분산 AI 연구에서 LLM 이전부터 있던 개념이 LLM 에이전트로 옮겨온 것)
개념 한 줄
“각자 맡은 역할을 가진 에이전트들이, 정해진 방식으로 소통하며 하나의 결과로 수렴하는 시스템.”
왜 하나로 안 하고 여러 개로 나누는가
| 이유 | 설명 |
|---|---|
| 전문화 | 탐색·구현·검증 등 역할별로 다른 시스템 프롬프트·모델 사용 가능 |
| 컨텍스트 격리 | 각자 독립 컨텍스트 → 서로의 잡음이 섞이지 않음 |
| 병렬성 | 동시에 여러 하위 작업을 진행해 시간 단축 |
| 적대적 검증 | 한 에이전트의 결과를 다른 에이전트가 반박·검증 → 오류 발견 확률↑ |
한 줄 요약: 멀티 에이전트 시스템 = 역할을 나눠 통신·조율하는 여러 에이전트로 구성된 문제 해결 시스템. 전문화·격리·병렬성·검증이 핵심 이점.
11. 멀티 에이전트 시스템의 구성 요소
그림: ①오케스트레이터(분배) · ②워커/전문 에이전트(실행) · ③공유 상태·메모리(맥락 공유) · ④통신(전달) · ⑤검증기(확인) · ⑥종료 조건(멈춤)이 중앙의 시스템을 둘러싸고 맞물리는 구조.
| 구성 요소 | 역할 | Claude Code에서의 예 |
|---|---|---|
| 오케스트레이터 / 코디네이터 | 작업을 쪼개 분배하고 전체 진행을 관리 | 메인 대화, dynamic workflow의 JS 코드 |
| 워커 / 전문 에이전트 | 실제 하위 작업을 수행 | 서브에이전트, Agent Teams의 팀원 |
| 공유 상태 / 메모리 | 에이전트들이 참조하는 공통 정보 | 공유 작업 목록(Task List), 파일시스템, git |
| 통신(메시징) | 에이전트 간 정보 전달 방식 | Agent Teams의 Mailbox, 메인↔서브의 요약 보고 |
| 검증기(Verifier/Critic) | 결과가 맞는지 독립적으로 확인 | 적대적 검증 패턴(6/20 노트 15번), doc-reviewer류 |
| 종료 조건 | 언제 멈출지 판단 | 목표 충족, 테스트 통과, 최대 반복 횟수 |
한 줄 요약: 오케스트레이터(분배) + 워커(실행) + 공유 상태(맥락 공유) + 통신(전달) + 검증기(확인) + 종료 조건(멈춤) 이 여섯 가지가 멀티 에이전트 시스템의 기본 골격.
12. 코딩 멀티 에이전트 시스템 사례 — Claude Code
Claude Code 안에서 11번의 구성 요소들이 실제로 어떤 기능으로 구현되어 있는지 정리. 상세는 각 이전 노트 참조.
| 방식 | 통신 구조 | 특징 | 출처 |
|---|---|---|---|
| 서브에이전트 | 허브앤스포크(메인에만 보고) | 결과 요약만 반환, 컨텍스트 격리 | 2026-06-20 노트 10번 |
| Agent Teams | 메시(팀원끼리 직접 소통) | 공유 작업목록·Mailbox, 실험적 기능 | 2026-06-20 노트 13·14번 |
| Dynamic Workflow | 오케스트레이터가 JS 코드로 결정론적 조율 | 수십~수백 에이전트 팬아웃, 6가지 조합 패턴 | 2026-06-20 노트 15·16번 |
세 방식의 위치
서브에이전트 : 일꾼 1명씩, 메인이 전부 관리 (단순·저비용)
Agent Teams : 일꾼들끼리 대화하며 협업 (토론·복합 작업)
Dynamic Workflow : 일꾼들을 "코드"로 결정론적으로 지휘 (대규모·고비용·고정확도)한 줄 요약: Claude Code는 서브에이전트(허브앤스포크) → Agent Teams(메시형 협업) → Dynamic Workflow(코드 기반 결정론적 오케스트레이션)까지, 규모와 협업 방식이 다른 멀티 에이전트 구현체를 여러 층으로 제공한다.
13. 루프 엔지니어링 다시보기
상세 개념은 2026-06-27 노트 17번에서 이미 다룸. 여기서는 “될 때까지 반복”이라는 핵심만 재정리하고, 다음 절(14~17번)의 Ralph로 이어간다.
개념 한 줄
에이전트를 한 번 실행하고 끝내는 게 아니라, “행동→관찰→결정→반복”의 순환 자체를 시스템으로 설계하는 것.
하네스 엔지니어링과의 관계
| 계층 | 다루는 범위 |
|---|---|
| 하네스 엔지니어링(9번) | 한 번의 실행을 잘 짜인 골격으로 감싸기 |
| 루프 엔지니어링 | 그 골격을 목표 달성까지 반복 구동 |
- OMC의
ralph/autopilot/ultrawork같은 스킬, hooks_and_context의 “The boulder never stops” 문구가 바로 이 “루프가 계속 도는” 상태를 가리킴 - 6/20 노트 15번 dynamic workflow의 Loop-until-done 패턴도 루프 엔지니어링의 코드 구현 사례
한 줄 요약: 루프 엔지니어링 = 에이전트를 한 번이 아니라 “목표 달성 또는 검증 통과까지” 반복 구동하는 시스템을 설계하는 것. 다음 절의 Ralph가 이 아이디어의 대표 사례다.
14. 루프 엔지니어링의 기원과 Ralph
⚠️ “누가 최초로 시작했다”를 딱 잘라 단정하기는 어려운 영역. 아래는 일반적으로 회자되는 계보 정도로 이해할 것.
2026-06-27 노트 17번에서 “루프 엔지니어링”이라는 용어 자체는 비교적 최근(2026년 6월, Peter Steinberger가 문제 제기 → Addy Osmani가 정립)에 이름 붙었다고 정리했다. 하지만 실제 관행— 같은 에이전트를 반복해서 돌려 목표에 도달시키는 방식 — 은 그보다 앞서 커뮤니티에서 **“Ralph”**라는 이름의 기법으로 이미 퍼져 있었다는 게 통설이다.
Ralph 기법 (반복 실행의 실무적 원형)
│
▼ (관행이 널리 퍼짐)
"루프 엔지니어링" 용어 정립 (Steinberger 제기 → Osmani 정리)한 줄 요약: 루프 엔지니어링이라는 이름이 붙기 전부터, 에이전트를 반복 실행해 목표까지 밀어붙이는 방식은 “Ralph”라는 기법으로 이미 실무에서 쓰이고 있었다.
15. Ralph란?
그림: Ralph Loop 한 사이클 — ①에이전트 실행 → ②작업·커밋 → ③상태 인수인계(HANDOFF·git) → ④검증 후, 완료될 때까지 매번 새 컨텍스트로 다시 시작한다. 기억은 대화가 아니라 파일·git이 담당하며, 본질은
while true; do …; done형태의 단순 반복이다.
개념 한 줄
에이전트를 같은 작업 지시(프롬프트 파일)로 계속 반복 호출하면서, 검증(테스트·체크리스트)을 통과할 때까지 스스로 진행 상태를 파일·git에 남기며 밀고 나가게 하는 기법.
핵심 아이디어
| 요소 | 설명 |
|---|---|
| 매 반복은 “새 컨텍스트” | 이전 대화 기억 없이 매번 새로 시작 — 대신 파일시스템·git 커밋이 “기억” 역할(=상태 인수인계/HANDOFF) |
| 자기 참조 루프 | 이전 반복이 남긴 상태(코드, 커밋, 테스트 결과)를 다음 반복이 읽고 이어감 |
| 검증이 종료 조건 | 테스트 통과·체크리스트 완료 등 명확한 성공 기준이 있어야 루프가 멈춤 |
| 단순함이 강점 | 정교한 상태 관리 프레임워크 대신, “반복 + 검증”이라는 단순한 구조로 동작 |
왜 이런 방식이 통하는가
한 번의 실행에서 완벽하게 끝내려 하지 않고, 여러 번의 시도 중 검증을 통과하는 순간에 도달하는 것을 목표로 삼는다 — 사람이 매번 개입해 다음 지시를 주는 대신, 반복 자체가 진행을 만들어낸다.
한 줄 요약: Ralph = 같은 프롬프트로 에이전트를 계속 다시 실행하며, 파일·git 상태를 매개로 진행을 이어가고, 검증을 통과할 때까지 멈추지 않는 자기 참조형 루프 기법.
16. Ralph 실행해보기
아래는 Ralph 방식의 일반적인 실행 흐름을 개념적으로 정리한 것. 구체적인 스크립트·명령은 원본 출처(15번 링크)를 확인할 것.
그림: PRD 작성 →
prd.json으로 잘게 쪼개기(user story) →ralph.sh실행 → 스토리 선택 → 구현·테스트 → 통과 시 커밋 &prd.json갱신(passes: true) → 진행 상황 기록(progress.txt) → 남은 스토리 반복 → 완료. 매 반복이 남긴 상태를 다음 반복이 이어받는다.
전형적인 흐름
1) 목표·완료 조건 정의
│
2) 작업 지시 파일 작성 (예: PROMPT.md, 또는 스토리를 담은 prd.json — 다음 17번에서 다룸)
│
3) 반복 루프 구성 (예: while true 형태로 에이전트를 계속 호출)
│ ┌─────────────────────────────┐
└─▶│ 에이전트 1회 실행 │
│ - 지시 파일 + 현재 저장소 상태 확인│
│ - 가능한 만큼 진행 (커밋) │
│ - 테스트/검증 실행 │
└─────────────┬───────────────┘
│ 완료 조건 미충족
▼
(에이전트 실행으로 복귀, 반복)
│ 완료 조건 충족
▼
루프 종료실행 시 챙겨야 할 것
| 항목 | 이유 |
|---|---|
| 명확한 완료 조건 | 없으면 루프가 끝없이 돌거나, 엉뚱한 지점에서 멈춤 |
| 상태를 파일/git에 남기기 | 다음 반복이 “새 컨텍스트”이므로, 기록이 곧 기억 |
| 최대 반복 횟수·비용 상한 | 무한 루프에 대한 안전장치 (루프 엔지니어링의 “종료 판단” 요소, 13번) |
| 검증 자동화(테스트 등) | 사람이 매번 확인하지 않아도 되게 하는 핵심 장치 |
한 줄 요약: Ralph 실행 = 완료 조건을 정하고 → 지시 파일을 만들고 → 반복 루프를 돌리며 → 매 회차 상태를 남기고 검증하다가 → 조건 충족 시 멈추는 흐름.
17. Ralph 실행 준비 — PRD 작성
Ralph를 돌리기 전, 가장 먼저 해야 할 사람의 일은 코드를 짜는 게 아니라 PRD(제품 요구사항 문서)를 쓰는 것이다.
왜 PRD가 먼저인가
Ralph의 매 반복은 새 컨텍스트로 시작한다(15번). 즉, 사람이 대화 중간에 “아, 그게 아니라 이렇게 해줘”라고 보정해줄 기회가 계속 있는 게 아니다. 그래서 에이전트가 매 반복마다 참고할 수 있도록, 요구사항을 미리 문서로 못 박아둬야 한다 — 이게 바로 Ralph의 지시 파일(PROMPT.md 등)에 담기는 내용이자, 사실상 PRD/기능 명세서 역할을 한다.
여기서 파트 A(1~7번)와 다시 만난다
| Ralph가 매 반복 참조하는 것 | 대응하는 문서 |
|---|---|
| ”무엇을 만드는가” | PRD(2026-06-27 노트 4번) |
| “각 기능이 정확히 뭘 하는가” | 기능 명세서(2번) |
| “화면이 어떻게 이어지는가” | 화면 흐름도(1번) |
| “데이터는 어떻게 생겼는가” | ERD(5번) |
| “완료 조건(성공 기준)“ | 기능 명세서의 검증 규칙 + API 명세서(6번)의 응답 계약 |
→ Ralph의 루프가 헤매지 않고 수렴하려면, 애매하지 않은 완료 조건이 문서에 명시돼 있어야 한다. “로그인 기능 만들어줘”가 아니라 “이메일·비밀번호로 로그인, 실패 시 이런 메시지, 성공 시 이 화면으로 이동, 이 API 스펙을 따름” 수준까지.
정리 — 사람의 역할이 이동하는 지점
예전: 사람이 코드를 직접 짠다
지금: 사람이 PRD·명세를 쓴다 → Ralph(루프)가 검증 통과까지 구현을 반복한다이것이 서두(“들어가며”)에서 던진 질문 — AI 에이전트 시대에 사람은 무엇을 할 것인가 — 에 대한 실무적 답이다. **명세를 정확히 쓰는 것(파트 A)**과 에이전트를 조율하는 루프를 설계하는 것(파트 B), 두 가지로 수렴한다.
한 줄 요약: Ralph를 돌리기 전에 사람이 할 일은 PRD·기능 명세·완료 조건을 명확히 쓰는 것. 매 반복이 새 컨텍스트인 Ralph에게는 이 문서가 유일한 “기억”이자 나침반이다.
참고: Ralph는 특정 벤더의 정식 제품이라기보다 커뮤니티에서 회자되는 **기법(technique)**에 가깝다. 실제 적용 전에는 원본 출처(https://snarktank.github.io/ralph) 와 사용 중인 에이전트 도구의 최신 문서를 함께 확인할 것.
18. 랄프는 천하무적인가? — Ralph의 한계
15~17번에서 본 것처럼 Ralph는 “PRD만 잘 쓰면 밤새 알아서 돌아가는” 강력한 기법처럼 보인다. 하지만 실제로는 특정 조건을 만족하는 작업에서만 잘 통하는 도구다.
개념 한 줄
Ralph는 만능 자동화가 아니라, “자동으로 검증 가능한 작업”에 한정된 레버리지 도구다.
한계 정리
| 한계 | 내용 |
|---|---|
| 자동 검증 가능한 작업에만 통함 | 목표를 테스트·명확한 성공 기준으로 객관적·자동으로 검증할 수 있어야 루프가 수렴한다. 판단이 많이 필요한(judgment-heavy) 작업이나 모호한 요구사항에는 잘 안 통함 — “모호한 입력 → 모호한 결과.” |
| 토큰·비용 폭증 | 자율 반복 루프는 토큰 소비량이 크다. 큰 코드베이스에서 50회 반복이면 맥락 크기에 따라 API 비용이 $50~100+ 수준까지 갈 수 있음. |
| 종료 조건의 불안정성 | 완료 판정을 단순 문자열 매칭 등으로 하면 불안정하게 종료되거나 끝나지 않을 수 있음 → 반드시 최대 반복 횟수(max-iterations) 같은 안전장치를 둬야 함(16번 표의 “최대 반복 횟수·비용 상한”과 동일 항목). |
| 컨텍스트 오염(context pollution) | 실패한 시도·무관한 코드가 파일·기록에 계속 쌓여 다음 반복의 모델을 혼란시킬 수 있음. |
| 모니터링 필요 | 방치하면 컴파일조차 안 되는 깨진 코드베이스로 아침을 맞을 수 있음 — 언제 리셋하고 언제 지시를 다시 구조화할지는 사람의 판단이 필요. |
🔗 토큰 폭증은 이전 노트의 Token Maxxing(2026-06-27 노트 1번)과 같은 맥락 — 자율성이 늘수록 토큰 소비가 커지는 트레이드오프. (최대 반복·비용 상한은 위 표대로 16번 안전장치와 이어진다.)
결론
Ralph는 기계적·자동검증 가능한 작업에서 2~3배 레버리지를 주는 도구이지, 판단·모호함이 핵심인 일까지 대체하진 못한다. 서두(“들어가며”)의 질문 — AI 에이전트 시대에 사람은 무엇을 할 것인가 — 으로 다시 돌아가면, 사람의 몫은 여기서도 검증 기준을 설계하고, 모호함을 걷어내는 것으로 확인된다.
한 줄 요약: Ralph는 만능이 아니다. 자동 검증 가능한 명확한 작업에서는 강력하지만, 판단이 필요한 모호한 작업·비용 관리·컨텍스트 오염 방지는 여전히 사람의 몫이다.
출처: https://tessl.io/blog/unpacking-the-unpossible-logic-of-ralph-wiggumstyle-ai-coding/ , https://www.leanware.co/insights/ralph-wiggum-ai-coding
19. 2026년 3월, Andrej Karpathy의 AutoResearch란?
Ralph 루프의 “반복 + 검증” 아이디어가 코딩을 넘어 ML 연구 자동화로 확장된 대표 사례.
개념 한 줄
사람이 program.md(연구 방향)를 쓰면, 에이전트가 train.py를 직접 고쳐가며 밤새 실험을 반복하고, 개선된 결과만 git에 남기는 자율 연구 루프.
그림: 사람이 쓴
program.md(연구 방향) → 에이전트가train.py수정 → 5분 고정 학습 →val_bpb평가 → 개선되면 git 커밋으로 유지(keep-if-better), 나빠지면 폐기 → 반복. 사람은 방향·지표를 설계하고, 루프가 밤새 실험을 돌린다.
기본 정보
| 항목 | 내용 |
|---|---|
| 공개일 | 2026년 3월 7일 |
| 공개자 | Andrej Karpathy |
| 라이선스 | MIT(오픈소스), 약 630줄 파이썬 |
| 목적 | 단일 GPU에서 ML 연구 실험을 자율로 반복 |
| 대상 모델 | nanochat(간소화된 GPT 구현) |
동작 루프
| 단계 | 내용 |
|---|---|
| 1) 명세 | program.md에 연구 방향·맥락을 사람이 마크다운으로 작성 |
| 2) 수정 | AI 에이전트가 train.py를 직접 수정(아키텍처·하이퍼파라미터·옵티마이저·배치 크기 등) |
| 3) 학습 | 각 실험은 플랫폼 무관 비교를 위해 정확히 5분(wall-clock) 학습 |
| 4) 평가 | val_bpb(validation bits per byte, 낮을수록 개선)로 평가 |
| 5) 선택 | 개선되면 git 커밋으로 유지, 나빠지면 폐기(keep-if-better) |
| 6) 반복 | 계속 반복 — 시간당 약 12개 실험, 자는 동안 약 100개 |
결과 사례
| 사례 | 결과 |
|---|---|
| Karpathy 본인 | 이틀 연속 실행, 약 700개 실험. “Time to GPT-2” 벤치마크 2.02시간 → 1.80시간 |
| Shopify(Tobi Lütke) | 사내 query-expansion 모델에 응용, 37개 실험으로 검증 점수 약 19% 개선(공개된 수치, 하루 만에 보고) |
핵심 관점
“program.md(사람이 쓰는 명세) + train.py를 고치는 루프” 구조는 Ralph 루프를 ML 연구에 특화한 형태에 가깝다. 사람은 코드를 직접 치는 대신 연구 방향과 평가 지표(val_bpb)를 설계하고, 나머지는 루프가 밤새 실험을 돌리며 채운다. Karpathy는 이런 흐름 속에서 “코드를 직접 짜지 않게 됐다”는 취지의 발언을 한 것으로 보도됨.
🔗 이 구조는 파트 A(1~7번)의 “명세가 먼저”라는 원칙, 루프 엔지니어링(13번), **Ralph(15번)**와 직접 연결된다 — 도메인만 “코딩”에서 “ML 연구”로 바뀐 것.
한 줄 요약: AutoResearch =
program.md(명세) +train.py자동 수정 + keep-if-better 선택을 5분 단위로 반복하는 오픈소스 자율 연구 루프. Ralph의 “반복+검증” 아이디어를 ML 연구 실험에 특화한 사례.
출처: https://github.com/karpathy/autoresearch , https://www.datacamp.com/tutorial/guide-to-autoresearch
20. AlphaEvolve와 AutoResearch의 차이
둘 다 “AI가 알고리즘·모델을 자동으로 탐색·개선한다”는 같은 방향을 향하지만, 구현 방식은 상당히 다르다.
개념 한 줄
AlphaEvolve는 대규모·진화형·비공개, AutoResearch는 경량·탐욕적·오픈소스 — 같은 목표를 다른 규모·방식으로 푼 두 사례.
대비표
| 구분 | AlphaEvolve | AutoResearch |
|---|---|---|
| 공개 | Google DeepMind, 2025년 5월 | Andrej Karpathy, 2026년 3월 7일 |
| 탐색 방식 | 진화형(evolutionary) — 개체군(population)을 두고 수백만 코드 변형을 진화 탐색 | LLM이 train.py 코드를 직접 수정 + greedy keep-if-better(사실상 언덕오르기) |
| 사용 모델 | Gemini Flash(빠른 아이디어) + Gemini Pro(정교화) + 자동 평가기 앙상블 | 임의의 코딩 에이전트(LLM) 1개 |
| 공개성 | 비공개(closed-source), 기술 블로그·결과만 공개 | 오픈소스(MIT), 약 630줄 |
| 규모/컴퓨트 | 대규모, 수백만 코드 변형 탐색 | 단일 GPU, 실험당 5분, 밤새 약 100개 |
| 주 대상 | 범용 알고리즘 발견(행렬 곱셈, 데이터센터 스케줄링, 수학 난제 등) | ML 학습 연구(nanochat 기반) |
| 접근성 | 재현 어려움(코드 비공개) | 누구나 실행 가능 |
| 성과 | 공개 난제 50여 개 중 75%에서 기존 SOTA 재발견, 20%에서 최고 기록 경신 | ”Time to GPT-2” 2.02시간→1.80시간(Karpathy), 검증 점수 약 19% 개선(Shopify 사례) |
공통점 — 왜 둘 다 “루프”로 도는가
탐색 방식은 다르지만, 둘 다 성립하려면 반드시 **자동 평가기(evaluator)**가 있어야 한다 — AlphaEvolve는 자동 채점기, AutoResearch는 val_bpb 지표. 사람이 매 실험을 눈으로 확인하지 않아도 되게 만드는 이 장치가 없으면 루프 자체가 돌 수 없다.
🔗 이는 18번 Ralph의 한계(“자동 검증 가능한 작업에만 통함”)와 같은 전제다 — 규모가 커지든 작아지든, 자율 반복 루프가 성립하려면 결국 명확하고 자동화된 성공 기준이 있어야 한다는 점은 동일하다.
한 줄 요약: AlphaEvolve(대규모·진화형·비공개)와 AutoResearch(경량·탐욕적·오픈소스)는 같은 “자율 알고리즘 발견”이라는 흐름 위에 있지만, AutoResearch는 접근성에서, AlphaEvolve는 탐색 규모에서 강점을 가진다. 둘 다 자동 평가기가 있어야 루프가 성립한다는 점은 동일.
출처: https://deepmind.google/blog/alphaevolve-a-gemini-powered-coding-agent-for-designing-advanced-algorithms/ , https://en.wikipedia.org/wiki/AlphaEvolve
21. 연구 과정·결과 기록 — LLM Wiki
LLM Wiki는 OMC(oh-my-claudecode) 플러그인의 스킬(
/oh-my-claudecode:wiki)이다. Claude Code 자체의 native 기능이 아니라 그 위에 얹힌 확장 기능임에 유의.
그림: 세션은 끝나면 컨텍스트가 사라지지만, 매 세션이 **LLM Wiki(영속 마크다운 지식 베이스)**에 기록(write)하고 다음 세션이 재사용(read)하며 지식이 누적된다. 추가·질의·흡수·정리로 관리하는 “외부 기억” 층.
개념 한 줄
세션을 넘나들며 축적되는 영속적 마크다운 지식 베이스 — “Karpathy 모델”이라는 이름으로 소개됨(19번 Karpathy의 “지식이 compounding된다”는 관점과 같은 맥락).
목적
연구 과정·결과·배운 점을 대화가 아니라 파일로 남겨, 컨텍스트가 초기화돼도 지식이 사라지지 않고 계속 쌓이게 하는 것.
주요 동작
| 동작 | 역할 |
|---|---|
| wiki_add | 새 지식·결과 추가 |
| wiki_query | 쌓인 지식 질의·검색 |
| wiki_ingest | 외부 문서를 흡수해 위키로 편입 |
| wiki_read | 특정 항목 읽기 |
| wiki_list | 목록 조회 |
| wiki_lint | 위키 내용 정리·정합성 점검 |
왜 필요한가
Ralph(15번)·AutoResearch(19번) 같은 루프는 매 반복이 새 컨텍스트라, 기억을 외부(파일·git)에 남겨야 이어진다고 이미 정리했다. LLM Wiki는 그 “외부 기억”을 연구 지식이라는 관점에서 체계화한 층이다 — 이전 노트의 파일 기반 메모리 시스템(2026-06-20 노트)과도 같은 계열.
🔗 15번(기억은 파일·git이 담당)·19번(program.md + git history로 상태 인계)·13번(루프 엔지니어링)과 연결.
한 줄 요약: LLM Wiki(OMC 스킬) = 세션이 끝나도 사라지지 않는 연구 지식 베이스. 추가·질의·흡수·정리 동작으로 Ralph·AutoResearch류 루프의 “외부 기억”을 지식 관리 관점으로 구체화한 것.
22. 자율 코딩 루프와 Goal (/goal)
그림:
/goal <조건>설정 → Claude 턴 실행 → 작은 모델(기본 Haiku)이 조건 평가 → 미충족이면 다음 턴을 자동 반복, 충족이면 정지. Prompt 기반 Stop hook으로 구현돼/compact후에도 유지되고--resume시 복원된다.
개념 한 줄
완료 조건(completion condition)을 정해두면, 그 조건이 충족될 때까지 여러 턴을 사용자 입력 없이 자동 반복 실행하는 Claude Code native 내장 기능. (Claude Code v2.1.139 이상 필요)
구현 원리
| 요소 | 내용 |
|---|---|
| 내부 구현 | ”Prompt 기반 Stop hook” |
| 평가 주체 | 각 턴 후 작은 빠른 모델(기본 Haiku)이 완료 조건 충족 여부를 평가 |
| 미충족 시 | 다음 턴을 자동으로 시작 |
| 컨텍스트 압축과의 관계 | hook은 컨텍스트가 아니라 코드로 실행되므로 /compact의 대상이 아님 → Goal 조건은 압축 후에도 유지 |
| 세션 재개 | 활성 Goal 상태로 종료 후 --resume/--continue로 재개하면 Goal이 복원됨. 단 턴 수·타이머·토큰 기준선은 리셋되고, 목표 조건 자체만 유지. 이미 달성했거나 /goal clear한 Goal은 복원되지 않음 |
사용법
| 명령 | 동작 |
|---|---|
/goal <조건문> | 조건 설정 + 자동 반복 시작 |
/goal | 상태 조회(경과 시간·턴 수·토큰·최근 평가 이유) |
/goal clear | 해제 (stop/off/reset/none/cancel도 동의어) |
claude -p "/goal ..." | 비대화형 실행 |
조건문 작성 제약
- 최대 4,000자
- 측정 가능한 단일 종료 상태여야 함(예: 테스트 통과, 빌드 종료 코드, 파일 개수 등)
- Claude가 이미 출력한 내용을 기준으로 평가됨
Auto mode와의 구분
| 구분 | 자동 반복 범위 |
|---|---|
| Auto mode | 한 턴 안에서 도구 호출을 자동 승인 |
| Goal | 턴 자체를 조건 충족까지 자동 반복 |
🔗 13번(루프 엔지니어링)의 native 구현이며, 외부 스크립트 방식인 Ralph와의 차이는 바로 다음 23번에서 대비한다.
한 줄 요약: Goal = 루프 엔지니어링(13번)을 Claude Code가 native로 구현한 것. 완료 조건을 한 줄로 걸어두면, 작은 모델이 매 턴 평가해 조건 충족까지 자동으로 턴을 반복한다.
23. Ralph Loop와 Goal의 차이점
15~17번의 Ralph와 22번의 Goal은 둘 다 “될 때까지 반복”이라는 루프 엔지니어링(13번)의 구현체이지만, 출처와 작동 방식이 다르다.
그림: Goal(내장 native)과 Ralph Loop(외부 플러그인)의 구현·세션/컨텍스트·상태·평가·강점 대비. 간단한 반복이면 Goal, 복잡한 외부 검증·다중 에이전트 조율이면 Ralph.
대비표
| 측면 | Goal (/goal) | Ralph Loop |
|---|---|---|
| 출처 | Claude Code 공식 native 기능 | 외부 플러그인(OMC·ouroboros 등)의 기법 |
| 구현 | 내부 Prompt 기반 Stop hook | 외부 bash 반복(while true; do claude -p ...; done) |
| 세션/컨텍스트 | 단일 세션 내 턴 반복 → 컨텍스트가 계속 누적 | 매 반복 새 세션 → 깨끗한 컨텍스트, 상태는 파일·git으로 전달 |
| 평가 방식 | 작은 모델(Haiku)이 조건을 자동 평가 | 커스텀 검증(hook·프롬프트·외부 명령) |
| 중단 조건 | 조건 충족 시 자동 | 검증 통과 또는 최대 반복 횟수 |
| 강점 | 간편·빠른 내부 반복, 설정 한 줄(/goal ...) | 복잡한 외부 검증·다중 에이전트·빌드/배포 통합에 유연 |
핵심 트레이드오프
Goal은 누적 컨텍스트라 설정이 간편하지만, 반복이 길어질수록 컨텍스트가 쌓여 성능 저하 우려가 있다. Ralph는 매번 새 컨텍스트(15·19번에서 이미 정리한 장점)라 편향·길이 문제를 피할 수 있지만, 그만큼 외부 스크립트·상태 관리(파일·git 인수인계)를 직접 챙겨야 한다.
선택 가이드
- 간단한 반복(같은 세션 안에서 조건 하나만 충족시키면 되는 작업) → Goal
- 복잡한 외부 검증·다중 에이전트 오케스트레이션이 필요한 작업 → Ralph
🔗 13번(루프 엔지니어링)·15번(Ralph)·19번(AutoResearch)과 연결.
한 줄 요약: Goal은 Claude Code native의 “턴 반복”, Ralph는 외부 플러그인·스크립트 기반의 “세션 반복” — 둘 다 자동 평가기가 있어야 성립한다는 점은 같지만, 컨텍스트를 누적할지(Goal) 매번 새로 시작할지(Ralph)가 근본적인 차이다.
24. OMC 코드 검증과 UltraQA
18번(Ralph의 한계)·20번(AlphaEvolve·AutoResearch 공통점)에서 이미 확인했듯, 자율 반복 루프가 성립하려면 자동 평가기가 반드시 있어야 한다. OMC는 이 검증 층을 여러 도구로 갖추고 있다.
그림: UltraQA는 테스트→검증→수정을 목표(품질 기준) 충족까지 반복하는 QA 사이클. 작성(writer)과 검수(reviewer)를 분리해 자기 승인을 막고, verifier·
/verify·code-reviewer로 검증 층을 갖춘다.
개념 한 줄
검증(테스트) → 확인 → 수정 → 반복을 목표 충족까지 도는 QA 워크플로가 UltraQA이며, 이는 OMC의 여러 검증 수단 중 하나다.
OMC의 검증 수단
| 수단 | 역할 |
|---|---|
| verifier 에이전트 | 완료 근거·검증 전략·테스트 적정성을 확인 |
/verify 스킬 | 완료를 주장하기 전에 변경이 실제로 동작하는지 확인 (Claude Code native built-in 스킬, 26번) |
| code-reviewer 에이전트 | 심각도 등급을 매기는 코드 리뷰 |
UltraQA(/oh-my-claudecode:ultraqa) | 테스트 → 검증 → 수정 → 반복의 QA 사이클 워크플로 |
주의 — 검증 수단은 native와 플러그인에 걸쳐 있다: /verify·/code-review는 Claude Code native built-in 스킬(26번)이고, verifier·code-reviewer 에이전트와 UltraQA는 OMC 플러그인이다.
원칙 — 작성과 검수는 분리
같은 컨텍스트에서 자기 승인을 하지 않고, 작성 패스와 검수 패스를 분리해 승인은 반드시 code-reviewer·verifier가 담당한다. 이번 21~24번 섹션도 doc-writer(초안 작성) → doc-reviewer(검수)의 별도 패스로 만들어지는 것이 같은 원칙의 실제 적용 사례다.
관점 — 왜 이 층이 필요한가
UltraQA는 루프 엔지니어링(13번)을 QA에 적용한 것이며, 이런 검증 층이 있어야 Ralph·Goal 같은 자율 루프가 안전하게 돌아간다. 이는 18번의 결론(Ralph는 “자동 검증 가능한 작업”에서만 통함)과 20번의 결론(AlphaEvolve·AutoResearch 모두 자동 평가기가 있어야 루프가 성립)으로 정확히 이어진다. 11번에서 정리한 멀티 에이전트 구성 요소 중 **검증기(Verifier)**의 실제 구현 사례이기도 하다.
🔗 11번(검증기)·13번(루프 엔지니어링)·18번(Ralph의 한계)·20번(자동 평가기 필요)과 연결.
한 줄 요약: UltraQA = 루프 엔지니어링을 QA에 적용한 OMC 워크플로. verifier·
/verify·code-reviewer와 함께 “자동 검증 가능해야 루프가 통한다”(18·20번)는 전제를 실제로 채우는 검증 층이다.
이렇게 2124번까지 오면, 서두(“들어가며”)의 질문 — AI 에이전트 시대에 사람은 무엇을 할 것인가 — 에 대한 답이 한 바퀴 돌아 완성된다. 사람은 **명세하고(파트 A, 17번), 조율하고(파트 B, 8~17번), 검증 기준을 세운다(18·20·24번)**. 코드를 직접 치는 일은 줄어들지만, 그 세 가지 — 명세·조율·검증 — 는 여전히, 그리고 앞으로도 사람의 몫으로 남는다.
25. OMC 개발 루프 자동화 — Autopilot
OMC 플러그인 스킬(
/oh-my-claudecode:autopilot). 아이디어 2~3줄만 던지면, 동작하고 검증된 코드가 나올 때까지 전체 생애주기를 자율로 실행한다.
그림: Autopilot의 5+1단계 — Expansion→Planning→Execution→QA(UltraQA)→Validation(전원 승인)→Cleanup. 각 단계 순차·단계 내 병렬이며, deep-interview→ralplan→autopilot 파이프라인으로 앞 단계를 건너뛸 수 있다.
개념 한 줄
“아이디어 → 명세 → 계획 → 구현 → QA → 검증 → 정리”까지 6단계를 사람 개입 없이 끝까지 밀어붙이는 OMC의 종합 자동화 스킬.
5+1 단계
| Phase | 이름 | 내용 |
|---|---|---|
| Phase 0 | Expansion | analyst + architect(Opus)가 짧은 아이디어를 구체적 스펙으로 확장 |
| Phase 1 | Planning | architect가 계획을 수립하고, critic이 그 계획을 검증 |
| Phase 2 | Execution | Ralph + Ultrawork 루프, executor(haiku·sonnet·opus)가 병렬로 구현 |
| Phase 3 | QA | UltraQA — 빌드·린트·테스트·수정을 반복(최대 5회), 같은 에러가 3회 반복되면 중단 |
| Phase 4 | Validation | architect·security-reviewer·code-reviewer가 병렬로 검증, 전원 승인해야 통과(거부 시 수정 후 재검증) |
| Phase 5 | Cleanup | 작업 중 생성된 상태 파일 정리 |
실행 방식
각 Phase는 순차 진행되고, Phase 내부의 여러 에이전트는 병렬 실행된다. /oh-my-claudecode:cancel로 언제든 취소할 수 있고, 재실행하면 중단 지점부터 재개한다.
3단계 파이프라인 안에서의 위치
| 단계 | 스킬 | 산출물 |
|---|---|---|
| 1 | deep-interview | 요구사항 명세 |
| 2 | ralplan | 합의된 계획 |
| 3 | autopilot | 실제 구현·검증 |
→ ralplan에서 이미 합의된 계획이 있으면, autopilot은 Phase 0·1을 건너뛰고 Phase 2부터 시작한다.
🔗 이 노트 전체의 종합판이다. 파트 A(제품 명세, 1~7번)를 잇는 명세 단계(Phase 0), Ralph·Ultrawork(루프, 13·15번)를 잇는 실행 단계(Phase 2), UltraQA(24번)를 잇는 QA 단계(Phase 3), 멀티 에이전트 검증(11번)을 잇는 Validation 단계(Phase 4)를 한 스킬로 압축했다. “사람은 아이디어를 명세하고, 나머지 루프를 자동화한다”는 이 노트의 결론을 그대로 구현한 스킬.
한 줄 요약: Autopilot = 아이디어 2~3줄에서 검증된 코드까지, 명세·계획·구현·QA·검증·정리 6단계를 자율로 도는 OMC 스킬. 각 단계는 순차, 단계 내부는 병렬로 실행되며, 합의된 계획이 이미 있으면 실행 단계부터 바로 시작한다.
26. Claude Code의 Built-in 스킬
그림: 스킬 네 갈래(내장 bundled·사용자·프로젝트·플러그인)와 SKILL.md의 점진적 로딩 — description만 항상 컨텍스트에, 본문은 호출 시 로드. Goal=native 기능,
/loop·/verify=native 스킬, autopilot·visual-verdict 등=OMC 플러그인.
개념 한 줄
Built-in(bundled) 스킬 = Claude Code에 기본 내장되어 함께 배포되는 스킬. prompt 기반으로 Claude에게 지침을 주고 도구 사용을 조율한다. 예: /code-review, /verify, /loop, /review, /security-review, /run, /init 등.
명령(command)과 bundled 스킬의 구분
고정 로직을 즉시 실행하는 built-in “명령”(/help, /compact)과, prompt 기반으로 Claude를 조율하는 “bundled 스킬”은 성격이 다르다. 다만 호출 방식은 둘 다 /이름으로 같다.
스킬의 네 가지 종류
| 종류 | 위치 | 범위 |
|---|---|---|
| bundled(내장) | Claude Code 자체에 포함 | 모든 세션 |
| 사용자 스킬 | ~/.claude/skills/ | 모든 프로젝트 |
| 프로젝트 스킬 | .claude/skills/ | 현재 프로젝트 |
| 플러그인 스킬 | 플러그인의 skills/ 디렉토리 | 해당 플러그인 설치 환경(예: OMC) |
발견과 호출
각 스킬의 SKILL.md frontmatter에 있는 description을 Claude가 현재 문맥과 매칭해 자동으로 트리거하거나, 사용자가 /이름으로 수동 호출한다. disable-model-invocation 설정을 걸면 자동 트리거를 막고 수동 호출 전용으로 만들 수 있다.
Progressive disclosure(점진적 로딩)
description만 항상 컨텍스트에 상주하고, 스킬 본문은 실제로 호출될 때만 로드된다. 설치된 스킬이 많아도 평소 토큰 비용은 최소로 유지되는 구조.
🔗 이 노트에서 다룬 것들의 큰 그림 정리: **Goal(22번)**은 Claude Code의 native 기능, /loop(27번)·/verify는 native bundled 스킬, **autopilot(25번)·ultraqa(24번)·visual-verdict(29번)·LLM Wiki(21번)**는 OMC 플러그인 스킬이다.
한 줄 요약: bundled 스킬 = Claude Code에 기본 내장된 prompt 기반 스킬. 사용자 스킬·프로젝트 스킬·플러그인 스킬과 함께 네 종류를 이루며, description만 상주하고 본문은 호출 시에만 로드되는 progressive disclosure 구조로 토큰을 아낀다.
27. loop — 반복 실행 스킬 (/loop)
출처: https://code.claude.com/docs/en/scheduled-tasks.md · Claude Code native bundled 스킬(26번)
그림:
/loop의 세 사용법(고정 5분·간격 생략 시 동적·기본)과/schedule(클라우드·영구·최소 1시간)과의 대비. 현재 작업 중 빠른 반복은/loop, 야간/정기 자동은/schedule.
개념 한 줄
현재 세션 안에서 프롬프트나 슬래시 명령을 주기적으로 반복 실행하는 스킬. 폴링·상태 확인·반복 작업에 적합하며, 세션이 닫히면 함께 멈춘다.
사용법
| 명령 | 동작 |
|---|---|
/loop 5m <prompt> | 5분 간격 고정(내부적으로 cron으로 변환) |
/loop <prompt> | 간격 생략 시 Claude가 1분~1시간 범위에서 동적으로 선택 — 진행 중이면 짧게, 조용하면 길게 |
/loop | 인자 없이 호출하면 기본 유지보수 프롬프트로 반복 |
- Esc로 언제든 중단 가능.
- 생성 후 7일이 지나면 자동 만료.
/schedule(Routines)과의 차이
| 구분 | /loop | /schedule |
|---|---|---|
| 실행 위치 | 현재 머신의 현재 세션 | Anthropic 클라우드 |
| 지속성 | 7일 만료 | 계정에 영구 등록, 머신을 꺼도 유지 |
| 최소 간격 | 1분 | 1시간 |
| 컨텍스트 | 현재 세션 컨텍스트 상속 | 없음(독립 실행) |
| 로컬 파일 접근 | 가능 | 불가 |
| 트리거 방식 | 세션 내 반복 | Schedule/API/GitHub 트리거 |
선택 가이드
- 야간·정기 자동 실행 →
/schedule - 지금 하고 있는 작업의 빠른 반복 확인(PR 모니터링, 빌드 대기 등) →
/loop
🔗 루프 엔지니어링(13번)의 “시간 기반 반복” 형태다. 조건이 충족될 때까지 도는 Goal(22번, 조건 기반), 파일·git으로 상태를 이어가는 자기참조형 **Ralph(15번)**와 나란히 놓이는, 이 노트의 세 번째 루프 구현 방식.
한 줄 요약:
/loop= 세션 안에서 정해진(또는 동적으로 조절되는) 간격으로 프롬프트를 반복하는 native bundled 스킬. 세션 종속·7일 만료가 특징이며, 계정에 영구 등록되는/schedule과는 지속성·간격·로컬 접근성에서 갈린다.
28. QA 자동화 워크플로우 설계
지금까지 나온 검증 요소들(UltraQA, visual-verdict, verifier, 반복 엔진)을 하나의 QA 자동화 파이프라인으로 엮어보는 종합 설계 섹션.
그림: 코드 변경 → 기능 검증(UltraQA) → 시각 검증(visual-verdict·CDP) → 완료 근거(verify) → 종료 조건 미충족이면 반복(엔진:
/loop·Goal·Ralph), 충족 시 완료. 설계 4원칙(명확한 종료 조건·작성/검수 분리·기능+시각 이중 검증·반복 안전장치) 포함.
개념 한 줄
기능 검증 + 시각 검증 + 완료 근거 확인을 한 파이프라인에 묶고, 통과할 때까지 반복 엔진으로 돌리는 QA 워크플로.
파이프라인
코드 변경
│
▼
① 기능 검증: 빌드·린트·테스트 (UltraQA, 24번)
│
▼
② 시각 검증: 스크린샷 캡처 후 레퍼런스와 대조 (visual-verdict, 29번 / 캡처 엔진: CDP, 30번)
│
▼
③ 완료 근거 확인 (verifier · `/verify`, 24번)
│
├─ 통과 못 하면 → 반복 엔진으로 되돌아감 (`/loop` 27번 · Goal 22번 · Ralph 15번 중 선택)
│
▼
자동 평가기(테스트 결과 + 시각 verdict)가 종료 조건 판단설계 원칙
| 원칙 | 내용 |
|---|---|
| 측정 가능한 종료 조건 | ”잘 됐는지”가 아니라 테스트 통과·verdict 점수 같은 명확한 수치·상태로 판단 |
| 작성/검수 분리 | 같은 컨텍스트에서 자기 승인 금지(24번 원칙과 동일) |
| 기능+시각 이중 검증 | 테스트는 로직을, visual-verdict는 눈에 보이는 결과를 각각 담당 — 한쪽만으로는 부족 |
| 반복 안전장치 | 최대 반복 횟수·비용 상한을 반드시 둠(16·18번에서 이미 강조된 원칙) |
완성형 구현
**Autopilot(25번)의 Phase 3(QA) + Phase 4(Validation)**가 이 설계를 실제로 구현한 사례에 해당한다 — 기능 검증(UltraQA)과 병렬 승인(다중 리뷰어)이 이미 파이프라인 안에 들어 있다.
🔗 24번(UltraQA·verifier)·29번(visual-verdict)·30번(CDP)·27번(/loop)·22번(Goal)·15번(Ralph) 종합.
한 줄 요약: QA 자동화 = 기능 검증(UltraQA) → 시각 검증(visual-verdict) → 완료 근거 확인(verifier) → 반복(loop/goal/ralph)을 하나로 묶은 파이프라인. 측정 가능한 종료 조건과 작성/검수 분리가 핵심 설계 원칙이며, Autopilot의 Phase 3·4가 이를 실제로 구현한 완성형이다.
29. OMC의 매서운 눈 — visual-verdict
OMC 플러그인 스킬(
/oh-my-claudecode:visual-verdict). 생성된 UI 스크린샷을 레퍼런스 이미지와 대조해 엄격한 JSON verdict를 반환한다.
그림: 레퍼런스 이미지 + 생성 스크린샷 → 대조 → JSON verdict(score·verdict·category_match·differences·suggestions·reasoning) → score≥90이면 pass, 미만이면 편집 후 재실행 반복. 픽셀 diff는 보조 디버그.
개념 한 줄
“이 화면이 레퍼런스와 얼마나 닮았는가”를 사람 대신 점수·판정으로 잘라 말해주는 시각 QA 스킬.
입력
| 입력 | 설명 |
|---|---|
reference_images[] | 비교 기준이 되는 레퍼런스 이미지 |
generated_screenshot | 현재 생성된 출력 스크린샷 |
category_hint(선택) | 화면 유형 힌트 |
출력(JSON only)
| 필드 | 내용 |
|---|---|
score | 0~100 정수 |
verdict | pass / revise / fail |
category_match | 레퍼런스와 같은 카테고리(화면 유형)인지 bool |
differences[] | 구체적인 시각 불일치 목록 |
suggestions[] | 다음 편집을 위한 제안 |
reasoning | 1~2문장 판정 근거 |
통과 기준과 반복
통과 임계는 90점 이상이다. 대략 90 이상이면 pass, 그 미만은 차이 정도에 따라 고칠 수 있으면 revise(편집 후 재판정), 방향 자체가 틀리면 fail로 갈린다. 90 미만이면 편집 후 /oh-my-claudecode:visual-verdict를 다시 실행하는 식으로 반복하며, 임계를 넘기 전까지는 시각 작업을 완료로 치지 않는다.
픽셀 diff는 보조일 뿐
pixelmatch 같은 픽셀 단위 diff 오버레이는 디버깅 보조 자료에 그치고, 최종 판단은 어디까지나 verdict가 내린다.
🔗 QA 자동화 파이프라인(28번)의 시각 검증 축이다. 텍스트·테스트로는 못 잡는 레이아웃·간격·타이포·색 차이를 정량적으로 판정한다. (참고: 이 노트에 들어간 SVG들도 브라우저로 렌더링해 육안으로 검증했는데, 그 판정 과정을 자동화·정량화한 것이 visual-verdict라고 볼 수 있다.)
한 줄 요약: visual-verdict = 스크린샷을 레퍼런스와 대조해 score·verdict·차이점·제안을 JSON으로 반환하는 OMC 스킬. 90점 미만이면 편집→재검증을 반복하며, 픽셀 diff는 보조일 뿐 최종 판정은 verdict가 담당한다.
30. CDP (Chrome DevTools Protocol)란?
그림: 제어 측(헤들리스 Chrome·Puppeteer 등) ⇄ WebSocket(JSON-RPC) ⇄ Chromium 브라우저의 도메인(Page·DOM·Network·Runtime·Performance·스크린샷). AI 생성 UI → CDP로 캡처 → visual-verdict 판정으로 이어지는 시각 QA의 캡처 엔진.
개념 한 줄
Chromium 계열 브라우저를 프로그램으로 제어·계측하는 프로토콜. WebSocket 위에서 JSON(JSON-RPC) 메시지를 주고받으며, 브라우저에 명령을 보내고 이벤트를 받는다.
주요 도메인(기능 영역)
| 도메인 | 역할 |
|---|---|
| Page | 페이지 이동·로드 제어 |
| DOM | 요소 조회·조작 |
| Network | 네트워크 요청 가로채기·관찰 |
| Runtime | 페이지 안에서 JS 실행 |
| Performance | 성능 지표 측정 |
| 스크린샷 캡처 | 현재 화면을 이미지로 저장 |
이를 활용하는 도구
헤드리스 Chrome, Puppeteer, Lighthouse 등이 CDP 위에서 동작한다. (Playwright는 자체 프로토콜을 위주로 쓰되, Chromium 대상 작업에서는 CDP도 일부 활용하는 것으로 알려져 있음 — 도구별 채택 정도는 버전에 따라 달라질 수 있어 단정하지 않음.)
이 노트에서의 위치
visual-verdict(29번)·QA 자동화(28번) 파이프라인에서 “스크린샷을 어떻게 얻는가”의 하부 엔진에 해당한다. AI가 만든 UI를 브라우저로 열어 캡처하고, 그 결과를 verdict로 판정하는 흐름의 기반 기술.
(참고: 이 노트에 들어간 이미지들도 헤드리스 Chrome으로 렌더링·캡처했는데, 그 캡처 과정이 CDP 계열 메커니즘에 해당한다.)
※ CDP는 널리 쓰이는 안정적 표준이지만, 특정 도구의 채택 정도·구현 방식은 버전에 따라 달라질 수 있다.
한 줄 요약: CDP = WebSocket 기반 JSON 메시지로 Chromium 브라우저를 원격 제어·계측하는 프로토콜. 헤드리스 Chrome·Puppeteer·Lighthouse 등이 이를 활용하며, visual-verdict·QA 파이프라인에서는 스크린샷 캡처의 하부 엔진 역할을 한다.
31. CDP MCP의 단점
CDP를 MCP 서버로 감싸 브라우저를 LLM에 붙이는 방식(30번 CDP + MCP)에는 뚜렷한 단점이 있다.
그림: ①브라우저 별도 프로세스로 리소스 차지 ②MCP 호출이 일회성이라 동작을 재실행 가능한 코드로 남기기 어려움 ③접근성 스냅샷·스키마로 토큰 비용 큼 — 같은 10단계 작업이 MCP ~114k vs CLI ~27k(보도된 예시).
개념 한 줄
“그냥 CDP를 MCP로 붙이면 되지 않나”가 편리한 만큼, 리소스·재현성·토큰 세 가지에서 대가를 치른다.
핵심 단점
| 단점 | 내용 |
|---|---|
| 별도 프로세스 리소스 | 브라우저를 별도 프로세스로 띄워야 해 메모리·CPU 등 리소스를 차지한다 |
| 동작을 코드로 남기기 어려움 | MCP 도구 호출은 일회성이라, 브라우저 상태가 LLM 컨텍스트에만 머문다 — 나중에 재실행 가능한 코드·스크립트로 저장·재현하기 어렵다 |
| 토큰 비용 | 접근성 스냅샷이 페이지당 대략 3,800~4,000 토큰, 도구 스키마 부담은 별도로 큼. 매 액션마다 스냅샷을 받으면 10단계 작업이 약 114,000 토큰까지 갈 수 있음(같은 작업을 CLI로 하면 약 27,000 토큰, 약 4배 차이 — 보도된 예시 수치) |
정리
“그냥 CDP를 MCP로 붙이면” 편하지만 리소스·재현성·토큰에서 아쉬움이 남는다. 그래서 32~34번의 대안(Playwright, CLI, Browser Harness)이 이어진다.
🔗 30번(CDP)·MCP(2026-06-27 노트)·컨텍스트 엔지니어링(2026-06-27 노트 6번)과 연결.
한 줄 요약: CDP를 MCP로 감싸는 방식은 별도 브라우저 프로세스의 리소스 부담, 재실행 가능한 코드로 남기기 어려운 일회성 도구 호출, 그리고 접근성 스냅샷·도구 스키마로 인한 큰 토큰 비용이라는 세 가지 단점을 가진다.
참고: https://playwright.dev/docs/getting-started-mcp (공식 MCP 문서) · 토큰 비교 수치(114k/27k)는 커뮤니티 보도 예시로, 버전·환경에 따라 다를 수 있다.
32. Playwright란?
Microsoft가 만든 브라우저 자동화 프레임워크. Claude Code native 기능도 OMC 플러그인도 아닌, 외부 도구다.
그림: 다중 브라우저(Chromium·Firefox·WebKit)를 하나의 API로 제어. auto-wait·네트워크 가로채기·스크린샷·codegen에 크로스 언어(JS/TS·Python·Java·.NET) 지원 — 접근성 트리 기반이라 AI 에이전트 자동화의 사실상 기본값.
개념 한 줄
코드로 브라우저를 열고·클릭하고·확인하는, AI 에이전트 브라우저 자동화의 사실상 기본값.
특징
| 특징 | 내용 |
|---|---|
| 다중 브라우저 | Chromium·Firefox·WebKit 지원 |
| auto-wait | 요소가 준비될 때까지 자동 대기 |
| 네트워크 가로채기 | 요청·응답을 가로채 관찰·조작 |
| 스크린샷 | 화면 캡처 |
| codegen | 사람의 동작을 녹화해 코드로 변환 |
| 크로스 언어 | JS/TS·Python·Java·.NET 지원 |
AI 에이전트와의 접점
접근성 우선 로케이터(getByRole 등)와 auto-wait 같은 AI 친화적 API 덕에 에이전트 브라우저 자동화에 자주 채택된다. 원래는 “사람이 테스트 코드를 작성”하는 도구였지만, AI 시대엔 에이전트가 쓰는 브라우저 제어 계층으로도 활용된다. (참고: 페이지를 접근성 스냅샷으로 다루는 방식은 주로 33번의 Playwright MCP 형태의 특징이다.)
🔗 30번 CDP(그 위 계층/대안), QA 자동화(28번)·visual-verdict(29번)의 “브라우저 조작·캡처” 축과 연결.
한 줄 요약: Playwright = Microsoft의 브라우저 자동화 프레임워크. 다중 브라우저·auto-wait·네트워크 가로채기·codegen을 갖췄고, 접근성 우선 로케이터 등 AI 친화적 API 덕에 AI 에이전트의 브라우저 제어 계층으로도 널리 쓰인다.
33. Playwright vs Playwright-MCP vs Playwright-CLI
같은 Playwright 코어를 세 가지 형태로 감싼 것. 셋 다 Microsoft Playwright 계열의 외부 도구이며, Claude Code native 기능이나 OMC 플러그인이 아니다.
그림: 라이브러리(상태=코드·파일, 재사용 스크립트) vs MCP(상태=LLM 컨텍스트, 접근성 스냅샷, 토큰 ~114k) vs CLI(상태=디스크 YAML, 셸 명령, ~27k·약 1/4로 절감). 핵심 축은 “상태가 어디 사는가”와 토큰 효율.
개념 한 줄
같은 자동화 엔진이라도, 상태(state)가 코드·LLM 컨텍스트·디스크 중 어디에 사는가에 따라 토큰 효율과 쓰임새가 갈린다.
대비표
| 형태 | 무엇 | 상태가 사는 곳 | 특징 |
|---|---|---|---|
| Playwright (라이브러리) | 코드로 스크립트 작성 | 코드·파일 | 사람이 작성 → 반복 실행 가능한 재사용 자산 |
| Playwright MCP | MCP 서버로 브라우저 도구 노출(@playwright/mcp) | LLM 컨텍스트 | 접근성 스냅샷 기반(스크린샷·비전 모델 불필요). 상태·도구 스키마가 컨텍스트에 남아 토큰 부담이 큼(예: 10단계 작업 ~114,000 토큰). 탐색적·자기치유형 루프에 유리 |
| Playwright CLI | 셸 명령(@playwright/cli, 2026년 초 등장) | 디스크(YAML 파일 경로만 컨텍스트에 남음) | 명령 기반, 토큰 효율적(예: ~27,000 토큰 — MCP 대비 약 1/4). 고처리량 코딩 에이전트에 적합 |
핵심 축과 선택 가이드
핵심 축은 두 가지 — ① 상태가 어디 사는가(코드 / LLM 컨텍스트 / 디스크) ② 토큰 효율. 최근엔 “MCP → CLI로 무게중심이 옮겨간다”는 흐름도 언급된다.
| 상황 | 추천 |
|---|---|
| 재사용 가능한 스크립트가 필요할 때 | Playwright 라이브러리 |
| 탐색적 에이전트 루프·풍부한 introspection이 필요할 때 | Playwright MCP |
| 고처리량·토큰 절약이 중요할 때 | Playwright CLI(+SKILL 조합) |
🔗 31번(MCP의 단점=프로세스·토큰), 26번(Built-in 스킬, CLI+SKILL 조합), 28번(QA 자동화)과 연결.
한 줄 요약: Playwright(코드) vs MCP(LLM 컨텍스트, 토큰 큼) vs CLI(디스크, 토큰 절약) — 같은 엔진을 상태 위치와 토큰 효율에 따라 다르게 감싼 세 형태이며, 재사용 스크립트=라이브러리, 탐색적 루프=MCP, 고처리량=CLI로 나눠 쓴다.
출처: https://github.com/microsoft/playwright-mcp , https://playwright.dev/docs/getting-started-mcp
※ CLI는 2026년 초 등장한 신생 도구라 세부는 버전에 따라 다를 수 있다.
34. Browser Harness란?
Browser Use가 공개한, AI 에이전트와 실제 브라우저 사이의 가장 얇은 연결 계층. Claude Code native 기능이나 OMC 플러그인이 아닌 외부 오픈소스 도구다.
그림: 에이전트 ⇄ Browser Harness ⇄ Chrome(CDP 직결). 페이지 스냅샷 → “다음 액션?” → 실행을 완료까지 반복하며, 헬퍼가 없으면 에이전트가 raw CDP로 직접 작성하는 자기치유(~600줄) 구조. Playwright(사람이 스크립트)와 달리 에이전트가 스스로 판단해 행동 — 9번 하네스 엔지니어링의 브라우저 버전.
개념 한 줄
에이전트가 페이지를 보고 스스로 판단해 한 스텝씩 행동하도록, CDP로 Chrome에 직접 접근하는 최소한의 실행 골격.
동작 루프
에이전트가 작업 설명으로 harness 호출
│
▼
harness가 페이지를 열고 스냅샷
│
▼
모델에게 "다음에 뭐 할까?" 질의
│
▼
모델이 액션(클릭·입력·스크롤)으로 응답
│
▼
harness가 액션 실행 ── (완료까지 반복)자기치유(self-healing)
약 600줄 규모의 harness로, 필요한 헬퍼 함수가 없으면 에이전트가 헬퍼 모듈(예: helpers.py)을 읽고 raw CDP로 그 함수를 직접 작성해 이어간다 — 실행 도중 스스로 부족한 부분을 채우는 자기치유 구조.
Playwright와의 차이
| 구분 | Playwright | Browser Harness |
|---|---|---|
| 각본 | 사람이 스크립트를 미리 작성 | 에이전트가 매 스텝 스스로 판단 |
| 실행 방식 | 정해진 대로 실행 | 페이지를 보고 관찰→결정→행동을 반복 |
🔗 9번 하네스 엔지니어링의 브라우저 버전 — “모델을 감싸 행동→관찰→반복시키는 실행 골격”을 브라우저 제어에 적용한 사례. 루프 엔지니어링(13번)·visual-verdict(29번)·CDP(30번)와도 연결.
한 줄 요약: Browser Harness = CDP로 Chrome에 직접 접근해, 에이전트가 스냅샷을 보고 다음 액션을 스스로 결정·실행하게 하는 얇은 연결 계층. 헬퍼 함수가 없으면 raw CDP로 직접 작성하는 자기치유 구조를 갖췄으며, 사람이 각본을 짜는 Playwright와 대비된다.
출처: https://github.com/browser-use/browser-use
※ browser-use / Browser Harness는 빠르게 변하는 신생 도구라 세부는 버전에 따라 다를 수 있다.
35. cua-driver란?
trycua가 만든 오픈소스 백그라운드 “컴퓨터-사용(computer-use)” 드라이버. 34번 Browser Harness가 브라우저(CDP)에 국한되는 것과 달리, 네이티브 데스크톱 앱 전반을 대상으로 한다. Claude Code native 기능도 OMC 플러그인도 아닌 외부 오픈소스 도구다.
그림: 코딩 에이전트 → MCP/CLI(동일 표면) → cua-driver → 네이티브 데스크톱 앱. 핵심은 커서·포커스를 빼앗지 않고 백그라운드로 클릭·입력·스크롤·접근성 트리 조회·창 캡처. macOS·Windows·Linux·Android를 지원하며 Cua 인프라(driver·agent·sandbox·bench)의 일부. 제어 표면이 CDP(30)→Playwright(32)→Browser Harness(34)→cua-driver(35, 데스크톱 전체)로 넓어진다.
개념 한 줄
커서·포커스를 빼앗지 않고 백그라운드에서, 네이티브 데스크톱 앱을 클릭·입력·스크롤·조회하게 해주는 드라이버.
기능
| 기능 | 내용 |
|---|---|
| 조작 | 클릭·입력·스크롤 |
| 조회 | 접근성 트리(accessibility tree) 조회 |
| 캡처 | 창(window) 상태 캡처(스크린샷) |
| 표면 | 위 기능을 MCP/CLI 동일 표면으로 제공 |
핵심 차별점 — 백그라운드 동작
34번 Browser Harness나 32~33번 Playwright류가 브라우저 안에서 동작하는 것과 달리, cua-driver는 커서·포커스를 가로채지 않고 백그라운드에서 동작한다. 즉 사람이 컴퓨터를 그대로 쓰는 동안에도, 에이전트가 별도로 다른 앱을 조작할 수 있다.
크로스 플랫폼
| 대상 | 지원 |
|---|---|
| macOS | O |
| Windows | O |
| Linux | O |
| Android | O |
| 스케일 | 컴퓨터 “플릿(fleet)” 단위로 확장 |
사용 방식 — CLI + MCP
CLI 도구이자 MCP 서버, 양쪽으로 동작한다. Claude Code·Cursor·Codex·OpenClaw 등의 MCP 설정에 추가하면, 코딩 에이전트에 “스크린샷·클릭·입력” 도구가 생겨 실제 네이티브 앱을 조작하게 할 수 있다 — 단, 이는 Claude Code 자체 기능이 아니라 외부 MCP 서버로서 붙는 것이다.
Cua 인프라 안에서의 위치
| 구성 | 역할 |
|---|---|
| cua-driver | 백그라운드 컴퓨터-사용 드라이버(이 절의 주제) |
| cua-agent | 컴퓨터-사용 에이전트 프레임워크 |
| cua-sandbox | 샌드박스 생성·제어 SDK |
| cua-bench | 벤치마크·RL 환경 |
→ “컴퓨터-사용 에이전트 인프라를 주말 해킹이 아니라 진짜 인프라로 취급”한다는 지향.
🔗 34번 Browser Harness(브라우저 한정·CDP)와 대비 — cua-driver는 데스크톱 전체 + 백그라운드 + MCP/CLI 표면. 30~33번(브라우저 자동화·CDP·MCP/CLI), 9번(하네스 엔지니어링)과도 이어진다. MCP/CLI 두 표면을 다 제공하는 점은 33번(Playwright MCP vs CLI)의 구도와 닮았다.
한 줄 요약: cua-driver = 커서·포커스를 뺏지 않고 백그라운드에서 네이티브 데스크톱 앱을 클릭·입력·스크롤·캡처하는 오픈소스 컴퓨터-사용 드라이버. MCP/CLI 두 표면으로 Claude Code 등 코딩 에이전트에 붙여 쓸 수 있으며, cua-agent·cua-sandbox·cua-bench와 함께 더 큰 Cua 인프라를 이룬다.
출처: https://github.com/trycua/cua , https://cua.ai
※ 신생·빠르게 변하는 프로젝트라 세부는 버전에 따라 다를 수 있다.
맺음말 — 30~35번을 관통하는 흐름
CDP(30) → Playwright(32) → MCP/CLI 대비(31 단점·33) → Browser Harness(34) → cua-driver(35)로 이어지며, “AI 에이전트에게 브라우저·컴퓨터를 어떻게 쥐여줄 것인가”라는 질문에 대한 제어 표면이 브라우저 한정에서 데스크톱 전체로 점점 넓어진다.
참고: 19·20번의 AutoResearch·AlphaEvolve 관련 일정·수치는 공개된 발표·보도 기준이며, 향후 업데이트될 수 있다. 실제 적용 전에는 각 프로젝트의 최신 저장소·공식 발표를 함께 확인할 것. 21·23·24번의 OMC(oh-my-claudecode) 관련 스킬·에이전트명은 플러그인 버전에 따라 달라질 수 있으니 실제 사용 전 해당 플러그인 문서를 확인할 것. 31~35번의 Playwright(Microsoft)·Browser Use·cua-driver(trycua)는 Claude Code native 기능도 OMC 플러그인도 아닌 외부 도구이며, 토큰 수치·CLI 등장 시점·browser-use/cua 세부는 예시/보도 수치이자 버전에 따라 달라질 수 있으니 실제 사용 전 각 프로젝트의 최신 문서를 확인할 것.