<바이브 코딩 심화> 가이드

0. 가장 먼저 보는 "개념 대응표"

바이브 코딩 도구의 확장 기능은 6개 부품으로 정리됩니다. 세 도구에서 이름이 어떻게 다른지 한눈에 보세요.

비유로 한 번에 이해하기 - 메모리 파일 = 신입에게 주는 업무 매뉴얼 (매일 아침 읽음)
- 슬래시 명령어 = 리모컨 버튼 (내가 눌러서 조종)
- 커스텀 명령어 = 내가 만든 나만의 리모컨 버튼 - 스킬 = 상황 보고 알아서 꺼내 쓰는 전문 매뉴얼 - 서브에이전트 = 일을 떼어 맡기는 별도 직원 (자기 책상=문맥을 따로 씀)
- 훅 = "이 일 끝나면 자동으로 ○○해" 하는 자동 알람 - MCP = 외부 회사와 연결하는 전용 전화선

---

1. 슬래시 명령어의 기본기 (3도구 공통)

1-1. 슬래시 명령어란?

세션 입력창에 / 를 치면 뜨는 조종 명령입니다. AI에게 보내는 일반 프롬프트와 달리, 세션 자체(모델 변경·문맥 정리·승인 설정 등)를 다룹니다.

• 입력창에 / 를 치면 명령 목록 팝업이 뜹니다. 계속 타이핑하면 필터링됩니다.
• 세 도구 모두 /help 로 현재 버전에서 쓸 수 있는 전체 목록을 볼 수 있습니다. (가장 확실한 방법)

1-2. 슬래시와 함께 쓰는 두 기호: @ 와 ! (3도구 공통)

슬래시(/)는 세션 조종, 골뱅이(@)는 맥락 첨부, 느낌표(!)는 터미널 직접 실행. 이 3개만 알아도 절반은 끝납니다.

---

2. 도구별 핵심 내장 슬래시 명령어

도구마다 명령이 수십 개지만, 초보가 실제로 자주 쓰는 것만 추렸습니다. 전체는 /help 참고.

2-1. Claude Code (90개 이상 중 핵심)

플랜 모드: Shift+Tab 으로 모드를 순환하면 계획만 세우고 실행은 멈추는 플랜 모드로 들어갈 수 있습니다. 큰 작업 전 안전장치.

2-2. OpenAI Codex (60개 이상 중 핵심)

샌드박스(권한) 모드: read-only(읽기) → workspace-write(작업 폴더 쓰기) → danger-full-access/--yolo(전체 허용). --yolo는 승인·보호를 모두 끄므로 격리 환경에서만! Alt+, / Alt+. 로 추론(reasoning) 깊이를 낮추거나 높일 수 있습니다.

2-3. Gemini CLI (50개 이상 중 핵심)

승인 모드: default / auto_edit(자동 편집) / yolo(전체 허용) / plan(계획만). Ctrl+Y 또는 Shift+Tab 으로 토글.
2026.6.18 전환: 개인용·AI Pro·Ultra는 기존 Gemini CLI가 Antigravity CLI로 이전됩니다. 명령 체계는 유사하나, 설치 경로·문서를 재확인하세요.

---

3. 메모리 파일 — CLAUDE.md · AGENTS.md · GEMINI.md

3-1. 왜 가장 중요한가?

이 파일은 AI의 "헌법"입니다. 매 세션 자동으로 읽혀서, 매번 프로젝트 설명을 반복하지 않아도 됩니다. 고급 기능을 건드리기 전에 이 파일부터 제대로 써야 효과가 큽니다.

• 세 도구 모두 /init 명령으로 초안을 자동 생성할 수 있습니다.
• 파일은 프로젝트 폴더 최상단에 둡니다. (전역 규칙은 각 도구의 홈 디렉터리에)

3-2. 작성 예시 (세 파일 내용은 거의 동일하게 써도 됨)

# 프로젝트 개요
이 저장소는 미디어학과 수업용 뉴스 분석 파이썬 프로젝트다.

# 코딩 규칙
- 모든 주석과 설명은 한국어로 작성한다.
- 의존성은 requirements.txt에 명시하고, 불필요한 라이브러리는 추가하지 않는다.
- 함수에는 한 줄 설명을 단다.

