[AI] 🤖 바이브 코딩의 핵심: Claude Code 프로젝트 문서 관리 완전 가이드

110턴 대화:  이전 10턴 + 새 요청 → 토큰 적음
2100턴 대화: 이전 100턴 + 새 요청 → 토큰 많음 (10배)

1my-project/
2├── README.md        # "이 프로젝트는 뭐지?"
3├── CLAUDE.md        # "어떻게 작업해야 하지?"
4├── PLAN.md          # "무엇을 만들어야 하지?"
5├── CHANGELOG.md     # "언제 뭐가 바뀌었지?"
6├── DECISIONS.md     # "왜 이렇게 했지?"
7└── DESIGN.md        # "UI를 어떻게 만들지?" (프론트엔드 프로젝트인 경우)

 1# 프로젝트명
 2
 3## 프로젝트 개요
 4한 줄 설명
 5
 6## 📚 문서 인덱스
 7- PLAN.md: 전체 기능 설계 및 개발 일정
 8- DESIGN.md: 디자인 시스템 (프론트엔드인 경우)
 9- CHANGELOG.md: 버전별 변경 이력
10- DECISIONS.md: 중요한 기술적 결정 기록
11
12## 🎯 코딩 규칙
13(프로젝트 기술 스택에 맞는 규칙)
14
15## 📋 현재 진행 상황
16- Phase 1: ✅ 완료
17- Phase 2: 🔄 진행 중 (어디까지 했는지)
18- Phase 3: ⬜ 미시작
19
20## 🔄 작업 완료 시 자동 수행 규칙
211. CHANGELOG.md에 변경사항 추가
222. 이 파일의 진행 상황 업데이트
233. git commit 메시지 규칙: feat:, fix:, chore:, docs:
24
25## ⚠️ 알려진 이슈
26- (현재 해결 중이거나 인지하고 있는 문제들)

 1# Changelog
 2
 3## [Unreleased]
 4### Added
 5- 새로 추가된 기능
 6
 7## [1.0.0] - 2026-04-25
 8### Added
 9- 초기 출시
10### Fixed
11- 수정한 버그

1# Architecture Decisions
2
3## 001: 데이터 저장 방식
4- 날짜: 2026-04-20
5- 상태: 승인됨
6- 결정: 서버 없이 로컬 저장
7- 이유: 서버 운영비 불필요, 개인정보 미수집
8- 결과: 기기 간 동기화 불가 (v2.0에서 고려)

 1아래 지시사항을 순서대로 실행해줘.
 2
 3## 사전 파악
 4먼저 프로젝트 루트의 모든 설정 파일을 읽고
 5기술 스택, 구조, 현재 상태를 파악해.
 6
 7## 생성할 파일
 8
 9### 1. README.md
10- 프로젝트 소개, 주요 기능, 기술 스택
11- 설치 및 실행 방법
12- 뱃지 포함 (기술 스택 기반 자동 감지)
13
14### 2. CLAUDE.md
15- 문서 인덱스
16- 코딩 규칙 (기술 스택에 맞게 자동 설정)
17- 현재 진행 상황
18- 작업 완료 시 자동 수행 규칙
19
20### 3. PLAN.md
21- 프로젝트 개요
22- 핵심 기능 정의
23- 데이터 모델
24- 폴더 구조
25- Phase별 개발 일정 (체크리스트)
26
27### 4. CHANGELOG.md
28- Keep a Changelog 형식
29- 현재까지 작업 내용 기반으로 초안
30
31### 5. DECISIONS.md
32- ADR 형식
33- 프로젝트에서 파악된 기술 결정 자동 추출
34
35## 완료 후
36각 파일 생성 결과를 체크리스트로 보고

 1아래 지시사항을 순서대로 실행해줘.
 2
 3## 사전 파악
 4package.json, tsconfig.json, app.json을 읽고
 5기술 스택과 현재 프로젝트 상태를 파악해.
 6
 7## 생성할 파일
 8
 9### 1. README.md
