النقاط الرئيسية
- كل أمر إنتاجي يحتاج كحد أدنى إلى بطاقة سطر واحد (الغرض، النموذج، التاريخ، المؤلف)
- كل أمر معدَّل يحتاج إلى كتلة إصدار (ما الذي تغير، لماذا، نتيجة الاختبار)
- كل أمر مختبَر يحتاج إلى رأس مجموعة اختبار (معايير النجاح، الأمثلة الذهبية، أوضاع الفشل)
- احتفظ بالتوثيق في النظام ذاته الذي يحتوي على الأمر — الوثائق المنفصلة تُهجر
- مبرر التغيير ("السبب") هو أهم حقل: الفرق التي تتجاهله تعود إلى الأنماط القديمة عند مغادرة المؤلف
- يوفر PromptHub أكثر هيكل توثيق مدمج شمولاً؛ يعمل Git لفرق الهندسة ذات الانضباط الجيد في الالتزامات
لماذا تُدمِّر الأوامر غير الموثقة الفرق
📍 In One Sentence
الأوامر غير الموثقة تُدمِّر الفرق من خلال التراجع الصامت والتكرار وفقدان المعرفة — وكل ذلك قابل للوقاية بـ5-10 دقائق توثيق لكل أمر.
💬 In Plain Terms
عندما لا يكون للأمر سجل بما يفعله أو بالسبب الذي كُتب به بتلك الطريقة، لا يستطيع الفريق تغييره بأمان، أو استعادته بعد تعديل، أو تسليمه لعضو جديد دون سياق.
الأوامر غير الموثقة تُدمِّر الفرق بثلاث طرق: التراجع الصامت (لا سجل لما تغير)، التكرار (الفرق تعيد كتابة الأوامر الموجودة لأنها لا تجدها)، وفقدان المعرفة (تصبح الأوامر غير قابلة للصيانة عند مغادرة المؤلف). كل إخفاق قابل للوقاية بـ5-10 دقائق توثيق لكل أمر.
الإخفاق الأكثر تكلفة هو التراجع الصامت. يعدّل فريق ما أمراً إنتاجياً لحل مشكلة، فيكسر عن غير قصد مشكلة أخرى، ولا يملك خطاً أساسياً للمقارنة. بدون سجل إصدارات ورأس مجموعة اختبار، يتطلب تشخيص التراجع مقارنة يدوية وتخمينات.
استخدم التوثيق لكل أمر يُستخدم أكثر من مرة، أو يُخزَّن في بنية أساسية مشتركة، أو يُنشر في الإنتاج. أغفله للأوامر الاستكشافية أحادية الاستخدام في جلسة واحدة.
⚠️ خطر التراجع الصامت
بدون كتلة إصدار وأمثلة ذهبية، لا يملك الفريق الذي يعدّل أمراً إنتاجياً خطاً أساسياً. كل تعديل هو تخمين حول الحالة السابقة.
6 قوالب لتوثيق الأوامر
ستة قوالب تغطي دورة حياة الأمر الكاملة من المسودة الأولى إلى التقاعد في الإنتاج. كل قالب مصمَّم ليكتمل في أقل من 10 دقائق ويوفر الحد الأدنى من المعلومات المطلوبة لكل مرحلة من مراحل دورة الحياة.
- 1بطاقة السطر الواحد
Why it matters: الغرض: التقاط السجل الأدنى لأي أمر مُعاد استخدامه. الحقول: اسم الأمر، الغرض (جملة واحدة)، النموذج المستهدف، تاريخ الإنشاء، المؤلف. متى تستخدمه: عند حفظ أمر لأول مرة. التخزين: أي أداة مشتركة (Notion، Git، PromptHub). - 2كتلة الإصدار
Why it matters: الغرض: تتبع سجل الأوامر التي تتغير بمرور الوقت. الحقول: رقم الإصدار، تاريخ التعديل، المؤلف، ما الذي تغير (جملة واحدة)، سبب التغيير (جملة واحدة)، ملخص نتيجة الاختبار. متى تستخدمه: عند تعديل أمر. التخزين: رسالة الالتزام في Git أو إدخال الإصدار في PromptHub. - 3رأس مجموعة الاختبار
Why it matters: الغرض: تحديد معايير القبول قبل كتابة الاختبارات. الحقول: هدف الاختبار (ما يجب أن يفعله الأمر)، معايير النجاح (ما هي خصائص الإخراج التي تحدد النجاح)، الأمثلة الذهبية (2-3 أزواج إدخال/إخراج)، أوضاع الفشل المعروفة. متى تستخدمه: عند دخول أمر إلى مجموعة الاختبار. التخزين: بجانب ملف الاختبار في Git أو في مشروع Braintrust. - 4سجل القرارات
Why it matters: الغرض: تسجيل قرارات التصميم غير الواضحة في نص الأمر. الحقول: القرار المتخذ، البدائل المدروسة، سبب اختيار هذا الخيار، التاريخ. متى تستخدمه: عند اتخاذ قرار تصميم غير واضح (مثلاً، لماذا تم تعيين درجة حرارة معينة). التخزين: مستند مرتبط من كتلة الإصدار. - 5مبرر التغيير
Why it matters: الغرض: شرح سبب تغيير أمر بمصطلحات تسمح بالتراجع عن التغيير أو تكراره. الحقول: وصف المشكلة (ما كان خاطئاً)، التغيير المُجرى، التحسين المتوقع، النتيجة المقيسة. متى تستخدمه: عند تعديل أمر استجابةً لإخفاق أو تراجع. التخزين: نص الالتزام في Git أو ملاحظة التغيير في PromptHub. - 6كتلة تهيئة API
Why it matters: الغرض: تسجيل معاملات النموذج المستخدمة في الإنتاج. الحقول: النموذج (مثلاً GPT-5.5، Claude 4.6 Sonnet)، درجة الحرارة، الحد الأقصى للرموز، top_p، تسلسلات الإيقاف، إصدار أمر النظام، إصدار أمر المستخدم. متى تستخدمه: عند نشر أمر في الإنتاج. التخزين: ملف تهيئة النشر، مشار إليه من كتلة الإصدار.
📌 دليل اختيار القالب
أمر جديد ← بطاقة السطر الواحد. أمر معدَّل ← كتلة الإصدار. أمر مختبَر ← رأس مجموعة الاختبار. قرار تصميم مُتخذ ← سجل القرارات. تغيير بعد إخفاق ← مبرر التغيير. نشر في الإنتاج ← كتلة تهيئة API.
أين تحفظ توثيق الأوامر
احتفظ بتوثيق الأوامر في النظام ذاته الذي يحتوي على الأمر. إذا كان الأمر يعيش في الكود، احتفظ بالوثائق في Git. وإذا كان يعيش في أداة واجهة رسومية، احتفظ بالوثائق في ملاحظات تلك الأداة أو في مستند مرتبط.
- Git: الأفضل لفرق الهندسة التي تخزّن الأوامر كملفات. رسائل الالتزام تعمل ككتل إصدار. مجاني. يتطلب انضباطاً. لا يوجد سير عمل مراجعة مدمج.
- PromptHub: إدارة الأوامر مع سجل الإصدارات وتوقيعات المراجعين وتخزين نتائج الاختبار. 0-49 دولاراً في الشهر. الأفضل للفرق التي تضم 3 أشخاص أو أكثر يكتبون الأوامر.
- Notion: يعمل للفرق التي تدير الأوامر كوثائق بدلاً من الكود. سهل الإعداد. يفتقر إلى التحكم في الإصدار وتكامل الاختبار — تعامل معه كطبقة توثيق، لا كمصدر حقيقة.
- Braintrust: يخزّن رؤوس مجموعات الاختبار ونتائج التقييم بجانب إصدارات الأمر. الأفضل للفرق التي تُجري تقييمات آلية منتظمة.
- PromptQuorum: منصة تحسين الأوامر لإرسال الأوامر الموثقة إلى أكثر من 25 مزوداً للذكاء الاصطناعي في آنٍ واحد. استخدمها للتحقق من أن الأوامر الموثقة تعمم عبر النماذج قبل تثبيت الإصدار. طبقة مجانية.
💡 ضع التوثيق في مكان الأمر
التوثيق المخزَّن في نظام منفصل (Notion، Confluence، Google Docs) عن الأمر سيصبح قديماً في أيام. التوثيق الوحيد الذي يظل محدثاً هو ما يعيش مع الأمر.
أخطاء التوثيق الشائعة
❌ لا توثيق على الإطلاق
Why it hurts: لا يمكن استعادة الأوامر بعد التعديلات، ولا يفهم الفريق سبب كتابة أمر بطريقة معينة
Fix: استخدم على الأقل قالب بطاقة السطر الواحد — 3 حقول، أقل من دقيقتين
❌ توثيق مخزَّن بصورة منفصلة عن الأمر
Why it hurts: يصبح التوثيق قديماً مع تغير الأوامر؛ الفرق تنسى تحديثه
Fix: احتفظ بالتوثيق في ملف Git ذاته أو في الالتزام ذاته الذي يحتوي على الأمر
❌ حقل "السبب" غائب — يصف فقط ما يفعله الأمر
Why it hurts: المحررون المستقبليون لا يعرفون القيود، ولا يستطيعون إعادة الهيكلة بأمان
Fix: أضف حقل "مبرر" لكل قالب: 1-2 جمل عن سبب اختيار هذا الهيكل
❌ لا توجد كتلة إصدار
Why it hurts: لا توجد طريقة لمعرفة ما إذا كان الأمر الجاري في الإنتاج يطابق الإصدار الموثق
Fix: أضف الإصدار وتاريخ التعديل إلى كل ملف أمر إنتاجي
الأسئلة الشائعة
لماذا تحتاج الأوامر إلى توثيق؟
الأوامر غير الموثقة لا يمكن مراجعتها أو تدقيقها أو إعادة إنتاجها. عندما يغير المؤلف الأمر دون ترك أي سجل، لا يستطيع الفريق تشخيص التراجعات، ولا العودة إلى إصدار معروف بأنه جيد، ولا استقطاب أعضاء جدد.
ما هو الحد الأدنى من التوثيق الذي يحتاجه الأمر؟
الحد الأدنى هو بطاقة سطر واحد: غرض الأمر (جملة واحدة)، النموذج المستهدف، تاريخ الإنشاء، والمؤلف. تستغرق دقيقتين للكتابة وتمنع أكثر إخفاقات التوثيق شيوعاً — الأوامر التي يكون غرضها مجهولاً بعد 6 أشهر.
أين يجب تخزين توثيق الأوامر؟
خزّن توثيق الأوامر في الموقع ذاته الذي يوجد فيه الأمر. يعمل Git للأوامر المخزنة كملفات كود. يوفر PromptHub تخزيناً منظماً مع سجل الإصدارات وتوقيعات المراجعين المدمجة. يعمل Notion للفرق التي تدير الأوامر كوثائق، لكنه يفتقر إلى التحكم في الإصدار.
ما مدى التفصيل الذي يجب أن يكون عليه مبرر التغيير؟
ثلاثة أسطر: ما الذي تغير (جملة واحدة)، السبب (المشكلة التي يحلها التغيير)، والاختبار الذي أكد أنه نجح. الفرق التي تتجاهل "السبب" تعود حتماً إلى النمط القديم عند مغادرة المؤلف.
ما القالب الذي يجب أن أستخدمه لأمر جديد؟
ابدأ ببطاقة السطر الواحد. إذا ذهب الأمر إلى الإنتاج، انتقل إلى كتلة الإصدار. إذا كان لديه حالات اختبار متعددة، أضف رأس مجموعة الاختبار. إذا كان يتطلب قراراً غير واضح في التصميم، أضف سجل القرارات.
كم مرة يجب أن أحدّث توثيق الأوامر؟
حدّثه في كل مرة يتغير فيها نص الأمر. أضف زيادة في الإصدار وإدخال مبرر تغيير لكل تعديل جوهري. لا تحدّث التوثيق بأثر رجعي.
هل يمكنني استخدام هذه القوالب في PromptHub؟
نعم. يخزّن PromptHub حقول بيانات تعريف الأوامر التي تتوافق مباشرة مع قوالب كتلة الإصدار وكتلة تهيئة API. استخدم القالب كمسودة ثم انسخ الحقول إلى PromptHub عند الاستعداد لمشاركته مع فريقك.