How to Use the CLAUDE.md Template
The CLAUDE.md is the most important document in the workflow. How you fill it out determines how well Claude performs. Here's a section-by-section walkthrough with examples and the mistakes that sink most builds.
What the CLAUDE.md Actually Does
Understanding why the template exists makes filling it out easier.
It replaces re-explaining
Without a CLAUDE.md, you re-explain your project at the start of every session. With it, Claude reads one file and has full context instantly. Every session starts informed.
It constrains Claude's scope
The Out of Scope section is what keeps Claude from building things you didn't ask for. Without it, Claude will often add features it thinks you probably want. You don't want that.
It produces better build plans
When Claude generates a build plan from a detailed CLAUDE.md, the plan is specific to your project. When it generates one from a vague description, the plan is generic and often misses key steps.
How to Fill Out Every Section
Walk through each section with examples of what good looks like — and what weak looks like.
Project Name
Just the name. Keep it short and clear. Claude will use this to refer to the project throughout the build.
Alchemy AI — AI Education Platform
Vision
2–5 sentences. What are you building and why? Who is it for? What problem does it solve? Be specific. "A web app" is not a vision. "A free AI education platform that shows non-developers how to build real apps using Claude" is a vision.
Being too vague. "A social app where people can share things" tells Claude nothing. The more specific your vision, the more on-target the build plan.
Tech Stack
List the exact technologies: languages, frameworks, databases, hosting, third-party APIs. If you don't know what to use, this is the section to work out with ChatGPT before coming to Claude Code. Don't leave it blank — Claude will make assumptions and they may not match what you want.
HTML5, CSS3, Vanilla JavaScript. Firebase Hosting. Firebase Authentication. No frameworks — keep it plain HTML/CSS/JS.
Target Users
Be specific. "Anyone" is not a target user. Describe the actual person: their skill level, what they're trying to do, what they're frustrated by right now. Claude uses this to make decisions about complexity, language, and feature scope.
Non-developers and early-stage builders who want to use AI to build apps but don't know where to start. They're in Facebook AI groups asking basic questions. They've seen demos but never shipped anything.
Core Features
List the things the app MUST do. Keep it to the essential features only — not the nice-to-haves. Each feature should be clear enough that Claude knows when it's done. "Users can log in" is clear. "Authentication" is vague.
Listing too many features. The more features in this section, the larger and more complex the build plan. Start with the minimum viable version. You can always add features in Phase 2.
Out of Scope
This is the most underused section and the most important one for keeping Claude focused. List everything the project will NOT do. This prevents Claude from adding features it thinks are obviously necessary. Be aggressive — the more things you explicitly exclude, the cleaner the build.
No user accounts. No database. No payments. No mobile app. No admin dashboard. No email notifications. Phase 1 is static HTML only.
Third-Party Services
List any external APIs, services, or platforms you'll be integrating. Include whether you have API keys set up and what accounts exist. This helps Claude write code that uses the right services without guessing.
Notes for Claude
Anything Claude needs to know that doesn't fit elsewhere. Code style preferences, things to avoid, constraints from previous sessions, decisions already made. This is also where you put behavioral instructions: "Do not modify completed steps unless there is a bug."
"Execute one step at a time and wait for confirmation before moving to the next." / "Do not add features that are not listed in Core Features." / "Mobile responsive is required on every page before moving to the next step."
What Sinks Most CLAUDE.md Files
These are the patterns that produce weak build plans and frustrating Claude sessions.
Vague Vision
The vision section is 1 sentence that says "a web app for people to do stuff." Claude will interpret this as broadly as possible and build whatever it thinks you mean.
No Out of Scope Section
Leaving Out of Scope blank means Claude will add features it thinks are obviously needed. User accounts. Admin panels. Email notifications. Things you didn't ask for and now have to undo.
Too Many Core Features
Listing 20 core features produces a 30-step build plan. The first few steps go well. By step 15, earlier decisions are breaking down and Claude is losing track of the full scope.
Undefined Tech Stack
Leaving Tech Stack blank or saying "whatever works best" means Claude picks the stack. It may pick React when you wanted vanilla JS. Or a framework you don't know how to debug.
Ready to Fill It Out?
Download the template, use this walkthrough as your guide, and bring the finished file to Claude Code. That's the whole setup.