Chapter 9: 본격 준비 — 코딩 전 세팅할 것들

지금까지 우리는 바이브 코딩의 개념을 배우고, 도구를 설치하고, 첫 번째 체험까지 해봤습니다. 이제 본격적으로 프로젝트를 시작하기 전에 작업 환경을 제대로 세팅하는 단계입니다.

9.1 MCP 서버 설정 — AI에게 팔다리를 달아주기

**MCP(Model Context Protocol)**는 AI가 외부 도구를 사용할 수 있게 해주는 표준 프로토콜입니다. 기본 상태의 AI는 텍스트만 주고받을 수 있지만, MCP를 설정하면 파일을 읽고 쓰고, 브라우저를 조작하고, 데이터베이스를 쿼리할 수 있습니다.

핵심 MCP 서버 종류

| MCP 서버 | 역할 | 음악 비유 | |-----------|------|-----------| | filesystem | 파일 읽기/쓰기 | 하드디스크 레코더 | | playwright | 브라우저 자동 조작 | 라이브 비디오 피드 | | fetch | 웹 URL 내용 가져오기 | 샘플 라이브러리 다운로드 | | memory | 대화 간 정보 기억 | 노트북에 메모하기 | | sqlite | 데이터베이스 쿼리 | 곡 목록 데이터베이스 | | sequential-thinking | 단계별 사고 | 편곡 스케치 |

실제 MCP 설정 파일 작성법

MCP 설정은 JSON 파일로 작성합니다. 프로젝트 루트에 .mcp.json 파일을 만들면 됩니다.

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y", "@modelcontextprotocol/server-filesystem",
        "/home/사용자/my-project"
      ]
    },
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    },
    "fetch": {
      "command": "uvx",
      "args": ["mcp-server-fetch"]
    },
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"]
    }
  }
}

Claude Code의 MCP 설정 위치

Claude Code에서는 두 가지 위치에 MCP를 설정할 수 있습니다:

# 글로벌 설정 (모든 프로젝트에 적용)
~/.claude.json

# 프로젝트별 설정 (해당 프로젝트에만 적용)
프로젝트루트/.mcp.json

9.2 AGENTS.md / CLAUDE.md — AI에게 악보를 주기

AGENTS.md (Codex용) 또는 CLAUDE.md (Claude Code용)는 AI에게 프로젝트의 맥락, 규칙, 스타일을 알려주는 지침 파일입니다. 이 파일이 있으면 AI는 매번 같은 설명을 반복하지 않아도 프로젝트를 이해합니다.

AGENTS.md 실습 — MediaPipe 프로젝트용

우리의 목표 프로젝트(MediaPipe + Ableton/TouchDesigner)를 위한 AGENTS.md를 작성해봅시다:

# MediaPipe Hand Controller

## 프로젝트 개요
MediaPipe Hands를 사용하여 웹캠으로 손동작을 인식하고,
OSC 프로토콜로 Ableton Live와 TouchDesigner에 제어 신호를 보내는
웹 기반 인터페이스입니다.

## 기술 스택
- **프론트엔드**: HTML + CSS + Vanilla JavaScript (프레임워크 미사용)
- **손 추적**: MediaPipe Hands (CDN 로드)
- **통신**: OSC over WebSocket (osc.js 라이브러리)
- **서버**: Node.js + Express (OSC 브릿지 역할)

## 코딩 규칙
- 한국어 주석을 반드시 작성할 것
- 변수명은 영어 camelCase 사용
- 모든 함수에 JSDoc 주석 포함
- console.log는 디버그 시에만, 프로덕션에서는 제거

