Graft تأخیر عامل‌های کدنویسی را با گراف‌های محلی ۶۰٪ کاهش داد

اگر هر بار برای یک تغییر کوچک در کد، باید منتظر بمانید تا عامل هوش مصنوعی شما دوباره کل پروژه را «بشناسد»، می‌دانید که بخش بزرگی از زمان و هزینه شما صرف کارهای تکراری می‌شود. ابزار Graft که در ۱۴ اوت ۲۰۲۶ منتشر شد، این مشکل را با ایجاد یک درک محلی و پایدار از کدبیس حل می‌کند که در طول جلسات مختلف و بین هم‌تیمی‌ها باقی می‌ماند.

بیشتر ابزارهای کدنویسی AI در وضعیت «فراموشی دائمی» عمل می‌کنند. هر بار که تسک جدیدی شروع می‌کنید، عامل باید دوباره مخزن را جست‌وجو کند، عبارات را با grep پیدا کند، فایل‌ها را باز کند و مسیرهای واردات (imports) را دنبال کند؛ اما به محض پایان جلسه، تمام این نقشه ذهنی را دور می‌ریزد. این وضعیت باعث ایجاد یک «مالیات اکتشاف» سنگین می‌شود که در هر درخواست، تأخیر و هزینه توکن را بالا می‌برد، زیرا عامل در هر بار فراخوانی باید هزینه یادگیری اولیه را بپردازد. این چالش دقیقاً همان نقطه‌ای است که ابزارهایی مانند CodeGraph با هدف کاهش نرخ خوانش فایل‌ها به صفر سعی در بهینه‌سازی آن داشتند.

همان‌طور که در تحلیل قبلی ما درباره‌ی Claude Code و توانایی آن در ادغام اصلاحات نگهداری اشاره کردیم، مشکل اصلی در نحوه «آنبوردینگ» یا آشنایی اولیه عامل با پروژه است. انسان‌ها کدبیس را یک‌بار یاد می‌گیرند، اما عامل‌ها تا پیش از این مجبور بودند هر بار که پرامپتی دریافت می‌کنند، از صفر شروع کنند. این بازیافت اطلاعات، بخش بزرگی از فراخوانی‌های ابزار، توکن‌ها و زمان پاسخ‌دهی را می‌سوزاند و چون بین هم‌تیمی‌ها به اشتراک گذاشته نمی‌شود و پس از هر جلسه پاک می‌شود، یک سربار خالص است.

مکانیزم: تبدیل نمادها به معنا

Graft برخلاف بسیاری از ابزارها، به بردار معنایی (Embedding) — که مثل کارت معرفی عددی برای هر واژه است و می‌گوید این کلمه همسایه چه کلمات دیگری است — یا جست‌وجوهای شباهت تکیه نمی‌کند، زیرا این روش‌ها اغلب به پایگاه‌های داده خارجی یا ایندکس‌های «گرم» نیاز دارند. در عوض، کدبیس را به پوشه‌ای از فایل‌های مارک‌داون متصل به هم تبدیل می‌کند که مستقیماً در دایرکتوری graft/ ذخیره می‌شوند. این گراف صرفاً لیستی از نام توابع نیست، بلکه مجموعه‌ای از توضیحات واقعی به زبان انگلیسی است؛ دقیقاً همان‌طور که یک مهندس ارشد سیستم را برای شما توضیح می‌دهد.

هر «گره» در این گراف، یک فایل مارک‌داون است که یک سیستم، API یا مفهوم را نمایندگی می‌کند. برخلاف ایندکس‌های استاندارد که فقط مسیر فایل و شماره خط را می‌دهند، یک گره در Graft شامل موارد زیر است:

