Claude.md — AI 개발 파트너를 만드는 4가지 핵심 전략

왜 Claude.md인가

처음 Claude Code를 써봤을 때 솔직히 좀 당황했어요. 분명 뛰어난 AI인데, 매번 같은 설명을 반복해야 한다는 느낌이 들었거든요. 내 코딩 스타일, 쓰는 라이브러리, 폴더 구조 이런 것들을 대화가 바뀔 때마다 다시 알려줘야 했으니까요. Claude.md는 바로 그 문제를 해결해주는 파일이에요. 한 번 제대로 써두면 AI가 새 대화를 시작해도 맥락을 이미 파악한 상태로 일을 시작해요. 인수인계 문서를 잘 써두면 신입이 빨리 적응하는 것처럼요.

4가지 핵심 역할

Claude.md가 하는 일을 정리해보니 크게 네 가지 역할로 나뉘더라고요. 각각이 얼마나 중요한지, 실제로 써보면서 몸소 느낀 것들이에요.

특히 시행착오 일지 기능은 처음엔 별로 중요하게 생각하지 않았는데, 써보니까 정말 핵심이에요. 어떤 라이브러리 버전이 충돌했는지, 어떤 패턴이 오류를 냈는지 기록해두면 AI가 같은 실수를 다시 저지르지 않거든요. 기억력 없는 AI에게 기억을 심어주는 방법인 셈이에요.

전역과 지역의 이분법

Claude.md를 하나만 써야 한다고 생각하면 오해예요. 전역(Global)과 지역(Local), 두 레이어로 나눠서 관리하는 게 훨씬 효율적이에요.

블로그와 사이드 프로젝트를 동시에 진행해본 사람이라면 공감할 거예요. 프로젝트마다 쓰는 언어도, DB도, API도 달라요. 그걸 하나의 파일에 다 넣으면 AI가 헷갈리기 딱 좋죠. 전역은 '나라는 사람'을 정의하고, 지역은 '이 프로젝트'를 정의한다고 생각하면 돼요.

효율적 관리 원칙

200줄 제한은 처음에 너무 짧다고 느꼈는데, 실제로 지켜보니 이유가 있었어요. AI도 결국 컨텍스트가 길어지면 초반 지시를 잊어버리거든요. 핵심만 남기고 나머지는 rules 폴더로 보내는 습관을 들이면 훨씬 지시 준수율이 올라가요.

3단계 개선 프로세스

Claude.md를 처음 쓰고 나서 끝이 아니에요. 주기적으로 다듬어야 AI가 점점 더 잘 맞는 파트너가 돼요. 그 과정을 정리하면 세 단계예요.

마치며

결국 Claude.md는 AI의 성능을 결정짓는 기반 인프라예요. 아무리 좋은 AI 모델을 써도 맥락이 없으면 매번 제자리걸음이에요. 반면 잘 쓴 Claude.md 하나는 프로젝트 전체의 생산성을 완전히 다른 수준으로 끌어올려줘요. 직접 써보면서 가장 크게 느낀 건, 남의 템플릿을 가져다 쓰는 것보다 내 경험과 판단을 한 줄씩 직접 쌓아가는 게 훨씬 강력하다는 거예요. 지금 당장 파일 하나 만들어보세요. 생각보다 금방 달라집니다.