パッケージ設計スキル

乱雑なコードを、体系立てた分析で整理されたパッケージへ再構成する。

核心: パッケージ設計は「ソースコードの配置」ではなく「変更の波をどこで止めるか」「依存の向きをどう制御するか」の設計問題である。

コアワークフロー

フェーズ1: 変更理由の分析 - 分割の起点を見つける

分割の出発点は「処理手順」ではなく「変化しそうな設計決定」である。

Parnas の情報隠蔽に基づき、まず以下を問う:

「何が変わるか？」（変更理由・変更源の列挙）
「変わったとき、どこまでを巻き込んでよいか？」（リリース単位・責務境界）

対象コードの変更履歴（git log）を分析し、一緒に変更されるファイル群を特定する
外部要因（UI変更、DB変更、API変更、ビジネスルール変更）ごとに影響範囲を整理する
各変更理由に対して「この変更は、ここで閉じるべき」という境界候補を仮置きする

出力: 変更理由と影響範囲の対応表

フェーズ2: Chunk Down（分解） - 責務を洗い出す

対象コードから原子的な責務を抽出する:

公開されている型・関数・トレイトをすべて列挙する
各要素に対して「一文の責務説明」を書く
暗黙的な責務（エラー処理、ログ、設定など）を洗い出す
複数責務を持つ要素（SRP違反）をフラグする

出力: 10〜50件の原子的な責務一覧

フェーズ3: グルーピング - 候補パッケージを作る

責務を分割する際の軸を選択し、グルーピングする。

分割軸の選択

分割軸	凝集の性質	適するケース	リスク
機能（feature/vertical）	変更が縦に閉じる	チーム独立、マイクロサービス候補	共通化地獄
ドメイン（業務概念）	情報的凝集	ドメインモデルの一貫性重視	コンテキスト間翻訳コスト
レイヤ（技術層）	技術責務の分離	小規模、導入初期	1変更が全層に散る
責務（変更理由）	CCP準拠	変更頻度が明確	初期分析コスト
API境界（公開IF）	表面積最小化	ライブラリ設計	内部柔軟性とのバランス

グルーピングのヒューリスティクス

一緒に変更される要素 → 同一パッケージ（CCP）
一緒に再利用される要素 → 同一パッケージ（CRP）
ドメイン概念の境界 → 自然なパッケージ境界

出力: 3〜7個の候補パッケージ（認知負荷の観点から7±2が目安）

MECEによる検証（設計目標ではなくチェック観点として）

MECEは「設計の目的」ではなく「網羅性チェックの補助」として使う。 厳密MECEにこだわりすぎると、横断的関心（ログ、認可、トランザクション等）の扱いで境界が薄くなる危険がある。8〜9割の網羅で十分。

各責務は1つのパッケージに割り当てられているか（重複なし）
未割り当ての責務が残っていないか（漏れなし）
「Xはどこに置く？」に対して答えが1つだけあるか

詳細は references/principles.md#mece-分割 を参照。

フェーズ4: Chunk Up - 抽象化と命名

各グループを一段抽象化して命名する:

各グループを貫く概念を見つける
技術的な役割ではなく、ドメイン概念で命名する
そのパッケージの目的を一文で言えることを確認する
命名が難しい場合はグルーピングが誤っている可能性が高い → フェーズ3に戻る

良い例: authentication, billing, inventory 避ける例: utils, helpers, common, misc

フェーズ5: 依存関係設計と原則検証

依存の向きを設計する

依存は「より安定・より抽象」な側へ向ける。

パッケージ間の依存グラフを描く
循環依存がないか確認（ADP）
安定側（多くから依存される）→ 不安定側（多くに依存する）の向きに依存が逆転していないか確認（SDP）
安定なパッケージが十分抽象的か確認（SAP）

循環依存の解消手順

循環が見つかった場合:

依存性逆転: 依存される側の抽象（Interface/Trait）を依存する側へ移し、実装は逆向きに差し込む
共有抽出: 相互参照している共通型/ロジックを第三のパッケージへ移動し、循環辺を切る
統合: 本当に同一責務ならパッケージを統合する

原則チェック

