Download the MD files HERE
Download the MDc files for Cursor HERE
Download the Single MD file HERE

Stop fighting your AI. Start giving it an architecture.

Large Language Models (LLMs) have become incredible coding assistants. They can scaffold projects, generate components, write tests, and even refactor entire codebases in minutes.

But there's one major problem.

Without clear architectural boundaries, AI will often generate code that works—but doesn't scale.

You'll commonly see it:

• 🍝 Mixing database queries directly inside React components
• 🎨 Repeating the same Tailwind utility classes across dozens of files
• ⚡ Using outdated React patterns instead of modern Next.js App Router features
• 🔐 Skipping validation and authorization checks
• 📦 Creating unnecessary client-side state
• 🚫 Ignoring accessibility, SEO, and Core Web Vitals

The result?

A project that becomes harder to maintain with every AI-generated feature.

If you want your AI to behave like a Senior Software Architect instead of a junior developer, you need to provide it with a clear engineering playbook.

That's exactly what the 5-Pillar Architecture accomplishes.

Instead of placing thousands of lines of instructions into one massive prompt, you split your engineering standards into focused rule files that are automatically loaded when they're needed.

The result is cleaner code, fewer hallucinations, better consistency, and dramatically improved developer experience.

Download the MD files HERE
Download the MDc files for Cursor HERE
Download the Single MD file HERE

🏛️ The 5-Pillar Architecture

The idea is simple.

Rather than giving your AI every instruction every time, divide your project standards into specialized domains.

For example:

This focused approach has several benefits:

• 🚀 Faster responses
• 🧠 Better reasoning
• 💰 Lower token usage
• 📚 More maintainable instructions
• 🎯 Consistent architecture across your entire project

Let's explore each pillar.

🧠 Pillar 1 — Global Core Architecture (global.md / global.mdc)

This is the foundation of your entire application.

Think of it as your project's engineering handbook.

Every AI-generated feature should follow these rules regardless of whether you're building authentication, dashboards, APIs, or UI components.

🔒 Zero-Trust Data Access Layer (DAL)

One of the most common mistakes AI makes is querying the database directly from UI components.

For example:

const users = await prisma.user.findMany()

inside a page or component.

While this works, it tightly couples your presentation layer to your database.

Instead, enforce a Zero-Trust Data Access Layer.

Every database request should follow a predictable flow:

React Component
        ↓
Server Action / Route Handler
        ↓
Data Access Layer (DAL)
        ↓
Database

This separation provides several advantages:

• 🔐 Improved security
• 🧪 Easier testing
• ♻️ Better code reuse
• 📦 Cleaner abstractions
• 🚀 Easier migrations later

Your UI should never know how the database works.

♻️ Extreme DRY Enforcement

AI loves copying code.

Unfortunately, that's one of the quickest ways to create technical debt.

Suppose the AI repeatedly generates:

<div className="mx-auto max-w-7xl px-6 py-12">

across multiple pages.

Instead of duplicating the same utilities, your rules should encourage the AI to identify reusable design patterns and extract them into components such as:

<Container />
<Section />
<PageHeader />
<Spacer />

This keeps your codebase:

• Cleaner
• Easier to update
• More consistent
• More scalable

If your designer changes spacing six months later, you'll update one component instead of fifty.

🎯 Smart Prompt Routing

Not every request needs every rule.

If you ask:

"Build a Hero Section"

The AI doesn't need database rules.

Likewise, if you're implementing authentication, animation guidelines aren't particularly useful.

Your global rules should encourage the AI to first classify the request before loading additional architectural context.

This keeps prompts lightweight while improving response quality.

🎨 Pillar 2 — UI, UX & Animations (ui-ux-animations.md)

Great software isn't only functional.

It should also feel polished.

This pillar transforms your AI from simply generating HTML into producing interfaces that look modern, professional, and enjoyable to use.

🎨 Build with Modern Design Systems

Instead of creating every component from scratch, encourage your AI to leverage modern UI ecosystems whenever appropriate.

Examples include:

• ✨ shadcn/ui
• 🚀 21st.dev
• 🌈 Origin UI
• 💎 Aceternity UI
• 🎭 Magic UI

These libraries provide production-ready components that save development time while maintaining excellent design quality.

⚡ The Animation Split

Not all animations should use the same library.

Your AI should understand which tool is appropriate for the job.

🎯 Framer Motion

