Vibe Coding 제대로 활용하기

들어가며

바이브 코딩(Vibe Coding)이 개발자들 사이에서 빠르게 확산되고 있습니다. Andrej Karpathy가 명명한 이 개발 방식은 "코드를 직접 작성하는 대신, AI와 함께 코드의 흐름을 타며 감으로 개발하는 것"을 의미합니다.

하지만 단순히 AI에게 모든 걸 맡기는 방식으로는 한계가 있습니다. 바이브 코딩을 프로젝트에 적용하다 보면 다음과 같은 문제를 겪을 수 있습니다.

이 문제들은 MCP 서버와 단계별 검증 방식으로 해결할 수 있습니다.

• MCP 서버로 PDF, Word, PPT 문서를 AI가 이해할 수 있는 형태로 변환
• 마크다운으로 컨텍스트를 구조화하여 토큰 효율과 정확도 향상
• 단계별 검증으로 검증 부담 최소화

이 글에서는 실제 프로젝트에 적용하면서 효과적이었던 방법들을 정리했습니다.

1. 환경 셋업

1.1 MCP 서버 구성

MCP(Model Context Protocol)를 쓰면 AI가 PDF, PPT 문서, DB 스키마, 코드 구조 같은 것들도 이해할 수 있게 됩니다. 파일의 텍스트를 직접 복사 붙여넣기 하는 것보다 정확하게 정보를 전달할 수 있습니다.

제가 활용한 MCP 서버는 이렇습니다.

MarkItDown: 문서 기반 코드 생성

외부 API 연동할 때 제일 귀찮은 게 PDF 문서를 읽는 겁니다. 인증 방식, 파라미터 스펙, 에러 코드 등 수십 페이지를 정리하다 보면 시간이 꽤 걸립니다.

MarkItDown MCP를 쓰면 이렇게 할 수 있습니다.

"이 API 문서 PDF를 읽고 연동 코드를 작성해줘"

AI가 문서에 있는 인증 방식, 에러 코드, 파라미터 스펙을 이해하고 그에 맞는 연동 코드를 생성합니다.

주의사항:

• 스캔된 PDF는 텍스트 추출이 어렵습니다. 텍스트 기반 PDF를 사용해야 합니다.

Serena (Java LSP): 의미 기반 코드 분석

AI에게 코드 수정을 시키면 보통 텍스트 검색으로 대상을 찾는데, 잘 안 될 때가 있습니다.

• 유틸 클래스로 감싼 호출을 못 찾음
• 상속받은 메서드를 놓침
• 타입 정보 없이 추측으로 수정함
• 여러 파일을 탐색하느라 토큰을 많이 소비함

Serena는 Java LSP를 연동해서 코드를 의미적으로 분석합니다.

"UserService를 상속받는 모든 클래스에서 validateUser를 오버라이드한 부분을 찾아줘"

IDE에서 F12를 눌러 정의로 이동하듯이 AI도 의미적으로 코드를 분석할 수 있습니다.

주의사항: 빌드 에러가 있으면 LSP 분석도 부정확해집니다. 먼저 빌드를 성공시킨 후 사용하는 것을 권장합니다.

PostgreSQL MCP: 실제 스키마 기반 개발

PostgreSQL MCP를 연결해두면 실제 테이블 구조를 보면서 작업할 수 있습니다.

"users 테이블 구조를 보여줘"
"이 스키마를 기반으로 회원가입 API를 만들어줘"

주의사항: 반드시 개발 DB에만 연결해야 합니다. 운영 DB 연결은 위험합니다.

그 외 유용한 MCP 서버들

상황에 맞는 MCP 서버를 붙여두면 AI가 더 정확한 컨텍스트로 작업할 수 있습니다.

1.2 MCP 서버 설정 방법

Claude Code에서 MCP 서버를 설정하는 방법은 두 가지가 있습니다.

/mcp 명령어로 설정

Claude Code 내에서 /mcp 명령어를 사용하면 대화형으로 MCP 서버를 추가할 수 있습니다.

/mcp add postgres -- mcp-server-postgres postgresql://localhost:5432/dev

.mcp.json 파일로 설정

프로젝트 루트에 .mcp.json 파일을 생성하면 설정을 Git으로 관리할 수 있습니다.

{
  "mcpServers": {
    "postgres": {
      "command": "mcp-server-postgres",
      "args": ["postgresql://localhost:5432/dev"]
    },
    "markitdown": {
      "command": "uvx",
      "args": ["markitdown-mcp"]
    }
  }
}

설정 방법 비교:

프로젝트 설정을 표준화하려면 .mcp.json을 사용하는 것을 권장합니다.

1.3 프로젝트 설정 구조

