نقشه codebase برای ایجنت‌های برنامه‌نویسی با ابزار Graft

نقشهٔ codebase برای ایجنت‌های برنامه‌نویسی چیست

نقشهٔ codebase برای ایجنت‌های برنامه‌نویسی، یک ایندکس پایدار از مخزن (repository) شماست که ایجنت برای جستجوی موارد از آن استفاده می‌کند؛ به‌جای اینکه در هر نشست جدید، از ابتدا با دستور grep به جستجو بپردازد. Graft یکی از پیاده‌سازی‌های این ایده است. این ابزار کد شما را با tree-sitter تجزیه می‌کند، پوشه‌ای از گره‌های markdown مرتبط به همراه یک گراف اتصال برای هر نماد (symbol) می‌سازد و ابزارهای بازیابی را از طریق MCP (پروتکل زمینه مدل، رابط استانداردی که ایجنت‌های برنامه‌نویسی برای فراخوانی ابزارهای خارجی استفاده می‌کنند) ارائه می‌دهد.

Graft یک پروکسی یا دروازه (gateway) نیست. هیچ‌چیز بین ایجنت شما و API مدل قرار نمی‌گیرد. این نقشه، پوشه‌ای روی دیسک است که ایجنت آن را می‌خواند. این تمایز تعیین می‌کند که شما در حال حل چه مشکلی هستید: یک دروازه توکن self-hosted درخواست‌هایی را که از قبل ارسال می‌کنید اندازه‌گیری و مسیریابی می‌کند، در حالی که یک نقشه، تعداد درخواست‌هایی را که اصلاً نیاز دارید ارسال کنید، تغییر می‌دهد.

این تکنیک قدیمی‌تر از این ابزار است و پس از آن نیز باقی خواهد ماند. ابتدا تکنیک را یاد بگیرید، سپس مکانیسم‌های آن را.

چرا ایجنت‌های کدنویسی با کشف مجدد ساختار، توکن‌های context را هدر می‌دهند

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

دلیل این موضوع ساده است. مدل هیچ حافظه‌ای بین نشست‌ها ندارد. هر آنچه ایجنت درباره ساختار پروژه شما آموخته، در پنجره context قرار داشته که با پایان نشست دور ریخته شده است. بنابراین، همان فرآیند کشف دوباره از صفر و با هزینه کامل تکرار می‌شود. در یک مخزن بزرگ، هزینه مرحله جهت‌یابی از هزینه ویرایش بیشتر است: ده فراخوانی ابزار برای یافتن کد، و تنها یکی برای تغییر آن. جهت‌یابی تنها نیمی از این صورت‌حساب است و ویرایش نیمه دیگر؛ به همین دلیل است که مهارتی که ایجنت را به کوچک‌ترین تغییرِ کارآمد محدود می‌کند، ارزش آن را دارد که با یک نقشه (map) ترکیب شود، نه اینکه مجبور باشید بین این دو یکی را انتخاب کنید.

یک نقشه با انتقال فرآیند کشف از مدل به دیسک، این چرخه را می‌شکند. یک پارسر (parser) مخزن را یک‌بار پیمایش می‌کند، ثبت می‌کند که هر نماد کجا تعریف شده و کدام نماد چه چیزی را فراخوانی می‌کند، و سپس با تغییر کد، آن رکورد را به‌روز نگه می‌دارد. ایجنت یک سؤال می‌پرسد و پاسخی به همراه نام فایل و شماره خط دریافت می‌کند. در نتیجه، کاوش‌های تکراری به یک جستجوی ارزان تبدیل می‌شوند.

