CLAUDE.md 제대로 쓰는 법 — 프로젝트 지도부터 시행착오 일지까지 네 가지 역할

핵심 메시지

• CLAUDE.md는 사람용 README에 대응하는 'AI용 인수인계 문서'로, 코딩 스타일 설정 파일 정도로만 쓰면 절반도 활용하지 못한다.
• 이 파일은 프로젝트 지도, 나만의 규칙서, 능력의 경계선, 시행착오 일지라는 네 역할을 동시에 맡는다.
• 전역 파일에는 나에 대한 원칙을, 프로젝트별 지역 파일에는 그 프로젝트의 구조와 맥락을 나눠 담아야 규칙이 서로 섞이지 않는다.
• 파일이 길어질수록 지시사항 준수율이 떨어지므로 200줄 이내로 유지하고, 규칙은 폴더·주제별로 나눠 필요한 때만 읽히게 하는 편이 좋다.
• 남의 템플릿을 복사하는 것보다, 내 워크플로와 시행착오가 녹아든 개인화된 파일이 실제 생산성을 만든다.

쉽게 이해하기

영상은 도발적인 전제로 시작한다. Claude Code가 월 100~200달러짜리 자동완성기로 남느냐, 진짜 개발 파트너가 되느냐를 CLAUDE.md 한 파일이 가른다는 것이다. 발표자는 이 파일을 새 직장의 인수인계 문서에 비유한다. 아무리 경력이 좋아도 코드 구조와 빌드 방법, 팀의 컨벤션을 모르면 첫 주에 성과를 낼 수 없듯, AI도 프로젝트 안내서가 없으면 매번 맨바닥에서 시작한다는 것이다.

첫 번째 역할은 프로젝트의 지도다. 폴더가 수십 개인 프로젝트에서 '자막 스타일을 바꿔달라'고 요청하면, 안내서가 없는 AI는 폴더를 하나씩 열어보며 관련 파일을 찾아야 한다. 구조를 압축해 적어두면 탐색 없이 곧장 해당 위치로 향할 수 있고, 이것이 토큰 절약과 속도로 직결된다. 두 번째 역할은 나만의 규칙서다. 선호하는 언어와 라이브러리, 에러 메시지 언어 같은 개인 취향뿐 아니라 '결과는 이런 포맷으로 정리하라' 같은 소통 방식까지 적어두면, 매 세션 백지에서 시작하는 AI에게 같은 말을 반복할 필요가 없어진다.

세 번째 역할은 능력의 경계선이다. 프로젝트 안에 이미 필요한 스크립트나 API 연동이 있는데도 AI가 '그 기능은 없다'고 답하는 일이 자주 생기는데, 이는 자기가 무엇을 할 수 있는지 모르기 때문이다. 호출 가능한 API, 접근 가능한 데이터베이스, 실행 가능한 스크립트를 명시해두면 이런 헛돎이 사라진다. 발표자는 외부 API를 쓰는 프로젝트라면 공식 문서를 프로젝트 폴더 안에 통째로 넣어두고, 외부 검색 전에 그곳을 먼저 보라고 한 줄 적어두라고 권한다.

네 번째이자 가장 과소평가된 역할은 시행착오 일지다. 어떤 라이브러리 버전이 호환되지 않는지, 어떤 방식으로 API를 호출하면 타임아웃이 나는지 같은 교훈을 기록해두면, AI가 시도할 수 있는 선택지 중 이미 실패한 방향을 미리 잘라낼 수 있다. 같은 삽질을 두 번 하지 않게 되는 셈이다. 이 네 가지를 어디에 적을지에 대해서는 층을 나눌 것을 제안한다. 전역 파일에는 프로그래밍 스타일과 커뮤니케이션 선호 같은 '나에 대한 정보'를, 프로젝트 폴더 안의 지역 파일에는 폴더 구조와 기술 스택, 그 프로젝트에서 겪은 시행착오를 담는 식이다.

다만 내용을 계속 더하면 파일이 길어지고, 길어질수록 중간의 지시사항을 건너뛸 확률이 올라간다. 발표자는 앤트로픽이 최근 웨비나에서 공개한 가이드를 인용해 200줄 이내 유지와 규칙 파일 분리를 원칙으로 제시한다. rules 폴더에 주제별로 규칙을 나눠두고 각 파일 상단에 적용 범위를 조건으로 붙이면, 특정 폴더를 작업할 때만 해당 규칙이 읽힌다. 프로젝트가 커지면 상위 폴더의 전체 규칙과 하위 폴더의 전용 규칙을 계층으로 배치할 수도 있다. 마지막으로 소개하는 개선 방법은 세 단계다. 추론 깊이를 최대로 올린 상태에서 현재 CLAUDE.md를 진단시키고, 결과가 나오면 곧바로 실행하지 말고 계획 모드로 전환해 실행 계획을 먼저 뽑은 뒤, 납득이 갈 때 실행하는 것이다.

주요 인사이트

• AI가 '그 기능은 못 한다'고 답할 때, 실제 원인이 능력 부족이 아니라 자기 권한과 도구를 모르기 때문인 경우가 많다. 능력 선언을 문서로 명시하는 것만으로 해결되는 문제다.
• 규칙 파일을 주제별로 나누고 적용 조건을 붙이는 방식은, 필요한 시점에 필요한 것만 로드하는 점진적 공개 원리를 설정 파일 층위에서 구현한 것이다.
• 문서가 길수록 좋아 보이지만 실제로는 지시 준수율이 떨어진다. 분량 제한이 성능 최적화 수단이 되는 흔치 않은 사례다.
• 진단 결과를 바로 실행시키지 않고 계획 모드를 한 단계 끼워 넣는 습관은, 잘 작동하던 부분까지 AI가 건드리는 사고를 막는 안전장치다.
• 초기 세팅에 들인 한 시간이 매 작업마다 반복 설명과 시행착오를 줄여준다는 점에서, 이 문서 관리는 복리로 돌아오는 투자에 가깝다.

자주 묻는 질문

관련 AI 소식