Next.js 16.3 AI Improvements入門——AGENTS.mdとMCPで開発を任せる

はじめに

2026年6月26日、Next.js公式ブログで Next.js 16.3: AI Improvements が公開されました。テーマは、Next.jsアプリをAIエージェントに扱わせるための改善です。AGENTS.mdにドキュメントを同梱する仕組み、Next.js向けのSkills、React状態を読めるagent-browser、エージェントが修正方針を選びやすいエラー表示、Next DevTools MCPの軽量化が紹介されています。

この記事では、架空の問い合わせ管理SaaS「HelpDeskHub」を題材に、Next.js App Router + Firestore + TypeScriptの開発環境へどう取り込むかを実践形式で整理します。16.3はPreviewとして扱われているため、本番更新ではなく、検証ブランチでAIエージェントの作業精度を上げるための導入手順として読んでください。

参考にした一次情報は次の通りです。

• Next.js 16.3: AI Improvements
• Enabling Next.js MCP Server for Coding Agents
• blocking-prerender-dynamic エラーDocs
• agent-browser公式Docs
• agent-browser npm registry
• vercel/next-devtools-mcp

何が変わったのか

今回の更新は、AIがコードを書く能力そのものではなく、AIがNext.jsの状態を誤読しにくくする足場 に価値があります。

事前準備: Previewブランチで試す

まずは本線から切り離したブランチで試します。Next.js 16.3の機能はPreview前提なので、既存アプリをいきなり更新しないほうが安全です。

git switch -c chore/nextjs-16-3-ai-agents
yarn add next@preview
yarn build

公式ブログでは、既存のAGENTS.mdを更新するためのcodemodも案内されています。@next/codemod はnpmレジストリで実在を確認できるNext.js公式パッケージです。プロジェクト依存は yarn のままにし、次の npx は公式codemodを一時実行する用途として使います。

npx @next/codemod@canary agents-md

HelpDeskHubでは、AGENTS.mdにエージェントへ渡す制約を入れます。実案件名や顧客名は書かず、技術スタックと検証条件だけを固定します。

# HelpDeskHub agent instructions

- Use Next.js App Router and TypeScript.
- Prefer Server Components for read-only screens.
- Use Server Actions for authenticated mutations.
- Store tickets and work logs in Cloud Firestore with firebase-admin.
- Do not introduce Express, SQL, or client-side secrets.
- Before finishing, run `yarn build`.
- For UI changes, verify `/tickets` and `/tickets/[id]`.

ハンズオン1: Next DevTools MCPで診断口を作る

Next.js 16以降では、開発サーバー内にMCP向けの入口があり、next-devtools-mcp を通じてエージェントがエラー、ログ、ルート、Server Actionsなどを取得できます。公式Docsの設定例に従い、リポジトリ直下へ .mcp.json を置きます。

{
  "mcpServers": {
    "next-devtools": {
      "command": "npx",
      "args": ["-y", "next-devtools-mcp@latest"]
    }
  }
}

この設定は、MCP対応エージェントが読み込むためのものです。開発者側は通常通りNext.jsを起動します。

yarn dev

エージェントには、いきなり「全部直して」と頼むのではなく、まず診断だけを任せます。

Next DevTools MCPで現在のルートとエラーを確認してください。
対象は /tickets と /tickets/[id] です。
修正前に、変更予定ファイルと理由を箇条書きで出してください。

これで、AIが存在しないルート名や古いPages Router前提で修正するリスクを下げられます。特にServer ActionsやApp Routerのファイル配置は、リポジトリごとの差が出やすいので、実際のdev serverから確認させるのが有効です。

ハンズオン2: Firestore読み取りをSuspense境界に寄せる

16.3のエラー改善では、Cache ComponentsやInstant Navigationsでブロック要因になるデータ取得に対して、Suspenseへ移す、キャッシュする、ブロックを許可する、という選択肢が提示されます。Firestoreを使う画面では、全部をページ直下で await しない設計が重要です。

HelpDeskHubの詳細画面では、チケット概要だけを先に見せ、コメント履歴と監査ログは後からstreamします。

// src/app/tickets/[id]/page.tsx
import { Suspense } from "react";
import { TicketAuditLog } from "./TicketAuditLog";
import { TicketComments } from "./TicketComments";
import { getTicketSummary } from "@/lib/tickets/getTicketSummary";

type Props = PageProps<"/tickets/[id]">;

export default function TicketDetailPage(props: Props) {
  return (
    <main className="space-y-6">
      <Suspense fallback={<p>問い合わせ概要を確認しています...</p>}>
        <TicketSummary params={props.params} />
      </Suspense>

      <Suspense fallback={<p>コメントを読み込んでいます...</p>}>
        <TicketComments params={props.params} />
      </Suspense>

      <Suspense fallback={<p>監査ログを読み込んでいます...</p>}>
        <TicketAuditLog params={props.params} />
      </Suspense>
    </main>
  );
}

