AGENTS.md و HUMAN.md چیستند و چه چیزی بنویسیم؟

AGENTS.md چیست

AGENTS.md یک فایل ساده با قالب markdown در ریشه یک repository است که به یک coding agent می‌گوید چگونه روی آن پروژه کار کند. سایت رسمی آن را این‌گونه توصیف می‌کند: «یک README برای agentها؛ مکانی اختصاصی و قابل پیش‌بینی برای ارائه زمینه و دستورالعمل‌هایی که به coding agentهای هوش مصنوعی کمک می‌کند روی پروژه شما کار کنند.» قالب آن زیر نظر Agentic AI Foundation در Linux Foundation مدیریت می‌شود و بیش از 20 agent، از جمله Codex، Cursor، Jules، Devin و GitHub Copilot، آن را می‌خوانند (تا July 2026).

دلیل ایجاد این قرارداد، کاربرد عملی آن است. فردی که به‌تازگی به تیم شما ملحق شده است، README را می‌خواند، دستور build را حدس می‌زند و اگر حدسش اشتباه باشد، از شخصی سؤال می‌کند. یک agent نمی‌تواند سؤال بپرسد. حدس می‌زند، npm test را در پروژه‌ای اجرا می‌کند که از pnpm test استفاده می‌کند، خطا را می‌خواند و راه دیگری را امتحان می‌کند. برای تک‌تک این tokenها هزینه می‌پردازید. نوشتن دستور واقعی در یک محل، کل این دسته از خطاها را حذف می‌کند.

هیچ فیلد الزامی وجود ندارد. سایت به‌صراحت می‌گوید: «AGENTS.md فقط Markdown استاندارد است. از هر headingای که می‌خواهید استفاده کنید؛ agent به‌سادگی متنی را که ارائه می‌کنید parse می‌کند.» این تمام specification است. ارزش آن در format نیست. ارزش آن در این است که فایل در مسیری قرار دارد که همه ابزارها از قبل آن را بررسی می‌کنند.

محل قرارگیری فایل و اولویت فایل‌ها

فایل اول را در ریشه مخزن قرار دهید. در یک monorepo می‌توانید در هر زیرپروژه فایل‌های بیشتری اضافه کنید. قاعده ساده است: «agents به‌صورت خودکار نزدیک‌ترین فایل را در درخت دایرکتوری می‌خوانند؛ بنابراین نزدیک‌ترین فایل اولویت دارد.» تعارض میان دو فایل به نفع فایلی حل می‌شود که در حال ویرایش آن هستید. هر چیزی نیز که در chat وارد کنید، بر هر دو فایل اولویت دارد.

my-repo/
├── AGENTS.md              # project-wide rules
├── services/
│   ├── api/
│   │   └── AGENTS.md      # wins for edits under services/api/
│   └── web/
│       └── AGENTS.md      # wins for edits under services/web/
└── README.md

استفاده از ساختار تو‌در‌تو مفید است، زیرا تنها راه بیان مطلبی است که در یک پوشه درست و در پوشه بعدی نادرست باشد. قاعده‌ای مانند «هر endpoint ورودی خود را اعتبارسنجی می‌کند» باید در کنار endpointها قرار بگیرد. اگر این قاعده در فایل ریشه باشد، در هر کار نامرتبطی بارگذاری می‌شود و فایده‌ای ندارد.

مواردی که باید در AGENTS.md بیاید

مواردی را بنویسید که agent نمی‌تواند با خواندن کد آن‌ها را مشخص کند. دستورهای دقیق build، test و lint در اولویت هستند و باید به شکلی نوشته شوند که بتوانید آن‌ها را در terminal جای‌گذاری کنید. دستور اجرای یک test را نیز اضافه کنید، زیرا agentی که فقط روش اجرای کل مجموعه را بداند، کل مجموعه را چهل بار اجرا خواهد کرد. قراردادهایی را نام ببرید که با پیش‌فرض ابزار تفاوت دارند، چون agent از پیش پیش‌فرض را می‌داند و فقط باید از تغییر شما مطلع شود. اگر برای پیام commit یا pull request قواعدی دارید، قالب پیام commit و قوانین pull request را نیز اضافه کنید.