Ideal for:

• Hover interactions
• Buttons
• Cards
• Dialogs
• Tooltips
• Page transitions
• Micro-interactions

🚀 GSAP

Best suited for:

• Scroll-triggered animations
• Landing pages
• Storytelling experiences
• Complex timelines
• Hero reveals
• Interactive marketing websites

A simple rule works well:

Small interactions → Framer Motion

Large storytelling animations → GSAP

🎨 Emotion CSS Boundaries

Tailwind CSS should remain the default styling solution.

However, occasionally you'll need styles driven by runtime props that Tailwind cannot reasonably express.

In those situations, Emotion can be used—but only within "use client" components and only for truly dynamic styling.

This prevents unnecessary runtime styling throughout the application.

🗄️ Pillar 3 — API, Database & State Management (api-db-state.md)

Modern Next.js applications don't need a massive state management library for every feature.

Unfortunately, AI assistants often default to unnecessary complexity.

This pillar teaches your AI how data should flow through the application.

🚀 Prefer Native Next.js Features

Before introducing additional libraries, the AI should first consider:

• ✅ Server Components
• ✅ Server Actions
• ✅ URL Search Params
• ✅ React Cache
• ✅ Suspense
• ✅ Streaming

The less client-side JavaScript your application ships, the better.

🪶 Zustand vs Redux

Every state management library has its place.

Use Zustand for lightweight UI state:

• Dark mode
• Mobile navigation
• Modals
• Toasts
• Filters
• Preferences

Use Redux Toolkit only when your application genuinely requires enterprise-level state management, such as:

• Complex dashboards
• Collaborative applications
• Offline synchronization
• Deeply nested shared state

Choosing the simplest solution keeps your application easier to maintain.

⚡ Optimistic UI

Waiting for every server response creates a sluggish user experience.

Instead, encourage your AI to implement optimistic updates whenever possible.

Use tools like:

• useOptimistic
• Cache mutation
• React transitions

This allows the interface to update immediately while the server processes the request in the background.

Users perceive the application as significantly faster.

🔐 Pillar 4 — Security Hardening (security.md)

Security shouldn't be an afterthought.

Unfortunately, AI often prioritizes convenience over safety.

Your security rules establish non-negotiable guardrails.

🚫 Never Leak Internal Errors

Never expose:

• SQL errors
• Prisma errors
• Stack traces
• Environment variables
• Internal exception messages

Instead, return predictable responses such as:

{
  success: false,
  error: "Unable to update profile."
}

Detailed logs should remain on the server where developers can safely inspect them.

✅ Validate Everything Twice

Client-side validation improves user experience.

Server-side validation protects your application.

Your AI should always validate data twice.

Client:

• Zod

Server:

schema.parseAsync(data)

Never assume the client is trustworthy.

👤 Authorization Before Mutation

Authentication only proves who the user is.

Authorization determines what they're allowed to do.

Before updating or deleting data, verify:

• Is the user authenticated?
• Does the user own this resource?
• Does their role permit this action?

These checks dramatically reduce accidental security vulnerabilities.

🌍 Pillar 5 — SEO & Core Web Vitals (seo-web-vitals.md)

Building a beautiful application isn't enough.

People—and increasingly AI systems—need to discover it.

This pillar helps your application perform well for both traditional search engines and AI-powered search experiences.

🤖 Generative Engine Optimization (GEO)

Search is changing.

Platforms like ChatGPT, Perplexity, Gemini, and Claude increasingly summarize content instead of simply returning links.

To improve discoverability, encourage your AI to generate:

• Semantic HTML
• Structured data
• Clear factual content
• llms.txt
• Consistent metadata
• Verifiable references where appropriate

These practices make your content easier for AI systems to understand and reference.

🚀 Protect Core Web Vitals

Performance directly impacts user experience and search visibility.

Your rules should remind the AI to:

• Prioritize hero images
• Lazy-load non-critical assets
• Optimize fonts
• Prevent layout shifts
• Minimize unnecessary JavaScript

Small improvements here can have a significant impact on perceived performance.

🏷️ Semantic HTML

Avoid generic <div> structures whenever meaningful HTML elements exist.

Prefer:

• <header>
• <main>
• <section>
• <article>
• <aside>
• <footer>

Semantic HTML improves accessibility, SEO, and overall code readability.

⚙️ Setting Up the Rules

The architecture consists of two file formats:

You may keep both versions in your repository depending on which AI tools your team uses.

🖥️ Installing the Rules in Cursor

Cursor provides first-class support for .mdc files, making it the best experience for modular AI instructions.

Unlike regular Markdown, .mdc files include YAML frontmatter that tells Cursor when a rule should be applied.

Step 1 — Create the Rules Directory

Create the following folder structure inside your project:

my-nextjs-app/
│
├── .cursor/
│   └── rules/
│       ├── global.mdc
│       ├── ui-ux-animations.mdc
│       ├── api-db-state.mdc
│       ├── security.mdc
│       └── seo-web-vitals.mdc
│
├── app/
├── components/
├── lib/
└── package.json

Keeping every rule inside .cursor/rules makes them easy to organize and allows Cursor to discover them automatically.

Step 2 — Configure the Global Rule

Your global architecture should always be active.

At the top of global.mdc, add YAML frontmatter similar to:

---
description: Global Architecture Rules
alwaysApply: true
---

Everything below this frontmatter becomes part of your project's permanent architectural guidance.

Step 3 — Configure Domain-Specific Rules

The remaining rule files should only load when they're relevant.

For example:

---
description: UI & Animation Rules
alwaysApply: false

globs:
  - "**/*.tsx"
  - "**/*.css"
---

Likewise:

Download the MDc files for Cursor HERE

• api-db-state.mdc should target API routes, server actions, and database-related files.
• security.mdc should target authentication, authorization, and validation logic.
• seo-web-vitals.mdc should target layouts, pages, metadata, and SEO-related files.

This selective loading keeps AI context focused and efficient.

Step 4 — Start Building

Once the rules are in place, simply work as you normally would.

As you move between files, Cursor automatically loads the relevant rule files in the background.

For example:

There's no need to remind Cursor which rules to follow—they're applied automatically based on the file you're editing.

🤖 Installing the Rules in Claude Projects

Claude doesn't currently support .mdc files, so you'll use the standard .md versions instead.

Step 1 — Create a Project

Open Claude and create a new Project for your Next.js application.

Projects allow Claude to retain shared knowledge across conversations, making them ideal for architectural documentation.

Step 2 — Upload the Rule Files

Navigate to Project Knowledge and upload:

• global.md
• ui-ux-animations.md
• api-db-state.md
• security.md
• seo-web-vitals.md

These documents become part of Claude's project knowledge and can be referenced throughout your development workflow.

Download the MD files HERE

Step 3 — Add a Custom Instruction

In your project's Custom Instructions, add something like:

Before generating any code, review the uploaded architecture documents. Always apply the rules from global.md, then selectively reference the appropriate domain-specific documents based on the current task. Follow these architectural standards unless I explicitly instruct otherwise.

This encourages Claude to consistently follow your architecture without requiring you to repeat the same instructions in every conversation.

🌊 Installing the Rules in Windsurf / Antigravity

Unlike Cursor, Windsurf and Antigravity don't currently support automatic modular loading of .mdc rule files.

Instead, use the standard .md versions and consolidate them into a single project rules file.

Create either a .windsurfrules or .antigravityrules file in the root of your project (depending on your IDE), then merge the contents of your five Markdown rule files into that document.

To keep the file organized and easy for the AI to navigate, separate each section with descriptive XML-style tags, such as:

<GlobalArchitecture>
...
</GlobalArchitecture>

<UI_UX>
...
</UI_UX>

<API_DB_State>
...
</API_DB_State>

<Security>
...
</Security>

<SEO_WebVitals>
...
</SEO_WebVitals>

This gives the AI a single source of truth while preserving the logical separation between each architectural pillar.

Download the Single MD file HERE

🎯 Final Thoughts

AI coding assistants are only as good as the architecture you provide.

Instead of relying on massive prompts for every feature, give your AI a structured engineering playbook.

By separating your standards into five focused rule files, you'll get:

🏗️ Cleaner architecture
🔒 Stronger security
🎨 Better UI and animations
⚡ Faster performance
🌍 Improved SEO
🤖 More reliable AI-generated code
🧩 Consistent patterns across your entire codebase

Treat your AI like a new engineer joining your team: give it clear architecture, well-defined boundaries, and reusable standards. The result is cleaner code, fewer surprises, and applications that scale gracefully as your project grows.

Download the MD files HERE
Download the MDc files for Cursor HERE
Download the Single MD file HERE