All posts

Planning

Your agent builds blind without two files

Two plain files give every new Claude session your rules and your spec, so the agent stops guessing what you want.

What to do

  1. Write a CLAUDE.md file

    Every session starts with no memory of the last one[1][2]. Claude reads CLAUDE.md at the start of every session, so it is where your project facts live[1].

  2. Put the build commands and rules in it

    Add your build commands, your conventions, the project layout and your "always do this" rules[1].

  3. Keep it under 200 lines

    Anthropic's docs give this limit for each CLAUDE.md file[1].

  4. Let Claude write the spec

    Tell it to interview you until it could write the spec, then to write it to SPEC.md[3][4].

  5. Pin down scope and done

    Make sure the spec says what is out of scope and how you will know it works[3][4].

  6. Build in a fresh session

    Start a new session to build from the spec, so it begins with a clean context and a written definition of done[3].

The prompt

Paste this into your coding agent before it writes any code.

The two-file prompt
Don't build anything yet.

First, write a CLAUDE.md file for this project.
Put in the build commands, the conventions, the project layout and the "always do this" rules.
Keep it under 200 lines.

Then interview me until you could write the spec.
Ask about every part I haven't pinned down:
1. The job the app does.
2. The people it is for.
3. The must-have features for the first version.
4. What stays out of scope.
5. How we can tell that it works.

When you have the answers, write the spec to SPEC.md and stop.

Use it at the start of a new project, before the agent writes any code. When SPEC.md exists, start a fresh session and tell the agent to build from it[3].

Did not fit in the video

The builder in the video calls the spec file PRD.md. That prompt asks for five things: what the app does, who it is for, the core features for the first version, what is out of scope, and how you will know it works[3][4]. Anthropic's docs call the same file SPEC.md[3][4].

In Anthropic's own example, Claude comes back with multiple-choice questions about the parts you have not pinned down, and what is out of scope is one of them[3][4]. So you do not have to know every answer before you start. The interview finds the gaps for you.

No source gives a number for how often an agent goes wrong without these files. The point is simpler: what you do not write down, the next session does not know[1].

Sources

  1. How Claude remembers your project (Claude Code docs)

    code.claude.com

  2. Effective harnesses for long-running agents (Anthropic Engineering)

    anthropic.com

  3. Best practices for Claude Code (Claude Code docs)

    code.claude.com

  4. 1,000 hours of vibecoding: everything I learned, start to finish (Murphmaxxing)

    murphmaxxing.com

Want the rest? Every post, by month and topic.

See all posts