pm-spec-writing

PM 仕様書の作成

アイデア（曖昧なものが多いです）を、開発者や AI エージェントが実際に実装できる仕様書にします。技術スタックに依存しません。新機能、バグ修正、コンテンツ変更、インフラ作業に対応します。

---

使用する場面

• アイデアを実装可能な機能仕様に落とし込む
• PRD または製品要件書を作成する
• 他の人が対応できるバグ報告を提出する
• プロジェクト開始前にスコープを定める
• 機能リクエストのバックログに優先順位を付ける
• 既存機能の受け入れ基準を作成する
• 大規模な取り組みをリリース可能な単位に分割する

使用しない場面

• 複数の取り組みを対象とした四半期または年間計画（roadmap-planning を使用）
• 既存コードのコードレビューやデバッグ（code-review-web を使用）
• 仕様書がすでにある機能の設計判断（design-standards を使用）
• アイデアを検証するためのユーザー調査（ux-research を使用）

---

必要な入力

• 対象となるアイデア、リクエスト、または問題
• 影響を受ける対象者またはユーザー
• 既存の制約（技術スタック、期限、依存関係など）
• 成功指標（成功したことをどう判断するか）

アイデアが曖昧な場合、ワークフローの最初のステップは明確化です。曖昧なまま仕様書を作成しないでください。

---

フレームワーク：4 つのフェーズ

すべての PM ワークフローは、同じ流れに従います。具体的な成果物が異なっていても、各フェーズは共通です。

フェーズ 1：アイデアを明確にする

仕様書を作成する前に、4 つの質問に答えてください。どれか 1 つでも答えが「わからない」なら、ユーザーに確認してください。

1. これはどのようなユーザーの問題を解決しますか？「何をするか」ではありません。まず問題があり、機能は提案する解決策です。
2. 具体的に誰にメリットがありますか？ 正確に特定してください。「ユーザー」では具体的ではありません。「コンバージョンに至らない初回訪問者」なら具体的です。
3. 成功指標は何ですか？ 成功したことをどう判断しますか？主な指標を 1 つ選んでください。
4. なぜ今ですか？ 今がこれを作るのに適した時期である理由は何ですか？「特に変化はない」なら、今が適切な時期ではない可能性があります。

フェーズ 2：影響度と工数でスコープを定める

候補となるアイデアをすべて、影響度／工数のグリッドに配置します。

HIGH IMPACT / LOW EFFORT       Ship immediately
  Examples: copy fixes, contrast fixes, meta tags,
            broken links, missing alt text, redirects

HIGH IMPACT / HIGH EFFORT      Plan and batch
  Examples: new page type, new feature, schema overhaul,
            major redesign, new integration

LOW IMPACT / LOW EFFORT        Nice-to-have batch
  Examples: tooltip improvements, minor copy polish,
            cosmetic UX touches

LOW IMPACT / HIGH EFFORT       Skip or defer indefinitely
  Examples: rebuilding what already works, exotic
            edge case features, premature optimization

これは完璧なフレームワークではありません。「影響度が低い」ものでも必須の場合があります（コンプライアンス、アクセシビリティ、セキュリティなど）。例外を記録してください。

フェーズ 3：仕様書を作成する

作業の種類に応じて、3 つの形式を使い分けます。

形式 A：機能仕様書（新機能向け）

TITLE: [Specific, action-oriented]

PROBLEM
[1-2 sentences. The user problem and current state.]

USERS
[Who specifically benefits. Be precise about the user segment.]

PROPOSAL
[1 paragraph. The proposed solution. Stay at the conceptual level.]

USER STORIES
- As a [user type], I want to [action], so that [outcome]
- As a [user type], I want to [action], so that [outcome]

ACCEPTANCE CRITERIA
- Given [context], when [action], then [expected outcome]
- Given [context], when [action], then [expected outcome]

OUT OF SCOPE
[What this spec explicitly does NOT cover. Important for scope control.]

DEPENDENCIES
[Other systems, APIs, designs, content needed before this can ship.]

SUCCESS METRIC
[The one primary metric that tells us this worked. With current baseline if known.]

ESTIMATED EFFORT
[Small (hours) / Medium (1-3 days) / Large (1-2 weeks) / XL (sprints)]

PRIORITY
[P0 launch blocker / P1 next sprint / P2 within quarter / P3 backlog]

形式 B：開発ブリーフ（開発者または AI エージェントへの引き継ぎ用）

すぐに着手できる実務的な作業向けです。完全な仕様書より簡潔です。

