Communityコーディング&開発github.com

ヘキサゴナルアーキテクチャ移行プラン

既存のコードベースを分析し、外部契約を維持したままヘキサゴナルアーキテクチャ(Ports and Adapters)へ段階的に移行する、破壊的変更のないリファクタリング計画を立案します。

ヘキサゴナルアーキテクチャ移行プラン とは?

このスキルは、任意の言語やフレームワークで書かれた既存のコードベースを、**ヘキサゴナルアーキテクチャ(Ports and Adapters)** に移行するための詳細な段階的リファクタリング計画を提供します。最も重要な原則は「破壊的変更ゼロ」であり、既存のすべての外部契約(HTTPルート、レスポンス形式、エラーフォーマットなど)を完全に維持します。このスキルはPlan Modeで動作し、まずコードベースを徹底的に調査してから計画を提案します。対応プラットフォームは特定のものに限定されず、TypeScript/Node、Python、Go、Java/Kotlin、C#、Rustなど、あらゆるスタックで使用できます。ワークフローは、コードベースの発見、ターゲットとなる3層構造(domain、application、infrastructure)の設計、5つのアトミックな実行フェーズ(特性テスト→ドメイン抽出→アプリケーションとアダプター→駆動アダプター→後片付けと検証)で構成されます。各フェーズの終了時には検証チェックポイントが設定され、安全な移行を保証します。

対応~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/gabrandalisse/skills/tree/HEAD/skills/to-hexagonal-architecture

Installed? Explore more コーディング&開発 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

ヘキサゴナルアーキテクチャへの移行

既存のリポジトリを詳細に分析し、外部契約や観測可能な動作を一切壊さずに、ヘキサゴナルアーキテクチャ(Ports and Adapters) へ移行するためのアトミックで段階的なリファクタリング計画を設計します。

ユーザーのリクエストと同じ言語で応答します。厳密にPlan Modeで動作し、まずコードベースを検査してから完全な計画を提供し、その後でファイルを変更します。

使用タイミング

  • ユーザーが既存のプロジェクトをヘキサゴナルアーキテクチャまたはPorts and Adaptersに移行またはリファクタリングするよう依頼した場合。
  • ユーザーがビジネスロジックをWebフレームワーク、ORM、データベース、メッセージブローカー、外部SDKから切り離したい場合。
  • ユーザーが破壊的変更のない安全で段階的なアーキテクチャリファクタリング計画を求めた場合。

