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.

---

<details> <summary><b>📖 Table of Contents</b></summary>

• 🚀 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

</details>

---

🚀 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 starting to handle image, video, audio, convert it to a package routers/generate/{image.py,video.py,audio.py,__init__.py} and re-export the combined router. main.py doesn't change.

   <details><summary>before / after</summary>

   # BEFORE — routers/generate.py (820 lines, three domains tangled)
   @router.post("/image")
   async def generate_image(...): ...
   @router.post("/video")
   async def generate_video(...): ...
   @router.post("/audio")
   async def generate_audio(...): ...
   

   # AFTER — routers/generate/__init__.py
   from fastapi import APIRouter
   from .image import router as image_router
   from .video import router as video_router
   from .audio import router as audio_router
   
   router = APIRouter(prefix="/generate", tags=["generate"])
   router.include_router(image_router)
   router.include_router(video_router)
   router.include_router(audio_router)
   

   main.py keeps from app.routers.generate import router — zero caller changes.

   </details>

2. Static data ≠ runtime logic. Pricing tables, model registries, prompt templates go into data/ (or <domain>/registry.py), never inline in a service file. Updating a price = a one-line PR, not a refactor.

   <details><summary>before / after</summary>

   # BEFORE — services/ai_service.py
   PRICING = {"gpt-4o": 0.005, "claude-3-5": 0.003, ...}  # 80 lines of constants
   class AIService: ...
   

   # AFTER — data/model_pricing.py
   from decimal import Decimal
   PRICING: dict[str, Decimal] = {
       "gpt-4o":     Decimal("0.005"),
       "claude-3-5": Decimal("0.003"),
   }
   
   # services/ai_service.py
   from app.data.model_pricing import PRICING
   

   </details>

3. Auth and schemas don't live with endpoints. A bloated routers/admin.py becomes routers/admin/{wallet,users}.py with auth in core/admin_auth.py and Pydantic schemas in schemas/admin/. Each file has one reason to change.

   <details><summary>before / after</summary>

   # BEFORE — routers/admin.py (520 lines)
   def require_admin(user_id: str = Depends(get_current_user_id)): ...
   class AdjustWalletRequest(BaseModel): ...
   class ListUsersResponse(BaseModel): ...
   @router.post("/admin/wallet/adjust"): ...
   @router.get("/admin/users"): ...
   

   # AFTER
   core/admin_auth.py        # require_admin dep
   schemas/admin/wallet.py   # AdjustWalletRequest
   schemas/admin/users.py    # ListUsersResponse
   routers/admin/wallet.py   # only HTTP for wallet ops
   routers/admin/users.py    # only HTTP for user ops
   routers/admin/__init__.py # combines and re-exports
   

   </details>

4. Provider with N format APIs → file per format. A single Fal.ai client that does both image and video generation becomes providers/falai/{image.py,video.py,_client.py}. The HTTP plumbing (auth, retries, base URL) sits in _client.py; each format file owns its request/response shape.

   <details><summary>before / after</summary>

   # BEFORE — providers/falai.py (640 lines, image+video request models tangled)
   class FalAiAdapter:
       async def generate_image(self, ...): ...
       async def generate_video(self, ...): ...
   

   # AFTER — providers/falai/_client.py
   class FalClient:
       def __init__(self, *, api_key: str, http: httpx.AsyncClient): ...
       async def request(self, path: str, payload: dict) -> dict: ...
   
   # providers/falai/image.py
   from ._client import FalClient
   class FalImageAdapter:
       def __init__(self, client: FalClient): self._c = client
       async def generate(self, req: ImageRequest) -> GenerateResult | ProviderError: ...
   

   </details>

5. Worker-handlers do NOT live in the router. routers/tasks.py stays HTTP-only (enqueue, list, cancel). Background processing goes to services/task_handlers/{image,video,audio}.py. The router becomes a thin entry point you can read in 30 seconds.

6. User-API ≠ Admin-API in the same service file. wallet_service.py (500 lines) becomes services/wallet/{user.py,admin.py,history.py,debt.py} with a shared services/wallet/_repo.py. User code can't accidentally import admin-only methods.

7. Soft cap 400 LOC, hard cap 600 LOC per file. At 400 lines you plan the split. At 600 lines you split now — no exceptions. Enforced by scripts/check_loc.py in CI.

8. Refactor without breaking changes. __init__.py re-exports the old public names, so callers (and your AI assistant's stale memory of the codebase) don't break. Decomposition is invisible from the outside.

   <details><summary>example</summary>

   # services/wallet/__init__.py
   from .user import WalletUserService
   from .admin import WalletAdminService
   
   # Backwards-compat: old code did `from app.services.wallet_service import WalletService`
   WalletService = WalletUserService  # alias keeps imports working during migration
   
   __all__ = ["WalletUserService", "WalletAdminService", "WalletService"]
   

   </details>

🔌 Part