پروژه پایانی مهندسی نرم‌افزار چندایجنت: ساخت کارخانه کدنویسی موازی

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

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

برای اجرای این معماری به مدل‌های مختلفی مثل Claude و GPT و Gemini نیاز دارید. با توجه به این‌که دسترسی مستقیم یا پرداخت ارزی برای سرویس‌های خارجی از ایران با موانعی همراه است، می‌توانید ارکستراسیون را به‌گونه‌ای تنظیم کنید که از طریق گیت‌وی‌های واسط و تغییر آدرس پایه (Base URL) به مدل‌های ابری یا نمونه‌های محلی متصل شود.

الگوی تیم‌های مهندسی چندایجنت در سال 2026 روی ساختار مشخصی همگرا شده است: یک معمار برنامه‌ریزی می‌کند، N کدنویس در ورک‌تری‌های موازی کار می‌کنند، یک بازبین نقش گیت کنترلی را دارد و یک آزمون‌گر صحت کار را می‌سنجد. معماری کارخانه‌ای SWE-AF، پرامپت‌نویسی مبتنی بر نقش MetaGPT، گراف اکتور نوع‌دار AutoGen 0.4، پلتفرم Devin از Cognition و ابزار Droids از Factory، همگی مستقل از یکدیگر به همین الگو رسیده‌اند. ورک‌تری‌های موازی زمان واقعی اجرای کار (Wall-clock) را به نرخ پردازش (Throughput) تبدیل می‌کنند. در این میان، وضعیت مشترک (Shared State) و پروتکل‌های دست‌به‌دست‌کردن وظایف (Handoff) به اصلی‌ترین سطوح بروز خطا تبدیل می‌شوند. پروژه‌ی پایانی این است که چنین تیمی بسازید، آن را روی SWE-bench Pro ارزیابی کنید و گزارش دهید کدام تحویل‌ها با چه بسامدی دچار شکست می‌شوند.

فازهای تمرین‌شده: P11 · P13 · P14 · P15 · P16 · P17
زمان: 40 ساعت

صورت مسئله

بسترهای آزمایشی (Harnesses) کدنویسی تک‌ایجنتی در تسک‌های بزرگ به سقف توانایی خود می‌رسند. دلیل این اتفاق، ضعف یک ایجنت خاص نیست؛ بلکه کانتکست 200 هزار توکنی نمی‌تواند طرح معماری، چهار برش موازی از کدبیس، نظرات بازبین و خروجی تست‌ها را هم‌زمان در خود نگه دارد. کارخانه‌های چندایجنت مسئله را خرد می‌کنند: معمار مسئولیت طرح را بر عهده می‌گیرد، کدنویس‌ها پیاده‌سازی را در ورک‌تری‌های موازی انجام می‌دهند، بازبین نقش گیت کنترلی را ایفا می‌کند و آزمون‌گر همه چیز را اعتبارسنجی می‌کند. معماری «کارخانه» در SWE-AF، نقش‌ها در MetaGPT و گراف اکتور نوع‌دار در AutoGen، هر سه همین ساختار را توصیف می‌کنند.

نقطه‌ی آسیب‌پذیر اصلی، فرایند دست‌به‌دست‌کردن است: معمار چیزی طراحی می‌کند که کدنویس‌ها نمی‌توانند پیاده کنند؛ کدنویس‌ها diffهای متداخل تولید می‌کنند؛ بازبین کدی را تایید می‌کند که حاصل توهم مدل است؛ یا آزمون‌گر پیش از پایان کار کدنویس، تست‌ها را اجرا می‌کند و وارد مسابقه (Race) می‌شود. شما یکی از این تیم‌ها را می‌سازید، آن را روی 50 ایشوی SWE-bench Pro اجرا می‌کنید، تمام موارد دست‌به‌دست‌کردن را زیر نظر می‌گیرید و گزارش کالبدشکافی (Post-mortem) آن را منتشر می‌کنید.

مفاهیم پایه

