AgentsMD CheckerCheck your files
The instruction-file sanity check

Make CLAUDE.md and AGENTS.md agree.

Compare, clean, and sync your coding-agent instructions before stale rules waste another session—or ship the wrong command.

✓ Runs locally✓ No signup✓ Nothing uploaded
01 / CHECK

Two files in. One source of truth out.

Your files stay in this browser
AGENTS.md10 lines
Plain MarkdownLocal only
CLAUDE.md7 lines
Plain MarkdownLocal only
Source of truth
Instruction health
29/ 100
Similarity0%
Shared rules0
Review queue

4 findings

Live analysis

The two files have materially drifted

Only 0% of unique instruction lines match. Pick one source of truth before editing either file again.

Conflicting package-manager commands

AGENTS.md mentions pnpm; CLAUDE.md mentions npm. An agent can install a second lockfile or run the wrong scripts.

Potential positive/negative rule conflict

Compare “- Do not push directly to main.” with “- Push directly to main after the task.”. Resolve the intended behavior manually.

CLAUDE.md does not import AGENTS.md

The official Claude Code pattern is @AGENTS.md plus only the Claude-specific overlay below it.

Only in AGENTS.md6
  • +- Use pnpm install.
  • +- Start the app with pnpm dev.
  • +- Run pnpm test and pnpm lint before finishing.
  • +- Add tests for behavior changes.
  • +- Never commit secrets or .env files.
  • +- Do not push directly to main.
Only in CLAUDE.md4
  • −- Use npm install.
  • −- Start the app with npm run dev.
  • −- Run npm test before finishing.
  • −- Push directly to main after the task.
02 / FIX

A clean cross-tool setup

We keep shared instructions in AGENTS.md and turn CLAUDE.md into a small, reviewable overlay. Review the result before replacing files.

AGENTS.md
# Project instructions

## Setup
- Use pnpm install.
- Start the app with pnpm dev.

## Quality gates
- Run pnpm test and pnpm lint before finishing.
- Add tests for behavior changes.

## Boundaries
- Never commit secrets or .env files.
- Do not push directly to main.
CLAUDE.md
@AGENTS.md

## Claude Code

<!-- Keep only Claude-specific instructions below this line. -->
Import — recommended

Cross-platform and leaves room for Claude-only rules.

# Cross-platform source of truth
printf '@AGENTS.md\n' > CLAUDE.md
Symlink — identical files

Best when both tools must read exactly the same content.

# macOS / Linux — preserve the old file first
mv CLAUDE.md CLAUDE.md.backup
ln -s AGENTS.md CLAUDE.md
03 / DECIDE

CLAUDE.md vs AGENTS.md, without the folklore.

They are both Markdown instruction files. The practical difference is who discovers them, how they compose, and how easily duplicated rules drift.

DecisionAGENTS.mdCLAUDE.md
Best roleCross-tool source of truthClaude-specific overlay
FormatPlain MarkdownPlain Markdown + @ imports
Project scopeRoot and nested filesRoot, local, and nested files
Team workflowCommit shared rulesImport shared rules; add exceptions
Main riskContext bloatDuplication and contradictory overlays
01

One shared contract

Put build commands, architecture, testing, safety, and delivery rules in one canonical AGENTS.md.

02

Thin tool overlays

Keep tool-specific preferences out of the common file. Import the contract, then add the smallest necessary exception.

03

Enforce real boundaries

Markdown guides behavior. Use permissions, hooks, tests, and branch protection for controls that cannot be optional.

04 / GO DEEPER

Your files can agree and still be wrong.

The free checker compares what you paste. A full repository audit checks whether referenced paths, commands, nested rules, security boundaries, and definitions of done still match the codebase.

  • All agent instruction files and nested scopes
  • Broken file, directory, and command references
  • Conflicting rules and unnecessary context
  • A repaired AGENTS.md and CLAUDE.md setup
  • A concise handoff report for your team
Founding repository audit
$49

One repository · human-reviewed · delivered as a clear change plan.

Request an audit No repository access is requested until scope is agreed.
05 / SCALE

Free now. Continuous checks next.

Browser checker

$0

Compare two files, find drift, and download a cleaner setup.

Use it now
GitHub Monitor · beta

$9/mo

PR checks for changed rules, broken references, and instruction drift.

Join the beta
Team policy · planned

$49/mo

Shared baselines, multiple repositories, history, and team alerts.

Talk to us
06 / FAQ

Questions before you change the files.

Should I use CLAUDE.md or AGENTS.md?

Use AGENTS.md for shared, tool-agnostic project instructions. Keep CLAUDE.md as a small Claude-specific overlay that imports AGENTS.md.

Can CLAUDE.md import AGENTS.md?

Yes. Put @AGENTS.md in CLAUDE.md, then add only Claude-specific instructions below it. Claude Code documents this as the cross-tool setup.

Is an import better than a symlink?

An import is the safest cross-platform default and allows Claude-specific additions. A symlink is useful when both files must remain byte-for-byte identical.

Does AgentsMD Checker upload my files?

No. The free checker runs entirely in your browser. Your instruction files are not sent to a server or stored by this site.

Can this prove that an AI agent will follow every rule?

No. Instruction files guide model behavior; they are not enforcement. Use permissions, hooks, tests, and branch protection for rules that must be guaranteed.

Private by architecture.

File comparison, checks, and downloads run in your browser. We do not receive or store the contents of files used in the free checker.

Privacy question ↗