좋은 CLAUDE.md 작성법: 코드 에이전트를 팀 동료처럼 만드는 비밀

Claude 같은 코드 에이전트에게 "우리 코드베이스를 제대로 이해하는 팀 동료" 역할을 맡기고 싶다면, 시작점은 항상 하나입니다. 바로 CLAUDE.md입니다.

이 한 파일이 매 세션마다 에이전트에게 자동으로 주입되는 유일한 문서이고, 그렇기 때문에 잘 만들면 강력한 생산성 부스터가 되고, 엉성하게 만들면 에이전트가 더 자주 엉뚱한 소리를 하게 됩니다.

이 글에서는:

• 왜 CLAUDE.md가 중요한지

• 어떤 내용을, 얼마나, 어떻게 담아야 하는지

• 흔히 하는 실수와 그 대안은 무엇인지

를 실제 사용 관점에서 쉽고 재미있게 풀어보겠습니다. Cursor, Zed, OpenCode, Codex 등 AGENTS.md를 쓰는 환경에도 그대로 적용할 수 있습니다.

LLM은 "대부분" 기억을 안 한다: CLAUDE.md가 중요한 이유

많은 분들이 "에이전트가 우리 코드베이스를 계속 쓰다 보면, 알아서 익숙해지겠지?"라고 기대합니다. 불편한 진실을 하나 말씀드리자면, 그렇지 않습니다.

LLM은 본질적으로 "거대한 함수"입니다. 한 번 학습이 끝나고 나면, 실사용 단계에서는 가중치가 더 이상 바뀌지 않기 때문에 "경험으로 성장"하지 않습니다. 모델이 아는 것은 오직, 지금 프롬프트로 넣어준 토큰뿐입니다.

코드 에이전트도 마찬가지입니다.

• 매 세션 시작 시, 에이전트는 당신의 코드베이스에 대해 "완전히 백지 상태"입니다.

• 실행 중인 에이전트가 과거 세션을 기억하는 것도 아닙니다(별도로 메모리를 설계하지 않는 이상).

• 매번 "이 프로젝트가 뭔지, 어디에 무엇이 있는지, 어떻게 실행·테스트하는지"를 알려줘야 합니다.

여기서 게임 체인저가 되는 것이 CLAUDE.md입니다. 이 파일 한 개만은 매 세션마다 자동으로 주입되기 때문에, 사실상 "에이전트용 온보딩 매뉴얼"이자 "공통 참고서" 역할을 합니다.

즉, CLAUDE.md를 잘 작성한다는 것은 곧 "내가 없는 회의에도 에이전트가 알아서 제대로 판단할 수 있는 환경"을 만들어주는 일입니다.

CLAUDE.md의 핵심 역할: 프로젝트의 WHY, WHAT, HOW 전달하기

그렇다면, CLAUDE.md에는 무엇을 적어야 할까요? 핵심은 세 가지입니다. 이 세 가지만 잘 담아도 절반은 성공입니다.

첫째, WHAT: 기술 스택과 구조를 알려주세요.

• 어떤 언어·프레임워크를 쓰는지

• 모노레포라면 앱과 패키지가 어떻게 나뉘어 있는지

• 디렉터리 구조와 각 폴더의 역할은 무엇인지

요컨대 "코드베이스 지도"를 그려주는 느낌입니다. 에이전트가 "이 기능은 어디서부터 찾아봐야 하지?"라고 고민하지 않게 해주는 것이 목표입니다.

둘째, WHY: 프로젝트의 목적과 의도를 담으세요.

• 이 서비스는 어떤 문제를 해결하기 위해 존재하는지

• 주요 모듈들은 각각 어떤 책임과 역할을 가지는지

• 중요한 설계 결정들이 "왜" 그렇게 되어 있는지

에이전트가 단순히 코드를 고치는 수준을 넘어, "프로덕트 목표에 맞는 방향"으로 작업할 수 있게 만드는 정보입니다.

셋째, HOW: 이 프로젝트를 어떻게 다뤄야 하는지 알려주세요.

• 개발 환경에서 어떤 명령으로 서버를 띄우는지

