كيف نستخدم Claude Code لصيانة مستودع Nuxt 4 + Rust الأحادي
Engineering Team
مجموعتنا التقنية ولماذا يناسبها Claude Code
في Open Soft، منتجنا الرئيسي هو موقع ويب مبني كمستودع أحادي: واجهة أمامية Nuxt 4 مع TypeScript وخلفية Rust/Axum API مدعومة بـ PostgreSQL. تمتد قاعدة الكود عبر لغتين ونظامي بناء وعقود بيانات مشتركة وترحيلات قواعد بيانات وملفات i18n لـ 10 لغات وبنية نشر تحتية. التغييرات تلمس في كثير من الأحيان كلا جانبي المجموعة التقنية في وقت واحد.
تبنينا Claude Code في منتصف 2025 وأصبح أداة التطوير الأكثر استخداماً لدينا. ليس لأنه يكتب الكود نيابة عنا — بل لأنه يستدل حول قاعدة كودنا بأكملها بطرق لا تستطيعها أي أداة أخرى. عندما تخبر Claude Code “أضف حقل published_at إلى المقالات”، يقرأ ترحيل Rust، ويحدّث استعلامات SQL في المعالج، ويعدّل أنواع TypeScript في الواجهة الأمامية، ويضبط مكون صفحة Nuxt، ويحدّث جميع ملفات اللغات العشر، ويشغل البناء للتحقق. هذا الوعي عبر المجموعة التقنية هو ما يجعله لا غنى عنه لتطوير المستودع الأحادي.
CLAUDE.md: تعليم الوكيل اتفاقياتك
أساس الاستخدام الفعال لـ Claude Code هو ملف CLAUDE.md. هذا ملف تعليمات على مستوى المشروع يقرأه Claude Code في بداية كل جلسة. فكر فيه كوثائق إعداد الموظف الجديد، لكن لوكيلك الذكي.
ملف CLAUDE.md لدينا يتضمن:
- اتفاقيات الالتزام: كل التزام يجب أن يبدأ بـ
TASK-XXX:ويستخدم صيغة الأمر - نظرة عامة على البنية: هيكل المستودع الأحادي، أي المجلدات تحتوي على ماذا
- قواعد أسلوب الكود: TypeScript الصارم، بدون
any، Composition API فقط، صيغة<script setup> - قواعد i18n: جميع اللغات العشر يجب أن تبقى متزامنة، المفاتيح مرتبة أبجدياً
- قواعد الأمان: لا أسرار في الالتزامات، SQL ذو معاملات، CORS صريح
- أوامر التطوير:
npm run dev،cargo run،make fixtures، إلخ.
Claude Code يتبع هذه الاتفاقيات باستمرار. عندما يولّد رسالة التزام، يستخدم بادئة TASK-XXX:. عندما يضيف مفتاح ترجمة، يضيفه إلى جميع ملفات اللغات العشر بترتيب أبجدي. عندما يكتب SQL، يستخدم استعلامات ذات معاملات. هذا يلغي فئة كاملة من تعليقات مراجعة الكود — انتهاكات الاتفاقيات.
إعادة الهيكلة متعددة الملفات: حالة الاستخدام القاتلة
سير العمل الذي يوفر لنا أكبر قدر من الوقت هو إعادة الهيكلة عبر المجموعة التقنية. إليك مثالاً حقيقياً من مشروعنا.
المهمة: إضافة حقول SEO (meta_title، meta_description، focus_keyword، robots_meta) إلى نظام المقالات.
بدون Claude Code، يتطلب هذا التغيير:
- كتابة ترحيل SQL يضيف 4 أعمدة
- تحديث هيكل
Articleفي Rust - تحديث DTOs
CreateArticleوUpdateArticleفي Rust - تحديث جميع استعلامات SQL في معالج المقالات
- تحديث نوع
Articleفي TypeScript في الواجهة الأمامية - تحديث نموذج محرر المدير ليشمل الحقول الجديدة
- تحديث صفحة المقال لعرض علامات الميتا
- تحديث منطق توليد خريطة الموقع
- تحديث جميع ملفات البيانات الأولية
- تشغيل الترحيلات وإعادة البناء والاختبار
مع Claude Code، نكتب أمراً واحداً ويُنفَّذ كحلقة وكيل واحدة عبر 12+ ملفاً. العملية بأكملها تستغرق حوالي 5 دقائق، مقارنة بـ 45-60 دقيقة يدوياً. والأهم أنه يلتقط أخطاء المراجع التبادلية التي يفوّتها البشر.
كتابة الترحيلات
ترحيلات قواعد البيانات مناسبة بشكل خاص لـ Claude Code لأنها تتطلب فهم المخطط الحالي والحالة النهائية المرغوبة ومسار التحويل الآمن بينهما.
عندما نطلب من Claude Code كتابة ترحيل، يقوم بـ:
- قراءة جميع ملفات الترحيل الحالية لفهم المخطط
- قراءة نماذج Rust لفهم الحالة المستهدفة
- كتابة SQL الترحيل مع عبارات
ALTER TABLEمناسبة - إضافة حراسات
IF NOT EXISTSللتكرارية عند الاقتضاء - تحديث نماذج ومعالجات Rust لاستخدام المخطط الجديد
توليد الاختبارات
نستخدم Claude Code بشكل مكثف لتوليد بيانات الاختبار الأولية وبيانات SQL التمهيدية. ملفات البيانات الأولية لدينا تحتوي على محتوى واقعي طويل (مقالات بأكثر من 1500 كلمة) مع بيانات SEO وصفية مناسبة، وكتابتها يدوياً مملة وعرضة للخطأ.
لاختبارات Rust الوحدوية، يقرأ Claude Code التنفيذ ويحدد الحالات الحدية ويولّد دوال اختبار بأسماء وصفية.
مراجعة الكود مع Claude Code
قبل فتح طلب دمج، نشغّل Claude Code كمراجع. يقوم بـ:
- تشغيل
git diff main...HEADلرؤية جميع التغييرات - تحليل كل ملف بحثاً عن مشاكل محتملة
- التحقق من حقن SQL (استعلامات غير ذات معاملات)
- التحقق من وجود مفاتيح i18n في جميع اللغات العشر
- التحقق من استدعاءات
.unwrap()في كود Rust الإنتاجي - التحقق من أن معالجة الأخطاء تتبع أنماطنا
هذا يلتقط حوالي 30% من المشاكل التي كانت ستُكتشف في مراجعة الكود البشرية.
الخطافات: أتمتة بوابات الجودة
يدعم Claude Code الخطافات — سكربتات تعمل تلقائياً قبل أو بعد إجراءات معينة.
خطاف ما قبل الالتزام: يشغّل cargo fmt --check وcargo clippy قبل أن ينشئ Claude Code التزاماً. إذا فشل أيّ منهما، يصلح Claude Code المشاكل ويعيد المحاولة.
خطاف ما بعد التحرير: بعد أن يعدّل Claude Code أي ملف في /i18n/locales/، يشغّل خطاف سكربتاً يتحقق من أن جميع ملفات اللغات العشر لديها مجموعات مفاتيح متطابقة.
خوادم MCP: توسيع قدرات Claude Code
تتيح خوادم Model Context Protocol (MCP) إعطاء Claude Code وصولاً إلى أدوات خارجية. نشغّل خادمي MCP مخصصين:
- خادم MCP لقاعدة البيانات: يتيح لـ Claude Code الاستعلام من PostgreSQL التطويري مباشرة.
- خادم MCP لحالة النشر: يتصل بخط أنابيب CI/CD لدينا. يمكن لـ Claude Code التحقق مما إذا نجح آخر نشر.
نصائح لقواعد الكود الكبيرة مع سياق 1M
دع Claude Code يستكشف. لا تحاول اختيار الملفات مسبقاً. صف ما تريد ودع Claude Code يستخدم أدواته (Grep، Glob، Read) للعثور على الكود ذي الصلة.
استخدم CLAUDE.md للسياق الثابت. المعلومات التي لا تتغير بين الجلسات — البنية والاتفاقيات والأوامر — توضع في CLAUDE.md.
قسّم المهام الضخمة إلى مراحل. حتى مع 1M رمز، مهمة مثل “أعد هيكلة نظام المصادقة بالكامل” تستفيد من التقسيم.
ثق بحلقة الوكيل. عندما يجري Claude Code تغييراً ويشغّل البناء ويرى خطأً ويصلحه — تلك الحلقة هي الميزة. لا تقاطعها في منتصف الدورة.
المزالق والحلول
المزلق: Claude Code يبالغ في الهندسة. أحياناً يضيف تجريدات أو أنماط غير ضرورية. الحل: أضف “KISS — أبقِ الأمر بسيطاً” إلى CLAUDE.md.
المزلق: السياق القديم في الجلسات الطويلة. بعد تعديلات كثيرة، قد ينحرف فهم Claude Code. الحل: ابدأ جلسة جديدة لكل مهمة رئيسية.
المزلق: مخرجات غير حتمية. نفس الأمر قد ينتج كوداً مختلفاً. الحل: استخدم أوامر محددة ومفصلة.
الخلاصة
Claude Code ليس عصا سحرية تكتب تطبيقك نيابة عنك. إنه مضاعف قوة يتفوق في الاستدلال عبر المجموعة التقنية وفرض الاتفاقيات والتغييرات المملة متعددة الملفات. الرؤية الرئيسية بعد 9 أشهر من الاستخدام اليومي: Claude Code أكثر قيمة ليس لكتابة كود جديد، بل لصيانة الكود الحالي — إعادة الهيكلة والترحيل والاختبار والمراجعة.