کار حرفه‌ای با ابزارها

AGENTS.md در Codex: دستورهای لایه‌لایهٔ پروژه

تستحریریهٔ سرنخ۲۳ آبان ۱۴۰۵۳ دقیقه مطالعه

این نوشته مستقل است و به هیچ برندی وابسته نیست. اگر ابزاری را معرفی کنیم، دلیلش را هم می‌نویسیم. رویهٔ نوشتن · روش بررسی ابزارها

Codex قبل از شروع هر کار، فایل‌های AGENTS.md را می‌خواند؛ پس قاعده‌های پروژه‌ات را همان‌جا بنویس تا هر بار تکرار نکنی. نکتهٔ مهم، لایه‌لایه بودن آن‌هاست: دستور سراسری، دستور ریشهٔ پروژه و دستور پوشه‌ای که در آن کار می‌کنی کنار هم قرار می‌گیرند.

این نوشته بر پایهٔ مستندات رسمی Codex است که در ۲۶ آبان ۱۴۰۵ خواندیم (مستندات اکنون روی سایت راهنمای ChatGPT قرار دارد). اگر نام تنظیمی در نسخهٔ تو فرق داشت، به مستندات همان نسخه رجوع کن.

زنجیرهٔ دستورها چطور ساخته می‌شود؟

طبق مستندات، زنجیره برای هر اجرا یک بار ساخته می‌شود (در رابط ترمینال، یک بار برای هر جلسه).

  1. سراسری: در پوشهٔ خانگی Codex (~/.codex یا مسیر CODEX_HOME). اگر AGENTS.override.md باشد همان خوانده می‌شود، وگرنه AGENTS.md. در این سطح فقط اولین فایل غیرخالی استفاده می‌شود.
  2. پروژه: از ریشهٔ پروژه (معمولاً ریشهٔ Git) تا پوشهٔ فعلی. در هر پوشه اول AGENTS.override.md، بعد AGENTS.md و بعد نام‌هایی که در project_doc_fallback_filenames آمده. حداکثر یک فایل در هر پوشه.
  3. ترکیب: همه از ریشه به سمت پایین کنار هم گذاشته می‌شوند. فایل‌های نزدیک‌تر دیرتر می‌آیند و روی دستورهای قبلی برتری دارند.

فایل‌های خالی نادیده گرفته می‌شوند و سقف حجم با 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، نوشتهٔ بعدی را ببین و برای مقایسهٔ فایل‌های دستور در ابزارها، مقایسهٔ ابزارهای کدنویسی.

سوالات متداول

اشتراک‌گذاری:تلگرامواتس‌اپایکس
تس

تحریریهٔ سرنخ

تیم نویسندگان و آزمایشگران

ما چند نفریم که هر روز با ابزارهای هوش مصنوعی و اتوماسیون کار می‌کنیم. هر راهنمایی که اینجا می‌بینید اول روی کارِ خودمان امتحان شده و بعد نوشته شده است.

کار حرفه‌ای با ابزارهاراهنمای اصلی

کار مؤثر با ابزارهای هوش مصنوعی: پنج اصل مشترک

پنج اصل مشترک برای کار با Claude، Codex، Cursor، Copilot، NotebookLM و Perplexity: زمینه، برنامه، سنجش، زمینهٔ تمیز و مرز دسترسی. به‌همراه فهرست راهنماها.

۲۶ آبان ۱۴۰۵۳ دقیقه مطالعه