[{"data":1,"prerenderedAt":1428},["ShallowReactive",2],{"blog-post-claude-md-vs-agents-md":3,"related-posts-claude-md-vs-agents-md":1400},{"id":4,"title":5,"author":6,"body":11,"category":1375,"date":1376,"description":1377,"extension":1378,"featured":1379,"hideToc":1379,"image":1380,"imageAlt":1381,"imageHeight":1382,"imageWidth":1383,"itemList":1384,"lang":1384,"meta":1385,"navigation":519,"noindex":1379,"path":1386,"readingTime":1387,"redirected":1379,"relatedSlugs":1384,"seo":1388,"seoTitle":1389,"stem":1390,"subtitle":1384,"tags":1391,"updatedDate":1376,"__hash__":1399},"blog/blog/claude-md-vs-agents-md.md","CLAUDE.md vs AGENTS.md: Which File Each Agent Reads, and How to Keep One Copy",{"name":7,"role":8,"avatar":9,"bio":10},"Shabnam Katoch","Growth Head","/img/avatars/shabnam-profile.jpeg","Shabnam leads growth at BetterClaw and has spent the past three years building organic distribution for AI-native products. She writes about no-code agent builders, content strategy, and what it actually takes to grow without an ads budget.",{"type":12,"value":13,"toc":1334},"minimark",[14,18,25,33,97,104,110,113,122,127,133,140,143,146,150,153,379,385,388,395,403,407,410,415,418,421,427,430,433,440,444,451,469,473,476,479,482,486,489,493,496,546,553,557,560,583,590,593,597,600,603,607,613,617,620,624,635,639,645,649,668,672,675,679,682,685,690,697,746,749,752,758,762,765,769,792,803,807,814,872,879,883,894,897,901,904,1021,1029,1033,1036,1173,1187,1190,1198,1202,1205,1208,1215,1219,1222,1225,1240,1244,1248,1254,1258,1272,1276,1286,1290,1300,1304,1307,1311,1317,1321,1330],[15,16,17],"p",{},"One repo, five agents, one set of rules. Here is the file layout that works.",[19,20,22],"callout",{"type":21},"quick-fix",[15,23,24],{},"AGENTS.md is the cross-tool convention read by Codex, Copilot, Cursor and most open agents. CLAUDE.md is Claude Code's own file, and you do not need both written out: keep the rules in AGENTS.md and point CLAUDE.md at it with an import line, or symlink. The differences that matter are below.",[15,26,27,28,32],{},"Here's ",[29,30,31],"strong",{},"CLAUDE.md vs AGENTS.md"," as one quick-answer table:",[34,35,36,52],"table",{},[37,38,39],"thead",{},[40,41,42,46,49],"tr",{},[43,44,45],"th",{},"File",[43,47,48],{},"Who reads it",[43,50,51],{},"What goes in it",[53,54,55,70,86],"tbody",{},[40,56,57,64,67],{},[58,59,60],"td",{},[61,62,63],"code",{},"AGENTS.md",[58,65,66],{},"Codex, Copilot, Cursor, OpenCode, Hermes Agent, OpenClaw, and Claude Code when no CLAUDE.md exists",[58,68,69],{},"Every shared rule, under 100 lines",[40,71,72,77,80],{},[58,73,74],{},[61,75,76],{},"CLAUDE.md",[58,78,79],{},"Claude Code (Cursor and Copilot read it too)",[58,81,82,83],{},"Two lines, ending in ",[61,84,85],{},"@AGENTS.md",[40,87,88,91,94],{},[58,89,90],{},"Hooks, CI, permission rules",[58,92,93],{},"The machine, not the model",[58,95,96],{},"Anything that must never be broken",[15,98,99,100,103],{},"Picture this: a teammate adds a ",[61,101,102],{},"CLAUDE.local.md"," to keep their sandbox URL out of git. Next session, Claude Code stops reading the AGENTS.md the rest of the team spent a month tuning.",[15,105,106],{},[107,108,109],"em",{},"Wait. Who deleted our rules?",[15,111,112],{},"No one did. Claude Code's default is to read AGENTS.md only when there's no CLAUDE.md, CLAUDE.local.md or .claude/CLAUDE.md in your working directory or above it. That one quiet rule is why the file layout matters more than the file content.",[15,114,115,116,121],{},"We checked every tool on this page against its own docs on 10 November 2026. If you're still deciding what to write in the file, our ",[117,118,120],"a",{"href":119},"/blog/agents-md-best-practices","AGENTS.md best practices guide"," covers length, templates and examples. This page is about which agent reads which file.",[123,124,126],"h2",{"id":125},"claudemd-vs-agentsmd-the-one-line-layout","CLAUDE.md vs AGENTS.md: the one-line layout",[15,128,129,130],{},"The layout we recommend for any repo touched by more than one agent fits in one sentence: ",[29,131,132],{},"rules live in AGENTS.md, and every CLAUDE.md is a pointer.",[15,134,135],{},[136,137],"img",{"alt":138,"src":139},"CLAUDE.md vs AGENTS.md repo layout: AGENTS.md at the root, a nested AGENTS.md in a package, and CLAUDE.md files as one-line pointers beside each","/img/blog/claude-md-vs-agents-md-repo-tree.jpg",[15,141,142],{},"The nested pointer is the part most guides skip. Once a CLAUDE.md sits at the root, Anthropic's memory docs say Claude Code reads \"your CLAUDE.md files only\". By default, a package's AGENTS.md with no CLAUDE.md beside it never loads for Claude.",[15,144,145],{},"So every folder that has an AGENTS.md also gets a one-line CLAUDE.md. Claude Code loads a subdirectory CLAUDE.md once it reads, writes or edits a file there, and the import pulls in the AGENTS.md next to it.",[123,147,149],{"id":148},"which-tools-read-which-file","Which tools read which file",[15,151,152],{},"Here's what each tool's own docs say today. Where a doc is silent, the table says \"not documented\" instead of guessing.",[34,154,155,174],{},[37,156,157],{},[40,158,159,162,165,168,171],{},[43,160,161],{},"Tool",[43,163,164],{},"Files it reads",[43,166,167],{},"Where it looks",[43,169,170],{},"Nested files",[43,172,173],{},"Size guidance",[53,175,176,208,246,278,305,327,356],{},[40,177,178,181,195,202,205],{},[58,179,180],{},"Claude Code",[58,182,183,185,186,185,189,191,192,194],{},[61,184,76],{},", ",[61,187,188],{},".claude/CLAUDE.md",[61,190,102],{},"; ",[61,193,63],{}," only when none of those exist (v2.1.277 or later)",[58,196,197,198,201],{},"Working directory and every parent; ",[61,199,200],{},"~/.claude/CLAUDE.md","; a managed policy file",[58,203,204],{},"Subdirectory files load when Claude touches a file there",[58,206,207],{},"Under 200 lines per file; launch files over 4 MiB are skipped",[40,209,210,213,226,236,239],{},[58,211,212],{},"OpenAI Codex",[58,214,215,218,219,221,222,225],{},[61,216,217],{},"AGENTS.override.md",", then ",[61,220,63],{},", then names in ",[61,223,224],{},"project_doc_fallback_filenames","; not CLAUDE.md by default",[58,227,228,231,232,235],{},[61,229,230],{},"~/.codex"," (or ",[61,233,234],{},"CODEX_HOME","), then project root down to the working directory",[58,237,238],{},"One file per directory, joined root first, closer files last",[58,240,241,242,245],{},"32 KiB combined (",[61,243,244],{},"project_doc_max_bytes",")",[40,247,248,251,269,272,275],{},[58,249,250],{},"GitHub Copilot",[58,252,253,185,256,185,259,261,262,264,265,268],{},[61,254,255],{},".github/copilot-instructions.md",[61,257,258],{},".github/instructions/*.instructions.md",[61,260,63],{},", or one ",[61,263,76],{}," or ",[61,266,267],{},"GEMINI.md"," at the root",[58,270,271],{},"The repository; support varies by surface",[58,273,274],{},"Nearest AGENTS.md takes precedence; VS Code needs a setting for files outside the workspace root",[58,276,277],{},"About 1,000 lines per file (code review guidance)",[40,279,280,283,296,299,302],{},[58,281,282],{},"Cursor",[58,284,285,288,289,185,292,185,294],{},[61,286,287],{},".mdc"," project rules in ",[61,290,291],{},".cursor/rules/",[61,293,63],{},[61,295,76],{},[58,297,298],{},"Project root and subfolders; user and team rules",[58,300,301],{},"Nested AGENTS.md combine with parents, more specific wins",[58,303,304],{},"Rules under 500 lines",[40,306,307,310,315,321,324],{},[58,308,309],{},"OpenCode (V2)",[58,311,312,314],{},[61,313,63],{}," only; V2 dropped the CLAUDE.md fallback",[58,316,317,320],{},[61,318,319],{},"~/.config/opencode/AGENTS.md",", then the working directory upward",[58,322,323],{},"Nested files load as the agent reads that area",[58,325,326],{},"Not documented",[40,328,329,332,347,350,353],{},[58,330,331],{},"Hermes Agent",[58,333,334,335,185,338,185,340,185,342,185,344],{},"First match wins: ",[61,336,337],{},".hermes.md",[61,339,217],{},[61,341,63],{},[61,343,76],{},[61,345,346],{},".cursorrules",[58,348,349],{},"Git root down to the working directory",[58,351,352],{},"Discovered progressively as the agent works in a folder",[58,354,355],{},"Cap scales with the model, 20,000 to 500,000 characters",[40,357,358,361,367,374,376],{},[58,359,360],{},"OpenClaw",[58,362,363,364,366],{},"Workspace ",[61,365,63],{}," with SOUL.md and friends; a project folder's AGENTS.md when the session runs there; CLAUDE.md not documented",[58,368,369,370,373],{},"The agent workspace, ",[61,371,372],{},"~/.openclaw/workspace"," by default",[58,375,326],{},[58,377,378],{},"20,000 characters per file, 60,000 total",[15,380,381],{},[136,382],{"alt":383,"src":384},"CLAUDE.md vs AGENTS.md support table: seven agents in rows, showing whether each reads AGENTS.md, CLAUDE.md and its own file","/img/blog/claude-md-vs-agents-md-which-tool.jpg",[15,386,387],{},"Three things jump out of that table.",[15,389,390,391,394],{},"First, AGENTS.md is the only file all seven read. Second, CLAUDE.md leaks: Cursor applies it to every conversation regardless of any ",[61,392,393],{},"alwaysApply"," frontmatter, and Copilot's cloud agent accepts it as an alternative.",[15,396,397,398,402],{},"Third, Hermes Agent and OpenClaw also load a personality file, SOUL.md, that has nothing to do with project rules. Our ",[117,399,401],{"href":400},"/blog/hermes-soul-md-guide","SOUL.md guide for Hermes"," covers where that one lives.",[123,404,406],{"id":405},"claudemd-vs-agentsmd-the-differences-that-actually-matter","CLAUDE.md vs AGENTS.md: the differences that actually matter",[15,408,409],{},"The file names are the easy part. Four behaviours decide whether your rules actually arrive.",[411,412,414],"h3",{"id":413},"loading-order","Loading order",[15,416,417],{},"Claude Code concatenates every file it finds, from the filesystem root down to your working directory, with CLAUDE.local.md after CLAUDE.md in each folder. Nothing overrides anything. Anthropic's docs warn that \"if two instructions contradict each other, Claude may pick one arbitrarily.\"",[15,419,420],{},"Codex also joins files root first, and says files closer to your working directory \"override earlier guidance because they appear later in the combined prompt.\" OpenCode V2 combines its files and \"does not resolve conflicts between them.\" Cursor merges Team, Project and User rules, with earlier sources winning a conflict.",[422,423,424],"blockquote",{},[15,425,426],{},"Four tools, four merge rules. The only safe nested file is one that adds rules, never one that reverses them.",[411,428,170],{"id":429},"nested-files",[15,431,432],{},"Claude Code, Hermes Agent and OpenCode all pick up a subfolder's file as the agent starts working there. Codex's docs describe no such step. It builds its chain once per run, from the project root down to where you launched it, and it \"stops searching once it reaches your current directory.\"",[15,434,435,436,439],{},"So if you start Codex at the repo root and edit ",[61,437,438],{},"packages/payments",", that package's AGENTS.md isn't in the loaded chain. Launch from the package, or keep must-know rules at the root.",[411,441,443],{"id":442},"imports","Imports",[15,445,446,447,450],{},"Of the seven, only Claude Code documents expanding ",[61,448,449],{},"@path"," imports. Paths resolve relative to the file that holds them, imports can nest four hops deep, and they work inside an AGENTS.md that Claude reads directly too.",[15,452,453,454,457,458,461,462,465,466,468],{},"Cursor treats ",[61,455,456],{},"@file"," as a pointer: its docs say the file's contents \"are not inlined into the prompt.\" OpenCode asks you to list extra files in the ",[61,459,460],{},"instructions"," array of ",[61,463,464],{},"opencode.json"," instead. Codex, Copilot, Hermes Agent and OpenClaw don't document import syntax at all, so to them ",[61,467,85],{}," is just text.",[411,470,472],{"id":471},"sections-a-tool-doesnt-understand","Sections a tool doesn't understand",[15,474,475],{},"AGENTS.md has no required fields. The agents.md FAQ says it's \"just standard Markdown\", so every tool reads every heading, including a \"## Claude Code\" section meant for one agent.",[15,477,478],{},"Two quirks are worth knowing. Claude Code strips block-level HTML comments from CLAUDE.md before Claude sees them, which makes them handy for maintainer notes.",[15,480,481],{},"Hermes Agent lists hidden HTML comments among the prompt-injection signs its scanner checks: a comment containing words like \"ignore\", \"override\", \"system\", \"secret\" or \"hidden\" is flagged, and a hit blocks the whole file. In a shared AGENTS.md, keep notes for humans out of comments.",[123,483,485],{"id":484},"one-source-of-truth-import-symlink-or-keep-them-separate","One source of truth: import, symlink or keep them separate",[15,487,488],{},"You have three ways to stop two files drifting apart. We've ranked them.",[411,490,492],{"id":491},"the-import-our-pick","The import (our pick)",[15,494,495],{},"This is the layout Anthropic's docs show for sharing one file with other coding tools:",[497,498,503],"pre",{"className":499,"code":500,"language":501,"meta":502,"style":502},"language-markdown shiki shiki-themes github-light","@AGENTS.md\n\n## Claude Code\n\nUse plan mode for changes under `src/billing/`.\n","markdown","",[61,504,505,514,521,528,533],{"__ignoreMap":502},[506,507,510],"span",{"class":508,"line":509},"line",1,[506,511,513],{"class":512},"sgsFI","@AGENTS.md\n",[506,515,517],{"class":508,"line":516},2,[506,518,520],{"emptyLinePlaceholder":519},true,"\n",[506,522,524],{"class":508,"line":523},3,[506,525,527],{"class":526},"surfw","## Claude Code\n",[506,529,531],{"class":508,"line":530},4,[506,532,520],{"emptyLinePlaceholder":519},[506,534,536,539,543],{"class":508,"line":535},5,[506,537,538],{"class":512},"Use plan mode for changes under ",[506,540,542],{"class":541},"sYu0t","`src/billing/`",[506,544,545],{"class":512},".\n",[15,547,548,549,552],{},"It works on every Claude Code version, it survives a teammate adding CLAUDE.local.md, and Anthropic says keeping the import \"never makes Claude read AGENTS.md twice.\" One catch: Cursor applies CLAUDE.md to every conversation, so anything you write under the import reaches Cursor's agent as well. Put Claude-only rules in ",[61,550,551],{},".claude/rules/"," instead, which loads alongside AGENTS.md and doesn't count as a CLAUDE.md.",[411,554,556],{"id":555},"the-symlink","The symlink",[15,558,559],{},"If you don't need Claude-specific content, Anthropic's docs list a symlink as the other option:",[497,561,565],{"className":562,"code":563,"language":564,"meta":502,"style":502},"language-bash shiki shiki-themes github-light","ln -s AGENTS.md CLAUDE.md\n","bash",[61,566,567],{"__ignoreMap":502},[506,568,569,573,576,580],{"class":508,"line":509},[506,570,572],{"class":571},"s7eDp","ln",[506,574,575],{"class":541}," -s",[506,577,579],{"class":578},"sYBdl"," AGENTS.md",[506,581,582],{"class":578}," CLAUDE.md\n",[15,584,585,586,589],{},"It has three costs. On Windows, creating it needs Administrator rights or Developer Mode, and Git checks a committed symlink out as a plain text file unless ",[61,587,588],{},"core.symlinks"," is enabled, leaving that clone with a one-line CLAUDE.md.",[15,591,592],{},"Claude Code's Edit and Write tools also refuse to write through a symlink. And Cursor and Copilot both read files named AGENTS.md and CLAUDE.md; neither documents whether it notices that the two are the same file.",[411,594,596],{"id":595},"no-claudemd-at-all","No CLAUDE.md at all",[15,598,599],{},"Since v2.1.277, Claude Code reads AGENTS.md on its own when there's no CLAUDE.md. It's the cleanest layout, but the CLAUDE.local.md trap above switches it off, and so do versions before v2.1.277 and, in some cases, the first session after upgrading from v2.1.276 or earlier.",[15,601,602],{},"Fine for a solo repo. Fragile for a team.",[411,604,606],{"id":605},"keep-them-separate","Keep them separate",[15,608,609,610,612],{},"Do this only when Claude needs a lot that other agents must not see. Even then, start the CLAUDE.md with ",[61,611,85],{}," so the shared rules exist once.",[123,614,616],{"id":615},"agentsmd-vs-skillsmd-vs-copilot-instructionsmd-vs-instructionsmd","AGENTS.md vs skills.md vs copilot-instructions.md vs instructions.md",[15,618,619],{},"The autocomplete asks about all of these, so here's one paragraph each.",[411,621,623],{"id":622},"skillsmd","skills.md",[15,625,626,627,630,631,634],{},"There's no single skills.md file. A skill is a folder with a SKILL.md inside it, following the Agent Skills open standard: ",[61,628,629],{},".claude/skills/\u003Cname>/SKILL.md"," in Claude Code, ",[61,632,633],{},".agents/skills"," in Codex. The difference from AGENTS.md is when it loads: Codex and Claude Code read a skill's full instructions only when the task calls for it, so multi-step procedures belong there.",[411,636,638],{"id":637},"copilot-instructionsmd","copilot-instructions.md",[15,640,641,642,644],{},"This is Copilot's own repository-wide file, at ",[61,643,255],{},". Every Copilot surface GitHub lists, from Chat on GitHub.com to Xcode, supports it, which AGENTS.md can't yet claim on Copilot.",[411,646,648],{"id":647},"instructionsmd","instructions.md",[15,650,651,652,655,656,659,660,663,664,667],{},"Copilot's path-specific files are named ",[61,653,654],{},"NAME.instructions.md"," under ",[61,657,658],{},".github/instructions/",", with an ",[61,661,662],{},"applyTo"," glob in the frontmatter. They're Copilot's version of Cursor's file-scoped rules and Claude Code's ",[61,665,666],{},"paths"," rules.",[411,669,671],{"id":670},"readmemd-and-agentmd","README.md and AGENT.md",[15,673,674],{},"The agents.md site puts it plainly: \"README.md files are for humans.\" And AGENT.md, singular, is a typo the same site suggests fixing with a rename plus a symlink back for older tools.",[123,676,678],{"id":677},"what-belongs-in-the-file-and-what-belongs-in-hooks","What belongs in the file and what belongs in hooks",[15,680,681],{},"Here's the line we draw. If a machine can check a rule, a machine should enforce it. AGENTS.md keeps the judgment calls.",[15,683,684],{},"Three vendors say the same thing in their own docs. Anthropic calls CLAUDE.md \"context, not enforced configuration\" and says to use a PreToolUse hook to block an action \"regardless of what Claude decides.\" OpenAI's AGENTS.md guide says to \"reserve formatting and lint checks for CI.\" Cursor's rules page says not to copy entire style guides: \"Use a linter instead.\"",[422,686,687],{},[15,688,689],{},"A sentence in AGENTS.md is a request. A hook, a CI check or a permission rule is a wall. Put each rule where it belongs.",[15,691,692,693,696],{},"So formatting, lint, \"tests must pass\" and forbidden paths go to pre-commit hooks, CI and permission rules. In Claude Code, a deny rule in the committed ",[61,694,695],{},".claude/settings.json"," holds for everyone on the repo:",[497,698,702],{"className":699,"code":700,"language":701,"meta":502,"style":502},"language-json shiki shiki-themes github-light","{\n  \"permissions\": {\n    \"deny\": [\"Edit(/generated/**)\", \"Read(./.env)\"]\n  }\n}\n","json",[61,703,704,709,717,736,741],{"__ignoreMap":502},[506,705,706],{"class":508,"line":509},[506,707,708],{"class":512},"{\n",[506,710,711,714],{"class":508,"line":516},[506,712,713],{"class":541},"  \"permissions\"",[506,715,716],{"class":512},": {\n",[506,718,719,722,725,728,730,733],{"class":508,"line":523},[506,720,721],{"class":541},"    \"deny\"",[506,723,724],{"class":512},": [",[506,726,727],{"class":578},"\"Edit(/generated/**)\"",[506,729,185],{"class":512},[506,731,732],{"class":578},"\"Read(./.env)\"",[506,734,735],{"class":512},"]\n",[506,737,738],{"class":508,"line":530},[506,739,740],{"class":512},"  }\n",[506,742,743],{"class":508,"line":535},[506,744,745],{"class":512},"}\n",[15,747,748],{},"Codex has its own hooks, including PreToolUse and Stop, plus rules for which commands may run outside its sandbox. What stays in AGENTS.md: which of two valid approaches your team prefers, when to stop and ask, and what an unfamiliar module is for.",[15,750,751],{},"That split also keeps the file short, and the research we summarised in the best practices guide linked above is clear that every extra line in a context file costs you on every run.",[15,753,754],{},[136,755],{"alt":756,"src":757},"CLAUDE.md vs AGENTS.md rules split: judgment calls stay in the file, checkable rules move to hooks, CI and permission rules","/img/blog/claude-md-vs-agents-md-file-vs-hooks.jpg",[123,759,761],{"id":760},"keeping-it-in-sync-across-many-repos-and-many-developers","Keeping it in sync across many repos and many developers",[15,763,764],{},"One repo is easy. Forty repos and 500 developers is where files quietly drift. Here's what each layer can do.",[411,766,768],{"id":767},"claude-code-organisation-wide","Claude Code, organisation-wide",[15,770,771,772,775,776,779,780,783,784,787,788,791],{},"IT can deploy a managed CLAUDE.md to every machine, at ",[61,773,774],{},"/Library/Application Support/ClaudeCode/CLAUDE.md"," on macOS, ",[61,777,778],{},"/etc/claude-code/CLAUDE.md"," on Linux and WSL, and ",[61,781,782],{},"C:\\Program Files\\ClaudeCode\\CLAUDE.md"," on Windows, using MDM, Group Policy or Ansible. Or skip the file and put the text in the ",[61,785,786],{},"claudeMd"," key of ",[61,789,790],{},"managed-settings.json",", which lives in the same three folders.",[15,793,794,795,798,799,802],{},"Developers can't exclude the managed file with ",[61,796,797],{},"claudeMdExcludes",". Several teams can each own a piece of the policy through a ",[61,800,801],{},"managed-settings.d/"," folder, and a claude.ai organisation can push server-managed settings instead.",[411,804,806],{"id":805},"make-claude-read-both-files-everywhere","Make Claude read both files everywhere",[15,808,809,810,813],{},"The Project instructions value lives under ",[61,811,812],{},"pluginConfigs"," in settings, and Claude Code honours it from user or managed settings but ignores it in project files. Set it once in managed settings:",[497,815,817],{"className":699,"code":816,"language":701,"meta":502,"style":502},"{\n  \"pluginConfigs\": {\n    \"cc-plugin-agents-md@builtin\": {\n      \"options\": { \"instructionFiles\": \"claude-md-and-agents-md\" }\n    }\n  }\n}\n",[61,818,819,823,830,837,857,862,867],{"__ignoreMap":502},[506,820,821],{"class":508,"line":509},[506,822,708],{"class":512},[506,824,825,828],{"class":508,"line":516},[506,826,827],{"class":541},"  \"pluginConfigs\"",[506,829,716],{"class":512},[506,831,832,835],{"class":508,"line":523},[506,833,834],{"class":541},"    \"cc-plugin-agents-md@builtin\"",[506,836,716],{"class":512},[506,838,839,842,845,848,851,854],{"class":508,"line":530},[506,840,841],{"class":541},"      \"options\"",[506,843,844],{"class":512},": { ",[506,846,847],{"class":541},"\"instructionFiles\"",[506,849,850],{"class":512},": ",[506,852,853],{"class":578},"\"claude-md-and-agents-md\"",[506,855,856],{"class":512}," }\n",[506,858,859],{"class":508,"line":535},[506,860,861],{"class":512},"    }\n",[506,863,865],{"class":508,"line":864},6,[506,866,740],{"class":512},[506,868,870],{"class":508,"line":869},7,[506,871,745],{"class":512},[15,873,874,875,878],{},"If some machines run Claude Code older than v2.1.285, the plugin ID there was ",[61,876,877],{},"agents-md@builtin",", so use that ID instead. Newer versions read either.",[411,880,882],{"id":881},"skills-and-hooks","Skills and hooks",[15,884,885,886,889,890,893],{},"Package them as a Claude Code plugin, which can hold skills, hooks, subagents and MCP servers. Register your marketplace with ",[61,887,888],{},"extraKnownMarketplaces"," and switch plugins on with ",[61,891,892],{},"enabledPlugins",".",[15,895,896],{},"Cursor does the same through team marketplaces and enforced Team Rules. Copilot has organisation instructions on Business and Enterprise plans, but only for sessions on GitHub's website and code review.",[411,898,900],{"id":899},"a-template-repo-and-one-ci-check","A template repo and one CI check",[15,902,903],{},"New repos start from a template, and CI fails when the files drift:",[497,905,907],{"className":562,"code":906,"language":564,"meta":502,"style":502},"test -f AGENTS.md || { echo \"AGENTS.md missing\"; exit 1; }\n[ \"$(wc -l \u003C AGENTS.md)\" -le 150 ] || { echo \"AGENTS.md over 150 lines\"; exit 1; }\ngrep -qx '@AGENTS.md' CLAUDE.md || { echo \"CLAUDE.md must import AGENTS.md\"; exit 1; }\n",[61,908,909,943,990],{"__ignoreMap":502},[506,910,911,914,917,919,923,926,929,932,934,937,940],{"class":508,"line":509},[506,912,913],{"class":541},"test",[506,915,916],{"class":541}," -f",[506,918,579],{"class":578},[506,920,922],{"class":921},"sD7c4"," ||",[506,924,925],{"class":512}," { ",[506,927,928],{"class":541},"echo",[506,930,931],{"class":578}," \"AGENTS.md missing\"",[506,933,191],{"class":512},[506,935,936],{"class":541},"exit",[506,938,939],{"class":541}," 1",[506,941,942],{"class":512},"; }\n",[506,944,945,948,951,954,957,960,963,966,969,972,975,977,979,982,984,986,988],{"class":508,"line":516},[506,946,947],{"class":512},"[ ",[506,949,950],{"class":578},"\"$(",[506,952,953],{"class":571},"wc",[506,955,956],{"class":541}," -l",[506,958,959],{"class":921}," \u003C",[506,961,962],{"class":578}," AGENTS.md)\"",[506,964,965],{"class":921}," -le",[506,967,968],{"class":541}," 150",[506,970,971],{"class":512}," ] ",[506,973,974],{"class":921},"||",[506,976,925],{"class":512},[506,978,928],{"class":541},[506,980,981],{"class":578}," \"AGENTS.md over 150 lines\"",[506,983,191],{"class":512},[506,985,936],{"class":541},[506,987,939],{"class":541},[506,989,942],{"class":512},[506,991,992,995,998,1001,1004,1006,1008,1010,1013,1015,1017,1019],{"class":508,"line":523},[506,993,994],{"class":571},"grep",[506,996,997],{"class":541}," -qx",[506,999,1000],{"class":578}," '@AGENTS.md'",[506,1002,1003],{"class":578}," CLAUDE.md",[506,1005,922],{"class":921},[506,1007,925],{"class":512},[506,1009,928],{"class":541},[506,1011,1012],{"class":578}," \"CLAUDE.md must import AGENTS.md\"",[506,1014,191],{"class":512},[506,1016,936],{"class":541},[506,1018,939],{"class":541},[506,1020,942],{"class":512},[15,1022,1023,1024,1028],{},"Running several agents against the same repo at once? Our guide to ",[117,1025,1027],{"href":1026},"/blog/agents-md-multi-agent-best-practices","AGENTS.md for multi-agent setups"," covers splitting roles without the files contradicting each other.",[123,1030,1032],{"id":1031},"a-starter-agentsmd-and-a-two-line-claudemd","A starter AGENTS.md and a two-line CLAUDE.md",[15,1034,1035],{},"Copy these, then cut anything your agents already get right without being told.",[497,1037,1039],{"className":499,"code":1038,"language":501,"meta":502,"style":502},"# AGENTS.md\n\n## Stack\nTypeScript 5, Node 22, pnpm workspaces, Vitest, Postgres via Drizzle.\n\n## Commands\nInstall: `pnpm install`\nTest one file: `pnpm vitest run path/to/file.test.ts`\nFull check before a PR: `pnpm check`\n\n## Conventions\nMoney is integer cents, never floats.\nNew endpoints go in `src/api/\u003Cresource>/` with a test beside them.\nPrefer small pure functions over classes in `src/lib/`.\n\n## Ask first\nBefore adding a dependency, changing a migration, or touching `src/billing/`.\n\n## Enforced elsewhere (do not restate here)\nFormatting, lint and forbidden paths are enforced by hooks and CI.\n",[61,1040,1041,1046,1050,1055,1060,1064,1069,1077,1086,1095,1100,1106,1112,1124,1135,1140,1146,1156,1161,1167],{"__ignoreMap":502},[506,1042,1043],{"class":508,"line":509},[506,1044,1045],{"class":526},"# AGENTS.md\n",[506,1047,1048],{"class":508,"line":516},[506,1049,520],{"emptyLinePlaceholder":519},[506,1051,1052],{"class":508,"line":523},[506,1053,1054],{"class":526},"## Stack\n",[506,1056,1057],{"class":508,"line":530},[506,1058,1059],{"class":512},"TypeScript 5, Node 22, pnpm workspaces, Vitest, Postgres via Drizzle.\n",[506,1061,1062],{"class":508,"line":535},[506,1063,520],{"emptyLinePlaceholder":519},[506,1065,1066],{"class":508,"line":864},[506,1067,1068],{"class":526},"## Commands\n",[506,1070,1071,1074],{"class":508,"line":869},[506,1072,1073],{"class":512},"Install: ",[506,1075,1076],{"class":541},"`pnpm install`\n",[506,1078,1080,1083],{"class":508,"line":1079},8,[506,1081,1082],{"class":512},"Test one file: ",[506,1084,1085],{"class":541},"`pnpm vitest run path/to/file.test.ts`\n",[506,1087,1089,1092],{"class":508,"line":1088},9,[506,1090,1091],{"class":512},"Full check before a PR: ",[506,1093,1094],{"class":541},"`pnpm check`\n",[506,1096,1098],{"class":508,"line":1097},10,[506,1099,520],{"emptyLinePlaceholder":519},[506,1101,1103],{"class":508,"line":1102},11,[506,1104,1105],{"class":526},"## Conventions\n",[506,1107,1109],{"class":508,"line":1108},12,[506,1110,1111],{"class":512},"Money is integer cents, never floats.\n",[506,1113,1115,1118,1121],{"class":508,"line":1114},13,[506,1116,1117],{"class":512},"New endpoints go in ",[506,1119,1120],{"class":541},"`src/api/\u003Cresource>/`",[506,1122,1123],{"class":512}," with a test beside them.\n",[506,1125,1127,1130,1133],{"class":508,"line":1126},14,[506,1128,1129],{"class":512},"Prefer small pure functions over classes in ",[506,1131,1132],{"class":541},"`src/lib/`",[506,1134,545],{"class":512},[506,1136,1138],{"class":508,"line":1137},15,[506,1139,520],{"emptyLinePlaceholder":519},[506,1141,1143],{"class":508,"line":1142},16,[506,1144,1145],{"class":526},"## Ask first\n",[506,1147,1149,1152,1154],{"class":508,"line":1148},17,[506,1150,1151],{"class":512},"Before adding a dependency, changing a migration, or touching ",[506,1153,542],{"class":541},[506,1155,545],{"class":512},[506,1157,1159],{"class":508,"line":1158},18,[506,1160,520],{"emptyLinePlaceholder":519},[506,1162,1164],{"class":508,"line":1163},19,[506,1165,1166],{"class":526},"## Enforced elsewhere (do not restate here)\n",[506,1168,1170],{"class":508,"line":1169},20,[506,1171,1172],{"class":512},"Formatting, lint and forbidden paths are enforced by hooks and CI.\n",[497,1174,1176],{"className":499,"code":1175,"language":501,"meta":502,"style":502},"# Claude Code: shared rules live in AGENTS.md\n@AGENTS.md\n",[61,1177,1178,1183],{"__ignoreMap":502},[506,1179,1180],{"class":508,"line":509},[506,1181,1182],{"class":526},"# Claude Code: shared rules live in AGENTS.md\n",[506,1184,1185],{"class":508,"line":516},[506,1186,513],{"class":512},[15,1188,1189],{},"The heading line is there for humans and for Cursor, which reads CLAUDE.md too and will see what the file is for. Claude Code expands the import.",[15,1191,1192,1193,1197],{},"OpenClaw truncates each file at 20,000 characters by default, and Hermes Agent's cap never drops below that, so a file this size fits everywhere. Our notes on ",[117,1194,1196],{"href":1195},"/blog/openclaw-agents-md-optimization","AGENTS.md optimization for OpenClaw"," cover what to trim when you get close.",[123,1199,1201],{"id":1200},"one-instruction-file-across-agents-and-where-betterclaw-fits","One instruction file across agents, and where BetterClaw fits",[15,1203,1204],{},"Everything above is about coding agents in a repo. But the same rules often need to reach agents that never open your repo: the one triaging support email overnight, or the one watching a deploy channel.",[15,1206,1207],{},"Those always-on agents are what BetterClaw runs. You bring your own model keys, with zero markup across 28+ providers, so the model stays your choice and your bill, and agents reach your tools through 500+ connectors.",[15,1209,1210,1211],{},"The principle from this page carries straight over: keep one written set of rules, and enforce the hard limits outside the prompt. Plans start from $19 a month, and your first workspace starts with a 7-day free trial. ",[117,1212,1214],{"href":1213},"/pricing","See BetterClaw plans",[123,1216,1218],{"id":1217},"write-the-rules-once-then-stop-thinking-about-file-names","Write the rules once, then stop thinking about file names",[15,1220,1221],{},"Every agent on this page will keep inventing its own file. Some new one will ship next quarter with a new name and a new fallback order.",[15,1223,1224],{},"You don't have to chase them. Write the rules once in AGENTS.md, point everything else at it in one line, and move anything that must never break into a hook. Then the only question left is the one worth your time: is this rule still earning its line?",[19,1226,1228,1233],{"type":1227},"cta",[15,1229,1230],{},[29,1231,1232],{},"Rolling this out across a whole team?",[15,1234,1235,1236],{},"If you're standardising agent setups across many repos or many teams, we can help you map it. The AI automation audit starts with a 30-minute call about how your team works, and within 5 business days you get a written report with where agents fit, the agent architecture and ROI projections. ",[117,1237,1239],{"href":1238},"/ai-automation-audit","Book an AI automation audit",[123,1241,1243],{"id":1242},"frequently-asked-questions","Frequently Asked Questions",[411,1245,1247],{"id":1246},"what-is-the-difference-between-claudemd-and-agentsmd","What is the difference between CLAUDE.md and AGENTS.md?",[15,1249,1250,1251,1253],{},"AGENTS.md is the cross-tool instruction file read by Codex, Copilot, Cursor, OpenCode, Hermes Agent and OpenClaw. CLAUDE.md is Claude Code's own file, with extras like ",[61,1252,449],{}," imports and a managed, organisation-wide version. Keep the rules in AGENTS.md and make CLAUDE.md a one-line import.",[411,1255,1257],{"id":1256},"does-claude-code-read-agentsmd","Does Claude Code read AGENTS.md?",[15,1259,1260,1261,1264,1265,1268,1269,1271],{},"Yes, from v2.1.277, but by default only when there's no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in your working directory or above it. To read both, set Project instructions to ",[61,1262,1263],{},"claude-md-and-agents-md"," in ",[61,1266,1267],{},"/config",", or put ",[61,1270,85],{}," in your CLAUDE.md. It never reads AGENTS.override.md or AGENTS.local.md.",[411,1273,1275],{"id":1274},"can-i-symlink-claudemd-to-agentsmd","Can I symlink CLAUDE.md to AGENTS.md?",[15,1277,1278,1279,1282,1283,1285],{},"Yes. ",[61,1280,1281],{},"ln -s AGENTS.md CLAUDE.md"," works, and Anthropic lists it as an option. Avoid it if anyone clones the repo on Windows, where Git can check the link out as a one-line text file, and note that Claude Code's edit tools won't write through it. The ",[61,1284,85],{}," import avoids both problems.",[411,1287,1289],{"id":1288},"what-is-skillsmd","What is skills.md?",[15,1291,1292,1293,1296,1297,1299],{},"There's no single skills.md file. Skills are folders that each hold a SKILL.md, following the Agent Skills open standard, in ",[61,1294,1295],{},".claude/skills/"," for Claude Code and ",[61,1298,633],{}," for Codex. Their full instructions load only when the task needs them, which makes them the right home for multi-step procedures.",[411,1301,1303],{"id":1302},"how-big-should-agentsmd-be","How big should AGENTS.md be?",[15,1305,1306],{},"Aim for under 100 lines. Anthropic's ceiling for CLAUDE.md is 200 lines, Codex stops adding files at 32 KiB combined, Cursor suggests rules under 500 lines, and Hermes Agent and OpenClaw truncate long files. Shorter files cost less on every run.",[411,1308,1310],{"id":1309},"how-do-teams-share-agentsmd-across-repos","How do teams share AGENTS.md across repos?",[15,1312,1313,1314,1316],{},"Start new repos from a template and add a CI check that the file exists, stays under your line limit and that CLAUDE.md imports it. For Claude Code, deploy organisation-wide guidance as a managed CLAUDE.md or the ",[61,1315,786],{}," key in managed-settings.json. Ship shared skills and hooks as plugins from a team marketplace.",[411,1318,1320],{"id":1319},"does-codex-read-claudemd","Does Codex read CLAUDE.md?",[15,1322,1323,1324,1264,1326,1329],{},"Not by default. Codex reads AGENTS.override.md and AGENTS.md, plus any names you add to ",[61,1325,224],{},[61,1327,1328],{},"~/.codex/config.toml",", and it uses at most one file per directory. Keep shared rules in AGENTS.md so Codex sees them without extra setup.",[1331,1332,1333],"style",{},"html pre.shiki code .sgsFI, html code.shiki .sgsFI{--shiki-default:#24292E}html pre.shiki code .surfw, html code.shiki .surfw{--shiki-default:#005CC5;--shiki-default-font-weight:bold}html pre.shiki code .sYu0t, html code.shiki .sYu0t{--shiki-default:#005CC5}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html pre.shiki code .s7eDp, html code.shiki .s7eDp{--shiki-default:#6F42C1}html pre.shiki code .sYBdl, html code.shiki .sYBdl{--shiki-default:#032F62}html pre.shiki code .sD7c4, html code.shiki .sD7c4{--shiki-default:#D73A49}",{"title":502,"searchDepth":516,"depth":516,"links":1335},[1336,1337,1338,1344,1350,1356,1357,1363,1364,1365,1366],{"id":125,"depth":516,"text":126},{"id":148,"depth":516,"text":149},{"id":405,"depth":516,"text":406,"children":1339},[1340,1341,1342,1343],{"id":413,"depth":523,"text":414},{"id":429,"depth":523,"text":170},{"id":442,"depth":523,"text":443},{"id":471,"depth":523,"text":472},{"id":484,"depth":516,"text":485,"children":1345},[1346,1347,1348,1349],{"id":491,"depth":523,"text":492},{"id":555,"depth":523,"text":556},{"id":595,"depth":523,"text":596},{"id":605,"depth":523,"text":606},{"id":615,"depth":516,"text":616,"children":1351},[1352,1353,1354,1355],{"id":622,"depth":523,"text":623},{"id":637,"depth":523,"text":638},{"id":647,"depth":523,"text":648},{"id":670,"depth":523,"text":671},{"id":677,"depth":516,"text":678},{"id":760,"depth":516,"text":761,"children":1358},[1359,1360,1361,1362],{"id":767,"depth":523,"text":768},{"id":805,"depth":523,"text":806},{"id":881,"depth":523,"text":882},{"id":899,"depth":523,"text":900},{"id":1031,"depth":516,"text":1032},{"id":1200,"depth":516,"text":1201},{"id":1217,"depth":516,"text":1218},{"id":1242,"depth":516,"text":1243,"children":1367},[1368,1369,1370,1371,1372,1373,1374],{"id":1246,"depth":523,"text":1247},{"id":1256,"depth":523,"text":1257},{"id":1274,"depth":523,"text":1275},{"id":1288,"depth":523,"text":1289},{"id":1302,"depth":523,"text":1303},{"id":1309,"depth":523,"text":1310},{"id":1319,"depth":523,"text":1320},"Comparison","2026-11-10","CLAUDE.md vs AGENTS.md: which tools read which file, how to keep one source of truth with an import or symlink, and where skills.md and hooks fit.","md",false,"/img/blog/claude-md-vs-agents-md.jpg","CLAUDE.md vs AGENTS.md cover: a CLAUDE.md card holding one import line, with an arrow to an AGENTS.md card that holds the shared rules",512,1024,null,{},"/blog/claude-md-vs-agents-md","10 min read",{"title":5,"description":1377},"CLAUDE.md vs AGENTS.md: Which File Each Agent Reads","blog/claude-md-vs-agents-md",[1392,1393,1394,1395,1396,1397,1398],"claude.md vs agents.md","agents.md vs claude.md","does claude code read agents.md","symlink claude.md to agents.md","agents.md vs skills.md","agents.md vs copilot-instructions.md","claude.md import agents.md","tCZC0EdYgXeZ5S0TWrfadxj80d5q-tEYpoGEuF3eQAA",[1401,1411,1420],{"stem":1402,"title":1403,"description":1404,"date":1405,"image":1406,"category":1407,"redirected":1379,"author":1408,"readingTime":1410},"blog/claude-cowork-missing-hcs-services-perbaikan","Perbaikan Claude Cowork \"Missing HCS Services (hns, vmcompute, vfpext)\" (2026)","Perbaiki Claude Cowork di Windows: bug update Windows September 2026, \"missing HCS services: hns, vmcompute, vfpext\", tab abu-abu, dan gagal dimuat.","2026-11-04","/img/blog/claude-cowork-missing-hcs-services-perbaikan.jpg","Troubleshooting",{"name":7,"role":8,"avatar":9,"url":1409,"bio":10},"https://www.betterclaw.io/about","14 menit membaca",{"stem":1412,"title":1413,"description":1414,"date":1415,"image":1416,"category":1417,"redirected":1379,"author":1418,"readingTime":1419},"blog/claude-skills-token-verbrauch-senken","Die besten Claude Skills gegen hohen Token-Verbrauch (2026): Caveman, RTK und 5 Methoden, die funktionieren","Caveman, RTK und claude-token-optimizer im Vergleich: Einsparung, Installation und 5 Methoden, die eine Claude-Rechnung von $304 auf $56 im Monat senken.","2026-11-03","/img/blog/claude-skills-token-verbrauch-senken.jpg","Guides",{"name":7,"role":8,"avatar":9,"url":1409,"bio":10},"14 Min. Lesezeit",{"stem":1421,"title":1422,"description":1423,"date":1424,"image":1425,"category":1407,"redirected":1379,"author":1426,"readingTime":1427},"blog/claude-cowork-missing-hcs-services-correcao","Correção de \"Missing HCS Services (hns, vmcompute, vfpext)\" no Claude Cowork (2026)","Corrija o Claude Cowork no Windows: bug da atualização de setembro de 2026, \"missing HCS services: hns, vmcompute, vfpext\", aba cinza e falha ao carregar.","2026-10-29","/img/blog/claude-cowork-missing-hcs-services-pt.jpg",{"name":7,"role":8,"avatar":9,"url":1409,"bio":10},"14 min de leitura",1794321819045]