<바이브 코딩 입문> 가이드

0부. 5분 오리엔테이션

0-1. 바이브 코딩이 뭔가요?

바이브 코딩(Vibe Coding) = 프로그래밍 언어 대신 우리말로 AI에게 시켜서 프로그램을 만드는 방식입니다.

• for 문을 외울 필요가 없습니다. "할 일을 추가하고 지울 수 있는 웹페이지 만들어 줘" 라고 말하면 AI가 코드를 씁니다.
• 우리가 할 일은 결과를 보고 "이렇게 고쳐 줘" 라고 대화하면서 완성도를 높이는 것입니다.
• 즉, 나는 감독, AI는 배우입니다.

0-2. 오늘 뭘 하게 되나요? — 전체 지도

① 준비물 설치        VS Code + 터미널 + Node.js + 파이썬        (1부, 약 20분)
        ↓
② 도구 하나 설치      Claude Code / Codex / Antigravity 중 택 1  (3~5부, 약 5분)
        ↓
③ 첫 결과물          "오늘의 할 일" 웹앱을 우리말로 주문         (약 10분)
        ↓
④ 대화로 수정        "다크 모드 버튼 추가해 줘"                  (약 10분)
        ↓
⑤ 규칙 심어두기      CLAUDE.md / AGENTS.md 파일 하나            (약 5분)

세 도구를 다 설치할 필요는 없습니다. 사용법이 거의 같으므로, 계정이 있는 것 하나만 골라서 끝까지 진행하면 됩니다.

0-3. 꼭 기억할 3가지

1. 나는 감독, AI는 배우 — 코드를 한 줄씩 쓰는 사람이 아니라, 무엇을 만들지 정하고 검수하는 사람입니다.
2. 작게, 한 번에 한 단계 — "쇼핑몰 만들어 줘"보다 "할 일을 입력하는 칸 하나 만들어 줘"가 훨씬 잘 됩니다.
3. AI는 가끔 틀립니다 — 그럴듯한데 틀린 답을 내놓습니다(할루시네이션). 반드시 실행해 보고 확인하세요.

0-4. 셋 중 무엇을 고를까요?

세 도구 모두 "에이전트형 CLI"입니다 — 코드를 추천만 하는 게 아니라 파일을 직접 만들고 고치고 명령어까지 실행합니다. 그래서 항상 "실행해도 될까요?"라고 묻고, 사람이 내용을 보고 승인하는 절차를 거칩니다.

참고: 세 도구 모두 유료 구독이 사실상 필요합니다. Antigravity의 무료 등급은 하루 20회 안팎이라 실습 도중 막히기 쉽습니다(5-5절 참고).

---

1부. 준비물 설치 — 모든 도구의 출발선

세 도구 모두 ① VS Code(편집기) + ② 터미널 + ③ Node.js + ④ 파이썬 위에서 돌아갑니다. 이 넷만 깔면 나머지는 거의 같습니다.

용어가 낯설면 부록 B의 용어 사전을 먼저 훑어보세요.

설치는 어느 인터넷에서 하나요? — 학교·기관 Wi-Fi는 피하세요

학교·회사·공공기관 Wi-Fi는 보안 필터가 프로그램 내려받기를 막거나 느리게 하는 경우가 많습니다. 여럿이 같은 Wi-Fi로 수백 MB를 한꺼번에 받으면 중간에 끊기기도 합니다. 이때 나는 오류는 명령을 잘못 친 것처럼 보여서 원인을 찾기 어렵습니다.

1. 집 Wi-Fi에서 수업 전에 설치·로그인까지 끝내 오기 — 가장 권합니다.
2. 수업 중에 설치해야 하면 내 휴대폰 핫스폿으로. 기관 Wi-Fi에서 아래 증상이 한 번이라도 나오면 고민하지 말고 바로 바꾸세요.
3. 설치가 끝난 뒤의 실습(대화·검색)은 기관 Wi-Fi로도 대개 문제없습니다.

• 망 문제의 증상 — ETIMEDOUT · ECONNRESET · ENOTFOUND · 403 · certificate·SSL이 들어간 오류, 설치 스크립트의 syntax error near unexpected token '<', 진행률이 몇 분째 멈춤, 로그인 브라우저 창이 "연결할 수 없음".
• 핫스폿 데이터(대략) — Claude Code 약 110MB · Codex 약 160MB · VS Code 약 100MB · Node.js 약 30MB · 파이썬 약 30MB. 도구 하나만 고르면 300MB 안팎입니다.
• 핫스폿은 각자 자기 휴대폰으로 켜세요. 한 사람의 핫스폿에 여럿이 붙으면 똑같이 느려집니다.
• 망을 바꾼 뒤에는 터미널을 새로 열고 실패했던 명령을 그대로 다시 실행하면 됩니다. 반쯤 설치된 것을 지울 필요는 없습니다.

1-1. VS Code 설치 (글 쓰는 창)

1. 브라우저에서 code.visualstudio.com 접속 → Download 버튼.
2. 내려받은 파일을 실행해 설치합니다.
3. 메뉴를 한글로 보고 싶다면, 실행 후 왼쪽 확장(Extensions) 탭에서 Korean Language Pack을 설치합니다.

✅ 체크포인트: VS Code가 열리고 왼쪽에 아이콘 줄이 보이면 성공입니다.

1-2. 터미널 열기 (AI에게 말 거는 창구)

