arch-clean

arch-clean

目的

このスキルは、ポートとアダプターを使うヘキサゴナルパターン、依存関係逆転、ユースケース、エンティティ、テスト容易性に重点を置き、コードベースにクリーンアーキテクチャの原則を適用します。関心事を分離してシステムをモジュール化し、テストしやすくするために、コードをリファクタリングまたは生成します。

使用する場面

モノリシックアプリをリファクタリングして保守性を高めるとき、高いテスト容易性が求められる新規プロジェクトを始めるとき、または密結合を避けて外部依存関係を統合するときに、このスキルを使用してください。ECサイトのバックエンドのようにビジネスロジックが複雑な場合や、レガシーコードをマイクロサービスなどの最新アーキテクチャに適合させる場合に適用します。

主な機能

• アダプター向けのポートインターフェースを生成し、依存関係逆転を実現します（例：interface UserPort { fetchUser(id: string): User; } のような契約を定義します）。
• エンティティとポートを統括するユースケースクラスを作成し、単一責任を促進します。
• 外部ライブラリをアダプターでラップして依存関係を逆転させます。たとえば、データベースへの直接呼び出しをポートの実装に置き換えます。
• ユースケース内でポートをモックするなど、ユニットテストに適したコード構成にして、テスト容易性を高めます。
• 静的解析を通じて、内側のレイヤーが外側のレイヤーに依存していないことを確認するなど、アーキテクチャのルールを検証します。

使用パターン

手早くリファクタリングする場合は OpenClaw の CLI から、自動化されたパイプラインでは API からこのスキルを呼び出します。まずスキャンコマンドでコードベースを分析し、その後に変換を適用します。スクリプトでは、出力を Make や Gradle などのビルドツールにパイプします。デフォルト設定が適用されないよう、対象ディレクトリと言語（例：TypeScript または Java）を必ず指定してください。アーキテクチャを適用するプリコミットフックとして、CI/CD で使用します。

よく使うコマンド／API

arch-clean をプレフィックスとするサブコマンドを使って、OpenClaw CLI を実行します。認証には、環境変数として $OPENCLAW_API_KEY を設定する必要があります。

• ポートインターフェースを生成する：

  openclaw arch-clean generate-port --name UserPort --methods "fetchUser(id: string)" --lang ts
  

  これにより、インターフェースを含む UserPort.ts のようなファイルが作成されます。

• モジュールの依存関係を逆転させる：

  openclaw arch-clean invert-dep --path src/services --adapter DatabaseAdapter
  

  指定されたパスをスキャンして依存関係をラップします。たとえば、直接インポートをアダプターの呼び出しに置き換えます。

• ユースケースを作成する：

  openclaw arch-clean create-usecase --name FetchUser --ports UserPort --entities User
  

  ポートを注入する FetchUserUseCase.ts のようなクラスを生成します。

プログラムから使用する API エンドポイント：

• POST /api/arch-clean/generate：本文 { "type": "port", "name": "UserPort", "methods": ["fetchUser(id: string)"] }。ヘッダーに $OPENCLAW_API_KEY が必要です。
• PUT /api/arch-clean/invert：本文 { "path": "src/services", "adapter": "DatabaseAdapter" }。

設定形式：カスタムルールには JSON ファイルを使用します。例：{ "layers": { "domain": ["entities", "usecases"], "adapters": ["http", "db"] } } を含む .openclaw-arch.json。

統合に関する注意事項

プロジェクトに OpenClaw を依存関係として追加して統合します（例：npm install openclaw、または Docker イメージを使用）。認証付きリクエストには $OPENCLAW_API_KEY を設定します。IDE プラグインでは、{ "arch-clean": { "defaultLang": "ts", "excludePaths": ["tests/**"] } } のような設定を使用します。出力をパイプすることで、ESLint などのリンターと組み合わせられます（例：openclaw arch-clean scan | eslint --fix）。ヘキサゴナルパターンに適合するよう、「domain」、「application」、「infrastructure」用のフォルダーなど、コードベースがサポート対象の構造を使用していることを確認してください。

エラー処理

コマンドの出力でエラーを確認してください。CLI は、たとえば { "error": "Dependency not inverted: invalid path" } のような JSON エラーメッセージと、0 以外の終了コードを返します。API では、{ "code": 400, "message": "Missing required field: methods" } のような本文を伴う HTTP 4xx／5xx レスポンスが返されます。次のように、呼び出しを try-catch ブロックで囲んで処理してください。

try {
  const response = await fetch('/api/arch-clean/generate', { headers: { 'X-API-Key': process.env.OPENCLAW_API_KEY } });
  if (!response.ok) throw new Error(response.statusText);
} catch (error) {
  console.error('Arch error:', error.message);
}

ネットワークの問題など、一時的なエラーは指数バックオフを使って最大 3 回再試行してください。

使用例

1. ポートを使用するようにシンプルなサービスをリファクタリングする： Node.js アプリの場合、openclaw arch-clean invert-dep --path src/userService.js --adapter HttpAdapter を実行します。これにより、直接的な HTTP 呼び出しがポートに変換されます。たとえば、axios.get('/user') が this.userPort.fetchUser(id) に変更され、モックを使用できるようになるため、テストしやすくなります。

2. ビジネスロジックのユースケースを生成する： Java プロジェクトで、openclaw arch-clean create-usecase --name OrderProcessor --ports PaymentPort --entities Order を実行します。これにより、public void process(Order order) { this.paymentPort.charge(order); } のようなメソッドを含む OrderProcessor.java が生成され、依存性注入によるアーキテクチャの改善が可能になります。

グラフの関係

• 関連：se-architecture クラスター（幅広いリファクタリングのための code-refactor などのスキルへのリンク）。
• 依存：ports-adapters タグ（アダプター実装のために hexagonal-architecture と接続）。
• 競合：モノリシックなパターン（レガシーシステムの密結合を回避）。