• 테스트, 타입체크, 빌드, 린트는 어떤 도구와 명령을 쓰는지

• 변경 사항을 검증하는 표준적인 절차는 무엇인지

다만 여기서 중요한 포인트가 있습니다. 에이전트에게 "생각할 필요가 없을 정도로" 모든 명령과 옵션을 다 나열하면, 오히려 성능이 떨어집니다. 다음 섹션에서 자세히 설명하겠습니다.

왜 Claude는 내 CLAUDE.md를 자꾸 무시할까?

많은 분들이 실제로 겪는 문제입니다. "분명 CLAUDE.md에 써뒀는데, 왜 또 물어보지?", "왜 규칙을 안 지키지?" 같은 순간이 자주 옵니다.

실제로 Claude Code는 CLAUDE.md를 이런 식으로 주입합니다. 시스템 메시지와 함께, 다음과 같은 안내가 들어갑니다(요약):

"이 컨텍스트는 현재 작업과 관련 없을 수도 있으니, 매우 관련성이 높을 때만 사용하라."

즉, 모델에게 "CLAUDE.md 내용을 무조건 따르지 말고, 관련 있을 때만 참조해라"라고 일부러 알려주는 겁니다.

왜 이렇게 했을까요?

• 많은 사용자들이 CLAUDE.md를 "땜빵 지침서"처럼 쓰기 시작했습니다.

• 특정 상황에서만 필요하거나, 감정적인(?) 요구사항들을 한가득 넣는 경우가 많았고,

• 이게 전체 작업 품질을 오히려 망치는 결과로 이어졌을 가능성이 큽니다.

그래서 Anthropic은 "모델이 봐도 별로 중요하지 않다고 느끼는 내용은, 과감히 무시하게" 해둔 것으로 보입니다.

결국 결론은 하나입니다. CLAUDE.md에 "보편적으로 중요한 내용만 간결하게" 담을수록, 모델이 그 내용을 진지하게 받아들일 확률이 높아집니다.

지침은 최소한으로: Less is more

많은 개발자들이 처음 CLAUDE.md를 만들 때 이렇게 합니다.

• "혹시 모르니, 쓸 수 있는 명령 다 넣자."

• "코드 스타일 가이드도 전부 넣어야지."

• "예외 케이스도 다 적어야 안전하지 않을까?"

하지만 LLM의 특성을 감안하면, 이 전략은 거의 항상 역효과입니다.

연구와 실사용 경험을 정리해보면 대략 이런 경향이 있습니다.

• 최신 대형 모델도 "지킬 수 있는 지침 수"에는 한계가 있습니다(대략 150~200개 정도).

• 작은 모델일수록, 그리고 "깊게 생각하는 모드가 아닌" 모델일수록 그 한계는 훨씬 더 낮습니다.

• 지침이 많아지면, 모델은 특정 부분만 무시하는 게 아니라 전체적인 지침 준수 능력이 일괄적으로 떨어집니다.

여기에 Claude Code의 시스템 프롬프트도 이미 수십 개의 지침을 포함하고 있습니다. 즉, CLAUDE.md에 잔뜩 규칙을 추가하는 순간, 이미 "수용 가능한 한계"에 가까워진 상태일 수 있습니다.

그래서 좋은 전략은 매우 단순합니다.

• "항상" 중요한 지침만 남기고,

• 상황에 따라 달라질 수 있는 것들은 과감히 빼는 것.

지침은 "최대한 적게, 그러나 꼭 필요한 것만" 남기는 것이, 실제 작업 품질을 올리는 지름길입니다.

CLAUDE.md 길이와 내용 선정: 짧고, 넓게, 보편적으로

컨텍스트 창은 한정된 자원입니다. 여기에 "지금 하는 작업과 관련 없는 정보"가 많이 들어가 있으면, 모델의 집중력은 그만큼 흐려집니다.

특히 CLAUDE.md는 모든 세션에 항상 포함되기 때문에, 여기에 들어가는 내용은 다음 기준을 반드시 만족하는 것이 좋습니다.

