Published: Reading time: 7 min read

CLAUDE.md for a Website: What to Put in It (With Our Real File)

Summarize with AI

Table of contents
  1. What is a CLAUDE.md file?
  2. Why does a marketing website need one?
  3. What should a website CLAUDE.md include?
  4. What does a real CLAUDE.md look like?
  5. What are the CLAUDE.md best practices?
  6. AGENTS.md vs CLAUDE.md: which one do you need?
  7. What can’t a CLAUDE.md do?
  8. How do you write one for your site?
  9. FAQs

A CLAUDE.md file is a Markdown file in your project that Claude Code reads at the start of every session, so the rules in it apply to every change without anyone repeating them. For a marketing website, it should hold what Claude can’t work out from the code: which design tokens and components to use, which URLs and SEO tags never change, and how to check a page before anyone sees it.

Below is what to put in one, using the real file Claude reads before it touches designme.agency, which we moved from Framer to Astro in October 2026. Our team changes the site by asking Claude, and this file keeps those changes on brand.

101
lines in the CLAUDE.md for designme.agency
Under 200
lines per file, Anthropic’s target
60,000+
open-source projects using AGENTS.md

What is a CLAUDE.md file?

Anthropic describes CLAUDE.md files as instructions you write to give Claude persistent context. You write them in plain text, Claude reads them at the start of every session, and you stop re-explaining the same things in chat. Where the file lives decides who it applies to:

  • Project: ./CLAUDE.md or ./.claude/CLAUDE.md, shared with your team through git. This is the one a website needs.
  • Local: CLAUDE.local.md next to it, for your own preferences, kept out of git.
  • User and organisation: ~/.claude/CLAUDE.md for you across every project, and a managed file IT sets for everyone.

Claude Code loads the files in your working directory and every directory above it at launch, and a subfolder’s CLAUDE.md once it works on a file there. Run /init and Claude drafts a starting file from your codebase, or suggests improvements if you already have one.

One thing to know before you write a line: Anthropic’s docs say Claude treats these files “as context, not enforced configuration”. There’s no guarantee it follows every line, especially vague or conflicting ones.

Why does a marketing website need one?

A website runs on rules that live in people’s heads. Your developer knows the card style, the corner radius and that a renamed URL needs a redirect. Claude doesn’t, unless someone writes it down, and when it guesses you get a new card style, a hard-coded colour or a renamed page with no redirect. That matters more when the people asking for changes aren’t developers. On our site, a request like “add a case study page” comes back as a pull request with a preview, and CLAUDE.md is what makes that page match the rest. The workflow around it is in how to let your team edit your website with Claude.

What should a website CLAUDE.md include?

Anthropic’s best-practices page gives a good test: only what Claude couldn’t work out from the code. That means how to confirm work, places where the code is misleading, decisions that aren’t in the repo, and anything you’ve had to correct twice. For a website, it comes down to six parts:

  1. Stack. The framework, where content and images live. A line or two.
  2. Design tokens. The semantic names to use and the raw values never to use.
  3. One component per job. Which primitive is a card, a list row, a chip, a big number.
  4. Rules that don’t bend. URLs, redirects, the title and meta tags every page keeps.
  5. Copy rules. Spelling, banned punctuation, how headings are phrased.
  6. How to check work. The build command, both themes, a phone width.

Leave out the tour of your folders. Anthropic lists describing your architecture and file layout as advice you can stop following, because Claude reads the repo itself. And the design rules need a system behind them to point at: we wrote up what that takes in design systems AI agents can build with.

What does a real CLAUDE.md look like?

The CLAUDE.md at the root of our site’s repository is 101 lines in 13 sections, from Stack and Design system to Motion and Cookie consent. Its opening line says the site is an Astro rebuild and that “Claude edits this repo directly.” Then it gets specific. Six rules, copied as they are:

