개발 요청 프롬프트 작성 방법 정리

  추천 프롬프트 패턴

  1단계: 명세서 작성

  [기능이름] 기능 명세서를 @docs/feature/[name].md에 작성해줘.

  [기능 설명을 자유롭게 2~3줄로]

  기존 명세서 @docs/feature/register.md 의 구조(개요 → 사용자흐름 → 화면설계

  → API설계 → 데이터모델 → 코드구조 → Facade설계 → TDD계획 → 개발순서 →

  결정사항)를

  따라서 작성해줘.

  선행 구현: register.md(완료), loginout.md(완료)

  결정이 필요한 부분은 선택지를 비교하고 네가 추천하는 것을 결정해줘.

  개발 현황 섹션은 비워두고 Phase별 항목만 만들어줘.

  핵심 포인트:

  - 기존 명세서를 @ 참조로 명시하면 AI가 구조를 복사함

  - "결정사항은 네가 추천" → 매번 물어보는 것 방지

  - "개발 현황은 비워두고" → 3단계에서 채울 영역 확보

  ---

  2단계: 코딩 요청

  여기가 가장 중요합니다. 한 번에 전부 하지 말고 Phase 단위로 요청하세요.

  @docs/feature/loginout.md 명세서 기반으로 코딩해줘.

  Phase 2 (세션 생성 — loginFacade 변경)부터 시작.

  CLAUDE.md 코딩룰과 명세서의 TDD 계획을 따라서:

  1. 테스트 먼저 작성

  2. 구현

  3. 테스트 통과 확인

  Phase 2가 끝나면 멈추고 알려줘.

  핵심 포인트:

  - Phase 단위로 끊어서 요청 → 컨텍스트 오버플로우 방지

  - "멈추고 알려줘" → AI가 전체를 한번에 진행하다 품질 떨어지는 것 방지

  - 명세서에 Facade 설계가 이미 있으므로 AI가 구현 방향을 정확히 잡음

  Phase 완료 후:

  테스트 통과 확인됐으면 Phase 3 진행해줘.

  ---

  3단계: 결과 기록

  @docs/feature/loginout.md 의 개발 현황 섹션을 업데이트해줘.

  지금까지 완료한 Phase 1~9의 항목별 상태를 기록하고,

  테스트 현황(테스트 클래스명, 테스트 수, 통과 여부)도 추가해줘.

  register.md의 개발 현황/테스트 현황 형식을 참고해서.

  ---

  더 개선할 수 있는 점

  A. CLAUDE.md에 워크플로우 규칙 추가

  CLAUDE.md에 이 3단계를 명시해두면 매번 설명할 필요가 없습니다:

  ## 기능 개발 워크플로우

  1. 명세서 작성: docs/feature/{name}.md — 기존 명세서 구조 따름

  2. 코딩: Phase 단위 TDD — 테스트 작성 → 구현 → 테스트 통과

  3. 결과 기록: 명세서의 개발 현황 섹션 업데이트

  B. 명세서에 "AI 코딩 지시" 섹션 추가

  명세서 자체에 AI가 코딩할 때 주의할 점을 적어두면 2단계가 더 정확해집니다:

  ## 코딩 주의사항

  - loginFacade 기존 코드를 수정하는 것이지 새로 만드는 것 아님

  - register.md에서 구현한 ACCOUNT_DISABLED 분리 반환을 INVALID_CREDENTIALS로

  통합

  - ScreenLockFilter는 SecurityContextHolderFilter 이후에 등록

  (실제로 loginout.md에 이런 내용이 이미 산재해 있는데, 별도 섹션으로 모으면

  AI가 놓칠 확률이 줄어듭니다.)

  C. 가장 흔한 실수와 대응

  문제: AI가 명세서와 다르게 구현

  원인: 컨텍스트가 길어서 일부를 놓침

  해결: Phase 단위로 쪼개기

  ────────────────────────────────────────

  문제: 기존 코드를 무시하고 새로 작성

  원인: 기존 파일을 안 읽음

  해결: "기존 AuthService.java를 수정해줘" 명시

  ────────────────────────────────────────

  문제: 테스트 건너뜀

  원인: TDD보다 구현이 쉬워서

  해결: "테스트 먼저 작성하고 보여줘. 확인 후 구현 진행"

  ────────────────────────────────────────

  문제: 개발 현황 부정확

  원인: 실제와 md가 불일치

  해결: 코딩 완료 직후 바로 기록 요청

  ---

  요약: 3단계 프롬프트 템플릿

  # 1단계 (한 번)

  "[기능] 명세서를 @docs/feature/register.md 구조로 작성해줘. [기능 설명]"

  # 2단계 (Phase마다 반복)

  "@docs/feature/[name].md Phase N 코딩해줘. 테스트 먼저, 끝나면 멈춰."

  # 3단계 (마지막에 한 번)

  "@docs/feature/[name].md 개발 현황 업데이트해줘."

  지금 쓰시는 방식이 이미 상당히 좋습니다. Phase 단위로 끊어서 요청하는 것이

  가장 큰 품질 차이를 만듭니다.

