التطوير بالمواصفات: دورة مكثفة

13 مفهوماً · اتفق على ماذا قبل أن تولّد كيف

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

لهذه الحلقة اسم: vibe coding. تعطي الذكاء الاصطناعي فكرة ضبابية، وتأمل أن يخمّن بشكل صحيح. هذا مقبول لنموذج أولي سترميه. أما أي شيء تنوي الاحتفاظ به، أو نشره، أو تسليمه لشخص آخر، فهو فخ.

التطوير بالمواصفات (SDD) هو المخرج. بدلاً من وصف ما تريده ثم الأمل، أنت تكتبه بوضوح كافٍ كي تتفق أنت والذكاء الاصطناعي قبل وجود أي كود. ذلك الاتفاق المكتوب هو المواصفة. يصبح الكود ما تنتجه المواصفة، لا العكس.

تغطي هذه الدورة الانضباط من البداية إلى النهاية. عند نهايتها تستطيع تشغيل بناء كامل بالمواصفات بنفسك، بثلاث طرق: في claude.ai، وهو تطبيق الويب وأداتك الأساسية هنا، وفي Claude Code، وفي OpenCode. الانضباط نفسه ينتقل إلى الثلاثة.

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

هذا هو فعلاً شكل البرمجة الوكيلة عملياً

لا تحتاج إلى قبول ذلك بالإيمان. وجد تحليل Anthropic لعام 2026 لحوالي 400,000 جلسة برمجة وكيلة تقسيماً واضحاً للعمل: البشر يتخذون معظم قرارات التخطيط، أي ماذا نبني، والوكيل يتخذ معظم قرارات التنفيذ، أي كيف نبنيه. وأقوى مؤشر على نجاح الجلسة لم يكن مهارة البرمجة؛ بل كان خبرة المجال: مدى دقة الشخص في تأطير العمل، وما الذي طلب من الوكيل التحقق منه، وهل استطاع إعادته إلى المسار عندما انحرف. SDD هو الانضباط الذي يجعلك جيداً في النصف الذي يبقى لك. راجع تحليل Anthropic: Agentic coding and persistent returns to expertise.

تقسيم ماذا/كيف، مقيساً على نحو 400,000 جلسة (Anthropic، 2026). SDD هو كيف تصبح جيداً في نصف التخطيط.

المتطلب السابق: AI Prompting in 2026

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

لا تحتاج إلى أن تكون مبرمجاً لهذا​

SDD هو انضباط تفكير، لا مهارة برمجة. تمارسه تقريباً كله بلغة عادية داخل نافذة محادثة عادية. المخرج وثيقة مكتوبة بوضوح، ثم نتيجة عاملة مبنية منها: تطبيق، سكربت، مولّد تقارير، أو أتمتة. إن كنت تستطيع كتابة brief واضح لزميل قادر، تستطيع كتابة مواصفة. (راجع Code You Never Write لترى لماذا صارت هذه مهارة عامة، لا مهارة مطور فقط.)

تجعل الدراسة هذا ملموساً: خلفية البرمجة بالكاد غيّرت نجاح الجلسة؛ خبرة المجال فعلت ذلك. لا يُطلب منك أن تكتب الكود؛ يُطلب منك أن تعرف مشكلتك بما يكفي لتكتبها: القواعد، الحالات الطرفية، وما معنى "done". المواصفة هي المكان الذي تضع فيه خبرتك. محاسب يستطيع ذكر كل قاعدة مطابقة سيتفوّق في البناء على مطور لا يفهم الدفاتر، لأن المواصفة تحمل المعرفة والوكيل يمدّ بالكود.

---

ثلاث أدوات، وانضباط واحد​

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

	claude.ai (الأساسي)	Claude Code	OpenCode
ما هو	تطبيق محادثة على الويب/سطح المكتب	وكيل البرمجة من Anthropic (طرفية/IDE)	وكيل برمجة مفتوح المصدر، أي نموذج
أين تعيش المواصفة	Artifact (وثيقة قابلة للتحرير بجانب المحادثة) داخل Project (مساحة عمل محفوظة)	ملفات في المستودع (CLAUDE.md, specs/)	ملفات في المستودع (AGENTS.md, specs/)
الأفضل ل	التفكير، الصياغة، غير المبرمجين، البداية	بناء software حقيقي من البداية للنهاية	الأمر نفسه، مع اختيار النموذج وضبط التكلفة
بدائل	ChatGPT (Projects + Canvas) وGemini (Gems + Canvas) يشغّلان الانضباط نفسه	(لا شيء)	(لا شيء)

ما الذي تغطيه هذه الدورة​

الجزء	الموضوع	ما الذي تتعلمه
1	التحول	لماذا يفشل vibe coding، وما هي المواصفة فعلاً، والمستويات الثلاثة ل SDD
2	الطريقة	الدستور، ثم المراحل الأربع: Research → Specify → Clarify → Build
3	الطرق الثلاث	تشغيل الحلقة في claude.ai وClaude Code وOpenCode
4	مثال كامل worked example	feature واحد، من البداية إلى النهاية، في claude.ai ثم في Claude Code
5	الحكم العملي	متى يستحق SDD وقته، ومتى يكون مبالغة، وكيف تُبقي المواصفة حية

العمود الفقري في 15 دقيقة، إن لم يكن لديك إلا دقائق

هل أنت جديد ومضغوط الوقت؟ اقرأ Concept 1 (لماذا يفشل vibe coding)، وConcept 2 (المواصفة هي المنتج)، وConcept 7 (Clarify by interview)، وكتلة prompts الأربع في نهاية Part 2، وworked example في Part 4. هذه هي القراءة الدنيا القابلة للحياة؛ كل شيء آخر يعمّقها لاحقاً. عندما تريد أن يصبح الانضباط ملكك فعلاً، فإن سلم Practice في النهاية هو المكان الذي تشغّل فيه الحلقة كاملة على شيء حقيقي. (هذا التقسيم نفسه حركة SDD: العمود الفقري هو المواصفة، والباقي هو الخطة.)

---

Part 1: The Shift​

ثلاث أفكار تعيد تشكيل طريقة عملك مع الذكاء الاصطناعي. إن فهمتها، فالباقي mechanics.