• خلاصه (Summary): توضیحی به زبان ساده از عملکرد کد که توسط مدل نوشته و کش شده است. این بخش هر زمان که منبع کد تغییر کند، دوباره تولید می‌شود.
• نقطه کلیدی (Crux): چند خطی که واقعاً منطق اصلی (مثل گاردها، شرایط پرش یا تغییر وضعیت) را حمل می‌کنند. این خطوط مستقیماً از منبع استخراج و به صورت متن ذخیره می‌شوند (نه به صورت بازه خطوط)، بنابراین حتی اگر فایل جابه‌جا شود، محتوا درست باقی می‌ماند.
• منابع (Sources): فایل‌های دقیقی که گره از آن‌ها ساخته شده و هر کدام با یک هش محتوایی ردیابی می‌شوند تا زمان کهنه شدن گره تشخیص داده شود.
• پیوندها (Links): اتصالات تایپ‌شده (مثل depends_on یا implements یا produces) با استفاده از [[wikilinks]] که عامل‌ها می‌توانند آن‌ها را دنبال کنند.
• یادداشت‌ها (Notes): زمینه‌هایی که کاربر می‌نویسد و در بازسازی‌های بعدی حفظ می‌شوند.

معماری فنی و فرآیند ساخت

این سامانه گراف را در دو مرحله مجزا می‌سازد. مرحله اول از tree-sitter برای تحلیل ساختاری قطعی و رایگان (با هزینه صفر) استفاده می‌کند تا تمام توابع، کلاس‌ها و لبه‌های فراخوانی را بدون نیاز به فراخوانی LLM نقشه‌برداری کند. این مرحله «سطح ۱»، فایل graft/.graph/wiring.json (یک گراف کد به ازای هر نماد) و همچنین یک کارت سیم‌کشی به ازای هر فایل را ایجاد می‌کند که آینه درخت منبع است.

مرحله دوم از یک مدل زبانی بزرگ (LLM) — از طریق OpenAI، Anthropic، OpenRouter، Fireworks، Groq، یک پروکسی LiteLLM یا مدل‌های محلی — استفاده می‌کند تا این نمادها را به گره‌های مفهومی سطح بالا تبدیل کند. این مرحله که با دستور --deep اجرا می‌شود، خلاصه‌های تک‌خطی و نقاط کلیدی را برای هر نماد اضافه می‌کند.

برای حفظ کارایی، Graft از هش محتوایی استفاده می‌کند. اجرای مجدد ساخت فقط فایل‌های تغییر یافته را لمس می‌کند و به‌روزرسانی‌ها را تقریباً آنی می‌کند. برای مثال، در یک مخزن با ۱۲۴ فایل، ساخت اولیه ۰.۷۴ ثانیه و به‌روزرسانی پس از ویرایش یک فایل تنها ۰.۱۸ ثانیه زمان می‌برد. یک فراخوانی بازیابی، درخت را در حدود ۳ میلی‌ثانیه با اثر انگشت آخرین ساخت مقایسه می‌کند و تنها در صورت جابه‌جایی چیزی، آن را بازسازی می‌کند. این اجازه می‌دهد گراف کد را دقیقاً در وضعیت فعلی، شامل ویرایش‌های ثبت‌نشده (uncommitted)، استیج‌نشده یا استیج‌شده توصیف کند.

جزئیات منطق ساخت

• کشینگ: هر مرحله بر اساس هش محتوایی کش می‌شود. برای اجبار به بازبینی کامل، می‌توان از graft build --no-reuse استفاده کرد.
• مکانیزم تازه‌سازی: تازه‌سازی‌های ساختاری رایگان هستند و هرگز LLM را فراخوانی نمی‌کنند. این قابلیت را می‌توان برای هر دستور با --no-refresh یا به صورت سراسری با GRAFT_NO_REFRESH=1 غیرفعال کرد.
• هسته قطعی: گراف ساختاری کد (در دستورات graft build و graft check) بر پایه tree-sitter است و هرگز از مدل استفاده نمی‌کند.
• بی‌طرفی در تامین‌کننده: کاربران می‌توانند GRAFT_PROVIDER (مثلاً openai یا anthropic)، GRAFT_API_KEY، GRAFT_MODEL و GRAFT_BASE_URL را برای نقاط اتصال سفارشی مانند OpenRouter یا سرورهای محلی تنظیم کنند.

تحلیل بهره‌وری و بنچمارک‌ها

بر اساس مستندات گیت‌هاب، Graft در برابر یک عامل «سرد» Claude Sonnet 5 در ۱۶۲ اجرا روی دو مخزن (خودِ Graft و یک سرویس احراز هویت Node/Express) تست شد. نتایج نشان‌دهنده کاهش شدید سربار بدون افت دقت است:

• کاهش هزینه: ۳۲٪ کاهش (از ۰.۰۴۲۹ به ۰.۰۲۹۲ دلار).
• کاهش توکن: ۴۲٪ توکن کمتر (از ۸,۰۷۰ به ۴,۶۵۰).
• کاهش فراخوانی ابزار: ۴۶٪ کاهش (از ۴.۲ به ۲.۳).
• تأخیر: ۶۰٪ پاسخ سریع‌تر (از ۳۹.۸ ثانیه به ۱۵.۸ ثانیه).
• صحت: در تسک‌های پایه روی ۹۳٪ ثابت ماند.

در محک SWE-bench Verified (شامل ۵۰ مورد از مسائل واقعی گیت‌هاب)، تاثیر بر صحت نتایج مشهود بود. عامل‌های مجهز به Graft توانستند ۳۳ مورد از ۵۰ مشکل را حل کنند (۶۶٪)، در حالی که مدل پایه تنها ۲۷ مورد (۵۴٪) را حل کرد؛ یک جهش ۱۲ درصدی. این بهبود ناشی از توانایی عامل در یافتن فایل‌های «همسایه» است که عامل‌های کور معمولاً آن‌ها را نادیده می‌گیرند.

برای مثال، در مورد django-11532 مدل پایه تنها ۱ فایل از ۵ فایل مورد نیاز را اصلاح کرد و ۱۸ تست را شکست داد؛ اما Graft بقیه فایل‌ها را یافت. در مورد django-16263 مدل Graft اصلاح را با نصف توکن‌ها و نصف زمان انجام داد. در مجموع، نتایج SWE-bench نشان‌دهنده ۲۳٪ کاهش توکن، ۱۹٪ کاهش هزینه و ۳۲٪ کاهش زمان واقعی (۸,۹۲۲ ثانیه در مقابل ۱۳,۰۹۴ ثانیه) بود.

یکپارچگی و ابزارها

Graft از طریق CLI و سرور پروتکل زمینهٔ مدل (MCP) مستقیماً با گردش کار توسعه‌دهنده ادغام می‌شود و از طیف گسترده‌ای از عامل‌ها شامل Cursor، Gemini، Copilot، Windsurf، Kiro و AdaL پشتیبانی می‌کند.

با اجرای دستور npx @nanonets/graft init ابزار این عامل‌ها را تشخیص داده و فایل‌های دستورالعمل بومی را می‌سازد. برای مثال، فایل‌های .cursor/rules/graft.mdc، .windsurf/rules/graft.md، .kiro/steering/graft.md و .adal/skills/graft/SKILL.md ایجاد می‌شوند. برای عامل‌هایی که از AGENTS.md استفاده می‌کنند، یک بخش محصور شده برای Graft اضافه می‌کند. همچنین تنظیمات سطح کاربر برای Codex را مدیریت کرده و ~/.codex/config.toml و ~/.codex/hooks.json را برای ثبت سرور MCP و هوک‌های پس از ویرایش به‌روز می‌کند.

جزئیات سیم‌کشی عامل‌ها

• اجراهای اسکریپتی: از --agents <ids> برای سیم‌کشی عامل‌های خاص یا --yes برای رد کردن پرامپت‌ها استفاده کنید. دستور --dry-run تمام فایل‌هایی را که ابزار قصد تغییر آن‌ها را دارد، قبل از نوشتن نمایش می‌دهد.
• تنظیمات سراسری: فایل ~/.codex/config.toml سرور MCP را ثبت می‌کند و ~/.codex/hooks/graft/graft-hooks.cjs شیم (shim) هوک پس از ویرایش را فراهم می‌کند. این موارد را می‌توان با --no-global نادیده گرفت.
• ویژگی‌های Claude Code: دستور graft init یک فایل مهارت در .claude/skills/graft/SKILL.md می‌نویسد و هرگز به فایل CLAUDE.md کاربر دست نمی‌زند.

