대부분의 개발자들은 Claude Code를 완전히 잘못 사용하고 있습니다.

그들은 새로운 세션을 열고 다음과 같은 프롬프트(Prompt)를 입력합니다:

대시보드 구축해줘

그러고 나서 생성된 코드가 왜 구조가 나쁜지, 명명 규칙(Naming)이 일관되지 않은지, 이상한 아키텍처(Architecture) 결정을 내렸는지, 혹은 프로젝트와 맞지 않는 UI 패턴을 사용하는지 의아해합니다.

문제는 이것입니다:

Claude Code는 강력하지만, 컨텍스트(Context)가 없다면 여전히 추측을 해야만 합니다.

그리고 실제 프로덕션 코드베이스(Production codebase) 내에서 추측을 하는 것은 빠르게 문제를 일으킵니다.

평범한 AI 보조 개발과 전문적인 AI 보조 개발의 가장 큰 차이점은 더 나은 프롬프팅(Prompting)이 아닙니다.

그것은 바로 더 나은 컨텍스트(Context)입니다.

그 지점에서 CLAUDE.md가 중요해집니다.

CLAUDE.md란 무엇인가?

CLAUDE.md는 Claude Code 워크플로우(Workflow)에서 가장 중요한 파일입니다.

Claude가 당신의 프로젝트에서 작업을 시작할 때마다, 이 파일을 가장 먼저 읽습니다.

이 파일은 다음 내용을 설명합니다:

• 프로젝트가 무엇을 하는지
• 어떤 기술(Technologies)이 사용되는지
• 아키텍처(Architecture) 결정 사항
• 폴더 구조
• 코딩 컨벤션 (Coding conventions)
• UI 패턴
• 개발 명령(Development commands)
• 재사용 가능한 프로젝트 규칙

이 파일이 없으면, Claude는 매 세션마다 제로 베이스에서 시작합니다.

이는 보통 다음과 같은 결과로 이어집니다:

• 일관성 없는 코드
• 잘못된 가정
• 구조적 실수
• 반복되는 설명
• 불필요한 리팩터링 (Refactoring)
• 생성 후 더 많은 수정 작업

적절한 컨텍스트(Context)가 있으면, Claude는 극적으로 더 정확해집니다.

두 가지 유형의 CLAUDE.md

1. 글로벌 (Global) CLAUDE.md

위치:

~/.claude/CLAUDE.md

이것은 모든 프로젝트에 영향을 미칩니다.

개인적인 엔지니어링 선호도를 설정하는 데 사용하세요.

예시:

- 항상 TypeScript를 사용할 것
- 함수형 컴포넌트 (Functional components)를 선호할 것
- 인라인 스타일 (Inline styles)을 피할 것
...

이것을 당신의 영구적인 엔지니어링 성향이라고 생각하세요.

2. 프로젝트 레벨 (Project-Level) CLAUDE.md

위치:

project-root/CLAUDE.md

이것은 프로젝트별로 특화된 것입니다.

예시:

• 프로젝트는 Next.js 15 App Router를 사용함
• 상태 관리 (State management)에는 Zustand를 사용함
• 서버 상태 (Server state)에는 React Query를 사용함
  ...

이를 통해 Claude는 귀하의 코드베이스를 즉각적으로 이해할 수 있습니다.

대규모 프로젝트를 위한 최적의 구조

작은 규모의 앱이라면 파일 하나로 충분합니다.

하지만 규모가 더 큰 프로젝트의 경우, 컨텍스트 (Context)를 여러 파일로 나누는 것이 훨씬 더 효과적입니다.

권장 구조:

project-root/
├── CLAUDE.md
└── .claude/
...

루트 CLAUDE.md 내부:

@.claude/architecture.md
@.claude/stack.md
@.claude/conventions.md
...

중요한 세부 사항:

Claude는 루트에 있는 CLAUDE.md만 자동으로 읽습니다.

.claude/ 디렉토리 내부의 파일들은 루트 파일에서 임포트 (Import)되지 않는 한 자동으로 로드되지 않습니다.

또한 .claude/를 .gitignore에 추가하세요.

.claude/

각 파일에 포함되어야 할 내용

architecture.md

다음 내용을 문서화하세요:

