Codex قبل از شروع هر کار، فایلهای AGENTS.md را میخواند؛ پس قاعدههای پروژهات را همانجا بنویس تا هر بار تکرار نکنی. نکتهٔ مهم، لایهلایه بودن آنهاست: دستور سراسری، دستور ریشهٔ پروژه و دستور پوشهای که در آن کار میکنی کنار هم قرار میگیرند.
این نوشته بر پایهٔ مستندات رسمی Codex است که در ۲۶ آبان ۱۴۰۵ خواندیم (مستندات اکنون روی سایت راهنمای ChatGPT قرار دارد). اگر نام تنظیمی در نسخهٔ تو فرق داشت، به مستندات همان نسخه رجوع کن.
زنجیرهٔ دستورها چطور ساخته میشود؟
طبق مستندات، زنجیره برای هر اجرا یک بار ساخته میشود (در رابط ترمینال، یک بار برای هر جلسه).
- سراسری: در پوشهٔ خانگی Codex (
~/.codexیا مسیرCODEX_HOME). اگرAGENTS.override.mdباشد همان خوانده میشود، وگرنهAGENTS.md. در این سطح فقط اولین فایل غیرخالی استفاده میشود. - پروژه: از ریشهٔ پروژه (معمولاً ریشهٔ Git) تا پوشهٔ فعلی. در هر پوشه اول
AGENTS.override.md، بعدAGENTS.mdو بعد نامهایی که درproject_doc_fallback_filenamesآمده. حداکثر یک فایل در هر پوشه. - ترکیب: همه از ریشه به سمت پایین کنار هم گذاشته میشوند. فایلهای نزدیکتر دیرتر میآیند و روی دستورهای قبلی برتری دارند.
فایلهای خالی نادیده گرفته میشوند و سقف حجم با project_doc_max_bytes تعیین میشود (مقدار پیشفرض ۳۲ کیبیبایت).
چه چیزی در آن بنویسیم؟
نمونههای خود مستندات دو بخش دارد: «توافقهای کاری» و «انتظارات مخزن». مثلاً «پیش از باز کردن pull request دستور npm run lint را اجرا کن».
یک نکتهٔ جالب: بخش ## Code Review Rules در نزدیکترین AGENTS.md به کد، قاعدههای بازبینی را مشخص میکند. قاعدههای کل مخزن را در ریشه و قاعدههای یک سرویس را در پوشهٔ همان سرویس بنویس. بررسیهای لینت و قالببندی را هم در CI نگه دار.
یک نمونهٔ کوتاه
# Working agreements
- Run `npm test` before finishing a task.
- Do not edit files under `vendor/`.
# Repository expectations
- Use TypeScript strict mode.
- New API routes go in `src/routes/`.
نوشتن به انگلیسی ضرورتی ندارد؛ اگر تیم فارسیزبان است فارسی بنویس. برای دستورهای فنی، نام دستورها را به همان شکل اصلی نگه دار.
چطور بفهمیم چه دستوری بارگذاری شده؟
مستندات خودش یک آزمون پیشنهاد میکند:
codex --ask-for-approval never "Summarize the current instructions."
اگر خلاصه با AGENTS.md تو نمیخواند، ساختار پوشه یا نام فایل را بررسی کن. برای ثبت جزئیات هم میشود پوشهٔ لاگ تعیین کرد.
دستور /init
داخل CLI، /init یک AGENTS.md اولیه میسازد. آن را مثل پیشنویس ببین: بخوان، کم کن و فقط قاعدههایی را نگه دار که واقعاً درستاند.
نکتههای عملی
- کوتاه بنویس. سقف ۳۲ کیبیبایتی برای کل زنجیره است، نه یک فایل.
- از قاعدههای سراسری برای عادتهای شخصی استفاده کن، نه برای قاعدهٔ پروژه.
- override را با احتیاط. آن فایل دستور همسطح خودش را کنار میزند؛ برای آزمایش موقت مناسب است.
ادامه
اگر Claude Code هم استفاده میکنی، CLAUDE.md همین نقش را دارد. برای کار امن با Codex، نوشتهٔ بعدی را ببین و برای مقایسهٔ فایلهای دستور در ابزارها، مقایسهٔ ابزارهای کدنویسی.
سوالات متداول
راهنمای اصلی این بخش
کار مؤثر با ابزارهای هوش مصنوعی: پنج اصل مشترکتحریریهٔ سرنخ
تیم نویسندگان و آزمایشگران
ما چند نفریم که هر روز با ابزارهای هوش مصنوعی و اتوماسیون کار میکنیم. هر راهنمایی که اینجا میبینید اول روی کارِ خودمان امتحان شده و بعد نوشته شده است.