# Dev-Lifecycle: 仕様駆動開発ライフサイクル

仕様を起点とし、要件→仕様→実装→テストの全工程を
Doorstopのトレーサビリティで一貫管理するライフサイクル定義。

## 基本原則

**仕様が起点、コードが従属。** コードは仕様を実現する手段であり、
仕様に紐づかないコードは存在意義を説明できない。
同様に、テストのないコードは検証されていない仕様実装であり、
仕様のない要件は実現方法が未定義である。

## ドキュメント階層

```
REQ（要件: What）
└── SPEC（仕様: How）
    ├── IMPL（実装: Build）
    └── TST（テスト: Verify）
```

4つのドキュメントは以下の役割を持つ:

### REQ — 要件（What: 何を実現するか）

ビジネス要件・ユーザーストーリー・機能要件を定義する。
技術的な実現方法には言及しない。

属性:
- `text`: 「〜できること」形式の要件文
- `header`: 要件の短い名称
- `group`: 機能グループ（AUTH, PAY 等）
- `level`: ドキュメント内の階層

例:
```
REQ001 [AUTH] ユーザーはパスワードでシステムにログインできること。
REQ002 [AUTH] ログインに5回失敗したアカウントは30分間ロックされること。
REQ003 [PAY]  ユーザーはクレジットカードで商品を購入できること。
```

### SPEC — 仕様（How: どう実現するか）

REQを実現するための技術仕様を定義する。
APIインターフェース、データモデル、アルゴリズム、制約条件、
非機能要件（性能・セキュリティ等）の具体値を記述する。

属性:
- `text`: 「〜すること」形式の仕様文
- `group`: 機能グループ（REQと同じグループ名を使用）
- `links`: 対応するREQアイテムへのリンク（必須）

例:
```
SPEC001 [AUTH] → REQ001
  パスワードはbcrypt（コスト12）でハッシュ化して保存すること。
SPEC002 [AUTH] → REQ002
  ログイン失敗回数はRedisで管理し、キーのTTLを1800秒に設定すること。
```

### IMPL — 実装（Build: 何を作ったか）

SPECに対応する実装成果物（ソースコード）を追跡する。
1つのIMPLアイテムが1つの実装単位（モジュール、クラス、関数など）に対応する。

属性:
- `text`: 実装の概要説明
- `group`: 機能グループ
- `links`: 対応するSPECアイテムへのリンク（必須）
- `ref`: ソースコードのファイルパス（リポジトリルートからの相対パス）

例:
```
IMPL001 [AUTH] → SPEC001
  ref: src/auth/password.py
  bcryptハッシュ化を実装。PasswordHasherクラスのhash()メソッド。
IMPL002 [AUTH] → SPEC002
  ref: src/auth/login_limiter.py
  Redisベースのログイン試行制限を実装。LoginLimiterクラス。
```

`ref` の粒度ガイドライン:
- ファイル単位が基本: `src/auth/password.py`
- 特定クラス/関数を示す場合: `src/auth/password.py::PasswordHasher`
- 複数ファイルにまたがる場合: IMPLアイテムを分割するか、主要ファイルをrefにして補足をtextに記載

### TST — テスト（Verify: どう検証するか）

SPECに対する検証手順・期待結果を定義する。
テストコードの場所を `ref` で紐づけ、実行と追跡を可能にする。

属性:
- `text`: テスト手順と期待結果の説明
- `group`: 機能グループ
- `links`: 対応するSPECアイテムへのリンク（必須）
- `ref`: テストコードのファイルパス

例:
```
TST001 [AUTH] → SPEC001
  ref: tests/test_auth.py::test_password_hash
  パスワード「test123」をハッシュ化し、bcrypt形式であることを検証する。
TST002 [AUTH] → SPEC002
  ref: tests/test_auth.py::test_login_lockout
  5回連続で誤ったパスワードを送信し、6回目がHTTP 429で拒否されることを検証する。
```

## トレーサビリティの流れ

全アイテムのリンクは **子 → 親** 方向で張る:

```
REQ001 [AUTH] ← SPEC001 [AUTH] ← IMPL001 [AUTH]
                                ← TST001  [AUTH]
```