دستورالعمل‌ها باید آن‌قدر دقیق باشند که بتوان یک ادعا را بررسی کرد. «از تورفتگی 2 فاصله‌ای استفاده کنید» دستورالعملی قابل‌استفاده است، زیرا مشخص است که رعایت شده یا نشده است. «کد را به‌درستی قالب‌بندی کنید» قابل‌بررسی نیست، چون هیچ بخش آن را نمی‌توان راستی‌آزمایی کرد. همین موضوع درباره محل فایل‌ها نیز صدق می‌کند: «handlerهای API در src/api/handlers/ قرار دارند» از «فایل‌ها را سازمان‌دهی‌شده نگه دارید» بهتر است.

قواعد منفی نیز ارزش درج دارند. «هرگز فایل‌های داخل dist/ را ویرایش نکنید؛ این فایل‌ها توسط npm run build تولید می‌شوند» از یک اشتباه مشخص جلوگیری می‌کند. چون علت را نیز بیان می‌کند، agent می‌تواند حالت مشابهی را که در دستورالعمل ذکر نشده است، تشخیص دهد.

چه چیزهایی هرگز نباید در این فایل‌ها قرار گیرند

هرگز اطلاعات محرمانه را در یکی از این فایل‌ها قرار ندهید. این فایل به git commit می‌شود، در آغاز هر session در context بارگذاری می‌شود و در هر request برای یک model provider ارسال می‌شود. وجود یک API key در AGENTS.md یعنی آن API key هم در تاریخچه repository شما و هم در logهای یک شخص ثالث ثبت می‌شود. به‌جای چسباندن secret، به محل آن اشاره کنید: «رمز عبور پایگاه داده در .env قرار دارد و این مسیر در gitignore نادیده گرفته می‌شود؛ پیش از خواندن آن سؤال کن.» جزئیات این رویکرد کلی‌تر در دور نگه‌داشتن اطلاعات دسترسی از دسترس agent آمده است.

هر چیزی را که agent می‌تواند با مشاهده به دست آورد، حذف کنید. یک فهرست از محتویات directory، یک نسخه از فهرست dependencyها یا یک نمای کلی از معماری که فقط نام folderها را تکرار می‌کند، همگی یک هفته پس از نوشتن منسوخ می‌شوند و در این فاصله در هر session از context استفاده می‌کنند. دام‌ها و دلایل را نگه دارید. فهرست اقلام را حذف کنید.

همان ایده برای نمونه Claude Code است

Claude Code فایل CLAUDE.md را می‌خواند و فایل AGENTS.md را به‌صورت خودکار نمی‌خواند. فایل پروژه در ./CLAUDE.md یا ./.claude/CLAUDE.md قرار می‌گیرد، ترجیحات شخصی برای همه پروژه‌ها در ~/.claude/CLAUDE.md ذخیره می‌شوند و سازمان می‌تواند در Linux یک فایل سراسری سیستم را در /etc/claude-code/CLAUDE.md قرار دهد. فایل‌های شناسایی‌شده از ریشه سیستم فایل تا دایرکتوری کاری شما به هم پیوسته می‌شوند؛ بنابراین فایلی که به محل راه‌اندازی session نزدیک‌تر است، آخر از همه خوانده می‌شود.

اگر مخزن شما از قبل فایل AGENTS.md دارد، یک نسخه دوم از آن نگه ندارید. آن را import کنید و فقط موارد مخصوص Claude را اضافه کنید:

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

اگر مورد دیگری برای افزودن ندارید، symlink کافی است:

ln -s AGENTS.md CLAUDE.md

این command در صورت موفقیت هیچ خروجی‌ای چاپ نمی‌کند. در session بعدی /context را اجرا کنید و تأیید کنید که CLAUDE.md زیر فایل‌های حافظه نمایش داده می‌شود. اگر این مورد در آن فهرست وجود نداشت، فایل هرگز بارگذاری نشده است؛ بنابراین هیچ‌یک از محتوای آن اعمال نشده است. برای تولید یک پیش‌نویس اولیه به‌جای نوشتن فایل، /init را اجرا کنید. این command کدبیس را می‌خواند و یک فایل اولیه تولید می‌کند. اگر CLAUDE.md از قبل وجود داشته باشد، به‌جای بازنویسی آن، پیشنهادهای بهبود ارائه می‌دهد.

