Six AI Coding Failure Modes and How to Fix Them: Be the Strategic Commander

Matt Pocock, creator of the skills repository ( https://github.com/mattpocock/skills), explored why AI-assisted programming often goes off track. He tried specification-driven development (SDD) — writing a spec, letting AI generate code, then iterating on the spec — but found the first iteration was acceptable, the second worse, and the third incoherent. The root cause is not AI itself but the codebase: AI performs far better in a well-structured codebase, while a poor one accelerates entropy.

Failure Mode 1: AI Doesn't Understand Your Intent

You have a design in mind; AI produces something else. This is a communication gap, not an AI flaw. Frederick Brooks in The Design of Design describes a "design concept" — a vague, shared mental model of what is being built that flows between collaborators. It is not a document or PRD but an intangible model in the brain. Between you and AI, those mental models are misaligned.

Solution: Grill Me Skill. Make AI ask you questions until both sides reach consensus. Matt's version prompts AI to ask 40–100 questions, walking each decision branch to align the two design concepts. The resulting dialogue can be turned into a PRD or issue for AI execution.

Failure Mode 2: AI Is Verbose but Unclear

AI uses flowery language but misses the point, similar to the domain-expert vs. developer language gap. Important details get buried in walls of text you don't have time to read.

Solution: Ubiquitous Language (from Domain-Driven Design). Create a Markdown glossary defining every key concept, its English/Chinese terms, and usage boundaries. Both AI and humans use it. Matt built a skill that auto-scans the codebase to extract terms and generate the glossary, keeping it active during planning, coding, and Grill Me sessions so AI's reasoning stays aligned with expectations.

Failure Mode 3: AI Writes Code That Doesn't Run

Logic may be correct but execution fails. Experienced developers write a little, compile, test, confirm; AI writes a large block then checks types and tests at the end.

Solution: Test-Driven Development (TDD). TDD forces small steps: write a test, implement, refactor. Faster feedback loops. However, TDD has a learning curve — deciding unit size, what to mock, which behaviors to test — and some argue it wastes tokens. Matt found a key correlation: a good codebase is naturally testable. Better codebase → stronger feedback loop → higher-quality AI feedback → better AI output → a positive flywheel. He also suggests running mutation score periodically.

Failure Mode 4: AI Creates Shallow Module Hell

AI defaults to generating many small modules — each with little functionality but complex interfaces and dense interdependencies. AI itself struggles to navigate this maze, often failing to locate the right file.

Solution: Deep Modules (from John Ousterhout's A Philosophy of Software Design ). Good modules are "deep": a simple interface hiding rich functionality. Fewer modules, more power per module, simpler interfaces. AI doesn't need to understand internals; it works through the interface. Refactoring from shallow to deep is systematic: scan code, group related logic into a deep module, test at the interface, delegate implementation to AI.

Failure Mode 5: Your Brain Can't Keep Up

AI increases code output but your cognitive capacity doesn't scale. You must simultaneously comprehend AI-generated code, maintain the design concept, and track module changes — cognitive load spikes.

Solution: Design Interfaces, Delegate Implementation. Treat deep modules as "gray boxes": you define the interface and behavioral contract, ignore internal implementation. External boundaries are testable; internals go to AI. You verify from outside; AI fills in. This drastically reduces mental burden. Prerequisite: you must know the system's module map intimately. Every change must specify in the PRD which module changes and how its interface evolves.

Failure Mode 6: Disinvestment in System Design

The "spec-to-code" movement often shifts all energy to iterating specs, abandoning holistic system structure design. Code becomes cheap to produce, but its impact may be costly; bad code can cause severe losses.

Solution: Daily Investment in System Design. Kent Beck's dictum: invest in system design every day, not just at project start. Matt embeds this by making every PRD explicitly state module changes and interface designs, folding system design into the daily rhythm.

Summary

Matt likens AI to an excellent tactical programmer — a sergeant on the front lines changing code. You need a higher-level strategist: yourself. The 20 years of software fundamentals — design patterns, modularity, DDD, TDD — are not obsolete in the AI era; they are more critical. AI won't do design for you; it only accelerates your design decisions. Good design → AI accelerates you. Bad design → AI accelerates your collapse.