using-user-stories

ユーザーストーリーの活用

ユーザーストーリーを使って、機能の実装を文書化し、追跡します。ストーリーの作成、機能の構築、受け入れ基準の合格判定までのワークフローです。

ユーザーストーリーでは、機能の動作を記述し、実装状況を追跡します。AI エージェントがユーザーストーリーに沿って体系的に作業すると、より良い成果が得られ、作業内容も明確に記録できます。

---

ワークフロー

機能に取り組む際は、次の手順に従います。

1. 作成／更新：構築を始める前に、ユーザーストーリーの機能を作成または変更します
2. 構築とテスト：テストに合格するまで実装します
3. 合格として記録：確認できたら passes: true に設定します

---

ユーザーストーリーを作成するタイミング

次の場合にユーザーストーリーを作成します。

• 新しい機能やフローに着手するとき
• テストによるカバレッジが必要なバグを修正するとき
• デザインや仕様書の要件を実装するとき
• 大規模な機能をテスト可能な単位に分割するとき

---

効果的なステップの書き方

ステップは次のようにします。

• 検証可能：アプリを実行するかテストを実施して確認できる
• 命令形：「移動する」「クリックする」「確認する」のような指示として書く
• 具体的：URL、ボタン名、期待される値を含める

良い例：

{
  "description": "User deletes a chat",
  "steps": [
    "Navigate to /chats",
    "Click the menu button on a chat",
    "Click 'Delete' option",
    "Confirm deletion in dialog",
    "Verify chat is removed from list"
  ],
  "passes": false
}

曖昧なステップは避けます。

{
  "description": "User deletes a chat",
  "steps": ["Delete a chat", "Check it worked"],
  "passes": false
}

---

作業内容の記録

機能を完成させる際は、次の手順に従います。

1. すべてのステップが手動またはテストで動作することを確認します
2. ユーザーストーリーの passes: true を更新します
3. 実装と更新したストーリーの両方をコミットします

これにより、今後のエージェントが参照できる完了作業の記録が作成されます。

---

AI エージェントとの活用

AI エージェントはユーザーストーリーを読み、次のことができます。

• 構築が必要な機能を把握する
• 正確な受け入れ基準を確認する
• 未対応の機能（passes: false）を見つける
• 機能を合格として記録し、進捗を残す

自動化されたエージェントループについては、Ralph Agent Loop レシピを参照してください。

---

ストーリーの検証

検証スクリプトを実行して、すべてのストーリーが有効な形式であることを確認します。

bun run user-stories:verify

次の項目を検証します。

• すべてのファイルが有効な JSON である
• 各機能に必須フィールドがある
• ステップが空でない文字列である
• ファイルごとの合格／不合格件数が表示される