مش مقالة عن أداة. دي مقالة عن الانضباط نفسه: ليه الـ spec بيشتغل مع الـ AI agents، إمتى بيستاهل تعبه وإمتى بيبقى ضريبة، وإيه اللي الأبحاث الحقيقية (بأرقامها ومصادرها) بتقوله — بما فيها الدراستين اللي نتايجهم بتتناقض.

منهجية Spec-Driven Development — الانضباط اللي ورا الأدوات

ملاحظة قبل ما نبدأ: لو انت جاي تدوّر على أوامر specify والـ 9 مراحل والـ 66 أمر، دول عندنا في مقالة تانية: GitHub Spec Kit — الدليل الشامل و الشيت الكامل. المقالة دي حاجة تانية خالص — دي عن المنهجية نفسها: الفكرة اللي الأدوات دي كلها بتحاول تنفّذها، ليه بتشتغل، وإمتى بتفشل. الأدوات هتتغير خلال سنة. الفكرة لأ.

Section1. المشكلة اللي المنهجية دي بترد عليها

عنق الزجاجة هو القصد، مش الكود

خليني أوصف لك موقف انت عشته:

بتقول للـ agent: "اعملي endpoint للـ checkout." بيشتغل تلات دقايق. بيرجعلك بـ 14 ملف متغيّر، PaymentStrategy interface، و AbstractCheckoutFactory، و retry logic بـ exponential backoff، وكل ده... شغال. الكود نضيف. الـ tests بتعدّي.

بس انت كنت عايز endpoint واحد بسيط يخصم من الرصيد. مفيش payment gateway أصلاً في المشروع.

الـ agent مغلطش. هو اشتغل بالظبط زي ما اتقاله. المشكلة إن اللي اتقاله كان ناقص، وهو مليان الفراغات دي بأكتر احتمال إحصائي — مش بأكتر احتمال صح في السياق بتاعك.

دي مش مشكلة ذكاء. دي مشكلة قصد غير محدد (underspecification). والفرق بين الاتنين هو كل المقالة دي.

1.1 ليه الكود لوحده مش كفاية

الكود سجل ناقص للقصد

الكود بيسجّل إزاي. عمره ما بيسجّل ليه.

لما تفتح ملف بعد 6 شهور وتلاقي if (retries > 3) throw، الكود بيقولك إن في حد وقف عند 3. مبيقولكش إن ده كان بسبب rate limit في API خارجي اتشال من سنة، ولا إن ده كان رقم عشوائي حد كتبه وهو مستعجل.

من ساعة ما بقى فيه agents بتكتب كود أسرع مننا بكتير، السؤال ده بقى أخطر: الـ agent كمان بيقرأ الكود، وكمان مش عارف الـ "ليه". وعشان هو بيولّد أسرع، بيولّد افتراضات غلط أسرع.

الفكرة المركزية: الـ prompt بيتبخّر. الـ session بتخلص. الكود بيفضل — بس الكود مفيش فيه القصد. لازم يبقى في artifact تالت.

Section2. الأطروحة — افصل القصد عن التنفيذ

افصل القصد عن التنفيذ

Spec-Driven Development بيقول حاجة واحدة، وبسيطة لدرجة إنها بتضايق:

خلي القصد artifact حقيقي: مكتوب، مُراجَع، مُخزَّن مع الكود، وله نسخ.

كده والسلام. كل الباقي تفاصيل تنفيذ.

الـ artifact ده بيحتوي على:

الطبقة	بتجاوب على	بتعيش قد إيه
المبادئ (constitution / steering)	إيه القواعد اللي متتكسرش في المشروع ده؟	عمر المشروع
الـ Spec	إيه المشكلة؟ لمين؟ إيه اللي مش داخل؟	عمر الـ feature
الـ Plan	إزاي تقنياً؟ وإيه البدائل اللي رفضناها وليه؟	عمر الـ feature
الـ Tasks	خطوات محدودة يقدر حد ينفّذها ويتأكد منها	عمر الـ PR

