CLAUDE.md 작성·구성

Claude Code 프로젝트에 메모리(CLAUDE.md)를 처음 만들고, 커지면 나누고, 주기적으로 점검하는 절차다. 개념과 로드 규칙은 개념 페이지에 있다.

준비물(필요한 것)#

1. 시작 파일 만들기#

1. 세션에서 /init(슬래시 명령, 용어 사전)을 실행한다. Claude가 코드베이스를 분석해 빌드 명령, 테스트 방법, 발견한 관례를 담은 CLAUDE.md를 만든다. 이미 CLAUDE.md가 있으면 덮어쓰지 않고 개선안을 낸다. Claude Code 메모리
2. 여러 단계 대화형으로 만들고 싶으면 /init 전에 환경 변수 CLAUDE_CODE_NEW_INIT=1을 설정한다. 그러면 CLAUDE.md·스킬·훅 중 무엇을 만들지 묻고, 서브에이전트로 코드베이스를 살핀 뒤 후속 질문으로 빈 곳을 채우고, 파일을 쓰기 전에 검토할 제안을 보여 준다. Claude Code 메모리
3. 생성된 파일에 Claude가 스스로 알아내지 못할 지시를 더해 다듬는다. Claude Code 메모리
4. /context를 실행해 Memory files 목록에 파일이 있는지 확인한다. Claude Code 메모리

파일 위치는 ./CLAUDE.md나 ./.claude/CLAUDE.md 중 하나다. 버전 관리로 팀과 공유되므로 개인 선호가 아니라 프로젝트 수준 표준(빌드·테스트 명령, 코딩 표준, 아키텍처 결정, 이름 규칙, 자주 쓰는 워크플로)에 집중한다. Claude Code 메모리

다른 도구에서 옮겨 오는 경우: /init은 Cursor 규칙(.cursor/rules/, .cursorrules)과 Copilot 규칙(.github/copilot-instructions.md)을 읽어 관련 부분을 반영한다. CLAUDE_CODE_NEW_INIT=1이면 AGENTS.md, .devin/rules/, .windsurf/rules/·.windsurfrules, .clinerules도 읽는다. /import(v2.1.213 이상)는 지원하는 코딩 에이전트의 지시 파일을 해당 CLAUDE.md에 한 번 복사해 붙이고 MCP 서버, 명령, 서브에이전트, 스킬도 가져온다. Claude Code 메모리

2. 지시 쓰기#

확인할 수 있게 구체적으로 쓴다. 원본 예: Claude Code 메모리

짧고, 정리되고, 일관되게. Claude Code 메모리

• 크기: 파일당 200줄 이하를 목표로 한다. 길수록 컨텍스트를 더 쓰고 준수가 떨어진다.
• 구조: 관련 지시를 마크다운 제목과 글머리 아래 묶는다. 빽빽한 문단보다 따르기 쉽다.
• 일관성: 두 지시가 모순되면 Claude가 하나를 임의로 고를 수 있다. 낡거나 충돌하는 지시를 주기적으로 지운다.

항상 들고 있을 사실만, 색인처럼. (2026-06-18 기준) 블로그 글은 CLAUDE.md를 코드베이스 개요, 또는 Claude가 필요할 때 더 많은 정보를 찾을 다른 파일을 가리키는 색인으로 생각하라고 한다. 내용은 다른 프롬프트와 같은 규칙을 따른다: 명시적으로 쓰고, 제약 뒤의 이유를 설명하고, 예시를 보여 준다. Steering Claude Code

주인을 두고 코드처럼 리뷰한다. (2026-06-18 기준) 공유 저장소의 CLAUDE.md는 주인 없는 설정 파일처럼 모든 팀이 덧붙이고 아무것도 지우지 않아 불어나며, 그 비용은 규모가 커질수록 복리로 쌓인다. 원본 팁: 200줄 이하로 유지하고, 주인을 정하고, 변경을 코드처럼 리뷰한다. 커지면 팀별 관례는 경로별 rules로, 절차는 스킬로 밀어낸다. Steering Claude Code

