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 個。それぞれに簡潔な理由を添える
• ユーザーストーリー：標準形式（「[ユーザーの種類]として、[メリット]を得るために、[機能]を利用したい」）でペルソナごとに分類する
• 要件：必須（P0）、あると望ましい（P1）、将来の検討事項（P2）に分類し、それぞれに受け入れ基準を設ける
• 成功指標：先行指標（すぐに変化する指標）と遅行指標（時間をかけて変化する指標）を、具体的な目標値とともに示す
• 未解決の質問：未解決の質問に、回答が必要な担当者（エンジニアリング、デザイン、法務、データ）を明記する
• スケジュール上の考慮事項：厳守すべき期限、依存関係、段階的な展開

5. レビューと反復

PRD の作成後：

• 調整が必要なセクションがあるか、ユーザーに尋ねる
• 特定のセクションを詳しく説明することを提案する
• フォローアップ資料（デザインブリーフ、エンジニアリングチケットの内訳、ステークホルダー向け提案資料）の作成を提案する

PRD の構成

問題の説明

• ユーザーの課題を 2〜3 文で説明する
• 誰がどれくらいの頻度でこの課題を経験するか
• 解決しない場合のコスト（ユーザーの苦痛、ビジネスへの影響、競争上のリスク）
• ユーザー調査、サポートデータ、指標、顧客からのフィードバックなどの根拠を示す

目標

• この機能で達成すべき、具体的で測定可能な成果を 3〜5 個示す
• 各目標について、「成功したことをどのように判断するか」に答える
• ユーザー目標（ユーザーが得るもの）とビジネス目標（企業が得るもの）を区別する
• 目標は成果を示すものとし、アウトプットにしない（「オンボーディングウィザードを作成する」ではなく「価値を初めて得るまでの時間を 50％短縮する」）

非目標

• この機能では明確に対応しないことを3～5項目挙げます
• 今回の対象範囲外となる、隣接する機能
• 対象範囲外とする理由（影響が小さい、複雑すぎる、別の取り組みとして扱う、時期尚早など）を、各非目標について簡潔に説明します
• 非目標を定めることで、実装中のスコープクリープを防ぎ、ステークホルダーの期待を調整できます

ユーザーストーリー

標準形式でユーザーストーリーを記述します。「[ユーザーの種類]として、[メリット]のために[機能]を実現したい」

ガイドライン：

• ユーザーの種類は、意味のある程度に具体的にします（単なる「ユーザー」ではなく「エンタープライズ管理者」など）。
• 実現したいことを記述し、方法は記述しません。
• メリットでは「なぜ」を説明し、どのような価値が得られるかを示します。
• エラー状態、空の状態、境界条件などのエッジケースを含めます。
• この機能が複数のペルソナを対象とする場合は、それぞれのユーザーの種類を含めます。
• 優先度順に並べ、最も重要なストーリーを先に記述します。

例：

• 「チーム管理者として、自分のチームメンバーが会社の認証情報でログインできるよう、組織の SSO を設定したい」
• 「チームメンバーとして、別のパスワードを覚えずに済むよう、会社の SSO ログインに自動的にリダイレクトされたい」
• 「チーム管理者として、展開が適切に進んでいることを確認できるよう、SSO 経由でログインしたメンバーを確認したい」

要件

必須（P0）：これらがなければ機能をリリースできません。機能の実用最小限のバージョンを構成します。「これを削った場合でも、機能は中核的な問題を解決できるか」と考えてください。答えが「いいえ」なら、P0 です。

あると望ましい（P1）：体験を大幅に向上させますが、なくても中核的なユースケースは実現できます。多くの場合、リリース後に迅速な追加対応として実施します。

将来の検討事項（P2）：v1 では明確に対象範囲外ですが、将来対応できるように設計しておきます。これらを記録することで、後から対応しにくくなるアーキテクチャ上の判断を誤って行うことを防ぎます。

各要件について：

• 期待される動作を明確かつ曖昧さのない表現で記述します
• 受け入れ基準（以下を参照）を含めます
• 技術上の考慮事項や制約を記載します
• 他のチームやシステムへの依存関係を明示します

未解決の質問

• 実装の前または実装中に回答が必要な質問
• 回答担当者（エンジニアリング、デザイン、法務、データ、ステークホルダー）を各質問に明記します
• ブロッキング質問（着手前に回答が必須）と、非ブロッキング質問（実装中に解決可能）を区別します

スケジュールに関する考慮事項

• 厳守すべき期限（契約上の約束、イベント、コンプライアンス上の日程）
• 他のチームの作業やリリースへの依存関係
• 機能が1回のリリースには大きすぎる場合に、段階的に進める案

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

優れたユーザーストーリーは次のとおりです。

• 独立している：単独で開発・提供できます
• 交渉可能である：詳細について議論でき、ストーリーは契約ではありません
• 価値がある：ユーザーに価値をもたらします（チームだけではありません）
• 見積もり可能である：チームが作業量をおおよそ見積もれます
• 小さい：1回のスプリント／イテレーションで完了できます
• テスト可能である：動作を明確に検証する方法があります

ユーザーストーリーでよくある間違い

• 曖昧すぎる：「ユーザーとして、製品をもっと速くしたい」—具体的に何を速くするのでしょうか？
• 解決策を決めつけている：「ユーザーとして、ドロップダウンメニューがほしい」—UI ウィジェットではなく、ニーズを記述します
• メリットがない：「ユーザーとして、ボタンをクリックしたい」—なぜでしょうか？何を実現するのでしょうか？
• 規模が大きすぎる：「ユーザーとして、チームを管理したい」—具体的な機能に分割します
• 内部向けになっている：「エンジニアリングチームとして、データベースをリファクタリングしたい」—これはユーザーストーリーではなく、タスクです

要件の分類

MoSCoW フレームワーク

• 必須：これらがなければ機能は成り立ちません。交渉の余地はありません。
• 必要：重要ですが、リリースに不可欠ではありません。優先度の高い追加対応の候補です。
• あると望ましい：時間が許せば実施します。削っても提供が遅れることはありません。
• 今回は対象外：明確に対象範囲外です。将来のバージョンで再検討する場合があります。

カテゴリ分けのヒント

• P0 は厳選してください。必須項目を絞るほど、より早くリリースして学べます。
• すべてが P0 なら、P0 はありません。必須項目はすべて問い直してください。「これがなければ本当にリリースしないのか？」
• 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つの仕様に収まらない場合は、フェーズに分けることを提案し、最初のフェーズの仕様を作成してください。
• 成功指標は具体的かつ測定可能なものにしてください。「ユーザーエクスペリエンスを向上させる」のように曖昧なものは避けてください。
• 目標と同じくらい、目標に含まれないことも重要です。実装中のスコープクリープを防ぎます。
• 未解決の質問は、本当に未解決のものにしてください。文脈から答えられる質問は含めないでください。