設計の意思決定を「感覚から根拠へ」──3アーキテクチャ並列設計の仕組み

こんにちは。ファインディ株式会社でテックリードマネージャーをやらせてもらってる戸田です。

ファインディでは要件定義から設計・タスク分解・Issue生成までをAIに任せるカスタムコマンドを開発しています。前回の記事ではコマンドの全体フローを紹介しました。

tech.findy.co.jp

AIにタスク分解やIssueを作成してもらうには、先に実装方針を明確にする必要があります。方針が固まっていないと、生成されるタスクの粒度や設計の一貫性がブレてしまうからです。このコマンドの設計ステップでは、3つのアーキテクチャアプローチを並列で設計し、トレードオフを比較して最適な方針を選択します。

本記事では、その設計ステップに焦点を当て、3つのアーキテクチャ案を並列で設計してトレードオフ比較で選ぶ仕組みを紹介します。

コードベースの並列探索
3アーキテクチャ並列設計の仕組み
トレードオフ比較と選択
まとめ

コードベースの並列探索

コマンドを実行すると、まず3つのエージェントが並列でコードベースを分析します。

既存のコードベースを理解するため、Claude Codeの公式Pluginであるfeature-dev にある code-explorerエージェントを活用します。このエージェントはプロジェクトの構造やパターンを自動的に分析して実装に必要な情報を収集します。feature-devプラグインをインストールするだけでcode-explorerエージェントを利用できるようになります。

要件を分割して複数のcode-explorerエージェントを並列で起動します。各エージェントが特定の観点からコードベースを探索して必要な情報を収集します。

実際の実行ログは次のとおりです。

⏺ Phase 2: コードベースの探索

  既存のコードとパターンを理解するため、複数のcode-explorerエージェントを並列で起動します。

  Running 3 feature-dev:code-explorer agents… (ctrl+o to expand)
   ├─ Explore user registration architecture · 12 tool uses · 29.1k tokens
   │  ⎿  Search: **/models/admin*.py
   ├─ Explore admin API patterns · 12 tool uses · 27.6k tokens
   │  ⎿  Read: main.py
   └─ Explore CSV and file handling · 10 tool uses · 17.0k tokens
      ⎿  Search: **/api/routes/**/*.py

3つの探索結果は統合され、既存のユーザー登録処理のパターンやCSVファイル処理の実装有無、管理者APIの構造といった知見が次の設計フェーズに引き渡されます。コードベースを自分で読んで回るよりも短時間で、設計に必要な情報を網羅的に集められます。

3アーキテクチャ並列設計の仕組み

このコマンドの中核となるのが、1つの機能要件に対して3つのアーキテクチャ案を同時に設計する仕組みです。コードベース探索の結果を受け取った3つのエージェントが、それぞれ異なる方針で設計を並列に進めます。

Claude Codeの公式Pluginであるfeature-dev にある code-architectエージェントを活用します。このエージェントは設計方針を提案してくれます。開発者は提案された選択肢の中からプロジェクトに最適な実装方針を選ぶことができます。この選択により実装の方向性が確定します。

Running 3 code-architect agents...
├─ Design minimal change approach
├─ Design clean architecture approach
└─ Design pragmatic balance approach

最小変更アプローチ

既存コードを最大限活用して変更範囲を最小に抑える方針です。たとえばCSVインポート機能の追加であれば、処理ロジックをルートハンドラに直接実装することで新規ファイルを2個に抑えられます。

タスク数: 2個
メリット: 最速で実装できる。既存コードとの整合性が高く、レビューしやすい
デメリット: ハンドラが肥大化しやすい。処理ロジックの再利用が難しく、将来の拡張で追加実装が必要になる

緊急対応や短期のPoC、スコープを絞った小規模な機能追加に向いています。

クリーンアーキテクチャアプローチ

Parser・Validator・Serviceといった責務の分離を徹底し、将来の変更に強い構造を作る方針です。新規ファイルは7個ほどになりますが、各層を独立してテストでき、将来ExcelやJSONへの対応を追加する際も既存コードへの影響を最小化できます。