• 폴더 구조 (Folder structure)
• 라우팅 시스템 (Routing system)
• 기능 경계 (Feature boundaries)
• 서버/클라이언트 분리 (Server/client separation)
• 데이터 흐름 (Data flow)
• API 아키텍처 (API architecture)
• 공유 컴포넌트 전략 (Shared component strategy)

예시:

- 기능(Features)은 src/features 내부에 위치함
- 공유 UI는 src/components 내부에 위치함
- API 클라이언트(API clients)는 src/services 내부에 위치함
...

이는 Claude가 무작위적인 구조를 생성하는 것을 방지하는 데 도움이 됩니다.

stack.md

모든 중요한 라이브러리와 그것이 존재하는 이유를 문서화하세요.

예시:

- Next.js 15 → 프레임워크 및 라우팅 (Framework and routing)
- React Query → 서버 상태 관리 (Server state management)
- Zustand → 클라이언트 상태 관리 (Client state management)
...

이를 통해 Claude가 불필요한 대안을 도입하거나 충돌하는 패턴을 사용하는 것을 방지할 수 있습니다.

conventions.md

이 파일은 매우 중요합니다.

다음 내용을 문서화하세요:

• 명명 규칙 (Naming conventions)
• 컴포넌트 구조 (Component structure)
• 임포트 규칙 (Import rules)
• 훅 패턴 (Hooks patterns)
• 파일 명명 (File naming)
• 상태 패턴 (State patterns)
• API 처리 (API handling)
• 에러 처리 (Error handling)
• 폼 패턴 (Form patterns)
• UI 컨벤션 (UI conventions)

예시:

- 컴포넌트는 PascalCase를 사용함
- 훅(Hooks)은 use*로 시작함
- 공유 타입(Shared types)은 src/types에 위치함
...

이를 통해 훨씬 더 일관된 생성 코드를 얻을 수 있습니다.

commands.md

유용한 프로젝트 명령어:

npm run dev
npm run build
npm run lint
...

단순하지만, 긴 작업 세션 동안 매우 유용합니다.

product.md

많은 개발자가 이 단계를 건너뛰지만, 이는 믿을 수 없을 정도로 유용합니다.

문서화 내용:

• 제품이 실제로 수행하는 기능
• 타겟 사용자 (target users)
• 비즈니스 로직 (business logic)
• 중요한 워크플로 (workflows)
• 사용자 역할 (user roles)
• 권한 (permissions)
• 기능 동작 방식 (feature behavior)

예시:

- 관리자(Admins)는 제품과 사용자를 관리할 수 있습니다.
- 고객(Customers)은 자신의 주문만 관리할 수 있습니다.
- 대시보드는 페르시아어와 영어를 지원합니다.
...

이는 Claude가 단순한 코드 수준의 결정을 넘어, 더 스마트한 제품 수준의 결정을 내릴 수 있도록 돕습니다.

이러한 파일들을 자동으로 생성하기 위한 최고의 프롬프트

프로젝트 시작 시, 다음 내용을 Claude Code에 붙여넣으세요:

무엇인가를 작성하기 전에 이 프로젝트를 철저히 탐색하세요:

- package.json 및 모든 설정 파일(config files)을 읽으세요.
...

이것만으로도 설정 시간을 몇 시간이나 절약할 수 있습니다.

기존 UI 컨벤션(UI Conventions)을 개선하기 위한 프롬프트

파일이 이미 존재하고 UI에 대한 더 나은 이해만을 원하는 경우:

먼저 .claude/conventions.md를 읽은 다음, UI 패턴을 확인하기 위해 코드베이스를 조사하세요.

- 기존 컴포넌트를 여세요.
...

이는 디자인 일관성(design consistency)을 크게 향상시킵니다.

파일이 생성된 후

하나 더 유용한 프롬프트:

방금 생성한 CLAUDE.md를 읽고, 더 전문적이고 간결하며 프로덕션 환경에 적합하도록(production-ready) 다시 작성하세요. 유용한 정보만 유지하세요.

이 과정은 보통 불필요한 내용을 제거하고 명확성을 높여줍니다.

프롬프트 품질은 여전히 중요합니다

좋은 컨텍스트(context)가 모호한 프롬프트를 해결해주지는 않습니다.

약한 프롬프트:

대시보드 구축해줘

강한 프롬프트:

다음 기능을 포함한 관리자 대시보드를 구축해줘:
- 반응형 사이드바 (responsive sidebar)
- 상단 네비게이션 바 (top navbar)
...

