# CLAUDE.md skeleton

Claude Code reads a file called `CLAUDE.md` at the start of every session. Mine is the difference
between a session that knows how my company runs and one that starts from zero every time. This is
the skeleton, with my business details taken out. Fill in the brackets.

Keep it lean. It loads on every session, so push detail into linked files and keep this one to the
rules and the map.

---

```markdown
# <Company> operating instructions

## What this is
<One paragraph: the business, who runs it, what the AI is here to do.>

## Where things live
| Need | Where to look |
|---|---|
| Tasks and to-dos | <the task table or tool. The ONLY place tasks live.> |
| A project's state | `<projects>/<slug>/INDEX.md`, `TARGETS.md`, `PASSES/`, `CHANGELOG.md`, `GOTCHAS.md` |
| Credentials | <your password manager. Never in files, never on a command line.> |
| How we do X | `<skills folder>/<skill>/SKILL.md` |

## Start of a session
1. Read the rules file (the never-do list).
2. Load the project you're working on: its INDEX, TARGETS, the active pass, and GOTCHAS (read whole).
3. Claim the pass before changing anything, so two sessions don't work the same thing.

## While working
- A to-do that isn't part of this pass gets filed as a task right away. Don't switch to it.
- Write the changelog entry at the moment something changes, not at the end.
- If a skill covers the work, run it through the skill. Don't write a one-off script around it.

## End of a session
Run the wrap checklist: pass file, changelog, gotchas, new tasks filed, commit and push, release the
claim. End with a "Done:" line and a "Next:" line.

## Hard rules
- Never state how something behaves unless you just checked it. Otherwise say "unverified" and name
  the cheapest check.
- A build passing is not QA. Run the real thing and look at what it did.
- A different agent reviews anything that touches logic, data or money before it's called done.
- Stop and ask a human before: <sending to real people, publishing, spending money, deleting data you
  didn't create, anything you can't undo>.
- Before asking a human anything: is the answer already written down? Can a 2-minute check answer it?
  Only ask if it's really theirs to decide, and give a recommended answer.
- Every question to a human must make sense read cold, on a phone, hours later. No internal labels.

## Money
- Check the real price before estimating any cost. Try the free option first.
- Log every spend in the project's INDEX.
- Stop and ask above <$ amount> per project.
```

---

## What I learned putting mine together

- Rules that keep getting broken should become code (a check or a script), not a longer paragraph.
- Put the map in here and the detail in linked files. A 50-page CLAUDE.md gets skimmed.
- Date your rules. When one turns out to be wrong, fix it in place and say what changed.