ولاحظ نتيجة جانبية مهمة جداً: بوابة المراجعة بتتحرك لبدري. بدل ما تراجع PR بـ 2000 سطر وانت مش عارف الأصل كان إيه، بتراجع صفحة واحدة قبل ما يتكتب سطر. الخلاف بيحصل على الـ spec، مش على الـ diff.

Section3. النسب — الفكرة دي عمرها 40 سنة

نسب فكرة SDD: من Design by Contract و BDD لـ ADR و RFC

أول حاجة لازم تتقال بصراحة: مفيش حاجة جديدة هنا. اللي اتغير هو مين بيقرا.

الأصل	مين وإمتى	إيه اللي SDD خده منه
Design by Contract	Bertrand Meyer، لغة Eiffel، 1986	preconditions / postconditions / invariants كحدود منطقية بتقيّد التوليد
BDD & Gherkin	Dan North وبعده Cucumber	`GIVEN-WHEN-THEN` — معيار قبول قابل للتنفيذ، مش وصف إنشائي
Architecture Decision Records	Michael Nygard	سجل قرارات مع السياق والبدائل والعواقب — أصل الـ constitution
Consumer-Driven Contracts	عالم الـ microservices / API-first	اتفق على الـ interface قبل الـ business logic
Literate Programming	Donald Knuth	نص وكود في artifact واحد — و SDD بيقلبها: النص هو الأصل
RFC / Design Docs	ثقافة IETF وبعدها الشركات الكبيرة	مرحلة نقد بشري إجبارية قبل التنفيذ

الجديد الوحيد: قارئ المواصفة بقى ماكينة هتنفّذها فوراً. الـ design doc زمان كان بيتقري مرة وينسى. دلوقتي بيتحقن في الـ context window كل session.

ده اللي بيخلي النقد "ده waterfall من تاني" نقد جدّي ومستاهل إجابة حقيقية — وهنجاوب عليه في القسم 10.

Section4. الميكانيكا — ليه ده بيشتغل على الـ LLM بالتحديد؟

أرقام ورقة Carnegie Mellon عن القصد غير المحدد

هنا بقى الجزء اللي فيه أرقام حقيقية، مش كلام.

في ورقة بحثية من جامعة Carnegie Mellon اسمها "What Prompts Don't Say: Understanding and Managing Underspecification in LLM Prompts" (Yang وزملاؤه، arXiv:2505.13360، ونُشرت في Findings of ACL 2026). الورقة دي قاست بالظبط الحاجة اللي احنا بنتكلم عنها.

النتايج:

القياس	الرقم	يعني إيه بالبلدي
الـ LLM بيستنتج المتطلبات الناقصة صح	41.1% فقط	يعني في ~59% من الحالات، الفراغ اللي سبته اتملى غلط
ثبات الاستنتاج ده عبر تحديثات الموديل/الـ prompt	ضعف احتمال الانهيار	الـ prompt الناقص هش مرتين قد الكامل
حجم الانهيار لما بيحصل	أكتر من 20% انخفاض في الدقة	شغلك بيقع لوحده لما الموديل يتحدّث
لو حشرت كل المتطلبات في prompt طويل	حتى 19% انخفاض	الحل مش "اكتب أكتر"
اختيار المتطلبات بذكاء (Bayesian / TPE)	+4.8% دقة و 41–45% tokens أقل	الحل هو "اكتب الصح"

الرقمين الأخيرين دول أهم حاجة في الجدول، وأكتر حاجة الناس بتفهمها غلط:

الـ SDD مش "اكتب تفاصيل أكتر". الـ SDD هو "حدّد الحاجات اللي الاستنتاج فيها هيبقى غلط، وسيب الباقي."

لو انت بتحوّل الـ spec لـ dump لكل حاجة في دماغك، انت مش بتعمل SDD — انت بتخنق الموديل، والورقة بتقول إن ده بيوقّع الأداء 19%.

4.1 وليه القصد بيتآكل جوه الـ session

الـ prompts بتتبخّر والـ specs بتفضل

في 3 آليات بتشتغل مع بعض:

تآكل السياق — كل ما الـ session تطول، الـ token window بتمتلي بـ diffs و build errors ومحاولات وسط. الموديل بيبدأ يرمي القيود المعمارية اللي في الأول عشان يفضّي مكان.
تضخّم التجريد — لما مفيش scope مكتوب، الـ agent بيـ maximize الاكتمال: interfaces وfactories وطبقات مش محتاجينها (زي مثال الـ checkout فوق).
عدم تماثل تكلفة التراجع — الـ agent بيعدّل 30 ملف في دقيقة. انت بتحتاج ساعات عشان تفهم وتراجع وترجع الـ 30 ملف دول. السرعة في اتجاه واحد بس.

النقطة 3 دي هي كل الاقتصاد بتاع الموضوع، وهنبني عليها في القسم 7.

Section5. سلّم النضج — تصنيف Böckeler التلاتي

مستويات Böckeler التلاتة: spec-first و spec-anchored و spec-as-source

أفضل تصنيف اتكتب للموضوع ده مش بتاع شركة أداة — هو من Birgitta Böckeler من Thoughtworks، في مقالة "Understanding Spec-Driven-Development: Kiro, spec-kit, and Tessl" المنشورة في 15 أكتوبر 2025 ضمن سلسلة Exploring Gen AI على موقع Martin Fowler.

هي قسّمت الموضوع لتلات مستويات — والفرق بينهم مش في إنك بتكتب spec ولا لأ، لكن في قد إيه الـ spec عايش وقد إيه سلطته:

المستوى	التعريف (ترجمة)	الـ spec بيموت إمتى؟
Spec-first	spec مدروس بيتكتب الأول، وبيستخدم في الـ workflow للمهمة اللي في إيدك	بعد ما المهمة تخلص
Spec-anchored	الـ spec بيتحفظ بعد ما المهمة تخلص، وبيفضل يُستخدم في تطوير وصيانة الـ feature	مع الـ feature
Spec-as-source	الـ spec هو ملف المصدر الأساسي؛ الإنسان بيعدّل الـ spec بس، وعمره ما بيلمس الكود	مبيموتش — الكود هو اللي derivative

وهنا مفاجأة معظم الناس مش واخدة بالها منها: Kiro و spec-kit الاتنين في نفس المستوى — spec-first. مش واحد أعلى من التاني. Böckeler بتقول عن spec-kit بالنص إنه "لسه اللي أسمّيه spec-first بس، مش spec-anchored على المدى الطويل"، لأنهم بيشوفوا الـ spec كـ artifact حي لعمر الـ change request، مش لعمر الـ feature.

Tessl هي الوحيدة اللي بتطمح لـ spec-anchored وبتستكشف الـ spec-as-source.

الخلاصة العملية: لو مشروعك بيكتب spec وبيرميه بعد الـ merge — انت في المستوى الأول، وده مش عيب. ده المستوى المناسب لمعظم الشغل. المهم إنك تعرف انت فين وانت مختار، مش بالصدفة.

اختار الدرجة اللي تناسب حجم المخاطرة

Section6. تشريح spec كويس (من غير أي أداة)

تشريح spec: المشكلة والنطاق والـ non-goals ومعايير القبول والأسئلة المفتوحة

الـ spec الكويس مش طوله. الـ spec الكويس بيمنع سوء فهم محدد.

القسم	السؤال	فخ شائع
المشكلة	مين المتضرر دلوقتي وإزاي؟	تبدأ بالحل بدل المشكلة
النطاق	إيه اللي داخل؟	تسيبه مفتوح
اللي مش داخل (Non-goals)	إيه اللي احنا مش هنعمله دلوقتي؟	بيتنسي — وده أخطر قسم في الملف
معايير القبول	إزاي نعرف إن ده خلص؟	"يبقى سريع" / "يبقى نضيف" — كلام مش قابل للاختبار
الأسئلة المفتوحة	إيه اللي لسه مش عارفينه؟	تخمّن وتكتبه كأنه حقيقة

6.1 قسم الـ Non-goals بيشتغل أكتر من أي قسم تاني

قسم الـ Non-goals هو اللي بيشتغل أكتر من أي قسم تاني

فاكر مثال الـ checkout؟ سطر واحد كان كفاية:

text

Non-goals:
-مفيشpaymentgatewayintegrationفيالمرحلةدي
-مفيشretry/backoff—نداءواحد،وأيفشليترميللـcaller
-مفيشabstractionلأكترمنطريقةدفع

