GAIA: هيكل تطوير بالمواصفات أولاً لـ Claude Code

لمن هذا مناسب

يصف GAIA نفسه بأنه "A serious harness for Claude Code": هيكل هندسي جاد لـ Claude Code. إنه يحوّل «فكّر بوضوح قبل أن تبني» إلى عملية — المواصفات قبل الكود (Specs before code)، وبوابة جودة عند كل commit، وتدقيق من Code Audit Team عند كل merge. إنه مناسب للمطورين الذين:

• يستخدمون Claude Code في تطوير برمجيات حقيقي ويريدون أن يكون لكل تغيير سند من المواصفات أولاً، وأن يكون كل commit قابلاً للتحقق وكل merge قابلاً للتدقيق، لا كوداً غير مدقق يُنتج في محادثة واحدة.
• يقبلون قيود العملية: قبل كل commit يجب أن تجتاز فحص الأنواع وlint واختبارات الوحدة وStorybook وPlaywright E2E واختبار الدخان لخادم التطوير، ولا تُعد البوابة مجتازة إلا باجتيازها جميعاً.
• يستوفون شرط التشغيل: Node.js >= 22.22.0.

الحالات التالية غير مناسبة أو تتطلب تأكيداً مسبقاً:

• البيئات التي لا تستخدم Claude Code: يوصف رسمياً كهيكل لـ Claude Code فقط، ولم يُذكر إمكانية استخدامه مع agents أخرى.
• الحالات التي تريد فيها توليد سكربتات بسرعة فقط دون عملية مواصفات واختبارات: إنه يشترط كتابة المواصفات أولاً، فتكلفة التمهيد أعلى.
• توقّع محادثة عامة أو مساعدة خالصة في الكتابة: الوصف الرسمي يدور بالكامل حول قيود عملية التطوير ولا يذكر استخدامات أخرى.
• إلى جانب Node.js >= 22.22.0، لم يسرد الرسميون قيوداً بيئية أخرى، ويجب اعتبار توافق النظام مجهولاً إلى أن يُؤكَّد.

أول تجربة في 3 دقائق

المسار الرئيسي الموصى به واحد فقط: أنشئ المشروع أولاً بالأمر الرسمي، ثم ابدأ كتابة المواصفات من داخل Claude Code.

الشرط المسبق: تثبيت Node.js >= 22.22.0 على جهازك وإمكانية استخدام Claude Code.

التثبيت: نفّذ في الطرفية

npx create-gaia@latest my-app

يطلب الرسميون صراحةً بدء المشروع بهذه الطريقة، لا باستنساخ المستودع (clone) أو تفريعه (fork). الـ my-app في الأمر هو اسم المشروع الجديد؛ احتفظ بهذا الاسم في أول تجربة لتجنب الخلط مع المجلدات الموجودة.

تشغيل المهمة: ادخل إلى مجلد my-app المنشأ حديثاً واكتب /gaia-spec في Claude Code. يصف الرسميون هذه العملية بأنها تؤلف قطعة أثرية للمواصفات غير قابلة للتغيير عبر سؤال سقراطي (Socratic discovery). أي أنها لا تُنتج المستند فوراً، بل تسأل عن المتطلبات بنداً بنداً، وبعد إجاباتك تُقرّ الخلاصة في مواصفات. الأعراض الجانبية ونقطة التأكيد: تُنشئ قطعة أثرية للمواصفات تصبح غير قابلة للتغيير (immutable) بمجرد إنشائها، لذا أكّد المتطلبات بوضوح قبل إغلاق الأسئلة؛ ويُستحسن أن تكون أول تجربة داخل هذا المشروع الجديد تماماً دون لمس كود موجود.

إشارة النجاح: عندما تنتهي الأسئلة وتحصل على قطعة المواصفات الأثرية المولّدة فقد اكتملت عملية كتابة المواصفات. إن رأيت في الأثناء جولات من الأسئلة المتقاربة بدلاً من نص كامل فوري، فهذا هو التصميم المقصود — إنه يوضّح المتطلبات بالسؤال.

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

