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
Real scarcity beats fake urgency
A countdown timer that resets every time you reload is a lie your customer can see. A cap you actually enforce is a promise you keep. Founding-member pricing only works when the scarcity is real — and real scarcity is the one growth lever a tiny shop can pull without spending a dollar.
The metric that quietly broke is the outage you'll never see coming
A product going down is loud. The failure that actually costs you is the quiet one: the product keeps working while the number that watches it dies. Here is how a healthy product goes dark on your dashboard — and the habits that catch it.
The checkout you never tested is the feature you never shipped
A page that works and a page that earns are two different facts, and only one is visible from your side of the screen. A ten-minute, end-to-end audit for the payment failures that hide from status checks and quietly burn your ad budget.