Write Spec

未知のプレースホルダーが表示される場合や、どのツールが接続されているかを確認する必要がある場合は、CONNECTORS.md を参照してください。

機能仕様書または製品要件書 (PRD) を作成します。

使用方法

/write-spec $ARGUMENTS

ワークフロー

1. 機能を理解する

ユーザーに何を仕様化したいのか尋ねます。以下のいずれかを受け入れます：

• 機能名 (「SSO サポート」)
• 問題ステートメント (「エンタープライズ顧客が中央集約認証を継続的に要求している」)
• ユーザーリクエスト (「ユーザーがデータを CSV としてエクスポートしたい」)
• 曖昧なアイデア (「オンボーディングのドロップオフについて何か対策を講じるべき」)

2. コンテキストを収集

以下の情報をユーザーに尋ねます。会話的に進めてください — 質問をまとめて出さないでください。最も重要な質問から始め、ギャップを埋めていきます：

• ユーザーの問題: これは何の問題を解決していますか？誰がそれを経験していますか？
• ターゲットユーザー: このユーザーセグメントのどれがこれを利用しますか？
• 成功指標: これが機能したことをどうやって知りますか？
• 制約: 技術的制約、タイムライン、規制要件、依存関係
• 先行事例: これは以前試みられていますか？既存のソリューションはありますか？

3. 接続ツールからコンテキストを取得

~~project tracker が接続されている場合：

• 関連するチケット、エピック、または機能を検索
• 既存の要件またはアクセプタンス基準を取得
• 他の作業項目の依存関係を特定

~~knowledge base が接続されている場合：

• 関連する調査ドキュメント、以前の仕様、設計ドキュメントを検索
• 関連するユーザー調査の成果を取得
• 関連する会議ノートまたは決定記録を検索

~~design が接続されている場合：

• 関連するモックアップ、ワイヤーフレーム、または設計の探索を取得
• 機能に関連する設計システムコンポーネントを検索

これらのツールが接続されていない場合、ユーザーが提供する情報から完全に作成します。ユーザーにツールを接続するよう尋ねないでください — 利用可能な情報で進めてください。

4. PRD を生成

以下のセクションを持つ構造化 PRD を作成します。各セクションに含めるべき内容の詳細は、以下の PRD 構成 を参照してください。

• 問題ステートメント: ユーザーの問題、誰が影響を受けるか、解決しない場合の影響 (2～3 文)
• ゴール: ユーザーまたはビジネス指標に結びついた 3～5 個の具体的で測定可能な成果
• ノンゴール: 明示的にスコープ外である 3～5 個の項目と、各項目の簡潔な根拠
• ユーザーストーリー: 標準的な形式 (「[ユーザータイプ] として、[機能] が必要です。[利益] を得られるように」)、ペルソナごとにグループ化
• 要件: Must-Have (P0)、Nice-to-Have (P1)、Future Considerations (P2) に分類し、各々にアクセプタンス基準を含める
• 成功指標: リーディング指標 (素早く変化) とラギング指標 (時間をかけて変化)、具体的なターゲット付き
• 未解決の質問: 未解決の質問に回答する必要のある人 (エンジニアリング、デザイン、法務、データ) でタグ付け
• タイムラインの考慮事項: 固定期限、依存関係、フェーズ分け

5. レビューと反復

PRD を生成した後：

• セクションの調整が必要かユーザーに尋ねます
• 特定のセクションの詳細化を提案
• フォローアップ資料 (設計ブリーフ、エンジニアリングチケット分解、ステークホルダーピッチ) の作成を提案

PRD 構成

問題ステートメント

• ユーザーの問題を 2～3 文で説明
• この問題を経験する人とその頻度
• これを解決しない場合のコスト (ユーザーの痛み、ビジネス影響、競争リスク)
• 証拠に基づいて記載: ユーザー調査、サポートデータ、メトリクス、顧客フィードバック

ゴール

• この機能が達成すべき 3～5 個の具体的で測定可能な成果
• 各ゴールは以下に答えるべき: 「成功したことをどうやって知りますか？」
• ユーザーゴール (ユーザーが得るもの) とビジネスゴール (企業が得るもの) を区別
• ゴールは成果であるべき、アウトプットではない (「オンボーディングウィザードを構築」ではなく「初回の価値創出までの時間を 50% 削減」)

ノンゴール

