نقشه codebase برای ایجنتهای برنامهنویسی با ابزار Graft
ابزار Graft با استفاده از tree-sitter یک نقشه پایدار از مخزن شما میسازد. با ارائه این دادهها از طریق MCP، ایجنت شما دیگر نیازی به اسکن مجدد فایلها ندارد.
نقشهٔ codebase برای ایجنتهای برنامهنویسی چیست
نقشهٔ codebase برای ایجنتهای برنامهنویسی، یک ایندکس پایدار از مخزن (repository) شماست که ایجنت برای جستجوی موارد از آن استفاده میکند؛ بهجای اینکه در هر نشست جدید، از ابتدا با دستور grep به جستجو بپردازد. Graft یکی از پیادهسازیهای این ایده است. این ابزار کد شما را با tree-sitter تجزیه میکند، پوشهای از گرههای markdown مرتبط به همراه یک گراف اتصال برای هر نماد (symbol) میسازد و ابزارهای بازیابی را از طریق MCP (پروتکل زمینه مدل، رابط استانداردی که ایجنتهای برنامهنویسی برای فراخوانی ابزارهای خارجی استفاده میکنند) ارائه میدهد.
Graft یک پروکسی یا دروازه (gateway) نیست. هیچچیز بین ایجنت شما و API مدل قرار نمیگیرد. این نقشه، پوشهای روی دیسک است که ایجنت آن را میخواند. این تمایز تعیین میکند که شما در حال حل چه مشکلی هستید: یک دروازه توکن self-hosted درخواستهایی را که از قبل ارسال میکنید اندازهگیری و مسیریابی میکند، در حالی که یک نقشه، تعداد درخواستهایی را که اصلاً نیاز دارید ارسال کنید، تغییر میدهد.
این تکنیک قدیمیتر از این ابزار است و پس از آن نیز باقی خواهد ماند. ابتدا تکنیک را یاد بگیرید، سپس مکانیسمهای آن را.
چرا ایجنتهای کدنویسی برای کشف مجدد ساختار، context را هدر میدهند
مشاهده کنید که یک ایجنت چگونه کار روی مخزنی را شروع میکند که قبلاً پنجاه بار آن را دیده است. ایجنت دایرکتوریها را لیست میکند. برای پیدا کردن یک نماد (symbol) دستور grep را اجرا میکند. سه فایل را باز میکند تا بفهمد کدامیک تابع مورد نظر را تعریف کرده است، سپس فایل چهارمی را باز میکند تا ببیند چه کسی آن را فراخوانی میکند. هیچکدام از اینها بخشی از وظیفه اصلی نیست. اینها مراحل جهتیابی (orientation) هستند و هزینه آن در هر نشست (session) با مصرف توکنهای ورودی پرداخت میشود.
دلیل این امر ساده است. مدل هیچ حافظهای بین نشستها ندارد. هر آنچه ایجنت درباره ساختار پروژه شما آموخته، در یک پنجره context قرار داشته که با پایان نشست دور ریخته شده است. بنابراین، همان فرآیند کشف دوباره از صفر اجرا میشود و شما دوباره هزینه آن را میپردازید. قابلیت Prompt caching فقط پیشوندهای کاملاً یکسان را که در پنج دقیقه اخیر یا با هزینه بیشتر در یک ساعت اخیر دیده شدهاند تخفیف میدهد، بنابراین نمیتواند اکتشافات دیروز را به نشست امروز منتقل کند. در یک مخزن بزرگ، هزینه مرحله جهتیابی از هزینه ویرایش بیشتر است: ده فراخوانی ابزار برای پیدا کردن کد، و تنها یکی برای تغییر آن. جهتیابی نیمی از این صورتحساب است و ویرایش نیمه دیگر؛ به همین دلیل است که مهارتی که ایجنت را به کوچکترین تغییرِ کارآمد محدود میکند ارزش آن را دارد که با یک نقشه همراه شود، نه اینکه بین این دو یکی انتخاب شود.
یک نقشه با انتقال فرآیند کشف از مدل به دیسک، این چرخه را میشکند. یک parser مخزن را یکبار پیمایش میکند، ثبت میکند که کدام نماد کجا تعریف شده و کدام نماد چه چیزی را فراخوانی میکند، سپس با تغییر کد، آن رکورد را بهروز نگه میدارد. ایجنت یک سوال میپرسد و پاسخی همراه با فایل و شماره خط دریافت میکند. اکتشافات تکراری به یک جستجوی ارزان تبدیل میشوند.
شما در حال حاضر از نسخه ضعیفتری از این روش استفاده میکنید. یک فایل AGENTS.md که قراردادهای شما را بیان میکند مانع از آن میشود که ایجنت هر بار قراردادهای شما را دوباره استنتاج کند. یک نقشه تولیدشده مانع از آن میشود که ایجنت ساختار شما را دوباره استنتاج کند. تفاوت در این است که چه کسی آن را مینویسد. شما فایل دستورالعمل را دستی مینویسید، بنابراین کوچک میماند. یک parser نقشه را تولید میکند، بنابراین میتواند ده هزار فایل را پوشش دهد. برای اینکه بودجه واقعاً در طول یک نشست کجا صرف میشود، نحوه مدیریت پنجره context توسط Claude Code جزئیات این حسابوکتاب را پوشش میدهد.
آنچه Graft در واقع میسازد
دو خروجی که هر دو در یک پوشه graft/ در ریشه مخزن قرار دارند.
خروجی اول یک گراف گره (node graph) است که به صورت مارکداون پیوندخورده نوشته شده و برای هر گره یک فایل مجزا دارد. هر گره شامل یک خلاصه به زبان ساده، «نکته کلیدی» (crux) از خطوط منطقی مهم استخراجشده از سورسکد، فایلهای منبع دقیق با یک هش محتوا، ویکیلینکهای تایپشده به گرههای دیگر (depends_on، part_of، uses، implements) و یک بخش یادداشت است که پس از بازتولید (regeneration) باقی میماند تا بتوانید زمینههایی را که یک پارسر قادر به استنباط آنها نیست، ثبت کنید.
خروجی دوم graft/.graph/wiring.json است؛ گراف ساختاریِ هر نماد (symbol) که tree-sitter آن را استخراج میکند: تعاریف، ارجاعات و لبههای فراخوانی (call edges) بین آنها.
این تفکیک اهمیت دارد زیرا تنها نیمی از آن به مدل نیاز دارد. graft build کاملاً مبتنی بر tree-sitter است و هرگز یک LLM (مدل زبانی بزرگ) را فراخوانی نمیکند، بنابراین قطعی (deterministic) است و هزینهای ندارد. graft build --deep خلاصههای نوشتاری و نکات کلیدی هر نماد را اضافه میکند و اینها فراخوانیهای مدلی هستند که باید برای آنها هزینه پرداخت کنید.
پشتیبانی از زبانها به صورت لایهبندیشده است و این لایه به شما میگوید که تا چه حد میتوان به گراف فراخوانی اعتماد کرد. زبانهای TypeScript، JavaScript، Python، Go، Java، Kotlin، PHP، Swift و R از قابلیت حل ارجاعات بینفایلی با آگاهی از scope برخوردارند. زبانهای Rust، C، C++، C#، Ruby، Scala، Elixir، Solidity، OCaml، Zig، Dart، Clojure، Nix و Lua نمادها به همراه لبههای فراخوانی عمومی را دریافت میکنند؛ به این معنی که یک لبه ممکن است صرفاً یک تطابق نام باشد تا یک ارجاع حلشده. لبههای با دقت کامپایلر (Compiler-grade) با استفاده از --lsp و یک سرور زبان (language server) مانند rust-analyzer یا gopls قابل فعالسازی هستند.
نصب Graft و ثابتسازی نسخه
نرمافزار Graft به Node.js نسخه 20 یا جدیدتر نیاز دارد و تحت مجوز MIT منتشر شده است. تا تاریخ 17 اکتبر 2026، آخرین نسخه منتشرشده 0.23.0 است که در 15 اکتبر 2026 عرضه شد؛ اولین نسخه آن یعنی 0.1.0 نیز در ژوئیه 2026 منتشر شده است. با این نرمافزار بهعنوان یک پروژه نوپا برخورد کنید. نسخه 0.22.0 که در 14 اکتبر 2026 منتشر شد، نام پروژه را به Trail-code تغییر داد: همان کد اکنون با نام @trailhq/trail-code و دستور trail عرضه میشود، در حالی که @nanonets/graft همچنان از دستور graft استفاده میکند.
این راهنما نسخه 0.21.1 را ثابت (pin) میکند که در 29 سپتامبر 2026 منتشر شد و آخرین نسخه پیش از تغییر نام است، زیرا نسخههای 0.22 و 0.23 دستوراتی را که این راهنما بر آنها متکی است، تغییر دادهاند. از نسخه 0.22 به بعد، graft check تفاوت (diff) شاخه شما را با آموختههای تیم در مخزن مقایسه میکند و در صورت بروز تداخل، با کد خروج 1 متوقف میشود؛ قابلیت تشخیص drift به graft build --check منتقل شده و ابزارهای MCP با نام trail_* شناخته میشوند (سرور همچنان به نامهای قدیمی graft_* پاسخ میدهد). همچنین در یادداشتهای انتشار 0.23.0 ذکر شده که در مخزنی که با trail راهاندازی شده، نقشه به .trail/cache/ منتقل میشود و Claude Code دیگر سرور MCP دریافت نمیکند، در حالی که فایل README همچنان graft/ و .mcp.json را توصیف میکند. پیش از تغییر نسخه ثابت، یادداشتهای انتشار را مطالعه کرده و --dry-run را اجرا کنید.
npm install -g @nanonets/graft@0.21.1
npm ls -g @nanonets/graftدستور npm ls -g باید @nanonets/graft@0.21.1 را چاپ کند. آن نسخه را بهصورت آگاهانه ثابت کنید. یک دستور npm install -g @nanonets/graft ساده، تگ latest را در لحظه اجرا حل میکند و در پروژهای که چندین نسخه فرعی در ماه منتشر میکند، این کار باعث میشود ابزاری که شما روز سهشنبه دارید با ابزاری که همکارتان روز دوشنبه نصب کرده، متفاوت باشد. نسخه ثابت باعث میشود فلگهای CLI و فرمت گراف برای همه یکسان باقی بماند تا زمانی که خودتان تصمیم به ارتقا بگیرید.
سپس آن را به مخزنی که در اختیار دارید متصل کنید:
cd /path/to/your/repo
graft init --dry-run
graft initدستور graft init از شما میپرسد کدامیک از عاملهای برنامهنویسی (coding agents) خود را میخواهید متصل کنید و سپس گراف را میسازد. ابتدا --dry-run را اجرا کنید و لیست فایلهایی که قرار است تغییر کنند را بخوانید، زیرا برخی از آنها خارج از مخزن قرار دارند. دستور graft init یک عملیات idempotent است و تنظیمات موجود را بازنویسی نمیکند، بنابراین اجرای مجدد آن ایمن است. برای بازگشت به حالت قبل، graft uninstall تمام فایلها و ورودیهای پیکربندی که Graft نوشته است را حذف میکند؛ این دستور تا زمانی که -y را وارد نکنید، در حالت dry run عمل میکند.
همان پرامپت شامل یک چکباکس برای تلهمتری است. از نسخه 0.12.0 به بعد، Graft بهصورت پیشفرض یک پینگ استفاده ناشناس ارسال میکند: شامل شمارشهای دستهبندیشده و برچسبهای ثابت، و هرگز کد، مسیر فایلها یا نام مخزن شما را ارسال نمیکند. رویدادها حداکثر یکبار در روز ارسال میشوند، با یک استثنا: رویداد نصب، که هوک postinstall در npm بلافاصله آن را به فرستنده پسزمینه تحویل میدهد. برای غیرفعال کردن آن، در حین graft init تیک چکباکس را بردارید، graft telemetry disable را اجرا کنید، یا DO_NOT_TRACK=1 را تنظیم کنید (این قابلیت در محیط CI بهطور خودکار غیرفعال میشود)؛ همچنین graft telemetry debug دستهای که قرار است ارسال شود را بدون ارسال واقعی، چاپ میکند.
در نسخه 0.21.1، این اتصال شامل Claude Code، Cursor، Codex، GitHub Copilot، Google Gemini، Kiro، Windsurf، Grok (xAI)، AdaL، Hermes Agent و Google Antigravity میشود. Hermes Agent از نسخه 0.13.0 یک میزبان درجهیک graft init بوده است و در نسخه ثابتشده، graft init --agents hermes و graft init --agents antigravity این دو را مانند هر میزبان دیگری انتخاب میکنند. Grok در نسخه 0.13.0 اضافه شد و با graft init --agents grok انتخاب میشود. Claude Code عمیقترین یکپارچهسازی را دریافت میکند: یک ورودی سرور MCP، یک خط وضعیت که اندازه و میزان قدیمی بودن گراف را نشان میدهد، هوکهای پس از ویرایش که گراف را بازسازی میکنند، و یک فایل مهارت در مسیر .claude/. بقیه موارد یک فایل دستورالعمل یا قانون دریافت میکنند که به عامل اطلاع میدهد ابزارها وجود دارند (Hermes Agent و Antigravity هر دو بخش AGENTS.md را میخوانند) و Grok نیز یک بلوک MCP در پیکربندی خود دریافت میکند. بنابراین "پشتیبانیشده" به این معنی است که Graft اتصال را مینویسد، پس عاملی که فایل قوانین خود را نادیده بگیرد، نقشه را نیز نادیده خواهد گرفت. این دلیل معمول برای نادیده گرفتن دستورالعملها توسط عاملها است و در اینجا نیز مانند هر جای دیگری صدق میکند.
چه چیزی در مخزن شما قرار میگیرد و چه چیزی نباید در git باشد
پس از graft init، موارد زیر را انتظار داشته باشید:
graft/: گراف گرههای markdown وgraft/.graph/wiring.json. برای شما به.gitignoreاضافه شده است..mcp.json: سرور MCP گراف را ثبت میکند تا Claude Code آن را اجرا کند..claude/settings.json: در محل ادغام شده و statusline و hookهای پس از ویرایش را اضافه میکند.AGENTS.md،GEMINI.md،.github/copilot-instructions.md،.cursor/rules/graft.mdc،.kiro/steering/graft.md،.windsurf/rules/graft.md،.grok/skills/graft/SKILL.mdو.adal/skills/graft/SKILL.md: بخشهای محصور در نشانگر که به هر فایلی که با عاملهای انتخابی شما مطابقت داشته باشد، پیوست میشوند..grok/config.toml: یک بلوک[mcp_servers.graft]در سطح مخزن، که فقط در صورت انتخاب Grok نوشته میشود.~/.codex/config.toml،~/.codex/hooks.jsonو~/.codex/hooks/graft/graft-hooks.cjs: در سطح ماشین، که فقط در صورت انتخاب Codex و وجود~/.codex/نوشته میشوند.graft init --no-globalاز آنها صرفنظر میکند وgraft init --no-hooksبه تنهایی از hook shim صرفنظر میکند.
این گراف یک کش (cache) است، مشابه node_modules. آن را commit نکنید. این گراف در عرض چند ثانیه از روی کد بازسازی میشود، تقریباً با هر ویرایش تغییر میکند و commit کردن آن باعث میشود یک اصلاح یکخطی به یک diff چندصد فایلی تبدیل شود که هیچ بازبینیکنندهای آن را نمیخواند. به جای آن، سیمکشی (wiring) را commit کنید، که شامل AGENTS.md و .mcp.json میشود. همتیمی شما مخزن را clone میکند، graft build را اجرا میکند و گراف محلی خودش را به دست میآورد.
بررسی کنید که قانون ignore پیش از اولین commit شما اعمال شده باشد:
grep -n graft .gitignore
git status --shortgrep باید خطی شامل graft/ را چاپ کند و git status --short نباید چیزی را در زیر graft/ فهرست کند. ظاهر شدن فایلهای زیر graft/ در آن خروجی به این معنی است که ورودی ignore وجود ندارد یا در جای دیگری نادیده گرفته شده است. پیش از commit آن را اصلاح کنید، زیرا git فایلی را که یک بار اضافه شده باشد همچنان ردیابی میکند و ویرایش بعدی .gitignore آن را از ردیابی خارج نخواهد کرد.
اگر ترجیح میدهید سرور MCP را به صورت دستی ثبت کنید، یا آن را روی همان نسخهای که نصب کردهاید قفل (pin) کنید، ورودی آن کوچک است:
{
"mcpServers": {
"graft": {
"command": "npx",
"args": ["-y", "@nanonets/graft@0.21.1", "mcp"]
}
}
}ابزارهای بازیابی که ایجنت شما بهجای grep فراخوانی میکند
Graft شش ابزار را از طریق MCP ارائه میدهد. graft_find_code گرههای رتبهبندیشده را برای شرح یک وظیفه، همراه با فایل و شماره خط بازمیگرداند. graft_file_api تمام امضاها (signatures) را در یک فایل بدون بدنه توابع بازمیگرداند. graft_trace_calls فراخوانندهها (callers) یا فراخواندهشدگان (callees) را تا چندین سطح عمق پیمایش میکند. graft_find_all نتایج منطبق بر regex را بهصورت گروهبندیشده بر اساس نماد (symbol) بازمیگرداند. graft_repo_map دید اولیهای از یک مخزن ناآشنا ارائه میدهد. graft_check_freshness گزارش میدهد که آیا گراف همچنان با کد مطابقت دارد یا خیر.
هر کدام از اینها یک همتای CLI دارند که روشی برای بررسی دادههایی است که واقعاً به ایجنت شما تحویل داده میشود:
graft map .
graft ask "where do we validate the refresh token"
graft skeleton src/auth/session.ts
graft callers validateRefreshToken
graft callers validateRefreshToken --direction out
graft grep "refresh_token" --jsongraft ask باید گرههای رتبهبندیشده را با ارجاعات file:line بهجای محتوای فایل چاپ کند. کل مکانیزم همین است: ایجنت یک اشارهگر دریافت میکند و بهجای خواندن ده فایل برای یافتن فایل درست، فقط یک فایل را باز میکند. graft viz اگر میخواهید خودتان گراف را مشاهده کنید، یک نمایشگر تعاملی را روی localhost باز میکند. اگر graft ask برای سوالی که خودتان میتوانید در 30 ثانیه پاسخ دهید نتیجه مفیدی بازنمیگرداند، آن را بازنویسی نکنید و دوباره نپرسید. بازیابی رتبهبندیشده ممکن است خطا داشته باشد و فایل مهارتهای خود پروژه میگوید که نتایج ضعیف به معنای تغییر به graft grep، graft skeleton یا graft callers است. اگر آنها نیز نتیجهبخش نبودند، انحراف (drift) را بررسی کنید (graft check . در نسخه پینشده 0.21.1، و graft build --check از نسخه 0.22 به بعد) و تأیید کنید که زبان شما در کدام سطح (tier) قرار دارد، زیرا یک گراف قدیمی یا یالهای سطحگسترده، ایجنت شما را به همان اندازه دچار شکست میکنند.
یک هزینه وجود دارد که نادیده گرفتن آن آسان است. شش تعریف ابزار در prompt سیستمِ هر درخواست برای کل نشست تزریق میشود. شما این هزینه را چه ایجنت از نقشه استفاده کند و چه نکند، میپردازید. در مخزنی که بهاندازه کافی کوچک است که در context جا شود، این هزینه ثابت میتواند بزرگتر از کاوشی باشد که صرفهجویی میکند.
هنگام تغییر کد چه اتفاقی برای گراف میافتد
بازسازی ساختاری ارزان و خودکار است. Graft بهجای git، درخت کاری (working tree) شما را میخواند؛ بنابراین تغییری که commit نکردهاید و تغییری که staged کردهاید، هر دو به یک اندازه برای آن قابل مشاهده هستند. هر پرسوجو ابتدا وضعیت درخت کاری را بررسی (stat) میکند و فقط فایلهایی را که تغییر کردهاند، دوباره تجزیه (re-parse) میکند. مستندات نسخه 0.21.1 این بررسی را در صورت عدم تغییر، حدود 3 میلیثانیه تخمین میزند؛ README فعلی به چند ده میلیثانیه اشاره دارد که در مخزن خود پروژه حدود 50 میلیثانیه است. بازسازی در پایان نوبت (turn-end rebuild) فقط فایلهایی را تحت تأثیر قرار میدهد که کد در آنها جابهجا شده است. برای پاسخدهی از روی گراف موجود در دیسک بدون تجزیه مجدد، GRAFT_NO_REFRESH=1 را تنظیم کنید یا --no-refresh را ارسال کنید. برای اجبار به تجزیه مجدد کامل (cold re-parse) که پس از ارتقای خودِ Graft به آن نیاز دارید، --no-reuse را ارسال کنید.
بخشی که توسط مدل نوشته شده است رفتار متفاوتی دارد و همان بخشی است که ممکن است بیسروصدا دچار خطا شود. خلاصهها و نکات کلیدی (cruxes) کش میشوند. هر گره یک هش محتوایی از منابع خود را ثبت میکند، بنابراین وقتی یک فایل منبع تغییر میکند، گره بهجای نمایش به عنوان وضعیت فعلی، به عنوان قدیمی (stale) علامتگذاری میشود. این پرچم فقط در صورتی کمک میکند که چیزی بر اساس آن عمل کند. با استفاده از graft build --deep که دوباره توکنهای مدل را مصرف میکند، آن را بازخوانی (refresh) کنید.
قدیمی بودن (staleness) را قابل مشاهده کنید:
graft check .
echo $?در نسخه ثابت 0.21.1، وضعیت خروج 0 به این معنی است که گراف با کد مطابقت دارد و وضعیت خروج 1 به معنی انحراف (drift) است. از نسخه 0.22 به بعد، graft check در صورت تداخل با یادگیری تیمی، وضعیت 1 را برمیگرداند و دروازه انحراف graft build --check است؛ بنابراین هنگام تغییر نسخه ثابت (pin)، دستور را نیز تغییر دهید. آن را از یک pre-push hook اجرا کنید تا یک نقشه ششماهه نتواند با اطمینان درباره کدی که در ماه مارس بازنویسی شده است، پاسخ دهد. README نسخه 0.21.1 از graft check به عنوان یک سیگنال تازگی محلی یاد میکند و README فعلی build --check را برای CI فهرست کرده است. در هر صورت، graft/ توسط git نادیده گرفته میشود، بنابراین یک checkout تازه در CI بدون گراف شروع میشود مگر اینکه job مربوطه یکی بسازد.
اعداد بنچمارک منتشرشده را با دقت بخوانید
فایل README نسخه 0.21.1 با این جمله شروع میشد: «تا 4 برابر ارزانتر و 3 برابر سریعتر، با دقت بهتر یا بدون افت دقت». README فعلی آن جمله را حذف کرده و با اعداد کوچکتری شروع میشود: «در 162 اجرای یک عامل (agent) روی وظایف مشابه: 32 درصد هزینه کمتر، 42 درصد توکنهای ورودی غیرکششده کمتر، 60 درصد زمان کمتر و سهم یکسانی از پاسخهای صحیح». این اعداد از بنچمارکهای خود پروژه که در README آن منتشر شده، استخراج شدهاند. در اینجا دو اجرای گزارششده به طور کامل آمده است.
دادههای پشت این نمودار
[
{
"label": "Controlled sweep",
"run_count": 162,
"token_saving_pct": 42,
"tool_call_saving_pct": 46,
"correctness_pct": 93,
"baseline_correctness_pct": 93
},
{
"label": "SWE-bench Verified",
"run_count": 50,
"token_saving_pct": 23,
"tool_call_saving_pct": 25,
"correctness_pct": 66,
"baseline_correctness_pct": 54
}
]بررسی کنترلشده شامل 162 اجرا روی دو مخزن (repository) است که یکی از آنها خود Graft است و برای هر وظیفه سه آزمایش انجام شده است. این گزارش حاکی از 42% توکن ورودی غیرکششده کمتر و 46% فراخوانی ابزار (tool call) کمتر است. اجرای SWE-bench Verified شامل 50 نمونه با مدل یکسان در هر دو حالت است و صرفهجویی کمتری را گزارش میکند: 23% از توکنها و 25% از فراخوانیهای ابزار. اجرای سوم شامل 15 وظیفه PocketBase، ده پرسش توسعهدهنده به علاوه پنج pull request ادغامشدهٔ بازتولیدشده، در مجموع 11.02 دلار آمریکا هزینه داشت، در حالی که هزینه حالت پایه 13.91 دلار بود.
با تمام این موارد به عنوان بنچمارک فروشنده برخورد کنید. دو عامل محدودیتهایی را برای آنچه این اعداد میتوانند به شما بگویند ایجاد میکنند. بررسی کنترلشده شامل مخزن خود Graft است، یعنی همان کدی که نویسندگان ابزار، آن را بر اساس آن بهینهسازی کردهاند. SWE-bench Verified یک مجموعه داده عمومی از مسائل پروژههای متنباز معروف پایتون است و مجموعهدادههای عمومی همان مواردی هستند که ابزارها برای آنها بهینهسازی میشوند، چه کسی قصد آن را داشته باشد و چه نداشته باشد. هیچکدام از اینها بیانیهای درباره monorepo خصوصی شما نیست که عادتهای نامگذاری و کدهای مرده (dead code) خاص خود را دارد.
دقت (Correctness) شایسته بررسی مجدد است. در بررسی کنترلشده، این مقدار تغییری نکرد: 93% با استفاده از نقشه (map) در مقابل 93% بدون آن. جهش به 66% از 54% فقط در SWE-bench Verified دیده میشود. ابزاری که هزینه توکن شما را کاهش دهد و کیفیت را ثابت نگه دارد، همچنان معامله خوبی است. فقط نتیجه دقت SWE-bench را با نتیجه توکنِ بررسی کنترلشده ترکیب نکنید و هر دو را به عنوان یک ادعای واحد نقل نکنید.
تفاضل توکن خود را پیش از باور به هر عددی، اندازهگیری کنید
تنها عددی که اهمیت دارد، عددی است که از مخزن (repository) خودتان به دست میآید. این روش یک بعدازظهر زمان میبرد.
وظیفهای را انتخاب کنید که بتوانید دقیقاً تکرار کنید. یک پرسش بهتر از یک ویرایش است، زیرا ویرایش، مخزن را تغییر میدهد و اجرای دوم دیگر همان آزمایش قبلی نخواهد بود. «کدام ماژول محدودیت نرخ (rate limit) را در مسیر ورود اعمال میکند؟» شکل درستی از پرسش است.
تلهمتری را فعال کنید و آن را به ترمینال خود بفرستید:
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=console
claudeصادرکننده کنسول (console exporter)، رکوردهای متریک را همزمان با جمعآوری چاپ میکند. موردی که به آن نیاز دارید claude_code.token.usage است که دارای ویژگی type با مقدار input، output، cacheRead یا cacheCreation میباشد. جهتگیری (orientation) در input و cacheRead ظاهر میشود، زیرا محتوای فایلها در آنجا قرار میگیرند. این دو مقدار را با هم جمع کنید.
وظیفه را سه بار، هر بار در یک نشست (session) تازه و با نقشه متصل (wired map)، اجرا کنید. سپس ورودی graft را از .mcp.json حذف کرده و سه بار دیگر اجرا کنید. به جای تکیه بر یک اجرای واحد، میانهها (medians) را مقایسه کنید، زیرا اجرای عاملها (agent runs) نوسان زیادی دارد و یک اجرای ناموفق ممکن است نتیجهای کاملاً خلاف واقعیت به شما بدهد. تعداد فراخوانی ابزار (tool-call count) را نیز ثبت کنید: فراخوانی ابزارها مکانیزم هستند و توکنها اثر آن؛ بنابراین کاهش توکن بدون کاهش در فراخوانی ابزارها به این معناست که عامل دیگری تغییر کرده است.
سپس هزینههایی که بنچمارک نشان نمیدهد را کسر کنید. graft build --deep در هر بار بازخوانی کامل (full refresh)، توکنهای مدل را مصرف میکند. شش طرحواره ابزار (tool schemas) در هر درخواست همراه هستند. اگر عاملهای شما روی سروری که اجاره کردهاید اجرا میشوند، تعیین سقف سخت برای هزینه عامل این موضوع را از یک غافلگیری به یک بودجهبندی تبدیل میکند و آنچه تلهمتری یک عامل کدنویسی واقعاً گزارش میدهد توضیح میدهد که پس از فعالسازی صادرکننده، چه دادههایی از دستگاه خارج میشود.
نقشهٔ codebase چه زمانی دیگر کارایی ندارد؟
- مخزن (repository) از قبل در context جای میگیرد. یک سرویس کوچک نیازی به نقشه ندارد و شما همچنان برای شش طرحوارهٔ ابزار در هر درخواست هزینه پرداخت میکنید. اگر عامل (agent) شما همین امروز هر فایلی را با یک یا دو فراخوانی ابزار پیدا میکند، از آن صرفنظر کنید.
- زبان شما در ردهٔ عمومی (broad tier) قرار دارد. لبههای فراخوانی عمومی (Generic call edges) به این معنی است که
graft callersممکن است یک فراخواننده را نادیده بگیرد یا به دلیل تداخل نام، فراخوانندهای اشتباه ایجاد کند. پیش از اعتماد به شعاع انفجار (blast radius)، باgraft grepتأیید کنید. - گراف قدیمی شده و کسی متوجه نشده است. در نسخه 0.21.1،
graft checkهنگام بروز انحراف (drift) با کد 1 خارج میشود (از نسخه 0.22 به بعد،graft build --checkاین کار را انجام میدهد)، که تنها در صورتی مفید است که چیزی آن را اجرا کند. این یک pre-push hook است، نه یک عادت. - مخزن یکپارچه (monorepo) نیاز به محدودسازی (scoping) دارد. یک monorepo با یک git واحد تفکیک نشده است، اما
graft buildزیرپروژهها را ازpnpm-workspace.yaml، فضاهای کاریpackage.jsonیا فایلهایgo.mod،pyproject.tomlیاCargo.tomlدر هر بسته تشخیص میدهد و از آنها به عنوان محدودههای رتبهبندی استفاده میکند، وgraft ask "..." --in services/billing/پرسوجو را به یک زیرپروژه محدود میکند. همان غریزهای که منجر به فایلهای AGENTS.md تو در تو برای هر بسته میشود، در مورد نقشه نیز صدق میکند. - عامل (agent) سیمکشیها را نادیده میگیرد. پیش از آنکه نتیجه بگیرید از نقشه استفاده میشود، فراخوانیهای ابزار را در یک نشست واقعی مشاهده کنید. عاملی که همچنان
grepرا اجرا میکند، به شما میگوید که هرگز فایل قوانین را نخوانده است.
FAQ
آیا باید پوشه graft/ را به git کامیت کنم؟
خیر. graft build بهطور خودکار graft/ را به .gitignore شما اضافه میکند، زیرا گراف یک کش قابل بازسازی مانند node_modules است. این پوشه تقریباً با هر ویرایش تغییر میکند، بنابراین کامیت کردن آن باعث میشود تغییرات واقعی (diffs) زیر صدها فایل تولیدشده دفن شوند. تنظیماتی را کامیت کنید که به ایجنتها وجود نقشه را اطلاع میدهد، از جمله AGENTS.md و .mcp.json، و اجازه دهید هر یک از اعضای تیم graft build را بهصورت محلی اجرا کنند. پیش از اولین کامیت، با استفاده از grep -n graft .gitignore و git status --short بررسیهای لازم را انجام دهید، زیرا git پس از اضافه شدن یک فایل، ردیابی آن را حفظ میکند و ویرایش .gitignore پس از آن، فایل را از حالت ردیابی خارج نمیکند.
آیا اجرای Graft هزینه دارد؟
بخش ساختاری آن هزینهای ندارد. graft build، graft ask، graft check و شش ابزار بازیابی MCP، عملیاتهای tree-sitter هستند که هرگز با مدل تماس نمیگیرند. graft build --deep بخش پولی است: این بخش خلاصههایی به زبان ساده و نکات کلیدی برای هر نماد را از طریق یک LLM مینویسد که با GRAFT_PROVIDER، GRAFT_API_KEY و GRAFT_MODEL، بهعلاوه GRAFT_BASE_URL برای هر endpoint سازگار با OpenAI پیکربندی شده است. شما میتوانید Graft را فقط با بخش ساختاری اجرا کنید و هرگز حتی یک توکن برای خودِ گراف هزینه نکنید.
نقشه کدبیس (codebase map) واقعاً چقدر در مخزن من صرفهجویی میکند؟
بدون اندازهگیری، هیچکس نمیتواند به شما بگوید. این پروژه در بررسی 162 مرحلهای خود، 42 درصد توکنهای ورودی غیرکششده کمتر و در SWE-bench Verified، 23 درصد توکن کمتر نسبت به حالت پایه بدون نقشه گزارش میدهد. هر دو مورد، بنچمارکهای فروشنده هستند؛ یکی از آنها تا حدی روی مخزن خودِ Graft اجرا شده و هیچکدام کد خصوصی شما را توصیف نمیکنند. یک پرسش تکرارپذیر را سه بار با نقشه و سه بار بدون آن، با تنظیم CLAUDE_CODE_ENABLE_TELEMETRY=1 و OTEL_METRICS_EXPORTER=console اجرا کنید، سپس میانه claude_code.token.usage را برای انواع input و cacheRead مقایسه کنید.
وقتی کد را بازنویسی (refactor) میکنم، چه اتفاقی برای گراف میافتد؟
ساختار، خود را دوباره تجزیه (re-parse) میکند. Graft درخت کاری را بررسی کرده و فقط فایلهایی که تغییر کردهاند را دوباره تجزیه میکند، بنابراین تغییر نام در کوئری بعدی شناسایی میشود. وقتی چیزی جابهجا نشده باشد، این بررسی در نسخه 0.21.1 حدود 3 میلیثانیه و در نسخه فعلی چند ده میلیثانیه زمان میبرد و چون فایلها را بهجای تاریخچه git میخواند، کارهای کامیتنشده را نیز میبیند. خلاصههای نوشتهشده توسط مدل هستند که قدیمی میشوند: هر گره یک هش محتوا از منابع خود ذخیره میکند و منبع تغییریافته، گره را بهجای بازنویسی، به عنوان قدیمی (stale) علامتگذاری میکند. برای بررسی عدم انطباق (graft check . در نسخه 0.21.1، graft build --check از نسخه 0.22 به بعد)، اقدام کنید و سپس برای تازهسازی بخش متنی، graft build --deep را اجرا کنید.
کدام ایجنتهای کدنویسی امروزه میتوانند از Graft استفاده کنند؟
در نسخه ثابت 0.21.1، graft init از Claude Code، Cursor، Codex، GitHub Copilot، Google Gemini، Kiro، Windsurf، Grok (xAI)، AdaL، Hermes Agent و Google Antigravity پشتیبانی میکند که در مجموع یازده میزبان هستند. در changelog از نسخه 0.13.0، Hermes Agent به عنوان یک میزبان درجه یک ذکر شده است و hermes و antigravity شناسههای معمولی --agents در نسخه ثابت هستند. Claude Code بیشترین بهره را میبرد: یک ورودی سرور MCP در .mcp.json، یک خط وضعیت، هوکهای پس از ویرایش و یک فایل مهارت تحت .claude/. Codex یک بخش AGENTS.md بهعلاوه ورودیهای سیستمی تحت ~/.codex/ دریافت میکند که graft init --no-global از آن صرفنظر میکند. Grok یک فایل مهارت بهعلاوه یک بلوک MCP در .grok/config.toml دریافت میکند. Hermes Agent و Antigravity بخش AGENTS.md را میخوانند و بقیه یک فایل قوانین یا هدایت دریافت میکنند. هر کلاینت MCP دیگری میتواند با ثبت دستور npx -y @nanonets/graft@0.21.1 mcp مستقیماً از سرور استفاده کند.