Skip to main content

CLAUDE.md

CLAUDE.md is a different mechanism from the three custom commands. It isn't invoked by name; Claude Code reads it automatically at the start of every session in this repo, without anyone typing anything. Where a command is a set of steps run on request, CLAUDE.md is standing context: instructions that apply to the whole session, every time.

What it does​

CLAUDE.md currently encodes two rules, both specific to this repo.

Keep pipeline.md and llms.txt honest​

website/docs/pipeline.md makes factual claims about this site's own pipeline, including how many GitHub Actions workflows exist, how many custom Vale rules exist, and what each tool does. Those claims have to keep matching the repo, not just read plausibly. CLAUDE.md tells Claude Code to re-check and update pipeline.md in the same change whenever a workflow, Vale rule, or other pipeline component it describes gets added, removed, or renamed, and gives the exact commands to compare against:

ls .github/workflows/ | wc -l
ls .vale/styles/Diana/ | wc -l

This is the same rule that the pipeline test checks by machine, on a schedule. CLAUDE.md is the manual half: a standing instruction Claude Code follows while making a change, rather than a check that runs after one lands.

llms.txt states the same two counts, but the rule is different because the mechanism is different: llms.txt isn't hand-edited prose, it's rendered by scripts/generate-llms-txt.py from a template plus live repo state, so CLAUDE.md's instruction is to run the generator rather than rewrite the file by hand, and to add a plain-English description to scripts/pipeline-facts.json in the same change whenever a Vale rule is added or removed — the generator refuses to run otherwise. The rule also covers merge conflicts, since a scheduled workflow commits a regenerated llms.txt to main: resolve the source files, rerun the generator, and stage what it produces, rather than hand-merging two stale renderings into a file that matches neither. This rule came directly out of an incident where llms.txt drifted silently for about six weeks; see "A baseline is not a fact" for the full story.

This rule stays scoped to these two files on purpose. Any pair discovered later goes into the coupling map instead of a third CLAUDE.md rule, so this file doesn't grow by one section per pair.

Keep Doc Detective test pages consistent​

Pages under website/src/pages/doc-detective/ each document one Doc Detective test and share a structure: a heading matching the page's title, a "Why this matters" section, a "Latest result" section with the relevant status badge, a "How the test works" section with numbered steps, and a "Run the test manually" section with the exact commands to run it locally. CLAUDE.md tells Claude Code to read an existing sibling page before adding a new one and match its heading order rather than inventing a new shape, and to say why in the prose if a page genuinely needs to deviate rather than silently dropping a section its siblings have.

Why CLAUDE.md instead of AGENTS.md​

AGENTS.md is an open, tool-agnostic convention that Copilot, Codex, Cursor, and several other AI coding tools read natively. Claude Code doesn't read it; Claude Code reads CLAUDE.md. This repo uses CLAUDE.md rather than AGENTS.md (or a setup that supports both) for a specific, local reason: there's exactly one contributor to this repo, and that contributor works through Claude Code by choice. Cross-tool portability isn't buying anything here, because there's no second tool in the picture.

That reasoning is specific to this repo, not a general recommendation. A project with contributors spread across different coding agents would get real value from AGENTS.md, since it's the file more of those tools already read. A project that wants both could keep AGENTS.md as the source of truth and have CLAUDE.md import it, or symlink one to the other, instead of maintaining two versions of the same instructions by hand.

See also​