AI-Native Boilerplate

Discipline for AI agents building serious software.
Stop AI drift. Enforce architecture. Save millions of tokens.

Quick Start · Architecture · What's Inside · Design System · Compliance · Extending · Cheatsheet

---

The Problem

You start coding with Claude. It's fast. It's fun. Then the codebase grows.

• AI writes code that contradicts your architecture — every session
• Requirements drift from implementation silently
• Every session re-explains the same context, burning tokens
• Patterns diverge across files with no enforcement
• Decisions get re-litigated because nobody wrote them down
• Features ship without tests because nothing enforced it
• UI looks different on every page — no design discipline
• Security, compliance, accessibility — afterthoughts

This boilerplate is the discipline layer that prevents all of that.

---

What It Is

A configurable, token-efficient boilerplate that gives AI coding agents (Claude Code, Cursor, Windsurf, Copilot, Cline) the rules, context, and enforcement they need to build production-grade software without drifting.

160+ files of discipline across 6 layers, loaded surgically — only what your project needs.

Why you'll save millions of tokens

The generator concatenates content into a single CLAUDE.md — one read, zero import overhead, zero wasted context on irrelevant rules.

---

The Architecture

┌─────────────────────────────────────────────────────────────┐
│  Layer 6: Compliance (GDPR · HIPAA · SOC2 · PCI · EU AI Act) │  ← Configurable per regulation
├─────────────────────────────────────────────────────────────┤
│  Layer 5: Custom Rules (.claude/rules/custom/)               │  ← Your overrides. Load last. Win.
├─────────────────────────────────────────────────────────────┤
│  Layer 4: Feature Rules (.claude/rules/features/)            │  ← Loaded by feature flag only
│  payments · seo · auth · auto-update · ai · i18n · realtime  │
│  email · analytics · file-uploads · error-tracking · openapi │
├─────────────────────────────────────────────────────────────┤
│  Layer 3: Design System (.claude/rules/design/)              │  ← UI/UX discipline (default: on)
│  tokens · typography · color · components · page-types       │
│  states · animation · accessibility · ux-patterns ·          │
│  agent-ux · responsive · performance · error-pages ·         │
│  email-templates                                             │
├─────────────────────────────────────────────────────────────┤
│  Layer 2: Stack Rules (.claude/rules/stack/)                 │  ← Loaded by config.stack
│  tanstack · tauri · nextjs · cloudflare · monorepo ·         │
│  cross-platform · mobile-web                                 │
├─────────────────────────────────────────────────────────────┤
│  Layer 1: Core (PRINCIPLES.md + core/ rules)                 │  ← Always loaded. Non-negotiable.
│  principles · security · git · mdd · discipline ·            │
│  conventions · nfr · testing · deployment · worktrees ·      │
│  multi-agent                                                 │
└─────────────────────────────────────────────────────────────┘

The key insight: Claude loads ONLY what is relevant to your project. A web-only app doesn't load auto-update rules. An API-only app doesn't load SEO rules. Zero token waste.

---

What's Inside

Discipline & Enforcement

Design System (15 rule files)

Compliance (configurable)

Cross-Platform

• Desktop: macOS (Intel + Apple Silicon), Windows, Linux (AppImage + .deb + .rpm)
• Web: Chrome, Firefox, Safari (WebKit), mobile Chrome, iPhone 13
• Mobile web: viewport, touch targets, iOS keyboard, PWA, offline UX
• CI: cross-browser E2E matrix on every PR

AI-Native Git Discipline

• Trunk-based or GitFlow — configurable
• Experiment branches (exp/) — try uncertain approaches, delete without guilt
• Checkpoint commits — logical units, not one giant commit
• Scope-creep check — flag anything in the diff that wasn't requested
• Work-free review loop — AI branches → implements → PRs. Human just reviews.
• Git worktrees — parallel agents get isolated working directories
• Feature flags > long branches — merge behind a flag, not a weeks-old branch

Testing & Auto-Eval Compliance

• Red Gate / Green Gate — tests must fail before implementation, pass after
• Minimum 3 assertions per test (URL + visibility + data)
• Test co-location — Component.test.tsx next to Component.tsx
• File length guard — warns at 300 lines, blocks at 500
• Eval compliance gate — AI features without evals can't ship
• Eval regression detection — score drop = blocked merge
• Eval runner template — TypeScript runner with LLM-as-judge hook

---

Getting Started

New project from this boilerplate

# Clone
git clone https://github.com/SrikanthVemulapally/ai-native-boilerplate.git my-project
cd my-project

# Install & setup
pnpm install
pnpm setup    # guided setup — fills config, generates CLAUDE.md, installs hooks

# Open in Claude Code
claude .

Then type /setup in Claude Code. That's it.

Manual setup

cp boilerplate.config.json.example boilerplate.config.json
# Edit boilerplate.config.json for your project
node scripts/generate-claude-md.js
git config core.hooksPath .githooks
chmod +x .githooks/* .claude/hooks/*.sh

One config file controls everything

{
  "profile": "web-only",
  "stack": { "frontend": "tanstack-start", "backend": "cloudflare-workers" },
  "features": {
    "payments": true,
    "auth": true,
    "seo": true,
    "i18n": true,
    "ai": false
  },
  "compliance": {
    "gdpr": true,
    "dpdpa": true,
    "pci": true,
    "hipaa": false,
    "soc2": false,
    "eu_ai_act": false
  },
  "designSystem": {
    "headingFont": "inter",
    "baseColor": "neutral",
    "darkMode": "system"
  },
  "gitStrategy": "trunk"
}

Run node scripts/generate-claude-md.js → Claude gets exactly the rules it needs. Nothing more.

---

Profiles

agent-web enforces auto-update as mandatory. An agent without auto-update is not shippable.

---

Extensibility

See EXTENDING.md for the full guide. Quick version:

• New stack? One .md file + one line in generator
• New feature? One .md file + one line in generator
• Override anything? Drop .md in rules/custom/ — loads last, always wins
• New profile? One .json file
• New command? Drop .md in .claude/commands/ — immediately available

Works with: Claude Code (native) · Cursor (.cursorrules) · Windsurf (.windsurfrules) · Copilot (.github/copilot-instructions.md) · Cline (.clinerules)

---

Quick Reference

See CHEATSHEET.md for the one-page scannable reference of all commands, hooks, and rules.

---

Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines.

---

License

MIT — use it, fork it, sell it, build your empire with it.

---

If this saved you tokens, give it a ⭐

Built by Srikanth Vemulapally · for builders who take AI-native coding seriously.