(버전 1.0 – 2025년 3월)

이 포스트는 reddit에 올라온 Vibe Coding 매뉴얼을 번역한 것입니다.

소개: Vibe Coding과 AI의 핵심 개념

Vibe Coding이란 무엇이며 무엇을 기반으로 하는가?

Vibe Coding은 인간이 AI 모델(예: Claude 3.7, GPT-4o)을 활용하여 기능적인 프로젝트를 효율적으로 구축하는 협업적 소프트웨어 개발 방식입니다. Matthew Berman이 자신의 유튜브 채널에서 공개한 “Vibe Coding 튜토리얼 및 모범 사례“에서 소개된 이 개념은 세 가지 핵심 기둥에 기반합니다:

  1. 명세(Specification): 목표를 정의합니다(예: “로그인 기능이 있는 Twitter 클론 구축”).
  2. 규칙(Rules): 명시적인 제약 조건을 설정합니다(예: “Python 사용, 복잡성 피하기”).
  3. 감독(Oversight): 프로세스를 모니터링하고 조정하여 일관성을 보장합니다.

이 매뉴얼은 Berman의 기초 위에 YouTube 댓글(u/nufh, u/robistocco 등)과 Reddit 스레드(u/illusionst, u/DonkeyBonked 등)의 커뮤니티 통찰력을 통합하여 모든 수준의 개발자를 위한 종합적인 프레임워크를 제공합니다.

이 프레임워크가 유용한 이유는 무엇인가?

AI 모델은 강력하지만 과도한 엔지니어링, 범위 확장 또는 컨텍스트 손실과 같은 혼란에 취약합니다. 이 매뉴얼은 다음과 같은 문제를 해결합니다:

  • 혼돈 제어: 규칙에 대한 엄격한 준수를 강제하여 일탈 행동을 최소화합니다.
  • 시간 절약: 구조화된 단계와 요약으로 재작업을 줄입니다.
  • 명확성 제공: 비기술적 사용자도 쉽게 따라갈 수 있으며, 프로그래머는 정밀한 제어를 얻습니다.

주요 이점

  1. 명확성: 규칙이 모듈식으로 구성되어 있어 탐색 및 조정이 용이합니다.
  2. 제어: 사용자가 AI 작업의 속도와 범위를 직접 지시합니다.
  3. 확장성: 작은 스크립트(예: 계산기)부터 대규모 앱(예: 웹 플랫폼)까지 모두 적용 가능합니다.
  4. 유지보수성: 문서화와 추적으로 장기적인 프로젝트 생존성을 보장합니다.

매뉴얼 구조: 어떻게 구성되어 있는가

이 프레임워크는 .cursor/rules 디렉토리(또는 .windsurfrules)에 각각 고유한 목적을 가진 네 개의 파일(또는 섹션)로 구성됩니다:

  1. 코딩 선호도 – 코드 스타일 및 품질 표준을 정의합니다.
  2. 기술 스택 – 도구 및 기술을 명시합니다.
  3. 워크플로우 선호도 – AI의 프로세스 및 실행을 관리합니다.
  4. 커뮤니케이션 선호도 – AI-인간 상호작용에 대한 기대치를 설정합니다.

접근성을 위한 기본 사항부터 시작하여 기술적 깊이를 위한 고급 세부 사항으로 진행할 것입니다.

핵심 규칙: 간단한 시작점

1. 코딩 선호도 – “이렇게 코드를 작성하세요”

목적: 깨끗하고 유지보수 가능하며 효율적인 코드를 보장합니다.

규칙:

  • 단순성: “복잡성보다 가장 간단한 솔루션을 항상 우선시하세요.” (Matthew Berman)
  • 중복 없음: “코드 반복을 피하고, 가능한 경우 기존 기능을 재사용하세요.” (Matthew Berman, DRY from u/DonkeyBonked)
  • 조직화: “파일을 간결하게 유지하고, 200-300줄 이내로 하며, 필요에 따라 리팩토링하세요.” (Matthew Berman)
  • 문서화: “주요 구성 요소 개발 후에는 /docs/[component].md(예: login.md)에 간략한 요약을 작성하세요.” (u/believablybad)

