장기 프로젝트를 위한 CLAUDE.md 구조화 방법

대부분의 CLAUDE.md 파일은 Claude의 행동을 실제로 제약하지 못하기 때문에 실패합니다. 프로젝트의 방향이 바뀌는 순간 너무 취약해지고 쓸모없게 변해버립니다. CLAUDE.md를 단순한 정보 나열(brain dump)로 취급하지 마세요. 이를 운영 계약(operating contract)으로 취급해야 합니다.

다음은 몇 달 동안 유지될 수 있는 4개 섹션 구조입니다.

대부분의 CLAUDE.md 파일이 실패하는 이유

요약하자면 다음과 같습니다:

프로젝트: 재고 관리를 위한 Next.js 앱. TypeScript 사용. Tailwind 선호. 클래스 컴포넌트(class components) 사용 금지.

이것은 시작 단계의 가이드일 뿐, 운영 계약이 아닙니다. Claude는 이 프로젝트에서 성공이 무엇을 의미하는지, 어떤 결정이 이미 내려졌는지, 무엇을 제안하지 말아야 하는지 알지 못합니다. 첫 번째 세션은 괜찮을지 모르지만, 다섯 번째 세션에 이르러 Claude가 "그것이 현대적인 Next.js 패턴입니다"라며 라우팅 레이어(routing layer)를 리팩터링(refactoring)하자고 제안할 때, 이를 하지 말라고 지시하는 내용이 파일에 아무것도 없게 됩니다.

너무 취약한 버전(too-brittle version) 또한 또 다른 문제입니다:

users 테이블은 user_id를 통해 profiles와 조인(join)됩니다. 프론트엔드(frontend)로 보내기 전에 항상 UUID를 문자열로 캐스팅(cast)하세요. /api/webhooks/stripe.ts의 Stripe 웹훅(webhook) 핸들러는 raw body가 필요합니다. /lib/auth/middleware.ts를 수정하지 마세요. pages/dashboard/[id]/edit.tsx 파일에는 ...와 관련된 알려진 레이스 컨디션(race condition)이 있습니다.

이것은 모든 사실을 하나의 파일에 억지로 끼워 넣은 것입니다. 이러한 사실 중 하나라도 바뀌는 순간(스키마 마이그레이션(schema migration), 웹훅 리팩터링, 새로운 인증 패턴 등), 이 파일은 틀린 정보가 됩니다.

해결책은 CLAUDE.md를 위키(wiki)가 아닌 계약(contract)으로 생각하는 것입니다. 계약에는 섹션이 있으며, 각 섹션은 서로 다른 질문에 답합니다.

모든 CLAUDE.md에 필요한 4개 섹션

섹션 1: 상시 운영 지침 (Standing operating instructions)

이것은 작업 내용과 관계없이 Claude가 항상 수행하기를 원하는 사항입니다. 거의 변경될 일이 없는 부분입니다.

여기에 들어갈 내용:

행동 패턴 (Behavior patterns). "허둥대지 마세요. 세 가지 접근 방식이 효과가 없다면, 멈추고 원래 요청의 무엇이 잘못되었는지 물어보세요."

재사용 기대치 (Reuse expectations). "새로운 추상화 (abstraction)를 작성하기 전에 코드베이스에서 기존 사례 (prior art)를 검색하세요."

작동 중인 코드 보호 (Working-code protection). "명시적인 요청 없이 작동 중인 코드를 덮어쓰지 마세요. '나는 다르게 작성했을 것이다'라는 생각은 기준이 될 수 없습니다."

커뮤니케이션 선호도 (Communication preference). "여러 가지 유효한 접근 방식이 있을 때는, 그것들의 이름을 나열하고 제가 선택하게 하세요. 임의로 선택하지 마세요."

이 섹션은 프로젝트 내에서 Claude의 인격(personality)에 가장 가까운 요소입니다. 한 번 잘 작성해 두면, 시작하는 모든 프로젝트에 동일한 규칙을 이식하게 될 것입니다. 그것이 목표입니다. 이 섹션은 대부분 프로젝트에 구애받지 않으므로(project-agnostic), 작성 노력이 복리로 쌓이게 됩니다.

섹션 2: 프로젝트 컨텍스트 (Project context)

이것은 이 프로젝트가 실제로 무엇인지, 왜 존재하는지, 그리고 성공이란 어떤 모습인지를 나타냅니다.

여기에 들어갈 내용:

한 줄 프로젝트 설명.

기술 스택 (The stack). 언어, 프레임워크, 데이터베이스, 배포 대상.

프로젝트의 라이프사이클 단계 (출시 전, 운영 중, 성숙기).

확정된 결정 사항 (The locked decisions). 이미 내려졌으며 재평가해서는 안 되는 아키텍처 선택 사항. ("우리는 MongoDB가 아닌 Postgres를 사용합니다. 10월에 결정되었습니다. 다시 제안하지 마세요.").

'확정된 결정 사항 (The Locked Decisions)' 하위 섹션은 이 섹션에서 가장 영향력이 큰 부분입니다. 대부분의 세션 이탈 (session drift)은 Claude가 이미 결정된 사항에 대해 다른 접근 방식을 제안할 때 발생합니다. 결정된 이유와 함께 한 번 문서화해 두면, 이후의 세션에서 발생하는 이탈을 방지하는 데 도움이 됩니다.

