nextjs-architecture

@architecture-rules.md @rules/project-structure.md @rules/services.md @rules/hooks.md @rules/db.md @rules/routes.md @rules/execution-model.md @rules/data-fetching.md @rules/server-actions.md @rules/route-handlers.md @rules/platform.md @rules/validation.md @references/official/nextjs-docs.md @references/official/current-docs-2026-06-02.md @references/official/drizzle-docs.md

Next.js アーキテクチャの適用

<output_language>

この標準スキルファイルが英語で書かれている場合でも、ユーザー向けの成果物、保存された成果物、レポート、計画、生成ドキュメント、要約、引き継ぎメモ、コミット／メッセージの下書き、検証メモは、特に指定がない限り韓国語にします。

ソースコードの識別子、CLI コマンド、ファイルパス、スキーマキー、JSON/YAML のフィールド名、API 名、パッケージ名、固有名詞、引用されたソースの抜粋は、必要な言語または原文の言語のままにします。

別の言語を使用するのは、ユーザーから明示的に指定された場合、既存の対象成果物の一貫性を保つ必要がある場合、または機械可読な仕様で英語のトークンが正確に要求される場合に限ります。ローカライズされたテンプレートやリファレンスがある場合（たとえば *.ko.md または *.ko.json）、ユーザー向けの成果物にはそちらを優先して使用してください。

</output_language>

• リポジトリが Next.js プロジェクトであることを確認し、アーキテクチャルールを適用する前に App Router、Pages Router、または混在モードを特定します。
• ファイル規約、Server/Client Component の境界、データ／キャッシュの動作、Server Actions、Route Handlers、Proxy、環境変数／プラットフォームの安全性に関する公式の Next.js の動作を適用します。
• src/modules/<domain>/、src/services/<domain>/、src/db/<area>/、src/server/<area>/、src/integrations/<provider>/、src/config/<area>/ などのネストされた共有フォルダーに対する Hypercore／リポジトリ固有の規約を適用します。ただし、これらを公式の Next.js の規則として提示しません。
• Drizzle、DAL／サービスの境界、クライアントフックのオーケストレーションについては、エントリーポイントを肥大化させず、専用のルールファイルに振り分けます。
• バージョン依存の公式情報は references/official/ に保持し、コアスキルを簡潔に保ちながら、最新ドキュメントを個別に更新できるようにします。

<routing_rule>

既存の Next.js プロジェクトでのアーキテクチャ適用、実装ガイダンス、レビューにこのスキルを使用します。特に、App Router の作業や移行、Server/Client の境界、キャッシュ／鮮度、Server Actions、Route Handlers、Proxy、環境変数／プラットフォームの安全性、サービス／DAL の境界、クライアントフックのオーケストレーション、Drizzle／DB の配置、ネストされた共有フォルダーの構成に使用します。

一般的な React アーキテクチャ、Remix／TanStack Start のプロジェクト、ドキュメントのみの要約、アーキテクチャ上の境界に触れない文章だけの編集には、簡単な安全性チェックを除き、このスキルを使用しないでください。Pages Router のみを使用するプロジェクトでは、Next.js 共通の安全性／プラットフォームのチェックを適用しますが、移行が依頼されていない限り、App Router 専用のファイル規約を強制しないでください。

</routing_rule>

<instruction_contract>

