Claude Code를 사용하면서 다음과 같은 경험을 한 적이 없으신가요?

• "any 타입을 사용하지 마세요"라고 매번 쓰고 있는데도, 아무렇지 않게 any를 사용한다.
• "main에 직접 커밋하지 마세요"라고 말했는데, 어느샌가 main에 커밋되어 있다.
• 같은 실수를 몇 번이고 지적하며, 매번 똑같은 설명을 다시 하고 있다.
• CLAUDE.md가 작성되어 있음에도, 정작 중요한 순간에 규칙이 무시된다.

이것은 모델이 말을 듣지 않거나 똑똑하지 않아서가 아닙. 원인의 대부분은 "규칙의 작성 방식이 모호하기 때문"입니다.

어느 조사에 따르면, **구체적으로 작성된 규칙의 준수율은 89%, 모호한 규칙의 준수율은 35%**라는 차이가 나타납니다. 같은 CLAUDE.md라도 작성 방식 하나에 따라 말을 들을 확률이 2.5배 달라진다는 뜻입니다.

이 기사에서는 Claude Code가 실제로 규칙을 준수하게 만드는 CLAUDE.md 설계 방법을 Before/After 구체적인 예시와 함께 소개합니다. 모두 복사해서 오늘부터 바로 시도해 볼 수 있습니다.

먼저 전제를 바로잡겠습니다. 많은 사람이 CLAUDE.md를 "인간을 위한 README"처럼 작성하곤 합니다. 이것이 실수의 출발점입니다.

CLAUDE.md는 새로 합류한 팀 멤버(=AI)에게 전달하는 온보딩(Onboarding) 문서입니다. 읽는 대상이 인간이 아니라 Claude Code이므로, 다음과 같은 발상으로 작성해야 합니다.

• "눈치껏 알아차려 주길" 바라는 전제는 통하지 않는다.
• 추상적인 정신론("깔끔하게 작성하기")은 판단 기준이 될 수 없다.
• 구체적인 커맨드(Command), 경로(Path), 금지 사항을 명시해야 한다.

이 관점을 바꾸는 것만으로도 작성 내용이 크게 달라집니다.

Claude Code는 지시가 모호하면 자신에게 유리한(=최단 거리로 끝낼 수 있는) 해석을 선택합니다. 이는 악의가 아니라 판단 기준이 제시되지 않았기 때문입니다.

왼쪽은 모두 "옳은 말"을 하고 있지만, AI가 따랐는지 여부를 검증할 수 없습니다. 검증할 수 없는 규칙은 준수 여부를 확인할 방법이 없으므로 실질적으로 기능하지 않습니다.

핵심 포인트는 "그 규칙을 지켰는지/어겼는지를 제삼자가 기계적으로 판정할 수 있는가"입니다. 판정할 수 없다면 그것은 아직 규칙이 아닙니다.

무엇을 어떻게 써야 할지 고민된다면, CLAUDE.md를 3개의 블록으로 나눕니다.

# myapp CLAUDE.md
## WHAT (무엇을 만들고 있는가)
- 프로젝트: B2B용 청구 관리 SaaS
...

여기서 효과적인 테크닉이 두 가지 있습니다.

1. 버전 번호까지 작성하기

"React를 사용한다"가 아니라 "React 18.3"이라고 작성합니다. 버전을 적지 않으면 AI는 오래된 방식이나 너무 최신인 방식을 섞어서 사용하게 됩니다.

2. 강제 어휘 MUST / NEVER / ALWAYS 사용하기

영어의 강한 명령어를 사용하면 준수율이 올라갑니다. "사용하지 않았으면 좋겠다"보다 "MUST NOT use"가 AI에게 규칙의 강도를 더 명확하게 전달합니다.

CLAUDE.md는 단 하나만 존재하는 것이 아닙니다. 배치 장소에 따라 역할과 스코프(Scope)가 달라지며, 더 깊은 계층이 상위 설정을 덮어씁니다 (후순위 승리/Last-write-wins).

예를 들어 "API 구현 시에만 지켜줬으면 하는 규칙"을 전체 CLAUDE.md에 적으면, 관련 없는 프론트엔드 작업 시에도 토큰을 소비하며 노이즈가 됩니다. 대신 src/api/CLAUDE.md에 두면, **해당 하위 디렉토리를 다룰 때만 지연 로딩(Lazy Loading)**됩니다.

기밀 정보(운영 DB 경로 및 API 키 위치 등)는 CLAUDE.local.md에 작성하고 .gitignore에 등록합니다. 이렇게 하면 팀의 규칙과 개인의 메모가 섞이지 않으며, 실수로 커밋하는 사고도 방지할 수 있습니다.

"규칙은 많을수록 잘 지켜질 것"이라고 생각하기 쉽지만, 반대입니다. CLAUDE.md가 너무 길어지면 중요한 규칙이 묻혀서 스킵됩니다.

참고로, Claude Code 제작자인 Boris Cherny 씨의 CLAUDE.md는 약 100행, 2,500 토큰 정도라고 소개되었습니다. "전부 쓰는 것"이 아니라 "효과적인 것만 남기는 것"이 정답입니다.

내용이 길어지면 @imports를 사용하여 파일을 분할합니다.

# CLAUDE.md (루트)
@.claude/rules/git-conventions.md
@.claude/rules/security-rules.md
...

루트를 슬림하게 유지하면서, 규칙별로 파일을 나누어 다른 프로젝트에서도 재사용할 수 있습니다.