왜 효과적인가: 단순한 코드는 버그를 줄이고, 문서화는 읽기 쉬운 감사 추적을 제공합니다.

2. 기술 스택 – “이런 도구를 사용하세요”

목적: AI를 사용자가 선호하는 기술에 제한합니다.

규칙(Berman의 예):

  • “백엔드는 Python으로 작성.”
  • “프론트엔드는 HTML과 JavaScript로 작성.”
  • “데이터는 JSON 파일이 아닌 SQL 데이터베이스에 저장.”
  • “테스트는 Python으로 작성.”

왜 효과적인가: 일관성을 유지하여 AI가 프로젝트 중간에 도구를 전환하는 것을 방지합니다.

3. 워크플로우 선호도 – “이렇게 작업하세요”

목적: 예측 가능성을 위해 AI의 실행 프로세스를 제어합니다.

  • 집중: “내가 지정한 코드만 수정하고, 나머지는 모두 손대지 마세요.” (Matthew Berman)
  • 단계: “큰 작업을 단계로 나누고, 각 단계 후에 내 승인을 기다리세요.” (u/xmontc)
  • 계획: “큰 변경 전에는 plan.md를 작성하고 내 확인을 기다리세요.” (u/RKKMotorsports)
  • 추적: “완료된 작업은 progress.md에, 다음 단계는 TODO.txt에 기록하세요.” (u/illusionst, u/petrhlavacek)

왜 효과적인가: 점진적인 단계와 로그를 통해 프로세스를 투명하고 관리 가능하게 유지합니다.

4. 커뮤니케이션 선호도 – “이렇게 대화하세요”

목적: AI로부터 명확하고 실행 가능한 피드백을 보장합니다.

  • 요약: “각 구성 요소 완료 후에는 완료된 내용을 요약하세요.” (u/illusionst)
  • 변경 규모: “변경사항을 작은(Small), 중간(Medium), 또는 큰(Large) 규모로 분류하세요.” (u/illusionst)
  • 명확화: “내 요청이 불분명하면 진행하기 전에 질문하세요.” (u/illusionst)

왜 효과적인가: AI의 의도를 해독할 필요 없이 명확한 정보를 받을 수 있습니다.

고급 규칙: 복잡한 프로젝트를 위한 확장

1. 코딩 선호도 – 품질 향상

확장:

  • 원칙: “적용 가능한 경우 SOLID 원칙(예: 단일 책임, 의존성 역전)을 따르세요.” (u/Yodukay, u/philip_laureano)
  • 가드레일: “개발이나 프로덕션 환경에서 모의 데이터를 사용하지 마세요—테스트에만 제한하세요.” (Matthew Berman)
  • 컨텍스트 확인: “컨텍스트 유지를 확인하기 위해 모든 응답을 랜덤 이모지(예: 🐙)로 시작하세요.” (u/evia89)
  • 효율성: “명확성을 희생하지 않고 토큰 사용을 최소화하도록 출력을 최적화하세요.” (u/Puzzleheaded-Age-660)

기술적 통찰: SOLID는 모듈성을 보장합니다(예: 로그인 모듈이 트윗 처리를 담당하지 않음). 이모지는 컨텍스트가 모델 한계(일반적으로 Claude 3.7의 경우 200k 토큰)를 초과할 때 신호를 보냅니다.

2. 기술 스택 – 사용자 정의

확장:

  • “추가 도구를 지정하는 경우(예: 검색용 Elasticsearch), 여기에 포함하세요.” (Matthew Berman)
  • “내 명시적 승인 없이는 스택을 절대 변경하지 마세요.” (Matthew Berman)

기술적 통찰: 고정된 스택은 AI가 호환되지 않는 종속성(예: SQL에서 JSON으로 전환)을 도입하는 것을 방지합니다.

3. 워크플로우 선호도 – 프로세스 마스터리