これにより以下の問いに答えられる:

| 問い | 追跡方向 |
|------|----------|
| この要件はどう実装されている？ | REQ → SPEC → IMPL |
| このコードはなぜ存在する？ | IMPL → SPEC → REQ |
| この仕様はテストされている？ | SPEC → TST |
| このテストは何を検証している？ | TST → SPEC → REQ |
| この要件は検証済みか？ | REQ → SPEC → TST（結果確認） |

## ライフサイクルフェーズ

### Phase 1: 要件定義

```
入力: ユーザーストーリー、ビジネス要件、ステークホルダー要望
成果: REQドキュメント
```

1. 機能グループを定義する（AUTH, PAY, ...）
2. 各グループごとにREQアイテムを作成する
3. 要件テキストを検証可能な形式で記述する
4. REQドキュメント内でレベル構造を整理する

完了基準: 全REQアイテムにテキストとグループが設定されていること。

### Phase 2: 仕様策定

```
入力: REQドキュメント
成果: SPECドキュメント（全SPEC → REQリンク済み）
```

1. 各REQアイテムに対して1つ以上のSPECアイテムを作成する
2. 技術仕様を具体的に記述する（数値、フォーマット、プロトコル等）
3. SPEC → REQ のリンクを張る
4. バリデーションでREQカバレッジ100%を確認する

完了基準: 全REQが少なくとも1つのSPECにカバーされていること。

### Phase 3: テスト設計

```
入力: SPECドキュメント
成果: TSTドキュメント（全TST → SPECリンク済み）
```

1. 各SPECアイテムに対して1つ以上のTSTアイテムを作成する
2. テスト手順と期待結果を記述する
3. TST → SPEC のリンクを張る
4. テストコードのファイルパスを `ref` に設定する（この時点ではスタブでも可）

完了基準: 全SPECが少なくとも1つのTSTにカバーされていること。

### Phase 4: 実装

```
入力: SPECドキュメント
成果: IMPLドキュメント + ソースコード（全IMPL → SPECリンク済み）
```

1. SPECに従ってコードを実装する
2. 各実装単位に対してIMPLアイテムを作成する
3. IMPL → SPEC のリンクを張る
4. `ref` にソースコードのパスを設定する
5. バリデーションでSPECカバレッジ（IMPL側）を確認する

Phase 3とPhase 4は並行して進めてよい。
TDD（テスト駆動開発）を実践する場合は Phase 3 → Phase 4 の順が自然。

完了基準: 全SPECが少なくとも1つのIMPLにカバーされていること。

### Phase 5: 検証

```
入力: 全ドキュメント + ソースコード + テストコード
成果: トレーサビリティレポート + テスト結果
```

静的検証（Doorstop）:
- `doorstop` でツリー全体のバリデーション
- `validate_and_report.py --strict` で全リンクの完全性チェック
- グループ別カバレッジが全て100%であること

動的検証（テスト実行）:
- TSTアイテムの `ref` が指すテストコードを実行する
- テスト結果をTSTアイテムのカスタム属性 `test_status` に記録する（pass/fail/skip）

完了基準: 静的検証エラー0件、テスト全件パス。

### Phase 6: レビュー

```
入力: 全ドキュメント（検証済み）
成果: 全アイテムのreviewed状態がクリア
```

Doorstopの `reviewed` 属性を活用する:
- アイテムの内容が変更されると `reviewed` がリセットされ、suspect（要再確認）状態になる
- レビュー完了後、`doorstop review <UID>` でクリアする
- レビュー漏れは警告として報告するが、リリースをブロックしない（緩めの運用）

レビュー対象:
- 新規・変更されたREQ/SPECアイテム → 仕様レビュー
- 新規・変更されたIMPLアイテム → コードレビュー（通常のPRレビューと統合）
- 新規・変更されたTSTアイテム → テストレビュー

### Phase 7: 変更影響分析（Impact Analysis）

```
入力: 変更されたアイテム（SPEC修正、REQ追加・変更など）
成果: 影響範囲レポート + 対応アクションリスト + suspect解消
```

