Skip to content

Blog

AI makes code easy, and only a spec keeps it simple

Conversational coding piles every instruction onto the last until the code tangles. Rich Hickey's distinction between easy and simple explains why, and a research, plan, implement process is the fix.

Written by

Specification and review

Published: 17 February 2026 Updated: 2 min read

Your AI treats technical debt the same as business logic. Every line is just another pattern to preserve.

That’s not a model limitation. It is a design problem in how we use conversational AI for code.

The complexity spiral

You ask for auth. You get auth.js. You iterate. Add OAuth. Sessions break. By message 20, you’re not having a conversation anymore. You’re managing context so tangled even you don’t remember all the constraints.

Dead code from abandoned paths. Tests fixed by making them pass. Fragments of three different solutions overlapping.

Each instruction overwrites architectural decisions, with no resistance to bad ones. The code just morphs to satisfy your latest request.

Easy versus simple

Rich Hickey nailed this distinction 15 years ago. Easy means adjacent, within reach. Simple means untangled, one thing per piece.

AI is the ultimate easy button. Code appears instantly. But easy always means speed now and complexity later.

That trade-off used to work, because complexity accumulated slowly enough to refactor. AI destroyed that balance.

The fix: research, plan, implement

In the talk, a team at Netflix tried to refactor millions of lines of authorization code with AI. The agent kept spiraling and couldn’t separate business logic from old auth patterns.

The fix was a three-phase process, not better prompts:

  1. Research. Feed in architecture docs, probe the agent, correct its analysis. Compress 5 million tokens into 2,000 words of specification.
  2. Plan. Create implementation steps so clear any developer could follow them. Validate decisions before a single line is generated.
  3. Implement. With a clean spec, the agent produces focused code. No complexity spiral, no “wait, actually” moments.

The knowledge gap

AI generates thousands of lines in seconds. Understanding them takes hours. Every time you skip thinking to keep up with generation speed, you lose the ability to recognize problems.

The instinct that says “this is getting complex” atrophies when you don’t understand your own system.

The full argument is in this talk on easy versus simple in AI-generated code (opens in a new tab).

Are you generating code as fast as possible, or understanding it as fast as you generate?

Further reading

  1. Cheap code makes engineering discipline worth more Generating code got cheap, and anyone can do it. Engineering systems that hold up in production is the skill that gained value. 1 min readShort post
  2. Do the sprint planning work before the planning meeting Most of what a planning meeting answers needs data, not a meeting. Agents split stories, map dependencies, order tasks, write evil user stories and check acceptance criteria before anyone sits down. 3 min readShort post
  3. Do the refinement research before the refinement meeting Refinement meetings exist to clarify requirements and surface blockers. An agent with codebase access does most of that research and questioning before the meeting, so the team only decides. 1 min readShort post

All 23 posts on Specification and review

ClientsClient work

Test the constraint in your system

The Factory Readiness Assessment connects this research to your value stream, your data, and the next decision.

Training on this topic: Agentic Engineering for Developers and QA
See the assessment

Want to check one team first? The self-check: twelve yes or no questions, three minutes, instant result, no account. Take the self-check