🎬 바이브 코딩 실전 레퍼런스 & 핵심 파일 가이드

바이브 코딩은 단순히 소스 코드를 올리는 것을 넘어, "AI에게 어떤 지시와 규칙을 전달하고, 어떻게 외부 도구 및 보안 환경을 연결하는가"를 조율하는 과정입니다.

💡 1. 한눈에 보는 역할 비교표 (영화 촬영 현장 비유)

개념 / 파일	역할 구분	영화 촬영 현장 비유	주요 기능 및 용도
intent.md	의도 및 목적	시놉시스 / 작업 기획서	이번 단기 작업의 목적, 배경, 기대 결과를 정리하여 AI에 전달하는 기획서
Claude.md	글로벌 규칙	감독의 연출 규칙 가이드	AI 프로젝트 전체에 적용되는 페르소나, 코딩 스타일, 프로젝트 대전제 가이드라인
Agent.md	에이전트 지침	담당 스태프 업무 지침서	특정 하위 역할(예: DB 전담, UI 전담)에 부여하는 스태프별 세부 미션 문서
Skill (*.md)	재사용 매뉴얼	특수 연출 교본	필요할 때 꺼내 쓰는 특정 작업 전용 실행 매뉴얼 (예: SEO 검수, 마이그레이션)
MCP	외부 연동 규격	외부 장비 연결 케이블	AI 에이전트가 외부 도구(Aside 브라우저, DB, GitHub 등)와 통신하는 표준 규격
*.json	기계 설정 데이터	촬영 장비 메뉴 세팅	시스템 및 소프트웨어가 읽는 구조화된 설정 파일 (예: mcp.json, package.json)
.env	보안 환경변수	현장 세이프티 보안 금고	API Key, DB 비밀번호 등 외부에 노출되면 안 되는 보안 정보 저장소
README.md	프로젝트 안내서	영화 포스터 & 브로셔	사람이나 AI가 프로젝트 저장소 진입 시 가장 먼저 읽는 전체 시작 안내서
.gitignore	제외 목록	비공개 출입 금지 구역	Git 저장소에 올리지 않을 불필요한 파일이나 보안 파일 목록

🎯 2. 파일별 실전 예시 및 참고 레퍼런스

📝 ① intent.md (작업 의도 및 기획서)

