By ByteBot
Ayman Nadeem, former senior engineer at GitHub, spent months building Nuanced — a coding tool where generating a detailed spec before writing any code was the entire point. He launched it on June 24. By September 24, he published a post-mortem titled “Plan mode is dead.” It hit 483 points and 432 comments on Hacker News in a day. Not because he killed his own product. Because he named something developers have been quietly experiencing for months: the planning phase we thought we needed is making us slower, not safer.
What Plan Mode Was Supposed to Do
Plan mode had a logical premise: separate thinking from building. Before the agent touches a single file, it reads the codebase, proposes a solution, and shows you exactly what it intends to do. You review it. You approve it. Then execution begins. The idea was that developers stay in control at the architectural level without having to write every line themselves.
Nuanced took this to its extreme — a persistent “living spec” that captured goals, constraints, invariants, and scope boundaries. The spec was the source of truth. Agents worked from it. Changes went back into it. It was, in principle, a governance layer.
In practice, nobody read it.
The Problem That Plan Mode Solved No Longer Exists
Nadeem’s diagnosis is precise: plan mode historically served two jobs. First, it forced developers to specify instructions precisely enough for an agent to execute correctly. In 2023 and 2024, this was essential — models went sideways on vague instructions constantly. Second, it helped humans understand what they were building, keeping architectural decisions visible before they became embedded in code.
The first job has evaporated. Current-generation models understand intent well enough that the gap between “what I meant” and “what I wrote” has collapsed. Exhaustive upfront specification went from a necessary control to an expensive ceremony. The second job — building understanding — is still real, but a front-loaded spec document is the wrong tool for it. Planning should be continuous, not sequential.
“I had confused planning with a plan. Planning is the activity; a plan is the artifact. The activity is essential. The artifact increasingly isn’t.”
— Ayman Nadeem, founder of Nuanced
The Loop That Actually Works
What works in practice is iterative: understand → act → inspect → clarify → adjust → act again. Planning happens inside every step of that loop — it just is not a document. The developer reviews the diff, adjusts scope, corrects course. The planning is in the review, not the spec.
This is faster and more accurate than plan-first workflows because the plan updates with every iteration. A spec written at the start of a session is already outdated by the first code review.
The Numbers Behind the Shift
JetBrains’ 2026 survey of over 15,000 professional developers shows where the industry actually stands: 90% use AI coding agents at least weekly, 68% daily. One in five developers writes zero code without AI assistance. And yet developer trust in AI accuracy fell from 43% to 29% in a single year. Active distrust jumped from 31% to 46%.
That gap — mass adoption meeting collapsing trust — is the governance crisis plan mode was supposed to prevent. It did not work. Teams that relied on plan approval as their safety gate are discovering that approved plans still produce subtly wrong code, hallucinated dependencies, and security vulnerabilities that pass syntactic checks at a 95% rate while failing semantic ones constantly.
The Replacement: Context Files and PR Gates
The planning that actually matters is not session-specific — it is project-level and persistent. AGENTS.md and CLAUDE.md files are version-controlled briefings that survive across sessions and improve over time. On September 18, Anthropic shipped AGENTS.md support in Claude Code 2.1.277. One file now works across Codex CLI, Copilot CLI, Gemini CLI, Cursor, and Claude Code. The industry is converging on a standard, and it lives in your repository, not a session window.
These files encode continuous planning rather than front-loading it. The AGENTS.md spec recommends keeping the root file under 20-30 lines — longer files measurably hurt agent performance. Architecture decisions, coding conventions, explicit anti-patterns, testing requirements: all of it lives there, version-controlled, collaborative, and persistent across every session.
The real governance gate moves from “approve the plan” to “review the PR.” AI-generated code has 1.7x more defects than human-written code despite arriving syntactically polished. Approving a plan before execution does not prevent semantic errors; reviewing a diff after execution does. PR review is the control that actually works — it just has to be taken seriously, not rubber-stamped because an agent wrote the code.
What to Do Now
If your team is still treating plan mode as its primary governance mechanism, the JetBrains data suggests you are in the majority — and the trust numbers suggest it is not working. The move is not to eliminate oversight but to relocate it: from the start of the session to the end of the diff.
- Create or update your
AGENTS.mdorCLAUDE.mdwith architecture decisions and explicit anti-patterns - Treat every agent-written PR as requiring the same scrutiny as a junior developer’s first commit
- Use plan mode selectively — for hard-to-reverse operations (schema migrations, security changes) — not as a default workflow
- Track your own trust gap: if you are approving agent PRs faster than you can actually read them, the plan mode approval was theater
Nuanced’s product failed. The insight it produced is worth more than the product would have been.
