architecture-patterns

architecture-patterns スキルの概要

architecture-patterns スキルは何のためのものか

architecture-patterns スキルは、Clean Architecture、Hexagonal Architecture、Onion Architecture、Domain-Driven Design など、実績のある構造パターンを軸に、エージェントがバックエンドコードを設計・リファクタリングするのを支援します。単にパターン名を挙げるだけではなく、サービス境界や散らかったモジュールを、依存ルール・インターフェース・テストしやすい分割・責務の境界が明確なレイヤリングへ落とし込むのが、このスキルの本質です。

バックエンドチームとリファクタリングに最適

このスキルは、コード量が増える前に保守しやすい構造を整えたいバックエンドサービス、社内基盤、モジュラーモノリスの開発者に向いています。特に、ビジネスロジックが controller、ORM model、transport code、vendor SDK に混ざっていて、よりテストしやすく進化させやすい設計へ整理したい場合に有効です。

ユーザーが architecture-patterns に期待するもの

architecture-patterns を検討するユーザーの多くは、主に次の4つの成果を求めています。新規サービス向けのきれいな初期構成、既存コードベースを安全に進めるためのリファクタリング方針、マイクロサービス化の前段としての bounded context の整理、そして依存サイクルやフレームワーク依存のドメイン侵食の解消です。一般的な「アーキテクチャを設計して」という曖昧なプロンプトよりも、このスキルの方が有効なのは、パターンの語彙、各レイヤーの責務、実装の形まで具体的に提示してくれるからです。

主な差別化ポイント

architecture-patterns skill の大きな強みは、単一のテンプレートを押し付けず、複数のバックエンドアーキテクチャスタイルを組み合わせて扱える点です。しかも高レベルな概念説明にとどまらず、各レイヤーの具体的な責務、内向きの依存フロー、インターフェース境界、さらに aggregates・value objects・domain events といった DDD の戦術的要素まで踏み込みます。加えて references/advanced-patterns.md には、より現実的なマルチサービス構成やコンテキスト間のパターンが含まれており、採用判断をする際の参考材料として役立ちます。

このスキルが向かないケース

小さな CRUD endpoint だけが必要な場合、フレームワーク専用の starter を探している場合、あるいはフロントエンドの component architecture を考えたい場合には、このスキルは適していません。主な課題がアプリケーション境界やコード構成ではなく、インフラ構成、デプロイ設計、クラウドネットワーク設計にある場合も、相性はあまり良くありません。

architecture-patterns スキルの使い方

architecture-patterns の導入コンテキスト

上流のスキルは SKILL.md 内で単体インストーラーを公開しているわけではなく、wshobson/agents リポジトリの plugins/backend-development/skills/architecture-patterns 配下に含まれています。skills 対応環境では、通常はリポジトリ経由で追加します。例:

npx skills add https://github.com/wshobson/agents --skill architecture-patterns

利用しているエージェント基盤でインポート手順が異なる場合でも、同じリポジトリパスを指定し、スキル名が architecture-patterns と一致していることを確認してください。

最初に読むべきファイル

まず確認したいのは次の2つです。

• plugins/backend-development/skills/architecture-patterns/SKILL.md
• plugins/backend-development/skills/architecture-patterns/references/advanced-patterns.md

最初に SKILL.md を読み、コアとなるパターンの指針と依存ルールを把握してください。bounded context、anti-corruption layer、より大きなサービス構成の具体例が必要になったら references/advanced-patterns.md を読みます。特に2つ目のファイルは、パターン理論を実際に実装可能なリポジトリ構成へ落とし込む助けになるため重要です。

このスキルがうまく機能するために必要な入力

architecture-patterns usage の品質は、渡す境界定義の精度に大きく左右されます。エージェントには次の情報を渡してください。

• サービスまたはモジュールの目的
• 主要なドメイン概念
• 重要な workflow または use case
• 現在の痛みどころ
• 既存の framework と language
• persistence と messaging の制約
• 新規開発か既存コードのリファクタリングか
• チーム所有境界、compliance、latency 要件などの強い制約

この情報がないと、見た目は正しそうでも実行に移せない、抽象的なレイヤー図で終わりがちです。

曖昧な目的を強い architecture-patterns プロンプトに変える

弱いプロンプト:

“Use architecture-patterns for my backend.”

より強いプロンプト:

“Use architecture-patterns for Backend Development on a Python order service. We are refactoring a Django app where business rules live in models and views. Design bounded contexts, propose Clean or Hexagonal layering, define repository interfaces, identify domain entities and value objects, and show where payment gateway and database adapters should live. We need unit tests for use cases without a database and a migration path that avoids a full rewrite.”

このように具体化すると、ドメイン、現状の破綻ポイント、採用したいパターン判断、外部依存、デリバリー上の制約まで含まれるため、出力の質が大きく上がります。

1つのパターンを押し付けず、適切なものを選ぶ

architecture-patterns guide の実践的な使い方は、盲目的な採用ではなくパターン選定にあります。実務では次のように考えるとよいです。

• ビジネスルールを framework から強く隔離したいなら Clean Architecture
• 外部システムとの分離を ports and adapters で表現するのが最も自然なら Hexagonal Architecture
• 同様の内向き依存モデルを、よりシンプルな概念中心で捉えたいなら Onion Architecture
• ドメインの複雑さが高く、言葉の精度が重要なら DDD 要素を導入

ドメインが浅いなら、重い要素は省いて軽い部分だけ使うべきです。単純な CRUD に対する過剰モデリングは、導入時によくある失敗です。

エージェントセッションでの推奨ワークフロー

進め方としては、次の流れが効果的です。

1. ビジネス機能または bounded context を定義する。
2. domain entities、value objects、aggregates、use cases の洗い出しをエージェントに依頼する。
3. 依存関係を整理し、domain・application・adapters・infrastructure の責務分離を依頼する。
4. language と framework に合う目標フォルダ構成を出してもらう。
5. repositories、event publishers、external clients の interface 定義を依頼する。
6. 既存コードがある場合は、リファクタリング手順を依頼する。
7. unit・integration・adapter test の境界設計を依頼する。

一度に「全部設計して」と投げるより、この流れの方が architecture-patterns から得られる価値は大きくなります。

architecture-patterns の利用で期待できる出力

architecture-patterns skill から良い出力が得られると、通常は次の内容が含まれます。

• 提案された layer model
• dependency direction のルール
• domain と use case の境界
• interface または port の定義
• adapter の例
• project structure の提案
• レイヤーごとの testing strategy

これらが十分に出てこない場合、プロンプトが抽象的すぎるか、対象範囲が広すぎる可能性があります。

グリーンフィールドだけでなく、リファクタリングにも使う

architecture-patterns install は出発点にすぎず、実際の価値はリファクタリング時にこそ出ます。既存システムでは、まず現在のファイル群と結合の問題を短く棚卸しし、そのうえで各関心事を domain、use case、adapter、infrastructure のどこに属するか分類させてください。そうすることで、理想図を新規に描くだけでなく、移行可能な手順まで出せるようになります。

実践向けプロンプトテンプレート

次のようなプロンプトが使えます。

“Apply architecture-patterns to this backend module. Context: [service purpose]. Stack: [language/framework]. Current issues: [coupling, test pain, dependency cycles]. Required integrations: [DB, queue, third-party APIs]. Deliverables: proposed architecture style, layer responsibilities, folder structure, interfaces/ports, test strategy, and incremental refactor plan. Prefer decisions that fit our current codebase rather than a rewrite.”

注意したい制約とトレードオフ

このスキルは概念面では非常に強力ですが、フレームワーク専用のコードジェネレーターではありません。Spring Boot、NestJS、FastAPI、Rails、その他のエコシステムへ合わせるには、追加のフォローアッププロンプトが必要になることがあります。また、一定の抽象化コストを払ってでもアーキテクチャ規律を保つ価値がある、という前提にも立っています。単純な endpoint を最速で出すことだけが目的なら、提案される構造は重く感じられる可能性があります。

architecture-patterns スキル FAQ

architecture-patterns は初心者にも向いていますか？

はい。ただし、controllers、services、repositories、tests といった基本的なバックエンド概念をすでに理解している場合に向いています。実績あるパターンを学ぶ導線としては十分わかりやすい一方で、完全な初学者にとっては、パターンの言葉を実際の framework コードに置き換える追加サポートが必要になることがあります。

普通のアーキテクチャプロンプトより良いですか？

多くの場合は良いです。汎用的なプロンプトだと、「関心を分離する」「services を使う」といった曖昧な助言で終わりがちです。architecture-patterns skill なら、名前のあるパターン、依存方向、domain boundary、テストしやすい分割まで示してくれるため、実装にもレビューにもつなげやすくなります。

