عامل هوش مصنوعی شما نمی‌تواند مشخصات فنی (Specifications) را که در مخزن دوم پروژه‌تان قرار دارند ببیند. برای توسعه‌دهندگانی که با معماری میکروسرویس سر و کار دارند، این یک انتخاب طاقت‌فرسا است: یا پنجره‌ی زمینه (Context Window) خود را با فایل‌های نامرتبط پر کنید و یا توکن‌های خود را برای یافتن سندهایی که می‌دانید وجود دارند اما مکانشان نامشخص است، به باد دهید. این تنگنا دقیقاً همان چیزی است که منجر به توسعه Repospec شد؛ ابزاری تخصصی که برای حل مشکل «کشف مشخصات در مخازن متقاطع» (Cross-repo specification discovery) طراحی شده است.
کدنویسی مدرن با کمک هوش مصنوعی به شدت بر پایه «زمینه» یا Context استوار است، اما این زمینه معمولاً محدود به فضای کاری (Workspace) فعال است. در یک معماری میکروسرویس، جایی که سرویس A به تعارینی در سرویس B وابسته است، هوش مصنوعی اغلب «بینایی» لازم برای پل زدن میان این شکاف را ندارد. این اصطکاک به‌ویژه برای توسعه‌دهندگان تک‌نفره که از قطعات کوچک و «قابل اتمام» برای مدیریت محدوده پروژه استفاده می‌کنند اما مستندات خود را در مخازن مجزا و اختصاصی نگه می‌دارند، بسیار شدیدتر است.
نویسنده این ابزار رویکردی را توصیف می‌کند که در آن قطعات کوچک به سبک میکروسرویس ساخته می‌شوند تا از عادت رایج «راضی شدن در نیمه راه پروژه‌های سرگرمی و هرگز منتشر نکردن آن‌ها» جلوگیری شود. با کاهش ابعاد پروژه به یک «اندازه قابل اتمام»، توسعه‌دهنده می‌تواند یک قطعه را به پایان برساند و بعداً از آن مجدداً استفاده کند، بدون اینکه این کار ماه‌ها از عمر او را ببلعد. برای فراهم کردن زمینه لازم برای AI در این ساختار توزیع‌شده، نوشتن اسناد مشخصات (Spec documents) دقیق — حتی برای پروژه‌های شخصی — به یک استاندارد تبدیل شد. این رویکرد با استراتژی توسعه‌ی مبتنی بر مشخصات همسو است که برای کاهش توهمات AI در کدنویسی استفاده می‌شود. اما وقتی مخزنی که در Cursor باز شده است مربوط به سرویس A باشد، در حالی که سند مشخصات در مخزن سرویس B است، AI نسبت به آن نابینا می‌شود. این وضعیت منجر به یک پرسش بنیادی می‌شود: «چگونه سندی را که خارج از فضای کاری فعلی من قرار دارد، به دست AI برسانم؟»
طبق یک گزارش فنی مفصل که در ۱۹ جولای ۲۰۲۶ در وب‌سایت dev.to منتشر شد، توسعه‌دهنده این ابزار دو مسیر اصلی را برای حل این مشکل بررسی کرد:
گزینه الف: ایندکس کردن همه چیز
اولین راه، «ایندکس کردن همه چیز» با استفاده از Multi-root workspaces در Cursor است. این روش شامل اضافه کردن کل مخزن مشخصات به فضای کاری فعال می‌شود. طبق مستندات به‌روزرسانی آپریل ۲۰۲۶ Cursor، یک جلسه عامل (Agent Session) می‌تواند یک فضای کاری با پوشه‌های متعدد را هدف قرار دهد و تغییراتی را در مخازن مختلف ایجاد کند (همان‌طور که در Changelog ذکر شده است). این قابلیت برای جریان‌های کاری مانند «اصلاح یک مورد در هر دو بخش فرانت‌اند و بک‌اند» مفید است، اما برای خواندن مستندات، هزینه ساختاری آن همچنان بالاست.
هر پوشه‌ای که به فضای کاری اضافه شود، بخشی از ایندکس می‌شود. نویسنده چندین نشانه از این فشار بیش از حد (Overload) را ذکر کرد:
- فایل‌های نامرتبط به طور خودکار وارد زمینه AI می‌شوند.
- فایل‌هایی از مخازنی که در حال حاضر روی آن‌ها کار نمی‌شود، در نتایج جست‌وجو ظاهر می‌شوند.
- ویرایش‌ها گاهی در مکان‌هایی اعمال می‌شوند که کاربر هرگز درخواست تغییر آن‌ها را نداده است.
- مصرف توکن‌ها به سرعت و به صورت تصاعدی افزایش می‌یابد.
گزینه ب: بازیابی بر اساس نیاز (Fetch on Demand)
مسیر دوم «بازیابی بر اساس نیاز» است، جایی که توسعه‌دهنده مخزن را خارج از فضای کاری نگه می‌دارد و AI فایل‌ها را در صورت نیاز فرا می‌خواند. این کار اغلب با نوشتن مسیرهای دقیق فایل در یک فایل قوانین (Rules file) انجام می‌شود. اگر مسیر دقیق فایل شناخته شده باشد، این روش بسیار بهینه عمل می‌کند.
با این حال، این روش در حالت «صبر کن، می‌دانم این را جایی نوشتم» شکست می‌خورد. چون AI مسیر دقیق را نمی‌داند، مجبور است چندین فایل کاندید را بخواند تا اطلاعات را مکان‌یابی کند. این کار مستلزم بارگذاری کامل محتوای فایل‌ها در زمینه (Context) است تا صرفاً یک جست‌وجو انجام شود، که حجم عظیمی از توکن‌ها را مصرف می‌کند. در واقع، توسعه‌دهنده باید بین پرداخت هزینه به صورت «نویز» (برای ایندکس همه چیز) یا پرداخت هزینه توکن (برای خواندن همه چیز) یکی را انتخاب کند.
اشتباه در ارزیابی سرور MCP گیت‌هاب
نویسنده پیش از ساخت یک ابزار سفارشی، راهکارهای موجود را بررسی کرد؛ از جمله ابزارهای مستندسازی خود-میزبان (Self-hosted) با استفاده از Docker (که انعطاف‌ناپذیر به نظر می‌رسیدند) و سرویس‌های SaaS مستندسازی خارجی (که یا بیش از حد گران بودند یا برای پروژه‌های تک‌نفره بیش از حد پیچیده بودند).
تلاش برای استفاده از زیرساخت‌های موجود، یک دام رایج را آشکار کرد: اعتماد به تحقیقات AI به‌جای منابع دست اول. نویسنده در ابتدا GitHub MCP Server را رد کرد زیرا تصور می‌کرد این سرور به کانتینرهای Docker محلی نیاز دارد. بر اساس یک چت تحقیقاتی با AI، او فرض کرد اگر کانتینری در محل لازم باشد، تفاوتی با گزینه‌های قبلی خود-میزبان ندارد.
اما بررسی مجدد GitHub Changelog نشان داد که یک نسخه میزبانی‌شده (Remote-hosted) در سپتامبر ۲۰۲۵ به صورت عمومی (General Availability) عرضه شده است. این نسخه نیاز به Docker یا مدیریت توکن‌های دسترسی شخصی (PAT) را از طریق یک احراز هویت ساده OAuth کاملاً حذف کرده است. نویسنده اعتراف کرد که اگر نسبت به تحقیقات AI شکاک‌تر بود و منابع دست اول را بررسی می‌کرد، شاید هرگز ساخت Repospec را آغاز نمی‌کرد. این مورد به عنوان یادآوری عمل کرد که تحقیقات AI می‌تواند بر اساس پیش‌فرض‌های قدیمی یا کاملاً غلط باشد. این چالش در درک محدودیت‌های AI، یادآور این بحث است که چرا باید مدل‌های زبانی را در سطح تکمیل‌کننده کد دید و نه لزوماً به عنوان معماران پروژه.
علیرغم وجود نسخه Remote، سرور MCP گیت‌هاب اصطکاک‌های عملیاتی خاصی را برای جست‌وجوی روزمره مستندات ایجاد می‌کند:
- محدودیت شاخه (Branch): فقط شاخه پیش‌فرض جست‌وجو می‌شود و مستنداتی که در شاخه‌های دیگر قرار دارند خارج از محدوده هستند.
- سقف حجم فایل: فقط فایل‌های کوچک‌تر از ۳۸۴ کیلوبایت جست‌وجو می‌شوند. اگرچه اکثر مستندات در این محدوده هستند، اما این یک محدودیت سخت است.
- محدودیت شدید نرخ درخواست (Rate Limits): API جست‌وجوی کد برای کاربران احراز هویت شده به ۱۰ درخواست در دقیقه محدود شده است. این یک ظرفیت بسیار کمتر از محدودیت کلی API است که ۵۰۰۰ درخواست در ساعت است. از آنجایی که عامل‌های AI اغلب پرس‌وجوهای جست‌وجو را در حلقه‌های آزمون و خطا ارسال می‌کنند، این سقف به‌سرعت پر می‌شود.
- تأخیر دو مرحله‌ای: نتایج جست‌وجو عمدتاً متادیتای فایل را ارائه می‌دهند. API می‌تواند قطعات کوتاهی از هایلایت‌ها را ارائه دهد، اما خواندن محتوای واقعی مستلزم یک درخواست Fetch تکمیلی است. این یعنی برای هر پرس‌وجو، حداقل دو رفت و برگشت (جست‌وجو و سپس بازیابی) لازم است.
سازوکار Repospec
برای دور زدن این محدودیت‌ها، Repospec بار جست‌وجو را از مخزن به یک پایگاه‌داده منتقل می‌کند. با ذخیره محتوای مشخصات در PostgreSQL، این ابزار امکان جست‌وجوهای تک-پرسشی (Single-query) — و در نهایت جست‌وجوی برداری (Vector Search) — را فراهم می‌کند که تنها خطوط منطبق به همراه چند خط زمینه را بازمی‌گرداند. این معماری محدودیت ۱۰ درخواست در دقیقه را حذف کرده و از جاری شدن داده‌های غیرضروری در زمینه AI جلوگیری می‌کند.
Repospec به عنوان یک پنجره کوچک و فقط-خواندنی (Read-only) به مستندات شما عمل می‌کند. جریان کاری آن شامل موارد زیر است:
- ثبت یک فایل خاص در یک مخزن خاص به عنوان یک «Spec» از طریق یک داشبورد.
- دسترسی به قابلیت‌های Fetch و جست‌وجوی متقاطع (Cross-repo) تنها روی این مستندات ثبت شده از طریق Cursor یا Claude Code با استفاده از MCP.
توسعه‌دهنده عمداً قابلیت‌های ویرایش و کنترل نسخه را حذف کرد تا از ساخت یک «GitBook بدتر» جلوگیری کند. اصل طراحی این بود که هر آنچه غیرضروری است حذف شود و منبع حقیقت (Source of Truth) را محکم در مخازن گیت‌هاب نگه دارد و با Repospec صرفاً به عنوان یک لوله‌کشی فقط-خواندنی برای کشف اطلاعات برخورد کند. در زمان نوشتن این متن، پروژه در مرحله پیش‌از-عرضه (Pre-launch) است و تنها یک صفحه فرود برای اعلان‌های انتشار دارد.
این تغییر رویکرد نشان‌دهنده یک روند گسترده‌تر در تجربه توسعه‌دهندگان (DevX) است: همان‌طور که پروژه‌ها به سمت معماری‌های توزیع‌شده و دانه‌بندی شده‌تر (Granular) حرکت می‌کنند، گلوگاه دیگر توانایی استدلال AI نیست، بلکه کارایی خط لوله بازیابی اطلاعات (Retrieval Pipeline) است. گذار از «ایندکس کردن همه چیز» به «ایندکس کردن فقط حقیقت»، نشان‌دهنده حرکتی به سمت مدیریت جراحی‌شده‌ی زمینه است.
برای اکثر توسعه‌دهندگان، راهکار فوری این است که مسیرهای مخزن مشخصات را در .cursor/rules بنویسند و اجازه دهند GitHub MCP Server آن‌ها را بخواند. اگر پروژه به اندازه کافی کوچک باشد که مسیرها به‌خاطر بمانند، نیازی به ابزار اضافی نیست. اما وقتی ترکیب «تعداد زیاد مخازن» در ضرب با «یادم نیست کجا چه نوشتم» به یک واقعیت روزمره تبدیل شود، انتقال لایه جست‌وجو به خارج از مخزن، تنها راه حفظ جریان کاری (Flow) بدون پرداخت مالیات سنگین توکن است.
وقتی صحبت از «تسلط» بر توسعه با کمک AI به میان می‌آید، هنوز فضای زیادی برای هنر و مهارت (Craft) وجود دارد. خارش برای بهینه‌سازی هرگز کاملاً برطرف نمی‌شود. اکوسیستم در حال تکامل Model Context Protocol را زیر نظر داشته باشید، زیرا سرورهای تخصصی فقط-خواندنی مانند Repospec برای حل مشکل «تکه تکه شدن زمینه» (Context Fragmentation) در سیستم‌های توزیع‌شده ظهور می‌کنند.
گام بعدی شما
- اگر از Cursor استفاده می‌کنید، لیست مسیر مستندات کلیدی خود را در فایل rules قرار دهید.
- برای پروژه‌های توزیع‌شده، از GitHub MCP Server نسخه Remote استفاده کنید تا نیاز به Docker نداشته باشید.
- چشم به اکوسیستم MCP داشته باشید؛ سرورهای Read-only تخصصی مانند Repospec آینده‌ی مدیریت زمینه (Context) در سیستم‌های پیچیده هستند.
اما داستان سخت‌افزاری این تحول حتی شگفت‌انگیزتر است — به تحلیل ما درباره‌ی تراشه‌های Blackwell مراجعه کنید.
گفتگو