ساخت فایل AGENTS.md گام‌به‌گام

یک فایل AGENTS.md یک فایل Markdown واحد در ریشه مخزن (repo root) شماست. این فایل به عامل‌های کدنویسی هوش مصنوعی (AI coding agents) می‌گوید که چگونه کار کنند. این فایل شامل مراحل ساخت، تست‌ها و قوانین است.

برای ساخت یک فایل برای یک پروژه Python FastAPI، این مراحل را دنبال کنید.

۱. تعریف تکنولوژی‌ها (Stack)

با یک جمله شروع کنید. به عامل بگویید از چه زبان، فریم‌ورک و پایگاه داده‌ای استفاده شده است. مثال: A URL shortener API in Python using FastAPI, SQLite, and pytest.

۲. ارائه دستورات راه‌اندازی

دستورات واقعی برای اجرا به عامل بدهید. از جایگزین‌ها (placeholders) استفاده نکنید.

  • Setup: python -m venv .venv && source .venv/bin/activate
  • Run: uvicorn app.main:app --reload

۳. تعیین استاندارد تست

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

  • Run pytest
  • Run ruff check
  • Run mypy

۴. ترسیم ساختار

پوشه‌های خود را لیست کنید تا عامل مجبور نباشد تمام فایل‌ها را جستجو کند.

  • app/main.py: مدیریت مسیرها (route handlers)
  • app/db.py: دسترسی به SQLite
  • migrations/: SQLهای تولید شده (ویرایش نکنید)

۵. تعریف قراردادها

دقیق باشید. قوانین مبهم بی‌فایده هستند.

  • برای تمام اعتبارسنجی‌های ورودی از Pydantic استفاده کنید.
  • برای خطاهای کلاینت، HTTPException را Raise کنید.
  • همه چیز را تایپ‌گذاری (Type) کنید تا mypy تمیز بماند.

۶. لیست «نبایدها»

با تعیین مرزهای مشخص، از بروز اشتباهات جلوگیری کنید.

  • فایل‌های migrations را دستی ویرایش نکنید.
  • مستقیماً روی main کامیت نکنید.
  • هرگز اسکریپت‌های seed را روی پایگاه‌های داده غیرمحلی (non-local) اجرا نکنید.

چرا این روش موثر است؟

وقتی به یک عامل هوش مصنوعی وظیفه‌ای مثل "Add a DELETE endpoint" می‌دهید، او ابتدا این فایل را می‌خواند.

با داشتن یک فایل AGENTS.md، عامل:

  • دقیقاً می‌داند کجا باید کد اضافه کند.
  • از ابزارهای تست خاص شما استفاده می‌کند.
  • بدون پرسیدن سوال، از سبک شما پیروی می‌کند.
  • به جای خراب کردن کد اصلی، یک branch باز می‌کند.

بدون این فایل، عامل حدس می‌زند. ممکن است از runner تست اشتباه استفاده کند یا فایل‌هایی را ویرایش کند که نباید به آن‌ها دست بزند.

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

Source: https://dev.to/wolfejam/agentsmd-hands-on-build-one-step-by-step-and-watch-an-agent-use-it-3g27

Optional learning community: https://t.me/GyaanSetuAi