## 디렉토리 구조
\`\`\`
src/
  index.html          # 메인 페이지
  css/style.css       # 스타일
  js/
    hand-tracker.js   # MediaPipe 손 추적
    osc-sender.js     # OSC 메시지 전송
    ui-controller.js  # UI 업데이트
server/
  bridge.js           # WebSocket-to-OSC 브릿지
\`\`\`

## 개발 환경
- Node.js v20+
- 테스트용 브라우저: Chrome (WebRTC 카메라 지원)
- Ableton Live 11/12 또는 TouchDesigner 2023+

좋은 지침 파일의 3요소

1. 구체적인 기술 스택: "웹 프로젝트"보다 "HTML + Vanilla JS + MediaPipe CDN"이 낫습니다
2. 명확한 코딩 규칙: AI가 일관된 스타일로 코드를 생성합니다
3. 디렉토리 구조: AI가 파일을 어디에 만들어야 하는지 압니다

9.3 Plan Mode — 작곡 전 스케치하기

Plan Mode는 AI에게 코드를 작성하기 전에 설계만 먼저 하자고 요청하는 방식입니다. 코드를 바로 생성하면 방향이 틀어졌을 때 처음부터 다시 해야 하지만, 설계를 먼저 논의하면 수정이 쉽습니다.

Plan Mode 사용법

# Codex CLI에서
codex "MediaPipe로 손가락 움직임을 추적해서 Ableton의 
볼륨을 제어하는 웹앱을 만들고 싶어. 
코드 작성하지 말고, 먼저 전체 구조와 필요한 
기술 스택을 설계해줘."

"이 설계에서 WebSocket 부분이 복잡해 보이는데, 
더 간단한 방법은 없어? 
그리고 TouchDesigner 연결도 고려해줘."

"좋아, 이 설계대로 가자. 
먼저 1단계: 기본 HTML 구조와 카메라 연결부터 만들어줘."

9.4 자료 조사 — 참고 트랙 수집하기

바이브 코딩에서 가장 중요하면서 간과되는 단계가 자료 조사입니다. AI는 학습 데이터에 있는 것만 알고 있으므로, 최신 라이브러리의 API 변경사항이나 특수한 사용법은 우리가 직접 찾아서 알려줘야 합니다.

자료 조사 워크플로우

# fetch MCP를 사용해서 AI에게 문서를 읽히기
"이 URL의 내용을 읽고 정리해줘: 
https://ai.google.dev/edge/mediapipe/solutions/vision/hand_landmarker/web_js"

# 또는 파일로 저장해두고 참조
curl -o docs/mediapipe-hands-api.md \\
  "https://ai.google.dev/edge/mediapipe/solutions/vision/hand_landmarker/web_js"

# 참고할 만한 프로젝트의 핵심 코드를 docs/ 폴더에 저장
mkdir -p docs/references
# 핵심 코드 조각만 복사하여 저장
# docs/references/mediapipe-example.js
# docs/references/osc-bridge-example.js

# 방법 1: 파일 경로로 참조
codex "docs/references/mediapipe-example.js 파일을 참고해서 
우리 프로젝트의 hand-tracker.js를 만들어줘."

# 방법 2: 직접 붙여넣기 (짧은 코드)
codex "다음 코드를 참고해서 작성해줘:
\\\`\\\`\\\`javascript
const hands = new Hands({locateFile: (file) => {
  return \\\`https://cdn.jsdelivr.net/npm/@mediapipe/hands/\\\${file}\\\`;
}});
\\\`\\\`\\\`"

9.5 프로젝트 디렉토리 구조 잡기

코딩을 시작하기 전에 폴더 구조를 미리 결정하는 것이 중요합니다. AI가 파일을 생성할 때 어디에 놓아야 하는지 알 수 있기 때문입니다.

mediapipe-controller/
├── .mcp.json           # MCP 서버 설정
├── AGENTS.md           # Codex용 지침
├── CLAUDE.md           # Claude Code용 지침
├── .gitignore          # Git 제외 목록
├── package.json        # Node.js 의존성
├── src/
│   ├── index.html      # 메인 페이지
│   ├── css/
│   │   └── style.css
│   └── js/
│       ├── hand-tracker.js
│       ├── osc-sender.js
│       └── ui-controller.js
├── server/
│   └── bridge.js       # OSC 브릿지 서버
├── docs/
│   └── references/     # 참고 자료
└── tests/              # 테스트 코드

9.6 전체 세팅 체크리스트

모든 준비가 끝났는지 확인해봅시다:

9.7 실습 과제

다음 장으로 넘어가기 전에, 직접 해보세요:

1. 자신의 프로젝트 폴더를 생성하고 Git을 초기화하세요
2. .mcp.json에 filesystem과 fetch MCP를 설정하세요
3. AGENTS.md에 자신만의 프로젝트 설명을 작성하세요 (최소 20줄)
4. 참고할 만한 자료를 2개 이상 찾아서 docs/references/에 저장하세요
5. 모든 세팅을 Git에 커밋하세요

이 준비가 끝나면, 다음 장에서 MCP와 Skills의 심화 옵션을 다루겠습니다.