10- 앱 소개, 주요 기능, 기술 스택
11- 설치: npm install, npx expo start
12- 뱃지: React Native, Expo, TypeScript
13
14### 2. CLAUDE.md (아래 구조로)
15- 문서 인덱스 (README, PLAN, DESIGN, CHANGELOG, DECISIONS)
16- 코딩 규칙:
17  - TypeScript strict mode
18  - 함수형 컴포넌트 + hooks
19  - StyleSheet.create 사용 (인라인 최소화)
20  - camelCase (변수), PascalCase (컴포넌트/타입)
21- 현재 진행 상황 (Phase별 체크박스)
22- 작업 완료 시: CHANGELOG 업데이트, 진행 상황 갱신
23- 커밋 규칙: feat:, fix:, chore:, docs:, refactor:
24
25### 3. PLAN.md
26- 프로젝트 개요 (목적, 플랫폼, 기술 스택)
27- 화면 구성 (탭/스택 네비게이션 구조)
28- 핵심 기능 정의 (우선순위 P0/P1/P2)
29- TypeScript interface 정의
30- 폴더 구조 (app/, components/, stores/, services/)
31- Phase별 개발 일정 (체크리스트)
32- 배포 요건 (App Store, Google Play)
33
34### 4. DESIGN.md
35- 컬러 팔레트 (hex 코드)
36- 타이포그래피 (폰트, 사이즈 스케일)
37- 간격 시스템 (4/8/12/16/24/32)
38- 모서리 둥글기 스케일
39- 컴포넌트별 규칙 (버튼, 카드, 입력 필드)
40- 애니메이션 가이드
41- 다크 모드 대응
42
43### 5. CHANGELOG.md + DECISIONS.md
44- 현재까지 작업 기반으로 초안
45
46## 완료 후 체크리스트로 보고

 1아래 지시사항을 순서대로 실행해줘.
 2
 3## 사전 파악
 4requirements.txt (또는 pyproject.toml, Pipfile),
 5main 진입점, 기존 코드 구조를 읽고 파악해.
 6
 7## 생성할 파일
 8
 9### 1. README.md
10- 프로젝트 소개, 주요 기능
11- 설치: pip install -r requirements.txt
12- 실행: python main.py 또는 uvicorn/flask 명령어
13- 환경 변수 설명 (.env.example 포함)
14- 뱃지: Python 버전, 프레임워크
15
16### 2. CLAUDE.md (아래 구조로)
17- 문서 인덱스
18- 코딩 규칙:
19  - PEP 8 준수
20  - Type hints 필수
21  - docstring: Google style
22  - 함수는 단일 책임 원칙
23  - 테스트: pytest 사용
24- 현재 진행 상황
25- 작업 완료 시: CHANGELOG 업데이트, pytest 실행
26- 커밋 규칙: feat:, fix:, chore:
27
28### 3. PLAN.md
29- 프로젝트 개요 (목적, 기술 스택)
30- 핵심 기능/모듈 정의
31- API 엔드포인트 설계 (REST/GraphQL인 경우)
32- 데이터 모델 (SQLAlchemy/Pydantic/dataclass)
33- 폴더 구조 (app/, models/, services/, utils/, tests/)
34- Phase별 개발 일정 (체크리스트)
35
36### 4. CHANGELOG.md + DECISIONS.md
37- 현재까지 작업 기반으로 초안
38
39## 완료 후 체크리스트로 보고

 1아래 지시사항을 순서대로 실행해줘.
 2
 3## 사전 파악
 4.xcodeproj 또는 Package.swift, Info.plist,
 5기존 Swift 파일 구조를 읽고 파악해.
 6
 7## 생성할 파일
 8
 9### 1. README.md