확장:

  • 테스팅: “주요 기능에 대한 포괄적인 테스트를 포함하고, 엣지 케이스 테스트(예: 잘못된 입력)를 제안하세요.” (u/illusionst)
  • 컨텍스트 관리: “컨텍스트가 100k 토큰을 초과하면 context-summary.md에 요약하고 세션을 재시작하세요.” (u/Minimum_Art_2263, u/orbit99za)
  • 적응성: “내 피드백에 따라 체크포인트 빈도를 조정하세요(더 많거나 적은 세분화).” (u/illusionst)

기술적 통찰: 토큰 한계(예: Claude의 200k)는 100k를 넘어서면 성능이 저하됩니다. 요약은 연속성을 유지하는 데 도움이 되며, 테스트는 초기에 회귀 문제를 감지합니다.

4. 커뮤니케이션 선호도 – 정밀 상호작용

확장:

  • 계획: “대규모(Large) 변경사항의 경우 구현 계획을 제공하고 승인을 기다리세요.” (u/illusionst)
  • 추적: “항상 완료된 작업과 보류 중인 작업을 명확히 명시하세요.” (u/illusionst)
  • 감정적 신호: “내가 긴급성을 나타내면(예: ‘이것은 중요합니다—실수하지 마세요!’), 주의와 정밀함을 우선시하세요.” (u/dhamaniasad, u/capecoderrr)

기술적 통찰: 변경 분류(S/M/L)는 영향을 정량화합니다(예: Small = 50줄 미만, Large = 아키텍처 변경). 감정적 신호는 AI가 훈련 데이터 패턴을 활용하여 더 나은 준수를 이끌어낼 수 있습니다.

실용적인 예: 어떻게 작동하는가

작업: “저장 기능이 있는 메모 작성 앱을 구축하세요.”

  1. 명세: 사용자가 말합니다, “메모를 작성하고 저장할 수 있는 앱이 필요합니다.”

  2. AI 응답: “🦋 이해했습니다. 계획: 1. 백엔드(Python, SQL 저장소), 2. 프론트엔드(HTML/JS), 3. 저장 기능. 진행할까요?”

  3. 사용자: “네.”

  4. 실행: 백엔드 후: “🐳 백엔드 완료(중간 규모 변경). 메모가 SQL에 저장됨. progress.md와 TODO.txt를 업데이트했습니다. 다음: 프론트엔드?” 프론트엔드 후: “🌟 프론트엔드 완료. 사용법이 포함된 docs/notes.md를 추가했습니다. 완료!”

  5. 결과: 참조를 위한 로그(progress.md, /docs)가 포함된 작동하는 앱.

기술적 참고: 각 단계는 개별적으로 테스트 가능하며(예: SQL 삽입 작동), 컨텍스트는 요약을 통해 보존됩니다.

고급 팁: 프레임워크 최대화

왜 네 개의 파일인가?

  • 모듈성: 각 파일은 쉬운 업데이트를 위해 관심사(스타일, 도구, 프로세스, 커뮤니케이션)를 분리합니다. (Matthew Berman)
  • 확장성: 다른 파일을 방해하지 않고 하나의 파일을 조정할 수 있습니다(예: 기술 스택을 건드리지 않고 커뮤니케이션 방식 조정). (u/illusionst)

사용자 정의 옵션

  • 초보자: 단순성을 위해 고급 규칙(예: SOLID)을 건너뜁니다.
  • 팀: team-collaboration.mdc를 추가: “team-standards.md의 팀 규칙에 맞추고, 동료들을 위해 요약하세요.” (u/deleatanda5910)
  • 대규모 프로젝트: 체크포인트 및 문서화 빈도를 늘립니다.

감정적 프롬프팅

  • 시도해보세요: “이 프로젝트는 중요합니다—집중해 주세요!” 일화적 증거는 개선된 주의력을 시사하며, 이는 훈련 데이터 편향에서 비롯될 수 있습니다. (u/capecoderrr, u/dhamaniasad)

크레딧과 감사