仕様や要件の変更は、下流のアイテム（実装・テスト）に波及する。
このフェーズでは変更の影響範囲を特定し、必要な修正を追跡する。

`scripts/impact_analysis.py` が3つの方式で変更を検出する:

**方式1: suspect自動検出 (`--detect-suspects`)**

Doorstopの組み込みメカニズムを利用する。各リンクにはリンク時点の
親アイテムのフィンガープリント（SHA256）が記録されており、親アイテムが
変更されるとフィンガープリントが不一致となり、リンクがsuspect状態になる。

```
SPEC001 変更前 → stamp: abc123
  IMPL001 link: SPEC001:abc123  ← 一致 → 正常
  TST001  link: SPEC001:abc123  ← 一致 → 正常

SPEC001 変更後 → stamp: xyz789
  IMPL001 link: SPEC001:abc123  ← 不一致 → ⚠ suspect
  TST001  link: SPEC001:abc123  ← 不一致 → ⚠ suspect
```

**方式2: Git diff検出 (`--from-git`)**

Gitの差分からDoorstopのYAMLファイルの変更を検出する。
PR単位で影響分析を実行する場合に有効。

```bash
# mainブランチとの差分から検出
python impact_analysis.py . --from-git --base main

# 直前のコミットからの差分
python impact_analysis.py . --from-git
```

**方式3: 手動指定 (`--changed UID`)**

変更予定のアイテムを事前に指定し、影響範囲を予測する。
変更前のシミュレーションとして使える。

```bash
python impact_analysis.py . --changed SPEC001 SPEC003
```

**影響範囲のトレース**

変更アイテムを起点に、リンクを双方向にたどる:

```
上流追跡（なぜ変わった？）       下流追跡（何に影響する？）
  REQ001 ← SPEC001 変更 → IMPL001 ⚠ suspect
                          → TST001  ⚠ suspect
```

上流追跡は変更の根本原因（要件変更の影響か、仕様自体の改善か）を把握するため、
下流追跡は修正が必要なコード・テストを特定するために行う。

**suspect解消のワークフロー**

```
1. impact_analysis.py で影響範囲を特定
2. 影響を受けるIMPL/TSTのref先（ソースコード/テストコード）を修正
3. doorstop clear <UID> でsuspectリンクを解消
4. doorstop review <UID> でレビュー済みに更新
5. validate_and_report.py で全体の整合性を再確認
```

このフェーズはPhase 1〜6のどの段階でも発生しうる。
変更が発生したら即座にPhase 7を実行し、影響を把握してから
修正→検証→レビューのサイクルに戻る。

## CI連携の概念

CIパイプラインに以下のチェックを組み込むことを推奨する
（具体的なCI設定はプロジェクトごとに別途定義）:

### PRゲート（推奨チェック）

1. **doorstop validate**: ツリーの構造整合性チェック
2. **traceability check**: 新規/変更されたSPEC/IMPL/TSTに対するリンク漏れ検出
3. **ref check**: IMPL/TSTの `ref` が指すファイルが実在するか検証
4. **impact analysis**: `impact_analysis.py --from-git --base main` で変更影響を表示
5. **test execution**: TSTの `ref` が指すテストを実行

### リリースゲート（推奨チェック）

1. **coverage check**: 全ドキュメントペアのカバレッジ100%
2. **suspect check**: `impact_analysis.py --detect-suspects` でsuspectが0件
3. **review check**: 未レビューアイテムの一覧表示（警告のみ、ブロックしない）
4. **report generation**: トレーサビリティレポートの自動生成・アーカイブ

### チェックの厳密度

| チェック | PRゲート | リリースゲート |
|----------|----------|----------------|
| doorstop validate | ブロック | ブロック |
| リンク漏れ | ブロック | ブロック |
| ref存在チェック | 警告 | ブロック |
| カバレッジ100% | 警告 | ブロック |
| テスト全件パス | ブロック | ブロック |
| suspect 0件 | 警告 | ブロック |
| 未レビューアイテム | 表示のみ | 警告 |

## フェーズ間の成果物と依存関係

