دليل لإنهاء مراجعة الكود سطرًا بسطر

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

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

إذًا، كيف تبدو مراجعة الكود عندما يذهب التحقق إلى الوكلاء ويبقى الحكم مع الأشخاص؟ في Aviator، نعمل على بناء هذه المراجعة ضمن Aviator Verify. فيما يلي أجزاؤها السبعة، بالترتيب.

ما هي مكونات المراجعة الموجهة بالنية؟

يتم فحص كل تغيير مقابل طبقتين. تصف معايير القبول ما يجب أن يفعله هذا التغيير. أما الثوابت (Invariants) فهي القواعد المدوّنة لمنظمتك الهندسية أو فريقك: المعايير التي تكون صحيحة دائمًا، بغض النظر عن التغيير.

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

تبني الأجزاء السبعة كلتا الطبقتين، وتتحقق من التغيير مقابلها، وتسلم القرار إلى شخص:

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

1. الثوابت

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

الثابت هو تلك القاعدة، تُكتب مرة واحدة وتُفحص في كل تغيير مطابق. معًا، تصبح ثوابتك سجلًا لعيوب الذكاء الاصطناعي، وهي القائمة المستمرة للأنماط التي يستمر فريقك في تصحيحها.

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

يحتوي سجل طلبات السحب (PR) الخاص بك بالفعل على معظمها. يقرأ Verify التعليقات التي ينشرها فريقك في GitHub ويصيغ الثوابت من الأنماط التي يجدها. كما يصيغها من CONTRIBUTING.md وملفات تعليمات الوكيل أو على الفور عندما يقوم شخص ما بوضع علامة @aviator invariant في تعليق طلب سحب أو في محادثة Slack. أنشئ ثوابت فريقك باستخدام حساب Aviator Verify المجاني واحتفظ بها حتى إذا قررت عدم الاستمرار في استخدام Verify.

تحدد ثلاثة أمور ما إذا كان الثابت يساعد أو يصبح مصدر إزعاج.

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

2. النية ومعايير القبول

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

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

يلتقط Verify كلاهما من الجلسة التي أجراها المهندس بالفعل. تعمل مهارة وكيل وخطاف على تشغيل verify submit قبل أن يفتح الوكيل طلب سحب. يستخرج الوكيل النية والمعايير من كل ما رآه في الجلسة، ويراجعها المهندس ويصححها قبل إرسال أي شيء.

3. القرارات الأساسية

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

يسجل Verify القرارات بجانب النية، مع تسمية البشر والوكلاء بشكل منفصل، حتى يعرف المراجع من اتخذ أي قرار ويمكنه مناقشته. كتب النص المزيد حول سبب كون القرارات هي الشيء الذي يجب على الأشخاص مراجعته في How to review AI code without reading the code.

4. خطة اختبار

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

هذا هو المكان الذي تؤتي فيه الطبقتان ثمارهما. يبقى المهندس مركزًا على التغيير، ويغطي السجل المعايير.

5. الأدلة

يجب أن يكون التحقق منفصلاً هيكليًا عن التوليد، ويجب أن ينتج أكثر من مجرد رأي.

يقوم Verify بإنشاء بيئة معاينة ويرسل وكلاء تحقق لتشغيل السيناريوهات.

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

6. مراجعة

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

يتغير سير عمل طلب السحب بالكاد.

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

7. الثوابت المحدّثة

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

تحتفظ الثوابت بما تعلمته كل مراجعة.

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

من أين تبدأ تطبيق هذا النهج؟

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

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

أنشئ ثوابت فريقك باستخدام حساب Aviator Verify المجاني واحتفظ بها حتى إذا قررت عدم الاستمرار في استخدام Verify.

جرّب الأداة: فاحص الفروقات بين النصوص