• この機能が明確に実施しないこと 3～5 個
• このバージョンでスコープ外である隣接機能
• 各ノンゴールについて、スコープ外である理由を簡潔に説明 (十分な影響がない、複雑すぎる、別の施策、時期尚早)
• ノンゴールは実装時のスコープクリープを防ぎ、ステークホルダーの期待を設定します

ユーザーストーリー

標準的な形式でユーザーストーリーを記述：「[ユーザータイプ] として、[機能] が必要です。[利益] を得られるように」

ガイドライン：

• ユーザータイプは意味のある程度に具体的に (「ユーザー」ではなく「エンタープライズ管理者」)
• 機能は何をしたいかを説明し、どうするかではない
• 利益は「なぜ」を説明 — これはどの程度の価値を提供しますか
• エッジケースを含める: エラー状態、空状態、境界条件
• 機能が複数のペルソナに役立つ場合は異なるユーザータイプを含める
• 優先度順に並べる — 最も重要なストーリーから

例：

• 「エンタープライズ管理者として、自分の組織に SSO を設定したいです。チームメンバーが企業の認証情報でログインできるように」
• 「チームメンバーとして、自分の企業の SSO ログインに自動的にリダイレクトされたいです。別のパスワードを覚える必要がないように」
• 「チームの管理者として、どのメンバーが SSO 経由でログインしたかを確認したいです。ロールアウトが機能していることを検証できるように」

要件

Must-Have (P0): 機能はこれなしではリリースできません。これは機能の最小限のバージョンを表します。質問: 「これを削除したら、機能は依然としてコア問題を解決していますか？」 いいえなら、P0 です。

Nice-to-Have (P1): ユーザー体験を大幅に改善しますが、コアユースケースはこれなしで機能します。これらはしばしばローンチ後の高速フォローアップになります。

Future Considerations (P2): v1 では明確にスコープ外ですが、後でこれらをサポートする方法で設計したいです。これらを文書化することで、後でこれらを困難にする偶発的な建築上の決定を防ぎます。

各要件について：

• 期待される動作の明確で曖昧でない説明を作成
• アクセプタンス基準を含める (下記を参照)
• 技術的な考慮事項または制約を記載
• 他のチームまたはシステムへの依存関係にフラグを立てる

未解決の質問

• 実装前または実装中に答える必要がある質問
• 各々に回答者でタグ付け (エンジニアリング、デザイン、法務、データ、ステークホルダー)
• ブロッキングの質問 (開始前に回答が必要) と非ブロッキングの質問 (実装中に解決可能) を区別

タイムラインの考慮事項

• 固定期限 (契約上のコミットメント、イベント、コンプライアンス日)
• 他のチームの作業またはリリースの依存関係
• 機能が 1 回のリリースに対して大きすぎる場合の推奨されるフェーズ分け

ユーザーストーリーの作成

優れたユーザーストーリーは以下の通り：

• 独立している: 独立して開発・デリバリーできる
• 交渉可能: 詳細について議論でき、ストーリーは契約ではない
• 価値がある: ユーザーに価値を提供 (チームだけではない)
• 見積もり可能: チームが大まかに努力を推定できる
• 小さい: 1 スプリント/イテレーション内で完了できる
• テスト可能: それが機能しているかを検証する明確な方法がある

ユーザーストーリーの一般的な間違い

• 曖昧: 「ユーザーとして、製品がもっと速くなってほしい」 — 何が具体的により速くなるべきですか？
• ソリューション規定的: 「ユーザーとして、ドロップダウンメニューが必要」 — UI ウィジェットではなく、ニーズを説明
• 利益なし: 「ユーザーとして、ボタンをクリックしたい」 — なぜですか？これは何を達成しますか？
• 大きすぎる: 「ユーザーとして、チームを管理したい」 — これを具体的な機能に分割
• 内部志向: 「エンジニアリングチームとして、データベースをリファクタリングしたい」 — これはタスク、ユーザーストーリーではない

要件の分類

MoSCoW フレームワーク

• Must have: これらがなければ、機能は実行可能ではありません。交渉不可能。
• Should have: 重要だが、ローンチに対して重大ではありません。高優先度の高速フォローアップ。
• Could have: 時間が許せば望ましい。削除されても配信は遅延しません。
• Won't have (this time): 明確にスコープ外。将来のバージョンで再検討する可能性があります。

分類のヒント

• P0 について容赦ない。Must-Have リストが厳しいほど、より速く出荷して学習できます。
• すべてが P0 なら、何も P0 ではありません。すべての Must-Have に挑戦: 「これなしで本当にリリースしないですか？」
• P1 は不完全なウィッシュリストではなく、すぐに構築することに自信のあるもの。
• P2 は建築上の保険 — 今は構築していませんが、設計上の決定を導きます。

