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 want.
This step is optional. If the folder is empty, Claude asks you questions in the chat when you run /start. The more you provide up front, 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 or text file) | The main thing. It 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 instead of guessing |
Sample data (any .json or .csv) | Shows Claude the shape of your data, for realistic mocks and tests |
| A design (a Claude Design or Figma export, wireframes, or an HTML mockup) | Gives Claude your screens, colours and wording. See Working From an Existing Design. |
| Brand or styling notes | Colour palettes, fonts, logo files or a tokens.css file: anything that defines the look and feel |
File names and folder structure don’t matter. Claude scans the whole folder.
Claude never changes the files in documentation/. They stay exactly as you supplied them.
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:
# 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 plan. You can add more detail, such as user stories, acceptance criteria or edge cases, but you don’t have to.
For help 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 documentation/. Claude uses it as the source of truth for endpoints, request and response shapes, and authentication, so the app calls your real API rather than invented endpoints.
See Providing an OpenAPI Spec.
If you have a design or a prototype
Section titled “If you have a design or a prototype”Put the design files in documentation/. There’s no separate import step. This includes the HTML from a prototype you’ve already built. If the files came as a .zip, unzip them first.
See Working From an Existing Design.
- Start small. A few paragraphs is plenty for a first feature. You can 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 saves a lot of back-and-forth when you connect to the real backend.
- Update the folder whenever you like. Add or change files, then ask Claude to re-read the folder.