تصور کنید هر بار که برای ویرایش کد به سراغ دستیار هوش مصنوعی می‌روید، او مانند کارمندی است که روز اولش است و هیچ خاطره‌ای از تصمیمات دیروز شما ندارد. این «راه‌اندازی سرد» (Cold Start) دقیقاً همان جایی است که خطرناک‌ترین باگ‌ها متولد می‌شوند؛ چون وقتی عامل هوش مصنوعی حافظه ندارد، مجبور به حدس زدن می‌شود و حدس زدن در دنیای کدنویسی، منشأ most frustrating bugs یا همان آزاردهنده‌ترین باگ‌هاست.
این چالش زمانی حیاتی می‌شود که عامل (Agent) — شبیه به دستیاری که حالا اجازه دارد مستقیماً در فایل‌های شما تغییر ایجاد کند و نه فقط پیشنهاد بدهد — از یک دستیار «فقط-خواندنی» به یک مشارکت‌کننده فعال با دسترسی نوشتن تبدیل شود. تفاوت در اینجا حیاتی است: یک دستیار فقط-خواندنی ممکن است صرفاً یک جمله بد تولید کند، اما عاملی با دسترسی نوشتن می‌تواند یک بیلد تولیدی (Production Build) را خراب کند یا وابستگی‌های حیاتی پروژه را حذف نماید. صنعت اکنون به سمت نیاز به «وضعیت پایدار» (Persistent State) برای عامل‌ها حرکت می‌کند؛ نه در وزن‌های مدل، بلکه در دایرکتوری ریشه پروژه.
طبق راهنمای منتشر شده در no-code.supply در اکتبر ۲۰۲۶، راهکار این مشکل ایجاد یک فایل متنی استاندارد به نام AGENTS.md در ریشه پروژه است. این فایل به عنوان «منبع واحد حقیقت» (Single Source of Truth) عمل می‌کند و ابزارهای مدرنی مثل Cursor، Codex و GitHub Copilot پیش از هر تغییری، آن را به‌طور خودکار می‌خوانند و از این کنوانسیون باز پیروی می‌کنند.
برای کاربرانی که از Claude Code استفاده می‌کنند و این ابزار به‌طور پیش‌فرض به دنبال CLAUDE.md می‌گردد، نویسنده پیشنهاد می‌کند از یک خط واردات ساده (@AGENTS.md) استفاده کنند تا مجبور نباشند دو نسخه از قوانین خود را مدیریت کنند. اگرچه Claude Code اکنون می‌تواند به‌تنهایی AGENTS.md را بخواند، اما اگر هر دو فایل وجود داشته باشند، اولویت را به CLAUDE.md می‌دهد. استفاده از این خط واردات تضمین می‌کند که شما نیازی به نگهداری دو کپی مجزا از قوانین خود ندارید.
زمینه: چرا این فایل اهمیت دارد؟
اعتقاد نویسنده به این متد از تجربه ساخت ۱۵ قالب وب‌سایت با Claude Code در حدود یک هفته نشأت می‌گیرد. در طول دو مخزن (Repository) و ده‌ها جلسه کاری، عامل هوش مصنوعی هر بار از نقطه صفر شروع می‌کرد. بدون یک سابقه مکتوب، عامل مجبور است حدس بزند که پروژه چگونه کار می‌کند.
علاوه بر این، برای کسانی که قالب‌های آماده می‌فروشند، وجود AGENTS.md برای کاربر نهایی حیاتی است. اکثر خریداران قالب‌ها، کدها را به‌صورت دستی ویرایش نمی‌کنند؛ بلکه از Cursor یا Claude Code استفاده می‌کنند تا درخواست‌هایی مثل «بخش Hero را آبی کن» بدهند. در این حالت، فایل AGENTS.md تنها چیزی است که مانع از آن می‌شود که دستیار هوش مصنوعی در حین اجرای درخواست کاربر، به‌طور بی‌صدا قوانین داخلی قالب را بشکند.
کالبدشکافی یک فایل AGENTS.md اثرگذار
برای جلوگیری از اینکه عامل دستورالعمل‌ها را نادیده بگیرد، این فایل باید به عنوان مجموعه‌ای از دستورات برای یک همکار نوشته شود، نه یک صفحه ویکی یا دانشنامه. یک AGENTS.md با عملکرد بالا از پنج بخش خاص تشکیل شده است. برای تشریح این بخش‌ها، نویسنده از مثال‌های قالب Oda (یک قالب استودیو معماری) استفاده می‌کند.
۱. تعریف پروژه (Project Definition)
با یک خلاصه دو جمله‌ای شروع کنید که پروژه چیست و چه محدودیتی همه چیز را شکل می‌دهد.
- مثال: «یک صفحه فرود استاتیک و بدون وابستگی برای یک استودیو معماری:
index.html+ CSS + JS کلاسیک. هیچ مرحله Build وجود ندارد و هرگز نباید اضافه شود. صفحه باید زمانی کهindex.htmlمستقیماً از روی دیسک باز می‌شود، به درستی کار کند.» - چرا جواب می‌دهد: جمله آخر مانع از آن می‌شود که یک عامل «خوش‌نیت»، به‌طور خودکار یک Bundler یا فرآیند Build اضافه کند که منجر به شکست شرط اصلی پروژه شود.
۲. نقشه پروژه (Project Map)
این بخشی است که فایل‌های مورد نیاز عامل برای انجام کار را مشخص می‌کند. به جای لیست کردن تک‌تک فایل‌ها، به عامل بگویید کجا تغییر ایجاد کند و از کجا دوری کند.
- ساختار و کپی: فایل
index.htmlبا استفاده از کامنت‌های بنر SECTION برای هر بخش (Hero, Studio, Work, Process). - توکن‌های طراحی: فایل
assets/css/tokens.css. دستورالعمل صریح است: «مقادیر را اینجا تغییر بده، نه درmain.css». - کمک‌های مشترک (Shared Helpers): فایل‌های
assets/js/kit.jsوassets/css/kit.css. این‌ها به عنوان فایل‌های Vendored علامت‌گذاری شده‌اند با این دستور: «ویرایش نکن؛ به جای پیاده‌سازی مجدد، از کمک‌هایkit.*استفاده کن».
۳. قوانین غیرقابل مذاکره (Non-Negotiable Rules)
این بخش قلب فایل است. قوانین باید کوتاه، شماره‌دار و همراه با یک «دلیل» باشند. بدون دلیل، عامل ممکن است قانون را صرفاً یک ترجیح سلیقه‌ای ببیند و آن را با چیزی که فکر می‌کند «بهتر» است معاوضه کند.
- قانون ۱: هیچ درخواست خارجی (بدون CDN، گوگل فونت، آنالیتیکس یا تصاویر ریموت).
- قانون ۲: اسکریپت‌های کلاسیک فقط با
defer. هرگز ازtype="module"یاimportاستفاده نکن چون در پروتکلfile://شکست می‌خورند. - قانون ۳: رعایت
prefers-reduced-motion؛ انیمیشن‌های جدید باید معادل استاتیک داشته باشند. - قانون ۶: دقیقاً یک تگ
<h1>؛ ترتیب هدینگ‌ها، لندمارک‌ها، لینک Skip و استایل‌های:focus-visibleرا حفظ کن. - قانون ۸: از توکن‌های موجود استفاده کن. اگر توکن جدیدی نیاز است، آن را با یک کامنت به
tokens.cssاضافه کن. به‌طور خاص، متن‌ها در رنگ Accent باید از--timber-ink(برای سایز بزرگ) یا--timber-deep(برای سایز کوچک) استفاده کنند و هرگز از--timberاستفاده نشود چون کنتراست آن ضعیف است.
۴. دستورالعمل‌های اجرایی (Task Recipes)
عامل‌ها آنچه را می‌بینند کپی می‌کنند. با ارائه یک قطعه کد (Snippet) عینی برای رایج‌ترین کارها — مانند اضافه کردن یک بخش جدید — توسعه‌دهنده تضمین می‌کند که عامل سبک معماری موجود را تکرار می‌کند.
برای قالب Oda، این دستورالعمل شامل موارد زیر است:
- هدر: استفاده از
.sec-headخط‌کشی شده با فرمت(NN) Nameبه همراه یک زیرعنوان و شماره صفحه آزاد بعدی. - چیدمان: استفاده از
.wrapبه همراه.g12دوازده ستونی؛ فاصله‌ها از.secمی‌آیند. - هدینگ‌ها: استفاده از
.h2به طوری که آخرین کلمه در<span class="dim">قرار گیرد. - نمایش‌ها (Reveals): استفاده از
data-reveal="draft"باdata-reveal-delayبر حسب میلی‌ثانیه.
۵. چک‌لیست «پایان کار» (The Done Checklist)
در نهایت، مجموعه‌ای از الزامات را قرار دهید تا عامل پیش از اعلام پایان کار، آن‌ها را تایید کند. این کار مانع از آن می‌شود که عامل در حالی که خطاهای کوچک باقی مانده، ادعای پیروزی کند.
- بررسی‌های دستی: نبود خطای کنسول، نبود اسکرول افقی در عرض ۳۹۰ پیکسل، کارکرد صحیح صفحه هنگام باز شدن از دیسک، و نمایش کامل صفحه در حالت reduced motion.
- دسترسی‌پذیری: هر کنترل باید از طریق کیبورد قابل دسترسی باشد و فوکوس آن قابل مشاهده باشد.
- بررسی‌های خودکار: برای پروژه‌های React، نویسنده از یک دستور واحد استفاده می‌کند:
npm run check(که لنتینگ، تایپ‌چکینگ و بیلد را مدیریت می‌کند). اگر عامل بتواند آن را اجرا کند، خطاها را پیش از آنکه انسان ببیند، اصلاح می‌کند.
جزئیات: چه چیزهایی را حذف کنیم؟
«توجه» (Attention) برای مدل‌های زبانی یک منبع محدود است. هر خط در AGENTS.md باید لیاقت حضور در آنجا را داشته باشد. نویسنده در مورد گنجاندن موارد زیر هشدار می‌دهد:
- توصیه‌های مبهم: عباراتی مثل «کد تمیز و قابل نگهداری بنویس» یا «بهترین متدها را دنبال کن» بی‌فایده هستند چون عامل همین حالا باور دارد که دارد این کار را می‌کند.
- اطلاعات تکراری: توضیح ندهید React چیست یا لیست تمام کامپوننت‌ها را ننویسید؛ عامل می‌تواند خودش کد را بخواند. فقط چیزی را بنویسید که کد نمی‌تواند بگوید: قصد شما، محدودیت‌ها و تصمیمات.
- تاریخچه: از جملاتی مثل «ما قبلاً از X استفاده می‌کردیم و بعد به Y تغییر دادیم» پرهیز کنید، مگر اینکه روش قدیمی تله‌ای باشد که احتمالاً عامل در آن می‌افتد.
- اسرار: هرگز کلیدهای API، توکن‌ها یا رمزهای عبور را وارد نکنید، زیرا این فایل در مخزن کد قرار دارد.
- جستارهای طولانی: اگر بخشی نیاز به پاراگراف‌های پس‌زمینه دارد، آن را به سندی مجزا (مثلاً
DESIGN.mdبرای منطق طراحی) منتقل کنید و درAGENTS.mdبه آن لینک دهید.
پالایش تکرار شونده و اشتباهات رایج
یک فایل AGENTS.md نباید سندی ایستا باشد. موثرترین قوانین اغلب از دل باگ‌ها بیرون می‌آیند. برای مثال، در ۲۶ سپتامبر، نویسنده تست کرد که یک بخش «Hero» را به یک سایت تست مجزا منتقل کند. این کار در چهار قالب باعث شکست شد زیرا ورود بخش Hero منتظر سیگنالی از یک Preloader یا Nav بود که دیگر وجود نداشت. این اتفاق منجر به ایجاد یک قانون جدید شد:
- قانون ۹: هر بخش باید به‌طور مستقل شروع شود. ورودی که منتظر سیگنال Boot/Intro است، نباید به Preloader یا Nav برای ارسال آن وابسته باشد؛ تابع Fallback را از داخل افکت خودِ بخش نیز فراخوانی کن.
برای موثر نگه داشتن فایل، از این تله‌های رایج دوری کنید:
- توصیف به جای دستور: به جای اینکه بگویید «پروژه از توکن‌های طراحی استفاده می‌کند»، بگویید «از توکن‌های موجود استفاده کن. اگر به توکن جدیدی نیاز داری، آن را با یک کامنت به
tokens.cssاضافه کن. هرگز مقادیر Hex را هارد-کد نکن». - قوانین بدون دلیل: قانونی که دلیل داشته باشد، زمانی که عامل ایده «بهتری» دارد، پیروز می‌شود. قانونی بدون دلیل، اغلب نادیده گرفته می‌شود.
- مستندات قدیمی: یک
AGENTS.mdقدیمی بدتر از نبود آن است، زیرا عامل به آن اعتماد می‌کند. اگر فایلی جابه‌جا شود، عامل از روی نقشه قدیمی پیش می‌رود و با اعتماد به نفس کامل گم می‌شود.
استراتژی پیاده‌سازی
توسعه‌دهندگان مجبور نیستند این فایل‌ها را از صفر بنویسند. یک عامل می‌تواند پس از مدتی کار روی پروژه، اولین پیش‌نویس را آماده کند. می‌توانید اینگونه دستور دهید: «یک فایل AGENTS.md برای این پروژه بنویس: جای فایل‌ها، قوانینی که نباید شکسته شوند، نحوه اضافه کردن یک بخش و چک‌لیستی برای پایان کار».
سپس انسان پیش‌نویس را بررسی می‌کند، زبان مبهم را حذف کرده و «چرایی» پشت قوانین را اضافه می‌کند. این رویکرد نقش توسعه‌دهنده را از پرامپت‌نویسی مداوم به بازرسی سطح بالا (High-level Auditing) تغییر می‌دهد.
برای مدیریت پروژه‌های پیچیده، نویسنده پیشنهاد می‌کند فایل‌های AGENTS.md را در زیرپوشه‌ها قرار دهید. عامل‌ها فایلی را می‌خوانند که به کدی که در حال ویرایش آن هستند نزدیک‌تر است. برای مثال، یک پروژه ممکن است یک AGENTS.md برای نسخه HTML و یکی دیگر برای نسخه React داشته باشد، زیرا قوانین سایتی که با دبل‌کلیک روی فایل باز می‌شود با قوانین یک بیلد Next.js کاملاً متفاوت است. این کار اجازه می‌دهد زیر-ماژول‌های خاص، قوانین خود را داشته باشند که قوانین فایل ریشه را بازنویسی یا تکمیل کند.
چک‌لیست نهایی برای AGENTS.md شما
اگر در حال ساخت فایل خود هستید، از این اسکلت استفاده کنید تا مطمئن شوید موارد ضروری را پوشش داده‌اید:
- نام پروژه: عنوان واضح در بالا.
- ماهیت پروژه: ۱ تا ۲ جمله درباره پروژه و محدودیت اصلی آن.
- نقشه فایل‌ها: جای فایل‌های کلیدی و دستورات خاص درباره اینکه در هر کدام چه چیزی تغییر کند (یا دست نخورده بماند).
- قوانین غیرقابل تخریب: لیستی شماره‌دار از محدودیت‌ها، هر کدام همراه با یک دلیل واقعی.
- دستورالعمل کارهای رایج: راهنمای انجام متداول‌ترین عملیات (مثلاً اضافه کردن بخش) با الگوهای قابل تکرار.
- دستورات (Commands): لیستی از دستورات توسعه و بررسی (مانند
npm run check). - پیش از اتمام: چک‌لیست نهایی بررسی‌های دستی و خودکار.
با سرمایه‌گذاری ده دقیقه‌ای روی یک فایل پیکربندی در ریشه — که معمولاً بین ۴۶ تا ۱۰۲ خط است — نیاز به تکرار دستورات در هر جلسه چت جدید را از بین می‌برید و عامل هوش مصنوعی را از یک ابزار ناپایدار به یک عضو منضبط تیم تبدیل می‌کنید.
گفتگو