# 3단계 개발 프롬프트 작성 가이드

## 개요

개발 사이클을 3단계로 명확히 분리하고, 각 단계의 프롬프트를 구체화하여 Claude와의 협업 효율을 높입니다.

```

[1단계: 기획서 작성] → [2단계: 코딩 구현] → [3단계: 결과 업데이트]

```

---

## 1단계: 기획서 작성 프롬프트

**목표:** 구현할 기능을 명확하게 정의하고 MD 파일로 저장

### ✅ 좋은 프롬프트 예시

```markdown

다음 기능에 대한 상세 기획서를 작성해줘.

## 입력 정보

- 기능명: "팔로우/언팔로우 기능"

- 백엔드: Spring Boot (JPA, Redis)

- 데이터베이스: PostgreSQL

- 인증: Spring Session (로그인한 사용자만)

- 상황: SNS 앱에서 다른 사용자를 팔로우하는 기능

## 기획서 작성 범위 (필수 포함)

### 1. 개요

- 기능의 목적

- 핵심 요구사항 3-5개

### 2. 사용자 흐름 (User Flow)

- 팔로우 버튼 클릭 → 팔로우 상태로 변경 → 피드에 반영 (흐름도 형식)

- 언팔로우 흐름 (유사)

- 엣지 케이스: 이미 팔로우한 사용자 재팔로우, 자기 자신 팔로우 시도 등

### 3. 화면 설계

- 팔로우/언팔로우 버튼 위치와 텍스트

- 토글 애니메이션

- 로딩 상태 표시

### 4. API 설계

- POST /api/users/{userId}/follow — 팔로우

- DELETE /api/users/{userId}/follow — 언팔로우

- 각 API별 요청/응답 스키마 (JSON)

- 에러 케이스와 HTTP 상태 코드

### 5. 데이터 모델

- follows 테이블 스키마 (SQL)

- 제약조건 (UNIQUE, FOREIGN KEY 등)

- 인덱스 전략 (조회 성능)

### 6. 비즈니스 로직

- 중복 팔로우 처리

- 자기 자신 팔로우 불가

- 팔로우 취소 시 알림 처리

- 팔로우 상태 조회 최적화

### 7. 코드 구조 (Spring Boot 규칙)

- 패키지 구성 (entity, repository, service, controller, dto)

- Facade 패턴 사용 여부

- 테스트 케이스 (TDD)

### 8. 개발 순서 (Phase 1, 2, ...)

- 각 Phase별 구현 항목 나열

### 9. 결정 사항 (트레이드오프)

- Redis vs DB 저장 비교 및 선택 이유

- 동기 vs 비동기 처리

## 출력 형식

- Markdown 파일 형식으로 상세하게 작성

- 각 섹션마다 예제 코드/SQL 포함

- 모호한 부분은 질문 형식으로 명시 (예: "추천 로직의 알고리즘은?")

```

### ❌ 나쁜 프롬프트 예시

```

팔로우 기능 기획서 작성해줘.

(→ 너무 간단하고 구체적인 지시사항이 없음)

```

### 📋 프롬프트 체크리스트

- [ ] 기능명이 명확한가?

- [ ] 기술 스택 (Spring Boot, DB, 캐시)을 명시했는가?

- [ ] 포함해야 할 섹션 (API, 데이터 모델, 코드 구조)을 나열했는가?

- [ ] 출력 형식(Markdown, JSON 등)을 지정했는가?

- [ ] 의사결정이 필요한 부분은 질문 형식으로 표시했는가?

---

## 2단계: 코딩 구현 프롬프트

**목표:** 기획서를 실제 코드로 구현

### ✅ 좋은 프롬프트 예시

