AGENTS.md in Claude Code: how to validate a migration

A team can maintain the same instruction in several files and still get incompatible changes. One copy requests package tests; another retains a retired command. When an agent changes environments, the failure looks like a coding mistake even though it started in configuration. AGENTS.md in Claude Code creates an opportunity to review that duplication, but first define a successful migration: the right instruction must reach the right context and produce a verifiable action.

Anthropic released Claude Code 2.1.277 on September 18, 2026. The release adds AGENTS.md loading when a project has no CLAUDE.md, with an option under Project instructions in /config; the announcement currently excludes Bedrock, Vertex, and Foundry. This is a compatibility release, not a productivity measurement. This article proposes five adoption criteria; it does not report a live Claude Code experiment or customer results.

The versioned README distinguishes CLAUDE.md-only loading, AGENTS.md fallback, and loading both. In fallback mode, .claude/CLAUDE.md and CLAUDE.local.md along the path to the working directory also matter. Nested files can be attached when reading a subdirectory. Checking only the visible repository root is therefore insufficient. The documentation also describes managed-only with caveats; it should not be interpreted as an absolute isolation guarantee.

The AGENTS.md convention provides a predictable place for working instructions and supports subproject-specific files. Our recommendation is to separate three adoption questions: where a rule is written, whether the environment actually loads it, and whether the agent follows it. Two tools recognizing a filename addresses part of the first question. The others require evidence in your repository, with your paths, configuration, and tasks.

Start with a reviewable inventory of instructions and entry points. Include tracked files, relevant local settings, agent launch directories, and references that import other documents. Assign an owner to each rule. An architecture instruction may belong to the platform team; a test command should be maintained alongside the package implementing it. Consolidation fails when it moves the text but loses its owner.

Flag contradictions before choosing which version to retain. If two documents prescribe different package managers, do not ask the model to arbitrate an infrastructure decision. Resolve it against the current scripts and lockfiles. Keep a short record of the canonical rule and its exceptions. The exit criterion is concrete: no important operating instruction should depend on remembering which copy someone updated last week.

Consider a hypothetical example: a monorepo contains an API and a mobile application. The shared guide requires reviewing the diff and reporting checks, while each package defines its test command. Copying every command into the root forces the agent to choose by intuition. A more maintainable structure places shared rules at the top and specific instructions beside the relevant code, with clear paths and applicability conditions.

Do not turn the shared guide into a manual for every tool. Separate repository conventions from execution-specific options and record who configures the latter. For each rule, ask whether it remains true after switching agents. If it depends on a particular integration, document that dependency. Shared context is useful when it reduces divergence; a huge file full of exceptions can relocate the problem without solving it.

In the hypothetical monorepo, prepare a trial branch and a disposable environment without production credentials. Introduce a small task with a known solution that requires running the correct package test. Repeat from the root and from the package, using representative team configurations. Compare the previous guide with the proposal while preserving the same initial commit. This reduces simultaneous variables when attributing a difference to the migration.

Record the agent version, access mode, starting directory, selected configuration, and available files. If the environment exposes loaded instructions, preserve that evidence alongside the outcome. Do not treat the model saying it read everything as sufficient proof. Retain the previous files until observed differences are explained and a simple rollback exists. Rolling out to one package first limits the scope of a configuration error.

Define observations before the trial: command executed, working directory, modified files, and test results. A task can succeed by chance while ignoring the procedure; it can also follow the procedure and uncover a genuine pre-existing failure. Score these dimensions separately. Add a case with a nested instruction and another with a deliberate conflict, clearly confined to the trial environment, to expose silent omissions and ambiguous decisions.

Repeat tasks to distinguish patterns from a lucky run. Review cost and time as local observations, without turning a small sample into a savings promise. A reasonable rollout condition is that all supported configurations load the expected rules and no unexplained regressions appear in the selected tasks. This validates that set of cases; it does not prove that every future instruction will be followed.

Version instructions and review them as part of any change that alters a command or repository boundary. Sensitive requirements should point to verifiable controls: if a directory must not change, inspect the diff automatically; if a test is mandatory, require it in CI. A document guides the agent, but it does not replace system permissions, branch protection, or product validation.

Repeat compatibility checks when the agent version, execution mode, or directory structure changes. Not every stylistic edit needs an evaluation campaign: prioritize changes affecting scope, precedence, or required actions. Keep instructions concise and executable, and remove obsolete references through human review. Periodic maintenance prevents the shared contract from fragmenting again into exceptions nobody checks.

Adopt a shared guide if duplication is your problem and you can identify compatible environments, owners, and representative tests. Keep an explicit transition if you depend on configurations not yet covered or cannot explain which rules your agents receive. Success is not measured by deleting a file: it means reducing maintenance while preserving traceability over how changes are produced.

For a CTO, the first useful deliverable is small: an inventory, a one-package trial, and a rollback criterion. If you need to turn that pilot into an engineering workflow tailored to your organization, Wasyra’s custom agent service can be the next conversation. Start with the process you need to verify and its boundaries; tool selection comes afterward.