• 어떤 종류의 작업이든 대부분에 도움이 되는 정보인지

• 특정 기능이나 특정 상황에만 필요한 내용은 아닌지

예를 들어, "새로운 데이터베이스 스키마를 설계할 때 고려해야 할 15가지 원칙" 같은 내용은, 정말 스키마 설계 작업을 할 때만 필요합니다. 이걸 CLAUDE.md에 넣어두면, 나머지 95%의 작업에서는 그냥 노이즈일 뿐입니다.

길이도 마찬가지입니다.

• 커뮤니티에서는 대략 300줄 이하를 권장하는 분위기이고,

• 실제로 HumanLayer 팀은 60줄도 안 되는 CLAUDE.md로 잘 쓰고 있습니다.

핵심은 "이 정보가 모든 유형의 작업에서 의미 있는가?"라는 질문입니다. 이 질문에 확신 있게 "그렇다"라고 답할 수 있는 내용만 남겨보세요.

Progressive Disclosure: 필요한 순간에만 더 깊은 설명을 보여주기

문제는, 프로젝트가 커질수록 "에이전트에게 알려주고 싶은 내용"이 기하급수적으로 늘어난다는 점입니다. 아키텍처, 서비스 간 통신 규칙, 테스트 전략, 배포 파이프라인… 다 중요해 보입니다.

이럴 때 쓸 수 있는 강력한 전략이 바로 Progressive Disclosure입니다. 간단히 말하면:

• CLAUDE.md에는 "어디서 무엇을 더 읽을 수 있는지"의 링크와 요약만 적고,

• 상세한 내용은 별도의 문서로 나누는 방식입니다.

예를 들어, 이런 구조를 생각해볼 수 있습니다.

• agent_docs/

  • building_the_project.md

  • running_tests.md

  • code_conventions.md

  • service_architecture.md

  • database_schema.md

  • service_communication_patterns.md

그리고 CLAUDE.md에는 이렇게만 적습니다.

• "빌드 방법은 agent_docs/building_the_project.md에 정리되어 있습니다."

• "테스트 실행 방법이 필요하면 running_tests.md를 먼저 읽어보세요."

• "서비스 간 통신 규칙은 service_communication_patterns.md에 있습니다."

여기에 한 줄 정도 지침을 추가할 수 있습니다.

• "작업을 시작하기 전에, 본인이 하려는 작업과 관련 있어 보이는 문서를 골라 먼저 읽어라."

• "혹은, 읽고 싶은 문서 목록을 사용자에게 먼저 제안하고 승인을 받으라."

또 하나 중요한 팁은 "코드 복붙 대신 참조를 쓰자"는 것입니다.

• 문서에 코드 스니펫을 길게 넣어두면 금방 오래되고,

• 컨텍스트 창도 불필요하게 차지합니다.

대신 "파일 경로 + 대략적 라인 번호"로 참조를 걸어두고, 에이전트가 실제 코드를 그때그때 열어 보도록 유도하는 것이 훨씬 좋습니다.

Claude를 린터로 쓰지 마세요: 도구는 도구에게

많은 팀이 CLAUDE.md에 "우리 코드 스타일 가이드"를 몽땅 넣고 싶어 합니다. 세미콜론 사용 여부부터 네이밍 규칙, import 순서까지 모두요.

하지만 이건 거의 최악의 사용법 중 하나입니다.

• LLM은 린터나 포매터보다 훨씬 느리고 비쌉니다.

• 스타일 가이드는 보통 지침이 매우 많고, 대부분의 작업에서 "핵심"도 아닙니다.

• 이걸 CLAUDE.md에 넣으면 지침 수만 늘어나고, 모든 작업에서 모델의 집중도만 떨어뜨립니다.

게다가, LLM은 "코드베이스에서 패턴을 학습하는" 능력이 상당히 좋습니다. 이미 코드가 일관된 스타일을 유지하고 있다면, 에이전트는 몇 개 파일만 읽어봐도 자연스럽게 그 스타일을 따라가는 경우가 많습니다.

