claude init과 5가지 질문 프레임워크(Who/What/Where/Why/How)를 사용하여 200라인 미만으로 Claude Code에 지속적인 프로젝트 컨텍스트를 제공하는 CLAUDE.md를 설정하세요.

변경된 점 — CLAUDE.md는 이제 모든 Claude Code 프로젝트의 필수 요소입니다

CLAUDE.md는 프로젝트의 루트 디렉토리에 배치되는 Markdown 파일로, Claude Code를 위한 지속적인 시스템 프롬프트 (system prompt) 역할을 합니다. 이 파일이 없으면 Claude는 각 세션을 처음부터 시작하며, 사용자의 실제 컨벤션 (conventions), 아키텍처 (architecture) 및 선호도를 놓치는 일반적인 가정에 의존하게 됩니다.

Claude Code가 프로젝트를 열 때 이 파일을 가장 먼저 읽습니다. 이러한 사전 컨텍스트 (context)는 Claude가 코드베이스에 대해 합리적이지만 틀린 추측을 하는 것을 방지하여, 세션마다 동일한 실수를 반복해서 수정해야 하는 번거로움을 줄여줍니다.

기술적 방법 — 5가지 질문 프레임워크

추측 없이 Claude에게 필요한 컨텍스트를 제공하는 CLAUDE.md를 구축하려면 다섯 가지 특정 질문에 답하세요. 먼저 초안을 생성하는 것부터 시작합니다:

cd /path/to/your/project
claude init

이 명령은 코드베이스를 스캔하여 빌드 명령 (build commands), 코드 스타일 (code style) 노트 및 구조 개요가 포함된 첫 번째 초안을 생성합니다. 하지만 이를 스캐폴드 (scaffold)로 취급하세요. 선호하는 테스트 프레임워크 (testing framework)나 아키텍처 결정 (architectural decisions)과 같은 중요한 세부 사항을 놓치는 경우가 많기 때문입니다.

다음 다섯 가지 섹션으로 내용을 다듬으세요:

Who are you? (당신은 누구인가요?) 당신의 역할과 팀을 정의하세요. 이는 Claude가 채택해야 할 관점을 설정합니다.

## Who
- 나는 2인 팀의 풀스택 개발자 (full-stack developer)입니다.
- 우리는 접근성 (accessibility)과 모바일 퍼스트 디자인 (mobile-first design)을 우선시합니다.

What are you building? (무엇을 만들고 있나요?) 프로젝트와 그 목표를 설명하세요.

## What
- 수공예품을 위한 Next.js 14 이커머스 사이트.
- 목표: Stripe 결제가 포함된 빠르고 SEO에 최적화된 제품 페이지.

Where does everything live? (모든 것이 어디에 있나요?) 프로젝트 구조와 주요 디렉토리 (directories)를 개략적으로 설명하세요.

## Where
- `app/`: Next.js App Router 페이지 및 API 라우트 (API routes).
- `components/`: 공유 UI 컴포넌트 (UI components).
...

Why did you make those choices? (왜 그런 선택을 했나요?) 아키텍처 결정 (architectural decisions)과 제약 사항 (constraints)을 설명하세요.

왜 (Why)

• 실시간 기능 (real-time features)과 행 단위 보안 (row-level security)을 위해 Supabase를 선택함.
• 기본적으로 서버 컴포넌트 (Server Components)를 사용하며, 필요한 경우에만 'use client'를 사용함.
  ...

어떻게 작업하나요? (How do you work?) 프로젝트를 빌드, 테스트, 린팅 (linting) 및 실행하기 위한 정확한 명령어를 제공하세요.

## 어떻게 (How)
- 빌드 (Build): `npm run build`
- 개발 서버 (Dev server): `npm run dev`
...

작동 원리 — 컨텍스트 윈도우 경제학 (Context Window Economics)

Claude Code의 컨텍스트 윈도우 (context window)는 유한합니다. 비대해진 CLAUDE.md는 무관한 세부 사항에 토큰 (tokens)을 낭비하게 만듭니다. 200행 미만으로 유지하면 가장 영향력 있는 컨텍스트를 우선순위에 두도록 강제할 수 있습니다. 만약 가이드라인이 방대하다면, 이를 CLAUDE.md/ 디렉토리로 분할하세요:

CLAUDE.md/
├── 01-project-overview.md
├── 02-project-structure.md
...

루트(root)의 CLAUDE.md에는 간단한 포인터(pointer)를 포함하세요:

# CLAUDE.md

이 프로젝트는 모듈형 컨텍스트 (modular context)를 사용합니다. 자세한 내용은 `CLAUDE.md/` 디렉토리를 참조하세요.

이 접근 방식은 초기 컨텍스트를 가볍게 유지하면서도, Claude가 필요할 때 모든 필수 정보에 접근할 수 있도록 합니다.

지금 바로 시도해보세요 — 오늘 당신의 프로젝트에 적용하기

1. 프로젝트 루트에서 claude init을 실행합니다.
2. 5가지 질문 프레임워크를 사용하여 생성된 CLAUDE.md를 편집합니다.
3. 파일이 200행을 넘지 않도록 유지합니다. 파일이 커지면 CLAUDE.md/ 디렉토리로 분할하세요.
4. Claude에게 프로젝트 관련 질문을 던져 테스트합니다. Claude가 별도의 수정 없이 당신의 컨벤션 (conventions)을 따르는지 관찰하세요.

출처: dev.to

원문 게시지: gentic.news