CLAUDE.md 파일로 프로젝트별 컨텍스트를 설정해 Claude Code가 아키텍처, 관례, 워크플로를 이해하도록 구성하는 방법을 소개합니다.
AI 코딩 에이전트를 사용할 때 모두가 겪는 공통적인 난제가 있다. 내 아키텍처, 관례, 워크플로를 이해할 만큼 충분한 컨텍스트를 어떻게 제공하되, 매번 같은 말을 반복하지 않을 수 있을까?
코드베이스가 커질수록 이 문제는 더 심각해진다. 복잡한 모듈 관계, 도메인 특화 패턴, 팀 관례는 겉으로 잘 드러나지 않는다. 결국 매 대화의 시작마다 동일한 아키텍처 결정, 테스트 요구사항, 코드 스타일 선호도를 계속 설명하게 된다.
CLAUDE.md 파일은 Claude에게 프로젝트에 대한 지속적인 컨텍스트를 제공함으로써 이 문제를 해결한다. Claude가 매 대화에서 자동으로 참고하는 설정 파일이라고 생각하면 된다. 이 파일 덕분에 Claude는 항상 프로젝트 구조, 코딩 표준, 선호하는 워크플로를 알고 있는 상태에서 작업할 수 있다.
이 글에서는 CLAUDE.md를 어떻게 구성할지, 베스트 프랙티스, 그리고 Claude Code를 최대한 잘 활용하기 위한 팁을 단계별로 살펴본다.
CLAUDE.md는 저장소에 위치하며 프로젝트별 컨텍스트를 Claude에 제공하는 특별한 설정 파일이다. 저장소 루트에 두어 팀 전체와 공유할 수 있고, 모노레포 환경에서는 상위 디렉터리에 둘 수도 있으며, 홈 디렉터리에 두어 모든 프로젝트에 공통으로 적용되게 할 수도 있다.
다음은 저장소에 둘 수 있는 예시 CLAUDE.md이다:
md# Project Context When working with this codebase, prioritize readability over cleverness. Ask clarifying questions before making architectural changes. ## About This Project FastAPI REST API for user authentication and profiles. Uses SQLAlchemy for database operations and Pydantic for validation. ## Key Directories - `app/models/` - database models - `app/api/` - route handlers - `app/core/` - configuration and utilities ## Standards - Type hints required on all functions - pytest for testing (fixtures in `tests/conftest.py`) - PEP 8 with 100 character lines ## Common Commands ```bash uvicorn app.main:app --reload # dev server pytest tests/ -v # run tests
All routes use /api/v1 prefix. JWT tokens expire after 24 hours.
잘 구성된 CLAUDE.md는 Claude가 특정 프로젝트와 상호작용하는 방식을 완전히 바꿔 놓는다. 이 파일은 아키텍처 컨텍스트 제공, 워크플로 수립, 그리고 Claude를 개발 도구들과 연결하는 등 여러 목적을 수행한다. 각 항목은 “Claude가 필요할지도 모른다”는 이론적인 가정이 아니라, 실제로 겪은 문제를 해결하기 위해 추가해야 한다.
이 파일에는 자주 쓰는 bash 명령어, 핵심 유틸리티, 코드 스타일 가이드라인, 테스트 방법, 저장소 관례, 개발 환경 설정 방법, 프로젝트 특화 경고 등을 문서화할 수 있다. 필수 형식은 없다. 사람과 Claude가 모두 빠르게 이해할 수 있도록, 짧고 읽기 쉬운 문서를 작성한다는 느낌으로 유지하는 것이 좋다.
CLAUDE.md 파일은 Claude의 시스템 프롬프트 일부가 된다. 모든 대화는 이 컨텍스트를 이미 로드한 상태에서 시작되므로, 기본적인 프로젝트 정보를 반복해서 설명할 필요가 없다.
**Getting started with /init**
------------------------------
특히 익숙하지 않은 코드베이스에서는 CLAUDE.md를 처음부터 직접 만드는 일이 부담스럽게 느껴질 수 있다.
`/init` 명령은 프로젝트를 분석해 초안 설정 파일을 자동으로 생성해 준다.
어떤 Claude Code 세션에서든 `/init`을 실행하자:
```bash
cd your-project
claude
/init
Claude는 패키지 파일, 기존 문서, 설정 파일, 코드 구조를 읽어 코드베이스를 살펴본 뒤, 프로젝트에 맞춘 CLAUDE.md 초안을 생성한다. 생성된 파일에는 보통 빌드 명령, 테스트 방법, 핵심 디렉터리, 감지한 코딩 관례 등이 포함된다.
/init은 완성본이 아니라 출발점이라고 생각하자. 생성된 CLAUDE.md는 눈에 잘 띄는 패턴은 잡아내지만, 실제 워크플로에 특화된 미묘한 부분은 놓칠 수 있다. Claude가 만들어 준 내용을 검토하고, 팀의 실제 관행에 맞게 다듬어야 한다.
이미 CLAUDE.md가 있는 기존 프로젝트에도 /init을 사용할 수 있다. 이 경우 Claude는 현재 파일을 검토하고, 코드베이스를 탐색하며 배운 내용을 바탕으로 개선점을 제안한다.
/init을 실행한 뒤에는 다음 단계를 고려해 보자:
/init 명령은 빠르게 방향을 잡는 데 유용하지만, 진짜 가치는 시간이 지나며 파일을 반복 개선하는 데서 나온다. Claude Code와 함께 작업하면서 # 키를 사용해 자꾸 반복해서 말하게 되는 지침을 파일에 추가하라. 이렇게 쌓인 내용이 결국 팀의 실제 작업 방식을 잘 반영하는 CLAUDE.md가 된다.
다음 섹션들은 CLAUDE.md 내용을 최대한 효과적으로 구성하는 법을 설명한다. 복잡한 아키텍처 탐색, 여러 단계에 걸친 작업의 진행 상황 추적, 커스텀 도구 통합, 일관된 워크플로를 통한 재작업 방지 등을 다룬다.
새로운 작업을 할 때마다 프로젝트 아키텍처, 핵심 라이브러리, 코딩 스타일을 설명하는 일은 금방 지겹고 번거로워진다. 코드베이스 구조에 대한 일관된 컨텍스트를 Claude가 스스로 유지하도록 해야, 매번 수동으로 되짚어 줄 필요가 없다.
프로젝트 요약과 상위 수준 디렉터리 구조를 CLAUDE.md에 추가하라. 이렇게 하면 Claude가 코드베이스를 탐색할 때 즉시 방향 감각을 가질 수 있다.
핵심 디렉터리를 보여 주는 간단한 트리 출력만으로도, 각 컴포넌트가 어디에 위치하는지 이해하는 데 도움이 된다:
textmain.py ├── logs │ ├── application.log ├── modules │ ├── cli.py │ ├── logging_utils.py │ ├── media_handler.py │ ├── player.py
주요 의존성, 아키텍처 패턴, 비표준적인 구조 선택에 대한 정보도 포함하라. 도메인 주도 설계(DDD), 마이크로서비스, 특정 프레임워크를 사용한다면 그 사실을 문서화해야 한다. Claude는 이 “지도”를 기반으로 코드를 어디서 찾고 어디를 수정할지 더 나은 결정을 내린다.
Claude는 여러분의 개발 환경 전체에 접근할 수 있지만, 어떤 커스텀 도구와 스크립트를 사용해야 하는지에 대해서는 안내가 필요하다. 팀마다 배포, 테스트, 코드 생성 등을 위한 전용 유틸리티가 있을 가능성이 크고, Claude 역시 이를 알아야 제대로 활용할 수 있다.
커스텀 도구를 CLAUDE.md에 사용 예시와 함께 문서화하라. 도구 이름, 기본 사용 패턴, 언제 호출해야 하는지를 포함한다. --help 플래그로 도움말을 제공하는 도구라면, Claude가 먼저 이를 확인할 수 있게 해당 사실을 적어 두는 것이 좋다. 복잡한 도구라면, 팀이 자주 사용하는 대표적인 호출 예시를 추가하라.
Claude는 MCP(Model Context Protocol) 클라이언트로 동작하며, 기능을 확장해 주는 MCP 서버에 연결된다. MCP 서버는 프로젝트 설정, 전역 설정, 혹은 저장소에 포함된 .mcp.json 파일을 통해 구성할 수 있다. --mcp-debug 플래그는 도구가 예상대로 보이지 않을 때 연결 문제를 디버깅하는 데 도움이 된다.
예를 들어, 조직에서 설정한 Slack MCP 서버가 있고 Claude가 이를 어떻게 사용해야 하는지 이해시켜야 한다면, CLAUDE.md에 다음과 같이 작성할 수 있다:
md### Slack MCP - Posts to #dev-notifications channel only - Use for deployment notifications and build failures - Do not use for individual PR updates (those go through GitHub webhooks) - Rate limited to 10 messages per hour
MCP의 기본 개념과 베스트 프랙티스에 대해 더 알아볼 수 있다.
Claude Code의 권한 설정에 대한 자세한 정보는 code.claude.com의 settings.json 문서를 참고하라.
아무런 계획 없이 곧바로 코드 변경에 들어가게 하면, 재작업이 발생하기 쉽다. Claude가 요구사항을 놓친 상태에서 구현을 진행하거나, 잘못된 아키텍처 접근을 선택하거나, 기존 기능을 깨뜨리는 변경을 할 수도 있다.
Claude가 행동하기 전에 먼저 “생각”하게 만들어야 한다. CLAUDE.md에 작업 유형별로 Claude가 따라야 할 표준 워크플로를 정의하라. 기본 워크플로는 코드 변경 전에 다음 네 가지를 점검하도록 하면 좋다:
특정 워크플로 예시로는 기능 개발 시 “탐색 → 계획 → 구현 → 커밋(explore-plan-code-commit)” 순서, 알고리즘 작업 시 테스트 주도 개발(TDD), UI 변경 시 시각적 반복(iteration) 등이 있다. 테스트 요구사항, 커밋 메시지 형식, 승인 단계 등도 문서화하라. Claude가 워크플로를 미리 알고 있으면, 팀의 실제 프로세스에 맞게 작업 구조를 짜고 추측에 의존하지 않는다.
다음은 워크플로 지침의 예시다:
md1) Before modifying code in the following locations: X, Y, Z - Consider how it might affect A, B, C - Construct an implementation plan - Develop a test plan that will validate the following functions...
CLAUDE.md 파일 설정 외에도, Claude Code와 더 잘 협업할 수 있는 추가 기법이 몇 가지 있다.
Claude Code와 오래 작업하다 보면 점점 관련 없는 컨텍스트가 쌓인다. 이전 작업에서 열어 본 파일 내용, 이제는 의미 없는 명령 출력, 주변부 대화들이 Claude의 컨텍스트 창을 가득 채운다. 신호 대비 잡음 비율이 떨어지면 Claude는 현재 작업에 집중하기 어려워진다.
작업이 뚜렷이 구분될 때마다 /clear를 사용해 컨텍스트 창을 초기화하라. 이 명령은 누적된 대화 이력을 제거하지만, CLAUDE.md 설정과 새로운 문제를 다룰 수 있는 Claude의 능력은 그대로 유지된다. 하나의 작업 세션을 닫고, 새로운 세션을 여는 것처럼 생각하면 된다.
예를 들어 인증 문제 디버깅을 마치고 새로운 API 엔드포인트 구현으로 넘어갈 때, 컨텍스트를 비우자. 더 이상 인증 관련 세부 사항은 중요하지 않고, 새 작업에는 오히려 방해가 된다.
긴 대화는 새로운 작업에 방해가 되는 컨텍스트를 계속 축적한다. 복잡한 인증 플로를 디버깅한 뒤, 같은 코드에 대해 보안 검토를 해야 한다고 해 보자. 이전 디버깅 세부 내용이 Claude의 보안 분석에 영향을 주어, 이미 해결된 이슈에 집중하거나 실제 취약점을 간과하게 만들 수 있다.
이럴 때는 작업 단계를 분리하기 위해 subagent를 사용하라고 Claude에 지시하라. 서브에이전트는 서로 격리된 컨텍스트를 유지하므로, 앞선 작업 정보가 새로운 분석에 끼어들지 않는다. 예를 들어 결제 모듈을 구현한 뒤, 같은 대화에서 계속 이어 가기보다는 “이 코드의 보안 검토를 위해 서브 에이전트를 사용해 달라”고 지시하는 식이다.
서브에이전트는 각 단계에 서로 다른 관점을 요구하는 다단계 워크플로에 특히 잘 어울린다. 구현 단계에서는 아키텍처 컨텍스트와 기능 요구사항이 중요하고, 보안 검토 단계에서는 오직 취약점에만 집중할 수 있는 “새로운 눈”이 필요하다. 컨텍스트를 분리하면 두 분석 모두 더 날카롭게 유지할 수 있다.
반복적인 프롬프트는 시간을 낭비하게 만든다. “이 코드를 보안 이슈 관점에서 리뷰해 줘”, “성능 관점에서 분석해 줘”라는 말을 계속해서 입력해야 하고, 매번 좋은 결과를 내는 정확한 문구를 기억해야 한다.
사용자 정의 슬래시 명령은 이런 프롬프트를 .claude/commands/ 디렉터리의 마크다운 파일로 저장한다. 예를 들어 원하는 성능 최적화 프롬프트를 담은 performance-optimization.md 파일을 만들면, 어떤 대화에서든 /performance-optimization 명령으로 사용할 수 있다. 명령은 $ARGUMENTS나 $1, $2 같은 번호 기반 플레이스홀더를 통해 인자를 지원하므로, 특정 파일이나 파라미터를 전달할 수 있다.
예를 들어 performance-optimization.md는 다음과 같을 수 있다:
md# Performance Optimization Analyze the provided code for performance bottlenecks and optimization opportunities. Conduct a thorough review covering: ## Areas to Analyze ### Database & Data Access - N+1 query problems and missing eager loading - Lack of database indexes on frequently queried columns - Inefficient joins or subqueries - Missing pagination on large result sets - Absence of query result caching - Connection pooling issues ### Algorithm Efficiency - Time complexity issues (O(n²) or worse when better exists) - Nested loops that could be optimized - Redundant calculations or repeated work - Inefficient data structure choices - Missing memoization or dynamic programming opportunities ### Memory Management - Memory leaks or retained references - Loading entire datasets when streaming is possible - Excessive object instantiation in loops - Large data structures kept in memory unnecessarily - Missing garbage collection opportunities ### Async & Concurrency - Blocking I/O operations that should be async - Sequential operations that could run in parallel - Missing Promise.all() or concurrent execution patterns - Synchronous file operations - Unoptimized worker thread usage ### Network & I/O - Excessive API calls (missing request batching) - No response caching strategy - Large payloads without compression - Missing CDN usage for static assets - Lack of connection reuse ### Frontend Performance - Render-blocking JavaScript or CSS - Missing code splitting or lazy loading - Unoptimized images or assets - Excessive DOM manipulations or reflows - Missing virtualization for long lists - No debouncing/throttling on expensive operations ### Caching - Missing HTTP caching headers - No application-level caching layer - Absence of memoization for pure functions - Static assets without cache busting ## Output Format For each issue identified: 1. **Issue**: Describe the performance problem 2. **Location**: Specify file/function/line numbers 3. **Impact**: Rate severity (Critical/High/Medium/Low) and explain expected performance degradation 4. **Current Complexity**: Include time/space complexity where applicable 5. **Recommendation**: Provide specific optimization strategy 6. **Code Example**: Show optimized version when possible 7. **Expected Improvement**: Quantify performance gains if measurable If code is well-optimized: - Confirm optimization status - List performance best practices properly implemented - Note any minor improvements possible **Code to review:**
$ARGUMENTS
사용자 정의 명령 파일을 반드시 직접 작성할 필요는 없다. Claude에게 대신 작성해 달라고 요청해도 된다:
textCreate a custom slash command called /performance-optimization that analyzes code for database query issues, algorithm efficiency, memory management, and caching opportunities.
Claude는 .claude/commands/performance-optimization.md 파일을 생성해 주며, 해당 명령은 즉시 사용할 수 있게 된다.
처음부터 모든 것을 다 담은 “완벽한” CLAUDE.md를 만들고 싶은 유혹이 들 수 있다. 그 유혹을 의식적으로 이겨 내자.
CLAUDE.md는 매번 Claude Code의 컨텍스트에 포함되므로, 컨텍스트 엔지니어링과 프롬프트 엔지니어링 관점에서 최대한 간결하게 유지하는 것이 좋다. 한 가지 방법은, 정보를 여러 개의 개별 마크다운 파일로 나누고, CLAUDE.md에서 이 파일들을 참조하도록 하는 것이다.
민감한 정보, API 키, 자격 증명, 데이터베이스 연결 문자열, 상세한 보안 취약점 정보 등은 포함하지 말라. 특히 버전 관리에 커밋할 계획이라면 더욱 주의해야 한다. CLAUDE.md는 Claude의 시스템 프롬프트 일부가 되므로, 공개 문서라고 생각하고 작성해야 한다.
CLAUDE.md 파일은 Claude Code를 범용 어시스턴트에서, 여러분의 코드베이스에 특화된 도구로 바꾸어 준다. 먼저 기본적인 프로젝트 구조와 빌드 문서를 간단히 정리한 뒤, 실제 워크플로에서 마찰이 생기는 지점들을 중심으로 점진적으로 확장하라.
가장 효과적인 CLAUDE.md 파일은 실제 문제를 해결하는 파일이다. 반복해서 입력하는 명령을 문서화하고, 설명하는 데 10분씩 걸리던 아키텍처 컨텍스트를 잡아 두며, 재작업을 막아 주는 워크플로를 정립한다. 이 파일은 팀이 실제로 소프트웨어를 개발하는 방식을 반영해야지, 그럴듯해 보이지만 현실과 맞지 않는 이론적 베스트 프랙티스를 나열해서는 안 된다.
커스터마이징을 일회성 설정 작업이 아니라, 지속적인 실천으로 바라보자. 프로젝트가 바뀌고, 팀이 더 나은 패턴을 배우고, 새로운 도구가 워크플로에 들어온다. 잘 관리되는 CLAUDE.md는 코드베이스와 함께 발전하며, 복잡한 소프트웨어에서 AI 지원을 받는 과정의 마찰을 꾸준히 줄여 준다.
지금 바로Claude Code를 사용해 시작해 보자.