نقش‌ها در واقع ایجنت‌های نوع‌دار (Typed agents) هستند. معمار (Claude Opus 4.7) ایشو را می‌خواند، برنامه‌ی اجرایی را می‌نویسد و آن را با رابط‌های مشخص به زیرتسک‌ها تقسیم می‌کند. کدنویس‌ها (Claude Sonnet 4.7، در N نمونه‌ی موازی که هر کدام در یک git worktree و ساندباکس Daytona کار می‌کنند) زیرتسک‌ها را مستقل از هم پیاده می‌کنند. بازبین (GPT-5.4) diff مرج‌شده را بررسی می‌کند و آن را تایید می‌نماید یا اصلاحات مشخصی را درخواست می‌کند. آزمون‌گر (Gemini 2.5 Pro) مجموعه‌ی تست‌ها را در محیطی ایزوله اجرا می‌کند و نتیجه‌ی قبولی یا رد را همراه با دست‌سازه‌ها (Artifacts) گزارش می‌دهد.

ارتباطات از طریق یک تابلوی تسک‌های مشترک (مبتنی بر فایل یا Redis) انجام می‌شود. هر نقش تسک‌هایی را برمی‌دارد که مجاز به پردازش آن‌ها است. تحویل وظایف با پیام‌های نوع‌دار تحت پروتکل A2A انجام می‌گیرد. چالش‌های هماهنگی عبارتند از: حل تعارضات مرج (توسط نقش هماهنگ‌کننده یا مرج سه‌طرفه‌ی خودکار)، همگام‌سازی وضعیت مشترک (برنامه‌ی اجرایی با شروع کار کدنویس‌ها قفل می‌شود و برنامه‌ریزی مجدد رویدادی جداگانه است) و گیت‌های کنترلی بازبین (بازبین نمی‌تواند تغییرات نوشته‌شده یا پیشنهادی خودش را تایید کند).

افزایش تصاعدی توکن (Token amplification) هزینه‌ی پنهان این ساختار است. هر مرز میان نقش‌ها، پرامپت‌های خلاصه‌سازی و کانتکست تحویل جدیدی اضافه می‌کند. اجرای تک‌ایجنتی با 40 نوبت گفت‌وگو (Turn)، در چهار نقش به 160 نوبت تبدیل می‌شود. شیوه‌نامه‌ی نمره‌دهی (Rubric) به طور ویژه بازدهی توکن را در مقایسه با خط مبنای تک‌ایجنتی می‌سنجد؛ چون مسئله فقط این نیست که «آیا سیستم چندایجنت کار می‌کند یا نه»، بلکه این است که «آیا به ازای هر دلار پرداختی می‌ارزد یا خیر».

معماری

GitHub issue URL
      |
      v
Architect (Opus 4.7)
   reads issue, produces plan with subtasks + interfaces
      |
      v
Task board (file / Redis)
      |
   +-- subtask 1 ---+-- subtask 2 ---+-- subtask 3 ---+-- subtask 4 ---+
   v                v                v                v                v
Coder A          Coder B          Coder C          Coder D          (4 parallel)
 (Sonnet)         (Sonnet)         (Sonnet)         (Sonnet)
 worktree A       worktree B       worktree C       worktree D
 Daytona          Daytona          Daytona          Daytona
      |                |                |                |
      +--------+-------+-------+--------+
               v
           merge coordinator  (three-way merge + conflict resolution)
               |
               v
           Reviewer (GPT-5.4)
               |
               v
           Tester  (Gemini 2.5 Pro)  -> passes? -> open PR
                                     -> fails?  -> route back to coder

پشته‌ی فناوری

