바이브코딩 컨텍스트 관리법 — AI에게 프로젝트 이해시키는 기술

AI에게 "이 프로젝트를 수정해줘"라고 하면 엉뚱한 코드가 나온다. AI가 내 프로젝트를 제대로 파악하게 만드는 것이 바이브코딩 생산성의 핵심이다. 컨텍스트 관리법을 익히면 AI 협업 품질이 즉시 달라진다.

:::callout type=info 이 가이드는 Claude Code (claude-sonnet-4-6) / Cursor 1.0 기준입니다 (2026-04). 도구 업데이트 시 검토 필요. :::

목표

AI 도구가 내 프로젝트의 목적·구조·규칙을 충분히 이해하도록 컨텍스트를 구성하는 방법을 단계별로 설명한다. CLAUDE.md 작성, 커스텀 룰 설정, 파일 구조 설명 세 가지를 체계적으로 활용하면 AI의 코드 생성 정확도가 눈에 띄게 향상된다.

준비물

• Claude Code 또는 Cursor 1.0 이상
• 작업 중인 프로젝트 디렉토리
• 예상 소요 시간: 30~45분

1. CLAUDE.md로 프로젝트 설명서 작성

CLAUDE.md는 Claude Code가 세션 시작 시 자동으로 읽는 프로젝트 설명 파일이다. AI가 "이 프로젝트가 무엇인지"를 항상 알 수 있도록 핵심 정보를 압축한다.

# 프로젝트명

## 목적

Next.js 16 + Supabase 기반 AI 콘텐츠 자동화 서비스.
티스토리·인스타그램 2채널 자동 발행이 목표.

## 기술 스택

- 프론트엔드: Next.js 16, TypeScript, Tailwind CSS
- 백엔드: Supabase (PostgreSQL + Edge Functions)
- AI: Claude API (claude-sonnet-4-6), Gemini Flash
- 배포: Vercel

## 디렉토리 구조

- web/src/app/      → Next.js 페이지 (App Router)
- project-scripts/  → 발행·Notion 스크립트
- .github/workflows/ → GHA 자동화

## 규칙

- 외부 API 연동 전 반드시 공식 문서 확인
- main 브랜치 직접 push 금지 (feature 브랜치 + PR)
- 에러 silent catch 금지

CLAUDE.md에 포함할 핵심 항목: 프로젝트 목적, 기술 스택, 디렉토리 구조, 개발 규칙, 금지 사항.

2. 커스텀 룰 설정으로 반복 지침 제거

매 프롬프트마다 "TypeScript로 작성해줘", "Tailwind 클래스 사용해줘"를 반복하는 것은 비효율이다. Cursor의 .cursorrules 또는 Claude Code의 설정으로 프로젝트 전체에 적용될 규칙을 사전에 정의한다.

# .cursorrules (Cursor용) 또는 CLAUDE.md 규칙 섹션

## 코드 스타일

- 언어: TypeScript (strict 모드)
- 포맷: Prettier 설정 따름
- 컴포넌트: React 함수형, 화살표 함수
- 스타일링: Tailwind CSS (className 방식)

## 금지

- any 타입 사용 금지
- console.log 프로덕션 코드 금지
- 인라인 스타일 금지 (Tailwind 클래스 사용)

## API 호출

- 모든 외부 API 호출에 try-catch 필수
- 에러 메시지는 사용자에게 노출하지 않고 로깅만

3. 파일 구조와 현재 상태 설명

AI가 특정 파일을 수정할 때, 주변 파일과의 관계를 모르면 충돌하는 코드를 생성한다. 작업 전에 관련 파일의 현재 상태를 AI에게 명시적으로 제공한다.

# Cursor 또는 Claude Code에서의 컨텍스트 제공 예시

@web/src/app/ai/page.tsx       ← 현재 수정할 파일
@web/src/lib/ai-client.ts      ← 연관된 AI 클라이언트
@web/src/types/ai.ts           ← 공유 타입 정의

위 세 파일을 참고해서 AI 응답에 스트리밍 기능을 추가해줘.

Claude Code에서는 @파일명 문법으로, Cursor에서는 파일을 열어둔 상태로 자동 컨텍스트가 제공된다.

4. 세션 간 컨텍스트 유지

AI 도구는 세션이 끊기면 이전 대화를 기억하지 못한다. 중요한 결정·규칙·현재 진행 상황을 지속적으로 유지하려면 메모리 파일을 활용한다.

# Claude Code의 메모리 활용
# 중요 사항을 저장하도록 지시
"이 내용을 기억해줘: 우리 프로젝트는 Tailwind v3을 사용하고
shadcn/ui 컴포넌트 라이브러리 기반이야"

# 다음 세션에서
"지난 세션 기억 확인해줘"

결과

올바르게 컨텍스트가 설정된 AI는 다음을 자동으로 적용한다:

• 프로젝트 규칙에 맞는 코드 생성 (TypeScript strict, Tailwind 등)
• 기존 파일 구조와 충돌 없는 수정
• 중복 선언·이름 충돌 없는 변수·함수 생성

다음 단계

관련 가이드: ai-github-actions — AI로 GitHub Actions 워크플로우 자동화 도구 상세: cursor / claude-code