"Claude야, 로그인 기능 만들어줘"
→ 결과: 엉망진창 코드 + 무엇을 만들었는지 모름

1. "로그인 기능 요구사항 정리를 같이 구상해보자"
2. Claude가 질문 → 답변하며 요구사항 구체화
3. 문서 작성 (기능 명세, API 설계, 테스트 시나리오)
4. 문서 기반으로 개발 시작

1. 목적 (Why): 왜 이 기능이 필요한가?
2. 범위 (What): 어디까지 만들 것인가?
3. 요구사항 (Requirements): 필수 기능 목록
4. 제약사항 (Constraints): 기술/시간/리소스 제한
5. 성공 기준 (Success Criteria): 언제 완성인가?

$ # 나쁜 예: 수동으로 커밋
git add .
git commit -m "수정함"  # ❌ 컨벤션 무시

# 좋은 예: Command 사용
/commit
# → Claude가 변경사항 분석
# → 적절한 타입 선택 (feat/fix/docs...)
# → 컨벤션 형식으로 커밋 메시지 생성
# → 자동 커밋

<!-- .claude/commands/api-doc.md -->
현재 프로젝트의 API 엔드포인트를 분석해서
다음 형식으로 문서를 작성해줘:

## API 명세서

### [HTTP Method] /api/endpoint

**목적:**
**요청 파라미터:**
**응답 형식:**
**에러 코드:**
**예시:**

모든 API를 찾아서 `docs/api-specification.md` 파일로 저장해줘.

$ /api-doc
# → 자동으로 API 문서 생성!

$ # ✅ 좋은 질문 (Claude가 자동으로 Explore Agent 실행)
"이 프로젝트에서 데이터베이스 연결은 어떻게 처리하고 있어?"

# ✅ 좋은 질문 (Claude가 자동으로 Plan Agent 실행)
"사용자 알림 기능을 추가하려고 하는데, 어떤 방식으로 구현하면 좋을까?"

# ❌ 나쁜 질문
"Explore Agent로 데이터베이스 찾아줘"  # 너무 구체적으로 지시

graph LR
    A[아이디어] --> B[요구사항 구체화]
    B --> C[문서 작성]
    C --> D[설계 문서]
    D --> E[개발]
    E --> F[테스트]
    F --> G[배포]

"사용자 프로필 기능을 만들려고 하는데,
어떤 것들을 결정해야 하는지 질문해줘.
질문을 통해 요구사항을 구체화하고 싶어."

좋습니다! 사용자 프로필 기능 요구사항을 구체화하기 위해
몇 가지 질문드릴게요:

1. 프로필에 포함될 정보는?
   - 기본 정보 (이름, 이메일, 프로필 사진 등)
   - 추가 정보 (자기소개, 관심사, SNS 링크 등)

2. 사용자가 직접 수정 가능한가요?
   - 실시간 수정 / 관리자 승인 필요

3. 프로필 공개 범위는?
   - 전체 공개 / 친구만 / 비공개

4. 프로필 사진 처리는?
   - 업로드 방식 (파일 직접 / URL / 소셜 연동)
   - 이미지 크기/형식 제한
   - 저장 위치 (서버 / 클라우드)

5. 인증/권한은?
   - 본인만 수정 가능 / 타인 조회 가능 여부

이 질문들에 답변해주시면 상세한 요구사항 문서를 작성하겠습니다!

1. 기본 정보: 이름, 이메일, 프로필 사진, 학번, 학과
2. 사용자가 직접 실시간 수정 가능
3. 전체 공개 (우리 학교 학생들에게만)
4. 파일 직접 업로드, 5MB 이하 jpg/png, AWS S3 저장
5. 본인만 수정 가능, 타인은 조회만 가능

완벽합니다! 이제 요구사항 문서를 작성하겠습니다.

[docs/features/user-profile-requirements.md](docs/features/user-profile-requirements.md) 파일에
다음 내용을 작성하겠습니다:

- 기능 개요
- 상세 요구사항
- API 엔드포인트 설계
- 데이터베이스 스키마
- 화면 UI 플로우
- 예외 처리 시나리오

# 사용자 프로필 기능 요구사항 명세서

## 1. 기능 개요

### 목적
학생들이 자신의 프로필을 관리하고, 다른 학생의 프로필을 조회할 수 있는 기능

### 범위
- 프로필 조회 (본인 + 타인)
- 프로필 수정 (본인만)
- 프로필 사진 업로드

---

## 2. 요구사항

### 2.1 기능 요구사항 (Functional Requirements)

| ID | 요구사항 | 우선순위 |
|----|----------|----------|
| FR-1 | 사용자는 자신의 프로필을 조회할 수 있다 | High |
| FR-2 | 사용자는 자신의 프로필을 수정할 수 있다 | High |
| FR-3 | 사용자는 다른 학생의 프로필을 조회할 수 있다 | High |
| FR-4 | 프로필 사진을 업로드할 수 있다 | Medium |
| FR-5 | 프로필 수정 이력을 기록한다 | Low |
### 2.2 비기능 요구사항 (Non-Functional Requirements)

| ID | 요구사항 | 기준 |
|----|----------|------|
| NFR-1 | 프로필 조회 응답 시간 | 500ms 이하 |
| NFR-2 | 이미지 업로드 크기 제한 | 5MB 이하 |
| NFR-3 | 지원 이미지 형식 | JPG, PNG |
| NFR-4 | 동시 접속 처리 | 1000명 |
---

## 3. 데이터베이스 스키마

### users 테이블

| 컬럼명 | 타입 | 제약조건 | 설명 |
|--------|------|----------|------|
| id | INT | PRIMARY KEY, AUTO_INCREMENT | 사용자 ID |
| email | VARCHAR(255) | UNIQUE, NOT NULL | 이메일 |
| name | VARCHAR(100) | NOT NULL | 이름 |
| student_id | VARCHAR(20) | UNIQUE, NOT NULL | 학번 |
| department | VARCHAR(100) | NOT NULL | 학과 |
| profile_image_url | VARCHAR(500) | NULL | 프로필 사진 URL |
| created_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP | 생성 시간 |
| updated_at | TIMESTAMP | ON UPDATE CURRENT_TIMESTAMP | 수정 시간 |
---

## 4. API 설계

### 4.1 프로필 조회

**Endpoint:** `GET /api/users/:userId/profile`

**설명:** 특정 사용자의 프로필 조회

