A CLAUDE.md example for a frontend website repository

Claude Code reads the project CLAUDE.md at the start of every session. In a website repository, use it for what Claude cannot work out quickly from the code: the commands to run, the file that defines colours, the component to reuse for buttons, the exact label of the main action, and what to report after a review.

Anthropic's documentation asks for instructions specific enough to verify, such as “Use 2-space indentation” rather than “Format code properly”, and suggests keeping each CLAUDE.md under 200 lines. A design rule passes that test when someone can find a break in a file: a hex value in a component, a 14px paragraph, a second primary button. “Make it look modern” gives a reviewer nothing to find.

This file is for Wrenboard, a fictional scheduling tool for small dental clinics. Save it as CLAUDE.md at the repository root, then replace the product, paths, commands and labels with your own. It is 28 lines long. The last section asks for a fixed opening phrase in reviews, which lets you tell from the reply whether the file reached the session.

Rules that only matter when Claude edits components can live in .claude/rules/. The paths field makes Claude Code load the file when it reads, writes or edits a matching file, so sessions that never open src/components do not carry these rules. Save this one as .claude/rules/components.md.

An @ import does something different. An imported file loads together with the CLAUDE.md that imports it, so splitting a long CLAUDE.md into imports makes it easier to edit but does not reduce what Claude reads.

The test project holds the two files above, a tokens.css file, a Button component and a Hero component written to break six rules. The hero has a purple-to-pink gradient, hex colours, 14px body text, a main button labelled Get started free and a second primary button. Button.tsx has no focus style, which only the path-scoped rule mentions.

The request names the file and says nothing about the rules. If the reply cites them, they came from the project files.

On 5 November 2026, Claude Code 2.1.309 ran that request with claude -p and only the Read, Glob and Grep tools enabled. The command exited 0. The reply began “UI check:”, as CLAUDE.md asks, and listed all six breaks in Hero.tsx with their line numbers and the rule each one broke. For the button it quoted the label Get started free against the required Book a demo.

It also reported the missing focus style in Button.tsx and named .claude/rules/components.md as the source, so the path-scoped rule had loaded. As the file asks, it kept two findings apart because they need a browser: the paragraph's line height and whether a focus outline appears.

A second run on 6 November 2026, with personal settings excluded by --setting-sources project,local, again listed the six breaks in Hero.tsx and cited .claude/rules/components.md for the focus style. That run put the line height with the source findings, because nothing in src/ sets it.

These are two runs on one small fixture. They show that both sessions read and applied both files; they do not measure how often Claude follows each rule. Claude Code treats CLAUDE.md as context rather than enforced configuration, and its documentation recommends a PreToolUse hook for anything that must be blocked whatever Claude decides.

Claude Code 2.1.277 and later read AGENTS.md as project instructions, but only when there is no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in the working directory or above it. If you keep both files, put @AGENTS.md on its own line in CLAUDE.md. Claude Code then loads both and, according to its documentation, does not read AGENTS.md twice.

The AGENTS.md example on this blog gives Codex the same kind of frontend rules. If you prefer to keep colours, type and layout decisions in a separate DESIGN.md, the Claude Code guide shows how to import it.