왜 CLAUDE.md가 코드베이스에서 가장 중요한 파일인가

Source: Dev.to

문제: 컨텍스트 기억 상실

Claude Code 세션을 시작할 때마다, 여러분은 프로젝트에 대해 전혀 모르는 매우 뛰어난 엔지니어와 대화하고 있는 겁니다—폴더 구조, 네이밍 규칙, 배포 파이프라인, 혹은 레거시 우회 방법에 대한 정보가 전혀 없습니다.

컨텍스트가 없으면 Claude는 합리적이지만 잘못된 가정을 합니다:

• 잘못된 디렉터리에 파일을 생성함
• 프로젝트가 pnpm을 사용함에도 npm을 사용함
• 모든 것이 TypeScript인 상황에서 JavaScript를 생성함
• 여러분이 Vitest를 사용함에도 Jest로 테스트를 작성함

그 결과? 코드를 직접 작성하는 것보다 Claude를 고치는 데 더 많은 시간을 쓰게 됩니다.

해결책: CLAUDE.md

CLAUDE.md는 프로젝트 루트에 위치하며 Claude Code가 세션을 시작할 때마다 자동으로 로드됩니다. AI 팀원을 위한 온보딩 문서라고 생각하면 됩니다—첫 날에 알아야 할 모든 것이 들어 있습니다.

CLAUDE.md에 포함할 내용

1. 프로젝트 개요

## Project Overview
BuildrFlags is a multi-tenant feature flag SaaS built with Next.js 15,
AWS Lambda, and DynamoDB. Targets small-to-medium engineering teams.

2. 기술 스택 및 규칙

## Tech Stack
- Language: TypeScript (strict mode, ESM, no `any`)
- Frontend: Next.js 15, React 19, Tailwind CSS v4, shadcn/ui
- Backend: AWS Lambda (Node.js 20+), API Gateway HTTP API v2
- Database: DynamoDB (single-table design)
- Package manager: pnpm v9+
- Testing: Vitest (unit), Playwright (E2E)

3. 파일 구조

## Structure
- `src/app/` — Next.js app router pages
- `src/components/` — React components (co‑located with pages)
- `infra/` — Terraform modules
- `tasks/` — Task tracking (todo.md, done.md)

4. 명령어

## Commands
- `pnpm dev` — Start dev server
- `pnpm test` — Run Vitest
- `pnpm lint` — ESLint check
- `pnpm build` — Production build

5. 규칙

## Rules
- NEVER push directly to main — always create a PR targeting dev
- Read files before modifying them — don't guess at content
- Run tests after every change
- Use single-table DynamoDB design — no new tables without approval
- All API responses must include CORS headers

실제 결과

프로젝트 전반에 CLAUDE.md를 도입한 이후:

• 첫 시도 정확도가 약 60 %에서 >90 %로 상승
• 세션 초기 설정 시간이 컨텍스트 설정에 5–10 분 걸리던 것이 0분으로 감소
• 코드 리뷰 수정이 약 70 % 감소
• 신입 팀원 온보딩이 매우 쉬워짐—Claude가 읽는 파일을 그대로 읽으면 됨

Workhuman에서 Claude Code 도입을 주도했을 때, 구조화된 CLAUDE.md가 그들의 Java 현대화 프로젝트에서 마이그레이션 노력 60 % 감소를 가능하게 한 기반이었습니다.

현장 팁

• 작게 시작하고 지속적으로 반복하세요. 첫 CLAUDE.md는 완벽하지 않을 겁니다. Claude가 잘못된 가정을 할 때마다 그를 방지할 규칙을 추가하세요.
• 설명보다는 지시를 명확히. “우리는 TypeScript를 선호합니다” 대신 “Language: TypeScript (strict, ESM, no any)”라고 적으세요. Claude는 직접적인 지시를 더 잘 따릅니다.
• 하지 말아야 할 예시도 포함하세요. Claude는 안티패턴에서도 학습합니다.
• 500줄 이하로 유지하세요. CLAUDE.md는 매 세션마다 컨텍스트에 로드됩니다. 2000줄 파일은 토큰을 낭비하고 핵심 내용이 희석됩니다.
• git에 버전 관리하세요. 프로젝트와 함께 진화하는 살아있는 문서입니다. PR에서 코드처럼 변경을 검토하세요.

더 큰 그림

CLAUDE.md는 단순히 Claude Code 기능이 아니라 좋은 엔지니어링 관행을 강제하는 도구입니다. 프로젝트의 규칙, 구조, 관행을 마크다운 파일에 명확히 적어놓지 못한다면, 인간 팀원들도 같은 모호함에 시달리고 있을 가능성이 높습니다.

최고의 CLAUDE.md 파일은 사실상 프로젝트 문서의 표준이 됩니다—인간과 AI 모두에게 유용한 자료가 되죠.