1. Vibe coding vs. spec-driven development​

الفرق هو متى تفكر.

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

في التطوير بالمواصفات، تفكر أولاً وتكتب ذلك. لا يبدأ الذكاء الاصطناعي بالبناء حتى تتفقا على معنى "done". بعدها يصبح البناء في معظمه ميكانيكياً: تنفيذ اتفاق، لا تخمين اتفاق.

حلقتان: vibe coding يدور بين prompt وcode و"not quite"؛ أما SDD فيقدّم المواصفة أولاً، ثم يشغّل حلقة build-and-check قصيرة عليها.

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

قاعدة عملية: إذا كان رمي النتيجة سيزعجك، فقد تجاوزت النقطة التي يكون فيها vibe coding آمناً. اكتب المواصفة.

2. The spec is the product; code is a build output​

هذه هي القلْبة الذهنية التي تعطي SDD اسمه. لعقود، كانت المواصفة تخدم الكود: تكتب brief، تبني الشيء، ثم ترمي brief. يعكس SDD ذلك. المواصفة هي الأثر الدائم الذي تحافظ عليه؛ والكود يتولّد منها، ويعاد توليده عندما تتغير المواصفة. "يعاد توليده" لا يعني ضغط زر compile سحري؛ بل يعني إعادة تشغيل حلقة البناء على المواصفة المحدّثة ومراجعة النتيجة: المواصفة ترشد وكيلاً غير كامل ما زلت تشرف عليه.

الانقلاب: الطريقة القديمة تعامل المواصفة كسقالات للكود؛ أما SDD فيجعل المواصفة مصدر الحقيقة، والكود ناتجاً يمكن اشتقاقه من جديد.

تجيب المواصفة الجيدة عن ثلاثة أسئلة، بالترتيب:

1. لماذا: ما المشكلة التي نحلها، ولمن؟ (الشيء الذي لا تذكره معظم جلسات vibe أصلاً.)
2. ماذا: ما الذي يجب أن يكون صحيحاً عند الانتهاء؟ السلوكيات، المدخلات، المخرجات، القواعد، الحالات الطرفية، وبوضوح ما هو خارج النطاق.
3. ما الذي لا نبنيه: الحدود. هذا القسم الواحد يمنع معظم إخفاقات "فعل أكثر مما ينبغي / فعل الشيء الخطأ".

لاحظ ما هو غائب: كيف. المواصفة تصف السلوك، لا التنفيذ. "يمكن للمستخدمين إعادة ضبط كلمة مرور منسية عبر رابط بريد ينتهي بعد 30 دقيقة" مواصفة. أما "استخدم JWT وجدول tokens في Postgres" فهو تنفيذ، وينتمي إلى الخطة، وهي مرحلة لاحقة. خلط الاثنين مبكراً هو أكثر خطأ شائع عند المبتدئين: تثبّت خياراً تقنياً قبل الاتفاق على السلوك الذي يفترض أن يقدمه.

اختبار كل سطر في المواصفة

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

3. The three levels of SDD​

SDD ليس كل شيء أو لا شيء. هناك ثلاثة مستويات، وتختار بينها حسب أهمية العمل.

المستوى	ما يعنيه	متى تستخدمه
Spec-First	اكتب المواصفة مرة واحدة في البداية، ثم ابنِ منها. قد تنحرف المواصفة لاحقاً.	معظم الميزات. هذا هو الافتراضي.
Spec-Anchored	تبقى المواصفة مصدر الحقيقة؛ تحدّثها كلما تغيّر السلوك، وتعيد الاشتقاق منها.	أي شيء ستصونه لأشهر.
Spec-as-Source	المواصفة هي المصدر؛ الكود يعاد توليده بالكامل منها، ويعامل كناتج يمكن اشتقاقه، لكنك ما زلت تعيد تشغيله وتراجعه.	فرق وأدوات ناضجة عالية الانضباط.

في هذه الدورة، ابدأ من Spec-First ثم انمُ نحو Spec-Anchored. Spec-as-Source هو الاتجاه الذي يسير إليه المجال، لكنك تستحقه بإتقان الأولين. الانضباط واحد في كل مستوى؛ الذي يتغير فقط هو مدى صرامتك في إبقاء المواصفة متزامنة.

---

Part 2: The Method​

لل workflow أساس واحد، وهو constitution، وأربع مراحل: Research → Specify → Clarify → Build:

الطريقة في نظرة واحدة: constitution فوق أربع مراحل (Research وSpecify وClarify وBuild)، وأي gap يظهر أثناء البناء يعيدك أولاً إلى إصلاح المواصفة.

4. The constitution: the rules above every spec​

قبل أي feature واحدة، تكتب وثيقة قصيرة لقواعد مستمرة تخص كل الميزات: constitution. في coding agents هي ملف القواعد (CLAUDE.md / AGENTS.md)؛ وفي claude.ai هي Project instructions. الفكرة نفسها في كل مكان: المبادئ والقيود والاتفاقات التي تريد من كل مواصفة وكل build أن يتبعها.

هناك caveat صريح لأنه يغيّر طريقة الاستخدام: constitution هو persistent context، لا قانون enforced. يحمّله الوكيل في كل session ويتبعه بثبات أكبر كلما كان محدداً ومختصراً، لكن "loaded" لا تعني "guaranteed". القواعد التي يجب ألا تُكسر أبداً، مثل عدم لمس production data أو عدم commit secrets، لا تعتمد فيها على القاعدة المكتوبة وحدها؛ ادعمها ب tests أو pre-commit أو tool hooks أو CI checks أو permissions أضيق أو review بشري لل diff. constitution يحدد intent؛ هذه الآليات تفرضه.

constitution هو principles، لا encyclopedia. يجيب عن "ما الصحيح دائماً هنا؟" لا "كيف تعمل feature X؟" اجعله محكماً؛ فالذكاء الاصطناعي يعيد قراءته باستمرار، والحشو مكلف ويدفن القواعد المهمة. تبدو أسطر constitution الجيدة هكذا:

# Constitution — Smart Notes

## Principles