CONTEXT: [1-2 sentences explaining why this matters]

TASK: [Specific files, exact changes needed]

CONSTRAINTS: [What must NOT change, what to preserve]

VERIFY: [Exact steps to confirm the work is done correctly]

確認セクションは最も省略されやすく、最も重要な項目です。これがないと、「完了」の意味は実装者の解釈次第になります。

形式 C：バグ報告

URL or context: [Where it happens]

Symptom: [What the user sees or experiences]

Expected: [What should happen instead]

Steps to reproduce:
1. [Specific step]
2. [Specific step]
3. [Specific step]

Hypothesis: [Likely root cause if known]

Files to investigate: [Likely files involved if known]

Priority:
  P0 - blocking critical user flow, ship immediately
  P1 - degrades UX significantly, fix this sprint
  P2 - minor issue, fix when convenient
  P3 - nice-to-have improvement

Browser/device: [If reproducibility might be browser-specific]

フェーズ 4：順序を決めてリリースする

順序が決まっていない仕様書は、棚の上でほこりをかぶることになります。

単一の機能の場合：リリース可能な最小単位を特定します。ユーザーに価値を届ける最小のバージョンは何でしょうか？まずそれをリリースし、その後に反復改善します。

バックログの場合：まず依存関係、次に優先順位、最後に影響度／工数の順に並べます。優先順位ラベルよりも順序が重要です。

---

ワークフロー

1. 明確にする。 アイデアが曖昧な場合は、先にフェーズ 1 の 4 つの質問をしてください。
2. スコープを定める。 作業を影響度／工数のグリッドに配置します。
3. 適切な形式を選ぶ。 新機能には機能仕様書、実務的な作業には開発ブリーフ、不具合にはバグ報告を使います。
4. 仕様書を作成する。 テンプレートの形式を使い、すべてのセクションを埋めます。空のセクションがあれば要注意です。
5. 完了の定義を決める。 確認手順は曖昧さのないものにしてください。「テストする」だけでは確認手順になりません。
6. 合意を得る。 着手前に、実装を担当する人と仕様書を確認します。
7. 順序を決める。 リリース可能な最小単位を特定します。

---

失敗パターン

• 問題より先に解決策を説明する仕様書。 必ずユーザーの問題から始めます。解決策はその次です。
• 成功指標のない仕様書。 指標がなければ、機能がうまくいったかどうか判断できません。
• テストできない受け入れ基準。 「ユーザー体験が向上する」はテストできません。「ユーザーが60秒以内にサインアップを完了する」ならテストできます。
• 「何を」ではなく「どのように」を記載した仕様書。 実装の詳細は仕様書ではなく、開発ブリーフに記載します。仕様書に記載するのは、望ましい成果です。
• 「対象範囲外」のセクションがない。 明確な境界がなければ、スコープが拡大していきます。
• 再現手順のないバグ報告。 対応できません。必ず手順を記載します。
• 検証手順が曖昧。 「正しく動作することを確認する」では役に立ちません。観察可能な結果が得られる具体的な操作を記載する必要があります。
• 最小限の出荷可能な増分を検討しない。 2週間の実験で済むはずが、6か月のプロジェクトにつながります。

---

出力形式

作業の種類に応じて、以下の3つの形式のいずれかをMarkdownで出力します。

• 機能仕様書の場合は spec-[feature-name].md
• 開発ブリーフの場合は brief-[task-name].md
• バグ報告の場合は bug-[summary].md

大規模な取り組みでは、関連する仕様書をフォルダーにまとめます。

specs/
  initiative-name/
    spec-feature-1.md
    spec-feature-2.md
    brief-task-1.md
    README.md   (overview and sequencing)

---

必要なデータを入手できない場合

このスキルの出力には、単独では生成できないデータ、測定値、またはツールの結果が必要です。必要な入力、ツール、またはデータソースを利用できない、あるいは検証できない場合、許可される出力は、情報の不足を明記した成果物です。必要だったもの、実際に取得または検証できたもの、出力のどの部分に影響するかを記載します。成果物を完成させるために、必要な数値を捏造、推定、または補間することは決して許可されません。不足を明記すれば、それで完全な回答になります。

---

参考ファイル

• references/feature-spec-template.md - 機能仕様書の完全なテンプレート。
• references/dev-brief-template.md - 実務的な作業向けの簡潔な開発ブリーフのテンプレート。
• references/prioritization-frameworks.md - インパクト／労力以外の優先順位付け手法：RICE、加重スコアリング、MoSCoW。