🤫 AI 코딩 속도를 두 배로 늘리는 비밀 `.md` 파일

Source: Dev.to

자신을 반복하지 마세요.

채팅 시작마다 “TypeScript와 Tailwind를 사용해주세요” 라고 입력한다면 AI 개발을 잘못하고 있는 겁니다.

우리 모두 겪어봤을 겁니다: Claude 3.5 Sonnet(또는 ChatGPT)와 새 채팅을 열고 오류 로그를 붙여넣으면 AI가 자신 있게 Python으로 해결책을 제시합니다.
프로젝트는 Rust이므로 이를 고칩니다. 그러자 AI는 Rust 해결책을 제시하지만 오래된 라이브러리를 사용합니다. 몇 차례 주고받은 뒤에 여러분은 몇 분과 수천 개의 토큰을 낭비하게 됩니다.

더 좋은 방법이 있습니다. Builder.io 팀은 간단한 트릭—LLM을 위한 “Context Cheat Sheet”—인 CLAUDE.md 파일을 사용합니다.

CLAUDE.md란?

CLAUDE.md를 로봇용 README라고 생각하면 됩니다.
일반 README.md는 사람을 위한 것이며 배지와 마케팅 문구가 가득합니다.
CLAUDE.md는 AI를 위한 것이며, 밀도 높고 사실에 기반해 모델이 즉시 코딩을 시작하는 데 필요한 정보를 정확히 담고 있습니다. 세션 시작 시 이 파일을 첨부(또는 붙여넣기)하면 AI는 여러분의 저장소에 대한 “시니어 엔지니어” 수준의 컨텍스트를 얻게 됩니다.

완벽한 CLAUDE.md 템플릿

Builder.io 가이드에 따르면, 고성능 컨텍스트 파일은 네 개의 구분된 섹션을 포함해야 합니다.

1. Build & Run Commands

AI에게 프로젝트를 시작하고, 테스트하고, 빌드하는 방법을 명시합니다.

## Commands
- Run Dev: `npm run dev`
- Run Tests: `npm test`
- Build: `npm run build`
- Database: `docker-compose up -d db`

2. Coding Standards (The “No‑Go” Zone)

AI가 나쁜 패턴을 사용하지 않도록 방지합니다.

## Code Style
- Use TypeScript for all new files.
- Prefer functional components over class components.
- Styling: Use Tailwind CSS utility classes (no CSS modules).
- State Management: Use Zustand, DO NOT use Redux.
- Error Handling: Use try/catch blocks in all async functions.

3. Architecture Overview

프로젝트 구조에 대한 정신적 지도를 AI에게 제공합니다.

## Architecture
- /src/components: Reusable UI atoms.
- /src/features: Domain‑specific business logic.
- /src/hooks: Custom React hooks.
- **Rule**: Business logic should NEVER exist inside UI components. Move it to a custom hook.

4. Tech Stack Definition

주요 라이브러리를 모두 나열해 AI가 잘못된 import를 만들어내는 일을 방지합니다.

## Tech Stack
- Frontend: Next.js 14 (App Router)
- UI: Shadcn UI + Lucide Icons
- DB: Supabase
- Auth: Clerk

왜 이것이 모든 것을 바꾸는가

이 파일을 Claude에게 세션 시작 시 제공하거나(또는 Claude Projects의 “Project Knowledge”에 추가) 하면 세 가지 일이 일어납니다:

• Zero‑Shot Accuracy: AI가 즉시 여러분의 스타일에 맞는 코드를 작성합니다—const를 var로 바꾸거나 누락된 타입을 추가할 필요가 없습니다.
• Less Hallucination: 명시적인 라이브러리 목록 덕분에 이미 fetch를 사용하고 있는데 axios를 설치하라는 제안을 받지 않게 됩니다.
• Onboarding Aid: 새로운 개발자는 CLAUDE.md를 읽고 불필요한 잡담 없이 엄격한 기술 가이드를 파악할 수 있습니다.

컨텍스트 삽입 자동화

파일을 클립보드에 복사하는 스크립트를 만들 수 있습니다. copy-context.sh 스크립트를 생성해 보세요:

# macOS / Linux
cat CLAUDE.md | pbcopy
echo "Context copied to clipboard!"

./copy-context.sh를 실행하고 Claude에 붙여넣은 뒤 “로그인 컴포넌트를 리팩터링합시다.” 라고 말하면 바로 동작합니다.

미래: .ai 파일?

우리는 AI‑Native Repositories 로 나아가고 있습니다. Git을 위한 .gitignore, Docker를 위한 .dockerignore가 있듯이, 곧 모든 저장소는 AI 에이전트를 위한 설정 파일이 필요해질 것입니다.

이를 .cursorrules, CLAUDE.md, context.txt 등으로 부르든, 원칙은 동일합니다: 컨텍스트가 왕이다.

오늘 프로젝트에 CLAUDE.md를 만들어 보세요—나중에 스스로에게 감사하게 될 겁니다.