- Plain language over cleverness. A new contributor should understand any file in 5 minutes.
- Prefer well-established libraries over custom code. Research before reinventing.
- Every feature ships with its spec in `specs/`. The spec is the source of truth.

## Constraints

- Stack: keep it to what's already here. Propose, don't add, new dependencies.
- Never touch `published/` or anything in `src/generated/`.

## Definition of done

- Behaviour matches the spec, edge cases included.
- A human has reviewed the diff against the spec before merge.

constitution شديد الصرامة يلوّث كل ما يأتي بعده

constitution يحدد نبرة كل شيء بعده: إذا طلب enterprise-grade testing وperformance budgets وprocess ثقيل لمشروع weekend، فكل مرحلة لاحقة ترث ذلك الوزن ويتحوّل تطبيق todo إلى كاتدرائية. طابق constitution مع stakes؛ تستطيع رفع السقف لاحقاً.

يمكنك مشاهدة ذلك يحدث. أعطِ weekend habit-tracker دستوراً يطلب 90% test coverage وperformance budget وdecision record مكتوباً لكل change، وستأتي أول feature ومعها benchmark harness وثلاث طبقات abstraction وdecision log: أسبوع process لزر يضيف صفاً إلى list. لم يطلب أحد ذلك؛ constitution طلبه، وكل phase بعده ورث الوزن.

والفشل العكسي شائع أيضاً: constitution غامض لدرجة أنه لا يقول شيئاً. ثلاث نسخ من المشروع نفسه:

خفيف جداً (بلا فائدة)	صارم جداً (خانق)	مناسب
"Write clean code. Be consistent. Use best practices."	12 قاعدة عن test coverage % وperformance budgets وcommit-message format وreview steps، كلها لتطبيق weekend app	الأسطر 6–8 أعلاه: مبادئ لا يستطيع AI استنتاجها، قيود تؤثر فعلاً، وتعريف واحد واضح ل "done"

اختبار كل قاعدة هو نفسه اختبار كل سطر في المواصفة: هل حذفها سيسمح ل AI بأن يخطئ؟ "Write clean code" تفشل، لأن AI يحاول ذلك أصلاً، فلا تضيف شيئاً. "Never touch published/" تنجح، لأنه لا توجد طريقة ليعرف AI ذلك وحده.

5. Phase 1: Research before you write​

لا تستطيع أن تكتب مواصفة لما لا تفهمه. قبل كتابة أي سطر في المواصفة، اجعل AI يرسم الخريطة: المشكلة، المستخدمون، القيود، و(في مشروع موجود) كيف يعمل الكود الحالي وأين يجب أن يدخل الشيء الجديد.

الحركة القوية هنا هي parallel research: بدلاً من حوار طويل واحد، اجعل AI يحقق في عدة أسئلة مرة واحدة ويعود بتقرير. في chat تطلب findings document منظماً؛ وفي coding agents تفعل ذلك حرفياً عبر subagents، كل واحد يبحث في مساحة سياقه الخاصة ويعيد summary فقط، فيبقى main conversation نظيفاً، وفق context discipline من Agentic Coding Crash Course.

المخرج ليس كوداً وليس مواصفة بعد. إنه findings document قصير: ما الموجود، الخيارات، المجهولات، وهو يغذي المواصفة. Prompt يعمل في الأدوات الثلاث:

Research what's involved in building [feature]. Investigate these separately and report each on its own: (1) how this kind of thing is usually done, (2) the main approaches and their trade-offs, (3) anything in our existing project it has to fit, (4) the failure modes and edge cases I should worry about. Give me a one-page findings doc: what exists, the options, and what's still unknown. Don't propose a final design or write any code yet.

6. Phase 2: Write the spec (the what and why, never the how)​

اكتب الآن المواصفة، مستنداً إلى research. لا تبدأ من صفحة فارغة: اكتب draft مع AI، ثم اجعله دقيقاً. الأسئلة الثلاثة من Concept 2 (why، what، وما لا نبنيه) تتوسع إلى ستة أقسام ملموسة. المواصفة العملية تحتوي، كحد أدنى، على:

• Goal: لماذا، في جملتين أو ثلاث.
• User scenarios: مسارات "عندما يفعل المستخدم X، يحصل على Y".
• Functional requirements: musts قابلة للاختبار، كل واحدة محددة بما يكفي كي يفشل build إن تجاهلها.
• Edge cases & rules: مدخلات فارغة، ضخمة، مكررة، malformed، unauthorized.
• Out of scope: ما لا يفعله هذا صراحةً. لا تتخط هذا.
• Acceptance criteria: checklist يقول "done" (وتبقى definition of done العامة من constitution فوقها).

تشريح المواصفة: ستة أقسام تصف السلوك، ولا HOW عمداً، لأن ذلك مكانه الخطة.

اكتبها بهذا prompt، ثم شدّدها بيدك:

Using the research above and our constitution, draft spec.md for [feature]. Include: goal (the why), user scenarios, functional requirements, edge cases & rules, out-of-scope, and acceptance criteria. Describe behaviour only, no databases, frameworks, or file layout. Make each requirement specific enough that a build which ignored it would visibly fail.

معنى "tighten by hand". إنه اختبار الدقة من Concept 2 وهو يعمل فعلاً. انظر كيف يتحول requirement من شيء يستطيع AI تلبيته خطأً إلى شيء لا يلبى إلا بشكل صحيح:

Before: "Users can reset their password."

After: "A signed-out user can request a password reset by email. The link works once, expires after 30 minutes, and a used or expired link shows a 'request a new link' message. The response never reveals whether an email is registered."

السطر الأول قد يمرر build يرسل كلمة مرور plaintext لأي شخص يطلبها. الثاني لا يمرر إلا الشيء الذي قصدته فعلاً. كل detail تتركه، سيقرره AI نيابة عنك، فقرر التفاصيل المهمة هنا، بالكلمات.

إبقاء المواصفة خالية من التنفيذ هو ما يتيح لك تغيير رأيك حول الأدوات لاحقاً دون إعادة كتابة intent.