이 프레임워크는 다음 기여자들의 덕분입니다:

  • Andrej Karpathy: “vibe coding"이라는 용어를 만들고 X에 게시한 포스트(2025년 2월 3일)에서 더 넓은 커뮤니티에 소개했습니다. 직관적이고 최소한의 노력으로 하는 워크플로우에 초점을 맞춘 AI 지원 프로그래밍을 설명했습니다. 그의 작업은 이 프레임워크의 기초 개념에 영감을 주었습니다.

  • Matthew Berman: 핵심 vibe coding 규칙 및 철학(YouTube, 2025).

  • YouTube 커뮤니티:

    • u/nufh, u/believablybad(문서화, .md 파일).
    • u/robistocco(반복적 워크플로우).
    • u/xmontc(체크포인트).

  • Reddit 커뮤니티:

    • u/illusionst(커뮤니케이션, 진행 추적).
    • u/Puzzleheaded-Age-660(토큰 최적화).
    • u/DonkeyBonked, u/philip_laureano(KISS, DRY, YAGNI, SOLID).
    • u/evia89(이모지 컨텍스트 확인).
    • u/dhamaniasad, u/capecoderrr(감정적 프롬프팅).

  • Grok(xAI): u/Low_Target2606의 요청으로 모든 통찰력을 하나의 일관된 프레임워크로 통합해 이 매뉴얼을 합성했습니다.

결론: Vibe Coding에 대한 가이드

이 매뉴얼은 개발에서 AI를 활용하기 위한 실전 테스트를 거친 템플릿입니다. 단순성, 제어 및 확장성의 균형을 맞추어 개인 코더, 팀 또는 비기술적 창작자에게 이상적입니다. 있는 그대로 사용하거나, 필요에 맞게 조정하고, 결과를 공유하세요—어떻게 발전하는지 보고 싶습니다! Reddit에 피드백을 게시하고 함께 개선해 봅시다. 즐거운 코딩 되세요!

부록: Windsurf를 위한 globar rules와 workspace rules 예시

Global rules

1️⃣ 구현 작업 원칙

  • SOLID 원칙을 사용해서 구현하세요:
    • 단일 책임 원칙 (Single Responsibility Principle)
    • 개방-폐쇄 원칙 (Open-Closed Principle)
    • 리스코프 치환 원칙 (Liskov Substitution Principle)
    • 인터페이스 분리 원칙 (Interface Segregation Principle)
    • 의존성 역전 원칙 (Dependency Inversion Principle)
  • TDD로 구현하세요: 테스트 주도 개발 방식으로 먼저 테스트를 작성하고 구현하세요.
  • Clean Architecture를 사용해서 구현하세요: 책임과 관심사를 명확히 분리하여 구현하세요.
  • Pulumi나 CloudFormation에 설정하는 Description은 영문으로 작성하세요.

2️⃣ 코드 품질 원칙

  • 단순성: 언제나 복잡한 솔루션보다 가장 단순한 솔루션을 우선시하세요.
  • 중복 방지: 코드 중복을 피하고, 가능한 기존 기능을 재사용하세요 (DRY 원칙).
  • 가드레일: 테스트 외에는 개발이나 프로덕션 환경에서 모의 데이터를 사용하지 마세요.
  • 효율성: 명확성을 희생하지 않으면서 토큰 사용을 최소화하도록 출력을 최적화하세요.

3️⃣ 리팩토링

  • 리팩토링이 필요한 경우 계획을 설명하고 허락을 받은 다음 진행하세요.
  • 코드 구조를 개선하는 것이 목표이며, 기능 변경은 아닙니다.
  • 리팩토링 후에는 모든 테스트가 통과하는지 확인하세요.

4️⃣ 디버깅

  • 디버깅 시에는 원인 및 해결책을 설명하고 허락을 받은 다음 진행하세요.
  • 에러 해결이 중요한 것이 아니라 제대로 동작하는 것이 중요합니다.
  • 원인이 불분명할 경우 분석을 위해 상세 로그를 추가하세요.

5️⃣ 언어

  • 한국어로 소통하세요.
  • 문서와 주석도 한국어로 작성하세요.
  • 기술적인 용어나 라이브러리 이름 등은 원문을 유지해도 됩니다.

6️⃣ Git 커밋

  • --no-verify를 절대 사용하지 마세요.
  • 명확하고 일관된 커밋 메시지를 작성하세요.
  • 적절한 크기로 커밋을 유지하세요.