# 자주 쓰는 명령
- 테스트:  pytest
- 실행:    python main.py

# 하지 말 것
- .env 파일을 절대 커밋하지 않는다.
- 대규모 리팩터링은 먼저 계획을 보여주고 승인받는다.

차이점 요약 | | 파일명 | 전역(글로벌) 위치 | 초안 생성 |
|---|---|---|---|
| Claude | CLAUDE.md | ~/.claude/CLAUDE.md | /init |
| Codex | AGENTS.md | ~/.codex/AGENTS.md | /init |
| Gemini | GEMINI.md | ~/.gemini/GEMINI.md | /init |

팁: 규칙은 짧고 명령형으로. "되도록 깔끔하게" 같은 모호한 말보다 "함수는 30줄을 넘기지 말 것"처럼 검증 가능한 규칙이 잘 지켜집니다.

---

4. 커스텀 슬래시 명령어 만들기

자주 쓰는 긴 프롬프트를 나만의 /명령 한 단어로 저장합니다. 예: /리뷰, /한글주석, /커밋메시지.

4-1. Claude Code

.claude/commands/ 폴더에 .md 파일을 만들면 파일명이 곧 명령이 됩니다.

mkdir -p .claude/commands
cat > .claude/commands/한글주석.md << 'EOF'
방금 작성한 코드에 초보자가 이해하기 쉬운 한국어 주석을 충분히 달아 줘.
대상 파일: $ARGUMENTS
EOF

→ 이제 /한글주석 src/main.py 처럼 사용. ($ARGUMENTS=전체 인자, $1 $2=위치 인자)

4-2. OpenAI Codex

~/.codex/prompts/ 폴더에 최상위 .md 파일을 둡니다. (하위 폴더는 인식 안 함)

mkdir -p ~/.codex/prompts
cat > ~/.codex/prompts/draftpr.md << 'EOF'
변경 내용을 요약해 PR 설명 초안을 만들어 줘. 제목과 본문을 나눠서.
EOF

→ /prompts:draftpr 로 호출. (인자는 $1, $2 …)

최근 Codex는 커스텀 프롬프트보다 "스킬"을 권장하는 방향입니다(5절 참고).

4-3. Gemini CLI

.gemini/commands/ 폴더에 .toml 파일을 만듭니다.

mkdir -p .gemini/commands
cat > .gemini/commands/plan.toml << 'EOF'
description = "구현 없이 단계별 계획만 세운다."
prompt = "다음 작업의 단계별 계획만 작성해. 코드는 쓰지 마: {{args}}"
EOF

→ /commands reload 후 /plan 인증 모듈 리팩터링 사용.

• 하위 폴더로 네임스페이스 가능: .gemini/commands/git/commit.toml → /git:commit
• {{args}} 자리에 사용자가 넘긴 인자가 들어갑니다.

---

5. 스킬(Skills) — 상황 보고 자동 발동하는 전문 능력

5-1. 커스텀 명령어와 무엇이 다른가?

• 커스텀 명령어 = 내가 /명령으로 직접 부른다.
• 스킬 = AI가 상황(맥락)을 보고 알아서 꺼내 쓴다(원하면 수동 호출도 가능). 예: "엑셀 파일이 보이면 자동으로 엑셀 처리 능력을 로드".

5-2. Claude Code (가장 정돈됨)

.claude/skills/<이름>/SKILL.md 폴더 구조로 만듭니다. 2026년 기준 슬래시 명령어와 스킬이 통합되어, 모든 스킬은 /스킬이름 으로도 부를 수 있습니다.

---
name: news-cleaner
description: 뉴스 CSV의 중복·결측을 정리할 때 사용한다.
# 프론트매터로 자동 발동 여부, 메뉴 노출, 서브에이전트 실행을 제어
---
# 뉴스 CSV 정리 절차
1. 중복 기사 제거 (제목+날짜 기준)
2. 빈 본문 행 표시
...

• 인자 치환: $ARGUMENTS, $1 $2, 스킬 폴더 경로 ${CLAUDE_SKILL_DIR}.

5-3. Codex / Gemini

• Codex: /skills 로 보기, $스킬이름 으로 직접 호출. (커스텀 프롬프트의 후속 개념)
• Gemini: /skills·확장(Extension) 형태로 제공(버전에 따라 다름). /skills 로 확인.

