The LoopCLAUDE.md best practices: a starter template for reliable agents
Most CLAUDE.md files are a wish list. Here is a battle-tested structure that agents actually respect — plus a copy-paste starter.
Why most CLAUDE.md files fail
They read like a manifesto. Grand principles, no enforcement, no examples. The agent skims and moves on.
A good CLAUDE.md is closer to an onboarding runbook for a new senior engineer: specific, opinionated, and full of concrete examples.
The five sections that matter
- Project context — one paragraph, no marketing.
- How we work — the non-negotiables (tests before merge, no direct pushes to main, etc.).
- Where things live — the directory map, in code-block form.
- Do / don''t — pairs of explicit examples.
- Escalation — what to do when unsure.
A starter template
# Project: <name>
## Context
One paragraph: what this repo does and who uses it.
## Rules
- Always run `bun test` before opening a PR.
- Never edit files under `src/generated/`.
- Never commit changes to `.env` or any file matching `**/secrets/*`.
- Prefer small PRs. Split anything over ~300 changed lines.
## Layout
- `src/routes/` — page routes
- `src/lib/` — shared utilities
- `src/server/` — server-only code, never imported from the client
## Do
- Add a test alongside every bug fix.
- Ask before adding a new dependency.
## Don''t
- Do not "helpfully" refactor unrelated files.
- Do not silently disable failing tests.
## When unsure
Stop and ask. Do not guess at intent.
Beyond the file
A CLAUDE.md is a good start, but it is still just text. Pair it with an enforcement layer — a harness — so the important rules become real. Loop-OS treats your CLAUDE.md as the source of truth and enforces it, so the words on the page match the behavior in the repo.
Frequently asked
Ready to try Loop-OS?
Governance & reliability harness for AI agents
Get Loop-OS →Keep reading
No second alert doesn't mean the first one got fixed
A monitoring discipline that escalates once and then stays quiet is doing its job -- but silence has two causes that look identical from the outside.
A setting left in test mode is still a decision
A test flag doesn't expire on its own -- a paused setting left untouched after the work that justified it stops isn't neutral, it's a decision nobody made on purpose.
Doubling the budget should feel as automatic as cutting it
Most operators who bother to write a kill rule never write its twin. They'll pre commit to cutting spend on a product after a bad enough stretch a number, a date, a threshold agreed to in advance, so the decision doesn't have to be re made in the emotional middle of a losing streak. Then a product actually starts working, and the same discipline disappears. Suddenly there's a meeting. Suddenly there's a reason to wait one more week and see if it holds. That hesitation isn't caution. It's the same bias that makes a bad number get explained away, just wearing the opposite outfit a good number getting second guessed instead of banked, scrutinized instead of acted on, while the thing that actually earned more spend sits underfunded during the exact window where funding it would matter most. A scale rule deserves the same mechanical treatment as a stop rule: the ratio that triggers it, the amount it releases, agreed to before anyone's ego or anxiety is in the room. Not because conviction doesn't matter, but because the moment a gate opens is precisely the moment you're least equipped to judge it cleanly too relieved to be rigorous, too invested in being right to ask whether the win is durable or lucky. Write the stop rule. Then write the rule that says go, and hold yourself to it exactly as hard.