프로젝트/
├── CLAUDE.md                 # 프로젝트 설명서 (자동 로드)
├── .claude/
│   ├── commands/             # 커스텀 명령어
│   │   ├── generate-api.md
│   │   └── review-pr.md
│   ├── skills/               # 재사용 가능한 스킬
│   │   └── code-review.md
│   └── agents/               # 도메인 가이드
│       ├── api-integration.md
│       └── error-handling.md
└── .mcp.json                 # MCP 서버 설정

CLAUDE.md

프로젝트 루트에 두면 Claude Code가 자동으로 읽습니다. 매번 "이 프로젝트는요..."라고 설명할 필요가 없어집니다.

# CLAUDE.md

## 빌드 명령어
./mvnw clean package

## 프로젝트 구조
- controller/: REST API 엔드포인트
- service/: 비즈니스 로직
- repository/: 데이터 접근 계층

## 코딩 규칙
- HTTP 메서드는 GET, POST만 사용
- 삭제 작업은 POST /xxx/delete 형태로 구현

에이전트 (agents/)

반복되는 작업 유형별로 가이드 문서를 만들어둡니다.

# api-integration.md

## 인증 방식
- 토큰 발급: Basic Auth
- API 호출: Bearer Token

## 에러 처리 규칙
- 4xx: 클라이언트 에러로 처리
- 5xx: 재시도 로직 추가

## 로깅 규칙
- 요청/응답 전체 로깅
- 민감정보는 마스킹 처리

활용 예시.

"api-integration 에이전트를 참고해서 결제 API를 연동해줘"

가이드를 읽고 패턴에 맞춰 코드를 생성합니다.

Commands와 Skills

Claude Code에서는 반복 작업을 자동화하는 두 가지 방법이 있습니다.

Commands: 직접 호출하는 명령어

.claude/commands/generate-api.md를 만들면 /generate-api로 실행합니다.

---
description: API 명세서 생성
allowed-tools: Read, Glob, Grep, Bash
---

# API 명세서 생성
1. controller/ 디렉토리의 모든 컨트롤러 분석
2. Request/Response DTO 추출
3. Markdown 테이블 형식으로 정리

Skills: AI가 알아서 참조하는 가이드

.claude/skills/code-review.md를 만들어두면, 코드 리뷰 관련 작업을 할 때 AI가 자동으로 참조합니다.

# 코드 리뷰 가이드

## 체크 항목
- null 체크 누락 여부
- 예외 처리 적절성
- 네이밍 컨벤션 준수

## 이 프로젝트의 규칙
- 모든 API는 try-catch로 감싸기
- 에러 로깅은 log.error() 사용

Commands는 "이거 실행해"이고, Skills는 "이런 상황에서는 이렇게 해"입니다.

2. 실전 워크플로우

2.1 단계별 검증

바이브 코딩을 하면서 불안한 부분은 "이 코드가 맞나?" 하는 것입니다.

한 번에 최종 코드까지 뽑으면 검증이 어렵습니다. 중간 산출물을 두고 빠르게 확인하는 방식이 효과적이었습니다.

패턴 A: 문서 → 시퀀스 다이어그램 → 코드

스토리보드 PPT 파일을 받아서 바로 API를 구현하면, 나중에 플로우 오류를 발견했을 때 전체를 수정해야 합니다.

1단계: "기획서를 읽고 시퀀스 다이어그램을 mermaid로 생성해줘"
2단계: 다이어그램 검토 → "에러 케이스가 빠졌네" → 수정 요청
3단계: "이 다이어그램을 기반으로 API를 구현해줘"

다이어그램은 코드보다 훨씬 빠르게 훑어볼 수 있습니다. 플로우 문제는 이 단계에서 잡는 게 편합니다.

docs/sequence/
├── 01_splash_auto_login.mmd
├── 02_social_login.mmd
├── 03_normal_login.mmd
└── ...

패턴 B: 코드 → Markdown → Excel

API 문서를 Excel로 바로 뽑으면 수정이 어렵습니다. 바이너리 파일이라 diff 추적도 안 됩니다.

1단계: "컨트롤러를 분석해서 API 명세를 Markdown으로 생성해줘"
2단계: Markdown 검토 → "필드가 누락되었네" → 수정
3단계: "Markdown을 Excel로 변환해줘"

API가 변경되면 Markdown을 업데이트하고 다시 변환합니다.

/generate-api-markdown  → 코드로부터 API 추출
/markdown-to-excel      → 공유용 엑셀로 변환

패턴 C: Postman으로 API 검증

API를 만들고 나면 직접 테스트해봐야 합니다. 저는 Postman Collection JSON을 활용했습니다.

