We're Adding Support for AGENTS.md to Claude Code  🔗 **Source:** [We're Adding Support for AGENTS.md to Claude Code](https://twitter.com/trq212/status/2101009392611278961/?rw_tt_thread=True) > [!note]+ Document Notes > tags: [claude-code, agents-md, agent-tooling, developer-experience, configuration-standards] > author: Thariq > source: X / Twitter (Anthropic) > reference: https://twitter.com/trq212/status/2101009392611278961/?rw_tt_thread=True > date created: 2026-09-19 16:27 > > > [!info] Generated analysis — not the author's words. Sections below are machine-written > > from the captured source. Only text inside `> [!quote]` blocks is verbatim from the author. > > Do not quote or attribute any other line to the named author. > > <!-- deep-read: light-touch --> > > # 🏷️ Title: We're adding support for AGENTS.md to Claude Code > <!-- deep-read:sections start --> ## 📝 Summary - Claude Code version 2.1.277 reads AGENTS.md when no CLAUDE.md exists in a folder. - The behavior is toggleable in /config. - It ships as a built-in 'mod' — the first public reference to Claude Code mods, described as an upcoming way to customize the harness. - Matters directly: Courtney maintains CLAUDE.md files across repos, and AGENTS.md is the cross-vendor convention other agents already read. - Bottom line: CLAUDE.md still wins where both exist; AGENTS.md is the fallback, not a replacement. ## 📖 Main Content - Precedence is explicit and one-directional — CLAUDE.md present means AGENTS.md is ignored in that folder. - Resolution is per-folder, not per-repo, so a monorepo can mix both conventions across subdirectories. - 'Mods' is the load-bearing announcement here: project instructions become one customizable component rather than hardcoded behavior, and the source is published on GitHub. - Unstated: whether both files are merged when a parent folder has one and a child the other. ## 🗒️ Notes - Version 2.1.277 is the floor for this behavior. - The mod source link points to github.com/anthropics/cla… (truncated in the post). - Practical consequence: a repo that wants one instruction file readable by every agent should use AGENTS.md and not also keep a CLAUDE.md. > [!quote] > if there is no CLAUDE.md in a folder, Claude will check for and use AGENTS.md ## 📚 References - [Claude Code mods source (truncated in post)](https://github.com/anthropics/claude-code) ## 🎯 Conclusion - Consolidating on AGENTS.md is now viable for repos that want one file every agent reads — but only in folders with no CLAUDE.md. - Next step: decide per repo whether to keep CLAUDE.md or move to AGENTS.md; do not keep both in the same folder expecting a merge. ## 🔄 Refactor Appendix — We're adding support for AGENTS.md to Claude Code ### 📚 Literature Atoms (H3) #### [H1] CLAUDE.md takes precedence over AGENTS.md per folder > [!quote] > if there is no CLAUDE.md in a folder, Claude will check for and use AGENTS.md **Context & use**: - Announcement body, version 2.1.277 - Determines which file to keep when consolidating a repo **Tags**: #xref #share <!-- atomicity: 1 idea ✓ --> #### [H2] Project instructions ship as a replaceable Claude Code mod > [!quote] > AGENTS.md support is built off of Claude Code mods, our upcoming way to customize the Claude Code harness. **Context & use**: - Second paragraph of the announcement - Signals instruction loading becomes user-customizable, not fixed **Tags**: #articleseed <!-- atomicity: 1 idea ✓ --> ### 🧠 Permanent Candidates (H4) #### [P1] Fallback resolution makes dual config files a silent no-op **Claim** (one sentence, Courtney's voice): When a tool resolves configuration by fallback rather than merge, keeping both files means the second one never runs and never warns you. **Evidence pointer**: [[#H1]] **Scope & conditions**: Holds for any first-match-wins config lookup; fails where the tool documents an explicit merge order. **Links** (≥1 with annotation): - [[Agent-instruction-files]] — because applies-in repo setup - [[Config-precedence]] — because extends <!-- atomicity: 1 idea ✓ --> ### ✏️ Fleeting Queue - [F1] Does a parent-folder CLAUDE.md suppress a child-folder AGENTS.md, or is resolution strictly per-folder? #fleeting #inbox ### → Things 3 (max 2 actions) - [ ] Audit repos for folders holding both CLAUDE.md and AGENTS.md #things <!-- deep-read:sections end --> 📄 **Full text:** [[Full Document Contents/Tweets/We're Adding Support for AGENTS.md to Claude Code.md|We're Adding Support for AGENTS.md to Claude Code by Thariq]] ## Highlights - This is a built-in mod, but you’ll be able to build custom versions of project instructions yourself as you’d like too. ([View Highlight](https://read.readwise.io/read/01m2zdf7spc3tpesb5crjr2kh7)) ## New Highlights added 2026-09-21 at 5:45 PM - This is a built-in mod, but you’ll be able to build custom versions of project instructions yourself as you’d like too. ([View Highlight](https://read.readwise.io/read/01m2zdf7spc3tpesb5crjr2kh7)) ## New Highlights added 2026-09-21 at 6:45 PM - This is a built-in mod, but you’ll be able to build custom versions of project instructions yourself as you’d like too. ([View Highlight](https://read.readwise.io/read/01m2zdf7spc3tpesb5crjr2kh7)) ## New Highlights added 2026-09-22 at 8:52 PM - This is a built-in mod, but you’ll be able to build custom versions of project instructions yourself as you’d like too. ([View Highlight](https://read.readwise.io/read/01m2zdf7spc3tpesb5crjr2kh7)) ## New Highlights added 2026-09-25 at 1:00 PM - This is a built-in mod, but you’ll be able to build custom versions of project instructions yourself as you’d like too. ([View Highlight](https://read.readwise.io/read/01m2zdf7spc3tpesb5crjr2kh7)) ## New Highlights added 2026-09-25 at 1:46 PM - This is a built-in mod, but you’ll be able to build custom versions of project instructions yourself as you’d like too. ([View Highlight](https://read.readwise.io/read/01m2zdf7spc3tpesb5crjr2kh7)) ## New Highlights added 2026-09-25 at 2:46 PM - This is a built-in mod, but you’ll be able to build custom versions of project instructions yourself as you’d like too. ([View Highlight](https://read.readwise.io/read/01m2zdf7spc3tpesb5crjr2kh7)) ## New Highlights added 2026-09-25 at 4:30 PM - This is a built-in mod, but you’ll be able to build custom versions of project instructions yourself as you’d like too. ([View Highlight](https://read.readwise.io/read/01m2zdf7spc3tpesb5crjr2kh7)) ## New Highlights added 2026-09-26 at 5:49 PM - This is a built-in mod, but you’ll be able to build custom versions of project instructions yourself as you’d like too. ([View Highlight](https://read.readwise.io/read/01m2zdf7spc3tpesb5crjr2kh7))