Appearance
Usecase Creation Guide
本ガイドは、複数コンポーネントにまたがる機能群やシナリオを束ねる「ユースケース」を <root>/docs/usecases/USECASE-XXX.md 配下に作成する際の記述ルールと標準Markdownテンプレートを定義するものです。
概念定義（ユースケースと実装単位 feature）
ユースケース (
usecase):- ユーザー視点またはシステム視点での目的・ユースケースを表すグループ構造。
- 配置先:
<root>/docs/usecases/USECASE-XXX.md - ID命名規則:
USECASE-XXX（XXXは001から始まる 3桁ゼロ埋め数字。例:USECASE-001.md）。 - 役割: 機能単位 (
feature) や実現条件、シーケンス図等を束ね、仕様・依存関係を永続的に記録・追跡します（※ feature の実装ステータス管理は<root>/docs/backlog/usecase.mdで行います）。
機能単位 (
feature):- 動作する機能の最小単位。
- 命名・ID規則:
F-<no>: <feature-name>（<feature-name>はkebab-case。例:F-1: user-login）。 - 外部参照形式: 外部文書から特定の feature を参照する場合は
<UseCaseID>:<FeatureID>（例:USECASE-001:F-1）と表記します。 - ユースケース内に含まれる縦切りスライスの実体です。
スライス / 実装ロードマップ:
- 実装時の一時的な分割・計画情報。
- ファイル名:
docs/backlog/roadmaps/<feature-name>.md（ 非追跡対象 ） - 参照規則: 実装ロードマップから親ユースケースへの単方向参照のみを行います（ユースケースから非追跡対象のロードマップへの参照は行いません）。
運用手順 & 総合台帳 (index.md) への登録
- ユースケースファイルの起票:
<root>/docs/usecases/USECASE-XXX.md（例:USECASE-001.md）として新規作成します。
- 総合台帳への登録:
- 新規作成時、総合台帳（
docs/usecases/index.md）の一覧表にID|名称|概要を登録・追記します。
- 新規作成時、総合台帳（
- feature ステータス台帳への登録:
- ユースケース起票時、
docs/backlog/usecase.mdに該当ユースケースの節（## USECASE-XXX: <ユースケース名>）、ユースケースステータス（- **ステータス**: DRAFT (YYYY-MM-DD)）、実現条件（- **実現条件**: ...）、および feature 表を作成し、各 feature をDRAFTステータスで登録します。
- ユースケース起票時、
- 実装とステータス更新:
statusの遷移:DRAFT（初期値） →REVIEW:DRAFT→TODO→WIP→REVIEW:WIP→DONEDRAFT: ユースケース・feature 定義中REVIEW:DRAFT: 策定フェーズのレビュー中（review-document実行）TODO: レビュー完了・着手待ちWIP: feature の実装ロードマップ（docs/backlog/roadmaps/<feature-name>.md）が着手・進行中の状態REVIEW:WIP: feature 実装ロードマップ完了後、ユースケース受入レビュー中（review-document実行）DONE: 実装ロードマップが完了し、実現条件を満たした状態
- ステータス遷移に応じて
docs/backlog/usecase.mdの feature 行およびユースケース自体のステータス (Timestamp)を更新します。 - feature の完了によって実現条件を満たした際、ユースケース自体のステータスを
DONEに更新します。 - 実現条件が
ORやXOR等でユースケースがDONEとなった場合、採用・実装されなかった選択 feature はTODOのまま残します（将来の拡張・代替候補として保持）。
セクション記述ルール
1. フロントマター
- 標準項目（
name,description,timestamp,ai）を設定します（※ ユースケースおよび feature の実装進捗ステータスは、フロントマターではなく台帳docs/backlog/usecase.mdで一括管理します）。
2. 概要 (Overview)
- 本ユースケースが提供するユーザー価値またはシステム目的を記述します。
3. 実現条件 (Realization Conditions)
本ユースケースの目的を達成するための条件を記述します。
- 論理式による記述:
AND,OR,XORを使用した論理式で記述します。F-1 AND F-2: F-1 と F-2 の両方の実装が必要F-1 OR F-2: F-1 または F-2 の実装が必要F-1 XOR F-2: F-1 か F-2 のいずれか一方の実装が必要
- 条件付き feature の展開:
- F-2 が条件付き（種類: 条件付き）の場合、
F-1 AND F-2はF-1 AND (IF <F-2条件> THEN F-2 ELSE TRUE)と展開されます。 - 条件付き feature は
ANDのみ指定可能です。
- F-2 が条件付き（種類: 条件付き）の場合、
- 文章による記述:
- 論理式では表現できない複雑な実現条件の場合は、文章で記述します。
4. feature 詳細 (Feature Details)
各 feature は見出し ### F-<no>: <feature-name> として定義し、以下の項目を記述します。
- 概要: 機能の具体的仕様・振る舞いを記述。
- 関連ソフトウェアコンポーネント・仕様書: 関連するコンポーネントおよび仕様書（
<AppID>または<AppID>:<SpecID>形式。例:webui:SPEC-001）。 - 完了条件: 当該 feature が完了したとみなす条件。
- 種類:
必須|選択|条件付きのいずれか。 - 条件: 種類が
条件付きの場合に、適用される条件を記述（必須・選択の場合は不要または「なし」）。 - シーケンス図: Mermaid 書式で処理の流れやコンポーネント間の連携を記述。
Template
以下はユースケース定義書を作成する際の標準Markdownテンプレートです。
markdown
---
name: USECASE-001.md
description: <ユースケースの1行概要>
timestamp: YYYY-MM-DD
ai: ai-coauthored
---
# USECASE-001: <ユースケース名>
## 概要
<ユースケースの目的と概要を記述します。>
## 実現条件
`F-1 AND F-2`
<論理式で表現できない複雑な条件がある場合は文章で記述します。>
## feature 詳細
### F-1: user-login
#### 概要
<ユーザーログイン機能の具体的仕様・振る舞いを記述します。>
#### 関連ソフトウェアコンポーネント・仕様書
- `webui:SPEC-001` (ログイン画面UI)
- `auth-service:SPEC-001` (認証API)
#### 完了条件
- ユーザーが認証情報を入力して正常にログインできること
- 認証失敗時に適切なエラーメッセージが表示されること
#### 種類
必須
#### 条件
なし
#### シーケンス図
```mermaid
sequenceDiagram
autonumber
actor User as ユーザー
participant UI as webui
participant Auth as auth-service
User->>UI: ログイン情報入力 & 送信
UI->>Auth: POST /api/login (credentials)
Auth-->>UI: 200 OK (token)
UI-->>User: ログイン完了画面表示
```
---
### F-2: password-reset
#### 概要
<パスワードリセット機能の具体的仕様・振る舞いを記述します。>
#### 関連ソフトウェアコンポーネント・仕様書
- `webui:SPEC-002` (パスワード再設定画面UI)
- `auth-service:SPEC-002` (トークン検証・パスワード更新API)
#### 完了条件
- パスワード再設定メールが送信され、リンクから新パスワードを設定できること
#### 種類
条件付き
#### 条件
メール配信サービスが利用可能な環境であること
#### シーケンス図
```mermaid
sequenceDiagram
autonumber
actor User as ユーザー
participant UI as webui
participant Auth as auth-service
User->>UI: パスワード再設定要求
UI->>Auth: POST /api/password-reset/request
Auth-->>UI: 200 OK
UI-->>User: 再設定メール送信完了表示
```