**요청 헤더:**
```json
{
  "Authorization": "Bearer {access_token}"
}

{
  "success": true,
  "data": {
    "id": 123,
    "name": "홍길동",
    "email": "hong@example.com",
    "student_id": "2024001",
    "department": "컴퓨터공학과",
    "profile_image_url": "https://s3.../profile.jpg"
  }
}

{
  "name": "홍길동",
  "department": "소프트웨어공학과"
}

{
  "success": true,
  "message": "프로필이 수정되었습니다"
}

{
  "success": true,
  "data": {
    "profile_image_url": "https://s3.amazonaws.com/..."
  }
}

#### Step 4: 문서 검토 및 보완

**문서를 읽고 추가 질문:**

**🤖 Claude가 문서 업데이트:**
- 재시도 로직 섹션 추가
- 썸네일 생성 요구사항 추가
- API 엔드포인트 수정

#### Step 5: 개발 시작

**이제 문서가 완성되었으니 개발 시작!**

**Claude가 문서를 참조하여:**
- DB 스키마 정확히 생성
- API 명세대로 엔드포인트 구현
- 에러 처리 시나리오 반영

---

## 5. 모르겠을 때 대처법: 질문으로 요구사항 구체화하기

### 🤔 막막한 상황들

| 상황 | 나쁜 대응 | 좋은 대응 |
|------|----------|----------|
| 기능 기획 막막함 | "일단 비슷한 거 찾아서 베껴야지" | "Claude야, 이 기능 기획을 같이 구상해보자" |
| 기술 선택 고민 | "그냥 내가 아는 거 쓰자" | "Claude야, 이 상황에 적합한 기술 스택 추천해줘" |
| 설계 방향 모호함 | "대충 만들고 나중에 수정하자" | "Claude야, 여러 설계 옵션과 장단점 알려줘" |

### 📝 질문 유도 템플릿

#### 템플릿 1: 기능 기획 단계

#### 템플릿 2: 기술 선택 단계

#### 템플릿 3: 아키텍처 설계 단계

### 🎯 질문 유도 실전 예시

#### 예시 1: 알림 기능 구현

**초기 요청:**

**Claude의 질문:**

**답변 후 Claude가 생성:**
- 알림 시스템 아키텍처 문서
- API 명세서
- DB 스키마 설계
- 푸시 알림 구현 가이드
- 알림 설정 UI 플로우

#### 예시 2: 검색 기능 개선

**초기 요청:**

**Claude의 질문:**

**답변 후 Claude가 생성:**
- 현재 문제 분석 보고서
- 개선 방안 3가지 비교 (인덱싱, 캐싱, Elasticsearch)
- 각 방안의 성능 예측
- 구현 우선순위 및 로드맵
- 선택한 방안의 구현 가이드

---

## 6. 프로젝트별 실전 예시

### 📱 Case 1: 새로운 기능 추가 (Full Cycle)

**시나리오:** "출석 체크 기능 추가"

#### Phase 1: 기획 및 문서화 (30분)

```bash
# Step 1: 요구사항 구체화
"출석 체크 기능을 추가하려고 해. 어떤 것들을 결정해야 하는지 질문해줘."

# Step 2: Claude의 질문에 답변
# (사용자, 기능 범위, 출석 방식, 예외 처리 등)

# Step 3: PRD 문서 생성 요청
"지금까지의 대화를 바탕으로 docs/features/attendance-system.md 파일에
요구사항 명세서를 작성해줘."

# Step 4: API 설계 문서 생성
"같은 내용으로 API 명세서도 docs/api/attendance-api.md 파일로 만들어줘."

# Step 5: DB 스키마 문서 생성
"DB 스키마 설계서도 docs/database/attendance-schema.md 파일로 작성해줘."

$ # Step 6: 백엔드 API 구현
"docs/api/attendance-api.md 문서를 기반으로
백엔드 API를 구현해줘. src/api/attendance.ts 파일로 만들어줘."

# Step 7: 프론트엔드 구현
"이제 프론트엔드 출석 페이지를 만들자.
src/pages/AttendancePage.tsx 파일로 만들어줘."

# Step 8: 테스트 코드 작성
"API와 컴포넌트에 대한 테스트 코드를 작성해줘."

$ # Step 9: 커밋
/commit
# → Claude가 자동으로 변경사항 분석해서 커밋 메시지 생성

# Step 10: PR 생성
/pr
# → Claude가 변경사항 요약해서 PR 작성

$ # Step 1: 문제 탐색 (Explore Agent 자동 실행)
"로그인 후 리다이렉트가 안 되는 문제가 있어.
관련 코드를 찾아서 문제 원인을 분석해줘."

# Claude가 자동으로:
# - 로그인 관련 파일 탐색
# - 리다이렉트 로직 분석
# - 문제 원인 파악

# Step 2: 수정
"문제를 수정해줘."

# Step 3: 테스트 시나리오 확인
"이 버그가 다시 발생하지 않도록 테스트 코드를 추가해줘."

# Step 4: 커밋
/commit
# → "fix: 로그인 후 리다이렉트 오류 수정"

$ # Step 1: 현재 상태 문서화
"src/api/legacy/ 폴더의 코드를 분석해서
현재 구조와 문제점을 문서로 작성해줘.
docs/refactoring/legacy-api-analysis.md 파일로 만들어줘."

