Drop-in security rules, architectural standards, and AI-agent constraints for modern web applications.
Last Updated: 2026-04-11
Guardrails is a collection of drop-in security rules and architectural standards designed to fix the "Security Gap" in AI coding agents.
Tools like Cursor, Windsurf, Copilot, and Gemini can write code at light speed — but they often skip critical production constraints like input validation, rate limiting, auth guards, and secure environment handling.
Guardrails forces these agents to move from "vibe-coding" to "engineering" by injecting a strict, framework-specific security and architecture layer into your project that the AI agent reads and enforces on every file it touches.
Guardrails provides two production-ready suites. Pick the one that matches your stack.
Best for: Teams building with Next.js using the App Router, Server Actions, and React Server Components.
This is a server-first architecture. Pages are React Server Components by default. Interactivity is isolated to Client Components in a components/ folder. Data mutations flow through a secure Server Action guard layer — never directly from the browser to the backend.
Key Features:
- ✅ Server Actions with Guard Layer —
requireAuth()→requireRateLimit()→schema.validate()on every action - ✅ RSC-First Pages — All
page.tsxfiles are Server Components."use client"is isolated tocomponents/ - ✅ Metadata & SEO — Every page exports
metadataorgenerateMetadata(). No raw<head>tags - ✅ Data Access Layer (DAL) — Centralized
lib/dal.tswithverifySession()+React.cache() - ✅
next/image+next/font— Mandatory. No raw<img>or Google Fonts CDN links - ✅ Caching Strategy —
use cachedirective,revalidateTag, v15fetch()breaking change documented - ✅ Middleware (v15) / Proxy (v16) — Edge-side auth and header injection
- ✅ Spec-Driven Development — Track implementation vs. FRS/SRS via
spec/ - ✅ TDD: Jest + SWC + Playwright — Official Next.js testing stack (not Vitest)
npm create guardrails nextjsBest for: Teams building a pure client-side Single Page Application with React and Vite.
This is a client-first architecture. There is no server rendering. All data fetching is done through TanStack Query hooks calling a separate backend API via a secure Axios instance. State is managed with React Context and React Query — no Redux.
Key Features:
- ✅ Secure Axios Layer — One centralized instance with interceptors. Never
fetch()inline - ✅ TanStack Query — All server state via
useQuery/useMutationhooks inhooks/api/ - ✅ Protected Route Pattern —
<PrivateRoute>wrapper using React Router<Outlet> - ✅ No
localStoragefor tokens — RecommendsHttpOnlycookies via backend. FlagslocalStorageas XSS-vulnerable - ✅ Accessibility (a11y) — WCAG 2.1 AA enforced: semantic HTML, ARIA, keyboard navigation
- ✅ Asset Indexing — All images imported through
src/assets/index.tsfor Vite cache-busting - ✅ TDD: Vitest + RTL + Playwright — Full test coverage enforced per component
- ✅ Spec-Driven Development — Track implementation vs. FRS/SRS via
spec/ - ✅
<Link>over<a>— React Router navigation enforced. No full-page reloads in SPA
npm create guardrails reactnextjs-app-router |
react-vite |
|
|---|---|---|
| Rendering | Server-first (RSC + SSR) | Client-first (SPA) |
| Routing | Next.js App Router (file-based) | React Router / TanStack Router |
| Data fetching | Server Actions + DAL | TanStack Query → Backend API |
| Auth pattern | Server-side verifySession() + DAL |
Client-side useAuth() + <PrivateRoute> |
| API calls | Server Actions (no direct client→API) | Axios instance from browser |
| Image handling | next/image |
src/assets/ import pattern |
| Testing | Jest + SWC + Playwright | Vitest + RTL + Playwright |
| Best for | Content-heavy apps, SEO-critical, dashboards | SPAs, portals, internal tools |
Not sure? If you're using
next dev→ picknextjs-app-router. If you're usingvite→ pickreact-vite.
Once you run the CLI and the .agent/ folder is in your project root, point your AI 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 will discover all rules, security constraints, and architectural patterns automatically.
You can easily add your own project-specific rules while maintaining the Guardrails standard. Use the built-in skill generator:
npx create-guardrails --add-skill MyProjectRuleThis automatically creates a directory at .agent/skills/MyProjectRule/SKILL.md with the required YAML frontmatter.
- Next.js App Router suite (v15 & v16)
- React + Vite suite (React 19)
- Unified
npm create guardrailsCLI — live on NPM - Public GitHub launch +
CONTRIBUTING.md - CI/CD: Auto-publish to NPM on merge
- Remix suite
- SvelteKit suite
We welcome contributions from the community. Adding a new security rule, fixing a doc, or proposing an entirely new framework suite are all valid contributions.
➡️ See CONTRIBUTING.md (coming soon)
MIT — Build fast. Ship secure.