شما در حال حاضر از نسخه ضعیف‌تری از این روش استفاده می‌کنید. یک فایل AGENTS.md که قراردادهای شما را بیان می‌کند، مانع از آن می‌شود که ایجنت هر بار قراردادهای شما را از نو استنتاج کند. یک نقشه تولیدشده نیز مانع از آن می‌شود که ایجنت ساختار شما را دوباره استنتاج کند. تفاوت در این است که چه کسی آن را می‌نویسد. شما فایل دستورالعمل را دستی می‌نویسید، بنابراین کوچک باقی می‌ماند. یک پارسر نقشه را تولید می‌کند، بنابراین می‌تواند ده هزار فایل را پوشش دهد. برای اینکه بدانید بودجه در طول یک نشست واقعاً کجا صرف می‌شود، نحوه مدیریت پنجره context توسط Claude Code جزئیات حسابداری آن را بررسی می‌کند.

Graft دقیقاً چه چیزی می‌سازد

دو آرتیفکت که هر دو در یک پوشه graft/ در ریشه مخزن قرار دارند.

اولین مورد، یک گراف گره (node graph) است که به صورت مارک‌داون لینک‌شده نوشته شده و برای هر گره یک فایل مجزا دارد. هر گره شامل یک خلاصه به زبان ساده، «هسته» (crux) خطوط منطقی مهم استخراج‌شده از سورس‌کد، فایل‌های سورس دقیق با هش محتوا، لینک‌های تایپ‌شده به سایر گره‌ها (depends_on، part_of، uses، implements) و یک بخش یادداشت است که پس از بازسازی فایل باقی می‌ماند تا بتوانید زمینه‌هایی که پارسر قادر به استنتاج آن‌ها نیست را ثبت کنید.

دومین مورد graft/.graph/wiring.json است؛ گراف ساختاریِ هر نماد (symbol) که tree-sitter آن را استخراج می‌کند: تعاریف، ارجاعات و یال‌های فراخوانی بین آن‌ها.

این تفکیک اهمیت دارد زیرا تنها نیمی از آن به مدل نیاز دارد. graft build کاملاً مبتنی بر tree-sitter است و هرگز LLM (مدل زبانی بزرگ) را فراخوانی نمی‌کند، بنابراین قطعی (deterministic) است و هزینه‌ای ندارد. graft build --deep خلاصه‌های متنی و هسته‌های مربوط به هر نماد را اضافه می‌کند و این‌ها فراخوانی‌های مدلی هستند که باید برای آن‌ها هزینه پرداخت کنید.

پشتیبانی از زبان‌ها به صورت لایه‌بندی‌شده است و این لایه به شما می‌گوید که تا چه حد می‌توان به گراف فراخوانی اعتماد کرد. زبان‌های TypeScript، JavaScript، Python، Go و Java از قابلیت حل ارجاعات بین‌فایلی با آگاهی از اسکوپ (scope-aware) برخوردارند. زبان‌های Rust، C، C++، C#، Ruby، PHP، Kotlin، Scala، Swift، Elixir، Solidity، OCaml، Zig و Dart نمادها به همراه یال‌های فراخوانی عمومی را دریافت می‌کنند؛ به این معنی که یک یال ممکن است صرفاً یک تطابق نام باشد تا یک ارجاع حل‌شده. یال‌های با دقت کامپایلر (Compiler-grade) با استفاده از --lsp و یک سرور زبان مانند rust-analyzer یا gopls قابل فعال‌سازی هستند.

نصب Graft و تعیین نسخه ثابت

نرم‌افزار Graft به Node.js نسخه 20 یا جدیدتر نیاز دارد و تحت مجوز MIT منتشر شده است. تا اوت 2026، نسخه فعلی 0.10.1 است و اولین نسخه منتشر شده یعنی 0.1.0، مربوط به ژوئیه 2026 می‌باشد. با این نرم‌افزار به عنوان یک پروژه نوپا برخورد کنید.

npm install -g @nanonets/graft@0.10.1
npm ls -g @nanonets/graft

