# スケーリング戦略: プロジェクト規模別の導入・運用ガイド

doorstop-spec-driven スキルをプロジェクト規模に応じてスケールさせるための
分析と戦略を定義する。

## 規模の定義

| 区分 | コード行数 | アイテム数目安 | プロファイル |
|------|-----------|---------------|-------------|
| 小規模 | ~1万行 | ~100 | lite |
| 中規模 | 1万~10万行 | 100~1,000 | standard |
| 大規模 | 10万~100万行 | 1,000~10,000 | full |
| 超大規模 | 100万行~ | 10,000~ | full + 分割戦略 |

参考: beautyspot は ~5,700行 / 110アイテム（standard プロファイル）。

---

## フェーズ1: 既存プロジェクトへの初期導入の壁

### 壁1: 初期ドキュメント化の工数（全規模共通、規模に比例して深刻化）

**問題**: 既存コードからREQ/SPEC/IMPL/TSTを遡及的に書き起こす作業量が、
プロジェクト規模に比例する。1万行なら数時間で済むが、10万行では数日、
100万行では数週間～数ヶ月の作業になりうる。

**対策: 段階的導入（Incremental Adoption）**

[F]フローは「一度にすべて網羅しなくてよい」と明記しているが、
規模が大きくなるほどこの原則が重要になる。

```
Phase 0: ツール導入のみ（init_project.py）— 30分
Phase 1: 核心モジュールのみ文書化（全体の10-20%）— 数時間
Phase 2: 新規変更から通常フロー適用 — 即時
Phase 3: 残りを変更のたびに遡及文書化 — 漸進的
```

**規模別の Phase 1 スコープ目安**:

| 規模 | Phase 1 の対象 | 目安工数 |
|------|---------------|---------|
| 小規模 | 全機能（全量一括でも可能） | 2-4時間 |
| 中規模 | 主要サブシステム2-3個 | 1-2日 |
| 大規模 | 最も変更頻度の高いモジュール群 | 3-5日 |
| 超大規模 | 1チーム/1サブシステムでパイロット | 1-2週間 |

### 壁2: コードと仕様の粒度マッピング（中規模以上）

**問題**: 既存コードのモジュール境界と、仕様アイテムの粒度が一致しない。
1つのクラスが複数の要件を横断していたり、1つの要件が多数のファイルに
散在していることがある。

**対策**:

- **groups属性**を活用し、機能横断的な関係を表現する。
  1つのIMPLが複数のgroupsに属することで、複数の要件領域との関連を示せる
- **references は最大2-3ファイル**のルールを厳守する。
  「このIMPLはこのファイル群」という明確な対応を維持する
- コードのリファクタリングが先に必要な場合は、それを認識した上で
  現状のまま文書化する（理想ではなく実態を記述）

### 壁3: チームの理解と合意（中規模以上）

**問題**: 仕様駆動の価値がチーム全体に浸透するまでに時間がかかる。
エージェント駆動であっても、人間のレビュープロセスとの統合が必要。

**対策**:

- パイロットチーム/パイロットモジュールで先行導入し、成功事例を作る
- ダッシュボード（`serve_app.py`）で可視化し、トレーサビリティの価値を体感させる
- PRゲートは最初は警告のみ（ブロックしない）で始め、段階的に厳格化する

---

## フェーズ2: 導入後の運用上の壁

### 壁4: エージェントのコンテキストウィンドウ制約（大規模以上）

**問題**: doorstop-spec-driven スキル自体（SKILL.md + references）が
エージェントのコンテキストウィンドウの一定割合を消費する。
アイテム数が1,000を超えると、`trace_query.py status` や
`doorstop_ops.py list` の出力も膨大になり、エージェントが
全体像を把握しきれなくなる。

**現状の緩和策**:

- `--group GROUP` フィルタで関心領域を絞り込む
- `trace_query.py chain <UID>` で特定アイテムの周辺だけを探索する
- `trace_query.py chain --file <path>` でコードから逆引きする
- `impact_analysis.py --from-git` でgit差分起点の分析に限定する

**スケールのための追加施策（未実装）**:

| 施策 | 効果 | 実装難度 |
|------|------|---------|
| `doorstop_ops.py list` に `--limit N` / `--offset` 追加 | ページネーション | 低 |
| `trace_query.py status` のサマリモード（アイテム一覧を省略） | 出力削減 | 低 |
| `doorstop_ops.py find --text "keyword"` のテキスト検索 | 関連アイテムの絞り込み | 低 |
| グループ階層化（AUTH.LOGIN, AUTH.TOKEN 等のサブグループ） | 分類の精緻化 | 中 |
| エージェント用の要約キャッシュ（セッション間でのコンテキスト保持） | コンテキスト効率 | 高 |

### 壁5: doorstop のパフォーマンス（大規模以上）

**問題**: `doorstop.build()` はプロジェクトルートからすべての
`.doorstop.yml` を探索し、全アイテムをメモリに読み込む。
アイテム数が10,000を超えると、ツリー構築に数十秒かかりうる。

**対策**:

- **ルート `.doorstop.yml` の `root` パス設定**: 探索範囲を限定する
- **`doorstop_ops.py` の起動コスト**: 各コマンド呼び出しでツリーを
  毎回構築するため、バッチ操作では `bulk_import.py` を活用する
- **超大規模ではサブツリー分割を検討**: 後述の分割戦略を参照

### 壁6: 仕様の陳腐化（ドリフト）（全規模、時間経過で深刻化）

**問題**: 仕様駆動フロー（A-C）を経由せずにコードが変更されると、
仕様と実装が乖離する。エージェント駆動であればフローを強制できるが、
人間が直接コードを変更した場合は検知が遅れる。

**現状の検知メカニズム**:

- `impact_analysis.py --from-git` でgit差分からYAML変更を検出
- `impact_analysis.py --detect-suspects` でsuspect状態を一覧化
- CIのPRゲートで警告/ブロック

**追加の対策**:

- **pre-commitフック**: `references` に登録されたファイルが変更された場合に
  警告を出す（IMPLの `references.path` とgit diffの交差チェック）
- **定期的なヘルスチェック**: CIのスケジュール実行で
  `validate_and_report.py --strict` を定期実行し、drift を早期検知
- **コードオーナーシップ**: IMPL/TSTの `references` をCODEOWNERSと連動させ、
  仕様アイテムの担当者がコード変更をレビューする仕組みを整備

### 壁7: グループ爆発と分類の曖昧化（大規模以上）

**問題**: 機能グループが増えすぎると、どのグループに属するかの判断が
曖昧になり、分類の一貫性が失われる。横断的関心事（ログ、認証、監視等）は
特に複数グループにまたがりやすい。

**対策**:

- グループ名の命名規約を明文化する（最大15-20グループ程度を目安）
- 階層的グループ名を導入する（`AUTH`, `AUTH.LOGIN`, `AUTH.TOKEN`）
- 横断的関心事は専用グループ（`INFRA`, `OBS` 等）に分離する
- グループ一覧を定期的にレビューし、統廃合する

---

## 規模別スケーリング戦略

### 小規模（~1万行）: そのまま使える

```
プロファイル: lite
グループ数: 3-5
アイテム総数: ~100
エージェント負荷: 低（全アイテムがコンテキストに収まる）
```

**ポイント**:
- [F]フローで全量を一括導入可能
- グループのフラット構造で十分
- 特別な対策は不要

### 中規模（1万~10万行）: グループ戦略が鍵

```
プロファイル: standard
グループ数: 5-15
アイテム総数: 100-1,000
エージェント負荷: 中（グループフィルタが必須）
```

**ポイント**:
- ARCH層の導入でコンポーネント間の設計が明確になる
- グループフィルタ（`--group`）を常用する運用に移行
- CIにPRゲート（警告レベル）を導入
- 段階的導入（Phase 1で主要モジュール、Phase 2以降で拡大）

### 大規模（10万~100万行）: 分割とCI統合が必須

```
プロファイル: full
グループ数: 10-20（階層化推奨）
アイテム総数: 1,000-10,000
エージェント負荷: 高（スコープ限定が必須）
```

**ポイント**:
- エージェントは常にグループまたはUIDを起点として作業する
  （全量スキャンは避ける）
- `impact_analysis.py --from-git` を中心とした差分ベースの運用
- CIのPRゲートとリリースゲートの両方を運用
- チームごとにグループの担当範囲を決める
- ダッシュボードを常時公開し、チーム横断の可視化を行う