이 섹션을 읽는 사람이 아무런 사전 정보 없이도 60초 이내에 프로젝트가 무엇인지 이해할 수 있도록 작성하세요. 만약 이해하지 못한다면, 해당 섹션은 너무 모호한 것입니다.

섹션 3: 관례 및 제약 사항 (Conventions and constraints)

이것은 부정적인 공간 (negative space)입니다. 하지 말아야 할 것, 피해야 할 패턴, 이미 시도했다가 거부된 것들에 대한 내용입니다.

여기에 들어갈 내용:

하지 말아야 할 것 (Don't lists). "요청이 없는 한 테스트 파일을 생성하지 마세요. 명시적인 요청 없이 파괴적인 명령(drop, delete, force push)을 실행하지 마세요."

사용 중인 스택에 특화된 안티 패턴 (Anti-patterns). "대화형 UI에 서버 컴포넌트 (Server Components)를 제안하지 마세요. 이 프로젝트는 대시보드에 클라이언트 컴포넌트 (Client Components)를 사용하기로 결정했습니다."

잘못되어 보일 수 있지만 의도된 사항들. "인증 미들웨어 (Auth middleware)는 세션이 누락되어도 조기에 반환하지 않습니다. 이는 의도된 사항이며, 파일 내 주석을 참조하세요."

이 내용을 섹션 1과 분리하는 이유는 제약 사항 (Constraints)이 변하기 때문입니다. 상시 운영 지침 (Standing operating instructions)은 대부분 변하지 않는 영구적인 성격을 띠지만, 제약 사항은 프로젝트가 성숙해지고 팀이 어떤 패턴이 자신들에게 맞지 않는지 학습함에 따라 계속 쌓여갑니다.

이 섹션은 도구의 노이즈 (Tool noise)를 기록하는 곳이기도 합니다. 매 세션마다 발생하여 시간을 낭비하게 만드는 요소들 말입니다.

"개발 서버 (Dev server)가 핫 리로드 (Hot reload) 시 하이드레이션 경고 (Hydration warnings)를 발생시킵니다. 지속적이지 않다면 무시하세요." 이를 한 번 기록해 두면 매 세션마다 같은 설명을 반복할 필요가 없습니다.

섹션 4: 교훈 (Lessons)

이 섹션은 대부분의 사람들이 건너뛰는 부분입니다. 하지만 가장 중요한 부분입니다.

여기에 들어갈 내용은 Claude가 시간이 흐르며 학습한 내용의 지속적인 로그입니다. 각 항목은 짧게 작성합니다:

교훈 (LESSON): 한 가지 접근 방식이 막혔을 때, 임시방편 (Workarounds)을 제안하기보다 즉시 전체 툴킷 (Toolkit)을 고려하세요.

실수 (THE MISTAKE): bash에서 네트워크 제한에 걸렸을 때, 계속해서 Python 대안을 제안함 (동일한 제한 사항 발생), 수동 다운로드 임시방편을 반복해서 제안함. 사용자가 이의를 제기한 후에야 브라우저 도구 (Browser tool)를 사용함.

해결책 (THE FIX): 막혔을 때는 자신의 역량을 먼저 조사하세요. 파일 다운로드 → 브라우저 도구 사용이 직접적인 해결책입니다. 자동화할 수 있는 도구가 있을 때는 수동 임시방편을 제안하지 마세요.

적용 대상 (APPLIED TO): SEC 공시 파일 다운로드, URL로부터의 모든 파일 관련 작업.

이 형식은 세 가지 역할을 합니다. 실패 모드 (Failure mode)의 이름을 명시하여 식별 가능하게 합니다. 해결책을 구체적으로 기록합니다. 그리고 적용 범위를 태그하여 해당 교훈이 언제 적용되는지 명확하게 합니다.

핵심적인 원칙은 덮어쓰는 것이 아니라 덧붙이는 것입니다. 이해도가 진화할 때는 다음과 같이 날짜와 함께 인라인 수정 사항 (inline correction)을 추가합니다.

CORRECTION (2026-05-21): "완전 자동화, 수동 단계 제로"라는 주장은 스케줄된 작업 샌드박스 (scheduled-task sandbox) 환경에서는 유효하지 않습니다. 호스트가 허용 목록 (allowlist)에 포함되어 있지 않습니다. 호스트가 허용 목록에 추가되거나 브라우저가 연결된 상태로 작업이 실행될 때까지 파이프라인이 차단됩니다.

두 달 후, 상황이 다시 변했을 때:

RESOLVED for LOCAL runs (2026-06-05): 스크립트가 일반적인 로컬 프로세스로 실행될 때 호스트에 접근할 수 있습니다. 차단 문제는 스케줄된 작업 샌드박스에서만 발생했습니다. 이제 스크립트에 로컬 실행을 위한 --auto 모드가 추가되었습니다.

원래의 교훈 (lesson) 위에 날짜가 기입된 두 개의 수정 사항을 쌓음으로써 이해가 어떻게 진화했는지 보여줍니다. 원래의 교훈을 덮어쓰지 마세요. 해결책을 LESSON 텍스트 안에 억지로 끼워 넣으려 하지 마세요. 이 기록의 사슬 (chain) 자체가 가치입니다.

이 섹션은 Claude 작업의 조직적 기억 (institutional memory) 역할을 합니다. 이것이 없다면 모든 새로운 세션은 아무런 정보 없이 차갑게 시작됩니다. 이것이 있다면, Claude가 구조적 섹션들을 읽은 후 가장 먼저 읽게 되는 내용은 "내가 알아야 할 것 중 우리가 무엇을 배웠는가"가 됩니다.

프로젝트 유형에 따른 차이점

4개 섹션 구조는 보편적입니다. 다만 각 섹션에 들어가는 내용은 달라집니다.

**코드 중심 프로젝트 (Code-heavy projects)**는 섹션 3에 크게 의존합니다. 수많은 제약 사항, 안티 패턴 (anti-patterns), 프레임워크 특유의 주의 사항 (gotchas) 등이 포함됩니다. 교훈 (lessons) 섹션에는 디버깅 과정에서 발견한 내용들을 기록합니다.

글쓰기 중심 프로젝트 (Writing-heavy projects) (연구 저장소, 지식 베이스)는 섹션 1이 편집 규율 (editorial discipline) 쪽으로 치우칩니다. 쓰기 전 읽기 (Read-before-write), 추가 전용 (append-only), 프레이밍 잠금 (framing locks), 출처 계층 구조 (source hierarchy) 등이 해당됩니다. 섹션 3은 "meta/ 디렉토리 외부에서는 1인칭 언어 사용 금지" 또는 "핸들(handle)이 아닌 정식 엔티티 이름(canonical entity names) 사용"과 같은 내용을 다룹니다.

파이프라인 프로젝트 (Pipeline projects) (데이터 스크래퍼, 자동화된 워크플로)는 섹션 4에 크게 의존합니다. 교훈 섹션은 날짜 기반 수정 형식이 그 진가를 발휘하는 곳입니다. 검증 프로토콜 (verification protocols)과 도구 폴백 계층 (tool fallback ladders) 또한 CLAUDE.md에서 참조되는 인접 파일들에 존재하게 됩니다.

개인 vs 협업 (Solo vs collaborative): 개인 프로젝트는 계약서(contract)에 1인칭 시점을 사용할 수 있습니다. 반면, 협업 프로젝트는 시점에 구애받지 않는 지침(voice-agnostic instructions)으로 작성해야 합니다 (예: "I use X"가 아닌 "the team uses X"라고 작성).

구조는 동일하게 유지됩니다. 채워 넣는 내용만 달라질 뿐입니다.

유지보수 (Maintenance)

규칙: 이 파일은 이유 없이 변경하지 않습니다.

CLAUDE.md를 수정하기 위한 좋은 이유들:

• 확정된 결정(locked decision)이 내려졌을 때. 이를 섹션 2에 추가합니다.
• 상시 규칙(standing rule)으로 다룰 가치가 있는 새로운 패턴이 나타났을 때. 섹션 1에 추가합니다.
• 제약 사항(constraint)에 부딪혔을 때. 섹션 3에 추가합니다.
• 교훈(lesson)을 얻었을 때. 섹션 4에 추가합니다.

나쁜 이유들:

• "이 문장을 더 잘 표현할 수 있을 것 같다." (아마 사실일 것입니다. 하지만 프로젝트 중간에 파일을 건드릴 좋은 이유는 아닙니다.)
• "섹션들을 재구성하고 싶다." (그러지 마세요. 기존 구조를 읽고, 그 안에서 작업하세요.)

파일이 다루기 힘들 정도로 길어진다면, 이는 가장 무거운 섹션들을 별도의 파일로 추출하여 @import를 통해 참조하라는 신호입니다. 전체 키트(full kit)의 구조(.claude/rules/는 행동 규칙용, .claude/reference/는 프로젝트 특정 데이터용)는 정확히 이러한 진화 과정을 위해 설계되었습니다.

스타터는 무료입니다

무료로 다운로드할 수 있는 스타터 CLAUDE.md가 있습니다. 여기에는 이 4개 섹션 구조가 미리 구축되어 있으며, 프로젝트에 맞춰 채워 넣을 수 있는 플레이스홀더(placeholders)가 준비되어 있습니다. 프로젝트 루트에 넣고 15분 동안 작업하면, 이미 시중에 있는 CLAUDE.md 파일의 90%보다 더 나은 운영 계약서(operating contract)를 갖게 될 것입니다.

solooperator.dev

강화된 모드별 버전(모듈형 .claude/rules/ 구조를 갖춘 코드 모드, 편집 규율을 갖춘 콘텐츠 모드)은 전체 Solo Operator Kit에 포함되어 있습니다.

두 가지 모드, 하나의 키트, $99. 파이프라인 모드(Pipeline mode)는 v2에서 v1 구매자에게 추가 비용 없이 제공될 예정입니다. 링크는 동일합니다.