Short vs Long Rule Files: Optimal Length

How Long Should a Rule File Be?

Every team writing their first CLAUDE.md or .cursorrules faces the same question: how much should I write? Too short (50-100 words): the file says "Use TypeScript and React" — the AI still generates generic patterns because it has no specific conventions. Too long (3000-5000 words): the file documents every coding decision ever made — the AI's context window is filled with rules instead of code, and the most important rules are buried in a wall of text. The optimal length is: shorter than most teams expect.

The optimal range: 500-1500 words (roughly 700-2000 tokens). This covers: project description (what it is, what stack it uses — 50 words), core conventions (10-15 specific rules about naming, patterns, and structure — 200-400 words), framework specifics (which framework patterns to use and which to avoid — 200-400 words), testing requirements (test runner, patterns, coverage expectations — 100-200 words), and critical prohibitions (security rules, deprecated patterns to avoid — 100-200 words). This range: provides enough specificity to guide the AI without consuming excessive context tokens.

This article provides: the evidence for the optimal range, what to include at each length tier, what to deliberately omit, the priority ordering trick for context windows, and how to measure whether your rule file is actually working. The goal: a rule file that maximizes AI output quality per token of context consumed.

Too Short: What You Lose Under 300 Words

Under 300 words: the rule file is a project description, not a coding guide. Example: "This is a Next.js 16 project with TypeScript, Tailwind CSS, and Drizzle ORM. Use pnpm for package management. Write tests with Vitest." This tells the AI: which technologies (useful for imports and API selection). It does not tell the AI: which React patterns to prefer (Server Components? Client Components?), how to structure files (app/ vs pages/? _components/ vs components/?), which Drizzle query patterns to use (select().from() or db.query?), or how to handle errors (throw? return? Result type?).

The AI with a too-short rule file: knows the technology stack (generates correct imports and API calls) but uses generic patterns (default React conventions, not your project specific conventions). The output: compiles and works, but does not match your codebase style. Code reviews: focus on style and convention issues that the rule file should have prevented. The developer: rewrites 20-30% of the AI output to match project conventions. The rule file saved: import and API decisions. It missed: everything else.

When short is acceptable: brand-new projects with no established conventions (the rules will grow as patterns emerge), personal projects where consistency does not matter (one developer, their patterns are in their head), and rule files for tools that have very limited context allocation (some tools truncate rules aggressively — shorter survives truncation). For most professional projects: under 300 words is: insufficient to guide the AI toward project-specific code.

• Under 300 words: stack declaration, not coding guide — AI knows imports but not patterns
• Missing: React patterns, file structure, query style, error handling, testing patterns
• Output: compiles but does not match codebase style. 20-30% rewriting needed
• Acceptable: brand-new projects, personal projects, severely limited context tools
• For professional teams: under 300 words = insufficient for meaningful AI guidance

Too Long: What You Lose Over 2000 Words

Over 2000 words: the rule file is a comprehensive style guide that documents every decision. Example: a 4000-word rule file with: TypeScript conventions (500 words), React patterns (800 words), API design (600 words), testing (500 words), Git workflow (300 words), deployment (300 words), accessibility (400 words), and performance (600 words). This file is: thorough, well-organized, and counterproductive. Why: it consumes 5000+ tokens of context that could hold code the AI needs to see.

The context competition: the AI's context window holds: system prompt + rule file + code context + conversation history. A 5000-token rule file in a 128K context (GPT-4): 4% of the window. In a 200K context (Claude Sonnet): 2.5%. The percentage seems small, but: those 5000 tokens could hold 3-4 additional source files. The files the AI cannot see: may contain the patterns it should follow, the types it should use, or the APIs it should call. The rule file crowded out: the code context that produces better output than rules.

The dilution effect: AI models give more weight to the beginning of context (primacy effect) and the end (recency effect). A 4000-word rule file: the first 500 words receive strong attention, the middle 3000 words receive moderate attention, and the last 500 words receive moderate attention. Your most important rules (security, core patterns): may be buried in the middle where attention is weakest. A 1000-word file: every rule receives strong attention because the file is short enough to be fully processed. Shorter is: not just more token-efficient but more effective per rule.

The Optimal Range: 500-1500 Words

The 500-1500 word range works because: it provides enough specificity (15-25 concrete rules that guide the AI toward project-specific patterns), it consumes a reasonable token budget (700-2000 tokens — 1-2% of even a moderate context window), every rule receives strong attention (the file is short enough for the AI to process fully), and it leaves maximum room for code context (the AI sees more of your codebase, which improves output quality more than additional rules). The range is: the sweet spot of guidance per token.