項目	契約
意図	Next.js プロジェクトのアーキテクチャを安全に保ち、公式ドキュメントおよび明示された Hypercore／リポジトリ内の規約に準拠させます。
トリガー	App Router、Pages Router、Server／Client の境界、データ／キャッシュの挙動、Server Actions、Route Handlers、Proxy、プラットフォーム／環境設定、共有フォルダー構成に関わる Next.js プロジェクトの作業。
範囲	変更対象のプロジェクトアーキテクチャ、トピック別ルールファイル、公式リファレンス、検証メモ、小規模で元に戻せるアーキテクチャの修正をレビューし、指針を示します。
権限	ユーザー／プロジェクトの指示がこのスキルより優先されます。フレームワークの挙動については、最新の Next.js 公式ドキュメントがローカル規約より優先されます。安全性ポリシーにより、リスクの高いランタイム、認証、シークレット、インポート境界の変更は制限されます。
根拠	ローカルのパッケージ／設定／ルーターの指標、変更対象のソースパス、トピック別ルール、公式リファレンス、検証スクリプト、プロジェクトのチェック結果を使用します。
ツール	ローカルの検索／読み取り／編集／検証コマンドを使用します。API の変更が問題となる場合は最新の公式ドキュメントを参照します。破壊的な移行、認証情報、本番環境への影響、広範なコードモッドには承認を求めます。
ループ	なし。このスキルはリクエストごとに 1 回の適用パスを実行し、ユーザーが再度の適用を求めた場合にのみ再実行します。
出力	ルールの分類、変更したファイル（ある場合）、検証根拠、残るリスク、日付を付した公式ドキュメントの曖昧さに関する注記を含む、韓国語でのアーキテクチャ判断またはレビュー。
検証	変更対象の領域に関連する rules/validation.md のチェックを実行します。このスキルのフォルダーを変更した場合は bash scripts/validate-nextjs-architecture-skill.sh を実行します。
停止条件	プロジェクトのモードを把握し、適用される安全確認を通過し、ローカル規約を適用または保留として記録し、検証根拠を記録し、未解決の API 変更に日付と出典を付した時点で停止します。

</instruction_contract>

概要

コード変更の前後に、Next.js の公式アーキテクチャルールを適用します。まず対象が Next.js プロジェクトであることを確認し、App Router、Pages Router、またはその両方を使用しているかを特定します。次に、ルーティング、Server Component と Client Component の境界、データ／キャッシュの挙動、Server Actions、Route Handlers、Proxy、プラットフォーム設定に関する、必要最小限のルールセットを適用します。

公式情報優先のルール： フレームワークの挙動については、最新の Next.js 公式ドキュメントを信頼できる情報源とします。リポジトリ内の規約が Next.js より厳しい場合は、フレームワークの規則ではなくローカル規約として明示します。

App Router の既定値： app/ と src/app/ の作業には、完全な適用を行います。Pages Router のみを使用するプロジェクトでは、ユーザーが移行中でない限り、App Router 専用のファイル規約を強制せず、Next.js の共有プラットフォーム、環境設定、境界チェックを適用します。

変更の既定値： App Router の UI から開始される書き込みには、Server Actions を優先します。ウェブフック、フィード、CORS エンドポイント、公開された機械可読エンドポイント、UI 以外への応答など、HTTP 固有の契約には Route Handlers を使用します。

セキュリティの既定値： すべての Server Action を、到達可能な POST エントリーポイントとして扱います。アクション内、または委譲先のサーバー専用レイヤーで、入力を検証し、認証と認可を行い、返却値を必要最小限に整えます。

クイックサーフェス選択

タスクの内容	デフォルトの選択肢	デフォルトで避けるもの
App Router でフォームや内部 UI の変更を追加する	Server Action	route.ts RPC
Webhook、フィード、CORS エンドポイント、公開 API、XML、JSON、ストリームを追加する	Route Handler	Server Action
UI の初期ページデータを取得する	Server Component	クライアント優先のデータ取得
インタラクティブ機能、ブラウザー API、クライアントフックを追加する	範囲を絞った Client Component	ルートレベルの 'use client'
Server Action を中心にクライアント側のオーケストレーションを追加する	アクションを呼び出すクライアントフック	DB／DAL／サーバー専用コードをインポートするフック
ドメインロジック、プロバイダー呼び出し、認可を追加する	サーバー専用のサービス／DAL レイヤー	Route ファイルまたは Client Component に所有させる
Drizzle のスキーマ、マイグレーション、リポジトリ、DB クライアントを追加する	rules/db.md ＋サーバー専用の src/db 規約	クライアントフックまたは Route Handler のリクエストライフサイクル
Next.js 16 以降で繰り返し利用するデータ／UI をキャッシュする	cacheComponents ＋ use cache／cacheTag／cacheLife	古い fetch のデフォルトに関する思い込み
ミューテーション後に UI を更新する	updateTag、revalidateTag、revalidatePath、refresh、またはリダイレクトフロー	文書化されていない鮮度管理
多数のリクエストにわたりレンダリング前にリダイレクト／リライトする	まず next.config.* を使用し、必要に応じて Proxy	汎用ミドルウェアとしての Proxy
Pages Router のみで、移行の依頼がない	共通の Next.js チェック	App Router 専用のファイル規則

