تجربه تغییر از ربات بازبینی کد تا Agent آگاه به قوانین تیم

چرا برای GitLab داخلی یک Agent سفارشی Code Review ساختیم

چند وقت پیش متوجه شدیم بخش قابل توجهی از Code Reviewهای تیم، در حال تکرار یک الگوی ثابت است.

Reviewerها بارها و بارها موارد مشابهی را بررسی می‌کردند:

• تغییرات خارج از Scope

• نقض استانداردهای تیم

• استفاده نادرست از Hookها

• الگوهای ناسازگار با معماری پروژه

• Refactorهای نامرتبط با Ticket

در نگاه اول، راه‌حل واضح به نظر می‌رسید:

«یک AI Code Reviewer اضافه کنیم.»

اما هرچه بیشتر بررسی کردیم، متوجه شدیم مسئله اصلی Code Review نیست.

مسئله اصلی اینه که بخش زیادی از دانش Review تیم فقط داخل ذهن Reviewerها وجود داره.

مسئله واقعی

فرض کنید توی تیم شما Ruleهایی مثل این‌ها وجود داره:

• استفاده مستقیم از fetch ممنوعه

• همه Modalها باید از Wrapper داخلی استفاده کنن

• تغییرات خارج از Scope Ticket باید Flag بشن

• برای React Query یه الگوی مشخص وجود داره

• بعضی Importها فقط از مسیرهای مشخص مجازن

این‌ها Ruleهای عمومی صنعت نیستن.

این‌ها Ruleهای تیم شما هستن.

و معمولاً هم توی یکی از این سه حالت نگهداری میشن:

• داخل ذهن Reviewerها

• داخل Wiki

• داخل Documentهای پراکنده

در نتیجه اجرای این Ruleها همیشه یکسان نیست.

Team-Aware Review Agent چیست؟

تعریف ما ساده بود:

Agent آگاه به قوانین تیم: ابزاری که Ruleهای نسخه‌بندی‌شدهٔ تیم را روی هر Merge Request اجرا می‌کنه.

نه Ruleهای Generic یک Vendor.

نه فقط Ruleهای عمومی .

بلکه Ruleهای واقعی تیم.

Review Botهای عمومی:

✓ Ruleها داخل خود ابزار تعریف شدن

✓ روی Best Practiceهای عمومی صنعت تمرکز دارن

✓ برای اکثر تیم‌ها جواب میدن

✓ سریع راه میفتن

✓ معمولاً چیزی از استانداردهای خاص تیم شما نمیدونن

Agent آگاه به قوانین تیم:

✓ Ruleها داخل Repository تیم نگهداری میشن

✓ دقیقاً همون استانداردهایی رو اجرا میکنه که تیم تعریف کرده

✓ با هر Pull Request میتونه تکامل پیدا کنه

✓ Agent و Reviewer از یک مجموعه Rule مشترک استفاده میکنن

✓ برای GitLab داخلی و فرآیندهای اختصاصی تیم انعطاف بیشتری داره

آیا ابزارهای آماده وجود ندارند؟

چرا.

ابزارهای بسیار خوبی وجود دارند:

• CodeRabbit

• GitLab Duo

• Qodo

• Greptile

• SonarQube

• Semgrep

اگر از GitHub یا GitLab Cloud استفاده می‌کنید و Ruleهای خاصی هم ندارید، به احتمال زیاد همین ابزارهای آماده کاملاً نیازتون رو برطرف می‌کنن.

این مقاله درباره این نیست که Agent سفارشی از CodeRabbit یا GitLab Duo بهتره.

موضوع اینه که برای بعضی تیم‌ها، به خاطر محدودیت‌ها یا فرآیندهای خاص، یک Agent سفارشی می‌تونه Trade-off بهتری داشته باشه.

محدودیت‌های ما

ما چند نیاز مشخص داشتیم:

GitLab Self-Hosted

بخشی از زیرساخت ما داخل شبکه سازمانی قرار داره.

Ruleهای اختصاصی تیم

می‌خواستیم Ruleها کنار کد نگهداری بشن و همراه Repository تغییر کنن.

