공식 참고 자료: Overview · Memory & CLAUDE.md · Settings
커리큘럼 흐름
- CLAUDE.md Mastery — 저장소 메모리, 컨벤션, 아키텍처 ← 현재 문서
- Effective Prompting — 작업 지시를 명확히 전달하기
- MCP Power Tools — 도구와 데이터를 연결하기
- Multi-Agent Workflows — 위임과 병렬 실행
- Hooks Automation — 로컬 가드레일 자동화
- GitHub Actions Workflows — 반복 작업을 팀 자동화로 옮기기
이 문서에서 참고한 공식 문서
CLAUDE.md의 역할과 메모리 방식 — Memory & CLAUDE.md files- 설정과 공유 규칙 관리 — Settings
- Claude Code의 기본 운영 모델 — Overview
CLAUDE.md가 중요한 이유
CLAUDE.md는 Claude Code에서 만들 수 있는 가장 영향력 있는 파일입니다. 모든 대화에 자동으로 로드되어 프로젝트에 대한 지속적인 컨텍스트를 제공합니다.
프로젝트 위키를 읽고 오는 시공사와 아무것도 모르고 오는 시공사의 차이라고 생각하세요.
좋은 CLAUDE.md의 구조
1. 프로젝트 컨텍스트 (What)
# MyProject
Next.js 16과 PostgreSQL로 만든 실시간 분석 대시보드.
Turborepo 모노레포: apps/web, apps/api, packages/shared.사실만 적으세요. Claude는 코드를 읽을 수 있습니다 — package.json에서 알 수 있는 내용을 반복하지 마세요.
2. 컨벤션 (How)
## 컨벤션
- 파일명은 kebab-case, 컴포넌트는 PascalCase
- 모든 API 라우트는 `{ data, error }` 형태로 반환
- 테스트 파일은 같은 위치에: `foo.ts` → `foo.test.ts`
- Conventional Commits 사용대부분의 사람이 여기에 투자를 적게 합니다. 컨벤션 하나하나가 Claude가 잘못 추측하는 것을 방지합니다.
3. 아키텍처 결정 (Why)
## 아키텍처 결정
- 기본적으로 Server Components 사용, 인터랙티브한 경우에만 'use client'
- MongoDB 대신 PostgreSQL — 복잡한 조인이 필요한 관계형 데이터
- ORM 없음 — pgtyped를 통한 타입이 있는 raw SQL"왜"를 적으면 Claude가 이미 평가하고 거부한 대안을 제안하는 것을 방지합니다.
4. 금지 패턴 (Don't)
## 하지 말 것
- `any` 타입 사용 금지 — `unknown` 사용 후 좁히기
- barrel exports (index.ts 재내보내기) 금지
- 테스트에서 데이터베이스 mock 금지 — test container 사용부정 지시는 강력합니다. Claude는 명시적 경계를 존중합니다.
프로 팁
CLAUDE.md 계층화
Claude Code는 여러 수준에서 CLAUDE.md를 지원합니다:
- 루트: 프로젝트 전체 규칙
- 하위 디렉토리: 도메인별 컨텍스트
project/
├── CLAUDE.md # 전역 컨벤션
├── apps/
│ ├── web/CLAUDE.md # 프론트엔드 전용
│ └── api/CLAUDE.md # 백엔드 전용
└── packages/
└── shared/CLAUDE.md # 공유 라이브러리 규칙
200줄 이내로 유지
긴 CLAUDE.md는 중요한 컨텍스트를 희석시킵니다. 자세한 내용이 필요하면 문서에 링크하세요:
## API 설계
API 스타일 가이드를 따르세요: `docs/api-style.md` 참조버전 관리하세요
CLAUDE.md는 커밋하세요. 팀 공유 자산입니다 — 한 엔지니어가 Claude에 도움이 되는 패턴을 발견하면 모두가 혜택을 받습니다.
흔한 실수
| 실수 | 왜 해로운지 | 해결법 |
|---|---|---|
| 너무 모호함 ("깨끗한 코드 작성") | 동작을 제한하지 못함 | 구체적으로: "함수당 최대 20줄" |
| 너무 길음 (500줄 이상) | 컨텍스트 희석 | 우선순위화, 문서 링크 |
| 업데이트 안함 | 오래된 규칙이 혼란 유발 | 월별 리뷰 |
| package.json 중복 | 컨텍스트 토큰 낭비 | 명확하지 않은 내용만 추가 |
팀 협업 패턴
CLAUDE.md는 개인 생산성 도구가 아니라 팀 인프라예요. 잘 관리된 CLAUDE.md 하나가 팀 전체의 AI 사용 방식을 통일시켜 줘요.
새 팀원 온보딩 자동화 새로운 팀원이 첫날 Claude Code를 켜면, CLAUDE.md가 이미 프로젝트 컨텍스트를 담고 있어요. "우리 프로젝트가 어떻게 구성되어 있어?"라고 물어보는 시간이 줄어들고, 바로 작업에 들어갈 수 있어요.
팀 전체가 동일한 AI를 사용하게 됨
CLAUDE.md 없이는 팀원마다 Claude에게 다른 방식으로 코드를 생성하게 돼요. 누구는 any 타입을 쓰고, 누구는 안 쓰고 — CLAUDE.md가 이 차이를 없애줘요.
PR 리뷰 마찰 감소 "왜 Claude가 이렇게 생성했지?"라는 질문이 PR 리뷰에서 나온다면, 그건 CLAUDE.md에 해당 컨벤션이 없다는 신호예요. 발견할 때마다 규칙을 추가하면 점점 리뷰 마찰이 줄어들어요.
시작하기 좋은 템플릿
처음 CLAUDE.md를 작성한다면 아래를 복사해서 프로젝트에 맞게 수정해 보세요:
# [프로젝트 이름]
[한 줄 설명: 무엇을, 어떤 기술로 만든 프로젝트인지]
## 컨벤션
- [파일명 규칙, 예: kebab-case]
- [코드 스타일, 예: 함수당 최대 20줄]
- [테스트 규칙, 예: 테스트 파일은 같은 디렉토리에 배치]
## 아키텍처
- [핵심 기술 결정과 그 이유]
- [피해야 할 대안과 이유]
## 하지 말 것
- [금지 패턴 1]
- [금지 패턴 2]
## 자주 쓰는 명령어
- 테스트: `npm test`
- 빌드: `npm run build`
- 린트: `npm run lint`고급 패턴
조건부 지시
파일 유형이나 작업 맥락에 따라 다른 규칙을 적용할 수 있어요:
## 상황별 규칙
- 프론트엔드 파일 수정 시: Tailwind CSS 클래스만 사용, 인라인 스타일 금지
- API 라우트 수정 시: 반드시 에러 핸들링 포함, 타입 있는 응답 반환
- 테스트 파일 수정 시: describe/it 패턴 사용, 한글 테스트명Claude는 현재 작업 중인 파일 경로를 알고 있기 때문에 이런 조건부 지시를 자연스럽게 따라요.
외부 문서 참조 패턴
CLAUDE.md에 모든 내용을 담으려 하지 마세요. 상세 내용은 파일로 분리하고 참조만 해두세요:
## 참고 문서
- API 설계 원칙: `docs/api-style.md` 참조
- DB 스키마 구조: `docs/schema.md` 참조
- 배포 절차: `docs/deploy.md` 참조Claude는 필요할 때만 해당 파일을 읽어요. CLAUDE.md는 가볍게 유지하면서 필요한 세부 정보는 항상 접근 가능한 구조예요.
CLAUDE.md를 지속적으로 발전시키는 방법
처음부터 완벽할 필요는 없어요. 오히려 처음엔 작게 시작하는 게 좋아요:
- 처음엔 최소한으로: 5-10줄로 시작하세요. 프로젝트 한 줄 설명과 핵심 컨벤션 2-3개면 충분해요
- Claude가 잘못하면 규칙 추가: Claude가 기대와 다른 코드를 생성하면, 그 자리에서 CLAUDE.md에 규칙을 추가하세요
- 월별 리뷰: 한 달에 한 번 훑어보며 이미 당연해진 규칙이나 더 이상 유효하지 않은 규칙을 제거하세요
- "왜 이렇게 했지?" 테스트: Claude의 결정이 이해되지 않는다면, 그 판단 근거가 CLAUDE.md에 빠져 있다는 신호예요
.claude/ 디렉토리 심화
CLAUDE.md 너머, .claude/ 디렉토리 전체가 하나의 프로젝트 AI 설정 공간이에요:
.claude/settings.json— 프로젝트 공유 설정 (버전 관리 O).claude/settings.local.json— 개인 설정, API 키 등 (gitignore 권장).claude/commands/— 팀만의 커스텀 슬래시 커맨드 정의
예를 들어 .claude/commands/review.md를 만들면 팀 전체가 /review 커맨드로 동일한 코드 리뷰 워크플로우를 실행할 수 있어요. CLAUDE.md가 "무엇을 알아야 하는지"를 정의한다면, .claude/는 "어떻게 동작해야 하는지"를 정의하는 공간이에요.
설정 계층 구조 (Settings Hierarchy)
Claude Code는 네 단계의 설정 우선순위 시스템을 가지고 있어요. 높은 단계가 낮은 단계를 덮어씁니다:
| 우선순위 | 레벨 | 위치 | 관리 주체 |
|---|---|---|---|
| 1 (최고) | Enterprise Policy | 조직 관리자 설정 | IT/보안 팀 |
| 2 | User Settings | ~/.claude/settings.json |
개인 |
| 3 | Project Settings | .claude/settings.json |
팀 (git 커밋) |
| 4 (최저) | Local Settings | .claude/settings.local.json |
개인 (gitignore) |
실제 팀에서 각 레벨을 어떻게 활용하는지 예시를 볼게요:
// Enterprise Policy — 조직 관리자가 설정, 개인이 변경 불가
{
"disallowedTools": ["Bash"], // 보안상 Bash 실행 차단
"blockedCommands": ["rm -rf"] // 위험 명령어 차단
}
// User Settings (~/.claude/settings.json) — 개인 전역 설정
{
"preferredModel": "sonnet", // 기본 모델 선호
"mcpServers": {
"my-notes": { "command": "notes-mcp" } // 개인 MCP 서버
}
}
// Project Settings (.claude/settings.json) — 팀 공유, git 추적
{
"allowedTools": ["Read", "Write", "Edit", "Bash"],
"hooks": {
"PreToolUse": [{ "matcher": "Write", "command": "lint-check.sh" }]
}
}
// Local Settings (.claude/settings.local.json) — 개인 로컬, gitignore
{
"env": {
"API_KEY": "sk-local-dev-key-..." // 개인 API 키
}
}핵심은 이거예요: 팀 규칙은 Project Settings에, 개인 환경은 Local Settings에 분리하세요. Enterprise Policy가 있는 조직이라면 보안 관련 설정은 개인이 우회할 수 없어요.
커스텀 슬래시 커맨드 심화
.claude/commands/ 디렉토리에서 팀만의 커스텀 슬래시 커맨드를 만들 수 있어요. 방법은 간단해요:
.claude/commands/디렉토리에 마크다운 파일을 만들어요- 파일명이 커맨드 이름이 돼요 (예:
review.md→/project:review) - 파일 내용이 Claude에게 전달되는 프롬프트 템플릿이에요
$ARGUMENTS플레이스홀더로 사용자 입력을 받을 수 있어요
실전 예시 1: 코드 리뷰
<!-- .claude/commands/review.md -->
다음 파일을 팀 코드 표준에 따라 리뷰해 주세요: $ARGUMENTS
체크리스트:
- 타입 안전성: `any` 사용 여부
- 에러 핸들링: 모든 async 함수에 try/catch 있는지
- 테스트: 새 함수에 대응하는 테스트가 있는지
- 네이밍: kebab-case 파일명, PascalCase 컴포넌트
발견된 문제마다 수정 코드를 제안해 주세요.사용법: /project:review src/api/users.ts
실전 예시 2: DB 마이그레이션 체크리스트
<!-- .claude/commands/migrate.md -->
다음 데이터베이스 마이그레이션을 검토해 주세요: $ARGUMENTS
확인 사항:
- 롤백 가능한 마이그레이션인가?
- 대용량 테이블에 대한 잠금 시간은 최소화되었는가?
- 인덱스 추가가 concurrently로 되어 있는가?
- 기존 데이터 호환성은 유지되는가?실전 예시 3: 배포 전 검증
<!-- .claude/commands/deploy-check.md -->
배포 전 검증을 실행해 주세요.
1. 빌드가 성공하는지 확인 (`npm run build`)
2. 테스트가 통과하는지 확인 (`npm test`)
3. 환경변수 누락이 없는지 `.env.example`과 비교
4. 마이그레이션 대기 중인 게 있는지 확인
5. CHANGELOG.md가 업데이트되었는지 확인사용법: /project:deploy-check
커스텀 커맨드는 git에 커밋하세요. 팀 전원이 동일한 워크플로우를 사용할 수 있어요.
CLAUDE.md 성능 최적화
CLAUDE.md의 모든 줄은 모든 대화에서 컨텍스트 토큰을 소비해요. 효율적으로 관리하는 팁들이에요:
HTML 주석으로 메타데이터 숨기기
HTML 주석(<!-- -->)은 Claude Code의 자동 주입에서 숨겨지지만, Read 도구로는 볼 수 있어요:
# MyProject
<!-- version: 2.1.0 -->
<!-- last-review: 2026-03-15 -->
<!-- agent-count: 12 -->
Next.js 16 기반 분석 대시보드.메타데이터, 체크섬, 유효성 검증 태그 등은 HTML 주석으로 넣으면 토큰을 절약할 수 있어요.
참조 문서 분리
CLAUDE.md에 모든 내용을 넣지 마세요. 상세 내용은 별도 파일로 분리하고 참조만 남기세요:
## API 설계
API 스타일 가이드를 따르세요: `docs/api-style.md` 참조Claude는 이런 참조를 보면 필요할 때 해당 파일을 읽어요. CLAUDE.md 자체는 가볍게 유지하면서도 깊은 정보에 접근할 수 있는 구조예요.
토큰 예산 인식
실질적인 규칙:
- 200줄 이하를 목표로 하세요 — 이 이상은 컨텍스트 희석이 시작돼요
package.json이나tsconfig.json에서 이미 알 수 있는 내용은 반복하지 마세요- 정기적으로 CLAUDE.md를 리뷰해서 더 이상 필요 없는 규칙을 제거하세요
- 행동 가능한(actionable) 지시만 남기세요 — 배경 설명은 별도 문서로
모노레포 CLAUDE.md 전략
모노레포에서는 세 단계의 CLAUDE.md 계층이 강력하게 작동해요:
monorepo/
├── CLAUDE.md # 레벨 1: 조직 전체 규칙
├── apps/
│ ├── web/
│ │ └── CLAUDE.md # 레벨 2: 프론트엔드 규칙
│ ├── api/
│ │ └── CLAUDE.md # 레벨 2: 백엔드 규칙
│ └── mobile/
│ └── CLAUDE.md # 레벨 2: 모바일 규칙
└── packages/
├── shared/
│ └── CLAUDE.md # 레벨 3: 공유 패키지 규칙
└── ui/
└── CLAUDE.md # 레벨 3: UI 패키지 규칙
레벨 1: 루트 CLAUDE.md (조직 전체)
# MyCompany Monorepo
Turborepo 모노레포. 모든 패키지는 TypeScript strict mode 사용.
## 공통 컨벤션
- Conventional Commits 필수
- PR에 반드시 테스트 포함
- 공유 타입은 `packages/shared/types/`에 정의레벨 2: 앱별 CLAUDE.md
# apps/web
Next.js 16 프론트엔드. App Router 사용.
## 규칙
- Server Components 기본, 인터랙티브에만 'use client'
- 스타일은 Tailwind CSS만 사용
- 배포: Vercel (프리뷰 브랜치 자동 배포)레벨 3: 패키지별 CLAUDE.md
# packages/shared
여러 앱에서 공유하는 유틸리티와 타입.
## API 계약
- 모든 export는 반드시 JSDoc으로 문서화
- Breaking change 시 major 버전 업
- 이 패키지를 사용하는 앱: web, api, mobile핵심 팁: 하위 디렉토리의 CLAUDE.md는 Claude가 해당 디렉토리에서 작업할 때만 로드돼요. 따라서 레벨 2, 3에는 해당 도메인에 특화된 규칙만 넣고, 공통 규칙은 루트에 두세요.
연결: GPT Codex 비교
GPT Codex는 비슷한 목적으로 AGENTS.md와 codex.md를 사용하지만 주요 차이가 있습니다:
- Codex는 태스크 시작 시 한 번만 읽음 (실시간 리로드 없음)
- Codex는 샌드박스에서 실행 — 파일 경로 컨벤션이 더 중요
- Codex 지시문 가이드에서 자세히 확인하세요