• 용도: AI에게 "이번 턴에 왜 이 코드를 짜야 하는지" 기획 의도를 설명합니다.
• 실전 파일 예시 (docs/intent.md):
• Markdown

   

  # 작업 목적: 로그인 페이지 UI 및 소셜 로그인 추가
  
  ## 1. 배경 및 목적
  - 기존 이메일 로그인 외에 카카오 소셜 로그인을 추가하여 사용자 전환율을 높이고자 함.
  
  ## 2. 세부 요구사항
  - [ ] Tailwind CSS를 사용하여 카카오 브랜드 컬러(#FEE500) 버튼 추가
  - [ ] 버튼 클릭 시 `/api/auth/kakao` 엔드포인트 호출
  

• 추천 레퍼런스: W3C Spec-Up Intent Template (표준 작업 의도 정의 방식 참고)

📄 ② Claude.md (프로젝트 글로벌 대전제)

• 용도: AI가 프로젝트 내 코드를 수정할 때 항상 준수해야 하는 공통 가이드라인입니다.
• 실전 파일 예시 (.claude/Claude.md):
• Markdown

   

  # 글로벌 프로젝트 개발 규칙
  - Framework: Next.js (App Router), TypeScript
  - 모든 변수/함수명은 camelCase를 준수하고, 함수 타입을 명시할 것.
  - 코드를 수정 후 추천 커밋 메시지는 한국어로 작성할 것.
  

• 추천 레퍼런스: Andrej Karpathy의 Claude.md Gist (전 OpenAI AI 수석의 실제 활용 파일)

📄 ③ Agent.md (특화 에이전트 지침)

• 용도: 특정 하위 작업만 전담하는 Sub-Agent의 역할 설정 문서입니다.
• 실전 파일 예시 (.agents/db-agent.md):
• Markdown

   

  # Role: Database Specialist Agent
  - 당신은 PostgreSQL 및 Prisma ORM 전문가입니다.
  - DB 마이그레이션 실행 전 쿼리문을 사용자에게 보여주고 승인을 받으세요.
  

🛠️ ④ Skill (*.md) (전문 기술 실행 매뉴얼)

• 용도: 특정 세부 작업의 검수나 절차를 모듈화한 스킬 문서입니다.
• 실전 파일 예시 (.skills/blog-seo-check.md):
• Markdown

   

  # Skill: 블로그 게시글 SEO 최적화 검수[cite: 3]
  1. H1 태그는 페이지당 1개만 존재하는지 확인[cite: 3].
  2. 본문 상단에 AI 검색엔진(AEO) 대응을 위한 2줄 요약 작성[cite: 1, 3].
  

• 추천 레퍼런스: superpowers Core Skills Repository (AI용 모듈화 스킬 모음)

🔌 ⑤ MCP 및 mcp.json (외부 시스템 연동)

• 용도: AI 모델이 사용자 PC 환경, 브라우저, 외부 API와 대화할 수 있도록 만드는 규격입니다.
• 실전 파일 예시 (mcp.json):
• JSON

   

  {
    "mcpServers": {
      "aside-browser": {
        "command": "aside",
        "args": ["mcp"]
      },
      "github-tools": {
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-github"]
      }
    }
  }
  

• 추천 레퍼런스: Model Context Protocol 공식 Specification
•  

⚙️ ⑥ *.json 및 🔐 .env (설정 및 보안)

• package.json: 실행 명령어(npm run dev 등) 및 라이브러리 세팅 데이터[cite: 1].
• .env: 소스 코드에 드러나면 안 되는 보안 암호화 키 파일입니다.
• Bash

   

  OPENAI_API_KEY="sk-proj-xxxxxxx..."
  DATABASE_URL="postgresql://user:password@localhost:5432/mydb"
  

🛠️ 3. 바이브 코딩 연동 도구 확장 지식 (보조 에이전트)

바이브 코딩 시 AI가 직접 제어하거나 로컬 환경에 구축하여 사용하는 보조 연동 도구들입니다.

🌐 1) Aside AI 브라우저 (에이전트 제어용)

• 개념: AI 에이전트가 웹 사이트를 탐색, 예매, 데이터 수집, 테스트(Smoke Test)를 직접 수행할 수 있도록 지원하는 AI 전용 브라우저입니다.
• CLI 및 MCP 설정법:
  • 터미널 설치: curl -fsSL [https://releases.aside.com/install.sh](https://releases.aside.com/install.sh) | bash 명령어로 설치.
  • MCP 연결: aside mcp 서버를 실행하고 mcp.json에 등록하여 Cursor나 Claude Code 등의 도구가 Aside 브라우저를 컨트롤하도록 연동합니다.

🔄 4. 바이브 코딩 실전 작업 프로세스 (Workflow)

Plaintext

 

1. [기획 정의]   intent.md 작성       ➔ "카카오 로그인 및 블로그 SEO 개선"[cite: 1, 3]
       │
2. [전체 규칙]   Claude.md 참조       ➔ "TypeScript 준수 및 코딩 기준 적용" (Karpathy 스타일)
       │
3. [스킬 실행]   Skill (*.md)         ➔ "SEO 검수 체크리스트 순서대로 적용"[cite: 3]
       │
4. [외부 연동]   MCP (mcp.json)       ➔ "Aside 브라우저 제어 및 로컬 Kokoro-TTS API 호출"[cite: 2]
       │
5. [보안 관리]   .env & .gitignore   ➔ "API Key 보안 금고 관리 및 GitHub 올림 방지"

비개발자도 위 흐름을 이해하면 AI 개발 도구와 훨씬 명확하고 정교하게 소통하며 바이브 코딩을 진행할 수 있습니다.