Comment فارسی

Reviewerهای تیم فارسی‌ تعامل میکنن.

Scope Creep Detection

می‌خواستیم تغییرات نامرتبط با Ticket به صورت صریح Flag بشن.

ایده اصلی

به جای ساختن یک Review Bot دیگه، تصمیم گرفتیم دانش Review تیم را Version-Control کنیم.

ساختار ساده‌ای شبیه این:

.cursor/skills/gitlab-mr-review/
├── SKILL.md
├── STANDARDS.md
├── FRONTEND-GUIDELINES.md
└── scripts/setup-glab.sh

نمونه‌ای از یک Rule:

### Scope Rule

هر تغییری که مستقیماً به Ticket فعلی مرتبط نباشد:

Severity: Critical

Action:
- Revert
یا
- انتقال به MR جدا

و نمونه‌ای دیگر:

### Frontend Rule

استفاده مستقیم از fetch مجاز نیست.

برای تمام درخواست‌ها باید از apiClient استفاده شود.

مزیت این رویکرد این بود که:

• Ruleها قابل Review شدند

• Ruleها Version-Control شدند

• Agent و Reviewer از یک منبع حقیقت استفاده کردند

تجربه استفاده

امروز برای شروع Review معمولاً کافیه بنویسم:

MR !263

سپس Agent:

• مرج ریکوئست !263 رو از GitLab می‌خونه

• فقط روی Diff تغییرات تمرکز می‌کنه

• Ruleهای تعریف‌شده در Repository رو بارگذاری می‌کنه

• یافته‌ها رو بر اساس Severity دسته‌بندی می‌کنه

• Commentهای فارسی RTL رو به‌صورت Inline روی MR ثبت می‌کنه

• یک Summary نهایی از Review منتشر می‌کنه

• و Author مرج ریکوئست رو برای مشاهده نتایج منشن می‌کنه

نمونه خروجی

<div dir="rtl" style="text-align:right;">
<strong>[Critical]</strong>

این تغییر ارتباط مستقیمی با Ticket فعلی ندارد.
پیشنهاد می‌شود در MR جداگانه ارسال شود.
</div>

یا:

<div dir="rtl" style="text-align:right;">
<strong>[High]</strong>

Dependency مورد نیاز در useEffect وجود ندارد و ممکن است باعث رفتار غیرمنتظره در Renderهای بعدی شود.
</div>

معماری

MR !263
      │
      ▼
Cursor Agent
      │
      ▼
Team Rules (Git)
      │
      ▼
glab + GitLab API
      │
      ▼
Comments & Summary

سه جزء اصلی وجود دارد:

• Agent

• Ruleهای Repository

• GitLab API

نتایج

هدف این پروژه جایگزین کردن Reviewerها نبود.

هدف این بود که Agent بخش‌های تکراری و مبتنی بر Rule را پوشش بده تا Reviewerها بتوانند روی موضوعات مهم‌تر تمرکز کنند.

نتیجه عملی:

• بررسی Ruleهای تکراری به‌صورت خودکار انجام میشه

• Scope Creep زودتر شناسایی میشه

• Commentها ساختار و کیفیت یکسان‌تری پیدا میکنن

• تمرکز Reviewerها از Rule Checking به Architecture Review و Business Logic منتقل میشه

به بیان ساده، زمان کمتری صرف یادآوری استانداردهای تیم میشه و زمان بیشتری صرف تحلیل واقعی تغییرات و تصمیم‌های مهندسی.

محدودیت‌ها

این Agent کامل نیست و قرار هم نیست جای Reviewer انسانی رو بگیره.

چند محدودیت مهم داره:

• تصمیم نهایی برای Merge رو نمی‌گیره

• Context کامل محصول و نیازمندی‌های کسب‌وکار رو نمی‌فهمه

• ممکنه بعضی Commentها دقیق یا کاربردی نباشن

• Ruleها نیاز به نگه‌داری و به‌روزرسانی مداوم دارن

• Inline Commentها همیشه روی بهترین Line قرار نمی‌گیرن

