CLAUDE.md 파일 사용: 코드베이스에 맞게 Claude Code 맞춤화하기

AI 코딩 에이전트를 사용하고 있다면, 동일한 과제에 직면하게 됩니다. 즉, 매번 같은 설명을 반복하지 않고도 아키텍처, 규칙, 워크플로우를 이해할 수 있는 충분한 맥락을 제공하려면 어떻게 해야 할까요?

코드베이스가 커지면서 문제는 더욱 복잡해졌습니다. 복잡한 모듈 관계, 도메인별 패턴, 팀 규칙은 쉽게 드러나지 않습니다. 대화를 시작할 때마다 동일한 아키텍처 결정, 테스트 요구 사항, 코드 스타일 선호도를 설명해야 합니다.

CLAUDE.md 파일은 Claude에 프로젝트에 대한 지속적인 맥락을 제공하여, 이 문제를 해결합니다. Claude가 모든 대화에 자동으로 통합하는 구성 파일처럼 작동해, 항상 프로젝트 구조, 코딩 표준, 선호하는 워크플로우를 파악할 수 있도록 합니다.

이 글에서는 CLAUDE.md를 구성하는 방법과 모범 사례, 그리고 Claude Code를 최대한 활용하기 위한 팁을 제공합니다. 

CLAUDE.md 파일은 무엇인가요?

CLAUDE.md는 리포지토리에 상주하는 특수 설정 파일로, Claude에 프로젝트별 맥락을 제공합니다. 팀과 공유하기 위해 리포지토리 루트에 배치할 수 있고, 모노레포 설정을 위해 상위 디렉토리에 둘 수 있으며, 모든 프로젝트에 공통으로 적용하도록 홈 폴더에 배치할 수도 있습니다.

다음은 리포지토리에 둘 수 있는 CLAUDE.md 예제입니다.

제대로 구성된 CLAUDE.md는 Claude가 구체적인 프로젝트와 연동되는 방식을 혁신적으로 변화시킵니다. 이 파일은 아키텍처 맥락을 제공하고, 워크플로우를 정리하며, Claude를 개발 도구와 연결하는 등 여러 가지 역할을 수행합니다. 각 항목은 Claude가 필요할 것이라고 추측해 추가하는 것이 아니라, 실제 작업 과정에서 마주한 문제를 해결하는 데 주안점을 두어야 합니다.이 파일에는 일반적인 bash 명령어, 핵심 유틸리티, 코드 스타일 가이드라인, 테스트 지침, 리포지토리 규칙, 개발자 환경 설정, 프로젝트별 경고 사항을 기록 할 수 있습니다. 정해진 형식은 없습니다. 이 파일을 간결하고 사람이 읽기 쉬운 형태로 유지하고, 사람과 Claude 모두 빠르게 이해할 수 있는 문서처럼 작성하는 것이 좋습니다.

이 CLAUDE.md 파일이 Claude의 시스템 프롬프트 일부가 됩니다. 모든 대화는 이미 이 맥락이 로드된 상태에서 시작되므로, 기본 프로젝트 정보를 반복적으로 설명할 필요가 없습니다.

/init로 시작하기‍

익숙하지 않은 코드베이스에서 CLAUDE.md를 처음부터 작성하는 것은 쉽지 않은 작업일 수 있습니다.

/init 명령어는 프로젝트를 분석하고 시작 구성 파일을 생성하여 이 프로세스를 자동화합니다.

Claude Code 세션에서 /init을 실행하세요:

Claude는 패키지 파일, 기존 문서, 구성 파일, 코드 구조를 읽어 코드베이스를 분석한 뒤, 프로젝트에 적합한 CLAUDE.md를 생성합니다. 일반적으로 생성된 파일에는 빌드 명령, 테스트 지침, 주요 디렉토리, 그리고 감지된 코딩 규칙이 포함됩니다.

