next-best-practices

next-best-practices スキルの概要

next-best-practices が実際に役立つこと

next-best-practices スキルは、モダンな Next.js コードを書く・レビューするための、コンパクトな実務ガイドです。特に App Router プロジェクトで効果を発揮します。焦点は、実際のコードベースでチームが繰り返し踏みがちなミスにあります。たとえば、Server/Client の境界設定ミス、Next.js 15+ で古くなった async API の使い方、弱いデータ取得設計、Route Handler の誤用、ファイル規約の取り違え、ブラウザ専用パッケージによるバンドル問題などです。

どんな読者・チームに向いているか

このスキルが特に有用なのは、次のようなケースです。

• App Router のコードを本番投入している、またはリファクタリングしている開発者
• 信頼できる Next.js のチェックリストが必要なレビュー担当者
• 汎用的な「Next.js コードを書いて」では弱く、より強いデフォルトが必要な AI 支援コーディングのワークフロー
• Next.js 15 と 16 の変更点をまたいで移行しているチーム

「コンパイルは通るのに実行時の挙動がおかしい」原因を追っているなら、next-best-practices for Frontend Development は特に有効です。単なるスタイルの好みではなく、境界設計やルーティングの実践ルールが整理されているためです。

本当に解決したい仕事

多くのユーザーに必要なのは、網羅的な Next.js チュートリアルではありません。モデルやレビュアーが、適切なパターンを素早く選べることです。

• 直接の server fetch と Route Handler のどちらを使うか
• Server Action と client 側の mutation フローのどちらを使うか
• Node と Edge のどちらの runtime を選ぶか
• page.tsx / layout.tsx / route.ts をどこに置くべきか
• どの場面で 'use client' が必要か
• Next.js 15 以降で無効になる async パターンをどう避けるか

そのため、next-best-practices skill は学習用リソースというより、実装やコードレビューを助ける道具としての価値が高いです。

このスキルの差別化ポイント

最大の強みは具体性です。単に「パフォーマンスを最適化しましょう」といった抽象的な助言ではなく、async-patterns.md、data-patterns.md、rsc-boundaries.md、route-handlers.md、bundling.md のような焦点の絞られたファイルを通じて、具体的な Next.js のルールと例を示してくれます。

もうひとつの差別化ポイントは、バージョン差分に追随したガイダンスです。リポジトリには、async params、async searchParams、async cookies() / headers() など、古い Next.js の感覚のままだと見落としやすい更新後のパターンが含まれています。

このスキルがやろうとしていないこと

next-best-practices は、フレームワーク全体の講座でも、スターターテンプレートでも、本番向けアーキテクチャ設計書でもありません。既存の Next.js ワークフローの中で、エージェントがより良い実装判断をする助けにはなりますが、認証、DB 設計、デプロイ、デザインシステム、プロダクト固有の規約まで置き換えるものではありません。

next-best-practices スキルの使い方

next-best-practices の導入コンテキスト

インストール元は vercel-labs/next-skills リポジトリです。

npx skills add https://github.com/vercel-labs/next-skills --skill next-best-practices

このスキルは、単体で直接実行するパッケージとしてではなく、すでに Next.js コードベースを支援しているアシスタントに追加する使い方が向いています。コード生成、レビュー、リファクタリングの際に、エージェントが内部で適用するガイダンスです。

実務で next-best-practices をどう呼び出すか

このリポジトリでは、このスキルはユーザーが直接呼び出す形式ではないとされています。実際には、AI エージェントに具体的な Next.js タスクを渡すことで使います。たとえば次のような依頼です。

• 「この page を App Router のベストプラクティスに沿ってリファクタリングして」
• 「これらのファイルを RSC 境界ミスの観点でレビューして」
• 「古い Next.js パターンを Next.js 15+ の async API に合わせて変換して」
• 「この機能では Server Component fetch、Server Action、Route Handler のどれが適切か選んで」

依頼内容が実際の実装タスクやレビュー依頼に近いほど、エージェントは next-best-practices usage を自然に適用しやすくなります。

出力品質を大きく左右する入力情報

次の情報を渡してください。

• わかるなら Next.js のバージョン
• App Router を使っているか、Pages Router を使っているか
• 対象ファイルやコード断片
• コードを Node で動かす必要があるか、Edge で動かす必要があるか
• 読み取り中心か、mutation 中心か、API 提供が主目的か
• 現在出ているエラーメッセージ

こうした前提がないと、生成されるコード自体は妥当に見えても、runtime の選択を誤ったり、Route Handler を使いすぎたり、インタラクティブな処理を RSC 境界の誤った側に置いたりしがちです。

あいまいな要望を強いプロンプトに変える

弱いプロンプト:

• 「Next.js でブログページを作って」

より強いプロンプト:

• 「next-best-practices skill を使って、Next.js 15 向けの App Router ブログ記事ページを実装して。slug は dynamic route params から取得し、metadata は記事タイトルから生成し、読み取りは Server Component で行い、インタラクティブなコメント機能は client-side に残して。ファイル配置と必要な async typing も説明して」

これが優れている理由:

• バージョン依存の async ルールを明示できる
• server 側の読み取りと client 側のインタラクションを分離できる
• コンポーネントコードだけでなくファイル規約も確認できる
• 古いパターンが混ざるリスクを下げられる

最初に読むべきリポジトリ内ファイル

まずは次の順番がおすすめです。

1. SKILL.md
2. file-conventions.md
3. data-patterns.md
4. rsc-boundaries.md
5. async-patterns.md

そのあと、問題の種類に応じて枝分かれします。

• bundling の問題: bundling.md
• server/client directive の混乱: directives.md
• runtime の選択: runtime-selection.md
• route API 設計: route-handlers.md
• リカバリーと boundary の挙動: error-handling.md
• 開発中のデバッグ: debug-tricks.md

ツリー全体を流し見するより、この順番のほうが出荷を止める意思決定ポイントに直接対応しているため、はるかに速く役立ちます。

next-best-practices を活かす実践ワークフロー

シグナルの強い進め方は次のとおりです。

1. 機能を reads・mutations・routes に分解して定義する
2. どの部分を Server Components にし、どの部分を Client Components にするかを決める
3. Next.js 15+ の async API が関係するか確認する
4. file-conventions.md でファイル配置を確認する
5. route segment ごとに必要な error/loading の挙動を追加する
6. サードパーティライブラリを import する前に、bundling と runtime の前提を確認する
7. 外部 API アクセスや UI 以外のクライアント対応が本当に必要な場合にだけ Route Handlers を導入する

ここが next-best-practices guide が汎用プロンプトより強い点です。不要な抽象化レイヤーを増やさずに済みます。

このスキルが最も強い場面

このスキルは、単なる構文ではなく「判断」が必要な場面で真価を発揮します。

• データをどこで fetch すべきか
• そのコードを Server Component に置くべきか
• そのパッケージに client wrapper や dynamic(..., { ssr: false }) が必要か
• Route Handler を作るだけの理由が本当にあるか
• 旧来の同期前提を Next.js 15+ の async API にどう移行するか

一方で、見た目だけのコンポーネント作成には、そこまで大きな差は出ません。

判断が割れやすい実装論点を整理できる

次のような論点で迷っているなら、next-best-practices for Frontend Development が役立ちます。

• Server Component で直接 DB / API fetch するか、内部 API route を挟むか
• フォームの mutation を Server Action で行うか、client-side fetch で処理するか
• error.tsx と global-error.tsx のどちらを使うか
• 基本は Node runtime にするか、特定用途だけ Edge にするか
• hooks や browser API が必要だから 'use client' を付けるのか、それとも不要に client 化を広げているだけか

こうした判断は、フォーマット調整よりも、パフォーマンス・bundle size・保守性に大きく効きます。

導入前に把握しておきたい実務上の注意点

見落としやすい制約がいくつかあります。

• 例が App Router 前提になっていることがあるため、Pages Router の作業にそのまま当てはめないこと
• Next.js 15+ の async API によって、params、searchParams、cookies(), headers() に関する従来の前提が崩れることがある
• すべてのパッケージが server-safe とは限らない。bundling failure は、browser 依存コードを Server Components に import したことが原因のことが多い
• redirect() と notFound() には特殊な挙動があり、雑な try/catch 構造にすると期待したナビゲーションフローが壊れることがある

生成コードをそのまま信じる前に、これらは必ず確認したい導入上のチェックポイントです。

見落とされがちなデバッグ支援

next-best-practices usage の中でも意外と便利なのが、debug-tricks.md にある dev-server 向けデバッグガイダンスです。Next.js の開発中は /_next/mcp エンドポイントを通じて、MCP 対応ツールからプロジェクトのメタデータ、routes、現在のエラーを参照できます。静的ファイルだけを見て推測するのではなく、live の route 発見や source map 付きのエラー文脈が必要なときに効きます。

next-best-practices スキル FAQ

next-best-practices は初心者にも向いていますか？

はい。基本的な React を理解していて、実際に Next.js を使って開発しているなら有用です。初心者向け入門チュートリアルではありませんが、抽象理論ではなく意思決定の領域ごとにファイルが整理されているため、比較的追いやすい構成です。

このスキルは App Router プロジェクト専用ですか？

主な対象は App Router で、そこで最も価値を発揮します。ファイル規約、Server Components、directive、data pattern のガイダンスは特に App Router と相性が良いです。プロジェクトが Pages Router 中心なら、next-best-practices skill のうち直接流用できる部分は一部に限られます。

普通の Next.js プロンプトと何が違いますか？

