Claude Code AGENTS.md Guide: Share One Instruction File Across Coding Agents

Claude Code 2.1.277 can now read AGENTS.md when a project does not have a CLAUDE.md. For teams that move between Codex, Cursor, Gemini CLI, and Claude Code, the change can remove a duplicate set of build, test, and contribution instructions. It does not mean every instruction file is automatically merged or that every Claude Code environment supports the feature in the same way.

This guide uses Anthropic’s release, memory documentation, and published built-in plugin notes checked on September 19, 2026. Version 2.1.277 shipped on September 18. A Hacker News discussion about the change had 605 points and 214 comments when checked, which is useful evidence of developer interest, not evidence that the implementation is flawless.

What changed: AGENTS.md is now the default fallback

AGENTS.md is a plain Markdown file for the information a coding agent needs before changing a repository: setup commands, tests, style rules, security boundaries, and completion criteria. It complements the human-facing README and gives multiple coding tools a predictable location for agent-specific guidance. The AGENTS.md project says the format is used in more than 60,000 open-source projects.

Claude Code’s new default is deliberately conservative. If a CLAUDE.md or CLAUDE.local.md exists on the path from the working directory upward, Claude reads the Claude-specific files. If neither exists, it falls back to AGENTS.md. Existing Claude projects therefore keep their current behavior, while repositories that already standardized on AGENTS.md no longer need a copied file or startup workaround.

Repository instruction precedence from CLAUDE.md to AGENTS.md and nested scopes
Claude-specific instructions take precedence by default; AGENTS.md and nested scopes fill the fallback path.

Precedence: which file Claude actually reads

Repository stateDefault behaviorRecommended action
Only AGENTS.mdReads AGENTS.mdKeep it and verify the load notice
AGENTS.md plus CLAUDE.mdReads CLAUDE.md files onlySelect the both-files mode or use an import
CLAUDE.local.md presentReads Claude files onlyEnable both files if team rules live in AGENTS.md
Nested AGENTS.mdLoads when Claude reads a text file in that subtreeKeep package instructions narrow and testable

The fallback check counts CLAUDE.md, .claude/CLAUDE.md, and CLAUDE.local.md in the working directory or any parent directory. A personal ~/.claude/CLAUDE.md, an organization-managed policy file, and files under .claude/rules/ do not suppress AGENTS.md. They can continue to load alongside it.

Before you migrate: check version, provider, and control boundaries

  1. Check the version. Run claude --version and confirm 2.1.277 or later.
  2. Inventory the path. Look for CLAUDE.md, CLAUDE.local.md, and AGENTS.md from the repository root through the current working directory.
  3. Check the runtime. Direct AGENTS.md loading can be unavailable when the session cannot fetch Anthropic feature flags, including some Bedrock, Vertex AI, Foundry, or telemetry-disabled configurations.
  4. Restart after upgrading. The first session after installing or upgrading may not load AGENTS.md. Start a second fresh session before diagnosing a failure.
  5. Separate guidance from enforcement. Instruction files are context for the model, not an access-control mechanism. Use permissions, sandboxes, or a PreToolUse hook for rules that must never be bypassed.

A passing check is more than seeing the file on disk. Under the default mode, the session should report that AGENTS.md loaded, and Claude should be able to summarize the repository’s actual commands and boundaries.

A minimal AGENTS.md that is useful instead of decorative

Put a concise, testable file at the repository root. Prioritize commands and decision boundaries over a copied product overview.

# Project instructions

## Setup
- Install: pnpm install --frozen-lockfile
- Dev server: pnpm dev

## Checks
- Unit tests: pnpm test
- Type and lint: pnpm check

## Boundaries
- Do not edit generated files under dist/
- Never commit .env files or real customer data
- Ask before changing database migrations

Start a new Claude Code session from the repository root. Confirm the load notice, then ask a verification question such as, “Summarize the paths you must not edit and the checks required before completion.” Only list commands that exist in the project. A plausible but nonexistent test command creates repeated failures and weakens trust in the entire file.

Choose one of four Project instructions modes

