product-specs-writer

プロダクト仕様書の作成者

戦略的な PRD から、エンジニアリングチームが実際に実装できる仕様書まで、包括的なプロダクトドキュメントの専門知識を提供します。

基本理念

優れたプロダクト仕様書は、ビジョンと実行のギャップを埋めます。官僚的な書類ではなく、チームの足並みをそろえ、コストのかかる誤解を防ぐためのコミュニケーションツールです。

優れたプロダクト仕様書の要件は次のとおりです。

1. 目的から始める — 要件の前に背景を示す
2. テスト可能である — すべての要件に明確な受け入れ基準がある
3. 疑問を先回りして解消する — エッジケース、エラー、制約をあらかじめ文書化する
4. プロダクトとともに進化する — 静的な成果物ではなく、生きたドキュメントにする
5. 読み手を尊重する — エンジニア、デザイナー、ステークホルダーの誰もが理解できる

このスキルの仕組み

呼び出されたら、rules/ にあるガイドラインを適用します。ガイドラインは次のように分類されています。

• prd-* — プロダクト要件定義書、ビジョン、スコープ
• stories-* — ユーザーストーリー、ペルソナ、ジョブ理論
• criteria-* — 受け入れ基準、完了の定義
• technical-* — 技術仕様、アーキテクチャ上の決定
• api-* — API 仕様、契約、バージョニング
• edge-* — エッジケース、エラー処理、障害モード
• design-* — デザインの引き継ぎ、コンポーネント仕様、インタラクション
• rollout-* — フィーチャーフラグ、ロールアウト計画、実験
• metrics-* — 成功指標、KPI、測定計画
• maintenance-* — ドキュメントのライフサイクル、バージョニング、非推奨化

主なフレームワーク

仕様書の階層

┌─────────────────────────────────────────┐
│              VISION                     │  ← Why are we building this?
│         (Problem & Opportunity)         │
├─────────────────────────────────────────┤
│               PRD                       │  ← What are we building?
│      (Requirements & Constraints)       │
├─────────────────────────────────────────┤
│          USER STORIES                   │  ← Who benefits and how?
│       (Personas & Journeys)             │
├─────────────────────────────────────────┤
│      ACCEPTANCE CRITERIA                │  ← How do we know it's done?
│      (Testable Conditions)              │
├─────────────────────────────────────────┤
│      TECHNICAL SPECS                    │  ← How do we build it?
│   (Architecture & Implementation)       │
└─────────────────────────────────────────┘

対象読者別のドキュメント種別

ドキュメント	主な対象読者	目的	更新頻度
PRD	リーダーシップ、PM、デザイン	何をするか、なぜするかの認識を合わせる	マイルストーンごと
ユーザーストーリー	エンジニアリング、QA	スコープと価値を定義する	スプリントごと
受け入れ基準	QA、エンジニアリング	完了の定義	ストーリーごと
技術仕様書	エンジニアリング	方法を定義する	機能ごと
API 仕様書	フロントエンド、外部開発者	契約を定義する	バージョンごと
デザイン引き継ぎ資料	エンジニアリング	UI/UX を定義する	コンポーネントごと
ロールアウト計画	エンジニアリング、運用	デプロイを定義する	リリースごと
成功指標	リーダーシップ、データ	成功を定義する	四半期ごと

INVEST 基準（ユーザーストーリー）

基準	問い	例
Independent（独立している）	単独で実装できますか？	未完了のストーリーへの依存がない
Negotiable（交渉可能である）	スコープに柔軟性がありますか？	詳細をエンジニアリングと調整できる
Valuable（価値がある）	ユーザーにメリットがありますか？	明確な価値提案が示されている
Estimable（見積もり可能である）	規模を見積もれますか？	工数を見積もるのに十分な詳細がある
Small（小さい）	1 スプリントに収まりますか？	1〜5 日で完了できる
Testable（テスト可能である）	検証できますか？	明確な受け入れ基準がある

仕様書の完全性チェックリスト

PRD Completeness:
├── Problem Statement         □ Clearly defined user pain
├── Success Metrics          □ Measurable outcomes defined
├── User Stories             □ All personas covered
├── Scope                    □ In-scope and out-of-scope clear
├── Constraints              □ Technical and business limits stated
├── Dependencies             □ External dependencies identified
├── Risks                    □ Known risks and mitigations
├── Timeline                 □ Milestones and deadlines set
└── Open Questions           □ Unknowns explicitly listed

Technical Spec Completeness:
├── Architecture             □ System design documented
├── Data Model               □ Schema and relationships defined
├── API Contracts            □ Endpoints and payloads specified
├── Edge Cases               □ Failure modes documented
├── Security                 □ Auth, encryption, compliance covered
├── Performance              □ SLAs and benchmarks defined
├── Monitoring               □ Observability strategy clear
└── Rollback Plan            □ Recovery procedures documented

エラー処理の分類

エラー種別	例	必要なドキュメント
検証	メールアドレスの形式が無効	エラーメッセージ、フィールドの強調表示
認可	ユーザーに権限がない	エラー状態、エスカレーション経路
リソース	項目が見つからない	空の状態、復旧アクション
システム	データベースのタイムアウト	再試行戦略、ユーザーへのフィードバック
ビジネスロジック	残高不足	エラーの説明、次の手順
外部	サードパーティ API が停止	フォールバック動作、縮退モード

仕様書テンプレート

最小限の PRD 構成

# Feature: [Name]

## Problem
What user problem are we solving?

## Solution
High-level approach (1-2 paragraphs)

## Success Metrics
- Primary: [Metric] from X to Y
- Secondary: [Metric] from X to Y

## User Stories
- As a [user], I want [goal] so that [benefit]

## Scope
**In scope:** [List]
**Out of scope:** [List]

## Open Questions
- [ ] Question 1
- [ ] Question 2

ユーザーストーリーテンプレート

**As a** [persona/user type]
**I want** [capability/action]
**So that** [benefit/value]

**Acceptance Criteria:**
- Given [context], when [action], then [result]
- Given [context], when [action], then [result]

**Edge Cases:**
- What if [edge case]? Then [behavior]

**Out of Scope:**
- [Explicit exclusion]

アンチパターン

• 委員会による仕様策定 — 過度な共同作業により、曖昧なドキュメントが生まれます
• 早すぎる最適化 — 実装の詳細を早い段階で指定します
• 理由の欠落 — 意思決定の背景がない要件です
• あれもこれも盛り込むスコープ — 1回のリリースですべてを解決しようとします
• 一方通行のドキュメント — 学びが得られても更新されない仕様書です
• 前提の見落とし — 暗黙の前提を文書化しません
• デザイナーとエンジニアの伝言ゲーム — 直接のコミュニケーションがなく、ドキュメントだけに頼ります
• 見せかけの成功 — 意味があるからではなく、測定しやすいから指標を選びます
• 契約としての仕様書 — 仕様書を変更できない法的文書として扱います
• ドキュメント負債 — 古くなった仕様書は、仕様書がない状態よりも悪いです