blevels

Home / AI / AI 바이브코딩 / CLAUDE.md

VIBE

CLAUDE.md

게시일 2026-04-30수정일 2026-04-30
공식 링크
On this page

:::callout type=info 이 가이드는 Claude Code 1.x 기준입니다 (2026-04). 도구 업데이트 시 검토 필요. :::

Claude Code를 켤 때마다 같은 맥락을 반복 설명하고 있다면 CLAUDE.md를 아직 쓰지 않는 것이다. CLAUDE.md는 Claude Code가 프로젝트를 열 때 자동으로 읽는 지침 파일이다. 프로젝트의 구조, 코딩 컨벤션, 금지 행동, 실행 명령까지 한 번 써두면 매 세션마다 다시 설명할 필요가 없다. AI에게 일관된 행동 기준을 부여하는 가장 단순하고 효과적인 방법이다.

CLAUDE.md가 하는 일

Claude Code는 세션을 시작할 때 프로젝트 루트의 CLAUDE.md를 자동으로 읽는다. 이 파일에 작성한 내용은 Claude의 모든 응답과 행동에 영향을 준다.

주로 다음 정보를 담는다.

  • 프로젝트 구조와 주요 파일 경로
  • 코딩 컨벤션 (네이밍, 포맷, 금지 패턴)
  • 실행 명령 (npm run dev, npm run lint)
  • 외부 서비스 연동 정보 (어떤 API를 쓰는지)
  • 에이전트 위임 규칙과 금지 행동 목록

준비물

  • Claude Code CLI (최신 버전)
  • 프로젝트 루트 디렉터리
  • 예상 시간: 30분 (초안 작성 기준)

1단계 — CLAUDE.md 생성

프로젝트 루트에 CLAUDE.md 파일을 만든다.

touch CLAUDE.md

또는 Claude Code에서 /init 명령을 실행하면 기존 파일 구조를 분석해 초안을 자동 생성해 준다.

2단계 — 기본 구조 작성

최소한의 CLAUDE.md 구조는 다음과 같다.

# 프로젝트명

한 줄 설명

## 실행 명령

- `npm run dev` — 개발 서버
- `npm run build` — 프로덕션 빌드
- `npm run lint` — ESLint 검사

## 프로젝트 구조

src/
├── components/  ← UI 컴포넌트
├── lib/         ← 유틸리티
└── app/         ← 페이지 (Next.js App Router)

## 코딩 컨벤션

- TypeScript 필수. `any` 사용 금지
- 컴포넌트는 함수형으로만 작성
- CSS: Tailwind CSS만 사용 (CSS 모듈 금지)

## 금지 행동

- `console.log` 커밋 금지
- main 브랜치 직접 push 금지
AD

3단계 — 고급 설정: @import 활용

규모가 커지면 @import 문법으로 다른 파일을 불러올 수 있다.

@docs/work-standards.md
@~/.claude/harness-manifesto.md

이 방식으로 공통 규칙은 전역 파일에 두고, 프로젝트별 규칙만 각 CLAUDE.md에 남길 수 있다. 팀이 공유하는 컨벤션을 한 곳에서 관리하는 데 효과적이다.

4단계 — 200줄 원칙 지키기

CLAUDE.md는 200줄 이하로 유지하는 것을 권장한다. 핵심 규칙만 남기고 상세 내용은 docs/ 하위 파일로 분리한 뒤 @import로 연결한다.

파일이 너무 길어지면 Claude가 전체 맥락을 처리하는 데 비용이 늘어나고, 정작 중요한 규칙이 묻힌다. 단순하고 짧을수록 Claude가 더 잘 따른다.

결과 확인

CLAUDE.md를 저장하고 Claude Code를 재시작하면 첫 메시지에서 파일을 읽었다는 확인이 가능하다. CLAUDE.md에 따르면...처럼 파일 내용을 참조하는 응답이 나오면 정상이다. 금지 행동을 시도하면 Claude가 거절하거나 경고를 표시한다.

CLAUDE.md 작성 팁

  • 구체적인 명령어 기록: "빌드하세요" 대신 npm run build 명령을 직접 기재
  • 금지 목록 명확히: "하지 마세요" 대신 "main 브랜치 직접 push 금지"처럼 구체적으로
  • 카테고리별 분리: 실행 명령 / 구조 / 컨벤션 / 금지 행동을 별도 섹션으로 구분
  • 최신 상태 유지: 프로젝트 구조가 바뀌면 즉시 업데이트

다음 단계

CLAUDE.md는 훅(Hook), 플러그인과 함께 쓸 때 시너지가 극대화된다. CLAUDE.md로 규칙을 정의하고, 훅으로 자동 실행하고, 플러그인으로 반복 작업을 명령어화하는 3층 구조를 권장한다.

관련 가이드: 훅-설정하기 / 플러그인-만들기 / mcp-입문

AD