<activation_examples>

肯定的な例：

• 「この Next.js App Router の機能について、Server／Client の境界とキャッシュの正しさを監査してください。」
• 「このフォームをリファクタリングして、内部の Route Handler ではなく Server Actions を使用してください。」
• 「Webhook 用の Route Handler を追加し、現在の Next.js ドキュメントに準拠していることを確認してください。」
• 「Next.js 16 の cacheComponents を基準に、データ取得のルールを確認してください。」
• 「Next.js App Router で src/lib/auth/session.ts や src/services/billing/mutations.ts のように、ネストした共通フォルダーに整理してください。」
• 「クライアントフックに DB アクセスを漏らさず、この Next.js アプリに Drizzle のスキーマとマイグレーションを追加してください。」
• 「この Next.js フォームをクライアントフック、Server Actions、サーバー専用サービス／DAL に分割してください。」

否定的な例：

• 「汎用的な React アーキテクチャガイドを作成してください。」
• 「Remix または TanStack Start のアプリをレビューしてください。」
• 「アーキテクチャに触れず、Next.js のランディングページ向けのマーケティング文を書いてください。」

境界の例：

• 「Next.js のページで、テキストだけを少し変更してください。」 アーキテクチャ上の境界に影響しなければ、直接編集だけで十分な場合があります。ただし、変更するファイルについては簡単な境界チェックが必要です。
• 「このリポジトリは Pages Router のみで、App Router に移行する予定はありません。」 共通の Next.js プラットフォーム、環境変数、サーバー／クライアントの安全性チェックを適用し、App Router 専用のファイル規約は緩和します。

</activation_examples>

ステップ 1：プロジェクトの検証

アーキテクチャに関する作業を始める前に、プロジェクトとルーターのモードを確認します。

rg -n '"next"' package.json
find . -maxdepth 3 \( -path './app' -o -path './src/app' -o -path './pages' -o -path './src/pages' \)
test -f next.config.ts -o -f next.config.mjs -o -f next.config.js

解釈：

• next 依存関係がない場合：停止します。このスキルは適用されません。
• app/ または src/app/ がある場合：App Router モードです。
• App Router がなく、pages/ または src/pages/ がある場合：共通の Next.js モードです。
• app/ と pages/ が混在する場合：変更対象の app/ コードには App Router のルールを適用し、依頼がない限りレガシー構成の移行は避けます。

ステップ 2：関連する最小限のルールセットを読む

最初に必ず読むファイル： architecture-rules.md。

次に、変更対象に必要なルールファイルだけを読み込みます。

• rules/routes.md — ファイル規約、セグメントルール、ルートグループ、プライベートフォルダー、並列ルート／インターセプトルートに関する注意事項
• rules/project-structure.md — プロジェクトのトップレベル構成、src/、共有コードの配置、ネストした src/modules、src/services、src/db、src/server、src/integrations、src/config、リポジトリ内の構成規約
• rules/services.md — DAL／サービス／プロバイダーの境界、DTO、認可の委譲、server-only ヘルパーの分割
• rules/hooks.md — クライアントフックのオーケストレーション境界、およびフックがサーバー／データレイヤーをまたいではならない場所
• rules/db.md — Drizzle のスキーマ／設定／マイグレーション、接続のライフサイクル、リレーション／RQB、バリデーション連携、server-only の DB 配置
• rules/execution-model.md — サーバー／クライアントコンポーネント、'use client'、プロバイダー、シリアライズ可能な props、server-only／client-only
• rules/data-fetching.md — サーバー優先の読み取り、ストリーミング、Cache Components、use cache／use cache: remote／use cache: private、キャッシュタグ、再検証、動的レンダリング
• rules/server-actions.md — use server、フォーム、バリデーション、認証／認可、DAL への委譲、updateTag／再検証／リダイレクトの順序
• rules/route-handlers.md — route.ts、HTTP メソッド、キャッシュの意図、params、UI 以外のレスポンス、CORS／ウェブフック
• rules/platform.md — 環境変数、next.config.*、typedRoutes、Proxy、ルートセグメント設定、デプロイに影響する設定

