Operator OS
All pages

Conventions

Working conventions

What this layer is: eleven habits that decide how Claude behaves while it works: how it asks, how fast it runs, what it may never do alone. Why it matters: these are the difference between a helpful assistant and an expensive surprise. Each one came from a real incident.

Core (everyone)

All are ON in templates/claude-md/user.CLAUDE.md. Each entry: what, why, how it is enforced. Turning off is explained at the end.

1. Grill before doing

  • What: before any non-trivial task, Claude asks the open decisions in rounds and starts only after you confirm.
  • Why: Claude kept choosing look and direction by itself, then you redid the work.
  • Enforced by: CLAUDE.md line + a grilling skill + a feedback note.

2. Ask with popups

  • What: decisions go through the AskUserQuestion tool: 2-4 options, Recommended first, up to 4 questions.
  • Why: five long text questions got skipped. Popups were answered in seconds.
  • Enforced by: CLAUDE.md line + memory note. It says it overrides skills that ask in text.

3. Parallel by default

  • What: independent work starts in the same turn. Cap of 2-3 heavy builds at once.
  • Why: most dead time is sequential waiting. But 30 dev servers at once ran the Mac out of RAM.
  • Enforced by: CLAUDE.md line, plus an optional reaper job that kills dev servers of dead sessions.

4. Model tiering

  • What: subagents use haiku for mechanical work, sonnet by default, opus only for judgment.
  • Why: 11 opus agents at once hit the usage limit and cost about 3 hours.
  • Enforced by: CLAUDE.md line + memory note. Claude must pass model on each subagent.

5. Worktree per coding session

  • What: coding happens in a separate git worktree on its own branch.
  • Why: two sessions shared a checkout. One committed the other's unfinished edits.
  • Enforced by: CLAUDE.md line + worktree skill. Advanced: a hook can block edits on the main checkout.

6. Always commit and push

  • What: finished and verified work is committed and pushed without asking.
  • Why: "want me to push?" cost a round trip every time, and unpushed work gets lost.
  • Enforced by: machine and user CLAUDE.md. The safety rails in 8 are the exception.
  • What: docs and reports are published and delivered as a link, with source links inside, not local paths.
  • Why: the user read on a phone and could not open a .md in a repo. Local paths also meant nothing to recipients.
  • Enforced by: CLAUDE.md line + memory note naming the default target.

8. Safety rails

  • What: external email is draft only. Money changes are proposals; new ads start PAUSED. A human presses Submit and Send. Chat messages are shown before sending. No screen capture while you are using the Mac.
  • Why: an agent replied to a customer with an unapproved refund. A screenshot caught a private chat window. Ad budgets are real money.
  • Enforced by: CLAUDE.md + memory notes. Strongest: tool allowlists. Daily ad jobs only get read tools.

9. MCP, then CLI, then browser

  • What: try connectors first, then CLI or API, browser control last.
  • Why: driving your real browser pops tabs, opens the wrong profile, and cannot run unattended.
  • Enforced by: CLAUDE.md line + memory note.

10. Plain, short writing

  • What: say what was done, what is left, what is needed.
  • Why: long formal answers hid the one useful line.
  • Enforced by: CLAUDE.md line. Can also be set as an output style.

11. Memory habit

  • What: corrections become notes with a Why and a How to apply. The index is checked before project work.
  • Why: rules that stay in chat are forgotten. See docs/02-memory.md.
  • Enforced by: CLAUDE.md line.

How to turn one off

Delete its numbered section in ~/.claude/CLAUDE.md (and the matching memory note). Say "just do it" to skip one for a single task. Chat overrides last one session only. Exceptions: do not delete 8 (safety rails); narrow it instead (who, what, how often). Convention 7 needs {{DEFAULT_PUBLISH_TARGET}} set first. Convention 6 also has a line in the machine file. Note in memory why you removed one so you do not re-add it.

Advanced (developers)

CLAUDE.md is advice. Move hard rules into settings so the harness enforces them:

  • Permissions. settings.json permissions.deny for dangerous commands (git push --force, rm -rf). allow for safe repeated ones, so you are not prompted.
  • Hooks. A PreToolUse hook can block a command or tool call: edits on the main checkout, any send-mail tool, any ad-activation call. A SessionStart hook can print where the last session stopped.
  • Agent frontmatter. Subagent definitions can pin model, so tiering does not depend on Claude remembering.
  • Parallel limits. Put heavy work (build, preflight) behind a lock file or pgrep check so two sessions do not run it at once.
  • Allowlists for jobs. Unattended jobs get a tool whitelist of read-only tools. Never give a scheduled job the write tools.
  • Scheduled jobs on macOS. Keep scripts and logs outside ~/Documents, and wait for network before the first call (see lessons below).

Lessons from real use

Most incidents are in the entries above. Extra ones:

  • Ads and money: a rule "optimize budget by the sheet" would have raised spend without approval. Now new ads are created PAUSED and changes are proposals. This beats the "do not ask" rule (6) on purpose.
  • Silent background jobs: a backup and a sync died for 5 weeks (exit 78) because logs sat in ~/Documents. A laptop on battery with the lid closed also woke with no network. Now: scripts and logs in a hidden home folder, wait for network first, and a daily "last exit" check per job.
  • RAM: 30 dev servers and type-checks at once stalled the Mac. Cap heavy work at 2-3 and reap servers of dead sessions.
  • Deliverables: a long plan sat as a markdown file for days because the reader was on a phone.