# ADR-20260301: 設計ドキュメント構造 — Foundation + Command Spec モデル

## ステータス

Accepted

## 日付

2026-03-01

## コンテキスト

### 更新頻度の偏り

git log 分析により、`04_cli_design.md` が他の設計書（変更2〜5回）に対し **7回** と突出して変更頻度が高いことが判明した。

### 安定度の混在

04 内部に **安定度の異なる2種類のコンテンツ** が混在していた。

| セクション | 性質 | 変更頻度 |
| :--- | :--- | :--- |
| §1-3（目的、規約） | 安定（アーキテクチャ決定） | 低 |
| §4（コマンド個別仕様） | 揮発（機能追加で増加） | 高 |
| §5, §7（一覧表、チェックリスト） | 派生データ（§4 の集約ビュー） | 高 |

### 派生データによる SSOT 違反

§5（Bounded Context 対応一覧）と §7（契約整合性チェックリスト）は §4 や 02/03 からの **派生データ** であり、手動メンテナンスの重複が発生していた。`raw get` 追加時には §4.7, §5.1, §5.2, §8 の4箇所を更新する必要があった。

## 決定

### 2層モデル: Foundation + Command Spec

ドキュメントを **変更頻度と安定度** で2層に分離する。

| 概念層 | 役割 | 該当ファイル | 更新パターン |
| :--- | :--- | :--- | :--- |
| **Foundation（基盤）** | アーキテクチャの不変ルール、型契約、スキーマ、共通規約 | 01〜05（ルート直下） | まれに更新。変更は全コマンドに波及し得る |
| **Command Spec（機能）** | 個別コマンドの仕様 | `commands/*.md` | 追加中心。新コマンド = 新ファイル |

**核心ルール: コマンド追加 = 新ファイル1つの追加。既存ファイルの更新ゼロ。**

### 派生セクションの廃止

| 旧セクション | 判断 | 理由 |
| :--- | :--- | :--- |
| §5 Bounded Context 対応一覧 | 廃止 | 各 Command Spec が自身の BC を宣言（Dependency Inversion） |
| §7 契約整合性チェックリスト | 廃止 | 実装時の確認事項であり設計仕様ではない |
| §8 将来拡張 | 廃止 | Issue tracker に移動 |

### Dependency Inversion（自己宣言パターン）

中央マッピング表で全コマンドを一覧管理する代わりに、各 Command Spec が自身の Bounded Context とレイヤー対応を冒頭で宣言する。これにより中央管理が不要になり、コマンド追加時に既存ファイルを更新する必要がなくなる。

### テンプレート方針

`commands/_template.md` を用意し、新コマンド追加時にコピーして使用する。テンプレートには Bounded Context 宣言セクションを含め、旧 §5 一覧表の代替とする。

## 却下した代替案

| 案 | 提案者 | 見送り理由 |
| :--- | :--- | :--- |
| `core/` ディレクトリ分離 | Codex, Gemini | 5ファイルの移動で全リンク破壊。コストに見合わない |
| バージョン付き命名 (`.v1.md`) | Codex | CLI コマンドにバージョン概念なし。YAGNI |
| `_generated/` ディレクトリ | Codex | 10コマンド規模で自動生成は過剰。`ls` で十分 |
| ADR ディレクトリ（当時） | Codex | 設計根拠は各ドキュメント内に既存。git history で追跡可能 |
| YAML フロントマター | Codex | 消費するツールなし。ボイラープレート化するだけ |
| サブコマンドディレクトリ (`raw/`) | Gemini | `raw` 配下2ファイル。フラットで十分 |

**共通する判断基準:** konkondb は CLI コマンド 10個、Foundation ドキュメント 5個の規模。上記の仕組みは 30+ コマンド規模で効果を発揮するが、現規模では複雑性の追加コストが効果を上回る。

## Graduation Path

プロジェクトが成長し、以下の閾値を超えた場合に構造の再検討を推奨する。

| 閾値 | トリガーされる再構成 |
| :--- | :--- |
| コマンド 20+ | `commands/` 内のサブディレクトリ化（`commands/raw/`, `commands/serve/`） |
| Foundation 以外のカテゴリ追加 | `core/` + `features/` ディレクトリ分離 |
| コマンド 30+ | `_generated/index.md` 自動生成スクリプトの導入 |
| 設計判断の追跡ニーズ増大 | ADR ディレクトリの本格運用 |
| 横断的なメタデータ検索ニーズ | YAML フロントマター + 生成スクリプトの導入 |

## 影響

### メリット

| メリット | 説明 |
| :--- | :--- |
| **追加のみで拡張 (OCP)** | コマンド追加時に既存ファイルの変更ゼロ。Feature-per-file パターン |
| **SSOT の厳格化** | 派生データを廃止し、情報の重複を排除 |
| **並行作業の容易化** | 異なるコマンドを異なる人/エージェントが同時に設計可能 |
| **レビュー範囲の明確化** | 新コマンドのレビュー = 1ファイルの差分のみ |
| **発見性の向上** | ファイル名からコマンドが直感的にわかる |

### デメリット

| デメリット | 緩和策 |
| :--- | :--- |
| ファイル数の増加（1→10+） | ディレクトリで整理。IDE の検索で対応可能 |
| 全体俯瞰の困難化 | `ls commands/` で一覧可能。ファイルツリー自体がインデックス |
| テンプレートの維持コスト | テンプレートはシンプルに保ち、規約は Foundation に集約 |
| クロスリファレンスの増加 | テンプレートにリンク欄を標準化 |