```markdown

## 개발 지시사항

### 현재 상황

- 프로젝트: circle (Spring Boot 4.0.4)

- 기획서: 첨부된 follow-feature.md 참고

- 현재 구현 상태: User Entity, UserRepository 완료

- 예상 작업 시간: Phase 1 완료 예정

### Phase 1: 팔로우 기능 기본 구조 (JPA, 즉시 구현)

#### 1.1 데이터 모델 작성

**파일**: `src/main/java/com/ddoongddak/circle/user/entity/Follow.java`

- JPA Entity 클래스 작성

- 필드: id, follower (User), following (User), createdAt

- @UniqueConstraint(columnNames = {"follower_id", "following_id"})

- equals/hashCode override (id 기반)

- Setter 제거 (불변성)

**테스트**: FollowTest.java

- Follow 엔티티 생성 테스트

- 동일한 팔로우 관계가 2개 생성되지 않도록 제약 테스트

#### 1.2 Repository 작성

**파일**: `src/main/java/com/ddoongddak/circle/user/repository/FollowRepository.java`

```java

public interface FollowRepository extends JpaRepository<Follow, Long> {

boolean existsByFollowerIdAndFollowingId(Long followerId, Long followingId);

Optional<Follow> findByFollowerIdAndFollowingId(Long followerId, Long followingId);

List<Follow> findByFollowerId(Long followerId); // 내가 팔로우한 사람들

long countByFollowingId(Long followingId); // 이 사람을 팔로우하는 수

}

```

**테스트**: FollowRepositoryTest.java

- 팔로우 저장 및 조회

- 중복 팔로우 여부 확인

- 팔로우 삭제

#### 1.3 Service 작성 (Facade 패턴)

**파일**: `src/main/java/com/ddoongddak/circle/user/service/FollowService.java`

메서드:

- `followUser(Long followerId, Long followingId)` — 팔로우

- 유효성 검사: 자기 자신 팔로우 불가, 존재하지 않는 사용자 팔로우 불가

- 이미 팔로우되었으면 무시 (IDEMPOTENT)

- Follow 엔티티 저장

- 반환값: followingUser 정보

- `unfollowUser(Long followerId, Long followingId)` — 언팔로우

- 팔로우 관계 삭제

- 없으면 무시 (IDEMPOTENT)

- `isFollowing(Long followerId, Long followingId)` — 팔로우 여부 확인

- boolean 반환

**테스트**: FollowServiceTest.java (TDD - 테스트 먼저 작성)

- followUser_정상요청_팔로우성공

- followUser_자신을팔로우_예외발생

- followUser_존재하지않는사용자_예외발생

- followUser_이미팔로우됨_무시됨

- unfollowUser_정상요청_언팔로우성공

- unfollowUser_팔로우안됨_무시됨

- isFollowing_팔로우됨_true반환

- isFollowing_팔로우안됨_false반환

#### 1.4 Controller API 작성

**파일**: `src/main/java/com/ddoongddak/circle/user/controller/api/FollowApiController.java`

엔드포인트:

- `POST /api/users/{userId}/follow` — 팔로우

- 인증: 필수 (로그인한 사용자만)

- 경로 변수: userId (팔로우할 사용자)

- 응답: 200 OK + { followingId, followingName, ... }

- 에러: 400 (자신), 404 (사용자 없음), 401 (미로그인)

- `DELETE /api/users/{userId}/follow` — 언팔로우

- 인증: 필수

- 경로 변수: userId (언팔로우할 사용자)

- 응답: 204 No Content

- 에러: 404, 401

- `GET /api/users/{userId}/is-following` — 팔로우 여부 확인

- 인증: 필수

- 경로 변수: userId

- 응답: 200 OK + { isFollowing: boolean }

**테스트**: FollowApiControllerTest.java (TDD)

- followUser_정상요청_200응답

- followUser_미로그인_401응답

- unfollowUser_정상요청_204응답

- isFollowing_팔로우됨_true응답

#### 1.5 DTO 작성

**파일**: `src/main/java/com/ddoongddak/circle/user/dto/FollowDto.java`

```java

public class FollowDto {

public record FollowResponse(

Long followingId,

String followingName,

String followingProfileImage

) {}

public record IsFollowingResponse(

boolean isFollowing

) {}

}

```

### 코딩 규칙 준수 사항

- [ ] Facade 메서드는 서비스에 작성 (컨트롤러X)

- [ ] 예외는 custom exception 사용 (예: UserNotFoundException, InvalidFollowException)

- [ ] TDD: 테스트를 먼저 작성하고 구현

- [ ] 에러 메시지는 코드가 아닌 Enum으로 관리

- [ ] API 응답은 사용자에게 보안상 민감한 정보 제외

### 제출 사항

1. Follow.java (Entity)

2. FollowRepository.java (Repository)

3. FollowService.java (Service)

4. FollowApiController.java (Controller)

5. FollowDto.java (DTO)

6. FollowServiceTest.java (Service 테스트)

7. FollowApiControllerTest.java (Controller 테스트)

### 테스트 실행

```bash