---

6. 서브에이전트(Subagents) — 일을 떼어 맡기는 독립 일꾼

6-1. 왜 쓰는가?

복잡한 작업을 별도의 두뇌(독립 문맥)에게 맡기면, ① 본 대화가 깔끔하게 유지되고 ② 토큰을 아끼며 ③ 역할별 전문화가 됩니다. 예: "코드 탐색 담당", "리뷰 담당".

6-2. Claude Code

.claude/agents/ 에 정의하거나 /agents 로 관리합니다. 내장 유형:

• Explore: 읽기 전용 코드베이스 탐색
• Plan: 실행 없이 계획 수립
• general-purpose: 범용

---
name: reviewer
description: 보안·테스트 관점으로 변경 코드를 검토한다.
tools: Read, Grep, Bash
model: haiku        # 가벼운 작업은 저렴한 모델로
---
너는 까다로운 코드 리뷰어다. 보안 취약점과 누락된 테스트를 우선 지적해라.

6-3. Codex / Gemini

• Codex: 서브에이전트 스레드로 분기, 리뷰를 guardian 서브에이전트로 라우팅 가능. /agents.
• Gemini: /agents list 로 서브에이전트 확인·관리.

선택 기준: 작업이 독립된 문맥을 필요로 하면 서브에이전트, 단순 반복이면 커스텀 명령어/스킬.

---

7. 훅(Hooks) — 특정 순간 자동 실행

7-1. 개념

"도구 실행 전/후"나 "프롬프트 제출 시" 같은 이벤트에 내 스크립트를 자동 실행합니다. 예: 코드 저장 후 자동 포맷팅, 비밀키가 들어가면 차단, 작업 끝나면 알림.

7-2. Claude Code (가장 세밀)

settings.json 에 이벤트별로 등록합니다. 대표 이벤트: PreToolUse(도구 실행 전), PostToolUse(후), UserPromptSubmit(프롬프트 제출 시), Notification, Stop 등.

// .claude/settings.json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [{ "type": "command", "command": "black ." }]
      }
    ]
  }
}

→ 파일을 수정/작성할 때마다 자동으로 black(파이썬 포매터) 실행.

7-3. Codex / Gemini

• Codex: /hooks 관리. 예) userpromptsubmit 훅으로 프롬프트를 차단하거나 보강한 뒤 실행.
• Gemini: /hooks 로 관리.

훅은 자동으로 명령을 실행하므로, 신뢰할 수 있는 스크립트만 등록하세요.

---

8. MCP — 외부 도구 연결 (Model Context Protocol)

8-1. 개념

MCP는 AI를 깃허브·노션·DB·브라우저·구글 워크스페이스 같은 외부 도구에 연결하는 표준 규격(전용 전화선)입니다. 한 번 연결하면 세 도구 모두 동일하게 "외부 도구를 호출"할 수 있습니다. (세 도구 다 /mcp 로 상태 확인)

8-2. 도구별 설정 위치

8-3. 예시 — 깃허브 MCP 서버 (Claude 기준)

// .mcp.json
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "여기에_토큰" }
    }
  }
}

→ 이후 /mcp 로 연결 확인 후 "내 깃허브 이슈 목록 가져와" 처럼 자연어로 요청.

토큰·키는 항상 환경변수/.env로. 설정 파일을 깃허브에 올릴 땐 키가 없는지 확인.

8-4. 플러그인 / 확장 (여러 부품을 한 번에 묶어 배포)

• Claude: 플러그인 = 스킬+서브에이전트+명령어+훅+MCP를 한 묶음으로 설치(/plugin).
• Codex: /plugins, /apps.
• Gemini: 확장(Extension) = 커스텀 명령어+MCP+GEMINI.md를 한 패키지로(gemini extensions, /extensions).

---

9. 다중·병렬 에이전트 — 여러 일꾼을 동시에

6장의 서브에이전트가 '일꾼 하나'라면, 이 장은 일꾼을 여럿, 동시에 굴리는 단계입니다. 대규모 리팩터링·코드베이스 전체 감사·다각도 검증처럼 한 대화로는 조율이 벅찬 작업에 씁니다. (이 기능들은 Claude Code에서 가장 성숙합니다. Codex·Gemini에도 백그라운드/병렬 실행이 있으나 명칭·완성도가 달라 각 도구 /help·공식 문서를 확인하세요.)

