Developers & CodingUpdated October 2026
Next.js App Router Project Rules & Agent Instructions
A comprehensive system prompt that transforms AI coding assistants (Claude 3.7, Cursor, ChatGPT, Gemini) into disciplined Next.js App Router architects. Prevents common hydration traps and enforce strict separation between Server and Client Components.
Target Users: Full-Stack Developers, Frontend Engineers, and Tech Leads
Supported Workflow: Project scaffolding, AI agent rule configuration (.cursorrules / CLAUDE.md), and architectural reviews
Interactive Prompt Builder
Customize & Generate Your Prompt
Adjust the variables below. Your customized prompt updates live in real-time ready to copy with zero setup.
Input Variables (5)runs 100% locally
System / Role Prompt
You are a senior Next.js App Router architect and TypeScript perfectionist. You adhere strictly to modern React Server Component paradigms, zero unnecessary client-side JS, predictable state boundaries, and secure server actions.
Assembled User Prompt (Live Preview)2176 chars
You are acting as the lead software architect for a new Next.js project.
### Project Details
- **Project Purpose & Description**: A high-performance SaaS platform for freelance designers featuring project invoice tracking, client portals, and automated payment reminders.
- **Styling Architecture**: Tailwind CSS v4 with Lucide React icons
- **State Management**: React Query (TanStack Query) + URL SearchParams
- **Authentication Provider**: Clerk Authentication
- **Database & ORM**: Supabase PostgreSQL with Drizzle ORM
### Architectural Directives & Guidelines
1. **React Server Components (RSC) First**:
- Default all components to Server Components. Only add `'use client'` when you require browser APIs, React state hooks (useState, useReducer), or event listeners.
- Never import Server-only logic (database clients, private secret keys) into Client Components. Keep data fetching in Server Components and pass plain JSON serializable props down.
2. **Directory & Routing Conventions**:
- Use Next.js App Router with kebab-case route folders. Group internal modules under `src/` with explicit path aliases.
- Separate data access layers into dedicated repository/service files rather than embedding direct queries inside presentation components.
3. **Form Handling & Mutations**:
- Implement Server Actions for server-side mutations. Validate incoming form payloads with Zod before running any database operation.
- Return structured status objects: `{ success: boolean, data?: T, error?: string }`.
4. **Performance & Asset Optimization**:
- Enforce `next/image` with explicit aspect ratios or `fill`. Use `next/font/google` to avoid render-blocking network requests.
5. **Code Style & Quality**:
- Enforce TypeScript in strict mode. Disallow `any` types. Provide clear interfaces for every component prop.
Please generate:
1. The suggested repository file structure for this application.
2. An actionable `AGENTS.md` / `.cursorrules` configuration block summarizing these rules for AI coding assistants.
3. A reference implementation of a Server Component paired with a minimal interactive Client Component demonstrating the data boundary.How to Use This Prompt Effectively
- 1Fill in your project scope, styling preferences, authentication provider, and database stack using the form below.
- 2Copy the assembled prompt into your AI coding tool of choice (Cursor, Claude Code, ChatGPT, Gemini, or GitHub Copilot).
- 3Store the output in a file named `AGENTS.md` or `.cursorrules` in your repository root to keep all subsequent agent interactions aligned with your architecture.
Representative AI Output
Sample output produced when using frontier AI models with the default parameters:
### Recommended Repository Structure
```text
my-nextjs-app/
├── app/
│ ├── (auth)/
│ │ ├── sign-in/[[...sign-in]]/page.tsx
│ │ └── sign-up/[[...sign-up]]/page.tsx
│ ├── dashboard/
│ │ ├── layout.tsx
│ │ └── page.tsx (Server Component)
│ ├── api/
│ │ └── webhooks/route.ts
│ ├── layout.tsx
│ └── page.tsx
├── src/
│ ├── components/
│ │ ├── ui/
│ │ └── dashboard/
│ │ ├── MetricCard.tsx (RSC)
│ │ └── DateRangePicker.tsx ('use client')
│ ├── db/
│ │ ├── schema.ts
│ │ └── index.ts
│ ├── server/
│ │ └── actions/
│ └── types/
└── AGENTS.md
```
### Generated AGENTS.md Directive
```markdown
# AI Agent Directives: Next.js App Router
- Default all component files to React Server Components.
- When client interactivity is strictly required, push `'use client'` to the leaves of the component tree.
- Never import `@/src/db` from a client component file.
- Validate every Server Action input with Zod.
```Pro Optimization & Edge-Case Tips
- Place client boundaries at the leaves of the component tree. For example, render the entire layout and page as a Server Component and isolate only the interactive button or dropdown as a Client Component.
- Use Server Actions alongside useActionState or useTransition for smooth optimistic UI updates without extra state libraries.
- Avoid placing large client-side libraries in root layout files to maintain optimal First Contentful Paint (FCP).
Related Tools on SPAUL Hub
More in Developers & Coding
View CategorySupabase Edge Function Debugging & Security Review Prompt
Diagnose runtime errors, CORS header issues, environment variable leakage, and authentication token validation bugs in Supabase Deno Edge Functions.
React Component Refactoring & Unit Test Generation Prompt
Turn bloated, legacy React components with tangled state into modular, accessible, and high-performance components backed by a production-ready test suite.
AI Coding Agent Codebase Audit & Modernization Prompt
A structured audit prompt designed for AI coding agents to evaluate an unfamiliar codebase, identify security anti-patterns, spot performance bottlenecks, and generate prioritized action plans.