```
Phase 1        Phase 2        Phase 3        Phase 4        Phase 5       Phase 6
要件定義  ───→  仕様策定  ──┬→  テスト設計  ──→  検証     ───→  レビュー
  │              │          │                    ↑               │
  REQ            SPEC       └→  実装       ──────┘              reviewed
                  │              │                              クリア
                  │              IMPL
                  │              ref → src/...
                  └── TST
                      ref → tests/...

                        Phase 7: 変更影響分析
                        ────────────────────
                        どのフェーズでも変更が発生したら即座に実行
                        suspect検出 → 影響トレース → 修正 → clear → review
                        → Phase 5（検証）に戻る
```

## ドキュメント間の健全性指標

validate_and_report.py が出力するメトリクス:

| 指標 | 説明 | 目標値 |
|------|------|--------|
| SPEC → REQ カバレッジ | SPECがカバーするREQの割合 | 100% |
| IMPL → SPEC カバレッジ | IMPLがカバーするSPECの割合 | 100% |
| TST → SPEC カバレッジ | TSTがカバーするSPECの割合 | 100% |
| 孤立REQ | SPECからリンクされていないREQ | 0件 |
| 孤立SPEC | IMPL/TSTどちらからもリンクされていないSPEC | 0件 |
| suspectリンク | 親アイテム変更後に未解消のリンク数 | 0件 |
| 未レビューアイテム | reviewed未クリアのアイテム数 | 0件（目標） |
| クロスグループリンク | 異なるグループ間のリンク数 | 少ないほど良い |

これらのメトリクスはグループ別にも集計される。

## エージェント駆動モード

自律型コーディングエージェント（Claude Code等）がこのライフサイクルを
自動実行する場合の運用モデル。

### 役割分担

```
ユーザー（人間）           エージェント
─────────────────         ─────────────────────────────────
「ログイン機能を作って」   → REQ/SPEC策定 → 実装 → テスト
                          → IMPL/TST登録 → リンク → 検証
                          → 結果を簡潔に報告

「ハッシュをbcryptに変えて」→ 影響分析 → SPEC修正 → 実装修正
                          → テスト修正 → suspect解消 → 検証
                          → 影響範囲と結果を報告

「出荷できる？」          → リリースゲート全チェック
                          → 結果を報告
```

### エージェント用ツール

`scripts/doorstop_ops.py` はエージェントが1コマンドでDoorstopを操作するためのツール。
すべてのコマンドはJSON形式で結果を返す。

```bash
# アイテム追加（リンク付き）
python doorstop_ops.py . add -d SPEC -t "仕様文" -g AUTH --links REQ001

# アイテム更新
python doorstop_ops.py . update SPEC001 -t "新しい仕様文"

# suspect解消
python doorstop_ops.py . clear IMPL001 TST001

# 状況確認
python doorstop_ops.py . list -d SPEC -g AUTH
python doorstop_ops.py . groups
python doorstop_ops.py . tree
```

### エージェントの判断フロー

```
ユーザーの発話
  │
  ├─ 新機能 → REQ作成 → SPEC策定 → 実装 → IMPL登録
  │           → テスト → TST登録 → 検証 → 報告
  │
  ├─ 変更   → 影響分析 → SPEC修正 → 実装修正 → IMPL更新
  │           → テスト修正 → TST更新 → clear → 検証 → 報告
  │
  ├─ バグ   → 原因特定（仕様バグ or 実装バグ）
  │           → 仕様バグ: 変更フローへ
  │           → 実装バグ: コード修正 → テスト追加 → 検証 → 報告
  │
  └─ 確認   → レポート生成 → 平易な言葉で報告
```

### ユーザーへの報告規約

エージェントはDoorstopの内部構造をユーザーに見せない。
報告は「何を作った/直した」「どのファイルが変わった」「テストは通ったか」に絞る。

```
✅ [AUTH] ログイン機能を実装しました。
  - src/auth/login.py — ログイン処理
  - tests/test_auth.py — テスト3件（全件パス）
  - トレーサビリティ: 全リンク済み、カバレッジ100%
```

