kiss

KISS — Keep It Simple

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

Given two solutions that produce the same result, prefer the one that is easier to read, understand, and change.

Why This Matters in Production

Simple code survives contact with production. Complex code breaks in ways that are hard to diagnose, hard to fix, and hard to verify the fix didn't break something else. Every incident response starts with someone reading code under pressure — if they can't understand it quickly, the outage gets longer.

Complexity compounds. A "slightly clever" solution today becomes an "incomprehensible" solution after six months of patches by three different developers.

The most dangerous bugs hide in code that's too complex for any single person to hold in their head.

Rules

1. Optimize for reading, not writing. Code is read 10x more often than it's written. A few extra lines of clear code beats a one-liner that requires a comment to explain.
2. Use boring technology. Prefer well-understood tools, patterns, and libraries over novel ones. Novel solutions carry hidden costs in debugging, hiring, and documentation.
3. Limit nesting depth. If a function has more than 3 levels of nesting, flatten it with early returns, guard clauses, or extraction into helper functions.
4. One function, one job. If you need the word "and" to describe what a function does, split it.
5. Name things for what they do, not how they do it. get_active_users() not query_db_filter_status_map_results().
6. Avoid clever tricks. Bitwise hacks, regex one-liners for complex parsing, operator overloading for non-obvious operations — these optimize for the writer's ego, not the reader's comprehension.
7. Prefer explicit over implicit. Magic values, hidden state, implicit type conversions, and action-at-a-distance make code unpredictable.