vibecodex — vibe coding rules for production

54 production architecture principles your AI coding agent (Claude Code, Cursor) follows automatically. Drop-in CLAUDE.md, .cursor/rules/, and .claude/skills/ for FastAPI, Next.js 15, and Go 1.22+. MIT.

npx @aimyerdaulet/vibecodex init

📘 Principles · 🐍 FastAPI example · ⚡ Next.js example · 🐹 Go example · 🤖 Claude skills · 🌐 vibecodex.dev

---

What is vibecodex?

vibecodex is the clean-code bible for vibe coding — 54 numbered architecture principles (A1–F10) that turn AI coding agents from fast juniors into disciplined seniors. You drop one CLAUDE.md plus a folder of Cursor rules into your repo, and from the next prompt every Claude Code or Cursor session follows production patterns: file size limits, anti-corruption layers, idempotency keys, bulkhead isolation, single-writer invariants, hexagonal boundaries.

It's built for vibe coders, solo devs, and indie hackers who ship fast with AI but don't want their Friday-night SaaS to become an unmaintainable 1,400-line router by Sunday.

Three stacks. One ruleset. Zero dependencies on a specific agent.

---

📖 Table of Contents

• 🚀 Quick Start
• 🚨 The problem
• 🛠️ 54 Production Principles
  • 🐍 FastAPI — Part A: Safe Decomposition (8)
  • 🐍 FastAPI — Part B: Integration Patterns (10)
  • ⚡ Next.js — Part C: Decomposition (10)
  • ⚡ Next.js — Part D: Modern Patterns (6)
  • 🐹 Go — Part E: Decomposition (8)
  • 🐹 Go — Part F: Integration Patterns (10)
• 📂 Directory Structure
• 🚀 Reference Implementations
• 🤖 Claude Code Skills
• 🛠️ Copy-Paste AI Config
• 📊 vs Other Templates
• ❓ FAQ
• 🎯 When to use this blueprint
• 🤝 Contributing
• 📜 Citations

---

🚀 Quick Start

# Add vibecodex rules to your project (any stack)
git clone https://github.com/yerdaulet-damir/vibe-coding-rules.git /tmp/vibecodex

# 1. Drop CLAUDE.md into your repo root — Claude reads it on every session
cp /tmp/vibecodex/CLAUDE.md ./

# 2. Copy Cursor rules
cp -r /tmp/vibecodex/.cursor/rules/ .cursor/rules/

# 3. Copy Claude Code skills (debug-backend, new-feature, split-monolith, etc.)
cp -r /tmp/vibecodex/.claude/skills/ .claude/skills/

That's it. Your AI agent now follows 54 production principles from line one.

For new projects, start from one of the reference apps:

Stack	Command	What you get
FastAPI	cp -r /tmp/vibecodex/reference/app/ ./backend/app/	Hexagonal Python with credits, providers, async jobs
Next.js 15	cp -r /tmp/vibecodex/examples/nextjs/ ./frontend/	RSC + typed cache-tag DSL + Drizzle + Better Auth
Go 1.22+	cp -r /tmp/vibecodex/examples/go/ ./service/	cmd/+internal/ + bulkhead clients + graceful shutdown

---

🚨 The problem

You start a project on Friday. By Sunday you have 14 endpoints, a working LLM integration, OAuth, Stripe, and a deploy pipeline. The AI is moving fast. So are you. Everything works.

Six weeks later, routers/generate.py is 1400 lines, services/ai_router.py ships a dict from OpenAI directly into your billing logic, the SQLAlchemy Session reaches into every layer including the JWT decoder, and a single hung httpx call to one provider exhausts your file descriptors and takes down image, video, and audio at once. The AI is still moving fast — but now every change touches eight files, breaks two of them, and your test suite mocks Session 47 different ways.

This isn't an AI failure. AI assistants produce structurally correct, locally optimal code. What they don't enforce — and what no template enforces by default — is architectural consistency at scale: layer boundaries, file size, ports & adapters, single-writer invariants, bulkhead isolation, typed cache-tag DSLs, hexagonal domain boundaries, idempotency keys, graceful shutdown rituals.

This repo codifies all of it into 54 rules that fit on a few pages, ship as CLAUDE.md + .cursor/rules/ + .claude/skills/, and turn your AI partner from a fast junior into a disciplined senior — across FastAPI, Next.js 15, and Go 1.22+.

---

🛠️ 54 Production Principles

The vibecodex blueprint covers 6 parts spanning Python, TypeScript, and Go — each one solving a recurring failure mode of vibe-coded apps:

#	Stack	Part	Focus	Principles
A	🐍 FastAPI	Decomposition	folder/file boundaries, single-writer	8
B	🐍 FastAPI	Integration	hexagonal, ACL, bulkhead, idempotency, observability	10
C	⚡ Next.js	Decomposition	feature-driven colocation, RSC defaults	10
D	⚡ Next.js	Modern (2024-25)	typed cache-tag DSL, use(), PPR, Better Auth, Drizzle	6
E	🐹 Go	Decomposition	internal/, consumer-side interfaces, no utils	8
F	🐹 Go	Integration	context.Context first, errgroup, bulkhead, graceful shutdown	10
Σ				54

🧩 Part A — Safe Decomposition (8 principles)

How to split files and folders without breaking imports and without losing the thread of the codebase.

1. Folder-instead-of-file when domain splits by type. If routers/generate.py is st