define-architecture

アーキテクチャを定義する

TypeScript のフルスタックアプリ向けに、長く使えて変更しやすいアーキテクチャの既定値を定義し、強制力のあるアーキテクチャ概要を作成します。

• 該当する用途： フォルダー構成、モジュールの契約、ミドルウェアのパイプライン、フロントエンドとバックエンドの境界、アーキテクチャ概要、既存コードベースのドメインに基づく深化、エージェントに適したコードベースのガードレール。
• 該当しない用途： 新しいリポジトリのスキャフォールディング（Next.js のターボレポには scaffold-nextjs、TypeScript CLI には scaffold-cli）、マルチテナントのドメイン／分離／ルーティング（multi-tenant-architecture）、ローカルの差分の構造的なレビュー（pr-reviewer）。

目次

• ワークフローとリファレンス
• セットアップワークフロー（新しいコードベース）
• 導入ワークフロー（既存のコードベース）
• 検証ループ
• 出力テンプレート
• 関連スキル
• 注意点

ワークフローとリファレンス

次のチェックリストに沿って進めます。

Architecture progress:
- [ ] Step 1: Pick workflow (new codebase: Setup; existing: Adoption)
- [ ] Step 2: Run it end to end
- [ ] Step 3: Write the brief (Output template)
- [ ] Step 4: Run Validation loop, record results in brief
- [ ] Step 5: Fix failed checks, re-run loop

該当する場合にのみ、リファレンスを読み込みます。

リファレンス	読むタイミング
references/stack-defaults.md	ライブラリ、ツール、デプロイ先を選ぶとき
references/api-design.md	エンドポイント、モジュールの契約、リクエストコンテキストを設計するとき、または API の公開範囲の変更をレビューするとき
references/distributed-correctness.md	外部システムを呼び出すフロー、Webhook を処理するフロー、再試行が必要なフロー、監査証跡が必要なフロー、または金銭（請求、クレジット、支払い）を扱うフローを設計するとき
references/deepening-existing.md	導入ワークフローを実施するとき（ドメインのマッピング、機会パターン、出力テンプレート）
references/craftsmanship.md	チームの規約、テスト、品質基準のセクションを記述するとき
references/agent-friendly-codebase.md	コーディングエージェント向けにコードベースを整えるとき：ガードレール用ツール、不変条件の段階的強化、レガシーマーカー、生成されたコントラクト、検証レベル
references/shipping-practices.md	ロールアウトとロールバックのセクションを記述するとき

セットアップワークフロー（新規コードベース）

1. まず制約を明確にします。プロダクトのスコープ、チームの規模、コンプライアンス／セキュリティ、想定規模、デプロイ先、必要な連携、品質基準を定めます。
2. リポジトリの構成を選びます。
   • apps/ はデプロイ可能なアプリケーション（api、web、admin）に使用します。
   • packages/ は共有ライブラリ（shared、ui、icons、auth、proto）に使用します。
3. バックエンドのモジュール契約を定義し、それぞれに適用する仕組み（lint の境界ルールまたは型チェック）を明記します。
   • handler：トランスポートのみを担当します。
   • service：ビジネス処理のオーケストレーションを担当します。
   • dao：データベースアクセスのみを担当します。
   • mapper：DB／proto／ドメイン間の変換を担当します。
   • constants と types：モジュール内の契約を定義します。
4. リクエストコンテキストとミドルウェアを定義します。
   • tenantId、userId、traceId を AsyncLocalStorage による RequestContext で保持し、すべてのエントリーポイント（RPC、HTTP、ジョブ、CLI）で初期化して、getContext() で読み取ります。ビジネス関数に ctx パラメーターを渡してはいけません。実装については references/api-design.md を参照してください。
   • RPC メソッドの登録時に、メソッドごとの認証ポリシーを明示的に指定することを必須にします。ポリシーのないメソッドは登録に失敗させ、オープンな設定をデフォルトにしてはいけません。
   • 認証、ログ、エラー、コンテキストは共有ミドルウェアにまとめ、各ハンドラーのコードに含めないでください。
