Claude.md 운영 원칙
한 줄 정의
Claude.md는 Claude Code, OpenCode 또는 Claude 데스크톱 앱의 Cowork 모드 같은 에이전트에게 프로젝트 구조, 제약 조건, 거부 기준을 명시하여 반복되는 온보딩 과정 없이 답변 품질을 극대화하는 AI 행동 계약(Behavioral Contract) 문서다.
핵심 요지
- 행동 계약(Behavioral Contract)으로서의 본질: 설정 파일이라기보다 새 팀원에게 주는 업무 매뉴얼에 가깝다. 복잡한 추상화 레이어를 겹겹이 쌓는 대신, 저장소 루트의 평범한 영어 문장만으로 에이전트가 묵시적 가정이나 과잉 엔지니어링을 피하도록 강제할 수 있다.
- Forrest Chang의 바이럴 레포지토리: Andrej Karpathy의 에이전트 행동 관찰을 바탕으로 정리된 단 한 장의 마크다운 파일(
CLAUDE.md)이 GitHub에서 스타 9만 1천 개를 받으며 주목받았다. 이는 도구 자체보다 ‘행동 가드레일 공유’라는 본질적인 문제를 해결하려는 개발자들의 요구를 방증한다. - 거부하는 것(Reject) 중심 설계: 모호한 긍정적 지침(“전문적으로 써줘”) 대신 싫어하는 문체, 쓰지 않을 단어, 피해야 할 결과물 등 “Hard Nos” 가드레일을 촘촘하게 규정할 때 최상의 답변이 나온다.
- Cowork 기능과의 연동: 데스크톱 앱의 Cowork 탭을 통해 프로젝트 폴더 권한을 부여하면, 매 대화 세션마다 .md 파일을 복사/붙여넣기 할 필요 없이 에이전트가 폴더 내 마크다운 규칙을 자동으로 파악한다.
- 인터뷰 기반 DNA 추출: 맨땅에서 작성을 시작하는 대신 에이전트에게 40~50개의 질문을 하나씩 던지게 하는 인터뷰 방식을 통해 사용자의 구체적 사례가 반영된 맞춤형 .md 프로필을 자동으로 도출한다.
상세
1. 전역 메모리와 로컬 instructions의 결합
- 프로젝트 루트 (
CLAUDE.md): 기술 스택, 빌드/테스트 명령, 프로젝트 구조, 코딩 규칙을 규정한다. context window 낭비를 줄이기 위해 60줄 이하의 핵심 지침 위주로 조립하는 것이 권장된다. - 전역 설정 (
~/.claude.json//memory명령어): 프로젝트 범위를 넘어 전역적으로 적용할 규칙을 설정한다. .claudeignore:.gitignore처럼 에이전트가 탐색하거나 읽지 않아야 할 파일(보안 비밀 키, 빌드 로그 등)을 지정한다.
2. Forrest Chang의 4가지 행동 원칙 (Andrej Karpathy의 관찰 기반)
에이전트가 기본적으로 보일러플레이트를 과도하게 생성하거나 무작정 파일 전체를 포맷팅하는 실패 동작을 방지하기 위한 핵심 규칙이다.
- 코딩하기 전에 먼저 생각하라 (Think before coding):
- 추론 도중 가정을 소리 내어 말하고, 요청이 모호하면 즉시 질문하여 확인한다.
- 헷갈릴 때 자의적으로 해석하여 잘못된 방향으로 코드를 전개하지 않고, 어떤 지점이 불분명한지 구체화하여 제시한다.
- 단순함을 먼저 택하라 (Choose simplicity first):
- 문제를 해결하는 최소한의 코드만 작성한다.
- 향후 발생할지 모르는 요구사항에 대비한 추측성 추상화나 불필요한 아키텍처적 유연성을 일절 배제한다. 항상 “시니어 엔지니어가 이 코드를 보고 과하게 복잡하다고 비판할 것인가?”를 자문하도록 강제한다.
- 외과적으로 수정하라 (Make surgical edits):
- 요청받은 기능 수정 영역만 정밀하게 건드린다.
- 주변 코드 스타일을 임의로 고치거나, 정상 작동하는 무관한 함수를 리팩토링하거나, 전체 파일에 포맷터/타입 힌트를 붙이는 범위 확장(Scope creep)을 엄격하게 금지한다.
- 목표 중심으로 실행하라 (Act target-oriented):
- 코드 작성을 시작하기 전에 모호한 비즈니스 요청을 검증 가능한 기술적 목표로 전환한다.
- 예컨대 “검증 로직 추가”라는 태스크는 “잘못된 입력값에 대응하는 테스트 케이스를 우선 작성하고 통과시키기”로 구체화되어야 한다.
3. 전문 영역별 5대 프로필 유형
취향과 미학, 혹은 도메인 지식의 엄밀성이 강하게 작동하는 워크스페이스는 아래의 특화 프로필(.md)로 나누어 Cowork 폴더에 보관한다.
① 비즈니스 맥락 프로필 (Business Context)
- 비즈니스 가치, 실제 제품 어조, 팀 구조, 주기적 난제, 선호하는 이메일 스타일, 재무/정산 지표, 타협할 수 없는 비즈니스 금기 사항을 정의한다.
② 고유한 글쓰기 문체 프로필 (Writer’s Voice)
- 작문 장르, 가장 만족스러운 대표 문단 예시, 시그니처 단어, AI 번역투 등 혐오 단어 목록, 동경하는 작가의 필살기, 줄글/불릿 레이아웃 선호도를 포함한다.
③ 클라이언트 업무 및 프로젝트 관리 (Client & Project Work)
- 온보딩 필수 자료, 인도물 완료(Done) 판정 기준, 고객 소통 톤앤매너, 프로젝트 범위 초과(Scope Creep) 시 대처 공식, 최우선 의사결정 지침을 명시한다.
④ 크리에이터 아이덴티티 프로필 (Content Creator)
- 채널 정보, 실 활성 타겟 오디언스 프로필, 핵심 콘텐츠 기둥(Content Fillers), 킬러 콘텐츠 및 실패한 콘텐츠 원인 분석, 모방 금지 트렌드를 규정한다.
⑤ 데이터 분석 및 연구원 프로필 (Analyst & Researcher)
- 최종 독자층 및 핵심 의문점, 목소리 대신 숫자를 신뢰하는 통계적 유의성, 신뢰도 및 출처 명시 기준, 가독성 높은 표 서식, 피해야 할 모호한 해석(자의적 주장)을 포함한다.
4. 적대적 프레이밍 (Adversarial Framing)
- 모델의 지나치게 공손하고 안전한 ‘기본 필터’를 해제하고 900달러 상당의 고급 컨설턴트급 사고력을 끌어내기 위한 프롬프트 전략이다.
- 페르소나의 범위를 극도로 좁히고(“스타트업 재무 모델 200개를 검토해 본 CFO”), “PR 리뷰에서 가차 없이 뜯어보고 거절하라”는 등의 적대적 비평을 강제한다.
실무 템플릿 3종 (CC101 가이드)
템플릿 A — 리서치 워크스페이스
- 원문 자료는
sources/폴더에 저장, 파일명:YYYY-MM-DD_출처_제목.md - 모든 수치 및 주장에는 출처 및 신뢰도 구분(A/B/C) 표기
- 결과물 구조: 5줄 요약 → 핵심 인사이트 5개 → 반대 근거/리스크 3개 → 다음 액션 3개
템플릿 B — 콘텐츠 제작 워크스페이스
- 브랜드 톤:
voice_profile.md를 우선 참고하며, 과장 금지 (“완벽/혁명/무조건” 등 금지 단어 지정) - 채널별 포맷: 블로그(제목 3안 → 본문 → 체크리스트 → CTA), 뉴스레터(3줄 요약 → 600~900자 본문)
- 파일 출력 규칙: 초안은
drafts/, 최종본은final/폴더에 버전/검수자/발행일 메타데이터 표기
템플릿 C — 비즈니스 운영 워크스페이스
- 회사/제품 맥락과 자주 쓰는 용어 정의 누적
- 커뮤니케이션 스타일: 이메일(3문단 구조), 고객 불만 응대(공감 → 사실 확인 → 해결 옵션)
- 보안: 개인정보/결제정보 마스킹, 외부 공유 전 “대외비 문구/고객명” 자동 점검
예시
문체 프로필 연동 후 지시 예시
사용자 전용 폴더에 voice_profile.md를 넣어두고 Cowork를 켠 상태로 아래와 같이 짧게 작업만 지시한다.
뉴스레터 Prosper 다음 호 초안을 작성해 줘.
(이 작업을 수행하기 전에 먼저 동일 폴더 안의 voice_profile.md 파일을 꼼꼼히 정독하고 지침을 엄격하게 적용해 줘.)충돌
- 프로젝트 규칙의 비대화에 따른 준수율 저하: Anthropic의 공식 연구에 따르면 에이전트 지침이 200줄을 넘어가면 준수율이 급격히 저하된다. 따라서 범용 프로젝트 룰은 60줄 이하로
CLAUDE.md에 유지하고, 상세 가이드라인과 템플릿 양식은 하위 폴더의 개별 프로필 마크다운(예:voice_profile.md)로 분리해 필요한 상황에서만 참조(Refer)하도록 레이어드 구조로 운영해야 한다.