التلات سطور دول كانوا هيمنعوا 12 ملف من الـ 14.

ليه؟ لأن حسب ورقة CMU، الموديل بيملى الفراغ في 100% من الحالات، وبيصيب في 41.1% بس. الـ non-goal مش بيديله معلومة — بيقفل الفراغ خالص، فمفيش حاجة يستنتجها.

6.2 معايير قبول قابلة للاختبار

❌ مش قابل للاختبار	✅ قابل للاختبار
الـ API يبقى سريع	p95 latency < 200ms عند 100 rps
معالجة أخطاء كويسة	أي input غير صالح يرجّع 400 بـ `{code, message}` ومفيش 5xx
الكود يبقى نضيف	مفيش ملف يعدّي 300 سطر؛ مفيش دالة تعدّي 3 مستويات تداخل

الفرق مش أسلوبي. الأول الـ agent بيقيّم نفسه بيه غلط، والتاني بيتحوّل لـ test.

Section7. الاقتصاد — إمتى يستاهل وإمتى يبقى ضريبة

اقتصاد SDD: تكلفة ثابتة قدام تكلفة بتكبر مع الوقت

دي أهم فقرة في المقالة، وأكتر واحدة الناس بتتخطاها.

القاعدة: تكلفة كتابة الـ spec ثابتة تقريباً. تكلفة التراجع عن غلطة بتكبر مع نطاق الانفجار.

يعني في نقطة تقاطع. تحتها الـ spec خسارة، فوقها ربح.

الحالة	الحكم	السبب
إصلاح typo / تعديل CSS	❌ خسارة صافية	تكلفة الغلط 10 ثواني
spike استكشافي	❌ خسارة	انت مش قادر تحدد حاجة لسه مستكشفتهاش
مشكلة لسه مش فاهمها	❌ خسارة	الـ spec هيقفل احتمالات محتاج تفتحها
feature في نظام إنتاج بيمسّه فريق	✅ ربح كبير	التراجع بيكلّف أيام
تغيير بيمسّ contract بين خدمتين	✅ ربح كبير	الغلط بيوصل لفرق تانية
شغل تحت تنظيم/امتثال	✅ إجباري	القصد المكتوب هو الدليل
شغل الـ agent هيمسّ أكتر من ~5 ملفات	✅ ربح	ده بالظبط عدم تماثل التكلفة

قاعدة الإبهام: لو تكلفة اكتشاف وتصحيح الغلط أقل من تكلفة كتابة الـ spec — متكتبش spec. ده مش كسل، ده هندسة.

وخد بالك من الفخ ده تحديداً: الاستكشاف. في ناس بتحاول تكتب spec لحاجة لسه مش فاهماها، والنتيجة spec مليان تخمين، والـ agent بيبني على التخمين ده بثقة. استكشف الأول بـ vibe coding، وبعدين اكتب spec لما تفهم. الترتيب ده مش اختياري.

Section8. الدليل الرقمي — ودراستين نتايجهم بتتناقض

دراستين نتايجهم بتتناقض حوالين ملفات السياق

هنا الجزء اللي هيفرّقنا عن أي مقالة تانية عن SDD: البيانات مش متفقة، ولازم نقول كده.

خلينا ناخد أبسط شكل للـ SDD وأكتر واحد منتشر: ملف سياق في جذر المشروع — AGENTS.md أو CLAUDE.md.

8.1 الدراسة الأولى: الملف بيوفّر وقت وفلوس

Lulla وزملاؤه، "On the Impact of AGENTS.md Files on the Efficiency of AI Coding Agents" (arXiv:2601.20404، يناير 2026).

المنهج: OpenAI Codex على 10 مستودعات و124 pull request حقيقي، كل مهمة اتنفّذت مرتين — مرة والملف موجود ومرة وهو متشال.

القياس	من غير الملف	مع الملف	الفرق
زمن التنفيذ (وسيط)	98.57 ثانية	70.34 ثانية	−28.64%
الـ output tokens (وسيط)	2,925	2,440	−16.58%

