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

출처: Dev.to

대부분의 CLAUDE.md 파일은 Claude의 행동을 실제로 제한하지 못하기 때문에 실패합니다. 프로젝트가 방향을 바꾸는 순간 바로 부서지고 오래된 정보가 됩니다. CLAUDE.md를 머리속 메모장처럼 다루지 마세요. 운영 계약으로 다루세요.

다음은 몇 달 동안 버틸 수 있는 네 섹션 구조입니다.

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

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

프로젝트: 재고 관리를 위한 Next.js 앱. TypeScript 사용. Tailwind 선호. 클래스 컴포넌트는 사용하지 않음.

이는 시작점일 뿐, 운영 계약이 아닙니다. Claude는 이 프로젝트에서 성공이 어떤 모습인지, 이미 어떤 결정이 내려졌는지, 무엇을 제안하지 말아야 하는지 전혀 모릅니다. 첫 번째 세션은 괜찮지만, 다섯 번째 세션에서 Claude가 “그게 최신 Next.js 패턴이니까 라우팅 레이어를 리팩터링하자”고 제안한다면, 파일에 이를 막는 내용이 없기 때문입니다.

너무 부서지기 쉬운 버전도 또 다른 문제입니다:

users 테이블은 user_id 로 profiles와 조인됩니다. 프론트엔드에 보내기 전에 UUID를 문자열로 캐스팅하세요. /api/webhooks/stripe.ts 의 Stripe 웹훅 핸들러는 원시 바디가 필요합니다. /lib/auth/middleware.ts 를 수정하지 마세요. pages/dashboard/[id]/edit.tsx 파일에는 알려진 레이스 컨디션이 있습니다…

이 모든 정보를 하나의 파일에 억지로 끼워넣은 것입니다. 스키마 마이그레이션, 웹훅 리팩터링, 새로운 인증 패턴 등 어느 하나라도 바뀌면 파일은 틀려버립니다.

해결책은 CLAUDE.md를 위키가 아니라 계약으로 생각하는 것입니다. 계약은 섹션으로 나뉘며, 각 섹션은 서로 다른 질문에 답합니다.

모든 CLAUDE.md에 필요한 네 섹션

섹션 1: 지속적인 운영 지침

작업에 관계없이 Claude가 항상 따라야 할 내용입니다. 거의 변하지 않아야 하는 부분이죠.

여기에 들어갈 내용:

• 행동 패턴. “허둥대지 마세요. 세 가지 접근법이 모두 실패했다면 멈추고 원래 요청에 뭐가 문제인지 물어보세요.”
• 재사용 기대치. “새로운 추상화를 만들기 전에 코드베이스에서 기존 구현을 검색하세요.”
• 작동 중인 코드 보호. “명시적인 요청 없이 작동 중인 코드를 덮어쓰지 마세요. ‘나는 다르게 작성하고 싶다’는 기준이 아닙니다.”
• 커뮤니케이션 선호도. “여러 유효한 접근법이 있다면 모두 열거하고 내가 선택하게 하세요. 조용히 하나만 고르지 마세요.”

이 섹션은 Claude에게 프로젝트 내에서 가장 가까운 ‘성격’과도 같습니다. 한 번 잘 만들면 시작하는 모든 프로젝트에 같은 규칙을 그대로 옮길 수 있습니다. 목표는 이 섹션이 대부분 프로젝트와 무관하도록 해서 작성 노력이 누적되게 하는 것입니다.

섹션 2: 프로젝트 컨텍스트

프로젝트가 실제로 무엇인지, 왜 존재하는지, 성공이 어떤 모습인지 설명합니다.

여기에 들어갈 내용:

• 한 줄 프로젝트 설명.
• 스택. 언어, 프레임워크, 데이터베이스, 배포 대상.
• 프로젝트 현재 단계(출시 전, 운영 중, 성숙 단계 등).
• 잠긴 결정(Locked decisions). 이미 내린 건축적 선택으로 재평가하면 안 되는 것들. 예: “우리는 MongoDB가 아니라 Postgres를 사용합니다. 10월에 결정했으며 다시 제안하지 마세요.”

