Claude.md가 개발 프로세스를 혁신하는 방법
Claude Code의 에이전트를 이용한 프로젝트를 진행하다 보면 개발자들은 수많은 문서와 코드 사이에서 길을 잃곤 합니다. 특히 AI 어시스턴트와 협업할 때는 프로젝트의 맥락을 매번 설명해야 하는 번거로움이 있었습니다. 이러한 문제를 해결하기 위해 등장한 것이 바로 claude.md 파일입니다. Claude.md는 프로젝트의 DNA와 같은 역할을 하며, 기획부터 배포까지 전체 개발 사이클에서 일관된 가이드라인을 제공합니다. 이 문서 하나로 AI는 프로젝트의 목표, 구조, 규칙을 즉시 이해하고 더 정확한 도움을 제공할 수 있게 됩니다.
Claude.md는 단순한 README 파일이 아닙니다.
이것은 프로젝트의 모든 단계에서 참조되는 살아있는 문서로, 개발 방향성을 제시하고 일관성을 유지하며 팀원 간의 커뮤니케이션을 원활하게 만듭니다. 초보 개발자부터 숙련된 엔지니어까지, 모든 이가 프로젝트의 전체 그림을 한눈에 파악할 수 있도록 돕습니다. 본 가이드에서는 '블로그 사이트 구축'이라는 실제 프로젝트를 예시로 claude.md의 모든 것을 단계별로 살펴보겠습니다.
| Claude.md는 단순한 README 문서가 아니라 프로젝트를 관리하고 유지하는 핵심 문서입니다. |
|
[ 차례 ]
|
1. 프로젝트 기획 단계의 Claude.md 활용
Claude.md의 필수 구성요소
프로젝트 기획 단계에서 claude.md의 기본 골격을 만드는 것은 매우 중요합니다. 필수 구성요소는 프로젝트의 정체성을 정의하며, 이후 모든 개발 작업의 나침반 역할을 합니다.
1) 프로젝트 개요 | Project Overview
여기에는 프로젝트의 목적, 목표 사용자, 핵심 가치 제안이 명확하게 기술되어야 합니다. 예를 들어 블로그 사이트의 경우, "개발자들이 기술 지식을 공유하고 소통할 수 있는 마크다운 기반의 경량 블로그 플랫폼"과 같이 한 문장으로 프로젝트의 본질을 표현합니다.
2) 기술 스텍 | Technical Stack
사용할 프로그래밍 언어, 프레임워크, 데이터베이스, 그리고 주요 라이브러리를 명시합니다. 블로그 프로젝트에서는
### Tech Stack
- Frontend : React 18, TypeScript, Tailwind CSS
- Backend : Node.js, Express, MongoDB
- Deployment : Vercel, MongoDB Atlas
와 같이 구체적으로 작성합니다. 이렇게 하면 AI 어시스턴트가 코드 작성 시 적절한 문법과 패턴을 사용할 수 있습니다. 기술 스택 선정 이유도 간략하게 덧붙이면 향후 의사결정에 도움이 됩니다.
3) 시스템 아키텍처 개요 | System Architecture
기본적인 claude.md에는 전체 시스템 구조를 간단한 다이어그램으로 표현합니다.
### System Architecture
Client (React SPA) ↔ API Server (Express) ↔ MongoDB / Cloudinary (Images)
위의 코드블럭처럼 주요 컴포넌트 간의 관계를 시각화합니다. 이는 개발자가 시스템 전체를 한눈에 파악하고, AI가 어느 레이어의 코드를 작성할지 이해하는 데 도움이 됩니다. 상세한 아키텍처는 별도 문서로 분리할 수 있지만, 핵심 구조는 claude.md에 포함되어야 합니다.
4) 데이터베이스 스키마 | Database Schema
각 컬렉션이나 테이블의 핵심 필드와 관계를 간략히 정의합니다. "Users: email(unique), passwordHash, username(unique) / Posts: title, slug(unique), content, tags[], authorId(ref: Users)"처럼 주요 필드와 제약조건을 명시합니다. 인덱스 정보도 함께 기록하여 "email, username, slug는 unique 인덱스, tags는 배열 인덱스"처럼 성능 최적화 전략을 포함합니다. 이렇게 하면 AI가 데이터 모델이나 쿼리를 작성할 때 정확한 스키마를 참조할 수 있습니다.
5) 핵심 API 엔드포인트 | Core API Endpoints
주요 API의 메서드, 경로, 간단한 설명을 나열합니다.
- POST /api/auth/register - 회원가입
- POST /api/auth/login - 로그인
- GET /api/posts - 글 목록 (pagination)
- POST /api/posts - 글 작성 (인증 필요)
처럼 기본 정보만 포함합니다. 상세한 요청/응답 형식은 별도 API 명세 문서로 분리하되, claude.md에는 전체 API 구조를 파악할 수 있는 요약이 있어야 합니다. 이는 프론트엔드와 백엔드 개발자 모두에게 유용한 참조 자료가 됩니다.
6) 프로젝트 구조 | Project Structure
디렉토리 구조를 트리 형태로 시각화하여 파일과 폴더의 역할을 명확히 합니다. 예를 들어 "/src/components (재사용 가능한 UI 컴포넌트), /src/pages (라우트별 페이지 컴포넌트), /src/api (백엔드 API 엔드포인트), /src/utils (유틸리티 함수)"와 같이 각 디렉토리의 목적을 설명합니다. 이는 새로운 팀원이나 AI가 어디에 어떤 코드를 작성해야 할지 즉시 파악하도록 돕습니다.
7) 개발 규칙 | Development Rules
코딩 컨벤션, 네이밍 규칙, 커밋 메시지 형식 등을 정의합니다. "함수명은 camelCase, 컴포넌트는 PascalCase 사용", "커밋 메시지는 feat/fix/docs/style 접두어 사용", "모든 함수에 JSDoc 주석 작성" 같은 구체적인 규칙을 명시합니다. 이러한 규칙은 코드의 일관성을 유지하고 협업을 원활하게 만듭니다. 규칙이 명확할수록 AI 어시스턴트도 프로젝트 스타일에 맞는 코드를 생성할 수 있습니다.
Claude.md 기본 버전 - [블로그 프로젝트] 예시 보기
# Blog Site Project
## Project Overview
- **Purpose**: 개발자들을 위한 마크다운 기반 블로그 플랫폼
- **Target Users**: 기술 블로거, 개발자 커뮤니티
- **Core Value**: 빠른 글 작성, 코드 하이라이팅, SEO 최적화
## Tech Stack
- Frontend: React 18.2, TypeScript 5.0, Tailwind CSS 3.3
- Backend: Node.js 20, Express 4.18, MongoDB 6.0
- Authentication: JWT, bcrypt
- Deployment: Vercel (Frontend), Railway (Backend)
## Project Structure
```
/blog-site
├── /client
│ ├── /src
│ │ ├── /components (재사용 UI 컴포넌트)
│ │ ├── /pages (라우트별 페이지)
│ │ ├── /hooks (커스텀 React 훅)
│ │ └── /utils (유틸리티 함수)
├── /server
│ ├── /routes (API 라우트)
│ ├── /models (데이터베이스 모델)
│ └── /middleware (미들웨어)
└── /docs (프로젝트 문서)
```
## System Architecture (간략)
```
Client (React) ↔ API Server (Express) ↔ MongoDB
↓
Cloudinary (Images)
```
## Database Schema (핵심)
- **Users**: email, passwordHash, username, avatar
- **Posts**: title, slug, content(markdown), tags, authorId
- **Indexes**: email(unique), username(unique), slug(unique), tags
## API Endpoints (핵심)
- POST /api/auth/register - 회원가입
- POST /api/auth/login - 로그인
- GET /api/posts - 글 목록 (pagination)
- POST /api/posts - 글 작성 (인증 필요)
- GET /api/posts/:slug - 글 상세
## Development Rules
- 함수명: camelCase, 컴포넌트: PascalCase
- 커밋 메시지: `feat: 새 기능`, `fix: 버그 수정`
- 모든 컴포넌트는 TypeScript로 작성
- API 응답은 항상 {success, data, error} 형식 사용옵션 구성요소로 프로젝트 완성도 높이기
필수 구성요소 외에도 프로젝트를 더욱 체계적으로 관리하기 위한 옵션 구성요소들이 있습니다.
8) 기능명세 | Feature Specifications
구현할 주요 기능을 우선순위와 함께 상세히 기술합니다. 블로그 프로젝트의 경우 "MVP 기능: 글 작성/편집/삭제, 마크다운 지원, 사용자 인증 / Phase 2: 댓글 시스템, 태그 검색, 이미지 업로드 / Phase 3: 소셜 공유, RSS 피드, 다국어 지원"과 같이 단계별로 나눕니다. 이렇게 하면 개발 우선순위를 명확히 하고 점진적으로 기능을 추가할 수 있습니다.
9) 디자인 가이드라인 | Design Guidelines
UI/UX 원칙, 색상 팔레트, 타이포그래피, 컴포넌트 스타일 등을 정의합니다. "Primary Color: #3B82F6 (파란색), Secondary: #10B981 (초록색), 폰트: Pretendard (한글), Inter (영문), 버튼 높이: 40px, 모서리: 8px radius"처럼 구체적으로 명시합니다. 이는 디자인 일관성을 유지하고 AI에게 UI 컴포넌트 생성을 요청할 때 프로젝트 스타일에 맞는 결과를 얻는 데 도움이 됩니다.
10) API 명세 | API Specifications
백엔드 엔드포인트, 요청/응답 형식, 인증 방법 등을 문서화합니다. "POST /api/posts - 새 글 작성 (인증 필요), 요청: {title, content, tags}, 응답: {id, createdAt} / GET /api/posts/:id - 글 조회, 응답: {post, author, comments}"와 같이 각 API의 역할을 명확히 합니다. 이렇게 하면 프론트엔드와 백엔드 개발을 병렬로 진행할 수 있고, AI가 API 호출 코드를 작성할 때 정확한 형식을 사용할 수 있습니다.
11) 시험 전략 | Testing Strategy
단위 테스트, 통합 테스트, E2E 테스트 계획을 수립합니다. "Jest + React Testing Library로 컴포넌트 테스트, Supertest로 API 테스트, Cypress로 E2E 테스트, 커버리지 목표 80% 이상"처럼 구체적인 도구와 목표를 명시합니다. 테스트 전략을 초기에 정의하면 코드 품질을 높이고 버그를 조기에 발견할 수 있습니다. AI에게 테스트 코드 작성을 요청할 때도 프로젝트의 테스트 방침에 맞는 코드를 받을 수 있습니다.
12) 상세 아키텍처 설계 | Detailed Architecture
기본 개요를 넘어 각 레이어의 역할과 데이터 흐름을 상세히 기술합니다. "프레젠테이션 계층: React 컴포넌트, 라우팅 / 비즈니스 로직 계층: Express 컨트롤러, 서비스 / 데이터 액세스 계층: Mongoose 모델, 쿼리 최적화"처럼 계층별 책임을 명확히 합니다. 각 계층 간 통신 방식, 에러 처리 전략, 캐싱 전략도 포함합니다. 이렇게 하면 AI가 특정 기능을 구현할 때 올바른 계층에 코드를 배치하고 적절한 패턴을 사용할 수 있습니다.
13) 완전한 데이터베이스 명세 | Complete Database Sepcification
각 필드의 타입, 제약조건, 기본값, 검증 규칙을 상세히 정의합니다. "Users.email: String, required, unique, lowercase, email validation / Users.passwordHash: String, required, bcrypt with 10 salt rounds / Posts.tags: [String], max 5 items, indexed for search"처럼 구현에 필요한 모든 정보를 포함합니다. 인덱스 전략도 "compound index on {published: 1, publishedAt: -1} for homepage query"처럼 사용 목적과 함께 명시합니다. 데이터베이스 마이그레이션 전략과 백업 정책도 추가하면 운영 단계에서 유용합니다.
14) 완전한 API 명세 | Complete API Specification
각 엔드포인트의 요청 본문, 쿼리 파라미터, 헤더, 응답 형식, 에러 코드를 상세히 문서화합니다. "GET /api/posts?page=1&limit=10&tag=react : 응답 {posts: [], pagination: {currentPage, totalPages, hasMore}} / 에러: 400 (invalid params), 401 (unauthorized)"처럼 실제 API 호출에 필요한 모든 정보를 제공합니다. 인증이 필요한 엔드포인트는 별도로 표시하고, Rate Limiting 정책도 명시합니다. 이는 프론트엔드 개발자가 API를 호출하거나, AI가 API 클라이언트 코드를 작성할 때 완벽한 가이드가 됩니다.
Claude.md 확장 구성 요소 예시
# Blog Site Project - Extended Configuration
## Feature Specifications
### MVP (Phase 1) - 4주
- 사용자 인증 (회원가입, 로그인, JWT)
- 글 작성/편집/삭제 (마크다운 에디터)
- 글 목록 조회 (페이지네이션)
- 반응형 레이아웃
### Phase 2 - 2주
- 댓글 시스템 (작성, 수정, 삭제)
- 태그 기반 검색 및 필터링
- 이미지 업로드 (Cloudinary)
### Phase 3 - 2주
- 소셜 미디어 공유
- RSS 피드 생성
- 다크 모드 지원
## Design Guidelines
- **Color Palette**
- Primary: #3B82F6 (블루)
- Secondary: #10B981 (그린)
- Background: #F9FAFB (라이트), #1F2937 (다크)
- **Typography**
- Headings: Pretendard Bold
- Body: Pretendard Regular
- Code: Fira Code
- **Spacing**: 8px 기본 단위 (8, 16, 24, 32, 48)
- **Components**: Material-UI 스타일 적용
## API Specifications
### Authentication
- POST /api/auth/register - 회원가입
- Body: {email, password, username}
- Response: {token, user}
- POST /api/auth/login - 로그인
- Body: {email, password}
- Response: {token, user}
### Posts
- GET /api/posts - 글 목록 (쿼리: page, limit, tag)
- POST /api/posts - 글 작성 (인증 필요)
- GET /api/posts/:id - 글 상세 조회
- PUT /api/posts/:id - 글 수정 (작성자만)
- DELETE /api/posts/:id - 글 삭제 (작성자만)
## Testing Strategy
- Unit Tests: Jest + React Testing Library
- API Tests: Supertest + MongoDB Memory Server
- E2E Tests: Cypress
- Coverage Goal: 80% 이상
- CI/CD: GitHub Actions로 자동 테스트 실행Claude.md 구성요소 우선순위 가이드 - 예시
# Claude.md 구성요소 우선순위 가이드
## 구성요소 중요도 및 작업 순서
### 필수 구성요소 (Priority 1) - 프로젝트 시작 즉시 작성
프로젝트를 시작하자마자 반드시 작성해야 하는 핵심 요소들입니다.
#### 1. 프로젝트 개요 (Project Overview)
**작업 순서**: 1순위
**중요도**: ★★★★★
**이유**:
- 프로젝트의 목적과 방향성 정의
- 팀원과 AI가 가장 먼저 이해해야 할 내용
- 모든 의사결정의 기준점
**포함 내용**:
- 프로젝트 목적
- 타겟 사용자
- 핵심 가치 제안
- 프로젝트 목표 (단기/중기/장기)
---
#### 2. 기술 스택 (Tech Stack)
**작업 순서**: 2순위
**중요도**: ★★★★★
**이유**:
- 개발 환경 설정의 기초
- AI가 코드 생성 시 필수 정보
- 기술 선정 이유 문서화로 향후 변경 시 참고
**포함 내용**:
- Frontend/Backend 프레임워크
- 프로그래밍 언어 및 버전
- 주요 라이브러리
- 인프라 및 배포 플랫폼
- 기술 선정 이유
---
#### 3. 시스템 아키텍처 개요 (System Architecture)
**작업 순서**: 3순위
**중요도**: ★★★★★
**이유**:
- 시스템 전체 구조 이해
- 컴포넌트 간 관계 파악
- 새 기능 추가 시 어디에 배치할지 결정
**포함 내용**:
- 간단한 아키텍처 다이어그램
- 주요 컴포넌트 (Client, Server, Database)
- 컴포넌트 간 통신 방식
- 기본 데이터 흐름
---
#### 4. 데이터베이스 스키마 (Database Schema)
**작업 순서**: 4순위
**중요도**: ★★★★★
**이유**:
- 데이터 구조가 전체 애플리케이션의 기반
- Backend와 Frontend 모두 참조
- 변경 비용이 높아 초기 설계 중요
**포함 내용**:
- 주요 테이블/컬렉션 구조
- 핵심 필드와 타입
- 관계 (1:N, N:M)
- 인덱스 전략
- 제약조건 (unique, required 등)
---
#### 5. 핵심 API 엔드포인트 (Core API Endpoints)
**작업 순서**: 5순위
**중요도**: ★★★★★
**이유**:
- Frontend-Backend 계약 역할
- 병렬 개발 가능하게 함
- API 변경 시 영향 범위 파악
**포함 내용**:
- 주요 엔드포인트 목록
- HTTP 메서드
- 간단한 요청/응답 형식
- 인증 필요 여부
---
#### 6. 프로젝트 구조 (Project Structure)
**작업 순서**: 6순위
**중요도**: ★★★★★
**이유**:
- 파일 배치 일관성
- 새 파일 생성 시 위치 결정
- 코드 탐색 용이성
**포함 내용**:
- 디렉토리 트리
- 각 폴더의 역할
- 파일 명명 규칙
---
#### 7. 개발 규칙 (Development Rules)
**작업 순서**: 7순위
**중요도**: ★★★★★
**이유**:
- 코드 일관성 유지
- 협업 효율성
- AI 코드 생성 품질 향상
**포함 내용**:
- 코딩 컨벤션
- 네이밍 규칙
- 커밋 메시지 규칙
- 코드 리뷰 기준
---
### 권장 구성요소 (Priority 2) - 개발 초기에 작성
프로젝트 초기 단계에서 작성하면 개발이 원활해지는 요소들입니다.
#### 8. 기능 명세 (Feature Specifications)
**작업 순서**: 8순위
**중요도**: ★★★★
**시기**: 설계 단계 초기
**이유**:
- 개발 범위 명확화
- 우선순위 결정
- Phase 별 계획 수립
---
#### 9. 요구사항 분석 (Requirements Analysis)
**작업 순서**: 9순위
**중요도**: ★★★★
**시기**: 설계 단계
**이유**:
- 기능적/비기능적 요구사항 명확화
- 제약사항과 가정 문서화
- 사용자 스토리로 기능 이해
---
#### 10. 인증 및 보안 정책 (Authentication & Security)
**작업 순서**: 10순위
**중요도**: ★★★★★
**시기**: 설계 단계
**이유**:
- 보안은 나중에 추가하기 어려움
- 아키텍처 전반에 영향
- 데이터 보호 필수
---
#### 11. 상세 API 명세 (Detailed API Specification)
**작업 순서**: 11순위
**중요도**: ★★★★
**시기**: 구현 단계 전
**이유**:
- 정확한 API 계약
- 에러 처리 명확화
- Postman/Swagger 문서 기초
---
#### 12. 디자인 가이드라인 (Design Guidelines)
**작업 순서**: 12순위
**중요도**: ★★★
**시기**: UI 개발 전
**이유**:
- 일관된 UI/UX
- 디자인 토큰 정의
- 컴포넌트 재사용성
---
### 선택 구성요소 (Priority 3) - 개발 중 필요시 작성
개발이 진행되면서 필요에 따라 추가하는 요소들입니다.
#### 13. 테스트 전략 (Testing Strategy)
**작업 순서**: 13순위
**중요도**: ★★★★
**시기**: 구현 단계 초기
**이유**:
- 코드 품질 보장
- 리팩토링 안전성
- 버그 조기 발견
---
#### 14. 작업 관리 (Task Management)
**작업 순서**: 14순위
**중요도**: ★★★
**시기**: 구현 단계
**이유**:
- 진행 상황 추적
- 일정 관리
- 의존성 파악
---
#### 15. 배포 전략 (Deployment Strategy)
**작업 순서**: 15순위
**중요도**: ★★★
**시기**: 구현 중반~후반
**이유**:
- 배포 자동화
- 환경 관리
- 롤백 계획
---
#### 16. 버전 관리 전략 (Version Management)
**작업 순서**: 16순위
**중요도**: ★★★
**시기**: 프로젝트 전반
**이유**:
- 문서 변경 추적
- 변경 이유 기록
- 이력 관리
---
#### 17. 변경 요청 관리 (Change Request Management)
**작업 순서**: 17순위
**중요도**: ★★★
**시기**: 프로젝트 진행 중
**이유**:
- 범위 관리
- 영향 분석
- 의사결정 기록
---
#### 18. 문서 생태계 연계 (Documentation Ecosystem)
**작업 순서**: 18순위
**중요도**: ★★
**시기**: 프로젝트 성숙 단계
**이유**:
- 대규모 프로젝트 관리
- 문서 간 일관성
- 지식 체계화
각 단계별 작성 체크리스트 작성을 다음과 같이 추가하는게 좋습니다. Claude Code는 체크리스트에 대하여 내부적으로 TODO목록을 작성하여 체계적으로 작업의 진행순서를 결정합니다.
Claude.md 단계별 작성 체크리스트 - 예시
## 단계별 작성 체크리스트
### Phase 1: 프로젝트 시작 (Day 1-2)
```
[ ] 1. 프로젝트 개요
[ ] 2. 기술 스택
[ ] 3. 시스템 아키텍처 (간략)
[ ] 6. 프로젝트 구조
[ ] 7. 개발 규칙 (기본)
```
**목표**: AI와 팀원이 프로젝트를 이해하고 개발 시작 가능
---
### Phase 2: 설계 단계 (Week 1)
```
[ ] 4. 데이터베이스 스키마
[ ] 5. 핵심 API 엔드포인트
[ ] 8. 기능 명세 (MVP)
[ ] 9. 요구사항 분석
[ ] 10. 인증 및 보안 정책
```
**목표**: 구현을 위한 기술적 기반 완성
---
### Phase 3: 개발 준비 (Week 1-2)
```
[ ] 11. 상세 API 명세
[ ] 12. 디자인 가이드라인
[ ] 13. 테스트 전략
```
**목표**: 개발 시작 전 세부 사항 정리
---
### Phase 4: 개발 진행 (Week 2-6)
```
[ ] 14. 작업 관리
[ ] 15. 배포 전략 (초안)
[ ] 16. 버전 관리 전략
[ ] 17. 변경 요청 관리
```
**목표**: 개발 과정 관리 및 문서화
---
### Phase 5: 성숙 단계 (Week 7+)
```
[ ] 15. 배포 전략 (완성)
[ ] 18. 문서 생태계 연계
[ ] 상세 아키텍처 문서
[ ] 트러블슈팅 가이드
```
**목표**: 운영 및 유지보수 준비
프로젝트 규모에 따라서 CLAUDE.md안에도 포함되는 것과 제외해도 되는 것들이 있을 수 있습니다.
Claude.md 프로젝트 규모별 최소 구성 - 예시
## 프로젝트 규모별 최소 구성
### 소규모 프로젝트 (1-2주, 1-2명)
```
필수:
- 프로젝트 개요
- 기술 스택
- 시스템 아키텍처 (간략)
- 데이터베이스 스키마
- 핵심 API 엔드포인트
선택:
- 개발 규칙
- 프로젝트 구조
```
---
### 중규모 프로젝트 (1-3개월, 3-5명)
```
필수:
- Phase 1 전체 (프로젝트 시작)
- Phase 2 전체 (설계 단계)
- 상세 API 명세
- 테스트 전략
권장:
- 디자인 가이드라인
- 작업 관리
- 배포 전략
```
---
### 대규모 프로젝트 (6개월+, 5명+)
```
필수:
- Phase 1-4 전체
- 완전한 아키텍처 문서
- 완전한 API 명세
- 상세 테스트 전략
- CI/CD 파이프라인
- 문서 생태계 연계
권장:
- 별도 문서 시스템 (Confluence, Notion)
- API 문서 자동화 (Swagger)
- 아키텍처 결정 기록 (ADR)
```
CLAUDE.md의 작성 순서 또는 유의사항에 대한 가이드를 참고하는 것도 매우 유익합니다.
Claude.md 작성 순서 주의사항 - 예시
## 작성 순서 주의사항
### 1. 순서를 지키는 것이 중요한 이유
- **의존성**: 아키텍처 없이 API 설계 어려움
- **효율성**: 스키마 없이 코드 작성하면 수정 많아짐
- **일관성**: 기본 규칙 없이 코드 작성하면 나중에 정리 필요
### 2. 유연하게 조정 가능
- 프로젝트 특성에 따라 순서 변경 가능
- 예: API 우선 프로젝트는 API 명세를 먼저 작성
- 예: 데이터 중심 프로젝트는 DB 스키마를 먼저 작성
### 3. 점진적 작성
- 모든 섹션을 처음부터 완벽하게 작성할 필요 없음
- 핵심만 먼저 작성하고 개발하면서 보완
- 중요한 것은 **시작하는 것**
### 4. AI 활용 팁
```
"claude.md의 1-7번 필수 구성요소를 작성해줘"
"데이터베이스 스키마를 정의한 후 API 엔드포인트를 설계해줘"
"Phase 1 체크리스트 항목들을 순서대로 작성해줘"
```
---
## 실전 예시: 블로그 프로젝트 작성 순서
### Day 1 (2시간)
1. 프로젝트 개요 작성 (30분)
2. 기술 스택 결정 및 작성 (30분)
3. 간단한 아키텍처 다이어그램 (30분)
4. 기본 프로젝트 구조 (30분)
### Day 2 (3시간)
5. Users, Posts 스키마 설계 (1시간)
6. 핵심 API 5개 정의 (1시간)
7. 기본 개발 규칙 (1시간)
**결과**: 개발 시작 가능한 최소 문서 완성
### Week 1 (추가 4시간)
8. 상세 API 명세 작성
9. 인증 방식 정의
10. 기능 명세서 작성
**결과**: 본격적인 개발을 위한 완전한 설계 문서
---
## 학습 곡선별 권장사항
### 초보 개발자
**시작**: 1-7번 필수만 집중
**점진적 추가**: 개발하면서 필요할 때 추가
**AI 활용**: "claude.md를 참고해서 ○○ 구현해줘"
### 중급 개발자
**시작**: 1-12번까지 체계적으로 작성
**병렬 작업**: 문서 작성과 개발 병행
**AI 활용**: 문서 기반 아키텍처 리뷰 요청
### 고급 개발자
**시작**: 전체 문서 체계 설계
**템플릿화**: 프로젝트별 템플릿 구축
**AI 활용**: 복잡한 아키텍처 결정 논의
---
이 가이드를 따르면 프로젝트 규모와 팀 수준에 맞는
효율적인 claude.md를 작성할 수 있습니다!2. 분석 단계에서의 Claude.md 활용
요구사항 분석과 문서화
"요구사항 분석은 프로젝트의 명확한 방향을 설정하는 핵심 단계입니다"
기능적 요구사항(Functional Requirements)과 비기능적 요구사항(Non-functional Requirements)을 명확히 구분하여 작성합니다.
- 기능적 요구사항에는 "사용자는 마크다운 형식으로 글을 작성할 수 있어야 한다", "관리자는 모든 글을 삭제할 수 있어야 한다"처럼 시스템이 제공해야 할 구체적인 기능을 나열합니다. 각 요구사항에는 고유 ID를 부여하여 나중에 추적 가능하게 만듭니다.
- 비기능적 요구사항에는 성능, 보안, 확장성, 사용성 등의 품질 속성을 명시합니다. "페이지 로딩 속도는 3초 이내", "동시 접속자 1000명 처리 가능", "HTTPS 필수 적용", "WCAG 2.1 AA 수준 접근성 준수"와 같이 측정 가능한 기준을 설정합니다.
이러한 요구사항은 아키텍처 설계와 기술 선택에 직접적인 영향을 미칩니다. AI에게 최적화된 코드를 요청할 때도 이런 기준을 참조하게 됩니다.
사용자 스토리(User Stories)를 작성하여 각 기능의 목적과 가치를 명확히 합니다.
"개발자로서, 나는 코드 스니펫을 하이라이팅하여 보여주고 싶다. 왜냐하면 독자가 코드를 더 쉽게 이해할 수 있기 때문이다"처럼 "~로서, 나는 ~하고 싶다, 왜냐하면 ~이기 때문이다" 형식을 사용합니다. 각 스토리에는 수락 기준(Acceptance Criteria)을 추가하여 언제 완료된 것으로 볼지 정의합니다. 이는 개발 완료 여부를 객관적으로 판단하는 기준이 됩니다.
제약사항(Constraints)과 가정(Assumptions)도 명시적으로 기록합니다.
"개발 기간 8주, 예산 제한으로 유료 서비스 최소화", "사용자는 최신 브라우저 사용 가정", "초기 트래픽은 하루 1000명 이하 예상"처럼 프로젝트의 경계 조건을 정의합니다. 이러한 제약사항은 의사결정의 기준이 되며, 향후 요구사항 변경 시 영향 범위를 파악하는 데 도움이 됩니다. Claude.md에 이를 명확히 기록하면 AI와 협업할 때 실현 가능한 범위 내에서 솔루션을 제안받을 수 있습니다.
CLAUDE.md - 요구사항 분석 문서 보기
# Blog Site Project - 요구사항 분석
## Functional Requirements
**FR-001: 사용자 인증**
- 사용자는 이메일과 비밀번호로 회원가입할 수 있다
- 사용자는 로그인하여 인증 토큰을 받을 수 있다
- 사용자는 로그아웃할 수 있다
- Priority: High | Status: Planned
**FR-002: 글 작성**
- 인증된 사용자는 마크다운 형식으로 글을 작성할 수 있다
- 실시간 마크다운 프리뷰를 제공한다
- 태그를 최대 5개까지 추가할 수 있다
- Priority: High | Status: Planned
**FR-003: 글 관리**
- 작성자는 자신의 글을 수정/삭제할 수 있다
- 모든 사용자는 공개된 글을 조회할 수 있다
- 글 목록은 페이지네이션으로 제공된다
- Priority: High | Status: Planned
## Non-functional Requirements
**NFR-001: 성능**
- 페이지 초기 로딩: 3초 이내
- API 응답 시간: 500ms 이내
- 동시 접속자: 1000명 처리 가능
**NFR-002: 보안**
- HTTPS 통신 필수
- 비밀번호는 bcrypt로 암호화 (salt rounds 10)
- JWT 토큰 만료 시간: 24시간
- XSS, CSRF 방어 적용
**NFR-003: 사용성**
- 모바일 반응형 지원 (320px 이상)
- 주요 액션 3클릭 이내 접근
- 로딩 상태 시각적 피드백 제공
## User Stories
**US-001: 글 작성**
- As a: 블로거
- I want to: 마크다운으로 글을 작성하고 싶다
- So that: 코드와 텍스트를 효율적으로 작성할 수 있다
- Acceptance Criteria:
- 마크다운 에디터 제공
- 실시간 프리뷰 동기화
- 코드 블록 syntax highlighting
- 이미지 삽입 지원
**US-002: 글 검색**
- As a: 독자
- I want to: 태그로 관심 있는 글을 찾고 싶다
- So that: 원하는 주제의 글을 빠르게 찾을 수 있다
- Acceptance Criteria:
- 태그 클릭으로 필터링
- 여러 태그 조합 검색
- 검색 결과 개수 표시
## Constraints & Assumptions
**Constraints**
- 개발 기간: 8주
- 개발 인원: 1명 (풀스택)
- 예산: 무료 티어 서비스 활용
- 초기 저장소 용량: 10GB
**Assumptions**
- 사용자는 Chrome, Firefox, Safari 최신 버전 사용
- 초기 트래픽: 하루 500-1000명
- 글 평균 길이: 2000-5000자
- 이미지 평균 크기: 500KB 이하버전관리 전략 수립
"체계적인 버전관리로 프로젝트 문서의 변화를 명확하게 추적합니다"
Claude.md 자체도 프로젝트와 함께 진화하므로 체계적인 버전관리가 필요합니다.
문서 상단에 버전 번호와 변경 이력을 기록하는 섹션을 추가합니다. "v1.0.0 (2024-03-01): 초기 프로젝트 구조 정의 / v1.1.0 (2024-03-15): API 명세 추가 / v1.2.0 (2024-04-01): 테스트 전략 업데이트"처럼 시맨틱 버저닝을 적용합니다. 주요 변경사항(Major), 기능 추가(Minor), 수정(Patch)을 구분하여 버전을 관리하면 문서의 변화를 추적하기 쉽습니다.
Git을 활용한 문서 버전관리도 중요합니다.
Claude.md는 프로젝트 루트에 위치하며, 다른 코드와 함께 버전 관리됩니다. 중요한 변경 사항이 있을 때는 별도의 커밋으로 분리하고, 커밋 메시지에 "docs: claude.md API 명세 업데이트"처럼 명확히 표시합니다. 브랜치 전략도 고려하여, 대규모 문서 개편 시에는 별도 브랜치에서 작업하고 리뷰 후 병합합니다. 이렇게 하면 문서 변경 이력을 코드 변경과 함께 추적할 수 있습니다.
프로젝트 단계별로 문서 스냅샷을 저장하는 것도 좋은 방법입니다.
"/docs/archive" 디렉토리에 "claude-v1.0-planning.md", "claude-v2.0-development.md" 같은 파일로 각 단계의 문서를 보존합니다. 이는 프로젝트 회고 시 초기 계획과 실제 구현을 비교하는 데 유용합니다. 또한 새로운 팀원이 합류했을 때 프로젝트가 어떻게 진화했는지 이해하는 데 도움이 됩니다. AI와 대화할 때도 과거 버전을 참조하여 변경 이유를 설명할 수 있습니다.
변경 이력(Changelog) 섹션을 claude.md 하단에 유지합니다.
각 변경사항에는 날짜, 변경자, 변경 이유를 기록합니다. "2024-03-20 | John | 인증 방식을 세션에서 JWT로 변경 - 확장성 향상을 위해"처럼 컨텍스트를 제공합니다. 이는 단순히 무엇이 변했는지뿐만 아니라 왜 변했는지를 기록하여, 향후 유사한 의사결정 시 참고 자료가 됩니다. AI에게 과거 결정의 배경을 설명할 때도 이 섹션을 참조하면 더 정확한 조언을 받을 수 있습니다.
Claude.md를 활용한 버전관리 전략 수립 예시
---
version: 1.2.0
last_updated: 2024-04-01
maintained_by: 개발팀
---
# Blog Site Project - Claude.md
## Version History
### v1.2.0 (2024-04-01)
- **Added**: 테스트 전략 섹션 추가
- **Changed**: API 명세 응답 형식 통일
- **Reason**: 코드 품질 향상 및 일관성 유지
### v1.1.0 (2024-03-15)
- **Added**: API 상세 명세 추가
- **Added**: 디자인 가이드라인 추가
- **Reason**: 프론트엔드-백엔드 병렬 개발 지원
### v1.0.0 (2024-03-01)
- **Initial Release**: 프로젝트 기본 구조 정의
- 기술 스택, 프로젝트 구조, 개발 규칙 설정
## Version Management Strategy
### Document Versioning
- Semantic Versioning 사용 (MAJOR.MINOR.PATCH)
- MAJOR: 프로젝트 구조나 기술 스택 변경
- MINOR: 새로운 섹션이나 주요 기능 추가
- PATCH: 오타 수정, 소규모 업데이트
### Git Integration
- claude.md는 프로젝트 루트에 위치
- 문서 변경 시 독립적인 커밋 생성
- 커밋 메시지 형식: `docs: claude.md [변경내용]`
- PR 리뷰 시 문서 변경도 함께 검토
### Archiving Strategy
- 주요 마일스톤마다 스냅샷 저장
- 경로: /docs/archive/claude-v{version}-{phase}.md
- 보관 주기: 프로젝트 단계 전환 시점
## Changelog
### [2024-04-01] - v1.2.0
**Author**: 김개발
**Changes**:
- 테스트 전략 섹션 추가 (Jest, Cypress 설정)
- API 응답 형식을 {success, data, error}로 통일
**Reason**: 프론트엔드 팀의 요청으로 API 응답 구조 표준화
### [2024-03-20] - v1.1.5
**Author**: 이백엔드
**Changes**:
- 인증 방식 JWT로 변경 (기존 세션 방식)
**Reason**: 서버 확장성 향상 및 마이크로서비스 준비
### [2024-03-15] - v1.1.0
**Author**: 박프론트
**Changes**:
- API 엔드포인트 상세 명세 작성
- 디자인 시스템 색상/타이포그래피 정의
**Reason**: 프론트-백엔드 병렬 개발 시작3. 설계 단계에서의 Claude.md 활용
아키텍처 설계 문서화
설계 단계에서는 claude.md에 시스템 아키텍처를 상세히 기록합니다.
먼저 전체 시스템 구조를 다이어그램으로 표현하고, 각 컴포넌트의 역할을 설명합니다. 블로그 프로젝트의 경우 "클라이언트(React SPA) ↔ API 게이트웨이(Express) ↔ 비즈니스 로직 레이어 ↔ 데이터 액세스 레이어 ↔ MongoDB"처럼 계층별 구조를 명시합니다. 각 계층 간 통신 방식과 데이터 흐름도 함께 기술하여, AI가 특정 레이어의 코드를 작성할 때 전체 맥락을 이해하도록 합니다.
데이터베이스 스키마 설계도 중요한 부분입니다.
각 컬렉션(또는 테이블)의 필드, 타입, 인덱스, 관계를 명확히 정의합니다. 관계형 데이터베이스라면 ERD를, NoSQL이라면 문서 구조를 명시합니다. 이는 AI에게 데이터 모델 코드나 쿼리 작성을 요청할 때 정확한 스키마를 참조하게 합니다.
컴포넌트 설계에서는 주요 UI 컴포넌트의 구조와 props를 정의합니다.
각 컴포넌트의 책임 범위와 재사용 가능성도 고려하여 설계합니다. 상태 관리 전략(Redux, Context API, Zustand 등)도 함께 명시하면, AI가 일관된 패턴으로 컴포넌트 코드를 생성할 수 있습니다.
API 설계에서는 RESTful 원칙을 따르는 엔드포인트 구조를 정의합니다.
각 엔드포인트의 HTTP 메서드, URL 패턴, 쿼리 파라미터, 요청 본문, 응답 형식, 에러 코드를 상세히 기술합니다. 인증이 필요한 엔드포인트는 별도로 표시하고, 권한 레벨도 명시합니다. 이렇게 하면 프론트엔드 개발자나 AI가 정확한 API 호출 코드를 작성할 수 있습니다.
Claude.md를 위한 시스템 아키텍처 설계 예시
# System Architecture Design
## Overall Structure
```
┌─────────────────┐
│ React Client │ (Port 3000)
│ - Vite Build │
│ - Tailwind CSS │
└────────┬────────┘
│ HTTPS
│ API Calls (Axios)
▼
┌─────────────────┐
│ Express Server │ (Port 5000)
│ - API Routes │
│ - Middleware │
│ - Validation │
└────────┬────────┘
│
┌────┴────┐
▼ ▼
┌───────┐ ┌──────────┐
│MongoDB│ │Cloudinary│
│(DB) │ │(Images) │
└───────┘ └──────────┘
```
**Communication Flow**:
1. Client ▶ JWT Token in Header ▶ Server
2. Server ▶ Validate & Process ▶ Database
3. Database ▶ Response Data ▶ Server
4. Server ▶ JSON Response ▶ Client
## Database Schema
**Users Collection**
```javascript
{
_id: ObjectId,
email: String, // unique, indexed
passwordHash: String, // bcrypt hashed
username: String, // unique, min 3 chars
bio: String, // optional, max 500 chars
avatar: String, // URL to image
createdAt: Date,
updatedAt: Date
}
```
**Posts Collection**
```javascript
{
_id: ObjectId,
authorId: ObjectId, // ref: Users, indexed
title: String, // required, max 200 chars
slug: String, // unique, indexed
content: String, // markdown format
excerpt: String, // auto-generated, 150 chars
tags: [String], // max 5 tags, indexed
coverImage: String, // optional URL
published: Boolean, // draft or published
publishedAt: Date, // indexed for sorting
views: Number, // default 0
createdAt: Date,
updatedAt: Date
}
```
**Comments Collection**
```javascript
{
_id: ObjectId,
postId: ObjectId, // ref: Posts, indexed
authorId: ObjectId, // ref: Users
content: String, // max 1000 chars
parentId: ObjectId, // for nested comments
createdAt: Date
}
```
## Component Design
**PostEditor Component**
```typescript
interface PostEditorProps {
initialPost?: Post;
onSave: (post: PostInput) => Promise<void>;
onCancel: () => void;
isLoading?: boolean;
}
// Features:
// - Split view: Markdown editor + Live preview
// - Auto-save to localStorage every 30 seconds
// - Tag input with autocomplete
// - Image upload with drag & drop
```
**PostList Component**
```typescript
interface PostListProps {
posts: Post[];
loading: boolean;
hasMore: boolean;
onLoadMore: () => void;
onPostClick: (postId: string) => void;
}
// Features:
// - Infinite scroll pagination
// - Skeleton loading states
// - Filter by tags (URL query params)
// - Sort by date/views
```
## State Management
**Global State (Context API)**
- AuthContext: 사용자 인증 상태, 토큰
- ThemeContext: 다크/라이트 모드
- NotificationContext: 토스트 메시지
**Local State (useState)**
- Form inputs, UI toggles
- Component-specific data
**Server State (React Query)**
- API data fetching
- Caching strategy: staleTime 5분
- Automatic refetch on window focus
## API Design
**Authentication Endpoints**
```
POST /api/auth/register
Body: { email, password, username }
Response: 201 { token, user: { id, email, username } }
Errors: 400 (invalid input), 409 (email exists)
POST /api/auth/login
Body: { email, password }
Response: 200 { token, user }
Errors: 401 (invalid credentials), 400 (validation error)
GET /api/auth/me (Auth required)
Headers: Authorization: Bearer <token>
Response: 200 { user }
Errors: 401 (invalid token)
```
**Posts Endpoints**
```
GET /api/posts?page=1&limit=10&tag=react&sort=recent
Response: 200 { posts, totalPages, currentPage, totalCount }
Errors: 400 (invalid params)
GET /api/posts/:slug
Response: 200 { post, author, commentCount }
Errors: 404 (not found)
POST /api/posts (Auth required)
Body: { title, content, tags, coverImage }
Response: 201 { post }
Errors: 400 (validation), 401 (unauthorized)
PUT /api/posts/:id (Auth required, owner only)
Body: { title?, content?, tags? }
Response: 200 { post }
Errors: 403 (forbidden), 404 (not found)
DELETE /api/posts/:id (Auth required, owner only)
Response: 204 No Content
Errors: 403 (forbidden), 404 (not found)
```
## Error Handling Strategy
**Client-side**
- API errors: Display toast notification
- Network errors: Retry 3 times with exponential backoff
- Validation errors: Show inline form errors
**Server-side**
- All errors return: { success: false, error: { message, code } }
- 400: Validation errors with field details
- 401: Authentication required
- 403: Permission denied
- 404: Resource not found
- 500: Server error (log to monitoring service)
작업관리와 마일스톤 설정
설계가 완료되면 구현 작업을 체계적으로 관리하기 위한 계획을 claude.md에 추가합니다.
먼저 프로젝트를 작은 작업 단위(Task)로 나눕니다. 각 작업에 고유 ID를 부여하고 명확한 설명을 추가합니다. 각 작업의 예상 소요 시간, 우선순위, 담당자, 상태(To Do/In Progress/Done)를 함께 기록합니다. 이렇게 하면 프로젝트 진행 상황을 한눈에 파악할 수 있습니다.
작업 간의 의존성도 명시합니다.
"TASK-003은 TASK-001과 TASK-002 완료 후 시작 가능"처럼 선행 작업을 표시하면, 어떤 순서로 작업해야 효율적인지 알 수 있습니다. AI에게 작업을 요청할 때도 "TASK-002를 먼저 완료했으니, 이제 TASK-003의 JWT 미들웨어를 구현해줘"라고 맥락을 제공할 수 있습니다. 의존성 그래프를 시각화하면 병렬로 진행할 수 있는 작업도 쉽게 파악됩니다.
마일스톤(Milestone)을 설정하여 프로젝트의 주요 단계를 정의합니다.
"M1: 백엔드 API 완성 (Week 3), M2: 프론트엔드 핵심 기능 (Week 5), M3: 테스트 및 배포 (Week 7)"처럼 날짜와 함께 각 마일스톤에서 달성해야 할 목표를 명확히 합니다. 각 마일스톤은 데모 가능한 수준의 결과물을 포함해야 합니다. 이는 프로젝트 진행 상황을 점검하고 필요시 계획을 조정하는 기준점이 됩니다.
스프린트 방식을 적용한다면, 각 스프린트의 목표와 포함된 작업 목록을 기록합니다.
스프린트 회고(Retrospective)도 간단히 기록하여 "잘된 점: API 설계가 명확해서 빠른 개발 / 개선할 점: 테스트 코드 작성 미흡"처럼 학습 내용을 문서화합니다. 이는 다음 스프린트나 향후 프로젝트에 귀중한 참고 자료가 됩니다.
Claude.md - 작업관리와 마일스톤 설정 예시
# Task Management & Milestones
## Task List
**TASK-001: 프로젝트 초기 설정** Done
- Priority: High | Estimated: 0.5d | Actual: 0.5d
- Description: Node.js 프로젝트 초기화, 패키지 설치, 폴더 구조 생성
- Dependencies: None
- Completed: 2024-03-01
**TASK-002: MongoDB 연결 설정** Done
- Priority: High | Estimated: 0.5d | Actual: 0.3d
- Description: Mongoose 설정, 연결 함수 작성, 환경변수 설정
- Dependencies: TASK-001
- Completed: 2024-03-01
**TASK-003: User 모델 및 스키마** In Progress
- Priority: High | Estimated: 1d | Progress: 70%
- Description: User 스키마 정의, validation, bcrypt 해싱
- Dependencies: TASK-002
- Assignee: 김개발
- Started: 2024-03-02
**TASK-004: 인증 API 구현** ⚪ To Do
- Priority: High | Estimated: 1.5d
- Description: 회원가입, 로그인 라우트, JWT 발급
- Dependencies: TASK-003
- Notes: JWT 만료시간 24시간, refresh token은 v2에서
**TASK-005: JWT 인증 미들웨어** ⚪ To Do
- Priority: High | Estimated: 0.5d
- Description: 토큰 검증 미들웨어, 보호된 라우트 적용
- Dependencies: TASK-004
**TASK-006: Post 모델 및 스키마** ⚪ To Do
- Priority: High | Estimated: 1d
- Description: Post 스키마, slug 자동 생성, 관계 설정
- Dependencies: TASK-003
**TASK-007: Post CRUD API** ⚪ To Do
- Priority: High | Estimated: 2d
- Description: 생성/조회/수정/삭제 API, 권한 검증
- Dependencies: TASK-005, TASK-006
**TASK-008: 페이지네이션 구현** ⚪ To Do
- Priority: Medium | Estimated: 1d
- Description: 커서 기반 페이지네이션, 정렬/필터링
- Dependencies: TASK-007
## Dependency Graph
```
TASK-001 (Setup)
↓
TASK-002 (MongoDB)
↓
TASK-003 (User Model) ──→ TASK-006 (Post Model)
↓ ↓
TASK-004 (Auth API) TASK-007 (Post API)
↓ ↓
TASK-005 (JWT Middleware) TASK-008 (Pagination)
└───────────┬──────────────┘
↓
Backend Complete
```
## Milestones
**M1: Backend Foundation (Week 3 - 2024-03-22)**
- 프로젝트 셋업 완료
- 인증 시스템 구현 (70% 완료)
- Post CRUD API 구현
- **Demo**: Postman에서 모든 API 테스트 가능
**M2: Frontend Core (Week 5 - 2024-04-05)**
- React 프로젝트 셋업
- 라우팅 및 레이아웃 구성
- 로그인/회원가입 페이지
- 글 작성 에디터 (마크다운)
- 글 목록 페이지
- **Demo**: 실제 글 작성 및 조회 가능
**M3: Integration & Polish (Week 7 - 2024-04-19)**
- 프론트-백엔드 통합
- 에러 핸들링 개선
- 로딩 상태 추가
- 반응형 디자인 완성
- **Demo**: 배포된 사이트에서 전체 플로우 시연
**M4: Testing & Deployment (Week 8 - 2024-04-26)**
- 단위 테스트 작성 (커버리지 80%)
- E2E 테스트 시나리오
- 성능 최적화
- 프로덕션 배포
- **Demo**: 라이브 사이트 공개
## Sprint Planning
**Sprint 1: Foundation (Week 1-2)**
**Goal**: 백엔드 인증 시스템 완성
**Tasks**: TASK-001 ~ TASK-005
**Review**: 2024-03-15
**Retrospective**:
- Well: MongoDB Atlas 설정이 예상보다 쉬웠음
- ⚠Improve: 환경변수 관리를 초기부터 체계적으로
- Learn: bcrypt salt rounds는 10이 적절
**Sprint 2: Core Features (Week 3-4)**
**Goal**: Post CRUD 및 페이지네이션
**Tasks**: TASK-006 ~ TASK-008
**Review**: 2024-03-29
**Retrospective**: (작성 예정)
**Sprint 3: Frontend Setup (Week 5-6)**
**Goal**: React 프로젝트 및 핵심 페이지 구현
**Tasks**: TASK-009 ~ TASK-015
**Review**: 2024-04-12
## Work Progress Tracking
**Week 1 (2024-02-26 ~ 03-01)**
- 프로젝트 기획 및 claude.md 작성
- 기술 스택 결정
- 개발 환경 셋업
**Week 2 (2024-03-04 ~ 03-08)**
- MongoDB 연결 및 User 모델
- 인증 API 구현 중 (70%)
- Next: JWT 미들웨어 완성
**Week 3 (2024-03-11 ~ 03-15)**
- Target: Post 모델 및 CRUD API 완성4. 구현 단계에서의 Claude.md 활용
개발 가이드라인과 코딩 표준
구현 단계에서는 claude.md에 명시된 코딩 표준을 엄격히 따릅니다.
파일 구조 규칙을 정의하여 "모든 React 컴포넌트는 /src/components 하위에 폴더로 생성하며, index.tsx (컴포넌트), styles.module.css (스타일), types.ts (타입) 파일을 포함"처럼 일관된 구조를 유지합니다. 이렇게 하면 AI에게 새 컴포넌트 생성을 요청할 때 자동으로 올바른 구조로 파일이 생성됩니다. 파일 이름 규칙도 명확히 하여 "컴포넌트는 PascalCase, 유틸리티는 camelCase, 상수는 UPPER_SNAKE_CASE"처럼 정의합니다.
코드 작성 패턴과 베스트 프랙티스를 문서화합니다.
"비동기 함수는 항상 try-catch로 감싸고 에러 로깅 포함", "React 컴포넌트는 함수형으로 작성하고 hooks 사용", "API 호출은 별도의 service 레이어로 분리"처럼 구체적인 가이드라인을 제공합니다. 좋은 예시와 나쁜 예시를 코드로 보여주면 더 효과적입니다. AI에게 코드 리뷰를 요청할 때도 이 가이드라인을 기준으로 평가하도록 지시할 수 있습니다.
주석과 문서화 규칙도 중요합니다.
"모든 함수는 JSDoc 형식의 주석 작성 필수", "복잡한 로직에는 인라인 주석으로 설명 추가", "API 엔드포인트는 Swagger 주석 포함"처럼 문서화 수준을 정의합니다. 좋은 주석은 "왜(why)" 이 코드가 필요한지 설명하고, "무엇을(what)" 하는지는 코드 자체가 설명하도록 합니다. AI가 생성한 코드에도 적절한 주석을 요청하면, 나중에 코드를 유지보수할 때 큰 도움이 됩니다.
Git 커밋 전략도 claude.md에 명시합니다.
"Conventional Commits 형식 사용: feat/fix/docs/style/refactor/test/chore", "커밋 메시지는 영문 명령형으로 작성: 'Add user authentication' (O) 'Added user authentication' (X)", "한 커밋은 하나의 논리적 변경만 포함"처럼 일관된 규칙을 따릅니다. 브랜치 전략도 정의하여 "main: 프로덕션, develop: 개발, feature/: 기능 개발, hotfix/: 긴급 수정"처럼 명확한 브랜치 모델을 수립합니다. 이는 버전 관리를 체계화하고 협업을 원활하게 만듭니다.
Claude.md - 개발 가이드라인과 코딩 표준 설정 예시
# Development Guidelines & Coding Standards
## File Structure Standards
**React Components**
```
/src/components/
/PostEditor/
├── index.tsx (메인 컴포넌트)
├── PostEditor.test.tsx (테스트)
├── types.ts (타입 정의)
├── hooks.ts (커스텀 훅)
└── styles.module.css (스타일)
```
**API Routes**
```
/server/routes/
/posts/
├── index.js (라우터 등록)
├── controller.js (비즈니스 로직)
├── validation.js (입력 검증)
└── tests.js (API 테스트)
```
## Naming Conventions
**JavaScript/TypeScript**
- 컴포넌트: `PascalCase` (예: PostEditor, UserProfile)
- 함수/변수: `camelCase` (예: fetchPosts, isLoading)
- 상수: `UPPER_SNAKE_CASE` (예: MAX_FILE_SIZE, API_BASE_URL)
- 타입/인터페이스: `PascalCase` (예: User, PostInput)
- 파일명: 컴포넌트는 `PascalCase`, 나머지는 `camelCase`
**CSS/Styles**
- 클래스명: `kebab-case` (예: post-editor, user-avatar)
- CSS 모듈: `camelCase` (예: styles.postEditor)
## Code Patterns & Best Practices
### Async/Await Pattern
**Good: 항상 try-catch로 에러 처리**
```typescript
async function fetchUserPosts(userId: string) {
try {
const response = await api.get(`/users/${userId}/posts`);
return { success: true, data: response.data };
} catch (error) {
logger.error('Failed to fetch user posts', { userId, error });
return { success: false, error: error.message };
}
}
```
**Bad: 에러 처리 없음**
```typescript
async function fetchUserPosts(userId: string) {
const response = await api.get(`/users/${userId}/posts`);
return response.data;
}
```
### React Component Pattern
**Good: Props 타입 정의, 명확한 구조**
```typescript
interface PostCardProps {
post: Post;
onEdit?: (id: string) => void;
onDelete?: (id: string) => void;
}
export function PostCard({ post, onEdit, onDelete }: PostCardProps) {
const [isExpanded, setIsExpanded] = useState(false);
// Event handlers
const handleEdit = () => onEdit?.(post.id);
// Render
return (
<article className="post-card">
{/* JSX */}
</article>
);
}
```
**Bad: 타입 없음, 복잡한 인라인 로직**
```typescript
export function PostCard(props) {
return <div onClick={() => { /* 복잡한 로직 */ }}>...</div>;
}
```
### API Service Layer
**Good: 분리된 서비스 레이어**
```typescript
// /src/services/postService.ts
export class PostService {
async getPosts(params: GetPostsParams) {
const response = await apiClient.get('/posts', { params });
return response.data;
}
async createPost(post: PostInput) {
const response = await apiClient.post('/posts', post);
return response.data;
}
}
```
**Bad: 컴포넌트에 직접 API 호출**
```typescript
function PostList() {
const fetchPosts = async () => {
const res = await fetch('/api/posts');
// ...
};
}
```
## Documentation Standards
### Function Documentation (JSDoc)
```typescript
/**
* 사용자의 게시글 목록을 가져옵니다.
*
* @param userId - 사용자 ID
* @param options - 페이지네이션 및 필터 옵션
* @param options.page - 페이지 번호 (기본값: 1)
* @param options.limit - 페이지당 항목 수 (기본값: 10)
* @returns 게시글 목록과 페이지네이션 정보
* @throws {ApiError} API 호출 실패 시
*
* @example
* const posts = await fetchUserPosts('user123', { page: 1, limit: 20 });
*/
async function fetchUserPosts(
userId: string,
options: PaginationOptions = {}
): Promise<PostsResponse> {
// ...
}
```
### Complex Logic Comments
**Good: 왜(why) 이렇게 했는지 설명**
```typescript
// bcrypt의 salt rounds를 10으로 설정합니다.
// 이는 보안과 성능의 균형을 맞추기 위한 권장값입니다.
// (8은 너무 약하고, 12는 너무 느림)
const saltRounds = 10;
const hashedPassword = await bcrypt.hash(password, saltRounds);
```
**Bad: 코드를 그대로 반복**
```typescript
// 비밀번호를 해싱합니다
const hashedPassword = await bcrypt.hash(password, 10);
```
## Git Commit Strategy
### Commit Message Format (Conventional Commits)
```
<type>(<scope>): <subject>
<body>
<footer>
```
**Types**:
- `feat`: 새로운 기능 추가
- `fix`: 버그 수정
- `docs`: 문서 변경
- `style`: 코드 포맷팅 (기능 변경 없음)
- `refactor`: 코드 리팩토링
- `test`: 테스트 추가/수정
- `chore`: 빌드/설정 변경
**Examples**:
```
feat(auth): add JWT refresh token logic
Implement refresh token rotation for enhanced security.
Tokens expire after 7 days and are automatically refreshed.
Closes #23
---
fix(posts): resolve pagination bug on last page
The pagination component crashed when on the last page
due to incorrect calculation of hasNextPage.
---
docs(readme): update installation instructions
```
## Branch Strategy
```
main (프로덕션 배포)
↓
develop (개발 통합)
↓
feature/* (새 기능)
- feature/user-auth
- feature/post-editor
hotfix/* (긴급 수정)
- hotfix/login-crash
```
**Branch Rules**:
- `main`에는 직접 커밋 금지 (PR만 허용)
- `feature` 브랜치는 `develop`에서 분기
- `hotfix`는 `main`에서 분기 후 `main`과 `develop` 양쪽에 머지
- PR은 최소 1명의 리뷰 필요
## Code Quality Checks
**Pre-commit Hooks (Husky)**
- ESLint: 코드 스타일 검사
- Prettier: 코드 포맷팅
- TypeScript: 타입 체크
- Test: 변경된 파일의 테스트 실행
**CI/CD Pipeline**
- Pull Request 시 자동 실행:
1. Lint & Format 체크
2. TypeScript 빌드
3. 전체 테스트 실행
4. 커버리지 리포트 (80% 이상 필수)
추가요청사항 관리 및 기존 문서 병합
프로젝트를 진행하다 보면 초기 계획에 없던 요구사항이 추가됩니다.
Claude.md에 '변경 요청 로그(Change Request Log)' 섹션을 만들어 모든 추가 요청을 기록합니다. "CR-001: 댓글 기능 추가 요청 (요청자: 사용자 피드백, 날짜: 2024-03-15, 상태: 승인, 예상 공수: 3일)"처럼 각 요청에 고유 ID, 요청 사유, 우선순위, 영향 범위를 명시합니다. 이렇게 하면 범위 확장(scope creep)을 관리하고 프로젝트 일정에 미치는 영향을 평가할 수 있습니다.
변경 요청 평가 프로세스를 정의합니다.
"모든 변경 요청은 1) 비즈니스 가치 평가, 2) 기술적 실행 가능성 검토, 3) 기존 아키텍처 영향 분석을 거쳐 승인/보류/거부 결정"처럼 체계적인 검토 절차를 만듭니다. 승인된 변경사항은 기존 claude.md 섹션에 통합하고, 변경 이력에 기록합니다. 예를 들어 댓글 기능이 추가되면 데이터베이스 스키마 섹션에 Comments 컬렉션을 추가하고, API 명세에 댓글 엔드포인트를 업데이트합니다.
추가된 작업을 기존 작업 목록과 통합할 때는 의존성을 명확히 합니다.
"TASK-020: 댓글 API 구현 (의존성: TASK-007 Post API, CR-001과 연결)"처럼 기존 작업과의 관계를 표시합니다. 마일스톤이나 스프린트 계획도 조정하여 "M3에서 M4로 댓글 기능 이동, 전체 일정 1주 연장"처럼 변경 영향을 반영합니다. 이렇게 하면 AI와 대화할 때 "CR-001 댓글 기능을 구현해야 하는데, 기존 Post 구조와 어떻게 통합해야 할까?"처럼 맥락을 포함한 질문을 할 수 있습니다.
버전 관리 측면에서 중요한 변경사항은 새로운 버전으로 claude.md를 업데이트합니다.
"v1.3.0: 댓글 시스템 추가로 인한 아키텍처 확장"처럼 버전 번호를 올리고 주요 변경 내용을 changelog에 기록합니다. 대규모 변경이라면 이전 버전을 아카이브 폴더에 백업하고, Git에서도 태그를 생성하여 특정 버전으로 쉽게 돌아갈 수 있게 합니다. 이는 프로젝트가 어떻게 진화했는지 추적하고, 필요시 이전 결정을 재검토하는 데 유용합니다.
Claude.md - 추가 요청사항 관리 및 기존 문서 병합 예시
# Change Request Management
## Change Request Log
**CR-001: 댓글 시스템 추가** Approved
- **Requested by**: 사용자 피드백 (베타 테스터 3명)
- **Date**: 2024-03-15
- **Priority**: High
- **Estimated Effort**: 3 days
- **Impact**:
- Database: Comments 컬렉션 추가
- API: 5개 새 엔드포인트
- Frontend: 댓글 컴포넌트 2개
- Testing: 단위/통합 테스트 추가
- **Business Value**: 사용자 참여도 증가, 커뮤니티 활성화
- **Technical Feasibility**: 기존 구조와 호환 가능
- **Status**: 승인됨 (2024-03-16)
- **Scheduled**: Sprint 4
**CR-002: 소셜 로그인 (Google OAuth)** Under Review
- **Requested by**: 제품 오너
- **Date**: 2024-03-18
- **Priority**: Medium
- **Estimated Effort**: 5 days
- **Impact**:
- Auth flow 재설계 필요
- User 모델 확장 (provider 필드)
- 보안 검토 필요
- **Business Value**: 가입 전환율 향상 예상
- **Technical Feasibility**: 기존 JWT 로직 수정 필요
- **Status**: 기술적 영향 분석 중
- **Decision Due**: 2024-03-22
**CR-003: 다국어 지원 (i18n)** Rejected
- **Requested by**: 마케팅 팀
- **Date**: 2024-03-17
- **Priority**: Low
- **Estimated Effort**: 10 days
- **Impact**: 전체 UI 구조 변경, 콘텐츠 번역 필요
- **Rejection Reason**: v1.0 범위 초과, 사용자 요청 없음, v2.0으로 연기
- **Status**: 거부됨 (2024-03-18)
- **Alternative**: v2.0 roadmap에 추가
## Change Request Evaluation Process
**Step 1: Initial Assessment**
- 요청의 명확성 검토 (모호한 경우 추가 정보 요청)
- 비즈니스 가치 평가 (High/Medium/Low)
- 초기 공수 추정 (T-shirt sizing: S/M/L/XL)
**Step 2: Technical Analysis**
- 기존 아키텍처와의 호환성 확인
- 데이터 모델 변경 필요성 검토
- 성능/보안 영향 분석
- 기술적 부채 발생 가능성 평가
**Step 3: Impact Analysis**
- 영향받는 컴포넌트/모듈 식별
- 현재 진행 중인 작업과의 충돌 확인
- 일정 및 리소스 영향 계산
- 테스트 범위 확대 필요성 검토
**Step 4: Decision Making**
- 승인: 현재 스프린트 또는 백로그에 추가
- 보류: 추가 정보 수집 또는 우선순위 재평가 필요
- 거부: 명확한 거부 사유와 대안 제시
## Integration of Approved Changes
### CR-001 (댓글 시스템) 통합 예시
**1. Database Schema Update**
```javascript
// /docs/schema.md에 추가됨
Comments Collection {
_id: ObjectId,
postId: ObjectId, // ref: Posts
authorId: ObjectId, // ref: Users
content: String, // max 1000 chars
parentId: ObjectId, // for nested replies
createdAt: Date,
updatedAt: Date
}
// Indexes:
db.comments.createIndex({ postId: 1, createdAt: -1 })
db.comments.createIndex({ authorId: 1 })
```
**2. API Specification Update**
```markdown
## Comments API (New)
GET /api/posts/:postId/comments
- Query: ?page=1&limit=20
- Response: { comments, totalCount, hasMore }
POST /api/posts/:postId/comments (🔒 Auth)
- Body: { content, parentId? }
- Response: 201 { comment }
PUT /api/comments/:id (🔒 Auth, owner only)
- Body: { content }
- Response: 200 { comment }
DELETE /api/comments/:id (🔒 Auth, owner only)
- Response: 204 No Content
```
**3. Task List Update**
```markdown
TASK-020: Comments 데이터 모델 및 API (CR-001)
- Priority: High | Estimated: 2d
- Dependencies: TASK-007 (Post API)
- Description: 댓글 스키마, CRUD API, 중첩 댓글 지원
TASK-021: Comment React 컴포넌트 (CR-001)
- Priority: High | Estimated: 1.5d
- Dependencies: TASK-020
- Description: CommentList, CommentForm, 대댓글 UI
TASK-022: Comment 통합 테스트 (CR-001)
- Priority: Medium | Estimated: 0.5d
- Dependencies: TASK-020, TASK-021
- Description: API 테스트, E2E 시나리오
```
**4. Milestone Adjustment**
```markdown
M3: Integration & Polish (Week 7 → Week 8)
- 프론트-백엔드 통합
- 댓글 시스템 구현 (CR-001)
- 에러 핸들링 개선
- 반응형 디자인 완성
Overall Timeline: 8주 → 9주 (댓글 기능으로 인한 1주 연장)
```
## Version Update Due to Changes
**Version Bump Criteria**
- **Major (2.0.0)**: 아키텍처 변경, 호환성 깨짐
- **Minor (1.3.0)**: 새 기능 추가, 하위 호환
- **Patch (1.2.1)**: 버그 수정, 문서 업데이트
**v1.3.0 Change Summary (2024-03-20)**
- **Added**: 댓글 시스템 (CR-001)
- Comments 데이터 모델
- 5개 새 API 엔드포인트
- 중첩 댓글 지원
- **Changed**: Post 응답에 commentCount 필드 추가
- **Impact**: API breaking change 없음, 하위 호환 유지
- **Migration**: 기존 데이터 마이그레이션 불필요
## Rollback Plan
변경사항이 문제를 일으킬 경우:
1. Git에서 이전 버전 태그로 롤백
2. Claude.md도 `/docs/archive/claude-v1.2.0.md` 참조
3. 데이터베이스 마이그레이션 롤백 스크립트 실행
4. 문제 분석 후 수정된 버전으로 재배포5. 시험 단계에서의 Claude.md 활용
테스트 계획과 실행 추적
시험 단계에서는 claude.md의 테스트 전략 섹션을 구체적인 실행 계획으로 확장합니다.
단위 테스트(Unit Tests) 계획에는 "각 함수와 컴포넌트별 테스트 케이스 작성, 순수 함수는 입출력 검증, 컴포넌트는 렌더링 및 인터랙션 테스트"처럼 상세한 범위를 정의합니다. 테스트 파일 위치도 명시하여 일관된 구조를 유지합니다. AI에게 특정 함수의 테스트 코드 작성을 요청할 때 이 규칙을 참조하게 할 수 있습니다.
통합 테스트(Integration Tests)에서는 여러 컴포넌트나 모듈이 함께 작동하는 시나리오를 테스트합니다.
"인증 플로우 통합 테스트: 회원가입 → 로그인 → 토큰 검증 → 보호된 리소스 접근", "글 작성 플로우: 에디터 입력 → 마크다운 변환 → API 호출 → 목록 갱신"처럼 엔드투엔드 사용자 플로우를 정의합니다. 각 시나리오의 사전 조건, 실행 단계, 예상 결과를 명확히 기술합니다. 이는 테스트 자동화 시나리오를 작성하는 가이드가 됩니다.
E2E 테스트(End-to-End Tests)에는 실제 사용자 관점의 주요 시나리오를 포함합니다.
"신규 사용자가 회원가입 후 첫 번째 글을 작성하고 게시하기까지의 전체 과정"처럼 비즈니스 크리티컬한 플로우를 우선순위로 합니다. Cypress나 Playwright 같은 도구로 자동화할 테스트 케이스를 나열하고, 각 케이스의 실행 시간과 성공 기준을 정의합니다. 스크린샷이나 비디오 녹화 설정도 포함하여 실패 시 디버깅을 용이하게 합니다.
테스트 커버리지 목표와 추적 방법도 명시합니다.
"전체 코드 커버리지 80% 이상, 핵심 비즈니스 로직은 90% 이상"처럼 구체적인 목표를 설정합니다. 커버리지 리포트는 매 PR마다 생성되고, 커버리지가 감소하면 머지를 차단하도록 CI/CD 파이프라인을 구성합니다. Claude.md에 현재 커버리지 상태를 기록하여 진행 상황을 추적할 수 있습니다.
Claude.md - 테스트 계획과 실행 추적 예시
# Testing Strategy & Execution Plan
## Test Pyramid Overview
```
/\ E2E Tests (10%)
/ \ - Critical user flows
/----\ - Cypress
/ \
/--------\ Integration Tests (30%)
/ \ - API + Database
/------------\ - Component interactions
/______________\ Unit Tests (60%)
- Functions, Components
- Jest, RTL
```
## Unit Tests
**Coverage Target**: 80% overall, 90% for core logic
**Testing Standards**:
- 모든 유틸리티 함수는 테스트 필수
- React 컴포넌트는 렌더링 + 주요 인터랙션 테스트
- API 컨트롤러 함수는 성공/실패 케이스 모두 테스트
## Test Case Examples
### AUTH-UT-001: 비밀번호 해싱 테스트
```typescript
// /server/utils/__tests__/auth.test.js
describe('hashPassword', () => {
it('should hash password with bcrypt', async () => {
const password = 'testPassword123';
const hash = await hashPassword(password);
expect(hash).not.toBe(password);
expect(hash).toMatch(/^\$2[aby]\$/);
});
it('should generate different hashes for same password', async () => {
const password = 'testPassword123';
const hash1 = await hashPassword(password);
const hash2 = await hashPassword(password);
expect(hash1).not.toBe(hash2);
});
});
```
### POST-UT-001: 슬러그 생성 테스트
```typescript
// /server/utils/__tests__/slug.test.js
describe('generateSlug', () => {
it('should convert title to lowercase slug', () => {
expect(generateSlug('Hello World')).toBe('hello-world');
});
it('should remove special characters', () => {
expect(generateSlug('React & TypeScript!')).toBe('react-typescript');
});
it('should handle Korean characters', () => {
expect(generateSlug('안녕하세요 블로그')).toMatch(/^[a-z0-9-]+$/);
});
});
```
### COMPONENT-UT-001: PostCard 렌더링 테스트
```typescript
// /client/src/components/__tests__/PostCard.test.tsx
describe('PostCard', () => {
const mockPost = {
id: '1',
title: 'Test Post',
excerpt: 'Test excerpt',
author: { username: 'testuser' },
createdAt: '2024-03-01',
};
it('should render post information', () => {
render(<PostCard post={mockPost} />);
expect(screen.getByText('Test Post')).toBeInTheDocument();
expect(screen.getByText('Test excerpt')).toBeInTheDocument();
});
it('should call onEdit when edit button clicked', () => {
const onEdit = jest.fn();
render(<PostCard post={mockPost} onEdit={onEdit} />);
fireEvent.click(screen.getByRole('button', { name: /edit/i }));
expect(onEdit).toHaveBeenCalledWith('1');
});
});
```
## Integration Tests
### API-IT-001: 인증 플로우 통합 테스트
```typescript
// /server/__tests__/integration/auth.test.js
describe('Authentication Flow', () => {
it('should complete full auth flow', async () => {
// 1. 회원가입
const signupRes = await request(app)
.post('/api/auth/register')
.send({
email: 'test@example.com',
password: 'password123',
username: 'testuser'
});
expect(signupRes.status).toBe(201);
expect(signupRes.body).toHaveProperty('token');
const { token } = signupRes.body;
// 2. 토큰으로 보호된 리소스 접근
const profileRes = await request(app)
.get('/api/auth/me')
.set('Authorization', `Bearer ${token}`);
expect(profileRes.status).toBe(200);
expect(profileRes.body.user.email).toBe('test@example.com');
// 3. 로그아웃 후 접근 실패
const unauthorizedRes = await request(app)
.get('/api/auth/me');
expect(unauthorizedRes.status).toBe(401);
});
});
```
### POST-IT-001: 글 작성 플로우 테스트
```typescript
describe('Post Creation Flow', () => {
let authToken;
beforeAll(async () => {
const res = await loginTestUser();
authToken = res.body.token;
});
it('should create, read, update, and delete post', async () => {
// 1. 글 작성
const createRes = await request(app)
.post('/api/posts')
.set('Authorization', `Bearer ${authToken}`)
.send({
title: 'Integration Test Post',
content: '# Test Content',
tags: ['test']
});
expect(createRes.status).toBe(201);
const postId = createRes.body.post.id;
// 2-4. 조회, 수정, 삭제 테스트...
});
});
```
## E2E Tests (Cypress)
### E2E-001: 신규 사용자 글 작성 플로우
```javascript
// /cypress/e2e/user-journey.cy.js
describe('New User Post Creation Journey', () => {
it('should sign up and create first post', () => {
cy.visit('/');
cy.contains('Sign Up').click();
cy.url().should('include', '/signup');
cy.get('input[name="email"]').type('newuser@example.com');
cy.get('input[name="username"]').type('newuser');
cy.get('input[name="password"]').type('SecurePass123!');
cy.get('button[type="submit"]').click();
cy.url().should('include', '/dashboard');
cy.contains('Welcome, newuser');
// 글 작성 프로세스...
});
});
```
### E2E-002: 글 검색 및 필터링
```javascript
describe('Post Search and Filtering', () => {
before(() => {
cy.seedDatabase();
});
it('should filter posts by tag', () => {
cy.visit('/');
cy.get('[data-testid="tag-filter"]').select('React');
cy.get('[data-testid="post-list"]')
.find('[data-testid="post-card"]')
.each($card => {
cy.wrap($card).should('contain', 'React');
});
});
});
```
## Test Coverage Tracking
**Current Coverage Status** (Updated: 2024-03-20)
```
Overall: 75% (Target: 80%)
├── Frontend: 72%
│ ├── Components: 78%
│ ├── Hooks: 65%
│ └── Utils: 85%
└── Backend: 78%
├── Routes: 82%
├── Controllers: 75%
└── Models: 70%
Critical Paths: 92%
```
**Coverage Requirements**:
- PR 머지 조건: 커버리지 감소 금지
- 새 코드는 최소 80% 커버리지 필수
- 핵심 비즈니스 로직은 90% 이상
**Uncovered Areas** (Action Required):
1. `/server/models/Post.js` - validation 함수들
2. `/client/src/hooks/useInfiniteScroll.js` - edge cases
3. `/client/src/utils/markdown.js` - 특수 문자 처리
## CI/CD Test Automation
**GitHub Actions Workflow**:
```yaml
name: Test Suite
on: [pull_request]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Run Unit Tests
run: npm test -- --coverage
- name: Run Integration Tests
run: npm run test:integration
- name: Run E2E Tests
run: npm run test:e2e
- name: Upload Coverage
uses: codecov/codecov-action@v2
- name: Check Coverage Threshold
run: npm run test:coverage-check
```버그 추적 및 문제 해결 프로세스
테스트 과정에서 발견된 버그는 claude.md의 '이슈 트래커(Issue Tracker)' 섹션에 기록합니다.
각 버그에는 고유 ID, 심각도, 재현 방법, 영향 범위, 현재 상태를 명시합니다. 재현 단계를 상세히 기록하여 누구나 동일한 버그를 재현할 수 있게 합니다.
버그 우선순위 시스템을 정의합니다.
"Critical: 서비스 중단, High: 핵심 기능 불가, Medium: 기능 제한적 동작, Low: UI 결함/개선사항"처럼 4단계로 분류합니다. 각 우선순위별 SLA(Service Level Agreement)도 설정하여 "Critical은 4시간 내 수정, High는 24시간 내, Medium은 1주일 내"처럼 대응 시간을 명확히 합니다.
각 버그의 해결 과정과 원인 분석을 기록합니다.
이는 유사한 버그를 예방하고, 팀 전체가 학습하는 데 도움이 됩니다. AI와 대화할 때도 "이전에 BUG-001에서 useEffect 의존성 문제가 있었는데, 이 코드도 같은 패턴인지 확인해줘"처럼 과거 버그를 참조할 수 있습니다.
회귀 테스트(Regression Tests) 계획도 수립합니다.
수정된 버그가 다시 발생하지 않도록 각 버그마다 테스트 케이스를 추가합니다. Claude.md에 "수정된 버그는 반드시 회귀 테스트 추가" 규칙을 명시하여 일관된 품질 관리를 유지합니다.
Claude.md - 버그 추적과 문제 해결 프로세스 예시
# Bug Tracking & Resolution Process
## Issue Tracker
**BUG-001: 로그인 후 리다이렉트 실패** Critical - Fixed
- **Reported**: 2024-03-18
- **Reporter**: QA 테스터
- **Severity**: Critical (서비스 핵심 기능 불가)
- **Affected**: 모든 사용자
- **Status**: Fixed (2024-03-19), Verified (2024-03-20)
**Reproduction Steps**:
1. 로그인 페이지 접속 (`/login`)
2. 올바른 이메일/비밀번호 입력
3. "Login" 버튼 클릭
4. **Expected**: `/dashboard`로 리다이렉트
5. **Actual**: `/login`에 남아있음, 콘솔 에러 없음
**Root Cause**:
- `LoginPage.tsx`에서 `useNavigate` 훅 사용
- `useEffect`에서 로그인 성공 시 리다이렉트 실행
- 의존성 배열에 `navigate` 함수 누락
- React strict mode에서 두 번 실행되어 navigate 무효화
**Solution**:
```typescript
// Before (버그)
useEffect(() => {
if (isAuthenticated) {
navigate('/dashboard');
}
}, [isAuthenticated]); // navigate 누락
// After (수정)
const handleNavigation = useCallback(() => {
if (isAuthenticated) {
navigate('/dashboard');
}
}, [isAuthenticated, navigate]);
useEffect(() => {
handleNavigation();
}, [handleNavigation]);
```
**Regression Test Added**:
```typescript
// cypress/e2e/auth.cy.js
it('should redirect to dashboard after login', () => {
cy.visit('/login');
cy.get('input[name="email"]').type('test@example.com');
cy.get('input[name="password"]').type('password123');
cy.get('button[type="submit"]').click();
cy.url().should('include', '/dashboard');
cy.contains('Welcome back').should('be.visible');
});
```
**Related Commits**: `fix(auth): add navigate to useEffect deps (BUG-001)`
---
**BUG-002: 마크다운 코드 블록 하이라이팅 깨짐** Medium - In Progress
- **Reported**: 2024-03-19
- **Reporter**: 베타 사용자
- **Severity**: Medium (기능 동작하나 UX 저하)
- **Affected**: 코드 블록이 있는 글 조회 시
**Reproduction Steps**:
1. 코드 블록이 포함된 글 작성
2. 글 게시 후 조회
3. **Expected**: Syntax highlighting 적용
4. **Actual**: 일반 텍스트로 표시
**Initial Analysis**:
- `react-markdown` 사용 중
- `react-syntax-highlighter` 설치되어 있음
- 코드 블록 컴포넌트에 제대로 연결되지 않은 것으로 추정
**Assigned To**: 박프론트
**Target Fix Date**: 2024-03-22
---
**BUG-003: 페이지네이션 마지막 페이지 에러** High - Fixed
- **Reported**: 2024-03-20
- **Severity**: High (주요 기능 장애)
**Root Cause**:
```javascript
// Before: 잘못된 계산
const hasNextPage = currentPage * limit < totalCount;
// 문제: currentPage가 1-based인데 0-based로 계산
// After: 수정
const hasNextPage = currentPage < Math.ceil(totalCount / limit);
```
**Prevention Measure**:
- 유사 버그 방지를 위해 페이지네이션 유틸 함수 작성
- 단위 테스트 추가하여 edge case 커버
## Bug Priority System
**Priority Levels**:
- **Critical**:
- 서비스 완전 중단
- 데이터 손실 위험
- 보안 취약점
- SLA: 4시간 이내 수정
- **High**:
- 핵심 기능 불가
- 다수 사용자 영향
- Workaround 없음
- SLA: 24시간 이내 수정
- **Medium**:
- 기능 제한적 동작
- 일부 사용자 영향
- Workaround 존재
- SLA: 1주일 이내 수정
- **Low**:
- UI/UX 개선사항
- 마이너 불편
- 기능에 영향 없음
- SLA: 다음 스프린트
## Bug Resolution Workflow
```
버그 발견
↓
Issue 등록 (고유 ID 부여)
↓
심각도 평가 (Priority 할당)
↓
원인 분석 (Root Cause Analysis)
↓
해결 방법 설계
↓
코드 수정 + 테스트
↓
회귀 테스트 추가
↓
코드 리뷰 + QA 검증
↓
배포 + 모니터링
↓
이슈 종료 (문서화 완료)
```
## Known Issues & Workarounds
**ISSUE-001: 대용량 이미지 업로드 느림**
- **Status**: Open (Low priority)
- **Description**: 5MB 이상 이미지 업로드 시 30초 이상 소요
- **Workaround**: 이미지 사전 압축 권장 (권장 크기: 1MB 이하)
- **Long-term Fix**: v2.0에서 클라이언트 사이드 이미지 압축 구현 예정
**ISSUE-002: Safari 특정 버전에서 마크다운 에디터 스크롤 버그**
- **Status**: Investigating
- **Affected**: Safari 14.x 이하
- **Workaround**: Chrome/Firefox 사용 권장
- **Note**: Safari 14는 전체 사용자의 2% 미만
## Lessons Learned
**From BUG-001 (로그인 리다이렉트)**:
- **Prevention**: useEffect 사용 시 ESLint exhaustive-deps 규칙 활성화
- **Detection**: E2E 테스트에 주요 사용자 플로우 반드시 포함
- **Documentation**: React Hooks 사용 가이드라인 문서 작성
**From BUG-003 (페이지네이션)**:
- **Prevention**: 경계값(boundary values) 테스트 케이스 추가
- **Reusability**: 공통 로직은 유틸 함수로 추출하여 재사용
- **Testing**: Off-by-one 에러에 민감한 로직은 테스트 필수
## Regression Test Coverage
모든 수정된 버그는 자동 회귀 테스트를 포함합니다:
- BUG-001: E2E 로그인 플로우 테스트
- BUG-002: 마크다운 렌더링 단위 테스트
- BUG-003: 페이지네이션 edge case 테스트
**CI/CD Integration**:
회귀 테스트는 모든 PR과 배포 시 자동 실행되며, 실패 시 배포 차단됩니다.
6. 배포 단계에서의 Claude.md 활용
배포 전략 및 환경 설정
배포 단계에서는 claude.md에 상세한 배포 계획을 기록합니다.
먼저 배포 환경을 명확히 정의합니다.
"Development (로컬 개발), Staging (테스트 및 QA), Production (실제 서비스)"처럼 각 환경의 목적과 특징을 설명합니다. 각 환경별 접근 URL, 데이터베이스 연결 정보, API 엔드포인트를 문서화하되, 민감한 정보는 환경변수로 관리하고 claude.md에는 변수명만 명시합니다.
배포 프로세스를 단계별로 상세히 기술합니다.
각 단계에서 수행해야 할 구체적인 작업과 확인 사항을 포함합니다. 예를 들어 "프로덕션 배포 전 체크리스트: 모든 테스트 통과, 데이터베이스 마이그레이션 준비, 롤백 계획 수립, 모니터링 알림 설정"처럼 빠뜨릴 수 없는 항목들을 나열합니다.
CI/CD 파이프라인 설정을 문서화합니다.
GitHub Actions, GitLab CI, Jenkins 등 사용하는 도구와 구체적인 워크플로우를 설명합니다. 실패 시 알림 방법과 롤백 절차도 함께 기록합니다.
환경변수 관리 전략도 중요합니다.
각 환경별로 필요한 변수 목록과 설정 방법을 안내합니다. 새로운 환경변수가 추가될 때마다 claude.md를 업데이트하여 모든 환경에서 일관되게 설정되도록 합니다. AI에게 배포 스크립트 작성을 요청할 때도 이 정보를 참조하여 올바른 환경 설정을 포함하도록 할 수 있습니다.
Claude.md - 배포 전략 및 환경 설정 예시
# Deployment Strategy & CI/CD
## Environments
**Development (Local)**
- **Purpose**: 로컬 개발 및 단위 테스트
- **URL**: http://localhost:3000 (frontend), http://localhost:5000 (backend)
- **Database**: Local MongoDB (localhost:27017)
- **Features**: Hot reload, debug mode, mock data
**Staging**
- **Purpose**: QA 테스트 및 통합 테스트
- **URL**: https://staging-blog.vercel.app
- **Database**: MongoDB Atlas (staging cluster)
- **Features**: Production-like environment, test data
- **Access**: QA team, developers
**Production**
- **Purpose**: 실제 서비스
- **URL**: https://blog.example.com
- **Database**: MongoDB Atlas (production cluster)
- **Features**: 최적화된 빌드, 모니터링, 백업
- **Access**: Public
## Environment Variables
**Required Variables per Environment**:
```bash
# Backend (.env)
NODE_ENV=development|staging|production
PORT=5000
MONGODB_URI=<database_connection_string>
JWT_SECRET=<random_secret_key>
JWT_EXPIRES_IN=24h
# External Services
CLOUDINARY_CLOUD_NAME=<your_cloud_name>
CLOUDINARY_API_KEY=<your_api_key>
CLOUDINARY_API_SECRET=<your_api_secret>
# Frontend (.env)
VITE_API_URL=http://localhost:5000/api
VITE_APP_NAME=DevBlog
```
**Management**:
- Local: `.env` 파일 (Git ignore)
- Staging/Production: Platform secrets (Vercel, Railway)
- Critical secrets: Never commit to repository
- Rotation: JWT_SECRET은 6개월마다 갱신
## Deployment Process
**Pre-deployment Checklist**
- [ ] 모든 테스트 통과 (Unit, Integration, E2E)
- [ ] 코드 리뷰 완료 및 승인
- [ ] Changelog 업데이트
- [ ] 데이터베이스 마이그레이션 스크립트 준비
- [ ] 롤백 계획 수립
- [ ] 모니터링 알림 설정 확인
**Deployment Steps**:
**Step 1: Code Review & Merge**
```bash
# feature 브랜치에서 develop으로 PR
git checkout develop
git pull origin develop
git merge feature/my-feature
git push origin develop
```
**Step 2: Staging Deployment (Automatic)**
- GitHub Actions trigger on `develop` branch push
- Run CI pipeline (lint, test, build)
- Deploy to Vercel staging environment
- Run smoke tests
**Step 3: QA Testing**
- QA team tests on staging
- Report any issues via GitHub Issues
- Developers fix bugs in develop branch
- Repeat until QA approval
**Step 4: Production Deployment**
```bash
# develop에서 main으로 PR (requires approval)
git checkout main
git merge develop --no-ff
git tag -a v1.0.0 -m "Release v1.0.0"
git push origin main --tags
```
**Step 5: Post-deployment**
- Monitor error rates for 24 hours
- Check performance metrics
- Verify critical user flows
- Update documentation if needed
## CI/CD Pipeline (GitHub Actions)
**Workflow: Deploy to Staging**
```yaml
name: Deploy to Staging
on:
push:
branches: [develop]
jobs:
test-and-deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Setup Node
uses: actions/setup-node@v2
with:
node-version: '20'
- name: Install dependencies
run: |
cd client && npm ci
cd ../server && npm ci
- name: Run linters
run: |
cd client && npm run lint
cd ../server && npm run lint
- name: Run tests
run: |
cd server && npm test -- --coverage
cd ../client && npm test -- --coverage
- name: Build frontend
run: cd client && npm run build
- name: Deploy to Vercel
uses: amondnet/vercel-action@v20
with:
vercel-token: ${{ secrets.VERCEL_TOKEN }}
vercel-org-id: ${{ secrets.ORG_ID }}
vercel-project-id: ${{ secrets.PROJECT_ID }}
working-directory: ./client
- name: Deploy backend to Railway
run: railway up --service blog-api
env:
RAILWAY_TOKEN: ${{ secrets.RAILWAY_TOKEN }}
- name: Run smoke tests
run: npm run test:smoke
- name: Notify Slack
uses: 8398a7/action-slack@v3
with:
status: ${{ job.status }}
text: 'Staging deployment completed'
```
**Workflow: Deploy to Production**
```yaml
name: Deploy to Production
on:
push:
branches: [main]
tags: ['v*']
jobs:
deploy-production:
runs-on: ubuntu-latest
environment: production
steps:
- uses: actions/checkout@v2
- name: Setup Node
uses: actions/setup-node@v2
- name: Install and Test
run: |
npm ci
npm test
- name: Deploy to Production
uses: amondnet/vercel-action@v20
with:
vercel-token: ${{ secrets.VERCEL_TOKEN }}
vercel-args: '--prod'
- name: Database Migration
run: npm run migrate:prod
env:
DATABASE_URL: ${{ secrets.PROD_DATABASE_URL }}
- name: Health Check
run: |
sleep 30
curl -f https://blog.example.com/api/health || exit 1
- name: Notify Team
uses: 8398a7/action-slack@v3
with:
status: ${{ job.status }}
text: '🚀 Production deployment v${{ github.ref_name }}'
```
## Rollback Strategy
**Automatic Rollback**:
- Health check 실패 시 이전 버전으로 자동 롤백
- Error rate 급증 시 알림 및 수동 롤백 판단
**Manual Rollback**:
```bash
# Vercel: 이전 배포로 롤백
vercel rollback <deployment-url>
# Railway: 이전 버전 재배포
railway rollback <version-id>
# 데이터베이스 마이그레이션 롤백
npm run migrate:down
```
**Rollback Decision Criteria**:
- 에러율 > 5% (정상 대비 2배 이상)
- 응답 시간 > 3초 (정상 대비 3배 이상)
- 크리티컬 기능 장애 발생
- 데이터 무결성 문제 발견
## Monitoring & Alerting
**Monitoring Tools**:
- **Application**: Sentry (에러 추적)
- **Performance**: Vercel Analytics
- **Uptime**: UptimeRobot (5분 간격 ping)
- **Logs**: Railway Logs, Vercel Logs
**Alert Conditions**:
- Critical: 서비스 다운, 5분 내 복구 필요
- Warning: 성능 저하, 1시간 내 조사 필요
- Info: 이상 징후, 모니터링 필요
**Alert Channels**:
- Slack #alerts 채널
- Email (긴급 연락처)
- SMS (Critical alerts only)
## Performance Optimization
**Frontend**:
- Code splitting (React.lazy)
- Image optimization (Cloudinary auto-format)
- Asset compression (Gzip/Brotli)
- CDN caching (Vercel Edge Network)
**Backend**:
- Database indexing (복합 인덱스 활용)
- API response caching (Redis, 5분 TTL)
- Rate limiting (100 req/min per IP)
- Compression middleware (gzip)
**Database**:
- Connection pooling (10 connections)
- Query optimization (explain analyze)
- Slow query logging (>100ms)
## Deployment History
**v1.0.0 (2024-04-26)**
- Initial production release
- Features: 인증, 글 CRUD, 마크다운 에디터
- Performance: 평균 응답 시간 150ms
- Issues: None
**v1.1.0 (2024-05-10)**
- Comments system
- Search & filtering
- Performance: 평균 응답 시간 180ms
- Issues: Minor CSS bug (hotfixed)
**Next Deployment (Planned)**
- v1.2.0: 소셜 공유, RSS 피드 (예정일: 2024-06-01)7. Claude.md 문서량 관리 및 서브 파일 전략
프로젝트가 성장하면서 claude.md는 점점 방대해집니다. 문서가 지나치게 길어지면 AI가 전체 맥락을 파악하기 어렵고, 개발자도 원하는 정보를 찾기 힘들어집니다. 따라서 적절한 문서 분리 전략이 필요합니다. 기본 원칙은 "claude.md는 프로젝트의 개요와 핵심 정보만 포함하고, 상세 내용은 별도 문서로 분리"하는 것입니다. claude.md의 크기는 200-300줄 정도로 유지하며, 각 섹션에서 "자세한 내용은 /docs/architecture.md 참조" 같은 링크를 제공합니다.
서브 파일 구조를 체계적으로 설계합니다.
"/docs" 디렉토리를 만들고 주제별로 문서를 분리합니다. "architecture.md (시스템 아키텍처 상세), api-spec.md (API 전체 명세), testing-guide.md (테스트 가이드), deployment.md (배포 매뉴얼), troubleshooting.md (문제 해결 가이드)"처럼 각 문서가 명확한 목적을 갖도록 합니다. 각 파일은 독립적으로 이해 가능하면서도 claude.md와 연결되어 전체 문서 생태계를 형성합니다.
claude.md에는 각 서브 파일로의 링크와 간단한 설명을 포함합니다.
"## Documentation Index" 섹션을 만들어 이모지와 함께 직관적으로 정리합니다. AI에게 특정 주제에 대해 질문할 때 "architecture.md를 참고해서 데이터베이스 구조를 설명해줘"라고 지시할 수 있습니다.
버전 관리 측면에서 서브 파일도 claude.md와 함께 관리합니다.
주요 변경 시 각 문서의 버전을 명시하고, claude.md에 "마지막 업데이트: 2024-03-25"처럼 날짜를 기록합니다. 문서 간 참조가 깨지지 않도록 링크를 상대 경로로 유지하고, 파일 이름이나 위치가 변경될 때는 모든 참조를 업데이트합니다. Git에서 문서 변경 이력을 추적하여 언제 어떤 문서가 왜 변경되었는지 확인할 수 있게 합니다.
Claude.md - 문서량 관리 및 서브 파일 전략 예시
---
# Claude.md - Blog Site Project
version: 2.0.0
last_updated: 2024-04-26
maintained_by: 개발팀
---
# Blog Site Project
> **프로젝트 개요**: 개발자를 위한 마크다운 기반 블로그 플랫폼
> **기술 스택**: React, TypeScript, Node.js, Express, MongoDB
> **현재 상태**: v1.0.0 Production 배포 완료
---
## Documentation Index
이 프로젝트의 상세 문서는 주제별로 분리되어 있습니다. 필요한 정보에 따라 아래 문서를 참조하세요.
### 핵심 문서
- **[Architecture Guide](./docs/architecture.md)** (45KB)
- 시스템 구조 및 컴포넌트 설계
- 데이터베이스 스키마 상세
- API 설계 원칙
- *Last updated: 2024-04-20*
- **[Testing Guide](./docs/testing-guide.md)** (38KB)
- 테스트 전략 및 커버리지 목표
- 단위/통합/E2E 테스트 작성법
- 현재 테스트 상태 및 미완성 영역
- *Last updated: 2024-04-25*
- **[Deployment Manual](./docs/deployment.md)** (32KB)
- 배포 환경 설정
- CI/CD 파이프라인 상세
- 롤백 및 모니터링
- *Last updated: 2024-04-26*
### 개발 가이드
- **[Development Guide](./docs/development.md)** (28KB)
- 개발 환경 설정
- 코딩 표준 및 베스트 프랙티스
- Git 워크플로우
- *Last updated: 2024-03-15*
- **[Design System](./docs/design-system.md)** (22KB)
- 색상, 타이포그래피, 스페이싱
- UI 컴포넌트 라이브러리
- 디자인 토큰 및 사용법
- *Last updated: 2024-03-10*
### 운영 문서
- **[Troubleshooting Guide](./docs/troubleshooting.md)** (25KB)
- 일반적인 문제 및 해결 방법
- 버그 히스토리 및 해결 사례
- 디버깅 팁
- *Last updated: 2024-04-22*
- **[API Reference](./docs/api-reference.md)** (40KB)
- 전체 API 엔드포인트 명세
- 요청/응답 예시
- 에러 코드 정의
- *Last updated: 2024-04-15*
### 기획 및 전략
- **[Product Roadmap](./docs/roadmap.md)** (15KB)
- v1.0 이후 계획
- 기능 우선순위
- 장기 비전
- *Last updated: 2024-04-01*
- **[Change Log](./CHANGELOG.md)** (12KB)
- 버전별 변경 이력
- 버그 수정 내역
- 마이그레이션 가이드
- *Last updated: 2024-04-26*
---
## Quick Start
### 프로젝트 개요
**목적**: 기술 블로거를 위한 경량 블로그 플랫폼
**핵심 가치**: 빠른 글 작성, 코드 하이라이팅, SEO 최적화
**타겟 사용자**: 개발자, 기술 블로거
### 기술 스택
```
Frontend: React 18.2 + TypeScript 5.0 + Tailwind CSS 3.3
Backend: Node.js 20 + Express 4.18
Database: MongoDB 6.0 + Mongoose
Auth: JWT + bcrypt
Hosting: Vercel (Frontend) + Railway (Backend)
```
### 프로젝트 구조
```
/blog-site
├── /client # React 프론트엔드
│ ├── /src
│ │ ├── /components # UI 컴포넌트
│ │ ├── /pages # 라우트 페이지
│ │ └── /services # API 클라이언트
│ └── package.json
├── /server # Express 백엔드
│ ├── /routes # API 라우트
│ ├── /models # Mongoose 모델
│ └── /middleware # 인증 등
├── /docs # 상세 문서 (서브 파일)
│ ├── architecture.md
│ ├── testing-guide.md
│ └── deployment.md
└── claude.md # 이 파일 (중앙 인덱스)
```
상세 구조는 [Architecture Guide](./docs/architecture.md) 참조.
### 로컬 개발 시작
```bash
# 저장소 클론
git clone https://github.com/yourorg/blog-site.git
cd blog-site
# 의존성 설치
cd client && npm install
cd ../server && npm install
# 환경변수 설정
cp server/.env.example server/.env
# .env 파일 편집
# 개발 서버 실행
cd server && npm run dev # 포트 5000
cd client && npm run dev # 포트 3000
```
더 자세한 설정은 [Development Guide](./docs/development.md) 참조.
---
## 핵심 규칙 (Quick Reference)
### 코딩 컨벤션
- **네이밍**: 컴포넌트 PascalCase, 함수 camelCase, 상수 UPPER_SNAKE_CASE
- **파일**: 컴포넌트는 폴더로 (index.tsx + types.ts + test.tsx)
- **주석**: JSDoc 형식, 복잡한 로직에는 인라인 주석
상세 규칙은 [Development Guide - Coding Standards](./docs/development.md#coding-standards) 참조.
### Git 워크플로우
```
main (프로덕션)
↓
develop (개발 통합)
↓
feature/* (기능 개발)
```
- **커밋 메시지**: Conventional Commits 형식
- **PR 요구사항**: 최소 1명 리뷰, 모든 테스트 통과
자세한 워크플로우는 [Development Guide - Git Workflow](./docs/development.md#git-workflow) 참조.
### 테스트 요구사항
- **커버리지 목표**: 전체 80%, 핵심 로직 90%
- **테스트 타입**: 단위 (Jest) + 통합 (Supertest) + E2E (Cypress)
- **PR 조건**: 모든 테스트 통과 + 커버리지 유지
현재 테스트 상태 및 가이드는 [Testing Guide](./docs/testing-guide.md) 참조.
---
## 문서 유지보수 규칙
### 문서 크기 관리
- **claude.md**: 200-300줄 유지 (개요 및 인덱스)
- **서브 파일**: 각 50KB 이하 권장
- **원칙**: 상세 내용은 분리, claude.md는 내비게이션 역할
### 문서 업데이트 시기
1. **Architecture.md**: 시스템 구조 변경 시
2. **API Reference**: 새 엔드포인트 추가 시
3. **Testing Guide**: 테스트 전략 변경 시
4. **Deployment Manual**: 배포 프로세스 변경 시
5. **Claude.md**: 위 문서들의 링크나 개요 변경 시
### 버전 관리
- 각 문서 상단에 `last_updated` 날짜 기록
- 주요 변경 시 CHANGELOG.md에 기록
- Git 커밋 메시지에 변경 이유 명시
---
## AI와 협업 시 참고사항
### Claude와 대화할 때 유용한 패턴
**아키텍처 관련 질문 시**:
```
"architecture.md를 참고해서 Post 컬렉션의 스키마를 설명해줘"
"현재 시스템 구조에서 댓글 기능을 추가하려면 어떤 변경이 필요할까?"
```
**코드 작성 요청 시**:
```
"development.md의 코딩 표준에 맞춰 PostEditor 컴포넌트를 만들어줘"
"api-reference.md의 응답 형식으로 GET /api/posts 핸들러를 작성해줘"
```
**테스트 코드 요청 시**:
```
"testing-guide.md를 참고해서 fetchUserPosts 함수의 단위 테스트를 작성해줘"
"현재 커버리지 상태를 보고 어떤 부분의 테스트를 추가해야 할지 제안해줘"
```
**배포 관련 질문 시**:
```
"deployment.md를 보고 스테이징 환경 배포 절차를 요약해줘"
"프로덕션 배포 전 체크리스트를 확인하고 누락된 항목이 있는지 알려줘"
```
### 컨텍스트 제공 팁
- 특정 문서를 명시적으로 참조 ("[문서명]을 참고해서...")
- 현재 작업 단계 언급 ("지금 구현 단계인데...")
- 관련 작업 ID 포함 ("TASK-007과 관련해서...")
---
## 연락처 및 리소스
**프로젝트 리더**: 김개발 (dev@example.com)
**저장소**: https://github.com/yourorg/blog-site
**배포 URL**: https://blog.example.com
**문서 피드백**: GitHub Issues 또는 Slack #blog-project
**외부 리소스**:
- [React 공식 문서](https://react.dev)
- [Express 가이드](https://expressjs.com)
- [MongoDB Docs](https://docs.mongodb.com)
---
*이 문서는 프로젝트의 진입점입니다. 상세 정보는 위의 Documentation Index에서 관련 문서를 참조하세요.*
8. 고급 활용 : Claude.md와 타 문서의 연계
전략 문서와의 통합
Claude.md는 단순히 기술 문서를 넘어 프로젝트의 전략적 문서와도 연계됩니다.
"STRATEGY.md"와 같은 별도의 전략 문서를 만들어 비즈니스 목표, 타겟 시장, 성장 전략을 정의합니다. Claude.md에서는 전략적 맥락을 간략히 언급하고 링크를 제공합니다. 이렇게 하면 AI와 대화할 때 단순히 기술적 구현뿐만 아니라 비즈니스 가치를 고려한 조언을 받을 수 있습니다.
"RULES.md" 파일을 만들어 프로젝트의 불변 규칙을 정의합니다.
"절대 사용자 비밀번호를 평문으로 저장하지 않는다", "모든 API는 HTTPS를 통해서만 접근 가능하다", "개인정보는 최소한으로만 수집한다"처럼 타협할 수 없는 원칙들을 명시합니다. Claude.md에서 이 파일을 참조하여 보안 및 프라이버시 원칙을 강조합니다.
"GUIDE.md" 시리즈로 다양한 가이드 문서를 작성합니다.
"ONBOARDING_GUIDE.md (신규 팀원을 위한 온보딩), CONTRIBUTION_GUIDE.md (기여자 가이드), RELEASE_GUIDE.md (릴리스 프로세스)"처럼 역할이나 상황별 가이드를 제공합니다. Claude.md는 이러한 가이드들의 디렉토리 역할을 하며, 역할별로 안내합니다.
문서 간 상호 참조를 명확히 합니다.
예를 들어 DEPLOYMENT.md에서 "배포 시 RULES.md의 보안 체크리스트를 확인하세요"라고 링크하고, TESTING_GUIDE.md에서 "테스트 커버리지 목표는 STRATEGY.md의 품질 기준에 따릅니다"처럼 연결합니다. 이렇게 하면 문서들이 독립적이면서도 일관된 메시지를 전달합니다.
Claude.md - 전략 문서와의 통합 예시
# Related Documentation Ecosystem
## 전략 및 정책 문서
### STRATEGY.md (20KB)
- 비즈니스 목표 및 성공 지표
- 타겟 사용자 페르소나
- 경쟁 분석 및 차별화 전략
- 성장 로드맵 (6개월/1년/3년)
**연계 방식**:
```markdown
# claude.md에서 참조
이 프로젝트는 STRATEGY.md에 정의된 "개발자 커뮤니티 활성화"
전략의 핵심 도구입니다. 모든 기능 개발은 전략 문서의
"지식 공유 촉진" 목표와 정렬되어야 합니다.
# AI와 대화 시
"STRATEGY.md를 참고해서, 댓글 기능이 우리 비즈니스 목표에
어떻게 기여할 수 있는지 분석해줘"
```
---
### ⚖️ RULES.md (10KB)
- 절대 규칙 (Non-negotiable Rules)
- 보안 및 프라이버시 원칙
- 접근성 요구사항 (WCAG 2.1 AA)
- 데이터 처리 정책
**절대 규칙 예시**:
```markdown
## Security Rules
1. 비밀번호를 평문으로 저장하지 않는다
bcrypt로 해싱 (salt rounds ≥ 10)
2. 사용자 입력을 검증 없이 데이터베이스에 저장하지 않는다
Joi 스키마 검증 + sanitization
3. 에러 메시지에 민감한 정보를 포함하지 않는다
일반적인 메시지만 클라이언트에 반환
4. HTTP로 API를 제공하지 않는다
모든 API는 HTTPS 필수
```
**연계 방식**:
```markdown
# claude.md에서 참조
모든 개발 결정은 RULES.md의 보안 및 프라이버시 원칙을
준수해야 하며, 이는 어떤 상황에서도 타협할 수 없습니다.
# AI와 대화 시
"RULES.md를 참고해서, 이 코드가 보안 규칙을 위반하는지 확인해줘"
"비밀번호 재설정 기능을 RULES.md 원칙에 맞게 구현해줘"
```
---
## 가이드 문서 시리즈
### ONBOARDING_GUIDE.md (25KB)
- 신규 팀원을 위한 첫 주 가이드
- 개발 환경 설정 (상세 단계)
- 첫 번째 기여 미션
- 멘토링 프로세스
**목차 예시**:
```markdown
## Week 1: Getting Started
### Day 1: Environment Setup
1. 저장소 클론 및 의존성 설치
2. 로컬 MongoDB 설정
3. IDE 설정 (VS Code + Extensions)
4. 첫 번째 실행 및 테스트
### Day 2-3: Code Walkthrough
- Frontend 구조 둘러보기
- Backend API 이해하기
- Database 스키마 학습
### Day 4-5: First Contribution
- "good first issue" 찾기
- PR 작성 및 리뷰 받기
- 코드 리뷰 프로세스 경험
```
---
### CONTRIBUTION_GUIDE.md (18KB)
- 오픈소스 기여자를 위한 가이드
- 이슈 리포팅 방법
- PR 작성 가이드라인
- 코드 리뷰 기대사항
**PR 체크리스트 예시**:
```markdown
## Pull Request Checklist
제출 전 확인사항:
- [ ] 코드가 DEVELOPMENT.md의 코딩 표준을 따르는가?
- [ ] 모든 테스트가 통과하는가?
- [ ] 새 기능에 테스트를 추가했는가?
- [ ] 문서를 업데이트했는가?
- [ ] 커밋 메시지가 Conventional Commits을 따르는가?
- [ ] CHANGELOG.md에 변경사항을 기록했는가?
```
---
### RELEASE_GUIDE.md (15KB)
- 릴리스 프로세스 체크리스트
- 버전 번호 결정 (Semantic Versioning)
- Release notes 작성 가이드
- 배포 후 검증 절차
**릴리스 체크리스트 예시**:
```markdown
## Pre-Release Checklist (v1.x.x)
1주 전:
- [ ] Feature freeze: 새 기능 머지 중단
- [ ] 모든 테스트 통과 확인
- [ ] 문서 업데이트 완료
3일 전:
- [ ] 스테이징에 RC (Release Candidate) 배포
- [ ] QA 전체 테스트 수행
- [ ] 성능 벤치마크 실행
릴리스 당일:
- [ ] Git 태그 생성 (v1.x.x)
- [ ] Production 배포
- [ ] Health check 모니터링 (24시간)
- [ ] GitHub Release 게시
```
---
## 문서 간 상호 참조 패턴
**Pattern 1: 전략적 정당성 참조**
```markdown
# api-reference.md에서
## Rate Limiting
모든 API는 분당 100회 요청 제한이 있습니다.
이는 STRATEGY.md의 "안정적인 서비스 제공" 목표를 지원합니다.
[전략 문서 참조](../STRATEGY.md#service-stability)
```
**Pattern 2: 규칙 준수 확인**
```markdown
# deployment.md에서
## Environment Variables
환경변수 설정 시 RULES.md의 보안 원칙을 반드시 확인하세요:
- 민감한 정보는 환경변수로만 관리
- .env 파일은 Git에 커밋하지 않음
[보안 규칙 확인](../RULES.md#secret-management)
```
**Pattern 3: 가이드 안내**
```markdown
# claude.md에서
## For New Team Members
처음 프로젝트에 참여하시나요?
ONBOARDING_GUIDE.md를 먼저 읽어보세요.
## For Contributors
외부 기여자이신가요?
CONTRIBUTION_GUIDE.md에서 PR 프로세스를 확인하세요.
```
---
## AI와 협업 시 활용 예시
**시나리오 1: 새 기능 제안**
```
개발자: "사용자 프로필 기능을 추가하고 싶은데,
STRATEGY.md를 보고 이게 우리 목표와 맞는지 평가해줘"
Claude: [STRATEGY.md 참조]
전략 문서의 "사용자 참여도 향상" 목표와 잘 맞습니다.
다만, RULES.md의 "최소 개인정보 수집" 원칙을
준수하려면 선택적 프로필 항목으로 설계해야 합니다.
```
**시나리오 2: 보안 검토**
```
개발자: "이 로그인 코드가 RULES.md를 위반하는지 확인해줘"
[코드 첨부]
Claude: [RULES.md 참조]
두 가지 문제를 발견했습니다:
1. 비밀번호가 평문으로 비교되고 있습니다
2. 실패 시 "Invalid username" 메시지 노출
```
**시나리오 3: 온보딩 지원**
```
신규 개발자: "프로젝트를 처음 시작하려는데 어디서부터?"
Claude: ONBOARDING_GUIDE.md를 참조하여 단계별로 안내해드리겠습니다.
```
---
## 문서 생태계 유지보수
**업데이트 트리거**:
```markdown
STRATEGY.md 변경 → claude.md 목표 섹션 검토
RULES.md 추가 → 모든 기술 문서에서 준수 확인
GUIDE 추가 → claude.md Documentation Index 업데이트
```
**일관성 검증**:
```bash
# 문서 링크 검증 스크립트
npm run docs:check-links
# 문서 간 모순 검출
npm run docs:consistency-check
```
**문서 리뷰 주기**:
- 월간: Documentation Index 최신 상태 확인
- 분기별: 모든 가이드 문서 리뷰
- 릴리스마다: 변경사항 반영 확인
Claude.md로 완성하는 효율적인 개발 문화
Claude.md는 단순한 문서를 넘어 프로젝트의 두뇌 역할을 합니다.
기획부터 배포까지 모든 단계에서 일관된 방향성을 제공하며, 팀원 간의 소통을 원활하게 하고, AI 어시스턴트와의 협업을 극대화합니다. 이 문서 하나로 프로젝트의 과거를 기록하고, 현재를 관리하며, 미래를 계획할 수 있습니다. 초보 개발자도 claude.md를 통해 프로젝트 전체를 이해하고 기여할 수 있으며, 숙련된 개발자는 의사결정의 근거를 명확히 할 수 있습니다.
효과적인 claude.md는 진화합니다.
프로젝트가 성장하면서 문서도 함께 발전하며, 새로운 요구사항과 학습 내용을 반영합니다. 중요한 것은 문서를 살아있게 유지하는 것입니다. 코드 변경과 함께 문서도 업데이트하고, 팀 회고에서 얻은 인사이트를 기록하며, 버그 해결 과정에서 얻은 교훈을 문서화합니다. 이렇게 축적된 지식은 프로젝트의 가장 귀중한 자산이 되며, 미래의 의사결정에 지혜를 제공합니다.
AI 시대의 개발은 사람과 AI의 협업입니다. Claude.md는 이 협업의 공통 언어이자 지식 베이스입니다.
AI에게 프로젝트의 맥락을 효과적으로 전달하고, 일관된 스타일과 규칙을 유지하며, 복잡한 문제에 대한 정보에 기반한 조언을 받을 수 있게 합니다. 더 나아가, 여러 프로젝트에서 claude.md 패턴을 표준화하면, 팀 전체의 생산성이 향상되고 지식 공유가 더욱 원활해집니다.
이제 여러분의 프로젝트에도 claude.md를 도입해보세요. 작게 시작해도 괜찮습니다. 프로젝트 개요와 기술 스택, 기본 규칙만으로도 큰 효과를 볼 수 있습니다. 프로젝트가 진행되면서 점진적으로 내용을 확장하고, 팀의 필요에 맞게 구조를 조정하세요. Claude.md는 여러분 프로젝트의 성공적인 완성을 돕는 든든한 동반자가 될 것입니다. 체계적인 문서화로 더 나은 개발 문화를 만들어가세요.
'AI 코딩' 카테고리의 다른 글
| Synology NAS Docker Compose 설치에서 운영까지 (1) | 2025.12.03 |
|---|---|
| [Claude] Claude Code MCP 완벽 가이드 (0) | 2025.11.28 |
| 파이썬 코딩에서 추천하는 네이밍 규칙 정리 (0) | 2025.11.18 |
| [개발환경] pyenv - Python 버전을 전환하면서 사용하기 (6) | 2025.11.05 |
| [Claude] Claude Skill기능으로 문서작업 효율 10배 높이기 (1) | 2025.11.03 |