7️⃣ 문서화

  • 주요 컴포넌트 개발 후에는 /docs/[component].md에 간략한 요약을 작성하세요.
  • 문서는 코드와 함께 업데이트하세요.
  • 복잡한 로직이나 알고리즘은 주석으로 설명하세요.

Workspace rules

1️⃣ 기술 스택 - “이 도구들을 사용하세요”

개발 도구
  • 백엔드: Python 사용
  • 인프라: Pulumi for TypeScript, CloudFormation
  • 데이터 저장: MySQL 호환 Aurora Serverless
  • 테스트: pytest, Jest
추가 정보
  • 추가 도구가 명시적으로 요청되면 여기에 포함될 수 있습니다.
  • 명시적인 승인 없이는 스택을 변경하지 마세요.
  • Pulumi 또는 CloudFormation 설정의 Description은 영어로 작성하세요.

2️⃣ 워크플로우 선호도 - “이런 방식으로 작업하세요”

기본 과정
  • 초점: 지정된 코드만 수정하고, 다른 부분은 그대로 두세요.
  • 단계: 큰 작업을 단계로 나누고, 각 단계 후에는 승인을 기다리세요.
  • 계획: 큰 변경 전에는 설계 및 작업개요 문서 [이슈명]_design.md 와 구현 계획 문서 [이슈명]_plan.md를 작성하고 확인을 기다리세요.
  • 추적: 완료된 작업은 progress.md에 기록하고, 다음 단계는 TODO.txt에 기록하세요.
고급 워크플로우
  • 테스팅: 주요 기능에 대한 포괄적인 테스트를 포함하고, 엣지 케이스 테스트를 제안하세요.
  • 컨텍스트 관리: 컨텍스트가 100k 토큰을 초과하면 context-summary.md로 요약하고 세션을 재시작하세요.
  • 적응성: 피드백에 따라 체크포인트 빈도를 조정하세요(더 많거나 적은 세분화).

3️⃣ 커뮤니케이션 선호도 - “이렇게 소통하세요”

기본 소통
  • 요약: 각 컴포넌트 후에 완료된 작업을 요약하세요.
  • 변경 규모: 변경을 작은, 중간, 큰 규모로 분류하세요.
  • 명확화: 요청이 불명확하면 진행 전에 질문하세요.
정밀 소통
  • 계획: 큰 변경의 경우 구현 계획을 제공하고 승인을 기다리세요.
  • 추적: 항상 완료된 작업과 대기 중인 작업을 명시하세요.
  • 감정적 신호: 긴급성이 표시되면(예: “이것은 중요합니다—집중해주세요!”) 주의와 정확성을 우선시하세요.

4️⃣ 프로젝트 구조

디렉토리 구조
  • docs/: 모든 문서 파일
    • architecture/: 아키텍처 문서
    • guides/: 개발자 가이드
    • runbooks/: 운영 매뉴얼
  • src/: 소스 코드
    • core/: 핵심 비즈니스 로직
    • infrastructure/: 인프라 관련 코드
    • api/: API 엔드포인트
  • tests/: 테스트 파일
명명 규칙
  • 파일명: 스네이크 케이스(snake_case) 사용 (예: user_service.py)
  • 클래스명: 파스칼 케이스(PascalCase) 사용 (예: UserService)
  • 함수와 변수명: 스네이크 케이스(snake_case) 사용 (예: get_user())
  • 상수: 대문자 스네이크 케이스(UPPER_SNAKE_CASE) 사용 (예: MAX_USERS)

5️⃣ 활용 방법

이 규칙 세트는 AI 지원 개발을 위한 템플릿입니다. 다음과 같이 사용하세요:

  1. 프로젝트 시작 시 이 규칙을 참조하세요.
  2. 필요에 따라 규칙을 조정하세요.
  3. AI 모델에게 이 파일의 내용을 따르도록 지시하세요.
  4. 프로젝트를 진행하면서 이 규칙이 어떻게 도움이 되는지 평가하세요.

이 규칙 세트를 통해 AI와의 협업이 더 효율적이고 예측 가능해질 것입니다.