> ⚠️ HOW TO USE THIS TEMPLATE > > This file is full of instructions, explanations, and examples to help you understand what to write in each section. > **Before you give this file to Claude Code, delete all of it — every instruction, every example, every bracket — and replace it with YOUR project's information only.** > Claude should only read your answers, not the guidance written for you. > > A good rule of thumb: if it's in [brackets] or says "Example:" — delete it and write your own. --- # PROJECT NAME [Replace this with your project name. Keep it short and clear.] Example — delete this line: "FitTrack — Personal Workout Logger" or "BudgetBuddy — Household Expense Tracker" --- ## Vision [2–5 sentences. Answer all four of these: What are you building? Who is it for? What problem does it solve? What does success look like?] **The more specific you are here, the better Claude performs. Vague vision = generic build plan.** Examples by category: **Health / Fitness:** "A simple web app that lets users log their daily workouts and track progress over time. Built for people who go to the gym regularly but are tired of using Notes or spreadsheets. The app should show a history of past workouts and highlight personal bests. Success looks like a user logging a workout in under 60 seconds." **Finance / Budgeting:** "A personal budget tracker that lets users enter income and expenses by category and see where their money is going each month. Built for people living paycheck to paycheck who want visibility without paying for an app. Success looks like a user being able to see their monthly spending breakdown at a glance." **Business / Productivity:** "A simple client intake form for my freelance photography business. Clients fill out their name, event date, type of shoot, and budget. I receive the info by email. No client login needed. Success looks like replacing my current process of texting back and forth to collect basic info." **Community / Social:** "A local event board for our neighborhood Facebook group. Anyone can post an event with a title, date, location, and description. No login required to view. Only approved users can post. Success looks like replacing our pinned Facebook post with something that doesn't get buried." --- ## Tech Stack [List exactly what you're using. Be specific — don't leave this blank or Claude will make assumptions that may not match your skill level or project needs.] **What is a framework and should you use one?** A framework (like React, Vue, or Next.js) is a pre-built set of tools that handles common tasks automatically. They're powerful but add complexity — you need to know how to install packages, use a terminal, and debug errors in a build system. For most first projects built with Claude Code, you don't need one. - **Use Vanilla HTML/CSS/JS if:** you're building a simple site, a form, a dashboard, or anything that doesn't need to update in real time. Easiest to debug, no setup required, Claude handles it cleanly. - **Use React if:** your app has lots of moving parts that update without reloading the page — think live feeds, real-time dashboards, or complex UI with many interactive components. Only use it if you're comfortable with npm and a terminal. - **Use Next.js if:** you need server-side rendering, SEO on dynamic pages, or you're building something that scales beyond a simple static site. **When in doubt: start with Vanilla. You can always rebuild in React later if you outgrow it.** Recommended starter stack (copy and edit): - HTML5, CSS3, Vanilla JavaScript — no frameworks - Firebase Hosting — free static site deployment, SSL included - Firebase Authentication — free Google/email login (only if your app needs accounts) - Firebase Firestore — free database tier (only if your app needs to store data) - No build tools, no npm, no terminal required for the basic stack --- ## Target Users [Who specifically is this for? "Everyone" is not an answer. Describe the real person — their situation, their frustration, what they've already tried.] **Weak:** "People who want to track their finances." **Strong:** "People in their 20s–30s who are paycheck to paycheck, have tried budgeting apps but stopped because they felt too complex or invasive, and just want something simple they actually fill out. They're not looking for investment advice — they want to see where their money went last month." Examples: - "Small business owners who send invoices manually via email and want a simple form to collect client info before onboarding." - "Parents who want to track their kids' chore completion and reward points without a subscription app." - "Gym-goers who lift 3–4 times a week and want to log sets and reps without downloading yet another fitness app." - "Real estate agents who want a simple page that explains their services and collects lead contact info." --- ## Core Features [List only what the app MUST do to be useful. These become your build steps. Be specific enough that Claude knows when each one is done.] **The more features you list here, the longer and more complex the build. Start with the minimum. Add features in Phase 2 after Phase 1 works.** **Weak:** "Feature 1, Feature 2, Feature 3" **Strong examples by category:** **Workout Tracker:** - User can log a workout: exercise name, sets, reps, weight, date - User can view a list of past workouts sorted by date (newest first) - User can tap any past workout to see the full details - App highlights the highest weight ever logged for each exercise (personal best) **Budget Tracker:** - User can add an income or expense entry: amount, category, date, optional note - User can see all entries for the current month in a list - App shows a category breakdown (e.g. Food: $340, Rent: $1200, Gas: $80) - User can delete an entry if they made a mistake **Client Intake Form:** - Page displays a form: name, email, event type (dropdown), event date, estimated budget, message - On submit, form data is emailed to the business owner - User sees a "thank you" confirmation message after submitting - Form validates required fields before submitting (no empty name or email allowed) --- ## Out of Scope [Everything this app will NOT do. This is the most important section for keeping Claude focused. Be aggressive — list everything you're not building.] The more you list here, the less Claude will add things you didn't ask for. Examples: - No user accounts or login (Phase 1 is anonymous / public) - No payments or Stripe integration - No mobile app — web only - No admin dashboard - No email notifications - No social sharing features - No dark/light mode toggle - No multi-language support - No search functionality - No export to PDF or CSV - Phase 1 is read-only for visitors — no user-generated content --- ## Third Party Services [List any external tools, APIs, or platforms your app will connect to. Include why you're using each one — especially if it's free.] **Why use third-party services instead of building everything yourself?** Building your own database, authentication system, or email server from scratch takes months and requires deep backend knowledge. Third-party services give you that infrastructure instantly — often for free — so Claude can wire it up in one build step instead of ten. Common services and why to use them: **Firebase (Google) — Recommended starting point** - Firebase Hosting: Free. Deploys your static site with SSL in one command. No server to manage. - Firebase Authentication: Free up to 10,000 users/month. Handles Google login, email/password login — no security code to write yourself. - Firebase Firestore: Free up to 1GB storage / 50,000 reads per day. A real database without writing any backend code. - *Use Firebase if:* you want a complete free backend with zero startup cost and Claude knows it well. **Stripe — Payments** - Industry standard for accepting credit cards online. Free to set up — they take 2.9% + 30¢ per transaction. - *Use Stripe if:* your app needs to collect money. Don't build your own payment system. **EmailJS — Send emails without a backend** - Free up to 200 emails/month. Lets your contact form send real emails without a server. - *Use EmailJS if:* you have a contact or intake form and want submissions sent to your inbox. **Cloudinary — Image uploads and storage** - Free tier: 25GB storage, 25GB bandwidth/month. Handles image uploads, resizing, and delivery. - *Use Cloudinary if:* users need to upload photos (profile pictures, product images, etc.) **OpenAI API — AI features** - Pay per use. Lets your app call ChatGPT or generate text/images programmatically. - *Use OpenAI API if:* your app needs AI-generated content, summaries, or responses. Fill in which ones apply to your project: - [ ] Firebase Hosting (free — use for all projects) - [ ] Firebase Authentication (free — use if your app needs login) - [ ] Firebase Firestore (free tier — use if your app needs to save data) - [ ] Stripe (use if your app needs payments) - [ ] EmailJS (use if your app has a contact or intake form) - [ ] Cloudinary (use if your app needs image uploads) - [ ] OpenAI API (use if your app needs AI-generated content) - [ ] Other: _______________ --- ## File Structure [Describe your project folder layout so Claude knows where to put each file. The structure below works for most projects — modify as needed.] **Why does file structure matter?** Claude creates and edits files based on the structure you define here. If you don't define it, Claude will invent one — and it may not match what you expected. Defining it upfront means every file ends up exactly where it should be. **Standard structure for a simple web app (recommended starting point):** ``` /your-project-name/ │ ├── index.html ← Homepage / main entry point ├── index.css ← All global styles (shared across every page) ├── index.js ← All global JavaScript (shared across every page) │ ├── /pages/ ← All subpages live here │ ├── about.html ← About page │ ├── dashboard.html ← App dashboard (if applicable) │ ├── form.html ← Any form pages │ └── privacy.html ← Privacy policy (required if collecting any data) │ ├── /assets/ ← All images, icons, and downloadable files │ ├── logo.png │ └── example-file.pdf │ ├── /components/ ← Optional: reusable HTML snippets (nav, footer) │ ├── nav.html │ └── footer.html │ ├── CLAUDE.md ← This file — stays in the root always ├── firebase.json ← Firebase config (Claude generates this) └── .gitignore ← Tells Git what not to upload (Claude generates this) ``` **If your app has user-specific pages (dashboard, profile, settings):** ``` /pages/ ├── login.html ├── dashboard.html ├── profile.html └── settings.html ``` **If your app is a single-page tool (no subpages):** ``` /your-project-name/ ├── index.html ├── index.css ├── index.js ├── CLAUDE.md └── /assets/ ``` Tell Claude which structure applies to your project, or paste a modified version here. --- ## Build Steps [Leave this section blank. Claude will fill it in after reading this file. Do not write steps yourself — let Claude generate them based on your Vision, Tech Stack, and Core Features.] --- ## Testing Instructions [How will you know each step is working? Be specific. "It looks right" is not enough.] Examples: - Open index.html in a browser — the page loads without a blank white screen - Submit the form with a test name and email — a thank you message appears - Check the browser console (F12 → Console tab) — no red errors - Open the page on your phone — everything fits without horizontal scrolling - Log in with a test Google account — the dashboard loads with your name shown - Add a workout entry — it appears in the list immediately without refreshing --- ## Notes for Claude [Anything Claude needs to know upfront. The instructions below are recommended for every project — add your own at the bottom.] **Standard instructions (keep these):** - Build one step at a time — do not proceed to the next step without my confirmation - After each step, tell me: what was built, what files were changed, and how to test it - Do not modify completed steps unless there is a bug in that specific step - Mobile-first — every component must work on small screens before moving on - No frameworks unless explicitly listed in the Tech Stack section above - Do not add features that are not listed in Core Features - Keep all CSS in index.css — do not use inline styles or style tags in HTML files - Keep all JavaScript in index.js — do not write script tags inside HTML files **Add your own below:** - [Example: "Use a dark color scheme — dark background, light text"] - [Example: "Keep the design minimal — no gradients, no animations"] - [Example: "The app is for older users — use large font sizes and high contrast"] - [Example: "I'm using a Windows PC — all terminal commands should be for Windows"]