Claude Code لانحراف التوثيق: حافظ على توافق الوثائق مع الشيفرة

ما هو انحراف التوثيق (ولماذا يستمر الحدوث)؟

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

على فريق حقيقي، يظهر الانحراف بهذه الصورة: README يقول إنك تستطيع تشغيل خدمة بأمر واحد، لكن الآن مطلوب متغير بيئة جديد. توثيق الـ API يظهر نقطة نهائية بحقل تم إعادة تسميته. كتيب التشغيل يخبر المُستجيب بإعادة تشغيل "worker-a"، لكن العملية الآن مقسمة إلى خدمتين.

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

التكاليف ملموسة:

• تعطّل التعريف بالعمل (الموظفون الجدد يضيعون أيامًا في مشكلات الإعداد).
• فشل النشر (الخطوات لا تتطابق مع التهيئة الحالية).
• ارتفاع عبء الدعم (المستخدمون يتبعون تعليمات قديمة).
• مطوّلة الحوادث (كتيبات التشغيل توجه المستجيبين في الاتجاه الخاطئ).

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

أين يظهر الانحراف: README و API docs و runbooks

عادةً ما يظهر الانحراف في المستندات التي يعاملها الناس كـ "مرجع سريع". يتم تحديثها مرة واحدة، ثم تستمر الشيفرة في التحرك. ابدأ بهذه الثلاثة لأنها تحتوي وعودًا محددة يمكنك التحقق منها.

README: المكان الأول الذي يشعر فيه المستخدمون بالألم

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

أسوأ نسخة هي "تقريبًا صحيحة". متغير بيئة واحد مفقود يمكن أن يضيع وقتًا أكثر من README قديم تمامًا، لأن الناس يستمرون في تجربة تباينات صغيرة بدلًا من التشكيك في الوثيقة.

توثيق API: أشكال متباينة وأمثلة مضللة

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

إشارات نموذجية:

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

كتيبات التشغيل: انحراف هادئ يسبب حوادث صاخبة

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

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

كيفية استخدام Claude Code: فروق وتقارير التناقض

Claude Code للتحقق من انحراف التوثيق يعمل بشكل أفضل عندما تعامل الوثائق كأنها شيفرة: اقترح تصحيحًا صغيرًا قابلًا للمراجعة واشرح السبب. بدلًا من طلب "تحديث README"، اطلب توليد فرق مقارنة لملفات محددة. يحصل المراجعون على عرض قبل/بعد واضح ويمكنهم اكتشاف تغييرات غير مقصودة بسرعة.

فحص الانحراف الجيد ينتج شيئين:

1. فرق بسيطة ومحدودة
2. تقرير تناقضات صريح ومحدد: "الوثيقة تقول X، المستودع يظهر Y."

اطلب دليلًا، لا آراء

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

إليك نموذج تحفيز يبقي الأمور متجذرة:

Check these docs for drift: README.md, docs/api.md, runbooks/deploy.md.
Compare them to the current repo.
Output:
1) Contradictions list (doc claim -> repo evidence with file path and line range)
2) Unified diffs for the smallest safe edits
Rules: do not rewrite sections that are still accurate.

إذا قال Claude أن "الـ API يستخدم /v2"، اجعله يدعم ذلك بالإشارة إلى الموجّه، مواصفة OpenAPI، أو اختبار تكاملي. إذا لم يعثر على دليل، يجب أن يقول ذلك.

حدد نطاق التغيير قبل التحرير

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

مثال: أعدت تسمية متغير بيئة من API_KEY إلى SERVICE_TOKEN. تقرير مفيد يعثر على كل مكان يظهر فيه الاسم القديم (قسم الإعداد في README، أمثلة API، قسم الأسرار في كتيب التشغيل)، ثم ينتج فرقًا ضيقة تحدّث تلك الأسطر فقط وأي أوامر مثال قد تفشل الآن.

أعد إعداد سير عمل بسيط قبل أن تطلب أي شيء

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

ابدأ بمجموعة وثائق واحدة: README، مرجع API، أو كتيب تشغيل فعلي الاستخدام. إصلاح منطقة واحدة من البداية للنهاية يعلمك الإشارات التي تثق بها قبل التوسع.

قرّر ما يُعد مصدر الحقيقة

اكتب، بكلمات بسيطة، من أين يجب أن تأتي الحقائق لمجموعة الوثائق تلك.

• بالنسبة لـ README: مخرجات مساعدة CLI وتطبيق مثال يعمل.
• بالنسبة لتوثيق API: تعريفات الموجّه بالإضافة إلى اختبارات التكامل.
• بالنسبة لكتيبات التشغيل: تهيئة النشر والتنبيهات التي تُثير الإجراء.

بمجرد تسمية هذه المصادر، تصبح التحفيزات أكثر وضوحًا: "قارن README بمخرجات CLI الحالية وافتراضات التهيئة، ثم ولِّد باتش."

اختر مخرجًا يمكن للمراجعين التحقق منه بسرعة