5. フロントエンドの境界を定義します。
   • Server Components をデフォルトとし、インタラクティブ性が必要なリーフコンポーネントに限って "use client" を追加します。
   • サーバー状態には TanStack/Connect Query、クライアント状態にはコンポーネントの状態を使います。どちらにも当てはまらない横断的なクライアント状態に限り、MobX を使用します。
   • それぞれのデータの所有者は必ず一つにします。サーバーのデータを useState に複製したり、useEffect で二つのストアを同期したりしてはいけません。どちらもデータの所有権が不明確であることを示す危険信号です。
6. テストとリリース：
   • 単体テストでは DB を使わず、統合テスト／E2E テストは動的に生成した ID を使って並列実行し、実行間でフィクスチャが衝突しないようにします。
   • 変更ごとにロールバック計画を用意し、小さく、完全で、元に戻せる垂直スライスでリリースします。
   • 信頼性、エラーパス、可観測性、ユーザー向けの状態まで対応して初めて、スライスは完成です。後の仕上げ作業に先送りしてはいけません。
7. エージェント向けのガードレール：デッドコード、重複、境界、ファイルサイズのチェックを、references/agent-friendly-codebase.md に従って pre-commit と CI に組み込みます。

導入ワークフロー（既存コードベース）

目標は、書き換えではなく、ドメインを踏まえて設計を深めることです。分析手法、改善の機会となるパターン、出力テンプレートについては references/deepening-existing.md を読み込んでください。

1. ドメインの用語と判断を把握します。 CONTEXT.md、docs/adr/、または存在する場合は同等のローカル資料を読み、その後、チームが名付けているエンティティ、アクション、境界づけられたコンテキストについてコードを読みます。用語の不一致（1つの概念に3つの名前、または1つの名前に3つの概念）を記録します。
2. 設計を深める機会を探します。 貧血な概念、浅いモジュール、境界からの漏れ、命名の不一致、概念の重複、プリミティブ執着、ロジックの配置ミス、公開インターフェースを越えないとテストできない箇所を探します。曖昧な違和感ではなく、それぞれの箇所をファイルパスとともに記録します。
3. 効果の大きさで優先順位を付けます。 削除テストに合格し、将来の変更箇所を明確に局所化でき、変更頻度が低く、現行要件を満たし、実現可能なテストの境界を持つ改善機会を優先します。対象インターフェースを設計する前に候補の順位を決め、推測に基づく整理は除外します。
4. まず垂直スライスを一つ移行します。 最も効果の大きい改善を一般化する前に、スライス一つを通してエンドツーエンドで実証します。
5. ガードレールを追加します。 lint、型チェック、テストによって新しい境界を適用し、劣化を防いでから、モジュールごとに展開します。エージェント向けのガードレール（デッドコード、重複、レガシーマーカー、ファイルサイズ上限）については references/agent-friendly-codebase.md を読み込んでください。

検証ループ

最終確定前に実行し、結果をブリーフの「未解決のリスク」に記録します。各チェックには証拠が必要です。「一貫しているように見える」だけでは合格になりません。

1. 一貫性： 命名、モジュール境界、ミドルウェアのルールが、すべてのサービスで同じように記述されていること。証拠：矛盾のスキャンで該当事項がゼロであること。
2. 強制可能性： すべての契約に、対応する lint ルール、型チェック、またはテストが記載されていること。証拠：契約ごとに強制方法を示す列または注記があること。
3. 運用可能性： デプロイ可能な各対象に、オブザーバビリティ、ヘルスチェック、ロールバック手順があること。証拠：ロールアウトのセクションで、それぞれが明記されていること。
4. 品質ゲート（コードが変更された場合のみ。例：Adoption のスライス）： リポジトリの lint、型チェック、対象を絞ったテスト（npm run lint、npm run check-types、npm run test --workspace=<pkg>、または同等のコマンド）を実行します。証拠：出力がすべて成功していること。

