AgentsMD CheckerBack to checker ↗
18-POINT CHECKLIST

Audit the repository, not just two files.

Use this checklist when adopting AGENTS.md, consolidating CLAUDE.md, or reviewing a repository used by several coding agents. Record evidence from the repository; a text comparison cannot complete the audit for you.

Published August 2, 2026 · Updated September 12, 2026 · AgentsMD Checker

Use it with your team

If you already have both files, compare them locally in the free checker first. Then work through the repository-level items from a clean checkout, record evidence beside each item, and review instruction changes like code.

Compare your files locally Download Markdown checklist

Three filled-in review examples

These are illustrative repository scenarios, not customer results. Each record separates the observation, decision, and remaining verification.

  • Import appears only in an example. Evidence: CLAUDE.md contains @AGENTS.md inside a fenced Markdown block. Fix: add the actual import outside the fence; keep the example intact. Verify: inspect the resulting text, then start a fresh Claude Code session and inspect Memory files. A browser check alone does not prove loading.
  • A package-manager warning may be harmless. Evidence: AGENTS.md says Run pnpm test; CLAUDE.md says Never use npm. Decision: these statements are compatible, not a conflict. Verify: check the package manager declared by the project and run the documented test in an isolated checkout. Do not change a lockfile just to satisfy a text warning.
  • Similar paths may govern different code. Evidence: one rule names src/API.ts, another src/api.ts, under different headings. Decision: preserve both until their existence and scope are checked. Verify: inspect tracked paths and the applicable nested instructions on the target filesystem; never delete one by lowercasing the text.

Runnable checker fixtures cover these text-level risks. For import and scope semantics, consult the official Claude Code memory documentation and AGENTS.md convention. Enforcement and command execution remain repository-level work.

1. Inventory and scope

  1. Find every instruction file

    Search the repository for AGENTS.md, CLAUDE.md, CLAUDE.local.md, tool-specific rule files, and nested copies. Record which directory each file governs.

  2. Map precedence

    Write down the order in which each coding agent discovers root, parent, nested, local, and user-level instructions. Do not assume two tools merge files the same way.

  3. Choose one shared contract

    Decide which committed file owns cross-tool rules. AGENTS.md is a practical default when several coding agents work in the same repository.

2. References and commands

  1. Resolve every path

    Verify that referenced source folders, architecture documents, fixtures, scripts, and generated directories still exist with the same casing.

  2. Run setup from a clean checkout

    Test the documented package-manager and setup commands without relying on an existing node_modules folder or uncommitted local configuration.

  3. Run every quality gate

    Execute the exact lint, typecheck, test, build, and formatting commands named in the instructions. Remove commands that no longer exist.

  4. Check command consistency

    Flag npm versus pnpm, duplicated flags, obsolete workspace filters, and different test commands across instruction files.

3. Conflicts and context quality

  1. Compare positive and negative rules

    Look for pairs such as always push versus never push, ask first versus proceed automatically, or edit generated files versus never edit them.

  2. Remove duplicated prose

    Keep a shared rule in one canonical place. Tool overlays should contain only real tool-specific exceptions.

  3. Replace vague preferences

    Turn 'write good tests' into an observable expectation: which tests, where they live, and when they must run.

  4. Trim stale context

    Delete historic explanations that do not change an agent's current decision. Link to durable documentation when background is still useful.

4. Safety and delivery

  1. Protect secrets and production

    State where secrets may live, what must never be committed, and which production systems require explicit approval.

  2. Separate guidance from enforcement

    Use repository permissions, CI, hooks, branch protection, and deployment controls for boundaries that cannot depend on model compliance.

  3. Define destructive actions

    Name operations that require confirmation, including data deletion, schema rollback, force push, broad file rewrites, and production changes.

  4. Define done

    List the evidence required before handoff: relevant tests, build status, changed behavior, migrations, documentation, and remaining external setup.

5. Multi-agent maintenance

  1. Test each supported agent

    Run the same small repository task with every supported coding agent and note which instructions it actually discovers.

  2. Keep overlays thin

    Import or reference the shared contract where the tool supports it, then add only the minimum agent-specific behavior.

  3. Assign an owner and review trigger

    Name who updates the instructions and require a review when commands, directories, CI, deployment, or supported agents change.

Fastest next step

Start with the free CLAUDE.md vs AGENTS.md checker. It suggests file-level differences to review in the browser. Use the full checklist for paths, commands, nested scope, and enforcement boundaries that a text comparison cannot verify.

Starting with Claude Code? Follow the exact AGENTS.md import setup, then return here for the repository-level review.