prd-generator

PRD 生成スキル

概要

問題を起点とし、仮説に基づく手法で構造化されたプロダクト要件定義書（PRD）を生成します。明確な問題の記述、根拠に裏付けられた意思決定、追跡可能な実装フェーズを実現します。

基本原則：「どのように」より先に「なぜ」を検証します。問題 → 根拠 → 仮説 → ソリューション。

使用する場面

常に使用：

• プロダクト定義が必要な新機能
• ステークホルダー間の合意形成が必要なプロダクト変更
• 複雑度が HIGH／EPIC の機能に関する要件の収集
• 構造化された分析が必要な機能リクエスト

特に次の場合に使用：

• 要件が不明確な機能（段階的な情報開示）
• 追跡が必要な複数フェーズの実装
• 意思決定の記録が必要な機能
• 成功指標が必要なプロダクト施策

使用しない場面：

• 単純なバグ修正（PRD は不要）
• 些細な設定変更
• プロダクトへの影響を伴わない、コードのみのリファクタリング

目的

1. 問題を起点とする： ソリューションを提案する前に、根拠を用いて問題を定義します
2. 仮説に基づく： 検証可能な測定可能な仮説を提示します
3. MoSCoW による優先順位付け： Must／Should／Could／Won't を用いてスコープの拡大を防ぎます
4. 実装フェーズ： フェーズ表（ステータス、依存関係、計画へのリンク）を使用して進捗を追跡します
5. 意思決定ログ： 将来参照できるよう、「Y ではなく X を選んだ理由」を記録します
6. 追跡可能性： PRD → Planner → Developer の間でコンテキストをすべて引き継ぎます

ワークフロー

ステップ 1：要件を収集する

対話モード（要件が不明確な場合）：

// Use AskUserQuestion for structured gathering
const problem = await AskUserQuestion({
  question: 'What problem does this solve? (Be specific about user pain points)',
});

const evidence = await AskUserQuestion({
  question: 'What evidence shows this problem exists? (Data, feedback, metrics)',
});

const hypothesis = await AskUserQuestion({
  question: 'What measurable outcome will prove this feature solves the problem?',
});

プロンプトモード（要件が提示されている場合）：

Extract requirements from user prompt or task description

段階的な情報開示（要件が曖昧な機能の場合）：

要件が不明確な場合は、8 フェーズの質問ワークフローを使用します。

1. 開始： 機能の目標とスコープを明確にします
2. 基盤： 問題の背景を把握します
3. 根拠（市場）： 類似するソリューションを調査します
4. 詳細調査： 機能とユーザーフローを検討します
5. 根拠（技術）： 実現可能性を評価します
6. 意思決定： 選択肢とトレードオフを記録します
7. 生成： 収集したコンテキストから PRD を作成します

段階的な情報開示を使用する場面：

• 複雑度が HIGH／EPIC の機能
• 曖昧なユーザーリクエスト（「もっとよくして」など）
• 既存のパターンがない新しいプロダクト領域
• ステークホルダー間の合意形成が必要な機能

省略する場面：

• 要件が明確に提示されている場合
• 類似する機能がすでに実装されている場合
• スコープの小さな変更

ステップ 2：テンプレートを読み込む

// Read PRD template
const template = Read({ file_path: '.claude/templates/prd-template.md' });

テンプレートには以下のセクションが含まれます（必須）。

• 問題の記述
• 根拠
• 主要な仮説
• 今回構築しないもの（スコープの除外項目）
• 成功指標の表
• コア機能（MoSCoW）
• ユーザーとコンテキスト
• ソリューションの詳細（MVP のスコープ、ユーザーフロー）
• 技術的アプローチ
• 実装フェーズの表
• 意思決定ログの表
• 調査の概要
• リスクの表
• 未解決の質問

ステップ 3：テンプレートの各セクションを記入する

問題の記述（エビデンスに基づく）：

## Problem Statement

[Specific problem description with user impact]

## Evidence

- User feedback: [quotes or summary]
- Data: [metrics showing problem scale]
- Business impact: [why this matters now]

主要な仮説：

## Key Hypothesis

We believe [capability] will [solve problem] for [users].
We'll know we're right when [measurable outcome].

