Présentation du skill de génération de PRD que j’utilise
Introduction
Le moment où l’implémentation d’une fonctionnalité se bloque n’arrive souvent pas après avoir commencé à écrire du code, mais avant cela. Quand on n’a pas clarifié ce qu’il faut construire, jusqu’où aller, dans quel ordre découper le travail et sur quelles parties du code existant s’appuyer, passer directement à l’implémentation déstabilise à la fois l’agent et la personne.
C’est pour cette raison que je ne considère pas un PRD comme un simple document de planification. Dans un environnement actuel de codage assisté par l’IA, un PRD est déjà très proche d’un plan d’exécution. En particulier, si vous utilisez un agent de codage comme Claude Code, la manière de structurer et de transmettre le travail change fortement la densité du résultat, souvent davantage que la simple définition de ce qu’il faut construire.
Dans cet article, je voudrais présenter l’un des skills que j’utilise, .claude/skills/prd-generator. Ce skill recueille de manière interactive les exigences d’une nouvelle fonctionnalité et les organise en un document PRD que Claude Code peut enchaîner directement vers la phase d’implémentation. Comme il s’agit d’un article de partage de ressources, je ne me contente pas d’un résumé intermédiaire : vous trouverez plus bas le texte intégral de SKILL.md ainsi que celui du modèle associé.
Pourquoi un tel skill était nécessaire
Laisser quelques notes rapides avant de créer une fonctionnalité et produire un PRD réellement implémentable sont deux choses complètement différentes.
Une note d’idée sommaire va vite, mais elle laisse vite échapper des éléments importants.
- La fonctionnalité centrale est notée, mais aucun scénario utilisateur n’est défini
- Il y a un plan d’implémentation, mais pas de critères d’acceptation
- Il existe du code à prendre en référence, mais le lien n’est pas établi
- On oublie quel skill d’implémentation devra être utilisé ensuite
- Le lieu et le nom d’enregistrement du document varient à chaque fois
Dans un tel état, même s’il existe un document, on ne peut pas passer directement à l’exécution. Il faut finalement reposer des questions, réorganiser les informations et redéfinir la structure.
prd-generator est précisément le skill que j’ai créé pour réduire ce gaspillage intermédiaire. Si l’on fixe d’un seul mouvement l’ordre des questions, le format du document, les règles d’enregistrement, les étapes d’implémentation et même l’enchaînement avec les skills d’implémentation, le PRD cesse d’être une simple note descriptive et devient une unité d’exécution immédiatement exploitable.
Si je devais décrire ce skill en une phrase
Lorsque je dois expliquer ce skill de la manière la plus courte possible, je le présente ainsi.
prd-generator est un skill qui recueille de manière interactive les exigences d’une nouvelle fonctionnalité, puis les transforme en un document PRD complet optimisé pour l’exécution dans Claude Code.
Dans les faits, sa structure est simple.
.claude/skills/prd-generator/
SKILL.md
assets/
prd_template.md
Mais au regard de cette structure de dossier très simple, son rôle est assez large. Il ne se contente pas de poser quelques questions puis de s’arrêter : il décide aussi des règles d’enregistrement du document, de la forme du plan d’implémentation, des critères d’acceptation et même du skill qu’il faudra appeler ensuite.
Le workflow permet de mieux voir l’intention de conception
Le cœur de ce skill réside dans la qualité du flux de conversation. Au lieu d’écrire un PRD d’un seul jet, il a été conçu pour recueillir les informations nécessaires dans un ordre précis.
Étape 1 : exploration de la fonctionnalité
Il commence par demander une vue d’ensemble de la fonctionnalité, ses fonctions clés et les principaux cas d’usage.
Le point important ici est qu’il ne déverse pas toutes les questions d’un coup. Le document du skill précise même : « Ne posez pas toutes les questions en une seule fois ». Cette seule ligne est plus importante qu’il n’y paraît. Un bon PRD ne se tire pas d’un questionnaire lancé en rafale ; il se construit en resserrant progressivement le périmètre au fil des réponses.
Étape 2 : vérification des implémentations de référence
Ensuite, il interroge sur le code existant ou les schémas d’implémentation à prendre en référence.
Cette étape est précieuse pour une raison simple. En pratique, une nouvelle fonctionnalité arrive bien plus souvent dans un cadre où il faut suivre une structure existante que sur une toile complètement blanche. Dès lors que l’on récupère les chemins et que l’on confirme les schémas et règles à suivre, le PRD n’est plus une spécification abstraite : il devient un document de travail connecté à la base de code réelle.
Étape 3 : extensibilité et architecture
Ensuite, il pose des questions sur la croissance future, les points d’intégration et les exigences de performance.
C’est l’un des aspects que j’apprécie le plus. Même pour une fonctionnalité simple, la tentation existe souvent de se contenter de quelque chose qui fonctionne immédiatement. Mais ce skill introduit d’emblée des questions d’extensibilité, ce qui oblige à laisser au moins une trace minimale de la charge future dans le document.
Étape 4 : choix de l’emplacement d’enregistrement
Ici, il ne demande pas à l’utilisateur de définir tout le chemin du répertoire. Il ne valide que le nom du fichier, puis calcule automatiquement le chemin d’enregistrement en appliquant les règles de génération de document.
Ce choix est lui aussi très pratique. Si l’on oblige les gens à réfléchir chaque fois au chemin et au nom du fichier, la documentation se disperse. À l’inverse, si l’on fixe la règle d’enregistrement, les documents se retrouvent plus facilement ensuite et les PRD s’accumulent comme de véritables actifs de travail.
Étape 5 : génération du PRD proprement dite
Lors de la dernière étape, il lit le modèle, remplit les placeholders, détermine les skills d’implémentation et finalise le document.
C’est ici que l’identité du skill apparaît le plus clairement. Son objectif n’est pas simplement d’« écrire un document de planification », mais de produire un PRD exécutable qui remplit sans omission les éléments ci-dessous.
- Nom et vue d’ensemble de la fonctionnalité
- Description détaillée de la fonctionnalité
- Implémentations de référence
- Points d’attention relatifs à l’extensibilité
- Plan d’implémentation en 4 étapes
- Critères d’acceptation de chaque étape
- Structure des fichiers
- Détails clés de l’implémentation
- Stratégie de test
- Problèmes potentiels et solutions
- Améliorations futures
- Skills à utiliser lors de l’implémentation
Le fait qu’il embarque aussi les règles de génération du document est important
prd-generator n’est pas seulement un skill qui pose les bonnes questions. Il définit aussi de façon explicite l’emplacement où enregistrer le PRD généré.
documents/PRD/{연}-{월}-{주차}w/{일}d-{hh}h-{파일명}.md
Cette règle est plus importante qu’il n’y paraît. Pour qu’un document demeure un actif du projet, il faut non seulement un contenu cohérent, mais aussi une méthode d’enregistrement cohérente. Ce skill va jusqu’à fixer la règle de calcul de la semaine et précise que le répertoire doit être créé automatiquement s’il n’existe pas.
Autrement dit, ce skill ne s’arrête pas au fait de bien écrire le document : il s’intéresse aussi à la manière de le laisser dans un état qui restera administrable plus tard.
La longueur du modèle est plutôt un avantage
À la première lecture, on peut trouver ce modèle assez long. Pourtant, je considère que cette longueur est précisément l’un de ses points forts.
Un modèle court va vite, mais il laisse aussi davantage de blancs que l’on doit compléter soi-même. À l’inverse, ce modèle expose dès le départ presque toutes les rubriques nécessaires.
- Vue d’ensemble
- Description de la fonctionnalité
- Implémentations de référence
- Fonctionnalités clés
- Considérations d’extensibilité
- Plan d’implémentation en 4 étapes
- Structure des fichiers
- Détails clés de l’implémentation
- Stratégie de test
- Problèmes potentiels et solutions
- Améliorations futures
- Skills à utiliser lors de l’implémentation
- Notes d’exécution pour Claude Code
Quand autant de rubriques sont ouvertes, on voit immédiatement au moins ce qui manque. C’est précisément là que je vois la valeur d’un modèle de PRD. Un bon modèle n’est pas un outil qui rend le document joli, mais un outil qui réduit les oublis de raisonnement.
L’articulation avec les skills d’implémentation est le cœur du skill
Dans ce skill, il y a un autre point que j’apprécie particulièrement. Lors de la génération du PRD, il détermine quels skills d’implémentation doivent être inclus dans le document.
Beaucoup de PRD s’arrêtent au document lui-même. Pourtant, dans le travail réel, la suite est encore plus importante. Si l’on ne relie pas aussi quel skill utiliser pour implémenter et dans quel ordre l’appeler, le PRD et l’implémentation se séparent de nouveau.
Pour éviter cela, prd-generator prévoit une section distincte consacrée à l’articulation avec les skills d’implémentation.
À la date du document actuel, deux skills sont évalués comme centraux.
| Nom du skill | Condition d’activation | Portée prise en charge |
|---|---|---|
endpoint-implement-skill | Inclus dès qu’au moins l’un de Entity, Repository, Service, Controller ou DTO est concerné | Implémentation de toutes les couches d’une API CRUD |
sse-streaming-skill | Inclus en cas de streaming SSE, TEXT_EVENT_STREAM_VALUE ou réponse en temps réel | Implémentation du contrôleur et du service SSE |
La qualité de cette logique de décision saute aux yeux. Le PRD cesse d’être un simple document descriptif et devient un document qui indique l’action suivante.
Par exemple, si une fonctionnalité nécessite des éléments allant de l’Entity au Controller, on peut laisser une instruction explicite indiquant d’utiliser endpoint-implement-skill. S’il y a un besoin de streaming de réponses IA, on peut aussi préciser à quelle étape rattacher sse-streaming-skill. Une telle connexion réduit fortement l’errance, tant pour la personne qui lit le document que pour l’agent.
Quand ce skill est particulièrement utile
Ce skill n’est pas indispensable dans tous les cas. Mais il est particulièrement efficace dans les situations suivantes.
- lorsqu’il faut concevoir une nouvelle fonctionnalité entièrement à partir de zéro
- lorsqu’il existe clairement du code existant à prendre en référence
- lorsqu’il existe des exigences fonctionnelles, mais que l’ordre d’implémentation reste encore flou
- lorsqu’on prévoit d’enchaîner directement ensuite avec Claude Code ou un autre skill d’implémentation
- lorsqu’il faut conserver le document comme un actif d’équipe
À l’inverse, il peut être excessif pour un simple changement de configuration ou une correction très limitée. Ce skill ressemble moins à un outil de mémo léger qu’à un outil destiné à structurer et transmettre le développement d’une fonctionnalité.
Je laisse aussi le texte intégral pour le partage de ressources
Jusqu’ici, il s’agissait de l’explication. À partir de maintenant, c’est une annexe destinée au partage du matériau source. Comme demandé, je laisse le texte intégral de SKILL.md et de assets/prd_template.md sans le condenser, afin que vous puissiez consulter directement le contenu central de .claude/skills/prd-generator.
Annexe 1. .claude/skills/prd-generator/SKILL.md en intégralité
---
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) 변경만 필요한 경우
- 기존 코드 수정/리팩토링만 필요한 경우
- 문서화, 마이그레이션 가이드 등 비코드 작업
Annexe 2. .claude/skills/prd-generator/assets/prd_template.md en intégralité
# 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. **위 "구현 시 사용할 스킬" 섹션의 스킬을 반드시 활용하여 구현 일관성 확보**
Conclusion
Plus l’environnement de codage assisté par l’IA s’accélère, plus je pense qu’il devient important de bien organiser l’étape juste avant l’implémentation, encore davantage que de simplement bien implémenter. prd-generator traite précisément ce point.
Ce que fait ce skill n’a rien de grandiloquent. Il pose des questions sur la fonctionnalité, vérifie les implémentations de référence, interroge l’extensibilité, applique les règles d’enregistrement et organise le tout en un PRD implémentable. Mais une fois ce processus structuré, l’implémentation suivante devient beaucoup plus stable.
Si vous développez souvent des fonctionnalités avec Claude Code et que le départ tarde à chaque fois parce que l’idée existe mais que le plan d’exécution reste flou, je recommande vraiment de commencer par structurer ce skill. Une part plus importante qu’on ne le croit de la productivité ne vient pas du fait d’écrire le code plus vite, mais du fait d’organiser plus précisément ce qui précède l’écriture du code.
Pièce jointe
Je joins un document généré par ce skill. Il peut aussi être intéressant d’imaginer à partir de quel prompt ce document a été produit.
# 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`