إذا تركت هذا الانضباط، سيصبح اختيار الأداة requirement بالخطأ. تقول مواصفة "store uploads in S3"؛ تتبعها الخطة والكود؛ بعد شهر تحتاج صفقة compliance إلى تخزين على خوادم الشركة نفسها. السلوك الذي اهتم به الجميع فعلاً، وهو أن uploads تبقى durable وقابلة للاسترجاع، لم يُكتب أبداً؛ الذي كُتب هو vendor فقط، لذلك يصبح التغيير refactor بدلاً من سطر واحد في الخطة.

7. Phase 3: Clarify by interview (make the AI ask you)​

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

Before we build anything, interview me about this spec. Ask one question at a time, focusing on ambiguities, missing edge cases, and unstated assumptions. Keep going until you could hand this spec to a stranger and trust they'd build exactly what I mean. Don't write any code yet.

ستتفاجأ بكم الأشياء "الواضحة" التي لم تُذكر أصلاً. كل ambiguity تحلها هنا، بالكلمات، هي ambiguity لا تحلها لاحقاً بحذف كود خاطئ. هذا أرخص مكان في العملية كلها لإصلاح خطأ: إصلاحه في المواصفة يكلف جملة؛ إصلاحه بعد التنفيذ يكلف rebuild.

إن تخطيته، فستُجاب الأسئلة على أي حال، لكن لاحقاً، داخل الكود. يكتب فريق في المواصفة "users can upload a profile photo"، يهز الجميع رؤوسهم، ثم يشحنون. خلال يوم: يرفع أحدهم TIFF بحجم 40 MB لأن size/type limit لم تُذكر، ويكتب مستخدمان فوق صور بعضهما لأن uniqueness rule غابت، وملف تالف يظهر فارغاً في الموقع كله لأن fallback لم يحدد. ثلاثة assumptions غير مكتوبة، كان interview سيسأل عنها في جملة واحدة، وأصبحت الآن bugs.

8. Phase 4: Build from the spec​

اتُفِق على المواصفة. الآن تبني منها، وحجم العملية الذي تضيفه يوازي حجم التغيير. لا يوجد pipeline ثابت تشغله كل مرة: افعل أقل قدر من planning يحتاجه التغيير، ثم أشرف على build مقابل المواصفة.

• تغيير يمكن وصفه في جملة واحدة، مثل typo أو rule واحد أو field جديد: اطلبه فقط. تخط الخطة. فرض process ثقيل على إصلاح من سطر واحد هو جانب المبالغة من الخطأ نفسه.
• تغيير approach فيه غير مؤكد، أو يمس عدة files: ابدأ بالخطة. اجعل agent يقترح approach، وراجعه قبل أي code.
• تغيير متعدد الملفات أو معماري: الحلقة الكاملة، plan ثم build ثم verify، والعمل مكسّر إلى خطوات صغيرة قابلة للفحص.

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

من يكسّر العمل إلى tasks؟ الوكيل يفعل. هذا هو الجزء الذي تغيّر. أنت لا تكتب task list بيدك. Claude Code وOpenCode يخططان ويفككان العمل إلى checklist متتبعة خاصة بهما، ويعملان خلالها، ويعلّمان كل item done. مهمتك هي مراجعة ذلك breakdown وفحص كل step مقابل المواصفة، لا كتابة القائمة. (في claude.ai، حيث لا توجد task tool، تحفظ plan وtasks ك Artifacts بنفسك: هذا هو الموضع الوحيد الذي ما زال يناسبه "write a tasks file".)

Plan (عندما يستحق التغيير):

Based on the agreed spec, propose a technical plan: stack, structure, and the key decisions, each with its trade-off. Match our constitution and reuse what already exists rather than adding new dependencies. Don't write code yet; I'll review the plan first.

Build (بإشراف):

Implement the agreed plan in small, checkable steps. Do one step at a time, and after each, check it against the spec and stop for me to confirm before the next. Commit after each so every step has a clean rollback point.

خطط بنموذج قوي، ونفّذ بنموذج أرخص

التفكير المكلف في الخطة. بعد الاتفاق على approach، يصبح البناء "اتبع الخطوات"، وهذا ينجزه نموذج أرخص أو أسرع جيداً. في coding agents هذا setting واحد؛ وفي claude.ai تنجز planning في أقوى chat لديك، وتحتفظ بالمواصفة والخطة ك handoff. (التقسيم نفسه Plan/Execute من Agentic Coding Crash Course.)

أغلق الحلقة: verify مقابل المواصفة

الكود الذي يعمل ليس هو نفسه الكود الذي يفعل ما اتفقت عليه. حوّل acceptance criteria إلى checks حقيقية: automated tests عندما تستطيع، manual run-through عندما لا تستطيع، أو قائمة قصيرة من review questions، وشغّلها بعد كل step. إن فشل check لأن المواصفة كانت غامضة لا لأن الكود خطأ، فأصلح المواصفة أولاً ثم الكود. إن تخطيت ذلك، يتدهور SDD بهدوء إلى ما جاء ليمنعه: documentation مصقولة بجانب كود لم يتحقق منه أحد.

Part 2 on one screen​

الطريقة كلها، قابلة للنسخ. خذ screenshot لل checklist؛ واحفظ prompts في snippet.

هل انتهت مواصفتي؟

• Goal: لماذا، في 2–3 جمل
• User scenarios: "عندما يفعل المستخدم X، يحصل على Y"
• Functional requirements: كل واحدة محددة بما يكفي كي يؤدي تجاهلها إلى فشل build
• Edge cases & rules: فارغ، ضخم، مكرر، malformed، unauthorized
• Out of scope: ما لا يفعله هذا صراحة
• Acceptance criteria: checklist يقول "done"
• No HOW: لا database ولا framework ولا file layout (هذا مكانه الخطة)

ال prompts الأربعة، بالترتيب:

RESEARCH:  Research what's involved in building [feature]. Investigate separately and
           report each on its own: (1) how this is usually done, (2) the main approaches
           and trade-offs, (3) what in our existing project it must fit, (4) failure modes
           and edge cases. One-page findings doc. No design or code yet.

SPECIFY:   Using the research and our constitution, draft spec.md for [feature]: goal,
           user scenarios, functional requirements, edge cases & rules, out-of-scope,
           acceptance criteria. Behaviour only — no tech choices. Make each requirement
           specific enough that a build ignoring it would visibly fail.

