architecture-patterns

アーキテクチャパターン

クリーンアーキテクチャ、バックエンドのレイヤー分離、プロジェクト構成の規約、テスト基準を網羅した、統合済みのアーキテクチャ検証・適用パターンです。各カテゴリには、オンデマンドで読み込まれる個別のルールファイルが rules/ にあります。廃止されたリファレンスチュートリアルから救出した、プロジェクト固有の教訓や日付付きの決定事項は references/ork-delta.md に記載しています。チュートリアル自体は上流の担当です（下記「上流のカバレッジ」を参照）。

クイックリファレンス

カテゴリ	ルール	影響度	使用する場面
クリーンアーキテクチャ	3	高	SOLID の原則、ヘキサゴナルアーキテクチャ、ポート＆アダプター、DDD
プロジェクト構成	2	高	フォルダー規約、ネストの深さ、インポートの方向、バレルファイル
バックエンドのレイヤー	3	高	ルーター／サービス／リポジトリの分離、DI、ファイル命名
テスト基準	3	中	AAA パターン、命名規約、カバレッジのしきい値
適正な規模	2	高	アーキテクチャのティア選択、過剰設計の防止、コンテキストを考慮した適用

合計：5 カテゴリにわたる 13 のルール

クイックスタート

# Clean Architecture: Dependency Inversion via Protocol
class IUserRepository(Protocol):
    async def get_by_id(self, id: str) -> User | None: ...

class UserService:
    def __init__(self, repo: IUserRepository):
        self._repo = repo  # Depends on abstraction, not concretion

# FastAPI DI chain: DB -> Repository -> Service
def get_user_service(db: AsyncSession = Depends(get_db)) -> UserService:
    return UserService(PostgresUserRepository(db))

# Project Structure: Unidirectional Import Architecture
shared/lib  ->  components  ->  features  ->  app
(lowest)                                    (highest)

# Backend Layers: Strict Separation
Routers (HTTP) -> Services (Business Logic) -> Repositories (Data Access)

クリーンアーキテクチャ

保守しやすいバックエンドを実現するための SOLID の原則、ヘキサゴナルアーキテクチャ、ポートとアダプター、DDD の戦術的パターンです。

ルール	ファイル	主なパターン
ヘキサゴナルアーキテクチャ	rules/clean-hexagonal.md	ドライビング／ドリブンポート、アダプターの実装、レイヤー構造
SOLID と依存関係ルール	rules/clean-dependency-rule.md	プロトコルベースのインターフェース、依存性逆転、FastAPI DI
DDD の戦術的パターン	rules/clean-ports-adapters.md	エンティティ、値オブジェクト、集約ルート、ドメインイベント

設計レビュー用チェックリスト：checklists/solid-checklist.md。ドメインエンティティのひな形：scripts/domain-entity-template.py。

主な決定事項

決定事項	推奨
Protocol と ABC のどちらを使うか	Protocol（構造的型付け）
Dataclass と Pydantic のどちらを使うか	ドメインには Dataclass、API には Pydantic
リポジトリの粒度	集約ルートごとに 1 つ
トランザクション境界	リポジトリではなくサービスレイヤー
イベントの発行	集約内で収集し、コミット後に発行

プロジェクト構成

機能ベースの構成、ネストの最大深度、一方向のインポート、バレルファイルの防止について説明します。

ルール	ファイル	主なパターン
フォルダー構造とネスト	rules/structure-folders.md	React／Next.js および FastAPI の構成、最大 4 階層のネスト、バレルファイルのルール
インポートの方向と配置	references/structure-import-direction.md	一方向のインポート、機能間の依存防止、コンポーネント／フックの配置

違反を阻止するルール

