A starter CLAUDE.md

# CLAUDE.md — Working in [PROJECT NAME]

[One or two sentences: what this app is, what it does, who it's for.]

The person who owns this project is not an engineer and relies on Claude for all changes. Optimize every change for their ability to understand, verify, and ship it — not for cleverness.

## Coding guidelines

These override default behavior. Follow them exactly.

### Readability first (CRITICAL)

- Reading the code should make what it does obvious. A reader should be able to follow what happens without reconstructing it from clever tricks.
- Prefer clear, small pieces: functions that take inputs and return outputs, composed together. Keep side effects (files, network calls, database writes) at the edges, not woven through the logic.
- Comments are minimal. Write code that doesn't need them. A comment should explain *why* — a non-obvious decision, a workaround, a safety guard — never *what* the next line does. If you're tempted to comment what, rename the thing or split it into a function instead.
- DRY matters, but readability beats DRY. Don't merge two things into one abstraction just to remove duplication if the result is harder to follow. Two clear copies can beat one confusing helper.

### Separation of concerns — policy vs. mechanism

- Mechanism = how something is done. The actual work — reading a file, calling an API, transforming data — should be plain functions that don't know about requests or UI.
- Policy = what's allowed and when. Routing, validation, permission checks, and "which action runs for this input" are policy. Policy calls mechanism — never the reverse.
- Keep the layers apart: input → validation → mechanism → output. A handler should validate, call one mechanism function, and return the result. Business logic doesn't belong inside the request handler itself.

### Keep it simple, not clever

- Single responsibility: one function, one job.
- Adding a feature should mean adding a function and a route/entry, not editing a long if/else ladder. Prefer a lookup table or dispatch over a growing chain of conditions.
- Reach for the abstraction the feature actually needs — no more. When you find the same pattern a third time, extract it. Don't build for hypothetical future needs.

### Naming (CRITICAL — be consistent)

- Same concept, same name, everywhere — across the backend, the frontend, and the labels the user sees. If the code calls it `trash`, the button isn't labeled "Delete."
- Use consistent casing conventions for the language you're in. Verbs for actions, nouns for data.
- A user-facing label and the function behind it should describe the same outcome.

### Scope discipline

- Build exactly what was asked. Don't add settings, options, or "while I'm here" features that weren't requested. Smaller, correct, shippable beats large and speculative.
- If a request needs extra work to be safe or correct, say so and ask — don't silently expand scope.

### Security

- Treat every piece of user input as untrusted. Validate it before acting on it, and never build a command or query by pasting user input directly into it.
- Don't make network calls, log data, or send analytics anywhere the user hasn't agreed to. If privacy or "runs locally" is part of what you're promising users, never quietly break that promise.
- Keep secrets (API keys, tokens, passwords) out of code that ships to users or gets pushed to a public repo. Use environment variables or a secrets manager.

### Logging

- Keep it minimal. No verbose debug logging in shipped code.
- Surface real errors to the user as clean messages. Don't leak stack traces, file paths, or internals to the UI.

### Documentation

- Keep docs simple and clear, written for a non-engineer owner and for the next person picking this up.
- Say it plainly. No filler, no marketing language.
- State what something does and how to use it. Cut anything that doesn't help the reader act. If a doc drifts from the code, fix the doc.

## Working process

- Do a small piece of work, show it running, then move to the next piece. Don't disappear into a big change you can't verify.
- Work on a copy or a branch, not directly on the version that's live. Confirm it works, then merge or replace.
- Keep a running changelog — a plain list of what changed and when. It's your memory of the project and the fastest way to explain to someone else (or future-you) what happened.
- Prefer undoing a bad change with a new commit over rewriting history. Keep the trail intact.

## Repository map

[Fill in as the project grows — where the main logic lives, where the UI lives, where config/secrets are handled, any build or deploy scripts.]