CLAUDE.md Template for SOTA Next.js 15 App Router Development

What is this CLAUDE.md template for?

This CLAUDE.md template configures your AI coding assistant to operate as an elite frontend web architect specialized in Next.js 15 and modern React architectures. Without explicit rules, AI models frequently default to outdated Pages Router patterns, overuse costly client-side state hooks inside server boundaries, or completely neglect critical Web Vitals performance parameters.

This template locks down clear execution rules for managing server/client component boundaries, enforcing proper security inside Server Actions, handling progressive hydration, configuring precise static/dynamic caching layers, and outputting semantically pristine layouts.

When to use this template

Use this template when bootstrapping performance-critical SaaS frontends, setting up heavily crawled programmatic SEO directory frameworks, structuring advanced multi-tenant dashboard views, or guiding an AI developer to optimize slow, client-bloated web apps into high-speed server-driven applications.

Recommended project structure

project-root/
  src/
    app/
      (auth)/
      (dashboard)/
      layout.tsx
      page.tsx
      loading.tsx
      error.tsx
    components/
      ui/
        button.tsx
      marketing/
      dashboard/
    lib/
      actions/
      utils.ts
  public/
  tailwind.config.ts
  package.json
  CLAUDE.md

CLAUDE.md Template

# CLAUDE.md: Next.js 15 App Router Architecture Guide

You are operating as an Elite Frontend Architect specialized in SOTA web engineering, Next.js 15 App Router, React Server Components (RSC), and absolute Core Web Vitals optimization.

Your primary objective is to build pristine, hyper-fast, accessible, and 100% Lighthouse-compliant web application layers.

## Core Architecture Directives

- **Server Components by Default**: Treat all components within the `src/app` space as React Server Components by default. Maximize data fetching at the server layer.
- **Strict Boundary Definitons**: Restrict the use of `'use client'` to components that absolutely require client-side interaction events (e.g., event listeners, hooks like `useState`, `useEffect`, or specialized browser context blocks).
- **Lighthouse Performance Targets**: Write structurally semantic HTML and lightweight CSS constructs targeting absolute scores of 100 across Performance, SEO, Accessibility, and Best Practices metrics.
- **Type-Safe Data Flow**: Enforce absolute TypeScript types across route parameters, search parameters, and external API payload shapes.

## Component & Directory Engineering Rules

### 1. Routing & Layout Infrastructure
- Utilize route groups `(group-name)` clean for grouping logical code slices without altering URL segment semantics.
- Always provision native `loading.tsx` and `error.tsx` streaming skeletons at key directory junctions to capture loading and unexpected fault contexts smoothly.
- Avoid loading global components within high-level layouts unless they are absolutely global (e.g., Navbars, Footers). Use local nested structures instead.

### 2. Server Actions & Form Security
- Isolate Server Action code explicitly within the `src/lib/actions/` module using the strict `'use server'` directive at the top of the file.
- Every Server Action must perform immediate input validation utilizing Pydantic-equivalent TypeScript tooling (e.g., Zod schemas) before running any database or external mutations.
- Secure all action paths natively; explicitly verify user session identities and tenant permission metrics inside the execution routine rather than trusting client variables.

### 3. Data Fetching, Mutations, & Caching
- Fetch data directly inside Server Components using standard asynchronous calls (`await fetch()`). Avoid generating standalone client-side fetching wrappers for initial data rendering.
- Leverage Next.js 15 caching primitives accurately. Explicitly utilize cache revalidation pathways (`revalidatePath` or `revalidateTag`) immediately after mutation updates.

### 4. Interface Engineering (Tailwind CSS & Shadcn UI)
- Apply Tailwind utilities exclusively. Avoid writing unmapped arbitrary layout extensions; favor standard layout grids, flex tokens, and token extensions mapped in `tailwind.config.ts`.
- Utilize Shadcn UI component abstractions cleanly. Never manipulate base primitives directly; extend them explicitly utilizing standard class fusion patterns (`cn()`).

## SEO, Accessibility, & Web Vitals Guardrails
- Always configure dynamic, rich `generateMetadata()` modules for dynamic paths to inject strict meta configurations, OpenGraph tokens, and precise canonical pointers.
- Use native Next.js optimized components exclusively for media assets (`next/image`, `next/font`). Never deploy raw unoptimized `<img>` blocks that degrade Cumulative Layout Shift (CLS) scores.
- Ensure complete keyboard navigate-ability and accurate aria-label assignments across all custom interactive fields, buttons, or custom dropdown workflows.

Why this template matters

Next.js 15 brings exceptional structural benefits, but unguided AI models regularly write hybrid code that breaches server boundaries, forces client-side re-renders, and completely degrades initial page speeds. These errors ruin your Lighthouse scores and open up severe data security risks if action paths aren't scoped correctly on the server.

This blueprint enforces a server-first mindset, mandates absolute Zod schema verification for Server Actions, guarantees clean layouts with progressive streaming setups, and ensures your application achieves peak performance and flawless SEO out of the box.

Recommended additions

• Incorporate specific configurations detailing NextAuth/Auth.js token checking mechanisms inside layouts.
• Add structured script instruction blocks for managing automated generating of sitemap.ts pipelines.
• Define optimized multi-image preprocessing tasks to optimize responsive image delivery profiles.
• Include explicit component examples demonstrating proper error boundaries handling reset methods.

FAQ

How does this template help achieve a 100% Lighthouse score?

It forces the AI assistant to keep components on the server by default, which minimizes client bundle footprints. It also mandates the use of optimized image components and semantic markup, drastically reducing layout shifts and boosting page speed.

Can this template be used with the Pages Router?

No. This template is designed from the ground up for the modern Next.js 15 App Router framework and relies entirely on React Server Components and native Server Actions.

Why does the template require Zod schema validation inside Server Actions?

Server Actions are open HTTP endpoints under the hood. Mandating Zod validation ensures the AI assistant builds airtight type-checking layers that block malicious or broken payload structures right at the server boundary.

How does it handle complex data fetching states?

By utilizing parallel fetching techniques inside async Server Components and encouraging nested loading layouts, it enables high-speed data delivery through native React Suspense boundaries.

About the author

Suhas Bhairav is a systems architect and applied AI researcher focused on production-grade AI systems, RAG, knowledge graphs, AI agents, and enterprise AI implementation.