タスク数: 6個
メリット: 拡張性・テスタビリティが高い。ビジネスロジックの再利用が容易
デメリット: 初期実装に時間がかかる。抽象化レイヤーが増えるため、シンプルな変更でも影響範囲の把握が必要になる

長期的に保守・拡張する基盤機能や、複数のフォーマット・ユースケースに対応する予定がある場合に向いています。

実用的バランスアプローチ

サービス層を導入して責務をある程度分離しながら、Parser・Validatorの細かい分割は行わない方針です。新規ファイルは5個ほどになり、実装速度と保守性のバランスが取れています。

タスク数: 5個
メリット: 適度な抽象化で保守性を確保しつつ、最小変更よりも将来の拡張に対応しやすい
デメリット: クリーンアーキテクチャほどの柔軟性はなく、最小変更ほどのシンプルさもない

通常の機能開発にもっとも推奨されるアプローチです。即時の拡張予定はないが、一定の保守性は確保したいというケースに適しています。

トレードオフ比較と選択

3案が揃うと、次のような比較表が提示されます。

⏺ 3 feature-dev:code-architect agents finished (ctrl+o to expand)
   ├─ Design minimal change approach · 20 tool uses · 25.2k tokens
   │  ⎿  Done
   ├─ Design clean architecture approach · 26 tool uses · 41.0k tokens
   │  ⎿  Done
   └─ Design pragmatic balance approach · 0 tool uses
      ⎿  Done

⏺ 3つのアーキテクチャアプローチが完成しました。それぞれの特徴を整理してご提案します。

  3つのアプローチ比較

  1. 最小変更アプローチ (Minimal Change)

  特徴:
  - CSV処理をルートハンドラに直接実装（約150行の単一ファイル）
  - 既存パターンを最大限活用（teams.pyの部分成功パターン）
  - 新規作成ファイル: 2個（エンドポイント + テスト）

  メリット:
  - 最速で実装可能（2 PR、~650行）
  - シンプルで理解しやすい
  - 既存コードとの整合性が高い

  デメリット:
  - ルートハンドラが長くなる（~150行）
  - CSV処理ロジックの再利用が困難
  - 将来の拡張（Excel対応など）に追加実装が必要

  タスク数: 2個

  ---
  2. クリーンアーキテクチャアプローチ (Clean Architecture)

  特徴:
  - サービス層を導入して責務を分離
    - Parser（CSV解析）
    - Validator（バリデーション）
    - UserImportService（オーケストレーション）
  - 新規作成ファイル: 7個

  メリット:
  - 将来の拡張が容易（Excel, JSON対応）
  - テストが容易（各層を独立してテスト可能）
  - ビジネスロジックの再利用性が高い
  - 保守性が高い

  デメリット:
  - 初期実装に時間がかかる（6 PR、~730行）
  - 抽象化により複雑さが増す
  - シンプルなCSV処理に対してはオーバーエンジニアリングの可能性

  タスク数: 6個

  ---
  3. 実用的バランスアプローチ (Pragmatic Balance)

  特徴:
  - サービス層を導入するが、Parser/Validatorは分離しない
  - UserImportServiceで一元管理
  - 新規作成ファイル: 5個

  メリット:
  - 適度な抽象化で保守性を確保
  - 実装速度とコード品質のバランスが取れている
  - 将来の拡張もある程度対応可能

  デメリット:
  - クリーンアーキテクチャほどの柔軟性はない
  - 最小変更アプローチほどシンプルではない

  タスク数: 5個

数字だけでなく、各アプローチが「どんな状況に向いているか」も合わせて提示されます。チームの状況や緊急度、今後の拡張計画に照らし合わせてアプローチを選択します。

────────────────────────────────────────────────────────────
 ☐ Approach

どの実装アプローチを採用しますか？

  1. 実用的バランス (Recommended)
  2. 最小変更
❯ 3. クリーンアーキテクチャ
  4. Type something.