🛡️ create-guardrails

Core Principle: You are the Architect, the AI is the Builder. Guardrails is the Building Code.

Stop "Vibe Coding" and start engineering. Drop-in security rules, architectural standards, and AI-agent constraints for Next.js and React + Vite projects.

🏗️ Converting "Vibe Coding" into Engineering

AI agents (Cursor, Claude, Gemini) are incredible at "Vibe Coding" — generating functional code at lightning speed. However, they naturally drift toward technical debt and inconsistent patterns if left unsupervised.

Guardrails ensures that the AI doesn't cut corners on the foundation. It provides a hard-coded set of architectural and security constraints that keep the AI aligned with your engineering vision, converting it from a fast-but-loose coder into a disciplined builder.

🚀 Quick Start

Run this in any project root — no installation needed:

npm create guardrails

Or go straight to your framework:

npm create guardrails nextjs    # Next.js 15 & 16 (App Router)
npm create guardrails react     # React 19 + Vite (SPA)

With your AI agent pre-selected:

npm create guardrails nextjs --gemini
npm create guardrails nextjs --cursor
npm create guardrails nextjs --claude

npm create guardrails react --gemini
npm create guardrails react --cursor
npm create guardrails react --claude

📦 What Gets Installed

Running the command injects a .agent/ folder into your project root containing production-grade documentation that your AI agent reads and enforces on every file it touches.

your-project/
├── .agent/
│   ├── Overview.md         ← Tech stack, core principles, agent protocol
│   └── skills/
│       ├── SecurityAndAPI/
│       │   └── SKILL.md
│       ├── TestingStrategy/
│       │   └── SKILL.md
│       ├── ProjectStructure/
│       │   └── SKILL.md
│       └── ... (20+ skill folders)
│   └── spec/
│       └── SpecStatus.md    ← Track implementation vs. FRS/SRS contracts
└── GEMINI.md (or .cursor.md / claude.md)  ← Agent activation file

🟦 Next.js App Router Suite

For teams using Next.js 15 or 16 with the App Router, Server Actions, and React Server Components.

Enforces:

• ✅ Server Actions with requireAuth() → requireRateLimit() → schema.validate() guards
• ✅ RSC-first pages — "use client" isolated to components/ only
• ✅ Metadata & SEO — metadata export required on every page.tsx
• ✅ Data Access Layer — lib/dal.ts with verifySession() + React.cache()
• ✅ next/image + next/font mandatory, no raw <img> or CDN font links
• ✅ Caching strategy — use cache directive, revalidateTag, v15 breaking change documented
• ✅ Middleware (v15) / Proxy (v16) gateway
• ✅ TDD: Jest + SWC + Playwright
• ✅ Spec-Driven: FRS/SRS compliance tracking via spec/

⚡ React + Vite Suite

For teams building a React 19 SPA with Vite and a separate backend API.

Enforces:

• ✅ Secure Axios instance with request interceptors
• ✅ TanStack Query for all server state (useQuery / useMutation)
• ✅ Protected Route pattern — <PrivateRoute> with React Router <Outlet>
• ✅ HttpOnly cookie sessions — localStorage flagged as XSS-vulnerable
• ✅ Accessibility (a11y) — WCAG 2.1 AA: semantic HTML, ARIA, keyboard navigation
• ✅ Asset indexing — all images through src/assets/ for Vite cache-busting
• ✅ TDD: Vitest + React Testing Library + Playwright
• ✅ Spec-Driven: FRS/SRS compliance tracking via spec/

🤖 Activating Your AI Agent

Once .agent/ is in your project, point your agent at it:

Gemini / Antigravity:

Read @.agent/Overview.md before starting any task.

Cursor (.cursorrules):

@.agent/Overview.md

Claude (claude.md):

@.agent/Overview.md

The agent discovers all security rules, architectural patterns, and enforcement protocol automatically.

🛠️ Extending Your Suite (Add Rules)

You can add project-specific rules while maintaining the generic standards. Use the integrated skill generator:

npx create-guardrails --add-skill MyProjectRule

This creates a directory at .agent/skills/MyProjectRule/SKILL.md with the required boilerplate and YAML frontmatter.

🔗 Links

• GitHub Repository
• NPM Package
• Browse Next.js Docs
• Browse React Docs

📝 License

MIT — Build fast. Ship secure.