- Use semantic tokens (`--color-text`, `--text-2xl`, `--space-6`) in components. Never hard-code a hex value, px font size or Framer value.
- Radius: nothing visible above 4px.
- Don't add new card, list or chip styles. Extend the primitive (a prop or variant), then add it to `/styleguide`.
- Never rename a slug without adding a 301 in `public/_redirects`.
- No em dashes anywhere in site copy.
- Suggestions go in the PR description, not the code.

What those lines have in common:

  • They name the thing. A token, a file path, a page. Anthropic makes the same point with “Use 2-space indentation” instead of “Format code properly”. A reviewer can check a page against --space-6, not against “keep spacing consistent”.
  • They say what to do instead. “Don’t add new card styles” alone leaves Claude stuck. The second half (extend the primitive, add it to the styleguide) gives it a way forward, and /styleguide shows every token in both themes for whoever reviews the change.
  • They point elsewhere for detail. The component inventory and the reasoning behind it live in docs/design-system.md, and CLAUDE.md links there.
  • Decisions carry a date. “No gradient glows behind heroes” names who made the call and when (the owner, 8 October 2026), so the next request doesn’t bring the glow back.

Our Stack section does break that advice a little: it says where insights, service pages and case studies live. We keep those lines because each carries a decision too, such as every case study being its own page with its own layout.

What are the CLAUDE.md best practices?

Size first. Anthropic’s target is under 200 lines per file, because longer files “consume more context and reduce adherence”. Splitting one into @path imports doesn’t reduce what Claude loads, since imported files load with the file that imports them. To stay short, move things out:

What Claude should know Where it goes Why there
A rule for every change: tokens, components, URLs CLAUDE.md Loads in every session
A rule for one part of the site, such as blog posts .claude/rules/ with a paths filter Loads only when Claude works on matching files
A step-by-step procedure, such as publishing a case study A skill Loads only when the task calls for it
Your own preferences CLAUDE.local.md, kept out of git Applies to you, not the team
Something that must never happen A hook, a deny rule or branch protection Enforced whatever the model decides
Long reasoning and full inventories A doc the file points to Keeps CLAUDE.md short

Three more habits from the same docs:

  • Add a line when Claude makes the same mistake twice, or when a code review catches something it should have known.
  • Skip the capitals. Anthropic says current models follow a plainly worded line, and piling on IMPORTANT or ALL CAPS mostly makes Claude over-apply the rule. If a line keeps getting missed, the file is too long or the rule belongs in a hook.
  • Check for conflicts. When two instructions contradict each other, Claude may pick one arbitrarily, so read the file and your rules files side by side every few months and delete what’s outdated.

AGENTS.md vs CLAUDE.md: which one do you need?

AGENTS.md is the open version of the same idea: a Markdown “README for agents” read by OpenAI’s Codex, Cursor, Gemini CLI, GitHub Copilot, Jules, VS Code and others. OpenAI released it in August 2025, and on 9 December 2025 it became a founding project of the Linux Foundation’s Agentic AI Foundation, alongside Anthropic’s Model Context Protocol and Block’s goose. The AGENTS.md site says more than 60,000 open-source projects use it.

CLAUDE.md AGENTS.md
Read by Claude Code Codex, Cursor, Gemini CLI, GitHub Copilot and more; Claude Code when there’s no CLAUDE.md
Maintained by Anthropic, as part of Claude Code The Agentic AI Foundation, under the Linux Foundation
Format Plain Markdown Plain Markdown, no required fields
Nested files A subfolder’s file loads when Claude works there The file closest to the edited file wins
Personal version CLAUDE.local.md Claude Code doesn’t read AGENTS.local.md

Claude Code can read either file, with one catch: by default it reads AGENTS.md only when there’s no CLAUDE.md or CLAUDE.local.md in your working directory or above it. If both exist, it reads CLAUDE.md only. So a personal CLAUDE.local.md stops Claude reading your team’s AGENTS.md for you, unless you set Project instructions to read both.