دستور npm ls -g باید خروجی @nanonets/graft@0.10.1 را نمایش دهد. این نسخه را به صورت عمدی ثابت (Pin) کنید. اجرای دستور خام npm install -g @nanonets/graft باعث می‌شود که تگ latest در همان لحظه اجرا Resolve شود؛ در پروژه‌ای که ماهانه چندین نسخه minor منتشر می‌کند، این کار باعث می‌شود ابزاری که شما روز سه‌شنبه استفاده می‌کنید با ابزاری که همکارتان روز دوشنبه نصب کرده متفاوت باشد. تعیین نسخه ثابت باعث می‌شود فلگ‌های CLI و فرمت گراف برای همه یکسان باقی بماند و شما تنها زمانی که خودتان تصمیم بگیرید، آن را ارتقا دهید.

سپس آن را به مخزنی که در اختیار دارید متصل کنید:

cd /path/to/your/repo
graft init --dry-run
graft init

دستور graft init از شما می‌پرسد که کدام‌یک از agentهای برنامه‌نویسی خود را می‌خواهید متصل کنید و سپس گراف را می‌سازد. ابتدا دستور --dry-run را اجرا کنید و لیست فایل‌هایی که قرار است تغییر کنند را بخوانید، زیرا برخی از آن‌ها خارج از مخزن قرار دارند. دستور graft init یک عملیات idempotent است و تنظیمات موجود را بازنویسی نمی‌کند، بنابراین اجرای مجدد آن ایمن است.

تا اوت 2026، این اتصال شامل Claude Code، Cursor، Codex، GitHub Copilot، Google Gemini، Kiro، Windsurf و AdaL می‌شود. Claude Code عمیق‌ترین سطح یکپارچه‌سازی را دریافت می‌کند: یک ورودی سرور MCP، یک خط وضعیت (statusline) که اندازه و میزان قدیمی بودن گراف را نشان می‌دهد، هوک‌های پس از ویرایش که گراف را بازسازی می‌کنند، و یک فایل مهارت (skill file) در مسیر .claude/. سایر موارد یک فایل دستورالعمل یا قانون دریافت می‌کنند که به agent اطلاع می‌دهد این ابزارها وجود دارند. بنابراین "پشتیبانی‌شده" به این معناست که Graft اتصالات را می‌نویسد؛ پس اگر یک agent فایل قوانین خود را نادیده بگیرد، نقشه را نیز نادیده خواهد گرفت. این دلیل معمول برای نادیده گرفتن دستورالعمل‌هایی است که برای agentها می‌نویسید، و این موضوع در اینجا نیز مانند هر جای دیگری صدق می‌کند.

چه چیزی در مخزن شما قرار می‌گیرد و چه چیزی خارج از git باقی می‌ماند

پس از graft init، موارد زیر را انتظار داشته باشید:

• graft/: گراف گره‌های markdown و graft/.graph/wiring.json. به‌طور خودکار به .gitignore اضافه می‌شود.
• .mcp.json: سرور MCP پیوندی (graft) را ثبت می‌کند تا 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 و .adal/skills/graft/SKILL.md: بخش‌های محصور در نشانگر که به هر فایلی که با agentهای انتخابی شما مطابقت داشته باشد، ضمیمه می‌شوند.
• ~/.codex/config.toml، ~/.codex/hooks.json و ~/.codex/hooks/graft/graft-hooks.cjs: در سطح کل سیستم، فقط زمانی نوشته می‌شوند که 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 --short

grep باید خطی شامل graft/ را چاپ کند و git status --short نباید چیزی را در زیر graft/ فهرست کند. ظاهر شدن فایل‌های زیر graft/ در آن خروجی به این معنی است که ورودی ignore وجود ندارد یا در جای دیگری نادیده گرفته شده است. پیش از commit آن را اصلاح کنید، زیرا git فایلی را که یک‌بار اضافه شده باشد همچنان ردیابی می‌کند و ویرایش بعدی .gitignore آن را از ردیابی خارج نخواهد کرد.

اگر ترجیح می‌دهید سرور MCP را به‌صورت دستی ثبت کنید یا آن را روی همان نسخه‌ای که نصب کرده‌اید قفل (pin) کنید، ورودی آن کوچک است:

{
  "mcpServers": {
    "graft": {
      "command": "npx",
      "args": ["-y", "@nanonets/graft@0.10.1", "mcp"]
    }
  }
}

ابزارهای بازیابی که ایجنت شما به‌جای grep فراخوانی می‌کند

Graft شش ابزار را از طریق MCP ارائه می‌دهد. graft_find_code گره‌های رتبه‌بندی‌شده را برای شرح یک وظیفه، به همراه فایل و شماره خط بازمی‌گرداند. graft_file_api تمام امضاها (signatures) را در یک فایل بدون بدنه توابع برمی‌گرداند. graft_trace_calls فراخواننده‌ها (callers) یا فراخوانده‌شدگان (callees) را تا چندین سطح عمق پیمایش می‌کند. graft_find_all نتایج منطبق با regex را به‌صورت گروه‌بندی‌شده بر اساس نمادها (symbols) بازمی‌گرداند. 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" --json

graft ask باید گره‌های رتبه‌بندی‌شده را با ارجاعات file:line به‌جای محتوای فایل چاپ کند. کل مکانیزم همین است: ایجنت به‌جای خواندن ده فایل برای یافتن فایل درست، یک اشاره‌گر دریافت کرده و تنها یک فایل را باز می‌کند. graft viz اگر می‌خواهید خودتان گراف را مشاهده کنید، یک نمایشگر تعاملی روی localhost باز می‌کند. اگر graft ask برای پرسشی که خودتان می‌توانید در 30 ثانیه پاسخ دهید نتیجه مفیدی برنمی‌گرداند، یعنی گراف قدیمی است یا زبان برنامه‌نویسی شما در سطح گسترده (broad tier) قرار دارد و این نقشه به ایجنت شما نیز کمکی نخواهد کرد.

یک هزینه وجود دارد که به‌راحتی نادیده گرفته می‌شود. شش تعریف ابزار در prompt سیستم برای هر درخواست در طول کل نشست تزریق می‌شود. شما این هزینه را چه ایجنت از نقشه استفاده کند و چه نکند، می‌پردازید. در مخزنی که به‌اندازه کافی کوچک است و در context جا می‌شود، این هزینه ثابت می‌تواند بزرگ‌تر از صرفه‌جویی حاصل از اکتشاف باشد.

وقتی کد تغییر می‌کند چه اتفاقی برای گراف می‌افتد

بازسازی ساختاری ارزان و خودکار است. ابزار Graft به‌جای git، درخت کاری (working tree) شما را می‌خواند؛ بنابراین ویرایشی که هنوز commit نکرده‌اید و ویرایشی که staged کرده‌اید، هر دو به یک اندازه برای آن قابل مشاهده هستند. یک پرس‌وجو (query) فقط فایل‌هایی را دوباره تجزیه (re-parse) می‌کند که وضعیت stat آن‌ها تغییر کرده است؛ طبق مستندات پروژه، این کار حدود 3 میلی‌ثانیه سربار دارد و بازسازی در پایان هر نوبت (turn-end) فقط فایل‌هایی را تحت تأثیر قرار می‌دهد که کد در آن‌ها جابه‌جا شده است. برای پاسخ‌دهی از روی گراف موجود در دیسک بدون تجزیه مجدد، GRAFT_NO_REFRESH=1 را تنظیم کنید یا پرچم --no-refresh را ارسال نمایید. برای اجبار به تجزیه مجدد کامل (cold re-parse) که پس از ارتقای خودِ Graft توصیه می‌شود، از --no-reuse استفاده کنید.

بخشی که توسط مدل نوشته شده است رفتار متفاوتی دارد و همان قسمتی است که ممکن است بی‌سروصدا دچار خطا شود. خلاصه‌ها و نکات کلیدی (cruxes) کش می‌شوند. هر گره (node) یک هش از محتوای منابع خود را ثبت می‌کند؛ بنابراین وقتی یک فایل منبع تغییر می‌کند، آن گره به‌جای اینکه به‌روز تلقی شود، به عنوان stale (قدیمی/نامعتبر) علامت‌گذاری می‌شود. این پرچم تنها در صورتی مفید است که چیزی بر اساس آن عمل کند. با استفاده از graft build --deep عمل تازه‌سازی (refresh) را انجام دهید که مجدداً توکن‌های مدل را مصرف می‌کند.

