Most developers think of project setup as: install dependencies, configure TypeScript, set up linting.
That is the wrong order. The AI-native setup order is different, and skipping it means your AI assistant works against your project instead of with it.
Here are the three files that should exist before you write a line of application code.
CLAUDE.md
is a markdown file at your project root that Claude Code loads as a system prompt prefix on every session. Think of it as the briefing document your AI assistant reads before touching your codebase.
A minimal CLAUDE.md
for a new project:
## Stack
Next.js 15, TypeScript strict, Prisma + PostgreSQL, Tailwind CSS
## Rules
- No `any` types. No unvalidated JSON.parse().
- Auth via NextAuth.js. Never roll custom auth.
- DB access only in `src/services/` — never in route handlers directly.
- Run `npm run typecheck` before declaring a fix done.
## Deploy
Vercel. Main branch auto-deploys. Staging on `preview` branches.
Ten lines. That is enough to prevent 80% of the decisions where the AI would otherwise guess wrong.
Why write this before any code? Because when you write it after, you are describing what you accidentally built rather than what you intended. The instruction layer should drive the codebase, not document it retroactively.
If you use Cursor, @.cursorrules
loads into Cursor's context. It is similar to CLAUDE.md
but optimized for Cursor's behavior — shorter, more rule-focused, less narrative.
The key difference from CLAUDE.md
: CLAUDE.md
can afford to be contextual ("we use Prisma because our team knows it"). @.cursorrules
should be purely prescriptive ("never write raw SQL; use Prisma query builders").
Keep them in sync. If you update the auth pattern in one, update the other. Two source-of-truth files with the same content that drift apart are worse than one.
A clean pattern: have CLAUDE.md
be the canonical source. In .cursorrules
, reference it and add only Cursor-specific formatting rules:
Project context: see CLAUDE.md at repo root.
Additional Cursor rules:
- Auto-import from absolute paths, not relative.
- Prefer named exports over default exports.
- Format with Prettier on save — do not manually align anything.
Four lines. Everything else lives in CLAUDE.md
.
This one surprises people. The README is not for human readers — it is for your AI assistant's cold-start.
When you open a new Cursor session or start a new Claude Code chat, the AI does not remember anything from yesterday. The README is the document it will read first if you paste it in, and it is what future agents (or you, in three months) will read to understand how the project works.
A README that serves as an AI onboarding document:
## Quick context
SaaS app for indie devs. Subscription billing via Stripe, auth via NextAuth.js,
database via Prisma + PostgreSQL on Neon.
## Local setup
npm install && cp .env.example .env.local && npx prisma migrate dev
## Project structure
src/
app/ Next.js App Router pages
services/ Business logic — no HTTP here
components/ React components — no data fetching here
lib/ Utilities and config
## Common tasks
Run dev: npm run dev
Run types: npm run typecheck
Run tests: npm test
Deploy: push to main
No fluff. No marketing copy. Just: what is this, how do I start it, what is where.
These three files form a triangle:
CLAUDE.md
tells the AI .cursorrules
tells the AI README.md
tells the AI When all three are in place before you write application code, you are building inside a defined context. The AI works with your decisions instead of making its own.
When none of them are in place, you are doing vibe coding in the wrong direction — the AI is building something, and you are figuring out what it is as you go.
Setting these three files up for a new project takes 20-30 minutes if you are doing it from scratch. Doing it for 12 different tech stacks (Next.js SaaS, Express + JWT, FastAPI, Discord Bot, Chrome Extension, and more) takes considerably longer.
The Vibe Coder Kit packages 12 production-configured starters where all three files are already in place and consistent with the actual codebase. You clone, run the setup command, and your AI assistant is already briefed.
At the end of your next project setup, ask: "If a new developer (or a new AI session) opened this repo with no context, could they figure out what it is, how to run it, and how to work in it?"
If the answer is yes, you have done the setup right.
BLN Craft builds developer tools for AI-native workflows. Find us at blncraft.com.