# CLAUDE.md — Scale-Ready Spec > **Bitwise · v1** > Companion to: *3 Things Every Vibe-Coded App Needs to Actually Scale* > https://www.youtube.com/watch?v=bLq3Eohnn3c > > Drop this file at the root of your project before your first prompt. > Claude Code, Codex CLI, and Cursor read it automatically. > Lovable / Bolt / v0 users: paste everything below the `--- FOR THE AI ---` line into your first chat message. --- ## How to use this file (60 seconds) 1. Save this file as `CLAUDE.md` (capitalized exactly) in the empty folder where your project will live. 2. **Scroll to the bottom and fill in the Project Description block.** Don't skip this. It's the part that makes everything else work. 3. Open Claude Code (or your tool of choice) in that folder. 4. Start with: *"Read CLAUDE.md and tell me back in your own words what the rules are before we begin."* 5. If the AI's summary is wrong, the file didn't load. Fix that before doing anything else. You don't need to understand every technical detail below. The AI does. Your job is to fill in the project block, then audit the AI using the **Verify** line at the end of each section. --- ## --- FOR THE AI --- You are working with a non-coder. Read every rule below before any task in this project. If a request from me conflicts with a rule, surface the conflict before acting. The rules in this file override any default behavior. --- ### 1. Source Control — the safety net Git is non-optional. Without it, one bad change wipes the project. **At project start:** - If `.git` doesn't exist in the project root, run `git init` immediately. - Create a `.gitignore` containing at minimum: ``` node_modules/ dist/ build/ .env .env.* !.env.example *.log .DS_Store ``` - Make the initial commit: `git add . && git commit -m "Initial commit"`. **As we work:** - After every change I confirm works ("good," "yes," "ship it," "looks right"), run `git add . && git commit -m ""`. - Commit messages: imperative, present tense, under 70 characters. ("Add login form" — not "added login form.") - Never run `git reset --hard`, `git push --force`, or anything destructive without asking me first. - Before any large refactor, schema change, or dependency swap, ask: *"This is risky. Commit the current state as a checkpoint first?"* **Recovery commands I might ask you to run:** - "What's changed?" → `git status` - "Show me the last 10 commits." → `git log --oneline -10` - "Roll back to the last commit." → `git reset --hard HEAD` *(warn me before running)* - "Go back to the version where [feature] worked." → find the commit by message, then reset. **✅ Verify the AI did this:** Ask the AI to run `git log --oneline -5` and paste the output. If it errors with "not a git repository" — git wasn't set up. --- ### 2. Containerization — build once, run anywhere Every part of the app runs in a Docker container, defined in one `docker-compose.yml` at the project root. **At project start:** - Verify Docker and Docker Compose are installed: `docker --version && docker compose version`. - If they aren't, give me the install command for my OS — **don't run it without confirmation**: - macOS / Windows → Docker Desktop from docker.com - Linux → `curl -fsSL https://get.docker.com | sh` - Create `docker-compose.yml` at the project root **before** writing application code. **Service rules:** - Each component (frontend, backend, database, cache, queue, anything that runs as a process) is a separate `service` in `docker-compose.yml`. - Database data must live in a **named volume**, never inside the container itself. Otherwise data dies when the container restarts. - All secrets and config live in `.env` (gitignored) — never hardcoded. Provide a `.env.example` with dummy values that I can copy. - The full stack must run with one command: `docker compose up`. **Default service skeleton when in doubt:** - A `frontend` service exposing port 3000 - A `backend` service exposing port 4000 - A `db` service running PostgreSQL with a named volume for `/var/lib/postgresql/data` - Generate the actual YAML to fit the project — don't paste a template blindly. **✅ Verify the AI did this:** Ask the AI to show `docker-compose.yml` and run `docker compose config`. If `docker compose config` errors out, the file is broken. If there's no file at all, containerization didn't happen. --- ### 3. Sustainable Technologies — pickable by any human dev Use boring, popular, well-documented frameworks. Litmus test: any developer with 2+ years of experience should be able to read the codebase without surprise. **Default stack (use unless I say otherwise):** - **Frontend:** React + Vite + **TypeScript**. JavaScript is not allowed — every frontend source file must use `.ts` or `.tsx`. A `tsconfig.json` must exist at the frontend root with `"strict": true`. - **Backend:** Node.js + Express *or* Fastify. Pick one at project start and stick with it. - **Database:** PostgreSQL (in a Docker container, see Section 2). - **Package manager:** npm. - **Code formatting:** ESLint + Prettier with default config. **Things you will NOT do without explicit permission:** - Use plain JavaScript (`.js` / `.jsx`) anywhere in the frontend. TypeScript is non-negotiable. - Switch frameworks mid-project (React → Vue, Express → NestJS, etc.). - Add a state-management library (Redux, MobX, Zustand) unless I show you a real problem that needs one. - Roll our own authentication. If we need auth, we'll use Auth.js, Clerk, or Supabase Auth — *future Bitwise issue covers this in detail*. - Pick a "newer" or "trendier" alternative just because it exists. If you want to suggest one, explain why in one sentence and wait for my "yes." **One thing to set up before the first feature:** - A `README.md` with three sections: what the app does, how to run it locally (`docker compose up`), and where the env vars come from. **✅ Verify the AI did this:** Ask the AI to show `package.json` for both frontend and backend, plus the frontend's `tsconfig.json`. The frontend should list `react`, `vite`, and `typescript` as dependencies; `tsconfig.json` should have `"strict": true`. If the AI can't show real files, the stack wasn't actually built. --- ### How you should communicate with me - **Before editing files** for any non-trivial change, summarize what you're about to do in 2–3 sentences. Wait for my "go." - **After each change**, tell me how to verify it worked in plain English ("open localhost:3000, click Login, you should see a form"). Don't claim success until I confirm. - **If you don't know something, say so.** I prefer "I'm not sure" over a confident wrong answer. - **If you mock data, fake an API, leave a TODO, or skip a step, say so explicitly** in the same message. I want to know what's real and what's a placeholder. - **If the same error happens twice in a row, stop.** Don't keep trying variations. Tell me what the error is and ask what to do. --- ## --- FOR ME (the human) — fill in before your first prompt --- The AI treats this as the source of truth for the project. Be specific. The thinner this section is, the more the AI guesses. - **Project name:** `your-project-name` - **What it does in one sentence:** `e.g., "A personal CRM that auto-tags contacts from my Gmail."` - **Who uses it:** `e.g., "Just me." / "My team of 5." / "Public, expecting up to 10k users."` - **Where it runs in production:** `e.g., "Just my laptop." / "A $7/mo VPS." / "AWS, needs to autoscale."` - **Red lines (things I do NOT want changed):** `e.g., "Don't switch to TypeScript." / "No auth — local-only." / "Don't add a paid service without asking."` --- *This is Phase A: The Spec. Phase B (The Team — assigning Doer / Checker / Manager roles to the AI) and Phase C (The Loop — the feedback cycle) are covered in upcoming Bitwise issues.* *Found a bug, missing rule, or smarter default? Reply to the newsletter that brought you here.* *— Aron & Bálint · aaronbitwise.tech*