CLARIFY:   Before we build anything, interview me about this spec, one question at a
           time — ambiguities, missing edge cases, unstated assumptions — until there's
           nothing left to misread. No code yet.

BUILD:     Right-size it. Tiny change: just ask. Otherwise: have the agent propose a
           plan and review it, then let it build in small steps, checking each against
           the spec and committing as you go. Turn acceptance criteria into checks.

---

Part 3: The Three Ways​

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

الأدوات تتحرك؛ الانضباط لا يتحرك

الميكانيكيات المحددة في هذا الجزء، مثل keybindings (Shift+Tab, Tab) وslash commands (/init, /undo) وأسماء النماذج وميزات المنتجات (Projects, Artifacts, Canvas, Gems)، صحيحة حتى يونيو 2026 وقد تتغير. الانضباط الرباعي الذي تشغله لا يتغير.

انضباط واحد، وثلاثة بيوت للمواصفة: الحلقة نفسها تعمل في claude.ai وClaude Code وOpenCode؛ الذي يتغير فقط هو أين تعيش المواصفة.

9. Way 1: claude.ai, the main method​

في تطبيق الويب، لديك لبنتان: Projects، وهي workspace مستمرة فيها custom instructions ومعرفة مرفوعة، وArtifacts، وهي وثائق قابلة للتحرير تعيش بجانب المحادثة. SDD يطابقهما مباشرة.

إعداد مرة واحدة، constitution:

1. أنشئ Project لعملك، مثل "Smart Notes".
2. ضع constitution في custom instructions للمشروع. ارفع research أو docs موجودة أو screenshots إلى Project knowledge حتى يراها كل chat في المشروع.

شغّل المراحل الأربع، وكل مرحلة تنتج Artifact:

• Research → اطلب من Claude أن يحقق وينتج Artifact لل findings. (لا توجد subagents في web app، لذلك اطلب تغطية عدة أسئلة في وثيقة منظمة واحدة.)
• Specify → اطلب من Claude أن يصوغ spec.md ك Artifact. عدّله مباشرة في Artifact panel حتى يصير صحيحاً.
• Clarify → الصق interview prompt من Concept 7. أجب عن الأسئلة؛ اجعل Claude يدمج الإجابات في spec Artifact.
• Build → اطلب Artifact باسم plan.md، ثم Artifact باسم tasks.md، ثم نفّذ task by task. كل code file يصبح Artifact خاصاً يمكنك preview وتنزيله.

لماذا يهم Project: يبقى constitution وspec loaded عبر كل chat، فتستطيع فتح محادثة جديدة للتنفيذ دون إعادة شرح المشروع. Artifacts هي ملفات المواصفة؛ انسخها إلى repo عندما تنتقل إلى coding agent.

يستطيع ChatGPT وGemini تشغيل الانضباط نفسه

إن كنت تفضل مساعد ويب آخر، فإن الانضباط ينتقل حتى لو اختلفت mechanics. ChatGPT: Projects للدستور، وCanvas لوثائق spec/plan القابلة للتحرير. Gemini: Gem للدستور، وCanvas للوثائق. الحلقة، constitution ثم Research → Specify → Clarify → Build، هي نفسها؛ تتغير الأزرار ومدى استمرار ذاكرة كل "project" فقط. claude.ai هو default لدينا لأن Artifacts + Projects يطابقان spec files بنظافة، لكن لا شيء هنا Claude-only.

قبل أن تلصق أي شيء في أداة browser

نافذة chat سهلة، وهذا هو الخطر. لا ترفع private source code أو customer data أو secrets أو credentials أو business material سرياً إلى أي web assistant إلا إذا سمحت سياسة منظمتك. للعمل الحساس، شغّل repo-based agent داخل بيئتك المعتمدة واستخدم أمثلة sanitized وخيالية، مثل Smart Notes أدناه. الانضباط نفسه؛ data boundary ليس نفسه.

10. Way 2: Claude Code, the discipline in your repo​

عندما يكون مشروعك software حقيقياً، يزيل Claude Code النسخ واللصق: spec وplan وtasks تعيش كملفات في repo، بجانب الكود الذي تولده. الميزات native أدناه تكفي، دون frameworks إضافية. ما يضيفه فوق chat loop هو machinery مدمجة لكل phase:

• constitution ملف يقرأه Claude في كل session. يتم تحميل CLAUDE.md عند بداية كل conversation، فلا تعيد اللصق، لكن عامله كإرشاد مستمر لا كضمان صلب (ادعم must-never rules ب hooks أو tests كما في Concept 4). شغّل /init، ثم اختصره إلى القواعد الحقيقية.
• Plan mode هو بوابة Specify/Clarify، ومفروضة. Shift+Tab إلى plan mode يجعل Claude read-only: يستطيع دراسة code وصياغة spec، لكنه لا يكتب سطراً قبل موافقتك. هذا هو "agree before you build" كميزة أداة.
• Subagents تنجز parallel research دون تلويث context. كل واحد يحقق في area داخل window خاص ويسلّم summary فقط، فتبقى Phase 1 سريعة وmain session خفيفة.
• الوكيل يحافظ على task list الخاصة به؛ أنت تشرف. بعد approval للخطة، يكسّر Claude العمل إلى checklist متتبعة ويعمل عليها، معلّماً كل item done. أنت لا تؤلف القائمة؛ عملك مراجعة breakdown، ثم بعد كل step تشغيل checks المناسبة مقابل المواصفة وال commit قبل التالي، حتى تكون لكل step نقطة rollback نظيفة. إيقاع commit-after-each هو workflow تديره أنت، ويمكن وضعه في constitution؛ إن كان يجب أن يحدث دائماً، افرضه ب hook.

لأن كل artifacts ملفات plain، صارت المواصفة في version control: تستطيع diff لها، ومراجعتها في pull request، ورؤية متى كان السلوك ينبغي أن يتغير. هذه هي القفزة من "مواصفة كتبتها مرة" إلى "مواصفة تحكم repo".

11. Way 3: OpenCode, any model​

