Preparing Your documentation/ Folder

Claude reads everything in the documentation/ folder before proposing anything. The more useful material you put there, the closer the first plan will be to what you actually want.

This step is optional. If the folder is empty, Claude will ask you questions in chat when you run /start. But the more you provide upfront, the less you'll need to answer in conversation.

What to Include

What	Why it helps
A feature description (any .md file or plain text)	The main thing — tells Claude what you want built and who it's for
An OpenAPI spec (.yaml or .json)	Locks in the real endpoints your backend exposes, so Claude uses your actual API shape instead of guessing
Sample data (any .json or .csv)	Helps Claude understand the shape of your data and write realistic tests
Brand or styling notes	Colour palette, fonts, logo files — anything that defines the look and feel
Wireframes	Reference for layout and screen flow, in a wireframes/ subfolder

File names and folder structure don't matter. Claude scans the whole folder automatically.

What a Good Feature Description Looks Like

You don't need formal documentation or technical language. A plain-language description is enough. Here's an example:

# User Profile Page

A page where signed-in users can view and edit their profile.

## What users should be able to do

- View their name, email, and profile picture
- See when their account was created
- Edit their name and profile picture inline (no separate edit page)
- Get a confirmation message after saving changes

## Things to keep in mind

- Changing email address should require re-verification
- Use a card layout
- Accessible from the main navigation menu

That's enough for Claude to produce a useful project brief. You can be more detailed if you like — user stories, acceptance criteria, edge cases — but you don't have to be.

For guidance on writing requirements that produce good results, see Writing Requirements That Work.

If You Have a Backend

Put your OpenAPI spec in the documentation/ folder (any name ending .yaml or .json will be detected). Claude uses it as the source of truth for endpoints, request and response shapes, and authentication — so the generated code calls your real API rather than invented endpoints.

See Providing an OpenAPI Spec for more detail.

If You Have a Prototype

If you've already built a signed-off prototype, run /start and pick the "I have a prototype repo to import" option. Claude will ask for the path to your prototype and import the relevant files automatically.

Tips

• Start small. A few paragraphs is plenty for a first feature. You can always refine as you go.

• Be specific where it matters. "Users can filter results by date range" is more useful than "Users can search".

• Include an API spec if you have one. It prevents a lot of back-and-forth when connecting to the real backend later.

• You can always update it. If you want Claude to re-read the folder after adding something, just ask it to.