Skip to content
How it learnsFrom coding sessions, reviews, Slack and docs.Only what fitsEach session gets the few rules its task needs.Pull request reviewEvery PR checked against your team’s rules.Keep it trueA gate, conflicts, disputes and stale rules, handled.HandoffsCarry the work to another session or a teammate.SecurityWhat it sends, what it changes and how to leave.
Engineering teamsOne agent or several: what one person learns, every session uses.PR review onlyInstall the GitHub App. Nothing on anyone’s machine.Teams that mix agentsClaude Code, Cursor, Codex and Copilot, the same rules.On your ownYour corrections follow you across repos, machines and agents.Book a call30 minutes with Roei, if you want a hand. Never required.
DocsPricingSign in
Connect your agents →
For teamsOn your ownPR review onlyHow it learnsOnly what fitsPull request reviewKeep it trueSecurityDocsPricingSign inConnect your agents →
Home/Blog

Blog

AGENTS.md, Cursor rules and Copilot instructions

  • AGENTS.md vs CLAUDE.md
  • Sync rules across repos
  • Why Codex ignores it
  • Keep rule files in sync
  • 3,905 files checked
  • Why Copilot ignores it
  • Cursor Team Rules
  • Cursor rules
  • copilot-instructions.md
  • Claude Code and AGENTS.md
  • AGENTS.md research

CLAUDE.md and context engineering

  • Why Claude ignores it
  • Test a CLAUDE.md rule
  • One CLAUDE.md for all projects
  • Context engineering, Claude 5
  • CLAUDE.md length
  • Which rules got used
  • Context rot, stale rules
  • Growing CLAUDE.md
  • Claude Code best practices
  • Karpathy CLAUDE.md
  • Committing CLAUDE.md

Built-in agent memory

  • Agent memory compared
  • Claude Code auto memory
  • GitHub Copilot Memory
  • Make Claude Code remember
  • Claude Tag vs Claude Code
  • Codex memories
  • Cursor memories
  • Memory or documentation?

Team knowledge and shared conventions

  • Claude Code team memory
  • Who owns CLAUDE.md
  • Claude Code second brain
  • Shared memory across agents
  • Stop repeated mistakes
  • Hand off between agents
  • Company brain
  • Slack decisions
  • Memory poisoning
  • Karpathy's LLM wiki
  • ADRs for agents

Skills, hooks and permissions

  • Rules vs skills
  • Claude Code hooks
  • Codex skills
  • Auto mode
  • CLAUDE.md vs skills vs hooks
  • Claude Code skills

AI code review and PR guardrails

  • PR review against AGENTS.md
  • Review comments to rules

Memory tools and alternatives

  • Best company brain tools
  • Unblocked alternatives
  • claude-mem alternatives
  • Supermemory alternatives
  • Mem0 alternatives
  • claude-mem
  • Best MCP memory servers
  • Supermemory Company Brain alternatives

Blog

How do I test if Claude Code follows a CLAUDE.md rule?

Published November 18, 2026

Run the same task several times with claude -p, once on a checkout with the rule and once without it, and score every run with a script. One run proves nothing, because Anthropic's docs say there is “no guarantee of strict compliance.” Check that the file loads first, and leave out --bare, which skips CLAUDE.md.

That is the short answer. This note gives the script, says how to read the count, and covers the same check for Codex. Claude Code facts are from Anthropic's docs, read on 18 November 2026. Why rules get skipped in the first place is in why Claude ignores CLAUDE.md; this note is about proving whether a fix worked.

Step 1: check the rule loads at all

A rule that never reaches the session fails every run, and no rewording fixes that. In a session, run /context all and look under Memory files. Two kinds of file do not show there at launch:

  • A CLAUDE.md in a subdirectory. It loads once Claude reads, writes or edits a file in that directory, and the terminal prints a Loaded line with its path. The memory docs suggest testing a new one by creating it from your shell, then asking Claude to read a file in that directory.
  • A path-scoped rule. A file in .claude/rules/ with paths: loads when Claude reads, writes or edits a matching file.

For a scripted check, an InstructionsLoaded hook logs which files loaded, when and why. If the task you plan to test never touches the files a scoped rule covers, the test measures nothing.