كل شيء في Concept 10 ينطبق على OpenCode أيضاً: ملف القواعد (AGENTS.md) ك constitution (ويقرأ OpenCode أيضاً CLAUDE.md موجوداً إن لم يوجد AGENTS.md)، وPlan mode (Tab) كبوابة read-only، وsubagents لل research، وgit-backed /undo بين build steps. كما في Claude Code، يتتبع agent task list الخاصة به ويعمل عليها بينما تراجع breakdown وتفحص كل step مقابل المواصفة؛ Tab يبدّل إلى Build mode بعد الموافقة. الشيء الوحيد الذي يضيفه OpenCode هو model choice، وهو ينسجم مع تقسيم SDD الطبيعي: phases المواصفة والخطة تكافئ نموذج reasoning قوي، بينما بناء task list واضحة يعمل جيداً على نموذج أرخص مثل deepseek-v4-flash. أنت تقرر أين تذهب كل دولار من "thinking". (تفاصيل setup لكلا الوكيلين في Agentic Coding Crash Course.)

---

Part 4: A Complete Worked Example​

12. One feature, start to finish, twice​

لنشغّل الحلقة كلها على feature صغير وحقيقي: "weekly digest" يرسل لكل مستخدم ملخصاً لملاحظاته كل يوم اثنين. يمس ذلك عدة ملفات، job مجدولة، query للملاحظات، وmailer، لذلك، وفق right-sizing rule من Concept 8، يستحق الحلقة الكاملة. نفعل ذلك مرتين: أولاً في claude.ai، حيث التفكير مرئي، ثم في Claude Code، حيث تعمل الحلقة على files حقيقية في repo.

في claude.ai

Phase 0: Constitution (معد مسبقاً في Project). المبادئ: لغة واضحة، تفضيل libraries الموجودة، كل feature تشحن مع spec، وعدم لمس published/.

Phase 1: Research. Prompt:

Research what's involved in a "weekly digest email" for our notes app. Cover: how we'd select which notes to include, scheduling options, email-sending approaches, and the main failure modes (no notes that week, send failures, time zones). Give me a one-page findings doc. Don't propose a final design yet.

يعيد Claude findings Artifact. تقرأه سريعاً؛ سؤال time-zone لم تكن قد فكرت فيه.

Phase 2: Specify. Prompt:

Using those findings and our constitution, draft spec.md for the weekly digest. Include goal, user scenarios, functional requirements, edge cases, out-of-scope, and acceptance criteria. Describe behaviour only, no tech choices yet.

تحصل على spec Artifact. جيد، لكنه عام في مواضع.

Phase 3: Clarify. Prompt:

Before we plan anything, interview me about this spec, one question at a time, until there's nothing left to misread.

يكشف interview قرارات لم تذكرها: تستخدم digests يوم الاثنين المحلي للمستخدم، لا UTC؛ أسبوع بلا notes لا يرسل شيئاً بدلاً من بريد فارغ؛ unsubscribed users يتخطاهم النظام. تجيب، ويطوي Claude كل إجابة داخل spec Artifact. هنا يجني SDD قيمته: ثلاثة bugs مستقبلية ماتت كجمل.

Phase 4: Build.

Now write plan.md: the technical approach for this spec, given our existing stack. Then tasks.md: an ordered, checkable task list.

تراجع الخطة، وهي تعيد استخدام mailer الموجود حسب constitution، توافق عليها، ثم تنفذ task by task، وتفحص كل واحدة مقابل المواصفة وتحفظها. عندما يكشف task أن المواصفة صامتة حول شيء، مثل email subject line، تحدّث المواصفة أولاً، ثم تكمل. تبقى المواصفة صحيحة.

الميزة نفسها في Claude Code

المراحل الأربع نفسها وال prompts نفسها؛ الذي يتغير أن كل artifact هو file وأن الأداة تفرض gates التي فرضتها على نفسك في المتصفح.

• Research: بدلاً من findings doc واحد، شغّل subagents، واحداً لكل area، فيبقى main session خفيفاً. تهبط findings في specs/weekly-digest/research.md.
• Specify: ادخل plan mode ب Shift+Tab، وهو read-only: قاعدة "don't build yet" تفرضها الأداة لا إرادتك.
• Build: يخطط Claude العمل في task list متتبعة خاصة به ويبني خلالها؛ تراجع كل step مقابل المواصفة وتعمل commit بعد كل واحدة، فيقرأ git log مثل تلك القائمة، وكل step rollback point نظيف.

الفرق الحقيقي الوحيد هو أين تنتهي المواصفة: في claude.ai عاشت داخل Artifact تنسخه لاحقاً؛ في Claude Code تعيش في specs/، version-controlled بجانب الكود الذي أنتجته. (OpenCode مطابق: استبدل CLAUDE.md ب AGENTS.md، وShift+Tab ب Tab.)

النتيجة ليست working code فقط؛ بل working code ومعه spec تشرحه وتحكمه، جاهزة للشخص التالي، أو أنت التالي، كي يغيّره بأمان.

See the shape of the artifacts: a compact spec.md, plan.md, and tasks.md

تبقى الطريقة مجردة حتى ترى ما ينتج عنها. هذه نسخ مختصرة من artifacts الثلاثة حتى ترى الشكل. في claude.ai تنشئ الثلاثة ك Artifacts؛ ومع coding agent تحفظ spec.md وplan.md ك files، بينما تكون task list عادةً خاصة بالوكيل، لكنها مكتوبة هنا حتى ترى شكل الجيدة منها. النسخ الحقيقية أطول؛ الشكل هو المهم.

# spec.md — Weekly Digest

## Goal

Email each user a once-a-week summary of their own notes so they
re-engage without opening the app. Reduce silent churn.

## User Scenarios

- A user with notes this week gets a Monday-morning digest listing them.
- A user with no notes this week gets nothing (not an empty email).
- An unsubscribed user gets nothing, ever.

## Functional Requirements

FR-1 Digest sends on the user's local Monday at 8:00am.
FR-2 Include only notes created or edited in the prior 7 days.
FR-3 Zero qualifying notes → no email is sent.
FR-4 Unsubscribed users are skipped.
FR-5 A send failure is retried once, then logged; it never blocks others.

## Edge Cases & Rules