برای کاربران Claude Code، این ادغام بسیار عمیق است. این ابزار در واقع مکمل قابلیت‌هایی است که Claude Code برای ویرایش مستقیم فایل‌ها در ترمینال معرفی کرده بود. یک خط وضعیت زنده به ترمینال اضافه می‌شود که وقتی گراف «کهنه» (stale) است، به کاربر هشدار می‌دهد (مثلاً "⚠ N stale"). همچنین هشدارهای «شعاع انفجار» (blast-radius) را پیاده می‌کند: وقتی فایلی را ویرایش می‌کنید، Graft فوراً تمام بخش‌های دیگر سیستم را که به آن تغییر وابسته هستند شناسایی می‌کند. هر پرس‌وجو در Claude Code ابتدا گراف را به‌روز می‌کند تا پاسخ‌ها وضعیت فعلی کد را توصیف کنند.

ابزارهای سرور MCP

سرور MCP شش ابزار بومی در اختیار عامل قرار می‌دهد تا نیاز به دستورات شل نباشد:

• graft_find_code: بازگرداندن گره‌های رتبه‌بندی شده با کد داخلی برای پاسخ‌های مستقیم.
• graft_file_api: ارائه تمام امضاهای یک فایل بدون بدنه، که هزینه توکن را حدود ۹۰٪ کاهش می‌دهد.
• graft_trace_calls: نقشه‌برداری وابستگی‌ها و شعاع انفجار تا N سطح عمق.
• graft_find_all: جست‌وجوی جامع با Regex که بر اساس نمادهای دربرگیرنده گروه‌بندی شده است.
• graft_repo_map: ارائه نگاه اول به خوشه‌های دایرکتوری و نقاط داغ (hotspots).
• graft_check_freshness: گزارش می‌دهد که آیا گراف محلی از کد فاصله گرفته است یا خیر.

مرجع دستورات CLI

• ساخت (Build): graft build (ساختاری)، graft build --deep (لایه LLM)، graft build --extensions .ts .py (فیلتر پسوندها).
• پرس‌وجو (Query): graft ask "<task>" (گره‌های رتبه‌بندی شده)، graft skeleton <file> (سطح API)، graft callers <symbol> (ردیابی وابستگی).
• جست‌وجو (Search): graft grep "<regex>" (جست‌وجوی جامع گروه‌بندی شده بر اساس نماد)، graft map (جهت‌گیری با بودجه توکن محدود).
• نگهداری (Maintenance): graft check (گزارش انحراف)، graft version (بررسی به‌روزرسانی)، graft upgrade (به‌روزرسانی CLI).

بصری‌سازی کدبیس

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

لبه‌ها از مجموعه‌ای بسته از افعال برای پاسخ به سوالات مهندسی استفاده می‌کنند:

• part_of / contains: این مورد کجا قرار دارد؟
• uses / calls / imports / depends_on: اگر این را تغییر دهم چه چیزی می‌شکند؟
• produces: این خروجی از کجا می‌آید؟
• configures: چه چیزی رفتار را بدون تغییر کد تغییر می‌دهد؟
• validates: چه چیزی این را بررسی یا قضاوت می‌کند (تست‌ها، بررسی‌های انحراف)؟
• extends / implements: این مورد باید از چه قراردادی پیروی کند؟

پشتیبانی از زبان‌ها

Graft سطوح مختلفی از دقت را در ۲۰ زبان ارائه می‌دهد:

• دقت کامل (Full-fidelity): استخراج‌کننده‌های دست‌نویس با تحلیل محدوده (scope-aware) و حل فراخوانی‌ها و واردات بین‌فایلی برای TypeScript/JavaScript (JSX/TSX)، Python، Go و Java.
• پشتیبانی گسترده (Broad): نمادها و لبه‌های فراخوانی حل‌شده از طریق استخراج‌کننده‌های عمومی tree-sitter برای Rust، C، C++، C#، Ruby، PHP، Kotlin، Scala، Swift، Elixir، Solidity، OCaml، Zig و Dart.
• در سطح کامپایلر (Compiler-grade): لبه‌های دقیق lsp_resolved اختیاری از طریق graft build --lsp زمانی که سرورهایی مثل rust-analyzer، clangd، gopls، pyright یا typescript-language-server در PATH سیستم باشند.

تست دنیای واقعی: PocketBase

برای تست کاربرد واقعی، Graft روی PocketBase (زبان Go، حدود ۳۵۰ فایل) با ۱۵ تسک اجرا شد. این شامل ۱۰ سوال پیچیده — مانند ردیابی ایجاد رکورد REST API از ابتدا تا انتها و شناسایی محل اعتبارسنجی ورودی کاربر — و ۵ بازسازی PR بود.

