CLAUDE.md 이렇게 쓰면 정말 편합니다

CLAUDE.md: 클로드 코드를 ‘오랜 동료’처럼 만드는 방법

저는 노션에 자주 쓰는 프롬프트문을 카테고리화해서 잘 관리하고 있습니다. 그리고 필요할 때마다 붙여넣기해 사용합니다. 

클로드 코드(Claude Code)를 사용할 때도 비슷했습니다. 새로운 세션을 열면 매번 의식처럼 똑같은 말을 반복했습니다. 

"우리 프로젝트는 Next.js 15 App Router를 사용해. TypeScript strict mode 켜져 있고, Tailwind CSS 쓰고 있어. 아, 그리고 상태관리는 Zustand야. API 호출은 전부 try-catch로 감싸야 하고...". 

그렇게 입력한 뒤에 진짜 제가 질문하고 싶은 것을 붙였습니다. 이 과정을 거치지 않으면 클로드 코드가 엉뚱한 대답을 하거나 멀쩡한 코드를 불필요하게 바꾸곤 했습니다.

그러던 어느 날 깜빡하고 질문을 추가하지 않았습니다. 그랬더니 클로드 코드가 “이 정보를 CLAUDE.md로 작성해 드릴까요?”라고 합니다. 

그렇게 저는 클로드 코드에 지도를 제공해 오랜 시간 함께 일한 동료처럼 결과물을 내게 하는 방법을 알게 됐습니다.

CLAUDE.md란?

먼저 CLAUDE.md는 클로드 코드가 프로젝트를 열 때마다 자동으로 읽는 '프로젝트 설명서'입니다. 프로젝트 루트에 CLAUDE.md 파일을 만들어두면, 클로드는 새 세션을 시작할 때마다 이 파일을 읽고 프로젝트의 규칙, 패턴, 기술 스택을 자동으로 인지합니다. 마치 신입 개발자에게 주는 온보딩 문서처럼, 클로드에게 "우리 프로젝트는 이렇게 작동해"라고 한 번만 설명해두는 것입니다. 

단 한 번 작성해두면, 클로드는 영원히 기억합니다. 새 세션을 시작해도, 다른 브랜치로 이동해도, 심지어 팀원이 프로젝트를 클론해도 똑같은 컨텍스트를 공유합니다.

CLAUDE.md에 무엇을 담아야 하는가

CLAUDE.md를 작성하기 시작했지만, 처음엔 뭘 써야 할지 막막했습니다. 그래서 “클로드 코드에게 CLAUDE.md에 어떤 내용들을 작성해줘야하니?” 라고 물었습니다. 꽤 친절히 알려줍니다. 클로드 코드는 다음과 같은 정보를 기입하기를 권장합니다. 

1. 기술 스택과 버전

왜 버전까지 명시해야 할까요? Next.js 13과 15는 완전히 다른 프레임워크나 마찬가지거든요. 버전을 안 적으면 클로드는 자기가 아는 가장 안정적인(=오래된) 버전으로 코드를 짭니다. 

2. 개발 규칙

이런 규칙들은 코드 리뷰에서 매번 지적되는 것들입니다. CLAUDE.md에 명시하면, 클로드가 알아서 지킵니다. 코드 리뷰 시간을 확실하게 줄일 수 있습니다. 스크립트 명령어를 추가해주면 스스로 확인이 필요한 경우에 스크립트를 실행시켜 확인할 수 있습니다. 그렇기 때문에 배포에 관련된 스크립트가 있다면 제외하는 것이 좋습니다.

3. 개발 워크플로우

저는 켄트 백(Kent Beck)이 제시한 증강 코딩의 개념을 반영했습니다. 클로드 코드를 활용한 개발할 때에도 TDD의 철학을 유지하도록 했습니다. 

이것을 적지 않으면 클로드는 매번 다른 스타일로 코드를 작성합니다. 한 파일에 camelCase와 snake_case가 섞여있는 광경을 볼 때도 있고 프로젝트의 컨벤션에 맞지 않는 경우도 발생합니다. 저는 jest를 사용해서 단위 테스트를 하는데 클로드 코드가 vitest를 설치하여 테스트하는 장면도 목격했습니다.

4. 특별 주의사항

이제 별개로 패시브하게 지시하고 싶은 사항들을 이 특별 주의사항에 넣어줍니다. 저는 클로드 코드가 개발할 때 타입을 자꾸 any로 선언해서 이 부분을 명시적으로 any를 사용하지 않도록 이 특별 주의사항에 추가했더니 더 이상 any를 사용하지 않았습니다. 

CLAUDE.md 효율적으로 활용하기: 계층적 CLAUDE.md

그런데 제가  CLAUDE.md의 사용법에 대해 클로드 코드와 대화를 나누며 알게 된 것이 있습니다. 바로 CLAUDE.md는 '규칙 파일'이 아니라 '컨텍스트 스위처'라는 점입니다. 그것을 알고 나서부터는 CLAUDE.md를 프로젝트 루트에만 두지 않고 계층 구조로 활용하게 됐죠. 

실제 프로젝트에서 어떻게 활용하는지 보여드리겠습니다.

요즘IT는 entities, widgets 등의 계층을 가지고 있습니다.(FSD는 아닙니다) 처음엔 모든 규칙을 루트 CLAUDE.md에 때려넣었습니다. 800줄이 넘는 거대한 파일이 되었고, 클로드 코드는 이 방대한 규칙을 신경 쓰느라 혼란스러워했습니다. 그래서 각 루트에는 정보를 최소한으로 담고, 각 계층별로 적합한 지시사항을 추가했습니다. 