컴팩션 때 남길 것을 적어 둔다. (2026-10-18 기준) 공식 작동 방식 문서는 컴팩션 때 무엇을 남길지 정하려면 CLAUDE.md에 "Compact Instructions" 절을 더하거나 /compact에 초점을 주라고 한다(예: /compact focus on the API changes). 절 안에 무엇을 어떤 형식으로 쓰는지는 원본에 없다. 같은 문서는 컴팩션 때 대화 초반의 자세한 지시가 사라질 수 있으니 지속 규칙은 대화가 아니라 CLAUDE.md에 두라고 한다. Claude Code 작동 방식 → 장기 작업 컨텍스트 관리

사람용 메모는 HTML 주석으로. 블록 단위 <!-- ... -->는 컨텍스트에 넣기 전에 지워지므로 토큰을 쓰지 않는다. Claude Code 메모리

3. 개인 지시 분리하기#

• 버전 관리에 올리지 않을 개인의 프로젝트별 선호(샌드박스 URL, 선호 테스트 데이터)는 프로젝트 루트의 CLAUDE.local.md에 두고 .gitignore에 추가한다. CLAUDE.md와 함께 로드되고 같은 방식으로 다뤄진다. Claude Code 메모리
• 같은 저장소의 git 워크트리 여러 개에서 개인 지시를 공유하려면 CLAUDE.local.md 대신 홈 디렉터리 파일을 import한다. Claude Code 메모리

# Individual Preferences
- @~/.claude/my-project-instructions.md

• 모든 프로젝트에 쓰는 개인 선호는 ~/.claude/CLAUDE.md나 ~/.claude/rules/에 둔다. Claude Code 메모리 (2026-06-18 기준) 블로그 글도 파일 기반 방법은 모두 저장소와 상관없이 매 세션 로드되는 사용자 수준 짝이 있으니, 개인 선호(예: 항상 시맨틱 커밋 메시지)는 거기에 두고 프로젝트 파일은 팀 공통이면서 그 코드베이스에 한정된 선호만 담으라고 한다. Steering Claude Code

4. 커지면 나누기#

@path import로 정리한다. README, package.json, 워크플로 문서를 CLAUDE.md 어디에서든 가져올 수 있다. Claude Code 메모리

See @README for project overview and @package.json for available npm commands for this project.

# Additional Instructions
- git workflow @docs/git-instructions.md

• 상대 경로는 import하는 파일 기준이다. 재귀 import는 최대 4단계. Claude Code 메모리
• 경로에 공백이 있으면 공백마다 백슬래시를 넣는다(@Design\ Docs/api-conventions.md). 따옴표로 감싼 경로는 import되지 않는다. Claude Code 메모리
• 백틱으로 감싸면(`@README`) import하지 않고 글자 그대로 남는다. Claude Code 메모리
• 주의: import는 정리용일 뿐 컨텍스트 비용을 줄이지 않는다. 가져온 파일도 시작 때 로드된다. Claude Code 메모리 → 컨텍스트 비용

코드베이스 일부에만 해당하는 지시는 .claude/rules/로 뺀다. 한 파일에 한 주제, testing.md·api-design.md처럼 설명적인 이름을 쓴다. 하위 폴더(frontend/, backend/)까지 재귀로 찾는다. Claude Code 메모리

your-project/
├── .claude/
│   ├── CLAUDE.md           # Main project instructions
│   └── rules/
│       ├── code-style.md   # Code style guidelines
│       ├── testing.md      # Testing conventions
│       └── security.md     # Security requirements

특정 파일에서만 쓰이게 하려면 paths frontmatter를 단다. Claude가 맞는 파일을 Read·Write·Edit 도구로 다루거나 cat·head 같은 읽기 명령으로 볼 때 로드된다. Claude Code 메모리

---
paths:
  - "src/api/**/*.ts"
---

# API Development Rules

- All API endpoints must include input validation
- Use the standard error response format
- Include OpenAPI documentation comments

