أنشئ ثلاثة ملفات مواصفات قبل تكليف Claude Code أو Codex بأي عمل

في يومٍ ما، أعطيتُ Claude Code مهمةً بسيطة: “أضف التحقق من صحة النموذج.” انتهى الأمر بكتابة منطق التحقق مباشرةً في المكوّن، متجاهلاً مكتبة الأدوات المشتركة التي بنيتُها طوال أسابيع. وفي يومٍ آخر، أعطيتُ المهمة ذاتها تقريباً لنفس النموذج، فاستخدم المكتبة الصحيحة، وأضاف اختبارات، ووثّق التغيير. الفرق بين الجلستين لم يكن في الأداة ولا في الطلب، بل كان في المعلومات المتاحة للوكيل عند بداية العمل.

هذه الإشكالية أعمق مما تبدو للوهلة الأولى.

المشكلة الجذرية: غياب النية المهيكلة

وكلاء الذكاء الاصطناعي يستطيعون قراءة الكود بكفاءة مذهلة. لكنهم لا يستطيعون قراءة عقلك. حين تبدأ جلسةً جديدة، يرى الوكيل الملفات كما هي الآن، لكنه لا يعرف لماذا اخترتَ هذه البنية، وما القرارات التي رفضتَها، وما الاتجاه الذي تسير فيه، وما القيود التي تعمل ضمنها.

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

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

الطبقات الثلاث لنظام المواصفات

الحل الذي توصلتُ إليه بعد أشهر من التجربة هو بناء ثلاث طبقات من الوثائق المهيكلة تُغذّي الوكيل بالسياق الصحيح قبل أن يكتب سطراً واحداً من الكود.

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

لماذا التعليمات وحدها لا تكفي: بحث “لعنة التعليمات”

قبل الخوض في التفاصيل، من المفيد فهم لماذا الكتابة الجيدة في حقل الـ prompt لا تحل المشكلة. أظهرت دراسات متعددة في تقييم LLMs ما يمكن تسميته بـ “لعنة التعليمات”: كلما أطلتَ التعليمات وزدتَ تفصيلها في رسالة واحدة، ازداد احتمال أن يُولي النموذج اهتماماً انتقائياً لأجزاء منها دون أخرى.

المشكلة ليست في جودة كتابتك، بل في طبيعة آلية الانتباه في النماذج اللغوية الكبيرة. التعليمات الطويلة تتنافس على الاهتمام، والمعلومات التي تظهر في المنتصف تُنسى بشكل غير متناسب.

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

الطبقة الأولى: CLAUDE.md كدستور المشروع

ملف CLAUDE.md هو أول ما يقرأه Claude Code عند بدء أي جلسة. فكّر فيه كدستور المشروع: يحتوي على القرارات التي لا تتغير من مهمة لأخرى، والقيود التي تنطبق دائماً، والأنماط التي يجب اتباعها في كل مكان.

المحتوى الفعّال لهذا الملف ليس قائمة تعليمات، بل سياق استراتيجي. هناك فرق جوهري:

التعليمات تقول: “استخدم TypeScript strict mode.” السياق الاستراتيجي يشرح: “نستخدم TypeScript strict mode لأن قاعدة الكود تُستهلك من خدمات خارجية لا نتحكم فيها، وأي نوع غير محدد قد يُسبب أعطالاً صامتة في الإنتاج.”

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

ما يجب أن يحويه CLAUDE.md عادةً: وصف موجز للمشروع وغرضه، مكدّس التقنيات مع سبب اختيار كل تقنية، أنماط البنية الحرجة (ماذا نفعل وماذا لا نفعل)، معايير الاختبار وقواعد تسمية الملفات، وأي قيود مهمة للنشر أو الأمان.

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

الطبقة الثانية: SPEC.md كعقد الميزة

لكل ميزة أو وحدة عمل كبيرة، تحتاج إلى ملف SPEC.md منفصل. هذه الطبقة تجيب عن سؤال محدد: “ما الذي يجب بناؤه ولماذا، دون الخوض في كيفية البناء؟”

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

SPEC.md الجيد يحتوي على خمسة أقسام:

السياق والدوافع: لماذا نبني هذا الآن؟ ما المشكلة التي يحلها؟ المستخدم والحالة الاستخدامية: من سيستخدم هذا وكيف؟ معايير النجاح: كيف نعرف أن الميزة اكتملت؟ تكون قابلة للقياس قدر الإمكان. ما هو خارج النطاق: ما الذي لن نبنيه الآن؟ هذا القسم يمنع الزحف التدريجي للنطاق. القيود والتبعيات: ما الذي يُحدد الحلول الممكنة؟

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

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