- Time zone missing → fall back to UTC.
- 50+ notes → list the 10 most recent, then "and N more."

## Out of Scope

- Digest customization, frequency options, non-email channels.

## Acceptance Criteria

- [ ] A user in Asia/Karachi receives the digest at their local Monday 8am.
- [ ] An empty week sends no email (verified in logs).
- [ ] Unsubscribed users receive nothing.
- [ ] One simulated send failure retries once, then logs, others still send.

# plan.md — Weekly Digest

## Approach

Reuse the existing mailer service (constitution: prefer what exists).
A scheduled job runs hourly, selects users whose local time is Mon 08:00,
builds the digest from the notes query, and hands it to the mailer.

## Key Decisions

- Scheduling: hourly cron + per-user timezone check (no per-user timers).
- Templating: reuse existing email template system.
- Failure handling: wrap each send; retry-once lives in the job, not the mailer.

## Touch Points

- new: jobs/weekly_digest.\* | reuse: services/mailer, models/note
- no schema change required

# tasks.md — Weekly Digest

1. Note-selection query: notes per user from the last 7 days. [FR-2]
2. Eligibility check: local Monday 08:00 + subscribed. [FR-1, FR-4]
3. Digest builder: top 10 + "and N more"; skip if empty. [FR-3, edge]
4. Wire to mailer with retry-once + logging. [FR-5]
5. Tests for each acceptance criterion. [Verify]

لاحظ الخيوط: كل task تذكر requirement الذي تحققه، وال task الأخيرة verification مشتقة مباشرةً من acceptance criteria.

---

Part 5: Judgment​

13. When SDD pays off, and when it is overkill​

SDD انضباط، والانضباط له كلفة: توقّع أن يبدو Specify وClarify بطيئين، عشرات الدقائق من التفكير بينما كان vibe coding سيعرض كوداً بالفعل، واعرف أن هذا الفارق هو المقايضة التي تصنعها. يترك المبتدئون الطريقة في اللحظة التي تبدو فيها أسوأ، قبل أن ترد قيمتها مباشرة. إنفاقها على إصلاح من سطر واحد خطأ، كما أن تخطيها في نظام مدفوعات خطأ. المهارة أن تعرف أيهما أمامك.

استخدم SDD عندما…	تخطّه، فقط vibe، عندما…
يمس العمل عدة files أو modules أو data	هو script لمرة واحدة أو tweak صغير
سيصونه شخص آخر أو future-you	سترمي النتيجة اليوم
الخطأ مكلف: مال، بيانات، ثقة	كلفة التخمين الخاطئ هي "press undo"
requirements ضبابية وتحتاج إلى تثبيت	المهمة واضحة تماماً في جملة واحدة
يحتاج عدة أشخاص إلى الاتفاق على معنى "done"	أنت تستكشف لتتعلم ما تريده أصلاً

تشغيل "make this button blue" عبر process كامل من constitution إلى implement عبث. لكن لحظة تتضمن المهمة state أو permissions أو data models أو money أو توقعات شخص آخر، تبدأ البنية بالدفع عن نفسها، وتدفع أكثر كلما طال عمر الشيء.

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

هناك payoff آخر غير فعل الشيء الصحيح من المرة الأولى: إنه يخرجك من التعثر. في بيانات جلسات Anthropic، عندما انحرف build، كان أقل المستخدمين خبرة يتركون الجلسات المتعثرة بمعدلات أعلى بكثير؛ ما اشترته الخبرة أساساً هو القدرة على إعادة توجيه agent. المواصفة المتفق عليها هي steering wheel: عندما ينكسر شيء، لديك نقطة ثابتة debug against بدلاً من ذكرى غامضة لما أردته. حركة التعافي ملموسة: عندما ينحرف agent عن المواصفة أثناء build، أعد grounding له بلصق requirement المحدد الذي تجاهله، صغّر المهمة إلى ذلك الشيء فقط، ثم أعد توجيهه إلى acceptance criteria.

أبقِ المواصفة حية، وهو الجزء الذي ينساه الجميع. المواصفة لا تكون source of truth إلا إذا بقيت صحيحة. عندما يتغير السلوك، قاعدة جديدة أو feature محذوفة أو edge case مصحح، غيّر المواصفة أولاً، ثم re-derive الكود. هذه الحركة تحول Spec-First إلى Spec-Anchored، وهي الفرق بين مواصفة تصبح أكثر قيمة مع الوقت ومواصفة تصبح كذبة في repo خلال شهر.

شكل drift عملياً: يغيّر شخص subject line في digest email مباشرة داخل الكود ويشحنه. تبقى المواصفة تصف subject القديم. بعد ثلاثة أسابيع يقرأ teammate جديد المواصفة، "يصلح" الكود ليتطابق معها، ويكسر بهدوء ما كان يعمل. لم يكذب أحد؛ المواصفة توقفت عن كونها صحيحة، وكلف ذلك bug ليظهر. الإصلاح رخيص وممل: يدخل تغيير spec.md في commit نفسه مع الكود، كل مرة.

ماذا يتغير عندما تملك specs كثيرة. مواصفة واحدة وثيقة؛ مجلد يضم عشرات المواصفات نظام. السؤال الحي لا يبقى "هل هذه المواصفة واضحة؟" بل يصبح "هل ما زالت هذه المواصفات متفقة؟" تتفاعل features معاً، وقد ينتشر change في واحدة إلى أخرى، وعندما تشير مواصفتان إلى خيارات متعارضة يكون constitution هو ما يحسم الأمر. إبقاء مجموعة المواصفات كلها متسقة مع نموها هو القفزة الحقيقية من "أستطيع spec feature" إلى "أدير repo على SDD".

---

Practice​

قراءة SDD ليست تعلم SDD. لا يصبح الانضباط ملكك إلا بعد تشغيل الحلقة كاملة على شيء حقيقي والشعور بمرحلة Clarify وهي تلتقط خطأ كنت ستشحنه. افعل هذه بالترتيب. كل واحدة ترفع stakes، وكل واحدة متعمدة بعد خط "just vibe it" حتى تضطر البنية إلى إثبات قيمتها.

