Claude가 따르는 CLAUDE.md

먼저, CLAUDE.md가 적합한 도구인지부터 물어보세요

규칙을 작성하기 전에, 그것이 CLAUDE.md에 속하는 것인지부터 물어보세요. 일부 규칙은 가이드이고, 일부 규칙은 절대 넘어서는 안 되는 엄격한 선입니다. 이 둘은 서로 다른 역할입니다.

"절대 main에 푸시하지 말 것"과 같은 규칙을 예로 들어보겠습니다. 이것을 CLAUDE.md에 넣으면, Claude가 이를 읽고 지켜주기를 바라는 것일 뿐입니다. 대부분의 경우에는 지켜질 것입니다. 하지만 그렇게 위험한 일에는 "대부분의 경우"로는 충분하지 않습니다. 이런 엄격한 규칙은 대신 pre-tool-use 훅에 속해야 합니다.

이 차이는 중요합니다. 훅은 Claude가 작업을 수행하기 전에 실행되는 코드이며, 실제로 그 작업을 막을 수 있습니다. 따라서 Claude가 main에 푸시를 시도하더라도, 훅이 이를 막습니다. 이것이 진짜 강제이며, 단순한 정중한 요청이 아닙니다. 엄격한 규칙은 훅으로 옮기고, CLAUDE.md는 더 부드러운 관례를 다루도록 하세요.

네 가지 위치

CLAUDE.md는 프로젝트에 놓인 단 하나의 파일이 아닙니다. 이 파일이 존재할 수 있는 네 곳이 있으며, Claude는 실행 시 이 모두를 함께 불러옵니다. 아무것도 빠지지 않으며, 서로 쌓입니다.

각각이 무엇을 위한 것인지 살펴보겠습니다:

• 관리형 정책(Managed policy) — 플랫폼 팀이 관리하는 조직 수준의 파일입니다. 이를 제외할 수 없으므로, 조직 정책은 항상 적용됩니다.
• 사용자(User) — 여러분의 머신에 있는 모든 프로젝트에 걸쳐 따라오는 개인 설정입니다.
• 프로젝트(Project) — 팀과 공유되며, 저장소에 체크인되는 파일입니다.
• 로컬(Local) — git에서 무시됩니다. 이 저장소 하나에만 해당하는 개인 메모입니다.

마지막의 로컬은 간과하기 쉽지만 정말 유용합니다. 예를 들어 자신의 브랜치에서 리팩터링을 하고 있고, 작업하는 동안 Claude가 몇 가지 아키텍처 결정을 염두에 두기를 원한다고 해봅시다. 이것은 팀 전체에 영향을 미치는 공유 프로젝트 파일에 속하지 않습니다. 이것은 로컬에 들어가며, 이 저장소에 대해서만 여러분만의 것이 됩니다.

import로 큰 파일 나누기

프로젝트 파일이 길어지기 시작하면, path-to-file import 구문을 사용해 여러 조각으로 나눌 수 있습니다. 하나의 거대한 텍스트 벽 대신, 다른 파일들을 가리키게 됩니다:

@.claude/conventions/code-style.md
@.claude/conventions/testing.md
@.claude/conventions/workflow.md

이것은 정리에 아주 좋습니다. 하지만 이것이 정확히 무엇을 해주는지 알아야 합니다. 잘못 이해하기 쉽기 때문입니다. Claude가 실행될 때, 참조한 바로 그 위치에서 import된 파일들을 인라인으로 확장합니다. 따라서 import는 정리를 도와주지만, 모든 것은 여전히 사전에 로드됩니다. Claude가 읽어야 하는 컨텍스트의 양을 줄여주지는 않습니다. import는 정리를 위해 사용하고, 부하를 줄이기 위해 사용하지 마세요.

규칙을 지키게 만드는 것은 표현 방식입니다

규칙이 CLAUDE.md에 속한다고 결정했다면, Claude가 실제로 이를 따를지는 어떻게 표현하느냐에 달려 있습니다. 대부분의 규칙은 모호하기 때문에 실패합니다. 이를 고치는 방법을 살펴보겠습니다.

구체적이고 확인 가능하게 작성하세요

"모범 사례를 따르세요"라고 쓰지 마세요. 그것이 정확히 무엇을 의미하는지 여러분 자신도 알고 있나요? 그것이 지켜졌는지 확인할 수 없다면, Claude도 확인할 수 없습니다. 다음 두 가지를 비교해 보세요:

• 모호함: "API 라우트에 대한 모범 사례를 따르세요."
• 구체적: "새 API 라우트는 src/api/handlers에 파일당 하나씩 넣으세요."

두 번째는 명확합니다. 결과를 보고 제대로 되었는지 즉시 알 수 있습니다. 그것이 모든 규칙이 넘어야 할 기준입니다.

대체안을 명시하세요, 단순히 금지만 하지 마세요

Claude에게 무언가를 하지 말라고 할 때는, 대신 무엇을 해야 하는지 말해주세요. 그렇지 않으면 문을 열어둔 것과 같습니다.

• 문을 열어둠: "default export를 사용하지 마세요." 좋습니다, 그런데 그다음은요?
• 문을 닫음: "default export가 아니라 named export를 사용하세요."

두 번째 버전은 대체안을 명시하므로, 잘못 해석할 여지가 남지 않습니다.

강조는 예산입니다

"IMPORTANT"나 "YOU MUST" 같은 단어는 규칙의 우선순위를 실제로 높여줍니다. 하지만 이는 주변의 더 조용한 것들에 비해서만 그렇습니다. 모든 규칙이 소리를 지르면, 아무것도 눈에 띄지 않고 강조는 아무 의미가 없어집니다. 그러니 강조를 예산처럼 다루세요. 어겼을 때 정말로 타격이 큰 두세 개의 규칙에만 이를 쓰고, 나머지는 평범한 수준으로 두세요.

파일을 계속 수정하세요

CLAUDE.md 파일은 절대 완성되지 않습니다. 계속 편집되는 살아있는 코드처럼 다루세요.

Claude가 잘못된 일을 했을 때, 그냥 한숨을 쉬고 직접 고치지 마세요. 이를 CLAUDE.md 파일에 대한 버그 리포트로 취급하세요. Claude에게 직접 "그것을 CLAUDE.md 파일에 추가해줘"라고 말할 수도 있으며, 그러면 Claude가 여러분을 위해 규칙을 작성해 줄 것입니다. 그렇게 하면 무언가 잘못될 때마다 파일이 더 나아집니다.

핵심 정리

CLAUDE.md를 프로덕션 코드처럼 다루세요. 어떤 줄을 정당화할 수 없다면, 삭제하세요. 파일을 간결하고 따르기 쉽게 유지하려면:

1. 엄격한 규칙은 훅으로 옮기세요. 그곳에서는 실제로 강제됩니다.
2. 긴 파일은 import로 정리하세요(단, 컨텍스트를 줄여주지는 않는다는 점을 기억하세요).
3. 모든 규칙을 구체적이고 확인 가능하게 만들고, 대체안을 명시하세요.
4. 강조 예산은 가장 중요한 몇 가지 규칙에만 쓰세요.
5. Claude가 무언가를 잘못할 때마다 파일을 계속 수정하세요.

전체 아이디어는 간단합니다. 파일이 간결할수록, Claude는 더 많은 부분을 따릅니다.