Example:
We believe adding JWT refresh tokens will reduce user re-authentication friction for mobile users.
We'll know we're right when session timeout complaints drop by 50% and mobile DAU increases by 10%.

成功指標：

指標	目標	測定方法
セッションタイムアウトに関する苦情	-50%	サポートチケットの分析
モバイル DAU	+10%	アナリティクスダッシュボード
トークン更新の成功率	>95%	バックエンドログ

主要な機能（MoSCoW）：

優先度	機能	理由
必須	JWT リフレッシュトークンエンドポイント	MVP に必須 — セッションの延長が可能になります
必須	更新時のトークンローテーション	セキュリティのベストプラクティス
推奨	リフレッシュトークンの失効	ユーザーがすべてのデバイスからログアウトできます
あればよい	トークン使用状況の分析	モニタリングに役立ちます
対象外	生体認証の統合	対象範囲外 — 今後検討します

MoSCoW の定義：

• 必須：MVP の阻害要因 — これがなければ機能が成立しません
• 推奨：価値が高く、時間が許せば含めます
• あればよい：あると便利ですが、必要に応じて延期します
• 対象外：現在の対象範囲から明示的に除外します

ユーザーとコンテキスト：

## Users & Context

**Primary User**: Mobile app user (iOS/Android) who experiences session expiration mid-workflow

**Current Behavior**: User logs in → session expires after 1 hour → forced to re-login → loses context

**Trigger**: Session expiration during active use

**Success State**: User stays logged in seamlessly, only re-authenticates when truly needed

**Job to Be Done**: When my session expires, I want to continue my work without re-entering credentials, so I can maintain my workflow momentum.

実装フェーズの表：

#	フェーズ	説明	ステータス	並行実行	依存関係	計画リンク
1	設計	リフレッシュトークンフローを含む認証アーキテクチャの設計	pending	No	-	-
2	バックエンド API	トークンローテーションを伴う /refresh エンドポイントの実装	pending	No	1	-
3	モバイルクライアント	モバイル SDK にリフレッシュ処理を追加	pending	No	2	-
4	テスト	リフレッシュフローの E2E テスト	pending	Yes	2,3	-
5	モニタリング	ダッシュボードにリフレッシュ指標を追加	pending	Yes	2	-

フェーズの各列の説明：

• #：フェーズ番号
• フェーズ：フェーズの短い名称
• 説明：このフェーズで実装する内容
• ステータス：pending | in_progress | completed | blocked
• 並行実行：ほかのフェーズと並行して実行できますか？
• 依存関係：先に完了する必要があるフェーズ（カンマ区切りの番号）
• 計画リンク：プランナーの実装計画へのリンク（.claude/context/plans/impl-{phase}-{date}.md）

決定事項の記録：

決定事項	選択	代替案	理由
トークンの保存	セキュアストレージ（Keychain/KeyStore）	ローカルストレージ、セッションストレージ	セキュリティ要件 — トークンは機密情報です
リフレッシュ戦略	401 発生時に自動実行	ユーザーによる手動操作	ユーザーに意識させず、UX が向上します
トークンの有効期間	アクセス：1時間、リフレッシュ：30日	アクセス：5分、リフレッシュ：90日	セキュリティと UX のバランス

調査の概要：

## Research Summary

**Market Context:**

- Auth0, Firebase use similar refresh token patterns
- Industry standard: short-lived access + long-lived refresh
- OWASP recommends token rotation on refresh

**Technical Context:**

- Existing JWT library supports refresh
- Mobile SDK has secure storage
- Backend already has session management

リスク：

リスク	発生可能性	緩和策
トークンの窃取	中	セキュアストレージを使用し、更新時にローテーションする
リフレッシュループ（無効なトークン）	低	指数バックオフと最大再試行回数を設定する
クロックスキューの問題	低	exp の検証に 5分間の猶予期間を設ける

未解決の質問：

## Open Questions

- [ ] What happens to active refresh tokens on password change?
- [ ] How do we handle token refresh during network outage?
- [ ] Should we notify user on refresh token expiration?

ステップ 4：完全性を検証する

必須セクションのチェックリスト：

const requiredSections = [
  'Problem Statement',
  'Evidence',
  'Key Hypothesis',
  'Success Metrics',
  'Core Capabilities',
  'Implementation Phases',
  'Decisions Log',
];

