CLAUDE.md for MVPs & Prototypes
Speed-first agent rules for pre-product-market-fit code.
A CLAUDE.md for MVP and prototype codebases where the goal is learning speed, not engineering perfection: what corners are explicitly OK to cut, the few things that still must never be cut, and rules that stop agents from gold-plating a throwaway.
The template
# CLAUDE.md
## Project
[Product] MVP — we are pre-product-market-fit. The goal is LEARNING SPEED. This file tells you which corners to cut and which never to cut.
## Commands
```bash
pnpm dev / pnpm build # [adjust to stack]
```
## Explicitly OK to cut (don't gold-plate)
- No test coverage requirements — test only genuinely tricky logic you'd otherwise re-debug
- Duplication is fine until the third copy — don't build abstractions for two call sites
- Skip loading states/edge-case polish on internal or low-traffic screens
- Hardcode configuration that has exactly one value today (mark with `// HARDCODED:`)
- One file getting long is fine; don't refactor working code for aesthetics
## NEVER cut (even in an MVP)
- **Security**: parameterized queries, hashed passwords, secrets in env vars, auth checks on every mutating endpoint. A breach kills the company faster than slow shipping
- **Payments/money paths**: idempotency and logging on anything touching billing
- **Data loss**: user-created content gets persisted transactionally — losing a user's work loses the user
- **Legal basics**: don't log or expose PII casually
## Decision rules
- Two ways to build it? Pick the one shippable today
- New dependency vs 30 lines of code: write the 30 lines
- "We might need X later" → we don't, until we do
- If a task balloons past its estimate, stop and surface the trade-off instead of pushing through
## Keep a debt ledger
When you knowingly cut a corner, append one line to DEBT.md: what, where, and the trigger for fixing it ("when we have >100 users", "before charging money"). This makes debt intentional instead of ambient.
## Verification
Definition of done: it works for the demo path, the NEVER-cut list holds, and any new debt is in DEBT.md.How to use
- 1Copy to your repo root; adjust the OK-to-cut list to your risk tolerance.
- 2The DEBT.md ledger is the load-bearing idea — it converts corner-cutting from vague guilt into managed decisions.
- 3Graduate to a stricter CLAUDE.md when you find product-market fit; the ledger tells you exactly what to pay down first.
Examples
Agent resisting gold-plating
Input
Agent asked to add a waitlist form, starts building a full email validation service with retries.
Output
With this file: agent ships the form with basic validation and a single INSERT, notes 'HARDCODED: single waitlist, no double-opt-in' in DEBT.md with trigger 'when sending actual emails' — 20 minutes instead of 3 hours.
Pro tips
- Review DEBT.md weekly — the entries that keep appearing are your real architecture roadmap.
Frequently asked questions
Isn't telling an agent to skip tests dangerous?+
The file doesn't skip correctness — it skips coverage ritual. The NEVER-cut list keeps the catastrophic categories (security, money, data loss) fully protected, which is where MVP corner-cutting actually kills companies.