Chapter 3. Planning and Specs — Getting Interviewed and Writing SPEC.md
Required Read this to follow this stage.One-line summary: When you are not yet sure what to build, do not try to figure it all out alone. Have Claude interview you. When the interview is done, Claude writes the result into SPEC.md (a specification). A spec is not "how to build it." It is a promise of "what it should be." This promise becomes your standard for building, checking, and reviewing in Chapters 4 to 6.
This chapter is based on the official Claude Code and GitHub docs, plus the spec-kit and OpenSpec repository descriptions, checked on November 1, 2026. You learned how to ask specifically when delegating work in Claude Code Chapter 5. This chapter expands that skill to the "before building" stage.
Why Start with Planning
As you saw in Chapter 1, a common reason AI builds something different from what you had in mind is that it is missing information it cannot get just from reading the repository.[1] That information is only in your head. It includes things like who will use it, what is inconvenient, and what you will not do.
GitHub's beginner tutorial also says to write down what you want to build and track your progress before writing code.[2]
The more specific you are, the fewer rounds of fixes you will need. The official docs say to name the file, describe the symptom, and say what "done" looks like right from the start.[3]
| Weak example | Better example |
|---|---|
| Make a page that shows to-dos | A page that collects the to-do tables from meeting notes and shows them by owner and due date. When it's done, all 5 to-dos from the notes should be visible |
Source: Examples from this guide (tips from official docs)[3:1]
Quick check
According to official docs, what is a common reason AI builds something different from what you had in mind?
Getting Interviewed and Writing SPEC.md
It is okay if you do not know exactly what you want yet. The official docs say you do not have to work it all out before writing a prompt. Instead, ask Claude to interview you.[4] Put in plain words, the example from the docs looks like this:
I want to build something like this, but I haven't thought it through deeply yet. Interview me until you have enough to write a spec, and when we're done, write it to SPEC.md.
Then Claude asks back with multiple-choice questions (questions where you pick from options) about the parts you have not decided yet.[5] For example, a question like "Should I group to-dos by person in charge or by deadline?" that you only need to pick an answer for. The actual questions vary each time, so pick one of the options or answer in your own words.
For the to-do board, your request would look like this:
I want to make a web page that collects and shows the to-do tables from the meeting notes created by the Stage 3 organizer tool. I haven't thought it through deeply yet. Interview me until you have enough to write a spec, and when we're done, write it to SPEC.md.Once SPEC.md is created, have Claude build from that file in a new session. This is so you start with a clean context and a written "definition of done."[6] It keeps the long back-and-forth conversation from the interview from mixing into the build step.
After building, you check the result against SPEC.md. We will come back to this in Chapter 6 on review.
Quick check
What do the official docs recommend when you are still unsure about what to build?
What a Good Spec Looks Like
In a spec, you write down behavior that is visible from the outside. This means you only write what someone looking at the screen can notice. For the to-do board's SPEC.md, lines like these belong in it:
| Good line | Weak line |
|---|---|
| Every single to-do from the meeting notes is visible | Reads the table with JavaScript |
| Past-due to-dos are marked differently | Looks pretty |
| Only roles are shown instead of personal names | Built with clean code |
Source: Examples from this guide
The lines on the left can be checked with a yes or no. In Chapter 5, these exact lines become your verification checklist.
The lines on the right are about how to build it (the tech) or a vague feeling. The docs for the spec tools in the next section say the same thing. The OpenSpec docs call a spec a "behavior contract, not an implementation plan." They say implementation details that do not change externally visible behavior usually do not belong in the spec.[7] spec-kit also says to focus on the what and why during the spec stage, not the tech, and leave technology choices for the next planning stage.[8]
Quick check
Which line is a good fit for a to-do board SPEC.md?
Spec-Driven Development Tools
A way of developing that puts the spec at the center is called Spec-Driven Development. You decide what to build and why first, and then turn that spec into a plan, tasks, and code.[9] Tools that help with this include spec-kit and OpenSpec.
This guide does not install either tool. You can put the exact same idea into practice with just the "interview → SPEC.md → new session" flow you learned above. In this section, you can just learn the names and move on.
Both tools put a human check in the middle.
- spec-kit (a tool made by GitHub): tells you to run spec → plan → task list → implementation one step at a time and review the result before moving on.[10]
- OpenSpec (a tool made by Fission-AI): has the AI write the documents and lets you review the plan before any code is written.[11]
This is the same idea as reading and approving SPEC.md in this guide's flow.
Learn more about the two tools (click to expand)
| Tool | Maker | What it does |
|---|---|---|
| spec-kit | GitHub | Guides you step by step from spec → plan → task list → implementation |
| OpenSpec | Fission-AI | Creates a folder with proposal, specs, design, and tasks for each change |
Source: Descriptions from each tool (excerpted)[12][11:1]
Installing them requires separate development tools. spec-kit requires Python 3.11+ and a tool called uv,[13] and OpenSpec requires a terminal installation (or Node.js 22.12+).[14] Python, uv, and Node.js are development tools used to run programs. You need none of them to follow this guide. Take a look at those tools later when you work on a larger project.
Quick check
How does this guide handle spec-kit and OpenSpec?
Try It Yourself
- Open the
todo-boardfolder you made in Chapter 2 in the Claude Code app. - Send the interview request above and answer Claude's questions. If you are not sure, you can say "Recommend one for me."
- Read the finished SPEC.md and ask for each line: "Can I check this with a yes or no?" If not, ask Claude to fix it.
- Check that no real names or contact info made it into SPEC.md (because it is a public repository).
- When you like it, save a record (commit).
Up next: In Chapter 4, you will get a plan based on SPEC.md in a new session, and build the first screen on a branch.
Summary
- A common reason AI builds the wrong thing is that information from your head was missing. Write it down before building.
- When you are not sure, have Claude interview you and get the result as SPEC.md.
- Once SPEC.md is ready, build in a new session. After building, check the result against SPEC.md.
- In a spec, write down externally visible behavior so it can be checked with a yes or no.
- spec-kit and OpenSpec are tools that support this same idea. This guide does not install them.
Glossary
| Term | One-line meaning |
|---|---|
| Spec | A written promise of what something should be (specification) |
| SPEC.md | The file where the spec is written |
| Spec-Driven Development | A way of building where you define the spec first and build from it |
| Definition of done | The standard for what counts as "finished" |
Finished this chapter?
Progress is saved only in this browser. See your progress on the full table of contents.
Next chapter: Chapter 4. Building
References (14)
Claude Code official docs, "Best practices for Claude Code". "Claude built something different from what you had in mind, or it has to rediscover the same fact at the start of every session. It's missing information it can't get from reading the repo." code.claude.com (checked on 2026-11-01) ↩︎
GitHub official docs, "Planning your work". "Before you write code, capture what you want to build and track your progress." docs.github.com (checked on 2026-11-01) ↩︎
Claude Code official docs, "Best practices for Claude Code". "If you name the file, describe the symptom, and say what "fixed" looks like up front, you usually save yourself a round of corrections later." code.claude.com (checked on 2026-11-01) ↩︎
Claude Code official docs, "Best practices for Claude Code". "When you don't know exactly what you want yet, you don't have to work it all out before you prompt. Ask Claude to interview you instead:" code.claude.com (checked on 2026-11-01) ↩︎
Claude Code official docs, "Best practices for Claude Code". "Claude comes back with multiple-choice questions about the parts you haven't pinned down: per-user versus per-key limits, what happens to requests over the limit, what's out of scope." code.claude.com (checked on 2026-11-01) ↩︎
Claude Code official docs, "Best practices for Claude Code". "Once
SPEC.mdexists, start a fresh session to build from it, so the build begins with a clean context and a written definition of done." code.claude.com (checked on 2026-11-01) ↩︎OpenSpec docs, "Concepts". "A spec is a behavior contract, not an implementation plan." / "If implementation can change without changing externally visible behavior, it likely does not belong in the spec." github.com (checked on 2026-11-01) ↩︎
spec-kit docs, "Spec-Driven Development Quickstart". "Creates the feature specification from a natural-language description. Focus on the what and why, not the tech stack." github.com (checked on 2026-11-01) ↩︎
spec-kit README. "Define what to build and why, then turn the specification into a plan, tasks, and working code." github.com (checked on 2026-11-01) ↩︎
spec-kit README. "Create a constitution once per project and repeat the remaining steps for each feature. Run these skills in your agent's chat, not your terminal, one at a time, reviewing each result before continuing." github.com (checked on 2026-11-01) ↩︎
OpenSpec README. "Stay organized — each change gets its own folder with proposal, specs, design, and tasks" / "Your AI writes these; you review the plan before any code is written." github.com (checked on 2026-11-01) ↩︎
spec-kit README. "Spec Kit is an open source toolkit that gives AI coding agents structured processes, reusable templates, and documented outcomes." github.com (checked on 2026-11-01) ↩︎
spec-kit README. "You need Python 3.11+, uv, and a supported AI coding agent on Linux, macOS, or Windows." github.com (checked on 2026-11-01) ↩︎
OpenSpec README. "Install OpenSpec. On macOS or Linux, in your terminal:" / "(needs Node.js 22.12.0 or higher)" github.com (checked on 2026-11-01) ↩︎