Type /config in Claude Code and open Project instructions. Anthropic documents four values:

  • claude-md-or-agents-md: the default. Read Claude files when present, otherwise AGENTS.md.
  • claude-md-and-agents-md: read both. Within a directory, Claude files are placed before AGENTS.md.
  • claude-md: ignore AGENTS.md and keep the earlier Claude-only behavior.
  • managed-only: keep organization-managed CLAUDE.md and auto memory while dropping user, project, local, and AGENTS.md files at startup.

The change applies from your next message. A frequent mistake is placing this plugin option in the repository’s .claude/settings.json; Claude Code does not read project or local settings for this option. Put it in ~/.claude/settings.json, a file passed with --settings, or managed settings.

{
  "pluginConfigs": {
    "agents-md@builtin": {
      "options": {
        "instructionFiles": "claude-md-and-agents-md"
      }
    }
  }
}
Four Project instructions modes and a separate enforced safety gate
Four Project instructions modes guide context, while enforceable safety remains a separate gate.

A safe migration from duplicate instruction files

  1. Compare the files. Mark duplicate setup, test, style, and safety rules, plus genuine conflicts.
  2. Move shared facts into AGENTS.md. Keep commands, completion evidence, repository structure, and data boundaries that every supported agent can use.
  3. Keep Claude-specific details separate. If you need a Claude-only feature, start CLAUDE.md with @AGENTS.md and add the special instruction below it.
  4. Choose one compatibility path. Remove CLAUDE.md when all environments support direct loading. Keep the import when Bedrock or another limited environment is part of the team.
  5. Remove old workarounds. Delete a SessionStart hook that prints AGENTS.md, or it may inject a second copy. A symlink is deduplicated, but an import is usually more portable for Windows contributors.
  6. Verify in a fresh session. Do not rely on a conversation that started before the migration.

An explicit @AGENTS.md import remains a valid and important compatibility method. It also lets a team add Claude-only notes after the shared file. A sentence telling Claude to “read AGENTS.md” is weaker because it depends on the model deciding to open the file; the import is deterministic.

How nested files behave in a monorepo

Keep repository-wide installation, CI, and security rules in the root AGENTS.md. Put package-specific commands in files such as apps/web/AGENTS.md or packages/api/AGENTS.md. In the supported modes, Claude attaches a nested AGENTS.md when the Read tool opens a text file under that directory. This makes local instructions available only when the work enters that part of the tree.

A good nested file says which test runner the package uses, which generated paths are off-limits, and which command proves completion. Do not copy the same global safety rules into every package. Repetition consumes context, makes updates inconsistent, and creates more opportunities for conflicting instructions.

Three practical setups and their acceptance checks

1. A small team using Codex and Claude Code

Goal: share build and pull-request rules in one file. Put common commands and completion checks in AGENTS.md and use the default fallback when no Claude file is needed. Ask both tools to name the same required tests and prohibited paths. The expected result is shared operational guidance, not identical wording or reasoning between models.

2. Personal preferences plus committed team rules

Goal: commit AGENTS.md for the team while keeping private preferences in CLAUDE.local.md. Because the local file suppresses the fallback, choose claude-md-and-agents-md. Verify that the next message reflects both files and that a personal preference does not override security or release checks owned by the team.

3. A monorepo with different package toolchains

Goal: keep common CI rules at the root and package checks close to each package. Start a clean session, have Claude read a file from two different packages, and ask for the applicable commands. Pass only if each package gets its own checks and Claude does not claim it loaded a subtree it never entered.

Troubleshooting in the right order

  • AGENTS.md never loads: confirm the version, then search the working-directory path for CLAUDE.md or CLAUDE.local.md. Check the Project instructions mode and whether the built-in agents-md plugin is enabled.
  • The setting does not exist: close the first post-upgrade session and start another. If it is still missing, check third-party provider, telemetry, and organization hook restrictions. Use @AGENTS.md from CLAUDE.md as the compatibility path.
  • Two files conflict: consolidate shared rules instead of relying on position to settle an avoidable contradiction. Keep only a genuinely Claude-specific exception in CLAUDE.md.
  • AGENTS.md is absent from /memory: that is a documented difference for direct loading. Confirm the startup load line or ask Claude to summarize its project instructions.
  • Instructions from --add-dir are missing: extra directories do not currently contribute AGENTS.md in the same way they can contribute CLAUDE.md. Import the needed file or reconsider the project root.

