CLAUDE.md 가 뭔가
Claude Code 가 매 대화에 자동으로 실어 보내는 규칙 파일이다. 여기 적어두면 매번 말하지
않아도 지켜진다.
전역(~/.claude/CLAUDE.md) 하나가 있고, 프로젝트마다 따로 둘 수도 있다. 계층 구조는
다른 글에서 다뤘고, 여기서는
전역 파일에 실제로 무엇을 썼는지만 본다.
지금 182줄에 절이 14개다. 처음부터 이랬던 건 아니다. 2026년 4월 24일에 시작해서 4개월간
하나씩 붙은 것이고, 대부분은 “또 이러네” 를 겪고 나서 추가됐다.
절 14개
| 절 | 한 줄 요지 |
|---|---|
| 기본 행동 규칙 | 요청하지 않은 개선을 하지 않는다 |
| 설명 방식 | 결론 3줄이 먼저다 |
| 팀 공유 설정 파일은 직접 고치지 않는다 | 남의 합의는 임의로 안 바꾼다 |
| 마크다운 작성 규칙 | 표의 모든 행을 \| 로 감싼다 |
| 코딩 전 사고 | 가정을 명시하고, 애매하면 묻는다 |
| 질문/대기 상태 명시 규칙 | 답이 필요하면 도구를 쓴다 |
| 단순성 우선 | 문제를 푸는 최소한만 |
| 최소 수술적 변경 | 건드려야 할 것만 |
| 목표 중심 실행 | 검증 가능한 목표로 바꾼다 |
| 브라우저 자동화 | 어느 도구를 먼저 쓸지 |
| 아티팩트 다이어그램 | Mermaid 가 기본, SVG 는 예외 |
| 프로파일별 규칙 | 머신별 파일을 불러온다 |
| OMC 자동 실행 | 조건 충족 시 자동으로 켠다 |
| 플러그인 조합 라우팅 | 셋이 겹칠 때 뭘 쓸지 |
성격이 크게 셋이다. 행동 제약(뭘 하지 마라), 출력 형식(어떻게 말해라), 도구
라우팅(뭘 언제 써라).
가장 자주 작동하는 규칙 셋
1. 요청한 것만 한다
변경된 모든 줄이 사용자 요청으로 직접 추적 가능해야 한다
— 리팩터링·개선·추가 기능은 명시적 요청이 있을 때만 한다
이게 첫 줄에 있는 이유가 있다. AI 는 시키지 않은 것까지 “김에” 고치는 성향이 강하다.
인접 코드를 정리하고, 주석을 다듬고, 안 쓰는 import 를 지운다. 각각은 선의인데 합치면
diff 가 커져서 리뷰가 불가능해진다.
같은 취지가 「최소 수술적 변경」 절에 더 구체적으로 있다.
- 인접 코드, 주석, 포맷을 "개선"하지 않는다
- 안 부러진 것을 리팩터링하지 않는다
- 관련 없는 dead code 를 발견하면 — 언급만 하고 삭제하지 않는다
마지막 줄이 절충안이다. 발견은 알려주되 손대지는 않는다.
2. 결론을 먼저 쓴다
결론 3줄이 먼저다. 첫 3줄만 읽어도 답이 나와야 한다.
근거·과정은 그 뒤에 붙인다.
이 절은 판정 가능한 기준으로 여러 번 고쳐졌다. 처음엔 “쉽게 설명해라” 였는데 그건 지켜졌는지
확인할 수가 없다. 그래서 세는 규칙으로 바꿨다.
- 근거 표는 5행 이내. 넘으면 대표 사례만 남기고 "나머지 N개도 동일" 로 줄인다
- 표는 긴 설명을 대체할 때만 쓴다 — 설명을 다 쓰고 표를 덧붙이면 짧아지지 않는다
- 처음 쓰는 전문용어는 괄호로 한 번 푼다
“5행 이내” 는 셀 수 있다. “쉽게” 는 못 센다.
3. 답이 필요하면 도구를 쓴다
이건 UX 문제를 푼 규칙이라 이유가 길게 적혀 있다.
사용자의 답이 필요하면 반드시 AskUserQuestion 도구를 쓴다.
텍스트로 묻고 턴을 끝내지 않는다.
텍스트 질문은 강제력이 없어 사용자가 대기 상태인지 알 수 없다.
도구는 시스템이 턴을 붙잡아 need input 이 뜨므로 구분이 확실하다.
AI 가 산문 끝에 “~할까요?” 를 붙이고 턴을 끝내면, 화면상으로는 작업이 끝난 것처럼 보인다.
자리를 비웠다 돌아오면 진행 중인지 대기 중인지 알 수 없다.
그래서 반대 케이스까지 규정했다 — 답이 필요 없는 경우에는 마지막 줄에
▶️ 답변 없이 계속 진행합니다. 를 붙이게 했다. 두 상태를 눈으로 구분하려는 것이다.
규칙은 사건 뒤에 붙는다
커밋 이력을 보면 대부분의 절이 무슨 일을 겪고 나서 생겼다.
| 시기 | 추가된 것 |
|---|---|
| 2026-06-23 | OMC 자동 제안 규칙 (난이도 높을 때만) |
| 2026-07-07 | 플러그인 3종 조합 라우팅 |
| 2026-07-28 | OMC 자동 실행 문턱 상향 + 배제 목록 |
| 2026-07-29 | 팀 공유 설정 파일 보호 원칙 |
| 2026-07-29 | 질문/대기 상태 명시 규칙 |
| 2026-07-30 | 답변을 쉽게 풀어쓰는 규칙 |
7월 28일 커밋이 대표적이다. 원문에 이유가 그대로 있다.
파일 3개 기준이 낮아 조사·설정 수정 같은 작업에도 ralph/ultrawork 가
자동으로 떠 opus 에이전트 토큰을 소비했다.
규칙을 만들었더니 그 규칙이 과하게 작동한 것이고, 그래서 문턱을 3 → 5 로 올리고
배제 목록을 신설했다. 이 이야기는 다음 글에서 따로 다룬다.
안 쓴 것도 규칙이다
넣었다가 뺀 것들이 있다.
-
다이어그램 실측 함정 — 상세 내용을 스킬로 옮겼다. 다이어그램을 그릴 때만 필요한데
매 대화에 실리고 있었다 - 브라우저 도구 호출 순서 — 같은 이유로 스킬로 분리 (전역 183 → 157줄)
- 환경변수 관리 — 개인 머신에만 해당해서 프로파일 파일로 이동
기준은 하나다. 모든 대화에 실릴 값어치가 있는가. 없으면 스킬이나 프로파일로 내린다.
그 판단 근거는 상시 로드 비용 쪽에
정리해뒀다.
정리
- 전역 CLAUDE.md 182줄, 절 14개
- 성격은 셋 — 행동 제약 / 출력 형식 / 도구 라우팅
- 대부분 사건을 겪은 뒤에 붙었고, 커밋 메시지에 그 이유가 남아 있다
- 판정 가능한 문장으로 쓴다. “쉽게” 대신 “표는 5행 이내”
- 매 대화에 실릴 값어치가 없으면 스킬·프로파일로 내린다
다음 글에서는 이 파일을 맥 4대에 어떻게 배포하고 관리하는지를 다룬다.