CLAUDE.md best practices: a starter template for reliable agents

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

1. Project context — one paragraph, no marketing.
2. How we work — the non-negotiables (tests before merge, no direct pushes to main, etc.).
3. Where things live — the directory map, in code-block form.
4. Do / don''t — pairs of explicit examples.
5. 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.