原則	確認観点
高凝集	パッケージ内の要素が単一目的に収束しているか
低結合	パッケージ間の依存が最小か
ADP	循環依存がないか
SDP	依存が安定側に向かっているか
SAP	安定なパッケージが十分抽象的か
CCP	同じ変更理由のものが同一パッケージに閉じているか

詳細は references/principles.md を参照。

フェーズ6: 公開インターフェースとテスト境界の定義

公開インターフェース

各パッケージについて:

pub にすべき要素（外部契約）を特定する
それ以外は pub(crate) か private にする
インターフェースが複雑ならファサード型/関数を用意する
モジュールドキュメントで契約を説明する

テスト境界の対応付け

テストを「境界」に対応させる:

テスト種別	対象	目的
ユニットテスト	パッケージ内部	内部の凝集を守る
統合テスト	パッケージ間	境界横断の依存が設計どおりか
契約テスト	公開API境界	互換性（結合点）を守る

評価チェックリスト

提案した構造が以下を満たしているか確認する（Yesが多いほど高凝集・低結合）:

各パッケージの目的が一文で言える（何を提供し、何を隠すか）
境界を越える依存は、公開API（ファサード/ポート）を経由している
パッケージ依存グラフが非循環である
安定度の高い領域が十分抽象化されている
変更理由がパッケージ境界で止まる
境界のテストが公開APIの範囲と一致している

メトリクスによる定量評価

メトリクス	対象	意味
Ca（求心結合）	パッケージ	外部から依存される数
Ce（遠心結合）	パッケージ	外部へ依存する数
I = Ce/(Ca+Ce)	パッケージ	不安定性（0=最安定, 1=最不安定）
D（Main Sequenceからの距離）	パッケージ	A + I = 1 からの乖離

詳細は references/principles.md#パッケージメトリクス を参照。

リファクタリングトリガー

以下が観測されたら分割/境界の見直しを検討する:

変更が複数パッケージに散る（CCP違反の兆候）
Ce増大（外部依存が増え続ける）
パッケージサイクル（循環依存）が発生する
パッケージ内の複雑度が上昇し続ける

Rust固有のパターン

references/rust-patterns.md を参照:

mod 階層設計
ワークスペースと単一クレートの選択
featureフラグ戦略
再エクスポートの指針

※ このプロジェクトでは mod.rs を使わない。2018モジュール方式で package_name.rs と package_name/ 配下のファイルで構成する。

代表パターン比較

パターン	凝集軸	利点	リスク
レイヤード	技術責務	導入容易	1変更が全層に散る
機能別（vertical slicing）	ユースケース	変更が閉じやすい	共通化地獄
コンポーネント別	機能集合	境界が明確	公開API設計コスト
Bounded Context	ドメイン境界	モデル整合性	コンテキスト間翻訳コスト
Ports & Adapters / Clean	依存方向	テスト容易	構造の形式主義

アンチパターン

God module: 1ファイルに500行以上の責務が集中している
循環依存: A → B → C → A（境界が実質的に崩壊したシグナル）
不安定依存: 中核モジュールが変化の激しいモジュールに依存（SDP違反）
抽象の漏れ: 内部型が公開APIに漏れ出る
雑多な util/common: 関連性の低い要素が「その他」で集約される（共通結合の温床）
レイヤだけで境界なし: 見た目がレイヤでも相互参照や内部参照が放置されている
cargo cult パッケージング: パターンを理由理解なしに適用し、構造は整って見えるが意図が失われている

出力フォーマット

再構成提案は以下の形式で示す:

## 提案パッケージ構成

package_name.rs (目的: 1文で説明)
package_name/
├── submodule_a.rs
└── submodule_b.rs

### 依存関係
package_a → package_b (reason)

### メトリクス概算
package_a: Ca=3, Ce=1, I=0.25 (安定)
package_b: Ca=1, Ce=2, I=0.67 (不安定)

### 移行手順
1. 新しいモジュール構造を作成する
2. 型や関数を最小変更で移動する
3. import を更新する
4. テストが通ることを確認する
5. 循環依存がないことを静的解析で確認する

package-design