# CLAUDE.md — project template

> I didn't invent this structure. I **lifted it** from the CLAUDE.md of a real project that made it
> through App Store review, removed the sensitive parts, and kept the structure. Scope table, single
> source of truth, document priority, definition of done: all exactly as used in practice.
>
> **How to use it:** save it as `CLAUDE.md` at the top of your project folder. Claude Code reads this
> file at the start of every session, so you stop re-explaining your project from scratch. It's like
> handing a new hire an onboarding doc on day one.
>
> Fill in the [brackets]. If you get stuck, see **Appendix A: filled-in example** at the bottom.
> To use it for running a shop or brand instead of code, see **Appendix B**.
>
> — Build Alone · buildalone.co · Pairs with step 7 of the 10-Step Launch Playbook.

---

## 0. Document priority

> Lesson from real projects: when there are several documents, the AI wobbles. Set a ranking.

This project's document ranking: **CLAUDE.md (this file) > PLAN.md > other docs > ideas from chat**

**For the AI:** if another document or an earlier conversation conflicts with this file, this file wins. To do something different from this file, first propose changing this file.

## 1. Project overview (one paragraph)

[One paragraph: who it's for, what it does, how it makes money.
A good example: "XX is a web app that lets independent shop owners make short brand videos from one phone.
No film crew, just a link and a few photos. Plans start at $29/month."]

**For the AI:** judge everything against this paragraph. When you suggest something outside it, say that it's outside it.

## 2. Scope table — now vs. later

> The most important section. AI will build anything you ask for,
> so if you don't write down what you *won't* do, you'll never launch.

### Build now (MVP — if it's not here, don't build it)

| Area | Scope |
|---|---|
| [e.g. Payments] | [e.g. One Stripe monthly plan only. No annual plan] |
| [e.g. Login] | [e.g. Email login only. No social login] |
| [e.g. Core feature] | [e.g. One video type. Three fixed templates] |

### Save for later (+ why)

| Deferred | Reason |
|---|---|
| [e.g. Annual billing] | [e.g. Meaningless before 10 users] |
| [e.g. Team features] | [e.g. Validate solo users first] |

**For the AI:** if I ask to build something from the "later" list, remind me of this table. To change scope, edit the table first.

## 3. Stack and file structure

Stack: [e.g. Next.js + Postgres (Neon) + Stripe + Vercel, with one line on why for each]

```
[Your project structure as a tree. e.g.
src/
├── app/          # pages and API routes
├── components/   # UI components: layout only, no logic
├── lib/          # business logic, DB, external APIs
└── constants.ts  # every constant (see section 4)
]
```

**For the AI:** new files follow this structure. If you need a folder that isn't in it, ask first.

## 4. Single source of truth — constants

> Rule from real projects: prices, limits and settings are defined **once, in one file**.
> Bugs start the moment those values get scattered across the code.

All constants live only in [e.g. `src/constants.ts`]:

```
[e.g.
Price: PRO_MONTHLY = $29
Limits: FREE_CREDITS = 3, MAX_UPLOAD_MB = 50
Policy: TRIAL_DAYS = 7
]
```

**For the AI:** never write these values directly into code (no hardcoding). Always import them from the constants file. When a new constant appears, add it to this section too.

## 5. Rules (non-negotiable)

> Only the non-negotiables. The shorter the list, the more it gets followed.

- User personal data (email, payment details) never goes into logs, error messages or any output
- Anything that costs money (API usage, running ads, signing up for paid services) gets an estimated cost reported before it runs
- Never edit the production database with direct queries. Always go through code or migrations
- Pricing, refund and legal wording is drafted only, and needs my confirmation
- [Add your own rules]

## 6. Error-handling principles

> Lesson from app review: apps that show users raw errors lose their trust.

- Every error a user sees is [e.g. one plain sentence like "Something went wrong. Please try again."]
- The real error details go to logs only. No stack traces or technical terms on user screens
- Every external call that can fail (payments, AI APIs, uploads) tells the user what to do next when it fails

## 7. Session routine

**Session start:** begin with "Summarize where we are against PLAN.md and what the next task is."

**Session end:** when the work is done, commit and update the progress in PLAN.md.

**For the AI:** before starting a long task, confirm this session's goal in one line.

## 8. Definition of done

> Not a feeling of "it's done". A checklist decides.
> This is the same approach used for a real App Store submission. Change the items to fit your product.

- [ ] New signup → core feature → result works end to end without breaking
- [ ] Both payment success and failure show the user a clear state
- [ ] Every screen has been checked on mobile
- [ ] All test data, seed users and debug leftovers are removed
- [ ] No API keys are hardcoded anywhere in the code
- [ ] [Add your own criteria]

---

## Appendix A — filled-in example

A condensed version filled in for a fictional product, "Plately" (restaurant menu photo → online menu page).

> **1. Overview:** Plately is a web app that turns a photo of a restaurant's printed menu into a
> QR-code online menu page. No designer, five minutes, $19/month.
>
> **2. Scope:** Now = photo upload → menu extraction → page generation → QR download, one Stripe monthly plan.
> Later = multilingual menus (until 3 users ask), reservation integration (after the menu is validated), POS integration (too big).
>
> **4. Constants:** `constants.ts` — PRICE_MONTHLY=$19, FREE_PAGES=1, MAX_PHOTO_MB=10.
>
> **7. DoD:** photo upload → printing the QR works on a phone without breaking / uploading the wrong photo (a receipt, say)
> gets a friendly error / test restaurant data deleted.

Fill the whole file at this density. A finished CLAUDE.md is usually around 100 lines.

## Appendix B — using it to run a business

If you're using it to run a shop or brand instead of code, change these sections:

- **Section 3 (structure)** → the list of tools you use (POS, booking system, Instagram account, Google Business Profile)
- **Section 4 (constants)** → your shop's fixed facts (hours, pricing policy, refund policy, address and contact)
- **Section 6 (errors)** → your customer-service tone (e.g. warm and polite, no excuses, at most one emoji)
- **Section 7 (routine)** → recurring work (weekly review-reply drafts, three content ideas a week, a monthly cost check)

The rest (priority, overview, scope, rules, definition of done) works as is.

---

*Free from Build Alone at buildalone.co.*