Rules Iteration and Accumulation
Write the right rules at the right time
Core Philosophy
Cursor Rules are not something you write once and forget. They are a system of standards that accumulates as your project evolves.
Many people want to write a perfect set of rules at the project’s beginning, only to end up with rules that are either too vague or disconnected from actual architecture. The correct approach is: Architecture first, rules follow.
When to Write Rules
Phase 1: After Scaffolding is Complete
When you finish project initialization and determine the basic tech stack and directory structure, immediately write global rules.
| Timing | Rules to Add |
|---|---|
| Tech stack determined | List all core dependencies (React, TypeScript, Tailwind, etc.) |
| Directory structure determined | Define responsibilities of each directory (pages/, components/, lib/, etc.) |
| Coding standards determined | TypeScript standards, import conventions, naming conventions |
| Toolchain configured | lint, build, test commands |
# Example: Global rules to add immediately after project init
## Tech Stack
- Vite + React + TypeScript
- Tailwind CSS + Shadcn/ui
- React Router + Zustand
## Directory Structure
/src/
├── pages/ # Route pages
├── components/ # UI components
├── lib/ # Utilities
├── stores/ # State management
└── types/ # Type definitions
## Quality Standards
- Ensure `npm run lint` and `npm run build` passes before commits📖 Reference: Global Rules Example
Phase 2: When Architecture Expands
Whenever you add new architectural layers or functional modules to your project, immediately write dedicated rules for them.
| Architecture Added | Rule File to Create | Rule Content |
|---|---|---|
| Routing system | routing-rules.mdc | Page file structure, route protection, auth flow |
| API layer | api-rules.mdc | HTTP client, data fetching patterns, error handling |
| UI component library | ui-rules.mdc | Component usage standards, icon system, theme config |
| State management | store-rules.mdc | Store organization, state update patterns |
| Form handling | form-rules.mdc | Form validation, error handling, submission flow |
Key principle: When architecture decisions land, rules must sync.
📖 Reference: Routing Rules Example, API Rules Example, UI Rules Example
Phase 3: During Iterative Development
In daily development, when you find AI repeatedly making certain types of mistakes, that’s the signal to add rules.
| Problem Found | Rule to Add |
|---|---|
| AI keeps using wrong date formatting | Add formatDate() from @/lib/date-time-utils.ts |
| AI uses forbidden components | Add “Do not use Card component unless I request it” |
| AI handles errors incorrectly | Add error handling code examples |
| AI ignores auth checks | Add <ProtectedRoute> usage standards |
Iteration principle: Problem → Rule → Verify → Optimize
Recommended Rule Composition
A healthy rule system should follow the “less is more” principle. Too many rules not only consume tokens but also conflict with each other, reducing AI execution effectiveness.
Recommended Rule Structure
| Rule Type | Quantity | Description |
|---|---|---|
| Global Rules | 1 (required) | Tech stack, directory structure, coding standards, quality standards |
| File-matched Rules | 2-4 | Split by architecture layer: routing, api, ui, store, etc. |
| Manual Rules | 0-2 | Manually triggered for specific scenarios: feature-template, refactor-guide, etc. |
Key Principle: Control Active Rules Per Chat
Keep active rules per chat session to 3 or fewer.
- 1 Global Rules (always active)
- 1-2 File-matched Rules (auto-triggered based on current file)
This means you need to carefully design globs patterns to ensure rules are mutually exclusive or have low overlap:
# ✅ Good design: globs are mutually exclusive, won't trigger together
routing-rules.mdc → globs: src/pages/**
api-rules.mdc → globs: src/clients/**
ui-rules.mdc → globs: src/components/**
# ❌ Bad design: globs overlap, may trigger multiple rules simultaneously
component-rules.mdc → globs: **/*.tsx
ui-rules.mdc → globs: src/components/**
page-rules.mdc → globs: src/pages/**Rule Quantity vs Quality
| Rule Count | Effect |
|---|---|
| 1-3 high-quality rules | ✅ AI executes precisely, significant results |
| 5-8 medium rules | ⚠️ Needs good globs design to avoid conflicts |
| 10+ rules | ❌ Rule conflicts, token waste, degraded results |
Better to have fewer rules that are truly needed and specifically actionable for your project.
Practical Example
Using a typical React project as an example, showing the evolution of rules:
Day 1: Project Initialization
# Create project with Vite
npm create vite@latest my-app -- --template react-ts
# Add Shadcn/UI
npx shadcn@latest initImmediately create: global-rules.mdc
Week 1: Building Core Architecture
- Configure React Router
- Integrate Okta authentication
- Set up API client
Add rules: routing-rules.mdc, api-rules.mdc
Week 2: Developing Business Features
- Found AI using wrong icon library
- Found AI not using project’s Toast component
Add rules: ui-rules.mdc
Continuous Iteration
- Find new problems → Add rules
- Architecture changes → Update rules
- Team feedback → Optimize rules
Common Mistakes
| Mistake | Correct Approach |
|---|---|
| Trying to write perfect rules from start | Start with 3-5 rules for biggest pain points |
| Writing rules and forgetting them | Rules need continuous updates as project evolves |
| Putting all rules in one file | Split by responsibility, use globs for precise matching |
| Copying generic rules from internet | Only write specific standards unique to your project |
Next Steps
Sometimes you may need to write rules from scratch for a new tech stack. Next, we’ll share meta prompts for generating Rules to help you quickly generate rule frameworks.