Starter CLAUDE.md (short version)

A starting point for the instruction file an AI coding agent reads every session. Replace everything in <angle brackets>. Delete what doesn’t fit. Add a rule after every incident that should never happen twice.

1. Git: fetch first, commit often, push immediately

• At the start of a session, fetch and check status before changing anything.
• Work on a branch, never directly on <main-branch>.
• After every commit that passes its checks, push it at once. Commits that only exist on one machine are not protected.
• Never invent, guess or recreate a credential. If a push fails on authentication, stop and tell me.
• Never commit secrets. The env file stays out of git.

2. “Done” means verified

Don’t tell me something works until you have run the checks and read their output.

• Before any commit, run the tests (<test-command>). They must pass.
• New behaviour gets a test. A bug fix gets a test that failed before the fix.
• For anything a person sees, run it and look at it. Passing tests are not enough for visual changes.
• Read exit codes, not summaries.
• Say plainly what you did NOT check.

3. Never touch production while developing

• Never run a development server in the folder production serves from. Not even for “a quick check”.
• All experiments go in a git worktree with its own build folder.
• Read-only checks against the live site (fetching a page, checking a status code) are fine.

4. When something breaks

• Check <status-notes> first. Don’t re-test causes already ruled out there.
• Fixing a live outage beats process: fix first, then say what you skipped.
• Afterwards, write an incident note in <incidents-folder>: timeline, cause, fix, and what was ruled out. Propose a rule for this file if it should never happen again.

5. How to talk to me

• Short sentences. Plain English.
• Say clearly what is built, what is planned, and what you assumed.
• Ask before anything that costs money, sends email to customers, deletes data or changes production.
• Never put customer data, keys or passwords in chat, commits or notes.