writing-product-specs

プロダクト仕様書の作成

概要

構築するもの、その理由、成功をどのように判断するかを明確に伝える、包括的なプロダクト仕様書を作成します。ステークホルダーが理解するために必要なすべての情報、つまり問題の背景、対象ユーザー、要件、成功基準、トレードオフを文書化します。機能やプロジェクトの全体像を伝えます。

読者はプロダクトに精通した人やエンジニアであるものの、この特定の機能や問題領域については何も知らないと想定してください。作業の「理由」を理解するための明確な背景情報が必要だと想定してください。

開始時に次のように伝えます：「プロダクト仕様書を作成するために、writing-product-specs スキルを使用しています。」

コンテキスト：明確な要件文書が必要な新機能の設計やプロジェクトの計画時に実行します。

仕様書は spec-<feature-name>-MM-DD-YYYY.md という名前のアーティファクトに保存します（またはユーザーの指定に従います）。

基本原則： プロダクト仕様書は、プロダクトの機能を詳細に記述した文書です。プロダクトの要件を開発チームに伝えるために使用します。

このスキルを使用するタイミング

次の場合にこのスキルを使用します。

• プロダクト仕様書、プロダクトスペック、または PRD（製品要件定義書）の作成を明示的に依頼された場合
• 新機能の設計を依頼され、実装前に要件を文書化する必要がある場合
• プロジェクトを計画し、何を構築するか、その理由を定義する必要がある場合
• プロダクト要件をステークホルダー、エンジニア、デザイナーに伝える必要がある場合
• 機能リクエストを、背景、要件、成功基準を含む詳細な仕様に拡張する必要がある場合
• 実装に進む前に、プロダクト上の決定の「内容」と「理由」を文書化するよう依頼された場合

プロダクト仕様書の作成手順

必要な情報を引き出し、包括的なプロダクト仕様書を作成するには、次の手順に従います。

ステップ 1：依頼された機能またはプロジェクトを理解する

機能またはプロジェクトを理解するために質問します。次の情報を集めます。

• これは何ですか？ どのような機能やプロジェクトを構築しますか？ どのような役割を果たしますか？
• 対象ユーザーは誰ですか？ 誰のためにこの問題を解決しますか？ その人たちの役割、ペルソナ、特性は何ですか？
• どのような問題を抱えていますか？ 対象ユーザーが直面している具体的な課題や悩みは何ですか？ 何が壊れている、または不足していますか？
• この機能／プロジェクトはどのように問題を解決しますか？ 提案する解決策は何ですか？ それは問題にどのように対処しますか？
• どのようなメリットがありますか？ 具体的なメリットは何ですか？ どのような価値を提供しますか？ ユーザーはどのような成果や改善を得られますか？
• 成功したことをどのように判断しますか？ 成功指標、検証基準、または観察可能な成果は何ですか？
• 失敗したことをどのように判断しますか？ 何が失敗を示しますか？ 失敗のパターンや否定的な兆候は何ですか？
• 対象外とするものは何ですか？ 明確に対象外とするものは何ですか？ 関連する機能や能力のうち、含めないものは何ですか？

完全な仕様書を作成するのに十分な情報が得られるまで、質問を続けます。これらの基本的な質問に明確な回答が得られるまで、草案の作成に進まないでください。

ステップ 2：仕様書の草案を作成する

収集した情報をもとに、「プロダクト仕様書のフォーマット」のセクションで説明する文書構成に従って、プロダクト仕様書の草案を作成します。草案全体をユーザーに提示します。

ステップ 3：フィードバックに基づいて反復する

草案を提示した後：

• 編集、明確化、追加事項がないかユーザーに尋ねます
• 仕様書の不足箇所を特定し、補完するための的を絞った質問をします
• フィードバックに基づいて仕様書を修正します
• ユーザーが仕様書の内容が完全かつ正確だと確認するまで、反復を続けます

ステップ 4：最終化して保存する

ユーザーが仕様書の内容で問題ないと確認したら：

• 「プロダクト仕様書のフォーマット」の文書構成に照らして、最終版を確認します
• アーティファクトを spec-<feature-name>-MM-DD-YYYY.md として保存します（またはユーザーの指定に従います）

プロダクト仕様フォーマット

以下は、プロダクト仕様のフォーマットです。各セクションでは、明確で実行可能な指針を記載してください。

