مهارة ast-grep: ابحث في الشفرة حسب البنية النحوية، لا حسب النص فقط

لمن تناسب

استخدم هذه المهارة عندما تريد أن يبحث مساعد البرمجة حسب بنية الشفرة (شجرة التركيب المجردة)، لا حسب مطابقة النص فقط. رسميًا وُضعت في سوق إضافات Claude Code وتوفر البحث البنيوي عبر ast-grep.

الشروط المسبقة: ast-grep مثبت مسبقًا على هذا الجهاز، والمساعد قادر على تثبيت المهارات. الدليل لا يشرح كيفية تثبيت ast-grep نفسه؛ لا تختلق برنامج تثبيت. الدليل يسمي Claude Code؛ لا تصف عملاء آخرين بأنهم حصريون رسميون. إمكانية الاستخدام خارج هذه المجموعة المسماة غير مذكورة.

مسار التثبيت واحد فقط: أمر npx واحد. بعد التثبيت يجب أن تطلب صراحة استخدام المهارة في السؤال، مثل "Use ast-grep to find...". يقول الدليل إنه حتى نوفمبر 2025 لا يستطيع Claude Code أن يقرر تلقائيًا استخدام ast-grep في كل موقف مناسب. الدليل لا يسمي مجلد الوجهة؛ بعد التثبيت أكّد فقط في المساعد الحالي أن المهارة يمكن استدعاؤها بالاسم.

أول محاولة في 3 دقائق

الصفحة الرسمية:

https://github.com/ast-grep/agent-skill

أكد أولًا أن ast-grep المحلي يعمل، ثم نفّذ التثبيت الموصى به (يكتب ملفات المهارة على هذا الجهاز؛ تحقق أولًا من اسم المستودع):

npx skills add ast-grep/agent-skill

إذا فشل الأمر فتوقف. بعد النجاح لا تغيّر شفرة التطبيق أولًا. افتح مستودعًا موجودًا وقل بوضوح باللغة الطبيعية: Use ast-grep to find...، مع هدف بنيوي منخفض المخاطر، مثل البحث عن شكل معيّن لاستدعاء دالة. اطلب من المساعد أن يحلّل أولًا هل ast-grep مناسب، وأن يكتب أمثلة وقواعد للمطابقة، وأن يختبر على الأمثلة أولًا.

علامة النجاح: استخدم المساعد ast-grep صراحة، وتحققت القاعدة على الأمثلة، ونتائج المستودع بالكامل تتضمن مسارات الملفات وأرقام الأسطر. إذا أراد كتابة ملف قواعد أو تغيير شفرة التطبيق فأوقفه أولًا وأكّد الآثار الجانبية قبل المتابعة.

حالات استخدام

الحالة 1: بحث بنيوي للقراءة فقط. يجب أن يسمي السؤال ast-grep صراحة. دع المساعد يجد المطابقات حسب البنية ويعيد مسارات الملفات وأرقام الأسطر. في المرة الأولى انظر إلى النتائج فقط؛ لا تدعه يعيد الهيكلة في الطريق. الدليل لا يعطي نطاق لغات ولا مستودع مثال؛ لا تستنتج من قائمة لغات متخيّلة.

الحالة 2: اكتب القاعدة أولًا، ثم تحقق، وأخيرًا ابحث في المستودع كله. خطوات الدليل هي: تحليل ما إذا كان الاستعلام يناسب ast-grep، إنشاء شفرة مثال للمطابقة، كتابة القاعدة، اختبارها على المثال، البحث في قاعدة الشفرة كلها فقط بعد النجاح، ثم إعطاء المسارات وأرقام الأسطر. البحث في المستودع كله مسموح فقط بعد نجاح اختبار المثال. الدليل لا يكتب مسار ملف القواعد ولا أعلام CLI؛ لا تكمل الناقص.

حدود الاستخدام

المسار الرئيسي يوثّق فقط:

npx skills add ast-grep/agent-skill

هذا الجهاز يحتاج ast-grep مثبتًا مسبقًا. يجب أن يسمي التشغيل المهارة صراحة، مثل "Use ast-grep to find..."؛ لا تتوقع اختيارًا تلقائيًا في كل موقف.

القدرة مثبتة بالدليل فقط للبحث البنيوي ولسلسلة «مثال → قاعدة → اختبار → المستودع كله → مسار ورقم سطر». كُتبت كمهارة في سوق إضافات Claude Code، لكن في المحاولة الأولى لا تنتقل إلى خطوات نقر في السوق لم تظهر في النص.

الدليل لا يوثّق أوامر تثبيت ast-grep ولا الفوترة ولا نطاق اللغات ولا مجلد الوجهة. المحاولة الأولى بحث للقراءة فقط؛ لا تعاملها كمدخل لإعادة الهيكلة. ما لا سند له يبقى مجهولًا؛ لا تختلق عمليات.