AGENTS.md ці CLAUDE.md? Што насамрэч ляжыць у 592 топавых рэпазіторыях

Практычныя рэкамендацыі Anthropic па працэсе разработкі програмнага забаву, адаптаваныя для AI, перакраяваюць усе шасць стадзій выдавання програмнага забаву навакола кодавальных агентоў. На трэцій стадзіі выкалічваецца адна конкрэтная дастатковасць — CLAUDE.md, файл з ведамасцю на рэпазітары, які адчыняецца па кожны раз, калі агент павтарыў тую ж самую памылку. Апытака найбольш падпісаных публічных рэпазітароў паказвала, насколькі з гэтых рэкамендацый практыкуецца на практыцы, і адказ ўсё ж здзівляе. CLAUDE.md мае перавагу па колькасці файлоў, але прасядзе па ўместнасці контэнту.

Ключовыя цыфры

8 септэбра 2026 года апытака прабавалася ў 592 найбольш падпісаных рэпазітарах, выбраных з шасцях класыфікацый языкоў (TypeScript, Python, Go, Rust, Java і JavaScript, без дуплікацый). У яе была пашук CLAUDE.md і калькі суседніх файлоў.

• 165 рэпазітароў (27,9%) маюць CLAUDE.md.
• У 94 з гэтых 165 рэпазітароў (57,0%) зовсім няма ведамасці пра рэпазітары — яны ўсе ў фармаце перыядрыкаў.

• Сярэд тых 165, 94 (57.0%) не маюць жодныххаведынгіў пра рэпазытары. яны ёсць перадывы.
• 209 рэпазытараў, 35.3%, мячыць файл AGENTS.md, і 93.8% з іх мячыць рэальныконтэнт.
• У 132 рэпазытарах, дзе ісцяці обабяваець файлы, 89% з іх мячыць CLAUDE.md. Толькі 10% мячыць файлы іншым бакам.
• Толькі 5.9% мячыць .claude/settings.json — тут прывязваецца стэгі плейбукса.
• Фярлікі CLAUDE.md мячыць сярэзны розмязджысьці 3,934 байтаў, а найбольшыя — 66,176 байтаў.

Для тых, хто зараз адаптуюўся да гэтага плану дзеяння, вывыкі ёсць сумешанымі. Агентам дэйсна патрэбны файлы з ведамасцю, створаныя з адпаведнаю відпаведальнасцю і пад керуванням версіяма, пры тым у плане дзеяння названы не тыя файлы. У всіх гэтых рэпазітарыях CLAUDE.md стаў свайго роду проміжным файлам для сумеснасці, які знаходзіцца раней AGENTS.md — файлам, нейтральным па відношэнню да віробніка, які чытаецца кожным з основных кодавальных агентоў. Праекты, які ужо рашылі гэту проблему, запісалі свою ведамасць аднойчы ў AGENTS.md і залішылі пасля сябе аднай-радковы паказчык.

Як была здзейснена підрахунок

Фрэйм для адзінкавання складаўся з карточак рангавання на GitHub, тыя 100 найбольш популярных рэпазітарыёў за канцантамі ў кожнай з шасцях мов, якія пасля адзінкавання сталі 592 унікальных рэпазітарыёў. Была запрошана фіксаваная сетка падзеяў з сайту raw.githubusercontent.com, без API-клуча, без аутантыкаціі і без скрапінгу. Пытанне заключалася толькі ў тым, чы гэты файл існуе і што ён містыць. Пасля чаго былі завантажаны всі кантэнты файлаў CLAUDE.md і AGENTS.md — 374 файлы з 242 рэпазітарыёў — і прачытаны вручную.

Саме пад час прачытання выявілася проблема. Медыянная дужнасць файла CLAUDE.md выявілася двухрадковай, таму 27,9% сама па сабе майжэ нічога не значыць.

Што змяшчаюць гэтыя файлы

Ні адна з распашчатых формаў не ёсць справжнімі знаннямі:

• Сіндыкат гіта. Файл мае размах дзевяць байтаў — цэльва тэкст AGENTS.md без завершальнага сімвола новай лініі, адколькі гіт зберагае сіндыкат у вачынку, які містыць яго цэль. Прыкладамі ўсьмішаюцца openclaw, dify, ant-design, moby, home-assistant, superset, Stirling-PDF і nushell.
• Адна лінія імпорту, @AGENTS.md, размахам адзеўнаць байтаў, яку Claude Code аналізуе пад час завантажэння. n8n, supabase, grafana, nuxt, storybook, prometheus, traefik, ruff і pdf.js працуюць такім жа спосабам.
• Адна рэчыца прозы. У lazygit гэта выражаецца як інструкцыя прачытаць спачатку AGENTS.md і даследаваць яе правілы. CLI-інструменты Google Workspace кажуць тое ж, але болей дакладна.