10- 앱 소개, 주요 기능, 스크린샷 섹션
11- 요구사항: Xcode 버전, iOS 최소 버전
12- 빌드: Xcode에서 열고 Run
13- 뱃지: Swift, iOS, Xcode
14
15### 2. CLAUDE.md (아래 구조로)
16- 문서 인덱스
17- 코딩 규칙:
18  - Swift API Design Guidelines 준수
19  - MVVM 또는 SwiftUI+Observable 아키텍처
20  - guard let 우선 사용 (if let보다)
21  - Protocol 기반 의존성 주입
22  - 네이밍: camelCase (프로퍼티), PascalCase (타입)
23- 현재 진행 상황
24- 작업 완료 시: CHANGELOG 업데이트, 빌드 확인
25- 커밋 규칙: feat:, fix:, chore:
26
27### 3. PLAN.md
28- 앱 개요 (목적, 타겟 iOS 버전)
29- 화면 구성 (NavigationStack/TabView 구조)
30- 핵심 기능 정의
31- 데이터 모델 (struct, Codable)
32- 폴더 구조 (Views/, Models/, ViewModels/, Services/)
33- Phase별 개발 일정
34
35### 4. DESIGN.md
36- Color Assets 정의
37- Typography 스케일
38- 컴포넌트별 규칙
39- 다크 모드 대응
40- SF Symbols 사용 가이드
41
42### 5. CHANGELOG.md + DECISIONS.md
43
44## 완료 후 체크리스트로 보고

 1아래 지시사항을 순서대로 실행해줘.
 2
 3## 사전 파악
 4build.gradle (또는 pom.xml), 기존 소스 구조,
 5application.properties를 읽고 파악해.
 6
 7## 생성할 파일
 8
 9### 1. README.md
10- 프로젝트 소개, 주요 기능
11- 요구사항: JDK 버전, Gradle/Maven
12- 빌드: ./gradlew build (또는 mvn package)
13- 실행: ./gradlew bootRun (Spring) 또는 Android Studio
14- 뱃지: Java/Kotlin, Spring Boot/Android
15
16### 2. CLAUDE.md (아래 구조로)
17- 문서 인덱스
18- 코딩 규칙:
19  - [Android] Kotlin 우선, Jetpack Compose UI
20  - [Spring] Java/Kotlin, 계층 구조 (Controller→Service→Repository)
21  - 네이밍: camelCase (메서드), PascalCase (클래스)
22  - 예외 처리: 커스텀 Exception 사용
23  - 테스트: JUnit 5 + Mockito
24- 현재 진행 상황
25- 작업 완료 시: CHANGELOG 업데이트, 빌드 확인
26- 커밋 규칙: feat:, fix:, chore:
27
28### 3. PLAN.md
29- 프로젝트 개요
30- [Android] 화면 구성 (Navigation Graph)
31- [Spring] API 엔드포인트 설계
32- 데이터 모델 (Entity, DTO)
33- 폴더 구조
34- Phase별 개발 일정
35
36### 4. CHANGELOG.md + DECISIONS.md
37
38## 완료 후 체크리스트로 보고

1실제 사고 사례:
2  1. AI가 .env의 API Key를 코드에 하드코딩
3  2. AI가 CLAUDE.md에 실제 키 값을 기록
4  3. AI가 .env 파일을 git commit에 포함
5  4. AI가 디버깅 중 콘솔에 키를 출력하는 코드 생성
6  5. AI가 README에 "실행 시 이 키를 넣으세요"라며 실제 값 노출

 1## 🔒 보안 규칙 (절대 위반 금지)
 2
 3### 환경 변수
 4- .env, .env.local 파일의 실제 값을 절대 코드나 문서에 기록하지 말 것
 5- API Key, Secret, Token, Password를 절대 하드코딩하지 말 것
 6- 환경 변수는 반드시 process.env.VARIABLE_NAME으로 참조
 7- 디버깅 시에도 console.log로 환경 변수 값을 출력하지 말 것
 8- 커밋 전 반드시 .env가 .gitignore에 포함되어 있는지 확인
 9
10### 문서에 적을 때
11- 필요한 환경 변수의 "이름"만 기록 (값은 절대 기록 금지)
12- .env.example 파일에 빈 값으로 목록만 제공
13
14### 금지 패턴
15❌ const API_KEY = "sk-abc123..."
16❌ OPENWEATHER_API_KEY=abc123  (CLAUDE.md에 실제 값)
17❌ console.log("Key:", process.env.API_KEY)
18❌ fetch(`...?key=abc123...`)
19
20### 허용 패턴
21✅ const API_KEY = process.env.OPENWEATHER_API_KEY
22✅ OPENWEATHER_API_KEY=your_key_here  (.env.example)
23✅ "환율 API Key가 필요합니다 (.env 참고)"

