Introducing the `prd-generator` Skill I Use
Introduction
The moment feature implementation gets stuck often arrives not after you start writing code, but before that. If you jump straight into implementation without clearly defining what to build, how far to build it, how to break it down into steps, and which parts of the existing codebase to reference, both the agent and the human operator start to drift.
That is why I do not see a PRD as just a planning document. In an AI coding environment like the current one, a PRD is much closer to an execution plan. If you are using a coding agent like Claude Code, the outcome changes dramatically based less on what you want to build and more on how you structure and hand off the work.
In this post, I want to introduce one skill I use: .claude/skills/prd-generator. This skill collects new feature requirements interactively and organizes them into a PRD document that Claude Code can take directly into implementation. Since this post is meant for sharing reference material, I am not stopping at a summary. I am also attaching the full text of SKILL.md and the template later in the article.
Why I Needed a Skill Like This
Leaving rough notes before building a feature and producing a PRD that is actually ready for implementation are completely different things.
Quick idea notes are fast, but they almost always miss something.
- The core feature is written down, but there is no user scenario.
- There is an implementation plan, but no acceptance criteria.
- There is existing code that should be referenced, but it is not connected.
- The implementation skill to use later is missing.
- The document name and storage path change every time.
In that state, even if a document exists, it still does not lead directly to execution. You end up asking again, reorganizing again, and rebuilding the structure again.
prd-generator is the skill I made to reduce that middle-layer waste. If you decide the order of questions, the document format, the storage rules, the implementation stages, and the implementation skill linkage all at once, the PRD stops being a mere description and becomes an immediately actionable unit of work.
If I Had to Explain This Skill in One Sentence
When I explain this skill as briefly as possible, I put it like this.
prd-generator is a skill that interactively gathers requirements for a new feature and then transforms them into a comprehensive PRD document optimized for Claude Code execution.
The actual structure is simple.
.claude/skills/prd-generator/
SKILL.md
assets/
prd_template.md
But compared with the simplicity of the folder layout, its role is fairly substantial. It does not just ask a few questions and stop. It also decides the document storage rules, the shape of the implementation plan, the acceptance criteria, and even which implementation skill should be used next.
The Design Intent Becomes Clearer When You Follow the Workflow
The core strength of this skill is that the conversation flow is well designed. Instead of trying to write a PRD in one pass, it is built to collect the required information in sequence.
Step 1: Feature Discovery
It begins by asking about the feature overview, the core functionality, and the main use cases.
The important point here is that it does not dump all the questions at once. The skill document explicitly says, "Do not ask every question at once." That single line matters more than it seems. A good PRD is not extracted by firing questions like a checklist. It is built by narrowing the scope as you follow the answers.
Step 2: Reference Implementation Review
Next, it asks about existing code and implementation patterns.
The reason this stage matters is obvious. In real work, new features are far more likely to need to follow an existing structure than to start on a completely blank canvas. Once you provide paths and confirm the patterns and rules to follow, the PRD stops being an abstract planning document and becomes a working document anchored in the real codebase.
Step 3: Scalability and Architecture
After that, it asks about future growth, integration points, and performance requirements.
This is one of the parts I like most. Even when building a simple feature, there is always a temptation to make it merely work for now. This skill counters that by inserting scalability questions early, which forces at least a minimal record of future burden into the document.
Step 4: Decide the Storage Location
At this stage, the user is not asked to define the full directory path by hand. The skill only asks for the filename, and the storage path is calculated automatically according to the document generation rules.
That choice is practical as well. If you make people think about the path and filename every single time, the documents scatter. If you keep the storage rules fixed instead, the documents are easier to find later, and PRDs accumulate as reusable work assets.
Step 5: Generate the Actual PRD
In the final step, the skill reads the template, fills the placeholders, determines which implementation skill applies, and completes the document.
This is where the identity of the skill becomes the clearest. Its goal is not simply to "write a planning document," but to produce an execution-oriented PRD that fills in all of the following without omission.
- Feature name and overview
- Detailed feature description
- Reference implementation
- Scalability considerations
- A four-stage implementation plan
- Acceptance criteria for each stage
- File structure
- Key implementation details
- Test strategy
- Potential challenges and solutions
- Future improvements
- The skills to use during implementation
What Matters Is That It Also Owns the Document Generation Rules
prd-generator is not just a skill that asks good questions. It also strictly defines where the generated PRD should be stored.
documents/PRD/{연}-{월}-{주차}w/{일}d-{hh}h-{파일명}.md
This rule matters more than it might seem. If documents are going to remain as project assets, not only the content but also the storage method needs to be consistent. This skill even defines the week-of-month calculation and specifies that the directory should be created automatically if it does not exist.
In other words, this skill does not stop at "writing documents well." It also cares about leaving documents behind in a state that can keep being managed later.
The Length of the Template Is Actually a Strength
When you first look at this skill's template, it may feel fairly long. I see that length as a strength rather than a weakness.
A short template is fast, but it also leaves more blanks for a person to fill in manually. This template, by contrast, exposes almost every required slot from the start.
- Overview
- Feature description
- Reference implementation
- Core functionality
- Scalability considerations
- A four-stage implementation plan
- File structure
- Key implementation details
- Test strategy
- Potential challenges and solutions
- Future improvements
- Skills to use during implementation
- Claude Code execution notes
With this many sections explicitly laid out, at the very least you can immediately see what is still missing. That is where I think the value of a PRD template really comes from. A good template is not a tool for making documents look nice. It is a tool for reducing omissions in thinking.
Implementation Skill Linkage Is the Core of This Skill
There is one separate aspect of this skill that I like the most. When it generates a PRD, it determines the implementation skill and includes it in the document.
Many PRDs end as documents. In actual work, though, what happens next matters more. If the PRD does not connect all the way to which implementation skill should be used and in what order, the PRD and the implementation split apart again.
To prevent that, prd-generator provides a separate implementation-skill linkage section.
As of the current document, it primarily evaluates these two skills.
| Skill Name | Activation Condition | Scope |
|---|---|---|
endpoint-implement-skill | If it includes any of Entity, Repository, Service, Controller, or DTO | Implements the full CRUD API layer |
sse-streaming-skill | If it includes SSE streaming, TEXT_EVENT_STREAM_VALUE, or real-time responses | Implements SSE controller/service |
The reason this decision logic works so well is straightforward. It turns the PRD into a document that specifies the next action, not just a description.
For example, if a feature needs everything from Entity to Controller, the document can clearly say to use endpoint-implement-skill. If the requirement includes something like AI response streaming, it can also say at which stage sse-streaming-skill should be used. Once that linkage is present, both the reader and the agent get lost much less often.
When This Skill Works Especially Well
This skill is not necessary in every situation. But it is especially strong in the following cases.
- When you need to design a new feature from scratch
- When there is clearly existing code that should be referenced
- When the feature requirements exist but the implementation order is still vague
- When you plan to continue directly into Claude Code or another implementation skill afterward
- When the document needs to remain as a team asset
By contrast, it may be too much for a very small settings change or a minor patch. This is less a tool for lightweight notes and more a tool for structuring feature development before handoff.
I Am Also Leaving the Full Source Text for Reference Sharing
Everything up to this point was explanation. From here on, this becomes an appendix for sharing the actual reference material. As requested, I am leaving the core contents of .claude/skills/prd-generator in full, without shortening them, by attaching the full text of SKILL.md and assets/prd_template.md.
Appendix 1. Full Text of .claude/skills/prd-generator/SKILL.md
---
name: prd-generator
description: 기능 개발을 위한 대화형 PRD(제품 요구사항 문서) 생성기. 사용자가 새로운 기능에 대한 체계적인 구현 계획을 작성하고자 할 때 사용합니다. 이 스킬은 대화형 질문을 통해 요구사항을 수집한 후, Claude Code 실행에 최적화된 포괄적인 PRD 문서를 생성합니다. "PRD 만들어줘", "기능 기획해줘", "구현 계획 작성해줘", "기능 요구사항 문서화해줘" 등의 요청 시 활성화됩니다.
---
# PRD Generator (한글 버전)
이 스킬은 대화형 질문 프로세스를 통해 포괄적인 제품 요구사항 문서(PRD)를 생성합니다. 생성된 PRD는 Claude Code가 구현 계획을 효율적으로 실행할 수 있도록 최적화되어 있습니다.
## 워크플로우
스킬이 활성화되면 다음 대화형 워크플로우를 따르세요:
### 1단계: 기능 탐색
사용자가 원하는 기능에 대해 질문합니다. 다음 가이드 질문을 사용하세요 (상황에 맞게 조정):
1. **기능 개요**: "어떤 기능을 구현하고 싶으신가요? 상위 수준의 설명을 제공해주세요."
2. **기능 상세**: "이 기능의 핵심 기능과 사용자 상호작용을 설명해주실 수 있나요?"
3. **사용 사례**: "이 기능의 주요 사용 사례나 시나리오는 무엇인가요?"
사용자 응답을 기다린 후 진행하세요. 모든 질문을 한 번에 던지지 마세요.
### 2단계: 참조 구현
참조로 사용할 수 있는 기존 코드에 대해 질문합니다:
1. **기존 구현**: "참조해야 할 기존 코드나 구현이 있나요?"
2. **파일 경로**: 있다면: "이러한 참조 구현의 파일 경로는 무엇인가요?"
3. **따라야 할 패턴**: "이러한 참조에서 따라야 할 특정 패턴, 아키텍처 또는 규칙이 있나요?"
### 3단계: 확장성 및 아키텍처
확장성 및 확장 가능성에 대한 정보를 수집합니다:
1. **향후 성장**: "어떤 확장성 고려사항을 다루어야 하나요? 예: 사용자 부하, 데이터 볼륨, 기능 확장 등"
2. **통합 지점**: "이 기능이 다른 시스템이나 서비스와 통합되어야 하나요?"
3. **성능 요구사항**: "특정 성능 요구사항이나 제약사항이 있나요?"
### 4단계: 저장 위치
PRD 문서는 **문서 생성 규칙**에 따라 자동으로 경로가 결정됩니다.
사용자에게 파일명만 확인받고, 디렉토리는 자동 생성합니다.
1. **파일명 확인**: "PRD 문서의 파일명을 지정해주세요 (예: `AI_SCENARIO_GENERATOR`)"
- 제공되지 않으면 기능명을 UPPER_SNAKE_CASE로 변환하여 사용
---
## 문서 생성 규칙
### 디렉토리 구조
```
documents/PRD/{연}-{월}-{주차}w/
```
- **연**: 4자리 연도 (예: 2025)
- **월**: 2자리 월 (예: 12)
- **주차**: 해당 월의 주차 (1~5) + `w` 접미사 (week의 약자)
**주차 계산**: 해당 월 1일부터 시작하여 7일 단위로 계산
- 1~7일: 1w (1주차)
- 8~14일: 2w (2주차)
- 15~21일: 3w (3주차)
- 22~28일: 4w (4주차)
- 29일~: 5w (5주차)
### 파일명 형식
```
{일}d-{hh}h-{파일명}.md
```
- **일**: 2자리 일 + `d` 접미사 (day의 약자, 예: 27d)
- **hh**: 2자리 시간(24시간제) + `h` 접미사 (hour의 약자, 예: 14h)
- **파일명**: UPPER_SNAKE_CASE (예: AI_SCENARIO_GENERATOR)
### 예시
2025년 12월 27일 14시에 AI 시나리오 생성기 PRD 생성 시:
```
documents/PRD/2025-12-4w/27d-14h-AI_SCENARIO_GENERATOR.md
```
### 디렉토리 자동 생성
지정된 디렉토리가 없으면 자동으로 생성합니다.
### 5단계: PRD 생성
모든 정보가 수집되면:
1. `assets/prd_template.md`에서 템플릿 읽기
2. **구현 시 사용할 스킬 판단** (아래 "구현 스킬 연동" 섹션 참조)
3. 다음 내용으로 모든 템플릿 플레이스홀더를 채워 포괄적인 PRD 생성:
- 기능 이름 및 개요
- 상세한 기능 설명
- 참조 구현 세부사항 (제공된 경우)
- 확장성 고려사항
- 구체적인 작업이 포함된 4단계 구현 계획
- 각 단계별 수용 기준
- 파일 구조 개요
- 논리적 섹션으로 나뉜 핵심 구현 세부사항
- 테스트 전략
- 잠재적 과제 및 해결책
- 향후 개선 아이디어
- **구현 시 사용할 스킬 (필수)**
3. 적절한 구조로 PRD 생성:
- 명확한 단계별 구현 계획
- 구체적이고 실행 가능한 작업
- 구체적인 수용 기준
- Claude Code가 따를 수 있는 기술적 세부사항
- 파일 조직 지침
4. 지정된 경로에 PRD 저장
5. 사용자에게 문서 링크 제공
## 템플릿 구조
PRD 템플릿(`assets/prd_template.md`)은 다음을 포함합니다:
- **개요**: 기능의 상위 수준 요약
- **기능 설명**: 상세한 기능
- **참조 구현**: 기존 코드에 대한 링크
- **기술 요구사항**: 핵심 기능 및 확장성
- **구현 계획**: 작업 및 수용 기준이 포함된 4단계
- 1단계: 설정 및 기반
- 2단계: 핵심 구현
- 3단계: 통합 및 테스트
- 4단계: 다듬기 및 최적화
- **파일 구조**: 제안된 디렉토리 레이아웃
- **핵심 구현 세부사항**: 기술적 세부사항
- **테스트 전략**: 구현 검증 방법
- **과제 및 해결책**: 예상되는 문제
- **향후 개선사항**: 확장 지점
- **Claude Code 실행 참고사항**: PRD 사용 방법
## 모범 사례
1. **대화형으로 진행**: 한 번에 한두 가지 질문을 자연스럽게 던지세요
2. **질문 조정**: 사용자 응답에 따라 후속 질문을 맞춤화하세요
3. **모호함 명확화**: 사용자 응답이 모호하면 구체적인 예를 요청하세요
4. **모듈식 사고**: 복잡한 기능을 논리적 단계로 나누세요
5. **구체적으로**: 추상적인 목표가 아닌 구체적인 작업을 생성하세요
6. **코드 참조**: 참조 구현이 있다면 읽고 패턴을 통합하세요
7. **확장성 고려**: 간단한 기능이라도 항상 확장성 고려사항을 포함하세요
8. **실행 가능하게**: 각 단계는 Claude Code가 실행할 수 있는 명확한 작업이 있어야 합니다
## 대화 흐름 예시
```
사용자: "사용자 인증 시스템에 대한 PRD를 만들고 싶어요"
Claude: "좋습니다! 사용자 인증 시스템에 대한 포괄적인 PRD를 작성하도록 도와드리겠습니다.
먼저, 원하시는 핵심 기능을 설명해주시겠어요? 예를 들어:
- 어떤 인증 방법을 사용하나요? (이메일/비밀번호, OAuth 등)
- 어떤 사용자 역할이나 권한이 필요한가요?
- 특정 보안 요구사항이 있나요?"
사용자: [세부사항 제공]
Claude: "감사합니다! 제가 참조해야 할 기존 인증 코드나 유사한 구현이 코드베이스에 있나요?"
사용자: [경로 제공 또는 없다고 답변]
Claude: "어떤 확장성 고려사항을 염두에 두어야 할까요? 예를 들어:
- 예상 사용자 수는?
- 속도 제한이 필요한가요?
- 세션 관리 전략은?"
사용자: [세부사항 제공]
Claude: "마지막으로, 이 PRD 문서를 어디에 저장하시겠어요?"
사용자: [경로 제공 또는 Claude가 기본값 사용하도록 함]
Claude: [포괄적인 PRD 생성 및 저장]
"사용자 인증 시스템에 대한 PRD를 작성했습니다. [문서 보기](computer:///path/to/prd.md)"
```
## PRD 생성 팁
- **1단계**는 설정에 집중: 의존성, 기본 구조, 구성
- **2단계**는 핵심 기능 구현
- **3단계**는 통합 지점 및 테스트 처리
- **4단계**는 다듬기 추가: 오류 처리, 엣지 케이스, 최적화
- 각 단계는 이전 단계를 기반으로 구축되어야 함
- 수용 기준은 테스트 가능하고 구체적이어야 함
- 참조 구현 패턴을 따르는 파일 구조 포함 (제공된 경우)
- **모든 내용은 한글로 작성**: 기능 설명, 작업, 수용 기준, 주석 등 모두 한글로 작성
---
## 구현 스킬 연동 (핵심)
PRD 생성 시 **반드시** 구현에 필요한 스킬을 판단하여 문서에 포함해야 합니다.
이를 통해 구현 일관성을 확보하고, 프로젝트 규약을 자동으로 준수할 수 있습니다.
### 스킬 판단 기준
| 스킬명 | 활성화 조건 | 담당 범위 |
|--------|------------|----------|
| `endpoint-implement-skill` | Entity, Repository, Service, Controller, DTO 중 **하나라도** 포함 | CRUD API 전체 레이어 구현 |
| `sse-streaming-skill` | SSE 스트리밍, `TEXT_EVENT_STREAM_VALUE`, 실시간 응답 포함 | SSE 컨트롤러/서비스 구현 |
### 스킬 판단 로직
PRD 내용을 분석하여 다음 키워드가 있으면 해당 스킬 사용을 안내합니다:
**endpoint-implement-skill 활성화 키워드:**
- Entity, 엔티티
- Repository, 레포지토리, JPA
- Service, 서비스
- Controller, 컨트롤러, API 엔드포인트
- DTO, Request, Response
- CRUD, 생성, 조회, 수정, 삭제
**sse-streaming-skill 활성화 키워드:**
- SSE, Server-Sent Events
- TEXT_EVENT_STREAM_VALUE
- 스트리밍 응답, 실시간 스트리밍
- SseEmitter, Flux<ServerSentEvent>
- 실시간 이벤트 전송
### PRD에 작성할 스킬 안내 예시
```markdown
## 구현 시 사용할 스킬
이 PRD를 구현할 때 다음 스킬을 **반드시** 활용하세요:
| 구현 영역 | 사용 스킬 | 활성화 조건 |
|----------|----------|------------|
| Entity ~ Controller | `endpoint-implement-skill` | 시나리오 CRUD API 구현 필요 |
| SSE 스트리밍 | `sse-streaming-skill` | AI 응답 실시간 스트리밍 필요 |
### 스킬 사용 순서
1. **1단계 (Entity/Repository)**: `endpoint-implement-skill` 호출
- Entity 정의, Repository 생성
2. **2단계 (Service/Controller)**: `endpoint-implement-skill` 계속 사용
- Service 비즈니스 로직, Controller 엔드포인트
3. **3단계 (SSE 통합)**: `sse-streaming-skill` 호출
- SSE 컨트롤러, 스트리밍 서비스 구현
### 스킬별 담당 범위
**endpoint-implement-skill:**
- `entity/Scenario.kt`, `entity/Character.kt` 등 Entity 파일
- `ScenarioRepository.kt` 등 Repository 인터페이스
- `ScenarioService.kt` 등 Service 클래스
- `ScenarioController.kt` 등 Controller 클래스
- `ScenarioRequestDto.kt`, `ScenarioResponseDto.kt` 등 DTO
**sse-streaming-skill:**
- `GameChatSseController.kt` SSE 전용 컨트롤러
- `GameChatStreamService.kt` 스트리밍 서비스
- SSE 이벤트 타입, 이미터 설정
```
### 복합 스킬 사용 시 주의사항
1. **스킬 간 경계를 명확히**: Entity~Controller는 endpoint-implement-skill, SSE 전용 로직은 sse-streaming-skill
2. **순서 준수**: 기반 Entity/Service가 먼저, SSE 통합은 나중에
3. **스킬 호출 시점 명시**: PRD의 각 단계에서 어떤 스킬을 호출해야 하는지 명시
### 스킬이 필요 없는 경우
다음 경우에는 스킬 연동 섹션을 생략할 수 있습니다:
- 설정 파일(application.yml) 변경만 필요한 경우
- 기존 코드 수정/리팩토링만 필요한 경우
- 문서화, 마이그레이션 가이드 등 비코드 작업
Appendix 2. Full Text of .claude/skills/prd-generator/assets/prd_template.md
# PRD: {{기능명}}
## 개요
{{기능_개요}}
## 기능 설명
{{기능_상세_설명}}
## 참조 구현
{{참조_구현}}
## 기술 요구사항
### 핵심 기능
{{핵심_기능}}
### 확장성 고려사항
{{확장성_고려사항}}
## 구현 계획
### 1단계: 설정 및 기반
**목표**: {{1단계_목표}}
**작업**:
1. {{1단계_작업1}}
2. {{1단계_작업2}}
3. {{1단계_작업3}}
**수용 기준**:
- {{1단계_수용기준1}}
- {{1단계_수용기준2}}
---
### 2단계: 핵심 구현
**목표**: {{2단계_목표}}
**작업**:
1. {{2단계_작업1}}
2. {{2단계_작업2}}
3. {{2단계_작업3}}
**수용 기준**:
- {{2단계_수용기준1}}
- {{2단계_수용기준2}}
---
### 3단계: 통합 및 테스트
**목표**: {{3단계_목표}}
**작업**:
1. {{3단계_작업1}}
2. {{3단계_작업2}}
3. {{3단계_작업3}}
**수용 기준**:
- {{3단계_수용기준1}}
- {{3단계_수용기준2}}
---
### 4단계: 다듬기 및 최적화
**목표**: {{4단계_목표}}
**작업**:
1. {{4단계_작업1}}
2. {{4단계_작업2}}
3. {{4단계_작업3}}
**수용 기준**:
- {{4단계_수용기준1}}
- {{4단계_수용기준2}}
## 파일 구조
```
{{파일_구조}}
```
## 핵심 구현 세부사항
### {{세부사항1_제목}}
{{세부사항1_내용}}
### {{세부사항2_제목}}
{{세부사항2_내용}}
### {{세부사항3_제목}}
{{세부사항3_내용}}
## 테스트 전략
{{테스트_전략}}
## 잠재적 과제 및 해결책
{{과제_및_해결책}}
## 향후 개선사항
{{향후_개선사항}}
## 구현 시 사용할 스킬
이 PRD를 구현할 때 다음 스킬을 **반드시** 활용하세요:
| 구현 영역 | 사용 스킬 | 활성화 조건 |
|----------|----------|------------|
| {{skill_table_rows}} |
### 스킬 사용 순서
{{skill_usage_order}}
### 스킬별 담당 범위
{{skill_coverage}}
---
## Claude Code 실행 참고사항
이 PRD는 순차적 구현을 위해 구조화되었습니다:
1. 1단계 작업부터 순서대로 시작
2. 각 단계는 이전 단계를 기반으로 구축됨
3. 다음 단계로 넘어가기 전에 수용 기준 검증
4. 구체적인 지침은 "핵심 구현 세부사항" 섹션 참조
5. 각 단계 검증 시 "테스트 전략" 사용
6. **위 "구현 시 사용할 스킬" 섹션의 스킬을 반드시 활용하여 구현 일관성 확보**
Closing
As AI coding environments get faster, I think the ability to organize work right before implementation becomes more important than raw implementation ability itself. prd-generator is a skill built exactly for that point.
What this skill does is not grand. It asks about the feature, checks the reference implementation, asks about scalability, applies the storage rules, and organizes everything into an implementable PRD. But once that process is turned into a structure, the implementation that follows becomes much less unstable.
If you are using Claude Code frequently for feature development, and you often have the idea but not a clear enough execution plan to get started quickly, I would strongly recommend organizing this skill first. More productivity than people expect comes not from writing code faster, but from defining the work more precisely before writing any code.
Attachment
I am attaching one document generated by the skill. It might be fun to think about what kind of prompt could have produced this document.
# Blog Service 다국어 번역 구조 도입 PRD
## 📋 개요
| 항목 | 내용 |
|------|------|
| **문서 ID** | PRD-2026-01-24-BLOG-MULTILANG |
| **작성일** | 2026-01-24 |
| **작성자** | Claude Code |
| **상태** | ✅ 완료 |
| **대상 서비스** | blog-service |
## 🎯 목표
Flashcard/FlashcardTranslation 패턴을 blog-service에 도입하여 Post, Category, Comment, Tag 엔티티의 다국어 지원을 구현한다.
## 📊 진행 현황
| # | Phase | 작업 항목 | 상태 | 완료일 |
|---|-------|----------|------|--------|
| 1 | Entity | PostTranslation.kt | ✅ 완료 | 2026-01-24 |
| 2 | Entity | CategoryTranslation.kt | ✅ 완료 | 2026-01-24 |
| 3 | Entity | CommentTranslation.kt | ✅ 완료 | 2026-01-24 |
| 4 | Entity | TagTranslation.kt | ✅ 완료 | 2026-01-24 |
| 5 | Repository | PostTranslationRepository.kt | ✅ 완료 | 2026-01-24 |
| 6 | Repository | CategoryTranslationRepository.kt | ✅ 완료 | 2026-01-24 |
| 7 | Repository | CommentTranslationRepository.kt | ✅ 완료 | 2026-01-24 |
| 8 | Repository | TagTranslationRepository.kt | ✅ 완료 | 2026-01-24 |
| 9 | DTO | PostDto.kt 수정 | ✅ 완료 | 2026-01-24 |
| 10 | DTO | CategoryDto.kt 수정 | ✅ 완료 | 2026-01-24 |
| 11 | DTO | CommentDto.kt 수정 | ✅ 완료 | 2026-01-24 |
| 12 | DTO | TagDto.kt 수정 | ✅ 완료 | 2026-01-24 |
| 13 | DTO | TranslationDto.kt 신규 | ✅ 완료 | 2026-01-24 |
| 14 | Service | PostService.kt 수정 | ✅ 완료 | 2026-01-24 |
| 15 | Service | CategoryService.kt 수정 | ✅ 완료 | 2026-01-24 |
| 16 | Service | CommentService.kt 수정 | ✅ 완료 | 2026-01-24 |
| 17 | Service | TagService.kt 수정 | ✅ 완료 | 2026-01-24 |
| 18 | Service | TranslationService.kt 신규 | ✅ 완료 | 2026-01-24 |
| 19 | Controller | PostController.kt 수정 | ✅ 완료 | 2026-01-24 |
| 20 | Controller | CategoryController.kt 수정 | ✅ 완료 | 2026-01-24 |
| 21 | Controller | CommentController.kt 수정 | ✅ 완료 | 2026-01-24 |
| 22 | Controller | TagController.kt 수정 | ✅ 완료 | 2026-01-24 |
| 23 | Controller | BoTranslationController.kt 신규 | ✅ 완료 | 2026-01-24 |
**진행률: 23/23 (100%) ✅ 완료**
---
## 🏗️ 기술 설계
### 1. 번역 대상 필드
| 엔티티 | 번역 필드 | 원본 길이 | 번역 길이 (2배) |
|--------|----------|----------|----------------|
| Post | title | 200 | 400 |
| Post | excerpt | TEXT | TEXT |
| Post | content | TEXT | TEXT |
| Category | name | 100 | 200 |
| Category | description | TEXT | TEXT |
| Comment | content | TEXT | TEXT |
| Tag | name | 50 | 100 |
### 2. 핵심 패턴 (Flashcard 검증 완료)
#### 2.1 Entity 패턴
```kotlin
@Entity
@Table(indexes = [...])
@IdClass(PostTranslationPk::class)
data class PostTranslation(
@Id @Column(updatable = false)
val postId: Long,
@Id @Column(length = 5, updatable = false)
val languageCode: String,
// 번역 필드들
var title: String,
var excerpt: String?,
var content: String
) : BaseTimeEntity()
data class PostTranslationPk(
val postId: Long? = null,
val languageCode: String? = null,
) : Serializable
```
#### 2.2 DTO 패턴
```kotlin
data class DetailResponse(
// 원본 필드
@get:JvmName("titleOriginal")
private val title: String,
// 번역 필드 (JSON 숨김)
@JsonIgnore
val translatedTitle: String? = null,
// 실제 응답 (번역 우선)
@JsonGetter("title")
fun getTitle(): String =
translatedTitle?.takeIf { it.isNotBlank() } ?: title
)
```
#### 2.3 Service JOIN 패턴
```kotlin
queryFactory
.select(PostDto.ListResponse.buildProjectionWithTranslation())
.from(post)
.leftJoin(postTranslation)
.on(postTranslation.postId.eq(post.id)
.and(postTranslation.languageCode.eq(lang)))
.fetch()
```
#### 2.4 Controller 패턴
```kotlin
@GetMapping("/posts")
fun findAll(
@RequestParam(required = false) lang: String?,
// ...
): JPage<PostDto.ListResponse>
```
### 3. 지원 언어 코드
---
## 📁 파일 경로
```
modules/blog-service/src/main/kotlin/com/jongmin/blog/
├── entity/
│ ├── PostTranslation.kt # 신규
│ ├── CategoryTranslation.kt # 신규
│ ├── CommentTranslation.kt # 신규
│ └── TagTranslation.kt # 신규
├── repository/
│ ├── PostTranslationRepository.kt # 신규
│ ├── CategoryTranslationRepository.kt # 신규
│ ├── CommentTranslationRepository.kt # 신규
│ └── TagTranslationRepository.kt # 신규
├── dto/
│ ├── PostDto.kt # 수정
│ ├── CategoryDto.kt # 수정
│ ├── CommentDto.kt # 수정
│ ├── TagDto.kt # 수정
│ └── TranslationDto.kt # 신규
├── service/
│ ├── PostService.kt # 수정
│ ├── CategoryService.kt # 수정
│ ├── CommentService.kt # 수정
│ ├── TagService.kt # 수정
│ └── TranslationService.kt # 신규
└── controller/
├── PostController.kt # 수정
├── CategoryController.kt # 수정
├── CommentController.kt # 수정
├── TagController.kt # 수정
└── BoTranslationController.kt # 신규
```
---
## 📝 작업 로그
### 2026-01-24
- **15:00** - PRD 문서 생성, 작업 계획 수립 완료
---
## 🔗 참조
- **레퍼런스 구현**: `legacy-service/catch_on/platform/entity/FlashcardTranslation.kt`
- **레퍼런스 서비스**: `legacy-service/catch_on/platform/service/SubjectService.kt`
- **레퍼런스 DTO**: `legacy-service/catch_on/platform/dto/response/FlashCardResponseDto.kt`