generate.py
█
// before vibecodex → after vibecodex
// 54 production principles

Your AI writes code
that breaks in prod.
vibecodex fixes that.

Architecture rules your AI follows automatically. Copy one file. Every Claude session follows 54 production principles from line one.

$ npx @aimyerdaulet/vibecodex init
FastAPINext.js 15Go 1.22+
⭐ github.com/yerdaulet-damir/vibe-coding-rules
// the problem
WITHOUT vibecodex
# routers/generate.py  (1,400 lines)
@router.post("/generate")
async def generate(req: dict, db=Depends(get_db)):
    result = await httpx.post(OPENAI_URL, json=req)
    data = result.json()
    wallet = db.query(Wallet).filter(...).one()
    wallet.balance -= data["usage"]["cost_usd"]
    db.commit()
    return data  # vendor shape leaks into response
WITH vibecodex
# routers/generate.py  (8 lines)
@router.post("/generate", response_model=GenerateResponse)
async def generate(
    req: GenerateRequest,
    user_id: str = Depends(get_current_user_id),
    svc: GenerateService = Depends(get_generate_service),
) -> GenerateResponse:
    return await svc.generate(user_id, req)

// AI assistants produce structurally correct, locally optimal code. What they don't enforce is architectural consistency: layer boundaries, single-writer invariants, bulkhead isolation, idempotency keys. vibecodex does.

// how it works
$ npx vibecodex init
? Select your stack:
❯ FastAPI (Python)
Next.js 15 (TypeScript)
Go 1.22+
✓ Copied CLAUDE.md
✓ Copied .cursor/rules/
✓ Copied .claude/skills/
01One command
# CLAUDE.md loaded
Router → Service → Repository
No business logic in routers
No sqlalchemy in services
ACL: providers return typed results
Bulkhead: one AsyncClient per provider
Idempotency keys on every side-effect
Single-writer for critical resources
0254 rules active
$ claude "add /generate endpoint"
→ Creating routers/generate.py (8 lines)
→ Creating services/generate.py
→ Creating repositories/protocols.py
✓ Layer boundaries respected
✓ No sqlalchemy in service layer
✓ Idempotency key in router
✓ lint-architecture.sh passes
03Clean code, first try
// 54 production principles
A1
File Size Limits
Python
A2
Static Data Separation
Python
A3
Folder-per-Domain
Python
A4
Provider Decomposition
Python
A5
Service Decomposition
Python
A6
Worker Handler Split
Python
A7
Internal File Prefix
Python
A8
Lazy DB Init
Python
B1
Anti-Corruption Layer
Python
B2
Bulkhead Isolation
Python
B3
Idempotency Keys
Python
B4
Structured Logging
Python
B5
Feature Flag Adapters
Python
B6
Contract Tests
Python
B7
Typed Error Hierarchy
Python
B8
Retry with Backoff
Python
B9
Protocol-based DI
Python
B10
Single-Writer Pattern
Python
C1
Repo Protocol Interface
TypeScript
C2
Feature Folder Structure
TypeScript
C3
Co-locate by Feature
TypeScript
C4
Thin Page Components
TypeScript
C5
Schema Validation Layer
TypeScript
C6
Error Boundary Pattern
TypeScript
C7
Static Data Extraction
TypeScript
C8
Hook Decomposition
TypeScript
C9
Action Isolation
TypeScript
C10
DB Client Singleton
TypeScript
D1
Typed Cache-Tag DSL
TypeScript
D2
RSC Leaf use() Pattern
TypeScript
D3
Server Actions + Zod
TypeScript
D4
Parallel Data Fetching
TypeScript
D5
Session cache()
TypeScript
D6
Partial Prerendering
TypeScript
E1
Package by Domain
Go
E2
Thin main() Function
Go
E3
Interface Next to Consumer
Go
E4
Sentinel Errors
Go
E5
Table-Driven Tests
Go
E6
Constructor Injection
Go
E7
Internal Package Boundary
Go
E8
run() Entry Pattern
Go
F1
Tiny Consumer Interface
Go
F2
errgroup Concurrency
Go
F3
ACL Typed Results
Go
F4
Per-Provider HTTP Client
Go
F5
Idempotency Store
Go
F6
Context Value Helpers
Go
F7
Graceful Shutdown
Go
F8
Structured slog
Go
F9
Feature Flag Interface
Go
F10
Contract Test Fixture
Go
// get started
$ npx @aimyerdaulet/vibecodex init
? Select your stack:
❯ FastAPI (Python)
Next.js 15 (TypeScript)
Go 1.22+
All stacks
✓ Copied CLAUDE.md
✓ Copied .cursor/rules/architecture.mdc
✓ Copied .cursor/rules/decomposition.mdc
✓ Copied .cursor/rules/integrations.mdc
✓ Copied .claude/skills/debug-backend/SKILL.md
✓ Copied .claude/skills/new-feature/SKILL.md
✓ Copied .claude/skills/add-provider/SKILL.md
✓ Copied .claude/skills/split-monolith/SKILL.md
Done. Your AI now follows 54 production principles.
⭐ Star on GitHubRead the principles →
// questions

Frequently asked

vibecodex is a set of 54 production architecture principles for AI-assisted coding. It ships as a single CLAUDE.md file plus Cursor rules and Claude Code skills that any AI coding agent loads automatically. Stacks covered: FastAPI (Python), Next.js 15 (TypeScript), and Go 1.22+.

Yerdaulet Damir — vibecodex author
// built by

Yerdaulet Damir

Full-stack engineer building production AI products. vibecodex is the architecture rulebook I wished existed when my first vibe-coded SaaS turned into a 1,400-line router. Distilled from real refactors across FastAPI, Next.js 15, and Go services in production.

github.com/yerdaulet-damir·npm: aimyerdaulet