Writing Effective CLAUDE.md & Agent Rules

CLAUDE.md is the briefing an AI coding agent reads at the start of every session in a repository: the commands, conventions, and constraints a new team member would need. A good one makes every agent session faster and more consistent; a bloated or vague one is ignored or misread. This guide is mainly for leads and maintainers who own a repository's rules.

Step 1: Know How the Files Are Loaded

Location	When it's read	Use it for
`CLAUDE.md` at the repository root	At the start of every session in the repository.	Team rules for the whole project. Committed.
`CLAUDE.md` in a subfolder	When the agent works with files in that folder.	Rules for one area, for example `src/Billing/CLAUDE.md`.
`~/.claude/CLAUDE.md`	Every session, in every project.	Personal preferences. Never team rules.

A CLAUDE.md can pull in other files with an @ reference on its own line, such as @ARCHITECTURE.md. Use this to reuse existing documents instead of copying them. If other AI tools in the team read AGENTS.md, keep the shared rules there and import it with @AGENTS.md.

Step 2: Put Each Rule in the Right Place

Belongs in	Content
`CLAUDE.md`	How to work here: build, test, and lint commands; branch and PR workflow; coding conventions that differ from the defaults; hard constraints; known gotchas.
`ARCHITECTURE.md`	How the system is designed: scope, components, invariants. Imported or referenced from `CLAUDE.md`.
The issue	What to do this time: goal, context, acceptance criteria. See Writing Issues for Agentic AI.
`.claude/settings.json`	What the agent is allowed to do: permission rules (Step 5).
Nowhere	Secrets, credentials, customer data, or internal URLs that grant access. `CLAUDE.md` is committed and sent to the model.

Step 3: Write Rules an Agent Will Follow

Be short. The whole file is loaded into every session and competes with the task for attention. Aim for a screen or two. If it grows past that, move area-specific rules into subfolder files.
Be specific and checkable. "Run dotnet test before every commit" can be followed; "make sure the code is good" can't.
Give exact commands, copy-pasteable, with any required flags.
Explain non-obvious rules in a few words. "Never call GetComponent in Update() (causes GC stutter on Switch)" is followed more reliably than a bare rule, and lets the agent apply the reason to similar cases.
Save emphasis for what matters. Marking one or two rules IMPORTANT or MUST works; marking everything does nothing.
Write what to do, not only what to avoid. Pair each "never" with the right alternative.
Don't duplicate. Link to ARCHITECTURE.md or the README rather than restating them; duplicated rules drift apart.

Vague:

- Write clean code and follow best practices.
- Be careful with the database.
- Test your changes.

Actionable:

- Every repository method takes a TenantId and filters by it. Never
  query a tenant-owned table without it (cross-tenant data leak).
- Schema changes need an EF Core migration: `dotnet ef migrations add <Name>`.
  Never edit an existing migration.
- Before committing, run `dotnet build` and `dotnet test`; both must pass.

Step 4: Start from a Template

Every studio CLAUDE.md shares the same workflow core (shown in Claude Code & GitHub CLI Setup, Step 6), plus a section specific to the repository type. Run /init for a first draft, then edit it against these examples:

Unity game:

## Unity project rules
- Unity version: 6000.0.23f1. Do not upgrade packages or the editor.
- Never edit .unity, .prefab, or .asset files by hand; describe the
  needed editor change in the PR instead.
- Always create or move assets together with their .meta files.
- No allocations in Update/FixedUpdate: cache components in Awake,
  no LINQ or string concatenation in per-frame code.
- Gameplay code lives in Assets/_Project/Scripts/<System>/. Each system
  has an assembly definition; keep references one-directional.
- Tests: Unity Test Framework, EditMode tests in Assets/_Project/Tests/.

Multi-tenant SaaS service:

## Service rules
- Build: `dotnet build` · Test: `dotnet test` · Format: `dotnet format`
- IMPORTANT: every query on tenant-owned data filters by TenantId via
  the repository layer. Never query DbContext directly from controllers.
- Business rules live in src/Domain; controllers only map HTTP to
  application services.
- Schema changes: add an EF Core migration; never edit existing ones.
- Never log request bodies, emails, or payment details.
- Use the test data builders in tests/Builders; never real customer data.

Static website:

## Site rules
- Read ARCHITECTURE.md before changing structure or styles.
- Pure static HTML/CSS/JS: no build tools, frameworks, or npm packages.
- No inline styles or <style> blocks; all CSS in /assets/css using the
  variables in variables.css.
- Pages must work opened directly from file:// (relative paths only).
- Add every new indexable page to sitemap.xml.

Step 5: Back Rules with Permissions and Enforcement

CLAUDE.md is guidance: the agent follows it almost always, but not with certainty. Anything that must never happen needs a hard control as well:

Layer	Strength	Example
`CLAUDE.md`	Guidance	"Branch from Dev; open PRs against Dev."
Permission rules in `.claude/settings.json`	Enforced by Claude Code	`deny` reading `.env` files; `ask` before `git push`.
Hooks in `.claude/settings.json`	Enforced by your own scripts	Run the formatter after every edit, or block a command that matches a pattern.
GitHub branch protection	Enforced by GitHub	No direct pushes to `Dev`, `QA`, or `main`; required reviews and checks.

A permission example is in Claude Code & GitHub CLI Setup. Branch protection is the guardrail that holds even if every other layer fails; see Repository Standards.

Step 6: Maintain the Rules Like Code

Change it through pull requests, reviewed by the repository's maintainers, like any other file.
Turn repeated mistakes into rules. When reviewers correct the same thing twice in AI-generated pull requests (see Reviewing AI-Generated Code), add one line that prevents it.
Prune. Delete rules that no longer apply, and rules the agent follows anyway without being told.
Test changes in a fresh session. Start a new session, give a small representative task, and check the new rule is followed.
Keep it in step with reality. When a build command, folder, or workflow changes, update CLAUDE.md in the same pull request.

Writing Effective CLAUDE.md & Agent Rules

1 Step 1: Know How the Files Are Loaded

2 Step 2: Put Each Rule in the Right Place

3 Step 3: Write Rules an Agent Will Follow