失敗した場合：ブリーフまたは規約を修正してから、ループを再実行します。

出力テンプレート

次の構成を使用します。

# Architecture brief

## Context and constraints
## Repo shape
## Backend module contracts
## Request context and middleware policy
## Frontend boundaries
## Testing strategy
## Quality bar and surface-area budget
## Rollout and rollback plan
## Open risks and follow-ups

関連スキル

• scaffold-nextjs または scaffold-cli：ブリーフの合意後にリポジトリをスキャフォールドします。
• multi-tenant-architecture：テナントの識別、分離、ドメイン戦略。
• pr-reviewer：実装後、ローカルの差分を構造面からレビューします。
• planning：Adoption の機会を実装計画に落とし込み、ストレステストします。
• agents-md：AGENTS.md ファイル自体を監査・リファクタリングします。このスキルでは、代わりにツールで対応すべき内容を判断します。
• tidy：差分の範囲に絞ったクリーンアップパス。references/agent-friendly-codebase.md では、こうしたパスを小規模に保つためのリポジトリ全体のガードレール設定を説明しています。

注意点

• 5 人未満のチームでは、マイクロサービスを安易に採用しないでください。サービスを増やすたびに、デプロイパイプライン、契約のバージョニング、オンコール対応の負担が増えます。まずはモジュール型モノレポから始め、チームまたは規模の制約によって境界が明確になってから分割します。
• モノレポのルート package.json にアプリレベルの依存関係を置かないでください。依存関係のホイスティングによって宣言漏れが隠れ、アプリがローカルではビルドできても、単独でデプロイすると失敗します。各アプリが自分の依存関係を管理します。
• 強制手段なしにモジュールの契約（handler/service/dao）を定義しないでください。強制されない契約は、最初の締め切りで形骸化します。契約を書いたその日に、インポート境界の lint ルール（例：dao は handler をインポートできない）を追加します。
• AsyncLocalStorage の代わりに、ビジネス関数へ ctx パラメーターを渡さないでください。すべてのシグネチャが肥大化し、後からフィールドを 1 つ追加するだけで何百もの呼び出し箇所を変更することになります。
• ページまたはレイアウトのレベルに "use client" を置かないでください。サブツリー全体がクライアントレンダリングになり、ストリーミングとサーバーからの直接データアクセスが失われます。葉のコンポーネントに限定します。
• Adoption の最中に大規模な一括書き換えを提案しないでください。まず垂直スライスを 1 つ移行して検証し、その後に一般化します。
• 早い段階で packages/ に切り出さないでください。同じコードを必要とするアプリが 3 つ以上になるまで待ちます。時期尚早な共有パッケージは、リリースサイクルを無用に結び付けます。
• 変更ごとのロールバック計画なしにブリーフを最終確定しないでください。取り消せない決定には、リリース前に文書化されたフォールバックが必要です。
• アウトボックス（または CDC）を使わずに、データベースとキュー／Webhook へ二重書き込みしないでください。一方のコミット後にもう一方が失敗すると、通知がひそかに失われたり、捏造されたりします。references/distributed-correctness.md を参照してください。
• 外部から強制されうる不変条件を、構造によって強制しないでください（符号なし型、厳格な CHECK など）。外部要因によって状態を強いられたとき、システムがクラッシュしたり値を丸めたりするのではなく、その状態を記録できるようにします。状態を表現し、事後に検出して、明示的に復旧します。
• リンターで決定論的に強制できる内容を AGENTS.md に記述しないでください。プロンプトのルールはコンテキストの制約で形骸化しますが、pre-commit と CI の終了コードはそうなりません。
• 現行のパターンの隣に、印のないレガシーコードを残さないでください。エージェントは grep で探し、古いエンドポイントを最初に見つけて、それを基に実装してしまいます。grep 可能な LEGACY コメントを付けるか、削除してください（references/agent-friendly-codebase.md を参照）。