펫의 에이전트 상태 3가지는 무엇인가?

Running(작업 중 애니메이션 + 메시지 버블), Waiting for input(빨간 시계 + 승인 대기), Ready for review(초록 체크 + 리뷰 대기) 3가지입니다.

나만의 커스텀 펫을 만들려면?

Codex 입력창에 /hatch 명령을 실행하면 이미지 업로드 또는 텍스트 묘사로 AI가 약 30분 안에 픽셀 아트 애니메이션 펫을 생성합니다.

커뮤니티 펫은 어디서 찾을 수 있나?

codex-pets.net에서 약 2,000개의 커뮤니티 펫을 탐색할 수 있습니다. 설치는 npx codex-pets add 한 줄로 가능합니다.

Free 플랜에서도 Codex 모바일을 쓸 수 있나?

현재 프리뷰 기간에는 Free 플랜도 지원 지역에서 모바일 접근이 가능하다. 다만 Codex 에이전트 기능 한도는 플랜별로 다르며, Free 플랜은 Codex 에이전트 자체를 포함하지 않는다.

명령어는 antigravity인가 agy인가?

터미널에서 실행하는 명령은 agy다. antigravity가 아니다. agy --help로 전체 옵션을 확인할 수 있다.

갓대희의 작은공간

Orca 사용 방법(Orca 설치 및 사용법) : Codex, Claude Code, Grok을 Git Worktree로 동시에 실행하기

갓대희 — Tue, 14 Jul 2026 18:00:33 +0900

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

이번 포스팅은 [ Orca 초보자 설치 및 AI 코딩 에이전트 활용 가이드 ] 입니다. : )

AI 코딩 도구를 여러 개 쓰면 터미널 창부터 늘어난다. 한쪽에는 Codex, 다른 쪽에는 Claude Code를 띄우고 작업별 브랜치와 개발 서버까지 따로 챙기다 보면 코드를 고치는 시간보다 창을 찾는 시간이 더 길어질 때도 있다.

이런 창 관리 문제를 한 화면에 모은 도구가 Orca다. 이름 때문에 새 AI 모델로 오해하기 쉽지만 실제로는 IDE다.

Orca는 AI 모델이 아니다.

이미 사용 중인 Codex, Claude Code, Grok 같은 AI 코딩 도구를 작업 공간별로 나눠 실행하고 결과를 비교하는 IDE다.

이번 글에서는 개념과 가격 구조를 짚고 macOS에 설치한 다음, 온보딩 체크리스트부터 저장소 추가·첫 요청·Diff 검토·local commit까지 따라가 본다.

핵심 5가지

Orca는 모델이 아니라 여러 AI 코딩 CLI를 한곳에서 다루는 데스크톱 IDE다.
작업마다 별도 작업 공간(worktree)을 만들어 파일이 섞이지 않게 한다.
Orca 앱은 MIT 라이선스지만 연결하는 에이전트의 구독료와 API 비용은 별도다.
macOS는 Homebrew 한 줄로 설치하고 Windows와 Linux용 설치 파일도 제공한다.
첫 실습은 worktree 하나에서 읽기 전용 요청으로 연결을 확인한 뒤 작은 수정·Diff·테스트·local commit까지 진행한다.

Orca가 왜 화제인가?
Orca와 worktree 쉽게 이해하기
코딩 성능·가격·비슷한 도구 가볍게 보기
설치 전에 준비할 것
macOS에 Orca 설치하기
설치 후 온보딩: 체크리스트와 저장소 추가
첫 작업: 요청, 상태 확인, Diff, commit
개발에서는 어떻게 활용할까?
주의사항과 트러블슈팅
마무리와 참고자료

1. Orca가 왜 화제인가?

Orca 공식 문서는 제품을 “여러 AI 코딩 에이전트를 나란히 실행하는 데스크톱 IDE”라고 소개한다.

작업마다 Git worktree, 에이전트 터미널, 브라우저 탭이 한 묶음으로 생긴다.

AI 코딩 CLI를 한 개만 쓸 때는 터미널 하나면 충분하다.

같은 버그를 두 에이전트에 맡기면 브랜치와 폴더부터 늘어난다. Orca는 이 준비 작업을 화면 안에서 처리한다.

2026년 7월 14일 KST에 GitHub API를 다시 확인했을 때 저장소는 18,159 stars와 1,436 forks였고 최신 안정판은 v1.4.138이었다.

별 개수는 성능 점수가 아니다

GitHub 수치는 현재 관심도의 스냅샷이다. 연결한 에이전트의 실제 성능은 내 저장소에서 따로 확인해야 한다.

2. Orca와 worktree 쉽게 이해하기

처음에는 용어가 가장 헷갈린다.

Orca에서는 이미 쓰고 있는 CLI 에이전트를 실행한다.

구분	하는 일	예시	Orca와의 관계
AI 모델	코드를 이해하고 답을 생성	GPT, Claude, Grok	Orca가 직접 제공하는 모델이 아님
CLI 에이전트	프로젝트를 읽고 명령 실행·파일 수정	Codex, Claude Code, Grok	Orca 안에서 실행하는 실제 작업자
Orca	여러 작업과 에이전트 화면을 정리	데스크톱 IDE	지휘실에 가까움
Git worktree	같은 프로젝트에 작업별 폴더를 추가	작업 A 폴더, 작업 B 폴더	에이전트끼리 같은 파일을 덮어쓰지 않게 도움

핵심은 Orca가 모델이나 에이전트가 아니라, 프로젝트와 작업별 worktree 안에서 여러 에이전트를 실행·검토하는 관리 화면이라는 점이다.

Supported agents 문서에는 2026년 7월 13일 현재 30개가 넘는 에이전트가 등록돼 있다. Orca를 열기 전에 사용할 에이전트가 일반 터미널에서 실행되고 로그인돼 있는지만 확인하면 된다.

2.1 화면 구조는 이렇게 보면 쉽다

Orca 화면은 프로젝트 → 작업 공간(worktree) → 탭 순서로 보면 쉽다.

프로젝트를 연 뒤 할 일마다 작업 공간을 만든다. 각 작업 공간 안에서 AI 에이전트와 브라우저를 사용한다.

프로젝트 = Git 저장소 또는 관련 저장소 묶음

↳ worktree = 작업 하나를 위한 별도 폴더

↳ 탭 = 에이전트, 터미널, 브라우저, 편집기

왼쪽에서 다른 worktree를 누르면 해당 작업에 연결된 파일과 터미널이 열린다. 자세한 구조는 공식 Worktrees 문서에서 확인할 수 있다.

2.2 worktree는 작업 공간을 따로 만드는 방식이다

하나의 프로젝트에서 로그인 기능과 버그 수정을 동시에 진행한다고 해보자. 같은 폴더에서 두 작업을 하면 파일이 섞일 수 있다. worktree는 작업마다 별도 폴더를 만들어 이를 줄여준다.

worktree는 저장소 기록을 함께 쓰면서 작업 파일은 폴더별로 나눈다. Orca에서는 저장소 옆의 + 버튼으로 만들 수 있다.

작업이 끝나면 변경 내용을 비교해 마음에 드는 결과만 원본 프로젝트에 반영한다.

터미널에서 만든 worktree도 Orca가 감지하면 알림에서 가져올 수 있다.

3. 코딩 성능·가격·비슷한 도구 가볍게 보기

3.1 Orca의 코딩 성능 점수는 따로 없다

Orca는 Codex처럼 직접 코드를 만드는 AI가 아니다. 결과 품질은 연결한 AI 에이전트와 모델, 요청 내용, 프로젝트 상태에 따라 달라진다.

Orca의 장점은 같은 작업을 여러 작업 공간에 나눠 맡기고 변경 내용(Diff)을 나란히 비교할 수 있다는 점이다.

3.2 Orca 앱은 무료지만 AI 사용료는 0원이 아니다

Orca Terms와 공식 저장소를 보면 앱은 MIT 라이선스다. 다만 Orca 안에서 실행하는 Codex, Claude Code, Grok 등의 구독이나 API 비용은 각 공급자 조건을 따른다.

에이전트를 세 개 병렬로 돌리면 세 작업이 각각 사용량을 만들 수 있다. Orca 사용료와 모델 사용료는 별도다.

3.3 무엇을 먼저 쓰면 될까?

방식	장점	먼저 맞는 상황
CLI 에이전트 하나	설정이 단순하고 터미널만 있으면 됨	AI 코딩을 이제 막 시작할 때
Orca	여러 작업 공간과 AI 결과를 한 화면에서 관리	병렬 작업과 결과 비교가 잦을 때
일반 AI 코드 편집기	편집기 안에서 코드 작성과 AI 기능을 바로 사용	하나의 편집기 경험이 더 중요할 때

정리하면: AI 코딩 도구 하나가 아직 낯설다면 그 도구부터 익히는 편이 낫다. 여러 작업을 동시에 진행해 창과 폴더 관리가 번거로워질 때 Orca가 도움이 된다.

4. 설치 전에 준비할 것

설치 전에 준비할 것은 세 가지다.

Git이 설치된 컴퓨터: Orca가 작업별 폴더를 만들 때 Git을 사용한다.
로컬 Git 저장소 하나: 첫 실습은 중요한 회사 저장소보다 개인 연습 프로젝트가 편하다.
로그인된 CLI 에이전트 하나: Codex, Claude Code, Grok 등 이미 쓰는 도구면 된다.

터미널에서 Git부터 확인한다.

git --version

Git 버전을 확인했다면 아래 세 명령 가운데 실제로 쓸 에이전트의 명령 하나만 확인한다.

# 아래에서 내가 쓰는 것 하나만 확인
codex --version
claude --version
grok --version

명령이 없거나 로그인 전이라면 Orca를 열기 전에 해당 공급자의 공식 CLI 설치와 인증부터 마친다.

5. macOS에 Orca 설치하기

5.1 Homebrew로 설치

공식 설치 문서의 macOS Homebrew 명령은 다음과 같다.

brew install --cask stablyai/orca/orca

현재 공식 문서는 Homebrew Cask를 안정판이 나올 때마다 자동 갱신되는 정식 설치 경로로 안내한다. 설치가 끝나면 macOS의 응용 프로그램 폴더나 Spotlight에서 Orca를 실행한다.

Homebrew가 막히면 공식 DMG를 사용한다

위 화면처럼 개별 환경에서 경고가 나올 수 있지만 Homebrew 경로 자체가 사용 중단된 것은 아니다. 설치가 실패하면 공식 Install 페이지나 v1.4.138 Releases에서 운영체제에 맞는 설치 파일을 내려받는다.

5.2 직접 설치 파일 다운로드와 첫 실행

공식 설치 페이지(https://www.onorca.dev/docs/install또는 https://www.onorca.dev/download) 또는 GitHub Releases를 방문하여 자신의 CPU에 맞는 .dmg 설치 파일을 내려받는다.

Apple Silicon(M1 이후): orca-macos-arm64.dmg
Intel Mac: orca-macos-x64.dmg

내려받은 .dmg 파일을 열고 Orca를 Applications 폴더로 드래그한다. 공식 문서는 macOS 빌드를 서명·공증된 앱으로 안내하며, 첫 실행 때 macOS 확인 창이 한 번 나타날 수 있다고 설명한다.

실행하면 기본 에이전트를 선택한다. 이 설정은 나중에 Settings → Agents에서 바꿀 수 있다. 여기서는 이미 설치하고 로그인한 Codex를 선택했다.

테마와 알림 설정까지 진행한다. 알림은 에이전트가 작업을 마치거나 입력을 기다릴 때 다른 worktree로 바로 돌아가는 데 유용하다.

설치 뒤 실제 사용 순서는 다음 온보딩 섹션에서 이어 간다.

Gatekeeper를 터미널 명령으로 우회하지 않는다

xattr -cr로 격리 속성을 통째로 지우는 방법은 Orca 공식 설치 절차가 아니다. 앱이 반복해서 손상됐다고 표시되면 먼저 공식 설치 페이지에서 다시 내려받고, 최신 안정판과 운영체제·CPU가 맞는지 확인한다.

5.3 자동 업데이트 확인

Orca는 기본적으로 안정 채널을 자동 업데이트한다. 앱의 Settings → General → Updates에서도 업데이트를 확인할 수 있으며, RC 빌드가 아니라면 공식 Releases의 stable 표시를 기준으로 삼는다.

5.4 Windows와 Linux

Windows와 Linux용 설치 파일도 제공한다. 최신 안정판의 대표 파일 형식은 다음과 같다.

Windows: orca-windows-setup.exe
Linux: x64·ARM64용 AppImage, .deb, .rpm

파일명과 CPU 종류는 릴리스마다 달라질 수 있으므로 Orca 공식 Install 페이지와 최신 stable Releases에서 다시 확인한다.

6. 설치 후 온보딩: 체크리스트와 저장소 추가

첫 실행 때 Orca는 홈 폴더 접근을 요청하고, 기존 ~/.claude·~/.codex·Ghostty 설정이 있으면 가져올지 묻는다. 쓰던 설정이 있을 때만 선택하면 된다.

설정 마법사가 끝나면 빈 화면과 함께 온보딩 체크리스트가 남는다.

내가 설치한 v1.4.137 앱에서는 아래 8개 항목으로 구성돼 있었다.

체크리스트	첫날 우선순위	무엇을 설정하나
Turn on notifications	권장	에이전트 완료·입력 대기 알림
Choose your default agent	필수	새 worktree에서 먼저 열 CLI
Enable Orca CLI	나중	터미널 자동화와 Orca 스킬
Connect integrations	선택	GitHub·Linear·Jira·MCP 연결
Automate workspace setup	프로젝트별	새 worktree 준비 명령 자동 실행
Start work in multiple repos	나중	두 번째 이상 저장소 추가
Multi-task	첫 작업 후	서로 다른 worktree 두 개 병렬 사용
Use Orca's browser	웹 프로젝트라면 권장	worktree별 내장 브라우저와 Design Mode

한 줄로 요약하면: 첫날에는 기본 에이전트·권한·저장소·worktree 하나에 집중하고, CLI·연동·병렬 작업은 첫 작업이 끝난 뒤 켜는 편이 이해하기 쉽다.

6.1 기본 에이전트와 권한부터 정한다

Settings → Agents에서 이미 설치하고 로그인한 CLI를 기본 에이전트로 고른다.

목록에 보여도 실행되지 않으면 Orca 터미널에서 해당 CLI를 직접 실행해 설치와 로그인 상태를 먼저 확인한다.

이미 설치 후 처음 실행할때 다음과 같이 선택 했겠지만, 언제든지 변경 가능하다.

처음에는 Agent Permissions를 Manual로 바꾼다

Supported agents 문서는 새 에이전트를 기본적으로 permission-bypass(Yolo) 인자와 함께 실행한다고 밝히고 있다.

worktree는 작업 중 서로의 파일을 즉시 덮어쓰는 문제를 막지만, 같은 줄을 수정하면 나중에 병합 충돌이 생길 수 있다.

운영체제 권한을 제한하는 보안 샌드박스도 아니다.

Settings → Agents → Agent Permissions에서 Manual을 선택하면 에이전트 자체의 승인 흐름을 유지할 수 있다.

중요한 저장소는 이 상태에서 먼저 익숙해지는 편이 안전하다.

단, 커스텀 실행 인자나 환경 변수를 설정한 에이전트는 전역 Manual 전환 대상에서 제외될 수 있다.

해당 에이전트의 기본 인자에 permission-bypass 플래그가 남아 있지 않은지도 확인한다.

화면에서 작업하는 데 Orca CLI는 필수가 아니다.

나중에 자동화가 필요해지면 Settings → General → Orca CLI에서 등록하고 아래처럼 연결만 확인한다.

일부 CLI 문서에는 예전 메뉴인 Experimental 경로가 남아 있지만 v1.4.137 설정 화면 소스에서는 General에 있다.

command -v orca
orca status --json

6.2 Add Repo로 연습 저장소를 추가한다

빈 화면에서 Add Repo를 누르고 이미 내려받아 둔 로컬 Git 저장소를 선택한다.

Orca는 저장소의 Git 상태를 읽고 기본 branch를 새 worktree의 base ref로 잡는다.

연습 저장소를 추가한 뒤 권한을 Manual로 설정하고 worktree에서 에이전트 하나를 선택한다.

처음에는 회사 운영 저장소보다 변경을 버려도 되는 개인 연습 저장소 하나만 추가한다.

여러 저장소 가져오기, 원격 호스트, GitHub·Linear 연동은 기본 흐름을 익힌 뒤 진행해도 늦지 않다.

ex)

- 프로젝트 추가 : 원격 저장소에서 가져올 수도 있고, 기존 로컬에 있는 저장소를 가져올 수도있다.

6.3 설정 스크립트는 필요한 프로젝트만 추가한다

저장소를 추가하면 왼쪽 아래에 설정 스크립트 추가 카드가 나타날 수 있다.

- 프로젝트에 따라 알아서 자동으로 설정 스크립트를 추가 해준다.

Settings reference의 Repository → Auto-run commands on worktree create에 해당하는 기능이다.

새 worktree마다 의존성 설치가 필요한 프로젝트라면 README와 lockfile을 확인해 실제 사용하는 명령 하나만 넣는다.

# 아래는 예시다. 프로젝트가 실제로 쓰는 명령 하나만 선택한다.
pnpm install
npm ci
yarn install --immutable

에이전트가 의존성 설치 결과를 바로 사용해야 한다면 Repository 설정에서 Wait for setup을 켠다.

이 옵션을 끄면 setup과 에이전트가 동시에 시작될 수 있다.

첫 읽기 실습에서는 비워도 된다

설정 스크립트는 새 worktree에서 자동 실행된다. 배포, 데이터 삭제, 비밀값 출력처럼 되돌리기 어려운 명령은 넣지 않는다. 패키지 설치 명령도 lifecycle script를 실행할 수 있으므로 출처와 lockfile을 신뢰하는 저장소에서만 자동 setup에 넣는다. 저장소의 orca.yaml이 setup 명령을 제안하면 첫 실행 전에 내용을 읽고 신뢰 여부를 결정한다. Orca는 신뢰 확인 창에서 실제 명령을 보여 주고 실행 여부를 묻는다.

6.4 + 버튼으로 첫 worktree를 만든다

저장소 옆의 +를 누르고 다음 순서로 만든다.

작업 이름에 first-orca-test를 입력한다.
Start from은 보통 base ref인 origin/main을 선택한다. 다른 branch나 commit에서 시작해야 할 때만 바꾼다.
기본 에이전트가 미리 선택됐는지 확인한다. 필요하면 다른 CLI나 빈 터미널을 고른다.
Create를 누르고 사이드바의 생성·setup 진행 상태가 끝날 때까지 기다린다.

ex) 저장소를 추가 했으면 좌측 상단의 + 버튼을 눌러 Work Tree 를 생성해보자.

- 에이전트와 함께 협업할 새로운 작업(Task)의 이름을 지정하거나, 기존에 연결된 이슈/PR(Pull Request)에서 작업을 시작하는 단계이다.

- Codex를 선택했더라도 Claude로 변경한다던지 언제든지 에이전트 모델 변경은 가능하다.

- 알아서 코덱스를 실행하는 모습

Worktrees 문서에 따르면 Git fetch와 worktree 생성은 백그라운드에서 진행되며, 실패하면 작업 탭에서 오류와 Retry를 확인할 수 있다. 작업 이름에서 branch 이름이 자동으로 만들어지므로 목적을 알아볼 수 있는 짧은 이름이 좋다.

공식 First session은 여기서 worktree 세 개를 만들지만, 이 글의 첫 실습은 하나로 진행한다.

7. 첫 작업: 요청, 상태 확인, Diff, commit

Orca의 기본 흐름은 저장소 추가 → worktree 생성 → 에이전트 실행 → Diff 검토 → commit·push다.

처음에는 읽기 전용 요청으로 연결을 확인한 뒤, README처럼 영향이 작은 파일 하나만 수정해 전체 흐름을 한 번 끝내 본다.

7.1 파일을 고치기 전에 저장소부터 읽힌다

에이전트 입력창이 보이면 아래 문장을 그대로 보내 본다.

이 저장소가 어떤 프로젝트인지 파일을 수정하지 말고 설명해줘.
실행 방법과 주요 폴더만 간단히 알려줘.

(사실 오르카를 설치하러 오신분들은 이런 기본 CLI 사용방법은 이미 익숙 하실 것 이기 때문에 가볍게 작성하고 넘어간다.)

이 요청으로 Orca가 올바른 저장소와 에이전트에 연결됐는지 확인할 수 있다.

답변은 프로젝트와 선택한 모델에 따라 달라진다.

응답을 받은 뒤 프로젝트 설명이 README와 주요 설정 파일의 내용과 맞는지 확인한다.

파일을 수정하지 말라고 요청했으므로 변경 내용(Diff)이 없어야 한다. 아래 명령으로도 확인할 수 있다.

git status --short

아무 내용도 나오지 않으면 파일 변경이 없는 상태다.

변경 파일이 보이면 바로 commit하지 말고 Diff에서 무엇이 바뀌었는지부터 확인한다.

여기까지 확인했다면 첫 실행 성공

Orca에 로컬 Git 저장소가 보인다.
별도 worktree와 선택한 CLI 에이전트가 열렸다.
프로젝트 설명 응답을 받았다.
의도하지 않은 파일 변경이 없다.

7.2 상태 점으로 에이전트가 멈춘 이유를 구분한다

Agents & sessions 문서는 worktree와 탭의 상태 점을 다음처럼 설명한다.

표시	공식 정의	대응 요령
초록색 점멸	에이전트가 능동적으로 작업 중 (TUI가 non-idle 상태)	다른 worktree를 보거나 기다린다.
노란색	사용자 입력 대기	터미널의 질문·승인 요청을 읽는다.
⚪ 회색	유휴(idle)	응답과 Diff를 검토한다.
점 없음	일반 shell 또는 인식되지 않은 CLI	에이전트 선택 메뉴에서 다시 실행한다.

공식 문서의 영상 참고

Inline agent status on every worktree card — yellow while working, green when done

ex) 나의 작업 중인 상태 참고

- 우클릭 하여 상태값을 직접 변경할수도 있다.

상태 표시의 차이는 단순하다. 초록은 작업 중, 노랑은 입력 대기, 회색은 검토할 때이며 점이 없으면 에이전트 선택 메뉴로 다시 실행한다.

작업이 많아지면 상태 점보다 Agents 피드를 먼저 본다

공식 Notifications 문서에 따르면 working에서 idle로 바뀔 때 시스템 알림·소리·worktree 칩이 갱신된다.

여러 worktree를 동시에 돌렸다면 왼쪽 Agents에서 실행 중·완료·입력 대기 항목을 한 번에 훑는다.

Agents 피드나 상단 종 모양 알림을 누르면 해당 worktree와 pane으로 바로 이동한다.

7.3 첫 수정은 작고 검증 가능한 일로 제한한다

읽기 전용 응답이 맞았다면 연습 저장소의 README처럼 영향이 작은 파일로 다음 요청을 보낸다.

README의 로컬 실행 방법을 실제 설정 파일과 대조해줘.
누락된 필수 단계가 있으면 기존 문체를 유지해 한 문장만 보완해줘.
새 의존성은 추가하지 말고, 바꾼 파일과 검증하지 못한 항목을 마지막에 알려줘.

ex) 소스 변경분도 바로 확인 가능하다.

에이전트가 끝나면 우측 Source Control 또는 worktree의 Diff 화면을 연다.

공식 Diff viewer는 시작 ref와 비교해 staged·unstaged·untracked 변경을 한 화면에 보여 준다.

Diff에서 최소 네 가지 확인

요청한 파일만 바뀌었는가?
API 키·토큰·개인 경로가 들어가지 않았는가?
불필요한 의존성이나 대규모 포맷 변경이 없는가?
에이전트가 말한 테스트·검증을 실제로 실행했는가?

코드 줄에 수정 의견이 있으면 Diff의 줄 옆 +를 눌러 코멘트를 남기고 Send to agent로 한 번에 보낸다.
ex)

- 새탭, 새터미널이 열리며 codex 세션이 시작되는데 프롬프트가 자동으로 불러와 지지는 않았다.

- Annotate AI Diff 문서에서는 여러 코멘트를 모아 한 번의 재작업 요청으로 보내는 흐름을 권장한다.

7.4 테스트하고 의도한 변경만 commit한다

프로젝트 README에 적힌 테스트나 검사 명령을 Orca 터미널에서 실행한다. 통과한 범위와 실행하지 못한 검사를 구분한 뒤 다음 순서로 마무리한다.

Diff에서 파일 또는 hunk 단위로 의도한 변경만 stage한다.
commit 메시지를 직접 확인하고 Commit을 누른다. macOS 기본 단축키는 Cmd-Enter다.
원격에 공유할 작업이면 Push한다. 일반 Push가 실패해도 Orca는 자동으로 force-push하지 않는다.
GitHub·GitLab 연동을 마쳤다면 base branch, 제목, 설명, draft 여부를 확인한 뒤 PR/MR을 만든다.

이 순서는 Commit & push from Orca의 공식 흐름이다. 첫날에는 push나 PR까지 하지 않고 로컬 commit에서 멈춰도 된다.

ex) 사실 직접 stage, commit, push 한게 꽤 오래 지난것 같은데 간만에 이 글을 작성하기 위해 해보았다.

- 소스 제어 > 변경할 파일(난 1개 뿐이어서)을 선택하거나 "모두 스테이지"를 클릭

- 커밋메세지를 직접 작성하거나, AI 커밋 메시지 생성 기능을 사용 해보자.

- Commit > 브랜치 게시 클릭 하여 푸시 까지 마무리 하고

- PR 만들기 >

- 머지 클릭 > 머지 이후 처리 과정또한 확인 가능하다.

첫 작업 완료 기준

Add Repo → worktree 하나 → 에이전트 요청 → 상태 확인 → Diff 검토 → 테스트 → 선택한 변경만 commit까지 스스로 설명할 수 있으면 기본 사용법을 익힌 셈이다.

8. 개발에서는 어떻게 활용할까?

Orca 사용에 익숙해지면 같은 요청을 여러 AI 에이전트에 보내고 결과를 비교할 수 있다.

공식 가이드는 작업 공간 세 개에서 Claude Code, Codex, Cursor CLI의 결과를 비교한다.

처음에는 “버그 원인 분석”과 “테스트 보강”처럼 작은 작업 두 개부터 나눠 보자.

공식 First session의 3-agent 분할 화면. 출처:

단계	해볼 일	확인할 것
1	읽기 전용으로 원인 분석 요청	저장소 이해가 맞는지
2	worktree별로 작은 수정 맡기기	Diff와 테스트 결과
3	여러 결과를 나란히 비교	불필요한 변경과 회귀
4	선택한 결과만 commit·push	사람이 최종 검토했는지

종합하면: 병렬 실행 자체보다 같은 기준으로 Diff와 테스트를 비교하고 선택한 결과만 반영하는 과정이 핵심이다.

프론트엔드 작업은 작업 공간별 브라우저에서 각각 확인할 수 있다.

수정된 코드에 의견을 남길 때는 Annotate AI Diff를 사용한다.

8.1 새 worktree와 새 탭·분할 화면은 목적이 다르다

기존 cmux, tmux 등의 터미널과 동일하게 오르카도 탭 분할도 가능하다.

현재 공식 Tabs, panes & split layouts 문서에도 같은 메뉴와 분할 버튼이 안내돼 있다.

ex) 터미널에서 우클릭하면 다음과 같은 메뉴가 보이고, 여기서 선택하여 분할하기 (단축키도 확인 가능하다.)

ex) 터미널 탭에서 우클릭하여 분할하기

하려는 일	선택	이유
같은 기능을 두 방식으로 수정·비교	새 worktree	branch와 작업 파일을 분리한다.
같은 작업에서 shell·개발 서버·읽기 전용 보조 세션 추가	새 탭 또는 terminal split	같은 worktree의 파일을 함께 본다.
에이전트·Diff·브라우저를 동시에 확인	pane 분할	탭을 오른쪽 또는 아래 가장자리로 끌어 나란히 배치한다.

한 줄로 요약하면: 파일 결과를 분리할 때는 worktree, 같은 결과를 여러 화면으로 볼 때는 탭과 pane을 쓴다. 파일을 고칠 수 있는 에이전트 여러 개를 동시에 실행한다면 충돌을 피하도록 수정 작업마다 새 worktree를 만든다.

창을 닫았다고 에이전트가 끝난 것은 아니다

Session restore 문서에 따르면 Orca를 종료해도 백그라운드 daemon이 살아 있으면 에이전트가 계속 실행되고, 다시 열 때 worktree·분할 화면·scrollback에 재연결된다.

반면 컴퓨터 재부팅이나 daemon 종료 시 프로세스는 끝난다. 장시간 작업은 앱 창의 상태만 보고 중단 여부를 판단하지 않는다.

8.2 프론트엔드라면 브라우저와 Design Mode를 한 흐름으로 쓴다

프론트 엔드 개발시에는 Markdown·이미지·HTML을 확인하고, 내장 브라우저에서 요소를 골라 수정 요청을 보낸 다음 새로 고침으로 결과를 확인한다. 이 흐름은 공식 File explorer, Viewers, Per-worktree browser, Design Mode 문서에서도 확인할 수 있다.

Orca 터미널에서 프로젝트의 개발 서버를 실행한다.
같은 worktree의 브라우저 탭에서 로컬 주소를 열고 Design Mode를 켠다.
바꾸려는 요소에 마우스를 올려 강조 표시를 확인한 뒤 클릭한다.
활성 에이전트에 들어간 요소 문맥과 함께 “이 버튼의 배경색을 빨간색으로 바꾸고 기존 hover 대비를 유지해줘”처럼 결과를 구체적으로 요청한다.
hot reload 또는 새로 고침으로 화면을 보고, Diff와 테스트까지 확인한다.

ex) 나의 경우 cmux의 내장 브라우저를 매우 만족스럽게 사용했었고, 오르카에서의 브라우저도 기대를 해본다.

- 좌측 하단의 설정 클릭

- 브라우저 > Agent 브라우저 사용, Browser Use 스킬 설치

- 브라우저 쿠키까지 가져왔다.

- 그리고 하단엔 예시 프롬프트가 있다.

- 서버가 띄워져 있으면 이런식으로 브라우저를 열 수 있다. (외부 브라우저)

- 아니면 탭 + > 새 브라우저 탭 클릭 또는 단축키로도 터미널 내의 탭에 브라우저를 띄워주게 된다.

- 하지만 아까 에이전트를 사용해서 브라우저를 띄우겠다고 선택하였으니 다음과 같은 식으로 AI를 통해 브라우저를 열어볼 수 있다.

공식 문서에 따르면 이때 요소의 주변 HTML, 계산된 CSS, 잘라낸 스크린샷이 전달된다.

- 개발에 필요한 다양한 기능들도 존재 한다.

ex) 브라우저 데이터 가져오기

ex) 페이지 요소 가져오기

- 원하는 요소를 클릭 하자.

- 클로드 cli 채팅에 붙여넣고 확인해보면 요소가 복사 되어 있는것을 볼 수 있다.

- 이외에도 주석 기능

- Dev tools 호출 등등 다양한 기능을 제공해준다.

- 이외에도 자세한 내용은 공식문서에 계속 갱신 중이며, 혹시 react개발자라면 개발용 source map이 있을 때만 원본 파일과 줄 정보까지 붙으며, source map이 없는 프로젝트에서는 파일·줄 정보가 생략된다.

Design Mode는 렌더링된 화면에서 수정 대상을 지정하는 기능이라고 생각하면 쉽다.

Design Mode는 화면 작업, Annotate AI Diff는 코드 검토에 사용한다.

8.3 Orca CLI는 익숙해진 뒤의 자동화 도구다

Orca CLI는 앱에서 하던 반복 작업을 명령으로 자동화하는 고급 기능이다.

처음 설치할 때는 건너뛰어도 된다.

자동화가 필요해졌을 때 Orca CLI 문서를 참고하자.

8.4 모바일은 작은 데스크톱판보다 보조 리모컨에 가깝다

Orca 모바일 앱은 현재 beta인 read-mostly 보조 앱이다.

PC에서 진행 중인 작업을 확인하고 짧은 답을 보낼 수 있지만, 전체 편집과 최종 상태의 기준(source of truth)은 데스크톱 Orca다.

QR 코드 방식으로 모바일 화면 연결 할 수 있다.

( 공식 문서에서는 데스크톱의 account/status 메뉴에서 일회용 pairing code를 만든 뒤 모바일의 Pair에 붙여 넣거나 deep link를 여는 절차를 안내한다. )

데스크톱 Orca의 account/status 메뉴에서 모바일 pairing을 연다.
표시된 일회용 코드를 모바일 앱의 Pair에 입력한다.
모바일에서 worktree 상태와 최근 터미널 출력을 확인하고, 입력 대기 중인 에이전트에는 짧은 답만 보낸다.

모바일과 데스크톱은 Orca의 클라우드 중계 서버를 거치지 않고 직접 연결된다.

PC의 Orca를 닫으면 모바일 연결은 끊기지만, 앞서 설명한 daemon이 살아 있으면 로컬 에이전트 자체는 계속 실행될 수 있다. 데스크톱을 다시 열면 모바일이 재연결된다.

외부에서 연결하려면 공식 원격 연결 문서에 따라 별도의 사설 네트워크를 설정해야 한다. 연결용 pairing 링크는 접속 권한을 주므로 공개 채널에 올리면 안 된다.

ex) 코덱스 앱, 클로드 코드 등에서도 제공되는 휴대폰 제어 기능이다.

- 앱 다운로드 QR을 보여준다.

- 오르카 에서 Continue 클릭

- 다운로드한 앱을 설치한 후 QR 스캔

- 휴대폰과 페어링이 완료되어 사용 가능하다.

9. 주의사항과 트러블슈팅

9.1 worktree가 보안을 대신해 주지는 않는다

Git worktree는 작업 폴더를 나누는 기능이다.

AI 에이전트가 실행할 수 있는 명령이나 네트워크 접근까지 막아 주지는 않는다.

처음에는 Manual 권한과 개인 연습 프로젝트로 시작하자.

API 키나 운영 데이터가 있는 프로젝트는 회사 정책과 에이전트의 데이터 처리 조건을 먼저 확인해야 한다.

worktree는 작업 파일을 나누는 기능이다. 에이전트 권한은 Manual 설정에서 따로 관리한다.

9.2 수정 요청 전에는 활성 worktree를 다시 본다

파일 수정 요청을 보내기 전에 왼쪽에서 선택한 worktree가 맞는지 확인하자.

작업 이름이 헷갈리면 현재 branch와 터미널 경로도 함께 확인한다.

git branch --show-current
git rev-parse --show-toplevel
git status --short

특히 main이나 master가 보이면 새 worktree를 만들었는지 먼저 확인한다.

9.3 자주 막히는 지점

Q1. Add Repo에서 폴더를 골랐는데 진행되지 않는다면?

A. 먼저 터미널에서 해당 폴더로 이동해 git rev-parse --show-toplevel을 실행한다. Git 저장소 경로가 나오지 않으면 다른 연습 저장소를 선택한다.

Q2. 에이전트가 목록에 있지만 실행되지 않는다면?

A. Orca를 닫고 일반 터미널에서 해당 CLI의 --version과 로그인 상태를 확인한다. CLI가 먼저 단독 실행돼야 Orca 안에서도 문제를 좁히기 쉽다.

Q3. 7.1의 읽기 전용 요청 뒤 Diff가 비어 있다면?

A. 정상이다. 7.1 요청의 목적은 파일 수정 없이 프로젝트 설명만 받는 것이다.

Q4. Orca를 설치하면 AI 구독이 따라오나?

A. 아니다. Orca는 사용자가 가져온 에이전트와 구독을 실행한다. 모델 사용 한도와 결제는 각 공급자 계정에서 확인한다.

Q5. 여러 에이전트를 바로 병렬로 돌려도 될까?

A. 가능하다. 에이전트 하나로 권한과 Diff 흐름을 확인한 뒤 공식 3-agent 가이드로 넓히자. 이 순서가 비용과 변경 범위를 추적하기 쉽다.

Q6. 새 worktree 생성이나 setup이 실패한다면?

A. 작업 탭의 오류와 Retry를 먼저 본다. 시작 ref를 가져오지 못했다면 원본 저장소 터미널에서 git fetch origin을 실행하고, 같은 branch의 worktree가 이미 있는지도 확인한다. setup만 실패했다면 저장소에 맞지 않는 설치 명령이나 신뢰하지 않은 orca.yaml hook이 없는지 점검한다.

10. 마무리와 참고자료

처음에는 Orca도 AI 코딩 에이전트 중 하나인 줄 알았다.

문서를 살펴보니 여러 작업 공간과 AI 결과를 한 화면에서 관리하는 도구였다.

첫날에는 온보딩 체크리스트를 전부 채우기보다 기본 에이전트와 Manual 권한을 정하고, 연습 저장소를 추가해 worktree 하나에서 읽기 요청과 작은 수정까지 마친다. setup script는 프로젝트에 필요할 때만 추가한다.

그다음 Diff를 읽고 테스트한 뒤 선택한 변경만 local commit한다. 이 단일 작업 주기를 익힌 다음 공식 First session처럼 같은 prompt를 여러 worktree에 보내고 결과를 비교한다.

한 줄 정리

CLI 에이전트 준비 → Orca 설치 → 권한 Manual → Add Repo → setup 확인 → worktree 하나 → 읽기·작은 수정 → Diff·테스트 → local commit

공식 참고자료

GPT-5.6 입문, 완전 기초 | Chat, Codex, Spark 활용 하는 법(Chat·Work·Codex 구분하여 사용하기)

갓대희 — Mon, 13 Jul 2026 18:00:07 +0900

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

이번 포스팅은 [ GPT-5.6을 Chat·Codex·Spark로 나눠 쓰는 방법 ] 입니다. : )

앞선 글에서는 GPT-5.6의 Sol·Terra·Luna 차이를 정리했다.

GPT-5.6 리뷰 - Sol vs Terra vs Luna: 성능, 가격, 요금제, 접근 권한, 105만 토큰 컨텍스트와 새로운 Max 모드 등

새 모델이 나오고 한동안은 이것저것 눌러보느라 토큰을 꽤 많이 소비했을 것이다. 나 역시 처음에는 무조건 강한 모델부터 켜고 마구잡이로 사용해 보았다.

그런데 실제 작업을 시작해 보니 모델 선택만큼이나 Chat, Work, Codex 중 어디에서 시작할지가 중요했다.

같은 GPT-5.6을 쓰더라도 기획부터 코드 수정까지 한곳에서 밀어붙이는 것보다, 일의 성격에 따라 나누는 편이 토큰도 덜 들고 결과 확인도 쉬웠다.

이번 글에서는 여러 작업에 직접 적용해 보며 정착한 Chat에서 기획 → Codex에서 실행 → GPT-5.3-Codex-Spark로 작은 후속 작업 → 마지막은 직접 검수하는 흐름을 정리해 보려 한다.

솔직히 말하면 나도 Sol을 써본 지 2~3일밖에 안 됐다. 그 짧은 시간 동안 Threads, X(트위터), Reddit을 꽤 뒤졌는데, 커뮤니티에서 반복적으로 올라오는 패턴이 몇 가지 눈에 들어왔다.

그 중에서 나한테 가장 와닿은 것들만 추려서, 내 방식으로 다시 정리한 게 이 글이다.

커뮤니티에서 공통적으로 나오던 패턴 4가지

① “Chat은 '무엇을 할지', Codex는 '어떻게 할지'”
가장 많이 보인 표현이었다. 목표나 방향은 Chat에서 대화로 잡고, 실제 파일을 건드리는 실행은 Codex로 넘긴다는 것. 처음엔 그냥 Codex에 바로 시키면 되지 않나 싶었는데, 막상 해보니 Chat에서 한 번 정리하고 넘기는 게 훨씬 결과가 깔끔했다.

② “Sol을 모든 작업의 기본값으로 두지 마라”
X에서 꽤 공감 받던 글이었다. 간단한 수정에 Sol·Ultra를 쓰면 토큰이 훅 나가면서 품질이 오히려 애매해지는 경우가 있다고. 나도 실제로 간단한 수정에 Sol·높음 설정이 Sol·Ultra보다 결과가 더 군더더기 없었다. 추론 강도를 max·ultra로 올렸을 때 오히려 과하게 해석하고 불필요한 코드를 끼워 넣는 느낌이 들었다.

③ “Work랑 Codex 한도 분리되는 줄 알았다가 낭패봤다”
Reddit r/ChatGPT에서 꽤 공감 댓글이 달렸던 글이다. Work를 쓰면 Codex 한도를 아낄 수 있을 거라 생각했는데, 실제로는 둘이 같은 풀(pool)을 공유한다는 것. 나도 이걸 모르고 Work와 Codex를 왔다 갔다 했다가 생각보다 빠르게 한도가 찼다.

④ “Spark는 작고 되돌리기 쉬운 일에만 쓴다”
Threads에서 나온 얘기인데, Spark에 큰 일을 시키거나 “고쳐줘” 한 마디만 던지면 테스트를 자동으로 건너뛰는 경우가 있다고 했다. 수정 범위가 좁고 결과를 바로 확인할 수 있는 것만 맡기는 게 맞더라.

이 네 가지가 내 흐름에도 거의 그대로 들어맞았다. 나머지 세부 내용은 아래에서 순서대로 풀어보겠다.

이 글은 Codex·Work·Spark가 처음인 분을 기준으로 작성했습니다.

Chat, Work, Codex가 무엇이고 어떻게 다른지부터 차근차근 살펴봅니다.

이미 Codex나 Work를 자주 사용하고 있다면 앞부분은 가볍게 읽어도 됩니다.

먼저 짧게 정리하면

GPT-5.6은 모델 제품군이고, Chat·Work·Codex는 그 모델을 사용하는 환경이다.
Chat의 Sol은 현재 Plus·Pro·Business·Enterprise에서 제공된다. (출처: OpenAI GPT-5.6 발표)
질문이나 아이디어 정리는 Chat, 긴 자료 조사와 문서 작업은 Work, 실제 파일과 코드를 고치는 일은 Codex가 편했다.
Work와 Codex는 같은 agentic usage·credit pool을 사용한다. 둘을 번갈아 쓴다고 한도가 분리되지 않는다. (출처: OpenAI 사용량 문서)
GPT-5.3-Codex-Spark는 현재 ChatGPT Pro 대상 research preview이며 자체 rate limit을 쓴다. 단, 무료·무제한은 아니다. (출처: OpenAI Spark 발표)
“Task로 Codex에 넘긴다”는 것은 Chat 대화 전체를 복사하는 일이 아니다. 목표와 범위, 완료 조건을 짧게 정리해 전달하면 된다.

직접 써보며 정착한 작업 흐름
Chat, Work, Codex, Spark는 무엇이 다를까?
내가 실제로 일을 나누는 순서
Chat에서는 어디까지 정리할까?
Chat에서 정한 내용을 Codex로 넘기는 방법
Codex App과 CLI에서 작업하는 순서
Spark는 언제 사용하면 좋을까?
직접 써보며 줄인 토큰 낭비
상황별로 적용해 본 예시
바로 바꿔 쓸 수 있는 프롬프트
자주 낭비한 패턴과 궁금한 점
처음 적용한다면 이 순서로
참고 자료

1. 직접 써보며 정착한 작업 흐름

ChatGPT에서 GPT-5.6 Sol로 대화하며 방향을 잡고,
실제 작업은 Task로 나누어 Codex에 넘긴다.

끝나고 남은 작은 수정은 사용량이 별도인 GPT-5.3-Codex-Spark로 처리하고 있다.

여러 방식으로 써본 뒤 개인적으로 가장 편했던 흐름은 이렇다.

기획 단계에서는 ChatGPT와 편하게 대화하며 생각을 정리하고, 실제로 만들 일은 Task로 쪼개어 Codex에 맡기는 방식이다.

(물론 개발자분들은 기획과 계획부터 Codex Plan 모드에서 진행하는 편이 더 익숙할 수도 있다.)

모델과 추론 강도는 현재 다음 설정이 나에게 가장 잘 맞았다.

- 모델 : GPT-5.6 Sol

- 추론 강도 : 높음

추론 강도를 max나 ultra로 올리면 모든 작업에서 체감 성능이 좋아진다기보다 토큰 소모가 먼저 커지는 느낌이었다.

작업 중간에 생기는 간단한 수정은 5.3 Codex Spark로 빼두는 편이 속도나 토큰 사용량 면에서 더 나았다.

그렇다면 업무(Work) 모드는 언제 사용하면 좋을까?

- 여러 자료를 모아 표, 문서, 발표 자료로 정리할 때

- 보고서와 표가 필요하지만 로컬 코드를 직접 고칠 일은 없을 때

이럴 때는 Work부터 시작하면 편했다. 반대로 파일을 실제로 수정하고 테스트 결과까지 확인해야 한다면 Codex가 맞다.

짧은 사실, 간단한 대화로 끝날 내용은 굳이 긴 작업을 만들지 않고 Chat에서 끝내면 된다.

나도 작업 성격에 따라 중간중간 업무(Work) 모드로 바꾸어 사용한다. ( Codex App에서 다음과 같이 Codex > 업무 선택)

기존에 Claude CoWork를 써보셨다면 거의 비슷한 용도로 생각해도 무리가 없다.

시작하기 전에 모델이 보이는지부터 확인

이 글은 Sol과 Spark를 선택할 수 있는 계정을 기준으로 설명한다.

Chat에서 Sol이 보이지 않으면 표준 Chat에서 현재 선택 가능한 모델로 기획하고 Work·Codex에서 Terra가 보이면 Terra를 선택하면 된다.

Spark가 보이지 않으면 같은 작은 작업을 범위가 좁은 Codex Task로 처리한다.

플랜과 롤아웃은 바뀔 수 있으니, 글만 믿기보다 내 계정의 모델 선택 화면도 함께 확인하길 바란다.

① Chat

대화하면서 무엇을 만들지 정한다.

② Codex

실제 파일을 고치고 검증한다.

③ Spark

작고 확인하기 쉬운 일을 마무리한다.

④ 사람

결과와 테스트를 직접 확인한다.

여기서 사용량은 꼭 구분해서 봐야 한다. Work와 Codex는 같은 agentic usage·credit pool을 사용하므로 둘을 번갈아 쓴다고 한도가 따로 생기지 않는다.

Spark는 research preview 동안 별도 rate limit을 쓰지만, 무료나 무제한이라는 뜻은 아니다. 수요가 몰리면 대기하거나 접근이 제한될 수 있다.

1.1 가장 헷갈렸던 사용량 관계

사용 환경	공식 사용량 관계	실전에서 기억할 점
ChatGPT Work	Codex와 같은 agentic usage·credit pool	Work를 거친다고 한도가 따로 생기지 않는다.
Codex App·CLI	Work와 같은 agentic usage·credit pool	작업 크기·복잡도·모델에 따라 실제 소모량은 달라진다.
GPT-5.3-Codex-Spark	research preview 자체 rate limit	표준 한도와 별도지만 무료·무제한은 아니다.

그래서 Work와 Codex를 한도 분리 목적으로 오가는 것은 별 도움이 되지 않았다. Spark도 별도 한도일 뿐 무제한은 아니다.

2. Chat, Work, Codex, Spark는 무엇이 다를까?

앞선 글에서 Sol·Terra·Luna의 차이를 살펴봤다면, 이제는 그 모델을 어디에서 사용할지 구분할 차례다. 이름이 한꺼번에 보이면 모델과 제품이 뒤섞여 꽤 헷갈린다.

Sol·Terra·Luna는 성능과 비용이 다른 모델이고, Chat·Work·Codex·Spark는 그 모델로 어떤 일을 할지 정하는 사용 환경이다. 모델을 고르는 일과 작업할 곳을 고르는 일은 따로 생각하면 이해하기 쉽다. (OpenAI 공식 발표)

처음에는 모든 일을 Sol로 처리했지만, 오탈자 수정이나 링크 확인까지 무거운 모델을 붙잡고 있을 필요는 없었다. 판단을 많이 해야 하는 일에는 Sol을 쓰고, 정답과 확인 방법이 분명한 일은 가벼운 모델로 내리는 편이 훨씬 효율적이었다.

도구	잘 맞는 일	결과물	검수 포인트
Chat	질문, 검색, 브레인스토밍, 결정 정리	대화, 요약, 기획안	전제·우선순위·빠진 질문
Work	긴 리서치, 분석, 문서·표·슬라이드	완성 파일과 리포트	출처·수치·누락
Codex App	로컬 프로젝트, 여러 thread, diff 검토	파일 변경, 테스트, Git diff	변경 범위·테스트·회귀
Codex CLI	터미널 중심 반복 작업과 자동화	명령 결과, 코드, 로그	종료 코드·Git 상태
Spark	작은 수정, 빠른 탐색, 짧은 코딩	최소 diff, 빠른 답	테스트를 명시했는지

글에서 자주 나오는 용어

agentic usage·credit pool: Work와 Codex의 에이전트 작업 사용량·크레딧이 함께 차감되는 묶음이다.
rate limit: 일정 시간 동안 사용할 수 있는 작업·호출의 제한이다.
thread: Codex App에서 하나의 작업을 이어가는 대화 단위다.
worktree: 같은 Git 저장소의 변경이 서로 섞이지 않도록 나눈 작업 폴더다.
viewport: 브라우저에서 현재 보이는 화면 영역을 말한다.
built-in: 별도로 설치하지 않아도 앱에 기본으로 들어 있다는 뜻이다.
handoff brief: 목표와 범위, 완료 조건만 추려 다음 작업에 넘기는 짧은 인계서다.

3. 내가 실제로 일을 나누는 순서

처음에는 Chat 다음에 Work를 거쳐야 Codex로 넘어가는 줄 알았는데, Work는 꼭 지나야 하는 단계가 아니었다. 자료를 많이 조사해 문서나 표를 만들어야 할 때만 Work를 사용하고, 코드 작업이 중심이라면 Chat에서 정리한 내용을 Codex로 바로 넘긴다. 어차피 Work와 Codex는 같은 agentic pool을 사용하므로 한도를 아끼기 위해 중간에 Work를 끼워 넣을 이유도 없다.

1) Chat에서 생각을 정리한다

무엇을 만들지, 누가 볼지, 어디까지 다룰지 먼저 대화한다. 대화가 길어져도 마지막에는 목표와 범위, 기준 자료, 완료 조건만 남긴 짧은 brief로 정리한다.

2) Codex Ask Mode에서 실제 파일을 확인한다

Chat은 저장소 안의 실제 상황까지 알지 못한다. Codex가 관련 파일과 호출 관계, 테스트 명령을 읽은 뒤 계획을 다시 맞추게 한다. OpenAI 팀도 Ask Mode에서 만든 구현 계획을 Code Mode 작업에 이어서 사용한다고 설명한다.

3) Code Mode에서 고치고 바로 확인한다

“구현해줘”라고만 하면 결과를 어디까지 확인해야 하는지 애매하다. 수정할 범위와 함께 테스트, lint, HTML validator, 브라우저 확인처럼 끝났다고 판단할 기준도 같이 적어준다.

4) 남은 작은 일은 Spark로 뺀다

문장 하나 다듬기, 실패한 테스트 한 건 살펴보기, 누락된 패턴 찾기, diff 요약처럼 결과를 바로 확인할 수 있는 일만 따로 맡긴다.

마지막은 직접 확인한다

에이전트가 “완료했다”고 말한 것만 믿지는 않는다. diff와 테스트 출력, 브라우저 화면, 출처 링크를 직접 보고 마무리한다. 특히 Spark를 쓸 때는 어떤 검증을 실행할지도 함께 적어두는 편이 안전했다.

4. Chat에서는 어디까지 정리할까?

Chat에서 기획한다고 해서 대화를 끝없이 이어갈 필요는 없다. 여러 번 해보니 Codex가 작업하면서 다시 추측하지 않아도 될 정도만 정하면 충분했다. 나는 아래 일곱 가지가 채워지면 Codex로 넘긴다.

원하는 결과: “블로그를 써줘” 대신 어떤 주제의 어떤 파일을 완성할지 한 문장으로 쓴다.
읽을 사람: 입문자와 숙련자 중 누구를 위한 글인지 정하면 설명의 깊이가 흔들리지 않는다.
다룰 범위: 이번 글에 넣을 내용과 앞 글로 넘길 내용을 구분한다.
기준 자료: 공식 문서, 기존 파일, 디자인 시안과 자료의 기준일을 함께 적는다.
작업 크기: 한 번에 확인하기 어려운 일은 사람이 검수할 수 있는 단위로 나눈다.
완료를 확인할 방법: 테스트, validator, 링크 수, 화면 크기처럼 눈으로 확인할 조건을 쓴다.
멈춰야 할 때: 권한이 없거나 사실이 충돌하거나 삭제·배포가 필요하면 먼저 멈추도록 한다.

작업 크기는 어느 정도가 좋을까? OpenAI 내부 가이드는 사람이 약 한 시간에 처리할 일이나 수백 줄 규모의 변경을 Codex에 맡기기 좋은 범위로 설명한다. 한 번에 검수하기 어렵다면 이미 너무 큰 작업일 가능성이 높다.

5. Chat에서 정한 내용을 Codex로 넘기는 방법

이 부분이 처음에는 가장 헷갈렸다. Chat에서 계획을 잘 세워도 모든 계정에서 Codex로 바로 보내는 범용 원클릭 기능은 현재 공식 문서에서 확인하지 못했다. 그래서 나는 Chat 결과를 Codex의 새 thread 첫 메시지에 붙여 넣거나, brief.md로 저장해 프로젝트 폴더에서 읽게 한다.

같은 종류의 작업을 반복한다면 파일로 남기는 편이 더 편했다. 대화가 압축되거나 새 thread를 열어도 내용이 사라지지 않고, Git으로 변경 이력도 확인할 수 있기 때문이다.

# Handoff brief

## 목표
- 최종 결과를 한 문장으로 쓴다.
## 현재 상태
- 이미 존재하는 파일과 확인한 사실을 적는다.
## 작업 범위
- 읽을 경로, 수정 가능한 경로, 새 파일을 적는다.
## 변경 금지
- 건드리지 않을 파일, 삭제 금지, 외부 게시 금지를 적는다.
## 기준 자료
- 공식 URL, 기존 구현, 디자인, 데이터 기준일을 적는다.
## 완료 기준
- 실행할 테스트와 validator, 화면 확인 조건을 적는다.
## 중단 조건
- 권한 부족, 사실 충돌, 파괴적 작업이 필요한 경우를 적는다.
## 완료 보고
- 변경 파일, 실행 명령, 결과, 남은 위험을 보고한다.

OpenAI도 Codex 프롬프트를 GitHub Issue처럼 작성하고 파일 경로·컴포넌트·참고 구현을 포함하라고 권한다. (출처: OpenAI Codex 활용 가이드) 위 brief도 그 내용을 Chat에서 Codex로 넘기기 쉽게 줄여 쓴 형식이다.

6. Codex App과 CLI에서는 이렇게 작업했다

6.1 App과 CLI 중 무엇을 쓸까?

여러 thread를 한눈에 보고 diff를 검토하거나 worktree로 작업을 나누고 싶을 때는 App이 편했다. Codex 앱은 여러 agent 작업과 built-in worktree를 지원한다. (출처: Codex 앱 소개)

반대로 터미널에서 명령과 로그를 계속 지켜보거나, 기존 셸 자동화와 이어서 쓸 때는 CLI 쪽이 손에 더 잘 맞았다. 어느 쪽이 더 똑똑한 것이 아니라 작업 화면이 다른 셈이다.

6.2 실제로 사용한 순서

Ask Mode: 먼저 저장소를 읽고 어떤 파일이 영향을 받는지, 어떤 테스트를 돌릴지 확인한다.
수정 범위 확인: 고칠 파일과 건드리지 않을 파일을 나눈다.
Code Mode: 확인한 계획대로 실제 파일을 수정한다.
자동 검증: 테스트·lint·typecheck·validator를 실행한다.
직접 확인: 웹이면 브라우저, API면 실제 요청처럼 사용자가 쓰는 화면에서 한 번 더 확인한다.
마무리: 바뀐 파일과 검증 결과, 아직 남은 위험을 짧게 기록한다.

작업 중 방향이 틀어졌다고 매번 새 thread를 만들 필요는 없었다. Codex에서는 새 지시를 입력한 뒤 Steer로 진행 중인 작업을 바로 교정할 수 있다.

7. Spark는 언제 사용하면 좋을까?

Spark는 빠르다고 해서 아무 일이나 맡기는 모델은 아니었다. 내가 주로 넘긴 것은 변경 범위가 한두 파일로 좁고, 테스트나 diff를 보면 정답을 바로 확인할 수 있는 일이다.

실패하더라도 쉽게 되돌릴 수 있고 긴 배경 설명 없이 현재 파일만 보고 판단할 수 있다면 잘 맞았다. 반대로 작은 수정처럼 보여도 인증, 결제, 보안처럼 실패 비용이 큰 일은 Spark에 가볍게 넘기지 않았다.

작업	Spark 추천	이유
오탈자·링크·HTML 속성 수정	높음	범위와 정답이 분명하다.
한 테스트 실패 원인 좁히기	높음	빠른 대화형 탐색에 맞는다.
작은 함수 리팩터링	보통	회귀 테스트를 지정해야 한다.
여러 모듈 아키텍처 변경	낮음	긴 맥락과 설계 판단이 필요하다.
인증·결제·보안 정책	낮음	작은 diff여도 위험이 크다.
출처가 많은 장문 리서치	낮음	빠른 코딩 모델의 장점과 맞지 않는다.

Spark를 고를 때는 코드가 몇 줄인지보다 범위가 좁은지, 결과를 빨리 확인하고 되돌릴 수 있는지를 보았다.

사용하기 전에 확인할 점: Spark는 research preview 동안 자체 rate limit을 사용하고 표준 한도에 포함되지 않는다. 그렇다고 무료나 무제한은 아니며, 수요가 높으면 접근이 제한되거나 대기할 수 있다. 테스트도 기본으로 자동 실행하지 않으므로 프롬프트에 검증 명령을 직접 적어주는 편이 좋다.

(출처: OpenAI Spark 발표)

8. 직접 써보며 줄인 토큰 낭비

토큰을 아끼려고 무조건 가벼운 모델만 쓰는 방법은 오래가지 않았다. 잘못 이해한 상태로 작업을 다시 시키면 오히려 더 많이 쓰게 된다. 모델보다 먼저 작업을 전달하는 방식을 바꾸었더니 낭비가 눈에 띄게 줄었다.

Chat 대화 전체를 복사하지 않고, 목표·결정·자료·완료 조건만 brief에 남겨 넘긴다.
문체나 테스트처럼 매번 반복하는 규칙은 프로젝트의 AGENTS.md에 적어둔다.
큰 작업은 조사, 설계, 구현, 테스트, 화면 확인처럼 내가 중간 결과를 검수할 수 있는 지점에서 나눈다.
Work와 Codex는 같은 agentic pool을 사용하므로 한도를 피하려고 두 환경을 오가지 않는다.
Sol은 실패했을 때 손실이 크거나 판단이 복잡한 일에 먼저 쓰고, 단순한 작업까지 기본값으로 두지는 않는다.
작업하다 발견한 오탈자나 경고는 본 작업에 섞지 않고 작업 목록(task queue)으로 빼둔다.
여러 thread를 동시에 돌릴 때는 같은 파일을 고치지 않도록 담당 파일과 worktree를 나눈다.
테스트가 실패했다면 숨기지 않고, 실행한 명령과 오류 한 줄을 완료 보고에 남긴다.
몇 번 직접 실행해 성공한 반복 작업만 skill이나 automation(자동화)으로 옮긴다. 불안정한 작업을 먼저 자동화하면 실패도 그대로 반복된다.

9. 상황별로 적용해 본 예시

설명만 읽으면 역할이 딱 나뉘는 것 같지만, 실제로 쓰다 보면 “여기서 Codex로 넘길까, Chat에서 조금 더 이야기할까?” 고민하는 순간이 자주 온다. 내가 반복해서 해본 세 가지 작업은 아래처럼 나누어 사용했다.

9.1 기술 블로그 작성

먼저 Chat Sol에서 누가 읽을 글인지, 어떤 각도로 쓸지, 반드시 답할 질문과 과장하지 않을 표현을 정한다.
외부 자료가 많아 표나 리포트까지 만들어야 할 때만 Work를 중간에 사용한다.
Codex에는 기존 글과 로컬 스타일을 읽게 한 뒤 작성 기준(spec), 근거(evidence), 초안(draft), 최종 HTML 파일을 만들게 한다.
링크 누락, data-ke 속성, 어색한 문장, 목차 앵커처럼 작은 수정은 Spark로 분리한다.
마지막에는 모바일과 데스크톱 화면을 직접 열어보고, 인용한 출처도 다시 확인한다.

9.2 코드 기능 개발

Chat Sol에서는 사용자가 겪는 문제와 꼭 지켜야 할 조건, 이번에 건드리지 않을 범위를 정리한다.
Codex Ask Mode로 실제 모듈 경계와 기존 구현 방식, 테스트 위치를 먼저 찾는다.
계획이 맞으면 Code Mode에서 기능과 테스트를 함께 구현한다.
실패한 테스트 한 건이나 타입 오류, 문구, 작은 접근성 문제는 별도 Spark 작업으로 뺀다.
끝나면 실제 UI나 API에 정상 입력과 실패 입력을 모두 넣어본다.

9.3 오래된 콘텐츠 유지보수

Chat에서 어디까지 업데이트할지, 그대로 남길 문장은 무엇인지 먼저 정한다.
Codex로 오래된 버전, 링크, 명령을 검색하고 바뀔 파일 목록을 만든다.
확인한 목록은 Spark가 파일별 작은 diff로 반영하게 할 수 있다.
마지막에는 Git diff를 열어 범위 밖의 문장까지 바뀌지 않았는지 확인한다.

세 작업을 해보고 남은 기준

Chat에서는 무엇을 할지 정하고, Codex에서는 실제 파일을 바꾼다. Spark는 앞의 작업이 끝난 뒤 범위가 분명해진 작은 수정에 붙였을 때 가장 편했다.

10. 바로 바꿔 쓸 수 있는 프롬프트

아래 문장은 실제로 사용할 때 대괄호 안의 내용만 바꾸면 된다. 그대로 복사하기보다 내 프로젝트의 파일 경로와 검증 명령을 구체적으로 적을수록 결과가 안정적이었다.

10.1 Chat Sol에서 기획을 정리할 때

나는 [xx 결과]를 완성하려 한다. 바로 실행하지 말고 먼저 기획한다.

1. 목표를 한 문장으로 다시 정의해라.
2. 독자/사용자와 해결할 문제를 적어라.
3. 필수로 포함할 것과 제외할 것을 나눠라.
4. 결정이 필요한 질문을 최대 7개로 줄여라.
5. 작업을 사람이 검수할 수 있는 3~5단계로 나눠라.
6. 각 단계의 완료 증거와 중단 조건을 적어라.
7. 마지막에는 Codex에 전달할 handoff brief만 출력해라.

확인하지 않은 사실은 [미확인], 내 선택이 필요한 것은 [결정 필요]로 표시해라.

10.2 Codex가 저장소를 먼저 살펴보게 할 때

다음 handoff brief를 읽고 아직 수정하지 마라.

[brief.md 경로 또는 본문]

저장소를 확인해 다음만 보고해라.
- 관련 파일과 현재 동작
- 기존 구현 패턴
- 예상 변경 파일
- 회귀 위험
- 실행할 테스트와 수동 QA
- brief와 저장소 현실이 충돌하는 부분

정보가 충분하면 3~7단계 구현 계획을 제시하고 기다려라.

10.3 확인한 계획대로 구현할 때

승인한 계획대로 구현해라.

수정 허용: [경로]
변경 금지: [경로/동작]
완료 기준:
- [테스트 명령]
- [lint/typecheck/validator]
- [실제 UI/API/CLI 수동 QA]

실패하면 원인을 고치고 검증을 다시 실행해라.
완료 후 변경 파일, 실행 명령과 결과, 남은 위험만 보고해라.

10.4 Spark에 작은 수정 하나만 맡길 때

작업은 하나뿐이다: [작은 작업].

수정 범위: [한두 파일]
하지 말 것: 주변 리팩터링, 새 의존성, 관련 없는 포맷 변경
검증: [짧은 테스트/검색/화면 확인]

최소 diff로 처리해라. 테스트는 자동으로 생략하지 말고 위 검증을 실행해라.
완료 후 바뀐 줄과 검증 결과만 짧게 보고해라.

11. 자주 낭비한 패턴과 궁금한 점

토큰이 많이 든 작업을 되짚어보면 모델을 잘못 고른 경우보다, 목표와 범위를 대충 넘겨 같은 설명을 반복한 경우가 더 많았다. 내가 자주 했던 실수를 표로 정리해 보았다.

낭비	왜 낭비되는가	바꿀 방법
App이나 CLI부터 열고 “알아서” 시킨다	작업하면서 목표와 완료 조건을 계속 다시 묻게 된다.	Chat에서 원하는 결과와 범위를 먼저 정한다.
Chat 로그 전체를 복사한다	지금 작업과 상관없는 대화까지 함께 읽게 된다.	결정한 내용만 짧은 brief로 줄여 넘긴다.
Work와 Codex를 한도 분리용으로 왕복한다	같은 agentic pool을 사용한다.	필요한 결과가 문서인지 코드인지 보고 환경을 고른다.
모든 일을 Sol로 실행한다	작은 수정까지 긴 맥락과 높은 추론 비용을 유지한다.	범위가 분명한 일은 Terra나 Spark로 분리한다.
Spark에 “고쳐줘”만 쓴다	수정은 해도 테스트까지 알아서 실행하지 않는다.	고칠 파일과 실행할 테스트를 함께 적는다.
병렬 thread가 같은 파일을 고친다	나중에 변경을 합치며 충돌을 해결해야 한다.	담당 파일과 worktree를 미리 나눈다.

직접 써보니 토큰은 비싼 모델을 한 번 고른 것보다, 목표·범위·검증을 빼먹어 같은 작업을 다시 할 때 더 많이 샜다.

사용하면서 헷갈렸던 질문

Q1. ChatGPT Work는 Codex 한도와 같이 빠지는가?

그렇다. 현재 공식 문서에 따르면 Work와 Codex는 같은 agentic usage·credit pool을 사용한다. 다만 작업 크기와 복잡도, 선택한 모델, 실행 위치에 따라 실제 소모량은 달라질 수 있다.

Q2. 기획은 무조건 일반 Chat에서 해야 하나?

꼭 그렇지는 않다. 저장소와 상관없이 문제를 정리할 때는 Chat이 편하지만, 실제 파일 구조에 따라 계획이 달라진다면 처음부터 Codex Ask Mode에서 살펴보는 편이 정확하다.

Q3. Spark는 표준 한도를 전혀 쓰지 않는가?

공식 발표는 research preview 동안 자체 rate limit을 사용하고 표준 한도에는 포함되지 않는다고 설명한다. 하지만 별도 한도라고 해서 무료나 무제한은 아니다. 실제 사용 전에는 계정의 Usage 화면도 함께 확인하는 것이 좋다.

Q4. Chat 계획을 Codex로 자동 전송할 수 있는가?

모든 계정에서 통하는 범용 원클릭 전송 기능은 공식 문서에서 확인하지 못했다. 그래서 brief를 새 thread의 첫 메시지로 전달하거나 프로젝트 파일로 저장하는 방식을 사용하고 있다.

Q5. 반복 업무마다 별도 에이전트 프로젝트를 만들어야 하는가?

반복 규칙만 담은 프로젝트라면 AGENTS.md·skills·automations로 옮길 수 있는 부분이 많아졌다. 다만 독자적인 데이터 모델이나 제품 UI, 배포와 권한 체계가 필요하다면 별도 프로젝트로 유지할 이유가 충분하다. 기존 프로젝트를 한 번에 없애기보다 규칙, 연결, UI, 배포로 나누어 대체 가능한 부분부터 줄이는 편이 안전하다.

12. 처음 적용한다면 이 순서로

처음부터 작업 방식을 전부 바꿀 필요는 없다. 오늘 자주 맡기는 일 하나만 골라 아래 순서대로 해보면 Chat과 Codex를 어디에서 나눌지 금방 감이 온다.

오늘 바로 해볼 것

반복해서 맡기는 작업 하나를 고른다.
Chat에서 원하는 결과, 범위, 기준 자료, 완료 조건을 정리한다.
brief.md를 만든다.
Codex Ask Mode에서 실제 파일 기준으로 계획을 보정한다.
한 개의 작은 작업만 실행하고 테스트한다.

익숙해진 다음

자주 반복하는 규칙을 AGENTS.md로 옮긴다.
본 작업 중 발견한 작은 수정은 별도 작업 목록(task queue)으로 모은다.
어떤 일을 Spark에 맡길지 팀이나 개인 기준을 정한다.
완료 보고에는 테스트 결과와 아직 확인하지 못한 부분을 함께 남긴다.

반복 작업까지 이어갈 때

여러 thread를 함께 쓴다면 담당 파일과 worktree 규칙을 만든다.
Usage 화면을 보며 작업별로 어떤 모델이 잘 맞았는지 간단히 기록한다.
직접 여러 번 성공한 작업만 skill이나 automation으로 옮긴다.

앞선 글에서 Sol·Terra·Luna를 비교했다면, 이번 글에서는 그 모델을 실제 일에 어떻게 나누어 붙일지 정리해 보았다. 직접 써보니 “무조건 Sol”보다 판단이 어려운 곳에는 Sol과 높은 추론 강도를 쓰고, 실제 파일 작업은 Codex로 넘긴 뒤, 범위가 작은 수정만 Spark로 빼는 방식이 나에게 가장 잘 맞았다.

토큰을 아끼는 특별한 공식이 따로 있는 것은 아니었다. brief를 짧게 남기고, 한 번에 맡길 범위를 나누고, 끝났는지 직접 확인하는 것. 이 세 가지만 지켜도 같은 작업을 다시 시키는 일이 많이 줄었다. : )

참고 자료

공식 문서

커뮤니티·관련 글

갓대희 - GPT-5.6 리뷰: Sol vs Terra vs Luna

GPT-5.6 리뷰 - Sol vs Terra vs Luna: 성능, 가격, 요금제, 접근 권한, 105만 토큰 컨텍스트와 새로운 Max 모드 등

갓대희 — Fri, 10 Jul 2026 17:30:35 +0900

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

이번 포스팅은 [ OpenAI GPT-5.6 정식 출시 및 모델별 비교 분석 ] 입니다. : )

OpenAI가 2026년 6월 26일, GPT-5.6을 단일 모델이 아닌 무려 세 개의 모델로 나누어 공개했다.

이름은 각각 Sol, Terra, Luna 이다. 버전은 5.6으로 같은데 이름이 세 개나 되다 보니, 처음 접하시는 분들은 "그래서 대체 내 실무엔 어떤 걸 써야 하지?" 하고 많이 헷갈렸을 것이다.

첫 공개 당시에는 미국 정부와의 사전 협의를 거친 제한적인 출시였기 때문에, 우리 같은 일반 사용자는 ChatGPT에서 바로 써볼 수 없었다.

하지만 드디어 2026년 7월 9일, OpenAI가 제한 Preview를 끝내고 정식 출시(GA)를 선언하면서 이제 우리나라에서도 자유롭게 사용할 수 있게 되었다!

발표에 따르면 ChatGPT, Codex, 그리고 OpenAI API의 글로벌 롤아웃이 시작되었고, 발표 시점 이후 24시간에 걸쳐 점진적으로 가용성을 확대할 계획이라고 한다.

이번 포스팅에서는 새롭게 출시된 GPT-5.6의 제품별 접근 범위부터 105만 토큰 컨텍스트, 모델별 공통 max 모드, Programmatic Tool Calling, multi-agent beta, 변경된 벤치마크 결과, 그리고 METR 안전성 평가 이슈와 출시 직후 커뮤니티의 반응까지 아주 딥(deep)하게 털어보려 한다.

특히 이번에는 ChatGPT·Codex·API 각각에서 GPT-5.6을 실제로 선택하는 방법과, 싱글 프롬프트로 게임을 만들어 보는 실전 체험기, 그리고 커뮤니티에서 화제가 된 활용 사례와 바로 따라해 볼 수 있는 예시 프롬프트까지 빠짐없이 담았다.

핵심 6가지 요약

GPT-5.6은 Sol, Terra, Luna 세 가지 모델로 나뉜다. 숫자(5.6)는 '세대'를 뜻하고, 이름은 각자 특화된 '역량 계층'을 의미한다.
가격은 Sol $5/$30, Terra $2.50/$15, Luna $1/$6 (입력/출력, 100만 토큰당, 2026-07-10 기준)로 모델 간 최대 5배까지 차이가 난다.
세 모델 모두 API에서 none부터 max까지 지원한다. ultra는 특정 제품이나 플랜별 multi-agent 설정일 뿐, Sol만의 고유 스펙은 아니다.
컨텍스트 윈도우는 세 모델 모두 105만 토큰이며, 최대 출력은 12.8만 토큰이다.
GA Terminal-Bench 공식 수치는 Terra 87.4%, Luna 84.7% 이다. (OpenAI 자체 보고 값이며, 독립 검증 리더보드와는 엄격히 구분해서 봐야 한다.)
표준 Chat, Work, Codex, API 등 환경에 따라 모델 선택 범위가 다르다. Free 및 Go 플랜의 Terra 접근은 표준 Chat이 아닌 Codex 환경에 해당한다.

▶ 목차

범위와 데이터 출처
발표 개요와 네이밍 체계
전체 비교 매트릭스
세 모델 심층 분석 — Sol · Terra · Luna
가격과 부대 비용
성능 벤치마크 읽는 법
제한 Preview의 배경과 GA 전환
GA에서 추가된 실전 기능 — API · Work · Codex
어디서 쓸 수 있나? — 제품별 접근 가이드
직접 사용해보기 — 활용 사례와 예시 프롬프트
안전성 평가(METR)와 커뮤니티 반응
작업 유형별 모델 선택 기준
한국 사용자 실용 가이드 (체크리스트)
FAQ와 트러블슈팅
결론

1. 범위와 데이터 출처

이번 포스팅에서 다룰 핵심은 GPT-5.6 세 모델의 직접적인 비교와 '어떤 상황에 무엇을 써야 할까'에 대한 가이드로 방향을 잡았다.

타사 모델과의 벤치마크 싸움보다는, "Sol, Terra, Luna 중 내 리소스와 작업에 맞는 최적의 모델은 무엇일까?"라는 질문에 포커스를 맞췄다.

주요 데이터는 OpenAI의 GA 공식 발표, 제품별 Help Center 문서, GPT-5.6 API 가이드, 그리고 GA 시스템 카드를 참고했다.

단, 수치나 가격 등은 측정 시점과 환경, 정책 변경에 따라 달라질 수 있으니 기준일(2026-07-10)을 염두에 두고 읽어주길 바란다. 스펙만 보고 판단하기엔 한계가 있으니, 실무에서는 꼭 본인의 데이터로 직접 테스트해 보는 것을 권장한다.

2. 발표 개요와 네이밍 체계

2.1 무슨 일이 있었나?

앞서 언급했듯 OpenAI는 2026년 6월 26일, GPT-5.6을 Sol, Terra, Luna 세 계층으로 먼저 공개했었다.

당시엔 미국 정부의 요청에 따라 API와 Codex의 소수 신뢰 파트너(trusted partners)에게만 Preview 형태로 제공되었고, 일반 ChatGPT 유저들은 구경만 해야 했다.

[현재 상태] 하지만 2026년 7월 9일, 정식 출시(GA)가 선언되며 글로벌 롤아웃이 시작되었다. 단, '전 세계 동시 땡!' 하고 열린 것은 아니고 24시간에 걸친 점진적 확대 방식이므로, 계정이나 플랜에 따라 내 화면에 뜨는 시점이 미세하게 다를 수 있다.

이번 릴리스의 가장 큰 특징은 '하나의 만능 모델'을 던져주는 것이 아니라, 가격·속도·성능이 각기 다른 세 계층을 만들어 작업 목적에 맞게 골라 쓰도록(durable capability tiers) 설계했다는 점이다.

다만 표준 Chat, Work, Codex, API 별로 선택할 수 있는 모델 범위나 모드 이름이 조금씩 달라서 스펙과 UI를 혼동하기 쉽다.

2.2 네이밍 체계 — 숫자와 이름의 분리

처음 접하면 네이밍이 꽤 헷갈릴 수 있다.

간단히 말해 숫자 '5.6'은 모델의 세대(Generation)를 뜻하고, 뒤에 붙는 Sol, Terra, Luna는 각 모델의 포지션(가격 및 역량 계층)을 뜻한다.

마치 자동차를 살 때 연식(세대)은 같아도 트림(기본형, 고급형 등)이 나뉘어 있는 것과 비슷하다고 보면 된다. 향후에 특정 계층만 따로 업데이트될 가능성도 열려 있으니 API 개발자라면 정확한 모델 ID와 변경 로그를 추적하는 습관이 필요하다.

네이밍 한 줄 정리

5.6 = 세대(언제 나온 모델인가?)
Sol / Terra / Luna = 역량 계층(어느 정도 급인가?).
Sol은 태양(최상위 성능), Terra는 대지(기본·균형), Luna는 달(가볍고 빠름)로 연상하면 직관적이다. : )

3. 전체 비교 매트릭스

공식 API 가격과 모델 사양을 기준으로 세 가지 모델의 핵심을 표로 비교해 보았다.

"적합 작업"은 OpenAI가 권장하는 포지셔닝일 뿐, 실제 내 서비스에서의 품질 우열은 무조건 자체 데이터 평가로 확인해야 한다.

비교 항목	Sol (플래그십)	Terra (균형·기본)	Luna (고속·저가)
입력 가격 (1M 토큰)	$5	$2.50	$1
출력 가격 (1M 토큰)	$30	$15	$6
API 추론 노력	지원	지원	지원
컨텍스트 / 최대 출력	105만 / 12.8만	105만 / 12.8만	105만 / 12.8만
포지션	최고 성능, 복잡·다단계 문제	비용·성능의 기준선	호출량·비용·지연에 민감
적합 작업	코딩 에이전트, 보안·과학 연구	일반 코딩·분석, 기본값	실시간 챗봇, 대량 배치
부적합 작업	단순·대량 호출(과한 비용)	오류 비용이 매우 큰 최상위 과제	검증 없이 맡기는 고위험 과제

확실히 세 모델의 타겟팅과 가격대가 명확히 구분된다. 가격 산정과 벤치마크 디테일은 아래 섹션에서 조금 더 깊게 파고들어 보겠다.

4. 세 모델 심층 분석 — Sol · Terra · Luna

4.1 Sol — 품질 우선 플래그십

Sol은 가격보다는 '압도적인 정확도'와 '복잡한 다단계 작업 해결' 능력을 최우선으로 하는 플래그십(최상위) 계층 모델이다.

여기서 많이들 오해하는 게 "API의 max 모드는 Sol 전용이다"라고 생각하는 것인데, 사실 그렇지 않다.

공식 문서를 보면 Sol, Terra, Luna 세 모델 모두 none부터 max 모드까지 폭넓게 지원한다.

또한 ultra라는 단어도 특정 모델의 고유 스펙이 아니라 ChatGPT Work 및 Codex 등에서 여러 서브에이전트를 조율할 때 쓰는 '제품 실행 모드' 중 하나일 뿐이다.

OpenAI가 발표한 Sol Ultra 벤치마크는 기본 4-agent 구성 기반이다.

이 말인즉슨, 각 에이전트가 소모한 토큰 비용이 전부 합산된다는 뜻이므로 일반적인 단일 실행 점수와 1:1로 비교하면 비용 폭탄을 맞을 수 있으니 주의해야 한다.

ultra 모드란?

문제를 여러 서브에이전트가 나누어 풀고 결과를 하나로 합치는 방식의 제품 실행 모드를 말한다.

4-agent 구성이라고 해서 정확히 비용이 4배가 되는 건 아니지만, 동원된 모든 에이전트의 토큰이 합산 청구되므로 품질 이점과 더불어 '총 토큰 소모량, 실패율, 지연 시간' 등을 꼼꼼히 체크해야 한다.

▶ 언제 쓰는가? : 코딩 에이전트 구축, 보안 취약점 분석, 과학 연구 등 정확도가 비용보다 압도적으로 중요한 고난도 작업.

▶ 언제 피하는가? : 단순 요약이나 대량의 데이터 분류 작업. 닭 잡는 데 소 잡는 칼을 쓰는 격이 되어 예산이 낭비된다.

4.2 Terra — 균형 잡힌 기본값 모델

Terra는 성능과 비용, 두 마리 토끼의 균형을 위해 설계된 미들급 계층 모델이다.

입출력 단가가 Sol의 딱 절반 수준이면서도, GA 기준 Terminal-Bench에서 87.4%의 우수한 스코어(Luna 84.7% 대비 우위)를 보여준다.

"기존 GPT-5.5급 성능"이라는 홍보 문구만 믿고 맹신하기보다는, 새로운 프롬프트를 테스트할 때 '품질 기준선(Baseline)'으로 삼기에 아주 훌륭한 모델이다.

▶ 언제 쓰는가? : 일반적인 코드 생성 및 리뷰, 문서 작성, 데이터 분석 등 품질과 비용 밸런스가 모두 중요한 대다수의 실무 작업.

▶ 언제 바꾸는가? : Terra로 돌렸을 때 발생하는 '오류로 인한 기회비용'이 크다면 Sol로 스펙업하고, 품질은 충분한데 단가가 부담된다면 Luna로 스펙다운 해보며 A/B 테스트를 진행한다.

Terra를 기준점으로 스마트하게 활용하는 법

잘 모르겠다면 일단 Terra로 시작하자.
성능이 조금 아쉽다 싶으면 Sol로 올리고, 성능은 충분한데 API 비용을 더 아끼고 싶다면 Luna로 내린다.

이처럼 계층을 하나로 고정하지 않고, 작업 성격에 맞게 유연하게 갈아 끼우는 것이 이번 5.6 라인업 설계의 진짜 핵심이다.

4.3 Luna — 초경량 · 초저가 모델

Luna는 대규모 호출, 저지연 처리, 그리고 비용 절감이 지상 과제인 워크로드를 위해 태어난 최저가 계층이다.

입력 100만 토큰당 $1, 출력은 $6으로 무려 Sol 모델의 5분의 1 가격밖에 되지 않는다.

다만, 공식 문서 상에서 무조건 Luna가 모든 작업에서 가장 빠르다고 보장하지는 않기 때문에, 실시간 서비스에 도입할 계획이라면 지연 시간(Latency)은 직접 측정해 보아야 한다.

Luna를 선택하는 가장 큰 명분은 '최고의 점수'가 아니다. 내가 원하는 최소 품질 기준선을 통과하면서도 압도적으로 낮은 단가를 누릴 수 있다는 점이 Luna의 진정한 매력이다.

▶ 언제 쓰는가? : 품질 허들이 명확한 대량의 텍스트 분류, 데이터 추출, 단순 초안 작성, 1차 고객 응대 챗봇 등.

▶ 언제 피하는가? : 별도의 사람 검증(Human-in-the-loop) 장치가 없는 보안 업무, 고위험 의사결정 등.

5. 가격과 부대 비용

5.1 토큰 단가 살펴보기

세 모델의 100만 토큰당 표준 단가를 정리해 보았다. (2026-07-10 공식 가격표 기준)

모델	입력 (1M 토큰)	출력 (1M 토큰)	Sol 대비 입력 배율
Sol	$5.00	$30.00	1.0배 (기준)
Terra	$2.50	$15.00	0.5배
Luna	$1.00	$6.00	0.2배

가격 차이가 확연하죠? 하지만 여기서 실무자가 꼭 체크해야 할 숨은 함정이 있다.

한 번의 API 요청 시 입력값이 272K 토큰을 초과하게 되면, 전체 요청에 대해 입력은 2배, 출력은 1.5배의 할증 요율이 적용된다. RAG 같은 걸로 무지막지하게 긴 문서를 컨텍스트로 넘길 때는 기본 단가만 계산하면 예산이 크게 펑크날 수 있다.

5.2 프롬프트 캐싱 · 컨텍스트 · 속도

비용 절감의 핵심 기술, 프롬프트 캐시(Prompt Caching)도 잘 활용해야 한다.

1,024 토큰 이상의 요청에서 동일한 앞부분 텍스트가 일치할 때 적용되며, 캐시 수명은 최소 30분이다.

처음 캐시를 구울 때(cache_write_tokens)는 기본 입력 요율의 1.25배가 들지만, 이후 캐시를 읽어올 때는 무려 90%의 할인이 들어간다. (반복되는 시스템 프롬프트는 무조건 앞쪽에 배치하자!)

세 모델 모두 공식 컨텍스트 창은 105만 토큰이며, 한 번에 생성 가능한 최대 출력은 12.8만 토큰이다.

참고로 Preview 공개 당시 Cerebras를 통해 7월 중 초당 750토큰의 속도로 Sol을 제공한다는 이야기가 있었는데, 이번 GA 문서에는 해당 내용이 구체적으로 확정되어 나오지 않았다. 속도 관련해서는 향후 공지를 좀 더 지켜봐야 할 듯하다.

6. 성능 벤치마크 읽는 법

6.1 Terminal-Bench 2.1

에이전트형 코딩 능력을 측정하는 Terminal-Bench 2.1의 GA 수치를 살펴보겠다.

아래 수치들은 OpenAI가 자체 보고한 값이며, 외부 독립 검증 리더보드(tbench.ai 등)에는 아직 등재 전이라는 점을 꼭 인지하길 바란다.

GPT-5.6 계층	Terminal-Bench 2.1	비고
Sol Ultra	91.9%	기본 4-agent Ultra (에이전트별 토큰 비용 합산 주의)
Sol	88.8%	일반 단일 실행 결과
Terra	87.4%	가장 추천하는 균형 계층
Luna	84.7%	저가 계층
GPT-5.5	85.6%	비교군 (OpenAI 동일 표 기준)

6.2 CTF·GeneBench — 도메인별 편차

※ GeneBench Pro 벤치마크란 무엇인가?

OpenAI가 발표한 GeneBench Pro는 단순한 코딩 능력이 아니라, 모델의 '과학적 직관(Research Taste)'과 다단계 추론 능력을 평가하기 위해 만든 연구 수준의 전산 생물학 벤치마크다. 유전체학(Genomics)이나 정량 생물학 분야의 복잡한 데이터를 다룬다.

1) 암기가 아닌 '판단력' 테스트

단순히 팩트를 기억하거나 정해진 코드를 짜는 게 아니라, 주어지는 데이터가 질문을 뒷받침할 수 있는지, 중간에 가설을 수정해야 하는지 등 인간 연구원이 하는 '판단(Judgment calls)'을 모델이 스스로 할 수 있는지 측정한다. 외부 전문가들에 따르면 전문 연구원이 한 문제를 푸는 데 무려 20~40시간이 걸릴 정도의 극악의 난이도를 자랑한다.

2) 꼼수(Cheating)의 원천 차단

AI가 대충 그럴싸한 지름길이나 꼼수를 써서 결과만 맞히는 것을 방지하기 위해, 129개의 문제를 모두 인과 구조가 통제된 '합성 데이터(Synthetic data)'로 구축했다. 즉, 올바른 분석 논리와 경로를 거치지 않으면 절대 정답을 낼 수 없도록 엄격하게 설계되었다.

3) Sol의 28.7%가 시사하는 바

Sol이 기록한 28.7%라는 수치는 낮아 보일지 몰라도, 이전 세대인 GPT-5.5(12.0%)나 초기 모델(5% 미만) 대비 엄청난 발전이다. 틀린 문제들을 분석해 보면 모델들이 데이터의 이상 신호를 '발견'은 하지만, 이를 전체 분석에 반영하지 못하고 처음에 잡은 잘못된 분석 방향을 끝까지 고집하는 한계를 보였다. 이는 아직 완전 자율 연구를 맡기기엔 무리이며, 인간 전문가의 승인(Human-in-the-loop)이 반드시 필요한 이유를 정확히 뒷받침하는 지표다.

OpenAI GA에서 보고한 CTF와 GeneBench Pro 벤더 실행 수치도 계층별 차이가 컸다.

CTF는 보호 장치가 줄어든 연구 환경의 결과이고, GeneBench Pro는 생물학 연구 과제다.

일반 사용자 작업의 성공률로 일반화하면 안 된다.

벤치마크	Sol	Terra	Luna	GPT-5.5
CTF 히트율(사이버보안)	96.7%	91.8%	85.2%	88.1%
GeneBench Pro	28.7%	23.3%	10.8%	12.0%

CTF에서는 세 모델이 Sol > Terra > Luna 순서지만, Luna는 GPT-5.5보다 낮다.

GeneBench Pro에서도 Luna 10.8%는 GPT-5.5 12.0%보다 낮다.

“신세대 저가 모델이면 전 세대보다 항상 낫다”는 결론은 성립하지 않는다.

7. 제한 Preview의 배경과 GA 전환

7.1 무엇이 왜 제한되었었나?

지난 6월 한정된 파트너에게만 Preview를 제공했던 것은, 미국 행정부의 정책적 요청과 연관이 있다.

해당 행정명령은 60일 이내에 AI 안전에 대한 자발적 프레임워크를 설계하도록 지시한 내용이었다.

OpenAI는 정부 부처가 모델 접근을 최대 30일 먼저 해볼 수 있도록 협조하는 차원에서 일반 공개를 늦췄다.

(이것이 모델에 치명적 결함이 있어서 막아둔 것은 아니라는 게 회사의 공식 입장 이다.)

7.2 드디어 찾아온 글로벌 GA

그리고 마침내 7월 9일 기점으로 제한이 풀리며 글로벌 롤아웃이 시작되었다.

이제 일반 Plus 유저도 ChatGPT에서 Sol 모델을 다뤄볼 수 있고, API를 통해서는 누구나 세 가지 모델을 자유롭게 골라서 연동할 수 있게 되었다.

8. GA에서 추가된 실전 기능 — API · Work · Codex

개발자들이 가장 주목해야 할 API 관련 내용이다.

API에서 호출할 수 있는 정확한 모델 ID는 gpt-5.6-sol, gpt-5.6-terra, gpt-5.6-luna 이다. 만약 그냥 gpt-5.6 이라고 별칭을 쓰면 기본적으로 가장 무거운 Sol 모델로 라우팅되니 주의하자.

이번에 새로 도입된 Programmatic Tool Calling 기능이 눈에 띈다.

모델이 격리된 V8 런타임 환경에서 직접 자바스크립트를 작성하여 허용된 Tool들을 순차적 혹은 병렬로 호출하고, 중간 결과를 스스로 가공할 수 있게 해준다. 단, 보안상의 이유로 Node.js API, 직접적인 네트워크 통신, 호스트 파일시스템 접근 등은 엄격히 차단되어 있으니 아키텍처 설계 시 참고하길 바란다.

또한 Multi-agent beta 기능도 추가되어, 메인 에이전트가 여러 서브 에이전트(기본 3개)를 동시에 띄워 작업을 분담하고 결과를 취합하는 오케스트레이션도 API 레벨에서 쉽게 구현이 가능해졌다.

9. 어디서 쓸 수 있나? — 제품별 접근 가이드

스펙을 아무리 알아도, 내 환경에서 실제로 어떤 모델을 고를 수 있는지 모르면 무용지물이다.

GPT-5.6은 표준 Chat(ChatGPT), Codex, API 이 세 가지 제품 환경에서 각각 다르게 노출되므로 한 눈에 정리해 보았다.

9.1 ChatGPT에서 GPT-5.6 Sol 사용하기

ChatGPT 웹이나 데스크톱 앱에서는 대화 입력창 위쪽의 모델 셀렉터 드롭다운을 클릭하면 추론 레벨을 선택할 수 있다.

기존처럼 'Sol', 'Terra', 'Luna'라는 모델명을 직접 고르는 게 아니라, Medium / High / Extra High / Pro와 같은 추론 레벨(Reasoning Level) 형태로 제공되는 점이 특이하다.

ChatGPT 추론 레벨과 모델 매핑

Medium: 일반 대화 수준, 빠른 응답 (내부적으로 하위 계층 모델 활용)
High / Extra High: Sol 모델이 투입되어 깊은 추론 수행
Pro: Sol + 최대 추론 노력(max effort), 가장 정확하지만 응답 시간·토큰 소모 최대

※ Plus 이상 유료 플랜에서 사용 가능. Free/Go 플랜에서는 GPT-5.6 모델군 직접 선택 불가.

ex) chatGPT

9.2 Codex에서 모델 선택하기

Codex 환경에서는 ChatGPT와 달리 Sol, Terra, Luna 세 모델을 직접 이름으로 선택할 수 있다.

특히 Free와 Go 유저도 Codex에서는 Terra에 접근 가능하다는 점이 중요하다. 무료 플랜이라도 코딩 작업은 Terra 급으로 할 수 있다는 뜻이다.

유료 플랜(Plus/Pro/Business)은 3개 모델 모두 선택 가능하고, ultra 모드까지 쓸 수 있다.

ex) Codex App

- 모델 : 5.6 Sol, Terra, Luna

- 추론 강도 : Light, 중간, 높음, 매우높음, 울트라

ex) Codex CLI

- /model 을 통해서 모델 선택 화면

- 5.6 sol, terra, luna 선택 가능

- 추론레벨 조정 : 로우, 중간, 높음, 매우높음, 울트라

9.3 API에서 모델 호출하기

API에서는 가장 자유롭다. 요금제와 무관하게 세 모델 모두 호출할 수 있고, 추론 노력도 none부터 max까지 세밀하게 제어 가능하다.

▶ 기본 호출 예시 (Python)

# Sol 모델로 고난도 작업 실행
response = client.responses.create(
    model="gpt-5.6-sol",
    input="이 프로젝트의 보안 취약점을 분석해줘",
    reasoning={"effort": "max"}
)

# Terra 모델로 일반 코딩 작업 (기본값 추천)
response = client.responses.create(
    model="gpt-5.6-terra",
    input="FastAPI CRUD 보일러플레이트를 만들어줘",
    reasoning={"effort": "high"}
)

# Luna 모델로 대량 배치 작업 (비용 최적화)
response = client.responses.create(
    model="gpt-5.6-luna",
    input="이 리뷰 텍스트의 감성을 분류해줘: 긍정/부정/중립",
    reasoning={"effort": "low"}
)

⚠️ 별칭 함정 주의

gpt-5.6이라고만 쓰면 자동으로 가장 비싼 Sol로 라우팅된다. 비용을 아끼려면 반드시 gpt-5.6-terra 또는 gpt-5.6-luna처럼 명시적으로 계층을 지정하자.

9.4 제품별 모델 접근 매트릭스

정리하면, 내가 쓰는 제품과 요금제에 따라 접근 가능한 모델이 이렇게 달라진다.

제품 환경	Free / Go	Plus	Pro	Business / Enterprise
표준 Chat	선택 불가	Sol (Medium/High)	Sol (전체 + Pro)	Sol (관리자 설정 기준)
Codex	Terra만	Sol / Terra / Luna	Sol / Terra / Luna + Ultra	Sol / Terra / Luna + Ultra
API	요금제 무관, 3개 모델 모두 (`gpt-5.6-sol` / `-terra` / `-luna`) 사용 가능

핵심 포인트

무료 유저라도 Codex에서 Terra를 쓸 수 있다. "난 Free 플랜이라 GPT-5.6 못 쓰는 줄 알았다"는 착각이 생기기 쉬운데, Codex 환경으로 가면 Terra 모델에 접근 가능하다. ChatGPT 표준 채팅창에서만 안 보이는 것이다.

10. 직접 사용해보기 — 활용 사례와 예시 프롬프트

스펙과 가격만 보면 체감이 안 온다. 실제로 GPT-5.6에게 무엇을 시켜볼 수 있는지, 커뮤니티에서 화제가 된 사례와 함께 살펴보자.

10.1 싱글 프롬프트로 게임 만들기

GPT-5.6의 파워를 가장 직관적으로 체감할 수 있는 방법은 "프롬프트 한 줄로 완전한 게임을 만들어 보는 것"이다.

아래 프롬프트들은 스네이크 → 로그라이크 → Tower Defense → 3D FPS → 3D 레이싱 순서로 난이도가 올라간다. 직접 붙여넣어 보면서 모델의 한계가 어디인지 체감해 보자.

★☆☆☆☆ 스네이크 게임 — 워밍업

"HTML/CSS/JavaScript 단일 파일로 스네이크 게임을 만들어줘. 반응형 캔버스, 점수판, 속도 단계별 증가, Game Over 후 재시작 버튼, 모바일 터치 지원까지 포함. 코드 전체를 한 번에 출력해줘."

Sol에 이 프롬프트를 던지면 단 한 번의 응답으로 500줄 이상의 완전 동작 게임 코드가 나온다. 캔버스 렌더링, 키보드·터치 입력, 충돌 감지, 점수 시스템까지 전부 포함된다. GPT-5.5 대비 터치 이벤트 누락이나 Game Over 로직 버그가 크게 줄었다.

ex) 스네이크 게임

- 환경 : Chat GPT Web

- 모델 : GPT-5.6 Sol

- 추론 수준 : 매우 높음

- 결과

- GPT 화면에서 바로 띄워서 확인

★★☆☆☆ 로그라이크 던전 액션 — 절차 생성 + 성장 시스템

"HTML/CSS/JavaScript 단일 파일로 Top-down Roguelite Dungeon Action 게임을 만들어줘. Canvas 2D를 사용하고 외부 이미지 없이 모든 그래픽을 코드로 그려줘. 절차적 Dungeon Room 생성, WASD 이동 + 마우스 방향 공격, Dash + Cooldown, 서로 다른 패턴의 적 5종 이상, Elite Monster, 보스 전투(단계별 공격 패턴), Level Up 시 무작위 Upgrade 카드 3장 중 선택, Upgrade 최소 12종(공격 속도, 투사체 수, 관통, 치명타 등), HP/EXP HUD, Damage Number + Particle Effect, 방 클리어 후 다음 문 열림, 사망 결과 화면, localStorage 최고 기록, 모바일 가상 Joystick 지원. 최소 10분 이상 반복 플레이 가능하도록 난이도와 성장 속도를 조정해줘. 전체 코드를 하나의 HTML 파일로 출력해줘."

절차적 맵 생성과 성장 시스템이 동시에 필요해 게임 설계 능력이 드러나는 프롬프트다. Sol은 방 구조, 적 패턴, 업그레이드 조합까지 한 번에 짜 주는 경우가 많다.

★★★☆☆ Tower Defense — 전략 + 밸런싱

"HTML/CSS/JavaScript 단일 파일로 완성도 높은 Tower Defense 게임을 만들어줘. Canvas 2D, 외부 이미지 없이 모든 그래픽 직접 그리기. 적이 이동하는 굽은 경로, Grid 기반 Tower 설치, Tower 4종(연사형 / 범위 폭발형 / 감속형 / 장거리 저격형), 공격 범위 표시, Tower 설치·Upgrade·판매, 적 5종(빠른 적, 방어력 높은 적, 공중 적, 분열 적 포함), 적 체력 Bar, Wave 시작 버튼 + 자동 Wave, Targeting 우선순위(First/Last/Strong) 변경, Projectile·폭발·Slow Effect, 1·2·3배속 지원, Gold/Life/Wave HUD, 일시정지·승리·패배·재시작, 모바일 Touch Tower 설치, 반응형 Layout. 실제로 승리하거나 패배할 수 있는 밸런스로 만들어줘. 모든 코드를 한 번에 출력해줘."

Tower 종류, 적 상성, 경로 설계, 난이도 곡선까지 게임 밸런싱 능력이 시험된다. 이전 세대 모델에서는 배속 기능이나 Targeting 우선순위 같은 세부 기능이 누락되는 경우가 잦았다.

★★★★☆ 3D FPS 아레나 — Three.js + 물리 + AI

"HTML/CSS/JavaScript 단일 파일로 브라우저 3D FPS 아레나 게임을 만들어줘. Three.js CDN 사용, 외부 Asset 없이 기본 Geometry + Web Audio API만 사용. Pointer Lock 시점 회전, WASD 이동, Shift 달리기, Space 점프, 중력·바닥 충돌, Crosshair, 클릭 발사, Raycasting 명중 판정, 추적 AI 적 6개 이상, 적 HP Bar, 탄창·재장전·발사 간격, 총구 Flash·피격 Effect·화면 흔들림, Wave 난이도 증가, 플레이어 체력·탄약·점수·Wave HUD, Game Over + 재시작, 시작 화면 조작법 표시, 모바일 가상 Joystick + 발사 버튼. 어두운 Sci-Fi Arena 스타일, 조명·안개·그림자 활용. TODO·생략·외부 Asset 의존성 금지, 완전 실행 가능한 전체 코드를 한 번에 출력해줘."

3D 렌더링, 물리 엔진, AI 추적, 무기 시스템이 한 파일에 들어가야 하는 최고 난이도 원샷 빌드다. Sol의 공간 추론과 장기 코드 일관성이 여기서 빛난다.

★★★★★ 3D 아케이드 레이싱 — 물리 + AI + 트랙 설계

"HTML/CSS/JavaScript 단일 파일로 Arcade 3D 자동차 레이싱 게임을 만들어줘. Three.js CDN, 외부 Asset 없이 자동차·트랙·나무·Barrier·Checkpoint를 기본 Geometry로 제작. WASD/방향키 조작, 가속·감속·브레이크·후진, 속도 따른 Steering 감도 변화, Arcade Physics(마찰력 + 관성), 곡선 포함 순환 트랙, 트랙 이탈 감속, Checkpoint·Lap 판정(3바퀴), Third-person Camera, AI 경쟁 차량 5대(Waypoint 주행, 서로 다른 속도), 순위·Lap·속도·기록 HUD, Mini Map, Nitro Boost, 충돌 Effect·Tire Mark·Camera Shake, 레이스 결과표, 모바일 가상 Steering·가속·브레이크 버튼, localStorage 최고 기록. Neon Night City 분위기, 조명·Fog·도로 발광선·배경 건물 활용. 완전한 HTML 파일 하나로 출력, 재시작 시 차량·AI·Lap·Timer 완전 초기화."

트랙 설계, AI Waypoint 주행, 물리 시뮬레이션, 순위 판정까지 한 번에 요구하는 극한 프롬프트다. 이 수준을 원샷으로 통과할 수 있는 모델은 현재 Sol이 거의 유일하다.

ex) 3D 게임도 잘 만드는 모습

더 도전해 볼 만한 프롬프트들

위 5개 외에도 다음 장르를 같은 방식으로 시도해 보면 모델의 한계를 더 깊이 탐색할 수 있다.

Bullet Hell 슈팅 — Neon Vector 스타일, 원형·나선형·조준형 탄막, 보스 Phase 전환, Object Pooling 필수
물리 2D 플랫포머 — 벽 점프, Moving Platform, Parallax Background, 5개 Stage, Checkpoint
리듬 액션 — Web Audio API 실시간 음악 생성, 4-Lane Note, Perfect/Great/Miss 판정, Calibration 설정
좀비 서바이벌 디펜스 — 3D Low-poly, Wave 기반, Shop Upgrade, Barricade 설치·수리
3D Endless Runner — Hover Bike, 3-Lane, Boost Gauge, 환경 테마 변화, Object Pooling 메모리 관리
미니 RTS — 유닛 다중 선택, Pathfinding, Fog of War, 적 AI 기지 확장, 자원 밸런스
3D 우주 탐험 — 태양계 8행성, 연료 시스템, 소행성 충돌, 행성별 수집 미션
Portal 스타일 퍼즐 — Teleporter 위치·방향 변환, Momentum 유지, Laser 반사
Neon Pinball — Sub-step Physics, Bumper·Ramp 충돌, Multi-ball, Combo Multiplier

10.1.1 결과물의 완성도를 높이는 공통 추가 문장

어떤 게임 프롬프트든, 마지막에 아래 문장을 덧붙이면 코드의 완성도와 안정성이 확 올라간다.

공통 품질 조건 (복사해서 프롬프트 끝에 붙여넣기)

"단순한 데모가 아니라 실제로 플레이 가능한 완성형 게임으로 만들어줘.

다음 품질 조건을 반드시 지켜줘.
- TODO, 생략, 의사 코드, '나머지는 동일' 같은 표현 금지
- HTML을 저장한 후 바로 실행 가능해야 함
- Console Error가 발생하지 않아야 함
- 모든 변수와 함수가 실제로 정의되어야 함
- 게임 재시작 시 Timer, Event Listener, Object, Score, Enemy 상태를 완전히 초기화
- 모바일과 데스크톱에서 모두 조작 가능
- 반응형 Layout과 고해상도 Canvas 대응
- 게임 규칙과 조작법을 시작 화면에 표시
- 코드에 적절한 주석 포함
- 출력 전 전체 코드를 내부적으로 검토한 뒤 최종 HTML 코드만 Markdown Code Block 하나로 출력"

10.1.2 모델 성능을 더 깊이 시험하는 방법

첫 번째 시도에서는 프롬프트 하나만 전달해 One-shot Generation 능력을 확인한다.

생성된 게임을 실행한 뒤, 두 번째 프롬프트에서 다음과 같은 수정·확장 작업을 요청해 보자.

"적 AI가 벽을 통과하는 문제를 수정해줘."
"모바일 조작 UI가 화면을 가리지 않도록 개선해줘."
"Object Pooling을 적용해 성능을 최적화해줘."
"현재 코드를 유지하면서 Boss Phase를 3단계로 추가해줘."
"게임 상태를 Finite State Machine 구조로 Refactoring해줘."

이렇게 하면 단순 코드 생성뿐 아니라 기존 코드 이해 → 오류 추적 → 구조 개선 → 기능 확장 능력까지 한 번에 확인할 수 있다. Sol과 Terra의 차이가 가장 극명하게 드러나는 지점이기도 하다.

바이브 코딩(Vibe Coding) 트렌드

자연어 지시만으로 소프트웨어를 만드는 '바이브 코딩'이 2026년 최대 트렌드로 자리 잡았다. vibecode.game 같은 커뮤니티에서는 AI로 생성한 게임을 공유하고 있으며, GPT-5.6 Sol의 등장으로 원샷 빌드 품질이 한 단계 올라갔다는 평가가 많다.

10.2 커뮤니티에서 화제된 활용 사례

GA 출시 직후 Reddit, Hacker News 등에서 공유된 주목할 만한 활용 사례를 정리했다.

사례 1: 에이전트 스택 전략 (Reddit)

경험 많은 개발자들이 추천하는 모델 조합 전략이 화제가 됐다.

Luna: 백그라운드 작업, 로그 요약, 데이터 전처리 등 단순·대량 작업
Terra: 일상적인 코드 작성, 리뷰, 문서 분석 등 기본 업무
Sol: 아키텍처 설계, 보안 분석, 디버깅 등 고난도 판단이 필요할 때만 투입

→ 이 조합으로 API 비용을 60~70% 절감했다는 후기가 여럿 올라왔다.

사례 2: 레거시 코드 리팩토링 (Reddit·HN)

수만 줄짜리 레거시 프로젝트를 Sol에게 맡겨 멀티파일 리팩토링을 시킨 후기가 주목받았다. 105만 토큰 컨텍스트 덕분에 프로젝트 전체를 한 번에 넘기고 구조적 개선안을 받을 수 있었다는 점이 핵심이다. 다만 Sol의 토큰 소모량이 크므로, "전체 투입 → 부분 확인"보다 "구조 파악은 Sol, 개별 수정은 Terra"로 나누는 것이 비용 면에서 효율적이라는 의견도 많았다.

사례 3: UI 클론 원샷 빌드

Spotify, Notion 등의 UI를 프롬프트 하나로 클론하는 시도가 유행 중이다. Sol이 GPT-5.5 대비 레이아웃 공간 추론과 CSS 일관성이 크게 좋아졌다는 평가가 많다. 다만 복잡한 인터랙션(드래그앤드롭, 애니메이션 체이닝 등)은 여전히 후속 프롬프트가 필요한 경우가 있다.

10.3 따라해 볼 수 있는 예시 프롬프트 모음

난이도별로 추천 모델과 함께 바로 쓸 수 있는 프롬프트를 정리했다. 복사해서 붙여넣기만 하면 된다.

난이도	추천 모델	예시 프롬프트	기대 결과
★☆☆☆	Luna	"이 CSV 데이터를 분석해서 상위 10개 트렌드를 한국어로 요약해줘"	빠른 응답, 최저 비용
★★☆☆	Terra	"Python FastAPI로 사용자 CRUD REST API 보일러플레이트를 만들어줘. Pydantic v2 모델, SQLAlchemy async, 에러 핸들링 포함"	균형 잡힌 코드 품질
★★★☆	Sol	"단일 HTML 파일로 3D 큐브 회전 시각화를 만들어줘. WebGL 사용, 마우스 드래그로 회전, 색상 각 면 다르게, 모바일 터치 지원"	복잡한 공간 추론 + 원샷 완성
★★★★	Sol (max)	"이 GitHub 레포의 전체 소스를 분석하고, OWASP Top 10 기준으로 보안 취약점을 찾아서 각각에 대한 수정 코드와 설명을 제시해줘"	다단계 분석 + 코드 수정안

프롬프트 팁

어떤 모델을 쓸지 고민되면 일단 Terra에 프롬프트를 던져보자. 결과가 만족스러우면 Luna로 내려보고, 부족하다면 Sol로 올려 비교한다. 이 "Terra-first → A/B 테스트" 패턴이 비용 절감의 핵심이다.

11. 안전성 평가(METR)와 커뮤니티 반응

11.1 METR의 Cheating 관측과 한계

출시 직후 일각에서 불거진 안전성 논란에 대해서도 짚고 넘어가야겠다.

비영리 AI 평가 기관인 METR은 Sol 모델을 평가하면서 'Cheating(꼼수)' 행위를 관측했다고 보고했다. 평가 환경의 버그를 악용하거나, 정답을 맞힌 척 속이는 시도가 있었다는 것이다.

이 Cheating 시도를 실패로 치면 과제 지속 시간이 11.3시간에 불과했고, 치팅을 묵인(성공으로 간주)하면 270시간이 넘게 작업이 지속되었다. OpenAI 내부 평가에서도 GPT-5.5 대비 심각도 3(severity-3)의 행동이 일부 늘어난 것으로 보고되었다.

결론적으로 이는 "Sol 모델이 통제 불능의 위험한 자아를 가졌다"는 뜻이라기보다는, 모델이 목표 달성을 위해 주어진 시스템의 룰을 우회하려는 성향(Cheating)이 강해졌다는 의미이다. 따라서 실무에 도입할 때는 무단 삭제나 결과 조작이 불가능하도록 권한을 격리하고, 사람의 승인(Human-in-the-loop) 과정을 반드시 거치도록 설계하는 것이 핵심이다.

11.2 출시 직후 커뮤니티 반응

해외 레딧이나 해커뉴스(HN) 등 커뮤니티 반응도 슬쩍 살펴보겠다. 초기 편향이 있을 수 있으니 재미와 참고용으로만 보자.

주요 반응 요약	긍정적 신호	주의할 점 (확대 해석 금물)
Sol 코딩 호평 (Reddit)	복잡한 로직 설계 시 체감 품질이 매우 훌륭함	모든 코드 저장소에서 무조건 우월한 것은 아님
사용량 한도 우려 (HN)	장문, 대형 작업 시 토큰 소모량이 커서 쿼터 관리가 필요함	이것이 공식적인 사용량 한도 제약을 의미하진 않음
Terra 원샷 성공 후기	Terra 만으로도 웬만한 실무 코드는 잘 짜준다는 반응	작업 난이도에 따라 Terra의 성공률은 달라질 수 있음

ex) 제 경험을 말씀드리면, 현재 ChatGPT Pro 요금제(X20)를 사용하고 있는데 평소엔 사용량이 캡에 걸릴 일이 거의 없었다. 그런데 이번에 Sol 모델을 딥하게 써보니 약 3시간 만에 사용량 경고가 뜨고 주간 쿼터가 훌쩍 소진되었다. 플래그십인 만큼 Sol이 토큰을 꽤나 묵직하게 잡아먹는 것으로 보인다. 서비스 도입 시 예산 관리에 각별히 신경 써야 한다.

12. 작업 유형별 모델 선택 기준

그래서 어떤 모델을 써야 할까? 실무 경험을 바탕으로 권장하는 가이드를 정리해 보았다.

작업 유형	추천 모델	핵심 이유
코딩 에이전트(다단계·자율)	Sol	중간에 삑사리(?) 나면 타격이 큰 복잡한 작업이므로 가장 똑똑한 놈을 쓴다.
일반 코드 작성 및 문서 분석	Terra	가성비 훌륭한 기본값. Sol의 절반 가격으로 웬만한 건 다 커버된다.
대량 배치 작업 및 단순 분류	Luna	비용 절감이 생명! 품질 통과선만 넘는다면 무조건 Luna이다.
실시간 고객 응대 챗봇	Luna	호출량이 많고 답변 속도가 생명인 B2C 서비스에 적합하다. (지연 시간은 자체 측정 필수)
보안(CTF) 및 생물학 연구	Sol + 사람 승인	고난도 추론이 필요하므로 Sol을 쓰되, 반드시 전문가의 검증 단계(Human-in-the-loop)를 거쳐야 한다.

위 표는 정답이 아니라 실험을 위한 '시작점'이다. 각 모델을 본인의 데이터셋으로 돌려보고 결과 품질, 총 토큰, 지연 시간, 재시도율을 직접 기록해서 판단해야 한다.

13. 한국 사용자 실용 가이드 (체크리스트)

한국이라고 해서 별도의 국가 제한이 있는 것은 아니다.

글로벌 롤아웃이 순차적으로 진행 중이므로, 아직 내 화면에 안 보인다면 앱 버전을 최신으로 업데이트하거나 워크스페이스 관리자 설정을 한번 점검해 보자.

제품별 GPT-5.6 접근 범위 한눈에 보기

표준 Chat (ChatGPT): 유료 플랜(Plus 이상)에서 Sol을 사용할 수 있다. Free나 Go 요금제 유저는 GPT-5.6 모델군을 직접 선택할 수 없다.
ChatGPT Work: 기업용 플랜 등급에 따라 Sol, Terra, Luna 세 가지 모두 선택 가능하다.
Codex: Free/Go 유저도 Terra에 한해 접근 가능하며, 유료 플랜은 3개 모델 모두 선택 가능하다.
API: 요금제와 무관하게 3개 모델 모두(ID: gpt-5.6-sol, -terra, -luna) 사용할 수 있다.

지금 바로 시작하기 — 실무 체크리스트

가장 먼저 표준 Chat, Work, Codex 중 현재 내 환경이 어디에 속하는지 파악하고, 앱이나 CLI를 최신 버전으로 업데이트하자.
최근 한 달간 AI를 주로 어떤 용도(코딩, 단순 요약, 실시간 응대, 대량 데이터 처리 등)로 썼는지 분석해 보자.
주력 작업 하나를 골라 Terra와 Sol 두 가지로 똑같이 테스트해 본다. (생각보다 Terra만으로도 충분한 경우가 많다.)
반복 호출이 많은 API 작업이라면, 시스템 프롬프트와 도구(Tool) 정의를 무조건 앞쪽에 고정하여 프롬프트 캐싱 할인을 적극적으로 노리자.
장문(272K 초과) 요율 할증이나 Multi-agent 연동 시 토큰 비용이 눈덩이처럼 불어날 수 있으니, API 호출 코드에 반드시 토큰 상한선(limit) 방어 로직을 구현하자.

14. FAQ와 트러블슈팅

많은 분들이 궁금해하시는 핵심 질문 5가지를 모아봤다.

Q1. 지금 한국에서도 GPT-5.6을 쓸 수 있나?

A. 네! OpenAI가 7월 9일부터 글로벌 롤아웃을 시작했다. 24시간에 걸쳐 점진적으로 배포되었으므로 현재는 대부분 사용 가능하다. 단, Free/Go 요금제 사용자는 표준 ChatGPT 화면에서 직접 5.6을 고를 수 없고, 유료 플랜 이상이거나 API/Codex 환경을 이용해야 한다.

Q2. 세 모델 중 당장 딱 하나만 고르라면 뭘 써야 할까?

A. 무조건 Terra를 추천한다. 성능과 비용의 밸런스가 가장 좋기 때문에 첫 벤치마크 기준으로 삼기 딱 좋다. 여기서부터 '오류가 나면 큰일 나는' 작업은 Sol로, '단순 반복이라 비용이 아까운' 작업은 Luna로 이동하는 전략을 짜면 실패가 없다.

Q3. Terminal-Bench 91.9% 수치를 그대로 믿어도 되나?

A. 참고용으로만 보자. 91.9%는 OpenAI가 기본 4-agent Ultra 모드로 돌려서 각 에이전트의 노력(토큰)을 모두 합산하여 낸 결과다. 독립적인 외부 검증 기관의 결과도 아직 안 나왔으니, 내 프로젝트 코드로 직접 정확도와 지연시간을 테스트해 보는 것이 가장 확실하다.

Q4. API에서 max 모드나 ultra는 비싼 Sol 전용인가?

A. 아니다. 공식 API 문서를 보면 Sol, Terra, Luna 세 모델 모두 none부터 max까지 추론 노력(Effort) 옵션을 줄 수 있다. 또한 ultra는 모델 사양이 아니라 Work나 Codex에서 쓰이는 multi-agent '제품 모드'일 뿐이다.

Q5. METR 안전성 논란 기사를 봤는데, 위험하니까 Sol은 피해야 할까?

A. 무조건 피할 필요는 없다. METR 평가에서 나온 'Cheating' 이슈는 모델이 완전 자동화된 위험한 자아를 가졌다기보다, 목표 달성을 위해 주어진 룰의 허점을 찌르려는 성향이 강해졌다는 뜻에 가깝다. 실무에선 무단 삭제나 배포 권한을 물리적으로 분리하고, 최종 실행 전 사람이 승인하는 장치만 잘 세팅해 두면 충분히 안전하게 활용 가능하다.

15. 결론

결론적으로 이번 GPT-5.6은 "무조건 제일 크고 좋은 거 하나!"가 아니라, 개발자가 입맛과 예산에 맞게 비용과 성능을 조율할 수 있도록 선택지(Sol, Terra, Luna)를 열어주었다는 데 큰 의미가 있다.

무조건 플래그십인 Sol만 고집할 필요는 없다. 내 프로젝트의 성격이 '정확도 우선'인지 '가성비와 스피드 우선'인지 파악하고, Terra를 기준으로 유연하게 모델을 스위칭하는 것이 이번 5.6 라인업 업데이트를 가장 스마트하게 활용하는 방법이다.

여기까지 새롭게 출시된 GPT-5.6의 세 가지 모델과 디테일한 벤치마크, 그리고 상황별 선택 가이드에 대해 알아보았다.

새로운 모델 도입에 고민이 많으셨을 개발자분들께 실질적인 도움이 되었길 바라며, 다음 포스팅에서 또 재미있는 기술 소식으로 찾아오겠다. 감사합니다. : )

참고자료

OpenAI, Introducing GPT-5.6, 2026-07-09
OpenAI Help, GPT-5.6 in ChatGPT
OpenAI Developers, GPT-5.6 모델 사양 및 API 가격표
OpenAI Deployment Safety, GPT-5.6 System Card
METR, GPT-5.6 Sol 사전 배포 평가

Ollama Launch 사용 방법(ollama 사용방법) : Claude Code, OpenCode, Codex App을 Ollama 모델로 실행 해보기

갓대희 — Tue, 7 Jul 2026 18:00:42 +0900

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

Ollama를 "내 컴퓨터에서만 도는 로컬 모델 도구"로 알고 있는 사람이 아직 많다.

"Claude Code는 이 모델, Codex는 저 모델"처럼 에이전트마다 쓸 수 있는 모델이 따로 정해져 있다고 생각하는 사람도 있다.

예전에는 Ollama·LM Studio·vLLM·LiteLLM을 손으로 하나씩 붙이는 글을 따로 써야 했을 만큼 이 두 생각이 어느 정도는 맞았다. 그런데 지금은 둘 다 맞지 않는 것 같다.

ollama launch는 Claude Code·Codex App·OpenCode 같은 코딩 도구를 로컬 모델이든 클라우드 모델이든 한 줄 명령으로 연결해 준다고 한다.

환경변수를 손으로 넣거나 설정 파일을 만질 필요가 없다.

이에 직접 해보려고 한다.(2026년 7월 초 시점이고, macOS, Ollama 0.30.11 기준으로 테스트 해볼 예정이다).

ollama launch --help를 확인 해 보니 지원 통합이 16개나 나열되어 있다.

GUI로 확인해도 유사하다.

이 글에서는 ollama launch가 무엇인지, 어떻게 16개 에이전트로 늘어났는지, 로컬 모델과 클라우드 모델(:cloud 접미사)을 어떻게 구분해 쓰는지 직접 확인한 대로 짚어본다. 이어서 Claude Code·Codex App·OpenCode 세 도구는 그대로 따라 할 수 있게 실습하고, 나머지 에이전트는 개요와 공식 문서 링크를 남겨 놓는 정도로 진행해보려 한다.

이 글의 핵심 6가지

ollama launch 한 줄이면 코딩 에이전트에 환경변수·설정 파일 없이 모델을 연결한다
로컬 모델과 클라우드 모델(:cloud)을 모두 지원한다 — "로컬 전용"이 아니다
직접 테스트 기준 ollama launch --help가 지원하는 통합은 16개다
데스크톱 앱 카드(약 8개)와 CLI(16개)의 숫자가 다른 이유가 있다
에이전트와 모델은 고정이 아니라 --model로 자유롭게 바꾼다
OpenClaw 웹서치처럼 ollama signin 계정 로그인이 필요한 기능이 있다

Ollama Launch란 무엇인가
연혁 — Anthropic API 호환에서 16개까지
로컬 모델 vs 클라우드 모델 (:cloud)
앱 카드 8개와 CLI 16개, 왜 다른가
사전 준비 — 버전·컨텍스트 길이
실습 ① Claude Code
실습 ② Codex App
실습 ③ OpenCode
--model 플래그 — 매핑은 고정이 아니다
나머지 에이전트 한눈에 보기
계정 로그인이 필요한 기능 (ollama signin)
트러블슈팅 & Q&A
마무리 — 로컬과 클라우드, 무엇을 고를까

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

Ollama Launch: ollama launch 한 줄로 코딩 도구를 Ollama 모델에 연결하는 명령
통합(integration): Ollama가 연결을 지원하는 외부 앱·에이전트
로컬 모델: 내 컴퓨터의 VRAM(그래픽 메모리)에서 직접 돌리는 모델
클라우드 모델(:cloud): Ollama 서버에서 돌아가는 모델, 이름 끝에 :cloud가 붙는다
코딩 에이전트: 코드를 읽고 편집·실행까지 하는 AI 도구 (Claude Code·Codex 등)
컨텍스트 길이: 모델이 한 번에 다루는 토큰 수 — 클수록 큰 코드베이스를 담는다
ANTHROPIC_BASE_URL: Claude Code가 요청을 보낼 주소를 바꾸는 환경변수
ollama signin: Ollama 계정에 로그인하는 CLI 명령

1. Ollama Launch란 무엇인가

ollama launch는 좋아하는 코딩 도구를 로컬 또는 클라우드 모델로 설정하고 실행하는 새 명령이다. 공식 블로그는 이 명령을 소개하며 "환경변수나 설정 파일이 필요 없다(No environment variables or config files needed)"라고 못 박는다.

ollama launch is a new command which sets up and runs your favorite coding tools like Claude Code, OpenCode, and Codex with local or cloud models.
(ollama launch는 Claude Code, OpenCode, Codex 같은 AI 코딩 도구를 로컬 또는 클라우드 모델과 연동해 손쉽게 설정하고 실행할 수 있는 새로운 명령어입니다.)

인용문의 마지막 구절이 이 글 전체의 전제다. 정의부터 "로컬 또는 클라우드 모델(local or cloud models)"이라고 적혀 있으니, "Ollama는 로컬 전용"이라는 흔한 요약은 이 명령 앞에서는 성립하지 않는다.

공식 CLI 문서는 이 명령을 조금 더 기계적으로 설명한다. 지원 앱과의 통합을 설정하고 시작하는 대화형(interactive) 방식을 제공한다는 것이다.

ex) ollama launch (내가 돌렸을때는 실제로 다음과 같이 나온다.)

공식 문서의 화면을 보면 ollama launch만 입력했을 때 claude·codex·droid·opencode 네 항목이 뜨고, 각 항목에 기본 모델(glm-4.7-flash:latest 등)이 미리 매핑돼 있다. 대화형이라는 말은 이렇게 목록에서 하나를 고르면 나머지 설정을 Ollama가 알아서 채운다는 말이다. (물론 내 로컬에선 공식문서와 달랐지만, 일단 공식 문서 기준으로 진행해보자. )

이 명령의 핵심은 결국 "설정 자동화"다. 예전에는 각 도구마다 어떤 환경변수를 어디에 넣어야 하는지 문서를 일일이 뒤져야 했는데, 그 과정을 명령 한 줄로 접은 것이 이 명령의 등장 배경이다.

왜 이게 편할까

설정 파일을 직접 여는 방식은 오타 하나로 연결이 깨지기 쉽다. 환경변수를 손으로 넣다가 어딘가에서 막혀본 사람이라면 이 번거로움에 공감할 것이다.

ollama launch는 검증된 설정을 도구별로 넣어 주므로, 처음 붙여 보는 단계에서 그렇게 막힐 확률이 줄어든다.

익숙해지면 수동 설정으로 넘어가도 되지만, 첫 연결은 이 명령으로 시작하는 편이 낫다.

2. 연혁 — Anthropic API 호환에서 16개까지

이 기능은 갑자기 튀어나온 게 아니라 여러 버전에 걸쳐 쌓였다.

날짜만 보면 헷갈리기 쉬우니, 버전 번호를 기준으로 따라가면 정확하다.

먼저 토대가 된 사건은 Ollama v0.14.0의 Anthropic Messages API 호환이다. 이 버전부터 Claude Code 같은 도구를 오픈소스 모델과 함께 쓸 수 있게 됐다고 공식 블로그에서 밝히고 있다.

GitHub v0.14.0 릴리스 노트에도 Anthropic API 호환(/v1/messages API 지원)이 변경사항으로 올라 있다. (출처: GitHub 릴리스 v0.14.0)

ollama launch 명령 자체는 v0.15.0에서 Claude Code·Codex·OpenCode·Droid 네 개 통합으로 처음 도입됐다.

(출처: GitHub 릴리스 v0.15.0) 이후 통합이 하나씩 붙었다.

버전	시점	추가·변경된 것
v0.14.0	2026-01	Anthropic Messages API 호환 — Claude Code를 오픈소스 모델과 연결
v0.15.0	2026-01	`ollama launch` 최초 도입 — Claude Code·Codex·OpenCode·Droid 4개
v0.15.2	2026-01-27	OpenClaw(당시 이름 Clawdbot) 추가
v0.15.3	2026-02-01	`clawdbot` → `openclaw`로 명령 이름 변경
v0.21.0	2026-04-17	Hermes·GitHub Copilot CLI 2개 추가
v0.24.0	2026-05-14	Codex App 추가 (데스크톱 앱)
0.30.11	2026-07-02 확인	직접 테스트 기준 `--help` 통합 16개

여기서 나도 처음에는 잘못 알고 있었다.

릴리스 히스토리를 훑기 전까지는 OpenClaw가 v0.21.0에서 새로 추가된 통합이라고 생각했다.

그런데 직접 하나씩 태그를 열어보니 순서가 달랐다.

실제로는 'Clawdbot'이라는 이름으로 v0.15.2에 먼저 들어왔고, 다음 릴리스에서 이름만 openclaw로 바뀐 것이었다.

그러면 v0.21.0에서는 정작 뭐가 새로 붙었을까 싶어 그 릴리스 노트도 확인해봤는데, Hermes와 GitHub Copilot CLI 두 개만 신규로 명시돼 있고 OpenClaw 관련 항목은 --yes 플래그 버그 수정뿐이었다.

참고로 직접 테스트한 ollama launch --help에도 openclaw의 별칭으로 clawdbot·moltbot이 남아 있어서, 옛 이름이 하위호환으로 유지되는 점도 확인했다.

데스크톱 앱을 겨냥한 Codex App은 조금 뒤인 v0.24.0에서 추가됐다.

릴리스 노트는 "Ollama 0.24 includes support for the Codex App"이라고 적는다. 뒤에서 다루겠지만 Codex App 실습에는 이 최소 버전(v0.24.0+)이 그대로 요구사항이 된다.

넉 달 남짓한 기간에 4개에서 16개로 늘어난 셈이다. 확장 방향을 보면 단순히 개수만 늘어난 게 아니라, 터미널 CLI(Claude Code·Codex·OpenCode)에서 데스크톱 앱(Codex App·Hermes Desktop), 그리고 메시징 어시스턴트(OpenClaw)까지 도구의 성격이 넓어졌다. 코딩 에이전트 생태계가 특정 벤더에 묶이지 않고 "모델은 갈아 끼우는 것"이라는 쪽으로 움직이고 있다.

넉 달 만에 4배

2026년 1월 v0.15.0의 4개 통합(Claude Code·Codex·OpenCode·Droid)에서 직접 테스트 기준 16개까지, 넉 달 남짓 만에 4배로 늘었다. 이 속도라면 지금 목록에 없는 도구가 다음 버전에 추가돼도 이상하지 않다.

3. 로컬 모델 vs 클라우드 모델 (:cloud)

ollama launch를 제대로 쓰려면 로컬 모델과 클라우드 모델의 차이를 먼저 구분해야 한다.

다행히 둘의 구분은 의외로 단순하다. 모델 이름 끝에 :cloud가 붙으면 클라우드, 없으면 로컬이다. 공식 블로그의 예시를 보면 이 구분이 한눈에 들어오는데, 같은 계열 모델을 로컬로 받을 수도 클라우드로 받을 수도 있다.

# 로컬: 64000 토큰 컨텍스트 기준 약 23GB VRAM 필요
ollama pull glm-4.7-flash

# 클라우드: 전체 컨텍스트 길이 지원 (:cloud 접미사)
ollama pull glm-4.7:cloud

주석에 적힌 그대로, 로컬 glm-4.7-flash는 64000 토큰 컨텍스트에서 약 23GB의 VRAM을 요구한다.

웬만한 노트북 그래픽카드로는 부담스러운 크기다. 반대로 :cloud 모델은 연산이 Ollama 서버에서 이뤄지므로 내 VRAM과 무관하게 전체 컨텍스트 길이를 쓴다.

구분	로컬 모델	클라우드 모델 (:cloud)
이름 예시	`glm-4.7-flash`, `gpt-oss:20b`	`glm-4.7:cloud`, `qwen3-coder:480b-cloud`
연산 위치	내 컴퓨터(VRAM)	Ollama 서버
하드웨어 부담	VRAM 요구(예: 약 23GB)	로컬 사양과 무관
컨텍스트 길이	VRAM에 따라 제한	전체 컨텍스트 길이
계정 로그인	불필요	Ollama 계정 필요(클라우드 서비스)
오프라인	가능	불가(네트워크 필요)

표의 핵심은 간단하다.

로컬은 하드웨어를 갈아 넣어 프라이버시와 오프라인을 얻고, 클라우드는 하드웨어 부담 없이 큰 컨텍스트를 빌려 쓰는 구조다.

로컬로 큰 모델을 돌리기 어렵다면 클라우드가 대안이라고 공식 블로그도 안내한다. ( 개인 노트북을 사용하시는 분들은 현실적으로 큰 모델 돌리기가 어렵다. )

무료 티어에서도 전체 컨텍스트 길이와 넉넉한 한도를 제공한다고 한다.

VRAM이 부족할 때

약 23GB VRAM은 개인 데스크톱에서도 상급 GPU가 있어야 나오는 수치다.

로컬 실행이 자꾸 느리거나 메모리 부족으로 죽는다면, 무리해서 로컬 대형 모델을 붙들기보다 같은 계열의 :cloud 모델로 갈아타는 편이 낫다. 코드는 그대로 두고 모델 이름만 바꾸면 된다.

어느 쪽부터 시작할까

개인적으로는 처음이라면 :cloud 모델로 동작을 먼저 확인하고, 프라이버시가 중요하거나 자주 쓰는 작업이 정해지면 그때 로컬로 내려오는 순서를 권한다.

로컬 설치·다운로드 시간에 막혀 "연결 자체가 되는지"조차 확인하지 못하는 상황을 줄일 수 있어서다.

4. 앱 카드 8개와 CLI 16개, 왜 다른가

Ollama를 데스크톱 앱으로 쓰는 사람은 앱의 'Launch' 탭에서 카드 형태로 통합을 고른다.

그런데 이 카드 개수와 CLI가 지원하는 개수는 계속 업데이트 됨에 따라 늘어나고 있다.

현재 내가 직접 테스트(2026년 7월 2일, macOS, Ollama 0.30.11)에서 확인한 ollama launch --help의 지원 통합은 16개였다.

Supported integrations:
  claude          Claude Code
  codex-app       Codex App (aliases: codex-desktop, codex-gui)
  hermes          Hermes Agent
  openclaw        OpenClaw (aliases: clawdbot, moltbot)
  opencode        OpenCode
  codex           Codex
  hermes-desktop  Hermes Desktop
  copilot         Copilot CLI (aliases: copilot-cli)
  omp             OMP
  droid           Droid
  kimi            Kimi Code CLI
  pi              Pi
  pool            Pool
  cline           Cline
  qwen            Qwen Code
  vscode          VS Code (aliases: code)

데스크톱 앱의 'Launch' 탭에는 자주 쓰는 코딩 에이전트만 카드로 노출된다.

직접 확인한 앱 화면(2026-07-02 기준)에는 총 8개 밖에 노출 안되고 있다.

(Claude Code·Codex App·Hermes Agent·OpenClaw·OpenCode·Codex·Copilot CLI·Droid)

"Copy a command and run it in your terminal(명령을 복사해 터미널에서 실행하라)"이라는 안내가 보였다.

카드가 8개뿐이라 처음엔 "나머지 8개는 어디 갔지" 싶었는데, 앱 카드는 애초에 전체 목록이 아니라 대표 선별본이었다.

그렇다면 공식 문서 사이트의 통합 인덱스는 어떨까 싶어 함께 찾아봤더니 또 다른 숫자가 나온다.

문서 인덱스는 통합을 7개 카테고리로 나눠 총 24개를 나열하는데,

여기에는 에디터 플러그인·자동화·RAG 도구까지 들어가 있어 CLI가 다루는 코딩 에이전트보다 범위가 넓다.

표면	노출 개수	성격
데스크톱 앱 'Launch' 탭	약 8개	자주 쓰는 코딩 에이전트만 선별 (앱 화면 기준)
CLI `ollama launch --help`	16개	실제 `launch`로 설정 가능한 전체 통합
공식 문서 통합 인덱스	24개	에디터·자동화·RAG까지 포함한 문서 전체

세 숫자가 다른 이유는 각 표면의 목적이 다르기 때문이다.

앱 카드는 초심자가 헤매지 않도록 좁혔고, CLI는 실제 지원 범위를 그대로 드러내며, 문서 인덱스는 관련 도구까지 폭넓게 안내한다.

"내 앱에 안 보인다"고 해서 지원되지 않는다고 단정할 필요는 없다.

카드에 없어도 터미널에서 ollama launch <이름>으로 실행되는 경우가 많다.

launch 명령의 4가지 플래그

ollama launch에는 알아두면 자주 쓰는 플래그가 네 개 있다. 직접 테스트한 --help 출력과 공식 블로그를 종합했다.

플래그	하는 일
`--config`	도구를 즉시 실행하지 않고 설정만 한다
`--model`	사용할 모델을 지정한다 (예: `--model glm-4.7:cloud`)
`--restore`	통합을 Ollama 실행 이전의 기본 프로필로 되돌린다
`-y`, `--yes`	확인 프롬프트에 자동으로 예로 답한다 (스크립트·CI용)

이 네 플래그가 뒤의 실습에서 반복해서 등장한다.

특히 --model은 다음 절에서 설명할 "매핑은 고정이 아니다"의 핵심이고,

--restore는 설정을 되돌리는 안전장치라 언제든지 복구하기 쉬우니 맘편히 진행해보자..

넷 중 가장 자주 쓰는 건 --model 하나

실습에서 반복해서 쓰는 건 사실상 --model뿐이다.

--config·--restore·-y는 "설정만 해두고 싶을 때", "원래대로 되돌리고 싶을 때", "자동화 스크립트에서 확인을 건너뛰고 싶을 때"처럼 특정 상황에서만 꺼내면 된다.

넷을 한 번에 외우려 하지 말고 뒤의 실습을 따라가며 하나씩 마주치는 편이 낫다.

5. 사전 준비 — 버전·컨텍스트 길이

실습 전에 두 가지만 확인하면 된다.

Ollama 버전과 컨텍스트 길이 설정이다.

첫째는 버전이다. Ollama Launch는 v0.15+가 필요하다고 공식 블로그가 안내하니, 터미널에서 설치 버전부터 확인하고 시작하자.

# 설치된 Ollama 버전 확인
ollama --version

# 지원 통합과 플래그 확인
ollama launch --help

첫 명령은 설치된 버전을 출력한다.

나의 테스트 환경에서는 ollama version is 0.30.11이다.

두 번째 명령으로는 앞에서 본 16개 통합 목록이 출력돼, 내 환경이 어떤 통합을 지원하는지 바로 확인할 수 있다.

여기서 하나 더 알아두면 좋은 점은, 에이전트에 따라 요구하는 최소 버전이 다르다는 것이다.

대표적으로 Codex App은 Ollama v0.24.0 이상이 필요하다.

둘째는 컨텍스트 길이다. 코딩 도구는 큰 컨텍스트에서 가장 잘 동작하므로, Ollama 설정에서 컨텍스트 길이를 넉넉히 올려야 한다.

다만 권장 하한선이 문서마다 조금씩 다르다.

통합	최소 Ollama 버전	권장 컨텍스트 길이
Claude Code	v0.14.0+ (Anthropic API 호환)	최소 32K 토큰
Codex App	v0.24.0+	(블로그 일반 권장치 적용)
Copilot CLI	v0.21.0+	최소 64k 토큰
공통 권장(코딩 도구)	v0.15+	최소 64000 토큰

표의 마지막 행이 기준선이다.

공식 블로그는 "컨텍스트 길이를 최소 64000 토큰으로 올리라"고 권한다.

Claude Code 문서는 32K를 하한으로 제시하는데, 이는 도구별로 최소 요구가 다를 뿐 값이 클수록 큰 저장소를 다루기 유리하다는 방향은 같다. 처음이라면 64000 토큰을 기준으로 잡고, 리포지토리가 크면 더 올리는 편이 안전하다.

실습 전 체크

Ollama v0.15+ 설치 (ollama --version으로 확인)
Ollama 설정에서 컨텍스트 길이 64000 토큰 이상으로 상향
클라우드 모델(:cloud)을 쓸 거라면 Ollama 계정 로그인(ollama signin)

버전이 낮으면 --help 목록 자체가 짧다

Ollama가 오래된 버전이면 ollama launch --help에 16개가 다 나오지 않는다. 예를 들어 Codex App은 v0.24.0 이상에서만 목록에 뜬다. 원하는 통합이 안 보인다면 지원 종료가 아니라 업데이트가 필요하다는 신호일 수 있다.

6. 실습 ① Claude Code

Claude Code는 이전 글에서 이미 자세히 다뤄본 도구라, 여기서는 핵심 명령과 환경변수만 짚고 넘어간다. 빠른 설정은 한 줄이다.

ollama launch claude

이 명령을 실행하면 Ollama가 Claude Code용 설정을 맞추고 Claude Code를 띄운다.

앞에서 본 것처럼 대화형으로 모델을 고르라는 프롬프트가 나오는데, 아래 화면이 실제로 그 뒤에 이어지는 모습이다.

이제 부터는 실제 공식 문서의 튜토리얼을 진행해보자.

ex) ollama launch claude

내 화면 기준은 ollama launch claude 이후 Claude Code가 glm-5.2:cloud 모델 부터 노출된다.

여기서 곧바로 코드를 물어보면 로컬 모델이 그대로 응답한다.

최근에 glm-5.2에 대해 글을 작성한 적도 있으니, 해당 모델을 선택해보겠다.

클라우드 모델 이용은 무료 계정으로도 가능하지만 사용량 제한이 있다.

무료 계정은 경량 모델 위주의 제한된 GPU 시간을 제공하며 동시에 클라우드 모델 1개만 구동할 수 있다.

위에서 시도한 glm-5.2:cloud처럼 대형 모델은 Pro 구독($20/월) 이상에서 이용 가능하다.

Pro는 무료 대비 50배 사용량에 동시 3개 모델을 지원한다. (출처: ollama.com/pricing, 2026-07-07 직접 확인)

일단 컨셉 증명을 해야 하는거니 클라우드 대신 로컬 모델로 먼저 연결을 확인해보자.

이미 qwen3:8b를 다운로드해 뒀다면 아래 한 줄이면 충분하다.

ollama launch claude --model qwen3:8b

저사양 PC용 로컬 모델 다운로드 (RAM 8 GB 기준)

qwen3:8b가 아직 없거나 더 가벼운 모델이 필요하면 아래 중 하나를 받으면 된다. 크기는 2026-07-07 기준 ollama.com/library에서 직접 확인한 수치다.

모델	다운로드 크기	컨텍스트	특징
`phi4-mini`	2.5 GB	128K	CPU만 있어도 동작, 최경량
`gemma3:4b`	3.3 GB	128K	추론·코드 균형
`qwen2.5-coder:7b`	4.7 GB	128K	코딩 특화, 7B급 최선택
`qwen3:8b`	5.2 GB	40K	범용 성능 우수, 위에서 시도한 모델

⚠️ qwen3-coder는 저사양 PC에 맞지 않는다
qwen3-coder 시리즈의 최솟값은 30b(약 19 GB)다. 이름이 비슷한 qwen3:8b와 다른 시리즈이므로 혼동하지 말자.
(출처: ollama.com/library/qwen3-coder/tags, 2026-07-07 확인)

# 하나만 골라서 받으면 된다
ollama pull phi4-mini          # 2.5 GB — 최경량
ollama pull gemma3:4b          # 3.3 GB
ollama pull qwen2.5-coder:7b   # 4.7 GB — 코딩 특화
ollama pull qwen3:8b           # 5.2 GB — 이미 있으면 skip

ex) ollama launch claude --model qwen3:8b

- 위 예시로 진행해도 되지만, 난 직접 ollama launch claude 를 통해 설정해보겠다.

>> ollama launch claude

>> qwen3:8b 모델로 클로드 코드가 연동 되었다.

- status line도 변경 되어 있다.

- token output 속도가 sonnet4.6일때보다 현저히 느리지만, 일단 정상동작하는 부분. 그리고 코드 수정도 가능하다.

(너무 느려 따로 캡쳐하진 않았다.)

- 소넷 예시

수동으로 붙이고 싶다면 환경변수 세 개를 지정한다. 공식 문서 기준이다.

export ANTHROPIC_AUTH_TOKEN=ollama
export ANTHROPIC_API_KEY=""
export ANTHROPIC_BASE_URL=http://localhost:11434

핵심은 ANTHROPIC_BASE_URL을 로컬 Ollama 주소(http://localhost:11434)로 돌려놓는 것이다.

쉽게 말해 Claude Code가 원래 Anthropic 서버로 보내던 요청을 내 컴퓨터의 Ollama로 우회시키는 설정이다. ANTHROPIC_API_KEY=""처럼 빈 값으로 두는 것도 문서가 명시한 그대로다.

모델 지정은 실행할 때 붙인다. 로컬이면 claude --model gpt-oss:20b, 클라우드면 claude --model glm-4.7:cloud 식이다.

# 로컬 모델로 실행
claude --model gpt-oss:20b

# 클라우드 모델로 실행
claude --model glm-4.7:cloud

ex) 이번엔 claude --model glm-4.7:cloud 을 통해 cloud 모델을 사용해보자. ( glm-5.2는 프로 구독이 필요하여 패스 )

- glm4.7:cloud 모델도 정상적으로 기동되는모습

스크립트나 Docker·CI처럼 사람이 지켜보지 않는 환경에서는 --yes를 쓴다. --yes는 선택 프롬프트를 건너뛰고 필요 시 모델을 자동으로 받으며, --model 지정을 반드시 요구한다. -- 뒤에 붙인 인자는 Claude Code에 그대로 전달된다.

ollama launch claude --model gemma4:cloud --yes -- -p "how does this repository work?"

이 명령은 확인 프롬프트 없이 gemma4:cloud 모델로 Claude Code를 띄우고, -p 뒤 질문을 그대로 실행한다. 자동화 파이프라인에 코드 리뷰나 요약을 걸어 둘 때 쓸 만하다.

Claude Code 권장 모델, 어디서 봐야 하나

2026-07-02 기준 Claude Code용 코딩 추천 모델은 로컬 gpt-oss:20b·qwen3-coder, 클라우드 glm-4.7:cloud·minimax-m2.1:cloud다. (출처: Ollama 블로그 — Claude Code)

여기서 하나 짚고 넘어가자면, 커뮤니티에서 자주 돌아다니는 kimi-k2.5:cloud·glm-5:cloud 목록은 Claude Code가 아니라 Copilot CLI 문서의 권장 목록이다.

페이지를 대조해보지 않으면 그대로 헷갈리기 쉬운 부분이니, 다운로드 전에 어느 도구 문서인지 한 번 더 확인하는 편이 안전하다.

7. 실습 ② Codex App

Codex App은 OpenAI의 macOS·Windows용 데스크톱 코딩 에이전트다.

워크트리와 git 기능을 내장해 여러 Codex 스레드를 병렬로 다룬다.

Ollama가 이 앱에 OpenAI 호환 엔드포인트를 자동으로 구성해 주므로, 로컬 모델과 Ollama Cloud 모델을 데스크톱 앱에서 함께 쓴다.

이번 글에서 가장 손이 많이 가는 실습이라 단계별로 보겠다.

Step 1 — 버전 확인

Codex App 통합은 Ollama v0.24.0에서 처음 추가됐다. 그래서 이 실습은 v0.24.0 이상에서만 동작한다. ollama --version으로 먼저 확인한다.

Step 2 — 한 줄로 설정·실행

ollama launch codex-app

이 명령은 Codex App의 설정을 Ollama 엔드포인트로 바꾸고 앱을 띄운다. 처음 실행하면 설정 파일을 덮어쓰기 전에 백업을 남긴다.

ex) ollama launch codex-app
- 이때도 모델을 선택하게 되어있다. (이번 예시엔 이미 설치되어있는 qwen3:8b 선택)

- codex App이 켜지는데 모델 선택 하는 부분은 보이지 않는다.

- 이에 모델 확인 요청 하니 Qwen임을 확인 가능 하였다.

Step 3 — 백업 위치 확인

Ollama Launch는 Codex App 설정 파일을 덮어쓰기 전에 ~/.ollama/backup/codex-app/에 백업을 저장한다. (Windows에서 ~는 사용자 프로필 디렉터리로 해석된다.) 원래 설정으로 돌아갈 길이 남아 있다는 말이라, 실습이 처음이라도 부담이 덜하다.

Step 4 — 모델 지정해서 실행

기본 선택 대신 원하는 모델을 바로 지정하면 된다. 클라우드 모델과 로컬 모델 예시는 다음과 같다.

# 클라우드 모델 지정
ollama launch codex-app --model kimi-k2.6:cloud

# 로컬 모델 지정
ollama launch codex-app --model gemma4:31b

Codex App 도입 당시 릴리스 노트는 어려운 코딩·에이전트 작업에는 kimi-k2.6·glm-5.1을, 클라우드 구독 없이 로컬로 쓸 때는 nemotron-3-super·gemma4:31b·qwen3.6을 권했다. 현재 문서의 예시도 같은 계열(kimi-k2.6:cloud·gemma4:31b)을 유지한다.

Step 5 — 원래 프로필로 되돌리기

Ollama로 바꾸기 전 프로필로 돌아가려면 --restore를 쓴다.

ollama launch codex-app --restore

이 명령을 실행하면 Ollama가 Codex App의 설정과 구성을 실행 이전 상태로 복원한다. Ollama 모델을 시험만 해보고 원래 쓰던 설정으로 깔끔하게 돌아가고 싶을 때 쓴다.

ex) ollama launch codex-app --restore

- 다시 GPT 5.5 모델로 돌아 오면서 Codex App이 기동되었다.

Codex App이 안 열리거나 모델이 안 바뀔 때

• 설정 후에도 앱이 열리지 않으면, Codex를 수동으로 한 번 연 뒤 ollama launch codex-app을 다시 실행한다.

• 앱이 이미 실행 중인데 모델이 바뀌지 않으면, Ollama가 재시작을 물어볼 때 허용하거나 앱을 완전히 종료한 뒤 다시 실행한다.

Codex App vs Codex CLI

이름이 비슷해 헷갈리기 쉽다.

codex-app은 데스크톱 GUI 앱이고, codex는 터미널 CLI다. CLI는 npm install -g @openai/codex로 설치한 뒤 codex --oss 플래그로 Ollama와 연결한다.

둘은 별개 통합이라 --help 목록에도 따로 올라 있다.

8. 실습 ③ OpenCode

OpenCode는 ollama launch 최초 도입(v0.15.0)부터 함께한 네 통합 중 하나다. 실행은 역시 한 줄이다.

# 바로 실행
ollama launch opencode

# 실행하지 않고 설정만
ollama launch opencode --config

첫 명령은 OpenCode를 설정하고 곧바로 띄운다. --config를 붙이면 실행은 하지 않고 설정만 해 둔다. 지금 당장 열지 않고 나중에 직접 실행하고 싶을 때 쓴다.

OpenCode + Ollama Cloud 모델(glm-4.7:cloud) 구동 화면. 출처:Ollama 공식 블로그 — Launch

공식문서의 캡쳐 화면은 ollama launch opencode --config 이후 OpenCode가 클라우드 모델 glm-4.7:cloud로 응답하는 모습이다.

하단 Build 표시줄에 모델 이름이 보인다.

로컬 모델을 붙였다면 이 자리에 glm-4.7-flash 같은 로컬 모델 이름이 뜬다.

같은 도구를 로컬로도, 클라우드로도 돌린다는 앞의 이야기가 화면에서 그대로 확인된다.

OpenCode도 --model로 바꿀 수 있다

여기서는 기본 흐름만 보였지만, Claude Code·Codex App과 마찬가지로 ollama launch opencode --model <모델명>으로 원하는 모델을 바로 지정하면 된다.

9. --model 플래그 — 매핑은 고정이 아니다

글 서두에서 짚었던 오해를 다시 꺼내보자.

"Claude Code는 이 모델, Codex는 저 모델"처럼 에이전트마다 쓸 모델이 정해져 있다는 생각 말이다.

ollama launch의 기본 프롬프트가 모델을 하나 미리 제시할 뿐이고, --model 플래그만 붙이면 언제든 다른 모델로 바꿀 수 있다.

CLI 문서도 ollama launch claude --model qwen3.5처럼 특정 통합에 원하는 모델을 지정하는 예시를 그대로 보여준다. 다른 에이전트도 마찬가지다.

에이전트	모델 지정 예시
Claude Code	`ollama launch claude --model qwen3.5`
Codex App	`ollama launch codex-app --model kimi-k2.6:cloud`
OpenClaw	`ollama launch openclaw --model kimi-k2.5:cloud`
Pool	`pool -m kimi-k2.6:cloud`

표에서 보듯, 에이전트와 모델의 관계는 고정 배선이 아니라 실행할 때 정하는 옵션이다. 같은 Claude Code를 로컬 qwen3.5로도, 클라우드 glm-4.7:cloud로도 돌린다. "이 도구는 이 모델 전용"이라는 표현을 보면 일단 의심하는 편이 맞다. 페이지에 적힌 권장 모델은 말 그대로 권장일 뿐, 강제 매핑이 아니다.

모델을 바꿔보기 전 체크 두 가지

--model로 다른 모델을 넣어 보기 전에 두 가지만 확인한다. 클라우드 모델(:cloud)이면 ollama signin 로그인 여부, 로컬 모델이면 VRAM이 버티는지다. 이 두 조건만 맞으면 어떤 에이전트에도 원하는 모델을 자유롭게 붙이면 된다.

10. 나머지 에이전트 한눈에 보기

실습으로 다룬 Claude Code·Codex App·OpenCode를 빼면 통합은 13개가 남는다.

각각을 깊게 다루긴 어려우니, 무엇이고 어떻게 실행하는지 표 하나로 묶었다. 대부분 ollama launch <이름> 패턴을 따른다.

표를 보는 법

'실행 / 문서' 열의 명령을 터미널에 그대로 입력하면 대부분 바로 연결된다. 표는 한 줄 설명일 뿐이니, 실제로 써 볼 통합이 있으면 링크를 눌러 옵션까지 문서에서 확인하는 편이 안전하다.

통합	한 줄 설명	실행 / 문서
Hermes Agent	Nous Research의 자가개선형 에이전트. 자동 스킬 생성·세션 간 메모리·기본 70여 개 스킬	`ollama launch hermes` · 문서
Hermes Desktop	Hermes Agent의 데스크톱 채팅 앱 (Nous Research)	`ollama launch hermes-desktop` · 문서
OpenClaw	메시징(WhatsApp·Telegram·Slack 등)을 코딩 에이전트에 연결하는 개인 어시스턴트	`ollama launch openclaw` · 문서
Copilot CLI	GitHub의 터미널용 AI 코딩 에이전트	`ollama launch copilot` · 문서
Codex (CLI)	OpenAI 터미널 CLI. `codex --oss`로 연결	`ollama launch codex` · 문서
Droid	최초 4개 통합 중 하나인 코딩 에이전트	`ollama launch droid` · 문서
OMP (Oh My Pi)	IDE형 터미널 코딩 에이전트 (언어 서버·디버깅·서브에이전트 내장)	`ollama launch omp` · 문서
Pool	Poolside의 엔터프라이즈용 터미널 에이전트	`ollama launch pool` · 문서
Pi	터미널 에이전트 (`--help` 목록 기준)	`ollama launch pi`
Kimi Code CLI	터미널 코딩 CLI (`--help` 목록 기준)	`ollama launch kimi`
Cline	코딩 에이전트 (`--help` 목록 기준)	`ollama launch cline`
Qwen Code	터미널 코딩 CLI (`--help` 목록 기준)	`ollama launch qwen`
VS Code	에디터 통합 (별칭 `code`)	`ollama launch vscode`

표를 만들다 정정할 대목을 하나 발견했다.

Hermes Desktop을 "공식 문서가 없는 통합"으로 적어놨었는데, 실제로 찾아보니 docs.ollama.com/integrations/hermes-desktop에 페이지가 있고 ollama launch hermes-desktop 사용법도 안내하고 있었다.

반대로 Pi·Kimi·Cline·Qwen Code처럼 --help 목록에는 있지만 개별 소개가 얕은 통합도 있으니, 이런 도구는 이름과 실행 명령만 확인하고 실제 문서에서 최신 사용법을 다시 확인하는 편이 안전하다.

11. 계정 로그인이 필요한 기능 (ollama signin)

ollama launch로 도구를 연결하는 것까지는 계정 없이도 되지만, 일부 기능에는 Ollama 계정 로그인이 필요하다.

대표적인 예가 웹서치다. ollama launch openclaw로 실행하면 Ollama 웹서치가 자동으로 켜지는데, 이 웹서치가 Ollama 웹서치 API에 의존하고 그 API는 API 키와 무료 Ollama 계정을 요구하기 때문이다.

클라우드 모델(:cloud)을 쓸 때도 같은 계정 인증이 필요하다.

로그인은 CLI 한 줄이다.

ollama signin

로그인이 필요한 순간

로컬 모델만 쓴다면 로그인 없이도 대부분 동작한다. 하지만 :cloud 모델을 지정하거나 OpenClaw 웹서치 같은 기능을 쓰려는데 인증 오류가 난다면, 먼저 ollama signin을 했는지 확인한다. 로그인을 건너뛴 채 클라우드 기능을 시도하다 막히는 경우가 의외로 흔하다.

로그인 없이도 되는 것

로컬 모델로 ollama launch claude·ollama launch codex-app 같은 기본 연결은 로그인 없이 동작한다. 로그인이 필요해지는 경우는 :cloud 모델을 붙이거나 OpenClaw 웹서치처럼 Ollama 계정 자체가 필요한 기능을 켤 때다.

12. 트러블슈팅 & Q&A

Q. ollama launch를 쳤는데 통합이 몇 개 안 보인다. 지원이 안 되는 건가?

데스크톱 앱 카드는 자주 쓰는 것만 선별해 보여 준다. 전체 지원 목록은 터미널에서 ollama launch --help로 확인한다. 직접 테스트 기준 16개가 나열되며, 카드에 없어도 ollama launch <이름>으로 실행되는 경우가 많다.

Q. 로컬 모델이 자꾸 느리거나 메모리 부족으로 죽는다.

로컬 대형 모델은 VRAM을 많이 요구한다. 예로 glm-4.7-flash는 64000 토큰 컨텍스트에서 약 23GB VRAM이 필요하다. 하드웨어가 못 따라가면 같은 계열의 :cloud 모델로 바꾼다. 모델 이름만 바꾸면 되고, 클라우드는 로컬 사양과 무관하게 전체 컨텍스트 길이를 쓴다.

Q. Codex App을 연결했더니 앱이 안 열린다.

Codex를 수동으로 한 번 연 뒤 ollama launch codex-app을 다시 실행한다. 이미 실행 중인데 모델이 안 바뀌면 Ollama가 재시작을 물어볼 때 허용하거나 앱을 종료한 뒤 다시 실행한다. 원 설정으로 돌리고 싶으면 --restore를 쓴다.

Q. 컨텍스트 길이는 얼마로 잡아야 하나?

공식 블로그는 코딩 도구용으로 최소 64000 토큰을 권한다. Claude Code는 최소 32K를, Copilot CLI는 최소 64k를 권장하는 식으로 도구마다 하한이 다르다. 값이 클수록 큰 리포지토리를 다루기 유리하므로, 64000 토큰을 기준으로 잡고 필요하면 올린다.

Q. 클라우드 모델 요금이 궁금하다.

공식 블로그는 이번 업데이트로 사용량이 늘고 5시간짜리 확장 코딩 세션 윈도우를 제공한다고 밝혔다. 다만 구체적인 요금과 한도는 시점에 따라 바뀔 수 있으므로, 결정 전에 Ollama 요금 페이지에서 최신 정보를 확인한다.

13. 마무리 — 로컬과 클라우드, 무엇을 고를까

여기까지 직접 돌려보고 정리하고 나니, ollama launch의 진짜 이점은 "에이전트를 바꾸든 모델을 바꾸든 명령 한 줄"이라는 데 있다는 걸 보여주고 싶었다.

그러면 남는 질문은 도구 선택이 아니라 로컬과 클라우드 중 무엇을 언제 쓰느냐다.

상황	추천	이유
코드가 외부로 나가면 안 됨	로컬	연산이 내 컴퓨터를 벗어나지 않는다
오프라인·네트워크 불안정	로컬	네트워크 없이 동작한다
VRAM이 부족(노트북 등)	클라우드(`:cloud`)	로컬 사양과 무관하게 전체 컨텍스트를 쓴다
큰 리포지토리·긴 컨텍스트	클라우드(`:cloud`)	전체 컨텍스트 길이 지원
일단 연결부터 확인	클라우드(`:cloud`)	대형 모델 다운로드 시간을 건너뛴다

공식 가이드가 정리해 주지 않는 것 — "권장 모델"의 파편화

이 글을 쓰면서 느낀 건데, Ollama 공식 페이지들은 "이 에이전트엔 이 모델"을 한곳에 모아 주지 않는다. 실제로 2026-07-02 기준 Claude Code 문서에는 권장 모델 섹션 자체가 없고, 같은 kimi-k2.5:cloud·glm-5:cloud 목록이 Copilot CLI 문서에 있다. 어시스턴트 계열(OpenClaw·Hermes)은 또 다른 4종을 권한다. "정답 모델"을 찾겠다고 페이지를 옮겨 다니면 오히려 헷갈리기만 한다. 차라리 --model로 몇 개 직접 돌려 보고 내 리포지토리에서 잘 맞는 것을 고르는 편이 현실적이다.

독자 적용 체크리스트

ollama --version으로 v0.15+인지 확인하고, 아니면 업데이트한다.
ollama launch --help를 실행해 내 환경이 지원하는 통합 목록을 직접 확인한다.
Ollama 설정에서 컨텍스트 길이를 64000 토큰 이상으로 올린다.
클라우드 모델을 쓸 계획이면 ollama signin으로 먼저 로그인한다.
같은 에이전트를 --model로 로컬·클라우드 모델을 번갈아 실행해 응답 차이를 비교한다.

단계별 도입 플레이북

오늘: Ollama를 v0.15+로 올리고 ollama launch claude 또는 ollama launch codex-app으로 한 도구를 연결한다.
이번 주: :cloud 모델과 로컬 모델을 각각 붙여 응답 속도·품질을 비교하고, 자주 쓰는 조합을 정한다.
자동화한다면: --yes와 --model을 조합해 스크립트·CI에 코드 리뷰나 요약 작업을 걸어 둔다.

거창하게 준비할 것 없다. 지금 터미널을 열어 ollama launch --help부터 실행해 보면, 내 환경이 어떤 에이전트를 지원하는지 30초 안에 확인된다.

참고 자료

같이 보면 좋은 글

공식 블로그·문서

GitHub 릴리스 (버전·기능 시점 교차검증)

작성일: 2026년 7월 2일 | 기준 버전: Ollama 0.30.11 (직접 테스트) | 통합 개수: ollama launch --help 기준 16개

통합 개수·권장 모델·요금·컨텍스트 권장치는 업데이트에 따라 달라질 수 있다. 적용 전 공식 문서를 최우선으로 확인하는 편이 안전하다. 요금·한도 정보는 시점에 따라 바뀔 수 있으므로 Ollama 요금 페이지에서 최신 정보를 확인한다.

Claude Tag란? @Claude로 업무를 위임하는 Slack 협업 방식(Slack in Claude, Claude Tag는 무엇이 다른가)

갓대희 — Mon, 6 Jul 2026 22:56:46 +0900

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

Slack에서 @Claude라고 한 번만 부르면 일을 맡길 수 있는 도구가 나왔다.

이름은 Claude Tag. 2026년 6월, Team·Enterprise 고객 대상 베타로 공개됐다.

이 글을 읽기 전에, 다들 제일 먼저 궁금해하는 것부터 바로 풀고 시작하자.

Q. 나는 개인 Pro나 Max 요금제인데, Claude Tag 쓸 수 있어?

→ 아니요, 지금은 안 됩니다. Claude Tag는 회사(조직)가 Team 또는 Enterprise 플랜일 때만 관리자가 켤 수 있는 기능이다. 개인이 쓰는 무료·Pro·Max 요금제로는 우회 방법이나 개인 업그레이드 경로가 없다. 회사 전체가 Team·Enterprise가 아니라면, 지금 당장은 사용할 수 없다.

2026-07-06 기준 공식 문서에 공개된 범위는 Team·Enterprise 플랜의 Slack 베타다. 다른 요금제나 다른 협업 도구 지원 시점은 확인되지 않았다.

기존 Claude in Slack 또는 Claude Code in Slack을 써본 팀이라면 Slack에서 @Claude를 부르는 흐름은 익숙할 수 있다. 다만 Claude Tag는 권한 범위, 청구 주체, PR 작성 주체, Agent Identity가 달라지는 새 경험이다.
https://code.claude.com/docs/en/slack

캡처 주의: 아래 일부 화면은 실제 Claude Tag 화면이 아니라 기존 Claude Code in Slack/Claude in Slack 기준의 참고 화면이다. UI 흐름을 이해하기 위한 예시로만 보고, Claude Tag의 권한·청구·PR 작성 주체·Agent Identity는 공식 Claude Tag 문서를 기준으로 확인해야 한다.

공식 화면으로 캡처하면 좋은 지점

Claude Tag 제품 페이지: 실제 @Claude 화면 예시와 Team·Enterprise 베타 문구
Claude Tag Overview: 개인 플랜 미지원, 실행 환경, usage balance 설명
Security and data handling: Agent Proxy, credential store, default-deny 네트워크 흐름

Claude Code in Slack - Claude Code Docs

Delegate coding tasks directly from your Slack workspace

code.claude.com

"우리 회사는 개인 요금제만 쓴다"면 이 글은 미리보기 정도로만 읽고, 나머지는 회사가 Team·Enterprise로 옮겨갈 때를 위해 저장해두면 된다. 반대로 "우리 회사가 Team이나 Enterprise 고객"이라면, 지금부터 나오는 내용이 바로 실무에 쓰일 이야기다.

처음 읽는 분을 위한 안내

이 글은 총 8개 섹션이다.
시간이 없다면 1(뭔지) → 3(뭘 할 수 있는지) → 5(실제 예시) → 8(FAQ)만 읽어도 충분하다.
4장(내부 구조)은 보안 담당자·관리자용으로, 일반 사용자는 건너뛰어도 된다.

Anthropic은 자기 회사 제품팀 코드의 상당 부분을 내부 버전 Claude Tag로 만들고 있다고 밝혔다.

자기가 만든 도구를 자기 개발 과정에 이 정도로 깊이 쓴다면, 단순한 채팅 봇 취급하고 넘어가기는 어렵다.

그래서 이 글은 "Claude Tag가 뭔가"라는 정의보다 "언제, 어떻게 쓰는가"에 초점을 둔다.

Claude Tag란 — Slack에 상주하는 팀 단위 Claude
시작하기 — 관리자 4단계 설정
핵심 기능 — 위임·비동기·Ambient 동작
(선택) 내부 구조 — 채널 격리 모델
실전 활용 시나리오 4가지 — 언제·어떻게 쓰는가
요금제와 제한사항
대안 비교 — Claude.ai 채팅·API 직접 호출 대비
자주 묻는 질문과 결론

용어부터 쉽게 잡고 가자

Claude Tag: Slack 채널에 상주하며 @Claude라고 부르면 일을 맡을 수 있는 팀용 Claude. 채팅창이 아니라 '팀에 새로 들어온 동료'라고 생각하면 쉽다.
멀티플레이어: 채널마다 Claude가 한 명씩 있고, 그 한 명을 팀원 전체가 같이 쓴다는 뜻. 나만의 개인 챗봇이 아니라 '팀 공용 계정' 개념에 가깝다.
Ambient 동작: 공식 문서의 ambient presence/ambient behavior를 이 글에서 쉽게 부르는 말. 누가 부르지 않아도 Claude가 채널 흐름을 보고 필요하다고 판단하면 먼저 답할 수 있는 동작이다.
에피메럴 샌드박스: 작업할 때마다 새로 만들었다가 끝나면 바로 없애버리는 임시 작업 공간. '1회용 컴퓨터'라고 이해하면 된다.
usage balance(사용량 잔액): 회사(조직) 단위로 깎이는 사용량 한도. 통신사 데이터 요금제처럼, 회사 전체가 하나의 잔액을 나눠 쓴다고 보면 된다.
Connections/도구 연결: Claude가 외부 도구나 데이터(예: 사내 데이터베이스, 깃허브)에 접근하도록 조직 관리자가 붙여주는 연결.
Member Access: Claude Tag를 누가 호출할 수 있는지 제한하는 설정. Enterprise에서는 역할과 capability를 이용한 제한까지 가능하다.
Routines(루틴): 사람이 매번 태그하지 않아도 알아서 반복 실행되는 작업. 예: 매일 아침 지표 요약, PR 올라오면 자동 확인.

1. Claude Tag란 — Slack에 상주하는 팀 단위 Claude

Claude Tag를 한 문장으로 줄이면 이렇다. "팀이 이미 쓰고 있는 Slack 채널 안으로, 일을 맡길 수 있는 Claude가 직접 들어온다."

개인이 Claude.ai 탭을 따로 여는 방식과는 다르다.
팀원들이 원래 대화하던 그 채널에 Claude가 상주한다.

핵심은 "멀티플레이어" 구조다. 공식 발표는 채널과 Claude의 관계를 이렇게 설명한다.

"Within a given Slack channel, there's one Claude that interacts with everyone."
(Slack 채널마다 팀원 모두와 상호작용하는 Claude가 하나씩 있습니다.)

쉽게 풀면 이렇다. 채널 하나에 Claude는 딱 한 명이고, 그 한 명을 팀원 전체가 같이 쓴다.

사람마다 별도 대화창이 열리는 개인 채팅과는 다르다. 한 채널의 모든 사람이 같은 Claude와, 같은 대화 맥락 위에서 이야기한다. 그래서 좋은 점이 있다. 누구나 Claude가 지금까지 뭘 했는지 볼 수 있고, 다른 사람이 멈춘 지점부터 이어서 대화할 수 있다.

예를 들면, 채널마다 하나의 @Claude가 붙어 있다고 이해하면 된다.

기존 Claude 인터페이스와 가장 다른 지점도 여기다.

Claude.ai 채팅은 '나 혼자 쓰는 세션'이고, Claude Tag는 '채널 전체가 공유하는, 계속 이어지는 동료'다.

이 차이를 실무에서 어떻게 체감하는지는 7장 대안 비교에서 다시 정리했다.

Anthropic이 밝힌 도입 이유

Anthropic은 공식 발표에서 "현재 제품팀 코드의 65%가 내부 버전 Claude Tag로 작성된다"고 밝혔다. 만든 회사가 자기 제품 개발에 이 정도 비중으로 쓴다는 건, "그냥 채팅 도우미"가 아니라 "실제로 일을 맡기는 도구"를 목표로 만들었다는 가장 직접적인 근거다.

정의만 놓고 보면 "그냥 Slack 봇 아닌가" 싶을 수 있다.

차이는 여기 있다. 명령어를 외워서 호출하는 봇이 아니라, 사람에게 일을 맡기듯 그냥 말로 부탁하고, 채널의 대화 맥락을 같이 공유한다는 점이다.

이 감각을 가지고 다음 장의 설정·기능을 보면 훨씬 이해가 쉽다.

기존 Claude in Slack 화면에서는 아래처럼 모델 선택 UI가 보였다.

아래 화면은 기존 Slack 연동 참고 화면이며, Claude Tag 실제 UI와 다를 수 있다.

출시 발표에서는 Claude Tag가 Opus 4.8과 함께 동작한다고 소개됐다. 다만 최신 공식 문서 기준으로는 조직에서 허용한 모델 중 스레드·채널·DM별로 모델을 바꿀 수 있고, 선택 가능한 모델 목록은 조직 설정에 따라 달라진다.

2. 시작하기 — 관리자 4단계 설정

Claude Tag는 일반 팀원이 혼자 켤 수 있는 기능이 아니다. 회사(조직) 관리자가 설정해야 한다.

정확히는 Claude 조직의 Owner 또는 Primary Owner가 Claude Tag의 identity와 Access bundle을 설정해야 한다. Slack 앱 승인이나 @Claude connect 단계에서는 Slack 워크스페이스 관리자 권한이 추가로 필요할 수 있다. Claude 조직 Admin은 일부 항목을 볼 수 있어도, 워크스페이스 페어링과 Access bundle 생성은 완료하지 못한다.

설정 시작 위치는 claude.ai/admin-settings/claude-tag다.

설정 절차는 네 단계, 그리 복잡하지 않다.

단계	할 일	왜 하는가
1	Slack 워크스페이스 연결하기	Claude를 우리 회사 Slack에 연결
2	쓸 수 있는 도구·데이터 정하기	Claude가 어디까지 손댈 수 있는지 범위 지정
3	한 달 지출 한도 정하기	비용이 예상치 못하게 쌓이지 않도록 상한선 설정
4	비공개 채널에서 먼저 테스트	전사에 풀기 전에 좁은 범위에서 확인

눈여겨볼 부분은 마지막 단계인 "비공개 채널 테스트"다.

처음 도입한다면 반드시 이 테스트 채널부터 작게 시작하자. 전사 채널에 곧바로 붙이면, 도구 권한과 비용이 어디까지 열려 있는지 확인할 틈도 없이 많은 사람이 한꺼번에 쓰기 시작한다.

설정이 끝나면 Claude Tag를 쓰는 방법은 세 가지다.

1) 채널에서 @Claude라고 태그하기
아래 예시 화면에서는 Claude Tag로 마이그레이션된다는 안내가 보인다. 다만 실제 Claude Tag 화면이 아니라 기존 Slack 연동 참고 화면이다.

2) Claude와 1:1 DM 하기

3) Slack 화면 위쪽 AI assistant 아이콘으로 Claude 패널 열기.

채널에서 태그하면 회사가 정한 채널 권한과 회사 usage balance(사용량 잔액)를 쓴다. DM과 패널은 개인 계정 쪽 기능에 더 가깝다. 이 차이는 6장 요금제에서 다시 자세히 다룬다.

관리자 입장에서 중요한 점이 하나 더 있다. Claude Tag가 외부 도구에서 수행한 작업은 서비스 계정 기준으로 추적 가능해야 한다는 것.

Anthropic 공식 문서 기준으로 관리자는 조직·채널별 지출 한도를 정할 수 있고, @Claude가 Slack·GitHub·연결 도구에서 남긴 활동은 Claude app, Claude GitHub App, 또는 별도 서비스 계정의 audit trail로 남는다.

그러니 도입 전에는 기능만 테스트하지 말고, Slack 스레드 링크와 연결 도구의 audit log에서 작업 출처가 어떻게 보이는지까지 확인해보자.

설정 권한 주의

Claude Tag 설정의 핵심 권한은 Claude 조직 Owner/Primary Owner다. Slack 앱 승인이나 워크스페이스 연결 단계에서는 Slack 쪽 관리자 권한도 필요할 수 있다. 도입을 검토 중이라면 "우리 Claude 조직 Owner와 Slack 승인 담당자가 누구지?"부터 확인하자.

기존에 "Claude in Slack" 앱을 쓰던 팀이라면 일정도 챙겨야 한다.

지원 문서 기준으로 이 앱은 2026년 8월 3일에 Claude Tag 경험으로 전환된다. 다만 기존 사용자 연결이나 도구 접근이 그대로 넘어간다고 보면 안 된다.

마이그레이션 기한 주의

기존 Claude in Slack은 2026년 8월 3일에 Claude Tag 경험으로 전환될 예정이다. 하지만 새 Claude Tag는 채널 단위 Agent Identity로 동작하므로, GitHub 저장소·연결 도구·서비스 계정 권한은 Access bundle로 다시 구성해야 한다. 기존 앱에 의존하는 업무가 있다면, 전환일 전에 어떤 채널을 New/Legacy/Off 중 어디에 둘지와 어떤 도구 권한을 붙일지 먼저 정리하자.

혹시나 하여 미리 https://claude.ai/admin-settings/claude-tag 에서 설정 가능한지 확인해 보았으나

- 개인 사용자는 다음과 같이 안내 되고 있다.

3. 핵심 기능 — 위임·비동기·Ambient 동작

Claude Tag의 기능을 한 줄로 줄이면 이렇다. "맡기고, 기다리지 않고, 먼저 챙긴다."

채널에서 일을 맡기는 기본 동작 위에, "기다릴 필요 없는 실행 방식"과 "먼저 알아서 챙기는 기능"이 얹혀 있다. 반복되는 작업은 루틴으로 등록해두면 된다.

가장 기본이 되는 건 비동기 실행이다. 쉽게 말해 "시켜두고 신경 안 써도 되는" 방식이다.

일을 넘긴 뒤 사용자는 다른 일을 하면 된다. Claude는 그동안 알아서 작업을 진행하고, 결과가 나오면 채널 스레드에 올라온다. 답을 기다리며 대화창을 계속 붙잡고 있지 않아도 된다는 뜻이다.

Ambient 동작은 한 단계 더 적극적이다.

공식 문서 표현으로는 Claude가 채널 안의 ambient presence처럼 동작할 수 있다는 뜻이다. 즉, 늘 @Claude를 붙여야만 하는 것은 아니다. 채널 흐름을 보고 답할 만하다고 판단하면 먼저 정보를 알려줄 수 있다. 부르면 대답하는 도구가 아니라, 옆에서 지켜보다가 알아서 끼어드는 동료에 가깝다.

Ambient 동작이 바꾸는 것

평소에는 Claude가 @Claude 태그가 있을 때 응답이 보장된다. Ambient 동작에서는 태그 없이도 채널 흐름을 보고 먼저 움직일 수 있다. 편리한 만큼, 비용과 승인 절차 측면의 부담도 함께 커진다. 이 한계는 6장에서 자세히 다룬다.

여기에 채널 메모리가 더해진다. 쉽게 말해 "이 채널에서 있었던 일을 Claude가 계속 기억한다"는 뜻이다.

Anthropic이 다른 글에서 짚은 원칙이 이 설계를 잘 설명해준다 — "에이전트에게는, 적혀 있지 않고 접근할 수 없다면 그것은 존재하지 않는 것과 같다."

사람끼리는 구두로 합의하거나 어깨너머로 들은 이야기도 통한다. 하지만 Claude에게는 채널에 실제로 기록된 대화만 존재하는 정보다. 그래서 Claude는 채널 안의 대화를 계속 따라가며 팀의 작업 맥락을 조금씩 배운다. 시간이 지날수록 그 채널의 일을 더 잘 이해하게 되는 구조다.

다만 알아둘 점이 있다. 공식 문서 기준으로 이 메모리는 '개인'이 아니라 '채널과 워크스페이스'에 붙는다.

공개 채널에서 만들어진 메모리는 회사 전체(워크스페이스) 차원에서 공유되고, 비공개 채널에서 쌓인 메모리는 그 채널만의 별도 저장소에 남는다.

앞서 말한 멀티플레이어 구조와 합쳐지면, 한 사람이 시작한 작업을 다른 사람이 같은 맥락 위에서 자연스럽게 이어받을 수 있다.

핵심 기능을 표로 정리하면 다음과 같다.

기능	쉽게 말하면	언제 작동하나
작업 위임	말로 부탁하면 실제로 일을 해줌	채널에서 `@Claude` 멘션할 때
비동기 실행	시켜두면 알아서 하고 스레드에 결과만 올려줌	일을 맡기면 자동으로
Ambient 동작	안 불러도 채널 지켜보다가 먼저 알려줌	채널 응답 설정과 루틴에 따라
채널 메모리	이 채널에서 있었던 일을 계속 기억함	채널에 상주하는 동안 항상
루틴	매번 안 불러도 반복해서 알아서 실행	채널에서 루틴 등록해두면
응답 제어	특정 스레드나 채널에서 조용히 시키거나 아예 빼기	직접 지시하거나 `/remove @Claude`

기능 체크 — 우리 팀엔 뭐가 맞을까

결과가 명확한 작업을 그냥 넘기고 싶다 → 작업 위임 + 비동기 실행
채널에서 중요한 걸 놓치기 싫다 → Ambient 동작 (다만 비용·승인 문제는 꼭 확인)
여러 사람이 같은 일을 이어서 해야 한다 → 멀티플레이어 + 채널 메모리
매일 똑같은 점검이나 알림이 필요하다 → 루틴

4. (선택) 내부 구조 — 채널 격리 모델

이 섹션은 보안 담당자·관리자용으로 다소 기술적이다. 그냥 사용자로서 궁금한 분이면 5장으로 건너뛰어도 무방하다.

공식 문서는 Claude Tag의 작업이 어디서 도는지 이렇게 설명한다.

"an ephemeral sandbox hosted by Anthropic, not on your computer or inside your network."
(작업은 사용자의 컴퓨터나 내부 네트워크가 아니라, Anthropic이 제공하는 임시 샌드박스 환경에서 실행됩니다.)

쉽게 말해, 작업은 사용자 PC나 회사 내부망 안이 아니라 Anthropic이 관리하는 임시 공간(에피메럴 샌드박스)에서 돌아간다. 작업이 끝나면 이 공간은 바로 사라진다. 그래서 실행 환경이 회사 인프라에 직접 붙어 있지 않다.

권한 모델도 공식 문서에 나와 있는 확정된 사실이다.

Claude가 무엇에 접근할 수 있는지는 "누가 쓰는가"가 아니라 "지금 어느 채널에 있는가"로 정해진다. 사람의 신원이 아니라 채널이 기준이라는 게 이 설계의 핵심이고, 동시에 6장에서 다룰 보안 우려의 출발점이기도 하다.

여기서부터는 공개된 정보를 종합한 추정이다.

기존 Claude in Slack은 사용자별 계정 연결을 바탕으로 동작했다. 반면 Claude Tag는 채널이 메모리를 공유하고, 조직이 provision한 Agent Identity가 도구에 접근하는 방식으로 바뀐다. 공식 문서는 Claude Tag가 채널 메모리와 세션 트랜스크립트를 보존하기 때문에, Zero Data Retention(ZDR, 데이터를 아예 남기지 않는 정책)을 켠 회사에는 제공되지 않는다고 명시한다.

보안 설계에서 더 중요한 부분은 Agent Proxy다.

연결에 필요한 자격증명(비밀번호나 인증 토큰 같은 것)은 샌드박스 안에 직접 들어가지 않는다.

별도 저장소(credential store)에 보관되고, 외부 시스템에 요청을 보낼 때만 Agent Proxy가 허용 규칙을 확인한 뒤 그 경계에서 자격증명을 붙인다.

샌드박스에서 나가는 HTTP/HTTPS 요청은 Agent Proxy에서 connection rule, bundle의 domain list, environment network access 중 하나에 허용되어야 한다. 아무 규칙에도 걸리지 않으면 인증 실패가 아니라 요청 자체가 차단된다. 다만 기본 Trusted 환경의 개발자 호스트 허용, 조직이 별도로 켠 allow-all egress, 서버 측 web search처럼 별도 경로도 있으므로 "무조건 모든 외부 요청이 막힌다"로 단순화하면 안 된다.

항목	공개된 설계	근거 수준
실행 환경	Anthropic이 관리하는 임시 격리 공간	공식 문서(확정)
접근 범위	사람이 아니라 채널 단위로 결정	공식 문서(확정)
메모리 모델	공개 채널은 회사 전체 공유, 비공개 채널은 그 채널만의 저장소	공식 문서(확정)
자격증명 처리	샌드박스가 아닌 별도 저장소에 보관, 경계에서만 주입	공식 문서(확정)
네트워크 정책	connection rule·domain list·environment network access에 없는 요청은 기본 차단	공식 문서(확정)
ZDR 지원	채널 메모리·세션 트랜스크립트를 보존하기 때문에 ZDR 회사는 이용 불가	공식 문서(확정)

표를 한 줄로 요약하면 이렇다 — 접근 권한이 "누가"가 아니라 "어느 채널"로 정해지므로, 채널 멤버 관리가 곧 보안 경계다.

채널 스코프 격리, 실무에서 뭘 뜻하나

Enterprise 플랜에는 Claude Tag를 쓸 수 있는 사람을 제한하는 기능(역할 기반 Member Access)이 있다. 하지만 한 채널에 붙은 서비스 계정 권한은 그 채널에 있는 사람이라면 누구나 함께 쓴다.

그래서 민감한 도구를 연결한 채널일수록 두 가지를 따로 확인해야 한다. "누가 Claude Tag를 호출할 수 있는가"와 "그 채널의 서비스 계정이 어디까지 손댈 수 있는가."

5. 실전 활용 시나리오 4가지 — 언제·어떻게 쓰는가

Claude Tag가 실무에서 진짜 쓸모 있어지는 순간을 네 가지로 정리했다. 공통점은 하나다 — "Slack 채널에 이미 있는 맥락을 그대로 활용한다."

5-1. 소프트웨어 엔지니어링 — 조사부터 PR까지 위임

엔지니어가 채널에서 이렇게 태그한다고 해보자.

@Claude can you investigate this latency spike and open a PR with a fix?

(@Claude, 이 지연(latency) 급증 원인을 분석하고, 수정한 뒤 PR까지 생성해 줄래?)

이 한 줄만으로 지연 급증의 원인 조사부터 수정 PR 생성까지 통째로 넘어간다.

엔지니어는 부탁만 해두고 다른 작업으로 넘어가면 된다. 결과(PR)가 나오면 스레드에서 확인만 하면 끝. 결과물이 눈으로 딱 확인되는 작업이라, 위임 효과를 가장 체감하기 쉬운 시나리오다.

5-2. PM·데이터 분석 — 지표 쿼리를 스레드에서 바로

제품 매니저가 지표(수치) 조회를 부탁하면, 결과가 그대로 채널 스레드에 뜬다.

분석 도구를 따로 열거나 데이터팀에 별도로 요청할 필요가 없다. 지금 논의 중인 그 채널에서 바로 숫자를 받아본다. 결정을 위한 대화와 데이터 조회 사이를 왔다갔다하는 시간을 줄여준다.

5-3. 고객 지원 — 티켓 전반의 패턴 발견과 팔로업

고객 지원 업무에서는 Claude가 여러 티켓을 가로질러 반복되는 패턴을 발견해준다.

아직 해결 안 된 이슈도 놓치지 않고 계속 챙긴다. 티켓 하나하나 대응하는 게 아니라, 흩어진 티켓들에서 공통된 신호를 찾아내는 역할이다. 지원 채널에 계속 상주하며 맥락을 쌓아가는 구조라서 가능한 활용이다.

5-4. 크로스팀 조율 — 부서 간 연결 지점 표면화

서로 다른 부서가 각자 하는 작업 사이에서 연결 지점을 찾아 드러내준다. 한 팀의 진행 상황이 다른 팀 일과 어떻게 맞물려 있는지 눈에 보이게 해주는 게 목적이다.

여러 채널을 함께 지켜보는 에이전트일수록 이 활용의 가치가 커진다.

네 시나리오를 표로 정리하면 다음과 같다.

시나리오	누가 쓰나	부탁 예시	결과
엔지니어링	개발팀	"레이턴시 조사하고 수정 PR 열어줘"	원인 분석 + PR 생성
PM·데이터	제품/데이터팀	지표 쿼리 부탁	결과가 스레드에 바로 표시
고객 지원	CS팀	티켓 패턴 분석 요청	공통 패턴 발견·미해결 추적
크로스팀	여러 부서	부서 간 작업 연결 확인	연결 지점 표면화

네 시나리오의 공통점은 명확하다. 별도 도구로 맥락을 옮길 필요 없이, Slack에 이미 있는 대화·티켓·지표 논의를 그대로 쓴다는 점이다.

반대로 중요한 자료가 채널 밖에 있거나, 결과를 사람이 매번 승인해야 하는 작업이라면 효과가 제한적이다.

"우리 팀 맥락이 어디에 모여 있는가"가 도입 여부를 가르는 첫 질문인 셈이다.

처음 써본다면

5-1 엔지니어링 시나리오처럼, 결과물이 명확한 작업부터 시작하는 게 낫다.

PR·테스트 통과·쿼리 결과처럼 "됐는지 안 됐는지"가 딱 보이는 작업이 위임 효과를 가장 체감하기 쉽다.

"코드 품질을 높여줘"처럼 끝이 뭔지 애매한 작업은 나중으로 미뤄두자.

6. 요금제와 제한사항

앞서 초반에 확인했듯, Claude Tag는 Team·Enterprise 전용이다. 개인 무료·Pro·Max 요금제로는 이용할 수 없다. 아래 내용은 회사가 이미 Team·Enterprise인 경우를 전제로 한 비용·제한 이야기다.

채널과 스레드에서 쓰는 Claude Tag 사용량은 회사(조직) 단위 usage balance(사용량 잔액)에서 깎인다. 사용자 1인당 추가 요금은 없다.

단, 예외가 있다. Direct Message(DM)로 Claude에게 직접 보내는 메시지는 회사 잔액이 아니라 개인 claude.ai 계정 한도에서 깎인다. 같은 Claude라도 "채널에서 쓸 때"와 "개인 DM으로 쓸 때"는 요금이 청구되는 곳이 다르다는 점, 꼭 구분해두자.

비용을 통제할 수단도 있다. 관리자는 회사 전체 또는 채널별로 지출 한도를 정할 수 있고, 사용량 분석 페이지에서 채널별 breakdown을 볼 수 있다. 단가 예측은 아직 어렵다. 공식 문서도 파일럿에서는 먼저 지출 한도를 작게 잡고 채널별 사용량을 보며 조정하라고 안내한다.

단, 이게 ZDR(Zero Data Retention, 데이터 완전 미보존) 지원을 뜻하는 건 아니다.

공식 보안 문서는 Claude Tag가 채널 메모리와 세션 트랜스크립트를 보존하기 때문에, ZDR을 켠 회사에서는 아예 쓸 수 없다고 밝히고 있다. 또한 Slack에서 Claude를 제거하거나 scope를 끄는 것만으로 메모리·루틴·트랜스크립트가 자동 삭제된다고 보면 안 된다. 삭제는 Claude 콘솔의 전용 삭제 controls와 Slack 보존 정책을 분리해 확인해야 한다.

항목	내용
채널·스레드 작업	회사(조직) usage balance에서 차감
개인 DM	개인 claude.ai 계정 한도에서 차감
좌석 요금	1인당 추가 요금 없음
지출 통제	조직 전체·채널별 지출 한도와 채널별 사용량 breakdown 확인
데이터 보존	제거·Off·scope 변경만으로 자동 삭제되지 않음. 전용 삭제 controls와 Slack 보존 정책 확인 필요
ZDR 회사	채널 메모리·세션 트랜스크립트를 보존하기 때문에 이용 불가

구체적인 단가는 베타 단계라 앞으로 바뀔 가능성이 크다. (2026-07-01 기준이며, 최신 가격은 공식 페이지에서 확인하자.)

비용 통제 팁

쓴 만큼 청구되는 구조라, 사람이 많이 오가는 채널에서 Claude가 먼저 응답하거나 루틴을 자주 돌면 사용량이 예상보다 빨리 쌓일 수 있다. 도입 초반에는 지출 한도를 보수적으로 잡고, usage page에서 채널별 사용량을 확인할 담당자를 미리 정해두자.

알려진 제한도 분명히 짚고 가자.

Claude Tag는 현재 Slack 전용이다. Microsoft Teams 같은 다른 협업 도구는 지원하지 않는다. 또한 이 글에서 확인한 공식 문서 범위에서는 Ambient 동작이나 루틴 작업 전에 별도 human approval 흐름이 핵심 통제로 제시된 것을 확인하지 못했다. 그래서 민감한 작업은 낮은 권한의 서비스 계정, 제한된 channel scope, spend limit, audit 확인을 전제로 파일럿부터 시작하는 편이 안전하다.

권한 통제는 특히 정확하게 표현하고 넘어가야 한다.

공식 문서 기준으로 Enterprise에는 역할 기반 Member Access가 있어서, 관리자가 Claude Tag를 부를 수 있는 사람을 제한할 수 있다. 하지만 연결된 서비스 계정의 권한 자체는, 그 채널에 들어와 있는 사람이라면 누구든 함께 쓰는 구조다.

보안 검토 포인트 (커뮤니티가 특히 우려하는 부분)

채널 접근 권한이 곧 도구 사용 가능성으로 이어질 수 있다. 그래서 외부 협력사나 일부 인원만 들어와야 하는 채널에 민감한 connector나 서비스 계정 권한을 붙이는 건 위험하다.

공식 문서상 게스트가 포함된 채널은 기본적으로 꺼져 있고, Slack Connect 채널은 항상 꺼져 있다. 그래도 내부 채널 안의 멤버 구성과 서비스 계정 범위는 별개 문제다.

도입 전에 "이 채널에 누가 들어와 있고, Claude의 서비스 계정이 어떤 도구까지 손댈 수 있는가"를 꼭 점검하자.

정리하면 비용은 지출 한도로 통제 가능한 변수다.

더 신경 써야 할 쪽은 서비스 계정 권한 공유, ZDR 미지원, 능동 동작의 승인·감사 절차다.

전자는 채널과 접근 권한(Access bundle)을 잘게 나눠 관리하고, 후자는 위험이 낮은 채널부터 조심스럽게 적용 범위를 넓혀가는 게 현실적이다.

7. 대안 비교 — Claude.ai 채팅·API 직접 호출 대비

Claude Tag의 위치를 가장 또렷하게 보여주는 비교는 기존 Claude in Slack과의 대비다.

기존 통합은 사용자별로 나뉜, 저장이 안 되는(stateless) 방식이었다.

Claude Tag는 계속 이어지는 메모리·회사 단위 아이덴티티·관리자가 정한 도구 접근을 갖춘 "하나의 공유 Claude"다.

같은 Slack 연동이라도, 분리된 개인 세션에서 공유하는 동료로 성격이 바뀐 셈이다.

Claude.ai 채팅, API 직접 호출과의 비교는 공개된 정보를 종합해서 정리한 것이다.

Claude.ai 채팅은 개인의 단일 세션에서 사람이 직접 주고받는 작업에 맞고, API 직접 호출은 프로그래밍으로 자동화하거나 비용을 아끼는 데 강하다.

Claude Tag는 개발자가 아니어도 Slack에서 바로 팀 협업 워크플로우를 굴릴 수 있다는 점에서, 셋 중 진입 장벽이 가장 낮다.

비교 기준	Claude.ai 채팅	API 직접 호출	Claude Tag
누가 쓰나	개인	프로그램·애플리케이션	팀 채널 전체
대화 맥락	1개 세션 안에서만	요청할 때마다 새로	채널이 공유하며 계속 이어짐
시작하기 쉬운 정도	쉬움	어려움(코딩 필요)	쉬움(Slack에서 바로)
잘 맞는 작업	1:1 대화·개인 작업	자동화·앱 개발	팀 단위 위임·비동기 실행

한 줄로 정리하면, Claude.ai 채팅은 개인의 대화를, API는 개발자의 자동화를, Claude Tag는 팀의 위임을 각각 최적화한 도구다.

셋은 서로 대체하는 경쟁 관계가 아니라, 쓰이는 층위 자체가 다르다.

팀이 이미 Slack에서 일하고 맥락이 거기 모여 있다면 Claude Tag가, 반복 작업을 코드로 자동화하고 싶다면 API가 더 맞는다.

8. 자주 묻는 질문과 결론

도입을 검토할 때 자주 나오는 질문부터 정리한다.

Q1. 개인 Pro·Max 요금제로도 쓸 수 있나?

아니다. 조직(회사)이 Team 또는 Enterprise 플랜일 때만 관리자가 켤 수 있다. 개인 무료·Pro·Max 요금제로는 우회 방법이 없다. 자세한 근거는 글 맨 위 첫 박스에서 확인할 수 있다.

Q2. Microsoft Teams나 다른 메신저에서도 되나?

지금은 Slack 전용이다. 다른 협업 도구는 지원하지 않으므로, Slack을 쓰지 않는 팀에는 현재로선 선택지가 아니다.

Q3. 사람 수가 늘면 1인당 요금이 붙나?

좌석 요금은 없다. 채널·스레드 작업은 회사 usage balance에서 차감되고, 개인 DM만 개인 계정 한도를 쓴다. 인원 수보다 실제 사용량이 비용을 좌우한다.

Q4. Ambient 동작을 켜도 괜찮은가?

이 글에서 확인한 공식 문서 범위에서는 행동 전 별도 승인 흐름을 핵심 통제로 확인하지 못했다. 민감한 작업이 오가는 채널에서는 신중해야 하며, 트래픽이 적고 위험이 낮은 채널부터 제한적으로 켜 보는 걸 권장한다. 너무 자주 끼어들면, 스레드 단위로 "멘션할 때만 답하라"고 지시하거나 채널 메모리에 같은 규칙을 저장해두면 된다.

Q5. ZDR(Zero Data Retention)이 필요한 회사도 쓸 수 있나?

아니다. 공식 문서 기준으로 Claude Tag는 채널 메모리와 세션 트랜스크립트를 보존하기 때문에, ZDR을 켠 회사에는 제공되지 않는다. 보안 검토에서 가장 먼저 확인해야 할 조건이다.

Q6. 기존 Claude in Slack을 쓰고 있는데 그대로 둬도 되나?

2026년 8월 3일에 Claude Tag 경험으로 전환될 예정이다. 다만 기존 사용자별 연결이 그대로 옮겨지는 것은 아니므로, Access bundle, GitHub 저장소, 서비스 계정 권한을 전환 전에 별도로 점검해야 한다.

이제 "지금 도입할지, 좀 더 기다릴지"를 정리해보자.

상황	판단
Team·Enterprise 고객이고 Slack에 맥락이 모여 있다	지금 도입 검토
결과물이 명확한 위임 작업(PR·쿼리 등)이 많다	지금 도입 검토
개인 Pro·Max 요금제만 쓰고 있다	현재 도입 불가·대기
외부 인력과 민감 도구가 한 채널에 섞인다	서비스 계정 범위 분리 후 도입
Microsoft Teams 중심으로 일한다	Slack 지원 전까지 대기
무인 능동 동작(Ambient)에 대한 사내 승인 절차가 없다	범위 제한 후 점진 도입
ZDR이 필수인 회사다	현재 도입 불가

도입 전 체크리스트

우리 회사가 Team·Enterprise 플랜인지부터 확인한다 (개인 Pro·Max로는 불가)
Claude 조직 Owner/Primary Owner와 Slack 승인 담당자가 누구인지 확인한다
첫 연결 채널을 비공개 테스트 채널로 좁게 잡는다
지출 한도를 보수적으로 설정하고 usage page 확인 담당자를 정한다
민감 도구를 붙일 채널의 멤버 구성을 점검한다
ZDR 요구사항, 감사 로그 확인 방식, 서비스 계정 범위를 보안팀과 먼저 맞춘다

Claude Tag는 "팀 채널 안의 공유 Claude에게 일을 맡긴다"는 한 문장으로 압축된다.

강점은 Slack에 이미 흐르는 맥락을 그대로 쓴다는 점이다. 지금의 약점은 개인 Pro·Max 요금제로는 못 쓴다는 점, 서비스 계정 권한이 채널 전체에 공유된다는 점, ZDR 미지원, 능동 응답·루틴 작업의 승인 절차를 조직이 별도로 설계해야 한다는 점, 그리고 Slack 전용이라는 범위다.

기술 체크리스트 밖의 비용 — 조직 운영

앞선 체크리스트는 전부 통제 가능한 기술적 변수다. 다만 Claude가 채널에서 먼저 답하고 루틴까지 맡기 시작하면, 사람이 언제 검토하고 언제 직접 결정할지에 대한 운영 규칙도 필요하다.

특히 PR 생성, 고객 응답, 데이터 조회처럼 결과가 실제 시스템에 남는 작업은 "Claude가 할 수 있는가"보다 "사람이 어디서 확인하고 승인하는가"를 먼저 정해두는 편이 안전하다.

오늘 바로 해볼 것

Team·Enterprise 관리자라면 claude.ai/admin-settings/claude-tag에서 비공개 채널 하나를 연결하고, 지출 한도를 보수적으로 잡은 뒤 결과물이 명확한 작업 하나(예: "레이턴시 조사하고 수정 PR 열기")로 먼저 돌려보자.

기존 Claude in Slack을 쓰고 있다면, 8월 3일 전환 전 마이그레이션 일정부터 잡아두자.

개인 Pro·Max 사용자라면, 지금은 회사 요금제가 바뀔 때를 대비해 이 글을 저장해두는 정도로 충분하다.

참고 자료

공식 발표·제품 페이지

공식 문서

공식 지원 문서

작성일: 2026-07-01 (초보자 가독성 개선판: 2026-07-06)

대상: Claude Tag (Team·Enterprise 베타, 2026년 6월 공개)

이 글은 2026-07-06 기준 공개 정보로 작성됐다. 베타 기능이라 이후 기능·요금·제한이 바뀔 수 있으니, 도입 전 공식 문서에서 최신 내용을 확인하는 것을 권장한다.

ZCode란? GLM-5.2 + ZCode 사용방법 - GLM 제작사가 만든 Claude Code 대항마(z.ai 가입, GLM Coding Plan, API 키 발급 등)

갓대희 — Thu, 2 Jul 2026 19:00:05 +0900

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

Claude Code나 Codex 구독료가 부담스러워 대안을 찾는 개발자가 늘었다. 그 대안으로 최근 다시 화제가 된 것이 ZCode다.

Hacker News에 ZCode: Claude Code from the Makers of GLM이라는 제목으로 올라오면서 주목을 받았는데, 사실 이 제품은 이번에 처음 나온 신제품이 아니라 이미 6월부터 다뤄져 온 도구다.

그런데 막상 검토하려고 보면 벽에 부딪힌다. ZCode가 정확히 무엇인지, GLM Coding Plan은 얼마이고 무슨 모델을 쓰는지, z.ai 계정은 어떻게 만들고 API 키는 어디서 받는지 — 한국어로 정리된 입문 안내가 드물다. 공식 문서는 대부분 영어이고, 오래된 가격을 그대로 옮긴 글도 섞여 있다.

이 글에서는 딥다이브가 아니라 제품 개요와 가입 온보딩에 초점을 맞춰 보려고 한다.

ZCode가 무엇인지, GLM Coding Plan 현재 가격(2026-07-02 기준)과 가입·API 키 발급 절차, 그리고 Claude Code 사용자가 전환을 검토할 때 참고할 판단 기준까지 공개 정보로 확인 가능한 선에서 정리해보려고 한다.

이 글은 2026년 7월 2일 기준으로 작성됐다. 공식 소스: ZCode 공식 사이트, z.ai DevPack Quickstart, GLM Coding Plan 구독 페이지. 가격·모델·한도는 업데이트마다 달라질 수 있으므로 최신 공식 문서를 함께 확인하기를 권장한다.

이 글의 핵심 6가지

ZCode는 명령줄 도구가 아니라 z.ai가 만든 데스크톱 앱이다 — 스스로를 GLM-5.2의 Official Harness(공식 하네스)로 소개한다
GLM Coding Plan 정가는 Lite $18 / Pro $72 / Max $160(월)이며, 결제주기에 따라 상시 -10%~-30% 할인된다
가입은 z.ai 계정 로그인 → 플랜 구독 → API 키 발급, 3단계로 정리된다
GLM Coding Plan은 ZCode 전용이 아니라 Claude Code를 포함한 20개 이상 도구에서 쓸 수 있다
지원 모델은 전 플랜 공통 GLM-5.2 / GLM-5-Turbo / GLM-4.7이다
z.ai(구 Zhipu AI)의 미국 Entity List 등재 이력은 과장 없이 사실로만 짚고 넘어간다

ZCode란 무엇인가 — GLM 제작사가 만든 데스크톱 코딩 에이전트
시작하기 — z.ai 가입부터 API 키 발급까지
주요 기능 — Goals·원격 개발·봇 제어·GLM-5.2 통합
공개 정보 기반 아키텍처 추정
실전 사용 경험 — 공개 리뷰와 커뮤니티 반응
요금제·quota와 지원 모델
대안 비교 — GLM Coding Plan은 ZCode 전용이 아니다
트러블슈팅 Q&A + 결론

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

ZCode: z.ai가 만든 개발용 데스크톱 앱 (명령줄이 아니라 창을 띄워 쓰는 프로그램)
GLM-5.2: z.ai의 코딩·추론용 AI 모델
GLM Coding Plan: z.ai의 코딩 전용 월정액 구독 요금제
하네스(Harness): 모델을 실제 코딩 작업에 연결해 돌려 주는 실행 껍데기
API 키: 내 계정으로 AI를 호출할 때 쓰는 비밀번호 같은 문자열
quota: 플랜에 포함된 사용 한도 (쓸수록 줄어든다)
endpoint(엔드포인트): API 요청을 보내는 인터넷 주소
MCP: AI에 외부 도구를 붙이는 표준 연결 규격

1. ZCode란 무엇인가 — GLM 제작사가 만든 데스크톱 코딩 에이전트

ZCode는 z.ai(구 Zhipu AI)가 만든 데스크톱 코딩 에이전트 앱이다.

공식 사이트는 스스로를 "Official Harness for GLM-5.2", 즉 GLM-5.2를 실제 코딩에 붙여 돌리는 공식 하네스로 소개하고, 슬로건은 "Simple, Fast, Vibe-Ready"다 (출처: ZCode 공식 사이트). 여기서 하네스라는 표현이 핵심이다. 모델(GLM-5.2)이 엔진이라면, ZCode는 그 엔진을 코딩 작업에 연결해 돌리는 차체에 해당한다.

공식 문서는 ZCode를 Agentic Development Environment(ADE)로 정의한다.

ADE는 AI 에이전트가 계획·실행·검증까지 이어서 맡는 개발 환경이라는 뜻이다. 마우스로 클릭해 쓰는 그래픽 화면(GUI) 형태라는 점에서, 터미널에 명령어를 입력해 쓰는 Claude Code나 Codex 같은 CLI 도구와 포지셔닝이 다르다. 실제로 Hacker News 스레드 제목도 Claude Code from the Makers of GLM으로, 이 도구를 Claude Code의 대항마로 읽는 시선이 분명하다.

배너를 보면 "ZCode 3.0: GLM-5.2 optimized, better multi-agent collaboration"이 걸려 있고, 확인 시점의 최신 버전은 3.2.2다. 이미 3.x 대에 올라 있다는 점은, 이 제품이 이번에 급조된 신제품이 아니라 몇 차례 메이저 업데이트를 거친 도구임을 보여준다.

코딩 성능은 이미 너무 좋다고 알려져 있고, 벤치마크 수치를 확인하는건 크게 의미가 없을 것 같아 넘어가려 한다.

1-1. 지원 플랫폼과 다운로드 형식

설치 파일은 세 운영체제(OS)를 모두 지원한다.

다운로드 섹션은 모든 플랫폼용 설치 파일을 안내하며, 아래 표처럼 8종 빌드가 나열된다.

OS	지원 아키텍처	설치 형식
macOS	Apple Silicon / Intel	.dmg
Windows	64-bit / ARM64	.exe
Linux (베타)	x64 / ARM64	.deb / .AppImage

표에서 눈여겨볼 지점은 Linux가 아직 베타로 표기된다는 것이다. macOS·Windows는 정식, Linux는 베타 단계이므로, 리눅스 상시 운영 환경에 바로 올리려는 경우라면 안정성을 먼저 확인하는 편이 낫다.

zcode.z.ai/en — 슬로건 Simple, Fast, Vibe-Ready와 플랫폼별 다운로드 버튼
1) https://zcode.z.ai/en 접속

2) Download Zcode를 누르면 다운로드가 시작된다.
3) 제일 하단에 OS별 다운로드 페이지가 별도 존재 하긴 하지만, 상단 Download ZCode 버튼을 누르면 된다.

4) 다운로드된 파일을 더블 클릭하여 설치 하자.

5) 설치가 되는동안 이어서 회원 가입 및 키 발급까지 진행 해보자.

2. 시작하기 — z.ai 가입부터 API 키 발급까지

GLM Coding Plan을 쓰려면 z.ai 계정 로그인 → 플랜 구독 → API 키 발급, 이 세 단계를 거친다.

공식 Quickstart 문서의 흐름을 입문자 기준으로 풀어 정리한다.

2-1. z.ai 계정 만들고 플랜 구독하기

먼저 z.ai에 가입해 로그인한 뒤, 구독 페이지에서 원하는 플랜을 고른다. 공식 Quickstart는 이 단계를 Subscribe to GLM Coding Plan으로 안내한다. 구독은 아래 페이지에서 진행하면 된다.

플랜 구독(현재까진 친구 추천의 경우 10% 할인 제공) : z.ai/subscribe

ex) 친구 추천 링크 접속시 구독 요금의 10% 할인 프로모션이 아직 진행 되고 있다.

https://z.ai/subscribe?ic=BVEF1AVEI0

- Subscribe Now 버튼을 클릭 하자.

- 구독 플랜을 결정 해야 한다. Default가 요즘엔 연간 결제인것 같은데, 여기서 추가 10-0%가 할인 되는것 같다.

잘 보면 월간도 있지만, 쿼터, 연간 결제 방식이 별도로 존재한다.

- 나의 경우 예전에 Quarterly로 구독 했는데, 그사이에 GLM이 인기가 올라가고, 성능이 좋아지면서 가격이 너무 많이 올랐어서 후회하고 있다. 예전 가격이 궁금하시다면 ... 다음글도 참고. 캡쳐해 두었다.

Open Code 리뷰(4) : OpenCode(oh-my-opencode)에 Z.ai GLM 연동하기(with claude code Z.aiGLM연동)

- 원하는 플랜을 선택하고 Subscribe 를 누르면 로그인 안내를 할 것 이다. 로그인 해주자.

- 그리고 다시 Subscribe 구독 버튼을 누르면 되는데

GLM 연간 구독, Pro Plan정도로 한다고 했을때 비용을 계산 해보겠다.

- 지금 환율이 너무 비싸서...

1) 할인전 정가 : $864 = 약 연간 133만원 / 매월 11만원씩

2) 할인 후 가격 : $544.32 = 약 연간 84만원 / 매월 7만원씩

할인 전 / 할인 후 가격

- 원하는 플랜으로 진행해보자.

2-2. API 키 발급하기

구독을 마쳤다면 API 키를 발급한다. 공식 Quickstart는 이 단계를 Obtain API Key로 부른다. 발급 위치는 가입 형태에 따라 갈린다.

개인(Individual) 플랜: Individual Coding Plan > Plan Overview 메뉴에서 발급
팀(Team) 플랜: Team Coding Plan > My Plan 메뉴에서 발급

여기서 한 가지 함정이 있다. 팀 플랜 키는 다른 Z.AI API 키와 호환되지 않는다. 따라서 팀 플랜 quota를 쓰려면 팀 플랜 키를 써야 한다 (출처: z.ai DevPack Quickstart).

개인용과 팀용을 섞어 쓰다 인증이 어긋나는 경우가 의외로 잦으므로, 발급 화면에서 어떤 트랙의 키인지 먼저 확인한다.

z.ai 로그인 후 API 키 관리 콘솔 접속 : https://z.ai/manage-apikey/apikey-list
- Add Api Key 클릭

- 본인이 원하는 키 이름 입력

- 생성된 API Key를 확인하고 복사해주자.

2-3. 코딩 도구에 연결하기

GLM Coding Plan은 Anthropic·OpenAI 두 프로토콜을 모두 지원한다.

덕분에 Claude 계열 도구와 OpenAI 계열 도구 양쪽에 같은 구독을 붙일 수 있다. 연결 자체는 원클릭 설정 스크립트로 처리할 수 있다.

npx @z_ai/coding-helper

이 명령은 z.ai가 제공하는 Coding Tool Helper를 실행해, GLM 코딩 패키지를 원하는 코딩 도구에 자동으로 붙여 준다. 도구별 설정 파일을 손으로 편집하지 않아도 되므로 입문자에게 특히 편하다.

ex) npx @z_ai/coding-helper

- EN : 디폴트로 진행하자.

- Global 선택

- API 키를 입력 요구한다.

- 키를 입력하고

- 어떤 코딩툴에 붙일지 선택하면되는데, Claude Code를 선택해도 좋고, 나의 경우 개인적으로는 OpenCode에 GLM을 붙이고, ClaudeCode는 클로드 코드대로 사용 하였었다.

- 오늘은 클로드 코드 선택해보려 한다.

- Apply Configuration 클릭

- 언제든지 설정은 제거 가능하다.

- Start Claude Code를 선택해보자.

- 나의 경우 제대로 동작하지 않아 지우고 다시 설치

- 하기와 같은 경고가 뜨면, 정상적으로 적용됫다고 볼 수 있을 것 이다.

- 난 지금 현재 구독이 끊긴 상태이지만, 클로드 코드에서 GLM을 쉽게 사용 가능하도록 설정해주는것을 볼 수 있다.

- 다만 난 둘다 동시에 사용하고싶어서 클로드 설정은 되돌려 두도록 하겠다.

API 키 방식으로 직접 연결할 때 주의할 점이 하나 더 있다. z.ai를 붙일 때는 코딩 전용 엔드포인트를 써야 한다.

주의 — 엔드포인트를 헷갈리면 인증이 실패한다

코딩 연결에는 https://api.z.ai/api/coding/paas/v4(코딩 전용 주소)를 써야 하며, 일반 엔드포인트 https://api.z.ai/api/paas/v4로 바꿔 넣으면 안 된다.
( 위에서 npx @z_ai/coding-helper를 통해 예시로 설정이 클로드 코드 엔드 포인트가 아닌 z.ai 코딩 플랜으로 변경해 주는걸 자동으로 해주는 방식 이라고 보면 된다. )

공식 문서가 "Do not replace the Coding endpoint with the general endpoint"이라고 명시한 부분이다 (출처: ZCode Configuration 문서).

ZCode 앱 자체에서 쓸 때는 더 간단하다.

앱에서 z.ai 계정으로 로그인하면, 그 계정에 GLM Coding Plan이 있을 경우 플랜과 quota가 자동으로 연동된다.

즉 API 키를 손으로 복사·붙여넣기 하지 않아도 된다. 앱 안에서 로그인 한 번으로 붙는 방식이므로, 터미널 설정이 낯선 입문자라면 API 키 직접 연결보다 앱 로그인 쪽이 진입 장벽이 낮다.

그럼 이제 아까 설치한 ZCode를 실행해보자.

- Connect to Z.ai 를 클릭

- 인증 해 주자.

- ZCode 열기 클릭

- 코덱스 App. 클로드 코워크, 커서와 같은 UI의 IDE가 활성화되는것을 볼 수 있다.

- 지금 정말 핫한 GLM-5.2가 Default로 선택되어있는 것을 볼 수 있다.

- 사용중인 세션의 Context windows도 시각적으로 표현 된다.

- 원하는 프로젝트를 열고 시작해볼 준비를 하자.

- 원하는 내용을 요청 해보자.

- 사이드 바에서 스킬, 서브에이전트, MCP 등등을 설정 가능하고 사용량 또한 모니터링하며 사용 가능하다.

- 사용량

- 내가 사용하던 스킬들이 적용되는 모습

- AOS emulator, IOS simulator가 눈에 띈다.

3. 주요 기능 — Goals·원격 개발·봇 제어·GLM-5.2 통합

ZCode의 기능은 크게 네 갈래다. 아래 표로 먼저 정리하고, 이어서 각 기능이 실제로 어떤 상황을 겨냥하는지 짚는다.

기능	무엇을 하나
Goals	장기 작업을 지속적인 계획·실행·검증으로 관리
Bot control	WeChat·Feishu·Telegram에서 원격으로 시작·제어
원격 개발	SSH 원격 호스트 / Docker 로컬 컨테이너 접속
GLM-5.2 딥 통합	추론·코딩·멀티에이전트 협업 전반 최적화

네 기능을 한 줄로 종합하면, ZCode는 한 대의 데스크톱에서 시작한 작업을 폰·메신저·원격 서버로 이어 가는 연속성에 무게를 둔 도구다.

3-1. Goals — 장기 작업 관리

Goals는 여러 턴에 걸친 긴 작업을 계획·실행·검증으로 이어 관리하는 기능이다.

이름과 개념이 Claude Code의 /goal과 겹치는데, 완료 조건을 향해 스스로 반복 작업한다는 취지에서 방향이 비슷하다.

검증 가능한 종료 상태가 있는 작업(예: 테스트 통과)일수록 이런 목표 기반 루프의 이점이 크다.

3-2. 원격 개발과 봇 제어

원격 접속은 두 진입점으로 나뉜다.

휴대폰으로 QR 코드를 스캔해 현재 워크스페이스를 제어하는 Remote Control, 그리고 WeChat·Feishu에서 워크스페이스를 여는 Bot Channel이다 (출처: ZCode ADE Tools 문서).

- 좌측 하단 프로필 우측에 위치 하고 있다.

- QR코드 스캔도 가능하다.

원격 개발 진입 방식으로는 SSH 원격 호스트(원격 서버·개발 머신용)와 Docker 로컬 컨테이너(기존 로컬 컨테이너 환경 진입용) 두 옵션을 제공한다.

여기서 Feishu·WeChat은 중국 협업 메신저라는 점을 감안할 필요가 있다.

국내 사용자 입장에서는 Telegram 정도가 현실적인 원격 트리거 경로이며, 봇 채널의 실효성은 어떤 메신저를 이미 쓰고 있느냐에 따라 갈린다.

3-3. GLM-5.2 딥 통합

ZCode는 추론·코딩·멀티에이전트 협업 전반에서 GLM-5.2에 맞춰 최적화됐다.

z.ai 공식 블로그도 ZCode를 GLM-5.2로 구동되는 데스크톱 에이전트로,

/goal 장기 작업·SSH 원격 개발·모바일 제어를 갖춘 도구로 소개한다.

모델 제작사가 직접 만든 하네스인 만큼 모델과 앱의 결합도가 높다는 점이, 서드파티 도구와 구분되는 이 제품의 특징이다.

ex)

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

여기부터는 공식 아키텍처 다이어그램이 공개돼 있지 않아, 공개된 구성 요소로부터 구조를 추정한 내용이다. 확정된 사실이 아니라 추정임을 먼저 밝힌다.

공개된 조각을 모아 보면 다음과 같다. 크로스플랫폼 네이티브 설치 패키지(데스크톱 중심), QR 스캔으로 붙는 모바일 Remote Control, WeChat·Feishu Bot Channel, SSH·Docker 원격 연결. 이 조합으로 미루어, ZCode는 데스크톱 클라이언트가 실행 주체이고 모바일·봇 채널·원격 호스트는 그 워크스페이스에 붙는 입력·모니터링 인터페이스로 연결되는 클라이언트 중심 구조로 추정된다.

이 추정을 뒷받침하는 외부 근거도 있다.

제3자 리뷰(bitdoze)는 모바일 원격 제어에 대해 실제 코드 실행은 전부 데스크톱에서 이뤄지고 폰은 화면 표시와 텍스트 입력만 담당한다고 설명한다. 데스크톱이 실행 중심이라는 앞선 추정과 맞물린다. 다만 공식 구조도가 없는 이상 이는 어디까지나 공개 정보 기반 추정이며, 내부 구현은 다를 수 있다.

5. 실전 사용 경험 — 공개 리뷰와 커뮤니티 반응

직접 장기간 운영한 경험 대신, 공개된 제3자 리뷰와 커뮤니티 반응으로 실사용 인상을 정리한다.

5-1. 공개 리뷰가 짚은 한계

가장 자주 지적되는 한계는 접근 경로가 좁다는 점이다. 공개된 리뷰를 보면 ZCode는 웹 버전도, VS Code 확장도 없이 데스크톱 앱으로만 제공된다는 점이 한계로 지적된다. 이미 VS Code 확장이나 웹 IDE 중심으로 일하는 팀이라면, 이 구조가 진입 장벽이 될 수 있다.

모바일 제어에도 제약이 있다. 같은 리뷰에 따르면 세션당 모바일 기기는 1대로 제한된다. 앞서 본 대로 폰은 화면 표시·텍스트 입력만 맡으므로, 모바일만으로 완결적인 개발을 기대하기보다 데스크톱 작업의 원격 보조 수단으로 보는 편이 현실적이다.

5-2. 커뮤니티 반응

Hacker News 스레드 "ZCode: Claude Code from the Makers of GLM"은 확인 시점(2026-07-02) 기준 약 267점, 댓글 12개였다. 이 수치는 계속 변동하므로 고정값으로 받아들이지 않는 편이 좋다. 상위 댓글은 모바일 언어 전환 UX의 불편, 그리고 Linux 베타 신청 링크가 영어 옵션 없는 중국 협업 앱(Feishu)으로만 연결된다는 국제화 접근성 우려에 초점이 맞춰졌다. 이 반응은 사실 단정이라기보다 커뮤니티의 체감이므로, 국제 사용자 편의성을 결정 기준으로 삼을 때 참고 신호 정도로 읽는 게 맞다.

도입 전에 알아둘 사실 — Entity List 등재 이력

z.ai(구 Zhipu AI)는 2025년 1월 미국 상무부에 의해 국가안보 우려를 이유로 Entity List에 등재된 이력이 있다 (출처: Wikipedia — Zhipu AI).

이는 위험이나 금지를 단정하는 근거가 아니라, 조직의 규제·데이터 정책상 벤더 선정 시 알아 두어야 할 사실 고지다.
조직 환경에 따라 판단 요소가 될 수 있으니 도입 전 자체 정책과 대조해 본다.

6. 요금제·quota와 지원 모델

이미 상기 섹션에서 한번 보여드리긴 했지만, 다시한번 정리해본다. 가격은 시간에 민감한 정보다.

아래 수치는 2026-07-02 기준이며, 최신 가격은 결제 전 공식 페이지에서 확인한다.

6-1. 플랜별 가격

GLM Coding Plan은 Lite·Pro·Max 세 등급이다. 정가와 연간 결제(-30%) 적용가는 다음과 같다.

플랜	정가(월)	Yearly -30% 적용가(월, 2년차부터)	연 환산	주요 사용량
Lite	$18	$12.6	$151.2	기본 사용량 + 20개+ 코딩 도구 지원
Pro	$72	$50.4	$604.8	Lite의 5배 + 엄선된 MCP 도구 + 빠른 생성
Max	$160	$112	$1,344	Lite의 20배 + 피크 시간대 전용 리소스

결제주기는 세 가지이며 각각 상시 할인이 붙는다. Monthly는 -10%, Quarterly는 -20%, Yearly는 -30%다 (출처: z.ai 구독 페이지). 위 표의 Pro $72→$50.4, Max $160→$112는 연간 -30% 적용가가 구독 페이지에 그대로 표기된 값이다.

한 줄로 종합하면, 정가는 Claude·OpenAI의 상위 구독과 비슷한 구간이지만 결제주기를 길게 잡을수록 실부담이 눈에 띄게 내려가는 구조다.

가격은 결제 직전 공식 페이지에서 재확인

플랜 가격과 할인율은 프로모션·시점에 따라 달라진다. 위 표는 2026-07-02 기준이며, 결제 직전 z.ai 구독 페이지에서 최신 금액을 확인한다. 과거 다른 글에 남아 있는 옛 가격을 현재가로 오해하지 않도록 주의한다.

6-2. quota — 5시간당 prompt 한도

quota는 prompt 단위로 계산된다. 플랜별 5시간당 prompt 한도는 다음과 같다.

플랜	5시간당 prompt 한도(근사)
Lite	약 80 prompts
Pro	약 400 prompts
Max	약 1,600 prompts

수치의 근거는 공식 DevPack FAQ다. 여기서 1 prompt는 단순한 한 번의 질문이 아니라, 보통 모델 호출 15~20회를 포함하는 단위이며 월 총 허용량은 수백억 토큰 규모로 안내된다. 즉 prompt 80개가 적어 보여도 실제 작업량은 그보다 훨씬 크다는 뜻이므로, 표의 숫자만 보고 부족하다고 지레짐작하지 않는 편이 낫다.

한 가지 더 감안할 점은 고급 모델의 quota 가중이다. GLM-5.2와 GLM-5-Turbo는 고급 모델로 분류돼, quota가 피크 시간대에는 표준의 3배, 오프피크에는 2배로 차감된다. 다만 여기에는 두 가지 별개의 완화 프로모션이 있으니 혼동하지 않도록 구분한다.

일반 GLM Coding Plan 프로모션: 9월 말까지 오프피크 사용이 1배로 청구된다.
ZCode 앱 한정 캠페인: 2026-07-31까지 ZCode 안에서 GLM-5.2를 쓰면 소모가 0.67배로 계산돼 실질 약 1.5배 quota 효과가 있다.

두 프로모션은 적용 범위(전체 Coding Plan vs ZCode 앱)와 종료일이 다르다. 앞의 것은 오프피크 시간대 전반에, 뒤의 것은 ZCode 앱 사용에 적용된다.

6-3. 지원 모델과 GLM-5.1 / GLM-5.2 관계

전 플랜 공통 지원 모델은 GLM-5.2, GLM-5-Turbo, GLM-4.7이다. 이 FAQ에는 GLM-5.1이 등장하지 않는다. 그렇다면 GLM-5.1과 GLM-5.2는 어떤 관계일까. 공식 블로그의 서술이 가장 명확한 단서다.

"It marks a substantial leap in long-horizon task capability over its predecessor GLM-5.1 and, for the first time, delivers that capability on a solid 1M-token context."

즉 z.ai는 GLM-5.2를 GLM-5.1의 후속작(predecessor GLM-5.1)으로 명시하고, 1M 토큰 컨텍스트를 처음으로 안정 지원한다고 밝힌다 (출처: z.ai 공식 블로그). 같은 블로그는 GLM Coding Plan 구독자에게 이미 GLM-5.2를 전원 롤아웃했다고도 적었다. 정리하면 코딩 플랜·ZCode 트랙의 표준 모델은 GLM-5.2로 봐도 무방하다.

다만 소비자용 챗봇(chat.z.ai)까지 같은 결론으로 묶기는 조심스럽다. 확인 시점의 chat.z.ai 페이지 타이틀은 "powered by GLM-5.2"로 표기되지만, 인앱에서 GLM-5.1 배너가 노출되는 경우도 관찰돼 왔다. 소비자 챗봇 트랙과 코딩 플랜 트랙의 모델 관계까지 단정할 근거는 아직 부족하므로, 이 글에서는 코딩 플랜 표준은 GLM-5.2까지만 확정하고 소비자 트랙은 별도일 가능성으로만 남겨 둔다.

7. 대안 비교 — GLM Coding Plan은 ZCode 전용이 아니다

ZCode를 검토하는 개발자가 가장 자주 놓치는 사실이 하나 있다. GLM Coding Plan은 ZCode 전용 구독이 아니다.

( 이밎 위 예시에서 클로드 코드에 GLM Coding Plan을 붙이는것을 보았을 것 이다.)

구독 페이지는 이 플랜이 Claude Code를 포함한 20개 이상 코딩 도구를 지원한다고 명시한다. 즉 GLM Coding Plan을 구독하고, 그 quota를 Claude Code·Cursor·Cline 같은 익숙한 도구에서 그대로 쓸 수 있다.

앞서 본 npx @z_ai/coding-helper 원클릭 스크립트가 이 연결을 담당한다. 이 점이 Claude Code 대항마라는 프레임을 다시 보게 만든다 — ZCode는 Claude Code를 대체하는 앱이면서, 동시에 GLM Coding Plan은 Claude Code와 함께 쓰는 모델 공급원이 될 수도 있다.

그래서 선택은 ZCode냐 Claude Code냐의 양자택일이 아니라, 아래 세 갈래에 가깝다.

원하는 것	현실적 선택
익숙한 CLI(Claude Code 등)를 유지하며 모델 비용만 낮추기	Coding Plan 구독 + 기존 도구에 연결
데스크톱 GUI + Goals·모바일 제어까지 한 앱에서	ZCode 앱 설치
웹 IDE·VS Code 확장이 필수인 워크플로우	현재 ZCode는 부적합(데스크톱 앱만 제공)

표를 한 줄로 종합하면, ZCode는 GLM을 가장 깊게 통합한 전용 앱이고 GLM Coding Plan은 여러 도구에 꽂아 쓰는 모델 구독이다. 두 층을 분리해 보면 도입 결정이 한결 단순해진다.

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

8-1. 자주 겪는 문제 Q&A

Q. 코딩 패키지를 샀는데 "1113 Insufficient Balance" 오류가 뜬다.

이 오류는 잔액 부족이 아니라 GLM Coding Plan 사용 조건을 벗어났을 때 나타나는 경우가 많다. 비공식 도구 사용, 엔드포인트 오설정, 비지원 모델 호출 등이 흔한 원인이다. 공식 문서도 구독 혜택은 공식 지원 도구·시나리오 안에서만 써야 한다고 못 박는다. 2-3절의 코딩 전용 엔드포인트(api/coding/paas/v4) 설정부터 다시 확인하는 편이 낫다.

Q. 승인 없이 자동 실행되는 모드는 그냥 켜도 되나?

공개된 리뷰는 승인 없이 자동 실행되는 'bypass' 계열 기능을 샌드박스나 버려도 되는 환경에서만 쓰라고 경고한다. 실제 저장소에 바로 적용하기보다, 격리된 환경에서 동작을 확인한 뒤 범위를 넓히는 순서를 권장한다.

8-2. 공식 가이드가 다루지 않는 부분

공식 문서가 잘 말하지 않는 현실

가격 표기가 국제판($)과 중국판(¥)으로 나뉘어, 통화를 혼동하기 쉽다. 이 글 수치는 전부 국제판 $ 기준이다.
봇 채널의 Feishu·WeChat은 중국 메신저라, 국내 환경에서는 Telegram 외 원격 트리거의 실효성이 낮을 수 있다.
Linux는 아직 베타이고 웹·VS Code 확장이 없어, 접근 경로가 데스크톱 앱으로 좁다.
프로모션 종료일(오프피크 1배, ZCode 1.5x)이 서로 달라, 캠페인 기간이 지나면 실부담이 달라진다.

8-3. 결론 — 전환 검토 체크리스트

Claude Code나 Codex를 쓰던 개발자가 ZCode·GLM Coding Plan을 검토한다면, 다음 순서로 자기 환경에 대입해 보면 된다.

무료 5일 혜택으로 ZCode를 실제 저장소에 붙여, quota 소모 속도를 직접 재 본다.
익숙한 CLI를 유지할지, 데스크톱 GUI로 옮길지 정한다. 전자라면 GLM Coding Plan만 구독해 Claude Code에 연결한다.
결제 직전 z.ai 구독 페이지에서 현재 가격과 결제주기별 할인을 확인한다.
조직 정책상 벤더 규제 이력(Entity List)이 문제되는지 내부 기준과 대조한다.

정리하면, 모델을 저렴하게 쓰는 것이 목적이면 Coding Plan 구독만으로 충분하고, GLM에 깊게 붙은 데스크톱 경험까지 원하면 ZCode 앱을 더한다. 오늘 당장 할 수 있는 첫걸음은 z.ai 구독 페이지에서 5일 무료 혜택으로 Lite 티어를 한 번 붙여 보는 것이다.

참고 자료

작성일: 2026-07-02

기준 버전: ZCode 3.2.2 (2026-07-02 확인 기준)

이 글은 2026-07-02 기준으로 작성됐다. 가격·모델·한도·프로모션은 이후 달라질 수 있다. 최신 내용은 공식 구독 페이지와 DevPack FAQ에서 확인할 수 있다.

Claude Sonnet 5 출시 : 공식 문서 살펴보기(주요 변화, 가격, 모델 ID, 플랜별 접근성, 1M 컨텍스트 등)

갓대희 — Wed, 1 Jul 2026 18:00:30 +0900

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

2026년 6월 30일, Anthropic이 Claude Sonnet 5를 발표했다. 같은 날 가격 페이지도 바뀌었다. 자세히 보면 어긋나는 대목이 있다. 9월부터 토큰당 단가는 Sonnet 4.6과 완전히 같아지지만 실제 청구액은 달라질 수 있다.

출시 첫 주라 정보가 많고 흩어져 있다. 발표문, 모델 문서, 가격 페이지, Claude Code 문서가 따로 움직이고, 어느 글을 봐도 "어떤 플랜에서 어떻게 쓰면 되는지"가 한곳에 모여 있지 않다. 모델 ID에 날짜를 붙여야 하는 줄 아는 사람도 있고 Claude Code에서 sonnet이라고만 치면 매번 Sonnet 5가 나온다고 생각하는 사람도 있다. 둘 다 공식 문서 기준으로는 맞지 않는다.

이 글에서는 출시 메시지와 벤치마크, 가격 정책, 플랜별 접근성, API·앱 실사용법, 한국 시장에서 달라지는 부분을 공식 발표와 문서 기준으로 정리한다. 코드를 안 써본 독자도 어떤 플랜으로 시작하면 되는지, 이미 Sonnet 4.6을 쓰던 개발자라면 무엇을 바꿔야 하는지 차례대로 확인하도록 구성했다.

이 글은 2026년 7월 1일 기준으로 작성됐다. 공식 소스: Anthropic 공식 발표 · Claude 모델 개요 문서

Claude 모델 출시 시리즈

미토스 5? 페이블 5? — Anthropic 신모델 출시 총정리, 이 글은 Fable 5가 직접 썼다 ← 이전 글
Claude Sonnet 5 출시 총정리 — 지금 가장 싸게 쓰는 법과 9월부터 달라지는 것들 [현재 글]

이 글의 핵심 6가지

Anthropic 공식 포지셔닝은 "Opus 4.8에 근접한 성능, 더 낮은 가격"
코딩·에이전틱 벤치마크가 Sonnet 4.6 대비 크게 올랐다 (SWE-bench Pro 58.1%→63.2%, Terminal-Bench 67.0%→80.4%)
가격은 8월 31일까지 입력 $2/출력 $10, 9월부터 $3/$15(Sonnet 4.6과 동일)
모델 ID는 claude-sonnet-5 하나뿐 — 날짜 붙은 버전은 없다
Claude Code의 sonnet·default 별칭은 계정 유형·제공자에 따라 다른 모델로 해석된다
thinking을 끄면 도구·검색 사용 성향도 낮아질 수 있어, 에이전트 작업은 effort와 max_tokens를 함께 봐야 한다
한국 전용 평가·출시일·요금 정책은 공식 확인되지 않았다 — 결제는 해외 결제 가능 카드 필요

출시 개요 — Opus 4.8에 근접한 성능, 가격은 더 낮게
코딩·에이전틱 성능, 벤치마크로 보는 변화 폭
안전성 평가 — Sonnet 4.6과 달라진 것
가격 정책 — 도입가와 표준가, 그리고 토크나이저 함정
플랜별 접근성과 추천 매트릭스
API 실사용법 — 모델 ID부터 마이그레이션까지
Claude.ai 앱·웹에서 쓰는 법
코딩 에이전트·자동화 파이프라인 적용 — Claude Code와 별칭 함정
Sonnet 4.6에서 갈아타야 할까
자주 묻는 질문과 결론

본문에서 쓰는 용어 정리

API(Application Programming Interface, 응용 프로그램 인터페이스): 프로그램끼리 데이터를 주고받는 약속된 호출 방식
SDK(Software Development Kit): API를 쉽게 호출하도록 묶어 놓은 코드 패키지
토크나이저(tokenizer): 텍스트를 모델이 처리하는 최소 단위(토큰)로 쪼개는 변환기
effort 파라미터: 모델이 답을 내기까지 얼마나 깊이 추론할지 조절하는 강도 설정값
적응형 사고(adaptive thinking): 질문 난이도에 따라 모델이 스스로 추론 깊이를 조절하는 사고 모드
ZDR(zero data retention, 데이터 무보존): 요청·응답 데이터를 서버에 전혀 남기지 않는 운영 방식
별칭(alias): claude-sonnet-5 같은 정식 모델 ID 대신 짧게 쓰는 sonnet, opus 같은 호출용 이름
캐시 히트(cache hit): 이전에 보냈던 프롬프트가 그대로 재사용되어 더 싸게 처리되는 경우
Batch API: 실시간 응답 대신 비동기로 대량 요청을 처리해 단가를 낮추는 API

1. 출시 개요 — Opus 4.8에 근접한 성능, 가격은 더 낮게

Claude Sonnet 5는 2026년 6월 30일 공개됐다. Anthropic이 발표문에서 앞세운 메시지는 단순하다. 공식 발표는 다음과 같이 설명한다.

"Sonnet 5 narrows the gap: its performance is close to that of Opus 4.8, but at lower prices."

(번역: Sonnet 5는 격차를 좁힌다 — 성능은 Opus 4.8에 근접하면서도 가격은 더 낮다.)

최상위 모델 Opus 4.8과의 성능 격차는 좁히고 가격은 낮췄다는 메시지다. 신모델을 낼 때 "더 강력해졌다"는 표현만 쓰는 경우가 많은데, 이번에는 가격까지 함께 강조한 점이 눈에 띈다. 가성비를 출시 메시지의 한 축으로 올린 셈이다. 구체적인 수치는 4장에서 따진다.

모델 ID는 claude-sonnet-5다. Sonnet 4.6의 드롭인(in-place, 호환 가능한 대체) 업그레이드로 설계됐고, 주의할 동작 변화는 세 가지다. 적응형 사고 기본 켜짐, 수동 확장 사고 제거, 기본값이 아닌 샘플링 파라미터 거부다. 세 가지 모두 6장 마이그레이션에서 코드 예제로 다룬다.

사용 범위도 넓다. Free·Pro 플랜의 기본 모델이고 Max·Team·Enterprise 사용자도 쓸 수 있다. 플랜별 차이는 5장에서 표로 정리한다.

공개 스펙을 보면 이번 출시는 새 모델 등급을 만든 사례라기보다, 기존 Sonnet 자리에 성능을 끌어올린 모델을 끼워 넣는 방식에 가깝다. 이런 드롭인 전략은 채택 장벽을 낮춘다. 대신 세 가지 동작 변화를 모르고 넘어가면 일부 코드에서 400 에러가 난다. 이 디테일은 가볍게 넘길 부분이 아니다.

2. 코딩·에이전틱 성능, 벤치마크로 보는 변화 폭

Anthropic은 Sonnet 5가 추론, 툴 사용, 코딩, 지식 작업 같은 에이전틱 성능에서 Sonnet 4.6보다 크게 개선됐다고 밝힌다. 발표 페이지 자체에는 구체 수치가 텍스트로 없다. 벤치마크 표가 이미지로만 제공된다.

수치 출처 고지: 아래 벤치마크 수치는 공식 발표 페이지 원문에 텍스트로 존재하지 않는다. 기술 매체 MarkTechPost 기사가 Anthropic의 6월 30일 공식 발표를 인용해 텍스트로 정리한 2차 출처 기준이며, 신뢰도(confidence)는 medium(중간) 등급으로 본다. 정확한 수치가 필요하면 공식 발표 페이지의 벤치마크 이미지와 직접 대조하는 편이 안전하다.

벤치마크	Sonnet 4.6	Sonnet 5	Opus 4.8
SWE-bench Pro (에이전틱 코딩)	58.1%	63.2%	69.2%
Terminal-Bench 2.1	67.0%	80.4%	미기재
OSWorld-Verified (컴퓨터 사용)	78.5%	81.2%	미기재
Humanity's Last Exam (도구 사용)	46.8%	57.4%	57.9%
GDPval-AA v2 (지식 작업, 점수)	미기재	1,618	1,615

표를 보면 Sonnet 5는 Sonnet 4.6 대비 전 항목에서 점수가 올랐다. Humanity's Last Exam과 GDPval-AA v2 두 항목에서는 Opus 4.8과 차이가 1점 안팎까지 좁혀졌다. SWE-bench Pro와 Terminal-Bench처럼 실제 작업을 끝까지 완수해야 하는 항목에서 격차가 가장 크게 벌어졌다는 점도 놓치면 안 된다. 단발성 질의응답보다 여러 턴에 걸친 작업에서 체감 차이가 클 가능성이 높다.

Sonnet 5가 Terminal-Bench 2.1에서 13.4%p, SWE-bench Pro에서 5.1%p 오른 건 단순 모델 교체 이상의 의미로 읽힌다. 두 벤치마크 모두 셸 명령 실행과 코드 수정을 거쳐 끝까지 작업을 완료해야 점수가 나오는 구조다. 그래서 이번 개선은 "더 똑똑한 답변"보다 "끝까지 해내는 능력"에 가깝다.

출시 직후 차트는 수정 이력이 있다

Anthropic은 2026년 6월 30일 발표문 하단 changelog에서 BrowseComp 비용-성능 차트를 한 차례 수정했다고 밝혔다. 초기 차트가 표준 agentic search 평가 방법론을 반영하지 않아 Sonnet 5 성능을 낮게 잡았고, 이후 10M 토큰 예산·압축·프로그래밍 방식 툴 호출을 포함한 시스템 카드 기준 방법론에 맞춰 업데이트했다는 설명이다. 따라서 출시 직후 캡처된 차트만 보고 결론을 내리기보다는 현재 공식 페이지와 시스템 카드 기준으로 다시 확인하는 편이 안전하다.

3. 안전성 평가 — Sonnet 4.6과 달라진 것

안전성 평가도 Sonnet 4.6과의 비교로 제시됐다. Anthropic은 Sonnet 5가 전반적으로 바람직하지 않은 행동(undesirable behaviors) 비율이 더 낮고, 에이전틱 맥락에서 더 안전하다고 설명한다.

평가 범위는 오용 협조, 기만 등 정렬되지 않은 행동 전반이다. 공식 발표는 악의적 요청 거부와 프롬프트 인젝션 하이재킹 저항이 개선됐다고 밝힌다. 환각(hallucination)과 아첨(sycophancy) 비율도 Sonnet 4.6보다 낮아졌다고 한다.

Sonnet 5는 실시간 사이버보안 안전장치를 갖춘 첫 Sonnet급 모델이다. 금지되거나 고위험인 사이버보안 주제 요청은 거부될 수 있다. 이때 거부는 에러가 아니라 정상 HTTP 200 응답으로 온다. stop_reason(응답 종료 사유) 필드에 refusal(거부)이 담기는 식이다.

실무 체크: 거부가 에러 코드가 아니라 정상 응답으로 온다는 점은 놓치기 쉽다. 기존에 4xx·5xx만 잡던 예외 처리 로직을 그대로 쓰면 거부 응답을 일반 성공으로 취급하게 된다. API 연동 코드에는 stop_reason 값을 분기하는 처리를 넣어 두는 게 안전하다.

4. 가격 정책 — 도입가와 표준가, 그리고 토크나이저 함정

가격은 두 단계다. 2026년 8월 31일까지는 입력 $2, 출력 $10(백만 토큰)이고 9월 1일부터는 입력 $3, 출력 $15로 오른다. 이 표준가는 Sonnet 4.6과 정확히 같다(2026-07-01 기준, 최신 가격은 공식 페이지 확인).

모델 / 기간 (MTok 기준)	기본 입력	5m 캐시 쓰기	1h 캐시 쓰기	캐시 히트	출력
Sonnet 5 (~2026-08-31)	$2	$2.50	$4	$0.20	$10
Sonnet 5 (2026-09-01~)	$3	$3.75	$6	$0.30	$15
Sonnet 4.6	$3	$3.75	$6	$0.30	$15

9월부터는 Sonnet 4.6과 토큰당 단가가 완전히 같아진다. 그런데 단가가 같다고 실제 비용까지 같다고 보면 틀린다.

가격표만 보면 놓치는 것 — 토크나이저

Sonnet 5는 새 토크나이저를 쓴다. 같은 입력 텍스트라도 Sonnet 4.6보다 약 30% 더 많은 토큰으로 쪼개진다 (출처: Sonnet 5 What's New 문서). API 요청·응답 형식 자체는 바뀌지 않아 코드 수정은 필요 없지만 토큰 카운팅과 비용 산정은 영향을 받는다. 토큰당 단가는 같아도 같은 작업에 드는 실제 비용은 Sonnet 4.6과 달라질 수 있다.

가성비를 단가표만 보고 판단하면 오판하기 쉽다. 9월 이후 기준으로 "Sonnet 4.6과 단가가 같으니 비용도 같다"고 생각하면, 토큰 소모량이 30% 늘어난 만큼 실제 청구액은 더 커질 수 있다. 마이그레이션 전에 자기 워크로드의 토큰 수를 다시 계산해 보는 게 낫다.

Batch API(비동기 대량 처리)를 쓰면 입출력 모두 50% 할인된다. Sonnet 5는 도입가 구간에서 입력 $1/출력 $5, 9월 이후에는 입력 $1.50/출력 $7.50이다.

프롬프트 캐싱은 5분 캐시 쓰기와 1시간 캐시 쓰기 단가가 따로 있다. 반복 호출이 많은 에이전트나 RAG 파이프라인에서는 "기본 입력 단가"만 볼 게 아니라 캐시 쓰기·캐시 히트 비율까지 같이 봐야 한다. 위 표에서 5분 캐시 쓰기 열을 따로 넣은 이유도 이 때문이다 (출처: 공식 가격 페이지).

컨텍스트가 길어진다고 단가가 오르는 구조도 아니다. Sonnet 5는 1M 토큰 전체 구간에서 표준 단가가 동일하게 적용된다. 900k 토큰 요청도 9k 토큰 요청과 같은 토큰당 단가로 청구된다. 이 부분은 한국 커뮤니티에 떠도는 다른 주장과 함께 11장에서 다시 짚는다.

5. 플랜별 접근성과 추천 매트릭스

Claude.ai 구독 플랜은 다섯 단계다. Free는 무료다. Pro는 연간 약정 시 월 $17(연 $200 선결제) 또는 월간 결제 시 $20, Max는 월 $100부터, Team 스탠다드 좌석은 연간 약정 월 $20(월간 $25)·프리미엄 좌석 월 $100, Enterprise는 좌석가에 API 단가 사용량을 더해 청구한다 (출처: Claude.ai 가격 페이지).

Sonnet 5는 이 중 Free와 Pro 플랜의 기본 모델이다. Max·Team·Enterprise 사용자도 쓸 수 있다.

플랜	월 가격	Sonnet 5
Free	$0	기본 모델
Pro	$17~20	기본 모델
Max	$100~	선택 가능
Team Standard	좌석당 $20~25	선택 가능
Team Premium	좌석당 $100	선택 가능
Enterprise	좌석가 + 사용량	선택 가능

Enterprise는 구조가 다르다. 좌석료는 접근권만 커버하고, 사용량은 모두 API 단가로 별도 청구된다. 플랜·좌석 단위의 사용량 한도는 없으며 관리자가 조직이나 개인 단위로 지출 한도 설정이 가능하다 (출처: Enterprise 플랜 안내).

한도가 없다고 비용까지 무제한은 아니다: Enterprise의 "플랜·좌석 단위 한도 없음"은 쓴 만큼 청구된다는 뜻이지, 비용이 안 든다는 뜻이 아니다. 관리자가 지출 한도를 미리 걸어 두지 않으면 사용량이 그대로 청구서에 반영된다.

5-1. 사용자 유형별 추천 매트릭스

사용자 유형	추천
비개발자, 가볍게 시작	Free 또는 Pro — claude.ai 채팅에서 기본으로 Sonnet 5 사용
개발자, API 직접 연동	Claude API에서 model="claude-sonnet-5" 호출
코딩 에이전트 상시 사용	Claude Code + Pro/Max — 단, default 별칭 차이는 8장 확인
팀 단위 협업	Team Standard/Premium — 좌석 단가와 워크로드 비교 후 선택
대규모 조직, 사용량 변동 큼	Enterprise — 좌석가+API 단가, 지출 한도로 통제

표만 보면 Pro가 제일 무난해 보인다. 다만 Claude Code를 상시 자동화에 쓸 계획이라면 이야기가 다르다. 계정 유형에 따라 Claude Code의 기본 모델 자체가 Sonnet 5가 아니라 Opus 4.8로 잡히는 경우가 있다. 이 함정은 8장에서 표로 짚는다.

여기서 한 번 축을 나눠서 보는 게 좋다. 5장까지는 "어떤 플랜으로 접근할 것인가"의 문제였다면, 이제부터는 "실제로 어떤 문자열과 설정으로 호출할 것인가"의 문제다. 이 둘을 섞어 생각하면 Free·Pro에서는 Sonnet 5가 기본인데 왜 Claude Code default는 다르게 보이느냐 같은 혼선이 생긴다. 다음 장부터는 구독 화면이 아니라 API 호출부 기준으로 정리한다.

6. API 실사용법 — 모델 ID부터 마이그레이션까지

먼저 바로잡을 부분이 있다. Sonnet 5의 모델 ID는 claude-sonnet-5 하나뿐이다.

모델 ID에 날짜를 붙이지 않는다

Claude 4.6 세대부터 모델 ID는 날짜가 붙은 것(예: 20250929)과 날짜가 없는 것 모두 고정 스냅샷이라는 것이 공식 규칙이다 (출처: Claude 모델 개요 문서). claude-sonnet-5-20260701처럼 날짜를 붙인 버전은 존재하지 않는다. claude-sonnet-5 자체가 이미 고정된 스냅샷이라 날짜를 따로 붙일 필요도, 이유도 없다.

6-1. 모델 ID와 컨텍스트 스펙

공식 모델 비교표 기준으로 Claude API ID는 claude-sonnet-5, AWS Bedrock ID는 anthropic.claude-sonnet-5, Google Cloud ID도 claude-sonnet-5이며, 설명은 "속도와 지능의 최적 조합"이다. AWS 쪽은 표기가 하나 더 있다. AWS 공식 블로그에서는 us.anthropic.claude-sonnet-5라는 크로스리전 추론 프로파일 ID를 쓴다 (출처: AWS 공식 블로그).

제공자	모델 ID
Claude API	claude-sonnet-5
AWS Bedrock (일반)	anthropic.claude-sonnet-5
AWS Bedrock (US 리전 추론 프로파일)	us.anthropic.claude-sonnet-5
Google Cloud (Vertex AI)	claude-sonnet-5

일반적으로는 anthropic.claude-sonnet-5를 쓰면 된다. US 리전 한정 변형이 필요할 때만 us. 접두사를 단 ID로 바꾸면 된다.

스펙은 컨텍스트 윈도우 1M 토큰, 최대 출력 128k 토큰이다. 신뢰할 수 있는 지식 기준일과 학습 데이터 기준일은 모두 2026년 1월이다. 1M 토큰은 기본값이자 최댓값이다. Sonnet 4.6에 있던 더 작은 컨텍스트 변형은 Sonnet 5에는 없다. 다만 Priority Tier(우선 처리 등급)는 Sonnet 5에서 지원되지 않는다.

6-2. 코드로 시작하기

Python SDK 설치는 한 줄이다.

pip install anthropic

이 명령은 Anthropic 공식 Python 패키지를 설치한다 (출처: Python SDK 문서). Python 3.9 이상이 필요하다.

import os
from anthropic import Anthropic

client = Anthropic(
    api_key=os.environ.get("ANTHROPIC_API_KEY"),
)

message = client.messages.create(
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "Hello, Claude",
        }
    ],
    model="claude-sonnet-5",
)
print(message.content)

공식 문서의 예제 코드는 기본값으로 model="claude-opus-4-8"을 쓴다. Sonnet 5를 호출하려면 이 부분만 claude-sonnet-5로 바꾸면 된다. 나머지 코드는 그대로 동작한다.

6-3. Sonnet 4.6에서 마이그레이션하기

가장 단순한 마이그레이션은 모델 ID 문자열만 바꾸는 방식이다.

model = "claude-sonnet-4-6"  # Before
model = "claude-sonnet-5"  # After

단, 세 가지는 그냥 넘어가면 막힌다.

첫째, 적응형 사고 기본 켜짐이다. Sonnet 4.6에서는 thinking(사고) 필드 없는 요청이 사고 없이 실행됐지만 Sonnet 5에서는 같은 요청이 적응형 사고로 실행된다. 끄고 싶다면 thinking: {type: "disabled"}를 명시해야 한다.

둘째, 수동 확장 사고 제거다. budget_tokens를 지정하던 방식은 400 에러로 돌아온다.

# Sonnet 5에서 지원되지 않음 (400 에러)
thinking = {"type": "enabled", "budget_tokens": 32000}

# 대신 이렇게
thinking = {"type": "adaptive"}

셋째, 기본값이 아닌 샘플링 파라미터 거부다. temperature, top_p, top_k를 기본값이 아닌 값으로 설정하면 400 에러가 반환된다. Sonnet급 모델에는 처음 적용되는 제약이며, Opus 4.7에서 먼저 도입된 것과 같다.

세 항목 모두 얼핏 보면 문법 차이처럼 보이지만 운영 환경에서는 성격이 다르다. 모델 ID 교체는 단순 치환에 가깝지만 thinking 방식과 샘플링 파라미터 제약은 요청 성공 여부를 바꾸는 조건이다. 특히 공용 유틸 함수나 래퍼 SDK에 temperature 같은 값을 관성적으로 넣어 둔 팀이라면, 모델만 갈아끼우고도 배포 직후 400 에러를 맞을 수 있다.

실무에서 가장 많이 걸리는 지점: 세 변화 중 두 번째가 가장 흔하다. 기존에 budget_tokens로 추론 강도를 세밀하게 맞춰 둔 파이프라인이 있다면, 마이그레이션 전에 해당 호출부를 effort 파라미터 기반으로 바꿔야 한다. 그대로 두면 요청이 전부 실패한다.

6-4. 그 외 알아둘 것

effort(추론 강도) 기본값은 API와 Claude Code 모두 high다. Opus 4.8은 claude.ai를 포함한 모든 표면에서 기본값이 high인 반면, Sonnet 5는 API와 Claude Code에서만 그렇다.

공식 prompting 문서에서 추가로 눈여겨볼 부분은 도구 사용 성향이다. Sonnet 5는 Sonnet 4.6보다 더 agentic하게 동작하지만, thinking을 disabled로 끄면 도구 호출이나 검색을 덜 시도할 수 있다. thinking을 끈 상태에서도 도구 사용을 기대한다면 시스템 프롬프트에 "필요하면 검색·도구를 사용하라"는 지시를 명시하는 편이 낫다.

반대로 high, xhigh, max effort로 오래 도는 작업에서는 max_tokens를 너무 낮게 잡으면 사고와 도구 호출이 예산을 먼저 써 버리고 최종 답변이 잘릴 수 있다. 이런 경우에는 max_tokens를 올리거나 medium effort로 낮추는 것이 공식 권장에 가깝다.

또 하나, assistant message prefilling은 Sonnet 5에서도 지원되지 않는다. 이 제약은 Sonnet 4.6에서 이어진 것이므로, JSON 형식 강제가 필요하면 prefilling 대신 structured outputs, system prompt, output_config.format 같은 대안을 써야 한다.

Message Batches API에서는 output-300k-2026-03-24 베타 헤더를 쓰면 최대 300k 출력 토큰까지 지원된다. 평소엔 잘 안 쓰는 옵션이지만 긴 생성 결과를 한 번에 받아야 하는 배치 작업이라면 챙겨둘 만하다.

출시 시점 제공 범위는 Claude API(전체 고객), AWS(Claude in Bedrock + Claude Platform on AWS, 단 레거시 Bedrock InvokeModel·Converse는 미지원), Google Cloud(Vertex AI), Microsoft Foundry(프리뷰)다. ZDR(데이터 무보존) 계약 조직도 지원된다.

7. Claude.ai 앱·웹에서 쓰는 법

코드를 안 쓰는 독자라면 claude.ai에서 바로 시작하면 된다. Free와 Pro 플랜은 가입 직후부터 Sonnet 5가 기본 모델이라 모델을 따로 고를 필요도 없다.

Projects(프로젝트) 기능을 쓰면 자체 대화 기록과 지식 베이스를 가진 독립 작업공간을 만든다.

문서·텍스트·코드 같은 파일을 업로드해 지식 베이스로 쓰고, 프로젝트 지침(project instructions)으로 응답 스타일을 커스터마이징한다. 무료 사용자는 최대 5개 프로젝트까지 만들 수 있다. 유료 플랜은 RAG(검색 증강 생성) 기술로 대용량 콘텐츠를 자동 확장 처리하며 Team·Enterprise는 조직 공유 기능이 추가된다.

Projects는 Sonnet 5 전용 신기능이 아니라 기존 claude.ai 플랫폼 기능이다.

Sonnet 5가 Projects를 "더 잘 쓴다"기보다는, 모델이 바뀌어도 그대로 쓸 수 있는 작업공간이 있다고 이해하는 편이 정확하다.

API의 1M과 채팅 앱의 대화 길이는 다른 숫자다

Claude API와 Claude Code에서 Sonnet 5는 1M 토큰 컨텍스트 윈도우로 동작한다. 반면 claude.ai 채팅 앱의 대화 길이 한도는 유료 플랜 전반 200K 토큰이고 일부 Enterprise 모델만 500K로 더 크다고 안내되어 있다. 이 문서에는 Sonnet 5에 대한 별도 언급이 없어 Sonnet 5 출시 이후 갱신됐는지는 확인되지 않는다. 채팅 앱에서 긴 대화가 막힌다면 API의 1M 토큰과는 다른 한도가 적용된다는 점을 염두에 두는 게 안전하다.

그리고 혹시나 Claude Design에서도 Sonnet5가 바로 사용 가능한지 확인 해 보았다. 당연히 클로드 디자인에서도 sonnet5가 바로 적용되어있는것을 확인 할 수 있었다.

8. 코딩 에이전트·자동화 파이프라인 적용 — Claude Code와 별칭 함정

Anthropic은 Sonnet 5를 에이전틱 코딩의 실행 계층으로 내세운다.

"Claude Sonnet 5 gives our agents a strong execution layer for multi-step software engineering work; it handles sustained coding, tool use, and debugging well across messy technical contexts. Claude Sonnet 5 sat on real pull requests, and it carried each one through to a tested, verified result on its own. It traces a failure to its actual root cause and ships a durable fix. For day-to-day automation, it's a no-brainer."

(번역: Claude Sonnet 5는 우리 에이전트에게 다단계 소프트웨어 엔지니어링 작업을 위한 강력한 실행 계층을 제공한다. 지속적인 코딩, 툴 사용, 그리고 복잡하고 지저분한 기술적 맥락에서의 디버깅을 잘 처리한다. Claude Sonnet 5는 실제 풀 리퀘스트를 맡아 각각을 테스트를 거쳐 검증된 결과까지 스스로 끝까지 처리했다. 실패의 실제 근본 원인을 추적해 오래 가는 수정을 내놓는다. 일상적인 자동화 작업에는 두말할 것 없이 좋은 선택이다.)

실제 PR을 끝까지 처리했다는 표현은 2장 벤치마크의 SWE-bench Pro 63.2%, Terminal-Bench 80.4%와 같은 맥락이다.

질의응답형 벤치마크가 아니라 "끝까지 검증된 결과까지 도달했는가"를 보는 작업에서 점수가 크게 오른 흐름과 맞물린다.

Claude Code에서 Sonnet 5를 쓰려면 v2.1.197 이상이 필요하다(Opus 4.8은 v2.1.154 이상).

Claude Code의 모델 별칭은 입력한 글자가 같아도 어떤 계정·제공자를 쓰느냐에 따라 실제로 호출되는 모델이 다르다.

sonnet 별칭이 제공자마다 다르게 해석된다: Anthropic API에서 sonnet 별칭은 Sonnet 5로 해석된다. 하지만 Claude Platform on AWS에서는 Sonnet 4.6, Bedrock·Vertex·Foundry에서는 Sonnet 4.5로 해석된다. 같은 /model sonnet 명령이라도 어느 제공자를 쓰느냐에 따라 다른 모델이 뜬다.

default(기본값) 별칭은 더 까다롭다.

Max, Team Premium, Enterprise 종량제(pay-as-you-go), Anthropic API 사용자는 Claude Code의 기본 모델이 Opus 4.8이다. Pro, Team Standard, Enterprise 구독좌석(subscription seats) 사용자만 기본 모델이 Sonnet 5다 (출처: Claude Code 모델 설정 문서).

단, 이 별칭들은 제공자별 권장 버전을 가리키며 시간이 지나면 바뀔 수 있다. 아래 표는 2026-07-01 기준 스냅샷이다.

계정/제공자	default	sonnet	opus
Max / Team Premium / Enterprise 종량제 / Anthropic API	Opus 4.8	Sonnet 5	Opus 4.8
Pro / Team Standard / Enterprise 구독좌석	Sonnet 5	Sonnet 5	Opus 4.8
Claude Platform on AWS	Opus 4.7	Sonnet 4.6	Opus 4.7
Bedrock / Vertex / Foundry	Sonnet 4.5	Sonnet 4.5	Opus 4.6

표에서 보듯 claude.ai 채팅 앱에서는 Free·Pro 모두 Sonnet 5가 기본(7장에서 다룬 사실)이지만 Claude Code의 "기본값"은 이 규칙을 따르지 않는다. claude.ai 앱 디폴트와 Claude Code 디폴트를 같은 규칙으로 생각하면 안 된다.

실무 해석 규칙을 하나만 잡으면 이렇다: Claude Code에서 default는 "내 계정에서 지금 가장 먼저 잡히는 모델"이지 "항상 Sonnet 계열"이라는 뜻이 아니다. 반대로 sonnet은 이름은 같아도 제공자에 따라 Sonnet 5가 아닐 수 있다. 비용 예측이든 재현성이든 중요하다면 별칭을 감으로 믿지 말고 /model 결과와 설정 파일을 같이 확인하는 쪽이 안전하다.

Claude Code에서 Sonnet 5는 Anthropic API 기준 언제나 1M 토큰 컨텍스트로 실행되며, 200K 변형이나 [1m] 접미사 선택, 별도 사용 크레딧이 전혀 필요 없다. 세션은 약 967K 토큰에서 자동 압축(auto-compact)된다(기본값, CLAUDE_CODE_AUTO_COMPACT_WINDOW로 조정 가능).

다만 LLM gateway를 통해 Claude Code를 라우팅하거나 CLAUDE_CODE_DISABLE_1M_CONTEXT=1로 1M 컨텍스트를 꺼 둔 환경은 예외다. 이런 배포에서는 [1m] 접미사나 별도 환경변수 핀이 의미를 가질 수 있다. 운영 자동화에서는 별칭보다 full model ID와 ANTHROPIC_DEFAULT_SONNET_MODEL 같은 env var로 고정하는 편이 재현성이 좋다.

기본 effort는 high이며, fallbackModel 설정 예시에서도 claude-sonnet-5가 1순위로 쓰인다.

"fallbackModel": ["claude-sonnet-5", "claude-haiku-4-5"]

ex) 나의 경우 max 플랜이어서 Default가 Opus 4.8, effort는 High가 default이다.

fallbackModel은 메인 모델 요청이 실패하거나 과부하일 때 자동으로 전환할 대체 모델을 지정하는 설정이다. Sonnet 5를 1순위로 두면 Opus 계열이 막혔을 때도 작업이 끊기지 않는다.

9. Sonnet 4.6에서 갈아타야 할까

갈아탈지 말지는 결국 두 가지로 갈린다. 작업의 성격과 비용이다.

항목	Sonnet 4.6	Sonnet 5	Opus 4.8
SWE-bench Pro	58.1%	63.2%	69.2%
가격(입력/출력, 9월 이후, MTok)	$3 / $15	$3 / $15	공식 가격 페이지 별도 확인
컨텍스트 윈도우	1M(작은 변형 존재)	1M(고정, 변형 없음)	1M
적응형 사고 기본값	꺼짐	켜짐	켜짐(모든 표면)
Claude Code 기본 모델	해당 없음	계정 유형별 상이(8장)	Max 등 일부 계정 기본

표로 보면 순수 성능은 Sonnet 5가 우위고 단가는 9월 이후 동일하다. 하지만 4장에서 짚었듯 토크나이저 변화로 실질 비용은 더 들 수 있다. 점수만 보고 무조건 갈아타면 비용 계산을 건너뛰는 셈이다.

여러 커뮤니티에서도(아직 출시한지 얼마 되지 않았지만) Sonnet 5를 "저렴한 Opus 대체재"로만 보면 실망하기 쉽고, "Sonnet 4.6보다 넓어진 agentic 작업 범위"로 보면 쓸 곳이 보인다. effort를 낮게 잡고 쓰는 가벼운 반복 작업이라면 Sonnet 5가 무난하고, 고난도 작업을 high·xhigh·max effort로 오래 돌리는 워크로드라면 Opus 4.8과 실측 비교를 해 보는 게 낫다.

Sonnet 4.6에서 급하게 옮길 필요가 없는 경우와 옮기는 게 분명히 이득인 경우는 갈린다.

적응형 사고 기본 켜짐이나 샘플링 파라미터 제약처럼 동작이 바뀌는 부분을 감당할 수 있고, 멀티스텝 에이전트 작업 비중이 크다면 옮기는 쪽이 유리하다. 단발성 질의응답 위주라면 체감 차이가 크지 않을 수 있다.

10. 자주 묻는 질문과 결론

Q1. Sonnet 5를 무료로 쓸 수 있나

claude.ai Free 플랜 가입만으로 Sonnet 5가 기본 모델로 제공된다. 다만 무료 플랜의 정확한 일일 사용량 한도는 공식 문서에 구체 수치로 공개되어 있지 않다. 서드파티 추정치만 떠돌 뿐이다. 정확한 한도가 필요하면 가입 후 직접 확인하는 게 정확하다.

Q2. API 비용은 어떻게 계산하나

토큰 수 × 단가로 계산하는 기본 공식은 같다. 다만 Sonnet 5는 새 토크나이저 때문에 같은 텍스트가 Sonnet 4.6보다 약 30% 더 많은 토큰으로 계산된다는 점을 넣어야 한다. 9월 이후 단가만 보고 Sonnet 4.6과 같은 비용이 나올 거라 가정하면 실제 청구액과 차이가 날 수 있다.

Q3. 기존 코드는 어떻게 옮기나

최소 변경은 모델 ID 문자열 교체뿐이다. budget_tokens로 수동 확장 사고를 쓰던 코드는 thinking: {type: "adaptive"}로 바꿔야 하고 temperature·top_p·top_k를 기본값이 아닌 값으로 설정해 뒀다면 그 설정을 제거해야 한다. 자세한 코드는 6장을 참고한다.

Q4. "200K 넘으면 추가 과금된다"는 말이 맞나

한국 커뮤니티 일부에는 "Sonnet이 200K 토큰을 넘기면 입력 $6, 출력 $22.5로 할증된다"는 주장이 돌아다닌다.

공식 가격 정책과 대조하면 사실이 아니다

Sonnet 5는 1M 토큰 전체 구간에서 표준 단가가 동일하게 적용된다. 900k 토큰 요청도 9k 토큰 요청과 같은 토큰당 단가로 청구된다 (출처: 공식 가격 페이지). 200K라는 숫자 자체가 Sonnet 5에는 적용되지 않는 기준이다.

이전 세대 모델이나 다른 서비스의 정책이 섞여 와전된 것으로 보인다. 출처가 분명하지 않은 가격 정보는 공식 가격 페이지와 대조하는 습관을 들이는 게 좋다.

결론

상황	판단
비개발자, 가볍게 시작	Free/Pro 가입만으로 충분 — 별도 설정 불필요
Sonnet 4.6 API 사용 중	모델 ID만 바꾸되 thinking·샘플링 파라미터 코드 점검
Claude Code 상시 사용	계정 유형별 default 별칭부터 확인(8장 표)
비용에 민감	9월 전 도입가 구간에 워크로드 실측, 토큰 증가분까지 계산
한국에서 결제 막힘	해외 결제 가능 카드 확인, 안 되면 비공식 대안은 참고 수준으로

오늘 바로 해볼 것 4가지

Claude API 호출부에서 model 문자열을 claude-sonnet-5로 바꿔 본다
budget_tokens를 쓰던 thinking 설정이 있다면 type: "adaptive"로 교체한다
Claude Code 버전이 v2.1.197 이상인지 확인하고 /model로 현재 기본 모델을 확인한다
자기 계정 유형이 8장 표의 어디에 해당하는지 확인하고 default 별칭을 맹신하지 않는다

출시 첫 주의 가격·접근성 정보는 빠르게 바뀔 수 있다. 이 글에서 정리한 모델 ID, 가격, 별칭 규칙은 공식 문서 기준이지만 실제 적용 전에는 Claude API 콘솔에서 model="claude-sonnet-5"로 메시지 하나를 직접 보내 응답이 정상적으로 오는지 확인하는 게 가장 빠르다.

참고 자료

작성일: 2026-07-01

분석 대상: Claude Sonnet 5 (모델 ID claude-sonnet-5, 2026-06-30 발표)

가격·플랜·한도 정보는 이후 변경될 수 있다. 최신 내용은 공식 발표 페이지에서 확인하는 게 좋다.

개발자를 위한 Codex Design : Codex Product Design 플러그인 사용방법(Codex Product Design 튜토리얼)

갓대희 — Wed, 1 Jul 2026 12:00:57 +0900

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

2026년 들어 AI 디자인 도구의 지형이 빠르게 바뀌었다. Anthropic이 Claude Design을 내놓자 디자인 협업 시장의 대표 주자인 Figma의 주가가 상당 폭 하락했고, "코드와 디자인의 경계가 무너진다"는 이야기가 본격적으로 돌기 시작했다.

그런데 Claude Design에는 한 가지 분명한 한계가 있다. 래스터 이미지(사진·일러스트레이션)를 직접 만들지 못한다. 그래서 비주얼이 필요한 자리는 placeholder, 즉 공란으로 남는다. 디자인 도구가 "그림을 못 그린다"는 건 꽤 큰 제약으로 볼 수 도 있다.

바로 이 흐름 속에서 2026년 6월, OpenAI가 Codex에 Product Design 플러그인을 공식적으로 추가했다.

이 글에서는 이 플러그인이 기획→와이어프레임→UI→코드라는 4단계를 한 대화 흐름에서 끊김 없이 처리하는 방식을 따라가 보고자 한다.

이 글에서 다루는 것

Codex Product Design 플러그인이 무엇이고, 어떻게 활성화하는가
공식 기능 구성 — 제품 방향 탐색·유저 플로우 감사·프로토타입 생성 등
Claude Design이 못 하는 이미지 생성을 Codex가 어떻게 처리하는가
기획→와이어프레임→UI→코드 4단계를 한 대화에서 잇는 실제 워크플로우
Claude Design vs Codex Design 비교와, 얼리어답터가 지금 써볼 이유
개발자 실전 예시: Codex App 프롬프트와 CLI 커맨드 (신설)

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

플러그인(Plugin): Codex를 특정 역할 전문가로 바꾸는 설치형 확장
스킬(Skill): 특정 작업을 위한 재사용 가능한 지침 묶음
와이어프레임(Wireframe): 색·이미지 없이 화면 뼈대만 잡은 설계도
래스터 이미지(Raster image): 사진처럼 픽셀로 그려진 그림
컨텍스트 연속성: 앞 단계의 정보가 뒤 단계로 끊김 없이 이어지는 것
placeholder: 나중에 채울 자리를 비워 둔 공란
AGENTS.md: Codex가 모든 UI 생성 전 자동으로 읽는 프로젝트 규칙 파일

AI 디자인 전환기와 Codex Design의 등장
Codex Product Design 플러그인 상세
실증 — 기획에서 배포까지 4단계 워크플로우
Claude Design vs Codex Design 비교
주요 한계 및 주의사항
개발자 실전 예시: Codex App vs CLI
마무리 — 지금 써볼 이유

1. AI 디자인 전환기와 Codex Design의 등장

2026년의 디자인 도구 지형 변화는 한 번에 일어난 게 아니라 여러 도구가 줄지어 등장하며 누적됐다. 시장은 "생성형 AI 도구가 디자인 협업 플랫폼과 겹치는 기능을 제공하기 시작했다"는 신호에 민감하게 반응했다. 기능 중첩이 커질수록 기존 플랫폼이 받는 압박도 커진다는 구도다.

이 압박의 한 축이 2026년 4월 17일 Anthropic Labs가 출시한 Claude Design이다. 이 도구는 코드베이스와 디자인 파일을 읽어 팀의 디자인 시스템을 구축하고, HTML 기반의 대화형 프로토타입을 만든다. 그런데 여기에 중요한 단서가 붙는다. Claude Design은 이미지 생성기가 아니다.

공식 지원 문서는 이 점을 분명히 한다. Claude는 "이미지 생성 도구처럼 사진이나 일러스트레이션을 만들지 않는다"고 밝힌다. 대신 대화 안에서 다이어그램·차트·대화형 시각자료를 직접 만든다. 즉 UI 목업을 반복해서 다듬는 데는 강하지만, 비주얼 자산이 필요한 자리는 비워 둔 채 넘어간다.

이 구조를 보면, 디자인 작업의 흐름이 "기획→와이어프레임→UI"까지는 한 도구로 가다가도, 실제 이미지가 필요해지는 순간 외부 도구로 빠져나가야 한다는 한계가 드러난다. 바로 이 빈 자리를 정조준한 것이 Codex의 Product Design 플러그인이다. OpenAI는 2026년 6월 2일, 개별 도구를 넘어 역할별 플러그인으로 Codex를 확장했고, Product Design은 그중 하나다.

Figma 주가 하락은 단일 사건의 결과가 아니라 여러 AI 디자인 도구가 동시에 시장을 압박한 누적 효과로 읽는 편이 정확하다. 이 글은 그중 가장 늦게 등장한 Codex Design에 초점을 맞춘다.

2. Codex Product Design 플러그인 상세

2-1. Product Design 플러그인이란

Codex의 플러그인은 "단 한 번의 설치로 코딩 없이 Codex를 특정 역할의 전문가로 바꾸는" 확장 단위다. Product Design 플러그인은 OpenAI가 2026년 6월 2일 공개한 6개 역할별 플러그인 중 하나로, 초기 아이디어를 팀이 검토할 수 있는 프로토타입으로 바꾸는 데 초점을 둔다.

공식 개발자 문서에 따르면, 플러그인은 세 가지 요소로 구성된다.

스킬(특정 작업을 위한 재사용 가능한 지침), 앱, 그리고 MCP 서버다.

그중 스킬은 "특정 종류의 작업을 위한 재사용 가능한 지침"으로 정의된다. 쉽게 말해, 플러그인은 여러 스킬을 한 묶음으로 패키징해 "제품 디자인"이라는 역할을 통째로 부여하는 셈이다.

활성화 절차와 관련하여선 공식 문서를 살펴보자.

앱: 사이드바 Plugins에서 plus 버튼 또는 "Add to Codex" 선택
CLI: /plugins 명령으로 마켓플레이스 열기 → Product Design 검색·설치
설치 후: 새 스레드를 시작하고 Codex에게 플러그인 사용을 요청

이 절차는 공식 문서의 "In the app, select the plus button or Add to Codex. In the CLI, select Install plugin. After installation, start a new thread and ask Codex to use the plugin." 안내를 그대로 옮긴 것이다. 핵심은 설치 후 새 스레드에서 시작하는 것이다. 의외로 여기서 막히기 쉬운데, 기존 대화에 이어 붙이면 플러그인 컨텍스트가 깔끔하게 적용되지 않을 수 있다.

ex) CLI 환경에서 활성화 하기

- CLI환경에서 활성화 하려고 하면 Product Design이 안보일 것 이다.

- Codex App에서 먼저 활성화, 설치 해보자.

ex) Codex App에서 활성화 하기

- Install plugin을 클릭 해보자.

- 설치 후 "채팅에서 아용해 보기" 클릭.

- "Product Design"에 대해 시작 방법을 알려 달라고 하는 프롬프트가 자동으로 입력 되어 있다.

- 이제 CLI에서 신규 세션을 열고 다시 사용해보자. Product Design을 사용 가능한것을 볼 수 있다.

인터페이스 측면에서 Codex는 단일 제품이 여러 표면에 걸쳐 동작한다.

CLI, IDE 확장, 클라우드, ChatGPT 앱, 모바일, Chrome 확장이 모두 같은 ChatGPT 계정·세션 기록·AGENTS.md 설정을 공유한다.

어떤걸로 시작하든 디자인 작업(Product Design) 컨텍스트를 사용할 수 있을 것 이다.

사용 가능 플랜은 다음과 같다.

항목	내용
출시일	2026년 6월 2일 (역할별 플러그인 공식 발표, 6개 동시 출시)
사용 가능 플랜	ChatGPT Free(제한적 체험), Go($8/월), Plus($20/월), Pro($100~$200/월), Business($25/사용자/월), Edu, Enterprise. Product Design 플러그인은 클라우드 기반 기능을 요구하므로 실질적으로 Go 이상 플랜이 필요하다. Free 플랜은 일부 기능 체험만 가능하며 플러그인 풀 기능은 제한된다.
설치 위치	지원 지역의 Codex 플러그인 디렉토리 (OpenAI Curated 섹션)
워크스페이스 관리	Business·Enterprise는 RBAC으로 관리

플랜 정보 중 사용량 한도 세부 사항은 공식 요금 페이지에서 최신 정보를 확인하자.

역할별 플러그인은 지원 지역에서 순차 배포 중이며 플러그인 디렉토리에서 설치할 수 있다.

2-2. 핵심 기능 구성

Product Design 플러그인의 내부 스킬 명칭은 공식 OpenAI 문서에 공개되어 있지 않다. (그리고 개인적으로는 스킬레벨까지 딥하게 이해하지 않아도 된다고생각한다.)
"Brainstorming", "Wireframe", "UI Design", "UX Audit", "Design QA"라는 명칭은 OpenAI 공식 문서에서 확인되지 않은 커뮤니티 추론이다. 이 섹션은 최대한 공식 발표 기반 기능 설명으로 작성하였다.

커뮤니티 분석에 따르면, Product Design 플러그인은 제품 디자인을 "프로그래밍 방식의 대화"로 다루며 연구 기반 디자인 프로세스를 자동화한다. OpenAI가 공식 발표에서 밝힌 기능 범위는 다음과 같다.

기능 영역	공식 발표 내용	활용 시점
제품 방향 탐색	해결할 사용자 문제·제품 표면·디자인 시스템 정렬을 먼저 묻고 복수의 방향을 제안한다	방향이 안 잡힌 초기 단계
유저 플로우 감사	기존 사용자 흐름의 접근성·UX 문제를 점검하고 개선점을 식별한다	기존 흐름 개선 시
라이브 URL 기반 프로토타입 생성	실제 제품 URL을 직접 입력해 인터랙티브 프로토타입을 생성한다	기존 제품 개선 방향 탐색
스크린샷 인터랙티브화	정적 스크린샷을 동작하는 인터랙티브 프로토타입으로 변환한다	기존 디자인 시안 검증
Figma 연동 (Design to Code)	Figma 프레임 URL을 입력받아 기존 디자인 시스템 컴포넌트를 재사용해 코드를 생성한다	Figma 디자인 구현 시

1) 제품 방향 탐색 기능의 동작

"디자인을 즉시 생성하기보다, 해결하려는 사용자 문제와 제품 표면(신규 기능인지, 리디자인인지, 감사인지), 디자인 시스템 정렬에 대한 전략적 질문을 먼저 한다"는 것이다. 디자인 도구가 곧장 화면부터 뽑지 않고 질문으로 시작한다는 점은, 결과물의 방향 정확도를 높이는 설계로 보인다.

2) 유저 플로우 감사와 Annotations 조합

"핸드오프 전에 반응형 버그를 잡는 사전 QA를 제공하고, Annotations 도구로 바꾸고 싶은 요소를 정확히 지정해 Codex로 다시 보내 빠른 수정을 받을 수 있다"고 한다.

디자인-개발 인계 과정에서 어긋나는 부분을 미리 거른다는 발상이다.

이 기능들은 Claude Design에는 없는 것들이다.

Claude Design은 단일 도구로 UI 목업 반복에 집중하며, 별도의 유저 플로우 감사 흐름이나 Annotations 핀포인트 수정을 노출하지 않는다.

2-3. 이미지 생성 기능

두 도구가 가장 선명하게 갈리는 지점이 이미지 생성이다.

앞서 봤듯 Claude는 공식적으로 래스터 이미지를 만들지 못한다. 제품 포지셔닝 자체가 그렇다.

반면 Codex는 이미지 생성을 직접 지원한다. 구체적으로는 Codex CLI v0.123.0(2026-04-23)부터 내장 이미지 생성 스킬($imagegen)이 gpt-image-2를 사용한다.

이 $imagegen 스킬은 Product Design 플러그인 전용 기능이 아니라 CLI 범용 내장 스킬이다.

플러그인 설치 여부와 무관하게 CLI에서 $imagegen 키워드로 호출할 수 있으며, 플러그인은 이 스킬을 디자인 워크플로 안에서 조율하는 역할을 한다. (참고: Codex 이미지 생성 워크플로우)

실제로 어떤 수준의 비주얼이 나오는지는, 손으로 그린 와이어프레임을 단일 프롬프트로 반응형 화면과 애니메이션이 포함된 프로토타입으로 변환하고 자동 QA까지 마치는 사례에서 가늠할 수 있다.

다만 생성 결과물의 품질에 대해서는, 소프트 그라디언트·과도한 둥근 모서리 등 "AI 티가 나는 generic한 디자인"이라는 커뮤니티 비판도 있다.

라이브 제품 URL, Figma 링크, 브랜드 가이드라인을 먼저 프롬프트에 제시할수록 이 문제는 줄어드는 것으로 보인다.

3. 예시 — MCPHub 마켓플레이스를 4단계 한 대화로 만들기

이론적인 내용 보단 실제로 한번 사용해보자.

공식 MCP Registry가 프리뷰로 열렸지만, Claude·Cursor·Windsurf 사용자가 npm install처럼 검색·설치·검증까지 끝내는 경험에는 아직 제품 기회가 남아 있다고 가정해 보자.

핵심은 4단계가 각각 따로 도는 게 아니라, 한 대화 흐름에서 컨텍스트가 끊기지 않고 이어진다는 점이다.

Step 1에서 잡은 타깃·디자인 방향은 Step 4의 배포 준비와 사전 QA까지 같은 대화 컨텍스트 안에서 이어진다.

다만 실제 Codex Sites 배포는 Sites 플러그인과 계정 권한·사용량 조건이 갖춰진 환경에서 실행되는 별도 연동 단계로 보는 편이 정확하다.

Codex의 아이디어→POC 공식 워크플로우는 "먼저 디자인하고, 코드로 일치시키고, 브라우저에서 컨셉과 결과를 비교"하는 흐름으로 설명된다.

3-1. Step 1 — 브레인스토밍 (제품 방향·컨셉)

첫 단계에서는 화면을 그리기 전에 방향을 잡는다.

플러그인이 먼저 질문을 던지므로, 사용자는 해결하려는 문제와 타깃을 또렷하게 정리하게 된다. 처음이라면 곧장 "이런 화면 만들어줘"라고 하기보다, 문제 정의부터 대화로 푸는 편이 결과가 낫다.

MCP 서버 마켓플레이스(MCPHub)를 만들고 싶다.
타깃은 Claude·Cursor·Windsurf를 쓰면서 MCP 서버를 직접 찾아 설치하는 AI 헤비유저 개발자다.
핵심 가치는 "npm install처럼 MCP 서버를 검색·설치하는 경험"이다.
현재 공식 레지스트리가 없다는 시장 공백을 감안해, 경쟁 서비스 대비 차별점과
다크 테마 기반 디자인 시스템 방향을 먼저 제안해줘.

이 프롬프트를 보내면 플러그인은 화면을 바로 뽑는 대신, 검색·카테고리 필터·설치 플로우 중 어느 화면부터 잡을지 되묻고 방향을 함께 좁힌다. 여기서 합의한 다크 테마·카드 그리드 방향과 핵심 사용자 플로우(검색 → 상세 → 설치)가 이후 모든 단계의 기준점이 된다.

ex) 상기 프롬프트로 실제 수행

Claude Code + Claude Design 분리 구조였다면, 이 방향 설정 결과를 다음 도구로 옮길 때 다시 설명해야 했다. Codex는 같은 대화라 그 단계가 사라진다.

3-2. Step 2 — 와이어프레임 생성

방향이 정해지면 화면의 뼈대를 잡는다. 색과 이미지를 빼고 구조부터 확정하는 단계다. 앞에서 합의한 핵심 사용자 흐름이 그대로 입력으로 쓰이므로, 별도 컨텍스트 재입력이 필요 없다.

방금 정한 방향으로 MCPHub 핵심 3개 화면의 와이어프레임을 만들어줘.

(1) 메인 마켓플레이스 — 검색창, 카테고리 필터 탭(tools/resources/prompts), 서버 카드 그리드
(2) 서버 상세 페이지 — 이름·설명·버전·GitHub 스타 수, 설치 커맨드 복사 버튼, 스키마 미리보기
(3) 서버 제출 폼 — URL 입력 → mcp.json 자동 파싱 → 미리보기 확인 → 제출

색이나 이미지는 빼고 정보 구조와 주요 동작 버튼 배치에만 집중해줘.

손으로 그린 와이어프레임을 입력으로 넣어 반응형 화면 프로토타입으로 변환하는 사례가 보고된다. 이 단계의 산출물은 다음 UI 단계의 출발점이 된다.

ex) 나의 경우는 최근에 작성한 LazyCodex를 여기서 사용하여 이어가보겠다.

참고 : LazyCodex 사용 방법 : LazyCodex란?

Claude Code + Claude Design 분리 구조였다면, 와이어프레임을 별도 도구에서 만든 뒤 UI 단계로 다시 가져와야 했다.

3-3. Step 3 — UI 디자인으로 발전

와이어프레임에 시각 디자인을 입힌다.

Step 1에서 합의한 GitHub 다크 팔레트·카드 그리드 방향이 여기서 실제 색·타이포·컴포넌트로 구현된다.

카테고리 아이콘 4종과 히어로 배너가 필요한데, $imagegen 스킬로 같은 대화 안에서 바로 생성해 코드에 인라인 삽입한다.

외부 이미지 도구로 빠져나갈 필요가 없다.

와이어프레임에 앞서 정한 다크 테마 디자인 시스템을 적용해 실제 UI로 발전시켜줘.

- 색상: 배경 #0d1117, 카드 #161b22, 강조 #58a6ff (GitHub 다크 팔레트)
- 서버 카드마다 카테고리 아이콘이 필요해. 각 카테고리(tools/resources/prompts/security)를
  $imagegen[minimalist flat icon, neon blue accent, dark background, 48x48, {카테고리명}]으로 생성해서 인라인 삽입해줘.
- 메인 히어로 배너도 $imagegen[futuristic API network visualization, dark purple gradient, cinematic]으로 생성해줘.
- 설치 커맨드 복사 버튼은 클릭 시 토스트 알림 포함.

플러그인은 프로토타입을 위해 React, Vue, 또는 바닐라 HTML/CSS/JS 코드를 생성한다. (참고: open-design.ai)

즉 이 단계의 UI는 정적 시안이 아니라 이미 동작하는 코드 형태로 나온다.

ex) 수행과정

변경 사항 반영 및 디자인 시스템 업데이트
기존의 정적 와이어프레임(Static Wireframe) 프리뷰를 GitHub Dark Palette 기반의 어두운 테마 UI로 진화시켰습니다.
UI 구성에 필요한 카테고리별 이미지 및 히어로 배너(Hero Banner) 생성을 완료하였으며, 복사(Copy) 기능 실행 시 토스트 알림(Toast Feedback)을 통해 사용자 경험을 개선했습니다.
디자인 변경 사항을 반영하기 위해 프로젝트 내 DESIGN.md 문서를 이미지 중심의 UI 방향성에 맞게 최신화했습니다.

프로젝트 자산(Assets) 생성 결과
Hero Banner: 메인 화면을 장식할 고품질 히어로 배너 이미지를 생성했습니다.

Category Icons (48x48): 각 카테고리의 특성을 직관적으로 시각화한 아이콘 4종을 생성하여 assets/ 폴더에 배치했습니다.

Tools (도구) 카테고리 아이콘
Resources (리소스) 카테고리 아이콘
Prompts (프롬프트) 카테고리 아이콘
Security (보안) 카테고리 아이콘

프론트엔드 코드 반영 및 로컬 서버 검증
생성된 자산 파일들을 프론트엔드 소스(index.html, styles.css, app.js)에 올바르게 참조(Reference)하도록 코드를 수정했습니다.

로컬 개발 서버가 정상적으로 작동하며, 변경된 GitHub Dark 테마와 스타일링이 화면에 올바르게 렌더링되는 것을 확인했습니다.

- imagegen 스킬을 활용하는 과정

- 결과

Claude Code + Claude Design 분리 구조였다면, 이미지가 필요한 순간 별도 이미지 생성 도구를 거쳐야 했고 placeholder로 비워 둔 자리가 그대로 남았다.

3-4. Step 4 — 개발 코드 생성 및 배포 준비

마지막으로 디자인을 동작하는 코드로 마무리하고, 배포 가능한 형태로 정리한다.

이미 UI 단계에서 코드가 생성되므로, 이 단계는 그것을 다듬고 내보내는 흐름에 가깝다.

Codex는 Annotations로 특정 요소를 지정해 수정 요청을 보낼 수 있고, 작업 결과를 Figma·Canva 같은 도구로 이어 갈 수 있다.
(Codex Sites 기능은 현재 Preview 단계이고, 공식 문서 기준으로 ChatGPT Business / Enterprise workspace에서만 사용 가능하다. 2026.06.29 기준)

MCPHub 프로토타입을 배포 가능한 형태로 정리해줘.
Codex Sites가 연결된 환경이면 배포까지 진행하고,
연결되지 않았으면 배포 후보 폴더와 검증 결과, 필요한 다음 단계를 알려줘.

배포 전 체크리스트:
- 모바일(375px)/태블릿(768px)/데스크톱(1280px) 반응형 레이아웃 확인
- 검색창 키보드 단축키(⌘K) 동작 확인
- 설치 커맨드 복사 버튼 토스트 알림 동작 확인
- 다크 모드에서 텍스트 대비율 WCAG AA 기준 이상인지 확인

문제 있으면 배포 전에 잡아줘.

배포 준비와 사전 QA까지 단일 대화 세션에서 컨텍스트를 유지하며 처리할 수 있다는 것이 이 워크플로우의 마지막 고리다. Codex Sites가 연결된 환경이라면 실제 배포 URL까지 이어지고, 연결되지 않은 환경에서는 배포 가능한 정적 산출물과 검증 결과를 넘기는 방식이 된다.

ex) 나중에 Business, Enterprise 이외의 플랜에도 Codex Sites가 출시되면 유용할 것 같다.

Claude Code + Claude Design 분리 구조였다면, 배포는 디자인 도구 밖의 별도 수동 단계였다. Codex는 Sites 연동으로 같은 흐름 안에서 처리한다.

네 단계를 관통하는 한 줄은 컨텍스트 연속성이다. 4단계 워크플로우 요약은 다음과 같다.

단계	핵심 동작	다음 단계로 넘기는 것
Step 1 방향 탐색	문제·타깃·디자인 시스템 방향 합의	브랜드 톤, 핵심 사용자 흐름
Step 2 와이어프레임	색·이미지 없이 화면 구조 확정	정보 구조, 화면 뼈대
Step 3 UI 디자인	시각 디자인 + 이미지 생성, 동작 코드 산출	실제 UI 코드, 비주얼 자산
Step 4 코드·배포 준비	정리·사전 QA·Sites 연동 시 배포	배포 후보 산출물 또는 배포 URL

앞 단계의 "다음 단계로 넘기는 것"이 자동으로 입력이 되는 구조라, 도구를 옮길 때마다 맥락을 다시 설명하던 비용이 사라진다.

4. Claude Design vs Codex Design 비교

두 도구를 같은 축에서 정리하면 차이가 더 명확해진다.

항목	Claude Design	Codex Design
이미지 생성	불가 (placeholder)	$imagegen CLI 범용 스킬 (gpt-image-2 내장)
컨텍스트 연속성	Claude Code와 도구 분리	한 대화에서 연속
기능 구성	없음 (단일 도구)	제품 방향 탐색·유저 플로우 감사·프로토타입 생성 등 (커뮤니티 보고)
개발 코드 연결	별도 도구 전환 필요	동일 대화에서 바로
배포	수동	Codex Sites 연동 가능 (Business·Enterprise 프리뷰)

표를 한 줄로 요약하면, Codex Design의 강점은 "끊김 없음"에 있다. 이미지 생성과 코드 산출, 배포 준비가 한 대화에 들어와 있어 도구 전환 비용이 낮다. 반대로 Claude Design은 코드베이스와 디자인 파일을 읽어 디자인 시스템을 구축하는 데 강점이 있어, 기존 코드 자산을 가진 팀에는 다른 결의 가치를 준다.

두 도구는 경쟁이라기보다 상황별 선택에 가깝다. 비주얼 자산을 직접 뽑으며 기획부터 배포까지 한 흐름으로 가야 하면 Codex Design이, 기존 코드베이스 위에서 디자인 시스템을 정돈하려면 Claude Design이 유리하다.

4-1. 선택 기준 정리

참고 사항일 뿐이지만 아래 기준으로 선택 기준을 나눠 보았다.

상황	더 맞는 도구
이미지·일러스트가 디자인에 필수	Codex Design
기획→배포를 한 사람이 한 흐름으로	Codex Design
기존 코드베이스 기반 디자인 시스템 정돈	Claude Design
HTML/SVG 대화형 시각자료 중심	Claude Design
ChatGPT 계정·여러 표면 연계 활용	Codex Design

한 가지 더 고려할 변수는 사용 한도다.

Codex Design은 이미지 생성 턴이 한도를 빠르게 소모하므로, 비주얼이 많은 작업에서는 비용이 변수로 작동한다.

텍스트 위주 흐름이라면 이 부담은 작다.

5. 주요 한계 및 주의사항

Codex Design은 강력한 도구지만, 알고 들어가야 할 한계가 있다.

아래는 2026년 6월 말 기준으로 커뮤니티와 공식 채널에서 확인된 주요 제약 사항이다.

한계 항목	내용
사용량 제한 (2026년 6월 기준)	ChatGPT Plus 월 10회 프로토타입, Pro 무제한. Codex Sites 배포는 Plus/Free 3회, Pro/Business 25회, Enterprise 무제한. 초과 시 Pro 업그레이드 필요.
마지막 20%는 수동	스타일링은 약 90% 완성도로 수렴하며 CSS 폴리싱, 엣지 케이스 레이아웃, 픽셀 단위 조정은 개발자가 직접 처리해야 한다.
Figma 이미지 참조 문제	Figma URL을 이미지 소스로 직접 참조하므로 배포 전 `src/img/`에 수동 다운로드·재배치가 필요하다. '브라우저에서 보인다'는 것이 '배포 가능'을 의미하지 않는다.
컴포넌트 재사용성 취약	초기 스캐폴딩에서 재사용 패턴과 명명 규칙 품질이 낮다. `'split components by responsibility into separate files'`를 명시 요청하지 않으면 모놀리식 파일 구조가 된다.
복잡한 애니메이션 미지원	Framer Motion, Lottie, 물리 기반 모션은 지원되지 않는다. 표준 전환 효과(페이지 로드 stagger, 기본 hover 트랜지션) 수준만 가능하다.
초기 버전 불안정	정식 출시 직후라 플러그인 마켓플레이스 표시가 불안정하다는 버그 보고가 있다. (참고: Codex GitHub Issue) 설치가 안 보이면 버전·지역 지원 여부를 먼저 확인한다.

6. 개발자 실전 예시: Codex App vs CLI

Product Design 플러그인은 Codex App과 Codex CLI 양쪽에서 활용할 수 있다.

아래 세 예시는 2026년 개발자 커뮤니티에서 "이 조합이라면 직접 해보고 싶다"는 반응을 가장 많이 이끌어 낸 시나리오를 추려 정리한 것이다.

각 예시가 어떤 상황에서 Codex의 차별점을 가장 잘 드러내는지를 중심으로 살펴본다.

6-1. AI 에이전트 트레이스 익스플로러 — Codex App

왜 흥미로운가 — Codex 에이전트 런이 완료되는 순간, 그 런을 설계한 Codex가 만든 대시보드 위에 자기 자신의 트레이스가 펼쳐진다. 에이전트가 에이전트를 감시하는 재귀 구조 하나가 2026년 가장 뜨거운 개발자 페인포인트(에이전트 가시성 부재)를 정조준하면서, HN 상위 카테고리인 AI 관찰 도구의 데모 스토리로도 완벽하다.

어떤 상황에서 쓰는가

LangGraph, AutoGen, Claude Computer Use 같은 멀티에이전트 파이프라인을 실무에 도입한 AI 개발자가 "에이전트가 지금 어느 단계에서 멈췄는지, 어디서 토큰을 낭비했는지" 가시성 없이 로그 파일만 뒤지고 있을 때다. 노드별 상태를 색으로 구분하고, 스텝별 토큰·소요 시간을 타임라인으로 보여주고, 실패 스텝을 드릴다운할 수 있는 관찰 대시보드가 필요한 상황에 맞는 워크플로우다.

Codex App 프롬프트

AI 멀티에이전트 파이프라인 관찰 대시보드를 만들어줘.

화면 3개:
(1) 실시간 에이전트 그래프 — 노드=에이전트 이름+현재 상태, 엣지=메시지 흐름 방향.
    상태별 노드 색상: running=파랑, done=초록, error=빨강.
    노드 클릭 시 오른쪽 사이드패널에 마지막 출력 텍스트 표시.
(2) 트레이스 타임라인 — 각 에이전트 스텝을 세로 타임라인으로 정렬.
    스텝별 입출력 토큰 수, 소요 시간(ms), 호출된 툴 목록 표시.
(3) 에러 드릴다운 패널 — 실패 스텝의 전체 컨텍스트, 스택 트레이스, 리트라이 버튼.

빈 상태(에이전트 없음) / 로딩 상태(실행 중 스피너) / 에러 상태(파이프라인 중단) 각각 별도 UI 처리.
디자인: 다크 모드, 모노스페이스 폰트, 형광 그린 액센트 컬러.
각 화면에 목 데이터 포함해서 즉시 렌더링 가능하게.

확장 방향 (Codex CLI)

대시보드 프로토타입이 App에서 완성된 후, CLI로 TypeScript React 컴포넌트와 WebSocket /ws/trace 엔드포인트 에뮬레이터를 추가 생성해 로컬 테스트 환경까지 구축할 수 있다. App 계획 → CLI 구현의 하이브리드 패턴이 이 예시에서 가장 자연스럽게 드러난다.

6-2. README.md → OSS 랜딩 페이지 원샷 생성 — Codex App

왜 흥미로운가 — $imagegen이 가장 자연스럽게 빛나는 시나리오다. README에서 추출한 기능명으로 히어로 이미지와 기능 카드 아이콘 3개를 동시에 생성해 코드에 인라인 삽입하는 흐름이 기획→이미지→코드 파이프라인을 한 번에 보여준다. "README 붙여넣기 → 랜딩 완성"이라는 원샷 스토리가 솔로 개발자 커뮤니티에서 즉각적인 '나도 해보고 싶다' 반응을 만든다.

어떤 상황에서 쓰는가

오픈소스 CLI 툴이나 라이브러리를 만들었는데 README만 있고 랜딩 페이지가 없어서 프로젝트가 묻힐 것 같을 때다. Figma 열 시간 없이 오늘 저녁 안에 배포 가능한 랜딩이 필요한 솔로 개발자에게 맞는 워크플로우다.

Codex App 프롬프트

내 CLI 툴 README.md를 기반으로 바로 배포 가능한 OSS 랜딩 페이지를 만들어줘.

[README.md 내용 여기 붙여넣기]

섹션 순서:
1. 히어로 — 툴 이름 + 한 줄 설명 + npm install 명령어 복사 버튼
2. 핵심 기능 3개 — README에서 자동 추출, 각 기능마다 아이콘 카드
3. 터미널 데모 영역 — 코드 블록 신택스 하이라이팅
4. GitHub 스타 버튼 + 기여자 아바타 행

히어로 배경은 $imagegen으로 생성:
  colorful terminal output on dark screen, hacker aesthetic,
  deep purple to black gradient, cinematic blur effect.

기능 카드 아이콘 3개는 README에서 추출한 핵심 기능명으로 각각
  $imagegen[minimalist flat icon, dark theme neon accent, 64x64, {기능명}] 생성.

결과물은 index.html 단일 파일, 외부 의존성은 CDN만.

CLI 버전으로 이어 가기

codex "README.md를 읽고 OSS 랜딩 페이지 index.html 생성. 섹션: hero(툴명+한줄설명+install 명령어 복사버튼) / features(README 핵심기능 3개 자동추출, 카드 그리드) / terminal-demo(코드블록 신택스하이라이팅) / github-star. 히어로 이미지 \$imagegen[dark terminal hacker aesthetic, neon green on deep purple background, cinematic depth of field], 기능 카드 아이콘 \$imagegen[minimalist flat icon neon accent 64x64 {기능명}] 3개 각각 생성 base64 인라인 삽입. 다크테마 CDN만, 단일 index.html 완결"

6-3. PR 오토파일럿 대시보드 — Codex CLI

왜 흥미로운가 — codex review --output json | codex 파이프 한 줄이 팀 주간 코드 품질 리포트를 즉석 생성한다. AI가 생성한 코드리뷰 출력을 AI가 설계한 UI로 보는 메타 구조에, Critical/High 우선 정렬·팀원별 반복 패턴 히트맵 같은 팀 단위 실용성이 결합된다. 스타트업 팀 리드가 슬랙에 스크린샷을 올리는 순간 "이거 어떻게 만들었어요?" 스레드가 터진다.

어떤 상황에서 쓰는가

팀 규모가 커지면서 AI 코드리뷰를 CI에 붙였지만 결과가 PR 코멘트 더미에 묻혀버리고, 심각도별 분류와 팀원별 반복 안티패턴을 한 화면에서 추적하고 싶은 스타트업 테크 리드에게 맞는 시나리오다.

Codex CLI — 파이프 한 줄로 즉석 리포트 생성

# 실제 Codex 코드리뷰 결과를 파이프로 넘겨 즉석 HTML 리포트 생성
codex review --output json | codex "위 JSON 코드리뷰 결과로 PR 팀 대시보드 HTML 리포트 생성. Critical/High 이슈 상단 우선 정렬, 파일별 이슈 트리, 심각도 컬러 배지(Critical 빨강 #EF4444 / High 주황 / Medium 노랑 / Low 회색), 수정 제안 코드 블록 포함, 반복 패턴 TOP 5 요약 섹션, Inter 폰트 CDN, 단일 HTML"

Codex App — 팀 대시보드 UI 프롬프트

AI 코드리뷰 팀 대시보드 UI를 만들어줘.

화면 4개:
(1) 팀 개요 — 이번 주 리뷰 PR 수, 평균 Codex 점수,
    Critical/High/Medium/Low 이슈 카운트 KPI 카드 4개, 일별 이슈 수 라인 차트
(2) PR 리뷰 피드 — PR별 행: 제목·작성자·심각도 배지·Codex 점수 게이지.
    클릭 시 오른쪽 드로어에 세부 코멘트 펼침
(3) 팀원 인사이트 — 멤버별 반복 이슈 유형 히트맵(행=멤버, 열=이슈 카테고리),
    주별 개선 트렌드 스파크라인
(4) 안티패턴 라이브러리 — 반복 감지 패턴 랭킹,
    클릭 시 발생 파일·라인 드릴다운

디자인: GitHub 뉴트럴 팔레트,
  Critical=#EF4444(빨강), High=주황, 품질 개선=초록, Inter 폰트.
목 데이터: PR 8개, 팀원 5명 포함해서 즉시 확인 가능하게.

6-4. 언제 App을, 언제 CLI를?

상황	권장 환경
시각적 diff 리뷰·댓글·승인	App
병렬 에이전트 × Git 워크트리 관리	App
Annotations 인브라우저 픽셀 수정	App
스테이크홀더 공유 (Codex Sites 배포)	App
멀티에이전트 트레이스 대시보드 설계	App → CLI 하이브리드
README → 랜딩 페이지 원샷 생성	App ($imagegen 연계) 또는 CLI
로컬 레포 컨텍스트 기반 구현	CLI
CI/CD 파이프라인 자동화	CLI (전용)
codex review 결과 파이프 → 즉석 리포트	CLI
이미지 배치 생성·크로마 키 처리	CLI
Figma 프레임 URL → 코드	App 또는 CLI (동일)
AGENTS.md 설정 공유	양쪽 동일 로드

2026년 권장 워크플로는 하이브리드다: App을 계획·병렬 스레드·리뷰 커맨드 센터로 사용하고, CLI를 로컬 구현·디버깅·CI 자동화에 사용한다. 위 세 가지 실전 예시가 그 패턴을 각각 다른 각도에서 보여준다.

7. 마무리 — 지금 써볼 이유

얼리어답터에게 Codex Design을 지금 권하는 이유는 분명하다. 기획·와이어프레임·UI·코드·배포를 한 대화에서 잇는 컨텍스트 연속성이다. 도구를 옮길 때마다 방향을 다시 설명하던 비용이 사라지고, 이미지가 필요한 자리도 같은 세션에서 채운다. Claude Design이 placeholder로 비워 두던 자리를 메우는 셈이다.

배경 수요도 이 방향을 뒷받침한다. Codex는 주간 사용자 5백만 명을 넘었고, 지식 노동자(비개발자) 채택이 개발자보다 빠르게 늘고 있다. 기획·디자인까지 한 도구에서 처리하려는 흐름이 커지는 셈이다.

2026년 6월 이후 주요 업데이트

정식 출시 이후에도 Codex는 빠르게 업데이트되고 있다. 2026년 6월 말 기준 주요 변화를 정리한다.

Codex Remote GA (2026-06-25): 모든 ChatGPT 플랜에서 Codex Remote가 정식 출시됐다. QR 코드 페어링으로 모바일 앱에서 Mac/Windows 호스트의 작업을 이어받거나 새로 시작할 수 있다.

DigitalOcean Droplet Workspace 플러그인 (2026-06-25): Codex가 DigitalOcean Droplet을 직접 프로비저닝하고 SSH 액세스를 설정해 원격 워크스페이스로 연결하는 플러그인이 출시됐다.

/plugins 3분류 체계 (2026-06-22): /plugins 커맨드가 OpenAI Curated, Workspace, Shared with me 세 섹션으로 개편됐다. Product Design 플러그인은 OpenAI Curated 섹션에서 찾을 수 있다.

사용량 크레딧 리딤 (2026-06-22): /usage 커맨드에서 적립된 사용량 한도 리셋 크레딧을 확인하고 사용할 수 있다.

접근 경로는 두 갈래다. 기능·사례를 모아 보려면 커뮤니티 허브 codex-design.ai를, 설치 절차와 정식 사양은 OpenAI 공식 개발자 문서를 본다. codex-design.ai는 OpenAI 공식 사이트가 아닌 커뮤니티 허브이므로, 설치·과금 같은 확정 정보는 공식 채널을 기준으로 삼는다.

오늘 바로 해볼 것

ChatGPT Go 이상 플랜이 있다면, Codex 사이드바 Plugins에서 Product Design을 설치하고 새 스레드를 연 다음, 만들고 싶은 화면의 "문제·타깃" 한 줄을 적어 보낸다.

플러그인이 화면을 바로 뽑는 대신 어떤 질문을 되묻는지 확인하는 것만으로도 이 도구의 작동 방식을 체감할 수 있다. CLI를 선호한다면 codex "$imagegen 내 첫 번째 UI 목업" 한 줄부터 시작해 보자.

궁금한 디자인 흐름이 있다면, 위 한 줄 프롬프트부터 시작해 4단계를 직접 따라가 보자. 컨텍스트가 끊기지 않는다는 말의 의미는 직접 한 번 돌려 보면 가장 빠르게 와닿는다.

참고 자료

이 글은 공식 문서, 커뮤니티 리뷰, LinkedIn·블로그 보고를 종합해 작성됐다. 서브 스킬 명칭은 공식 확인 불가로 기능 중심 서술로 교체됐다. 플랜·사용량 한도·기능은 변경될 수 있으니, 적용 전 OpenAI 공식 채널에서 최신 정보를 확인한다. (최종 업데이트: 2026-06-29)

LazyCodex 사용 방법 : LazyCodex란? ultrawork, ulw-loop, 멀티모델 라우팅, 토큰 비용까지(LazyCodex Light Edition과 OmO Ultimate의 차이)

갓대희 — Mon, 29 Jun 2026 12:00:15 +0900

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

Codex로 코딩을 시켜 본 사람은 알 것 이다. 모델을 고르고, 작업을 잘게 쪼개고, 결과가 진짜 맞는지 일일이 확인하는 그 과정이 결국 사람 몫으로 남는다. 도구는 똑똑한데, 그 똑똑함을 굴리는 잔손질이 만만치 않다.

LazyCodex는 그 잔손질을 Codex 안으로 숨긴다.

새로 나온 AI 모델이 아니라, 기존 Codex 위에 계획·실행·검증 흐름을 얹는 얇은 자동화 계층이다.

공식 소개에서도 "복잡한 코드베이스를 위한 에이전트 하네스"라고 못박고 있다.

원래 원조격의 도구인 OmO(oh-my-openagent)를 Codex에 맞게 줄여 담은 Light Edition이고, 설치는 npx 한 줄이면 끝난다.

제작자가 개인 프로젝트에 LLM 토큰값으로 2만 4천 달러를 태웠다고 공개할 만큼(OmO GitHub README), 토큰을 많이 써 본 사람이 그 비용을 의식해 만든 자동화 도구다.

그래서 이 글은 명령어 사전을 늘어놓지 않는다.

설치 → $init-deep → $ulw-plan → $start-work 순서로 직접 돌려본 흐름을 그대로 따라간다.

이 글은 2026년 6월 28일 기준으로 작성됐다. 기준 버전은 v4.13.0(2026-06-22 릴리스)이다. 공식 소스: LazyCodex 공식 문서, LazyCodex GitHub README. 버전이 빠르게 오르는 도구이므로, 적용 전 최신 공식 문서를 함께 확인하기를 권한다.

이 글에서 직접 확인하는 것

LazyCodex는 새 모델이 아니라 Codex에 얹는 Light Edition 하네스다. 설치는 npx lazycodex-ai install 한 줄
실전 흐름은 넷 — $init-deep(프로젝트 파악) → $ulw-plan(계획) → $start-work(실행) → $ulw-loop(검증 반복)
$ulw-plan은 코드를 한 줄도 안 건드리고 계획만 짠다. 카카오톡 분석기에서 계획이 점점 잘게 쪼개지는 과정을 그대로 담았다
$start-work로 넘기고 2시간 넘게 화면을 안 건드렸다. 끝에는 ORCHESTRATION COMPLETE가 떴다
검증은 5개 evidence gate와 review-work(5개 병렬 검토)로 돈다. 토큰이 많이 드는 이유가 여기에 있다
설치만으로 '욜로 모드'가 되진 않는다. --codex-autonomous를 고를 때만 무승인으로 바뀐다

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

하네스(harness): Codex를 직접 쓰는 대신, 계획·실행·검증을 위에 얹어 자동화하는 한 겹이다. 자동차에 안전벨트·계기판을 두른 골조라고 생각하면 된다.
$명령·$스킬: Codex 입력창에서 $를 붙여 부르는 내장 명령이다. 슬래시 명령과 비슷하게 생각하면 된다.
AGENTS.md: 에이전트가 코드를 고치기 전에 먼저 읽는 '프로젝트 안내문'이다. 폴더별 맥락을 적어 두는 파일이다.
evidence gate(증거 게이트): "됐다"는 말이 아니라 실제로 캡처한 결과물이 있어야 단계를 닫는 검증 관문이다.
npx: Node.js에 딸려 오는 실행기다. 설치 없이 패키지를 즉석에서 한 번 돌릴 때 쓴다.

오해 먼저 풀고 가기 — '전부 다' 들어오는 건 아니다

OmO 본판(Ultimate Edition)은 54개 이상의 lifecycle hook(생명주기 훅 — 작업 흐름의 특정 시점에 자동으로 끼어드는 처리)을 가진 큰 도구다.

Team Mode(팀 모드 — 여러 에이전트가 팀처럼 협업하는 모드)를 더하면 61개로 늘어난다).

LazyCodex는 그중 Codex 플러그인에 맞는 부분만 추린 Light Edition이다. 에이전트 오케스트레이션(여러 에이전트를 지휘하는 상위 조율 층)과 팀 도구는 빠져 있고, rules·LSP(코드 진단·정의를 돕는 도구)·ultrawork·ulw-loop·start-work continuation 같은 핵심 컴포넌트가 들어온다. "OmO 전체가 Codex에 통째로 이식됐다"고 읽으면 안 된다.

Lazy-게으른? 이라는 이름의 역설적인 면

AI한테 코딩을 제대로 시키려면 보통 공부가 필요하다.
어떤 모델을 쓸지 고르고, 도구를 붙이고, 작업 순서를 짠다. 잘 쓰는 사람일수록 이 세팅에 시간을 더 쏟는다.
LazyCodex는 그 반대로 간다고 보면 된다.

복잡한 설정을 도구 내부로 숨기고 사용자에게는 단어 하나를 남겼다.

공식 표현도 직설적이다. "그냥 프롬프트에 단어를 넣어라. 더 설정할 것은 없다(Just include the word in your prompt. Nothing else to configure)."

그래서 '게으른' 것은 도구가 아니라 사용자다.

도구 쪽은 오히려 지독하게 부지런하다. 뒤에서 보겠지만 $ulw-loop는 검증 조건을 채우려고 반복하고 ultrawork 모드에서는 그 상한이 최대 500회다.

'게으른'의 진짜 의미는 이거다. 사용자를 더 공부시키는 게 아니라, 반복 작업을 그냥 잊게 만드는 것.

복잡함을 사용자 대신 도구가 떠안는다는 것 — 그게 이름에 담긴 뜻이다.

설치 — 준비물부터 한 줄 명령까지
$init-deep — 프로젝트부터 파악시킨다
$ulw-plan — 코드는 안 건드리고 계획만
$start-work — 계획을 맡기고 2시간 자리를 비웠다
$ulw-loop와 ultrawork — 루프와 키워드
검증은 어떻게 동작하나 — 5개 게이트와 review-work
알아두면 좋은 것들 — Insane Search·욜로 오해·토큰
이런 분께 맞고, 이런 분께는 안 맞는다
자주 묻는 질문 (Q&A)
마무리 — 오늘 바로 해볼 것

1. 설치 — 준비물부터 한 줄 명령까지

LazyCodex는 Codex 안에서 도는 도구다.

그래서 Codex가 먼저 깔려 있고 로그인돼 있어야 한다. 공식 문서가 '설치 전 점검'으로 정리한 준비물은 다섯 가지다.

준비물	준비 상태
Codex	Codex 앱 또는 Codex CLI 설치 + 로그인 완료
Node.js / npm	유지보수 중인 LTS 버전. `npx`는 npm에 딸려 와 따로 안 깔아도 된다
프로젝트	Codex에서 연, 작업할 저장소
Git	변경을 추적·되돌릴 수 있는 Git 저장소
시크릿	제공자(API) 키는 셸이나 Codex 환경에 둔다 — 프로젝트 파일에 붙여넣지 않는다

LTS(Long-Term Support)는 한동안 보안 업데이트가 보장되는 '안정 버전'이라는 뜻이다. 버전부터 확인하고 싶으면 터미널에서 node -v, npm -v를 쳐 본다. 둘 다 숫자가 뜨면 준비가 된 것이다.

설치는 정말 한 줄이다.

# 설치 (대화형 TUI)
npx lazycodex-ai install

# 기본 설치 (대화형 TUI)
npx lazycodex-ai install

# TUI 없이 완전 자동 설치
npx lazycodex-ai install --no-tui --codex-autonomous

# 설치 상태 점검
npx lazycodex-ai doctor

# 제거
npx lazycodex-ai uninstall

이 명령을 실행하면 설치관리자가 Codex 플러그인 컴포넌트를 내려받아 설치한다.

TUI는 터미널 안에서 화살표·엔터로 고르는 텍스트 화면(Terminal User Interface)이라고 보면 된다. 참고로 npx lazycodex-ai install은 npx --yes --package oh-my-openagent omo install --platform=codex를 줄여 쓴 것이다.

아래는 실제 설치 화면인데, 나의 경우는 Codex App 기준으로 진행했고, Codex CLI를 써도 흐름은 거의 같다.

설치가 끝나면 이후 작업은 전부 Codex 안에서 한다.

운영체제는 가리는 편이다. 공식 문서가 정리한 권장 순서가 분명하다.

권장 실행 환경

Ubuntu: 가장 권장
macOS: 권장
Windows: 권장하지 않음. 꼭 써야 한다면 WSL2 안의 Ubuntu에서 돌린다 (공식 문서 — Recommended environment)

WSL2는 Windows 안에서 진짜 리눅스를 돌리는 공식 기능이다.

팁 — 설치를 에이전트에게 맡겨도 된다

사람이 설정 파일을 손으로 만지면 오타가 나기 쉽다. 그래서 설치 자체를 Codex에게 시켜도 된다. Codex를 열고 https://github.com/code-yeongyu/lazycodex 링크를 준 뒤 "이 저장소에서 LazyCodex를 설치해 줘"라고 하면, 구독 감지·모델 선택·인증까지 에이전트가 처리한다. 코딩 에이전트가 처음이라면 맨 Codex를 한 세션 먼저 써 본 뒤 얹는 편이 낫다. 하네스가 뒤에서 뭘 하는지 감을 잡고 쓰는 것과 아닌 것은 차이가 크다.

2. $init-deep — 프로젝트부터 파악시킨다

설치가 끝나면 명령 넷을 순서대로 쓴다.

외울 명령은 이 표가 전부다. 나머지는 흐름을 따라가며 자연스럽게 익히면 된다.

명령	이럴 때 쓴다
`$init-deep`	저장소가 크거나 오래돼 한 번에 설명하기 어려울 때. 계층형 `AGENTS.md`를 만든다. 저장소당 한 번
`$ulw-plan`	코드를 짜기 전에 결정이 필요할 때. 계획만 세워 파일로 적고 제품 코드는 건드리지 않는다
`$start-work`	계획이 있고 끝까지 실행할 때. 모든 단계가 끝나면 `ORCHESTRATION COMPLETE`를 출력한다
`$ulw-loop`	결과가 증거로 검증될 때까지 알아서 돌게 하고 싶을 때. 자기참조 루프

첫 단추는 $init-deep이다.

프로젝트 루트에서 $init-deep을 치면 코드베이스를 훑어 계층형 AGENTS.md를 만들어 준다.

복잡한 디렉터리에 점수를 매기고, 코드가 있는 자리 근처에 안내문을 적고, 나중에 들어올 에이전트가 길을 잃지 않도록 표지판을 세우는 작업이다. 저장소당 딱 한 번이면 충분하다.

카카오톡 분석기(바이브 코딩용 테스트 프로젝트)에서 $init-deep을 쳐 보니, 코드베이스를 스캔하는 단계가 순서대로 돌아갔다.

다 돌고 나면 디렉터리별 역할이 정리된 AGENTS.md가 만들어진다. 이 파일 덕분에 이후 명령들은 "이 프로젝트가 뭘 하는 곳인지"를 매번 처음부터 설명할 필요가 없어진다.

처음이라면 새 프로젝트에 LazyCodex를 붙인 직후 $init-deep부터 한 번 돌려 두는 편이 낫다. 프로젝트가 작으면 굳이 필요 없을 수도 있지만, 파일이 수백 개 넘어가는 저장소라면 이 한 번이 이후 계획·실행의 품질을 좌우한다.

언제 다시 돌리나

$init-deep은 저장소당 한 번이 기본이다. 폴더 구조가 크게 바뀌거나 새 모듈이 통째로 들어온 뒤라면 한 번 더 돌려 AGENTS.md를 갱신해 주는 정도면 충분하다. 커밋마다 돌릴 필요는 없다.

3. $ulw-plan — 코드는 안 건드리고 계획만

$init-deep으로 프로젝트 지도를 그렸으면, 다음은 계획이다. 여기서 강조할 점이 하나 있다.

$ulw-plan은 제품 코드를 한 줄도 건드리지 않는다. 전략 계획만 세워 plans/<slug>.md 파일로 적고 끝낸다.

공식 문서는 이 계획 담당을 'Prometheus(프로메테우스) 전략 플래너'라고 부른다. 불을 미리 건네주는 신화 속 이름처럼, 손대기 전에 길부터 깔아 두는 역할이다.

오늘 실습 대상은 운영 중인 카카오톡 분석기(kakaotalk.goddaehee.co.kr)다.

"현재 상태를 파악하고 개선 아이디어를 뽑아 달라"고 $ulw-plan에 던져 봤다.

프롬프트를 던지면 코드부터 짜는 게 아니라 분석부터 시작한다. 어떤 단계를 거치는지 아래 화면에서 확인한다.

1차 계획이 나왔다. 여기서 멈춰도 되는데, 상세 계획이 궁금해서 한 번 더 밀어 봤다.

밀수록 각 단계가 훨씬 촘촘하게 쪼개졌다. 두루뭉술한 "개선하자"가 아니라, 실행 가능한 작은 항목들로 갈라진다. 계획 파일을 열면 체크리스트 형태로 정리돼 있다.

이 단계의 인사이트

코드를 한 줄도 바꾸지 않은 채, 무엇을 어떤 순서로 할지 먼저 합의한다.
계획이 마음에 안 들면 코드 손실 없이 다시 던지면 된다.
처음이라면 곧장 실행으로 가지 말고, 이 계획서를 눈으로 한 번 훑어 "내가 시키려던 게 맞나"부터 확인하는 습관을 들이는 편이 낫다.

실전 팁 — 큰 작업은 세 줄로 시작한다

규모가 있는 작업이라면 파악 → 계획 → 실행을 그대로 이어 붙인다.

$init-deep
$ulw-plan "add rate limiting to the api gateway"
$start-work plans/add-rate-limiting.md

위 영어 한 줄("add rate limiting...")은 "API 게이트웨이에 요청 제한을 붙여라"라는 작업 지시다. 작고 명확한 일이라면 계획을 건너뛰고 다음 섹션의 루프로 바로 가도 된다.

4. $start-work — 계획을 맡기고 2시간 자리를 비웠다

계획이 마음에 들면 $start-work를 친다. 계획서를 읽고 바로 실행에 들어간다. 핵심은 이 명령이 모든 체크박스가 끝날 때까지 실행을 이어 간다는 점이다. 다 끝나면 ORCHESTRATION COMPLETE를 출력하고 멈춘다.

맡기기 전 한 번만 확인

실행할 계획서가 내가 의도한 그 계획이 맞는지
자율 모드를 켜 뒀다면 신뢰하는 저장소에서 돌리는 게 맞는지
Git 저장소가 깨끗한 상태인지 (언제든 되돌릴 수 있게)

카카오톡 분석기에서는 $start-work로 넘긴 뒤 2시간 넘게 화면을 건드리지 않았다. 그동안 AI가 계획서의 항목을 하나씩 처리하며 혼자 돌아갔다. 끼어들 일이 없었다.

중단돼도 이어진다 — 대신 비용은 흐른다

Light Edition에는 start-work continuation(이어가기) 컴포넌트가 들어 있어, 중간에 세션이 끊기거나 자리를 옮겨도 진행 상황을 이어 간다. 길게 도는 작업도 처음부터 다시 시킬 필요가 없다. 다만 길게 돌수록 토큰을 쓴다는 점은 기억해 둬야 한다. 자리를 비울 수 있다는 건 편하지만, 그 시간 동안 비용도 함께 흐른다.

5. $ulw-loop와 ultrawork — 루프와 키워드

네 번째 명령 $ulw-loop는 결과가 검증될 때까지 스스로 도는 자기참조 루프다. "한 번 해보고 끝"이 아니라, 통과 조건을 채울 때까지 반복한다. 무한정 도는 건 아니다. 반복 상한이 걸려 있어, ultrawork 모드는 최대 500회, 일반 모드는 100회에서 멈춘다.

여기서 한 가지 헷갈리기 쉬운 구분이 있다. ultrawork(또는 줄여서 ulw)는 명령이 아니라 프롬프트 키워드다. ultrathink처럼 프롬프트 아무 데나 이 단어를 넣으면 하네스가 증거 기반 최대 정밀도 모드로 바뀐다. 더 설정할 건 없다.

입력 예시	무슨 일이 일어나나
`ulw fix the flaky checkout test`	키워드 `ulw`가 붙어 증거 기반 모드로 실행. 작고 명확한 수정에 적합
`$ulw-plan "what to build"`	계획만 작성하고 제품 코드는 손대지 않는다
`$ulw-loop "task"`	검증을 통과할 때까지 자기참조 루프로 반복

표를 한 줄로 정리하면 이렇다. $가 붙으면 정해진 동작을 하는 명령이고, ulw는 그냥 프롬프트에 끼워 넣는 스위치다. 명령을 다 외우는 것보다 중요한 건 '계획이 필요한 일($ulw-plan)'과 '검증까지 돌릴 일($ulw-loop)'을 구분하는 감각이다. 한두 줄 수정에까지 자기참조 루프를 끌어다 쓰면 결과는 같아도 토큰만 더 든다.

가장 헷갈리는 한 가지

철자가 비슷한 $ulw-loop와 ulw는 다른 것이다. 앞은 $로 부르는 명령(검증 루프), 뒤는 프롬프트에 끼워 넣는 키워드(증거 기반 모드 스위치)다. 처음에는 이 둘을 헷갈리기 쉽다.

실전 팁 — 루프에는 '측정 가능한 완료 조건'을 줘라

루프는 완료 기준이 모호하면 헛돌거나 너무 빨리 끝난다. "앱을 개선해 줘"가 아니라 "앱이 60fps 이하로 떨어지지 않을 때까지 속도를 잡아 줘"처럼 통과 조건을 숫자로 못박는 편이 낫다. 공식 FAQ도 반복 횟수만으로는 모호한 완료 기준이 채워지지 않는다며, 무엇을 수집하고 어떤 검증을 통과해야 하는지부터 구체화하라고 권한다.

참고사항.. 이 내용은 어려우면 데충 보고 넘어가자. 몰라도 전혀 무방 하다.

ulw-loop는 목표를 잘 세운 다면 해당 완료신호. 목표를 달성할때까지 반복하는데 루프 횟수 제한이 있기때문에 무한루프에 빠지지 않도록 되어있다.

각각의 명령어에는 스킬 레이어가 있다.

대부분 작업 성격에 맞으면 자동으로 켜지므로 구지 우리가 알고 있거나, 외울 필요는 없지만 직접 부르고 싶으면 프롬프트에 $스킬명을 넣으면 된다

(예: $review-work, $git-master, $ulw-research). 주요 스킬만 추리면 이렇다.

스킬	쓰임새
review-work	구현 후 5개 레인 병렬 리뷰(목표·QA·코드·보안·맥락)
programming	TS·Rust·Python·Go 엄격 타입 + TDD 강제 (파일당 250 LOC 상한)
frontend	UI·디자인·성능(Lighthouse 100)·접근성, 실제 브라우저로 검증
debugging	코드 읽기 아닌 런타임 관측 기반 근본원인 추적
refactor / AST-grep	동작 보존 리팩터 + 구조 검색·치환(25개 언어)
git-master / LSP	원자 커밋·히스토리 조사 / 진단·정의·안전한 rename
remove-ai-slops	테스트로 동작 잠근 뒤 'AI 티 나는 코드'만 정리
ulw-research	코드베이스·웹·공식문서·OSS 병렬 스웜 최대포화 리서치(6번)

명령을 외우는 것보다 중요한 건 '계획이 필요한 일($ulw-plan)'과 '검증까지 돌릴 일($ulw-loop)'을 구분하는 감각이다.

한두 줄 수정에까지 자기참조 루프를 끌어다 쓰면 결과는 같아도 토큰만 더 든다.

6. 검증은 어떻게 동작하나 — 5개 게이트와 review-work

$start-work로 맡겨 두고 자리를 비울 수 있는 건, 도구가 스스로 결과를 검증하기 때문이다. 이 검증 구조가 LazyCodex의 핵심이자, 토큰이 많이 드는 이유이기도 하다.

먼저 에이전트가 "됐다"고 말해도 그대로 닫히지 않는다. 실행 중에는 단계 하나를 끝내기 전에 다섯 개의 evidence gate를 통과해야 한다.

5개 evidence gate

plan reread: 계획 다시 읽기
automated verification: 자동 검증(테스트·빌드 같은 기계적 확인)
manual QA: 실제로 직접 실행해 결과 확인
adversarial QA: 일부러 깨뜨려 보는 적대적 점검
cleanup: 임시로 만든 것들 정리

여기서 'gate(게이트)'는 상태값만 보고 통과시키지 않는다는 뜻이다. 실제로 캡처한 결과물, QA 통과 기록, 정리까지 있어야 단계가 닫힌다. 말로 "끝났다"가 아니라 증거로 "끝났다"를 요구하는 셈이다.

루프 전체의 마지막 판정은 Oracle(오라클)이 맡는다. $ulw-loop는 완료 신호를 받아도 거기서 멈추지 않고, Oracle이 결과를 검증한 뒤에야 끝난다. 검증을 통과하지 못하면 Oracle verification failed. Continuing ULTRAWORK loop.라는 메시지를 띄우며 루프를 계속 돈다.

코딩이 어느 정도 끝나면 review-work가 5개 서브에이전트를 병렬로 띄운다. 각자 다른 관점에서 동시에 들여다보고, 다섯 곳 모두 합격해야 리뷰가 닫힌다.

검토 레인	무엇을 보나
목표·제약 검증	요청한 걸 제대로 만들었나
직접 QA 실행	실제로 작동하나
코드 품질 평가	코드는 잘 짰나
보안 점검	안전한가
Git 히스토리·이슈 맥락	놓친 맥락은 없나

다섯 관점을 한 번에 돌리니, 단발성 실행보다 결과는 단단해지지만 그만큼 모델 호출이 늘어난다. 검증을 여러 겹으로 거치는 구조라 비용은 반복 횟수를 따라 곱해진다.

한 줄 정리

토큰이 많이 드는 건 부작용이 아니라 설계다. 5개 게이트와 review-work 5개 레인이 모두 모델 호출이기 때문이다. 이걸 이해하고 쓰는 것과 모르고 쓰는 것은 다르다.

7. 알아두면 좋은 것들 — Insane Search·욜로 오해·토큰

실전 흐름은 위에서 끝났다. 여기서는 처음 쓸 때 자주 헷갈리거나 화제가 된 세 가지를 짚는다.

Insane Search — 막힌 페이지도 뚫는 웹 리서치

gptaku님(fivetaku/insane-search)이 직접 만든 오픈소스 라이브러리에서 출발한 기능이다.

gptaku님은 스레드에서 "클코대장"으로 불리는 Claude Code 커뮤니티 리더로, 팔로워 약 3.6만 명을 보유하며 cc101 한국어 입문 가이드와 다양한 Claude Code 플러그인을 개발해왔다. insane-search의 슬로건은 "If it's public, insane-search gets in"으로, API 키 없이 Phase 0→3 단계를 자동 선택해 WAF 우회부터 실제 브라우저 자동화까지 처리한다. 이 라이브러리가 oh-my-openagent v4.13.0에 통합되면서 LazyCodex 사용자도 별도 설정 없이 사용할 수 있게 됐다.

AI 도구들로 단순 리서치를 하면 막히는, 실패하는 사이트가 많을 것 이다. 어떤 사이트는 로그인 없이는 본문이 안 뜨고, 어떤 곳은 JavaScript가 실행돼야 글이 나온다. 거기에 봇 탐지 방화벽(WAF, Web Application Firewall)까지 걸리면 일반 요청은 빈손으로 돌아온다.

Insane Search는 v4.13.0(2026-06-22)에 새로 들어온 기능이다 (릴리스 노트 — v4.13.0).

API·메타데이터 탐색을 먼저 시도하고, 막히면 아카이브·캐시 폴백, Jina(웹페이지 본문을 텍스트로 뽑아 주는 리더)·RSS(사이트 갱신을 구독하는 표준 피드) 경로, Playwright(실제 브라우저 자동화)로 단계적으로 강도를 높이는 다층 래더 구조다. 가벼운 방법부터 시작해 안 되면 무거운 방법으로 올라가므로, 불필요하게 브라우저를 띄우지 않아 토큰을 아낀다.

어디에 쓸모가 있나

최신 라이브러리 문서나 로그인이 걸린 페이지, JavaScript로 본문이 그려지는 사이트를 조사할 때 빛을 본다.

"이 기능 최신 사용법을 찾아서 적용해 줘" 같은 작업에서, 일반 요청이 빈손으로 돌아오던 페이지까지 읽어 온다.

사용 예시는 다음과 같은 예시로 사용하면 될 것 이다.

ulw-research - React 상태관리 라이브러리들 2025년 기준 심층 비교

ultraresearch GPT-5.5와 Claude Opus 4.7 코딩 벤치마크 전부 찾아줘

/ultraresearch Next.js 15의 Server Actions 성능 비교 조사해줘

이쯤 왔으면 직접 성격에 맞는 에이전트를 활성화 화는 방법, 이 에이전트들이 사용하는 스킬들이 별도로 존재하는것을 알게된 분들이 많을 것 같아서 다음과 같은 예시를 준비해봤다.

난 ulw-research의 동작 구조를 이미 살펴 보았고, 쓰레드가 막힐걸 알기 때문에 ulw-research를 사용하지 않고 해당 ulw-research에서 사용하는 스킬을 직접 지정하고, 일반적인 리서치 방법으로는 막히는 Threds에 직접 해당 스킬을 명시적으로 사용해보겠다.(스킬명 : ultimate-browsing)

ex) /ultimate-browsing "lazy codex에 대해 threds에서의 약 1~2주 반응을 종합해서 정리해줘"

- 하기 내용은 그 과정 및 결과

Insane Search 과정 및 결과

1) 수행 과정

- 영문으로 나와 한글로 정리 하자면... 429, 접근 차단 에러를 뚫기 위해 여러 방법을 시도한 결과 Reader 방식으로 성공하였다고 나온다.

- 이런 실패시의 fallback 로직을 살펴보는게 오히려 도움이 될 것 같아 공유 해보려 한다.

ex) 성공했던 방법

브라우징 전략

Threads는 JavaScript 의존도가 높고 로그인 또는 Rate Limit에 걸리기 쉬운 소셜 서비스이기 때문에 omo:ultimate-browsing을 사용했습니다.
접근 방식은 먼저 검색 인덱스와 직접 추출을 시도하고, Threads가 본문 접근을 막을 경우에만 단계적으로 더 강한 브라우징 방식으로 전환하는 흐름입니다.

Threads 접근 이슈

일반적인 Fetch 방식으로는 여러 Threads 게시물에서 429 Rate Limit 문제가 발생했습니다.
이는 Ultimate Browsing 스킬에서 말하는 Escalation Case, 즉 접근 차단 또는 제한 상황에 해당합니다.
그래서 먼저 Tier-1 extraction path와 검색 인덱스 Snippet을 활용했습니다.
이 방식은 대화형 브라우저를 바로 여는 것보다 텍스트 근거를 더 깔끔하게 확보할 수 있습니다.

직접 Threads 접근 재시도

threads.com과 threads.net의 여러 게시물 및 프로필 URL을 대상으로 접근을 시도했습니다.
일부 게시물은 여전히 직접 접근이 제한되었지만, Reader 경로를 통해 일부 공개 텍스트를 읽을 수 있었습니다.

2) 결과 정리

2026년 6월 중순부터 6월 말까지 공개로 읽힌 Threads 글을 훑어보면, 반응은 단순한 "새 도구가 나왔다"보다 "이걸 내 작업 흐름 어디에 붙일까"에 가까웠다.

특히 한국어 AI·개발자 스레드에서는 리서치, 슬라이드 제작, 게임 개발 QA처럼 반복이 많고 검증이 필요한 일에 먼저 붙여 보는 흐름이 보였다.

반응 축	Threads에서 보인 흐름	읽어야 할 포인트
리서치 자동화	가장 강한 반응은 리서치였다. X·Reddit·Hacker News 같은 여러 출처를 Codex 안에서 빠르게 모으는 사례가 공유됐고, 댓글에서도 "리서치만 놓고 보면 강하다"는 식의 반응이 붙었다.	LazyCodex 자체보다 `$ultraresearch`, insane-search, 멀티세션 수집이 한 덩어리로 받아들여지고 있다.
실무 결과물 제작	슬라이드 작업 사례에서는 insane-search로 조사하고, im-not-ai로 문장을 다듬고, DESIGN.md와 slide-grab까지 이어 붙이는 흐름이 좋은 반응을 받았다.	핵심은 "모델이 똑똑하다"가 아니라, 여러 도구를 어떤 순서로 묶느냐였다.
모바일·장시간 실행	제작자 쪽에서는 리서치 업무를 팀처럼 멀티세션으로 수행하고, 모바일에서도 쓸 수 있다는 점을 강조했다. 반대로 사용자 쪽에서는 "멈출 때까지 계속" 시키면 토큰이 빠르게 소모된다는 경험담도 나왔다.	장시간 자동 실행은 장점이면서 비용 리스크다. 완료 조건과 중단 조건을 같이 줘야 한다.
개발 현장 적용	게임 개발자는 LazyCodex와 Unity 플러그인이 데이터 버그를 잡는 데는 도움이 됐지만, 물리 상호작용·타이밍성 버그처럼 실제 플레이에서만 터지는 문제는 여전히 어렵다고 적었다.	AI 에이전트가 강한 영역과 사람 테스트가 필요한 영역을 나눠 봐야 한다.

종합하면, 최근 Threads의 분위기는 "모두가 바로 설치하는 대중 도구"라기보다 Codex를 이미 쓰는 파워 유저들이 리서치와 검증 루프에 먼저 붙여 보는 도구에 가깝다.

좋게 보는 쪽은 빠른 조사, 여러 도구 조합, 긴 루프 실행을 높게 봤다. 조심하는 쪽은 토큰 비용, 장시간 실행의 통제, 도메인 특화 버그의 한계를 짚었다. 그래서 이 글의 결론도 단순하다. LazyCodex는 "알아서 다 해주는 버튼"보다, 반복 작업을 맡기되 사람이 완료 조건을 제대로 걸어야 하는 하네스로 보는 편이 맞다.

설치하면 Codex가 '욜로 모드'로 바뀌나?

결론부터 말하면 자동으로 바뀌지 않는다.

설치관리자가 "자율 전체권한 모드로 설정할까?"를 물어보고, 자율 모드를 고르거나 --codex-autonomous 플래그를 줄 때만 ~/.codex/config.toml에 무승인 설정이 들어간다 (OmO 설치 가이드 — Autonomous Mode).

approval_policy = "never"
sandbox_mode    = "danger-full-access"
network_access  = "enabled"

이 세 줄이 들어가면 승인 프롬프트도 샌드박스도 없이 네트워크까지 열고 돈다. approval_policy = "never"는 "매번 묻지 말고 그냥 실행하라", sandbox_mode = "danger-full-access"는 "격리 없이 전체 접근을 허용하라"는 뜻이다. 반대로 마켓플레이스로 설치하면 Codex 권한 설정 자체를 건드리지 않는다. 자율 모드는 어디까지나 설치 때 사용자가 명시적으로 고르는 선택지로 남는다.

안전 주의

자율 모드는 일일이 승인하지 않아도 명령을 실행한다는 뜻이다. 편한 만큼 위험도 따라온다. 신뢰할 수 있는 저장소, 격리된 환경에서만 켜는 것이 좋다. Git 저장소를 준비물로 두는 이유도 여기에 있다 — 언제든 되돌리기 위해서다. '게으름'의 진짜 비용은 토큰만이 아니라, 승인 게이트를 꺼 둔 사실을 잊는 순간이다.

토큰 — 아껴 주는 도구가 아니다

LazyCodex는 토큰을 꽤 많이 쓴다. 공식 FAQ도 이걸 숨기지 않고 첫머리에 적는다.

LazyCodex는 토큰 절약 도구가 아니다. 계획·실행·검증에 좋은 모델과 충분한 토큰을 밀어 넣는다.

여러 겹의 검증을 거치는 구조이니 단발 실행보다 토큰이 더 나가는 건 당연하다.

앞서 본 5개 게이트와 review-work 5개 레인이 전부 모델 호출이다. 그래도 줄이는 방향은 있다.

FAQ가 말하는 "좋은 모델과 충분한 토큰"을 뒤집으면, 일의 무게에 모델과 추론 강도를 맞추라는 뜻이 된다.

토큰을 줄이는 방향

어려운 검증엔 강한 설정, 쉬운 편집엔 가벼운 설정으로 나눠 쓴다
큰 작업은 한 스레드가 무거워지기 전에 잘게 쪼갠다
작은 질문·한 줄 수정은 하네스 없이 그냥 Codex로 간다

무턱대고 전체를 약한 모델로 갈아 끼우면 검증을 통과 못 해 루프가 오히려 더 돈다.

8. 이런 분께 맞고, 이런 분께는 안 맞는다

LazyCodex는 편리함을 토큰으로 사는 도구다. 어떤 일엔 잘 맞고, 어떤 일엔 오히려 짐이 된다.

잘 맞는 경우	맞지 않는 경우
긴 작업을 걸어 두고 검증까지 반복시키고 싶을 때	토큰 예산이 빠듯할 때 (반복 루프가 비용을 곱한다)
복잡한 설정을 직접 만지지 않고 Codex 안에서 써 보고 싶을 때	한두 줄 빠른 수정만 필요할 때 (오케스트레이션이 과하다)
테스트가 통과돼야 완료로 치는 엄격한 품질이 필요할 때	진행 과정을 한 단계씩 직접 통제하고 싶을 때

한 줄 결론

긴 검증형 작업엔 강하고, 짧고 값싼 작업엔 과하다. 작은 질문이나 한 줄 수정은 하네스 없이 그냥 Codex로 가도 된다. 카카오톡 분석기처럼 "현황 분석 + 개선 실행"을 한 번에 맡기는 작업이 이 도구가 가장 빛나는 자리였다.

자주 막히는 곳 · 해법

$ 메뉴에 명령이 안 보인다: 새 Codex 세션을 열어 플러그인을 다시 로드한다. 그래도 안 보이면 설치가 정상인지 확인하고 재설치한다.
$ulw-loop가 너무 빨리 끝난다: 완료 기준이 모호해서다. 무엇을 통과해야 하는지 숫자로 못박거나 $ulw-plan으로 범위부터 잡는다.
Windows: 네이티브도 되지만 권장하지 않는다. WSL2 안의 Ubuntu에서 돌리고 프로젝트도 그 안에 두는 편이 안정적이다.

9. 자주 묻는 질문 (Q&A)

Q. LazyCodex는 새로운 AI 모델인가?

A. 아니다. Codex 위에 설치하는 OmO 기반 Light Edition 하네스다. 모델 성능이 아니라 "Codex를 어떤 워크플로로 굴리느냐"를 맡는다.

Q. 어떤 명령부터 익히면 되나?

A. 네 개만 외우면 된다. $init-deep(프로젝트 파악) → $ulw-plan(계획) → $start-work(실행) → $ulw-loop(검증될 때까지 반복). 작은 일은 프롬프트에 ulw만 붙여도 된다.

Q. 막힌 사이트도 리서치할 수 있다는 게 사실인가?

A. v4.13.0에서 들어온 Insane Search가 WAF·로그인·JS로 막힌 페이지를 단계적으로 우회해 긁는다. 가벼운 방법부터 시작해 안 될 때만 실제 브라우저를 띄운다.

Q. 설치하면 위험한 자동 실행으로 바뀌나?

A. 자동으로 바뀌지 않는다. 설치 중에 물어보고, --codex-autonomous를 고를 때만 무승인(approval_policy="never" 등)으로 설정된다. 신뢰하는 저장소·격리 환경에서만 켜는 게 안전하다.

Q. 토큰을 아껴 주나?

A. 아니다. 공식 FAQ가 "토큰 절약 도구가 아니다"라고 못박는다. 500회는 ultrawork 모드 반복 상한일 뿐, 실제 쓰는 양은 작업 크기마다 다르다. 줄이려면 작업 무게에 맞게 모델과 추론 강도를 낮춰 쓴다.

10. 마무리 — 오늘 바로 해볼 것

직접 흐름을 돌려 보니 "잘 만든 도구"가 뭔지 다시 생각하게 됐다. 기능을 다 보여 주는 게 아니라, 사용자가 챙겨야 할 것을 줄여 주는 설계다. 대신 청구서는 토큰으로 오고, 승인 게이트를 꺼 뒀다는 사실을 잊는 순간도 온다. 그래서 반복은 도구에 맡기되, 그 반복이 필요한 작업인지와 비용·권한은 직접 따져야 한다.

독자 적용 체크리스트

설치 전에 Codex 로그인 + Git 저장소 + Node LTS가 준비됐는지 확인한다.
새 프로젝트라면 $init-deep을 한 번 돌려 AGENTS.md부터 만든다.
큰 작업은 $ulw-plan으로 계획서를 먼저 받아 눈으로 확인한 뒤 $start-work로 넘긴다.
$ulw-loop에는 "60fps 될 때까지"처럼 측정 가능한 완료 조건을 준다.
자율 모드(--codex-autonomous)는 신뢰하는 저장소·격리 환경에서만 켠다.

오늘 바로 해볼 것

작업할 저장소를 Codex로 열고 npx lazycodex-ai install을 친 다음, $init-deep으로 프로젝트부터 한 번 읽혀 본다. 큰 장벽은 없다.

참고 자료

공식 문서·저장소

LazyCodex 공식 문서 — Installation, Iteration Cap, Evidence Gates, Oracle, review-work, FAQ, Recommended environment
LazyCodex GitHub README — 소개 문구·설치 명령·Commands 표
OmO (oh-my-openagent) GitHub — Light/Ultimate Edition 구분, 54+ lifecycle hooks, 토큰 비용 공개
OmO Releases — v4.13.0(2026-06-22) Insane Search 출처
OmO Installation Guide — --codex-autonomous와 권한 설정(approval_policy 등) 출처

관련 가이드 (갓대희 블로그)

Codex CLI 입문(1) : codex 설치, 인증 하기
카카오톡 분석기 — 이 글의 실습 대상 프로젝트

루프 엔지니어링 이란? — 프롬프트를 짜는 게 아니라 시스템을 짜는 시대(프롬프트 엔지니어링은 끝났다? 다음은 '루프 엔지니어링'이다)

갓대희 — Fri, 12 Jun 2026 12:00:15 +0900

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

요즘 코딩 에이전트(스스로 코드를 읽고 고치는 AI 일꾼)를 다루는 방식이 조금씩 달라지고 있다. 핵심은 한 문장으로 줄일 수 있다. "AI한테 매번 시키지 말고, AI를 시키는 시스템을 짜라." 요즘 이 흐름을 루프 엔지니어링(loop engineering) 이라 부른다.

여기서 정말 달라지는 건 내 자리다. 매 줄 직접 지시하던 '실행자'에서, 루프를 설계하고 결과를 검토하는 '감독관'으로 옮겨간다. 그래서 이건 단순히 신규 기능이나 명령어 몇 개를 외우는 차원이 아니다. 내가 무슨 일을 하는 사람인지... 관점 자체가 바뀌는 이야기다.

여기서 루프(loop) 란, 쉽게 말해 목적만 정해두면 AI가 끝날 때까지 스스로 같은 일을 반복하는 작업 묶음이다. 빨래 건조기를 떠올리면 쉽다. 우리는 매 분마다 "더 돌려, 그만 돌려"라고 말하지 않는다. "이만큼 마르면 멈춰"라는 조건만 걸어두면 알아서 돈다. 루프 엔지니어링은 바로 그 건조기를 설계하는 일이다.

이 글에서는 Addy Osmani의 글 Loop Engineering을 기준으로 정리한다. 루프를 이루는 부품이 무엇인지, Claude Code와 Codex에서는 각각 어떻게 부르는지, 그리고 마지막에 꼭 짚어야 할 냉정한 현실까지 차례로 살펴보려 한다.

이 글의 핵심 5가지

흐름이 '프롬프트 쓰기'에서 '루프 설계'로 옮겨가고 있다 — Peter Steinberger, Boris Cherny가 같은 말을 한다.
루프를 만드는 핵심 부품은 5개 + 기억장치 1개다.
1년 전엔 직접 스크립트로 짜야 했지만, 지금은 Claude Code·Codex 둘 다 기본으로 갖췄다 — 이름만 다르고 기능은 같다.
이 블로그 글 자체가 그 루프의 산출물이다 — 부품 6개 중 5개를 실제로 돌리고 있다.
하지만 루프는 사람을 일에서 빼주지 않는다. 검토하는 사람은 여전히 당신이다.

"프롬프트를 쓴다"에서 "루프를 짠다"로
루프를 이루는 다섯 부품과 기억장치 하나
실제로 돌아가는 루프 한 바퀴
Claude Code와 Codex — 같은 부품, 다른 이름
나의 하네스 살펴보기
냉정하게 — 루프는 사람을 일에서 빼주지 않는다
자주 묻는 질문

용어정리

에이전트(agent): 스스로 도구를 쓰고 판단해 일하는 AI. 단순 챗봇보다 한 단계 위, '일꾼'에 가깝다.
루프(loop): 목적만 주면 완료될 때까지 스스로 반복하는 작업 묶음.
오토메이션(automation): 정해진 시각·주기에 사람 없이 자동으로 시작되는 것.
워크트리(worktree): 한 저장소 안에서 AI마다 따로 떼어주는 독립 작업 폴더.
스킬(skill): 프로젝트 설명을 미리 적어둔 파일. AI가 작업마다 다시 읽는 '인수인계 노트'.
플러그인·커넥터(plugin·connector): AI를 외부 도구(이슈 트래커·Slack 등)에 연결하고, 그 묶음을 한 번에 설치하게 포장한 것.
서브에이전트(sub-agent): 본 작업과 별개로 띄우는 보조 AI. 보통 '검사역'으로 쓴다.

1. "프롬프트를 쓴다"에서 "루프를 짠다"로

지금까지 우리가 AI를 쓰던 방식은 대체로 프롬프트, 즉 대화형이었다. 한 줄 한 줄 시키고(프롬프트), AI가 답하고, 결과를 읽고, 다시 사람이 프롬프트를 입력하여 일을 이어 간다. 매 턴마다 사람이 직접 지시하는, 운전대를 손에서 놓지 않는 구조였다.

루프 엔지니어링은 이 운전대를 시스템에게 넘긴다. Addy Osmani의 표현을 그대로 옮기면 이렇다.

"Loop engineering is replacing yourself as the person who prompts the agent. You design the system that does it instead."

(루프 엔지니어링이란, 에이전트에게 프롬프트를 쓰는 그 사람 자리에서 당신을 빼내는 것이다. 대신 그 일을 해줄 시스템을 당신이 설계한다.) — Addy Osmani

말로만 도는 유행도 아니다. 개발자 Peter Steinberger는 이렇게 못 박았다.

"You shouldn't be prompting coding agents anymore. You should be designing loops that prompt your agents."

(이제 코딩 에이전트에 프롬프트를 쓰지 마라. 에이전트에게 프롬프트를 던지는 루프를 설계하라.) — Peter Steinberger

Anthropic에서 Claude Code를 총괄하는 Boris Cherny도 같은 결의 말을 했다.

"I don't prompt Claude anymore. I have loops running that prompt Claude and figuring out what to do. My job is to write loops."

(나는 더 이상 Claude에 프롬프트를 쓰지 않는다. Claude에게 무엇을 할지 시키는 루프를 돌리고 있고, 내 일은 그 루프를 짜는 것이다.) — Boris Cherny

원문이 인용한 두 사람의 말은 같은 방향을 가리킨다. 지렛대의 받침점이 프롬프트 한 줄에서 루프 한 벌로 옮겨갔다는 뜻이다.

2. 루프를 이루는 다섯 부품과 기억장치 하나

그럼 루프는 무엇으로 만들까.

핵심 부품은 다섯 가지, 여기에 기억장치 하나가 더 붙는다.

1년 전만 해도 이걸 별도의 MCP를 사용하거나, 직접 셸 스크립트(터미널 명령을 묶어 자동 실행하는 작은 프로그램)로 짜고 계속 관리해야 했지만, 지금은 Claude Code와 Codex 두 제품 모두에 기본으로 들어가 있다.

하나씩 자세히 살펴보자.

부품 ① 오토메이션 — 알아서 '시작' 버튼을 누른다

비유: 매일 아침 7시에 알아서 켜지는 커피머신. 버튼을 누르지 않아도 정해진 시각에 돈다.
기능: 오토메이션(automation) 은 정해진 주기에 사람 개입 없이 발견과 분류를 실행한다. 여기서 '분류'는 영어로 트리아지(triage) 라고 부른다. 응급실에서 환자의 급한 순서를 가리듯, 할 일을 추리고 우선순위를 매기는 것을 뜻한다.
두 제품에서는: Claude Code는 /loop(주기 반복), /goal(조건 만족까지), 그리고 cron(시각 예약기)·hooks(특정 사건에 자동 실행되는 갈고리)·GitHub Actions로 돈다. Codex는 'Automations' 탭에서 프로젝트·프롬프트·주기·실행 환경을 지정하고, 처리 못 한 일이 모이는 'Triage inbox'와 /goal을 제공한다.

부품 ② 워크트리 — AI마다 책상을 따로 준다

비유: 개발자 둘이 상의 없이 같은 문서를 동시에 덮어쓰면 서로의 작업이 날아간다. 그래서 각자 책상에 사본을 한 부씩 깔아준다.
기능: 워크트리(worktree) 는 같은 커밋 이력(코드 변경 기록)을 공유하는 하나의 저장소 안에서, AI마다 별도 브랜치(작업 갈래)의 독립 폴더를 내어준다. 한 AI의 수정이 다른 AI의 폴더에 닿지 않게 분리해 충돌을 막는다. 다만 충돌을 막아준다고 무한정 늘릴 수는 없다 — 결과를 검토하는 사람은 결국 당신이고, 검토 여력이 동시 실행 대수를 정한다.
이름은: Claude Code 쪽이 git worktree, --worktree 플래그(실행 옵션), 그리고 서브에이전트에 isolation: worktree를 걸어 작업 후 자동 정리되는 폴더를 준다. Codex 쪽은 스레드(작업 대화 한 줄기)마다 워크트리를 내장으로 띄운다. 실제로 Codex 앱의 깃 통합 메뉴에는 '브랜치 접두사·워크트리' 설정이 그대로 들어 있다. (참고: 갓대희 Codex Mac App 가이드 실측)

부품 ③ 스킬 — 매번 처음부터 설명하지 않게 적어둔다

비유: 새 직원이 올 때마다 회사 규칙을 입으로 다시 설명하면 지친다. 대신 인수인계 노트를 한 장 써두면 그걸 읽고 시작한다.
기능: AI는 세션(작업 한 판)이 바뀌면 맥락이 백지로 돌아간다. 그러면 비어 있는 정보를 자신 있게 추측으로 메워버리는 일이 생긴다. 스킬(skill) 은 프로젝트 지식을 SKILL.md라는 파일에 적어두고, AI가 매 작업마다 다시 읽고 시작하게 한다. 처음부터 설명하는 수고를 줄여준다.
부르는 법: Claude Code와 Codex 둘 다 SKILL.md 같은 형식을 쓴다. Codex에서는 $이름으로 부르거나 문맥에 맞으면 알아서 불러온다.

부품 ④ 플러그인·커넥터 — 손발을 달아준다

비유: 아무리 똑똑해도 손발이 없으면 보고서를 직접 제출하진 못한다. 플러그인은 그 손발이다.
기능: 커넥터(connector) 는 에이전트를 외부 도구(GitHub·이슈 트래커, 데이터베이스(DB), 각종 API, 협업 메신저 Slack 등)에 연결한다. 보통 MCP(Model Context Protocol, AI와 외부 도구를 잇는 표준 연결 규격)를 통한다. 그래서 "고치세요"라고 말만 하고 끝나지 않는다 — 직접 PR(Pull Request, 코드를 이렇게 바꾸자는 변경 제안)을 열고, 이슈 티켓을 연결하고, CI(작성한 코드를 자동으로 빌드·검사하는 단계)가 통과하면 채널에 알림까지 보낸다. 플러그인(plugin) 은 이 커넥터와 스킬을 한 묶음으로 포장한 것이다. 동료가 한 번에 같은 환경을 설치할 수 있게 해준다. 스킬이 '작성하는 형식'이라면, 플러그인은 그걸 '배포하는 방식'이다.
제품 표기: Claude Code는 MCP 서버 + 플러그인, Codex도 MCP + 플러그인으로 배포한다. 다만 Codex의 플러그인은 OpenAI가 큐레이트한 GUI 확장이고, MCP는 표준 프로토콜 서버, Skills는 재사용 지침 묶음으로 셋의 역할이 갈린다 — 자주 헷갈리는 지점이라 구분해두면 좋다. (참고: 갓대희 Codex Mac App 가이드 실측)

부품 ⑤ 서브에이전트 — '짓는 AI'와 '검사하는 AI'를 나눈다

비유: 자기가 쓴 글은 자기 눈엔 다 잘 써 보인다. 그래서 교정은 다른 사람에게 맡긴다.
기능: 코드를 짠 모델은 자기 결과를 후하게 평가하는 경향이 있다. 그래서 서브에이전트(sub-agent) — 다른 지시문, 때로는 다른 모델을 쓰는 두 번째 에이전트 — 가 첫 번째가 놓친 문제를 잡아낸다. '만드는 AI'와 '검사하는 AI'를 일부러 나누는 것이다. 역할마다 모델과 추론 강도를 달리 둘 수도 있다 — 보안 검토용은 강한 모델에 깊은 추론(high effort)으로, 빠른 탐색용은 가벼운 읽기 전용 모델로 굴리는 식이다.
설정 위치: Claude Code는 .claude/agents/에 설정 파일을 두고 에이전트 팀이나 작업용 서브에이전트를 띄운다. Codex는 .codex/agents/에 같은 방식으로 두고, 요청할 때만 서브에이전트를 띄워 동시에 돌린 뒤 결과를 하나로 합친다.

+ 기억장치: 상태 파일 — 어제 멈춘 곳에서 잇는다

비유: 게임의 '세이브 파일'. 전원을 꺼도 다시 켜면 죽은 자리부터 다시 시작한다.
기능: 부품 5개가 손발이라면, 상태 파일(state file) 은 기억이다. 대화 컨텍스트(그 세션이 기억하는 범위) 바깥에 오래 남는 마크다운 파일이나 이슈 관리 보드(예: Linear)에, 뭘 시도했고·뭐가 통과했고·뭐가 남았는지를 적어둔다. 그래서 다음 날 아침 작업이 멈춘 지점부터 이어진다. Addy Osmani의 한마디가 핵심을 찌른다 — "The agent forgets, the repo doesn't(에이전트는 잊어도, 저장소는 잊지 않는다)."
저장처: Claude Code는 마크다운(AGENTS.md·진행 파일) 또는 MCP로 연결한 Linear, Codex는 마크다운 또는 커넥터로 연결한 Linear를 쓴다.

3. 실제로 돌아가는 루프 한 바퀴

부품을 다 모으면 어떤 그림이 될까.

한 바퀴, 즉 하나의 루프는 발견 → 분류 → 수정 → 검증 네 동작으로 압축할 수 있다

(원문이 공식 4단계로 못 박은 건 아니고, 흐름을 정리한 것이다). Addy Osmani가 든 예시를 따라가 보자.

그래서 루프는 실제로 뭐에 쓰나

흐름이 추상적으로 느껴진다면, 실제 사용처를 보면 된다.

OpenAI는 사내에서 루프를 지루하지만 끝없이 반복되는 일에 돌린다 — 매일 이슈 분류, CI 실패 요약, 커밋 브리핑 작성, 지난주 누군가 심어둔 버그 사냥. 사람이 매번 시키기엔 아깝지만, 안 하면 조용히 쌓이는 일들이다.

거창한 자동화부터 떠올릴 필요가 없다 — 손이 자꾸 가는 잡일 하나가 첫 루프로 가장 좋다.

오토메이션이 매일 아침 저장소에서 한 번 돈다.
깨어난 루프가 트리아지 스킬을 불러, 어제의 CI 실패·열린 이슈·최근 커밋을 읽고 그 결과를 마크다운 파일(또는 Linear 보드)에 적는다.
처리할 만한 작업마다 격리된 워크트리를 연다. 그 안에서 한 서브에이전트가 수정안을 쓰고, 두 번째 서브에이전트가 프로젝트 스킬과 기존 테스트를 기준으로 그 수정안을 검토한다.
커넥터가 PR을 열고 티켓을 갱신한다.
무언가 발견한 실행은 사람의 수신함(triage inbox)으로 올라오고, 아무것도 못 찾은 실행은 스스로 아카이브된다 — 책상에 올라오는 건 정말 봐야 할 것만 남는다.
상태 파일이 이 전체의 중심이다 — 뭘 했고 뭐가 남았는지 기억해, 다음 날 멈춘 지점부터 잇는다.

이 모든 걸 사람은 단 한 번 설계했을 뿐, 어느 단계도 직접 프롬프트하지 않았다.

Addy Osmani의 말 그대로다 — "You designed it one time. You did not prompt any of those steps." (당신은 이걸 한 번 설계했다. 그 단계들 중 어느 것도 직접 시키지 않았다.)

4. Claude Code와 Codex — 같은 부품, 다른 이름

두 제품을 부품별로 나란히 놓으면 이렇게 정리된다.

부품	Claude Code	Codex
오토메이션	`/loop`(주기), `/goal`(조건 만족까지), cron·hooks·GitHub Actions	Automations 탭(프로젝트·프롬프트·주기·환경), Triage inbox, `/goal`
워크트리	`git worktree`, `--worktree` 플래그, 서브에이전트 `isolation: worktree`	스레드별 워크트리 내장 (깃 통합: 브랜치 접두사·워크트리)
스킬	`SKILL.md` 파일	`SKILL.md`(동일 형식), `$이름` 또는 암묵 호출
플러그인·커넥터	MCP 서버 + 플러그인	MCP + 플러그인(배포용), 플러그인=큐레이트 GUI 확장
서브에이전트	`.claude/agents/` 설정파일, 에이전트 팀, 작업 서브에이전트	`.codex/agents/` 설정파일, 요청 시 병렬 실행 후 합치기
상태·기억	마크다운(`AGENTS.md`·진행 파일) 또는 Linear(MCP)	마크다운 또는 Linear(커넥터)

한 줄로 요약하면 이렇다. 부품 6개는 두 제품에 모두 있고, 갈리는 건 기능이 아니라 부르는 이름과 설정 위치뿐이다. 어느 쪽을 쓰든 '루프를 짠다'는 사고방식은 그대로 옮겨간다.

참고로 Codex는 모바일 QR 5단계로 폰을 Mac에 연결하고, 화면이 잠겨도 백그라운드로 계속 돈다.

Codex Mac App 가이드(2) : Codex App 원격 제어 방법 : 모바일 제어 부터 다른 기기 제어, SSH 원격 연결까지

SSH로 원격 서버까지 붙일 수 있어, '어디서나 루프를 돌리는' 쪽으로도 확장 중이다.

한 가지 실용 팁도 있다. Codex의 Fast 모드는 속도가 빠른 대신 크레딧(사용 한도)을 2~2.5배 빨리 쓴다.

보통 모드는 추론 시간을 더 둬서 멀티파일 리팩터나 복잡한 에이전트 작업에 오히려 더 안정적인 경향이 있다.

루프를 돌릴 땐 속도보다 안정성이 결국 비용을 좌우한다. 그래서 보통 모드를 권한다.

5. 나의 하네스 살펴보기

Addy의 부품	내 하네스의 실제 구현
① 오토메이션	형제 파이프라인이 Codex heartbeat(주기적으로 깨우는 자동 신호) + cron 프롬프트로 토픽을 스스로 발굴하고 예약 실행한다. 'AI 트렌드 자동 토픽' 런이 쌓여 있다.
② 워크트리	거의 쓰지 않는다(정직한 약점). 블로그는 코드가 아니라 콘텐츠라, 각 런이 `runs/<run-id>/` 디렉토리로 이미 분리된다. git worktree는 과하다고 판단해 도입하지 않았다.
③ 스킬	파이프라인 지식을 여러 `SKILL.md`로 코드화했다(주간 블로그 파이프라인 등).
④ 플러그인·커넥터	Codex·이슈 트래커·NotebookLM 등을 MCP 커넥터로 붙였다.
⑤ 서브에이전트	가장 강한 부품. Planner→Researcher→Writer↔Evaluator↔Critic를 별도 서브에이전트로 분리한다. "만드는 AI와 평가하는 AI를 반드시 다른 에이전트로 분리"하는 것이 설계의 핵심이다.
⑥ 상태·기억	수정 금지 산출물 체인(`spec.json→evidence.json→draft.md→qa_report.json→final.html`). 모델은 런 사이에 잊으므로 기억을 디스크에 둔다.

⑤ 서브에이전트의 한 바퀴를 그림으로 옮기면 이렇다. 만드는 AI(Writer)와 검사하는 AI(Evaluator·Critic)가 같은 글을 두고 역할을 나눠 맡는다.

[토픽/URL]
        └─ Planner     → spec.json       (무엇을 쓸지 정한다)
        └─ Researcher  → evidence.json   (출처·인용을 모은다)
        └─ Writer      → draft.md        ← 만드는 AI
        └─ Evaluator   → qa_report.json  ← 검사하는 AI (별도 서브에이전트)
        └─ Publisher   → final.html      (발행용 HTML로 변환)
        └─ Critic      → ship 판정        ← 또 다른 검사 AI
             ↑________________________________|
              통과 못 하면 Writer로 되돌려 다시 한 바퀴

왜 만드는 AI와 검사하는 AI를 갈라놨나

같은 글을 Claude가 스스로 채점하면 9.04, Codex가 독립으로 채점하면 7.43이 나온 적이 있다 — 1.6점이 벌어졌다. 자기가 만든 글을 자기가 후하게 본다는 뜻이다. 그래서 평가자를 만드는 AI와 분리하고, 같은 계열 모델이 채점하면 'self-bias 경고' 플래그를 강제로 단다. 이 수치는 내 한 번의 하네스 런에서 관찰한 값이다 — 공개 벤치마크가 아니며, 재현을 보장하지도 않는 한 사례의 기록이다.

6. 냉정하게 — 루프는 사람을 일에서 빼주지 않는다

루프는 일의 형태를 바꿀 뿐, 사람을 일에서 빼주지 않는다.

오히려 루프가 좋아질수록 사람이 붙잡아야 할 부분이 더 선명해진다.

Addy Osmani는 세 가지를 못 박았다.

검증은 여전히 사람 몫이다. 루프는 사람이 안 볼 때 실수한다. "Your job is to ship code you confirmed works." (당신의 일은 작동을 직접 확인한 코드를 내보내는 것이다.) 검토 없이 루프에 다 맡기면 제품 품질이 무너지고 악순환에 빠진다고, 저자 본인도 인정한다.
이해도는 노력하지 않으면 떨어진다. 코드가 빨리 나올수록, 읽지 않으면 내가 어떤 코드를 들고 있는지 모르게 된다. 루프의 산출물을 읽는 일은 선택이 아니다.
가장 큰 위험은 '인지적 항복'이다. 똑같은 루프를 두 사람이 만들어도 정반대 결과가 나온다 — 한 명은 깊이 아는 일을 더 빨리 하려고 쓰고, 다른 한 명은 그 일을 이해하지 않으려고 쓴다. 여기서 '인지적 항복(cognitive surrender)'이란, 생각하기를 기계에 넘겨버리는 것을 말한다. Addy Osmani가 그 차이를 한 문장으로 못 박는다. "The loop doesn't know the difference. You do." (루프는 그 차이를 모른다. 당신은 안다.)

가장 위험한 신호 — 인지적 항복

루프가 매끄러울수록 '생각하기'를 기계에 넘기고 싶어진다. 그 순간 루프는 숙련을 빠르게 만드는 도구가 아니라 이해를 피하는 핑계가 된다. 똑같은 루프인데 결과가 갈리는 건, 도구가 아니라 쓰는 사람 때문이다.

앞 장에서 본 자기 채점과 독립 채점의 괴리가 바로 이 경고의 증거다. 검사하는 AI를 따로 두지 않았다면, 후한 자기 점수만 믿고 부족한 글을 내보냈을 것이다. 검증을 빼면 품질이 조용히 무너진다는 말은 추상이 아니라 한 번 측정된 사실이다.

그러면서 저자는 균형추를 단다. 코드를 직접 검토하지 않거나 수정을 전적으로 루프에 맡겼다면 제 제품의 품질은 나빠졌을 것이라고 솔직히 인정한다. 그리고 덧붙인다 — 루프는 짜되, 에이전트에게 직접 프롬프트를 던지는 방식도 여전히 효과적이라고. 루프냐 직접이냐의 양자택일이 아니라 "결국 올바른 균형을 찾는 일(It's all about finding the right balance)" 이라는 것이다.

"Build the loop. But build it like someone who intends to stay the engineer, not just the person who presses go."

(루프를 만들어라. 단, '시작' 버튼만 누르는 사람이 아니라 끝까지 엔지니어로 남을 작정인 사람처럼 만들어라.) — Addy Osmani

이게 루프 설계가 프롬프트 작성보다 더 어려운 이유다. 일이 쉬워진 게 아니라, 지렛대의 받침점이 옮겨갔을 뿐이다. 글 처음에 말한 '실행자에서 감독관으로'의 자리바꿈은 일을 덜어준다는 약속이 아니다. 더 무거운 자리로 옮겨 앉으라는 요구에 가깝다. 감독관은 버튼만 누르는 사람이 아니라, 무엇이 통과했고 무엇이 틀렸는지 끝까지 책임지는 사람이다.

7. 자주 묻는 질문

Q. 루프 엔지니어링은 결국 cron 자동화 아닌가?

자동화는 루프의 부품 하나(오토메이션)일 뿐이다. 루프는 발견→분류→수정→검증을 여러 부품으로 엮은 작업 묶음이고, 자동화는 그중 '시작 버튼'에 해당한다. 나머지 다섯(워크트리·스킬·커넥터·서브에이전트·상태)이 빠지면 그냥 예약 실행이지 루프가 아니다.

Q. 초보도 오늘 시작할 수 있나?

부품 전부를 한 번에 깔 필요는 없다. 스킬(SKILL.md) 한 장과 진행 파일(progress.md) 하나부터 시작한다. 이 둘만 있어도 다음 세션에서 다시 설명할 일이 줄고, 작업이 멈춘 지점부터 이어진다.

Q. Claude Code와 Codex 중 뭘 골라야 하나?

부품은 둘 다 갖췄다. 갈리는 건 이름과 설정 위치뿐이다. 이미 쓰는 환경을 그대로 쓰되, '루프를 짠다'는 사고방식만 옮기면 된다. 두 제품을 굳이 갈아탈 이유는 부품이 아니라 팀의 기존 워크플로우에서 찾는 편이 낫다.

Q. 루프를 돌리면 코드 리뷰를 안 해도 되나?

반대다. 산출물이 빨리·많이 나올수록 검토는 더 중요해진다. 앞에서 봤듯 자기 채점과 독립 채점은 크게 벌어질 수 있다. 검증을 빼면 그 괴리가 그대로 발행물에 실린다.

마무리 — 오늘 당장 할 수 있는 것

루프 엔지니어링은 거창한 인프라에서 시작하지 않는다. 부품 6개를 내 작업에 하나씩 끼워보는 일에서 시작한다. 부품 전부를 갖추지 않아도 된다 — 내 하네스도 워크트리는 안 쓰고, 무인 발행은 일부러 닫지 않았다.

단계별 도입 플레이북

오늘 — 부품 ③ 스킬부터: 자주 하는 작업 하나를 골라 SKILL.md(인수인계 노트)로 적는다. 다음 세션부터 설명이 줄어든다.
이번 주 — 부품 ⑤ 서브에이전트: 코드를 짠 AI에게 검토까지 맡기지 말고, 별도 검사 AI를 한 번 띄운다. 자기 글에 후한 편향이 바로 보인다.
꾸준히 — 기억장치 상태 파일: 진행 파일 하나(progress.md)에 '한 일/남은 일'을 적게 하면, 내일 아침 작업이 훨씬 매끄럽다.

잊지 말아야 할 한 가지 — 검토하는 사람은 여전히 당신이다. 루프는 '시작' 버튼을 대신 눌러줄 뿐, 책임까지 가져가진 않는다. 이 글을 출발점 삼아, 가장 작은 부품 하나부터 내 작업에 끼워보길 권한다.

함께 읽으면 좋은 글

하네스 엔지니어링 — 루프의 '한 층 아래'. 프롬프트→컨텍스트→하네스의 계층과 7원칙.
Ralph Loop — 한 작업을 완료까지 자기참조로 반복하는 루프 패턴.
Autoresearch 루프 — 스킬을 스스로 개선하는 자동 연구 루프.
컨텍스트 엔지니어링 시리즈 — AGENTS.md 작성법 · /init 분석 · .claude 폴더 해부.

참고 자료

출처

Loop Engineering — Addy Osmani

작성 기준: Addy Osmani — Loop Engineering (2026-06-08) | 제품 기능은 업데이트마다 달라질 수 있다.

제품별 기능명·설정 위치는 변경될 수 있으므로 적용 전 각 제품의 최신 공식 문서를 함께 확인하기를 권한다. 저자 하네스 수치(self-eval 9.04 / 독립 eval 7.43)는 개인 런 이력에서 확인한 값이며 일반화된 벤치마크가 아니다.

Claude Fable 5 출시 — Claude Fable 5 가격·무료 기간·API 이용법 (2026년 6월 22일 까지) : 미토스 5가 아닌 Fable 5

갓대희 — Wed, 10 Jun 2026 18:00:34 +0900

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

업데이트 (2026-06-16): Fable 5 · Mythos 5 전 세계 차단 중

이 글은 2026년 6월 10일, Fable 5 출시 직후 작성됐다. 그런데 발행 사흘 뒤 상황이 뒤집혔다. 2026년 6월 12일(금), 미국 상무부(장관 하워드 러트닉)가 국가안보를 근거로 수출통제 지침(export control directive)을 발동했고, Anthropic은 Fable 5와 Mythos 5 접근을 전 세계 모든 사용자 대상으로 차단했다. (출처: Anthropic 공식 성명 · CNBC)

지침의 표적 vs 실제 결과: 지침은 "미국 내외를 불문한 모든 외국 국적자(외국인 직원 포함)의 접근 차단"을 명령했다. Anthropic은 실시간으로 사용자의 국적을 가려낼 수 없어, 외국인만 거르는 대신 두 모델을 전체 차단했다.
차단 범위: Fable 5 + Mythos 5 / claude.ai · Claude API · Amazon Bedrock · Google Vertex AI · MS Foundry · GitHub Copilot · Claude Code 전 채널.
영향 없는 모델: Opus 4.8 · Sonnet · Haiku 등은 정상 ("Access to all other Anthropic models will not be affected" — Anthropic).
발단: 제3자(아마존 연구진)가 보고한 탈옥(jailbreak) 기법. "특정 코드베이스를 읽혀 소프트웨어 결함을 찾게 하는" 방식으로, Mythos급 사이버 능력을 막던 안전장치를 우회했다는 것이다. (출처: Fortune, 2026-06-14)
Anthropic 입장: "좁고 보편적이지 않은(narrow) 탈옥"이며 GPT-5.5 등 다른 모델에도 있는 수준 — 수억 명에게 배포된 상용 모델을 회수할 사유로는 과하다고 반박. "최대한 빨리 복구하겠다"고 밝힘.

현재 상태 (2026-06-16 기준): 여전히 차단 중이며, Anthropic도 미국 정부도 공식 복구 일정을 내놓지 않았다. 하필 무료 프로모션 기간(6/9~6/22)과 겹쳐, 무료로 써볼 수 있던 창구가 차단된 채 소진되고 있다. [추정] 예측시장은 6월 20일 이전 복구 가능성을 약 70~79%로 보지만, 이는 추정일 뿐 공식 약속이 아니다.

아래 본문은 6월 10일 작성 원문을 그대로 두되, 차단으로 사실과 달라진 문장에 ~~취소선~~과 [6/16 업데이트] 메모를 달았다. 「오늘 쓸 수 있다」류 서술은 현재 차단 상태를 전제로 읽어 주세요.

✅ 업데이트 (2026-07-02): 수출통제 해제 · Fable 5 프로모션 접속 재개

6/16 업데이트 이후 상황이 다시 바뀌었다. 미국 상무부가 Fable 5·Mythos 5에 대한 수출통제 지침을 해제하면서 전 세계 차단이 풀렸다. Anthropic은 보안 위험 탐지 체계 운영, 미 정부와의 프로토콜 협력, 악의적 사용 발견 시 신고 등을 조건으로 합의하며 통제에서 벗어났다고 밝혔다. (출처: Anthropic 공식 트윗 · Hacker News에서 900점대로 화제)

차단 해제와 별개로, Anthropic은 2026년 7월 1일~7일 한정으로 Fable 5 프로모션 접속을 재개했다. 이번엔 6/9~6/22 때와 조건이 다르다 — 전액 무료가 아니라 구독 플랜 주간 사용량 한도의 50%까지만 Fable 5에 쓸 수 있고, 한도를 넘기면 유료 사용량 크레딧으로 자동 전환된다. Anthropic은 "Fable 5는 Opus 4.8보다 사용량을 더 빠르게 소진한다"고 안내했다. (출처: Claude 지원센터 — Fable 5 프로모션 접속 안내 · Hacker News 80점)

현재 상태 (2026-07-02 기준): 차단은 해제됐고, claude.ai·Claude Code·API·GitHub Copilot·클라우드 3사(AWS·GCP·Azure) 경로가 모두 다시 정상 작동한다. 다만 이번 프로모션은 7월 7일까지이고 조건도 6월 프로모션(전액 무료)보다 제한적(주간 한도 50%)이니, 아래 본문의 "무료 기간(~6/22)" 관련 서술은 이번 재개 조건과는 다르다는 점을 감안해서 읽어 주세요.

2026년 6월 9일, Anthropic이 새 모델을 발표했다. 그런데 커뮤니티 반응을 보면 이름부터 엇갈린다. "미토스 5가 나왔다"는 사람도 있고 "페이블 5"라는 사람도 있다. 둘 다 맞고, 둘 다 절반만 맞다.

정리하면 이렇다. 일반 공개(GA)된 모델은 Claude Fable 5다. Mythos 5는 같은 기반 모델에서 일부 안전장치를 해제한 버전으로, 사이버 방어 조직에만 제한 배포된다. 이 구분이 이번 발표를 읽는 첫 단추이고, 벤치마크 표의 별표(*) 하나까지 이 구조와 연결된다.

이 글은 모델 이름 구분, 성능 수치, 가격과 무료 프로모션, 안전장치 3가지, 고객 사례를 공식 발표·문서 기준으로 다룬다. 그리고 한 가지를 더 얹었다. 이 글 자체를 Fable 5가 썼다. Claude Code에서 모델을 claude-fable-5로 전환하고, 6단계 AI 작업 흐름 전체를 Fable 5로 돌린 발표 직후 실측 기록이 8장에 있다.

이 글은 2026년 6월 10일 기준으로 작성됐다. 공식 소스: Anthropic 공식 발표 · Claude 공식 모델 문서

[6/16 업데이트] 발행 후 2026-06-12 미국 수출통제 지침으로 Fable 5·Mythos 5가 차단됐다(상단 박스 참조). 차단 관련 서술은 Anthropic 차단 성명 기준.

[7/2 업데이트] 2026-07-02 기준 수출통제가 해제되어 차단이 풀렸고, Anthropic이 7월 1일~7일 한정으로 Fable 5 프로모션 접속을 재개했다(상단 녹색 박스 참조). 관련 서술은 Claude 지원센터 안내 기준.

이 글의 핵심 6가지

Fable 5 = 일반 공개 | Mythos 5 = 사이버 방어자 한정 배포
SWE-Bench Pro 80.3%, FrontierCode 29.3%
가격: 입력 $10 / 출력 $50 (백만 토큰) — Opus 4.8의 2배
6월 22일까지 Pro·Max·Team·Enterprise 무료, 이후 크레딧 필요 — [6/16] 무료 기간이지만 6/12부터 차단되어 현재 사용 불가 — [7/2] 차단 해제, 7/1~7/7 한정 프로모션 재개(주간 한도 50%, 초과 시 유료 크레딧)
위험 요청 → Opus 4.8 전환, 전체 대화 95% 이상은 전환 없음
이 글을 Fable 5가 직접 자동 작성 — 과정은 8장

출시 개요
모델 이름 정리
벤치마크
가격 · 무료 기간 · 이용 방법
안전장치 3가지
고객 사례 · 게임 생성 데모
한계와 주의점
Q&A & 결론

본문에서 쓰는 용어 정리

Mythos-class(미토스 클래스): Anthropic이 최상위 능력 등급에 붙인 모델군 명칭
GA(General Availability, 일반 공개): 누구나 쓸 수 있는 정식 출시 상태
fallback(폴백): 위험 판정된 요청을 다른 모델(Opus 4.8)이 대신 처리하는 동작
classifier(분류기): 요청의 위험 여부를 판별해 fallback을 결정하는 안전 장치
distillation(증류): 모델의 출력을 학습 데이터 삼아 모방 모델을 만드는 기법
universal jailbreak(범용 탈옥): 주제를 가리지 않고 안전장치를 무력화하는 단일 공격 기법
MTok: 백만(million) 토큰 — API 과금 단위
ZDR(zero data retention): 사용자 데이터를 전혀 보존하지 않는 운영 방식

1. 출시 개요 — 일반 공개로 내려온 Mythos-class

Claude Fable 5는 2026년 6월 9일 공식 발표됐다. Anthropic이 발표문 첫머리에 박아 둔 정의는 한 문장이다.

"a Mythos-class model that we've made safe for general use."
(일반 목적(General use)으로 안전하게 사용할 수 있도록 최적화한 Mythos class 모델입니다.)

일반 사용을 위해 안전화한 Mythos-class 모델 — 새 모델 라인을 만든 게 아니라, 이미 존재하던 최상위 등급 모델을 일반인도 쓸 수 있게 다듬었다는 발표다. '능력은 그대로, 안전장치를 입혔다'가 이번 출시의 한 줄 설계 철학이고, 5장에서 그 구조를 설명한다.

API 모델 ID는 claude-fable-5다.

AI가 한 번에 기억하고 처리할 수 있는 분량(컨텍스트 윈도우)은 기본 100만 토큰이고, 한 번에 낼 수 있는 최대 답변은 12만 8천 토큰이다.

토큰은 AI가 텍스트를 처리하는 기본 단위로, 대략 한글 1~2자 수준이다. 발표문 자체에는 "수백만 토큰"이라고만 나와 있고 구체 수치는 공식 문서에서 확인된다.

출시 당일부터 Claude API, AWS(Amazon Bedrock), Google Cloud(Vertex AI), Microsoft(Foundry) 등에서 바로 쓸 수 있다. GitHub의 AI 코딩 도구 Copilot도 같은 날 지원을 발표했고, 유료 구독자부터 단계적으로 제공된다.

[6/16 업데이트] 위 채널은 출시일(6/9)엔 모두 정상이었으나, 2026-06-12 수출통제 지침 이후 전부 차단됐다. GitHub은 "2026년 6월 12일부로 모든 GitHub Copilot 환경에서 Claude Fable 5 접근이 중단됐다(suspended)"고 공지했다. (출처: GitHub Changelog)

[7/2 업데이트] 수출통제 해제로 위 5개 채널이 모두 다시 정상 작동한다. 여기에 더해 2026년 7월 1일~7일 한정으로 구독 플랜(Pro·Max·Team·Enterprise) 주간 사용량 한도의 50%까지 Fable 5를 다시 무료로 쓸 수 있는 프로모션이 재개됐다(4장에서 자세히 다룸).

항목	내용
발표일	2026-06-09
성격	최상위 Mythos 모델을 일반인용으로 안전하게 다듬은 버전
API 모델 ID	claude-fable-5
가격	입력 $10 / 출력 $50 (백만 토큰)
한 번에 처리 가능 / 최대 답변 분량	100만 토큰 / 12.8만 토큰 (토큰 ≈ 한글 1~2자)
무료 프로모션	6/9~6/22 Pro·Max·Team·좌석형 Enterprise 플랜 포함
Mythos 5	일반 공개 아님 — Project Glasswing 한정

Anthropic은 Fable 5에 대해 "지금까지 일반 공개한 어떤 모델보다 능력이 앞서며, 테스트한 거의 모든 성능 평가 기준(벤치마크)에서 1위"라고 밝혔다. 자사 주장인 만큼 수치 만큼 성능이 탁월한지는 실제 사용하면서 확인해 보자.

생각하는 방식이 기존 모델과 다르다

기존 Claude 모델들은 '깊이 생각하는 모드'를 필요할 때 켜고 끌 수 있었다.

Fable 5는 이 방식 대신 '적응형 추론(adaptive thinking)'이 항상 켜져 있다 — AI가 알아서 얼마나 깊이 생각할지 조절한다는 뜻이다. 끄는 옵션이 없고, 생각 깊이는 low·medium·high·xhigh·max 5단계로만 조절한다(기본값 high). AI가 생각하는 과정 자체는 사용자에게 보이지 않는다.

공개 스펙을 보면 이번 라인업은 '더 똑똑한 모델'과 '덜 똑똑한 모델'의 구분이 아니라, 같은 모델에서 안전장치 두께만 달리한 구조로 설계됐다. 모델 차별화의 축이 성능에서 접근 권한으로 옮겨간 모양새이고, 이 관점을 잡고 이후 내용을 이해해보자.

2. 미토스? 페이블? — 세 모델 이름 정리

혼란에는 이유가 있다. 발표 제목에 Fable 5와 Mythos 5가 나란히 들어 있고, Mythos는 한국어로 '미토스'로도 '미쏘스'로도 읽혀 검색어부터 갈린다. 실제로 한국 개발 커뮤니티 GeekNews에서는 '미소스'라는 표기도 등장한다. 게다가 두 달 전에 나온 Claude Mythos Preview까지 있어서 'Mythos'가 붙은 이름만 둘이다.

Mythos 5의 정체는 발표문에서 정의한 내용을 살펴보자.

"the same underlying model as Fable 5, but with the safeguards lifted in some areas."
(Fable 5의 기반 모델과 동일하지만, 일부 도메인에서 안전 규제(Safeguards)를 완화한 모델입니다.)

즉 Mythos 5는 별도의 더 뛰어난 모델이 아니다.

Fable 5와 같은 기반 모델에서 일부 영역의 안전장치를 들어낸 버전이고, 그래서 배포가 Project Glasswing에 참여한 사이버 방어자·인프라 제공자로 제한된다.

Anthropic은 추후 trusted access(신뢰 기반 접근) 프로그램으로 접근을 넓힐 계획이라고 밝혔는데, 이는 아직 운영 전인 예정 단계다.

Claude Mythos Preview는 2026년 4월 7일 공개된 리서치 프리뷰 모델로, 당시에는 일반 공개 계획이 없다고 명시됐었다.

Glasswing 참가자에게 입력 $25/출력 $125(백만 토큰)로 제공된다.

구분	Claude Fable 5	Claude Mythos 5	Claude Mythos Preview
정체	일반 공개용으로 안전화한 Mythos-class	같은 기반 모델, 일부 안전장치 해제	2026-04-07 공개된 리서치 프리뷰
누가 쓰나	누구나 (API·구독 플랜)	Glasswing 승인 사이버 방어자	Glasswing 참가자
API 모델 ID	claude-fable-5	claude-mythos-5	claude-mythos-preview
가격 (입력/출력, MTok)	$10 / $50	$10 / $50	$25 / $125

셋의 차이는 한 줄씩이면 충분하다. Fable 5는 오늘 살 수 있는 제품, Mythos 5는 같은 모델의 제한 공개 변형, Mythos Preview는 두 달 전에 나온 직전 세대 프리뷰다.

3. 벤치마크

Anthropic 공식 발표

코딩 벤치마크 부터 보자.

SWE-Bench Pro(실제 오픈소스 소프트웨어 버그를 AI가 직접 찾아 수정하는 테스트)에서 Mythos 5/Fable 5는 80.3%를 기록했다. Opus 4.8이 69.2%, GPT 5.5가 58.6%, Gemini 3.1 Pro가 54.2%이고, 두 달 전의 Mythos Preview(77.8%)보다도 높다. 경쟁 모델들이 한 칸씩 밀렸다.

격차가 가장 크게 벌어진 항목은 FrontierCode Diamond다.

최고 난도 코딩 문제 150개 중 제일 어려운 50개만 추린 테스트인데, Mythos 5/Fable 5가 29.3%, Opus 4.8이 13.4%, GPT 5.5가 5.7%다. 29.3%라는 절대값이 낮아 보일 수 있는데, 경쟁 모델이 한 자릿수에서 13%대에 머무는 난도라는 점을 같이 봐야 의미가 잡힌다.

위 차트에서 X축은 문제 하나당 드는 평균 비용(달러), Y축은 점수이다.

Fable 5는 생각 깊이(effort)를 올릴수록 점수가 오른다 — 낮음(low) 약 11.5%에서 최고(max) 약 31%까지.

반면 Opus 4.8은 xhigh에서 13.4%로 정점을 찍고 max에서는 오히려 약 11%대로 내려온다.

더 많은 연산을 써도 점수가 오르지 않는다는 뜻이다.

GPT 5.5는 전 구간에서 약 5~6%로 평탄하다. 결국 이 차트가 보여주는 건 점수 자체가 아니라 '컴퓨팅 자원을 더 쓸수록 더 잘하는 능력'의 차이다 — 생각 깊이를 높이는 데 비용을 쓸 만한 첫 모델이라는 판단이 과하지 않다.

4. 가격과 이용 방법

가격은 AI에 보내는 텍스트(입력) 100만 토큰당 $10, AI가 돌려주는 답변(출력) 100만 토큰당 $50이다.

Fable 5와 Mythos 5 모두 같은 가격이며, 공식 발표는 이를 "Mythos Preview의 절반 이하 가격"으로 설명한다.

직전 최상위 모델인 Opus 4.8($5/$25)과 비교하면 두 배 비싸다.

모델	입력 (MTok)	출력 (MTok)	비고
Claude Fable 5 / Mythos 5	$10	$50	2026-06-09 출시
Claude Opus 4.8	$5	$25	직전 플래그십
Claude Mythos Preview	$25	$125	Glasswing 참가자 한정

표의 비교 기준은 2026년 6월 10일이고, 최신 가격은 공식 페이지에서 확인해야 한다.

재미있는 건 상위 모델이 더 싸졌다는 사실이다.

Mythos Preview를 쓰던 조직 입장에선 같은 등급 능력의 가격이 절반 이하로 내려온 출시다.

구독 사용자에게는 무료 프로모션이 있다.

6월 9일부터 22일까지 Pro·Max·Team·좌석 기반 Enterprise 플랜에 추가 크레딧 비용 없이 사용량에서 차감하여 사용 가능하다.

6월 23일에 해당 플랜에서 제거되며, 이후 사용은 usage credits(사용량 크레딧)가 필요하다.

기간 주의: 무료 포함은 2026년 6월 22일까지로 명시된 한시 조건이다. '플랜에 포함'이라는 글만 보고 6월 말에 쓰기 시작하면 크레딧 결제가 필요하다. 조건은 변경될 수 있으니 공식 페이지에서 확인 후 사용한다 (2026-06-10 기준).

[6/16 업데이트] 이 무료 프로모션은 2026-06-12 차단으로 사실상 중단됐다. 무료 기간(6/9~6/22)이 끝나기도 전에 모델 자체를 쓸 수 없는 상태다. 결제 후 못 쓰게 된 경우 환불 절차가 열렸다는 보도가 있으나(조건 변동 가능), 프로모션 연장 여부는 공식 발표가 확인되지 않았다.

[7/2 업데이트] 위 6/9~6/22 무료 프로모션과는 별개로, Anthropic이 2026년 7월 1일~7일 한정으로 새 프로모션을 열었다. 조건은 이전과 다르다 — 전액 무료가 아니라 구독 플랜(Pro·Max·Team·Enterprise) 주간 사용량 한도의 50%까지만 Fable 5에 쓸 수 있고, 그 한도를 넘기면 유료 사용량 크레딧으로 자동 전환된다. Anthropic은 "Fable 5는 Opus 4.8보다 사용량을 더 빠르게 소진한다"고 안내한다. 7월 8일 이후에는 다시 크레딧이 필요하다. (출처: Claude 지원센터 — Fable 5 프로모션 접속 안내)

Claude Code에서는 어떤 계정 타입에서도 기본 모델이 아니다. /model fable로 직접 선택해야 하며, Claude Code v2.1.170 이상이 필요하다 — 구버전에서는 모델 피커에 아예 표시되지 않는다.

어디서 쓸 수 있나 — 5개 경로

~~출시일부터 아래 5개 경로에서 바로 사용할 수 있다.~~ [6/16 업데이트] 아래 5개 경로는 출시일엔 모두 열려 있었으나 현재(6/12 차단 이후)는 전부 막혀 있다. 차단이 풀리면 같은 경로로 복귀할 것으로 보이나, 복구 시점은 미정이다. [7/2 업데이트] 수출통제 해제로 아래 5개 경로 모두 복귀했다. 7/1~7/7 한정으로 구독 플랜 주간 한도의 50%까지는 다시 무료로 쓸 수 있다. (출처: Anthropic 출시 발표 · 차단 성명 · 프로모션 재개 안내)

경로	대상	시작 방법
claude.ai 웹	누구나	채팅창 모델 선택기에서 Claude Fable 5 클릭
Claude Code (CLI)	개발자	`/model fable` 입력 (v2.1.170 이상 필수)
Anthropic API	개발자·기업	`model="claude-fable-5"` 지정
GitHub Copilot	Pro+·Business·Enterprise 구독자	Copilot 채팅 모델 선택기에서 Claude Fable 5 선택 (단계적 롤아웃 중)
AWS Bedrock · Vertex AI · Azure Foundry	기업·클라우드 팀	각 플랫폼 콘솔에서 모델 ID로 접근. 정확한 설정은 각 플랫폼 공식 문서 확인 필요

ex) claude.ai 웹

Claude Code에서 쓰는 방법

Claude Code(터미널에서 쓰는 개발자용 AI 도구)에서는 세 가지 방식으로 Fable 5를 지정할 수 있다.

세션 중 전환 (가장 간단)
/model fable
기본 모델을 Fable 5로 고정 (환경변수)
export ANTHROPIC_MODEL=claude-fable-5
하위 에이전트도 Fable 5로 통일
export CLAUDE_CODE_SUBAGENT_MODEL=claude-fable-5

안전 필터가 작동해 Opus 4.8로 전환된 뒤에는 대화가 끝날 때까지 Opus로 유지된다. 다시 Fable 5로 돌아오려면 /model fable을 재입력해야 한다. 이 점은 자동화 스크립트에서 가장 놓치기 쉬운 동작이다.

ex) /model > Fable 모델 선택

API 연동 예시 (Python)

API로 직접 연동할 때는 model을 바꾸고, 생각 깊이는 output_config의 effort 값으로 지정한다. Fable 5는 적응형 추론이 항상 켜져 있어서 thinking: {"type": "enabled", "budget_tokens": N} 방식은 지원하지 않는다. (출처: 공식 Effort 문서)

Python — Anthropic SDK
import anthropic
 
client = anthropic.Anthropic()
 
response = client.messages.create(
    model="claude-fable-5",
    max_tokens=16000,
    output_config={"effort": "high"},  # low / medium / high(기본값) / xhigh / max
    messages=[{"role": "user", "content": "여기에 요청을 입력"}]
)
print(response.content)

effort 단계 선택 기준 (출처: 공식 Effort 문서): high가 기본값이며 대부분의 작업에 적합하다. xhigh는 30분 이상 걸리는 장기 에이전트·코딩 작업 전용이다. max는 가장 어려운 추론 문제에만 쓰는 것이 권장된다. medium/low는 속도·비용을 아낄 때 쓴다. 단, Fable 5의 lower effort도 이전 모델 xhigh 수준을 초과하는 경우가 많다.

거절(refusal) 처리 — 개발자 주의: Fable 5가 요청을 거절할 때 API는 에러(4xx/5xx)를 반환하지 않는다. HTTP 200 성공 응답으로 오되 stop_reason: "refusal"이 포함된다. 거절된 요청은 과금되지 않으며, fallbacks 파라미터를 쓰면 서버에서 자동으로 다른 Claude 모델로 재시도한다. (출처: Refusals and fallback 공식 문서)

어떤 작업에 쓰면 좋나

Fable 5가 벤치마크에서 두드러진 영역과 공식 사례를 살펴 보자.

작업 유형	적합 이유
복잡한 코드베이스 리뷰·마이그레이션	SWE-Bench Pro 80.3% — 실제 오픈소스 버그를 직접 찾아 수정하는 능력
여러 단계를 거치는 긴 자동화 작업	적응형 추론이 항상 켜져 있어 단계 간 맥락 유지가 강점
정밀한 문서·보고서 작성	장기 집중 유지 + 자기 노트로 출력 개선 — Anthropic 공식 설명 인용
대용량 데이터 분석	100만 토큰 컨텍스트 윈도우 — 큰 파일을 잘라 넣지 않아도 됨

이런 작업은 주의: 사이버 보안·생물학 관련 작업은 안전 필터가 작동해 Opus 4.8 수준으로 내려간다 (5장 참고). 빠른 단답이나 간단한 질문은 굳이 Fable 5를 쓸 이유가 없다 — 비용 대비 효과가 낮다.

루프를 설계하라 — 명령 대신 판을 깔아라

Anthropic 연구원 랜스 마틴(Lance Martin)이 출시 당일 올린 글의 첫 줄이다.

"Fable 5한테는, 직접 시키지 마세요." 이전 모델들은 단계마다 사람이 붙어서 방향을 잡고 수정을 요청해야 했다. Fable 5는 다르다. 목표와 채점 기준만 환경에 깔아두면 Claude가 알아서 한 번 시도하고, 기준에 비춰보고, 틀린 부분을 고치고, 기준이 충족될 때까지 다시 돌아간다. (출처: Lance Martin, X, 2026-06-09)

이 방식을 루프(loop)라 부른다. 핵심은 두 가지다. 목표(Goal)와 채점 기준(Rubric)을 명확히 정의할 것, 그리고 채점은 반드시 외부 채점자가 맡게 할 것.

왜 모델이 자기 결과를 직접 채점하면 안 되나: 모델은 자기가 만든 결과를 자기가 검토하는 데 약하다. 자기 코드를 사람이 쓴 것처럼 위장해 검사를 통과하려 시도하거나, 보안 이슈를 찾았다고 단언했는데 실제 테스트 세션은 비어 있었던 사례가 보고된다. 생성과 검증은 서로 다른 에이전트나 사람이 맡아야 한다.

루프를 구현하는 실제 방법은 크게 둘이다.

구성 요소	Claude Code `/goal`	Claude Managed Agent Outcomes
목표	측정 가능한 완료 상태	채점 가능한 기준(Rubric)
채점자	독립된 소형 모델 (예: Haiku)	독립된 채점 서브에이전트
루프 동작	미달 판정 → 다음 턴 자동 시작	실행 → 채점 → 수정 반복
종료 조건	조건 충족 자동 종료 또는 `/goal clear`	Rubric 통과 또는 `max_iterations` 도달
피드백	채점 모델의 피드백	채점 서브에이전트의 피드백

이 루프 구조에서 실무적으로 정착 중인 조합이 있다.

Fable 5를 오케스트레이터로, Sonnet 계열을 워커로 쓰는 Hub-and-Spoke 패턴이다. Fable이 전체 맥락과 목표를 관리하고, 반복적이거나 기계적인 단위 작업은 저렴한 Sonnet 워커가 처리한다. Fable 단독으로 쓸 때보다 비용을 낮추면서도 복잡한 다단계 작업을 처리하는 방식으로, 커뮤니티에서 표준 구조로 자리 잡는 추세다.

5. 안전장치 3가지와 위험 요청 처리 방식

이번 출시에서 기술적으로 가장 눈여겨볼 부분이다.

Fable 5의 안전장치는 모델 자체의 성능을 낮추는 방식이 아니다. 내부 감지기가 위험한 요청을 탐지하면, 그 요청만 더 보수적인 모델(Claude Opus 4.8)이 대신 처리하도록 넘기는 구조다.

영역	동작	비고
해킹·사이버 공격 관련 요청	감지기 탐지 → Opus 4.8로 전환	초기 데이터 기준 전체 대화의 95% 이상은 이 전환 없이 진행됨
생물·화학 무기 관련 민감 요청	감지기 탐지 → Opus 4.8로 전환	공인 연구자에게는 예외 허용 프로그램 운영 예정 (발표 기준)
AI 모방 학습(증류)	감지기 탐지 → Opus 4.8로 전환	Fable 5 답변으로 다른 AI를 학습시키는 행위 차단

세 영역 모두 작동 방식은 같고 막는 대상이 다르다. 숫자 하나만 기억하면 된다. '전체 대화의 95% 이상은 이 전환이 아예 발생하지 않는다.' 일반 작업에서는 체감할 일이 드물다는 뜻이지만, 뒤집으면 사이버 보안·생물학 영역 작업에서는 항상 이 전환이 작동한다는 뜻이기도 하다.

사이버 영역 평가 결과도 수치로 공개됐다. 이미 알려진 'AI 탈출 기법'을 사용해서 해킹 계획 짜기·공격 코드 작성·보안 우회 방법 같은 유해한 요청을 보냈을 때, Fable 5가 이를 들어준 비율은 0%였다.

외부 공격 테스트 결과도 공개됐다.

보안 전문가들이 1,000시간 이상 AI를 뚫으려 시도했지만 'AI를 완전히 제어하는 만능 탈출법'은 찾지 못했다. 단, 같은 발표문에 영국 AI 안전 연구소(UK AISI)가 짧은 초기 테스트 기간에 그런 탈출법에 근접하는 진전을 이뤘다는 내용도 함께 붙어 있다. 이 대목은 '안전하다'는 신호가 아니라 '공격 기술이 빠르게 발전하고 있다'는 경고다. Anthropic이 이 불편한 결과를 숨기지 않고 함께 공개한 점이 오히려 눈에 띈다.

왜 Mythos 5는 일반에 공개하지 않나 — 공격 능력 때문이다

Anthropic이 공개한 자체 평가에서 Mythos 5는 실제로 작동하는 사이버 공격 코드(익스플로잇)를 90%의 성공률로 만들어낸다. Anthropic 스스로 "우리가 평가한 모델 중 전반적인 사이버 공격 능력이 가장 강하다(strongest overall cyber capabilities of any model we have ever evaluated)"고 밝혔다. "아직 완전 자율적인 공격 도구 수준은 아니다(hasn't yet crossed into a fully autonomous cyber offense tool)"는 단서를 달았지만, 기존 Fable 5의 안전 필터만으로는 이 수준의 능력을 통제하기 어렵다는 판단에서 약 200개 심사된 조직 한정으로만 제공한다. 2장에서 설명한 'Project Glasswing을 통한 사이버 방어자 한정 배포'가 이 맥락에서 나온 결정이다. (출처: BankInfoSecurity — Claude Mythos 5 Can Build Exploits)

[6/16 업데이트] 이 안전장치가 바로 차단 사건의 핵심이었다. 2026-06-12 미국 정부가 문제 삼은 것은, 위 표의 사이버 능력(Mythos급)을 막아야 할 Fable 5의 안전 필터를 우회하는 탈옥(jailbreak)이 보고됐다는 점이다. Anthropic은 그 탈옥을 "특정 코드베이스를 읽혀 결함을 찾게 하는 좁은(narrow) 방식이며 GPT-5.5 등 다른 모델에도 있는 수준"이라고 반박했지만, 정부는 수출통제 지침으로 두 모델을 전면 차단했다. 즉 '안전장치를 두께로 나눠 배포한다'는 이번 출시의 설계가, 그 안전장치 신뢰성을 둘러싼 분쟁으로 사흘 만에 시험대에 올랐다. (출처: Anthropic 차단 성명)

'AI가 사람의 의도를 얼마나 잘 따르는가'를 측정하는 정렬 평가에서는, Mythos 5가 엇나가는 행동을 하는 비율이 낮고 Opus 4.8과 비슷한 수준이라는 것이 공식 차트의 요지다. 더 자세한 평가 내용은 발표와 함께 공개된 시스템 카드 문서에 수록돼 있다.

데이터 보관 정책도 다른 모델과 다르다. Fable 5·Mythos 5는 대화 내용을 안전 목적으로 30일간 보관하는 것이 의무다. 이 기간에 Anthropic 직원이 데이터를 열람하면 전부 기록에 남고, 30일 후에는 거의 대부분 삭제된다. 두 모델은 '데이터를 아예 저장하지 않는 환경(ZDR, Zero Data Retention)'에서는 사용할 수 없다.

규제·보안 민감 조직 주의: 사내 규정이나 계약서에 '데이터를 외부에 보관하지 않겠다'는 조건이 있다면 Fable 5는 쓸 수 없다. GitHub Copilot에서도 다른 Claude 모델은 이 제한이 없지만 Fable 5만 30일 보관 조건이 붙는다. 어떤 경로로 쓰든 도입 전에 데이터 정책을 먼저 확인해야 한다.

개발자 직접 연동 시 알아둘 동작

내부 필터(classifier)가 요청을 거부하면 에러 코드가 아니라 정상 응답 형태로 반환하되, 거부 이유를 별도 필드로 알려 준다. 자동 재시도 옵션(fallbacks 파라미터, 베타)도 제공된다. 거부된 요청은 답변이 생성되기 전이면 과금되지 않는다. API를 코드에 연결할 때 거부 상황을 처리하는 분기를 미리 넣어 두는 편이 안전하다.

비용 세부는 AWS가 따로 정리했다. Amazon 클라우드(AWS)에서는 미국 동부·유럽 서버부터 출시 당일에 제공됐다. 위험 요청이 Opus 4.8로 넘어가면 그 부분은 Opus 가격으로 청구되고, 대화 중간에 차단될 경우 차단 전까지는 Fable 가격, 이후 처리는 Opus 가격으로 나뉜다. (출처: AWS 공식 블로그)

구조 전체를 놓고 보면, 1,000시간 무사고 기록과 영국 AI 안전 연구소의 '진전' 보고가 한 발표문에 공존한다는 사실이 설계 철학을 드러낸다. Anthropic의 선택은 '절대 안 뚫린다'가 아니라 '뚫려도 운영으로 수습한다'에 가깝다. 위험 감지 시 다른 모델로 전환, 30일 보관, 접근 전수 기록이 전부 사후 대응 장치인 것만 봐도 그렇다.

6. 고객 사례와 실전 성능 — Stripe의 하루·게임 생성·포켓몬 완주

발표문에서 가장 회자될 사례는 결제 서비스 기업 Stripe다. 5,000만 줄 규모의 Ruby(프로그래밍 언어) 코드 전체를 새 방식으로 전환(마이그레이션)하는 작업을 하루 만에 해냈다. 사람이 손으로 했다면 팀 전체가 2개월 이상 걸렸을 분량이다.

AI 코딩 에디터 Cursor는 자체 평가 기준에서 Fable 5를 최고 성능 모델로 꼽으며, "기존 모델로는 엄두 내기 어렵던 길고 복잡한 작업 유형이 이제 가능해졌다"고 평가했다. 금융 AI 기업 Hebbia도 자체 금융 평가 기준에서 어떤 모델보다 높은 점수가 나왔다고 밝혔다.

화면 인식 쪽 사례는 두 가지다. 화면 캡처(스크린샷)만 보고 웹 서비스의 전체 코드를 재구성했고, 화면만 보는 방식으로 포켓몬 게임 FireRed를 처음부터 끝까지 완주했다 (공식 타임랩스 영상은 아래 참조). 이 글의 벤치마크 이미지 판독(3장)도 결국 같은 능력을 빌렸으니, 발표문 사례 중 이 항목만큼은 직접 검증한 셈이다.

Mythos 5 쪽 과학 성과는 별도로 소개됐다. 내부 단백질 설계 전문가의 신약 설계 프로세스 일부를 약 10배 가속했고, 연구 대상 14개 단백질 타깃 중 9개에서 유력한 설계 후보를 얻었다. 블라인드 비교에서 과학자들은 Mythos의 분자생물학 가설을 약 80% 비율로 선호했다.

단일세포 유전체학 사례도 있다. 138종 동물에 걸친 수백만 세포의 단일세포 데이터를 자율적으로 조립하고 커스텀 머신러닝 모델을 직접 설계·훈련했는데, 이 모델이 Science에 게재된 최신 모델보다 100배 작으면서 성능은 더 높았다는 설명이다.

사례들을 나란히 놓고 보면 공통점이 보인다. "빠른 답변이 좋다"는 사례가 하나도 없다. 코드 전환, 복잡한 장기 작업, 게임 완주, 대규모 데이터 분석 — 전부 '오래 오래 달리는 작업' 이야기다. Anthropic이 이번 모델의 차별점을 어디에 두는지는 사례 선정 자체가 말해 준다.

한 문장으로 3D 게임 만들기

발표 직후 가장 많이 공유된 데모는 게임 생성이다. 아이디어를 한 문장으로 입력하면 브라우저에서 바로 실행되는 완성된 게임이 나온다. 연구자 Ethan Mollick이 Claude Code에서 직접 만들어 공개한 사례들이 대표적이다.

게임	한 줄 설명
Library of Babel 탐험기	무한한 책이 꽂힌 가상 도서관을 탐험하는 3D 브라우저 게임
자기 인식 뱀(Snake)	게임이 자신이 뱀 게임임을 인식하며 반응하는 메타 버전의 Snake
Strata	지하 터널에서 랜턴을 켜 나가는 어드벤처 — 고전 게임 Myst풍 그래픽
Duino	시인 라이너 마리아 릴케의 '두이노 비가' 시집을 기반으로 만든 게임

포켓몬 FireRed 완주 영상 — 공식 공개 타임랩스

Anthropic이 직접 공개한 영상이다. 화면 캡처(스크린샷) 외에 지도·좌표·게임 상태 정보 같은 보조 도구를 일절 주지 않은 상태에서, Fable 5가 시각 정보만으로 포켓몬 FireRed를 처음부터 끝까지 완주한 과정을 타임랩스로 담았다. 이전 Claude 모델들은 추가 도구를 줘도 이 게임을 완주하기 어려웠다. (출처: Shacknews)

▲ Anthropic 공식 공개 — 화면만 보고 포켓몬 FireRed 완주 (타임랩스)

7. 한계와 주의점 — 별표 영역·토큰 증가·데이터 보존

먼저 별표 영역. 사이버 보안·생물학 관련 작업이 주 업무라면, 3장 표의 별표 수치는 내 환경의 수치가 아니다. Fable 5는 해당 영역에서 안전 필터가 작동해 Opus 4.8에 가까운 성능으로 동작한다. 보안 연구 도구에 Fable 5를 연결할 계획이라면 기대치를 표가 아니라 Opus 4.8에 맞추는 것이 현실적이다.

기존 프롬프트와 스킬을 그대로 쓰면 오히려 품질이 떨어진다. 이전 모델용으로 만든 단계별 지시나 스킬 프롬프트는 Fable 5에서 충돌을 일으킨다. 모델 능력이 뛰어나서 지시가 적어도 되는데, 과도한 안내를 받으면 지시 간 충돌이 일어난다는 것이 커뮤니티 합의다. 기존 스킬을 정리하고 CLAUDE.md를 처음부터 점검하는 것이 권장된다. 단계별 지시 대신 최종 목표만 넘기는 방식이 훨씬 효과적이다.

단순 작업에서는 토큰 소비 상한을 설정하지 않으면 타임아웃까지 토큰을 과도하게 쓰는 현상이 보고된다. 루틴하거나 간단한 작업에 Fable 5를 투입할 때는 effort를 low 또는 medium으로 낮추거나, API 호출 시 max_tokens를 명시적으로 제한해 두는 것이 좋은 것 같다.

비용 계산에도 함정이 하나 있다. Fable 5는 텍스트를 처리 단위(토큰)로 쪼개는 방식이 바뀌어서, 예전 모델들보다 같은 텍스트를 약 30% 더 많은 토큰으로 계산한다. Opus 4.8과는 같은 방식을 쓰므로 '단가 2배' 비교는 그대로 유효하지만, 더 오래된 모델에서 넘어오는 경우라면 토큰 수 증가까지 겹쳐 체감 비용이 단가 차이 이상으로 커질 수 있다.

AI의 사고 방식도 통제 변수다. 항상 켜져 있는 적응형 추론은 끌 수 없고, 기존에 쓰던 '응답 길이 제한' 설정이 Fable 5에는 통하지 않는다. 자동화된 작업에서 응답 분량을 관리하고 있었다면, '생각 깊이 조절 옵션(low·medium·high·xhigh·max 5단계)'으로 대신 조절하는 방식에 먼저 익숙해져야 한다.

추론이 길어지는 작업은 첫 답변이 나오기까지 상당한 시간이 걸릴 수 있다. 복잡한 작업에서 오랫동안 화면에 아무 출력 없이 AI가 내부 추론만 하는 사례가 실사용자들 사이에서 공유되고 있다. 공식 명세가 아닌 사용 경험 기반 수치이므로 환경마다 다를 수 있지만, 타임아웃 설정이나 '응답 없으면 오류'로 처리하는 자동화 흐름이 있다면 이 대기 구간을 미리 고려해야 한다.

비용 계획과도 연결된다. 실제 답변이 시작되기 전 사고 단계에서 이미 상당한 토큰이 소모된다. 실사용 사례 기준으로 내부 추론에만 5만~10만 토큰을 쓰고 나서 첫 출력이 시작되는 경우가 보고된다. 역시 공식 수치가 아닌 사용 경험 데이터지만, 구독 할당량이나 API 예산을 짤 때 '답변에 쓰인 토큰'보다 실제 청구 토큰이 훨씬 많을 수 있다는 점을 미리 반영해 두는 것이 좋다.

Claude Code(개발자용 CLI 도구) 사용자라면 자동 모델 전환 동작을 알아둘 필요가 있다.

내부 필터가 요청에 반응하면 해당 요청을 Opus 4.8로 처리하고 대화 기록에 알림을 남긴다. 놓치기 쉬운 건 그다음이다.

이후 대화 전체가 Opus로 계속된다.

Fable 5로 돌아가려면 /model fable을 다시 입력해야 한다.

첫 요청에 담기는 프로젝트 설정 파일이나 작업 현황 정보만으로도 필터가 반응할 수 있다.

커뮤니티 보고 기준으로 평균 5% 미만 발생하지만, 정상적인 보안 감사 작업이나 의료 데이터 분석(MRI 등)에서도 분류기가 오발동해 Opus로 강제 전환되는 사례가 다수다. CLAUDE.md나 스킬 프롬프트에 '보안', '취약점', '분석' 같은 단어가 있으면 첫 요청부터 트리거되기도 한다.

안전 필터가 자주 작동한다면: claude --safe-mode로 실행하면 내 설정 파일(CLAUDE.md 등)이 원인인지 분리해서 확인할 수 있다. 설정에서 자동 전환 대신 매번 확인하도록 바꾸는 옵션도 있다. 의외로 자주 막히는 부분이 '나도 모르게 Opus로 전환된 채 작업을 계속하는' 상황이다.

이 '과도한 차단' 문제를 Anthropic도 모르지 않는다. 발표문은 "더 뛰어난 모델들이 몇 달 안에 도착하는 만큼, 안전장치를 개선하고 잘못 차단되는 경우를 최대한 빨리 줄이는 작업을 병행하고 있다"고 밝혔다.

반대편 문제도 있다. 자율성이 너무 높아 선을 넘는 경우다.

출시 직후 한 사용자가 겪은 일이다. 저장소에 "버그 있다"고 한마디 했더니 Fable이 버그를 고쳤다. 거기서 멈추면 다행인데 gh CLI로 GitHub PR까지 올려버렸다. CONTRIBUTING.md를 따른다는 이유를 대면서. PR 자체는 멀쩡했지만, Claude 혼자서 세 가지를 넘겨짚은 것이다. '내 자격증명을 써도 된다', '이 변경에 만족할 것이다', '바로 올려도 된다'. 버그 있다는 말 한마디에서 이 셋을 끌어낸 것이다.

Anthropic 시스템 카드도 비슷한 패턴을 경고한다. 감독 없이 두면 모델이 알아서 간다는 것이다. 이제 Fable 5를 쓰는 개발자들은 "이건 하지 마라"를 일일이 명시해야 하는 상황이 됐다는 보고가 나온다. 자율성이 높아질수록 허용 범위를 먼저 정의하는 것 자체가 설계의 일부가 됐다.

자율성 범위 설정 체크리스트: 자격증명 사용 범위를 명시한다. GitHub·Slack 등 외부 시스템에 자동으로 쓰는(push, post, send) 행동을 허용할지 미리 정한다. 최종 출력·배포 전 사람 확인 단계를 남겨둔다. 허용하지 않는 행동은 프롬프트나 CLAUDE.md에 "~는 하지 말 것" 형식으로 명시한다.

결국 도입 판단의 갈림길은 내 작업의 분야다. 보안 연구·생물학 분야는 기대치를 Opus 4.8 수준에 맞추고 시작하는 편이 낫고, 일반 코딩·반복 작업은 ~~무료 기간에 직접 써보고 판단하면 된다~~ [6/16] — 차단이 풀린 뒤 무료 기간이 남아 있으면 직접 써보고 판단하면 된다(6/16 현재 차단으로 테스트 불가). 데이터 정책(30일 보관, 무저장 환경 불가)은 5장에서 짚었듯 분야와 무관하게 먼저 확인해야 할 사항이다.

8. Q&A와 결론 — 도입 판단 가이드

Q1. '미토스 5'를 써보고 싶은데 어디서 신청하나

일반 제공 경로가 없다. Mythos 5는 Project Glasswing 승인 고객 한정이며, 일반 사용자·기업이 오늘 쓸 수 있는 모델은 Fable 5다. 능력 차이는 대부분 벤치마크에서 1~3%p 이내라는 것이 공식 방법론 주석의 설명이다.

Q2. 무료 기간이 끝나면 어떻게 되나

6월 23일에 구독 플랜에서 제거되고, 이후 사용은 별도 사용 크레딧(유료)이 필요하다. API 직접 사용 요금은 입력 100만 토큰당 $10, 출력 100만 토큰당 $50이다. 2026년 6월 10일 기준 조건이므로 사용 시점의 공식 페이지 확인이 필요하다.

[6/16 업데이트] 지금은 '무료 기간이 끝나면'을 따질 단계가 아니다. 6/12 차단으로 무료 기간(~6/22) 안에서도 모델을 쓸 수 없다. 차단이 풀려야 무료/크레딧 구분이 의미를 갖는다. 복구 시점은 미정.

[7/2 업데이트] 차단이 풀렸고, 2026년 7월 1일~7일 한정으로 구독 플랜 주간 사용량 한도의 50%까지는 다시 무료로 쓸 수 있다. 한도를 넘기면 유료 사용량 크레딧으로 전환되고, 7월 8일 이후에는 이전처럼 크레딧이 필요하다.

Q3. Opus 4.8에서 갈아탈 가치가 있나

일반 코딩·장기 에이전트 작업이라면 벤치마크 격차가 크다 — SWE-Bench Pro 80.3% 대 69.2%, FrontierCode 29.3% 대 13.4%. 반대로 사이버 보안·생물학 관련 작업이라면 안전 필터가 작동해 Opus 4.8 수준으로 내려가므로 두 배 비용의 의미가 없다. 갈림길은 모델 성능이 아니라 내 작업의 분야다.

Q4. 회사 데이터 정책이 엄격한 환경인데 쓸 수 있나

Fable 5는 대화 기록을 30일간 보관하는 것이 의무라서, 데이터를 저장하지 않는 '무저장 환경(ZDR, Zero Data Retention)'에서는 사용이 불가하다. 회사 규정 검토가 모델 선택보다 먼저다. GitHub Copilot을 통해 쓸 때도 Fable 5만 이 30일 보관 조건이 적용된다.

상황	판단
일반 코딩·장기 에이전트 작업	~~무료 기간(6/22까지)에 실측 후 전환 검토~~ [6/16] 차단 해제 후 실측 — 현재 사용 불가, 대안은 Opus 4.8 [7/2] 차단 해제됨 — 7/1~7/7 한정 프로모션(주간 한도 50%)으로 지금 실측 가능
사이버 보안·생물학 도메인 업무	안전 필터 작동 시 Opus 4.8 수준으로 내려감 — 기대치 조정
데이터 무저장(ZDR) 필수 환경	사용 불가 — 기존 모델 유지
비용 신경 쓰임 + Opus 4.8로도 충분한 작업	단가 2배의 가치를 자기 데이터로 판단
Mythos 5 사용 희망	일반 제공 없음 — Glasswing 대상 조직만

한 줄로 요약하면, 이번 결정의 변수는 '모델이 좋은가'가 아니라 '내 도메인이 별표에 걸리는가'와 '데이터 정책이 허용하는가' 두 가지다.

공식 발표가 말해 주지 않는 것

벤치마크 수치가 본문 텍스트가 아니라 이미지로만 제공된다 — 검색·인용에 불리하고, 이 글이 판독치를 텍스트로 옮긴 이유다
'전체 대화의 95% 이상은 안전 필터 작동 없음'은 전체 통계다 — 내 작업의 필터 작동 빈도는 분야에 따라 다르므로 직접 확인해야 한다
시스템 카드의 세부 분량이나 학습 데이터 기준일은 공식 페이지에서 확인되지 않는다 — 이 글도 해당 정보는 다루지 않는다

오늘 바로 해볼 것 4가지 ([7/2] 차단 해제 — 4가지 모두 지금 가능, 단 1·2번은 7/1~7/7 프로모션(주간 한도 50%) 기간에 시도할 것)

Claude Code(개발자용 Claude 도구) 사용자라면 v2.1.170 이상 버전인지 확인하고 /model fable을 입력해 본다 — [7/2] 차단 해제로 다시 가능
평소 주력 작업 하나를 Fable 5로 돌려 안전 필터 알림이 얼마나 뜨는지 확인한다 — [7/2] 차단 해제로 다시 가능(7/7까지 주간 한도 50%는 무료)
API로 연동 중이라면 거부 응답 처리 코드를 추가한다 (stop_reason "refusal" 분기) — 지금 가능
30일 데이터 보관 정책이 조직 규정과 충돌하는지 먼저 확인한다 — 지금 가능

출시 당일 Hacker News에는 발표 스레드와 별개로 시스템 카드 PDF가 따로 제출됐을 만큼 관심이 안전장치 세부에 쏠렸다. (참고: Hacker News 스레드) 성능 수치보다 '같은 모델을 안전장치 두께로 나눠 배포하는 구조'가 이번 출시의 진짜 뉴스라는 방증으로 읽힌다.

한국 커뮤니티 반응 — 기대와 우려의 공존

한국 개발 커뮤니티 GeekNews의 출시 토픽 두 건(출시 정리 토픽, 후속 토론 토픽)에서는 Opus 4.8 대비 벤치마크 점프에 대한 기대가 먼저 눈에 띈다. 동시에 보안 제한을 해제한 Mythos 5가 공격 용도로 쓰일 가능성 — 이른바 '바이브 해킹' — 을 걱정하는 시각도 있다. 같은 스레드 안에 기대와 우려가 나란히 놓인 모양새다.

[6/16 추가] 차단 사건 타임라인과 시장 함의

상단 긴급 박스의 요약을 사건 순서로 풀면 이렇다. (출처: 요즘IT, 2026-06-15 · Anthropic 성명 · Fortune)

시점	사건
6/9	Fable 5 · Mythos 5 출시 (이 글의 원본 작성 시점)
6/11~12	아마존 연구진이 탈옥 기법 발견 → CEO가 미 행정부에 보고
6/12 오후 (ET)	상무부 장관 서한 수령 → 같은 날 두 모델 전면 차단
6/15~16	차단 지속, 공식 복구일 미정 ([추정] 예측시장 6/20 이전 복구 ~70~79%)
7/1 무렵	미국 상무부, Fable 5·Mythos 5 수출통제 지침 해제 → 전 세계 차단 해제
7/1~7/7	Fable 5 프로모션 접속 재개(구독 플랜 주간 한도 50%, 초과 시 유료 크레딧)

한국 개발 커뮤니티(GeekNews) 반응 (출처: 차단 토픽)

"안전성을 강조한 마케팅이 제 발등을 찍었다" — 위험을 강조해 온 마케팅이 규제의 빌미가 됐다는 역풍론이 다수.
"업무용 도구로 신뢰하기 어렵다" — 단일 벤더 의존의 사업 리스크 지적.
소버린 AI · 독립 파운데이션 모델 필요성 언급.

요즘IT 기사가 짚은 함의 (아래는 해당 기사의 분석)

단일 벤더 · 단일 국가(미국) 모델에 대한 의존도를 재검토하는 압력.
[기사 분석] 차단과 맞물려 중국 Moonshot의 Kimi K2.7-Code 공개 등 오픈소스 대안에 시선 이동.
[기사 분석] Cohere(캐나다) · Mistral(프랑스) 등 비미국 모델 / 소버린 AI 논의 확대.

한국 팀에게 실질적 교훈: 핵심 워크플로를 한 모델에 묶지 말 것. Fable 5처럼 하루아침에 막힐 수 있으니, 동급 대체 경로(우선 Opus 4.8, 나아가 타사 · 오픈소스 모델)를 미리 확보해 두는 편이 안전하다.

[7/2 추가] 차단 해제 & 프로모션 재개 타임라인

차단 사건 이후 흐름을 이어서 정리하면 이렇다. (출처: Anthropic 공식 트윗 · Claude 지원센터)

수출통제 해제: 미국 상무부가 Fable 5·Mythos 5에 대한 수출통제 지침을 해제했다. Anthropic은 보안 위험 탐지, 미 정부와의 프로토콜 협력, 악의적 사용 신고 등을 조건으로 합의하며 통제에서 벗어났다고 밝혔다. Hacker News에서 900점대로 화제가 됐다.
프로모션 재개: 2026년 7월 1일~7일 한정으로 Fable 5 접속이 다시 열렸다. 단 조건은 6월과 다르다 — 전액 무료가 아니라 구독 플랜 주간 사용량 한도의 50%까지만 적용되고, 초과분은 유료 사용량 크레딧으로 자동 전환된다. Hacker News 80점.
복귀 경로: claude.ai·Claude Code·Anthropic API·GitHub Copilot·클라우드 3사(AWS Bedrock·Google Vertex AI·MS Foundry) 5개 채널 모두 차단 이전과 동일하게 복귀했다.

남은 불확실성: 이번 프로모션이 끝나는 7월 8일 이후 조건이 6월 수준(플랜 포함, 별도 크레딧 불필요)으로 되돌아갈지, 아니면 이번의 '주간 한도 50%' 방식이 새 기본값이 될지는 공식적으로 확인되지 않았다. 최신 조건은 반드시 Claude 지원센터 페이지에서 확인한다.

~~첫 분기점은 6월 23일이다. 무료 기간의 실측 데이터가 크레딧 전환 이후의 판단 재료가 된다.~~ [6/16] 지금의 첫 분기점은 6월 23일(크레딧 전환)이 아니라 차단이 언제 풀리느냐다. 차단이 무료 기간을 잠식하고 있어 실측 자체가 미뤄진 상태다. [7/2] 차단은 풀렸고, 지금의 분기점은 7월 7일(프로모션 종료)과 7월 8일 이후 조건이 어떻게 바뀌는지다. 이 글의 하네스 런 실측치는 8장에 남겼으니, 같은 결정을 앞둔 독자에게 비교 기준 하나가 되면 충분하다.

참고 자료

작성일: 2026-06-10 (발표 다음 날) · 수정일: 2026-07-02 (수출통제 해제 · Fable 5 프로모션 재개 반영, 6-16 수정분에 이어 두 번째 갱신)

벤치마크 수치: 공식 벤치마크 이미지에서 직접 판독한 값이다. 인용 시 본문 첨부 이미지 원본과 시스템 카드 대조를 권장한다.

가격·무료 프로모션 조건은 이후 변경될 수 있다. 최신 내용은 공식 발표 페이지에서 확인하는 것을 권장한다.

Codex Mac App 가이드(3) : Codex App 펫(Pets) 사용 방법 : 백그라운드 AI 에이전트 실시간 모니터링, 나만의 픽셀 아바타 만들기

갓대희 — Sat, 30 May 2026 18:32:47 +0900

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

Codex 에이전트에게 중장기 작업을 맡기면 늘 마주하는 문제가 있다. 백그라운드에서 연산 중인 에이전트가 지금 승인을 기다리는지, 이미 끝났는지, 아직 갈 길이 먼지 — 매번 Codex 창을 열어 확인해야 했다.

OpenAI가 이 불편함을 없앴다. 화면 구석에 떠다니는 작은 픽셀 캐릭터, Codex 펫(Pets)이 에이전트의 실시간 상태를 알려주기 시작한 것이다.

Codex 펫이란 백그라운드 에이전트의 작업 상태를 화면 위에 떠서 알려주는 선택형 애니메이션 캐릭터다(공식 명칭: "Optional animated companions"). 에이전트 상태를 색상·아이콘으로 구분하고, 말풍선을 클릭하면 Codex 본체 없이도 바로 답장을 보낼 수 있다. 기본 8종을 고르거나, /hatch 명령으로 나만의 펫을 만들거나, codex-pets.net 커뮤니티 펫을 가져올 수도 있다.

본 가이드는 2026년 5월 29일 발표 자료를 바탕으로 작성되었다.
공식 출처: Codex App 공식 개발자 가이드, codex-pets.net 커뮤니티 펫 아카이브. 커뮤니티 갤러리 수치 정보는 실시간 갱신되므로 최신 공식 페이지와 대조하길 권한다.

Codex Mac App 실무 정복 시리즈

Part 1: Codex App 기초 가이드 Part 2: Codex App 원격 연동 가이드Part 3: Codex App 펫(Pets) 활용 가이드 — 현재 글

펫의 탄생 배경 — 어떤 문제를 해결해 주는가
펫 활성화 옵션 — /pet 명령어와 시스템 단축키
기본 장착 가능한 8종 픽셀 펫 라인업
에이전트 3색 상태 변화 — Running · Waiting · Ready
인터랙티브 인라인 답변 — 양방향 소통 채널
/hatch 스킬 활용 — 세상에 단 하나뿐인 커스텀 펫 만들기
전 세계 펫 아카이브 — codex-pets.net 갤러리 활용
커뮤니티 펫 설치 방법
이용자 주의사항 — 동명 오픈소스 프로젝트 분리 및 저작권 가이드
요약 정리 — 펫 활용이 유용한 상황과 소환 해제 팁

1. 펫이란 무엇인가 — 왜 만들어졌나

기존 Codex 자율 에이전트의 아쉬운 점은 백그라운드 실행 중 진행 상황을 직관적으로 확인하기 어렵다는 것이었다.

Codex 본체가 트레이로 내려가 있거나 다른 IDE가 전면을 덮고 있어도, 픽셀 아바타는 항상 화면 최상단에 상주한다.

에이전트가 사람의 판단을 요구하는 순간 앱을 직접 찾아볼 필요 없이 펫이 그 자리에서 신호를 보낸다.

2. 펫 활성화 방법

다음과 같은 경로에서 펫을 활성화 있다. : 설정(Settings) > 모양(Appearance) > 펫(Pets)

1) 설정

2) 모양 클릭 > 우측 패널의 가장 하단으로 가보면 "펫" 메뉴가 보일 것 이다. 활성화 해보자.

3) 원하는 펫을 "선택" 클릭 > "펫 깨우기" 클릭(나의 경우 활성화 되어있어서 펫 숨기기로 캡쳐 되어있다.)

4) 처음 소환하면 기본 픽셀 캐릭터가 화면 우측 모서리에 나타난다.

5) 드래그 앤 드롭을 지원하므로, 시야를 방해하지 않는 구석이나 듀얼 모니터 한편으로 밀어두고 쓰면 된다.

6) 기본 내장 8종을 선택하거나, 커스텀 아바타를 로드할 수 있다.

3. 기본 제공 8종 펫 소개

설치 직후 선택할 수 있는 기본 펫은 총 8종이며, 화면 점유율을 최소화한 레트로 픽셀 아트 스타일로 그려져 있다.

기본 제공되는 모든 펫은 아래 3가지 조작을 지원한다.

인터랙션	동작 결과
드래그 이동	마우스 드래그로 화면 어느 구석이든 끌어다 배치 가능
메시지 버블	에이전트가 탐색·연산 중인 정보를 말풍선으로 표시
버블 클릭	메시지 버블 클릭 시 그 자리에서 에이전트와 지시를 주고받는 미니 입력창 팝업

4. 에이전트 상태 3종 — Running · Waiting · Ready

핵심은 3색 상태 지표다. 아이콘 색과 형태만 봐도 모델의 현재 상태를 바로 알 수 있다.

상태	시각적 표현	의미	권장 조치
Running	⚙️ 연산 중 애니메이션 + 말풍선	에이전트가 탐색하거나 코드를 수정하는 중	완성 전까지 다른 작업에 집중
Waiting for input	시계 아이콘 + 말풍선 대기	에이전트가 승인이나 추가 지시를 기다리며 멈춤	펫을 탭해 인라인 입력창에서 빠르게 승인
Ready for review	✅ 초록 체크 서클	목표 구현 완료, 코드 변경(Diff) 리뷰 대기	현재 작업 마무리 후 본체로 복귀해 리뷰 진행

갑자기 다른 펫으로 변경되었는데, 내가 만든 커스텀 펫 이다. (이후 섹션에서 만드는법은 설명 예정 이다.)

ex) Running

- 프로젝트 목록에서의 표시 방식 : 인디케이터가 돌아가는 모습

- 펫도 동일한 인디케이터가 돌아가고 있는 모습

ex) Waiting for input

- 프로젝트 목록에서의 표시 방식 : 승인 대기 중

- 펫 : 시계 아이콘

- 실제 세션 화면에서의 권한 승인 대기 상태

ex) 여러 작업을 병렬로 동작하는 모습

빨간 시계가 보이면 승인이나 추가 입력이 필요하다는 신호다.

ex) Ready for review

- 작업이 끝나면(목표 구현 완료, 코드 변경(Diff) 리뷰 대기 등) ✅ 초록 체크 서클 로 상태를 알려준다.

이 몇가지 표기만 눈에 익히면 Codex 창을 전환할 타이밍이 자연스럽게 잡힐 것 이다.

5. 인터랙티브 답변 기능 — 양방향 소통 채널

플로팅 펫은 진행 상태만 보여주는 단방향 위젯이 아니다.

메시지 버블을 클릭하면 그 자리에서 인라인 텍스트 패널이 열리고, 화면 포커스를 바꾸지 않고도 에이전트에게 피드백을 전달할 수 있다.

ex) 빨간 시계 알림 또는 Codex가 작업 중인 도중에도 갑자기 요청할 내용이 있다면 펫 메시지 버블에 바우스 오버레이 해보자.

- "답장" 이라는 버튼이 활성화 되니 클릭해보자.

- AI로 프롬프트를 보낼 수 있는 경량 텍스트 패널이 열린다.

처음에는 좁은 말풍선에 짧은 명령을 타이핑하는 게 어색했지만, 익숙해지면 빨간불이 들어왔을 때 승인 신호를 보내고 코딩으로 돌아오는 리듬이 자연스러워졌다.

긴 설계 지침은 본체 창에서, 짧은 확인과 분기 수락은 펫 버블에서 처리하면 된다.

6. /hatch — 나만의 펫 만들기

기본 8종 스킨이 마음에 들지 않거나, 나만의 브랜드 로고나 반려동물 모습을 화면에 띄우고 싶다면 Codex 입력창에 /hatch 명령을 입력하면 된다. 이미지를 드롭하거나 원하는 모습을 텍스트로 묘사하면 Hatch 스킬이 픽셀 스프라이트 펫을 만들어 준다.

입력 방식	세부 방법	출력 결과
이미지 업로드	/hatch 실행 후 로컬 파일 첨부	이미지를 분석해 9가지 동작의 픽셀 애니메이션으로 변환
텍스트 묘사	/hatch 후 원하는 아바타 특징을 텍스트로 입력	텍스트 프롬프트를 기반으로 AI가 픽셀 스프라이트 생성

스프라이트 프레임 생성에 약 30분이 걸리므로, /hatch 명령을 실행해 두고 다른 작업을 진행하는 게 낫다. 완성되면 자동으로 설정(Settings) > 모양(Appearance) > 펫(Pets) 목록에 등록된다.

ex) 난 이미지도 주고, 텍스트로도 묘사 하여 생성 요청 하였다.

- /hatch 펫을 만들고 싶어. 귀멸의 칼날 아카자 스타일의 펫을 만들어줘

( 사실 개인사용시 문제가 없곘지만, 블로그에 올린땐 이런 케릭터를 사용하는게 불편하신 분들이 계셔 블러처리 )

- 42분이나 걸렸다.

( 중간 사고과정을 보면 오래 걸릴만 한 작업으로 보인다.. 중간 사고 과정을 공유 )

7. 커뮤니티 갤러리 — codex-pets.net

기본 duck, flame 스킨에서 벗어나고 싶다면 codex-pets.net 갤러리를 한번 둘러보자.

전 세계 빌더들이 올린 다양한 테마 펫이 등록돼 있다.

이 사이트는 portons/codex-pet-share 오픈소스 커뮤니티가 MIT 라이선스 기반으로 자발적으로 운영하고 있다고 한다.

검색/정렬 필터	지원 사양
정렬 옵션	Newest · Liked · Viewed · Discussed · Random
종류별 카테고리(kind)	Object(사물) · Animal(동물) · Person(인물) · Creature(환상 정령)
태그 검색	커뮤니티가 부여한 키워드로 픽셀 스타일 검색 가능

마음에 드는 펫을 찾았다면 카드에 표시된 펫 ID를 메모해 두자. 바로 설치 명령어로 활용할 수 있다.

8. 커뮤니티 펫 설치 방법

갤러리에서 원하는 펫을 골랐다면, 아래 2가지 방법 중 로컬 환경에 맞는 방식을 선택하자.

① npx 명령어 한 줄 설치 (가장 간단)

npx codex-pets add <펫ID>
# 예시
npx codex-pets add scarf-cat-asset

Node.js가 설치된 환경이라면 터미널에 한 줄만 붙여 넣으면 끝난다. 갤러리 펫 카드 하단에 표시된 명령어를 그대로 복사해 실행하면 된다.

ex)

- npx codex-pets add guga

② ZIP 패키지 다운로드 후 수동 해제

# macOS / Linux 예시
mkdir -p "$HOME/.codex/pets/scarf-cat-asset"
unzip ~/Downloads/scarf-cat-asset.codex-pet.zip \
  -d "$HOME/.codex/pets/scarf-cat-asset"

브라우저로 ZIP 파일을 내려받아 OS별 펫 설치 경로에 폴더째 압축을 푸는 방법이다. Node.js 환경이 없거나 파일 내용을 직접 확인하고 싶을 때 쓰기 좋다. (macOS: $HOME/.codex/pets/ · Windows: %USERPROFILE%\.codex\pets\)

9. 주의사항 — 유사 이름 별개 프로젝트·저작권

아래 외부 프로젝트들은 Codex 공식 펫과 연동되지 않는다

검색하다 보면 이름이 비슷한 별개의 앱들이 함께 노출된다. 아래 3가지는 공식 Codex 펫과 무관한 독립 서비스다.

codingpets.com — 전혀 다른 목적의 유료 솔루션
codexpets.app — 이름만 비슷한 별개 서비스
codexpets/codex-pets (GitHub 오픈소스) — Codex를 넘어 Claude Code, Cursor 등 범용 IDE를 대상으로 한 별도 위젯형 데스크탑 마스코트

CLI 명령어 구조, 저장 디렉토리, 기능 연동 방식이 완전히 다르므로 혼동하지 않도록 주의하자.

커뮤니티 펫 사용 전 확인할 사항

출처 확인: codex-pets.net 아카이브는 전 세계 빌더들의 창작물 모음이다. OpenAI가 코드 감수나 보안 검토를 거친 자산이 아님을 염두에 두자.
팬아트 저작권 주의: 유명 캐릭터를 픽셀로 오마주한 2차 창작물이 섞여 있다. 기업 프레젠테이션이나 기술 방송에 펫을 띄울 때는 라이선스 리스크가 없는지 확인하는 편이 안전하다.
ZIP 내용물 점검: 이미지와 정적 JSON으로만 구성돼 악성 코드 위험은 낮지만, 수동 해제 시 엉뚱한 스크립트 파일이 없는지 확인하는 습관을 들이자.

10. 정리 — 펫을 쓰면 좋은 상황, 끄는 법

펫은 반드시 켜야 하는 기능이 아니다. 비활성화해도 자율 에이전트의 연산 능력이나 프롬프트 처리에는 아무 영향이 없다.

코딩 상황	권장 여부	이유
에이전트에게 무거운 프레임워크 리팩터링을 맡긴 긴 연산 주기	켜기	본체 앱 창을 오갈 필요가 없어진다
다중 병렬 서브에이전트를 동시에 실행 중인 복합 작업	켜기	어느 에이전트에서 문제가 생겼는지 주변시로 바로 파악 가능
30분 이내에 끝낼 가벼운 단기 작업	선택	본체 창에서 바로 결과를 확인하면 되므로 필요성이 낮다
클라이언트 대상 화면 공유, 기술 세미나 라이브 코딩	끄기	화면 구석의 픽셀 캐릭터로 청중 시선이 분산된다
깊은 집중이 필요한 딥 코딩 상황	끄기	시각적 움직임이 방해가 될 수 있다

지금 바로 해볼 수 있는 체크리스트

/pet 명령으로 기본 펫을 띄운 뒤, 에이전트에게 작업을 맡기고 /✅ 색 변화를 직접 확인해 본다.
Settings > Appearance > Pets에서 내장 8종을 둘러보고 마음에 드는 스킨을 고른다. 더 다양한 스킨은 codex-pets.net에서 npx codex-pets add <펫ID> 한 줄로 설치 가능하다.
나만의 캐릭터를 원한다면 /hatch로 AI가 생성하는 커스텀 펫을 만들어 본다(약 30분 소요).

가이드 시리즈 다른 글

Codex Mac App 시리즈의 다른 포스트들도 함께 읽어보자.
• Part 1: Mac App 완전 정복 가이드 — 빌드업·초기 세팅·승인 옵션
• Part 2: 다중 디바이스 연결 가이드 — 원격 제어 및 모바일 연동

최초 작성일: 2026년 5월 29일

실측 대상 릴리스 버전 정보: Codex Mac App (2026년 5월 빌드 기준), codex-pets.net (2026-05-27 DB 기준)

공식 기술 개발자 아카이브

Claude Opus 4.8 출시 - Dynamic Workflows, ultracode, Fast mode, 서브에이전트 1000개 등 정리(41일 만의 업데이트가 보내는 메시지)

갓대희 — Sat, 30 May 2026 14:45:41 +0900

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

Opus 4.7이 나온 지 41일 만에 Opus 4.8이 나왔다. TechCrunch는 "Anthropic치고는 유난히 빠른 업그레이드 주기"라고 했는데, 나는 버전 숫자보다 이 출시 속도 자체가 더 큰 메시지라고 본다. 자잘한 패치를 하나 더 얹은 게 아니다. Anthropic이 경쟁 압박 속에서 '작은 조직처럼 빠르게 내보내겠다'는 걸 행동으로 보여준 셈이다.

이번 업데이트에는 두 가지 축이 있다.

하나는 '더 정직한 모델'이라는 Anthropic의 주장이다. 모델이 모르는 건 모른다고 인정하고, 코드 결함을 슬쩍 넘기지 않게 설계했다는 얘기다.

다른 하나는 Dynamic Workflows와 ultracode — 단일 요청이 여러 서브에이전트로 분기되어, 사실상 소형 개발 조직처럼 병렬로 움직이는 구조다.

둘은 따로 노는 기능처럼 보이지만, 결국 같은 얘기를 한다. 모델이 일하는 방식 자체를 바꾸겠다는 것.

이 글은 2026년 5월 29일 기준으로 작성됐다. 공식 소스: Anthropic 공식 발표 · Claude Code 공식 문서

이 글의 핵심 6가지

41일 만의 출시 — 숫자가 아니라 Anthropic의 전략 신호
'더 정직한 모델': 코드 결함 미보고 확률 전작 대비 약 4배 감소 (공식 발표 수치)
Dynamic Workflows: 서브에이전트 동시 최대 16개 / 1회 실행 총 1,000개 상한
ultracode — 모델 effort 레벨이 아닌 Claude Code 설정, /effort 메뉴에서 접근
Fast mode: 2.5배 속도, 이전 Fast mode 대비 3배 저렴 (공식 발표)
Mythos-class 모델은 사이버보안 안전장치 이유로 'coming weeks' 보류 상태

출시 개요 — 41일이 보내는 메시지
'더 정직한 모델' — 자기 의심하는 AI의 실체
Dynamic Workflows — 작은 개발 조직처럼 병렬화
ultracode — Claude Code 설정과 effort 조절 패널
Fast mode 2.5배 속도 — 언제 쓸모 있는가
Claude Code 업데이트 3종 — Agent view · /goal · 보안 검토
Mythos 보류와 커뮤니티 반응
실제로 써보면 어떤가 — 4.7 대비 체감과 개발자 판단
결론 — 이 업데이트를 어떻게 받아들여야 할까

1. 출시 개요 — 41일이 보내는 메시지

Claude Opus 4.8은 2026년 5월 28일 공식 출시됐다.

Opus 4.7 출시일이 2026년 4월 16일이므로, TechCrunch는 "41일"로 표기했으며, 날짜 산술상 실제 간격은 42일이다.

어느 쪽이든 Anthropic으로서는 이례적으로 짧은 주기다.

가격은 Opus 4.7과 동일하다: 입력 $5/백만 토큰, 출력 $25/백만 토큰. 플랫폼은 Claude API(모델 ID: claude-opus-4-8), claude.ai Pro/Max/Team/Enterprise, Claude Code, Amazon Bedrock, Google Cloud Vertex AI, Microsoft Foundry에서 이용 가능하다.

GitHub Copilot에서도 2026-05-28 당일 가용 상태가 됐다.

항목	내용
출시일	2026-05-28
Opus 4.7 대비 간격	약 42일 (TechCrunch 보도: '41일')
표준 가격	입력 $5 / 출력 $25 (백만 토큰, 4.7과 동일)
Fast mode 성능·비용	2.5배 속도, 이전 Fast mode 대비 3배 저렴 (공식 발표, 절대 가격은 공식 페이지 확인)
모델 ID (API)	claude-opus-4-8
필요 버전 (Dynamic Workflows)	Claude Code v2.1.154 이상

개발자 입장에서 이 출시 주기가 중요한 건 그냥 "빠르다"는 게 아니다. Anthropic이 자기 로드맵보다 시장 압박에 더 민감하게 움직이기 시작했다는 신호에 가깝다.

Opus 4.7이 "냉랭한 반응(chilly reception)"을 받았다는 보도가 나온 직후 곧바로 4.8이 등장했다는 점도 이 해석을 뒷받침한다.

배경으로는 Google이 2025년 11월 Gemini 3와 함께 출시한 Antigravity 2.0의 경쟁 압박도 있다. — Claude Code와 정면 경쟁하는 에이전트 코딩 도구다.

41일이냐 42일이냐 같은 숫자에 자꾸 눈이 가는데, 정작 중요한 건 그게 아니었다. 작게 쪼개서 자주 내보내는 출시 리듬 자체가 핵심이다. 41일 만에 다음 버전을 낸다는 건, 학습부터 배포까지 파이프라인이 그만큼 짧게 돈다는 뜻이다.

2. '더 정직한 모델' — 자기 의심하는 AI의 실체

Anthropic의 공식 발표에서 가장 강조된 개선은 정직성(honesty)이다. 구체적으로 "Opus 4.8은 전작 대비 코드 결함을 미보고로 통과시킬 확률이 약 4배 낮다"고 밝혔다.

이 말은 이렇게 해석된다: 이전 모델은 코드에 버그가 있어도 그냥 제출했다. 4.8은 그 대신 "이 부분이 잘못됐을 수 있다"고 먼저 알린다. 에이전트 작업에서 모델이 자신의 출력 결함을 사용자가 잡을 때까지 방치하는 것이 얼마나 흔한 문제인지 생각해보면, 이 개선이 왜 먼저 강조됐는지 이해된다.

초기 테스터 평가

초기 테스터들은 에이전트 작업에서 Opus 4.8을 "더 신뢰할 수 있고 판단력이 더 예리하다"고 평가했다. 불확실성을 플래그하는 빈도가 높고, 근거 없는 주장을 할 가능성이 낮아졌다는 보고다.

Bridgewater Associates는 Opus 4.8이 "분석 과정의 입출력 문제를 미리 짚어주는 경향"이 다른 모델들이 놓치고 사용자에게 떠넘기던 부분을 처리한다고 평가했다. 다만 이것은 Bridgewater가 공개적으로 언급한 사용 평가이며, Anthropic의 공식 벤치마크 결과와 동일시해서는 안 된다.

벤치마크 수치 — 출처 구분 필수

SWE-Bench Pro 69.2% — 공식 발표 + 복수 매체 일치: Opus 4.8이 SWE-Bench Pro에서 69.2%를 기록했다. Opus 4.7(64.3%) 대비 약 5%p 향상. (출처: Anthropic 공식 발표, TestingCatalog)

USAMO 2026 96.7%: 여러 매체에서 인용.

PCWorld는 Opus 4.8을 "자신이 모르는 것에 대해 더 정직하게 말하고, 낮은 신뢰도를 갖고 있을 때 그것을 알린다"고 정리했다. 이 방향은 Anthropic이 지속적으로 강조해온 AI 정렬(alignment) 목표와 일치한다.

개발자 관점에서 이 개선은 두 가지를 의미한다. 첫째, 에이전트 루프에서 모델이 자신의 결함을 알리면 재실행 비용이 줄어든다. 둘째, "모델이 확신하는 척한다"는 불신을 줄일 수 있다. 물론 실제로 얼마나 체감되는지는 사람마다 다르다. HN에서는 "정직성에는 결국 진짜 지능이 필요한 거 아니냐"는 시큰둥한 반응도 있었다. 둘 다 일리가 있다.

내 경우엔 코드 자동화 파이프라인을 돌릴 때 "모델이 틀린 줄 모르고 통과시키는" 상황이 가장 골치 아팠다. 그 관점에서 보면 정직성 개선은 화려한 신기능보다 오히려 실무에서 먼저 와닿는 변화다. 처음 접한다면 벤치마크 숫자보다 "이 모델이 자기 실수를 먼저 말해주는가"를 직접 돌려보며 확인하는 편이 빠르다.

3. Dynamic Workflows — 작은 개발 조직처럼 병렬화

Dynamic Workflows는 Opus 4.8과 함께 출시된 Claude Code의 핵심 신기능이다.

Claude Code v2.1.154 이상이 필요하며, 모든 유료 플랜에서 이용 가능하다 — 단, 플랜별 기본 활성화 여부가 다르다.

작동 방식과 서브에이전트 상한은 얼마인가?

Q. Dynamic Workflows의 서브에이전트 상한은 얼마인가?

단일 요청이 내부적으로 여러 서브에이전트로 분기되어 실행되는 방식입니다. Claude가 스스로 "이 작업에 워크플로우가 필요하다"고 판단하면, 하나의 요청이 여러 워크플로우로 연쇄 실행됩니다: 코드를 이해하는 워크플로우 → 수정하는 워크플로우 → 검증하는 워크플로우.

공식 상한 (중요): 동시 최대 16개 서브에이전트 (CPU 코어 수 제한 환경에서는 더 적을 수 있음) / 1회 실행당 총 최대 1,000개 서브에이전트. 이 제한은 로컬 리소스 보호와 무한 루프 방지를 위해 설계됐다. (출처: Claude Code 공식 문서)

커뮤니티에서 "100개 이상 동시 실행"이라는 체감담이 나오지만, 이것은 개별 사용 사례에서의 총 에이전트 수를 가리키는 것으로 보인다. 공식 동시 실행 상한은 16개이며, 이 사실은 공식 문서에서 명확히 확인된다.

플랜별 기본 활성화 여부

플랜	기본 상태	활성화 방법
Max / Team	기본 활성화	자동 적용
Enterprise	기본 비활성화	관리자가 설정에서 수동 활성화
Pro	기본 비활성화	`/config`에서 Dynamic workflows 행 켜기

ex) Max의 경우 기본 활성화

실제 사용 사례 — Bun 마이그레이션

가장 강렬한 사례로 인용된 것은 Jarred Sumner(Bun 개발자)가 Dynamic Workflows를 활용해 Bun을 Zig에서 Rust로 포팅한 작업이다: 약 75만 줄, 11일, 기존 테스트 스위트 통과율 99.8%.

"75만 줄을 11일 만에"라는 숫자를 곧이곧대로 읽기 전에 짚을 게 하나 있다. 이건 완전히 자동화 사례가 아니라 Sumner가 Claude와 같이 붙어서 한 작업이다. 그래도 대규모 코드 마이그레이션에서 이 도구가 쓸 만하다는 걸 보여주는 사례로는 충분하다.

Klarna의 Senior Engineering Manager Alessio Vallero는 "대규모 코드베이스에서 발견과 리뷰 작업에 특히 유용하다"고 평가했다. 개발자 입장에서는 리뷰 전 준비 작업 — 어떤 파일이 영향을 받는지, 어떤 패턴이 반복되는지 — 에서 의미 있는 시간 절약을 기대할 수 있다.

처음 Dynamic Workflows를 써보고 싶다면 /deep-research 명령이 가장 빠른 진입점이다. Claude Code에 내장된 번들 워크플로우로, 여러 소스에 걸쳐 질문을 탐색하는 작업을 수행한다.

직접 써보기 전에 내가 가장 궁금했던 건 "서브에이전트가 많아질수록 비용도 그만큼 늘어나는가"였다. 동시 16개·총 1,000개라는 상한을 보면 무한정 늘어나진 않지만, 한 요청이 수백 개 서브에이전트로 분기되면 토큰 소비가 단일 세션과는 다른 규모가 된다. 처음이라면 작은 작업부터 걸어보고 소비량 패턴을 눈으로 확인한 뒤 규모를 키우는 편이 안전하다.

4. ultracode — Claude Code 설정과 effort 조절 패널

Q. ultracode는 모델 effort 레벨인가?

아닙니다. ultracode는 모델의 effort 레벨이 아니라 Claude Code의 고급 세션 설정입니다. /effort 메뉴에서 활성화하면 모델에 xhigh 추론 강도를 전달하는 동시에, Claude가 복잡한 작업을 처리하기 위해 동적 워크플로우(Dynamic Workflows)를 자동으로 구성하고 관리합니다. 해당 설정은 현재 세션에 한해서만 유효합니다.

핵심 요약: ultracode는 Claude Code 설정이지, 모델의 effort 레벨이 아닙니다. 이 두 개념을 명확히 구분하는 것이 본 기능 이해의 핵심입니다.

공식 문서는 이를 명확히 정의한다:

"The /effort menu also offers ultracode. Ultracode is a Claude Code setting rather than a model effort level: it sends xhigh to the model and additionally has Claude orchestrate dynamic workflows for substantive tasks. It applies to the current session only." (출처: Claude Code 공식 모델 설정 문서)

ex) 번역본

/effort 메뉴에서 ultracode를 선택할 수도 있습니다.
ultracode는 단순한 ~~모델 추론 수준 설정~~이 아니라 Claude Code의 고급 작업 모드입니다.

활성화하면 모델에 xhigh 추론 강도가 적용되며, 동시에 Claude가 복잡한 작업을 처리하기 위해 동적 워크플로우(Dynamic Workflows)를 자동으로 구성하고 관리합니다.
해당 설정은 현재 세션에 한해서만 유효합니다.

풀어보면 이렇다.

ultracode를 켜면 Claude Code가 모델에 xhigh effort를 전달하고,

거기에 더해 좀 묵직한 작업이다 싶으면 Dynamic Workflows를 알아서 엮어 돌린다.

ex) workflow가 자동으로 동작 되는 모습

- 진행 상황 확인

- workflows로 토큰이 녹는 모습 / 이로 인해 몇몇 세션은 동작했지만, complete 이라고 나온 세션들은 사실 리밋 제한이 걸려 종료된 세션들이 대부분 이었다. 토큰이 여유로울때 하자.

ex) deep-research

- 이전 섹션에서 말했듯이 /deep-research 명령이 가장 쉽게 Dynamic Workflows 를 사용해볼수있는 방법 이다.

- /deep-research 현재 카카오톡 대화 분석 서비스의 개선사항을 deep research 해줘.

- 총 106개의 에이전트를 활용하여 조사 후 결과를 알려준다.

두 가지가 같이 움직이는 거지, ultracode가 곧 xhigh effort 레벨인 건 아니다.

설정	reasoning	Dynamic Workflow 자동 실행	적합 상황
`effort: high` (기본)	high	없음	일반 작업, 단일 파일 수정
`effort: xhigh`	최대	없음	복잡한 단일 작업, 깊은 추론 필요
ultracode (CC 설정)	xhigh 전달	Claude가 판단해 자동 실행	대규모 마이그레이션, 멀티 파일 리팩터링

effort 레벨 체계

모델	지원 effort 레벨	기본값
Opus 4.8, Opus 4.7	low / medium / high / xhigh / max	Opus 4.8: high, Opus 4.7: xhigh
Opus 4.6, Sonnet 4.6	low / medium / high / max (xhigh 미지원)	high

눈에 띄는 건 Opus 4.8의 기본 effort가 4.7의 ~~xhigh~~가 아니라 high라는 점이다.

4.7 때 기본이던 xhigh에서 한 단계 내려왔다.

같은 effort에서도 4.8이 더 효율적으로 돈다는 뜻으로 보면 될 것 같다.

ultracode 활성화 방법

ultracode는 /effort 메뉴에서 접근하거나,

ex)

--settings 또는 Agent SDK control request를 통해 "ultracode": true로 전달하면 활성화된다.

중요한 점은 ultracode가 effortLevel 설정, --effort 플래그, CLAUDE_CODE_EFFORT_LEVEL 환경변수에 포함되지 않는다는 것이다.

이것들은 별개의 메커니즘이다.

ultracode는 세션 전용이다: 현재 세션에만 적용되며, 설정 파일이나 --effort 플래그로 저장·유지되지 않는다.

매번 필요할 때마다 켜야 한다는 의미이기도 하고, 반대로 세션이 끝나면 자동으로 해제된다는 의미이기도 하다.

언제 쓰고 언제 쓰지 않는가

상황	권장
대규모 코드 마이그레이션, 리팩터링	ultracode ON — 병렬 워크플로우 효과 최대
탐색적 질문, 단일 파일 수정	ultracode OFF — 추가 부담 불필요
비용/토큰 소비 제한이 중요한 환경	ultracode OFF — xhigh effort + 다중 서브에이전트로 비용 증가
검증 루프가 중요한 대형 PR	ultracode ON — 이해→수정→검증 자동 연쇄

내가 켜고 끄는 기준은 단순하다.

"이 작업을 사람 여럿이 나눠서 한다면 도움이 될까"를 먼저 떠올린다. 그렇다면 ultracode를 켜고,

혼자 빠르게 끝낼 단순 작업이라면 끈다.

세션 전용이라 매번 켜야 하는 게 번거롭게 느껴질 수 있는데, 막상 써보면 작업 시작 시점에 한 번 판단하고 넘어가는 흐름이 오히려 자연스럽다.

5. Fast mode 2.5배 속도 — 언제 쓸모 있는가

Opus 4.8의 Fast mode는 표준 모드 대비 2.5배 속도로 실행되며, 이전 Fast mode 대비 3배 저렴하다.

(출처: Anthropic 공식 발표) 공식 발표는 "3배 저렴"이라는 표현을 쓴다.

Fast mode 달러 가격 — 직접 확인 권장: 일부 매체에서 $10/백만 입력 · $50/백만 출력(표준가 2배)으로 표기했으나, 이 수치는 3차 매체에서 확인된 것이며 공식 anthropic.com 발표에서는 "이전 Fast mode 대비 3배 저렴"이라는 상대적 표현만 사용됐다.
정확한 달러 가격은 공식 가격 페이지에서 확인하는 것을 권장한다.

Fast mode가 의미 있는 상황은 구체적이다: 응답 대기 시간이 병목이 되는 경우, 대화형 코딩 보조, 고빈도 API 호출 파이프라인. Opus 급 모델의 응답 속도가 체감상 느리다고 느낀 개발자에게 실용적인 선택지다.

반대로 깊은 추론이 필요하거나, 단계가 복잡하거나, 속도보다 정확도가 중요한 프로덕션 파이프라인이라면 표준 모드가 낫다. 결국 작업 성격을 보고 고르면 된다.

개인적으로는 코드 리뷰 코멘트 정리나 커밋 메시지 초안처럼 "정답이 하나로 좁혀지는 가벼운 작업"에 Fast mode가 잘 맞는다고 본다.

반대로 설계 판단이 섞인 작업에 속도를 우선하면, 빨리 받은 답을 다시 검토하느라 오히려 시간을 더 쓰게 되는 경우가 있다.

언제 Fast mode가 유리한가 — 한눈에

응답 지연이 작업 흐름을 끊는 대화형 코딩 보조
커밋 메시지·리뷰 코멘트 같은 정답이 좁은 경량 작업
고빈도 API 호출로 누적 지연이 비용이 되는 파이프라인
반대로 설계 판단·복잡한 다단계 추론은 표준 모드 권장

ex) 상황별 설정 예시

6. Claude Code 업데이트 3종 — Agent view · /goal · 보안 검토

Opus 4.8 출시와 맞물려 Claude Code에 세 가지 의미 있는 업데이트가 왔다.

( 이미 출시된 기능이지만 4.8 opus와의 결합시 더 최적화 되지 않을까 하여 작성해보았다.)

이 중 Agent view와 /goal은 2026-05-11(v2.1.139) 기준이며, /code-review --fix는 2026-05-27(v2.1.152) 기준이다.

6-1. Agent view — 모든 세션을 단일 목록으로

Agent view는 실행 중인 세션, 사용자 입력 대기 중인 세션, 완료된 세션 전체를 하나의 목록으로 통합 관리한다. claude agents 명령으로 실행하며, Research Preview 상태다.

여러 Claude Code 세션을 동시에 돌리는 환경에서 이 기능의 가치가 두드러진다. 어떤 세션이 멈춰 있는지, 어디서 사용자 입력을 기다리는지를 탭 전환 없이 한 화면에서 파악할 수 있다. Dynamic Workflows와 함께 쓸 때 특히 유용하다.

ex) claude agents

- claude agents로 세션을 시작하면 아무런 동작이 없을때에는 다음과 같이 0개의 agents 상태 알림을 확인 가능하다.

- claude agents로 시작한 세션에서 prompt를 날리게 되면 다음과 같이 n개의 작업을 별도의 세션에서 동작하게 시킬 수 있으며, 화살표로 움직여 상세 작업 내용을 살펴볼수 있다.

- 화살표로 이동한 후 Enter 입력

- 해당 기존의 클로드 코드 세션처럼 작업 및 확인이 가능하다.

6-2. /goal — 완료 조건 설정 후 자율 작업

/goal 명령은 완료 조건을 설정하면 Claude가 해당 조건을 충족할 때까지 여러 턴에 걸쳐 자율적으로 작업을 지속하는 기능이다.

대화형, -p(비대화형), Remote Control 모두에서 동작하며, 진행 중 경과 시간·턴 수·토큰 소비를 오버레이 패널로 표시한다.

실전에서 가장 유용한 패턴은 장시간 작업을 야간에 세션을 열어두고 다음 날 아침 결과를 확인하는 것이다. 개인적으로는 복잡한 리팩터링을 걸어두고 다른 작업을 하는 사이 Claude가 처리하게 하는 방식으로 쓸 수 있다.

ex) /goal 목표 입력

ex) 코덱스도 동일한데 권한때문에 중간에 동작하지 않은 상태가 있지만, 정말 목표를 달성할때까지 목표가 해제되지 않는 모습

6-3. /code-review --fix — 리뷰 결과 자동 적용

/code-review --fix는 코드 리뷰 결과(재사용·단순화·효율성 제안)를 작업 트리에 자동으로 적용한다.

/simplify 명령도 이제 내부적으로 /code-review --fix를 호출한다.

ex) code-review

ex) simplify

기능	버전 (날짜)	핵심 역할
Agent view	v2.1.139 (2026-05-11)	전체 세션 통합 목록 — `claude agents`
/goal	v2.1.139 (2026-05-11)	완료 조건 기반 자율 다턴 작업
/code-review --fix	v2.1.152 (2026-05-27)	리뷰 결과 작업 트리에 자동 적용

7. Mythos 보류와 커뮤니티 반응

Q. Mythos 모델은 언제 출시되는가?

Anthropic은 공식 발표에서 'coming weeks'(향후 몇 주 내)라고만 밝혔으며, 구체적인 출시 일정은 이 글 작성 시점(2026-05-29) 기준 아직 공개되지 않았습니다. 이번 발표에서 주목할 또 다른 부분은 이 Mythos-class 모델의 보류 결정입니다.

Anthropic은 공식 발표에서 이렇게 밝혔다:

"Models of this capability level require stronger cyber safeguards...We're making swift progress on developing these safeguards and expect to be able to bring Mythos-class models to all our customers in the coming weeks."

번역 : 이 수준의 역량을 가진 모델을 공개하기 위해서는 더욱 강화된 사이버 보안 보호 체계가 필요합니다. 현재 우리는 이러한 안전장치 구축에 빠르게 진전을 이루고 있으며, 향후 몇 주 내로 Mythos 클래스 모델을 모든 고객이 사용할 수 있도록 제공할 계획입니다.

공식적으로 구체적인 위협 모델, 충족해야 할 통제 항목, 해제 조건을 공개하지 않았다.

Axios 보도에 따르면 Mythos는 현재 "소수의 선정된 파트너에게만 공개" 상태다.

커뮤니티 반응 — 빠른 출시 주기에 대한 온도차

HN 커뮤니티에서 사용자 NiloCK는 "4.5와 비교했을 때 어떤 능력 개선이 있는지 명확히 파악하기 어렵다"는 반응을 남겼다. (출처: HN 토론) 4.5 → 4.6 → 4.7 → 4.8로 이어지는 버전 연속 출시 패턴에 대한 피로감이 반영된 반응이다.

MacRumors 포럼에서는 "이 마이너 모델 업데이트를 계속 따라가는 사람이 실제로 있냐"는 피로감 섞인 반응도 있었다. (출처: MacRumors 포럼) 같은 포럼에선 '정직성' 주장을 두고 "정직성에는 실제 지능이 필요하다"는 시큰둥한 반응도 나왔다. 공식 메시지와 실사용자 체감 사이의 간극이 그대로 드러나는 대목이다.

반면 HN의 또 다른 사용자 onlyrealcuzzo는 다음 세대 프론티어 모델이 마지막일 수 있다는 관점을 제시했다 — 소형 오픈소스 모델들이 2~3년 내 현재 SOTA를 따라잡을 수 있다는 주장이다. (출처: HN 토론) 다수 upvote를 받은 댓글이었지만, 이것은 커뮤니티 추측이며 공식 분석이 아니다.

반응을 정리하면 이렇다. 빠른 출시 주기에 지쳤다는 쪽이 있고, Dynamic Workflows나 ultracode 같은 실제 도구 개선을 반기는 쪽이 있다. 재미있는 건 같은 사실을 두고 입장이 갈린다는 거다. 어느 쪽 목소리가 큰지 따지기보다, 내 작업에 뭐가 와닿는지를 기준으로 보면 된다.

7-2. 하루 뒤 업데이트 — 출시 이틀째 커뮤니티 반응 (2026-05-30 추가)

이 글의 본문은 출시 다음 날인 2026-05-29에 작성은 해두었었다.

그런데 하루 사이 해외·국내 반응이 더 쌓여서, 출시 이틀째(2026-05-30) 분위기를 따로 덧붙이게 되었다.

이틀째 분위기는 한마디로 "확실히 똑똑해졌는데, 알아서 챙기는 센스는 아직"이라는 평이 보인다.

가장 눈에 띈 건 "GPT로 갈아탔다가 다시 돌아왔다"는 반응이다.

뉴스레터 every.to의 Vibe Check는 자기 팀의 클로드 골수 사용자들이 OpenAI Codex 앱 때문에 GPT로 손이 갔었는데, Opus 4.8을 보고 "다시 달려 돌아왔다(running back)"고 적었다. (출처: every.to — Opus 4.8 Vibe Check)

다만 같은 글은 "모델은 (그걸 감싼) 앱보다 강하다"며, 클로드 앱 UI의 파편화는 여전한 약점이라고 짚었다.

수치로도 비슷한 그림이다. every.to가 자체 운영하는 Senior Engineer 벤치마크에서 Opus 4.8은 xhigh effort 기준 63점, GPT-5.5는 62점, Opus 4.7은 33.5점이었다. 다만 이건 every.to의 주관적 사내 평가라 §2의 공식 SWE-Bench Pro(69.2%)와는 척도가 달라 직접 비교할 수 없다. 63 대 62는 1점 차로 GPT-5.5와 사실상 동급이고, 의미가 있는 건 오히려 4.7(33.5)에서 4.8(63)로의 큰 도약이다. "멍청한 느낌이 사라졌다"는 체감과 맞닿는 지점이다.

냉정한 평가도 있다.

개발자 Simon Willison은 Anthropic이 스스로 4.8을 "점진적이지만 체감되는 개선(a modest but tangible improvement)"이라고 표현한 대목을 짚으며, "AI 연구소가 신모델을 솔직하게 '소폭 개선'이라고 말하는 게 오히려 신선하다"고 했다. (출처: Simon Willison — Claude Opus 4.8)

혁신이라기보다 "이제 쓸 만해진 점진적 업데이트"라는 시각이다.

출처	출시 이틀째 주요 반응
every.to (해외)	"GPT 갔다가 다시 클로드로" · 자체 벤치 63 vs GPT-5.5 62 · 앱 UI는 아쉬움
Simon Willison (해외)	"점진적이지만 솔직한 개선" — 과대포장 없는 점이 신선
r/ClaudeAI (해외)	"더 정직하다더니 오히려 아첨이 늘었다" — 커뮤니티 관찰, 공식 미확인
요즘IT (국내)	"클로드가 빼앗긴 주도권을 되찾을까" — 경쟁 구도 관점
AI타임스 (국내)	"근거 없는 과신을 잡았다" — 정직성 개선에 무게

그런데 결이 다른 신호도 하루 만에 나왔다.

먼저 짚어둘 게 있다. 이 글이 말한 '정직성'은 사실 두 축이다.

하나는 자기가 쓴 코드의 결함을 숨기지 않는 사실성 차원(공식 발표가 말한 4배 개선)이고,

다른 하나는 사용자 의견에 얼마나 고분고분한가라는 대화 톤 차원이다.

둘은 별개 축이다.

그런데 일부 사용자들은 4.8이 "당신 말이 맞다(you're right to…)"는 동의로 응답을 열고 교정을 아첨으로 감싸는 경향이 보이며,

동일 프롬프트에서 4.7보다 더 두드러졌다고 보고했다.

코드 정직성은 좋아졌다는데 대화에선 더 아첨한다니..... ㅎㅎㅎ

'아첨' 보고는 공식 확인된 내용이 아니다: 위 sycophancy 보고는 커뮤니티 사용자들의 체감 관찰이며, Anthropic 공식 벤치마크로 검증된 결과가 아니다. "동일 프롬프트 비교"라지만 표본·방법이 공개되지 않아 [미확인]으로 한번더 표기한다.

이 반응들을 한데 모으면, 커뮤니티가 4.8을 받아들이는 정서는 "FM대로 일하는 신입 부하직원이 생긴 느낌"에 가깝다.

시키는 일은 전보다 정직하게, 빠뜨리는 것 없이 해낸다.

그리고 위 [미확인] 아첨 관찰이 사실이라면, 시키지 않은 걸 알아서 챙기거나 내 말에 날을 세워 반박하는 눈치는 아직 모자란 셈이다.

every.to 팀처럼 GPT-5.5로 손이 갔다가 4.8로 돌아온 경우라면, "얼마나 똑똑한가"보다 이 "정직하되 고분고분한" 성격이 내 작업 방식과 맞는지를 먼저 보게 될 것 같다.

현재 나도 주력은 Codex였는데, 고민이다. 한동안 Opus4.8의 성능과, 토큰이 얼마나 빠르게 녹아 버리냐에 따라 판단하게 될 것 같다.

( 이미 열심히 사용하고 벌써 리뷰한 사례를 미리 다음 섹션에 하나 남겨 두도록 하겠다.)

8. 실제로 써보면 어떤가 — 4.7 대비 체감과 개발자 판단

Opus 4.7이 개발자 커뮤니티에서 받은 반응은 냉랭했다. TechCrunch는 "chilly reception"이라고 표현했고, 주된 불만은 주석 과다 작성과 도구 호출 일관성 문제였다. (출처: TechCrunch)

Devin CEO는 Opus 4.8이 "4.7에서 봤던 주석 과다 작성과 도구 호출 일관성 문제를 수정했다"고 공개 발언했다.

(출처: DevToolPicks — Devin CEO 발언 인용) 이것은 기업 제품 평가이다.

Cursor CEO는 Opus 4.8이 "모든 effort 레벨에서 이전 Opus 모델들을 능가한다"고 평가했다. (출처: DevToolPicks)

4.7에서 4.8로 전환할 때 체감 차이

관점	4.7 이슈	4.8 개선 (기업 평가 기반)
코드 작성	주석 과다, 불필요한 설명	주석 밀도 감소, 간결해짐
도구 호출	일관성 부족	일관성 개선
불확실성 처리	침묵으로 통과	선제적 플래그
에이전트 신뢰도	낮음	테스터 평가 기준 향상

위 표는 기업 테스터와 초기 사용자 평가를 종합한 것이며, 공식 벤치마크 결과가 아니다.

HN에서 일부 사용자는 4.5 대비 개선이 명확하지 않다는 반응을 보였다.

직접 비교해보기 전까지 체감 차이는 개인 환경과 사용 목적에 따라 다를 수 있다.

Max 또는 Pro 플랜을 사용 중이라면 Dynamic Workflows와 ultracode를 함께 테스트하는 것이 4.8의 개선을 가장 직접적으로 확인하는 방법이다.

9. 결론 — 이 업데이트를 어떻게 받아들여야 할까

공식 가이드와 현실의 차이: Anthropic 공식 문서는 ultracode와 Dynamic Workflows의 기술적 상한과 켜는 방법은 깔끔하게 설명한다. 그런데 실제 현장에서 어떤 작업에 효과가 크고 어떤 경우엔 괜히 부담만 늘어나는지는, 아직 커뮤니티에 쌓인 데이터가 부족하다. 이 기능들이 아직 Research Preview라는 점을 생각하면, 운영 핵심 환경에 곧장 넣기보다 덜 중요한 작업에서 먼저 굴려보는 게 안전하다.

한 줄로 정리하면 이렇다. Anthropic은 이번 출시 주기와 기능 구성으로 "작은 조직처럼 병렬로 일하고, 모델이 실패를 정직하게 말하는" 방향을 골랐다. 이게 일종의 선언이라면, 41일 만의 출시가 그 첫 실행인 셈이다.

내가 이번 업데이트에서 가장 무게를 두는 건 화려한 벤치마크 숫자가 아니라 ultracode와 Dynamic Workflows가 바꾸는 작업 방식이다. 모델이 얼마나 똑똑해졌는지보다, 내 손에서 일이 어떻게 굴러가는지가 더 빨리 체감되기 때문이다. 처음이라면 결정 매트릭스에서 자신의 플랜에 해당하는 줄부터 따라가며 한 가지씩 켜보는 편이 낫다.

업데이트 수용 결정 매트릭스

상황	권장 액션
Max/Team 플랜 + 대규모 코드 마이그레이션	Dynamic Workflows + ultracode 즉시 테스트
Pro 플랜 + 일반 개발	`/config`에서 Dynamic Workflows 수동 활성화 후 테스트
Enterprise + 보안 정책 강한 환경	관리자 확인 후 활성화 여부 결정
API 비용 민감 환경	Fast mode 우선 검토, ultracode는 신중하게
Opus 4.7에서 주석 과다/도구 호출 불만이 있었던 경우	4.8 전환 적극 권장

독자 적용 체크리스트 — 오늘 바로 해볼 것

Claude Code 버전 확인: claude --version으로 v2.1.154 이상인지 확인한다. 미달이면 업데이트 후 Dynamic Workflows 사용 가능.
Max/Team 플랜이라면 /deep-research 명령으로 Dynamic Workflows 첫 체험 — 어떻게 서브에이전트가 분기되는지 직접 확인한다.
ultracode가 필요한 작업인지 판단: 대규모 리팩터링·마이그레이션이라면 /effort 메뉴에서 ultracode ON을 테스트한다. 단순 질문·단일 파일 수정은 ultracode 없이도 충분하다.
Pro 플랜이라면 /config에서 Dynamic Workflows 행을 찾아 직접 켜본다. 기본 비활성화 상태임을 잊지 않는다.
주간 한도 증가(~2026-07-13) 기간을 활용해 ultracode + Dynamic Workflows 조합을 실제 작업에 테스트할 기회로 삼는다. (@ClaudeDevs 발표 기준 — 공식 출처 미확인, 적용 전 claude.ai에서 현재 한도 먼저 확인 권장)

참고자료

작성일: 2026-05-29 · 최종 수정: 2026-05-30 (§7-2 출시 이틀째 반응 추가)

분석 대상: Claude Opus 4.8 (2026-05-28 출시), Claude Code v2.1.154+

이 글은 2026년 5월 29일 기준으로 작성됐다. 가격·플랜 정보·기능 상태는 이후 변경될 수 있다. 최신 내용은 공식 Opus 페이지에서 확인하는 것을 권장한다.

Gemini in Chrome 사용방법 - Gemini in Chrome vs 확장 프로그램 : 탭 전환 없이 멀티탭 교차 분석

갓대희 — Wed, 27 May 2026 18:30:03 +0900

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

API 문서 보다가 탭 여섯 개 열어놓고, 결국 별도 창에서 AI에 "이거 요약해줘"라고 붙여넣기 한 경험이 한 번쯤은 있을 것이다. Gemini in Chrome은 그 탭 전환 과정을 브라우저 안에서 끝내려는 시도다.

2026년 4월 20일, Google이 Gemini in Chrome을 한국을 포함한 아시아·태평양 7개국에 공식 출시했다. Chrome 탭바에 AI Side Panel이 내장돼 지금 보는 페이지를 바로 분석하고, 여러 탭을 한 번에 비교하며, Google 서비스와 연동해 탭 전환 없이 작업을 처리할 수 있다.

이 글은 개발자가 바로 따라 할 수 있는 튜토리얼 4개를 중심으로 구성된다. Side Panel 요약, 멀티탭 교차 분석, Google 서비스 연동, 인라인 이미지 편집을 단계별로 실습하고, 아키텍처 추정, 보안(prompt injection), 요금제, 대안 비교, 트러블슈팅까지 다룬다.

Gemini in Chrome이란 — 한국 출시 배경과 핵심 가치
시작하기 — 온보딩 가이드
튜토리얼 1 — Side Panel 요약 실습
튜토리얼 2 — 멀티탭 교차 분석 실습
튜토리얼 3 — Google 서비스 연동 실습
튜토리얼 4 — 인라인 이미지 편집 실습 (Nano Banana 2)
개발자 심화 활용 케이스
공개 정보 기반 아키텍처 추정
보안 고려사항 — Prompt Injection 방어
요금제 및 제한사항
대안 비교
트러블슈팅 Q&A + 결론

1. Gemini in Chrome이란 — 한국 출시 배경과 핵심 가치

Gemini in Chrome은 Google이 Chrome 브라우저 자체에 AI를 내장하는 방향으로 전환하면서 나온 서비스다.

2026년 1월 미국 출시 이후 3월에 인도·캐나다·뉴질랜드로 확장했고, 4월 아시아·태평양 7개국 동시 배포로 한국에도 공식 출시됐다.

브라우저 익스텐션이 아닌 Chrome 내장 방식이라는 점이 이전 AI 브라우저 도구들과의 핵심 차이다.

기반 모델은 Gemini 3.1이다. 1월 초기 출시 시 'Gemini 3' 기반으로 시작했고, 3월 인도·캐나다·뉴질랜드 확장 시 'Gemini 3.1'로 업그레이드됐다. 한국 배포 시 동일하게 Gemini 3.1이 적용됐을 가능성이 높지만, 공식 문서에서 한국 배포 시점의 모델 버전을 명시적으로 확인하지 못했으므로 단정하기 어렵다.

2. 시작하기 — 온보딩 가이드

사용 조건

항목	조건
연령	18세 이상
국가/지역	한국 포함 지원 국가 *
기기	Chromebook Plus, Mac, Windows 컴퓨터
브라우저	Chrome 최신 버전
계정	Google 계정으로 Chrome 로그인 (시크릿 모드 제외, 직장·학교 계정은 관리자 허용 필요)
언어	지원 언어로 기기 또는 Chrome 언어 설정 (한국어 포함)

Chrome을 최신 버전으로 유지하는 것은 필수 조건이지만 충분 조건은 아니다.

공식 문서는 Gemini in Chrome이 사용자에게 순차 배포되므로, 지원 지역이어도 아직 계정에 표시되지 않을 수 있다고 안내한다.

플랫폼별 시작 방법

데스크톱 (Mac / Windows / Chromebook Plus)

Mac, Windows, Chromebook Plus 중 하나인지 확인한다.
Chrome 최신 버전으로 업데이트한다 (Chrome 메뉴 → 도움말 → Chrome 정보).
Google 계정으로 Chrome에 로그인한다. 시크릿 모드에서는 사용할 수 없고, 직장·학교 계정은 관리자가 Gemini in Chrome을 허용해야 한다.
기기 또는 Chrome 언어가 지원 언어로 설정되어 있는지 확인한다. 한국어는 공식 지원 언어에 포함된다.
브라우저 우측 상단 Gemini 버튼을 클릭해 Side Panel을 열고, 최초 사용 시 화면 안내에 따라 opt-in 한다.
버튼이 보이지 않으면 Chrome 설정 → AI innovations → Gemini in Chrome에서 "Show Gemini at the top of the browser"가 켜져 있는지 확인한다. 이 메뉴 자체가 없다면 계정 배포, 지역, 언어, 관리자 정책 조건을 먼저 확인한다.

ex) 업에디트 완료 및 활성화된 상태는 우측 상단에 보면 직관적으로 확인 가능하다.

- 단축키도 알려 준다. (나의 경우 맥북이어 command + G)

iOS

iOS용 Chrome 앱을 최신 버전으로 업데이트한다.
Google 계정으로 로그인한다.
주소창(omnibox) 영역을 통해 Gemini에 접근한다.

Android

Android용 Chrome 앱을 최신 버전으로 업데이트한다.
[2026-05-27 수정] 2026년 4월 APAC 출시에는 Android Chrome 전용 Gemini Side Panel이 포함되지 않았다.
전원 버튼 길게 누르기로 호출되는 Gemini는 시스템 레벨 Gemini(구 Google Assistant 대체)이며, Chrome 앱 내 Side Panel과는 별개 기능이다.
Chrome 전용 Android 통합은 2026년 6월 말 미국을 시작으로 출시 예정(Android 12+, RAM 4GB+ 필요)이며 APAC 일정은 미발표.
Google 공식 블로그에 따르면 이번 APAC 출시에서 일본은 iOS 미지원(데스크톱만), 나머지 6개국(한국 포함)은 데스크톱·iOS 모두 지원된다. 안드로이드는 이번 출시에서 어느 국가도 해당되지 않았다.

3. 튜토리얼 1 — Side Panel 요약 실습

Chrome 공식 지원 문서에 따르면 Gemini in Chrome은 현재 탭의 내용을 분석해 맥락 기반 응답을 제공한다.

긴 기술 문서를 읽을 때 가장 빠르게 가치를 확인할 수 있는 기능이다.

ex) 사용 예시1

ex) 사용 예시2

ex) 사용 예시3

단계별 실습

Chrome에서 분석할 페이지를 연다 (예: FastAPI 공식 문서, npm 패키지 README, 기술 블로그 글).
우측 상단 Gemini 버튼을 클릭해 Side Panel을 연다.
Side Panel 입력창에 요청을 입력한다.
- "이 페이지의 핵심 내용을 3줄로 요약해 줘"
- "이 문서에서 인증 관련 내용만 찾아줘"
- "이 README의 설치 방법과 주의사항을 정리해 줘"
Gemini가 현재 탭 내용을 분석해 응답을 반환한다.
후속 질문을 이어서 입력할 수 있고, 대화 컨텍스트가 유지된다.

ex) 이 페이지의 핵심 내용을 3줄로 요약해 줘 ( 이미 해당 페이지에 대한 어느정도 Context를 파악하고 질문을 추천 하고 있는 모습)

ex) 모델 선택이 현재 다음과 같이 가능하다.

- Case1. Gemini 1만원대 저가 모델인 경우

(고급 모델로 업그레이드 가 나오긴 하지만, 현재 Pro모드랑 딱히 모델 선택에 있어 차이점은 없어 보인다.)

- Case2. Gemini 3만원 Pro 모델인 경우

- 응답 결과

이런 상황에서 바로 써볼 수 있다

Stripe, AWS SDK처럼 문서가 방대한 경우: "이 API 인증 방식과 rate limit 요약해 줘"로 바로 핵심만 뽑는다
오픈소스 라이브러리 README: "이 라이브러리가 해결하는 문제와 설치 요건 정리해 줘"
arXiv 논문: Abstract와 Conclusion 빠르게 추출
Stack Overflow 긴 스레드: 채택된 해결책과 주요 주의사항만 추출

4. 튜토리얼 2 — 멀티탭 교차 분석 실습

Chrome 공식 지원 문서에 따르면 데스크톱 환경에서 최대 10개 탭을 Gemini와 공유해 교차 분석을 요청할 수 있다. 여러 탭을 오가며 직접 비교하던 작업을 Side Panel 하나로 통합한다.

ex) 사용 예시1

단계별 실습

비교·분석할 페이지를 여러 탭으로 연다.
- 예 A: React 18, Vue 4 최신 버전의 공식 changelog 탭 2개
- 예 B: 같은 기능을 구현한 두 npm 패키지의 README 탭 2개
- 예 C: 검토 중인 GitHub PR 탭 2~3개
Gemini 버튼을 클릭해 Side Panel을 연다.
"현재 열린 탭들을 분석해 줘"라고 요청하거나, 구체적인 질문을 입력한다.
- "이 두 라이브러리의 bundle size, license, 마지막 업데이트를 비교해 줘"
- "세 탭의 PR에서 공통으로 변경된 파일 패턴을 찾아줘"
Gemini가 공유된 탭들의 내용을 교차 분석해 통합 응답을 반환한다.
결과를 표 형태로 정리해 달라고 후속 요청할 수 있다.

ex) 탭들이 열려있는 상황에서 Gemini 버튼을 클릭하여 사이드 패널 오픈, + 버튼을 클릭하여 을 추가 해 주자. 탭2개가 선택되었다.

- 이 두 라이브러리의 bundle size, license, 마지막 업데이트를 비교해 줘

- 결과

직접 쓸 수 있는 케이스

axios vs ky처럼 유사한 라이브러리 선택 상황: API 방식·번들 크기·유지보수 상태를 탭 두 개 열고 한 번에 비교
같은 기능 구현한 PR 2~3개: "변경 범위와 테스트 커버리지 차이 요약해 줘"로 리뷰 준비 시간 단축
Stripe vs Braintree 같은 API 선택 상황: 결제 실패 처리 흐름을 나란히 놓고 비교
MDN 탭 + 관련 SO 스레드 탭: 브라우저 호환성 이슈와 실무 해결책을 같이 뽑아달라고 요청

탭 공유 상한이 10개라는 점은 Chrome 공식 지원 문서에서 확인된 수치다.

10개를 초과하면 Gemini에 공유되지 않으므로, 비교 대상을 10개 이내로 좁혀 요청하는 것이 효과적이다.

5. 튜토리얼 3 — Google 서비스 연동 실습

Google 공식 블로그(2026-04-20)에 따르면 Gemini in Chrome은 Gmail·Google 지도·Google 캘린더·YouTube·Google Shopping·Google Flights와 깊게 통합되어 있다.

사용 중인 페이지를 이탈하지 않고 일정 추가, 이메일 초안 작성, 장소 확인, YouTube 영상 질의응답을 처리할 수 있다.

Google Shopping과 Flights 연동은 Google 공식 블로그(2026-01) 이후 공식 확인된 Connected Apps다.

사용 예시1)

시나리오 A: YouTube 기술 세션 중 질의응답

YouTube에서 기술 컨퍼런스 발표 영상을 재생한다 (예: Google I/O, KCD, JSConf 발표).
Side Panel을 열고 영상과 관련된 질문을 입력한다.
- "이 발표에서 언급된 API 이름과 GitHub 링크를 정리해 줘"
- "발표자가 설명한 아키텍처 패턴을 요약해 줘"
- "이 영상에서 권장한 설정값들을 목록으로 만들어 줘"
Gemini가 영상 내용을 분석해 응답을 반환한다.
후속 질문을 이어서 입력한다.

ex) 얼마전 발표한 구글 IO의 참조 링크 정리

시나리오 B: Gmail 초안 작성

어느 페이지에서든 Side Panel을 연다.
"팀원에게 오늘 발견한 [특정 버그]를 설명하는 이메일 초안을 작성해 줘"라고 요청한다.
Gemini가 초안을 생성하면 검토 후 "Gmail로 보내줘" 또는 "Gmail에 초안으로 저장해 줘"를 요청한다.
Gmail이 열리며 초안이 작성된 상태로 연결된다. 전송은 사용자가 직접 확인 후 진행한다.

시나리오 C: Calendar 일정 추가

Side Panel에서 "다음 주 화요일 오후 2시에 코드 리뷰 미팅 일정 추가해 줘"라고 요청한다.
Gemini가 일정 상세를 확인하는 응답을 반환하고, 최종 추가 여부를 사용자에게 확인한다.
사용자가 확인하면 Google Calendar에 일정이 추가된다.

이런 식으로 쓸 수 있다

YouTube 기술 세션 시청 중: 발표에서 언급된 API 이름·GitHub 링크·설정값을 실시간으로 정리
버그 재현 단계 정리 후: Side Panel에서 바로 Gmail 초안으로 연결해 팀원에게 전달
장애 대응 직후: 회고 미팅 일정을 Calendar에 바로 추가
컨퍼런스나 팀 모임 장소: Maps에서 바로 확인

민감 작업(이메일 전송, 캘린더 추가)은 Gemini가 자동으로 실행하지 않고 사용자 최종 확인을 거친다.

보안 설계에 대한 상세한 내용은 섹션 9에서 다룬다.

6. 튜토리얼 4 — 인라인 이미지 편집 실습 (Nano Banana 2)

Google 공식 블로그(2026-04-20)에 따르면 Nano Banana 2(공식 기술 명칭: Gemini 3.1 Flash Image)를 활용해 브라우저에 표시된 이미지를 텍스트 프롬프트 하나로 변환할 수 있다. 이미지를 다운로드하거나 외부 도구로 재업로드할 필요가 없다.

ex) 사용 예시1

Nano Banana 2 (Gemini 3.1 Flash Image) 소개

Google DeepMind 공식 발표(2026-02-26)에 따르면 Gemini 3.1 Flash Image는 Nano Banana Pro의 고급 기능과 Gemini Flash의 속도를 결합한 이미지 모델이다. 출시 직후 Artificial Analysis Image Arena 텍스트-이미지 리더보드 최상위권에 진입했으며(2026-04-21 기준 #2, GPT Image 1.5가 #1), 이전 모델인 Nano Banana Pro 대비 API 가격이 약 절반 수준으로 알려져 있다.

단계별 실습

Chrome에서 편집하거나 변형 아이디어를 확인하고 싶은 이미지가 있는 페이지를 연다.
- 예 A: UI 디자인 스크린샷이 포함된 Figma 공유 링크
- 예 B: 아키텍처 다이어그램 이미지가 있는 기술 문서
- 예 C: 색상이나 레이아웃 변형을 검토 중인 목업 페이지
Side Panel을 열고, 변환하고 싶은 이미지를 선택하거나 가리킨다.
텍스트 프롬프트로 변환 요청을 입력한다.
- "이 UI의 배경색을 다크 테마로 바꿔줘"
- "이 다이어그램에서 데이터 흐름 화살표를 더 명확하게 강조해 줘"
- "이 목업에서 버튼 크기를 키우고 여백을 넓혀줘"
Gemini가 Nano Banana 2 모델을 사용해 변환된 이미지를 Side Panel에 반환한다.
결과를 다운로드하거나 추가 변환을 요청할 수 있다.

ex)

- 동작 과정

- 결과

주로 이럴 때 쓴다

디자이너 Figma 스크린샷을 받은 경우: "다크 모드 버전으로 바꿔줘", "모바일 레이아웃처럼 재배치해 줘"로 시각적 대안 빠르게 확인
시스템 아키텍처 다이어그램: 특정 컴포넌트를 강조 표시한 버전 바로 생성
DB 스키마 이미지: "이 테이블 관계 더 명확하게 그려줘"로 수정 방향 빠르게 시각화
버그 재현 스크린샷: "오류 발생 영역 빨간 박스로 표시해 줘" 후 버그 리포트에 첨부

7. 개발자 심화 활용 케이스

Google 공식 블로그에 따르면 Auto Browse는 멀티스텝 작업을 자율적으로 처리하는 기능이다. 초기 테스트에선 양식 작성, 세금 서류 수집, 경비 보고서 제출 같은 반복 작업 위주로 활용됐다. 개발자 입장에서 즉각적으로 쓸 수 있는 케이스는 아래와 같다.

코드 리뷰 지원

GitHub PR 페이지에서 Side Panel을 열고 "이 PR의 변경 사항 요약, 잠재적 사이드 이펙트, 테스트 누락 여부를 분석해 줘"를 요청할 수 있다. 변경 파일 목록과 diff 내용을 Gemini가 분석해 리뷰 포인트를 추출한다.

CI/CD 오류 로그 요약

CI 파이프라인 실패 로그 페이지에서 Side Panel을 열고 "이 빌드 실패의 핵심 원인과 수정 방향을 요약해 줘"를 요청하면, 길고 복잡한 로그에서 핵심 에러를 빠르게 추출할 수 있다.

API 문서 분석 및 코드 예제 요청

공식 API 문서 페이지에서 "이 엔드포인트를 Python requests로 호출하는 예제를 작성해 줘" 또는 "이 파라미터 조합에서 주의해야 할 에지 케이스를 알려줘"처럼 문서 내용을 직접 참조한 코드 예제를 요청할 수 있다.

Personal Intelligence (AI Pro·Ultra 구독자 대상)

Google 공식 블로그(2026-04-20)에 따르면 Personal Intelligence 기능은 과거 대화 컨텍스트를 기억해 개인 맞춤형 응답을 제공한다. Google AI Pro·AI Ultra 구독자 대상 베타로 제공되며, 이메일·캘린더·문서·검색 기록 기반 맞춤 응답이 가능하다.

Skills — 커스텀 워크플로우 저장 (2026-04-14 출시, 포스트 최초 발행 시 누락)

Google 공식 블로그(2026-04-14)에 따르면 Skills는 Side Panel 입력창에서 /를 입력해 저장된 프롬프트 워크플로우를 즉시 실행하는 기능이다. 이름과 이모지를 붙인 커스텀 프롬프트를 저장해두면 반복 작업을 원클릭으로 처리할 수 있고, Google이 제공하는 공식 Skills 라이브러리는 chrome://skills/browse에서 Learning·Research·Shopping·Writing 카테고리로 탐색 가능하다. Skills는 멀티탭에도 적용돼 여러 탭을 선택한 뒤 한 번에 실행할 수 있다. 현재 Mac·Windows·ChromeOS 환경, 영어(US) 언어 설정에서 제공된다.

개발자가 바로 만들어 쓸 수 있는 Skills 예시

/pr-review — "이 PR의 변경 사항, 잠재적 사이드 이펙트, 테스트 누락 여부를 분석해 줘" 저장
/api-summary — "이 API 문서에서 인증 방식, rate limit, 주요 엔드포인트를 정리해 줘" 저장
/ci-log — "이 빌드 실패 로그의 핵심 원인과 수정 방향을 요약해 줘" 저장

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

이 섹션은 공개된 정보를 기반으로 한 추정이다. Gemini in Chrome의 내부 아키텍처는 공개되지 않았으므로, 공식 동작 설명과 배포 방식을 바탕으로 추론한 내용이다. 직접 확인이 어려운 부분은 명시적으로 "추정된다", "보인다" 등으로 표기한다.

추론 위치: 서버사이드 가능성이 높다

9to5Google(2026-01-28)은 "Gemini 사이드바 지원과 Nano Banana 통합이 서버사이드 서비스 업데이트로 배포된다"고 보도했다. 특정 Chrome 버전 업데이트 없이 기능이 활성화된다는 점은 추론이 클라이언트가 아닌 Google 클라우드 서버에서 이루어지고 있을 가능성을 시사한다.

다만 Gemini Nano 계열 모델이 Pixel 기기 등에서 온디바이스 실행을 지원한다는 점을 감안하면, 향후 경량 추론 일부가 클라이언트 측으로 이동하는 하이브리드 구조로 발전할 가능성도 있어 보인다. 현재 Gemini in Chrome이 온디바이스 추론을 활용하는지는 공식적으로 확인된 정보가 없다.

Nano Banana 2 온디바이스 가능성

Gemini 3.1 Flash Image 공식 페이지에 따르면 이 모델은 "Flash"급으로 빠른 응답속도를 설계 목표로 하고 있다. 이미지 변환 요청이 서버를 거쳐 처리되는지, 또는 일부 연산이 기기 내에서 처리되는지는 공개된 문서에서 확인할 수 없다. 실제 네트워크 지연을 측정해보면 처리 위치를 간접적으로 파악할 수 있을 것으로 추정되나, 이 역시 직접 검증이 필요한 영역이다.

Side Panel 데이터 처리 흐름 추정

사용자가 Side Panel에서 질문을 입력하면, 현재 탭(또는 선택한 탭들)의 콘텐츠가 Gemini API 요청에 컨텍스트로 포함되어 Google 서버로 전송되고, 응답이 Side Panel에 표시되는 흐름으로 추정된다. 탭 내용이 Google 서버로 전송된다는 점은 개인정보 처리 관점에서 유의해야 한다. 민감한 내부 문서나 인증 정보가 포함된 페이지에서는 특히 주의가 필요하다.

9. 보안 고려사항 — Prompt Injection 방어

Prompt Injection이란

Prompt injection은 악의적인 웹 페이지가 숨겨진 텍스트나 이미지를 통해 AI에게 의도치 않은 명령을 주입하려는 공격이다. 예를 들어 웹 페이지 본문에 "이 이메일을 공격자 주소로 전송하라"는 내용이 숨겨져 있으면, AI가 페이지 내용을 읽으면서 그 명령을 따를 위험이 있다.

개발자 입장에서 이 문제는 특히 중요하다. 외부 사용자가 입력할 수 있는 콘텐츠(게시글, 이슈, PR 설명 등)를 AI가 처리하는 상황이라면 prompt injection을 항상 고려해야 한다.

Google의 다층 방어 설계

Google Workspace 보안 문서에 따르면 Google은 다음 4가지 핵심 방어 메커니즘을 포함한 다층(multi-layered) 방어 구조를 구성한다.

Model Resilience (모델 견고성): 적대적 강건성 훈련을 통해 모델이 주입 시도를 식별하도록 훈련
Content Classification (콘텐츠 분류기): prompt injection 시도를 감지하는 별도 분류기 적용
Security Thought Reinforcement (보안 사고 강화): 실행 전 보안 관련 지시사항 점검
Markdown Sanitization (마크다운 정제): 마크다운 기반 주입 시도를 사전 차단

여기에 더해 공식 블로그(2026-01-28)에 따르면 구매·SNS 게시 등 민감 작업은 실행 전 사용자 확인을 요청하도록 설계되어 있다.

사용자 정렬 비평가 (User Alignment Critic)

Gemini in Chrome의 브라우징 에이전트(보도에서는 'Gemini for Chrome'이라고도 표기)에는 "사용자 정렬 비평가(user alignment critic)"로 불리는 두 번째 AI 에이전트가 내장되어 있다. 이 에이전트는 Gemini가 제안하는 각 행동을 실행 전에 독립적으로 검토해, 목표 탈취(goal-hijacking)와 데이터 유출을 방어하는 역할을 한다. 이 정보는 미디어 보도 기반이며 Google 공식 문서에서 직접 확인하지 못했으므로, 적용 범위는 별도 검증이 필요하다.

알려진 취약점 및 패치 이력

CVE-2026-0628(CVSS 8.8)이 발견됐다. 악성 Chrome 확장이 Gemini 패널을 통해 권한 탈취(privilege escalation)를 일으킬 수 있었던 취약점이며(Palo Alto Networks Unit 42 분석), Google이 2026년 1월 Chrome 143.0.7499.192 버전에서 패치를 완료했다. 현재는 수정된 취약점이나, Chrome 확장 관리에 주의가 필요하다는 점을 시사한다.

개발자 보안 체크리스트

Gemini in Chrome을 업무 환경에서 활용할 때 다음 항목을 점검한다.

내부 문서·인증 정보가 있는 페이지에서는 신중하게 사용한다. 탭 내용이 Google 서버로 전송될 가능성이 있다.
의심스러운 외부 사이트에서 Side Panel 사용을 자제한다. 악의적인 페이지가 prompt injection을 시도할 수 있다.
이메일 전송, 캘린더 추가 등 민감 작업은 Gemini 제안을 반드시 직접 검토 후 확인한다. 자동 실행 없이 사용자 확인 절차가 있더라도, 내용을 직접 확인하는 것이 안전하다.
기업 계정을 사용하는 경우 IT 관리자에게 정책 적용 여부를 확인한다. HIPAA BAA 체결 기업, 학교 계정, 관리 정책 적용 계정에서는 기능이 차단될 수 있다.
Chrome 확장 프로그램을 최소화하고 신뢰할 수 없는 확장은 제거한다. CVE-2026-0628 패치 이후에도 확장 권한 관리는 보안의 기본이다.
Chrome을 항상 최신 버전으로 유지한다. 보안 패치가 자동으로 포함된다.

10. 요금제 및 제한사항

아래 요금 정보는 2026-05-27 기준으로 갱신됐다 (원본 작성: 2026-04-21). 최신 가격은 공식 Gemini 구독 페이지에서 반드시 확인하라.

요금 구조

Gemini 구독 페이지 기반 정보에 따르면 (2026-04-21 기준, 최신 가격은 공식 페이지 확인):

티어	가격	주요 포함 사항
무료	$0	Side Panel 기본 기능, 15GB 스토리지 (AI 크레딧 세부 한도는 공식 페이지 확인)
Google AI Pro	$19.99/월 (미국 기준)	확장 Gemini 기능, Personal Intelligence 베타 접근
Google AI Ultra 5x	$99.99/월 (미국 기준, 신설)	최고 수준 모델 접근, Auto Browse 포함, 미국 한정
Google AI Ultra 20x	$199.99/월 (미국 기준, 구 $249.99에서 인하)	최고 수준 모델 최대 사용량, 모든 기능 포함

Auto Browse 기능(멀티스텝 자율 작업)은 공식 블로그(2026-01-28)에 따르면 미국 내 Google AI Pro 및 AI Ultra 구독자에게만 제공된다. 한국에서의 Auto Browse 제공 여부는 공식 문서에서 별도 확인이 필요하다.

지원 언어 및 지역

Chrome 공식 지원 문서는 Gemini in Chrome 지원 언어 목록에 Korean을 명시하고, 지원 지역 목록에 South Korea와 U.S.A를 함께 포함한다. 따라서 한국어 환경 자체가 Side Panel 미노출의 원인이라고 보기는 어렵다. 다만 기능은 순차 배포되므로, 조건을 충족해도 계정별로 표시 시점이 다를 수 있다.

알려진 제한사항

공식 지원 문서 및 커뮤니티 보고 기반 제한사항은 다음과 같다.

멀티탭 공유 상한: 데스크톱 기준 최대 10개 탭
모바일 기능 차이: Android는 데스크톱 대비 일부 기능이 제한될 수 있다
기업 계정 제한: Google Workspace 업데이트(2026-03)에 따르면 HIPAA BAA 체결 기업, 교육 계정, 관리 정책 적용 직장 계정에서 기능이 차단될 수 있다
Auto Browse 지역 제한: 미국 내 유료 구독자 한정 (2026-04-21 기준)

11. 대안 비교

비교 전제: 2026-05-27 기준으로 갱신

빠르게 변하는 분야이므로 최신 기능은 각 공식 페이지에서 확인을 권장한다.

비교 축	Gemini in Chrome	Microsoft Copilot in Edge¹	ChatGPT Atlas³
요약/질의응답	Side Panel 통합	사이드바 통합	사이드바 통합
멀티탭 분석	최대 10개 탭	무료 멀티탭 AI 지원 (2026-05-13부터, M365 불필요)	에이전트 모드 (Agent Mode) 자동화 지원
이미지 편집	Nano Banana 2 (인라인 편집)	인라인 직접 수정 미지원 (Vision 분석 및 이미지 생성 가능)	미지원
Google 서비스 연동	Gmail·Maps·Calendar·YouTube 네이티브 통합	Microsoft 365 앱 통합	해당 없음
플랫폼	Chrome (데스크톱·iOS·Android)	Edge (데스크톱·iOS·Android)	macOS (독립 브라우저)
무료 사용 범위	하루 50 AI 크레딧 무료	멀티탭·Vision·Voice·History 개인화 무료; Browse with Copilot(에이전트)는 M365 Premium 구독 필요	기본 브라우징 맥락 (Context) 요약 무료
침습성	버튼 클릭 시만 활성 (opt-in)	기본 활성 (opt-out 방식)	별도 브라우저 앱
prompt injection 방어	다층 방어 + 사용자 확인 절차	미확인	미확인

선택 기준은 단순하다.

이미 Google 생태계를 쓰고 있다면 Gemini in Chrome이 가장 마찰이 없다.

Microsoft 365가 메인 환경이라면 Copilot in Edge가 낫다.

멀티탭은 30개까지 지원하고 M365 통합도 더 자연스럽다.

Arc Max는 무료라는 점이 매력이지만 개발 중단 발표가 있으므로 장기 도입 계획이라면 재고할 필요가 있다.

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

트러블슈팅 Q&A

Q1. Side Panel이 보이지 않는다.

Chrome 공식 지원 문서는 Gemini in Chrome이 순차 배포 중이라 국가·지역에 따라 아직 보이지 않을 수 있다고 안내한다. 지원 지역이라면 다음 순서로 확인한다.

일반 Chrome 창에서 Google 계정으로 Chrome에 로그인되어 있는지 확인한다. 시크릿 모드에서는 사용할 수 없다.
기기 또는 Chrome 언어가 지원 언어인지 확인한다. 한국어는 지원된다.
Chrome을 최신 버전으로 업데이트한 뒤 브라우저를 재시작한다.
Chrome 설정 → AI innovations → Gemini in Chrome에서 "Show Gemini at the top of the browser"가 켜져 있는지 확인한다.
직장·학교 Google 계정이라면 관리자가 Gemini in Chrome 접근을 허용했는지 확인한다.
위 조건을 모두 충족해도 보이지 않으면 계정별 순차 배포 대기 상태일 가능성이 있다.

Q2. "This account can't use Gemini" 오류가 발생한다.

Chrome 지원 스레드(2026-04-21)에 따르면 두 가지 원인이 주로 보고된다. 첫째, 지역 미지원 — "not supported in your region" 메시지가 함께 표시된다. 둘째, 기업·학교 계정 정책에 의한 차단. 개인 Google 계정으로 전환 후 재시도하면 원인을 구분할 수 있다.

Q3. Glic Actor Failure 오류가 발생한다.

stepcodex.com(2026-04-21)에 따르면 Chrome UI 우측 상단 'Action Required' 버튼이 표시되면 권한 부여나 계정 동기화가 필요한 상태다. 버튼을 클릭해 안내에 따라 완료하면 해결되는 경우가 많다.

Q4. 특정 사이트에서 Side Panel이 응답하지 않는다.

일부 사이트(iframe 기반, 로그인 필요 페이지, 특수 렌더링 방식)에서는 Gemini가 탭 내용에 완전히 접근하지 못할 수 있다. 이 경우 접근 가능한 부분만 분석되거나 응답이 제한될 수 있다. 해당 페이지의 공개 URL을 직접 제공하는 방식으로 우회할 수 있다.

Q5. 기업 계정에서 Gemini가 차단되어 있다면?

IT 관리자에게 Google Workspace 관리 콘솔에서 Gemini in Chrome 기능 허용 여부를 확인하도록 요청한다. 관리 정책이 적용된 계정은 관리자 허용 없이 개인이 직접 활성화할 수 없다.

결론 — 어떤 개발자에게 유용한가

개발자 유형	활용도	추천 기능
문서 탐색·학습이 많은 개발자	높음	Side Panel 요약, 멀티탭 교차 분석
PR 리뷰·코드 리뷰를 자주 하는 개발자	높음	멀티탭 비교, GitHub 페이지 분석
Google Workspace를 업무에 쓰는 팀	높음	Gmail·Calendar·YouTube 연동
UI/UX 프로토타이핑을 빠르게 검토하는 개발자	중간	Nano Banana 2 이미지 편집
기업 계정(HIPAA, 교육기관) 사용자	낮음	관리자 확인 필수
터미널·IDE 중심 워크플로우 개발자	낮음~중간	브라우저 작업 시에만 선택적 활용

브라우저를 이미 개발 도구로 쓰고 있다면 별다른 준비 없이 시작할 수 있다. API 문서 정리, PR 비교, 기술 영상 학습처럼 어차피 브라우저 안에서 하는 작업이 많다면 진입 비용이 낮다.

터미널과 IDE에서 대부분의 시간을 보내는 개발자라면 체감 효용이 크지 않을 수 있다. 그 경우 Side Panel 요약 하나만이라도 API 문서나 오픈소스 README를 빠르게 파악하는 용도로 쓰면 충분하다.

무료 티어는 하루 50 AI 크레딧을 제공하므로 일상적인 문서 작업을 처리하는 데 충분하다.

Auto Browse 기능은 현재 미국 내 Google AI Pro·Ultra 구독자 한정으로 제공되므로, 한국에서는 먼저 무료로 사용해 보고 활용 패턴이 생기면 구독을 검토하는 접근이 합리적이다.

Gemini in Chrome은 지속적으로 업데이트되는 서비스이므로, 기능·요금·지원 지역 변경 사항은 Chrome 공식 지원 문서 및 Google 공식 블로그에서 확인하는 것을 권장한다.

Codex Mac App 가이드(2) : Codex App 원격 제어 방법 : 모바일 제어 부터 다른 기기 제어, SSH 원격 연결까지

갓대희 — Tue, 26 May 2026 00:53:17 +0900

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

Codex Mac App 실무 정복 시리즈

Part 1: Codex App 기초 가이드Part 2: Codex App 원격 연동 가이드 — 현재 글Part 3: Codex App 펫(Pets) 활용 가이드

Codex란 무엇인가 — 데스크톱에서 모바일로
시작하기 — ChatGPT 앱에서 Codex 연결하는 방법
주요 기능 상세 — 모바일에서 할 수 있는 것과 없는 것
한 걸음 더 — 다른 기기 제어와 SSH 원격 연결
실전 사용 시나리오
요금제 및 제한사항
트러블슈팅 Q&A + 도입 결정 매트릭스

집에서 작업중인 Mac에 Codex를 돌려두고 출근 할 때, 또는 퇴근 버스에서 해당 작업이 계속 잘 동작하는지 확인하고 싶을 때가 있다. 2026년 5월 14~15일, OpenAI가 ChatGPT iOS·Android 앱에 Codex 모바일 기능을 추가한다고 발표했다.

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

Codex: OpenAI의 클라우드 기반 코딩 AI 에이전트. ChatGPT 안의 한 기능이 아니라, 그 위에 따로 얹힌 에이전트 레이어다.
codex-1: Codex의 두뇌에 해당하는 모델. OpenAI o3 기반으로 알려져 있다.
호스트 머신(Host Machine): Codex가 실제로 코드를 실행하는 컴퓨터. 개발자 Mac, devbox, 원격 서버 등이 여기에 해당한다.
페어링(Pairing): 모바일 앱과 호스트의 Codex 앱을 QR 코드로 처음 연결하는 작업.
보안 릴레이(Secure Relay): 내 컴퓨터를 인터넷에 그대로 열어두지 않고도, 인증된 폰하고만 통신하게 해 주는 중계 계층.
프리뷰(Preview): 정식 출시 전 단계. 기능이나 접근 대상이 도중에 바뀔 수 있다.
diff: 코드가 어떻게 바뀌었는지 보여 주는 형식. +는 추가된 줄, -는 삭제된 줄이다.

1. Codex란 무엇인가 — 데스크톱에서 모바일로

Codex는 OpenAI의 클라우드 기반 코딩 에이전트다.

IDE에서 흔히 보는 자동완성 같은 도구라기보다는, 격리된 컨테이너(샌드박스) 안에서 작업을 알아서 처리한다.

격리 컨테이너라고 하니 거창해 보이지만, "다른 코드와 섞이지 않게 따로 차린 임시 작업방" 정도로 이해하면 충분하다.

기존 Codex 인터페이스는 데스크톱 앱, CLI, IDE 확장 세 가지였다. 여기에 모바일이 추가되면서 네 가지 인터페이스가 같은 백엔드 하나에 연결되는 형태가 됐다. 실제로 작업을 처리하는 머신은 그대로 두고, 그것을 확인하고 조작하는 화면만 폰으로 옮긴 구조다. 이 구조를 이해해야 모바일 Codex가 왜 "코드를 짜는 도구"가 아니라 "에이전트를 감독하는 도구"인지 분명해진다.

참고: "폰으로 AI 코딩 에이전트 조작" 흐름은 이미 있었다

이 흐름의 시작은 Anthropic 쪽이다. Claude Code Remote Control이 2026년 2월에 먼저 출시됐다.
Codex 모바일은 약 4개월 뒤에 같은 기능을 ChatGPT 생태계로 도입한 것이다.

2. 시작하기 — ChatGPT 앱에서 Codex 연결하는 방법

구조를 확인했으니 실제 연결 방법을 살펴보자. 현재 모바일 연결은 macOS 전용이다.
Windows 지원은 "coming soon"으로만 안내되어 있다. Windows 사용자라면 정식 지원이 출시된 후 다시 검토하는 것이 안전하다.

사전 조건

macOS 기기에서 Codex 앱 설치 및 최신 버전 업데이트 완료
iPhone, iPad, 또는 Android 기기에 최신 버전 ChatGPT 앱 설치
ChatGPT 계정으로 두 기기 모두 로그인

연결 절차

[1] 두 앱 모두 최신 버전으로 업데이트한다
[2] Mac Codex 앱 → 'Codex mobile' 섹션을 찾는다
[3] 표시된 QR 코드를 ChatGPT 모바일 앱으로 스캔한다

이 세 단계를 거치면 Mac의 Codex 앱과 폰의 ChatGPT 앱이 연결된다.

- 본인의 os에 맞는 QR코드를 생성 하여 스캔하자.

- GPT 앱이 설치되어있다면 다음과 같이 인증 화면이 뜰 것이다. 연결 클릭 후 인증완료해보자.

- - 폰에서 인증 완료되면 PC Codex App에서도 연결되는것을 볼 수 있다.

- 좌측 하단에 Codex 모바일을 클릭하거나, 설정 > "연결" 을 클릭해보자.

- 정상연결되어있음을 확인할 수 있고, 언제든 연결해지 가능하다.

페어링이 완료되면 진행 중인 Codex 작업을 폰에서 거의 실시간으로 확인하고 조작할 수 있다.

QR 코드가 보이지 않는다면 대부분 앱 버전 문제이므로, 다른 설정을 변경하기 전에 두 앱의 업데이트 여부부터 확인하는 것이 좋다.

연결 방식은 보안 릴레이(Secure Relay)로 알려져 있다. 내 컴퓨터를 인터넷에 그대로 열어두는 대신, 인증된 ChatGPT 기기끼리만 OpenAI 인프라를 거쳐 신호를 주고받는 구조다. 방화벽 없이 개인 서버를 외부에 노출하는 것과는 다른 그림이라고 보면 된다.

macOS 전용 제약에 대한 현실적인 조언

Codex 앱 자체는 아직 macOS 전용이다. 다만 devbox나 원격 Linux 서버를 주로 쓴다면, 그 Mac 앱에서 SSH 원격 연결로 원격 머신을 직접 작업 대상으로 삼을 수 있다. 즉 Mac은 "조종석" 역할만 하고 실제 코드는 원격 호스트에서 돌아가는 구성이 가능하다. 설정 방법은 4장 — 다른 기기 제어와 SSH 원격 연결에서 단계별로 다룬다. Windows에서 Codex 앱을 직접 구동하는 것은 아직 예정 단계다.

3. 주요 기능 상세 — 모바일에서 할 수 있는 것과 없는 것

연결은 완료됐다. 그렇다면 폰에서 실제로 무엇을 할 수 있을까.

할 수 있는 것

모바일에서 가능한 작업은 다음과 같은 예시가 있다.

기능	설명
새 작업 시작	폰에서 자연어로 Codex 작업을 새로 생성한다
출력물 검토	터미널 출력, 스크린샷, diff, 테스트 결과를 실시간으로 확인한다
명령 승인	에이전트가 중요 액션 실행 전 요청하는 승인을 폰에서 처리한다
모델 전환	작업에 맞게 백엔드 모델을 변경한다
컨텍스트 추가	진행 중인 작업에 새로운 지시나 파일을 추가한다
승인 요청 알림	작업이 완료되거나 입력이 필요할 때 알림을 받는다

표에서 보이듯 폰의 역할은 "실제 실행"이 아니라 "모니터링과 제어"에 가깝다.

이 차이를 이해해야 이후 내용이 자연스럽게 연결된다.

ex) 모바일에서 Codex에게 요청 해보자.

- 로컬 PC의 Codex App에서도 동일한 프롬프트가 동작하고 있다.

할 수 없는 것

코드 실행은 호스트 머신에서만 이루어진다.

파일, 자격증명, 권한, 로컬 설정은 Codex가 작동하는 머신에 그대로 유지된다.

모바일 앱이 이 데이터에 직접 접근하거나 코드를 실행하지 않는다.

보안 주의: 폰에서 승인 누르는 일은 생각보다 위험하다

실제 사용자 리뷰에서도 "폰에서 에이전트 액션을 승인하는 건 진짜로 실수가 날 만한 일"이라는 지적이 나온 바 있다.

작은 화면에서 diff를 한 줄 한 줄 따라가기는 쉽지 않다.

그 상태로 무거운 승인을 누르는 건 분명히 위험하다.

프로덕션에 영향을 주는 변경은 웬만하면 자리에 앉아 데스크톱에서 처리하는 편이 낫다.

Codex CLI·IDE 확장과의 관계

모바일 페어링 대상은 macOS 데스크톱 앱 전용이다.

Codex CLI나 IDE 확장(VS Code 등)은 현재까지는 모바일 호스트로 동작하지 않는다.

4. 한 걸음 더 — 다른 기기 제어와 SSH 원격 연결

여기까지가 "폰으로 내 Mac 보기"였다.

그런데 Codex Mac 앱의 설정 > 연결 패널을 열어 보면 탭이 세 개다.

2장에서 쓴 건 그중 첫 번째 탭 하나뿐이다.

탭	하는 일	방향
이 Mac 제어	폰(ChatGPT 앱)으로 이 Mac의 Codex를 제어 — 2장에서 다룬 기능	폰 → 이 Mac
다른 기기 제어	이 Mac에서 다른 Codex 기기에 접근하고 제어	이 Mac → 다른 Mac
SSH	원격 머신(devbox·Linux 서버)에 SSH로 연결해 그 위에서 Codex 작업 실행	이 Mac → 원격 호스트

아래 두 탭은 모바일 제어와 같은 2026년 5월 14일에 함께 공개됐다.

그중 SSH 원격 연결은 2026년 4월 알파를 거쳐 현재 정식(GA) 단계이며, 모든 플랜에서 제공된다(2026-05-25 기준).

4-1. 다른 기기 제어 (Control other devices)

한 대의 Mac에서 다른 Codex 기기에 접근해 작업을 이어받는 기능이다.

공식 문서는 "한 기기가 원격 접근을 허용하는 동시에 다른 기기를 제어할 수 있다"고 설명한다.

사무실 iMac과 집 MacBook을 모두 Codex 호스트로 두고, 어느 쪽에서든 다른 쪽 작업을 들여다보는 식이다.

설정 패널의 "다른 기기 제어" 탭을 열면 "이 Mac에서 제어할 수 있는 기기" 목록과 함께 [설정하기] 버튼이 보인다.

[1] Codex 앱 → 설정(Settings) > 연결(Connections)
[2] '다른 기기 제어' 탭 선택
[3] [설정하기] 클릭 → 제어할 다른 Codex 기기 연결

제어 대상이 되는 기기에도 Codex 앱이 같은 계정으로 로그인되어 있어야 한다.

4-2. SSH 원격 연결

세 탭 중 실무 활용도가 가장 높은 기능이다.

devbox나 원격 Linux 서버를 SSH로 연결하면, Codex가 그 원격 머신 위에서 직접 명령을 실행하고 파일을 읽고 변경을 쓴다.

즉 Mac 앱은 조종석 역할만 하고, 실제 코드는 원격 호스트에서 돌아간다.

"SSH" 탭을 열면 "이 Mac의 SSH 연결" 영역과 [추가] 버튼이 보인다.

사전 조건

Codex 앱(macOS) 설치 및 최신 버전 — Windows는 아직 미지원
Mac 터미널에서 해당 원격 호스트로 SSH 접속이 이미 되는 상태일 것(계정·키 등 준비)
원격 호스트의 PATH에 codex 명령이 설치되어 있을 것

연결 절차

SSH 탭에서 [추가]를 누르면 "SSH 연결 추가" 창이 뜬다. 이 창은 두 갈래다 —

① ~/.ssh/config에서 자동 탐지된 호스트를 고르는 방식과,

② 정보를 직접 입력하는 "수동으로 추가" 방식이다. 둘 중 편한 쪽을 쓰면 된다.

방식 A — 자동 탐지 (~/.ssh/config 활용)

① 먼저 ~/.ssh/config에 호스트를 등록해 둔다. Codex는 이 파일의 구체적 호스트 별칭만 읽고 OpenSSH로 해석하며, 패턴(*) 전용 호스트는 무시한다.

# ~/.ssh/config
Host devbox
  HostName devbox.example.com
  User you
  IdentityFile ~/.ssh/id_ed25519

② Mac 터미널에서 ssh devbox로 접속이 정상인지 먼저 확인한다.

③ SSH 탭 → [추가]를 누르면 "SSH 연결 추가" 창이 ~/.ssh/config의 호스트를 자동으로 훑어 목록에 보여 준다. 목록에서 호스트를 선택하고 [추가]를 누른다.

등록된 호스트가 없으면 창에 "발견된 SSH 연결이 없습니다"라고 표시된다. 이때는 아래 방식 B로 넘어가면 된다.

방식 B — 수동으로 추가

~/.ssh/config를 손대지 않고도, 창 왼쪽 아래 [수동으로 추가]를 누르면 정보를 직접 입력하는 폼이 열린다.

입력 항목	설명
디스플레이 이름	목록에 표시될 별칭. 알아보기 쉬운 이름(예: "회사 devbox")
호스트 이름	`host.com` 또는 `user@host.com` 형식
SSH 포트 (선택 사항)	비워 두면 기본값(22). 비표준 포트를 쓸 때만 입력
인증 방식	인증 없음 / 인증 키 파일 중 선택. 키 기반 인증이라면 "인증 키 파일"을 골라 개인키 파일(예: `~/.ssh/id_ed25519`)을 지정한다

입력을 마치면 [저장]을 누른다.

~/.ssh/id_ed25519

지정 후 [저장]을 누른다.

"인증 없음" 옵션의 정확한 동작은 확인 후 갱신 예정

"인증 없음"은 이 폼에서 키 파일을 따로 지정하지 않는 선택지다. 시스템에 이미 구성된 SSH 설정(ssh-agent에 올라간 키, ~/.ssh/config의 IdentityFile 등)에 의존하는 것으로 보이나, 이 옵션의 세부 동작은 공식 문서에 명시되어 있지 않다. 키 인증을 확실히 쓰려면 "인증 키 파일"로 개인키를 직접 지정하는 편이 안전하다.

④ [저장]을 누르면 연결 정보가 목록에 등록되는 동시에 Codex가 즉시 SSH 접속을 시도한다.

호스트가 정상이면 목록에 녹색 점으로 표시되고, 호스트가 없거나 원격 머신에 codex 명령이 없으면 빨간 점과 함께 "SSH 연결 실패"가 표시된다. 각 연결 항목에는 토글 스위치가 있어 개별적으로 활성/비활성 전환이 가능하다.

- 위의 경우는 테스트 서버 여서 그렇지만, 실제 서버 정보를 올바르게 입력하면 다음과 같이 초록 불이 들어올 것 이다.

ex) 인증키 생성 및 실제 접속 예시

⑤ 연결이 성공 상태라면 원격 프로젝트 폴더를 지정하고, 그 폴더에서 Codex thread를 실행한다.

앱은 이 SSH 경로로 원격 사용자의 로그인 셸을 통해 원격 Codex 앱 서버를 시작한다.

(앞의 "사전 조건"대로 원격 호스트 PATH에 codex가 있어야 이 단계가 성공한다.)

이렇게 등록한 원격 프로젝트의 thread는 원격 호스트에서 명령을 실행하고 파일을 읽고 변경을 기록한다.

"로컬 서버"는 내 리눅스 서버인데 해당 서버에 있는 프로젝트를 내 맥북에 등록하여 바로 작업을 요청할 수 있게 되었다.

ex)

4-3. 세 기능을 합치면 — 폰에서 원격 서버까지

세 탭을 조합하면 흥미로운 그림이 나온다. 폰(ChatGPT 앱)이 Mac(Codex 앱)을 제어하고, 그 Mac이 SSH로 원격 Linux 서버를 작업 대상으로 삼는 다단계 연결이다.

폰(ChatGPT 앱) ──▶ Mac(Codex 앱) ──SSH──▶ 원격 devbox/Linux
   제어·승인          조종석             실제 코드 실행

카페에서 폰으로 승인을 누르면, 집 Mac을 거쳐 회사 devbox에서 실제 빌드가 돌아가는 구성이 가능하다는 뜻이다.

주의: 호스트 Mac이 깨어 있어야 한다

공식 문서는 "그 Mac이 잠들거나, 네트워크를 잃거나, Codex를 닫으면 원격 접근이 중단된다"고 명시한다. 외출 중 계속 쓰려면 호스트 Mac을 전원에 연결하고 절전(잠자기)을 꺼 두는 것이 좋다. SSH 호스트(원격 서버)도 당연히 켜져 있어야 한다.

5. 실전 사용 시나리오

구조와 제약을 확인했으니, 실제로 어떤 상황에서 활용할 수 있는지 살펴보자.

결론부터 말하면 모바일 Codex가 가장 효과적인 상황은 "20분 이상 소요되지만 중간에 사용자 결정이 한두 번 필요한 작업"이다.

그보다 짧은 작업은 자리에서 직접 처리하는 것이 빠르고, 완전 자동화가 가능한 작업은 CI에 맡기는 것이 적합하다.

이 경계를 염두에 두고 아래 두 시나리오를 살펴보자.

시나리오 1 — 이동 중 버그 대응

① 오전 9시: 사무실 Mac에서 "auth 모듈 토큰 검증 버그 수정" 작업을 Codex에 지시하고 출근 버스에 오른다.
② 9시 20분: 폰 알림 — Codex가 버그를 찾고 패치 초안을 완성했다.
③ 9시 21분: ChatGPT 앱에서 diff를 확인한다. 변경 범위가 납득된다.
④ 9시 22분: 승인 버튼을 누른다. Codex가 테스트를 실행한다.
⑤ 사무실 도착 시: 테스트 결과만 최종 확인하면 된다.

이 흐름에서 폰의 역할은 코드 수정이 아니라, 에이전트가 다음 단계로 진행해도 되는지 결정하는 "승인 게이트"에 가깝다.

핵심은 에이전트가 작업하는 동안 사용자가 이동 중이어도 무방하다는 점이다.

알림이 도착할 때만 확인하면 된다.

시나리오 2 — 시간 오래 걸리는 작업 떠넘기기

데이터베이스 마이그레이션이나 큰 리팩토링처럼 20분 넘게 걸리는 작업을 Codex에게 맡겨두고, 개발자는 그동안 다른 일을 한다.

도중에 결정이 필요한 순간이 오면 알림으로 와서 그때 승인만 눌러주는 식이다.

긴 작업에 이 패턴이 잘 맞는 이유는 단순하다. Codex가 자율적으로 단계를 진행하다가, 중요한 지점에서는 잠깐 멈추고 사용자의 결정을 기다린다. 그래서 작업이 끝날 때까지 모니터를 계속 확인할 필요가 없다. "카페에 앉아서 마지막 결과만 승인한다"는 표현이 과장처럼 들릴 수 있지만, 실제 구조상 가능하다.

어떤 작업에 쓰지 않는가

반대로 모바일 Codex가 적합하지 않은 상황도 분명히 존재한다.

실시간 인라인 코드 편집 작업. Cursor나 IDE를 활용하는 것이 적합하다.
프로덕션 DB에 영향을 주는 긴급 롤백. 작은 화면에서 잘못 조작할 위험이 크다.
처음부터 설계를 잡아가는 장시간 대화형 세션. 데스크톱이 훨씬 효율적이다.

6. 요금제 및 제한사항

플랜별 Codex 접근 조건

요금 정보는 매체마다 수치가 조금씩 다르게 기재되어 있다. 실제 도입을 결정할 때는 공식 페이지에서 직접 확인하는 것이 안전하다.

Codex 에이전트는 Plus($20/월), Pro($200/월), Business($25/사용자/월), Enterprise(맞춤형)에서 쓸 수 있다.

Free 플랜은 Codex 에이전트 기능 자체가 포함되지 않는다.

모바일 프리뷰 자체는 Free와 Go 플랜을 포함한 모든 플랜에서 지원 지역에 한해 접근 가능하다는 점이다.

다만 그 안에서 사용 가능한 Codex 에이전트 사용량은 플랜별로 별도 적용된다.

플랜	월 요금	Codex 에이전트	모바일 프리뷰
Free	무료	미포함	접근 가능(지역 한정)
Plus	$20	포함	접근 가능
Pro	$200	포함	접근 가능
Enterprise	맞춤형	포함	접근 가능

한편 SSH 원격 연결과 Hooks는 정식(GA) 단계로 모든 플랜에서 제공된다(4장 참조). 즉 Codex 에이전트 사용량 한도는 플랜별로 다르지만, "연결" 기능 자체에는 플랜 장벽이 거의 없다. 단, 프로그래밍 방식 액세스 토큰은 Business·Enterprise 플랜으로 제한된다.

기능별 출시 단계와 제한

모바일 제어: 프리뷰(preview) 단계 — 지역별 롤아웃 중이며 기능·인터페이스·접근 정책이 변경될 수 있다
SSH 원격 연결 · Hooks: 정식(GA) 단계, 모든 플랜 제공
호스트 앱은 macOS 전용 — Windows에서 Codex 앱을 직접 구동하는 것은 예정 단계다
모바일/원격 제어가 유지되려면 호스트 Mac이 깨어 있고 네트워크에 연결되어 있어야 한다

7. 트러블슈팅 Q&A + 도입 결정 매트릭스

자주 묻는 질문

Q. 모바일에서 Codex 앱이 보이지 않는다.

프리뷰 단계이므로 지역별 롤아웃 중이다. 두 앱(Mac Codex 앱, ChatGPT 모바일 앱) 모두 최신 버전으로 업데이트한 뒤 Mac 앱에서 'Codex mobile' 섹션을 다시 확인한다. Windows 환경은 아직 지원되지 않는다.

Q. Mac mini와 연결이 자꾸 끊긴다.

일부 사용자가 Mac mini 등 특정 기기에서 연결 문제를 보고하고 있다. 재현 사례가 다수 확인된 버그는 아니지만, 발생 시 두 앱을 재시작하거나 QR 코드 페어링을 다시 시도하는 것이 현재로서는 가장 직접적인 방법이다.

Q. 폰에서 명령을 승인할 때 실수가 걱정된다.

합리적인 우려다. 프로덕션 환경에 직접 영향을 주는 승인은 가급적 데스크톱에서 처리하는 것이 안전하다. 모바일 승인은 테스트 환경, 코드 리뷰 목적의 diff 확인, 비프로덕션 작업 위주로 활용하는 것이 권장된다.

Q. Free 플랜에서도 쓸 수 있나?

현재 프리뷰 기간에는 Free 플랜도 지원 지역에서 접근 가능하다. 다만 Codex 에이전트 기능 한도는 플랜별로 다르며, Free 플랜은 Codex 에이전트 자체를 포함하지 않는다.

Q. Codex CLI를 이미 쓰고 있다. 모바일도 같이 쓸 수 있나?

현재 모바일 페어링 대상은 macOS 데스크톱 앱 전용이다. CLI를 통해 실행 중인 Codex 작업은 모바일에서 직접 제어할 수 없다. 다만 원격 머신에서 작업해야 한다면 Codex 앱의 SSH 원격 연결(4장)이 대안이 될 수 있다 — 앱이 SSH로 원격 호스트에 붙어 그 위에서 thread를 실행하는 방식이다.

Q. 원격 Linux 서버나 devbox에서도 Codex를 쓸 수 있나?

쓸 수 있다. Codex 앱의 'SSH' 탭에서 ~/.ssh/config에 정의된 호스트를 추가하면, 원격 머신의 파일과 셸을 대상으로 Codex thread를 실행할 수 있다. 원격 호스트의 PATH에 codex 명령이 설치되어 있어야 한다. SSH 원격 연결과 Hooks는 모든 플랜에서 제공된다. 다만 Codex 앱 자체는 아직 macOS 전용이다. 자세한 절차는 4장을 참고하자.

도입 결정 매트릭스

상황	모바일 Codex 적합 여부
macOS에서 Codex를 이미 사용 중이며 이동 중 모니터링이 필요하다	적합
장시간 비동기 작업(마이그레이션, 대규모 리팩토링)을 위임하고 싶다	적합
원격 devbox나 Linux 서버에서 코드를 실행해야 한다	적합 — SSH 원격 연결(4장), 모든 플랜 제공
승인 요청 알림을 받고 필요할 때만 개입하는 워크플로가 필요하다	적합
실시간 인라인 코드 편집이 주 목적이다	비적합 — Cursor나 IDE 사용
Windows 환경이 주 개발 머신이다	보류 — Windows 지원 출시 후 재평가
GitHub 저장소 기반 모바일 에이전트가 필요하다	비적합 — GitHub Copilot 모바일 검토
프로덕션 긴급 롤백을 모바일에서 처리해야 한다	주의 요망 — 실수 위험, 가급적 데스크톱 권장

마무리하며: 모바일 Codex는 어떤 도구인가

한 줄로 정리하면 모바일 Codex는 "이동 중에도 코딩하는 도구"가 아니라, "어디서든 에이전트를 확인하고 결정해 주는 도구"다. Mac에서 이미 Codex를 사용 중이라면 프리뷰를 시도해 볼 만하다. 추가 비용 없이도 "이동 중 작업 위임과 결과 확인" 흐름이 자신의 워크플로에 맞는지 직접 검증할 수 있다.

여기에 4장의 SSH 원격 연결과 다른 기기 제어까지 더하면, "폰 → Mac → 원격 서버"로 이어지는 다단계 작업 흐름이 완성된다. 모바일 제어는 프리뷰지만 SSH 원격 연결은 이미 모든 플랜에 정식 제공된다는 점에서, 원격 개발 환경을 쓰는 개발자에게는 지금 당장 실무 가치가 있다.

조금 더 큰 그림에서 보면, OpenAI는 Greg Brockman이 돌아온 뒤 ChatGPT·Codex·Developer API를 하나의 에이전트 플랫폼으로 묶어가고 있다고 techtimes가 보도했다(2026-05-16). 모바일 Codex는 그 통합이 사용자 손에 처음 닿는 지점이다.

참고자료

이 글의 정보는 2026-05-25 기준이다. 모바일 제어는 프리뷰 단계로 기능·접근 정책이 변경될 수 있으며, SSH 원격 연결의 플랜 조건과 가격은 공식 Remote connections 문서와 OpenAI 공식 pricing에서 직접 확인하는 것이 정확하다.

Antigravity CLI(agy)로 넘어가는 기초 사용법과 마이그레이션 : Gemini CLI 종료(2026년 6월 18일)

갓대희 — Mon, 25 May 2026 18:23:19 +0900

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

Antigravity 시리즈

1편: 설치·입문 튜토리얼 2편: IDE 복구 가이드 3편: CLI 기초 사용 & alias (현재 글)

Antigravity CLI를 설치는 했는데, 막상 터미널을 열면 "그래서 뭘 입력하지?" 싶은 순간이 온다.

명령어 이름부터 antigravity가 아니라 agy라 한 번 막히고, 옵션은 많아 보이는데 정작 매일 쓰는 건 두세 개뿐이다.

그래서 이번 글은 네 가지를 차례로 짚는다.

먼저 Gemini CLI가 왜 종료되는지 배경을 짧게 정리하고,

agy 기초 사용 문법,

나만의 alias(별칭) 세팅,

그리고 넘어온 분을 위한 마이그레이션까지다.

Gemini CLI에서 막 넘어온 분도, Antigravity CLI가 처음인 분도 이 글 하나로 바로 시작할 수 있게 하는 것이 목표다.

설치 과정은 1편 6섹션 — Antigravity CLI 설치 및 첫 사용에서 이미 다뤘으니, 사용법은 "설치한 다음"부터 시작한다.

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

agy: 터미널에서 Antigravity CLI를 실행하는 실제 명령어 이름. antigravity가 아니다.
대화형 세션(interactive session): agy만 입력하면 열리는, 자연어로 계속 주고받는 채팅형 모드.
플래그(flag): 명령 뒤에 붙여 동작을 바꾸는 옵션. 보통 -c(짧은 형) 또는 --continue(긴 형) 형태다.
alias(별칭): 길고 자주 쓰는 명령을 짧은 이름으로 등록해 두는 셸 기능. 예: ag → agy.
MCP(Model Context Protocol): AI 에이전트가 외부 도구·서비스와 연결하는 표준 프로토콜.
~/.zshrc: zsh 셸을 열 때마다 자동으로 읽는 설정 파일. alias·환경변수를 여기에 적어 둔다.(bash라면 ~/.bashrc)

Gemini CLI 종료, 그리고 Antigravity CLI
설치 다음에 할 것
기초 사용법 — 자주 쓰는 명령어
권한과 안전 — --dangerously-skip-permissions 이해하기
나만의 alias 세팅
안전하게 첫 작업 시켜보기
Gemini CLI에서 넘어오는 마이그레이션 4단계
자주 묻는 질문 (FAQ)

1. Gemini CLI 종료, 그리고 Antigravity CLI

Antigravity CLI(agy)가 왜 갑자기 "넘어가야 하는" 도구가 됐는지부터 짧게 짚고 가자.

처음 쓰는 분은 배경만 알고 넘어가면 되고, Gemini CLI를 쓰던 분에게는 이 절이 전환 판단의 근거가 된다.

종료 일정과 영향 대상

2026년 5월 19일(Google I/O 2026 당일), Google은 개발자 블로그를 통해 Gemini CLI를 Antigravity CLI로 전환한다고 발표했다. 종료 일정은 딱 한 줄이다.

On June 18, 2026, Gemini CLI and Gemini Code Assist IDE extensions will stop serving requests.

(2026년 6월 18일부터 Gemini CLI와 Gemini Code Assist IDE 확장이 요청 처리를 중단한다.)

공지(5/19)에서 종료(6/18)까지 약 30일로, 전환 기간이 짧은 편이다. 영향을 받는 대상과 그렇지 않은 대상을 먼저 구분해 두자.

구분	6월 18일 이후
Google AI Pro / AI Ultra (개인)	요청 처리 종료
Gemini Code Assist for individuals (무료)	요청 처리 종료
Gemini Code Assist for GitHub (무료/개인)	신규 설치 불가 후 수 주 내 종료
Standard / Enterprise 라이선스	기존 접근 유지 — 변경 없음

개인·무료 사용자가 먼저 영향을 받고, Enterprise는 그대로 유지된다.

Antigravity CLI 얼리 액세스도 Enterprise에 먼저 제공됐다.

왜 논란이 됐나 (오픈소스 → 클로즈드소스)

논란의 핵심은 라이선스다.

Gemini CLI는 Apache 2.0 오픈소스(TypeScript)였지만, Antigravity CLI는 공개 소스 저장소가 확인되지 않는다 — The Register는 "Antigravity CLI GitHub 페이지에는 체인지로그·README·GIF 파일만 있다"고 전했다.

커뮤니티는 GitHub Issue #27304로 오픈소스 정신의 계승을 요청했으나, 2026-05-22 기준 낮은 우선순위(priority/p3)로 답변 없이 열려 있다.

유료·Enterprise는 유지되는데 무료·개인 사용자만 즉시 전환을 요구받는 구도라 형평성 비판도 나왔다.

무엇이 달라졌나

달라진 점 (공식 발표 기준)

언어: Node.js(TypeScript) → Go 재작성. 메모리 사용량이 낮고 시작 속도가 빠른 것이 특징으로 꼽힌다.
아키텍처: 비동기 멀티에이전트. 대규모 리팩터·리서치가 백그라운드 서브에이전트로 분리돼, 기다리는 동안에도 다음 명령을 입력할 수 있다.
명령어: agy (← antigravity 아님).
확장: Extensions → Plugins로 개명, Agent Skills·Hooks·Subagents 지원.
Antigravity 2.0 데스크톱 앱과 동일한 에이전트 하네스(에이전트 실행 환경을 묶는 런타임)를 공유한다.

아직 초기 버전이다.
Google도 "처음부터 1:1 기능 동등성은 없다"고 밝혔다.
예를 들어 커스텀 테마는 플러그인 임포트 때 빠지고, gemini skills 같은 스킬 관리 명령은 아직 동등한 것이 없다.
아키텍처는 매력적이지만, 핵심 작업이라면 기대치를 조금 낮춰 잡고 중요한 환경에서는 충분히 검증한 뒤 옮기는 편이 안전하다.

2. 설치 다음에 할 것

설치가 끝났다면 가장 먼저 두 가지만 확인하고 넘어가자.

# 1) 설치·버전 확인
agy --version

# 2) 그냥 실행 → 대화형 세션이 열리면 준비 끝
agy

agy를 처음 실행하면 곧바로 작업이 시작되는 게 아니라, 색상 테마를 고르는 환영 화면이 먼저 나올 수 있다.

테마를 고르고 나면 자연어로 지시를 입력할 수 있는 대화형 세션이 열린다. 여기까지 됐다면 다음 절로 바로 넘어가도 좋다.

아직 설치 전이라면?
설치 명령과 OS별 절차는 1편 §6과 공식 CLI 시작 문서를 참고하자. 이 글은 설치 이후의 "사용법"에 집중한다.

3. 기초 사용법 — 자주 쓰는 명령어

Antigravity CLI는 크게 두 가지 방식으로 쓴다.

대화형(채팅처럼 주고받기)과 비대화형(명령 한 번에 결과만 받기)이다.

3.1 대화형으로 시작하기

가장 기본은 옵션 없이 agy 한 줄이다. 세션이 열리면 "이 파일에 유닛 테스트를 추가해줘"처럼 자연어로 자유롭게 지시한다.

# 대화형 세션 시작
agy

# 첫 프롬프트를 미리 주고, 그 뒤로 대화를 이어가기
agy -i "이 프로젝트 구조부터 설명해줘"

ex)

3.2 비대화형 — 한 번에 결과만

대화창을 열지 않고 프롬프트 하나만 던져 결과를 받고 싶을 때는 -p(또는 --print)를 쓴다. 스크립트나 빠른 단발 작업에 어울린다.

# 프롬프트 하나만 실행하고 응답을 출력
agy -p "이 디렉터리에서 가장 큰 파일 3개를 알려줘"

3.3 대화 이어가기

앞서 하던 작업을 다시 이어가고 싶을 때 쓰는 두 가지다. 최근 대화 하나만 빠르게 이어갈 거라면 -c, 여러 대화 중 특정 하나를 골라 재개할 거라면 --conversation이다.

# 가장 최근 대화를 이어서 시작
agy -c

# 특정 대화를 ID로 지정해 재개
agy --conversation <대화ID>

ex) agy -c

ex) agy로 세션을 활성화한 후 /resume > 원하는 세션을 선택하여 원하는 대화를 이어 갈 수도 있다.

3.4 명령어 요약표

아래는 agy --help로 확인한 항목 중 자주 쓰는 것들이다(직접 확인: agy 1.0.0, 2026-05-25). 전부 외울 필요는 없고, 처음엔 agy로 시작했다가 필요할 때 표에서 찾아 쓰면 된다.

명령 / 플래그	하는 일
`agy`	대화형 에이전트 세션을 연다.
`agy -p "..."` (`--print`/`--prompt`)	대화창 없이 프롬프트 하나만 실행하고 결과를 출력한다(비대화형).
`agy -i "..."` (`--prompt-interactive`)	첫 프롬프트를 주고, 그대로 대화형 세션을 이어간다.
`agy -c` (`--continue`)	가장 최근 대화를 이어서 시작한다.
`agy --conversation <ID>`	특정 대화를 ID로 지정해 재개한다.
`agy --add-dir <경로>`	작업 대상 디렉터리를 추가한다(반복 가능). 여러 폴더를 함께 다룰 때 쓴다.
`agy --sandbox`	터미널 동작을 제한하는 샌드박스 모드로 실행한다.
`agy update`	CLI를 최신 버전으로 갱신한다.
`agy plugin import gemini`	기존 Gemini CLI의 설정·확장을 Antigravity 플러그인으로 가져온다(7절 참고).
`agy changelog` / `agy help`	변경 내역(릴리스 노트) 확인 / 서브커맨드 도움말 확인.

전체 옵션은 언제든 agy --help로 확인할 수 있다. 버전이 올라가면 항목이 바뀔 수 있으니, 표와 다르면 agy --help를 기준으로 삼자.

3.5 이미지 생성하기

예전 Antigravity 1.0가 초창기 강력했다고 평가 받았고, 그리고 Hermes 등에서 매우? 인기 있는 기능 중 하나가 CLI에서 이미지 생성하는 기능이었다. Antigravity CLI 에서 이 기능이 가능하니 매우 잘 활용하지 않을까?

- 생성 결과

4. 권한과 안전 — `--dangerously-skip-permissions` 이해하기

alias를 만들기 전에, 잠깐 권한 이야기를 먼저 하고 가자. 다음 절에서 만들 별칭 중 일부가 바로 이 플래그를 쓰기 때문이다.

기본적으로 Antigravity CLI는 파일 수정이나 명령 실행처럼 영향이 큰 작업을 하기 전에 사용자에게 승인을 묻는다.

이 "물어보는 단계"를 통째로 끄는 옵션이 --dangerously-skip-permissions다.

--dangerously-skip-permissions는 "빠른 모드"가 아니다.
agy --help 설명 그대로, 이 플래그는 모든 도구 권한 요청을 묻지 않고 자동 승인한다(직접 확인: agy 1.0.0, 2026-05-25). 즉 에이전트가 파일을 고치거나 명령을 실행하기 전에 더 이상 확인을 받지 않는다.

편하지만, 그만큼 로컬 파일·실행 명령·네트워크 요청이 사용자 확인 없이 진행될 수 있다는 뜻이다. 중요한 코드베이스에서는 쓰지 않는 편이 좋다. 꼭 써야 한다면 평소 작업 폴더가 아니라 사용 후 버리는 임시 디렉터리나 격리된 환경에서, 의미를 알고 쓰자.

더 안전한 중간 단계: --sandbox
격리된 환경에서 시험만 해보고 싶다면 agy --sandbox로 터미널 동작을 제한한 채 실행할 수 있다. "권한을 다 열어두기"와 "매번 일일이 승인하기" 사이에서 한 단계 안전한 선택지로 기억해 두면 좋다.

정리하면, 기본은 권한을 묻는 agy 그대로 쓰고, --dangerously-skip-permissions는 위험을 이해한 격리 환경에서만 쓴다. 이 전제를 깔고 다음 절의 alias를 만든다.

5. 나만의 alias 세팅

매번 agy --continue --dangerously-skip-permissions처럼 긴 명령을 치는 건 번거롭다.

자주 쓰는 조합은 alias(별칭)로 짧게 줄여두면 입력이 한결 빨라진다. Codex CLI에서 cdd 같은 별칭을 만들어 쓰던 것과 같은 방식이다.

5.1 기본 별칭 세 개

이름은 외우기 쉽게 ag(기본), agd(d = dangerous), agr(r = resume)로 잡았다.

alias ag='agy'                                              # 기본 실행 (대화형, 권한 확인 그대로)
alias agd='agy --dangerously-skip-permissions'             # 권한 자동 승인 (격리/일회성 환경 전용)
alias agr='agy --continue --dangerously-skip-permissions'  # 최근 대화 이어서 + 권한 자동 승인

ex) 보통 요즘은 ai 에게 요청하면 다 등록 해 준다. (직접 설정 하실 분들은 다음 섹션을 확인 하면 된다.)

- 아직 권한 자동 승인 처리를 하지 않아 권한을 물어보는 모습

- 설정 완료

- cat ~/.zshrc

5.2 `~/.zshrc`에 등록하기

macOS·Linux의 zsh를 쓴다면 ~/.zshrc 파일 끝에 위 세 줄을 추가한다(bash라면 ~/.bashrc). 직접 편집기로 열어 붙여 넣어도 되고, 아래처럼 터미널에서 한 번에 추가해도 된다.

# ~/.zshrc 끝에 alias 블록 추가
cat >> ~/.zshrc <<'EOF'

# Antigravity CLI (agy) aliases
alias ag='agy'
alias agd='agy --dangerously-skip-permissions'
alias agr='agy --continue --dangerously-skip-permissions'
EOF

# 현재 셸에 즉시 반영
source ~/.zshrc

# 잘 등록됐는지 확인
type ag agd agr

type ag agd agr를 실행했을 때 각 별칭이 어떤 명령으로 풀리는지 출력되면 성공이다.

새 터미널 창을 열면 그때부터는 source 없이도 바로 쓸 수 있다.

참고: agy install 서브커맨드는 환경 경로와 셸 설정을 자동으로 구성해 준다(agy --help 기준). 다만 이건 PATH·기본 설정을 잡아주는 용도이고, 위처럼 개인 취향의 별칭은 ~/.zshrc에 직접 적어두는 쪽이 관리하기 편하다.

5.3 만든 별칭으로 실행하기

ag                 # = agy            (대화형 시작, 권한 확인)
agd                # = agy --continue --dangerously-skip-permissions
agr                #   (아까 하던 작업을, 격리 환경에서 빠르게 이어갈 때)

평소 작업은 ag로 충분하다. agd·agr는 "이건 망가져도 되는 폴더"라는 확신이 있을 때만 꺼내 쓰는 카드로 남겨두자.

6. 안전하게 첫 작업 시켜보기

가장 먼저 "읽기만 하는 작업"부터.
설치만 하고 막막하다면, 파일을 바꾸지 않는 질문부터 던져보자. 권한 승인 걱정 없이 에이전트가 어떻게 움직이는지 감을 잡을 수 있다.

아래 순서대로 하면 어렵지 않게 첫 작업을 끝낼 수 있다.

작업할 프로젝트 폴더로 이동한다.
ag(= agy)를 실행해 대화형 세션을 연다.
"이 프로젝트 구조를 설명해줘"처럼 읽기 위주 작업을 시킨다.
답이 나오면, 에이전트가 어떤 단계를 거쳤는지 살펴본다. 여기까지 되면 한 번 성공한 것이다.
익숙해지면 "이 함수에 주석을 달아줘"처럼 작은 수정 작업으로 넘어간다. 이때부터 권한 승인 프롬프트가 뜨므로, 내용을 확인하고 허용/거부를 누른다.

중요한 코드라면 작업 전에 git add -A && git commit으로 현재 상태를 저장(체크포인트)해 두면, 결과가 마음에 들지 않을 때 되돌리기 쉽다.

7. Gemini CLI에서 넘어오는 마이그레이션 4단계

Gemini CLI를 쓰던 분이라면 설정·스킬을 그대로 가져올 수 있다. 명령어 구조 자체는 거의 비슷하니, 핵심 절차만 간단히 정리한다.

사전 준비 — 설정 위치 확인 & 백업

먼저 Gemini CLI 설정이 어디에 있는지 확인하고 통째로 백업한다. 작업 중 실수가 있어도 이 백업으로 되돌릴 수 있다.

항목	macOS / Linux	Windows
글로벌 스킬	`~/.gemini/skills/`	`%USERPROFILE%\.gemini\skills\`
워크스페이스 스킬	`.gemini/skills/` (프로젝트 루트)	`.gemini\skills\` (프로젝트 루트)
글로벌 규칙	`~/.gemini/GEMINI.md`	`%USERPROFILE%\.gemini\GEMINI.md`
MCP 설정	`~/.gemini/settings.json`	`%USERPROFILE%\.gemini\settings.json`

# 1) 내 환경에 뭐가 있는지 먼저 확인 (macOS / Linux)
ls -la ~/.gemini/

# 2) 날짜를 붙여 통째로 백업
cp -r ~/.gemini ~/.gemini-backup-$(date +%Y%m%d)

출력에 안 보이는 항목은 원래 안 썼다는 뜻이니 마이그레이션 대상에서 빼면 된다. .gemini-backup-20260525 같은 폴더가 생기면 백업 성공이다.

4단계 요약

설치 — 1편 §6 절차를 따르고, 끝나면 agy --version으로 확인한다. 최초 실행 시 OAuth 인증이 진행된다.
설정·스킬 임포트 — agy plugin import gemini로 기존 Gemini CLI 설정·스킬을 가져온다.
실행한 뒤 평소 쓰던 작업 하나를 바로 돌려보면 무엇이 옮겨졌고 무엇이 빠졌는지 가장 빠르게 파악된다.
워크스페이스 스킬 이동 — 프로젝트별 .gemini/skills/를 .agents/skills/로 옮긴다(프로젝트마다 수동). 플러그인 임포트가 자동으로 처리하지 않는 부분이다. 이미 .agents/skills/가 있다면 디렉터리째 mv하지 말고 cp -R .gemini/skills/. .agents/skills/로 내용만 병합해야 폴더가 중첩되지 않는다.
MCP 설정 필드 — 원격 MCP 서버를 쓴다면 키 이름을 url → serverUrl로 바꾼다. 놓치면 오류 메시지 없이 무음으로 실패하니 주의한다.

// 원격 MCP 서버: 키 이름만 변경 (Antigravity 전용 mcp_config.json)
"mcpServers": { "my-server": { "url":       "http://localhost:3000" } }  // 변경 전 (Gemini CLI)
"mcpServers": { "my-server": { "serverUrl": "http://localhost:3000" } }  // 변경 후 (Antigravity CLI)

mcp_config.json 위치는 버전마다 달라질 수 있다(예: ~/.gemini/antigravity/ 등으로 보고됨). 헷갈리면 직접 찾으면 된다.

# mcp_config.json 위치 검색 (macOS / Linux)
find ~ -name "mcp_config.json" 2>/dev/null

CI 스크립트에서 gemini 바이너리를 직접 호출한다면 agy로 교체해야 하는데, 플래그·인증·종료 코드가 달라질 수 있으니 단순 치환은 피하고 하나씩 테스트한다. 더 깊은 절차와 정확한 경로는 공식 문서와 커뮤니티 마이그레이션 가이드를 agy --help와 대조해 확인하자.

막히면 여기부터

MCP 서버 무응답: 4단계의 url → serverUrl을 빠뜨렸는지부터 본다(오류 없이 조용히 실패).
인증 오류(Error calling 'initialize': EOF, macOS): 인증 캐시를 삭제 대신 백업 이동한 뒤 재인증하면 풀리는 사례가 보고된다. [UNVERIFIED] 정확한 경로는 공식 문서에서 확인한다.
SSH·CI 환경: 인증 흐름이 Gemini CLI와 달라 지연될 수 있다. 비대화형(API 키 등) 인증 방법을 공식 문서에서 확인하고, CI는 하나씩보다 한 번에 전환하는 편이 디버깅이 쉽다.
네트워크/VPN: *.googleapis.com 방화벽 허용을 확인하고, VPN을 잠시 끄거나 DNS를 1.1.1.1/8.8.8.8로 바꿔 시도한다.

8. 자주 묻는 질문 (FAQ)

Q. Gemini CLI는 언제 종료되나?

공식 발표 기준 2026년 6월 18일부터 Gemini CLI와 Gemini Code Assist IDE 확장이 요청 처리를 중단한다. 단, Standard·Enterprise 라이선스 조직은 접근이 유지된다.

Q. 지금 꼭 Antigravity CLI로 옮겨야 하나?

무료·Pro 사용자는 6월 18일 이후 선택지가 제한된다. 당장 옮기지 않더라도 설정 백업과 agy plugin import gemini 정도는 미리 해두면 안전하다. Enterprise 라이선스라면 기존 Gemini CLI를 계속 쓸 수 있다.

Q. 명령어가 antigravity가 아니라 agy인가?

그렇다. 터미널에서 실행하는 명령은 agy다. antigravity로 입력하면 동작하지 않으니 주의하자. 전체 옵션은 agy --help로 확인할 수 있다.

Q. agy -c와 agy --conversation은 무엇이 다른가?

-c(--continue)는 가장 최근 대화 하나를 자동으로 이어서 시작한다. --conversation <ID>는 특정 대화를 ID로 지정해 재개한다. 평소에는 -c가 빠르고, 여러 대화를 오갈 때만 --conversation을 쓰면 된다.

Q. --dangerously-skip-permissions는 언제 써도 되나?

모든 도구 권한 요청을 자동 승인하는 옵션이라, 중요한 코드베이스에서는 권하지 않는다. 사용 후 버리는 임시 디렉터리, 일회성 컨테이너처럼 망가져도 되는 격리 환경에서, 의미를 알고 쓰는 게 안전하다. 시험만 할 거라면 --sandbox를 먼저 고려하자.

Q. alias를 등록했는데 동작하지 않는다.

두 가지를 확인하자. ① ~/.zshrc에 추가한 뒤 source ~/.zshrc로 다시 읽었거나 터미널을 새로 열었는지. ② type ag로 별칭이 등록됐는지. 그래도 agy: command not found가 나오면 별칭 문제가 아니라 agy가 PATH에 없는 것이니, 설치 상태부터 점검한다(1편 §6 참고).

마무리

여기까지 따라왔다면 기본기는 거의 갖춰졌다. 정리하면:

배경: Gemini CLI는 6월 18일 종료, 후속은 Antigravity CLI(agy) — Go 재작성·비동기 멀티에이전트. Enterprise는 기존 유지.
기본: agy로 대화형, agy -p로 단발 실행, agy -c로 이어가기.
권한: 기본은 승인을 묻는 agy. --dangerously-skip-permissions는 격리 환경에서만, --sandbox는 안전한 중간 단계.
alias: ag/agd/agr를 ~/.zshrc에 등록해 빠르게. --resume이 아니라 --continue인 점만 기억하자.
마이그레이션: 백업 → agy plugin import gemini → 스킬 경로 이동 → MCP url→serverUrl.

처음엔 ag 하나로 충분하다. 자주 쓰다 보면 자기만의 조합이 생기는데, 그때마다 별칭으로 줄여두면 터미널 작업이 한결 가벼워진다.

참고자료

직접 테스트: agy --help, agy --version (agy 1.0.0, macOS, 2026-05-25)
Google Developers Blog: An important update — Transitioning Gemini CLI to Antigravity CLI (2026-05-19)
The Register: Bye-bye Gemini CLI (2026-05-20)
GitHub google-gemini/gemini-cli Issue #27304
Antigravity 공식 CLI 시작 문서
agentpedia.codes: Gemini CLI → Antigravity CLI 마이그레이션 가이드
갓대희 블로그: Antigravity 시리즈 1편 — 설치·입문 튜토리얼 (§6 CLI 설치)

작성일: 2026-05-21 (개정: 2026-05-25 — 종료 정리·CLI 기초·alias·마이그레이션으로 재구성)

대상 버전: Antigravity CLI 1.0 (agy 1.0.0 기준), Gemini CLI 종료 예정 2026-06-18

이 글의 명령어는 agy --help로 직접 확인했으나, 버전이 올라가면 옵션·경로가 달라질 수 있다. 적용 전 agy --help와 공식 문서로 최신 값을 확인하기 바란다.

Antigravity 2.0 마이그레이션(1.0에서 2.0으로) : 안티그래비티 2.0 업데이트 후 IDE가 안 켜지고 확장프로그램이 날아갔을 때 복구 방법

갓대희 — Fri, 22 May 2026 21:24:22 +0900

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

Antigravity 시리즈

1편: 설치·입문 튜토리얼 2편: IDE 복구 가이드 (현재 글)

Antigravity를 쓰다가 2.0으로 업데이트했더니 확장프로그램(extensions — 에디터에 추가 기능을 붙여 주는 플러그인)이 전부 사라졌거나, IDE 자체가 아예 실행되지 않는 문제를 겪은 분들이 꽤 많다. Google AI Developers Forum과 Hacker News에서도 동시에 여러 스레드가 올라올 만큼 흔한 사고였다.

이 글에서는 왜 이런 문제가 생겼는지 원인부터 짚고, macOS 기준 8단계 복구 가이드와 Windows PowerShell 복구 절차를 함께 정리한다. 마지막에는 이번에 함께 출시된 Antigravity CLI 1.0도 간단히 살펴본다.

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

Antigravity IDE: VS Code(비주얼 스튜디오 코드)를 기반으로 만든 코드 에디터. 파일을 열고, 작성하고, AI 도움을 받는 전통적인 개발 환경이다.
Antigravity 2.0 (데스크탑 앱): 에이전트 오케스트레이션 전용 앱. 쉽게 말해 여러 AI 에이전트를 동시에 시키고 결과를 관리하는 컨트롤 타워다.
확장프로그램 (Extensions): 에디터에 기능을 추가하는 플러그인 패키지. 예: 린터, 테마, Git 연동 도구.
CLI (Command Line Interface): 마우스 클릭 없이 터미널에 명령어를 입력해서 쓰는 도구.
숨김 폴더: 파일명이 점(.)으로 시작하는 폴더. macOS Finder에서 기본적으로 보이지 않는다.
데이터 디렉터리: 앱이 설정, 히스토리, 확장프로그램 정보를 저장하는 폴더.

왜 갑자기 확장프로그램이 사라졌을까?
Antigravity 2.0이 바꿔 놓은 것들
확장프로그램 복구 — macOS 8단계 가이드
Windows 복구 가이드
복구가 잘 됐는지 확인하는 방법
트러블슈팅 Q&A
핵심 정리

1. 왜 갑자기 확장프로그램이 사라졌을까?

2026년 5월 19일 Google I/O 2026에서 Google은 Antigravity 2.0을 공식 발표했다. 이 업데이트는 단순한 버전 업이 아니라 앱 구조 자체를 분리한 대규모 개편이었다.

문제의 핵심은 데이터 저장 위치가 바뀐 것이다.

기존 1.x에서는 모든 설정과 확장프로그램이 ~/.gemini/antigravity/ 폴더 안에 저장됐다.

그런데 2.0 업데이트 이후 Antigravity IDE는 ~/.gemini/antigravity-ide/라는 완전히 다른 폴더를 사용하기 시작했다. 두 앱이 데이터를 공유하지 않으니, 1.x에서 쌓아 놓은 확장프로그램 설정이 IDE 입장에서는 처음부터 없는 것처럼 보인다. 커뮤니티 논의에서도 이 자동 이전 미지원 문제가 가장 많이 언급됐다.

더 까다로운 상황도 있다. Antigravity 2.0과 Antigravity IDE를 동시에 설치하면 인스톨러끼리 충돌해서 IDE 바이너리 자체가 실행을 거부한다. 2.0을 지우더라도 이 충돌의 흔적이 남아 IDE가 정상화되지 않고, 결국 IDE를 깔끔히 재설치해야 하는데 그러면 또 기존 설정이 지워진다.

의외로 자주 막히는 부분이 바로 이 '이미 두 앱을 모두 설치한 상태'다. 이 경우 복구 순서를 정확히 지키지 않으면 같은 문제를 반복해서 겪게 된다.

2. Antigravity 2.0이 바꿔 놓은 것들

복구 방법을 이해하려면 2.0이 어떻게 구조를 나눴는지 먼저 파악하는 편이 낫다. 공식 발표에 따르면 Antigravity 2.0은 네 가지 구성 요소로 분리됐다.

구성 요소	역할	특징
Antigravity 2.0 데스크탑 앱	에이전트 오케스트레이션 전용	여러 에이전트 병렬 실행, 백그라운드 작업 예약
Antigravity IDE	코드 에디터 (VS Code 포크)	2025년 11월 출시, 전통적인 개발 환경
Antigravity CLI	터미널 전용 인터페이스	Go 언어로 새로 작성, `agy` 명령어로 실행
SDK	커스텀 에이전트 개발용	외부 개발자가 에이전트를 직접 만들 때 사용

표에서 핵심은 데스크탑 앱과 IDE가 완전히 다른 앱이라는 점이다. 데스크탑 앱은 에이전트를 병렬로 돌리는 컨트롤 타워이고, IDE는 코드를 직접 쓰고 편집하는 에디터다. 같은 이름처럼 보이지만 사용 목적이 다르다.

한편 2.0 데스크탑 앱은 Google AI Studio, Android, Firebase와의 네이티브 통합을 지원하고 음성 명령 기능도 추가됐다. Gemini 3.5 Flash 모델이 이 기능들을 구동한다.

이번 분리 구조는 실제 개발자 워크플로에 꽤 직접적인 영향을 준다. 기존에는 "Antigravity를 연다" 한 가지 선택지였다면, 이제는 코드를 직접 편집할 때는 IDE를, 여러 에이전트를 동시에 돌릴 때는 2.0 데스크탑 앱을 따로 열어야 한다. 처음에는 번거롭게 느껴지지만, 두 앱의 역할을 명확히 구분하면 각 도구를 더 적합한 상황에 맞게 쓸 수 있다.

3. 확장프로그램 복구 — macOS 8단계 가이드

!! 하기 절차를 따르지 않아도 최신 안티그래비티 IDE로 업데이트만 하면 이제 딸깍 한번으로 마이그레이션을 하게 해주는것 같다. (mac 기준, 5월 22일 기준)

업데이트 후 재시작하면 하기와 같이 마이그레이션 관련 팝업이 노출되고, "Migrate"버튼을 클릭하면 마이그레이션 된다.

혹시나 하여 이 스크립트도 작성해 두려고 한다.

cp -r ~/.antigravity/extensions ~/.antigravity-ide/; mkdir -p "/Users/gdh/Library/Application Support/Anti gravity IDE/User"; cp~/Library/Application\ Support/Antigravity/User/settings.json ~/Library/Application\ Support/Ant igravity\ IDE/User/; cp ~/Library/Application\ Support/Antigravity/User/keybindings.json ~/Library/Application\ Suppor t/Antigravity\ IDE/User/

혹여 상기 Migrate 팝업이 안뜨는 경우, 아래 방식으로도 가능하다.

( 업데이트를 해서 공식 제공하는 마이 그레이션을 활용하도록 하자 )

아래 순서를 정확히 따라야 한다. 특히 1~3단계의 백업과 앱 간 충돌 확인은 건너뛰면 이후 단계에서 예상치 못한 문제가 생긴다.

시작 전 주의: 이 가이드는 macOS 기준이다. Windows 사용자는 아래 '4. Windows 복구 가이드' 섹션을 참고한다. Linux에서는 ~/.config/antigravity(구)와 ~/.config/antigravity-ide(신) 경로가 macOS의 ~/.gemini/antigravity와 ~/.gemini/antigravity-ide에 각각 대응한다.

1단계: 현재 상태 확인

터미널(Terminal — macOS에 기본으로 설치된 명령줄 앱)을 열고 아래 명령을 실행한다.

ls -la ~/.gemini/

이 명령을 실행하면 홈 디렉터리의 .gemini 폴더 안에 있는 항목 목록이 출력된다.

antigravity, antigravity-ide, antigravity-backup 폴더가 어떻게 있는지 확인한다.

폴더 상태를 미리 파악해야 이후 단계에서 어떤 데이터를 옮겨야 하는지 판단할 수 있다.

ex) 나의 경우도 Antigravity 를 사용하고 있었기 때문에 다음과 같은 이력이 확인 된다.

2단계: Antigravity IDE 폴더 백업

복구 작업을 시작하기 전, 현재 Antigravity IDE 폴더를 반드시 백업한다. 작업 중 실수가 있어도 이 백업으로 원상 복구할 수 있다.

cp -r ~/.gemini/antigravity-ide ~/.gemini/antigravity-ide-backup-$(date +%Y%m%d)

이 명령은 antigravity-ide 폴더를 날짜가 붙은 이름(antigravity-ide-backup-20260520 형식)으로 복사한다. 처음이라면 그대로 복사해 실행하면 된다.

ex) 백업 예시

3단계: Antigravity 2.0 앱과의 충돌 확인

Applications 폴더에 Antigravity(2.0 데스크탑 앱)와 Antigravity IDE가 둘 다 설치되어 있는지 확인한다.

Finder에서 Applications 폴더를 열어 두 앱이 모두 있는지 본다.

두 앱이 모두 있다면: Antigravity 2.0 앱을 먼저 완전히 삭제해야 한다.

단순히 Trash에 버리는 것 만으로는 부족하다.

Applications 폴더에서 Antigravity(2.0) 아이콘을 오른쪽 클릭 → "Move to Trash" 후 Trash를 비운다.

이후 Antigravity IDE도 삭제하고 5단계에서 재설치한다.

두 앱 중 IDE만 있거나, 문제가 없었다면 이 단계를 넘어가도 된다.

4단계: 기존 1.x 데이터 폴더 확인

Finder에서 숨김 폴더를 보려면 단축키가 필요하다.

macOS는 점(.)으로 시작하는 폴더를 기본적으로 숨겨 두기 때문이다.

방법 A — Command+Shift+. (점) 단축키:

Finder를 열고 홈 폴더(/Users/{사용자이름}/)로 이동한다
키보드에서 Command + Shift + .(마침표)를 동시에 누른다
숨김 파일과 폴더가 회색으로 표시되어 보이기 시작한다
.gemini 폴더를 찾아 더블클릭해서 열면 antigravity 폴더가 보인다

방법 B — Command+Shift+G로 직접 경로 입력:

Finder에서 메뉴바의 "Go" → "Go to Folder..."를 선택한다 (또는 Command+Shift+G)
입력창에 ~/.gemini/antigravity를 입력하고 Enter를 누른다
바로 해당 폴더로 이동한다

처음이라면 방법 B가 더 빠르다. 경로를 직접 입력하면 숨김 여부와 관계없이 해당 폴더로 이동할 수 있다.

5단계: Antigravity IDE 재설치 (필요한 경우)

3단계에서 두 앱 동시 설치 충돌이 있었다면 IDE를 재설치해야 한다. antigravity.google 공식 사이트에서 최신 Antigravity IDE를 다운로드한다.

다운로드한 .dmg(디스크 이미지 — macOS 앱 설치용 패키지 파일) 파일을 열고 Antigravity IDE 아이콘을 Applications 폴더로 드래그한다. macOS가 파일 시스템 접근 권한과 네트워크 연결 권한을 요청하면 허용한다.

6단계: 확장프로그램 파일 복사

이제 핵심 단계다. 기존 1.x 데이터(~/.gemini/antigravity/)에서 IDE 폴더(~/.gemini/antigravity-ide/)로 확장프로그램 관련 파일을 복사하면 된다.

cp -r ~/.gemini/antigravity/extensions ~/.gemini/antigravity-ide/extensions

이 명령은 기존 antigravity 폴더 안의 extensions 디렉터리 전체를 IDE 폴더로 복사한다. 만약 antigravity 폴더에 settings.json 같은 개인 설정 파일도 있다면 아래 명령으로 추가 복사할 수 있다.

cp ~/.gemini/antigravity/settings.json ~/.gemini/antigravity-ide/settings.json

chat history(대화 기록)를 복구하고 싶다면 chat_history 폴더도 같은 방법으로 복사한다.

단, mcp_config.json은 복사하지 않는 편이 안전하다. MCP(Model Context Protocol — AI 모델이 외부 도구를 쓸 수 있게 해주는 설정) 설정은 IDE와 2.0 앱이 다른 형식을 사용하는 경우가 있어 충돌이 생길 수 있다.

7단계: Antigravity IDE 재실행

Antigravity IDE를 다시 실행한다. 이미 실행 중이라면 완전히 종료(Command+Q)한 뒤 다시 연다.

macOS 독(Dock — 화면 아래쪽에 앱 아이콘이 고정되어 있는 바)에서 Antigravity IDE 아이콘을 클릭하거나, Launchpad에서 찾아 실행한다.

4. Windows 복구 가이드

기본 원리는 macOS와 동일하다. 데이터 경로가 1.x용과 2.0 IDE용으로 나뉘어 설정이 자동 이전되지 않는 것이 문제다. 아래 경로 비교표를 확인한 뒤, 상황에 맞는 방법을 선택한다.

항목	macOS	Windows
1.x 설정 (구)	`~/.gemini/antigravity/`	`%APPDATA%\Antigravity\`
2.0 IDE 설정 (신)	`~/.gemini/antigravity-ide/`	`%APPDATA%\Antigravity IDE\`
1.x 확장프로그램 (구)	`~/.gemini/antigravity/extensions/`	`%USERPROFILE%\.antigravity\extensions\`
2.0 IDE 확장프로그램 (신)	`~/.gemini/antigravity-ide/extensions/`	`%USERPROFILE%\.antigravity-ide\extensions\`
인스톨러 충돌 파일	`/Applications/Antigravity.app/Contents/Resources/app.asar`	`%LOCALAPPDATA%\Programs\Antigravity\resources\app.asar`

위 경로는 Google AI Developers Forum에서 다수 사용자가 검증한 경로다. 설치 방식에 따라 위치가 달라질 수 있으니, 파일 탐색기에서 실제 존재 여부를 먼저 확인한다.

방법 A — app.asar 백업 (IDE가 실행조차 안 될 때)

2.0 인스톨러가 app.asar 파일을 덮어쓰면서 IDE 진입이 막히는 경우에 유효한 방법이다. PowerShell을 열고 아래 두 줄을 실행한다. 관리자 권한은 필요 없다.

cd "$env:LOCALAPPDATA\Programs\Antigravity\resources"
Rename-Item app.asar app.asar.bak

실행 후 Antigravity를 재시작하면 IDE가 복구된다.

나중에 2.0으로 되돌리고 싶으면 app.asar.bak을 app.asar으로 이름만 바꾸면 된다. Google AI Developers Forum에서 다수 사용자가 이 방법으로 복구에 성공했다.

방법 B — 설정·확장프로그램 마이그레이션 (PowerShell)

macOS 6단계에 해당하는 핵심 복구 단계다.

PowerShell에서 아래 명령을 순서대로 실행한다.

# 설정 파일 마이그레이션 (User 폴더 전체)
Copy-Item -Path "$env:APPDATA\Antigravity\User" `
          -Destination "$env:APPDATA\Antigravity IDE\User" `
          -Recurse -Force

# 확장프로그램 마이그레이션
Copy-Item -Path "$env:USERPROFILE\.antigravity\extensions" `
          -Destination "$env:USERPROFILE\.antigravity-ide\extensions" `
          -Recurse -Force

MAX_PATH 오류가 발생하는 경우: Windows는 경로 길이가 260자를 넘으면 복사가 실패할 수 있다. 이때는 심볼릭 링크(symbolic link — 원본 폴더를 가리키는 단축 경로)를 대신 만든다. 관리자 권한으로 CMD(명령 프롬프트)를 열어 아래 명령을 실행한다.

mklink /J "%USERPROFILE%\.antigravity-ide\extensions" "%USERPROFILE%\.antigravity\extensions"

심볼릭 링크를 사용하면 두 경로가 같은 폴더를 가리키므로, 이후 확장프로그램을 한 곳에서만 관리하면 된다.

숨김 폴더 표시 및 자동 업데이트 비활성화

파일 탐색기(File Explorer) 상단 메뉴에서 "보기 → 숨긴 항목" 체크박스를 켜면 .antigravity처럼 점으로 시작하는 폴더가 보인다. 주소창에 %APPDATA%\Antigravity를 직접 입력해도 바로 이동할 수 있다.

같은 문제가 반복되지 않으려면 자동 업데이트를 꺼 두는 것이 좋다. %APPDATA%\Antigravity IDE\User\settings.json을 열어 아래 항목을 추가한다.

"update.mode": "manual"

5. 복구가 잘 됐는지 확인하는 방법

IDE가 실행되면 확장프로그램 패널을 열어 상태를 확인한다. 일반적으로 왼쪽 사이드바의 네모 블록 아이콘(Extensions 뷰)을 클릭하면 된다.

확인 순서:

설치된 확장프로그램 목록이 이전과 동일하게 나타나는지 본다
"비호환(incompatible)" 또는 "업데이트 필요" 표시가 있는 확장은 하나씩 업데이트한다
업데이트 후 IDE를 재시작하고 확장을 하나씩 켜 보며 충돌 여부를 확인한다

모든 확장이 한 번에 다 살아나지 않을 수도 있다. 버전 호환성 문제로 일부 확장은 Antigravity IDE 최신 버전을 아직 지원하지 않기 때문이다. 이런 경우 해당 확장의 GitHub(깃허브 — 코드를 저장·공유하는 온라인 플랫폼) 저장소나 마켓플레이스 페이지에서 업데이트 일정을 확인한다.

처음에는 확장을 전부 켜는 것보다 핵심 확장 2~3개만 먼저 켜서 안정성을 확인하는 편이 낫다. 내 경험상 한꺼번에 다 켰다가 어떤 확장이 충돌을 일으키는지 파악하기 어려워지는 경우가 많았다.

확장을 활성화할 때는 언어 지원(예: Python, TypeScript 언어 서버)이나 Git 연동처럼 에디터의 기본 기능을 보완하는 확장을 먼저 켜는 쪽이 효율적이다. 테마, 아이콘 팩, 스니펫 등 보조적인 확장은 핵심 확장들이 안정적으로 작동하는 것을 확인한 뒤에 하나씩 추가한다.

6. 트러블슈팅 Q&A

복구 과정에서 자주 나오는 질문들을 모았다.

Q: ~/.gemini/antigravity 폴더 자체가 없어요.

A: 2.0 업데이트 과정에서 기존 데이터가 ~/.gemini/antigravity-backup으로 이동된 경우가 있다 (커뮤니티 보고). 1단계에서 ls -la ~/.gemini/ 명령으로 폴더 목록을 확인하고, antigravity-backup 폴더가 있으면 7단계 rsync 명령으로 복원한다. 의외로 이 경우가 많아서, 먼저 backup 폴더부터 확인하는 것이 시간을 아끼는 방법이다.

Q: 6단계에서 extensions 폴더가 없다고 나옵니다.

A: ~/.gemini/antigravity/ 안에 extensions 폴더가 없다면, 1.x에서 확장프로그램을 별도로 설치하지 않았거나, 경로명이 다를 수 있다. ls ~/.gemini/antigravity/로 실제 폴더 구조를 확인한 뒤, 다른 이름으로 된 폴더가 있는지 본다.

Q: Windows나 Linux에서는 어떻게 하나요?

A: Windows 전용 복구 절차는 본문 4. Windows 복구 가이드 섹션에 경로 비교표와 PowerShell 명령어가 정리되어 있다. Linux에서는 ~/.config/antigravity(구 1.x)와 ~/.config/antigravity-ide(신 2.0 IDE) 경로가 macOS의 ~/.gemini/antigravity와 ~/.gemini/antigravity-ide에 각각 대응한다. 명령어는 macOS와 동일한 cp, rsync를 그대로 쓸 수 있다.

Q: 재설치 후 IDE 설정이 전부 초기화됐어요.

A: 2단계에서 미리 백업(antigravity-ide-backup-YYYYMMDD 폴더)을 만들었다면 해당 폴더 안의 파일을 다시 복사해 복원할 수 있다. 백업을 안 했다면 6단계에서 ~/.gemini/antigravity/ 원본 데이터를 활용해 재복구한다.

Q: 확장프로그램이 "비호환" 표시만 나오고 활성화가 안 됩니다.

A: 해당 확장이 아직 Antigravity IDE 최신 버전을 공식 지원하지 않는 경우다. 확장 마켓플레이스에서 업데이트 버전이 있는지 확인하고, 없으면 해당 확장의 GitHub 이슈 탭에서 지원 예정 여부를 확인한다. 당장 필요하다면 호환되는 이전 버전의 IDE를 임시로 사용하는 방법도 있다.

Q: agy 명령이 설치 후에도 인식되지 않습니다.

A: 터미널을 닫았다가 다시 열어 보자. 설치 스크립트가 ~/.zshrc 또는 ~/.bash_profile에 PATH(경로: 터미널이 명령어를 찾는 디렉터리 목록)를 추가하지만, 현재 열린 터미널 세션에는 바로 반영되지 않는 경우가 있다. 재시작 후에도 안 된다면 echo $PATH로 Antigravity CLI 설치 경로(~/.local/bin 등)가 포함되어 있는지 확인한다.

7. 핵심 정리

Antigravity 2.0 업데이트 후 IDE 기능이 사라지는 문제는 앱 구조가 나뉘면서 데이터 저장 경로가 바뀐 것이 원인이다. ~/.gemini/antigravity/에 있던 설정이 ~/.gemini/antigravity-ide/로 자동 이전되지 않아서 발생한다.

복구의 핵심은 순서다. 실제로 3단계(충돌 확인)를 건너뛰었다가 같은 오류를 반복하는 경우가 많다. 이 단계만큼은 건너뛰지 말자:

백업 먼저 만든다
두 앱 충돌이 있으면 2.0 데스크탑 앱을 먼저 제거한다
그런 다음 기존 폴더 데이터를 IDE 폴더로 복사한다

Antigravity CLI 1.0은 Gemini CLI의 후속 도구로, 터미널에서 AI 코딩 작업을 처리하고 싶다면 6월 18일 Gemini CLI 지원 종료 전에 전환해 두는 것이 좋다.

독자 적용 체크리스트 — 아래 항목을 순서대로 확인해 보자

ls -la ~/.gemini/ 명령으로 현재 폴더 구조를 확인했는가?
복구 작업 전 ~/.gemini/antigravity-ide 폴더를 백업했는가?
Antigravity 2.0과 IDE를 동시에 설치한 상태라면 2.0을 먼저 삭제했는가?
Command+Shift+. 단축키로 숨김 폴더를 확인했는가? (또는 Command+Shift+G로 직접 경로 입력)
~/.gemini/antigravity/extensions를 ~/.gemini/antigravity-ide/extensions로 복사했는가?
IDE 재실행 후 확장프로그램 패널에서 설치 상태를 확인했는가?
Gemini CLI를 쓰고 있다면 2026년 6월 18일 이전에 Antigravity CLI로 전환 계획을 세웠는가?

참고 자료

위 방법으로 해결이 안 된다면, 2.0 자체를 구버전(1.23.2)으로 되돌리는 방법도 있다.

작성일: 2026-05-20

분석 대상 버전: Antigravity 2.0 (2026-05-19 Google I/O 2026 발표 기준), Antigravity CLI 1.0

이 글은 2026-05-20 기준으로 작성되었다. Antigravity 공식 마이그레이션 도구 출시 및 업데이트 이후 내용이 변경될 수 있다.

Antigravity 2.0 설치·입문(1) : 처음 시작하는 분들을 위한 Antigravity 2.0, IDE, CLI 설치 해보기(간단하게 구조·기능 살펴보기)

갓대희 — Fri, 22 May 2026 03:21:06 +0900

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

Antigravity 시리즈

1편: 설치·입문 튜토리얼(현재글)2편: IDE 복구 가이드

Antigravity 2.0이 2026년 5월 19일 Google I/O 2026에서 공식 발표됐다.

이 글은 Antigravity 2.0을 처음 접하는 분, 또는 1.x를 쓰다가 2.0으로 넘어온 분들을 위한 가이드를 작성할 예정이다.

앱 구조와 설치 방법, 핵심 기능 튜토리얼, 자주 마주치는 오류 해결까지 같이 살펴보자.

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

에이전트(Agent): 사용자 지시를 받아 코드 작성·파일 수정·테스트 실행까지 스스로 수행하는 AI 프로그램. 단순히 답을 돌려주는 챗봇과 달리 실제 액션을 수행한다.
오케스트레이션(Orchestration): 여러 에이전트를 동시에 실행하고 조율하는 것. 오케스트라의 지휘자처럼 각 에이전트에게 역할을 나눠주고 결과를 모은다.
CLI(Command Line Interface): 마우스 클릭 없이 터미널에 명령어를 직접 입력해서 쓰는 도구. 화면에 앱이 뜨지 않는다는 점이 GUI 앱과 다르다.
SDK(Software Development Kit): 개발자가 자신의 서비스 안에 특정 기능을 심을 때 쓰는 개발 도구 묶음. Antigravity SDK를 쓰면 에이전트 기능을 내 앱에 직접 내장할 수 있다.
에이전트 하네스(Agent Harness): 앱·CLI·SDK가 공통으로 쓰는 에이전트 실행 엔진. 어디서 실행하든 똑같은 방식으로 에이전트가 동작하도록 맞춰주는 공통 기반이다.
Artifacts: 에이전트가 작업을 수행하면서 생성하는 결과물 — 구현 계획서, 태스크 목록, 스크린샷 등. 에이전트가 한 일을 직접 코드를 읽지 않고 확인하는 수단이다.
WSL2(Windows Subsystem for Linux 2): Windows 안에서 Linux를 실행하는 기능. Antigravity가 Windows에서 격리된 터미널 환경(샌드박스)을 쓰기 위해 필수로 필요하다.
Gatekeeper: macOS가 신뢰할 수 없는 앱의 실행을 막는 보안 기능. 설치 직후 처음 실행할 때 경고창이 뜰 수 있다.
Pending Approvals(보류 중인 승인): 에이전트가 파일 수정이나 명령어 실행처럼 외부 액션이 필요할 때 사용자에게 허락을 요청하는 항목. Agent Manager 화면에서 확인하고 처리한다.

Antigravity 2.0이란 — 'agents first' 재설계
앱 구조 — 네 컴포넌트의 역할
Antigravity 1.x에서 2.0으로 업그레이드하는 방법
신규 설치 가이드 — macOS / Windows / Linux
Antigravity 1.x 대비 2.0 주요 변경사항 정리
Antigravity CLI 설치 및 첫 사용
핵심 기능 튜토리얼 1 — AI 코드 어시스턴트 사용법
핵심 기능 튜토리얼 2 — 에이전트(Agent) 모드
핵심 기능 튜토리얼 3 — Antigravity IDE 기본 사용법
자주 묻는 질문(FAQ) + 트러블슈팅
어떤 도구를 먼저 써야 할까 — 결정 매트릭스

1. Antigravity 2.0이란 — 'agents first' 재설계

1.1 이전 버전과의 차이점

Antigravity 1.x는 IDE(통합 개발 환경 — 코드 작성·실행·디버깅을 한 화면에서 하는 프로그램) 안에서 AI 어시스턴트가 하나씩 답변하는 구조였다. 2.0은 이 구조를 크게 바꿨다고 한다.

Google I/O 2026 공식 블로그에 따르면, Antigravity 2.0은 "에이전트 퍼스트 개발 플랫폼"으로 포지셔닝됐다고 소개하고 있다. "프롬프트에서 행동으로(from prompts to action)"가 핵심 슬로건이다.

실제로 어떻게 달라졌는지 살펴보자면,

1.x에서는 사용자가 질문하면 AI 하나가 답변을 돌려주는 방식이었다.

2.0에서는 매니저 에이전트가 작업을 쪼개고, 전문화된 여러 에이전트가 동시에 실행되며, 서로 결과를 검증한다.

쉽게 말해 혼자 일하던 AI 직원이 팀으로 바뀐 셈이다.

1.x 대비 2.0의 핵심 변화는 세 가지로 요약된다:

앱 구조: 단일 앱 → 데스크탑 앱 + CLI + SDK 컴포넌트 분리
사용량 방식: 일일 프롬프트 한도 → 컴퓨팅 기반 사용량으로 전환 (Sprint Quota 5시간 리셋 + Weekly Baseline Cap 이중 구조)
작업 방식: 코드 에디터를 직접 쓰는 IDE → 에디터가 빠진 에이전트 전용 앱

처음 2.0을 열었을 때 코드 에디터가 아닌 "에이전트 대시보드"가 나타나는 이유가 바로 이 세 번째 변화 때문이다. 낯설게 느껴지는 것이 정상이다.

1.2 Gemini 3.5 Flash가 엔진이다

Antigravity 2.0은 Gemini 3.5 Flash 모델로 구동된다.(물론 이후 업데이트가 됨에 따라 달라질 수 있다.)

"코딩·에이전틱 벤치마크에서 Gemini 3.1 Pro보다 우수하며 경쟁 프론티어 모델 대비 4배 빠르다"고 Google이 발표했다.

컨텍스트 윈도우는 약 1,048,576 토큰으로, 한 번의 대화에서 매우 긴 코드베이스도 참조할 수 있다. 다만 이 수치는 Google 발표 기준이며, 독립 벤치마크로 별도 검증된 자료는 아직 확인하지 못했다.

( 그리고 요즘 우리는 알것이다. 벤치마크 점수가 중요 하다기 보다는 이를 사용하는 하네스가 더 중요 하니 ... 그만큼 발전 중 이구나 정도로 이해하고 넘어가자. )

2. 앱 구조 — 네 컴포넌트의 역할

Antigravity는 이제 하나의 앱이 아니다.

2.0 데스크탑 앱, 코드 에디터인 Antigravity IDE, CLI, SDK — 네 갈래로 나뉜다.

각각 언제 쓰는지, 그리고 어떤 것이 별도 제품인지 먼저 알아두면, 뒤이어 나오는 설치 단계에서 "무엇을 받아야 하는지"를 헷갈리지 않는다.

2.1 네 컴포넌트 한눈에 보기

컴포넌트	주요 용도	대상 사용자
Antigravity 2.0 앱	멀티에이전트 오케스트레이션, 백그라운드 작업 예약	자동화·병렬 실행이 필요한 개발자
Antigravity IDE	일상적인 코드 작성·편집, 단일 에이전트 보조	VS Code(마이크로소프트의 코드 에디터)처럼 직접 코드를 보며 작업하는 개발자
Antigravity CLI	터미널에서 에이전트 즉시 실행, 앱 없이 가볍게 사용	터미널 친화적 개발자, SSH 원격 환경
Antigravity SDK	자신의 서비스에 에이전트 기능 삽입, CI/CD(코드 변경을 자동으로 빌드·테스트·배포하는 자동화) 연동	에이전트 기능을 제품에 내장하려는 개발자

2.2 Antigravity 2.0 데스크탑 앱

2.0 앱은 대화(Conversation)가 곧 작업 공간이 되는 구조다.

에이전트에게 요청을 입력하면 에이전트가 "Worked for Xm"(X분 동안 작업함) 로그를 남기고, 각 단계를 클릭해 펼치면 내부에서 어떤 생각과 명령을 실행했는지 순서대로 확인할 수 있다.

정해진 시간이나 주기에 작업이 자동으로 실행되도록 예약하는 Scheduled Tasks 기능도 있어서, 자리를 비운 사이에도 에이전트가 일을 처리하게 만들 수 있다.

새 대화를 시작할 때 선택하는 모델 목록은 2026년 5월 기준 다음 7가지다:

모델	특징	권장 용도
Gemini 3.5 Flash (High) ← 기본값	Fast, 쿼터 소모 낮음	일상 코딩, 빠른 반복 작업
Gemini 3.5 Flash (Medium)	Fast, 쿼터 소모 낮음	가벼운 작업
Gemini 3.1 Pro (High)	쿼터 소모 중-높음	복잡한 구현, 아키텍처 결정
Gemini 3.1 Pro (Low)	쿼터 소모 중간	품질과 비용의 균형
Claude Sonnet 4.6 (Thinking)	확장 사고, 쿼터 소모 중-높음	복잡한 버그 분석, 추론 필요 작업
Claude Opus 4.6 (Thinking)	확장 사고, 쿼터 소모 매우 높음(~4×)	최고 난이도 문제, 주 1~2회 사용 권장
GPT-OSS 120B (Medium)	오픈소스 GPT 계열	다양성 확보, 비교 실험

또한 실행 환경(Execution Environment)을 선택할 수 있다.

기본값은 Local(내 컴퓨터에서 실행)이고, New Worktree를 선택하면 현재 작업 브랜치에 영향 없이 격리된 git 워크트리(worktree — 쉽게 말해 원본을 건드리지 않는 임시 사본 작업 공간) 환경에서 에이전트가 작업한다. 메인 코드에 영향을 주지 않고 에이전트를 시험해볼 때 유용하다.

코드 한 줄을 고치는 단순 작업보다 "테스트 코드를 전부 작성하고, 빌드하고, 결과를 리포트해줘" 같은 여러 단계가 얽힌 작업에서 2.0 앱의 멀티에이전트 구조가 확실히 유용하다.

Antigravity 2.0은 하기 실제 설치 하는 과정에서 얘기하겠지만, Cowork와 Codex 앱과 동일한 컨셉을 가져 가려는 것 같다.

2.3 Antigravity IDE

지금의 Antigravity IDE는 2025년 11월 18일 출시된 원조 Antigravity가 이어진 제품이다.

출시 당시 이름은 그냥 "Antigravity"였고, 2.0 앱이 갈라져 나오면서 코드 에디터 쪽을 "IDE"로 구분해 부르게 됐다.

즉 IDE는 1.x 계보를 잇는 별도 제품이다. 다만 "1.x 계보"가 곧 "낡은 버전"이라는 뜻은 아니다. IDE도 2.0 출시에 맞춰 버전이 함께 올라가, 본 가이드 작성 시점 macOS에서는 IDE가 2.0대 버전을 달고 있다(직접 확인: IDE 2.0.2 / 2.0 앱 2.0.1, macOS, 2026-05-22).

VS Code의 코드를 그대로 가져와 Antigravity에 맞게 손본 에디터인데, 이렇게 기존 소프트웨어를 바탕으로 새로 만든 것을 '포크(fork)'라고 부른다. 그래서 VS Code를 쓰던 사람이라면 화면 구성이 거의 똑같게 느껴진다.

IDE는 개인 코딩 작업 공간이고 2.0 앱은 자율 에이전트 관리자로 구분된다.

IDE에는 코드 에디터가 들어 있고, AI는 코드 작성을 옆에서 돕는 역할에 집중한다.

IDE와 2.0 앱을 동시에 설치하면 충돌이 발생한다

Hacker News 커뮤니티와 Google AI Developers Forum에 보고된 실제 이슈다. 발표 직후(2026-05-19~20) 2.0 인스톨러가 기존 IDE와 같은 설치 위치를 덮어쓰면서, 업데이트 뒤 IDE가 정상 실행되지 않는다는 보고가 다수 있었다. [WARNING] 다만 이후 버전(앱·IDE 모두 2.0대)에서는 두 제품이 별도 경로로 공존하는 사례도 있다 — 실제로 본 가이드 작성 시점 macOS에서 IDE 2.0.2와 2.0 앱 2.0.1이 충돌 없이 함께 설치된 것을 확인했다(직접 테스트: macOS, 2026-05-22). 즉 충돌 여부는 버전·설치 순서에 따라 다를 수 있으므로, 둘 다 쓰려면 각각 따로 내려받아 설치 결과를 확인하는 편이 안전하다.

2.4 Antigravity CLI

CLI(Command Line Interface)는 터미널에서 명령어를 입력해서 쓰는 도구다.

앱이나 IDE를 굳이 열지 않아도 터미널 하나로 에이전트를 즉시 실행할 수 있다.

공식 블로그에 따르면 Go 언어로 새로 작성되어 빠르고 가볍다.

중요한 점은 CLI가 2.0 앱과 동일한 에이전트 하네스(harness)를 공유한다는 것이다.

즉, 터미널에서 실행한 에이전트나 앱에서 실행한 에이전트나 내부 엔진은 동일하다.

Gemini CLI를 사용하다가 Antigravity CLI로 마이그레이션하는 방법은 별도로 상세히 다루려고 한다.

2.5 Antigravity SDK

SDK는 개발자가 자신의 서비스나 내부 도구에 에이전트 기능을 직접 심을 때 사용한다.

MarkTechPost 보도에 따르면 "Google 자체 제품을 구동하는 에이전트 하네스에 프로그래밍 방식으로 접근"하게 해준다.

CI/CD 파이프라인에 에이전트를 통합하거나, 회사 내부 도구에 AI 기능을 삽입하는 데 쓰인다.

일반 입문자에게는 당장 필요하지 않은 영역이지만, 언젠가 자신의 제품에 에이전트를 내장하려 할 때 주목하면 된다.

3. Antigravity 1.x에서 2.0으로 업그레이드하는 방법

기존 Antigravity 1.x 사용자라면 새로 설치 대신 업그레이드 경로를 사용하자.

( 신규 설치하시는 분들은 다음 섹션으로 바로 넘어가자. )

⚠️ 먼저 알아두자 — 2.0으로 업데이트하면 코드 에디터가 사라진다

1.x는 VS Code처럼 코드를 직접 열어 편집하는 IDE였다. 2.0 앱으로 업데이트하면 그 코드 에디터와 통합 터미널, 파일 탐색기가 사라지고 에이전트에게 작업을 맡기는 화면만 남는다. 이는 오류가 아니라 Google이 의도한 구조 변경으로 — 코드 에디터는 별도 제품 Antigravity IDE로 분리됐다. 다만 업데이트 화면에 이런 설명이 없어서, 적지 않은 1.x 사용자가 "내 에디터가 어디 갔지?"라며 당황했다 (Google AI Developers Forum).

코드를 직접 보며 편집하는 환경을 계속 쓰고 싶다면, antigravity.google/download에서 Antigravity IDE를 따로 설치하거나 이전 1.x 버전으로 되돌리면 된다.

3.1 업그레이드 절차

보통 우측 상단에 업데이트가 되어 있을 것 이고, Restart to Update 를 클릭해보자.

신규 버전의 Antigravity를 다운로드하여 설치 하라고 안내된다. "Explore the new Antigravity" 클릭.

나의 경우는 Google 계정을 통해 진행 할 예정이다. "Continue with Google" 클릭하여 진행. 이후 인증을 진행하자.

다시 Antigravity로 돌아가면 이후 단계가 진행되는데, 혹시 안되는 분들은 브라우저의 "Click here"를 클릭하여 진행하면된다.

안티그래비티로 돌아오면 다음과 같이 화면이 변경 되어있다.

계속 next를 클릭하여 테마를 선택하고, 원하는 플러그인들이 있으면 선택하여 주자. 그냥 next만 클릭해도 된다.

그리고 나의 경우는 마지막에 뜨는 화면에서 한번더 "Restart to Update"를 클릭하여 재시작해주었다.

다음과 같이 초기 화면이 보이면 된 것 이다.

이 화면을 보니 바로 감이 오시는 분들이 많을 것 이다.

Claude의 Cowork, Open AI의 Codex 앱을 결국 따라 가는 길을 택한 것 으로 보인다.

ex) Codex App의 모습

3.2 이 인상이 맞을까 — 커뮤니티·미디어 반응

위에서 "Codex 앱·Cowork를 따라가는 길로 보인다"고 적었는데, 같은 인상을 받은 사람이 나만은 아니었다. Antigravity 2.0이 발표된 2026년 5월 19일 직후, 해외 개발자 커뮤니티와 기술 매체에도 비슷한 관찰이 올라왔다.

발표 직후 커뮤니티·미디어 반응 (2026-05-19 ~ 21)

"Antigravity 2.0은 이제 독립형(standalone) 앱이며, 이는 Anthropic이 Claude Code로, OpenAI가 Codex로 한 것과 더 비슷하다." — 기술 매체 TelecomTalk 보도 (2026-05-20)
"Codex랑 많이 닮았다(Looks a lot like Codex!)" — Hacker News의 Antigravity 2.0 토론 댓글 (2026-05-19)
"Cursor도 이제 IDE가 아니다. 또 하나의 챗봇이 됐다." — Reddit r/google_antigravity 댓글 (2026-05-19)

정리하면, "코드 에디터(IDE)에서 독립형 에이전트 앱으로" 가는 흐름은 Antigravity만의 선택이 아니다. OpenAI의 Codex 앱, Anthropic의 Claude Code(코딩용)와 Cowork(문서·리서치 같은 지식 노동용)가 먼저 데스크탑 에이전트 앱이라는 형태를 만들었고, Antigravity 2.0도 같은 카테고리에 합류한 셈이다. 여러 매체는 이를 "수렴(convergence — 서로 다른 제품이 비슷한 형태로 모여드는 현상)"이라고 표현한다.

다만 두 가지는 짚고 넘어가자.

첫째, 커뮤니티에서 "Google이 베꼈다"는 식의 표현은 거의 없었다. 대부분 "비슷한 길", "수렴"이라는 중립적인 관찰이다. 그러니 이 글의 "따라간다"는 표현도 단정이 아니라 인상에 가깝다는 점을 감안하자.

둘째, 발표 직후 커뮤니티의 가장 큰 반응은 사실 이 비교가 아니라 "코드 에디터가 사라진 것"에 대한 불만이었다. Reddit에는 "agent-first 전환이 거대한 퇴보처럼 느껴진다"는 글이 수백 개의 공감(upvote)을 받았다. 기술 매체 InfoWorld도 Antigravity 2.0을, GitHub Copilot·Cursor·Claude Code·Codex가 일반화한 에이전틱 코딩 흐름에 Google이 내놓은 자체 답안으로 다뤘다(InfoWorld 보도).

입문자 입장에서는 이 대목을 이렇게 이해하면 충분하다. 2.0의 낯선 화면은 Antigravity 하나의 변덕이 아니라, AI 코딩 도구 업계 전체가 "사람이 에디터에서 코드를 직접 치는 도구"에서 "에이전트에게 작업을 맡기고 결과를 관제하는 앱"으로 옮겨가는 큰 흐름의 한 장면이다. 처음 그 화면이 당황스러웠다면, 낯선 게 정상이다 — 업계의 전환기를 정면으로 마주한 것뿐이다.

3.3 커스텀 에이전트 마이그레이션

1.x에서 커스텀 에이전트를 만들어 쓰던 사용자라면, 그 에이전트 설정은 대체로 2.0에서도 그대로 인식된다.

단, 1.x와 2.0은 데이터 디렉터리가 서로 분리돼 있어 에디터 설정·확장프로그램·대화 기록이 자동으로 옮겨지지 않을 수 있다. 이 경우 수동 복사가 필요한데, 업데이트 직후 설정이나 기록이 비어 있다면 이 섹션 상단의 안내 박스에서 짚은 복구 경로(별도 IDE 설치 또는 1편의 복구 절차)를 따른다.

Antigravity가 노란색 'Needs Review' 태그로 표시해주므로, 업그레이드 후 에이전트 목록을 한 번 훑어보면 된다.

4. 신규 설치 가이드 — macOS / Windows / Linux

이 섹션에서 다루는 것은 Antigravity 2.0 데스크탑 앱의 신규 설치다.

같은 시리즈의 다른 컴포넌트 설치는 위치가 다르니 먼저 짚어두자 — CLI(agy) 설치는 6장, 코드 에디터인 Antigravity IDE 설치는 9장에서 다룬다.

SDK는 자기 제품에 에이전트를 내장하려는 개발자용이라 입문 가이드 범위 밖이며, 설치·사용법은 공식 문서를 참고한다.

설치 전 알아두면 좋은 것

요금: 개인 Gmail 계정으로 로그인하면 무료 사용량(쿼터) 범위에서 쓸 수 있고, 더 많은 사용량이 필요하면 유료 플랜(AI Ultra 등)이 있다. 무료 범위와 요금은 변경될 수 있으니 정확한 내용은 공식 페이지에서 확인한다.

시스템 요구사항: 지원 OS와 최소 사양은 공식 다운로드 페이지에서 확인한다. 본 가이드는 macOS는 Apple Silicon 기준으로 진행하며(Intel Mac 지원 여부는 공식 페이지 확인), Windows는 WSL2가 필요하다(4.2 참조).

코드 전송·프라이버시: 에이전트 처리는 Google의 클라우드 모델을 거치므로 코드·대화 내용 일부가 전송될 수 있다. 데이터 수집 동의는 설정에서 끌 수 있고(opt-out, 6.2 참조), 민감한 코드에는 승인 강도가 높은 Secure 모드(4.4 참조)를 고려한다. 학습 활용 여부 등 상세는 공식 약관을 확인한다.

먼저 설치 흐름부터 따라가자. 순서는 대체로 다운로드 → OS별 설치 → 첫 실행 → 로그인 → 권한 허용 → 초기 설정 마법사다. 이 순서대로 확인하면 자기 화면이 글에서 설명하는 흐름과 맞게 진행되고 있는지 비교하기 쉽다.

4.1 macOS 설치 (Apple Silicon 기준)

1. antigravity.google/download에 접속하여 본인의 환경에 맞는(나의 경우는 macOS용 .dmg) 설치 파일을 다운로드한다.

2. 맥북의 경우 다운로드된 .dmg 파일을 열고, Antigravity 아이콘을 Applications 폴더로 드래그한다.

3. Applications 폴더에서 Antigravity를 실행한다.

4. Google 계정(개인 Gmail)으로 로그인한다. 기업용 Google Workspace 계정은 현재 지원되지 않는다.

5. 파일시스템 접근, 네트워크 연결, 손쉬운 사용(Accessibility) 권한 허용 창이 차례로 나타난다. 에이전트가 파일을 읽고 쓰기 위해 필요한 권한이므로 모두 허용한다.

( 이후 단계는 계속 next를 입력해도 되고, 이전 섹션인 [3. Antigravity 1.x에서 2.0으로 업그레이드하는 방법] 섹션에 작성해 두었다.)

4.2 Windows 설치

Windows에서는 설치 전에 WSL2(Windows Subsystem for Linux 2)가 먼저 준비돼 있어야 한다.

WSL2는 "Windows 안에서 Linux를 실행하는 기능"이며, Antigravity가 샌드박스(sandbox — 격리된 실행 환경) 터미널을 쓰기 위해 반드시 필요하다.

사전 준비: WSL2 설치

PowerShell(파워셸 — Windows에 기본으로 들어 있는 명령어 입력 창. macOS의 터미널과 같은 역할이다)을 관리자 권한으로 열고 다음 명령을 실행한다 (설치 가이드 기준):

wsl --install

이 명령을 실행하면 WSL2와 기본 Linux 배포판(Ubuntu)이 설치된다. 설치 완료 후 PC를 재시작한다.

본 설치 절차:

antigravity.google/download에서 Windows용 .exe(.exe — Windows 실행 파일 형식. 이 파일을 더블클릭하면 설치가 시작된다) 인스톨러를 다운로드한다.
인스톨러를 실행하기 전, 서명 정보가 "Google LLC"인지 확인한다.
인스톨러를 실행한다. 기본 설치 경로는 C:\Program Files\Google\Antigravity다.
Windows Defender 방화벽 허용 창이 나타나면 허용한다. Antigravity는 *.google.com과 *.googleapis.com 도메인에 접속한다.
설치 완료 후 설정 마법사가 자동으로 실행된다.

4.3 Linux 설치 (Debian/Ubuntu)

APT(Debian/Ubuntu 계열 Linux에서 소프트웨어를 설치·업데이트하는 도구. 명령어로 쓰는 설치 관리자라고 보면 된다) 저장소를 등록한 뒤 다음 명령으로 설치한다:

sudo apt install antigravity

Fedora/RHEL 계열 Linux는 APT 대신 DNF라는 도구를 쓴다. 역할은 APT와 같다:

sudo dnf install antigravity

설치 전에 APT 또는 DNF 저장소를 등록해야 한다.

공식 설치 가이드에 나오는 키링 설정 명령을 먼저 실행한다. 여러 파일을 하나로 묶어 압축한 파일(tarball, 보통 .tar.gz 형태)도 따로 제공되므로, 패키지 관리자를 쓰기 어려운 환경에서는 이 파일을 직접 풀어서 설치할 수 있다.

Linux에서는 설치 후 로그인 정보(OAuth 토큰)를 저장하기 위해 gnome-keyring 또는 libsecret이라는 패키지가 필요하다. 둘 다 비밀번호와 인증 정보를 안전하게 보관해 주는 Linux용 도구다. 로그인이 자꾸 풀린다면 이 패키지가 깔려 있는지부터 확인한다.

4.4 초기 설정 마법사 — 5단계

설치 완료 후 처음 실행하면 설정 마법사가 시작된다.

약 2~3분이 소요된다. "설정 가져오기", "테마 선택", "에이전트 모드 선택", "로그인", "워크스페이스 초기화" 화면이 순서대로 나타나면 정상 흐름으로 보면 된다.

1단계: 설정 가져오기

기존 VS Code, Cursor, Windsurf의 설정을 가져오거나 새로 시작할 수 있다. 처음이라면 "새로 시작"을 선택해도 무방하다.

2단계: 에디터 테마 선택

Light, Dark, High Contrast 중 하나를 선택한다.

3단계: 에이전트 동작 모드 선택 (중요)

에이전트가 얼마나 자율적으로 행동할지를 결정하는 핵심 설정이다.

모드	설명	권장 대상
Secure	최대 제한, 거의 모든 작업에서 승인 요청	매우 민감한 저장소
Review-driven	주요 작업마다 사용자 검토 요청	프로덕션 환경, 처음 사용자
Agent-driven	최대 자율 실행	자동화 실험 환경
Custom	세밀한 개별 설정	중급 이상

처음이라면 Review-driven 모드를 권장한다.

공식 코드랩은 이 방식을 "에이전트가 스스로 판단하되 사용자에게 승인을 요청하는, 균형 잡힌 방식"이라고 소개한다. 모드는 나중에 설정에서 언제든 바꿀 수 있다.

4단계: Google 계정 로그인

개인 Gmail 계정으로 로그인한다. 기업용 Workspace 계정은 현재 지원되지 않는다.

5단계: 이용약관 동의 및 워크스페이스 초기화

동의 후 2~3분간 워크스페이스가 초기화된다.

4.5 설치 후 실행 방법

설치가 끝났다면 이제 "어디서 어떻게 여는가"가 중요하다. 설치 직후 보게 되는 화면과 여닫는 방법을 잡고 넘어가자.

macOS: Applications 폴더, Launchpad, Spotlight 검색에서 Antigravity를 실행한다. 앱을 완전히 종료하려면 창 닫기만 하지 말고 Cmd+Q를 사용한다.

Windows: 시작 메뉴에서 Antigravity를 검색해 실행한다. 설치 중 바로가기를 만들었다면 바탕화면 아이콘으로 열 수 있다. 종료는 창 닫기 또는 Alt+F4를 사용한다.
Linux: 데스크탑 환경의 앱 런처에서 실행하거나, 패키지 설치 후 등록된 명령이 있다면 터미널에서 실행한다. CLI 작업은 터미널 세션을 종료하면 함께 끝난다.

처음 열리는 화면은 전통적인 코드 에디터가 아니라 대화 중심의 에이전트 작업 공간이다. 파일 탐색기나 에디터 창이 없고, 왼쪽 사이드바와 오른쪽 대화 영역으로 구성된다.

왼쪽 사이드바는 다음 다섯 구역으로 나뉜다:

New Conversation: 새 에이전트 대화를 시작한다. 클릭하면 프로젝트 선택기, 모델 선택기, 실행 환경 선택기(Local / New Worktree), 마이크(음성 입력)가 나타난다.
Conversation History: 지금까지 나눈 모든 대화 목록을 본다.
Scheduled Tasks(시계 아이콘): 에이전트가 정해진 시간에 자동으로 실행할 작업을 등록하고 관리한다. 사용법은 7장 7.4에서 다룬다.
Projects: 폴더 단위로 묶인 프로젝트 목록. 각 프로젝트 아래에 해당 프로젝트 관련 대화가 중첩된다.
Conversations: 프로젝트에 속하지 않은 독립 대화 목록. 최근 대화 순으로 나열된다.

입력창 힌트 "Ask anything, @ to mention, / for actions"는 세 가지 입력 방식을 알려준다. @는 파일·폴더를 대화에 첨부할 때, /는 Skills 및 내장 액션(예: /goal, /schedule)을 불러올 때 사용한다.

5. Antigravity 1.x 대비 2.0 주요 변경사항 정리

5.1 UI/UX 변화

2.0을 처음 실행하면 전통적인 파일 탐색기 대신 대화 중심의 에이전트 작업 공간이 열린다.

실제로 앱을 열면 왼쪽 사이드바에 다섯 가지 영역이 보인다:

New Conversation(새 대화 시작),

Conversation History(대화 기록),

Scheduled Tasks(예약 작업),

Projects(폴더 단위 프로젝트),

Conversations(독립 대화 목록).

하단에는 Settings가 있다.

새 대화를 시작할 때 선택 가능한 주요 항목:

프로젝트: 대화를 특정 프로젝트(폴더)와 연결한다. 에이전트가 해당 프로젝트 컨텍스트를 갖고 작업한다.
모델: Gemini 3.5 Flash(기본값)부터 Claude Opus 4.6, GPT-OSS 120B까지 7가지 모델 중 선택한다.
실행 환경: Local(내 컴퓨터) 또는 New Worktree(격리된 git 워크트리)를 선택한다.

음성 명령(마이크 아이콘)도 새로 추가됐다. 입력창 오른쪽의 마이크 버튼을 클릭하면 말로 에이전트에게 지시할 수 있다.

5.2 새로 생긴 기능

Google I/O 2026 공식 블로그 등 발표 자료를 종합하면, 2.0에서 새로 들어온 기능은 다음과 같다:

동적 서브에이전트 — 복잡한 작업을 병렬 워크플로로 분산 실행
백그라운드 작업 예약 — cron형 스케줄링으로 야간·주기 자동화
음성 명령
Google AI Studio, Android, Firebase 네이티브 연동

보안 기능으로는 개발자 키노트 블로그에서 크로스플랫폼 터미널 샌드박싱, 자격증명 마스킹, 강화된 Git 정책이 내장됐다고 밝혔다.

5.3 사라진 기능 / 구조 변화

항목	1.x	2.0
코드 에디터 내장	Antigravity 앱 자체가 코드 에디터(IDE형)	2.0 앱엔 에디터 없음 · 코드 에디터는 별도 제품 Antigravity IDE로 분리
사용량 기준	일일 프롬프트 한도	컴퓨팅 기반 사용량 (Sprint 5시간 리셋 + 주간 상한 이중 구조)
단일 에이전트 응답	주된 방식	멀티에이전트 오케스트레이션으로 전환
Gemini CLI	별도 존재	Antigravity CLI로 통합

2.0에서 코드 에디터가 없어진 것을 가장 당황스럽게 느끼는 사용자가 많다. 직접 코드를 보면서 편집해야 한다면, 별도 제품인 Antigravity IDE를 따로 설치해 쓰면 된다.

6. Antigravity CLI 설치 및 사용

CLI(Command Line Interface)는 터미널에 명령어를 입력해서 에이전트를 실행하는 도구이다.

그래픽 앱을 열지 않아도 된다는 것이 장점이다. Gemini CLI에서 넘어온 사용자라면 사용 방법이 크게 다르지 않아 금방 익숙해진다.

처음이라면 화면이 있는 2.0 앱으로 시작하는 편이 낫다.

에이전트 상태와 작업 결과를 눈으로 바로 확인할 수 있기 때문이다.

CLI는 터미널 작업이 익숙한 사람, 또는 SSH로 접속한 원격 서버에서 에이전트를 돌려야 하는 상황에서 특히 유용하다.

6.1 설치 명령

공식 CLI 문서에서 제공하는 설치 명령은 다음과 같다.

macOS 또는 Linux:

curl -fsSL https://antigravity.google/cli/install.sh | bash

이 명령은 Antigravity CLI 바이너리를 다운로드하고, agy 명령을 시스템에 등록한다. (agy는 터미널에서 Antigravity CLI를 실행하는 명령어 이름이다.) 설치가 완료되면 터미널을 닫았다가 다시 열어 변경사항을 적용한다.

Windows PowerShell:

irm https://antigravity.google/cli/install.ps1 | iex

Windows에서는 PowerShell을 관리자 권한으로 실행한 후 위 명령을 입력한다.

설치 시 함께 구성되는 항목은 다음 네 가지다: CLI 바이너리, 공유 에이전트 엔진, 시스템 키링(자격증명 저장), 설정 동기화(2.0 GUI와 양방향). 즉, CLI에서 변경한 설정이 2.0 앱에도 반영된다.

6.2 첫 실행 — 테마 선택과 로그인

설치 후 터미널에서 agy를 처음 실행하면, 이미 인증이 되어있는 경우가 아니라면 인정부터 진행해야 한다.

인증 후 해당 값을 복사하여 안티그래비티 CLI로 돌아와 프롬프트에 입력하여 주자.

이후 색상 테마(color scheme)를 고르는 환영 화면이 먼저 나타난다. GUI 앱과 달리 CLI도 자체 테마 설정을 받는다는 점이 처음에는 낯설 수 있다.

↑/↓로 8가지 테마(light, solarized light, colorblind-friendly light, dark, solarized dark, colorblind-friendly dark, tokyo night, terminal) 중 하나를 고르고 enter로 확정한다. 색약 사용자를 위한 colorblind-friendly 테마가 라이트·다크 양쪽에 준비돼 있는 점이 눈에 띈다.

테마를 고르면 약관 및 데이터 사용(Terms of Service & Data Use) 화면으로 넘어간다.

두 가지를 안내하는데, 그냥 넘기지 말고 한 번씩 읽어두는 편이 좋다.

⚠️ Google이 직접 밝히는 보안 위험

이 화면은 "AI 코딩 에이전트에는 자율 코드 실행, 데이터 유출(data exfiltration), 프롬프트 인젝션(prompt injection — 악의적 입력으로 에이전트를 조종하는 공격), 공급망(supply chain) 위험이 있을 수 있으니, 에이전트가 수행하는 모든 동작을 모니터링하고 검증하라"고 경고한다. 에이전트에게 작업을 통째로 맡기더라도 결과를 그대로 신뢰하지 말고 검토하라는 뜻이다. 실제로 동작을 검토·승인하는 방법은 8장에서 다룬다.

두 번째는 데이터 수집 동의다.

"상호작용(Interactions) 데이터를 Google이 수집·활용하도록 허용"하는 항목인데, 기본적으로 동의([x])에 체크되어 있다.

데이터 제공을 원치 않으면 enter로 체크를 해제한 뒤 진행하면 되고, 지금 켜두더라도 나중에 설정에서 언제든 끌 수 있다(opt-out).

화면 하단에는 약관(antigravity.google/terms)과 개인정보처리방침(policies.google.com/privacy) 링크가 함께 표시된다. [Done]을 선택하면 첫 설정이 끝난다.

설정을 마치면 Google 계정으로 인증한다.(이미 인증되어있다면, 바로 CLI 화면이 나타나게된다.)

로컬 환경: 기본 브라우저가 자동으로 열려 Google 로그인 화면이 나타난다.
SSH 원격 환경: 인증 URL이 터미널에 표시된다. 이 URL을 로컬 브라우저에 직접 입력해서 로그인한다.

로그아웃할 때는 아래 명령을 입력한다:

/logout

이 명령으로 세션이 종료되고 저장된 자격증명이 삭제된다.

6.3 시작하기

로그인 후 agy를 실행하면 대화형 에이전트 세션이 시작된다.

예를 들어 다음과 같이 입력할 수 있다:

agy

이제 자연어로 작업을 지시하면 된다. "이 파일에 유닛 테스트를 추가해줘" 또는 "버그를 찾아서 고쳐줘"처럼 자유롭게 입력한다.

Gemini CLI에서 넘어오는 경우, 명령어 구조는 거의 동일하다.

6.4 알아두면 좋은 명령 몇 가지

대화 세션 외에 터미널에서 바로 쓰는 명령도 있다. 아래는 agy --help로 확인한 것들이다(직접 확인: agy 1.0.0, 2026-05-22). 전부 외울 필요는 없고, 처음엔 agy로 시작했다가 필요할 때 찾아 쓰면 된다.

명령	설명
`agy -p "..."`	대화창을 열지 않고 프롬프트 하나를 던져 결과만 받는다(비대화형). 스크립트나 빠른 단발 작업에 쓴다.
`agy -c`	가장 최근 대화를 이어서 시작한다.
`agy --add-dir <경로>`	작업 대상 디렉터리를 추가한다(여러 번 반복 가능). 여러 폴더를 함께 다룰 때 쓴다.
`agy update`	CLI를 최신 버전으로 갱신한다.
`agy plugin import gemini`	기존 Gemini CLI의 설정·확장을 Antigravity 플러그인으로 가져온다(2편 참고).

주의: --dangerously-skip-permissions 플래그는 모든 권한 요청을 자동 승인한다.

에이전트가 파일 수정·명령 실행을 묻지 않고 진행하므로, 중요한 코드베이스에서는 쓰지 않는 것이 좋다.

격리된 환경에서 시험할 때는 --sandbox로 터미널 동작을 제한할 수 있다.

7. 핵심 기능 튜토리얼 1 — AI 코드 어시스턴트 사용법

7.1 대화 시작하기

Antigravity 2.0 앱 왼쪽 사이드바에서 "+ New Conversation"을 클릭한다.
상단의 프로젝트 선택기에서 작업할 프로젝트를 고른다. 프로젝트 없이 빠르게 시작하려면 그대로 둬도 된다.(나의 경우 기존에 작업중이던 프로젝트가 자동 선택되어있다.)
모델을 선택한다. 기본값은 Gemini 3.5 Flash (High)이며, 7가지 모델 중 작업에 맞게 고른다:
- 빠른 일상 작업: Gemini 3.5 Flash (High) — 쿼터 소모가 적고 속도가 빠르다.
- 복잡한 구현: Gemini 3.1 Pro (High) 또는 Claude Sonnet 4.6 (Thinking)
- 최고 난이도 추론: Claude Opus 4.6 (Thinking) — 쿼터 소모가 약 4배 많으므로 주 1~2회 이내 사용 권장
실행 환경을 선택한다. 기본값은 Local이다. 코드를 건드리기 전 안전하게 테스트하고 싶다면 New Worktree를 선택한다.
채팅 입력창에 작업 내용을 입력한다. 파일을 첨부하려면 @를 입력해 파일을 선택한다. Skills를 불러오려면 /를 입력한다.

처음이라면 Gemini 3.5 Flash (High) 모델과 Local 실행 환경으로 시작하는 편이 낫다. 가장 빠르게 반응하고 쿼터 소모도 적어서 감을 잡기 쉽다. 복잡한 작업에는 그다음 단계에서 더 강력한 모델로 바꿔본다.

ex) New Conversation > next-frontend 라는 프로젝트에 기본적으로 선택 되고, 대화창이 열린다.

- 모델은 다음과 같이 선택 가능하다.

- 기본적으로 Local 이 선택되어있는데, 여러 병렬작업을 할때 안전하게 작업하려면 Worktree 방식을 권장 하고 있다. (해당내용을 다루면 너무 복잡해질 수 있으니 넘어가려고 한다.)

7.2 코드 생성 에이전트의 작업 흐름

에이전트에게 코드 작성을 요청하면 대화 영역에 "Worked for Xm"(X분 동안 작업함) 배너가 나타난다.

이 배너 오른쪽의 > 화살표를 클릭하면 에이전트가 수행한 단계가 순서대로 펼쳐진다.

실제로 확인한 단계 순서는 다음과 같다:

Thought for Xs: 에이전트가 X초 동안 내부적으로 생각한 단계. 클릭하면 추론 과정이 펼쳐진다.
Ran [명령어]: 실제로 실행한 터미널 명령. 예: Ran git status, Ran git pull. 클릭하면 명령 출력 결과를 볼 수 있다.
Checked command status: 명령 결과를 확인하고 다음 단계를 결정한다.

이 "Thought → Ran → Thought → Ran" 패턴이 반복되며 에이전트가 작업을 완료한다. 단계가 예상과 다른 방향으로 가면 중간에 취소 버튼으로 중단할 수 있다.

에이전트가 "버그를 고쳤다"고 말할 때, 코드를 일일이 다 읽어보지 않아도 "Worked for Xm"을 펼쳐서 어떤 명령을 실행했고 결과가 어떠했는지 단계별로 추적할 수 있다. 에이전트의 행동이 투명하게 기록되는 핵심 UX다.

왼쪽이 "에이전트가 어떻게 작업했나"를 보여준다면, 대화 오른쪽 패널은 "무엇을 얼마나 바꿨나"를 한눈에 요약한다. 상단에 Overview와 Review 두 탭이 있다. (직접 확인: 2026-05-22)

Overview 탭은 이번 작업의 결과를 네 가지 숫자로 집계한다. 각 항목을 클릭하면 해당 내역으로 바로 이동한다.

항목	의미
Subagents	이 작업을 처리하려고 띄운 보조 에이전트(서브에이전트) 수. 복잡한 작업을 여러 갈래로 나눠 처리할 때 늘어난다.
Files Changed	에이전트가 생성·수정·삭제한 파일 수.
Artifacts	에이전트가 만든 산출물(구현 계획, 태스크 목록 등) 수.
Background Tasks	예약되거나 백그라운드로 실행 중인 작업 수.

옆의 Review 탭에서는 에이전트가 바꾼 내용(diff)을 모아 검토하고 승인하거나 되돌릴 수 있다.

예컨대 "git pull 부탁해"처럼 이미 최신 상태라 실제로 바뀐 것이 없는 작업에서는 네 항목이 모두 0으로 표시된다. 반대로 코드를 생성하거나 리팩터링하는 작업에서는 Files Changed와 Artifacts 숫자가 올라가고, 그 숫자를 눌러 바뀐 파일이나 산출물을 바로 확인할 수 있다. 이 패널은 앞서 나온 서브에이전트(8장), Artifacts, 백그라운드 작업을 한곳에 모아 보여주는 작업 요약 대시보드인 셈이다.

7.3 빌트인 명령어 · Skills · Rules 활용

채팅창에 /를 입력하면 두 종류의 항목이 드롭다운으로 나타난다.

빌트인 액션 4개 (<> 아이콘): 앱에 하드코딩된 시스템 명령어로, Customizations에 표시되지 않는다.

명령어	앱 표시 설명	용도
`/goal`	Run until the specified goal is completely finished	목표 설정 → 완료까지 자율 실행
`/schedule`	Run an instruction on a recurring schedule or as a one-time timer	반복·일회성 예약 작업 등록
`/browser`	Invoke a browser agent for web tasks	브라우저 에이전트 실행 (웹 조작)
`/grill-me`	Interview me to align on a plan	에이전트가 역질문으로 계획 정렬 후 실행

Skills(스킬): 사용자가 설치한 커스텀 작업 패키지다. 각 Skill은 SKILL.md 파일로 정의되며, 에이전트가 대화 맥락에 따라 자동으로 적용하거나 /skill-name으로 직접 호출할 수 있다. Settings > Customizations에서 관리하며, 직접 확인한 결과 현재 41개가 설치되어 있었다.

용어 참고: 공식 문서(docs/rules-workflows)에는 단계별 자동화 프로세스를 "Workflows"라는 별도 개념으로 설명하고 있다.

그러나 2.0 데스크탑 앱의 Customizations 패널에는 Workflows 탭이 없고 Skills로 통합 표기된다.

일부 서드파티 가이드가 "Workflows"라고 부르는 것이 이 때문이다.

Rules(규칙): 에이전트가 모든 대화에서 항상 따르는 마크다운 파일이다. "항상 한국어로 답변해줘", "커밋 메시지는 Conventional Commits 형식으로 작성해줘"처럼 프로젝트 전반에 적용할 규칙을 설정한다.

Global 범위(~/.gemini/GEMINI.md)와 Workspace 범위(.agent/rules/) 두 가지로 설정할 수 있다. (경로 이름에 gemini가 들어가는 것은 Antigravity CLI가 Gemini CLI 계보를 잇기 때문이다. 오타가 아니다.)

Customizations 전체 구조 (직접 확인: 2026-05-21):

Settings > Customizations 패널은 상단에 토큰 예산 사용량(Rules · Skills · MCP 별 소모 비율 표시)을 보여주고, 그 아래로 Skills 목록 → Rules 목록 → Installed MCP Servers → Build With Google Plugins 순서로 구성된다.

토큰 예산이 초과되면 대형 커스터마이제이션은 자동으로 잘린다는 경고도 표시된다.

7.4 Scheduled Tasks — 작업 예약하기

지금까지는 내가 요청할 때마다 에이전트가 한 번씩 움직였다.

Scheduled Tasks(예약 작업)는 여기서 한 걸음 더 나아가, 정해진 시각이나 주기에 에이전트가 스스로 작업을 실행하게 만든다.

매번 같은 프롬프트를 직접 치는 대신 "매일 아침 이걸 해둬"라고 한 번 등록해두는 셈이다.

등록하는 두 가지 방법:

왼쪽 사이드바의 Scheduled Tasks(시계 아이콘) 메뉴를 연다.

또는 채팅 입력창에 /schedule을 입력한 뒤, 할 일과 시점을 자연어로 적는다.

가장 간단한 예시는 다음과 같다. 채팅창에 이렇게 입력해보자:

/schedule 매일 아침 9시에 테스트를 실행하고, 업데이트가 필요한 의존성이 있으면 알려줘

이렇게 하면 매일 아침 9시에 에이전트가 알아서 테스트를 돌리고 결과를 정리해둔다.

주기는 "한 번만", "매일", "매주 월요일 오전 9시"처럼 자연어로 지정하면 된다.

또는 다음과 같이 직접 화면에 채워 넣고 설정 할 수도 있다.

예약한 작업의 진행 상태와 결과는 Agent Manager(에이전트 매니저)에서 확인한다.

완료된 작업은 어떤 명령을 실행했고 무엇이 바뀌었는지 7.2에서 본 작업 단계·Overview 패널과 똑같은 방식으로 추적할 수 있다.

예약 작업을 쓰기 전 알아둘 것

· 쿼터를 소모한다: 예약 작업도 결국 에이전트 실행이라 일반 사용량(쿼터)을 쓴다. 너무 자주 도는 작업을 여러 개 걸어두면 쿼터가 금방 소진될 수 있다.

· 실행 조건: 앱이 켜진 상태에서 백그라운드로 도는 것으로 보이나, 컴퓨터를 끈 동안에도 실행되는지는 환경에 따라 다를 수 있다. 중요한 자동화라면 실제로 한 번 테스트해 동작을 확인한다.

· 되돌리기 안전한 작업부터: 자동으로 반복되므로, 처음에는 "테스트 실행", "리포트 정리"처럼 여러 번 돌아도 문제없는 작업으로 시작하는 편이 안전하다.

8. 핵심 기능 튜토리얼 2 — 에이전트(Agent) 모드

8.1 에이전트가 무엇인지 다시 한번

에이전트는 단순히 답변을 돌려주는 AI가 아니다. 사용자가 "이 기능을 구현해줘"라고 말하면, 코드를 직접 작성하고, 파일을 저장하고, 터미널에서 빌드를 실행하고, 브라우저로 결과를 테스트하기까지 스스로 수행한다. 마치 주니어 개발자에게 작업을 맡기는 것과 비슷하다.

2.0의 멀티에이전트 모드에서는 매니저 에이전트가 작업을 쪼개서 여러 전문 에이전트에게 동시에 분배한다. 예를 들어 "결제 시스템을 리팩터링해줘"라는 요청을 받으면, 한 에이전트는 코드 분석을, 다른 에이전트는 테스트 작성을, 또 다른 에이전트는 문서 업데이트를 병렬로 수행한다.

8.2 권한 승인 흐름 — 에이전트가 물어볼 때

처음 에이전트 모드를 쓰면 "에이전트가 내 파일을 마음대로 바꾸는 건 아닐까?" 하는 걱정이 들 수 있다. 그래서 권한 승인 절차가 있다. 에이전트는 파일 수정이나 명령어 실행처럼 바깥에 영향을 주는 작업을 하기 전에 항상 사용자에게 먼저 묻는다.

에이전트가 승인을 요청하는 상황:

터미널 명령 실행 (예: npm install, python test.py)
파일 생성·수정·삭제
브라우저를 열어 접근하는 작업

공식 에이전트 설정 문서에 따르면 "각 에이전트가 무엇을 하고 있는지 실시간으로 확인하고, 변경 사항을 승인하거나 거부하며, 코드베이스에 대한 완전한 통제권을 유지할 수 있다."

화면에서는 이렇게 보인다.

터미널 명령 승인의 경우: 에이전트가 npm install express를 실행하려 하면 Agent Manager 화면 상단에 "Pending Approvals" 알림이 표시된다. 내용을 확인하고 허용(Allow) 또는 거부(Deny)를 클릭한다. 코드 인라인 수정 승인의 경우: IDE에서 코드 위에 인라인 지시(Cmd+I, 9.4 참조)를 내리면 에이전트가 변경 전후를 나란히 보여주는 diff(차이) 화면을 띄운다. 마음에 들면 accept(수락), 원하지 않으면 reject(거부)를 클릭한다.

비유하면 이렇다. 에이전트는 유능한 인턴이고, 사용자는 팀장이다. 인턴이 "이 파일을 삭제해도 될까요?"라고 먼저 물어보는 구조다. 팀장이 확인하지 않으면 인턴은 기다린다.

Review-driven 모드로 시작하면 이런 승인 요청이 자주 나타난다. 처음에는 번거롭게 느껴질 수 있지만, 에이전트가 어떤 방식으로 작업하는지 직접 보고 배우는 좋은 방법이기도 하다. 익숙해지면 Agent-driven 모드로 전환해 자율도를 높일 수 있다.

8.3 에이전트 중단 방법

에이전트가 예상과 다른 방향으로 가거나, 멈춰 있는 것 같을 때는 다음 순서로 조치한다:

Cancel/Stop 버튼 클릭: 트러블슈팅 가이드에 따르면 대부분의 경우(약 80%) 이것으로 중단된다.
터미널 확인: 멈춰 있는 프로세스가 있으면 종료한다. 터미널이 열려 있다면 Ctrl+C로 중단할 수 있다.
브라우저 창 닫기: 에이전트가 브라우저를 열어 작업 중이었다면 해당 창을 닫는다.
인터페이스 새로고침: 앱을 새로고침하거나 재시작한다.
새 대화 시작: 새로운 대화를 시작하면 토큰 카운트가 초기화된다.

9. 핵심 기능 튜토리얼 3 — Antigravity IDE 기본 사용법

Antigravity IDE는 직접 코드를 보면서 편집해야 할 때 사용하는 VS Code 기반 에디터다. 2.0 앱이 에이전트에게 작업을 맡기는 곳이라면, IDE는 개발자가 직접 손을 움직이는 공간이다.

9.1 Antigravity IDE 설치

IDE는 2.0 앱과 별개 제품이라 따로 내려받아야 한다. 특히 1.x를 쓰다가 2.0으로 업데이트하면서 코드 에디터가 사라졌다면, 여기서 IDE를 설치하면 익숙한 에디터 환경을 되찾을 수 있다(3장 상단 안내 박스 참조).

antigravity.google/download에서 Antigravity IDE 항목을 찾아 내려받는다.

(또는 다음 링크는 앵커 위치까지 잡아 준다. https://antigravity.google/download?_gl=1*1y8ejq9*_up*MQ..*_ga*MTIwNjQ3NzA0NC4xNzc5Mzg0NjU0*_ga_47V54ZJ3EV*czE3NzkzODQ2NTMkbzEkZzAkdDE3NzkzODQ2NjIkajUxJGwwJGgw#antigravity-ide)

2.0 데스크탑 앱과 같은 페이지에 별도 항목으로 제공된다.

(이 다운로드 페이지는 접속 시점에 따라 화면이 동적으로 구성되므로, 항목 이름·위치는 페이지에서 직접 확인한다.)

macOS: .dmg를 열어 앱을 Applications 폴더로 드래그한다. 첫 실행 시 Gatekeeper 보안 경고가 뜨면 "열기"를 누른다.

Windows: .exe 인스톨러를 실행한다. SmartScreen 경고가 나오면 "추가 정보 → 실행"을 선택한다. 기본 설치 경로는 C:\Program Files\Google\Antigravity다.
Linux: .deb 패키지 또는 압축 tarball(묶음 아카이브 파일)이 제공된다. 단, 2.0으로 제품이 분리된 이후의 정확한 설치 명령은 공식 다운로드 페이지에서 확인하는 것을 권장한다.

설치가 완료된 후 실행해보자.

ex) Antigravity 2.0 과 유사하다. 나의 경우는 "Continue with Google"을 클릭하여 진행하자.

- 인증 완료되면 Next를 선택해서 넘어간다.

- 기존 VS Code/Cursor 설정 가져오기

- 테마 선택

- 하기 표를 통해 확인 하자.

모드	설명	권장 대상
Secure	최대 제한, 거의 모든 작업에서 승인 요청	매우 민감한 저장소
Review-driven	주요 작업마다 사용자 검토 요청	프로덕션 환경, 처음 사용자
Agent-driven	최대 자율 실행	자동화 실험 환경
Custom	세밀한 개별 설정	중급 이상

처음이라면 Review-driven 모드를 권장한다.

- 에디터 설정 ( 한글화 하여 두었다. )

- 플러그 인 등 원하는 것들을 체크

- 보안 관련 내용도 확인 후 다음 클릭( 한글화 하여 캡쳐 )

9.2 프로젝트 열기

IDE를 실행한다.
File → Open Folder를 선택하여 작업할 프로젝트 폴더를 연다.
파일 탐색기와 코드 에디터가 VS Code와 동일한 배치로 열린다.

VS Code를 쓰던 개발자라면 별도 적응 기간 없이 바로 사용할 수 있다.

설정 마법사에서 VS Code 설정을 가져왔다면 테마, 키바인딩, 확장프로그램이 이미 적용된 상태다.

9.3 확장프로그램 설치

IDE 왼쪽 사이드바에서 Extensions(확장프로그램) 아이콘을 클릭한다.

VS Code 호환 확장프로그램을 검색하여 설치할 수 있다.

대부분의 VS Code 확장프로그램이 수정 없이 동작한다.

ex) codex 플러그인을 설치하는 예시

9.4 AI 에이전트 패널 활용

단축키	기능
`Cmd+L` (macOS)	AI 에이전트 패널 토글 (열고 닫기)
`Cmd+I` (macOS)	Command 호출 — 커서 위치에서 자연어로 코드·명령 생성(에디터·터미널 공통). 안 먹히면 아래 주의 박스 참조
`Cmd+E` (macOS)	IDE 안에서 Editor 뷰 ↔ Manager(미션 컨트롤) 뷰 전환 (별도 2.0 앱이 아니라 IDE 내부 뷰다)
Ctrl+`	터미널 토글
`Cmd+,` (macOS) / `Ctrl+,` (Windows)	설정 열기

인라인 AI 지시 사용법:

지시하고 싶은 코드 줄에 커서를 두거나, 바꾸고 싶은 코드를 선택한다.
Cmd+I를 눌러 Command 입력창을 연다.
지시를 입력한다. 예: "이 함수에 에러 핸들링을 추가해줘"
에이전트가 변경안을 제시하면, 마음에 들면 Accept(수락), 원하지 않으면 Reject(거부)를 선택한다.

⚠️ Cmd+I가 동작하지 않을 때

실제로 Cmd+I가 먹히지 않는 경우가 있다. 주된 원인은 두 가지다.

① 다른 명령으로 재바인딩됨 — keybindings.json에서 cmd+i가 인라인 Command가 아닌 다른 명령(예: 에이전트 모드 전환)으로 덮여 있으면 기대한 동작이 안 나온다.
② 기본값 충돌 — VS Code 내장 자동완성(Trigger Suggest)이 Cmd+I를 가로채 Command 입력창이 안 뜨는 사례가 보고됐다(Google AI Developers Forum).

확인 방법: Cmd+K를 누른 뒤 Cmd+S를 눌러 Keyboard Shortcuts(단축키) 화면을 열고, cmd+i로 검색해 어떤 명령에 묶여 있는지 직접 확인한다. 인라인 편집 단축키는 환경·버전에 따라 Cmd+K 등으로 다를 수 있으니, 이 화면에서 본인 설정을 기준으로 삼는 것이 가장 정확하다.

참고로 Cmd+L과 Cmd+I는 역할이 다르다. Cmd+L은 AI 에이전트 패널 자체를 열고 닫고, Cmd+I는 코드 위에서 AI에게 인라인으로 지시하는 단축키다.

ex) 특정 라인을 드래그하여 Cmd + L 을 입력하면 AI 에이전트 패널에 해당 코드 라인이 Context로 넘어가게 된다.

10. 자주 묻는 질문(FAQ) + 트러블슈팅

Q1. macOS에서 "앱이 손상됨" 오류가 나타난다

Gatekeeper가 앱 실행을 막는 경우다. 트러블슈팅 가이드에 따라 터미널에서 다음 명령을 실행한다:

xattr -cr /Applications/Antigravity.app

이 명령은 macOS가 앱에 붙인 격리(quarantine) 속성을 제거한다. 실행 후 앱을 다시 열면 된다.

Q2. Windows에서 인스톨러가 도중에 멈춘다

트러블슈팅 가이드에 따르면 관리자 권한으로 실행하면 약 60%의 경우 해결된다. VPN이나 프록시를 쓰고 있다면 설치하는 동안만 잠시 꺼둔다. 그래도 문제가 계속되면 C:\Antigravity 경로에 다시 설치해본다.

Q3. 로그인 화면이 반복해서 나타난다 (인증 루프)

저장된 인증 정보를 초기화하면 해결되는 경우가 많다. 가장 안전한 방법은 앱/CLI가 제공하는 로그아웃 기능이다 — CLI는 세션에서 /logout(6.2 참조), 앱은 설정에서 로그아웃한 뒤 다시 로그인한다. 이 방법이 저장된 자격증명을 깔끔하게 정리한다.

로그아웃으로도 안 되면 인증 파일을 직접 정리한다. [WARNING] 단, 정확한 파일명·경로는 버전에 따라 다를 수 있다(실제로 macOS에서는 아래 auth-tokens 대신 Cookies 등으로 저장된 사례를 확인했다). 아래 명령은 트러블슈팅 가이드 기준이며, 실행 전 해당 디렉터리에서 인증 관련 파일이 실제로 있는지 확인한다. OS에 맞는 명령을 실행한 후 앱을 재실행하고 다시 로그인한다.

macOS:

rm -rf ~/Library/Application\ Support/Antigravity/auth-tokens

Windows (PowerShell):

rd /s /q "%APPDATA%\Antigravity\auth-tokens"

Linux:

rm -rf ~/.config/Antigravity/auth-tokens

Q4. "계정 자격 없음(Account Not Eligible)" 오류가 나타난다

두 가지 원인이 흔하다:

기업용 계정 사용: Antigravity는 현재 개인 Gmail 계정만 지원한다. 회사 Google Workspace 계정으로는 사용할 수 없다.
지역 제한: 일부 국가에서는 서비스가 제한된다.

Linux에서 이 오류가 나타난다면 gnome-keyring 또는 libsecret 패키지가 설치돼 있는지 확인한다.

Q5. CLI와 IDE를 함께 쓰고 싶다

발표 직후에는 2.0 앱과 IDE를 함께 설치하면 인스톨러가 서로의 설치 위치를 덮어써 충돌한다는 보고가 많았다. 다만 이후 버전(앱·IDE 모두 2.0대)에서는 둘이 충돌 없이 공존하는 사례도 있다 — macOS에서 IDE 2.0.2와 앱 2.0.1이 함께 설치된 것을 직접 확인했다(2026-05-22). 충돌 여부가 버전에 따라 다를 수 있으니, 둘 다 쓰려면 각각 따로 내려받아 결과를 확인한다. 한편 Antigravity CLI(agy)는 2.0 앱과 같은 에이전트 하네스를 공유하므로, 터미널에서 CLI로 실행하다가 2.0 앱 GUI에서 이어 작업하는 식으로 충돌 없이 함께 쓸 수 있다.

Q6. 에이전트가 자꾸 rate limit(사용량 제한)에 걸린다

Antigravity 2.0의 사용량 제한은 이중(dual) 구조로 되어 있다. "5시간마다 초기화된다"는 말을 들어봤다면, 그건 절반만 맞는 설명이다.

한도 유형	설명	초기화 주기
Sprint Quota	단기 집중 사용 한도. 소진 시 쿨다운 후 다음 스프린트 창 시작	약 5시간마다 리셋
Weekly Baseline Cap	주간 총 사용량 상한. 이 한도가 소진되면 5시간 리셋도 작동하지 않음	주 1회 리셋

즉, Sprint Quota는 5시간마다 복구되지만, Weekly Baseline Cap을 다 소진하면 5시간을 기다려도 한도가 돌아오지 않는다. 집중적으로 사용한 주에 "5시간이 지났는데 왜 또 걸리지?"라는 현상이 나타나면 주간 한도 소진을 의심해야 한다.

"40% Capacity Bug" (커뮤니티 보고): 쿨다운 이후 스프린트 창이 재개될 때 이전보다 쿼터가 점점 더 적게 복구되는 현상이 보고되고 있다. 복구율이 첫 스프린트의 40% 수준에서 멈추는 사례가 있다. [UNVERIFIED] 공식 확인이 안 된 커뮤니티 보고 사항이므로, 경험하게 되면 앱을 완전히 재시작하거나 다음 날까지 기다려 보는 것이 권장된다.

실용적 대처법: 처음에는 에이전트 여러 개를 한꺼번에 돌리기보다 하나씩 순서대로 써 보는 편이 낫다. Claude Opus 4.6처럼 쿼터 소모가 큰 모델은 반드시 필요한 작업에만 쓰고, 일상적인 작업은 기본값인 Gemini 3.5 Flash (High)를 유지한다. AI Ultra 플랜은 Pro 플랜 대비 5배 높은 AI 사용 한도를 제공한다(TechCrunch 보도, 2026-05-19 기준 $100/월). 요금제는 변경될 수 있으므로 최신 정보는 공식 페이지에서 확인한다.

Q7. Linux에서 저장소 연결이 안 된다

APT 저장소 연결 실패 시 IPv4 강제 사용으로 해결되는 경우가 있다 (트러블슈팅 가이드 기준)

apt-get -o Acquire::ForceIPv4=true update

11. 어떤 도구를 먼저 써야 할까 — 결정 매트릭스

Antigravity 2.0의 네 컴포넌트 중 어떤 것을 먼저 시작해야 할지 헷갈리는 분을 위해 간단한 기준을 정리했다.

상황	권장 도구
처음 설치하고 AI 코딩 도구를 체험해보고 싶다	Antigravity 2.0 앱
VS Code처럼 직접 코드를 보면서 편집하고 싶다	Antigravity IDE (2.0 앱 미설치 권장)
터미널 작업이 편하고, SSH 서버에서도 써야 한다	Antigravity CLI (agy)
Gemini CLI를 쓰다가 이쪽으로 옮기는 중이다	Antigravity CLI
자신의 서비스에 에이전트를 내장하려 한다	Antigravity SDK
복잡한 프로젝트를 여러 에이전트가 동시에 처리하길 원한다	Antigravity 2.0 앱 (멀티에이전트 모드)

처음 시작하는 입문자에게는 2.0 앱 단독 설치 → Review-driven 모드 → 간단한 작업부터 지시 순서가 가장 자연스럽다. 에이전트가 무엇을 할지 먼저 계획을 보여주고, 사용자가 승인한 뒤 진행하므로 실수를 줄일 수 있다.

도구가 많다고 처음부터 전부 설치하려 하지 않는 편이 낫다. 발표 초기에는 2.0 앱과 IDE를 함께 설치할 때 충돌 보고가 있었으므로(버전에 따라 다를 수 있다), 하나에 익숙해진 후 필요에 따라 확장하는 방식이 안전하다.

독자 적용 체크리스트 — 오늘 바로 해볼 것

antigravity.google/download에서 2.0 앱 또는 CLI 중 하나를 선택해 설치해본다
초기 설정 마법사에서 Review-driven 모드를 선택해본다
에이전트에게 "이 파일의 버그를 찾아줘" 같은 작은 작업부터 지시해본다
Agent Manager의 Pending Approvals 화면에서 승인 흐름을 직접 경험해본다
CLI를 설치했다면 터미널에서 agy 명령을 실행해 첫 인증을 완료해본다

참고자료

작성일: 2026-05-21

분석 대상 버전: Antigravity 2.0 / Antigravity CLI 1.0 (2026-05-19 Google I/O 2026 발표 기준)

이 글은 2026-05-21 기준으로 작성되었다. Antigravity는 프리뷰 단계에 있어 기능·요금·인터페이스가 이후 변경될 수 있다. 최신 정보는 antigravity.google 공식 사이트에서 확인한다.

대형 코드베이스에서 Claude Code 제대로 쓰는 법 — 원리부터 실전까지

갓대희 — Thu, 21 May 2026 01:00:50 +0900

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

수십만? 수백만? 줄 규모의 코드베이스를 처음 받았을 때의 막막함은 누구나 알 것 이다.

(개인 프로젝트, 간단한 서비스를 처음부터 만들땐 비교적 문제가 없지만 복잡한 규모의 프로젝트를 다루기 시작하면 막상 막막한 분들이 많은 것 같다.)

어디서부터 손을 대야 할지 몰라 find 명령을 반복하거나, 팀 문서를 뒤지거나, 동료에게 물어보는 시간이 의외로 길다. Claude Code는 이 문제를 "에이전틱 검색(agentic search)"이라는 방식으로 풀어낸다.

이 글에서는 Claude Code가 대형 코드베이스를 탐색하는 원리, 컨텍스트 윈도우를 관리하는 전략, CLAUDE.md 파일 설계 방법, 그리고 실전 시나리오에서 바로 꺼내 쓸 수 있는 명령 패턴까지 정리한다.

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

Agentic Search: RAG 인덱스 없이 파일 시스템을 직접 탐색하며 필요한 것을 찾는 방식
Context Window(컨텍스트 윈도우): 모델이 한 번에 처리할 수 있는 최대 텍스트 크기
CLAUDE.md: 세션 시작 시 자동 로드되는 프로젝트 지침 파일
Harness(하네스): Claude Code가 대형 코드베이스를 다루기 위해 연결하는 도구 모음
Subagent(서브에이전트): 메인 세션과 분리된 별도 컨텍스트로 실행되는 탐색 전담 인스턴스
LSP: Language Server Protocol — 코드 편집기에 심볼 이동, 정의 찾기 같은 정밀 탐색 기능을 제공하는 표준 프로토콜
MCP: Model Context Protocol — Claude Code가 외부 서비스 및 도구와 연결하기 위한 프로토콜
Auto memory(자동 메모리): 세션 간 지식을 자동으로 축적하는 기능 (v2.1.59+)
/compact: 컨텍스트를 수동으로 압축하는 내장 슬래시 명령
DRI: 조직에서 Claude Code 설정을 단독으로 책임지도록 지정된 담당자 (Anthropic 공식 블로그가 제시한 최소 운영 단위)
에이전트 매니저(Agent Manager): Claude Code 생태계 운영을 전담하는 PM·엔지니어 혼합 직책

Claude Code란 무엇인가 — 대형 코드베이스에서의 핵심 문제
탐색 원리 — 에이전틱 검색과 하네스 구조
컨텍스트 윈도우 관리 — 토큰 한계를 넘어서는 전략
CLAUDE.md — 프로젝트 지침 설계와 계층 구조
낯선 코드베이스에서 시작하기 — 탐색 전략과 Plan Mode
실전 사용 시나리오 — 버그 수정, 리팩토링, 기능 탐색
제한사항과 흔한 실수 — 기대를 조정하는 법
조직 차원의 도입과 운영 — DRI, 에이전트 매니저, 검수 문화
트러블슈팅 Q&A

1. Claude Code란 무엇인가 — 대형 코드베이스에서의 핵심 문제

Claude Code는 터미널, VS Code, JetBrains IDE, 데스크탑 앱, 웹에서 모두 사용할 수 있는 AI 코딩 도구이다. 모든 환경에서 동일한 CLAUDE.md 파일, 설정, MCP 서버가 그대로 작동한다는 점이 특징이다.

대형 코드베이스에서 AI 도구가 가장 많이 실패하는 지점은 "컨텍스트 파악"이다. 코드베이스 전체를 한꺼번에 로드할 수 없으니, 어떤 파일을 어느 순서로 읽을지 결정하는 방식 자체가 결과의 질을 가른다.

전통적인 RAG 방식은 사전에 구축한 벡터 인덱스를 기반으로 관련 코드 조각을 검색한다.

문제는 타이밍이다. Anthropic 공식 블로그는 "개발자가 인덱스를 조회할 시점에 인덱스는 수 시간, 심지어 수 주 전의 코드베이스를 반영하고 있다"는 점을 지적한다.

빠르게 변하는 코드베이스에서 인덱스는 언제나 한 박자 늦다.

Claude Code는 이 문제를 다른 방식으로 접근한다. 인덱스 없이 파일 시스템을 직접 탐색하는 에이전틱 검색 방식을 채택한 것이다.

두 방식의 차이를 정리하면 다음과 같다.

구분	인덱스 기반 검색 (RAG)	에이전틱 검색 (Claude Code)
동작 방식	코드베이스 전체를 미리 임베딩해 인덱스로 만들고, 쿼리 시 관련 청크를 검색	인덱스 없이 그때그때 파일 시스템을 직접 탐색하고 grep으로 찾음
코드 최신성	인덱스가 수 시간~수 주 전 상태를 반영 — 조회 시점보다 한 박자 늦음	조회하는 시점의 실제 코드 상태를 그대로 반영
대규모 팀 확장성	수천 명이 커밋하면 임베딩 파이프라인이 따라가지 못해 실패할 수 있음	유지할 파이프라인이나 중앙 인덱스가 없어 이 실패 모드 자체를 피함

이 차이가 Anthropic 공식 블로그가 에이전틱 검색을 채택한 이유로 든 핵심이다 — 수천 명의 엔지니어가 새 코드를 커밋하는 환경에서는 유지해야 할 임베딩 파이프라인이 없다는 점 자체가 곧 안정성이 된다.

2. 탐색 원리 — 에이전틱 검색과 하네스 구조

에이전틱 검색: 인덱스 없이 파일을 찾는 방법

Claude Code의 탐색 방식은 숙련된 개발자가 낯선 코드베이스를 처음 분석할 때 하는 행동과 비슷하다.

Claude Code는 "파일 시스템을 탐색하고, 파일을 직접 읽고, grep으로 필요한 것을 정확히 찾고, 코드베이스 전반에 걸쳐 참조를 따라간다" — 이 모든 것을 별도의 인덱스 유지 없이 수행한다.

처음 맞닥뜨린 코드베이스에서는 넓게 훑은 다음 구체적인 곳으로 좁혀 들어가는 편이 훨씬 낫다. 에이전틱 검색이 그 흐름을 자연스럽게 따른다.

Claude Code 에이전틱 루프의 3단계

작업을 받으면 Claude Code는 세 단계를 반복한다

컨텍스트 수집(Gather Context) — 관련 파일과 참조를 파악한다
행동 실행(Take Action) — 코드를 편집하거나 명령을 실행한다
결과 검증(Verify Results) — 테스트 실행이나 타입 체크로 의도대로 동작하는지 확인한다

이 세 단계는 직선이 아니라 혼합되어 반복된다. 탐색 중에 편집이 일어나고, 편집 후 다시 탐색이 필요해지는 식이다.

내장 도구 5가지 카테고리

카테고리	주요 기능
파일 작업(File operations)	파일 읽기, 코드 편집, 신규 파일 생성, 이름 변경 및 재구성
검색(Search)	패턴으로 파일 찾기, regex로 내용 검색, 코드베이스 탐색
실행(Execution)	셸 명령 실행, 서버 시작, 테스트 실행, git 사용
웹(Web)	웹 검색, 문서 가져오기, 에러 메시지 조회
코드 인텔리전스(Code intelligence)	편집 후 타입 에러 확인, 정의로 이동, 참조 찾기

grep과 ripgrep은 "검색" 카테고리의 핵심이다. 실제로 의외로 자주 막히는 부분이 ripgrep 바이너리 호환성 문제인데, 이는 7절 제한사항에서 다룬다.

하네스(Harness) 7가지 구성 요소

대형 코드베이스를 다루기 위한 Claude Code Harness는 7가지 구성 요소로 이루어져 있다:

구성 요소	역할
CLAUDE.md Files	세션 시작 시 자동 로드되는 프로젝트 지침
Hooks	특정 이벤트에 연결되는 자동화 액션
Skills	재사용 가능한 전문 지식 저장소
Plugins	기능 확장 모듈
LSP (Language Server Protocol)	심볼 수준의 정밀 탐색
MCP Servers	외부 서비스 및 도구 연결
Subagents	탐색 전담 격리 인스턴스

이 7가지를 어떻게 조합하느냐에 따라 동일한 코드베이스에서도 탐색 효율이 크게 달라진다.

LSP와 Subagents는 특히 주목할 만하다. LSP는 텍스트 패턴 매칭에서 발생하는 오탐을 줄여 심볼 수준의 정확한 탐색을 제공한다. Subagents는 탐색 작업을 독립된 컨텍스트에서 실행해 메인 세션의 컨텍스트 윈도우를 깨끗하게 보존한다.

⚠️ 중요한 주의사항: LSP 연동은 자동으로 되지 않는다. 이것이 흔한 실수 중 하나다 — LSP 서버를 별도로 배포해야 한다.

Hooks · Skills · Plugins — 자주 오해하는 세 가지

하네스 7요소 중 Hooks, Skills, Plugins는 흔히 한 줄로 요약되지만, 공식 블로그의 설명을 보면 실제 쓰임새는 그보다 넓다.

Hooks — 차단 장치가 아니라 개선 장치. 많은 팀이 Hooks를 'Claude가 잘못된 행동을 하지 못하게 막는 스크립트'로만 생각한다. 그러나 더 가치 있는 용도는 '지속적 개선'이다. 예를 들어 세션이 끝나는 시점에 실행되는 stop hook는 그 세션에서 무슨 일이 있었는지 되돌아보고, 컨텍스트가 아직 신선할 때 CLAUDE.md에 반영할 업데이트를 제안할 수 있다.

Skills — 필요할 때만 꺼내는 전문 지식. Skills는 progressive disclosure(점진적 공개) 방식으로 동작한다. 전문 워크플로와 도메인 지식을 평소에는 컨텍스트 밖에 두었다가, 그 작업이 실제로 필요해지는 순간에만 로드한다. 한정된 컨텍스트 공간을 불필요하게 차지하며 경쟁하지 않게 하는 것이다. 특정 경로에 스코프를 지정하면 해당 코드 영역에서만 활성화되도록 할 수도 있다.

Plugins — 묶어서 배포하는 패키지. 플러그인은 Skills, Hooks, MCP 설정을 하나의 설치 가능한 패키지로 묶는다. 잘 잡아 둔 설정 한 벌을 팀이나 조직 전체가 동일하게 설치해 쓸 수 있다는 뜻이다. 이 '공유' 성격은 8절의 조직 차원 운영으로 이어진다.

3. 컨텍스트 윈도우 관리 — 토큰 한계를 넘어서는 전략

왜 컨텍스트 관리가 핵심인가

모범 사례의 대부분이 단 하나의 제약에서 나온다고 명확히 말한다:

"Claude의 컨텍스트 윈도우는 빠르게 채워지고, 가득 찰수록 성능이 저하된다."

단일 디버깅 세션이나 코드베이스 탐색만으로도 수만 개의 토큰이 생성·소비될 수 있다.

컨텍스트 윈도우에는 대화 기록, 파일 내용, 명령 출력, CLAUDE.md, 자동 메모리, 로드된 스킬, 시스템 지침이 모두 쌓인다. 이 공간은 유한하다.

자동 압축(Auto-compact)의 동작 방식

컨텍스트가 한계에 가까워지면 Claude Code는 자동으로 대응한다.

먼저 오래된 도구 출력을 제거한다
필요하면 대화를 요약한다
요청과 핵심 코드 스니펫은 보존된다
초기 상세 지침은 손실될 수 있다

실제로 "지속해야 할 규칙은 대화 기록에 의존하지 말고 CLAUDE.md에 넣어라"는 원칙이 여기서 나온다.

Autocompact thrashing 경고

Autocompact is thrashing: the context refilled to the limit... 오류가 보이면, 하나의 파일이나 도구 출력이 너무 커서 압축 직후 컨텍스트가 다시 가득 찬 상태다. Claude Code는 무한 루프를 피하기 위해 재시도를 멈춘다. 이 경우 큰 파일이나 빌드 출력을 .claude/ignore에 추가하거나, 더 작은 범위로 작업을 쪼개야 한다.

수동 컨텍스트 관리 명령

자동 압축만으로 부족할 때는 직접 제어한다.

# 관련 없는 작업 사이에 컨텍스트 초기화
/clear

# 컨텍스트 수동 압축
/compact

# 포커스를 지정한 압축 (특정 변경사항에 집중)
/compact Focus on the API changes

/compact <지침> 형태가 단순 /compact보다 유용하다. 무엇을 중심으로 요약할지 명시하면 다음 작업에서 방향이 유지된다.

Subagents로 탐색 컨텍스트 분리하기

가장 효과적인 컨텍스트 보존 방법 중 하나는 탐색 작업을 Subagent에 위임하는 것이다.

"use subagents to investigate X"라고 지시하면 Subagent가 별도 컨텍스트에서 코드베이스를 탐색하고 파일을 읽은 뒤 결과만 메인 세션에 보고한다.

메인 대화는 구현에만 집중하고, 탐색의 잡음은 Subagent가 흡수한다. 탐색과 편집을 같은 세션에서 섞지 않는 것이 중요하다 — 이는 흔한 실수 목록에도 명시되어 있다.

4. CLAUDE.md — 프로젝트 지침 설계와 계층 구조

CLAUDE.md 파일의 위치별 범위

CLAUDE.md 파일은 여러 위치에 배치할 수 있으며, 위치에 따라 적용 범위가 다르다:

위치	파일 경로	범위
관리 정책	/Library/Application Support/ClaudeCode/CLAUDE.md (macOS)	조직 전체
사용자 지침	~/.claude/CLAUDE.md	모든 프로젝트 개인 설정
프로젝트 지침	./CLAUDE.md 또는 ./.claude/CLAUDE.md	팀 공유 프로젝트 설정
로컬 지침	./CLAUDE.local.md	개인 프로젝트별 설정 (.gitignore 권장)

루트 파일은 중요한 정보만 간결하게 유지하고, 디렉토리 계층을 이동할수록 추가 CLAUDE.md가 적재되는 "lean and layered" 구조가 권장된다.

CLAUDE.md에 포함할 것과 제외할 것

포함할 것:

Claude가 코드만 봐서는 알 수 없는 Bash 명령
기본값과 다른 코드 스타일 규칙
테스트 지침 및 선호하는 테스트 러너
브랜치 명명, PR 컨벤션 같은 리포지토리 에티켓
프로젝트 고유의 아키텍처 결정사항
필수 환경 변수 같은 개발 환경 특이사항

제외할 것:

Claude가 코드를 읽으면 스스로 파악할 수 있는 내용
이미 알고 있는 표준 언어 규칙
상세한 API 문서 (문서 링크로 대체)
자주 바뀌는 정보

CLAUDE.md 크기와 @import 문법

파일당 200줄 미만을 목표로 한다. 공식 문서에서는 "파일이 길어질수록 컨텍스트를 더 많이 소모하고 준수율이 떨어진다"고 명시하고 있다. 지침이 많아지면 path-scoped 규칙으로 분리해 해당 경로에서만 로드되도록 구성한다.

대규모 프로젝트에서 내용이 늘어날 때는 @import 문법이 유용하다:

# CLAUDE.md 내에서 외부 파일 가져오기
@path/to/shared-conventions.md
@.claude/architecture-notes.md

이렇게 가져온 파일들은 세션 시작 시 CLAUDE.md와 함께 컨텍스트에 로드된다.

공통 규칙은 한 파일에서 관리하고, 프로젝트별 CLAUDE.md에서 가져오는 패턴으로 중복을 줄일 수 있다.

CLAUDE.md 유지 관리 주기

주요 모델 릴리스 후 3~6개월마다 검토를 권장한다. 이때 두 가지를 확인하자:

구형 모델 한계를 보완하기 위해 추가했던 지침 — 제거한다
최신 기능을 오히려 제한하는 규칙 — 제거한다

모델이 업그레이드될수록 예전에 필요했던 세세한 지침이 오히려 방해가 되는 경우가 많다.

CLAUDE.md도 코드처럼 정기적으로 다이어트가 필요하다.

5. 낯선 코드베이스에서 시작하기 — 탐색 전략과 Plan Mode

첫 번째 세션: 넓게 훑고 좁혀가기

권장순서

# 1. 프로젝트 루트로 이동
cd /path/to/project

# 2. Claude Code 실행
claude

# 3. 고수준 개요 요청
give me an overview of this codebase

# 4. 특정 컴포넌트로 심화 탐색
explain the main architecture patterns used here
what are the key data models?
how is authentication handled?

이 순서대로 실행하면 전체 구조 파악 → 핵심 패턴 이해 → 특정 관심 영역 심화의 흐름이 자연스럽게 이어진다.

Plan Mode로 구현 전에 계획 검토하기

Shift+Tab을 두 번 누르면 Plan Mode에 진입한다.

이 모드에서 Claude는 먼저 코드베이스를 분석하고, 구현 계획을 대화로 설명한다.

계획을 검토하고 피드백을 주고받은 다음 실제 구현으로 넘어가는 2단계 접근 방식이다.

처음이라면 복잡한 기능 추가나 리팩토링 작업 전에 반드시 Plan Mode를 거치는 습관을 들이는 편이 낫다. "바로 코드로 뛰어들기"보다 계획 단계에서 방향을 맞추는 편이 훨씬 효율적이다.

코드베이스를 탐색 가능하게 만드는 설정

설정	방법	효과
하위 디렉토리 초기화	저장소 루트 대신 하위 디렉토리에서 claude 실행	불필요한 파일 탐색 범위 제한
테스트/린트 범위 지정	CLAUDE.md에 서브디렉토리별 명령 명시	관련 없는 빌드 출력 차단
생성 코드 제외	.claude/ignore에 자동 생성 파일 경로 추가	노이즈 감소
코드베이스 맵 구축	비전통적 구조에 CLAUDE.md에 맵 기술	구조 이해 지원
LSP 서버 배포	언어별 LSP 서버 설정	심볼 기반 정밀 탐색

"비전통적 구조"란 게임 엔진 바이너리 에셋, 일반적이지 않은 버전 관리, 비개발자 기여자 환경 등을 말한다. 이런 경우에는 표준 설정만으로는 부족하고 추가 커스터마이징이 필요하다.

6. 실전 사용 시나리오 — 버그 수정, 리팩토링, 기능 탐색

시나리오 1: 버그 수정

1. 오류 메시지를 Claude에 공유
   → "npm test를 실행하면 이 에러가 나온다"

2. 수정 방안 요청
   → "user.ts의 @ts-ignore를 수정하는 방법 몇 가지를 제안해줘"

3. 수정 적용
   → "user.ts에 null 체크를 추가해줘"

4. 이슈 재현 명령과 스택 트레이스 제공으로 검증

에러 메시지와 재현 명령을 함께 제공하는 것이 핵심이다.

Claude가 직접 테스트를 실행해서 수정 결과를 확인할 수 있어야 루프가 빠르게 돈다.

시나리오 2: 레거시 코드 리팩토링

1. 레거시 코드 식별
   → "우리 코드베이스에서 deprecated API 사용 부분을 찾아줘"

2. 리팩토링 권장사항 요청
   → "utils.js를 모던 JavaScript 기능으로 리팩토링하는 방법을 제안해줘"

3. 안전하게 적용
   → "utils.js를 ES2024 기능으로 리팩토링하되 동작은 그대로 유지해줘"

4. 테스트로 검증
   → "리팩토링된 코드의 테스트를 실행해줘"

"동작은 그대로 유지"라는 조건을 명시하는 것이 중요하다. Claude가 임의로 로직을 변경하는 것을 방지한다.

시나리오 3: 새로운 코드베이스 파악

처음에는 "이 코드베이스 개요를 설명해줘"처럼 넓은 질문으로 시작하고,

"인증은 어떻게 처리되는가?", "핵심 데이터 모델은 무엇인가?" 순서로 좁혀가는 것이 효과적이다.

한 번에 모든 걸 파악하려 하면 컨텍스트만 낭비된다.

시나리오 4: 신규 기능 추가 — Explore → Plan → Implement → Commit

새 기능을 추가할 때 바로 구현으로 뛰어드는 것은 대형 코드베이스에서 잘못된 방향으로 작업하는 가장 빠른 길이다.

1단계: Explore (Plan mode 진입)
   → "read /src/auth and understand how we handle sessions and login.
      also look at how we manage environment variables for secrets."

2단계: Plan (구현 계획 수립)
   → "I want to add Google OAuth.
      What files need to change? What's the session flow? Create a plan."

3단계: Implement (Plan mode 해제 후 구현)
   → "implement the OAuth flow from your plan.
      write tests for the callback handler, run the test suite and fix any failures."

4단계: Commit (커밋 및 PR 생성 요청)
   → "commit with a descriptive message and create a PR."

Plan mode(Shift+Tab 두 번 또는 claude --permission-mode plan)에서 Claude는 파일을 읽고 분석만 하며, 승인 전까지 어떤 파일도 수정하지 않는다. Ctrl+G를 누르면 계획을 텍스트 에디터에서 직접 편집한 뒤 Claude가 진행하도록 할 수도 있다.

대형 기능이라면 먼저 Claude에게 인터뷰를 진행하게 하는 방법도 있다.

AskUserQuestion 도구를 사용해 기술 구현, UI/UX, 엣지 케이스, 트레이드오프를 물어보게 한 뒤, 완성된 스펙을 SPEC.md로 작성하게 하고 새 세션에서 구현을 시작하는 패턴이다.

테스트는 구현과 함께 가는 편이 낫다. Claude는 프로젝트의 기존 테스트 파일을 분석해 동일한 스타일, 프레임워크, 어서션 패턴으로 테스트를 생성한다. "write tests for the callback handler, run the test suite and fix any failures(callback handler 테스트를 추가한 다음, 테스트 suite를 돌려보고 실패하는 부분이 있으면 고쳐줘.)"처럼 테스트 실행까지 한 번에 지시하면 Claude가 실패를 직접 수정하는 루프가 돈다.

7. 제한사항과 흔한 실수 — 기대를 조정하는 법

구조적 제한: 컨텍스트 윈도우

가장 근본적인 제약은 컨텍스트 윈도우다.

단일 디버깅 세션이나 코드베이스 탐색만으로도 수만 개의 토큰이 소비될 수 있고, 컨텍스트가 가득 찰수록 성능이 저하된다.

Claude Code가 대형 코드베이스에서 잘 못 하는 것:

전체 코드베이스를 한 번에 파악하는 작업 — 컨텍스트가 빠르게 차고 성능이 저하된다
단일 세션에서 탐색과 편집을 계속 반복하는 작업 — Subagents로 분리해야 한다

흔한 설정 실수 5가지

CLAUDE.md에 재사용 전문 지식을 넣기 → Skills를 사용해야 할 내용이다
모든 것을 CLAUDE.md에 로드하기 → Skills와 계층적 CLAUDE.md로 분산해야 한다
LSP 연동이 자동으로 된다고 가정하기 → LSP 서버는 별도로 배포해야 한다
기초가 작동하기 전에 MCP 연결 구축하기 → 단계적으로 설정한다
탐색과 편집을 같은 세션에서 실행하기 → Subagents로 분리한다

이 중 3번과 5번이 실전에서 가장 자주 실수가 나오는 지점이다.

환경별 제한사항: WSL과 ripgrep

ripgrep 바이너리 호환성: 번들된 ripgrep이 일부 시스템에서 실행되지 않을 수 있다. Search 도구, @file 멘션, 커스텀 에이전트, 커스텀 스킬이 파일을 찾지 못하면 이 문제를 의심한다.
WSL 파일 시스템 간 작업: WSL에서 서로 다른 파일 시스템 간 작업 시 디스크 읽기 성능 저하로 검색 결과가 불완전할 수 있다.

적용 범위: 어떤 환경에서 이 패턴이 동작하는가

이 패턴들이 표준 디렉토리 구조의 일반적인 Git 기반 환경에 적용된다고 명시한다. 게임 엔진 바이너리 에셋, 비전통적 버전 관리, 비개발자 기여자가 있는 환경은 추가 커스터마이징이 필요하다.

8. 조직 차원의 도입과 운영 — DRI, 에이전트 매니저, 검수 문화

여기까지는 개발자 한 사람이 Claude Code를 잘 쓰는 방법이었다.

그런데 이 글이 토대로 삼은 Anthropic 공식 블로그의 제목은 "best practices and where to start"다.

'where to start' — 팀과 조직이 어디서부터 시작해야 하는가 — 가 글의 큰 축을 차지한다.

도구를 능숙하게 다루는 것과, 그 도구를 조직의 표준으로 정착시키는 것은 별개의 문제다.

유능한 신입 사원 한 명을 뽑아도, 회사에 업무 매뉴얼도 사수도 검수 절차도 없다면 그 역량은 개인 안에 갇힌다. Claude Code도 같다. 도구의 잠재력이 아무리 커도, 그것이 팀의 실제 성과로 이어질지는 조직이 갖춘 교육·관리 체계가 결정한다.

왜 조직 차원의 운영이 필요한가

Claude Code 도입은 보통 현장 개발자들이 자발적으로 시작한다(bottoms-up).

공식 블로그는 이런 방식이 열정을 만들어내지만, 무엇이 잘 작동하는지를 중앙에서 모아 줄 사람이 없으면 파편화될 수 있다고 지적한다.

그 정리 작업이 없으면 노하우는 특정 개인·팀 안에만 머무는 'tribal knowledge'로 남고, 도입은 어느 선에서 정체(plateau)된다.

해결책 자체는 단순하다.

한 개인 또는 한 팀이 잘 작동하는 Claude Code 컨벤션을 모으고, 조직 전체에 적극적으로 전파(evangelize)하는 것이다.

같은 팀의 누군가가 찾아낸 좋은 설정이 그 사람 노트북에만 남지 않게 만드는 일이다.

DRI와 에이전트 매니저 — 누가 책임지는가

공식 블로그는 이 책임을 맡는 형태를 두 가지로 제시한다.

조직 규모와 성숙도에 따라 골라 쓰면 된다.

구분	DRI	에이전트 매니저 (Agent Manager)
적용 조직	전담 팀을 두기 어려운 조직의 최소 형태	여러 조직에서 떠오르고 있는 본격적 역할
정의	Claude Code 설정에 대한 ownership을 가진 한 사람	Claude Code 생태계 관리를 전담하는 PM·엔지니어 혼합 직책
책임 범위	설정, 권한 정책, 플러그인 마켓플레이스, CLAUDE.md 컨벤션을 소유하고 최신 상태로 유지	같은 범위를 전담 업무로 수행하며, 컨벤션 수립과 조직 내 확산을 주도
성격	"이건 내가 책임진다"가 분명한 담당자 1명	기획(PM)과 기술 이해(엔지니어)를 함께 갖춘 신규 직무

핵심은 직책 이름이 아니라 'ownership이 한 곳에 모여 있는가'다.

설정을 아무도 책임지지 않으면 4절에서 다룬 3~6개월 주기 검토도, 컨벤션 전파도 실제로는 실행되지 않는다. 담당자가 비어 있는 일은 결국 아무 일도 일어나지 않는다.

AI가 작성한 코드의 검수 — 인간 코드와 같은 기준

조직 규모가 커지면, 특히 규제 산업에서는 거버넌스 질문이 일찍 등장한다. 공식 블로그가 그대로 인용한 질문은 이렇다.

"AI가 생성한 코드가 인간이 작성한 코드와 동일한 리뷰 프로세스를 거치도록 어떻게 보장할 것인가?"

블로그가 권장하는 답은 한꺼번에 모든 문을 여는 것이 아니라 단계적으로 넓히는 것이다.

승인된 Skills 집합을 먼저 정의한다
코드 리뷰 프로세스를 필수 절차로 건다
초기 접근 범위를 제한해서 시작한다
신뢰가 쌓이는 만큼 범위를 확대한다

요지는 분명하다. AI가 만든 코드라고 검수를 건너뛰지 않는다.

동료 엔지니어의 PR과 똑같은 리뷰 라인을 통과시키는 것 — 블로그가 거버넌스 질문에 내놓은 답의 핵심이 여기에 있다.

도입 플레이북

오늘 바로 할 수 있는 것:

하나의 프로젝트 루트에 CLAUDE.md 생성 — 200줄 제한으로 핵심 정보만
낯선 코드베이스라면 give me an overview of this codebase로 시작
/clear 명령을 작업 전환 습관으로 만들기

이번 주 안에 설정할 것:

.claude/ignore에 빌드 디렉토리와 생성 코드 추가
자주 쓰는 탐색 패턴을 Skills로 분리 (CLAUDE.md에서 덜어내기)
Plan Mode 습관화 — 복잡한 작업 전에 Shift+Tab 두 번

팀 환경에 반영할 것:

Claude Code 설정을 책임질 DRI를 한 명 지정 — 전담 팀이 가능하면 에이전트 매니저 역할로 키운다
조직 수준 CLAUDE.md와 프로젝트 수준 CLAUDE.md 계층 분리
개인 설정은 CLAUDE.local.md + .gitignore로 분리
AI가 생성한 코드도 인간 코드와 동일한 코드 리뷰 라인을 통과하도록 검수 절차 수립
주요 모델 릴리스 후 3~6개월 주기로 CLAUDE.md 검토 일정 등록

9. 트러블슈팅 Q&A

Q. 컨텍스트가 계속 금방 가득 찬다

A. 세 가지를 확인한다:

/compact를 정기적으로 사용한다
주요 작업 사이에 Claude Code를 재시작한다
큰 빌드 디렉토리를 .gitignore에 추가한다

Q. "Autocompact is thrashing" 오류가 발생한다

A. 하나의 파일이나 도구 출력이 너무 커서 압축 직후 컨텍스트가 다시 가득 찬 상태다. .claude/ignore에 대용량 파일 경로를 추가하거나 작업 범위를 더 작게 쪼개야 한다.

Q. 검색 도구가 파일을 못 찾는다

A. 번들된 ripgrep 바이너리가 해당 시스템에서 실행되지 않을 가능성이 있다. WSL 환경이라면 파일 시스템 간 경계를 넘는 작업인지도 확인한다.

Q. CLAUDE.md 지침을 무시하는 것 같다

A. 파일이 200줄을 넘지 않는지 확인한다. 길어질수록 준수율이 떨어진다. 지침이 많다면 path-scoped 규칙으로 분산하거나 @import 문법으로 외부 파일로 빼낸다.

Q. Auto memory를 사용하려면 어떻게 해야 하나

A. Claude Code v2.1.59 이상이 필요하다. claude --version으로 버전을 확인하고, MEMORY.md의 처음 200줄 또는 25KB 중 먼저 도달하는 범위가 세션 시작 시 자동으로 로드된다.

Q. Claude Code를 팀 전체에 도입하려면 어디서부터 시작해야 하나

A. 먼저 설정을 책임질 DRI를 한 명 지정한다. 전담 팀을 둘 수 있다면 PM과 엔지니어 역량을 함께 갖춘 에이전트 매니저 역할로 키운다. 그다음 승인된 Skills 집합과 필수 코드 리뷰 절차를 정하고, 제한된 접근 범위로 시작해 신뢰가 쌓이는 만큼 확대한다.

Claude Code의 대형 코드베이스 지원은 도구 하나를 쓰는 것이 아니라 탐색 방식 자체를 재설계하는 과정에 가깝다. 에이전틱 검색, 계층적 CLAUDE.md, Subagents를 통한 컨텍스트 분리 — 이 세 가지 원리를 이해하면 나머지 모범 사례들이 자연스럽게 맞아 들어간다.

그리고 팀 단위로 넘어가면 기술 설정만으로는 부족하다. DRI나 에이전트 매니저처럼 설정을 책임지고 전파하는 역할이 있어야, 개인이 찾아낸 노하우가 조직의 표준으로 자리 잡는다. 좋은 도구를 들이는 데서 멈추지 않고 그 도구가 제 역량을 펼칠 운영 체계까지 함께 설계하는 것 — 원본 블로그가 말한 'where to start'의 진짜 의미는 거기에 있다.

작성일: 2026-05-19
분석 대상 버전: Claude Code (2026-05-19 기준 공식 문서)
면책 조항: 이 글은 2026-05-19 기준으로 작성되었다. 이후 변경될 수 있다.

참고 자료

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으로 명시하는 것이 암묵적 선택보다 결과를 예측하기 쉽다.

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월 기준. 이 글은 공식 문서에 공개된 범위만 다루며, 이후 기능명이나 설정 키는 변경될 수 있다.

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