AGENTS.md файлы қолданбаның екінші пайдалану нұсқаулығы емес және әрбір пернені басуды басқаруға тырысатын prompt емес. Бұл нұсқамен бірге сақталатын шағын контекст келісімі. Ол coding agent-ке репозиторийдің қалай құрылғанын, қандай командалар тексерілетін дәлел беретінін, қандай шекаралар маңызды екенін және нақтырақ ереже қайда орналасқанын айтады. Жақсы файл agent кодты өзгертпей тұрып белгісіздікті азайтады. Ол бастапқы кодты, тесттерді, жоба иелерін немесе тапсырма сипаттамасын алмастырмайды.
Контекстің құны бар. Codex жұмыс басталғанда жоба нұсқауларын нұсқаулар тізбегіне жүктейді. Қайталанатын мәтін пайдаланушы сұрауымен, репозиторий файлдарымен, құралдар нәтижесімен және тесттермен бәсекелеседі. Сондықтан agent қауіпсіз түрде шығара алмайтын фактілерді жазыңыз, бұрын біреу айтқан барлық қалауды емес. Әр сөйлемді күтімді қажет ететін интерфейс деп қараңыз.
Codex нақты нені табады
OpenAI компаниясының Codex үшін AGENTS.md жөніндегі қазіргі нұсқаулығы үш деңгейді сипаттайды. Ғаламдық ауқымда Codex CODEX_HOME ішінде AGENTS.override.md файлын іздейді, оның әдепкі орны ~/.codex, ал ол болмаса AGENTS.md қолданылады. Бұл деңгейде бірінші бос емес файл ғана алынады. Жоба ауқымында Codex жоба түбірінен, әдетте Git түбірінен, ағымдағы жұмыс бумасына дейін төмен түседі. Әр бумада ол AGENTS.override.md, содан кейін AGENTS.md, одан кейін конфигурацияланған қосалқы атауларды тексереді және әр бумадан ең көбі бір файл қосады.
Табылған жоба файлдары түбірден ағымдағы бумаға қарай жалғанады. Тереңірек файл біріктірілген нұсқауларда кейінірек келеді, сондықтан оның тар ережесі кең ережені ауыстыра алады. Codex анықталған жоба түбірінен жоғары қарай іздеуді жалғастырмайды. Түбір табылмаса, тек ағымдағы бума тексеріледі. Бос файлдар өткізіледі. project_doc_max_bytes әдепкі бойынша 32 KiB, ал жалпы шекке жеткенде Codex жоба нұсқауларын қосуды тоқтатады. Бұл Codex-тің мінез-құлқы, барлық құралдарға ортақ уәде емес.
OpenAI Codex бастапқы кодындағы AGENTS.md табу іске асыруы сол шекараларды көрсетеді. Әдепкі түбір белгісі — .git, қалаулы жергілікті атау — AGENTS.override.md, ал қалған байт бюджеті файл өлшемінен аз болса файл қысқартылуы мүмкін. Репозиторий түбір белгілерін, қосалқы атауларды және бюджетті баптай алады. Нақты қолданылатын баптауларды ғана құжаттаңыз.
Ғаламдық қалауды ~/.codex/AGENTS.md файлына барлық репозиторийге қауіпсіз болғанда ғана қойыңыз. Бүкіл репозиторийге ортақ ереже түбірде тұрады. Қызмет ережесі сол қызметтің жанында тұрады. Уақытша немесе ерекше ауыстыру иесі және жою шарты көрсетілген override файлында тұрады. Басқа agent құжаттамасы мұны растамаса, осыны барлық agent үшін әмбебап иерархия деп жазбаңыз.
Репозиторий картасынан бастаңыз
Стиль туралы кеңеске дейін 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 орындаңыз» дегені манифестпен расталса ғана факт. Манифест пен CI тексерілмей тұрып нұсқаны AGENTS.md ішіне көшірмеңіз. Нұсқа айырмашылығы — күтім мәселесі, мәтінді көбейтуге себеп емес.
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 схемасы өзгерсе, келісім тестін талап етіңіз. Parser өзгерсе, өкілдік fixture және қате енгізулерді талап етіңіз. Жасалған client өзгерсе, қайта генерацияны және таза diff-ті талап етіңіз.
Репозиторий басқа қамтуды анықтаса немесе толық жинаққа сыртқы инфрақұрылым керек болса, «әрқашан барлық тестті орындаңыз» деп жазбаңыз. Дұрысы: «алдымен мақсатты пакет тестін, содан кейін біріктіру алдында CI-ға тең жинақты орындаңыз». Formatting пен lint CI ішінде әлдеқашан орындалса, оларды сол жерге қалдырыңыз. SWE-bench бастапқы репозиторийі тапсырмалық бағалауға бастапқы дерек болады, бірақ нақты репозиторий тесттерін алмастырмайды.
Әр маңызды ережені тексеріспен байланыстырыңыз. Agent жасалған нәтижені өзгертпеуі керек болса, CI генераторды қайта іске қосып, diff болғанда қате қайтара алады. Migration қайтарымды болуы керек болса, тест оны таза fixture-ге қолданып, кейін кері қайтара алады. Қауіпсіздік инварианты маңызды болса, оны тест немесе статикалық тексеріс етіңіз. Бақыланатын нәтижесі жоқ нұсқау agent-тің жадына сенуді сұрайды.
Agent әрекетін бағалағанда тапсырма сәттілігін, тесттен өту үлесін, өзгерген файлдар ауқымын, ревьюден кейінгі қайта жұмысты және тексерілген patch-ке дейінгі уақытты салыстырыңыз. Ескі және жаңа файлмен бірдей тапсырмалар жинағын іске қосып, сұрау мен репозиторий ревизиясын тұрақты ұстаңыз және тек сәтті көрсетілімдерді емес, қателерді де жазыңыз. Бұл инженерлік белгі, бір тұжырым кез келген модельде жұмыс істейтініне дәлел емес. Құралдар контексті үшін agentic coding, Codex және Claude Code мақаласын, жүйе шекарасы үшін production AI agent архитектурасын оқыңыз, ал бағалау дизайны үшін AI agent бағалауын қараңыз.
Қауіпсіздікті шекарада ұстаңыз
AGENTS.md — жоба кірісі. Ол ескірген, қате немесе сенімсіз болуы мүмкін. Codex бастапқы коды белсенді жоба сенімсіз болғанда жоба нұсқауларын әдейі жүктемейді, бірақ host берген нұсқауларды сақтайды. Бұл адам тексерісін алып тастамайды. Репозиторийді және сұралған өзгерісті тексергенше, репозиторий нұсқауларын сенімсіз мәтін деп санаңыз.
Файлға API кілттерін, token-дерді, құпиясөздерді, жеке сертификаттарды немесе өндірістен көшірілген деректерді ешқашан салмаңыз. Agent-тен орта айнымалыларын басып шығаруды немесе жұмыс кеңістігіндегі файлдарды жүктеуді сұрамаңыз. Секретті рөлімен, мысалы DATABASE_URL деп атауға және жергілікті әзірлеу оның мәнін жазбай қалай алатынын түсіндіруге болады. Workflow қолдаса, дерек өшіру, credentials ротациясы, production deployment немесе кең желі рұқсаты алдында растау сұраңыз.
Факт пен рұқсатты ажыратыңыз. «Қызмет S3 пайдаланады» — контекст. «Bucket-ті жоюға болады» — өкілеттік. Өкілеттік markdown-да емес, қолжетімділік саясаты мен бекіту рәсімінде болуы керек. Қорғалған жолдарды, жасалған артефактілерді, migration ережелерін және тест деректерінің шекарасын жазыңыз. Белгісіздік кезінде қауіпсіз жол ұсыныңыз: тоқтау, ұсынылған команданы көрсету және иеден сұрау.
Issue, fixture немесе тәуелділік файлдарынан көшірілген нұсқауларға сақ болыңыз. Оларда prompt injection немесе тапсырмаға қатысы жоқ команда болуы мүмкін. Жақсы файл пайдаланушы немесе сенімді жоба ережесі әрекетке рұқсат бермесе, репозиторий мазмұнын дерек деп санауды айтады. Бұл қауіпсіздік шекарасы, бастапқы кодты елемеу туралы бұйрық емес.
Қысқа қабатты файлды таңдаңыз
AGENTS.md сайты жоба шолуын, build және тест командаларын, код стилін, тесттерді және қауіпсіздікті жиі кездесетін бөлімдер деп атайды. Бұл міндетті schema емес, таңдау мәзірі. Қайталанатын қателердің алдын алатын ең аз жиыннан бастаңыз. Түбір файлға көбіне бес бөлім жеткілікті: карта, баптау, тексеру, шекара және терең нұсқауларға сілтеме.
## Репозиторий картасы
`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 қазір файлдарды каталог табуы және бапталған қосалқы атаулар арқылы біріктіреді. Құрал арнайы include синтаксисін құжаттамаса, «келесіде docs/rules.md файлын оқыңыз» деген жол жай мәтін болып қалады. Symlink, CLAUDE.md немесе басқа agent ережесі Codex-ке автоматты түрде жүктелмейді. Өзара әрекеттесуді әмбебап ереже емес, тексерілген workflow ретінде жазыңыз.
Оны код сияқты күтіңіз
Файлға иесін тағайындаңыз. Өзгерісті ол басқаратын кодпен бірге қарап шығыңыз. Команда, runtime, бума немесе CI workflow өзгергенде, сол өзгерістің ішінде ең жақын нұсқау файлын жаңартыңыз. Соңғы тұтынушы жоғалғанда ережені алып тастаңыз. Мысалдар орындалатын әрі қауіпсіз болуы керек. Бір саясатты үш файлға көшірмей, бір ақиқат көзіне сілтеме жасаңыз.
Ай сайынғы немесе релиздік аудит қысқа болуы мүмкін. Әр команданың бар екенін, әр нұсқаның манифестке немесе CI образына сәйкес екенін, әр жолдың әлі бар екенін тексеріңіз. Codex көздерінің тізімін түбірден және бір өкілдік ішкі бумадан сұраңыз. Тиімді тізбектің өлшемін өлшеңіз. Әр ереже нақты қатені әлі де тоқтата ма деп иеден сұраңыз.
AGENTS.md өзгерісін конфигурация өзгерісі сияқты бағалаңыз. Жаңа мүмкіндік, қате түзету, тек тест өзгерісі және қауіпсіздікке сезімтал өзгеріс кіретін шағын тұрақты тапсырмалар жинағын пайдаланыңыз. Agent түсіндірмесін ғана емес, patch дұрыстығы мен ауқымын салыстырыңыз. Регрессия тесті жасалған файлдар өзгермегенін, пакет тесті орындалғанын немесе қауіпті команданың қабылданбағанын тексере алады. Салыстыру түсінікті болуы үшін репозиторий ревизиясын, модель баптауларын, рұқсаттарды және тапсырма мәтінін тұрақты ұстаңыз.
Тұрақты үлгі қарапайым. Тұрақты фактілерді қолданылатын ауқымға жақын орналастырыңыз. Репозиторий дәлелдейтін нақты командалар мен нұсқаларды атаңыз. Толығырақ құжаттарға сілтеме жасаңыз. Маңызды ережелерді тестіленетін етіңіз. Секреттер мен өкілеттікті markdown-нан тыс ұстаңыз. Үлкен нұсқаулықтың орнына қабаттарды қолданыңыз. Жұмыс бумасы, конфигурация немесе құрал нұсқасы өзгерсе, тиімді тізбекті қайта тексеріңіз.