حجم هر فایل را حدود 200 خط یا کمتر نگه دارید. فایل‌های طولانی‌تر بخش بیشتری از window را مصرف می‌کنند و میزان پایبندی کاهش می‌یابد. اگر می‌خواهید ببینید چه موارد دیگری برای این فضا رقابت می‌کنند، آنچه واقعاً window زمینه یک agent را پر می‌کند موضوع را به‌صورت جزئی توضیح می‌دهد.

یک نکته نیازمند تأکید است. AGENTS.md راهنماست، نه سیستم مجوزدهی. محتویات آن به‌صورت context معمولی ارائه می‌شود؛ بنابراین مدل آن را می‌خواند و معمولاً رعایت می‌کند، اما هیچ چیزی مانع اجرای اقدامی که با آن تناقض دارد نمی‌شود. برای قانونی که باید هر بار بدون استثنا رعایت شود، مانند «هرگز به main push نکن»، از hook یا تنظیم مجوز استفاده کنید؛ زیرا این موارد به‌صورت code اجرا می‌شوند و به تصمیم مدل برای اطاعت وابسته نیستند.

ابزارهایی که این فایل‌ها را برای شما ایجاد می‌کنند

دو پروژه در فهرست پرطرفدارهای GitHub در 30 July 2026 نشان می‌دهند این رویه به کدام سمت می‌رود.

agent0ai/dox (با 1,368 ستاره تا July 2026) چارچوبی برای به‌روز نگه‌داشتن درختی از فایل‌های AGENTS.md است. این پروژه هیچ package یا runtimeای ارائه نمی‌کند. محتوای AGENTS.md آن را در AGENTS.md ریشه پروژه خود کپی می‌کنید و همین کار، نصب محسوب می‌شود. برای پروژه‌ای که از قبل وجود دارد، به agent خود می‌گویید:

Initialize DOX tree for this project now.

سپس agent فایل‌های AGENTS.md فرزند و indexهای آن‌ها را ایجاد می‌کند، پیش از ویرایش هر چیزی درخت را پیمایش می‌کند و پس از اعمال تغییر، مستندات تحت‌تأثیر را به‌روز می‌کند. مبنای این رویکرد آن است که مستنداتی که agent به‌عنوان پیامد جانبی کار خود نگهداری می‌کند، دقیق و منطبق باقی می‌مانند؛ اما مستنداتی که فردی به‌صورت دستی به‌روز می‌کند، چنین وضعیتی ندارند.

HUMAN.md؛ همان ترفند، این بار برای خودتان

Intuition-Lab/personal-model (با 1,260 ستاره تا ژوئیه 2026) همین الگو را به‌جای مخزن، برای یک فرد به کار می‌برد. این پروژه HUMAN.md شما را خروجی سیستم می‌داند، نه فایلی که خودتان می‌نویسید: «مدلی زنده از آنچه اکنون اهمیت دارد، نحوه تصمیم‌گیری معمول شما و مسیری که توجهتان در آن حرکت می‌کند.» این ابزار به‌صورت محلی روی macOS 13 یا نسخه‌های جدیدتر اجرا می‌شود، پس از اعطای مجوز به macOS فعالیت‌ها را ثبت می‌کند و نتیجه را از طریق MCP (پروتکل زمینه مدل) در اختیار agentها قرار می‌دهد. مسیر کوتاه نصب:

uv tool install personal-model
persome onboard
persome model open --after 30

برای دریافت بیشتر مزایا، به هیچ‌یک از این موارد نیاز ندارید. یک HUMAN.md دست‌نویس حدود 20 خط است: نقش شما، منطقه زمانی‌تان، stackای که واقعاً استفاده می‌کنید، تصمیم‌هایی که قبلاً گرفته‌اید و نمی‌خواهید دوباره مطرح شوند، و میزان توضیحی که می‌خواهید دریافت کنید. این فایل همان توضیح‌های تکراری را که فایل پروژه حذف می‌کند، در یک لایه بالاتر کاهش می‌دهد.

یک نکته احتیاطی وجود دارد. HUMAN.md نمایه‌ای از یک فرد است؛ بنابراین ذاتاً حساس است. آن را در یک مخزن عمومی قرار ندهید. آن را در ~/.claude/CLAUDE.md قرار دهید یا در یک CLAUDE.local.md که در ریشه پروژه قرار دارد و توسط git نادیده گرفته می‌شود؛ این فایل در کنار فایل commit‌شده بارگذاری می‌شود و به همان روش با آن رفتار می‌شود.

