أنشئ ثلاثة ملفات Spec قبل استخدام Claude Code وCodex

بعد ما يقارب عامًا من الاستخدام اليومي لوكلاء البرمجة بالذكاء الاصطناعي، لم يُزعجني الكود الهلوسي أو الواجهات البرمجية الخاطئة بقدر ما أزعجني التذبذب. المهمة نفسها، بصياغة مختلفة قليلًا، تنتج مخرجات نظيفة يومًا وفوضى في اليوم التالي. وكلما طالت الجلسة، تفاقم الأمر؛ إذ ينسى الوكيل الاتفاقيات التي جرى التوصل إليها قبل عشرين رسالة.

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

ثلاث طبقات غيّرت النتيجة

تقسيم التعليمات إلى ثلاثة ملفات، كل منها بدور محدد، أصلح مشكلة التذبذب شبه فورًا.

الطبقة الأولى، CLAUDE.md تُحمَّل تلقائيًا في كل جلسة. تحتوي على ثوابت المشروع: أوامر البناء، وإصدارات التقنيات المستخدمة، وهيكل المجلدات، وأسلوب الكتابة البرمجية، والحدود السلوكية (افعل دائمًا X، اسأل قبل Y، لا تفعل Z أبدًا).

الطبقة الثانية، SPEC.md ترصد الماذا والسبب لميزة محددة. الغرض والمتطلبات ومعايير النجاح والقيود التقنية وحدود النطاق. لا شيء يتعلق بتفاصيل التنفيذ.

الطبقة الثالثة، plan.md تُفكّك المواصفات إلى مهام قابلة للتنفيذ في دقيقتين إلى خمس دقائق، مع مسارات ملفات صريحة وترتيب يضع الاختبار أولًا ونقاط تحقق للـ commit.

لماذا يفشل حشر كل شيء في ملف واحد

تصف الأبحاث المتعلقة بمتابعة اللغوية الكبيرة للتعليمات هذا بـ”لعنة التعليمات”. كلما ازداد عدد التوجيهات في سياق واحد، انخفض معدل الامتثال لكل توجيه بشكل حاد. اختبرت ذلك مباشرةً: ملف واحد يحتوي على قواعد المشروع ومواصفات الميزات وقوائم المهام جعل الوكيل يتجاهل ما يقارب نصف التعليمات الموجودة في الأسفل.

الفصل حسب الدور حلّ المشكلة. يقرأ الوكيل القواعد العامة من الطبقة الأولى، ونية الميزة من الطبقة الثانية، وخطوات التنفيذ من الطبقة الثالثة. يبقى كل ملف قصيرًا بما يكفي لأن يولي النموذج انتباهه الكامل له.

CLAUDE.md يعمل بشكل أفضل حين يظل مختصرًا

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

النهج الذي نجح معي كان البدء بالحد الأدنى والإضافة تدريجيًا في كل مرة ألاحظ فيها الوكيل يكرر خطأ ما. محاولة كتابة CLAUDE.md شامل من البداية أدى إلى انتفاخ أطلق نفس انخفاض الامتثال الذي كنت أحاول تجنبه.

بعض الأخطاء الشائعة: لا تضع مفاتيح API أو مقاطع كود هنا لأنها تتقادم بسرعة. لا تكرر قواعد يطبّقها الـ linter أصلًا. وانقل أي شيء خاص بميزة واحدة إلى الطبقة الثانية.

ملفات Spec تركّز على الماذا والسبب، وتترك الكيف للوكيل

الفرق عن PRD التقليدي أن هذه المواصفات مهيكلة للاستهلاك من قِبل الوكيل. خمسة أقسام تكفي: الغرض، والمتطلبات، ومعايير النجاح، والقيود التقنية، والحدود.

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

بديل لكتابة المواصفات يدويًا: دع الوكيل يجري معك مقابلة. ضع قاعدتين: سؤال واحد في كل مرة وخيارات متعددة كلما أمكن. المواصفات الناتجة كانت أقل ثغرات مما كتبته بنفسي من الصفر.

احفظ المواصفات المكتملة في docs/specs/YYYY-MM-DD-topic.md وادفعها إلى Git. هذا يمنح الوكيل إمكانية الوصول إلى تاريخ تغييرات المواصفات عبر git diff، ويوفر للمراجعين سجلًا بالنية الكامنة وراء تغييرات الكود.

فصل الجلسات من أكثر الممارسات إغفالًا

العصف الذهني والأسئلة أثناء كتابة المواصفات تستهلك جزءًا كبيرًا من نافذة السياق. الانتقال مباشرة إلى التنفيذ من الجلسة نفسها يعني أن الوكيل يفقد تدريجيًا إمكانية الوصول إلى السياق المبكر.

أعدت هيكلة العمل إلى ثلاث جلسات: الجلسة الأولى تنتج SPEC.md، والثانية تنشئ plan.md، والثالثة فصاعدًا تنفّذ المهام واحدة تلو الأخرى. كان تحسن الدقة ملحوظًا خلال الأسبوع الأول.

ثلاث عادات جعلت هذا يعمل: كتابة مسارات الملفات الصريحة في كل مهمة حتى يتوقف الوكيل عن التخمين، وتثبيت ترتيب TDD (الاختبار أولًا، التنفيذ، التحقق، الـ commit) في plan.md، وبدء جلسة جديدة في كل مرة يصل فيها استخدام السياق إلى حوالي 50%.

نموذج النضج يشير نحو Spec كمصدر الحقيقة

حدّد فريق Martin Fowler مؤخرًا نموذج نضج للتطوير البرمجي القائم على الوكلاء بثلاثة مستويات. المستوى الأول: اكتب مواصفة، نفّذ، تخلص من المواصفة. المستوى الثاني: احتفظ بالمواصفة كوثيقة حية بجانب الكود. المستوى الثالث: تصبح المواصفة المصدر الوحيد للحقيقة، والكود مجرد ناتج مولَّد.

معظم الفرق والأفراد الذين أعرفهم لم يبلغوا المستوى الأول بعد. إنهم يرسلون أوامر آنية ويأملون في الأفضل.

الانتقال من المستوى الأول إلى الثاني يتطلب عادة واحدة: إيداع ملفات المواصفات في Git. الانتقال من الثاني إلى الثالث يعني تحديث المواصفة قبل تغيير الكود. أصغر خطوة يمكنك اتخاذها اليوم هي إنشاء CLAUDE.md لمشروعك وكتابة SPEC.md قبل الميزة التالية.