ルール	チェック項目
ネストの最大深度	src/ または app/ から最大 4 階層
バレルファイルの禁止	index.ts による再エクスポートは禁止（ツリーシェイキングの問題を防ぐため）
コンポーネントの配置	React コンポーネントは components/ または features/ のみに配置
フックの配置	カスタムフックは hooks/ または features/*/hooks/ のみに配置
インポートの方向	一方向：shared -> components -> features -> app

バックエンドのレイヤー

ルーター／サービス／リポジトリのレイヤー分離と、違反を阻止する検証を備えた FastAPI のクリーンアーキテクチャです。

ルール	ファイル	主なパターン
レイヤー分離	rules/backend-layers.md	ルーター／サービス／リポジトリの境界、禁止パターン、非同期ルール
依存性注入	rules/backend-di.md	Depends() の連鎖、禁止される DI パターン、違反の検出
ファイル命名と例外	rules/backend-repository.md	命名規約、非同期ルール、ドメイン例外

このカテゴリに関するプロジェクト固有の教訓（例外から HTTP ステータスへの対応表、インポートレベルの違反を検索する grep、DI オーバーライドのティアダウン）：references/ork-delta.md。

レイヤーの境界

レイヤー	責務	禁止事項
ルーター	HTTP 関連の処理、リクエストの解析、認証チェック	データベース操作、ビジネスロジック
サービス	ビジネスロジック、検証、オーケストレーション	HTTPException、Request オブジェクト
リポジトリ	データアクセス、クエリ、永続化	HTTP 関連の処理、ビジネスロジック

テスト基準

AAA パターン、命名規則、分離、カバレッジしきい値に関するテストのベストプラクティスです。

ルール	ファイル	主なパターン
AAA パターンと分離	rules/testing-aaa.md	Arrange-Act-Assert、テストの分離、パラメーター化テスト
命名規則	references/testing-naming-conventions.md	Python と TypeScript で、動作に焦点を当てた説明的な名前を付ける
カバレッジと配置	rules/testing-coverage.md	カバレッジしきい値、フィクスチャのスコープ、および（references/ork-delta.md に従った）同じ場所に配置しないルール

カバレッジ要件

領域	最低値	目標
全体	80%	90%
ビジネスロジック	90%	100%
クリティカルパス	95%	100%
新規コード	100%	100%

適切な規模の選択

コンテキストに応じたバックエンドアーキテクチャの適用です。scope-appropriate-architecture で検出されたプロジェクトのティアに応じて、ルールの厳格さを調整します。

適用手順：

1. scope-appropriate-architecture のコンテキストからプロジェクトのティアを読み取ります（ブレインストーミング／実装のステップ 0 で設定）。
2. ティアが設定されていない場合は、Read("rules/right-sizing-tiers.md") のシグナルを使って自動検出します。
3. ティア別の適用マトリクスを適用し、検出されたティアで OFF とマークされたルールはスキップします。
4. セキュリティルールはティアに依存しません — SQL のパラメーター化、入力検証、認証チェックを常に適用します。

ルール	ファイル	主なパターン
アーキテクチャの規模のティア	rules/right-sizing-tiers.md	面接／MVP／本番／エンタープライズの規模マトリクス、LOC の見積もり、検出シグナル
適切な規模を選ぶための判断ガイド	rules/right-sizing-decision.md	ティアごとの ORM、認証、エラー処理、テストに関する推奨事項、過剰設計のコスト

ティア別のルール適用

ルール	面接	MVP	本番	エンタープライズ
レイヤー分離	OFF	WARN	BLOCK	BLOCK
リポジトリパターン	OFF	OFF	WARN	BLOCK
ドメイン例外	OFF	OFF	BLOCK	BLOCK
依存性注入	OFF	WARN	BLOCK	BLOCK
OpenAPI ドキュメント	OFF	OFF	WARN	BLOCK

手動オーバーライド： ユーザーはティアを明示的に設定して、自動検出を回避できます（例：「スキルを示すため、この持ち帰り課題にはエンタープライズのパターンを使いたい」）。

判断フローチャート

Is this a take-home or hackathon?
  YES --> Flat architecture. Single file or 3-5 files. Done.
  NO  -->

Is this a prototype or MVP with < 3 months runway?
  YES --> Simple layered. Routes + services + models. No abstractions.
  NO  -->

Do you have > 5 engineers or complex domain rules?
  YES --> Clean architecture with ports/adapters.
  NO  --> Layered architecture. Add abstractions only when pain appears.

使用すべきでない場合

すべてのプロジェクトにアーキテクチャパターンが必要なわけではありません。プロジェクトのティアに合わせて複雑さを調整してください。

パターン	面接	ハッカソン	MVP	成長期	エンタープライズ	よりシンプルな代替案
リポジトリパターン	過剰（約200 LOC）	過剰	境界線上	適切	必須	サービス内で ORM を直接呼び出す（約20 LOC）
DI コンテナー	過剰（約150 LOC）	過剰	最小限のみ	適切	必須	コンストラクターパラメーターまたはモジュールレベルのシングルトン（約10 LOC）
イベント駆動アーキテクチャ	過剰（約300 LOC）	過剰	過剰	選択的	適切	サービス間で関数を直接呼び出す（約30 LOC）
ヘキサゴナルアーキテクチャ	過剰（約400 LOC）	過剰	過剰	境界線上	適切	インポートを使ったフラットなモジュール（約50 LOC）
厳格なレイヤー分離	過剰（約250 LOC）	過剰	警告	ブロック	ブロック	同じファイルにルートとモデルを置く（約40 LOC）
ドメイン例外	過剰（約100 LOC）	過剰	過剰	ブロック	ブロック	組み込みの ValueError／HTTPException（約5 LOC）

経験則： 検出されたティアでパターンが「過剰」と示されている場合は、そのパターンを使わないでください。よりシンプルな代替案を使います。ヘキサゴナルアーキテクチャを使った持ち帰り課題は、スキルではなく過剰設計を示します。

アンチパターン（禁止）

# CLEAN ARCHITECTURE
# NEVER import infrastructure in domain layer
from app.infrastructure.database import engine  # In domain layer!

# NEVER leak ORM models to API layer
@router.get("/users/{id}")
async def get_user(id: str, db: Session) -> UserModel:  # Returns ORM model!

# NEVER have domain depend on framework
from fastapi import HTTPException
class UserService:
    def get(self, id: str):
        raise HTTPException(404)  # Framework in domain!

# PROJECT STRUCTURE
# NEVER create files deeper than 4 levels from src/
# NEVER create barrel files (index.ts re-exports)
# NEVER import from higher layers (features importing from app)
# NEVER import across features (use shared/ for common code)

# BACKEND LAYERS
# NEVER use database operations in routers
# NEVER raise HTTPException in services
# NEVER instantiate services without Depends()

# TEST STANDARDS
# NEVER mix test files with source code
# NEVER use non-descriptive test names (test1, test, works)
# NEVER share mutable state between tests without reset

上流の網羅範囲（再掲しないでください）

以下のトピックに関する長文のチュートリアルは、このスキルから削除されました（2026-07-31 の wrap-plus-delta キャンペーン）。一次情報源を参照してください。ここには基礎、失敗から得た知見、独自の判断のみを記載します（references/ork-delta.md を参照）。

トピック	一次情報源
ヘキサゴナルアーキテクチャ、ポートとアダプターの解説	Alistair Cockburn、https://alistair.cockburn.us/hexagonal-architecture/ および Architecture Patterns with Python、https://www.cosmicpython.com/
SOLID 原則のチュートリアル（Protocol ベース）	Architecture Patterns with Python、https://www.cosmicpython.com/ および Python Protocol 仕様、https://typing.python.org/en/latest/spec/protocol.html
DDD の戦術的パターン（エンティティ、値オブジェクト、集約、ドメインイベント）	Architecture Patterns with Python、https://www.cosmicpython.com/
FastAPI の依存性注入、認証依存関係、DI テストオーバーライド	FastAPI ドキュメント（context7: /tiangolo/fastapi）、https://fastapi.tiangolo.com/tutorial/dependencies/ およびスキル ork:python-backend
ルーター／サービス／リポジトリレイヤーの解説	FastAPI の大規模なアプリケーション、https://fastapi.tiangolo.com/tutorial/bigger-applications/ およびスキル ork:python-backend
FastAPI のクリーンアーキテクチャを採用した完全なサンプルアプリ	FastAPI フルスタックテンプレート、https://github.com/fastapi/full-stack-fastapi-template
Next.js のフォルダーレイアウトと構造違反の一覧	Next.js のプロジェクト構造に関するドキュメント、https://nextjs.org/docs/app/getting-started/project-structure（スキル vercel:nextjs）
AAA パターン、分離、パラメーター化テスト、フィクスチャのスコープ、カバレッジ設定	スキル ork:testing-unit、pytest ドキュメント、https://docs.pytest.org/en/stable/ および Vitest のカバレッジ、https://vitest.dev/config/#coverage

関連スキル

• ork:scope-appropriate-architecture - プロジェクトのティアを検出し、適正規模を保つためのルールに反映します
• ork:quality-gates - YAGNI ゲートでティアのコンテキストを使い、複雑さを検証します
• ork:distributed-systems - 分散ロック、レジリエンス、冪等性のパターン
• ork:api-design - REST API の設計、バージョニング、エラー処理
• ork:testing-unit - 単体テスト：AAA パターン、フィクスチャ、モック、ファクトリー
• ork:testing-e2e - E2E テスト：Playwright、ページオブジェクト、ビジュアルリグレッション
• ork:testing-integration - 統合テスト：API エンドポイント、データベース、コントラクト
• ork:python-backend - FastAPI、SQLAlchemy、asyncio のパターン
• ork:database-patterns - スキーマ設計、クエリー最適化、マイグレーション