async function TicketSummary({ params }: { params: Props["params"] }) {
  const { id } = await params;
  const ticket = await getTicketSummary(id);

  return (
    <section>
      <p className="text-sm text-gray-500">問い合わせ番号: {ticket.code}</p>
      <h2 className="text-2xl font-bold">{ticket.subject}</h2>
      <p>ステータス: {ticket.status}</p>
    </section>
  );
}

Firestoreアクセス層は、必要な型を明示します。ここでは例として、概要取得だけを切り出します。

// src/lib/tickets/getTicketSummary.ts
import { getFirestore } from "firebase-admin/firestore";

export type TicketSummary = {
  code: string;
  subject: string;
  status: "open" | "waiting" | "resolved";
};

export async function getTicketSummary(id: string): Promise<TicketSummary> {
  const snapshot = await getFirestore().collection("tickets").doc(id).get();

  if (!snapshot.exists) {
    throw new Error("Ticket not found");
  }

  const data = snapshot.data() as TicketSummary;
  return {
    code: data.code,
    subject: data.subject,
    status: data.status,
  };
}

公式のエラーDocsでは、データが毎回新鮮であるべきならSuspenseへ移し、再利用できるデータなら use cache を検討する、という整理がされています。問い合わせステータスは変わりやすいため、最初はキャッシュせず、境界を低く置くほうが実務では扱いやすいです。

ハンズオン3: agent-browserでUI確認を任せる

agent-browserは、AIエージェント向けのブラウザ自動化CLIです。公式Docsでは npm install -g agent-browser、macOSでは brew install agent-browser、一時実行では npx agent-browser open example.com が案内されています。npmレジストリの最新情報では、agent-browser@0.31.1 はNode.js 24以上を要求します。Node.js 22系のCIに無理に入れず、まずはローカル検証端末か専用jobで試すのが安全です。

npx agent-browser open http://localhost:3000/tickets
npx agent-browser snapshot -i

AIには、スクリーンショットの雰囲気ではなく、アクセシビリティツリーと参照IDを使って確認させます。

agent-browserで /tickets を開き、次を確認してください。
- heading "問い合わせ一覧" が存在する
- 未対応チケットが10件以下に絞られている
- 詳細リンクから /tickets/[id] へ移動できる
- 失敗した場合は、見つかったrefと失敗理由だけを報告する

これにより、AIがDOM全体を読み込んで文脈を浪費するより、必要なUI要素だけを確認しやすくなります。

ハンズオン4: Firestoreへ作業ログを残す

AIエージェントに複数Issueを任せるなら、変更の証跡をPRだけに閉じないほうが運用しやすいです。HelpDeskHubでは、架空チケット HDH-001 から HDH-028 を3〜4件ずつ処理し、Firestoreへ検証結果を保存します。

"use server";

import { FieldValue, getFirestore } from "firebase-admin/firestore";

type AgentWorkLogInput = {
  issueKey: `HDH-${string}`;
  summary: string;
  routes: string[];
  checks: string[];
};

export async function createAgentWorkLog(input: AgentWorkLogInput) {
  if (!input.issueKey.startsWith("HDH-")) {
    throw new Error("issueKey must start with HDH-");
  }

  if (input.checks.length === 0) {
    throw new Error("checks must include at least one item");
  }

  await getFirestore()
    .collection("agentWorkLogs")
    .doc(input.issueKey)
    .set(
      {
        summary: input.summary,
        routes: input.routes,
        checks: input.checks,
        updatedAt: FieldValue.serverTimestamp(),
      },
      { merge: true },
    );
}

GitHub Actionsでは、最低限 yarn build を通します。agent-browserをCIに入れる場合はNode.js 24以上の別jobに分け、既存のNode.js 22ビルドを巻き込まない設計にします。

name: pull-request-check

on:
  pull_request:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    timeout-minutes: 15
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "22"
          cache: "yarn"
      - run: yarn install --frozen-lockfile
      - run: yarn build

実務での注意点

AI向け機能が増えても、エージェントに与える作業単位は小さく保つべきです。HelpDeskHubなら、読み取り層、一覧UI、詳細UI、Server Action、監査ログを混ぜず、3〜4Issueずつ処理します。

存在しないコマンドや未確認のMCPツール名をプロンプトに書くと、AIはそれらしく補完してしまいます。この記事で具体名を出したものは、Next.js公式Docs、agent-browser公式Docs、npmレジストリ、または公式リポジトリで確認できる範囲に絞っています。

まとめ

Next.js 16.3 AI Improvementsは、AIエージェントにNext.js開発を任せるための「信号」を増やすアップデートです。AGENTS.mdで前提を固定し、Next DevTools MCPで実アプリの状態を読ませ、エラーDocsで修正方針を選ばせ、agent-browserでUIを確認させると、Next.js + Firestoreの業務アプリでも作業の再現性を上げられます。

まずはPreviewブランチで、1つの画面と3〜4件の架空Issueだけを対象にしてください。yarn build、Firestore作業ログ、GitHub Actionsの3点を通せるようになってから、AIに任せる範囲を広げるのが現実的です。