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
Section titled “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
Section titled “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 menuThat’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
Section titled “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
Section titled “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.
- 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.