Security and context cost: guidance is not a guardrail

Neither AGENTS.md nor CLAUDE.md can technically prevent a destructive command. A line saying “never modify production” is useful guidance, but the enforceable boundary belongs in sandbox rules, permission prompts, a PreToolUse hook, CI protection, and deployment authorization. Keep the safe default and approval condition in the instruction file, then implement the actual block in a separate control layer.

Every persistent instruction also consumes context. Remove stale commands, repeated prose, and facts that are obvious from the repository. Keep the parts an agent must decide correctly: what to run, what not to touch, when to ask, and what evidence counts as complete. Nested files can reduce irrelevant context, but duplicating root rules into every subtree produces the opposite effect.

Migration checklist

  • Claude Code is version 2.1.277 or later.
  • You inventoried CLAUDE.md, CLAUDE.local.md, and AGENTS.md on the complete project path.
  • You selected fallback, both-files, Claude-only, or managed-only behavior intentionally.
  • You accounted for unsupported providers and the first post-upgrade session.
  • A fresh session reported the load state and summarized the correct rules.
  • Hard security controls live outside the instruction file.
  • Legacy imports, symlinks, and SessionStart workarounds do not inject duplicates.

A practical end state is one AGENTS.md for shared build, test, and safety guidance, plus a small CLAUDE.md only when Claude-specific behavior is genuinely necessary. If your next step is packaging repeatable team workflows rather than just documenting them, see the Claude Code plugins guide.

한국어판: Claude Code AGENTS.md 사용법: 여러 코딩 에이전트 지침 하나로 관리하기

Official sources

Sources checked September 19, 2026.

Comments

Post a Comment

Popular posts from this blog

Diagram Design: Set Up Claude Code or Codex for Clearer Diagrams

Image
Diagram Design is a third-party skill/plugin for coding agents that turns a written brief into an HTML file with inline SVG diagrams. It is not a standalone web-based diagram editor. Its useful promise is narrower: give an agent a specific process and visual direction, then review an editable browser-ready diagram rather than starting from a blank canvas. Three practical takeaways Use in-session slash commands for Claude Code and terminal CLI commands for Codex. Describe the flow, constraints, and output path before asking for drawing. Treat every generated diagram as a draft: verify logic, labels, privacy, and export needs yourself. What it does, and what it does not do The plugin can create several diagram layouts and produces static HTML by default. The inline SVG approach makes the result convenient to open, inspect, and share. Keep the request focused on the decision or process the reader must understand. Existing Mermaid, ...
Read more

OpenAI Agents API: A Practical Guide to Managed Agent Runtimes

Image
Making one model call is different from operating an agent that reads files, uses tools, and works through several steps. The latter also needs progress records, execution permissions, recovery decisions, and a plan for keeping its outputs. The OpenAI Agents API exposes the Codex agent harness through an OpenAI-managed API. Its value is not simply a different model endpoint: it changes who operates part of the agent runtime. OpenAI announced the public beta on September 10, 2026. This guide explains what the service manages, how it differs from the Agents SDK and Responses API, and how to evaluate it with a small, reviewable task rather than immediately handing it an entire business process. Documentation checked: September 16, 2026. Three things to keep in mind A managed harness coordinates work and tool use; it is not the model itself. Choosing a managed runtime does not decide your data permissions, external-system access, or approval policy for you. Long-running work may benef...
Read more

Notion Agent Skills: Turn Repeatable Team Work into Reusable Instructions

Image
If your team repeatedly asks AI for the same meeting summary, review, or draft format, copying a prompt eventually becomes fragile. A useful prompt stays in one person’s notes, while the output varies from teammate to teammate. Notion 3.7 Agent Skills , released on September 15, 2026, are designed to turn that working knowledge into reusable instruction pages that Notion Agent can use again. This guide explains where Skills fit for a team that already uses Notion as its document and database hub, how they differ from Custom Agents, and what to check for permissions and cost. An example specification for a meeting-notes skill. Define the input and working rules before adding more instructions. What a Skill is: a repeatable way of working Notion defines a Skill as reusable instructions that teach Notion AI how to complete a type of work. The important detail is that a Skill is a Notion page , not an opaque configuration file. A team can name it, assign an owner, share it, revise it, ...
Read more