1단계: API 구현 완료
2단계: "이 API들을 테스트할 수 있는 Postman Collection JSON을 만들어줘"
3단계: Postman에서 직접 호출해서 검증

AI가 만든 코드가 실제로 동작하는지 바로 확인할 수 있습니다.

단계별 검증의 장점

AI는 자신감 있게 틀리는 경우가 많기 때문에 검증은 필수입니다. 코드는 빠르게 훑어보고, 기능 테스트에 더 집중하는 게 효율적이었습니다.

단계별 검증의 이점.

• 검증 단위가 작음 → 빠르게 확인 가능
• 수정 범위가 좁음 → 전체 재생성 안 해도 됨
• 텍스트 기반 → diff 추적, 버전 관리 가능

"빠르게 생성하고, 빠르게 확인하고, 빠르게 수정"하는 사이클을 만드는 게 핵심입니다.

2.2 효과적인 프롬프트 패턴

예시 기반

"이것처럼 만들어줘"라는 요청이 효과적입니다.

"UserService를 참고해서 같은 패턴으로 OrderService를 만들어줘"
"이 테스트 코드 패턴으로 나머지 서비스의 테스트도 작성해줘"

문서 참조

"docs/api-spec.md를 읽고 클라이언트 코드를 생성해줘"
"이 Swagger JSON으로 TypeScript 타입을 만들어줘"

3. 환경 표준화

바이브 코딩에 필요한 설정을 잘 만들어두면 나중에 다른 사람이 와도 똑같은 방식으로 바이브 코딩할 수 있는 환경이 갖춰집니다.

Git으로 공유되는 설정

프로젝트/
├── .claude/
│   ├── commands/          # 커스텀 명령어
│   └── agents/            # 에이전트 가이드
├── CLAUDE.md              # 프로젝트 설명서
└── .mcp.json              # MCP 서버 설정

git clone만 하면 동일한 환경이 구성됩니다.

재현 가능한 바이브 코딩

컨텍스트의 표준화

CLAUDE.md에 프로젝트 구조와 규칙을 적어두면, 누가 작업하든 AI가 같은 맥락에서 시작합니다. "이 프로젝트 구조가 뭐예요?"라고 물어볼 필요가 없어집니다.

코딩 패턴 일관성

에이전트에 "이 프로젝트는 이렇게 작성한다"고 적어두면, AI가 같은 패턴으로 코드를 만듭니다. 사람이 바뀌어도 스타일이 유지됩니다.

삽질 경험의 문서화

"이 외부 API는 이런 함정이 있다" 같은 경험을 에이전트 문서에 적어두면, 다음 사람은 같은 실수를 안 해도 됩니다.

MCP 설정 공유

.mcp.json 파일로 MCP 서버 설정을 공유할 수 있습니다.

{
  "mcpServers": {
    "postgres": {
      "command": "mcp-server-postgres",
      "args": ["postgresql://${DB_USER}:${DB_PASSWORD}@localhost:5432/dev"]
    },
    "markitdown": {
      "command": "uvx",
      "args": ["markitdown-mcp"]
    }
  }
}

주의사항: DB 비밀번호와 같은 민감 정보는 환경 변수(${DB_PASSWORD})로 분리해야 합니다. .mcp.json은 Git에 커밋됩니다.

4. 주의사항

검증은 필수

AI가 자신감 있게 만든 코드에도 버그가 있을 수 있습니다.

• 경계값 처리 누락
• null 체크 누락
• 예외 케이스 미처리

리뷰는 꼭 해야 하고, 테스트 코드도 같이 만들어두는 게 좋습니다.

컨텍스트 오염

대화가 길어지면 이전 맥락이 현재 작업에 영향을 줄 수 있습니다. 새 작업은 새 세션에서 시작하는 게 깔끔합니다.

적재적소에 활용

한 줄 수정도 AI에게 시키고 싶어지는데, 간단한 건 직접 하는 게 빠릅니다.

마치며

코드를 직접 치는 것보다 의도를 명확히 전달하는 게 더 중요해졌습니다. 그리고 의도 전달을 잘 하려면 좋은 컨텍스트가 필요합니다.

• MCP 서버로 외부 문서와 데이터를 연결하기
• 단계별 검증으로 품질을 확보하기
• Commands/Agents로 반복 작업을 자동화하기
• 가이드 문서로 개발 환경 및 코드 스타일을 재현 가능하게 만들기

모든 상황에 바이브 코딩이 정답은 아닙니다. 그러나 대부분의 작업이 바이브 코딩으로 가능하고, 이 강력한 도구를 적절히 통제하고 활용할 수만 있다면 더 효율적인 개발이 가능해집니다.

참고 자료

• MCP 공식 문서
• Claude Code
• MarkItDown MCP