با استفاده از Claude Opus، ابزار Graft هزینه‌ها را ۲۱٪ (از ۱۳.۹۱ به ۱۱.۰۲ دلار) و زمان واقعی را ۱۴٪ (از ۲۰۴۴ به ۱۷۶۲ ثانیه) کاهش داد، در حالی که تمام ۵ PR ادغام شده را بازسازی کرد و دقیقاً همان فایل‌هایی را لمس کرد که توسعه‌دهندگان اصلی لمس کرده بودند. این PRها از تولید تامنیل‌های WebP (#6744) تا اصلاح بازگشت‌های automigration (#3192) را شامل می‌شد. بیشترین سود در سنتز بین‌فایلی بود؛ مثلاً در تسکی که می‌پرسید «احراز هویت در ارائه‌دهندگان OAuth2 چگونه کار می‌کند»، هزینه‌ها از ۲.۱۹ دلار به ۰.۸۴ دلار کاهش یافت.

تحلیل: تغییر پارادایم عامل‌ها

تغییر از «اکتشاف در لحظه» به «حافظه ساختاری پایدار»، اقتصاد کدنویسی AI را تغییر می‌دهد. با انتقال مرحله درک کد از زمان پرامپت (گران) به زمان ساخت (ارزان و کش‌شده)، Graft عملاً کدبیس را به یک نقشه خوانا برای AI تبدیل می‌کند.

این ابزار به‌طور خودکار مونو-ریپوها (monorepos) و پوشه‌های چند-ریپویی را مدیریت می‌کند. در مونو-ریپوها، زیرپروژه‌ها را به عنوان محدوده‌های رتبه‌بندی شناسایی می‌کند تا پروژه‌های بزرگ باعث غرق شدن پروژه‌های کوچک نشوند. در پوشه‌هایی شامل ریپوهای گیت مجزا، یک ایندکس graft/workspace.json ایجاد می‌کند تا پرس‌وجوها را بین فرزندان فدرالیزه کند.

برای توسعه‌دهنده، این یعنی AI دیگر در مخزن «پرسه نمی‌زند». اثر ثانویه آن، کاهش توهمات در مسیر فایل‌ها و افزایش قابل توجه توانایی عامل در مدیریت بازسازی‌های چندفایلی (multi-file refactors) است که نقطه شکست اصلی کدنویسان LLM فعلی است. این رقابت برای بهینه‌سازی تجربه توسعه‌دهنده در محیط ترمینال، تقابل ابزارهایی مانند Claude Code و Aider را به مرحله‌ای جدید از کارایی رسانده است.

اگر صنعت به سمت این رویکرد «گراف به عنوان فایل» حرکت کند، خودِ مخزن به منبع حقیقت برای انسان و AI تبدیل می‌شود و نیاز به سرویس‌های ایندکس بسته و کدر که اغلب از آخرین commit گیت عقب هستند، از بین می‌رود. گراف در گیت زندگی می‌کند؛ یک گراف کهنه به صورت یک diff در Pull Request ظاهر می‌شود و تضمین می‌کند که مستندات همگام با کد تکامل می‌یابند.

برای شروع بهینه‌سازی عملکرد عامل خود، می‌توانید دستور npx @nanonets/graft init را در پروژه فعلی خود اجرا کنید تا آن را به عامل کدنویسی مورد نظرتان متصل کنید.

گام بعدی شما

• برای بهینه‌سازی عملکرد عامل کدنویسی خود، دستور npx @nanonets/graft init را در پروژه فعلی اجرا کنید.
• اگر از Claude Code استفاده می‌کنید، وضعیت stale گراف را در ترمینال چک کنید تا مطمئن شوید مدل از آخرین تغییرات شما باخبر است.
• از دستور graft viz برای تحلیل بصری وابستگی‌های پیچیده در پروژه‌های بزرگ استفاده کنید.

اما داستان سخت‌افزاری این تحول حتی شگفت‌انگیزتر است — به تحلیل ما درباره‌ی تراشه‌های Blackwell مراجعه کنید.