simplicity cursor rule

simplicity.mdc

# Ruthless Simplicity

## Core Philosophy

**RUTHLESSLY PURSUE SIMPLICITY.** Great code isn't written—it's carved from complexity with unrelenting pressure. Every line must justify its existence. Every abstraction must prove its worth. We seek the essential core of each problem, then eliminate everything else without mercy.

Like a sculptor who starts with a block of marble and strips away everything that isn't the sculpture, we start with a problem and ruthlessly eliminate everything that isn't the solution. No compromises. No "just in case." No clever tricks.

We achieve this through:

1. **SINGLE FILE WINS** - One 80-line file beats five 20-line files. Perfection is achieved not when there's nothing more to add, but nothing left to take away.
2. **TRUST THE OBVIOUS** - Use proven libraries. Write boring code. Complexity is a burden; simplicity is a gift.
3. **CONVENTION OVER CONFIG** - The expected solution is the right solution. Question every deviation.
4. **ZERO SPECIAL CASES** - Edge cases are a design smell. If you need special cases, you've failed to find the real solution.
5. **TINY FUNCTIONS** - Nothing over 8 lines. If it's longer, you're solving multiple problems. Don't.

## Code Structure

1. **80-LINE LIMIT:** No file > 80 lines. If it's bigger, it's wrong.
2. **NO CLEVER CODE:** Write the most boring, obvious solution possible.
3. **SIMPLIFY, THEN DELETE:**
   - First, refactor for extreme simplicity
   - Then ruthlessly delete anything not directly needed
   - If code's purpose isn't obvious, delete it
   - No "we might need this later"

## Function Design

1. **PURE CORE, SIDE EFFECTS AT EDGES:**
   - Core logic must be pure functions
   - Keep I/O at the entry points only
   - No side effects in business logic
   - Clear separation of concerns

2. **FUNCTION RULES:**
   - 8 lines maximum
   - Single responsibility
   - Clear inputs and outputs
   - No state management

## Interface Design

1. **MINIMAL SURFACE AREA:**
   - Every interface should be obvious at first glance
   - No optional parameters
   - No configuration objects
   - One way to do one thing

2. **PREDICTABLE PATTERNS:**
   - Input → Output, always
   - Data flows in one direction
   - First argument is always primary data
   - No context or state dependencies

3. **COMPOSITION OVER OPTIONS:**
   - Chain simple functions instead of complex interfaces
   - Each function does exactly one transformation
   - No flag arguments
   - No boolean toggles

## Naming

1. **ONE WORD WINS:**
   - Single words beat compounds
   - Verbs for actions (parse, build, run)
   - Nouns for data (user, post, log)
   - No qualifiers needed? Remove them

2. **NAMES REVEAL INTENT:**
   - If you need "Manager" or "Service", you're hiding complexity
   - If you need "Helper" or "Util", you lack organization
   - If you need "Interface" or "Abstract", you're overengineering
   - Name things by what they do, not what they are

3. **BRUTAL NAMING RULES:**
   - Max 2 words per name
   - Filenames match exports exactly
   - No prefixes or suffixes
   - No abbreviations

## Data & Types

1. **FLAT STRUCTURES:**
   - No nested configuration
   - One level deep objects
   - Minimal optional fields
   - Simple, obvious shapes

2. **TYPE RULES:**
   - Types describe shape only
   - No behavior in types
   - No complex hierarchies
   - Keep it flat and obvious

## File Organization

1. **SINGLE FILE FIRST:**
   - Start with one file
   - Split only when absolutely necessary
   - Keep related code together
   - No premature organization

2. **PREDICTABLE PATHS:**
   - `src/` = all code
   - `config/` = all config
   - Filenames match exports
   - No specialty folders

## Dependencies

1. **USE LIBRARIES > WRITE CODE:**
   - Every line we write is a line that can break
   - Well-tested libraries beat custom code
   - If it exists, use it
   - Don't reinvent wheels

2. **DIRECT USAGE:**
   - Import libraries directly
   - No wrappers around libraries
   - No "our version" of libraries
   - Trust your dependencies

3. **CHOOSE LIBRARIES WISELY:**
   - Popular > obscure
   - Maintained > abandoned
   - Simple > complex
   - Standard > custom

## Configuration

1. **CONVENTION BEATS CONFIG:**
   - Use predictable patterns
   - Sensible defaults everywhere
   - Infer what you can
   - Make the obvious choice the default

2. **MINIMAL OPTIONS:**
   - Question every config option
   - Remove rarely used options
   - Use conventions instead
   - Make decisions, don't defer them

## Testing

1. **SIMPLICITY > COVERAGE:**
   - Simple code needs fewer tests
   - Test what users see
   - No mocks if possible
   - Integration > unit tests

2. **TEST RULES:**
   - Test the CLI/API layer
   - Skip testing library code
   - No complex test setups
   - If tests are complex, code is complex

## Simplification Process

1. **EVALUATE:**
   - Can this fit in one file?
   - Is every line necessary?
   - What can I delete?
   - Are abstractions justified?

2. **SIMPLIFY:**
   - Combine similar things
   - Remove special cases
   - Question every pattern
   - Delete anything we don't need

3. **VALIDATE:**
   - Does it work?
   - Is it obvious?
   - Could it be simpler?
   - What else can I remove?

## Code Review Checklist

Before committing:
- [ ] Could I delete 30% of this?
- [ ] Is any function > 8 lines?
- [ ] Is any file > 80 lines?
- [ ] Am I reinventing something?
- [ ] Is there any "just in case" code?
- [ ] Could this be expressed more simply?
- [ ] Am I using libraries directly?
- [ ] Are my types minimal?
- [ ] Is configuration necessary?
- [ ] Could this be a convention instead?

## When Uncertain

1. Remove it
2. Use a library
3. Simplify further
4. Remove options
5. Start fresh

## Final Reminder

**SIMPLICITY IS AN ART.**
It's the courage to do less,
the wisdom to embrace constraints,
and the joy of finding elegance in the obvious.

The truly simple solution feels like a revelation—
like finding the perfect word,
like solving a puzzle,
like watching the sun rise.

Simple code is an act of generosity:
- A gift to the next developer
- A gift to our future selves
- A gift to the machines that run our code
- A gift to the users who depend on it

The perfect codebase reads like poetry. Each line flows naturally to the next, each function tells a clear story, and the whole feels inevitable—as if it couldn't have been written any other way.

Remember:
- Complexity obscures; simplicity illuminates
- Code is read far more than it is written
- The obvious solution is a feature, not a bug
- Understanding is the best documentation
- The best code feels like it was discovered, not written