CLAUDE.md는 세션마다 전체 내용이 Claude에게 읽힙니다. 작성한 만큼 컨텍스트 (Context)를 소비하며, 양이 많아질수록 중요한 규칙이 묻혀 지켜지지 않게 됩니다. "상세하게 적을수록 좋다"는 성립하지 않습니다.

그래서 필요해지는 것이 "작성할 것인가, 작성하지 않을 것인가"의 판단 기준입니다.

최근에 비대해진 규칙 파일을 정리했으므로, 작성할 때 주의할 점을 공식 문서(Official Document)를 바탕으로 정리합니다.

공식 베스트 프랙티스 (Best Practice)가 제시하는 판단 기준은, "이것을 삭제하면 Claude가 실수를 저지르는가"를 한 줄씩 묻는 것입니다. 실수하지 않는다면 삭제합니다.

즉, 삭제해도 Claude가 실수하지 않는 규칙은 작성할 의미가 없다는 뜻입니다. 남길 가치가 있는 것은 Claude가 추측할 수 없는 것뿐입니다.

예를 들어 "배열 변환에는 map을 사용한다"는 작성할 가치가 없지만, "날짜 처리는 반드시 자체 제작한 DateUtil을 통한다"는 작성할 가치가 있습니다.

이 질문은 검토할 때뿐만 아니라 작성할 때도 사용할 수 있습니다. "이것을 적지 않으면 Claude가 실수할까"라고 뒤집어서 질문하면, 작성하기 전에 불필요한 규칙을 알아차릴 수 있습니다.

삭제해도 Claude가 실수하지 않는 규칙에는 다음과 같은 것들이 있습니다.

라이브러리의 기본적인 사용법이나 언어의 표준적인 문법·구문의 설명입니다. Claude가 처음부터 알고 있는 것은 삭제해도 생성되는 코드가 변하지 않습니다.

동일한 규칙이 여러 규약 문서에 적혀 있으면, 언젠가 한쪽만 업데이트되어 서로 어긋나게 됩니다. 남길 경우에도 그대로 베껴 쓰는 것이 아니라 "상세 내용은 ◯◯를 참조"와 같이 한 줄로 작성합니다.

방침을 변경했을 때 오래된 기술을 삭제하는 것을 잊으면, 동일한 파일 내에서 지시 사항이 서로 충돌합니다.

공식 문서는 "두 규칙이 서로 모순되는 경우, Claude는 하나를 임의로 선택할 가능성이 있습니다"라고 경고하며, CLAUDE.md나 rules를 정기적으로 확인하여 오래된 지시나 모순되는 지시를 삭제할 것을 권장하고 있습니다.

작성할 가치가 있는 것은 코드나 일반 지식으로부터 추측할 수 없는 것입니다. 공식 베스트 프랙티스는 CLAUDE.md에 포함할 내용으로 다음을 꼽고 있습니다.

• Claude가 추측할 수 없는 Bash 커맨드 (Command)
• 기본값과 다른 코드 스타일 규칙
• 테스트 지시 사항 및 사용하는 테스트 러너 (Test Runner)
• 리포지토리 (Repository) 운영 규칙 (브랜치 명명, PR 규약)
• 프로젝트 고유의 아키텍처 (Architecture) 상의 결정 사항
• 개발 환경의 특성 (필수 환경 변수 등)
• 자주 발생하는 함정이나 자명하지 않은 동작

CLAUDE.md는 AI에게 읽히는 주석이며, 가치의 판단 기준은 인간을 위한 코드 주석과 동일한 "추측할 수 없는 것만 적는다"입니다.

작성하기로 결정한 규칙에는 다음의 선택지가 있습니다. 바로 어디에 적을 것인가입니다. 위치에 따라 읽히는 방식이 달라지기 때문에 이 또한 컨텍스트 소비와 관련이 있습니다.

대표적인 위치는 .claude/rules/입니다.

이는 지시 사항을 토픽별로 여러 파일로 나누어 유지보수하기 쉽게 정리하기 위한 공식 메커니즘이며, 작성할 것과 작성하지 않을 것은 CLAUDE.md와 동일한 기준으로 생각할 수 있습니다.