السبب اللي الباحثين قالوه: الملف بيمنع الـ agent من إنه يلف على المشروع بالعمى — مبيقراش ملفات على أمل، ومبيجربش أوامر build غلط. بيروح على الصح من أول مرة.

⚠️ تنبيه أمانة: الورقة دي مقاستش صحة الكود خالص. الباحثين قالوا حرفياً إن تقييم الصحة "خارج نطاق الورقة"، واكتفوا بفحص يدوي لـ 50 مهمة عشان يتأكدوا إن في تعديلات حقيقية. فأي حد يقولك "الدراسة أثبتت إن معدل النجاح فضل زي ما هو" — ده مش موجود في الورقة.

8.2 الدراسة التانية: الملف بيغلّي التكلفة والفايدة هامشية

Gloaguen وزملاؤه من ETH Zurich، "Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?" (arXiv:2602.11988، فبراير 2026 — في ورشة MemAgents التابعة لـ ICLR 2026، مش المؤتمر الرئيسي).

المنهج: benchmark جديد اسمه AGENTbench — 138 مهمة Python حقيقية من 12 مستودع، بالإضافة لـ SWE-bench Lite.

القياس	النتيجة
تكلفة الاستدلال مع وجود ملف السياق	+20% (SWE-bench Lite) / +23% (AGENTbench)
تحسّن معدل النجاح بملفات مكتوبة ببني آدم	+4% فقط
ملفات مولّدة بالـ LLM	−3% — يعني بتضرّ

8.3 إزاي التنين صح في نفس الوقت؟

التفسير موجود في تحليل الـ traces بتاع دراسة ETH نفسها، وهو ألطف حاجة في الموضوع كله:

الـ agents بتطيع ملفات السياق.

يعني لما تكتب "شغّل الـ tests بعد أي تعديل" و"عدّي الـ linter"، هو بيعملها. فبيعمل خطوات أكتر، وبيستكشف أعمق، وبيفكر خطوة بخطوة أكتر. النتيجة:

✅ جودة وانضباط أعلى في الشغل
❌ tokens أكتر
❌ والـ benchmark مش شايف الفرق، لأنه بيقيس نجح/مانجحش (binary) — مش بيقيس "هل الكود ماشي مع أسلوب المشروع" ولا "هل عدّى الـ linter"

يعني الدراستين مش بيتناقضوا. الأولى قاست الكفاءة (وقت و tokens للوصول). التانية قاست معدل النجاح على مقياس مبيشوفش الجودة أصلاً.

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

Section9. روائح الإعدادات — 91% من الملفات فيها مشكلة

روائح الإعدادات: 91% من ملفات السياق فيها مشكلة

طب لو ملف السياق ده مهم، الناس بتكتبه إزاي؟

دراسة من جامعة Minas Gerais الفيدرالية (UFMG) في البرازيل — "Configuration Smells in AGENTS.md Files" (arXiv:2606.15828، يونيو 2026) — فحصت 100 مستودع من الأعلى نجوماً (39 ملف AGENTS.md و 61 ملف CLAUDE.md).

النتيجة: 91% من الملفات فيها رائحة إعداد واحدة على الأقل.

الرائحة	الانتشار	إيه هي
Lint Leakage	62%	تكتب قواعد الـ formatting والـ imports اللي الـ linter أصلاً بيفرضها — حشو بيستهلك context
Context Bloat	42%	ملف طويل أوي، فالموديل بيبدأ يهمل التعليمات المهمة
Skill Leakage	35%	تحقن workflow نادر (زي migration أو deployment) في كل session
Conflicting Instructions	28%	تقول `pnpm` في سطر و `npm` في سطر تاني — والموديل بيلخبط
Init Fossilization	24%	ملف اتولّد أول يوم ومحدش لمسه تاني
Blind Reference	16%	تشاور على ملف مش موجود أو مش هيتقرا

خد بالك من Lint Leakage بالذات: 62% — دي أكتر واحدة، وأسهل واحدة تتصلّح. أي قاعدة الـ tooling بتاعك بيفرضها، شيلها من الملف. مكانها الـ CI، مش الـ prompt.

9.1 نموذج السياق الطبقي

الحل مش "اكتب ملف أحسن". الحل إنك تقسّمه على 3 طبقات:

الطبقة	فين	بتتحمّل إمتى	تحط فيها إيه
عام	`AGENTS.md` / `CLAUDE.md` في الجذر	كل session	الاتفاقيات الثابتة اللي متتغيرش + الحاجات الممنوعة
مرتبط بمسار	ملف في المجلد نفسه	لما الـ agent يدخل المجلد ده	قواعد الـ package/الطبقة دي بس
عند الطلب	Skills / templates	لما تتطلب المهمة دي	migration، release، إجراءات نادرة

عن الحجم: Anthropic بتوصي رسمياً بإن CLAUDE.md يفضل تحت 200 سطر، بالنص: "الملفات الأطول بتستهلك context أكتر وبتقلّل الالتزام." دي توصية مش سقف — الملف بيتحمّل كامل مهما طال. أما Codex فعنده سقف فعلي: project_doc_max_bytes بـ 32 KiB افتراضياً، وده على مجموع ملفات التعليمات كلها، وقابل للتغيير، وبيقطع الزيادة من غير ما يحذّرك.

9.2 وقاعدة أهم من كل ده: حوّل الكلام لـ hooks

الجملة دي في ملف السياق:

text

دايماً شغّل الـ tests و الـ linter قبل الـ commit

الموديل بينفّذها احتمالياً. يعني أحياناً.

نفس القاعدة كـ hook بيتنفّذ بعد كل تعديل ملف: بتتنفّذ 100%، وبتوفّر tokens، ومش بتعتمد على مزاج الموديل.

القاعدة: أي حاجة تقدر تتحوّل لـ hook أو CI check — متكتبهاش في ملف السياق. ملف السياق للحاجات اللي مينفعش تتأتمت.

Section10. أنماط فشل المنهجية نفسها

المنهجية نفسها ممكن تفشل

أي حد بيبيعلك منهجية من غير ما يقولك بتفشل إمتى، بيبيعلك حاجة تانية.

10.1 "ده waterfall بس الـ AI هو اللي بيكتب"

ده أشهر نقد، وهو نقد محترم. الحجة: إنك تكتب تصميم كامل قبل أي كود بيكرّر غلطة الـ waterfall الأصلية — بتاخد أكبر التزام معماري في اللحظة اللي انت فيها أقل واحد عارف.

الرد الأمين: الحجة دي بتقع لو الـ batch كبير، وبتقف لو صغير.

الفرق مش في وجود الـ spec، الفرق في حجم الشريحة. spec لـ feature واحدة أفقها ساعات = حلقة تغذية راجعة. spec لربع سنة كامل = waterfall بحق وحقيق. لو الـ spec بتاعك مبيتغيّرش أثناء التنفيذ، ده مش دليل إنه كان كويس — ده غالباً دليل إن محدش بيقراه.

10.2 Spec Rot — وده أخطرهم

بوابة المراجعة: عدّل الـ spec في نفس الـ pull request

الكود بيتغيّر تحت ضغط production، والـ spec مبيتغيّرش. بعد شهرين الـ spec بقى كذب موثّق، والـ agent بيبني على الكذب ده.

العلاج الوحيد اللي بيشتغل: تعديل الـ spec في نفس الـ PR بتاع الكود. مش تاسك تاني، مش "هنحدّثه بعدين". نفس الـ PR أو مفيش.

وتقدر تفرضها ميكانيكياً:

CI gate يمنع الـ spec rot

➜ ~ git diff --name-only origin/main...HEAD

src/checkout/handler.ts

src/checkout/validate.ts

⠋ Checking for matching spec update...

