mcpField
A
architecture

architecture

github.com/liaoann開発044 回インストール4 週間前に更新
リポジトリ

architecture について

成長するコードベースを整理しやすく保つための、開発者向けアーキテクチャスキルです。ドメイン単位の構成、明確なモジュール境界、非循環依存、薄いトランスポート層、リクエスト経路上の認可を重視します。

主な機能

  1. 01ドメイン単位でのコード編成
  2. 02公開 API を介した連携
  3. 03依存グラフの非循環化
  4. 04トランスポート処理の簡素化
  5. 05リクエスト経路上での認可

活用シーン

  1. 01新機能のディレクトリ構成の計画
  2. 02モジュール間の内部参照の削減
  3. 03依存関係の循環の特定と解消
  4. 04ハンドラー処理と認可位置の確認

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/liaoann/skills --skill architecture

インストール後、Claude Code で/architectureを入力して読み込まれたか確認します。

詳細

アーキテクチャ

コードベースの成長に伴って、構造を把握しやすく保つための原則です。プロジェクト独自の規約に沿って適用してください。これらはデフォルトの指針であり、すでに文書化されたリポジトリ構成を上書きするものではありません。

レイヤーではなくドメインごとに整理する

コードは、それが担う機能ごとにまとめます。そうすることで、1つの機能を1か所を調べるだけで理解できます。

features/
  bookings/      ← services, data access, UI, tests for bookings
  availability/  ← services, data access, UI, tests for availability

1つのドメインに関する変更が複数のディレクトリに分散する場合は、トップレベルに技術レイヤー（controllers/、services/、repositories/）を設けるのは避けてください。機能内に技術的なサブフォルダーを設けるのは、その機能の構造を把握しやすくなるのであれば問題ありません。

パブリック API を介して連携する

ある機能から別の機能をインポートするときは、必ずパブリックエントリーポイントを通し、内部ファイルを直接参照しないでください。

// ❌ reaching into internals
import { calculateSlots } from "features/availability/services/internal/slotCalculator";

// ✅ through the public API
import { getAvailability } from "features/availability";

ドメインに依存しないユーティリティ（ロギング、認証、汎用ヘルパー）は共有の低レベルモジュールに配置し、共有 UI プリミティブは共有 UI モジュールに配置してください。ツールチェーンで可能な場合は、リンタールールによってインポート境界を強制してください。

依存関係グラフを非循環に保つ

依存関係は、低レベルの共有コードから高レベルのアプリケーションエントリーポイントへと、一方向に流れるようにしてください。

shared utils → shared domain modules → features → transport/API → app entry

低レイヤーから高レイヤーをインポートしてはいけません。機能をインポートするユーティリティや、相互にインポートし合う2つの機能は循環依存です。これはビルドエラーや型エラーを引き起こし、依存関係を正しく反映しない構造につながります。共有する部分を下位レイヤーに切り出して、循環依存を解消してください。

通信層を薄く保つ

HTTP ハンドラー、RPC ルーター、CLI コマンド、キューコンシューマー、UI イベントハンドラーは、デリバリーの仕組みです。入力を検証し、アプリケーションデータに変換して、ドメインまたはアプリケーションのコードを呼び出し、結果を外部向けに変換する役割にとどめてください。

ビジネス上の判断、永続化の詳細、複雑なオーケストレーションが通信境界に蓄積しないようにしてください。同じ動作を別の通信経路でも必要とする場合は、ドメイン側のインターフェースの背後に移してください。

リクエスト経路上に認可を配置する

これは、このスキルにおけるほかの配置判断と同じです。ガードは、実際に保護する境界に配置してください。適用されるはずだと思い込んでいても、保証されない1つ外側の層に置いてはいけません。

すべてのリクエストが通過することを確実に証明できる経路、つまりリソース自体を保護するハンドラーに認可チェックを配置してください。共通の外側の枠組み（継承されたレイアウト、ラップするデコレーター、一部のエントリーポイントでは通らないミドルウェア）は、リクエストがそこを通らずに保護対象のリソースに到達できる場合、回避可能です。制限されたデータを読み取る前に、本人確認とロールの確認を行い、デフォルトで拒否するフェイルクローズの方針にしてください。認可されていない場合は、拒否するか、リダイレクトするか、早期に処理を終了してください。

完了条件

変更が既存の境界を尊重していることが条件です。新しいファイルは、それが担う機能に合わせて配置されていること、モジュールをまたぐインポートはパブリックエントリーポイントを経由すること、インポートによって循環依存や低レイヤーから高レイヤーへの依存が生じないこと、通信処理が薄く保たれていること、認可チェックが回避可能なラッパーではなく保護対象のリクエスト経路上に配置されていることが求められます。1つでも違反があれば、条件を満たしていません。

コメント

Markdown 対応