Step 2: pick a task that tempts the break

A test only tells you something if the easy path breaks the rule. “Log with src/lib/log.ts, never console.log” is a good subject: adding a retry to a webhook handler is a task where a quick console.log is the obvious move. Pick a rule you can score from the diff alone, without reading it yourself:

RuleScore it with
Never console.log; use the loggergit diff has no added console.log line
Every new file in src/ gets a test beside itEach added src/*.ts has a matching *.test.ts
Use pnpm, never npmNo package-lock.json in the diff
Retry on 5xx onlyA unit test that sends a 404 and expects one call

A rule you can only score by reading, such as “keep functions small”, is a sign the rule is too vague to follow either. Anthropic's guidance is to write instructions “concrete enough to verify.”

Step 3: run it headless, with and without the rule

The headless docs say a claude -p run discovers and loads CLAUDE.md, hooks, skills and settings “as an interactive session would.” That is what you want here. Do not add --bare: it skips auto memory and CLAUDE.md, so every run would be the without-rule run. And since a -p run starts in Manual mode on recent versions (2.1.302 and later), where an edit that needs approval is denied, pass --permission-mode acceptEdits so Claude can write files.

#!/bin/sh
# test-rule.sh REF [RUNS]
# Runs one task RUNS times on a clean checkout of REF and counts the
# runs whose diff keeps the rule. Run it once on a ref with the rule
# and once on a ref without it.
REF=${1:-HEAD}
RUNS=${2:-10}
TASK="Add a retry with backoff to the Stripe webhook handler in src/payments/webhooks.ts"
kept=0
for i in $(seq 1 "$RUNS"); do
  dir="/tmp/rule-test-$i"
  git worktree add -q --detach "$dir" "$REF"
  ( cd "$dir" && claude -p "$TASK" \
      --permission-mode acceptEdits \
      --output-format json > "$dir.json" )
  # the rule under test: "Log with src/lib/log.ts, never console.log"
  git -C "$dir" add -A
  if ! git -C "$dir" diff --cached | grep -q '^+.*console\.log'; then
    kept=$((kept + 1))
  fi
  git worktree remove --force "$dir"
done
echo "$REF: $kept of $RUNS runs kept the rule"
jq -s 'map(.total_cost_usd) | add' /tmp/rule-test-*.json

Make two refs: your branch with the rule, and a throwaway branch with that one line deleted. Then run ./test-rule.sh with-rule and ./test-rule.sh without-rule. Each run starts in a fresh worktree, so no run sees another's edits. With --output-format json the result includes total_cost_usd, and the last line adds it up. It is a client-side estimate, so treat it as a guide to the bill, not the bill.

Your own ~/.claude/CLAUDE.md and ~/.claude/rules/ load in every run too. If one of them already says the same thing, the without-rule side is not really without it.

How to read the count

With the ruleWithout itWhat it means
10 of 1010 of 10Claude does this anyway. The line costs context on every turn; consider deleting it
9 or 10 of 10Well belowThe rule works. Keep it
About the same as withoutBelow 10The rule loads and changes little. Rewrite it concretely, then rerun
Still misses after a rewriteAnyIf it must hold every time, it belongs in a hook

Ten runs a side separates “almost always” from “about half the time.” It does not separate 90 from 95 percent, so do not read small differences as wins. Run it again after a model update, since the same line can land differently on a new model.

The last row is Anthropic's own line. The best practices page says that if you keep adding emphasis to a CLAUDE.md line and Claude still misses it, “that's a sign the line belongs in a hook.” A PreToolUse hook that exits with code 2 blocks the call whatever the model decides. Examples are in Claude Code hooks.

What /doctor prompt-audit checks, and what it does not

Claude Code ships a review of the files themselves: /doctor prompt-audit looks for instructions written for older models, references to files or commands that do not exist, and files that contradict each other. Nothing changes until you ask it to apply the edits. It is a good first pass before a test, because a contradiction can make a rule look ignored. It reads the text, though, not what happened in a session, so it cannot tell you whether a rule changes behaviour. Only runs can.

The same test for Codex and AGENTS.md

Codex documents its own load check. From the repo, run codex --ask-for-approval never "Summarize the current instructions." and it should echo your global and project guidance in precedence order (AGENTS.md guide). If a file is missing, check the 32 KiB project_doc_max_bytes limit first. The loop above works with codex exec "$TASK" in place of the claude -p line, with whatever sandbox setting lets it write in your setup. More on what goes wrong in why Codex ignores AGENTS.md.

What a test like this cannot tell you

  • It tests one task. A rule that holds on the webhook task may still slip in a long session. A study of 1,650 Claude Code sessions found compliance falling as the agent wrote more code in one session (arXiv:2605.10039).
  • It tests the rules you thought to test. Most files have dozens of lines, and nobody scripts a check for each.
  • It runs on your machine. A teammate's home files differ from yours, so their runs may not match.

Where Harbor fits. Harbor does not run this test for you. What it adds is the signal for which rule to test: across the team's real Claude Code, Codex, Cursor and Copilot sessions, it counts per rule how often the rule was served to an agent and how often an answer cited it. A rule that is served on most sessions and rarely cited is the first one to put through the script above. Read the cited count as an upper bound: a cite is evidence a rule was used, not proof it was followed. How the counting works is in measure, and the one-machine version is served vs cited.

Questions

How do I test if Claude Code follows my CLAUDE.md?

Run the same task several times with claude -p on a checkout with the rule and on one without it, and score each run from its diff with a script. Ten runs a side separates a rule that almost always holds from one that holds about half the time. Check the file loads first with /context all.

Does claude -p read CLAUDE.md?

Yes. Anthropic's headless docs say a claude -p run loads CLAUDE.md, hooks, skills and settings as an interactive session would. Adding --bare skips CLAUDE.md, auto memory, hooks, skills, plugins and MCP servers, so do not use it when testing a rule.

What should I do if a CLAUDE.md rule fails the test?

Rewrite it so it can be checked, scope it to the paths it is about, and run the test again. If it still misses and it must hold every time, move it to a PreToolUse hook or a deny rule, which Claude Code applies whatever the model decides.

Does /doctor prompt-audit test my rules?

It reviews the text: instructions written for older models, references to files or commands that do not exist, and files that contradict each other. It does not run tasks, so it cannot tell you whether a rule changes what Claude does.

How do I check which instructions Codex loaded?

OpenAI's AGENTS.md guide gives a prompt for it: run codex --ask-for-approval never "Summarize the current instructions." from the repo. Codex should echo the global and project guidance in precedence order.

More on CLAUDE.md and context engineering

  • Why does Claude ignore my CLAUDE.md?
  • How do I use the same CLAUDE.md in all my projects?
  • Context engineering for Claude 5: what changes for teams
  • How long should CLAUDE.md be? Under 200 lines (median 81)

See which rules each agent was served and cited →

Your team’s rules, in every agent, checked on every PR.

Harbor is shared memory for your team’s Claude Code, Cursor, Codex and Copilot. Free for you and one teammate. No card. No end date.

Start free →

Product

  • How it learns
  • Only what fits
  • Pull request review
  • Keep it true
  • Handoffs
  • The result
  • Security
  • For coding agents
  • Pricing

Developers

  • Docs
  • Quickstart
  • Install
  • CLI
  • MCP server
  • Served and cited
  • Rule-file checker
  • Blog

Guides

  • Why Claude ignores CLAUDE.md
  • AGENTS.md vs CLAUDE.md
  • Share Claude Code memory with a team
  • Why Codex ignores AGENTS.md
  • Why Cursor ignores rules
  • Copilot instructions vs AGENTS.md
  • Shared memory across agents
  • Copilot Memory and Dreaming

Compare

  • All comparisons
  • vs Mem0
  • vs Zep
  • vs Unblocked
  • vs ByteRover
  • vs Cognee
  • vs Hindsight
  • vs OpenViking
  • vs Supermemory
  • vs Glen
  • vs MemPalace
  • vs Sentra
  • vs Trail-code

Company

  • Questions
  • Contact
  • X
  • LinkedIn
  • Privacy Policy
  • Terms of Service
  • Data Processing Agreement
  • Refund Policy
© 2026 HarborConnect your agents