/init를 완성본이 아니라 출발점으로 생각하세요. 생성된 CLAUDE.md는 명확한 패턴은 포착하지만, 워크플로우에 특화된 세밀한 뉘앙스는 놓칠 수 있습니다. Claude가 작성한 결과를 검토하고, 팀의 실제 작업 방식에 맞게 다듬어 주세요.

또한 CLAUDE.md가 이미 있는 기존 프로젝트에서도 /init을 사용할 수 있습니다. Claude는 현재 파일을 검토하고, 코드베이스 분석을 토대로 개선 사항을 제안합니다.

/init을 실행한 후, 다음 단계를 고려하세요.

• 생성된 콘텐츠의 정확성을 검토합니다.
• Claude가 추론하지 못했던 워크플로우 지침(브랜치 네이밍 규칙, 배포 프로세스, 코드 리뷰 요구 사항)을 추가합니다.
• 프로젝트에 적용되지 않는 일반 지침은 삭제합니다
• 팀원들이 활용할 수 있도록 파일을 버전 관리에 커밋합니다

/init 명령어는 빠르게 방향을 결정하는 데 유용하지만, 진정한 가치는 시간이 지남에 따라 생성된 파일을 반복해서 개선하는 것에서 나옵니다. Claude Code로 작업하면서 자주 반복하게 되는 지침이 있다면, # 키를 활용해 추가하세요. 이러한 누적된 내용이 팀의 업무 방식을 정확하게 반영하는 CLAUDE.md로 발전합니다.

CLAUDE.md를 구성하는 방법

다음 섹션은 복잡한 아키텍처 탐색, 다단계 작업의 진행 상황 추적, 맞춤형 도구 통합, 일관된 워크플로우를 통해 재작업 방지와 같은 효과를 극대화할 수 있도록 콘텐츠를 구조화하는 방법을 보여줍니다.

Claude에 지도를 제공하세요

매번 새로운 작업을 할 때마다 프로젝트 아키텍처, 주요 라이브러리, 코딩 스타일을 설명하는 것은 번거로운 일이 될 것입니다. 매번 수동으로 반복해서 상기시키지 않고도 코드베이스 구조에 대한 일관된 맥락을 유지할 수 있도록 Claude가 필요합니다.

CLAUDE.md에 프로젝트 요약과 개요 디렉토리 구조를 추가하세요. 이를 통해 Claude는 코드베이스를 탐색할 때 즉각적인 방향을 제시합니다. 

Claude는 주요 디렉토리를 보여주는 간단한 트리 출력만으로도, 다양한 구성 요소가 어디에 있는지 이해하는 데 도움이 됩니다.

주요 의존성 요소, 아키텍처 패턴, 비표준 구조적 결정에 대한 정보까지 포함해야 합니다. 도메인 중심 설계, 마이크로서비스, 특정 프레임워크를 사용하는 경우, 이를 문서화하세요. Claude는 이 지도를 활용해 코드 위치와 변변경을 적용해야 할 지점을 더 정확하게 판단합니다.

Claude를 도구에 연결하세요

Claude는 전체 환경을 그대로 물려받지만, 어떤 맞춤형 도구와 스크립트를 사용할지에 대한 지침이 필요합니다. 대부분의 팀은 배포, 테스트, 코드 생성 전문 유틸리티를 보유하고 있을 것이며, Claude 역시 이러한 도구를 인지하고 있어야 합니다.

맞춤형 도구는 사용 사례와 함께 CLAUDE.md에 기록해 두세요. 도구 이름, 기본 사용 패턴, 그리고 언제 사용해야 하는지 포함하는 것이 좋습니다. 만약 도구가 --help 플래그를 통해 도움말 문서를 제공한다면, Claude가 확인할 수 있도록 해당 정보를 언급하세요. 복잡한 도구의 경우, 팀이 자주 사용하는 일반적인 호출 예시를 추가해 두세요.

Claude는 MCP(모델 컨텍스트 프로토콜) 클라이언트 역할을 하며, 기능을 확장하는 MCP 서버에 연결합니다. 이러한 연결은 프로젝트 설정, 글로벌 구성 또는 체크인된 .mcp.json 파일을 통해 구성합니다. 도구가 예상대로 작동하지 않을 경우 --mcp-debug 플래그를 통해 연결 문제를 해결할 수 있습니다.

