Plan big builds: from messy idea to a plan an agent can run

Use this first, when the idea is a page of notes or a few sentences.

I want to build something and my notes are messy. Here they are: <notes> [PASTE YOUR NOTES, VOICE MEMO TRANSCRIPT OR ROUGH IDEA] </notes> You are a product engineer turning this into a spec, a written description of exactly what will be built. Process: 1. Interview me one question at a time. Skip anything the notes already answer. Focus on the hard parts: who uses it, what they do first, what happens when something goes wrong, what data is stored, and what is out of scope. 2. Before your first question, tell me roughly how many you expect to ask. Stop when you can write the spec without guessing. 3. Write the spec with these sections: Problem, Users, What version 1 does (numbered), Out of scope, Main user journeys step by step, Data it stores, Edge cases and errors, How we will know it works, Open questions. Where I contradicted myself, point it out and ask. If the idea is too big for one version, say so and suggest what to cut.

Swap the highlighted parts for your own words.

Tip

• In Claude Code, ask Claude to save the result to SPEC.md, then type /clear before the next prompt.

Use this once the spec exists and before you choose any tools.

Here is the spec for what I am building: <spec> [PASTE SPEC.md] </spec> My constraints: budget [AMOUNT PER MONTH], skills [WHAT YOU OR YOUR TEAM KNOW], deadline for a first version [DATE], expected users in year one [NUMBER]. You are a software architect. Propose three different ways to build this. Make them genuinely different, such as one using managed services, one self hosted and one minimal. For each option give: the main parts and how they connect, the tools and services, monthly cost at launch and at 10 times the users, time to a first working version, what it is good at, and what breaks first as it grows. Then put all three in one comparison table. Recommend one and explain why for my constraints. Say what would have to change for you to pick a different one. If you are unsure of a price, say so and tell me which pricing page to check.

Swap the highlighted parts for your own words.

Tip

• Ask "what is the hardest thing to change later in your recommended option?" before you commit to it.

Use this when the new work goes into a project that already exists.

Read SPEC.md. Then explore this codebase before you suggest anything. Open the files you rely on and do not guess about code you have not read. 1. Describe how the project is organised today: the main folders, patterns, libraries, and how data and requests flow. 2. List every place the new feature touches, with file paths. 3. Propose two ways to add it. One should follow the existing patterns closely. The other can change something if that is clearly better. 4. For each, list the files to create or change, what could break, and how we would test it. 5. Recommend one. Do not change any files. This is planning only.

Tip

• Run this in plan mode so Claude cannot edit anything by accident.

Use this after you pick an approach, before you start building.

Here is my spec and chosen approach: <spec> [PASTE SPEC AND THE CHOSEN OPTION] </spec> Imagine it is six months from now and this project has failed. Write down the most likely reasons why. Cover technical risks (a service limit, a hard feature, data loss), product risks (nobody uses the main feature), time risks (a part that takes three times as long) and outside risks (a price rise, an API that changes). Output a table ranked from most to least dangerous, with columns: Risk, Likelihood (high, medium, low), Impact (high, medium, low), Early warning sign, What to do now to reduce it. Then name the single riskiest assumption in the whole plan and suggest the cheapest experiment that would test it in under two days. Be blunt. I want to hear it now.

Swap the highlighted parts for your own words.

Tip

• Paste the top three risks into the build order prompt, so you build the risky parts early.

Use this when one unknown could sink the plan, such as whether an API can do what you need.

Before we build anything real, I want to answer one question: [THE QUESTION, FOR EXAMPLE CAN THIS PAYMENT API HANDLE REFUNDS FROM OUR SERVER]. Build the smallest throwaway experiment that answers it. Put it in a folder called spike/ so it stays separate from the real code. Rules: 1. Tell me your plan in three or four lines before you write code. 2. Use fake or test data and test accounts only. 3. Stop as soon as the question is answered, yes or no. 4. Report: the answer, the evidence (the command you ran and what it returned), anything surprising, and what it means for the plan. If you cannot answer it without something from me, such as an API key, stop and ask.

Swap the highlighted parts for your own words.

Tip

• Delete the spike/ folder once you have the answer, or keep it as a reference. Do not build the real feature on top of it.

Use this after the spec, approach and risks are settled.