• paths가 없는 규칙은 시작 때 무조건 로드된다. Claude Code 메모리 (2026-06-18 기준) 블로그 글은 범위 없는 규칙이 CLAUDE.md에 넣은 것과 기계적으로 같다고 말한다. 항상 로드되고 항상 토큰을 쓰며, 컴팩션 때 다시 주입된다. Steering Claude Code
• (2026-06-18 기준) 경로별 규칙 vs 하위 디렉터리 CLAUDE.md: "마이그레이션은 append-only" 같은 파일별 제약은 paths: frontmatter를 단 규칙이 가장 잘 맞는다. 지시가 코드베이스 여러 구석(전부는 아닌)에 나타나는 횡단 관심사나 파일에 관한 것이면 하위 디렉터리 CLAUDE.md보다 경로별 규칙을 쓴다. 원본 예시: Steering Claude Code

---
paths:
  - "src/api/**"
  - "**/*.handler.ts"
---
All API handlers must validate input with Zod before processing.

• glob 예: **/*.ts(모든 TS 파일), src/**/*(src 아래 전부), *.md(루트의 마크다운), src/components/*.tsx. 중괄호 확장도 된다("src/**/*.{ts,tsx}"). Claude Code 메모리
• 규칙 frontmatter에서 Claude Code가 읽는 필드는 paths 하나뿐이다. 다른 필드는 오류 없이 무시된다. YAML이 깨지면 paths가 없는 규칙처럼 로드되며, claude --debug로 파싱 오류를 볼 수 있다. Claude Code 메모리
• 여러 프로젝트에서 같은 규칙을 쓰려면 심볼릭 링크를 건다(ln -s ~/shared-claude-rules .claude/rules/shared). 작업 디렉터리 밖을 가리키는 링크는 외부 import처럼 승인이 필요하다. 승인 없이 쓰려면 ~/.claude/rules/에 둔다. Claude Code 메모리

항상 필요하지 않은 작업별 지시는 스킬로. 규칙은 매 세션 또는 맞는 파일을 열 때 로드되지만, 스킬은 부르거나 관련 있다고 판단될 때만 로드된다. Claude Code 메모리 공식 스킬 문서도 CLAUDE.md의 한 절이 사실이 아니라 절차로 자랐다면 스킬을 만들라고 한다. 스킬 본문은 쓸 때만 로드되므로 긴 참고 자료도 필요하기 전까지 비용이 거의 없다(2026-10-18 기준). Claude Code 스킬 옮기는 절차: 업무 절차를 스킬로 만들기

5. 주기적으로 점검하기#

• /doctor prompt-audit를 실행하면 Claude가 지시 파일에서 옛 모델용으로 쓴 지시, 없는 파일·명령 참조, 서로 모순되는 파일을 찾아 수정 제안과 함께 보고한다. 사용자가 적용하라고 하기 전에는 파일을 바꾸지 않는다. v2.1.283 이상. Claude Code 메모리
• 기본 대상은 CLAUDE.md, CLAUDE.local.md, AGENTS.md와 .claude/·~/.claude/ 아래 규칙, 스킬, 명령, 서브에이전트, 출력 스타일이다. 하나만 보려면 경로를 넘긴다(/doctor prompt-audit .claude/skills/deploy). Claude Code 메모리
• /doctor는 체크인된 CLAUDE.md를 줄일 제안을 낸다. 코드에서 알 수 있는 내용은 빼고 함정·이유·기본값과 다른 관례는 남긴다. Claude Code 메모리 공식 스킬 문서에 따르면 /doctor 점검은 체크인된 CLAUDE.md와 중복되는 로컬 CLAUDE.md도 찾고, 남은 항상 로드되는 지침을 필요할 때 로드되는 스킬과 하위 CLAUDE.md로 옮기자고 제안한다. 바꾸기 전에 확인을 받는다(2026-10-18 기준). Claude Code 스킬

6. 팀·조직 단위로 운영하기#