예를 들어, 조직에 맞게 Slack MCP 서버를 구성하고 Claude가 그 사용 방법을 이해해야 한다면, CLAUDE.md에 다음과 같은 내용을 포함시킵니다.

MCP 기본 사항과 모범 사례에 대해 자세히 알아보세요.

Claude Code의 권한 설정에 대한 자세한 내용은 code.claude.com의 settings.json 문서를 참조하세요.

표준 워크플로우 정의

Claude가 계획 없이 바로 코드 변경을 수행하게 되면 재작업을 해야 합니다. Claude는 요구 사항을 충족하지 못하는 솔루션을 구현하거나, 잘못된 아키텍처 접근 방식을 선택하거나, 기존 기능을 방해하는 변경을 할 수 있습니다.

Claude가 행동하기 전에 먼저 생각하도록 만들어야 합니다. 작업 유형별로 Claude가 따라야 할 표준 워크플로우를 CLAUDE.md에 정의하세요. 안정적인 기본 워크플로우는 변경 사항을 적용하기 전에 다음 네 가지 질문을 해결합니다.

1. 현재 상태를 파악하기 위해 사전 조사가 필요한 질문인가요?
2. 구현 전에 세부적인 계획이 필요한가요?
3. 어떤 추가 정보가 더 필요한가요?
4. 효과는 어떻게 테스트되나요?

구체적인 워크플로우에는 기능 개발을 위한 탐색–계획–코드–커밋 흐름, 알고리즘 작업을 위한 테스트 주도 개발, UI 변경을 위한 시각적 반복 방식 등이 포함될 수 있습니다. 테스트 요구 사항, 커밋 메시지 형식, 승인 단계를 문서화하세요. Claude가 사전에 워크플로우를 파악하면, 추측이 아닌 팀의 실제 프로세스에 맞게 작업을 구조화할 수 있습니다.

워크플로우 지침의 예시는 다음과 같습니다. 

Claude Code 작업을 위한 추가 팁 

CLAUDE.md 파일 구성 외에도 Claude Code 작업 방식을 개선하는 세 가지 추가 기법이 있습니다.

맥락을 최신 상태로 유지하세요

Claude Code를 계속 사용하다 보면 불필요한 맥락이 누적됩니다. 이전 작업에서 가져온 파일 내용, 더 이상 중요하지 않은 명령어 출력, 부차적인 대화들이 컨텍스트 창을 채우게 됩니다. 신호 대비 잡음 비율이 낮아질수록, Claude는 현재 작업에 집중하기 어려워집니다.

개별 작업 간에 /clear를 사용하여 컨텍스트 창을 재설정하세요. 이렇게 하면 누적된 기록을 삭제하면서, CLAUDE.md 구성과 새로운 문제를 신선한 맥락에서 처리하는 Claude의 능력은 그대로 유지됩니다. 한 작업 세션을 마무리하고 새로운 세션을 시작하는 것으로 생각하세요.

디버깅 인증을 완료하고 새 API 엔드포인트 구현으로 전환할 때는 기존 맥락을 정리하세요. 인증 세부 사항은 더 이상 중요하지 않으며, 새로운 작업에 방해가 됩니다.

서로 다른 단계에는 서브에이전트를 활용하세요

긴 대화는 새로운 작업에 방해가 되는 맥락을 누적시킵니다. 복잡한 인증 흐름을 디버깅한 뒤 동일한 코드에 대한 보안 검토를 진행하면 디버깅 세부 정보가 Claude의 보안 분석에 영향을 미쳐, 문제를 간과하거나 이미 해결된 문제에 매달릴 수 있습니다.

Claude에게 각 단계의 업무에 서브 에이전트를 사용하도록 전하세요. 서브 에이전트는 컨텍스트를 격리시키고, 이전 작업의 정보가 새로운 분석을 방해하지 않도록 합니다. 결제 프로세서 구현 후, Claude에 동일한 대화를 계속하는 대신 "하위 에이전트를 활용해 코드의 보안 검토를 수행하도록" 지시했습니다.