اتفق على صيغة إخراج قبل أن يشغّل أحد الفحص الأول. مزج الصيغ يجعل رؤية ما تغيّر ولماذا أصعب.

قواعد بسيطة:

• اطلب فرقًا لكل تغيير وثائقي، مع جملة سبب قصيرة.
• اسمح بقائمة تناقضات قصيرة فقط عندما لا يمكن للأداة اقتراح صياغة آمنة.
• حافظ على أن تُقيَّد الفرق بملف واحد في كل تغيير عندما يكون ذلك ممكنًا.
• اعتبر الأمثلة الفاشلة (أوامر، طلبات، مقتطفات شيفرة) أولوية أعلى من الصياغة العامة.

عادة عملية مفيدة: أضف ملاحظة صغيرة لكل PR وثائقي مثل "مصدر الحقيقة مُتحقق: routes + tests" حتى يعرف المراجعون ما الذي قورن. هذا يحوّل تحديثات الوثائق من "يبدو جيدًا" إلى "مُتحقق مقابل شيء حقيقي".

خطوة بخطوة: حافظ على توافق الوثائق مع الشيفرة عند كل تغيير

عامل كل تغيير في الشيفرة كتحقيق صغير في الوثائق. الهدف هو اكتشاف التناقضات مبكرًا وإنتاج باتش صغير يمكن للمراجع الوثوق به.

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

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

ثم اطلب جدول مقارنة بسيط: ادعاء الوثيقة، ما تُظهره الشيفرة، وحالة (مطابق، لا يطابق، مفقود، غير واضح). يبقي ذلك النقاش متجذرًا.

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

اختم بملخص مراجع قصير: ما الذي تغيّر، ولماذا تغيّر، وما الذي يجب إعادة التحقق منه (مثل إعادة تسمية متغير بيئة أو رأس مطلوب جديد).

توثيق API: طريقة عملية للتحقق من النقاط النهائية والأمثلة

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

مع Claude Code لانحراف التوثيق، المهمة هي إثبات ما الذي يفعله الـ API من المستودع، ثم الإشارة إلى الاختلافات في الوثائق. اطلب منه استخراج جرد من التعاريف والمعالجات (المسارات، الأساليب، نماذج الطلب والاستجابة) ومقارنة ذلك بما يدّعيه مرجع الـ API.

ركّز على ما ينسخه الناس بالفعل: أوامر curl، الرؤوس، أمثلة الحمولة، رموز الحالة، وأسماء الحقول. في تحفيز واحد، اجعله يتحقق من:

• متطلبات المصادقة (رؤوس، نوع التوكن، نقاط نهاية عامة)
• معلمات الترقيم والقيم الافتراضية
• رموز الحالة وصيغة JSON للأخطاء
• سلوك الترقيم بالإصدار (v1 مقابل v2)
• ما إذا كانت الأمثلة تطابق قواعد التحقق الحالية

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

مثال: الشيفرة الآن تُرجع 201 على POST /widgets وتضيف حقل name إلزامي. الوثائق ما تزال تعرض 200 وتتجاهل name. مخرج جيد يشير إلى كلا التناقضين ويحدّث حالة تلك النقطة النهائية فقط، ويترك الباقي كما هو.

كتيبات التشغيل: قلل الانقطاعات الناتجة عن إجراءات قديمة

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

عامل كتيب التشغيل كأنّه شيفرة: اطلب فرقًا مقابل المستودع الحالي واشترط تقارير تناقض. قارنها بما يستخدمه النظام الآن: السكربتات، افتراضات التهيئة، وأدواتك الحالية.

ركّز على نقاط الفشل التي تسبب أكثر ارتباك أثناء الحوادث:

• هل الأوامر المدرجة تطابق السكربتات والأعلام الحالية؟
• هل قيم التهيئة "الافتراضية" تطابق ما يشحن به التطبيق الآن؟
• هل متغيرات البيئة والأسرار المطلوبة مُشار إليها في الشيفرة وتهيئة النشر؟
• هل خطوات النشر والتراجع تطابق أدوات وإجراءات الإصدار الحالية؟
• هل القيم "الموثوق بها" (المنافذ، المناطق، مهلات الوقت) ما تزال صحيحة؟

أضف فحوصات سريعة ومخرجات متوقعة حتى يعرف المستجيبون أنهم على المسار الصحيح. "تحقّق أنه يعمل" غير كافٍ؛ أشِر إلى الإشارة الدقيقة المتوقعة (سطر حالة، سلسلة إصدار، أو استجابة فحص صحة).

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

أخطاء شائعة تجعل الانحراف أسوأ

أسرع طريقة لخلق انحراف في التوثيق هي معاملة الوثائق كـ "نص جميل" بدلاً من مجموعة ادعاءات يجب أن تتطابق مع الشيفرة.

أخطاء تكسر المحاذاة بهدوء

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

خطأ آخر هو ترك النموذج يخمن. إذا لم يكن سلوك مرئيًا في الشيفرة، الاختبارات، أو التهيئات، اعتبره غير معروفًا. "على الأرجح" هو كيف تُخترع وعود README وتتحول كتيبات التشغيل إلى خيال.