• ارکستراسیون: LangGraph با وضعیت مشترک و زیرگراف‌های مجزا برای هر ایجنت
• پیام‌رسانی: پروتکل A2A (گوگل 2025) برای پیام‌های نوع‌دار بین ایجنت‌ها
• مدل‌ها: Opus 4.7 (معمار)، Sonnet 4.7 (کدنویس‌ها)، GPT-5.4 (بازبین)، Gemini 2.5 Pro (آزمون‌گر)
• ایزوله‌سازی ورک‌تری: دستور git worktree add برای هر کدنویس به‌همراه ساندباکس Daytona
• هماهنگ‌کننده‌ی مرج: مرج سه‌طرفه‌ی سفارشی به‌همراه حل تعارضات با میانجی‌گری مدل‌های زبانی
• ارزیابی: SWE-bench Pro (شامل 50 ایشو)، سناریوهای SWE-AF و HumanEval++ برای تست‌های واحد
• پایش‌پذیری: Langfuse با اسپن‌های برچسب‌گذاری‌شده بر اساس نقش و محاسبه‌ی توکن به تفکیک ایجنت
• استقرار: K8s که در آن هر نقش یک Deployment مجزا با قابلیت HPA بر اساس کارهای باقی‌مانده (Backlog) است

پیاده‌سازی از صفر

1. تابلوی تسک‌ها: فایلی بر پایه‌ی JSONL با پیام‌های نوع‌دار شامل plan_request، subtask، diff_ready، review_needed، test_needed، approved، rejected و replan_needed. ایجنت‌ها در تگ‌های مشخصی مشترک می‌شوند (Subscribe).

2. معمار: ایشوی GitHub را می‌خواند، Opus 4.7 را با قالبی اجرا می‌کند که رابط‌های دقیق زیرتسک‌ها (فایل‌های دستکاری‌شده، توابع عمومی، تاثیر روی تست‌ها) را الزامی می‌کند. سپس یک پیام plan_request به‌همراه گراف جهت‌دار بدون دور (DAG) از زیرتسک‌ها صادر می‌کند.

3. کدنویس‌ها: N ورکر موازی که هر کدام یک زیرتسک را از روی تابلو برمی‌دارند. هر کدام یک branch جدید با git worktree add به‌همراه یک ساندباکس Daytona می‌سازند، زیرتسک را پیاده می‌کنند و پیام diff_ready را با تکه کد (Patch) نهایی و تغییرات تست ارسال می‌کنند.

4. هماهنگ‌کننده‌ی مرج: پس از اتمام کار همه‌ی کدنویس‌ها، N شاخه را با مرج سه‌طرفه در یک branch تجمیعی (Staging) ادغام می‌کند. حل تعارض با کمک مدل زبانی فقط زمانی انجام می‌شود که تداخل در سطح فایل وجود داشته باشد.

5. بازبین: GPT-5.4 تغییرات ادغام‌شده را می‌خواند. این نقش نمی‌تواند کدهایی را که خودش نوشته تایید کند. در نهایت پیام approved (بدون عملیات اضافی) یا پیام review_feedback شامل بازخوردهای مشخص را برای ارسال مجدد به کدنویس مربوطه صادر می‌کند.

6. آزمون‌گر: Gemini 2.5 Pro تست‌ها را در ساندباکسی تمیز اجرا کرده و دست‌سازه‌ها را ذخیره می‌کند. سپس پیام test_passed یا test_failed را همراه با ردگیری خطای پشته (Stacktrace) ارسال می‌کند. تست‌های ناموفق مجدداً به کدنویس مسئول همان زیرتسک ارجاع داده می‌شوند.

7. حسابداری دست‌به‌دست‌کردن: هر پیامی که از مرز یک نقش عبور می‌کند، یک اسپن در Langfuse با اندازه‌ی داده و مدل استفاده‌شده ثبت می‌کند. میزان افزایش تصاعدی توکن به ازای هر زیرتسک را به این شکل حساب کنید: (توکن‌های کدنویس + بازبین + آزمون‌گر + سهم معمار) تقسیم بر توکن‌های کدنویس.

8. ارزیابی: سیستم را روی 50 ایشوی SWE-bench Pro اجرا کنید. معیارهای pass@1 و هزینه به ازای هر ایشوی حل‌شده را با خط مبنای تک‌ایجنتی (یک Sonnet 4.7 در یک ورک‌تری) مقایسه کنید.