architecture-patterns はモノリスにも使えますか？

はい。実際には、初期の microservices より modular monolith でこそ価値が高いことも少なくありません。bounded contexts と内向き依存を使ってモノリスを整理しておけば、そもそもサービス分割が必要かどうかを後から冷静に判断できます。

Domain-Driven Design は必須ですか？

いいえ。DDD はこのスキルの一部ですが、すべてのプロジェクトで完全な戦術モデリングが必要なわけではありません。レイヤリングや ports-and-adapters のガイダンスだけ使うこともできます。aggregates、value objects、domain events は、ドメインの複雑さに見合うときだけ持ち込めば十分です。

framework 依存の強いスタックでも architecture-patterns は使えますか？

はい。ただし、調整作業は前提になります。このスキルは意図的に framework-agnostic に作られているため、きれいな境界を作りやすい反面、使っている framework の慣習や dependency injection model にどう対応させるかは、明示的に確認する必要があります。

どんなときに architecture-patterns を使うべきではありませんか？

問題の中心が UI architecture、cloud infrastructure layout、あるいはビジネスロジックの少ない小規模な CRUD 機能である場合、architecture-patterns は使わない方がよいです。そのようなケースでは、抽象化のコストが得られるメリットを上回りやすくなります。

architecture-patterns スキルをより良く使う方法

スキルに与える境界をもっとシャープにする

architecture-patterns の結果を最も手早く改善する方法は、ドメイン境界をより具体的に定義することです。Order service でも通りますが、order placement, payment authorization, inventory reservation, and shipment initiation の方がはるかに良いです。境界が明確になるほど、entities、use cases、adapters の切り分けが正確になります。

現在の結合問題を見せる

リファクタリングの場合は、たとえば次のような具体例を含めてください。

• controllers に business rules が入っている
• ORM models がメール送信している
• use cases が framework classes を import している
• domain logic の実行に live database が必要
• application layer 間で circular imports が起きている

こうした情報があると、一般論のベストプラクティスではなく、今ある問題に効く構造改善を狙いやすくなります。

実装順で出力を依頼する

アーキテクチャ説明自体はきれいでも、実行手順が出てこないことはよくあります。これを防ぐには、次の順で結果を求めてください。

1. bounded contexts
2. layer responsibilities
3. ports/interfaces
4. folder structure
5. refactor sequence
6. test plan

この順序にすると、architecture-patterns guide が実際の開発に使いやすくなります。

トレードオフを踏まえた提案を強制する

Clean、Hexagonal、Onion、あるいは選択的な DDD のどれが自分のケースに最適なのか、理由付きで説明させてください。これにより、パターンの形だけを真似る cargo-cult を避けられます。追加すると有効な一文は次のとおりです。“Prefer the lightest architecture that preserves testability and clear boundaries.”

システムのスコープが広がったら advanced reference を使う

より大きなシステムでは、bounded contexts、anti-corruption layers、multi-service structures の例を見るために、references/advanced-patterns.md を参照するよう明示的に依頼してください。特に legacy systems や複数ドメインと連携するサービスでは重要です。

architecture-patterns 利用時によくある失敗パターン

よくある問題は次のとおりです。

• ドメイン文脈が不足している
• 1回でシステム全体を再設計しようとする
• すべての概念を bounded context として扱ってしまう
• 明確な use case がないまま repository interfaces を作る
• framework types を domain layer に持ち込む
• 単純な CRUD 領域でも DDD パターンを使いすぎる

これらはスキル単体の欠点というより、入力品質やスコープ設定のミスマッチから起きることがほとんどです。

最初の出力で止まらず、反復する

最初のアーキテクチャ案で終わらせないでください。たとえば次のようなフォローアップが有効です。

• “Which dependencies still violate inward flow?”
• “What can stay simple CRUD instead of full DDD?”
• “Show a migration plan from current files to target layers.”
• “Which interfaces are essential now, and which can wait?”
• “How should tests differ for domain, use case, and adapter layers?”

この2ラウンド目で、architecture-patterns for Backend Development は実装可能なレベルまで具体化しやすくなります。

architecture-patterns を実リポジトリの証拠と組み合わせる

小さな file tree、代表的な classes、あるいは1つの問題 workflow を貼ると、結果はかなり良くなります。このスキルは、理論を実際のコード境界へ対応づけるときに最も力を発揮します。代表的なコードが 20〜50 行あるだけでも、アーキテクチャ提案の質は大きく変わります。