코드를 한 줄도 쓰기 전에 모든 AI 지원 프로젝트에 필요한 3가지 파일

대부분의 개발자들은 프로젝트 설정을 의존성 설치, TypeScript 설정, 린팅(linting) 설정 정도로 생각합니다.

그것은 잘못된 순서입니다. AI 네이티브(AI-native) 설정 순서는 다르며, 이를 건너뛰는 것은 당신의 AI 어시스턴트가 프로젝트와 함께 협력하는 대신 프로젝트에 방해가 되도록 만드는 것을 의미합니다.

애플리케이션 코드를 한 줄도 작성하기 전에 존재해야 하는 세 가지 파일은 다음과 같습니다.

파일 1: CLAUDE.md (지침 계층 (the instruction layer))

CLAUDE.md는 프로젝트 루트에 있는 마크다운(markdown) 파일로, Claude Code가 매 세션마다 시스템 프롬프트 접두사(system prompt prefix)로 로드합니다. 이것을 당신의 AI 어시스턴트가 코드베이스를 건드리기 전에 읽는 브리핑 문서라고 생각하세요.

새 프로젝트를 위한 최소한의 CLAUDE.md 예시:

# Project: My SaaS App

## Stack
...

단 열 줄입니다. 이것만으로도 AI가 잘못 추측할 수 있는 결정의 80%를 방지하기에 충분합니다.

왜 코드를 쓰기 전에 이것을 작성해야 할까요? 코드를 작성한 후에 작성하면, 당신이 의도한 것이 아니라 실수로 만들어진 것을 설명하게 되기 때문입니다. 지침 계층(instruction layer)은 코드베이스를 사후에 문서화하는 것이 아니라, 코드베이스를 주도해야 합니다.

파일 2: .cursorrules (도구 계층 (the tool layer))

만약 Cursor를 사용한다면, @.cursorrules가 Cursor의 컨텍스트(context)로 로드됩니다. 이는 CLAUDE.md와 유사하지만 Cursor의 동작에 최적화되어 있습니다. 즉, 더 짧고, 규칙 중심적이며, 서술적인 내용은 적습니다.

CLAUDE.md와의 핵심 차이점은 다음과 같습니다: CLAUDE.md는 맥락적일 수 있습니다 ("우리 팀이 잘 알기 때문에 Prisma를 사용합니다"). 반면 @.cursorrules는 순수하게 규정적이어야 합니다 ("절대 생 SQL(raw SQL)을 작성하지 마세요; Prisma 쿼리 빌더를 사용하세요").

두 파일을 동기화된 상태로 유지하세요. 한 곳에서 인증(auth) 패턴을 업데이트한다면 다른 곳도 업데이트해야 합니다. 동일한 내용을 담고 있지만 서로 어긋나기 시작하는 두 개의 신뢰할 수 있는 원천(source-of-truth) 파일은 하나가 없는 것보다 더 나쁩니다.

깔끔한 패턴: CLAUDE.md를 표준 원천(canonical source)으로 만드세요. .cursorrules에서는 이를 참조하고 Cursor 전용 포맷팅 규칙만 추가하세요:

Project context: see CLAUDE.md at repo root.

Additional Cursor rules:
...

네 줄입니다. 그 외의 모든 것은 CLAUDE.md에 담깁니다.

파일 3: README.md (온보딩 계층 (the onboarding layer))

이 부분은 사람들을 놀라게 합니다. README는 사람을 위한 것이 아니라, 당신의 AI 어시스턴트의 콜드 스타트 (cold-start)를 위한 것입니다.

새로운 Cursor 세션을 열거나 새로운 Claude Code 채팅을 시작할 때, AI는 어제의 어떤 것도 기억하지 못합니다. README는 당신이 이를 붙여넣었을 때 AI가 가장 먼저 읽게 될 문서이며, 미래의 에이전트(또는 3개월 뒤의 당신)가 프로젝트가 어떻게 작동하는지 이해하기 위해 읽게 될 문서입니다.

AI 온보딩 (onboarding) 문서 역할을 하는 README는 다음과 같습니다:

## Quick context
SaaS app for indie devs. Subscription billing via Stripe, auth via NextAuth.js,
database via Prisma + PostgreSQL on Neon.
...

미사여구는 필요 없습니다. 마케팅 문구도 필요 없습니다. 그저 이것이 무엇인지, 어떻게 시작하는지, 무엇이 어디에 있는지만 명시하면 됩니다.

코드를 쓰기 전, 왜 이 세 가지가 모두 필요한가

이 세 파일은 하나의 삼각형을 형성합니다:

• CLAUDE.md는 AI에게 무엇이 중요한지 (이해관계, 패턴, 타협할 수 없는 원칙)를 알려줍니다.
• .cursorrules는 AI에게 어떻게 행동해야 하는지 (기계적인 규칙, 포맷팅, 임포트 (import) 컨벤션)를 알려줍니다.
• README.md는 AI에게 무엇이 존재하는지 (구조, 명령어, 멘탈 모델 (mental model))를 알려줍니다.

애플리케이션 코드를 작성하기 전에 이 세 가지가 모두 갖춰져 있다면, 당신은 정의된 컨텍스트 (context) 안에서 구축하고 있는 것입니다. AI는 스스로 결정을 내리는 대신 당신의 결정에 따라 작동합니다.

이 중 어느 것도 갖춰져 있지 않다면, 당신은 잘못된 방향으로 바이브 코딩 (vibe coding)을 하고 있는 것입니다. AI는 무언가를 만들고 있고, 당신은 진행하면서 그것이 무엇인지 파악하고 있는 상태가 됩니다.

지름길

새 프로젝트를 위해 이 세 파일을 처음부터 설정하는 데는 20~30분이 소요됩니다. 12가지의 서로 다른 기술 스택 (Next.js SaaS, Express + JWT, FastAPI, Discord Bot, Chrome Extension 등)에 대해 이를 수행하려면 훨씬 더 오랜 시간이 걸립니다.

Vibe Coder Kit는 세 파일이 이미 갖춰져 있고 실제 코드베이스와 일관성을 유지하도록 구성된 12개의 프로덕션 설정 스타터 (production-configured starters)를 패키지로 제공합니다. 클론 (clone)하고 설정 명령어를 실행하기만 하면, 당신의 AI 어시스턴트는 이미 브리핑을 마친 상태가 됩니다.

테스트

다음 프로젝트 설정을 마친 후, 스스로에게 이렇게 물어보세요: "만약 새로운 개발자(또는 새로운 AI 세션)가 아무런 맥락 없이 이 저장소(repo)를 열었을 때, 이것이 무엇인지, 어떻게 실행하는지, 그리고 어떻게 작업해야 하는지를 파악할 수 있을까?"

만약 대답이 '예'라면, 설정을 올바르게 마친 것입니다.

BLN Craft는 AI 네이티브 워크플로 (AI-native workflows)를 위한 개발자 도구를 구축합니다. blncraft.com에서 저희를 찾아보세요.