# Step 2: 리팩토링 계획 수립 (Plan Agent 자동 실행)
"이 레거시 코드를 리팩토링하려고 해.
어떤 순서로 진행하면 좋을지 계획을 세워줘."

# Claude가 생성하는 계획:
# 1. 타입 정의 추가
# 2. 중복 코드 제거
# 3. 에러 처리 개선
# 4. 테스트 코드 추가
# 5. 문서화

# Step 3: 단계별 리팩토링
"1단계부터 시작하자. 타입 정의를 추가해줘."
"2단계 진행해줘."
...

# Step 4: 각 단계마다 커밋
/commit

$ # Step 1: 프로젝트 기획 문서 작성 (중요!)
"학교 동아리 관리 시스템을 만들려고 해.
프로젝트 전체 구조를 같이 기획해보자.
어떤 것들을 결정해야 하는지 질문해줘."

# Claude의 질문:
# - 주요 기능 (동아리 등록, 회원 관리, 활동 기록 등)
# - 사용자 역할 (학생, 동아리 회장, 관리자)
# - 기술 스택
# - 배포 환경
# 등등...

# Step 2: 답변 후 프로젝트 문서 생성
"지금까지의 대화를 바탕으로 다음 문서들을 작성해줘:
1. docs/project-overview.md - 프로젝트 개요
2. docs/requirements.md - 전체 요구사항
3. docs/architecture.md - 시스템 아키텍처
4. docs/tech-stack.md - 기술 스택 선정 이유
5. docs/roadmap.md - 개발 로드맵"

# Step 3: 프로젝트 구조 생성
"문서를 기반으로 프로젝트 초기 구조를 만들어줘.
백엔드는 NestJS, 프론트엔드는 React + TypeScript로."

# Step 4: 개발 가이드 작성
"팀원들을 위한 개발 가이드를 docs/development-guide.md 파일로 작성해줘.
코딩 컨벤션, Git 사용 방법, 커밋 규칙 등을 포함해줘."

# Step 5: 첫 기능 개발 시작
"문서를 기반으로 사용자 인증 기능부터 개발하자."

"Claude야, 게시판 만들어줘"
→ 결과: 요구사항 불명확, 여러 번 수정, 시간 낭비

"게시판 기능 요구사항을 같이 정리해보자. 질문해줘."
→ 요구사항 구체화 → 문서 작성 → 개발

"프로젝트 전체를 만들어줘"
→ 결과: 중간에 끊김, 일관성 없음, 디버깅 어려움

"프로젝트를 단계별로 나눠서 진행하자.
먼저 1단계 계획을 세워줘."
→ 단계별 진행
→ 각 단계마다 검토
→ 다음 단계 진행

"Explore Agent로 파일 찾아줘"
→ 결과: 불필요하게 복잡, Claude가 알아서 판단하게 두는 게 나음

"로그인 관련 코드가 어디 있어?"
→ Claude가 자동으로 적절한 Agent 선택

"이거 좀 고쳐줘"
→ 결과: Claude가 뭘 고쳐야 할지 모름

"src/components/LoginForm.tsx 파일에서
로그인 실패 시 에러 메시지가 표시되지 않는 문제를 수정해줘."
→ 명확한 문제 설명

초기 문서 작성 → 개발 진행 → 요구사항 변경 → 문서는 그대로
→ 결과: 문서와 코드 불일치, 문서 무용지물

요구사항 변경 시:
"요구사항이 변경됐어. docs/requirements.md 문서를 업데이트하고,
영향받는 코드를 수정해줘."
→ 문서 먼저 업데이트
→ 코드 수정

git commit -m "수정"
git commit -m "ㅇㅇ"
→ 결과: 나중에 변경 이력 추적 불가

/commit
→ Claude가 자동으로 컨벤션에 맞춰 작성