لكل project، أنتج artifacts الأربعة نفسها: constitution و**spec.md** و**plan.md** و**tasks.md**، إضافة إلى النتيجة العاملة. اختبار النجاح الوحيد هو اختبار Concept 2: هل يستطيع غريب أن يبني الشيء الصحيح من مواصفتك وحدها، دون أن يسألك سؤالاً واحداً؟

Warm-up: اشعر بال interview (claude.ai، نحو 30 دقيقة). اختر أصغر شيء حقيقي كنت تنوي بناءه: study planner، CSV-to-summary tool، habit tracker. أنشئ Project، الصق constitution من ثلاثة أسطر، وشغّل المراحل الأربع. القاعدة الوحيدة: لا تتخط Concept 7. اجعل Claude ي interview قبل أي code. احسب كم قراراً ظهر لم تفكر في ذكره. ذلك الرقم هو سبب وجود SDD.

Project 1: feature بقواعد حقيقية (claude.ai، نحو ساعة). اكتب spec وابنِ "tag and filter" feature ل Smart Notes: يضيف المستخدمون tags إلى notes ويصفّون بها. يبدو تافهاً حتى تكتبه كمواصفة، وهذا هو المقصود. أجبر نفسك على تثبيت edge cases في spec: ماذا يحدث بلا tags؟ duplicate tags؟ filter بلا matches؟ حساسية case؟ rename tag مستخدم؟ Done when تجيب المواصفة عن الخمسة قبل كتابة سطر implementation واحد.

Project 2: انقله إلى repo (Claude Code أو OpenCode، نحو ساعتين). خذ Project 1 من chat window وشغّله في coding agent. ضع constitution في CLAUDE.md / AGENTS.md، واحفظ spec.md وplan.md وtasks.md ك files في repo، واستخدم plan mode كبوابة specify/clarify. نفّذ task واحدة كل مرة، مع commit بعد كل واحدة. Done when يعرض git log commit نظيفاً لكل task، وتعيش المواصفة في version control بجانب الكود الذي أنتجته.

Project 3: أبقِ المواصفة حية (الأصعب، نحو ساعة). غيّر رأيك الآن. أضف requirement جديداً إلى Project 2: مثلاً tags can be colour-coded أو filtering supports "any of" and "all of" modes. قاوم رغبة أن تطلب من agent إضافته مباشرة. بدلاً من ذلك: عدّل spec.md أولاً، أعد تشغيل Clarify على القسم المتغير، حدّث plan وtasks، ثم implement. Done when يحكي diff في spec.md وdiff في الكود القصة نفسها. هذه هي الحركة التي تحول Spec-First إلى Spec-Anchored، وهي التي لا يتدرب عليها معظم الناس.

Project 4: اعمل داخل code لم تكتبه (Claude Code أو OpenCode، نحو ساعتين). مشروع جديد تماماً هو الحالة السهلة. استنسخ مشروع open-source صغيراً لم تره، أو خذ repo لشخص آخر، وأضف feature متواضعة باستخدام SDD. هذه المرة Phase 1 تحمل الوزن: قبل كتابة أي spec، اجعل agent يبحث كيف ينظم code الحالي، وأين يجب أن تدخل feature، وما conventions التي يجب احترامها؛ استخدم subagents حتى يرسم كل واحد area ويعود. يجب أن تحتوي مواصفتك على قسم "fits the existing system" يذكر patterns التي تطابقها. Done when تقرأ feature كأنها كانت دائماً جزءاً من codebase، لا ملحقة، وتشرح المواصفة why it fits.

Project 5: SDD بلا code على الإطلاق (claude.ai، نحو 45 دقيقة). أثبت لنفسك أن هذا thinking discipline، لا coding discipline (Concept "not a programmer"). اختر process قابلة للتكرار، لا app: weekly status report من raw notes، content-repurposing pipeline، inbox-triage routine، أو grading rubric للتسليمات. شغّل الحلقة نفسها: constitution وresearch وspec وclarify وbuild، حيث ينتج "build" process and its prompts لا source code. Done when تستطيع أنت أو teammate تشغيل العملية من spec والحصول على نتيجة consistent كل مرة، بلا improvisation.

Project 6: stranger test الحقيقي (capstone، نحو 1.5 ساعة). كل ما سبق راجعته أنت، وهذا أضعف reviewer ممكن لأنك تعرف ما قصدته. لذلك احذف نفسك. اكتب spec ل feature، ثم سلّمها إلى fresh, empty AI session، chat جديد بلا memory من نقاشك، أو إلى peer، واجعلهم يبنونها ب zero questions allowed. أينما بنوا الشيء الخطأ، فالخلل في المواصفة لا فيهم: أصلح المواصفة لا الكود، وجرب ثانية. Done when يبني cold reader ما قصدته فعلاً من أول محاولة. إن نجحت، فقد امتلكت المهارة الحقيقية: كتابة intent بدقة تكفي ليعيش خارج رأسك.

---

Where this leads​

أصبحت لديك الآن discipline كاملة: اتفق على ماذا قبل أن تولّد كيف، أبقِ المواصفة source of truth، وشغّل constitution → Research → Specify → Clarify → Build في أي من الأدوات الثلاث يناسب اللحظة.

هذه هي طبقة التفكير تحت كل شيء آخر في الكتاب. رأيت أدوات البرمجة التي تشغّل هذه الحلقة، Claude Code وOpenCode، في Agentic Coding Crash Course، ورأيت الانضباط يعمل في Cowork Crash Course؛ ارجع إلى أي منهما لل mechanics بعمق. من هنا، تجعل Mode tracks هذه الحلقة تعمل: كل build course تأخذه، Python in the AI Era، وBuild AI Agents، وAI Searchable Context، وBuilding a Digital FTE، هو الحلقة نفسها مطبقة على systems أكبر فأكبر.

تذكر thesis الكتاب كله: General Agents build Custom Agents. Spec-Driven Development هو كيف توجه general agent إلى hard problem وتستعيد reliable system بدلاً من كومة guesses.

---

Flashcards Study Aid

---

Test Your Understanding

اختبر ما تعلمته. تعرض كل session مجموعة جديدة من 18 سؤالاً، لذلك تحصل على أسئلة جديدة كلما أعدته.

Checking access...