[プロジェクト／機能のタイトル]

手順： 構築するものについて、簡潔に（最大1～2文で）説明してください。これは要約であり、プロジェクト全体とそのメリットを数文で説明するものです。読者がタイトルと説明だけで、中心となる価値提案を理解できるようにしてください。

含める内容：

• 機能／プロジェクトの内容が伝わる、明確で説明的なタイトル
• 構築するものを要約した1～2文
• 提供する主なメリットまたは価値

背景

コンテキスト

手順： 問題が存在する背景と、問題の概要を説明してください。この取り組みが重要である理由を示します。現状、市場やユーザーのワークフローで起きていること、そしてこの問題がなぜ発生したのか、あるいは今重要になったのかを説明してください。

含める内容：

• 世界／ワークフロー／システムの現状
• この問題が存在する理由、または重要性が増した理由
• 関連するトレンド、制約、外部要因
• 現状と目指す状態のギャップ

対象ユーザー

手順： この問題を解決する対象者を特定してください。ユーザーペルソナ、役割、またはユーザーの種類を具体的に示します。可能であれば、一般的なユーザーペルソナ（例：ドキュメント作成者、プロダクトエンジニア、DevOps／IT、顧客の顧客／ドキュメントの読者など）に対応付けてください。対象者が複数いる場合は、それぞれを列挙し、各対象者がどのようなメリットを得るかを説明してください。

含める内容：

• 影響を受ける主要なユーザーペルソナまたは役割
• 該当する場合は、二次的な対象者
• ソリューションによって各対象者が得られるメリット
• 関連する具体的なユーザーの特性やニーズ

問題の記述

手順： 解決する具体的な問題を列挙してください。問題ごとに箇条書きにします。簡潔かつ明確に記述してください。背景の説明はすでに行われています。各問題の記述は、明確で具体的かつ実行可能なものにしてください。

含める内容：

• 問題ごとに分けた箇条書き
• 具体的で明確な問題（曖昧な記述は避ける）
• ソリューションによって直接対処できる問題
• ユーザーの課題またはビジネスニーズに焦点を当てる

仮説

手順： これらの問題を解決することで、顧客が目標を達成できると考える理由を説明してください。これは「何をするか」を支える「なぜ」にあたります。問題と提案するソリューションを結び付ける根拠を示します。期待する結果と、それを裏付ける論理を明確にしてください。

含める内容：

• 問題が解決された場合に期待される結果
• 問題とソリューションを結び付ける論理
• このアプローチが効果的である理由
• 前提条件

成功基準

手順： 問題が解決されたと判断する方法を定義してください。成功を示す指標は、測定、テスト、または観察が可能である必要があります。該当する場合は、定量的な指標と定性的な検証手順の両方を含めてください。

含める内容：

• 具体的で測定可能な指標（例：導入率、パフォーマンスの改善、ユーザー満足度スコア）
• QA／検証手順または受け入れ基準
• 成功を示す、観察可能な行動や結果
• 成功の期間やしきい値（該当する場合）

要件

手順： この問題を解決するために構築する必要があるものを列挙してください。機能要件、技術要件、制約を具体的に記述します。必要に応じて、優先度やカテゴリごとに整理してください。各要件は、エンジニアが構築する内容を理解できる程度に明確にしてください。

含める内容：

• 機能要件（システム／機能が実行すべきこと）
• 技術要件（パフォーマンス、スケーラビリティ、互換性に関するニーズ）
• ユーザーエクスペリエンス要件（該当する場合）
• 統合要件または依存関係の要件
• 該当する場合は、優先順位（必須と、あると望ましいもの）

非要件

指示： 対応しないこと、対象範囲外のこと、実施する必要のないことを明確に記載してください。これにより、スコープの拡大を防ぎ、明確な境界を定められます。関連があるように見えても、明示的に対象外とする機能や能力を具体的に示してください。

含める内容：

• 明示的に対象範囲外とする機能や能力
• 解決しない関連課題
• 関連があるように見えても、この仕様には含めない将来の作業
• 構築する必要がないものについての前提

トレードオフと懸念事項

指示： このセクションには、以下のプレースホルダーを斜体で記載するだけにしてください。

特にエンジニアリング面で、このソリューションを実装するためにどのような難しい決断が必要になりますか？この実装を選択したことで、将来どのような問題を解決する必要が生じる可能性がありますか？