--- name: yagni description: When writing or reviewing code to prevent over-engineering and speculative features. Use when the user says "is this over-engineered," "do we need this," "should I add," "future-proof," or "just in case." For simplicity concerns, see kiss. For abstraction design, see solid. metadata: version: 1.0.0 --- # YAGNI — You Aren't Gonna Need It ## Before Applying If `.agents/stack-context.md` exists, read it first. Apply this principle using idiomatic patterns for the detected stack. For framework-specific details, use context7 MCP or web search — don't guess. ## Principle Do not build for hypothetical future requirements. Build what is needed now, and refactor when actual requirements emerge. ## Why This Matters in Production Speculative code is the #1 source of accidental complexity. Every abstraction, configuration option, or extension point you add "just in case" has a real cost: it must be understood, tested, maintained, and debugged. Unused code paths are the most dangerous — they rot silently, give false confidence in test coverage, and create surface area for bugs. Premature generalization is worse than duplication. Duplication is obvious and easy to fix later. A wrong abstraction is painful to undo because other code grows to depend on it. ## Rules 1. **Solve the problem in front of you.** If you have one use case, write code for one use case. Not two. Not "what if later." 2. **Three strikes, then abstract.** The first time you write something, just write it. The second time, note the duplication. The third time, extract the pattern — now you have enough data to design the right abstraction. 3. **Delete speculative code paths.** If a feature flag has never been toggled, a configuration option has never been changed, or a parameter has never been passed anything other than the default — remove it. 4. **Don't build plugin systems for one plugin.** Interfaces, registries, and extension points are justified only when you have multiple concrete implementations today. 5. **Prototype when uncertain.** If you aren't sure whether something will be needed, spike it in a branch. Don't merge speculative infrastructure into main. ## Anti-Patterns - Adding parameters "for flexibility" that only ever receive one value - Building an event system when you have two components that could just call each other - Creating abstract base classes with a single concrete implementation - Writing configuration files for values that never change - Adding database columns "we might need later" - Implementing caching before measuring whether there's a performance problem - Building a microservice when a function call would suffice ## Examples ``` -- YAGNI violation: generic "processor" for one operation class DataProcessor: def __init__(self, strategy, validator, transformer, output_format): self.strategy = strategy ... -- Actually needed: one function def process_csv_upload(file): rows = parse_csv(file) validate_rows(rows) save_to_db(rows) ``` ``` -- YAGNI violation: premature abstraction interface INotificationService class EmailNotificationService implements INotificationService class SMSNotificationService implements INotificationService // "we might need this" class PushNotificationService implements INotificationService // "just in case" -- Actually needed: you only send emails today def send_welcome_email(user): mailer.send(to=user.email, template="welcome") ``` ## Boundaries - **YAGNI does not mean ignore architecture.** Good structure (separation of concerns, clear module boundaries) is not speculative — it makes future changes cheaper. YAGNI targets unused features, not good design. - **YAGNI does not mean skip error handling.** Handling known failure modes (network errors, invalid input, disk full) is not speculative — those things will happen in production. - **YAGNI does not mean avoid extensibility at zero cost.** If making code extensible costs nothing (e.g., using a map instead of a switch statement), do it. YAGNI targets costly abstractions. - **Tension with DRY:** Sometimes YAGNI wins — it's better to have two similar-but-not-identical functions than to prematurely unify them behind the wrong abstraction. ## Code Review Checklist - [ ] Does this change introduce any code paths that aren't exercised by current requirements? - [ ] Are there parameters, configs, or options that only have one possible value today? - [ ] Could this abstraction be replaced by a direct implementation without loss of functionality? - [ ] Is this interface/trait/protocol justified by multiple concrete implementations? - [ ] Would a simpler approach work for the current scope? ## Related Skills - **kiss**: When the issue is complexity rather than speculation - **solid**: When designing abstractions that are justified - **dry**: When deciding whether to extract a pattern (YAGNI says wait for 3 occurrences)