claude-design-to-nextjs

vibe-stack-rules

Modular, import-friendly engineering rules for vibe coders shipping on Next.js + Supabase + shadcn/ui + Zustand.

Drop them at the root of your repo. Your agent behaves.

If you've watched Claude Code, Cursor, Codex, or any other vibe-coding agent ship the same 10 bugs on this stack over and over — async page.tsx, module-scope Supabase clients, Zustand state leaks, ISR on authenticated routes, duplicate zod schemas, skeletons buried in if (!data) branches — this repo is the fix.

---

Why this is split into multiple files

A monolithic 500-line CLAUDE.md is a trap. Three problems:

1. Context pollution. Your agent loads every rule on every session, even when editing a button label.
2. Adherence degrades with length. Anthropic's own docs recommend keeping memory files under ~200 lines for reliable rule-following. Longer = more drift.
3. Wrong home for generic rules. CLAUDE.md should be the brain of your specific app — what it does, how to run it, current decisions — not a stack tutorial.

The fix: a lean CLAUDE.md at your repo root that describes your project, plus a stack/ folder of focused rule files that CLAUDE.md imports via @path syntax. Each stack file is ~150–250 lines, scoped to one concern, and loaded by Claude Code automatically.

---

This repo's structure

vibe-stack-rules/
├── README.md                    ← you are here
├── USAGE.md                     ← end-to-end walkthrough for the skill
├── LICENSE                      ← MIT
├── .gitignore
├── .claude-plugin/
│   └── marketplace.json         ← makes this repo an installable Claude Code marketplace
├── plugins/                     ← plugin distribution (for /plugin install)
│   └── claude-design-to-nextjs/
│       ├── .claude-plugin/plugin.json
│       └── skills/claude-design-to-nextjs/   ← same content as template/.claude/skills/ below
└── template/                    ← the files you install into your project via degit
    ├── CLAUDE.md                ← lean project-brain template
    ├── stack/
    │   ├── 00-foundations.md    ← reading instructions, versions, principles, project structure
    │   ├── 10-server.md         ← RSC boundary, data fetching, Suspense, Server Actions
    │   ├── 20-supabase.md       ← 3 clients, middleware/proxy, auth gate, the 6 traps
    │   ├── 30-client.md         ← Zustand store factory + shadcn composition
    │   └── 90-discipline.md     ← redundancy rules, TS rules, LLM checklist, anti-patterns
    └── .claude/
        └── skills/
            └── claude-design-to-nextjs/   ← convert Claude Design bundles → Next.js + TSX + Tailwind + shadcn
                ├── SKILL.md
                └── references/            ← per-phase subagent prompts + stack adapter

The skill appears in two locations on purpose: plugins/claude-design-to-nextjs/skills/ for /plugin install, and template/.claude/skills/ for degit installs. Keep them in sync when editing — a quick rsync -a plugins/claude-design-to-nextjs/skills/claude-design-to-nextjs/ template/.claude/skills/claude-design-to-nextjs/ after a change is enough.

Everything inside template/ is what lands in your project. The rest is repo metadata.

What lands in your project after install

your-next-app/
├── CLAUDE.md                    ← customize this with your project details
├── stack/                       ← leave these alone unless amending rules
│   ├── 00-foundations.md
│   ├── 10-server.md
│   ├── 20-supabase.md
│   ├── 30-client.md
│   └── 90-discipline.md
├── .claude/
│   └── skills/
│       └── claude-design-to-nextjs/  ← triggers when you paste a Claude Design command
├── app/                         ← your actual Next.js app
├── lib/
└── ...

CLAUDE.md at your repo root imports the stack/*.md files via @stack/*.md syntax. Claude Code picks them up automatically at session start.

---

The target stack

Tool	Version	Role
Next.js	≥ 15 (App Router)	Framework
React	≥ 19	RSC + Server Actions
TypeScript	strict mode	Type safety
Supabase	@supabase/ssr ≥ 0.10	Auth + database
shadcn/ui	latest	Component primitives
Tailwind CSS	≥ 3.4	Styling
Zustand	≥ 5	Client UI state

Middleware filename: Next.js ≤15 uses middleware.ts at project root. Next.js 16+ renamed it to proxy.ts. Same code, different filename. The rules cover both.

---

Install

1. Copy the template into your project

The cleanest way is degit, which pulls the template/ folder contents directly into your current directory without any git history:

# from your project root
npx degit imfaisii/vibe-stack-rules/template .

That single command creates CLAUDE.md and stack/ at the root of your project. Done.

Alternative (no Node required):