서브에이전트는 각 단계마다 다른 관점이 필요한 다단계 워크플로우에 가장 적합합니다. 구현은 아키텍처 컨텍스트와 기능 요구 사항이 필요하고, 보안 검토는 취약점에만 집중된 새로운 시선이 필요합니다. 두 가지 분석 모두 정확한 상태로 유지, 컨텍스트 분리

맞춤형 명령 생성

반복적인 프롬프트는 시간 낭비입니다. "이 코드에서 보안 문제가 있는지 검토하세요", "성능 문제가 있는지 분석하세요"라는 말을 반복해서 입력하고 있습니다. 매번 좋은 결과를 얻었던 정확한 표현을 기억해야 합니다.

커스텀 슬래시 명령은 이를 .claude/commands/ 디렉토리에 마크다운 파일로 저장합니다. 원하는 성능 최적화 프롬프트로 performance-optimization.mm라는 파일을 생성하고, 모든 대화에서 /performance-optimization으로 설정할 수 있습니다. 명령어는 $1, $2와 같은 자리 번호를 통해 인수를 뒷받침하며, 특정 파일이나 매개변수를 전달할 수 있도록 합니다.

예를 들어, performance-optimization.md는 다음과 같습니다.

수동으로 맞춤형 명령 파일을 작성할 필요가 없습니다. Claude에 요청하세요:

Claude가 마크다운 파일을 .claude/commands/performance-optimization.md에 기록하고, 즉시 명령을 사용할 수 있습니다.

간단하게 시작하고, 신중하게 확장하세요

처음부터 모든 것을 담은 CLAUDE.md를 만들고 싶은 유혹이 들 수 있지만, 그 충동은 피하는 것이 좋습니다.

CLAUDE.md는 매번 Claude Code의 맥락에 추가되므로, 컨텍스트 엔지니어링과 프롬프트 엔지니어링 관점에서 간결하게 유지되어야 합니다. 한 가지 옵션은 정보를 별도의 마크다운 파일로 나누고, CLAUDE.md 파일 내에서 참조하는 것입니다.

중요한 정보, API 키, 자격 증명, 데이터베이스 연결 문자열, 보안 취약점 상세 정보는 포함하지 않아야 합니다. 특히 버전 관리를 위해 커밋하는 경우에는 더욱 주의해야 합니다. CLAUDE.md는 Claude의 시스템 프롬프트 일부가 되므로, 공개적으로 공유될 수 있는 문서임을 염두에 두고 작성해야 합니다.

CLAUDE.md를 활용하세요

CLAUDE.md 파일은 Claude Code를 범용 보조 도구에서 코드베이스에 맞게 특별히 구성된 도구로 전환합니다. 기본 프로젝트 구조와 빌드 문서 같은 간단한 요소부터 시작하여, 워크플로우의 실제 문제점을 기준으로 확장해야 합니다.

가장 효과적인 CLAUDE.md 파일은 실제 문제를 해결합니다. 반복적으로 입력하는 명령어를 기록하고, 설명하는 데 오래 걸리던 아키텍처 맥락을 포착하며, 재작업을 방지하는 워크플로우를 수립합니다. 파일은 그럴듯해 보이는 이론적 모범 사례가 아니라 팀이 소프트웨어를 개발하는 방식을 실제 현실에 맞게 그대로 반영해야 합니다.

맞춤 설정을 일회성 작업이 아니라, 지속적으로 다듬어 가는 과정으로 생각해 보세요. 프로젝트는 변하고, 팀은 더 나은 패턴을 배우며, 새로운 도구가 워크플로우에 도입됩니다. 잘 관리되는 CLAUDE.md는 코드베이스와 함께 진화하며, 복잡한 소프트웨어에서 AI 지원을 받을 때 발생하는 불필요한 부담을 지속적으로 줄여줍니다.

지금 바로 Claude Code를 시작해 보세요