9-2. Claude Code — 4가지 병렬 방식

• 에이전트 뷰: 각 세션을 자동으로 별도 워크트리(git worktree)에 격리하고 상태를 한 줄씩 보여줍니다. 입력이 필요한 세션에만 부착.
• 다이내믹 워크플로: 조율·중간결과가 스크립트 안에 있어 대화 문맥엔 최종 답만 남습니다. 한 런에 동시 16개·총 1,000개까지, 진행상황이 저장돼 중단돼도 이어서 실행. (v2.1.154+, 유료 플랜·API·Bedrock·Vertex·Foundry)
• /batch: 큰 변경을 5~30개의 워크트리 격리 서브에이전트로 쪼개 각각 PR을 엽니다.

선택 기준 — 한 번의 병렬 판단이면 서브에이전트, 서로 대화하며 오래 협업하면 에이전트 팀, 앞 단계 결과가 다음 단계를 좌우하거나 서로의 결과를 반증(adversarial verify)시키려면 다이내믹 워크플로, 감독 화면이 필요하면 에이전트 뷰.

비용 주의: 에이전트 10개를 병렬로 돌리면 토큰(=구독 할당량·비용)도 약 10배로 나갑니다. 반드시 작은 범위로 먼저 시험하세요.

---

10. 반복·장기 실행·예약 — 시간을 다루기

같은 일을 반복하거나, 오래 걸리는 일을 백그라운드로 떼어 돌리거나, 내가 없을 때 예약 실행하는 세 축입니다.

10-2. Claude Code — /loop·/goal·백그라운드·예약

세 자동화 축 구분 — 훅(7장)은 이벤트에 반응, /loop는 당신이 있는 동안 타이머로 반복, 루틴은 당신이 없을 때 예약 실행.

구독 한도 주의: /loop은 대화형 세션이라 5시간·주간 한도를 그대로 씁니다. 반면 헤드리스 자동화(claude -p·Agent SDK)는 2026-06-15부터 대화 한도가 아니라 별도 월 크레딧에서 차감되고, 소진되면 멈춥니다. 수천 건을 /loop으로 도는 건 한도상 비현실적입니다.

---

11. 대량 배치 처리 & 재현성 — 데이터·연구 작업

수천~수만 건의 독립적·동일한 작업(예: 기사마다 취재원 추출·투명/익명 분류, 대량 라벨링·요약)은 대화형 도구가 아니라 Message Batches API가 정답입니다.

• 한 배치 최대 10만 건(또는 256MB), 50% 할인, 대부분 1시간 내(상한 24시간). custom_id로 결과 매핑, 웹훅 없이 폴링, 결과 29일 보관 → 받는 즉시 영구 저장.
• 모든 요청이 같은 시스템 프롬프트를 쓰면 프롬프트 캐싱이 배치 할인 위에 겹쳐 비용이 더 내려갑니다.
• 다단계(추출→검증→분류)나 상호 반증이 필요하면 다이내믹 워크플로(9장)를 얹습니다.

11-2. 재현성 주의 — 시드로 "똑같이" 재현되지 않는다

• Claude API에는 시드(seed) 파라미터가 없습니다. 시드 기반 리플레이 자체가 불가.
• 온도 0에서도 완전히 결정적이지 않습니다(Anthropic 문서 명시) — GPU 부동소수점·요청 배칭·MoE 라우팅 때문.
• 연구용 재현성은 통계적 재현으로: 조건당 다수 반복 → 분포·신뢰구간 보고(예: GLMM), 모델 스냅샷·파라미터 고정, 프롬프트·응답 전량 로깅. "전사(transcript)"가 아니라 "발견"을 재현.
• 비트 단위 정확 재현이 꼭 필요하면 로컬 오픈모델(vLLM/PyTorch 시드 고정+동적 배칭 비활성)만이 답.

소셜 시뮬레이션·에이전트 페르소나 실험에 에이전트 팀을 쓰면 병렬·비동기 탓에 재현성이 더 나빠집니다. 통제된 실험은 Agent SDK나 커스텀 루프(스케줄러·순서·로깅을 직접 소유)로 구성하세요.

