Claude Code의 'Import other agent setup'은 CLI에서도 쓸 수 있나?

아니다. Import other agent setup은 Codex Mac 데스크톱 앱 전용 UI 버튼으로, CLI에는 동일한 명령이 없다. CLI 사용자는 CLAUDE.md를 직접 분류해서 AGENTS.md와 config.toml로 옮겨야 한다.

CLAUDE.md를 Codex로 그대로 복사해도 되나?

그대로 복사하는 것은 권장되지 않는다. CLAUDE.md 안의 권한 지시(allow/deny), hooks 설정은 Codex의 sandbox_mode·approval_policy·Rules 체계와 1:1로 맞지 않는다. 팀 컨벤션과 개인 취향만 AGENTS.md로 옮기고, 나머지는 config.toml과 .rules 파일로 재설정하는 것이 안전하다.

Smoke Test는 어떻게 시작하면 좋은가?

먼저 AGENTS.md 파일이 올바른 위치(~/.codex/AGENTS.md 또는 프로젝트 루트 AGENTS.md)에 있는지 확인한 뒤, read-only sandbox 모드로 Codex를 실행해 간단한 설명 요청을 해본다. 파일을 변경하지 않는 작업으로 sandbox와 approval 정책이 의도대로 작동하는지 검증하는 것이 핵심이다.

Codex 자동화를 가장 빠르게 시작하는 방법은?

저장소 루트에서 codex exec --sandbox read-only 명령 하나로 시작한다. GitHub Actions나 CI 설정 없이도 로컬에서 바로 저장소 분석, 파일 검토, 커밋 전 체크를 자동화할 수 있다.

처음부터 GitHub Actions를 설정해야 하나?

아니다. 로컬 codex exec로 자동화를 먼저 익히고, 팀 공유 패턴을 만든 뒤에 GitHub Actions로 옮기는 순서가 훨씬 쉽다. 레벨 1~2만 해도 일상 업무에서 충분히 쓸 수 있다.

API key는 어디에 보관해야 안전한가?

로컬 개발에서는 .env 파일 또는 환경변수에, CI에서는 GitHub repository secret에 저장한다. 절대 코드에 직접 쓰거나 git에 커밋하지 않는다.

갓대희의 작은공간

Google AI SEO 최적화 가이드 리뷰 : AI 검색 시대, 하던 SEO를 잘 하면 된다( AEO·GEO는 SEO의 다른 이름이다)

갓대희 — Tue, 19 May 2026 18:30:51 +0900

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

오늘 작성할 내용은 AI가 SEO를 죽인다는 주제이다.

AEO, GEO라는 새 약어가 등장했고, llms.txt를 만들어야 한다거나 콘텐츠를 잘게 쪼개야 한다거나 하는 조언이 넘쳐난다. 2026년 5월, Google이 드디어 공식 답변을 내놨다.

Google AI 최적화 가이드(AIO 가이드)는 "AI Overview·AI Mode 시대에 무엇을 해야 하는가"에 대한 Google의 공식 입장이다. 결론부터 말하면, 하던 것을 잘 하면 된다. 단, 그 안에 담긴 논리와 새로운 개념, 특히 에이전트 경험(Agentic experiences)은 앞으로 웹의 방향을 바꿀 것이다.

이 글은 그 가이드의 핵심을 풀어보고, 지금 당장 해야 할 일을 정리한다.

먼저 용어부터 가볍게 잡고 가자

SEO(검색엔진 최적화): Google 같은 검색엔진에서 내 글·사이트가 상위 결과에 나오도록 최적화하는 작업 — 이 글 전반에서 '기존 방식'으로 언급되는 것
AI Overview(AI 오버뷰): 검색 결과 상단에 AI가 요약 답변을 생성해 보여주는 기능
AI Mode: AI Overview를 확장한 대화형 검색 모드
RAG(Retrieval-Augmented Generation): 검색 인덱스에서 문서를 가져와 AI 답변에 활용하는 기술 — "grounding"이라고도 부름
Query fan-out: 하나의 질문에 대해 AI가 여러 관련 쿼리를 병렬로 실행해 더 많은 자료를 수집하는 기법
AEO(Answer Engine Optimization): AI 답변 엔진에 최적화한다는 뜻으로 쓰이던 용어
GEO(Generative Engine Optimization): 생성형 AI 검색에 최적화한다는 뜻으로 쓰이던 용어
llms.txt: 사이트에 LLM이 참고할 정보를 제공하기 위해 만드는 텍스트 파일 (표준안)
Agentic experiences(에이전트 경험): AI 에이전트가 사용자 대신 예약·비교·구매 등 작업을 수행하는 새로운 웹 상호작용 형태

배경: AI 검색이 바꾼 것과 바꾸지 못한 것
핵심 개념: AI 검색의 기술적 작동 방식
작동 원리: AI 검색은 내 콘텐츠를 어떻게 가져오는가
실무 적용: 콘텐츠·기술·커머스
지금 당장 할 수 있는 체크리스트
통념 파괴: llms.txt·청킹·AI 마크업이 필요 없는 이유
에이전트 경험 — 웹의 다음 레이어
결론: 지금 무엇을 해야 하는가

1. 배경: AI 검색이 바꾼 것과 바꾸지 못한 것

Google은 2026년 5월 15일, AI Overview와 AI Mode에 대응하는 공식 최적화 가이드를 발표했다.

기존에 여기저기 흩어져 있던 AI 검색 관련 안내들을 하나의 공식 문서로 정리한 것이다.

Search Engine Land의 보도에 따르면, 이 가이드의 핵심 메시지는 "AI 검색을 위한 별도 전략은 없다"이다.

가이드가 나오기까지의 맥락이 중요하다.

마케팅 업계에는 AEO, GEO라는 새 개념이 난무했고, llms.txt 파일을 서버에 올려야 한다거나 콘텐츠를 AI가 읽기 좋게 잘게 쪼개야(이를 '청킹'이라 부른다) 한다는 조언이 쏟아졌다.

기존 SEO 대행사들이 구식 기법에 'AI' 라벨만 붙여 팔고 있다는 비판도 Reddit r/SEO, r/bigseo 커뮤니티에서 반복적으로 제기됐다. 검색 생태계 전반에서 혼란이 증폭되던 시점에 이 가이드가 나왔다.

Google의 공식 입장은 간결하다.

"The best practices for SEO continue to be relevant because our generative AI features on Google Search are rooted in our core Search ranking and quality systems."
“Google 검색의 생성형 AI 기능은 핵심 검색 순위 시스템과 품질 평가 시스템을 기반으로 작동하기 때문에, 기존 SEO 모범 사례는 여전히 중요합니다.”

— Google AI 최적화 가이드

AI Overview와 AI Mode는 Google의 핵심 검색 랭킹 및 품질 시스템 위에 구축됐다. 좋은 SEO는 여전히 좋은 AI 검색 노출로 이어진다는 공식 확인이다.

2. 핵심 개념: AI 검색의 기술적 작동 방식

RAG와 grounding — AI 답변이 만들어지는 구조

AI Overview의 답변은 허공에서 나오지 않는다.

Google은 RAG(Retrieval-Augmented Generation, 검색 증강 생성) 방식을 사용해 핵심 검색 랭킹 시스템으로 웹 인덱스에서 관련 페이지를 가져온 뒤 그 내용을 AI 답변에 반영한다. 가이드는 이 과정을 "grounding"이라고 부르며, 답변의 품질·정확도·최신성을 높이는 핵심 메커니즘으로 설명한다.

즉, AI 검색에 노출되려면 먼저 Google 인덱스에 잘 들어가 있어야 한다. AI가 별도의 소스를 참조하는 게 아니라, 기존 검색 랭킹 결과를 그대로 활용한다는 뜻이다.

Query fan-out — 하나의 질문이 여러 검색으로 분화한다

AI Mode에서 사용자가 하나의 질문을 하면, 모델은 관련된 여러 쿼리를 병렬로 실행해 더 많은 자료를 수집한다. 이를 Query fan-out이라고 한다.

이게 실제로 어떤 의미인지 살펴보자.

단순히 특정 키워드에 최적화된 단일 글보다, 특정 주제를 여러 각도에서 깊게 다룬 콘텐츠가 Query fan-out의 여러 쿼리에 걸쳐 노출될 가능성이 높다. 주제 심도(topic depth)가 표면적 키워드 밀도보다 중요해지는 이유다.

AEO·GEO는 SEO다 — 용어 정리

Search Engine Land의 분석에 따르면, 이 가이드는 AEO(Answer Engine Optimization)와 GEO(Generative Engine Optimization)가 SEO와 별개 전략이 아니라 AI 검색 환경에 적용된 SEO일 뿐이라는 점을 명확히 한다. Google은 AI 검색을 위한 독자적인 최적화 방법론을 인정하지 않는다.

결국 AEO·GEO 컨설팅을 표방하는 서비스가 제공하는 'AI 전용' 기법들은 대부분 기존 SEO를 재포장한 것이거나, 효과가 없는 것들이다.

3. 작동 원리: AI 검색은 내 콘텐츠를 어떻게 가져오는가

AI Overview 노출의 실질적 경로

AI Overview 링크의 96%는 상위 10위 오가닉 검색 결과에서 나온다는 Brainlabs 데이터가 있다. (출처: ppc.land의 Brainlabs 데이터 재인용)

이 수치가 말하는 것은 단순하다: AI 오버뷰에 등장하고 싶다면 먼저 오가닉 검색 상위에 들어야 한다.

AI 검색이 새로운 채널처럼 보이지만, 실제 콘텐츠 접근 경로는 기존 검색 인덱스와 동일하다. 별도의 파이프라인이 아니다.

무엇을 해야 하는지 — 가이드의 두 축

가이드는 AI 검색 최적화의 방향을 두 가지로 압축한다.

첫 번째: 가치 있는 비상품형 콘텐츠 창출.

가이드는 이것이 다른 어떤 권장 사항보다 AI 검색 노출에 더 큰 영향을 미친다고 명시한다. (Search Engine Land)

비상품형 콘텐츠(non-commodity content)란 어디서나 구할 수 있는 일반적 정보가 아니라, 독자적인 관점·심층 분석·고유한 경험이 담긴 콘텐츠다.

가이드가 구체적으로 권장하는 콘텐츠는 이렇다: 나만의 관점이 담긴 글, 독자에게 실질적으로 유용한 정보, 명확한 구성과 품질 좋은 이미지·영상. 키워드를 억지로 욱여넣거나 내용을 반복 변형한 글은 오히려 불리하다.

두 번째: 명확한 기술 구조 구축

크롤러블 HTML, 시맨틱 마크업, JavaScript SEO 모범 사례, 좋은 페이지 경험, 중복 콘텐츠 최소화가 기술 축이다.

4. 실무 적용: 콘텐츠·기술·커머스

콘텐츠 전략 — 비상품형 고유 인사이트가 유리한 이유

AI 검색에서 비상품형 콘텐츠가 유리한 이유는 Google 가이드가 명시한 콘텐츠 속성에서 비롯된다.

가이드는 독자적 관점 제공, 유용하고 신뢰할 수 있는 비상품형 자료 창출을 AI 검색 노출에 영향을 미치는 핵심 요소로 꼽는다.

블로거와 개발자에게 직접적으로 적용하면:

남들이 정리한 것을 재정리하는 콘텐츠보다, 직접 테스트하거나 분석한 내용을 담은 글이 AI 검색에서 더 유리하다.

트래픽을 위해 키워드를 남발한 글보다, 독자에게 실질적 가치를 주는 심층 분석이 앞으로 더 많이 인용된다.

기술 구조 최적화 — 시맨틱 HTML의 재발견

기술 구조에서 주목할 포인트는 시맨틱 HTML에 대한 Google의 입장이다:

"사람이 읽기 좋게 작성하면 되고, 완벽한 코드 검증은 필요 없다." HTML 마크업의 기계적 완벽함보다 독자가 쉽게 이해하는 구조가 더 중요하다는 뜻이다.

JavaScript 기반 프레임워크(React, Vue, Next.js 등)를 사용한다면 콘텐츠가 차단 없이 크롤링되는지 확인하는 것이 우선이다. Google은 차단되지 않은 JavaScript 콘텐츠를 처리할 수 있지만, 일반 HTML보다 더 복잡한 과정이 필요하다. 의외로 자주 막히는 부분이 바로 JavaScript 렌더링 차단 설정이다.

로컬 비즈니스·이커머스 — 커머스 에이전트의 입구

로컬 비즈니스와 이커머스 운영자에게는 Google Business Profile과 Merchant Center 피드가 AI 응답 노출의 핵심 입구가 된다.

이와 함께 Google은 Business Agent를 소개했다. 검색에서 브랜드와 고객이 직접 대화할 수 있는 경험으로, Lowe's, Michael's, Poshmark, Reebok 등과 함께 2026년 1월에 런칭됐다. AI 에이전트가 쇼핑 여정 전체를 중개하는 방향으로 커머스 생태계가 이동하고 있음을 보여주는 사례다.

5. 지금 당장 할 수 있는 체크리스트

Google 가이드의 "다음 단계" 섹션과 기술 구조 권장 사항을 블로거·개발자 관점에서 실행 가능한 항목으로 정리했다.

우선순위	항목	확인 방법
즉시	기존 SEO 모범 사례 점검 (Search Console 오류 해결)	Google Search Console → Coverage 탭
즉시	비상품형 콘텐츠 감사 — 독자적 관점·데이터가 없는 글 목록화	직접 검토
즉시	JavaScript 렌더링 차단 여부 확인	Google Search Console → URL 검사
단기	고유 인사이트 콘텐츠 기획 — 직접 테스트·분석 포함	콘텐츠 캘린더
단기	시맨틱 HTML 구조 점검 (heading 계층, alt 텍스트 등)	Lighthouse → Accessibility
단기	중복 콘텐츠 정리 및 canonical 태그 확인	Screaming Frog 또는 Search Console
이커머스	Merchant Center 피드 최신화	Google Merchant Center
이커머스/로컬	Google Business Profile 정보 최신화	Google Business Profile 대시보드
관망	llms.txt 파일 생성	필요 없음 (Google이 명시)
관망	콘텐츠 청킹·분할 작업	필요 없음 (Google이 명시)
관망	AI 전용 schema.org 마크업 추가	필요 없음 (Google이 명시)

가이드가 "불필요하다"고 명시한 항목에 시간을 쓰지 않는 것 자체가 실행이다.

6. 통념 파괴: llms.txt·청킹·AI 마크업이 필요 없는 이유

Google이 공식으로 부정한 네 가지

가이드는 AI 검색에 필요하지 않다고 명시한 항목을 직접 열거한다. (Google AI 최적화 가이드)

항목	가이드의 공식 입장
llms.txt 파일	"생성형 AI 검색에 노출되기 위해 새 기계 가독 파일, AI 텍스트 파일, 마크업, 마크다운을 만들 필요 없다"
콘텐츠 청킹	"AI가 더 잘 이해하도록 콘텐츠를 작은 조각으로 쪼갤 필요 없다"
AI 전용 글쓰기 스타일	"생성형 AI 검색을 위해 특정 방식으로 글을 쓸 필요 없다"
구조화 데이터 과의존	"생성형 AI 검색에 구조화 데이터가 필수가 아니며, 추가해야 할 특별한 schema.org 마크업도 없다"

네 가지 모두 "하지 않아도 된다"는 공식 선언이다. 마케팅 업계에서 'AI SEO 필수'로 포장해 팔리던 기법들이 공식으로 부정된 셈이다.

John Mueller의 llms.txt 비유

Google의 John Mueller는 Reddit에서 llms.txt에 대해 더 직접적으로 말했다.

"원본 콘텐츠(와 구조화 데이터)가 이미 다운로드된 상태에서 그 마크다운 파일을 왜 쓰겠느냐, 신뢰하기에는 너무 조작 가능해서 어떤 검색엔진도 쓰지 않게 된 키워드 메타 태그와 매우 유사하다." (Search Engine Journal)

이미 크롤링한 콘텐츠를 마크다운으로 재요약한 파일을 따로 신뢰할 이유가 없다는 논리다. llms.txt는 키워드 메타 태그처럼, 한때 유행하다가 조작 가능성 때문에 무시된 기법의 경로를 밟을 가능성이 높다.

llms.txt 논란 — Google의 자기모순?

논란: Google이 llms.txt를 "불필요하다"고 공개적으로 말한 뒤, 자사 Search Central 개발자 문서 포털에 조용히 llms.txt 파일을 업로드했다. Mueller의 반응은 단순히 "hmmn :-/"였고, 이는 Google의 공식 입장을 더욱 모호하게 만들었다. (Omnius)

이 논란을 어떻게 봐야 할까. Google이 llms.txt를 자사 사이트에 올린 것은 "llms.txt를 활용하는 다른 AI 도구들을 위한 배려"로 해석된다. Google 검색이 llms.txt를 사용하지 않더라도, ChatGPT나 Claude 같은 AI 도구들은 이를 참고할 수 있기 때문이다. 즉, "Google Search 최적화 관점에서는 불필요하지만, 다른 AI 생태계를 위해서는 고려할 수 있다"는 게 현재로서 가장 합리적인 해석이다.

구글 검색 노출을 목표로 한다면 가이드의 공식 입장을 따르면 된다. 다른 AI 도구까지 고려한다면 llms.txt는 옵션이지 의무가 아니다.

7. 에이전트 경험 — 웹의 다음 레이어

AI 에이전트가 웹을 '사용'하는 방식

가이드에서 가장 앞을 내다보는 섹션은 Agentic experiences(에이전트 경험)다. AI 에이전트는 사용자를 대신해 예약, 상품 비교 등의 작업을 수행하는 자율 시스템이다. (Google AI 최적화 가이드)

브라우저 에이전트가 웹사이트에 접근하는 방식이 인간 사용자와 다르다는 점이 중요하다. 브라우저 에이전트는 스크린샷 분석, DOM 구조 검사, 접근성 트리(accessibility tree) 해석 방식으로 페이지를 이해한다. (Google AI 최적화 가이드) 쉽게 말해, AI 에이전트는 눈으로 보기도 하고, 코드 구조를 읽기도 하고, 스크린리더처럼 접근성 정보를 파싱하기도 한다.

이 세 가지 방식 모두에서 잘 동작하는 사이트가 에이전트 시대에 유리하다. 그리고 접근성 최적화의 의미가 달라진다. 장애인 사용자를 위한 배려였던 게, AI 에이전트가 사이트를 정확히 읽어내기 위한 조건으로도 바뀌는 것이다.

Universal Commerce Protocol(UCP) — 커머스 에이전트의 공통 언어

Google은 UCP(Universal Commerce Protocol)를 2026년 1월에 발표했다. AI 에이전트가 쇼핑 전체 여정에 걸쳐 더 많은 작업을 할 수 있도록 지원하는 개방형 표준 프로토콜이다.

현재는 초기 단계다. 그러나 방향은 명확하다:

AI 에이전트가 검색만 하는 것이 아니라 웹에서 직접 거래와 예약을 처리하는 시대가 온다.

이커머스 운영자라면 Merchant Center와 Business Profile을 최신 상태로 유지하는 것이 에이전트 커머스 시대의 가장 현실적인 준비다.

AEO — 에이전트가 '사용할 수 있는' 콘텐츠

Search Engine Land는 이 가이드가 "에이전트 엔진 최적화(AEO)"의 방향을 제시한다고 해설했다. Google Cloud AI Engineering Director인 Addy Osmani는 AEO를 "AI 에이전트가 단순히 렌더링하는 것이 아니라 사용할 수 있도록 기술 콘텐츠를 구조화하고 제공하는 실천"으로 정의했다.

'렌더링(rendering)'과 '사용(use)'의 차이가 핵심이다. 지금까지 SEO는 검색엔진이 콘텐츠를 찾아 보여주는 것에 집중했다. 에이전트 시대는 다르다. AI가 "강남 맛집 예약해줘"라는 요청을 받으면, 검색 결과를 보여주는 데서 끝나지 않고 직접 예약까지 처리한다. 내 사이트의 콘텐츠를 AI가 그런 작업에 활용할 수 있는지가 새로운 기준이 된다.

내 블로그에 직접 대입해보니

이 가이드를 내 블로그(goddaehee.tistory.com)에 직접 대입해봤다.

결론부터 말하면, 손볼 게 몇군데 있다. alt text 누락이 많다. (정말 귀찮다 ㅠㅠ). 그리고 H1 → H3으로 건너뛰는 헤딩 구조가 있었다. llms.txt나 AI 전용 마크업 같은 것보다 이쪽을 손보는게 먼저일 것 이다.

Search Console에서 AI Overview 인용 여부를 확인하는 공식 방법이 있긴 하다.

실적 리포트의 "+ 필터 추가" → 검색 결과 유형 → "AI 개요"를 선택하면 AI Overview에 등장한 쿼리와 노출수를 볼 수 있다.

하지만 2026년 5월 기준 이 필터는 아직 모든 계정에 제공되지 않는 것 같다 — goddaehee.com 독립 도메인 포함 여러 속성에서 확인해봤지만 필터 자체가 나타나지 않았다.

구글이 전체 롤아웃을 완료하지 않은 것 같은데 이 내용도 추적 갱신해야겠다.

현재로선 타겟 쿼리를 시크릿 창에서 직접 검색해 AI Overview 박스에 내 URL이 인용됐는지 확인하는 것이 가장 실용적인 방법이다.

한 가지 테스트한 사실이 있다.

"codex 설치" 쿼리에서 내 블로그가 오가닉 2위에 랭크됐는데도 AI Overview에는 인용되지 않았다.

검색 순위 상위 = AI Overview 인용이 아니라는 것을 데이터로 직접 봤다.

AI Overview는 별도의 콘텐츠 선정 기준을 갖고 있고, Google 가이드가 말하는 "비상품형 고유 인사이트"가 그 기준에 더 가깝게 맞아야 한다는 의미가 아닐까?

이 글 자체가 비상품형 콘텐츠 기준을 충족하는지도 솔직히 모른다.

다만 가이드의 핵심 — "좋은 콘텐츠와 건강한 기술 구조" — 은 새로운 얘기가 아니어서, 기존에 해오던 방향이 크게 틀리지 않았다는 방향, 나의 경우에도 SEO의 기본부터 충실하자는 입장이었는데 이런 방향성에 대한 확인이 된 것 같아 좋았다.

8. 결론: 지금 무엇을 해야 하는가

Google AIO 가이드가 확인한 것은 하나다:

AI 검색 시대에도 좋은 콘텐츠와 건강한 기술 구조가 기본이다. AEO·GEO라는 새 약어는 SEO를 재포장한 것에 불과하고, llms.txt·콘텐츠 청킹·AI 전용 마크업은 Google 검색 기준으로 시간 낭비다.

단, 에이전트 경험 섹션은 다르다. 이것은 현재가 아니라 미래를 말한다. 브라우저 에이전트가 스크린샷·DOM·접근성 트리로 웹을 탐색하고, UCP 같은 프로토콜로 구매까지 처리하는 시대가 오면, 기술 구조의 의미가 달라진다. 접근성은 보너스가 아니라 에이전트 호환성의 기준이 된다.

지금 즉시 해야 할 것

비상품형, 독자적 인사이트가 담긴 콘텐츠를 만든다
Search Console 오류를 해결하고 크롤링 환경을 정비한다
JavaScript 렌더링 차단 여부를 확인한다

중단해야 할 것

llms.txt 제작, 콘텐츠 청킹, AI 전용 마크업에 투자한다
AEO·GEO라는 이름의 'AI SEO' 서비스에 비용을 쓴다
브랜드 언급을 인위적으로 조작하려 한다

관심 갖고 지켜볼 것

접근성(accessibility) 최적화 — 에이전트 시대의 기술 구조 기반
UCP(Universal Commerce Protocol) — 이커머스 에이전트 시대의 공통 언어
Business Agent — AI가 브랜드 대화를 중개하는 경험

공식 가이드 전문은 Google AI 최적화 가이드에서 확인할 수 있다. AI 검색이 빠르게 진화하고 있으므로, 가이드 업데이트를 주기적으로 확인하는 것이 좋다.

내 블로그·사이트에 적용해볼 것 (AIO 체크리스트)

AI 검색 결과에서 인용될 가능성이 있는 내 글 3개를 뽑아본다 — '비상품형'인지 확인한다 (원본 분석·경험·데이터가 있는가?)
최근 발행 글의 <img> 태그 중 alt text 없는 것을 카운트한다 (목표: 0개)
헤딩 구조를 확인한다 — H1 → H2 → H3 계층이 맞는지, H2 없이 H3으로 건너뛰는 곳은 없는지
AI Overview 인용 여부를 확인한다 — Search Console 실적 리포트의 "AI 개요" 필터는 아직 모든 계정에 제공되지 않는다. 가장 확실한 방법은 타겟 쿼리를 시크릿 창에서 직접 검색해 AI Overview 박스에 내 URL이 뜨는지 확인하는 것이다.
llms.txt, 콘텐츠 청킹, AI 전용 마크업 투자 계획이 있다면 일단 보류한다 — Google 검색 기준으로는 현재 효과 없음

참고자료

작성일: 2026년 5월 18일

분석 대상: Google AI Optimization Guide (2026년 5월 기준)

⚠️ 이 글의 내용은 공식 문서 기반이며, Google 정책 변경에 따라 내용이 달라질 수 있다. 중요한 결정 전에는 최신 Google AI 최적화 가이드를 확인한다.

Codex CLI 입문(8) : 슬래시 명령어 정리 - Codex 슬래시 명령어 사용방법

갓대희 — Mon, 18 May 2026 12:00:27 +0900

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

codex CLI 안에서 /를 누르면 명령이 한꺼번에 쏟아져서 어떤 것부터 익혀야 할지 망설이게 된다.

이번에는 Codex CLI의 슬래시 명령어 들을 정리 해보려 한다.

앞부분은 초보자용 사전, 뒷부분은 기존 글에서 정리해 둔 config.toml 키 사전과 CLI 플래그 사전을 부록으로 작성해보려 한다.

이 글은 2026년 5월 기준 codex-cli 0.130.0 공식 문서(developers.openai.com/codex/cli/slash-commands)와 릴리즈 노트를 바탕으로 작성되었다. 슬래시 명령 목록은 릴리즈마다 추가·제거가 있으므로, 자신의 설치 버전에서 / 입력으로 popup을 띄워 직접 확인하기를 권장한다.

OpenAI Codex 개발자 시리즈

Part 1: CLI 빠른 시작 Part 2: 핵심 개념 4가지 Part 3: Subagents · Workflows Part 4: AGENTS.md · Rules Part 5: MCP · Plugins · Skills Part 6: 자동화 Part 7: 마이그레이션 (현재 글) Part 8: 슬래시 명령어 정리(예정)

이 편에서 처음 나오는 용어 미리 보기

슬래시 명령(slash command): Codex TUI에서 /로 시작하는 인터랙티브 명령. 채팅 메시지가 아니라 TUI 동작을 직접 제어한다.
popup: /를 입력하면 composer 위에 뜨는 명령 자동완성 창. 화살표로 선택, Tab으로 큐잉, Enter로 즉시 실행한다.
큐잉(queueing): 현재 턴이 끝나기 전에 다음 명령을 미리 등록해 두는 동작. Codex가 응답 중에 /clear 같은 명령을 미리 예약할 때 쓴다.
feature 플래그(게이트): 일부 명령은 [features] 테이블의 특정 키가 켜져 있어야만 동작한다. 사용 전에 게이트 조건을 함께 확인한다.
[공식 문서 미등재]: 소스 코드나 릴리즈 노트에서만 확인되고 공식 slash-commands 페이지에 올라오지 않은 명령. 동작·인터페이스가 버전마다 다를 수 있다.

슬래시 명령 기본기 — popup·큐잉·별칭
세션 관리 (8개): /new, /resume, /fork, /side, /clear, /compact, /exit, /logout
모델·승인·권한 (5개): /model, /fast, /permissions, /sandbox-add-read-dir, /experimental
도구·맥락 (5개): /mention, /mcp, /plugins, /apps, /agent
코드 작업 (4개): /init, /diff, /review, /plan
진단·디버그 (4개): /status, /debug-config, /feedback, /copy
UI·UX·테마 (4개): /theme, /title, /statusline, /keymap
게이트·조건부 명령 (4개): /goal, /personality, /ps, /stop
공식 미등재 명령 (8개): /rename, /raw, /skills, /approve, /realtime, /settings, /collab, /setup-default-sandbox
부록 A — config.toml 키 사전
부록 B — CLI 플래그·codex exec 사전
마무리 — 안전 기본값 + 캡쳐 체크리스트

1. 슬래시 명령 기본기

명령 목록을 보기 전에, TUI에서 어떻게 명령을 불러서 실행하는지 흐름부터 잡아두자. 크게 세 단계다.

1.1 popup 띄우고 명령 고르기

composer(메시지 입력란)에서 /를 입력하면 명령 popup이 열린다. 키워드 일부를 더 치면 목록이 좁혀지고, 화살표로 골라 Enter로 즉시 실행하거나 Tab으로 예약할 수 있다.

# composer에서
    /mod      ← '/'로 popup, 'mod' 입력 시 /model이 위로 올라옴
    ↑/↓       ← 화살표로 항목 이동
    Enter     ← 즉시 실행

활용 주제 전환 시 이전 맥락 끊고 새로 시작.

/resume — 이전 세션 이어 받기

picker가 열려 최근 세션 목록을 보여준다. 어제 작업하다 만 세션을 그대로 이어가고 싶을 때 사용한다.

CLI에서 codex resume --last로 한 단계 건너뛰는 방법도 있다.

/resume

활용 중단된 작업 이어서 컨텍스트 복구.

ex)

/fork — 현재 스레드 분기

현재 대화 기록이 정상적으로 저장된 상태라면, 현재 스레드를 새 분기로 복제한다. 본 흐름을 망가뜨리지 않고 "이 부분을 다르게 가면 어떻게 될까?"를 시험해볼 때 유용하다. 다만 앱 서버가 대상 스레드의 rollout 기록을 찾지 못하면 no rollout found for thread id 같은 오류가 날 수 있다. 이 경우 명령 부재가 아니라 로컬 세션 인덱스/앱 서버 상태 문제로 보는 편이 맞다.

/fork

활용 기존 맥락을 보존한 채 분기 실험. 실패하면 터미널에서 codex fork --last 또는 codex fork <SESSION_ID>로 확인.

/side — 보조 대화 열기

메인 스레드를 그대로 둔 채 별도의 보조 창을 띄운다. "이 함수 의미만 잠깐 물어보고 싶다" 같은 곁가지 질문을 메인 흐름에 흘리지 않는 용도다. ESC로 닫으면 메인 스레드로 돌아간다.

/side

활용 메인 흐름 건드리지 않고 버그 원인 가설 검증(로그 추가, 임시 패치)에 유용. 본선 컨텍스트 오염 방지 목적.

ex) 진행 중 /side

- 보조 대화창 열림

- esc를 통해 해당 보조 대화창을 종료 하면 기존 대화창으로 복귀 된다.

/clear — 화면 초기화

같은 스레드를 유지한 채 터미널 화면과 대화 컨텍스트를 정리한다. 화면이 너무 길어져 가독성이 떨어지거나 컨텍스트 누적으로 모델이 산만해질 때 사용한다. 새 스레드를 통째로 여는 /new와는 동작 범위가 다르다.

/clear

활용 컨텍스트 누적으로 판단 흔들릴 때 초기화. 초기화 전 TODO·결정사항 3줄 요약을 남기는 습관 권장.

/compact — 대화 축약

긴 대화를 요약해서 압축한다. AI 모델은 한 번에 기억할 수 있는 대화 길이(컨텍스트 윈도우)에 한계가 있는데, 대화가 너무 길어지면 응답이 느려지거나 앞 내용을 놓치기 시작한다. 그럴 때 이 명령으로 핵심만 남기면 된다. 압축된 요약은 새 메시지 형태로 들어가고, 원본 대화는 백그라운드에 보존된다.

/compact

활용 긴 대화 토큰 줄여 핵심만 남길 때.

ex)

/exit · /quit — 세션 종료

두 명령은 완전히 동일하다(공식 docs에서 alias로 명시). 작업을 마치고 TUI를 닫을 때 쓴다. 키보드 단축키 Ctrl+C와 달리 정상 종료 경로를 타므로 세션 메타데이터가 깔끔하게 저장된다.

/exit
    # 또는
    /quit

활용 현재 세션 작업 마감하고 종료. 종료 전 /diff·미커밋 여부 확인 후 실행("끝냈다" 착각 방지).

/logout — 로그아웃

저장된 인증 자격을 모두 제거한다. 다른 계정으로 전환하거나 공용 노트북에서 흔적을 지워야 할 때 사용한다. 재로그인은 codex login으로 다시 시작한다.

/logout

활용 계정 전환·보안 정리 위해 인증 해제.

3. 모델·승인·권한 (5개)

Codex가 어느 수준까지 자율로 움직일지를 제어하는 명령들이다.

처음엔 기본값이 낯설 수 있는데, 각 명령이 뭘 하는지 한 번만 파악해두면 의도치 않은 동작을 방지하는 데 도움이 된다.

/model — 모델 선택

사용할 AI 모델을 picker로 고른다. 가벼운 질문은 작은 모델로, 깊은 분석이 필요할 땐 큰 모델로 그때그때 전환할 수 있다. 버전에 따라 같은 화면에서 추론 강도(reasoning effort, 얼마나 깊이 생각할지)까지 함께 조정할 수 있다.

/model

활용 작업 난도에 맞춰 모델 성향 교체.

ex)

/fast — 빠른 응답 모드 토글

빠른 응답을 우선하는 모드를 켜고 끈다. 코드 탐색이나 간단한 질문처럼 답의 정밀도보다 빠른 피드백이 더 중요한 상황에서 유용하다. 복잡한 분석이나 코드 수정처럼 깊은 추론이 필요한 작업에서는 다시 끄는 것을 권장한다.

/fast

활용 아이디어 발산·로그 훑기 초반 탐색에 좋음. 최종 수정안·릴리즈 판단 전에는 해제 권장.

/permissions — 승인 정책·샌드박스 보기/변경

현재 승인 정책(approval policy)과 샌드박스 수준을 한 화면에서 확인하고 바꾼다. 위험한 작업 전에 가장 먼저 들여다봐야 할 명령이다. 공식 docs에서 /approvals가 popup에서 사라졌다고 명시했으므로 신규 사용자는 이쪽을 외운다.

/permissions

활용 실행 권한 경계 먼저 확인.

ex)

/sandbox-add-read-dir — 읽기 가능 경로 추가 (Windows)

공식 docs에서 Windows 전용이라고 명시된 명령이다. 워크스페이스 바깥의 디렉터리를 한시적으로 읽기 허용 목록에 추가한다. macOS/Linux 사용자는 동일한 효과를 --add-dir CLI 플래그(부록 B)로 처리한다.

/sandbox-add-read-dir

활용 참조 폴더 읽기 범위 확장 필요.

/experimental — 실험 기능 토글 메뉴

메모리·목표·터미널 리플로우 같은 실험 기능을 그 자리에서 켜고 끄는 토글 메뉴를 연다. config.toml을 직접 손대지 않고 즉시 반영된다. 토글 가능한 항목 표는 섹션 8에서 자세히 다룬다.

/experimental

활용 개인 브랜치에서 A/B 테스트 후 채택 판단. 팀 표준 브랜치에서는 비권장.

ex) Goals 같은 기능은 현재 아직 실험적 단계이다.

4. 도구·맥락 (5개)

에이전트가 쓸 수 있는 도구와 맥락을 관리하는 명령들이다. Codex가 갑자기 모르는 답을 내거나 도구가 안 보일 때 가장 먼저 들여다본다.

/mention — 컨텍스트 참조 삽입

파일·앱·플러그인 등 특정 컨텍스트 항목을 메시지에 정확히 박는다. @ 자동완성과 유사하지만, popup 기반이라 모르는 이름을 검색해서 고를 수 있어 초보자에게 더 친화적이다.

/mention

활용 특정 리소스·앱 컨텍스트를 정확히 지목.

/mcp — MCP 서버 상태 보기

연결된 MCP(Model Context Protocol) 서버 목록과 각 서버에서 노출되는 도구 정보를 본다. 도구가 작동 안 할 때 가장 먼저 의심해야 하는 지점이 MCP 연결 상태다.

/mcp

활용 도구 서버 연결 상태·기능 범위 확인. 인증 만료·스키마 불일치·권한 부족을 먼저 분리 진단.

ex)

/plugins — 플러그인 마켓·설치 관리

설치된 플러그인과 마켓플레이스에서 찾을 수 있는 플러그인을 탐색한다.

v0.128.0에서 마켓 설치 워크플로가 정식 추가됐다(v0.128.0 릴리즈 노트).

/plugins

활용 플러그인 가용성·작업 적합성 먼저 판단.

ex)

/apps — 앱·커넥터 탐색

외부 앱·커넥터를 프롬프트에 끌어다 쓰는 워크플로다. 채팅 결과를 바로 출력하는 명령이 아니라 전체 화면 앱 선택기를 열고, 앱을 고르면 composer에 $app-slug 형태로 삽입한다. 현재 버전에서는 apps 기능이 기본 활성화된 환경도 있으므로, 아무 출력이 없어 보이면 Enter로 선택기가 열리는지 먼저 확인한다.

/apps

활용 외부 서비스 연동 작업 흐름 점검. 앱을 선택한 뒤 프롬프트에 삽입된 mention과 연결 계정이 올바른지 확인.

ex)

/agent — 에이전트 스레드 선택

이미 생성된 메인 스레드와 서브에이전트 스레드 사이를 전환하거나 관찰하는 명령이다. 새 서브에이전트를 직접 호출하는 명령은 아니며, 서브에이전트가 생성된 뒤 해당 작업 흐름을 확인하거나 이어갈 때 사용한다.
현재 서브에이전트가 없으면 Main [default]만 표시될 수 있다.

/agent

활용 병렬 조사·구현 중 어느 에이전트가 작업 중인지 확인하고, 필요한 스레드로 전환할 때 사용.

ex)

5. 코드 작업 (4개)

코드 파일을 실제로 읽고 수정하는 명령들이다. 직접 코드에 손을 대는 만큼, 실행 전에 섹션 12의 안전 기본값을 한 번 확인해두는 것이 좋다.

/init — AGENTS.md 초기화

저장소 루트에 AGENTS.md를 만들거나 보강한다. Codex가 매 세션 자동으로 읽는 파일이라 프로젝트 규칙을 한 번만 적어 두면 다음부터 반복 설명할 필요가 없다. Part 5에서 AGENTS.md 작성법을 다룬다.

/init

활용 저장소 규칙·환경 맥락을 시작점에 주입.

/diff — 변경 사항 미리 보기

현재 워킹 트리의 변경 내역을 시각화해서 보여준다. Codex가 방금 만든 변경이 의도와 일치하는지 검증할 때 가장 자주 누르게 되는 명령이다. 큰 변경은 화살표·페이지 키로 스크롤한다.

/diff

활용 수정 전후 변경 의도 빠르게 검증.

/review — 코드 리뷰 모드

현재 변경 또는 지정한 베이스 브랜치/커밋을 대상으로 코드 리뷰 흐름을 시작한다. 머지 직전 회귀·품질 리스크를 한 번 더 훑을 때 쓴다. CLI에서 codex review 서브커맨드로도 진입 가능하다.

/review

활용 병합 전 회귀·품질 리스크 집중 점검. 보안·성능·회귀·테스트 누락 등 관점을 명시하면 효과 상승.

ex) 1. Review against a base branch (PR Style)

- 소스리뷰 base branch를 선택 하는 화면

ex) Review a commit

- 특정 커밋에 대한 리뷰

/plan — 계획 모드

바로 코드를 고치는 대신 단계별 실행 계획을 먼저 짠다. 복잡한 변경에서 충돌·범위를 미리 식별할 수 있어 안전하다. 계획에 동의해야 다음 단계로 넘어간다.

/plan

활용 구현 전 단계·리스크를 구조화.

ex) shift + tab 으로 모드를 변경 가능하며 계획을 먼저 세우게 된다. (너무 간단한 내용은 바로 수행하기도 한다.)

- 계획을 세워주며

- 해당 계획대로 수행할지, 쌓여있는 context를 비우고 수행할지, 플랜모드를 통해 계속 계획모드를 개선할지 등 선택 가능하다.

6. 진단·디버그 (4개)

"왜 안 되지?"가 들 때 가장 먼저 누르는 명령들이다. 보통 이 카테고리에서 답이 거의 다 나온다.

/status — 현재 세션 상태 한눈에 보기

모델, 승인 정책, 샌드박스, 연결된 MCP 수, 토큰 사용량 같은 핵심 상태를 한 화면에 정리한다. 다른 사람과 환경을 비교하거나 이슈 리포트 쓸 때 첫 줄에 붙이기 좋은 자료다.

/status

활용 현재 모드·제약·연결 상태 빠르게 확인.

/debug-config — 설정 레이어 진단

전역·프로젝트·CLI 플래그가 어떻게 병합되어 현재 설정이 만들어졌는지 보여준다. "내 config.toml이 제대로 읽히고 있나?" 의심이 들면 가장 먼저 누른다. feature 플래그가 안 먹는 문제는 거의 다 여기서 답이 나온다.

/debug-config

활용 설정 파일·프로필·환경변수 우선순위 충돌 확인. 오작동 원인 분리 진단 첫 번째 수단.

/feedback — 로그와 함께 피드백 보내기

현재 세션 로그를 첨부해 Codex 팀에 의견·버그 리포트를 전송한다. 재현 단계를 직접 정리하지 않아도 로그가 자동 동봉되므로 작은 이상도 가볍게 보낼 수 있다.

/feedback

활용 사용성 불편·버그 체감 즉시 전달. 재현 단계(명령→기대결과→실제결과)를 포함해야 처리 속도 빠름.

/copy — 마지막 출력 클립보드 복사

방금 받은 마지막 응답을 클립보드로 옮긴다. v0.129.0에서 tmux passthrough 없이도 동작하도록 버그가 수정됐다(v0.129.0 릴리즈 노트). 결과를 다른 문서로 옮기기 직전에 가장 가볍게 쓰는 명령이다.

/copy

활용 PR 템플릿·위키·이슈 본문으로 이동할 때 유용. 코드블록·링크 형식 깨짐 여부 붙여넣기 후 점검.

7. UI·UX·테마 (4개)

TUI의 외관과 입력 환경을 손에 맞게 다듬는 명령들이다. 한 번 정한 뒤에는 잘 안 건드리지만, 처음에 맞춰 두면 장시간 작업 피로가 크게 줄어든다.

/theme — 구문 강조 테마 선택

코드 블록의 구문 강조 테마를 picker로 고른다. 터미널 배경이 어두운지 밝은지에 따라 가독성이 크게 달라지므로 OS 다크모드 전환 시 같이 바꾸는 것이 자연스럽다.

/theme

활용 장시간 작업 피로 줄이려 UI 대비 조정.

/title — 터미널 창 제목 설정

터미널 창 또는 탭 제목을 설정한다. v0.128.0에서 활성 턴 중에도 편집할 수 있게 개선됐다. 여러 프로젝트 세션을 동시에 열어 둘 때 창 구분에 가장 유용하다.

/title

활용 세션 목적이 드러나게 작업 제목 정리. "레포-브랜치-목표" 패턴(예: api-fix/1234-auth-timeout)으로 통일하면 검색·회고에 유리.

/statusline — 상태 표시줄 구성 (v0.128.0~)

TUI 하단 상태 표시줄에 표시할 항목을 대화형으로 고른다. v0.129.0에서 테마 색상 추적과 PR 요약 세그먼트가 추가됐다. 브랜치명·작업 상태가 늘 눈에 띄게 둘 때 컨텍스트 상실이 줄어든다.

/statusline

활용 상태바 정보 밀도·표시 항목 튜닝. 승인 정책·샌드박스·모델명을 우선 노출하도록 설정하면 실수 예방.

/keymap — 단축키 재매핑 (v0.128.0~)

TUI 키보드 단축키를 대화형으로 다시 잡는다. [tui.keymap.*] config 키와 동기화되며, TUI에서 즉시 변경하거나 config.toml에 영구 저장할 수 있다(부록 A 참고).

/keymap

활용 단축키 동작이 손에 안 맞을 때 조정. IDE 공통 단축키와 충돌 최소화 기준으로 설정 권장.

8. 게이트·조건부 명령 (4개)

이 명령들은 특정 기능 스위치(feature 플래그)가 켜져 있어야만 popup에 표시된다. "왜 내 화면엔 이 명령이 없지?"라는 의문이 든다면, 명령이 없는 게 아니라 게이트 조건이 닫혀 있는 것이다. 각 명령 옆에 어떤 조건이 필요한지 함께 표기해뒀다.

/goal — 세션 목표 설정 [게이트: features.goals = true]

긴 작업의 목표를 명시적으로 박아 두면 Codex가 응답마다 목표 정합성을 따져준다. /experimental에서 켜거나 config.toml에 직접 적는다. 설정·일시정지·재개·초기화를 모두 지원한다.

/goal "feature X 구현 끝내고 회귀 없도록 머지"

활용 장기 작업 목표·진행 기준 명확히 고정.

ex) 현재 정식 기능은 아닌고 실험적 기능이며 하기 글에 자세하게 리뷰해 두었다.

Codex CLI /goal 사용방법 : 목표를 기억하고 스스로 이어가는 자율 루프 - /goal과 Ralph Loop 비교

/personality — 응답 톤 선택 [모델 의존]

응답 톤을 friendly·pragmatic·none 중에서 고른다.

config.toml 최상위 personality 키와 연동된다.

사용 중인 모델이 personality를 지원하지 않으면 popup에서 숨겨질 수 있다.

/personality

활용 답변 톤을 팀 규칙에 맞춰 고정. 리뷰 기준(근거 중심, 라인 인용 필수)도 함께 고정하면 실무 일관성 향상.

ex)

/ps — 백그라운드 터미널 목록 [게이트: features.unified_exec = true]

에이전트가 띄워 둔 백그라운드 셸 프로세스를 보여준다. 빌드·서버처럼 길게 도는 작업이 어떤 상태인지 한눈에 본다. unified_exec 플래그가 켜져 있어야 활성화된다.

/ps

활용 백그라운드 에이전트 상태 추적.

ex)

/stop — 백그라운드 터미널 중지

백그라운드에서 돌고 있는 터미널을 일괄 중지한다. 빌드가 폭주하거나 무한 루프에 빠진 프로세스를 한 번에 정리할 때 쓴다. /ps와 마찬가지로 features.unified_exec이 켜진 환경에서 의미를 갖는다.

/stop

활용 비용 급증·잘못된 대량 수정 조짐 시 즉시 중단하는 안전 스위치. 망설이지 말고 먼저 멈출 것.

9. 공식 미등재 명령 (8개)

⚠️ 공식 문서 미등재 항목

이 섹션의 명령들은 소스 코드(codex-rs/tui/src/slash_command.rs)나 릴리즈 노트에서 확인됐으나 공식 slash-commands 페이지에는 등재되어 있지 않다.
동작과 인터페이스는 버전마다 달라질 수 있으므로 자신의 설치 버전에서 /debug-config로 먼저 확인하기를 권장한다.

/rename — 스레드 이름 변경 [공식 문서 미등재]

현재 TUI 스레드의 이름을 변경한다. 여러 스레드를 동시에 운영할 때 각 스레드를 프로젝트명이나 작업 목적에 맞춰 구분하는 데 유용하다. 소스 코드 enum에서만 확인됐다.

/rename

활용 세션 이름을 이력 검색 친화적으로 바꿀 때.

/raw — 원시 스크롤백 토글 [공식 문서 미등재] (v0.129.0~)

스크롤백 렌더링을 원시(raw) 텍스트와 서식 적용 사이에서 토글한다. v0.129.0 릴리즈 노트에서 확인됐다. ANSI 코드가 섞여 출력이 깨질 때 한 번 눌러보면 원인을 가린다.

/raw

활용 로그·JSON·에러 원문 전달 시 유용. 민감 정보 마스킹 후 전송하는 원칙 준수.

/skills — 설치된 스킬 보기 [공식 문서 미등재]

설치된 스킬 목록을 TUI에서 탐색한다. Part 6에서 스킬 config 설정을 다루었지만 슬래시 명령 자체는 공식 docs에 없다. 스킬이 제대로 로드됐는지 빠르게 확인할 때 시도해본다.

/skills

활용 사용 가능 스킬 목록 확인 후 전략 짤 때.

/approve — 자동 리뷰 승인 [공식 문서 미등재] (v0.129.0~)

v0.129.0에서 구 /autoreview가 이 이름으로 바뀌었고 동시에 /approvals가 popup에서 빠졌다. 자동 리뷰 재시도 흐름을 명시 승인할 때 사용한다.

/approve

활용 보안 경계 넘는 실행을 명시 승인. 명령 목적·영향 파일·롤백 가능성을 체크한 뒤 승인.

/realtime — 실시간 음성 모드 [공식 문서 미등재]

오디오 디바이스와 실시간 음성 입력 관련 실험 기능이다. 하드웨어 의존이 커서 이 글에서는 핸즈온을 다루지 않는다. 자신의 환경에서 feature 플래그를 켠 뒤 직접 확인하기를 권장한다.

/realtime

활용 디버깅 대화형 탐색에 적합. 장문 생성보다 빠른 피드백 루프가 필요한 탐색 초반에 유용.

/settings — 기본 동작 일괄 조정 [공식 문서 미등재]

선호 옵션을 한 화면에서 묶어 조정하는 진입점이다. 소스 코드에서만 확인되고 공식 docs에는 없다. 동작 범위가 버전에 따라 다를 수 있으므로 적용 후 /debug-config로 결과를 확인한다.

/settings

활용 팀 공통 프로필(모델·승인정책·출력 스타일)을 템플릿화해 신규 멤버 온보딩에 활용 가능.

/collab — 협업 모드 [공식 문서 미등재]

collaboration_modes_enabled 플래그로 게이트된 명령이다. UX 문서가 없어 동작 세부는 직접 확인이 필요하다. 새 키 후보는 multi_agent로 옮겨질 가능성이 있다(부록 A 마이그레이션 표 참고).

/collab

활용 협업 세션에서 역할 분담·동기화. 파일 오너십을 먼저 나눠 역할 충돌을 방지할 것.

/setup-default-sandbox — 기본 샌드박스 상승 [공식 문서 미등재]

⚠️ 보안 경고

이 명령은 allow_elevate_sandbox 플래그로 게이트되어 있으며, 실행하면 기본 샌드박스 수준이 상승한다. Codex가 더 넓은 파일시스템·네트워크 범위에 접근할 수 있게 된다는 의미다. 소스 코드에서만 확인됐고 공식 docs 미등재다. 대부분의 개발자에게 필요한 상황은 드물다. 꼭 필요한 경우가 아니라면 기본 sandbox_mode를 유지하는 것을 권장한다.

/setup-default-sandbox

활용 반복 작업용 기본 샌드박스 정책 고정.

10. 부록 A — config.toml 키 사전

슬래시 명령으로 잠깐 토글한 항목을 영구 적용할 때, 또는 팀 전체가 같은 기본값을 공유할 때 config.toml을 편집한다. 공식 config-basic 문서에 등재된 키 중 Part 1~9에서 다루지 않았거나 자주 묻는 것들을 모았다.

A.1 [tui.keymap.*] — TUI 키맵 재정의 (v0.128.0~)

[tui.keymap.global]은 전체 TUI 단축키, [tui.keymap.composer]는 composer 특화 단축키를 재정의한다. /keymap으로 임시 변경, config.toml로 영구 저장한다.

# config.toml — TUI 키맵 재정의 (v0.128.0~)
    [tui.keymap.global]
    open_transcript = "ctrl-t"
    
    [tui.keymap.composer]
    submit = ["enter", "ctrl-m"]

한글로 이해하기
submit = ["enter", "ctrl-m"]은 Enter와 Ctrl+M 어느 쪽을 눌러도 메시지가 전송된다는 뜻이다. 배열로 여러 키를 동시에 바인딩한다.

A.2 personality · log_dir · animations · web_search

# config.toml — 자주 묻는 최상위 키
    personality = "pragmatic"       # friendly | pragmatic | none
    log_dir = "/tmp/codex-logs"     # 로그 위치 재정의 (CI·디버깅)
    animations = false              # TUI 애니메이션 비활성화 (v0.129.0~)
    web_search = "cached"           # cached | live | disabled

animations = false는 v0.129.0에서 추가된 접근성 옵션이다. 스크린 리더 사용이나 저사양 터미널에서 유용하다. web_search는 기존 두 개의 [features] 하위 키(web_search_request, web_search_cached)를 단일 최상위 키로 통합한 것이다.

A.3 [features] 테이블

# config.toml — [features] 테이블 자주 쓰는 키
    [features]
    undo            = true    # 턴별 git 스냅샷
    memories        = true    # 메모리 저장소 (v0.129.0~ Memories MCP v1)
    shell_snapshot  = true    # 셸 상태 스냅샷
    unified_exec    = true    # 백그라운드 터미널 — /ps, /stop 활성화
    apps            = true    # 앱·커넥터. 기본 ON인 버전도 있으므로 필요 시에만 명시
    goals           = true    # /goal 활성화
    terminal_resize_reflow = true   # 터미널 크기 변경 시 스크롤백 재구성 (기본 ON)
    prevent_idle_sleep     = false  # 장시간 작업 절전 방지 (macOS/Windows)
    
    # ⚠️ EXPERIMENTAL — 공유 저장소에서 활성화 금지
    codex_git_commit = false  # Codex가 git 커밋 자동 작성 (v0.129.0~)

⚠️ codex_git_commit 활성화 전 확인

Codex가 직접 git 커밋을 작성하는 실험 기능이다. 공유 저장소에서는 활성화하지 않는 것을 강력히 권장한다. 자동 생성된 커밋이 의도하지 않은 변경을 남길 수 있다. 개인 저장소에서 켜더라도 push 직전 git log --oneline -5로 검토하는 루틴을 더해 두면 안전하다.

A.4 [shell_environment_policy] — 환경 변수 화이트리스트

# config.toml — 셸에 전달할 환경 변수만 화이트리스트
    [shell_environment_policy]
    include_only = ["PATH", "HOME", "LANG", "TERM"]
    # OPENAI_API_KEY 등 민감 변수는 이 목록 밖으로 격리된다

보안이 중요한 공유 환경이나 CI에서는 적극 활용한다. 허용 범위를 좁힐수록 의도치 않은 정보 노출 표면이 줄어든다.

A.5 [hooks] managed_dir — 엔터프라이즈 훅 경로

# config.toml — 엔터프라이즈 훅 경로
    [hooks]
    managed_dir = "/enterprise/hooks"
    windows_managed_dir = 'C:\enterprise\hooks'
    
    [[hooks.PreToolUse]]
    matcher = "^Bash$"
    
    [[hooks.PreToolUse.hooks]]
    type    = "command"
    command = "python3 /enterprise/hooks/pre_tool_use_policy.py"

Codex가 managed_dir 안의 스크립트를 직접 배포하지 않는다. 스크립트 설치·업데이트는 조직의 엔터프라이즈 툴링이 담당해야 한다. 훅 이벤트는 PreToolUse, PostToolUse, UserPromptSubmit, Stop, SessionStart, PermissionRequest 여섯 가지다(hooks 공식 문서).

A.6 [agents] · MCP 키 모음

[agents] job_max_runtime_seconds는 배치 작업 타임아웃을, interrupt_message는 인터럽트 안내 문구를 설정한다(v0.128.0~). MCP 쪽에서는 mcp_servers.<name>.experimental_environment = "remote"로 원격 실행기를 지정하고, mcp_oauth_callback_port·mcp_oauth_callback_url로 headless 환경의 OAuth 콜백을 고정한다(MCP 공식 문서).

A.7 옛 키 → 새 키 마이그레이션 치트시트

옛 키 (레거시)	새 키	비고
`connectors`	`apps`	[features] 하위
`codex_hooks`	`hooks`	최상위 섹션
`memory_tool`	`memories`	[features] 하위, v0.129.0 Memories MCP v1
`web_search_request` / `web_search_cached`	`web_search`	최상위 통합 키 (cached / live / disabled)
`collab`	`multi_agent`	[UNVERIFIED] 소스 코드 확인, 공식 문서 미등재
`telepathy`	`chronicle`	[UNVERIFIED] 소스 코드 확인, 공식 문서 미등재

Deprecated 플래그

소스 코드에서 deprecated로 표시된 키: web_search_request, web_search_cached, use_legacy_landlock. CLI 플래그 --full-auto도 v0.128.0에서 deprecated됐다. 명시적 권한 프로파일과 신뢰 흐름 설정(approval_policy + sandbox_mode)으로 대체한다.

11. 부록 B — CLI 플래그·codex exec 사전

B.1 자주 쓰는 CLI 플래그

플래그	설명	주요 용도
`--cd / -C <path>`	작업 디렉터리 변경	모노레포 서브 패키지 지정
`--profile / -p <name>`	[profiles.<name>] config 로드	CI 환경별 설정 분리
`--enable / --disable <feature>`	단일 실행에 한해 feature 토글	config.toml 안 건드리고 테스트
`--image / -i`	이미지 첨부	스크린샷 분석, UI 버그 설명
`--no-alt-screen`	대체 스크린 버퍼 비활성화	tmux / cmux 멀티 패널
`--oss`	오픈소스 모드	OSS 기여 컨텍스트
`--search`	웹 검색 활성화	실시간 정보 필요할 때

가장 자주 쓰는 조합은 -C(경로 지정) + -p(프로파일)이고, tmux에서는 --no-alt-screen이 거의 기본 옵션처럼 따라붙는다.

⚠️ CI 인증 키 — CODEX_API_KEY vs OPENAI_API_KEY

Part 2·7의 CI 예시에서 OPENAI_API_KEY를 사용한 부분이 있다. CI 환경에서는 CODEX_API_KEY를 별도로 발급·관리하는 것이 권장된다. 두 키는 서로 다른 인증 경로이며, OPENAI_API_KEY를 그대로 쓰면 권한 범위가 지나치게 넓어질 수 있다.

B.2 codex exec 핵심 플래그

플래그	설명
`--ephemeral`	세션 지속성 비활성화. CI에서 매 실행을 독립적으로
`--ignore-rules`	Rules 파일 무시
`--ignore-user-config`	사용자 전역 config 무시, 프로젝트 config만 사용
`-o / --output-last-message <path>`	마지막 어시스턴트 메시지를 파일로 저장
`--output-schema`	출력 JSON 스키마 지정
`exec resume --last`	마지막 세션을 이어 실행
`exec -`	표준 입력에서 프롬프트 읽기 (파이프라인용)

B.3 파이프라인 예시 — stdin + 파일 출력

# git diff 결과를 Codex에 넘겨 코드 리뷰 요약을 파일로 받는다
    git diff HEAD~1 | codex exec - \
      --ephemeral \
      --ignore-user-config \
      -o /tmp/review-summary.txt \
      --profile ci

한글로 이해하기
exec -는 파이프(|)로 들어온 내용을 프롬프트로 받고, -o로 결과를 파일로 떨군다. --ephemeral까지 합치면 각 CI 실행이 서로 영향을 주지 않는다.

B.4 새 서브커맨드 카탈로그

codex update (v0.128.0~): CLI 업데이트 확인·적용.
codex completion: 셸 자동완성 스크립트 생성. 예: codex completion zsh >> ~/.zshrc.
codex features (v0.129.0~): feature 플래그 조회·토글. --enable / --disable과 함께 쓴다.
codex app: 데스크톱 앱 진입(없으면 설치 안내).
codex app-server (EXPERIMENTAL): 앱 서버 시작.

12. 마무리 — 안전 기본값 + 캡쳐 체크리스트

안전 기본값 권장 세트

어디서 시작할지 모르겠다면 아래 네 가지를 기본값으로 잡는다.

# config.toml — 안전 기본값
    approval_policy = "on-request"    # on-request | untrusted | never
    sandbox_mode    = "workspace-write" # 파일·네트워크 접근 수준
    
    # CI 환경에서는 OPENAI_API_KEY 대신 CODEX_API_KEY를 별도 관리
    # export CODEX_API_KEY="sk-..."
    
    # tmux / cmux 환경에서 실행
    # codex --no-alt-screen "프롬프트"

approval_policy = "on-request": Codex가 실행 전 승인을 요청한다. 의도하지 않은 변경의 첫 번째 방어선이다.
sandbox_mode = "workspace-write": 작업 디렉터리는 쓰되 그 외 파일시스템·네트워크는 제한한다.
CODEX_API_KEY: CI에서 개인 OpenAI 키 대신 별도 발급한 Codex 전용 키를 쓰면 권한 범위를 좁게 유지한다.
--no-alt-screen: tmux 환경에서 대체 스크린 버퍼를 끄면 다른 패널과 스크롤백이 섞이지 않는다.

캡쳐 체크리스트 — 직접 검증하기

이 글은 codex-cli 0.130.0 기준으로 작성됐다. 자신의 환경에서 명령을 실행해 화면을 캡쳐할 때 다음 항목을 함께 확인하면 글의 정확성을 직접 검증할 수 있다.

섹션 1 기본기
□ / 입력 시 popup이 뜨는가
□ Tab으로 큐잉 표시("Queued")가 나타나는가
□ /approvals 입력 시 비활성/안내 메시지가 뜨는가

섹션 2-7 공식 등재 명령
□ /new, /resume, /fork, /side, /clear, /compact, /exit, /logout — 화면 변화 캡쳐
□ /model, /fast, /permissions, /experimental — picker·토글 UI 캡쳐
□ /mention, /mcp, /plugins, /apps, /agent — 카드·표 형태 캡쳐
□ /init, /diff, /review, /plan — 결과 view 캡쳐
□ /status, /debug-config, /feedback, /copy — 상태표·진단 결과 캡쳐
□ /theme, /title, /statusline, /keymap — 변경 즉시 반영 캡쳐

섹션 8 게이트 명령
□ /goal — config.toml에 features.goals = true 세팅 후 실행
□ /personality — 사용 모델이 지원하는지 popup 표시 여부 확인
□ /ps, /stop — features.unified_exec = true 세팅 후 백그라운드 셸 띄워보기

섹션 9 미등재 명령
□ /rename, /raw, /skills, /approve, /realtime, /settings, /collab, /setup-default-sandbox — 자신의 버전에 존재하는지 popup·직접 입력으로 확인
□ 비활성 상태로 표시되면 어떤 플래그가 필요한지 /debug-config에서 점검

자주 겪는 문제

슬래시 명령이 popup에 안 나온다: alias이거나(/quit↔/exit) feature 플래그가 꺼져 있을 수 있다. 직접 입력 후 Enter로 시도하고 /debug-config로 게이트 조건을 확인한다.
명령이 "비활성" 상태로 보인다: 필요한 feature 플래그가 꺼져 있다는 뜻이다. /experimental로 즉시 토글하거나 config.toml에서 영구 설정한다.
config.toml 변경이 반영되지 않는다: TUI를 완전히 재시작한다. 일부 키는 세션 재시작이 필요하다.
tmux에서 화면이 깨진다: --no-alt-screen 플래그를 붙이거나 /raw로 렌더링 모드를 전환해본다(v0.129.0~).

참고 자료

Codex CLI 입문(7) : Claude Code 사용자를 위한 Codex 전환 가이드 - CLAUDE.md·슬래시 명령·MCP 완전 마이그레이션

갓대희 — Sat, 16 May 2026 19:03:07 +0900

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

Claude Code를 쓰다가 Codex로 갈아타려는 분을 위한 실전 이사 가이드입니다. Mac 데스크톱 앱의 자동 import 경로와 CLI 수동 경로 중 하나를 고른 뒤, CLAUDE.md를 세 줄기로 나눠 옮기고 5분 Smoke Test로 확인하는 흐름으로 설명합니다.

한 줄 결론

Mac 데스크톱 앱이면 "Import other agent setup" 한 번 클릭으로 시작한다.
CLI라면 CLAUDE.md를 개인 취향 / 팀 컨벤션 / 위험 지시 세 줄기로 나눠 옮긴 뒤, Smoke Test로 확인한다.

OpenAI Codex 개발자 시리즈

이 글은 2026년 5월 15일 기준 OpenAI Codex 공식 문서와 Anthropic Claude Code 공식 문서를 바탕으로 작성되었다. 기능 이름과 설정 키는 계속 바뀔 수 있으므로 실제 이전 전에는 각 도구의 최신 문서를 다시 확인하자.

1. 먼저 경로를 고른다

마이그레이션 경로는 두 가지이다.

경로	언제 쓰나	무엇을 해주나	한계
경로 A Mac 앱 자동 import	Codex Mac 데스크톱 앱을 쓰는 경우	instructions·config·skills·MCP·hooks·subagents까지 일괄 가져오기 시도	tool 제한·MCP custom auth·plugins는 import 후 수동 검토 필요
경로 B CLI 수동 마이그레이션	CLI만 쓰거나 세밀하게 제어하고 싶은 경우	CLAUDE.md를 직접 분류해서 AGENTS.md + config.toml로 옮김	자동 변환 없음, 모든 매핑을 수동으로 해야 함

경로 A — Mac 앱 "Import other agent setup"

⚠ Mac 데스크톱 앱 전용

"Import other agent setup"은 Codex Mac 데스크톱 앱에만 있는 UI 버튼이다. CLI(codex 명령어)에는 동일한 import 명령이 없다. (출처: Codex Mac 앱 가이드 §9 — 같은 시리즈 본문 직접 확인)

사용 방법:

Codex Mac 앱 실행 → 설정(⚙) 열기
"다른 에이전트 설정 가져오기" 항목 확인 — Codex가 로컬 에이전트(Claude, Cursor, Continue 등)를 자동 감지해서 목록을 표시한다
가져오기 버튼 클릭 → 해당 도구의 시스템 프롬프트·규칙이 Codex 맞춤형 지침으로 전환된다
결과 검토: 자동 변환 내용이 의도와 맞는지 맞춤형 지침 화면에서 직접 확인한다

자동 import 후 반드시 검토해야 하는 것

자동 import가 시도되지만 그대로 신뢰하면 안 되는 항목이다. (출처: OpenAI Codex — Migrate to Codex)

import된 skills·subagents의 tool restrictions / permissions — Codex의 sandbox·approval·Rules와 의도대로 맞는지 검토 (§4 함정 ① 참고)
MCP 서버의 custom authentication · headers · env vars · transports — import 후 ~/.codex/config.toml 에서 직접 확인 (§5 접힘 박스 참고)
Claude Code 전용 plugins · marketplaces — Codex에 대응 기능 없으면 수동 후속 작업 필요

경로 B — CLI 수동 마이그레이션 핵심 매핑

CLI만 쓰거나 Mac 앱이 없는 환경이면 경로 A를 건너뛰고 아래 매핑 표만 참고한 뒤 §2로 이동하면 된다. CLI 경로는 아래 표를 기준으로 파일을 옮긴다.

Claude Code	Codex	한 줄 설명
`~/.claude/CLAUDE.md`	`~/.codex/AGENTS.md`	개인 전역 지침 (이름 호칭, 응답 스타일 등)
`.claude/CLAUDE.md`	`AGENTS.md` (프로젝트 루트)	팀 컨벤션, 코드 스타일 (Git 추적)
`~/.claude/settings.json`	`~/.codex/config.toml`	전역 설정 (sandbox, approval, model 등)
`.mcp.json`	`[mcp_servers.*]` in config.toml	MCP 서버 목록 (§5 접힘 박스 참고)
`hooks` in settings.json	`hooks` in config.toml	이벤트 훅 (§4 함정 ② + §5 접힘 박스 참고)
permission mode `default / acceptEdits / plan / auto`	`sandbox_mode` + `approval_policy` sandbox_mode: `read-only` / `workspace-write` / `danger-full-access` approval_policy: `untrusted` / `on-request` / `never` / `{ granular = {...} }`	§4 함정 ① 참고 — 1:1 대응 안 됨

2. CLAUDE.md를 세 줄기로 나눈다

CLAUDE.md를 한꺼번에 복사하지 말고 내용 유형별로 세 줄기로 분류한 뒤 각자 다른 곳으로 보낸다.

Step 1 — 개인 취향 → `~/.codex/AGENTS.md`

해당하는 내용: 이름 호칭, 응답 언어, 설명 스타일, "마지막 줄에 요약 추가해줘" 같은 개인 습관

목적지: 전역 사용자 지침 파일 — 내 모든 Codex 세션에 적용된다

# 터미널에서 실행
ls ~/.claude/CLAUDE.md # 없으면 이 단계 건너뜀
mkdir -p ~/.codex
cat ~/.claude/CLAUDE.md
# 개인 취향 부분만 복사해서 아래 파일에 붙여넣기
nano ~/.codex/AGENTS.md

개인 취향 예시

응답은 한국어로 해줘
코드 변경 전에 한 줄로 계획 먼저 말해줘
파일 수정 후 변경 요약을 마지막에 덧붙여줘

Step 2 — 팀 컨벤션 → 프로젝트 루트 `AGENTS.md`

해당하는 내용: 코드 스타일, 브랜치 전략, 테스트 방침, 프레임워크 컨벤션

목적지: 프로젝트 루트 AGENTS.md — Git에 커밋해서 팀과 공유한다

# 프로젝트 루트에서 실행
ls .claude/CLAUDE.md # 없으면 이 단계 건너뜀
cat .claude/CLAUDE.md
# 팀 컨벤션 부분만 복사 → 아래 파일에 작성
nano AGENTS.md
git add AGENTS.md && git commit -m "chore: add Codex AGENTS.md"

trusted project 필수

프로젝트 루트 AGENTS.md는 trusted project에서만 자동 적용된다. 외부에서 clone한 프로젝트는 untrusted로 간주되어 프로젝트 설정이 무시된다. 자세한 신뢰 설정은 Part 4: AGENTS.md · Rules를 참고한다.

Step 3 — 위험 지시는 보류 또는 폐기

해당하는 내용: 권한 우회 지시, 자동 승인 설정, subagent 위임 설정, 실험적 플래그

처리 방침: 복사하지 말고 Codex의 sandbox·approval·Rules 체계로 새로 설계한다 (§4 함정 ① ③ 참고)

보류해야 할 지시 예시

allowedTools 목록 전체 (→ Codex Rules의 prefix_rule로 재설계)
bypassPermissions: true (→ Codex에선 sandbox 모드로 대응)
"subagent에게 모든 파일 접근 권한 줘" 류의 지시 (→ §4 함정 ③ 참고)

3. 5분 Smoke Test — 설정이 작동하는지 확인

설정을 옮긴 뒤 바로 실제 코드를 맡기지 말고, 아래 항목을 순서대로 확인한다.

파일을 바꾸지 않는 작업으로 sandbox와 approval 정책이 의도대로 작동하는지 검증하는 게 핵심이다.

전제: 2번 섹션의 결과물(~/.codex/AGENTS.md, 프로젝트 루트 AGENTS.md, ~/.codex/config.toml) 이 준비된 상태에서 시작한다.

Smoke Test 체크리스트

[ ] 1. AGENTS.md 위치 확인

ls ~/.codex/AGENTS.md            # 개인 지침
ls ./AGENTS.md                # 프로젝트 지침 (프로젝트 루트에서)

기대 결과: 두 파일 모두 존재하면 Codex가 세션 시작 시 자동으로 읽는다

[ ] 2. 첫 실행(읽기 작업만)

# 프로젝트 루트에서 실행해야 ./AGENTS.md가 적용됨
cd <프로젝트-루트>
codex # 실행 후 AGENTS.md 내용 요약해줘라고 요청

기대 결과: Codex가 AGENTS.md를 읽어 내용을 요약해 응답한다. 응답 스타일이 개인 지침을 따르는지 확인한다. 루트가 아닌 곳에서 실행하면 프로젝트 AGENTS.md가 적용되지 않으므로 응답에서 빠지면 위치를 다시 확인한다.

[ ] 3. sandbox 모드 확인

~/.codex/config.toml에 sandbox_mode = "workspace-write"가 있다면, 세션에서 파일 쓰기 요청 시 approval_policy대로 멈추는지 확인한다

# ~/.codex/config.toml 예시
sandbox_mode = "workspace-write"
approval_policy = "on-request"

기대 결과: 파일 쓰기 도구 호출 전에 "허용할까요?" 승인 요청이 뜬다

[ ] 4. MCP 연결 확인 (MCP를 옮긴 경우만)

# TUI 안에서 입력
/mcp # 연결된 MCP 서버 목록과 상태 확인
# 그 다음 MCP 도구 하나를 자연어로 호출 (예: "filesystem MCP로 현재 폴더 ls 해줘")

기대 결과: 정상이면 도구 응답이 반환된다. 실패하면 보통 auth · headers · env_vars · transport 중 하나의 import 누락이다 — config.toml의 [mcp_servers.*] 섹션을 §5 접힘 박스 기준으로 다시 점검한다.

[ ] 5. 첫 실제 작업 1개 완료

5-A (read-only 환경): "현재 디렉토리 구조 설명해줘" 같은 읽기 전용 탐색 1개
5-B (workspace-write 환경): 단순 파일 생성 1개 (예: test.md에 'hello' 한 줄 써줘) — approval 요청이 §3-3 기대대로 뜨는지 확인

4. 빠지기 쉬운 함정 3가지

마이그레이션 과정에서 자주 만나는 실수를 정리했다. 세 가지 모두 "Claude Code 방식을 그대로 이식하려는" 데서 생긴다.

함정 ① — permissions allow/deny를 AGENTS.md에 그대로 적지 말 것

잘못된 이식	Codex 방식
AGENTS.md에 `"파일 쓰기는 항상 허용"` 적기	config.toml에 `sandbox_mode = "workspace-write"` `approval_policy = "on-request"`
AGENTS.md에 `"git push는 금지"` 적기	`~/.codex/rules/default.rules`에 `prefix_rule(pattern=["git","push"], decision="forbidden")` (Part 4 참고)

왜?

Codex는 권한 제어를 자연어 지시로 처리하지 않고, sandbox(파일·네트워크 범위)와 approval(승인 시점)을 config.toml로, 명령별 허용·차단을 Rules로 분리한다.

AGENTS.md에 적은 권한 지시는 무시되거나 의도치 않게 작동할 수 있다.

함정 ② — hooks를 1:1로 이식하지 말 것

Claude Code	Codex	주의
`PreToolUse`	`PreToolUse`	이름 같음, 설정 위치 다름
`PostToolUse`	`PostToolUse`	이름 같음, 설정 위치 다름
`PreToolUse`로 도구 실행 차단	Codex도 가능 — PreToolUse hook이 `permissionDecision: "deny"` 반환 시 차단됨. 단, Rules가 정책 우선순위	⚠ hooks는 enforcement 경계가 아니라 보조 — 정책성 차단은 Rules에 두는 것이 안전

왜? Codex에서도 PreToolUse hook이 permissionDecision: "deny" 또는 exit code 2를 반환해 차단할 수 있다.

그러나 공식 문서는 hooks를 "단일 enforcement 경계로 의존하지 말 것"이라고 명시한다.

(출처: OpenAI Codex — Hooks)

역할 분리 — 이 두 줄만 기억하면 된다

Hook: 알림·로그·임시 검사 (예: PostToolUse에서 "테스트 자동 실행")
Rules: 영구·정책성 차단 (예: git push forbidden, 외부 도메인 접근 prompt)

hooks 상세는 §5 접힘 박스 참고.

함정 ③ — subagent의 tool 권한을 그대로 옮기지 말 것

먼저: Codex에도 Subagents가 있다. Mac 앱 import는 Claude의 subagent를 Codex의 subagent로 자동 가져온다. 다만 가져온 subagent의 tool restrictions·permissions는 import 후 반드시 검토해야 한다. (출처: OpenAI Codex — Migrate)

그대로 신뢰	검토 후 적용
import된 subagent의 allowedTools 목록을 그대로 신뢰하기	Codex Mac 앱: 설정 → Subagents 화면에서 열기. CLI: `~/.codex/agents/.toml` 또는 프로젝트 `.codex/agents/.toml` 파일을 열어 tool 권한과 sandbox 범위가 의도와 맞는지 확인
subagent가 임의로 외부 서비스를 호출하도록 두기	외부 서비스 호출은 MCP 서버로 옮기고 (Part 5), subagent는 작업 분담에만 사용

왜? Mac 앱 import는 subagent를 옮기지만, Claude Code와 Codex의 권한 모델이 다르기 때문에 import된 subagent가 의도보다 넓은 권한을 가질 수 있다.

import 후 Codex Subagents 설정을 열어 tool 권한·sandbox 범위를 직접 확인하는 절차가 필수다.

5. MCP · hooks · Rules — 이미 쓰는 팀만 열어보기

아래 세 섹션은 이미 Claude Code에서 MCP·hooks·규칙을 쓰고 있는 팀만 참고한다. 처음 마이그레이션하는 분은 §1~§4만으로 충분하다.

▶ MCP 서버 옮기기 (config.toml 형식)

.mcp.json (Claude Code) → config.toml [mcp_servers.*] (Codex)

# ~/.codex/config.toml 예시

[mcp_servers.filesystem]
  command = "npx"
  args = ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"]

[mcp_servers.github]
  command = "npx"
  args = ["-y", "@modelcontextprotocol/server-github"]
  env_vars = ["GITHUB_TOKEN"]

대안: config.toml을 직접 편집하지 않고 CLI로 추가할 수도 있다 — codex mcp add, codex mcp login, TUI에서는 /mcp.

MCP 스코프(읽기 전용·읽기쓰기), HTTP 서버 연결, 헤더 설정 등 상세 옵션은 Part 5: MCP · Plugins · Skills를 참고한다.

▶ hooks 이벤트 매핑 (이름과 위치 변경)

이벤트	Claude Code	Codex
도구 실행 전	`PreToolUse`	`PreToolUse`
도구 실행 후	`PostToolUse`	`PostToolUse`
승인 요청 시	`PermissionRequest`	`PermissionRequest` — 양쪽 공통
프롬프트 제출 시	`UserPromptSubmit`	`UserPromptSubmit`
세션 시작	`SessionStart`	`SessionStart`
세션 종료	`Stop`	`Stop`

# ~/.codex/config.toml — array of tables 구조
[[hooks.PreToolUse]]
  matcher = "^Bash$"

[[hooks.PreToolUse.hooks]]
  type = "command"
  command = "/usr/bin/python3 .codex/hooks/check.py"
  timeout = 30

주의: 단일 테이블([hooks.PreToolUse])이 아니라 array of tables([[hooks.PreToolUse]]) 구조다.

하나의 이벤트에 여러 hook을 등록할 수 있도록 설계됐다. (출처: OpenAI Codex — Hooks) hooks 상세 설정과 이벤트 페이로드는 Part 4: AGENTS.md · Rules를 참고한다.

▶ Rules prefix_rule — allow / prompt / forbidden

Codex Rules는 Starlark(Python 유사 안전 실행 언어)로 작성하며 파일은 ~/.codex/rules/*.rules에 둔다. Claude Code의 allowedTools(허용·거부 두 단계) 대신 Codex는 세 단계 결정을 쓴다.

결정값	의미	Claude Code 대응
`allow`	승인 없이 바로 실행	allowedTools 허용
`prompt`	매번 승인 요청	— (없음, Codex 추가 단계)
`forbidden`	완전 차단	allowedTools deny

# ~/.codex/rules/default.rules — Starlark 함수 호출
prefix_rule(
  pattern = ["git", "push"],
  decision = "forbidden",
  justification = "main 푸시는 차단",
)

주의: prefix_rule = "forbidden"처럼 TOML 키값 대입이 아니라 함수 호출 형태로 작성한다. pattern은 문자열 리스트, decision은 "allow" / "prompt" / "forbidden" 중 하나. (출처: OpenAI Codex — Rules)

작성 방법과 패턴 예시는 Part 4: AGENTS.md · Rules를 참고한다.

자주 묻는 질문

"Import other agent setup"은 CLI에서도 쓸 수 있나?

아니다. 이 기능은 Codex Mac 데스크톱 앱 전용 UI 버튼이다. CLI(codex 명령어)에는 동일한 import 명령이 없다. CLI 사용자는 §2의 3분류 단계에 따라 CLAUDE.md를 직접 분류해서 옮겨야 한다.

CLAUDE.md를 통째로 복사해도 되나?

권장하지 않는다. 권한 지시·hooks·subagent 설정은 Codex의 sandbox·approval·Rules 체계와 1:1로 맞지 않아서, 그대로 복사하면 무시되거나 의도치 않게 작동한다. §4 함정 ①②③을 먼저 확인하고 설계한 뒤 옮긴다.

마이그레이션 후 설정이 제대로 적용됐는지 어떻게 확인하나?

§3 Smoke Test 체크리스트를 순서대로 따라한다. AGENTS.md 위치 확인 → 간단한 설명 요청으로 지침 적용 여부 확인 → 파일 쓰기 요청으로 approval 정책 확인 순서다. 설정을 바꿔도 현재 세션에 바로 반영되지 않으므로, Rules·hooks 변경 후에는 새 세션을 열어 재확인해야 한다.

참고 자료

OpenAI Codex 공식 문서

Claude Code 공식 문서

같은 시리즈

작성일: 2026-05-06. 최종 수정: 2026-05-15. 공식 문서 기준. CLI 동작과 설정 키는 버전에 따라 변경될 수 있다.

Codex CLI 입문(6) : Codex 자동화 파이프라인 구축 - 사람 없이 돌아가는 Codex

갓대희 — Wed, 13 May 2026 01:23:13 +0900

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

Codex 자동화라고 하면 CI 파이프라인, GitHub Actions, sandbox 설정을 한꺼번에 떠올리기 쉽다. 하지만 처음부터 그게 다 필요한 건 아니다.

이 글은 세 단계로 나눈다. 레벨 1은 내 컴퓨터에서 혼자, 레벨 2는 팀 저장소에 공유하기, 레벨 3은 PR마다 자동으로 실행하기.

각 단계에서 복붙하면 바로 되는 예제 하나씩을 이글에서는 준비해봤다.

이 글에서 나오는 용어 2개

sandbox — Codex가 내 파일을 얼마나 건드릴 수 있는지 범위를 정하는 설정. read-only는 읽기만 하고 파일을 수정하지 않는다.
stdout — 명령 실행 후 터미널에 출력되는 결과. > 파일명으로 파일에 저장할 수 있다.

OpenAI Codex 개발자 시리즈

Part 1: CLI 빠른 시작 Part 2: 핵심 개념 4가지 Part 3: Subagents · Workflows Part 4: AGENTS.md · Rules Part 5: MCP · Plugins · Skills Part 6: 자동화 (현재 글) Part 7: 마이그레이션 Part 8: 슬래시 명령어 정리(예정)

레벨 1 — 내 컴퓨터에서 바로 써보기
레벨 2 — 팀 저장소에 등록하기
레벨 3 — GitHub Actions에 붙이기
자동화 안전 규칙 5가지
정리와 다음 편 안내

레벨 1 — 내 컴퓨터에서 바로 써보기

GitHub Actions도 필요 없다.

CI 설정도 없다. Codex CLI가 설치되어 있고 인증되어 있으면 지금 바로 실행할 수 있다.

1-1. 낯선 저장소 빠르게 파악하기

처음 들어온 저장소가 어떻게 생겼는지, 어떤 부분이 복잡한지 빠르게 파악하고 싶을 때 쓴다. 저장소 루트에서 아래 한 줄을 실행하면 된다.

복붙하고 바로 실행

codex exec --sandbox read-only \
  "이 저장소 구조를 요약하고, 복잡하거나 위험해 보이는 파일 3개를 경로와 함께 알려줘" \
  > summary.md

ex)

- 응답 예시 (터미널 출력)

- summary.md 파일도 생성해서 해당 파일에 작성해 두었다.

결과가 summary.md 파일로 저장된다. --sandbox read-only는 Codex가 파일을 읽기만 하고 수정하지 않도록 막아준다. 처음엔 항상 이 플래그를 붙인다.

1-2. 특정 파일 집중 검토하기

새로 작성한 파일이나 수정이 많았던 파일을 빠르게 검토하고 싶을 때다. 파일 경로를 프롬프트에 직접 넣으면 된다.

복붙하고 파일명만 바꿔서 실행

codex exec --sandbox read-only \
  "src/components/features/auth/Auth.tsx 파일을 검토해줘. 보안 문제나 빠진 예외 처리가 있으면 줄 번호와 함께 알려줘."

실행하면 이런 결과가 나온다

## 검토 결과: src/auth/login.ts

보안 문제
- 34번째 줄: password를 평문으로 로그에 출력 중 (console.log 제거 필요)
- 52번째 줄: 로그인 실패 횟수 제한 없음, brute-force 공격에 취약

빠진 예외 처리
- 67번째 줄: DB 연결 실패 시 500 에러가 그대로 클라이언트로 전달됨
- 89번째 줄: JWT 만료 토큰 처리 없음

ex) 실제로 수정해야하는 이슈들이 도출되었아. (실제 결과는 생략)

1-3. 커밋 전 30초 안전 체크

코드를 수정하고 커밋하기 직전, "혹시 놓친 게 있나?" 싶을 때 쓴다. 변경 내용을 파일로 저장해서 Codex에게 넘기는 패턴이다.

복붙하고 바로 실행 (git add 하기 전에 실행)

# 1. 변경 내용을 파일로 저장
git diff > /tmp/my-changes.txt

# 2. Codex에게 검토 요청
codex exec --sandbox read-only \
  "/tmp/my-changes.txt 파일을 보고, 버그나 빠진 부분이 있으면 알려줘. 없으면 '이상 없음'이라고 해줘."

ex) 결과 예시

왜 파일로 저장하고 넘기나?

Codex는 지시한 파일을 직접 읽는다. git diff 출력이 길어도 파일로 넘기면 안정적으로 처리된다. 터미널 명령 중간에 직접 붙여 넣으면 내용이 잘리거나 파싱에 실패할 수 있다.

레벨 1 핵심 정리

--sandbox read-only를 항상 붙인다 — 파일을 수정하지 않으므로 실수할 걱정 없다
> 파일명.md로 결과를 저장한다 — 나중에 다시 보거나 팀에 공유할 수 있다
프롬프트에 파일 경로와 원하는 출력 형식을 명시할수록 결과가 구체적이다

레벨 2 — 팀 저장소에 등록하기

레벨 1 명령어가 익숙해지면, 팀원 누구나 같은 명령을 쓸 수 있도록 저장소에 등록한다.

복잡한 설정 없이 package.json 스크립트로 충분하다.

2-1. npm script로 팀 공유하기

package.json의 scripts에 등록하면 팀원 모두 npm run codex:check으로 같은 검토를 실행할 수 있다.

package.json에 추가하기

{
  "scripts": {
    "codex:check": "mkdir -p reports && codex exec --sandbox read-only 'src/ 폴더에서 타입 오류나 버그 가능성이 있는 부분을 파일 경로와 함께 알려줘' > reports/check.md && echo '완료: reports/check.md를 확인하세요'",
    "codex:review-diff": "git diff > /tmp/pr-diff.txt && codex exec --sandbox read-only '/tmp/pr-diff.txt 파일을 보고 문제가 있으면 알려줘' > reports/diff-review.md"
  }
}

ex) 상기 스크립트 추가

- 추가한 스크립트 실행 및 결과 예시

팀원은 이제 npm run codex:check 또는 npm run codex:review-diff만 치면 된다. 긴 명령어를 외울 필요가 없다.

reports/ 폴더 처리 팁

결과 파일이 저장되는 reports/ 폴더를 .gitignore에 추가하면 검토 결과가 커밋에 포함되지 않는다.

# .gitignore에 추가
reports/

2-2. 프롬프트를 파일로 관리하기

검토 기준이 길어지거나, 팀 내 리뷰 관점을 통일하고 싶다면 프롬프트를 파일로 분리한다. 파일로 관리하면 리뷰 기준 변경도 PR로 리뷰할 수 있다.

.github/codex-prompts/review.md 파일을 만들고:

이 코드를 리뷰해줘. 아래 관점으로만 확인하고, 코드는 수정하지 말아줘.

확인할 것:
- 버그나 논리 오류
- 빠진 예외 처리
- 보안 취약점 (SQL injection, XSS, 노출된 시크릿 등)
- 테스트가 필요한데 없는 함수

결과 형식:
각 문제를 "파일경로:줄번호 — 문제 설명" 형식으로 나열해줘.
문제가 없으면 "이상 없음"이라고만 해줘.

ex) 나의 경우는 AI에게 생성 요청하였다.

- 내 nextjs 프로젝트 기준, 프로젝트 폴더 기준에 맞게 변경하여 등록 해 보았다.

이 저장소의 코드를 리뷰해줘. 코드는 수정하지 말고, 아래 관점으로만 확인해줘.

리뷰 대상:
- 현재 git diff가 있으면 변경된 파일과 그 영향 범위를 우선 확인한다.
- diff가 없으면 `src/app`, `src/components`, `src/services`, `src/hooks`, `src/utils`, `src/constants`, `tests`를 중심으로 확인한다.
- 명확한 근거가 있는 문제만 보고하고, 단순 취향이나 스타일 취향은 제외한다.

프로젝트 전제:
- Next.js 16 App Router, React 19, TypeScript strict mode, Tailwind CSS 4 기반이다.
- 라우팅, 공개 경로, SEO metadata, AdSense 배치, API 프록시(`/api`, `/crawl`)가 사용자 영향도가 큰 영역이다.

확인할 것:
- 버그나 논리 오류: 라우팅 상수와 실제 페이지 경로 불일치, query param 처리 오류, 조건 분기 누락, 상태 갱신 순서 문제, 잘못된 memo/dependency 사용.
- Next.js App Router 경계: Server Component에서 브라우저 API 사용, Client Component에 필요한 `'use client'` 누락, `useSearchParams` 등 Suspense가 필요한 훅 사용 방식, hydration mismatch 가능성.
- 예외 처리 누락: API 호출 실패, 비정상 응답, 빈 데이터, 파일/파서 입력 오류, 환경 변수 누락, 외부 서비스 지연 또는 실패.
- 보안 취약점: XSS(`dangerouslySetInnerHTML`, markdown/html 변환, diff 렌더링), open redirect, 노출된 시크릿, 토큰/localStorage 취급, 인증 우회, 프록시/CORS 오용.
- SEO와 공유 메타데이터: title/description, canonical, OpenGraph, Twitter card, sitemap/robots 영향, 페이지 목적과 맞지 않는 metadata.
- AdSense와 성능: 정책 위반을 유도하는 문구나 보상형 UI, 광고/이미지 영역 예약 누락으로 인한 CLS, `next/image` 크기 지정 누락, LCP를 악화시키는 font/image 사용.
- 테스트 갭: 복잡한 분기, route guard, API 에러 상태, parser/formatter, hook, 주요 사용자 플로우에 필요한 Vitest 또는 Playwright 테스트 누락.

결과 형식:
- 각 문제를 `파일경로:줄번호 — 문제 설명` 형식으로 나열한다.
- 문제 설명에는 왜 실제 위험인지와 필요한 테스트가 있으면 함께 적는다.
- 문제가 없으면 `이상 없음`이라고만 쓴다.

그리고 package.json 스크립트에서 --prompt-file로 참조한다:

{
  "scripts": {
    "codex:review": "codex exec --sandbox read-only --prompt-file .github/codex-prompts/review.md > reports/review.md"
  }
}

ex) pnpm codex:review

- 결과 (review.md 파일은 생략)

레벨 2 핵심 정리

npm script로 등록하면 팀 전체가 같은 기준으로 검토할 수 있다
프롬프트를 파일로 분리하면 리뷰 기준도 버전 관리가 된다
결과 파일은 .gitignore에 추가해서 커밋에서 제외한다

레벨 3 — GitHub Actions에 붙이기

레벨 2까지 익숙해졌다면, PR이 열릴 때마다 Codex가 자동으로 리뷰 코멘트를 달아주는 환경을 만들 수 있다.

레벨 3 준비물 3가지

GitHub 저장소 — 공개 또는 비공개 모두 가능
OPENAI_API_KEY — GitHub repository secret에 저장 (아래에서 설명)
프롬프트 파일 — 레벨 2에서 만든 .github/codex-prompts/review.md 재사용 가능

3-1. API key 안전하게 저장하기

GitHub Actions에서는 API key를 코드에 직접 쓰면 안 된다.

GitHub repository secret에 저장하고 워크플로우에서 참조하는 방식을 쓴다. "repository secret"은 저장소 설정에 보관하는 암호화된 값으로, 워크플로우 파일에서 ${{ secrets.이름 }} 형태로 꺼내 쓴다.

GitHub secret 저장 방법 (3단계)

저장소 페이지 → Settings 탭 클릭
Secrets and variables → Actions → New repository secret
Name: OPENAI_API_KEY / Value: 실제 API key 값 입력 후 저장

3-2. 미니멀 워크플로우 만들기

아래 파일을 저장소의 .github/workflows/codex-review.yml로 저장한다. PR이 열리거나 업데이트될 때마다 자동으로 실행된다.

.github/workflows/codex-review.yml 예시

name: Codex PR Review

on:
  pull_request:
    types: [opened, synchronize, reopened]

jobs:
  review:
    runs-on: ubuntu-latest
    permissions:
      contents: read        # 코드를 읽는 권한
      pull-requests: write  # PR 코멘트를 달 수 있는 권한
    steps:
      # 1. PR의 코드를 가져온다
      - uses: actions/checkout@v5

      # 2. Codex로 리뷰한다
      - uses: openai/codex-action@v1
        id: codex
        with:
          openai-api-key: ${{ secrets.OPENAI_API_KEY }}
          prompt-file: .github/codex-prompts/review.md
          sandbox: read-only

      # 3. 리뷰 결과를 PR 코멘트로 게시한다
      - uses: actions/github-script@v7
        if: steps.codex.outputs.final-message != ''
        with:
          script: |
            github.rest.issues.createComment({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: context.payload.pull_request.number,
              body: process.env.REVIEW_RESULT
            })
        env:
          REVIEW_RESULT: ${{ steps.codex.outputs.final-message }}

각 부분이 하는 일

on: pull_request — PR이 새로 열리거나 커밋이 추가될 때마다 자동 실행한다
permissions — 필요한 권한만 최소로 열어둔다. contents: read는 코드 읽기, pull-requests: write는 코멘트 달기에 필요하다
actions/checkout@v5 — PR의 코드를 내려받는다. 이게 없으면 Codex가 읽을 파일이 없다
prompt-file — 레벨 2에서 만든 프롬프트 파일을 그대로 재사용한다
sandbox: read-only — CI에서도 파일 수정 없이 읽기 전용으로만 실행한다

3-3. 실제로 어떻게 보이나

PR을 열면 몇 분 안에 Codex가 아래와 같은 코멘트를 자동으로 달아준다.

PR 코멘트 예시

## Codex 자동 리뷰 결과

발견된 문제
- src/payment/charge.ts:45 — 금액 계산에 부동소수점 오류 가능성 (정수 연산 권장)
- src/payment/charge.ts:67 — 결제 실패 시 롤백 처리 없음
- src/user/profile.ts:23 — XSS 취약점: 사용자 입력을 innerHTML에 직접 삽입

빠진 테스트
- charge() 함수의 실패 케이스 테스트 없음

이상 없는 파일: src/utils/format.ts, src/config/index.ts

주의: API key는 절대 코드에 직접 쓰지 않는다

워크플로우 파일에 key를 직접 쓰면 저장소에 노출된다. 반드시 ${{ secrets.OPENAI_API_KEY }} 형태로 참조한다.

레벨 3 핵심 정리

워크플로우 파일 1개, 프롬프트 파일 1개만 있으면 PR 자동 리뷰가 된다
API key는 GitHub secret에만 저장한다
처음에는 read-only로만 시작한다. 파일 수정이나 자동 커밋은 자동화가 안정적으로 동작한 뒤 천천히 추가한다

자동화 안전 규칙 5가지

자동화에서 문제가 생기는 대부분의 원인은 권한을 너무 넓게 열었거나, API key가 노출됐거나, 예상치 못한 입력이 프롬프트에 들어간 경우다. 아래 다섯 가지만 지키면 입문 단계에서 발생하는 대부분의 문제를 피할 수 있다.

처음엔 항상 read-only로 시작한다 — 파일을 수정하거나 커밋을 만드는 자동화는 read-only 리뷰가 안정적으로 돌아간 뒤에 추가한다
API key는 코드에 직접 쓰지 않는다 — 로컬은 환경변수, CI는 GitHub secret에만 저장한다. ~/.codex/auth.json 같은 파일도 git에 커밋하지 않는다
PR 본문이나 커밋 메시지를 프롬프트에 그대로 넣지 않는다 — 외부 기여자가 악의적인 지시문을 숨길 수 있다. 프롬프트는 내가 작성한 파일에서만 가져온다
결과는 파일이나 PR 코멘트로 남긴다 — 사람이 검토할 수 있는 형태로 남아야 자동화 결과를 신뢰할 수 있다
배포·push 자동화는 마지막에 추가한다 — 자동으로 코드를 수정하거나 push하는 단계는 수동 리뷰 → 파일 생성 → 제한된 브랜치 push 순서로 천천히 넓혀간다

정리

레벨	핵심 명령	결과
레벨 1	`codex exec --sandbox read-only "..." > file.md`	로컬에서 즉시 검토 결과
레벨 2	`npm run codex:check`	팀 전체가 같은 기준으로 검토
레벨 3	PR 오픈 시 워크플로우 자동 실행	PR마다 자동 리뷰 코멘트

세 레벨 모두 read-only로 시작하고, 결과를 파일이나 코멘트로 남기는 원칙이 공통이다. 이 두 가지만 지키면 자동화가 실수를 만들어도 코드베이스는 안전하다.

Codex CLI 입문(5) : Codex에 외부 도구 연결하기 - MCP, Plugin, Skill 사용법

갓대희 — Tue, 12 May 2026 19:00:06 +0900

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

Codex를 어느 정도 쓰다 보면 다음 질문이 생긴다. 코드 수정은 되는데, GitHub 이슈를 보거나, 외부 문서를 찾아오거나, 브라우저에서 화면을 확인하는 일은 여전히 다른 도구를 오가며 처리해야 한다.

이번 글에서는 그 연결부를 다뤄 보려고 한다.

MCP: Codex가 내 GitHub 이슈 목록을 직접 불러올 때.
Plugin: 팀 전체가 같은 MCP 묶음을 한 번에 설치할 때.
Skill: 매번 PR 리뷰 방식을 다시 설명 안 해도 될 때.

이름만 따로 떼면,

MCP(Model Context Protocol)는 Codex가 외부 도구를 호출하는 통로다.

Plugin은 그 도구·Skill 묶음을 한 패키지로 배포하는 단위다.

Skill은 자주 쓰는 작업 흐름을 마크다운 파일로 저장해 이름으로 호출하는 재사용 단위다.

먼저 용어부터 가볍게 잡고 가자 (미니사전)

MCP: AI가 외부 도구(GitHub, DB, 브라우저)에 표준 방식으로 요청·응답을 주고받는 통신 규약. USB-C 포트라고 보면 된다.
Plugin: MCP 서버·Skill·앱 연동을 한 패키지로 묶어 설치 가능하게 배포하는 단위.
Skill: 자주 쓰는 작업 흐름을 마크다운 파일로 저장해두고 이름으로 호출하는 재사용 단위.
transport: MCP 메시지를 실제로 주고받는 채널. 로컬 프로세스끼리 쓰는 stdio, 외부 서버용 HTTP가 대표적이다.
manifest: 플러그인 이름·버전·포함 MCP 서버 목록을 담은 설정 파일. 앱스토어 앱 정보지에 가깝다.
tool discovery: 에이전트가 MCP 서버에 "어떤 기능 있어?"라고 묻는 과정. 서버가 지원하는 도구 목록을 자동 파악한다.
capability negotiation: 연결 초기에 에이전트와 MCP 서버가 서로 지원 기능을 확인하는 협상 과정.
implicit invocation: 자연어로 작업을 설명하면 Codex가 등록된 Skill·Plugin 중 적절한 것을 자동 선택하는 방식.
explicit invocation: @plugin-name 또는 @skill-name으로 사용자가 직접 지정하는 방식. Skill이 여러 개일 때 결과 예측이 쉽다.

OpenAI Codex 개발자 시리즈

Part 1: CLI 빠른 시작 Part 2: 핵심 개념 4가지 (예정) Part 3: Subagents · Workflows Part 4: AGENTS.md · Rules Part 5: MCP · Plugins · Skills (현재 글) Part 6: 자동화 Part 7: 마이그레이션 Part 8: 슬래시 명령어 정리(예정)

MCP·Plugin·Skill 관계도 (한 장으로 보기)

[Codex Agent]
     │
     ├─[MCP]── GitHub API / DB / Browser
     │          (실시간 외부 도구 연결)
     │
     ├─[Plugin]── MCP 묶음 패키지
     │             (설치·배포 단위)
     │
     └─[Skill]── .md 작업 흐름 파일
                  (재사용 단위)

각 층의 역할은 아래 섹션에서 하나씩 살펴본다.

개념	한 줄 설명	언제 쓰나
MCP 서버	Codex가 외부 도구·데이터에 접근하는 연결 통로	GitHub 이슈, 라이브러리 문서, 브라우저 등 저장소 밖 자원이 필요할 때
Plugin	Skills·앱 연동·MCP 서버를 묶어 설치 가능한 형태로 배포하는 단위	팀 전원에게 동일한 확장 묶음을 배포해야 할 때
Skill	반복 작업 절차를 SKILL.md 파일로 정의해 Codex가 재사용하는 지침	릴리스 노트 작성, 보안 점검 등 팀 내 반복 작업을 표준화할 때
STDIO 서버	로컬 프로세스를 실행해 MCP 서버와 표준 입출력으로 통신하는 방식	네트워크 설정 없이 로컬에서 빠르게 MCP 서버를 테스트할 때
HTTP 서버	URL로 접근하는 외부 MCP 서버 — 인증 토큰으로 연결	Figma, GitHub 등 외부 SaaS 서비스를 Codex 작업에 연결할 때

1. MCP가 왜 중요한가

Codex의 기본 능력은 현재 프로젝트를 읽고, 코드를 수정하고, 셸 명령을 실행하는 데 있다.

하지만 실제 개발 업무는 저장소 안에서만 끝나지 않는다. 이슈 트래커, 문서 사이트, 디자인 파일, 브라우저, 로그 시스템까지 함께 봐야 할 때가 많다.

나도 처음에 Codex로 코드만 고치다가, "그래서 이 라이브러리 최신 문서대로 맞췄나?"가 늘 걸렸다. 외부 문서·이슈를 같이 보게 만드는 통로가 바로 MCP다.

MCP 공식 문서는 Codex에서 MCP 서버를 설정하는 방법을 다룬다. 여기서 중요한 점은 MCP를 "또 하나의 플러그인 이름"으로 보는 것이 아니라, Codex가 외부 도구나 공유 정보에 접근하는 서버 연결 방식으로 이해하는 것이다.

MCP 연결할 때 자주 듣는 두 단어

tool discovery: 에이전트가 MCP 서버에 "너 어떤 기능 있어?"라고 묻는 과정. 서버가 지원하는 도구 목록을 자동으로 파악한다.
capability negotiation: 연결 초기에 에이전트와 MCP 서버가 서로 지원 기능을 확인하고 맞추는 협상 과정. 두 사람이 만나기 전에 "나는 영어, 너는 한국어 가능해?"부터 맞추는 것과 같다.

MCP 서버가 많을수록 Codex가 더 유능해질까?

툴킷이 많을수록 더 유능하다는 직관은 MCP에서 그대로 통하지 않는다. 오히려 반대로 작동하는 상황이 있다.

MCP tool result를 통한 prompt injection — MCP 서버가 반환하는 텍스트 안에 지시문이 숨어 있으면 Codex가 그것을 다음 행동의 지시로 읽을 수 있다. 공식 문서는 이 공격 벡터를 별도로 다루지 않는다. 하지만 외부 MCP 서버가 반환하는 데이터를 신뢰 경계 밖 입력으로 취급해야 하는 이유가 여기 있다.

MCP가 진짜 필요한 3가지:

① 저장소 밖 데이터를 Codex가 직접 읽어야 할 때 (문서, 이슈 트래커)

② Codex 작업 결과를 외부 시스템에 써야 할 때 (GitHub PR 생성)

③ 브라우저·로그 같은 런타임 상태를 확인해야 할 때. 이 3가지 중 하나가 아니면 MCP 없이 프롬프트로 충분하다.

실전에서는 "라이브러리 문서를 확인하고 그 기준으로 코드를 고쳐라" 같은 요청이 대표적이다.

이때 context7 같은 문서 MCP 서버를 붙이면 Codex가 기억에만 기대지 않고 외부 문서를 직접 읽는다.

MCP를 한 줄 비유로 다시 말하면

노트북 충전기·외장 모니터·외장 SSD가 다 다른 단자를 쓰던 시절을 USB-C가 정리한 것과 같다.
도구마다 다른 통신 방식을 만들지 말고, AI 에이전트와 외부 도구가 공통 규약 하나만 알고 있으면 된다는 발상이 MCP다.
Codex가 GitHub에 붙든, Notion에 붙든, 사내 DB에 붙든 같은 문법으로 도구를 호출한다.

잠깐 — 어려운 문법 외우기 전에 이것부터

MCP를 설치하지 않아도 Codex는 이미 CLI를 직접 호출할 수 있다.

초보자라면 이 세 가지만 알고 시작해도 충분하다.

codex "React 최신 useEffect 규칙대로 수정해" — context7 MCP를 등록하면 Codex가 공식 문서를 직접 참조하며 수정한다
aws s3 ls · gh pr view 123 — MCP 없이도 Codex가 CLI를 직접 호출한다. "aws mcp 안 깔아도 클로드 코드가 알아서 aws cli로 처리한다"는 실무 사례가 있다 (GeekNews @jamsya, 2026-03)
codex "myorg/myrepo 이슈 #42에 bug 라벨 붙여줘" — GitHub MCP를 등록하면 자연어 한 줄로 끝난다

"원격 실행은 MCP, 로컬 실행은 Skills로 정리되는 것 같습니다" — GeekNews @m00nlygreat (2026-03)

2. MCP 서버 등록 — STDIO와 HTTP

가장 먼저 익힐 방식은 CLI(Command Line Interface — 터미널에서 명령어로 조작하는 방식) 등록이다.

공식 문서의 기본 문법은 다음과 같다.

codex mcp add <server-name> --env VAR1=VALUE1 --env VAR2=VALUE2 -- <stdio server-command>

이 문법에서 -- 뒤쪽은 실제 STDIO 서버를 시작하는 명령이다.

즉 codex mcp add는 서버 이름과 환경변수를 Codex 설정에 등록하고, 마지막 명령으로 MCP 서버를 어떻게 띄울지 알려준다.

공식 문서에 나온 context7 등록 예시는 다음과 같다.

codex mcp add context7 -- npx -y @upstash/context7-mcp

주의: npx -y는 npm 패키지를 내려받아 실행할 수 있다. 블로그 예시를 복사하기 전에는 패키지 출처, 버전, 공식 문서 링크를 확인하고 팀 환경에서는 버전 고정을 검토한다.

이 명령은 context7이라는 이름으로 STDIO MCP 서버를 등록한다. 문서 확인이 자주 필요한 프론트엔드·SDK 작업에서는 이 유형의 문서 서버가 특히 유용하다.

환경변수가 필요한 서버는 다음 패턴으로 등록한다. 아래는 공식 문법을 따른 템플릿이며, 실제 서버 명령과 변수명은 해당 MCP 서버 문서에 맞춰 바꿔야 한다.

codex mcp add my-server --env API_TOKEN=$API_TOKEN -- node ./server.js

등록 후에는 터미널 UI에서 /mcp 명령을 사용하거나, 셸에서 codex mcp --help로 관련 명령을 확인할 수 있다.

공식 문서가 확인해주는 범위는 여기까지이며, 서버별 헬스체크 절차는 각 MCP 서버 문서를 함께 봐야 한다.

따라 해보는 MCP 설정

세 패턴 — STDIO 1종, HTTP 2종

STDIO는 로컬에서 프로세스를 직접 실행한다. HTTP는 외부 서비스 엔드포인트에 직접 연결한다. 두 방식 모두 TOML에 기록되며 공통 원칙은 같다.

인증 정보는 환경변수 이름만 — 토큰 값은 config에 절대 남기지 않는다
enabled_tools로 범위를 좁혀 시작 — 서버 전체보다 필요한 도구만 먼저 열고 확인해가며 추가한다
Goal·Completion을 주석으로 먼저 적는다 — 설정 의도가 파일에 남으면 다음 사람이 맥락을 이해한다

예시 A — 로컬 STDIO (문서 확인용, 인증 없음)

낯선 라이브러리를 쓸 때마다 공식 문서와 Codex를 번갈아 보는 흐름이 있다면, context7을 붙이면 그 왕복이 줄어든다.

# Goal: 라이브러리 문서를 Codex가 직접 참조하게 한다
# Setup: npx가 설치된 환경, 인터넷 연결
# Constraints: 읽기 전용. 코드 수정은 Codex 자체가 한다.
# Completion: codex mcp add 실행 후 "React 최신 useEffect 규칙 기준으로 수정해" 요청이 되면 완료

codex mcp add context7 -- npx -y @upstash/context7-mcp

ex) codex mcp add context7 -- npx -y @upstash/context7-mcp

- 추가 한 후 접속하면 새로 추가한 context7 mcp가 로드 되고 있는것을 볼 수 있다.

- 로드된 이후 /mcp 입력해보면 잘 설치되어 있음을 확인 가능하다.

- 사용방법 관련해서는 하기 섹션에서 다루지만, 미리 잠깐 살펴보자면, 다음과 같이 명시적으로 context7을 사용하라는 지시를 내려 사용해보았다.

- context7 을 사용하려는 시도와 결과

- 이후 질문들은 우리 글과 상관은 없지만, codex기본기를 다루는 상황에 이력을 공유 하려고 한다. 시간이 없으신분들은 빠르게 넘어가자.

줄별 해설

Goal: "외부 문서를 Codex가 읽는다"가 목적이다. 코드 수정을 자동화하는 게 아니다. 이 구분이 없으면 Codex 행동 범위에 대한 기대가 어긋난다.
npx -y: 매번 최신 버전을 내려받는다. 팀 환경에서는 버전 고정(@버전)을 추가하지 않으면 동일 서버 버전을 보장하기 어렵다.
Constraints 없음: context7은 읽기 전용이므로 Rules 파일에 별도 제한이 없어도 쓰기 사고가 없다. 쓰기 가능한 서버는 이 단계에서 명시해야 한다.
Completion: 실제 요청을 날려봐야 연결이 됐는지 안 됐는지 알 수 있다. "등록 완료" 메시지만으로 동작 확인이 된 건 아니다.

예시 B — Figma HTTP (디자인 조회, OAuth 토큰)

Figma 컴포넌트 목록·레이어 정보를 Codex가 직접 읽어오게 하려면 Figma MCP를 쓴다. Figma는 공식 HTTP 엔드포인트를 제공하므로 로컬에 서버를 설치하지 않아도 된다. STDIO가 로컬 프로세스를 띄우는 방식이라면, HTTP는 SaaS가 운영하는 서버에 직접 붙는 방식이다.

아래 엔드포인트 URL과 인증 방식은 2026년 5월 공식 문서 기준이다. 적용 전 figma.com/developers/mcp에서 최신 가이드를 확인한다.

자연어 설치 (Codex 세션 안에서)

"Figma MCP를 설치해줘"

Codex가 아래 TOML 블록을 ~/.codex/config.toml에 자동으로 추가한다.

이후 안내에 따라 token등록은 별도로 진행 하자.

수동 설치 (TOML 직접 편집)

# Goal: Codex가 Figma 컴포넌트·레이어 정보를 직접 조회하게 한다
# Setup: Figma Personal Access Token → FIGMA_OAUTH_TOKEN 환경변수 설정
# Constraints: 읽기 전용. 파일 수정은 Figma 앱에서 직접 한다.
# Completion: "현재 파일의 컴포넌트 목록 보여줘" 요청이 성공하면 완료

# ~/.codex/config.toml 에 추가
[mcp_servers.figma]
url = "https://mcp.figma.com/mcp"
bearer_token_env_var = "FIGMA_OAUTH_TOKEN"

줄별 해설

url: Figma가 공식 제공하는 HTTP MCP 엔드포인트. SaaS가 직접 운영하므로 로컬에 서버를 설치·실행할 필요가 없다.
bearer_token_env_var: 토큰 값이 아닌 환경변수 이름만 기록한다. config.toml이 저장소에 올라가도 실제 토큰은 노출되지 않는다.
Constraints에 읽기 전용 명시: Figma MCP는 쓰기 도구도 포함할 수 있다. 처음에는 읽기만 허용하고, 필요가 확인된 뒤 enabled_tools를 넓힌다.
CLI 보조 방법: codex mcp add figma --url https://mcp.figma.com/mcp으로 URL만 먼저 등록한 뒤, TOML에서 bearer_token_env_var를 수동 추가하는 방법도 있다.

예시 C — HTTP 범용 패턴 (모든 HTTP MCP 서버에 적용)

Linear, Stripe, Notion 등 "MCP HTTP 지원"을 발표한 SaaS 서비스는 모두 이 패턴으로 등록한다. 서비스마다 엔드포인트 URL과 인증 방식이 다르므로 각 서비스의 공식 MCP 문서를 먼저 확인하는 것이 첫 번째 단계다.

아래 URL과 토큰 형식은 템플릿 예시다. 실제 서비스 공식 MCP 문서에서 정확한 엔드포인트를 확인한 뒤 사용한다.

자연어 설치 (Codex 세션 안에서)

"Linear MCP를 설치해줘"

Codex가 해당 서비스의 MCP 문서를 참조해 TOML 블록을 자동으로 작성한다.

수동 설치 (TOML 범용 템플릿)

# Goal: <서비스>가 제공하는 데이터를 Codex가 직접 조회하게 한다
# Setup: <서비스> API 키 → <TOKEN_ENV_VAR> 환경변수 설정
# Constraints: 필요한 도구만 enabled_tools에 명시한다
# Completion: "<서비스> 데이터 조회" 요청이 성공하면 완료

# ~/.codex/config.toml 에 추가
[mcp_servers.<service-name>]
url = "https://<service-mcp-endpoint>/mcp"
bearer_token_env_var = "<SERVICE_API_TOKEN_ENV>"
enabled_tools = ["<read-tool-1>", "<read-tool-2>"]

필드 해설

url: 서비스가 공식 발표한 HTTP MCP 엔드포인트. 해당 서비스가 공개하지 않았다면 STDIO 방식을 사용한다.
bearer_token_env_var: HTTP MCP의 표준 Bearer 인증 방식. OAuth 방식인 서비스는 서비스 문서를 별도로 확인한다.
enabled_tools: 처음엔 읽기 도구만 열어 동작을 확인한 뒤 범위를 넓힌다. 도구 이름은 서비스 MCP 문서에서 확인한다.
적용 사례: 예시 B의 Figma가 이 패턴 그대로다. Linear, Stripe 등이 HTTP MCP를 공식 발표했거나 준비 중이다.

세 예시 공통 패턴

Goal/Constraints/Completion을 주석으로 먼저 적었다 — 설정 의도가 파일에 남으면 다음 사람이 왜 이렇게 설정했는지 이해한다
인증 정보는 환경변수 이름만 썼다 — 실제 값은 파일에 없다
enabled_tools로 먼저 좁혔다 — 서버가 제공하는 전부를 여는 게 아니라 필요한 것부터 시작한다
STDIO는 로컬 시작, HTTP는 외부 인증 — 두 유형의 구분이 설정 패턴에 드러난다

3. CLI ↔ TOML 매핑 빠른 참조

CLI로 등록한 서버는 자동으로 TOML에 기록된다.

두 방식은 같은 결과다.

팀 저장소에 커밋할 때는 TOML을 직접 관리하고, 빠른 테스트는 CLI를 쓴다.

( 사실 Codex에게 context7 MCP 설치 해줘 라고 하면 한번에 끝날 것 이다. 이를 이론적으로 살펴보고 가는 시간이라고 생각하고 빠르게 넘어가도 무방하다. )

상황	CLI 명령	TOML 설정 (동일 결과)
STDIO (로컬, 인증 없음)	`codex mcp add context7 -- npx -y @upstash/context7-mcp`	`[mcp_servers.context7] command = "npx" args = ["-y", "@upstash/context7-mcp"]`
HTTP + 토큰 (외부 SaaS)	HTTP 서버는 TOML 직접 설정 권장	`[mcp_servers.figma] url = "https://mcp.figma.com/mcp" bearer_token_env_var = "FIGMA_OAUTH_TOKEN"`
프로젝트 공유 (팀)	.codex/config.toml을 저장소에 커밋	`# .codex/config.toml (저장소 루트) [mcp_servers.context7] command = "npx" args = ["-y", "@upstash/context7-mcp@1.2.0"] startup_timeout_sec = 15`

토큰·비밀 값은 절대 TOML에 직접 쓰지 않는다. bearer_token_env_var·env_vars로 환경변수 이름만 기록한다.

4. 권장 MCP 서버 후보 3종

MCP 공식 문서에서 명령 예시까지 확인되는 서버는 context7이다.

GitHub·Playwright는 각 서버 공식 문서와 함께 확인 후 적용한다.

서버 후보	공식 문서에서 확인되는 용도	공식 docs
GitHub	저장소 관리(repository management) - 이슈·PR 관리 (도구명은 README 재확인)	modelcontextprotocol/servers
context7	문서 확인(documentation) - 라이브러리 공식 문서 실시간 참조	Codex MCP 공식 문서
Playwright	브라우저 제어(browser control) - 브라우저 자동화·UI 검증	microsoft/playwright-mcp

세 서버 모두 초보자가 처음 시도해볼 수 있는 공식 예시가 있다. context7은 읽기 전용이라 가장 안전하게 시작할 수 있고, GitHub·Playwright는 토큰 및 실행 환경 확인 후 추가한다.

초보자는 MCP까지만 읽어도 충분하다. Skill·Plugin·CLI는 팀 합류자가 생기거나 반복 작업이 쌓일 때 다시 봐도 늦지 않다.

5. 도구 권한과 타임아웃 제어

MCP 서버를 붙이면 Codex가 사용할 수 있는 도구가 늘어난다. 그래서 등록보다 더 중요한 것이 권한 제어다.

MCP 공식 문서는 공통 옵션으로 startup_timeout_sec, tool_timeout_sec, enabled, required, enabled_tools, disabled_tools를 제시한다. 처음 보는 이름이 많지만, 결국 서버를 켤지, 기다릴 시간을 얼마로 둘지, 어떤 도구만 열지를 정하는 값들이다.

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
startup_timeout_sec = 10
tool_timeout_sec = 60
enabled_tools = ["<tool-name-from-server>"]

startup_timeout_sec의 기본값은 10초, tool_timeout_sec의 기본값은 60초로 문서에 제시되어 있다. 느린 서버를 붙일 때는 타임아웃을 늘릴 수 있지만, 너무 크게 잡으면 Codex 작업이 멈춘 것처럼 보일 수 있다.

초심자용으로 풀면 startup_timeout_sec는 서버가 켜질 때까지 기다리는 시간이고, tool_timeout_sec는 MCP 도구 하나가 응답할 때까지 기다리는 시간이다.

위 enabled_tools 값은 필드 형태를 보여주는 템플릿이다.

실제로는 해당 MCP 서버가 노출하는 도구명을 확인해 넣어야 한다. 공식 문서 기준으로 enabled_tools는 허용 목록이고, disabled_tools는 차단 목록이다.

보수적으로 운영하려면 처음에는 필요한 도구만 enabled_tools로 열고, 실제 사용하면서 넓히는 방식이 낫다.

MCP 서버는 Codex의 행동 반경을 넓힌다. 특히 GitHub, 브라우저, 로그 시스템처럼 외부 상태를 바꿀 수 있는 도구는 처음부터 넓게 열지 말고 필요한 도구만 확인해가며 연다.

MCP 서버를 켜기 전 체크리스트

서버 출처와 설치 명령이 공식 문서나 신뢰 가능한 저장소에서 확인되는가?
서버가 노출하는 도구 목록을 보고 읽기 전용과 쓰기 가능 도구를 구분했는가?
토큰 값 자체가 아니라 환경변수 이름만 config에 남기는가?
응답이 느린 서버를 위해 timeout을 늘리더라도 Codex 전체 작업이 멈추지 않을 범위인가?
문제가 생겼을 때 enabled = false나 disabled_tools로 빠르게 좁힐 수 있는가?

5.5 MCP 운영 3원칙

MCP 서버를 처음 도입하는 팀이 같은 실수를 반복한다. 세 원칙은 그 실수를 예방하는 데서 나왔다.

쓰기 가능 도구는 읽기 가능 도구와 반드시 분리한다 — 같은 서버라도 읽기·쓰기 도구는 다른 환경에서 관리한다
MCP tool result를 사용자 입력과 같은 수준으로 다룬다 — 외부 서버가 반환하는 텍스트는 신뢰 경계 밖에서 온다. 그 안에 지시문이 있으면 Codex가 따른다.
장애 시 빠르게 좁힐 수 있는 구조를 미리 만든다 — enabled = false 또는 disabled_tools로 즉시 차단 가능한 상태를 유지한다

초보자 졸업 체크리스트

☐ context7 MCP 1개 등록해봤다
☐ Skill 1개 직접 작성해봤다 (SKILL.md frontmatter + 지시문)
☐ 토큰을 config에 직접 쓰지 않고 환경변수로 분리했다
☐ 자연어 한 줄 요청 — 원하는 결과가 나왔다
☐ Plugin은 팀 합류자가 생길 때 다시 봐도 늦지 않다

6. Skills — 이론과 실제 설치

MCP를 이해한 뒤에는 Plugin과 Skill의 경계를 잡아야 한다.

Plugins 공식 문서를 풀어 쓰면 Plugin은 GitHub에 올려두면 다른 팀도 설치해서 쓸 수 있는 MCP·Skill 묶음 패키지다. 이 묶음의 정보지가 manifest(plugin manifest — 이름·버전·포함된 MCP 서버 목록을 담은 설정 파일, 앱스토어 앱 정보지에 가깝다)다.

반면 Skills 공식 문서는 Skill을 SKILL.md 파일과 optional scripts, references를 가진 디렉터리로 설명한다.

즉 Skill은 작업 절차를 작성하는 형식이고, Plugin은 그것을 설치 가능한 형태로 배포하는 단위에 가깝다.

개념을 추상 비교표로 외우는 건 잘 안 남는다. 같은 작업을 세 방식으로 구현해보면 차이가 더 빨리 손에 잡힌다.

아래는 "GitHub 이슈 #42에 'bug' 라벨 붙이기"를 MCP·Skill·Plugin 세 방식으로 짠 예시다.

읽는 순서를 MCP → Skill → Plugin으로 잡아두면 차이가 더 잘 보인다. 가장 낮은 층(MCP)에서 시작해서, 그걸 흐름으로 묶고(Skill), 다시 묶음을 배포 가능한 패키지로 감싼다(Plugin).

방식 1 — MCP로 직접 도구 호출

# MCP tool call (코드 또는 Codex 세션에서 직접 호출)
result = codex.tools.call("github_add_label", {
    "repo": "myorg/myrepo",
    "issue": 42,
    "label": "bug"
})

한 번 쓰고 끝낼 작업, 또는 다른 코드 안에서 호출해야 할 때 적합하다. 매번 같은 인자를 입력해야 하므로 반복하면 피곤해진다.

방식 2 — Skill로 작업 흐름 저장

---
name: label-bug
description: 지정된 이슈에 'bug' 라벨을 추가
---
GitHub 이슈 #{{issue_number}}에 'bug' 라벨을 추가해라.

팀에서 자주 반복하는 작업이라면 Skill로 저장한다. 다음에 @label-bug 42처럼 호출만 하면 된다. 내부에서는 결국 MCP 도구를 호출한다.

방식 3 — Plugin으로 묶어 배포

# Plugin manifest 안에 위 GitHub MCP 서버 + label-bug Skill 번들링
# 팀원 누구든 한 줄로 설치
codex plugin install github-tools

팀 전체가 같은 MCP·Skill 조합을 써야 할 때 Plugin으로 묶는다. 설치 한 줄로 MCP 서버 등록과 Skill 배치까지 끝난다.

셋의 관계는 사실 직렬이다. Skill은 안에서 MCP 도구를 호출하고, Plugin은 Skill·MCP를 한 묶음으로 배포한다. 하나만 골라야 하는 게 아니라, 작업 빈도와 공유 범위에 따라 층을 쌓는다.

6.1 Skill은 로컬·저장소 워크플로에 강하다

Skill의 최소 단위는 SKILL.md다. 공식 문서의 최소 포맷은 YAML frontmatter(마크다운 파일 상단에 ---로 감싼 메타데이터 블록 — 이름, 설명 같은 구조적 정보를 기술함)의 name, description과 실제 지시문으로 구성된다.

---
name: skill-name
description: Explain exactly when this skill should and should not trigger.
---

Skill instructions for Codex to follow.

예를 들어 PR description에 breaking changes 항목을 강제로 챙기게 하는 커스텀 Skill은 다음과 같이 쓴다. 추상 "코드 리뷰 스킬" 대신 실제로 검증할 수 있는 항목 한 개에 집중하는 게 핵심이다.

---
name: pr-review-breaking
description: PR description에 breaking changes 섹션 체크
---
이 PR의 description을 확인하고:
1. '## Breaking Changes' 섹션이 없으면 추가 요청
2. breaking change 항목이 있으면 각 항목의 마이그레이션 가이드 확인
3. 없으면 '없음'으로 명시 요청

완료 기준: PR description에 Breaking Changes 섹션 존재 여부 리포트

위 예시는 직접 작성하는 커스텀 Skill 구조를 보여 주는 것이다. openai/skills 공개 저장소에 등록된 Skill이 아니므로 $skill-installer로 설치할 수 없다.

문서에 따르면 Skill 디렉터리는 필수 SKILL.md 외에 선택적으로 scripts/, references/, assets/, agents/openai.yaml을 둘 수 있다.

반복되는 릴리스 노트 작성, 보안 점검, 디자인 QA 같은 작업도 같은 패턴으로 Skill로 만들 수 있다.

실습용 Skill 3종

Skill 이름	한 줄 용도	공식 docs
`gh-fix-ci`	GitHub Actions CI 실패 자동 분석·수정 제안	openai/skills
`gh-address-comments`	현재 브랜치 PR 리뷰 댓글 일괄 처리	openai/skills
`security-best-practices`	Python · JS · Go 코드 보안 점검 및 개선 제안	openai/skills

※ k-skill 31개(NomaDamas/k-skill)는 Claude Code / OpenClaw 타깃이므로 Codex 비대상. Claude Code의 Plugin · Skill 생태계는 필자의 Claude Code Plugin · Skill 가이드를 참고.

6.2 공개 Skill 설치 — 자연어와 수동 명령

OpenAI 공식 openai/skills 저장소에는 큐레이션된 Skill이 있다. 설치 명령은 $skill-installer를 사용한다. Codex 세션 안에서 자연어로 요청해도 된다.

자연어 설치 (Codex 세션 안에서)

"gh-fix-ci 스킬 설치해줘."

Codex가 $skill-installer 명령을 대신 실행해 Skill을 설치한다. 설치 후 Codex를 재시작해야 새 Skill이 인식된다.

ex) gh-fix-ci 스킬 설치해줘

- 중간에 네트워크 오류가 있었는데 의도를 파악하고 다른 방법으로 설치 시도 하는 과정도 공유

수동 설치 (CLI)

# openai/skills 큐레이션 목록에서 이름으로 설치
$skill-installer gh-fix-ci

# GitHub URL로 직접 지정 (서드파티 저장소 등)
$skill-installer install https://github.com/<owner>/<repo>/tree/main/<skill-path>

큐레이션 Skill: 이름만으로 설치 가능. openai/skills/skills/.curated/에 등록된 목록만 이름으로 찾는다. 목록에 없는 이름을 지정하면 설치에 실패한다.
커뮤니티 Skill: ComposioHQ/awesome-codex-skills에서 추가 목록을 찾을 수 있다.
오픈 스탠더드: agentskills.io는 Agent Skills 공개 표준 스펙 사이트다. 특정 플랫폼에 종속되지 않는 Skill 포맷의 기준을 정의한다.

설치 전에 목록 먼저 보기

Codex 세션 안에서 자연어로 목록을 요청하면 $skill-installer가 큐레이션 목록을 나열해 준다.
이름을 확인한 뒤 설치하는 게 실패 없이 설치하는 가장 확실한 방법이다.

"설치 가능한 Skills 목록 보여줘."

ex) 설치 가능한 Skills 목록 보여줘.

- pdf 플러그인 설치해줘

7. Plugins — 배포와 실제 설치

7.1 Plugin은 배포와 조합에 강하다

Plugin은 Skill 하나만 담을 수도 있지만, app integration이나 MCP server까지 함께 묶을 수 있다.

공식 문서는 Plugin 호출 방식을 implicit invocation과 explicit invocation으로 나눈다.

implicit invocation은 사용자가 원하는 결과를 자연어로 설명하면 Codex가 등록된 Skill·Plugin 중 적절한 걸 자동 선택하는 방식이다.

explicit invocation은 @plugin-name 또는 @skill-name 형식으로 사용자가 직접 지정하는 방식이다. Skill이 두 개 이상 겹치는 환경에서는 explicit이 결과 예측에 유리하다.

비활성화도 설정으로 제어할 수 있다.

[plugins."gmail@openai-curated"]
enabled = false

팀에서 특정 플러그인을 임시로 막아야 할 때 삭제보다 비활성화가 더 관리하기 쉽다. 나중에 다시 켤 수 있고, 왜 꺼두었는지도 설정 파일에서 추적할 수 있다.

Plugin이 빛을 보는 순간

새로 합류한 팀원이 첫 번째 PR을 올리기 전 Codex 환경을 갖추는 시간을 줄이고 싶을 때.
조직 단위로 동일한 MCP·Skill 묶음을 쓰게 만들어 결과 편차를 줄이고 싶을 때.
사내 도구(Jira, Notion, 사내 wiki)용 MCP 서버와 그걸 쓰는 Skill을 한 번에 배포하고 싶을 때.

비교 — Skill 호출: 암묵적 vs 명시적

❌ 이렇게 하면

codex "릴리스 노트 작성해줘"
# Skill이 여러 개일 때 어느 Skill을
# 써야 할지 Codex가 추측해야 한다.
# 결과가 매번 달라질 수 있다.

✅ 이렇게 하면

codex "@gh-fix-ci PR #42 CI 실패 수정해줘"
# @로 Skill을 명시하면 항상 같은
# 절차로 실행된다. 결과가 일관된다.

Skill이 두 개 이상 등록된 환경에서는 @skill-name으로 명시하는 것이 암묵적 선택보다 결과를 예측하기 쉽다.

Plugin	한 줄 용도	공식 docs
`gmail@openai-curated`	Gmail 연동 (공식 예시)	Codex Plugins 공식 문서
`github-tools` (사내 템플릿)	GitHub MCP + PR Skill 번들 사내 배포 (가상 예시)	—
기타 curated Plugin	OpenAI curated Plugin 목록 참고	Codex Plugins 공식 문서

7.2 Plugin 설치 — 자연어와 수동 명령

Gmail, Slack, Figma, Playwright, Sentry는 Codex에 기본 탑재되어 있어 별도 설치 없이 바로 쓸 수 있다. 그 외 Plugin은 아래 명령으로 설치한다.

자연어 설치 (Codex 세션 안에서)

"github-tools 플러그인 설치해줘."

Codex가 codex plugin install 명령을 대신 실행한다.

수동 설치 (CLI)

# 공식 큐레이션 Plugin 설치
codex plugin install gmail@openai-curated
codex plugin install github-tools

# 커뮤니티 마켓플레이스 등록 후 설치
codex plugin marketplace add owner/repo [--ref main]
codex plugin install <plugin-name> --source <marketplace>

@openai-curated: OpenAI가 공식 관리하는 Plugin 소스. 신뢰 경계가 명확하다.
marketplace add: 팀 내부나 커뮤니티 저장소를 소스로 등록한 뒤 설치할 수 있다.
비활성화: [plugins."gmail@openai-curated"] enabled = false로 삭제 없이 끌 수 있다.

MCP vs CLI — 2026년 커뮤니티 정리

stdio MCP(로컬 프로세스)는 대부분 CLI + Skill로 대체 가능하다
HTTP MCP(원격 서버)는 인증 중앙화·텔레메트리 필요 시 게임 체인저다
"원격 실행은 MCP, 로컬 실행은 Skills" — @m00nlygreat (GeekNews, 2026-03)

8. 정리와 의사결정 트리

한 줄 의사결정 트리

외부 도구 1회만? → MCP | 같은 작업 반복? → Skill | 팀 전체 배포? → Plugin | gh · aws · kubectl 있음? → 그냥 CLI

MCP, Plugin, Skill은 서로 경쟁하는 개념이 아니다.

Codex 확장을 세 층으로 나누면 이해가 쉽다.

셋을 동시에 쓰는 경우
팀 개발 환경을 예로 들면 GitHub MCP + Jira MCP 두 도구를 묶어 Plugin으로 배포하고, PR 리뷰 절차를 Skill로 저장해두면 팀원 전체가 동일한 환경을 유지할 수 있다. MCP는 도구 연결, Plugin은 환경 복제, Skill은 작업 방식 표준화라는 세 문제를 각각 담당한다.

해야 할 일	먼저 볼 것	이유
외부 문서나 외부 도구를 붙인다	MCP server	Codex가 호출할 도구 접근 통로가 필요하다
반복 작업 절차를 저장한다	Skill	지침, 참고자료, 스크립트를 한 디렉터리에 묶을 수 있다
여러 팀원에게 확장 묶음을 배포한다	Plugin	Skills, apps, MCP servers를 설치 가능한 단위로 묶을 수 있다

도입 순서는 단순하게 잡는다. 먼저 context7처럼 읽기 전용 MCP 서버를 하나 붙인다. 그다음 팀에서 반복되는 작업을 Skill로 정리한다. 여러 사람이 같은 묶음을 써야 할 때만 Plugin 배포를 고려한다.

다음 편에서는 Codex를 실제 팀 운영에 붙일 때 생기는 문제를 다룰 예정이다. 설정 파일을 만들고, 도구를 붙이고, Skill을 늘리는 것보다 더 어려운 일은 "어떤 권한과 검증 기준으로 운영할 것인가"를 정하는 일이다.

다음 글 예고: Part 6 — Codex 자동화

반복 작업을 Codex로 자동화하는 실전 패턴
스케줄링, 훅, 이벤트 기반 트리거 설계
CI/CD 파이프라인과 Codex 통합 사례

자주 묻는 질문

MCP는 Codex에서 어떤 역할을 하나?

MCP는 Codex가 저장소 밖의 도구나 데이터 소스와 연결되는 통로다. 이슈 트래커, 문서, 브라우저, 내부 API 같은 외부 맥락을 작업에 포함할 때 필요하다.

Plugins와 Skills는 어떻게 구분하면 되나?

Plugin은 여러 기능이나 도구 묶음을 제공하는 확장 단위에 가깝고, Skill은 특정 작업 절차나 실행 패턴을 재사용하기 위한 지침 단위로 이해하면 쉽다.

MCP 서버를 추가할 때 가장 조심할 점은 무엇인가?

인증 정보, 네트워크 접근, 사용 가능한 도구 범위, 타임아웃을 확인해야 한다. 외부 도구 연결은 편리하지만 권한 경계가 넓어질 수 있기 때문이다.

참고 자료

작성일: 2026년 5월 6일

분석 범위: OpenAI Codex 공식 MCP, Plugins, Skills 문서와 해당 run의 evidence.json 기준

기능과 설정 키는 변경될 수 있으므로 실제 적용 전 공식 문서를 다시 확인해야 한다.

Codex CLI 입문(4) : AGENTS.md와 Rules 설정 방법 - Codex에게 팀 규칙과 권한을 알려주는 방법

갓대희 — Mon, 11 May 2026 19:00:07 +0900

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

Codex를 혼자 쓸 때는 프롬프트에 규칙을 매번 적어도 어느 정도 버틸 수 있다.

하지만 팀 프로젝트에서는 어떨까? "테스트는 어떤 명령으로 돌릴까", "수정하면 안 되는 파일은 어디일까", "위험한 명령은 어디까지 허용할까" 같은 기준이 사람마다 다르면 Codex의 결과도 흔들린다.

이번 글에서는 Codex에 팀 규칙을 남기는 두 가지 방법을 정리해보려 한다.

하나는 저장소 안에 두는 AGENTS.md(프로젝트 루트에 두면 Codex가 자동으로 읽는 행동 규칙 파일)이고,

다른 하나는 명령어 실행 정책을 다루는 .rules 파일이다.

쉽게 말해 AGENTS.md는 "이 프로젝트에서는 이렇게 일해줘"라고 적는 설명서이고, .rules는 "이 명령은 바로 실행해도 되고, 이 명령은 먼저 확인해야 해"라고 정하는 안전장치에 가깝다.

OpenAI Codex 개발자 시리즈

Part 1: CLI 빠른 시작 Part 2: 핵심 개념 4가지 Part 3: Subagents · Workflows Part 4: AGENTS.md · Rules (현재 글) Part 5: MCP · Plugins · Skills Part 6: 자동화 Part 7: 마이그레이션 Part 8: 슬래시 명령어 정리(예정)

이 글에서 다루는 범위는 AGENTS.md, .rules, config.toml의 핵심 설정까지다. 외부 도구 연결, 플러그인, 스킬 구성은 다음 편에서 따로 다룬다.

이 편에서 처음 나오는 용어 미리 보기

AGENTS.md: 프로젝트 전체에 적용되는 규칙 문서. Codex가 프로젝트를 열 때 자동으로 읽는다. → 비유: 팀 위키/사규집
Rules (.rules): 특정 셸 명령을 허용·확인·차단하는 규칙 파일. "이 명령은 바로 실행해도 돼, 이 명령은 먼저 물어봐"처럼 실행 정책을 선언한다. → 비유: 출입 보안 게이트
config.toml: 권한 정책·샌드박스 설정을 담은 Codex 설정 파일. 어떤 모델을 쓸지, 승인을 어떻게 받을지 같은 기본 환경을 정한다. → 비유: 권한 카드 발급 설정
prefix_rule: 명령어 앞부분(prefix) 패턴을 기준으로 허용·차단 여부를 결정하는 Rules 함수. "git"으로 시작하는 명령만 허용하거나 "rm -rf"를 막는 식으로 쓴다.

지금 바로 따라 할 수 있는 가장 작은 AGENTS.md

AGENTS.md는 자연어 지침 파일이라 꼭 영어로 쓸 필요가 없다. 팀이 한국어로 일한다면 처음부터 한국어로 쓰는 편이 더 읽기 쉽다. 아래 내용을 프로젝트 루트에 AGENTS.md로 저장해 보자.

# AGENTS.md

## 빌드와 테스트
- 작업을 완료했다고 말하기 전에 `npm test`를 실행한다.

## 수정 금지
- `.env`, `.env.local`은 읽거나 수정하지 않는다. API 키가 들어 있을 수 있다.

중요한 점은 영어 표현이 아니라 명확한 완료 조건과 금지 경계다.

왜 규칙을 파일로 관리해야 하는가
AGENTS.md 쉽게 이해하기
AGENTS.md와 로컬 메모리의 차이
Rules 파일로 명령어 제어하기
config.toml 핵심 설정
여러 규칙이 충돌할 때
팀에 적용하는 방법
정리와 Part 5 예고

개념	한 줄 설명	언제 쓰나
`AGENTS.md`	팀 규칙을 자연어로 적어 두는 프로젝트 지침 파일	빌드·테스트 명령, 금지 디렉토리, 코딩 컨벤션을 Codex에 전달할 때
`.rules`	명령어 실행 정책을 선언하는 파일 (허용·확인·차단)	위험한 명령은 막고, 안전한 명령은 자동 허용할 때
`config.toml`	모델·승인 정책·샌드박스 수준 등 기본 실행 환경 설정 파일	팀 전체 실행 환경을 통일하거나 CI 자동화 환경을 구성할 때
로컬 메모리	개인 작업 맥락과 선호를 세션 간에 이어주는 보조 기능	나만 반복 사용하는 워크플로·개인 취향을 저장할 때

1. 왜 규칙을 파일로 관리해야 하는가

핵심: 채팅에 적은 규칙은 세션이 끝나면 사라진다. 저장소 파일로 옮겨야 다음 세션·다음 팀원에게 같은 기준이 전달된다.

팀에서 Codex를 쓰기 시작하면 처음에는 프롬프트가 규칙 저장소처럼 쓰인다. "테스트 먼저 돌려라", "이 디렉토리는 건드리지 마라", "PR 설명은 이 형식으로 써라" 같은 지시를 매번 대화에 붙인다. 문제는 그 방식이 오래가지 않는다는 점이다.

OpenAI의 Customization 공식 문서에서는 AGENTS.md를 저장소와 함께 이동하는 지속적인 프로젝트 가이드로 설명한다.

이 파일은 Codex가 프로젝트 작업 지침으로 참고하는 규칙층이므로, 반복되는 리뷰 피드백을 한 번의 대화가 아니라 저장소 규칙으로 바꿀 수 있다.

핵심은 "프롬프트를 길게 쓰는 것"이 아니다. 팀이 반복해서 지적하는 규칙만 파일로 올려서 다음 세션과 다음 팀원에게 같은 기준이 적용되게 만드는 것이다.

예를 들어 백엔드 팀이 pytest를 기본 검증 명령으로 쓰고, 프론트엔드 팀이 pnpm test와 pnpm lint를 함께 요구한다고 하자. 이 규칙이 채팅에만 있으면 새 세션마다 누락된다.

반대로 저장소의 AGENTS.md에 적어 두면 Codex가 같은 프로젝트 안에서 일할 때 반복해서 참고할 수 있다.

2. AGENTS.md 쉽게 이해하기

핵심: AGENTS.md는 Codex가 프로젝트를 열 때 자동으로 읽는 팀 규칙 파일이다. 처음엔 10줄 이내로 시작하면 충분하다.

2.1 세 위치를 구분한다

공식 문서 기준으로 AGENTS.md는 크게 세 위치에 둘 수 있다.

Customization 문서와 AGENTS.md 공식 가이드는 전역 파일, 저장소 루트 파일, 하위 디렉토리 파일을 구분한다.

위치	적용 범위	적기 좋은 내용
`~/.codex/AGENTS.md`	모든 저장소에 걸친 개인 선호	응답 길이, 리뷰 스타일, 기본 커뮤니케이션 방식
`AGENTS.md`	저장소 전체의 팀 규칙	빌드/테스트 명령, 리뷰 기준, 프로젝트 구조
`packages/api/AGENTS.md` 같은 하위 파일	해당 디렉토리 작업	모듈별 금지 사항, 로컬 테스트 명령, 도메인 규칙

전역 파일은 개인 취향, 루트 파일은 팀 규칙, 하위 파일은 특정 영역 규칙이다. 여기서 전역은 운영체제 전체 설정이 아니라 Codex 홈 디렉토리의 공통 지침층을 뜻한다.

루트는 현재 프로젝트의 가장 바깥 폴더다. 팀에서 공유해야 하는 내용은 개인 전역 파일이 아니라 저장소 안의 AGENTS.md에 둔다.

Codex 지침 체인 (세션 시작 시 순서대로 로드)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ~/.codex/AGENTS.md          ← 1단계: 전역 (개인 선호)
         │
         ▼
  {repo}/AGENTS.md            ← 2단계: 저장소 루트 (팀 규칙)
  (같은 위치에 AGENTS.override.md 있으면 대체)
         │
         ▼
  {subdir}/AGENTS.md          ← 3단계: 하위 디렉토리 (모듈별)
  (같은 위치에 AGENTS.override.md 있으면 대체)

─────────────────────────────────────────
  config.toml                 ← 모델·승인·샌드박스 런타임 설정
  .rules                      ← 셸 명령 허용/차단 정책
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

같은 위치에 AGENTS.override.md가 있으면 그 디렉토리의 AGENTS.md는 무시되고 override 파일만 지침으로 포함된다.

AGENTS.override.md는 팀 전체 AGENTS.md 규칙 중 특정 폴더에서만 일부를 덮어쓸 때 쓰는 로컬 예외 파일이라고 보면 된다. 디렉토리마다 최대 한 개의 지침 파일만 포함되므로, 임시로 강한 예외가 필요할 때는 AGENTS.override.md를 쓰고 끝나면 제거하는 방식이 안전하다. Codex는 세션이나 실행을 시작할 때 지침 체인을 만들기 때문에, 지침 파일을 바꾼 뒤 현재 세션에 바로 반영되지 않으면 Codex를 다시 시작하거나 새 명령으로 확인한다.

예를 들어 계약직 개발자에게 tests/integration/만 접근을 허용하고 나머지 테스트는 원래 규칙대로 막을 때 이렇게 쓴다.

# tests/AGENTS.override.md
# 원본 AGENTS.md: "tests/ 수정 금지"
# 이 파일이 있으면 tests/ 안에서는 아래 규칙만 적용된다

## 덮어쓰기 규칙 (feature/contractor-scope 브랜치용)
- tests/integration/ 하위 파일은 수정 가능하다.
- tests/unit/ 하위 파일은 원래 규칙대로 수정 금지.
- 작업 완료 후 이 파일을 삭제하고 PR을 올린다.

AGENTS.md는 길수록 Codex가 잘 따를까?

좋은 시스템 프롬프트는 자세할수록 좋다는 경험을 가진 개발자라면 AGENTS.md도 길수록 낫다고 느낀다.

실제로는 반대다.

날카로운 규칙 10줄 > 위키 dump 100줄. 파일이 길어질수록 중요한 규칙이 잡음에 묻히고, Codex가 읽어야 할 토큰도 늘어난다. 공식 AGENTS.md 가이드도 "중요한 지시사항만으로 시작하라"고 명시한다.

그래도 올려야 하는 것은 딱 세 가지다: ① 반복해서 리뷰에서 지적되는 패턴, ② 새 세션에서 Codex가 놓치는 프로젝트 구조, ③ 실수하면 되돌리기 어려운 금지 명령. 그 외는 프롬프트에서 그때그때 말하면 된다.

2.2 무엇을 적어야 효과적인가

공식 문서는 AGENTS.md에 빌드와 테스트 명령, 리뷰 기대사항, 저장소별 컨벤션, 디렉토리별 지시사항을 적는 것을 권장한다. 동시에 "중요한 지시사항만으로 시작하라"는 방향도 함께 제시한다(Customization 문서).

그래서 첫 버전부터 회사 위키 전체를 옮길 필요는 없다. Codex가 자주 틀리는 부분, 사람이 반복해서 리뷰하는 부분, 프로젝트 구조상 반드시 지켜야 하는 부분만 먼저 적으면 된다. 처음 AGENTS.md를 만들 때 어디서부터 시작해야 할지 막막하다면 /init 명령을 써볼 수 있다. Codex가 저장소 구조를 읽고 AGENTS.md 초안을 생성해준다.

# AGENTS.md

## 프로젝트 규칙
- 프론트엔드 명령은 `pnpm`을 사용한다. `npm install`은 사용하지 않는다.
- 작업을 완료했다고 말하기 전에 `pnpm lint`와 `pnpm test`를 실행한다.
- 변경 범위는 요청받은 기능이나 버그 수정에 한정한다.
- `generated/` 아래 파일은 직접 편집하지 않는다.

## 백엔드
- API 코드는 `apps/api`에 둔다.
- 백엔드 변경 후에는 `pytest tests/api`를 실행한다.
- 데이터베이스 마이그레이션은 커밋 전에 검토를 받아야 한다.

## 프론트엔드
- UI 컴포넌트는 `apps/web/components`에 둔다.
- 일회성 색상값보다 기존 디자인 토큰을 우선 사용한다.
- 아이콘만 있는 버튼에는 접근성 라벨을 추가한다.

이 예시는 일부러 짧다. 좋은 AGENTS.md는 긴 문서가 아니라 작업 중 판단이 갈리는 지점을 줄이는 문서다. 특히 "하지 말아야 할 일"과 "완료라고 말하기 전에 돌릴 명령"을 명확히 적으면 효과가 크다.

내용	어디에 둘까	이유
이번 요청에서만 필요한 제약	프롬프트	다음 작업까지 남길 필요가 없다
팀이 항상 지켜야 하는 빌드·테스트·리뷰 규칙	`AGENTS.md`	저장소와 함께 공유되고 반복 적용된다
개인 말투, 선호하는 설명 방식, 반복 작업 습관	전역 `AGENTS.md` 또는 메모리	팀 규칙과 개인 선호를 섞지 않는다
특정 명령을 허용·확인·차단하는 실행 정책	Rules	자연어 지침이 아니라 명령 실행 경계를 제어한다

비교 — 효과 있는 AGENTS.md 규칙 vs 무시되기 쉬운 규칙

❌ 이렇게 하면

## 규칙
- 좋은 코드를 작성한다.
- 문제를 만들지 않는다.
- migrations/는 중요하다.

✅ 이렇게 하면

## 빌드와 테스트
- 작업을 완료했다고 말하기 전에 `pytest`를 실행한다.

## 수정 금지
- `migrations/`는 커밋 전에 DBA 검토가 필요하다.
  직접 수정하면 데이터 손실 위험이 있다.

이유 없는 금지("문제 만들지 않는다")는 다음 세션에서 무시되기 쉽다. 완료 조건과 금지 이유를 함께 적어야 Codex가 예외 상황에서도 의도를 지킨다.

2.3 언제 업데이트해야 하는가

처음 만든 AGENTS.md는 완성본이 아니라 출발점이다. 공식 문서는 세 가지 상황에서 내용을 추가하라고 안내한다(Customization 문서). Codex가 잘못된 가정을 반복할 때, 너무 많은 문서를 읽느라 헤맬 때, PR 리뷰에서 같은 피드백이 반복될 때다.

초심자 입장에서는 이렇게 기억하면 쉽다. "한 번만 말하면 되는 내용"은 프롬프트에 쓰고, "다음에도 또 지켜야 하는 내용"은 AGENTS.md에 올린다.

다만 문서가 커질수록 Codex가 읽어야 할 내용도 늘어난다. 공식 가이드는 합쳐진 지침 크기가 project_doc_max_bytes(Codex가 읽을 프로젝트 문서의 최대 바이트 한도) 한도에 닿으면 더 이상 추가하지 않는다고 설명하고, AGENTS.md 가이드의 기본 설명에서는 32 KiB를 기준값으로 안내한다. 그래서 규칙은 이유가 분명한 것만 넣고, 오래된 규칙은 주기적으로 걷어낸다.

AGENTS.md로 옮길지 판단하는 체크리스트

같은 피드백을 세 번 이상 반복해서 말하고 있는가?
새 세션에서도 반드시 지켜야 하는 팀 규칙인가?
규칙을 지키지 않으면 테스트 실패, 보안 위험, 배포 사고로 이어질 수 있는가?
반대로 오래된 도구명, 사라진 폴더, 더 이상 쓰지 않는 명령은 없는가?

또 하나 중요한 점은 AGENTS.md가 모든 문제를 혼자 해결하는 파일은 아니라는 점이다. Codex 문서에는 메모리, 스킬, MCP, 서브에이전트처럼 역할이 다른 확장 기능도 따로 설명되어 있다. 프로젝트 규칙은 AGENTS.md, 반복 워크플로는 스킬, 외부 시스템 연결은 MCP처럼 역할을 나눠 생각하면 된다.

2.4 모듈식으로 나누는 법

여기서 말하는 모듈식 구성은 AGENTS.md 안에서 다른 문서를 import한다는 뜻이 아니다. 공식 AGENTS.md 가이드가 설명하는 방식은 적용 범위에 맞게 지침 파일을 가까운 디렉토리에 두는 것이다. 저장소 전체 규칙은 루트 AGENTS.md에 두고, 특정 폴더에만 필요한 규칙은 그 폴더의 AGENTS.md 또는 AGENTS.override.md에 둔다.

상황	권장 위치	이유
공통 빌드·테스트 명령	`{repo-root}/AGENTS.md`	저장소 어디에서 작업하든 적용되는 규칙
프론트엔드만의 UI 규칙	`web/frontend/AGENTS.md`	해당 폴더 아래 작업에만 적용
특정 팀의 임시 우선 규칙	`하위 폴더/AGENTS.override.md`	같은 위치의 AGENTS.md 대신 override 파일만 포함

기본값 그대로 사용하면 된다. 파일명 커스텀이나 용량 한도 조정은 처음에는 필요하지 않다.

더 알아보기 — 파일명 커스텀과 한도 조정

이미 팀에서 TEAM_GUIDE.md 같은 파일을 쓰고 있다면, 아래처럼 fallback 이름으로 등록할 수 있다. 설정을 바꾼 뒤에는 Codex를 재시작해야 반영된다.

# ~/.codex/config.toml
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
project_doc_max_bytes = 65536

처음부터 한도를 키우는 방식은 좋은 기본값이 아니다. 한도 상향은 중요한 지침이 잘릴 때 검토하고, 그 전에는 오래된 규칙 삭제와 폴더별 분리를 먼저 시도한다.

또 하나 자주 헷갈리는 점이 있다. @rules/foo.md나 ./rules/foo.md를 AGENTS.md 안에 적는다고 해서 그 파일이 자동으로 합쳐지는 것은 아니다.

공식 문서가 설명하는 자동 발견 대상은 AGENTS.md, AGENTS.override.md, 그리고 설정에 등록한 fallback 파일명이다. 한 번만 참고할 파일은 프롬프트에 경로를 직접 쓰고, 반복해서 적용할 규칙은 가까운 AGENTS.md로 승격하는 편이 명확하다.

2.5 AGENTS.md 스타터 템플릿 4가지

빈 파일 앞에서 "뭘 써야 하지?"가 막히는 게 가장 흔하다.

바로 복붙해서 쓸 수 있는 템플릿 4가지를 준비해봤다.

예시 A는 개인 프로젝트, B는 작은 풀스택 팀, C는 모노레포, D는 Next.js App Router 팀 프로젝트 기준이다.

예시들이 반복해서 보여주는 섹션 패턴

빌드와 테스트: 완료라고 말하기 전에 반드시 돌릴 명령
코드 스타일 / 규칙: 리뷰에서 반복 지적된 것만 — 취향 수준은 넣지 않는다
수정 금지 또는 금지 규칙: 실수하면 되돌리기 어려운 파일과 이유
각 규칙에 이유: "하지 마" 한 줄보다 "하지 마 — 이유" 형식이 Codex가 예외 상황을 더 잘 판단한다

예시 A — 개인: Node.js 프로젝트 혼자 쓸 때

처음 AGENTS.md를 만들 때 가장 흔한 실수는 너무 많이 쓰는 것이다.

반복 지적된 것 3가지, 금지 파일 2가지로 시작한다.

나머지는 나중에 추가한다.

# AGENTS.md

## 빌드와 테스트
- 작업을 완료했다고 말하기 전에 `npm test`를 실행한다.
- `npm install`은 자동으로 실행하지 않는다. 새 패키지가 필요하면
  패키지 이름과 이유를 먼저 설명하고 확인을 기다린다.

## 코드 스타일
- 새 비동기 코드는 `.then()` 체인보다 `async/await`로 작성한다.
- 커밋될 코드에 `console.log`를 남기지 않는다. `lib/log.ts`의 logger를 사용한다.

## 수정 금지
- `package-lock.json`은 직접 편집하지 않는다. `npm install`로만 갱신한다.
- `.env`, `.env.local`은 읽거나 수정하지 않는다.

직접 해보자

아래 내용을 그대로 복붙해서 프로젝트 루트에 AGENTS.md 파일을 만들어 보자.

Codex가 다음 작업부터 테스트를 자동으로 돌리고, 지정한 파일은 건드리지 않는다.

# AGENTS.md

## 빌드와 테스트
- 작업을 완료했다고 말하기 전에 `npm test`를 실행한다.

## 수정 금지
- `.env`, `.env.local`은 읽거나 수정하지 않는다.

줄별 해설

빌드와 테스트 — "완료 전에 실행": 이 문구가 없으면 Codex가 테스트를 돌리지 않고 완료라고 말한다. 완료 조건을 명시하는 게 핵심이다.
npm install 자동 실행 금지: 패키지가 추가되면 package-lock.json이 바뀌고 빌드 환경이 달라진다. 어떤 패키지인지 사람이 먼저 확인하게 강제하는 규칙이다.
수정 금지 — .env: 이 섹션이 없으면 Codex가 환경 파일을 읽거나 수정할 수 있다. API 키나 DB 주소가 담긴 파일은 반드시 명시한다.
규칙 자체는 10줄 안팎: 처음엔 한국어로 짧게 시작한다. 실제 리뷰에서 "또 이거야"가 나올 때만 규칙을 추가한다.

Python 프로젝트를 쓴다면 — pytest 기반 예시 보기

# AGENTS.md

## 빌드와 테스트
- 작업을 완료했다고 말하기 전에 `pytest`를 실행한다.
- 데이터베이스 마이그레이션은 자동 실행하지 않는다. 먼저 마이그레이션 파일을
  보여주고 검토 확인을 기다린다.

## 코드 스타일
- 모든 함수 시그니처에 타입 힌트를 작성한다.
- `except:`만 단독으로 쓰지 않는다. 처리할 예외 타입을 명확히 적는다.

## 수정 금지
- `migrations/` 파일은 커밋 전에 수동 검토가 필요하므로 자동 수정하지 않는다.
- `.env`, `.env.local`은 읽거나 수정하지 않는다.

예시 B — 소팀: 프론트엔드(Node) + 백엔드(Python) 한 저장소

프론트엔드는 Node.js, 백엔드는 Python·FastAPI인 흔한 풀스택 구조다. 팀원마다 다른 명령을 쓰면 Codex도 흔들린다. 어느 폴더에서 어떤 명령을 써야 하는지 지도를 먼저 그려준다.

# AGENTS.md

## 프로젝트 구조
- 프론트엔드: `apps/web/` (Next.js, pnpm)
- 백엔드: `apps/api/` (FastAPI, pytest)
- 공유 타입: `packages/types/`

## 빌드와 테스트
- 프론트엔드 변경: `pnpm --filter web lint && pnpm --filter web test`
- 백엔드 변경: `pytest apps/api/tests/ -q`
- 공유 타입이나 양쪽에 걸친 변경을 건드렸다면 프론트엔드와 백엔드 검증을 모두 실행한다.

## 코드 스타일
- 프론트엔드: 기존 디자인 토큰을 사용한다. 컴포넌트 안에 일회성 hex 색상값을 넣지 않는다.
- 백엔드: 모든 API 요청/응답 스키마는 Pydantic 모델로 정의한다.
- 공통: TODO 주석을 남길 때는 연결된 이슈 번호를 함께 적는다.

## 수정 금지
- `apps/api/migrations/`는 DBA 검토가 필요하므로 자동 수정하지 않는다.
- `packages/types/`는 양쪽 팀 계약에 해당하므로 변경 전에 영향 범위를 설명한다.

줄별 해설

프로젝트 구조 섹션: Codex가 어느 폴더에서 어떤 명령을 써야 할지 아는 지도다. 없으면 웹 명령을 API에 적용하거나 반대가 된다.
테스트 명령에 "cross-cutting changes" 조건: "항상 둘 다 돌려라"고 적으면 백엔드만 건드려도 프론트 테스트가 불필요하게 돈다. 언제 둘 다 돌릴지 조건을 명시하는 게 낫다.
코드 스타일 영역 분리: 프론트엔드/백엔드/공통으로 나눠야 Codex가 잘못된 영역에 규칙을 적용하지 않는다.
packages/types/ 수정 주의: 팀 경계를 넘는 파일은 항상 명시해야 한다. 적지 않으면 Codex가 단독으로 수정할 수 있다.

예시 C — 모노레포: 루트 공통 + 모듈별 분리

팀 규모가 커진 다음에 보면 된다 — 처음 도입이라면 예시 A나 D부터 시작하자.

팀이 커지면 루트 하나에 모든 규칙을 다 넣으면 금방 커진다. "이 규칙이 저장소 전체에 적용되는가, 아니면 특정 앱에만 적용되는가"를 기준으로 나눠서 둔다.

# AGENTS.md  ← 저장소 루트 (어디서 작업하든 적용)

## 공통 규칙
- 작업을 완료했다고 말하기 전에 `pnpm -r lint`를 실행한다.
- 패키지 버전은 직접 올리지 않는다. 버전 변경이 필요하면 `pnpm changeset`을 사용한다.
- `packages/ui/` 또는 `packages/types/`를 변경했다면, 변경 후 모든 `apps/` 소비자에서
  타입 오류가 없는지 확인한다.

## 모노레포 구조
- apps/web: Next.js 앱 (`pnpm test`, `pnpm lint`)
- apps/api: Node.js Express API (`npm test`)
- packages/ui: 디자인 시스템. UI 컴포넌트의 원본이다.
- packages/types: 공유 TypeScript 타입. 모든 앱에 영향을 줄 수 있다.

# apps/web/AGENTS.md  ← 프론트엔드 전용 (이 폴더 안 작업에만 적용)

## 테스트 명령
- 단위 테스트: `pnpm test`
- E2E 테스트: 인증 흐름이나 라우팅이 바뀐 경우에만 `pnpm test:e2e`를 실행한다.

## 수정 금지
- `src/components/ui/`는 `packages/ui`에서 동기화되는 폴더다. 원본 패키지를 수정한다.
- `public/assets/`의 정적 파일은 디자인팀 확인 없이 바꾸지 않는다.

줄별 해설

루트에는 공통 규칙만: "어디서 작업하든 적용되는 것"만 루트에 둔다. 특정 앱 규칙은 해당 폴더 AGENTS.md로 내린다. 루트가 길어지면 정작 중요한 규칙이 묻힌다.
pnpm changeset 명시: 버전 관리 도구를 적지 않으면 Codex가 package.json을 직접 수정한다. 도구 이름과 이유를 함께 적어야 한다.
apps/web E2E 조건: "항상 돌려라"보다 "언제 돌려라"가 더 실용적이다. 조건 없이 쓰면 매 변경마다 E2E가 돌 수 있다.
src/components/ui/ 수정 금지 이유: 소스 패키지가 따로 있는데 여기를 직접 고치면 다음 동기화에서 덮어씌워진다. 이유를 적어야 Codex가 왜 금지인지 이해한다.

예시 A~C에서 반복된 패턴

빌드와 테스트에 완료 조건을 명시했다 — "돌려라"보다 "완료라고 말하기 전에 돌려라"가 낫다
금지 규칙에 이유를 같이 적었다 — 이유 없는 금지는 다음 세션에서 무시될 수 있다
조건부 규칙을 명시했다 — "항상"보다 "언제"가 더 실용적이다
처음엔 짧게 시작했다 — 리뷰에서 반복된 것만 추가하면 문서가 자연스럽게 성숙한다

예시 D — Next.js App Router 팀 프로젝트: 컴포넌트·API·DB 규칙 한 파일에

Node.js / React 단일 스택을 쓴다면 예시 D가 가장 실전적이다. 예시 A 다음에 바로 읽어도 좋다.

A·B·C가 언어나 저장소 구조 중심이었다면, 예시 D는 프레임워크 특화 규칙이 필요한 상황이다. Next.js App Router 프로젝트에서 Codex가 새 파일을 만들 때 가장 자주 발생하는 실수는 세 가지다. Server Component와 Client Component를 구분 없이 쓰는 것, API 경로 밖에서 DB를 직접 호출하는 것, Tailwind 대신 인라인 스타일을 섞는 것. 이 규칙들을 AGENTS.md에 못 박으면 다음 세션에서 같은 실수를 반복하지 않는다.

# 프로젝트
Next.js 14 App Router (TypeScript). 주요 스택: React, Tailwind CSS, Prisma, PostgreSQL.

# 구조
- app/: 페이지와 레이아웃을 둔다. App Router 기준 폴더다.
- app/api/: API Route Handler를 둔다. 서버 API는 이 폴더 안에서 만든다.
- components/: 공유 UI 컴포넌트를 둔다.
- lib/: 유틸리티, Prisma client, 서버 전용 함수를 둔다.
- prisma/: 스키마와 마이그레이션을 둔다.

# 규칙
- "use client"는 필요한 컴포넌트에만 붙인다. 기본은 Server Component다.
- app/api/ 이외에서 DB를 직접 호출하지 않는다. DB 접근은 lib/db.ts를 통해서만 한다.
- Tailwind 클래스는 className에만 쓴다. style 속성으로 인라인 스타일을 넣지 않는다.
- .env, .env.local 파일을 읽거나 수정하지 않는다.
- prisma/migrations/ 아래 파일을 직접 수정하지 않는다.

# 빌드와 테스트 (완료 기준)
코드 수정 후 완료라고 말하기 전에 아래를 순서대로 실행한다:
1. npx tsc --noEmit     # TypeScript 타입 에러 확인
2. npm run lint          # ESLint 경고 확인
3. npm run build         # 프로덕션 빌드 성공 여부 확인

줄별 해설

"use client"는 필요한 컴포넌트에만: App Router에서 Server Component가 기본이다. "use client"를 남발하면 서버 사이드 렌더링 이점이 사라진다. 이 한 줄이 Codex가 새 파일을 만들 때 기본값을 잡아준다.
lib/db.ts를 통해서만: DB 접근 경로를 단일화하면 컴포넌트 안에서 Prisma를 직접 import하는 실수를 막는다. "하지 마라"보다 "어디서 해라"가 더 잘 지켜진다.
prisma/migrations/ 직접 수정 금지: 마이그레이션 파일은 자동 생성 파일이다. Codex가 선의로 고치면 DB 스키마가 코드와 어긋난다. 이 줄이 없으면 Codex가 임의로 수정할 수 있다.
빌드와 테스트에 순서 명시: 타입 에러 → 린트 → 빌드 순으로 가장 빨리 발견할 수 있는 문제부터 확인하게 한다. "빌드를 돌려라" 한 줄보다 세 단계를 순서대로 적는 편이 놓치는 오류가 적다.

3. AGENTS.md와 로컬 메모리의 차이

핵심: AGENTS.md는 팀 전체가 공유하는 규칙, 로컬 메모리는 나만 쓰는 개인 맥락이다. 팀 기준은 반드시 AGENTS.md에 넣는다.

Codex에는 로컬 메모리 기능도 있다. 이름만 보면 AGENTS.md와 비슷해 보이지만, 이번 편의 핵심은 "팀 공유 규칙"이다.

Memories 공식 문서는 필수 팀 지침을 AGENTS.md나 저장소에 포함된 문서에 보관하고, 메모리는 항상 적용되어야 하는 규칙의 유일한 출처로 보지 말라고 안내한다.

구분	AGENTS.md	로컬 메모리
목적	팀과 프로젝트 규칙을 Codex에 전달	이전 작업 맥락과 개인 선호를 이어받음
공유 방식	Git에 포함해 팀에 공유 가능	기본적으로 개인 Codex 홈 아래에 저장
적합한 내용	테스트 명령, 코드 규칙, 디렉토리별 주의사항	자주 쓰는 워크플로, 개인 선호, 최근 작업 맥락
위험	너무 길면 읽기 비용 증가	팀 규칙을 개인 메모리에만 두면 다른 사람에게 전파되지 않음

AGENTS.md는 팀 일관성을 위한 파일이고, 로컬 메모리는 개인 작업 연속성을 위한 보조층이다. "이 규칙은 누구에게나 항상 적용되어야 한다"면 메모리가 아니라 저장소 문서로 올려야 한다.

4. Rules 파일로 명령어 제어하기

핵심: .rules 파일로 위험한 명령은 막고, 안전한 명령은 자동 허용해 불필요한 승인 확인을 줄인다.

4.1 Rules가 다루는 문제

AGENTS.md가 팀 위키의 “작업 방식” 페이지라면, Rules는 그 방식 중 셸 명령 부분을 실제로 강제하는 CI 게이트다. 위키에 “테스트 먼저 돌려라”고 적어 두어도 CI가 없으면 선언에 그친다. Rules는 Codex가 셸 명령을 실행할 때마다 “자동 통과 / 사람 확인 / 차단” 중 하나를 자동으로 결정해 그 선언을 집행한다.

AGENTS.md가 “무엇을 해야 하는가”를 설명한다면 .rules 파일은 “샌드박스 밖으로 나가려는 명령을 허용할지, 물어볼지, 막을지”를 정한다. Rules 공식 문서는 Rules를 샌드박스 밖에서 Codex가 실행할 수 있는 명령을 제어하는 기능으로 설명하며, 2026년 5월 기준 실험적 기능이라고 안내한다. 즉 아직 바뀔 수 있는 기능이므로, 팀에 적용하기 전에 최신 문서를 반드시 한 번 더 확인한다.

이 차이를 놓치면 Rules를 샌드박스 자체로 오해하기 쉽다. 샌드박스는 Codex가 기술적으로 어디까지 접근할 수 있는지 정하는 울타리이고, Rules는 그 울타리 밖 실행 요청에 붙는 승인/차단 정책이다. 둘은 서로 대체 관계가 아니라 함께 쓰는 안전장치다.

.rules 파일은 현재 설정이 놓인 위치 옆의 rules/ 폴더 아래에 둔다.

예를 들어 개인 설정에는 ~/.codex/rules/default.rules를 둘 수 있고, 프로젝트별 규칙은 신뢰된 프로젝트 안의 .codex/rules/ 폴더에서 읽힌다(Rules 문서).

규칙 파일을 새로 만들거나 바꾼 뒤에는 Codex를 재시작해야 시작 시점에 다시 스캔된다.

다음 절에서는 규칙 파일의 가장 단순한 형태인 두 필드짜리 규칙부터 시작한다.

4.2 가장 단순한 prefix_rule 한 개

prefix_rule은 “명령어의 앞부분(prefix)이 패턴과 일치하면, 그 명령을 허용할지·물어볼지·막을지 정한다”는 뜻이다. 이름만 보면 낯설지만, 동작 자체는 단순하다.

가장 작은 형태부터 보자.

# .codex/rules/team.rules
prefix_rule(
    pattern = ["git", "status"],
    decision = "allow",
)

이 규칙이 하는 일은 단순하다. git status로 시작하는 명령은 자동 허용한다. pattern은 명령의 앞부분, decision은 결정값이다. 이 두 필드만 있어도 규칙은 동작한다.

pattern이 배열인 이유는 명령어를 단어(토큰) 단위로 끊어서 비교하기 때문이다. ["git", "status"]는 “git”으로 시작하고 두 번째 토큰이 “status”인 명령을 잡는다. 뒤에 --short 같은 플래그가 붙어도 앞부분만 맞으면 이 규칙에 걸린다.

더 알아보기 — Starlark란? (초보자는 건너뛰어도 됩니다)

Rules 파일은 Starlark(스타라크)라는 언어로 작성한다. Python과 생김새가 거의 같지만 파일시스템 접근이나 네트워크 호출 같은 부작용이 없다. 쉽게 말해 "읽기 전용 Python"이라고 보면 된다. 규칙 파일 안에서 실행 코드를 넣는 방식이 아니라 명령 패턴과 결정을 선언하는 방식이라고 이해하면 된다.

4.3 결정값(decision) 3가지와 우선순위

한 줄 요약 — allow = 자동 통과, prompt = 실행 전 물어봄, forbidden = 막힘. 이 셋만 알면 된다.

decision에는 세 가지 값만 있다.

값	동작	언제 쓰나
`allow`	자동 허용 (사람 확인 없음)	읽기 전용·안전한 명령 (`git status`, `npm test`)
`prompt`	실행 전 사람 확인 요청	되돌릴 수 있지만 검토가 필요한 명령 (`npm install`, `git push`)
`forbidden`	실행 금지	되돌리기 어려운 명령 (`rm -rf`, `terraform apply -var-file=prod`)

여러 규칙이 같은 명령에 걸릴 때는 더 제한적인 결정이 이긴다. forbidden > prompt > allow 순서다.

decision 값을 따로 쓰지 않으면 기본값은 allow다.

4.4 옵션 필드와 응용 예시

pattern과 decision 외에 세 가지 선택 필드를 더 쓸 수 있다.

justification은 이 규칙을 왜 만들었는지 설명하는 메모다. Codex가 사람에게 확인을 요청할 때 이 텍스트를 함께 보여 주므로, 팀원이 규칙의 의도를 바로 알 수 있다.

match에는 이 규칙에 걸려야 하는 명령 예시를, not_match에는 걸리면 안 되는 예시를 적는다. 일종의 인라인 단위 테스트처럼 활용할 수 있어서, 규칙이 많아질수록 이 예시를 빠뜨리지 않는 게 낫다.

네 가지 필드를 모두 활용한 실전 예시다.

# .codex/rules/team.rules

# 프로덕션 terraform apply 차단 — CI/CD 파이프라인을 통해서만 허용
prefix_rule(
    pattern = ["terraform", "apply"],
    decision = "forbidden",
    justification = "프로덕션 배포는 CI/CD 파이프라인을 통해서만. Codex가 직접 apply하면 변경 이력이 남지 않는다",
    match = [
        "terraform apply -var-file=prod.tfvars",
        "terraform apply -var-file=production.tfvars",
    ],
    not_match = [
        "terraform apply -var-file=dev.tfvars",
    ],
)

# Git 읽기 전용 명령은 자동 허용
prefix_rule(
    pattern = ["git", ["status", "diff", "log"]],
    decision = "allow",
    justification = "Read-only git inspection is safe for routine work",
    match = [
        "git status",
        "git diff",
        "git log --oneline",
    ],
    not_match = [
        "git reset --hard",
    ],
)

# 파괴적 Git 명령 차단
prefix_rule(
    pattern = ["git", "reset", "--hard"],
    decision = "forbidden",
    justification = "Use a reviewed revert plan instead of destructive reset",
    match = [
        "git reset --hard",
    ],
)

# 의존성 변경은 사람이 확인
prefix_rule(
    pattern = ["npm", "install"],
    decision = "prompt",
    justification = "Dependency changes require human review",
    match = [
        "npm install react",
    ],
)

심화 예시 — kubectl 읽기/쓰기 분리 (Kubernetes를 쓰지 않는다면 건너뛰어도 됩니다)

not_match로 kubectl 쓰기 명령을 막고 읽기 명령만 허용하는 예시다. 클러스터를 직접 건드리는 명령은 사람이 수동으로 실행해야 하는 환경에서 쓴다.

# kubectl 읽기 전용만 허용 — 쓰기 명령은 수동 실행 금지
prefix_rule(
    pattern = ["kubectl"],
    decision = "forbidden",
    justification = "kubectl 쓰기 명령은 클러스터에 즉시 반영되므로 수동 실행 필요",
    not_match = [
        "kubectl get",
        "kubectl describe",
        "kubectl logs",
        "kubectl top",
    ],
)

# 읽기 명령은 자동 허용
prefix_rule(
    pattern = ["kubectl", ["get", "describe", "logs", "top"]],
    decision = "allow",
    justification = "클러스터 조회·로그 확인은 안전한 읽기 작업",
    match = [
        "kubectl get pods",
        "kubectl describe deployment api",
        "kubectl logs -f api-pod",
    ],
)

핵심 패턴: 넓은 forbidden으로 전체를 먼저 막고, 허용할 읽기 명령을 not_match 또는 별도 allow로 예외를 낸다.

4.5 규칙 검증 명령

규칙 파일을 작성한 뒤에는 실제로 원하는 대로 동작하는지 반드시 확인한다. 공식 문서는 codex execpolicy check로 규칙을 검증하는 예시를 제공한다. --rules로 파일을 지정하고, -- 뒤에 검사할 명령을 둔다(Rules 문서).

기본 출력은 JSON 형태이고, --pretty를 붙이면 사람이 읽기 좋은 형태로 확인할 수 있다.

codex execpolicy check --pretty \
  --rules .codex/rules/team.rules \
  -- git reset --hard

팀에 적용하기 전에는 “허용해야 하는 명령이 막히는가”보다 “막아야 하는 명령이 통과하는가”를 먼저 본다. 예를 들어 파일을 지우거나 Git 기록을 되돌리는 명령은 특히 먼저 확인해야 한다. 여러 명령을 한 번에 감싸서 실행하는 방식은 실제 실행 형태가 단일 명령과 달라질 수 있으므로, 팀이 실제로 쓰는 명령 그대로 검사하는 것이 좋다.

4.6 셸 래퍼: 정의·함정·체크리스트

Rules를 처음 팀에 적용할 때 가장 자주 뚫리는 구멍이 셸 래퍼다. 셸 래퍼는 bash -lc "...", zsh -c "..."처럼 문자열 안에 여러 명령을 담아 실행하는 방식이다.

예를 들어 bash -lc "git add . && rm -rf /"처럼 보이면 겉으로는 하나의 명령이지만, 실제로는 여러 행동이 숨어 있다.

변수 확장, 리다이렉션, 제어문 같은 복잡한 문법 없이 단순한 명령들이 &&, ||, ;, |로 이어진 형태라면 Codex가 이를 개별 명령으로 나누어 규칙을 적용할 수 있다. 하지만 복잡한 셸 문법이 들어가면 사람이 의도한 대로 나뉘지 않을 수 있으므로, 위험한 명령은 실제 실행 형태로 반드시 검사해야 한다.

비교 1 — bash를 통째로 허용 vs 하위 명령 단위 허용

❌ 위험한 패턴
prefix_rule( pattern = ["bash"], decision = "allow", justification = "shell scripts needed", )

✅ 안전한 패턴
prefix_rule( pattern = ["bash", "scripts/test.sh"], decision = "allow", justification = "only the known test helper", match = ["bash scripts/test.sh"], not_match = ["bash -c 'rm -rf /'"], )

pattern = ["bash"]는 bash -lc "git reset --hard && rm -rf ."도 매칭한다. 패턴이 짧을수록 더 넓게 열린다.

비교 2 — forbidden 없는 규칙 파일 vs forbidden + allow 조합

❌ 구멍이 있는 파일
# 허용 규칙만 있고 금지가 없음 prefix_rule( pattern = ["git", "status"], decision = "allow", ) prefix_rule( pattern = ["npm", "test"], decision = "allow", )

✅ 금지를 먼저, 허용은 좁게
# 위험 명령은 forbidden으로 먼저 prefix_rule( pattern = ["git", "reset", "--hard"], decision = "forbidden", justification = "use revert; hard reset loses work", ) prefix_rule( pattern = ["git", "status"], decision = "allow", )

허용 목록만 있으면 Codex는 목록에 없는 명령도 기본 승인 정책을 따른다. 위험한 명령은 별도로 명시해야 확실히 막힌다.

Rules 적용 전 preflight — preflight는 비행기 이륙 전 조종사가 체크리스트를 점검하듯, 실제 작업 전에 규칙이 의도대로 동작하는지 미리 검사하는 사전 점검이다.

허용하려는 wrapper가 아니라 실제 하위 명령을 기준으로 검사했는가?
삭제, reset, 배포, secret 출력처럼 되돌리기 어려운 명령은 좁은 forbidden 규칙을 먼저 두었는가?
codex execpolicy check로 허용·확인·차단 결과를 실제 명령 문자열로 확인했는가?
새 규칙을 넣은 뒤 Codex를 재시작해 스캔 시점을 맞췄는가?

TUI에서 어떤 명령을 허용 목록에 추가하면 Codex는 사용자 레이어의 ~/.codex/rules/default.rules에 기록해 다음 실행에서 같은 확인을 줄일 수 있다.

Smart approvals란? — 신뢰도 높은 작업은 매번 사람이 승인하지 않아도 자동으로 통과시키는 Codex의 승인 정책 기능이다. SSH의 authorized_keys처럼, 한 번 신뢰 등록된 명령은 매번 승인 없이 자동으로 통과하는 방식이다.

Smart approvals가 켜져 있으면 Codex가 승인 요청 중에 prefix_rule을 제안할 수도 있다. 편하긴 하지만, 제안된 prefix가 너무 넓으면 의도보다 많은 명령을 허용할 수 있으므로 적용 전에 좁게 잡혔는지 확인해야 한다.

Smart approvals가 켜져 있으면 Codex가 승인 요청 중에 prefix_rule을 제안할 수도 있다. 편하긴 하지만, 제안된 prefix가 너무 넓으면 의도보다 많은 명령을 허용할 수 있으므로 적용 전에 꼭 좁게 잡혔는지 확인해야 한다.

Rules 작성 순서: 금지 → 확인 → 허용

파일시스템 삭제, Git 기록 변경, 시크릿 출력처럼 되돌리기 어려운 명령을 forbidden으로 먼저 나열하고, 그 다음에 prompt와 allow를 추가한다.

허용 규칙이 많아지면 패턴이 넓어지기 쉽다. codex execpolicy check로 실제 명령 문자열을 넣어 검사하는 습관이 이 문제를 막는 가장 간단한 방법이다.

5. config.toml 핵심 설정

핵심: config.toml은 모델·승인 정책·샌드박스 수준을 팀 전체에 통일하는 설정 파일이다. 처음에는 기본값 그대로 써도 된다.

프로젝트 헌법(AGENTS.md)과 시행령(Rules)이 준비됐다면, config.toml은 이 모든 규칙이 실제로 집행되는 환경 자체를 설정한다. 어떤 모델에서 실행할지, 승인 없이 진행할 수 있는 범위는 어디까지인지, 파일 시스템 접근 울타리는 어떻게 치는지를 정한다.

config.toml은 Codex의 기본 실행 환경을 정하는 파일이다. 어떤 모델을 쓸지, 명령 실행 전에 승인을 받을지, 파일을 어디까지 수정할 수 있게 할지 같은 값을 여기서 정한다.

Config basics 문서에 따르면 사용자 전역 설정은 ~/.codex/config.toml에 두고, 프로젝트별 설정은 저장소 안의 .codex/config.toml에 둔다.

프로젝트 안의 .codex/ 설정은 신뢰된 프로젝트에서만 로드된다. 프로젝트를 신뢰하지 않음으로 표시하면 프로젝트 로컬 config, hooks, rules는 건너뛰고 사용자/시스템 설정만 로드된다.

# .codex/config.toml — 팀 공유 기본 설정 예시
# model 값은 공식 문서(developers.openai.com/codex/config-reference) 기준으로 확인한다.
# 아래는 구조 예시이므로 실제 모델명은 최신 문서를 참고한다.
approval_policy = "on-request"
sandbox_mode = "workspace-write"
default_permissions = "workspace"

줄별 해설 — 빠뜨리거나 잘못 설정하면 생기는 일

model: 생략하면 Codex 기본 모델로 실행된다. 팀 전체가 같은 모델을 쓰려면 명시하는 것이 낫다. 모델에 따라 컨텍스트 길이와 비용이 다르므로, 긴 코드베이스 작업이라면 미리 확인해야 한다.
approval_policy: "never"로 두면 모든 명령이 승인 없이 실행된다. CI 환경처럼 외부 격리가 확실한 곳이 아니라면 "on-request"가 팀 기본값으로 적합하다.
sandbox_mode: "danger-full-access"는 이름 그대로 샌드박스를 끈다. approval_policy = "never"와 함께 쓰면 완전 자동 전체 접근이 된다. 처음 설정할 때는 "workspace-write"에서 시작한다.
default_permissions: 생략하면 Codex가 기본 권한 프로필로 실행된다. 프로젝트마다 다른 접근 범위가 필요하다면 .codex/config.toml에 별도로 두고 저장소에 커밋한다.

자주 조정하는 값은 세 가지다.

approval_policy로 자동 승인 범위를 정한다. Codex가 명령 실행 전에 언제 멈춰서 사람 확인을 받을지 결정하는 값이다. 팀 기본값으로는 "on-request"가 무난하다.

sandbox_mode는 파일 시스템 접근 허용 범위를 조정한다. "workspace-write"는 작업 디렉토리 안 쓰기를 허용하고, "danger-full-access"는 샌드박스를 끈다.

처음 설정이라면 "workspace-write"에서 시작한다.

default_permissions는 팀 기본 권한 프로필을 덮어쓸 때 쓴다. 프로젝트마다 접근 범위가 다르다면 .codex/config.toml에 별도로 두고 저장소에 커밋하면 팀 전체에 공유된다.

공식 보안 문서는 기본적으로 네트워크 접근이 꺼져 있고, 로컬 Codex는 OS 수준 샌드박스와 승인 정책을 함께 사용한다고 설명한다.

default_permissions는 샌드박스 모드 자체라기보다 재사용 가능한 권한 프로필을 고르는 값이다.

현재 공식 문서 기준으로는 sandbox_mode = "read-only", workspace-write, danger-full-access 같은 sandbox mode와 default_permissions = "workspace" 같은 permission profile을 구분해서 읽는 것이 안전하다.

설정	의미	실전 기준
`approval_policy = "untrusted"`	더 제한적인 승인 흐름	낯선 저장소, 위험한 자동화
`approval_policy = "on-request"`	필요할 때 승인 요청	일반적인 팀 개발 기본값
`approval_policy = "never"`	승인 없이 진행	격리된 환경에서만 신중히 사용
`sandbox_mode = "read-only"`	읽기 중심 작업	리뷰, 조사, 구조 파악
`sandbox_mode = "workspace-write"`	작업공간 쓰기 허용	일반적인 기능 수정
`sandbox_mode = "danger-full-access"`	샌드박스 비활성화	외부 격리가 이미 있는 특수 환경

주의할 점도 있다. workspace-write라고 해서 작업공간 안의 모든 경로가 항상 쓰기 가능한 것은 아니다.

공식 보안 문서는 기본 정책에서 .git, .codex, .agents 같은 보호 경로가 읽기 전용으로 남을 수 있다고 설명한다. 그래서 Git 커밋이나 Codex 설정 파일 변경은 별도 승인이 필요할 수 있다.

특히 sandbox_mode = "danger-full-access"와 approval_policy = "never"를 함께 쓰면 사실상 전체 접근 + 승인 없음 조합이 된다. 공식 문서는 파일 수정과 명령 실행을 자동화하려는 중간 지점으로 workspace-write와 on-request 조합을 예로 든다. 초심자나 일반 팀 개발 환경이라면 이 조합부터 시작하는 게 낫다.

처음 팀 규칙을 도입할 때는 단순한 문자열 정책으로 시작한다. 실제로 막히는 지점이 보이면 그때 조금씩 세분화해도 늦지 않다.

고급 옵션 — granular 승인 정책 (처음 도입할 때는 건너뛰어도 됩니다)

승인 정책을 더 잘게 나누는 방식도 가능하다. 샌드박스 밖으로 나가는 명령은 확인을 받고, Rules 검사는 켜 두고, 별도 권한 요청은 막는 식으로 나눌 수 있다. granular는 이렇게 잘게 나눈다는 뜻이다. (Advanced Configuration 문서 참조 — 실제 팀 설정 전에 최신 필드 목록을 확인한다.)

approval_policy = { granular = {
  sandbox_approval = true,
  rules = true,
  mcp_elicitations = true,
  request_permissions = false,
  skill_approval = false
} }

6. 여러 규칙이 충돌할 때

핵심: 구체적인 규칙이 일반적인 규칙을 이긴다. 하위 디렉토리 설정이 루트보다, AGENTS.override.md가 AGENTS.md보다 먼저 적용된다.

AGENTS.md, .rules, config.toml은 각각 다른 층위에서 동작한다. 어떤 설정이 어떤 설정을 덮어쓰는지 한눈에 보면 이렇다.

설정 우선순위 (높음 → 낮음)

CLI 플래그 / --config 직접 지정  ← 실행 시점에 가장 강하게 적용
──────────────────────────────────
config.toml (프로젝트 .codex/)   ← 권한·샌드박스 정책, 팀 기본 실행 환경
AGENTS.override.md               ← 특정 폴더에서만 AGENTS.md를 덮어쓰는 로컬 예외
AGENTS.md (저장소 루트)          ← 프로젝트 전체 팀 규칙 (자연어 지침)
.rules                           ← 셸 명령 허용·확인·차단 (실행 정책)
~/.codex/config.toml             ← 사용자 전역 기본값 (개인 설정)

규칙이 충돌하면 더 제한적인 결정이 적용된다. Rules에서 forbidden > prompt > allow 순서가 대표적인 예다.

6.1 AGENTS.md 우선순위

여러 AGENTS.md가 동시에 존재하면 작업 디렉토리에 가까운 파일이 우선한다.

즉 하위 디렉토리 AGENTS.md가 저장소 루트보다 우선하고, 저장소 루트가 전역 ~/.codex/AGENTS.md보다 팀 규칙에 더 가깝다(Customization 문서).

이 규칙은 모노레포(monorepo, 프론트엔드·백엔드·공통 라이브러리처럼 여러 프로젝트가 한 저장소 안에 함께 들어 있는 구조)에서 특히 유용하다. 루트에는 공통 규칙을 두고, apps/web/AGENTS.md에는 프론트엔드 규칙을, apps/api/AGENTS.md에는 백엔드 규칙을 둘 수 있다. 서로 다른 영역의 테스트 명령과 금지 파일이 달라도 가까운 파일이 판단 기준이 된다.

6.2 config.toml 우선순위

config.toml에도 별도의 우선순위가 있다. 공식 문서 기준으로는 실행할 때 직접 넘긴 CLI 플래그와 --config 값이 가장 강하다.

그다음은 프로필 값, 프로젝트 config, 사용자 config, 시스템 config, 기본값 순이다(Config basics 문서). CLI 플래그는 터미널에서 명령을 실행할 때 붙이는 옵션이라고 생각하면 된다. 프로젝트 config는 프로젝트 루트에서 현재 작업 디렉토리까지 내려오며 적용되고, 가까운 .codex/config.toml이 더 우선한다.

규칙 충돌을 디버깅할 때는 "AGENTS.md 우선순위"와 "config.toml 우선순위"를 섞지 않아야 한다. 전자는 작업 지침의 가까운 파일 우선이고, 후자는 실행할 때 더 직접 지정한 설정을 우선하는 방식이다.

6.3 Rules 충돌 처리

Rules에서는 여러 규칙이 같은 명령에 매칭될 수 있다. 이때 Codex는 더 제한적인 결정을 적용한다. 공식 문서가 제시한 순서는 forbidden > prompt > allow다(Rules 문서).

따라서 넓은 allow 규칙과 좁은 forbidden 규칙을 함께 둘 수 있다.

예를 들어 git status와 git diff처럼 내용을 확인하는 명령은 허용하되, git reset --hard처럼 작업 내용을 되돌릴 수 있는 명령은 금지하는 식이다.

팀 규칙에서는 넓은 허용보다 좁은 금지 규칙을 명확히 쓰는 편이 리뷰 비용을 줄인다.

7. 팀에 적용하는 방법

핵심: AGENTS.md 한 파일을 저장소에 커밋하면 팀 전체가 같은 Codex 기준을 자동으로 공유한다.

첫 적용은 작게 시작하는 것이 좋다. 루트 AGENTS.md 하나, .codex/config.toml 하나, .codex/rules/team.rules 하나면 충분하다.

팀 공통 규칙으로 확정한 AGENTS.md와 .codex/rules/team.rules는 저장소에 체크인해 같은 기준을 공유한다. 체크인은 Git에 파일을 포함해 팀원이 같은 내용을 받을 수 있게 만드는 과정이다. 그리고 실제 리뷰에서 반복된 피드백만 조금씩 반영한다.

다만 저장소에 넣었다고 해서 항상 강제로 적용되는 것은 아니다. 프로젝트 .codex/ 설정은 신뢰된 프로젝트에서만 로드되고, 사용자 config나 CLI 플래그, 프로필, 기업 관리 설정과 우선순위가 함께 작동한다. 따라서 저장소 체크인은 "팀의 공유 기본값"이고, 반드시 강제해야 하는 보안 정책은 CI, 브랜치 보호, 사전 커밋 훅, 기업용 requirements.toml 같은 관리형 설정과 함께 설계해야 한다.

8. 정리와 Part 5 예고

핵심: AGENTS.md·.rules·config.toml 세 파일이 각각 '무엇을·어떻게 실행할지·어느 수준까지 허용할지'를 담당한다.

AGENTS.md는 Codex에게 "이 프로젝트에서는 이렇게 일한다"를 알려주는 팀 규칙 파일이다. 로컬 메모리가 개인 작업 흐름을 이어주는 보조층이라면, AGENTS.md는 저장소와 함께 이동하는 공유 기준이다.

.rules는 그 기준을 명령 실행 정책으로 한 단계 더 좁힌다. 어떤 명령은 자동 허용하고, 어떤 명령은 매번 확인하고, 어떤 명령은 막을지 파일로 관리할 수 있다. config.toml은 이 규칙들이 동작하는 기본 실행 환경을 정한다.

파일	역할	저장소 공유
`AGENTS.md`	팀 전체 행동 규칙 (자연어)	Git에 포함 — 팀 공유
`.rules`	명령 실행 허용·확인·차단 정책	Git에 포함 — 팀 공유
`.codex/config.toml`	모델·샌드박스·승인 정책 기본값	신뢰된 프로젝트에서 로드
`~/.codex/config.toml`	개인 전역 기본값	개인 로컬 — 공유 안 함

실전 판단 기준 — 어디에 두면 되는가

팀 전체가 따라야 할 코딩 컨벤션, 테스트 명령, 금지 디렉토리라면 AGENTS.md에 둔다. Git에 함께 커밋하면 팀원 모두에게 같은 기준이 자동으로 전달된다.
"rm -rf 차단"처럼 특정 명령을 막거나, 읽기 전용 Git 명령은 자동 허용하고 싶을 때는 .rules에 둔다. 실행 경계를 선언하는 곳이다.
나만 반복해서 쓰는 워크플로 스타일이나 개인 취향은 내 ~/.codex/config.toml 또는 로컬 메모리에 둔다. 팀 저장소에 올리지 않아도 된다.

OpenAI Codex 개발자 시리즈

Part 1: CLI 빠른 시작 Part 2: 핵심 개념 4가지 (예정) Part 3: Subagents · Workflows (예정) Part 4: AGENTS.md · Rules (현재 글) Part 5: MCP · Plugins · Skills (예정) Part 6: 자동화 (예정) Part 7: 마이그레이션 (예정) Part 8: 병행 사용 패턴 (예정) Part 11: 숨은 명령·config 사전

다음 글 예고: Part 5 — MCP, 플러그인, 스킬

MCP(Model Context Protocol, Codex가 외부 도구·API와 통신하는 표준 프로토콜)로 Codex에 외부 도구 연결하기
플러그인과 스킬의 차이 — 언제 어떤 걸 써야 하나
실제 프로젝트에서 MCP 서버를 붙이는 실습

자주 묻는 질문

AGENTS.md에는 무엇을 적어야 하나?

프로젝트 구조, 빌드와 테스트 명령, 코딩 규칙, 금지해야 할 변경, 리뷰 기준처럼 Codex가 작업 전에 알아야 하는 팀 규칙을 적는 것이 좋다.

Rules는 AGENTS.md와 무엇이 다른가?

AGENTS.md는 자연어 지침이고, Rules는 특정 명령 prefix를 허용하거나 차단하는 실행 정책에 가깝다. 설명은 AGENTS.md에, 강제하고 싶은 명령 경계는 Rules에 두는 식으로 나누어 생각하면 된다.

명령 허용 규칙을 넓게 잡아도 괜찮은가?

가능한 한 좁게 잡는 편이 안전하다. 예를 들어 셸 wrapper 전체를 허용하기보다 실제로 필요한 하위 명령 prefix를 허용해야 예기치 않은 실행 범위를 줄일 수 있다.

참고 자료

작성일: 2026년 5월 6일. 분석 범위: OpenAI Codex 공식 문서 2026년 5월 기준. 이 글은 공식 문서에 공개된 범위만 다루며, 이후 기능명이나 설정 키는 변경될 수 있다.

Codex CLI 입문(3) : Codex Subagents와 Workflows 사용 방법 - 큰 작업을 나누어 처리하는 방법

갓대희 — Mon, 11 May 2026 01:23:48 +0900

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

프로젝트가 커질수록 "Codex에게 한 번에 다 맡기면 되겠지"라는 접근방식은 금방 한계가 드러나고, 자꾸 맥락을 까먹는 문제가 생긴다.

요구사항 정리, 파일 탐색, 테스트 실행, 오류 로그 분석을 한 대화창에 계속 쌓아 두면 사람도 헷갈리고 Codex도 중요한 내용을 놓치기 쉽다.
이번 편에서는 그 이유를 풀어보고, 서브에이전트로 일을 나누는 방법과 초보자가 따라 하기 좋은 작업 흐름을 살펴본다.

OpenAI Codex 개발자 시리즈

Part 1: CLI 빠른 시작 Part 2: 핵심 개념 4가지 Part 3: Subagents · Workflows (현재 글) Part 4: AGENTS.md · Rules Part 5: MCP · Plugins · Skills (예정) Part 6: 자동화 Part 7: 마이그레이션 Part 8: 슬래시 명령어 정리(예정)

이 글은 2026년 5월 기준 공식 문서(developers.openai.com/codex)를 바탕으로 작성되었다. 기능은 지속 업데이트되므로 최신 정보는 공식 문서에서 확인한다.

먼저 용어만 가볍게 잡고 가자

코드베이스: 프로젝트를 이루는 코드, 설정 파일, 테스트 파일 전체를 말한다.
컨텍스트: Codex가 현재 대화에서 참고하는 배경 정보다. 앞에서 말한 요구사항, 로그, 파일 내용이 여기에 쌓인다.
서브에이전트: 메인 Codex가 일부 일을 따로 맡기는 보조 작업자다. 사람으로 치면 "이 부분만 따로 조사해 와"라고 역할을 나누는 것에 가깝다.
워크플로: 일을 어떤 순서로 나누고, 누가 맡고, 언제 합칠지 정한 작업 흐름이다.
CLI: 터미널에서 글자로 명령을 입력해 쓰는 도구다. Codex CLI는 Codex를 터미널에서 쓰는 방식이다.
PR: Pull Request의 줄임말이다. 보통 "내가 고친 코드를 main 브랜치에 합쳐도 되는지 검토해 달라"는 요청을 뜻한다.
orchestrator — 여러 subagent에게 일을 나눠주고 결과를 모아 다음 단계를 결정하는 관리자 에이전트
subagent — orchestrator로부터 특정 작업만 받아 수행하는 보조 에이전트. 프리랜서에 가깝다
컨텍스트 격리 — 각 에이전트가 자기 일에만 집중하도록 다른 에이전트의 작업 내용을 차단하는 것. 슬랙 알림을 끄고 집중하는 것과 같다
fan-out / fan-in — fan-out은 작업을 여러 에이전트에 동시 분배, fan-in은 결과를 다시 하나로 합치는 것. 채점지 복사(fan-out) → 점수 취합(fan-in)
spawn — 에이전트가 실행 중에 새 에이전트를 동적으로 생성하는 것

따라 하기 전에 확인할 것

서브에이전트는 편하지만, 여러 에이전트가 동시에 명령을 실행할 수 있다. 초보자는 아래 항목을 먼저 확인하는 편이 안전하다.

프로젝트 루트가 맞는지 확인한다. 엉뚱한 폴더에서 실행하면 다른 파일을 읽거나 수정할 수 있다.
git status로 현재 변경 사항을 확인한다. 중요한 변경은 커밋하거나 백업해 둔다.
처음에는 "수정하지 말고 읽기만 해라", "요약만 돌려줘"처럼 읽기 전용 지시를 명확히 쓴다.
테스트가 데이터베이스, 외부 API, 실제 비밀키를 건드리지 않는지 확인한다.
샌드박스와 승인 정책을 확인한다. 공식 Sandbox 문서에 따르면 샌드박스는 파일 수정 범위와 네트워크 사용 같은 경계를 정하고, 승인 정책은 그 경계를 넘을 때 멈춰 물어볼지를 정한다.
서브에이전트는 각자 모델과 도구 작업을 수행하므로 단일 에이전트보다 토큰 사용량, 대기 시간, 요금 부담이 늘 수 있다.

내 작업에 서브에이전트가 필요한가?

이 글을 끝까지 읽기 전에 먼저 아래 표로 감을 잡자. 서브에이전트는 "무조건 많이 띄우면 좋은 기능"이 아니라, 일을 나눴을 때 조율 비용보다 이득이 클 때 쓰는 도구다.

서브에이전트 사용 여부 빠른 판단표
상황	판단	이유
한 파일 안의 작은 수정	쓰지 않는 편이 낫다	나누는 시간보다 직접 처리하는 시간이 짧다
낯선 저장소 구조 파악	읽기 전용이면 권장	구조, 테스트, 의존성을 따로 읽어도 충돌이 거의 없다
PR 다각도 리뷰	관점이 분명하면 권장	보안, 테스트, 유지보수성처럼 렌즈를 나눌 수 있다
같은 파일을 여러 에이전트가 수정	초보자는 피한다	충돌과 재검증 비용이 커질 가능성이 높다
외부 API, DB, 결제, 메일 발송이 걸린 테스트	먼저 멈추고 확인한다	병렬 실행보다 부작용 통제가 먼저다

첫 기준

처음에는 "읽기 전용 서브에이전트 2개"에서 시작한다.
여기서 결과가 잘 맞고 검증이 쉬우면 3개로 늘리고, 파일 수정이 필요해지는 순간에는 역할별 파일 소유권을 먼저 나눈다.

왜 작업을 쪼개야 하는가
서브에이전트란 무엇인가
서브에이전트 생성하기
병렬 실행 — 읽기와 쓰기를 구분하라
모델 배분 전략
워크플로 설계 원칙
정리 및 실전 적용 가이드

서브에이전트 워크플로 패턴 한눈에 살펴보기

패턴	언제 쓰나	흔한 실패
병렬 독립	역할이 완전히 나뉘어 파일 충돌이 없을 때	결과 취합 기준이 없어 응답이 뒤섞임
순차 직렬	이전 결과가 다음 에이전트의 입력이 될 때	Phase 완료 체크 없이 다음 단계 바로 실행
오케스트레이터	복잡한 작업을 총괄 에이전트가 조율할 때	서브에이전트가 같은 파일을 덮어씀

처음에는 병렬 독립(읽기 전용 2개)패턴으로 시작해보자.
결과가 잘 나오면 순차 직렬을 추가하고, 오케스트레이터는 역할이 완전히 정리된 뒤 도입하자.

1. 왜 작업을 쪼개야 하는가

하나의 대화창에서 요구사항 정리부터 디버깅, 문서 작성까지 모두 처리하다 보면 두 가지 문제가 생긴다.

두 단어가 낯설 수 있지만, 결국 "중요한 말이 잡음에 묻힌다"는 이야기다.

공식 서브에이전트 문서는 이 문제를 명확히 구분한다.

"Context pollution: useful information gets buried under noisy intermediate output. Context rot: performance degrades as the conversation fills up with less relevant details."

(번역) "컨텍스트 오염: 유용한 정보가 불필요한 중간 출력에 묻혀 버린다. 컨텍스트 부식: 덜 관련된 세부 정보로 대화창이 채워지면서 성능이 점점 저하된다."

Context pollution은 말 그대로 "대화창이 지저분해지는 현상"이다. 파일 탐색 메모, 테스트 로그, 스택 트레이스(오류가 어디서 시작됐는지 보여주는 긴 기록)가 쌓이면서 정작 중요한 요구사항이 뒤로 밀린다.

Context rot은 그 결과로 답변 품질이 서서히 나빠지는 상태다. 쉽게 말해, 대화창이 너무 어수선해져서 Codex가 처음 목표를 잊어버리는 것이다.

해결 방향은 단순하다. 메인 스레드, 즉 내가 계속 보고 있는 중심 대화창에는 "요구사항·결정·최종 출력"만 남긴다.

파일 탐색이나 테스트처럼 로그가 많이 나오는 일은 서브에이전트에게 따로 맡기면 된다.

이 두 개념을 굳이 나누는 이유도 실전에서는 꽤 중요하다. context pollution은 지금 당장 "로그가 너무 많이 쌓였네" 하고 알아차릴 수 있다. 반면 context rot은 한참 뒤에 "왜 답이 점점 엉뚱해지지?"라는 식으로 드러난다. 먼저 오염을 줄이고, 길어진 대화에서는 품질 저하가 생기지 않는지 확인해야 한다.

2. 서브에이전트란 무엇인가

2.1 핵심 용어 3가지

공식 문서는 서브에이전트 관련 용어를 세 가지로 구분한다.

"Subagent workflow: A workflow where Codex runs parallel agents and combines their results. Subagent: A delegated agent that Codex starts to handle a specific task. Agent thread: The CLI thread for an agent, which you can inspect and switch between with /agent."

(번역) "서브에이전트 워크플로: Codex가 여러 에이전트를 병렬로 실행하고 결과를 합치는 흐름. 서브에이전트: 특정 작업을 담당하도록 Codex가 시작한 보조 에이전트. 에이전트 스레드: /agent 명령으로 전환하거나 확인할 수 있는 에이전트별 CLI 작업창."

subagent workflow는 Codex가 여러 에이전트를 병렬로 실행하고 결과를 합치는 흐름이다.

subagent는 특정 작업을 맡기기 위해 Codex가 시작한 보조 에이전트이고, agent thread는 /agent로 전환하거나 확인할 수 있는 에이전트별 작업창이다.

ex) /agent

서브에이전트 워크플로(Subagent workflow): Codex가 여러 보조 에이전트를 실행하고 결과를 합치는 전체 흐름이다.
서브에이전트(Subagent): 특정 작업을 담당하도록 Codex가 따로 띄운 보조 에이전트다.
에이전트 스레드(Agent thread): CLI에서 각 에이전트가 일하는 개별 작업창이다. /agent 명령으로 전환하거나 확인할 수 있다.

관계는 이렇게 보면 쉽다. 하나의 작업 흐름 안에 여러 보조 작업자가 있고, 각 보조 작업자는 자기 대화창을 따로 가진다.

여기서 중요한 것은 에이전트 스레드다. 서브에이전트는 안 보이는 곳에서 잠깐 실행되고 끝나는 기능이 아니다. CLI에서 직접 들어가 볼 수 있는 독립된 작업창으로 남는다. 그래서 /agent 명령으로 실행 중인 서브에이전트의 중간 상태를 확인하거나 추가 지시를 줄 수 있다.

2.2 언제 필요한가

두 가지 상황에서 서브에이전트가 유용하다.

첫째, 대화창이 복잡해지기 시작할 때다. 메인 스레드에 요구사항과 탐색 로그가 뒤섞이면, 파일 조사 같은 작업을 서브에이전트로 빼는 편이 낫다.

둘째, 한 번에 읽기 어려울 만큼 큰 작업이다. 예를 들어 문서나 코드가 너무 많으면 Codex가 모든 내용을 한 대화 안에서 안정적으로 다루기 어렵다. 이때는 여러 서브에이전트가 각자 일부를 읽고, 핵심 요약만 메인 스레드로 돌려보내게 만들 수 있다(서브에이전트 문서 참조).

3. 서브에이전트 생성하기

3.1 명시적 지시만 가능하다

서브에이전트 생성에는 중요한 전제가 있다. 공식 문서는 이를 명확히 못 박는다.

"Codex doesn't spawn subagents automatically, and it should only use subagents when you explicitly ask for subagents or parallel agent work."

(번역) "Codex는 서브에이전트를 자동으로 생성하지 않으며, 사용자가 명시적으로 서브에이전트 또는 병렬 에이전트 작업을 요청할 때만 사용한다."

Codex는 서브에이전트를 마음대로 만들지 않는다.

사용자가 "병렬 에이전트를 써라", "이 일을 나눠서 맡겨라"처럼 직접 지시해야 한다. 이 제한은 오히려 초보자에게 좋다.

나도 모르는 사이에 여러 에이전트가 실행되면 비용, 속도, 작업 흐름을 파악하기 어려워지기 때문이다.

3.2 지시 표현 예시

공식 문서는 다음과 같은 표현을 직접 지시의 예로 든다. 이 표현만 되는 것은 아니고, 핵심은 "일을 나눠서 병렬 에이전트에게 맡긴다"는 의도가 분명해야 한다는 점이다.

"spawn two agents", "delegate this work in parallel", "use one agent per point"

(번역) "에이전트 두 개를 띄워라", "이 작업을 병렬로 위임해라", "항목마다 에이전트 하나씩 써라"

핵심은 "병렬로", "에이전트를 따로", "항목별로 나눠서" 같은 말을 프롬프트에 직접 넣는 것이다.

그냥 "검토해 줘"라고 쓰면 보통 하나의 메인 스레드에서 처리된다.

비교 — 같은 PR 리뷰 요청, 지시 방식에 따라 결과가 다르다

프롬프트 원문: "이 PR을 다각도로 리뷰해줘"

서브에이전트 지시 없을 때

이 PR을 다각도로 리뷰해줘.

→ 보안·테스트·유지보수성이 한 응답에 섞여 나옴
→ 각 관점의 깊이가 얕아지고, "다각도"의 범위는 Codex가 임의로 결정
→ 어느 관점에서 뭘 말하는지 구분 안 됨

ex) 가장 최신 pr을 다각도로 리뷰해줘.

- 싱글 에이전트가 단독으로 계쏙 리뷰해 나가는 모습

병렬 서브에이전트 명시 후

Spawn one agent for security risks,
one for test gaps,
one for maintainability.
Wait for all three, then summarize by category with file references.

한국어로도 동일하게 동작한다:

보안 리스크를 볼 에이전트, 테스트 빈틈을 볼 에이전트, 유지보수성을 볼 에이전트를 각각 하나씩 띄워라.
세 결과가 모두 나오면 파일 경로와 함께 카테고리별로 요약하라.

→ 각 에이전트가 한 관점만 깊이 분석
→ 결과가 카테고리별로 정리되어 합치기 쉬움
→ 완료 기준이 "세 에이전트 모두 반환"으로 명확

ex) 가장 최신 pr을 보안 리스크를 볼 에이전트, 테스트 빈틈을 볼 에이전트, 유지보수성을 볼 에이전트를 각각 하나씩 띄워라.
세 결과가 모두 나오면 파일 경로와 함께 카테고리별로 요약하라.

- 최신 커밋은 1개의 에이전트가 확인

- 이후 지시사항대로 3개의 에이전트를 각각 띄워 작업을 시키는것을 볼 수 있다.

3.3 실전 프롬프트 예시

예시 1 — 읽기 전용 조사

Use two parallel subagents for read-only exploration.
One subagent should map the changed files.
The other should find related tests.
Do not edit files. Return short summaries with file paths.

한국어 버전:

읽기 전용 조사에 서브에이전트 2개를 병렬로 써라.
에이전트 1: 변경된 파일 목록을 정리해라.
에이전트 2: 관련 테스트 파일을 찾아라.
파일 수정 금지. 파일 경로가 포함된 짧은 요약만 돌려줘.

처음에는 이렇게 2개 정도의 읽기 전용 서브에이전트로 시작하는 편이 좋다. "수정하지 말라", "파일 경로를 포함해 짧게 요약하라"를 함께 적어 두면 결과를 확인하기 쉽다.

예시 2 — 브랜치 병렬 리뷰

Review this branch with parallel subagents.
Spawn one subagent for security risks, one for test gaps,
and one for maintainability.
Wait for all three, then summarize the findings by category
with file references.

한국어 버전:

이 브랜치를 병렬 서브에이전트로 리뷰해라.
보안 리스크를 볼 에이전트, 테스트 빈틈을 볼 에이전트, 유지보수성을 볼 에이전트를 각각 하나씩 띄워라.
세 결과가 모두 나오면 파일 경로와 함께 카테고리별로 요약하라.

세 가지 관점(보안·테스트·유지보수성)을 각각의 서브에이전트에 맡기고, 모든 결과를 기다린 뒤 카테고리별로 정리하게 하는 예시다. 여기서도 "누가 무엇을 볼지", "모든 결과를 기다릴지", "어떤 형식으로 요약할지"를 노골적으로 적는 것이 중요하다.

예시 3 — PR 6개 관점 분산 리뷰

I would like to review the following points on the current PR
(this branch vs main).
Spawn one agent per point, wait for all of them, and summarize
the result for each point.
1. Security issue
2. Code quality
3. Bugs
4. Race
5. Test flakiness
6. Maintainability of the code

한국어 버전:

현재 PR(이 브랜치 vs main)을 아래 관점으로 리뷰해라.
항목마다 에이전트를 하나씩 띄우고, 모두 끝나면 항목별로 결과를 요약하라.
1. 보안 이슈
2. 코드 품질
3. 버그
4. 경쟁 조건 (race condition: 동시 실행 시 순서가 꼬이는 문제)
5. 테스트 불안정성 (test flakiness: 가끔만 실패하는 테스트)
6. 코드 유지보수성

체크리스트 형태로 관점을 적으면 Codex가 항목마다 서브에이전트를 하나씩 배정할 수 있다.

다만 6개 에이전트는 기초 실습으로는 많다. (토큰 낭비로 이어질수도 있다.)

큰 PR에서 비용과 대기 시간을 감수할 만할 때만 쓰고, 평소에는 2~3개 관점부터 시작하는 편이 낫다(서브에이전트 문서 참조).

Goal / Constraints / Completion을 더 정밀하게: prompt-blocks

위 패턴이 익숙해졌다면 XML 블록으로 각 역할을 명시적으로 분리하는 방식으로 한 단계 올릴 수 있다. 긴 프롬프트에서 에이전트가 Goal과 Constraints를 혼동하는 경우에 효과적이다.

<task>
  이 브랜치의 보안 리스크와 테스트 갭을 병렬로 분석한다.
</task>
<action_safety>
  파일 수정 금지. 읽기만 허용.
</action_safety>
<completeness_contract>
  두 서브에이전트 결과가 모두 반환되면 완료.
  파일 경로와 줄 번호를 포함해 요약한다.
</completeness_contract>

<task>는 Goal, <action_safety>는 Constraints, <completeness_contract>는 Completion과 대응된다. 처음에는 위 자연어 패턴이 충분하다. 프롬프트가 길어지고 에이전트 동작이 예상과 달라질 때 이 구조로 바꿔보면 된다.

3.4 /agent 명령으로 스레드 확인하기

서브에이전트가 실행 중일 때 /agent 슬래시 명령을 쓰면 각 에이전트의 작업창으로 이동할 수 있다. 슬래시 명령은 Codex CLI 안에서 /로 시작하는 명령어다.

공식 슬래시 명령 문서에 따르면 /agent의 역할은 다음과 같이 정의되어 있다.

"/agent — Switch the active agent thread. Inspect or continue work in a spawned subagent thread."

(번역) "/agent — 활성 에이전트 스레드를 전환한다. 생성된 서브에이전트 스레드의 작업을 확인하거나 이어서 진행할 수 있다."

여러 서브에이전트가 동시에 실행될 때는 현재 CLI 세션 안에서 각 스레드에 들어가 중간 상태를 보거나 추가 지시를 줄 수 있다.

처음에는 꼭 필요한 경우에만 확인하면 된다. 너무 자주 끼어들면 병렬 작업의 장점이 줄어든다(CLI 슬래시 명령 문서 참조).

ex) 상기 예시중 3개의 서브 에이전트를 띄운 상황에서 /agent 입력

- 메인 에이전트 이외에 3개의 에이전트가 확인된다.

- 이중 3번째 code-reviewer 를 선택하면 실제 작업 중인 내역도 확인 가능하.

승인 요청이 뜨면 먼저 출처를 확인한다

서브에이전트가 여러 개일 때는 내가 보고 있지 않은 에이전트 스레드에서 명령 승인 요청이 올라올 수 있다. 이때는 바로 허용하지 말고 /agent로 해당 스레드를 열어 어떤 작업 중인지 확인한 뒤 승인한다. 특히 파일 수정, 네트워크 접근, 테스트 실행처럼 부작용이 있을 수 있는 명령은 이 확인 절차가 중요하다.

현재 공식 문서는 서브에이전트 활동을 Codex 앱과 CLI에서 확인할 수 있고, IDE에서의 가시성은 별도로 안내 중이라고 설명한다. 그래서 이 글의 실습은 CLI 기준으로 설명한다.

3.5 따라 해보는 실전 멀티 에이전트 프롬프트 4가지

개념만 읽으면 "언제 써야 하지?"가 막연하다.

바로 복붙해서 써볼 수 있는 프롬프트를 준비했다.

실습 내용은 가장 안전한 읽기 전용 예시이고, 예시 A에서 C로 갈수록 에이전트 협업 복잡도가 올라간다.

직접 해보자 — 바이브 코딩 버전

구조 몰라도 된다. 이 한 줄을 그대로 Codex에 붙여넣어 보자.

main 브랜치와 비교해서 바뀐 파일들을 보안 리스크와 테스트 갭, 두 관점으로 병렬로 분석해줘. 파일 수정 금지. 파일 경로와 줄 번호 포함해서 각각 요약해줘.

두 개의 에이전트가 뜨고, 결과가 "보안 리스크 / 테스트 갭" 두 섹션으로 나눠 오면 이 편의 핵심을 이해한 것이다.

ex) 실제 의도 파악을 하는지 테스트 하였고 그 결과

- 읽기 전용 및 보인/테스크 갭 분리하여 2개의 병렬 검토 진행 성공

실전 예시에 공통으로 들어가는 패턴

Goal: 에이전트가 달성할 결과를 한 문장으로
Setup: 컨텍스트 — 저장소, 브랜치, 파일 경로
Subagents: 에이전트별 역할과 산출 형식 명시
Constraints: 금지 사항 — 특히 쓰기 제한
Completion: 완료 판단 기준

에이전트가 많을수록 빠를까?

멀티스레딩 경험이 있는 개발자라면 본능적으로 "에이전트 수 = 속도"라고 느낀다. 틀린 직관이다.

프롬프트가 명확한 에이전트 하나 > 역할이 흐릿한 에이전트 셋. 분담이 모호하면 세 방향으로 흩어질 뿐이다.

대표적으로 효과가 나는 경우는 세 가지다. 독립적인 읽기 전용 탐색, 같은 산출물에 다른 관점을 동시에 적용하는 리뷰, 가벼운 탐색과 무거운 최종 판단을 나누는 흐름이다.

첫 실습 — 현재 저장소를 읽기만 해서 요약하기

가장 먼저 해볼 실습은 파일을 수정하지 않는 저장소 탐색이다. 아래 프롬프트는 현재 작업 폴더에서 구조, 테스트 위치, 패키지 관리 흔적만 읽고 짧게 요약하게 한다.

Use two parallel subagents for read-only exploration.
Do not edit files and do not run install commands.

Agent 1: inspect the top-level folders and summarize the project structure in 5 lines.
Agent 2: find test folders and package manager files, then summarize them in 5 lines.

Wait for both agents and return:
1. Project structure summary
2. Test/package summary
3. One next command I should run manually to verify the project

ex) 2개의 읽기 전용 서브에이전트를 띄워 일하는 모습

기대 결과

좋은 결과는 길지 않다. 예를 들어 "src는 앱 코드, tests는 회귀 테스트, package.json 기준 npm 프로젝트, 다음 확인 명령은 npm test"처럼 짧은 구조 요약과 수동 검증 명령 하나가 나오면 충분하다. 처음부터 파일 수정까지 맡기지 않는 이유는, 서브에이전트가 어떻게 결과를 합치는지 먼저 확인하기 위해서다.

예시 A — 낯선 저장소 첫 탐색: 구조·테스트·의존성 동시에

새 프로젝트에 처음 들어갔을 때 "디렉토리 구조가 어떻게 되지? 테스트는 어디까지 있지? 외부 의존성은 뭐가 있지?"를 순서대로 확인하면 시간이 꽤 걸린다. 세 에이전트가 동시에 읽어서 요약하면 전체 그림을 더 빨리 잡을 수 있다. 세 에이전트 모두 읽기만 하므로 충돌 가능성이 낮다.

Goal: 낯선 저장소의 전체 그림을 빠르게 파악한다.

Setup:
  저장소: github.com/example/myproject (로컬 클론 완료)
  브랜치: main

Subagents:
  - structure-agent: src/ 하위 디렉토리 구조와 주요 파일 역할을
      3~5줄 요약으로 돌려줘. 파일을 수정하면 안 된다.
  - test-agent: tests/ 또는 __tests__/ 폴더를 훑어서 테스트가
      어느 모듈까지 커버하는지 3줄로 요약해 줘. 파일을 수정하면 안 된다.
  - deps-agent: package.json 또는 requirements.txt를 읽고
      핵심 외부 의존성 5개와 용도를 정리해 줘. 파일을 수정하면 안 된다.

Constraints:
  - 세 에이전트 모두 파일 수정, 실행, 설치 금지
  - 요약은 각 에이전트 역할 범위 안에서만

Completion:
  세 에이전트 요약을 모아 "저장소 첫인상 보고서"를 한 블록으로 출력한다.

프롬프트 줄별 해설

Subagents 에이전트별 이름: 이름이 없으면 /agent로 추적하기 어렵다. 어느 에이전트가 어떤 역할인지 Codex도, 사람도 헷갈린다.
각 에이전트 지시 안에 "파일을 수정하면 안 된다" 반복: Constraints 블록만으로는 부족하다. 에이전트별 지시 안에도 직접 적어야 더 잘 지킨다.
출력 형식을 줄 수로 제한: "3~5줄", "3줄"처럼 길이를 못 박으면 각 에이전트가 과도한 맥락을 쏟아내지 않는다. 통합 단계가 훨씬 깔끔해진다.
Completion에 통합 주체 명시: "세 에이전트 요약을 모아"처럼 누가 결과를 합치는지 적지 않으면 각자 결과만 출력하고 끝날 수 있다.

예시 A의 구조를 그림으로 보면 한눈에 들어온다. orchestrator가 작업을 fan-out으로 분배하고, 각 에이전트가 자기 범위만 읽은 뒤 결과를 fan-in으로 합치는 형태다.

┌─────────────────────────────────────────────────────┐
│                   orchestrator                       │
│           (목표 설정 · 결과 검토 · 다음 지시)         │
└──────────────┬───────────────────────────────────────┘
               │  fan-out (작업 분배)
       ┌───────┼───────┐
       ▼       ▼       ▼
  [탐색 agent] [테스트 agent] [리뷰 agent]
       │       │       │
       └───────┼───────┘
               │  fan-in (결과 합산)
               ▼
          최종 보고서

이 구조가 머릿속에 그려지면 다음 예시들도 같은 틀의 변주로 읽힌다. 예시 B는 같은 틀에 "관점별 모델 차등"을 더한 형태다.

예시 B — PR 셀프 리뷰: 보안·성능·가독성을 동시에

PR 리뷰를 혼자 할 때 보안, 성능, 가독성을 한 번에 보려면 시각이 섞인다. 관점별로 에이전트를 따로 두면 각자 다른 렌즈로 같은 코드를 본다. 리뷰 깊이가 다른 관점엔 모델 설정도 다르게 줄 수 있다.

Goal: feature/auth-refactor 브랜치 PR을 세 관점으로 동시 리뷰한다.

Setup:
  대상: src/auth/ 변경분 (main 브랜치 대비)
  범위: 신규 파일 + 수정 파일만

Subagents:
  # 모델 ID 참고: https://platform.openai.com/docs/codex
  - security-agent (model: o3, effort: high):
      인증 우회, 세션 고정, 입력값 미검증 패턴만 찾아서
      파일명:줄번호 형식으로 목록화해 줘.
  - perf-agent (model: codex-mini-latest, effort: medium):
      N+1 쿼리, 루프 안 DB 호출, 불필요한 await를 찾아서
      파일명:줄번호 형식으로 목록화해 줘.
  - readability-agent (model: codex-mini-latest, effort: low):
      함수 길이 30줄 초과, 인자 5개 초과, 중복 로직을 찾아서
      파일명:줄번호 형식으로 목록화해 줘.

Constraints:
  - 파일 수정 금지. 리뷰 의견만 출력
  - 관점 범위 밖 이슈는 언급하지 않는다

Completion:
  세 에이전트 결과를 "보안 / 성능 / 가독성" 섹션으로 나눠서 출력한다.

프롬프트 줄별 해설

에이전트별 다른 model/effort: 보안처럼 놓치면 위험한 검토는 강한 모델과 높은 추론 설정으로 시작하고, 단순 스캔은 가벼운 모델로 시작할 수 있다. 이것은 공식 규칙이 아니라 비용과 위험을 함께 보는 실무 출발점이다.
"관점 범위 밖 이슈는 언급하지 않는다": 이 줄이 없으면 각 에이전트가 다른 관점의 이슈까지 포함해서 결과가 3배로 중복된다.
출력 형식을 "파일명:줄번호"로 통일: 자유 형식으로 두면 에이전트마다 양식이 달라져서 통합이 어렵다.
Completion의 섹션 구분: 사소해 보이지만, 통합 에이전트가 섹션 헤더를 인식하고 결과를 분류하는 데 도움이 된다.

A와 B는 모두 한 번에 fan-out하는 단순 구조였다. 예시 C는 한 단계 더 나아가, 직렬과 병렬을 섞은 다단계 흐름을 다룬다.

예시 C — 라이브러리 업그레이드 영향 분석: 직렬 → 병렬 → 통합

큰 의존성을 올릴 때 "어디가 깨지는지"를 보려면 먼저 전체 사용처를 파악해야 한다.

그 다음에 영역별로 나눠서 동시에 분석하고, 마지막에 합친다. A·B와 달리 에이전트 실행 순서가 있다.

Goal: lodash 4 -> 6 업그레이드 시 영향 범위를 분석한다.

Setup:
  저장소: 현재 작업 디렉토리
  대상 패키지: lodash (4.x -> 6.x)

Phase 1 (직렬):
  - scan-agent: lodash를 import하는 파일 전체 목록을 출력하고
      reports/lodash-usage.md 에 저장해 줘.

Phase 2 (병렬, Phase 1 완료 후 실행):
  - api-agent: reports/lodash-usage.md를 읽고 lodash 6에서
      제거되거나 시그니처가 바뀐 함수만 정리해 줘.
      결과를 reports/api-changes.md 에 저장해 줘.
  - test-agent: reports/lodash-usage.md를 읽고 lodash 관련
      테스트 파일을 찾아서 커버리지 갭을 요약해 줘.
      결과를 reports/test-gaps.md 에 저장해 줘.
  - type-agent: reports/lodash-usage.md를 읽고 TypeScript 타입
      불일치 가능성이 있는 파일을 목록화해 줘.
      결과를 reports/type-risks.md 에 저장해 줘.

Phase 3 (직렬, Phase 2 완료 후 실행):
  - merge-agent: reports/ 아래 세 파일을 읽어서 파일별 대응
      우선순위를 "위험도: 높음/중간/낮음" 기준으로 정리해 줘.

Constraints:
  - scan-agent, api-agent, test-agent, type-agent: 파일 수정 금지
  - merge-agent: reports/ 파일만 읽고, 코드 파일 수정 금지

Completion:
  merge-agent 결과가 콘솔에 출력되면 완료.

프롬프트 줄별 해설

Phase 1/2/3 명시적 분리: Codex가 순서를 추론하게 두면 Phase 1 완료 전에 Phase 2가 실행될 수 있다. "Phase 1 완료 후 실행"을 직접 적어야 한다.
시그니처: 함수의 이름, 매개변수(입력), 반환 타입을 합친 외형 정보다. "시그니처가 바뀐 함수"란 호출 방법이 달라진 함수를 뜻한다. 업그레이드 후 이전 코드가 그대로 동작하지 않는 원인이 된다.
커버리지 갭: 테스트가 실행하지 않는 코드 영역이다. "커버리지 갭을 요약해 줘"는 lodash를 쓰는 코드 중 테스트가 없는 부분을 찾아 달라는 뜻이다.
중간 산출을 파일로 남기기 (reports/*.md): Phase 2 에이전트가 Phase 1 결과를 메모리에서만 받는 방식은 불안정하다. 파일에 쓰고 읽게 하면 각 단계를 독립적으로 검증할 수 있다.
merge-agent 읽기 범위를 "reports/ 파일만"으로 제한: 범위를 적지 않으면 전체 저장소를 다시 읽는다. 통합 에이전트는 중간 산출물만 보면 충분하다.
Completion: 마지막 에이전트 기준으로 명시: "모든 에이전트 완료 후"처럼 모호하게 적으면 완료 판단이 흔들린다. 마지막 단계 에이전트를 명시해야 Codex가 종료 시점을 정확히 안다.

세 예시에서 반복된 패턴

에이전트마다 역할과 산출 형식을 따로 적었다 — "요약해 줘"보다 "3줄로 파일명:줄번호 형식으로"가 낫다
쓰기를 허용한 에이전트는 쓸 파일 경로를 명시했다 — 경로 없이 허용하면 어디에 저장할지 임의로 정한다
Constraints의 파일 수정 금지를 에이전트 지시 안에도 반복했다 — 블록 하나로는 부족하다
Completion에 통합 주체 또는 마지막 에이전트를 명시했다 — 이 줄이 없으면 언제 끝나는지 모호해진다

4. 병렬 실행 — 읽기와 쓰기를 구분하라

4.1 읽기 중심 작업에 먼저 적용한다

공식 서브에이전트 문서는 병렬 에이전트가 코드베이스 탐색이나 여러 단계가 있는 기능 계획처럼 나누기 쉬운 작업에 잘 맞는다고 설명한다. 초보자에게는 이 말을 "먼저 읽기 중심 작업부터 나눠 보라"는 운영 기준으로 받아들이는 편이 안전하다.

탐색(exploration, 파일과 구조를 살펴보는 일), 테스트 실행, 이슈 트리아지(문제의 원인과 우선순위를 가르는 일), 요약처럼 파일을 읽고 분석하는 작업은 병렬화에 적합하다. 서로 다른 에이전트가 같은 파일을 동시에 수정하지 않기 때문에 코드 충돌 가능성이 낮다.

테스트 실행은 완전한 읽기 작업이 아닐 수 있다

실제 테스트는 캐시 파일을 만들거나 스냅샷을 갱신하거나 데이터베이스를 건드릴 수 있다. 그래서 "테스트 실행 에이전트"를 둘 때는 프로덕션 DB, 실서비스 API 키, 외부 결제·메일 발송 같은 부작용이 없는지 먼저 확인해야 한다.

예를 들어 오래된 프로젝트에 처음 들어갔다고 해 보자. 디렉토리 구조를 보는 에이전트, 사용 중인 라이브러리를 정리하는 에이전트, 테스트가 어디까지 있는지 확인하는 에이전트를 동시에 실행할 수 있다. 세 작업 모두 읽기 전용이라 충돌이 거의 없다. 각 에이전트가 짧은 요약만 돌려주면, 메인 에이전트는 그 요약을 모아 전체 그림을 만든다. 직접 하나씩 읽는 것보다 대화창도 훨씬 깔끔하게 유지된다.

4.2 쓰기 작업은 충돌에 주의한다

병렬 쓰기는 다르다.

여러 에이전트가 동시에 코드를 고치면 충돌과 조율 비용이 커질 수 있다. 그래서 쓰기 병렬화는 처음부터 조심해야 한다.

여러 에이전트가 동시에 같은 파일을 고치면 충돌 가능성이 매우 높다. 나중에 어느 변경을 살릴지 다시 정리해야 하므로, 병렬화로 아낀 시간을 되돌려 쓰게 된다. 쓰기 작업은 파일 단위로 작업 영역을 나누거나, 아예 순서대로 처리하는 방식이 더 현실적이다.

읽기 vs 쓰기 판단 기준

각 서브에이전트가 "읽고 분석해서 요약을 돌려준다"면 병렬화하기 좋다.
"특정 파일을 직접 수정한다"면 누가 어떤 파일을 고칠지 먼저 나눠야 한다.

4.3 작업 조율은 Codex가 도와준다

여러 서브에이전트가 실행되는 동안 생성, 작업 배정, 대기, 결과 취합 같은 조율은 Codex가 도와준다. 이런 조율을 오케스트레이션이라고 부르지만, 초보자는 "여러 작업자를 관리하는 일" 정도로 이해하면 충분하다. 다만 이것이 사용자의 검증 책임까지 대신한다는 뜻은 아니다. 파일 소유권, 완료 기준, 결과 형식은 사용자가 분명히 적어야 하고, 마지막 검증도 직접 해야 한다(서브에이전트 문서 참조).

5. 모델 배분 전략

서브에이전트마다 모델을 다르게 줄 수 있지만, 초보자가 처음부터 모델 카탈로그를 외울 필요는 없다.

기본값으로 시작하고, 느리거나 비싸거나 위험한 작업이 반복될 때만 역할별 조정을 한다.

모델 이름과 제공 범위는 계정과 시점에 따라 달라질 수 있으므로 실제 선택 전에는 Codex Models 문서와 CLI의 모델 선택기를 함께 확인한다.

( 하기 내용은 실제 codex 사용하시는 분들이 아닌 api 방식으로 사용하는 분들이, 비용 대비 성능 최적화를 하기 위해 사용하는 전략이니, 가볍게 보고 어렵다면 데충 넘어가는것을 추천한다. )

서브에이전트 모델 선택을 위한 실무 기준
상황	운영 기준	이유
처음 쓰는 작업	세션 기본 모델 사용	모델 선택보다 역할·범위·완료 기준이 더 중요하다
파일 목록 수집, 구조 요약	가벼운 모델과 낮은 reasoning effort(생각의 깊이 — 높을수록 느리고 비싸다)로 시작	깊은 추론보다 빠른 스캔과 짧은 요약이 중요하다
보안, 설계, 최종 통합 판단	가능한 강한 모델과 높은 effort로 시작	가정 검증과 엣지 케이스 탐색 실패 비용이 크다
비용이나 속도가 부담될 때	모델보다 에이전트 수를 먼저 줄인다	서브에이전트는 단일 실행보다 토큰 사용과 대기 시간이 늘 수 있다

실무 출발점

가벼운 읽기 전용 서브에이전트에는 codex-mini-latest 같은 효율 모델을, 복잡한 리뷰나 최종 판단에는 o3 같은 강한 모델을 배정하는 식으로 시작할 수 있다. 이것은 공식 규칙이 아니라 비용, 속도, 작업 위험을 함께 보는 운영 기준이다.

o3: 복잡한 추론이 필요한 작업에 쓴다. 보안 분석, 설계 결정, 최종 통합 판단처럼 한 번 틀리면 비용이 큰 단계에 배정한다. 느리지만 정확하다.
codex-mini-latest: 빠른 탐색·분류 작업에 쓴다. 파일 목록 수집, 디렉토리 구조 요약, 단순 패턴 스캔처럼 단순 작업에 최적이다. 빠르지만 깊은 추론에는 약하다.

CLI에서는 실행 중에 /model 명령으로 모델을 바꿀 수 있고, 새 CLI 세션이나 codex exec(프롬프트를 인수로 전달해 대화 없이 한 번만 실행하는 서브명령)에서는 -m 또는 --model 플래그를 쓴다. 반복해서 같은 모델을 쓰고 싶을 때만 config.toml 기본값을 조정한다.

요금과 플랜도 함께 봐야 한다. 여러 서브에이전트는 "한 명의 Codex가 더 빨리 생각한다"가 아니라 여러 모델 호출이 동시에 늘어나는 구조다. 공식 Pricing 문서를 확인하고, 현재 계정의 사용 가능 모델, 플랜 한도, API 키 사용 여부를 먼저 본다.

6. 워크플로 설계 원칙

처음엔 이 순서로 생각하면 편하다. 각 원칙을 하나씩 살펴보자.

왜 네 가지인가? 멀티 에이전트가 망가지는 지점은 대부분 같은 자리에서 반복된다. 분리되지 않은 일을 분리한 척 시키거나, 같은 파일을 동시에 고치게 두거나, 결과를 합치는 사람이 없거나, 중간 결과를 확인할 방법이 없거나.

그래서 이 네 자리에 각각 가드레일을 세운 것이 아래 4원칙이다. 세부 구현보다 이 네 가지가 실수를 막는다.

멀티 에이전트 협업 4원칙

분리 가능성을 먼저 검증한다 — 진짜 독립 작업인가, 아니면 숨은 순서가 있는가. 숨은 의존성을 무시하면 Phase 2가 Phase 1 결과를 받지 못한다.
읽기는 병렬, 쓰기는 직렬 — race condition은 여러 작업이 동시에 같은 대상을 건드릴 때 생기는 실행 순서 문제다. 같은 파일을 동시에 고치게 두면 충돌 가능성이 높다.
통합 책임을 명시한다 — 누가 결과를 모으고 최종 판단하는지 적지 않으면, 각 에이전트가 자기 결과만 출력하고 아무도 합치지 않는다.
검증 가능한 산출을 남긴다 — 파일, 요약, 테스트 결과처럼 명시적 artifact(산출물: 에이전트가 남긴 확인 가능한 결과)가 없으면 중간 단계를 나중에 확인할 방법이 없다.

원칙이 어떻게 실수를 막는지 두 가지로 비교해 봤다.

문제 있는 지시

"api-agent와 test-agent가 동시에
src/auth/session.ts를 수정해 줘."

이렇게 바꾸자

"api-agent는 탐색만, 수정은 merge-agent
단독으로 Phase 2에서 진행한다."

해설: 같은 파일을 동시에 수정하면 충돌 가능성이 높다. 탐색 단계를 분리하면 사고를 줄일 수 있다.

문제 있는 지시

"각 에이전트가 분석 결과를
잘 정리해서 돌려줘."

이렇게 바꾸자

"각 에이전트는 결과를
reports/[역할].md 에 저장해 줘."

해설: 파일로 남기면 나중에 어느 에이전트가 뭘 출력했는지 바로 확인할 수 있다.

6.1 명확한 배경 정보 + 완료 기준

워크플로 설계의 출발점은 단순하다. 공식 Workflows 문서는 이렇게 말한다.

"Codex works best when you treat it like a teammate with explicit context and a clear definition of 'done.'"

(번역) "명확한 컨텍스트와 '완료' 기준이 함께 주어지면 Codex는 팀원처럼 가장 잘 작동한다."

팀원에게 일을 맡길 때처럼 배경과 완료 기준을 함께 적어야 한다. "이 PR을 리뷰해 줘"보다 "main 브랜치와 비교해서 보안 위험만 파일 경로와 함께 정리해 줘"가 훨씬 좋은 지시다. PR은 코드 변경 검토 요청이고, main 브랜치는 보통 기준이 되는 기본 브랜치다. 무엇을 봐야 하는지, 결과를 어떤 형태로 돌려줘야 하는지가 분명할수록 결과도 좋아진다.

Workflows를 적용하기 전에는 Prompting 문서의 기본 원칙도 같이 보는 게 낫다. 서브에이전트도 결국 프롬프트 품질에 좌우되기 때문이다. 어떤 파일을 봐야 하는지, 어떤 결과를 돌려줘야 하는지, 무엇을 하면 안 되는지를 적지 않으면 병렬로 빨라지는 대신 여러 방향으로 엇나갈 수 있다.

CLI에서는 파일 경로를 더 명확히 적어야 한다

공식 Workflows 문서에 따르면 IDE 확장은 열린 파일을 자동 컨텍스트로 포함하지만, CLI에서는 보통 파일 경로를 직접 언급하거나 /mention과 @ 경로 자동완성을 사용해야 한다. 초보자는 "이 프로젝트를 봐줘"보다 "src/auth/session.ts와 tests/auth를 기준으로 봐줘"처럼 적는 편이 안전하다.

6.2 오케스트레이터 패턴

복잡한 작업 흐름은 총괄 담당 1명과 역할별 작업자 여러 명으로 나누면 이해하기 쉽다.

메인 에이전트가 전체 목표와 완료 기준을 잡고, 서브에이전트가 각자 좁은 범위를 조사한 뒤 결과를 돌려주는 구조다.

"Review this branch against main. Have pr_explorer map the affected code paths, reviewer find real risks, and docs_researcher verify the framework APIs that the patch relies on."

(번역) "이 브랜치를 main과 비교해서 리뷰해라. pr_explorer가 영향받는 코드 경로를 파악하고, reviewer가 실제 위험을 찾고, docs_researcher가 패치가 의존하는 프레임워크 API를 공식 문서와 대조해서 확인한다."

pr_explorer는 바뀐 코드가 어디에 영향을 주는지 찾고, reviewer는 실제 위험을 찾고, docs_researcher는 사용한 API가 공식 문서와 맞는지 확인한다. API는 프로그램끼리 서로 기능을 호출하는 약속이라고 보면 된다. 역할이 분명하면 마지막에 결과를 합치기도 쉽다(서브에이전트 문서 참조).

실제 프로덕션 에이전트 해부: codex-rescue

오케스트레이터 패턴의 실제 구현체가 궁금하다면 superpowers 플러그인의 codex-rescue 에이전트가 좋은 참고 사례다. 이 에이전트는 세 가지 규칙만으로 설계되어 있다.

단일 책임: Codex CLI 호출 하나만 담당한다. 저장소를 직접 탐색하거나 파일을 분석하는 일은 하지 않는다. 터미널 출력(stdout)을 그대로 돌려주는 것이 전부다.
도구 제한: Bash 도구만 허용한다. 권한을 최소화하면 예상치 못한 부작용이 줄어든다. 에이전트가 할 수 있는 일을 적게 정의할수록 결과를 예측하기 쉽다.
모델 라우팅: 작업 복잡도에 따라 --model과 --effort를 조합한다. 무거운 모델을 모든 작업에 쓰지 않는다.

같은 원칙을 직접 만드는 에이전트 TOML에 적용하면 다음과 같다.

# 모델 ID 참고: https://platform.openai.com/docs/codex
name = "pr_reviewer"
description = "Security and test gap reviewer. Read-only."
model = "codex-mini-latest"
model_reasoning_effort = "medium"
sandbox_mode = "read-only"
developer_instructions = """
Review only. Do not edit files.
Report findings with file path and line number.
Return a summary under 200 words.
"""

superpowers 플러그인은 Claude Code 마켓플레이스에서 /install superpowers로 설치하면 바로 확인할 수 있다. 이 단일 책임·도구 최소화·모델 라우팅 세 원칙은 오픈소스 에이전트 생태계에서 반복적으로 나타나는 패턴이다. Part 5 (MCP · Plugins · Skills)에서는 이 원칙을 직접 플러그인으로 만들어 배포하는 법을 다룬다.

6.3 커스텀 에이전트 파일 정의

처음부터 커스텀 에이전트를 만들 필요는 없다. 기본 에이전트로도 충분히 실습할 수 있다.

다만 같은 역할을 계속 반복한다면 TOML 파일로 에이전트를 정의해 재사용할 수 있다. TOML은 설정 파일 형식이고, 여기서는 "이 에이전트의 이름, 설명, 지시문을 파일로 저장해 둔다" 정도로 이해하면 된다.

커스텀 에이전트를 만들지 판단하는 기준
상황	판단
한 번 해보는 저장소 탐색	프롬프트에 직접 역할을 적는다
매 PR마다 같은 보안 리뷰를 반복	커스텀 에이전트 후보
팀 전체가 같은 역할을 재사용	`.codex/agents/`에 두고 버전 관리 검토

공식 문서 기준으로 커스텀 에이전트의 필수 필드는 name, description, developer_instructions다. 전역 에이전트는 ~/.codex/agents/, 프로젝트 에이전트는 .codex/agents/에 둔다.

아주 작은 예시는 다음과 같다. 다만 에이전트 파일의 sandbox_mode = "read-only"만으로 항상 읽기 전용 실행이 보장된다고 이해하면 안 된다. 서브에이전트는 현재 세션의 권한·승인 설정 영향을 받으므로, 처음에는 현재 CLI 권한을 확인하고 프롬프트에도 Do not edit files.를 함께 적는 편이 안전하다.

# 모델 ID 참고: https://platform.openai.com/docs/codex
name = "docs_researcher"
description = "Official documentation checker for API and framework behavior."
model = "codex-mini-latest"
model_reasoning_effort = "medium"
sandbox_mode = "read-only"
developer_instructions = """
Use official documentation first.
Return concise findings with source links.
Do not edit files.
"""

에이전트 수 제한도 안전장치다

공식 Config Reference 기준으로 agents.max_threads의 기본값은 6, agents.max_depth의 기본값은 1이다. 동시에 너무 많은 스레드가 열리거나, 서브에이전트가 다시 하위 에이전트를 계속 만드는 일을 제한하기 위한 값이다. 초보자는 이 값을 올리기보다 작업을 더 작게 나누는 편이 안전하다.

6.4 결과 취합은 요약으로 돌려받는다

서브에이전트의 가공되지 않은 긴 로그나 추적 기록 전체를 메인 스레드로 가져오면 다시 대화창이 지저분해진다. 그래서 프롬프트에 "핵심만 요약해 줘", "중요한 결론만 돌려줘"라고 명시하는 것이 좋다. 영어 프롬프트를 쓴다면 "summarize the findings"나 "return distilled takeaways"처럼 적으면 된다.

6.5 결과를 믿기 전에 확인할 것

서브에이전트가 여러 개면 결과도 그럴듯해 보이기 쉽다. 하지만 요약이 깔끔하다고 해서 바로 맞는 것은 아니다. 최소한 아래 네 가지는 확인한다.

파일 경로와 줄 번호가 실제로 존재하는지 확인한다.
테스트를 실행했다면 어떤 명령을 실행했고, 성공/실패 결과가 무엇인지 확인한다.
API나 프레임워크 동작을 말한다면 공식 문서 링크가 붙어 있는지 확인한다.
서로 다른 서브에이전트의 결론이 충돌하면, 메인 스레드에서 다시 근거를 비교한 뒤 결정한다.

7. 정리 및 실전 적용 가이드

7.1 언제 서브에이전트를 쓸 것인가

마지막 사용 판단표
상황	권장 행동	이유
탐색·문제 분류·요약 작업	읽기 전용이면 권장	대부분 읽기 전용이라 충돌이 적다
PR(코드 변경 요청) 다각도 리뷰	관점별 역할이 분명할 때 권장	보안, 버그, 테스트를 따로 볼 수 있다
대용량 문서 분석	범위를 나눠 사용	큰 내용을 나눠 읽고 요약만 합칠 수 있다
동일 파일 동시 수정	초보자는 피함	같은 줄을 고치면 충돌 정리가 필요하다
단순 단일 파일 편집	메인 스레드에서 처리	나눠 맡기는 비용이 더 클 수 있다

한 줄로 정리하면 이렇다. 읽고 분석해 요약을 돌려주는 작업은 병렬 서브에이전트에 맡기고, 파일을 직접 고치는 단순 작업은 메인 스레드에서 처리하는 편이 안전하다.

7.2 다음 편 예고

Part 4: AGENTS.md · Rules

이번 편에서 서브에이전트에게 역할별 지시를 줬다면, 그 지시를 파일로 굳혀 팀 전체가 재사용하는 법이 Part 4의 주제다.

Constraints 블록을 AGENTS.md로 옮기면 매 프롬프트마다 반복하지 않아도 된다
전역 규칙 · 저장소 규칙 · 폴더별 규칙을 어떻게 나눌지
Karpathy 4원칙을 AGENTS.md 템플릿으로 만들어 바로 쓰는 방법

Part 5: MCP · Plugins · Skills

오늘 해부한 codex-rescue처럼 에이전트를 플러그인으로 만들어 배포하는 법을 다룬다. 오케스트레이터 패턴이 외부 서비스(Slack, GitHub, Jira)와 연결되면 사람 없이 돌아가는 워크플로가 된다.

MCP 서버로 Codex가 외부 API를 직접 호출하게 만들기
superpowers 같은 마켓플레이스 플러그인 구조 분석
이번 편에서 만든 TOML 에이전트를 스킬로 패키징하는 방법

OpenAI Codex 개발자 시리즈

Part 1: CLI 빠른 시작 Part 2: 핵심 개념 4가지 Part 3: Subagents · Workflows (현재 글) Part 4: AGENTS.md · Rules (예정) Part 5: MCP · Plugins · Skills (예정) Part 6: 자동화 (예정) Part 7: 마이그레이션 (예정) Part 8: 병행 사용 패턴 (예정)

자주 묻는 질문

Codex subagent는 언제 쓰면 좋은가?

파일 범위가 넓거나 역할이 분명히 나뉘는 작업에 유용하다. 예를 들어 한 에이전트는 코드 탐색, 다른 에이전트는 테스트 전략, 또 다른 에이전트는 문서 검토를 맡길 수 있다.

모든 작업을 subagent로 나누는 것이 좋은가?

아니다. 작은 수정이나 한 파일 안에서 끝나는 작업은 오히려 직접 처리하는 편이 빠르다. subagent는 조율 비용보다 병렬 처리 이점이 클 때 쓰는 것이 맞다.

Workflow를 만들 때 가장 중요한 기준은 무엇인가?

작업 단계를 탐색, 구현, 검증, 정리처럼 검증 가능한 단위로 나누는 것이다. 각 단계의 산출물과 완료 기준이 분명해야 다음 단계에서 맥락 손실이 줄어든다.

참고 자료

작성일: 2026년 5월 6일

분석 대상: OpenAI Codex (2026년 5월 기준 공식 문서)

이 글은 2026년 5월 기준으로 작성되었다. 이후 변경될 수 있다.

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

프로젝트가 커질수록 "Codex에게 한 번에 다 맡기면 되겠지"라는 접근방식은 금방 한계가 드러나고, 자꾸 맥락을 까먹는 문제가 생긴다.

OpenAI Codex 개발자 시리즈

Part 1: CLI 빠른 시작 Part 2: 핵심 개념 4가지 Part 3: Subagents · Workflows (현재 글) Part 4: AGENTS.md · Rules Part 5: MCP · Plugins · Skills (예정) Part 6: 자동화 (예정) Part 7: 마이그레이션 (예정) Part 8: 병행 사용 패턴 (예정)

먼저 용어만 가볍게 잡고 가자

코드베이스: 프로젝트를 이루는 코드, 설정 파일, 테스트 파일 전체를 말한다.
컨텍스트: Codex가 현재 대화에서 참고하는 배경 정보다. 앞에서 말한 요구사항, 로그, 파일 내용이 여기에 쌓인다.
서브에이전트: 메인 Codex가 일부 일을 따로 맡기는 보조 작업자다. 사람으로 치면 "이 부분만 따로 조사해 와"라고 역할을 나누는 것에 가깝다.
워크플로: 일을 어떤 순서로 나누고, 누가 맡고, 언제 합칠지 정한 작업 흐름이다.
CLI: 터미널에서 글자로 명령을 입력해 쓰는 도구다. Codex CLI는 Codex를 터미널에서 쓰는 방식이다.
PR: Pull Request의 줄임말이다. 보통 "내가 고친 코드를 main 브랜치에 합쳐도 되는지 검토해 달라"는 요청을 뜻한다.
orchestrator — 여러 subagent에게 일을 나눠주고 결과를 모아 다음 단계를 결정하는 관리자 에이전트
subagent — orchestrator로부터 특정 작업만 받아 수행하는 보조 에이전트. 프리랜서에 가깝다
컨텍스트 격리 — 각 에이전트가 자기 일에만 집중하도록 다른 에이전트의 작업 내용을 차단하는 것. 슬랙 알림을 끄고 집중하는 것과 같다
fan-out / fan-in — fan-out은 작업을 여러 에이전트에 동시 분배, fan-in은 결과를 다시 하나로 합치는 것. 채점지 복사(fan-out) → 점수 취합(fan-in)
spawn — 에이전트가 실행 중에 새 에이전트를 동적으로 생성하는 것

따라 하기 전에 확인할 것

서브에이전트는 편하지만, 여러 에이전트가 동시에 명령을 실행할 수 있다. 초보자는 아래 항목을 먼저 확인하는 편이 안전하다.

프로젝트 루트가 맞는지 확인한다. 엉뚱한 폴더에서 실행하면 다른 파일을 읽거나 수정할 수 있다.
git status로 현재 변경 사항을 확인한다. 중요한 변경은 커밋하거나 백업해 둔다.
처음에는 "수정하지 말고 읽기만 해라", "요약만 돌려줘"처럼 읽기 전용 지시를 명확히 쓴다.
테스트가 데이터베이스, 외부 API, 실제 비밀키를 건드리지 않는지 확인한다.
샌드박스와 승인 정책을 확인한다. 공식 Sandbox 문서에 따르면 샌드박스는 파일 수정 범위와 네트워크 사용 같은 경계를 정하고, 승인 정책은 그 경계를 넘을 때 멈춰 물어볼지를 정한다.
서브에이전트는 각자 모델과 도구 작업을 수행하므로 단일 에이전트보다 토큰 사용량, 대기 시간, 요금 부담이 늘 수 있다.

내 작업에 서브에이전트가 필요한가?

서브에이전트 사용 여부 빠른 판단표
상황	판단	이유
한 파일 안의 작은 수정	쓰지 않는 편이 낫다	나누는 시간보다 직접 처리하는 시간이 짧다
낯선 저장소 구조 파악	읽기 전용이면 권장	구조, 테스트, 의존성을 따로 읽어도 충돌이 거의 없다
PR 다각도 리뷰	관점이 분명하면 권장	보안, 테스트, 유지보수성처럼 렌즈를 나눌 수 있다
같은 파일을 여러 에이전트가 수정	초보자는 피한다	충돌과 재검증 비용이 커질 가능성이 높다
외부 API, DB, 결제, 메일 발송이 걸린 테스트	먼저 멈추고 확인한다	병렬 실행보다 부작용 통제가 먼저다

첫 기준

왜 작업을 쪼개야 하는가
서브에이전트란 무엇인가
서브에이전트 생성하기
병렬 실행 — 읽기와 쓰기를 구분하라
모델 배분 전략
워크플로 설계 원칙
정리 및 실전 적용 가이드

서브에이전트 워크플로 패턴 한눈에 살펴보기

패턴	언제 쓰나	흔한 실패
병렬 독립	역할이 완전히 나뉘어 파일 충돌이 없을 때	결과 취합 기준이 없어 응답이 뒤섞임
순차 직렬	이전 결과가 다음 에이전트의 입력이 될 때	Phase 완료 체크 없이 다음 단계 바로 실행
오케스트레이터	복잡한 작업을 총괄 에이전트가 조율할 때	서브에이전트가 같은 파일을 덮어씀

1. 왜 작업을 쪼개야 하는가

하나의 대화창에서 요구사항 정리부터 디버깅, 문서 작성까지 모두 처리하다 보면 두 가지 문제가 생긴다.

두 단어가 낯설 수 있지만, 결국 "중요한 말이 잡음에 묻힌다"는 이야기다.

공식 서브에이전트 문서는 이 문제를 명확히 구분한다.

"Context pollution: useful information gets buried under noisy intermediate output. Context rot: performance degrades as the conversation fills up with less relevant details."

Context rot은 그 결과로 답변 품질이 서서히 나빠지는 상태다. 쉽게 말해, 대화창이 너무 어수선해져서 Codex가 처음 목표를 잊어버리는 것이다.

해결 방향은 단순하다. 메인 스레드, 즉 내가 계속 보고 있는 중심 대화창에는 "요구사항·결정·최종 출력"만 남긴다.

파일 탐색이나 테스트처럼 로그가 많이 나오는 일은 서브에이전트에게 따로 맡기면 된다.

2. 서브에이전트란 무엇인가

2.1 핵심 용어 3가지

공식 문서는 서브에이전트 관련 용어를 세 가지로 구분한다.

subagent workflow는 Codex가 여러 에이전트를 병렬로 실행하고 결과를 합치는 흐름이다.

subagent는 특정 작업을 맡기기 위해 Codex가 시작한 보조 에이전트이고, agent thread는 /agent로 전환하거나 확인할 수 있는 에이전트별 작업창이다.

ex) /agent

서브에이전트 워크플로(Subagent workflow): Codex가 여러 보조 에이전트를 실행하고 결과를 합치는 전체 흐름이다.
서브에이전트(Subagent): 특정 작업을 담당하도록 Codex가 따로 띄운 보조 에이전트다.
에이전트 스레드(Agent thread): CLI에서 각 에이전트가 일하는 개별 작업창이다. /agent 명령으로 전환하거나 확인할 수 있다.

관계는 이렇게 보면 쉽다. 하나의 작업 흐름 안에 여러 보조 작업자가 있고, 각 보조 작업자는 자기 대화창을 따로 가진다.

2.2 언제 필요한가

두 가지 상황에서 서브에이전트가 유용하다.

첫째, 대화창이 복잡해지기 시작할 때다. 메인 스레드에 요구사항과 탐색 로그가 뒤섞이면, 파일 조사 같은 작업을 서브에이전트로 빼는 편이 낫다.

3. 서브에이전트 생성하기

3.1 명시적 지시만 가능하다

서브에이전트 생성에는 중요한 전제가 있다. 공식 문서는 이를 명확히 못 박는다.

"Codex doesn't spawn subagents automatically, and it should only use subagents when you explicitly ask for subagents or parallel agent work."

(번역) "Codex는 서브에이전트를 자동으로 생성하지 않으며, 사용자가 명시적으로 서브에이전트 또는 병렬 에이전트 작업을 요청할 때만 사용한다."

Codex는 서브에이전트를 마음대로 만들지 않는다.

사용자가 "병렬 에이전트를 써라", "이 일을 나눠서 맡겨라"처럼 직접 지시해야 한다. 이 제한은 오히려 초보자에게 좋다.

나도 모르는 사이에 여러 에이전트가 실행되면 비용, 속도, 작업 흐름을 파악하기 어려워지기 때문이다.

3.2 지시 표현 예시

"spawn two agents", "delegate this work in parallel", "use one agent per point"

(번역) "에이전트 두 개를 띄워라", "이 작업을 병렬로 위임해라", "항목마다 에이전트 하나씩 써라"

핵심은 "병렬로", "에이전트를 따로", "항목별로 나눠서" 같은 말을 프롬프트에 직접 넣는 것이다.

그냥 "검토해 줘"라고 쓰면 보통 하나의 메인 스레드에서 처리된다.

비교 — 같은 PR 리뷰 요청, 지시 방식에 따라 결과가 다르다

프롬프트 원문: "이 PR을 다각도로 리뷰해줘"

서브에이전트 지시 없을 때

이 PR을 다각도로 리뷰해줘.

ex) 가장 최신 pr을 다각도로 리뷰해줘.

- 싱글 에이전트가 단독으로 계쏙 리뷰해 나가는 모습

병렬 서브에이전트 명시 후

Spawn one agent for security risks,
one for test gaps,
one for maintainability.
Wait for all three, then summarize by category with file references.

한국어로도 동일하게 동작한다:

보안 리스크를 볼 에이전트, 테스트 빈틈을 볼 에이전트, 유지보수성을 볼 에이전트를 각각 하나씩 띄워라.
세 결과가 모두 나오면 파일 경로와 함께 카테고리별로 요약하라.

- 최신 커밋은 1개의 에이전트가 확인

- 이후 지시사항대로 3개의 에이전트를 각각 띄워 작업을 시키는것을 볼 수 있다.

3.3 실전 프롬프트 예시

예시 1 — 읽기 전용 조사

Use two parallel subagents for read-only exploration.
One subagent should map the changed files.
The other should find related tests.
Do not edit files. Return short summaries with file paths.

한국어 버전:

읽기 전용 조사에 서브에이전트 2개를 병렬로 써라.
에이전트 1: 변경된 파일 목록을 정리해라.
에이전트 2: 관련 테스트 파일을 찾아라.
파일 수정 금지. 파일 경로가 포함된 짧은 요약만 돌려줘.

예시 2 — 브랜치 병렬 리뷰

Review this branch with parallel subagents.
Spawn one subagent for security risks, one for test gaps,
and one for maintainability.
Wait for all three, then summarize the findings by category
with file references.

한국어 버전:

이 브랜치를 병렬 서브에이전트로 리뷰해라.
보안 리스크를 볼 에이전트, 테스트 빈틈을 볼 에이전트, 유지보수성을 볼 에이전트를 각각 하나씩 띄워라.
세 결과가 모두 나오면 파일 경로와 함께 카테고리별로 요약하라.

예시 3 — PR 6개 관점 분산 리뷰

I would like to review the following points on the current PR
(this branch vs main).
Spawn one agent per point, wait for all of them, and summarize
the result for each point.
1. Security issue
2. Code quality
3. Bugs
4. Race
5. Test flakiness
6. Maintainability of the code

한국어 버전:

현재 PR(이 브랜치 vs main)을 아래 관점으로 리뷰해라.
항목마다 에이전트를 하나씩 띄우고, 모두 끝나면 항목별로 결과를 요약하라.
1. 보안 이슈
2. 코드 품질
3. 버그
4. 경쟁 조건 (race condition: 동시 실행 시 순서가 꼬이는 문제)
5. 테스트 불안정성 (test flakiness: 가끔만 실패하는 테스트)
6. 코드 유지보수성

체크리스트 형태로 관점을 적으면 Codex가 항목마다 서브에이전트를 하나씩 배정할 수 있다.

다만 6개 에이전트는 기초 실습으로는 많다. (토큰 낭비로 이어질수도 있다.)

큰 PR에서 비용과 대기 시간을 감수할 만할 때만 쓰고, 평소에는 2~3개 관점부터 시작하는 편이 낫다(서브에이전트 문서 참조).

예시 4 — React 컴포넌트 스타일 버그 병렬 탐색

Use two parallel subagents for read-only exploration.
One subagent should find all files that import or use the broken Button component.
The other should check the Button's CSS module and styled-component for conflicting styles.
Do not edit files. Return short summaries with file paths.

한국어 버전:

읽기 전용 조사에 서브에이전트 2개를 병렬로 써라.
에이전트 1: Button 컴포넌트를 import하거나 사용하는 파일 전체를 목록화해라.
에이전트 2: Button의 CSS 모듈 또는 styled-component에서 충돌 가능성 있는 스타일을 찾아라.
파일 수정 금지. 파일 경로가 포함된 짧은 요약만 돌려줘.

React 프로젝트에서 특정 컴포넌트에 스타일 버그가 생겼을 때 유용한 패턴이다. 사용처와 스타일 정의를 동시에 훑어야 원인을 빨리 좁힐 수 있고, 두 에이전트 모두 읽기만 하므로 부작용이 없다.

Goal / Constraints / Completion을 더 정밀하게: prompt-blocks

<task>
  이 브랜치의 보안 리스크와 테스트 갭을 병렬로 분석한다.
</task>
<action_safety>
  파일 수정 금지. 읽기만 허용.
</action_safety>
<completeness_contract>
  두 서브에이전트 결과가 모두 반환되면 완료.
  파일 경로와 줄 번호를 포함해 요약한다.
</completeness_contract>

3.4 /agent 명령으로 스레드 확인하기

공식 슬래시 명령 문서에 따르면 /agent의 역할은 다음과 같이 정의되어 있다.

"/agent — Switch the active agent thread. Inspect or continue work in a spawned subagent thread."

(번역) "/agent — 활성 에이전트 스레드를 전환한다. 생성된 서브에이전트 스레드의 작업을 확인하거나 이어서 진행할 수 있다."

여러 서브에이전트가 동시에 실행될 때는 현재 CLI 세션 안에서 각 스레드에 들어가 중간 상태를 보거나 추가 지시를 줄 수 있다.

처음에는 꼭 필요한 경우에만 확인하면 된다. 너무 자주 끼어들면 병렬 작업의 장점이 줄어든다(CLI 슬래시 명령 문서 참조).

ex) 상기 예시중 3개의 서브 에이전트를 띄운 상황에서 /agent 입력

- 메인 에이전트 이외에 3개의 에이전트가 확인된다.

- 이중 3번째 code-reviewer 를 선택하면 실제 작업 중인 내역도 확인 가능하.

승인 요청이 뜨면 먼저 출처를 확인한다

3.5 따라 해보는 실전 멀티 에이전트 프롬프트 4가지

개념만 읽으면 "언제 써야 하지?"가 막연하다.

바로 복붙해서 써볼 수 있는 프롬프트를 준비했다.

실습 내용은 가장 안전한 읽기 전용 예시이고, 예시 A에서 C로 갈수록 에이전트 협업 복잡도가 올라간다.

직접 해보자 — 바이브 코딩 버전

구조 몰라도 된다. 이 한 줄을 그대로 Codex에 붙여넣어 보자.

main 브랜치와 비교해서 바뀐 파일들을 보안 리스크와 테스트 갭, 두 관점으로 병렬로 분석해줘. 파일 수정 금지. 파일 경로와 줄 번호 포함해서 각각 요약해줘.

두 개의 에이전트가 뜨고, 결과가 "보안 리스크 / 테스트 갭" 두 섹션으로 나눠 오면 이 편의 핵심을 이해한 것이다.

ex) 실제 의도 파악을 하는지 테스트 하였고 그 결과

- 읽기 전용 및 보인/테스크 갭 분리하여 2개의 병렬 검토 진행 성공

실전 예시에 공통으로 들어가는 패턴

Goal: 에이전트가 달성할 결과를 한 문장으로
Setup: 컨텍스트 — 저장소, 브랜치, 파일 경로
Subagents: 에이전트별 역할과 산출 형식 명시
Constraints: 금지 사항 — 특히 쓰기 제한
Completion: 완료 판단 기준

에이전트가 많을수록 빠를까?

멀티스레딩 경험이 있는 개발자라면 본능적으로 "에이전트 수 = 속도"라고 느낀다. 틀린 직관이다.

프롬프트가 명확한 에이전트 하나 > 역할이 흐릿한 에이전트 셋. 분담이 모호하면 세 방향으로 흩어질 뿐이다.

첫 실습 — 현재 저장소를 읽기만 해서 요약하기

Use two parallel subagents for read-only exploration.
Do not edit files and do not run install commands.

Agent 1: inspect the top-level folders and summarize the project structure in 5 lines.
Agent 2: find test folders and package manager files, then summarize them in 5 lines.

Wait for both agents and return:
1. Project structure summary
2. Test/package summary
3. One next command I should run manually to verify the project

ex) 2개의 읽기 전용 서브에이전트를 띄워 일하는 모습

기대 결과

예시 A — 낯선 저장소 첫 탐색: 구조·테스트·의존성 동시에

Goal: 낯선 저장소의 전체 그림을 빠르게 파악한다.

Setup:
  저장소: github.com/example/myproject (로컬 클론 완료)
  브랜치: main

Subagents:
  - structure-agent: src/ 하위 디렉토리 구조와 주요 파일 역할을
      3~5줄 요약으로 돌려줘. 파일을 수정하면 안 된다.
  - test-agent: tests/ 또는 __tests__/ 폴더를 훑어서 테스트가
      어느 모듈까지 커버하는지 3줄로 요약해 줘. 파일을 수정하면 안 된다.
  - deps-agent: package.json 또는 requirements.txt를 읽고
      핵심 외부 의존성 5개와 용도를 정리해 줘. 파일을 수정하면 안 된다.

Constraints:
  - 세 에이전트 모두 파일 수정, 실행, 설치 금지
  - 요약은 각 에이전트 역할 범위 안에서만

Completion:
  세 에이전트 요약을 모아 "저장소 첫인상 보고서"를 한 블록으로 출력한다.

프롬프트 줄별 해설

Subagents 에이전트별 이름: 이름이 없으면 /agent로 추적하기 어렵다. 어느 에이전트가 어떤 역할인지 Codex도, 사람도 헷갈린다.
각 에이전트 지시 안에 "파일을 수정하면 안 된다" 반복: Constraints 블록만으로는 부족하다. 에이전트별 지시 안에도 직접 적어야 더 잘 지킨다.
출력 형식을 줄 수로 제한: "3~5줄", "3줄"처럼 길이를 못 박으면 각 에이전트가 과도한 맥락을 쏟아내지 않는다. 통합 단계가 훨씬 깔끔해진다.
Completion에 통합 주체 명시: "세 에이전트 요약을 모아"처럼 누가 결과를 합치는지 적지 않으면 각자 결과만 출력하고 끝날 수 있다.

┌─────────────────────────────────────────────────────┐
│                   orchestrator                       │
│           (목표 설정 · 결과 검토 · 다음 지시)         │
└──────────────┬───────────────────────────────────────┘
               │  fan-out (작업 분배)
       ┌───────┼───────┐
       ▼       ▼       ▼
  [탐색 agent] [테스트 agent] [리뷰 agent]
       │       │       │
       └───────┼───────┘
               │  fan-in (결과 합산)
               ▼
          최종 보고서

이 구조가 머릿속에 그려지면 다음 예시들도 같은 틀의 변주로 읽힌다. 예시 B는 같은 틀에 "관점별 모델 차등"을 더한 형태다.

예시 B — PR 셀프 리뷰: 보안·성능·가독성을 동시에

Goal: feature/auth-refactor 브랜치 PR을 세 관점으로 동시 리뷰한다.

Setup:
  대상: src/auth/ 변경분 (main 브랜치 대비)
  범위: 신규 파일 + 수정 파일만

Subagents:
  # 모델 ID 참고: https://platform.openai.com/docs/codex
  - security-agent (model: o3, effort: high):
      인증 우회, 세션 고정, 입력값 미검증 패턴만 찾아서
      파일명:줄번호 형식으로 목록화해 줘.
  - perf-agent (model: codex-mini-latest, effort: medium):
      N+1 쿼리, 루프 안 DB 호출, 불필요한 await를 찾아서
      파일명:줄번호 형식으로 목록화해 줘.
  - readability-agent (model: codex-mini-latest, effort: low):
      함수 길이 30줄 초과, 인자 5개 초과, 중복 로직을 찾아서
      파일명:줄번호 형식으로 목록화해 줘.

Constraints:
  - 파일 수정 금지. 리뷰 의견만 출력
  - 관점 범위 밖 이슈는 언급하지 않는다

Completion:
  세 에이전트 결과를 "보안 / 성능 / 가독성" 섹션으로 나눠서 출력한다.

프롬프트 줄별 해설

에이전트별 다른 model/effort: 보안처럼 놓치면 위험한 검토는 강한 모델과 높은 추론 설정으로 시작하고, 단순 스캔은 가벼운 모델로 시작할 수 있다. 이것은 공식 규칙이 아니라 비용과 위험을 함께 보는 실무 출발점이다.
"관점 범위 밖 이슈는 언급하지 않는다": 이 줄이 없으면 각 에이전트가 다른 관점의 이슈까지 포함해서 결과가 3배로 중복된다.
출력 형식을 "파일명:줄번호"로 통일: 자유 형식으로 두면 에이전트마다 양식이 달라져서 통합이 어렵다.
Completion의 섹션 구분: 사소해 보이지만, 통합 에이전트가 섹션 헤더를 인식하고 결과를 분류하는 데 도움이 된다.

A와 B는 모두 한 번에 fan-out하는 단순 구조였다. 예시 C는 한 단계 더 나아가, 직렬과 병렬을 섞은 다단계 흐름을 다룬다.

예시 C — 라이브러리 업그레이드 영향 분석: 직렬 → 병렬 → 통합

큰 의존성을 올릴 때 "어디가 깨지는지"를 보려면 먼저 전체 사용처를 파악해야 한다.

그 다음에 영역별로 나눠서 동시에 분석하고, 마지막에 합친다. A·B와 달리 에이전트 실행 순서가 있다.

Goal: lodash 4 -> 6 업그레이드 시 영향 범위를 분석한다.

Setup:
  저장소: 현재 작업 디렉토리
  대상 패키지: lodash (4.x -> 6.x)

Phase 1 (직렬):
  - scan-agent: lodash를 import하는 파일 전체 목록을 출력하고
      reports/lodash-usage.md 에 저장해 줘.

Phase 2 (병렬, Phase 1 완료 후 실행):
  - api-agent: reports/lodash-usage.md를 읽고 lodash 6에서
      제거되거나 시그니처가 바뀐 함수만 정리해 줘.
      결과를 reports/api-changes.md 에 저장해 줘.
  - test-agent: reports/lodash-usage.md를 읽고 lodash 관련
      테스트 파일을 찾아서 커버리지 갭을 요약해 줘.
      결과를 reports/test-gaps.md 에 저장해 줘.
  - type-agent: reports/lodash-usage.md를 읽고 TypeScript 타입
      불일치 가능성이 있는 파일을 목록화해 줘.
      결과를 reports/type-risks.md 에 저장해 줘.

Phase 3 (직렬, Phase 2 완료 후 실행):
  - merge-agent: reports/ 아래 세 파일을 읽어서 파일별 대응
      우선순위를 "위험도: 높음/중간/낮음" 기준으로 정리해 줘.

Constraints:
  - scan-agent, api-agent, test-agent, type-agent: 파일 수정 금지
  - merge-agent: reports/ 파일만 읽고, 코드 파일 수정 금지

Completion:
  merge-agent 결과가 콘솔에 출력되면 완료.

프롬프트 줄별 해설

Phase 1/2/3 명시적 분리: Codex가 순서를 추론하게 두면 Phase 1 완료 전에 Phase 2가 실행될 수 있다. "Phase 1 완료 후 실행"을 직접 적어야 한다.
시그니처: 함수의 이름, 매개변수(입력), 반환 타입을 합친 외형 정보다. "시그니처가 바뀐 함수"란 호출 방법이 달라진 함수를 뜻한다. 업그레이드 후 이전 코드가 그대로 동작하지 않는 원인이 된다.
커버리지 갭: 테스트가 실행하지 않는 코드 영역이다. "커버리지 갭을 요약해 줘"는 lodash를 쓰는 코드 중 테스트가 없는 부분을 찾아 달라는 뜻이다.
중간 산출을 파일로 남기기 (reports/*.md): Phase 2 에이전트가 Phase 1 결과를 메모리에서만 받는 방식은 불안정하다. 파일에 쓰고 읽게 하면 각 단계를 독립적으로 검증할 수 있다.
merge-agent 읽기 범위를 "reports/ 파일만"으로 제한: 범위를 적지 않으면 전체 저장소를 다시 읽는다. 통합 에이전트는 중간 산출물만 보면 충분하다.
Completion: 마지막 에이전트 기준으로 명시: "모든 에이전트 완료 후"처럼 모호하게 적으면 완료 판단이 흔들린다. 마지막 단계 에이전트를 명시해야 Codex가 종료 시점을 정확히 안다.

세 예시에서 반복된 패턴

에이전트마다 역할과 산출 형식을 따로 적었다 — "요약해 줘"보다 "3줄로 파일명:줄번호 형식으로"가 낫다
쓰기를 허용한 에이전트는 쓸 파일 경로를 명시했다 — 경로 없이 허용하면 어디에 저장할지 임의로 정한다
Constraints의 파일 수정 금지를 에이전트 지시 안에도 반복했다 — 블록 하나로는 부족하다
Completion에 통합 주체 또는 마지막 에이전트를 명시했다 — 이 줄이 없으면 언제 끝나는지 모호해진다

예시 D — Next.js 기능 추가 전 탐색: 컴포넌트·API·테스트 패턴 동시에

새 페이지나 기능을 붙이기 전에 기존 코드의 패턴을 먼저 파악하지 않으면, 팀 컨벤션과 어긋나는 코드를 짜게 된다. 특히 Next.js App Router 프로젝트는 Server Component 사용 방식, 데이터 패칭 방법, 테스트 도구가 프로젝트마다 다르다.

세 에이전트가 각자 한 영역만 읽고 요약을 돌려주면, 코드를 짜기 전에 "이 프로젝트에서 어떻게 해야 하나"를 빠르게 정리할 수 있다. A·B·C가 리뷰·분석 중심이었다면, 예시 D는 신규 기능을 구현하기 전 "탐색 단계"에 서브에이전트를 쓰는 패턴이다.

Goal: /dashboard 페이지 추가 전에 Next.js 프로젝트의 기존 패턴을 파악한다.

Setup:
  저장소: 현재 작업 디렉토리 (Next.js App Router 기반)
  목적: 신규 대시보드 페이지 구현 전 코드 컨벤션 파악

Subagents:
  - component-agent: app/ 디렉토리의 기존 페이지 컴포넌트를 읽어라.
      Server Component와 Client Component("use client") 구분 기준,
      공통 레이아웃 파일(layout.tsx)이 어디 있는지 3~5줄로 요약해라.
      파일 수정 금지.
  - api-agent: app/api/ 또는 lib/ 아래 데이터 패칭 패턴을 찾아라.
      fetch, axios, React Query 중 어떤 방식을 쓰는지,
      인증 처리(middleware.ts 또는 세션 확인 로직)가 어디서 이루어지는지 3줄로 요약해라.
      파일 수정 금지.
  - test-agent: __tests__/ 또는 *.test.tsx, *.spec.tsx 파일을 찾아서
      테스트 도구(jest, vitest, RTL 등)와 기존 테스트 파일 위치를 3줄로 요약해라.
      파일 수정 금지.

Constraints:
  - 세 에이전트 모두 파일 수정, 설치, 실행 금지
  - 각 에이전트는 자기 담당 범위 안에서만 요약

Completion:
  세 에이전트 결과를 모아 "대시보드 페이지 추가 시작점 보고서"를 한 블록으로 출력한다.
  보고서 형식: 컴포넌트 패턴 / API 연동 / 테스트 위치 세 섹션.

프롬프트 줄별 해설

왜 코드 짜기 전에 탐색부터?: Next.js 프로젝트마다 "use client" 쓰는 위치, 데이터 패칭 방식, 테스트 도구가 다르다. 탐색 없이 바로 짜면 기존 패턴과 달라져 나중에 리팩토링 비용이 생긴다.
component-agent에 "Server vs Client 구분 기준" 명시: App Router에서 가장 자주 틀리는 지점이다. "use client"가 어느 깊이에서 선언되는지 파악해 두면 새 페이지를 짤 때 실수를 줄인다.
api-agent에 "인증 처리 위치" 추가: 대시보드는 보통 로그인이 필요하다. 기존 middleware.ts나 세션 확인 로직을 먼저 알아야 같은 패턴을 새 페이지에 적용할 수 있다.
Completion의 섹션 분리: "컴포넌트 / API / 테스트" 세 섹션으로 강제하면, 이후 실제 구현 프롬프트에서 섹션별로 참조하기 쉽다. 예시 A·B와 마찬가지로 통합 주체를 명시해야 각자 결과만 내고 끝나는 것을 막는다.

직접 해보자 — 바이브 코딩 버전

구조 몰라도 된다. 이 한 줄을 그대로 Codex에 붙여넣어 보자.

이 Next.js 프로젝트에 대시보드 페이지를 추가하려고 해. 코드 짜기 전에 서브에이전트 3개로 병렬 탐색해줘. 하나는 기존 컴포넌트 패턴, 하나는 API 연동 방식, 하나는 테스트 위치. 파일 수정 금지. 결과는 세 섹션으로 나눠서 요약해줘.

세 개의 에이전트가 뜨고, 결과가 "컴포넌트 패턴 / API 연동 / 테스트 위치" 세 섹션으로 나눠 오면 이 패턴을 이해한 것이다.

예시 D는 신규 기능 추가 전 "탐색 → 구현" 2단계 흐름의 첫 단계다. 탐색 결과 보고서가 나오면 그 내용을 컨텍스트로 붙여 구현 프롬프트로 넘어가면 된다. 익숙해지면 탐색·구현·테스트 생성을 직렬로 이어 붙이는 3단계 워크플로로 확장할 수 있다.

4. 병렬 실행 — 읽기와 쓰기를 구분하라

4.1 읽기 중심 작업에 먼저 적용한다

테스트 실행은 완전한 읽기 작업이 아닐 수 있다

4.2 쓰기 작업은 충돌에 주의한다

병렬 쓰기는 다르다.

여러 에이전트가 동시에 코드를 고치면 충돌과 조율 비용이 커질 수 있다. 그래서 쓰기 병렬화는 처음부터 조심해야 한다.

읽기 vs 쓰기 판단 기준

각 서브에이전트가 "읽고 분석해서 요약을 돌려준다"면 병렬화하기 좋다.
"특정 파일을 직접 수정한다"면 누가 어떤 파일을 고칠지 먼저 나눠야 한다.

4.3 작업 조율은 Codex가 도와준다

5. 모델 배분 전략

서브에이전트마다 모델을 다르게 줄 수 있지만, 초보자가 처음부터 모델 카탈로그를 외울 필요는 없다.

기본값으로 시작하고, 느리거나 비싸거나 위험한 작업이 반복될 때만 역할별 조정을 한다.

모델 이름과 제공 범위는 계정과 시점에 따라 달라질 수 있으므로 실제 선택 전에는 Codex Models 문서와 CLI의 모델 선택기를 함께 확인한다.

서브에이전트 모델 선택을 위한 실무 기준
상황	운영 기준	이유
처음 쓰는 작업	세션 기본 모델 사용	모델 선택보다 역할·범위·완료 기준이 더 중요하다
파일 목록 수집, 구조 요약	가벼운 모델과 낮은 reasoning effort(생각의 깊이 — 높을수록 느리고 비싸다)로 시작	깊은 추론보다 빠른 스캔과 짧은 요약이 중요하다
보안, 설계, 최종 통합 판단	가능한 강한 모델과 높은 effort로 시작	가정 검증과 엣지 케이스 탐색 실패 비용이 크다
비용이나 속도가 부담될 때	모델보다 에이전트 수를 먼저 줄인다	서브에이전트는 단일 실행보다 토큰 사용과 대기 시간이 늘 수 있다

실무 출발점

o3: 복잡한 추론이 필요한 작업에 쓴다. 보안 분석, 설계 결정, 최종 통합 판단처럼 한 번 틀리면 비용이 큰 단계에 배정한다. 느리지만 정확하다.
codex-mini-latest: 빠른 탐색·분류 작업에 쓴다. 파일 목록 수집, 디렉토리 구조 요약, 단순 패턴 스캔처럼 단순 작업에 최적이다. 빠르지만 깊은 추론에는 약하다.

6. 워크플로 설계 원칙

처음엔 이 순서로 생각하면 편하다. 각 원칙을 하나씩 살펴보자.

그래서 이 네 자리에 각각 가드레일을 세운 것이 아래 4원칙이다. 세부 구현보다 이 네 가지가 실수를 막는다.

멀티 에이전트 협업 4원칙

분리 가능성을 먼저 검증한다 — 진짜 독립 작업인가, 아니면 숨은 순서가 있는가. 숨은 의존성을 무시하면 Phase 2가 Phase 1 결과를 받지 못한다.
읽기는 병렬, 쓰기는 직렬 — race condition은 여러 작업이 동시에 같은 대상을 건드릴 때 생기는 실행 순서 문제다. 같은 파일을 동시에 고치게 두면 충돌 가능성이 높다.
통합 책임을 명시한다 — 누가 결과를 모으고 최종 판단하는지 적지 않으면, 각 에이전트가 자기 결과만 출력하고 아무도 합치지 않는다.
검증 가능한 산출을 남긴다 — 파일, 요약, 테스트 결과처럼 명시적 artifact(산출물: 에이전트가 남긴 확인 가능한 결과)가 없으면 중간 단계를 나중에 확인할 방법이 없다.

원칙이 어떻게 실수를 막는지 두 가지로 비교해 봤다.

문제 있는 지시

"api-agent와 test-agent가 동시에
src/auth/session.ts를 수정해 줘."

이렇게 바꾸자

"api-agent는 탐색만, 수정은 merge-agent
단독으로 Phase 2에서 진행한다."

해설: 같은 파일을 동시에 수정하면 충돌 가능성이 높다. 탐색 단계를 분리하면 사고를 줄일 수 있다.

문제 있는 지시

"각 에이전트가 분석 결과를
잘 정리해서 돌려줘."

이렇게 바꾸자

"각 에이전트는 결과를
reports/[역할].md 에 저장해 줘."

해설: 파일로 남기면 나중에 어느 에이전트가 뭘 출력했는지 바로 확인할 수 있다.

6.1 명확한 배경 정보 + 완료 기준

워크플로 설계의 출발점은 단순하다. 공식 Workflows 문서는 이렇게 말한다.

"Codex works best when you treat it like a teammate with explicit context and a clear definition of 'done.'"

(번역) "명확한 컨텍스트와 '완료' 기준이 함께 주어지면 Codex는 팀원처럼 가장 잘 작동한다."

CLI에서는 파일 경로를 더 명확히 적어야 한다

6.2 오케스트레이터 패턴

복잡한 작업 흐름은 총괄 담당 1명과 역할별 작업자 여러 명으로 나누면 이해하기 쉽다.

메인 에이전트가 전체 목표와 완료 기준을 잡고, 서브에이전트가 각자 좁은 범위를 조사한 뒤 결과를 돌려주는 구조다.

"Review this branch against main. Have pr_explorer map the affected code paths, reviewer find real risks, and docs_researcher verify the framework APIs that the patch relies on."

실제 프로덕션 에이전트 해부: codex-rescue

단일 책임: Codex CLI 호출 하나만 담당한다. 저장소를 직접 탐색하거나 파일을 분석하는 일은 하지 않는다. 터미널 출력(stdout)을 그대로 돌려주는 것이 전부다.
도구 제한: Bash 도구만 허용한다. 권한을 최소화하면 예상치 못한 부작용이 줄어든다. 에이전트가 할 수 있는 일을 적게 정의할수록 결과를 예측하기 쉽다.
모델 라우팅: 작업 복잡도에 따라 --model과 --effort를 조합한다. 무거운 모델을 모든 작업에 쓰지 않는다.

같은 원칙을 직접 만드는 에이전트 TOML에 적용하면 다음과 같다.

# 모델 ID 참고: https://platform.openai.com/docs/codex
name = "pr_reviewer"
description = "Security and test gap reviewer. Read-only."
model = "codex-mini-latest"
model_reasoning_effort = "medium"
sandbox_mode = "read-only"
developer_instructions = """
Review only. Do not edit files.
Report findings with file path and line number.
Return a summary under 200 words.
"""

6.3 커스텀 에이전트 파일 정의

처음부터 커스텀 에이전트를 만들 필요는 없다. 기본 에이전트로도 충분히 실습할 수 있다.

커스텀 에이전트를 만들지 판단하는 기준
상황	판단
한 번 해보는 저장소 탐색	프롬프트에 직접 역할을 적는다
매 PR마다 같은 보안 리뷰를 반복	커스텀 에이전트 후보
팀 전체가 같은 역할을 재사용	`.codex/agents/`에 두고 버전 관리 검토

# 모델 ID 참고: https://platform.openai.com/docs/codex
name = "docs_researcher"
description = "Official documentation checker for API and framework behavior."
model = "codex-mini-latest"
model_reasoning_effort = "medium"
sandbox_mode = "read-only"
developer_instructions = """
Use official documentation first.
Return concise findings with source links.
Do not edit files.
"""

에이전트 수 제한도 안전장치다

6.4 결과 취합은 요약으로 돌려받는다

6.5 결과를 믿기 전에 확인할 것

서브에이전트가 여러 개면 결과도 그럴듯해 보이기 쉽다. 하지만 요약이 깔끔하다고 해서 바로 맞는 것은 아니다. 최소한 아래 네 가지는 확인한다.

파일 경로와 줄 번호가 실제로 존재하는지 확인한다.
테스트를 실행했다면 어떤 명령을 실행했고, 성공/실패 결과가 무엇인지 확인한다.
API나 프레임워크 동작을 말한다면 공식 문서 링크가 붙어 있는지 확인한다.
서로 다른 서브에이전트의 결론이 충돌하면, 메인 스레드에서 다시 근거를 비교한 뒤 결정한다.

7. 정리 및 실전 적용 가이드

7.1 언제 서브에이전트를 쓸 것인가

마지막 사용 판단표
상황	권장 행동	이유
탐색·문제 분류·요약 작업	읽기 전용이면 권장	대부분 읽기 전용이라 충돌이 적다
PR(코드 변경 요청) 다각도 리뷰	관점별 역할이 분명할 때 권장	보안, 버그, 테스트를 따로 볼 수 있다
대용량 문서 분석	범위를 나눠 사용	큰 내용을 나눠 읽고 요약만 합칠 수 있다
동일 파일 동시 수정	초보자는 피함	같은 줄을 고치면 충돌 정리가 필요하다
단순 단일 파일 편집	메인 스레드에서 처리	나눠 맡기는 비용이 더 클 수 있다

7.2 다음 편 예고

Part 4: AGENTS.md · Rules

이번 편에서 서브에이전트에게 역할별 지시를 줬다면, 그 지시를 파일로 굳혀 팀 전체가 재사용하는 법이 Part 4의 주제다.

Constraints 블록을 AGENTS.md로 옮기면 매 프롬프트마다 반복하지 않아도 된다
전역 규칙 · 저장소 규칙 · 폴더별 규칙을 어떻게 나눌지
Karpathy 4원칙을 AGENTS.md 템플릿으로 만들어 바로 쓰는 방법

Part 5: MCP · Plugins · Skills

MCP 서버로 Codex가 외부 API를 직접 호출하게 만들기
superpowers 같은 마켓플레이스 플러그인 구조 분석
이번 편에서 만든 TOML 에이전트를 스킬로 패키징하는 방법

OpenAI Codex 개발자 시리즈

자주 묻는 질문

Codex subagent는 언제 쓰면 좋은가?

모든 작업을 subagent로 나누는 것이 좋은가?

Workflow를 만들 때 가장 중요한 기준은 무엇인가?

참고 자료

작성일: 2026년 5월 6일

분석 대상: OpenAI Codex (2026년 5월 기준 공식 문서)

이 글은 2026년 5월 기준으로 작성되었다. 이후 변경될 수 있다.

Codex CLI 입문(2) : OpenAI Codex 핵심 개념 4가지 - Prompting, Memories, Sandboxing, Models

갓대희 — Thu, 7 May 2026 10:42:45 +0900

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

Codex를 처음 써본 뒤 "명령이 뜻대로 안 된다"거나 "같은 실수를 반복한다"는 느낌이 든 적이 있다면, 꼭 도구 탓만은 아닐 수 있다. Codex가 무엇을 읽고, 어떤 기준으로 판단하고, 어디까지 실행하는지 모른 채 맡겼을 가능성이 크다.

이번 글에서는 Codex를 제대로 쓰기 위해 먼저 알아야 할 네 가지 — 프롬프트(Prompting), 메모리(Memories), 샌드박스(Sandboxing), 모델(Models) — 를 공식 문서를 바탕으로 정리한다.

먼저 용어부터 가볍게 잡고 가자

- 프롬프트 : Codex에게 보내는 지시문이다.

- 컨텍스트 : Codex가 함께 참고할 파일, 코드, 이미지 같은 자료다.

- 샌드박스 : Codex가 함부로 파일을 바꾸거나 명령을 실행하지 못하게 막는 안전 울타리이고, 모델은 실제로 답을 만들고 판단하는 AI 엔진이라고 보면 된다.

- 작업 범위 : Codex에게 맡기는 일의 크기다. 예를 들어 "읽기만 해라", "이 폴더 안 파일만 고쳐라", "위험한 명령은 먼저 물어봐라"처럼 정하는 것이다.

- 승인 정책 : Codex가 경계를 넘으려 할 때 나에게 먼저 물어볼지 정하는 규칙이다.

앞선 CLI 빠른 시작 편과 이 글의 차이

앞선 글의 샌드박스 설명은 "처음 켤 때 어떤 안전 설정으로 시작할까"에 가까웠다.

이 글에서는 한 단계 더 들어가서 이번 작업을 Codex에게 어디까지 맡겨도 되는지를 고르는 법을 다룬다. 프롬프트·메모리·모델도 결국 이 판단과 함께 움직인다.

즉. Codex가 읽기만 할지, 프로젝트 안에서 수정해도 될지, 명령 실행은 언제 물어봐야 할지를 판단할 수 있도록 이해 하는게 이번글에서의 목표이다..

OpenAI Codex 개발자 시리즈

Part 1: CLI 빠른 시작 Part 2: 핵심 개념 4가지 (현재 글) Part 3: Subagents · Workflows Part 4: AGENTS.md · Rules Part 5: MCP · Plugins · Skills (예정) Part 6: 자동화 Part 7: 마이그레이션 Part 8: 슬래시 명령어 정리(예정)

프롬프트(Prompting) — 좋은 지시의 4원칙
메모리(Memories) — AGENTS.md와 로컬 메모리
샌드박스(Sandboxing) — 3가지 권한 레벨 선택 가이드
모델(Models) — 어떤 모델을 언제 쓸까
정리: 4개 개념이 어떻게 연결되는가
Part 3 예고

4개 개념을 한 장으로 보면

개념	결정하는 것	흔한 실패
프롬프트(Prompting)	이번 작업의 목표와 완료 기준	범위가 넓어져 엉뚱한 파일까지 수정
메모리(Memories) / AGENTS.md	반복해서 지킬 배경 규칙	매번 같은 설명을 다시 하거나 팀 규칙을 놓침
샌드박스(Sandboxing)	Codex가 실제로 실행할 수 있는 경계	권한이 좁아 작업이 막히거나, 너무 넓어 위험해짐
모델(Models)	속도, 비용, 추론 깊이	가벼운 작업에 과한 모델을 쓰거나 복잡한 작업에 너무 약한 모델을 씀

초심자라면 순서를 이렇게 잡으면 편하다. 먼저 프롬프트로 할 일을 정한다. 반복해서 지켜야 할 규칙은 AGENTS.md에 둔다. 샌드박스로 Codex가 건드릴 수 있는 파일과 명령을 제한한다. 마지막으로 작업 난이도와 비용에 맞춰 모델을 고른다.

1. 프롬프트(Prompting) — 좋은 지시의 4원칙

Codex는 지시가 명확할수록 더 잘 작동한다.

프롬프트는 쉽게 말해 "Codex에게 보내는 작업 지시서"다. 공식 Prompting 문서에서는 검증 가능성, 작업 분해, 계획 요청, 스레드 같은 기본 개념을 설명한다. 이 글에서는 초심자가 바로 써먹기 쉽도록 4가지 원칙으로 나눠 보자.

Codex는 프롬프트를 받으면 모델을 호출하고, 파일을 읽거나 고치고, 도구를 실행하는 Loop를 반복한다. 작업이 끝났다고 판단하거나 내가 취소할 때까지다. 그러니 프롬프트에는 "무엇을 할지"와 함께 "언제 멈추는지"도 같이 적어두는 게 낫다.

1.1 검증 가능성(Verifiability): 결과를 확인할 수 있게 만든다

Codex는 자신의 작업을 확인할 방법이 있을 때 더 좋은 결과를 낸다.

버그를 다시 만드는 순서, 기능이 맞게 동작하는지 확인하는 방법, 린트나 프리커밋 체크 실행 방법을 함께 적어 줄수록 좋다. 여기서 린트는 코드 스타일과 흔한 실수를 자동으로 검사하는 도구이고, 프리커밋 체크는 커밋 전에 자동으로 돌리는 검사라고 보면 된다.

단순히 "이 버그를 고쳐라"보다 "버그를 고친 후 npm test로 회귀 테스트가 통과하는지 확인하라"처럼 검증 조건을 명시하면 Codex가 스스로 작업 완성 여부를 판단할 수 있다. 회귀 테스트는 고친 문제가 다시 생기지 않는지 확인하는 테스트이다.

1.2 작업 분해(Task Decomposition): 작게 나눌수록 잘 처리한다

복잡한 작업은 작게 나눌수록 Codex가 더 잘 처리한다. 예를 들어 "게시판을 개선해줘"보다 "검색 버그를 고치고, 그다음 빈 결과 화면 문구를 바꿔줘"처럼 나누는 식이다. 작은 단위의 작업은 Codex가 테스트하기도 쉽고, 개발자가 결과를 검토하기도 쉽다.

분해 방법을 모른다면, 직접 분해하지 않아도 된다.

1.3 계획 먼저(Plan First): 분해가 막히면 계획을 먼저 요청한다

분해 방법이 막힐 때는 Codex에게 먼저 계획을 제안하게 하면 된다. 그러면 Codex가 접근 순서를 먼저 정리하고, 개발자는 그 계획을 보고 다음 구현 지시로 이어갈 수 있다.

예를 들어 "이 기능을 추가할 계획을 먼저 만들어라. 구현은 내가 검토한 뒤 진행하겠다"처럼 지시하면, 실행 전에 방향을 조율할 수 있다.

Plan mode는 초심자에게 특히 중요하다

/plan으로 현재 대화를 계획 모드로 바꿀 수 있다.
큰 리팩토링, 마이그레이션, 원인 모르는 장애처럼 바로 수정하면 위험한 일은 먼저 /plan으로 접근하는 편이 안전하다.
현재 CLI에서는 Shift+Tab으로 모드를 전환할 수 있는 환경도 있지만, 단축키는 키맵에 따라 바뀔 수 있다.

ex) shift + tab 으로 모드를 변경 가능하며 계획을 먼저 세우게 된다. (너무 간단한 내용은 바로 수행하기도 한다.)

- 계획을 세워주며

- 해당 계획대로 수행할지, 쌓여있는 context를 비우고 수행할지, 플랜모드를 통해 계속 계획모드를 개선할지 등 선택 가능하다.

1.4 컨텍스트 제공(Context): 관련 파일과 이미지를 함께 넣는다

프롬프트를 제출할 때 관련 파일, 이미지 같은 컨텍스트를 함께 넣어야 한다. 컨텍스트는 Codex가 답을 만들 때 참고하는 배경 자료다. Codex IDE 확장을 쓴다면 열린 파일 목록과 선택된 텍스트 범위가 자동으로 컨텍스트에 포함된다.

CLI에서는 스레드(thread) 개념을 이해하면 컨텍스트 관리가 쉬워진다. (어려운 용어면 데충 넘어가자)

CLI는 터미널에서 명령어로 쓰는 방식이고, 스레드는 "Codex의 한 번의 작업 세션"에 가깝다. 처음 보낸 프롬프트, Codex의 답변, 도구 실행 기록이 한 스레드 안에 쌓인다. 한 스레드 안에 여러 프롬프트를 이어서 넣을 수 있고, 나중에 이어서 재개할 수도 있다.

다만 여러 스레드를 동시에 돌릴 때는 주의해야 한다.

공식 문서는 여러 스레드를 동시에 실행할 수는 있지만, 두 스레드가 같은 파일을 동시에 수정하지 않도록 피하라고 안내한다.

초심자라면 한 작업이 끝난 뒤 다음 작업을 맡기는 방식이 가장 안전하다.

스레드는 실행 위치에 따라 로컬 스레드와 클라우드 스레드로도 나눠 볼 수 있다.

로컬 스레드는 내 컴퓨터에서 샌드박스 안에 실행되고, 클라우드 스레드는 저장소를 별도로 가져와 원격 환경에서 작업한다.

처음에는 로컬에서 흐름을 익히고, 병렬 작업이나 위임이 필요해졌을 때 클라우드 작업을 보는 편이 이해하기 쉽다.

CLI 컨텍스트 팁: IDE 확장은 열린 파일과 선택한 코드가 자동으로 컨텍스트에 들어가는 편이다. CLI에서는 보통 파일 경로를 직접 적거나, /mention <path>로 관련 파일을 현재 대화에 붙이는 것이 좋다.

프롬프트 예시 5가지

상기 이미지 처럼 하고자 하는 내용을 잘 설명 하면 되는게 프롬프트가 아닐까?

( 모르는 것은 AI에게 도움을 받고, 내가 잘 설명할수있는것은 잘 설명 하는 것??)

5개의 예시로 상기 내용을 이해해보자.

왜 영문 프롬프트인가?

Codex를 포함한 대부분의 AI 코딩 도구는 영문 프롬프트에서 더 정확하고 일관된 결과를 낸다.

학습 데이터의 대부분이 영어 코드베이스·문서이기 때문이다.

실제 사용 시에는 영문으로 작성하는 것을 권장한다. 다만 처음 접하는 독자의 이해를 돕기 위해 각 예시 아래에 한글 번역을 함께 제공한다.

예시 1 — 프로젝트 분석 (Workflows 문서 제공 예시)

Explain how the request flows through the selected code.

Include:
- a short summary of the responsibilities of each module involved
- what data is validated and where
- one or two "gotchas" to watch for when changing this

한글로 이해하기

선택한 코드를 통해 요청이 어떻게 흐르는지 설명해줘.

포함할 내용:
- 관련된 각 모듈의 역할 요약
- 어디서 어떤 데이터가 검증되는지
- 이 부분을 수정할 때 주의해야 할 함정 1~2가지

단순히 "이 코드를 설명해라"보다 포함할 항목을 명시하면 Codex가 더 유용한 분석을 돌려준다.

예시 2 — 기능 추가 (Prompting 문서 제공 예시)

Add a new command-line option `--json` that outputs JSON.

한글로 이해하기

JSON을 출력하는 새 커맨드라인 옵션 `--json`을 추가해줘.

범위가 명확한 요청이다. 새 옵션의 이름과 동작을 한 줄로 정했기 때문에 Codex가 어디서부터 어디까지 작업해야 하는지 판단하기 쉽다.

예시 3 — 디버깅 (Workflows 문서 제공 예시)

Bug: Clicking "Save" on the settings screen sometimes shows "Saved" but doesn't persist the change.

Repro:
1) Start the app: npm run dev
2) Go to /settings
3) Toggle "Enable alerts"
4) Click Save
5) Refresh the page: the toggle resets

Constraints:
- Do not change the API shape.
- Keep the fix minimal and add a regression test if feasible.

Start by reproducing the bug locally, then propose a patch and run checks.

한글로 이해하기

버그: 설정 화면에서 "저장" 버튼을 누르면 "저장됨"이 표시되는데,
실제로는 변경사항이 유지되지 않는 경우가 있다.

재현 방법:
1) 앱 실행: npm run dev
2) /settings 이동
3) "알림 활성화" 토글
4) 저장 클릭
5) 페이지 새로고침 → 토글이 원래대로 돌아옴

제약 사항:
- API 구조는 변경하지 않는다.
- 수정은 최소한으로 하고, 가능하면 회귀 테스트를 추가한다.

버그를 로컬에서 먼저 재현한 다음, 패치를 제안하고 검사를 실행한다.

이 예시가 잘 작동하는 이유는 세 가지다. 재현 단계를 구체적으로 적었고, 건드리면 안 되는 범위를 못 박았고, Codex가 먼저 문제를 재현한 뒤 패치를 제안하도록 순서를 정했다.

예시 4 — 리팩토링 전 계획 세우기 (/plan 응용)

/plan Refactor the payment validation flow safely.

Start by reading the current validation path and tests.
Do not edit files yet.

Return:
- files that probably need changes
- behavior that must stay the same
- risks and edge cases
- the smallest implementation steps
- tests to run before and after the change

한글로 이해하기

/plan 결제 유효성 검사 흐름을 안전하게 리팩토링한다.

현재 유효성 검사 경로와 테스트를 먼저 읽는다.
아직 파일을 편집하지 않는다.

반환할 내용:
- 변경이 필요할 가능성이 있는 파일
- 그대로 유지해야 하는 동작
- 위험 요소와 엣지 케이스
- 가장 작은 구현 단계
- 변경 전후에 실행할 테스트

이런 프롬프트는 "바로 고쳐줘"보다 안전하다. Codex가 먼저 영향 범위와 테스트 기준을 정리하므로, 개발자는 계획을 보고 범위를 줄이거나 빠진 조건을 보완한 뒤 실행으로 넘어갈 수 있다.

예시 5 — 실패한 테스트를 기준으로 원인 좁히기

Test failure:
- command: pnpm test -- auth
- failing test: should refresh an expired session token
- error: expected 200, received 401

Goal:
Find the root cause and make the smallest safe fix.

Constraints:
- Do not change the public API response shape.
- Do not rewrite the auth module.
- Add or update one regression test if the fix changes behavior.

Completion:
Run the focused auth test, then tell me what changed and why.

한글로 이해하기

테스트 실패:
- 명령어: pnpm test -- auth
- 실패 테스트: 만료된 세션 토큰을 갱신해야 한다
- 오류: 200 예상, 401 수신

목표:
근본 원인을 찾고 가장 작고 안전한 수정을 한다.

제약 사항:
- 공개 API 응답 형태를 변경하지 않는다.
- auth 모듈을 재작성하지 않는다.
- 수정이 동작을 바꾼다면 회귀 테스트를 하나 추가하거나 업데이트한다.

완료 기준:
집중 auth 테스트를 실행하고, 무엇이 왜 바뀌었는지 알려준다.

개발자에게 가장 와닿는 프롬프트는 보통 실패한 명령, 실패한 테스트 이름, 바꾸면 안 되는 계약, 완료 조건을 함께 준다. 이렇게 쓰면 Codex가 "대충 고쳐 보기"보다 원인을 좁혀서 움직이기 쉽다.

더 많은 프롬프트 패턴은 공식 Workflows 문서에서 확인한다.

초심자용 프롬프트 점검표

목표: 무엇을 고치거나 만들 것인지 한 문장으로 적었는가?
맥락: 관련 파일, 화면, 오류 메시지, 재현 단계를 줬는가?
제약: 바꾸면 안 되는 API, UI 문구, 파일 범위를 적었는가?
완료 기준: 어떤 테스트나 확인이 통과해야 끝인지 적었는가?

1.5 따라 해보는 실전 튜토리얼 프롬프트 3가지

앞의 예시들은 실무 코드베이스에서 쓰는 방식이었다. Codex가 처음이거나 개발을 막 시작한 사람이라면 어디서부터 써야 할지 막막할 수 있다. 여기서는 "지금 바로 따라 해볼 수 있는" 시나리오 세 가지를 프롬프트 한 줄씩 뜯어보면서 설명한다.

공통 패턴: 세 예시 모두 같은 구조를 따른다 — 목표(Goal) → 설정(Setup) → 기능/규칙 → 제약(Constraints) → 완료 기준(Completion). 이 순서를 익히면 어떤 작업에도 응용할 수 있다.

"넌 전문가야" — 꼭 써야 하나?

예전에 ChatGPT 쓸 때 "넌 시니어 개발자야", "넌 HTML/CSS 전문가야" 같은 역할 주입을 많이 했다. 효과가 있었다. 지시가 모호하니까 역할로 방향을 잡으려던 거다.

Codex 같은 에이전트 도구에서는 점점 안 써도 되는 방향으로 흐르고 있다. 이유는 단순하다. Constraints가 페르소나보다 정확하게 범위를 잡아준다.

"넌 바닐라 JS 전문가야"는 스타일 힌트다. 반면 "외부 라이브러리 없이 index.html 하나로 동작해야 한다"는 범위 제한이다. Codex는 후자를 훨씬 잘 따른다.

페르소나가 여전히 쓸모 있는 경우는 있다. 설명 수준("초보자에게 설명하듯 주석을 달아라"), 피드백 스타일("시니어 코드 리뷰 스타일로"), 특정 관점("프론트엔드 입장에서 UX 문제를 찾아라") 같은 뉘앙스는 Constraints로 잡기 어렵다. 코드 생성 작업이라면 Goal + Constraints + Completion이 "넌 전문가야" 한 줄보다 낫다.

그런데… 꼭 이렇게 써야 할까?

지금까지 설명한 구조화된 프롬프트는 분명히 효과가 있다. 하지만 반대 관점도 있다. 모델이 계속 발전하면서, 오히려 규칙을 모르는 채로 자유롭게 바이브 코딩(vibe coding)하는 사람들이 더 창의적인 결과를 낸다는 이야기가 나온다. 머릿속에 있는 걸 그냥 말하듯 던지면, 모델이 알아서 채워준다는 것이다.

어느 쪽이 맞다기보다, 모델이 강해질수록 프롬프트의 최소 요건이 낮아진다는 말이 더 정확하다. 구조를 알면 정확하게 쓸 수 있고, 몰라도 일단 시작할 수 있다. 아래 예시에서는 두 가지 버전을 모두 보여준다. 먼저 구조화된 프롬프트로 어떻게 작동하는지 보고, 그다음 한두 줄짜리 바이브 버전으로 여러분이 직접 해보자.

예시 A — HTML 파일 하나로 게임 만들기

요즘 LLM은 숫자 맞추기 같은 간단한 게임을 넘어선 지 오래다. 갤러그, 1945 스타일의 슈팅 게임도 싱글 프롬프트 하나면 동작하는 코드가 나온다. 모델이 얼마나 발전했는지 직접 체감하고 싶다면, 이 예시부터 시작해보자. HTML 파일 하나를 브라우저로 열기만 하면 된다.

Goal:
싱글 HTML 파일로 갤러그 스타일 우주 슈팅 게임을 만들어라.

Rules:
- 플레이어 우주선은 좌우 방향키(또는 A/D)로 이동, 스페이스바로 총알 발사
- 적 우주선은 위에서 아래로 내려오며 화면 하단에 닿으면 게임 오버
- 총알이 적에게 맞으면 적이 사라지고 점수가 오른다
- 웨이브마다 적 생성 속도가 빨라진다
- 플레이어는 목숨 3개 — 적과 충돌 시 1개 감소
- 화면 상단에 점수와 남은 목숨 표시
- 게임 오버 시 최고 점수와 함께 "다시 시작" 화면 표시

Constraints:
- HTML, CSS, JavaScript를 index.html 파일 하나에 모두 작성한다
- 외부 라이브러리 없이 브라우저에서 파일을 열기만 해도 동작해야 한다
- Canvas API로 렌더링한다

Completion:
index.html을 크롬으로 열어 적 5마리를 격추하고,
일부러 적과 충돌해 목숨이 줄어드는지 확인한다.
"다시 시작"을 눌러 점수가 초기화되는지 확인한다.

프롬프트 줄별 해설

Goal: "게임 만들어줘"보다 "갤러그 스타일 우주 슈팅 게임"이 구체적이다. 레퍼런스 타이틀 하나로 UI·조작감·난이도 흐름까지 Codex가 공통 인식을 갖는다.
Rules (목록으로): 조작키, 충돌 판정, 목숨 수를 미리 못 박지 않으면 Codex가 임의로 채운다. 나중에 "왜 목숨이 5개야"라며 다시 고치는 수고를 줄인다.
Constraints의 핵심 줄: "Canvas API로 렌더링한다" — 이 줄을 빠뜨리면 Codex가 DOM 엘리먼트를 CSS로 움직이는 방식을 택할 수 있다. 게임 루프가 필요한 작업엔 렌더링 방식을 명시하는 게 낫다.
Completion: "동작 확인"이 아니라 "적 5마리 격추 → 충돌 → 다시 시작"처럼 검증 시나리오를 구체적으로. Codex가 어떤 흐름으로 테스트해야 하는지 알 수 있다.

여러분이 직접 해보자 — 바이브 코딩 버전

구조 몰라도 된다. 이 두 줄을 그대로 Codex에 붙여넣고 어떤 결과가 나오는지 확인해보자.

갤러그 스타일 우주 슈팅 게임을 HTML 파일 하나로 만들어줘.
방향키로 움직이고 스페이스바로 쏘는 거야. 외부 라이브러리 없이.

ex) 결과 캡쳐

- 3분 34초 만에 개발 완료 하였다.

- 사용 모델 5.5 / reasoning effort : high / fast 모드 사용

(지금은 모델을 알 필요 없다. 모델과 관련된 자세한 내용은 단락 4에 작성해 두었다.)

예시 B — React로 할 일 목록 앱 만들기

처음 React를 배울 때 가장 많이 만드는 게 할 일 목록이다. 상태 관리와 이벤트 처리 두 가지를 익히기에 딱 맞다. 백엔드는 없어도 된다.

Goal:
Vite + React로 간단한 할 일 목록(To-do) 앱을 만들어라.

Setup:
프로젝트가 없다면 아래 명령으로 만든다:
  npm create vite@latest my-todo-app -- --template react
  cd my-todo-app && npm install

Features:
- 입력창에 할 일을 입력하고 버튼(또는 Enter)으로 추가한다
- 각 항목에 완료 체크박스와 삭제 버튼이 있다
- 완료된 항목은 텍스트에 취소선이 생긴다

Constraints:
- 상태 관리는 useState만 쓴다 (Redux, Context, Zustand 불필요)
- 백엔드와 데이터베이스 없이 컴포넌트 상태로만 동작한다
- 스타일은 App.css 파일 하나에 간단히 작성한다

Completion:
npm run dev 실행 후 http://localhost:5173 에서
할 일 추가 → 체크 → 삭제 순서로 동작하는지 확인한다.

프롬프트 줄별 해설

Setup 줄: "Vite + React"로 기술 스택을 고정했다. 이 줄이 없으면 Codex가 Create React App, Next.js, Parcel 중에서 하나를 알아서 골라 만들어 온다. 처음엔 어떤 차이인지 파악하기 어려우니 그냥 막막해진다.
Features의 구체성: "CRUD 기능을 구현해라"보다 "버튼 또는 Enter로 추가, 체크박스로 완료, 삭제 버튼"처럼 UI 동작을 써주면 Codex가 빠뜨리는 기능이 줄어든다.
Constraints의 핵심 줄: "useState만 쓴다"와 "백엔드 없이". 이 두 줄을 빠뜨리면 Redux Toolkit에 Firebase까지 붙여 오는 경우가 생긴다. 초보자에겐 지금 당장 필요 없는 것들이다.
Completion: "추가 → 체크 → 삭제 순서로"처럼 시나리오를 주면 Codex가 어떤 흐름으로 테스트해야 하는지 명확하게 안다.

여러분이 직접 해보자 — 바이브 코딩 버전

구조 몰라도 된다. 이 한 줄을 그대로 Codex에 붙여넣어 보자.

React로 할 일 목록 앱 만들어줘. 추가, 완료 체크, 삭제 되는 거. useState만 써.

ex) 결과 요약

- 직접 서버를 띄우고, 브라우저까지 띄워 테스트 완료 하였다.

- 완료 결과 보고

- 직접 브라우저로 결과 확인

예시 C — Next.js로 간단한 소개 페이지 만들기

Next.js는 React 기반 프레임워크다. 배포가 쉽고 SEO 설정이 편리해 개인 포트폴리오나 소개 페이지를 만들 때 많이 쓴다. 백엔드 없이 정적 페이지 2개만 만드는 것부터 시작하자.

Goal:
Next.js로 간단한 개인 소개 사이트를 만들어라.

Setup:
프로젝트가 없다면 아래 명령으로 만든다:
  npx create-next-app@latest my-profile --app --tailwind --no-src-dir --no-typescript
  cd my-profile

Pages:
- app/page.js (홈): 이름, 한 줄 소개, 간단한 자기소개 문단
- app/about/page.js (소개): 기술 스택 목록 (HTML, CSS, JavaScript 등)

Navigation:
- 상단에 "홈"과 "소개" 페이지를 오가는 링크를 넣는다

Constraints:
- 데이터베이스 없음, 로그인 없음, 서버 API 없음
- 정적 페이지 2개와 nav만 만든다
- Tailwind CSS로 간단히 스타일을 입힌다

Completion:
npm run dev 후 홈과 소개 페이지 이동이 되는지,
nav 링크가 양쪽 방향으로 동작하는지 확인한다.

프롬프트 줄별 해설

Setup 플래그들: --app(App Router 사용), --tailwind(Tailwind 포함), --no-typescript(TypeScript 제외). 플래그를 생략하면 Codex가 추측해서 TypeScript 파일로 만들어 올 수 있다. 초보자라면 TypeScript는 나중에 배워도 늦지 않는다.
Pages 줄: 파일 경로(app/page.js, app/about/page.js)를 명시했다. "소개 페이지도 만들어줘"보다 경로까지 주면 Codex가 어디에 파일을 만들지 결정하지 않아도 된다.
Constraints의 "없음 3가지": 데이터베이스 없음, 로그인 없음, 서버 API 없음. 이 세 줄이 핵심이다. 안 적으면 "소개 페이지"라는 말에 Codex가 서버 컴포넌트나 API Route까지 만들어 올 수 있다. 지금 필요한 건 정적 페이지뿐이다.
Completion의 "양쪽 방향으로": nav 링크를 홈→소개, 소개→홈 둘 다 눌러보라는 뜻이다. 이렇게 적으면 Codex가 한쪽 링크만 만들어두고 완료라고 할 가능성이 줄어든다.

여러분이 직접 해보자 — 바이브 코딩 버전

구조 몰라도 된다. 이 한 줄을 그대로 Codex에 붙여넣어 보자.

Next.js로 내 소개 페이지 만들어줘. 홈이랑 소개 탭 두 개, Tailwind로 예쁘게.

ex) 결과 요약

- 직접 서버를 띄우고, 브라우저까지 띄워 테스트 완료 하였다.

- 결과

- 한방에 끝내기 하쉽다면 여기서 계속 개선 사항을 요구하여 이어 나가면 된다.

ex) 지금 결과를 목 데이터로 채워도 상관없으니, 디자인 개선을 하고싶은데 사람인 스타일 또는 링크드인 스타일로 변경해줘

- 개선 결과

세 예시에서 반복된 패턴

기술 스택과 파일 구조를 명시하고, 제약 조건으로 범위를 좁히고, 완료 기준을 구체적으로 준다. 이 세 가지만 챙겨도 Codex가 "알아서 결정"하는 일이 크게 줄어든다.

2. 메모리(Memories) — AGENTS.md와 로컬 메모리

Codex에는 메모리와 AGENTS.md 같은 지속 지침이 따로 있다.

메모리는 이전 대화의 맥락을 이어 주고, AGENTS.md는 작업할 때 따라야 할 지침을 담는다.

둘 다 Codex에게 배경지식을 주지만, 쓰임새는 다르다.

( 해당 세션은 중요한 주제인데, 초반에 무겁게 다루기엔 어려운 내용이니 최대한 간단히 알아보고 나중에 자세히 다루기로 한다. )

2.1 AGENTS.md — 반복 규칙을 저장소에 남기는 장치

AGENTS.md는 Codex가 작업할 때 계속 참고하는 지침 파일이다.

예를 들면 "테스트는 이 명령으로 실행한다", "새 의존성(외부 라이브러리)은 함부로 추가하지 않는다" 같은 반복 규칙을 넣는다.

공식 Customization 문서와 AGENTS.md 가이드에 따르면 전역 지침, 저장소 지침, 하위 폴더 지침을 함께 사용할 수 있다.

구분	역할	이 글에서 기억할 것
전역 지침	개인 기본값	모든 프로젝트에서 유지하고 싶은 습관
저장소 지침	팀 공통 규칙	빌드·테스트 명령, 리뷰 기준, 금지 변경
하위 폴더 지침	특정 영역 규칙	프론트엔드, 백엔드, 문서 폴더처럼 영역별로 다른 기준

Codex는 전역 지침을 먼저 보고, 프로젝트 루트에서 현재 작업 폴더 방향으로 지침을 이어 붙인다.

이 글에서 필요한 수준은 여기까지다.

실제 파일 배치, 예외 파일, 길이 제한, Rules 정책처럼 팀 운영에 필요한 세부 내용은 별도 AGENTS.md · Rules 편에서 다루는 편이 낫다.

이 글의 경계: 여기서는 "AGENTS.md는 반복 규칙을 담는 배경 지침"이라는 역할만 잡는다. 구체적인 파일 배치, 예외 파일, 지침 길이 관리, 명령 실행 정책과 충돌 처리는 AGENTS.md · Rules 편의 본문 주제다.

AGENTS.md에 Karpathy의 4원칙 넣기

AGENTS.md를 어떻게 채울지 막막하다면 출발점으로 쓸 수 있는 원칙이 있다. 2026년 초 AI 연구자 Andrej Karpathy가 LLM 코딩의 반복 실패 패턴을 정리하면서 화제가 된 4가지 원칙이다. Forrest Chang이 이를 CLAUDE.md(Claude Code의 같은 역할 파일)로 만들어 공개했고, GitHub 10만 스타를 넘겼다. 이 원칙들은 AGENTS.md에도 그대로 적용된다.

코드 변경 시 4가지 원칙 (우선순위와 무관하게 모든 코드 변경 작업에 적용)

가정하지 말고 표면화하라 — 불확실하면 멈추고 묻는다. 해석이 여러 개면 모두 제시한다.
단순함이 우선 — 요청된 것만 구현한다. 추측성 추상화·유연성·방어 코드 금지.
외과적 변경 — 요청과 직접 연결되지 않은 줄은 건드리지 않는다. 본인이 만든 orphan만 정리한다.
검증 가능한 목표 — 작업 시작 전 성공 기준을 명시하고, 끝난 뒤 그 기준으로 자체 검증한다.

AGENTS.md에 넣으면 어떤 차이가 생기는지 두 가지 시나리오로 비교해본다. 아래 예시는 실제로 Codex에게 같은 프롬프트를 줬을 때 나오는 반응 차이다. (실제 결과 스크린샷은 직접 확인해보자.)

위치는 Codex로 작업할 프로젝트 폴더의 루트 경로에 추가하면 된다.

ex) 방금 생성한 NextJS 앱의 예시

비교 1 — 날짜 처리: 기존 라이브러리를 쓸까, 새로 설치할까

프롬프트: "결제 날짜를 'YYYY년 MM월 DD일' 형식으로 포맷하는 함수를 추가해줘"

AGENTS.md 없을 때

// Codex가 알아서 판단: "dayjs가 좋겠다"
// 먼저 설치하라고 안내하거나, 직접 package.json에 추가함
import dayjs from 'dayjs';

export function formatPaymentDate(date) {
  return dayjs(date).format('YYYY년 MM월 DD일');
}

프로젝트에 이미 date-fns가 있어도 Codex는 모른다. 새 의존성이 들어오고, 팀에서 "왜 갑자기 dayjs?"라는 리뷰 코멘트가 달린다.

AGENTS.md 있을 때

# AGENTS.md (저장소 루트)
## 의존성 규칙
- 날짜 처리는 이미 설치된 date-fns를 쓴다
- 새 npm 패키지를 추가하기 전에 반드시 물어봐라

// Codex가 AGENTS.md를 읽고: "date-fns를 써야 한다"
import { format } from 'date-fns';
import { ko } from 'date-fns/locale';

export function formatPaymentDate(date) {
  return format(new Date(date), 'yyyy년 MM월 dd일', { locale: ko });
}

새 의존성이 생기지 않고, 리뷰어가 따로 지적할 일도 없다. Karpathy의 "단순함이 우선" 원칙이 여기서 동작한다 — 이미 있는 것을 쓰고, 없으면 먼저 물어본다.

비교 2 — 버그 수정 후: 테스트를 자동으로 돌릴까, 안 돌릴까

프롬프트: "로그인 세션 만료 버그를 고쳐줘"

AGENTS.md 없을 때

Codex 응답:
"auth.js의 세션 만료 로직을 수정했습니다.
토큰 갱신 타이밍을 조정하면 문제가 해결될 것입니다."

→ 코드만 수정하고 완료 보고
→ 어떤 테스트도 실행하지 않음
→ 개발자가 수동으로 확인해야 함

AGENTS.md 있을 때

# AGENTS.md (저장소 루트)
## 테스트 규칙
- 코드 수정 후 반드시 `npm test -- auth`를 실행한다
- 테스트가 실패하면 수정하지 않고 결과를 먼저 보고한다

Codex 응답:
"auth.js를 수정했습니다. AGENTS.md에 따라 npm test -- auth를 실행합니다.

결과: 3 passed, 0 failed
수정이 기존 테스트를 깨뜨리지 않음을 확인했습니다."

→ 수정 후 자동으로 인증 관련 테스트 실행
→ 테스트 통과 여부를 스스로 확인하고 보고

Karpathy의 "검증 가능한 목표" 원칙이다. AGENTS.md에 "수정 후 테스트를 실행한다"고 적어두면, 개발자가 매번 프롬프트에 "테스트도 돌려봐"를 적을 필요가 없다.

AGENTS.md 시작 템플릿: 처음 만든다면 아래 내용을 저장소 루트에 AGENTS.md로 저장하고 프로젝트에 맞게 채워가면 된다.

# AGENTS.md

## 테스트
- 코드 변경 후 [테스트 명령]을 실행한다

## 의존성
- 새 패키지를 추가하기 전에 반드시 물어봐라

## 코딩 규칙
- 불확실한 부분이 있으면 구현 전에 먼저 물어봐라
- 요청에 없는 파일은 건드리지 않는다

2.2 로컬 메모리 — ~/.codex/memories/

메모리 파일은 Codex 홈 디렉토리 아래에 저장된다. 기본 위치는 ~/.codex/memories/다.

공식 Memories 문서에 따르면, 이 파일에는 이전 대화의 요약, 오래 유지할 항목, 최근 입력, 그 내용을 뒷받침하는 증거가 들어간다.

메모리에 들어가기 좋은 내용은 안정적인 개인 선호, 반복되는 작업 흐름, 기술 스택, 프로젝트 관례, 자주 겪는 함정이다. 반대로 반드시 지켜야 하는 규칙은 AGENTS.md나 저장소 문서에 둬야 한다.

메모리는 모든 대화가 끝나는 즉시 만들어지는 기능이 아니다.

Codex는 활성 작업이나 너무 짧은 세션은 건너뛸 수 있고, 비밀값은 생성된 메모리 필드에서 가린다.

또한 스레드가 충분히 유휴 상태가 된 뒤 백그라운드에서 업데이트될 수 있으며, 남은 사용량이 낮으면 백그라운드 메모리 생성이 건너뛰어질 수 있다. 방금 끝낸 대화가 바로 메모리에 보이지 않아도 이상한 상황은 아니다.

중요한 점은 메모리 파일을 Codex가 만들어 둔 기록으로 봐야 한다는 것이다.

사람이 확인하거나 검토할 수는 있지만, 의도적인 동작 변경의 기본 수단으로 삼지는 않는다. 그런 변경은 설정, config, AGENTS.md 같은 명시적인 지침으로 관리하는 편이 안전하다.

Codex가 비밀값을 가리더라도, Codex 홈 디렉토리나 메모리 파일을 다른 사람에게 공유하기 전에는 민감한 내용이 없는지 직접 살펴보는 것이 좋다.

Codex 앱과 TUI에서는 /memories 명령으로 현재 스레드가 기존 메모리를 사용할지, 이 스레드를 앞으로의 메모리 생성에 사용할지 조절할 수 있다. 단, 이 설정은 현재 스레드 기준이고 전역 메모리 설정 자체를 바꾸는 것은 아니다.

ex) /memories를 사용하지 않고 기억해달라고 자연어로 해보았다.

- 이번 테스트에서는 AGENTS.md 에 저장하는 모습.

- /memories 입력 해보자. 다음과 같이 나올 것이다. 엔터 입력 >> 관련 설명은 이후 [ 2.3 ] 으로 바로 넘어 가자.

- Yes > 엔터

- 다음 대화 세션부터 적용된다는데 이럴때 팁은 일단 세션 종류 후, 다시 codex로 신규 대화 세션을 열고 기존 대화를 이어가면된다.

- /exit 입력하여 완전히 빠져 나간후 codex 입력

- 새로 코덱스창이 열리면 >> /resume 을 입력 한다.

- 방금 하고있던 대화 내용을 확인하고 로드 하자.

- 아까 AGENTS.md 에 저장하던 마지막 대화 내용이 그대로 로드 되는것을 볼 수 있다.

- 기억해달라는 내용을 로컬 메모리에 저장하는 모습을 볼 수 있다.

2.3 메모리 활성화 방법과 주의사항

지역 제한 고지: 메모리 기능은 기본적으로 꺼져 있으며, 출시 시점 기준 유럽 경제 지역(EEA), 영국, 스위스에서는 사용할 수 없다.

활성화 방법은 두 가지다.

위에서 보여드린대로 /memories 를 대화창에서 입력하여 Codex 설정에서 켜거나,

~/.codex/config.toml의 [features] 테이블에 아래와 같이 추가하면 된다.

[features]
memories = true

2.4 AGENTS.md vs 메모리 — 언제 무엇을 쓸까

공식 문서는 이 구분을 분명히 한다. 반드시 지켜야 하는 팀 규칙은 AGENTS.md 또는 버전 관리되는 문서에 보관한다. 메모리는 편리한 개인 기억으로 보고, 꼭 지켜야 하는 규칙의 유일한 근거로 쓰지 않는다.

실전 기준으로 정리하면 이렇다.

상황	사용할 도구
팀 전체가 따라야 하는 린트 규칙	`AGENTS.md` (저장소 루트)
PR 전 실행할 체크 명령	`AGENTS.md` (저장소 루트)
내가 선호하는 패키지 관리 방식	`AGENTS.md` (전역)
지난 스레드에서 배운 패턴	메모리 (자동 축적)
이번 작업에서만 참고할 특정 파일	프롬프트 경로, CLI `/mention`, IDE `@파일명`

예를 들어 팀에서 "PR 전에 npm run lint와 npm test를 반드시 실행한다"는 규칙은 AGENTS.md에 둔다.

이 규칙은 팀원이 바뀌어도 유지되어야 하기 때문이다. 반대로 "나는 설명을 한국어로 길게 듣는 편을 선호한다"처럼 개인 습관에 가까운 내용은 전역 AGENTS.md나 메모리로 충분하다.

"오늘 이 버그만은 API 응답 형식을 바꾸지 말라"처럼 일회성 제약은 프롬프트에 직접 쓰는 편이 가장 명확하다.

기억할 기준: 반복해서 지켜야 하는 팀 규칙은 AGENTS.md, 개인화된 작업 습관은 메모리, 이번 작업에만 적용되는 조건과 참고 파일은 프롬프트에 둔다. 명령 실행 정책처럼 더 구체적인 운영 규칙은 AGENTS.md · Rules 편에서 따로 다룬다.

3. 샌드박스(Sandboxing) — 3가지 권한 레벨 선택 가이드

Codex는 파일 접근과 명령 실행 권한을 샌드박스로 제어한다.

샌드박스는 말 그대로 안전 울타리다.

Codex가 내 컴퓨터 안에서 어디까지 읽고, 어디까지 수정하고, 어떤 명령을 실행할 수 있는지 정한다. 공식 Sandboxing 문서는 샌드박스의 목적을 "승인 피로 감소"로 설명한다. 여기서 승인 피로는 쉬운 명령마다 "허용할까요?"를 반복해서 묻는 바람에 사람이 지치는 상황을 말한다.

샌드박스는 위험이 낮은 작업은 정해진 울타리 안에서 진행하게 하고, 위험한 작업은 따로 막거나 확인받게 만든다.

여기서 자주 헷갈리는 부분이 있다. 샌드박스와 승인 정책은 같은 말이 아니다. 샌드박스는 Codex가 넘으면 안 되는 기술적인 경계이고, 승인 정책은 그 경계를 넘거나 특정 명령을 실행하려 할 때 사용자에게 물어볼지를 정하는 규칙이다. Codex가 git, 패키지 매니저, 테스트 러너 같은 명령을 실행할 때도 이 경계가 적용된다.

질문을 이렇게 바꿔 보자: "어떤 옵션이 있나?"보다 "이번 작업에서 Codex가 어디까지 해도 되나?"가 중요하다. 읽기만 시킬 작업, 파일을 고치게 할 작업, 패키지 설치까지 필요한 작업은 서로 다른 안전 울타리가 필요하다.

3.1 3가지 샌드박스 레벨

레벨	동작	기본 시작점	적합한 상황
`read-only`	파일을 읽어 분석하는 데 초점을 둔다. 수정이나 명령 실행은 제한된다	아님	코드 분석, 리뷰만 할 때
`workspace-write`	파일 읽기와 작업 폴더 안의 수정이 가능하다. 폴더 밖 작업이나 위험한 명령은 승인 정책을 따른다	권장 시작점	로컬 개발 일반 작업
`danger-full-access`	안전 울타리를 거의 푼다. 내 컴퓨터 파일과 네트워크 접근 제한이 크게 줄어든다	아님	Codex에 전체 접근 권한이 필요할 때만

한 줄로 요약하면: 처음에는 workspace-write + approval_policy = "on-request" 조합이 가장 무난하다.

프로젝트 폴더 안에서 고치는 일은 맡기되, 경계를 넘는 일은 물어보게 만드는 조합이기 때문이다.

danger-full-access는 정말 전체 권한이 필요할 때만 의도적으로 선택한다.

선택이 헷갈리면 아래 순서로 판단한다.

질문	권장 선택	이유
낯선 저장소를 읽기만 할 것인가?	`read-only`	수정 없이 구조만 파악하므로 울타리를 좁게 둔다.
현재 프로젝트 안에서만 파일을 고치면 되는가?	`workspace-write` + `on-request`	일반 개발 작업의 기본값이다. 폴더 밖 작업처럼 애매한 일만 따로 물어보게 한다.
다른 폴더도 일부 수정해야 하는가?	`writable_roots`	전체 권한을 열기보다 필요한 폴더만 추가로 연다.
사람 확인 없이 전체 권한 자동화가 필요한가?	전용 VM, 컨테이너, CI runner에서만 검토	로컬 작업 폴더에서 바로 쓰면 피해 범위가 커진다.

ex1) code --sandbox read-only

- 수정자체가 불가능한건 아니다. 수정시 권한을 요청한다.

- 권한 요청

ex2) code --sandbox workspace-write

- 해당 프로젝트 내에서는 수정이 가능하다.

- 별도의 권한 요청 없이 수정 완료 하였다.

3.2 승인 정책과의 조합

샌드박스 레벨은 승인 정책(approval_policy)과 함께 설정한다. 승인 정책은 Codex에게 언제 "물어보고 진행할지"를 정하는 옵션이다. 공식 문서에서 말하는 대표 정책은 untrusted, on-request, never다.

승인 정책	의미
`untrusted`	안전하다고 판단된 명령만 바로 실행하고, 나머지는 확인을 요청
`on-request`	샌드박스 안에서는 진행하고, 울타리 밖으로 나가려 할 때 확인을 요청
`never`	승인 질문을 하지 않는다. 실패하면 Codex가 그 결과를 보고 다음 방법을 찾는다

공식 문서에서 제시하는 두 가지 대표 조합은 다음과 같다.

완전 자동화 (주의 필요)

sandbox_mode = "danger-full-access"
approval_policy = "never"

저위험 로컬 자동화 (권장 시작점)

sandbox_mode = "workspace-write"
approval_policy = "on-request"

또는 CLI 플래그로 동일하게 설정할 수 있다.

codex --sandbox workspace-write --ask-for-approval on-request

작업 폴더 외의 다른 폴더도 함께 수정해야 한다면 무조건 danger-full-access로 올릴 필요는 없다.

공식 설정 문서 기준으로는 sandbox_workspace_write.writable_roots에 추가로 열어둘 폴더를 좁게 지정할 수 있다.

예를 들어 현재 프로젝트 밖의 공유 폴더 하나만 필요하다면, 전체 컴퓨터를 열기보다 그 폴더만 추가로 열어 주는 식이다.

초심자에게는 "필요한 폴더만 열어준다"는 감각이 중요하다.

3.3 config.toml 우선순위와 권한 프로필

샌드박스와 승인 정책은 대부분 config.toml에서 기본값으로 둔다.

개인 기본값은 ~/.codex/config.toml에 두고, 프로젝트별 예외는 저장소 안의 .codex/config.toml에 둘 수 있다. 단, 프로젝트 설정은 신뢰한 프로젝트에서만 로드된다.

우선순위도 알아두면 헷갈리지 않는다.

공식 문서 기준으로는 CLI 플래그와 --config가 가장 강하고, 그다음이 profile, 프로젝트 설정, 사용자 설정, 시스템 설정, 기본값 순서다. 즉, 오늘 한 번만 다르게 실행하려면 CLI 플래그를 쓰고, 계속 유지할 기본값은 config에 넣는 식으로 나누면 된다.

권한 설정을 매번 직접 조합하기 번거롭다면 default_permissions를 사용할 수 있다. 여기서 헷갈리기 쉬운 말이 permission profile이다. 쉽게 말해 permission profile은 여러 권한 설정을 묶어 놓은 프리셋에 가깝고, sandbox mode는 그중 "파일과 명령을 어디까지 허용할지"를 정하는 한 항목이다.

read-only, workspace-write, danger-full-access는 sandbox mode 이름이고, default_permissions = "workspace" 같은 값은 여러 설정을 묶어 고르는 예시로 읽으면 된다. 처음에는 제한이 있는 설정부터 시작한다.

주의: danger-full-access + approval_policy = "never" 조합은 Codex가 거의 모든 작업을 확인 없이 실행하게 만든다. 실험용 폴더처럼 충분히 통제된 환경에서만 쓰는 편이 안전하다.

4. 모델(Models) — 어떤 모델을 언제 쓸까

모델은 Codex 안에서 실제로 답을 만들고 판단하는 AI 엔진이다. 같은 Codex라도 어떤 모델을 쓰느냐에 따라 속도, 비용, 얼마나 깊게 따져 보는지가 달라진다. Codex가 사용하는 모델은 공식 Models 문서에서 확인한다. 2026년 5월 기준 Codex에서 주로 선택하는 모델은 다음과 같다.

4.1 모델 비교

모델	특성	적합한 상황
`gpt-5.5`	최신 고성능 모델, 복잡한 코딩·컴퓨터 사용·문서 작업·연구 흐름	대부분의 작업 — 시작점으로 권장
`gpt-5.4`	고성능 모델, 깊은 추론·도구 사용·에이전트 작업에 강함	전문성이 필요한 복잡한 작업
`gpt-5.4-mini`	빠르고 효율적인 미니 모델	빠른 코딩 반복, 작은 역할을 맡는 서브에이전트
`gpt-5.3-codex`	코딩에 특화된 모델, gpt-5.4의 코딩 능력을 뒷받침	복잡한 개발 작업
`gpt-5.3-codex-spark`	텍스트 중심의 빠른 리서치 프리뷰 모델	거의 즉각적인 코딩 반복. ChatGPT Pro 사용자 대상

한 줄로 요약하면: 일반 작업은 gpt-5.5로 시작하고, 가볍고 빠른 반복이 필요하면 gpt-5.4-mini를 선택한다. 단, 공식 문서는 gpt-5.5가 ChatGPT 로그인으로 사용할 때 제공되며, API 키 인증에서는 사용할 수 없다고 안내한다. 계정에 아직 보이지 않는다면 gpt-5.4를 쓰면 된다.

gpt-5.2는 깊은 디버깅을 포함한 코딩·에이전트 작업에 쓸 수 있는 이전 범용 모델이다. 지금 새로 시작하는 초심자라면 먼저 위 표의 추천 모델을 보고, 특별한 이유가 있을 때만 이전 모델을 선택하는 편이 단순하다.

ex) 가장 기본적인 변경 방법

- /model 입력 > 나오는 선택 화면에서 위아래로 움직여 모델을 선택한다.

- effort 수준을 선택하는 화면인데 하기에 상세 내용은 작성해 두었다.

- 선택된 모델 및 추론 레벨을 확인 가능하다.

모델 선택은 "가장 센 모델 하나만 고르면 끝"이 아니다. 작업의 성격이 다르면 적절한 모델도 달라진다.

작업	추천 방향	판단 이유
작은 파일 수정, 문구 변경, 빠른 탐색	`gpt-5.4-mini`	빠른 응답과 비용 효율이 더 중요하다.
여러 파일을 바꾸는 기능 구현	`gpt-5.5` 또는 `gpt-5.4`	맥락을 길게 유지하고 설계 판단이 필요하다.
원인 추적이 어려운 버그, 아키텍처 검토	강한 모델 + 높은 reasoning effort	속도보다 추론 깊이와 검증 계획이 중요하다.
여러 보조 에이전트에게 나눠 맡기는 반복 작업	가벼운 모델을 역할별로 사용	각 역할이 작고 독립적이면 빠른 모델이 효율적이다.

ex) 하나의 작업을 진행할때 여러가지 모델을 사용하여 작업하는 예시

- 메인 세션 : gpt 5.5 xhigh

- 작업을 수행하는 서브 에이전트 세션 예시

4.2 모델 지정과 reasoning effort

CLI에서는 시작할 때 --model로 모델을 지정한다. 공식 모델 예시에는 같은 뜻의 짧은 옵션인 -m도 함께 나온다. 플래그는 명령어 뒤에 붙여 동작을 바꾸는 옵션이다.

codex --model gpt-5.5 "이 모듈의 구조를 분석해라"

config.toml에 기본 모델을 설정할 수도 있다.

model = "gpt-5.5"

지원되는 모델에서는 생각의 깊이를 조절하는 model_reasoning_effort도 설정할 수 있다. 공식 Config Reference 기준 선택지는 minimal, low, medium, high, xhigh다. 단 xhigh는 모든 모델에서 되는 값이 아니라 모델 의존 옵션으로 안내되어 있다.

model_reasoning_effort = "high"

값	초심자용 의미	적합한 작업	주의점
`minimal`	생각을 거의 늘리지 않는 가장 가벼운 설정	짧은 요약, 단순 분류, 파일명 목록 정리	코드 수정이나 추론이 필요한 작업에는 부족할 수 있다
`low`	속도를 우선하는 낮은 추론	반복 수정, 간단한 리팩터링 후보 탐색	엣지 케이스를 놓칠 가능성이 있다
`medium`	속도와 판단 깊이의 균형	대부분의 일반 코딩, 문서화, 리뷰 초안	기본값으로 보기 좋지만 어려운 버그에는 올려볼 수 있다
`high`	가정을 더 많이 점검하는 깊은 추론	복잡한 버그, 설계 검토, 보안·권한 검토	응답이 느려지고 사용량도 커질 수 있다
`xhigh`	가능한 모델에서만 쓰는 더 깊은 추론	아키텍처 결정, 장기 리팩터링 계획, 원인 추적이 어려운 장애 분석	모델 의존 옵션이므로 안 되면 `high`로 낮춘다

클라우드 태스크 주의: 모델 선택과 사용 한도는 모델, 플랜, 그리고 로컬/클라우드 실행 여부에 따라 달라진다. 공식 Models 문서 기준으로, 클라우드 태스크의 기본 모델은 현재 사용자가 직접 바꾸지 못한다. 반면 로컬 CLI에서는 시작할 때 --model/-m으로 지정하고, 실행 중에는 /model로 바꿀 수 있다.

4.3 Fast mode와 Codex-Spark는 다르다

여기서 헷갈리기 쉬운 것이 Fast mode다.

Fast mode는 별도 모델명이 아니라, 지원 모델을 더 빠른 서비스 티어로 실행하는 속도 설정이다.

공식 Speed 문서 기준으로 Fast mode는 지원 모델 속도를 약 1.5배 높이고, 그 대신 크레딧을 더 빠르게 소모한다.

2026년 5월 기준 지원 모델과 배율은 다음처럼 공개되어 있다.

구분	공식 문서 기준	실전 해석
Fast mode	GPT-5.5와 GPT-5.4를 더 빠르게 실행. GPT-5.5는 표준 대비 2.5배, GPT-5.4는 2배 크레딧 소모	급하게 결과가 필요할 때만 켠다. 계속 켜두면 사용 한도가 빨리 줄어든다.
Codex-Spark	별도 빠른 모델. 연구 프리뷰이며 ChatGPT Pro 사용자 대상	Fast mode처럼 기존 모델을 가속하는 것이 아니라, 빠른 반복용 모델을 고르는 것이다.
설정 방법	`/fast on`, `/fast off`, `service_tier = "fast"`	작업 단위로 켜고 끄는 습관이 좋다. 기본값으로 고정하기 전에는 사용량을 먼저 본다.

service_tier = "fast"

[features]
fast_mode = true

API 키로 실행하는 경우에는 Fast mode 크레딧 체계가 아니라 표준 API 과금으로 처리된다는 점도 구분한다.

즉 "빠르게 하고 싶다"는 요구가 항상 Fast mode를 뜻하지 않는다.

단순 작업이면 먼저 작은 모델이나 낮은 reasoning effort를 쓰고, 그래도 지연이 문제일 때 Fast mode를 검토하는 순서가 낫다.

4.4 사용량과 비용은 모델명만으로 결정되지 않는다

요금과 사용량 제한은 모델명만으로 고정되지 않는다.

ChatGPT 플랜, API 키 사용, GitHub에서 실행되는 코드 리뷰, 클라우드 작업은 각각 사용량 계산 방식이 달라질 수 있다.

특히 플랜별 한도와 크레딧 정책은 바뀌기 쉬운 영역이므로 숫자를 외우기보다 공식 Pricing 페이지와 현재 계정의 사용량 화면을 확인하는 편이 안전하다.

실행 방식	공식 Pricing 문서 기준	관리 포인트
로컬 CLI / IDE 메시지	플랜별 5시간 단위 한도와 모델별 사용량 범위가 다르다	작은 반복은 작은 모델, 낮은 reasoning effort, 짧은 프롬프트로 처리한다
클라우드 태스크 / GitHub 코드 리뷰	공식 표 기준 GPT-5.3-Codex로 계산되는 항목이 따로 있다	로컬 모델 선택과 같은 방식으로 직접 바꿀 수 있다고 가정하지 않는다
API 키 사용	CLI, SDK, IDE 확장은 가능하지만 GitHub 코드 리뷰나 Slack 같은 클라우드 기능은 제공되지 않으며 API 토큰 요금이 적용된다	CI 자동화는 API key 비용과 로그 보관 정책을 따로 본다
Fast mode	지원 모델에서 더 높은 크레딧 비율을 쓴다	속도 병목이 확인된 작업에만 제한적으로 켠다

공식 Pricing 문서가 제시하는 절약 기준도 실용적이다.

프롬프트 크기를 줄이고, AGENTS.md를 작게 유지하고, 필요 없는 MCP 서버를 끄고, 반복 작업에는 더 작은 모델을 쓰면 한도를 더 오래 쓸 수 있다. 그래서 초심자에게 가장 좋은 기본 습관은 "강한 모델을 계속 켜두기"가 아니라, 작업 난이도에 맞춰 모델·reasoning effort·Fast mode·MCP 수를 함께 줄이는 것이다.

5. 정리: 4개 개념이 어떻게 연결되는가

지금까지 살펴본 4가지 개념은 따로 노는 기능이 아니다. Codex에게 일을 맡길 때 역할을 나눠 갖는 장치들이다. 공식 Customization 문서는 이 관계를 명확하게 설명한다.

모델(Models)
  └─ 작업 특성에 따라 선택 → 생각의 깊이와 속도 결정

프롬프트(Prompting)
  └─ 모델에 전달하는 지시 → 결과 품질을 크게 좌우

메모리(Memories) + AGENTS.md
  └─ 매번 프롬프트에 쓰지 않아도 Codex가 참고하는 배경 정보
     - AGENTS.md: 팀 규칙, 버전 관리, 공유
     - 메모리: 개인 작업 패턴, 이전 대화에서 배운 내용

샌드박스(Sandboxing)
  └─ 모델이 실제로 실행할 수 있는 범위를 제한
     → 반복 확인은 줄이고, 위험한 실행은 막음

예를 들어 gpt-5.5를 기본으로 쓰고, AGENTS.md에 린트·테스트 규칙을 박아두고, workspace-write로 실행한다. 그러면 매번 프롬프트에 "PR 전에 린트 돌려라"를 다시 쓸 필요가 없다. 메모리가 팀 코딩 습관을 기억해두면 다음번 프롬프트도 짧아진다.

4개가 제대로 맞으면 Codex에게 같은 말을 반복할 일이 줄어든다.

실제로는 아래처럼 연결해서 생각하면 된다.

상황	프롬프트	메모리/AGENTS.md	샌드박스/모델
낯선 저장소 분석	구조 요약, 위험 파일, 수정 전 확인 요청	팀 규칙은 아직 신뢰하지 말고 먼저 읽기	`read-only` + 강한 모델
작은 버그 수정	재현 단계, 수정 금지 범위, 테스트 명령	AGENTS.md의 테스트 규칙을 따르게 함	`workspace-write` + `on-request`
큰 리팩토링	먼저 계획 요청, 단계별 체크포인트, 회귀 테스트	반복 규칙은 AGENTS.md에, 임시 제약은 프롬프트에 둠	강한 모델 + 높은 reasoning effort

결국 좋은 프롬프트는 예쁜 문장이 아니라 작업 주문서다. 무엇을 고칠지, 어떤 규칙을 기억할지, 어떤 파일까지 건드려도 되는지, 어떤 모델로 처리할지를 함께 정해야 Codex가 덜 헤맨다.

6. Part 3 예고

다음 편은 Skills, MCP, Subagents다. Skills는 자주 쓰는 절차를 묶어두는 것이고, MCP는 Codex가 외부 도구로 나가는 통로다. Subagents는 큰 일을 역할별로 쪼개 돌리는 방식이다. 이 글이 "Codex에게 어떤 규칙을 줄 것인가"였다면, 다음 편은 "Codex가 어떤 도구를 쓸 수 있는가"에 가깝다.

OpenAI Codex 개발자 시리즈

Part 1: CLI 빠른 시작 Part 2: 핵심 개념 4가지 (현재 글) Part 3: Subagents · Workflows (예정) Part 4: AGENTS.md · Rules (예정) Part 5: MCP · Plugins · Skills (예정) Part 6: 자동화 (예정) Part 7: 마이그레이션 (예정) Part 8: 병행 사용 패턴 (예정)

자주 묻는 질문

Codex에서 좋은 프롬프트는 무엇이 다른가?

좋은 프롬프트는 목표, 맥락, 제약, 완료 기준을 함께 준다. 이렇게 쓰면 Codex가 추측으로 범위를 넓히기보다 검증 가능한 작업 단위로 움직이기 쉽다.

Memories와 AGENTS.md는 같은 기능인가?

역할이 다르다. Memories는 개인 작업 패턴이나 이전 대화에서 배운 내용을 돕고, AGENTS.md는 저장소 안에서 팀 규칙과 작업 기준을 공유하는 지침 파일에 가깝다.

앞선 글에서 다룬 샌드박스를 왜 다시 다루는가?

앞선 글은 처음에 어떤 안전 설정으로 시작할지를 다뤘고, 이 글은 이번 작업을 Codex에게 어디까지 맡겨도 되는지 판단하는 법을 다룬다. 샌드박스는 외울 옵션 목록이 아니라, Codex가 읽기만 할지, 프로젝트 안에서 수정까지 할지, 더 넓은 권한이 필요한지를 정하는 안전 울타리다.

프롬프트, AGENTS.md, 메모리에는 각각 무엇을 넣어야 하나?

이번 작업에만 적용되는 조건은 프롬프트에 둔다. 팀이 반복해서 지켜야 하는 빌드, 테스트, 리뷰 규칙은 AGENTS.md에 둔다. 개인 작업 습관이나 이전 대화에서 배운 패턴은 메모리가 보조하도록 두는 편이 좋다.

처음에는 어떤 샌드박스와 승인 정책이 무난한가?

일반적인 로컬 개발 작업은 workspace-write와 on-request 조합이 무난하다. 낯선 저장소를 읽기만 할 때는 read-only로 시작하고, danger-full-access는 격리된 환경에서 정말 필요한 경우에만 쓴다.

모델은 항상 가장 강한 것을 고르면 되는가?

그렇지 않다. 큰 리팩토링, 복잡한 원인 분석, 넓은 코드 이해에는 강한 모델과 높은 reasoning effort가 유리하지만, 작은 반복 수정이나 단순 정리에는 더 가벼운 모델이 비용과 속도 면에서 낫다.

참고 자료

작성일: 2026년 5월

분석 대상: OpenAI Codex CLI (2026년 5월 공식 문서 기준)

이 글은 2026년 5월 기준으로 작성되었다. 이후 변경될 수 있다.

Codex CLI 입문(1) : OpenAI Codex CLI 빠른 시작 - codex 설치, 인증 하기

갓대희 — Thu, 7 May 2026 01:34:01 +0900

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

Codex에 대해 처음 글을 작성한 지 꽤 오래되었다.

요즘 Claude Code 요금 부담 때문에 Codex를 다시 살펴보는 분들이 많아진 것 같다. 그래서 이번에는 기초부터 다시 정리해보려 한다. 이 글에서는 Codex CLI, 즉 터미널에서 쓰는 Codex를 중심으로 설치, 로그인, 첫 명령 실행, 안전하게 쓰는 기본 습관까지 실제로 따라 할 수 있는 순서로 다룬다.

먼저 용어부터 가볍게 잡고 가자.
CLI는 마우스로 누르는 앱이 아니라 터미널에 명령어를 입력해서 쓰는 도구를 말한다.
터미널은 macOS의 Terminal, Windows의 PowerShell처럼 글자로 명령을 실행하는 창이다.
저장소(repo)는 프로젝트 코드가 들어 있는 폴더라고 이해하면 된다.

OpenAI Codex 개발자 시리즈

Part 1: CLI 빠른 시작 (현재 글) Part 2: 핵심 개념 4가지 Part 3: Subagents · Workflows Part 4: AGENTS.md · Rules Part 5: MCP · Plugins · Skills (예정) Part 6: 자동화 Part 7: 마이그레이션 Part 8: 슬래시 명령어 정리(예정)

1. 설치하기

Codex CLI는 OpenAI의 로컬 터미널용 코딩 에이전트다. 공식 GitHub 저장소를 보면 Rust 중심으로 구현된 오픈소스 프로젝트라는 점도 확인할 수 있다. Rust는 빠르고 안정적인 프로그램을 만들 때 자주 쓰는 프로그래밍 언어이고, 오픈소스는 소스 코드가 공개되어 누구나 확인할 수 있다는 뜻이다.

macOS, Windows(PowerShell 또는 WSL2), Linux를 모두 지원한다. Windows에서는 PowerShell에서 네이티브로 실행할 수 있고, Linux 환경이 필요하면 WSL2를 사용할 수 있다. 설치 방법은 크게 세 가지다.

1.1 npm으로 설치

처음 시도하기 좋은 방법이다. Node.js가 설치되어 있다면 바로 사용할 수 있다.

npm은 Node.js 패키지를 설치하는 도구라서, 자바스크립트 개발을 해본 분들에게는 익숙할 것이다.

npm install -g @openai/codex

패키지명은 @openai/codex다. 처음이라면 위 명령어를 그대로 복사해 실행하면 된다. 나중에 최신 버전으로 업데이트할 때는 다음 명령어를 쓴다.

npm install -g @openai/codex@latest

1.2 Homebrew로 설치 (macOS)

macOS를 사용한다면 Homebrew로도 설치할 수 있다.

Homebrew는 맥에서 개발 도구를 설치할 때 많이 쓰는 패키지 관리자다.

다만 2026년 5월 기준으로 공식 문서와 GitHub README의 명령어 표기가 다르다.

# GitHub README(https://github.com/openai/codex) 기준
brew install --cask codex

# 공식 quickstart(developers.openai.com/codex/quickstart) 기준
brew install codex

처음 설치할 때는 공식 quickstart의 brew install codex를 먼저 기준으로 삼고, 환경에 따라 동작하지 않으면 GitHub README에 적힌 --cask 방식을 확인하는 식으로 접근하는 편이 안전하다. 이 부분은 문서 간 표기가 엇갈리므로, 설치 직전 최신 문서를 다시 확인한다.

1.3 바이너리 직접 다운로드

npm이나 Homebrew를 사용하기 어려운 환경이라면, GitHub Releases에서 플랫폼별 바이너리를 직접 내려받을 수 있다.

바이너리는 설치 파일이나 실행 파일에 가까운 형태라고 보면 된다.

macOS(Apple Silicon/x86_64), Linux(x86_64/arm64) 옵션이 제공된다.

1.4 터미널이 부담스럽다면 IDE 확장으로 시작

이 글은 CLI 기준으로 설명하지만, Codex를 꼭 터미널에서만 써야 하는 것은 아니다. OpenAI의 Codex 업그레이드 발표와 공식 IDE 확장 문서에 따르면 Codex는 에디터 안에서도 사용할 수 있다.

공식 문서 기준으로 VS Code, VS Code Insiders, Cursor, Windsurf 같은 VS Code 계열 에디터와 JetBrains IDE 통합을 지원한다. 설치 후에는 에디터 사이드바에서 Codex를 열고, ChatGPT 계정 또는 API 키로 로그인해 사용할 수 있다.

Codex는 에디터에서 열어둔 파일, 선택한 코드, 현재 작업 중인 맥락을 참고할 수 있다. 그래서 터미널에서 파일 경로를 길게 적는 대신, 에디터에서 문제 구간을 선택한 뒤 "이 부분 왜 실패하는지 봐줘"처럼 짧게 요청해도 시작하기 쉽다.

ex) Cursor에 설치해 보도록 하자. Cursor 클릭시 빈 브라우저 새창이 열리면서 다음과 같이 컨펌 창이 열린다. Cursor 열기 클릭.

- 바로 Install을 클릭하여 설치해보자.

- 좌상한(다른 위치에 있을수 있는데 꽃 보양의 이모티콘을 찾아보자) 패널을 클릭해보면 Codex Extension이 설치 되어있는것을 볼 수 있다. 클릭해 보자.

- CODEX 플러그인이 활성화 되는데, Next 를 눌르며 읽어보자.

- Try GPT-5.5 now 를 클릭하면 이제 CODEX 플러그인도 사용할 준비가 되었다.

(Codex app 다운로드를 유도하는데 App은 별도의 글에서 다룬다. > Codex Mac App 가이드: 설치부터 권한, MCP, 자동화까지 )

입문자라면 IDE 확장도 좋은 시작점이다.
터미널 명령어가 아직 낯설다면 플러그인처럼 에디터 안에서 Codex를 먼저 써보는 편이 부담이 적다. 로컬 변경사항을 에디터 안에서 미리 보고, Codex가 제안한 코드도 바로 확인할 수 있기 때문이다.

DE 확장에서 클라우드 작업을 새로 만들고, 진행 중인 작업을 추적하고, 완료된 작업을 검토할 수 있다고 설명한다. 쉽게 말해 간단한 수정은 에디터 안에서 바로 처리하고, 오래 걸리는 작업은 클라우드에 맡긴 뒤 결과를 다시 에디터에서 이어볼 수 있다는 뜻이다.
다만 CI/CD(자동 빌드·테스트·배포), 자동화, 원격 서버 작업까지 다루려면 CLI 흐름도 알아두는 편이 좋다.
그래서 이 글에서는 CLI를 중심으로 설명하고, 에디터 중심 개발자는 IDE 확장을 함께 쓰는 방식을 추천한다.

2. 인증하기

설치가 끝나면 터미널에 codex를 입력해 실행한다. 첫 실행 시 ChatGPT 계정 또는 OpenAI API 키로 인증할 수 있다.

여기서 인증이라는 것은 "이 사용자가 Codex를 사용할 권한이 있는지 확인하는 과정"이다.

두 방식은 단순한 로그인 화면 차이가 아니다. 접근 권한, 요금 체계, 사용할 수 있는 기능, 적용되는 데이터 처리 정책이 조금씩 다르다.

2.1 ChatGPT 계정으로 로그인

ChatGPT 계정 로그인: ChatGPT 계정의 Codex 사용량과 권한을 사용하는 방식이다.
2026년 5월 기준 Codex pricing 문서는 ChatGPT Free, Go, Plus, Pro, Business, Edu, Enterprise 플랜에 Codex가 포함된다고 설명한다.
다만 플랜별 사용량, 모델, 클라우드 기능 지원 범위는 다르다.

터미널에서 codex라고 입력해보자.

예를 들어 내 환경에서는 로그인 방식을 선택하는 화면이 나왔다. 나는 ChatGPT Pro 플랜을 사용 중이라 ChatGPT 계정 로그인을 선택했다.

브라우저가 열리면 사용 중인 ChatGPT 계정으로 인증을 완료한다.

인증이 끝난 뒤 터미널로 돌아와 Enter 키를 누르면 Codex를 사용할 준비가 된다.

2.2 OpenAI API 키로 로그인

API 키 인증: 공식 인증 문서에 따르면 OpenAI Platform 계정을 통해 표준 API 요금으로 청구된다.
API 키는 프로그램이 OpenAI Platform API에 접근할 때 쓰는 비밀번호 같은 값이다.
CI/CD처럼 사람이 직접 누르지 않고 자동으로 빌드·테스트·배포하는 흐름에 어울린다.

printenv OPENAI_API_KEY | codex login --with-api-key

API 키 인증을 사용할 때 한 가지 주의할 점이 있다.

ChatGPT 계정 대신 API 키를 쓰면 클라우드 쪽에서 이어지는 일부 기능을 사용할 수 없을 수 있다고 설명한다.

가격 문서도 API 키 방식은 CLI, SDK, IDE 확장에는 쓸 수 있지만 GitHub 코드 리뷰나 Slack 같은 클라우드 기반 기능은 제공되지 않는다고 설명한다. 개인 개발 작업이라면 ChatGPT 계정 로그인이, 자동화 스크립트나 CI/CD 파이프라인이라면 API 키가 적합하다.

2.3 인증 방식 선택 가이드

상황	권장 방식
개인 개발, 대화형 작업	ChatGPT 계정 로그인
CI/CD(자동 빌드·테스트·배포), 자동화 스크립트	API 키 인증
조직 워크스페이스 권한과 데이터 보관 정책을 맞춰야 할 때	ChatGPT 계정 (조직 설정 적용 범위 확인 필요)
브라우저를 열 수 없는 서버/원격 환경	`codex login --device-auth`

한 줄로 정리하면 이렇다. 직접 개발하면서 대화하듯 쓸 거라면 ChatGPT 계정이 편하고, 자동화 작업에 붙일 거라면 API 키가 더 자연스럽다.

보안 주의: 공식 인증 문서에 따르면 자격증명 저장 위치는 file(CODEX_HOME/auth.json, 기본값은 보통 ~/.codex/auth.json), keyring(macOS 키체인이나 Windows 자격 증명 관리자 같은 OS 보안 저장소), auto 중 config.toml에서 선택할 수 있다. file 방식을 쓰면 이 인증 파일을 비밀번호처럼 다뤄야 한다. Git에 커밋하거나 티켓/채팅에 붙여 넣으면 안 된다.

2.4 로그인 상태 확인과 로그아웃

입문 단계에서 의외로 자주 막히는 부분이 "내가 지금 어떤 방식으로 로그인되어 있는지"다.

codex login status

예를 들면 다음처럼 확인할 수 있다.

계정을 바꾸거나 API 키 인증을 지우고 싶다면 다음 명령어를 사용한다.

codex logout

회사 네트워크처럼 사내 인증서나 TLS 프록시를 쓰는 환경에서는 로그인 과정에서 인증서 문제가 날 수 있다.

이 경우 공식 인증 문서는 CODEX_CA_CERTIFICATE 환경 변수로 사내 루트 CA 번들을 지정하는 방법도 안내한다. 일반 개인 개발자는 보통 신경 쓰지 않아도 되지만, 회사 장비에서 로그인 실패가 반복된다면 확인할 만하다.

3. 처음 실행해보기

인증까지 마쳤다면 프로젝트 디렉토리, 즉 내가 작업하려는 코드 폴더로 이동한 뒤 codex를 실행한다. 터미널 UI가 열리면 평소 말하듯 작업을 입력하면 된다.

예시 1: 프로젝트 분석

Tell me about this project

가장 처음 해볼 만한 명령이다. Codex가 현재 폴더의 코드를 읽고 프로젝트 구조를 설명해준다. 여기서 모듈은 기능별로 나뉜 코드 묶음, 의존성은 이 프로젝트가 가져다 쓰는 외부 라이브러리라고 생각하면 된다.

한국어로는 "해당 프로젝트에 대해 간단히 요약해줘"처럼 입력해도 된다.

예시 2: 기능 구현

Build a classic Snake game in this repo

새 파일을 만들고 기존 파일을 수정하는 작업도 수행한다.

다만 승인 모드 설정에 따라 각 변경 전에 확인을 요청할 수도 있고, 자동으로 진행할 수도 있다.

예시 3: 버그 수정

Find and fix bugs in my codebase with minimal, high-confidence changes

여기서 "minimal, high-confidence changes"는 "작고 확실한 수정만 해달라"는 뜻이다. 이런 제약 조건을 같이 적어두면 좋다. 범위를 지정하지 않으면 Codex가 내가 생각한 것보다 넓게 파일을 바꿀 수 있다.

예시 4: 기능 추가

Add a new command-line option --json that outputs JSON.

이 예시는 원하는 사용 방법을 꽤 구체적으로 적은 명령이다. 여기서 인터페이스 명세는 "사용자가 어떤 옵션을 입력하면 프로그램이 어떻게 동작해야 하는지"를 뜻한다. 이렇게 적으면 Codex가 바꿔야 할 파일, 추가할 로직, 필요한 테스트를 더 잘 좁힐 수 있다.

좋은 첫 프롬프트의 4요소

공식 best practices(모범 사례)는 프롬프트에 목표, 맥락, 제약, 완료 기준을 넣으라고 권장한다. 처음부터 길게 쓸 필요는 없지만, 이 네 가지를 넣으면 Codex가 덜 추측하고 더 좁은 범위에서 작업한다.

요소	초심자식 표현
Goal	무엇을 만들거나 고치고 싶은가
Context	관련 파일, 오류 메시지, 참고 문서가 무엇인가
Constraints	건드리면 안 되는 범위나 지켜야 할 규칙은 무엇인가
Done when	어떤 테스트나 확인이 끝나야 완료로 볼 것인가

Goal: 로그인 오류를 고쳐줘.
Context: 에러 메시지는 "Invalid token"이고, 관련 파일은 src/auth.ts야.
Constraints: API 응답 형식은 바꾸지 말아줘.
Done when: 기존 테스트를 통과하고, 로그인 실패 케이스 테스트를 하나 추가해줘.

4. 샌드박스와 승인 정책 이해하기

Codex CLI를 처음 사용할 때 꼭 이해해야 할 개념이 권한과 승인 설정이다. Codex는 코드를 읽는 것뿐 아니라 파일을 편집하고 셸 명령도 실행할 수 있다. 그래서 "어디까지 자동으로 맡길 것인가"를 정해야 한다.

Codex의 안전 장치는 샌드박스(격리)와 승인 정책 두 축으로 구성된다. 공식 best practices(모범 사례) 문서도 이 둘을 Codex 권한을 조절하는 핵심 손잡이로 설명한다.

두 축을 분리해서 이해하자.
sandbox_mode는 Codex가 어디까지 접근할 수 있는지를 정한다. 파일 수정 범위, 네트워크 접근, 셸 명령 실행 범위가 여기에 걸린다.
approval_policy는 Codex가 작업하다가 언제 사용자에게 물어볼지를 정한다.
--yolo는 이 두 안전장치를 함께 우회하는 별도 고위험 옵션이다.

중요한 점은 샌드박스가 Codex 내부 파일 편집뿐 아니라 Codex가 실행하는 git, 패키지 매니저, 테스트 명령에도 적용된다는 것이다. 예를 들어 npm install은 단순한 설치 명령처럼 보여도 네트워크 요청과 설치 스크립트 실행을 동반할 수 있다.

아래 세 가지는 --sandbox에 넣는 샌드박스 모드이고, 승인 정책은 뒤에서 --ask-for-approval 또는 approval_policy로 따로 지정한다.

4.1 샌드박스 3단계

공식 sandboxing(격리) 문서와 CLI reference(옵션 목록)에 따르면 샌드박스 모드는 다음 세 가지다.

모드	CLI 플래그 값	언제 쓰나
read-only	`--sandbox read-only`	낯선 저장소를 처음 분석할 때. 파일을 읽는 데 집중하고, 수정이나 명령 실행은 막아두고 싶을 때
workspace-write	`--sandbox workspace-write`	일반적인 로컬 개발 기본값. 현재 작업 폴더 안의 파일 읽기/수정은 허용하고, 바깥 폴더 수정이나 네트워크 접근은 기본적으로 제한
danger-full-access	`--sandbox danger-full-access`	샌드박스 경계를 제거해야 하는 특수 상황. 로컬 입문자에게는 비권장. 승인 정책까지 자동으로 꺼지는 것은 아니지만, `never`와 결합하면 사실상 전체 권한 실행에 가까워짐

처음에는 workspace-write로 시작하는 편이 낫다. 어느 파일을 바꾸는지 감이 잡히고, 저장소를 충분히 신뢰할 수 있을 때만 권한을 넓힌다.

네트워크 접근은 별도 문제다.
공식 설정 reference(설정 목록) 기준으로 workspace-write에서도 네트워크 접근은 별도 설정(sandbox_workspace_write.network_access)으로 다룬다.
패키지 설치, 외부 API 호출, 웹 요청이 필요하면 승인 요청이 뜨거나 설정을 바꿔야 할 수 있다.
초심자라면 네트워크가 필요한 작업인지 먼저 확인하고, 왜 필요한지 Codex에게 설명하게 하는 습관이 좋다.

4.2 승인 정책 3단계

--ask-for-approval은 사용자 확인을 언제 받을지 정하는 옵션이다. 2026년 5월 기준 공식 CLI reference(옵션 목록)와 로컬 codex-cli 0.128.0 도움말에서 확인되는 주요 값은 다음과 같다.

값	의미	주의점
untrusted	신뢰된 명령 목록에 없는 명령을 실행하기 전에 사용자 승인을 요청	보수적으로 시작하고 싶을 때 유용
on-request	샌드박스 안에서 가능한 작업은 진행하고, 경계를 넘을 필요가 있을 때 승인 요청	일반적인 대화형 로컬 개발에 가장 무난
never	사용자 승인을 요청하지 않음. 실패는 곧바로 모델에게 돌아감	승인만 끄는 것이지 샌드박스를 자동으로 끄는 것은 아님. `never`와 `--yolo`는 다름

예전 문서나 글에서 보이는 on-failure는 현재 도움말에서 더 이상 권장하지 않는 값(deprecated)으로 표시된다. 새로 설정한다면 대화형 작업은 on-request, 비대화형 작업은 상황에 따라 never를 검토하는 편이 낫다.

4.3 처음 고를 조합

처음에는 옵션 이름을 외우는 것보다 상황별 조합을 기억하는 편이 쉽다.

상황	권장 조합	이유
처음 보는 저장소를 읽기만 할 때	`read-only + on-request`	수정 없이 구조 파악부터 할 수 있음
일반적인 로컬 개발	`workspace-write + on-request`	작업 폴더 안에서는 진행하고, 범위를 넘을 때 멈춰 물어봄
CI나 자동화 스크립트	`workspace-write` 기반으로 별도 검토	깨끗한 Git 상태, 임시 실행 환경(CI runner), 필요한 네트워크 권한을 함께 설계해야 함
전체 파일/네트워크 권한이 필요한 특수 작업	입문 단계 비권장	먼저 `--add-dir`나 쓰기 허용 폴더(writable roots)로 필요한 폴더만 추가하는 편이 안전

CLI 플래그로 실행할 때마다 지정할 수도 있다. 플래그는 명령어 뒤에 붙여서 동작 방식을 바꾸는 옵션이다.

# 기본 권장 조합 (로컬 작업)
codex --sandbox workspace-write --ask-for-approval on-request

# 읽기 전용으로 탐색만 할 때
codex --sandbox read-only

# 스크립트나 CI처럼 비대화형 실행이 필요할 때
codex exec "run the tests and summarize failures"

여기서 주의할 점이 있다. codex exec는 비대화형으로 실행하는 방식이지, 그 자체가 안전 모드는 아니다.

자동화가 필요하면 제한된 샌드박스, 깨끗한 Git 상태, 임시 실행 환경, 필요한 네트워크 권한을 함께 설계해야 한다.

자주 쓰는 조합은 별칭(alias)으로 줄여도 된다.
옵션이 길어서 매번 입력하기 번거롭다면 본인이 기억하기 쉬운 짧은 명령어를 만들어둘 수 있다. 예를 들어 나는 Codex를 자주 쓰는 기본 조합으로 실행하기 위해 cdd 같은 별칭을 만들어 사용한다.
macOS나 Linux의 zsh/bash라면 ~/.zshrc 또는 ~/.bashrc에 아래처럼 적어둘 수 있다.

alias cdd='codex --sandbox workspace-write --ask-for-approval on-request'

다만 별칭은 편의 기능일 뿐이다. 별칭 이름만 보고 어떤 권한으로 실행되는지 잊어버리면 오히려 위험해질 수 있다. 처음 만들 때는 alias cdd로 실제 실행 명령을 확인하고, 권한을 넓힌 별칭에는 더 노골적인 이름을 붙이는 편이 안전하다.

ex) cdd

4.4 yolo는 빠른 모드가 아니라 우회 모드다

위험 옵션은 의미를 알고 써야 한다. 공식 CLI reference(옵션 목록)는 --dangerously-bypass-approvals-and-sandbox와 별칭 --yolo를 승인 프롬프트와 샌드박스를 모두 건너뛰는 옵션으로 설명한다.
즉, 단순히 "빠르게 실행"하는 모드가 아니라 로컬 파일, 네트워크, 패키지 설치 스크립트, 환경변수나 토큰이 노출될 수 있는 경계까지 함께 넓히는 선택이다.
기술적으로는 사용자가 위험을 이해하고 감수한다면 쓸 수 있다. 다만 그 경우에도 평소 쓰는 로컬 프로젝트 폴더가 아니라 사용 후 버리는 가상 머신(disposable VM), 임시 컨테이너, 제한된 자동화 실행 환경(CI runner)처럼 외부에서 격리된 환경을 먼저 준비하는 편이 맞다. 입문 단계에서는 이름과 의미를 알아두되, 예제 명령어처럼 따라 치는 옵션으로 소개하지 않는다.

never와 yolo를 혼동하지 말자.
approval_policy = "never"는 승인 질문을 하지 않겠다는 뜻이다. 샌드박스 설정은 별도로 남아 있을 수 있다.
반면 --yolo는 승인과 샌드박스를 함께 우회한다. 이 차이를 모르면 "승인만 줄이려던 설정"이 "보호장치 전체 해제"로 바뀔 수 있다.

4.5 영구 설정

매번 플래그를 입력하기 번거롭다면 config.toml에 기본값을 설정한다. 이 파일은 Codex의 기본 동작을 적어두는 설정 파일이다.

sandbox_mode = "workspace-write"
approval_policy = "on-request"

공식 설정 문서 기준으로 개인 기본값은 ~/.codex/config.toml에 두고, 특정 프로젝트 전용 설정은 저장소 안의 .codex/config.toml에 둔다. 우선순위는 CLI 플래그와 --config, 프로필, 프로젝트 설정, 사용자 설정, Unix의 시스템 설정(/etc/codex/config.toml), 내장 기본값 순서다. 프로젝트 설정은 신뢰한 프로젝트에서만 적용된다.

처음에는 sandbox_mode = "workspace-write"와 approval_policy = "on-request" 조합을 기본값으로 두는 편이 안전하다. default_permissions는 샌드박스와 승인 정책 자체가 아니라, 재사용할 권한 프로필 이름을 고르는 설정으로 이해하면 된다. 신뢰하지 않는 프로젝트에서는 프로젝트 안의 .codex/config.toml을 무조건 믿지 말고 먼저 내용을 확인한다.

공식 문서에 따르면 sandbox_workspace_write.writable_roots로 쓰기를 허용할 폴더 범위도 지정할 수 있다. 쉽게 말해 "Codex가 이 폴더 안에서는 파일을 수정해도 된다"라고 선을 그어두는 설정이다. 실행할 때만 임시로 추가 폴더를 허용하고 싶다면 CLI reference의 --add-dir 플래그를 사용할 수 있다.

4.6 플랫폼별 샌드박스 구현

macOS는 내장 Seatbelt 프레임워크를 사용한다. Seatbelt는 앱의 접근 범위를 제한하는 macOS의 보안 장치다.

Linux나 WSL2에서는 bubblewrap(bwrap) 기반 격리를 사용한다. 환경에 따라 설치 상태나 보안 설정이 달라질 수 있으므로, 샌드박스 오류가 나면 공식 sandboxing 문서의 Linux/WSL2 안내를 함께 확인한다.

입문자를 위한 권장 접근법: 공식 best practices(모범 사례)는 처음엔 기본 설정(workspace-write + on-request)으로 시작하고, 특정 저장소에서의 필요가 분명해진 뒤에만 권한을 넓히도록 권장한다. 나도 이 방식이 가장 무난하다고 본다. 처음부터 --yolo로 시작하면 의도치 않은 파일 삭제나 네트워크 요청이 발생할 수 있다.

Codex 공식 UseCase 번역글도 참고

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

5. 안전하게 쓰기 — Git checkpoint 패턴

Codex CLI는 코드베이스, 즉 프로젝트 전체 코드를 실제로 수정한다. 그래서 강력하지만 동시에 조심해야 한다. 공식 문서도 이 점을 명확히 언급한다.

"Codex can modify your codebase, so consider creating Git checkpoints before and after each task so you can easily revert changes if needed."
— 공식 quickstart

번역: Codex는 내 코드베이스를 수정할 수 있으므로, 필요할 때 쉽게 되돌릴 수 있도록 각 작업 전후에 Git 체크포인트를 만들어 두는 것이 좋다는 뜻이다.

뜻은 간단하다. Codex에게 작업을 맡기기 전에 현재 상태를 Git에 저장해두면, 결과가 마음에 들지 않을 때 되돌릴 수 있다. Git은 코드 변경 이력을 저장하는 도구이고, checkpoint는 "지금 상태를 저장해두는 지점"이라고 보면 된다.

실전 Git checkpoint 패턴

# 작업 시작 전 checkpoint 생성
git status
git add -A && git commit -m "checkpoint: before codex task - [작업 내용 간략 설명]"

# Codex 작업 실행
codex

# 작업 결과 확인 후, 만족스러우면 다시 커밋
git diff
git add -A && git commit -m "feat: [작업 완료 내용]"

# 이미 커밋한 Codex 결과를 취소하고 싶을 때
git log --oneline -5
git revert <codex_result_commit_sha>

주의: 공식 문서는 checkpoint를 만들라고 권장하지만, 어떤 Git 명령으로 되돌릴지는 상황에 따라 다르다. 초심자에게는 보통 git revert가 더 안전하다. 이전 이력을 지우지 않고 "되돌리는 새 커밋"을 만들기 때문이다. 작업 이력을 지우는 reset 계열 명령은 저장하지 않은 변경을 즉시 삭제할 수 있으므로, Git에 익숙하지 않다면 이 글의 예제로 따라 하지 않는다.

이건 단순히 "커밋을 자주 하라"는 말이 아니다.

AI 에이전트가 여러 파일을 한 번에 수정하면, 나중에 어느 변경이 문제였는지 찾기 어려워진다.

작업 단위로 checkpoint를 남겨두면 디버깅도 쉽고, 결과가 별로일 때 되돌리기도 훨씬 편하다.

6. 정리 + Part 2 예고

이 편에서 다룬 내용을 정리하면:

설치: npm install -g @openai/codex (npm) 또는 Homebrew로 시작. Homebrew 명령은 공식 quickstart와 GitHub README 표기가 다를 수 있으니 설치 직전 최신 문서를 확인
인증: 직접 개발할 때는 ChatGPT 계정이 편하고, 자동 실행에는 API 키가 어울림. 단, 플랜별 사용량과 클라우드 기능 지원 범위는 다름
시작: 목표, 맥락, 제약, 완료 기준을 넣고 프로젝트 설명 요청 → 작은 기능 구현 → 버그 수정 순으로 난이도를 높임
권한과 승인 모드: 처음에는 workspace-write + on-request로 시작하고, yolo는 위험을 이해하고 감수할 때 격리 환경에서만 검토
Git checkpoint: 작업 전후 커밋으로 되돌릴 수 있는 안전망을 만들어 둠
계정 관리: codex login status와 codex logout으로 현재 인증 상태를 확인하고 정리

주요 CLI 플래그 빠른 참조

터미널에서 codex --help를 실행하면 전체 옵션 목록을 확인할 수 있다. 옵션이 너무 많아 보일 수 있지만, 처음에는 아래 주요 항목만 알아도 충분하다.

플래그	축약	역할
`--sandbox`	`-s`	Codex가 접근할 수 있는 파일 범위 선택 (`read-only` / `workspace-write` / `danger-full-access`)
`--ask-for-approval`	`-a`	사용자 확인을 언제 받을지 선택 (`untrusted` / `on-request` / `never`)
`--dangerously-bypass-approvals-and-sandbox`	`--yolo`	격리와 승인 절차를 모두 끄는 고위험 옵션. 외부에서 충분히 격리된 실행 환경 전용
`--add-dir`	-	현재 작업 폴더 외에 추가로 쓰기 허용할 폴더 지정

전체 옵션은 codex --help 또는 공식 CLI reference(옵션 목록)에서 확인한다.

처음 실행 시 자주 겪는 문제

Codex CLI를 처음 설치하고 실행할 때 자주 마주칠 수 있는 상황과 대응법이다.

인증 토큰 만료: codex를 실행했을 때 인증 오류가 발생하면 codex login을 다시 실행해 재인증한다.
어떤 계정으로 로그인했는지 헷갈림: codex login status로 확인하고, 계정을 바꾸려면 codex logout 후 다시 로그인한다.
Linux/WSL2에서 샌드박스 오류: bubblewrap(bwrap)이 설치되지 않은 경우 발생할 수 있다. 패키지 매니저로 bubblewrap을 먼저 설치한다.
패키지 설치나 외부 요청이 막힘: 기본적으로 네트워크 접근이 꺼져 있을 수 있다. Codex가 왜 네트워크가 필요한지 설명하게 한 뒤, 필요한 경우에만 승인하거나 설정을 바꾼다.
그 외 오류: 먼저 공식 인증 문서의 로그인 진단 안내와 공식 troubleshooting(문제 해결) 문서를 확인한다. 같은 증상이 없으면 GitHub Issues(openai/codex)에서 오류 메시지를 그대로 검색한다.

Codex CLI를 지금 당장 써볼 상황 vs 잠시 미룰 상황

지금 쓸 때	잠시 미룰 때
혼자 개발하는 사이드 프로젝트	프로덕션 배포 직전 작업
리팩토링이나 테스트 보강	보안 민감 코드 직접 수정
버그 재현/분석 탐색	팀 규칙 정의가 아직 없는 경우

다음 편(Part 2)에서는 Codex를 제대로 쓰기 위해 알아야 할 Prompting, Memories, Sandboxing, Models를 정리한다.

핵심은 단순하다. 어떻게 지시할지, Codex가 무엇을 기억하게 할지, 어디까지 실행하게 할지, 어떤 모델을 고를지에 대해서이다.

OpenAI Codex 개발자 시리즈

Part 1: CLI 빠른 시작 (현재 글) Part 2: 핵심 개념 4가지 (예정) Part 3: Subagents · Workflows (예정) Part 4: AGENTS.md · Rules (예정) Part 5: MCP · Plugins · Skills (예정) Part 6: 자동화 (예정) Part 7: 마이그레이션 (예정) Part 8: 병행 사용 패턴 (예정)

자주 묻는 질문

Codex CLI를 처음 설치할 때 어떤 방법이 가장 무난한가?

Node.js가 이미 있다면 npm 설치가 가장 단순하다. macOS 사용자는 Homebrew도 선택할 수 있고, 설치 직전 공식 quickstart와 GitHub README의 최신 표기를 함께 확인하는 편이 안전하다.

Codex CLI에서 sandbox와 approval은 무엇이 다른가?

sandbox는 Codex가 접근하거나 수정할 수 있는 파일과 네트워크 범위를 제한하는 울타리다. approval은 위험한 명령이나 제한 밖 작업을 실행하기 전에 사용자 확인을 받을지 정하는 정책이다.

yolo 모드는 언제 써도 되는가?

위험을 정확히 이해하고, 버릴 수 있는 VM이나 임시 컨테이너처럼 격리된 환경을 준비한 경우에만 고려한다. 일반 프로젝트나 중요한 저장소에서는 기본 사용 모드로 두지 않는 편이 안전하다.

참고 자료

작성일: 2026년 5월 | 분석 대상 버전: Codex CLI (2026년 5월 기준)

이 글은 2026년 5월 기준으로 작성되었다. 이후 변경될 수 있다. 최신 정보는 공식 문서에서 확인한다.

OpenAI on AWS : AWS Bedrock으로 향한 GPT와 Codex 전략 - OpenAI가 Azure 독점을 벗어났다

갓대희 — Wed, 6 May 2026 01:58:49 +0900

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

OpenAI가 Microsoft의 품을 떠나 AWS에 올라탔다. 2026년 4월 28일, OpenAI는 GPT-5.5·Codex·Managed Agents를 Amazon Bedrock에 올리며 클라우드 AI 판도를 뒤흔들었다.

단순한 파트너십 확장이 아니다. Amazon은 OpenAI에 50억 달러를 투자하고, 기존 380억 달러 계약을 8년간 1,000억 달러 추가 확대했다. AWS는 OpenAI 엔터프라이즈 플랫폼의 독점 외부 클라우드 배포처가 됐다.

이번엔 세 가지 제품의 실체, 투자 구조, 개발자가 지금 당장 해야 할 것, 그리고 Azure와의 경쟁 구도 변화를 정리하려 한다.

배경 — Microsoft 독점 종료와 새 판세
AWS에서 쓸 수 있는 세 가지 새 제품
OpenAI Models on Bedrock — GPT-5.5의 AWS 상륙
Codex on AWS — 4백만 사용자의 코딩 에이전트
Bedrock Managed Agents — 프로덕션 에이전트 인프라
투자·딜 구조 — 50억 달러 투자와 1,000억 달러 확장
OpenAI Frontier — AWS 독점 엔터프라이즈 플랫폼
기술 통합 — IAM, PrivateLink, Trainium, AgentCore
개발자·기업에게 지금 당장 의미하는 것
경쟁 구도 변화 — Azure vs AWS vs Google
현황 및 주의사항
트러블슈팅 Q&A
결론 — 언제 쓰고, 언제 기다리는가

이 글의 핵심 요약

2026-04-28: OpenAI, GPT-5.5·Codex·Bedrock Managed Agents를 Amazon Bedrock에 Limited Preview 출시 (출처: OpenAI 공식 발표)
하루 전(04-27): Microsoft가 OpenAI 독점 라이선스를 비독점으로 전환, 법적 제약 해소 (출처: TechCrunch)
Amazon, OpenAI에 50억 달러 투자($15B 선행 + $35B 조건부) / AWS 클라우드 계약 380억 → +1,000억 달러(8년) 확장 (출처: GeekWire)
AWS = OpenAI Frontier 독점 외부 클라우드 배포처 — 엔터프라이즈 에이전트 플랫폼
세 제품 모두 Limited Preview. 가격 미공개, 몇 주 내 GA 예정 (출처: AWS What's New)

1. 배경 — Microsoft 독점 종료와 새 판세

2026년 4월 27일, Microsoft와 OpenAI는 파트너십 계약을 대대적으로 재편했다. 핵심은 하나다: Microsoft의 독점이 끝났다.

기존 계약에서 Microsoft는 OpenAI의 모든 제품과 지적재산에 독점 접근권을 가졌다. 재편 후 Microsoft는 2032년까지 비독점 라이선스를 유지하되, 더 이상 OpenAI가 다른 클라우드 업체와 협력하는 것을 막을 수 없다. (출처: Axios)

Microsoft-OpenAI 새 계약 핵심 변경 사항

Microsoft 독점 → 비독점 IP 라이선스 (2032년까지 유지)
Microsoft가 OpenAI에 지급하던 수익 배분 폐지 (출처: CNBC)
OpenAI는 Microsoft에 수익 배분 지속, 단 상한선 추가 (2030년까지)
OpenAI가 AWS·Google 등 어느 클라우드에서도 제품 판매 가능

재편 합의

발표 다음 날인 4월 28일, OpenAI는 즉시 AWS와의 확장 파트너십을 공식 발표했다. GeekWire가 "GPT-5.5가 Azure 독점을 멈춘 지 하루 만에 AWS에 상륙했다"고 표현한 것은 이 타이밍의 상징성을 잘 요약한다. (출처: GeekWire)

이 변화가 의미하는 바는 단순히 "AWS에서도 GPT를 쓸 수 있게 됐다"가 아니다. OpenAI의 모델·제품·플랫폼이 이제 멀티클라우드 전략의 중심축이 된다는 것이다. AWS 워크로드를 이미 운영 중인 수만 개 기업이 별도 OpenAI 계정이나 Azure 마이그레이션 없이 GPT-5.5를 호출할 수 있다.

2. AWS에서 쓸 수 있는 세 가지 새 제품

이번 발표는 세 개의 별도 제품으로 구성된다. 단순히 모델 API를 얹은 수준이 아니라, OpenAI의 프로덕션 제품 라인 전체가 AWS 생태계 안으로 들어왔다.

제품	핵심 기능	대상	상태
OpenAI Models on Bedrock	GPT-5.5, GPT-5.4 등 프론티어 모델 호출	AI 앱 개발자, 에이전틱 워크플로우 팀	Limited Preview
Codex on AWS	코딩 에이전트: 코드 작성·리팩터·테스트·설명	개발자 팀, DevOps	Limited Preview
Bedrock Managed Agents	멀티스텝 워크플로우, 툴 사용, 장기 작업 실행	엔터프라이즈, 비즈니스 자동화 팀	Limited Preview

(2026-04-28 기준, 출처: AWS What's New)

한 줄로 요약하면: 모델 API는 기초 인프라이고, Codex는 개발자용 에이전트, Managed Agents는 엔터프라이즈 자동화 레이어다. 세 제품이 함께 AWS 환경에서 OpenAI의 전체 스택을 완성한다.

3. OpenAI Models on Bedrock — GPT-5.5의 AWS 상륙

Amazon Bedrock에 올라온 OpenAI 모델 라인업의 핵심은 GPT-5.5다. OpenAI의 현재 최상위 프론티어 모델로, 이전까지는 Azure를 통해서만 기업 환경에서 접근할 수 있었다. GPT-5.4도 함께 제공된다.

AWS에서 OpenAI 모델 호출 시 달라지는 점

단일 벤더 관계: 별도 OpenAI 계정·청구 없이 AWS IAM 크레덴셜로 호출
컴플라이언스 통합: AWS의 기존 보안 제어, 암호화, 감사 로그(CloudTrail)를 그대로 적용
클라우드 약정 적용: OpenAI 모델 사용량을 AWS 클라우드 약정(EDP)에 포함 가능
Bedrock 에코시스템 연동: 기존 Bedrock 도구·파이프라인과 동일 방식으로 통합

이 통합이 해결하는 실질적인 문제는 벤더 분리(vendor fragmentation)다. 지금까지 AWS 메인 스택에 OpenAI 모델을 붙이려면 별도 API 키 관리, 별도 보안 검토, 별도 청구 프로세스가 필요했다. 특히 대기업 엔터프라이즈에서 이 프로세스는 몇 주에서 몇 달이 걸리는 승인 절차를 수반한다.

이제 IAM 정책 하나로 GPT-5.5를 기존 AWS 워크플로우에 붙일 수 있다. 금융·의료 등 규제 산업에서 이 차이는 단순한 편의가 아니라 도입 가능 여부 자체를 가른다.

import boto3

# AWS 크레덴셜로 OpenAI GPT-5.5 호출 (Bedrock 통해)
bedrock = boto3.client("bedrock-runtime", region_name="us-east-1")

response = bedrock.invoke_model(
    modelId="openai.gpt-5.5",   # Bedrock 모델 ID (Limited Preview 기준 예시)
    body={
        "messages": [{"role": "user", "content": "안녕하세요"}],
        "max_tokens": 1024
    }
)

위 코드의 modelId는 Limited Preview 단계의 예시 형식이다. 실제 GA 출시 시 모델 ID가 변경될 수 있다. 공식 Bedrock 콘솔에서 확인 후 사용한다.

4. Codex on AWS — 4백만 사용자의 코딩 에이전트

Codex는 OpenAI의 코딩 에이전트 제품이다. 이제 Amazon Bedrock을 통해 기업 환경에서도 접근할 수 있다.

Codex가 실제로 하는 것

OpenAI 공식 발표 기준 Codex의 주요 기능 전체 목록 (출처: OpenAI on AWS):

코드 작성: 요구사항을 받아 신규 코드 생성
시스템 설명: 기존 코드베이스의 구조와 로직을 자연어로 설명
리팩터링: 코드 품질 개선, 패턴 현대화
테스트 생성: 단위 테스트·통합 테스트 자동 작성
레거시 현대화: 오래된 코드베이스를 현재 기술 스택으로 마이그레이션
리서치 및 분석: 코드 외 문서 작업, 데이터 분석 지원

접근 방법 4가지

Codex on AWS는 다음 방식으로 접근할 수 있다 (출처: AWS What's New):

접근 방법	설명	대상
Bedrock API	프로그래매틱 호출, 기존 앱 통합	백엔드 개발자
Codex CLI	터미널에서 AWS 크레덴셜로 직접 사용	DevOps, 파워유저
데스크톱 앱	Codex 데스크톱 앱을 Bedrock 백엔드로 연결	개인 개발자
VS Code 확장	IDE 안에서 AWS 인증으로 Codex 사용	IDE 중심 개발자

(2026-04-28 기준)

기업 관점에서 Codex on AWS의 핵심 가치는 보안 검토 단순화다. 기존에는 개별 개발자가 Codex를 쓰려면 OpenAI 계정을 별도로 만들고, 보안팀의 외부 서비스 승인을 받아야 했다. Bedrock을 통하면 회사가 이미 승인한 AWS 인프라 안에서 동일한 기능을 쓴다.

5. Bedrock Managed Agents — 프로덕션 에이전트 인프라

Bedrock Managed Agents는 이번 발표에서 가장 새로운 제품이다. OpenAI 모델을 백엔드로 삼아 멀티스텝 워크플로우를 실행하는 에이전트 인프라로, 팀이 "에이전트를 유용하게 만드는 것"에만 집중하고 주변 인프라 조립은 플랫폼이 처리한다는 것이 핵심 가치 제안이다.

주요 기능

멀티스텝 워크플로우 실행: 컨텍스트를 유지하며 여러 단계의 작업 수행
툴 통합: 외부 API, 데이터베이스, AWS 서비스 호출 가능
장기 작업 처리: 빠른 실행, 정확한 추론, 장기 작업의 안정적 조향
개별 에이전트 ID: 각 에이전트가 고유 ID와 액션 로그를 보유
내장 거버넌스: IAM, 암호화, CloudTrail이 기본 포함
Amazon Bedrock AgentCore 연동: 기본 컴퓨팅 환경으로 AgentCore 사용

Managed Agents가 기존 접근과 다른 점

기존에 AI 에이전트를 프로덕션에 올리려면 오케스트레이션 레이어, 툴 호출 처리, 상태 관리, 모니터링, 보안 제어를 개발팀이 직접 조립해야 했다. Bedrock Managed Agents는 이 전체를 관리형 서비스로 제공한다. 프로토타입에서 프로덕션까지의 시간을 단축하는 것이 목표다.

AWS의 공식 표현은 "빠른 배포, 툴 사용, 오케스트레이션, 거버넌스를 처리한다"이다. (출처: OpenAI 공식 발표) 이 일련의 움직임이 보여주는 것은 OpenAI가 단순한 API 공급자를 넘어 엔터프라이즈 운영 플랫폼 레이어로 진입하려 한다는 것이다.

6. 투자·딜 구조 — 50억 달러 투자와 1,000억 달러 확장

이번 파트너십의 재정 규모는 OpenAI 역사상 단일 파트너와의 계약 중 가장 크다.

항목	규모	비고
Amazon의 OpenAI 투자	50억 달러	15억 선행 + 35억 조건부
OpenAI 전체 펀딩 라운드	1,100억 달러 (출처: GeekWire)	SoftBank, NVIDIA 포함
OpenAI 기업가치 (pre-money)	7,300억 달러 (출처: GeekWire)	2026년 4월 기준
AWS 클라우드 계약 확장	기존 380억 + 추가 1,000억	8년간 추가
Trainium 사용 약정	2기가와트 용량	AWS 자체 AI 칩

(출처: GeekWire, 2026-04-28 기준)

애널리스트 추산에 따르면 총 클라우드 계약(기존 380억 + 추가 1,000억 달러)을 8년으로 나누면 연 약 170억 달러 규모다. 이는 AWS의 2026년 예상 매출의 약 11%에 해당한다. (출처: GeekWire)

Trainium이란?

Trainium은 Amazon이 자체 개발한 AI 학습·추론 전용 칩이다. OpenAI가 AWS 계약에서 2기가와트 용량의 Trainium 사용을 약정했다는 것은 OpenAI 모델 훈련 및 서빙 인프라의 일부가 AWS 하드웨어 위에서 실행된다는 의미다. NVIDIA 의존도를 낮추려는 양사의 공통 이해관계가 맞물린 결과이기도 하다.

7. OpenAI Frontier — AWS 독점 엔터프라이즈 플랫폼

이번 발표에서 가장 전략적 의미가 큰 항목은 OpenAI Frontier다. 개별 모델 API 접근이 아닌, AI 에이전트 팀을 구축하고 관리하는 엔터프라이즈 플랫폼이다.

핵심: AWS = OpenAI Frontier의 독점 외부 클라우드 배포처

AWS가 exclusive third-party cloud distribution provider로 지정됐다. OpenAI가 직접 판매하는 것 외에, 외부 클라우드를 통해 Frontier를 도입하려면 AWS를 통해야 한다는 의미다. Azure나 Google Cloud에서는 Frontier를 쓸 수 없다.

OpenAI Frontier란 무엇인가

OpenAI Frontier는 AI 에이전트 팀을 만들고 관리하는 플랫폼이다. 공개된 정보 기준 특징:

공유 컨텍스트(shared context)를 가진 AI 에이전트 팀 구성
거버넌스 및 보안 제어 내장
여러 에이전트 간 협업 워크플로우 지원

Stateful Runtime Environment

AWS와 OpenAI는 Stateful Runtime Environment를 공동 개발한다. OpenAI 모델로 구동되며 Amazon Bedrock을 통해 제공되는 이 환경은 고객이 AI 애플리케이션과 에이전트를 "프로덕션 스케일"로 구축할 수 있는 기반이 된다. (출처: GeekWire)

8. 기술 통합 — IAM, PrivateLink, Trainium, AgentCore

AWS 환경에서 OpenAI 제품을 쓸 때 적용되는 보안·인프라 통합 요소를 정리한다.

AWS 서비스/기능	역할	적용 대상
IAM	인증·권한 관리 — 기존 AWS 계정으로 OpenAI 호출	모든 제품
AWS PrivateLink	퍼블릭 인터넷 우회, VPC 내 프라이빗 연결	보안 민감 환경
암호화	전송 중·저장 중 데이터 암호화	모든 제품
CloudTrail	API 호출 감사 로그 — 규제 요구사항 충족	모든 제품
Bedrock Guardrails	콘텐츠 필터링, 안전 가드레일	모든 제품
Bedrock AgentCore	Managed Agents의 기본 컴퓨팅 환경	Bedrock Managed Agents
Trainium	OpenAI 모델 학습·서빙용 AWS 자체 AI 칩	인프라 레이어

(출처: AWS What's New, 2026-04-28)

이 통합의 실질적 의미는 OpenAI 제품이 AWS의 컴플라이언스 경계 안으로 들어온다는 것이다. HIPAA, SOC 2, FedRAMP 등 AWS가 인증받은 규제 프레임워크를 OpenAI 호출에도 동일하게 적용할 수 있다. 이는 의료·금융·공공 부문에서 OpenAI 도입 장벽을 크게 낮춘다.

9. 개발자·기업에게 지금 당장 의미하는 것

이 발표를 접한 개발자와 기업의 입장에 따라 의미가 다르다.

AWS 메인 스택으로 이미 운영 중인 팀

가장 직접적인 수혜자다. 기존 IAM 크레덴셜, 보안 검토 프로세스, AWS 청구 계정을 그대로 쓰면서 GPT-5.5를 호출한다. 별도 OpenAI API 키 관리, 별도 컴플라이언스 승인이 필요 없다. Codex CLI를 AWS 크레덴셜로 인증하는 방식은 AWS Builders 블로그에서 상세히 다룬다.

Azure 기반으로 OpenAI를 쓰던 팀

즉각적인 전환 필요성은 없다. Azure OpenAI Service는 계속 운영되고, Microsoft는 2032년까지 비독점 라이선스를 유지한다. 다만 향후 멀티클라우드 전략을 검토하거나 AWS 워크로드와 OpenAI를 더 긴밀하게 통합하고 싶은 팀이라면 Limited Preview 신청을 고려할 시점이다.

규제 산업(금융·의료·공공) 팀

AWS의 기존 컴플라이언스 인증이 OpenAI 제품에 그대로 적용되는 구조는 이 업종에서 의미가 크다. 이전에는 "OpenAI가 우리 규제 요구사항을 충족하는가"를 별도로 검토해야 했다. Bedrock을 통하면 "AWS가 해당 인증을 보유하고 있는가"로 질문이 단순화된다.

에이전트 시스템을 구축하는 팀

Bedrock Managed Agents는 아직 Limited Preview다. 지금 당장 프로덕션 에이전트를 올릴 수 있는 상태는 아니다. 그러나 설계 단계라면 AWS 환경에서 OpenAI 기반 에이전트를 만들 때 Bedrock Managed Agents + AgentCore 조합을 아키텍처에 포함시킬 수 있다.

10. 경쟁 구도 변화 — Azure vs AWS vs Google

이번 발표로 클라우드 AI 경쟁 구도는 명확하게 재편됐다.

구분	Microsoft Azure	Amazon AWS	Google Cloud
OpenAI 모델 접근	Azure OpenAI Service (비독점, 2032년까지)	Bedrock (Limited Preview → GA)	미지원
OpenAI 엔터프라이즈 플랫폼(Frontier)	미지원	독점 배포	미지원
자체 AI 모델	Phi 시리즈	Amazon Nova	Gemini
Anthropic Claude	미지원	Bedrock (주요 모델)	Vertex AI (주요 모델)
OpenAI에 대한 투자	기존 대규모 투자 (비공개)	50억 달러	미투자

한 줄로 요약하면: Azure는 OpenAI의 원조 파트너로서 안정적 접근권을 유지하지만, AWS는 엔터프라이즈 에이전트 플랫폼(Frontier)의 독점 외부 배포처로 더 깊은 통합 위치를 확보했다. Google Cloud는 OpenAI 라인업에서 완전히 배제됐다.

이 구도의 함의는 중장기적이다. 기업이 AI 에이전트 인프라를 구축할 때 OpenAI 기반 스택을 선택하면 AWS 환경이 자연스러운 선택지가 된다. OpenAI 없이 자체 모델 생태계를 구축하는 Google은 Gemini 모델의 경쟁력으로 독자 노선을 걸어야 한다.

Anthropic 입장에서 보면

같은 달(2026년 4월), Anthropic도 Amazon으로부터 50억 달러를 추가로 받고 100억 달러 클라우드 지출을 약정했다. (출처: TechCrunch) AWS는 한 달 안에 두 개의 주요 AI 모델 공급사(OpenAI·Anthropic)와 각각 대규모 딜을 체결했다. AWS의 "AI 모델 멀티호밍" 전략이 본격화됐다.

11. 현황 및 주의사항

발표 내용 그대로 믿기 전에 현재 상태와 불확실성을 명확히 확인한다.

현재 상태 (2026-05-03 기준)

세 제품 모두 Limited Preview — 신청 폼을 통해 접근. 모든 AWS 고객이 즉시 사용할 수 없다.
가격 미공개 — 구체적 가격표가 공개되지 않았다. 관심 고객은 문의 폼을 통해 연락하라고 안내한다.
GA 일정 "몇 주 내" — 정확한 날짜 없이 "몇 주 내 일반 출시"라고만 밝혔다. (출처: OpenAI 발표)
모델 ID 미확정 — Bedrock 콘솔에서의 실제 모델 식별자는 공개되지 않았다.
지역 가용성 미공개 — 어느 AWS 리전에서 가용한지 명시되지 않았다.

대규모 발표에서 자주 나오는 함정

"AWS에서 GPT-5.5를 지금 바로 쓸 수 있다"는 표현은 부정확하다. Limited Preview이므로 신청 후 승인을 받아야 접근 가능하다. GA 전 Limited Preview 단계에서는 기능·가격·API 인터페이스가 변경될 수 있다. 프로덕션 도입 결정은 GA 발표 이후 공식 문서를 확인하고 내리는 것이 안전하다.

12. 트러블슈팅 Q&A

Q. 지금 바로 AWS에서 GPT-5.5를 사용할 수 있나요?

A. 아니다. 2026년 4월 28일 기준 Limited Preview다. openai.com/index/openai-on-aws 페이지의 신청 폼을 통해 액세스를 요청해야 한다. GA는 "몇 주 내"로 예정됐다.

Q. Azure OpenAI를 쓰고 있는데 AWS로 마이그레이션해야 하나요?

A. 즉각적인 전환 필요성은 없다. Azure OpenAI Service는 Microsoft의 비독점 라이선스(2032년까지)로 계속 운영된다. 마이그레이션은 AWS 워크로드와의 통합 필요성, 컴플라이언스 요구사항, OpenAI Frontier 도입 계획 등을 종합적으로 판단해야 할 사항이다.

Q. Codex on AWS와 GitHub Copilot의 차이는 무엇인가요?

A. GitHub Copilot은 IDE 코드 자동완성에 최적화된 반면, Codex on AWS는 코드 작성부터 리팩터링, 테스트, 레거시 현대화, 문서 작업까지 포괄하는 에이전트 제품이다. 또한 AWS IAM·컴플라이언스 환경과 통합된다는 점에서 엔터프라이즈 보안 요구사항을 충족하는 방식이 다르다.

Q. OpenAI Frontier는 Google Cloud나 Azure에서도 쓸 수 있나요?

A. 현재 공개 정보 기준으로는 AWS가 OpenAI Frontier의 독점 외부 클라우드 배포처다. Azure나 Google Cloud에서는 Frontier를 쓸 수 없다. OpenAI 직접 판매는 별도다.

Q. Trainium을 별도로 설정해야 하나요?

A. 아니다. Trainium은 OpenAI가 AWS 인프라 위에서 모델을 훈련·서빙하는 데 사용하는 내부 하드웨어다. 개발자가 Bedrock API를 호출할 때 Trainium을 직접 설정하거나 선택할 필요는 없다.

13. 결론 — 언제 쓰고, 언제 기다리는가

이번 발표를 한 문장으로 요약하면: OpenAI가 Azure 독점에서 벗어나 멀티클라우드 전략으로 전환했고, AWS가 그 첫 번째이자 가장 깊은 통합 파트너가 됐다.

상황	권장 행동
AWS 기반으로 운영 중이고 OpenAI 모델 도입을 검토 중	Limited Preview 신청 → GA 후 공식 가격 확인
Azure OpenAI로 이미 프로덕션 운영 중	즉각 전환 불필요. GA 이후 비교 검토
엔터프라이즈 에이전트 플랫폼을 설계 중	OpenAI Frontier 공식 발표 확인 후 아키텍처 반영
규제 산업에서 GPT 도입을 검토 중	AWS PrivateLink + CloudTrail 통합 구조 우선 검토
개인 개발자로 Codex를 써보고 싶다	GA 대기 후 Codex CLI + Bedrock 인증 방식 시도

도입 플레이북

오늘: openai.com/index/openai-on-aws에서 Limited Preview 신청 폼 작성
이번 주: AWS 계정의 IAM 정책과 CloudTrail 설정을 Bedrock 신규 모델 호출에 맞게 검토
GA 이후: 가격 공개 후 Azure OpenAI 대비 비용·성능 비교, 팀 내 Codex 파일럿 프로젝트 선정

전망은 명확하다. OpenAI의 멀티클라우드 전환은 모델 접근성을 높이는 동시에 클라우드 벤더 간 AI 경쟁을 본격화한다. AWS가 OpenAI Frontier의 독점 배포처라는 지위는 단기 이점이지만, 중장기적으로는 OpenAI 제품이 어느 클라우드에서나 쓰이는 세상을 향한 첫걸음이기도 하다.

지금은 Limited Preview 신청을 해두고, GA 공식 발표에서 가격과 지역 가용성을 확인하는 것이 현실적인 다음 단계다.

참고 자료

공식 문서

파트너십 배경 및 재정

뉴스 보도

관련 발표

Claude Code 4월 업데이트(v2.1.89~126 업데이트) 정리

갓대희 — Wed, 6 May 2026 01:32:45 +0900

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

Claude Code가 v2.1.87 이후에도 빠르게 바뀌었다.

이번 글에서는 v2.1.89부터 v2.1.126까지 공식 CHANGELOG 기준 27개 릴리스를 하나로 정리한다. v2.1.88은 npm 메타데이터에는 흔적이 있지만 현재 공식 CHANGELOG와 현재 registry artifact 기준으로는 일반 릴리스처럼 다루기 어렵다. 그래서 이 글에서는 v2.1.88을 별도 주의 사항으로만 짚고, 실제 기능 변화는 v2.1.89 이후를 중심으로 본다.

이번 업데이트의 핵심 : Auto Mode가 더 조심스러워졌고, Opus 4.7과 effort 제어가 확장되었고, Remote Control·MCP·플러그인·보안 정책이 운영 도구답게 다듬어졌다.

버전 타임라인 (v2.1.89 → v2.1.126)
v2.1.88은 왜 조심해서 봐야 하나
Auto Mode — 자동 실행의 안전장치가 촘촘해지다
Opus 4.7 + xhigh effort — 모델 체급과 조절 장치
No Flicker / TUI / Focus — 터미널 UI의 큰 방향 전환
Remote Control & Cloud — 로컬 세션이 웹과 이어지다
/ultrareview, /team-onboarding, /powerup — 학습과 리뷰 도구
MCP & 플러그인 — 더 늦게 로드하고, 더 안전하게 연결한다
훅 시스템 — PreCompact, PermissionDenied, PostToolUse 확장
보안 수정 — Bash 권한, 샌드박스, managed settings
성능 & 안정성 — /resume, 프롬프트 캐시, 긴 세션
Windows & VSCode — PowerShell이 본격적으로 들어오다
Provider / Gateway — Bedrock, Vertex, Foundry, 커스텀 게이트웨이
v2.1.126에서 특히 확인할 변경
지금 확인해야 할 것
결론

1. 버전 타임라인

버전	주요 헤드라인
v2.1.88	현재 공식 CHANGELOG 항목 없음. npm 메타데이터 흔적은 있으나 일반 릴리스처럼 요약하지 않음
v2.1.89	NO_FLICKER, PermissionDenied 훅, named subagents, MCP nonblocking, Auto Mode denial UX
v2.1.90	/powerup, explicit user boundary 존중, PowerShell 권한 하드닝, SDK 장기 세션 성능
v2.1.91~92	plugin bin 실행, `disableSkillShellExecution`, fail-closed remote settings, Bedrock setup wizard, `/release-notes` picker
v2.1.94	기본 effort high 전환(API key/Bedrock/Vertex/Foundry/Team/Enterprise), Bedrock Mantle 지원
v2.1.96~98	Vertex setup wizard, Monitor tool, Linux subprocess sandbox, Bash 권한 우회 다수 수정
v2.1.101	/team-onboarding, OS CA store trust, cloud env 자동 생성, command injection 수정
v2.1.105	EnterWorktree path, PreCompact 훅, plugin monitors, `/proactive` alias, stream hang 개선
v2.1.108~110	1시간 prompt cache TTL, recap, built-in slash command Skill invocation, /tui, Remote Control 명령 확장
v2.1.111	Opus 4.7 xhigh, /effort slider, /ultrareview, /less-permission-prompts, Auto Mode 플래그 제거
v2.1.113	네이티브 바이너리 dispatch, `sandbox.network.deniedDomains`, Bash deny rule 강화
v2.1.116	`/resume` 대형 세션 최대 67% 개선, MCP startup 최적화, installer URL 변경
v2.1.117~119	forked subagent, config persistence, vim visual mode, themes, plugin tag, prUrlTemplate, OTEL 확장
v2.1.120	Git Bash 없이 Windows PowerShell 사용, `claude ultrareview` CLI, `${CLAUDE_EFFORT}`
v2.1.121~123	MCP `alwaysLoad`, plugin prune, /skills 검색, Bedrock service tier, PR URL resume 검색, OAuth 401 수정
v2.1.126	gateway /v1/models picker, `claude project purge`, OAuth code paste login, PowerShell primary shell, 보안 수정

버전 범위 주의

2026-05-04 기준 npm registry의 latest와 next는 2.1.126이지만, stable dist-tag는 2.1.118이다. 따라서 이 글에서 말하는 "최신"은 latest 채널 기준이며, 조직에서 안정 채널을 따르는 경우 실제 설치 버전이 다를 수 있다.

2. v2.1.88은 왜 조심해서 봐야 하나

v2.1.87 이후 바로 v2.1.88을 이어서 정리하고 싶지만, 이 버전은 글에 넣을 때 조심스러웠다. (단하나의 실수도 악플로 이어지기도 하니..) 현재 공식 CHANGELOG에는 v2.1.88 섹션이 없고, v2.1.88의 registry version endpoint와 tarball endpoint도 일반 설치 가능한 릴리스처럼 확인되지 않는다.

이 글의 처리 원칙

공식 CHANGELOG에 남아 있는 v2.1.89 이후 항목만 기능 분석 대상으로 삼는다.
v2.1.88은 "공개 아티팩트 기준으로 일반 릴리스처럼 다루기 어렵다" 정도로만 설명하고 넘어가도록 하려 한다.

3. Auto Mode — 자동 실행의 안전장치가 촘촘해지다

v2.1.89 이후 Auto Mode의 방향은 "더 많이 자동화"만이 아니다. 오히려 핵심은 자동 실행을 하되, 사용자가 명시한 경계를 더 잘 지키는 것에 가깝다.

버전	Auto Mode 변경
v2.1.89	Auto Mode에서 거부된 명령을 알림으로 보여주고, `/permissions` Recent 탭에서 재시도 가능
v2.1.90	사용자가 "push하지 마", "X 전에는 Y 하지 마"처럼 명시한 경계를 더 잘 존중
v2.1.111	Opus 4.7 사용 시 Max 구독자에게 Auto Mode 제공. 별도 `--enable-auto-mode` 플래그 요구 제거
v2.1.118	`autoMode.allow`, `autoMode.soft_deny`, `autoMode.environment`에 `"$defaults"`를 포함해 기본 규칙과 사용자 규칙을 병합 가능
v2.1.120	Auto Mode denial 메시지가 설정 문서로 연결되어, 왜 막혔는지 추적하기 쉬워짐
v2.1.126	권한 체크가 멈춰 보일 때 spinner가 빨간색으로 바뀌어 "도구 실행 중"과 "권한 확인 정체"를 구분

실전 팁

Auto Mode를 켤 때는 "하지 말아야 할 일"을 프롬프트에 분명히 적는 것이 중요하다. v2.1.90 이후에는 이런 명시적 경계를 더 잘 반영하도록 수정되었지만, 애초에 경계가 모호하면 자동화가 과감하게 보일 수 있다.

4. Opus 4.7 + xhigh effort — 모델 체급과 조절 장치

이전 글에서 Opus 4.6과 1M 컨텍스트를 다뤘다면, 이번 구간의 모델 변화는 Opus 4.7과 effort 제어이다.

특히 v2.1.111은 모델 체감에 영향을 주는 변화가 많다.

버전	모델 / effort 변경
v2.1.94	API key, Bedrock, Vertex, Foundry, Team, Enterprise 사용자의 기본 effort가 medium → high로 변경
v2.1.108	`ENABLE_PROMPT_CACHING_1H`, `FORCE_PROMPT_CACHING_5M`로 prompt cache TTL 제어
v2.1.111	Claude Opus 4.7 xhigh 추가. `/effort`, `--effort`, 모델 피커에서 선택 가능
v2.1.111	`/effort`를 인자 없이 실행하면 interactive slider로 열림
v2.1.117	Pro/Max 구독자의 Opus 4.6, Sonnet 4.6 기본 effort가 high로 변경
v2.1.122	Bedrock application inference profile ARN에서 effort 옵션 표시 및 전달 문제 수정
v2.1.126	커스텀 Anthropic-compatible gateway 사용 시 `/v1/models`에서 모델 목록을 읽어 `/model` 피커에 표시

# v2.1.111 이후: effort를 더 명시적으로 조절
/effort          # interactive slider
/effort xhigh    # Opus 4.7에서 xhigh 사용

# CLI 실행 시 effort 지정
claude --effort high

주의

xhigh는 모든 모델에서 같은 의미로 동작하는 범용 옵션이 아니다. 공식 CHANGELOG는 Opus 4.7 맥락에서 설명하며, 다른 모델은 high로 fallback된다고 적고 있다. 팀 설정이나 provider gateway를 쓰는 경우에는 실제 모델 지원 여부를 먼저 확인해야 한다.

5. No Flicker / TUI / Focus — 터미널 UI의 큰 방향 전환

v2.1.89부터 Claude Code의 터미널 UI는 단순 렌더링 개선을 넘어, 긴 세션을 읽고 조작하는 방식을 바꾸기 시작했다. 핵심 키워드는 NO_FLICKER, TUI, Focus다.

기능	버전	설명
NO_FLICKER	v2.1.89	`CLAUDE_CODE_NO_FLICKER=1`로 alt-screen 기반 flicker-free 렌더링 opt-in
Focus view	v2.1.97	NO_FLICKER 모드에서 prompt, one-line tool summary, final response 중심으로 보는 집중 뷰
/tui	v2.1.110	동일 대화에서 `/tui fullscreen`으로 fullscreen 렌더링 전환
/focus	v2.1.110	`Ctrl+O`는 normal/verbose transcript 토글로 정리되고, focus는 별도 `/focus`로 분리
Dialog scroll	v2.1.121	터미널보다 큰 dialog를 방향키, PgUp/PgDn, home/end, mouse wheel로 스크롤 가능

실전 팁

긴 세션에서 화면이 자주 깨지거나 스크롤이 흔들린다면, 먼저 /tui fullscreen과 /focus 조합을 확인해볼 만하다. 단순히 예쁜 UI가 아니라, 도구 호출이 많은 세션에서 읽어야 할 정보량을 줄이는 방향이다.

6. Remote Control & Cloud — 로컬 세션이 웹과 이어지다

이전 구간에서 VSCode Remote Control이 등장했다면, 이번 구간에서는 Remote Control이 실제 운영 가능한 보조 인터페이스에 가까워졌다. 모바일/웹 클라이언트에서 사용할 수 있는 명령이 늘고, PR·세션·클라우드 환경과의 연결도 더 촘촘해졌다.

버전	Remote / Cloud 변경
v2.1.92	Remote Control 세션 이름 기본 prefix가 hostname 기반으로 변경. `--remote-control-session-name-prefix`로 변경 가능
v2.1.101	`/ultraplan` 등 remote-session 기능이 기본 cloud environment를 자동 생성
v2.1.110	`/context`, `/exit`, `/reload-plugins`가 Remote Control 클라이언트에서 동작
v2.1.110	Remote Control과 push 설정이 켜져 있으면 Claude가 모바일 push notification을 보낼 수 있음
v2.1.113	`/extra-usage`가 Remote Control 클라이언트에서도 동작. 파일 autocomplete suggestion도 조회 가능
v2.1.119	`prUrlTemplate` 설정으로 footer PR badge를 GitHub 외 custom review URL로 연결 가능
v2.1.122	PR URL을 `/resume` 검색창에 붙여넣으면 해당 PR을 만든 세션을 찾음 (GitHub, GitLab, Bitbucket 등)

흐름 변화

Claude Code가 "내 터미널 안에서만 도는 도구"에서 벗어나고 있다. 로컬 CLI 세션, 웹/모바일 Remote Control, PR, cloud environment가 하나의 작업 흐름으로 묶이는 방향이다.

7. /ultrareview, /team-onboarding, /powerup — 학습과 리뷰 도구

이번 구간에서는 "Claude Code 자체를 더 잘 쓰게 만드는 기능"도 늘었다. 단순 명령 추가라기보다, 팀 학습과 리뷰 자동화 쪽으로 방향이 보인다.

명령어	버전	기능
`/powerup`	v2.1.90	Claude Code 기능을 animated demo와 함께 학습하는 interactive lesson
`/team-onboarding`	v2.1.101	로컬 Claude Code 사용 패턴을 바탕으로 팀원 온보딩 가이드 생성
`/less-permission-prompts`	v2.1.111	트랜스크립트에서 반복되는 read-only Bash/MCP 호출을 분석해 allowlist 후보 제안
`/ultrareview`	v2.1.111	cloud 기반 병렬 multi-agent 분석으로 현재 브랜치 또는 특정 PR을 종합 리뷰
`claude ultrareview`	v2.1.120	CI/script에서 실행 가능한 non-interactive ultrareview CLI. `--json` 지원

# 현재 브랜치 리뷰
/ultrareview

# 특정 PR 리뷰
/ultrareview 123

# CI나 스크립트에서 실행
claude ultrareview 123 --json

8. MCP & 플러그인 — 더 늦게 로드하고, 더 안전하게 연결한다

MCP와 플러그인은 v2.1.89 이후에도 계속 확장됐다. 방향은 두 가지다. 첫째, 느린 서버 때문에 세션 시작이 막히지 않게 한다. 둘째, 플러그인 의존성과 보안 정책을 더 예측 가능하게 만든다.

버전	MCP / Plugin 변경
v2.1.89	`MCP_CONNECTION_NONBLOCKING=true`로 `-p` 모드에서 MCP 연결 대기를 건너뜀. `--mcp-config` 서버 연결도 5초로 bounded
v2.1.91	MCP result persistence override `_meta["anthropic/maxResultSizeChars"]` 지원. 플러그인 `bin/` 실행 파일 지원
v2.1.94	plugin skill frontmatter name을 invocation name으로 사용. plugin hook/frontmatter 관련 수정
v2.1.105	플러그인 background monitor 지원. marketplace plugin의 `package.json`/lockfile 의존성 자동 설치 수정
v2.1.116	stdio MCP가 여러 개일 때 startup 개선. `resources/templates/list`를 최초 `@` mention까지 지연
v2.1.117	plugin install 시 누락된 dependency 자동 설치. managed-settings의 blocked/strict marketplaces를 install/update/autoupdate에 적용
v2.1.121	MCP server config에 `alwaysLoad` 옵션 추가. `claude plugin prune`으로 orphan dependency 정리
v2.1.122	`/mcp`에서 수동 서버와 claude.ai connector 중복 상황을 더 명확히 표시

실전 팁

MCP 서버가 많아 시작이 느린 팀은 alwaysLoad를 남발하지 않는 것이 좋다. 자주 쓰는 핵심 서버만 항상 로드하고, 나머지는 tool-search나 @ mention 시점에 늦게 연결되도록 두는 편이 대형 환경에서 유리하다.

9. 훅 시스템 — PreCompact, PermissionDenied, PostToolUse 확장

훅 시스템은 v2.1.85에서 조건부 실행을 얻었고, 이후에는 자동화 파이프라인에 필요한 이벤트와 출력 제어가 계속 추가됐다.

훅 / 기능	버전	용도
`PermissionDenied`	v2.1.89	Auto Mode classifier가 명령을 거부한 뒤 실행. `{retry: true}`로 모델에게 재시도 가능 신호 전달
`PreCompact`	v2.1.105	compaction 직전 실행. exit code 2 또는 `{"decision":"block"}`으로 compaction 차단 가능
Agent frontmatter hooks	v2.1.116	`--agent`로 main-thread agent 실행 시 frontmatter `hooks:`도 동작
`duration_ms`	v2.1.119	`PostToolUse`, `PostToolUseFailure` hook input에 도구 실행 시간 추가
`updatedToolOutput`	v2.1.121	`PostToolUse` hook이 모든 도구 출력 교체 가능. 이전에는 MCP 중심

// 개념 예시: compaction 직전 검사
{
  "hooks": {
    "PreCompact": [{
      "type": "command",
      "command": "test -f .claude/no-compact && exit 2 || exit 0"
    }]
  }
}

주의

훅이 강력해질수록 세션 동작을 가로막는 원인도 훅이 될 수 있다. v2.1.105 이후에는 hook stderr 첫 줄을 transcript에 더 잘 보여주는 개선도 들어갔지만, 팀 환경에서는 hook 실패 메시지를 사람이 읽을 수 있게 작성하는 것이 중요하다.

10. 보안 수정 — Bash 권한, 샌드박스, managed settings

이번 구간에서 가장 중요하게 봐야 할 부분은 보안이다. 특히 Bash permission rule, sandbox, managed settings 쪽 수정이 많다. 자동화 도구가 강력해질수록 "어디까지 자동으로 허용할 것인가"가 핵심 운영 이슈가 된다.

주요 보안 수정 하이라이트

v2.1.98: backslash-escaped flag가 read-only로 auto-allow되어 임의 코드 실행으로 이어질 수 있던 Bash permission bypass 수정
v2.1.98: compound Bash command가 safety check와 explicit ask rule을 우회하던 문제 수정
v2.1.101: LSP binary detection의 POSIX which fallback에서 command injection 취약점 수정
v2.1.113: macOS /private/{etc,var,tmp,home} 경로를 위험 삭제 대상으로 취급
v2.1.113: Bash deny rule이 env, sudo, watch, ionice, setsid 같은 wrapper 명령도 매칭
v2.1.116: sandbox auto-allow가 rm/rmdir의 위험 경로 safety check를 우회하지 못하게 수정
v2.1.119: blockedMarketplaces가 hostPattern, pathPattern을 제대로 강제
v2.1.126: allowManagedDomainsOnly / allowManagedReadPathsOnly가 특정 managed-settings 우선순위 조합에서 무시되던 문제 수정

영역	무엇이 바뀌었나
Bash permission	read-only처럼 보이지만 실제로는 위험한 flag, redirect, compound command, wrapper command를 더 엄격하게 검사
Sandbox	네트워크 domain deny, 위험 삭제 경로, sandbox auto-allow 예외를 더 명확히 제어
Managed settings	조직 정책이 플러그인 설치/업데이트/마켓플레이스 접근/읽기 경로 제한에 더 강하게 적용
Skip permissions	v2.1.126에서 일부 보호 경로에 대한 prompt bypass 범위가 넓어졌지만, catastrophic removal command에는 안전망 prompt 유지

11. 성능 & 안정성 — /resume, 프롬프트 캐시, 긴 세션

v2.1.59~87 구간에서도 긴 세션 안정화가 중요했다. 이번 구간에서도 같은 방향이 계속된다. 특히 /resume, prompt cache, transcript, MCP startup, long session memory leak가 반복적으로 다듬어졌다.

버전	성능 / 안정성 개선
v2.1.90	`--resume` 첫 요청의 full prompt-cache miss 수정. SDK long conversation transcript write의 quadratic slowdown 제거
v2.1.97	MCP HTTP/SSE 재연결 시 버퍼가 시간당 약 50MB씩 쌓이던 누수 수정
v2.1.101	대형 세션에서 `--resume`/`--continue`가 live conversation 대신 dead-end branch에 붙던 문제 수정
v2.1.105	API stream이 5분간 무응답이면 abort 후 non-streaming retry. 네트워크 에러도 silent spinner 대신 즉시 retry 메시지 표시
v2.1.116	40MB+ 대형 세션에서 `/resume` 최대 67% 개선. dead-fork entries가 많은 세션 처리 개선
v2.1.121	이미지가 많은 세션에서 multi-GB RSS까지 커질 수 있던 메모리 증가 수정. `/usage` 대형 transcript history 메모리 누수 수정
v2.1.126	Mac sleep 후 stream idle timeout, 장시간 thinking pause 중 background/remote session timeout 오탐 수정

실전 팁

긴 세션을 자주 재개한다면 v2.1.116 이후의 차이가 크다. 특히 40MB가 넘는 transcript, fork가 많은 세션, 중간에 종료된 세션을 자주 다루는 사용자라면 단순 업데이트만으로도 체감이 날 수 있다.

12. Windows & VSCode — PowerShell이 본격적으로 들어오다

Windows 지원은 이번 구간의 중요한 축이다. Git Bash 의존을 줄이고, PowerShell을 실제 도구로 다루기 시작했다. 동시에 VSCode/Cursor 통합 터미널의 스크롤, clipboard, voice dictation 문제도 계속 수정됐다.

버전	Windows / VSCode 변경
v2.1.89	Windows에서 voice mode WebSocket 문제, CRLF 중복, PowerShell stderr 처리 등 수정
v2.1.91	Windows version cleanup이 active rollback copy를 보호하도록 수정
v2.1.111	PowerShell tool 점진 rollout. `CLAUDE_CODE_USE_POWERSHELL_TOOL`로 opt in/out
v2.1.113	Windows `Ctrl+Backspace` word delete, long URL clickability, multiline input readline 동작 개선
v2.1.120	Git for Windows/Git Bash가 없어도 PowerShell을 shell tool로 사용
v2.1.121	VSCode voice dictation이 Claude Code language 설정이 없을 때 VSCode speechLanguage 설정을 존중
v2.1.126	PowerShell 7 설치 위치 탐지 개선. PowerShell tool 활성 시 PowerShell을 primary shell로 취급. Windows clipboard command-line 노출 방지

Windows 사용자는 확인

이제 Windows에서는 "Git Bash가 없으면 Claude Code가 제대로 못 돈다"에 가까운 전제가 약해지고 있다. 다만 PowerShell tool은 버전별 rollout과 설정 영향을 받으므로, 실제 환경에서는 claude doctor와 /status로 어떤 shell tool이 활성화되어 있는지 확인하는 것이 좋다.

13. Provider / Gateway — Bedrock, Vertex, Foundry, 커스텀 게이트웨이

기업 환경에서는 Anthropic API만 쓰지 않는다. Bedrock, Vertex, Foundry, 또는 Anthropic-compatible gateway를 붙이는 경우가 많다. 이번 구간은 이런 provider 환경의 마찰을 많이 줄였다.

버전	Provider 변경
v2.1.92	login screen에서 interactive Bedrock setup wizard 제공
v2.1.94	Amazon Bedrock powered by Mantle 지원. `CLAUDE_CODE_USE_MANTLE=1`
v2.1.96	Bedrock auth 관련 403 regression 수정
v2.1.98	Google Vertex AI setup wizard 추가. GCP auth, project/region, credential verification, model pinning 안내
v2.1.108	API key, Bedrock, Vertex, Foundry에서 1시간 prompt cache TTL opt-in 지원
v2.1.122	`ANTHROPIC_BEDROCK_SERVICE_TIER`로 Bedrock service tier 선택
v2.1.126	`ANTHROPIC_BASE_URL`이 Anthropic-compatible gateway를 가리킬 때 `/v1/models` 모델 목록을 `/model`에 표시

실전 팁

사내 gateway를 쓰는 팀이라면 v2.1.126의 /v1/models 연동이 중요하다. 모델 ID를 사람이 외워서 고르는 방식에서, gateway가 제공하는 모델 목록을 Claude Code UI에서 직접 보는 방식으로 넘어갈 수 있다.

14. v2.1.126에서 특히 확인할 변경

현재 latest 기준 마지막 릴리스인 v2.1.126은 단순 버그픽스만 있는 버전이 아니다.

로그인, 프로젝트 상태 삭제, gateway 모델 피커, Windows PowerShell, 보안 정책까지 여러 운영 포인트가 들어 있다.

기능	왜 중요한가
`claude project purge`	프로젝트의 transcripts, tasks, file history, config entry 등 Claude Code 상태를 삭제. `--dry-run`, `--interactive`, `--all` 지원
OAuth code paste login	WSL2, SSH, container처럼 browser callback이 localhost에 닿지 않는 환경에서 terminal에 OAuth code를 붙여넣어 로그인 가능
Gateway model picker	사내 gateway가 제공하는 `/v1/models` 목록을 모델 선택 UI에서 확인 가능
PowerShell primary shell	PowerShell tool이 켜져 있으면 Claude가 PowerShell을 기본 shell로 더 명확히 인식
Oversized image 처리	2000px 초과 이미지 paste로 세션이 깨지는 문제를 downscale/retry로 처리
Windows clipboard privacy	복사 내용이 process command-line arguments로 노출되는 문제를 줄임. EDR/SIEM 환경에서 중요

# 프로젝트 Claude Code 상태 삭제 전 점검
claude project purge . --dry-run

# 대화형으로 확인하며 삭제
claude project purge . --interactive

주의

claude project purge는 이름 그대로 상태 삭제 명령이다. 실제 삭제 전에는 반드시 --dry-run으로 어떤 데이터가 지워지는지 확인하는 편이 안전하다.

15. 지금 확인해야 할 것

당신의 상황	지금 해볼 것
Auto Mode가 과감하게 느껴진다	명시적 금지 조건을 프롬프트와 settings에 적고, `/permissions` Recent 탭에서 거부/재시도 흐름을 확인한다
긴 세션 재개가 느리다	v2.1.116 이후로 업데이트하고 `/resume` 대형 세션 개선을 확인한다
터미널 화면이 자주 깨진다	`/tui fullscreen`, `/focus`, NO_FLICKER 관련 설정을 점검한다
MCP 서버가 많아 시작이 느리다	`alwaysLoad`를 핵심 서버에만 쓰고, 나머지는 지연 로드되도록 정리한다
팀에서 플러그인을 운영한다	`blockedMarketplaces`, `strictKnownMarketplaces`, `claude plugin prune`를 확인한다
Windows에서 Claude Code를 쓴다	PowerShell tool 활성 여부와 Git Bash 의존 여부를 `claude doctor`로 확인한다
사내 gateway를 쓴다	`ANTHROPIC_BASE_URL` gateway의 `/v1/models` 응답이 `/model` 피커에 반영되는지 확인한다
프로젝트 상태를 정리하고 싶다	`claude project purge . --dry-run`으로 삭제 대상부터 확인한다

# 현재 설치 버전 확인
claude --version

# 업데이트
claude update

# 환경 점검
claude doctor

16. 결론

v2.1.59~87 구간이 Auto Memory, /loop, Voice, 검색, 팀 정책, 훅의 확장이었다면, v2.1.89~126 구간은 그 기능들을 실제 운영 환경에서 덜 깨지게 만드는 구간에 가깝다. Auto Mode는 더 안전한 경계를 갖추고, 모델 선택은 Opus 4.7과 gateway까지 넓어졌고, MCP와 플러그인은 느린 연결·의존성·정책 문제를 계속 줄이고 있다.

가장 중요한 변화는 Claude Code가 "기능 많은 CLI"를 넘어 팀 정책, 원격 세션, 플러그인 생태계, 보안 규칙을 함께 다루는 개발 운영 도구로 이동하고 있다는 점이다. 그만큼 업데이트 속도도 빠르다. 따라서 릴리즈노트를 읽을 때는 새 기능만 보지 말고, 권한·샌드박스·provider·긴 세션 안정성 수정도 같이 봐야 한다.

참고 자료

공식 CHANGELOG: GitHub
공식 CHANGELOG Raw: Raw Markdown
공식 Releases: GitHub Releases
npm registry metadata: @anthropic-ai/claude-code
Claude Code 공식 문서: Anthropic Docs

DESIGN.md 자동 생성 : DesignMD Style Extractor - 클릭 하나로 웹사이트 디자인 시스템을 추출하는 Chrome 확장 프로그램

갓대희 — Mon, 4 May 2026 02:25:52 +0900

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

Design.md를 만들때 Claude.design을 사용하며 테스트를 이것저것 해보는 와중이었다.

여러 유명한 유튜버, x.com의 빅테크 인사, 여러 한국 쓰레드를 즐겨보곤 하는데 그중 즐겨보는 @unclejobs.ai의 Threads 에서 하나의 아이디어를 보게되어 글을 작성하게 되었다.

내가 며칠 전 정리하던 Design.md 관련 글보다 핵심을 더 단정하게 짚고 있어 보였다.

2026.04.23 - [AI/Design] - DESIGN.md : Google Stitch가 도입한 DESIGN.md - DESIGN.md 도입 배경부터 적용해보기(VoltAgent awesome-design-md 컬렉션 활용 가이드)

한 문장으로 요약하면 "Google Stitch가 design-to-code 흐름을 정착시켰는데, 그 앞단(upstream)이 비어 있다"라는 지적이다.

AI는 디자인 명세를 받으면 코드를 꽤 잘 만든다. 문제는 그 명세를 누가 쓰느냐는 점이다. 디자이너가 없거나 피그마를 안 쓰는 바이브 코더에게 이 공백은 꽤 크다.

이 글에서 다루는 DesignMD Style Extractor는 그 빈 칸을 Chrome 확장 하나로 메우려는 시도다. 어떤 웹페이지든 클릭 한 번이면 페이지의 색·타이포·간격·모션을 추출해 DESIGN.md 또는 SKILL.md로 정리해 준다.

이번 글에서는 GitHub 소스를 직접 뜯어 이 확장이 어떻게 280개 요소를 샘플링하고, 어떤 기준으로 사이트의 성격을 추론하는지, 그리고 DESIGN.md/SKILL.md 두 출력 모드의 차이가 무엇인지까지 짚어본다. v0.4.0(2026-04-29 기준) 코드 기준이다.

너무 딥다이브한다는 느낌이 있다면 차라리 해당 피드를 보시는것을 추천 드립니다.

https://www.threads.com/@unclejobs.ai/post/DXLGC2hiZu4

DesignMD가 뭐고, 왜 쓰는가
설치: 1분이면 충분
실전 사용: 3단계로 끝내기
시나리오별 활용법
이것만 알고 쓰자 (주의사항)
트러블슈팅 Q&A
결론: 언제 쓰고, 언제 쓰지 않는가

1. DesignMD 가 뭐고, 왜 쓰는가

DesignMD Style Extractor는 GitHub에 공개된 MIT 라이선스 Chrome 확장프로그램다.

어떤 웹페이지든 클릭 한 번으로 색상, 폰트, 간격, 애니메이션을 읽어 DESIGN.md나 SKILL.md 파일로 만들어준다고 한다.

배경은 간단하다. 2026년 3월 Google Stitch와 함께 등장한 DESIGN.md 포맷은 Claude Code, Cursor, Codex 같은 AI 코딩 도구가 "이 파일을 보고 디자인에 맞춰라"는 식으로 참고할 수 있도록 설계됐다.

문제는 이 파일을 누가 만드느냐다. 피그마도 없고 디자이너도 없는 환경에서는 직접 써야 했는데, 이 확장프로그램을 통해 기존 웹사이트에서 역으로 추출해 만들어주는 방식으로 그 빈 자리를 채우고자 하는 컨셉이라고 한다.

vs 대안 비교

항목	DesignMD Style Extractor	직접 작성 (수기 DESIGN.md)	TypeUI Pro 스킬 풀
입력	임의의 웹페이지 URL	디자이너 가이드 + 개발자 정리	사전 큐레이션된 스킬
출력	DESIGN.md / SKILL.md	DESIGN.md	디자인 스킬 + 컴포넌트 마크다운
가격	무료 (MIT)	인건비	$30/월 또는 $120/년
데이터 처리	브라우저 내 로컬	로컬	CLI pull
적합 시나리오	기존 사이트 톤 복제, 빠른 프로토타입	신규 디자인 시스템 정의	정해진 스타일(Paper, Bento, Neobrutalism 등) 빠르게 적용

(가격 출처: TypeUI 공식, 데이터 처리 출처: Chrome Web Store 개인정보 선언)

세 방식은 같은 줄 위에 있지 않다. 직접 작성은 디자인 시스템을 새로 정의하는 작업이고, TypeUI Pro는 57개 이상의 사전 큐레이션된 스타일을 골라 쓰는 방식이다. 반면 DesignMD 확장은 이미 존재하는 사이트를 역방향으로 추출해 명세화한다. "내가 좋아하는 그 사이트처럼 만들고 싶다"라는 흔한 요구를 정면으로 받는다.

2. 설치 방법

Chrome Web Store 설치 (1클릭)

가장 간단한 경로는 https://chromewebstore.google.com/detail/designmd-style-extractor/ogpdnchdjiibhobphelbbkemnnemkfma에서 "Chrome에 추가"를 누르는 것이다. 카테고리는 Developer Tools다. 설치 후 임의의 웹페이지에서 확장 아이콘을 클릭하면 팝업이 뜬다.

ex) 나의 경우 이미 설치해서 삭제가 노출된다.

- 확장 프로그램에 설치되어있는것을 볼 수 있다.

개발자 모드 (소스에서 직접)

저장소를 직접 빌드해 쓰려면 README의 절차를 따른다. 단계는 4개다.

chrome://extensions에 접속한다.
우측 상단 Developer mode를 활성화한다.
Load unpacked를 선택한다.
클론한 프로젝트 폴더를 지정한다.

저장소가 47.06 KiB 수준이라 빌드 단계가 따로 없다. 클론 → 폴더 지정만으로 바로 동작한다.

권한은 activeTab, scripting, storage, downloads 4가지뿐이다. v0.2.0 단계에서 tabs 권한이 의도적으로 제거되었으며, 원격 서버로 데이터를 보내는 통신 권한이 없는것 같다.

실제로 Chrome Web Store 개인정보 선언에서도 "데이터를 수집하지 않으며, 제3자에게 판매하거나 핵심 기능 외 목적으로 사용하지 않는다. 추출은 브라우저 내에서만 동작한다"라고 개발자(Zoltan, typeui.sh 운영)가 직접 선언했다.

권한 목록과 현재 공개 소스의 처리 흐름을 보면 이 고지와 대체로 맞아떨어지지만, 개인정보 보장은 실제 배포본과 코드 흐름을 함께 봐야 한다.

3. 사용해보기

Step 1. 원하는 사이트에서 추출하기

따라 만들고 싶은 레퍼런스 사이트를 열고, 상단 확장 아이콘을 클릭한다.

팝업이 뜨면 Auto-extract 버튼을 누르면 된다. 수 초 안에 색상, 폰트, 간격, 모션 6개 카테고리를 자동으로 읽어온다.

팁: SPA나 모달이 있는 사이트라면, 먼저 원하는 화면 상태(모달 열린 상태 등)를 만들어 두고 Refresh를 누르면 그 시점 기준으로 다시 추출한다.

ex) 내 바이브 코딩용 사이트를 예시로 테스트 해 보았다.

- 우측 상단에 있는 플러그인 클릭

- 추출한 design.md 원문

# GodDaeHee Hub

## Mission
Create implementation-ready, token-driven UI guidance for GodDaeHee Hub that is optimized for consistency, accessibility, and fast delivery across content site.

## Brand
- Product/brand: GodDaeHee Hub
- URL: https://goddaehee.co.kr/
- Audience: readers and knowledge seekers
- Product surface: content site

## Style Foundations
- Visual style: structured, tokenized, content-first
- Main font style: `font.family.primary=Noto Sans KR`, `font.family.stack=Noto Sans KR, sans-serif, Arial, Helvetica, sans-serif`, `font.size.base=16px`, `font.weight.base=400`, `font.lineHeight.base=24px`
- Typography scale: `font.size.xs=14px`, `font.size.sm=16px`, `font.size.md=18px`, `font.size.lg=24px`, `font.size.xl=48px`
- Color palette: `color.text.primary=#171717`, `color.text.secondary=lab(35.6337 -1.58697 -10.8425)`, `color.text.tertiary=lab(7.78673 1.82345 -15.0537)`, `color.text.inverse=lab(48.0876 -2.03595 -16.5814)`, `color.surface.base=#000000`, `color.surface.muted=#ffffff`, `color.surface.raised=#6366f1`, `color.surface.strong=#f8fafc`, `color.border.muted=lab(91.7353 -0.998765 -4.76968)`
- Spacing scale: `space.1=4px`, `space.2=6px`, `space.3=8px`, `space.4=10px`, `space.5=12px`, `space.6=16px`, `space.7=20px`, `space.8=24px`
- Radius/shadow/motion tokens: `radius.xs=6px`, `radius.sm=8px`, `radius.md=32px`, `radius.lg=16777200px` | `shadow.1=rgba(0, 0, 0, 0) 0px 0px 0px 0px, rgba(0, 0, 0, 0) 0px 0px 0px 0px, rgba(0, 0, 0, 0) 0px 0px 0px 0px, rgba(0, 0, 0, 0) 0px 0px 0px 0px, rgba(0, 0, 0, 0.1) 0px 1px 3px 0px, rgba(0, 0, 0, 0.1) 0px 1px 2px -1px`, `shadow.2=rgba(0, 0, 0, 0) 0px 0px 0px 0px, rgba(0, 0, 0, 0) 0px 0px 0px 0px, rgba(0, 0, 0, 0) 0px 0px 0px 0px, rgba(0, 0, 0, 0) 0px 0px 0px 0px, oklab(0.585387 0.0253055 -0.202469 / 0.25) 0px 10px 15px -3px, oklab(0.585387 0.0253055 -0.202469 / 0.25) 0px 4px 6px -4px`, `shadow.3=rgba(0, 0, 0, 0) 0px 0px 0px 0px, rgba(0, 0, 0, 0) 0px 0px 0px 0px, rgba(0, 0, 0, 0) 0px 0px 0px 0px, rgba(0, 0, 0, 0) 0px 0px 0px 0px, oklab(0.585387 0.0253055 -0.202469 / 0.3) 0px 10px 15px -3px, oklab(0.585387 0.0253055 -0.202469 / 0.3) 0px 4px 6px -4px` | `motion.duration.instant=150ms`, `motion.duration.fast=200ms`

## Accessibility
- Target: WCAG 2.2 AA
- Keyboard-first interactions required.
- Focus-visible rules required.
- Contrast constraints required.

## Writing Tone
Concise, confident, implementation-focused.

## Rules: Do
- Use semantic tokens, not raw hex values, in component guidance.
- Every component must define states for default, hover, focus-visible, active, disabled, loading, and error.
- Component behavior should specify responsive and edge-case handling.
- Interactive components must document keyboard, pointer, and touch behavior.
- Accessibility acceptance criteria must be testable in implementation.

## Rules: Don't
- Do not allow low-contrast text or hidden focus indicators.
- Do not introduce one-off spacing or typography exceptions.
- Do not use ambiguous labels or non-descriptive actions.
- Do not ship component guidance without explicit state rules.

## Guideline Authoring Workflow
1. Restate design intent in one sentence.
2. Define foundations and semantic tokens.
3. Define component anatomy, variants, interactions, and state behavior.
4. Add accessibility acceptance criteria with pass/fail checks.
5. Add anti-patterns, migration notes, and edge-case handling.
6. End with a QA checklist.

## Required Output Structure
- Context and goals.
- Design tokens and foundations.
- Component-level rules (anatomy, variants, states, responsive behavior).
- Accessibility requirements and testable acceptance criteria.
- Content and tone standards with examples.
- Anti-patterns and prohibited implementations.
- QA checklist.

## Component Rule Expectations
- Include keyboard, pointer, and touch behavior.
- Include spacing and typography token requirements.
- Include long-content, overflow, and empty-state handling.
- Include known page component density: links (31), buttons (13), cards (12), navigation (3), lists (3), inputs (1).

- Extraction diagnostics: Audience and product surface inference confidence is low; verify generated brand context.

## Quality Gates
- Every non-negotiable rule must use "must".
- Every recommendation should use "should".
- Every accessibility rule must be testable in implementation.
- Teams should prefer system consistency over local visual exceptions.

Step 2. DESIGN.md 또는 SKILL.md 선택하기

추출 후 두 가지 출력 모드를 고를 수 있다.

모드	언제 쓰나	특징
DESIGN.md	프로젝트에 디자인 문서로 두고 싶을 때	사람이 읽기 좋은 마크다운. AI가 컨텍스트로 통째 읽는 용도
SKILL.md	Claude 같은 AI 도구의 스킬로 등록하고 싶을 때	YAML frontmatter(name, description)가 붙어 스킬 등록에 바로 쓸 수 있는 형태

처음 쓴다면 DESIGN.md로 시작하는 게 낫다.

가장 범용적이고, Claude Code / Cursor / Codex 어디에나 붙일 수 있다.

ex) skills.md 로도 추출 가능하니 확인만 해보자.

- 추출한 skills.md 원문

---
name: design-system-goddaehee-hub
description: Creates implementation-ready design-system guidance with tokens, component behavior, and accessibility standards. Use when creating or updating UI rules, component specifications, or design-system documentation.
---

<!-- TYPEUI_SH_MANAGED_START -->

# GodDaeHee Hub

## Mission
Deliver implementation-ready design-system guidance for GodDaeHee Hub that can be applied consistently across content site interfaces.

## Brand
- Product/brand: GodDaeHee Hub
- URL: https://goddaehee.co.kr/
- Audience: readers and knowledge seekers
- Product surface: content site

## Style Foundations
- Visual style: structured, accessible, implementation-first
- Main font style: `font.family.primary=Noto Sans KR`, `font.family.stack=Noto Sans KR, sans-serif, Arial, Helvetica, sans-serif`, `font.size.base=16px`, `font.weight.base=400`, `font.lineHeight.base=24px`
- Typography scale: `font.size.xs=14px`, `font.size.sm=16px`, `font.size.md=18px`, `font.size.lg=24px`, `font.size.xl=48px`
- Color palette: `color.text.primary=#171717`, `color.text.secondary=lab(35.6337 -1.58697 -10.8425)`, `color.text.tertiary=lab(7.78673 1.82345 -15.0537)`, `color.text.inverse=lab(48.0876 -2.03595 -16.5814)`, `color.surface.base=#000000`, `color.surface.muted=#ffffff`, `color.surface.raised=#6366f1`, `color.surface.strong=#f8fafc`, `color.border.muted=lab(91.7353 -0.998765 -4.76968)`
- Spacing scale: `space.1=4px`, `space.2=6px`, `space.3=8px`, `space.4=10px`, `space.5=12px`, `space.6=16px`, `space.7=20px`, `space.8=24px`
- Radius/shadow/motion tokens: `radius.xs=6px`, `radius.sm=8px`, `radius.md=32px`, `radius.lg=16777200px` | `shadow.1=rgba(0, 0, 0, 0) 0px 0px 0px 0px, rgba(0, 0, 0, 0) 0px 0px 0px 0px, rgba(0, 0, 0, 0) 0px 0px 0px 0px, rgba(0, 0, 0, 0) 0px 0px 0px 0px, rgba(0, 0, 0, 0.1) 0px 1px 3px 0px, rgba(0, 0, 0, 0.1) 0px 1px 2px -1px`, `shadow.2=rgba(0, 0, 0, 0) 0px 0px 0px 0px, rgba(0, 0, 0, 0) 0px 0px 0px 0px, rgba(0, 0, 0, 0) 0px 0px 0px 0px, rgba(0, 0, 0, 0) 0px 0px 0px 0px, oklab(0.585387 0.0253055 -0.202469 / 0.25) 0px 10px 15px -3px, oklab(0.585387 0.0253055 -0.202469 / 0.25) 0px 4px 6px -4px`, `shadow.3=rgba(0, 0, 0, 0) 0px 0px 0px 0px, rgba(0, 0, 0, 0) 0px 0px 0px 0px, rgba(0, 0, 0, 0) 0px 0px 0px 0px, rgba(0, 0, 0, 0) 0px 0px 0px 0px, oklab(0.585387 0.0253055 -0.202469 / 0.3) 0px 10px 15px -3px, oklab(0.585387 0.0253055 -0.202469 / 0.3) 0px 4px 6px -4px` | `motion.duration.instant=150ms`, `motion.duration.fast=200ms`

## Accessibility
- Target: WCAG 2.2 AA
- Keyboard-first interactions required.
- Focus-visible rules required.
- Contrast constraints required.

## Writing Tone
concise, confident, implementation-focused

## Rules: Do
- Use semantic tokens, not raw hex values in component guidance.
- Every component must define required states: default, hover, focus-visible, active, disabled, loading, error.
- Responsive behavior and edge-case handling should be specified for every component family.
- Accessibility acceptance criteria must be testable in implementation.

## Rules: Don't
- Do not allow low-contrast text or hidden focus indicators.
- Do not introduce one-off spacing or typography exceptions.
- Do not use ambiguous labels or non-descriptive actions.

## Guideline Authoring Workflow
1. Restate design intent in one sentence.
2. Define foundations and tokens.
3. Define component anatomy, variants, and interactions.
4. Add accessibility acceptance criteria.
5. Add anti-patterns and migration notes.
6. End with QA checklist.

## Required Output Structure
- Context and goals
- Design tokens and foundations
- Component-level rules (anatomy, variants, states, responsive behavior)
- Accessibility requirements and testable acceptance criteria
- Content and tone standards with examples
- Anti-patterns and prohibited implementations
- QA checklist

## Component Rule Expectations
- Include keyboard, pointer, and touch behavior.
- Include spacing and typography token requirements.
- Include long-content, overflow, and empty-state handling.

## Quality Gates
- Every non-negotiable rule must use "must".
- Every recommendation should use "should".
- Every accessibility rule must be testable in implementation.
- Prefer system consistency over local visual exceptions.

<!-- TYPEUI_SH_MANAGED_END -->

Step 3. AI 도구에 연결하기

Download 버튼으로 파일을 받아 프로젝트 루트에 놓으면 된다.

v0.3.0부터는 팝업 안에 Claude Code / Codex / Cursor용 Quick Install 버튼이 생겨서 이 단계가 더 빨라졌다.

ex)

- 원하는 프로젝트 선택

- Design.md 파일을 생성해줄 줄 알았는데

- skill을 설치해 주었다.

- 차라리 난 DESIGN.md파일로 다운로드 하여 루트 경로에 추가해 보았다.

- DESIGN.md파일을 내 프로젝트 경로에 추가

파일을 루트에 둔 뒤 AI 도구에 이렇게 지시하면 된다:

DESIGN.md 파일을 참고해서 헤더와 버튼 스타일을 맞춰줘

참고: AI 도구가 DESIGN.md를 자동으로 읽는지는 도구와 설정마다 다르다. 자동으로 안 읽힌다면 프롬프트에서 "DESIGN.md 파일 참고해서"라고 명시적으로 언급하는 게 가장 확실하다.

4. 시나리오별 활용법

Claude Code · Codex · Cursor에 물리기

가장 단순한 사용법은 다운로드한 DESIGN.md를 프로젝트 루트에 두는 것이다.

DESIGN.md 포맷 자체가 프로젝트 파일로 읽히도록 설계되어 있어, Claude Code/Cursor/Windsurf 같은 도구에서 참조하기 쉽다. 다만 실제로 자동 컨텍스트에 포함되는지는 도구와 설정에 따라 달라질 수 있다.

Google Stitch에 연결하기

manifest의 description이 직접 Google Stitch를 명시한다. 다만 이 확장이 Stitch에 직접 import되는 연동 흐름까지 보여주지는 않는다. 안전하게 말하면 DesignMD가 만든 DESIGN.md를 Stitch 중심 워크플로에서 보조 디자인 명세로 활용할 수 있다는 정도다.

TypeUI 스킬 풀과 결합

Creative Tim 블로그의 워크플로 가이드에 따르면 TypeUI CLI는 npx typeui.sh pull [slug] 명령으로 큐레이션된 스킬 파일을 프로젝트에 내려받는다. 이후 AI 에이전트가 자동으로 그 파일을 읽어 디자인 시스템을 적용한다.

Chrome 확장은 정확히 그 반대 방향이다. 기존 웹사이트에서 스킬 파일을 역방향 추출한다. 두 도구를 같이 쓰면 "큐레이션된 스타일을 받아 쓰는 풀"과 "내가 좋아하는 사이트에서 추출하는 풀"을 모두 갖게 된다.

시나리오 A: 피그마 없이 일관된 화면 만들기

1인 개발자가 SaaS 랜딩 페이지를 만든다고 하자. 디자이너가 없고 피그마도 안 쓴다. 본인이 좋아하는 레퍼런스 사이트에서 확장을 누르고 DESIGN.md를 다운받는다. 그 파일을 프로젝트 루트에 두고 Claude Code에 "이 디자인 시스템을 따라 헤더와 가격표 섹션을 만들어줘"라고 지시한다.

이때 추출 결과의 siteProfile이 productSurface: marketing, audience: business, confidence: medium으로 나오면, 마크다운의 Mission 섹션은 자동으로 "marketing surface" 기준의 가이드를 생성한다. 색상 팔레트가 5개 이상이면 시각 스타일도 "clean, functional, implementation-oriented"로 라벨링되어 들어간다.

DESIGN.md를 참고해서 헤더, 히어로 섹션, 가격표를 만들어줘. 색상과 폰트는 이 파일 기준으로 맞춰줘.

시나리오 B: 바이브 코딩 중 디자인 일관성 유지

이미 만든 사이트의 톤을 새 화면이 깨지 않게 하고 싶을 때, 본인 사이트에서 확장을 한 번 돌려 DESIGN.md를 갱신한다. 이를 Cursor의 컨텍스트에 넣어 두면, 새 화면을 만들 때 기존 토큰을 다시 쓰는 빈도가 올라간다. 이는 DESIGN.md 포맷이 명시적으로 의도하는 "에이전트가 프로젝트 루트에서 직접 읽는다" 시나리오와 일치한다.

DESIGN.md의 color.text.primary와 spacing 토큰을 기준으로 새 대시보드 카드 컴포넌트 만들어줘.

시나리오 C: SKILL.md로 에이전트 큐 만들기

DESIGN.md 모드 대신 SKILL.md 모드로 출력하면 frontmatter의 name, description이 스킬 등록용 메타데이터로 쓰일 수 있다. Claude 같은 도구의 스킬 시스템에 맞게 배치해두면, 같은 디자인 명세를 여러 프로젝트에서 재사용 가능한 스킬로 관리하기 쉬워진다.

SKILL.md에 정의된 디자인 시스템을 기반으로 신규 프로젝트의 버튼, 카드, 네비게이션 컴포넌트를 생성해줘.

5. 이것만 알고 쓰자 (주의사항)

CSS 변수 원본은 못 가져온다

이 확장은 브라우저가 최종적으로 계산한 값(hex 색상, px 단위)만 읽는다. 원본 디자인 시스템이 --color-primary: #3b82f6처럼 변수로 정의되어 있어도, 추출 결과에는 그냥 color.text.primary: #3b82f6으로 나온다. 시각적 외형을 따라가기엔 충분하지만, 원본 토큰 구조 그대로를 복원하지는 못한다.

늦게 그려지는 요소는 직접 띄우고 Refresh

SPA 라우터로 늦게 그려지거나, 모달처럼 처음엔 숨겨진 요소는 추출 시점에 잡히지 않는다. 원하는 화면 상태를 먼저 만들어 두고 팝업의 Refresh를 다시 누르면 된다.

결과물은 출발점이지 정답이 아니다

공식 문서 어디에도 "정확도 N%"라는 수치는 없다. 나도 직접 확인하지 못했다. 추출 결과를 바로 운영에 투입하기보다는, 한 번 훑어보고 필요한 부분을 손봐서 쓰는 게 안전하다.

6. 트러블슈팅 Q&A

Q1. 추출 결과가 거의 비어 있다

isVisible() 검증이 모든 요소를 걸러냈을 가능성이 높다. SPA에서 첫 화면이 비어 있는 상태로 추출됐거나, display:none 요소가 많은 페이지가 그렇다. 화면을 충분히 그린 뒤 팝업의 Refresh를 다시 누르고, 모달이 들어간 디자인이라면 모달을 띄운 채로 다시 추출한다.

Q2. 폰트가 시스템 기본 폰트로 잘못 잡힌다

사용자 컴퓨터에 해당 웹폰트가 설치돼 있지 않으면 시스템 폴백 폰트가 computed style에 잡힌다. v0.3.0에서 폰트 패밀리 추출 로직이 보강되었지만, 근본 한계는 computed 기반이라는 점이다. mainFontStyle.familyStack을 확인하면 폴백 체인 전체가 들어가 있는지 점검할 수 있다.

Q3. 특정 사이트에서 확장이 동작하지 않는다

service-worker가 chrome:// URL에서의 추출을 차단한다. 확장 페이지, 크롬 설정 페이지, 일부 내부 페이지에서는 의도적으로 동작하지 않는다. 또 activeTab 권한 모델 때문에 백그라운드 탭에서는 동작하지 않으니, 추출하려는 탭을 활성 상태로 두고 아이콘을 눌러야 한다.

Q4. siteProfile의 confidence가 항상 low로 나온다

score >= 5 AND gap >= 1.4라는 high 임계값이 까다롭기 때문이다. 1·2위 점수 격차가 좁은 페이지(예: 마케팅과 SaaS가 섞인 메인 페이지)에서는 medium 이하가 자연스럽다. confidence가 low여도 productSurface/audience 1위 라벨은 계속 채워지므로, 그 라벨을 참고하되 너무 단정적으로 해석하지 않는 정도로 사용하면 된다.

Q5. Manifest V3 배경 워커 종료 후 동작이 끊긴다

MV3 service-worker는 idle 상태에서 종료된다. 다행히 이 확장의 통신은 사용자 클릭 → RUN_EXTRACTION 메시지 단발성이라 종료가 큰 문제가 되지 않는다. 다만 팝업을 닫지 말고 결과 다운로드까지 마치는 편이 안전하다.

7. 결론: 언제 쓰고, 언제 쓰지 않는가

DesignMD Style Extractor는 v0.1.0(2026-04-15)부터 v0.4.0(2026-04-17)까지 사흘에 걸쳐 네 번 릴리스된 프로젝트다.

v0.2.0에서는 보안 면에서 tabs 권한이 제거됐고, v0.3.0에서는 Quick Install 버튼과 폰트 추출이 보강됐으며, v0.4.0에서는 에셋 폴더 재구성과 manifest 정보 업데이트가 이루어졌다.

짧은 출시 사이클과 작은 배포 크기가 보여주는 것은 범위가 비교적 좁다는 점이다. 여러 문제를 한꺼번에 풀기보다, 기존 페이지의 스타일을 추출해 DESIGN.md/SKILL.md로 만드는 한 가지 흐름에 집중한 47.06 KiB짜리 단일 목적 확장에 가깝다.

도입 결정 매트릭스

상황	권장 여부	이유
디자이너 없는 1인 개발자가 레퍼런스 톤을 따라가고 싶다	적합	클릭 1회로 시작점 확보
Claude Code/Cursor/Stitch로 바이브 코딩 중이다	적합	manifest가 명시적으로 이들과의 연동을 가정
정확한 디자인 토큰 원본을 그대로 가져와야 한다	비적합	computed 값만 수집, CSS 변수 원본은 손실
동적 렌더링이 많은 SPA에서 한 번에 모든 화면을 추출	비적합	로드 시점 가시 요소만 표본
결과물을 그대로 운영에 바로 투입한다	비적합	정확도 보장 없음, 검수 단계 필요

DesignMD가 정확히 노린 자리는 "AI에게 넘길 디자인 명세를 누가 만드는가"라는 upstream 공백이다. 디자이너가 있고 토큰 시스템이 정착된 팀에는 보조 도구지만, 그렇지 않은 1인 개발자·바이브 코더에게는 빠진 단계 하나를 메우는 47.06 KiB짜리 다리다.

참고자료

OpenAI Privacy Filter 사용방법 : 내 서버 로그를 ChatGPT에 분석 맡기기 전에 — OpenAI Privacy Filter로 1초 마스킹

갓대희 — Sun, 3 May 2026 23:49:56 +0900

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

예를 들어 로그 파일을 그대로 LLM이나 외부 분석 도구에 넘기면 사용자 이메일, 임시 비밀번호, API 키가 같이 흘러갈 수 있다. 보내기 전에 한 번 닦아 내고 싶은데, 정규식만으로는 "갓대희는 1990-01-02에 태어났다" 같은 자연어 속 PII를 안정적으로 잡기 어렵다. 그렇다고 클라우드 PII 서비스에 원문을 보내면, 그 자체가 또 다른 유출 경로가 된다.

OpenAI가 2026년 4월 22일에 Privacy Filter를 공개했다.

텍스트 속 개인정보를 감지하고 마스킹하는 무료 공개 AI 모델(open-weight)이다.

노트북에서도 돌아갈 만큼 가볍고, Apache 2.0 라이선스라 상업적 용도에도 쓸 수 있다. 무엇보다 로컬에서 돌린다 — 원문이 외부로 나가지 않는다.

이번 글은 Privacy Filter를 내 프로젝트·문서·로그에 어떻게 실제로 쓸 수 있는지를 중심으로 정리한다.

Privacy Filter는 무엇이고, 왜 지금 주목하는가
설치 및 시작하기 (macOS venv 오류 해결 · 첫 실행 모델 다운로드 포함)
내 프로젝트에서 쓰는 4가지 패턴
복사해서 바로 쓰는 명령어 모음
성능 및 벤치마크 — 무엇을 믿고, 무엇을 직접 재라
제한사항 및 주의사항
트러블슈팅 Q&A
결론 — 도입 결정 매트릭스

한 장으로 보는 Privacy Filter 위치

1. 원문 입력

로그, 문서, PR diff, 상담 기록

→

2. 로컬 Privacy Filter

8개 PII 카테고리 감지, 로컬 실행

→

3. 마스킹 결과

<PRIVATE_EMAIL>, <SECRET> 등으로 치환

→

4. 다음 단계

LLM, RAG 인덱스, 분석 SaaS, 내부 공유

검증 1 모델 다운로드 이후 런타임 egress 차단

검증 2 앱 로그·APM·오류 리포트에 원문 저장 금지

검증 3 한국 고유 식별자는 정규식/룰과 병행

1. Privacy Filter는 무엇이고, 왜 지금 주목하는가

이 글은 누구를 위한 글인가

로그·문서·코드를 LLM에 넘기기 전에 개인정보를 지우고 싶은 개발자
클라우드 PII API 없이 로컬에서 처리하고 싶은 팀
Privacy Filter가 뭔지는 알겠는데 "내 프로젝트에 어떻게 쓰지?"가 막히는 분

Privacy Filter는 자연어 텍스트에서 개인정보(PII)를 감지하고 마스킹하기 위한 무료 공개 AI 모델(open-weight)이다.

OpenAI는 이 모델을 "텍스트가 저장되거나 공유되거나 다음 단계로 넘기기 전에 민감 정보를 식별하고 마스킹하도록 설계됐다"고 정의한다.

먼저 봐야 할 건 로컬 실행이다. 한국어 공식 발표문은 "로컬 환경에서 실행이 가능하여 데이터를 외부로 내보내지 않고도 개인 식별 정보를 마스킹하거나 비식별화할 수 있습니다"라고 설명한다. 원문을 외부로 보내기 전에 사내 장비에서 마스킹하고, 그 결과만 다음 단계로 넘기는 구성을 염두에 둔 모델이다.

또 하나는 개방형 가중치 + Apache 2.0 라이선스다. 공식 문서는 실험, 커스터마이징, 상업적 배포에 쓸 수 있는 라이선스라고 안내한다. 사내 로그 정제 도구나 제품 기능에 붙일 때 라이선스 부담이 비교적 작다.

1-1. vs 대안 비교표

한국 개발 현장에서 PII 마스킹을 검토하는 팀이 가장 많이 비교하는 대안은 Microsoft Presidio와 Amazon Comprehend다. The New Stack의 분석을 정리하면 다음과 같다.

비교 전제: 2026-04-28 기준, OpenAI Privacy Filter 초기 공개 버전(2026-04-22 릴리스). 아래 표는 OpenAI의 공식 비교표가 아니라 The New Stack 분석과 각 도구의 공개 정보를 바탕으로 정리한 운영 관점 요약이다.

항목	OpenAI Privacy Filter	Microsoft Presidio	Amazon Comprehend
접근 방식	AI 모델 (end-to-end transformer)	규칙 + NER 기반	관리형 클라우드 NLP
실행 위치	로컬(GPU/CPU/WebGPU)	로컬·온프레미스	AWS 클라우드
라이선스	Apache 2.0	MIT	상용 (사용량 과금)
강점	자연어 글, 맥락 의존 PII	정규 패턴(IBAN, 이메일)	AWS 통합, 운영 편의
약점	고정 라벨 체계, 비영어·비라틴 성능 저하 가능	모호한 이름·복잡 맥락 한계	클라우드 의존
다국어 성숙도	주로 영어, 선택적 다국어 평가 보고	기본은 영어, 모델·recognizer 확장으로 다국어	PII 감지는 영어·스페인어 지원
멀티모달·구조화 연계	미지원	별도 연계 필요	AWS 내 다른 서비스와 연계

자연어 글에서 강하고, Presidio는 패턴이 뚜렷한 데이터에 더 편하다. 공식 문서를 보면 Presidio 기본 설정은 영어 중심이고, Amazon Comprehend의 PII 지원 언어도 제한적이다. 한국어 운영에서는 '다국어 지원'이라는 큰 표현보다, 실제 한국어 샘플로 재현율을 직접 재는 게 맞다.

Privacy Filter가 잡는 8가지 카테고리: 이름(private_person) · 주소(private_address) · 이메일(private_email) · 전화번호(private_phone) · URL(private_url) · 날짜(private_date) · 계정번호(account_number) · 비밀번호·API 키(secret). (출처: GitHub README)

한 줄 정리: 로컬 실행 + Apache 2.0 + 8개 PII 카테고리. 핵심은 "원문이 외부로 나가지 않는다"는 점이다.

2. 설치 및 시작하기

저장소를 체크아웃한 뒤 PoC를 띄우는 과정은 단순한 편이다.

git clone https://github.com/openai/privacy-filter.git
cd privacy-filter
pip install -e .

2-1. macOS에서 pip 오류가 나는 경우 — venv로 해결

macOS + Homebrew Python 조합인 경우 위 pip 명령이 막혔다.

error: externally-managed-environment

× This environment is externally managed
╰─> To install Python packages system-wide, try brew install xyz,
    where xyz is the package you are trying to install.

    If you wish to install a Python library that isn't in Homebrew,
    use a virtual environment:

    python3 -m venv path/to/venv
    source path/to/venv/bin/activate
    python3 -m pip install xyz

원인은 PEP 668이다. Homebrew가 관리하는 Python은 시스템 환경을 보호하기 위해 pip의 전역 설치를 차단한다.

venv(가상환경)를 만들어 그 안에 설치하면 된다.

python3 -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
pip install -e .

# Successfully installed opf-0.1.0 torch-2.11.0 huggingface_hub-1.13.0 ...

터미널을 새로 열 때마다 source .venv/bin/activate를 한 번 실행해야 opf를 쓸 수 있다.

앞으로도 Python 패키지를 쓸 때는 프로젝트별 venv를 만드는 패턴이 안전하다.

2-2. 실행 — 모델 자동 다운로드 (~2.8GB)

설치 후 처음 opf를 실행하면 모델 가중치를 HuggingFace에서 ~/.opf/privacy_filter/에 내려받는다.

약 2.8GB라 회선 속도에 따라 수 분이 걸린다.

Mac(Apple Silicon 포함)에서는 CUDA가 없어 --device cpu 플래그를 붙여야 한다.

생략하면 AssertionError: Torch not compiled with CUDA enabled 오류가 난다.

# Mac은 반드시 --device cpu
$ opf --device cpu "Alice was born on 1990-01-02."

Default OPF checkpoint not found at /Users/gdh/.opf/privacy_filter.
Downloading from HuggingFace repo 'openai/privacy-filter' to /Users/gdh/.opf/privacy_filter.
Fetching 4 files:   0%|          | 0/4 [00:00<?, ?it/s]
Downloading (incomplete total...): 0%|     | 5.19k/2.80G [00:01<...
Fetching 4 files: 100%|██████████| 4/4 [완료]

Alice was born on <PRIVATE_DATE>.

실제 결과를 보면 날짜 "1990-01-02"는 <PRIVATE_DATE>로 잡혔지만, 이름 "Alice"는 마스킹되지 않았다. 단순한 영어 이름 하나만 있는 짧은 문장에서는 모델이 private_person으로 분류하지 않는 경우가 있다.

더 많은 맥락(성·이메일·주소가 함께 있는 문장 등)이 붙으면 잡히는 경우가 다르다. "6장 제한사항"에서 다루고 있다.

이후 실행부터는 저장된 가중치를 바로 써서 즉시 시작된다. HuggingFace 계정이 있다면 환경변수를 설정해 두면 속도 제한 없이 다운로드할 수 있다.

export HF_TOKEN=hf_xxxxxxxxxxxxxxxx   # HuggingFace 계정에서 발급
opf --device cpu "Alice was born on 1990-01-02."

설치가 끝나면 opf CLI가 활성화된다. GitHub README가 보여 주는 가장 흔한 호출 패턴 네 가지는 이렇다.

opf "Alice was born on 1990-01-02."
opf --device cpu "Alice was born on 1990-01-02."
opf -f /path/to/file
cat /path/to/file | grep pattern | opf

문자열을 인자로 직접 넘기는 방식, CPU 강제 실행, 파일 입력, Unix 파이프 입력까지 한 번에 지원한다. opf는 마스킹용 redact, 평가용 eval, 파인튜닝용 train 세 가지 서브커맨드를 제공해 운영·평가·재학습 흐름을 한 바이너리에서 처리하도록 설계됐다. 기존 셸 도구에 끼워 넣기 좋은 형태다.

2-3. 최소 요구 사양

공식 문서는 1.5B 총 파라미터와 50M 활성 파라미터, 브라우저 또는 노트북 실행 가능성을 밝히지만, 하드웨어별 고정 VRAM 요구량이나 토큰/초 처리량을 보장하지는 않는다. 메모리와 속도는 디바이스, 정밀도, 입력 길이, 배치 방식에 따라 달라진다.

따라서 도입 판단은 직접 재는 쪽이 맞다. 샘플 로그 100MB, 위키 문서 1,000건, PR diff 100건처럼 실제 입력에 가까운 묶음을 만들고 CPU, GPU, WebGPU 환경에서 처리량과 누락률을 따로 측정해야 한다.

설치만 보면 가벼운 사이드 도구처럼 느껴지지만, 운영 단계에서는 입력 크기와 지연시간 목표가 먼저다. 하드웨어 사양은 그다음에 정해야 한다.

한 줄 정리: git clone → venv → pip install → opf --device cpu. Mac이면 --device cpu 빠뜨리지 말 것. 첫 실행 시 ~2.8GB 모델 다운로드.

3. 내 프로젝트에서 쓰는 4가지 패턴

설치가 됐으니, 이제 실제로 어디에 끼워 넣을 수 있는지 패턴별로 보자. 각 패턴은 "상황 → 명령어 → 결과 → 응용" 순서로 정리했다.

패턴 1. 노션·옵시디언 노트 → LLM 붙여넣기 전에 닦기

상황: 고객 미팅 회의록, 지원 티켓, 개인 메모에 이름·이메일·전화번호가 담겨 있다. 이걸 그대로 ChatGPT·Claude에 붙여넣으면 원문이 외부 서버로 올라간다.

# Mac: 클립보드 텍스트를 마스킹해서 다시 클립보드로
pbpaste | opf --device cpu | pbcopy

결과: "갓대희(goddaehee@example.com)와 2시에 미팅" → "갓대희(<PRIVATE_EMAIL>)와 2시에 미팅"이 클립보드에 들어간다. 붙여넣기만 하면 된다.

응용: Linux는 xclip -out | opf --device cpu | xclip -in, Windows PowerShell은 Get-Clipboard | opf --device cpu | Set-Clipboard.

패턴 2. 로그 파일을 AI 분석에 넘기기 전에 마스킹

상황: 서버 에러 로그를 AI에 던져 원인 분석을 받고 싶은데, 로그 안에 고객 이메일·임시 비밀번호·API 토큰이 섞여 있다.

opf --device cpu -f server.log > server.masked.log

결과: server.masked.log에는 PII만 <PRIVATE_EMAIL>, <SECRET> 태그로 교체된 로그 구조가 그대로 남는다. 이 파일을 ChatGPT·Claude에 첨부하거나 붙여넣으면 된다.

응용: 마스킹된 파일만 외부에 공유하고 원본은 사내망에 보관. S3·GCS 업로드 전 필터링 파이프라인에도 그대로 끼울 수 있다.

패턴 3. Git 커밋 전 — 비밀번호·API 키 자동 검사

상황: 테스트 코드에 박아 둔 임시 비밀번호, 실수로 들어간 개인 이메일, 하드코딩된 API 키. 커밋 전에 잡는 게 낫다.

[WARNING] Privacy Filter는 PII 감지 모델이다. secret 카테고리(비밀번호·API 키)가 있지만, 시크릿 전용 도구(gitleaks, trufflehog)와 보완적으로 쓰는 것이 원칙이다. 공식 모델 카드 기준 secret의 span F1은 0.624로, 다른 PII 카테고리에 비해 낮다. pre-commit 체인에 함께 넣는 구성을 권장한다.

#!/bin/sh
# .git/hooks/pre-commit 에 저장 후 chmod +x .git/hooks/pre-commit

CHANGED=$(git diff --cached --name-only | grep -E '\.(py|js|ts|jsx|tsx)$')
[ -z "$CHANGED" ] && exit 0

RESULT=$(git diff --cached -- $CHANGED | opf --device cpu)
if echo "$RESULT" | grep -q "<SECRET>"; then
  echo "[privacy-filter] <SECRET> 감지. 커밋 전 확인하세요."
  exit 1
fi

결과: <SECRET> 태그가 나오면 커밋이 중단된다.

응용: pre-commit 프레임워크를 쓴다면 .pre-commit-config.yaml에 local 훅으로 추가할 수 있다.

패턴 4. 브라우저에서 바로 — 코드 없이

상황: 설치 없이, 코드 없이 빠르게 동작을 확인하거나 한 번만 쓰고 싶을 때.

OpenAI 공식 Hugging Face Space에 접속해 텍스트를 붙여넣으면 끝이다. 비개발자에게 동작을 보여줄 때도 유용하다.

[WARNING] 공개 데모다. 실제 고객 이메일, API 키, 내부 기밀이 담긴 텍스트는 절대 올리지 말 것. 동작 확인은 가짜 샘플 텍스트로 한다.

- 아쉬운점은 한글 인식을 아직 잘 하지 못하는 것으로 보인다. ㅠㅠ 영문으로 테스트하여 결과 공유

> 훨씬 필터 적용이 잘 되는것을 볼 수 있다.

한 줄 정리: 클립보드(패턴 1) → 로그 파일(패턴 2) → pre-commit 훅(패턴 3) → 브라우저 데모(패턴 4). 일상 업무에서 접하는 대부분의 시나리오를 커버한다.

4. 복사해서 바로 쓰는 명령어 모음

전제: venv 활성화 상태, Mac이라면 모든 명령에 --device cpu 필수.

CLI 명령어

# 한 문장 인라인
opf --device cpu "안녕하세요, alice@example.com 입니다."

# 파일 마스킹
opf --device cpu -f mylog.txt > mylog.masked.txt

# 디렉토리 일괄 (bash)
for f in logs/*.log; do
  opf --device cpu -f "$f" > "${f%.log}.masked.log"
done

# 파이프 — 실시간 로그 마지막 100줄
tail -100 server.log | opf --device cpu

# Mac 클립보드 원스텝
pbpaste | opf --device cpu | pbcopy

Python 호출 (3줄)

import opf

text = open("mylog.txt").read()
print(opf.redact(text))

opf.redact(text)는 기본 로컬 모델로 마스킹한 문자열을 반환한다. (출처: opf/__init__.py)

파이프와 파일 모드 모두 venv 안에서 opf가 실행되어야 한다. 터미널을 새로 열었다면 source .venv/bin/activate부터 확인하자.

한 줄 정리: 위 명령어들은 모두 로컬에서 돌기 때문에 원문이 외부로 나가지 않는다. Mac에서는 --device cpu를 빠뜨리지 말 것.

5. 성능 및 벤치마크 — 무엇을 믿고, 무엇을 직접 재라

OpenAI가 공개한 공식 모델 카드 PDF §7.4.1 Table 1은 두 가지 데이터셋(PII-Masking-300k, CredData)에서 측정한 1차 수치를 다음과 같이 제시한다.

데이터셋 / 버전	Precision	Recall	F1 (token)	F1 (span)
PII-Masking-300k (baseline)	0.940	0.980	0.960	0.926
PII-Masking-300k (corrected)	0.968	0.981	0.974	0.942
CredData (secret, baseline)	0.747	0.965	0.842	0.617
CredData (secret, corrected)	0.750	0.965	0.844	0.624

PII-Masking-300k의 baseline과 corrected는 동일 데이터셋의 주석 오류 수정 전·후를 의미한다. CredData는 비밀번호·API 키 같은 secret 카테고리 전용 벤치마크로, Precision이 0.747까지 떨어지는 만큼 거짓양성(과도한 마스킹) 비용이 다른 카테고리보다 크다.

The New Stack도 같은 PII-Masking-300k 수치를 인용하지만, 1차 출처는 모델 카드다. 운영 환경에서는 자체 데이터로 한 번 더 측정해 도메인 차이를 확인하는 편이 안전하다.

파인튜닝 효율도 눈여겨볼 만하다. OpenAI 공식 발표는 도메인 적응 벤치마크에서 소량의 데이터로 F1이 54%에서 96%까지 개선됐다고 설명한다. opf train /path/to/train.jsonl --output-dir /path/to/finetuned_checkpoint 명령으로 자체 도메인에 맞춰 적응시키는 흐름도 제공된다.

다국어 평가는 한 줄로 오해하면 안 된다. 모델 카드는 PII-Masking-300K의 유럽어권 언어별 결과와 별도로, 확장 synthetic multilingual 평가에서 한국어 962개 예시에 대해 Recall 0.887, Precision 0.903, F1 0.895를 보고한다. 다만 synthetic 평가이므로 한국 기업 로그, 고객 상담, 사내 위키에서 같은 수치가 나온다는 뜻은 아니다.

여기서 중요한 건 "공식 벤치마크 96%"가 아니라 "우리 데이터에서 몇 %가 나오느냐"다. 한국어 도메인, 사내 약어, 주민등록번호·사업자번호 같은 로컬 패턴이 많다면 자체 라벨 데이터로 짧게라도 재평가해야 한다.

6. 제한사항 및 주의사항

수치만 보고 "이걸로 끝"이라 결론 짓기엔 이르다.

공식 한계는 꽤 분명하다. Privacy Filter는 고정된 라벨 체계와 학습 분포 안에서 동작한다. Hugging Face 모델 카드는 비영어 텍스트, 비라틴 문자, 지역별 이름 관습, 학습 분포 밖 도메인에서 성능이 떨어질 수 있다고 경고한다.

한국 환경에서 직접적인 함의는 두 가지다. 첫째, 주민등록번호·사업자등록번호처럼 국내 고유 식별자는 별도 정규식 검사를 병행해야 한다. 둘째, 모델 카드가 한국어 synthetic 평가를 보고하더라도 실제 한국어 이름·주소·사내 약어·문서 양식은 별도 분포이므로 자체 샘플로 재현율을 확인해야 한다.

Hugging Face 모델 카드는 더 강한 경고를 적는다.

"Over-reliance 위험: 익명화, 컴플라이언스, 또는 보안 보장이 아님. 포괄적 개인정보 보호 접근법의 일부로만 사용 권장. 고위험 배포: 의료, 법률, 금융, HR, 교육, 정부 워크플로우에서 신중히 사용. 거짓음성(정보 노출), 거짓양성(문맥 제거) 모두 비용이 높음."

이 모델 자체가 "익명화 도구"라고 부를 수 없다는 입장을 OpenAI가 직접 밝힌다. 더 광범위한 프라이버시 설계의 한 구성요소로 두고, 의료·법률·금융 분야에서는 인간 검토를 반드시 병행해야 한다.

또 하나 놓치기 쉬운 점이 있다. 이름을 가려도 문맥만으로 사람을 다시 식별할 수 있는 경우가 있다. "[PRIVATE_PERSON]이 우리 회사 대표다" 같은 문장은 이름을 지워도 조직 내부에서는 거의 답이 보일 수 있다. 결정론적 식별자는 정규식으로, 맥락 의존적인 자연어 PII는 Privacy Filter로, 재식별 위험은 정책과 사람 검토로 나눠 보는 편이 현실적이다.

7. 트러블슈팅 Q&A

Q0. Mac에서 `AssertionError: Torch not compiled with CUDA enabled` 오류

CUDA는 NVIDIA GPU 전용이다. Mac(Intel·Apple Silicon 모두)에는 CUDA가 없으므로 이 오류가 난다. --device cpu 플래그를 붙이면 해결된다.

# 오류 나는 명령
opf "Alice was born on 1990-01-02."
# → AssertionError: Torch not compiled with CUDA enabled

# Mac 해결
opf --device cpu "Alice was born on 1990-01-02."
# → Alice was born on <PRIVATE_DATE>.

Apple Silicon(M1/M2/M3/M4)은 MPS 백엔드를 쓸 수도 있지만, 현재 공식 문서가 명시하는 Mac 지원 방식은 CPU다.

Q1. 설치는 됐는데 GPU에서 너무 느리다

공식 문서가 하드웨어별 처리량을 보장하지 않으므로 먼저 입력 길이를 줄여 기준치를 잡는 게 낫다. 같은 파일을 opf --device cpu, GPU 단일 점유 상태, 배치 크기 변경 조건으로 각각 재고, 모델 다운로드·초기 로딩 시간과 순수 추론 시간을 분리해서 봐야 한다.

Q2. 한국어 이름·주소가 자주 누락된다 (오탐/미탐)

모델은 비영어·비라틴 문자에서 성능 저하 가능성이 보고된 모델이다. 두 가지 경로가 있다.

자체 한국어 라벨 데이터로 opf train을 통해 파인튜닝하거나 운영 포인트를 조정한다.
결정론적 패턴(주민번호, 사업자번호 등)은 정규식 사전 필터로 분리한다.

최소한 다음 샘플은 직접 넣어 봐야 한다. 주민등록번호 형식, 휴대전화 표기 변형(010-1234-5678/010 1234 5678), 사업자등록번호, 한글 이름+도로명 주소 혼합 문장, 사내 계정번호처럼 보이는 임의 숫자열이다.

Q3. 커스텀 카테고리를 추가하고 싶다

공식 파인튜닝 가이드는 opf train --label-space-json /path/to/custom_label_space.json 경로를 제공한다. span_class_names에 새 카테고리를 정의하고 그 라벨로 학습하는 방식이다. 새 카테고리 하나를 추가하면 내부적으로 경계 태그(시작·중간·끝·단독) 4개 클래스가 생성된다.

Q4. 정말 외부로 데이터가 나가지 않는가

공식 발표가 보장하는 것은 "로컬에서 실행 가능하다"는 점이다. 실제 운영에서 외부 호출이 없는지는 배포자가 검증해야 한다. 모델 다운로드 단계의 외부 통신, 런타임 egress 차단, 임시파일·애플리케이션 로그 보존 여부, APM/오류 리포팅 도구 전송 여부를 같이 확인해야 한다.

8. 결론 — 도입 결정 매트릭스

Privacy Filter를 어디에 쓰고 어디에 쓰지 않을지를 한 표로 정리한다.

상황	권장
자연어 글(로그·문서·코드 리뷰) PII 마스킹	Privacy Filter 단독 또는 정규식과 병행
한국어·한국 고유 식별자(주민번호 등) 중심	정규식 + Privacy Filter, 가능하면 자체 파인튜닝
정규 패턴이 강한 폼 데이터(IBAN·이메일)	Microsoft Presidio가 더 자연스러움
AWS 의존 환경, 영어·스페인어 텍스트, 운영 부담 최소화	Amazon Comprehend 등 관리형 서비스
의료·법률·금융 등 고위험 도메인	모델 단독 사용 금지, 인간 검토 필수
클라우드 의존을 피하고 싶음	Privacy Filter 로컬 운영, egress 차단과 로그 정책 병행

자연어 텍스트 PII와 온프레미스 운영이 필요한 환경에는 Privacy Filter가, 정규 패턴 기반 데이터에는 Presidio가 더 자연스러운 선택이다. AWS 의존도가 높고 Comprehend PII의 지원 언어가 맞는 경우에는 관리형 서비스가 운영 부담을 줄일 수 있다.

8-1. 도입 플레이북

오늘: 개인 PC에서 git clone → pip install -e . → opf --device cpu -f sample.log로 8개 카테고리 동작을 확인한다.
이번 주: PII-Masking-300k 외에, 자체 데이터 100~300건에 라벨을 달아 정밀도/재현율을 측정한다. 동시에 한국 고유 식별자 정규식 룰을 정리한다.
운영 반영: 내부 서비스로 Privacy Filter를 띄우고, LLM 호출 직전 단계에 게이트로 끼운다. CI에는 secret 카테고리 검출 시 머지 차단 룰을 추가한다.

Privacy Filter는 PII 문제를 끝내 주는 도구가 아니라, PII 파이프라인을 처음부터 다시 설계할 때 쓸 수 있는 부품이다. 노트북에서도 돌아가는 가벼운 모델을 사내망에서 쓸 수 있다는 건 분명히 가치 있다. 단, 한국어·국내 식별자·고위험 도메인에서는 별도 평가와 정책 검토를 빠뜨리면 안 된다.

GitHub 저장소는 openai/privacy-filter에서 받을 수 있다. 바로 운영에 넣기보다, 한국 환경에 맞는 라벨링 샘플과 정규식 보강을 먼저 준비하는 쪽이 낫다.

참고 자료

Codex CLI /goal 사용방법 : 목표를 기억하고 스스로 이어가는 자율 루프 - /goal과 Ralph Loop 비교

갓대희 — Sun, 3 May 2026 18:27:15 +0900

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

/goal은 Codex CLI 신규버전 (0.128.0 : 2026-04-30) 업데이트의 핵심 기능 중 하나는 슬래시 커맨드 이다. 목표를 한 번 입력해 두면, AI가 할 일이 없어지는 순간마다 "계속 진행해"라는 신호를 스스로 받아 작업을 이어가는 구조다.

한국 개발자 사이에서도 반응이 빠르게 갈렸다. 어떤 사람은 "드디어 ralph loop가 Codex CLI에 들어왔다"고 환영했고, 어떤 사람은 "장시간 돌아가는 자율 모드가 비용 폭탄 아니냐"고 걱정했다. 마침 OpenAI의 Felipe Coury가 원문 트윗에서 "Our take on the Ralph loop"라고 표현하기도 했으니, 두 진영 모두 어느 정도 일리가 있다.

/goal — 자율 루프 한 줄 요약
설정 — config.toml 한 줄과 명시적 활성화
/goal 사용법 — 네 개의 명령어로 끝나는 인터페이스
내부 동작 — 모델 툴, continuation 템플릿, 안전장치
Claude ralph loop와의 비교 — 같은 철학, 다른 구조
토큰 소모 후 동작 — 확인된 것과 확인되지 않은 것
실전 활용 팁
결정 매트릭스 — 언제 쓰고, 언제 쓰지 않는가
마무리

이 글 한 줄 요약

Codex CLI 0.128.0에 새로 추가된 /goal 기능의 소스코드 기반 동작 분석, Claude oh-my-claudecode ralph loop와의 비교, 안전한 실전 운용 가이드를 담는다.

1. /goal — 자율 루프 한 줄 요약

한 줄로 정리하면, /goal은 "대화 세션이 끊겨도 목표는 사라지지 않고, 모델이 쉬고 있는 틈마다 '계속 진행해' 신호를 받아 작업을 이어가는 루프"다. 여기서 핵심은 목표가 대화를 넘어 유지된다는 점이다. 다음 턴에 사용자 입력이 없으면 시스템이 알아서 모델을 다시 깨워 작업을 이어가게 한다.

2. 설정 — config.toml 한 줄과 명시적 활성화

/goal은 기본으로 켜져 있는 기능이 아니다.

- 나의 경우도 /goal 을 그냥 사용해보려고 했는데 동작하지 않았다.

0.128.0 버전 기준으로 OpenAI의 기능 성숙도 구분 상 Experimental(실험적)보다도 앞 단계인 UnderDevelopment(개발 중)로 분류되어 있다. Codex의 features 모듈 소스를 보면 다음과 같이 나온다.

FeatureSpec {
    id: Feature::Goals,
    key: "goals",
    stage: Stage::UnderDevelopment,
    default_enabled: false,
}

default_enabled: false가 의도적으로 들어가 있다.

공식 Feature Maturity 문서는 Under development를 "아직 사용할 준비가 안 된" 단계로 설명한다.

즉, "공개 실험 기능"이 아니라 코드와 릴리즈 노트가 먼저 들어간 개발 중인 기능으로 보는 게 맞다.

/goal 기능을 킬려면 공식 config 가이드에 나오는 [features] 섹션에 한 줄 추가하면 된다.

config.toml에 다음 내용을 추가하면 된다.

[features]
goals = true

ex) 활성화 후 /goal 확인

3. /goal 사용법 — 네 개의 명령어로 끝나는 인터페이스

사용자 인터페이스는 의외로 단순하다.

slash_dispatch.rs의 GOAL_USAGE 상수가 사실상 모든 사용법을 압축해서 보여 준다.

const GOAL_USAGE: &str = "Usage: /goal <objective>";
const GOAL_USAGE_HINT: &str = "Example: /goal improve benchmark coverage";

match trimmed.to_ascii_lowercase().as_str() {
    "clear"  => Some(GoalControlCommand::Clear),
    "pause"  => Some(GoalControlCommand::SetStatus(AppThreadGoalStatus::Paused)),
    "resume" => Some(GoalControlCommand::SetStatus(AppThreadGoalStatus::Active)),
    _ => None,
}

정리하면 네 개의 형태가 있다.

명령	동작
`/goal <목표>`	새 목표를 생성하고 자율 루프를 시작한다
`/goal pause`	현재 활성 목표를 paused 상태로 전환한다
`/goal resume`	paused 목표를 active로 되돌린다
`/goal clear`	현재 목표를 제거한다

인자 없이 빈 /goal 만 실행하면 현재 목표 상태를 표시하는데, 목표가 설정되어 있으면 내용을 보여주고 없으면 No goal is currently set. 라고 출력한다.

요약하자면, /goal은 "새 목표 입력 + 라이프사이클 제어 3종"으로 디자인되어 있고, 사용자가 외울 단어는 pause/resume/clear 세 개뿐이다.

검증 메모: 0.128.0의 TUI /goal <objective> 경로는 objective 문자열만 넘긴다. token_budget 필드는 코어와 모델 툴에는 존재하지만, 이 슬래시 커맨드에 별도 예산 인자 문법이 노출된 것은 확인되지 않는다.
따라서 예산 이야기는 "지원되는 표면에서는 가능"으로 표현해야 한다.

4. 내부 동작 — 모델 툴, continuation 템플릿, 안전장치

표면 인터페이스는 단순하지만, 내부에는 모델 자율성과 사용자 통제를 분리한 설계가 깔려 있다. 핵심 구성 요소는 세 가지다.

/goal 런타임 흐름 한눈에 보기

1. 사용자가 목표 설정
/goal <objective>

→

2. Thread goal 저장
active / paused / complete

→

3. idle 조건 확인
진행 중 턴, 대기 입력, plan mode 제외

→

4. continuation 주입
목표, 시간, 토큰 사용량 포함

→

5. 다음 행동 실행
완료 시 모델이 complete 처리

연속 continuation에서 tool call이 없으면 다음 자동 continuation은 억제된다. 토큰 예산이 있는 목표가 한도에 닿으면 새 작업 대신 wrap-up 지시가 들어간다.

4-1. 모델에게 노출되는 세 개의 툴

goal_tool.rs를 보면 모델이 사용할 수 있는 goal 관련 함수는 정확히 세 개로 제한된다.

pub const GET_GOAL_TOOL_NAME: &str = "get_goal";
pub const CREATE_GOAL_TOOL_NAME: &str = "create_goal";
pub const UPDATE_GOAL_TOOL_NAME: &str = "update_goal";

모델은 get_goal로 현재 목표를 조회하고, create_goal로 새 목표를 만들며, update_goal로 상태를 갱신한다. 다만 update_goal의 description에는 다음과 같은 제한이 명시되어 있다.

Set status to complete only when the objective has actually been achieved and no required work remains. You cannot use this tool to pause, resume, or budget-limit a goal; those status changes are controlled by the user or system.

(번역) 목표가 실제로 달성되어 남은 필수 작업이 없을 때만 complete로 상태를 변경하라.
이 툴로 목표를 pause·resume·budget-limit 할 수 없으며, 해당 상태 변경은 사용자 또는 시스템만 제어한다.

즉, 모델이 직접 손댈 수 있는 상태는 complete 하나뿐이고, pause/resume/budget_limited는 사람 또는 런타임만 제어한다. 자율성과 통제권을 명확히 분리한 설계로 보인다.

또한 create_goal의 description은 다음 두 가지를 못 박아 둔다.

첫째, 사용자나 system/developer 지시에서 명시적으로 요청했을 때만 목표를 만든다. 일반 태스크에서 모델이 임의로 목표를 추론해 만드는 것은 금지된다.

둘째, 이미 목표가 있으면 create_goal은 실패하고, 상태 변경은 update_goal로만 처리해야 한다. "조용히 자율 모드로 진입하는" 가능성을 의도적으로 차단한 것이다.

4-2. continuation 프롬프트 템플릿

루프를 실제로 굴리는 건 continuation.md 템플릿이다. 모델이 한 턴을 끝내고 아무 입력도 없는 대기 상태(idle)가 되면, 시스템이 이 템플릿 내용을 모델에게 다시 전달한다.

Continue working toward the active thread goal. Budget: - Time spent pursuing goal: {{ time_used_seconds }} seconds - Tokens used: {{ tokens_used }} - Token budget: {{ token_budget }} - Tokens remaining: {{ remaining_tokens }} ... Avoid repeating work that is already done. Choose the next concrete action toward the objective.

(번역)

활성 목표를 향해 계속 작업하라.

예산 현황: - 목표 추진에 사용한 시간: {{ time_used_seconds }}초 - 사용한 토큰: {{ tokens_used }} - 토큰 예산: {{ token_budget }} - 남은 토큰: {{ remaining_tokens }} ...

이미 완료된 작업을 반복하지 마라. 목표를 향한 다음 구체적인 행동을 선택하라.

단순한 "계속해" 한 마디가 아니다. 토큰을 얼마나 썼는지, 시간이 얼마나 지났는지까지 함께 전달해서, 모델이 자기 진행 상황을 파악한 채로 다음 행동을 고르게 만든다.

4-3. 안전장치 — idle 우선순위와 무한 루프 차단

루프가 무한정 돌지는 않는다. core/src/goals.rs를 보면 두 가지 제동 규칙이 있다.

이어가기(continuation)는 세션이 완전히 비어 있을 때만 시작된다. 사용자 입력이 들어오거나 처리할 메시지가 남아 있으면 뒤로 밀린다.
연속된 이어가기에서 실제 도구 호출(tool call)이 한 번도 없으면 그 다음 이어가기는 자동으로 막힌다.

두 번째 규칙이 무한 루프 방지 장치다. 모델이 아무것도 하지 않고 빈 답만 반복하면 더 이상 깨우지 않는다는 뜻이다. 또한 작업이 중간에 끊기면(인터럽트) 목표가 자동으로 일시정지(paused) 상태가 되고, 작업을 다시 이어가면 자동으로 활성 상태로 돌아온다.

목표의 상태는 goal_status.rs 기준으로 active(진행 중), paused(일시정지), budget_limited(예산 소진), complete(완료) 네 가지로 관리된다. 터미널 화면 상단에는 경과 시간이나 토큰 사용량이 표시된다.

토큰 예산을 따로 지정하지 않아도 자율 실행 자체는 가능한데, 이때는 경과 시간만 보인다. 같은 파일의 테스트가 그 동작을 직접 보여 준다.

fn active_goal_usage_reports_time_without_budget() {
    assert_eq!(active_goal_usage(None, 12_500, 120), Some("2m".to_string()));
}

fn active_goal_usage_prefers_token_budget() {
    assert_eq!(active_goal_usage(Some(50_000), 12_500, 90), Some("12.5K / 50K".to_string()));
}

토큰 예산이 주어지면 화면에 12.5K / 50K 같은 잔량으로 표시되고, 없으면 경과 시간만 나온다. 내부 로직은 예산 관리를 지원하지만, 터미널에서 /goal 목표내용으로 직접 입력할 때는 예산값을 함께 넣는 문법이 확인되지 않는다. 예산 설정이 필요하다면 서버 API나 모델 툴을 통한 경로를 확인해야 한다.

5. Claude ralph loop와의 비교 — 같은 철학, 다른 구조

앞서 인용한 OpenAI 발표 트윗이 ralph loop를 직접 언급한 만큼, Claude Code 진영의 oh-my-claudecode ralph 스킬과 비교해 두는 편이 자연스럽다. ralph 스킬 SKILL.md는 다음과 같이 자기 정의한다.

Ralph is a PRD-driven persistence loop that keeps working on a task until ALL user stories in prd.json have passes: true and are reviewer-verified. It wraps ultrawork's parallel execution with session persistence, automatic retry on failure, structured story tracking, and mandatory verification before completion.

(번역)

ralph는 PRD 기반 지속 루프로, prd.json의 모든 요구사항 항목이 passes: true 상태가 되고 검토자가 검증할 때까지 계속 작업한다.

ultrawork의 병렬 실행을 세션 지속, 실패 시 자동 재시도, 구조화된 항목 추적, 완료 전 필수 검증으로 감싼 구조다.

이 정의가 두 도구의 차이를 잘 보여준다. Codex /goal은 자유 텍스트 목표 하나를 AI가 알아서 풀어가는 구조다.

반면 ralph는 기획 문서(PRD/prd.json)에 적힌 요구사항 항목들을 하나씩 구현하고, 각 항목을 검증자가 확인한 뒤에야 다음으로 넘어가는 다단계 구조다. 같은 SKILL.md에서 단계 설명을 보면 ralph 흐름이 더 분명해진다.

Steps: 1. PRD Setup ... 2. Pick next story ... 3. Implement ... 4. Verify the current story's acceptance criteria ... 7. Reviewer verification (tiered, against acceptance criteria) ... 8. On approval: run /oh-my-claudecode:cancel to cleanly exit

(번역) 단계: 1. PRD 설정 ... 2. 다음 항목 선택 ... 3. 구현 ... 4. 현재 항목의 완료 조건 검증 ... 7. 검토자 검증(단계적, 완료 조건 기준) ... 8. 승인 시: /oh-my-claudecode:cancel로 깔끔하게 종료

ralph는 architect 같은 별도 검토자(reviewer) 단계를 구조상 강제로 포함한다. 재미있는 건 ralph가 옵션으로 Codex CLI를 검토자로 불러 쓸 수 있다는 점이다.

If --critic=codex, run omc ask codex --agent-prompt critic "..." for the approval pass. The Codex critic prompt MUST include: 1. The full list of acceptance criteria from prd.json ... 2. A directive to evaluate whether the implementation is OPTIMAL — oh-my-claudecode ralph SKILL.md (같은 출처)

(번역) --critic=codex인 경우, 승인 단계에서 omc ask codex --agent-prompt critic "..."을 실행하라. Codex critic 프롬프트에는 반드시 다음이 포함되어야 한다: 1. prd.json의 전체 완료 조건 목록 ... 2. 구현이 최적인지 평가하는 지시문

다시 말해, 두 도구는 경쟁만 하는 관계가 아니라 보완재로 묶일 수 있다.

Claude는 PRD 기반 분해/검증 루프를 돌리고, 그 검증 단계에 Codex CLI를 critic으로 호출하는 식이다.

비교 축	Codex `/goal`	oh-my-claudecode ralph
트리거 방식	슬래시 커맨드 `/goal <목표>`	슬래시 커맨드 `/oh-my-claudecode:ralph`
목표 표현	자유 텍스트 목표 하나	prd.json의 요구사항 항목 여러 개
종료 조건	모델이 `update_goal`로 complete 처리	모든 story `passes: true` + reviewer 승인
사람 개입 지점	pause/resume/clear 사용자 제어, 모델은 complete만	각 요구사항 항목별 완료 확인 + 검토자(architect/critic) 단계
토큰/비용 관리	내부 로직은 토큰 예산 관리 지원. 다만 터미널 `/goal` 입력에서 예산 인자 문법은 미확인	별도 명시 없음. critic 호출 시 별도 비용
생태계	OpenAI Codex CLI 0.128.0+	Claude Code + oh-my-claudecode 플러그인

한 줄로 요약하면, /goal은 모델 자율성을 최대화하는 단일 루프이고, ralph는 PRD라는 외부 아티팩트로 자율성을 강제 분해하는 다단계 루프다.

ex) AI에게 goal 예시를할만한 프롬프트를 생성해달라고 했더니 엄청 장황하게 작성해 주었는데, 이대로 진행해보겠다.

  /goal 이 Next.js 앱의 공개 서비스/라우트 메타데이터를 하나의 타입 안전한 레지스트리로 단일화해줘.

  목표:
  현재 Hub 카드, Header/Footer 링크, sitemap 생성, 라우트 관련 테스트에 흩어져 있는 공개 페이지/서비스 정보를 하나의 typed registry로 정리
  하고, 중복 하드코딩을 줄여줘.

  범위:
  - src/constants, src/app/sitemap.ts, src/components/features/hub, src/components/layout/Header*, Footer를 먼저 조사한다.
  - public route/service 정보를 표현하는 작은 typed registry를 설계한다.
  - registry에는 필요에 따라 path, title, description, category, priority, sitemap 설정, nav 노출 여부, hub 노출 여부, asset/icon 메타데이
  터 같은 필드를 포함한다.
  - sitemap.ts와 Hub 카드, Header/Footer 링크 등 중복이 큰 부분은 registry를 사용하도록 리팩터링한다.
  - 기존 라우트, SEO 동작, 화면 UI는 가능한 한 유지한다.
  - 명백한 불일치나 버그가 있으면 작은 범위에서 함께 고친다.
  - 중요한 공개 라우트가 누락되지 않는지, 중복 path가 없는지, sitemap/hub/nav 메타데이터가 일관적인지 검증하는 테스트를 추가하거나 보강한
  다.

  제약:
  - 새 의존성은 추가하지 않는다.
  - diff는 작고 리뷰 가능하게 유지한다.
  - 기존 라우트와 SEO 동작을 깨지 않는다.
  - 관련 없는 UI 개편은 하지 않는다.
  - 이 프로젝트의 기존 패턴, path alias, TypeScript strict 모드를 따른다.

  검증:
  - lint, unit test, 관련 E2E test를 실행한다.
  - 가능하면 pnpm quality-gate까지 실행한다.
  - 전체 quality gate가 기존의 무관한 실패 때문에 실패하면, 어떤 명령이 어떤 이유로 실패했는지 증거와 함께 분리해서 보고한다.
  - registry 구현, 중복 제거, 테스트 보강, 남은 리스크 정리가 끝났을 때만 완료 처리한다.

  최종 보고:
  - 어떤 중복 소스를 발견했는지
  - 어떤 registry 구조를 선택했는지
  - 어떤 파일이 단순해졌는지
  - 어떤 테스트를 추가/수정했는지
  - 전후로 어떤 유지보수 리스크가 줄었는지

ex)

- 이후 얼마나 오래 일하는지, 어떤 결과가 얼마만에 나오게 되는지 살펴보자.

- 생각보다 빨리 완료 되었다. (나중엔 좀더 복잡한 개발 요청을 해보도록 하겠다.)

- 15m 소요시간 확인.

6. 토큰 소모 후 동작 — 확인된 것과 확인되지 않은 것

"며칠씩 돌아가다 토큰이 떨어지면 어떻게 되느냐"는 질문이 가장 많이 나온다. 이 부분은 사실과 추정을 분리해서 적는다.

Codex 0.128.0의 goals/budget_limit.md 템플릿에는 다음 본문이 들어 있다.

The active thread goal has reached its token budget. The system has marked the goal as budget_limited, so do not start new substantive work for this goal. Wrap up this turn soon: summarize useful progress, identify remaining work or blockers, and leave the user with a clear next step. Do not call update_goal unless the goal is actually complete.

(번역) 활성 목표가 토큰 예산 한도에 도달했습니다.

시스템이 목표를 budget_limited로 표시했으므로, 이 목표로 새로운 실질적인 작업을 시작하지 마세요.

이번 턴을 곧 마무리하세요: 유용한 진행 상황을 요약하고, 남은 작업이나 장애물을 파악하고, 사용자에게 명확한 다음 단계를 남겨 주세요.

목표가 실제로 완료된 경우가 아니라면 update_goal을 호출하지 마세요.

이 템플릿에서 확인할 수 있는 사실은 두 가지다.

첫째, 토큰 예산이 소진되면 시스템이 목표를 budget_limited(예산 소진) 상태로 표시한다.

둘째, 진행 중인 턴을 강제로 끊지 않고 "마무리 지시"를 주입한다.

즉, 진행하던 작업을 요약하고 다음 단계를 남겨 놓은 뒤 조용히 멈추는 방식이다.

PR #18076에서도 같은 동작을 "soft stop"이라고 표현한다.

주의: budget_limited 이후 자동 재시작 메커니즘은 소스코드와 릴리즈 노트에서 확인되지 않는다.

커뮤니티 일각의 "토큰 충전 후 알아서 다시 돈다" 류 표현은 직접 검증이 어렵다.

확인할 수 있었던 범위에서는, 재시작은 사용자가 /goal resume을 입력하거나 새 목표를 다시 등록해야만 일어난다.

자동 재시작 로직이 어딘가 숨어 있을 가능성을 단정적으로 부정할 수는 없지만, 적어도 0.128.0 시점의 공개 코드와 문서로는 그 동작을 보장하지 못한다.

7 활용 팁

소스코드 분석을 바탕으로 실제 운용 시 유용한 가이드를 정리한다.

7-1. 목표 작성 요령

소스코드의 create_goal 설명에는 "일반 작업 중에 멋대로 목표를 추론하지 마라"고 못 박혀 있다.

이 원칙은 목표를 작성하는 사람에게도 그대로 적용된다. 목표 텍스트에 다음 세 가지가 명확하게 들어가야 한다.

완료 정의: 어떤 상태가 되면 update_goal이 complete로 호출되어야 하는지 명시한다. "벤치마크 커버리지를 70%로 올린다"처럼 정량 기준이 들어가면 모델이 종료를 판단할 단서가 생긴다.
금지 행동: 무인 모드에서 절대 하면 안 되는 행동을 함께 적는다. 예컨대 "프로덕션 DB에 직접 쿼리하지 않는다", "GitHub PR 머지는 사람이 한다"처럼 단단한 가드레일을 텍스트에 박는다.
시간/예산 한도: 토큰 예산 설정을 지원하는 API나 툴을 쓰는 경우라면 예산을 명시한다. 터미널 화면에서 /goal 목표내용으로만 입력하는 경우에는 예산 문법이 확인되지 않으므로, 목표를 작게 나누고 수동으로 pause/clear 지점을 만든다.

7-2. 안전한 실행 환경

/goal을 켜기 전에는 환경 자체를 격리한다. 다음 항목은 자율 루프 본격 운용 전에 한 번씩 점검해 둔다.

격리 환경 우선: 별도 작업 디렉토리(worktree), 컨테이너, VM에서 실행한다. 이어가기(continuation)는 대기 상태마다 자동으로 켜지므로 같은 환경에서 다른 작업을 병행하지 않는다.
Git 보호 설정: 루프가 스스로 PR을 만드는 워크플로라면, main 같은 보호된 브랜치에 직접 push하지 못하도록 권한을 분리해 둔다.
/goal pause 위치 미리 파악: 터미널 화면에서 즉시 멈추는 방법을 미리 익혀 둔다. "이 방향이 아니다" 싶을 때 pause를 입력하면 이어가기가 멈춘다.
예산 설정 방법 확인: 무인 실행에는 예산 상한이 있는 게 안전하다. 단, 터미널 슬래시 커맨드만으로는 토큰 예산 설정 문법이 확인되지 않으니, 서버 API나 모델 툴 경유 여부를 먼저 확인한다. 그게 어렵다면 목표를 잘게 나눠 수동 중단 지점을 만드는 게 현실적이다.
로그 분리: 이어가기는 사람이 없는 시간대에도 돌 수 있다. 로그를 별도 파일이나 채널로 빼 두고, 나중에 어떤 동작이 있었는지 추적할 수 있게 한다.

정리하면, 자율 모드의 비용은 모델이 결정하지만 안전은 사람이 사전 설계한다.

8. 결정 매트릭스 — 언제 쓰고, 언제 쓰지 않는가

상황	권장 도구
단일 자유 텍스트 목표를 모델 자율로 풀고 싶다	Codex `/goal`
요구사항을 항목별로 분해하고 검토자 승인이 필요하다	oh-my-claudecode ralph
Codex 환경에서 token 예산만으로 자연 종료를 원한다	token_budget을 노출하는 app-server/API 경로. 단순 TUI `/goal`만으로는 확인 필요
Claude Code 환경이고 PRD 기반 검증이 익숙하다	oh-my-claudecode ralph
자율 모드를 처음 써 보는 단계라 위험을 최소화하고 싶다	둘 다 신중히. 특히 `/goal`은 격리 환경 + 작은 목표 단위 + 가능한 경우 token_budget

결정 원칙은 둘 중 하나를 고르는 게임이 아니라 자율성과 가드레일의 비율을 어디서 잡을지 정하는 문제다.

9. 마무리

/goal은 화려한 신기능이라기보다, 커뮤니티가 비공식으로 써 오던 ralph loop 방식을 OpenAI가 자기 식으로 정리한 버전에 가깝다. config 한 줄, 슬래시 커맨드 네 개, 모델용 툴 세 개, 이어가기 템플릿 한 장이라는 단순한 구성이다. 그 안에서 AI가 자율로 할 수 있는 범위와 사람이 통제하는 범위를 명확히 나눈 점은 인상적이다.

참고 자료

Codex Mac App 가이드: 설치부터 권한, MCP, 자동화까지 - Codex App으로 코드를 직접 맡기는 시대

갓대희 — Sat, 2 May 2026 15:37:53 +0900

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

Codex 앱은 워크트리를 들고 코드를 직접 바꾸는 에이전트 도구다.

이 글은 OpenAI 공식 문서를 기준으로 Codex 앱의 설치·권한·설정·플러그인·자동화를 정리하고, 공식 문서에 아직 세부 설명이 부족한 부분만 실제 Mac 설정 화면으로 보완한 글이다. 공식 문서상 Codex 앱은 macOS와 Windows에서 제공되지만, 여기서는 Mac 화면과 macOS 권한 흐름을 중심으로 다룬다.

사실 Codex 앱은 사용한지 오래 되었는데, 많이 활용하는 편은 아니었다.

그러던 중 최근 Codex 5.5로 업그레이드 되고 난 후 코딩에서 활용시에도 만족스럽고, 기획서를 만들어 가는데에도 많이 활용하고, 그 퀄리티가 많이 올라 가게 되었다. (이 상세 활용에 대해서는 별도의 글에서 작성할 수 있도록 하겠다.)

이제 코덱스 앱에 대해서 충분히 알아갈만한 가치가 매우 커진것 같아서 Codex App에대해 하나하나 자세히 살펴보는 시간을 갖게 되었다.

ex) 개발 및 소스리뷰 진행 예시

ex) 자주 사용하는 excel, powerpoint 플러그인

공식 문서 기준 핵심 기능 맵

OpenAI는 Codex 앱을 "parallel threads, built-in worktree support, automations, Git functionality"를 갖춘 데스크탑 경험으로 설명한다. 아래 기능들은 공식 Codex App 문서의 기능 목록을 기준으로 재구성한 것이다.

공식 기능	무엇을 의미하나	글에서 다루는 위치
Parallel project threads	여러 프로젝트 스레드를 나란히 실행하고 전환	사이드바, 사용량, `agents.max_threads`
Worktrees	병렬 변경을 Git worktree로 격리	깃 통합, 워크트리 자동 정리
Review and ship	diff 검토, 파일 stage, commit, push	깃 통합, ChatGPT 앱과의 차이
Automations	반복 작업 예약 또는 기존 스레드 웨이크업	Standalone vs Thread 자동화
Computer use / Browser	macOS 앱, 브라우저 플로우, 로컬 페이지 테스트	플러그인, 권한, Computer Use 주의
Plugins / Skills / MCP	앱 통합, 재사용 지침, 외부 도구 서버 연결	플러그인, MCP, 개인 맞춤

설치 · 계정 · 사용 한도
사이드바 + 작업 모드 + 권한 3단계
일반 / 받아쓰기 / 알림 / 후속 행동
플러그인 마켓 14개
예약 채팅 자동화 — Standalone vs Thread
config.toml + 샌드박스 + 승인 정책
MCP 서버 통합
깃 통합 — 브랜치 접두사 · 워크트리
개인 맞춤 + 다른 에이전트 설정 가져오기
ChatGPT Mac 앱과의 차이

1. 설치 · 계정 · 사용 한도

공식 문서 기준으로 Codex는 ChatGPT Plus, Pro, Business, Edu, Enterprise 플랜에 포함된다.

설치는 chatgpt.com/codex에서 시작하면 되고, Mac 사용자는 Apple Silicon 또는 Intel용 DMG를 받는다. Windows는 Microsoft Store 경로가 따로 제공된다.

일반적인 로그인 경로는 ChatGPT 계정이다.

공식 문서에는 OpenAI API 키 로그인도 가능하다고 되어 있지만, API 키 방식은 cloud threads 같은 일부 클라우드 기능이 제한될 수 있고 사용량 기반 API 과금이 적용된다. 따라서 데스크탑 앱을 일반 개발 워크플로우에 쓰려면 ChatGPT 계정 로그인을 기본 전제로 보는 편이 맞을 것 같다.

사용 화면 읽는 법

실제 화면: 사용 메뉴 — 일반 한도 / Spark 한도 / 잔액 영역이 분리되어 표시된다

사용 메뉴에서는 실제 남은 한도를 확인할 수 있다.

내 화면 기준으로는 일반 사용 한도(5시간 / 주간), GPT-5.3-Codex-Spark 사용 한도(5시간 / 주간), 잔액 영역이 분리되어 표시된다.

(글에서 자주 부르는 "잔여 크레딧"의 GUI 라벨은 잔액이며 그 안에 "0크레딧 남음" 표시와 구매하기/자동 충전 설정 버튼이 있다).

일반 사용 한도와 Spark 한도가 따로 보이는 이유는 GPT-5.3-Codex-Spark가 별도 usage limit을 가진 research preview 모델로 안내되기 때문이다.

( 난 gpt pro 요금제 사용중이다. 현재 5월 2일기준)

화면 항목	의미	공식 문서 기준 해석
일반 사용 한도	현재 계정의 기본 Codex 사용량. 화면에는 5시간 사용 한도와 주간 사용 한도가 함께 표시된다.	공식 pricing 문서는 local messages와 cloud tasks가 5시간 창을 공유하고, 추가 주간 한도가 적용될 수 있다고 설명한다.
GPT-5.3-Codex-Spark 사용 한도	Spark 모델용 별도 한도. 일반 사용 한도와 별도 섹션으로 표시된다.	공식 pricing 문서는 GPT-5.3-Codex-Spark가 Pro 사용자 대상 research preview이며, 별도 사용 한도로 관리된다고 설명한다.
잔액 (GUI 라벨)	포함 한도에 도달한 뒤 계속 작업할 때 사용할 수 있는 크레딧 잔액. 화면에는 "0크레딧 남음"과 함께 구매하기 버튼이 표시된다.	공식 pricing 문서는 Plus/Pro 사용자가 한도 도달 후 추가 크레딧을 구매할 수 있고, Business/Edu/Enterprise는 flexible pricing 조건에서 workspace credits를 사용할 수 있다고 설명한다.
크레딧 자동 충전	잔액이 최소값에 도달하면 크레딧을 자동으로 추가하는 설정.	공식 pricing 문서는 한도 도달 후 크레딧을 사용해 작업을 이어갈 수 있다고 설명한다. 자동 충전 토글은 앱 화면 기준 세부 UI다.

요약하면, 이 화면은 "지금 얼마나 남았는가"를 보는 곳이다. 구체적인 메시지 수는 모델과 작업 복잡도에 따라 범위로 계산되므로, 숫자를 외우기보다 일반 한도·Spark 한도·크레딧 잔액이 따로 움직인다는 점을 이해하는 것이 더 중요하다.

Fast 모드와 이미지 생성은 한도를 더 빨리 쓴다

공식 pricing 문서는 Fast 모드가 지원 모델에서 크레딧을 더 빠르게 소모하고, 이미지 생성은 일반 턴보다 평균 3-5배 빠르게 포함 한도를 사용한다고 안내한다.

또한 Free 플랜에서는 Codex 이미지 생성이 제공되지 않고, API 키 사용 시에는 ChatGPT 포함 한도 대신 API 가격이 적용된다고 명시한다.

이미지 생성 가능 여부와 별도 한도는 ChatGPT 플랜/지역/시점에 따라 달라질 수 있으므로, 여기서는 Codex 포함 한도에서 더 빠르게 차감될 수 있다는 점을 중심으로 이해하면 된다.

설정 창을 열면 왼쪽 사이드바에 12개 메뉴가 보인다. 각 메뉴가 어떤 영역을 담당하는지 한 번 훑어 두면 이후 섹션이 빠르게 이해된다.

사이드바 12개 메뉴

번호	메뉴	역할
1	일반	작업 모드 · 권한 · 단축키 · 속도 · 후속 행동
2	모양	테마 · 폰트 · 레이아웃
3	구성	`config.toml` · 승인 정책 · 샌드박스 · Codex 종속성
4	개인 맞춤 설정	성격 · 맞춤형 지침 · 메모리(실험용)
5	MCP 서버	MCP 프로토콜 서버 추가/관리
6	깃	브랜치 접두사 · PR 병합 방식 · 워크트리 자동 정리
7	환경	실행 환경 변수 · 셸 통합
8	작업 트리	Codex가 만든 워크트리 목록(자동 삭제 토글·한도는 깃 메뉴에 있음)
9	브라우저 사용	앱 내장 브라우저(Browser Use) 설정
10	컴퓨터 사용	Computer Use 플러그인(macOS 앱 제어 + 앱별 승인)
11	보관된 채팅	아카이브된 스레드
12	사용	5시간 / 1주 사용 한도 · 계정 정보

사이드바가 12개로 늘어난 만큼, 한 번에 모두 다듬기보다 일반 → 구성 → 깃 → MCP 순서로 자주 쓰는 메뉴부터 정돈하는 편이 효율적이다.

작업 모드 — 코딩용 vs 일상 작업용

일반 메뉴 상단에서 코딩용과 일상 작업용 두 모드 중 하나를 선택한다. 같은 모델·같은 권한이라도 응답 톤과 디테일 수준이 달라진다.

모드	응답 성향	권장 용도
코딩용	기술 디테일 우선. 파일 경로·diff·테스트 명령어를 빠짐없이 노출하는 편이다.	기능 구현, 리팩터, 테스트 작성
일상 작업용	간결한 응답. 자연어 설명과 결정 요약 중심이다.	스탠드업 정리, 릴리스 노트, 회의 후속

권한 3단계 — GUI 라벨과 config.toml 매핑

Codex 앱의 권한은 샌드박스 모드 · 승인 정책 두 축이 합쳐진 결과다.

일반 메뉴 상단의 권한 영역에는 기본 권한 · 자동 검토 · 전체 접근 권한 세 항목이 토글로 표시되는데, 이는 단계별 권한 상승 토글에 가깝다. 실제 sandbox_mode 값은 구성 메뉴의 샌드박스 설정 드롭다운(Read only / Workspace write / Full access)에서 선택하고, config.toml에는 두 키로 분리해 적는다.

매핑 관계는 다음과 같다. (출처: Sandbox concepts, Agent approvals & security)

GUI 라벨	`sandbox_mode` 값	파일 시스템	셸 실행
기본 권한	`"read-only"`	읽기 전용	읽기·조회 중심. 쓰기나 경계 밖 액션은 승인 흐름으로 넘어간다.
자동 검토	`"workspace-write"`	현재 워크스페이스 쓰기 허용	워크스페이스 안 작업은 진행하고, 위험하거나 경계 밖이면 승인 요청.
전체 접근 권한 (구성 메뉴 라벨: Full access)	`"danger-full-access"`	호스트 전체 쓰기 가능	샌드박스 제한을 해제한다. 승인 정책을 별도로 보수적으로 잡아야 한다.

함께 쓰는 승인 정책(approval_policy)은 실제 GUI 드롭다운 기준 네 값이 모두 활성화되어 있다.

Untrusted — "Always ask before taking action"

On failure — "Ask only when a command fails"

On request — "Ask when escalation is requested"

Never — "Run without asking for approval"가 표시된다.

화면에서는 On request가 기본으로 잡혀 있다. 일반적으로 workspace-write + on-request 조합이 가장 자주 쓰이는 편이다.

전체 접근 권한(danger-full-access) 위험성

이 모드는 호스트 시스템 전체를 수정할 수 있다. 실수로 키 파일이나 시스템 설정을 덮어쓸 수 있고, 외부 명령·앱 조작의 피해 범위도 커진다. 실서비스 코드베이스나 개인 노트북에서는 기본값으로 켜지 않는 것이 좋다. 사용한다면 컨테이너·전용 VM·격리된 워크트리에서만 활성화한다. (출처: Agent approvals & security)

3. 일반 / 받아쓰기 / 알림 / 후속 행동

일반 메뉴는 자잘하지만 매일 손에 닿는 옵션이 모여 있다.

실제 화면: 일반 메뉴 6개 옵션 + 속도 + 후속 행동 + 코드 리뷰 + 추천 프롬프트 + 다른 에이전트 가져오기(2개 감지)

일반 옵션 6가지(자주 쓰는 항목)

기본 열림 위치: 드롭다운에서 IDE 선택. 기본 옵션에 VS Code가 잡혀 있다.
언어: 자동 탐지가 기본. 영어/한국어 등으로 강제 지정 가능.
메뉴 막대에 표시: macOS 메뉴바 상단에 Codex 아이콘 노출.
팝아웃 창 단축키: 미니 채팅 창을 띄우는 단축키. 작업 흐름을 끊지 않을 때 유용하다.
실행 중 절전 모드 방지: 장시간 작업 중 Mac이 잠들지 않게 한다.
긴 프롬프트를 보내려면 ⌘+Enter 필요: 활성화하면 여러 줄 프롬프트는 ⌘+Enter로만 보내진다. 실수로 미완성 프롬프트가 전송되는 사고를 줄인다.

속도 — 보통 / Fast

속도 옵션은 보통과 Fast 두 가지다. Fast는 지원 모델의 응답 속도를 올리는 대신 포함 크레딧을 더 빠르게 쓴다.

공식 Speed 문서 기준 Fast 모드는 GPT-5.5와 GPT-5.4에서 1.5배 속도를 목표로 하며, 크레딧 차감률은 각각 Standard 대비 2.5배, 2배로 안내되어 있다.

API 키 로그인에서는 Fast 모드 크레딧이 아니라 표준 API 가격이 적용된다. 보통은 추론 시간을 더 두므로 멀티파일 리팩터나 복잡한 에이전트 작업에 더 안정적인 경향이 있다. (출처: Speed)

후속 행동 / 코드 리뷰

옵션	선택지	의미
후속 행동	대기열 추가 / 스티어링	대기열은 현재 작업을 끝낸 뒤 다음 차례로 실행한다. 스티어링은 진행 중인 에이전트 작업을 즉시 중단하고 새 지시로 방향을 전환한다 — 진행 중 작업은 취소된다. 이미 실행 중인 내용이 필요 없어졌을 때만 스티어링을 쓴다.
코드 리뷰	인라인 / 분리됨	인라인은 본문 diff 옆에 주석을 박아 맥락과 함께 본다. 분리됨은 별도 패널에서 전체 리뷰를 한 번에 훑을 때 유용하다.

받아쓰기 4개

받아쓰기 4개 항목과 알림 3개(완료/권한/질문) 토글이 같은 일반 메뉴 하단에 위치

누르고 말하기 단축키: 키를 누르고 있는 동안만 음성 입력.
말하기 단축키 켜기/끄기: 토글식 단축키. 한 번 누르면 켜지고 다시 누르면 꺼진다.
받아쓰기 사전: 자주 잘못 인식되는 고유명사·약어 등록.
최근의 받아쓰기 기록: 최근 발화 텍스트 검토.

알림 3개

완료 알림 — 집중하지 않았을 때만: 다른 앱에 포커스가 있을 때만 작업 완료를 알린다. 사용 중인 동안엔 조용하다.
권한 알림 활성화: 권한 승인이 필요한 순간 시스템 알림으로 띄운다.
질문 알림 사용: 에이전트가 사용자에게 질문할 때 알림을 보낸다.

환경 메뉴 — 실행 환경 변수 · 셸 통합

사이드바 7번 환경 메뉴는 에이전트 실행 시 주입할 환경 변수를 GUI에서 등록하는 곳이다.

API 키·프록시 주소·내부 서비스 엔드포인트처럼 하드코딩하기 싫은 값을 여기 넣어 두면 에이전트가 셸 명령을 돌릴 때 해당 변수를 자동으로 받는다.

시스템 ~/.zshrc나 .env 파일을 직접 열지 않아도 된다는 점이 편리하다.

다른 에이전트 설정 가져오기는 섹션 9에서

일반 메뉴 화면 하단에 있는 "다른 에이전트 설정 가져오기"는 별도 영역이라 섹션 9 개인 맞춤에서 자세히 다룬다.

4. 플러그인 마켓 — Featured 18개 외 다수

Codex 앱은 OpenAI가 큐레이트한 GUI 플러그인을 한곳에 모아두었다.

공식 문서에서 플러그인은 앱·스킬·MCP 서버를 묶어 Codex가 할 수 있는 일을 확장하는 단위로 설명된다.

Built by OpenAI 필터로 보면 Featured 카테고리에 18개, 그 외에 Coding / Design / Lifestyle / Productivity 등 여러 카테고리가 추가로 보이며 총 50개 이상이 노출된다.

아래 표는 그중 가장 자주 쓰이는 Featured 18개를 카테고리별로 정리한 것이다. 플러그인 목록은 자주 추가·변경되므로 정확한 개수와 항목은 화면에서 직접 확인하는 편이 안전하다.

플러그인	설명 (GUI 그대로)	카테고리
Computer Use	Control Mac apps from Codex	앱/시스템 제어
Browser Use	Control the in-app browser with Codex	웹 탐색
Spreadsheets	Create and edit spreadsheet files	파일 작업
Presentations	Create and edit presentations	파일 작업
GitHub	Triage PRs, issues, CI, and publish flows	개발 도구
Slack	Read and manage Slack	업무 도구
Notion	Notion workflows for specs, research,...	업무 도구
Linear	Find and reference issues and projects.	개발 도구
Statsig	Bring your Statsig workspace into Codex.	개발 도구
Gmail	Read and manage Gmail	업무 도구
Google Calendar	Manage Google Calendar events and...	업무 도구
Google Drive	Work across Drive, Docs, Sheets, and...	업무 도구
Teams	Summarize Teams and draft follow-ups	업무 도구
SharePoint	Summarize SharePoint sites and files	업무 도구
Outlook Email	Triage Outlook inboxes and draft replies	업무 도구
Outlook Calendar	Manage Outlook schedules and meetings	업무 도구
Figma	Design-to-code workflows	디자인/개발
Vercel	Build and deploy web apps and agents	개발 도구

위 18개는 Featured 카테고리이고,

그 외

Coding 카테고리에 Hugging Face / Netlify / CircleCI / Cloudflare / Sentry / Build iOS · macOS · Web Apps / Test Android Apps / Expo / CodeRabbit / Neon Postgres / Supabase / Codex Security 등

Design에 Canva / Remotion / BioRender / HyperFrames

Productivity에 Documents / Atlassian Rovo / Jam / Stripe / Box / Amplitude 등이 추가로 보인다.

일반 플러그인은 설정 → 플러그인 → + 버튼으로 추가한다.

OAuth가 필요한 항목은 클릭 시 별도 인증 창이 뜬다.

Computer Use는 공식 문서 기준 설정 → Computer Use에서 설치하며, 프롬프트 내용상 필요하다고 판단되면 대화 입력창 위에 설치 유도 배너가 뜰 수도 있다.

ex) Computer Use 권한 요청

한 번에 너무 많이 연결하면 권한 알림이 누적되니, 실제로 쓰는 것만 켜두는 편이 깔끔하다.

Computer Use 지역 제한

Computer Use 플러그인은 macOS 전용이며, 출시 시점 기준 EEA(유럽경제지역)·영국·스위스에서는 사용할 수 없다. 사용하려면 macOS의 화면 기록(Screen Recording)과 손쉬운 사용(Accessibility) 권한이 필요하고, Codex 안에서도 앱별 허용 프롬프트를 별도로 승인한다. 해당 지역 사용자는 메뉴에서 비활성화로 표시될 수 있다. (출처: Computer Use)

Computer Use를 켜야 하는 경우와 켜지 말아야 하는 경우

상황	권장	이유
로컬 웹앱 화면 확인	브라우저 사용 먼저	공식 문서는 로컬 웹앱 검증에는 in-app browser를 먼저 쓰라고 안내한다. 파일 변경과 화면 검증이 한 스레드 안에서 정리된다.
macOS 앱, 시뮬레이터, 로그인된 브라우저, 여러 앱을 오가는 흐름	Computer Use 적합	명령줄이나 MCP로는 볼 수 없는 GUI 상태를 보고 클릭·입력·메뉴 이동을 해야 하기 때문이다.
계정, 결제, 보안, 개인정보, 관리자 권한이 걸린 흐름	옆에서 직접 승인	화면 내용과 클릭 결과가 계정 상태에 영향을 줄 수 있다. 민감한 단계는 사용자가 직접 확인해야 한다.
터미널 앱이나 Codex 앱 자체 조작	불가 / 부적합	실제 앱 검증에서 Codex 자체는 Computer Use 대상 앱으로 차단됐다. 터미널이나 Codex 자체를 대신 조작하게 만들면 기존 승인·샌드박스 정책을 우회할 수 있기 때문이다.

플러그인 vs MCP vs Skills

셋이 자주 헷갈린다.

플러그인은 OpenAI가 큐레이트한 GUI 확장으로 앱·스킬·MCP 서버 같은 구성요소를 묶어 설치한다.

MCP는 표준 프로토콜 서버로 사용자가 직접 호스팅하거나 외부 서버를 가져와 붙인다.

Skills는 재사용 가능한 지침·워크플로우 묶음이라 코드/문서 형태로 공유된다. Skills 내부 구조는 이 글의 범위 밖이라 자세히 다루진 않으려 한다.

5. 예약 채팅 자동화 — Standalone vs Thread

실제 화면: 자동화 메뉴 — Status reports / Release prep / Incidents & triage / Code quality 4개 카테고리

Codex 앱의 자동화는 두 형태다.

둘은 동작 방식이 다르고, 화면에서도 분리되어 있다. (출처: Automations)

유형	동작	결과 보고
Standalone	독립 실행. 매번 새 컨텍스트로 시작한다.	Triage/Inbox(분류함)에 보고된다. 보고할 내용이 없으면 자동 보관될 수 있다.
Thread	현재 스레드에 붙어 하트비트처럼 반복 웨이크업한다.	스레드 안에 메시지로 추가된다.

GUI 4 카테고리와 예시 타일

자동화 화면 상단에는 4개 카테고리가 있다. 카테고리는 시작점일 뿐이고, 자유롭게 새 자동화를 만들 수도 있다.

카테고리	예시 타일 (화면 그대로)
Status reports	"스탠드업용으로 어제 Git 활동을 요약해줘", "이번 주 PR·롤아웃·인시던트·리뷰를 종합해 주간 업데이트로 정리해줘", "지난주 PR을 팀원별·주제별로 요약해주고 리스크를 강조해줘"
Release prep	"병합된 PR로 주간 릴리스 노트를 초안으로 작성해줘", "태그를 달기 전에 변경 로그·마이그레이션·기능 플래그·테스트를 확인해줘", "이번 주 하이라이트와 핵심 PR 링크를 반영해 변경 로그를 업데이트해줘"
Incidents & triage	"지난 CI 기간의 CI 실패와 플래키 테스트를 요약하고 우선 수정 사항을 제안해줘", "CI 실패를 확인하고 가능한 근본 원인별로 묶은 다음 최소한의 수정안을 제안해줘", "새 이슈를 분류하고 담당자·우선순위·라벨을 제안해줘"
Code quality	테스트 커버리지·정적 분석 보고 등 코드 품질 지표(예시 타일은 환경에 따라 다르게 노출되므로 화면에서 직접 확인)

설정 방법

자동화 화면에서 새 자동화를 만든다.
스케줄(예: 매일 09:00) 지정. 커스텀 주기가 필요하면 cron 구문을 쓴다.
대상 프로젝트와 사용할 플러그인 선택.
결과 보고 위치(Triage / 현재 스레드) 선택.

실행 위치 — 로컬 프로젝트 vs 백그라운드 워크트리

자동화를 만들 때 실행 위치를 선택할 수 있다.

로컬 프로젝트는 현재 열려 있는 프로젝트 폴더에서 직접 실행한다.

백그라운드 워크트리는 Git 저장소에 별도 워크트리를 만들어 돌리므로, 현재 작업 브랜치에 영향을 주지 않는다.

프로젝트 범위 자동화는 앱이 실행 중이고 선택한 프로젝트가 디스크에 있어야 안정적으로 동작한다. 정기 릴리스 노트·PR 요약처럼 메인 브랜치를 건드리지 않고 반복 실행해야 하는 자동화라면 백그라운드 워크트리 쪽이 안전하다. 자동화는 기본 샌드박스 설정을 사용하며, 조직 정책이 허용하면 approval_policy = "never"로 실행될 수 있어 권한 설정을 보수적으로 잡는 편이 좋다.

(출처: Automations)

ex) 이미 기존 템플릿을 사용해볼 수 있고, 로컬 / worktree, 프로젝트, 주기 등을 임의로 설정해 보았다.

ex) 바로 실행도 가능하다.

ex)

6. config.toml + 샌드박스 + 승인 정책

Codex의 핵심은 config.toml 한 파일이다.

앱·CLI·IDE 확장이 같은 파일을 읽는다. 한 곳을 고치면 세 환경이 동시에 영향을 받는다. (출처: Config Reference)

위치	경로	우선순위
사용자 레벨	`~/.codex/config.toml`	기본값
프로젝트 레벨	`.codex/config.toml` (프로젝트 루트)	신뢰된 프로젝트에서 사용자 레벨을 덮어쓴다. untrusted 프로젝트는 프로젝트 스코프 `.codex/` 설정을 건너뛴다.

구성 화면 — GUI에서 보이는 항목

사이드바의 구성 메뉴에는 다음 컨트롤이 있다.

사용자 지정 드롭다운: 사용자 설정이 기본. 워크스페이스나 프로젝트 단위 프로필을 선택할 수 있다.
config.toml 열기: 기본 텍스트 에디터로 ~/.codex/config.toml을 연다.
승인 정책: On request가 기본 선택. 드롭다운에는 Untrusted, On failure, On request, Never 네 값이 모두 노출된다.
샌드박스 설정: Read only가 기본 선택.다른 값은 Workspace write, Full access (config.toml에는 danger-full-access로 적힘).
Codex 종속성: ON이면 앱이 번들된 Node.js·Python을 사용. OFF면 시스템 PATH의 런타임을 사용.
현재 버전: 직접 검증한 로컬 앱은 26.430.10722로 표시(2026-05-02 기준).
진단 / 재설치 버튼: 종속성 손상 시 진단을 돌리고, 필요하면 번들 런타임을 재설치한다.

샌드박스 모드 표

GUI 라벨	`sandbox_mode`	동작
Read only	`"read-only"`	읽기·조회 중심. 파일 쓰기나 경계 밖 액션은 승인 정책에 따라 멈춘다.
Workspace write	`"workspace-write"`	현재 워크스페이스 안에서 쓰기 허용. 외부 디렉터리·네트워크·민감 액션은 추가 제한을 받을 수 있다.
Full access	`"danger-full-access"`	"Can edit files outside this workspace" — 샌드박스 제한 해제. config.toml 값은 `danger-full-access`이지만 GUI 라벨은 Full access로 표시된다. 호스트 전체에 영향을 줄 수 있으므로 별도 격리 환경에서만 쓴다.

승인 정책 표

Untrusted / On failure / On request / Never

Read only / Workspace write / Full access

GUI 라벨	`approval_policy`	설명
Untrusted	`"untrusted"`	Always ask before taking action. 모든 액션마다 승인 요청.
On failure	`"on-failure"`	Ask only when a command fails. 명령이 실패했을 때만 승인 요청.
On request	`"on-request"`	Ask when escalation is requested. 에이전트가 권한 상승을 요청할 때만 승인. 화면 기본값.
Never	`"never"`	Run without asking for approval. 자동화·CI처럼 사람이 중간 승인할 수 없는 환경에서만 신중히 사용.

고급: granular 승인 정책

네 문자열 값 외에 approval_policy = { granular = { ... } } 객체 형태도 지원된다. sandbox_approval, rules, mcp_elicitations, request_permissions, skill_approval 카테고리별로 승인 여부를 독립 제어할 수 있다. 기본 네 값으로 충분한 경우가 대부분이지만, MCP 호출만 별도 승인하고 싶은 경우 등에 유용하다.

(출처: Config Reference)

config.toml 예시

# ~/.codex/config.toml

# 샌드박스: 워크스페이스 안에서만 쓰기 허용
sandbox_mode = "workspace-write"

# 승인 정책: 필요한 경우에만 승인 요청
approval_policy = "on-request"

[agents]
# 동시에 돌릴 수 있는 에이전트 스레드 수 (기본값 6)
max_threads = 6

# MCP 서버 등록 — 섹션 7 참조
[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]

GUI에서 토글한 값은 즉시 config.toml에 반영된다. 반대로 config.toml을 직접 편집하면 다음 실행 시 GUI에 그대로 보인다. 다만 GUI와 파일을 동시에 편집할 때 어느 쪽이 우선인지는 공식 docs에 명확한 안내가 보이지 않는다. 한쪽만 골라 쓰는 편이 깔끔하다.

Codex 종속성 ON / OFF

ON이면 앱이 자체 번들한 Node.js·Python을 사용한다. 시스템에 어떤 버전이 깔려 있어도 영향이 없다.
OFF면 PATH 상의 시스템 런타임을 사용한다. nvm·asdf·pyenv 환경을 그대로 쓰고 싶을 때 끈다.
종속성이 깨졌다는 메시지가 보이면 진단 → 재설치 순서로 복구한다.

7. MCP 서버 통합

MCP(Model Context Protocol)는 외부 도구·데이터를 표준화된 방식으로 LLM에 붙이는 프로토콜이다.

공식 MCP 문서는 CLI와 IDE 확장의 공유 설정을 중심으로 설명하고, 플러그인 문서는 MCP 서버를 플러그인 구성요소 중 하나로 설명한다. 현재 Codex 앱 화면에도 MCP 서버 메뉴가 있어 앱에서 직접 관리할 수 있다.

즉 특정 벤더 락인 없이 직접 호스팅한 서버, 오픈소스 서버, 사내 서버를 가져와 붙이는 구조로 이해하면 된다.

(출처: MCP server integration, Plugins)

추가 방법 — GUI vs config.toml

공식 문서 기준 CLI와 IDE 확장은 같은 config.toml 설정을 공유한다. Codex 앱은 화면에서 MCP 서버를 관리할 수 있으므로, GUI에서 보이는 값과 config.toml을 함께 확인하는 방식이 안전하다.

GUI: 설정 → MCP 서버 → + 서버 추가 → 이름·command·args 입력.
config.toml 직접 편집: ~/.codex/config.toml에 [mcp_servers.<name>] 블록 추가.

물론 요즘엔 그냥 자연어로 ~~ MCP 추가해줘 라고 말만해도 쉽게 등록이 가능하다.

예시 — context7 MCP

# ~/.codex/config.toml

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]

# 사내 서버 추가 예시
[mcp_servers.internal_kb]
command = "node"
args = ["/Users/me/mcp-servers/internal-kb/dist/index.js"]

CLI와 IDE 확장이 같은 config.toml을 읽는다는 점이 가장 큰 장점이다.

반복해서 쓰는 MCP 서버는 파일에 명시해 두면 터미널 codex 명령과 IDE 확장에서 같은 설정을 재사용할 수 있다. 앱 GUI에서 추가한 서버도 같은 이름과 실행 명령이 들어갔는지 config.toml에서 한 번 확인해 두면 혼선을 줄일 수 있다.

추가 필드 — enabled, required, HTTP 서버

command/args 외에 실용적인 필드가 더 있다.

enabled = false를 추가하면 블록을 삭제하지 않고 서버를 일시 비활성화한다.

required = true로 설정하면 해당 서버가 연결되지 않을 때 앱 시작이 실패하므로, 팀 필수 서버에 달아 두면 빠뜨릴 수 없다.

(출처: MCP server integration)

HTTP 기반 MCP 서버는 command 대신 url과 bearer_token_env_var를 쓴다. 토큰은 환경 변수 이름으로 전달해 파일에 직접 노출되지 않게 한다.

# HTTP 서버 예시 (bearer token 인증)
[mcp_servers.company_api]
url = "https://mcp.internal.example.com/sse"
bearer_token_env_var = "COMPANY_MCP_TOKEN"

# stdio 서버 — 일시 비활성화
[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
enabled = false

# 팀 필수 서버 — 없으면 시작 실패
[mcp_servers.internal_kb]
command = "node"
args = ["/opt/mcp/internal-kb/index.js"]
required = true

플러그인과의 차이 한 줄

플러그인은 OpenAI가 골라 둔 GUI 통합이고, MCP는 사용자가 직접 가져와 붙이는 표준 프로토콜이다. 같은 서비스(예: GitHub)를 두 경로 모두로 연결할 수도 있는데, 동작 범위가 겹치면 혼선이 생기니 한쪽만 활성화하는 편이 정리된다.

8. 깃 통합 — 브랜치 접두사 · 워크트리

깃 메뉴는 Codex가 만든 변경을 어떤 모양으로 저장할지 결정한다. 기본값이 잘 잡혀 있어 그대로 써도 무방하지만, 팀 규칙에 맞춰 한 번 손보면 PR 흐름이 깔끔해진다.

설정	기본값	설명
브랜치 접두사	`codex/`	에이전트가 만드는 모든 브랜치 앞에 자동으로 붙는다. 예: `codex/fix-login`
PR 병합 방법	병합 / 스쿼시	팀 컨벤션에 맞춰 선택한다.
사이드바 PR 아이콘	OFF	사이드바에 PR 상태 아이콘 표시 여부.
항상 강제 푸시	OFF	ON으로 두면 `--force-with-lease` 류의 강제 푸시를 매번 수행한다. 팀 환경에선 신중히 켠다.
초안 PR 생성	ON	PR을 Draft로 먼저 만들고, 검토 후 Ready로 승격한다.

기본값 조합이 이미 팀 친화적으로 잡혀 있다. 브랜치 접두사 codex/는 에이전트가 만든 브랜치를 사람이 만든 브랜치와 명확히 구분하고, 초안 PR ON은 리뷰 없이 바로 병합되는 사고를 막는다.

항상 강제 푸시는 OFF가 기본이라 협업 브랜치를 실수로 덮어쓸 위험이 낮다.

팀 컨벤션이 스쿼시 병합이라면 PR 병합 방법만 교체하면 나머지는 건드리지 않아도 된다.

처음엔 기본값 그대로 쓰고, 브랜치 이름이 PR 리스트에서 눈에 띄게 정리된 다음에 접두사만 팀 규칙으로 바꾸는 순서가 안전하다.

워크트리 자동 정리

Codex 앱은 작업마다 별도 워크트리를 만든다.

자동 정리 토글과 한도는 작업 트리 메뉴가 아니라 깃 메뉴 하단에 있다. 기본값은 오래된 작업 트리 자동 삭제 ON, 자동 삭제 한도 15이며 한도를 넘으면 오래된 워크트리부터 삭제된다. 사이드바의 작업 트리 메뉴는 현재 생성된 워크트리 목록을 보여주는 화면이고, 정리 옵션이 따로 있지는 않다.

한 가지 헷갈리지 않게 둘은 다른 값이다. 자동 삭제 한도는 디스크에 남기는 워크트리 개수이고, agents.max_threads = 6(공식 기본값)은 동시에 돌릴 수 있는 에이전트 스레드 수다. 한쪽은 보관, 한쪽은 동시성이다. (출처: Config Reference)

# 워크트리 목록 확인 (Codex가 만든 트리도 함께 표시된다)
$ git worktree list

/Users/me/projects/myapp                 abc1234 [main]
/Users/me/projects/myapp/.codex/wt-001   def5678 [codex/fix-login]
/Users/me/projects/myapp/.codex/wt-002   ghi9012 [codex/refactor-auth]
/Users/me/projects/myapp/.codex/wt-003   jkl3456 [codex/add-tests]

# 수동 정리가 필요한 경우
$ git worktree remove /Users/me/projects/myapp/.codex/wt-001

9. 개인 맞춤 + 다른 에이전트 설정 가져오기

개인 맞춤 메뉴는 응답 톤과 컨텍스트 메모리를 조정한다.

성격 (Personality)

드롭다운으로 응답 톤을 선택한다. 화면 기본값은 실용적이다. 다른 옵션은 화면에서 직접 확인할 수 있다.

맞춤형 지침

"이 프로젝트는 FastAPI + Python 3.12 기준" 같은 영구 컨텍스트를 적어 둔다. AGENTS.md 파일과 연동되며, 위치는 사용자 레벨이라면 ~/.codex/AGENTS.md, 프로젝트 단위라면 프로젝트 루트의 AGENTS.md를 따른다. 화면에는 자세히 알아보기 링크가 함께 노출된다. (출처: AGENTS.md guide — developers.openai.com)

AGENTS.md — 실제로 무엇을 쓰는가

AGENTS.md는 에이전트에게 줄 자유형식 지침 파일이다. YAML이나 특별한 문법이 없고, 마크다운 텍스트로 자연어 규칙을 적으면 된다. 프로젝트 루트의 AGENTS.md는 CLI·앱·IDE 어디서 호출해도 동일하게 읽힌다.

# AGENTS.md — 프로젝트 규칙 예시

## 기술 스택
- Python 3.12 / FastAPI / SQLAlchemy 2.x
- 테스트: pytest, 커버리지 80% 이상 유지

## 코딩 규칙
- main 브랜치에 직접 커밋하지 않는다.
- 모든 외부 호출은 httpx 비동기 클라이언트를 쓴다.
- 환경 변수는 pydantic-settings로 로드한다.

## PR 규칙
- PR 제목은 `feat:`, `fix:`, `refactor:` 접두사를 붙인다.
- 릴리스 PR에는 CHANGELOG.md 항목을 함께 추가한다.

임시로 전역 AGENTS.md를 재정의하고 싶다면 ~/.codex/AGENTS.override.md(사용자 레벨) 또는 프로젝트 루트의 AGENTS.override.md를 만들면 된다. 같은 범위에 override 파일이 있으면 일반 AGENTS.md보다 우선 적용되고, 삭제하면 원래 지침으로 돌아간다. 특정 기간만 다른 규칙을 적용할 때 유용하다.

메모리(실험용) — 토글 3개 + 초기화 버튼

개인 맞춤 화면 하단의 메모리(실험용) 영역에는 토글 3개와 액션 버튼 1개가 있다.

내 화면 기준 토글은

메모리 활성화(채팅에서 새 메모리를 생성해 새 채팅에 가져옴),

Chronicle 리서치 미리보기(작업을 도울 수 있도록 화면 맥락을 활용해 메모리 보강),

도구 사용 채팅 제외(MCP 도구나 웹 검색을 사용한 채팅에서는 메모리를 생성하지 않음)이고,

마지막에 메모리 초기화 버튼(모든 Codex 메모리 삭제)이 별도로 있다.

실험용이라는 라벨이 붙은 만큼 베타 단계로 보는 편이 안전하다.

실험용 기능은 변경·삭제될 수 있다

실험용 메모리 토글은 안정 기능보다 동작이 자주 바뀐다. 사내 워크플로우의 핵심 의존으로 묶기 전에 동일 효과를 AGENTS.md·맞춤형 지침으로 옮길 수 있는지 먼저 검토한다.

다른 에이전트 설정 가져오기

외부 에이전트 설정 2개가 자동으로 감지되었고, 항목 옆에 가져오기 버튼이 표시된다(설명 문구: "Codex가 다른 로컬 에이전트 앱에서 유용한 설정을 찾았습니다"). 감지 개수와 어떤 앱(예: Cursor, Continue, Claude 등)을 인식하는지는 환경에 따라 다르므로 화면에서 직접 확인한다. 가져오기를 누르면 해당 도구의 시스템 프롬프트나 규칙이 Codex의 맞춤형 지침으로 전환되어 옮겨진다.

10. ChatGPT Mac 앱과의 차이

두 앱은 같은 OpenAI 출시이지만 목적이 다르다. ChatGPT 앱이 물어보고 받아보는 도구라면, Codex 앱은 맡기고 결과를 받는 에이전트 도구다. 표로 정리하면 다음과 같다.

항목	ChatGPT Mac 앱	Codex Mac 앱
주 사용 목적	질문·요약·아이디어 정리	코드 변경·테스트·PR 자동화
전역 호출	Option+Space (Chat Bar)	메뉴바 아이콘 + 팝아웃 창 단축키
IDE 연동	Work with Apps — IDE 파일 컨텍스트 읽고 diff 적용	자체 워크트리 생성 + 깃 커밋·PR까지 수행
샌드박스/권한	macOS 권한 + 앱별 연결 권한 중심	3단계 샌드박스 + 3단계 승인 정책 + 플러그인별 권한
설정 공유 범위	앱 자체 설정	`~/.codex/config.toml`로 앱·CLI·IDE 공유
확장 방식	Work with Apps / ChatGPT Apps	화면 기준 14개 GUI 플러그인 + MCP 서버 직접 등록 + Skills
자동화	예약 작업 영역 별도 노출 안 함	Standalone / Thread 자동화
워크트리 관리	없음	자체 워크트리 + 자동 정리(기본 한도 15)
음성	ChatGPT Voice는 웹·iOS·Android·Windows 쪽과 구분해야 한다. 공식 릴리스 노트에는 macOS 앱 Voice 경험이 2026-01-15 종료된다고 공지되어 있으나, Work with Apps 도움말에는 Advanced Voice 관련 문구가 남아 있어 현재 앱 화면 기준 확인이 필요하다.	받아쓰기 4종 옵션 제공

표를 정리해 보면 두 앱은 겹치는 듯해도 사용 흐름이 갈린다. ChatGPT 앱은 IDE 옆에서 짧게 묻고 답을 가져오는 사이드킥에 가깝고, Codex 앱은 워크트리·브랜치·PR을 들고 들어가 끝까지 처리하는 에이전트다. 권한 모델도 Codex 쪽은 샌드박스·승인 정책·플러그인 권한이 겹치므로, 코드를 바꾸는 작업에서는 설정을 먼저 정리하는 편이 안전하다. 자동화 측면에서도 Codex 쪽이 한 단계 더 깊다.

한 줄 요약: ChatGPT 앱은 정보를 가져오는 도구, Codex 앱은 코드를 바꾸는 도구다.

처음 켰을 때는 사이드바 12개가 빽빽해 보이지만, 실제로 자주 만지는 곳은 일반·구성·깃·MCP 네 메뉴 정도다. 이 글을 옆에 두고 한 번씩 토글해 보면 한 시간 안에 익숙해진다. 더 깊은 자동화나 CLI 통합은 별도 글에서 이어 다룬다.

참고 출처

Hermes Agent(2) : 보조 모델(Auxiliary Model) 분리 - 비싼 메인 모델 대신 보조 모델 따로 쓰는 법

갓대희 — Sat, 2 May 2026 00:11:40 +0900

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

Hermes를 며칠 굴려보면 한 번쯤 이 질문이 걸린다. "이미지 한 장 분석하거나 세션 제목 붙이는 일도 메인 모델이 하나?" 지금 공식 문서 기준의 답은 대체로 "그렇다"에 가깝다. Hermes는 이미지 분석, 웹 페이지 요약, 컨텍스트 압축 같은 부가 작업을 위해 별도의 보조 모델 슬롯을 두지만, auxiliary.*.provider: "auto"는 기본적으로 사용자가 고른 메인 채팅 모델로 흘러간다.

이번에는 Hermes의 보조 모델이 어떤 작업을 처리하는지, hermes model CLI와 config.yaml로 그 슬롯을 어떻게 분리해 비용을 낮출 수 있는지, 그리고 Curator 스킬 리뷰처럼 별도 보조 슬롯으로 빠진 항목은 어디서 손대는지를 살펴보려 한다.

이 가이드, 나한테도 해당될까?

보조 슬롯 분리의 비용 효과는 메인 모델의 과금 구조에 따라 크게 달라진다. 아래 표로 본인 상황을 먼저 짚어보자.

사용 패턴	분리 효과	이유
API 직접 과금 (OpenRouter, Anthropic API 등)	효과 큼	호출마다 토큰 비용 발생 → Flash 계열로 전환 시 즉시 절감
구독형 (ChatGPT Plus / Codex OAuth)	효과 제한적	월정액 내 소비 → 보조 슬롯 호출의 한계비용 ≈ 0. 분리보다 그냥 쓰는 게 나을 수 있다.
특수 플랜 (GLM 코딩 플랜, z.ai 등)	플랜 조건에 따라 다름	플랜에 포함된 모델이라면 분리 불필요. 초과 시 별도 과금 구조라면 분리가 유효하다.
로컬 모델 (Ollama, vLLM 등)	비용보다 전문화	메인 모델 자체가 무료 → 분리 목적은 절감보다 작업별 모델 전문화 또는 응답 속도.

한 줄 요약: API 직접 과금 사용자라면 이 가이드가 바로 써먹힌다. 구독형이나 특수 플랜 사용자는 먼저 보조 호출이 플랜 안에 포함되는지, 초과분이 별도 과금인지를 확인하는 게 먼저다.

왜 보조 모델 설정이 비용 문제와 직결되는가
시작하기 — 현재 설정 확인과 첫 분리 시도
설정 방법 1: hermes model CLI로 인터랙티브 구성
설정 방법 2: config.yaml 직접 편집
주요 설정 키 — provider / model / base_url / timeout
Curator 별도 슬롯 설정
비용 절감 전략 — 작업별 모델 매칭 가이드
트러블슈팅 — 흔한 오류와 진단 명령

1. 왜 보조 모델 설정이 비용 문제와 직결되는가

Hermes는 본 채팅과는 별개로 부가 작업용 모델 슬롯을 둔다.

공식 문서는 이를 다음과 같이 정의한다.

"Hermes는 이미지 분석, 웹 페이지 요약, 컨텍스트 압축 등 부가 작업에 '보조' 모델을 사용합니다."

즉, "메인 모델 = 대화", "보조 모델 = 잡일"이라는 역할 분리가 처음부터 설계 차원에 들어가 있다는 뜻이다. 그런데 같은 문서가 곧바로 못 박는 한 줄이 있다.

"기본값(auxiliary.*.provider: "auto")으로는 주 채팅 모델을 사용하지만, 비용 절감을 위해 별도 모델로 라우팅할 수 있습니다."

다시 말해, 슬롯은 분리되어 있지만 기본값으로는 같은 모델이 들어간다. 사용자가 명시적으로 보조 모델을 지정하지 않으면 비싼 메인 모델이 이미지 한 장 보는 작업까지 떠맡는 구조다. 비용 측면에서 이 기본값은 사실상 함정에 가깝다.

공식 문서에서 확인되는 보조 작업 슬롯

공식 Configuration 문서는 auxiliary 아래에서 vision, web_extract, approval, compression, session_search, skills_hub, mcp를 직접 보여준다.

모델 설정 문서에는 title_generation까지 포함한 8개 보조 슬롯이 보이고, Curator 문서는 Curator 리뷰용 슬롯을 auxiliary.curator로 따로 설명한다.

작업명(설정 키)	하는 일	직접 확인 출처
vision	이미지 분석	공식 문서
web_extract	웹 페이지 요약	공식 문서
compression	긴 대화 컨텍스트 압축	공식 문서
session_search	과거 세션 검색	공식 문서
title_generation	새 세션 제목 자동 작성	공식 문서
approval	위험 명령 승인 판단	공식 문서
skills_hub	스킬 검색과 매칭	공식 문서
mcp	MCP 툴 라우팅	공식 문서
curator	Curator의 스킬 검토	공식 Curator 문서

한 줄로 요약하면, 이제 "공식 문서가 보장하는 건 4종뿐"이라고 쓰면 틀린다.

다만 슬롯마다 중요도는 다르다. 비용 절감 효과가 바로 체감되는 쪽은 보통 vision, web_extract, compression, session_search이고, title_generation, approval, skills_hub, mcp, curator는 사용 패턴에 따라 우선순위가 갈린다.

2. 시작하기 — 현재 설정 확인과 첫 분리 시도

보조 모델 설정에 손대기 전에, 지금 내 Hermes가 어떤 상태인지부터 확인하는 게 빠르다.

CLI 레퍼런스에 따르면 hermes config 명령은 구성값을 표시·편집·변경하는 통합 명령으로, show, edit, set, path, env-path, check, migrate 같은 부분 명령을 지원한다.

# 현재 설정 전체 보기
hermes config show

# 보조 모델 설정만 좁혀 보기 (셸 grep)
hermes config show | grep -A 2 auxiliary

provider가 auto로 잔뜩 떠 있다면, 지금 사용자의 비싼 메인 모델이 잡일까지 처리하고 있다는 신호다. 여기서부터가 비용 절감의 시작점이다.

첫 분리 시도는 hermes model 인터랙티브 모드를 추천한다. config.yaml을 직접 다루기 전에 어떤 프로바이더 옵션이 살아 있는지, 어떤 모델 ID가 유효한지 한눈에 보기 좋다. 익숙해지면 그때 yaml 편집이나 hermes config set으로 자동화하면 된다.

3. 설정 방법 1: hermes model CLI로 인터랙티브 구성

가장 간단한 진입점은 hermes model 명령이다. 공식 사용자 가이드는 다음 흐름을 제시한다.

hermes model
# → "Configure auxiliary models" 선택
# → 작업별로 프로바이더/모델 선택

CLI 레퍼런스는 hermes model을 "인터랙티브 provider + model 선택기"로 정의하며, 새 제공자 추가, API 키 입력, OAuth 흐름 실행에도 같은 명령을 쓰도록 안내한다.

즉, 보조 모델 라우팅 외에도 신규 프로바이더 등록까지 같은 진입점으로 묶여 있다.

실제 화면 흐름을 텍스트로 옮기면 다음과 같이 정리된다.

hermes model을 실행한다.
메뉴에서 "Configure auxiliary models"를 선택한다.
vision, compression, session_search 등 작업 단위로 들어간다.
각 작업마다 프로바이더(auto, openrouter, nous, main 등)와 모델 ID를 고른다.

인터랙티브 모드의 장점은 잘못된 모델 슬러그를 입력했을 때 그 자리에서 바로 거부된다는 점이다. 다만 옵션이 많아질수록 클릭 수가 늘어나고, 같은 설정을 여러 머신에 복제하기 어렵다. 팀 단위 표준화가 필요하다면 다음 절의 yaml 편집이 더 깔끔하다.

ex)

4. 설정 방법 2: config.yaml 직접 편집

공식 가이드는 auxiliary 섹션을 yaml로 직접 작성하는 예시를 제공한다.

핵심은 작업명별로 한 블록씩 적고, 그 아래에 provider, model, timeout 등을 명시하는 형태다.

auxiliary:
  vision:
    provider: openrouter
    model: google/gemini-2.5-flash
    timeout: 120
  compression:
    provider: openrouter
    model: google/gemini-2.5-flash
    timeout: 120
  session_search:
    provider: main
    model: glm-4.5-air
    timeout: 60

즉, vision과 compression은 OpenRouter 경유 Gemini 2.5 Flash로 라우팅하고, session_search는 main 프로바이더(주 에이전트 프로바이더 상속) 위에서 가벼운 모델을 쓰는 식이다.

다만 provider와 model ID는 항상 한 쌍으로 생각해야 한다. 같은 GLM 모델이라도 어떤 provider를 쓰느냐에 따라 model ID 형식이 달라진다.

시나리오	provider	model
메인이 z.ai(GLM)이고 보조도 GLM으로 상속	`main`	`glm-4.5-air`
z.ai를 보조 슬롯에서 직접 지정	`zai`	`glm-4.5-air`
OpenRouter 경유 GLM	`openrouter`	`z-ai/glm-4.5-air` (네임스페이스 포함)

위 예시 yaml은 메인 provider가 z.ai(GLM)로 이미 설정된 상황을 전제로 한다. OpenRouter를 메인으로 쓰는 독자라면 session_search의 model도 z-ai/glm-4.5-air로 바꿔야 한다.

4.1 timeout 키와 동시성 제어

공식 가이드의 다른 예시는 web_extract와 session_search에 별도의 timeout/동시성 설정을 권장한다.

auxiliary:
  vision:
    provider: "auto"
    timeout: 120
    download_timeout: 30
  web_extract:
    timeout: 360  # 6분 권장
  approval:
    timeout: 30
  compression:
    timeout: 120
  session_search:
    timeout: 30
    max_concurrency: 3

같은 출처에 따르면 현재 예시값은 vision timeout: 120과 download_timeout: 30, web_extract timeout: 360, approval timeout: 30, compression timeout: 120, session_search timeout: 30과 max_concurrency: 3이다.

또한 extra_body: {}를 통해 enable_thinking: false 같은 프로바이더 특화 필드를 전달할 수 있다. 보조 슬롯은 단순히 모델 이름만 갈아끼우는 곳이 아니라 호출 시간, 다운로드 시간, 병렬 처리 한도까지 같이 손대는 공간이다.

4.2 hermes config set — 한 키씩 안전하게 바꾸기

yaml 전체를 다시 쓰지 않고 한 키만 갱신하고 싶다면 hermes config set을 쓰는 편이 안전하다. 공식 가이드의 예시는 다음과 같다.

hermes config set auxiliary.vision.provider openrouter
hermes config set auxiliary.vision.model openai/gpt-4o
hermes config set auxiliary.vision.timeout 180

한 줄에 하나씩 키를 바꾸는 방식이라 변경 내역이 셸 히스토리에 그대로 남는다. CI 스크립트로 묶기에도 적합하다. 즉, 인터랙티브 모드는 탐색용, yaml 편집은 표준화용, config set은 운영용 도구로 역할을 나눠 보면 된다.

5. 주요 설정 키 — provider / model / base_url / timeout

공식 가이드는 보조 모델 슬롯의 주요 키를 다음과 같이 정의한다.

키	의미
`provider`	프로바이더 선택 (`auto`, `openrouter`, `nous`, `main` 등)
`model`	모델 ID 문자열
`base_url`	커스텀 OpenAI 호환 엔드포인트
`api_key`	base_url용 인증 키
`timeout`	API 호출 타임아웃(초)
`download_timeout`	vision 입력 파일 다운로드 제한 시간
`max_concurrency`	session_search 같은 일부 작업의 동시 실행 한도
`extra_body`	프로바이더별 추가 요청 필드

공통 스키마의 중심은 provider, model, base_url이다. 여기에 api_key, timeout, download_timeout, max_concurrency, extra_body가 작업별로 붙는다. 즉, provider만 바꾸면 같은 슬롯이 다른 라우팅으로 흘러가고, base_url을 채우면 라우팅이 사용자 자체 호스트로 옮겨간다.

5.1 provider 옵션이 가진 의미

같은 문서의 provider 옵션 설명은 짧지만 밀도가 높다.

주요 provider — 대표 예시 (전체 목록은 공식 문서 기준)

auto — 기본값. 보조 작업도 메인 채팅 모델을 사용 / openrouter — OpenRouter 강제 라우팅 / nous — Nous Portal 강제 / zai — z.ai(GLM) 네이티브 / codex 또는 openai-codex — ChatGPT OAuth 계열 / main — 보조 슬롯 전용, 주 에이전트 프로바이더 상속 / minimax — API 키 기반 MiniMax / minimax-oauth — MiniMax OAuth / minimax-cn — 중국 리전 MiniMax (공식 가이드)

* 현재 공식 문서에는 openai, gemini, deepseek, qwen-oauth, kimi-coding, xai, ollama-cloud 등이 추가로 등록되어 있다. 위 목록은 2026-05-01 기준 대표 옵션이며, 최신 전체 목록은 공식 문서를 우선한다.

즉, "이미 OpenRouter 키가 있으면 openrouter", "z.ai(GLM)를 메인으로 쓰면 zai", "주 에이전트와 같은 프로바이더 위에서 다른 모델을 쓰고 싶으면 보조 슬롯에서 main", "ChatGPT OAuth를 쓰고 싶으면 문서 예시의 codex와 registry의 openai-codex 표기 차이를 확인한다"로 갈라진다. auto는 편하지만, 메인 모델이 비싼 추론 모델일수록 비용 면에서는 가장 느슨한 선택지다.

5.2 base_url로 로컬·커스텀 엔드포인트 붙이기

base_url을 채우면 OpenAI 호환 인터페이스를 가진 임의의 엔드포인트를 보조 모델로 쓸 수 있다. 공식 가이드의 예시를 그대로 옮기면 다음과 같다.

auxiliary:
  vision:
    base_url: "http://localhost:1234/v1"
    api_key: "local-key"
    model: "qwen2.5-vl"

다시 말해, Ollama나 사용자가 직접 띄운 vLLM 서버 같은 로컬 인프라를 vision 슬롯에 꽂을 수 있다. 이미지 데이터를 외부 API로 보내고 싶지 않을 때 특히 유용하다. 단, api_key 같은 비밀값을 yaml에 평문으로 두지 않고 환경변수 경유로 묶는 등 별도 운영 규칙은 사용자가 책임져야 한다.

6. Curator 별도 슬롯 설정

Curator 스킬 리뷰는 예전 자료와 현재 공식 문서가 갈리는 지점이다.

최신 Curator 문서는 리뷰 패스를 일반 보조 작업과 같은 auxiliary.curator 슬롯으로 다룬다.

curator:
  enabled: true

auxiliary:
  curator:
    provider: openrouter
    model: google/gemini-3-flash-preview
    timeout: 600

모델 안정성 주의: 예시의 google/gemini-3-flash-preview는 공식 문서에 등장하지만 Preview 상태다. Google이 사전 예고 없이 슬러그를 변경하거나 deprecated할 수 있어 장기 운영용으로 고정하기엔 리스크가 있다. 안정적인 대안으로 google/gemini-2.5-flash(Stable 릴리즈, $0.30/$2.50/M tokens)가 있다. 도입 시점에 OpenRouter 카탈로그에서 현재 상태를 직접 확인하는 것이 가장 안전하다.

여기서 헷갈리기 쉬운 부분이 있다. 과거에는 curator.auxiliary.{provider,model} 형태가 쓰였고, 현재 문서도 이 경로가 아직 동작한다고 설명한다. 다만 deprecation 로그가 남는 레거시 경로이므로 새로 설정한다면 auxiliary.curator로 옮기는 편이 맞다.

# 레거시. 새 설정에는 권장하지 않음.
curator:
  auxiliary:
    provider: openrouter
    model: google/gemini-3-flash-preview

Curator 문서의 위치도 바뀌었다. docs/user-guide/curator가 아니라 docs/user-guide/features/curator 아래에 있다. 이전 URL을 보고 404라고 판단하면, 기능이 없는 게 아니라 문서 경로를 잘못 잡은 것이다.

예시에 등장한 google/gemini-3-flash-preview는 공식 문서 예시에도 나온다. 그래도 이름에 preview가 붙어 있다는 점은 무시하면 안 된다. 장기 운영용 표준 모델로 박아두기보다는, 실제 도입 시점에 OpenRouter나 사용 중인 프로바이더의 카탈로그에서 가격·지원 상태를 다시 확인하는 편이 안전하다.

정리하면, Curator는 일반 보조 슬롯과 같은 패턴(provider, model, 필요하면 base_url/api_key/timeout)을 따른다. 위치만 auxiliary.curator다. 기존 설정에 curator.auxiliary가 남아 있다면 당장 깨질 가능성은 낮지만, 새 글이나 새 설정 예시에서는 레거시 경로를 앞세우지 않는 게 맞다.

7. 비용 절감 전략 — 작업별 모델 매칭 가이드

공식 모델 설정 문서는 보조 슬롯을 값싼 모델로 분리할 만한 대표 사례를 꽤 노골적으로 든다. 세션 제목 생성, compression, approval, web_extract처럼 짧거나 요약 중심인 작업은 비싼 추론 모델을 계속 태울 이유가 약하다는 취지다.

공식 문서의 핵심은 단순하다. 모든 보조 슬롯은 기본적으로 auto, 즉 메인 모델을 쓰지만, 작업 성격이 가벼운 슬롯은 Flash 계열이나 mini 계열로 분리할 수 있다.

즉, 공식 문서 자체가 비용 측면에서 auto보다 작업별 분리를 더 실용적인 선택지로 본다는 뜻이다. 단, 구체적인 절감률은 사용량, 프로바이더 가격, 메인 모델 가격에 따라 달라진다. 그래서 이 글에서도 "X% 절약"처럼 숫자를 박아 넣지 않는다.

7.1 작업 성격에 따른 권장 패턴

공식 가이드의 추천을 작업 성격에 맞춰 정리하면 다음과 같다.

작업	특성	권장 방향
vision (이미지 분석)	멀티모달, 짧은 호출	OpenRouter 경유 멀티모달 Flash 계열
compression (대화 압축)	긴 입력, 빠른 응답	OpenRouter 경유 가벼운 Flash 계열
web_extract (웹 요약)	외부 호출 + 긴 timeout	timeout 360초 + 가벼운 요약 모델
session_search (세션 검색)	빈번 호출, 짧은 텍스트	`main` 프로바이더 위 경량 모델, max_concurrency 제한

한 줄로 종합하면, "긴 입력에는 빠른 Flash 계열을, 짧고 잦은 호출에는 경량 모델 + 동시성 제한을" 붙이는 게 공식 가이드의 기본 발상에 가깝다. 절대 수치보다는 이 매칭 패턴 자체가 의사결정의 출발점이다.

7.2 언제 auto로 두는 것이 합리적인가

모든 슬롯을 분리해야 하는 건 아니다. 다음 두 가지 경우에는 auto를 그대로 두는 편이 나을 수 있다.

호출 빈도가 매우 낮은 슬롯(예: 위험 명령어 판단을 거의 트리거하지 않는 사용 패턴): 분리 작업에 드는 시간 대비 절감 효과가 작다.
보조 모델용 외부 API 키를 별도로 발급하기 어려운 환경: OpenRouter 키 등록까지 가야 분리가 가능하다면, 운영 부담이 절감폭을 넘어설 수 있다.

다시 말해, "비싼 슬롯부터 잘라낸다"가 첫 번째 원칙이고, "잘 안 쓰는 슬롯은 나중에"가 두 번째 원칙이다. vision과 compression은 보통 호출량이 가장 많은 슬롯에 속하므로 가장 먼저 분리할 후보다.

8. 트러블슈팅 — 흔한 오류와 진단 명령

보조 모델 설정에서 자주 발생하는 패턴은 셋이다.

첫째, provider 이름 오타.

둘째, base_url 누락이나 잘못된 스킴.

셋째, timeout이 짧아 외부 호출이 잘려 나가는 케이스. 셋 다 진단 명령으로 빠르게 좁힐 수 있다.

# 1) 현재 보조 모델 설정 확인
hermes config

# 2) 누락된 옵션 자동 추가/마이그레이션
hermes config migrate

# 3) 특정 값을 강제 검증하면서 설정
hermes config set auxiliary.vision.model openai/gpt-4o

공식 가이드는 hermes config로 현재 보조 모델 설정을 확인하고, hermes config migrate로 누락 옵션을 보충하며, hermes config set으로 특정 값을 검증하면서 갱신하라고 안내한다. 즉, "show → migrate → set"이 보조 모델 트러블슈팅의 기본 순서다.

8.1 "내 설정이 왜 무시되지?" 패턴

yaml을 고쳤는데도 변화가 보이지 않을 때 가장 먼저 의심할 곳은 두 가지다.

첫째, 편집한 yaml이 Hermes가 실제 읽는 경로와 다른 곳에 있는 경우. hermes config path 또는 env-path 부분 명령으로 현재 사용 중인 경로를 확인하면 된다(CLI 레퍼런스).

둘째, 키 계층 오류. auxiliary.vision.provider가 아니라 auxiliary.vision: openrouter처럼 한 단계가 빠진 경우다. 후자는 hermes config check로 잡아내는 게 빠르다.

8.2 timeout과 max_concurrency가 보내는 신호

session_search나 web_extract가 잦게 실패한다면 timeout 자체를 의심할 시점이다.

현재 공식 예시 기준으로 web_extract는 360초(6분), vision과 compression은 120초, approval과 session_search는 30초를 쓴다. vision에는 입력 파일을 가져오는 download_timeout: 30도 따로 있다. web_extract를 60~90초처럼 짧게 깎아두면 외부 페이지 응답을 기다리는 도중 호출이 잘리기 쉽고, session_search는 max_concurrency 값이 너무 크면 단기 부하가 튄다. 이 키들은 비용보다 안정성과 직결된다.

결론 — 비용 절감을 위한 도입 가이드

Hermes의 보조 모델 슬롯은 세 단계로 다듬으면 된다.

현황 파악: hermes config show로 모든 auxiliary.*.provider가 auto인지 확인한다. auto가 많을수록 메인 모델이 잡일을 떠맡고 있다는 뜻이다.
고비용 슬롯부터 분리: vision과 compression처럼 호출량이 많고 비용 영향이 큰 슬롯을 OpenRouter 경유 Flash 계열로 옮긴다. 인터랙티브 모드 한 번이면 충분하다.
세부 슬롯과 Curator 정리: web_extract의 timeout, session_search의 max_concurrency, 그리고 Curator(auxiliary.curator)까지 작업 성격에 맞춰 손본다. 운영 환경에서 키 이름이 다르다면 공식 문서와 hermes config show 출력을 우선한다.

한 가지만 기억한다면 충분하다. Hermes는 보조 슬롯을 분리해 비용을 줄이도록 설계되었지만, 기본값은 그 분리를 하지 않는다. 그 한 줄짜리 격차를 메우는 게 이 글이 다룬 전부다.

참고자료

GPT Image2 이미지 잘 만드는 법 : GPT Image2로 한글 썸네일과 인포그래픽까지 끝내기(이미지 프롬프트 패턴, 예시 모음)

갓대희 — Wed, 29 Apr 2026 00:51:59 +0900

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

지난 글에서는 GPT Image 2를 API로 다루는 방법을 정리했다. 이번 글은 방향이 다르다. 코드 한 줄도 쓰지 않고, ChatGPT 채팅창만으로 이미지를 만드는 일반 사용자용 가이드다.

이미지 생성 도구는 많지만, 막상 써보면 비슷한 지점에서 막힌다. "예쁜 이미지 만들어줘"라고 했는데 결과물이 어색하다. 한글이 깨진다. 같은 인포그래픽 스타일을 두 번 다시 못 만든다. 이 막막함을 줄이는 가장 빠른 방법은 프롬프트의 구조를 패턴으로 익혀두는 것이다.

이 글은 그 패턴을 7가지 이미지 유형별로 정리한다. 각 유형마다 바로 복사해서 채팅창에 붙여 넣을 수 있는 템플릿을 함께 준비했다. 마지막 섹션에는 필자가 매일 trendshift.io의 GitHub 트렌딩 TOP25를 한 장의 인포그래픽으로 정리할 때 쓰는 워크플로우도 넣었다.

전편을 한 문장으로 요약하면 이렇다. GPT Image 2에서 체감되는 변화는 텍스트 렌더링, 세계 지식, 색상 정확도였다. 이번 글은 그 세 가지가 일반 사용자의 프롬프트 작성에서 어떻게 바로 체감되는지에 초점을 맞춘다.

지금 바이럴 중인 트렌드

사진 1장 + 프롬프트 1개 → 나만의 카카오톡 이모티콘 팩

이미지 생성 기능이 출시된 이후 한국 SNS를 중심으로 폭발적으로 퍼진 사용법이 있다. 본인 사진을 채팅창에 올리고 프롬프트 한 줄을 입력하면 16가지 표정의 이모티콘 시트가 완성된다.

ex) 원본사진 - ai로 만든 가상의 인물 사진

ex) 프롬프트 예시

첨부 사진 속 인물의 얼굴 특징(눈, 코, 입 위치, 얼굴형, 헤어스타일, 피부톤)을
정확히 유지하면서, 카카오톡 이모티콘 스타일 스티커 16종을 한 장의 이미지로 만들어줘.

[출력 사양]
- 비율: 1:1 정사각형, 해상도 1024×1024 이상
- 배치: 4행 × 4열 그리드, 16칸 모두 동일 인물
- 배경: 순수 흰색(#FFFFFF), 칸 사이 여백 충분히
- 각 캐릭터: 얼굴 중심 상반신, 흰색 외곽선(약 6px)으로 스티커 컷아웃 처리

[스타일]
- 실사 얼굴 특징을 유지한 세미 카툰 일러스트 (2D)
- 파스텔 톤 컬러 팔레트 (크림 베이지, 연한 핑크, 부드러운 민트, 채도 60% 이하)
- 따뜻하고 귀여운 분위기, 카카오 프렌즈 감성
- 표정마다 어울리는 미니 이모지(하트♥, 물방울 , 별★, 땀 , 번개⚡ 등) 1~2개씩 추가

[16칸 표정-텍스트 매핑] (좌상단부터 행 우선 순서)
1행: 
 (1,1) 귀엽게 삐진 표정 - "흥칫뿡!"
 (1,2) 귀엽게 침 뱉는 표정 - "퉤!"
 (1,3) 귀엽게 말 거는 표정 - "갓대희!"
 (1,4) 뾰루퉁한 표정 - "난 살쪄도 귀엽거든!"

2행:
 (2,1) 호통치는 표정 - "록쳐라!"
 (2,2) 환하게 웃는 표정 - "안녕!"
 (2,3) 우는 표정 - "힝 ㅠㅠ"
 (2,4) 졸린 표정 - "졸려요~"

3행:
 (3,1) 놀란 표정 - "우와!"
 (3,2) 멍한 표정 - "멍~"
 (3,3) 먹는 표정 - "냠냠~"
 (3,4) 사랑스러운 표정(하트 눈) - "좋아요!"

4행:
 (4,1) 화난 표정 - "크앙!"
 (4,2) 짜증난 표정 - "쳇!"
 (4,3) 당황한 표정(땀) - "응?"
 (4,4) 자신만만한 표정(반짝) - "반짝!"

[텍스트 스타일]
- 둥글고 통통한 한글 손글씨체
- 글자 색: 진한 갈색 또는 검정, 흰색 외곽선 2px
- 위치: 캐릭터 머리 위 또는 옆 빈 공간

[엄수 사항]
- 16칸 모든 캐릭터의 얼굴형/헤어/의상은 100% 동일, 표정만 변화
- 영문이 아닌 정확한 한글로 텍스트 렌더링
- 첨부 사진 속 인물의 핵심 얼굴 비율(눈 사이 거리, 코-입 거리, 얼굴 윤곽)은 그대로 유지

ex) 생성되는 사진 예시

이런 결과물을 만드는 프롬프트 구조, 커뮤니티에서 검증된 팁, 한글 텍스트 처리 방법을 다룬다.

GPT Image 2가 일반 사용자에게 의미하는 것
이미지 생성 시작하기 — ChatGPT에서 바로 쓰는 방법
이미지 유형별 프롬프트 가이드
한글 텍스트 잘 넣는 법
프롬프트 작성 핵심 원칙 5가지
대화형 편집 — 수정 요청하는 방법
실패 패턴과 해결법
실전 워크플로우 — 콘텐츠 제작 파이프라인
결론 — 이미지 유형 선택 가이드

1. GPT Image 2가 일반 사용자에게 의미하는 것

GPT Image 2(gpt-image-2)는 OpenAI가 2026년 4월 21일 공개한 ChatGPT 이미지 생성 모델이다(OpenAI 공식 발표). 모델 이름보다 먼저 봐야 할 것은 일반 사용자 입장에서 무엇이 달라졌느냐다.

조금 더 직설적으로 말하면, 이전 세대에서 자주 틀리던 부분이 한꺼번에 줄었다. 글자가 깨지고, 색이 노랗게 뜨고, 익숙한 UI가 어색하게 그려지던 지점들이다. 그래서 이번 모델은 "신기한 이미지 생성기"보다 "실제로 써먹을 수 있는 시각 도구"에 더 가까워졌다.

한글이 드디어 제대로 나온다

이전 모델에서 가장 답답했던 부분이다. 이미지 안에 한글을 넣으면 자모가 분리되거나, 비슷하게 생긴 다른 글자로 바뀌었다. GPT Image 2는 텍스트 렌더링이 대폭 향상되어 간판, 라벨, UI 화면 안의 한글이 실용 수준으로 정확해졌다. 한국어 콘텐츠를 만드는 입장에서는 체감 차이가 꽤 크다.

노란색 편향이 사라졌다

이전 모델은 흰 배경을 요청해도 결과물이 노랗게 뜨는 경향이 있었다. GPT Image 2에서는 색상 편향이 제거되어 흰 배경, 중성 색상, 다크 테마가 의도한 대로 나온다. "라이트 그레이 배경" 같은 미묘한 색상 지시도 따라온다.

실제 UI와 브랜드 외관을 안다

세계 지식이 강화되어 YouTube 플레이어, Windows 탐색기, iPhone 프레임 같은 실제 UI 요소를 자연스럽게 그린다. 가짜 비슷한 화면이 아니라, 실제 그 화면처럼 보이는 시안을 만든다.

대화로 수정할 수 있다

이전 이미지를 가리키며 "배경만 네이비로 바꿔줘", "오른쪽 항목 3개 추가해줘"처럼 자연어로 수정 요청이 가능하다. 기존에는 프롬프트를 통째로 다시 짜야 했던 작업이 한 줄로 끝난다.

결국 GPT Image 2의 일반 사용자용 가치는 네 가지로 압축된다. 한글 텍스트, 정확한 색상, 실제 UI 재현, 대화형 편집. 이 네 가지가 이 글의 프롬프트 패턴 전체를 받쳐준다.

2. 이미지 생성 시작하기 — ChatGPT에서 바로 쓰는 방법

시작은 어렵지 않다. ChatGPT에 로그인해서 채팅창에 한국어로 원하는 이미지를 설명하면 된다. 필요하면 사이드바의 More → Images 메뉴로 시작해도 된다(공식 도움말).

가장 짧은 형태는 이렇다.

강아지가 공원에서 뛰노는 수채화 스타일 이미지 만들어줘.

이 정도로도 결과물은 나오지만, 의도한 그림과는 거리가 있다. 이 글에서 다루는 모든 패턴의 출발점은 짧은 한 줄을 구조화된 프롬프트로 확장하는 것이다.

2026-04-28 기준 ChatGPT Images 2.0은 Free를 포함한 전 요금제에서 사용할 수 있다. 다만 생성 속도, 사용 한도, thinking 기반 이미지 같은 고급 기능 범위는 플랜별로 다르므로 공식 가격 페이지와 도움말에서 최신 기준을 확인하는 편이 확실하다.

ex)

3. 이미지 유형별 프롬프트 가이드

이제 유형별로 본다. 6가지 유형 모두 동일한 골격을 따른다. 목적 → 레이아웃 → 색상 → 텍스트 → 스타일. 이 순서로 채워 넣으면 결과물이 한결 안정적이다.

3-1. 인포그래픽 / 요약 카드

언제 쓰는가. 복잡한 정보를 한 장으로 압축할 때다. 뉴스레터 커버, 트렌드 정리, 블로그 헤더, 발표 슬라이드 단일 이미지 등에 잘 맞는다.

프롬프트 작성 핵심 포인트:

레이아웃 구조를 명시한다(예: 3열 그리드, 상-중-하 분할)
색상 팔레트를 2~3색으로 좁힌다
정보 위계를 글자 크기 순서로 지정한다
항목 수를 숫자로 못 박는다(5개 항목, 10개 카드)

GitHub 트렌딩 레포 TOP5를 한눈에 보여주는 인포그래픽을 만들어줘.

레이아웃: 1열 5행 카드 구조. 상단 타이틀 영역 별도.
배경: 짙은 네이비(#0d1b2a)
강조색: 민트 그린, 흰색
각 카드 구성: 좌측에 순위 번호(매우 크게), 우측에 레포 이름·한줄 설명·스타 수
폰트: 산세리프, 굵은 헤드라인
텍스트는 모두 한국어. 상단 타이틀에 [GitHub 트렌딩 TOP5] 라고 표기.

ex)

thinking모델 5.5 / pro 모델 5.5

Trendshift 스타일은 여기서 세 갈래로 더 확장할 수 있다. 같은 데이터를 놓고도 질문을 어떻게 던지느냐에 따라 이미지 성격이 달라진다. 하나는 오늘 뭐가 바뀌었는지, 하나는 그래서 무엇이 중요한지, 마지막 하나는 지금 어디에 베팅할지를 보여준다.

1) 전일 대비 델타 보드. 오늘 순위표만 보여주는 대신 New / 급상승 / 유지 / 이탈 네 칸으로 나누는 방식이다. "오늘 새로 들어온 것"과 "갑자기 치고 올라온 것"을 빠르게 보여주고 싶을 때 좋다.

오늘과 어제 데이터를 비교해서, 전일 대비 변화만 한눈에 보이는 델타 보드를 만들어줘.

주제: [Trendshift GitHub TOP25 전일 대비 변화]
형식: 한 장짜리 에디토리얼 인포그래픽

반드시 포함:
- 상단 제목 [오늘 무엇이 바뀌었나]
- 기준 날짜 [2026-04-29 vs 2026-04-28]
- 4개 모듈: New / 급상승 / 유지 / 이탈
- 각 모듈마다 대표 레포 3~5개
- 하단 한 줄 결론

레이아웃:
- 배경은 짙은 네이비
- 상단은 타이틀 영역
- 중앙은 2x2 모듈 그리드
- 각 모듈 헤더는 크게
- 레포 이름은 짧은 메모와 함께

디자인:
- 굵은 산세리프
- 흰색 텍스트 + 민트 / 노랑 / 빨강 포인트 컬러
- 뉴스룸 briefing board 느낌

주의:
- 전일 대비 수치가 없으면 임의 추정하지 말 것
- 날짜와 Source: Trendshift / GitHub 를 이미지 안에 넣을 것

ex)

2) 에디터 브리핑 보드. 이건 랭킹표보다 해석이 중심인 포맷이다. 메인 헤드라인 1개, 오늘의 핵심 흐름 3개, 에디터 픽 5개, 마지막 판단 1줄로 끝낸다. 본문 삽입용이나 SNS 공유용으로 특히 강하다.

오늘 데이터의 핵심만 해설하는 에디터 브리핑 보드를 만들어줘.

주제: [Trendshift GitHub TOP25]
목표: 오늘 꼭 봐야 할 흐름만 1장으로 요약

반드시 포함:
- 메인 타이틀 [Today’s Editor Brief]
- 서브타이틀 [2026-04-29 기준]
- 오늘의 핵심 흐름 3개
- 에디터 픽 5개
- 각 픽마다 한 줄 이유
- 하단 [오늘의 판단] 한 문장

레이아웃:
- 상단 20%는 제목 영역
- 좌측은 핵심 흐름 3개 세로 배치
- 우측은 에디터 픽 5개 카드형 정렬
- 하단은 전체 총평 밴드

스타일:
- 짙은 네이비 배경
- 흰색 텍스트
- 포인트 컬러는 청록과 형광 라임
- 편집장 메모처럼 날카로운 분위기
- 한국어 가독성 최우선

주의:
- 분류와 판단은 편집적 해석임을 드러낼 것
- 긴 설명 대신 짧은 판단 문장 위주로

ex)

thinking모델 5.5 / pro 모델 5.5

3) 기회 매트릭스. 이 포맷은 지금 써볼 것 / 더 지켜볼 것 / 과열 / 기반도구처럼 판단을 시각화한다. 단순 인기 순위보다 한 단계 더 해설적인 이미지가 필요할 때 잘 맞는다.

다음 데이터를 2x2 기회 매트릭스로 정리한 에디토리얼 인포그래픽을 만들어줘.

주제: [Trendshift GitHub TOP25]
목표: 화제성과 실사용 가능성을 기준으로 무엇을 지금 써볼지 정리

축:
- 가로축: 실사용 가능성 낮음 → 높음
- 세로축: 화제성 낮음 → 높음

반드시 포함:
- 2x2 매트릭스
- 각 사분면 이름 [지금 써볼 것 / 지켜볼 것 / 과열 / 기반도구]
- 대표 레포 8~12개
- 우측에 해석 메모
- 하단 한 줄 결론

레이아웃:
- 중앙에 큰 quadrant chart
- 핵심 레포는 크게, 주변 레포는 작게
- 우측 좁은 컬럼에 해석 메모

디자인:
- dark navy background
- bold sans-serif
- 흰색 본문 + 주황 / 청록 포인트
- 데이터 저널리즘 포스터 느낌

주의:
- 근거 없는 점수 추정은 하지 말 것
- 사용자가 준 원본 데이터 범위 안에서만 배치할 것
- Source와 날짜를 반드시 표기할 것

ex)

이 세 가지를 쓸 때 공통 주의점도 있다. 날짜와 출처를 이미지 안에 반드시 넣고, 분류와 판단은 어디까지나 편집적 해석이라는 점을 드러내야 한다. 텍스트를 욕심내서 많이 넣기보다, 실명 레포 8~12개 정도 선에서 끊는 편이 결과가 더 안정적이다.

3-2. SNS 콘텐츠 카드 / 카드뉴스 (X / Threads / Instagram / LinkedIn)

언제 쓰는가. X(트위터), Threads, Instagram, LinkedIn 같은 플랫폼에 공유할 이미지를 만들 때다. 여기서는 한 장짜리 카드뿐 아니라, 여러 장으로 넘기는 카드뉴스/캐러셀도 함께 본다.

프롬프트 작성 핵심 포인트:

플랫폼명을 명시한다(X, Threads, Instagram, LinkedIn)
비율을 지정한다(1:1, 4:5, 16:9, 9:16)
텍스트 오버레이의 위치와 크기를 정한다
플랫폼 톤에 맞춘 디자인 스타일을 짚는다

지금 많이 쓰는 포맷 — 카드뉴스 / 캐러셀. 2026년 3월 Buffer가 공개한 5,200만+ 포스트 분석에 따르면 Instagram에서는 캐러셀이 단일 이미지나 릴스보다 참여율이 높았고, LinkedIn에서도 캐러셀이 가장 강한 포맷으로 집계됐다(Buffer 리포트). LinkedIn 공식 도움말도 문서 포스트를 지식 공유, 인사이트, 트렌드 정리에 적합한 포맷으로 안내한다(LinkedIn Help).

다만 여기서 바로 오해가 생긴다. 카드뉴스는 ChatGPT 이미지 한 장으로 끝나는 포맷이 아니라, 여러 장의 템플릿을 일관되게 운영하는 포맷이다. ChatGPT는 커버, 비주얼 콘셉트, 짧은 문장 위주의 슬라이드에는 강하지만, 긴 문장을 많이 넣는 6~10장짜리 덱을 한 번에 정확하게 뽑는 데는 여전히 약하다. 그래서 초안 생성은 ChatGPT, 최종 조립은 Canva/PPT/Figma로 나누는 편이 안정적이다.

Instagram 카드뉴스용 프롬프트:

인스타그램 4:5 카드뉴스 캐러셀용 시안을 만들어줘.

주제: [ChatGPT 이미지 프롬프트에서 자주 하는 실수 5가지]
목적: 저장해두고 다시 보는 교육형 카드뉴스
출력 방식: 먼저 1장 표지와 2장 본문 시안만 만들고, 내가 확인하면 같은 스타일로 다음 장을 이어서 만든다.

슬라이드 구성:
1장 - 강한 제목 훅 [ChatGPT 이미지, 이렇게 시키면 망한다]
2장 - 실수 1 [한 장에 너무 많은 요소 넣기]
3장 - 실수 2 [긴 문장 통째로 넣기]

디자인:
- 비율 4:5, 인스타그램 피드 최적화
- 핵심 정보는 중앙 3:4 안전 영역 안에 배치
- 배경은 아이보리, 텍스트는 검정, 포인트 컬러는 형광 오렌지
- 각 장마다 동일한 상단 라벨과 하단 페이지 번호
- 텍스트는 장당 한 문장 + 키워드 3개 이내
- 한국어, 굵은 산세리프, 에디토리얼 매거진 느낌

중요:
- 한 장에 텍스트를 많이 넣지 말 것
- 모든 장이 같은 템플릿 시스템을 유지할 것

ex)

thinking모델 5.5 / pro 모델 5.5

LinkedIn 문서형 캐러셀 프롬프트:

링크드인 문서형 캐러셀에 들어갈 표지와 핵심 슬라이드 시안을 만들어줘.

주제: [AI 이미지 프롬프트 품질을 높이는 5가지 규칙]
목적: 지식 공유용 LinkedIn document carousel
출력: 표지 1장 + 본문 3장 시안

슬라이드 구성:
1장 - 제목 [AI 이미지 프롬프트 5원칙]
2장 - 원칙 1, 2
3장 - 원칙 3, 4
4장 - 원칙 5 + 마무리 한 줄

디자인:
- 차분한 화이트 배경, 네이비 헤더, 포인트 컬러는 민트
- 텍스트는 짧은 bullet 위주
- 각 장 좌상단에 같은 섹션 라벨 유지
- 비즈니스 문서처럼 깔끔하고 과장 없는 톤
- 한국어, 가독성 최우선

중요:
- 최종 업로드는 PDF 문서형 캐러셀로 쓸 예정
- 긴 문단 대신 짧은 항목 중심으로 구성

전후 비교 proof 카드. 이 포맷은 프롬프트 차이를 가장 빨리 납득시키는 방식이다. "왜 구조화된 프롬프트가 더 좋은가"를 길게 설명하는 대신, 같은 주제를 Before와 After로 나눠 보여주면 된다. 여기서 핵심은 같은 대상, 같은 구도, 같은 거리감을 유지하는 것이다.

구조화 전후를 보여주는 Before / After proof 카드를 만들어줘.

주제: [모호한 프롬프트 vs 구조화된 프롬프트]
형식: 4:5 비교 카드 1장

구성:
- 왼쪽은 Before
- 오른쪽은 After
- 같은 대상, 같은 앵글, 같은 거리감 유지
- 중앙에 얇은 구분선

Before 설명:
- 프롬프트가 모호해서 결과가 흐릿하고 산만한 상태
- 색감은 탁하고 정보 위계가 약함

After 설명:
- 목적, 레이아웃, 색상, 텍스트를 구체적으로 지정한 뒤 더 정돈된 상태
- 색 대비가 선명하고 핵심 요소가 또렷함

텍스트:
- 상단에 [Before / After] 라벨만 간단히
- 긴 설명 문장은 넣지 말 것

스타일:
- SNS 공유용
- 현실적인 차이가 분명히 보이게
- 과한 화살표나 장식 없이 에디토리얼 비교 보드 느낌

ex)

thinking모델 5.5 / pro 모델 5.5

X(트위터)용 기술 팁 카드:

X(트위터) 포스트용 기술 팁 카드 이미지 만들어줘.

비율: 1:1 정사각형
배경: 진한 보라색(#3b1e6e) 그라디언트
상단: 작은 카테고리 태그 [#AI #개발] (작게)
중앙: 핵심 팁 텍스트 [Claude Code의 /resume 명령으로 어제 작업을 그대로 이어가자] (한국어, 크고 굵게)
하단: 계정명 [@goddaehee] (작게)
스타일: 미니멀, 현대적, 여백 충분히

ex)

thinking모델 5.5 / pro 모델 5.5

Threads용 인용 카드:

Threads 공유용 인용 카드 이미지 만들어줘.

비율: 1:1
배경: 크림색(#faf6ef)
중앙 상단: 대형 따옴표 기호(연한 회색)
중앙: 인용 문구 [코드를 짜기 전에, 프롬프트부터 정리하라] (한국어)
하단 우측: 출처 [— 갓대희]
스타일: 깔끔한 타이포그래피 중심, 장식 최소화

ex)

thinking모델 5.5 / pro 모델 5.5

Reddit 포스트용 비교형 이미지:

Reddit r/programming 포스트용 비교 이미지 만들어줘.

비율: 16:9
상단: 영어 제목 [Before vs After: Claude Code 도입 30일]
중앙: 2열 비교표
  좌측 열 헤더: Before (회색 배경)
  우측 열 헤더: After (초록 배경)
  각 열에 5개 항목
배경: 라이트 테마(흰색)
폰트: 가독성 높은 산세리프

ex)

thinking모델 5.5 / pro 모델 5.5

플랫폼별로 비율을 다르게 두는 이유도 분명하다. X와 Threads는 모바일 타임라인에서 정사각형이 잘 보이고, Instagram 카드뉴스는 4:5가 무난하며, Reddit은 데스크톱 사용자가 많아 가로형이 잘 읽힌다. 프롬프트에 플랫폼명과 비율을 함께 넣어두면 모델이 분위기까지 그쪽에 맞춰준다.

3-3. 기술 다이어그램 / 아키텍처

언제 쓰는가. 시스템 구조, 데이터 흐름, 컴포넌트 관계를 시각화할 때다. 블로그 본문 중간에 이해를 돕는 그림으로 자주 쓴다.

프롬프트 작성 핵심 포인트:

다이어그램 유형을 명시한다(플로우차트, 시퀀스, 아키텍처, 마인드맵)
구성 요소와 화살표 흐름을 문장으로 풀어 쓴다
박스 모양과 색상 톤을 지정한다

마이크로서비스 아키텍처 다이어그램 이미지 만들어줘.

유형: 아키텍처 다이어그램
배경: 흰색
구성:
  상단 — 클라이언트 영역(모바일 아이콘 + 웹 브라우저 아이콘)
  중앙 — API Gateway(가운데 큰 박스)
  하단 — 3개 서비스 박스 병렬 배치(User Service / Order Service / Payment Service)
  각 서비스 아래 — 개별 데이터베이스 아이콘(원통형) 연결
화살표: 클라이언트 → Gateway → 각 서비스 → DB 흐름 표시
박스 스타일: 둥근 모서리, 옅은 파랑 채움, 짙은 파랑 테두리
화살표: 회색
레이블: 한국어

다이어그램은 글로 적은 흐름을 모델이 좌표로 옮기는 작업이라 위치 표현(상단, 중앙, 하단, 좌측, 우측)이 결과에 큰 영향을 준다. "병렬 배치", "트리 구조", "원형 배치" 같은 형태 키워드도 잘 먹힌다.

ex)

thinking모델 5.5 / pro 모델 5.5

3-4. UI 목업 / 와이어프레임

언제 쓰는가. 앱이나 웹 화면 시안을 빠르게 만들 때다. 기획안 첨부, 블로그 설명용 가짜 화면, 발표 자료에 자주 쓴다.

프롬프트 작성 핵심 포인트:

디바이스 프레임을 명시한다(iPhone 14 Pro, 안드로이드, 1440px 데스크톱 등)
UI 영역을 헤더/콘텐츠/푸터로 나눠 설명한다
컬러 테마를 결정한다(라이트/다크, 포인트 컬러)

모바일 앱 목업:

iPhone 14 Pro 프레임 안의 할 일 관리 앱 UI 목업 이미지 만들어줘.

상단 헤더: [오늘의 할 일] 타이틀 + 작은 날짜 텍스트
중앙: 카드형 할 일 목록 5개. 각 카드는 [체크박스 + 할 일 텍스트 + 우선순위 태그]
하단 탭바: 3개 탭 [홈 / 캘린더 / 설정], 가운데 [+] 플로팅 버튼
테마: 라이트
포인트 컬러: 파란색
한국어 텍스트

ex)

thinking모델 5.5 / pro 모델 5.5

웹 대시보드 목업:

SaaS 대시보드 웹 UI 목업 이미지 만들어줘.

해상도: 1440px 와이드스크린
좌측 사이드바: 네비게이션 메뉴 5개 [대시보드 / 사용자 / 매출 / 분석 / 설정]
중앙 상단: KPI 카드 4개 가로 배치 [방문자 / 전환율 / 매출 / 활성사용자]
중앙 하단: 라인 차트 1개(월별 추이)
테마: 다크
포인트 컬러: 퍼플
한국어 레이블

ex)

디바이스 프레임을 빼면 결과물이 이미지인지 화면인지 모호해진다. 명시적으로 "iPhone 14 Pro 프레임 안에", "1440px 데스크톱 브라우저"라고 못 박아두면 모델이 알아서 베젤과 상태바까지 그려준다.

3-5. 비교표 / 데이터 시각화

언제 쓰는가. 도구나 서비스를 한 화면에서 비교할 때다. 블로그 비교 글, 의사결정 자료, 트윗에 끼우는 요약 카드에 잘 맞는다.

프롬프트 작성 핵심 포인트:

비교 항목과 행/열 구조를 정확히 적는다
헤더 행 강조 색상을 지정한다
셀 표시 방식(텍스트, 체크/엑스 마크, 별점 등)을 정한다

AI 코딩 도구 3가지 비교표 이미지 만들어줘.

배경: 흰색
표 구조: 4행 3열
열 헤더: GitHub Copilot / Cursor / Claude Code (헤더 행은 짙은 네이비 배경 + 흰색 텍스트)
행 항목:
  1행: 가격
  2행: 주요 강점
  3행: 한국어 지원
  4행: 추천 사용자
셀 표시: 짧은 텍스트
홀수 행 배경: 연한 회색
폰트: 가독성 높은 산세리프
한국어

ex)

thinking모델 5.5 / pro 모델 5.5

막대 차트 스타일:

2025-2026년 주요 AI 모델 출시 타임라인 가로 바 차트 이미지 만들어줘.

배경: 흰색
좌측: 모델명 6개 세로 정렬
우측: 각 모델의 출시 시점 가로 바
색상: 모델마다 다른 파스텔 톤
상단: 제목 [AI 모델 출시 타임라인 2025-2026]
하단: X축 — 분기 표시(Q1 2025 ~ Q4 2026)
한국어 레이블

ex)

thinking모델 5.5 / pro 모델 5.5

표 형태 이미지에서 가장 자주 깨지는 부분이 셀 안의 텍스트다. 한 셀에 긴 문장을 넣으면 줄바꿈이 어색해진다. 셀 안에는 짧은 키워드, 별점, 체크 마크 위주로 채우고, 긴 설명은 표 아래 별도 영역에 두는 편이 안정적이다.

3-6. 블로그 썸네일 / 브랜딩

언제 쓰는가. 블로그 헤더, 유튜브 썸네일, 채널 아트 등 시각적 임팩트가 필요한 자리에 쓴다.

프롬프트 작성 핵심 포인트:

비율을 매체별로 맞춘다(블로그 썸네일 16:9, 유튜브 채널 아트 2560x1440)
제목 텍스트를 정확히 적어준다
분위기 키워드를 명시한다(전문적, 캐주얼, 미니멀, 빈티지)

기술 블로그 썸네일 이미지 만들어줘.

비율: 16:9
배경: 짙은 네이비에서 퍼플로 이어지는 그라디언트
중앙: 큰 제목 텍스트 [GPT Image 2 완전 가이드] (굵은 산세리프, 한국어)
중앙 하단: 부제목 [일반 사용자를 위한 프롬프트 가이드] (작게)
좌측 상단: 워터마크 [goddaehee.tistory.com] (얇은 텍스트)
분위기: 전문적, 모던, 약간의 광택감

ex)

에디토리얼 커버 포스터. 썸네일보다 한 단계 더 분위기 중심인 포맷이다. 블로그 대표 이미지, 브런치 커버, 세미나 공지, 전자책 표지처럼 "한 장으로 첫인상을 잡는" 상황에 잘 맞는다. 텍스트는 짧게, 오브제는 크게, 여백은 넓게 가져가는 편이 좋다.

[주제]를 소개하는 에디토리얼 커버 포스터를 만들어줘.

용도: [블로그 대표 이미지 / 브런치 커버 / 세미나 공지]
비율: 4:5 세로형

구성:
- 화면 중심에 핵심 오브제 1개 또는 인물 1명
- 큰 제목 1개
- 작은 보조 문구 1줄
- 넓은 여백
- 명확한 타이포 위계

분위기:
- 하이엔드 매거진 표지 느낌
- 종이 질감이나 필름 그레인 약하게
- 채도는 절제, 포인트 컬러만 강하게

중요:
- 긴 문장은 넣지 말 것
- 스톡 이미지 광고처럼 보이지 말 것
- 세련된 현대 에디토리얼 커버처럼 보여줄 것

ex)

무드보드 / 소재 팔레트 시트. 이건 일반 사용자도 가장 쉽게 "전문가처럼 보이는 결과물"을 얻는 포맷이다. 브랜딩, 인테리어, 패션, 유튜브 채널 리뉴얼처럼 취향과 방향성을 먼저 맞춰야 할 때 특히 강하다.

[프로젝트 주제]를 위한 무드보드 시트를 만들어줘.

예: [카페 브랜딩], [침실 인테리어], [가을 룩북], [유튜브 채널 리뉴얼]
비율: A4 세로형 또는 4:5

구성:
- 6~9개의 이미지 조각을 감각적으로 배치
- 컬러 스와치 4~6개
- 소재/무드 키워드 3~5개만 짧게 표기

톤앤매너:
- [차분한 프렌치 에디토리얼 / 따뜻한 필름 무드 / 미래적이지만 절제된 미감]
- 메인 컬러는 [색상 조합]
- 재질감은 [리넨 / 크롬 / 유광 종이 / 원목 / 유리]

중요:
- 핀터레스트 스크랩처럼 산만하지 말 것
- 하나의 브랜드 방향서처럼 정리된 느낌으로
- 텍스트보다 색감과 질감 중심으로 보여줄 것

ex)

thinking모델 5.5 / pro 모델 5.5

브랜드 로고가 들어간 썸네일은 까다롭다. 특정 회사 로고(애플, 구글, OpenAI 등)를 그대로 그려달라고 하면 거절될 가능성이 있다. 유사 스타일의 추상 아이콘으로 우회하거나, 로고 자리는 비워두고 실제 로고는 사후 편집기에서 합치는 방식이 무난하다.

3-7. 개인화 이모티콘 스티커 시트 (카카오톡 / WhatsApp 스타일)

언제 쓰는가. 본인 또는 가족·지인 사진을 카카오톡 이모티콘 스타일의 스티커 시트로 변환할 때다. 단톡방용 개인 이모티콘, SNS 바이럴 콘텐츠, 유튜브 채널 굿즈 기획 초안 등 앞서 다룬 6가지 포맷과 완전히 다른 목적을 가진다.

왜 지금 유행하는가. 2025년 3월 25일 GPT-4o 네이티브 이미지 생성이 출시된 이후 첫 주에만 전 세계 1억 3,000만 명이 7억 장 이상의 이미지를 생성했다(OpenAI 발표). 지브리 스타일 변환이 먼저 바이럴된 뒤, 한국 커뮤니티에서는 카카오톡 이모티콘 생성으로 트렌드가 이동했다. 2025년 4월에는 국내 언론 보도(아이뉴스24, 2025-04-03)가 나올 정도로 화제가 됐다. 규모를 가늠할 수 있는 수치가 있다. 카카오톡 이모티콘 시장은 2024년 말 기준 약 1조 2,000억 원, 누적 발신량은 2,800억 건에 달한다.

기존 AI 사진 변환 서비스와 무엇이 다른가. 2022년 Lensa AI '매직 아바타'가 바이럴됐을 때는 사진 10~20장을 올리고 며칠 기다려야 했고, 결과물을 수정할 수 없었다. ChatGPT는 사진 1장이면 충분하고, "눈을 더 크게 해줘", "표정을 더 강하게 해줘"처럼 대화로 즉시 수정된다. 별도 앱 설치 없이 기존 ChatGPT 인터페이스에서 바로 가능하다는 점도 진입 장벽을 낮췄다.

커뮤니티 반응 — 실제로 어떻게 쓰이고 있나.

Threads @choi.openai: "이미지를 챗GPT에 입력하는 것만으로도 카카오톡 이모티콘이 완성된다니... 너무 놀랍네요" — 수천 개 공유
Threads @gpt_kimisa: "10초만에 나만의 이모티콘 만들기, 챗gpt에 이 프롬프트만 붙여 넣으면 끝!"
X @MayorKingAI: "Create your own chibi stickers using ChatGPT for WhatsApp" — 프롬프트 공유와 함께 바이럴
국내 브런치에서는 아기·자녀 사진 이모티콘 제작 후기가 다수 공유됨(브런치, 2025-04-14)

프롬프트 작성 핵심 포인트:

사진을 먼저 첨부하고 프롬프트를 입력한다
그리드 규격을 명시한다 (4×4, 16칸, 1:1 정사각형)
"카카오톡 이모티콘 스타일", "카카오 프렌즈 감성" 키워드를 참조로 넣는다
표정 목록을 하나씩 열거하면 누락이 줄어든다
흰색 외곽선(white outline, 약 6px)을 지정하면 스티커 컷아웃 느낌이 산다
한글 텍스트는 짧게(2~4자), 위치를 명시한다
얼굴 비율 고정 지시를 반드시 포함한다 ("얼굴형·헤어·의상 100% 동일, 표정만 변화")

[첨부 사진 속 인물]을 기반으로 카카오톡 이모티콘 스타일 스티커 16종을 한 장에 만들어줘.

[출력 사양]
- 비율: 1:1 정사각형, 해상도 1024×1024 이상
- 배치: 4행 × 4열 그리드, 16칸 모두 동일 인물
- 배경: 순수 흰색(#FFFFFF), 칸 사이 여백 충분히
- 각 캐릭터: 얼굴 중심 상반신, 흰색 외곽선(약 6px)으로 스티커 컷아웃 처리

[스타일]
- 실사 얼굴 특징을 유지한 세미 카툰 일러스트 (2D)
- 파스텔 톤 컬러 팔레트 (크림 베이지, 연한 핑크, 부드러운 민트, 채도 60% 이하)
- 따뜻하고 귀여운 분위기, 카카오 프렌즈 감성
- 표정마다 어울리는 미니 이모지(하트, 물방울, 별, 땀, 번개 등) 1~2개씩 추가

[16칸 표정 배치] (좌상단부터 행 우선)
1행: 귀엽게 삐진 "흥칫뿡!" / 혀 내미는 "퉤!" / 말 거는 "안녕!" / 뾰루퉁한 "살쪄도 귀엽거든!"
2행: 호통치는 "롹쳐라!" / 환하게 웃는 "반가워!" / 우는 "힝 ㅠㅠ" / 졸린 "졸려요~"
3행: 놀란 "우와!" / 멍한 "멍~" / 먹는 "냠냠~" / 하트눈 "좋아요!"
4행: 화난 "크앙!" / 짜증난 "쳇!" / 당황한 "응?" / 자신만만한 "반짝!"

[텍스트 스타일]
- 둥글고 통통한 손글씨체
- 진한 갈색 또는 검정, 흰색 외곽선 2px
- 위치: 캐릭터 머리 위 또는 옆 빈 공간

[엄수 사항]
- 16칸 모든 캐릭터의 얼굴형/헤어/의상은 100% 동일, 표정만 변화
- 첨부 사진 속 인물의 핵심 얼굴 비율(눈 위치, 코-입 거리, 얼굴 윤곽)은 그대로 유지

ex)

⚠️ 알아두어야 할 한계 3가지

① 한글 텍스트가 깨질 수 있다. GPT-4o가 한국어 글자를 픽셀 패턴으로 처리하는 경향이 있어 이모티콘 안의 한글이 변형되거나 빠질 수 있다. 해결법: Canva나 파워포인트에서 둥근 손글씨 폰트(어비세현체 Bold, 배민 도현체 등)를 직접 덧씌운다. 커뮤니티에서 가장 많이 검증된 방식이다.

② 16칸 그리드 내 얼굴 일관성이 흔들릴 수 있다. 칸마다 머리카락 색이나 옷 색상이 미묘하게 달라질 수 있다. 실제 사용자 사례에서 32개 생성 시 최종 완성이 9개(28%)에 그친 경우도 보고됐다. 칸을 4~8개씩 나눠 생성하거나, 문제 칸만 재생성을 요청하는 편이 낫다.

③ 카카오 이모티콘샵 공식 입점은 불가하다. 카카오는 2023년 9월부터 생성형 AI를 활용한 이모티콘의 공식 판매를 제한하며 2025년 현재도 유지 중이다(아이뉴스24). 개인 단톡방 사용과 SNS 공유에는 제한이 없다.

반대로 여기서 일부러 늘리지 않은 포맷도 있다. 명언 카드, 체크리스트 카드, 마인드맵은 겉보기에 새로워 보여도 지금 글 안에서는 각각 SNS 카드, 카드뉴스, 다이어그램과 경계가 많이 겹친다. 유형 수를 늘리기보다, 실제로 다른 결과를 만드는 포맷만 남기는 편이 낫다.

4. 한글 텍스트 잘 넣는 법

GPT Image 2에서 눈에 띄는 장점이 한글 렌더링 개선이지만, 그렇다고 아무렇게나 적어도 잘 나오는 것은 아니다. 한글이 깨끗하게 들어가는 프롬프트에는 공통 패턴이 있다.

텍스트는 따옴표나 대괄호로 감싼다

프롬프트 안에서 어디까지가 이미지에 들어갈 텍스트인지 모델이 헷갈리지 않도록, 들어가야 할 문구를 [ ] 또는 " "로 감싼다. "중앙에 '오늘의 개발 팁'이라고 크게"보다 "중앙에 [오늘의 개발 팁] 텍스트를 크게"가 더 잘 먹힌다.

폰트 스타일을 지정한다

"굵은 산세리프", "가는 명조체", "손글씨 스타일" 같은 키워드를 함께 넣으면 텍스트의 느낌이 의도와 가까워진다. 한글 폰트의 특정 이름(예: 나눔고딕, 본명조)은 모델이 인식하기 어려워 일반적인 스타일 키워드로 적는 편이 낫다.

글자 크기 위계를 명시한다

"제목 크게, 본문 작게" 정도로는 부족하다. "제목은 본문의 3배 크기", "헤드라인 48px 스타일, 본문 14px 스타일"처럼 비율이나 픽셀 기준 키워드를 적으면 결과물의 위계가 명확해진다.

카카오톡 스타일 알림 카드 이미지 만들어줘.

배경: 노란색
중앙 상단: 큰 제목 [Claude Sonnet 4.6 출시] (굵은 산세리프, 본문의 3배 크기)
중앙 하단: 부제목 [더 빠르고 정확해진 AI 코딩 도구] (보통 두께)
하단 우측: 작은 날짜 [2026-04-28]
모두 한국어

5. 프롬프트 작성 핵심 원칙 5가지

어떤 유형이든 공통으로 적용되는 원칙이다. 이 다섯 가지만 기억해도 프롬프트 품질이 눈에 띄게 좋아진다.

① 구체적으로 적는다. "예쁜 이미지"는 아무것도 아니다. 색, 크기, 위치, 항목 수까지 숫자와 명사로 적는다. "라이트 민트색 배경, 중앙에 큰 아이콘 1개, 하단에 설명 텍스트 2줄" 정도가 출발선이다.

② 스타일 키워드를 넣는다. "미니멀", "플랫 디자인", "3D 렌더링", "수채화", "픽셀아트", "일러스트레이션" 같은 단어 한두 개가 톤 전체를 결정한다.

③ 비율과 크기를 지정한다. "1:1 정사각형", "16:9 가로형", "9:16 세로형(스토리/릴스)". 어디에 쓸 이미지인지에 따라 골라 쓴다.

④ 색상은 이름이나 코드로 못 박는다. "파란색"보다 "네이비"가, "네이비"보다 "#0d1b2a"가 더 정확하다. 톤이 중요한 작업이면 헥스 코드로 적는다.

⑤ 이미지 안에 들어갈 텍스트는 따옴표나 대괄호로 감싼다. 프롬프트 설명 문장과 실제 이미지 텍스트가 구분되어 모델이 덜 헷갈린다.

다섯 원칙을 한 문장으로 묶으면 이렇다. "무엇을, 어떤 스타일로, 어떤 비율과 색에, 어떤 텍스트와 함께". 이 네 축이 빠짐없이 들어 있는 프롬프트는 결과물의 70% 이상을 1차 시도에서 잡아낸다.

6. 대화형 편집 — 수정 요청하는 방법

GPT Image 2는 대화 맥락을 기억한다. 방금 만든 이미지에 대해 자연어로 수정을 요청하면 된다. 처음부터 다시 짜는 것보다 빠르고, 일관성도 유지된다.

자주 쓰는 수정 요청 패턴이다.

방금 만든 이미지에서 배경색을 네이비로 바꿔줘.
텍스트를 한국어로 바꿔줘.
오른쪽 열에 항목 3개 더 추가해줘.
전체적으로 더 미니멀하게, 불필요한 장식 제거해줘.
상단 타이틀을 [2026년 AI 트렌드]로 바꿔줘.
폰트를 더 굵게, 가독성 높게 바꿔줘.

한 가지 주의할 점이 있다. 대화가 너무 길어지면 모델이 초기 맥락을 흐리기 시작한다. 수정이 5~6번을 넘어가는데도 의도와 멀어진다면, 새 대화창을 열어 처음부터 정리한 프롬프트로 다시 만드는 편이 낫다. 잘 나온 이미지가 다음 시도에서 그대로 나오지 않을 수도 있다는 점도 감안한다.

7. 실패 패턴과 해결법

직접 수십 장을 만들어보면 비슷한 실패 패턴이 반복된다. 자주 마주치는 세 가지와 해결법을 정리한다.

패턴 1 — 너무 많은 요소를 욱여넣었다

한 이미지에 10개 이상의 서로 다른 요소를 넣으면 레이아웃이 무너진다. 항목이 겹치거나, 텍스트가 박스 밖으로 빠져나가거나, 의도하지 않은 빈 공간이 생긴다. 이럴 때는 핵심 3~5개로 줄이거나, 여러 장으로 나누는 편이 낫다. 한 장에 다 담으려는 욕심이 가장 흔한 실패의 원인이다.

패턴 2 — 긴 문장을 이미지 안에 넣었다

이미지 안에 두세 문장 이상을 넣으면 중간에 글자가 깨지거나, 줄바꿈이 어색해진다. 한글 렌더링이 좋아졌다고 해도, 긴 문단을 깨끗하게 그려내는 일은 여전히 다른 차원이다. 이미지에는 짧은 키워드와 슬로건 위주로 넣고, 긴 설명은 캡션이나 본문 텍스트로 분리한다.

패턴 3 — 특정 브랜드 로고를 그대로 그려달라고 했다

세 패턴에서 공통으로 보이는 점이 있다. 생성형 이미지는 한 번에 너무 많은 일을 시키면 바로 흔들린다. 한 이미지의 역할을 좁히고, 부족한 부분은 여러 장이나 사후 편집으로 메우는 쪽이 대체로 더 깔끔하다.

8. 실전 워크플로우 — 콘텐츠 제작 파이프라인

지금까지의 내용을 실제 운영에 어떻게 녹이는지 정리한다. SNS 운영자, 블로거, 뉴스레터 작성자에게 그대로 적용되는 주간 워크플로우다.

단계 1 — 주제 수집

뉴스, 한국 개발 커뮤니티(GeekNews 등), trendshift.io 등 에서 그날의 화제 거리를 모은다. 이 단계는 이미지 생성과 무관하지만, 좋은 인풋 없이는 좋은 이미지도 없다.

단계 2 — ChatGPT에 정리 요청

수집한 원본을 ChatGPT 채팅창에 그대로 붙여 넣고, 분류와 요약을 시킨다. 이 단계의 출력은 이미지가 아니라 구조화된 텍스트다.

Trendshift처럼 랭킹 데이터를 다룰 때는 순서도 중요하다. 원본 랭킹과 날짜를 먼저 붙여 넣고, 해석은 그다음 시키는 편이 낫다. 순서를 거꾸로 두면 모델이 근거 없는 변화량이나 판단 문구를 먼저 만들어버릴 수 있다.

단계 3 — 이미지 프롬프트로 전환

같은 대화창에서 "이 내용을 인포그래픽으로 만들어줘"라고 요청한다. 앞 단계에서 정리한 텍스트가 자동으로 프롬프트 재료가 된다.

단계 4 — 대화형 수정

1차 결과물을 보고 색상, 레이아웃, 텍스트를 자연어로 다듬는다. 보통 2~3회 수정으로 발행 가능한 수준이 된다.

단계 5 — 저장과 배포

최종 이미지를 저장하고 SNS, 블로그, 뉴스레터에 게시한다. 같은 콘텐츠를 X용 1:1, 블로그용 16:9, 인스타용 9:16로 변형해두면 멀티 채널 배포가 쉬워진다.

매일 같은 시리즈(예: Trendshift TOP25 해설판)를 운영한다면, 한 번 잘 만든 프롬프트 템플릿을 메모장에 저장해두고 날짜와 내용만 갈아 끼우는 방식으로 반복 작업을 꽤 많이 줄일 수 있다. 필자는 이 방식으로 매일 1장의 요약 카드를 빠르게 정리한다.

9. 결론 — 이미지 유형 선택 가이드

어떤 유형의 이미지를 만들지부터 헷갈린다면, 목적에 따라 고르는 매트릭스를 참고한다.

목적	추천 유형	비율 기본값
복잡한 정보를 한 장으로 요약	인포그래픽 / 요약 카드	1:1 또는 4:5
SNS 바이럴 콘텐츠	SNS 카드(플랫폼별)	1:1, 16:9, 9:16
기술 개념 설명	다이어그램 / 아키텍처	16:9
제품/서비스 시안	UI 목업	디바이스 비율
도구 비교, 의사결정 자료	비교표 / 데이터 시각화	16:9
블로그 헤더, 유튜브 썸네일	썸네일 / 브랜딩	16:9, 2560x1440
개인 SNS · 단톡방 이모티콘	개인화 이모티콘 스티커 시트	1:1 (1024×1024)

활용도가 가장 높은 조합은 인포그래픽 + SNS 카드다. 같은 정보를 두 포맷으로 만들어 멀티 채널에 동시에 올리면 재활용 폭이 넓다.

이미지 생성은 더 이상 디자이너만의 영역만은 아니다. 코드를 모르는 사용자도 ChatGPT 채팅창 하나로 매일 올릴 콘텐츠를 만들 수 있다. 결국 오래 가는 차이는 도구보다 프롬프트 구조를 얼마나 빨리 자기 것으로 만드느냐에서 나온다. 이 글의 6가지 패턴을 메모장에 저장해두고 한 주만 써봐도, 다음부터는 빈 캔버스 앞에서 덜 망설이게 된다.

참고 자료

Claude Opus 4.7 설정 최적화 - 달라진 것, 주의할 것, 지금 바꿀 것 (effort 레벨부터 Extended Thinking 등)

갓대희 — Sun, 26 Apr 2026 22:40:17 +0900

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

Claude Code를 Opus 4.7가 출시되었다. 해당 출시소식을 아주 간단히 살펴보고, Anthropic이 직접 공개한 Opus 4.7 베스트 프랙티스 가이드와 모델 카드, Claude Code 공식 문서를 바탕으로 "왜 느려졌는지", "무엇을 어떻게 바꿔야 하는지"를 정리한다.

effort 레벨 완전 해부, 첫 턴 프롬팅 전략, 사고 깊이 제어, auto mode, Extended Thinking 마이그레이션, 서브에이전트 명시까지 — 2026-04-16 Anthropic 공식 가이드 기준으로 한 번에 정리해 보자.

▸ Opus 4.7 출시 개요 — 무엇이 달라졌나

왜 갑자기 느려졌나
무엇이 바뀌었나 — Opus 4.7의 핵심 변화
effort 레벨 완전 해부 (xhigh 신규 단계 포함)
첫 턴 프롬팅 전략
사고 깊이 제어하기
auto mode와 토큰 효율화
Extended Thinking 마이그레이션 주의사항
서브에이전트 — 명시하지 않으면 안 한다
즉시 적용 체크리스트
트러블슈팅 Q&A

Opus 4.7 출시 개요 — 무엇이 달라졌나

2026년 4월 16일, Anthropic이 Claude Opus 4.7을 일반 공급(GA)했다.

API 모델 ID는 claude-opus-4-7, 가격은 Opus 4.6과 동일한 입력 $5 / 출력 $25 per MTok이며 1M 토큰 컨텍스트에 long-context premium 없이 standard pricing이 적용된다. Claude API, Amazon Bedrock, Google Cloud Vertex AI, Microsoft Foundry에서 출시일 당일부터 사용 가능하다.

Opus 4.6과 비교했을 때 핵심 변경 사항을 정리하면 다음과 같다.

항목	Opus 4.6	Opus 4.7
가격 (per MTok)	입력 $5 / 출력 $25	동일 (1M context도 standard pricing)
이미지 최대 해상도	1568px / 1.15MP	2576px / 3.75MP, 좌표 1:1 픽셀 매핑
Tokenizer	이전 세대	신규 — 동일 텍스트 대비 1.0×~1.35× 토큰
Thinking 모드	extended + adaptive	adaptive only (기본 off, 명시 지정 필요)
temperature / top_p / top_k	사용 가능	기본값 외 지정 시 HTTP 400 에러
기본 tool 호출 성향	더 많음	더 적음, effort로 조정 / 톤도 더 직설적
Subagent 스폰	기본 더 많음	기본 더 적음, 프롬프트로 조정

신규 개발자 기능도 세 가지 추가되었다.

1) task budgets(public beta, 베타 헤더 task-budgets-2026-03-13)는 긴 에이전틱 루프 전체에 토큰 예산 힌트를 주는 advisory cap 기능이다 — 최소 20k tokens이며 hard cap이 아니라 모델에게 페이스를 알려 주는 신호이다.

2)/ultrareview 슬래시 커맨드는 Claude Code에서 전담 코드 리뷰 세션용으로 추가됐다.

3) 고해상도 이미지는 최대 2576px / 3.75MP로 확장되었고, 반환 좌표가 실제 픽셀과 1:1이 되어 스케일 보정 계산이 더 이상 필요 없다.

Breaking change: temperature / top_p / top_k 제거

Opus 4.7에서 temperature, top_p, top_k를 기본값 외의 값으로 지정하면 HTTP 400 에러를 반환한다.

기존에 창의성 조절 용도로 temperature를 올려 쓰던 코드가 있다면 Opus 4.7 전환 전 반드시 해당 파라미터를 제거하거나 기본값으로 되돌려야 한다. sampling 제어가 필요하다면 effort 레벨로 대체하는 편이 권장된다.

Anthropic은 Opus 4.7 발표와 같은 날 "Claude Mythos Preview"의 존재를 공식 인정하고, Opus 4.7이 그보다 덜 유능하다고 밝혔다. Mythos는 Project Glasswing의 일환으로 방어 사이버보안 워크플로우를 위한 연구 프리뷰 모델로, 액세스는 invitation-only이며 self-serve sign-up이 없다.

현재 소수의 기술·사이버보안 회사에만 공개되어 있어 일반 개발자가 호출해 볼 수 있는 제품 라인이 아니다.

1. 왜 갑자기 느려졌나

Claude Code v2.1.117 이후 Opus 4.7로 처음 전환하면, Claude Code는 이전에 설정해 둔 effort 레벨을 무시하고 xhigh를 자동 적용한다.

즉, 어제까지 high에서 잘 돌던 워크플로가 오늘은 xhigh로 돌아간다. Anthropic은 이 동작을 의도적으로 설계했고, 같은 문서에서 "Opus 4.7로 처음 전환할 때는 이전에 Opus 4.6이나 Sonnet 4.6에서 설정한 effort 레벨이 무엇이든 xhigh가 적용된다"고 명시한다.

그렇다면 단순히 effort만 한 단계 올린 것이 아니다. Opus 4.7은 토크나이저가 새로 바뀌었고, 사용자 턴 이후 추론도 더 길어졌다. 출시 공고에 따르면 새 토크나이저는 동일 텍스트에 대해 이전 모델 대비 약 1.0배에서 1.35배 사이의 토큰을 사용할 수 있다.

여기에 베스트 프랙티스 문서는 인터랙티브 세션에서 Opus 4.7이 "사용자 턴 이후 더 많이 추론하며, 이는 장기 세션에서 일관성·지시 추종·코딩 품질을 개선하지만 토큰 사용을 늘리는 경향이 있다"고 적고 있다.

결국 "느려졌다"는 체감은 세 가지가 겹친 결과다. (1) 기본 effort가 xhigh로 자동 상향되었고, (2) 토크나이저가 바뀌어 같은 텍스트도 더 많은 토큰을 차지하며, (3) 사용자 턴 이후 추론이 길어졌다.

Claude Code 메인테이너 boris_cherny는 "Opus 4.7은 thinking 토큰을 더 쓰므로 모든 구독자의 rate limit을 올렸다"고 공식 발표했다. Anthropic은 토큰 사용 증가를 모델 회귀가 아닌 "더 많이 사고하는 동작 변화"로 보고, rate limit 자체를 올려 대응한 것이다. 버그가 아니라 의도된 설계다.

2. 무엇이 바뀌었나 — Opus 4.7의 핵심 변화

Opus 4.7은 2026년 4월 16일에 출시되었고, 모든 Claude 제품과 API, Amazon Bedrock, Google Cloud Vertex AI, Microsoft Foundry에서 즉시 사용할 수 있다. 겉보기엔 평범한 마이너 업그레이드 같지만, 안쪽 동작은 4.6과 상당히 다르다.

2-1. 응답 길이가 작업 복잡도에 맞춰 조정된다

모델 카드는 Opus 4.7이 "고정된 verbosity 기본값을 따르지 않고, 인지된 작업 복잡도에 따라 응답 길이를 조정한다"고 설명한다. 간단한 질문에는 짧게, 복잡한 리팩토링에는 길게 답하는 자기 조절이 강해졌다는 의미다.

2-2. 도구 호출은 줄고 추론은 늘었다

같은 모델 카드는 "기본적으로 도구 호출이 줄고 추론을 더 사용하며, effort를 올리면 도구 사용도 함께 늘어난다. 서브에이전트도 기본적으로 덜 생성된다"고 적고 있다. low/medium 같은 낮은 effort에서는 4.6보다 더 절약 모드로 동작하고, xhigh/max에서는 도구 호출과 서브에이전트가 함께 폭증한다. 같은 모델이 effort에 따라 완전히 다른 성격으로 동작하는 셈이다.

2-3. 지시를 더 문자 그대로 따른다

모델 카드는 또 "낮은 effort 레벨에서 특히, 지시를 더 문자 그대로 따른다. 한 항목에 대한 지시를 다른 항목으로 조용히 일반화하지 않으며, 요청하지 않은 사항을 추론하지 않는다"고 명시한다. 이는 양날의 검이다. 모호한 프롬프트를 4.6처럼 "알아서 해석"해 주는 자비가 줄었다. 그래서 같은 프롬프트가 4.6에서는 잘 동작하다가 4.7에서는 절반만 처리되는 경험이 생긴다.

앤트로픽이 공개한 공식 프롬프팅 베스트 프랙티스 가이드는 이 변화의 긍정적 측면도 명시한다. "이 리터럴리즘의 장점은 정밀성과 불필요한 재처리 감소다. 세심하게 조율된 프롬프트, 구조화된 추출, 예측 가능한 동작이 중요한 파이프라인에서는 오히려 더 좋은 성능을 낸다." 즉, 4.7은 엉성한 프롬프트에 더 엄격해졌지만, 잘 작성된 프롬프트에는 더 충실하게 응답한다는 의미이기도 하다.

실용적 대응법은 단순하다. 지시를 광범위하게 적용받고 싶다면 그 범위를 명시적으로 써야 한다. 가이드의 예시 문구: "이 서식을 첫 번째 섹션만이 아니라 모든 섹션에 적용하라(Apply this formatting to every section, not just the first one)." 4.6이라면 알아서 전체에 적용했을 지시를, 4.7은 첫 항목에만 적용하고 멈춘다.

같은 가이드는 '명확하고 직접적으로'(Be clear and direct) 섹션에서 이렇게 표현한다. "Claude를, 당신의 업무 규범과 워크플로에 대한 맥락은 없지만 능력은 뛰어난 신입 직원이라고 생각하라. 원하는 것을 더 정확히 설명할수록 결과물이 좋아진다." 그리고 황금률 하나를 제시한다: "프롬프트를 해당 작업에 맥락이 거의 없는 동료에게 보여주고 그대로 따르도록 해보라. 그 동료가 혼란스러워한다면, Claude도 마찬가지일 것이다." 결과물이 예전보다 못하게 느껴진다면, 4.6이 알아서 채워줬던 맥락을 이제는 직접 써야 한다는 신호다.

2-4. 새 토크나이저로 입력 토큰이 늘어날 수 있다

앞서 언급한 토크나이저 변화는 비용·속도 양쪽에 모두 영향을 준다. 모델 카드는 "이 새 토크나이저는 텍스트 처리 시 이전 모델 대비 약 1.0배에서 1.35배의 토큰을 사용할 수 있다"고 적고 있다. 콘텐츠에 따라 다르지만, 같은 코드베이스를 같은 프롬프트로 보내도 입력 토큰이 더 많이 잡힐 수 있다. 동일 워크로드에서 비용이 올라간 것처럼 보이는 또 하나의 원인이다.

3. effort 레벨 완전 해부 (xhigh 신규 단계 포함)

Opus 4.7부터 effort 레벨이 5단계로 확장되었다. Anthropic API 문서가 정의한 공식 설명을 정리하면 다음과 같다.

레벨	공식 설명	권장 용도	구체 예시
`low`	가장 효율적. 일부 능력 감소를 감수하고 토큰을 크게 절약	간단한 조회/요약	단순 조회, 텍스트 변환, 비용이 중요한 대량 배치
`medium`	균형 접근. 적당한 토큰 절약	일반적인 코드 수정	단일 파일 수정, 코드 포매팅, 비용 민감한 배치
`high`	높은 능력. effort 파라미터를 설정하지 않은 것과 동일 (API 기본값)	일반적인 코딩/추론	복수 세션 동시 실행, 다중 파일 변경, 비용 절감 필요 시
`xhigh`	장기 작업을 위한 확장 능력. Opus 4.7 한정. Claude Code 기본값	코딩·에이전트 작업 권장 출발점	API/스키마 설계, 레거시 마이그레이션, 대형 코드베이스 리뷰, 에이전트 워크플로
`max`	절대 최대 능력. 토큰 사용 제약 없음	진짜 프런티어 문제만	eval 최대 성능 테스트, 극히 지능 민감하고 비용 비민감한 작업

max는 무조건 좋은 선택이 아니다.

공식 문서는 "진짜 프런티어 문제에만 보존해 두라. 대부분의 워크로드에서 max는 상대적으로 작은 품질 향상을 위해 큰 비용을 추가하며, 일부 구조화 출력이나 지능 민감도가 낮은 작업에서는 오버싱킹으로 이어질 수 있다"고 명시한다.

단순 코드 포매팅이나 정형화된 변환 작업에 max를 쓰면 모델이 불필요하게 길게 사고하다 오히려 결과 품질이 떨어질 수 있다.

3-1. CLI와 API의 기본값이 다르다

Claude Code 모델 설정 문서는 "v2.1.117 기준 Claude Code 기본 effort는 Opus 4.7에서는 xhigh, Opus 4.6과 Sonnet 4.6에서는 high"라고 못 박는다.

API 쪽은 다르다. API 공식 문서에 따르면 "API 기본값은 high이다. xhigh를 쓰려면 effort를 명시적으로 설정해야 하며, 전달한 값이 기본값을 덮어쓴다". 즉, Claude Code CLI는 Opus 4.7 한정으로 자동 xhigh이고, API는 명시 설정해야만 xhigh로 올라간다. 이 차이를 모르면 "API에서는 멀쩡한데 CLI는 왜 느리지?" 같은 혼란이 생긴다.

3-2. effort를 바꾸는 다섯 가지 방법

Claude Code는 effort 변경 경로를 다섯 가지 제공한다.

# 1. /effort 커맨드 (인자 없이 실행하면 인터랙티브 슬라이더)
/effort

# 2. /model 선택 시 좌우 화살표로 effort 조정

# 3. --effort 플래그 (단일 세션 전용)
claude --effort medium

# 4. 환경 변수 (세션 간 지속됨)
export CLAUDE_CODE_EFFORT_LEVEL=high

# 5. settings 파일의 effortLevel 필드
# settings.json
# { "effortLevel": "high" }

같은 문서가 "low, medium, high, xhigh는 세션 간 지속되지만 max는 현재 세션에만 적용되고 세션 간 지속되지 않는다. 단, CLAUDE_CODE_EFFORT_LEVEL 환경 변수로 설정한 경우는 예외"라고 명시한다. max로 실험하던 세션을 종료하면 자동으로 기본값(xhigh)으로 돌아간다는 뜻이다.

ex) /effort

ex) /model

3-3. xhigh/max에서는 max_tokens도 같이 올려야 한다

공식 문서는 "Claude Opus 4.7을 xhigh나 max effort로 실행할 때, 모델이 서브에이전트와 도구 호출 사이에서 사고하고 행동할 공간을 갖도록 큰 max_tokens를 설정하라. 64k 토큰부터 시작해 튜닝하는 것이 합리적인 기본값"이라고 명시한다. 64k는 직접 인용된 수치다. 무작정 늘리지 말고 64k부터 워크로드에 맞춰 조정하면 된다.

실제 설정은 ~/.claude/settings.json의 환경변수로 한다. maxTokens 필드가 아니라 env.CLAUDE_CODE_MAX_OUTPUT_TOKENS에 문자열로 지정하는 방식이다.

{
  "env": {
    "CLAUDE_CODE_MAX_OUTPUT_TOKENS": "65536"
  },
  "effortLevel": "xhigh"
}

나의 경우는 멀티에이전트 파이프라인 작업이 많아 "CLAUDE_CODE_MAX_OUTPUT_TOKENS": "128000"으로 올려서 쓰고 있다. 서브에이전트가 여러 도구 호출을 연달아 처리하다 보면 64k도 빠듯한 경우가 생기기 때문이다. 단순 코딩 세션이라면 64k가 충분하고, 에이전트가 길게 이어지는 작업이라면 128k까지 올려볼 것을 권한다.

3-4. 얕게 답하면 프롬프트가 아니라 effort를 올려라

Anthropic은 4.7의 effort 추종 정책 자체가 4.6보다 엄격해졌다고 밝힌다. "Claude Opus 4.7은 Claude Opus 4.6보다 effort 레벨을 더 엄격하게 존중하며, 특히 low와 medium에서 그렇다. 낮은 effort에서는 모델이 요청된 범위로 작업을 한정하며 그 이상을 시도하지 않는다. Claude Opus 4.7로 복잡한 문제에서 얕은 추론이 관찰된다면, 프롬프트로 우회하지 말고 effort를 올려야 한다". 4.6에서는 "Think step by step"을 추가하면 어느 정도 효과가 있었지만, 4.7에서는 그런 우회가 잘 안 통한다. 깊이 있는 답이 필요하면 effort 자체를 올려야 한다.

4. 첫 턴 프롬팅 전략

베스트 프랙티스 가이드는 4.7의 토큰 효율을 끌어올리는 가장 강력한 레버로 "첫 턴 프롬팅"을 꼽는다.

4-1. 첫 턴에 의도·제약·인수 기준·파일 위치를 모두 담아라

가이드는 "첫 턴에 작업을 명세하라. 의도, 제약, 인수 기준, 관련 파일 위치를 포함한 잘 정의된 작업 설명이 Opus 4.7에게 더 강력한 결과물을 내기 위한 컨텍스트를 제공한다"고 적는다. 앞서 본 모델 카드의 "지시를 더 문자 그대로 따른다"와 합치면, 첫 턴에 부족했던 컨텍스트를 모델이 추측으로 채우지 않는다는 뜻이 된다.

실전 예시를 들면 이렇다. 많은 사용자가 Claude Code를 쓸 때 대화를 조금씩 쪼갠다. "이 파일 봐줘" → "여기 버그 있어?" → "그럼 고쳐줘." 자연스러운 흐름처럼 보이지만, Opus 4.7에서는 이것이 비효율을 만든다.

안 좋은 패턴 (멀티턴)
1턴: "auth 모듈 봐줘"
2턴: "여기 버그 있어?"
3턴: "고쳐줘. 테스트도 추가해"

좋은 패턴 (첫 턴 풀스펙)
"src/auth/login.ts의 세션 만료 처리 로직에 버그가 있다. 만료된 토큰이 갱신 없이 통과되는 문제다. 수정 후 tests/auth/ 아래에 단위 테스트를 추가해줘. 기존 테스트는 깨지면 안 된다."

4-2. 사용자 인터랙션을 줄이고 질문은 묶어라

가이드는 또 "필요한 사용자 인터랙션 수를 줄이고 질문을 배치로 묶어라. 매 사용자 턴마다 추론 오버헤드가 추가된다"고 명시한다.

"Every user turn adds reasoning overhead. Batch your questions and give the model the context it needs to keep moving."
(모든 사용자 턴은 추론 오버헤드를 추가한다. 질문을 묶고, 모델이 계속 진행할 수 있도록 필요한 컨텍스트를 한 번에 제공하라.)

4.7은 사용자 턴 직후에도 길게 사고하므로, 한 번에 5개를 물어보는 대화 한 번이 5번 짧게 묻는 대화보다 훨씬 토큰 효율이 좋다.

4-3. interactive와 asynchronous는 전략이 다르다

같은 가이드는 두 세션 패턴을 명시적으로 구분한다. "비동기 에이전트는 처음부터 단일 턴, 완전히 명세된 작업일 때 이점을 얻는다"고 적는다. 백그라운드 잡, CI 통합 같은 비동기 에이전트는 첫 한 턴에 모든 명세를 다 넣는 것이 최적이다.

인터랙티브 세션은 품질이 올라간 만큼 토큰도 더 쓴다. 이를 받아들이거나, 질문을 의식적으로 묶어서 인터랙션 횟수를 줄이는 것이 현실적인 대응이다.

Anthropic은 모델을 "라인 바이 라인으로 안내하는 페어 프로그래머"가 아니라 "위임할 수 있는 유능한 엔지니어"처럼 대하라고 권한다. 더 큰 청크로 위임하고, 컨텍스트를 충분히 주는 것이 핵심이다.

첫 턴 프롬프트 템플릿 예시

[의도] 결제 모듈의 retry 로직을 idempotent하게 리팩토링한다.
[제약] Spring Boot 3.2, JDK 21, 기존 PaymentService 인터페이스 유지.
[인수 기준] (1) 동일 트랜잭션 ID로 두 번 호출되어도 한 번만 처리. (2) 기존 단위 테스트 모두 통과.
[관련 파일] src/main/java/com/example/payment/PaymentService.java, src/test/java/com/example/payment/PaymentServiceTest.java
[질문] 분산락은 Redisson을 쓰는 게 좋을지, DB unique 제약을 쓰는 게 좋을지 권장안과 trade-off를 함께 알려달라.

이 한 메시지로 의도·제약·인수 기준·파일 위치·질문이 전부 담긴다. 이후 턴이 줄어드는 만큼 토큰 사용도 함께 줄어든다.

5. 사고 깊이 제어하기

effort 외에도 "특정 턴만 더 깊이/얕게 사고하게 하는" 보조 기법이 있다.

5-1. 더 깊이 사고하게 만들기

가이드는 사고를 늘리고 싶을 때 다음 표현을 권장한다.

Think carefully and step-by-step before responding; this problem is harder than it looks.

(응답하기 전에 신중하게 단계별로 생각하라. 이 문제는 보기보다 어렵다.)

4.7은 지시를 문자 그대로 받는다. "더 깊이 생각하라"고 쓰면 쓴 대로 한다. 복잡한 버그 수정이나 아키텍처 설계처럼 정확도가 중요한 상황에 쓴다.

5-2. 더 빠르게 응답하게 만들기

반대 방향도 가능하다. 가이드는 다음 표현을 제안한다.

Prioritize responding quickly rather than thinking deeply. When in doubt, respond directly.

(깊이 생각하는 것보다 빠르게 응답하는 것을 우선시하라. 의심스러울 때는 직접 답변하라.)

다만 같은 가이드는 "어려운 단계에서 일부 정확도를 잃을 수 있다"는 경고를 함께 단다. 요약·포매팅·텍스트 변환에는 적합하지만, 알고리즘 설계나 복잡한 디버깅에 쓰면 답이 얕아진다.

5-3. ultrathink: 한 턴만 깊게 사고시키기

Claude Code 문서는 별도의 in-context 키워드도 안내한다. "세션 설정을 바꾸지 않고 일회성 깊은 추론을 하려면 프롬프트에 ultrathink를 포함하라. 이는 모델에 해당 턴에서 더 많이 추론하라는 in-context 지시를 추가하며, API에 전송되는 effort 레벨을 변경하지는 않는다". 세션 전체를 무겁게 만들지 않고 한 번만 깊이 파고들고 싶을 때 쓰면 된다.

6. auto mode와 토큰 효율화

auto mode는 베스트 프랙티스 가이드가 명시적으로 권장하는 토큰/사이클 효율화 기능이다.

6-1. auto mode란

auto mode 공식 발표에 따르면 "auto mode는 Claude Code의 신규 권한 모드로, Claude가 사용자를 대신해 권한 결정을 내리며 실행 전에 안전 장치가 행동을 모니터링한다."

핵심은 자동화의 안전성을 어떻게 확보하느냐다. 같은 발표는 "각 도구가 실행되기 전에 분류기가 잠재적 파괴 행동을 검토한다"고 적고 있으며, 그 예시로 "대규모 파일 삭제, 데이터 유출, 악성 코드 실행" 등을 든다. 사용자가 매 도구 호출마다 yes/no를 누르지 않아도 되지만, 위험 행동에는 분류기 게이트가 여전히 작동한다.

6-2. 어떻게 켜고 누구에게 권장되나

베스트 프랙티스 가이드는 "auto mode는 사이클 시간을 줄이며, 현재 Claude Code Max 사용자에게 research preview로 제공된다. Shift+Tab으로 토글할 수 있다"고 적는다. 플랜별 가용성은 auto mode 공식 발표가 더 명확하다.

"Team 플랜에서 research preview로 지금 이용 가능하며, Enterprise 플랜과 API 사용자에게는 곧 제공될 예정"이라고 적고 있다.

별도 설정으로 알림도 구성할 수 있다. 베스트 프랙티스 가이드에 따르면 Claude에게 작업 완료 시 소리를 재생해달라고 요청하면, 클로드가 자체적으로 훅 기반 알림을 만들 수 있다.

6-3. 언제 쓰고, 언제 쓰지 않는가

가이드는 "잦은 체크인 없이 모델이 안전하게 실행할 것으로 신뢰할 수 있는 작업에 권장된다"고 명시한다.

이를 실전 결정 매트릭스로 옮기면 다음과 같다.

상황	auto mode 권장
독립 디렉터리에서의 리팩토링·테스트 작성	권장
격리된 샌드박스/컨테이너 환경	권장
명세가 충분히 적힌 비동기 작업	권장
운영 DB 또는 운영 인프라 직접 접근 가능한 세션	비권장
자격 증명이 환경에 노출된 세션	비권장
모호한 명세 + 대규모 변경이 필요한 작업	비권장

분류기가 막아주는 것은 "분명한 파괴 행동"이고, "비즈니스 로직상 위험한 행동"까지 책임지지는 않는다. 신뢰 가능한 환경 + 충분한 명세가 갖춰진 작업에서만 auto mode의 효율을 노리는 것이 안전하다.

7. Extended Thinking 마이그레이션 주의사항

Opus 4.7로 올라오면서 Extended Thinking 사용법이 크게 바뀌었다. 기존 코드를 그대로 보내면 4.7에서는 에러가 난다.

7-1. budget_tokens는 더 이상 동작하지 않는다

모델 카드는 단호하다. "Extended thinking budgets are removed in Claude Opus 4.7. Setting thinking: {"type": "enabled", "budget_tokens": N} will return a 400 error. Adaptive thinking is the only thinking-on mode".

4.6에서 쓰던 고정 thinking 예산 설정 코드는 4.7에서 즉시 400 에러를 던진다. 마이그레이션하려면 adaptive 모드로 전환해야 한다.

7-2. Adaptive thinking은 기본값이 OFF다

같은 모델 카드는 "Adaptive thinking은 Claude Opus 4.7에서 기본적으로 꺼져 있다. thinking 필드가 없는 요청은 thinking 없이 실행된다. 활성화하려면 thinking: {type: 'adaptive'}를 명시적으로 설정해야 한다"고 적는다. 4.7로 올린 뒤 별도 설정을 안 했다면 thinking이 꺼진 채로 돌아가고 있을 가능성이 높다. 의도한 동작인지 확인해볼 필요가 있다.

7-3. Adaptive thinking은 무엇을 해주나

Adaptive thinking 공식 문서는 동작 모델을 명확하게 정의한다.

"In adaptive mode, thinking is optional for the model. Claude evaluates the complexity of each request and determines whether and how much to use extended thinking. At the default effort level (high), Claude almost always thinks. At lower effort levels, Claude may skip thinking for simpler problems."
(adaptive 모드에서 thinking은 모델에게 선택 사항이다. Claude는 각 요청의 복잡도를 평가해 extended thinking을 사용할지, 얼마나 사용할지 결정한다. 기본 effort 레벨(high)에서는 거의 항상 사고한다. 낮은 effort 레벨에서는 단순한 문제에 대해 사고를 건너뛸 수 있다.)

단순한 요청엔 사고를 건너뛰고 복잡한 단계에 사고를 집중하는 동적 할당이다. 또한 같은 문서는 "Adaptive thinking은 도구 호출 사이의 인터리브드 사고도 자동으로 활성화한다. 즉, Claude가 도구 호출 사이에 사고할 수 있어 에이전트 워크플로에 특히 효과적"이라고 적고 있다.

7-4. 사고를 줄이고 싶다면 시스템 프롬프트로

같은 문서는 시스템 프롬프트에 추가할 수 있는 가이던스 문장도 제시한다.

"Extended thinking adds latency and should only be used when it will meaningfully improve answer quality — typically for problems that require multi-step reasoning. When in doubt, respond directly."
(Extended thinking은 지연을 추가하므로 답변 품질을 의미 있게 개선할 때만 사용해야 한다. 주로 다단계 추론이 필요한 문제에 적합하다. 불확실할 때는 직접 응답하라.)

adaptive를 켠 상태에서도 시스템 프롬프트로 사고 빈도를 조절할 수 있다. 응답 지연이 중요한 인터랙티브 시나리오에서 유용하다.

8. 서브에이전트 — 명시하지 않으면 안 한다

Opus 4.7은 서브에이전트를 기본적으로 더 신중하게 생성한다. 이전 버전에서 자동으로 병렬 처리하던 작업도 이제는 직접 처리하는 경향이 있다.

"Opus 4.7 tends to be more judicious about when to delegate work to subagents. If your use case benefits from parallel subagents (for example, fanning out across files or independent items), we recommend spelling that out."
(Opus 4.7은 서브에이전트에게 작업을 위임하는 시점에 대해 더 신중한 경향이 있다. 병렬 서브에이전트가 유용한 경우(예: 파일 전반 팬아웃, 독립 항목 처리)라면 명시적으로 지정할 것을 권장한다.)

병렬 처리가 필요한 경우 반드시 명시해야 한다는 뜻이다. 공식 가이드가 제공하는 예시 지침이다.

"Do not spawn a subagent for work you can complete directly in a single response (e.g., refactoring a function you can already see)."
(단일 응답으로 직접 완료할 수 있는 작업에는 서브에이전트를 생성하지 마라. 예: 이미 보이는 함수 리팩토링.)

"Spawn multiple subagents in the same turn when fanning out across items or reading multiple files."
(여러 항목에 걸쳐 팬아웃하거나 여러 파일을 읽을 때는 같은 턴에 복수 서브에이전트를 생성하라.)

서브에이전트를 만들지 말아야 할 때와 만들어야 할 때를 명확히 구분하고 있다. 단일 응답으로 완료할 수 있는 함수 리팩토링에는 서브에이전트가 불필요하다. 반대로 여러 파일에 걸쳐 팬아웃하거나 독립적인 항목들을 동시에 처리할 때는 같은 턴에 복수 서브에이전트를 생성하도록 지시해야 한다.

9. 적용 체크리스트

지금까지 정리한 내용을 한 번에 적용할 수 있는 체크리스트로 압축해보자.

오늘 바로 적용할 4단계 점검

1. Claude Code 버전 확인: Opus 4.7은 Claude Code v2.1.111 이상이 필요하다. claude update로 최신화한다.
2. /effort 재실행: Opus 4.7로 처음 전환하면 자동으로 xhigh가 적용된다. 본인 워크로드에 맞춰 /effort로 다시 선택한다.
3. 간단 작업은 effort를 낮춘다: 정형 변환·간단 조회는 medium, 단순 코드 포매팅은 low로 내린다. xhigh는 진짜 코딩·에이전트 작업에 보존한다.
4. 무거운 세션은 max_tokens 64k부터: xhigh/max로 실행할 때는 공식 권장대로 max_tokens를 64k에서 시작해 튜닝한다.

첫 턴 프롬프트 체크리스트

의도(목표) 한 줄
제약(스택, 버전, 호환성) 한 줄
인수 기준(통과 조건) 1~3줄
관련 파일 경로
묻고 싶은 질문은 한 메시지에 묶어서

이 다섯 줄이 갖춰지지 않은 첫 턴은 4.7에서 거의 반드시 추가 턴을 부른다. 추가 턴은 추론 오버헤드를 부른다.

언제 어떤 effort를 쓰는가

작업 유형	권장 effort	이유
단순 조회·요약·텍스트 변환	`low`	토큰 절약, 일부 능력 감소 수용
명확한 단일 파일 수정	`medium`	균형 잡힌 토큰 사용
다중 파일 코드 변경, 일반 디버깅	`high`	API 기본값. 안정적 품질
에이전트 워크플로, 반복 도구 호출, 깊은 검색	`xhigh`	Claude Code의 Opus 4.7 기본값
진짜 프런티어 문제 (새 알고리즘, 대형 리팩토링)	`max`	비용 폭주 감수, 한 세션 한정

10. 트러블슈팅 Q&A

Q. effort를 low로 낮추면 Opus 4.6보다 못한 결과가 나오지 않나?

A. 공식 가이드에 따르면 medium/low effort에서도 동일 effort 레벨의 Opus 4.6보다 여전히 뛰어나다. 토큰이 더 적게 나올 수 있다는 점도 명시돼 있다. 더 어려운 작업에서는 성능이 낮아지지만, 단순 작업이라면 낮은 effort로도 충분히 쓸 수 있다.

Q. max effort를 쓰면 무조건 더 좋은 결과가 나오지 않나?

A. 그렇지 않다. 공식 가이드는 max가 수확 체감(diminishing returns)을 보이고 과도한 사고(overthinking) 경향이 있다고 명시했다. 진짜 어려운 문제, eval 최대 성능 테스트, 비용 비민감한 극히 지능 민감 작업에서만 의도적으로 쓰는 것이 권장된다.

Q. Auto mode는 언제부터 쓸 수 있나?

A. 현재 Claude Code Max 사용자와 Team 플랜을 대상으로 research preview로 제공 중이다.

Shift+Tab으로 토글 가능하다. Enterprise 플랜과 API 사용자에게는 곧 제공될 예정이며, 최신 가용성은 공식 채널에서 확인해야 한다.

Q. 서브에이전트를 자동으로 많이 쓰게 하려면?

A. 명시적으로 지시해야 한다. "여러 파일에 걸쳐 팬아웃이 필요하면 같은 턴에 복수 서브에이전트를 생성해라"처럼 구체적인 조건을 프롬프트에 포함하면 된다. 공식 가이드의 예시 문구를 그대로 쓰거나 참고해도 된다.

Q. Extended Thinking을 써야 하는데 Opus 4.7에서 안 된다. 어떻게 하나?

A. Opus 4.7에서 budget_tokens를 포함한 고정 thinking 예산 설정은 HTTP 400 에러를 반환한다. 대신 thinking: {type: 'adaptive'}로 명시 전환해야 한다. API에서 adaptive thinking은 기본값이 OFF이므로 반드시 명시해야 활성화된다. "Think carefully and step-by-step before responding…" 문구로 추론 깊이를 유도하는 것도 가능하다.

Q. xhigh/max에서 실행할 때 max_tokens는 얼마로 설정해야 하나?

A. Anthropic은 64k 토큰부터 시작해 튜닝하라고 권장한다. xhigh/max에서는 서브에이전트와 도구 호출 사이에 사고할 공간이 필요하기 때문이다. 64k를 기준으로 실제 워크로드에 맞춰 조정하면 된다.

Q. API에서는 왜 xhigh가 자동 적용되지 않나?

A. Claude Code CLI와 API의 기본값이 다르다. CLI는 Opus 4.7 한정으로 자동 xhigh를 적용하지만, API는 여전히 high가 기본값이다. API에서 xhigh를 원하면 effort 파라미터를 명시적으로 설정해야 한다.

Opus 4.7로 올라온 뒤 느려졌다는 체감은 대부분 (1) 자동으로 xhigh로 올라간 effort, (2) 새 토크나이저로 인한 입력 토큰 1.0~1.35× 증가, (3) 사용자 턴 이후 더 길어진 추론, 이 셋이 결합한 결과다.

해결도 단순하다. effort를 워크로드에 맞게 다시 정하고, 첫 턴에 컨텍스트를 충분히 담고, 인터랙션을 줄이고, Extended Thinking을 쓴다면 adaptive로 명시 전환한다. 기존 코드를 그대로 4.7에 보내고 있다면 budget_tokens 호출은 즉시 제거해야 한다.

참고자료

Best practices for using Claude Opus 4.7 with Claude Code — Anthropic 공식 블로그, 2026-04-16
Claude Opus 4.7 출시 공고 — Anthropic
Claude Opus 4.7 What's New (모델 카드) — Anthropic 공식 문서
Prompting best practices — Anthropic 공식 문서 (Claude 4.x 시리즈 통합 프롬프트 엔지니어링 가이드)
Claude Code 모델 설정 문서 — Anthropic 공식 문서
Effort 공식 문서 — Anthropic 공식 문서
Auto mode 공식 발표 — Anthropic 공식 블로그
Adaptive thinking 공식 문서 — Anthropic 공식 문서
boris_cherny Threads — rate limit 인상 발표
Claude Code 세션 관리 및 1M 컨텍스트 가이드 — Anthropic 공식 블로그

Claude API 신기능 : Advisor Strategy(어드바이저 전략) - 비용은 낮추고 성능은 올리는 Advisor Tool API

갓대희 — Sun, 26 Apr 2026 15:00:11 +0900

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

AI 에이전트 개발자라면 한 번쯤 마주치는 딜레마가 있다. 성능이 필요하면 Opus, 비용이 걱정되면 Haiku나 Sonnet — 이 둘 중 하나를 골라야 했다. Anthropic이 2026년 초 이 이분법을 깨는 패턴을 공식 API로 내놨다. 이름은 Advisor Strategy다.

핵심 아이디어는 단순하다. 빠른 모델(executor)이 작업을 진행하다 복잡한 판단이 필요한 순간에만 Opus(advisor)에게 묻는다. Opus는 도구도 실행하지 않고, 짧은 계획만 전달한다. executor는 그 조언을 받아 재개한다.

이 글에서는 두 가지를 다룬다. 하나는 공식 Advisor Tool API — Python SDK와 TypeScript SDK, curl로 바로 붙일 수 있는 코드 예시. 다른 하나는 advisor-opus 커뮤니티 플러그인 — Claude Code에서 슬래시 커맨드 하나로 Opus에게 묻는 방법이다.

등장 배경 — 왜 Advisor Strategy가 필요했나
핵심 개념 — 동작 원리와 API 구조
벤치마크 — 실제로 얼마나 좋아졌나
공식 API 사용법 — Python SDK · TypeScript SDK · curl 예시
advisor-opus 플러그인 설치 및 사용법
사용 시나리오별 선택 가이드
베타 제한사항 · 트러블슈팅 Q&A
도입 플레이북

1. 등장 배경 — 왜 Advisor Strategy가 필요했나

에이전트 프레임워크를 만들어본 개발자라면 공통된 벽에 부딪혔을 것이다. Opus를 쓰면 품질은 좋지만 비용이 부담스럽고, Haiku나 Sonnet을 쓰면 복잡한 추론 단계에서 실수가 나온다.

Anthropic 공식 블로그에 따르면, 현장 개발자들이 이미 이 패턴에 독립적으로 수렴하고 있었다. 비싼 Opus를 전체 작업에 쓸 것인지, 저렴한 모델로 품질을 낮출 것인지 — 이 이분법이 에이전트 설계의 공통된 병목이었다. Advisor Strategy는 이 둘 사이에 세 번째 길을 제시한다. executor가 작업을 계속 담당하되, 복잡한 판단이 필요한 시점에만 Opus에게 자문을 구하는 것이다.

핵심은 "모델 전환 없는 실시간 자문"이다. 작업 중간에 Opus로 갈아타는 것이 아니라, executor가 실행을 멈추지 않고 Opus의 조언만 구해서 계속 진행한다.

Anthropic이 이 패턴을 공식 API로 표준화했다.

2. 핵심 개념 — 동작 원리와 API 구조

executor가 advisor에게 묻는 흐름

공식 문서에 따르면 동작 흐름은 다음과 같다.

"The executor model (Sonnet/Haiku) runs tasks end-to-end, calling tools and iterating. When facing difficult decisions, it consults Opus for guidance—which provides plans, corrections, or stop signals—then resumes execution."

(해석) executor 모델(Sonnet/Haiku)은 작업을 처음부터 끝까지 담당하며 도구를 호출하고 반복 실행한다. 복잡한 판단이 필요한 순간에는 Opus에 자문을 구해 계획·수정·중단 신호를 받은 뒤 실행을 재개한다.

executor는 작업 전체를 처음부터 끝까지 담당한다. 복잡한 판단이 필요한 시점에만 advisor를 호출하고, advisor의 계획이나 수정 신호를 받아 실행을 재개한다. advisor는 도구를 직접 실행하지 않는다.

advisor가 토큰을 적게 쓰는 것도 설계의 일부다. 공식 문서에 따르면 advisor는 요청당 400-700 text token만 생성한다. 전체 출력이 아닌 짧은 계획만 반환하기 때문에, Opus를 계속 돌리는 것보다 비용이 훨씬 낮아진다.

API 페이로드 구조

공식 API 문서에서 확인한 핵심 파라미터는 세 가지다.

type: advisor_20260301 — advisor tool임을 선언하는 고정 값
name: advisor — 변경 불가 고정 값
model: claude-opus-4-7 — 현재 API 문서 기준으로 advisor로 지원되는 유일한 모델

버전 주의: Anthropic 블로그 발행 시점(2026-04-09)에는 claude-opus-4-6이 언급됐으나, 현재 공식 API 문서에서는 claude-opus-4-7만 advisor로 지원한다. 공식 문서를 우선 적용한다.

모델 페어링은 공식 문서에서 다음과 같이 명시한다.

Executor 모델	Advisor 모델
claude-haiku-4-5-20251001	claude-opus-4-7
claude-sonnet-4-6	claude-opus-4-7
claude-opus-4-6	claude-opus-4-7
claude-opus-4-7	claude-opus-4-7

한 줄로 요약하면: advisor는 항상 claude-opus-4-7이고, executor는 네 가지 중에서 선택한다.

응답 구조

advisor를 호출하면 응답에 두 가지 블록이 추가된다. server_tool_use로 advisor 호출 시작을 알리고, advisor_tool_result로 Opus의 조언이 전달된다. 공식 문서 기준 실제 응답 구조는 아래와 같다.

{"type": "server_tool_use", "id": "srvtoolu_abc123", "name": "advisor", "input": {}}

결과:

{
  "type": "advisor_tool_result",
  "content": {
    "type": "advisor_result",
    "text": "어드바이저의 조언 텍스트"
  }
}

이 advisor_tool_result 블록을 멀티턴 대화에서 반드시 보존해야 한다는 점이 중요하다. 이 내용은 섹션 7(트러블슈팅)에서 다시 다룬다.

3. 벤치마크 — 실제로 얼마나 좋아졌나

SWE-bench Multilingual

Anthropic 공식 블로그에서 공개한 수치다.

"Sonnet with Opus as an advisor showed a 2.7 percentage point increase on SWE-bench Multilingual over Sonnet alone, while reducing cost per agentic task by 11.9%."

(해석) Opus를 advisor로 쓴 Sonnet은 SWE-bench Multilingual에서 Sonnet 단독 대비 2.7%p 성능 향상을 기록했으며, 에이전트 작업당 비용은 11.9% 줄었다.

이 수치가 의미하는 바는 단순하지 않다. 성능을 올리면서 비용도 줄였다 — 보통은 둘 중 하나를 포기해야 하는 트레이드오프를 Advisor Strategy가 동시에 해소했다는 점이다. 공식 블로그 본문에는 2.7%p와 11.9%만 명시되며, 세부 점수(74.8%/72.1%)는 커뮤니티 소스(decodethefuture.org)에서 확인된 수치다.

측정 조건도 확인할 필요가 있다. 공식 블로그에 따르면 Sonnet 4.6 단독 측정에는 adaptive thinking이 사용됐고, Sonnet 4.6 + Advisor 조합에는 thinking을 비활성화한 권장 시스템 프롬프트가 적용됐다. 비교 전제를 이해하고 적용하는 것이 중요하다.

BrowseComp

코딩 외 영역의 수치도 주목할 만하다. 공식 블로그에 따르면:

"Haiku with an Opus advisor reached 41.2% on BrowseComp—more than double its standalone 19.7% score."

(해석) Opus를 advisor로 쓴 Haiku는 BrowseComp에서 41.2%를 기록했다 — 단독 점수 19.7%의 두 배 이상이다.

Haiku 단독 19.7%에서 Haiku+Opus advisor 41.2%로 2배 이상 뛰었다. 이 조합은 Sonnet 단독 대비 성능이 29% 낮지만 비용은 85% 낮다는 점도 같은 출처에서 확인된다.

결국 용도가 갈린다. 코딩·버그 수정이면 Sonnet+Opus. 웹 탐색처럼 Haiku로 처리 가능하지만 판단이 필요한 작업이라면 Haiku+Opus가 비용 절감폭이 훨씬 크다.

Terminal-Bench 2.0

터미널 작업 벤치마크에서도 공식 블로그에 따르면 Sonnet과 Haiku executor 모두 Opus advisor 페어링 시 성능이 향상됐다. 89개 태스크, 5회 평균 측정 기준이다.

실 사용 사례 — Eve Legal

벤치마크 외에 실 고객 사례도 공개됐다. Anthropic 공식 블로그에 수록된 Eve Legal 사례다.

"On structured document extraction tasks, the advisor tool enables Haiku 4.5 to dynamically scale intelligence by consulting Opus 4.6 as complexity demands, matching frontier-model quality at 5× lower cost." — Anuraj Pandey, Machine Learning Engineer, Eve Legal

(해석) 구조화 문서 추출 작업에서 advisor 도구는 Haiku 4.5가 복잡도에 따라 Opus 4.6에 자문을 구하며 지능을 동적으로 확장할 수 있게 해준다. 그 결과 프론티어 모델 수준의 품질을 5배 낮은 비용으로 달성했다. — Anuraj Pandey, Machine Learning Engineer, Eve Legal

구조화 문서 추출 작업에서 Haiku 4.5가 Opus를 advisor로 활용해 프론티어 모델 수준의 품질을 5배 낮은 비용으로 달성했다는 사례다. 인용문은 당시 Opus 4.6 기준이며, 현재 API에서는 Opus 4.7이 advisor로 지원된다.

4. 공식 API 사용법 — Python SDK · TypeScript SDK · curl 예시

베타 헤더 필수 설정

모든 요청에 anthropic-beta: advisor-tool-2026-03-01 헤더를 포함해야 한다. Python SDK에서는 betas=["advisor-tool-2026-03-01"]로 전달한다. 공식 문서에서 확인된 필수 요구사항이다.

베타 헤더 누락 시 API 호출이 실패한다. 현재 GA(정식 출시) 상태가 아니므로, 모든 요청에 반드시 베타 헤더를 포함해야 한다.

공식 권장 시스템 프롬프트

공식 문서는 코딩 작업에서 advisor를 효과적으로 쓰기 위한 시스템 프롬프트 작성 지침을 제공한다. 핵심은 실질적 작업 착수 전에 advisor를 호출하도록 executor에게 지시하는 것이다.

"Call advisor BEFORE substantive work — before writing, before committing to an interpretation, before building on an assumption."

(해석) 실질적인 작업에 착수하기 전에 advisor를 호출하라 — 코드를 쓰기 전, 해석을 확정하기 전, 가정 위에 구현을 쌓기 전에.

글 쓰기 전, 해석을 확정하기 전, 가정 위에 구현을 쌓기 전 — 이 세 시점이 advisor 호출의 최적 타이밍이다.

advisor 출력 토큰을 35-45% 줄이는 팁도 공식 문서에 나와 있다. 시스템 프롬프트에 다음 지시를 추가하면 된다.

The advisor should respond in under 100 words and use enumerated steps, not explanations.

Python SDK 최소 동작 예시

import anthropic

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-sonnet-4-6",      # executor 모델
    max_tokens=4096,
    betas=["advisor-tool-2026-03-01"],  # 베타 헤더 필수
    tools=[
        {
            "type": "advisor_20260301",
            "name": "advisor",          # 변경 불가 고정값
            "model": "claude-opus-4-7", # advisor 모델
        }
    ],
    messages=[{"role": "user", "content": "Build a concurrent worker pool in Go with graceful shutdown."}],
)
print(response.content)

TypeScript SDK 최소 동작 예시

공식 문서에 수록된 TypeScript SDK 예시다. Python SDK와 구조는 동일하며, client.beta.messages.create()에 betas 배열을 함께 전달한다.

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

async function main() {
  const response = await client.beta.messages.create({
    model: "claude-sonnet-4-6",   // executor 모델
    max_tokens: 4096,
    betas: ["advisor-tool-2026-03-01"],  // 베타 헤더 필수
    tools: [
      {
        type: "advisor_20260301",
        name: "advisor",          // 변경 불가 고정값
        model: "claude-opus-4-7"  // advisor 모델
      }
    ],
    messages: [
      {
        role: "user",
        content: "Build a concurrent worker pool in Go with graceful shutdown."
      }
    ]
  });

  console.log(response);
}

main().catch(console.error);

Python SDK 멀티턴 완전 예시

공식 문서에 수록된 멀티턴 예시다. Go 워커 풀 구현을 요청하고, 이어서 추가 제약을 붙이는 시나리오다.

import anthropic

client = anthropic.Anthropic()
tools = [{
    "type": "advisor_20260301",
    "name": "advisor",
    "model": "claude-opus-4-7",
}]
messages = [{
    "role": "user",
    "content": "Build a concurrent worker pool in Go with graceful shutdown.",
}]

# 첫 번째 요청
response = client.beta.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=4096,
    betas=["advisor-tool-2026-03-01"],
    tools=tools,
    messages=messages,
)

# 멀티턴: assistant 응답 전체를 히스토리에 추가 (advisor_tool_result 포함)
messages.append({"role": "assistant", "content": response.content})
messages.append({"role": "user", "content": "Now add a max-in-flight limit of 10."})

# 두 번째 요청
response = client.beta.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=4096,
    betas=["advisor-tool-2026-03-01"],
    tools=tools,
    messages=messages,
)

response.content 전체를 messages에 추가하는 부분이 핵심이다. advisor_tool_result 블록을 빠뜨리면 다음 요청에서 400 에러가 발생한다.

curl 예시

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: advisor-tool-2026-03-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 4096,
    "tools": [
      {
        "type": "advisor_20260301",
        "name": "advisor",
        "model": "claude-opus-4-7"
      }
    ],
    "messages": [
      {"role": "user", "content": "작업 내용을 입력하세요"}
    ]
  }'

max_uses와 캐싱 설정

max_uses 파라미터로 요청당 advisor 호출 횟수를 제한할 수 있다. 공식 문서에 따르면 초과 시 advisor_tool_result_error와 함께 max_uses_exceeded 에러 코드가 반환되며, executor는 advisor 없이 계속 실행된다. 이 제한은 요청 단위(per-request)이며, 대화(conversation) 전체에 걸친 cap은 별도로 존재하지 않는다.

대화 수준에서 advisor 호출을 제한하려면 클라이언트 쪽에서 직접 카운트해야 한다. 공식 문서에 따르면 한도에 도달한 시점에 tools 배열에서 advisor를 제거하고, 메시지 히스토리에서 advisor_tool_result 블록도 함께 제거해야 한다. advisor_tool_result 블록을 남긴 채 advisor를 tools에서 제거하면 400 에러가 발생한다.

같은 advisor를 여러 번 호출하는 시나리오라면 캐싱이 비용을 줄여준다. 공식 문서에서 확인된 설정이다. ttl은 "5m"(5분)과 "1h"(1시간) 두 값을 지원하며, 기본값은 "5m"이다. tools 배열의 advisor 정의 안에 추가한다.

{
  "type": "advisor_20260301",
  "name": "advisor",
  "model": "claude-opus-4-7",
  "caching": {"type": "ephemeral", "ttl": "5m"}
}

캐시 쓰기 비용이 읽기 절감보다 크므로, 대략 3회 이상 호출하는 시나리오에서 손익분기점에 도달한다. 단, extended thinking을 활성화하는 경우 clear_thinking 설정과의 상호작용에 주의가 필요하다. clear_thinking의 keep 값이 "all"이 아닌 경우 advisor 쪽에서 매 턴 캐시 미스가 발생해 비용이 늘어난다. extended thinking을 별도 설정 없이 활성화하면 API 기본값(keep: {type: "thinking_turns", value: 1})이 이 문제를 자동으로 유발한다. keep: "all"로 설정하면 advisor 캐시 안정성이 유지된다.

토큰 사용량 추적 — 비용 계산 가이드

공식 문서에 따르면 top-level usage 필드는 executor 토큰만 반영한다. advisor 토큰은 top-level usage에 합산되지 않으며, usage.iterations 배열에서 별도로 확인한다. 실제 비용 계산 시에는 두 모델의 청구 요금이 다르므로 iterations를 반드시 분리해서 집계해야 한다.

usage.iterations 배열의 각 항목은 다음과 같이 구분된다.

{
  "usage": {
    "input_tokens": 1200,
    "output_tokens": 850,
    "iterations": [
      {
        "type": "message",
        "input_tokens": 1200,
        "cache_read_input_tokens": 0,
        "cache_creation_input_tokens": 0,
        "output_tokens": 120
      },
      {
        "type": "advisor_message",
        "input_tokens": 4800,
        "cache_read_input_tokens": 3200,
        "cache_creation_input_tokens": 0,
        "output_tokens": 95
      },
      {
        "type": "message",
        "input_tokens": 1350,
        "cache_read_input_tokens": 0,
        "cache_creation_input_tokens": 0,
        "output_tokens": 730
      }
    ]
  }
}

type: "message"는 executor(Sonnet/Haiku) 요금으로, type: "advisor_message"는 advisor(Opus) 요금으로 별도 청구된다. top-level input_tokens는 executor의 첫 번째 iteration만 반영한다는 점에 주의한다. Batch processing을 사용하는 경우 usage.iterations는 아이템별로 보고된다.

실전에서 흔한 실수는 top-level usage.output_tokens만 보고 advisor 비용을 누락하는 것이다. 위 예시에서 advisor_message의 output_tokens(95)는 Opus 요금으로 별도 산정되므로, 비용 대시보드에서 iterations를 집계하지 않으면 실제 비용을 과소 추정하게 된다. advisor_message가 예상보다 많이 찍힌다면 max_uses 파라미터로 요청당 advisor 호출 횟수에 상한을 두는 것이 비용 통제의 첫 번째 수단이다.

5. advisor-opus 플러그인 설치 및 사용법

플러그인 개요

advisor-opus는 Claude Code에서 Advisor Strategy를 슬래시 커맨드로 쓸 수 있게 만든 커뮤니티 플러그인이다. MIT 라이선스로 공개되어 있다.

Deprecated 상태: GitHub README에 명시된 내용이다: "Claude Code에 /advisor 기능이 공식 출시(혹은 출시 예정)되어, 이 플러그인은 deprecated 되었습니다. 이 플러그인이 제공하던 Advisor 패턴이 Claude Code에 네이티브로 내장됩니다. 공식 기능을 사용하세요: Claude Code 세션에서 /advisor를 입력하면 됩니다. 다만, 이 플러그인은 skill 호출 시점을 직접 커스터마이즈할 수 있어 여전히 유용합니다. Repo는 계속 유지되며, 설치하여 사용할 수 있습니다."

Claude Code /advisor — Experimental 상태 (v2.1.117, 2026-04-22 기준): Claude Code changelog에 따르면 내장 /advisor 기능은 현재 GA(정식 출시)가 아닌 experimental 상태다. "Advisor Tool (experimental)" 레이블이 붙어 있으며 세션 시작 시 startup notification이 표시된다. 운영 환경 도입 전 experimental 상태임을 고려해야 한다.

설치 3단계

GitHub README에서 확인한 설치 절차다.

# 1. 마켓플레이스에서 플러그인 추가
/plugin marketplace add shalomeir/advisor-opus

# 2. 플러그인 설치
/plugin install advisor-opus@advisor-opus

# 3. 플러그인 리로드
/reload-plugins

ex)

> /plugin marketplace add shalomeir/advisor-opus

> /plugin install advisor-opus@advisor-opus

> /reload-plugins

제공 커맨드 3종

플러그인 README에 따르면 세 가지 커맨드가 있다.

커맨드	역할
`/advisor-opus:plan`	작업 시작 전 전략적 계획 수립 — end state, critical path, risks, next steps
`/advisor-opus:advise`	아키텍처·방향 결정 시 두 번째 의견 (second opinion)
`/advisor-opus:review`	커밋 전 정확성·보안 검토

한 줄 요약: plan은 시작 전, advise는 방향이 헷갈릴 때, review는 커밋 직전에 쓴다.

자동 호출 로직과 모델 추천

플러그인은 호출 타이밍도 정의해 놨다. README에 따르면 PLANNING(복잡 작업 전), COMPLETION(코드 작성 후 커밋 전), PIVOT/REACTIVE(방향 전환이나 막혔을 때) 세 시점이 기준이다. 복잡한 작업당 최대 2회(최대 4회 수준), 단순 작업은 건너뛴다.

executor 모델별 추천도 같은 문서에서 명확하다.

Executor	추천 여부	이유
Haiku	강력 추천	지능 격차가 커서 Opus 조언의 효과가 극대화됨
Sonnet	추천	비용과 의미 있는 Opus 조언 사이 균형점
Opus	비추천	지능 이점 없음, 자동 호출 비활성화

v0.2.0 변경 사항

2026-04-10 출시된 v0.2.0에서 공식 Advisor Tool 모범 사례에 맞춰 플러그인을 전면 재작성했다. 출력 제한도 150단어에서 100단어로 축소됐다. 공식 API의 "100단어 이내" 권장 지침을 반영한 변경이다.

6. 사용 시나리오별 선택 가이드

시나리오 A — API를 직접 통합하는 개발자

자체 에이전트 프레임워크를 Python이나 TypeScript로 구축 중이라면 공식 Advisor Tool API가 적합하다. client.beta.messages.create()에 advisor tool을 추가하고, betas=["advisor-tool-2026-03-01"]을 붙이면 기존 코드를 크게 수정하지 않고 붙일 수 있다.

이 시나리오에서는 max_uses 설정으로 비용을 통제하는 것이 중요하다. advisor가 무제한 호출되면 Opus 비용이 예상보다 커질 수 있다. 3회 이상 호출이 예상되는 플로우라면 캐싱(ttl: "5m")을 함께 적용한다.

공식 문서에 따르면 비용 최적화 조합도 참고할 만하다. Sonnet executor에 medium effort를 적용하고 Opus advisor를 붙이면 Sonnet default effort와 유사한 지능을 더 낮은 비용으로 달성할 수 있다. 최대 지능이 필요하다면 executor를 default effort로 유지한다.

시나리오 B — Claude Code에서 바로 써보고 싶은 개발자

코드를 작성하지 않고 Advisor Strategy를 경험해보고 싶다면 두 가지 선택지가 있다.

Claude Code 내장 /advisor 커맨드 — v2.1.117 기준 experimental 상태. 별도 설치 없이 바로 사용 가능하나, 정식 출시 전 기능임을 감안한다.
advisor-opus 플러그인 — deprecated됐지만, 호출 타이밍(plan/advise/review)을 수동으로 제어하고 싶을 때 유용.

Claude Code /advisor — Experimental (v2.1.117, 2026-04-22): Claude Code changelog에서 확인된 상태다. "Advisor Tool (experimental)" 레이블이 붙어 있으며, 이전 버전에서 'Advisor tool result content could not be processed' 버그가 수정된 이력이 있다. GA 이전 기능이므로 운영 환경 도입 시 주의가 필요하다.

executor로 Haiku를 쓰는 경우라면 플러그인의 효과가 가장 크다. advisor-opus README에 따르면 Haiku+Opus 조합에서 "지능 격차가 최대화"되어 Opus 조언의 효과가 극대화된다.

언제 Advisor Strategy를 쓰지 않는가

모든 작업에 advisor를 붙이는 것이 항상 유리한 것은 아니다. 공식 문서는 advisor가 적합하지 않은 케이스를 명시한다.

단순 one-shot Q&A — 계획할 것이 없는 단일 턴 요청에는 advisor 오버헤드가 태스크 복잡도를 초과해 비용만 늘어난다.
pass-through model picker — 사용자가 직접 비용·품질 트레이드오프를 선택하는 구조라면 advisor를 끼워 넣어도 의미가 없다. 사용자가 이미 원하는 모델을 선택한 상황이다.
Opus를 executor로 쓰는 경우 — advisor도 Opus이므로 지능 이점이 없다. advisor-opus 플러그인도 이 경우 자동 호출을 비활성화한다.
모든 턴이 advisor 수준 역량을 필요로 하는 워크로드 — executor와 advisor의 역할 분리보다 처음부터 Opus 단독으로 실행하는 편이 낫다.

7. 베타 제한사항 · 트러블슈팅 Q&A

베타 주의사항

Advisor Tool은 현재 베타 상태다(2026-04-24 기준). GA(정식 출시)되지 않았으므로 프로덕션 도입 시 다음 사항을 고려한다.

베타 헤더(advisor-tool-2026-03-01)는 GA 시 변경될 수 있다.
스트리밍 사용 시: advisor sub-inference는 스트리밍되지 않는다. 공식 문서에 따르면 advisor 실행 중 executor 스트림이 일시 중단되며, 약 30초마다 SSE keepalive가 전송된다. 단, advisor 호출이 짧을 경우 ping이 전혀 없을 수 있다.
모델 페어링은 현재 Opus 4.7(advisor)로 고정된다.
ZDR(Zero Data Retention) 계약이 있는 조직은 advisor tool도 ZDR 적용 대상이다.

추가 제한사항 (v2026-04-24 기준 신규 확인)

공식 문서에서 새로 확인된 제한사항 3가지다.

clear_tool_uses 미완전 지원 (임시): clear_tool_uses는 아직 advisor tool blocks와 완전히 호환되지 않는다. 향후 릴리즈에서 지원 예정이다.
Priority Tier 모델별 적용: Anthropic Priority Tier는 모델별로 적용된다. executor에 Priority Tier가 설정되어 있어도 advisor에는 자동으로 적용되지 않는다. advisor 모델에도 별도로 Priority Tier를 설정해야 한다.
max_tokens executor 전용: top-level max_tokens는 executor output에만 적용된다. advisor 토큰 출력은 별도로 제어되지 않는다.

에러 코드 6종과 대처법

공식 문서에서 확인한 에러 코드와 대처법이다.

에러 코드	원인	대처법
`max_uses_exceeded`	요청당 advisor 호출 한도 초과	`max_uses` 값을 높이거나, 호출 빈도를 줄인다
`too_many_requests`	레이트 제한	재시도 로직(exponential backoff) 적용
`overloaded`	API 서버 용량 초과	일시적 현상, 재시도
`prompt_too_long`	트랜스크립트가 advisor 모델 컨텍스트 초과	히스토리를 줄이거나 대화를 분리
`execution_time_exceeded`	타임아웃	태스크를 더 작은 단위로 분리
`unavailable`	advisor 모델 일시 불가	재시도, 지속 시 Anthropic 지원 문의

6가지 에러 중 실무에서 가장 빈번한 것은 advisor_tool_result 블록 누락으로 인한 invalid_request_error(아래 Q&A에서 별도 다룸)와 max_uses_exceeded이며, 나머지 4종은 일시적 서버 상태에 의한 것이므로 exponential backoff 재시도로 대부분 해결된다.

Q&A

Q. 멀티턴 대화에서 400 에러가 발생한다.

공식 문서에 따르면 advisor_tool_result 블록을 포함한 assistant 응답 전체를 다음 턴의 메시지 히스토리에 추가해야 한다. 이 블록을 빠뜨린 채 요청하거나, tools 목록에서 advisor를 제거한 상태로 히스토리에 advisor_tool_result가 남아있으면 400 invalid_request_error가 발생한다.

Q. beta header를 어떻게 정확히 설정하는가?

Python SDK: betas=["advisor-tool-2026-03-01"]

TypeScript SDK: betas: ["advisor-tool-2026-03-01"]

curl: -H "anthropic-beta: advisor-tool-2026-03-01"

Q. advisor 호출 횟수를 어떻게 추적하는가?

응답의 usage.iterations 배열에서 type: "advisor_message" 항목 수를 세면 된다. top-level usage는 executor 첫 번째 iteration의 input_tokens만 반영하므로 advisor 비용 산출 시에는 반드시 iterations를 분리해서 집계해야 한다.

Q. 스트리밍 연결이 끊기는 것처럼 느껴진다.

공식 문서에 따르면 advisor 실행 중 스트림이 멈추는 것은 정상 동작이다. SSE keepalive는 약 30초마다 전송되나, advisor 호출이 짧은 경우 ping이 전혀 없을 수 있다. advisor 완료 후 advisor_tool_result는 delta 없이 단일 content_block_start 이벤트로 한 번에 도착한다. 클라이언트 타임아웃을 충분히 (30초 이상) 설정한다.

8. 도입 플레이북

Advisor Strategy를 처음 도입한다면 단계적 접근이 현실적이다.

오늘 (탐색)

Claude Code를 쓰고 있다면 내장 /advisor 커맨드로 패턴을 먼저 경험한다. 현재 experimental 상태이므로 프로덕션 적용 전 충분히 테스트하는 것을 권장한다. advisor-opus 플러그인은 /plugin marketplace add shalomeir/advisor-opus 한 줄로 설치하고 /advisor-opus:plan으로 시작해볼 수 있다.

이번 주 (API 통합 검증)

기존 에이전트 워크플로의 복잡한 판단 단계를 특정한다. Python 또는 TypeScript SDK 예시를 참고해 client.beta.messages.create()에 advisor tool을 추가하고, max_uses=3으로 호출 횟수를 제한하며 실험한다. usage.iterations로 실제 advisor/executor 토큰을 분리해 측정한다. 비용 최적화가 목표라면 Sonnet medium effort + Opus advisor 조합도 검토한다.

운영 반영 시 체크리스트

베타 헤더 명시 (advisor-tool-2026-03-01)
<code style="background: #f4f4f4; padding: 2px 6px; border-radius: 4px;

Claude Code 'ultrareview'란 : 멀티 에이전트 코드 리뷰, 어떻게 작동하나 - 회당 $5~$20 추가 과금은 합리적 일까

갓대희 — Fri, 24 Apr 2026 19:00:35 +0900

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

AI가 코드를 쓰는 속도가 빨라질수록 리뷰하는 속도는 따라가지 못했다. Anthropic 내부 데이터에 따르면 엔지니어 1인당 코드 산출량이 지난 1년간 200% 증가했고, 코드 리뷰가 새로운 병목이 됐다. 이 문제를 해결하기 위해 Anthropic이 선택한 답이 /ultrareview다.

/ultrareview는 원격 클라우드 샌드박스에서 에이전트 플릿이 병렬로 버그를 탐색하고, 별도 검증 단계에서 거짓 양성을 걸러낸 뒤 결과를 세션에 알림으로 돌려주는 멀티 에이전트 코드 리뷰 파이프라인이다.

이 글은 /ultrareview가 무엇인지, 어떻게 작동하는지, 기존 /review·Skill 기반 리뷰와 무엇이 다른지 공식 문서 기반으로 분석해보고자 한다.

/ultrareview란 무엇인가 — 개념과 공식 정의
시작하기 — 사전 요건과 CLI 실행 순서
작동 방식 — Find·Verify 파이프라인과 병렬 분석
공개 정보 기반 아키텍처 추정
실전 적용 사례 — 치명적 버그 탐지 3가지
요금제 및 제한사항
/review vs /ultrareview vs Skill 기반 리뷰 비교
7-1. 비용 논란 — 커뮤니티 반응
7-2. 앤트로픽의 슬래시 명령어 전략
결정 매트릭스 + 도입 플레이북

1. /ultrareview란 무엇인가

공식 문서는 /ultrareview를 다음과 같이 정의한다.

"Ultrareview is a deep code review that runs on Claude Code on the web infrastructure. When you run /ultrareview, Claude Code launches a fleet of reviewer agents in a remote sandbox to find bugs in your branch or pull request."
(Ultrareview는 웹 기반 인프라에서 Claude Code를 통해 수행되는 심층 코드 리뷰입니다. /ultrareview 명령을 실행하면, Claude Code는 원격 샌드박스 환경에서 다수의 리뷰어 에이전트를 구동하여 브랜치 또는 Pull Request 내의 버그를 탐지합니다.)

핵심은 세 단어다. 원격(remote), 샌드박스(sandbox), 플릿(fleet). 로컬 세션에서 실행되는 /review와 달리, /ultrareview는 Claude Code on the web 인프라 위에서 여러 에이전트가 동시에 브랜치 또는 PR을 분석한다.

공식 출시 발표에서 /ultrareview를 "변경 사항을 읽어내고 꼼꼼한 리뷰어가 잡을 만한 것을 플래그하는 전용 리뷰 세션"이라고 설명했으며, Max 사용자 대상 Auto 모드 확장과 함께 공개됐다. 이는 /ultrareview가 단순 기능 추가가 아니라 "긴 작업을 더 적은 중단으로 실행"하는 Claude Code 자동화 방향의 일환임을 보여준다.

중요한 전제부터 확인하고 넘어간다. 공식 문서는 /ultrareview를 research preview 기능으로 명시하고 있으며, "기능·요금·가용성은 피드백에 따라 변경될 수 있다"고 밝히고 있다. GA(정식 출시)가 아니므로, 현재 동작이 향후 달라질 수 있다는 점을 먼저 인지해야 한다.

기존 /review 대비 3가지 강점

공식 문서는 /review 대비 세 가지 강점을 명시한다.

높은 신호(Higher signal): 모든 발견 사항은 독립적으로 재현·검증된다. 스타일 제안 대신 실제 버그에 집중한 결과만 받는다.
넓은 커버리지(Broader coverage): 여러 리뷰어 에이전트가 변경 사항을 병렬로 탐색하므로, 단일 패스 리뷰가 놓칠 수 있는 문제를 포착한다.
로컬 리소스 무사용(No local resource use): 리뷰가 원격 샌드박스에서 완전히 실행되므로, 리뷰 도중 터미널을 자유롭게 사용할 수 있다.

세 가지 모두 홍보 문구가 아니다. /ultrareview의 아키텍처에서 그대로 나온 특성들이다. Verify 단계, 병렬 플릿, 원격 실행 — 각각이 '높은 신호', '넓은 커버리지', '로컬 리소스 무사용'의 실제 이유다.

2. 시작하기 — 사전 요건과 CLI 실행 순서

사전 요건 확인

/ultrareview를 실행하기 전에 두 가지 요건을 먼저 충족해야 한다.

요건 1: Claude Code v2.1.86 이상

/ultrareview는 Claude Code v2.1.86 이상에서 사용 가능하다.

명령어가 공식 추가된 시점은 v2.1.111(2026-04-16)이고, v2.1.113에서 UX 개선이 이뤄졌다. 2026-04-24 현재 최신 버전은 v2.1.119(2026-04-23 출시)이므로, 최신 버전으로 업데이트해 두는 것을 권장한다.

# 현재 버전 확인
claude --version

# npm으로 최신 버전 업데이트
npm install -g @anthropic-ai/claude-code

요건 2: Claude.ai 계정 인증

/ultrareview는 Claude Code on the web 인프라에서 실행되기 때문에 Claude.ai 계정 인증이 필요하다. API 키만으로 로그인한 상태라면 아래 명령을 먼저 실행해야 한다.

# API 키만으로 로그인된 경우 Claude.ai 인증 추가
/login

주의: Amazon Bedrock, Google Cloud Vertex AI, Microsoft Foundry 환경에서 Claude Code를 사용 중이면 /ultrareview를 실행할 수 없다. Zero Data Retention을 활성화한 조직도 마찬가지다.

CLI 실행 순서

사전 요건을 충족했다면, 실행 방법은 두 가지다.

방법 A: 현재 브랜치 리뷰

인수 없이 실행하면 현재 브랜치와 기본 브랜치(main/master) 간의 diff를 리뷰한다. 커밋되지 않은 스테이징 변경 사항도 포함된다.

# 현재 브랜치 전체 리뷰
/ultrareview

방법 B: GitHub PR 직접 리뷰

# PR 번호를 인수로 전달
/ultrareview 1234

PR 모드에서는 원격 샌드박스가 로컬 워킹 트리를 번들링하지 않고 GitHub에서 PR을 직접 클론한다.

이 모드는 저장소에 github.com 원격이 설정되어 있어야 한다.

실행 흐름: 확인 다이얼로그 → 백그라운드 실행 → 결과 수신

명령을 실행하면 곧바로 리뷰가 시작되지 않는다. 실행 전 확인 다이얼로그에서 세 가지 정보가 표시된다.

리뷰 범위 (파일 수·라인 수)
남은 무료 실행 횟수
예상 비용

확인 후 리뷰는 백그라운드에서 실행된다. 세션은 그대로 사용할 수 있다. 리뷰 진행 상황과 완료된 리뷰는 아래 명령으로 확인한다.

# 실행 중·완료된 리뷰 목록 확인
/tasks

리뷰 완료 시 검증된 발견 사항이 세션에 알림으로 표시되며, 각 발견 사항에는 파일 위치와 이슈 설명이 포함된다. Claude에게 곧바로 수정을 요청할 수 있다.

저장소가 너무 클 때

저장소가 너무 커 번들링이 불가한 경우, Claude Code는 PR 모드 사용을 권고한다. 브랜치를 푸시하고 draft PR을 열었다면 아래처럼 PR 번호를 직접 전달한다.

# 대용량 저장소: PR 번호로 전달
git push origin feature/my-branch
# GitHub에서 draft PR 생성 후
/ultrareview 1234

3. 작동 방식 — Find·Verify 파이프라인과 병렬 분석

병렬 탐색과 검증 단계

/ultrareview의 핵심 파이프라인은 두 단계로 구성된다. 공식 지원 문서는 이 흐름을 다음과 같이 설명한다.

"When a review runs, multiple agents analyze the diff and surrounding code in parallel. Each agent looks for a different class of issue, then a verification step checks results against actual code behavior to filter out false positives. Findings are deduplicated, ranked by severity, and posted as inline comments on the specific lines where issues were found."
(코드 리뷰가 실행되면, 여러 에이전트가 diff와 관련 코드 컨텍스트를 병렬로 분석합니다. 각 에이전트는 서로 다른 유형의 이슈를 탐지하며, 이후 검증 단계에서 실제 코드 동작과 대조하여 false positive를 제거합니다. 그 후 결과는 중복 제거 및 심각도 기준으로 정렬되며, 문제가 발견된 정확한 코드 라인에 inline 코멘트 형태로 게시됩니다.)

각 에이전트는 서로 다른 이슈 유형을 탐색한다(보안 취약점, 로직 오류, 타입 불일치 등). 이후 검증 단계에서 실제 코드 동작과 비교해 거짓 양성을 필터링한다. 중복을 제거한 뒤 심각도순으로 정렬해 결과가 나온다.

결과의 신뢰도

Anthropic 블로그는 내부 운영 결과를 구체적인 수치로 공개했다. 1,000줄 이상 대형 PR의 84%에서 발견 사항이 있으며 평균 7.5개 이슈가 보고됐다. 50줄 미만 소형 PR은 31%, 평균 0.5개 이슈를 기록했고, 엔지니어의 발견 사항 불일치율은 1% 미만이다.

1% 미만의 불일치율은 신뢰도가 매우 높다는 의미다. 이는 Verify 에이전트가 거짓 양성을 걸러내는 과정이 실질적으로 작동하고 있음을 보여준다. 단순히 버그 후보를 나열하는 것이 아니라, 재현 가능한 실제 버그만 통과시키는 구조다.

소요 시간

CLI 기반 /ultrareview는 리뷰에 약 5~10분이 소요된다. Team/Enterprise용 PR 통합 Code Review는 Anthropic 테스트 기준 평균 약 20분이며, PR 크기와 복잡도에 따라 확장된다. 큰 변경에는 더 많은 에이전트가 투입되고, 단순한 변경에는 가벼운 검토가 적용된다.

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

이 섹션은 공개된 공식 문서와 커뮤니티 분석을 바탕으로 한 추정이다. 물론 나도 직접 수행하여 테스트 해보았으니 이후에 있는 실제 수행 예시 섹션을 참고해도 좋다.

원격 샌드박스 구조 (추정)

공식 문서에 따르면 /ultrareview는 "Claude Code on the web 인프라"에서 실행된다. /ultraplan도 동일하게 Anthropic의 클라우드 인프라에서 실행되며 Bedrock/Vertex/Foundry 미지원, Claude Code on the web 계정 필수라는 동일한 제약을 공유한다는 점에서, 두 기능이 같은 인프라 레이어를 공유할 가능성이 높다고 추정된다.

HN 커뮤니티에서는 /ultrareview가 Mythos(Anthropic의 내부 에이전트 안전 레이어) 위에서 동작할 가능성에 대한 추측이 나왔다. HN 사용자 mchinen은 "seems at least plausible"이라고 평가했으나, 이는 커뮤니티 추론 수준이며 Anthropic이 공식 확인한 사실이 아니다.

에이전트 플릿 구성 (추정)

공식 문서는 "리뷰어 에이전트 플릿"이라고만 명시하고 에이전트 수를 공개하지 않는다. 비교 스펙 자료에는 기본 5개 에이전트로 추정되는 내용이 있으나, 이는 PR 크기에 따라 동적으로 달라지는 것으로 보인다고 추정된다. "Large or complex changes get more agents"라는 블로그 표현이 이를 뒷받침한다.

에이전트 구조는 추정상 두 레이어로 나뉜다. Find 레이어에서 각 에이전트가 서로 다른 버그 클래스(보안, 로직, 타입, 동시성 등)를 병렬 탐색하고, Verify 레이어에서 찾은 버그를 독립적으로 재현해 거짓 양성을 제거한다. 이 구조가 1% 미만 불일치율의 기반이 될 가능성이 높다.

ex) 비교적 작은 수정사항을 내가 직접 테스트 해보았다.

Case1. 리뷰 기회 낭비

- 전반적인 UX를 개선했던 사항 (처음 리뷰 이다보니 최대한 간단한 class 수정 작업에 대한 리뷰 요청)

❯ /ultrareview b32eae7

- 나도 처음 써보는 것이며, 3번의 기회중 1번을 사용해보겠다.

- 너무 간단한 예시였을까........................................... 충격적인 결과

- 자세히 보니 에러ㅠㅠ 버그가 아직 많은가?

Case2. 복잡한 소스 개발과 관련된 케이스 리뷰

- https://goddaehee.com/showcase/toktok-analyzer

❯ /ultrareview

- 로그는 보니 3 files changed, 65 insertions(+) 아무 파라미터를 주지 않으니 최신 커밋 기준으로 리뷰를 해버렸다 ㅠㅠ 아까운 기회..

❯ /ultrareview 특정 커밋 시점 다시 시도 해도 실패

- 나의 경우 이미 여러 멀티 에이전트를 통해 바이브 코딩시 자동 리뷰가 되다 보니 리뷰를 할 특이점이 딱히 없는가 싶어서 오래된 막 굴리던 프로젝트 대상으로 목표를 변경하였다.

어느정도 복잡한 프로젝트로 시작하니 관련 내용을 체크 하기 시작

❯ /ultrareview

- 9개의 후보군을 찾은 후 1개씩 체크 하는 과정

- Dead code를 포함하여 몇개의 이슈 확인

- 중복제거 까지 완료

- 이후 claude code에게 리뷰 완료를 알려주며 이후 작업을 이어 나갈수 있다.

너무 안타깝게 좀 복잡한 소스개발건에 대한, 그리고 대량 머지 요청에 대해 ultrarivew를 걸껄 내가 잘 못 한 것 같다.

너무 죄송스럽게도 얼마나 대단한지 알려 드리지 못 한 것 같다.

이후 다른분들의 커뮤니티 사례 또는 지인분들께 부탁하여 공유 드릴 수 있도록 하겠습니다!

5. 실전 적용 사례 — 치명적 버그 탐지 3가지

사례 1: 인증 장애를 머지 전에 막다

Anthropic 블로그는 내부 운영 사례를 구체적으로 공개했다.

"In one case, a one-line change to a production service looked routine and was the kind of diff that normally gets a quick approval. But Code Review flagged it as critical. The change would have broken authentication for the service, a failure mode that's easy to read past in the diff but obvious once pointed out. It was fixed before merge, and the engineer shared afterwards that they wouldn't have caught it on their own."

(TrueNAS 오픈소스 미들웨어의 ZFS 암호화 리팩토링 작업 중, 코드 리뷰를 통해 기존 코드에 숨어 있던 버그가 드러났습니다. 타입 불일치로 인해 sync가 수행될 때마다 암호화 키 캐시가 무음으로 초기화되는 문제였는데, 이는 PR에서 직접 수정한 코드가 아니라 그 주변 코드에 잠재되어 있던 이슈였습니다. 이런 종류의 문제는 일반적으로 변경된 diff만 확인하는 인간 리뷰어라면 쉽게 찾아내기 어려운 케이스입니다.)

한 줄짜리 변경이 프로덕션 서비스의 인증을 통째로 깨뜨릴 수 있었다. 사람 리뷰어가 빠르게 승인하고 넘겼을 diff를 Code Review가 critical로 표시했고, 머지 전에 수정됐다. 담당 엔지니어 스스로도 잡지 못했을 것이라고 인정한 케이스다.

사례 2: ZFS 암호화 리팩터에서 잠재 버그 발굴

오픈소스 프로젝트에서도 사례가 확인됐다.

"On a ZFS encryption refactor in TrueNAS's open-source middleware, Code Review surfaced a pre-existing bug in adjacent code: a type mismatch that was silently wiping the encryption key cache on every sync. It was a latent issue in code the PR happened to touch, the kind of thing a human reviewer scanning the changeset wouldn't immediately go looking for."

이게 사실 더 의미 있는 부분이다. PR이 직접 건드리지 않은 인접 코드에서 타입 불일치를 찾아냈다. 매 동기화마다 암호화 키 캐시가 날아가고 있었는데, diff를 훑어보는 사람 리뷰어라면 굳이 그 코드를 들여다볼 이유가 없다.

사례 3: 커버리지 격차 — 실질 리뷰가 16%에서 54%로

Code Review 도입 전 Anthropic 내부에서는 PR의 16%만 실질적 리뷰 코멘트를 받았다. 도입 후 이 비율이 54%로 높아졌다. 코드 산출량이 200% 증가한 상황에서 사람 리뷰어가 모든 PR을 커버하기는 구조적으로 어렵다. 멀티 에이전트 자동화가 이 격차를 메운 것이다.

6. 요금제 및 제한사항

요금 구조 (2026-04-24 기준)

만료 임박: Pro/Max 무료 3회 실행 기간이 2026-05-05(11일 후)에 종료된다. 아직 무료 실행을 사용하지 않은 Pro/Max 구독자라면 만료 전에 사용하는 것을 권장한다. 만료 후에는 회당 $5~$20이 추가 사용량으로 과금된다. 요금 정보는 research preview 기간 중 변경될 수 있으므로, 실행 전 공식 ultrareview 문서에서 최신 정보를 확인한다.

플랜	무료 실행	무료 종료 후
Pro	3회 (2026-05-05까지)	추가 사용량으로 청구
Max	3회 (2026-05-05까지)	추가 사용량으로 청구
Team	없음	추가 사용량으로 청구
Enterprise	없음	추가 사용량으로 청구

Pro/Max 구독자는 3회 무료 실행을 제공받는다. 이 3회는 계정당 1회성 할당으로, 갱신되지 않으며 2026년 5월 5일에 만료된다. 무료 실행 소진 또는 만료 후에는 변경 크기에 따라 약 $5~$20이 추가 사용량으로 과금된다.

Team/Enterprise용 PR 통합 Code Review는 토큰 사용량 기반으로 청구되며 PR 크기·코드베이스 복잡도·검증 이슈 수에 따라 평균 $15~$25가 소요된다.

추가 사용량(extra usage) 활성화 필수

유료 리뷰를 실행하기 전에 계정 또는 조직에서 추가 사용량(extra usage)이 활성화되어 있어야 한다. 미활성화 시 Claude Code가 실행을 차단하고 결제 설정 페이지로 안내한다. 아래 명령으로 현재 설정을 확인하거나 변경할 수 있다.

# 추가 사용량 설정 확인·변경
/extra-usage

제약 사항

/ultrareview를 사용할 수 없는 환경은 공식 문서에 명시되어 있다. 2026-04-24 현재 최신 버전(v2.1.119) 기준으로 변경 없이 유지 중이다.

Amazon Bedrock으로 Claude Code를 사용하는 경우
Google Cloud Vertex AI로 Claude Code를 사용하는 경우
Microsoft Foundry로 Claude Code를 사용하는 경우
Zero Data Retention(ZDR)을 활성화한 조직
self-hosted GitHub Enterprise Server 저장소 (PR 모드 시)

7. /review vs /ultrareview vs Skill 기반 리뷰 비교

/review와 /ultrareview 공식 비교표

공식 문서는 두 명령어의 차이를 아래와 같이 정리한다.

항목	`/review`	`/ultrareview`
실행 위치	로컬 세션	원격 클라우드 샌드박스
깊이	단일 패스 리뷰	독립 검증 포함 멀티 에이전트 플릿
소요 시간	수초~수분	약 5~10분
비용	일반 사용량 포함	3회 무료, 이후 약 $5~$20 추가 과금
결과 검증	단일 패스	Verify 에이전트가 독립 재현 확인
적합 상황	작업 중 빠른 피드백	상당한 변경 머지 전 심층 검증

한 줄로 요약하면: /review는 속도를 최적화하고, /ultrareview는 신뢰도를 최적화한다.

Skill 기반 코드 리뷰와의 차이

Claude Code에는 사용자가 직접 정의한 커스텀 Skill로 코드 리뷰를 수행하는 방법도 있다. Anthropic 블로그는 /ultrareview(및 Code Review)가 오픈소스 Claude Code GitHub Action보다 더 심층적이고 더 비싼 선택지라고 명시하며, GitHub Action은 여전히 오픈소스로 제공된다고 밝혔다.

항목	내장 /ultrareview	Skill 기반 리뷰	Claude Code GitHub Action
설정	제로 설정	커스텀 CLAUDE.md 작성 필요	.github/workflows 설정 필요
실행 환경	원격 샌드박스	로컬 세션	GitHub Actions 러너
거짓 양성 필터	Verify 에이전트 내장	해당 없음	해당 없음
비용	$5~$20/회 (무료 3회 제공)	일반 사용량 포함	오픈소스, 별도 API 비용
커스터마이징	불가	자유롭게 정의 가능	워크플로 수준 설정
GitHub 인라인 코멘트	미지원 (CLI 기준)	해당 없음	지원

한 줄로 요약하면: /ultrareview는 설정 없이 즉시 쓸 수 있는 심층 리뷰이고, Skill 기반 리뷰는 팀의 리뷰 기준을 완전히 제어하고 싶을 때 선택한다.

7-1. 비용 논란 — 커뮤니티 반응

요금 체계 변경에 대한 혼란

요금 구조와 관련해 커뮤니티에서 의미 있는 반응이 나왔다. Simon Willison의 기술 블로그(2026-04-22)는 Claude Code 요금 체계 변경에 대한 커뮤니티 혼란을 정리했다.

"A whole lot of people got scared or angry or both that a service they relied on was about to be rug-pulled. There really is a significant difference between $20/month and $100/month for most people, especially outside of higher salary countries."

Pro에서 Max로의 전환 시 $20→$100/월 가격 점프에 대한 불만이 컸다. 특히 고소득 국가 외 개발자들에게 $100/월은 접근 장벽이 된다는 지적이다. /ultrareview의 회당 $5~$20 추가 과금도 이 맥락에서 받아들여졌다.

Anthropic 가격 실험 논란

혼란의 직접적 원인이 된 사건도 있다. The Register(2026-04-22) 보도에 따르면, Anthropic은 신규 Pro 가입자 약 2%를 대상으로 Claude Code를 Pro 플랜 공개 요금 페이지에서 제외하는 실험을 진행했다. 기존 Pro/Max 구독자는 영향을 받지 않았으나, 온라인 포럼에서 가입자들은 서비스가 갑자기 변경될 것이라는 불안을 표출했다.

이는 /ultrareview의 비용 논쟁과 맞물려 더 큰 파장을 일으켰다. 구독 플랜에서 기능을 제외하고 추가 과금으로 전환하는 방향에 대한 불신이 누적된 상태에서 나온 실험이었기 때문이다. Anthropic 입장에서는 소수 대상 A/B 테스트였지만, 커뮤니티가 이를 정책 변경의 신호로 해석한 것이다.

팀 vs 솔로 개발자 시각 차이

비용 논쟁은 사용 규모에 따라 관점이 갈린다. BuildFastWithAI 블로그는 "하루 3~4개 이상 PR을 머지하는 팀에서는 비용이 정당화되지만, 솔로 개발자에게는 부담스럽다"고 정리했다. 이는 커뮤니티 출처의 평가로, 개인 경험에 따라 다를 수 있다.

Reddit r/ClaudeCode에서는 사용량 한도 정책(주간 상한 추가)에 대한 불만이 별도로 이어졌다. $200/월 플랜 사용자가 주말 전에 주간 상한에 도달했다는 보고가 나왔고, Anthropic은 공식 서브레딧에서 버그 2건이 해결됐다고 응답하며 의도적 성능 저하를 부인했다. 이 내용은 간접 보고 기반으로, 독립 검증이 어렵다.

한편, /ultrareview는 정식 출시(v2.1.111, 2026-04-16) 이전인 2026-03-31에 v2.1.88 소스맵 유출을 통해 커뮤니티에 먼저 발견됐다. Product Hunt에도 등록됐으며, 실제 엔지니어링 문제를 해결하는 기능으로 긍정적 반응을 얻었다. 비용 때문에 시끄러운 와중에도 기능 자체는 쓸 만하다는 평가는 일관됐다.

행동지침

비용 논란에서 개발자가 취할 수 있는 실질적 판단 기준은 다음과 같다.

머지 전 치명적 버그 탐지 가치 > $5~$20: /ultrareview가 정당화된다 (인증 로직, 데이터 마이그레이션, 대규모 리팩터 등)
빠른 피드백 루프가 필요한 반복 작업: /review가 더 적합하다
팀 단위 PR 자동화: Team/Enterprise Code Review를 검토한다
비용 부담이 있는 솔로 개발자: 무료 3회를 중요한 PR에 집중 사용하고, 이후는 /review와 병행한다

7-2. 앤트로픽의 슬래시 명령어 전략

내장 명령어 확장 패턴

/ultrareview는 독립된 기능이 아니라 Anthropic의 슬래시 명령어 전략의 일부다. Claude Code v2.1.111에서 /ultrareview, /effort(xhigh 포함 인터랙티브 슬라이더), /less-permission-prompts 등 새로운 내장 슬래시 명령어가 일괄 추가됐다.

패턴은 명확하다. 높은 영향력이 있는 특정 워크플로를 사용자 정의 Skill이 아닌 내장 명령어로 표준화하는 방향이다. v2.1.113에서는 /ultrareview의 병렬화된 검사로 더 빠른 시작, 시작 다이얼로그에 diffstat 추가, 애니메이션 실행 상태 표시 등 UX 개선이 이어졌다. 내장 명령어가 Skill과 달리 버전별 지속 관리된다는 의미다.

이후 v2.1.114~v2.1.119(2026-04-18~04-23) 기간에는 /ultrareview 관련 직접 변경사항은 없다. 다만 v2.1.119에서 prUrlTemplate 설정이 추가됐는데, 이는 Team/Enterprise Code Review의 PR 배지 URL을 커스터마이징하는 기능으로 CLI /ultrareview 동작에는 영향이 없다. 핵심 기능은 v2.1.111(출시)·v2.1.113(UX 개선)에 집중됐고 이후 안정화 단계에 있다.

ultraplan과의 공통 구조

/ultraplan도 동일한 패턴을 따른다. /ultraplan은 Anthropic의 클라우드 인프라에서 실행되며, Bedrock/Vertex/Foundry 미지원, Claude Code on the web 계정 필수라는 /ultrareview와 동일한 제약을 공유한다.

공통점은 세 가지다. 원격 인프라 활용, API 키만으로 사용 불가, 추가 사용량으로 별도 청구. 이 구조는 "클라우드 기반 고영향 워크플로를 내장 명령어로, 단순 작업은 Skill/API로"라는 계층 분리를 보여준다.

정량제(pay-per-use) 전환 트렌드

/ultrareview는 구독 플랜 포함 사용량이 아닌 '추가 사용량(extra usage)'으로 별도 청구되는 premium 기능이다. 이는 구독 플랜 외 정량제 과금 모델의 첫 사례다.

월정액 구독과 정량제를 병행하는 이 모델은, AI 도구 업계에서 '기본 플랜 + 고급 기능 추가 과금'으로 수익을 다각화하는 흐름과 맞닿아 있다. Anthropic 입장에서는 심층 리뷰처럼 컴퓨팅 집약적 기능을 구독에 묶으면 단가를 올리거나 수익성이 악화되므로, 별도 과금이 합리적 선택이다. 독자 입장에서는 필요한 리뷰에만 비용을 지불하는 선택지가 생겼다는 의미다.

8. 결정 매트릭스 + 도입 플레이북

언제 /ultrareview를 쓰는가 / 언제 쓰지 않는가

상황	권장 도구	이유
인증·권한 로직 변경 머지 전	`/ultrareview`	한 줄 변경이 인증을 깨뜨릴 수 있다
데이터 마이그레이션 스크립트 검토	`/ultrareview`	데이터 손실 리스크 최소화
1,000줄 이상 대규모 리팩터	`/ultrareview`	84% 확률로 평균 7.5개 이슈 발굴
작업 중 빠른 피드백 루프	`/review`	수초 내 결과, 비용 없음
간단한 버그 픽스·텍스트 수정	`/review`	`/ultrareview` 비용 대비 효과 낮음
팀 전체 PR 자동화	Team Code Review	PR 생성 시 자동 트리거 가능
리뷰 기준을 직접 제어하고 싶을 때	Skill 기반 리뷰	완전한 커스터마이징 가능
Bedrock/Vertex/Foundry 환경	`/review` 또는 Skill	`/ultrareview` 사용 불가

한 줄로 요약하면: /ultrareview는 치명적 버그 리스크가 있는 PR의 신뢰도를 최적화하고, /review는 반복 작업 중 빠른 피드백 속도를 최적화한다.

도입 플레이북

오늘 바로 시작하기

# 1. 버전 확인 (v2.1.86 이상, 최신 v2.1.119 권장)
claude --version

# 2. Claude.ai 인증 추가 (API 키만 있는 경우)
/login

# 3. 추가 사용량 설정 확인
/extra-usage

# 4. 중요한 브랜치에서 무료 3회 중 1회 사용
/ultrareview

이번 주 워크플로 통합

무료 3회를 가장 위험한 PR에 집중 투자한다. 인증 변경, DB 마이그레이션, 대규모 리팩터 순서로 우선순위를 정하는 것을 권장한다. 결과를 받은 뒤 Claude에게 발견 사항을 바로 수정 요청할 수 있다는 점도 활용한다.

운영 반영 시 고려사항

현재 research preview 상태이므로 운영 환경에 의존적으로 통합하기 전에 몇 가지를 확인해야 한다. 2026-05-05 무료 기간 만료 후 비용 구조가 팀 예산에 맞는지 검토하고, ZDR 조직이나 Bedrock/Vertex 환경이라면 대안(Skill 기반 또는 GitHub Action)을 병행 준비한다.

리뷰 커버리지가 16%에서 54%로 올라간 건 데이터가 말한다. 코드 산출량은 200% 늘었는데 리뷰어 수는 그대로다. 자동화 말고 이 격차를 메울 방법이 없다.

이 글의 요금·기능 정보는 2026-04-24 기준이다. /ultrareview는 research preview 기능으로, 기능·요금·가용성은 Anthropic의 피드백 반영에 따라 변경될 수 있다. 실행 전 공식 문서에서 최신 정보를 확인할 것을 권장한다.

OpenAI GPT-5.5 리뷰 : 에이전틱 AI의 새 기준인가, 가격 2배 인상의 정당화인가 - 벤치마크부터 환각률까지

갓대희 — Fri, 24 Apr 2026 18:00:02 +0900

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

6주마다 새 모델이 나오는 시대다. GPT-5.4 출시 6주 만인 2026년 4월 23일, OpenAI는 GPT-5.5를 공개했다.

Fortune은 이를 두고 "AI 모델 출시가 소프트웨어 업데이트처럼 보이기 시작했다"고 평했다. (Fortune, 2026-04-23)

그러나 이번 릴리즈는 단순한 버전 숫자 올림이 아니다.

GPT-5.5는 에이전틱 AI, 즉 스스로 계획하고 도구를 사용해 장시간 작업을 완수하는 AI로의 전환을 선언한다. 동시에 API 가격은 전작 대비 2배로 올랐고, 독립 기관의 환각률 측정에서는 업계 최고 수준의 부담스러운 수치를 기록했다.

이 글에서는 공식 발표와 벤치마크 데이터를 기반으로 GPT-5.5의 성능·가격·한계·경쟁 모델 비교를 정리했다. 여기에 더해 GPT-5.5 Pro에게 직접 단일 프롬프트로 게임 6개를 만들게 한 실험 결과도 함께 담았다. 도입을 고민 중인 개발자와 담당자에게 판단 근거가 됐으면 한다.

소개 + 핵심 가치
시작하기: 모델 계층과 가용성
주요 기능 상세
공개 정보 기반 아키텍처 추정
실전 사용 경험 + 직접 만든 GPT-5.5 게임 6선
요금제 및 제한사항
대안 비교: Claude Mythos Preview vs Claude Opus 4.7 vs Gemini 3.1 Pro
트러블슈팅 Q&A + 결론

1. 소개 + 핵심 가치

GPT-5.5가 해결하려는 문제

GPT-5.5는 OpenAI가 공식적으로 "실제 업무와 에이전트 구동을 위한 새로운 수준의 지능(A new class of intelligence for real work and powering agents)"으로 정의한 모델이다.

단순 Q&A Assistant를 넘어, 복잡한 코딩·과학 연구·사무 자동화 등 멀티스텝 에이전틱 업무를 처리하는 것이 핵심 포지셔닝이다.

OpenAI의 Greg Brockman은 GPT-5.5의 특징을 이렇게 설명했다.

"더 적은 토큰으로 더 빠르고 날카로운 사고를 합니다. 비즈니스와 소비자 모두에게 더 많은 프론티어 AI를 제공하는 것이 우리 목표입니다."

토큰 효율성과 추론 속도를 동시에 올리겠다는 이야기다. 더 많이 계산하는 게 아니라, 같은 시간에 더 적은 토큰으로 더 높은 품질을 내겠다는 것.

6주 릴리즈 주기와 업계 반응

GPT-5.4가 2026년 3월 5일 출시됐고, GPT-5.5는 4월 23일 나왔다. 간격은 6주만이다.

"단기적으로 상당한 개선, 중기적으로 매우 큰 개선이 예상됩니다. 사실 지난 2년은 놀랍도록 느렸다고 생각합니다."

이 속도를 유지하거나 더 빠르게 가겠다는 의도가 보인다. 개발자 입장에서는 6~8주 단위로 모델 평가 주기를 맞춰야 할 수도 있다.

ex) ChatGPT 환경에서 확인해보자.

- https://chatgpt.com/ 접속

- 좌상단의 모델 리스트 선택 > 구성... 클릭

- 5.5 모델을 선택할 수 있음을 확인 가능하다.

- 코덱스 최신 버전에서 실행 (나의 경우 : 0.124.0 버전 )

> GPT5.5 버전을 사용할 수 있음을 바로 안내해준다.

( 자세한 업데이트 내용은 공식문서를 참고 하라는 내용 : https://openai.com/index/introducing-gpt-5-5/ )

- /model 입력하여 변경해보자.

- xhigh는 간단한 업무엔 너무 과하니 high로 선택 하였다.

- ChatGPT든, Codex든 이제 5.5를 사용해볼 준비는 완료 되었다. 다만 간단히 이론을 살펴보고 갈 예정이다.

2. 시작하기: 모델 계층과 가용성

네 가지 모델 계층

GPT-5.5는 단일 모델이 아니라 네 가지 계층으로 구성된다.

모델	특징	적합한 용도
GPT-5.5 (기본)	표준 성능, 범용	일반 개발, 콘텐츠 생성
GPT-5.5 Thinking	응답 전 내부 검증으로 정확도 향상	고정밀 수학·과학·법률 분석
GPT-5.5 Pro	최상위 성능	최전선 연구·엔터프라이즈 자동화
Fast Mode	1.5배 빠른 토큰 생성, 비용 2.5배	실시간 응답이 필요한 프로덕션 서비스

Fast Mode는 속도를 위해 비용을 2.5배 지불한다. 비용 민감 서비스라면 Batch/Flex 옵션(50% 할인)과의 트레이드오프를 반드시 계산해야 한다.

플랜별 가용성

GPT-5.5 기본 모델은 Plus, Pro, Business, Enterprise 플랜에서 사용 가능하다. GPT-5.5 Pro는 Pro, Business, Enterprise 전용이다. 개인 무료 사용자는 GPT-5.5에 접근할 수 없다.

컨텍스트 윈도우

ChatGPT 환경의 최대 컨텍스트는 1,000,000 토큰(1M)이다. Codex 환경에서는 400K 토큰으로 제한된다. 1M 컨텍스트는 수백 페이지 분량의 문서를 한 번에 넣을 수 있는 수준이며, 이 용량을 실제로 활용하는 능력은 3절과 4절에서 벤치마크로 확인한다.

3. 주요 기능 상세

에이전틱 코딩: Terminal-Bench 2.0과 Expert-SWE

Terminal-Bench 2.0은 계획·반복·도구 협조가 필요한 복잡한 명령줄 워크플로우를 테스트하는 벤치마크이다. GPT-5.5는 이 벤치마크에서 82.7%를 기록했고, 전작 GPT-5.4는 75.1%였다.

Expert-SWE는 OpenAI가 개발한 내부 벤치마크로, 인간이 완료하는 데 중간 예상 시간이 20시간인 장기 코딩 태스크를 측정한다. GPT-5.5는 여기서 73.1%를 달성했다. 20시간짜리 코딩 작업을 70% 이상 완수한다는 건, 자동완성 수준이 아니라는 뜻이다.

컴퓨터 사용: OSWorld-Verified 78.7%

OSWorld-Verified는 실제 데스크톱 환경에서 마우스·키보드 조작, 파일 관리, 앱 실행 등을 포함한 컴퓨터 사용 능력을 평가한다. GPT-5.5는 78.7%를 기록했다. OpenAI의 Mark Chen은 "컴퓨터 작업 탐색 능력이 전작보다 훨씬 뛰어나다"고 밝혔다.

비교 맥락에서 보면, Claude Opus 4.7도 같은 벤치마크에서 78.0%를 기록해 GPT-5.5와 거의 동등하다. 컴퓨터 사용 영역은 현재 두 모델이 사실상 동률로 경쟁 중이다.

지식 노동: GDPval 84.9%

GDPval은 44개 직종에 걸친 지식 노동 능력을 평가하는 벤치마크다. GPT-5.5는 84.9%(wins/ties)를 기록했다. 고객 서비스 워크플로우를 평가하는 Tau2-bench Telecom에서는 프롬프트 튜닝 없이 98.0%라는 높은 수치를 기록했다.

단, GDPval 기준 전작 GPT-5.4는 83.0%였다. 1.9%p 향상이다. 일반적인 전문 사무 업무에서 체감 향상이 얼마나 뚜렷할지에 대해서는 6절에서 단점과 함께 다룬다.

과학 연구: FrontierMath와 장문 컨텍스트

수학 분야에서 GPT-5.5는 FrontierMath Tier 1-3에서 51.7%, 최고 난도인 Tier 4에서 35.4%를 기록했다. Claude Opus 4.7과 Gemini 3.1 Pro를 크게 앞서는 수치다.

Mark Chen은 "과학적·기술적 연구 워크플로우에서 의미 있는 향상이 있으며, 전문 과학자들의 연구 진보를 실질적으로 도울 수 있다"고 밝혔다.

장문 컨텍스트 처리도 주목할 만한 도약을 보였다. MRCR v2(512K~1M 토큰)에서 GPT-5.5는 74.0%로, 전작 GPT-5.4의 36.6% 대비 2배 이상 향상됐다. 1M 토큰 Graphwalks BFS 태스크에서는 45.4%로, 전작(9.4%) 대비 약 5배 향상됐다.

웹 리서치: BrowseComp

BrowseComp에서 GPT-5.5 기본 모델은 84.4%, GPT-5.5 Pro는 90.1%를 기록했다. 웹 검색·리서치가 핵심인 워크로드에서 GPT-5.5 Pro는 Claude Opus 4.7(79.3%)을 10%p 이상 앞선다. 단, 기본 모델 기준으로는 Gemini 3.1 Pro(85.9%)에 소폭 뒤처진다는 점은 유의할 필요가 있다.

도구 사용: Toolathlon

도구 사용 능력을 평가하는 Toolathlon 벤치마크에서 GPT-5.5는 55.6%로 Gemini 3.1 Pro(48.8%)를 앞섰다. 전작 GPT-5.4(54.6%)와 비교하면 소폭 향상됐다.

MCP Atlas(Scale AI 운영 도구 사용 벤치마크, 75.3%)에서 경쟁 모델에 뒤지는 것과 대비하면, Toolathlon에서는 GPT-5.5가 우위를 보인다. 두 벤치마크의 결과가 엇갈리는 만큼, 도구 사용 능력 평가 시 어떤 종류의 도구 워크플로우가 핵심인지에 따라 판단 기준을 달리해야 한다.

안전성 평가: 역대 가장 강력한 가드레일

GPT-5.5는 Preparedness Framework v2에 따라 사이버 보안·생물학·화학 세 분야 모두에서 'High' 등급 평가를 받았다. Critical 등급에는 해당하지 않으나, 세 분야 모두 High로 분류된 것은 능력 향상에 따른 위험 수준이 상당함을 의미한다.

이에 따라 OpenAI는 GPT-5.5에 역대 가장 강력한 안전 분류기(classifier)를 적용했다. 특히 CyberGym 벤치마크 성능(81.8%)이 향상되면서, 초기에는 사이버 관련 요청 거부율이 높아질 수 있다고 공식 안내했다.

보안 연구자를 위한 별도 채널도 마련됐다. Trusted Access for Cyber 프로그램을 통해 검증된 보안 연구자와 주요 인프라 관리자에게는 제한 완화 모델(예: GPT-5.4-Cyber) 접근이 제공된다. 강화된 가드레일이 보안 전문 업무의 활용성을 제한하는 문제를 해결하기 위한 제도적 완충 장치다.

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

이 섹션은 공개된 정보를 기반으로 한 추정이다. OpenAI는 내부 아키텍처를 공개하지 않으므로, 아래 내용은 공식 발표에서 확인된 사실과 그로부터의 합리적 추론이 혼재한다. 공식 확인이 필요한 결정에는 이 섹션을 단독 근거로 사용하지 않도록 권한다.

NVIDIA GB200 NVL72 기반 인프라

OpenAI는 공식 블로그에서 GPT-5.5의 훈련 및 서빙 인프라가 NVIDIA GB200 NVL72 및 GB300-NVL72 시스템 기반으로 최적화됐다고 밝혔다. GB200 NVL72는 72개의 Blackwell GPU를 NVLink로 연결한 대규모 추론 특화 시스템으로, 초고밀도 행렬 연산과 대규모 배치 처리에 유리하다.

자기 최적화: Codex가 인프라를 개선하다

이번 발표에서 가장 주목받은 대목은 GPT-5.5(Codex)가 OpenAI 자사의 서빙 인프라를 스스로 최적화했다는 사실이다.

"Codex가 프로덕션 트래픽 패턴을 분석하고, 부하 분산을 위한 자체 휴리스틱 알고리즘을 작성해 토큰 생성 속도를 20% 이상 향상시켰다."

이 사례는 AI가 단순 코드 보조를 넘어, 실제 프로덕션 시스템의 성능 엔지니어링을 수행할 수 있음을 OpenAI가 공개적으로 시연한 것이다. GPT-5.5 자신이 자신의 서빙 속도를 높인 셈이다. 공개 발표에서 확인된 수치는 "20% 이상"이며, 구체적인 알고리즘 세부 사항은 공개되지 않았다.

토큰 효율성 향상 추정

OpenAI는 GPT-5.5가 GPT-5.4와 동일한 토큰당 지연시간(per-token latency)을 유지하면서, 동일한 Codex 작업에 현저히 적은 토큰을 사용한다고 밝혔다. 이를 기반으로 추정하면 GPT-5.5는 훈련 효율성이나 추론 최적화 측면에서 전작 대비 상당한 개선이 이뤄진 것으로 보인다. 다만 정확한 모델 규모나 아키텍처 변경 사항은 공개되지 않았으므로, 이 부분은 추정이다.

5. 사용 경험 리서치 + 직접 만든 GPT-5.5 게임 6선

엔터프라이즈 도입 사례

BNY(뉴욕멜론은행): 220개 AI 사용 사례

BNY의 Leigh-Ann Russell은 GPT-5.5 도입 효과에 대해 이렇게 밝혔다.

"5.5에서 실제로 중요하게 보고 있는 것은 응답 품질과 더불어 인상적인 환각 저항성입니다. 은행은 매우 높은 정확도가 필요하므로 이는 매우 중요합니다. 220개 이상의 AI 사용 사례를 스케일업하는 데 도움이 됩니다."

은행처럼 정확도가 생명인 곳에서 환각 저항성이 얼마나 중요한 변수인지 잘 보여주는 사례다. 220개 AI 사용 사례를 이미 돌리고 있는 기관이 환각 저항성을 선택 근거로 들었다면, 마케팅이 아닌 실제 검증 결과다.

OpenAI 내부 재무팀: K-1 세금 양식 71,637페이지

OpenAI 자체 재무팀이 Codex GPT-5.5를 활용해 71,637페이지, 24,771개의 K-1 세금 양식을 검토하고 전년 대비 작업 시간을 2주 단축했다.

숫자가 인상적이다. 7만 페이지 세무 서류를 AI가 검토해서 2주 단축. 단순 보조 도구 이상이다.

면역학 교수 Derya Unutmaz: 28,000개 유전자 분석

면역학 교수 Derya Unutmaz는 28,000개 유전자가 포함된 데이터 분석으로 수개월치 연구 보고서를 완성했다. 대규모 바이오인포매틱스 데이터 처리에서 1M 컨텍스트가 실제로 쓰인 사례다.

수학 앱 11분 완성과 램지 수 증명

Greg Brockman이 인용한 사례에서, 한 수학 교수가 GPT-5.5와 Codex를 써서 프롬프트 하나로 11분 만에 대수기하학 앱을 완성했다.

OpenAI 내부 수학 연구팀은 GPT-5.5를 활용해 조합론 난제인 비대각 램지 수(Ramsey numbers)에 대한 새로운 수학적 증명을 발견했고, Lean으로 공식 검증을 완료했다. 수학 연구에서 AI가 발견 기여자로 등장한 사례다.

ex) 나도 내가 사용하고 있는 스킬 개선 계획을 한번 GPT5.5 모델을 통해 세워보게 하였다.

- 해당스킬이 어떤건지, 개선안이 유효한지는 볼 것 까진 없을 것 같지만, 얼마나 오랜기간 생각을했고, 어떤 제안을 줬는지 이력을 남겨는 두려고 한다. 10분 넘게 작업을 한것 같아서 정확히 걸린 시간은 보지 못했지만, 엄청 깊은 분석을 했음에 확실한 내용은 받아볼 수 있었다.

1. 검토 방식

이번 작업은 skill-creator 관점도 함께 사용했습니다.
현재 작업은 스킬(skill) 자체를 고치는 문제라서, 기존 context-planner 문서만 보는 것보다 “좋은 스킬 파일은 어떻게 구성되고 운영되어야 하는가”라는 기준도 함께 보는 것이 더 적절했습니다.

검토한 주요 대상은 다음과 같습니다.

- skill-creator의 SKILL.md
- context-planner의 SKILL.md
- README.md
- AGENTS.md
- context-planner-prompt.md
- plan-template.md
- plan-template-lite.md
- plan-template-full.md
- playbook.md
- context-pack-spec.md
- prompt-pack.md
- generate-spec.js
- cases/*/plan.md
- examples/*.md
- docs/retro/2026-04-24-spec-review/*.md

작업 경로 예시는 다음과 같이 확인했습니다.

- /Users/dedur/work/context-to-planning
- /Users/dedur/work/context-to-planning/generate-spec.js
- /Users/dedur/work/context-to-planning/.claude/skills/context-planner/SKILL.md

2. 함께 검토한 역할

여러 관점에서 보기 위해 다음 역할을 나누어 검토했습니다.

- prompt-engineer
  - 프롬프트 구조와 스킬 실행 흐름을 검토했습니다.
- documentation-engineer
  - README, AGENTS, onboarding 문서처럼 사용자가 읽는 문서를 검토했습니다.
- code-reviewer
  - generate-spec.js와 관련 코드 구조를 검토했습니다.
- research-analyst
  - 회고 문서와 실제 산출물의 문제 패턴을 비교했습니다.

3. 전체 결론

현재 context-planner 스킬의 방향은 틀리지 않았습니다.
plan.md는 범위, Open Question(OQ), source 같은 중요한 정보를 비교적 잘 보존하고 있습니다.

문제는 스킬 자체가 완전히 실패했다는 것이 아닙니다.
핵심 문제는 다음 문서와 코드 사이의 약속이 명확하지 않다는 점입니다.

- plan.md
- template 문서
- README / AGENTS / onboarding 문서
- generate-spec.js
- spec.pptx 생성 로직

쉽게 말하면, plan.md에는 중요한 내용이 잘 들어가 있는데, 이 내용을 PPTX로 바꾸는 과정에서 의미가 줄어들거나 잘못 표현될 수 있습니다.

특히 QA, 완료 기준, 착수 판단 같은 내용은 사람이 읽을 때는 어느 정도 이해할 수 있지만, PPTX 생성기가 읽을 때는 구조가 명확하지 않아 정보가 손상될 가능성이 큽니다.

4. 핵심 문제 1: QA와 완료 기준 구조가 약함

현재 plan-template-lite.md의 완료 기준은 자유로운 bullet 형태로 되어 있습니다.
반면 generate-spec.js는 기대 결과가 없으면 기본값으로 “Pass”를 넣는 구조가 있습니다.

관련 위치는 다음과 같습니다.

- /Users/dedur/work/.claude/skills/context-planner/references/plan-template-lite.md:65
- /Users/dedur/work/context-to-planning/generate-spec.js:208
- /Users/dedur/work/context-to-planning/generate-spec.js:1411

이 구조의 문제는 다음과 같습니다.

- 완료 기준이 구체적인 테스트 조건으로 정리되지 않을 수 있습니다.
- 기대 결과가 비어 있으면 “Pass” 같은 너무 단순한 값으로 대체될 수 있습니다.
- 결과적으로 QA 담당자가 실제로 무엇을 확인해야 하는지 알기 어려워질 수 있습니다.
- PPTX에서는 검증 내용이 있어 보이지만, 실제 테스트 기준으로는 부족할 수 있습니다.

개선 방향은 완료 기준을 표로 바꾸는 것입니다.

권장 컬럼은 다음과 같습니다.

- ID
- 검증 시나리오
- 기대 결과
- 우선순위
- 테스트 데이터 또는 조건
- 상태

예시는 다음과 같습니다.

| ID | 검증 시나리오 | 기대 결과 | 우선순위 | 테스트 데이터/조건 | 상태 |
|---|---|---|---|---|---|
| QA-01 | 사용자가 필수 값을 입력하고 저장한다 | 저장 성공 메시지가 표시된다 | High | 정상 입력값 | Ready |
| QA-02 | 사용자가 필수 값을 비우고 저장한다 | 필수 입력 안내 메시지가 표시된다 | High | 빈 입력값 | Ready |
| QA-03 | Open Question에 걸린 조건을 확인한다 | 조건 확정 전까지 테스트가 Blocked로 표시된다 | Medium | OQ-01 의존 | Blocked |

5. 핵심 문제 2: 착수 판단과 Open Question 의미가 PPTX에서 약해짐

plan.md 안에는 다음과 같은 중요한 판단이 들어 있습니다.

- 지금 바로 시작 가능한지
- 보류해야 하는지
- 2Phase로 넘겨야 하는지
- fallback이 필요한지
- Open Question(OQ)이 어떤 작업을 막고 있는지

하지만 generate-spec.js는 일부 구간에서 “가능”이라는 단어가 들어간 bullet만 뽑는 방식으로 동작할 수 있습니다.

관련 위치는 다음과 같습니다.

- /Users/dedur/work/context-to-planning/generate-spec.js:1236

이 방식의 문제는 다음과 같습니다.

- “보류 권고” 같은 중요한 판단이 빠질 수 있습니다.
- “2Phase 이관” 같은 일정 판단이 약하게 표현될 수 있습니다.
- fallback 조건이 사라질 수 있습니다.
- Open Question이 단순 메모처럼 보일 수 있습니다.

개선 방향은 착수 판단을 표로 분리하는 것입니다.

권장 구조는 다음과 같습니다.

| 판단 항목 | 상태 | 이유 | 관련 OQ | 다음 행동 |
|---|---|---|---|---|
| 즉시 착수 | 가능 / 불가 | 바로 개발 가능한 이유 또는 불가능한 이유 | OQ-번호 | 착수 / 확인 필요 |
| 보류 권고 | 예 / 아니오 | 보류해야 하는 이유 | OQ-번호 | 보류 또는 조건 확인 |
| 2Phase 이관 | 예 / 아니오 | 후속 단계로 넘기는 이유 | OQ-번호 | 2Phase 범위로 이동 |
| fallback 필요 | 예 / 아니오 | 실패 시 대체 흐름이 필요한 이유 | OQ-번호 | fallback 설계 |

이렇게 하면 사람이 보기도 쉽고, PPTX로 변환할 때도 정보가 덜 손상됩니다.

6. 핵심 문제 3: 문서가 중복되어 서로 다른 말을 할 수 있음

현재 다음 문서들이 비슷한 내용을 반복해서 담고 있습니다.

- SKILL.md
- README.md
- AGENTS.md
- context-planner-prompt.md
- docs/onboarding.html

문제는 같은 규칙이 여러 문서에 나뉘어 있으면 시간이 지나면서 서로 내용이 달라질 수 있다는 점입니다.

예를 들어 다음 항목들이 문서마다 다르게 적힐 가능성이 있습니다.

- 실행 명령
- 입력 파일 이름
- 출력 파일 이름
- 스킬을 언제 실행해야 하는지
- PPTX 생성 조건
- QA 기준
- Open Question 처리 방식

이 문제는 스킬 품질 문제라기보다 운영 방식의 문제에 가깝습니다.

개선 방향은 “기준 문서 하나”를 정하고 나머지 문서는 그 기준을 짧게 안내하는 방식으로 바꾸는 것입니다.

권장 역할 분리는 다음과 같습니다.

- SKILL.md
  - 가장 중요한 기준 문서로 유지합니다.
  - 실행 규칙, 입력/출력 계약, 검증 기준을 담습니다.
- README.md
  - 빠른 시작 가이드만 담습니다.
- AGENTS.md
  - 어떤 상황에서 어떤 스킬을 호출할지 정도만 담습니다.
- context-planner-prompt.md
  - 독립 실행용 축약 프롬프트로만 유지합니다.
- docs/onboarding.html
  - 사용자 안내용 문서로 유지하되, 세부 규칙은 SKILL.md를 따르게 합니다.

7. 수용한 개선 방향

다음 개선 방향은 바로 반영할 가치가 높습니다.

7-1. 완료 기준을 표로 바꾸기

§7 완료 기준을 자유 bullet이 아니라 표로 바꾸는 것이 좋습니다.

필수 컬럼은 다음과 같습니다.

- ID
- 검증 시나리오
- 기대 결과
- 우선순위
- 테스트 데이터/조건
- 상태

이렇게 해야 QA 담당자와 PPTX 생성기가 모두 같은 의미로 읽을 수 있습니다.

7-2. 착수 판단을 표준 표로 바꾸기

§10 착수 판단은 다음 항목으로 나누는 것이 좋습니다.

- 즉시 착수
- 보류 권고
- 2Phase 이관
- fallback 필요
- Open Question 의존 여부

이 구조는 PPTX 때문만이 아니라 의사결정 문서로도 더 좋습니다.

7-3. SKILL.md를 줄이고 역할을 명확히 하기

현재 SKILL.md에는 너무 많은 내용이 들어 있습니다.

섞여 있는 내용은 다음과 같습니다.

- 실행 지침
- 설치 가이드
- 템플릿 규칙
- PPTX 제약
- 검증 기준
- 운영 규칙

개선 방향은 SKILL.md를 다음 중심으로 재구성하는 것입니다.

- router
  - 어떤 요청이 들어왔을 때 어떤 흐름으로 보낼지 결정합니다.
- phase card
  - 각 단계에서 해야 할 일을 작게 나눕니다.
- validation contract
  - 산출물이 반드시 지켜야 하는 검증 기준을 정합니다.

8. 부분적으로만 수용할 개선 방향

“문장 단위 source traceability”는 좋은 방향입니다.
쉽게 말하면, 문장마다 출처를 붙이는 방식입니다.

하지만 이것을 처음부터 전면 도입하면 입력 부담이 너무 커질 수 있습니다.

그래서 현실적인 1차 개선안은 다음과 같습니다.

- 출처 없는 추정은 금지합니다.
- 중요한 생성값에만 우선 source를 붙입니다.
- 출처가 없는 내용은 “확인 필요”로 표시합니다.
- 나중에 필요하면 문장 단위 출처까지 확장합니다.

9. 지금은 보류할 개선 방향

multi-view 아키텍처는 방향 자체는 좋습니다.
쉽게 말하면 하나의 plan.md에서 여러 목적의 view를 만드는 방식입니다.

예를 들면 다음과 같습니다.

- QA용 view
- 개발 전달용 view
- 의사결정용 view
- PPTX용 view

하지만 지금 바로 도입하기에는 범위가 큽니다.
먼저 plan.md에서 spec.pptx로 변환되는 구조를 안정화하는 것이 우선입니다.

추천 순서는 다음과 같습니다.

1. plan.md와 spec.pptx 사이의 계약을 먼저 안정화합니다.
2. QA용 view를 추가합니다.
3. 개발 전달용 dev-handoff view를 추가합니다.
4. 필요하면 multi-view 구조로 확장합니다.

10. 실행 계획

10-1. M1: 계약 안정화

가장 먼저 해야 할 일은 plan.md와 spec.pptx 사이의 약속을 명확히 하는 것입니다.

작업 항목은 다음과 같습니다.

- SKILL.md 트리거를 plan compile과 spec-gen으로 분리합니다.
- §7 완료 기준을 표로 바꿉니다.
- §10 착수 판단을 표준 표로 바꿉니다.
- generate-spec.js에서 “Pass” 기본값을 제거합니다.
- HTML entity decode 처리를 추가합니다.
- 한글 문장을 무리하게 자르는 hard slice를 제거합니다.
- 체크리스트를 직접 파싱하도록 개선합니다.
- 루트 package.json과 lockfile로 실행 환경을 통일합니다.

10-2. M2: 검증 자동화

다음 단계는 자동 검증을 추가하는 것입니다.

작업 항목은 다음과 같습니다.

- cases/*/plan.md 기반 fixture 테스트를 추가합니다.
- spec.pptx 텍스트 dump 기반 회귀 테스트를 추가합니다.
- Gate를 Blocker와 PPTX lint로 분리합니다.
- 실패 조건을 명확히 정의합니다.

실패 조건 예시는 다음과 같습니다.

- Pass-only QA가 생성되는 경우
- & 같은 HTML entity가 남아 있는 경우
- OQ 내용이 잘리는 경우
- 보류 또는 2Phase 판단이 누락되는 경우
- 필수 슬라이드가 빠지는 경우

10-3. M3: 문서 정리

문서 간 중복을 줄여야 합니다.

작업 항목은 다음과 같습니다.

- SKILL.md를 기준 문서로 확정합니다.
- README.md는 빠른 시작만 유지합니다.
- AGENTS.md는 트리거와 진입점만 유지합니다.
- context-planner-prompt.md는 standalone 축약판으로만 유지합니다.
- 설정 경로, 산출물 이름, 실행 명령을 모든 문서에서 동일하게 맞춥니다.

10-4. M4: QA 소비자 강화

QA 담당자가 실제로 바로 사용할 수 있는 형태로 강화해야 합니다.

Phase A+에 다음 선택 필드를 추가하는 것이 좋습니다.

- test_data
- test_env
- device_matrix
- why_now

Open Question에 걸린 테스트는 다음 중 하나로 표시하는 것이 좋습니다.

- Blocked
- OQ-N 의존
- N/A

또한 QA completeness 지표를 추가하면 좋습니다.

예를 들면 다음 항목을 확인할 수 있습니다.

- 검증 시나리오가 충분한가
- 기대 결과가 비어 있지 않은가
- 테스트 데이터가 있는가
- Open Question에 막힌 항목이 명확한가
- PPTX로 변환해도 의미가 유지되는가

11. 우선순위

가장 먼저 할 일은 코드를 고치는 것이 아니라 “계약 정리”입니다.

특히 다음 항목을 먼저 확정해야 합니다.

- §7 완료 기준 입력 구조
- §10 착수 판단 입력 구조
- Slide 10 입력 계약
- Slide 12 입력 계약

이 계약이 정리되지 않으면 generate-spec.js를 고쳐도 다음 케이스에서 다시 문제가 생길 수 있습니다.

그 다음에 generate-spec.js를 고치는 순서가 좋습니다.

우선 고쳐야 할 코드 포인트는 다음과 같습니다.

- “Pass” 기본값 제거
- .slice()로 한글 문장을 강제로 자르는 부분 제거
- “가능” 단어만 보고 판단하는 필터 제거
- HTML entity decode 처리 추가
- 체크리스트 직접 파싱 추가

12. 쉬운 말로 정리한 최종 판단

현재 context-planner는 아이디어와 방향은 좋습니다.
하지만 사람이 읽는 문서와 프로그램이 읽는 문서 사이의 규칙이 아직 정확히 맞지 않습니다.

그래서 plan.md에는 중요한 내용이 들어 있어도, PPTX로 바뀌는 과정에서 일부 의미가 빠질 수 있습니다.

지금 가장 중요한 개선은 다음 세 가지입니다.

- 완료 기준을 표로 바꿔서 QA가 바로 쓸 수 있게 만들기
- 착수 판단을 표로 바꿔서 보류, 2Phase, fallback을 잃지 않게 만들기
- SKILL.md, README.md, AGENTS.md 같은 문서의 역할을 나누고 기준 문서를 하나로 정하기

결론적으로, 지금은 “더 많은 설명”을 추가할 때가 아니라 “입력과 출력의 약속”을 명확히 정리할 때입니다.

ex2) 직접 실험: 단일 프롬프트로 GPT-5.5 Pro에게 게임 6개 만들기

리서치와 사례 수집만으로는 한계가 있다. GPT-5.5 Pro에게 직접 단일 프롬프트로 게임을 만들게 해봤다. 모두 HTML 단일 파일로 완성되었고, 내 바이브코딩 사이트에 배포해서 직접 플레이하고 원본 프롬프트를 확인할 수 있다.

GPT-5.5 Pro로 싱글 프롬프트로 게임 만들기
https://goddaehee.co.kr/arcade — 상단의 "GPT-5.5 Pro" 필터를 선택하면 6개 게임이 바로 나온다. 각 게임 상세 페이지에서 원본 프롬프트를 확인하고 직접 재현해볼 수 있다.

게임	장르	설명	플랫폼	데모
Tetris Prime 강화 SRS + 7-bag + 미션 모드	퍼즐	SRS 회전·월킥·7-bag·홀드·고스트 완비. 20라인 7분 미션 + 모바일 터치 지원	PC·모바일	열기
한옥마을 워크 시뮬 Three.js 1인칭 전통 마을 탐험	시뮬레이션	Three.js 기반 1인칭 한옥마을. WASD+마우스, 충돌 감지, 미니맵, 한국어 표지판	PC 전용	열기
Billiards Sim Canvas 2D 8볼 당구 시뮬레이터	스포츠	물리 엔진 기반 8볼 당구. 마찰·탄성, 반사 경로 예측, 볼-인-핸드 파울 완비	PC 전용	열기
Gomoku AI 19×19 오목 vs Minimax AI	보드	Minimax+Alpha-Beta AI, Easy~Hard 3단계 난이도, Undo, 착수 애니메이션	PC·모바일	열기
Rhythm Beat 4레인 DDR 리듬 게임	리듬	D·F·J·K키 4레인, PERFECT/GOOD/MISS 판정, BPM 128 자동 패턴, Web Audio 피드백	PC 전용	열기
Tower Defense 20×14 그리드 BFS 타워 디펜스	전략	BFS 경로탐색, 3종 타워·3종 적, 10웨이브, 업그레이드, 2× 속도 배율	PC 전용	열기

① Tetris Prime — 퍼즐 / ★★★★ / PC·모바일 / 데모 열기

SRS 회전·월킥·7-bag·홀드·고스트가 모두 구현된 정통 테트리스. 20라인 7분 미션 클리어와 모바일 터치 컨트롤을 지원한다.

[ROLE] 당신은 10년차 시니어 HTML5 게임 개발자다. Canvas 2D API, requestAnimationFrame 기반 게임 루프, 키보드 입력 처리, 점수 시스템 설계에 능숙하다. 단일 HTML 파일로 즉시 실행 가능한 게임을 만드는 전문가다. [PROJECT] 코드네임: TETRIS-PRIME 목표 플랫폼: 데스크톱 Chrome 130+ (모바일 best-effort) 산출물: 단일 index.html (외부 라이브러리 CDN 사용 금지, vanilla JavaScript만) [FUNCTIONAL REQUIREMENTS] — 반드시 모두 구현하라 F-01: SRS 회전 시스템 (Super Rotation System, wall kick 테이블 포함) F-02: 7-bag 랜덤화 (같은 미노가 5번 이상 연속으로 나오지 않는다) F-03: Hold 기능 (C 또는 Shift 키, 한 턴에 1회만 허용) F-04: 하드드롭 (Space) + 소프트드롭 (↓ 길게) + lock delay 0.5초 F-05: 라인 클리어 점수: Single=100, Double=300, Triple=500, Tetris=800, T-Spin Triple=1600 F-06: 레벨 시스템: 10라인마다 +1, 낙하 속도 = (0.8 - level×0.007)^level 초/cell F-07: Ghost piece 표시 (착지 위치 반투명) F-08: 한국어 UI: "다음 블록", "보유 블록", "점수", "레벨", "라인", "일시정지", "게임오버", "재시작" F-09: 일시정지 (P키), 게임오버 후 재시작 (R키) F-10: 미션 모드: 시작 시 "20라인을 7분 안에 클리어하라" 메시지 표시, 달성 시 "미션 성공!" 화면 [NON-FUNCTIONAL REQUIREMENTS] N-01: 60fps 유지 (requestAnimationFrame 기반, frame drop 없이) N-02: 키 입력 반응 latency 50ms 이하 N-03: 모바일: 터치 컨트롤 5버튼 자동 활성화 (좌·우·회전·소프트드롭·하드드롭) N-04: 코드 총 길이 1,500줄 이하 (주석 제외) [ACCEPTANCE TESTS] — 당신이 코드를 완성한 뒤 직접 검증하라 T-01: J 미노를 좌측 벽에 붙인 상태에서 시계 방향 회전 → wall kick으로 우측 1칸 이동 확인 T-02: 동시에 4라인을 클리어하면 점수가 정확히 800 증가 확인 T-03: 같은 미노가 5번 연속으로 등장하지 않는지 50턴 동안 확인 T-04: Hold 사용 직후 즉시 Hold 재시도 → 무시되어야 함 T-05: 미션 모드에서 7분이 경과하기 전에 20라인 클리어 → "미션 성공!" 화면 표시 T-06: 브라우저 창을 절반 크기로 줄여도 캔버스가 잘리지 않고 리스케일 확인 [DELIVERABLES] 1. index.html 파일 1개 (즉시 브라우저에서 열면 실행되어야 함) 2. 코드 상단 주석 블록에 SELF_CHECK 결과 (각 T-01~T-06에 대해 PASS 또는 FAIL + 실패 이유) 3. 코드 하단 주석 블록에 알려진 한계 및 개선 여지 5줄 이내 [CONSTRAINTS] - 외부 라이브러리, CDN, npm 패키지 사용 금지 (순수 HTML+JS+CSS) - 한국어 주석 5줄 이상 포함 - ES2020+ 문법 자유롭게 사용 - inline style 또는 <style> 태그로 모든 스타일 처리 (외부 CSS 파일 금지) [NOW BEGIN] 위 모든 요구사항을 충족하는 완전한 index.html을 지금 바로 작성하라. 중간에 멈추거나 "이후 구현 필요" 같은 불완전한 코드를 남기지 말고, 처음부터 끝까지 완전한 코드를 제출하라.

② 한옥마을 워크 시뮬 — 시뮬레이션 / ★★ / PC 전용 / 데모 열기

Three.js 기반 1인칭 한옥마을 워킹 시뮬레이션. WASD+마우스로 기와지붕 건물을 자유롭게 탐험하고 미니맵과 한국어 표지판을 만나보자.

[ROLE] 당신은 Three.js 전문 개발자로, 3D 씬 구성, 조명·그림자 시스템, 1인칭 카메라 컨트롤, 충돌 감지에 능숙하다. 한국 전통 건축 양식(한옥)의 기본 형태를 알고 있으며, 한국어 UI를 자연스럽게 작성한다. 단일 HTML 파일로 즉시 실행 가능한 3D 씬을 만드는 전문가다. [PROJECT] 코드네임: HANOK-MAEUL 목표 플랫폼: 데스크톱 Chrome 130+ (Three.js r165 CDN 사용) 산출물: 단일 index.html (Three.js CDN 1개만 허용, 그 외 외부 라이브러리 금지) [FUNCTIONAL REQUIREMENTS] — 반드시 모두 구현하라 F-01: Three.js r165 CDN 로드 (https://cdn.jsdelivr.net/npm/three@0.165.0/build/three.min.js) F-02: 1인칭 시점 카메라 (WASD: 전진/후진/좌이동/우이동, 마우스: 시점 회전, 클릭으로 포인터 락 활성화) F-03: 한옥 건물 최소 3채 (지붕 곡선 표현, 기둥, 마루, 담장 포함) F-04: DirectionalLight 기반 그림자 시스템 (castShadow, receiveShadow 모두 활성화) F-05: AABB 충돌 감지 (건물과 담장에 부딪히면 통과 불가) F-06: 지면: 잔디 또는 흙 색상 기반 PlaneGeometry, 15×15 이상 크기 F-07: 한국어 HUD: 화면 상단에 "한옥마을" 제목, 조작법 안내 ("WASD: 이동 | 마우스: 시점"), "클릭하면 시작" 안내 F-08: 안내 표지판 3개 이상 (한국어 텍스트, Canvas Texture로 Sprite에 렌더링) F-09: 미니맵 (화면 우하단, 60×60px, 플레이어 위치와 건물 위치를 2D 점으로 표시) F-10: 로딩 화면 → 씬 전환 (로딩 중 "한옥마을을 불러오는 중..." 표시, 완료 시 자동 전환) [NON-FUNCTIONAL REQUIREMENTS] N-01: 60fps 유지 목표 (requestAnimationFrame, 단순 지오메트리로 최적화) N-02: 포인터 락 실패 시 WASD 이동은 정상 동작, 시점 회전은 화살표 키로 대체 N-03: 씬 전체 폴리곤 수 10,000개 이하 (BoxGeometry·CylinderGeometry 조합 허용) N-04: 코드 총 길이 1,800줄 이하 (주석 제외) [ACCEPTANCE TESTS] — 당신이 코드를 완성한 뒤 직접 검증하라 T-01: 브라우저에서 열면 로딩 화면이 표시된 뒤 씬으로 자동 전환 확인 T-02: 클릭 후 WASD로 캐릭터가 이동하며 마우스로 시점이 회전 확인 T-03: 건물에 가까이 다가가면 통과하지 못하고 멈춤 확인 (충돌) T-04: 그림자가 지면과 건물에 드리워짐 확인 (console에 shadow-related error 없음) T-05: 미니맵에서 플레이어 위치가 이동에 따라 실시간 갱신 확인 T-06: 안내 표지판 3개가 화면에 보이고 한국어 텍스트가 읽힘 확인 [DELIVERABLES] 1. index.html 파일 1개 (즉시 브라우저에서 열면 실행되어야 함) 2. 코드 상단 주석 블록에 SELF_CHECK 결과 (각 T-01~T-06에 대해 PASS 또는 FAIL + 실패 이유) 3. 코드 하단 주석 블록에 알려진 한계 및 개선 여지 5줄 이내 [CONSTRAINTS] - Three.js CDN 1개를 제외한 모든 외부 라이브러리 금지 - 한국어 주석 5줄 이상 포함 - ES2020+ 문법 자유롭게 사용 - inline style 또는 <style> 태그로 모든 스타일 처리 [NOW BEGIN] 위 모든 요구사항을 충족하는 완전한 index.html을 지금 바로 작성하라. 중간에 멈추거나 "이후 구현 필요" 같은 불완전한 코드를 남기지 말고, 처음부터 끝까지 완전한 코드를 제출하라.

③ Billiards Sim — 스포츠 / ★★★ / PC 전용 / 데모 열기

물리 엔진 기반 Canvas 8볼 당구. 마찰·탄성 시뮬레이션, 조준선과 1회 반사 경로 예측, 볼-인-핸드 파울 처리까지 완전한 8볼 규칙이 구현되어 있다.

[ROLE] 당신은 10년차 시니어 물리 엔진 개발자다. Canvas 2D 기반 강체(rigid body) 물리 시뮬레이션, 원형 충돌 감지, 반사 벡터 계산, 마찰·탄성 모델링에 능숙하다. 당구 게임 규칙과 UI를 한국어로 자연스럽게 구성한다. 단일 HTML 파일로 즉시 실행 가능한 게임을 만드는 전문가다. [PROJECT] 코드네임: BILLIARDS-SIM 목표 플랫폼: 데스크톱 Chrome 130+ 산출물: 단일 index.html (외부 라이브러리 CDN 사용 금지, vanilla JavaScript만) [FUNCTIONAL REQUIREMENTS] — 반드시 모두 구현하라 F-01: 당구대 렌더링 (초록 펠트, 쿠션 영역, 4개 코너 포켓 + 2개 사이드 포켓) F-02: 공 물리 시뮬레이션: 속도 벡터, 마찰 감속 (운동 마찰 계수 0.02/frame), 탄성 계수 0.85 F-03: 공-쿠션 충돌: 반사 벡터 계산 (입사각 = 반사각), 쿠션 충돌 시 속도 10% 손실 F-04: 공-공 충돌: 완전탄성충돌 공식 적용 (질량 동일), 겹침 방지 처리 F-05: 8볼 룰: 수구(흰공), 솔리드(1~7), 스트라이프(9~15), 8번 공 분류 및 규칙 적용 F-06: 조준 시스템: 마우스 드래그로 파워·방향 결정, 조준선(점선) + 예상 반사경로 1회 표시 F-07: 포켓 인식: 공이 포켓 반경 내 진입 시 제거, 득점 처리 F-08: 한국어 UI: "솔리드 차례" / "스트라이프 차례" / "파울!" / "8번 공 넣어 승리!" / 점수판 F-09: 파울 처리: 수구 포켓인 경우 볼-인-핸드(드래그로 수구 재배치) F-10: 새 게임 버튼, 공 삼각형 래킹 자동 배치, 브레이크 샷 시작 [NON-FUNCTIONAL REQUIREMENTS] N-01: 물리 업데이트 120Hz (requestAnimationFrame 내 sub-step 2회), 렌더링 60fps N-02: 공 정지 판정: 모든 공 속도 < 0.1px/frame 시 다음 턴으로 전환 N-03: 조준선이 마우스 이동에 16ms 이내 반응 (입력 레이턴시) N-04: 코드 총 길이 1,400줄 이하 (주석 제외) [ACCEPTANCE TESTS] — 당신이 코드를 완성한 뒤 직접 검증하라 T-01: 수구를 정중앙에서 쿠션에 45도 각도로 충돌 → 반사각 45도로 이탈 확인 (±5도 허용) T-02: 수구가 목적구 정면 중심 충돌 시 수구 정지, 목적구가 동일 방향 직선 이동 확인 T-03: 공을 강하게 쳐서 마찰로 인해 감속 후 완전 정지 확인 (무한 구르기 없음) T-04: 조준선이 마우스 방향 변경 시 실시간 업데이트, 쿠션 반사 경로 1회 예측선 표시 확인 T-05: 솔리드 차례에 스트라이프 공 먼저 포켓 → "파울!" 표시, 상대방 볼-인-핸드 확인 T-06: 새 게임 시 15개 공이 삼각형 래킹 배치로 리셋, 수구 위치 초기화 확인 [DELIVERABLES] 1. index.html 파일 1개 (즉시 브라우저에서 열면 실행되어야 함) 2. 코드 상단 주석 블록에 SELF_CHECK 결과 (각 T-01~T-06에 대해 PASS 또는 FAIL + 실패 이유) 3. 코드 하단 주석 블록에 물리 모델 설계 방침 및 알려진 한계 5줄 이내 [CONSTRAINTS] - 외부 라이브러리, CDN, npm 패키지 사용 금지 (순수 HTML+JS+CSS) - 한국어 주석 5줄 이상 포함 - ES2020+ 문법 자유롭게 사용 - inline style 또는 <style> 태그로 모든 스타일 처리 [NOW BEGIN] 위 모든 요구사항을 충족하는 완전한 index.html을 지금 바로 작성하라. 중간에 멈추거나 "이후 구현 필요" 같은 불완전한 코드를 남기지 말고, 처음부터 끝까지 완전한 코드를 제출하라.

④ Gomoku AI — 보드 / ★★★ / PC·모바일 / 데모 열기

19×19 바둑판 오목 대전. Minimax + Alpha-Beta Pruning AI와 Easy~Hard 3단계 난이도로 대결하라. 착수 애니메이션, Undo, 경과 시간이 모두 포함된다.

[ROLE] 당신은 10년차 시니어 게임 AI 개발자다. Minimax 알고리즘, Alpha-Beta Pruning, 휴리스틱 평가 함수 설계에 능숙하다. Canvas 2D로 보드 게임 UI를 만들고, 한국어 인터페이스를 자연스럽게 작성한다. 단일 HTML 파일로 즉시 실행 가능한 게임을 만드는 전문가다. [PROJECT] 코드네임: GOMOKU-AI 목표 플랫폼: 데스크톱 Chrome 130+ (모바일 best-effort) 산출물: 단일 index.html (외부 라이브러리 CDN 사용 금지, vanilla JavaScript만) [FUNCTIONAL REQUIREMENTS] — 반드시 모두 구현하라 F-01: 19×19 바둑판 스타일 보드 (Canvas 2D, 격자선, 화점 표시) F-02: 플레이어(흑) vs AI(백) 대전, 클릭으로 착수 F-03: Minimax + Alpha-Beta Pruning AI (탐색 깊이 조절 가능) F-04: 난이도 3단계: Easy(깊이2) / Normal(깊이4) / Hard(깊이6+휴리스틱강화) F-05: 5목 승리 감지 (가로·세로·대각선 모두), 승리 돌 강조 표시 F-06: 착수 애니메이션 (돌이 자연스럽게 놓이는 효과), 마지막 착수 위치 표시 F-07: 한 수 되돌리기 (Undo): 플레이어 수 + AI 수 동시 취소, 턴당 1회 F-08: 한국어 UI: "흑 차례" / "AI 생각 중..." / "흑 승리!" / "백 승리!" / "무승부!" / 난이도 선택 버튼 F-09: 게임 정보 패널: 경과 시간, 착수 수(手), 현재 난이도 표시 F-10: 새 게임 버튼, 보드 가득 찼을 때 무승부 처리 [NON-FUNCTIONAL REQUIREMENTS] N-01: Hard 난이도 AI 응답 시간 3초 이하 (Web Worker 사용 가능) N-02: 보드 렌더링 60fps 유지 (requestAnimationFrame 기반) N-03: 반응형: 윈도우 크기에 따라 보드 자동 리스케일 (최소 400×400px) N-04: 코드 총 길이 1,200줄 이하 (주석 제외) [ACCEPTANCE TESTS] — 당신이 코드를 완성한 뒤 직접 검증하라 T-01: 가로 5목 완성 시 해당 돌 5개 강조 표시 + "흑 승리!" 메시지 확인 T-02: Hard AI가 플레이어의 열린 4목(활사: 양쪽 열린 4개)을 즉시 막음 확인 T-03: 보드 우하단 모서리에 5목 완성 시 정상 감지 확인 (경계 처리) T-04: Undo 실행 시 플레이어 돌과 AI 돌 각 1개씩 제거, 플레이어 차례로 복귀 확인 T-05: 보드 361칸 모두 채워진 상태에서 승자 없으면 "무승부!" 표시 확인 T-06: Easy → Hard로 난이도 변경 후 새 게임에서 AI의 착수 품질 차이 확인 가능 [DELIVERABLES] 1. index.html 파일 1개 (즉시 브라우저에서 열면 실행되어야 함) 2. 코드 상단 주석 블록에 SELF_CHECK 결과 (각 T-01~T-06에 대해 PASS 또는 FAIL + 실패 이유) 3. 코드 하단 주석 블록에 AI 휴리스틱 설계 방침 및 알려진 한계 5줄 이내 [CONSTRAINTS] - 외부 라이브러리, CDN, npm 패키지 사용 금지 (순수 HTML+JS+CSS) - 한국어 주석 5줄 이상 포함 - ES2020+ 문법 자유롭게 사용 - inline style 또는 <style> 태그로 모든 스타일 처리 [NOW BEGIN] 위 모든 요구사항을 충족하는 완전한 index.html을 지금 바로 작성하라. 중간에 멈추거나 "이후 구현 필요" 같은 불완전한 코드를 남기지 말고, 처음부터 끝까지 완전한 코드를 제출하라.

⑤ Rhythm Beat — 리듬 / ★★★ / PC 전용 / 데모 열기

4레인 DDR 스타일 리듬 게임. D·F·J·K키로 노트를 판정하고 PERFECT/GOOD/MISS로 점수를 쌓아라. BPM 128 자동 생성 패턴, 등급 시스템, Web Audio 비프 피드백이 포함된다.

[ROLE] 당신은 10년차 시니어 HTML5 게임 개발자다. Canvas 2D 기반 리듬 게임 구조, 타이밍 판정 시스템, Web Audio API 활용, 파티클 이펙트 설계에 능숙하다. 리듬 게임 UI를 한국어로 자연스럽게 구성한다. 단일 HTML 파일로 즉시 실행 가능한 게임을 만드는 전문가다. [PROJECT] 코드네임: RHYTHM-BEAT 목표 플랫폼: 데스크톱 Chrome 130+ 산출물: 단일 index.html (외부 라이브러리 CDN 사용 금지, vanilla JavaScript만) [FUNCTIONAL REQUIREMENTS] — 반드시 모두 구현하라 F-01: 4레인 노트 판정 시스템 (키: D·F·J·K), 레인별 컬러 구분 (파랑·초록·주황·빨강) F-02: 노트가 위에서 아래로 낙하, 판정선(하단 20% 위치)에서 타이밍 판정 F-03: 3단계 판정: PERFECT(±40ms) / GOOD(±80ms) / MISS, 판정 결과 팝업 텍스트 표시 F-04: 콤보 시스템: MISS 시 초기화, 콤보 10·50·100에서 화면 이펙트 강화 (테두리 발광) F-05: 점수 시스템: PERFECT=300, GOOD=100, MISS=0, 콤보 보너스(콤보수×10 추가) F-06: 노트 패턴 자동 생성: BPM 128 기준, 16분음표 단위, 3분 분량 패턴 프로시저럴 생성 F-07: Web Audio API로 비프음 생성 (외부 파일 없이): 레인별 다른 음정, 키 입력 시 피드백음 F-08: 한국어 UI: "PERFECT!" / "GOOD" / "MISS" / "콤보" / "점수" / 결과 화면(Perfect수·Good수·Miss수·최대콤보·최종점수·등급) F-09: 결과 화면 등급: S(PERFECT 90%+) / A(80%+) / B(70%+) / C(60%+) / D(그 이하) F-10: 일시정지(Esc키), 재시작(R키), 곡 진행률 바 (상단) [NON-FUNCTIONAL REQUIREMENTS] N-01: 타이밍 판정 기준: performance.now() 사용, setTimeout·setInterval 의존 금지 N-02: 노트 렌더링 60fps 유지, 판정선 기준 입력 레이턴시 보정 (-20ms 오프셋 적용) N-03: 키 입력 시 해당 레인 하단 발광 이펙트(50ms 지속), 롱프레스 방지 처리 N-04: 코드 총 길이 1,300줄 이하 (주석 제외) [ACCEPTANCE TESTS] — 당신이 코드를 완성한 뒤 직접 검증하라 T-01: 노트가 판정선에 정확히 도달하는 순간 키 입력 시 "PERFECT!" 판정 및 300점 추가 확인 T-02: 판정선 기준 80ms 이후 입력 시 "MISS" 처리, 콤보 초기화 확인 T-03: 콤보 50 달성 시 화면 테두리 발광 이펙트 강도 증가 확인 T-04: MISS 발생 후 즉시 키 입력 성공 시 콤보 1부터 재시작 확인 T-05: 곡 종료 시 PERFECT·GOOD·MISS 개수 합이 전체 노트 수와 일치 확인, 등급 표시 확인 T-06: Esc 일시정지 → 재개 후 타이밍 판정이 정상 동작 확인 (일시정지 중 노트 누락 없음) [DELIVERABLES] 1. index.html 파일 1개 (즉시 브라우저에서 열면 실행되어야 함) 2. 코드 상단 주석 블록에 SELF_CHECK 결과 (각 T-01~T-06에 대해 PASS 또는 FAIL + 실패 이유) 3. 코드 하단 주석 블록에 타이밍 판정 설계 방침 및 알려진 한계 5줄 이내 [CONSTRAINTS] - 외부 라이브러리, CDN, npm 패키지 사용 금지 (순수 HTML+JS+CSS) - 한국어 주석 5줄 이상 포함 - ES2020+ 문법 자유롭게 사용 - inline style 또는 <style> 태그로 모든 스타일 처리 [NOW BEGIN] 위 모든 요구사항을 충족하는 완전한 index.html을 지금 바로 작성하라. 중간에 멈추거나 "이후 구현 필요" 같은 불완전한 코드를 남기지 말고, 처음부터 끝까지 완전한 코드를 제출하라.

⑥ Tower Defense — 전략 / ★★★★ / PC 전용 / 데모 열기

20×14 그리드 타워 디펜스. BFS 경로탐색으로 타워 배치 시 경로를 실시간 재계산한다. 3종 타워·3종 적·10웨이브·업그레이드·2× 속도 배율이 포함된다.

[ROLE] 당신은 10년차 시니어 HTML5 게임 개발자다. Canvas 2D 기반 타일 맵, BFS/A* 경로탐색, 엔티티-컴포넌트 게임 루프, 웨이브 스폰 시스템 설계에 능숙하다. 전략 게임 UI를 한국어로 자연스럽게 구성한다. 단일 HTML 파일로 즉시 실행 가능한 게임을 만드는 전문가다. [PROJECT] 코드네임: TOWER-DEF 목표 플랫폼: 데스크톱 Chrome 130+ 산출물: 단일 index.html (외부 라이브러리 CDN 사용 금지, vanilla JavaScript만) [FUNCTIONAL REQUIREMENTS] — 반드시 모두 구현하라 F-01: 20×14 타일 그리드 맵 (경로 타일 / 건설 가능 타일 / 장애물 타일 구분, Canvas 렌더링) F-02: 적 경로: 시작점 → 도착점 BFS 최단경로, 타워 배치 시 경로 실시간 재계산 F-03: 타워 3종: 기본포탑(단일공격·저비용) / 저격포탑(긴사거리·고대미지) / 광역포탑(AOE·고비용) F-04: 타워 배치: 건설 가능 타일 클릭 → 타워 선택 UI → 배치, 골드 차감 F-05: 웨이브 시스템: 10웨이브, 웨이브마다 적 수·속도·HP 20% 증가, 웨이브 간 10초 휴식 F-06: 적 3종: 일반(기본) / 기갑(HP2배·속도절반) / 돌격대(HP절반·속도2배) F-07: 경제 시스템: 웨이브 시작 골드 지급, 적 처치 골드 획득, 타워 판매(건설비 70% 환급) F-08: 한국어 UI: "웨이브 N/10" / "목숨: N" / "골드: N" / 타워 이름·비용·설명 / "게임 오버" / "승리!" F-09: 타워 업그레이드: 타워 클릭 → 업그레이드 버튼 (공격력·속도 각 +30%, 2단계까지) F-10: 게임 속도 배율: 1×/2× 토글 버튼, 일시정지(P키) [NON-FUNCTIONAL REQUIREMENTS] N-01: 60fps 유지 (requestAnimationFrame, 적 100마리 동시 처리 가능) N-02: 타워 배치 시 BFS 재계산 100ms 이내 완료 N-03: 타워 사거리 표시: 마우스 오버 시 반투명 원형 사거리 표시 N-04: 코드 총 길이 1,600줄 이하 (주석 제외) [ACCEPTANCE TESTS] — 당신이 코드를 완성한 뒤 직접 검증하라 T-01: 웨이브 1 시작 시 적이 시작점 → 도착점까지 BFS 경로를 따라 이동 확인 T-02: 타워로 경로를 완전 차단하면 배치 불가 처리 (경로 없음 → 배치 거부) 확인 T-03: 광역포탑 공격 시 사거리 내 모든 적에게 동시 피해 확인 T-04: 적이 도착점 도달 시 목숨 1 차감, 목숨 0 → "게임 오버" 화면 확인 T-05: 웨이브 10 모두 클리어 시 "승리!" 화면 + 최종 점수 표시 확인 T-06: 타워 2단계 업그레이드 후 공격력·속도 각 30% 증가 수치 UI에 반영 확인 [DELIVERABLES] 1. index.html 파일 1개 (즉시 브라우저에서 열면 실행되어야 함) 2. 코드 상단 주석 블록에 SELF_CHECK 결과 (각 T-01~T-06에 대해 PASS 또는 FAIL + 실패 이유) 3. 코드 하단 주석 블록에 경로탐색 알고리즘 설계 방침 및 알려진 한계 5줄 이내 [CONSTRAINTS] - 외부 라이브러리, CDN, npm 패키지 사용 금지 (순수 HTML+JS+CSS) - 한국어 주석 5줄 이상 포함 - ES2020+ 문법 자유롭게 사용 - inline style 또는 <style> 태그로 모든 스타일 처리 [NOW BEGIN] 위 모든 요구사항을 충족하는 완전한 index.html을 지금 바로 작성하라. 중간에 멈추거나 "이후 구현 필요" 같은 불완전한 코드를 남기지 말고, 처음부터 끝까지 완전한 코드를 제출하라.

GPT-5.4 Pro로 만든 9개 게임도 같은 페이지의 다른 모델 필터에서 바로 비교해볼 수 있다. 프롬프트 구조가 어떻게 달라지는지, 완성도 차이가 어디서 나타나는지 직접 확인하기 좋다.

6. 요금제 및 제한사항

API 가격 구조 (2026-04-24 기준)

가격 정보는 2026-04-24 기준이다. 변경 가능성이 있으므로 최신 가격은 OpenAI 공식 가격 페이지에서 반드시 확인하도록 권한다.

모델	입력	출력
GPT-5.5	$5/1M 토큰	$30/1M 토큰
GPT-5.5 Pro	$30/1M 토큰	$180/1M 토큰
GPT-5.4 (참고)	$2.50/1M 토큰	$15/1M 토큰

(출처: OpenAI 공식 블로그, 2026-04-24 기준)

GPT-5.5는 GPT-5.4 대비 정확히 2배 인상됐다. Batch/Flex 옵션을 사용하면 표준 가격의 50%, Priority 옵션은 표준의 250%가 적용된다. 입력 토큰이 272K를 초과하면 가격이 2배 적용된다.

비용 절감 전략

비용 최소화가 목표라면 Batch/Flex 옵션이 효과적이다. 표준 대비 50% 비용으로 GPT-5.5를 쓸 수 있다. 실시간 응답이 불필요한 배치 처리, 비동기 분석 파이프라인 등에 적합하다. 반대로 응답 지연이 허용되지 않는 프로덕션 서비스에서는 Fast Mode(2.5배 비용)와 Priority 옵션(2.5배)의 차이를 파악하고 선택해야 한다.

주요 한계와 단점

환각률 86% (독립 기관 측정)

Artificial Analysis의 AA-Omniscience 독립 평가에서 GPT-5.5의 환각률은 86%로 측정됐다. 이 수치는 OpenAI의 공식 발표가 아니라 독립 기관 Artificial Analysis의 AA-Omniscience 벤치마크 결과다. 같은 평가에서 Claude Opus 4.7은 36%, Gemini 3.1 Pro는 50%를 기록했다.

Handy AI는 이를 두고 "이 모델은 다른 어떤 모델보다 더 많이 알지만, 모르는 질문에도 자신있게 답변하는 비율이 최고 경쟁사의 2.5배에 달한다"고 분석했다. 아는 범위는 넓은데, 모르는 걸 물어봐도 자신 있게 대답하는 경향이 강하다는 뜻이다. 금융·법률·의료처럼 정확도가 중요한 곳에서는 교차 검증이 필수다.

GDPval 향상 1.9%p: 일상 업무 체감 제한

GDPval 기준 GPT-5.5(84.9%)와 GPT-5.4(83.0%)의 차이는 1.9%p다. API 가격이 2배 인상된 것에 비해, 일반 지식 노동 영역의 성능 향상폭은 제한적이다. 에이전틱 코딩이나 수학·과학 연구가 주된 용도가 아닌 팀이라면, 업그레이드 ROI를 신중하게 계산해야 한다.

MCP Atlas 도구 사용 열위

MCP Atlas(Scale AI 운영 도구 사용 벤치마크)에서 GPT-5.5는 75.3%로, Claude Opus 4.7(79.1%)과 Gemini 3.1 Pro(78.2%)에 뒤진다. MCP 기반 에이전틱 파이프라인 구축이 핵심인 팀이라면 이 차이를 고려할 필요가 있다.

7. 대안 비교: Claude Mythos Preview vs Claude Opus 4.7 vs Gemini 3.1 Pro

벤치마크 종합 비교표

(출처: The Decoder, 2026-04-24, deploymentsafety.openai.com. 2026-04-24 기준)

벤치마크	GPT-5.5	Claude Mythos Preview	Claude Opus 4.7	Gemini 3.1 Pro
Terminal-Bench 2.0	82.7%	82.0%	해당 없음	해당 없음
SWE-Bench Pro	58.6%	77.8% ⚠️	64.3% ⚠️	해당 없음
Expert-SWE	73.1%	해당 없음	해당 없음	해당 없음
OSWorld-Verified	78.7%	해당 없음	78.0%	해당 없음
HLE (도구 없음)	41.4%	56.8%	해당 없음	해당 없음
FrontierMath Tier 1-3	51.7%	해당 없음	43.8%	36.9%
FrontierMath Tier 4	35.4%	해당 없음	22.9%	16.7%
BrowseComp	84.4%	해당 없음	79.3%	85.9%
GDPval	84.9%	해당 없음	80.3%	67.3%
MCP Atlas	75.3%	해당 없음	79.1%	78.2%
CyberGym	81.8%	83.1%	73.1%	해당 없음
MRCR v2 (1M)	74.0%	해당 없음	해당 없음	해당 없음
AA-Omniscience 환각률	86% ↑ 높을수록 불리	해당 없음	36%	50%

SWE-Bench Pro: OpenAI는 Claude Mythos Preview(77.8%)와 Claude Opus 4.7(64.3%)의 수치에 암기(memorization) 징후가 있다고 공식 지적했고, Anthropic은 이를 부분 인정했다.

종합 분석

Artificial Analysis 지능 인덱스에서 GPT-5.5는 3점 차로 1위를 기록했고, Claude Opus 4.7과 Gemini 3.1 Pro가 공동 2위다.

한 줄 종합: GPT-5.5는 수학·과학·장문 컨텍스트·지식 노동에서 가장 넓은 우위를 가지며, Claude Mythos Preview는 일반 추론·사이버 보안에서 앞서고, Gemini 3.1 Pro는 웹 리서치와 도구 사용에서 실용적인 대안이 된다.

어느 한 모델이 모든 영역에서 압도적이지는 않다. 벤치마크별로 선두가 분산되어 있으며, 도메인과 사용 패턴에 따라 최적 선택이 달라진다. 도구 사용 중심 에이전트를 구축한다면 Claude Opus 4.7이나 Gemini 3.1 Pro가 비용 대비 경쟁력을 가질 수 있다. 수학·과학 연구나 1M 장문 컨텍스트 처리가 핵심이라면 GPT-5.5의 우위가 뚜렷하다.

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

자주 묻는 질문 5가지

Q1. GPT-5.5와 GPT-5.5 Pro 중 무엇을 선택해야 하나?

GPT-5.5 Pro는 수학 최고 난도(FrontierMath Tier 4 39.6% vs 35.4%), 웹 리서치(BrowseComp 90.1% vs 84.4%) 등에서 기본 모델보다 의미 있는 우위를 보인다. API 가격은 입력 $30, 출력 $180/1M으로 기본 모델의 6배다. 최전선 연구나 고부가가치 자동화에만 Pro가 정당화된다.

Q2. 환각률 86%라는 수치를 어떻게 해석해야 하나?

이 수치는 Artificial Analysis의 AA-Omniscience라는 독립 벤치마크에서 측정된 것으로, OpenAI 공식 수치가 아니다. BNY처럼 높은 정확도가 필수인 도메인에서는 GPT-5.5 단독 사용보다 교차 검증 워크플로우를 함께 설계하는 것이 현실적인 접근이다.

Q3. 과도한 확인 요청 문제를 줄이려면?

얼리 액세스 테스터들의 커뮤니티 보고에 따르면, 추상적인 명령보다 구체적인 조건과 지시사항을 프롬프트에 명시적으로 포함하면 확인 요청이 크게 줄어든다. 예: "중간에 확인 없이 끝까지 완료하라"는 지시를 프롬프트에 포함하는 방식이 실효성이 있다고 보고됐다.

Q4. Codex 환경에서의 컨텍스트 제한은 어떻게 대응하나?

Codex는 400K 토큰으로 제한되므로, 1M이 필요한 장문 문서 처리는 ChatGPT API 직접 호출 방식을 고려해야 한다. 대규모 코드베이스 분석이라면 컨텍스트 청킹 전략과 함께 MRCR v2 기준 74.0%의 장문 성능을 최대한 활용하는 방식이 효과적이다.

Q5. API 비용 부담이 크다. 절감 방법은?

Batch/Flex 옵션은 표준의 50% 비용으로 GPT-5.5를 쓸 수 있는 공식 방법이다. 실시간 응답이 불필요한 분석·검토 파이프라인에 적합하다. 입력 토큰 272K 초과 시 2배 과금되므로, 장문 컨텍스트 사용 시 청킹으로 272K 이하를 유지하는 비용 최적화도 고려할 수 있다.

도입 결정 매트릭스

시나리오	추천 선택	이유
에이전틱 코딩 (멀티스텝, 장기 태스크)	GPT-5.5	Terminal-Bench 82.7%, Expert-SWE 73.1% 우위
1M 장문 문서 처리	GPT-5.5	MRCR v2 74.0% (전작 2배 이상)
수학·과학 연구 자동화	GPT-5.5 Pro	FrontierMath 전 구간 선두
도구 사용 중심 에이전트	Claude Opus 4.7 / Gemini 3.1 Pro	MCP Atlas에서 GPT-5.5보다 우위
웹 리서치 (기본 모델)	Gemini 3.1 Pro	BrowseComp 85.9% vs GPT-5.5 84.4%
환각 최소화 우선 고정밀 업무	Claude Opus 4.7	AA-Omniscience 36% vs GPT-5.5 86%
비용 절감 배치 처리	GPT-5.5 + Batch/Flex	50% 할인 옵션 활용
비용 대비 범용 성능	GPT-5.4 또는 Claude Opus 4.7	GPT-5.5 대비 50% 비용, GDPval 1.9%p 차이

마무리 하며..

GPT-5.5는 에이전틱 AI로의 전환을 선언한 모델이다. 에이전틱 코딩, 수학·과학 연구, 1M 장문 컨텍스트 처리에서 현재 공개된 벤치마크 기준 가장 강력한 성능을 보여준다.

근데 벤치마크만 보고 결정할 수 있는 게 아니다. API 가격은 2배 올랐고, 독립 측정 환각률이 86%다. MCP 도구 사용에선 경쟁 모델보다 뒤처지고, 보상 해킹이나 과도한 확인 요청 같은 에이전틱 행동의 불안정성도 남아 있다.

지금 도입을 고려할 팀: 에이전틱 코딩 또는 1M 장문 컨텍스트 처리가 핵심 워크로드이고, 비용 증가를 감당할 수 있는 팀. Batch/Flex를 활용해 비용을 절반으로 줄이고 파이프라인을 먼저 검증하는 방식을 권한다. 여기에 하나 더 추가하자면, 단일 프롬프트로 동작하는 미니앱·HTML 게임 프로토타이핑 워크로드에도 적합하다. 이번 실험에서 7-블록 구조 프롬프트 하나로 게임 6개를 완성한 것이 그 증거다.

도입을 서두르지 않아도 될 팀: 일반 사무 자동화 중심이거나 MCP 도구 사용이 핵심이며, 환각률에 민감한 도메인(금융·법률·의료)인 경우. Claude Opus 4.7이나 GPT-5.4와의 성능·비용 비교를 우선 수행하는 것이 합리적이다.

Claude Code 'Claude Design이란?' 리뷰(1) : Figma 대체재인가, 보완재인가 - 디자인 시스템 설정부터 Claude Code 핸드오프까지

갓대희 — Thu, 23 Apr 2026 12:00:15 +0900

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

Anthropic Labs가 2026-04-17 공개한 Claude Design은 텍스트 프롬프트 한 줄에서 인터랙티브 프로토타입까지 직접 생성하는 도구이다. 접근 URL은 claude.ai/design이고 Pro/Max/Team/Enterprise 구독자에게 제공된다.

공식 문서(Help Center, Design System 문서, Pricing 문서)와 커뮤니티 리뷰를 직접 읽어 각 기능을 단계별로 정리한 것이다.

Claude Design은 Anthropic Labs의 research preview로, 기능·사용량 한도·내보내기 옵션은 공식 발표 이후에도 변경될 수 있다. 실제 사용 전 공식 발표 페이지와 Help Center에서 최신 상태를 다시 확인하자.

출시 배경과 포지셔닝
접근 방법과 요금제
캔버스 인터페이스 이해: 화면 구성과 3가지 인터랙션 모드
기능 1: 첫 프로젝트 생성 — 입력 방법 완전 가이드
기능 2: 디자인 시스템 설정 — 단계별 튜토리얼
기능 3: 인라인 코멘트 심화
기능 4: Adjustment Knobs (Custom Sliders)
기능 5: Chat 기반 광역 리파인
기능 6: 내보내기 6종 상세 튜토리얼
기능 7: Claude Code 핸드오프
기능 8: 공유와 협업
실전 예시 3가지
사용량 관리와 토큰 절약 전략
현재 알려진 제한과 주의사항
커뮤니티 반응
결정 매트릭스
결론

읽는 방법

각 섹션 제목 앞에 난이도 뱃지가 붙어 있다. 처음 읽는다면 초급 섹션만 따라오는 것을 권장한다 — 전체를 순서대로 읽으면 중간에 개발자 전용 내용이 섞여 어렵게 느껴질 수 있다.

초급 누구나 — 바로 써먹을 수 있는 내용

중급 선택 — 기본 사용에 익숙해진 뒤 참고

개발자 개발자 전용 — 비개발자는 건너뛰어도 무방

초급1. 출시 배경과 포지셔닝

Claude Design은 Anthropic Labs가 운영하는 실험 제품 인큐베이터의 결과물이다.

Anthropic Labs는 2026-01-13에 공식 소개된 조직으로, Claude Code·Model Context Protocol(MCP)·Skills·Claude in Chrome·Cowork를 앞서 론칭했다고 Anthropic 공식 발표는 기술한다.

Claude Design은 이 중에서 디자이너·PM·마케터를 주 대상으로, 디자인·프로토타입·슬라이드·원페이저 등 시각 산출물(polished visual work)을 생성하는 도구다.

1.1. 무엇을 입력하면 무엇이 나오는가

입력: 텍스트 프롬프트, 스크린샷, 이미지, DOCX/PPTX/XLSX 문서, Figma 파일(.fig), 코드 리포지토리, 웹 캡처

출력: 랜딩 페이지·UI 목업·피치덱·이메일/마케팅 에셋 등 시각 산출물

기반 모델은 Claude Opus 4.7(기본값)이며, 캔버스 내 모델 선택기에서 Claude Haiku 4.5 · Claude Sonnet 4.6 · Claude Opus 4.6 · Claude Sonnet 4.5 · Claude Opus 3로 전환 가능하다 (UI 직접 확인, 공식 문서에는 Opus 4.7만 명시).

1.2. 공식 포지셔닝

TechCrunch 보도에 따르면 Anthropic은 Claude Design을 Canva의 대체재가 아닌 보완재로 포지셔닝한다.

Figma에 대한 공식 포지셔닝은 별도로 언급되지 않았다.

발표 당일 Figma 주가는 장중 최대 약 7.28% 하락해 $18.84에 거래됐다고 OfficeChai가 보도하나, Claude Design 출시가 직접적 원인이라는 공식 출처는 확인되지 않는다.

독립 디자이너 Sam Henri Gold는 Claude Design의 핵심 차이를 다음과 같이 정의했다: "HTML and JS all the way down." (처음부터 끝까지 HTML과 JS다.) Figma가 독점 벡터 포맷 위에서 동작하는 반면 Claude Design은 실제 웹 구현 재료인 HTML/JS를 바로 생성한다는 뜻이다.

초급2. 접근 방법과 요금제

2.1. 접속 요건

두 가지가 필요하다.

첫째, Pro/Max/Team/Enterprise 중 하나의 구독.

둘째, claude.ai/design 접속 권한 (Anthropic 발표).

Enterprise는 기본값이 비활성화(off by default, 처음엔 꺼져 있음)이며 관리자가 Organization settings에서 직접 켜야 한다.

2.2. 사용량 구조와 플랜별 권장

Claude Design 사용량은 채팅 및 Claude Code와 완전히 별도의 주간 한도(weekly allowance)로 집계된다.

즉 Claude Design을 많이 써도 채팅 대화 횟수에는 영향이 없다.

ex) 실제 사용후 사용량 측정

플랜	공식 권장 용도	실사용 참고
Pro ($20/월)	Quick explorations, one-off use (간단한 탐색, 단발성 사용)	30분 사용으로 주간 한도 소진 보고 다수 (§13 참조)
Max 5x ($100/월)	Semi-regular (준정기적 사용) — PM·엔지니어의 정기 목업	정기 업무 사용 시 권장
Max 20x ($200/월)	Power use (집중 사용) — 디자이너·크리에이터 주업무	디자이너가 메인 도구로 쓰는 경우
Team ($30/인/월)	팀 단위 협업, 조직 디자인 시스템 공유	주간 한도(weekly allowance) 적용, 채팅과 별도 쿼터
Enterprise	Admin 활성화 필요, 대규모 조직 배포	usage-based (사용량 기반) 계정: 신규 사용자당 ~20 프롬프트 크레딧(만료 2026-07-17); seat-based (좌석 기반) 계정: 주간 한도 적용

최신 가격과 정확한 한도 수치는 공개되지 않았다. 플랜 결정 전 스스로 짧은 세션으로 소비량을 직접 측정해 보는 것이 안전하다.

초급3. 캔버스 인터페이스 이해: 화면 구성과 3가지 인터랙션 모드

Claude Design을 처음 열면 낯선 인터페이스가 나온다.

실제로 써본 리뷰어들의 공통된 묘사를 종합하면 "채팅박스에 프리뷰 창을 붙인 수준이 아니라 실제 디자인 환경처럼 느껴진다"는 점이 일관된 평가이다.

각 요소를 먼저 파악해 두면 이후 기능 튜토리얼이 훨씬 빠르게 이해된다.

3.1. 화면 레이아웃

화면 레이아웃

왼쪽 사이드바: 대화(chat) 입력창. 프롬프트 전송과 Claude 응답이 여기서 이루어진다.
오른쪽 캔버스: 라이브 프리뷰. 생성된 디자인이 실시간으로 렌더링된다.
상단 탭: 여러 프로젝트 변형(variation)과 하위 파일을 탭으로 전환.
우측 상단: Export 버튼.

3.2. 3가지 인터랙션 모드

캔버스와 상호작용하는 방법은 크게 세 가지다. 디자인 비평 플랫폼 Nervegna는 이를 가장 구체적으로 정리했다.

모드	동작 방식	쓸 때
Edit 모드	캔버스 요소를 직접 클릭 → 색상, 라인 높이 등 속성을 즉시 변경	텍스트 직접 수정, 단일 속성값 변경
Comment 모드	요소를 선택 후 자연어 명령 입력 ("make this bigger and center it" — 이거 더 크게 하고 가운데로)	특정 요소에 AI 적용이 필요한 변경
Draw 모드	프로토타입 위에 직접 스케치 → 시각적 지시로 전송	레이아웃 구조 변경, 손으로 그린 주석 전달

공식 문서 vs 커뮤니티 용어 정리: 공식 Help Center는 이 세 모드를 별도로 명명하지 않는다. 모드 이름(Edit/Comment/Draw)은 Nervegna 리뷰에서 정리한 표현이다.

공식 문서는 "direct edits," "inline comments," "adjustment knobs" 등의 기능으로 각각 기술한다.

초급4. 기능 1: 첫 프로젝트 생성 — 입력 방법 완전 가이드

4.1. 홈 화면 구성 — 처음 접속하면 보이는 화면

claude.ai/design에 접속하면 캔버스가 아니라 프로젝트 피커(project picker) 화면이 먼저 나온다. 왼쪽 생성 패널과 오른쪽 갤러리 패널로 구성된다.

왼쪽 — 새 프로젝트 생성 패널

프로젝트 타입 탭 4종 — 탭 선택에 따라 하위 옵션이 달라진다.
- Prototype: 인터랙티브 웹 프로토타입 생성 — 이 글의 주요 사용 흐름
- Slide deck: 발표용 슬라이드덱 생성 — 주제를 입력하면 여러 슬라이드로 구성된 프레젠테이션을 만들어 준다
- From template: 미리 제공된 템플릿을 골라 빠르게 시작하는 방법
- Other: 이메일·배너 등 기타 형식, Animated video(영상) 포함
Slide deck · From template · Other 탭의 상세 사용법과 영상 제작(Animated video)은 별도 글에서 자세히 다룰 예정이다.
Wireframe vs High fidelity: 결과물의 완성도를 선택한다. Wireframe은 구조 중심의 단순한 뼈대 시안, High fidelity는 색상·타이포그래피가 적용된 완성도 높은 시안이다. 처음 만드는 경우 High fidelity를 권장한다.
Project name: 프로젝트 이름 입력.
+ Create 버튼: 클릭하면 프로젝트가 생성되고 캔버스 화면으로 진입한다.
기본 공개 범위: "Only you can see your project by default." (기본적으로 본인만 볼 수 있다.) 공유 설정은 이후 변경 가능하다.
Set up design system 버튼: 하단에 위치. 조직 디자인 시스템 미설정 시 CTA로 표시된다. 상세 설정은 섹션 5에서 다룬다.

오른쪽 — 프로젝트 갤러리

Designs 탭: 내가 만든 프로젝트 목록. Recent / Your designs 필터와 검색 기능.
Examples 탭: Anthropic이 제공하는 예시 디자인 모음. 처음 사용 시 레퍼런스로 활용할 수 있다.
Design systems 탭: 조직에 등록된 디자인 시스템 목록(섹션 5 연결).

4.2. 프로젝트 생성 절차

브라우저에서 claude.ai/design에 접속한다. Pro/Max/Team/Enterprise 계정으로 로그인된 상태여야 한다.
왼쪽 패널에서 프로젝트 타입 탭을 선택하고, 이름을 입력한 뒤 + Create 버튼을 클릭한다.
새 프로젝트는 조직 디자인 시스템이 설정되어 있다면 자동으로 상속한다. "When you create a project, it automatically inherits your organization's design system." (프로젝트를 만들면 조직의 디자인 시스템이 자동으로 상속된다.)

중급4.3. 입력 방법

Claude Design은 다음 입력 방법을 지원한다.

① 텍스트 프롬프트

가장 기본 입력. 목표(goal), 레이아웃(layout), 콘텐츠(content), 타겟 독자(audience)를 포함하면 더 좋은 결과가 나온다. PCWorld 리뷰어는 "NYT/Pudding feel, serif headlines, generous whitespace, one accent color" (뉴욕타임스·Pudding 스타일, 세리프 헤드라인, 여백 넉넉하게, 포인트 색상 하나)처럼 구체적인 에스테틱 레퍼런스를 포함했을 때 결과가 향상됐다고 보고한다.

② 이미지·스크린샷·디자인 파일 업로드

기존 에셋이나 참고 스크린샷을 올린다. 지원 파일 확장자 목록은 공식 문서에 명시되지 않아 확인 불가. Opus 4.7 모델은 긴 변 기준 최대 2,576픽셀까지 이미지를 처리한다.

③ 문서 업로드 (DOCX/PPTX/XLSX)

회사 브랜드 가이드 PPT, 콘텐츠 스프레드시트 등을 입력으로 활용할 수 있다. "Upload images and documents (DOCX, PPTX, XLSX)"라고 공식 발표가 명시한다.

④ 코드베이스 연결

두 가지 방식으로 제공된다.

Connect GitHub: 원격 GitHub 리포를 연결한다.

Link code folder: 로컬 코드 폴더를 드래그하거나 browse로 선택한다. 대용량 코드베이스는 프론트엔드 또는 디자인 시스템 폴더만 업로드하도록 UI가 안내한다. ("For large codebases, drop the frontend or design system folder")

둘 다 Claude가 기존 코드에서 디자인 토큰과 컴포넌트를 자동 추출한다.
Vibecoding 리뷰는 iOS 리포를 연결했을 때 "a prototype that matched the existing app's visual language with no additional prompting" (추가 프롬프트 없이도 기존 앱의 시각 언어와 일치하는 프로토타입이 나왔다)이 출력됐다고 기록한다.

⑤ 웹 캡처 도구

웹사이트의 요소를 직접 가져올 수 있다.
공식 발표 원문: "You can also use the web capture tool to grab elements directly from your website so prototypes look like the real product." (웹 캡처 도구로 실제 웹사이트에서 요소를 바로 가져와, 프로토타입이 실제 제품처럼 보이게 할 수 있다.)

⑥ Figma 파일 (.fig) 업로드

UI에 "Drag in a Figma file" 버튼이 있고, 첨부 메뉴에는 "Upload .fig file"로 표시된다. 버튼 옆 ?는 베타 표시가 아니라 사용 방법을 안내하는 도움말 버튼이다 — 클릭하면 다음 절차가 표시된다 (UI 직접 확인):

Figma 웹 또는 데스크톱 앱에서 파일을 연다.
File → Save local copy... (웹: main menu → File)를 선택한다.
다운로드된 .fig 파일을 채팅 입력창에 드롭한다.

도움말 원문: "The file is parsed locally in your browser and never uploaded." (파일은 브라우저에서 로컬로 파싱되며 서버에 업로드되지 않는다.) — 개인정보 보호 관점에서 주목할 만한 특징이다. 공식 지원 문서에는 이 입력 방식이 별도로 기재되어 있지 않다.

⑦ 다른 프로젝트 참조 (Reference another project)

캔버스 첨부 메뉴에 "Reference another project" 항목이 있다 (UI 직접 확인). 기존에 만든 Claude Design 프로젝트를 현재 작업의 컨텍스트로 활용하는 기능으로 보인다. 공식 지원 문서에는 기재되어 있지 않으므로 동작 방식은 직접 확인이 필요하다.

⑧ Skills (디자인 모드 선택)

"Skills and design systems"에서 Claude가 만들어낼 결과물의 종류를 지정할 수 있다.

여기서 말하는 "Skills"는 Anthropic 일반 Skills 기능(조직 확장)과는 별개 개념이다.

Skill	UI 설명
Animated video	Timeline-based motion design
Interactive prototype	Working app with real interactions
Make a deck	Slide presentation in HTML
Make tweakable	Add in-design tweak controls
Frontend design	Aesthetic direction for designs outside an existing brand system
Wireframe	Explore many ideas with wireframes and storyboards

같은 패널에서 조직에 게시된 디자인 시스템도 선택할 수 있다.

디자인 모드를 별도로 지정하지 않으면 Claude가 프롬프트 맥락을 보고 자동으로 판단한다.

초급4.4. Claude의 온보딩 질문 (초기 프롬프트 직후)

프롬프트를 입력하면 Claude가 바로 생성을 시작하지 않고 먼저 설문을 제시한다.

간단한 예시: "포트폴리오 랜딩 페이지 만들어줘"라고 입력하면 Claude가 즉시 생성하는 대신, 목적·타겟 오디언스·비주얼 스타일을 먼저 묻는다. 텍스트 몇 줄로 답하면 된다. (아래에 실제 답변 화면 첨부 예정)

팁: 온보딩 질문에 답할 때 "타겟 오디언스"와 "비주얼 에스테틱" 항목에 구체적인 레퍼런스를 제공하면 초안 품질이 높아진다.
예: 에스테틱 레퍼런스에 "NY Times, serif headline, wide whitespace" 입력. 질문 자체가 이미 토큰을 소비하므로 Pro 플랜은 이 단계부터 사용량을 의식한다.

- 제일 기본적인 설정으로 시작 / 포트폴리오 랜딩 페이지 만들어줘 입력

- 설문조사를 마치면 디자인 설계를 시작한다.

- 요청 내용이 너무 부실하여 허접하지만 몇분 뒤 디자인이 생성 되긴 하였다.
( 실제 나의 경우 충분한 내용 전달을 잘 하였을때에는 퀄리티가 당연히 높아 만족스러운 퀄리티 였다. )

아래는 실제 진행 흐름 전체 사례다 — 개념만 파악했다면 다음 예시 내용은 건너뛰자.
(실제 내가 디자인을 돌려본 전과정을 올리다보니 내용이 너무 길어지는것 같다 Skip하길 권장 드립니다.)

ex) 실제 사용 예시 - 내가 원하는 사이트 컨셉을 정리하여 텍스트 프롬프트 + 이미지, 스크린샷 전달하여 디자인 생성 요청

1) 다음과 같이 프롬프트와 충분한 설명, 이미지 등을 작성하여 한방 프롬프트로 전달하여 테스트

( 상세한 디자인 설명 없이 얼마나 잘 작성하는지 확인, model은 opus 4.7에서 변경하지 않았다. )

- 프롬프트가 약 200라인으로(이미지도 포함) 너무 길기 때문에 작성하지 않았는데 혹여라도 동일하게 진행해보고자 하여 퀄리티 비교를 해보실분이라면 ... https://goddaehee.co.kr/guide/n8n-handson/agent 한줄을 입력해보는것을 추천드립니다.

- 물론 프롬프트 작성 이후 설문이 뜰텐데 설문의 방향은 달라지겠지만 유사한 컨텍스트를 가져가실수 있을 것 같다.

2) 4.4 Claude의 온보딩 질문이 시작되며, 이에 대한 답변 작성 (실제 답변도 참고)

3) 답변이 끝나면 실제 클로드가 일하는 방식 처럼 Task를 나누어 작업을 시작한다.

4) 작업 완료 알림 및 결과물

모든 Task가 완료되면 Claude가 결과물을 화면에 바로 렌더링해 보여준다. 결과 뷰어 상단에는 탭바가 생기며, 첫 번째 탭이 Design Files다. 이후 탭들은 Claude가 생성한 개별 HTML 페이지들이다.

Design Files 탭을 클릭하면 화면이 좌우로 나뉜다. 좌측은 Claude가 생성한 파일 전체를 탐색하는 패널이고, 우측은 선택한 파일의 미리보기다.

좌측 패널은 FOLDERS와 PAGES 두 섹션으로 구분된다.

FOLDERS: Claude가 내부적으로 생성한 소스 파일 트리다. 필자의 'n8n 핸즈온 가이드' 결과물을 보면 src/ 폴더 아래 sections/(콘텐츠 섹션들), App.jsx(루트 컴포넌트), components.jsx(공통 컴포넌트), Tweaks.jsx(Tweaks 패널 컴포넌트)가 있고, styles/main.css가 별도 폴더에 위치한다. Claude Design이 결과물을 React 컴포넌트 구조로 생성한다는 사실을 여기서 확인할 수 있다.
PAGES: 실제 출력된 HTML 페이지 목록이다. 파일명·타입·수정일·용량이 표시된다. 목록에서 파일을 클릭하면 우측 패널에 미리보기가 나타나고, Open 버튼으로 새 탭에서 바로 열 수 있다.

상단 오른쪽의 New sketch는 기존 프로젝트 맥락을 유지한 채 새 스케치를 추가하는 버튼이고, Paste는 외부에서 복사한 콘텐츠를 프로젝트에 붙여넣는 버튼이다.

ex) New sketch 화면

결과 화면에서 눈에 띄는 것이 Tweaks 패널이다. 오른쪽 하단에 위치한 이 패널은 Claude가 해당 결과물에 맞춰 동적으로 생성하는 커스터마이즈 컨트롤이다. 공식 문서는 "adjustment knobs to tweak spacing, color, and layout live", 즉 "실시간으로 간격·색상·레이아웃을 조정하는 노브"라고 설명한다. 클릭 한 번으로 결과물의 느낌을 즉석에서 바꿀 수 있다는 뜻이다.

위 스크린샷처럼 'n8n 핸즈온 가이드' 결과물에는 다음 항목이 Tweaks로 생성됐다.

ACCENT: 노랑·초록·주황·보라·하늘·분홍 6가지 포인트 컬러 — 선택 즉시 버튼, 배경 강조 등 전체 테마 색상이 바뀐다.

FONT: Pretendard / system-ui / Apple / Noto 중 선택 — 한국어 가독성을 고려한 폰트들이 포함돼 있다.

다크 모드: 토글 하나로 라이트↔다크 전환.

Tweaks 항목은 Claude가 프로젝트 성격에 따라 자동 결정한다. 공식 표현으로는 "whatever Claude decided was adjustable"(Claude가 조정 가능하다고 판단한 항목). 따라서 어떤 프로젝트는 컬러·폰트 외에 여백, 타이밍 값, 레이아웃 옵션이 추가로 나타날 수도 있다. 결과물을 받은 뒤 Tweaks를 먼저 훑어보고, 마음에 드는 조합을 찾아 Export하자.

오른쪽 상단 Export 버튼을 누르면 Download as .zip / Export as PDF / Export as PPTX / Export as standalone HTML / Handoff to Claude Code 등 다양한 형식으로 저장할 수 있다.

- Export 메뉴 맨 아래 Handoff to Claude Code...는 완성된 디자인을 코드 구현 단계로 넘기는 기능이다. 공식 설명은 "Claude packages everything into a handoff bundle that you can pass to Claude Code with a single instruction"(디자인 전체를 번들로 묶어 단 한 줄의 명령으로 Claude Code에 전달한다)이다. 과거 Google AI Studio의 Stitch가 프로토타입을 AI Studio 코딩 에이전트로 바로 넘기던 방식과 같은 개념이다.

Handoff to Claude Code...를 클릭하면 다이얼로그가 열리고, 상단에 두 탭이 나타난다.

Send to local coding agent: 로컬에서 실행 중인 Claude Code(터미널·IDE)로 핸드오프한다. 다이얼로그 중앙 터미널 프리뷰에 커맨드가 자동 생성된다.

Fetch this design file, read its readme, and implement the relevant aspects of the design. https://api.anthropic.com/v1/design/h/{id}?open_file={파일명}
Implement: {파일명}
Copy command 버튼으로 복사한 뒤 로컬 Claude Code 터미널에 붙여넣으면 바로 구현이 시작된다.

ex)Fetch this design file, read its readme, and implement the relevant aspects of the design. https://api.anthropic.com/v1/design/h/{id}?open_file={파일명} Implement: {파일명}

- 폴더 생성, 압축 해제 등 권한 허용

- 원래는 소스를 파악하고 바로 claude code로 개발 진행할 것으로 보이는데, 나의 경우 이미 구현을 다 해둬서 수정을 해버리는 모습이다.

Send to Claude Code Web: 브라우저 기반 Claude Code Web으로 핸드오프한다. Claude Code Web은 공식 설명대로 "works with repositories you may not have on your local machine" — 로컬에 코드베이스가 없어도 사용할 수 있어, 새 프로젝트를 처음부터 만들 때 적합하다.

다이얼로그 하단 OPTIONS에는 두 가지 추가 항목이 있다.

Download zip instead: 체크하면 번들을 .zip 파일로 내려받는다. 안내 문구 "Drop the bundle into your agent's chat manually."처럼, 자동 전송 대신 원하는 에이전트 채팅창에 직접 드래그·드롭하는 방식이다. Claude Code 외의 다른 코딩 에이전트를 쓸 때 유용하다.
Give the agent more detail on what to implement (optional): 에이전트에 전달할 추가 지시를 자유 텍스트로 입력한다. 특정 파일만 구현하거나 구현 범위를 좁히고 싶을 때 활용한다.

Tweaks로 디자인을 확정하고, Handoff to Claude Code로 구현을 넘기는 것이 Claude Design 워크플로의 마지막 단계다. 디자이너가 완성한 시안을 개발자에게 넘길 때 생기는 전달 비용을 Claude가 자동으로 제거하는 구조다.

ex) 내 실제 바이브 코딩용 사이트에 실제 적용까지 완료 하였다.

- https://goddaehee.co.kr/guide/n8n-handson/agent

중급5. 기능 2: 디자인 시스템 설정 — 단계별 튜토리얼

디자인 시스템은 Claude Design에서 브랜드 일관성을 유지하는 핵심 기능이다. 한 번 설정하면 이후 모든 새 프로젝트가 자동으로 상속한다.

이 섹션은 선택 사항이다. Slide deck · From template 탭으로 지금 바로 시작할 수 있으며, 조직 브랜드 일관성이 필요해질 때 이 섹션으로 돌아오면 된다. organization admin 권한과 브랜드 에셋(GitHub · Figma · 로고 등)이 준비되어 있을 때 진행하면 가장 효과가 좋다.

5.1. 사전 요건 확인

권한 확인 필수: 디자인 시스템 설정은 organization admin이 권한을 부여한 디자이너 또는 브랜드 오너가 진행한다. "Permissions granted by your organization admin" (조직 관리자에게 권한을 부여받아야 접근 가능하다)이 전제이므로, 막히면 admin에게 권한 부여를 요청한다.
준비할 자료: 다음 중 하나 이상. 모두 선택 사항(all optional)이지만 많을수록 결과가 좋아진다.
- 회사명과 브랜드 설명 텍스트 — 예: "Mission Impastabowl: fast-casual pasta restaurant with in-store touchscreen kiosk, mobile app and website"
- GitHub 리포 URL (프론트엔드/디자인 시스템 코드)
- 로컬 코드 폴더 (GitHub 없는 경우 대안)
- Figma .fig 파일 (Figma에서 File → Save local copy로 다운로드)
- 폰트·로고·에셋 파일 (PNG, PDF, PPT 브랜드 가이드 등)
- 추가 설명 메모 (색상 톤, 브랜드 보이스 등 자유 텍스트)

5.2. Organization Settings 접근 방법

claude.ai/design 화면의 왼쪽 하단 모서리에서 현재 조직 이름을 클릭한다. 공식 문서 원문: "In the lower-left corner of the project picker, click the current organization name." (프로젝트 선택 화면 왼쪽 하단에서 현재 조직 이름을 클릭한다.)
조직을 선택하거나, 없다면 새로 생성한다.
Organization settings 화면으로 진입한다.

5.3. 디자인 시스템 설정 폼 입력 가이드

실제 설정 폼은 "Set up your design system — Tell us about your company and attach any design resources you have."로 시작하며 다음 필드로 구성된다.

① Company name and blurb

회사명과 브랜드 설명을 한 문장으로 입력한다. 예: "Mission Impastabowl: fast-casual pasta restaurant with in-store touchscreen kiosk, mobile app and website" — 어떤 제품을 어떤 채널에서 사용하는지 맥락을 줄수록 결과가 정확해진다.

② Link code on GitHub

GitHub 리포 URL을 입력하고 Add 버튼을 클릭한다. 공식 문서: "If your design system lives in code (for example, a React component library), you can link or upload the repository." Claude가 컴포넌트·CSS 토큰을 자동 추출한다.

③ Link code from your computer

로컬 코드 폴더를 드래그하거나 browse로 선택한다. GitHub 없이도 사용 가능하다.

"This doesn't upload the whole codebase; Claude will copy selected files. For large codebases, we recommend attaching a frontend-focused subfolder."

④ Upload a .fig file

Figma .fig 파일을 드래그하거나 browse로 선택한다. 준비 방법: Figma → File → Save local copy → 다운로드된 .fig 파일 업로드.

"Parsed locally in your browser — never uploaded."

⑤ Add fonts, logos and assets

로고 PNG, 폰트 파일, 브랜드 가이드 PDF·PPT 등 시각 에셋을 드래그하거나 browse로 선택한다. 공식 문서는 "Even a well-designed PowerPoint or PDF that reflects your brand can work. Claude extracts colors, layout patterns, and typographic choices."라고 명시한다.

⑥ Any other notes?

브랜드 보이스, 선호 색감, 코너 반경 등 자유 텍스트로 추가 맥락을 제공한다. 예: "We use a warm, earthy color palette with rounded corners. Our brand voice is playful but professional."

ex) Link code from your computer 방법으로 폴더를 지정하여 진행해보았따.

- 로컬 코드 폴더 지정 및 간단한 소개 입력

- 우상단 Continue to generation 버튼 클릭

- 5분 정도 소요 예상된다고 한다.

- 작업 상황 관찰한 이력

- 버그 발생

- 어쩔수 없이 github 연동하여 진행

- 이번엔 정상 동작하는 모습

- 작업 중 계속 피드백을 줄 수 있다. (이번엔 테스트이니 모두 허용)

- 너무 복잡한 프로젝트를 제공했더니 추가 요청사항이 있어 답변

- 한참 끝에 완료 되엇다.

- Design System 결과물

5.4. Claude가 추출하는 디자인 시스템 구성요소

업로드한 자산을 분석한 Claude는 다음 네 가지를 자동으로 구성한다.

Color palette: Primary, Secondary, Accent 색상. 코드 리포에서 연결하면 Tailwind CSS 토큰까지 추출된다는 커뮤니티 보고가 있다.
Typography: Font families, sizes, weights.
Components: Buttons, cards, navigation elements.
Layout patterns: Spacing, grid systems, page structures.

5.5. Published 토글 켜기

디자인 시스템 구성이 완료되면 Published 토글을 켠다. 공식 문서 원문: "Make sure the 'Published' toggle is switched on." (Published 토글이 켜져 있는지 확인한다.)
토글을 켜면 조직 내 모든 새 프로젝트에 자동 적용된다. 원문: "After publishing, any projects created from the Claude Design homescreen while in your organization will use your design system." (게시 후에는 조직 내에서 Claude Design 홈 화면으로 만든 모든 프로젝트에 디자인 시스템이 자동 적용된다.)
Published 토글을 켠 후 새 프로젝트를 열어 디자인 시스템이 반영되는지 확인한다. 이전에 만든 프로젝트에는 소급 적용되지 않으므로 새 프로젝트로 테스트한다.

ex) Design System Tab 확인

- Published에 토글이 켜져있다. 새프로젝트를 열어보자.

- Design system 선택 후 Create

- 기본적으로 추가되어있는것으로 보이지만 실제 결과를 테스트 해봐야 겠다.

- 나 바이브 코딩 프로젝트의 디자인 시스템 로드 완료된 모습

주의: 디자인 시스템 생성 자체가 Claude Design 사용량(주간 한도)을 소비한다. Nervegna 리뷰에 따르면 "디자인 시스템 생성 1회 + 프로토타입 1개로 Pro 주간 한도의 65%를 소진했다"는 보고가 있다. 디자인 시스템은 조직 전체에서 한 번만 설정하고 재사용하는 것이 사용량 절약에 효율적이다.

ex) 디자인 시스템 만들고 나니 28% 정도 사용 되었다. (이전 22%)

초급6. 기능 3: 인라인 코멘트 심화

인라인 코멘트는 캔버스의 특정 요소를 집어 "이 부분만 바꿔달라"고 지시하는 기능이다. 전체 레이아웃을 재생성하지 않고 원하는 지점을 콕 집어 변경을 요청할 때 쓴다.

6.1. 인라인 코멘트 사용 방법

캔버스에서 수정하고 싶은 요소를 직접 클릭한다. 공식 원문: "Inline comments let you click directly on a specific part of the canvas and request a targeted change." (인라인 코멘트를 쓰면 캔버스의 원하는 부분을 직접 클릭해 딱 그 부분만 바꿔달라고 요청할 수 있다.)
클릭한 요소에 대한 변경 요청을 자연어로 입력한다.
Claude가 해당 요소만 수정한다. 다른 섹션은 그대로 유지된다.

ex) 코멘트 클릭 > 요소 직접 클릭

- 코멘트 입력 및 전송

- 작업 완료 (버그로 새로고침해야 볼 수 있었다.)

6.2. 인라인 코멘트가 적합한 변경 vs Chat이 적합한 변경

둘의 차이를 알고 쓰는 것만으로 편집 효율이 크게 달라진다.

방법	적합한 변경 유형	공식 예시
인라인 코멘트	특정 요소의 타겟 변경	버튼 패딩 조정, input 타입 변경, 브랜드 색상 적용, 섹션 접기(collapsible) 처리
Chat	전체 톤·레이아웃 광역 변경	컬러 스킴 변경, 레이아웃 재배치, 섹션 추가, 디자인 대안 생성

# 인라인 코멘트로 잘 되는 요청 예시
[CTA 버튼 클릭 후] "Make this button padding larger"
[히어로 제목 클릭 후] "Make this heading font size larger and font weight bold"
[특정 카드 클릭 후] "Apply brand primary color (#0066cc) to this card border"
[토글 버튼 클릭 후] "Convert this to a collapsible accordion"

# Chat으로 보내야 하는 요청 예시
"Make the overall color scheme darker and more minimal"
"Rearrange sections: move pricing above features"
"Add a testimonials section after the hero"
"Generate 3 alternative hero designs"

6.3. 협업에서의 인라인 코멘트

인라인 코멘트는 팀원이 디자인을 직접 편집하지 않고 주석만 달 때도 활용된다.

원문: "My team can jump into a Claude Design project and leave comments without editing directly. A designer can annotate 'this hierarchy is wrong' without touching the implementation."
(팀원이 Claude Design 프로젝트에 들어와 직접 편집 없이 코멘트만 남길 수 있다. 디자이너가 구현을 건드리지 않고 '이 계층 구조가 잘못됐어'라고 주석을 달 수 있다.)

6.4. 알려진 버그와 워크어라운드

버그 (공식 확인): 인라인 코멘트가 Claude가 읽기 전에 사라지는 현상이 간헐적으로 발생한다. 공식 원문: "Inline comments occasionally disappear before Claude reads them." (인라인 코멘트가 Claude가 읽기 전에 간헐적으로 사라진다.)

공식 워크어라운드: 코멘트가 반영되지 않으면 피드백 내용을 chat에 직접 붙여 넣는다. 공식 원문: "If your comments aren't being picked up, paste the feedback directly into the chat instead." (코멘트가 반영이 안 된다면 피드백을 그냥 채팅에 붙여넣자.)

초급7. 기능 4: Adjustment Knobs (Custom Sliders)

7.1. 용어 정리

이 기능은 두 가지 이름으로 불린다.

Anthropic 공식 발표는 "adjustment knobs"를 사용하고, Anthropic 공식 발표는 "custom sliders (made by Claude)"라고도 표현하며, 커뮤니티 리뷰들은 두 명칭을 혼용한다.

이 글에서는 공식 발표 기준 "adjustment knobs"를 주 명칭으로 쓰되 괄호 안에 "custom sliders"를 병기한다.

7.2. 이 기능이 하는 일

Adjustment Knobs는 프롬프트를 새로 쓰지 않고 디자인의 spacing, color, layout을 실시간으로 조정하는 컨트롤이다.

런치 당시 발표 자료에 인용된 문구: "Use adjustment knobs to tweak spacing, color, and layout live."

(adjustment knobs로 간격, 색상, 레이아웃을 실시간으로 조정한다.)

Banani 리뷰는 이를 구체적으로 묘사한다: "adjust spacing, color, and layout in real time without needing to write a prompt." (프롬프트를 새로 쓸 필요 없이 간격, 색상, 레이아웃을 실시간으로 조정한다.)

7.3. 핵심 차별점: Claude가 해당 디자인에 맞는 Knobs를 생성한다

일반적인 디자인 툴의 슬라이더와 결정적으로 다른 점이 있다.

Vibecoding 리뷰는 이를 가장 잘 설명한다: "a sidebar with sliders, toggles, and natural-language tweaks that modify any element without triggering a full regeneration."

(전체 재생성 없이 어떤 요소든 수정할 수 있는 슬라이더, 토글, 자연어 조정 기능을 갖춘 사이드바.) The Register는 공식 워크플로우 설명에서 "custom sliders (made by Claude)"라고 병기했다.

즉 knobs(슬라이더)는 고정된 범용 컨트롤이 아니라, 해당 디자인의 컨텍스트에 맞게 Claude가 생성해주는 조정 컨트롤이다. 예를 들어 hero 섹션이 있는 랜딩 페이지라면 "hero font scale" 슬라이더가, 카드 레이아웃이 있다면 "card gap" 슬라이더가 자동 생성되는 식이다. Vibecoding 리뷰어 Austin Lau는 이 기능이 "런치 커버리지에서 가장 덜 주목받은 기능"이라고 평했다.

7.4. 사용 흐름

초안 생성 후 Adjustment Knobs 패널에 접근한다. (UI 위치 정확한 메뉴명은 공식 문서에 기술되지 않아 확인 불가.)
생성된 knobs 목록을 확인한다. 제어 가능한 공식 확인 속성: spacing, color, layout.
슬라이더나 토글을 조작해 실시간 캔버스 변화를 확인한다. 전체 재생성 없이 즉각 반영된다는 점이 핵심이다.
타이포그래피 조정 가능 여부는 공식 문서에 명시되지 않아 확인 불가.

언제 Adjustment Knobs를 쓰는가: "색상을 조금 더 진하게", "섹션 간격을 조금 더 넓게" 같은 정도 조절(degree tweaking)에 적합하다. 새 섹션 추가, 전체 컬러 스킴 교체 같은 구조적 변경은 chat으로 보낸다.

초급8. 기능 5: Chat 기반 광역 리파인

Chat은 전체 디자인의 방향을 바꾸거나 구조적 변경을 요청할 때 쓴다. 인라인 코멘트(특정 요소 타겟)와 대비되는 "광역 지시" 채널이다.

8.1. Chat 리파인이 적합한 경우

전체 컬러 스킴 변경: "Make the color scheme darker and more minimal" (전체 색상을 더 어둡고 미니멀하게)
레이아웃 재배치: "Move the pricing section above the features section" (pricing 섹션을 features 섹션 위로 올려)
섹션 추가/삭제
대안 시안 생성: "Show me 3 alternative hero designs" (hero 디자인 3가지 대안을 보여줘)
전체 톤 변경: "Make the overall tone more playful and less corporate" (전체 톤을 더 유쾌하고 덜 딱딱하게)

8.2. 효율적인 Chat 리파인 전략

# 비효율: 인라인 작업을 Chat에 몰기
"hero 제목 폰트 크게, CTA 버튼 라운딩 8px, feature 카드 간격 줄이기"

# 권장: Chat은 구조·방향, 인라인은 포인트 처리로 분리
[Chat]   "전체 컬러를 다크 네이비 기반으로 바꾼다. pricing 가운데 플랜을 강조한다."
[인라인] 각 세부 요소는 캔버스에서 개별 클릭 후 처리

Vibecoding 리뷰는 "단일 컴포넌트부터 시작하라"고 권장한다.

원문: "Start small: a single landing page, a pricing section, a login screen."

(작게 시작하라. 랜딩 페이지 1개, pricing 섹션 1개, 로그인 화면 1개처럼.)

복잡한 멀티섹션 디자인을 한 번에 요청하면 수정 사이클이 복잡해지고 사용량도 빠르게 소진된다.

초급9. 기능 6: 내보내기 6종 상세 튜토리얼

Export 버튼은 화면 우측 상단에 있다. 클릭하면 6가지 포맷이 제공된다.

개발자9.1. Download as .zip

용도: 전체 에셋을 로컬로 저장하거나 개발자에게 전달할 때.

포함 내용: Vibecoding 리뷰는 핸드오프 번들 구성으로 /pages/landing.tsx, /components/pricing-card.tsx, /styles/tokens.css 형태의 파일을 언급한다. 공식 문서에는 zip 내 파일 목록이 명시되지 않아 확인 불가.

절차: Export 버튼 → "Download as .zip" 선택 → 파일 저장.

9.2. Export as PDF

용도: 인쇄, 이메일 첨부, 사내 리뷰 공유.

특성: 정적 이미지 기반. 인터랙티브 요소는 동작하지 않는다.

설정 옵션 (페이지 크기, 해상도 등): 공식 문서에 기술되지 않아 확인 불가.

절차: Export 버튼 → "Export as PDF" 선택 → 파일 저장.

9.3. Export as PPTX — 두 종류

용도: 피치덱, 사내 발표, 슬라이드 기반 리뷰.

UI에 두 가지 옵션이 별도로 제공된다 (UI 직접 확인, 공식 문서 미기재).

옵션	특성	권장 용도
Export as PPTX (editable)	Native text & shapes — PowerPoint에서 텍스트·도형을 직접 편집 가능	내용 수정이 필요한 발표, 협업
Export as PPTX (screenshots)	Flat images — 픽셀 완벽 이미지로 변환, 편집 불가	디자인 그대로 보존, 외부 공유

절차: Export 버튼 → 원하는 PPTX 옵션 선택 → 파일 저장 → PowerPoint에서 열기.

9.4. Send to Canva

용도: 소셜 카드·마케팅 에셋 대량 제작, Canva 템플릿 기반 후처리.

배경: Canva CEO Melanie Perkins는 "Claude Design의 아이디어와 드래프트를 Canva로 seamless(매끄럽게, 별도 설정 없이)하게 가져올 수 있다"고 발표했다.

Canva 계정 연동 요건: 공식 문서에 명시되지 않아 확인 불가. Canva 계정이 필요한지 여부는 직접 확인한다.

절차: Export 버튼 → "Send to Canva" 선택 → Canva로 이동 후 연동 진행.

중급9.5. Export as Standalone HTML

용도: 서버 없이 바로 열리는 프로토타입 공유, 인터랙티브 프리뷰.

특성: 공식 발표는 "standalone HTML files"라고 명시한다. 외부 의존성 없는 완전한 단일 파일인지는 공식 문서에 명시적으로 확인되지 않는다. PCWorld 리뷰어는 "plain-text 프리뷰 경고가 단일 HTML 익스포트에 변형이 완전히 통합되지 않았음을 시사했다"고 기록했다. 실제 사용 전 직접 확인 권장.

내부 포맷: 독립 디자이너 Sam Henri Gold는 "HTML and JS all the way down"이라고 평했다. 인터랙티브 요소(호버 스테이트, 테마 토글 등)도 포함된다.

절차: Export 버튼 → "Export as standalone HTML" 선택 → .html 파일 저장 → 브라우저에서 열기.

개발자9.6. Handoff to Claude Code

이 포맷은 §10에서 별도로 상세 설명한다. Claude Design을 벗어나 실제 구현 단계로 넘어가는 과정이기 때문이다.
( 이미 상기 예시에서도 리뷰하긴 하였다. )

개발자10. 기능 7: Claude Code 핸드오프

Claude Design에서 디자인이 완성되면 Claude Code로 핸드오프해 실제 구현 단계로 바로 넘어갈 수 있다. 단순 목업 도구와 달리, 디자인에서 코드까지 같은 생태계 안에서 이어지는 게 이 도구의 핵심이다.

10.1. 핸드오프 메커니즘

공식 발표 원문: "When a design is ready to build, Claude packages everything into a handoff bundle that you can pass to Claude Code with a single instruction." (디자인이 구현 준비가 되면, Claude가 모든 것을 핸드오프 번들로 패키징해 단 하나의 명령으로 Claude Code에 넘길 수 있다.)

Nervegna 리뷰는 실제 절차를 다음과 같이 묘사한다: "You export from Claude Design, copy a command, paste it into Claude Code, and it fetches the design file from an API endpoint." (Claude Design에서 내보내기 후 커맨드를 복사해 Claude Code에 붙여넣으면, Claude Code가 API 엔드포인트에서 디자인 파일을 가져온다.)

10.2. 단계별 핸드오프 절차

Claude Design에서 Export 버튼 클릭.
"Handoff to Claude Code" 선택. 두 가지 옵션이 있다:
- Local agent: Claude Code CLI가 설치된 로컬 환경에서 실행.
- Web: 브라우저에서 이어서 작업.
내보내기 후 커맨드를 복사한다. (Nervegna 리뷰 기준)
Claude Code 터미널 또는 웹 인터페이스에 커맨드를 붙여넣는다.
Claude Code가 API 엔드포인트에서 디자인 파일을 가져와 구현을 시작한다.

10.3. 핸드오프 번들 내용

공식 문서는 번들에 포함되는 구체적 파일 목록을 기술하지 않는다. Vibecoding 리뷰는 핸드오프 번들에서 다음 파일 구조를 언급했다.

[커뮤니티 보고 - 공식 확인 미완료]
/pages/landing.tsx       → 랜딩 페이지 컴포넌트
/components/pricing-card.tsx  → UI 컴포넌트
/styles/tokens.css       → Tailwind CSS 토큰

10.4. 디자인 시스템과 핸드오프의 연결

Claude Code 핸드오프 결과가 팀 코드베이스 스타일과 다르게 나온다면 Organization settings의 디자인 시스템에 해당 리포지토리가 Published 상태로 연결되어 있는지 확인한다. Remix 버튼으로 시스템을 보정한 뒤 재생성할 수 있다.

초급11. 기능 8: 공유와 협업

11.1. 공유 링크 생성

공유 링크 생성 버튼의 위치는 공식 문서에 명시되지 않아 확인 불가. 생성 시 세 가지 권한 수준 중 하나를 선택한다.

권한 수준	기능 범위	사용 시나리오
View-only	조회만 가능. 수정 불가.	임원 리뷰, 클라이언트 프리뷰
Comment	코멘트 추가 가능. 구현 직접 편집 불가.	팀 피드백 수집, 디자이너 주석
Edit	디자인 직접 수정 가능.	협업 작업, 공동 편집

11.2. 공개 범위

공식 발표 원문: "Keep a document private, share it so anyone in your organization with the link can view it, or grant edit access so colleagues can modify the design." (문서를 비공개로 유지하거나, 링크를 가진 조직 내 누구나 볼 수 있도록 공유하거나, 동료가 디자인을 수정할 수 있도록 편집 권한을 부여할 수 있다.)

이 표현에서 "your organization"이 반복됨을 주목한다. 조직 외부 사용자(외부 클라이언트 등)와의 공유 가능 여부는 공식 문서에 명시되지 않아 확인 불가. 외부 공유가 필요한 경우 PDF 또는 Standalone HTML로 내보내는 것이 현재로서는 안전한 대안이다.

11.3. 실시간 멀티플레이어 편집 — 현재 미지원

Figma처럼 두 명 이상이 동일 캔버스를 실시간으로 같이 편집하는 기능은 현재 없다. 이는 복수의 커뮤니티 리뷰에서 공통으로 지적한 launch-time 한계다. 팀 2인 이상이 실시간 공동 편집이 필수라면 현재는 Figma를 병행하는 것이 권장된다.

초급12. 실전 예시 3가지

아래 시나리오는 공식 워크플로(Create → Refine → Export)를 기반으로 한국어 실무에 맞춰 재구성한 것이다. 실제 결과물은 환경·프롬프트·디자인 시스템 설정에 따라 달라진다.

12.1. 예시 A — SaaS 랜딩 페이지

목표: 핀테크 SaaS "Finsight"의 랜딩 페이지 초안을 브랜드 가이드 기반으로 생성.

【 Create 】
"Finsight" 핀테크 SaaS 랜딩 페이지를 만든다.
- 섹션: hero, 3-feature row, 고객 로고, pricing 3-tier(starter/growth/enterprise),
  FAQ, footer
- 톤: 전문적이고 신뢰감 있는 금융
- 첨부한 브랜드 가이드 PDF의 컬러와 타이포그래피를 따른다
- 에스테틱: corporate but modern, sans-serif, generous whitespace

【 온보딩 질문 응답 예시 】
타겟 오디언스 → 중소기업 CFO, 재무팀장
포맷 → Single landing page
비주얼 에스테틱 → Clean fintech, Bloomberg Terminal meets Stripe
인터랙션 스타일 → Scroll animations, hover states on CTA

【 Refine - Chat 】
전체 컬러를 다크 네이비 기반으로 바꾼다.
pricing 가운데(growth) 플랜에 "Most popular" 배지를 추가한다.
hero 카피를 12단어 이내로 줄인다.

【 Refine - 인라인 코멘트 】
[hero 제목 클릭] "더 크고 굵게"
[CTA 버튼 클릭] "라운딩 8px로"
[feature row 클릭] "아이콘을 line style로 통일"

【 Adjustment Knobs 】
section gap: 조금 넓게
primary color saturation: 조금 낮게

【 Export 】
Standalone HTML + Handoff to Claude Code (local)

【 기대 결과 】
첨부 브랜드의 컬러가 반영된 초안 HTML.
Brilliant 사례에서 "경쟁 툴에서 20개 이상의 프롬프트가 필요했던 페이지를
2개로 줄였다"는 보고가 있으나 이는 Anthropic 발표에 수록된 단일 사례다.

개발자12.2. 예시 B — 모바일 앱 온보딩 목업

목표: 기존 iOS 리포지토리 스타일과 일치하는 온보딩 3화면.

【 디자인 시스템 사전 설정 (권장) 】
Organization settings에서 iOS 앱 GitHub 리포를 먼저 연결 → Published 토글 ON
→ 이후 생성하는 모든 프로젝트에 기존 컴포넌트 패턴이 자동 상속됨

【 Create 】
연결한 iOS 리포지토리의 기존 디자인 언어를 참고해 온보딩 3화면을 만든다.
- 화면1: 가치 소개. 화면2: 권한 요청. 화면3: 첫 작업 유도.
- iPhone 15 Pro 프레임에 맞춘 모바일 레이아웃.

【 Refine - 인라인 코멘트 】
[primary CTA 클릭] "각 화면의 primary CTA 위치를 safe area 하단에 고정한다"
[화면2 권한 카피 클릭] "한국어로 바꾼다. 20자 이내."

【 Export 】
PNG 포함 .zip + Handoff to Claude Code (local)

【 커뮤니티 근거 】
iOS 리포를 연결했을 때 "a prototype that matched the existing app's
visual language with no additional prompting"이 출력됐다는 보고 있음
(Vibecoding 리뷰 — 2차 인용, 개별 환경에서 직접 검증 권장)

12.3. 예시 C — B2B 이메일 템플릿 3종

목표: SaaS 온보딩 이메일 시퀀스 3종 세트.

【 Create 】
B2B SaaS 고객 온보딩 이메일 3종을 만든다.
- 메일1: 가입 환영 + 체크리스트 3개.
- 메일2: Day 3 기능 하이라이트 + CTA.
- 메일3: Day 7 성공 사례 + 업그레이드 제안.
600px 너비, 다크 모드 호환. 첨부 브랜드 가이드 컬러 적용.

【 Refine - Chat 】
메일2 CTA 버튼 색을 브랜드 오렌지로.
모든 이메일에 푸터 주소와 수신거부 링크 추가.

【 Adjustment Knobs 】
button corner radius: 최소로 (각진 스타일)
section padding: 넉넉하게

【 Export 】
Standalone HTML (각 이메일을 개별 파일로)

【 주의 】
이메일 템플릿은 공식 use case 문서에 직접 명시되지 않았으나,
HTML 내보내기와 에셋 생성 범위로 볼 때 재현 가능한 시나리오로 판단한다.

초급13. 사용량 관리와 토큰 절약 전략

Claude Design에서 가장 먼저 부딪히는 실용적 문제가 사용량 소진이다. Pro 플랜 기준 복수의 독립적 리뷰가 30분 내외로 주간 한도가 소진됐다고 보고한다. 사용량 관리는 선택이 아닌 필수다.

한도 구조 (공식 문서 확인): 주간 사용 한도는 개인(user) 단위로 적용된다. 조직 레벨에서 한도를 공유하거나 풀링하는 구조가 아니므로, 팀 구성원 각각이 별도의 주간 한도를 갖는다. Max 플랜도 동일 구조다.

13.1. 실제 소진 사례 (커뮤니티 보고)

사례	소비량	출처
완전한 디자인 세션 2회	Pro 주간 한도의 58%	Vibecoding (2차 인용)
디자인 시스템 생성 1회 + 프로토타입 1개	Pro 주간 한도의 65%	Nervegna/Substack
약 30분 작업 (variation 3회 + 재빌드 1회)	Pro 주간 한도의 100%	PCWorld

13.2. 토큰 절약 전략 5가지

디자인 시스템은 조직에서 한 번만 설정: 디자인 시스템 생성 자체가 많은 토큰을 소비한다. 팀에서 공유되는 조직 디자인 시스템을 한 번 설정해 두면 이후 프로젝트마다 재생성할 필요가 없다.
단일 컴포넌트부터 시작: 멀티섹션 전체 페이지를 한 번에 요청하면 수정 사이클이 많아진다. 랜딩 페이지 1개 → 마음에 들면 섹션 추가 방식으로 접근한다.
Adjustment Knobs로 세부 조정: Chat 또는 인라인 코멘트로 매번 재생성하는 것보다 Adjustment Knobs로 실시간 조정하면 토큰 소비 없이 미세 조정이 가능하다.
Sonnet으로 모델 전환: 세부 텍스트 수정이나 소규모 조정은 Opus 4.7 대신 Sonnet 4.6으로 전환해 토큰을 아낄 수 있다. PCWorld 리뷰어가 이 방법을 사용했다. 단, 모델 전환이 결과물 품질에 미치는 영향은 케이스별로 다를 수 있다.
Pro는 소비 패턴 먼저 측정: 첫 주에 실제 작업 흐름과 동일한 짧은 세션을 2~3회 진행해 주간 한도가 얼마나 빠르게 소진되는지 먼저 파악한다. 그 결과를 기준으로 Max 플랜 업그레이드 여부를 결정하는 것이 안전하다.

초급14. 현재 알려진 제한과 주의사항

14.1. 공식 Known Limitations

공식 Help Center가 명시한 4가지 한계.

인라인 코멘트가 간헐적으로 사라지는 현상 — 상세와 워크어라운드는 §6.4 참조.
Compact view mode에서 저장 오류가 발생할 수 있음.
큰 리포지토리를 연결하면 lag 또는 브라우저 문제가 발생할 수 있음.
Chat upstream error 발생 시 새 chat 탭으로 이동.

14.2. 결과물 품질 한계 (커뮤니티 공통 지적)

초기 출력물의 색상 구성 오류: Nervegna는 "검정 텍스트가 어두운 짙은 녹색 배경 위에 렌더링되어 전혀 읽을 수 없었다"는 사례를 보고했다. 첫 생성 결과의 접근성과 가독성을 항상 확인한다.
제네릭한 미학 수렴: 여러 리뷰에서 "blue-to-purple gradient, card-based layout, round corners, generous padding"으로 수렴하는 경향을 공통으로 지적한다. 브랜드 차별화는 디자인 시스템과 구체적 에스테틱 지시가 함께 있어야 한다.
컴포지션 판단 한계: 브랜드 컬러는 정확히 추출하지만 색상의 구도적 사용은 잘못될 수 있다 (Nervegna). 도구 출력을 그대로 받지 말고 반드시 사람이 검수한다.

14.3. 현재 없는 기능

공식 발표에는 이 항목들의 부재가 직접 언급되지 않는다. 아래는 커뮤니티 리뷰가 launch-time 한계로 정리한 내용이다.

실시간 멀티플레이어 편집 없음 — 상세와 권장 대안은 §11.3 참조.
Public API 없음
Figma 직접 import 없음
Undo/Redo: 전통적 버전 히스토리 없음. 대신 Help Center는 "Save what we have and try a completely different approach" (현재 상태를 저장하고 완전히 다른 방향을 시도해보자) 명령으로 현재 상태를 저장한 뒤 다른 방향을 실험하는 방식을 버전 관리 방법으로 안내한다.

14.4. 데이터·프라이버시

Team/Enterprise 구독은 Anthropic Commercial Terms에 따라 기본적으로 모델 학습에 사용되지 않는다. Pro/Max 등 Consumer 플랜의 학습 사용 여부는 계정 데이터 프라이버시 설정에 따른다. 정확한 조건은 Anthropic Privacy Center에서 확인한다.

14.5. 트러블슈팅 Q&A

Q1. claude.ai/design에 접속해도 빈 화면이거나 홈으로 리다이렉트된다.

Pro/Max/Team/Enterprise 중 하나로 로그인됐는가. Free 계정은 접근 불가.
Enterprise 플랜이라면 Organization settings에서 Claude Design을 활성화했는가 (기본값 off).
출시 초기 rollout 중이라면 몇 시간 후 재시도한다.
모바일 앱 지원 여부는 공식 문서에 명시되지 않아 확인 불가. 현재는 웹 브라우저를 기본으로 가정한다.

Q2. 인라인 코멘트가 반영되지 않는다.

§6.4의 공식 워크어라운드를 참조한다(코멘트 내용을 chat에 붙여넣기).

Q3. 주간 한도가 너무 빨리 소진된다.

한도 소진이 걱정된다면: §13.1 소진 사례 표와 §13.2 절약 전략 5가지를 먼저 확인한다. 정확한 주간 한도 수치는 공개되지 않아 본인 소비 패턴을 직접 측정해야 한다.

Q4. Claude Code 핸드오프 결과가 우리 팀 스타일과 다르다.

Organization settings 디자인 시스템에 해당 코드 리포지토리가 Published 상태로 연결되어 있는지 확인한다. Remix 버튼으로 시스템을 보정 후 재생성한다.

Q5. Chat upstream error가 발생한다.

공식 권장: 새 chat 탭을 열어 재시도한다.

초급15. 커뮤니티 반응

15.1. Hacker News: "균질화" 논쟁

출시 당일 Hacker News 스레드(id=47806725)는 1,191 points, 740 comments를 기록했다. 핵심 논쟁은 디자인 "균질화(homogenization)"다.

ljm (비판): "something like this has only been possible to develop because of how homogenous the internet has become" (이런 도구가 개발 가능했던 건 인터넷이 그만큼 균질해졌기 때문이다) — AI 디자인 도구의 성능이 웹의 수렴을 전제로 한다는 지적.

crazygringo (옹호): "A competent UI with little effort is a godsend" (수고 없이 쓸 만한 UI가 나온다는 건 정말 반갑다) — 예측 가능하고 얌전한 UI의 실용적 가치 옹호.

15.2. 디자이너 커뮤니티

독립 디자이너 Sam Henri Gold는 Claude Design의 재료적 정직함에 호의적이었다. "Claude Design is honest about what it is: HTML and JS all the way down." (Claude Design은 자신이 뭔지 솔직하다. 처음부터 끝까지 HTML과 JS다.) Figma의 복잡한 변수 aliasing·중첩 컴포넌트와 대비되는 단순함을 긍정한다.

반면 Tommaso Nervegna는 유보적이다. "When you delegate design to an AI and accept the output without deep design thinking, you're importing a set of decisions you didn't consciously make." (AI에게 디자인을 맡기고 깊은 고민 없이 결과물을 받아들이면, 스스로 의식하지 못한 채 누군가의 결정을 그대로 들여오는 것이다.) 브랜드 컬러는 정확하지만 검정 텍스트를 어두운 배경 위에 올리는 등 구도적으로 나쁜 결정이 섞인다는 실무적 비판이다.

The Register는 베테랑 디자이너 Molly McCoy의 평가를 인용했다: AI 툴은 프리미엄 디자인 작업에 필요한 "consultative depth" (컨설팅 수준의 깊이와 맥락 이해)가 부족하며, 영향은 기업 디자인 영역에 집중될 것이라는 관점이다.

초급16. 결정 매트릭스: 언제 Claude Design을 쓰고, 언제 쓰지 않는가

상황	1순위 선택	근거
아이디어에서 첫 시안까지 1시간 내	Claude Design	Anthropic이 지정한 핵심 사용 맥락
사내 디자인 시스템을 적용한 랜딩/원페이저	Claude Design	코드/디자인 파일 기반 자동 적용
디자인 → 실제 구현으로 바로 연결	Claude Design → Claude Code 핸드오프	공식 핸드오프 번들 지원
팀 2명 이상이 같은 캔버스 실시간 공동 편집	Figma	Claude Design 멀티플레이어 미지원
소셜 카드·마케팅 템플릿 대량 제작	Canva (+ Send to Canva로 연결)	공식 Canva 연결 파이프라인
배포까지 포함한 웹 앱 빠른 출시	Lovable	Lovable은 배포 단계 포함, Claude Design은 배포 전 단계
React/Next.js 컴포넌트로 직접 뽑는 목업	v0 또는 Claude Design → Claude Code	v0는 React 스택 전용, Claude Design은 다양한 스택으로 핸드오프 가능
Pro 한도로 상시 업무 목업 생산	Max 5x 이상으로 상향	Pro는 "Quick explorations" 정의, Max 5x/20x 권장

초급17. 결론

Claude Design은 2026-04-19 시점 Anthropic Labs의 research preview다. 핵심 기능을 정리하면 다음과 같다.

디자인 시스템: GitHub 리포·브랜드 PDF 등에서 컬러·타이포그래피·컴포넌트를 자동 추출. 조직 전체 프로젝트에 Published 토글 한 번으로 자동 상속.
3가지 인터랙션 모드: Edit(직접 클릭), Comment(선택+자연어), Draw(스케치 주석)로 캔버스와 상호작용.
Adjustment Knobs: Claude가 해당 디자인에 맞게 생성해주는 spacing/color/layout 실시간 조정 컨트롤.
6가지 Export: .zip·PDF·PPTX·Canva·Standalone HTML·Claude Code 핸드오프.
Claude Code 핸드오프: export → 커맨드 복사 → Claude Code에 붙여넣기 → API fetch 방식으로 구현 단계로 직접 연결.
사용량: 채팅과 완전히 분리된 별도 주간 한도. Pro는 30분 내 소진 사례 다수.

도입 플레이북:

오늘: Pro 계정으로 claude.ai/design 접속 → "랜딩 페이지 1섹션 + Standalone HTML export" 15분 안에 1회 실행. 일회성 크레딧 범위 내 소비량 직접 측정.
이번 주: Organization settings에서 팀 디자인 시스템(레포 또는 브랜드 PDF) 등록 → Published 토글 ON → 새 프로젝트에서 자동 반영 여부 확인.
운영 반영: Pro 소비 패턴을 확인한 후 Max 5x/20x 승격 여부 결정. Enterprise는 관리자 활성화 정책과 공유 권한 3단 설정을 먼저 문서화.

도입 전 자기 검증 체크리스트

팀에 실시간 공동 편집이 필수인가? 필수라면 Figma 병행 권장.
Enterprise 관리자가 Organization settings에서 Claude Design을 활성화했는가?
디자인 시스템을 업로드했는가? Published 토글이 켜져 있는가?
Pro로 시작한다면 주간 소비 패턴을 먼저 측정했는가?
초기 출력물의 가독성(색상 대비)을 사람이 직접 검수하는 프로세스가 있는가?

한 줄로 종합하면: Claude Design은 Figma를 대체하지 않는다. 아이디어에서 구현 사이의 중간 단계를 짧게 줄이는 도구다. 커뮤니티 전반의 "균질화" 우려를 감안할 때, 도구 출력을 그대로 받지 않고 디자인 차별화는 사람이 붙이는 프로세스를 팀 내에 함께 두는 것이 안전하다.

참고 자료

공식 문서 (Level 1 — 직접 확인)

커뮤니티·미디어 (Level 2-3 — 직접 읽어 확인)

DESIGN.md : Google Stitch가 도입한 DESIGN.md - DESIGN.md 도입 배경부터 적용해보기(VoltAgent awesome-design-md 컬렉션 활용 가이드)

갓대희 — Thu, 23 Apr 2026 01:25:10 +0900

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

AI 코딩 에이전트에게 "Stripe 스타일로 만들어줘"라고 지시해본 적이 있는데 매번 결과물이 들쭉날쭉하다면, 그 원인은 에이전트가 디자인 의도를 읽을 공통 언어가 없기 때문이다.

Google Stitch는 이 문제를 해결하기 위해 DESIGN.md라는 개념을 도입했다.

마크다운 파일 한 장으로 컬러 팔레트부터 타이포그래피, 컴포넌트 스타일까지 명시해두면, AI 에이전트가 코드를 생성할 때마다 이 파일을 먼저 읽어 일관된 외관을 유지한다.

DESIGN.md란 무엇인가 — README.md와 무엇이 다른가
왜 DESIGN.md가 필요한가 — AI UI의 랜덤성 문제
DESIGN.md 포맷 상세 — 9개 섹션 구조
awesome-design-md 레포지토리 소개
DESIGN.md 접근 방법 — getdesign.md 서비스
주요 컬렉션 예시 분석 — Stripe, Vercel, Linear
실전 활용법 — 프로젝트에 적용하기
기술 아키텍처 분석 — DESIGN.md가 LLM에 최적화된 이유
제한사항 및 주의사항
결론 — LLM 시대 디자인 시스템 표준화 방향

이 글의 핵심

DESIGN.md는 Google Stitch가 도입한 AI 에이전트용 플레인텍스트 디자인 시스템 문서다
9개 섹션으로 컬러·타이포·컴포넌트·레이아웃·프롬프트 가이드를 명세한다
VoltAgent의 awesome-design-md 컬렉션에 69개 브랜드 DESIGN.md가 MIT 라이선스로 제공된다 (getdesign.md 서비스 통해 배포)
공개 CSS 추출 기반이므로 공식 디자인 토큰과 동일하다고 보장되지 않는다

1. DESIGN.md란 무엇인가 — README.md와 무엇이 다른가

1.1 개념 정의

DESIGN.md는 Google Stitch가 도입한 새로운 개념으로, AI 에이전트가 일관된 UI를 생성하기 위해 읽는 플레인텍스트 디자인 시스템 문서다. awesome-design-md README는 이를 다음과 같이 정의한다.

"DESIGN.md is a new concept introduced by Google Stitch. A plain-text design system document that AI agents read to generate consistent UI."
(DESIGN.md는 Google Stitch에서 도입한 새로운 개념으로, AI 에이전트가 이를 읽어 일관된 사용자 인터페이스(UI)를 생성할 수 있도록 만든 순수 텍스트 기반의 디자인 시스템 문서입니다.)

핵심은 단순함이다 — Figma 익스포트도, JSON 스키마도, 특수 툴링도 필요 없다. 마크다운 파일 한 장을 프로젝트 루트에 넣으면, AI 코딩 에이전트나 Google Stitch가 즉시 UI 외관을 이해할 수 있다.

"Markdown is the format LLMs read best, so there's nothing to parse or configure"

(Markdown은 LLM(Large Language Model)이 가장 잘 읽고 이해할 수 있는 포맷이므로, 추가적인 파싱 과정이나 별도의 설정 없이 바로 사용할 수 있습니다.)라는 것이 채택 근거이다.

1.2 파일 역할 분리 — AGENTS.md vs DESIGN.md

프로젝트에는 이미 README.md와 AGENTS.md가 있다. DESIGN.md는 이 체계에 세 번째 레이어를 추가한다.

awesome-design-md README가 제시한 역할 비교표는 다음과 같다.

파일	누가 읽는가	무엇을 정의하는가
`AGENTS.md`	코딩 에이전트	프로젝트 빌드 방법
`DESIGN.md`	디자인 에이전트	프로젝트의 외관과 느낌

출처: awesome-design-md README

한 줄로 요약하면: AGENTS.md가 "어떻게 만드는가"를 정의한다면, DESIGN.md는 "어떻게 보여야 하는가"를 정의한다.

2. 왜 DESIGN.md가 필요한가 — AI UI의 랜덤성 문제

AI 코딩 에이전트에게 UI 컴포넌트 생성을 요청할 때, 에이전트가 참조할 디자인 명세가 없으면 출력이 매번 달라진다. 컬러, 폰트, 여백, 그림자 — 모든 요소가 에이전트의 추측에 맡겨진다.

DESIGN.md는 이 문제를 텍스트 명세(specification)로 해결한다. awesome-design-md README가 직접 명시하듯, DESIGN.md를 프로젝트 루트에 두면 "AI 코딩 에이전트나 Google Stitch가 즉시 UI 외관을 이해"한다. 에이전트가 파일을 컨텍스트로 읽고 디자인 결정을 따르므로, 임의의 추측이 개입할 여지가 줄어든다.

stitch-skills의 공식 design-md 스킬은 이를 한 단계 더 구체화한다. DESIGN.md 파일이 "기존 디자인 언어와 완벽하게 일치하는 새 화면을 생성하도록 프롬프팅하는 단일 진실의 원천(source of truth)"이 된다는 것이 스킬의 공식 목표로 보인다.

3. DESIGN.md 포맷 상세 — 9개 섹션 구조

3.1 섹션 구조 — awesome-design-md 기준 9개 섹션

VoltAgent의 awesome-design-md README가 정의하는 DESIGN.md 포맷은 9개 섹션으로 구성된다. 아래는 README 원문에서 직접 인용한 전체 목록이다.

#	섹션명	담는 내용
1	Visual Theme & Atmosphere	분위기, 밀도, 디자인 철학
2	Color Palette & Roles	시맨틱 이름 + hex + 기능적 역할
3	Typography Rules	폰트 패밀리, 전체 계층 표
4	Component Stylings	버튼, 카드, 입력, 네비게이션(상태 포함)
5	Layout Principles	간격 스케일, 그리드, 여백 철학
6	Depth & Elevation	그림자 시스템, 표면 계층
7	Do's and Don'ts	디자인 가드레일과 안티패턴
8	Responsive Behavior	브레이크포인트, 터치 타겟, 접기 전략
9	Agent Prompt Guide	빠른 컬러 레퍼런스, 즉시 사용 가능한 프롬프트

출처: awesome-design-md README

위 9개 섹션은 VoltAgent의 awesome-design-md 컬렉션이 정의한 확장 구조다.

Google Stitch 공식 design-md SKILL.md의 Output Format에는 1~5번 섹션(Visual Theme & Atmosphere ~ Layout Principles)만 명시되어 있다. 6번(Depth & Elevation)부터 9번(Agent Prompt Guide)은 VoltAgent가 실제 컬렉션 파일 분석을 통해 추가한 항목이다.

9개 전체를 Google 공식 포맷과 동일시하지 않도록 주의가 필요하다.

3.2 섹션 9 — Agent Prompt Guide의 역할

9번 섹션 "Agent Prompt Guide"가 이 포맷의 핵심이다. 단순한 토큰 명세를 넘어, AI에게 즉시 전달할 수 있는 프롬프트 예시를 직접 포함한다. Stripe DESIGN.md의 Agent Prompt Guide는 Quick Color Reference와 컴포넌트별 예시 프롬프트를 담고 있다.

예를 들어:

"Create a hero section on white background. Headline at 48px sohne-var weight 300, line-height 1.15, letter-spacing -0.96px, color #061b31..."
(화이트 배경의 히어로 섹션을 구성합니다. 헤드라인은 sohne-var 폰트를 사용하고, weight 300, 크기 48px, line-height 1.15, letter-spacing -0.96px, 색상은 #061b31로 설정합니다...)

결국 DESIGN.md는 사람이 읽는 스타일 가이드가 아니라, AI가 직접 소비하는 프롬프트 라이브러리다.

4. awesome-design-md 레포지토리 소개

4.1 레포지토리 개요

awesome-design-md는 VoltAgent가 관리하는 큐레이션 컬렉션으로, MIT 라이선스로 배포된다.

4.2 9개 카테고리 구성

컬렉션은 현재 9개 카테고리 총 69개 브랜드로 구성된다. 아래는 README 원문 직접 확인 기준이다 (2026-04-22).

카테고리	포함 브랜드	수
AI & LLM Platforms	Claude, Cohere, ElevenLabs, Minimax, Mistral AI, Ollama, OpenCode AI, Replicate, RunwayML, Together AI, VoltAgent, xAI	12
Developer Tools & IDEs	Cursor, Expo, Lovable, Raycast, Superhuman, Vercel, Warp	7
Backend, Database & DevOps	ClickHouse, Composio, HashiCorp, MongoDB, PostHog, Sanity, Sentry, Supabase	8
Productivity & SaaS	Cal.com, Intercom, Linear, Mintlify, Notion, Resend, Zapier	7
Design & Creative Tools	Airtable, Clay, Figma, Framer, Miro, Webflow	6
Fintech & Crypto	Binance, Coinbase, Kraken, Mastercard, Revolut, Stripe, Wise	7
E-commerce & Retail	Airbnb, Meta, Nike, Shopify, Starbucks	5
Media & Consumer Tech	Apple, IBM, NVIDIA, Pinterest, PlayStation, SpaceX, Spotify, The Verge, Uber, Vodafone, WIRED	11
Automotive	BMW, Bugatti, Ferrari, Lamborghini, Renault, Tesla	6

출처: awesome-design-md README 원문

5. DESIGN.md 접근 방법 — getdesign.md 서비스

5.1 현재 폴더 구조

현재 GitHub 레포지토리의 각 브랜드 폴더는 GitHub API 직접 조회 기준 README.md 1개만 포함한다. DESIGN.md 본문은 외부 서비스 getdesign.md로 이전되었다.

design-md/stripe/
└── README.md  (113 bytes)
    → "Design system details have been moved to: https://getdesign.md/stripe/design-md"

stripe, vercel, linear.app, supabase 등 모든 브랜드 폴더가 동일한 구조다. DESIGN.md 본문, 라이트/다크 프리뷰는 getdesign.md 웹 서비스에서 제공된다.

5.2 getdesign.md 서비스

각 브랜드의 DESIGN.md는 https://getdesign.md/{브랜드명}/design-md 패턴의 URL로 접근한다.

예: getdesign.md/stripe/design-md. 웹 UI에서 열람하거나, 아래 CLI로 프로젝트에 바로 설치할 수 있다.

6. 주요 컬렉션 예시 분석 — Stripe, Vercel, Linear

6.1 Stripe — 핀테크 디자인의 기준

Stripe DESIGN.md의 Visual Theme 섹션은 커스텀 sohne-var 가변 폰트를 중심으로 서술된다. 원문에서 직접 인용하면:

"The custom sohne-var variable font is the defining element of Stripe's visual identity. Every text element enables the OpenType "ss01" stylistic set... At display sizes (48px-56px), sohne-var runs at weight 300 — an extraordinarily light weight for headlines"
(커스텀 sohne-var variable font는 Stripe의 비주얼 아이덴티티를 규정하는 핵심 요소입니다. 모든 텍스트 요소에는 OpenType의 'ss01' 스타일 세트가 적용되며, 디스플레이 크기(48px~56px) 구간에서는 sohne-var를 weight 300으로 사용합니다. 이는 헤드라인 기준으로 매우 가벼운 두께에 해당합니다.)

헤드라인에 weight 300을 사용한다는 점이 핵심이다. 대부분의 웹사이트가 헤드라인에 굵은 폰트를 쓰는 반면, Stripe는 극단적으로 얇은 웨이트로 고급스러움을 표현한다.

Depth & Elevation 섹션에서 Stripe의 그림자 시스템을 확인할 수 있다:

"Rather than the flat or single-layer approach of most sites, Stripe uses multi-layer, blue-tinted shadows: the signature rgba(50,50,93,0.25) combined with rgba(0,0,0,0.1) creates shadows with a cool, almost atmospheric depth"
("일반적인 웹사이트의 단일 레이어 또는 평면적인 그림자 처리와 달리, Stripe는 블루 계열이 반영된 멀티 레이어 그림자 방식을 사용합니다. rgba(50,50,93,0.25)와 rgba(0,0,0,0.1)의 조합을 통해, 차분하면서도 공기감 있는 깊이감을 표현하는 것이 특징입니다.")

대부분의 사이트가 단일 레이어 그림자를 쓰는 것과 달리, Stripe는 블루 틴트 멀티레이어 그림자로 "대기적 깊이감(atmospheric depth)"을 만든다. 이런 결정이 DESIGN.md에 명시되어 있어야 AI가 재현할 수 있다.

6.2 Vercel — "shadow-as-border" 기법

Vercel DESIGN.md에서 가장 흥미로운 부분은 CSS border를 대체하는 shadow 기법이다:

"Instead of traditional CSS borders, Vercel uses box-shadow: 0px 0px 0px 1px rgba(0,0,0,0.08) — a zero-offset, zero-blur, 1px-spread shadow that creates a border-like line without the box model implications."
(기존의 CSS border를 사용하는 대신, Vercel은 box-shadow(0px 0px 0px 1px rgba(0,0,0,0.08))를 활용합니다. offset과 blur를 0으로 두고 spread만 1px 적용해, 레이아웃(box model)에 영향을 주지 않으면서도 테두리처럼 보이는 라인을 구현하는 방식입니다.)

offset 0, blur 0, spread 1px의 box-shadow로 CSS border를 대체한다. 박스 모델에 영향을 주지 않으면서 경계선을 표현하는 이 기법은, Geist 커스텀 폰트와 극단적 음수 자간(-2.4px~-2.88px)과 함께 Vercel 특유의 미니멀 UI를 구성한다.

6.3 Linear — 다크모드 네이티브 설계

Linear DESIGN.md는 다크모드 퍼스트 설계의 교과서다:

"Linear's website is a masterclass in dark-mode-first product design... Inter Variable with "cv01", "ss03" globally... Signature weight 510 (between regular and medium) for most UI text... Brand indigo-violet: #5e6ad2 (bg) / #7170ff (accent) / #828fff (hover) — the only chromatic color in the system"
("Linear 웹사이트는 다크 모드 중심 제품 디자인의 대표적인 사례입니다. Inter Variable 폰트를 전역적으로 적용하고, 'cv01', 'ss03' 스타일 옵션을 활성화합니다. UI 텍스트 대부분에는 regular와 medium 사이의 중간 두께인 weight 510을 사용하며, 브랜드 컬러는 인디고-바이올렛 계열(#5e6ad2: 배경 / #7170ff: 강조 / #828fff: hover)로 구성되어 있으며, 시스템 내에서 사실상 유일한 컬러 포인트로 활용됩니다.")

배경 #08090a(퓨어 블랙에 가깝지만 완전한 블랙은 아님)에 단 하나의 유채색 계열(인디고-바이올렛)만 사용한다. "시스템에서 유일한 유채색"이라는 명시적 제약이 DESIGN.md에 담겨 있어야 AI가 임의로 다른 색상을 추가하지 않는다.

세 사이트 모두 디자인의 독특한 결정(Stripe의 얇은 헤드라인, Vercel의 shadow-as-border, Linear의 단색 크로마)은 구두 설명 없이는 재현이 어렵다. DESIGN.md는 이런 암묵적 지식을 명문화하는 역할을 한다.

7. 활용법 — 프로젝트에 적용하기

7.1 Step 1 — DESIGN.md 다운로드 및 프로젝트 배치

컬렉션에서 원하는 브랜드의 DESIGN.md를 프로젝트 루트에 배치한다. 현재 공식 배포 방식은 getdesign.md 서비스를 통한 CLI 설치다.

Stripe를 예로 들면:

# CLI로 설치 (프로젝트 루트에서 실행)
npx getdesign@latest add stripe

# 다른 브랜드 예시
npx getdesign@latest add vercel
npx getdesign@latest add linear.app

명령어 실행 시 DESIGN.md가 프로젝트 루트에 저장된다. 웹에서 미리 확인하려면 getdesign.md/stripe/design-md 에서 라이트·다크 프리뷰를 포함한 전체 내용을 볼 수 있다.

다운로드 후 프로젝트 루트 구조:

my-project/
├── AGENTS.md       ← 빌드 방법 정의 (선택)
├── DESIGN.md       ← 디자인 외관 정의
├── src/
└── ...

다른 브랜드를 원하면 stripe 자리에 브랜드명을 넣는다. 예: vercel, linear.app, supabase, cursor. 지원 브랜드 전체 목록은 getdesign.md 또는 GitHub 디렉토리에서 확인할 수 있다.

7.2 Step 2 — AI 에이전트에 참조 지시하기

awesome-design-md README는 사용법을 다음과 같이 안내한다:

"Copy a site's DESIGN.md into your project root. Tell your AI agent to use it."
(사용하려는 사이트의 DESIGN.md 파일을 프로젝트 루트 디렉토리에 복사하고, AI 에이전트가 해당 파일을 참조하도록 안내합니다.)

핵심은 에이전트에게 DESIGN.md를 읽도록 명시적으로 지시하는 것이다.

상황별 프롬프트 예시:

상황	프롬프트 예시
컴포넌트 생성	`DESIGN.md를 먼저 읽고, 이 디자인 시스템에 맞는 가격표(pricing table) 컴포넌트를 React로 만들어줘.`
페이지 생성	`DESIGN.md의 Color Palette, Typography, Component Stylings 섹션을 참조해서 랜딩 페이지 히어로 섹션을 만들어줘.`
기존 코드 수정	`현재 버튼 컴포넌트의 스타일을 DESIGN.md의 Component Stylings 섹션에 정의된 값으로 맞춰줘.`
전체 프로젝트 스타일 통일	`DESIGN.md를 읽고, src/components/ 내 모든 컴포넌트의 컬러와 폰트를 DESIGN.md 기준으로 일괄 수정해줘.`

7.3 Step 3 — 자체 프로젝트용 DESIGN.md 작성하기

컬렉션에 원하는 사이트가 없거나, 자체 디자인 시스템을 명세해야 할 경우 직접 작성할 수 있다.

awesome-design-md README에서 정의한 9개 섹션을 스켈레톤으로 사용한다:

# My Project — DESIGN.md

## 1. Visual Theme & Atmosphere
<!-- 분위기, 밀도, 디자인 철학 -->

## 2. Color Palette & Roles
<!-- 시맨틱 이름 + hex 값 + 기능적 역할 -->

## 3. Typography Rules
<!-- 폰트 패밀리, 크기/굵기 계층 표 -->

## 4. Component Stylings
<!-- 버튼, 카드, 입력, 네비게이션 (상태별 스타일 포함) -->

## 5. Layout Principles
<!-- 간격 스케일, 그리드, 여백 철학 -->

## 6. Depth & Elevation
<!-- 그림자 시스템, 표면 계층 -->

## 7. Do's and Don'ts
<!-- 디자인 가드레일, 안티패턴 -->

## 8. Responsive Behavior
<!-- 브레이크포인트, 터치 타겟, 접기 전략 -->

## 9. Agent Prompt Guide
<!-- 빠른 컬러 레퍼런스, 즉시 사용 가능한 프롬프트 예시 -->

각 섹션에 실제로 무엇을 쓰는지, Stripe DESIGN.md 원문의 섹션 2(Color Palette & Roles)를 예로 보자:

## 2. Color Palette & Roles

**Primary:** Stripe Purple (`#533afd`), Deep Navy (`#061b31`), Pure White (`#ffffff`)
**Accents:** Ruby (`#ea2261`), Magenta (`#f96bee`)
**Interactive:** Purple Hover (`#4434d4`), Purple Deep (`#2e2b8c`)
**Neutrals:** Heading (`#061b31`), Body (`#64748d`)
**Surfaces:** Border Default (`#e5edf5`), Border Purple (`#b9b9f9`)
**Shadows:** Shadow Blue (`rgba(50,50,93,0.25)`), Shadow Black (`rgba(0,0,0,0.1)`)

출처: Stripe DESIGN.md 원문

작성 핵심 원칙:

구체적 값 — #533afd처럼 hex/rgba 값을 명시한다. "파란색 계열"같은 모호한 표현은 AI가 임의로 해석한다.
시맨틱 이름 — Primary, Accent, Interactive 등 역할별로 분리하면 AI가 용도에 맞는 색상을 선택할 수 있다.
상태 포함 — 버튼이라면 기본·호버·클릭·비활성 상태 각각의 스타일을 명시한다.
섹션 9 활용 — Agent Prompt Guide에 에이전트가 바로 복사해서 쓸 수 있는 프롬프트 조각을 넣으면 효과적이다.

7.4 Google Stitch 연동 — stitch-skills

google-labs-code/stitch-skills는 Stitch MCP 서버와 연동하는 에이전트 스킬 라이브러리다.

이 레포지토리는 design-md 스킬을 공식으로 포함한다. 스킬 파일 상단에 명시된 허용 도구 목록은 다음과 같다:

name: design-md
description: Analyze Stitch projects and synthesize a semantic design system into DESIGN.md files
allowed-tools:
  - "stitch*:*"
  - "Read"
  - "Write"
  - "web_fetch"

이 스킬의 목표는 DESIGN.md 파일이 Stitch가 기존 디자인 언어와 일치하는 새 화면을 생성하도록 프롬프팅하는 "단일 진실의 원천(source of truth)"이 되는 것이다:

"The DESIGN.md file will serve as the 'source of truth' for prompting Stitch to generate new screens that align perfectly with the existing design language."
(DESIGN.md 파일은 Stitch가 기존 디자인 언어와 정확하게 일관된 새로운 화면을 생성할 수 있도록 프롬프트의 기준이 되는 ‘source of truth(신뢰 가능한 단일 기준)’로 활용됩니다.)

설치 및 사용법은 stitch-skills 공식 레포지토리에서 확인할 수 있다. 스킬 파일(SKILL.md) 원문에 따르면, 이 스킬은 Stitch MCP 서버를 통해 프로젝트 화면을 조회하고 HTML/CSS를 분석하여 DESIGN.md를 자동 생성하는 방식으로 동작한다.

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

상황	권장 여부	이유
AI 에이전트로 UI 반복 생성	사용	매번 다른 스타일 출력 문제를 DESIGN.md가 해결한다
기존 사이트와 유사한 스타일 구현	사용	컬렉션에서 골라 복사하면 되므로 즉시 적용 가능
팀 내 AI 기반 프론트엔드 개발 표준화	사용	프로젝트 루트 파일 하나로 팀 전체 AI 출력을 통일할 수 있다
공식 디자인 토큰이 정확히 필요한 경우	주의	컬렉션 파일은 공개 CSS에서 추출한 값이며 공식 토큰과 동일하다고 보장되지 않는다
저작권 민감 프로젝트	확인 필요	MIT 라이선스이나, 해당 사이트의 시각적 아이덴티티 소유권은 별개다

8. 기술 아키텍처 분석 — DESIGN.md가 LLM에 최적화된 이유

mindstudio.ai 블로그는 DESIGN.md를 "디자인 시스템을 위한 시스템 프롬프트(system prompt for your design system)"이자 "머신이 읽을 수 있는 디자인 시스템(machine-readable design system)"으로 설명한다.

Claude Code, Cursor, Gemini CLI 같은 AI 코딩 에이전트가 프로젝트 루트의 DESIGN.md를 컨텍스트로 직접 읽어 디자인 규칙을 반영한다. (출처: mindstudio.ai blog)

DESIGN.md가 마크다운을 채택한 이유는 명확하다:

"Markdown is the format LLMs read best, so there's nothing to parse or configure."
(Markdown은 LLM(Large Language Model)이 가장 잘 읽고 이해할 수 있는 포맷이므로, 추가적인 파싱 과정이나 별도의 설정 없이 바로 사용할 수 있습니다.)

LLM은 구조화된 JSON이나 이진 Figma 파일보다 마크다운을 더 잘 이해한다. Figma 익스포트나 JSON 스키마를 파싱하는 추가 레이어 없이, 에이전트가 파일을 그대로 컨텍스트로 읽을 수 있다.

stitch-skills design-md 스킬은 Stitch MCP 서버를 통해 프로젝트 화면 메타데이터를 조회하고 HTML/CSS를 파싱해 DESIGN.md를 자동 생성하는 방식으로 동작한다. Stitch가 UI를 생성할 때는 Visual Description(구체적 컬러값으로 뒷받침되는 설명)을 통해 디자인을 해석한다.

9. 제한사항 및 주의사항

9.1 공개 CSS 추출 값 — 공식 토큰과의 오차

awesome-design-md의 모든 DESIGN.md 파일은 공개 웹사이트에서 추출된 CSS 값을 기반으로 한다. 레포지토리 자체가 이를 명시한다:

"The extracted design tokens represent publicly visible CSS values. We do not claim ownership of any site's visual identity. These documents exist to help AI agents generate consistent UI."
(본 문서에서 추출된 디자인 토큰은 공개적으로 노출된 CSS 값을 기반으로 하며, 특정 사이트의 시각적 아이덴티티에 대한 소유권을 주장하지 않습니다. 이 문서의 목적은 AI 에이전트가 일관된 UI를 생성할 수 있도록 지원하는 데 있습니다.)

공개 CSS에서 추출한 값이므로, 해당 사이트의 내부 디자인 토큰 시스템과 완전히 동일하다고 볼 수 없다. 브랜드 정확성이 중요한 공식 프로젝트에서는 직접 검증이 필요하다.

9.2 유지보수 주기와 버전 드리프트

레포지토리가 2026년 3월 31일 생성된 신규 프로젝트라는 점을 고려해야 한다. 각 사이트가 디자인을 업데이트하면 DESIGN.md 파일이 구식이 될 수 있다. 커밋 이력을 보면 현재는 빠른 주기로 업데이트되고 있으나, 장기적인 유지보수 주기는 확인할 수 없다.

9.3 저작권 및 라이선스

레포지토리는 MIT 라이선스로 배포되며, 다음 고지가 명시되어 있다:

"MIT License - see LICENSE. This repository is a curated collection of design system documents extracted from public websites. All DESIGN.md files are provided 'as is' without warranty."

추출된 디자인 토큰은 공개 가시 CSS 값을 나타내며, 해당 사이트의 시각적 아이덴티티 소유권을 주장하지 않는다는 점을 레포지토리가 명시한다. 상업적 프로젝트에서 사용 시 해당 브랜드의 가이드라인을 별도로 확인하는 것이 권장된다.

10. 결론 — LLM 시대 디자인 시스템 표준화 방향

도입 플레이북

DESIGN.md는 AI 에이전트 기반 UI 개발에서 발생하는 "디자인 일관성 부재" 문제에 대한 마크다운 레이어 해결책이다. 구조는 단순하지만, 9개 섹션이 담는 정보 밀도는 높다.

오늘: awesome-design-md 레포지토리에서 원하는 브랜드를 골라 npx getdesign@latest add {브랜드명}으로 프로젝트 루트에 DESIGN.md를 설치한다. AI 에이전트에게 UI 컴포넌트 생성을 요청하면서 DESIGN.md를 참조하도록 지시해 결과를 비교한다.

이번 주: Stripe, Vercel, Linear 세 사이트의 DESIGN.md를 읽어보면 디자인 결정의 "왜"가 담겨 있다. 이것을 직접 작성하는 연습을 통해 자체 프로젝트의 DESIGN.md를 만드는 것도 가능하다.

운영 반영: Google Stitch 기반 프로젝트에서는 stitch-skills의 design-md 스킬로 DESIGN.md 자동 생성을 고려한다. Claude Code, Cursor 등 AI 코딩 에이전트 환경에서는 AGENTS.md와 DESIGN.md를 함께 관리하면 에이전트가 "빌드 방법"과 "외관"을 모두 이해한 상태로 작업할 수 있다.

자주 묻는 질문 (FAQ)

Q. DESIGN.md를 직접 작성해야 하는가, 아니면 컬렉션에서 복사해서 써도 되는가?

두 방법 모두 가능하다. 빠르게 시작하고 싶다면 npx getdesign@latest add {브랜드명} CLI로 원하는 사이트의 DESIGN.md를 프로젝트 루트에 바로 설치할 수 있다(awesome-design-md에서 브랜드 목록 확인). 설치 후 필요에 맞게 수정하면 된다. Google Stitch 환경에서는 stitch-skills design-md 스킬로 기존 프로젝트에서 자동 생성할 수도 있다.

Q. awesome-design-md의 파일이 해당 사이트의 공식 디자인 토큰과 동일한가?

동일하다고 보장되지 않는다. 레포지토리가 명시하듯, 모든 DESIGN.md 파일은 공개 웹사이트에서 추출된 CSS 값 기반이다. 브랜드 정확성이 중요한 공식 프로젝트에서는 직접 검증이 필요하다.

Q. AGENTS.md가 이미 있는 프로젝트에 DESIGN.md를 추가해야 하는가?

역할이 다르므로 함께 관리하는 것이 권장된다. AGENTS.md가 "어떻게 만드는가"를 정의한다면, DESIGN.md는 "어떻게 보여야 하는가"를 정의한다. 두 파일을 프로젝트 루트에 함께 두면 AI 에이전트가 빌드 방법과 외관을 모두 파악한 상태로 작업할 수 있다.

현시점의 한계와 전망

컬렉션 파일이 공개 CSS 추출 기반이라는 한계, 유지보수 주기의 불확실성, 사이트 업데이트 시 드리프트 가능성은 실제 운영에서 고려해야 할 요소다. 레포지토리 자체도 2026년 3월 31일 생성된 신규 프로젝트이므로, 장기 안정성은 지켜볼 필요가 있다.

그럼에도 이 개념이 주목받는 이유는 명확하다 — AI가 코드를 생성하는 시대에, 코드 규칙(AGENTS.md)과 디자인 규칙(DESIGN.md)을 텍스트 파일로 명시해두는 방향은 자연스러운 표준화 경로다. DESIGN.md가 AGENTS.md처럼 많은 프로젝트의 루트 파일로 자리잡는 것은 시간 문제일 수 있다.

Google Stitch는 이 개념을 공식적으로 "Vibe Design"으로 명명하고 있다. Google Labs 공식 블로그에서 "Introducing 'vibe design' with Stitch" 제목으로 2026년 3월 발표되었다.

(출처: Google Blog — Introducing vibe design with Stitch)

참고자료

Google Stitch 공식 DESIGN.md 문서 — stitch.withgoogle.com
Google Blog — Introducing vibe design with Stitch — Google Labs, 2026-03
awesome-design-md README — VoltAgent, 2026
VoltAgent/awesome-design-md — GitHub 레포지토리
GitHub API: stripe 폴더 구조
GitHub API: linear.app 폴더 구조
Stripe DESIGN.md 원문
Vercel DESIGN.md 원문
Linear DESIGN.md 원문
google-labs-code/stitch-skills — GitHub 레포지토리
stitch-skills design-md SKILL.md 원문
awesome-design-md 커밋 이력
awesome-design-md Open Issues