الطبقة الثالثة: plan.md كخريطة تنفيذ قابلة للتحقق

إذا كان CLAUDE.md هو “من نحن” وSPEC.md هو “ماذا نبني”، فـ plan.md هو “كيف نبنيه خطوة بخطوة.”

الفرق الجوهري بين plan.md الفعّال وقائمة المهام العادية هو قابلية التحقق. كل خطوة في plan.md يجب أن تكون مهمةً مستقلة يمكن إنجازها في دقيقتين إلى خمس دقائق، وتنتهي بحالة يمكن التحقق منها.

مثال على خطوة سيئة: “أضف ميزة المصادقة”

مثال على خطوة جيدة:

- [ ] أنشئ `src/lib/auth/tokens.ts` مع دوال `generateToken` و`verifyToken`
  - الاختبار: `bun test src/lib/auth/tokens.test.ts` يجتاز
  - لا يعتمد على قاعدة البيانات في هذه المرحلة

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

حين لا تُحدد المسار، يختار الوكيل موقعاً يبدو له منطقياً، والذي قد يتعارض مع بنية ملفاتك. حين لا تُوفر معيار اختبار، يعرف الوكيل أن المهمة “اكتملت” عند كتابة الكود، لا عند التحقق منه. حين لا تُوضح التبعيات، قد ينتهي بك الأمر بتنفيذ خطوات بترتيب خاطئ.

استخدام TDD في plan.md ليس مجرد ممارسة جيدة؛ إنه آلية تغذية راجعة. الوكيل يكتب الاختبار أولاً، وعندما يجتاز الاختبار، يكون هناك دليل موضوعي على اكتمال المهمة، لا تقييم ذاتي.

تقسيم الجلسات: متى تبدأ جلسة جديدة

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

القاعدة العملية التي أتبعها: عند إكمال وحدة عمل متماسكة يمكن تلخيصها في جملتين، ابدأ جلسة جديدة. قبل الإنهاء، اطلب من الوكيل كتابة ملخص “حالة الآن” في ملف مؤقت. هذا الملخص يصبح أول ما تُلصقه في الجلسة التالية.

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

نموذج النضج: أين أنت الآن

بعد تطبيق هذا النظام مع فرق مختلفة، لاحظتُ ثلاثة مستويات واضحة من النضج في استخدام وكلاء الذكاء الاصطناعي:

المستوى الأول: الفوضى المُنتجة التعليمات تُكتب لحظة الحاجة، السياق يعيش في رأس المطوّر، النتائج متفاوتة بشكل كبير بين الجلسات. يشعر المطوّر أن الأداة “تعمل أحياناً وتخذله في أحيان أخرى.”

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

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

الانتقال من المستوى الأول إلى الثاني يستغرق أياماً. الانتقال من الثاني إلى الثالث يستغرق أسابيع من التعوّد على الانضباط. لكن العائد من المستوى الثالث يتجاوز مجرد تحسين نتائج الوكيل: القاعدة الوثائقية التي تبنيها تصبح أصلاً حقيقياً للمشروع.

ابدأ اليوم بهذا

لا تنتظر حتى تُكمل قراءة كل ما كُتب عن هندسة السياق. الخطوة الأولى بسيطة:

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

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

الوكلاء لا يحتاجون تعليمات أفضل. يحتاجون سياقاً أفضل. والسياق الجيد لا يُكتب في لحظة، بل يُبنى بالتراكم.

---

مصادر ومراجع

• Anthropic. (2024). Claude Code documentation: CLAUDE.md context files. Anthropic Developer Docs.
• Liu, N. F., et al. (2023). Lost in the Middle: How Language Models Use Long Contexts. Transactions of the Association for Computational Linguistics, 12, 157-173. https://arxiv.org/abs/2307.03172
• Karpas, E., et al. (2022). MRKL Systems: A modular, neuro-symbolic architecture that combines large language models, external knowledge sources and discrete reasoning. arXiv preprint arXiv:2205.00445.
• OpenAI. (2024). Best practices for prompt engineering with OpenAI API. OpenAI Cookbook. https://platform.openai.com/docs/guides/prompt-engineering
• Khattab, O., et al. (2023). Demonstrate-Search-Predict: Composing retrieval and language models for knowledge-intensive NLP. arXiv preprint arXiv:2212.14024.