تصور کنید تیمی از برنامه‌نویسان هستید که از بازبینی‌های خودکار خسته شده‌اید چون هوش مصنوعی مدام استانداردهای داخلی شما را نادیده می‌گیرد. در هنگام پیکربندی گیت‌هاب کوپایلت برای بازبینی‌های خودکار کد، توسعه‌دهندگان اغلب با این سردرگمی مواجه می‌شوند که کدام فایل‌ها واقعاً برای هدایت رفتار هوش مصنوعی ضروری هستند. برای حل این مشکل، باید بدانید کدام فایل تنظیمات واقعاً روی رفتار مدل اثر می‌گذارد و کدام یک صرفاً یک مستند تکمیلی است.
یکی از نقاط بحث‌برانگیز این است که آیا وجود فایل AGENTS.md برای اینکه کوپایلت قوانین خاص یک مخزن (Repository) را درک کند، الزامی است یا خیر. طبق مستندات گیت‌هاب (GitHub)، پاسخ کوتاه منفی است؛ فایل AGENTS.md برای عملکرد بازبینی کد یا پایبندی به استانداردهای پروژه ضروری نیست. در عوض، گیت‌هاب مکانیزم هدفمندتری را برای این منظور ارائه داده است: فایل .github/copilot-instructions.md. درک تفاوت بین این دو فایل برای تیم‌هایی که می‌خواهند گردش‌کار توسعه مبتنی بر هوش مصنوعی خود را بدون ایجاد مستندات تکراری یا متضاد بهینه کنند، حیاتی است.
همان‌طور که در تحلیل‌های قبلی ما درباره‌ی بهینه‌سازی گردش‌کار توسعه با هوش مصنوعی اشاره کردیم، تفکیک بین «قوانین اجرایی» و «زمینهٔ کلی» کلید کاهش توهمات مدل است. در اینجا، فایل copilot-instructions.md نقش همان دفترچه قانون را ایفا می‌کند.
ابزار اصلی برای شکل دادن به نحوه بازبینی درخواست‌های ادغام (Pull Requests) توسط کوپایلت، همان فایل .github/copilot-instructions.md است. این فایل به‌طور خاص برای تعریف قوانین سراسری مخزن، استانداردهای کدنویسی و انتظارات از بازبینی طراحی شده است. وقتی کوپایلت (Copilot) یک بازبینی کد را انجام می‌دهد، به دنبال این دستورالعمل‌های سفارشی می‌گردد تا مطمئن شود پیشنهاداتش با راهنمای سبک (Style Guide)، محدودیت‌های معماری و معیارهای کیفی تیم همراستا است. این قابلیت‌ها در راستای تبدیل کوپایلت به یک تأییدکننده فعال در مدیریت درخواست‌های ادغام است که کنترل بیشتری بر فرآیند ادغام کد فراهم می‌کند. به عنوان مثال، اگر تیمی الزام دارد که تمام نقاط انتهایی API جدید حتماً شامل الگوهای خاصی برای مدیریت خطا باشند، یا تمام متدهای عمومی باید با فرمت خاصی مستند شوند، این قوانین باید صراحتاً در فایل copilot-instructions.md ذکر شوند. با قرار دادن این دستورالعمل‌ها در اینجا، تیم تضمین می‌کند که هوش مصنوعی یک نقطه مرجع مستقیم برای تشخیص اینکه چه کدی در آن مخزن خاص «درست» تلقی می‌شود، در اختیار دارد.
در مقابل، فایل AGENTS.md هدف گسترده‌تر و کلی‌تری دارد. این فایل برای ارائه زمینهٔ مشترک به عامل (Agent) — شبیه به یک شناسنامه جامع از پروژه که هر کسی (چه مدل بازبینی و چه مدل تولید کد و سایر عوامل هوش مصنوعی) بتواند آن را بخواند — به کار می‌رود. این رویکرد با تلاش‌های گسترده‌تر برای استانداردسازی قابلیت‌های عامل‌های هوش مصنوعی همسو است تا تعامل با مدل‌ها در محیط‌های مختلف یکپارچه شود. اگرچه کوپایلت ممکن است از اطلاعات موجود در AGENTS.md استفاده کند، اما این فایل برای زمینه‌های سطح بالای پروژه مناسب‌تر است؛ مواردی مانند معماری کلی سیستم، الگوهای طراحی عمدی که ممکن است برای یک هوش مصنوعی غیرمنطقی یا متناقض به نظر برسند، یا بخش‌های خاصی از کد که به دلیل پیچیدگی یا شکنندگی نیاز به بررسی دقیق‌تری دارند. در واقع، اگر copilot-instructions.md کتاب قانون بازبینی است، AGENTS.md پایگاه دانش عمومی برای هر عامل هوش مصنوعی است که با مخزن تعامل دارد. اشتباه بسیاری از توسعه‌دهندگان این است که تصور می‌کنند یکی از این فایل‌ها جایگزین دیگری می‌شود؛ در حالی که در واقعیت، آن‌ها ابزارهایی مکمل هستند که برای سطوح مختلفی از انتزاع (Abstraction) استفاده می‌شوند.
از نظر فنی، کوپایلت دستورالعمل‌های سفارشی مخزن، دستورات عامل و مهارت‌های عامل را مستقیماً از شاخه‌ای (Branch) که در حال بازبینی است می‌خواند. این بدان معناست که برای اثرگذاری قوانین، فایل .github/copilot-instructions.md باید در شاخهٔ هدف (Head Branch) مربوط به درخواست ادغام موجود باشد. علاوه بر این، مالکان مخزن این توانایی را دارند که این دستورالعمل‌های سفارشی را از طریق تنظیمات مخزن فعال یا غیرفعال کنند. به‌طور پیش‌فرض، این دستورالعمل‌ها فعال هستند، به این معنی که به محض ثبت (Commit) فایل در شاخه، کوپایلت شروع به گنجاندن آن قوانین در منطق بازبینی خود می‌کند. این قابلیت خواندنِ شاخه-محور به تیم‌ها اجازه می‌دهد تا استانداردهای کدنویسی خود را در طول زمان تکامل دهند؛ به گونه‌ای که با رشد پروژه، دستورالعمل‌ها می‌توانند در یک شاخه ویژگی (Feature Branch) به‌روزرسانی شده و پیش از ادغام در کد اصلی، آزمایش شوند. با این حال، باید به خاطر داشت که حتی با دقیق‌ترین تنظیمات، بازبینی‌های خودکار کوپایلت اعتبار تأیید نهایی برای ادغام کد ندارند و نظارت انسانی همچنان ضروری است.
برای تیم‌هایی که از صفر شروع کرده‌اند، ساده‌ترین و موثرترین استراتژی، اولویت دادن به ایجاد فایل .github/copilot-instructions.md است. این کار تضمین می‌کند که هدف فوری — یعنی بهبود کیفیت و یکپارچگی بازبینی‌های کد — محقق شود. تنها پس از تثبیت قوانین بازبینی است که یک تیم باید به فکر افزودن فایل AGENTS.md در ریشه مخزن باشد، آن هم در صورتی که متوجه شوند عوامل هوش مصنوعی آن‌ها فاقد درک گسترده‌تری از معماری پروژه یا شیوه‌های تست هستند. استفاده از AGENTS.md به عنوان تنها منبع برای قوانین بازبینی توصیه نمی‌شود، زیرا روش کم‌دقتی برای انتقال رفتارهای خاص و انتظارات بازبینی است.
هدف نهایی از استفاده از این فایل‌های پیکربندی، کاهش «نویز» در بازبینی‌های تولیدشده توسط هوش مصنوعی است. بدون دستورالعمل‌های خاص، کوپایلت به داده‌های آموزشی عمومی خود تکیه می‌کند که ممکن است الگوهایی را پیشنهاد دهد که از نظر فنی درست هستند اما با استانداردهای داخلی یک پروژه ناسازگارند. با بهره‌گیری از .github/copilot-instructions.md برای قوانین رفتاری و AGENTS.md برای زمینه معماری، توسعه‌دهندگان می‌توانند کوپایلت را از یک دستیار عمومی به یک عضو متخصص تبدیل کنند که ظرافت‌های کدبیس خاص آن‌ها را می‌شناسد. این رویکرد ساختاریافته برای هدایت هوش مصنوعی، نیاز به اصلاحات دستی را به حداقل می‌رساند و تضمین می‌کند که فرآیند بازبینی خودکار، ارزش واقعی به چرخه حیات توسعه اضافه می‌کند.
گام بعدی شما
- فایل
.github/copilot-instructions.mdرا ایجاد کرده و ۳ قانون طلایی کدنویسی تیمتان را در آن بنویسید. - بررسی کنید که آیا قوانین بازبینی شما در شاخه‌های Feature قرار دارند یا فقط در Main.
- اگر مدل در درک روابط بین ماژول‌ها مشکل دارد، یک فایل AGENTS.md برای توصیف معماری کلی اضافه کنید.
اما مدیریت این دستورالعمل‌ها در پروژه‌های عظیم، چالش‌های جدیدی در زمینهٔ تداخل قوانین ایجاد می‌کند — به بررسی ما درباره‌ی پروتکل‌های مدیریت زمینه (MCP) مراجعه کنید.
گفتگو