9. کالبدشکافی: برای هر ایشوی ناموفق، مرحله‌ای از تحویل را که دچار شکست شده مشخص کنید (برنامه‌ی بیش‌ازحد مبهم، تداخل در مرج، تایید اشتباه بازبین یا ناپایداری تست‌ها). در پایان، هیستوگرام شکست‌های تحویل وظیفه را ترسیم کنید.

استفاده از ابزارهای واقعی

$ team run --issue https://github.com/acme/widget/issues/842
[architect] plan: 4 subtasks (parser, cache, api, migration)
[board]     dispatched to 4 coders in parallel worktrees
[coder-A]   subtask parser  -> 42 lines, tests pass locally
[coder-B]   subtask cache   -> 88 lines, tests pass locally
[coder-C]   subtask api     -> 31 lines, tests pass locally
[coder-D]   subtask migration -> 19 lines, tests pass locally
[merge]     3-way merge: 0 conflicts
[reviewer]  comments on cache (thread pool sizing); routed to coder-B
[coder-B]   revision: 92 lines; submits
[reviewer]  approved
[tester]    all 412 tests pass
[pr]        opened #3382   4 coders, 1 revision, $4.90, 18m

خروجی این درس

فایل outputs/skill-multi-agent-team.md خروجی نهایی است. این تیم با دریافت آدرس ایشو و میزان موازی‌سازی، یک PR آماده‌ی مرج به‌همراه گزارش مصرف توکن به تفکیک نقش‌ها ارائه می‌دهد.

تمرین‌ها

1. در میانه‌ی اجرا باگی واضح وارد diff کنید (مثلاً یک return None اضافی قبل از بدنه‌ی اصلی تابع). نرخ تایید اشتباه بازبین را بسنجید. پرامپت بازبین را آن‌قدر بهینه‌سازی کنید تا نرخ تایید اشتباه به زیر 5% برسد.

2. تعداد کدنویس‌ها را به دو مورد کاهش دهید (معمار + دو کدنویس + بازبین + آزمون‌گر، به‌طوری‌که هر کدنویس دو زیرتسک را به‌صورت متوالی اجرا کند). زمان واقعی و نرخ قبولی را مقایسه کنید.

3. هماهنگ‌کننده‌ی مرج را با محدودیت «تنها یک نویسنده برای هر فایل» جایگزین کنید (زیرتسک‌ها باید مجموعه‌ای کاملاً مجزا از فایل‌ها را تغییر دهند). بار برنامه‌ریزی روی دوش معمار را در این حالت بسنجید.

4. بازبین را از GPT-5.4 به Claude Opus 4.7 تغییر دهید. نرخ تایید اشتباه و تغییرات هزینه‌ی توکن را محاسبه کنید.

5. نقش پنجمی اضافه کنید: مستندساز (Haiku 4.5). این نقش پس از بازبینی، متن تغییرات (Changelog) را می‌نویسد. بررسی کنید آیا کیفیت مستندات، هزینه‌ی توکن اضافی را توجیه می‌کند یا خیر.

اصطلاحات کلیدی

برای مطالعه‌ی بیشتر

• معماری کارخانه‌ای SWE-AF — مرجع کارخانه‌های چندایجنت در سال 2026
• MetaGPT — فریم‌ورک چندایجنت مبتنی بر نقش
• AutoGen v0.4 — فریم‌ورک مایکروسافت بر پایه‌ی اکتورهای نوع‌دار
• Cognition AI (Devin) — محصول مرجع در این حوزه
• Factory Droids — محصول مرجع جایگزین
• پروتکل A2A گوگل — مشخصات پیام‌رسانی بین ایجنت‌ها
• مستندات git worktree — بستر پایه‌ای برای ایزوله‌سازی
• SWE-bench Pro — بستر اصلی ارزیابی سیستم‌ها