اگر از عاملهای برنامهنویسی برای بازبینی کد استفاده میکنید، احتمالاً متوجه شدهاید که آنها یا بخشهای بیربطی از پروژه را میخوانند یا تغییرات حیاتی را نادیده میگیرند. این ناکارآمدی نه تنها هزینه استنتاج را بالا میبرد، بلکه باعث پر شدن سریع پنجرهٔ زمینه میشود. بسیاری از دستیارهای هوش مصنوعی با مشکل «شعاع اثر» (Blast Radius) دستوپنجه نرم میکنند؛ یعنی نمیدانند تغییر یک خط کد در یک فایل، دقیقاً کدام توابع در فایلهای دوردست را خراب میکند. برای جبران این نقص، مدلها یا تکههای عظیمی از کد را میخوانند یا به جستوجویهای متنی (grep) غیردقیق تکیه میکنند. این مقاله، شماره ۱۲۶ از سری «هر روز یک پروژه متن-باز» است.
این عدم بهرهوری باعث ایجاد هزینه و تأخیر (Latency) شدیدی برای توسعهدهندگانی میشود که از ابزارهایی مانند Claude Code یا Cursor استفاده میکنند. این مشکل زمانی شدت مییابد که عاملهای AI از اتوکامپلیتهای ساده به سمت بازسازیهای پیچیده و چندفایلی (Multi-file refactoring) حرکت میکنند. در حالی که سیستمهای RAG ابتدایی از شباهت معنایی برای یافتن کد استفاده میکنند، آنها اغلب وابستگیهای ساختاری سخت — مانند توارث یا لبههای فراخوانی (Call edges) — را که در واقع تعیین میکنند آیا یک تغییر ایمن است یا خیر، نادیده میگیرند. در واقع، این عاملها به دلیل فقدان یک نقشه ساختاری پایدار از پروژه، در حال «سوزاندن توکنها» هستند.
به گزارش توسعهدهنده این پروژه، tirth8205، ابزار code-review-graph (CRG) در تاریخ ۲۶ فوریه ۲۰۲۶ عرضه شد تا این اسکنهای کورکورانه را با یک نقشه ساختاری پایدار جایگزین کند. این ابزار که در حال حاضر نسخه v2.3.6 آن با مجوز MIT منتشر شده و بیش از ۱۹,۷۶۲ ستاره و ۲,۱۰۷ فورک در گیتهاب دارد، کدها را با استفاده از Tree-sitter تحلیل کرده و توابع، کلاسها و وابستگیها را در یک گراف تبدیل نموده و سپس این اطلاعات را در یک پایگاهداده محلی SQLite ذخیره میکند. هدف نهایی CRG، ارائه زمینه (Context) بسیار دقیق به ابزارهای کدنویسی AI از طریق پروتکل زمینهٔ مدل (Model Context Protocol - MCP) است.
زمینه و پیشگراند پروژه
ابزار CRG به عنوان یک ابزار هوشمندی کد «محلی-محور» (Local-first) عمل میکند. این ابزار برای توسعهدهندگانی طراحی شده است که تجربه اولیهای در کار با Claude Code یا سایر ابزارهای AI دارند و با مفاهیمی چون تحلیل استاتیک (Static Analysis) و گرافهای فراخوانی (Call Graphs) آشنا هستند. این ابزار با زبان پایتون ۳.۱۰+ نوشته شده است و بهطور کامل بدون وابستگی به شبکه عمل میکند، به این معنا که تمام دادهها در محیط محلی باقی میمانند و هیچ اطلاعاتی به بیرون ارسال نمیشود.
مکانیزم شعاع اثر (Blast-Radius)
نوآوری اصلی این ابزار در مکانیزم تحلیل «شعاع اثر» است. وقتی فایلی تغییر میکند (به عنوان مثال، یک تابع login() در فایل auth/login.py)، CRG یک کوئری چندمرحلهای را اجرا میکند:
- تأثیر مستقیم: شناسایی توابعی که مستقیماً تابع تغییریافته را فراخوانی میکنند.
- تأثیر ثانویه: شناسایی توابعی که فراخوانکنندگانِ مرحله قبل را صدا میزنند. این فرآیند به صورت زنجیروار بالا میرود و عمق آن قابل تنظیم است، هرچند عمق ۲ به صورت پیشفرض تنظیم شده است.
- پوشش تست: گراف را جستوجو میکند تا بفهمد کدام فایلهای تست خاص، توابع اثرپذیر را پوشش میدهند.
- نتیجه: خروجی نهایی، مجموعهای حداقلی از توابع و فایلهایی است که واقعاً تحت تأثیر تغییر قرار گرفتهاند.
با ارائه این مجموعه حداقلی، مدل AI به جای اسکن کل مخزن کد، تنها کدهای ضروری را میخواند. این امر ریسک توهم (Hallucination) و اتمام سریع سهمیه توکنها را بهشدت کاهش میدهد.
معماری فنی و عملکرد
معماری CRG از یک خط لوله با کارایی بالا برای بهروز نگه داشتن نقشه پیروی میکند: مخزن کد $ \rightarrow $ دستور git ls-files (برای ایندکس کردن فقط فایلهای ردیابی شده) $ \rightarrow $ تحلیلگرهای Tree-sitter $ \rightarrow $ پایگاهداده گراف SQLite $ \rightarrow $ سرور MCP.
- موتور تحلیل (Parsing Engine): از AST مربوط به Tree-sitter برای استخراج توابع، کلاسها، ایمپورتها، فراخوانیها، توارث و پوشش تست استفاده میکند.
- ذخیرهسازی: یک پایگاهداده SQLite محلی در پوشه
.code-review-graph/قرار دارد که بهطور پیشفرض در.gitignoreقرار میگیرد. این موضوع حریم خصوصی کامل و عدم نیاز به شبکه را تضمین میکند. - یکپارچگی با MCP: این ابزار ۳۰ ابزار تخصصی را از طریق پروتکل MCP در دسترس قرار میدهد. این به عاملها اجازه میدهد توابعی مانند
get_impact_radius_toolوget_review_context_toolرا مستقیماً فراخوانی کنند. - بهروزرسانیهای افزایشی (Incremental Updates): با استفاده از بررسی هش SHA-256، ابزار تشخیص میدهد کدام فایلها واقعاً تغییر کردهاند و فقط همان فایلها را مجدداً ایندکس کرده و یالهای وابسته را برای بازسازی علامتگذاری میکند. در یک پروژه با ۲,۹۰۰ فایل، بهروزرسانیها معمولاً در کمتر از ۲ ثانیه کامل میشوند. ساخت اولیه برای یک پروژه ۵۰۰ فایلی حدود ۱۰ ثانیه زمان میبرد.
سیستم امتیازدهی به اطمینان یالها
از آنجایی که تحلیل استاتیک همیشه در محیطهای با تایپ پویا (Dynamically-typed) قطعی نیست، CRG یک سیستم امتیازدهی سه سطحی را برای کمک به عاملهای AI در فیلتر کردن نویز معرفی کرده است:
- EXTRACTED: اطمینان بالا؛ فراخوانیهای صریحی که مستقیماً از AST استخراج شدهاند.
- INFERRED: اطمینان متوسط؛ روابطی که از طریق استنتاج نوع (Type Inference) یا تحلیل معنایی به دست آمدهاند.
- AMBIGUOUS: اطمینان پایین؛ مواردی شامل Dispatch پویا، چندریختی یا بخشهایی که بهصورت استاتیک قابل حل نیستند.
این لایهبندی به هوش مصنوعی اجازه میدهد کوئریها را بر اساس سطح اطمینان فیلتر کند و از هشدارهای کاذب ناشی از یالهای کمکیفیت در کدهای پیچیده دوری کند.
بررسی عمیق: ۳۰ ابزار MCP
۳۰ ابزار موجود بر اساس هدفشان سازماندهی شدهاند تا دستیار AI بتواند بهطور بهینه در گراف پیمایش کند:
- بازیابی زمینه (Context Retrieval): شامل
get_minimal_context_tool(حدود ۱۰۰ توکن، اولین ابزار اجرا شده)،get_impact_radius_toolبرای شعاع اثر،get_review_context_tool(خلاصهای بهینه شده برای توکن) وdetect_changes_tool(تحلیل با امتیاز ریسک). - کوئریهای گراف: شامل
query_graph_tool(برای فراخوانها، فراخوانیشوندهها و توارث)،traverse_graph_tool(پیمایش BFS/DFS با بودجه توکنی مشخص) وsemantic_search_nodes_tool(جستوجوی اختیاری مبتنی بر Embeddingها). - تحلیل معماری: شامل
get_architecture_overview_tool(نمای کلی)،get_hub_nodes_tool(نقاط داغ معماری)،get_bridge_nodes_tool(نقاط گلوگاهی با مرکزیت بینابینی)،get_surprising_connections_tool(جفتشدگیهای غیرمنتظره بین ماژولها) وget_knowledge_gaps_tool(بخشهای تستنشده). - ابزارهای عمومی: شامل
refactor_tool(تشخیص کدهای مرده)،generate_wiki_tool(تولید ویکی مارکداون) وcross_repo_search_tool(جستوجو در چندین مخزن).
در محیطهایی که محدودیت توکن شدید است، کاربران میتوانند سرور را محدود به چند ابزار خاص کنند: code-review-graph serve --tools query_graph_tool,detect_changes_tool,get_review_context_tool.
پشتیبانی از پلتفرمها و زبانها
در نسخه v2.3.6، این ابزار از ۱۴ پلتفرم AI پشتیبانی میکند: Claude Code, Cursor, Windsurf, Zed, Continue, OpenCode, Antigravity, Gemini CLI, Qwen, Qoder, Kiro, GitHub Copilot, Codex, and CodeBuddy Code. کاربران میتوانند با فلگهایی مانند --platform cursor یا --platform claude-code نصبهای اختصاصی را انجام دهند.
این ابزار بیش از ۴۰ زبان و فرمت را پوشش میدهد، از جمله: Python, JavaScript/TypeScript/TSX, Go, Rust, Java, C/C++, C#, Ruby, Kotlin, Swift, PHP, Scala, Solidity, Dart, R, Elixir, Zig, Vue/Svelte SFCs, Jupyter/Databricks notebooks, Terraform, و Ansible. برای زبانهای پشتیبانینشده، کاربران میتوانند یک فایل languages.toml در پوشه .code-review-graph/ ایجاد کنند تا پسوندهای جدید و دستور زبان (مانند Erlang) را تعریف کنند، بدون اینکه نیاز به تغییر کد یا فورک کردن پروژه باشد.
ارزیابی بنچمارکها
میزان صرفهجویی در توکنها بسیار زیاد است، اما نویسنده آنها را با صداقت غیرمعمولی ارائه کرده است. یک «پنل صرفهجویی توکن» که توسط دستور detect-changes --brief ارائه میشود، میتواند تخمینها را با توکنایزر cl100k_base شرکت OpenAI تطبیق دهد و دقت آن در حدود ۱٪ است. در این میان، اهمیت صحت بنچمارکها در دنیای کدنویسی بسیار زیاد است؛ چنانکه گزارشهای اخیر OpenAI نشان میدهد نشت دادهها چگونه میتواند اعتبار بنچمارکهای ارزیابی کدنویسی را تخریب کند.
| مخزن (Repo) | توکنهای بدنه (Corpus) | توکنهای گراف | کاهش |
|---|---|---|---|
| fastapi | 951,071 | 2,169 | 528x |
| code-review-graph | 208,821 | 2,495 | 93x |
| gin | 166,868 | 1,990 | 92x |
| flask | 125,022 | 1,986 | 71x |
| express | 135,955 | 3,465 | 41x |
| httpx | 89,492 | 2,438 | 38x |
| میانه (Median) | - | - | ~82x |
نتیجه ۵۲۸ برابر برای FastAPI بهترین حالت است. نویسنده اعتراف میکند که برای تغییرات کوچک در تکفایل، سربار متادادههای ساختاری ممکن است از خواندن ساده فایل بیشتر شود (مانند نتایج پروژه Express). علاوه بر این، ادعای recall=1.0 به دلیل دایرهای بودن (چون از همان گرافی استخراج شده که پیشبینیکننده در آن حرکت میکند) مورد نقد است؛ لذا حالت «Co-change mode» معیار صادقانهتری را با مقایسه در برابر تاریخچه واقعی git ارائه میدهد.
جریانهای کاری CI و چند-مخزنی
برای تیمها، CRG به عنوان یک GitHub Action ادغام میشود. این اکشن کد را دریافت کرده و ساخت گراف را کاملاً روی Runner ایسی-آی اجرا میکند، به این معنی که هیچ کد منبعی به سرویسهای خارجی ارسال نمیشود. این ابزار یک کامنت «چسبنده» با امتیاز ریسک روی هر PR قرار میدهد که با هر Push بهروزرسانی میشود. کاربران میتوانند ورودی fail-on-risk را فعال کنند تا بازبینی کد به یک دروازه رسمی برای ادغام (Merge Gate) تبدیل شود.
برای توسعه محلی، crg-daemon ادیتورهایی را که از Hook پشتیبانی نمیکنند (مانند Cursor یا OpenCode) مدیریت میکند. این دیمون به کاربران اجازه میدهد چندین مخزن را اضافه کنند (crg-daemon add ~/project-a --alias proj-a)، آنها را در پسزمینه رصد کند، هر ۳۰ ثانیه بررسی سلامت انجام دهد و تنظیمات را در ~/.code-review-graph/watch.toml ذخیره نماید.
مقایسه و جمعبندی
تفاوت CRG با سایر ابزارها در تمرکز بر یکپارچگی ساختاری به جای شباهت معنایی صرف است. در حالی که LSP (پروتکل سرور زبان) در سطح هر نماد (Symbol) دقیقتر است، CRG یک گراف پایدار و بین-زبانی ارائه میدهد. در حالی که RAG از Embeddingها استفاده میکند، CRG از یالهای مشتق شده از AST بهره میبرد (Embeddingها اختیاری هستند). در مقایسه با grep، ابزار CRG در پاسخ به سوالات چند-گامی درباره جریانهای اثرپذیر بسیار برتر است.
این ابزار برای مخازن کوچک، تغییرات ساده در تکفایل یا سوالات یکباره که سربار ساخت گراف از مزایای آن بیشتر است، توصیه نمیشود. با این حال، برای پایگاههای کد متوسط تا بزرگ، نقش AI را از یک «خواننده» به یک «ناوبری» تغییر میدهد. به جای اینکه عامل بپرسد «در این پوشه چه خبر است؟»، میپرسد «شعاع اثر این تغییر چیست؟».
اگر مخزنی با صدها یا هزاران فایل مدیریت میکنید، سربار ۱۰ ثانیهای ساخت اولیه در برابر بهرهوری توکنی حاصله، تبره بسیار کوچکی است. میتوانید با اجرای pip install code-review-graph و سپس دستور code-review-graph install برای شناسایی خودکار ادیتورهای AI و نوشتن تنظیمات MCP شروع کنید.
گام بعدی شما
- اگر پروژهای با بیش از ۱۰۰ فایل دارید،
pip install code-review-graphرا اجرا کنید. - با دستور
code-review-graph installابزار را به ادیتور AI خود متصل کنید. - برای کاهش بیشتر هزینه، تنها ابزارهای مورد نیاز (مثل
query_graph_tool) را در دستورserveفعال کنید.
اما تأثیر این رویکرد بر کاهش هزینه استنتاج در مقیاس سازمانی حتی تکاندهندهتر است؛ در تحلیل بعدی ما درباره بهینهسازی توکنها در مدلهای استدلالی، به این موضوع میپردازیم.
گفتگو