Claude Code가 “코드베이스에 사는 시니어 엔지니어”처럼 행동하길 원한다면, 프로젝트에 구조가 필요합니다.
Claude는 네 가지가 필요합니다: • why → 시스템이 무엇을 하는지 • map → 것들이 어디 있는지 • rules → 무엇을 해도/하지 말아야 하는지 • workflows → 일이 어떻게 진행되는지
이걸 Claude Code 프로젝트 구조 가이드라고 부릅니다.
Claude Code 프로젝트 구조 4계층 아키텍처: CLAUDE.md, Skills, Hooks, Docs
1. CLAUDE.md = 프로젝트 개요 (짧게 유지)
가장 중요한 파일입니다.
지식을 쌓는 곳이 아닙니다. 다음만 명확히 적으면 됩니다: • 프로젝트가 무엇을 하는지 • 디렉터리 구조가 무엇인지 • 어떤 규칙이 있는지 • 자주 쓰는 명령어는 무엇인지
흔한 실수: 너무 길게 쓰는 것. CLAUDE.md가 너무 길면, 모델이 중요한 정보를 놓치기 시작합니다. 2000줄 쓴 사람도 봤는데, 결과적으로 Claude가 기본적인 “테스트 파일 수정하지 마”조차 기억 못 했습니다.
추천 길이: 100-300줄.
예시 구조:
# 프로젝트 이름
## 이것은 무엇인가
한 문장으로 프로젝트 목적 설명.
## 디렉터리 구조
src/
auth/ # 인증 모듈
api/ # API 레이어
db/ # 데이터베이스
tests/
## 규칙
- tests/ 디렉터리는 수정하지 말 것
- 모든 API 변경은 먼저 docs/api.md 업데이트
- conventional commits 형식 사용
## 자주 쓰는 명령어
- pnpm dev: 개발 서버 시작
- pnpm test: 테스트 실행
- pnpm build: 프로덕션 빌드이게 전부입니다.
2. .claude/skills/ = 자주 쓰는 프로세스 저장하기
매번 지시사항을 새로 쓰지 마세요.
흔한 워크플로를 skill 파일로 만드세요: • 코드 리뷰 체크리스트 • 리팩터링 가이드 • 배포 프로세스 • 디버깅 단계
장점: 매번 반복할 필요 없고, 팀원도 사용할 수 있습니다.
예시:
.claude/skills/
├── review.md # 코드 리뷰
├── refactor.md # 리팩터링 가이드
├── release.md # 배포 프로세스
└── debug.md # 디버깅 단계review.md 예시:
# Code Review Skill
## 체크리스트
- 코드가 프로젝트 스타일에 맞는지
- 해당 테스트가 있는지
- 하드코딩된 비밀키가 없는지
- 에러 처리가 완전한지
- 성능상 뚜렷한 문제가 없는지
## 출력 형식
1. 전체 평가
2. 구체적 문제 (행 번호 포함)
3. 개선 제안호출 방법: Claude에게 “review skill로 이 PR 검토해줘”라고 말하면 됩니다.
3. .claude/hooks/ = 가드레일
모델은 까먹습니다. Hook은 안 까먹습니다.
반드시 실행해야 하는 것들을 hooks에 넣으세요: • 편집 후 자동 포매팅 • 핵심 코드 변경 시 자동 테스트 실행 • 민감 디렉터리 수정 금지 (auth, billing, migrations)
설정 예시 (settings.json):
{
"hooks": {
"PostToolUse": [
{"matcher": "Edit", "hooks": ["pnpm format"]}
]
}
}민감 디렉터리 금지 hook:
{
"hooks": {
"PreToolUse": [
{
"matcher": "Edit|Write",
"paths": ["src/auth/*", "src/billing/*"],
"action": "block",
"message": "민감 디렉터리, 수동 확인 필요"
}
]
}
}이렇게 하면 Claude가 auth 코드를 수정하려 할 때 자동으로 멈춥니다.
4. docs/ = 상세 문서의 색인
모든 걸 프롬프트에 넣지 마세요.
Claude는 “상세 정보가 어디 있는지”만 알면 됩니다: • 아키텍처 개요 • 기술 결정 기록 • 운영 매뉴얼
원칙: CLAUDE.md에는 색인을, 상세 내용은 docs/에.
## 아키텍처
자세한 내용은 docs/architecture.md 참조
## 중요 결정
- [2024-01] PostgreSQL 선택 이유: docs/adrs/001-postgres.md
- [2024-03] 이벤트 소싱 사용 이유: docs/adrs/002-event-sourcing.mdClaude는 필요할 때 읽으러 갑니다. 불필요할 때는 토큰을 낭비하지 않습니다.
5. 핵심 모듈에 별도의 CLAUDE.md 배치
문제가 자주 발생하는 곳에 별도의 작은 파일을 배치하세요:
src/auth/CLAUDE.md
src/persistence/CLAUDE.md
infra/CLAUDE.md이렇게 하면 Claude가 이 디렉터리에서 작업할 때 주의사항을 바로 볼 수 있습니다.
src/auth/CLAUDE.md 예시:
# Auth 모듈
## 주의사항
- 비밀번호 해시는 bcrypt 사용, SHA256 사용 금지
- Session 만료시간은 7일, auth.service.ts에 하드코딩됨
- verifyToken은 건드리지 말 것, 프로덕션 의존 있음
## 관련 문서
- 인증 흐름도: docs/auth-flow.md
- 보안 감사 보고서: docs/security-audit-2024.md왜 효과적인가: Claude가 이 디렉터리에서 작업할 때, 마침 이 주의사항을 보게 됩니다.
6. 규칙은 오류에서 온다, 미리 계획하는 게 아니다
이게 가장 중요한 점입니다.
CLAUDE.md의 규칙은 “내가 Claude에게 뭘 하길 바라는지”가 아니라 “Claude가 지난번에 뭘 망쳤는지”여야 합니다.
Claude가 같은 실수를 두 번 하면, 그때 규칙 하나를 추가하세요.
몇 주 후, 진짜로 문제를 막을 수 있는 “헌법”이 생깁니다 — 소원 목록이 아니라요.
내 규칙 출처:
| 규칙 | 출처 |
|---|---|
| tests/ 수정 금지 | Claude가 세 번이나 테스트 스냅샷을 망가뜨림 |
| API 변경 시 문서 업데이트 | 두 번 까먹어서 프론트엔드 연동 실패 |
| auth/에 의존성 추가 금지 | 한 번 취약점 있는 패키지 도입 |
| 커밋 메시지 conventional 형식 | CI 실패 너무 많이 발생 |
내가 가진 규칙은 다 이렇게 생겼습니다.
복리 효과가 전부입니다. 시간이 지날수록 규칙은 더 유용해집니다.
규칙은 오류에서 온다, 미리 계획하는 게 아니다: 매번 실수가 규칙 하나가 되고, 복리로 쌓인다.
7. “챗봇”에서 “프로젝트를 이해하는 팀원”으로
프롬프트는 임시적입니다. 구조는 영구적입니다.
코드베이스가 이렇게 조직되면, Claude는 더 이상 일문일답의 챗봇이 아닙니다… 진짜 프로젝트를 이해하는 사람처럼 행동하기 시작합니다.
구조 없음 vs 구조 있음: “AI에게 프롬프트”에서 “팀원과 협업”으로
| 구조 없음 | 구조 있음 |
|---|---|
| 매번 “테스트 수정하지 마” 말해야 함 | Hook이 자동 차단 |
| 매번 아키텍처 설명해야 함 | CLAUDE.md에 지도 있음 |
| 매번 코드 스타일 말해야 함 | skill에 적혀 있음 |
| Claude가 자주 까먹음 | 핵심 위치에 로컬 CLAUDE.md가 있어서 리마인드 |
본질적 차이:
- 구조가 없을 때, 당신은 AI에게 “프롬프트”하는 겁니다.
- 구조가 있을 때, 당신은 프로젝트를 이해하는 팀원과 “협업”하는 겁니다.
요약
Claude Code는 완벽한 프롬프트를 원하지 않습니다.
구조가 명확한 프로젝트 환경을 원합니다.
네 가지:
- CLAUDE.md → 프로젝트 개요와 규칙 (짧게 유지)
.claude/skills/→ 재사용 가능한 워크플로.claude/hooks/→ 강제 실행 가드레일- docs/ + 핵심 위치 CLAUDE.md → 상세 문서
규칙은 오류에서 온다, 미리 계획하는 게 아니다.
이렇게 쓰면, Claude Code가 진짜 프로젝트의 든든한 조수가 될 수 있습니다.
