domain-organization

ドメインの整理

ソースコードは 所有者 → 役割 → モジュール の順に整理します。パスから、誰がその振る舞いを所有し、どの責務を担い、どの概念や操作を含むのかが分かるようにします。モデルとサービスは同じ所有者に属しますが、同じファイルに置く必要はありません。

境界を選ぶ際は codebase-design を適用します。各機能はまとめて保ち、分割するのは理解しやすくなる場合に限ります。役割ディレクトリは有用なモジュールを整理するためのものであり、ヘルパー、クエリ、型、ステップごとに個別のファイルを設ける必要はありません。

これを依頼された範囲に適用します。計画の依頼では計画を作成し、実装の依頼では関連する構造変更が許可されます。このスキル自体は、インストール、依存関係のアップグレード、または別のリポジトリの変更を許可するものではありません。

作業の根拠を確認する

対象リポジトリの指示、パッケージのガイダンス、承認済みの決定事項、マニフェスト、エクスポート／インポートのマップ、検証スクリプトを確認します。役割を割り当てる前に、実際のソースコードと呼び出し元を調べます。既存の計画は設計上の根拠として扱い、その内容にある一覧や実行に関する記述を現在の作業ツリーと照合します。

既存の所有者、公開インターフェース、コンポジションルート、テスト方針、生成入力、フレームワークの命名要件を特定します。確認済みの事実と提案するパスを区別します。プロジェクト全体を対象とする場合は、意図的に変更しない領域も含め、すべてのパッケージとアプリを考慮します。

明示されたユーザーおよびリポジトリの制約を守ります。通常のレイアウト上の判断はコードを根拠に行い、未解決の所有権や契約に関する選択が依頼の結果を大きく左右する場合に限り、質問します。

所有者を選ぶ

• 特定の目的に絞ったパッケージを所有者にできます。src/models/Invoice.ts と src/services/InvoiceStore.ts は同じ所有者に属します。
• 複数の実質的なドメインを持つパッケージでは、まずドメインごとにまとめます。 src/billing/models/Invoice.ts、src/billing/services/InvoiceStore.ts のようにします。
• アプリ固有の画面、ルート、振る舞いはアプリ内に置きます。 再利用可能な UI は独自のパッケージに置きます。そのパッケージ名とエイリアスはワークスペースから確認します。アプリのルート、ストア、API クライアントはそのパッケージに含めません。
• 共有インフラストラクチャは、実際の所有者と呼び出し元に基づいて配置先を決めます。名前が似ているだけでは、機能を統合したり別のパッケージを作成したりする根拠になりません。
• ドメインの models/ と AI モデルプロバイダー機能を区別します。後者は inference/ や providers/ など、実際の責務に沿った名前を使い、公開契約を黙って変更しないようにします。

パッケージは公開インターフェースを小さく保った、深いモジュールとして維持します。型やサービスごとにパッケージを作成しないでください。役割ディレクトリを作成するのは、その中に置く有用なコードがある場合に限ります。既存の明確な役割を保ち、空の足場を作成しないでください。

責務に応じて役割を割り当てる

役割	内容と境界
models/	スキーマ、派生型、ID、値オブジェクト、および密接に関連する純粋な操作。スキーマとその派生型は一緒に配置します。
services/	名前付きの機能と、必要なインターフェースに対する操作。コンポジションを通じて具体的な実装を受け取ります。
adapters/	データベース、HTTP、SDK、ファイルシステム、ホスト、フレームワークの実装、およびプロバイダー固有のデコード。
workflows/	サービスを調整するプロセス。コンポジションルートが具体的なアダプターを選択します。
policies/	ドメインの概念に依存するビジネス上の判断と検証ルール。
mappers/	確立された表現間の、単独でも有用な変換。アダプター内だけで使う行変換は、その操作と一緒に配置します。
utils/	ドメインの契約に依存しない小規模な補助関数。ドメインを考慮したヘルパーは、対応するモデル、ポリシー、またはマッパーに配置します。

コードの説明に役立つ場合は、config/、tools/、prompts/、 components/、hooks/、state/、routes/、runtime/ などの役割を追加します。設定の形状と既定値は、認証情報や実行時のリソース構築とは分けておきます。 アプリのエントリーポイントは薄く保ち、実行時の組み立てはコンポジションルートに配置します。

複数の責務が混在するモジュールは、移動する前に読みます。ファイル名だけでは、関数が純粋であることや、サービスの契約と具体的な実装が分離されていることは保証されません。動作を維持しながら一貫性のある責務に分割し、必要な意味上の変更は別の変更として設計します。

操作の内部ヘルパー、クエリ、バインディング、デコードは、まとめて理解する必要がある場合、その操作内に置きます。意味のある判断を隠蔽する場合や、実際に利用する呼び出し元がある場合はマッパーやヘルパーを共有します。他のファイルを短くすることだけを目的に共有しません。一貫性のあるモジュールについては、設定済みの行数制限を維持し、限定的な例外には理由を記載します。

モジュール名を一貫させる

これらのデフォルトは、ユーザーによる明示的な選択や、リポジトリまたはフレームワークの確立された制約より優先されるものではありません。リポジトリに合わせてオーナーディレクトリの大文字・小文字を統一し、ロールディレクトリは小文字の複数形にします。

