Smell #6: Magic Black Box
Severity: High
Magic Black Box: Code generated by AI that passes tests and works in demos but whose internal logic, design rationale, and potential side effects are not understood by the team.
Symptoms
How to recognize this smell:
- [ ] "The AI wrote it" is the only explanation for why a pattern was used.
- [ ] Developers avoid modifying the code for fear of "breaking the magic."
- [ ] A complex algorithm has zero human-authored comments or documentation.
- [ ] You are relying on "Vibe Coding" — if the demo passes, you don't read the code.
Self-Assessment
If you checked 2+ items, your project is filled with Magic Black Boxes.
Example
The "Opaque Optimizer"
AI Output:
// AI-generated priority algorithm
function getScore(t) {
const f = Math.exp(-0.1 * t.age);
const w = Math.pow(t.p, 1.3);
const d = 1 / (1 + Math.exp(-0.5 * (t.due - 3)));
return (f * w * d) / 0.62;
}
Why it's a Black Box: Why 1.3? Why 0.62? What is the decay curve? If the business logic for "Priority" changes, no one knows how to adjust these numbers. The team owns logic they cannot maintain.
Debt Impact
This smell is the primary driver of:
| Debt Category | Impact | |---------------|--------| | 🧠 KNOW | Total loss of mental models (Comprehension Debt). | | 👥 TEAM | Onboarding becomes impossible; "Bus Factor" drops to zero. |
How to Fix
- Request Explanation: Ask the AI to explain the logic line-by-line in a new chat.
- Refactor for Clarity: Rewrite the logic using descriptive variable names and standard patterns.
- The "Junior Test": If you can't explain the code to a junior developer, it remains a Black Box. Don't stop refactoring until you can.
How to Prevent
- The "Explain Before Merge" Rule: PR authors must document the "Why" of all prompted logic.
- Radical Understanding: Spend 3x more time reading AI code than you spent generating it.
- Reject "Clever" Code: Prefer simple, readable logic over "AI-optimized" abstractions.
Related Smells
- Smell #10: Missing Self-Review — How black boxes get merged.
- Smell #14: Silent Failure — Black boxes often fail invisibly.
Book Reference
- Chapter 1: How black boxes begin with the first prompt.
- Chapter 5: How agents create massive black boxes across multiple files.
- Chapter 12: The ultimate "onboarding nightmare" caused by black boxes.