Дзеяныя некалькі спецыяльных случаў маюць значэнне для кожнага, хто стварае класыфікатор. У Docusaurus ёсць загалоўны пункт, за якім следуе імпорт, і больш нічога. Jest звяртаецца да .github/copilot-instructions.md. Ansible складаецца з трохох ліній імпорту без прозы. Zed стварае сімвалінкі на файл пад назвай .rules.

Пасля адключэння ўсіх файлаў, якія маюць як ўжо толькі перэнаправленне, у 71 з 592 рэпазітарыяў ёсць CLAUDE.md, які містыць інформацыю пра рэпазітарый, тое ў 12,0%. Гэтыя 71 рэпазітарыя ёсць рэальнымі, дзеяныя з іх вялікія: медыяннае значэнне — 3 934 байты, 90-е перцентыль — 19 506, максімум — 66 176. Праекты такія як bun, pytorch, swc, gstack і 3x-ui падтрымліваюць справжнія інструкцыі з аператыўнага керавання, якія паводзяцца пра команды пабудовы, карты рэпазітарыяў, філасофію тэставання і правіла, дзеяныя на рэгістроўых дырэктарыях.

Дзе насправды знаходзіцца гэтая інформацыя

У файле AGENTS.md розкішная перапраўка. Яго фактычны паракцэнт станавіць 93,8%, тое ў 196 з 209 файлаў, проты 43,0% у файле CLAUDE.md. Гэтая асіметрыя і ёсць ключовым моментам. Рэпазітарый, які стварае файл AGENTS.md, практычна завжды заповнюе яго контэнтам. Рэпазітарый, які стварае файл CLAUDE.md, часта проста створуе «мост» да іншага месца.

132 рэпазітарыя, які маюць оба файлы, чыста паказваюць гэты направленні:

• У 89 з іх файл CLAUDE.md ёсць вказывальнік, а файл AGENTS.md мае фактычны контэнт.
• У 10 вароты ролей зміненыя: файл AGENTS.md выканае перапраўку, а файл CLAUDE.md ёсць справжнім файлам. До іх належаюць Pytorch, bun, milvus, anki і litellm.
• У 31 рэпазітарыі фактычны контэнт зберагаецца ў обох файлах, тое самы інстытуцыйны кантэнт падтрымваецца два разы.
• У 2 рэпазітарыях ёсць вказывальнікі ў обох файлах, што значыць, што дзе-небудзь існуе трэці файл.

Таму перадзваненні працуюць прыбліжна у спявазе дзевяць да аднаго ў баку файлу, нейтральнага да прадавцоў. Однонаправлены рэзультат часта ёсць наследкам паказніка меры, таму спецыяльна шукалася працоўная сітуацыя, працоўная працэсам. Яна існуе, але толькі як меньшасць.

Іспытанне па мовам

Разлік межы моваў дастаткова вялік, каб можна было планаваць. Спачатку CLAUDE.md, потым AGENTS.md:

• TypeScript: 46,5% і 53,5%.
• Rust: 33,3% і 43,4%.
• Go: 32,3% і 37,4%.
• Python: 25,5% і 31,6%.
• JavaScript: 19,0% і 23,0%.
• Java: 10,3% і 22,7%.

Файл AGENTS.md ўсюды ў першасце. У Java спостаткуе найбольшыя разлікі: у рэпазітарыях з AGENTS.md ў два разы больш шансоў, чым з CLAUDE.md, а у праектах на TypeScript шансы на наявнасць CLAUDE.md у чатыры разы вышэй, чым у Java-праектах. У всіх шасці мов 43,2% лепшых рэпазітарыяў маюць які-небудзь файл з інструкцыямі для агента — будзь то AGENTS.md, CLAUDE.md, .cursorrules чы файл інструкцыяў Copilot. Файл Copilot прыналежыць 9,3% рэпазітарыяў. Стандарт .cursorrules практычна знік у гэтай групе — толькі 0,5%, што ўсёлякі прыклад таго, як быстра можа знікнуць прычыпленасць да спецыфічных рашэнняў прадаўца.

Рэшта комплекту Stage-3

Команды, якія працуюць з платформамі, должны атрымліваць гэты частаку адзін у адзін. У плане дзейнасці трэба не толькі файлы з ведамасцю: ён аб’яднае файлы з ведамасцю, навыкі і хукі, пры чым хукі ўжо являюцься слойам контролю, які запобегае небяспечным дзеянням пад час стварэння.

Толькі 35 з 592 рэпазітарыяў (5,9%) маюць файл .claude/settings.json, а толькі 32 (5,4%) — яго разам з файлам CLAUDE.md. Дакументацыя, якая ўособліваеся простам файлам, які можа напісаць кожны, і ўжо стала популярной. Слой прымусовага адканалення, які фактычна вялічыць тое, што можа робіць агент, існуе толькі прыблізна ў адным рэпазітарыяве з вісімнадцатых. План дзейнасці, безпека якога залежыць ад спецыяльных элементаў, опісвае ўсё тое, што практычна ніхто яшчо не створыў.

Меры дадзеных