이 부분이 CLAUDE.md 운영의 가장 핵심적인 부분입니다.

PR 리뷰나 코드 리뷰에서 Claude Code의 실수를 발견했다면, 감정적으로 지적하는 대신 그 실수를 구체적인 규칙으로서 CLAUDE.md에 한 줄 추가하는 것만으로 충분합니다.

PR 리뷰에서 Claude의 실수 발견
↓
그 실수를 "구체적인 규칙"으로 `CLAUDE.md`에 추가
...

예를 들어 "날짜 처리 시 타임존(Timezone)을 고려하지 않는" 실수가 있었다면,

## 날짜 처리
- 날짜는 반드시(MUST) 모두 UTC로 저장할 것
- 표시할 때만 `formatInTimeZone`을 사용하여 로컬로 변환할 것 (src/utils/date.ts 사용)

라고 추가합니다. 이를 반복하면 CLAUDE.md는 **"이 프로젝트에서 두 번 다시 밟고 싶지 않은 지뢰 목록"**으로서 자동으로 성장해 나갑니다. 지적할 때마다 똑똑해지는 구조이므로, 운영할수록 지시를 내리기가 쉬워집니다.

CLAUDE.md는 "항상 적용되는 토대 규칙"이지만, 이것만으로는 닿지 않는 영역이 있습니다. 실무에서는 다음 세 가지와 조합하면 효과가 비약적으로 상승합니다.

1. 개별 태스크는 "애자일 티켓형(Agile Ticket Type)"으로 전달하기

CLAUDE.md에 쓰는 것은 보편적인 규칙입니다. 반면, 그때그때의 태스크는 Context / To-dos / Not-to-dos / Acceptance Criteria의 4개 블록으로 전달하면 스코프(Scope) 외의 변경을 막을 수 있습니다.

## Context
JWT 리프레시 토큰을 구현한다. src/auth/session.ts의 패턴을 따른다.
## To-dos
...

특히 효과적인 것이 Not-to-dos입니다. 이것이 없으면 AI는 스코프 외의 파일을 멋대로 "개선"해 버립니다.

2. 구현은 PIV (Plan → Implement → Verify) 루프로 진행하기

갑자기 구현하게 하지 말고, (1) 계획만 세우게 한 뒤 승인 → (2) 승인된 계획만 구현 → (3) 테스트로 검증, 과 같이 3단계로 나눕니다. "계획이 좋으면 코드도 좋다"이므로, 계획과 실행을 분리하는 것만으로도 오구현이 급격히 줄어듭니다.

3. 커밋은 "1태스크 = 1세이브 포인트"로 나누기

AI는 빠르고 광범위하게 코드를 변경하기 때문에, 한꺼번에 커밋하면 문제 발견 시 되돌리는 비용(Rollback Cost)이 치솟습니다. 태스크 완료 시마다 Conventional Commits 형식으로 즉시 커밋해 두면 언제든 안전하게 되돌릴 수 있습니다.

git add src/auth/jwt.ts tests/auth/jwt.test.ts
git commit -m "feat(auth): JWT 리프레시 토큰 로테이션 구현"

이 네 가지(CLAUDE.md 설계 / 애자일 프롬프트 / PIV 루프 / 커밋 전략)가 맞물리면, "프로급 Claude Code 개발 1주기"의 워크플로우가 완성됩니다.

CLAUDE.md

• CLAUDE.md를 "README가 아닌 AI를 위한 온보딩 문서"로 재정의한다. - 모호한 규칙을 "기계적으로 검증 가능한 구체적 규칙"으로 다시 작성한다 (MUST / NEVER 사용). - WHAT/WHY/HOW로 구조화하고, 200행 및 2,000토큰 이내로 유지한다.
• 모듈별 고유 규칙은 폴더별 CLAUDE.md로 분리한다. - 리뷰에서 발견된 실수를 매번 한 줄씩 추가하며 키워나간다 (Compound Engineering).

"Claude Code가 말을 듣지 않는다"고 느껴진다면, 프롬프트를 의심하기 전에 먼저 CLAUDE.md를 의심해 보세요. 대부분의 경우 모델의 문제가 아니라 설정의 문제입니다.

이 기사에서 다룬 CLAUDE.md 설계 / 애자일 티켓형 프롬프트 (Agile Ticket-style Prompt) / PIV 개발 루프 / AI 커밋 전략의 4가지를 그대로 자신의 프로젝트에 복사해서 사용할 수 있는 형태(절차, 프롬프트 예시, 안티 패턴 포함)로 GitHub에 무료 공개하고 있습니다. 라이선스는 CC BY 4.0이며, 상업적 이용 및 수정이 자유롭습니다.

git clone https://github.com/noguso245-jpg/claude-code-skills-starter
cp claude-code-skills-starter/skills/ja/claude-md-architecture.md your-project/.claude/skills/

4가지 요소는 각각 단독으로도 실용적이며, 조합하면 "계획 → 구현 → 검증 → 커밋 → CLAUDE.md를 통한 통제"라는 하나의 개발 루프가 완성됩니다.

도움이 되었다면 리포지토리에 ⭐를 남겨주세요. 새로운 무료 스킬을 추가하는 데 큰 힘이 됩니다. 기사에 대한 질문이나 "다음에는 이 주제를 깊게 다뤄달라"는 요청도 댓글로 환영합니다.