잠긴 결정 하위 섹션은 이 섹션에서 가장 큰 영향력을 가집니다. 대부분의 세션 편향은 Claude가 이미 결정된 사항에 대해 다른 접근법을 제안하면서 발생합니다. 왜 그런 결정을 내렸는지 한 번 문서화하면 이후 세션에서 그 편향을 차단할 수 있습니다.

누군가가 차가운 상태에서 이 섹션만 읽고도 60초 안에 프로젝트를 이해할 수 있어야 합니다. 그렇지 못하면 내용이 너무 모호한 겁니다.

섹션 3: 관례와 제약

부정적인 공간, 즉 하지 말아야 할 것을 적는 곳입니다. 피해야 할 패턴, 이미 시도했지만 거절된 방법 등을 기록합니다.

여기에 들어갈 내용:

• 금지 목록. “요청이 없으면 테스트 파일을 생성하지 마세요. 명시적인 요청 없이 파괴적인 명령(drop, delete, force push)은 실행하지 마세요.”
• 스택에 특화된 안티패턴. “대시보드 UI에는 서버 컴포넌트를 제안하지 마세요. 이 프로젝트는 클라이언트 컴포넌트를 선택했습니다.”
• 의도적으로 보이지만 잘못된 것이 아닌 경우. “인증 미들웨어가 세션이 없을 때 조기에 반환하지 않는 것은 의도된 동작이며, 파일 내 주석을 참고하세요.”

섹션 1과 구분하는 이유는 제약은 시간이 지나면서 변하기 때문입니다. 지속적인 운영 지침은 대부분 영구적이지만, 제약은 프로젝트가 성장하고 팀이 어떤 패턴이 안 맞는지 배우면서 누적됩니다.

이 섹션은 또한 ‘툴 잡음(tool noise)’을 문서화하는 곳입니다. 매 세션마다 반복해서 설명해야 하는 사소한 방해 요소들을 기록합니다.

예시: “개발 서버가 핫 리로드 시 hydration 경고를 내보내면 지속되지 않는 한 무시하세요.” 한 번 기록해두면 매 세션마다 같은 설명을 할 필요가 없습니다.

섹션 4: 교훈

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

여기에 들어갈 내용은 Claude가 시간이 지나면서 배운 점을 기록한 실시간 로그입니다. 각 항목은 짧게 적습니다:

LESSON: 하나의 접근법에 막혔을 때, 우회책을 제시하기보다 전체 툴킷을 즉시 고려하세요.
THE MISTAKE: Bash에서 네트워크 제한에 걸려 Python 대안을 계속 제시(같은 제한), 수동 다운로드 방안을 반복 제시. 사용자가 도전했을 때만 브라우저 툴을 사용함.
THE FIX: 막혔을 때 먼저 자신의 기능을 조사하세요. 파일 다운로드 → 브라우저 툴이 직접적인 해결책. 자동화 가능한 툴이 있을 때 수동 방안을 제안하지 마세요.
APPLIED TO: SEC 서류 다운로드, URL 기반 파일 다운로드 전반.

이 형식은 세 가지 역할을 합니다. 실패 유형을 명명해 인식 가능하게 만들고, 구체적인 해결책을 문서화하며, 적용 범위를 태그해 언제 적용되는지 명확히 합니다.

핵심 원칙은 덮어쓰기(overwrite) 대신 추가(append) 하는 것입니다. 이해가 진화하면 날짜와 함께 인라인 교정문을 추가합니다:

CORRECTION (2026-05-21): “완전 자동화, 수동 단계 전혀 없음”이라는 주장은 예약 작업 샌드박스에서는 성립하지 않습니다. 호스트가 허용 목록에 없으며, 파이프라인은 호스트가 허용 목록에 올라가거나 브라우저가 연결된 상태에서만 실행됩니다.

RESOLVED for LOCAL runs (2026-06-05): 스크립트를 일반 로컬 프로세스로 실행할 때 호스트에 접근 가능했습니다. 제한은 예약 작업 샌드박스에만 있었으며, 이제 로컬 실행을 위한 --auto 모드가 추가되었습니다.