Grepathy منطقِ عامل‌های کدنویس را برای جلوگیری از «پوسیدگی کد» مستند می‌کند

بزرگ‌ترین کابوس یک برنامه‌نویس، مواجهه با یک Pull Request (PR) پر از منطق‌های پیچیده‌ای است که نه خودِ او تایید کرده و نه می‌تواند دلیل وجودشان را توضیح دهد. برای حل این بحران، Grepathy تاریخچه‌های زودگذر چت را به مستنداتی دائمی تبدیل می‌کند که می‌توان آن‌ها را در مخزن کد ثبت (commit) کرد. به نقل از انتشار این ابزار در ۱۵ ژوئیه ۲۰۲۶ در گیت‌هاب، Grepathy تضمین می‌کند که هرگاه یک عامل (Agent) تصمیمی در طراحی بگیرد، دلیل آن «چرا» به‌جای ذخیره در یک لاگ موقت، در خودِ مخزن کد باقی بماند.

عامل‌های کدنویسی مانند Claude Code اغلب هنگام ساخت ویژگی‌های جدید، تصمیمات کوچک و خود‌مختاری می‌گیرند. این استدلال‌ها در تاریخچه‌ی چت‌هایی زندگی می‌کنند که Claude Code به‌صورت پیش‌فرض پس از ۳۰ روز حذف می‌کند. این اتفاق یک شکاف دانشی ایجاد می‌کند؛ جایی که بازبین‌های انسانی تغییری را می‌بینند — مثلاً پیش‌ساخت کاربران مهمان در Clerk — اما هیچ سندی ندارند که چرا عامل این مسیر را به مسیرهای دیگر ترجیح داده است. این چالش در واقع تکامل‌یافته‌ی نگرانیاتی است که در پروژه RAC-Core برای تبدیل تصمیمات فنی به کد مطرح شد تا از نادیده گرفته شدن استانداردهای تیمی توسط AI جلوگیری شود.

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

در یک مثال واقعی از یک پروژه قراردادی، یک عامل به‌تنهایی تصمیم گرفت کاربران مهمان را در Clerk پیش‌ساخت کند. این اقدام بخشی از هیچ برنامه یا پرامپت اولیه نبود. وقتی مدیر فنی (CTO) این تغییر را در PR دید و دلیلش را پرسید، برنامه‌نویس پاسخی نداشت چون خودش تصمیم‌گیرنده نبود و این تصمیم در جریان یک چت گذرا گرفته شده بود.

