active: true
derived: false
groups:
- CLI
header: |
  実践的なCLIリファクタリングポリシー
level: 1.26
links:
- ARCH011: MuEszjxI2CEtYDj9vnuASs-Y55-4Zf45GBu_6uBGI-I=
- REQ011: OVqOTj0C8wPg2sT3ZDzQbWyXOFCZ4tvRuEyYZRp0O7E=
normative: true
ref: ''
reviewed: DISmVYRt65pfinXjY8Wp0kL-EDccW9gAtA6QWiDEa48=
status: accepted
text: |
  # 実践的なCLIリファクタリングポリシー

  ## コンテキストと課題

  `quality_report.md` において、`src/beautyspot/cli.py` 内の複数の関数（`show_cmd`, `prune_cmd`, `stats_cmd`）が循環的複雑度（CC）で **Rank C** の警告を受けています。一般的にプロジェクトでは CC の低減を推奨していますが、CLI モジュールに関してはその優先度と費用対効果を再検討する必要があります。

  ## 判断基準

  * **Efficiency**: リファクタリングのリソースを、ユーザーに直接影響するコアロジックに優先的に配分すること。
  * **Readability**: CLI コマンドの「上から下への命令的フロー」を維持し、挙動の追いやすさを損なわないこと。
  * **Architectural Impact**: 依存関係の末端にある CLI モジュールの複雑さが、システム全体の安定性に与える影響を考慮すること。

  ## 検討した選択肢

  * **Option 1**: 厳格なリファクタリング。すべての Rank C 関数を Rank A/B になるまで分解する。
  * **Option 2**: 戦略的許容。表示ロジックに起因する複雑さは許容し、現状の構造を維持する。

  ## 決定事項

  採用した選択肢: **Option 2**.

  CLI モジュールの Rank C スコアについては、以下の理由から**「即時の抜本的なリファクタリングは行わず、現状の構造を維持する」**ことを決定しました。

  * **表示ロジックの特性**: `cli.py` の複雑さは、データ取得後の表示フォーマット分岐（Rich ライブラリによる出力制御）に集中しており、純粋なビジネスロジックの複雑さとは性質が異なります。
  * **設計上の影響の小ささ**: `cli.py` は依存関係の末端に位置しており、他モジュールへの波及効果がありません。
  * **可読性の維持**: CLI コマンドは、過度に抽象化されるよりも命令的に記述されている方が挙動を追いやすい場合があります。

  ## 影響・結果

  * **ポジティブ**:
      * コアロジック（`cachekey.py` など）のリファクタリングにリソースを集中できる。
      * 不要な抽象化による「コードの追いづらさ」を回避できる。
  * **ネガティブ**:
      * 品質レポート上の警告は残り続ける。
      * 将来的にコマンドがさらに肥大化した場合には、改めて分割を検討する必要がある。
