Claude Code는 프로젝트 폴더에서 CLAUDE.md 파일을 자동으로 읽습니다. 이 파일에 규칙을 적어두면, AI가 매번 같은 말을 하지 않아도 규칙을 따릅니다.
웨비나에서 배운 "이유 3: 같은 에러가 계속 반복된다"의 해결책이 바로 이 파일입니다.
.claude/폴더를 프로젝트 루트에 통째로 복사합니다CLAUDE.md를 프로젝트 루트에 복사합니다- 끝입니다
내 프로젝트/
├── CLAUDE.md <- 프로젝트 전역 설정
├── .claude/ <- 이 폴더를 통째로 복사
│ ├── settings.json <- 훅 설정 (자동 PRD 감지)
│ ├── hooks/
│ │ └── prd-detector.py <- PRD 키워드 감지 훅
│ ├── skills/
│ │ └── prd-create/
│ │ └── SKILL.md <- /prd-create 스킬
│ └── rules/
│ ├── coding-style.md
│ ├── date-rules.md
│ ├── execution-rules.md
│ ├── prd-guide.md
│ ├── project-rules.md
│ └── security-rules.md
├── src/
└── ...
- CLAUDE.md의 "기술 스택" 섹션을 자신의 프로젝트에 맞게 수정합니다
- Claude Code를 실행하면 자동으로 규칙이 적용됩니다
| 파일 | 역할 | 설명 |
|---|---|---|
CLAUDE.md |
프로젝트 전역 설정 | 언어, 스택, 품질, 안전, 아키텍처 (8개 섹션) |
settings.json |
훅 설정 | PRD 키워드 자동 감지 설정 |
prd-detector.py |
PRD 감지 훅 | 사용자 입력에서 PRD 키워드를 감지하여 안내 |
SKILL.md |
PRD 생성 스킬 | /prd-create 명령으로 5단계 PRD 작성 |
coding-style.md |
코드 작성 표준 | 네이밍, 불변성, 타입, 에러 처리 (8개 섹션) |
project-rules.md |
개발 프로세스 | TDD, Pre-mortem, 커밋, 에러 처리 (10개 섹션) |
date-rules.md |
날짜 계산 규칙 | 날짜 계산은 코드로만 (LLM 추론 금지, 4개 규칙) |
execution-rules.md |
실행 완전성 규칙 | 수정 후 검증, 전체 grep, 변형 검색 (4개 규칙) |
security-rules.md |
보안 규칙 | 인증/인가, OWASP Top 10, 시크릿 관리 (6개 섹션) |
prd-guide.md |
PRD 작성 참조 | 아이디어를 PRD 문서로 변환하는 5단계 참조 가이드 |
"이런 앱 만들고 싶어"라고 입력하면 자동으로 PRD 작성 프로세스를 안내받을 수 있습니다.
그냥 대화하듯 입력하면 됩니다:
- "운동 추천 앱 만들고 싶어"
- "요구사항 문서 작성해줘"
- "서비스 기획서 만들어줘"
PRD 관련 키워드가 감지되면 /prd-create 사용을 안내하는 메시지가 자동으로 표시됩니다.
Claude Code에서 /prd-create를 입력하면 바로 5단계 PRD 작성 프로세스가 시작됩니다.
| 단계 | 내용 | 하는 일 |
|---|---|---|
| Phase 1 | 아이디어 구체화 | 필수 질문 4개로 아이디어를 구체화 |
| Phase 2 | 사업성 검토 | Go/No-Go 5점 척도 평가 + 경쟁사 3개 분석 |
| Phase 3 | 기술 리서치 | 기술 스택 결정 + 참고 자료 수집 |
| Phase 4 | PRD 생성 | 10개 섹션으로 PRD 문서 작성 |
| Phase 5 | 다음 단계 | 저장(docs/PRD.md) / 수정 / 개발 시작 선택 |
훅은 Claude Code에서 특정 이벤트가 발생할 때 자동으로 실행되는 스크립트입니다. 이 프로젝트에서는 사용자가 메시지를 보낼 때 PRD 관련 키워드를 감지하는 훅이 포함되어 있습니다.
- 사용자가 Claude Code에 메시지를 입력합니다
prd-detector.py가 메시지에서 PRD 키워드를 찾습니다- 키워드가 발견되면 "/prd-create를 사용해보세요"라는 안내가 표시됩니다
- 키워드가 없으면 아무 일도 일어나지 않습니다 (정상 동작에 영향 없음)
.claude/hooks/prd-detector.py 파일을 열어서 POSITIVE_KEYWORDS와 NEGATIVE_KEYWORDS 리스트를 수정하면 됩니다.
| 좌절 | 원인 | 이 설정으로 해결 | 스터디에서 해결 |
|---|---|---|---|
| 하나 고치면 다른 데 깨짐 | 값이 여러 곳에 흩어져 있음 | SSOT 규칙 (한 곳에만 정의) | 자동 검증으로 누락 방지 |
| AI가 매번 다른 스타일로 코딩 | 규칙이 없어서 매번 새로 판단 | CLAUDE.md가 일관된 규칙 제공 | 프로젝트별 맞춤 규칙 고도화 |
| 같은 에러가 계속 반복 | AI가 이전 실수를 기억 못함 | 에러 처리/안전 규칙으로 예방 | 에러 지식 베이스(KB) 자동 축적 |
| 코드가 점점 복잡해짐 | 파일이 비대해지고 역할이 섞임 | SRP/파일 크기 제한으로 구조 유지 | 자동 리팩토링/분할 도구 |
| 뭘 어디서부터 고쳐야 할지 모름 | 프로젝트 구조 파악이 안됨 | 수정 전 확인 원칙, TDD 규칙 | AI 자동 분석 및 고급 워크플로우 |
| 웨비나에서 배운 구조적 이유 | 이 설정이 해결하는 방법 |
|---|---|
| 이유 1: 하나 고치면 다른 데 깨짐 | SSOT 규칙으로 "한 곳에만 정의" 강제 |
| 이유 2: AI가 길을 잃음 | SRP/파일 크기 제한으로 구조 유지 |
| 이유 3: 같은 에러 반복 | CLAUDE.md가 일관된 규칙을 매 세션 자동 적용 |
- Claude Code에서 "이 프로젝트의 규칙을 알려줘"라고 입력합니다
- 응답이 한국어로 오는지 확인합니다
- 기술 스택(Next.js, TypeScript 등)을 정확히 아는지 확인합니다
- "코드를 작성할 때 지켜야 할 규칙은?"이라고 물어봤을 때 SSOT, SRP 등이 언급되면 정상 적용된 것입니다
Q: 기술 스택을 뭘로 바꿔야 하나요? A: CLAUDE.md의 "기술 스택" 섹션을 본인 프로젝트에 맞게 수정하세요. React, Vue, Python 등 무엇이든 가능합니다.
Q: 이 설정만으로 충분한가요? A: 기본적인 품질 유지에는 충분합니다. 더 자동화된 검증, 위험 방지, AI 팀 협업 등은 스터디에서 다룹니다.
Q: Cursor에서도 되나요? A: Cursor는 .cursorrules 파일을 사용합니다. CLAUDE.md의 내용을 .cursorrules에 복사하면 비슷한 효과를 얻을 수 있습니다.
Q: 설정을 적용했는데 달라진 게 모르겠어요 A: Claude Code를 재시작한 후 "이 프로젝트의 규칙을 알려줘"라고 물어보세요. 규칙을 인식하지 못하면 파일 위치가 맞는지 확인하세요.
Q: /prd-create가 작동하지 않아요
A: .claude/skills/prd-create/SKILL.md 파일이 존재하는지 확인하세요. Claude Code를 재시작하면 스킬이 인식됩니다. 스킬은 Claude Code에서만 작동합니다 (Cursor 등 다른 에디터에서는 지원되지 않습니다).
Q: 훅이 작동하지 않아요 A: 아래 순서로 확인하세요:
.claude/settings.json파일이 존재하는지 확인- Python 3이 설치되어 있는지 확인 (
python3 --version) - 수동 테스트:
echo '{"prompt":"앱 만들고 싶어"}' | python3 .claude/hooks/prd-detector.py - 출력이 나오면 정상, 아무것도 안 나오면 키워드가 매칭되지 않는 것
Q: 훅을 끄고 싶어요
A: .claude/settings.json에서 "hooks" 부분을 삭제하면 됩니다. 규칙 파일(rules/)과 스킬(/prd-create)은 훅 없이도 독립적으로 작동합니다.
Q: 테스트가 통과했는데도 버그가 생겨요 A: 테스트는 "작성한 시나리오"만 확인합니다. 빈 값, 네트워크 끊김, 대량 데이터 같은 예외 상황을 테스트에 포함했는지 확인하세요. project-rules.md의 Pre-mortem 규칙이 이런 누락을 방지합니다.
이 설정은 정적 규칙 기반 설정입니다. 다음 영역은 포함하지 않습니다:
- 규칙을 어겨도 경고가 뜨지 않는다 -- AI가 규칙을 무시하고 코드를 작성해도 자동으로 감지하거나 되돌리지 못한다
- AI가 실수해도 자동으로 되돌리지 못한다 -- 위험한 명령(파일 삭제, 강제 푸시 등)을 실행하기 전에 자동으로 차단하는 장치가 없다
- 복잡한 작업을 한 줄 명령으로 처리할 수 없다 -- 컴포넌트 생성, 페이지 구성 같은 반복 작업을 자동화하는 워크플로우가 없다
- 여러 AI가 동시에 작업하지 못한다 -- 디자인, 개발, 검증을 각각 담당하는 AI 팀 구성이 불가능하다
이 설정은 전체의 약 20%입니다. 나머지 80%(자동 검증, 자동 차단, 워크플로우 자동화, AI 팀 협업)는 3주 스터디에서 직접 만들어봅니다.