با Grepathy، این تصمیم پیشینی (a-priori) به‌صورت یک ورودی ساختاریافته در مخزن ذخیره می‌شود. این سند وضعیت را «به‌ابتکار عامل» (agent-initiated) نام‌گذاری می‌کند، فایل‌های اثرپذیر (مانند lib/clerk/* و db/schema/guests.ts) را لیست می‌کند و توضیح می‌دهد که عامل برای ساده‌سازی بررسی‌های احراز هویت در مراحل بعدی، این رویکرد را استنباط کرده است. همچنین ریسک انحراف کاربران مهمان از مسیر عادی ثبت‌نام را علامت‌گذاری می‌کند و به‌طور مشخص از بازبین می‌خواهد تایید کند که آیا کاربران مهمان باید به عنوان کاربران عادی مدل‌سازی شوند یا خیر.

Grepathy به‌صورت یک ابزار CLI عمل می‌کند که از طریق Git Hooks اجرا می‌شود. این ابزار تاریخچه‌های محلی جلسه را پس از اتمام کار می‌خواند، تصمیمات حیاتی را استخراج کرده و آن‌ها را در فایل‌های markdown در مسیر .ai/why/<branch>.md می‌نویسد. این فرآیند در پس‌زمینه رخ می‌دهد؛ ابزار از عامل نمی‌خواهد که وسط کار تصمیمات را ثبت کند، زیرا توسعه‌دهنده متوجه شده بود که عامل‌ها معمولاً در ثبت مداوم و سازگار یادداشت‌ها شکست می‌خورند.

جزئیات فنی و سازوکارها

• تزریق خودکار: یک هوک PreToolUse درست قبل از هر ویرایش اجرا می‌شود. اگر فایل ویرایش‌شده با یک الگوی glob در بخش «Touches:» مطابقت داشته باشد، ورودی مربوطه به زمینه (context) عامل تزریق می‌شود.
• بسته‌ی «چرا» (Why-Pack): مجموعه‌ای از خلاصه‌های ثبت‌شده است. عامل‌ها از طریق دو تریگر با این استدلال‌ها آشنا می‌شوند: یک اشاره‌گر در CLAUDE.md که در هر جلسه به‌طور خودکار بارگذاری می‌شود و هوک مذکور.
• حفاظ‌های حریم خصوصی: یک اسکنر داخلی، اسرار (secrets)، جزئیات مالی و گفتگوهای شخصی رفت و برگشتی را حذف می‌کند. این ابزار از دو بررسی قطعی — یک اسکنر اسرار/مالی و قانونی که هر ورودی حتماً باید به کد واقعی اشاره کند — پیش از اینکه کاربر فایل را برای Push بازبینی کند، استفاده می‌کند.
• وابستگی صفر در زمان اجرا: ابزار با TypeScript خالص نوشته شده و تنها به Node >= 20 و Git نیاز دارد. این یک CLI است که هیچ سرور ابری، هیچ حساب کاربری و هیچ باتی ندارد.
• تست‌های محصور (Hermetic Testing): مجموعه تست‌ها بدون کلید API یا دسترسی به شبکه و با استفاده از مدل‌های زبانی شبیه‌سازی‌شده (mocked LLMs) و مخازن موقت git اجرا می‌شوند. این تست‌ها مواردی چون حذف موارد تکراری معنایی (semantic dedupe)، قفل‌های هم‌زمانی (concurrency locking) و حفظ ویرایش‌های انسانی را پوشش می‌دهند.

گردش کار عملیاتی

Grepathy مسیر Push کد را مسدود نمی‌کند، به ناحیه staging دست نمی‌زند و خودش کد Push نمی‌کند. این ابزار با چندین عامل و worktreeهای مختلف به خوبی سازگار است. جریان تعامل ساده است: برنامه‌نویس طبق معمول با Claude کار می‌کند و هنگام اجرای git push ابزار Grepathy فایل «چرا» را نوشته و برای بازبینی نمایش می‌دهد. این رویکرد تکمیلی بر قابلیت‌هایی است که پروژه y در پیوند عامل‌های هوش مصنوعی با رابط‌های کاربری پویا به کار گرفته بود تا انعطاف‌پذیری سیستم را افزایش دهد.

کاربران می‌توانند سیستم را با دستورات خاص مدیریت کنند:

• grepathy init: نصب هوک‌ها و پوشه‌ها؛ همچنین پیشنهاد بازخوانی (backfill) جلسات قدیمی را می‌دهد.
• grepathy status / doctor: انجام بررسی‌های سلامت روی مواردی که استخراج شده‌اند یا قدیمی (stale) شده‌اند.
• grepathy context <path>: نمایش ورودی‌های قابل اعمال برای یک فایل خاص.
• grepathy sync: استخراج و ثبت (commit) فوری بدون نیاز به Push.
• grepathy distill / repair / off / on / uninstall: دستورات مربوط به نگهداری عمومی و پیکربندی.

در یک ارزیابی کور و پیش‌ثبت‌شده که در REPORT.md پروژه منتشر شد، توسعه‌دهنده دریافت که عامل‌هایی که به فایل‌های «چرا» دسترسی داشتند، جایگزین‌های ردشده (مانند تصمیم برای دور زدن یک CDN) را به‌درستی تشخیص دادند. در مقابل، عامل‌های بدون این زمینه، توهم (Hallucination) داشتند و دلایلی باورپذیر اما نادرست درباره تاریخچه کد می‌ساختند.

ارزیابی ارزش

این ارزیابی نشان داد ابزار در ذخیره استدلال‌ها پیش از حذف ۳۰ روزه توسط Claude Code بسیار موفق است؛ شکافی که پیش‌تر باعث از بین رفتن تاریخچه دو پروژه شده بود. Grepathy دانشی را ثبت می‌کند که در کد هیچ ردی از آن نیست، مانند رد صریح استفاده از یک CDN.

با این حال، تست‌ها نشان داد که این ابزار عامل‌ها را به‌معنای کلی «باهوش‌تر» نمی‌کند و جلوی بازنویسی (Refactoring) کدهای مهم توسط عامل را نمی‌گیرد. اگر پاسخی از خودِ کد قابل خواندن باشد، عامل‌ها بدون کمک آن را می‌یابند. Grepathy دقیقاً برای اطلاعاتی طراحی شده که هیچ‌کجا نوشته نشده‌اند.

این تغییر، بخشی از بدهی فنی هوش مصنوعی را برطرف می‌کند. با انتقال استدلال از رابط چت به سیستم کنترل نسخه، منطق تبدیل به دارایی‌ای می‌شود که با تغییر برنامه‌نویس یا انقضای تاریخچه چت، از بین نمی‌رود. این ابزار فرض «جعبه سیاه» بودن کدهای تولید شده توسط AI را می‌شکند و استدلال عامل را به یک اثر قابل بازبینی تبدیل می‌کند. این مدیریت متمرکز از منطق، مشابه همان هدفی است که ابزار klaussy-agents برای یکپارچه‌سازی مهارت‌های کدنویسی دنبال می‌کرد تا هماهنگی میان عامل‌های مختلف را تضمین کند.

برای متخصصان، تگ «به‌ابتکار عامل» به یک لاگ حسابرسی قابل جست‌وجو تبدیل می‌شود. شما می‌توانید با اجرای grep -rn "agent-initiated" .ai/why/ تمام تصمیماتی را که عامل بدون دخالت انسان گرفته ببیند و بازبینی PR را از یک بازی حدس‌زدن به یک فرآیند تایید تبدیل کنید.

مقیاس‌پذیری این الگو برای تیم‌های بزرگ به نحوه مدیریت این فایل‌های markdown در طول زمان بستگی دارد. در حالی که فعلاً برای نوشتن به Claude Code نیاز است، بخش خواندن برای هر ابزاری باز است زیرا فایل‌ها markdown استاندارد هستند. گام بعدی پروژه، انتشار یک آداپتور Codex برای پشتیبانی از ابزارهایی فراتر از Claude Code خواهد بود.

گام بعدی شما

• اگر از Claude Code یا عامل‌های مشابه برای پروژه‌های تیمی استفاده می‌کنید، Grepathy را نصب کنید تا منطق تصمیمات AI در Git ثبت شود.
• برای شروع، دستور grepathy init را اجرا کرده و سعی کنید جلسات قدیمی را بازخوانی (backfill) کنید.
• در بازبینی PRها، به‌جای پذیرش کورکورانه تغییرات، فایل‌های .ai/why/ را بررسی کنید تا ریسک‌های احتمالی استنباط‌شده توسط مدل را بسنجید.

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