成功指標の定義

リーディング指標

ローンチ後に素早く変化するメトリクス (日から週)：

• 採用率: 適格ユーザーの何％が機能を試しているか
• アクティベーション率: ユーザーの何％がコアアクションを完了しているか
• タスク完了率: ユーザーの何％が目標を正常に達成しているか
• 完了時間: コアワークフローにかかる時間
• エラー率: ユーザーがエラーまたはデッドエンドに遭遇する頻度
• 機能使用頻度: ユーザーが機能を使用するために戻ってくる頻度

ラギング指標

開発に時間がかかるメトリクス (週から月)：

• リテンション影響: この機能はユーザーリテンションを改善しますか？
• 収益影響: これはアップグレード、拡張、または新しい収益を推進しますか？
• NPS / 満足度の変化: これはユーザーが製品についてどう感じるかを改善しますか？
• サポートチケット削減: これはサポート負荷を削減しますか？
• 競争的勝利率: これはより多くの取引に勝つのに役立ちますか？

ターゲットの設定

• ターゲットは具体的に: 「高い採用」ではなく「30 日以内に 50% の採用」
• ターゲットは比較可能な機能、業界ベンチマーク、または明示的な仮説に基づく
• 「成功」閾値とストレッチ目標を設定
• 測定方法を定義: どのツール、どのクエリ、どの時間窓
• 評価時期を指定: ローンチ後 1 週間、1 ヶ月、1 四半期

アクセプタンス基準

Given/When/Then 形式またはチェックリストでアクセプタンス基準を記述：

Given/When/Then：

• Given [前提条件またはコンテキスト]
• When [ユーザーが実行するアクション]
• Then [期待される結果]

例：

• Given 管理者が自分の組織に SSO を設定している
• When チームメンバーがログインページにアクセスする
• Then 組織の SSO プロバイダーに自動的にリダイレクトされる

チェックリスト形式：

• 管理者は組織設定で SSO プロバイダー URL を入力できる
• チームメンバーはログインページで「SSO でログイン」ボタンを表示
• SSO ログインが存在しない場合は新しいアカウントを作成
• SSO ログインはメールが一致する場合、既存アカウントにリンク
• SSO ログイン失敗は明確なエラーメッセージを表示

アクセプタンス基準のヒント

• ハッピーパス、エラーケース、エッジケースをカバー
• 実装ではなく期待される動作について具体的に
• 何が起こるべきではないか (ネガティブテストケース) を含める
• 各基準は独立してテスト可能であるべき
• 曖昧な単語を避ける: 「速い」、「ユーザーフレンドリー」、「直感的」 — これらが具体的に何を意味するかを定義

スコープ管理

スコープクリープの認識

スコープクリープは以下の場合に起こります：

• 仕様が承認された後も要件が追加され続ける
• 「小さな」追加が重大な大規模プロジェクトに累積
• チームがユーザーが求めていない機能を構築 (「ついでだから」)
• リリース日が明示的な再スコーピングなしに移動し続ける
• ステークホルダーが何も削除せずに要件を追加

スコープクリープの防止

• すべての仕様に明示的なノンゴールを記述
• スコープの追加は、スコープの削除またはタイムライン拡張を伴う必要
• 仕様で「v1」と「v2」を明確に分離
• 元の問題ステートメントに対して仕様をレビュー — すべてがそれに役立ちますか？
• 調査を時間制限: 「2 日以内に X を理解できなければ、これを削除」
• スコープ外の良いアイデアの「駐車場」を作成

出力形式

明確なヘッダーを持つ Markdown を使用。ドキュメントをスキャン可能に保つ — 忙しいステークホルダーはヘッダーと太字テキストだけを読んで要点を把握できるべき。

ヒント

• スコープについて意見を述べる。拡大して曖昧な仕様より、厳密で明確に定義された仕様の方が良い。
• ユーザーのアイデアが 1 つの仕様に対して大きすぎる場合は、フェーズに分割し、最初のフェーズを仕様化することを提案。
• 成功指標は具体的で測定可能であるべき、曖昧ではない (「ユーザー体験を改善」)。
• ノンゴールはゴールと同じくらい重要。実装中のスコープクリープを防ぎます。
• 未解決の質問は真に未解決であるべき — コンテキストから回答できる質問を含めないでください。