AGENTS.md و CLAUDE.md چیست؟ فایل راهنمای پروژه برای ایجنت‌ها

هر بار که با Claude Code یا Codex گفتگوی تازه‌ای شروع می‌کنید، دستیار چیزی از پروژه‌ی شما به یاد ندارد: نمی‌داند دستور بیلد چیست، تست‌ها کجا هستند و کدام پوشه را نباید دست بزند. فایل‌های AGENTS.md و CLAUDE.md برای همین ساخته شده‌اند: حافظه‌ی همیشگی پروژه که ایجنت در شروع هر کار می‌خواند.

#این فایل‌ها چه هستند؟

هر دو، فایل مارک‌داون ساده‌ای در ریشه‌ی پروژه‌اند. فرقشان فقط این است که کدام ابزار کدام را می‌خواند:

• CLAUDE.md را Claude Code در شروع هر گفتگو می‌خواند.
• AGENTS.md قالبی است که OpenAI معرفی کرد و حالا Codex و ابزارهای زیادی آن را می‌خوانند. از دسامبر ۲۰۲۵ هم کنار MCP زیر نظر بنیاد Agentic AI قرار گرفته است.

اگر تیمتان با چند ابزار کار می‌کند، یک راه ساده این است که محتوای اصلی را در AGENTS.md بنویسید و در CLAUDE.md فقط به آن ارجاع دهید، تا دو نسخه‌ی متفاوت درست نشود.

#چه چیزی بنویسیم؟

فقط چیزهایی که همیشه درست‌اند و ایجنت بدون آن‌ها اشتباه می‌کند:

# فروشگاه Skills
## دستورها
- نصب: npm install
- بیلد: npm run build — قبل از گفتن «تمام شد» اجرا کن
- تست: npm test

## قواعد
- متن‌های رابط فارسی‌اند: نیم‌فاصله، ارقام فارسی، «ی» و «ک» فارسی
- در CSS از ویژگی‌های منطقی استفاده کن، نه left و right
- پوشه‌ی drizzle/ را دستی تغییر نده؛ با npm run db:generate بساز

سه دسته‌ی اصلی:

1. دستورها: نصب، بیلد، تست و اجرای محلی.
2. قواعد پروژه: نام‌گذاری، سبک کد، کتابخانه‌هایی که باید یا نباید استفاده شوند.
3. خط قرمزها: فایل‌هایی که نباید عوض شوند و کارهایی که پیش از انجام باید پرسیده شوند.

#چه چیزی ننویسیم؟

• توضیح چیزهایی که ایجنت از خود کد می‌فهمد. ساختار پوشه‌ها را می‌خواند؛ لازم نیست فهرستشان کنید.
• دانش تخصصی که فقط گاهی لازم است. قواعد کامل طراحی آیکون یا روش نوشتن متن رابط، جایشان در اسکیل است.
• متن طولانی. این فایل در هر گفتگو کامل خوانده می‌شود و هر خط اضافه، حافظه‌ی همه‌ی کارها را می‌گیرد.

#AGENTS.md یا اسکیل؟

سؤالی که زیاد پیش می‌آید. قاعده ساده است: هر چیزی که در همه‌ی کارهای این پروژه لازم است، در AGENTS.md؛ هر چیزی که فقط برای یک نوع کار لازم است، در اسکیل. دستور بیلد همیشه لازم است؛ قواعد طراحی پوستر فقط وقتی پوستر می‌سازید.

تفاوت مهم دیگر: اسکیل قابل‌انتقال است. اسکیل نوشتن متن فارسی را در همه‌ی پروژه‌هایتان نصب می‌کنید، ولی AGENTS.md مال همان یک پروژه است. برای فهم بهتر سازوکار اسکیل، راهنمای کامل اسکیل را ببینید.

#نگهداری

این فایل هم مثل کد پیر می‌شود. دو عادت کمک می‌کند:

• هر بار ایجنت اشتباهی کرد که با یک خط قابل جلوگیری بود، آن خط را اضافه کنید.
• هر چند وقت یک بار فایل را بخوانید و هر چیزی را که دیگر درست نیست حذف کنید. قاعده‌ی کهنه از نبود قاعده بدتر است.

اگر تازه با Claude Code شروع کرده‌اید، راهنمای شروع Claude Code قدم بعدی خوبی است.