1# .env.example (git에 포함 OK)
2OPENWEATHER_API_KEY=your_key_here
3EXCHANGE_RATE_API_KEY=your_key_here
4GOOGLE_MAPS_API_KEY=your_key_here
5ADMOB_ANDROID_APP_ID=ca-app-pub-xxx
6ADMOB_IOS_APP_ID=ca-app-pub-xxx

1# .env (git에 절대 포함 금지)
2OPENWEATHER_API_KEY=abc123실제키값
3EXCHANGE_RATE_API_KEY=xyz789실제키값

 1# .gitignore
 2.env
 3.env.local
 4.env.production
 5.env.*.local
 6*.keystore
 7*.jks
 8*.p12
 9google-services.json
10GoogleService-Info.plist

 1## 🔑 필요한 환경 변수
 2
 3| 변수명 | 용도 | 발급처 |
 4|--------|------|--------|
 5| OPENWEATHER_API_KEY | 날씨 조회 | openweathermap.org |
 6| EXCHANGE_RATE_API_KEY | 환율 조회 | exchangerate-api.com |
 7| GOOGLE_MAPS_API_KEY | 지도 (Android) | Google Cloud Console |
 8
 9⚠️ 실제 값은 .env 파일에만 저장. 이 문서에 절대 기록 금지.
10⚠️ .env.example 참고하여 로컬에 .env 파일 생성할 것.

1# Python
2import os
3API_KEY = os.environ.get("OPENWEATHER_API_KEY")
4# 또는 python-dotenv 사용
5from dotenv import load_dotenv
6load_dotenv()

1// TypeScript / React Native
2const API_KEY = process.env.EXPO_PUBLIC_OPENWEATHER_API_KEY;
3// Expo에서는 EXPO_PUBLIC_ 접두사 필요

1// Swift (iOS)
2let apiKey = ProcessInfo.processInfo.environment["OPENWEATHER_API_KEY"]
3// 또는 xcconfig 파일 사용

1// Java / Kotlin (Android)
2String apiKey = BuildConfig.OPENWEATHER_API_KEY;
3// build.gradle에서 local.properties 참조

11. 즉시 해당 서비스에서 키 재발급 (기존 키 비활성화)
22. git 히스토리에서 제거:
3   git filter-branch 또는 BFG Repo-Cleaner 사용
43. GitHub에서 "Secret scanning alert" 확인
54. .gitignore에 .env 추가 확인
65. 새 키로 .env 업데이트

1세션 A (짧은 세션 3개):
2  세션 1: 20턴 → 20턴분 토큰
3  세션 2: 15턴 → 15턴분 토큰
4  세션 3: 10턴 → 10턴분 토큰
5
6세션 B (긴 세션 1개):
7  45턴 → 1+2+3+...+45 = 누적 1,035턴분 토큰
8  (이전 대화가 매번 재처리되므로)

 1작업 단위로 세션 분리 (가장 중요):
 2  오전: "체크리스트 버그 수정" → exit
 3  오후: "지도 탭 구현" → exit (새 세션)
 4  저녁: "문서 정리" → exit (새 세션)
 5
 6긴 세션은 /compact로 압축:
 7  작업 중 대화가 20턴 넘어가면
 8  /compact 실행 → 이전 내용 요약 → 토큰 절약
 9
10/resume으로 이전 세션 이어하기:
11  claude --resume → 세션 목록에서 선택
12
13effort 레벨 조절:
14  /effort low    → 오타 수정, 텍스트 변경
15  /effort medium → 일반 기능 구현 (기본값)
16  /effort high   → 복잡한 로직, 멀티파일 작업
17  /effort max    → 아키텍처 설계, 풀리지 않는 디버깅

1끊어야 할 때:
2  ✅ 하나의 작업/이슈가 완료됐을 때
3  ✅ 다른 주제로 넘어갈 때
4  ✅ 대화가 20~30턴 이상 길어졌을 때
5
6유지해야 할 때:
7  🔄 같은 파일을 연속 수정 중일 때
8  🔄 디버깅이 진행 중일 때
9  🔄 관련된 작업을 연속으로 할 때