./gradlew test --tests "*Follow*"

```

모든 테스트가 통과해야 함.

### 다음 단계

Phase 1 완료 후:

- Phase 2: 팔로우 목록 조회 API (페이징, 정렬)

- Phase 3: 알림 기능 연동 (팔로우 시 알림 발송)

- Phase 4: 캐싱 최적화 (Redis에 팔로우 상태 캐시)

```

### ❌ 나쁜 프롬프트 예시

```

팔로우 기능 코드 작성해줘.

(→ 어디서부터 시작할지, 뭘 만들어야 할지 불명확)

```

### 📋 프롬프트 체크리스트

- [ ] Phase를 명시했는가? (1단계씩 진행)

- [ ] 작성할 파일명과 경로를 정확히 지정했는가?

- [ ] 메서드 시그니처와 역할을 설명했는가?

- [ ] 테스트 케이스 이름을 나열했는가? (TDD)

- [ ] 예상 응답 형식(JSON)을 명시했는가?

- [ ] 코딩 규칙 (예: custom exception, Enum)을 상기시켰는가?

- [ ] 다음 단계는 무엇인지 명시했는가?

---

## 3단계: 결과 업데이트 프롬프트

**목표:** 구현 완료 후 기획서와 결과 MD 파일을 최신화

### ✅ 좋은 프롬프트 예시

```markdown

## 코딩 완료 후 결과 기록

### 현재 상황

- Phase 1 팔로우 기능 구현 완료

- 테스트: 모두 통과 (13개 테스트 케이스)

- 이제 기획서와 결과 파일을 업데이트해야 함

### 1단계: 기획서 업데이트 (follow-feature.md)

**섹션: 개발 현황**

다음 표를 추가/수정해줘:

```markdown

### 개발 현황 (2026-03-28)

| Phase | 항목 | 파일 | 상태 | 테스트 수 |

|-------|------|------|------|----------|

| 1 | Follow Entity | Follow.java | ✅ 완료 | 3 |

| 1 | FollowRepository | FollowRepository.java | ✅ 완료 | 4 |

| 1 | FollowService | FollowService.java | ✅ 완료 | 8 |

| 1 | FollowApiController | FollowApiController.java | ✅ 완료 | 7 |

| 1 | DTO | FollowDto.java | ✅ 완료 | - |

| **합계** | | | **✅ Phase 1 완료** | **22개** |

```

- 표의 "파일" 열에는 생성된 파일의 상대 경로 추가

- 테스트 수는 각 클래스별 테스트 케이스 개수

- 상태는 ✅ 완료, ⏳ 진행 중, ❌ 미구현

### 2단계: 개발 결과 파일 작성 (follow-result.md)

새 파일 `docs/results/follow-result.md`을 생성하고 다음 내용을 포함해줘:

```markdown

# 팔로우 기능 구현 결과

## 개발 일정

- 시작: 2026-03-25

- 완료: 2026-03-28

- 기간: 4일 (Phase 1)

- 테스트: 22개 케이스 모두 통과

## 구현 내용

### Follow Entity

**파일**: `src/main/java/com/ddoongddak/circle/user/entity/Follow.java`

```java

@Entity

@Table(name = "follows",

uniqueConstraints = @UniqueConstraint(columnNames = {"follower_id", "following_id"}))

public class Follow {

@Id @GeneratedValue(strategy = GenerationType.IDENTITY)

private Long id;

@ManyToOne(fetch = FetchType.LAZY)

@JoinColumn(name = "follower_id", nullable = false)

private User follower; // 팔로우하는 사용자

@ManyToOne(fetch = FetchType.LAZY)

@JoinColumn(name = "following_id", nullable = false)

private User following; // 팔로우되는 사용자

@CreationTimestamp

@Column(name = "created_at", nullable = false)

private LocalDateTime createdAt;

// 생성자, getter만 제공 (setter 제거)

}

```

**특징**:

- UNIQUE 제약조건으로 중복 팔로우 방지

- LAZY 로딩으로 성능 최적화

- 불변성 보장 (setter 제거)

### 테스트 결과

#### FollowServiceTest (8개 케이스)

