Skip to content

Plan and Design First

The instinct with a capable AI is to jump straight to "build it." Resist that. The work that pays off most is the thinking you do before any code exists: what you actually want, what constrains it, and how it should fit together. Get that right and the implementation is almost mechanical. Get it wrong and you'll spend more time reviewing and reverting than you saved.

Why this matters — Limitation #2 (No real thinking / no persistent learning). A model doesn't brainstorm with you over a week, sleep on a problem, or carry hard-won lessons from the last feature into this one. It produces its best guess from the prompt in front of it, right now. That means you own the intent and the design — and you have to supply them explicitly. A written plan is how you inject the thinking the model can't do on its own, and (per Limitation #1) a compact, durable plan keeps the model focused instead of drowning in exploration debris.

Start with intent, not implementation

Before asking for code, answer: what am I really trying to achieve, and how will I know it worked? A model will happily implement the wrong thing very efficiently. The cost of a misunderstanding is highest at the start and compounds with every line built on top of it.

So begin one level up from code: the intent (the outcome you want) and the design (how the pieces fit). Implementation is the easy part once those are settled.

Write a short design note

For anything beyond a trivial change, write a brief design note first. It does not need to be long — half a page is often plenty. Cover:

  • Goal — the outcome, in one or two sentences.
  • Constraints — frameworks, performance budgets, compatibility, deadlines, things you must not break.
  • Edge cases — the inputs and situations that will actually bite: empty states, failures, concurrency, large inputs, permissions.
  • Architecture expectations — where this lives, which modules it touches, the boundaries it must respect.
  • Non-goals — what this work explicitly will not do. This is where you prevent scope creep and over-engineering.

You can write this yourself, or brainstorm it with the agent and have it draft the note — but you own the final version. It's the contract the rest of the work is measured against.

Have the agent review the plan before coding

Once a plan exists, ask the agent to critique it before implementing: "Here's the plan. What's missing? What edge cases haven't I considered? Where is this more complex than it needs to be?" This catches gaps while they're cheap — a paragraph to fix, not a pull request to unwind. It also surfaces hidden assumptions before they harden into code.

Always start non-trivial work in plan mode. Plan mode is a state where the agent investigates and proposes an approach but is not allowed to change files. Make it your default for anything that isn't a one-liner. You read the plan, correct it, and then let it build — turning "review 300 lines of code" into "review one paragraph." It is the cheapest quality lever you have.

Split larger work into small, testable chunks

A plan that says "build the whole feature" gives you one giant diff that's painful to review and risky to ship. A good plan decomposes the work into a sequence of small steps, each of which can be built and verified on its own:

  • Each chunk should be independently testable — you can confirm it works before moving on.
  • Each chunk should leave the system in a coherent state.
  • Small chunks keep the context focused (Limitation #1 again) and make it obvious which step introduced a problem.

Small, verified steps beat one heroic leap, every time. Verification belongs in this loop from the start — see Verification and Review.

Write the plan to a file — for the agent and the human

Don't keep the plan in the chat. Write it to a markdown file in the repo. This is a deceptively important habit, and it serves two readers:

  • The agent, later. A written plan is a clean, low-noise context artifact. When you start a fresh execution session (see Context Management), you hand it the plan instead of re-deriving everything. The model's whole context budget goes to building, not rediscovering.
  • The human, later. The teammate who picks this feature up next week — or you, after you've forgotten the details — gets the reasoning, the constraints, and the non-goals in one place. It answers "why was it built this way?" long after the conversation is gone. This is a direct counter to Limitation #2: the file is the durable memory the model itself doesn't keep.

A plan written to a file is the rare artifact that pays off twice — once during the build, and again every time someone has to understand the result.

A concrete embodiment: brainstorm → write plans → execute

This whole philosophy is captured in a concrete workflow you can use today — the superpowers flow of brainstorming a feature, writing the plan to a file, and then executing the plan in a focused session:

  1. Brainstorm — explore the problem and design space with the agent, pressure-testing intent and edge cases before committing.
  2. Write the plan — distill the brainstorm into a structured plan file in the repo.
  3. Execute the plan — open a fresh session that works step-by-step from the plan, with review checkpoints.

It is exactly the "intent → design note → small testable chunks → durable artifact" loop described above, packaged into repeatable steps. See Superpowers and Workflows for how to run it, and From Feature Idea to Plan to Handoff for the same loop walked end-to-end on a real feature.

Quick checklist

  • Intent and success criteria written down before any code
  • Short design note: goal, constraints, edge cases, architecture, non-goals
  • Agent asked to critique the plan first
  • Started in plan mode for non-trivial work
  • Work split into small, independently testable chunks
  • Plan saved to a markdown file in the repo, not left in the chat

Sources