// Verify all present
const missingRequiredSections = requiredSections.filter(section => !prdContent.includes(section));

if (missingRequiredSections.length > 0) {
  throw new Error(`Missing required sections: ${missingRequiredSections.join(', ')}`);
}

品質チェック：

• 問題の記述が具体的である（曖昧ではない）
• 根拠にデータまたはユーザーからのフィードバックが含まれている
• 仮説が測定可能である（指標が含まれている）
• MoSCoW に「Must」が 1 つ以上、「Won't」が 1 つ以上含まれている
• 実装フェーズの依存関係が明確になっている
• 決定ログで、代替案について「なぜ X ではないのか」が説明されている

ステップ 5：PRD を作成する

// Generate filename
const featureName = 'auth-refresh-tokens'; // from problem statement
const date = new Date().toISOString().split('T')[0]; // YYYY-MM-DD
const filename = `${featureName}-prd-${date}.md`;

// Write to specs directory
Write({
  file_path: `.claude/context/artifacts/specs/${filename}`,
  content: prdContent,
});

出力先： .claude/context/artifacts/specs/{feature-name}-prd-{YYYY-MM-DD}.md

出典情報ヘッダー：

# PRD: {Feature Name}

**Version**: 1.0
**Author**: PM Agent
**Date**: {YYYY-MM-DD}
**Status**: Draft

統合ポイント

PRD → プランナー → 開発者のフロー

PM が PRD を作成する：

## Implementation Phases

| #   | Phase   | Description       | Status  | Parallel | Depends | Plan Link |
| --- | ------- | ----------------- | ------- | -------- | ------- | --------- |
| 1   | Design  | Auth architecture | pending | No       | -       | -         |
| 2   | Backend | /refresh endpoint | pending | No       | 1       | -         |

プランナーが PRD を読む：

1. TaskGet({ taskId: 'X' }) → PRD の場所を取得します
2. PRD を読む → 問題、決定事項、フェーズを理解します
3. 次に着手可能なフェーズ（依存関係が満たされているもの）を選択します
4. 実装計画を作成します
5. 計画へのリンクを PRD に追加します：

| 1 | Design | Auth architecture | completed | No | - | [Plan](.claude/context/plans/impl-phase1-2026-02-09.md) |

開発者が計画を読む：

1. プランナーの計画から PRD にリンクします
2. 開発者は問題、決定事項、根拠を含むすべての背景情報を把握できます
3. 「なぜ」を理解したうえで実装します

結果：

• 信頼できる唯一の情報源：ステータスは PRD のフェーズ表で確認できます
• トレーサビリティ：PRD → 計画 → 実装
• コンテキストの保持：新しい開発者も PRD を読めば機能を理解できます

必須セクションのチェックリスト

PRD を作成する前に、以下を確認します。

• 問題の記述（具体的で、曖昧ではない）
• 根拠（データ、フィードバック、指標）
• 主要な仮説（測定可能な成果）
• 成功指標の表（指標 | 目標 | 測定方法）
• 主要機能（Must／Should／Could／Won't による MoSCoW）
• 実装フェーズの表（# | フェーズ | ステータス | 依存関係 | 計画リンク）
• 決定ログ（決定 | 選択肢 | 代替案 | 根拠）
• ユーザーとコンテキスト（主要ユーザー、達成すべきジョブ）
• 技術的アプローチ（実現可能性、依存関係）
• リスクの表（リスク | 発生可能性 | 軽減策）
• 未解決の質問（未解決項目）

よくあるパターン

パターン 1：機能リクエスト → PRD

User: "Add dark mode to the app"

PM:
1. Problem: Users report eye strain in low-light conditions
2. Evidence: 200+ support tickets, 4.2 → 3.8 app rating mentions "too bright"
3. Hypothesis: Dark mode will reduce eye strain complaints by 60%
4. MoSCoW:
   - Must: System-default theme detection
   - Must: Manual toggle in settings
   - Should: Per-screen theme override
   - Won't: Automatic sunset-based switching (future)
5. Phases:
   - Phase 1: Design system color tokens
   - Phase 2: Implement theme provider
   - Phase 3: Update all screens