**導入戦略**:
```
Week 1-2:  パイロットチーム（1チーム）で lite プロファイルで開始
Week 3-4:  パイロット結果を評価、standard に昇格
Month 2:   他チームへ展開開始
Month 3-4: full プロファイルへ移行（必要に応じて）
Month 5+:  CIゲートの段階的厳格化
```

### 超大規模（100万行~）: フェデレーション戦略

```
プロファイル: full + サブツリー分割
グループ数: サブプロジェクト単位
アイテム総数: 10,000+
エージェント負荷: 非常に高（サブツリー分離が必須）
```

**問題の本質**: 100万行を超えるプロジェクトでは、doorstop の単一ツリーに
すべてのアイテムを収めること自体がボトルネックになる。

**フェデレーション戦略**:

```
monorepo/
├── services/
│   ├── auth-service/        ← 独立した doorstop ツリー
│   │   └── specification/
│   ├── payment-service/     ← 独立した doorstop ツリー
│   │   └── specification/
│   └── user-service/        ← 独立した doorstop ツリー
│       └── specification/
├── shared/
│   └── specification/       ← 共通ライブラリの doorstop ツリー
└── system-requirements/     ← システム全体の REQ（最上位）
    └── specification/
```

- **サブプロジェクト単位**で独立した doorstop ツリーを持つ
- **システム要件**は最上位に置き、各サブプロジェクトのREQが
  システム要件を参照する（doorstop の外部リンクまたは手動参照）
- 各サブプロジェクトは独立してバリデーション可能
- エージェントは1つのサブプロジェクトのスコープ内で動作する

**注意**: この戦略はdoorstop のネイティブ機能ではサポートされない。
サブプロジェクト間のトレーサビリティは手動管理または外部ツールが必要。

---

## 導入チェックリスト（規模に応じて選択）

### 全規模共通

- [ ] `init_project.py` でプロジェクト初期化
- [ ] 機能グループの命名規約を決定
- [ ] 最低1つの機能を REQ → SPEC → IMPL → TST の全チェーンで登録
- [ ] `validate_and_report.py --strict` がエラー0件で通ることを確認

### 中規模以上で追加

- [ ] ARCH（またはHLD）層の設計方針を決定
- [ ] グループのスコープと担当チームの対応表を作成
- [ ] CIにPRゲート（警告レベル）を追加
- [ ] ダッシュボード（`serve_app.py`）のデプロイ先を決定

### 大規模以上で追加

- [ ] パイロットチームとパイロットモジュールを選定
- [ ] 段階的導入のロードマップを策定
- [ ] CIのリリースゲートの閾値を決定（最初は緩め→段階的厳格化）
- [ ] `impact_analysis.py --from-git` のCI統合
- [ ] pre-commitフックの検討

### 超大規模で追加

- [ ] サブプロジェクト分割の境界を決定
- [ ] サブプロジェクト間のトレーサビリティ管理方針を決定
- [ ] 各サブプロジェクトの doorstop ツリー初期化
- [ ] システム要件とサブプロジェクト要件の参照関係を定義

---

## まとめ: スケーリングの段階と主な壁

```
                        導入時の壁                  運用時の壁
                    ─────────────────         ─────────────────────
小規模  (~1万行)    壁は低い                  ほぼなし
                    全量一括導入可能

中規模  (1-10万行)  壁2: 粒度マッピング       壁4: コンテキスト制約（軽度）
                    壁3: チーム合意            壁6: 仕様ドリフト
                    → 段階的導入で緩和         → CI警告で緩和

大規模  (10-100万行) 壁1: 初期工数が巨大       壁4: コンテキスト制約（深刻）
                    壁2: 複雑な依存関係        壁5: パフォーマンス
                    壁3: 組織的抵抗            壁7: グループ爆発
                    → パイロット→段階展開      → スコープ限定運用

超大規模 (100万行~)  壁1: 単一ツリーの限界     壁4+5: ツリー分割が必須
                    → フェデレーション戦略     壁6: 組織横断のドリフト管理
                                              → サブプロジェクト自律
```

最も重要な原則: **完璧を目指さず、価値のある部分から始める。**
仕様駆動は全か無かではなく、カバレッジを段階的に高めていくプロセスである。