Which setup to pick:

  • Everyone uses Claude Code: one CLAUDE.md. That’s our site: the repo has a CLAUDE.md and no AGENTS.md, because Claude is the agent that edits it.
  • Your team mixes tools: keep the shared rules in AGENTS.md, and add a CLAUDE.md that starts with @AGENTS.md and holds any Claude-only lines below. Claude reads the imported file first, then the rest.
  • One file, no Claude-only lines: a symlink (ln -s AGENTS.md CLAUDE.md) works too, but Anthropic recommends the import if anyone on the team works on Windows.

What can’t a CLAUDE.md do?

It can’t enforce anything. Anthropic’s best-practices page splits instructions into the ones Claude decides on (your prompt, CLAUDE.md, skills) and the ones enforced every time (hooks, deny rules, managed settings, and branch protection with a person approving the merge). Claude follows a line in the file almost every time, and “almost” isn’t good enough for a production deploy.

So on our site, the rule that matters most (nothing reaches production without the owner’s explicit OK) doesn’t rely on CLAUDE.md. It’s in the deploy runbook, and production only updates after the owner says so in writing. If you want the full setup around the file, with the rules, a preview for every change and a person’s approval before anything goes live, our free guide Let your team edit your website with Claude walks through it in order.

How do you write one for your site?

Writing a CLAUDE.md for a website

  1. Draft it with /init

    Claude reads the repo and writes a starting file.

  2. Cut what Claude can read

    Folder tours and dependency lists go.

  3. Add the design rules

    Token names, one component per job, what never to create.

  4. Add what never changes

    URLs and redirects, page meta, copy rules.

  5. Add how to check work

    The build command, both themes, a phone width.

After that, the file grows a line at a time: when Claude repeats a mistake or a review catches something, write the rule down.

Keep keys, passwords and private URLs out of it. The file is committed to git, so everyone with the repo reads it, and so does every agent they run. Then read it the way Claude will: if a rule can’t be checked against a page (a token, a path, a number), rewrite it until it can.

Need more info?

Questions about CLAUDE.md files

Adrian

Can't find your answer?

Book a call and let's talk.

Or email us  hello@designme.agency

What is a CLAUDE.md file?

A Markdown file in your project that Claude Code reads at the start of every session. The project version sits at ./CLAUDE.md or ./.claude/CLAUDE.md and is shared with the team through git, so its rules apply to every change without anyone repeating them. Claude treats it as context, not enforced configuration.

What should a CLAUDE.md for a website include?

What Claude can't work out from the code: the stack in a line or two, the design tokens to use and the raw values never to use, which component fits each job, the rules that never bend such as URLs and redirects, copy rules, and how to check work. Leave out tours of the folders and dependency lists, because Claude reads the repo itself.

How long should a CLAUDE.md file be?

Anthropic's target is under 200 lines per file, because longer files consume more context and reduce adherence. Splitting it into imports doesn't reduce that cost. Move rules for one part of the site into .claude/rules/, procedures into skills and long reasoning into docs the file points to. The CLAUDE.md for designme.agency is 101 lines.

What is the difference between AGENTS.md and CLAUDE.md?

Both are Markdown instruction files for coding agents. CLAUDE.md is the file Claude Code reads. AGENTS.md is the open format read by Codex, Cursor, Gemini CLI, GitHub Copilot and other tools. OpenAI released it in August 2025, and it is now stewarded by the Agentic AI Foundation under the Linux Foundation.

Does Claude Code read AGENTS.md?

Yes, when there's no CLAUDE.md or CLAUDE.local.md in your working directory or above it. If both files exist, it reads CLAUDE.md only by default. To share one file across tools, start a CLAUDE.md with an @AGENTS.md import and add any Claude-only rules below it.

Does Claude always follow CLAUDE.md?

Not always. Anthropic's docs say there's no guarantee of strict compliance, especially for vague or conflicting instructions. Write rules concrete enough to check, and put anything that must never happen in a hook, a deny rule or branch protection, with a person approving before anything goes live.

You've reached the end, so now…

Tell us what you’re building.

We’ll help you map the right scope, team, timeline, and next steps.

Book a call