中核原則

  1. 破壊的変更ゼロ(黄金律): 既存の外部契約をすべて維持します。ルート、HTTPメソッド、ステータスコード、リクエスト/レスポンスペイロードスキーマ、ヘッダー、エラーフォーマット、CLIフラグ、キューなどのメッセージ形式は完全に同一でなければなりません。
  2. リファクタリング前の特性テスト: 自動化された契約/特性テストが既存のエンドポイントまたはエントリポイントをカバーするまで、プロダクションロジックを移動または削除してはいけません。
  3. 厳格な依存関係ルール: ソースコードの依存関係は常にdomain(ドメイン)に向かって内向きでなければなりません。ドメインレイヤーは、Webフレームワーク、データベースドライバー、ORM、シリアライゼーションライブラリ、外部SDKからのインポートを一切持ってはいけません。
  4. スタックに即した適応: ディレクトリパス、命名規則、型構文、テストランナーを、検出されたプロジェクトの言語とエコシステム(例:TypeScript/Node、Python、Go、Java/Kotlin、C#、Rust)に適合させます。

ワークフロー

ステップ 1: コードベースの発見

フォルダツリーや移行手順を提案する前に、リポジトリをスキャンします。

  1. スタックとツール: 依存関係マニフェスト、コンパイラ/リンター設定、テストランナーを検査し、言語、フレームワーク、バリデーションライブラリ、ORM/クエリビルダー、DIアプローチを特定します。
  2. エントリポイントと契約: すべての駆動エントリポイント(HTTPルート、GraphQLリゾルバー、gRPCサービス、メッセージコンシューマー、cronジョブ)、そのバリデーションスキーマ、ミドルウェア/インターセプター、およびグローバルエラーハンドラーを棚卸しします。
  3. 外部依存関係: すべての駆動される副作用(データベース、キャッシュ、HTTP/RPCクライアント、キュー、ファイルストレージ、環境設定、ロガー)を棚卸しします。
  4. 現在の実行フロー: エントリポイントから永続化/外部呼び出し、そして戻ってくるまでのデータの流れを追跡し、ビジネスルールがトランスポートや永続化の詳細と混在している箇所を特定します。

ステップ 2: ターゲットとなるヘキサゴナル構造の設計

3つの同心円状のレイヤーを、プロジェクトの慣用的なソースルート(例:TypeScript/Rustのsrc/、Goのinternal/、JVMのsrc/main/<lang>/、Pythonのメインパッケージディレクトリ)にマッピングします。

  • domain/(純粋なビジネスコア - フレームワークやI/O依存関係なし):
    • entities/ および value-objects/:ビジネスルール、不変条件、自己バリデーションをカプセル化するドメインモデル。
    • ports/in/:ユースケース契約を定義する駆動ポートインターフェース。
    • ports/out/:リポジトリ、外部サービス、イベントパブリッシャー、LoggerPort契約を定義する駆動されるポートインターフェース。
    • errors/:意味論的なドメイン例外(例:ResourceNotFoundError、DomainValidationError、ConflictError)。
  • application/(ユースケースオーケストレーション):
    • use-cases/:ports/inの実装であり、ドメインエンティティとports/outを調整します。
    • dtos/:トランスポートペイロードや永続化エンティティから切り離された不変の入力および出力データ構造。
  • infrastructure/(技術的詳細とアダプター):
    • adapters/in/:駆動アダプター(HTTPコントローラー/ハンドラー、コンシューマーハンドラー)、トランスポートバリデーションスキーマ、マッパー(TransportInput -> InputDTO および OutputDTO -> TransportOutput)、およびdomain/errorsを正確なレガシーエラーレスポンスに変換するグローバルエラーマッパー。
    • adapters/out/:ports/outの具体実装(データベースリポジトリ、HTTPクライアント、ブローカー)。永続化/外部マッパーを備え、ORMモデルやSDK型がdomain/に漏れることを防ぎます。
    • config/:環境変数とランタイム設定の厳格な読み込みおよび起動時バリデーション。
    • di/(コンポジションルート):コンストラクターインジェクションを介した、駆動されるアダプター、ユースケース、駆動アダプターの明示的な配線。隠れたシングルトンやサービスロケーターを避けます。
  • ブートストラップの分離: アプリケーションの構築(buildApp / 分離された統合テストのためのファクトリ関数)とサーバー/プロセスの起動(main / listen)を分離します。

ステップ 3: 計画におけるエンジニアリング標準の適用

計画の各フェーズで以下を適用することを保証します。

  • 強い型付けと不変性: 型なしエスケープ(例:any または型構造が適用される場所での未加工の型なしマップ)を禁止し、不変DTOとValue Object(readonly、凍結データクラス、レコード、値型)を優先します。
  • SOLIDとコンストラクターインジェクション: クラスと関数を単一責任で小さく保ち、コンストラクターを介してインターフェースを注入します。
  • 結合のない可観測性: 構造化ロギングとリクエスト相関コンテキストを維持しながら、LoggerPortを介してdomain/とapplication/を特定のロギングライブラリから切り離します。
  • ピラミッド型テスト:
    • domain/(純粋な不変条件)とapplication/(ports/outのモック)のユニットテスト。
    • スタックのネイティブなインメモリテストクライアント(例:fastify.inject、Supertest、FastAPI TestClient、Spring MockMvc、Go httptest)を使用して、実際の駆動アダプターをアプリケーション配線に対して検証する統合/契約テスト。

出力形式(Plan Mode)

応答を以下の正確なセクションに構成して提供します。

  1. 現在のアーキテクチャ診断: 検出されたスタック、エントリポイント/エンドポイント、外部依存関係、および主要な結合ホットスポットの簡潔な棚卸し。
  2. ターゲットディレクトリツリー: リポジトリ内で見つかった実際のモジュール名と機能名を使用した、提案される完全なフォルダ構造。
  3. 段階的実行計画: 5つのアトミックで検証可能なフェーズ。
    • フェーズ 1 - 特性テストと基本スキャフォールディング: 現在の動作を固定するコントラクトテストを作成し、ターゲットフォルダ、設定ローダー、コンポジションルート(di/)を作成します。
    • フェーズ 2 - ドメイン抽出: エンティティ、値オブジェクト、ドメインエラー、ports/in + ports/outインターフェースをユニットテストとともに抽出します。
    • フェーズ 3 - アプリケーションのユースケースと駆動されるアダプター: ユースケース、DTO、adapters/outリポジトリ/クライアント、永続化マッパーを実装します。
    • フェーズ 4 - 駆動アダプターとエラー変換: コントローラー/ハンドラーをリファクタリングしてマッパーを介してユースケースに委譲し、グローバルエラー変換を配線し、di/に接続します。
    • フェーズ 5 - レガシークリーンアップと最終検証: 不要なファイルを削除し、完全なテストスイート、リンター、型チェッカーを実行し、契約のずれがないことを確認します。
  4. 検証チェックポイント: 各フェーズの終了時に、次のフェーズに進む前に何も壊れていないことを証明する明示的なコマンドまたはチェック。

注意点

  • コードを時期尚早に編集しないでください: ユーザーが明示的にフェーズ1の実行を要求しない限り、最初は計画のみを出力してモジュール境界を確認できるようにします。
  • 単純なCRUDでの過剰な抽象化を避ける: それでもdomain、application、infrastructureはきれいに分離しますが、パススルーユースケースは簡潔に保ち、人為的なドメイン複雑性を発明しないようにします。
  • レガシーの癖に合わせる: 既存のエンドポイントが非標準のステータスコードやエラーフィールド名を返す場合、フェーズ1でそれを文書化し、infrastructureエラーマッパーで維持して、既存のクライアントが壊れないようにします。

関連スキル