نامعتبر بودن (staleness) را قابل مشاهده کنید:

graft check .
echo $?

وضعیت خروجی 0 به این معنی است که گراف با کد مطابقت دارد. وضعیت خروجی 1 به معنای وجود انحراف (drift) است. این دستور را در یک pre-push hook یا روی شاخه (branch) در CI اجرا کنید تا یک نقشه شش‌ماهه نتواند با اطمینان درباره کدی که در ماه March بازنویسی شده است، پاسخ دهد.

اعداد بنچمارک منتشرشده را با دقت بخوانید

ادعای اصلی Graft این است که «تا 4 برابر ارزان‌تر و 3 برابر سریع‌تر، با دقت بهتر یا بدون کاهش دقت» عمل می‌کند. این اعداد از بنچمارک‌های خود پروژه که در 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 اجرا روی دو مخزن است که یکی از آن‌ها خود Graft است و برای هر تسک سه بار آزمایش انجام شده است. این گزارش نشان‌دهنده 42% توکن کمتر و 46% فراخوانی ابزار (tool call) کمتر است. اجرای SWE-bench Verified شامل 50 نمونه با مدل یکسان در هر دو حالت است و صرفه‌جویی کمتری را گزارش می‌کند: 23% توکن و 25% فراخوانی ابزار. اجرای سوم، پنج pull request ادغام‌شده در PocketBase را با هزینه 11.02 دلار در مقابل 13.91 دلار برای حالت پایه بازتولید کرد.

به تمام این موارد به‌عنوان بنچمارک ارائه‌شده توسط فروشنده نگاه کنید. دو عامل محدودکننده در مورد اطلاعاتی که این بنچمارک‌ها به شما می‌دهند وجود دارد. بررسی کنترل‌شده شامل مخزن خود Graft است، یعنی همان کدبیسی که نویسندگان، ابزار خود را بر اساس آن بهینه‌سازی کرده‌اند. SWE-bench Verified یک مجموعه داده عمومی از مشکلات پروژه‌های متن‌باز معروف پایتون است و مجموعه‌داده‌های عمومی همان مواردی هستند که ابزارها برای آن‌ها بهینه‌سازی می‌شوند، چه کسی قصد این کار را داشته باشد و چه نداشته باشد. هیچ‌کدام از این‌ها بیانیه‌ای درباره monorepo خصوصی شما نیستند که عادت‌های نام‌گذاری و کدهای مرده (dead code) خاص خود را دارد.

دقت (correctness) شایسته بررسی دوباره است. در بررسی کنترل‌شده، تغییری ایجاد نشد: 93% با استفاده از ابزار در مقابل 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 جا می‌شود. یک سرویس کوچک نیازی به نقشه ندارد و شما همچنان برای شش طرحواره (schema) ابزار در هر درخواست هزینه می‌پردازید. اگر عامل (agent) شما در حال حاضر هر فایلی را با یک یا دو فراخوانی ابزار پیدا می‌کند، از آن صرف‌نظر کنید.
• زبان شما در ردهٔ عمومی (broad tier) قرار دارد. لبه‌های فراخوانی عمومی (Generic call edges) باعث می‌شود graft callers ممکن است یک فراخواننده (caller) را از دست بدهد یا به دلیل تداخل نام، فراخوانندهٔ اشتباهی ایجاد کند. پیش از اعتماد به شعاع انفجار (blast radius)، با graft grep تأیید کنید.
• گراف قدیمی شده و کسی متوجه نشده است. دستور graft check در صورت وجود انحراف (drift) با کد خروجی 1 متوقف می‌شود، که تنها در صورتی مفید است که چیزی آن را اجرا کند. این کار باید یک hook یا مرحله‌ای در CI باشد، نه یک عادت دستی.
• مونو‌ریپو (monorepo) نیاز به محدودسازی دامنه دارد. یک مونو‌ریپوی تک‌گیت به‌طور خودکار توسط فایل workspace، 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) زیر صدها فایل تولیدشده دفن شوند. فقط تنظیماتی را کامیت کنید که به agentها اطلاع می‌دهد نقشه وجود دارد، از جمله AGENTS.md و .mcp.json، و اجازه دهید هر یک از اعضای تیم graft build را به‌صورت محلی اجرا کنند. پیش از اولین کامیت، با grep -n graft .gitignore و git status --short صحت کار را بررسی کنید، زیرا git فایلی را که یک‌بار اضافه شده باشد همچنان ردیابی می‌کند و ویرایش .gitignore پس از آن، باعث حذف ردیابی (untrack) نمی‌شود.

