26 ديسمبر 2025·6 دقيقة
Claude Code لانحراف التوثيق: حافظ على توافق الوثائق مع الشيفرة
تعلم استخدام Claude Code لاكتشاف انحراف التوثيق ومزامنة README، مستندات API، وكتيبات التشغيل مع الشيفرة عبر توليد فروق والإشارة إلى التناقضات.
تعلم استخدام Claude Code لاكتشاف انحراف التوثيق ومزامنة README، مستندات API، وكتيبات التشغيل مع الشيفرة عبر توليد فروق والإشارة إلى التناقضات.
انحراف التوثيق هو الفصل التدريجي بين ما تقوله وثائقك وما تفعله الشيفرة بالفعل. يبدأ كمطابقات صغيرة، ثم يتحول إلى ارتباك من نوع "نحن نقسم أنه عمل الشهر الماضي".
على فريق حقيقي، يظهر الانحراف بهذه الصورة: README يقول إنك تستطيع تشغيل خدمة بأمر واحد، لكن الآن مطلوب متغير بيئة جديد. توثيق الـ API يظهر نقطة نهائية بحقل تم إعادة تسميته. كتيب التشغيل يخبر المُستجيب بإعادة تشغيل "worker-a"، لكن العملية الآن مقسمة إلى خدمتين.
يحدث الانحراف حتى مع النوايا الحسنة لأن الشيفرة تتغير أسرع من عادات التوثيق. يطلق الناس إصلاحات تحت الضغط، ينسخون أمثلة قديمة، أو يفترضون أن شخصًا آخر سيحدّث الوثائق لاحقًا. كما ينمو الانحراف عندما توجد أماكن كثيرة تُشبه "مصدر الحقيقة": ملفات README، مراجع API، صفحات ويكي داخلية، تذاكر، ومعرفة قبلية.
التكاليف ملموسة:
تحسين الصياغة لا يصلح الانحراف إذا كانت الحقائق خاطئة. ما يساعد هو معاملة الوثائق كأمر قابل للتحقق: قارنها بالشيفرة الحالية، والتهيئات، والمخرجات الحقيقية، ثم أشر إلى التناقضات حيث تعد الوثائق بسلوك لم تعد الشيفرة تقوم به.
عادةً ما يظهر الانحراف في المستندات التي يعاملها الناس كـ "مرجع سريع". يتم تحديثها مرة واحدة، ثم تستمر الشيفرة في التحرك. ابدأ بهذه الثلاثة لأنها تحتوي وعودًا محددة يمكنك التحقق منها.
تنزلق README عندما تتغير الأوامر اليومية. يُضاف علم جديد، يُحذف آخر، أو يُعاد تسمية متغير بيئة، لكن قسم الإعداد ما يزال يعرض الواقع القديم. زملاء العمل ينسخون الأمثلة ويلصقونها، يواجهون أخطاء، ويفترضون أن المشروع معطل.
أسوأ نسخة هي "تقريبًا صحيحة". متغير بيئة واحد مفقود يمكن أن يضيع وقتًا أكثر من README قديم تمامًا، لأن الناس يستمرون في تجربة تباينات صغيرة بدلًا من التشكيك في الوثيقة.
يتحرف توثيق API عندما تتغير حقول الطلب أو الاستجابة. حتى التحولات الصغيرة (إعادة تسمية مفاتيح، افتراضات افتراضية مختلفة، رؤوس مطلوبة جديدة) يمكن أن تكسر العملاء. غالبًا ما تكون قائمة النقاط النهائية صحيحة بينما تكون الأمثلة خاطئة، وهذا بالضبط ما ينسخه المستخدمون.
إشارات نموذجية:
تنزلق كتيبات التشغيل عندما تتغير خطوات النشر أو التراجع أو التشغيلية. أمر واحد قديم، اسم خدمة خاطئ، أو شرط سابق مفقود يمكن أن يحول إصلاحًا روتينيًا إلى وقت توقف.
يمكن أن تكون دقيقة لكن غير مكتملة: الخطوات لا تزال تعمل، لكنها تتخطى هجرة جديدة، مسح ذاكرة مخبّأة، أو تبديل علم ميزة. عندها يتبع المستجيبون كتيب التشغيل تمامًا ويظلّون مندهشين.
Claude Code للتحقق من انحراف التوثيق يعمل بشكل أفضل عندما تعامل الوثائق كأنها شيفرة: اقترح تصحيحًا صغيرًا قابلًا للمراجعة واشرح السبب. بدلًا من طلب "تحديث README"، اطلب توليد فرق مقارنة لملفات محددة. يحصل المراجعون على عرض قبل/بعد واضح ويمكنهم اكتشاف تغييرات غير مقصودة بسرعة.
فحص الانحراف الجيد ينتج شيئين:
عند التحفيز، اشترط دليلًا من المستودع: مسارات الملفات وتفاصيل مثل المسارات، قيم التهيئة، أو اختبارات تُظهر السلوك الحالي.
إليك نموذج تحفيز يبقي الأمور متجذرة:
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 الحالية وافتراضات التهيئة، ثم ولِّد باتش."
اتفق على صيغة إخراج قبل أن يشغّل أحد الفحص الأول. مزج الصيغ يجعل رؤية ما تغيّر ولماذا أصعب.
قواعد بسيطة:
عادة عملية مفيدة: أضف ملاحظة صغيرة لكل PR وثائقي مثل "مصدر الحقيقة مُتحقق: routes + tests" حتى يعرف المراجعون ما الذي قورن. هذا يحوّل تحديثات الوثائق من "يبدو جيدًا" إلى "مُتحقق مقابل شيء حقيقي".
عامل كل تغيير في الشيفرة كتحقيق صغير في الوثائق. الهدف هو اكتشاف التناقضات مبكرًا وإنتاج باتش صغير يمكن للمراجع الوثوق به.
ابدأ باختيار الملفات الدقيقة للتحقق وسؤال انحراف واضح. على سبيل المثال: "هل غيرنا أي متغيرات بيئة، أعلام CLI، مسارات HTTP، أو رموز خطأ التي لا تزال الوثائق تذكرها؟" كونك محددًا يمنع النموذج من إعادة كتابة أقسام كاملة.
بعد ذلك، اطلب من Claude Code استخراج حقائق صارمة من الشيفرة أولًا. اجعله يسرد عناصر ملموسة فقط: الأوامر التي يشغلها المستخدمون، النقاط النهائية والطرق، حقول الطلب والاستجابة، مفاتيح التهيئة، متغيرات البيئة المطلوبة، وخطوات تشغيلية المشار إليها بواسطة سكربتات أو تهيئات. إذا لم يُعثر على شيء في الشيفرة، يجب أن يقول "لم يُعثر" بدلًا من التخمين.
ثم اطلب جدول مقارنة بسيط: ادعاء الوثيقة، ما تُظهره الشيفرة، وحالة (مطابق، لا يطابق، مفقود، غير واضح). يبقي ذلك النقاش متجذرًا.
بعد ذلك، اطلب فرقًا موحّدًا بأصغر التعديلات. قل له أن يغيّر فقط الأسطر اللازمة لحل الاختلافات، ويحافظ على أسلوب الوثيقة الحالي، ويتجنب إضافة وعود لا تدعمها الشيفرة.
اختم بملخص مراجع قصير: ما الذي تغيّر، ولماذا تغيّر، وما الذي يجب إعادة التحقق منه (مثل إعادة تسمية متغير بيئة أو رأس مطلوب جديد).
ينحرف توثيق API عندما تتغير الشيفرة بهدوء: تُعاد تسمية مسار، يصبح حقل إلزاميًا، أو يتغير شكل الخطأ. النتيجة هي تعطل تكامل العملاء ووقت debugging ضائع.
مع Claude Code لانحراف التوثيق، المهمة هي إثبات ما الذي يفعله الـ API من المستودع، ثم الإشارة إلى الاختلافات في الوثائق. اطلب منه استخراج جرد من التعاريف والمعالجات (المسارات، الأساليب، نماذج الطلب والاستجابة) ومقارنة ذلك بما يدّعيه مرجع الـ API.
ركّز على ما ينسخه الناس بالفعل: أوامر curl، الرؤوس، أمثلة الحمولة، رموز الحالة، وأسماء الحقول. في تحفيز واحد، اجعله يتحقق من:
عندما يجد عدم تطابق، اقبل فقط الفروق التي يمكنه الاستدلال عليها من الشيفرة (تعريف المسار بالضبط، سلوك المعالج، أو المخطط). هذا يجعل الباتشات صغيرة وقابلة للمراجعة.
مثال: الشيفرة الآن تُرجع 201 على POST /widgets وتضيف حقل name إلزامي. الوثائق ما تزال تعرض 200 وتتجاهل name. مخرج جيد يشير إلى كلا التناقضين ويحدّث حالة تلك النقطة النهائية فقط، ويترك الباقي كما هو.
تفشل كتيبات التشغيل بالطريقة الأكثر تكلفة: تبدو كاملة، لكن الخطوات لم تعد تطابق ما يفعله النظام اليوم. تغيير صغير مثل إعادة تسمية متغير بيئة أو أمر نشر جديد يمكن أن يطيل الحادث لأن المستجيبين يتبعون تعليمات لا تعمل.
عامل كتيب التشغيل كأنّه شيفرة: اطلب فرقًا مقابل المستودع الحالي واشترط تقارير تناقض. قارنها بما يستخدمه النظام الآن: السكربتات، افتراضات التهيئة، وأدواتك الحالية.
ركّز على نقاط الفشل التي تسبب أكثر ارتباك أثناء الحوادث:
أضف فحوصات سريعة ومخرجات متوقعة حتى يعرف المستجيبون أنهم على المسار الصحيح. "تحقّق أنه يعمل" غير كافٍ؛ أشِر إلى الإشارة الدقيقة المتوقعة (سطر حالة، سلسلة إصدار، أو استجابة فحص صحة).
إذا تبنيت ونشرت تطبيقات على منصات مثل Koder.ai، فهذا يصبح أكثر أهمية لأن اللقطات والتراجع مفيدة فقط عندما يسمي كتيب التشغيل الإجراء الصحيح ويعكس مسار الاسترداد الحالي.
أسرع طريقة لخلق انحراف في التوثيق هي معاملة الوثائق كـ "نص جميل" بدلاً من مجموعة ادعاءات يجب أن تتطابق مع الشيفرة.
خطوة شائعة خاطئة هي طلب إعادة صياغة أولًا. عندما تتخطى فحص التناقض، قد ينتهي بك الأمر بصياغة أنعم لا تزال تصف السلوك الخاطئ. ابدأ دائمًا بالسؤال ما الذي تدّعيه الوثائق، ماذا تفعل الشيفرة، وأين يختلفان.
خطأ آخر هو ترك النموذج يخمن. إذا لم يكن سلوك مرئيًا في الشيفرة، الاختبارات، أو التهيئات، اعتبره غير معروفًا. "على الأرجح" هو كيف تُخترع وعود README وتتحول كتيبات التشغيل إلى خيال.
تظهر هذه المشاكل كثيرًا في التحديثات اليومية:
يتغير معالج من إرجاع 401 إلى 403 للحالات المنتهية الصلاحية، ويتبدل اسم الرأس من X-Token إلى Authorization. إذا كتبت فقط قسم المصادقة من جديد، قد تفوّت أن مثال الـ API لا يزال يعرض الرأس القديم، وكتيب التشغيل ما يزال يوجّه المستجيبين للبحث عن ارتفاعات 401.
عند توليد فروق، أضف سطر قرار قصير مثل: "فشل المصادقة الآن يُرجع 403 لتمييز الصلاحية غير الصحيحة عن المفقودة." هذا يمنع الشخص التالي من "إصلاح" الوثائق وإعادتها إلى السلوك القديم.
عامل كل تحديث وثائقي كمراجعة صغيرة. الهدف هو مفاجآت أقل عند محاولة شخص اتباع التعليمات لاحقًا.
قبل الضغط على الدمج، امسح README و API docs و runbook بحثًا عن الادعاءات الملموسة وتحقق منها واحدة تلو الأخرى:
إذا وجدت ادعائين أو أكثر غير معروفين في نفس الوثيقة، أوقف الدمج. إما أضف دليلًا (مسارات ملفات وأسماء دوال) أو قلّص الوثيقة إلى ما هو مؤكد.
فريق صغير يحدّث المصادقة: بدلًا من إرسال مفتاح 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 لإنتاج فرق صغيرة وقائمة تناقضات قصيرة، ثم صحح أصغر ما يجعل الوثائق صحيحة مرة أخرى.
روتين خفيف يحافظ على الاستمرارية:
اجعل ملخصات الفرق تلك سهلة العثور لاحقًا. سطر قصير مثل "الوثائق محدثة لمطابقة /v2، أُزيل الرأس المُهمل، حدّثت استجابة المثال" يساعد عندما يسأل أحدهم بعد أشهر لماذا تغيّر ملف ما.
طبق فكرية "اللقطات والتراجع" على الوثائق أيضًا. إذا كانت تعليمات غير مؤكدة، غيّرها في مكان واحد، تحقق سريعًا، ثم انسخ النسخة المؤكدة إلى أماكن أخرى.
إذا كنت تبني بسرعة، فقد يساعد إنشاء التطبيق وجولة أولية من وثائقتِه معًا في Koder.ai (koder.ai)، ثم تصدير الشيفرة المصدرية والحفاظ على التغييرات قابلة للمراجعة في سير العمل المعتاد. الهدف ليس صياغة مثالية. الهدف هو أن تبقى الأفعال الحقيقية (الأوامر، النقاط النهائية، الخطوات) متناغمة مع ما تفعله الشيفرة فعليًا.
انحراف التوثيق هو عندما تتوقف وثائقك تدريجيًا عن مطابقة ما تفعله الشيفرة فعليًا. يبدأ عادةً بتغييرات صغيرة (مثل إعادة تسمية متغير بيئة، أو جعل حقل إلزامي، أو تغيير رمز حالة) لا تنعكس في README أو أمثلة API أو كتيبات التشغيل.
لأن الشيفرة تتغير تحت ضغط العمل والوثائق لا تحظى بنفس مستوى الحزم أو المراجعة.
الأسباب الشائعة:
ابدأ بالوثائق التي ينفّذها الناس فعليًا، لا تلك "الجميلة" فقط. ترتيب عملي:
إصلاح هذه أولًا يزيل أغلب الفشل عالي التكلفة.
لأن إعادة صياغة النص لا تضمن صحة الحقائق. الانحراف يتعلق بشكل أساسي بـ الادعاءات الخاطئة.
نهج أفضل هو اعتبار الوثائق كبيانات قابلة للاختبار: "شغّل هذا الأمر"، "استدعِ هذا النقطة النهائية"، "ضبط هذا المتغير"، ثم تحقق من هذه الادعاءات مقابل المستودع الحالي، والتهيئات، والمخرجات الحقيقية.
اطلب مخرجين:
اشترط: إذا لم يجد دليلًا في المستودع، يجب أن يقول "لم يُعثر" بدلًا من التخمين.
لأن المراجعين يمكنهم التحقق السريع من الفرق. الفرق تُظهر بالضبط ما الذي تغيّر، وتمنع إعادة الصياغات "المساعدة" التي قد تضيف وعودًا جديدة.
قواعد عملية: ملف واحد لكل فرق عندما يكون ممكنًا، ولكل تغيير جملة سبب قصيرة مرتبطة بدليل المستودع.
اشترط الاستشهاد بالدليل.
قواعد عملية:
راجع ما ينسخ الناس ولصقه:
إذا كانت قائمة النقاط النهائية صحيحة لكن الأمثلة خاطئة، سيظل المستخدمون يفشلون—لذلك اعتبر الأمثلة أولوية عالية.
تتزعزع كتيبات التشغيل عندما تتغير الواقعية التشغيلية.
فحوصات عالية الأثر:
إذا لم يستطع المستجيبون التحقق من التقدّم، سيهدرون وقتًا أثناء الحوادث.
استخدم قاعدة "مصدر الحقيقة" بسيطة لكل نوع وثيقة:
ادمج ذلك في سير العمل: شغّل فحوصات الانحراف على الوثائق المتأثرة في كل PR، واحتفظ بالتعديلات صغيرة وقابلة للمراجعة.