write-user-story

ユーザーストーリーを作成する

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

すべてのストーリーには、順番に3つの中核セクションがあります。目的／概要、要件／スコープ、受け入れ基準です。補足セクションは、テンプレートではなく実際の成果物に基づいて選んでください。依頼と利用可能なコンテキストから作業の種類を判断し、未解決の区別によってストーリーが大きく変わる場合に限り、焦点を絞った質問をしてください。

目的／概要では、成果とその価値を示します。要件／スコープには、機能、契約、成果物、拘束力のある制約を記載します。受け入れ基準には、完了を確認できる、最小限かつ十分な個別条件を記載します。技術的なイネーブラーや調査／ポリシー関連の作業に、エンドユーザーのペルソナを無理に設定する必要はありません。

テンプレート

補足セクションを加える必要がなければ、このひな形がストーリーの全体です。

## Purpose/Overview

[Outcome, value, and relevant context.]

## Requirements/Scope

1. [Required capability, contract, or deliverable, including binding constraints.]

## Acceptance Criteria

[Distinct verifiable completion conditions.
Use Given-When-Then for behavior or a concise checklist for contracts/deliverables.]

受け入れ基準

観測可能な動作には Given-When-Then を使い、技術的な契約や意思決定の成果物をより明確に表現できる場合は、簡潔で検証可能なチェックリストを使います。各基準では、合意したスコープの個別の完了条件を扱います。重要なエラーや境界の動作を網羅しますが、すべての設定項目を個別のシナリオに分ける必要はありません。基準の目標数はありません。簡潔にするために重要な条件を省いたり、受け入れ基準をテスト計画にしたりしないでください。各 Given／When／Then／And は、それぞれ独立した箇条書き行（- Given ...、- When ...、- Then ...）として記載してください。1つの箇条書きの下に継続行としてインデントしてはいけません。標準的な Markdown では、改行を含む継続行が1つの連続した行として表示され、意図した手順形式ではなく「Given abc When xyz Then 123」のように表示されるためです。

作業に適した検証

作業	必須の対応
ユーザー向け／実行時の変更	受け入れ基準だけでは不十分な場合は、Testing Guidance を追加します。実際の UI ワークフローでは、短い手順と期待される結果を記載した Manual Testing が適切です。
バックエンド／API／ライブラリの変更	有用であれば、契約チェック、ローカルハーネス、スタブ、または制御された失敗条件などの Controlled Verification を追加します。テストを記述せずに、自動検証のレベルを示してもかまいません。共有環境や本番環境のデプロイを壊したり、実際の障害を待ったりすることを決して求めないでください。
調査／ポリシー／意思決定のみの作業	実行時の Testing Guidance は不要です。要件と受け入れ基準を通じて、意思決定に関する成果物、トレードオフ、推奨事項、制約、合意したレビューを検証します。Testing Guidance: N/A は記載しないでください。

複数の作業が混在する場合は、実際に依頼された各部分に適した方法で検証します。「ポリシー」という語があるだけで、実際に依頼された実行時の変更に対するテストが不要になるわけではありません。

テストコード、モック設定、フィクスチャスクリプト、実装計画レベルのテストケースはストーリーに含めないでください。これにより詳細を制限しますが、自動検証や契約検証への言及は禁止されません。

条件付きセクション

条件に該当する場合に限り、セクションを追加してください。

• スコープ外 — この依頼に対するもっともらしい別の解釈を明確に除外する必要がある場合、またはユーザーが境界を明示した場合に限ります。隣接するトピック、将来の拡張、無関係な機能は、除外事項を追加する理由にはなりません。
• 非機能要件 — セキュリティ、互換性、並行性、整合性、パフォーマンスに関する、具体的で重要な制約を記載します。テンプレートを埋めるための一般的な要望は記載しません。
• 補足事項 — 拘束力のない、関連するコンテキストのみを記載します。正確性や受け入れに影響するコミットメントは要件に記載し、検証可能な場合は受け入れ基準にも記載します。補足事項だけに記載してはいけません。
• 技術的アプローチ — 必要に応じて、高レベルのコンテキストを記載します。実装方法を作り上げたり、技術的であることを理由に合意済みの技術的制約を削除したりしないでください。
• 関連リンク — 残すリンクはすべて、依存関係、以前の動作、親スコープ、仕様、根拠のいずれかとして明確な役割を持つものにしてください。近接する Jira キーをすべて列挙したり、関係性を作り上げたりしないでください。

作成ガイドライン

ペルソナ形式（ユーザーの役割がある場合）

As a [user persona/role]
I want [goal/desire]
So that [benefit/value]

実際のユーザーの役割が関係する場合に使用します。技術的なイネーブラーや意思決定のチケットでは、ペルソナを作り出すのではなく、成果とその価値を直接記述してください。

INVEST の原則

• Independent — 個別に提供できる
• Negotiable — 詳細を調整できる
• Valuable — 明確な価値をもたらす
• Estimable — チームが作業量を見積もれる
• Small — 1 スプリント以内に完了できる
• Testable — 明確な検証基準がある

ベストプラクティス

すること ✓

1. 受益者が誰であっても、価値と成果を説明する
2. 受け入れ基準を具体的かつ検証可能にする
3. 重大なエラーのシナリオと境界条件を網羅する
4. 拘束力のある制約は「要件」に記載する
5. ドメイン用語を一貫して使用する
6. リンクされた各チケットが何に寄与するかを説明する

しないこと ✗

1. 技術的な作業や意思決定の作業で、エンドユーザーのペルソナを作り出さない
2. 曖昧な記述を避ける。「パフォーマンスを向上させる」には指標が必要です
3. 受け入れ基準を省略しない
4. 成果物に不要なセクションを追加しない
5. これまでスコープ外だった隣接トピックについて、「スコープ外」を追加しない
6. テストコード、フィクスチャ、詳細なテスト設定をストーリーに記載しない
7. 実装を過度に指定しない。「どのように実現するか」は開発者に委ねる
8. 拘束力のある制約を「追加メモ」に残さない

クイックリファレンスチェックリスト

• 目的で価値と背景が明確に説明されている
• 選択したセクションが実際の成果物に合っている
• 要件が具体的で、拘束力のある制約がすべて記載されている
• 受け入れ基準がそれぞれ独立して検証可能で、結果の種類に合っている
• 重大なエラーと境界条件が網羅されている
• 検証方法が作業の種類に適しているか、意思決定の作業であれば適切に省略されている
• 含まれる各任意セクションが実質的な役割を果たしている
• リンクされた各チケットの関係が説明されている
• ストーリーの規模が 1 スプリントに収まっている
• 技術的なアプローチは必要な場合にのみ概要を示し、過度に詳細化していない
• 非機能要件は重要な場合にのみ含まれている

任意のセクションが欠けていても、不備ではありません。

各セクションの詳細なガイダンスについては、references/section-details.md を参照してください。 よくある落とし穴と修正前後の例については、references/pitfalls.md を参照してください。 ストーリーの完全な例については、references/example.md を参照してください。 JIRA マークアップの変換については、references/jira.md を参照してください。