✗ specs/checkout.md unchanged while src/checkout/** modified

✗ CI FAILED — update the spec in this PR or add [no-spec] with a reason

➜ ~⏎ نفّذ · ⌫ امسح

10.3 الباقي

النمط	العلامة إنك واقع فيه	العلاج
Spec Theater	الـ specs كلها بتتوافق عليها من غير أي تعليق	راجع الـ spec زي ما بتراجع كود — لو مفيش أسئلة، محدش قرا
الإفراط في التحديد	بتكتب أسماء الدوال والـ classes في الـ spec	الـ spec بيقول إيه، الـ plan بيقول إزاي — متخلطش
إرهاق المراجعة	بوابة اتحركت لبدري بس نفس الشخص بيراجع الاتنين	البوابة المبكرة بتنفع لو حد فعلاً بيقرا
الثقة الزايفة	spec مفصّل جداً و... غلط	الـ spec المفصّل الغلط أخطر من مفيش spec — لأنه بيقنع الـ agent والمراجع

Section11. SDD من غير أي أداة — ابدأ النهاردة

تقدر تبدأ النهاردة بـ Markdown بس

مش محتاج تنزّل حاجة. أقل نسخة شغّالة:

أقل هيكل SDD ممكن

➜ ~ mkdir -p specs docs/adr

➜ ~ touch AGENTS.md

➜ ~ tree -L 2

├── AGENTS.md # المبادئ + الممنوعات (تحت 200 سطر)

├── specs/

│ └── checkout.md # spec لكل feature

├── docs/adr/

│ └── 0001-why-no-payment-gateway.md

└── src/

✓ خلاص. دي كل الأدوات اللي محتاجها.

➜ ~⏎ نفّذ · ⌫ امسح

وقواعد التشغيل:

AGENTS.md = المبادئ + الممنوعات. تحت 200 سطر. مفيش قواعد الـ linter فيه.
specs/<feature>.md = المشكلة، النطاق، الـ non-goals، معايير القبول، الأسئلة المفتوحة.
docs/adr/ = القرارات اللي هتنساها. السياق والبدائل والعواقب.
الـ PR بيشاور على الـ spec، وبيعدّله في نفس الـ PR.
أي قاعدة قابلة للأتمتة → hook أو CI، مش نص.

الأدوات بتديك سقالات وانضباط مراحل وتكامل مع الـ agent. مبتديكش الفكرة — الفكرة دي فوق.

Section12. مشهد الأدوات في منتصف 2026 (بإيجاز مقصود)

الأداة	الشكل	ملف السياق	صيغة المتطلبات	المستوى (Böckeler)
GitHub Spec Kit	CLI مفتوح المصدر (`specify`) + أوامر `/speckit.*`	`constitution.md`	قوالب `spec.md` / `plan.md` / `tasks.md`	Spec-first
AWS Kiro	IDE مبني على Code OSS + CLI + web (preview)	`.kiro/steering/` → `product.md`, `tech.md`, `structure.md`	EARS: `WHEN … THEN … SHALL …`	Spec-first
Tessl	إطار + registry (beta مغلقة)	إعدادات `.tessl/`	`.spec.md` بربط 1:1 مع ملف الكود	يطمح لـ Spec-anchored

تلات تصحيحات مهمة تلاقيها غلط في 90% من المقالات:

Kiro بيستخدم EARS مش Gherkin. الصيغتين مختلفتين. EARS هي WHEN [حدث] THEN [النظام] SHALL [استجابة]، وفيها كمان IF/THEN و WHILE و WHERE. Gherkin هي Given/When/Then وحاجة تانية خالص.
أوامر Spec Kit كلها بقت بـ namespace /speckit. — يعني /speckit.specify مش /specify. والتثبيت الرسمي uv tool install specify-cli. و**npx github-spec-kit init أمر غير موجود أصلاً** (مفيش package بالاسم ده على npm).
Tessl اتحوّلت. الإطار اللي نزل في سبتمبر 2025 بفكرة spec-as-source لسه في beta مغلقة، والموقع دلوقتي بقى "منصة تمكين وكلاء" بتبيع مهارات (skills) — وصفحات الوثائق القديمة بترجّع 404. فأي كلام عن spec-as-source بتاع Tessl لازم يتكتب بتاريخه.

Section13. طب أقيس إيه؟

لو مش بتقيسها، تبقى مجرد طقوس

لو مش بتقيس، انت بتعمل طقوس مش هندسة.

المؤشر	ليه	إشارة الخطر
معدل إعادة الشغل	الغرض الأساسي من SDD	مبيقلّش بعد 3 شهور → الـ specs مش بتتقري
عدد تعديلات الـ spec بعد بدء التنفيذ	صحة الحلقة	صفر = spec theater، عالي جداً = بتكتب spec بدري أوي
حجم الـ PR	التقطيع شغال؟	بيكبر → الـ tasks مش متقطّعة كويس
الأخطاء الهاربة للإنتاج	جودة معايير القبول	ثابت → المعايير مش قابلة للاختبار فعلاً
من الـ spec للـ merge	تكلفة الطقوس	بيطول من غير ما الجودة تتحسّن → المنهجية أتقل من اللازم

المؤشر التاني هو المفضّل عندي: لو الـ spec بتاعك عمره ما بيتعدّل أثناء التنفيذ، مفيش حد بيقراه.

Section14. الخلاصة — الفكرة اللي هتفضل

القصد يستاهل يبقى artifact

خلينا نكون صرحاء عن حالة الأدلة:

✅ متأكدين: الغموض بيخلّي سلوك الموديل هش — 41.1% استنتاج صحيح، وضعف احتمال الانهيار عند أي تحديث (CMU).
✅ متأكدين: ملف السياق بيقلّل الوقت والـ tokens بشكل معتبر (28.64% و16.58% — Lulla).
⚠️ مش متأكدين: إن ده بيترجم لمعدل نجاح أعلى — دراسة ETH لقت +4% بس مع +20% تكلفة.
⚠️ حذار: أرقام الإنتاجية الشهيرة أضعف مما بتتنقل. رقم الـ 55% أسرع بتاع Copilot كان من تجربة سنة 2022 على مهمة واحدة لعبة (HTTP server بـ JavaScript) و70 مطور خلّصوا، بفاصل ثقة واسع جداً [21%, 89%]. ورقم الـ 19% أبطأ بتاع METR (2025، 16 مطور، 246 مهمة) هو نفسه اتراجع في تحديث فبراير 2026 لدرجة إن METR وصفته بإنه "دليل ضعيف جداً".

يعني إيه ده كله؟

يعني متبعش SDD كوعد بإنتاجية. بيعه كوعد بـ تحكّم.

الحاجة الوحيدة اللي كل الأدلة متفقة عليها إن الـ spec بيقلّل التباين: الشغل بيبقى متوقّع أكتر، والـ agent بيلتزم بالحدود أكتر، والمراجعة بتحصل قبل ما التكلفة تكبر.

والفكرة اللي هتفضل بعد ما Spec Kit و Kiro و Tessl يتغيّروا أو يموتوا:

القصد يستاهل يكون artifact.

ومحدش يقدر ينفّذ حاجة كويس — لا junior، ولا contractor، ولا موديل — من غير ما حد يكتب الأول يعني إيه "صح".

Sectionالمصادر

كل رقم في المقالة دي اتراجع على مصدره الأصلي:

Böckeler, B. — Understanding Spec-Driven-Development: Kiro, spec-kit, and Tessl (martinfowler.com، 15 أكتوبر 2025) — تصنيف المستويات التلاتة
Yang, C. وآخرون (CMU) — What Prompts Don't Say — arXiv:2505.13360 / Findings of ACL 2026
Lulla, J. وآخرون — On the Impact of AGENTS.md Files on the Efficiency of AI Coding Agents — arXiv:2601.20404
Gloaguen, T. وآخرون (ETH Zurich) — Evaluating AGENTS.md — arXiv:2602.11988 (ورشة MemAgents @ ICLR 2026)
dos Santos وآخرون (UFMG) — Configuration Smells in AGENTS.md Files — arXiv:2606.15828
Becker, J.، Rush, N.، Barnes, B.، Rein, D. (METR) — arXiv:2507.09089، وتحديث 24 فبراير 2026
Peng, S.، Kalliamvakou, E.، Cihon, P.، Demirer, M. — The Impact of AI on Developer Productivity — arXiv:2302.06590
Piskala, D. B. — Spec-Driven Development: From Code to Contract — arXiv:2602.00180
ContextBench (Nanjing University + UCL) و SWE-ContextBench — arXiv:2602.08316
AGENTS.md — agents.md، والإعلان عن Agentic AI Foundation (Linux Foundation، 9 ديسمبر 2025)

منهجية Spec-Driven Development — الانضباط اللي ورا الأدوات، بالأرقام