만약 스타일을 정말 강하게 강제하고 싶다면, 다른 접근을 추천합니다.

• 자동 고침 기능이 있는 린터/포매터(Biome 등)를 세팅하고,

• Claude Code의 Stop Hook에서 린터를 돌려 에러만 다시 Claude에게 전달하게 하거나,

• 혹은 슬래시 커맨드로 "스타일 가이드 + 변경된 코드 목록"을 한 번에 보여주는 명령을 만들 수도 있습니다.

핵심은 이거 하나입니다. "포매팅이나 간단한 규칙 검사는, 사람이 만든 빠르고 결정론적인 도구에게 맡기자."

에이전트는 그 위에서 "설계, 구현, 리팩토링"에 집중할 때 가장 큰 가치를 냅니다.

/init 자동 생성은 왜 위험한가: CLAUDE.md는 레버리지 포인트다

요즘 많은 에이전트 도구들이 "CLAUDE.md 자동 생성하기" 같은 기능을 제공합니다. 레포를 훑어서 알아서 정리해 주니 참 편해 보입니다.

하지만 문제는, CLAUDE.md는 "편하게 대충 만들어도 되는 문서"가 아니라는 점입니다. 이 파일은:

• 매 세션, 매 작업에 빠짐없이 들어가며

• 기획·구현·리팩토링·디버깅 등 모든 단계에 영향을 줍니다.

나쁜 코드 한 줄은 나쁜 기능 하나를 만들 수 있습니다. 나쁜 설계 문서 한 줄은 나쁜 코드 수십 줄을 양산할 수 있습니다. 하지만 잘못된 CLAUDE.md 한 줄은, "모든 작업에 걸쳐 일관되게 나쁜 방향"을 강요할 수 있습니다.

그래서 이 파일은 오히려 "가장 사람 손이 많이 들어가야 하는 문서"에 가깝습니다.

• 자동 생성 결과를 그대로 쓰지 말고,

• 한 줄 한 줄 "이게 정말 항상 필요한 정보인가?"를 검토해 보세요.

• 팀에서 함께 리뷰하고, 실제 사용해 보며 계속 다듬는 것이 좋습니다.

조금 번거롭지만, 이 수고가 나중에 에이전트 생산성에서 몇 배로 돌아옵니다.

시사점: 좋은 CLAUDE.md를 위한 실전 체크리스트

마지막으로, 지금 당신의 CLAUDE.md를 점검할 수 있는 간단한 기준을 정리해 보겠습니다.

• 이 파일은 "에이전트를 우리 코드베이스에 온보딩하는 문서"인가?

• 프로젝트의 WHY(왜 하는지), WHAT(무엇으로 구성됐는지), HOW(어떻게 다루는지)가 명확하게 드러나는가?

• 거의 모든 작업에 공통으로 필요한 정보만 남겼는가?

• 지침은 최소한으로 줄이고, 예외적인 규칙은 다른 문서로 분리했는가?

• 스타일 가이드와 린트 규칙을 여기 넣어두고 있지는 않은가?

• 더 자세한 정보는 별도의 markdown 파일로 나누고, CLAUDE.md에는 "어디서 찾을지"만 적어두었는가?

• /init 등 자동 생성 결과를 그대로 쓰지 않고, 팀에서 충분히 검토했는가?

Claude와 같은 코드 에이전트는 "어떻게 컨텍스트를 설계하느냐"에 따라 완전히 다른 동료가 됩니다.

• 아무 정보도 모르는 신입처럼 만들 수도 있고,

• 팀의 역사와 설계 의도까지 이해하는 시니어 엔지니어처럼 만들 수도 있습니다.

그 차이를 만드는 첫 단추가 바로 CLAUDE.md입니다. 오늘 한 번 시간을 내서, 여러분의 CLAUDE.md를 "진짜 팀 동료에게 건네는 온보딩 문서"라고 생각하고 다시 써보세요.

에이전트의 답변이 달라지는 순간, 그 시간이 절대 아깝지 않았다고 느끼실 겁니다.

출처 및 참고 : Writing a good CLAUDE.md | HumanLayer Blog