Why a plan helps AI write better code, and when it doesn't

When AI-written code goes wrong, the code itself often isn't the problem. It compiles, it may even be tidy, and it solves something slightly different from what you wanted. It adds the abstraction you avoided on purpose, or the feature you decided against last week.

A plan helps with that kind of failure, and it's worth being precise about why, because it doesn't help with every kind.

The assistant can't see your decisions

Anthropic's best practices for Claude Code make the key point: Claude starts by reading your code and is very good at it, so it already finds your layout, conventions and test framework. What it can't find is the information that was never in the repo. Their first example is "a decision your team made in a meeting".

That is what an architecture plan holds. Code shows what was built. It rarely shows why, what was rejected, or what's coming next. Without that, an assistant has to infer your intent from what exists, and the existing code can't tell it what you decided not to do.

Four things a plan gives the assistant

1. Decisions, with the reason

"Use Postgres" can be seen in the code. "Use Postgres because orders and payments change together" can't, and it's the reason that lets an assistant handle a case you didn't foresee.

2. Scope, including what's out

Assistants tend to complete things. Telling one what you won't build is often worth more than telling it what you will. On a Hunch board, that's a single line:

note "Rescheduling by chat is out for now. A reply can only confirm or cancel." [out-of-scope]

3. Where things belong

When a change touches several parts, the plan says which part owns it. A box can name the code it stands for, which saves the assistant from guessing:

jobs: Scheduled job "Send reminders" "" "Every 15 minutes" [path=src/jobs/reminders]

4. Something to be checked against

Anthropic's guide describes reviewing a diff against a spec rather than hunting for problems in general, and warns that a reviewer asked to find problems will always find something. A plan gives that review a target:

Use a subagent to review this diff against board.hunch. Check that it follows the decisions on the board and doesn't build anything marked out of scope. Report only gaps that affect correctness. Skip style.

Why text, and not a picture

A plan only helps if it's in front of the assistant and still true. That rules out a lot of what teams use today: a whiteboard photo, a design file in another tool, or a wiki page from last quarter.

That's the idea behind Hunch Board: you get a drawing, and the assistant gets the lines it's drawn from. Here's how to set it up with Claude Code.

What a plan won't fix

• Bugs. A plan doesn't catch an off-by-one. Tests do. Anthropic's advice stands: give the assistant something to run that comes back pass or fail.
• A wrong plan. The assistant will carefully build the wrong thing. That's why you build a thin slice first.
• A stale plan. An outdated plan is worse than none, because it's believed. Change it in the same commit as the code.
• A bloated plan. Each detail competes for attention. If the code already shows it, leave it out.

What to write down

Anthropic's guide offers a good test before writing anything for Claude: could it find this by reading the code, and would it actually go and look? If both are yes, leave it out. For a plan, that usually leaves this:

• The main parts and how they talk to each other
• Each decision that was hard to make, with the reason
• What's out of scope
• What must never go wrong
• The questions still open

Then there's the question of where each thing goes. CLAUDE.md or an architecture board covers that.

How to find out if it works for you

Pick two similar features. Build one the way you do today and one from a short plan. Count how many times you had to correct the assistant's direction, and how much of the first diff you threw away. Those two numbers will tell you more than any article, including this one.