• مثل هر سیستم مبتنی بر LLM، ممکنه گاهی برداشت اشتباه داشته باشه

به همین دلیل Human Review همچنان بخش ضروری فرآیند باقی می‌مونه.

Agent می‌تونه Ruleها، الگوهای تکراری و موارد مشکوک رو پیدا کنه، اما تصمیم‌های مهندسی، معماری و Product Context همچنان به قضاوت انسانی نیاز دارن.

پیشنهادی که برای ما بهترین نتیجه رو داشت

به جای اینکه Agent رو جایگزین Human Review کنیم، از یک رویکرد ترکیبی استفاده کردیم:

SonarQube / Semgrep

• بررسی مشکلات امنیتی

• Quality Gate

• Static Analysis

Team-Aware Review Agent

• First Pass Review

• بررسی Ruleهای اختصاصی تیم

• شناسایی Scope Creep

• تولید Commentهای ساختاریافته و یکدست

Human Reviewer

• بررسی معماری و Design

• درک Context محصول و نیازمندی‌ها

• تصمیم نهایی برای Merge

در این مدل، هر ابزار کاری رو انجام میده که در اون بهترین عملکرد رو داره.

ابزارهای Static Analysis روی Security و Quality تمرکز می‌کنن، Agent روی Ruleهای تیم و بررسی اولیه MR، و Reviewer انسانی روی تصمیم‌های مهندسی و Product Context.

این ترکیب برای ما نتیجه بهتری نسبت به تکیه کامل روی هر کدوم از این بخش‌ها به تنهایی داشت.

مهم‌ترین چیزی که یاد گرفتیم

ارزش اصلی این پروژه Agent نبود.

ارزش واقعی زمانی خودش رو نشون داد که دانش Review تیم از حالت ضمنی خارج شد و به Ruleهای شفاف و قابل نگه‌داری تبدیل شد.

وقتی Ruleها داخل Repository قرار گرفتن:

• همه اعضای تیم به یک منبع مشترک دسترسی پیدا کردن

• Ruleها قابل جستجو و مستندسازی شدن

• تغییر Ruleها مثل هر تغییر دیگه‌ای قابل Review شد

• Ruleها تحت Version Control قرار گرفتن

• Agent و Reviewer انسانی از یک مجموعه استاندارد مشترک استفاده کردن

در عمل، Repository به منبع اصلی دانش Review تیم تبدیل شد.

نتیجه این بود که با تغییر Ruleها، رفتار Agent هم به‌صورت طبیعی تغییر می‌کنه؛ بدون اینکه لازم باشه Promptها بازنویسی بشن یا Workflow جدیدی تعریف بشه.

شاید مهم‌ترین دستاورد این پروژه خودکار کردن Review نبود؛ بلکه تبدیل دانش پراکنده و ذهنی تیم به Ruleهای شفاف، قابل اجرا و قابل تکامل بود.

جمع‌بندی

اگر از GitHub یا GitLab Cloud استفاده می‌کنید و Ruleهای خاصی هم ندارید، احتمالاً ابزارهای آماده انتخاب بهتری برای شما هستن.

اما اگر:

• GitLab داخلی دارید

• Ruleهای اختصاصی تیم دارید

• می‌خواید استانداردها کنار کد نگهداری بشن

• یا می‌خواید Agent دقیقاً مطابق فرهنگ، فرآیندها و استانداردهای تیم شما عمل کنه

ساخت یک Team-Aware Review Agent می‌تونه گزینه قابل دفاعی باشه.

نکته مهم اینه که این پروژه برای جایگزین کردن Reviewerها ساخته نشد.

هدف این بود که بخشی از دانش Review تیم که معمولاً داخل ذهن افراد، Wikiها یا Documentهای پراکنده قرار داره، به Ruleهای شفاف، قابل نگه‌داری و قابل اجرا تبدیل بشه.

در نهایت، مهم‌ترین خروجی این پروژه یک Agent جدید نبود؛ بلکه ایجاد یک منبع مشترک از دانش Review بود که هم انسان و هم Agent می‌تونن ازش استفاده کنن.