تظهر هذه المشاكل كثيرًا في التحديثات اليومية:

• تحديث قسم مع ترك الأمثلة ورسائل الخطأ وحالات الحافة دون تعديل
• إعادة تسمية مفهوم في مكان واحد (README) لكن ليس في توثيق API، مفاتيح التهيئة، أو كتيبات التشغيل
• تصحيح وصف نقطة نهاية لكن نسيان عينات الطلب والاستجابة
• تغيير سلوك لكن عدم تحديث الافتراضات أو ملاحظات القيود
• دمج تعديلات الوثائق دون إضافة سطر مختصر "لماذا تغيّر" في ملخص الفرق

مثال صغير

يتغير معالج من إرجاع 401 إلى 403 للحالات المنتهية الصلاحية، ويتبدل اسم الرأس من X-Token إلى Authorization. إذا كتبت فقط قسم المصادقة من جديد، قد تفوّت أن مثال الـ API لا يزال يعرض الرأس القديم، وكتيب التشغيل ما يزال يوجّه المستجيبين للبحث عن ارتفاعات 401.

عند توليد فروق، أضف سطر قرار قصير مثل: "فشل المصادقة الآن يُرجع 403 لتمييز الصلاحية غير الصحيحة عن المفقودة." هذا يمنع الشخص التالي من "إصلاح" الوثائق وإعادتها إلى السلوك القديم.

قائمة فحص سريعة قبل دمج تحديثات الوثائق

عامل كل تحديث وثائقي كمراجعة صغيرة. الهدف هو مفاجآت أقل عند محاولة شخص اتباع التعليمات لاحقًا.

خمس فحوصات تلتقط معظم الانحراف

قبل الضغط على الدمج، امسح README و API docs و runbook بحثًا عن الادعاءات الملموسة وتحقق منها واحدة تلو الأخرى:

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

قاعدة إيقاف سريعة

إذا وجدت ادعائين أو أكثر غير معروفين في نفس الوثيقة، أوقف الدمج. إما أضف دليلًا (مسارات ملفات وأسماء دوال) أو قلّص الوثيقة إلى ما هو مؤكد.

سيناريو مثال: تغيير ميزة واحدة، وانحراف في ثلاث وثائق

فريق صغير يحدّث المصادقة: بدلًا من إرسال مفتاح API في X-API-Key، يرسل العملاء توكن قصير الأمد في Authorization: Bearer <token>. تُشحن الشيفرة، تجتاز الاختبارات، ويتابع الفريق.

بعد يومين، يتبع مطور جديد التعليمات في README. لا يزال يقول "اضبط X-API-Key في بيئتك" ويعرض مثال curl بالرأس القديم. لا يتمكن من تشغيل بيئة محلية ويفترض أن الخدمة متوقفة.

في الوقت نفسه، توثيق الـ API قديم أيضًا. يصف الرأس القديم ولا يزال يعرض حقل استجابة باسم user_id، بينما تعيد الـ API الآن userId. لا خطب في الصياغة، لكنها تتناقض مع الشيفرة، فينسخ القراء الأشياء الخطأ.

ثم يحدث حادث. يتبع المسؤول كتيب التشغيل خطوة "دوّر مفتاح الـ API وأعد تشغيل العاملين". هذا لا يساعد لأن المشكلة الفعلية هي فشل تحقق التوكن بعد تغيير تهيئة. يوجه كتيب التشغيل الفريق في الاتجاه الخاطئ لعشرين دقيقة.

هنا يكون Claude Code مفيدًا حين ينتج فروقًا وتقارير تناقض، لا إعادة كتابة كاملة. يمكنك طلب مقارنة middleware المصادقة ومعالجات المسارات مع مقتطفات README، أمثلة API، وخطوات كتيب التشغيل، ثم اقتراح باتشات ضيقة:

- Header: X-API-Key: <key>
+ Header: Authorization: Bearer <token>

- { "user_id": "..." }
+ { "userId": "..." }

الجزء المهم أنه يشير إلى عدم التطابقات، يحدد الأماكن الدقيقة، ويغيّر فقط ما تثبته الشيفرة كقَدِيم.

الخطوات التالية: حول فحوصات الانحراف إلى روتين

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

عامل انحراف الوثائق كفشل اختبار، لا كمهمة كتابة. استخدم Claude Code لإنتاج فرق صغيرة وقائمة تناقضات قصيرة، ثم صحح أصغر ما يجعل الوثائق صحيحة مرة أخرى.

روتين خفيف يحافظ على الاستمرارية:

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

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

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

إذا كنت تبني بسرعة، فقد يساعد إنشاء التطبيق وجولة أولية من وثائقتِه معًا في Koder.ai (koder.ai)، ثم تصدير الشيفرة المصدرية والحفاظ على التغييرات قابلة للمراجعة في سير العمل المعتاد. الهدف ليس صياغة مثالية. الهدف هو أن تبقى الأفعال الحقيقية (الأوامر، النقاط النهائية، الخطوات) متناغمة مع ما تفعله الشيفرة فعليًا.