Read SPEC.md and the chosen approach in [FILE, FOR EXAMPLE DESIGN.md]. Break the work into tasks. Each task must: 1. Do one thing that can be checked on its own. 2. Be small enough to finish in one Claude Code session. 3. Have a done condition: a test that passes, a command that succeeds, or something I can see in the browser. 4. List the files it will likely create or change. 5. Name the tasks it depends on. 6. Have a size: S (under an hour), M (a few hours), L (a day). Split any L task into smaller ones. Output a numbered list in that format. After the list, point out any spec requirement that no task covers, and any task that does more than the spec asks for.

Swap the highlighted parts for your own words.

Tip

• If the list has more than 30 tasks, ask Claude to group them into milestones, each ending in something that works.

Use this once you have the task list.

Here is my task list and the top risks: <tasks> [PASTE THE TASK LIST] </tasks> <risks> [PASTE THE TOP THREE RISKS] </risks> Put the tasks in the order I should build them. Follow these rules: 1. Start with the thinnest version that runs from end to end, even if each part does almost nothing. 2. Move tasks that test a big risk as early as their dependencies allow. 3. The project should work after every task. 4. Mark which tasks can run at the same time because they touch different files. Output: the ordered list grouped into milestones, the critical path (the chain of tasks that sets the finish date), and the first three tasks to start this week. Explain any choice that is not obvious in one sentence.

Swap the highlighted parts for your own words.

Use this to turn everything above into one file Claude Code can work through across many sessions.

Write PLAN.md for this project. A fresh Claude Code session with no memory of this conversation must be able to read it and do the next task correctly. Use SPEC.md, the chosen approach and the ordered task list. PLAN.md must contain, in this order: 1. Goal: two sentences. 2. Context: the stack, how to run the app, how to run the tests, with exact commands. 3. Rules: keep changes small, follow the existing patterns, never edit or delete a test to make it pass, ask before anything that cannot be undone. 4. Tasks: a checkbox list in build order. Each task has its done condition, the files it touches, and its dependencies. 5. Definition of done for the whole project. Also create PROGRESS.md with a dated line for what is finished and any notes the next session needs. Then check the plan yourself: read it as if you were a new session and list anything that would make you guess. Fix those gaps before you finish.

Tips

• Commit PLAN.md and PROGRESS.md with git, the tool that records versions of your code, so every session and every helper agent sees the same plan.
• Claude works less well as a long session fills up with old messages. A plan file lets each new session start clean and still know the plan.

Use this in a fresh session after PLAN.md is written, before any building starts.

Read SPEC.md and PLAN.md. You are a reviewer who did not write this plan. Find gaps that would cause the build to fail or miss a requirement: 1. Requirements in the spec that no task delivers. 2. Tasks in the wrong order, where a task depends on something built later. 3. Done conditions that cannot actually be checked. 4. Missing setup: accounts, keys, environment variables, data. 5. Tasks too big for one session. For each gap give the task number, the problem, and a fix. Flag only gaps that affect correctness or the spec. List nice to have ideas separately and keep that list short. If the plan is sound, say so.

Tip

• Type /clear before this prompt so Claude reviews the plan with fresh eyes.

Use this at the start of every build session.

Read PLAN.md and PROGRESS.md, and run `git log --oneline -10` to see recent work. 1. Run the tests and tell me the result before you change anything, so we know the starting state. 2. Pick the first unchecked task whose dependencies are done. Tell me which one in a sentence. 3. Do that task only. 4. Check it against its done condition and show me the evidence: the command and its output, or a screenshot. 5. Tick the task in PLAN.md and add a dated line to PROGRESS.md with what you did and anything the next session should know. If the task turns out bigger than planned, or the plan is wrong, stop and tell me. Do not quietly change the plan.

Tips

• Type /clear between tasks. /clear starts a fresh conversation, and the new session reads the files to pick up where the last one stopped.
• Commit after each task so you can go back if a later task goes wrong.

Use this when the plan is longer than the time you have.

I have [NUMBER] days until [DEADLINE OR EVENT]. Here is my plan: <plan> [PASTE PLAN.md] </plan> Help me cut it down so a working version ships on time. 1. Ask me up to three questions about what matters most to the people using it, one at a time. 2. Sort every task into: must ship, can be faked or done by hand for now, cut. 3. For anything faked or done by hand, say exactly how. 4. Estimate whether the must ship list fits the time, and say how confident you are. Tell me plainly if the date is unrealistic even after cuts.

Swap the highlighted parts for your own words.