変化の影響を受けやすい Next.js の動作については、まず references/official/current-docs-2026-06-02.md を読み、次に references/official/nextjs-docs.md を読みます。ブラウザーで読める Markdown が必要な場合は、https://r.jina.ai/https://nextjs.org/docs/... を通じて公式ページを取得してください。Drizzle 固有の動作については、references/official/drizzle-docs.md を読んでください。

ステップ 3：変更前のゲート

既存コードへの導入

• 原則として、変更対象外のレガシーな逸脱を理由に失敗と判定しないでください。
• 変更対象のファイルにおける安全性、シークレット、認証、境界に関する問題は、直ちにブロックします。
• 大規模な移行が必要になる場合を除き、変更対象のファイルを準拠させてください。

ゲート 1：ルーティング、ファイル規約、プロジェクト構成

確認項目	ルール
page.tsx、layout.tsx、loading.tsx、error.tsx、not-found.tsx、または route.ts が有効なセグメント構成の外に配置されている	ブロック
同じルートセグメントに route.ts と page.tsx を作成している	ブロック
URL が変わるかのようにルートグループを使用している	ブロック
ルーティング可能なセグメントとして公開する代わりに _folder を使うべきプライベートな実装ファイルが公開されている	ブロック
共有の src/modules／src/services／src/db／src/server／src/integrations／src/config の構成を、ネストしたドメイン／プロバイダー別のグループ化によって変更対象コードが明確になるにもかかわらず、フラットな構成や直接のリーフ構成にしている	警告。ネストしたグループ化を優先
リポジトリ内のフォルダー構成の好みを、公式の Next.js の規則として報告している	ブロック
対応するレイアウトスロットやハードナビゲーション時の動作がないまま、並列ルート／インターセプトルートを追加している	リスクに応じて警告／ブロック

ゲート 2：サーバーとクライアントの境界

確認項目	ルール
インタラクティブなコンポーネントに 'use client' がない	ブロック
必要がないのにツリーの上位に 'use client' を追加している	ブロック
クライアントコンポーネントが DB コード、非公開の環境変数、cookies()、headers()、または server-only ヘルパーをインポートしている	ブロック
サーバーからクライアントへ渡す props が広範囲、シークレットを含む、またはシリアライズ不可能である	ブロック
プロバイダーが必要以上に広い範囲のツリーをラップしている	警告
クライアントフックが DB、Drizzle スキーマ、DAL、非公開の環境変数、cookies()、headers()、または server-only のプロバイダークライアントをインポートしている	ブロック

ゲート 3：データ取得、キャッシュ、鮮度

チェック	ルール
クライアントのみで処理する必要がない初期 UI データを、クライアントコンポーネントで取得している	BLOCKED
キャッシュの動作が意図せず決まっている、文書化されていない、または古いデフォルト設定に依存している	BLOCKED
cacheComponents が有効なのに、キャッシュされないランタイムデータに use cache、connection()、loading.tsx、または <Suspense> の意図が欠けている	BLOCKED
use cache が、シリアライズ可能な引数として受け取るのではなく、キャッシュ対象のスコープ内で cookies() / headers() を読み取っている	正当な理由がある実験的な use cache: private を明示的に使用している場合を除き、BLOCKED
新しい App Router の作業で connection() の代わりに unstable_noStore を追加している	レガシーコードの保守を除き、BLOCKED
ミューテーションに updateTag、revalidateTag、revalidatePath、refresh、リダイレクト時の鮮度確保、または文書化された代替手段が欠けている	BLOCKED

ゲート 4：サーバーアクション

