How to Write Cursor Rules and Claude System Prompts for Vibe Coding

1. Why Default AI Output Falls Short

Out of the box, AI coding assistants produce generic code. They default to popular patterns, common libraries, and verbose boilerplate. That is fine for a throwaway prototype, but the moment you need code that fits an existing codebase - matching your naming conventions, your state management approach, your testing patterns - defaults stop being useful.

The fix is not better prompting in the chat window. It is persistent configuration files that tell the AI how your project works before every conversation starts. Think of it like onboarding a new developer: you would not just say "write me a feature." You would point them at the style guide, explain the architecture, and show them where things live.

That is exactly what .cursorrules and CLAUDE.md files do. They are your project's onboarding docs for AI.

2. Writing Effective .cursorrules Files

A .cursorrules file sits in your project root and is automatically injected into every Cursor conversation. It is the single highest leverage file in a vibe coding workflow. Here is what to include and what to skip.

What to include

• Tech stack and versions - "This project uses Next.js 14 with the App Router, TypeScript strict mode, Tailwind CSS, and Prisma for database access." This prevents the model from suggesting Pages Router patterns or incompatible libraries.
• File structure conventions - "Components go in src/components/. API routes go in src/app/api/. Database queries are centralized in src/lib/db/." Explicit paths prevent the AI from inventing new directory structures.
• Coding patterns to follow - "Use server components by default. Only add 'use client' when the component needs interactivity. Prefer server actions over API routes for mutations."
• Patterns to avoid - "Never use any or unknown types. Never add console.log statements. Do not create utility files with single functions." Negative constraints are surprisingly effective because models tend to fall back to common patterns when unconstrained.
• Error handling approach - "Use Result types for expected failures. Throw only for unexpected errors. Always handle loading and error states in UI components."

What to skip

• Generic advice like "write clean code" or "follow best practices." The model already tries to do that. You need specifics.
• Lengthy explanations of why. The model does not need to understand your architectural reasoning - it just needs the rules.
• Anything over about 500 lines. Long rules files eat into context window and actually degrade output quality. Keep it focused.

A good .cursorrules file is usually 50 to 200 lines. Treat it like a linter configuration - specific, opinionated, and maintained as the project evolves.

3. CLAUDE.md: Giving Claude Code Persistent Context

If you use Claude Code (the terminal-based coding agent), the equivalent of .cursorrules is CLAUDE.md. It lives in your project root and is automatically loaded into every conversation. The principles are similar but CLAUDE.md supports a few patterns that are uniquely powerful.

• Build and test commands - Claude Code can actually run your code. Tell it: "Build with npm run build. Test with npm run test. Lint with npm run lint." This lets it verify its own output.
• Multi-agent coordination - If you run parallel Claude Code agents on the same codebase, CLAUDE.md can include rules like "if you see build errors in files you did not edit, wait 30 seconds and retry." This prevents agents from stepping on each other.
• Custom skills and hooks - Claude Code supports slash commands and event hooks defined in your config. CLAUDE.md can reference these: "Use /test-local to build and run the app. Use /deploy to push to production."
• Global vs project-level - You can have a global ~/.claude/CLAUDE.md for preferences that apply everywhere (your identity, default accounts, coding style) and a project-level CLAUDE.md for project-specific rules. Both are loaded automatically.

The biggest advantage of CLAUDE.md over .cursorrules is that Claude Code is agentic - it can read files, run commands, and verify its work. Your CLAUDE.md should lean into that. Instead of just describing patterns, give it executable verification steps.

4. The Interview Step: Let AI Poke Holes First

One of the most underrated techniques in vibe coding is what some developers call the "interview step." Before writing any code, you dump your full context into Claude or Cursor and ask it to poke holes in your thinking.

The prompt looks something like: "Here is what I want to build. Here is my current architecture. Here are my constraints. Before we write any code, tell me what is wrong with this plan. What edge cases am I missing? What will break first?"

This works because AI models are surprisingly good at finding inconsistencies and missing requirements - better than they are at generating perfect code from scratch. You get a free architecture review before you invest any time building.

• Catches scope creep early - The model will ask about features you mentioned but did not spec out, forcing you to either scope them properly or cut them.
• Surfaces integration issues - "You said you are using Prisma but your schema does not have a relation for this feature. How should that work?"
• Identifies the hard parts - The model can estimate which parts of your plan will be straightforward and which will require more thought, helping you prioritize.
• Produces better cursor rules - The interview conversation itself often reveals patterns and constraints you should add to your .cursorrules or CLAUDE.md file.

Think of it as specification-driven development with an AI reviewer. You spend more time writing specs than code, but you ship faster because you are building the right thing from the start.

5. Cursor Rules vs CLAUDE.md vs System Prompts

Each AI coding tool has its own mechanism for persistent configuration. Here is how they compare:

Many developers use more than one. A common setup: .cursorrules for quick edits in Cursor, CLAUDE.md for larger agentic tasks in Claude Code, and a shared architectural doc that both reference.

The key insight is that all of these are solving the same problem - giving the AI enough context about your project to produce code that fits, not just code that works.

6. Templates and Real Examples

Here is a minimal .cursorrules template that covers the essentials:

# Project: [Your App Name]

## Stack
- Next.js 14 (App Router)
- TypeScript (strict)
- Tailwind CSS
- Prisma + PostgreSQL

## File Structure
- src/app/ - pages and API routes
- src/components/ - reusable components
- src/lib/ - shared utilities and db queries

## Rules
- Server components by default
- Use 'use client' only for interactive components
- Prefer server actions over API routes
- Never use 'any' type
- Error boundaries on every page
- All database queries in src/lib/db/

## Patterns
- Forms: react-hook-form + zod validation
- Auth: next-auth with JWT strategy
- State: URL params for shareable state, React state for UI-only

## Do NOT
- Create utility files with single functions
- Add console.log (use structured logging)
- Use default exports (except pages)

And here is a CLAUDE.md snippet focused on agentic workflows:

# Project: [Your App]

## Commands
- Build: npm run build
- Test: npm run test
- Lint: npm run lint
- Dev: npm run dev (port 3000)

## Testing Rules
- Run tests after every change
- If tests fail, fix before moving on
- Never mock the database in integration tests

## Architecture
- Monorepo: apps/web, apps/api, packages/shared
- API follows REST conventions
- All env vars in .env.local (never commit)

## When stuck
- Read the error message carefully
- Check existing tests for similar patterns
- Ask me before adding new dependencies

These are starting points. The best rules files evolve with your project. Every time the AI produces something that does not fit your codebase, add a rule to prevent it. Over a few weeks, your rules file becomes a precise specification of how your project should be built.

7. Beyond Code: AI Agents That Act on Your Rules

The natural next step after coding assistants is AI agents that can actually execute tasks on your computer - not just write code, but interact with apps, fill out forms, manage files, and automate repetitive workflows.

The same principle applies: the better your instructions and context, the better the output. Tools like Fazm take this idea further by letting AI agents control your entire macOS desktop through accessibility APIs - handling browser automation, document management, Google Apps, and CRM tasks through voice commands or natural language instructions. Instead of writing .cursorrules for code generation, you are giving context to an agent that can actually do the work.

The pattern is consistent across all AI tooling: specificity wins. Whether you are configuring a code completion model, an agentic coding tool, or a desktop automation agent, the quality of your output is directly proportional to the quality of your input context.

Start with your .cursorrules or CLAUDE.md file today. Keep it updated as your project grows. Treat it like living documentation that makes every AI interaction more productive. The upfront investment of writing good rules pays for itself within the first week.