Writing Spec Files — Your Feature’s Memory for Claude

What is a spec file?

A spec file is a short markdown document that describes what you want built, before you ask Claude to write any code. It’s the second most important habit when working with Claude (after CLAUDE.md), and it’s the single biggest quality multiplier for non-trivial features.

Think of it like a mini-brief: durable, reviewable, and read by Claude as authoritative context every time you reference it.

Why bother? Why not just chat?

Most people skip specs and dump requirements into a chat message. That works for tiny tasks, but for real features it causes three problems:

• Claude makes assumptions you didn’t intend — without a clear scope, it fills gaps with guesses
• Context dies with the chat session — next week, you’re re-explaining the same thing
• You can’t review or share it — teammates have no idea what was asked

A spec file fixes all three. Half a page is usually enough — the point isn’t a formal PRD, it’s forcing yourself to think clearly before code starts.

What goes in a spec file

Four sections, kept short:

• Goal — one or two sentences on what this feature does and why
• User stories / scenarios — concrete examples of how it’s used
• Acceptance criteria — a checklist of what “done” looks like
• Out of scope — what this feature explicitly does NOT do (this prevents Claude from over-building, which is a common failure mode)

Where to put it

Use a per-feature folder structure under docs/:

docs/features/login/
├── spec.md           ← what to build
├── design.md         ← how to build it (added later)
├── decisions.md      ← why we chose X over Y
└── notes.md          ← session notes, open questions

This scales: by feature 20, a flat specs/ folder is unfindable. Grouping by feature keeps related files together, and you can sit docs/architecture/, docs/runbooks/, docs/adr/ alongside without anything getting tangled.

A note on filenames and paths

Neither the filename spec.md nor the path docs/features/<name>/ has any built-in significance to Claude — they’re just regular files and folders. Claude only reads them when you point to them. You could call the file requirements.md or brief.md and Claude would treat it identically.

What gives them significance is consistency and your CLAUDE.md. Add one line to your root CLAUDE.md:

Feature work lives in docs/features/<feature-name>/. Each folder contains spec.md (requirements), design.md (implementation plan), and decisions.md (key choices and rationale).

Now when you say “start work on the login feature,” Claude knows where to look without you spelling out paths every time. Pick a convention, document it, stick with it — consistency beats cleverness.

How to use a spec file with Claude

The pattern is spec first, plan second, code third. Instead of saying “build me a login feature with email and password,” you say:

“Read docs/features/login/spec.md and propose an implementation plan. Don’t write code yet.”

Claude reads the spec, asks clarifying questions, proposes a plan. You review the plan, push back, refine. Only then do you let it write code. This three-step rhythm catches misunderstandings before they become diffs you have to throw away.

Quick start

1. Create docs/features/<feature-name>/spec.md with the four sections above
2. Add the convention line to your root CLAUDE.md
3. Reference the spec by full path when prompting Claude
4. After implementation, add decisions.md to capture key choices for future you