---

12. 언제 무엇을 쓸까? — 의사결정 가이드

무엇을 자동화/확장하고 싶은가?
├── 항상 지켜야 할 규칙                → ② 메모리 파일 (CLAUDE/AGENTS/GEMINI.md)
├── 내가 직접 부르는 반복 프롬프트      → ③ 커스텀 슬래시 명령어
├── 상황 보고 '알아서' 적용될 지식      → ④ 스킬(Skill)
├── 독립 문맥이 필요한 큰 하위 작업      → ⑤ 서브에이전트
├── 여러 작업을 '동시에' 병렬로         → 다중 에이전트: 뷰·팀·워크플로 (9장)
├── 조건 충족까지 '반복'               → /loop + /goal (10장)
├── 내가 없을 때 '예약' 실행           → 루틴·스케줄드 디플로이먼트 (10장)
├── 수천~수만 건 '대량' 처리           → Message Batches API (11장)
├── 특정 순간 '자동으로' 실행할 동작     → ⑥ 훅(Hook)
└── 외부 서비스(깃허브·DB·노션) 연결    → ⑦ MCP

---

13. 안전 수칙 & 자주 막히는 곳

안전 수칙

1. --yolo / danger-full-access 는 격리 환경에서만. 승인·샌드박스를 모두 끕니다.
2. 비밀키는 절대 코드·설정 파일에 직접 쓰지 않기. .env + .gitignore.
3. 큰 작업은 플랜 모드로 먼저 계획 확인 (/plan, Claude는 Shift+Tab).
4. 훅·MCP·플러그인은 신뢰할 수 있는 출처만 등록(자동 실행되기 때문).
5. 병렬 에이전트는 할당량·비용을 N배로 소모. 작은 범위부터, 무인 방치 금지.
6. 무인 자동실행(루틴·백그라운드)에 파괴적 작업(삭제·배포) 금지. auto·bypass 권한 모드 주의.
7. 배치 결과는 29일 만료 → 받는 즉시 영구 저장(DB·파일).

자주 막히는 곳

---

참고문헌

1. Claude Code 공식 문서(슬래시 명령어·서브에이전트·스킬·훅·MCP). https://docs.claude.com/en/docs/claude-code
2. Claude Code 기능·설정 레퍼런스(2026). https://hidekazu-konishi.com/entry/claude_code_features_settings_reference_2026.html
3. OpenAI Codex — Slash commands(공식). https://developers.openai.com/codex/cli/slash-commands
4. OpenAI Codex — Custom prompts(공식). https://developers.openai.com/codex/custom-prompts
5. Codex Slash Commands 레퍼런스(2026.6). https://explainx.ai/blog/codex-slash-commands-complete-reference-guide-2026
6. Gemini CLI — CLI commands(공식). https://geminicli.com/docs/reference/commands/
7. Gemini CLI — Custom commands(공식). https://geminicli.com/docs/cli/custom-commands/
8. Gemini CLI 저장소(GEMINI.md·확장·MCP). https://github.com/google-gemini/gemini-cli
9. Gemini CLI 커스텀 슬래시 명령 발표(Google Cloud Blog). https://cloud.google.com/blog/topics/developers-practitioners/gemini-cli-custom-slash-commands
10. Claude Code — 다이내믹 워크플로(공식). https://code.claude.com/docs/en/workflows
11. Claude Code — 서브에이전트·에이전트 뷰·에이전트 팀(공식). https://code.claude.com/docs/en/agents
12. Claude Code — 명령어 레퍼런스(공식). https://code.claude.com/docs/en/commands
13. Message Batches API(공식). https://docs.claude.com/en/docs/build-with-claude/batch-processing
14. Pro/Max로 Claude Code 사용·한도(공식). https://support.claude.com/en/articles/11145838-use-claude-code-with-your-pro-or-max-plan
15. Agent SDK 구독 크레딧 분리(2026-06-15, 공식). https://support.claude.com/en/articles/15036540-use-the-claude-agent-sdk-with-your-claude-plan

도구 버전·명령어·기본 모델·전환 일정은 2026년 6월 기준이며 매우 자주 바뀝니다. 항상 각 도구에서 /help를 먼저 확인하고, 위 공식 문서를 참고하세요.