チェック	ルール
サーバーアクションが適しているにもかかわらず、内部 UI のミューテーションを route.ts で実装している	HTTP セマンティクスが必要な場合を除き、BLOCKED
アクションが FormData、パラメーター、ヘッダー、または検索パラメーターを検証／再検証せずに信頼している	BLOCKED
アクションがページレベルの認証チェックのみに依存している	BLOCKED
アクションが未加工の DB 行または広範な内部オブジェクトを返している	BLOCKED
アクションが、認可、DTO の整形、またはプロバイダーのオーケストレーションに必要なサーバー専用のサービス／DAL 境界を迂回している	リスクに応じて WARNING/BLOCKED
必要な再検証またはタグの更新より前に redirect() が実行される	BLOCKED

ゲート 5：ルートハンドラーと Proxy

チェック	ルール
UI 専用のフローで、デフォルトの内部 RPC としてルートハンドラーを使用している	BLOCKED
ルートハンドラー内で NextResponse.next() を使用している	BLOCKED
正確性が重要な箇所で、ルートハンドラーのキャッシュ動作が明示されず、推測に委ねられている	BLOCKED
ヘルパー関数ではなく、ルートハンドラーの本体に直接 use cache を配置している	BLOCKED
新たに proxy.ts を追加すべきところに middleware.ts を追加している	BLOCKED
next.config.*、ヘッダー、リダイレクト、リライト、またはレンダリング時のロジックで十分なのに Proxy を追加している	BLOCKED
Proxy のマッチャーがない、範囲が広すぎる、または必要な箇所でメタデータ／静的コンテンツの対象を除外できていない	BLOCKED

ゲート 6：プラットフォームと環境

チェック	ルール
.env* ファイルが src/ から読み込まれると想定している	BLOCKED
クライアントコードが NEXT_PUBLIC_ 以外の環境変数を読み取っている	BLOCKED
ランタイムのクライアント環境変数を、ビルド時のパブリック環境変数として扱っている	BLOCKED
cacheComponents が有効な状態で、削除された v16 のルートセグメント設定オプション（dynamic、revalidate、fetchCache）を使用している	BLOCKED
プラットフォームとの互換性を確認せずに、runtime: 'edge' または Proxy のランタイムに関する前提を変更している	BLOCKED
デプロイに影響するサーバーアクションのオリジン／設定の変更が文書化されていない	リスクに応じて WARNING/BLOCKED

ステップ 4：実装ポリシー

局所的で元に戻せる問題は自動修正します。クライアント境界を狭める、サーバー専用コードを DAL／ヘルパーの背後に移動する、server-only を追加する、不足している鮮度確保を追加する、UI 専用の route.ts によるミューテーションを小規模なサーバーアクションに置き換える、Proxy のマッチャーを絞り込む、キャッシュの意図を明確にする、といった修正が該当します。

広範な移行は自動適用しないでください。Pages から App Router への書き換え、キャッシュモデルの全面的な変更、ルートハンドラーからサーバーアクションへの一括変換、デプロイに影響するオリジン／暗号化の変更が該当します。

<validation_checklist>

ステップ 5：変更後の検証

主張を裏付けるため、プロジェクト固有の最小限のチェックを実行し、証拠を報告します。

1. プロジェクトのモードが、編集した対象と引き続き一致している
2. 特殊ファイルが有効なセグメント内にあり、page／route の競合が存在しない
3. 共有フォルダーとセグメントローカルフォルダーがプロジェクト構成のルールに従っており、新たに変更した共有コードには、明示的な例外が記録されていない限り、ネストした src/lib／src/services によるグループ化が必要です
4. 'use client' の境界が限定的で安全である
5. クライアントコードからサーバー専用モジュールやプライベートな環境変数をインポートできない
6. データ／キャッシュ戦略が明確で、最新のドキュメントと互換性がある
7. 変更後の鮮度維持に updateTag、revalidateTag、revalidatePath、refresh、リダイレクトフロー、または文書化された代替手段を使用している
8. Route Handler と Proxy の使用が引き続き妥当である
9. next.config.*、環境変数の読み込み、ルートセグメントの設定、デプロイ設定に一貫性がある

このスキルフォルダー自体については、次を実行します。

bash skills/nextjs-architecture/scripts/validate-nextjs-architecture-skill.sh

完了条件

Next.js のモードが判明し、変更したすべての対象が該当するゲートを通過し、検証結果が最新であり、リポジトリ固有の規約や残るリスクがあれば明示的に報告した時点で完了です。