• VS Code 상단 메뉴 → Terminal → New Terminal. 단축키는 Ctrl + 백틱(`)입니다.
• 화면 아래쪽에 까만 입력창이 나타나면 성공입니다. 앞으로 여기에 명령어를 입력합니다.

✅ 체크포인트: 까만 창에 PS C:\...>(Windows) 또는 사용자이름@맥북 ~ %(macOS) 같은 글자가 보이면 준비 완료입니다.

터미널이 무섭게 생겼나요? 그냥 명령어를 받아 적는 메모장이라고 생각하세요. 이 문서의 명령어는 모두 복사해서 붙여넣고 Enter만 누르면 됩니다. 코드 블록 오른쪽 위의 복사 버튼을 쓰세요.

Windows 사용자 — 터미널은 PowerShell 하나로 통일하고, 처음에 이 한 줄부터 실행하세요

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned -Force

• VS Code 터미널의 기본값이 PowerShell이고, 이 문서의 Windows 명령도 PowerShell 기준입니다. 명령 프롬프트(CMD)는 쓰지 마세요 — 두 종류의 명령이 섞이면 실패가 늘어납니다.
• 새 Windows PC의 PowerShell은 npm으로 깐 claude·codex 명령과 가상환경 켜기(Activate.ps1)를 막아 둡니다. 위 한 줄은 내 계정에만 적용되고 관리자 권한도 필요 없습니다. 한 번 해 두면 이 오류가 다시 생기지 않습니다.
• 학교 PC처럼 관리자가 정책을 잠가 둔 컴퓨터에서는 이 명령이 거부될 수 있습니다. 그때는 개인 노트북을 쓰세요.

1-3. Node.js 설치 (엔진)

Claude Code와 Codex를 npm으로 설치할 때 필요합니다. (설치 스크립트 방식을 쓰면 없어도 되지만, 깔아 두면 두루 편합니다.)

1. nodejs.org 접속 → LTS 버전 다운로드·설치. Windows는 설치 중 "Add to PATH" 체크를 그대로 두세요.
   주의: 설치 중 Automatically install the necessary tools 또는 Tools for Native Modules 같은 추가 개발도구 설치 옵션이 나오면 체크하지 마세요. 이 옵션을 선택하면 Python, Visual Studio Build Tools 등이 함께 설치되어 시간이 매우 오래 걸릴 수 있습니다.
2. 설치가 끝나면 터미널을 껐다 켜고 아래를 입력합니다.

node -v
npm -v

✅ 체크포인트: v22.x.x 처럼 버전 번호가 나오면 성공입니다. Claude Code는 Node.js 22 이상, Codex는 16 이상이면 npm으로 설치됩니다. 22보다 낮으면 LTS로 다시 설치하세요.

macOS에서 Homebrew를 쓴다면 brew install node 한 줄로 끝납니다. Antigravity CLI는 단일 실행파일이라 Node.js 없이도 설치됩니다(5부 참고).

1-4. 파이썬(Python) 설치

바이브 코딩으로 만든 프로그램을 실행하거나 데이터를 다루려면 파이썬이 필요합니다.

1. 브라우저에서 python.org 접속 → 상단 Downloads.
2. 내 컴퓨터에 맞는 버전을 내려받습니다. - Windows: 노란 버튼 "Download Python 3.x.x" 클릭. 설치 첫 화면에서 "Add python.exe to PATH" 체크가 필수입니다. 체크한 뒤 "Install Now". - macOS: "macOS 64-bit universal2 installer"를 내려받아 실행합니다.
3. 설치 확인 — 터미널에 입력합니다.

python --version

• macOS에서는 python3 --version으로 확인합니다.
• 권장 버전은 3.11 이상입니다.

✅ 체크포인트: Python 3.13.x 처럼 버전이 보이면 성공입니다.

"Add to PATH"를 빠뜨렸다면 — 터미널이 python을 못 찾습니다. 설치 파일을 다시 실행해 Modify → PATH 추가를 선택하세요.

1-5. 작업 폴더 만들기 (집 짓기 전 땅 고르기)

AI 코딩 도구는 "지금 열려 있는 폴더"를 작업 공간으로 삼습니다. 그 폴더 안의 파일을 읽고, 만들고, 고칩니다. 그래서 폴더를 먼저 만들고, 그 안에서 도구를 실행해야 합니다. 이 순서가 뒤바뀌면 엉뚱한 곳에 파일이 생기거나, 중요한 폴더 전체가 작업 대상이 됩니다.

① 터미널에서 만들기 — 자기 운영체제 블록만 복사하세요.

# Windows (PowerShell)
cd C:\
mkdir vibecoding -ErrorAction SilentlyContinue
cd vibecoding
mkdir my-first-vibe
cd my-first-vibe

# macOS
cd ~/Desktop
mkdir my-first-vibe
cd my-first-vibe

② VS Code에서 그 폴더 열기 — File → Open Folder → 방금 만든 my-first-vibe 선택. "이 폴더의 작성자를 신뢰하나요?"가 뜨면 신뢰(Yes, I trust the authors). 이렇게 열면 VS Code 터미널이 자동으로 그 폴더에서 시작합니다.

③ 위치 확인 — 도구를 실행하기 전에 매번 터미널 경로 끝을 눈으로 봅니다.

PS C:\vibecoding\my-first-vibe>          ← Windows
사용자이름@맥북 my-first-vibe %           ← macOS

✅ 체크포인트: VS Code 왼쪽 탐색기에 MY-FIRST-VIBE 폴더 이름이 보이고, 터미널 경로 끝이 my-first-vibe이면 성공입니다.

VS Code 확장(3-2절 방법 1)으로 하는 경우도 똑같습니다 — File → Open Folder로 연 폴더가 곧 작업 폴더입니다. 폴더를 열지 않고 확장을 쓰면 AI가 일할 곳이 없습니다.

도구가 "이 폴더를 신뢰하나요?"라고 물으면(Claude Code의 Yes, proceed, Codex의 Trust this folder?) — 방금 만든 작업 폴더일 때만 Yes를 고르세요. 모르는 폴더에서 이 질문이 뜨면 cd로 작업 폴더로 이동한 뒤 다시 실행합니다.

1-6. 오늘의 공통 과제

"오늘의 할 일(To-Do) 웹앱" 할 일을 입력해 추가하고, 완료하면 체크하고, 삭제할 수 있는 한 페이지짜리 웹앱. 별도 설치 없이 브라우저로 바로 열 수 있도록 HTML 파일 하나로 만듭니다.

3·4·5부에서 같은 과제를 도구만 바꿔 만들어 봅니다. 결과물이 어떻게 다른지 비교하는 것이 목적입니다.

---

2부. 가상환경(.venv)과 pip — 파이썬을 쓸 때만

급하면 건너뛰어도 됩니다. 3부(첫 실습)를 먼저 해보고, 파이썬 프로그램을 만들 때 이 절로 돌아오세요. 다만 이 절만 익혀 두면 설치 관련 사고가 거의 사라집니다.

2-1. 왜 가상환경을 쓰나요?

• 문제: 패키지를 컴퓨터 전체에 설치하면 프로젝트끼리 버전이 충돌합니다. A 프로젝트는 requests 2.28이 필요한데 B 프로젝트가 2.32로 덮어쓰는 식입니다.
• 비유: 가상환경은 프로젝트 전용 서랍입니다. 서랍 안에만 물건을 넣으니 다른 프로젝트와 섞이지 않습니다. 프로젝트를 지울 땐 서랍째 버리면 끝입니다.
• 결과: "내 컴퓨터에선 되는데" 문제가 크게 줄어듭니다.
• 이 강의의 표준: 파이썬 기본 기능인 venv + pip. 추가로 배울 도구가 없습니다.

이름이 왜 .venv인가요? 관례입니다. 점(.)으로 시작해 숨김 폴더가 되고, VS Code·깃 등 대부분의 도구가 이 이름을 자동으로 알아봅니다.

2-2. 만들기 · 켜기 · 끄기

① 작업 폴더로 이동 — 가상환경은 프로젝트 폴더 안에 만듭니다.

cd my-first-vibe

② 가상환경 만들기 — 폴더 안에 .venv/가 생깁니다. 한 프로젝트에 한 번만 실행하면 됩니다.

# Windows
python -m venv .venv

# macOS / Linux
python3 -m venv .venv

③ 활성화(켜기) — 터미널을 새로 열 때마다 필요합니다.

# Windows · PowerShell (VS Code 기본 터미널)
.venv\Scripts\Activate.ps1

# Windows · 명령 프롬프트(cmd)
.venv\Scripts\activate.bat

# macOS / Linux
source .venv/bin/activate

④ 켜졌는지 확인 — 터미널 입력줄 맨 앞에 (.venv)가 붙으면 성공입니다.

(.venv) PS C:\vibecoding\my-first-vibe>
 ↑ 이 표시가 핵심입니다

⑤ 끄기 — 다른 프로젝트로 옮길 때.

deactivate

✅ 체크포인트: 줄 맨 앞에 (.venv)가 보이나요? 안 보이면 아직 켜지지 않은 것입니다.

2-3. pip로 패키지 설치하기

반드시 (.venv)가 켜진 상태에서 설치하세요. 그래야 서랍 안으로 들어갑니다.

pip install requests python-dotenv

실행 — 활성화 상태에서 그냥 python을 씁니다.

python wordcount.py

공유·백업 규칙 — .venv/ 폴더는 공유하지 않습니다(용량이 크고 OS마다 내용이 다릅니다). 대신 requirements.txt만 공유하세요. .gitignore에 .venv/와 .env를 넣어 두는 것도 잊지 마세요.

2-4. VS Code에 가상환경 연결하기

VS Code가 어느 파이썬을 쓸지 알려 줘야 자동완성·오류 표시가 맞게 동작합니다.

1. VS Code 확장 탭에서 Python 확장(제작사 Microsoft)을 설치합니다.
2. Ctrl+Shift+P(macOS는 Cmd+Shift+P) → Python: Select Interpreter 입력.
3. 목록에서 .venv가 붙은 항목을 고릅니다. 보통 ('.venv': venv)로 표시됩니다.
4. 이후 VS Code 터미널을 새로 열면 (.venv)가 자동으로 켜집니다.

2-5. 가상환경에서 자주 나는 오류

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

막히면 AI에게 그대로 물어보세요 — 오류 메시지를 복사해 붙이고 "내 OS는 Windows야. 이 오류 원인과 해결 방법을 알려줘"라고 요청하면 됩니다. 설치 문제는 AI가 가장 잘 해결하는 영역입니다.

---

3부. Claude Code 실습 — 가장 쉬운 출발점

이 부분은 조태호 저 『혼자 공부하는 바이브코딩 with 클로드코드』(한빛미디어)를 참조했습니다. 더 깊이 배우려면 책과 공식 깃허브(참고문헌 [1])를 추천합니다.

3-1. Claude Code란?

• Anthropic이 만든 터미널 기반 AI 코딩 에이전트입니다.
• 2026년 10월 기준 기본 모델은 Claude Opus 5.5입니다. 더 빠른 작업엔 Sonnet 5.5, 가벼운 작업엔 Haiku 4.5를 고를 수 있습니다.
• 모델 변경은 /model, 생각의 깊이 조절은 /effort입니다.
• 계정 주의: 무료 claude.ai 요금제로는 쓸 수 없습니다. Pro(약 $20) 이상 구독 또는 API 계정이 필요합니다.

3-2. 설치 — 네 가지 방법 중 택 1

결론부터 — 처음이면 방법 1(VS Code 확장), 터미널에서 claude를 쓰려면 방법 2(설치 스크립트). 하나가 안 되면 바로 다음 방법으로 넘어가세요. 네 방법 모두 2026년 10월 기준 실제 경로·명령을 확인했습니다.

설치 전에 확인 — ① 집 Wi-Fi 또는 내 휴대폰 핫스폿인가(1부 망 안내) ② Windows라면 1-2절의 Set-ExecutionPolicy 한 줄을 했는가 ③ 유료 구독(Pro·Max·Team·Enterprise)이 있는가. 무료 claude.ai 계정으로는 쓸 수 없습니다.

방법 1 — VS Code 확장 (가장 쉬움)

1. VS Code 왼쪽 확장(Extensions) 아이콘 — 단축키 Ctrl+Shift+X (Mac은 Cmd+Shift+X)
2. 검색창에 Claude Code → 이름이 Claude Code for VS Code, 만든 이가 Anthropic인 것을 확인하고 Install
3. 설치되면 왼쪽(또는 편집기 오른쪽 위)에 ✱ 아이콘이 생깁니다. 누르면 대화 패널이 열립니다
4. 처음 열면 로그인 화면 → 3-3절의 "확장에서 로그인"대로 진행

• 별도 본체 설치가 필요 없습니다. 확장이 실행 파일을 품고 있어 Node.js도 필요 없습니다.
• 필요 조건 — VS Code 1.94 이상. Cursor 등 VS Code 계열 편집기에서도 같은 방식으로 설치됩니다.
• 확장이 안 보이면 VS Code를 재시작하거나 Ctrl+Shift+P → Developer: Reload Window.

주의 — 확장을 깔아도 터미널에서 claude라고 치면 안 됩니다. 확장은 자기 패널 안에서만 돕니다. 터미널 명령까지 쓰려면 방법 2~4 중 하나를 추가로 하세요. 이 문서의 실습은 claude 명령 기준으로 적혀 있지만, 확장 패널에 같은 문장을 넣어도 결과는 같습니다.

방법 2 — 공식 설치 스크립트 (터미널에서 claude를 쓰려면)

자기 운영체제·자기 터미널에 맞는 한 줄만 복사해 실행하세요. 섞어 쓰면 반드시 실패합니다.

# macOS · Linux · WSL (터미널)
curl -fsSL https://claude.ai/install.sh | bash

# Windows — PowerShell (권장)
irm https://claude.ai/install.ps1 | iex

REM Windows — 명령 프롬프트(CMD)에서만. PowerShell에 붙여넣으면 실패
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

지금 내 터미널이 무엇인지 — 입력줄 맨 앞을 보세요

• VS Code 터미널 오른쪽 위 + 옆 꺾쇠(∨)를 누르면 PowerShell·Command Prompt·Git Bash를 골라 열 수 있습니다. 이 문서는 PowerShell 기준입니다.
• 설치 스크립트는 claude 실행 파일을 내 계정 폴더에 넣고 PATH에 등록합니다. 그래서 끝나면 터미널을 완전히 닫았다 새로 열어야 claude가 인식됩니다.
• 이 방법은 자동 업데이트됩니다.

방법 3 — 패키지 관리자 (스크립트가 막힐 때)

# Windows (PowerShell 또는 CMD)
winget install Anthropic.ClaudeCode

# macOS (Homebrew가 깔려 있어야 함)
brew install --cask claude-code

• 자동 업데이트가 안 됩니다. 가끔 직접 올리세요 — winget upgrade Anthropic.ClaudeCode / brew upgrade claude-code
• Ubuntu·Debian·Fedora는 apt·dnf 저장소도 제공됩니다(공식 문서 참고).

방법 4 — npm (이미 Node.js를 쓰고 있다면)

npm install -g @anthropic-ai/claude-code

• Node.js 22 이상이 필요합니다(node -v로 확인). 낮으면 EBADENGINE 경고가 뜹니다.
• sudo npm install -g는 쓰지 마세요. 권한이 꼬이고 보안상 나쁩니다. 권한 오류(EACCES)가 나면 방법 2·3으로 바꾸세요.
• npm은 운영체제용 본체 파일(Windows 약 110MB)을 따로 내려받습니다. 망이 불안하면 끝에서 Native package ... not found가 납니다 → 부록 A.
• 업데이트는 npm install -g @anthropic-ai/claude-code@latest (npm update -g는 최신으로 안 갈 수 있음).
• 방법 2와 4를 둘 다 하지 마세요. 설치가 두 개가 되면 업데이트해도 옛 버전이 실행되는 일이 생깁니다.

Windows에서 권하는 것 하나 더 — Git for Windows. 필수는 아니지만 설치해 두면 Claude Code가 더 익숙한 방식(Bash)으로 명령을 실행합니다. 없으면 PowerShell로 돕니다.

설치 확인 — 터미널을 새로 열고:

claude --version      # 2.1.xxx (Claude Code) 처럼 버전이 찍히면 성공
claude doctor         # 설치 상태를 스스로 점검해 문제를 알려 줌

✅ 체크포인트: 2.1.x (Claude Code) 처럼 버전이 보이면 성공입니다. command not found / 'claude'은(는) ... 인식되지 않습니다가 나오면 터미널을 완전히 껐다 켜고, 그래도 안 되면 VS Code 자체를 재시작하세요. 나머지 오류는 부록 A.

3-3. 실행과 로그인

작업 폴더 안에서 한 단어만 입력합니다.

claude

로그인 따라 하기 — 구독한 계정 기준. 로그인은 처음 한 번만 합니다. 비밀번호를 터미널에 치는 일은 없고, 브라우저에서 로그인하고 "허용"만 누르면 끝납니다.

1. 글자 색 테마를 고르라는 화면 → 방향키로 고르고 Enter (아무거나 괜찮습니다)
2. 로그인 방법 선택 → Claude account with subscription(Pro·Max·Team·Enterprise)을 고르고 Enter
3. 브라우저가 저절로 열립니다 → 구독한 claude.ai 계정으로 로그인 → Authorize(승인)
4. "로그인 성공" 문구가 뜨면 터미널로 돌아와 Enter
5. "이 폴더의 파일을 신뢰하나요?"라는 질문 → 작업 폴더에서 실행했다면 Yes, proceed
6. 입력창에 안녕이라고 쳐서 답이 오면 끝. 나갈 때는 /exit

• 브라우저가 안 열리면 — 터미널에 긴 주소가 보입니다. 안내대로 c를 눌러 복사 → 브라우저 주소창에 붙여넣기 → 승인 후 나오는 코드를 복사해 터미널에 붙여넣기.
• 로그인 창이 계속 다시 뜨면 — 기관 Wi-Fi라면 핫스폿으로 바꿔 다시 해 보세요(1부 망 안내).
• 계정을 바꾸려면 claude 안에서 /logout 후 다시 claude.
• 구독은 Pro 약 $20 / Max $100·$200입니다. 사용량에 따라 고르세요.

✅ 체크포인트: 터미널에 Claude Code 환영 화면과 입력창이 뜨면 성공입니다.

VS Code 안에서 쓰기 — 확장 탭에서 "Claude Code for VS Code"(제작사 Anthropic)를 설치하면, 사이드 패널에서 인라인 diff(바뀐 부분 미리보기), @파일명 멘션, /model·/context 같은 슬래시 명령을 화면으로 쓸 수 있습니다. 확장에서 로그인: ✱ 아이콘으로 패널 열기 → Sign in → Claude.ai 구독 쪽 선택 → 브라우저에서 Authorize → 브라우저가 "Visual Studio Code를 여시겠습니까?"라고 물으면 열기. 터미널에서 이미 로그인했다면 그대로 이어집니다.

3-4. 첫 실습 — 할 일 웹앱 만들기

claude가 실행된 상태에서 우리말로 그대로 입력합니다.

초보자도 이해하기 쉽게, 할 일을 추가·완료체크·삭제할 수 있는 '오늘의 할 일' 웹앱을 만들어 줘.
조건:
1) 설치 없이 브라우저로 바로 열리도록 index.html 파일 하나로 만들 것
2) 디자인은 깔끔하고 모바일에서도 보기 좋게
3) 할 일 목록은 새로고침해도 남아 있도록 브라우저에 저장

Claude Code는 계획을 먼저 보여주고, 동의하면 index.html을 만듭니다. 파일이 생기면 더블클릭하거나 아래 명령으로 엽니다.

# macOS
open index.html
# Windows
start index.html

✅ 체크포인트: 브라우저에 할 일 입력창과 "추가" 버튼이 보이고, 실제로 항목이 추가되면 첫 바이브 코딩 성공입니다.

아래는 나올 결과물의 뼈대 예시입니다. 이런 코드가 나오는지 눈으로 확인하는 용도이며, 외울 필요는 전혀 없습니다.

<!DOCTYPE html>
<html lang="ko">
<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>오늘의 할 일</title>
  <style>
    body { font-family: sans-serif; max-width: 480px; margin: 40px auto; padding: 0 16px; }
    .done { text-decoration: line-through; color: #aaa; }
    li { display: flex; justify-content: space-between; padding: 8px 0; }
  </style>
</head>
<body>
  <h1>오늘의 할 일</h1>
  <input id="todoInput" placeholder="할 일을 입력하세요" />
  <button onclick="addTodo()">추가</button>
  <ul id="todoList"></ul>
  <script>
    // 브라우저 저장소(localStorage)에서 목록 불러오기
    let todos = JSON.parse(localStorage.getItem('todos') || '[]');
    function save() { localStorage.setItem('todos', JSON.stringify(todos)); render(); }
    function addTodo() {
      const v = document.getElementById('todoInput').value.trim();
      if (!v) return;
      todos.push({ text: v, done: false });
      document.getElementById('todoInput').value = '';
      save();
    }
    function render() {
      const ul = document.getElementById('todoList');
      ul.innerHTML = '';
      todos.forEach((t, i) => {
        const li = document.createElement('li');
        li.innerHTML = `<span class="${t.done ? 'done' : ''}"
          onclick="toggle(${i})">${t.text}</span>
          <button onclick="remove(${i})">삭제</button>`;
        ul.appendChild(li);
      });
    }
    function toggle(i) { todos[i].done = !todos[i].done; save(); }
    function remove(i) { todos.splice(i, 1); save(); }
    render();
  </script>
</body>
</html>

3-5. 대화로 고치기 (바이브 코딩의 핵심)

결과를 보고 말로 수정을 요청합니다. 한 번에 하나씩 시키는 것이 요령입니다.

완료한 항목이 자동으로 목록 맨 아래로 내려가게 해 줘. 그리고 상단에 '남은 할 일 N개'를 표시해 줘.

다크 모드 켜고 끄는 버튼을 오른쪽 위에 추가해 줘.

✅ 체크포인트: 브라우저를 새로고침했을 때 요청한 변화가 보이면 성공입니다. 안 보이면 "적용이 안 된 것 같아. 브라우저에서 강제 새로고침해도 그대로야"라고 그대로 말해 주세요.

3-6. 두 번째 실습 — 파이썬 프로그램 만들고 실행하기

웹페이지(HTML)는 브라우저로 열어 봤습니다. 이번에는 터미널에서 돌아가는 작은 파이썬 프로그램을 만들어, AI가 코드를 쓰고 직접 실행해 결과까지 보여주는 경험을 합니다.

먼저 가상환경을 켭니다 — 2부대로 (.venv)가 켜진 상태에서 진행하세요.

claude 실행 상태에서 우리말로 요청합니다.

글을 분석해 글자 수·단어 수·문장 수를 세어 주는 간단한 파이썬 프로그램을 만들어 줘.
조건:
1) 파일 이름은 wordcount.py
2) 분석할 예시 글을 코드 안에 넣어 두고, 결과를 보기 좋게 출력
3) 초보가 읽기 쉽게 한국어 주석을 충분히 달 것
4) 표준 라이브러리만 사용(추가 설치 없이 실행되게)
그리고 그 프로그램을 실행해서 결과까지 보여줘.

Claude가 wordcount.py를 만들고 직접 실행해 결과를 보여줍니다. 만들어질 코드의 예시입니다.

# 분석할 글 (이 부분만 바꾸면 다른 글도 분석됩니다)
text = "오늘 시청에서 기자회견이 열렸다. 시장은 내년 예산을 발표했다. 질문도 이어졌다."

# 글자 수 (공백 포함 / 공백 제외)
char_with_space = len(text)
char_no_space = len(text.replace(" ", ""))

# 단어 수 (공백 기준으로 나눠 셉니다)
word_count = len(text.split())

# 문장 수 (마침표·물음표·느낌표 개수로 단순 계산)
sentence_count = text.count(".") + text.count("?") + text.count("!")

print("글자 수(공백 포함):", char_with_space)
print("글자 수(공백 제외):", char_no_space)
print("단어 수:", word_count)
print("문장 수:", sentence_count)

직접 실행해 보려면 터미널에 입력합니다.

python wordcount.py

✅ 체크포인트: 터미널에 글자 수(공백 포함): 43 처럼 숫자가 출력되면 성공입니다.

외부 패키지가 필요한 프로그램이라면 — (.venv)가 켜진 상태에서 pip install로 먼저 설치하세요. AI에게 "필요한 패키지를 pip install로 설치하고 requirements.txt에도 추가해 줘"라고 요청하면 한 번에 처리됩니다.

웹앱 때와 똑같이, 결과를 보고 말로 고치면 됩니다.

평균 문장 길이(공백 제외 글자 수 ÷ 문장 수)도 함께 출력해 줘.

HTML(웹페이지)과 파이썬(프로그램) 두 가지를 만들어 보면, 바이브 코딩이 웹뿐 아니라 일반 프로그램에도 똑같이 통한다는 걸 알 수 있습니다.

3-7. CLAUDE.md — 프로젝트에 규칙 심기

폴더에 CLAUDE.md 파일을 두면 Claude가 매번 그 규칙을 자동으로 읽습니다. 초보에게 특히 강력한 기능입니다.

# 프로젝트 규칙
- 모든 설명과 주석은 한국어로 작성한다.
- 초보자가 읽기 쉽게 변수명은 명확하게 짓는다.
- 외부 라이브러리는 꼭 필요할 때만 쓴다.
- 파이썬 패키지는 .venv 가상환경에 pip로 설치한다. 설치 후 requirements.txt를 갱신한다.

파일을 직접 쓰기 어렵다면 claude 안에서 /init 을 입력하세요. 폴더를 분석해 초안을 자동으로 만들어 줍니다.

3부 요약: 설치 → claude 실행 → 우리말로 요청 → 결과 확인 → 대화로 수정 → CLAUDE.md로 규칙화. 웹앱이든 파이썬 프로그램이든 같은 사이클이며, 이것이 바이브 코딩의 전부입니다.

---

4부. OpenAI Codex 실습 — 같은 앱, 다른 도구

4-1. Codex란?

• OpenAI의 에이전트형 코딩 시스템입니다. 터미널 CLI·IDE 확장·클라우드·깃허브 봇이 하나의 계정, 하나의 모델로 연결됩니다.
• 2026년 10월 기준 모델은 GPT-6 계열입니다. /model로 고를 수 있습니다.
• GPT-6.1-Sol — 코딩과 일상 작업의 기본 모델(기본으로 무난)
• GPT-6-Astra — 가장 강력. 어려운 작업용
• GPT-6-Luna — 빠르고 저렴. 쉬운 작업용
• 예전 자료에 나오는 gpt-5.6 계열(Sol·Terra·Luna)은 이제 이전 세대로 분류됩니다. 목록은 계정·버전마다 다르니 /model에서 확인하세요.

4-2. 설치 — 네 가지 방법 중 택 1

Claude Code와 같은 네 갈래입니다. 터미널에서 쓸 거면 npm(방법 4) 또는 설치 스크립트(방법 2), 터미널이 낯설면 VS Code 확장(방법 1). npm 설치는 2026년 10월 최신판(Codex CLI 0.160)을 빈 환경에 직접 설치해 확인했습니다.

방법 1 — VS Code 확장

1. 확장 탭(Ctrl+Shift+X)에서 Codex 검색
2. 이름이 Codex – OpenAI's coding agent, 만든 이가 OpenAI인 것을 Install
3. 사이드바(왼쪽 또는 오른쪽)의 Codex 아이콘 → Sign in with ChatGPT → 브라우저 승인 (아래 "로그인 따라 하기")

• 확장은 터미널 codex와 로그인·설정(~/.codex/)을 함께 씁니다. 한쪽에서 로그인하면 다른 쪽도 이어집니다.

방법 2 — 공식 설치 스크립트

# Windows — PowerShell
irm https://chatgpt.com/codex/install.ps1 | iex

# macOS · Linux
curl -fsSL https://chatgpt.com/codex/install.sh | sh

• Windows 스크립트는 codex.exe를 %LOCALAPPDATA%\Programs\OpenAI\Codex\bin에 넣고 PATH에 등록합니다. 끝나면 터미널을 새로 여세요.
• Codex는 CMD용 설치 스크립트가 없습니다. Windows는 PowerShell에서 하세요.

방법 3 — 패키지 관리자

# Windows
winget install OpenAI.Codex

# macOS
brew install --cask codex

방법 4 — npm (Node.js가 있다면 권장)

npm install -g @openai/codex

패키지 이름 주의 — 반드시 @openai/codex입니다. 앞의 @openai/를 빼고 codex만 설치하면 전혀 다른 패키지가 깔립니다.

• Windows는 1-2절의 Set-ExecutionPolicy 한 줄을 먼저 해 두어야 설치 후 codex가 막히지 않습니다(codex.ps1을 로드할 수 없습니다 오류 예방).
• npm은 운영체제용 실행 파일(Windows 약 160MB)을 함께 내려받습니다. 기관 Wi-Fi에서 멈추면 핫스폿으로 바꿔 같은 명령을 다시 실행하세요.
• macOS에서 EACCES가 나면 sudo를 붙이지 말고 방법 2나 3으로 바꾸세요.
• 업데이트는 npm install -g @openai/codex@latest.

설치 확인과 실행

codex --version
codex

• codex --version에 codex-cli 0.1xx.x가 나오면 설치 성공입니다.
• 요금: ChatGPT Plus·Pro·Business·Edu·Enterprise에 포함됩니다. Free·Go에도 한시적으로 열려 있지만 한도가 작아 실습엔 Plus 이상을 권합니다.

로그인 따라 하기 — ChatGPT 구독 계정 기준

1. 작업 폴더에서 codex 입력 → Enter
2. 로그인 방법 화면에서 Sign in with ChatGPT를 고르고 Enter
3. 브라우저가 열림 → ChatGPT 계정으로 로그인 → 승인(Continue) → "로그인됨" 화면이 나오면 브라우저를 닫음
4. Trust this folder?가 뜨면 작업 폴더일 때만 Yes
5. 입력창에 안녕을 쳐서 답이 오면 끝. 나갈 때는 /quit

codex login status     # Logged in using ChatGPT 가 나오면 정상

• 브라우저 로그인이 안 돌아오면 — codex login --device-auth를 실행해, 화면의 주소를 브라우저로 열고 화면에 나온 코드를 입력하세요. 회사망·원격 PC에서 특히 잘 됩니다.

✅ 체크포인트: 터미널에 Codex 입력창이 뜨고 codex login status가 Logged in using ChatGPT이면 성공입니다.

VS Code 안에서 쓰기 — 확장 탭에서 Codex를 검색해 제작사가 OpenAI인 확장을 설치하면 사이드 패널 에이전트가 열려 있는 파일을 맥락으로 활용합니다. 패널에서 Sign in with ChatGPT를 누르면 위와 같은 브라우저 로그인이 진행됩니다. 터미널 codex와 로그인·설정을 함께 씁니다.

4-3. Claude Code와 다른 점

• 작업 흐름: /plan으로 계획만 먼저 받고 → 확인 후 "이대로 진행해 줘"로 실행 → /review로 바뀐 내용을 검토하게 합니다. (/exec라는 명령은 없습니다. 옛 자료에 나오면 무시하세요.)
• 주의점: 변경 전 diff(미리보기)가 약하고 승인 흐름이 거칠다는 평이 있습니다. 바뀐 파일을 꼭 직접 확인하세요.
• 그 밖에 대화를 마크다운으로 내보내는 /export, 현재 설정과 사용량을 보여주는 /status, 규칙 파일 초안을 만드는 /init이 있습니다. 전체 목록은 입력창에 /만 쳐 보면 나옵니다.

4-4. 같은 과제 실습

먼저 /plan을 입력해 플랜 모드로 바꾼 뒤 요청합니다. 플랜 모드에서는 파일을 만들지 않고 계획만 보여 줍니다.

/plan

할 일을 추가·완료체크·삭제할 수 있는 '오늘의 할 일' 웹앱을
index.html 한 파일로 만들고 싶어. 브라우저 저장 기능도 포함해 줘.

계획이 마음에 들면 실행을 요청합니다. 화면에 실행 여부를 묻는 선택지가 나오면 그것을 골라도 됩니다.

좋아, 이 계획대로 만들어 줘.

파일을 만들거나 명령을 실행하기 전에 승인을 물으면 무엇을 하는지 읽고 승인합니다. 작업이 끝나면 index.html을 직접 열어 확인하고 다듬습니다.

/review
방금 만든 코드에서 초보가 헷갈릴 만한 부분에 한국어 주석을 더 달아 줘.

비교 포인트(강의용 질문): "Claude Code와 결과물이 어떻게 다른가? 어느 쪽 설명이 더 이해하기 쉬운가?" — 정답은 없습니다. 도구마다 결과가 다르다는 걸 체감하는 것이 목적입니다.

---

5부. 구글 도구 실습 — Antigravity CLI

5-1. Gemini CLI는 종료됐습니다 (중요)

2026년 6월 18일부로 기존 gemini 명령은 종료됐습니다. 개인용·Google AI Pro·Ultra 요금제에서 Gemini CLI와 Gemini Code Assist IDE 확장의 요청 처리가 중단됐고, 이후 gemini 호출은 HTTP 410을 돌려줍니다. 후속 도구는 Antigravity CLI이며 실행 명령은 agy입니다. (기업용 Gemini Code Assist 라이선스를 보유한 조직은 예외적으로 기존 CLI를 계속 쓸 수 있습니다.)

5-2. VS Code에서 쓰는 법 — 무엇이 적절한가요?

구글의 코딩 도구는 두 갈래로 나뉩니다. 이 강의는 VS Code를 표준 편집기로 쓰므로 선택이 갈립니다.

결론 — VS Code를 계속 쓰면서 터미널에서 agy를 실행하는 방식이 이 강의에 맞습니다. 아래는 모두 이 방식 기준입니다.

5-3. 설치와 로그인

Antigravity CLI는 npm 패키지가 아닙니다. 설치 스크립트로만 깝니다. Node.js도 필요 없습니다.

# macOS · Linux
curl -fsSL https://antigravity.google/cli/install.sh | bash

# Windows · PowerShell
irm https://antigravity.google/cli/install.ps1 | iex

REM Windows · 명령 프롬프트(CMD)
curl -fsSL https://antigravity.google/cli/install.cmd -o install.cmd && install.cmd && del install.cmd

설치 스크립트가 OS와 CPU 종류를 알아서 판별해 실행파일을 내려받고, 체크섬을 확인한 뒤 ~/.local/bin/agy(Windows는 C:\Users\내이름\AppData\Local\agy\bin)에 넣어 줍니다. 이후 업데이트도 자동입니다. 끝나면 터미널을 새로 열고 agy --version으로 확인하세요. 명령 이름이 gemini가 아니라 agy입니다.

• npm install -g @google/gemini-cli로 까는 옛 Gemini CLI는 설치는 되지만 개인 Google 계정으로 로그인해 쓸 수 없습니다(2026-06-18 종료).
• Windows는 PowerShell 줄을 쓰세요(1-2절). CMD 줄은 예비입니다.

실행과 로그인 — 작업 폴더에서 agy를 입력하면 브라우저가 열리며 구글 계정 인증을 진행합니다.

agy

동작 확인 — 한 줄 질문으로 바로 테스트해 볼 수 있습니다.

agy -p "이 폴더에 뭐가 들어 있는지 요약해줘"

✅ 체크포인트: 폴더 내용 요약이 출력되면 성공입니다.

기존 Gemini CLI 사용자 — 설정을 옮기는 마법사가 있습니다. 첫 실행 때 가져오기를 수락하면 MCP 서버 등록·허용 명령어·키바인딩이 자동으로 넘어옵니다. 수동으로 하려면 아래 명령을 쓰고 agy inspect로 결과를 확인하세요.

agy plugin import gemini
agy inspect

5-4. 같은 과제 실습

'오늘의 할 일' 웹앱을 index.html 한 파일로 만들어 줘.
- 할 일 추가/완료체크/삭제
- 브라우저에 저장(localStorage)
- 무료 폰트만 사용하고, 한국어 주석을 충분히 달아 줘

구글 도구의 강점(검색 근거)을 살린 추가 요청입니다.

모바일 접근성(a11y) 최신 권고를 검색해서 확인하고,
그 권고에 맞춰 버튼과 입력창에 적절한 라벨을 붙여 줘. 출처 링크도 알려줘.

→ 검색 결과를 근거로 찾아 반영하는 모습을 강의에서 시연할 수 있습니다.

5-5. 무료 한도 주의 (강의 전 확인 필수)

"무료로 넉넉하게"는 옛말입니다. 무료 등급은 하루 20회 안팎의 에이전트 요청으로 제한됩니다(5시간 단위로 조금씩 회복). 실습 도중 한도에 걸려 멈추는 사례가 흔합니다. 강의 실습의 기본 도구로는 권장하지 않습니다. 유료(Pro / AI Ultra)를 쓰거나, 시연·보조용으로만 사용하세요. 유료 등급도 2026년 3월부터 주 단위 한도로 바뀌어, 한도를 다 쓰면 최대 일주일간 잠길 수 있습니다.

• 서브에이전트 병렬 실행은 사용량을 아주 빠르게 소모합니다. 입문 단계에서는 쓰지 마세요.
• /usage(또는 /quota)로 남은 양을 확인하는 습관이 필요합니다.
• 추가 크레딧 구매도 가능하지만 입문 실습에 필요한 수준은 아닙니다.

5-6. 설정과 승인 모드

승인 모드(toolPermission) — 설정 파일이나 /permissions로 바꿉니다.

자주 쓰는 슬래시 명령

---

6부. 도구 비교와 공통 원칙

6-1. 한눈에 비교 (2026년 10월 기준)

초보 추천 동선: ① Claude Code로 감을 잡고(자료가 가장 많습니다) → ② 이미 ChatGPT를 결제 중이면 Codex로 옮겨 계속 → ③ 구글 도구는 검색 근거가 필요한 작업에서 보조로 활용.

6-2. 어떤 도구든 통하는 원칙 5가지

1. 작게 쪼개서 시킬 것 — "앱 전체"가 아니라 "기능 하나"씩.
2. 조건을 구체적으로 적을 것 — 파일 형식, 디자인, 저장 방식까지 명시.
3. 계획을 먼저 보고 승인할 것 — 실행 전에 무엇을 할지 확인.
4. 항상 실행해서 확인할 것 — AI는 틀릴 수 있습니다.
5. 규칙은 .md 파일로 고정할 것 — CLAUDE.md / AGENTS.md.

6-3. 좋은 프롬프트 vs 아쉬운 프롬프트

---

부록 A. 자주 나오는 오류 해결

먼저 볼 것 — 학교·기관 Wi-Fi에서 설치 중이라면, 아래 표를 보기 전에 내 휴대폰 핫스폿으로 바꿔 같은 명령을 다시 실행해 보세요(1부 망 안내). 망 문제가 가장 흔하고, 오류 문장만 봐서는 구분이 어렵습니다.

A-1. 터미널·설치 공통

A-2. Claude Code

A-3. Codex

A-4. 구글 · 가상환경 · 기타

모든 오류의 1번 해결책 — 오류 메시지를 그대로 복사해서 AI에게 붙여 넣고 "내 OS는 ○○이야. ○○를 하려던 중이야. 원인과 해결 방법을 알려줘"라고 물어보세요. 추측해서 이것저것 지우지 마세요. 설치가 반쯤 된 상태에서 손대면 원인 찾기가 더 어려워집니다.

---

부록 B. 용어 사전

---

부록 C. Codex만으로 진행하기

이 문서는 Claude Code를 기준으로 썼지만, OpenAI Codex만으로도 전 과정을 그대로 진행할 수 있습니다. ChatGPT 구독자가 많다면 이 절만 따라가면 됩니다. 바꿀 것은 명령어·파일명·승인 방식 세 가지뿐입니다.

C-1. 개념 대응표

C-2. 설치부터 첫 실습까지

① 공통 준비는 동일합니다 — VS Code·터미널·Node.js·파이썬·작업 폴더(1부), 가상환경(2부). 여기까지는 도구와 무관하게 같습니다.

② 설치와 로그인

# Windows · PowerShell (npm 방식 — 1-2절의 Set-ExecutionPolicy 한 줄을 먼저)
npm install -g @openai/codex
cd my-first-vibe
codex

# macOS
curl -fsSL https://chatgpt.com/codex/install.sh | sh
cd my-first-vibe
codex

로그인은 4-2절의 "로그인 따라 하기"와 같습니다. Trust this folder?가 뜨면 작업 폴더이므로 Yes.

③ 권한(샌드박스) 정하기 — 실습에서는 workspace-write가 적절합니다. 작업 폴더 안의 파일만 고칠 수 있습니다.

④ 규칙 파일 만들기 — AGENTS.md를 작업 폴더 최상단에 저장합니다. 3-7절의 CLAUDE.md 내용을 그대로 옮기면 됩니다.

# 프로젝트 규칙
- 모든 설명과 주석은 한국어로 작성한다.
- 초보자가 읽기 쉽게 변수명은 명확하게 짓는다.
- 외부 라이브러리는 꼭 필요할 때만 쓴다.
- 파이썬 패키지는 .venv 가상환경에 pip로 설치한다. 설치 후 requirements.txt를 갱신한다.
- 파일을 고치기 전에 무엇을 바꿀지 먼저 알려준다.

⑤ 할 일 웹앱 만들기 — 3-4절 프롬프트를 그대로 쓰되, 계획·실행을 끊어서 지시합니다.

/plan

초보자도 이해하기 쉽게, 할 일을 추가·완료체크·삭제할 수 있는 '오늘의 할 일' 웹앱을 만들어 줘.
조건:
1) 설치 없이 브라우저로 바로 열리도록 index.html 파일 하나로 만들 것
2) 디자인은 깔끔하고 모바일에서도 보기 좋게
3) 할 일 목록은 새로고침해도 남아 있도록 브라우저에 저장

좋아, 이 계획대로 만들어 줘.

⑥ 파이썬 프로그램 만들기 — 3-6절과 동일합니다. 가상환경을 켠 뒤 진행하세요.

글자 수·단어 수·문장 수를 세는 파이썬 프로그램을 wordcount.py로 만들어 줘.
표준 라이브러리만 쓰고, 한국어 주석을 충분히 달아 줘. 만든 뒤 실행해서 결과도 보여줘.

C-3. Codex를 쓸 때 특히 주의할 점

• 바뀐 파일을 꼭 눈으로 확인하세요 — 작업 후 파일을 직접 열어 보는 습관을 들이세요. 폴더가 git 저장소라면 /diff로 바뀐 줄만 볼 수 있습니다.
• --yolo·danger-full-access 금지 — 승인과 샌드박스를 모두 끕니다. 강의 환경에서는 절대 쓰지 마세요.
• 웹 검색은 켜야 실시간으로 됩니다 — codex --search로 실행하거나 설정에 web_search = "live"를 넣으세요. 검색 결과는 반드시 링크를 열어 확인하세요.
• Codex가 실행하는 명령은 기본적으로 인터넷이 막혀 있습니다 — Codex에게 만들어 달라고 한 파이썬 프로그램이 인터넷(API 등)을 써야 한다면, 작업 폴더의 .codex/config.toml에 [sandbox_workspace_write]와 network_access = true 두 줄이 필요합니다. 이 설정은 폴더를 신뢰(Trust)했을 때만 읽힙니다.
• 서브에이전트·스킬까지 쓸 때 (실제로 확인한 함정 넷)
  ① 스킬은 .agents/skills/<이름>/SKILL.md에 둬야 합니다. .claude/skills·.codex/skills는 읽지 않습니다.
  ② 서브에이전트(.codex/agents/*.toml, 필수 항목 name·description·developer_instructions)는 신뢰한 폴더에서만 읽힙니다. 신뢰하지 않으면 default·explorer·worker만 보입니다.
  ③ Codex의 샌드박스가 .codex/ 폴더를 보호해서, Codex에게 이 파일을 만들라고 시키면 PC에 따라 거부될 수 있습니다. VS Code에서 직접 만들거나 설치 스크립트를 쓰세요.
  ④ Codex는 서브에이전트를 알아서 부르지 않습니다. "searcher, judge 서브에이전트로 해 줘"처럼 이름을 불러야 합니다.
  파일을 만들거나 고친 뒤에는 /quit로 나갔다 다시 codex를 실행해야 새 설정이 읽힙니다. 그대로 따라 할 수 있는 최소 구성은 C-4.
• 명령·설정이 자주 바뀝니다 — codex 안에서 /help로 현재 버전의 명령 목록을 먼저 확인하세요.

핵심 — 도구가 달라져도 바이브 코딩의 사이클은 같습니다. 말로 요청 → 계획 확인 → 실행 → 결과 검수 → 규칙 파일로 고정. 이 흐름만 몸에 익히면 어느 도구로 옮겨도 30분이면 적응할 수 있습니다.

C-4. Codex에서 서브에이전트·스킬을 확실하게 쓰는 법

Claude Code처럼 "규칙 파일 + 서브에이전트 + 스킬"을 Codex에서 쓰려면 파일 위치와 설정이 다릅니다. 아래는 2026년 10월 Codex CLI 0.160으로 빈 폴더에서 직접 만들어 서브에이전트 호출·스킬 인식·인터넷 접속까지 확인한 최소 구성입니다.

my-agent/                                   (작업 폴더 — 1-5절 규칙대로)
├── AGENTS.md                               규칙 파일 (Claude의 CLAUDE.md 자리)
├── .codex/config.toml                      이 폴더 전용 Codex 설정
├── .codex/agents/reviewer.toml             서브에이전트 하나당 파일 하나 (.toml)
└── .agents/skills/my-report/SKILL.md       스킬 (폴더 안에 SKILL.md)

① .codex/config.toml — 이 폴더 전용 설정

sandbox_mode = "workspace-write"   # 이 폴더 안에서만 파일 생성·수정
web_search = "live"                # 내장 웹 검색을 실시간으로

[sandbox_workspace_write]
network_access = true              # Codex가 실행하는 프로그램의 인터넷 접속 허용

[windows]
sandbox = "unelevated"             # Windows: 관리자 권한 없이 동작하는 샌드박스

② 서브에이전트 — .codex/agents/reviewer.toml (세 항목 name·description·developer_instructions는 필수)

name = "reviewer"
description = "결과물을 저장하기 전에 오류와 근거 없는 문장을 검토할 때 사용한다."
sandbox_mode = "read-only"         # 읽기만 가능 — 검토자가 직접 고치지 못하게 막음
developer_instructions = """
너는 검토자다. 직접 고치지 않고 지적만 한다.
답의 첫 줄은 "검토: 통과" 또는 "검토: 지적"으로 쓴다.
"""

③ 스킬 — .agents/skills/my-report/SKILL.md

---
name: my-report
description: 작업 결과를 output 폴더에 보고서 파일로 저장할 때 사용한다.
---
- 저장 위치: output/report_YYYY-MM-DD.md
- 맨 위에 한 줄 요약, 그 아래 근거와 출처 URL

④ 폴더 신뢰 — 가장 많이 빠뜨리는 단계

• Codex는 신뢰한 폴더에서만 .codex/config.toml과 .codex/agents/를 읽습니다. 신뢰하지 않으면 파일이 있어도 서브에이전트가 default·explorer·worker만 보입니다.
• 그 폴더에서 codex를 처음 실행할 때 Trust this folder?가 뜨면 Yes.
• 질문이 안 떴는데 안 읽힌다면 ~/.codex/config.toml(Windows는 C:\Users\내이름\.codex\config.toml) 맨 아래에 직접 두 줄을 넣습니다. 경로는 내 작업 폴더로 바꾸세요.

[projects.'C:\vibecoding\my-agent']
trust_level = "trusted"

⑤ 파일은 사람이 만든다 · 이름을 불러 쓴다

• Codex의 샌드박스는 .codex/ 폴더를 보호해서, Codex에게 이 파일을 만들라고 시키면 PC에 따라 "액세스 거부"로 실패합니다. 위 파일들은 VS Code에서 직접 새 파일로 만들어 붙여넣으세요.
• 파일을 만들거나 고친 뒤에는 /quit → codex로 다시 실행해야 읽힙니다.
• Codex는 서브에이전트를 알아서 부르지 않습니다. "reviewer 서브에이전트로 검토해 줘"처럼 이름을 넣어 요청하세요. 스킬은 $my-report 또는 /skills로 부를 수 있습니다.

⑥ 인식 확인 — Codex에 이렇게 물어서 내 서브에이전트와 스킬 이름이 모두 나오면 준비 완료입니다.

사용할 수 있는 서브에이전트(agent_type)와 이 폴더 스킬 이름을 알려줘

✅ 체크포인트: 답에 reviewer와 my-report가 보이면 성공입니다. 안 보이면 ④(신뢰) → 파일 위치 → 재시작 순서로 확인하세요.

---

참고문헌

1. 조태호, 『혼자 공부하는 바이브코딩 with 클로드코드』 공식 GitHub. https://github.com/taehojo/vibecoding
2. Claude Code 설치·설정 공식 문서. https://code.claude.com/docs/en/setup
3. Claude Code VS Code 확장 공식 문서. https://code.claude.com/docs/en/vs-code
4. Anthropic, 모델 개요(Claude Opus 5.5 · Sonnet 5.5 · Haiku 4.5). https://platform.claude.com/docs/en/about-claude/models/overview
5. OpenAI Codex 공식 저장소(설치 명령). https://github.com/openai/codex
6. OpenAI Codex 모델 목록·종료 일정. https://learn.chatgpt.com/docs/models
7. OpenAI Codex 변경 이력. https://learn.chatgpt.com/docs/changelog
8. Google, Gemini CLI → Antigravity CLI 이전 안내(2026.6.18). https://antigravity.google/docs/gcli-migration
9. Google Antigravity CLI 설치·인증 공식 문서. https://antigravity.google/docs/cli/install/
10. Google Antigravity CLI 설정(settings.json) 문서. https://antigravity.google/docs/cli/settings/
11. 파이썬 공식 문서 — venv 가상환경. https://docs.python.org/ko/3/library/venv.html
12. 파이썬 공식 문서 — 모듈 설치하기(pip). https://docs.python.org/ko/3/installing/index.html
13. Visual Studio Code 공식 다운로드. https://code.visualstudio.com
14. Node.js 공식 다운로드(LTS). https://nodejs.org
15. OpenAI Codex 서브에이전트(.codex/agents) 문서. https://learn.chatgpt.com/docs/agent-configuration/subagents
16. OpenAI Codex 스킬(.agents/skills) 문서. https://learn.chatgpt.com/docs/build-skills
17. Using Codex with your ChatGPT plan. https://help.openai.com/en/articles/11369540-using-codex-with-your-chatgpt-plan
18. Google Antigravity 서브에이전트 문서. https://antigravity.google/docs/subagents/
19. Google Antigravity 스킬 문서. https://antigravity.google/docs/skills/

도구 버전·모델·요금·전환 일정은 2026년 10월 기준이며 변경이 잦습니다. 위 1차 출처에서 최신 정보를 확인하세요.