6. Write PRD → specs/dark-mode-prd-2026-02-09.md

パターン 2：曖昧なリクエスト → 段階的な情報開示

User: "Make the app faster"

PM:
1. [Progressive Disclosure: 8-phase questioning]
   - What specific slowness? (App launch? Navigation? Data load?)
   - Where is evidence? (Metrics showing 5s app launch vs 2s competitor)
   - What outcome? (Launch time < 2s for 95th percentile)
2. [After gathering context]
   - Problem: App launch time 5s vs industry 2s
   - Hypothesis: Lazy loading modules will reduce launch to <2s
3. Write PRD → specs/app-launch-performance-prd-2026-02-09.md

パターン 3：実装中の PRD 更新

Planner completes Phase 1 design:

Update PRD:
| 1 | Design | Auth architecture | completed | No | - | [Plan](.claude/context/plans/impl-phase1-2026-02-09.md) |
| 2 | Backend | /refresh endpoint | in_progress | No | 1 | [Plan](.claude/context/plans/impl-phase2-2026-02-09.md) |

Add decision to log:
| Token algorithm | RS256 | HS256 | RS256 for key rotation support |

ベストプラクティス

推奨事項：

• 解決策ではなく、問題から始めます
• 根拠（データ、引用、指標）を含めます
• 仮説を測定可能にします
• 「Won't」を明記します（スコープの拡大を防ぐため）
• フェーズの依存関係を明確に示します
• 検討した代替案とともに決定事項を記録します
• フェーズを実装計画にリンクします
• フェーズの完了に応じて PRD を更新します

禁止事項：

• 問題を記述せずに解決策へ飛びつく
• 根拠の収集を省く
• 曖昧な成功指標（「改善する」など）を使う
• 優先順位付けを忘れる（すべてを「Must」にする）
• 依存関係を明確にせずにフェーズを作成する
• 決定の根拠を省く
• PRD を古いままにする（フェーズの進行に合わせて更新する）
• 些細な変更に PRD を作成する

絶対遵守事項

1. 決して、根拠を示して問題を明確にする前に解決策を定義してはいけません。解決策を先に考えると、誰も必要としていない機能や、検証できない仮説が生まれます。
2. MoSCoW の優先順位付けには、必ず「Won't」を少なくとも 1 つ含めてください。明示的な対象外項目によって、スコープの拡大や機能の無秩序な増加を防げます。
3. 成功の仮説は、具体的な数値目標を用いて必ず測定可能にしてください。「UX の向上」や「パフォーマンスの高速化」のような曖昧な成果は、検証も反証もできません。
4. 実装開始前に、フェーズの依存関係を必ず明確にしてください。見落とされた依存関係は、スプリント中のブロッカーを生み、ロードマップ全体に遅延を波及させます。
5. 実装中に PRD を古いままにしてはいけません。作業の進行や新たな発見に合わせて、フェーズのステータスと決定ログを継続的に更新してください。

アンチパターン

アンチパターン	失敗する理由	正しいアプローチ
問題を明示せずに解決策に飛びつく	誤ったものを作ってしまい、成功を測る基準がありません	解決策を提案する前に、根拠をもとに問題を定義します
成功指標が曖昧（「UX を改善する」「高速化する」）	仮説を検証できず、機能が成功したかどうかを判断できません	数値目標を指定します：「サポートチケットを50％削減」「読み込み時間を2秒未満」
MoSCoWですべてを「Must」にする	優先順位を付けられず、実現不可能なスコープとなり、期限を逃します	Won't項目を明示し、Could／Shouldは調整可能なものとして扱います
依存関係を整理せずにフェーズを設定する	依存関係が明らかになったとき、並行実行の前提が崩れます	実装前に「Depends」列を整理し、それに応じて作業をブロックします
キックオフ後にPRDを更新しない	開発者が背景を見失い、判断が共有されない属人的な知識になります	実装中はフェーズのステータスと決定ログを更新します

例：完成したPRD

# PRD: JWT Refresh Token Implementation

**Version**: 1.0
**Author**: PM Agent
**Date**: 2026-02-09
**Status**: Draft

---

## Problem Statement

Mobile app users experience session expiration (1 hour timeout) during active use, forcing re-authentication and losing workflow context. This creates friction and frustration, particularly for users performing multi-step tasks.