```

✅ followUser_정상요청_팔로우성공

✅ followUser_자신을팔로우_예외발생 (InvalidFollowException)

✅ followUser_존재하지않는사용자_예외발생 (UserNotFoundException)

✅ followUser_이미팔로우됨_무시됨 (IDEMPOTENT)

✅ unfollowUser_정상요청_언팔로우성공

✅ unfollowUser_팔로우안됨_무시됨 (IDEMPOTENT)

✅ isFollowing_팔로우됨_true반환

✅ isFollowing_팔로우안됨_false반환

```

#### FollowApiControllerTest (7개 케이스)

```

✅ followUser_정상요청_200응답

✅ followUser_미로그인_401응답

✅ followUser_자신_400응답

✅ unfollowUser_정상요청_204응답

✅ unfollowUser_미로그인_401응답

✅ isFollowing_팔로우됨_200응답

✅ isFollowing_팔로우안됨_200응답

```

### API 명세 최종 확정

#### POST /api/users/{userId}/follow

- 요청: 없음 (경로 변수만)

- 응답: `{ followingId, followingName, followingProfileImage }`

- 에러:

- 400: 자신을 팔로우 시도

- 401: 미로그인

- 404: 사용자 없음

#### DELETE /api/users/{userId}/follow

- 요청: 없음

- 응답: 204 No Content

- 에러: 401, 404

#### GET /api/users/{userId}/is-following

- 요청: 없음

- 응답: `{ isFollowing: boolean }`

- 에러: 401

### 데이터 모델 최종 확정

#### SQL 마이그레이션 (Flyway)

```sql

-- V4__create_follows_table.sql

CREATE TABLE follows (

id BIGSERIAL PRIMARY KEY,

follower_id BIGINT NOT NULL REFERENCES users(id) ON DELETE CASCADE,

following_id BIGINT NOT NULL REFERENCES users(id) ON DELETE CASCADE,

created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,

UNIQUE(follower_id, following_id)

);

CREATE INDEX idx_follower_id ON follows(follower_id);

CREATE INDEX idx_following_id ON follows(following_id);

```

### 주요 결정사항

#### 1. 중복 팔로우 처리: IDEMPOTENT

- 같은 팔로우를 여러 번 요청해도 1번만 저장됨

- 에러 발생 시 자동 재시도 가능

- 클라이언트 입장에서 안전함

#### 2. 자신 팔로우 방지: 예외 발생

- 비즈니스 로직 레벨에서 사전 차단

- `InvalidFollowException` custom exception 사용

#### 3. N+1 쿼리 방지

- Repository에서 `.findByFollowerId(followerId)`

- `@EntityGraph(attributePaths = "following")` 사용 (또는 fetch join)

### 예상 성능

| 작업 | 쿼리 수 | 응답 시간 |

|------|--------|---------|

| 팔로우 | 3 | ~10ms |

| 언팔로우 | 2 | ~5ms |

| 팔로우 여부 확인 | 1 | ~2ms |

| 팔로우 목록 조회 (100명) | 101 (N+1 문제) | ~100ms |

> Phase 2에서 N+1 문제 해결 예정

### 다음 Phase 계획

#### Phase 2: 팔로우 목록 조회 및 페이징

- 내가 팔로우한 사람 목록 조회

- 나를 팔로우하는 사람 목록 조회

- 페이징 (20명씩)

- 정렬 (최신순, 알파벳순)

#### Phase 3: 알림 연동

- 팔로우 시 알림 발송

- 언팔로우 시 알림 삭제

#### Phase 4: 캐싱 최적화

- Redis에 팔로우 상태 캐시

- 조회 성능 ~10ms → ~1ms

## 재검토 사항 및 피드백

### 기획서에서 놓친 부분

1. **팔로우 목록 조회 API**: 기획서에 없었는데 Phase 2에서 필요

2. **성능 고려**: N+1 쿼리 문제 언급 필요

### 코딩 중 변경사항

1. **DTO 간소화**: 원래는 FollowRequest를 만들 계획이었으나, 경로 변수만 사용하므로 불필요

2. **예외 전략**:

- 원래: `FollowException`으로 통일

- 변경: `InvalidFollowException`, `UserNotFoundException` 분리 (더 명확)

### 테스트 추가 발견

- 동시성 테스트: 여러 사용자가 동시에 팔로우 시 race condition 확인 필요 (향후)

- 대량 팔로우: 성능 테스트 (1,000명 팔로우 시 응답 시간)

---

## 마이그레이션 확인

```bash

./gradlew flywayInfo

```

**결과**:

```

+-------+---------+----------------------------------+------+---------------------+---------+

| Ver | State | Description | Type | Installed On | Success |

+-------+---------+----------------------------------+------+---------------------+---------+

| 1 | Success | create users table | SQL | 2026-03-20 10:00:00 | yes |

| 2 | Success | add password to users | SQL | 2026-03-21 10:00:00 | yes |

| 3 | Success | create chat tables | SQL | 2026-03-22 10:00:00 | yes |

| 4 | Success | create follows table | SQL | 2026-03-28 15:30:00 | yes |

+-------+---------+----------------------------------+------+---------------------+---------+

```

---

## 빌드 및 테스트 결과

```bash

./gradlew build --tests "*Follow*"

```

**결과**:

```

BUILD SUCCESSFUL in 25s

Test Summary:

- FollowServiceTest: 8/8 passed

- FollowApiControllerTest: 7/7 passed

- Total: 15 tests passed, 0 failed

```

```

```

### 3단계: 전체 점검 체크리스트

기획서 `follow-feature.md`의 "개발 현황" 섹션에 다음을 추가해줘:

```markdown

## 개발 진행 상황

### Phase 1: 완료 (2026-03-28)

- [x] Follow Entity 작성 및 테스트

- [x] FollowRepository 작성 및 테스트

- [x] FollowService (Facade) 작성 및 테스트

- [x] FollowApiController 작성 및 테스트

- [x] Flyway 마이그레이션 (V4__create_follows_table.sql)

- [x] 모든 테스트 통과 (15/15)

### Phase 2: 예정 (2026-04-01)

- [ ] 팔로우 목록 조회 API

- [ ] 페이징 처리

- [ ] N+1 쿼리 최적화

### Phase 3: 예정

- [ ] 알림 기능 연동

### Phase 4: 예정

- [ ] Redis 캐싱 최적화

```

### 최종 확인

다음을 모두 확인했는가?

- [ ] 기획서 업데이트 (개발 현황 표 추가)

- [ ] 결과 파일 생성 (follow-result.md)

- [ ] 결과 파일에 구현 코드, 테스트 결과, API 명세 포함

- [ ] 다음 Phase 계획 명확히 함

- [ ] 전체 체크리스트 추가

```

### ❌ 나쁜 프롬프트 예시

```

기획서 업데이트해줘.

(→ 무엇을 업데이트할지, 어느 섹션을 수정할지 불명확)

```

### 📋 프롬프트 체크리스트

- [ ] 어떤 파일을 업데이트할지 명시했는가? (follow-feature.md)

- [ ] 새로 만들 결과 파일의 이름과 위치를 지정했는가?

- [ ] 결과 파일에 포함할 섹션을 나열했는가?

- [ ] 테스트 결과 표 형식을 제시했는가?

- [ ] 다음 Phase의 계획을 명시했는가?

- [ ] 마이그레이션 상태 확인 명령어를 포함했는가?

---

## 3단계 과정에서의 팁

### ✨ 효과적인 업데이트 방법

#### Tip 1: 표 형식으로 진행 상황 기록

```markdown

| Phase | 항목 | 파일 | 상태 | 테스트 |

|-------|------|------|------|--------|

| 1 | Entity | Follow.java | ✅ | 3 |

| 1 | Repository | FollowRepository.java | ✅ | 4 |

| 1 | Service | FollowService.java | ✅ | 8 |

```

→ 진행률을 한눈에 파악 가능

#### Tip 2: 변경사항은 "코딩 중 변경사항" 섹션에 기록

```markdown

### 코딩 중 변경사항

#### 원래 계획

- FollowRequest DTO 사용

#### 실제 구현

- FollowRequest 제거 (경로 변수만 사용하므로 불필요)

#### 이유

- API 설계 단계에서 놓친 부분

- TDD 과정에서 발견

```

#### Tip 3: 성능 측정 테이블 추가

```markdown

| 작업 | 쿼리 수 | 응답 시간 | 최적화 여부 |

|------|--------|---------|-----------|

| 팔로우 | 3 | ~10ms | - |

| 팔로우 여부 확인 | 1 | ~2ms | ✅ |

| 목록 조회 (100명) | 101 | ~100ms | ❌ (Phase 2에서) |

```

#### Tip 4: 피드백 섹션으로 개선 사항 추적

```markdown

## 재검토 사항 및 피드백

### 기획서에서 놓친 부분

1. **팔로우 목록 조회 API**: ...

### 코딩 중 변경사항

1. **DTO 간소화**: ...

### 테스트 추가 발견

1. **동시성 테스트**: ...

```

---

## 전체 워크플로우 예시

### 1단계: 기획 (Day 1)

```

