DEV Community

Cover image for Under 30-Minute Setup: AI Coding Guidelines for Your Next.js Project (Before/After Code)
yunbow
yunbow

Posted on

Under 30-Minute Setup: AI Coding Guidelines for Your Next.js Project (Before/After Code)

#nextjs #typescript #aitools #aidevos

Your Next.js project has an AI assistant. The question isn't whether to use AI — it's whether the code it generates follows your project's conventions.

This is a hands-on walkthrough. In under 30 minutes (10 via CLI, 20 manually), you'll install AI Dev OS into an existing Next.js project using Claude Code. By the end, your AI will consistently apply your naming conventions, security patterns, and architectural rules — without you reminding it every prompt.

All examples show before/after code so you can see exactly what changes.

What You're Installing (5 min)

AI Dev OS uses a 4-layer model. For a Next.js project, here's what goes where:

CLAUDE.md                     ← L1 + L2: Always loaded, project philosophy
.claude/guidelines/
  nextjs.md                   ← L3: App Router, Server Actions, Middleware
  typescript.md               ← L3: Type conventions, naming rules
  security.md                 ← L3: Auth patterns, input validation
.claude/commands/             ← L4: Reusable Skills for common tasks
Enter fullscreen mode Exit fullscreen mode

The rules you care about most day-to-day live in guidelines/. They're loaded when relevant — not every single prompt — so they don't dilute Claude's attention on your actual task.

Prerequisites 

Node.js >= 18
Next.js >= 14 (App Router)
Claude Code CLI installed
TypeScript (strict mode strongly recommended)
Enter fullscreen mode Exit fullscreen mode

Already have a running Next.js project? Good — work from there. Starting fresh also works.

Option A: CLI Setup (10 min)

The fastest path:

npx ai-dev-os init --rules typescript --plugin claude-code
Enter fullscreen mode Exit fullscreen mode

This generates:

  • CLAUDE.md — guidelines index (3 directive lines + file references)
  • docs/ai-dev-os/ — rule submodule with L1–L3 guidelines for TypeScript/Next.js
  • .claude/plugins/ai-dev-os/ — Skills, Agents, and Hooks (L4)
  • Pre-commit hooks for automated rule verification

After it runs, open CLAUDE.md and add your project-specific guideline files to the ## Project-Specific Guidelines section (3 files is the recommended starting point).

Verify the setup:

npx ai-dev-os doctor
Enter fullscreen mode Exit fullscreen mode

Output should show all guideline files detected and no configuration conflicts.

Option B: Manual Setup (20 min)

Manual setup takes longer but gives you a clear mental model of what each file does. Recommended if you want to adapt the rules heavily.

Step 1: Add the rule submodule and copy the CLAUDE.md template 

# Add L1–L3 rules for TypeScript/Next.js
git submodule add https://github.com/yunbow/ai-dev-os-rules-typescript.git docs/ai-dev-os
git submodule update --init

# Add Claude Code plugin (Skills, Agents, Hooks)
git submodule add https://github.com/yunbow/ai-dev-os-plugin-claude-code.git .claude/plugins/ai-dev-os

# Copy the CLAUDE.md template
cp docs/ai-dev-os/templates/nextjs/CLAUDE.md.template ./CLAUDE.md
Enter fullscreen mode Exit fullscreen mode

CLAUDE.md is an index file — 3 directive lines followed by references to guideline files in the submodule. Open it and fill in your project name, then add project-specific guideline files in the ## Project-Specific Guidelines section:

## Project-Specific Guidelines
- docs/guidelines/your-business-rule.md
- docs/guidelines/your-external-api.md
- docs/guidelines/your-compliance.md
Enter fullscreen mode Exit fullscreen mode

3 files is the recommended starting point. Create these files in docs/guidelines/ and document the rules specific to your project (auth provider choices, external service integrations, business constraints).

Step 2: Understand what the submodule provides

The docs/ai-dev-os/ submodule already contains comprehensive L3 guidelines. Key files for a Next.js project:

docs/ai-dev-os/03_guidelines/
  frameworks/nextjs/
    overview.md         ← App Router conventions, tech stack overview
    api.md              ← API route patterns (auth check, field selection)
    server-actions.md   ← ActionResult<T> pattern, Zod validation
    auth.md             ← NextAuth integration
    database.md         ← Prisma usage, no raw SQL
  common/
    security.md         ← Auth invariants, data exposure prevention
    validation.md       ← Zod schema placement and usage
    error-handling.md   ← Error patterns
    naming.md           ← Naming conventions
Enter fullscreen mode Exit fullscreen mode

These files contain the concrete rules with examples — including the patterns shown in the Before/After section below. You don't write these; they come with the submodule.

Step 3: Create the ActionResult type

If you don't have it already:

// types/action.ts
export type ActionResult<T = void> =
  | (T extends void ? { success: true } : { success: true; data: T })
  | { success: false; error: string }
Enter fullscreen mode Exit fullscreen mode

This conditional type handles the common void case — Server Actions that return no data can use return { success: true } without a data field, while actions that return data get a fully typed { success: true; data: T }.

Verification: Test Before/After

The best way to confirm your setup is working: ask Claude the same task twice — before applying guidelines, after.

Test prompt:

Create an API route at app/api/profile/route.ts that returns 
the current user's profile data from the database.
Enter fullscreen mode Exit fullscreen mode

Before (no guidelines, typical output):

import { prisma } from '@/lib/prisma'

export async function GET(request: Request) {
  const userId = request.headers.get('x-user-id')
  const user = await prisma.user.findUnique({ where: { id: userId } })
  return Response.json(user)
}
Enter fullscreen mode Exit fullscreen mode

Problems: takes user ID from a header (trivially spoofable), returns the entire user object including password hash and tokens, no error handling if user not found. Also note the import uses prisma from @/lib/prisma — in the conventions we're setting up, the db client is exposed as db from @/lib/db for consistency.

After (with guidelines loaded):

import { auth } from '@/lib/auth'
import { db } from '@/lib/db'

export async function GET(): Promise<Response> {
  const session = await auth()
  if (!session) {
    return Response.json({ error: 'Unauthorized' }, { status: 401 })
  }

  const user = await db.user.findUnique({
    where: { id: session.user.id },
    select: {
      id: true,
      name: true,
      email: true,
      image: true,
      createdAt: true,
    },
  })

  if (!user) {
    return Response.json({ error: 'Not found' }, { status: 404 })
  }

  return Response.json({ data: user })
}
Enter fullscreen mode Exit fullscreen mode

Auth from session (not headers). Explicit field selection. Error cases handled. Consistent response shape.

Before / After: Server Action

Test prompt:

Create a Server Action to update the current user's display name.
Enter fullscreen mode Exit fullscreen mode

Before:

'use server'
import { prisma } from '@/lib/prisma'

export async function updateDisplayName(name: string) {
  await prisma.user.update({
    where: { id: 'user_id_here' },
    data: { name },
  })
}
Enter fullscreen mode Exit fullscreen mode

Problems: hardcoded placeholder ID, no validation, no auth, no return value.

After:

'use server'
import { z } from 'zod'
import type { ActionResult } from '@/types/action'
import { auth } from '@/lib/auth'
import { db } from '@/lib/db'

const UpdateNameSchema = z.object({
  name: z.string().min(1, 'Name is required').max(100, 'Name too long'),
})

export async function updateDisplayName(
  formData: FormData
): Promise<ActionResult<void>> {
  const session = await auth()
  if (!session) return { success: false, error: 'Unauthorized' }

  const parsed = UpdateNameSchema.safeParse({ name: formData.get('name') })
  if (!parsed.success) return { success: false, error: parsed.error.message }

  await db.user.update({
    where: { id: session.user.id },
    data: { name: parsed.data.name },
  })

  return { success: true }
}
Enter fullscreen mode Exit fullscreen mode

Loading Guidelines in Practice

The Skills bundled with ai-dev-os-plugin-claude-code handle contextual loading automatically. For example, the /api skill loads the relevant framework and security guidelines before generating code.

You can also reference guidelines directly in your prompt:

@docs/ai-dev-os/03_guidelines/frameworks/nextjs/server-actions.md
Create a Server Action to update the current user's display name.
Enter fullscreen mode Exit fullscreen mode

Or add a project-specific skill in .claude/commands/api.md that loads your project-specific rules alongside the framework guidelines:

Load the API and security guidelines, then complete the task:

@docs/ai-dev-os/03_guidelines/frameworks/nextjs/api.md
@docs/ai-dev-os/03_guidelines/common/security.md
@docs/guidelines/your-business-rule.md

Task: $ARGUMENTS
Enter fullscreen mode Exit fullscreen mode

Now in Claude Code: /api Create a route for updating user preferences

Next Steps

Add your project-specific rules. The submodule provides the framework-level rules. Create docs/guidelines/ files for your project's business logic, external API integrations, and compliance requirements — these go in the ## Project-Specific Guidelines section of CLAUDE.md.

Commit the submodule reference to git. Team members who clone the repo run git submodule update --init --recursive and get the full guideline set automatically.

Keep the submodule updated. Run git submodule update --remote docs/ai-dev-os to pull the latest rules, or pin to a specific version with git checkout v1.x.x inside the submodule.

The full ruleset (with Python/FastAPI support) is at github.com/yunbow/ai-dev-os.

What Next.js patterns does your team enforce that keep slipping through AI-generated code? I'm collecting edge cases to improve the default ruleset.

Top comments (0)