الحالة الأولى: تثبيت المتطلبات قبل بدء مشروع جديد. السيناريو: ستبدأ مشروعاً جديداً وتخشى أن تنجرف المتطلبات الشفهية عبر جولات المحادثة، فيختلف اتجاه التنفيذ من جولة إلى أخرى. البدء: في مشروع أُنشئ بـ npx create-gaia@latest my-app، أرسل /gaia-spec إلى Claude Code. العملية والنتيجة: يوضّح الـ agent المتطلبات بنداً بنداً بالسؤال السقراطي، ثم يُنتج في النهاية قطعة أثرية غير قابلة للتغيير للمواصفات؛ ولأن «المواصفات أولاً» هي طريقة عمل هذا الهيكل، تصبح هذه القطعة المرجع الموحّد قبل أي كتابة كود لاحقة. القطعة غير قابلة للتغيير، وجلسة الأسئلة قبل التوليد هي نقطة التأكيد الوحيدة، فحسم القرارات الأساسية قبل الإجابة. اسم ملف قطعة المواصفات وموقع تخزينها لم يذكرهما الرسميون، والنهاية القابلة للتأكيد هي خطوة «توليد قطعة أثرية غير قابلة للتغيير».

الحالة الثانية: عمل commit لتغيير صغير وتجربة بوابة الجودة قبل الـ commit. السيناريو: عدّلت موضعاً في الكود داخل مشروع GAIA وستعمل commit. البدء: نفّذ عملية commit كما في المعتاد. العملية والنتيجة: قبل الـ commit تُشغَّل بوابة جودة — فحص الأنواع (Typecheck) وlint واختبارات الوحدة وStorybook وPlaywright E2E واختبار الدخان لخادم التطوير — ولا تتم المتابعة إلا باجتيازها جميعاً؛ وفشل بند واحد يمنع إتمام الـ commit. اختر تغييراً محدود الأثر ليسهل ملاحظة سير البوابة كاملاً؛ تضم البوابة اختبارات E2E ودخاناً تُشغَّل فعلياً، فالتشغيل الأول عادةً أبطأ من commit بلا بوابة، كما يجب أن تكون بيئتك المحلية قادرة على تشغيل خادم التطوير. وجود طريقة لتجاوز البوابة غير مذكور رسمياً.

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

• بيئة التشغيل: المتطلب الرسمي المؤكد هو Node.js >= 22.22.0 فقط، ولم تُذكر قيود أخرى على مستوى النظام، فتحقق من البيئة بنفسك قبل الاستخدام.
• شرط العميل: GAIA موجَّه إلى Claude Code؛ ولم يُذكر رسمياً إمكانية استخدامه مع agents أخرى.
• الأعراض الجانبية ونقطة التأكيد: تُنشئ /gaia-spec قطعة أثرية غير قابلة للتغيير للمواصفات، وتسبقها جلسة أسئلة للتأكيد؛ والبوابة التي يستدعيها الـ commit تشغّل فعلياً الاختبارات وE2E واختبار الدخان لخادم التطوير.
• نطاق البوابة: بنود الفحص المدرجة رسمياً هي فحص الأنواع وlint واختبارات الوحدة وStorybook وPlaywright E2E واختبار الدخان لخادم التطوير تحديداً؛ ولم يُذكر إن كانت هناك فحوص أخرى.
• قيود الصندوق الرملي (sandbox): يذكر الرسميون أن قواعد الصندوق الرملي تمنع قراءة ملفات .env وملفات المفاتيح والشهادات والملفات المسماة بأسماء بيانات الاعتماد (block reads of .env files, key and certificate files, credential-named files)، لتقليل فرص الـ agent في لمس بيانات اعتماد حساسة.
• قيد الدمج: كل merge يمر بتدقيق من Code Audit Team؛ وشكل مخرجات التدقيق ومدته غير مذكورين رسمياً.
• ما لم يُؤكد بعد: العمليات غير /gaia-spec، وموقع تخزين المواصفات، ووجود واجهة رسومية، ونطاق اللغات المدعومة — كلها غائبة عن الصفحة الرسمية، فاعتمد على التعليمات الفعلية داخل المشروع.