1mkdir -p ~/.claude/commands

 1# 프로젝트 문서 초기화
 2
 3이 프로젝트에 다음 문서 구조를 생성해줘.
 4실행 전 설정 파일들을 읽고 기술 스택을 파악할 것.
 5
 6## 생성할 파일
 71. README.md (프로젝트 소개, 기술 스택, 설치 방법)
 82. CLAUDE.md (문서 인덱스, 코딩 규칙, 진행 상황, 자동 수행 규칙)
 93. PLAN.md (기능 설계, 데이터 모델, 폴더 구조, 개발 일정)
104. CHANGELOG.md (Keep a Changelog 형식)
115. DECISIONS.md (ADR 형식)
12
13## 규칙
14- 기술 스택은 설정 파일에서 자동 감지
15- 코딩 규칙은 기술 스택에 맞게 자동 설정
16- 기존 파일이 있으면 덮어쓰지 말고 병합 제안
17
18## 완료 후
19생성 결과를 체크리스트로 보고

1cd any-project
2claude
3/init-docs

 1# 프로젝트 상태 점검
 2
 3현재 프로젝트 상태를 점검하고 보고해줘.
 4
 5## 점검 항목
 61. CLAUDE.md의 진행 상황이 실제 코드와 일치하는지
 72. CHANGELOG.md가 최신인지
 83. 알려진 버그나 TODO가 남아있는지
 94. 빌드/테스트가 정상적으로 통과하는지
105. 다음으로 해야 할 작업이 뭔지
11
12## 보고 형식
13- 현재 상태 요약
14- 불일치 항목 (있으면)
15- 다음 작업 추천

 1# 문서 정리
 2
 3프로젝트의 모든 문서를 점검하고 정리해줘.
 4
 5## 작업
 61. 중복된 내용 통합
 72. 오래되어 관련 없어진 내용 제거
 83. 각 문서의 역할이 명확한지 확인
 94. 문서 간 링크가 올바른지 확인
105. 필요하면 새 문서 분리 제안
11
12## 대상 파일
13README.md, CLAUDE.md, PLAN.md, CHANGELOG.md, DECISIONS.md

1touch ~/.claude/CLAUDE.md

 1# 글로벌 Claude Code 규칙
 2
 3## 모든 프로젝트 공통
 4
 5### 문서 규칙
 6- README.md, CLAUDE.md, CHANGELOG.md는 필수
 7- 작업 완료 시 CHANGELOG.md 업데이트
 8- 중요한 결정은 DECISIONS.md에 기록
 9
10### 커밋 메시지
11- feat: 새 기능
12- fix: 버그 수정
13- chore: 설정, 의존성
14- docs: 문서 변경
15- refactor: 리팩토링
16
17### 작업 스타일
18- 큰 작업은 작은 단계로 나눠서 진행
19- 각 단계 완료 후 git commit
20- 불확실한 부분은 먼저 질문하고 진행

1CLAUDE.md: 200줄 이하 (허브 역할, 짧게)
2PLAN.md:   500줄 이하 (넘으면 기능별 분리)
3DESIGN.md: 300줄 이하
4CHANGELOG: 제한 없음 (시간순 누적)
5DECISIONS: 제한 없음 (결정순 누적)

1# PLAN.md
2상세 디자인은 [DESIGN.md](./DESIGN.md) 참고.
3AdMob 연기 결정은 [DECISIONS.md](./DECISIONS.md#003) 참고.

1체크리스트 버그 수정 완료했어.
2CHANGELOG.md에 추가하고,
3CLAUDE.md 진행 상황도 업데이트해줘.

1PLAN.md의 Phase 3 섹션만 읽고,
2예산 탭의 환율 변환 기능을 구현해줘.

 1문서가 없는 AI 개발:
 2  매 세션마다 처음부터 설명
 3  → 토큰 낭비
 4  → 일관성 없는 코드
 5  → 매번 다른 스타일
 6
 7문서가 있는 AI 개발:
 8  새 세션에서도 즉시 맥락 파악
 9  → 토큰 절약
10  → 일관된 코드
11  → 누적되는 품질

1cd my-project
2claude
3/init-docs