• 조직 전체 지시는 managed policy 위치(macOS /Library/Application Support/ClaudeCode/CLAUDE.md 등)에 파일을 만들고 MDM, Group Policy, Ansible 같은 구성 관리 도구로 배포한다. 개인 설정으로 제외할 수 없다. Claude Code 메모리
• 파일 대신 managed-settings.json의 claudeMd 키에 내용을 직접 넣을 수 있다. managed·policy 설정에서만 효력이 있다. Claude Code 메모리 managed-settings.json을 OS별 시스템 디렉터리(조직 CLAUDE.md와 같은 디렉터리)에 배포하고 /status로 적용을 확인하는 절차는 Claude Code managed settings 배포·점검에 있다(2026-10-18 기준). Claude Code managed settings 배포

{
  "claudeMd": "Always run `make lint` before committing.\nNever push directly to main."
}

• (2026-06-18 기준) 모노레포에서는 팀 디렉터리마다 하위 디렉터리 CLAUDE.md를 두어 각 팀이 자기 관례만 로드하게 하고, 개발자는 claudeMdExcludes로 자기가 손대지 않는 팀의 파일을 건너뛸 수 있다. Steering Claude Code
• 대형 모노레포에서 다른 팀의 상위 CLAUDE.md가 섞이면 claudeMdExcludes로 건너뛴다. 내 기계에만 적용하려면 .claude/settings.local.json에 둔다. Claude Code 메모리

{
  "claudeMdExcludes": [
    "**/monorepo/CLAUDE.md",
    "/home/user/monorepo/other-team/.claude/rules/**"
  ]
}

됐는지 확인하는 법#

• 파일이 로드되는지: /context를 실행해 Memory files 목록에 방금 만든 CLAUDE.md가 있는지 본다(1절 4번). Claude Code 메모리
• 경로별 규칙(paths:)의 frontmatter: YAML이 깨지면 오류 없이 paths가 없는 규칙처럼 항상 로드된다. claude --debug로 파싱 오류를 볼 수 있다(4절). Claude Code 메모리
• 지시끼리 모순·낡은 참조가 없는지: /doctor prompt-audit(v2.1.283 이상)가 옛 모델용 지시, 없는 파일·명령 참조, 서로 모순되는 파일을 보고한다. 적용하라고 하기 전에는 파일을 바꾸지 않는다(5절). Claude Code 메모리
• 조직 배포분: managed-settings.json이 적용됐는지는 /status로 확인한다. 절차는 Claude Code managed settings 배포·점검. Claude Code managed settings 배포
• 지시를 실제로 따르는지: 원본에는 따로 확인 방법이 없다. 따르지 않는 것 같으면 CLAUDE.md 문제 해결의 증상별 점검으로 넘어간다. Claude Code 메모리

언제 쓰고 언제 쓰지 않는가#

• CLAUDE.md에 적는다: Claude가 같은 실수를 두 번째로 할 때, 코드 리뷰에서 Claude가 알았어야 할 것이 걸릴 때, 지난 세션에 친 교정을 또 칠 때, 새 팀원에게도 필요한 맥락일 때. Claude Code 메모리
• (2026-06-18 기준) 이미 있는 CLAUDE.md에서 옮길 지시를 찾을 때는 블로그 글의 다섯 신호("매번 X면 항상 Y", "절대 하지 마라", 30줄짜리 절차, 범위 없는 API 전용 규칙, 프로젝트 파일의 개인 선호)를 쓴다. Steering Claude Code → Claude Code 확장 기능 고르기
• CLAUDE.md에 적지 않는다: 여러 단계 절차나 코드베이스 일부에만 해당하는 것(스킬이나 경로별 규칙으로), 매번 반드시 지켜져야 하는 규칙(→ 훅. 조직 단위의 도구·명령·경로 차단은 managed settings의 permissions.deny). Claude Code 메모리
• 지켜지지 않으면: CLAUDE.md 문제 해결
• 이미 AGENTS.md를 쓰는 저장소라면: AGENTS.md와 CLAUDE.md 함께 쓰기
• 무엇부터 더할지 큰 순서: Claude Code 셋업 점진적으로 키우기