種類	デフォルト	例
名前付きモデル、スキーマ、サービス、ツールキット	PascalCase	Invoice.ts、InvoiceStore.ts、BillingTools.ts
名前付きアダプター	PascalCase の語幹。実装を示す小文字のサフィックスは任意	InvoiceStore.postgres.ts
コンポーネントまたは JSX モジュール	PascalCase	InvoiceTable.tsx
関数、ワークフロー、ポリシー、マッパー、ハンドラー	kebab-case	issue-invoice.ts、parse-row.ts
React フック	camelCase	useInvoice.ts
対応するテストまたはフィクスチャ	ソースの語幹に小文字のサフィックスを付ける	InvoiceStore.test.ts、parse-row.fixture.ts

慣例的なファイルは、小文字のまま認識しやすい名前にします。index、app、main、agent、cli、config、errors、constants、types、schemas、fixtures、testing、setup、runtime が該当します。意味を絞り込めるよう、ディレクトリ名を付けます。幅広い概念を扱う types.ts は、役立つ場合には所有する概念ごとに分割します。すべての別名ごとに分割する必要はありません。

PascalCase は名前付きモジュールを示しますが、クラスであることも、エクスポートが一つだけであることも意味しません。関連するスキーマと型の組み合わせ、および有用な関連エクスポートはまとめておきます。ファイルを移動する際は、既存のエクスポート名とサービスの識別情報を維持します。

小文字のドット付きサフィックスで、実装とテストのロールを区別します。フレームワークのルート、設定ファイル、宣言ファイル、マイグレーション番号、SQL、スクリプト、生成された名前やレジストリで管理される名前は、限定的な例外としてそのまま維持します。ロールが異なる通常のヘルパーは、コンポーネントのディレクトリから移動します。

3 つ以上の兄弟実装モジュールで、同じ概念を示すプレフィックスが繰り返されている場合、その概念のサブディレクトリを作成し、ファイル名からプレフィックスを取り除きます。

composer-attachments.ts → composer/attachments.ts
composer-images.ts     → composer/images.ts
composer-text.ts       → composer/text.ts

グループは utils/composer/text.ts のように、オーナーとロールの範囲内に保ち、短くした名前にも上記の大文字・小文字の規則を適用します。数えるのは個別の実装モジュールです。対応するテストとフィクスチャは、ソースの名前に従います。単語が操作そのものを表す parse-row.ts のような、操作を説明する名前は維持します。

公開境界を維持する

パッケージに src/ がある場合は、実装をその中に置き、リポジトリのエクスポートポリシーに沿った、明示的で薄い公開エントリーファイルを使用します。プライベートなツリーをワイルドカードでエクスポートするのではなく、小さなインターフェースを公開します。モデルのみを扱うエントリーから、具体的なアダプターも読み込まないようにしてください。

公開インターフェースは、完全な操作を公開し、その順序、失敗時の処理、クリーンアップを担う必要があります。薄い公開再エクスポートはその境界を確立しますが、内部の転送チェーンは通常、コードの追跡を増やすだけです。外部の実行モデルを変換し、実際のアダプター境界で受信データを検証してください。

対象の互換性ポリシーに従ってください。必要な場合は安定した公開指定子を維持し、廃止すべきパスはすべて削除して、呼び出し元も更新します。包括的な互換性ラッパーを追加しないでください。公開アセットと生成リソースには、ソースファイルの命名規則とは別のエクスポート処理が必要です。

Effect プロジェクトでは、エージェントのインフラストラクチャ型やサービスを定義する前に、インストール済みの Effect Agent コントラクトカタログと公開済みの上流コントラクトを確認してください。上流にコントラクトがある場合はそれをインポートします。組織内の作業を理由に、サンドボックス、耐久性、承認、ワークフローのコントラクトを重複して定義しないでください。

計画または実装

計画、プロジェクト全体の再編成、または段階的な展開を依頼された場合は、references/planning.md を読んでください。再利用可能なプリセットが共有リポジトリにある場合でも、依頼された計画は対象プロジェクトの docs/ に保存します。計画はその成果物の作成で完了です。移動の提案は、実行した証拠にはなりません。

実装が許可されたら、一度に一つずつ、まとまりのある所有単位を移動します。その単位のインポート、公開エクスポート、プライベートエイリアス、ビルドルート、テスト検出、アセットをまとめて更新してください。ソース拡張子はエイリアスの参照先に合わせます。拡張子を付加するマッピングによって、インポートが Invoice.ts.ts にならないようにしてください。大文字小文字だけを変更するリネームでは、必要に応じて中間パスを使用し、Git が確実に変更を記録できるようにします。

実行時の動作、スキーマ、ワイヤ形式、永続化キー、サービスタグ、ツール名、ワークフロー ID は維持してください。移動した公開インターフェースと実行時アセットを検証するには、リポジトリ既存のテストとチェックを使用します。新しいテストツリーを押し付けず、リポジトリのテスト配置ポリシーに従ってください。

ファイル名や依存関係のチェックを評価、追加、または適用済みと主張する場合は、references/enforcement.md を読んでください。選択したチェックを実際に実行し、適用範囲が網羅されていることを確認してから、その範囲が適用済みだと説明してください。変更したパス、検証済みのチェック、残っている不足点、無関係な失敗について、正確なコマンドと最初の対応可能な診断内容を報告してください。