nextjs-15-expert

Base Claude knows Next.js at a mostly-current tutorial level; nextjs-15-expert knows current-version idioms, opinionated conventions, and Next 15's specific caching-and-async-params changes.

The gap is most obvious on Next.js 15-specific features where base Claude sometimes defaults to Next.js 14 patterns that look right but fail at runtime.

The specialist also runs in its own context window, so its work doesn't pollute your main conversation.

Match your project's actual Next.js version. Check package.json. Next.js 15 changed defaults significantly:

• Caching is opt-in (was opt-out in 14)
• Params and searchParams are async (were sync in 14)

A 15-expert giving 14 advice or vice versa produces code that looks right but breaks. During a 14→15 migration, install both briefly and remove the older one after the migration completes.

Via the description field. Claude Code reads all subagent descriptions on session start and routes work to the one whose description best matches your prompt.

The reference config uses "Use PROACTIVELY" plus specific trigger keywords: App Router, Server Components, page.tsx, layout.tsx, route.ts, Server Actions, searchParams.

Include the vocabulary your team actually uses when talking about Next.js code.

Sonnet by default. Framework work is largely applied — knowing the idioms and applying them correctly — which Sonnet handles well.

Reserve Opus for framework agents only when the work is architectural (designing a new module structure, choosing data-fetching strategies for complex pages).

For daily Next.js coding, Sonnet with the specialist system prompt beats Opus without it.

Directory-scoped writes plus Next.js-specific bash. Reference config:

• Read, Grep, Glob, Edit
• Write(app/**), Write(components/**), Write(lib/**)
• Bash(pnpm:*), Bash(npx next:*)

Do not allow general Bash. Do not allow Write on next.config.js unless you specifically want config changes going through this agent.

They complement each other:

• CLAUDE.md — tells Claude about your project (versions, deployment targets, team conventions).
• Agent — tells Claude about the framework itself (default patterns, gotchas, current idioms).

Both load on session start. Together they give Claude the fullest possible context for Next.js work — the trifecta with an added MCP server is the mature setup.

Install both specialists. Give each a directory-scoped tool restriction:

• Next.js agent → Write(apps/web/**)
• FastAPI agent → Write(apps/api/**)

Cross-cutting work routes to the main conversation, but framework-specific work goes to the right specialist. Common pattern for polyglot full-stack projects.

It knows what's in the config you install. That's the whole point of the agent — you can encode information about post-cutoff features by adding them to the "Next.js 15 specifics" section.

When Next.js ships a new feature, update the agent config the same day; every session from then on incorporates the update.

Our editorial team refreshes the reference config within 48 hours of every Next.js release.

Yes, temporarily. Make the two descriptions non-overlapping so Claude Code's auto-routing picks the right one:

• nextjs-14-expert — mentions "Pages Router" or "Next.js 14".
• nextjs-15-expert — mentions "App Router", "Server Components", "Next.js 15".

Add directory-scoped tool restrictions so each only writes into the code owned by its version. Remove the older agent once the migration completes.

It's an instruction to the agent about how to structure its responses. When it implements a feature, it will:

1. Explain the Server/Client boundary decision.
2. Show a diff, not the full file.
3. Note caching implications.
4. Mention which revalidatePath/revalidateTag calls are needed.

That consistency makes agent output easy to review — every response has the same shape, so you know where to look for the important information.