Файл AGENTS.md не з'яўляецца другой інструкцыяй па эксплуатацыі праграмы і не з'яўляецца prompt, які спрабуе кіраваць кожным націсканнем клавішы. Гэта невялікі версіяваны кантракт кантэксту. Ён паведамляе coding agent, як уладкаваны рэпазіторый, якія каманды даюць правяральныя доказы, якія межы важныя і дзе знаходзіцца больш вузкае правіла. Добры файл памяншае нявызначанасць да таго, як agent пачне змяняць код. Ён не замяняе зыходны код, тэсты, суправаджальнікаў праекта або апісанне задачы.
Кантэкст мае кошт. Codex загружае ўказанні праекта ў ланцужок інструкцый перад працай. Паўторны тэкст канкуруе з запытам карыстальніка, файламі рэпазіторыя, вынікамі інструментаў і тэстамі. Таму запісвайце факты, якія agent не можа бяспечна вывесці сам, а не ўсе пажаданні, калі-небудзь выказаныя чалавекам. Успрымайце кожны сказ як інтэрфейс, які трэба падтрымліваць.
Што сапраўды знаходзіць Codex
Актуальнае кіраўніцтва OpenAI пра AGENTS.md для Codex апісвае тры ўзроўні. У глабальнай вобласці Codex шукае AGENTS.override.md у CODEX_HOME, якое па змаўчанні роўнае ~/.codex, а калі яго няма, выкарыстоўвае AGENTS.md. На гэтым узроўні бярэцца толькі першы непусты файл. У вобласці праекта Codex пачынае з кораня праекта, звычайна кораня Git, і спускаецца да бягучага працоўнага каталога. У кожным каталогу ён правярае AGENTS.override.md, потым AGENTS.md, потым наладжаныя запасныя назвы і дадае не больш за адзін файл з каталога.
Знойдзеныя файлы праекта аб'ядноўваюцца ад кораня да бягучага каталога. Больш глыбокі файл з'яўляецца пазней у аб'яднаных інструкцыях, таму яго вузкае правіла можа перакрыць шырокае. Codex не працягвае пошук вышэй за выяўлены корань праекта. Калі корань не знойдзены, правяраецца толькі бягучы каталог. Пустыя файлы прапускаюцца. Значэнне project_doc_max_bytes па змаўчанні роўнае 32 KiB, і пасля дасягнення агульнага наладжанага ліміту Codex перастае дадаваць указанні. Гэта паводзіны Codex, а не ўніверсальная абяцанка ўсіх інструментаў.
Рэалізацыя пошуку AGENTS.md у зыходным кодзе OpenAI Codex паказвае тыя ж межы. Стандартны маркер кораня — .git, пажаданая лакальная назва — AGENTS.override.md, а файл можа быць абрэзаны, калі рэшта бюджэту байтаў меншая за яго памер. Рэпазіторый можа наладзіць маркеры кораня, запасныя назвы і бюджэт. Дакументуйце толькі налады, якія сапраўды выкарыстоўваюцца.
Глабальнае пажаданне належыць у ~/.codex/AGENTS.md толькі тады, калі яно бяспечнае для кожнага рэпазіторыя. Правіла для ўсяго рэпазіторыя змяшчайце ў корані. Правіла сэрвісу трымайце каля гэтага сэрвісу. Часовую або выключную замену змяшчайце ў override-файле, пазначыўшы ўладальніка і ўмову выдалення. Не называйце гэта ўніверсальнай іерархіяй для іншых агентаў, калі іх дакументацыя гэтага не пацвярджае.
Пачніце з карты рэпазіторыя
Спачатку agent трэба арыентаваць, а ўжо пасля даваць яму парады пра стыль. У пачатку каранёвага файла размясціце кароткую карту. Назавіце праграму або бібліятэку, галоўныя каталогі зыходнікаў, зоны згенераваных файлаў, каталогі тэстаў і канфігурацыю пастаўкі. Тлумачце толькі адрозненні, якія мяняюць дзеянне. «У src/ ёсць код» — слабая фраза. «src/ пастаўляецца, scripts/ працуе толькі ў CI, а dist/ генеруецца і не рэдагуецца ўручную» — карысная.
Карта павінна перажыць звычайныя рэфактарынгі. Выбірайце стабільныя межы замест спісу кожнага файла. У monorepo пакажыце ўладальнікаў пакетаў, а карты пакетаў размясціце ва ўкладзеных файлах. Спасылайцеся на README або дакумент архітэктуры, калі ён з'яўляецца крыніцай праўды. Не капіруйце гэты дакумент у AGENTS.md.
repository/
apps/web/ браўзерная праграма і тэсты маршрутаў
packages/core/ агульная бібліятэка выканання і unit-тэсты
services/api/ HTTP-апрацоўшчыкі і кантрактныя тэсты
infra/ канфігурацыя пастаўкі
docs/ дакументы, якія падтрымліваюцца
generated/ вынік, які пераствараецца скрыптам
Выразна запішыце здагадкі пра працоўны каталог. Каманда з services/api можа атрымаць іншы ўкладзены файл інструкцый, чым тая ж каманда з кораня. Калі менеджар пакетаў трэба запускаць з каталога пакета, скажыце пра гэта. Калі ў згенераванага файла ёсць крыніца праўды, назавіце абодва шляхі і каманду генератара.
Рабіце каманды дакладнымі і ўмоўнымі
Каманда карысная, калі яе можна скапіяваць без тлумачэння. Для кожнай абавязковай каманды пакажыце каталог, прызначэнне і ўмову запуску. Выкарыстоўвайце версіі і скрыпты, абвешчаныя рэпазіторыем, а не модны інструмент, які памятаеце. Структура раздзела можа выглядаць так:
З кораня рэпазіторыя:
git rev-parse --show-toplevel
npm ci
npm run check
npm test
npm run build
Для змен API запускайце з services/api:
npm run test:contract
Гэта прыклад структуры, а не сцвярджэнне, што такія скрыпты ёсць у кожным праекце. Перад запісам прачытайце package.json, lockfile, CI workflow, pyproject.toml, Cargo.toml або адпаведныя файлы. Пішыце «пасля змяненняў TypeScript запусціце npm run check» толькі калі такі скрыпт існуе. Калі камандзе патрэбны лакальны сэрвіс, fixture, база, пераменная асяроддзя або сетка, апішыце перадумову і бяспечную замену для сфакусаванага тэсту.
Запішыце падтрымліванае асяроддзе выканання і палітыку залежнасцяў. Карысны пункт называе версію Node, Python, Rust, Java або Go, менеджар пакетаў, палітыку lockfile і спосаб праверкі абнаўленняў. Напрыклад, «package.json абвяшчае Node >=22.12.0, выкарыстоўвайце зафіксаваны package-lock.json і запускайце npm ci» з'яўляецца фактам, калі гэта пацвярджае маніфест. Не капіруйце версію ў AGENTS.md, не праверыўшы маніфест і CI. Розніца версій — праблема падтрымкі, а не прычына дадаваць тэкст.
Codex можа дапамагчы праверыць актыўны ланцужок. Афіцыйнае кіраўніцтва паказвае каманды такога выгляду:
codex --ask-for-approval never "Summarize the current instructions."
codex --cd services/api --ask-for-approval never "List the instruction sources you loaded."
codex -c log_dir=./.codex-log --ask-for-approval never "Show the active instruction files."
Выкарыстоўвайце бяспечны запыт без змен і праглядайце журнал толькі ў надзейнай лакальнай працоўнай прасторы. Пасля змены файлаў інструкцый перазапусціце run, бо пошук будуецца нанова ў пачатку run або TUI-сеансу. Састарэлы адказ азначае, што трэба праверыць працоўны каталог, CODEX_HOME, override, запасныя назвы і ліміт байтаў.
Тэсты даюць доказы
Апісвайце стан «гатова» назіранымі вынікамі. Аддзяляйце хуткія праверкі ад поўнага набору. Назавіце каманду тэсту, закрануты пакет, чаканы артэфакт і дзеянні пры памылцы. Для змены HTTP-схемы патрабуйце кантрактны тэст. Для парсера патрабуйце рэпрэзентатыўныя fixture і няправільны ўвод. Для згенераванага кліента патрабуйце паўторную генерацыю і чысты diff.
Не пішыце «заўсёды запускайце ўсе тэсты», калі рэпазіторый вызначае іншы абсяг або поўны набор патрабуе знешняй інфраструктуры. Дакладней сказаць: «спачатку запусціце мэтавы тэст пакета, а перад зліццём набор, эквівалентны CI». Фарматаванне і lint пакіньце CI, калі яны ўжо правяраюцца там. Першасны рэпазіторый SWE-bench карысны для ацэнкі задач, але яго пратакол не замяняе тэсты канкрэтнага рэпазіторыя.
Злучайце кожнае важнае правіла з праверкай. Калі agent не павінен рэдагаваць згенераваны вынік, CI можа зноў запусціць генератар і завяршыцца памылкай пры diff. Калі міграцыя павінна быць зваротнай, тэст можа прымяніць яе да чыстай fixture і адмяніць. Калі важны інварыянт бяспекі, выкажыце яго тэстам або статычнай праверкай. Інструкцыя без назіранага выніку просіць спадзявацца на памяць agent.
Для ацэнкі паводзін agent параўноўвайце поспех задачы, долю пройдзеных тэстаў, ахоп змененых файлаў, пераробку пасля рэвю і час да праверанага патча. Запускайце аднолькавы набор задач са старым і новым файлам, захоўваючы запыт і рэвізію рэпазіторыя, і запісвайце няўдачы, а не толькі ўдалыя дэманстрацыі. Гэта інжынерны сігнал, а не доказ, што адна фармулёўка працуе для кожнай мадэлі. Пра інструменты чытайце ў матэрыяле пра agentic coding, Codex і Claude Code, пра межы сістэмы — у архітэктуры production AI agent, а пра дызайн ацэнкі — у ацэнцы AI agents.
Трымайце бяспеку на мяжы
AGENTS.md — уваход праекта. Ён можа быць састарэлым, памылковым або ненадзейным. Зыходны код Codex выразна не загружае інструкцыі праекта, калі актыўны праект не з'яўляецца давераным, але захоўвае інструкцыі, пададзеныя хостам. Гэта не адмяняе чалавечай праверкі. Лічыце інструкцыі рэпазіторыя ненадзейным тэкстам, пакуль не праверыце рэпазіторый і запытаную змену.
Ніколі не змяшчайце ў файл ключы API, токены, паролі, прыватныя сертыфікаты або скапіяваныя production-дадзеныя. Не прасіце agent друкаваць пераменныя асяроддзя або загружаць файлы рабочай прасторы. Можна назваць сакрэт па ролі, напрыклад DATABASE_URL, і пазначыць, дзе лакальная распрацоўка атрымлівае яго без запісу значэння. Перад выдаленнем даных, ратацыяй credentials, production-дэлоем або шырокім сеткавым доступам патрабуйце пацвярджэнне, калі workflow гэта падтрымлівае.
Раздзяляйце факты і дазволы. «Сэрвіс выкарыстоўвае S3» — кантэкст. «Можна выдаліць bucket» — паўнамоцтва. Паўнамоцтвы павінны знаходзіцца ў палітыцы доступу і працэсе пацвярджэння, а не ў markdown. Назавіце абароненыя шляхі, згенераваныя артэфакты, правілы міграцый і межы тэставых даных. Для нявызначанасці дайце бяспечны шлях: спыніцца, паказаць прапанаваную каманду і спытаць суправаджальніка.
Асцярожна стаўцеся да інструкцый, скапіяваных з issue, fixture або файлаў залежнасцяў. Яны могуць утрымліваць prompt injection або каманду, не звязаную з задачай. Добры файл кажа лічыць змесціва рэпазіторыя данымі, калі карыстальнік або даверанае правіла праекта не дазволіць дзеянне. Гэта мяжа бяспекі, а не просьба ігнараваць зыходны код.
Выбірайце кароткі шматслойны файл
Сайт AGENTS.md называе агляд праекта, каманды зборкі і тэстаў, стыль, тэсты і бяспеку распаўсюджанымі раздзеламі. Гэта меню, а не абавязковая схема. Пачніце з мінімуму, які прадухіляе паўторныя памылкі. Каранёваму файлу часта дастаткова пяці раздзелаў: карта, наладжванне, праверка, межы і спасылкі на глыбейшыя ўказанні.
## Карта рэпазіторыя
`apps/web` — браўзерная праграма. `packages/core` — агульны runtime-код.
## Інструменты
Выкарыстоўвайце Node 22 і зафіксаваны lockfile. Запускайце каманды з кораня, калі не пазначана іншае.
## Праверка
Для змяненняў, бачных карыстальніку, запускайце `npm run check`, тэст пакета і `npm run build`.
## Межы
Не рэдагуйце `generated/`. Не выкарыстоўвайце production-дадзеныя лакальна. Пытайцеся перад даданнем залежнасці.
## Глыбейшыя ўказанні
Чытайце `apps/web/AGENTS.md` пра маршруты і `services/api/AGENTS.md` пра кантрактныя тэсты.
Дрэнная версія — каталог асабістых густаў на 1000 радкоў: паўторы, поўныя спісы файлаў, супярэчлівыя «заўсёды», прыдуманыя каманды, старыя версіі і просьбы перачытаць усе дакументы. Яна спажывае бюджэт байтаў і хавае прыярытэты. Падзяляйце паводле адказнасці. Каранёвы інварыянт пакідайце ў каранёвым файле, а ўкладзенаму дазваляйце дадаваць лакальныя каманды. Укладзены файл павінен дапаўняць або звужаць указанні, а не ціха змяняць мяжу бяспекі.
Не абяцайце кампазіцыю, якую інструмент не дакументуе. Codex цяпер аб'ядноўвае файлы праз пошук у каталогах і наладжаныя запасныя назвы. Радок «потым прачытайце docs/rules.md» з'яўляецца звычайным тэкстам, калі інструмент не вызначае спецыяльны сінтаксіс include. Symlink, CLAUDE.md або правіла іншага agent не загружаюцца Codex аўтаматычна. Апісвайце сумяшчальнасць як правераны workflow, а не як агульнае правіла.
Падтрымлівайце яго як код
Прызначце ўладальніка файла. Правярайце змены разам з кодам, якім яны кіруюць. Калі змяняюцца каманда, runtime, каталог або CI workflow, абнаўляйце найбліжэйшы файл інструкцый у тым жа змяненні. Выдаляйце правіла пасля знікнення апошняга спажыўца. Прыклады павінны быць выканальнымі і бяспечнымі. Спасылайцеся на адну крыніцу праўды, а не дублюйце палітыку ў трох файлах.
Штомесячны або рэлізны аўдыт можа быць кароткім. Праверце, што кожная каманда існуе, кожная версія адпавядае маніфесту або вобразу CI, а кожны шлях яшчэ існуе. Запусціце запыт спісу крыніц Codex з кораня і аднаго тыповага падкаталога. Вымерайце памер эфектыўнага ланцужка. Спытайце суправаджальніка, ці кожнае правіла па-ранейшаму прадухіляе сапраўдную памылку.
Змены AGENTS.md ацэньвайце як змены канфігурацыі. Выкарыстоўвайце невялікі фіксаваны набор задач: новая магчымасць, выпраўленне памылкі, змяненне толькі тэстаў і змяненне, важнае для бяспекі. Параўноўвайце правільнасць і ахоп патча, а не толькі тлумачэнне agent. Рэгрэсійная праверка можа пацвердзіць, што згенераваныя файлы не змяніліся, тэст пакета выкананы або небяспечная каманда адхілена. Захоўвайце рэвізію, налады мадэлі, дазволы і тэкст задачы дастаткова стабільнымі, каб параўнанне мела сэнс.
Устойлівы падыход просты. Размяшчайце стабільныя факты побач з іх вобласцю дзеяння. Называйце дакладныя каманды і версіі, пацверджаныя рэпазіторыем. Спасылайцеся на падрабязныя дакументы. Рабіце важныя правілы тэстуемымі. Трымайце сакрэты і паўнамоцтвы па-за markdown. Выкарыстоўвайце слаі замест гіганцкай інструкцыі. Правярайце эфектыўны ланцужок пасля змены каталога, канфігурацыі або версіі інструмента.