یک الگوی اولیه برای کپی‌کردن

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

# AGENTS.md

## Project
A Django API serving the mobile app. Python 3.12, PostgreSQL 16.

## Setup
uv sync
docker compose up -d db
./manage.py migrate

## Commands
Run one test: pytest tests/test_orders.py::test_refund
Run everything: pytest
Lint: ruff check . && ruff format --check .

## Conventions
Type hints on every public function. Line length 100, not 88.
Migrations are generated, never hand-edited.
Never edit files under static/dist/, they come from npm run build.

## Secrets
Local credentials live in .env, which is gitignored. Ask before reading it.

## Pull requests
Title format: [area] short description. Run the linter before opening one.

آن را بنویسید و سپس همان‌جا اصلاحش کنید. وقتی یک اصلاح را برای بار دوم در چت تایپ کردید، این نشانه‌ای است که باید آن را به فایل اضافه کنید. همین یک قاعده فایل را مفید نگه می‌دارد و مانع از آن می‌شود که فایل به سندی تبدیل شود که هیچ‌کس، حتی ماشین‌ها، آن را نمی‌خواند. وقتی فایل پایدار شد، همراه repository جابه‌جا می‌شود. این موضوع زمانی اهمیت بیشتری دارد که agent در جایی غیر از لپ‌تاپ شما اجرا شود: اجرای coding agent روی سرور شخصی شما این راه‌اندازی را پوشش می‌دهد.

FAQ

آیا AGENTS.md همان فایل CLAUDE.md است؟

این دو فایل با دو نام متفاوت، یک ایده را دنبال می‌کنند. Claude Code فایل CLAUDE.md را می‌خواند و فایل AGENTS.md را نادیده می‌گیرد، مگر اینکه آن‌ها را به یکدیگر متصل کنید. یک فایل را به‌عنوان مرجع اصلی نگه دارید و فایل دیگر را به آن پیوند دهید؛ این کار را می‌توانید با قرار دادن خط @AGENTS.md در ابتدای CLAUDE.md یا با استفاده از ln -s AGENTS.md CLAUDE.md انجام دهید. اگر دو نسخه کامل را جداگانه نگهداری کنید، این دو فایل ظرف یک ماه با هم ناسازگار می‌شوند.

آیا نوشتن AGENTS.md تضمین می‌کند که agent از آن پیروی کند؟

خیر. محتوا به‌عنوان context ارائه می‌شود؛ بنابراین model آن را می‌خواند و معمولاً از آن پیروی می‌کند، اما هیچ چیزی مانع اجرای اقدامی که با آن در تضاد است نمی‌شود. دستورالعمل‌های مبهم با کمترین قابلیت اطمینان اجرا می‌شوند و اگر دو فایل راهنمایی متناقض ارائه دهند، agent یکی را به‌صورت دلخواه انتخاب می‌کند. برای قاعده‌ای که باید هر بار اجرا شود، از hook یا permission rule استفاده کنید؛ این موارد، صرف‌نظر از تصمیم model، توسط client اعمال می‌شوند.

آیا باید AGENTS.md را در git commit کرد؟

بله، برای هر چیزی که درباره پروژه حقیقت دارد؛ مانند build commandها، layout و conventionها. هدف این فایل همین است، زیرا agentهای همکارانتان نیز با همان context اولیه‌ای شروع می‌کنند که agent شما دارد. هر چیزی که شخصی یا مخصوص یک machine است باید در فایلی جداگانه قرار گیرد و در gitignore ثبت شود؛ credentialها نیز نباید در هیچ‌کدام از این فایل‌ها قرار بگیرند.

HUMAN.md چیست و آیا به آن نیاز دارم؟

HUMAN.md یک profile قابل خواندن توسط machine درباره یک شخص است، نه درباره یک project. این فایل role، محدودیت‌ها و تصمیم‌هایی را که قبلاً نهایی کرده‌اید نگه می‌دارد تا در هر session دوباره مطرح نشوند. برای شروع به ابزار خاصی نیاز ندارید: بیست خط که در فایل user-level instructions خود بنویسید، بیشتر مزایای آن را فراهم می‌کند. با آن مانند داده شخصی رفتار کنید و آن را در هیچ repository که push می‌کنید قرار ندهید.