## Evidence

- **Support Tickets**: 200+ complaints about "forced logout" in past 2 months
- **Analytics**: 35% of mobile sessions end with forced re-auth (vs 5% desktop)
- **User Feedback**: App store reviews mention "annoying login prompts" (4.2 → 3.8 rating)
- **Business Impact**: 15% cart abandonment rate correlates with session timeout

## Key Hypothesis

We believe adding JWT refresh tokens will reduce user re-authentication friction for mobile users.
We'll know we're right when session timeout complaints drop by 50% and mobile DAU increases by 10%.

## What We're NOT Building

- Biometric authentication integration (future Phase 2)
- Social login providers (separate initiative)
- Multi-device session management (v2.0)

## Success Metrics

| Metric                     | Target | How Measured            |
| -------------------------- | ------ | ----------------------- |
| Session timeout complaints | -50%   | Support ticket analysis |
| Mobile DAU                 | +10%   | Analytics dashboard     |
| Token refresh success rate | >95%   | Backend logs            |
| Forced re-auth rate        | <10%   | Analytics events        |

## Core Capabilities (MoSCoW)

| Priority | Capability                               | Rationale                                    |
| -------- | ---------------------------------------- | -------------------------------------------- |
| Must     | JWT refresh token endpoint               | Required for MVP - enables session extension |
| Must     | Token rotation on refresh                | Security best practice (OWASP)               |
| Must     | Secure token storage (Keychain/KeyStore) | Prevent token theft                          |
| Should   | Refresh token revocation                 | Allows user logout from all devices          |
| Should   | Token usage analytics                    | Monitoring and debugging                     |
| Could    | Configurable token lifetimes             | Admin flexibility                            |
| Won't    | Biometric auth integration               | Out of scope - future consideration          |
| Won't    | Push notification on token expiry        | Nice to have, defer to v2                    |

## Users & Context

**Primary User**: Mobile app user (iOS/Android) who experiences session expiration during active use (shopping, form filling, browsing)

**Current Behavior**: User logs in → performs task → session expires after 1 hour → forced to re-login → loses form data/cart context

**Trigger**: Session expiration during active use OR app returning from background after >1 hour

**Success State**: User stays logged in seamlessly for up to 30 days (refresh token lifetime), only re-authenticates when truly needed

**Job to Be Done**: When my session expires, I want to continue my work without re-entering credentials, so I can maintain my workflow momentum and complete my tasks.

## Solution Detail

### MVP Scope

**Phase 1**: Design auth architecture with refresh token flow
**Phase 2**: Implement backend /refresh endpoint with token rotation
**Phase 3**: Add refresh logic to mobile SDK (iOS/Android)
**Phase 4**: E2E tests for refresh flows
**Phase 5**: Add refresh metrics to monitoring dashboard

### User Flow

1. User logs in → receives access token (1 hour) + refresh token (30 days)
2. User makes API call → server validates access token
3. Access token expires → next API call returns 401
4. Mobile SDK detects 401 → calls /refresh with refresh token
5. Server validates refresh token → issues new access + refresh tokens
6. SDK retries original API call with new access token
7. User continues seamlessly (no re-login)

### Edge Cases

- Network failure during refresh → retry with exponential backoff
- Refresh token expired → force re-login with "session expired" message
- Refresh token revoked (password change) → force re-login
- Concurrent API calls during refresh → queue and retry after refresh completes

## Technical Approach

**Feasibility**: HIGH

**Dependencies**:

- Existing JWT library (jsonwebtoken) supports refresh
- Mobile SDK has secure storage (Keychain/KeyStore)
- Backend has session management infrastructure

**Integration Points**:

- Mobile SDK (iOS/Android) needs refresh interceptor
- Backend needs /refresh endpoint
- Database needs refresh token storage (w/ expiry)

**Architecture Notes**:

- Access token: 1 hour lifetime, stateless (JWT)
- Refresh token: 30 days lifetime, stateful (stored in DB)
- Token rotation: each refresh invalidates old token, issues new one
- Secure storage: Keychain (iOS), KeyStore (Android)

## Implementation Phases

