Merge pull request 'test' (#425) from test into main

Reviewed-on: #425

AGENTS.md

@@ -158,14 +158,19 @@ Strong success criteria let you loop independently. Weak criteria ("make it work
 - 커밋 본문에는 `Ultraworked with [Sisyphus]...` 및 `Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>` 자동 footer를 포함하지 않는다.
 - `git commit` 실행 직전과 직후에 `work/scripts/check-commit-message-rules.sh`를 실행해 규칙 준수 여부를 검증한다.
 
-## 작업 계획 문서 규칙 (docs)
-- 모든 작업 시작 전에 `docs` 폴더 아래에 계획 문서를 먼저 생성하고, 해당 문서를 기준으로 구현을 진행한다.
-- 연속된 하나의 작업에 대한 후속 수정/보완이라면 새 계획 문서를 만들지 말고 기존 계획 문서에 작업 항목과 검증 기록을 이어서 추가한다.
-- 계획 문서 파일명은 `[날짜]_구현할내용한글.md` 형식을 사용한다.
+## PRD 및 계획 TASK 문서 규칙 (docs)
+- PRD와 계획 TASK 문서 없이 구현하지 않는다.
+- 작업 문서 작성과 구현은 반드시 `사용자 프롬프트 입력 -> PRD 문서 작성 -> 모호한 사항 사용자 인터뷰 -> 인터뷰 내용으로 PRD 보강 -> PRD 기반 계획 TASK 문서 작성 -> 계획 TASK 기반 최소 구현` 순서로 진행한다.
+- PRD 작성 중 애매하거나 더 필요한 내용, 결정해야 하는 사항이 있으면 애매한 사항이 없어질 때까지 사용자와 인터뷰한다.
+- PRD 문서는 `docs/prd/` 아래에 작성하고, `docs/prd/sample-prd.md`에서 필요한 섹션만 발췌해 작성한다.
+- 계획 TASK 문서는 `docs/plan-task/` 아래에 작성하고, 해당 문서를 기준으로 구현을 진행한다.
+- 연속된 하나의 작업에 대한 후속 수정/보완이라면 새 PRD 또는 계획 TASK 문서를 만들지 말고 기존 문서에 요구사항, 작업 항목, 검증 기록을 이어서 추가한다.
+- PRD 문서 파일명은 `[날짜]_구현할내용한글_prd.md` 형식을 사용해 계획 TASK 문서와 구분한다.
+- 계획 TASK 문서 파일명은 `[날짜]_구현할내용한글.md` 형식을 사용한다.
 - 날짜는 `YYYYMMDD` 8자리 숫자를 사용한다.
-- 구현 항목은 기능/작업 단위로 분리해 체크박스(`- [ ]`) 목록으로 작성한다.
+- 계획 TASK 문서의 구현 항목은 기능/작업 단위로 분리해 체크박스(`- [ ]`) 목록으로 작성한다.
 - 구현 완료 시마다 체크박스를 `- [x]`로 갱신하고, 범위가 바뀌면 문서를 먼저 갱신한다.
-- 결과 보고 시 계획 문서 맨 아래에 무엇을, 왜, 어떻게 검증했는지 한국어로 누적 기록한다.
+- 결과 보고 시 계획 TASK 문서 맨 아래에 무엇을, 왜, 어떻게 검증했는지 한국어로 누적 기록한다.
 
 ## 에이전트 동작 원칙
 - 추측하지 말고, 근거 파일을 읽고 결정한다.

docs/agent-guides/문서유지보수.md

@@ -1,11 +1,14 @@
 # 문서 유지보수
 
 ## 문서 유지보수 규칙
+- PRD 문서는 `docs/prd/`에 두고, 계획 TASK 문서는 `docs/plan-task/`에 둔다.
+- PRD 문서 파일명은 `[날짜]_구현할내용한글_prd.md`, 계획 TASK 문서 파일명은 `[날짜]_구현할내용한글.md` 형식을 사용한다.
+- PRD 문서는 `docs/prd/sample-prd.md`에서 필요한 섹션만 발췌해 작성하고, 불필요한 빈 섹션을 기계적으로 복사하지 않는다.
 - `build.gradle.kts` 변경 시 실행 명령 섹션을 함께 갱신한다.
 - 테스트 클래스 추가/이동 시 단일 테스트 실행 예시를 최신 상태로 유지한다.
 - `.editorconfig` 변경 시 포맷 규칙 섹션을 동기화한다.
 - Cursor/Copilot 규칙 파일이 생기면 해당 내용을 이 문서에 반영한다.
-- 연속된 하나의 작업에 대해 계획 문서가 여러 개 생기지 않도록 기존 계획 문서 재사용 여부를 먼저 확인한다.
+- 연속된 하나의 작업에 대해 PRD 또는 계획 TASK 문서가 여러 개 생기지 않도록 기존 문서 재사용 여부를 먼저 확인한다.
 - 문서 변경 후 최소 한 번 `./gradlew tasks --all`로 명령 유효성을 확인한다.
 - 불확실한 규칙은 추측으로 채우지 말고 근거 파일 경로를 먼저 확인한다.
 - 에이전트 안내 문구는 한국어 중심으로 유지한다.

docs/agent-guides/작업절차.md

@@ -1,8 +1,12 @@
 # 작업 절차
 
 ## 작업 절차 체크리스트
+- 변경 전: PRD와 계획 TASK 문서 없이 구현하지 않는다.
+- 변경 전: 사용자 프롬프트를 받으면 먼저 `docs/prd/` 아래에 PRD 문서를 작성하고, `docs/prd/sample-prd.md`에서 필요한 섹션만 발췌한다.
+- 변경 전: PRD 작성 중 애매하거나 더 필요한 내용, 결정해야 하는 사항이 있으면 애매한 사항이 없어질 때까지 사용자와 인터뷰하고 PRD를 보강한다.
+- 변경 전: 보강된 PRD를 바탕으로 `docs/plan-task/` 아래에 계획 TASK 문서를 작성한 뒤, 해당 문서를 기준으로 필요한 내용만 최소 구현한다.
 - 변경 전: 유사 기능 코드를 먼저 찾아 네이밍/예외/응답 패턴을 맞춘다.
-- 변경 전: 같은 작업의 연속 후속 수정인지 먼저 확인하고, 연속 작업이면 새 계획 문서를 만들지 말고 기존 계획 문서를 갱신한다.
+- 변경 전: 같은 작업의 연속 후속 수정인지 먼저 확인하고, 연속 작업이면 새 PRD 또는 계획 TASK 문서를 만들지 말고 기존 문서를 갱신한다.
 - 변경 중: 공개 API 스키마를 임의 변경하지 말고, 작은 단위로 안전하게 수정한다.
 - 변경 후: 최소 단일 테스트 또는 `./gradlew test`를 실행하고, 필요 시 `./gradlew ktlintCheck`를 수행한다.
 - 커밋 전/후: `commit-policy` 스킬을 먼저 로드하고, `git commit` 직전과 직후에 `work/scripts/check-commit-message-rules.sh`를 실행해 커밋 메시지 규칙 준수 여부를 확인한다.

docs/agent-guides/코드스타일.md

@@ -22,37 +22,41 @@
 - Request/Response DTO는 `...Request`, `...Response` 접미사를 유지한다.
 - 서비스/컨트롤러/리포지토리 명명은 역할 접미사(`Service`, `Controller`, `Repository`)를 유지한다.
 
-### 4) 타입/널 처리
+### 4) 패키지/코드 배치 규칙
+- 기존 로직을 수정하는 경우에는 기존 패키지 구조를 따른다.
+- 기존 로직 수정이 아닌 신규 API나 하위 코드는 `kr.co.vividnext.sodalive.v2` 패키지 하위에 작성한다.
+
+### 5) 타입/널 처리
 - Kotlin 타입 시스템을 활용하고 nullable(`?`)를 명시한다.
 - 불필요한 `Any`/약한 타입을 피하고 구체 타입을 우선한다.
 - 기존 코드에서 `!!` 사용이 많지만, 신규 코드는 가능한 안전 호출/가드절/명시적 예외로 대체를 우선 고려한다.
 
-### 5) API/응답 규칙
+### 6) API/응답 규칙
 - API 응답은 `ApiResponse.ok(...)`, `ApiResponse.error(...)` 패턴을 따른다.
 - 컨트롤러는 도메인 예외를 직접 포맷하지 말고 `SodaException`을 던진다.
 - 인증 사용자 필요 시 `@AuthenticationPrincipal(... ) member: Member?` 패턴 + null 가드절을 사용한다.
 
-### 6) 예외 처리 규칙
+### 7) 예외 처리 규칙
 - 비즈니스 예외는 `SodaException(messageKey = "...")` 우선 사용.
 - 사용자 노출 문구는 하드코딩보다 `messageKey` 기반 i18n을 우선한다.
 - 공통 예외 변환은 `SodaExceptionHandler`에서 수행하므로, 개별 컨트롤러에서 중복 처리하지 않는다.
 - 예외를 삼키는 빈 `catch` 블록을 금지한다.
 
-### 7) 트랜잭션 규칙
+### 8) 트랜잭션 규칙
 - 서비스 계층에서 `@Transactional`을 사용한다.
 - 조회 위주 메서드는 `@Transactional(readOnly = true)`를 우선한다.
 - 쓰기 로직은 메서드 단위 `@Transactional`로 경계를 명확히 한다.
 
-### 8) 비동기/동시성 규칙
+### 9) 비동기/동시성 규칙
 - 비동기 처리는 Kotlin Coroutines 패턴을 따른다.
 - `CoroutineScope(Dispatchers.IO)` + `launch` + 예외 처리 패턴을 일관되게 유지한다.
 - 생명주기 종료 시 scope 정리(`@PreDestroy`) 패턴을 참고한다.
 
-### 9) 의존성 주입
+### 10) 의존성 주입
 - 생성자 주입(primary constructor + `private val`)을 기본으로 사용한다.
 - 필드 주입보다 명시적 생성자 주입을 우선한다.
 
-### 10) 주석
+### 11) 주석
 - 의미 단위별로 주석을 작성한다.
 - 주석은 한 문장으로 간결하게 작성한다.
 - 주석은 코드의 의도와 구조를 설명한다.