普通のプロンプトでもそれらしいコードは出ますが、古いパターンや前提不一致が混ざりがちです。next-best-practices は、async route props、server/client 境界、route 規約、API レイヤーを作るべきでない場面など、バージョンに即したルールにエージェントを根拠づけることで、判断の精度を上げます。

どんなときは next-best-practices を使わないほうがいいですか？

作業の中心が UI の磨き込み、CSS スタイリング、あるいはフレームワーク非依存の React パターンなら、優先度は下がります。また、チーム内ですでに強い Next.js 規約が整っていて、実装判断ではなく純粋なコード生成だけが必要な場合も、追加価値は小さめです。

next-best-practices を入れるとアプリに何かインストールされますか？

いいえ。アプリの runtime dependency が追加されるわけではありません。next-best-practices install は AI スキル環境にガイダンスを追加する手順であり、アシスタントがリポジトリ作業中にその知見を使えるようにするものです。

移行作業にも使えますか？

はい。古い理解と新しい Next.js の挙動のズレ、たとえば async request API や更新された file/runtime 規約を見つけるのに特に有効です。移行やリファクタリングのプロンプトは、このスキルの得意分野のひとつです。

next-best-practices スキルを改善する方法

まず next-best-practices に設計コンテキストを渡す

より良い出力を得るには、次の情報を先に渡してください。

• 現在の route 構成
• 対象の file path
• そのコードが static である必要があるか、dynamic である必要があるか、mutation に対応する必要があるか
• mobile app や webhook などの外部利用者がいるか

これにより、Server Components、Server Actions、Route Handlers を全部並べるのではなく、適切なものを選ばせやすくなります。

機能要件だけでなく境界条件も示す

問題にインタラクティブ要素があるなら、どこを client-side に残す必要があるかを明示してください。例:

• 「ページの外枠とデータ取得は server-rendered のままにしつつ、filter bar では hooks と URL 更新が必要」

この一文だけでも next-best-practices usage の精度は上がります。'use client' を置くべき場所が明確になり、不要な client 化の拡大を防げます。

バージョンと runtime 制約を必ず含める

対象がそうなら、「Next.js 15 App Router on Node runtime」と明示してください。これでよくある失敗を 2 つ避けられます。

• 古い同期的な params パターンを使ってしまう
• 早まって Edge を勧めてしまう

このスキルは、明確な理由がない限り、基本的に Node を優先します。

コードだけでなく判断理由も求める

強いプロンプトの型は次のようなものです。

• 「これを実装したうえで、なぜ Route Handler ではなく Server Component fetch を選んだのかも説明して」

これにより、エージェントが本当に next-best-practices guide を使っているのか、それとも見慣れたコードを出しているだけなのかが見えます。悪い前提は、説明部分に表れやすいものです。

よくある失敗パターンを確認する

最初の出力では、次の点を重点的にレビューしてください。

• 単純な read にもかかわらず不要な内部 API route を作っている
• browser 専用パッケージを Server Components に import している
• インタラクティブなコンポーネントに 'use client' がない
• 逆に 'use client' をツリーの上位に付けすぎている
• params や searchParams を古い同期型で扱っている
• ナビゲーション helper を広すぎる try/catch で包んでいる

これらはまさにこのスキルで減らしたいミスですが、入力が弱いとすり抜けることがあります。

ファイルを指定したプロンプトで出力精度を上げる

次のような依頼は避けましょう。

• 「自分の Next.js アプリを直して」

代わりに、次のように指定します。

• 「app/blog/[slug]/page.tsx, app/blog/[slug]/loading.tsx, app/blog/[slug]/error.tsx を next-best-practices でレビューして。file conventions、async params、error boundary の正しさを見てほしい」

ファイル単位で対象を絞ると、より実用的な出力になりやすいです。スキル内容自体が、具体的なフレームワークの接点ごとに整理されているためです。

最初の回答のあとに反復する

最初の草案が出たら、次のような追加依頼を重ねると効果的です。

• 「不要な client components を削って」
• 「network round-trips が減るように最適化して」
• 「サードパーティライブラリに bundling 上の危険がないか確認して」
• 「Next.js 15 の async request APIs に照らして検証して」

こうすることで、next-best-practices は一発生成ツールではなく、レビューのループとして機能します。価値が最も出るのはこの使い方です。

問題に合った repo の読み先を指定する

結果をさらに良くしたいなら、エージェントに絞った参照先を示してください。

• routing の問題: file-conventions.md, parallel-routes.md
• 不正な component boundary: rsc-boundaries.md, directives.md
• data flow の混乱: data-patterns.md, functions.md
• 不安定な package import: bundling.md
• runtime や hosting の懸念: runtime-selection.md, self-hosting.md

スキルそのものを編集しなくても、これだけで next-best-practices skill の活用結果はかなり改善できます。