| #   | Phase       | Description                                      | Status  | Parallel | Depends | Plan Link |
| --- | ----------- | ------------------------------------------------ | ------- | -------- | ------- | --------- |
| 1   | Design      | Auth architecture design with refresh token flow | pending | No       | -       | -         |
| 2   | Backend API | Implement /refresh endpoint with token rotation  | pending | No       | 1       | -         |
| 3   | Mobile SDK  | Add refresh logic to iOS/Android SDK             | pending | No       | 2       | -         |
| 4   | Testing     | E2E tests for refresh flows                      | pending | Yes      | 2,3     | -         |
| 5   | Monitoring  | Add refresh metrics to dashboard                 | pending | Yes      | 2       | -         |

## Decisions Log

| Decision         | Choice                             | Alternatives                           | Rationale                                               |
| ---------------- | ---------------------------------- | -------------------------------------- | ------------------------------------------------------- |
| Token storage    | Secure storage (Keychain/KeyStore) | Local storage, Session storage         | Security requirement - tokens are sensitive credentials |
| Refresh strategy | Automatic on 401                   | Manual user action, Proactive refresh  | Better UX - transparent to user, no extra UI            |
| Token lifetime   | Access: 1hr, Refresh: 30 days      | Access: 5min/90min, Refresh: 7/90 days | Balance security (short access) and UX (long refresh)   |
| Token algorithm  | RS256 (asymmetric)                 | HS256 (symmetric)                      | Enables key rotation, better for distributed systems    |
| Refresh rotation | Always rotate                      | Rotate on suspicious activity          | OWASP best practice, prevents token replay              |
| Storage location | Database                           | Redis, In-memory                       | Need persistent storage, DB already available           |

## Research Summary

**Market Context**:

- Auth0, Firebase, Okta all use refresh token pattern
- Industry standard: short-lived access + long-lived refresh
- OWASP recommends token rotation on every refresh
- JWT RFC 7519 and OAuth 2.0 RFC 6749 define patterns

**Technical Context**:

- Existing backend uses jsonwebtoken library (supports refresh)
- Mobile SDK has secure storage capabilities
- Backend has session management and database for token storage
- Average API latency: 100ms (refresh won't impact UX significantly)

**Feasibility Assessment**: HIGH

- All dependencies available
- No new infrastructure required
- Clear implementation path
- Low risk of scope creep

## Risks

| Risk                           | Likelihood | Mitigation                                                |
| ------------------------------ | ---------- | --------------------------------------------------------- |
| Token theft (XSS/MITM)         | Medium     | Use secure storage, HTTPS only, rotate on refresh         |
| Refresh loop (invalid token)   | Low        | Add exponential backoff, max 3 retries, fallback to login |
| Clock skew issues              | Low        | Use 5min grace period for exp validation                  |
| DB performance (token lookups) | Low        | Index refresh tokens, implement token cleanup job         |
| Concurrent refresh attempts    | Low        | Use mutex/lock during refresh, queue pending requests     |

## Open Questions

- [ ] What happens to active refresh tokens on password change? (Decision: revoke all)
- [ ] How do we handle token refresh during network outage? (Decision: retry with backoff)
- [ ] Should we notify user on refresh token expiration? (Decision: yes, with "session expired" message)
- [ ] Do we need per-device refresh tokens? (Decision: yes, for "logout all devices" feature)

---

_Generated: 2026-02-09_
_Status: Draft_

関連スキル

• context-compressor - 要件が不明確な場合に段階的に情報を提示します
• plan-generator - PRDの各フェーズを実装タスクに分割します
• research-synthesis - 問題の定義に必要な根拠を集めます

割り当てられたエージェント

このスキルは、次のエージェントによって呼び出されます。

• pm（プロダクトマネージャー） - このスキルの主なユーザー

メモリプロトコル（必須）

開始前： .claude/context/memory/learnings.mdを読みます

次の項目を確認します。

• 以前に作成されたPRD
• このコードベースにおける機能のパターン
• よくある判断とその理由

完了後：

• 新しいPRDのパターン → .claude/context/memory/learnings.md
• 繰り返し発生する判断 → .claude/context/memory/decisions.md
• PRD作成を妨げる問題 → .claude/context/memory/issues.md

中断を前提にしてください。メモリに記録されていなければ、実際には起きていないものとします。