How to write an implementation plan for an AI agent

An AI agent starts every session with no memory of the last one. Long chats get summarised and details drop out, and where the agent has no instruction, it guesses. You usually find out later, in a change you didn't ask for.

An implementation plan fixes that. It's a Markdown file in the repo that says what to build and how to tell when each part is done. My last post gave it one bullet. This one goes further, with examples from the plan I used to build this portfolio with Claude Code.

Put the plan in a file in the repo, where you and the agent both read it and git keeps its history. Claude Code loads a short CLAUDE.md at the start of every session, and mine points to docs/implementation-plan.md. Other agents read AGENTS.md or .github/copilot-instructions.md the same way. Rules for every task, like "Style through tokens", sit in both files. The build order, the decisions and the status live only in the plan.

Say what you won't build. Start with what the product is for, in a sentence or two, then list what's out of scope. If the agent sees a feature in a prototype, it builds it. My prototype had settings to swap the background and accent colours. The plan says dark only, and none of those settings got built.

Say which source wins. Most projects have more than one source of truth: a PRD, a Figma file, a prototype, old notes. In my plan the PRD decides scope, and the prototype decides pixels and copy. Plans can disagree too, so the blog's own plan says in its first lines that it wins for anything about the blog.

List what you haven't decided. Note which phase each open decision blocks, and what the agent should do in the meantime. My case-study URLs came from the old site, and I hadn't listed them when the build got there. The plan told the agent to use placeholder URLs, kept in one constant "so the swap is a single edit."

Split the build into phases, in the order the parts depend on each other, and keep each one small enough to review in one sitting. My plan had six. The homepage phase went one section at a time.

End every phase with "Done when" and a check you can run, written before the work starts. My homepage check was strict. Every section had to match the prototype at 1440px and work at tablet and phone widths. Even the copy had to match, character for character. The agent can run a check like that itself, so ask it to open the page in a browser with Playwright and report back with screenshots.

The build never follows the plan exactly. When a decision changes, update the plan first and the code second, in the same commit, or the next session follows the old version.

Write an "As built" note after each phase. Have the agent record what shipped and where it differs from the plan, with the reason. These notes turned out to be the most useful part of my plan. In the first phase, create-next-app refused to set up the project in a folder that already had files in it. The note explains the workaround, including why the repo kept its own .gitignore, so a later session doesn't swap it back.

Turn bugs into rules. When a bug could happen again, fix it, then add a line to CLAUDE.md so the agent sees it every session. Two from this site:

• The blank page. The first scroll animations gave a blank page to anyone with reduced motion turned on. The rule now says the page must render the same on the server and in the browser, whatever the motion setting.
• The missing font size. tailwind-merge, which combines Tailwind classes, read the site's custom font sizes as colours. A large number in a case study shrank to 16px, with no error. The rule now says to add every new font-size token to one list in utils.ts.

Keep the reason next to the decision. Without one, a later session sees a choice that looks wrong and "fixes" it. My showreel is one MP4 with no WebM version, and the plan gives the numbers. The WebM was bigger and scored 83 on a video quality test, against 96 for the MP4. The note ends with "Re-measure before adding one back."

Put the status at the top. Open the plan with where the project stands and a checklist of next steps. Then a new session can pick up the work with one prompt.

Read docs/plan.md and do the next unchecked step in "Next steps".

Before you start, tell me which step it is and what its "Done when" check is. When you finish, run the check, tick the step, and add an "As built" note if anything changed.

Fill in the brackets and run it in a fresh session. In Claude Code, use plan mode, so the agent can read the project but can't change any file until you approve.

I want to build [what you are building] for [who it is for]. The goal is [the outcome that matters].

Before you write anything, interview me. Ask about the goal, the users, what is out of scope, the sources of truth (PRD, designs, prototype), the tech stack, and how we will know each part works. Ask one group of questions at a time.

Then write docs/plan.md with these sections:
1. Status, and a "Next steps" checklist.
2. Goal, and what is out of scope.
3. Sources of truth, and which one wins when they disagree.
4. Rules that apply to every task.
5. Phases in build order. Each phase lists its tasks and ends with "Done when:" and a check you can run.
6. Open decisions, and the phase each one blocks.
7. A decision log: each decision, its reason, and what would change it.

Do not write any code yet. When the plan is ready, list the parts you are least sure about.

Or write the plan yourself, starting from this skeleton.

# Implementation plan: [project]

> **Status:** Phase 1 in progress.
> **Reads with:** prd.md (scope), the design file (pixels and copy).
> Where they disagree: [which one wins].

## Next steps
- [ ] …

## Goal
One or two sentences: who it is for, and what it changes for them.

## Out of scope
- …

## Rules for every task
- Style through design tokens. No raw hex colours or one-off font sizes.
- Reuse an existing component before writing a new one.
- Check every change in a browser at desktop, tablet, and phone widths.

## Phases

### Phase 0: Foundation
- Tasks …
- **Done when:** a check you can run, written before the work starts.

**As built:** what shipped, what differs from the plan, and why.

### Phase 1: …

## Open decisions
- [Decision]. Blocks Phase [n]. Options: …

## Decision log
- [YYYY-MM-DD] The decision. The reason, with evidence. What would change it.

Try the prompt on your next project. Before the agent writes any code, read the plan, and look hardest for anything too vague to test. Or see the work this plan built.