Smell #8: Over-Structuring
Severity: Medium
Over-Structuring: A phenomenon where AI assistants apply design patterns dogmatically, creating unnecessary layers of abstraction, factories, and boilerplate for simple tasks.
Symptoms
- You have a "Factory for a simple Object" or an "Adapter for a single function."
- There is more structure (interfaces, types, wrappers) than actual business logic.
- Adding a simple field to a form requires modifying five different files.
- The AI proposes an "Enterprise-Ready" solution for a prototype.
Self-Assessment
If your codebase has more "structural files" than "feature files," you are Over-Structuring.
Example
The "Enterprise" Config
Task: "Create a simple config for the API URL." AI Output:
// ConfigStrategyFactory.js
// ConfigValidator.js
// ConfigBuilder.js
// EnvConfigProvider.js
// ... 5 more files for one URL string.
The Clean Alternative:
const API_URL = process.env.API_URL || 'http://localhost:3000';
Debt Impact
This smell contributes to:
| Debt Category | Impact | |---------------|--------| | 🏗️ ARCH | Unnecessary complexity makes the system harder to navigate and maintain. | | 🧠 KNOW | The "Signal-to-Noise" ratio is poor; logic is buried under boilerplate. |
How to Fix
- Apply YAGNI: Ask "Do I actually need this abstraction today?"
- Flatten the Structure: Merge small, over-engineered files into single modules.
- Prefer Simple over "Correct": If a standard pattern feels like overkill, it probably is.
How to Prevent
- The "Keep it Simple" Constraint: Include "Minimal Viable Abstraction" in your Clean Prompts.
- Prototype First: Ask for a single-file implementation first, then refactor only if needed.
- Engineering Judgment: Don't assume the AI's "Enterprise Pattern" is the best pattern for your project.
Related Smells
- Smell #6: Magic Black Box — Over-structuring often hides simple logic in a black box.
- Smell #9: Style Drift — Different structures for different modules.
Book Reference
- Chapter 4: The Power of Rules — how rules can force over-structuring.
- Chapter 13: Clean Prompts — specifying "minimal structure" requirements.