이렇게 하면 예를 들어 entities 계층의 작업을 할 경우, src/entities/CLAUDE.md 가 자동으로 활성화됩니다. 이 계층에서는 요즘IT에서 사용할 데이터들의 처리를 담당하는데 클로드 코드가 이와 관련된 작업을 감지하면 자동으로 이 컨텍스트로 전환됩니다.

이게 왜 게임체인저인지 아시겠나요? 클로드가 작업 컨텍스트를 자동으로 인식하고, 필요한 규칙만 적용합니다. 또한  이 컨텍스트들이 조합 가능하다는 점입니다. 

예를 들어 이커머스 프로젝트를 진행한다고 합시다. 이 프로젝트에서 "인증이 필요한 결제 폼"을 작업한다면, auth, payment, form 세 개의 컨텍스트가 동시에 활성화됩니다. 클로드는 이 세 영역의 규칙을 모두 고려하면서도 충돌하지 않게 코드를 생성합니다.

클로드코드와 함께 CLAUDE.md 작성하기

저는 여러 프로젝트에 CLAUDE.md를 작성했지만 한 번도 제가 전체를 작성해본 적이 없습니다. CLAUDE.md의 작성 방법은 클로드 코드가 가장 잘 알 것이라고 생각했습니다. 그래서 다음과 같은 프롬프트로 클로드 코드에게 작성하도록 시킵니다. 

클로드는 프로젝트를 스캔하고, 패턴을 파악하고, 일관된 규칙을 추출해서 CLAUDE.md를 생성합니다. 저보다는 확실히 훨씬 꼼꼼하게 작성합니다. 그다음, 생성된 CLAUDE.md를 팀과 리뷰하면서 수정해 나갑니다. 

수정도 마찬가지로 클로드 코드에게 지시합니다. 이번에 성능 기준을 추가해 보겠습니다. 프롬프트로 “성능 기준 Lighthouse 90점 이상으로 설정해”라고 지시하겠습니다.

이렇게 하면 30분 만에 완벽한 CLAUDE.md가 완성됩니다. 처음부터 손으로 작성하려면 반나절은 걸렸을 것입니다. 지금은 작성하는 데 3분 정도 소요되었네요.

CLAUDE.md 지속적으로 개선하는 방법

핵심은 CLAUDE.md는 살아있는 문서라는 점입니다. 즉 프로젝트가 성장하면서 계속 진화해야 합니다. 그리고 그 진화를 가장 잘 도와줄 수 있는 건, 아이러니하게도 클로드 자신입니다. 

각자 주기(커밋, PR, 스프린트)를 가지고 꾸준히 클로드 코드에게 이렇게 물어보세요.

이전 커밋의 변경사항을 확인해서 CLAUDE.md에 추가할 내용이 있으면 제시해줄래?

클로드 코드는 새로운 패턴을 발견하고, 일관성이 깨진 부분을 찾아내고, 개선할 규칙을 제안합니다. 클로드 코드를 사용해서 CLAUDE.md를 관리하는 것이 가장 효율적이고 효과적인 방법입니다.

또한 우리가 열심히 작성한 규칙 중에는 필요 없는 규칙이 있을 것입니다. 그 부분도 확인해서 필요 없는 규칙을 삭제해 나가면 좋습니다. 그러려면 어떤 규칙이 많이 사용되었는지, 또 어떤 규칙이 사용되지 않았는지를 알아야 합니다. 이 또한 클로드 코드에게 물어봐서 알 수 있습니다. 마침 저희 인증 서비스에 CLAUDE.md를 점검해야 할 것 같으니 한번 물어보겠습니다.

CLAUDE.md 에서 가장 많이 참조된 규칙과 가장 참조되지 않는 규칙을 알려줘

인증 서비스다 보니 이미 인증에 대한 부분이 구현이 되어 있어서 더 이상 인증에 관련된 규칙을 참조하지 않네요. 이 부분은 이제 제거하면 좋을 것 같습니다. 그런데 저한테 확신이 없습니다. 그래서 저는 질문을 합니다. 

가장 적게 참조될 가능성이 높은 규칙을 규칙에서 제거해도 될까?

제거하지 말라고 하네요. 그리고 섹션별로 구조화하라고 제안합니다. 좋은 제안인 것 같아 진행해보겠습니다.

CLAUDE.md는 시작에 불과하다

CLAUDE.md를 작성하고 관리하는 방법을 익혔다면, 이제 클로드 코드와의 협업 품질이 확실히 달라졌을 것입니다. 매번 새 세션마다 컨텍스트를 다시 설명할 필요도 없고, 일관성 있는 코드를 받을 수 있게 되었습니다. 하지만 여전히 한계가 있습니다.

일례로 저는 Button component를 만드는 데 3분이 걸렸습니다. CLI에 아래 코드 딱 한 줄을 넣는 것으로 말이죠. 

/create-component Button

이 한 줄의 명령어로 완벽한 Button 컴포넌트를 만들어내는 것. CLAUDE.md만으로는 아직 불가능합니다. 

CLAUDE.md는 클로드 코드와 효율적으로 협업하기 위한 첫 번째 단계일 뿐입니다. 진짜 게임이 시작되는 건 이제부터입니다. 

다음 편에서도 클로드 코드를 진정한 개발 파트너로 만드는 여러 가지 기법들을 다뤄보겠습니다. 클로드 코드에 기억력을 만들어주고, Agent를 만들어주고, 커스텀 명령어를 만드는 것까지, 30분 작업을 3분으로 줄이는 방법들을 공개하겠습니다.

클로드 코드 활용 사례 세미나에 관심 있으신가요?

▶ 아래 버튼 을 눌러 알려주세요!

©️요즘IT의 모든 콘텐츠는 저작권법의 보호를 받는 바, 무단 전재와 복사, 배포 등을 금합니다.