프롬프트: "기능 기획서 작성해줘"

↓

생성물: follow-feature.md (기획서)

↓

상태: 검토 및 수정 (논의 필요 부분 Q&A)

```

### 2단계: 코딩 (Day 2-3)

```

프롬프트: "Phase 1 구현해줘"

↓

생성물:

- Follow.java (Entity)

- FollowRepository.java

- FollowService.java

- FollowApiController.java

- Follow*Test.java (테스트 클래스)

↓

상태: 모든 테스트 통과

```

### 3단계: 결과 기록 (Day 3 말)

```

프롬프트: "개발 완료, 결과 파일 작성해줘"

↓

생성물:

- follow-feature.md 업데이트 (개발 현황 추가)

- follow-result.md (신규 생성, 구현 결과 상세 기록)

↓

상태: 다음 Phase 준비 완료

```

---

## 프롬프트 템플릿 (바로 사용 가능)

### 템플릿 1: 기획서 작성

```markdown

다음 기능에 대한 상세 기획서를 마크다운으로 작성해줘.

## 입력 정보

- 기능명: "[기능명]"

- 백엔드: Spring Boot 4.0.4

- 데이터베이스: PostgreSQL

- 캐시: Redis (선택사항)

- 인증: Spring Session (로그인 필수 여부)

- 관련 기획서: [파일명].md

## 필수 포함 섹션

1. 개요

2. 사용자 흐름 (흐름도)

3. 화면 설계

4. API 설계 (요청/응답 JSON 포함)

5. 데이터 모델 (SQL)

6. 비즈니스 로직

7. 코드 구조 (Spring Boot 패키지 구성)

8. 개발 순서 (Phase 1, 2, ...)

9. 결정 사항 (트레이드오프)

10. 개발 현황 (표 형식)

## 출력

- 파일명: `docs/specs/[기능명]-feature.md`

- 형식: 구체적인 예제 코드/SQL 포함

- 의문점은 질문 형식으로 표시

```

### 템플릿 2: 코딩 구현

```markdown

## 개발 지시사항

### 현재 상황

- Phase: [1/2/3] — [단계 이름]

- 기획서: [파일명].md 참고

- 선행 완료: [이전 단계 내용]

- 예상 시간: [기간]

### Phase [X]: [제목]

#### [X.1] [항목명] 작성

**파일**: `src/main/java/.../[ClassName].java`

[상세 요구사항]

**테스트**: [TestClassName].java

- [테스트 케이스 1]

- [테스트 케이스 2]

#### [X.2] [다음 항목] ...

### 코딩 규칙

- [ ] TDD (테스트 먼저)

- [ ] Custom Exception 사용

- [ ] Facade 패턴 (Service에서)

- [ ] [기타 규칙]

### 제출 사항

1. [파일1]

2. [파일2]

...

### 테스트 실행

\`\`\`bash

./gradlew test --tests "[테스트 패턴]"

\`\`\`

### 다음 단계

Phase [X+1]: [내용]

```

### 템플릿 3: 결과 업데이트

```markdown

## 코딩 완료 후 결과 기록

### 현재 상황

- Phase [X] 완료

- 테스트: [개수] 통과

- 마이그레이션: V[N] 추가됨

### 1단계: 기획서 업데이트 ([파일명].md)

**섹션: 개발 현황**

표를 다음과 같이 수정/추가:

| Phase | 항목 | 파일 | 상태 | 테스트 |

| ... |

### 2단계: 결과 파일 작성

새 파일 `docs/results/[기능명]-result.md` 생성:

```markdown

# [기능명] 구현 결과

## 개발 일정

- 시작: [날짜]

- 완료: [날짜]

- 기간: [기간]

- 테스트: [개수] 케이스 모두 통과

## 구현 내용

### [항목 1]

**파일**: `...`

[코드 예제]

### 테스트 결과

#### [테스트 클래스]

\`\`\`

✅ [테스트 케이스 1]

✅ [테스트 케이스 2]

\`\`\`

### 데이터 모델 최종 확정

#### SQL 마이그레이션

\`\`\`sql

-- V[N]__[설명].sql

...

\`\`\`

### 주요 결정사항

#### 1. [결정 사항 1]

[설명]

#### 2. [결정 사항 2]

[설명]

### 다음 Phase 계획

#### Phase [X+1]: [제목]

- [ ] [항목 1]

- [ ] [항목 2]

\`\`\`

### 3단계: 점검 체크리스트

- [ ] 기획서 업데이트 완료

- [ ] 결과 파일 생성 완료

- [ ] 모든 테스트 통과 확인

- [ ] 마이그레이션 상태 확인

- [ ] 다음 Phase 계획 명시

```

