Agent Merge در VS Code چیست؟ راهنمای تکمیل امن Pull Request با Agent
Agent Merge در VS Code را فعال و کنترل کنید تا Agent بازخورد Review، خطای CI و Merge Conflict را پیگیری کند؛ بدون اینکه تصمیم نهایی Merge و بازبینی انسانی حذف شود.
Agent Merge قابلیتی در پنجره Agents ویژوال استودیو کد است که Pull Request مرتبط با یک Session را زیر نظر می‌گیرد و برای رفع موانع، Agent را دوباره به کار می‌اندازد. این موانع می‌توانند Commentهای Review، Checkهای الزامی شکست‌خورده یا ناسازگاری Branch با شاخه مقصد باشند.
نام قابلیت ممکن است این تصور را ایجاد کند که همه چیز باید خودکار Merge شود؛ در حالی که تنظیم پیش‌فرض ادغام خودکار خاموش است. استفاده حرفه‌ای یعنی نگهداری PR را به Agent واگذار کنید، اما Scope، Permission، تست و تصمیم نهایی را همچنان تحت کنترل انسان نگه دارید.
Agent Merge در VS Code دقیقاً چه کاری انجام می‌دهد؟
Agent Merge یک حلقه نگهداری برای Pull Request ایجاد می‌کند. وقتی Reviewer نظر تازه‌ای می‌گذارد، Required check شکست می‌خورد یا Base branch جلو می‌افتد، قابلیت می‌تواند Session را دوباره فعال کند تا Agent مانع را بررسی و تغییر لازم را روی Branch همان PR اعمال کند.
پس از تغییر، Workflowها دوباره اجرا می‌شوند و Agent Merge منتظر نتیجه می‌ماند. چرخه تا زمانی ادامه پیدا می‌کند که PR آماده ادغام شود، تنظیم غیرفعال شود یا Session به Branch یا PR دیگری منتقل شود.
| مانع | اقدام احتمالی Agent | کنترل انسانی |
|---|---|---|
| Review thread حل‌نشده | اصلاح کد و پاسخ به Comment | صحت برداشت از نظر Reviewer |
| Changes requested | اجرای تغییر تکمیلی | تأیید دوباره Reviewer |
| Required CI شکست‌خورده | تحلیل Log و Fix | کنترل ریشه خطا و Regression |
| Branch عقب‌افتاده | به‌روزرسانی با Base | بررسی نتیجه Integration |
| Merge conflict | حل Conflict و Sync | حفظ قصد هر دو تغییر |
| PR آماده | Merge یا افزودن به Queue در صورت مجوز | تصمیم نهایی و Rollback |
پیش‌نیازهای Agent Merge
این قابلیت در VS Code 1.136 به‌صورت Preview معرفی شده و ممکن است تغییر کند. باید Agents window، یک Agent قابل استفاده و Session مرتبط با Pull Request داشته باشید. Repository باید Workflow و Required checkهای قابل اتکا داشته باشد؛ وگرنه آماده‌شدن ظاهری PR معیار کافی نیست.
- VS Code و افزونه‌های مرتبط را از منبع رسمی و به نسخه جدید ارتقا دهید.
- Repository را Commit کنید و Session را ترجیحاً در Worktree جدا اجرا کنید.
- Pull Request باید به همان Branch تحت پیگیری Session متصل باشد.
- Branch protection و Required checks را پیش از فعال‌سازی تنظیم کنید.
- فایل‌های حساس و عملیات Deploy باید Approval دستی داشته باشند.
- Reviewer انسانی و Code Ownerهای مسیرهای حساس را حفظ کنید.
چطور Agent Merge را فعال کنیم؟
ابتدا تنظیم chat.agentMerge.enabled را در Settings فعال کنید. سپس Agents window را باز کنید، Session متصل به Pull Request را انتخاب و از نوار عنوان Agent Merge را بزنید. گزینه Enable Agent Merge پایش را برای همان Session آغاز می‌کند.
راه دیگر، اجرای Configure Agent Merge for Active Session از Command Palette است. روی ویندوز و لینوکس Command Palette با Ctrl+Shift+P باز می‌شود. پس از باز شدن منو، دقیقاً مشخص کنید Agent کدام Blockerها را اجازه دارد برطرف کند.
چرا بهتر است با یک Session آزمایشی شروع کنیم؟
فعال‌شدن Agent Merge سطح Session را به Autopilot با Assisted permissions تغییر می‌دهد و هر Repair turn می‌تواند فایل و Branch را تغییر دهد و Model request مصرف کند. یک Repository آزمایشی با CI سریع کمک می‌کند رفتار Permission، Reply و Conflict را پیش از استفاده روی کد حساس بشناسید.
چطور Agent Merge را متوقف کنیم؟
در نوار عنوان Agent Merge را باز و Disable Agent Merge را انتخاب کنید. اگر Session Branch یا Pull Request دیگری را دنبال کند، قابلیت خودکار خاموش می‌شود و برای هدف جدید باید دوباره فعال شود. تغییر هدف بدون تأیید صریح نباید پایش قبلی را ادامه دهد.
تنظیم Address Reviews
گزینه chat.agentMerge.addressReviews تعیین می‌کند Agent نظرهای حل‌نشده، Changes requested و Commentهای تازه Maintainer یا Copilot reviewer را پیگیری کند. مقدار پیش‌فرض آن فعال است.
برای جلوگیری از برداشت اشتباه، توضیح Pull Request و معیار پذیرش را دقیق بنویسید. Commentهایی مثل «این را بهتر کن» برای Agent مبهم‌اند. Reviewer باید رفتار مورد انتظار، سناریوی شکست و محدودیت تغییر را در نظر خود مشخص کند.
پاسخ خودکار Agent به Review thread با Attribution مشخص می‌شود؛ تنظیم chat.agentMerge.replyAttribution به‌طور پیش‌فرض روشن است. این برچسب را خاموش نکنید، چون اعضای تیم باید بدانند کدام پاسخ توسط Automation ایجاد شده است.
تنظیم Fix CI
گزینه chat.agentMerge.fixCI اجازه می‌دهد Agent Required check شکست‌خورده را بررسی کند. این قابلیت فقط زمانی مفید است که CI خطای قابل بازتولید و Log کافی داشته باشد. Flaky test، قطعی سرویس بیرونی یا محدودیت Runner نباید با تغییر تصادفی کد پنهان شود.
- نام Check و Commit شکست‌خورده را کنترل کنید.
- تفاوت خطای کد با خطای Infrastructure را مشخص کنید.
- Test را در محیط ایزوله بازتولید کنید.
- Diff اصلاحی را فقط به علت اصلی محدود کنید.
- هم Test هدفمند و هم مجموعه Regression را اجرا کنید.
- اگر خطا ناپایدار است، آن را ثبت و از Retry کور جلوگیری کنید.
Agent نباید برای سبزکردن Pipeline، Test را حذف، Assertion را ضعیف یا Check الزامی را غیرفعال کند. فایل Workflow و پیکربندی تست را مسیر حساس قرار دهید.
حل Merge Conflict با Agent
گزینه chat.agentMerge.resolveConflicts به Agent اجازه می‌دهد Branch عقب‌افتاده را Update و Conflict را حل کند. حل Conflict فقط حذف Markerهای Git نیست؛ باید قصد تغییر Feature و تغییر Base هر دو حفظ شود.
پس از Resolution، Diff نهایی را نسبت به Base تازه بخوانید و Testهای Integration را دوباره اجرا کنید. موفقیت هر Branch قبل از Merge ثابت نمی‌کند ترکیب آن‌ها صحیح است. اگر Conflict در Migration، Dependency lockfile یا قرارداد API رخ داده، Reviewer متخصص همان بخش باید نتیجه را تأیید کند.
| نوع فایل | ریسک | بازبینی لازم |
|---|---|---|
| کد Business | تغییر رفتار | Test سناریوی ترکیبی |
| Migration | از دست رفتن یا ناسازگاری داده | DBA و اجرای آزمایشی |
| Lockfile | نسخه Dependency متفاوت | Restore تمیز و Security scan |
| Workflow CI | دورزدن Gate | Code Owner و Audit |
| Configuration | رفتار متفاوت محیط | مقایسه Stage و Production |
| Instruction فایل Agent | تغییر رفتار Automation | Review مستقل انسانی |
آیا Agent اجازه Merge خودکار داشته باشد؟
تنظیم chat.agentMerge.mergePullRequest سه حالت اصلی دارد. مقدار never ادغام خودکار را غیرفعال می‌کند و برای شروع بهترین انتخاب است. حالت ifUnchanged فقط تا زمانی اجازه Merge می‌دهد که Repair turn جدید PR را تغییر نداده باشد. حالت always پس از انجام نگهداری انتخاب‌شده می‌تواند Merge کند.
برای Repository آموزشی یا Production، از never شروع کنید. تنها بعد از چند دوره ارزیابی، Required checks کامل، Branch protection و Rollback روشن درباره حالت دیگر تصمیم بگیرید. مسیرهای احراز هویت، پرداخت، Secret، Infrastructure و Migration را از Merge خودکار مستثنا کنید.
انتخاب Merge Method
گزینه chat.agentMerge.mergeMethod روش ادغام را تعیین می‌کند. مقدار auto نخستین روش سازگار Repository را با ترتیب Squash، Merge commit و Rebase انتخاب می‌کند. می‌توانید یکی از روش‌ها را صریح الزام کنید.
روش را بر اساس سیاست تاریخچه تیم انتخاب کنید، نه راحتی Agent. اگر Commitهای میانی ارزش مستقلی ندارند، Squash تاریخچه تمیزتری می‌دهد. اگر حفظ ساختار Branch ضروری است Merge commit مناسب‌تر است. تغییر این تصمیم باید در Repository policy مستند شود.
گیت امن پیشنهادی برای اولین اجرا
- یک Pull Request کوچک و بدون دسترسی Production انتخاب کنید.
- Agent Merge را فقط برای Address Reviews فعال کنید.
- Fix CI و Resolve Conflicts را در دور اول خاموش نگه دارید.
- Merge خودکار را روی never قرار دهید.
- یک Comment دقیق با معیار پذیرش ثبت کنید.
- Repair turn، Tool callها و Diff همه فایل‌ها را بررسی کنید.
- Test را مستقل در محیط تیم اجرا کنید.
- Reviewer انسانی Thread را Resolve و Approval را ثبت کند.
- Merge را دستی انجام دهید و نتیجه Deploy آزمایشی را بسنجید.
پس از موفقیت، هر قابلیت را جداگانه اضافه کنید. روشن‌کردن هم‌زمان Review، CI، Conflict و Merge پیدا کردن علت رفتار ناخواسته را دشوار می‌کند.
بازبینی تغییرات Agent در Agents window
نمای Changes فایل‌های تغییرکرده، اضافه‌شده و حذف‌شده را نشان می‌دهد. هر فایل را در Diff باز کنید، فایل‌های Untracked را فراموش نکنید و تغییرات خارج از Workspace را هم ببینید. قابلیت Mark as Reviewed فقط وضعیت بازبینی را ثبت می‌کند و جای تست نیست.
اگر بخشی نیاز به اصلاح دارد، Range را انتخاب و با Add Feedback توضیح دقیق بدهید. پس از Turn بعدی، Reviewed state فایل تغییرکرده پاک می‌شود تا دوباره آن را بررسی کنید. این رفتار کمک می‌کند تغییر جدید بدون Review باقی نماند.
برای طراحی گیت انسانی، راهنمای بازبینی Pull Request با AI را بخوانید. اگر Copilot reviewer نیز در PR فعال است، راهنمای Copilot Code Review روش مدیریت Commentها را توضیح می‌دهد.
Permission و Worktree چه نقشی دارند؟
Worktree تغییرات Agent را از Workspace فعال جدا می‌کند، اما به‌تنهایی Sandbox امنیتی نیست و دسترسی فرمان یا شبکه را محدود نمی‌کند. Permission مشخص می‌کند کدام Tool call نیاز به Approval دارد. برای Session پایش‌شونده، دسترسی را کوتاه‌مدت و در سطح Session نگه دارید.
Workspace ناشناس را در Restricted mode باز کنید. فایل‌های حساس مانند .env، تنظیمات Deploy و Credential را از Auto-approval خارج کنید. MCP Serverها و Extensionهایی که Agent می‌تواند فراخوانی کند باید منبع معتبر و Scope حداقلی داشته باشند.
مصرف مدل و جلوگیری از حلقه بی‌پایان
هر بار فعال‌شدن Agent برای رفع Blocker یک Model request مصرف می‌کند. Comment متناقض، Test ناپایدار یا Policy غیرممکن می‌تواند چرخه اصلاح ایجاد کند. سقف مصرف و هشدار حساب را فعال و History Session را دوره‌ای بررسی کنید.
- معیار پایان را در توضیح PR روشن بنویسید.
- Commentهای متناقض را پیش از ادامه حل کنید.
- Flaky test را با Retry نامحدود پنهان نکنید.
- برای تغییرات تکراری، Agent Merge را Disable و علت را دستی بررسی کنید.
- پس از هر Repair turn، Scope Diff و مصرف را ثبت کنید.
اشتباه‌های رایج
- فعال‌کردن always در اجرای اول: فرصت بازبینی نهایی حذف می‌شود.
- اعتماد به سبزشدن CI: ممکن است Agent Test یا Workflow را ضعیف کرده باشد.
- حل Conflict با انتخاب یک سمت: نیاز Feature دیگر از بین می‌رود.
- استفاده روی Branch اشتباه: تغییر در PR مورد انتظار ثبت نمی‌شود.
- نادیده‌گرفتن هزینه Turnها: حلقه نگهداری مصرف پیش‌بینی‌نشده ایجاد می‌کند.
- برابر دانستن Worktree و Sandbox: دسترسی Toolها همچنان گسترده می‌ماند.
جمع‌بندی
Agent Merge می‌تواند بخش خسته‌کننده پایان Pull Request را پیگیری کند: پاسخ به Review، رفع CI، Update Branch و حل Conflict. مزیت آن در تکرار کنترل‌شده است، نه حذف Reviewer و Merge policy.
با یک PR کوچک، گزینه Address Reviews و Merge روی never شروع کنید. سپس Diff، تست، Permission و مصرف را بسنجید و قابلیت‌های دیگر را مرحله‌ای اضافه کنید. هر Repair turn باید قابل توضیح، محدود و قابل بازگشت باشد.
امروز Agent Merge را فقط روی یک Pull Request کم‌ریسک و با mergePullRequest=never آزمایش کنید؛ یک Blocker مشخص انتخاب کنید و نتیجه را پیش از هر Merge با Diff، Test و Approval انسانی بسنجید.