Design Heuristics and Smells

Software design doesn’t come with a rulebook that covers every situation. Instead, experienced practitioners develop heuristics, rules of thumb that guide decisions when the “right” answer depends on context. This section lives at the heuristic level: the layer of taste, judgment, and pattern recognition that separates adequate code from code that’s pleasant to work with over time.

Heuristics aren’t laws. They conflict with each other, they admit exceptions, and they require judgment to apply well. “Keep it simple” is excellent advice until simplicity means duplicating the same logic in twelve places. The skill is knowing when each heuristic applies and when to set it aside.

This section also introduces smells, surface symptoms that suggest something deeper may be wrong. A code smell doesn’t prove a defect exists; it raises a question worth investigating. In the agentic coding era, a new category of smell has emerged: patterns in AI-generated output that suggest the model optimized for plausibility rather than understanding. Learning to recognize both kinds of smell makes you a better reviewer, whether you’re reviewing human work or agent output.

This section contains the following entries:

• KISS — Keep it simple. Remove needless complexity.
• YAGNI — You aren’t gonna need it. Resist speculative generality.
• Local Reasoning — Understanding a part without loading the whole system into your head.
• Make Illegal States Unrepresentable — Design types and structures so invalid conditions cannot be expressed.
• Smell (Code Smell) — A surface symptom suggesting a deeper design problem.
• Smell (AI Smell) — A surface symptom that output was produced for plausibility rather than understanding.
• Cargo Cult Programming — Copying the visible shape of working software without understanding the reason it worked.
• Architecture Astronaut — Designing at an altitude so high that the abstractions stop touching any real problem.
• Jagged Frontier — The observation that AI capability is uneven in ways that do not track human intuition about task difficulty.
• Load-Bearing — A piece of code, comment, test, or instruction whose removal would break something important, usually in a non-obvious way.
• Pinning — Explicitly fixing a choice (a version, a model id, a prompt, a schema, a decision, a snapshot) so downstream work can rely on it not changing without a deliberate update.
• Footgun — A feature, tool, or default whose correct use is less obvious or less ergonomic than its dangerous use; the design that makes self-inflicted damage the path of least resistance.
• DWIM — The system-design stance of treating user input as evidence of probable intent and acting on the inferred form, with roots in 1966 Lisp and its sharpest modern form in every LLM coding agent.
• Best Current Practice — A recommendation that reflects the community’s present understanding, with the expectation it will evolve.
• Premature Optimization — Spending effort making code faster before you know whether the optimization matters.
• Vibe Coding — Generating code through AI prompts without reading, understanding, or verifying the output.