규칙이 읽히는 방식에는 두 가지 종류가 있습니다.

• 매번 읽기: 프로젝트 루트의 CLAUDE.md와 paths 지정이 없는 .claude/rules/*.md. 실행 시 전체 내용이 읽힙니다. 공식적으로는 CLAUDE.md에 대해 200행 이하를 권장합니다.
• 조건부 읽기: 파일 서두의 ---로 둘러싸인 메타데이터 영역 (frontmatter)에 paths:를 작성한 rules. 매칭되는 파일을 다룰 때 읽힙니다. 서브 디렉토리에 둔 CLAUDE.md도 해당 디렉토리의 파일을 다룰 때 읽힙니다. --- paths: - '**/*.test.ts' ---

조건부 읽기라고 해서 컨텍스트 소비가 없어지는 것은 아닙니다. 대상 파일을 다룰 때는 파일 전체가 읽힙니다. 테스트 규약이라면 테스트를 건드리는 시점에 통째로 읽힙니다. 어떤 방식으로 읽히든 컨텍스트 소비는 작성한 양에 비례합니다.

분할을 통해 읽기 양이 줄어드는 것은 읽히는 타이밍이 분리될 때뿐입니다. 동일한 paths: '**/*.test.ts'를 가진 3개의 파일로 나누더라도, 테스트를 편집하는 순간에는 3개 모두 동시에 읽히므로 총 행수는 1개의 파일일 때와 같습니다. @path 임포트 (Import)로 다른 파일로 나누었을 경우에도, 임포트 대상은 실행 시점에 읽히기 때문에 컨텍스트는 줄어들지 않습니다.

공식 문서의 rules에서 제시하는 분류 단위는 행수가 아니라 '1파일 1토픽'입니다. testing.md나 api-design.md와 같이, 하나의 파일에는 하나의 주제에 대한 규약(convention)만 넣고, 파일 이름만 봐도 어떤 규약인지 알 수 있도록 합니다. 조건부 로딩 (conditional loading)을 적용한 후, 남은 내용이 하나의 주제에 수렴한다면 행수를 이유로 분할할 필요는 없습니다.

행수가 신경 쓰일 때의 순서는 먼저 내용을 덜어내고, 그래도 스코프 (scope)가 나뉜다면 분할하는 것입니다. 반대로 하면 중복되거나 일반적인 지식이 여러 파일에 흩어져서 수정하기 어려워집니다.

실제로 스코프가 나뉘는 경우에는 두 가지 배치 방법이 있습니다. 차이점은 규약 파일을 두는 위치입니다. 규약을 코드 근처에 두고 함께 관리하려면 각 디렉토리의 CLAUDE.md를 사용하고, 규약을 한곳에 모으고 싶거나 떨어진 여러 경로에 동일한 규칙을 적용하고 싶다면 paths를 지정한 rules가 적합합니다.

여러 단계의 절차나 가끔 사용하는 도메인 지식 (domain knowledge)은 규칙 (rules)이 아니라 skills에 두는 것이 공식 권장 사항입니다.

skills에서 기동 시에 읽히는 것은 이름과 설명뿐이며, 본문은 요청과 관련이 있다고 Claude가 판단했을 때나 이름으로 호출되었을 때 읽힙니다. 파일 경로로 조건부 로딩 조건이 결정되는 rules와 달리, skills는 무엇을 요청받았느냐에 따라 결정됩니다.

• 그것은 Claude가 모르는 내용인가 (일반 지식이라면 쓰지 않음)

• 이미 다른 문서나 헬퍼 (helper)에 없는가 (있다면 참조 한 줄로 처리)

• 그것은 규칙인가, 절차인가 (여러 단계의 절차나 도메인 지식이라면 skills로)

• 항상 필요한가, 특정 파일을 다룰 때만 필요한가 (후자라면 paths가 포함된 rules로)

• 삭제했을 때 Claude가 실수하는가 (실수하지 않는다면 삭제)

• 같은 주제가 두 곳에 작성되어 있지 않은가 (한쪽만 업데이트되어 내용이 어긋날 수 있음)

• 분할한다면, 읽히는 타이밍이 나뉘는가 (나뉘지 않는다면 내용을 덜어내는 것이 우선)