더 구체적인 프롬프트가 훨씬 더 나은 결과를 만들어냅니다.

컨텍스트를 최신 상태로 유지하세요

프로젝트는 끊임없이 진화합니다.

여러분의 AI 컨텍스트도 함께 진화해야 합니다.

예시:

• 새로운 기능 추가 → architecture.md 업데이트
• 새로운 패키지 추가 → stack.md 업데이트
• 새로운 반복 패턴 발견 → conventions.md 업데이트
• 새로운 스크립트 추가 → commands.md 업데이트
• 비즈니스 로직 변경 → product.md 업데이트

오래된 컨텍스트는 시대에 뒤떨어진 AI 결정을 초래합니다.

Claude가 혼란을 느낄 때

긴 세션은 때때로 출력 품질을 저하시킵니다.

간단한 해결 방법:

CLAUDE.md를 다시 읽어줘

또는:

/clear

채팅은 초기화되지만, CLAUDE.md를 통해 프로젝트 컨텍스트 (Context)는 여전히 유지됩니다.

중요한 워크플로 규칙

몇 가지 사항만 지켜도 결과가 크게 향상됩니다:

1. 프로젝트당 별도의 세션 사용

하나의 채팅 안에 서로 관련 없는 프로젝트들을 섞지 마세요.

2. 큰 작업을 더 작은 단계로 나누기

나쁜 접근 방식:

완전한 대시보드 구축해줘

더 나은 접근 방식:

1. 사이드바 구축
2. 구조 확인
3. 네비게이션 바 (Navbar) 구축
4. API 연결
5. 로딩 상태 (Loading states) 추가
6. 애니메이션 추가

범위가 좁은 작은 작업들이 더 깔끔한 출력을 만들어냅니다.

3. 대규모 기능 구현 전 아키텍처 확인

대규모 시스템을 생성하기 전에, Claude에게 먼저 계획을 설명하도록 요청하세요.

예시:

코딩하기 전에, 네가 만들 계획인 아키텍처 (Architecture)와 파일 구조를 설명해줘.

이를 통해 초기에 발생할 수 있는 큰 구조적 실수를 방지할 수 있습니다.

Claude 메모리

Claude는 세션 사이에도 장기적인 선호도를 기억할 수 있습니다.

예시:

내가 항상 TypeScript를 사용하고 싶어 한다는 걸 기억해줘.

또는:

내 프로젝트는 기능 기반 아키텍처 (Feature-based architecture)를 사용한다는 걸 기억해줘.

이렇게 하면 반복적인 설정 작업을 더욱 줄일 수 있습니다.

이 모든 것의 진정한 이점

다음과 같은 사항들을 반복해서 말할 필요가 없어집니다:

• TypeScript 사용
• App Router 사용
• Zustand 사용
• shadcn/ui 사용
• 폼 (Forms)에는 Zod 사용
• 프로젝트는 RTL (Right-to-Left) 방식
• 기능들은 /features 내부에 위치

Claude는 이미 알고 있습니다.

이는 다음과 같은 결과로 이어집니다:

• 구조적 실수 감소
• 더 나은 아키텍처 결정
• 더 깔끔한 생성 코드
• 더 빠른 반복 (Iteration)
• 편집 작업 감소
• 더 일관된 출력

대규모 프로젝트에서는 그 차이가 엄청나게 커집니다.

마치며

대부분의 개발자들은 더 나은 프롬프트 (Prompt)를 작성하는 데에만 집중합니다.

하지만 진지한 AI 보조 개발 (AI-assisted development)을 위해서는 프롬프팅만으로는 충분하지 않습니다.

진정한 개선은 지속적인 컨텍스트 엔지니어링 (Context engineering)에서 옵니다.

좋은 컨텍스트 + 명확한 프롬프트 + 업데이트된 프로젝트 메모리가 결합될 때, Claude Code는 진정으로 전문적인 느낌을 줍니다.

CLAUDE.md를 올바르게 사용하기 시작하면, 이전 방식으로 돌아가는 것이 매우 어려워질 것입니다.

출처

이 가이드에 포함된 대부분의 워크플로 (workflows), 패턴 (patterns), 그리고 권장 사항 (recommendations)은 Claude AI로부터 직접 수집되었으며, 실제 개발 환경에서의 사용을 통해 테스트되고 정제되었습니다.