CLAUDE.md for Next.js: A Project Instructions Template

A CLAUDE.md for Next.js should describe the version, commands, routing structure, and server boundaries of the repository you actually have. Adapt a template after inspecting those facts, then verify it with a small change. Tools like fenbs keep the implementation decisions and current tasks outside the file, so stable instructions do not become a running development diary.

The framework name alone does not define your project. Two Next.js repositories can use different routers, package managers, data layers, and test setups. Your instruction file should help an assistant discover the right path through this codebase, rather than importing conventions from a generic tutorial.

What should you inspect before filling in the template?

1. Read package.json and the lockfile. Identify the package manager, resolved Next.js version, and scripts that the project actually uses.
2. Inspect the application directories. Determine whether routes live in app, pages, src/app, or another package, and whether more than one routing system is present.
3. Find representative components and data calls. Follow a read and a write from the interface to their established service or database boundary.
4. Read the current test and deployment documentation. Check which commands are safe locally and which require secrets, external services, or approval.
5. Identify any existing project instructions. Extend the authoritative source rather than creating a second copy of the same rules.

Use version-matched documentation when an API detail matters. The Next.js installation guide↗ (opens in a new tab) describes documentation bundled with the installed package. Where those local docs are available, they help you avoid assuming the online latest version matches your dependency.

The general CLAUDE.md guide covers the instruction file itself. This template focuses on the Next.js facts a contributor needs before choosing an implementation.

What does a useful Next.js template look like?

The following is an illustrative App Router project using pnpm. Its paths and script names are examples, not a claim about your repository. Replace or remove every line that you cannot support by inspecting the project. Do that before asking an assistant to treat the file as an instruction.

# Project
This application uses Next.js App Router and TypeScript.
Read package.json and the lockfile for installed versions.
Use pnpm. Run app commands from apps/site.
Read the matching installed Next.js docs before unfamiliar API changes.

# Structure
Routes and layouts: apps/site/src/app
Shared interface components: apps/site/src/components
Server data functions: apps/site/src/lib/data
Reuse the existing data layer and component patterns.

# Boundaries
Keep secrets and privileged data access on the server.
Use Client Components for browser interaction where needed.
Validate untrusted input and enforce access at the server boundary.
Do not treat a hidden button as an authorization check.
Do not introduce a second data layer or router without approval.

# Validation
Read package.json before choosing validation commands.
Use the scripts for type checks, lint, tests, and production build.
Report the exact commands, working directory, and results.
Report checks that were blocked or not run.
Do not deploy, modify live data, or add dependencies without approval.

Notice what the example leaves out: a specific release number to maintain by hand, a list of every component, and a claim that all projects share one command. It points to facts with a clear source and records choices that the source files may not explain.

Compare it with other CLAUDE.md examples, but keep only rules your team needs. An instruction file should make the first useful action easier, not require an assistant to read a second copy of the entire repository.

How should you describe the server and client boundary?

For App Router projects, the Next.js component guide↗ (opens in a new tab) explains that layouts and pages are Server Components by default, while browser interaction can use Client Components. State how your codebase applies that distinction, with one real component and one real data function as references.

Do not turn the distinction into “never use client components.” A search field with interactive state may need browser behavior. The useful constraint is to place that behavior deliberately while preserving the server-side boundary around secrets and privileged operations. Describe the existing pattern rather than imposing a blanket rule.

Also distinguish interface visibility from permission enforcement. The Next.js data security guide↗ (opens in a new tab) says Server Actions require authentication and authorization checks at their own boundary. Your template should identify where the project performs those checks and require contributors to preserve them. A page redirect or hidden action is not a substitute.

Record the human-approved architecture choice in fenbs Decisions and rules. The repository file can point contributors toward the established pattern while the decision explains why the team uses it.

Which commands should the file require?

List the checks that exist and matter, together with their working directory. A monorepo command from the root may differ from an app command. If a script depends on a local service or private configuration, say what prerequisite is needed without putting secrets in the instruction file.

Do not assume the build includes every other check. The Next.js lint setup guidance↗ (opens in a new tab) documents linting separately and notes that newer versions do not automatically lint during a production build. Tie the requirement to the installed version and actual scripts rather than an old checklist. A missing check should be reported as a gap, not described as passing.

What should stay outside the instruction file?

Keep temporary bugs, current assignments, and unfinished experiments with their tasks. A note that the checkout page needs another test is useful today, but it should not become a permanent instruction to every future session. Stable boundaries belong in the file; changing progress belongs in the project record.

Keep detailed design and API decisions in their maintained sources too. If the team rejects a second data client, the lasting rule can be short and point toward the chosen layer. The discussion, alternatives, and approval should remain available without being loaded into every small styling task.

For repositories with several apps, see Claude Code across multiple projects. Give each app the instructions it needs while keeping shared decisions consistent. Avoid repeating the same long architecture explanation in every directory.

How can you verify the instructions on a real task?

Choose a small change that crosses a meaningful boundary, such as adding an empty state to a server-rendered list with an interactive filter. Ask Claude to identify the relevant files and checks first. Review whether its plan follows the actual data layer and places browser behavior appropriately.

Then inspect the change and the reported checks. If the assistant chooses a nonexistent script or invents a directory, fix the source of that assumption before adding more instructions. If it claims a test passed, verify the command and result. An instruction-file trial is useful only when you examine behavior rather than accept a confident summary.

How to do this with fenbs

1. Create a free account and add the Next.js project.
2. Record the architecture decisions people approved, including the data boundary and any restrictions on dependencies or live changes.
3. Save your reusable instruction template in Skills and prompts. Add a task for adapting it to the repository, with a plan for checking paths and scripts.
4. Connect a supported assistant through Integrations and ask it to read the project context before inspecting the repository.
5. Save the validation results and Where we left off, including any checks blocked by missing services or credentials. Keep those credentials out of the record.

fenbs does not build, host, or deploy your Next.js app. A short instruction file may be sufficient for a small solo project. The shared record helps when decisions, tasks, and handoffs must survive changes of assistant or teammate. The AI prompts hub has more guidance for maintaining those instructions.