What to include in 500-1500 words: Tier 1 (must include, 200-300 words): project description (what, which stack), framework patterns (RSC default, form library, state management), and critical prohibitions (security rules, deprecated patterns). Tier 2 (should include, 200-400 words): naming conventions, file structure, testing patterns, and error handling approach. Tier 3 (include if space allows, 100-300 words): import ordering, comment style, Git conventions, and deployment notes. Tier 1 alone produces: 80% of the AI guidance value. Adding Tier 2: reaches 95%. Tier 3: marginal improvement.

The priority ordering trick: put the most important rules first in the file. AI models give primacy attention to the beginning. Your rule file order should be: (1) project stack and critical patterns (what the AI needs to know for every interaction), (2) conventions and structure (what the AI needs for most interactions), (3) testing and deployment (what the AI needs for specific tasks). If the context window truncates: the most important rules survive. If the AI attention fades: the critical rules were read first.

• 500-1500 words = 700-2000 tokens — 1-2% of context, leaves room for code
• 15-25 concrete rules: specific enough to guide, not so many they overwhelm
• Tier 1 (200-300 words): stack + framework patterns + security = 80% of value
• Tier 2 (200-400 words): naming + structure + testing + errors = reaches 95%
• Priority ordering: most important rules first — survives truncation and attention fade

What to Deliberately Omit

Omit obvious defaults: "Use semicolons in TypeScript" (the formatter handles this, not the AI). "Write clean code" (meaningless — every developer thinks their code is clean). "Follow best practices" (the AI already does this — the rule file should specify WHICH practices). "Use meaningful variable names" (the AI does this by default — the rule adds zero value). Rules that the AI already follows without instruction: are wasted tokens. Include only: rules that change the AI default behavior or specify a non-obvious project convention.

Omit documentation: "This project was created in 2024 and serves as the main customer-facing application for..." (background context that does not affect code generation). "The architecture decision to use Next.js was made because..." (the reasoning is interesting but the rule is: use Next.js). "For more information about our testing strategy, see the wiki at..." (links are not useful for the AI). The rule file is: instructions for the AI, not documentation for humans. CLAUDE.md can double as documentation (Markdown renders on GitHub), but: the AI-relevant rules should be at the top, the documentation context below.

Omit formatting rules handled by tools: ESLint handles: import ordering, unused variable detection, consistent return types. Prettier handles: indentation, quote style, semicolons, line length. TypeScript compiler handles: type checking, strict mode enforcement, unused parameter detection. If a tool enforces it: the rule file does not need to repeat it. The AI generates code; the formatter and linter fix the style. Include in the rule file: only rules that affect code logic and architecture, not rules that tools will auto-fix.

• Omit obvious defaults: 'Write clean code', 'Use meaningful names' — AI does this already
• Omit documentation: project history, architecture rationale, wiki links — not AI instructions
• Omit tool-enforced rules: ESLint, Prettier, TypeScript compiler handle formatting and linting
• Include only: rules that change AI default behavior or specify non-obvious conventions
• Test: if removing a rule does not change AI output, the rule was wasted tokens

Measuring Whether Your Rules Work

The test: generate code with the rule file, then generate the same code without it. Compare: does the rule-file version match your codebase conventions better? If yes: the rules are working. If no difference: the rules are either obvious (the AI follows them anyway) or ineffective (too vague to change behavior). Remove: rules that produce no difference. Strengthen: rules that produce partial improvement (make them more specific).

The rewrite rate metric: after the AI generates code, what percentage do you rewrite to match conventions? With no rule file: 40-60% rewriting (the AI generates generic patterns). With a good rule file: 5-15% rewriting (the AI matches most conventions, minor adjustments needed). If your rewrite rate is: above 30% with a rule file, the rules are not specific enough. Below 10%: the rules are well-calibrated. The rewrite rate is: the most practical measure of rule file quality. Track it informally for a week.

The iteration cycle: write the initial rule file (500 words). Use it for a week. Note: which AI outputs needed convention-based rewriting. Add rules for: the conventions the AI missed. Remove rules for: the conventions the AI followed without instruction. After a month: the rule file is: calibrated to your actual needs (not theoretical best practices). The rules that survive are: the ones that actually changed AI behavior. The rules that were removed are: the ones that wasted tokens without impact. Calibrate through use, not through anticipation.

Length Comparison Summary

Summary of short vs long rule file trade-offs.

• Under 300 words: too short — AI knows the stack but uses generic patterns. 20-30% rewriting
• 500-1500 words: optimal — 15-25 specific rules, 700-2000 tokens, every rule gets attention
• Over 2000 words: too long — consumes context, dilutes attention, buries important rules
• Tier 1 (stack + patterns + security): 80% of value in 200-300 words
• Priority ordering: most important rules first — survives truncation and attention fade
• Omit: obvious defaults, documentation, tool-enforced formatting rules
• Measure: rewrite rate (30%+ = rules too vague, 10% = well-calibrated)
• Calibrate: write, use for a week, add what AI missed, remove what AI already does. Repeat monthly