---

## 요약

| 단계 | 목표 | 출력물 | 프롬프트 길이 | 중요 포인트 |

|------|------|--------|------------|-----------|

| **1단계** | 기능 정의 | `[기능명]-feature.md` | 중간 (500자+) | 구체적인 API 스키마, 데이터 모델 명시 |

| **2단계** | 코드 구현 | 소스 파일 + 테스트 | 길음 (1000자+) | Phase별 분리, 파일명 명시, 테스트 케이스 나열 |

| **3단계** | 결과 기록 | `[기능명]-result.md` 업데이트 | 길음 (1000자+) | 구현 코드 포함, 테스트 결과, 변경사항 기록 |

**핵심**: 각 단계의 프롬프트는 **구체적일수록, 세부 항목을 나열할수록** Claude가 정확하게 이해하고 빠르게 실행할 수 있습니다.

📌 핵심 요약

각 단계별 프롬프트 작성 원칙

1단계: 기획서 작성 (당신의 회원가입 기능서 같은 수준)

markdown

✅ 포함해야 할 것
- 기능명, 기술 스택 명시
- 포함할 섹션 명확히 나열 (API 설계, 데이터 모델, 코드 구조 등)
- "Markdown으로 작성해줘", "예제 코드 포함" 등 형식 지정

❌ 하면 안 되는 것
- "기능 기획서 작성해줘" (너무 일반적)

2단계: 코딩 구현 (구체적일수록 ⭐⭐⭐⭐⭐)

markdown

✅ 반드시 포함
- Phase 번호 (1단계씩 진행)
- 파일명과 정확한 경로 지정
- 메서드 시그니처 (파라미터, 반환값)
- 테스트 케이스 이름 먼저 나열 (TDD)
- 예상 API 응답 JSON 형식
- 코딩 규칙 상기 (custom exception, Enum 등)

❌ 절대 금지
- "코드 작성해줘" (너무 뜬구름)
- Phase 미구분 (한 번에 다 하려고 하면 복잡함)

3단계: 결과 업데이트 (문서화)

markdown

✅ 꼭 포함
- 업데이트할 기획서 파일명과 섹션
- 새로 만들 결과 파일명과 위치
- 테스트 결과 표 형식
- 변경사항, 발견사항 섹션
- 다음 Phase 계획

❌ 피해야 할 것
- "기획서 업데이트해줘" (어느 부분을?)

---

🎯 실제 사용 시나리오

당신의 프로젝트에 바로 적용할 수 있습니다:

markdown

### 현재 상태: 회원가입 기능 Phase 1 (SMS 인증) 완료

### 1단계: Phase 2 기획서 작성
프롬프트:
"회원가입 기능 기획서의 'Phase 2: 프로필 이미지 업로드' 부분을 
상세하게 확장해줘. API 설계, 데이터 모델, 파일 저장 전략 포함."

생성물: auth-feature.md 업데이트

### 2단계: Phase 2 코딩 구현
프롬프트:
"Phase 2 구현:
- FileUploadService 작성 (OCI Object Storage)
- ProfileImageController API 작성 (/api/upload/profile)
- 파일 검증 (5MB, jpg/png만)
- 테스트 케이스 20개 (TDD)"

생성물: FileUploadService.java, ProfileImageController.java 등

### 3단계: Phase 2 결과 기록
프롬프트:
"Phase 2 완료. 
auth-feature.md의 '개발 현황' 표를 업데이트하고,
auth-result.md에 구현 결과를 상세히 기록해줘.
(테스트 결과, 성능 측정, 변경사항 포함)"

생성물: auth-result.md (신규 또는 업데이트)
```

---

## 💡 TIP: 점진적 개발 흐름
```
Phase 1: 기반 (User Entity, Security Config) ✅
  ↓
Phase 2: SMS 인증 (인증번호 발송/검증) ✅
  ↓
Phase 3: 회원가입 + 비밀번호 ✅
  ↓
Phase 4: 로그인 ✅
  ↓
Phase 5: 프로필 이미지 업로드 (다음 단계)
  ↓
Phase 6: 성능 최적화 (캐싱, 인덱스) (그 다음)

각 Phase마다:

1. 기획 → 2. 코딩 → 3. 결과 기록

이렇게 하면 프로젝트 진행 상황을 MD 파일로 추적할 수 있고, 나중에 리뷰할 때도 명확합니다! 🚀