آیا اجرای 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 چقدر در مخزن من صرفه‌جویی ایجاد می‌کند؟

بدون اندازه‌گیری دقیق، هیچ‌کس نمی‌تواند پاسخ دهد. این پروژه در بررسی خود 42٪ کاهش مصرف توکن را در 162 اجرا، و 23٪ را در SWE-bench Verified گزارش می‌دهد؛ هر دو در مقایسه با حالتی است که نقشه وجود ندارد. هر دو بنچمارک‌های فروشنده هستند، یکی از آن‌ها تا حدی روی مخزن خودِ Graft اجرا شده و هیچ‌کدام کد خصوصی شما را توصیف نمی‌کنند. یک پرسش تکرارپذیر را سه بار با نقشه و سه بار بدون آن، با تنظیم CLAUDE_CODE_ENABLE_TELEMETRY=1 و OTEL_METRICS_EXPORTER=console اجرا کنید، سپس میانه claude_code.token.usage را برای انواع input و cacheRead مقایسه کنید.

هنگام refactor چه اتفاقی برای گراف می‌افتد؟

ساختار خودش را دوباره تجزیه (re-parse) می‌کند. Graft وضعیت working tree را بررسی کرده و فقط فایل‌هایی را که تغییر کرده‌اند دوباره تجزیه می‌کند، بنابراین تغییر نام در پرس‌وجوی بعدی با حدود 3 میلی‌ثانیه سربار شناسایی می‌شود و چون فایل‌ها را می‌خواند (نه تاریخچه git)، کارهای کامیت‌نشده را نیز می‌بیند. خلاصه‌های نوشته‌شده توسط مدل هستند که قدیمی می‌شوند: هر گره یک content hash از منابع خود ذخیره می‌کند و منبع تغییریافته، گره را به‌جای بازنویسی، به عنوان قدیمی (stale) علامت‌گذاری می‌کند. برای مشاهده این انحراف graft check . و برای تازه‌سازی بخش متنی graft build --deep را اجرا کنید.

کدام agentهای برنامه‌نویسی امروزه می‌توانند از Graft استفاده کنند؟

تا آگوست 2026، graft init از Claude Code، Cursor، Codex، GitHub Copilot، Google Gemini، Kiro، Windsurf و AdaL پشتیبانی می‌کند. Claude Code بیشترین بهره را می‌برد: یک ورودی سرور MCP در .mcp.json، یک statusline، هوک‌های پس از ویرایش و یک فایل مهارت در .claude/. Codex یک بخش AGENTS.md به‌علاوه ورودی‌های سیستمی در ~/.codex/ دریافت می‌کند که graft init --no-global از آن‌ها صرف‌نظر می‌کند. سایر موارد یک فایل قوانین یا هدایت دریافت می‌کنند. هر کلاینت MCP دیگری می‌تواند با ثبت دستور npx -y @nanonets/graft@0.10.1 mcp مستقیماً از سرور استفاده کند.