• Адбірка включае публічныя рэпазітарыяў, распакаваныя па колькасці звёзд. Падобныя планы дзейнасці выкорыстоўваюцца ў прыватных корпаратывных рэпазітарыях, якія не ёсць доступнымі для перагляду. Іх адыябраўнасць там можа быць вышэй і болей адгукнутай.
• Гэта простае адбіранне дадзеных, зробленае на стане HEAD 8 септэбра 2026 года. Адыябраўнасць развіваецца быстра, таму за месач час практычна ўсе пацэнтажы буду некарэктныя, і напрамак развіцця мае большое значэнне, чым ўжо існуючы рывень.

Файл — гэта не практыка. Файл CLAUDE.md сам по сабе паказвае толькі тое, што хтось яго напісаў. Ён не дае жадных доказоў таго, што хтось яго падтрымлівае чы ўжо робіцца крашчэя якосць выходу агента. Опублікованыя працы ставяць пад сумнев, чы гэтыя файлы ваобшча дапамагаюць агентам для кодавання, і гэты показнік нічога пра гэта не кажа.

Файл settings.json ёсць заменнікам для хуков, а не статыстычным дадзенням. Усі хукі, заданыя ў іншых месцах, застаюць непазірнымі, таму 5,9% — гэта мінімум.

Адміністрацыя можа сама адначасна выбieraць, які элементы лічыцца паказчыкамі, а які — сутэйнымі часткамі тэксту. Праграма выкарыстоўвала 120 сімваў залішковага тэксту пасля адзьёмленая загалоўкаў, імпортаваных элементаў і рэкерсіяў. Чырнаццаць файлаў, якія знаходзіліся найбліжэй да гэтага праграматы, былі пераглянуты ручна, і найбліжэйшы сутэйны файл, lazydocker, мае 172 сімволаў рэальных флагаў для складання. Змена праграмы зменяе і гэтыя цыфры. Другія перагляды 25 рэпазітарыёў у супараванні з фактычнымі файламі паказалі, што адхыленні ўсталяваныя ў адной напрамоў: класіфікатор часам прызнае рэкерсію сутэйной часткаю, калі гэтая рэкерсія выражаецца як інструкцыя для агента, а не як пазначэнне месца розташоўвання дакументацыі, як у прыкладзе zeroclaw. Таму 57,0% — гэта мінімум, а рэальны падзел на паказчыкі і сутэйныя часткі ўсё-такі вышы.

Існуе таксама прыграда, якую варта ўзнайсці. У першым аналізе было зазначана, што 27,9% ведучых рэпазітарыёў выкарыстоўвалі CLAUDE.md, і гэтыя даны мелі бы быць опублікованы. Адно ўсё спявалося з тым, што было выкарыстоўваецца двухрадковае медыяна.

Практычныя рашэнні

У камплекце з якога файла трэба размістыць кантэнт? Даныя падтрымліваюць варыянт AGENTS.md, пры чым CLAUDE.md стае толькі паказывачам. Большасць рэпазітарыёў з двума файламі (89 з 132) робяць самэ гэта. Адна копія знання застаецца, і агенты, якія ніколі не шукаюць файл пад конкрэтным назвам Claude, все равно можаць яго прачытаць.

Чы рэдзе Claude Code файл AGENTS.md безпосерэдна? Не за дапамою названня, на адміністрацыю з CLAUDE.md, і самэ гэта разлік являе сабо прычыну існавання шаблона паказчыка. У практыцы працуюць два спосабы: гіт-сіндык, названы CLAUDE.md, які вядомае да AGENTS.md, або імпорт @AGENTS.md. У праекце new-api нават паведамляе ў своем CLAUDE.md, што імпорт не завжды працюе надзеямо, і радзіць агенту ачыць файл самаму.

Чы 27,9% адопцыі — гэта добра чы паслаба? Лепша, чым чакалося для такога моладога стандарта, але горша, чым паводзіцца з выкладкамі. Іншыя два показнікі гавораюць больш: 12,0% рэпазітарыяў маюць файлы CLAUDE.md з рэальным контэнтам, а толькі 5,4% аднае іх з хукамі для адканаўлення.

Чаму 31 рэпазітарыя заставляець зберагаць оба файлы? Разлік между копіямі ніколі не вімервалі, і гэта ясны наступны направленні даследжэння. Двойная інстытуцыйна інфармацыя стае прычыной проблем, калі копіі не састаюцца, а інструменты не даюць жадных паведамленняў.

Можа кто-небудзь іншы павтарыць гэта? Так. Адзінакі прыклад бераецца з публічнага рангавання зорак, запыт — гэта простыя неаутэнтыфікованыя HTTP-запыты да raw.githubusercontent.com, а класыфікатор запаўнюе прыблізна 40 ліній.

Апошняя перапаконтка для тых, хто адрабатвае рэпазітарыю з прыўязаным агентам для кодавання: калі ўпершыню змяніўся запыт да складання, чы змяніліся файлы з інфармацыяй агента ў той жа коміт, чы стары запыт з’явіўся праз тры сесіі?