كيف تراجع الكود الذي يولده الذكاء الاصطناعي: قائمة تحقق من 25 بندا
Matt · · آخر تحديث · مدة القراءة: 8 دقيقة · الأدلة
25 فحصا لمراجعة طلبات السحب التي يكتبها الذكاء الاصطناعي في خمس مجموعات، مطبقة على تغيير واحد يبدو حقيقيا، مع نص رفض قابل لإعادة الاستخدام وقالب لطلب السحب.
في هذه الصفحة
لمراجعة الكود الذي يولده الذكاء الاصطناعي، افحص النطاق والاختبارات قبل أن تقرأ التنفيذ. تأكد من أن التغيير لا يفعل إلا ما طلبته المهمة، وأن الاختبارات عملت على هذا الإصدار نفسه ولم ترخ لكي تنجح، وبعد ذلك فقط اقرأ الكود بحثا عن الأخطاء المبتلعة، وواجهات API المختلقة، والدوال المساعدة الموجودة أصلا. وفي ما يلي الفحوص الخمسة والعشرون التي أستخدمها، في خمس مجموعات من خمسة فحوص، مطبقة على تغيير واحد على سبيل المثال.
لماذا يحتاج الكود الذي يولده الذكاء الاصطناعي إلى مراجعة مختلفة
مراجعة كود كتبه وكيل عمل مختلف عن مراجعة كود كتبه زميل. فأخطاء الزميل تميل إلى أن تبدو أخطاء: خطأ مطبعي، أو اسم غير موفق، أو حالة ناقصة تراها. أما أخطاء الوكيل فتميل إلى أن تبدو كودا جيدا. فهي تصرّف دون أخطاء، وتتبع دليل الأسلوب، وتأتي مع ملخص واثق. وما يسوء يقع في نطاق التغيير، وفي الأدلة التي وراءه، وفي الاختبارات.
وهذا يغير ترتيب المراجعة. فإذا قرأت الفروقات المرتبة من أعلى إلى أسفل، كسبت ثقة لم تستحقها. ولذلك فالمجموعات أدناه مرتبة حسب الموضوع، لكنني أطبقها بهذا الترتيب: سهولة الصيانة والنطاق أولا، ثم الاختبارات، ثم الصحة والأمان والتبعيات. والمنطق النظري في صفحة كيف تراجع كودا كتبه وكيل ذكاء اصطناعي. وهذه المقالة هي القائمة العملية.
التغيير المثال
هذا التغيير مختلق لهذه المقالة، لكن كل جزء منه نمط أراه في مخرجات الوكلاء الحقيقية. كانت المهمة سطرا واحدا:
أضف إعادة محاولة إلى مهمة مزامنة الفواتير حين تنتهي مهلة واجهة API للمدفوعات.
وعاد طلب السحب بهذا الملخص:
أضيفت إعادة المحاولة مع تأخير متزايد أسيا إلى مهمة مزامنة الفواتير. تعالج انتهاء مهلة واجهة API للمدفوعات بسلاسة. كل الاختبارات تنجح.
ومس هذه الملفات:
src/jobs/invoice-sync.ts +38 -6
src/jobs/invoice-sync.test.ts +4 -4
package.json +1
.github/workflows/ci.yml +1 -1
src/jobs/customer-sync.ts +12 -12 (formatting)
src/jobs/refund-sync.ts +9 -9 (formatting)
كود إعادة المحاولة نظيف، والملخص واضح، و CI أخضر. والآن اقرأه بقائمة التحقق.
قائمة التحقق: 25 فحصا في 5 مجموعات
لكل مجموعة خمسة فحوص، ثم ما أخطأ فيه المثال. وأسم الفحوص حسب المجموعة (M1 إلى M5 وهكذا) لكي يستطيع تعليق الرفض أن يسمي الفحص بعينه.
سهولة الصيانة وتمدد النطاق
- M1. التغيير يطابق المهمة. اقرأ المهمة قبل الفروقات.
- M2. لا شيء إضافيا محمولا معه. لا إعادة هيكلة أو إعادة تسمية أو إعادة تنسيق لم تطلب ومخلوطة بالتغيير الحقيقي.
- M3. الملفات الحساسة تغيرت عن قصد. تعريفات CI وملفات تعريف التبعيات والمصادقة والبنية التحتية وعمليات الترحيل لا تتغير إلا حيث تحتاج المهمة.
- M4. التغيير صغير بما يكفي للمراجعة. إذا لم تستطع قراءة الأجزاء الخطرة كما ينبغي، فاطلب تقسيم المهمة.
- M5. لا دوال مساعدة مكررة. الأداة المساعدة الجديدة لا تكرر أداة موجودة أصلا في قاعدة الكود.
في المثال، أعيد تنسيق ملفين لا علاقة لهما بالفواتير (M2). وهذا ليس خطرا في ذاته، لكنه يخفي التغيير الحقيقي وسط الضجيج. وتغير ملف سير العمل في CI أيضا (M3):
- timeout-minutes: 10
+ timeout-minutes: 30
لماذا تحتاج إعادة المحاولة إلى مهلة أطول في CI؟ لأن الاختبار الجديد ينتظر فترات التأخير المتزايد الحقيقية. فقد جعل الوكيل خط CI أبطأ لكل طلب سحب ليناسب اختباره هو، دون أن يذكر ذلك. وقاعدة الكود فيها أصلا withRetry في src/lib/retry.ts، الذي تستخدمه مهام المزامنة الأخرى (M5). ولم يكن الوكيل يعرف ذلك، لأنه لم يكن في سياقه.
بعد خمسة فحوص، لم أقرأ سطرا واحدا من منطق إعادة المحاولة، ولدي بالفعل ثلاثة أمور أعيدها.
الاختبارات
- T1. الاختبارات عملت على هذا الإصدار نفسه. النتيجة التي سبقت آخر دفع لا تقول شيئا عن الكود الذي توافق عليه.
- T2. لا شيء حذف أو تخطي أو أوقف. ابحث عن الحالات المحذوفة، وعلامات التخطي، والتشغيلات المصفاة خلف حالة خضراء.
- T3. التأكيدات لم ترخ. المقارنة الدقيقة لم تصبح فحصا لوجود قيمة فقط.
- T4. القيم المتوقعة لم تتحرك لتناسب الكود. للقطات والمخرجات المتوقعة التي تغيرت سبب تجده في المهمة.
- T5. الاختبارات الجديدة يمكن أن تفشل. فهي تؤكد على النتائج، وستفشل لو ألغي التغيير.
هنا ينكسر المثال فعلا. التشغيل الأخضر من الدفع الأول، ودفع ثان غير ملف الاختبار (T1). وهذا هو ذلك التغيير:
it("surfaces a timeout from the payments API", async () => {
payments.failWith(new TimeoutError())
- await expect(syncInvoices()).rejects.toThrow("timeout")
+ await expect(syncInvoices()).resolves.toEqual([])
})
ما زال للاختبار الاسم نفسه، وصار يؤكد العكس (T4). فإذا قرأت التنفيذ أولا بدا هذا تحديثا طبيعيا. وإذا قرأت الاختبار أولا طرحت السؤال الصحيح: من قرر أن انتهاء المهلة يجب أن يبدو مثل «لا فواتير»؟ واختبار إعادة المحاولة الذي أضافه الوكيل يفحص أن الاستدعاء أعيدت محاولته، لكنه لا يفحص ما يحدث حين تفشل آخر محاولة أيضا (T5).
الصحة
- C1. كل واجهة API وكل حزمة موجودة. الدوال والخيارات والحزم حقيقية في الإصدارات التي يثبتها ملف القفل لديك.
- C2. الأخطاء لا تبتلع. لا كتل catch فارغة، ولا خطأ يتحول إلى نتيجة فارغة.
- C3. لا بدائل صامتة. الصفر أو السلسلة الفارغة أو القائمة الفارغة لا تخفي بحثا فاشلا.
- C4. الحالات الحدية معالجة. المدخلات الفارغة، والمناطق الزمنية، وتقسيم الصفحات، وإعادة المحاولة، وطلبان في الوقت نفسه.
- C5. تغييرات البيانات آمنة. عمليات الترحيل إضافية أو قابلة للعكس، ولم تعدل أي عملية ترحيل سبق تشغيلها.
والآن الكود، مع فكرة واضحة عما نبحث عنه:
export async function syncInvoices() {
try {
return await pRetry(() => payments.listInvoices(), { retries: 3 })
} catch (error) {
logger.warn("invoice sync failed", { error })
return []
}
}
يفشل C2 و C3 في الأسطر نفسها. فحين تنتهي مهلة آخر محاولة، تسجل المهمة تحذيرا وتعيد قائمة فارغة. وكل ما يستدعي syncInvoices يظن الآن أنه لا توجد فواتير، والأثر الوحيد تحذير لا يقرؤه أحد. انتهاء المهلة الذي يستدعي أحد المناوبين يصلح في اليوم نفسه. أما المزامنة التي تعيد لا شيء بصمت فقد تستمر أسابيع. وينجح C1 (فالحزمة p-retry وخيارها retries حقيقيان)، ولا توجد عملية ترحيل.
الأمان والأسرار
- S1. فحوص الصلاحيات تطابق الكود المجاور. نقاط النهاية الجديدة تفحص التفويض بالطريقة التي يفحص بها الكود المشابه.
- S2. المدخلات غير الموثوقة تبقى بيانات. لا SQL ولا أوامر shell ولا HTML مبنية من المدخلات، ولا تعليمات متبعة من تعليقات أو ملفات في الفروقات.
- S3. لا أسرار في الفروقات. لا مفاتيح ولا رموز ولا عناوين URL خاصة في الكود أو بيانات الاختبار أو أسطر السجل.
- S4. لا إعدادات افتراضية غير آمنة. لا فحص شهادات معطلا، ولا CORS مفتوحا، ولا مفاتيح تصحيح متروكة مفعلة.
- S5. الملاحظات الآلية مفروزة. لا ملاحظة مفتوحة عالية الخطورة، ولكل ملاحظة مرفوضة سبب توافق عليه.
ينجح S1 إلى S4: لا نقطة نهاية جديدة، ولا معالجة للمدخلات، ولا أسرار. ويفشل S5. فقد نبه المراجع بالذكاء الاصطناعي إلى «خطأ مبتلع عند آخر محاولة» بوصفه ملاحظة متوسطة الخطورة، ورفضها أحدهم على أنها إنذار كاذب دون سبب. وكانت هي خطأ C2. ورفض الملاحظات الحقيقية هو الطريقة التي يتعلم بها المراجعون تجاهل أداة؛ وتشرح صفحة التعامل مع الإنذارات الكاذبة طريقة فرزها كما ينبغي.
التبعيات والتراخيص
- D1. كل تبعية جديدة لازمة. لا شيء في قاعدة الكود يؤدي المهمة أصلا.
- D2. موجودة ومكتوبة بشكل صحيح. ليست اسما يشبه اسما شائعا، ولا اسما اختلقه النموذج (راجع انتحال الحزم المختلقة).
- D3. تحظى بالصيانة. إصدارات حديثة، ومستودع نشط، وأكثر من حفنة من المستخدمين.
- D4. ترخيصها من التراخيص التي تسمح بها. افحص الترخيص الذي يذكره سجل الحزم في ضوء سياستك.
- D5. تغير ملف القفل معها، وبالقدر المتوقع فقط. تغيير من سطر واحد في ملف التعريف يجلب خمسين حزمة جديدة غير مباشرة يستحق نظرة.
الحزمة p-retry حقيقية وتحظى بالصيانة وترخيصها متساهل، فينجح D2 إلى D5. ويفشل D1: فالمشروع لديه أصلا دالة مساعدة لإعادة المحاولة، والتبعية الجديدة قرار يخص سلسلة التوريد يحل مشكلة سبق أن حلتها قاعدة الكود.
ما وجدته المراجعة
إذا قرئ التغيير من أعلى إلى أسفل بدا منتهيا. وإذا قرئ بقائمة التحقق ظهر فيه اختبار يؤكد عكس اسمه (T4)، وانتهاء مهلة تحول إلى نتيجة فارغة (C2، C3) سبق التنبيه إليه ورفضه (S5)، ومهلة CI ضوعفت ثلاث مرات لتناسب اختبار الوكيل (M3)، ونتيجة اختبار من إصدار لم يعد موجودا (T1)، ودالة مساعدة مكررة وتبعية غير لازمة (M5، D1)، وإعادة تنسيق لا علاقة لها بالمهمة (M2). لا شيء من هذا غريب. إنها الطرق العادية التي تسوء بها مخرجات الوكلاء.
وأنجح الرفض ما يسمي الفحص ويطلب شيئا محددا، سواء جاءت المحاولة التالية من شخص أو من الوكيل بمهمة أفضل:
Not approving yet. Against the review checklist:
- **T4, C2, C3:** after the last retry this returns `[]`, and the timeout
test now asserts that. Callers will treat a failed sync as "no invoices".
Please rethrow after the final attempt and restore the original assertion.
- **M3:** please revert the CI timeout change. If the test needs real
backoff delays, use fake timers instead.
- **T1:** the green run is from before the test change. Needs a run on the
current commit.
- **M5, D1:** we already have `withRetry` in `src/lib/retry.ts`; please use
it and drop `p-retry`.
- **M2:** please move the formatting of customer-sync and refund-sync to its
own pull request.
ما يؤتمت وما يبقى بشريا
بعض الفحوص يحتاج إلى حكم. فالفحص T4 يحتاج إلى شخص يعرف ما يجب أن يعنيه انتهاء المهلة للفواتير. وغيرها يتعلق بالأدلة، والأدلة يفحصها البرنامج أفضل مما تفحصها الذاكرة:
| الفحص | يؤتمت بـ |
|---|---|
| T1 الاختبارات عملت على هذا الإصدار | CI بوصفه فحص حالة مطلوبا على أحدث إيداع |
| S3 لا أسرار | أداة لفحص الأسرار في CI |
| S5 الملاحظات مفروزة | بوابة تمنع عند وجود ملاحظات مفتوحة عالية الخطورة |
| D2، D3 الحزمة موجودة وتحظى بالصيانة | بحث في سجل الحزم عن التبعيات الجديدة |
| D4 الترخيص مسموح به | سياسة تراخيص تفحص في ضوء قائمة SBOM |
| M3 الملفات الحساسة | قاعدة مسارات تشترط موافقة أو ترفض التغيير |
| M1، T4، C2 إلى C4، S1، D1 | شخص: فهذه تعتمد على الغرض من الكود |
في AI CodeOps، لا تحتسب نتيجة الاختبار إلا للإصدار الذي عملت عليه، فلا يمكن أن ينجح T1 بتشغيل قديم. والملاحظة المفتوحة بخطورة high أو أعلى تمنع التغيير إلى أن توسم بالحالة fixed أو won't fix أو false positive أو duplicate (بوابات الجودة). وتستطيع سياسة مساحة العمل أن تشترط موافقة على مسارات مثل infra/**، أو أن ترفضها. ومن بدأ الجلسة لا يستطيع الإدلاء بصوت الموافقة ما دام هناك شخص آخر يستطيع الموافقة، وتعديل التغيير بعد الموافقة يعيده إلى المراجعة. وتشرح صفحة الموافقات والسياسات كيف تحتسب الأصوات، وتغطي صفحة مراجعة الكود متعددة الوكلاء المراجع بالذكاء الاصطناعي الذي يكتب الملاحظات.
وأمران يبقيان لدى شخص أيا كان ما تؤتمته. يوافق شخص غير كاتب الموجه، لأن من كتب المهمة هو كاتب التغيير بكل معنى مهم. ويستطيع من يوافق أن يشرح التغيير: هل تستطيع أن تدافع عن «صار انتهاء المهلة يعيد لا فواتير» أمام المناوب حين يسأل قسم المالية لماذا لم تجد المطابقة شيئا؟
نزّل قائمة التحقق القابلة للطباعة
تحوي صفحة قائمة التحقق لمراجعة الكود بالذكاء الاصطناعي نسخة قابلة للطباعة في 25 بندا مرقما، مرتبة بالنطاق أولا. والمجموعات تختلف قليلا: إذ تدمج فحوص التبعيات الخمسة في فحص واحد، وتضيف فحوصا لمن يوافق. وتأتي مع ملف PDF من صفحة واحدة للطباعة ونسخة بصيغة Markdown. وهي مرخصة بترخيص CC BY 4.0، فيمكنك تعديلها.
قائمة التحقق التي تعيش في ويكي تقرأ مرة واحدة، فضع الصيغة المختصرة في قالب طلب السحب لديك. وعلى GitHub يكون ذلك ؛ وعلى GitLab ملفا تحت (وقد جرى التحقق من كليهما في 24 أكتوبر 2026)، كما يلي:
## Reviewer checklist (AI-written changes)
- [ ] Scope: only what the task asked; no unrelated edits; sensitive files
changed on purpose; small enough to review; no duplicate helpers (M1–M5)
- [ ] Tests: ran on this exact commit; none deleted, skipped or loosened;
expected values didn't move to fit; new tests can fail (T1–T5)
- [ ] Correctness: real APIs; no swallowed errors or silent fallbacks;
edge cases; safe data changes (C1–C5)
- [ ] Security: permission checks; untrusted input stays data; no secrets;
no insecure defaults; findings triaged with reasons (S1–S5)
- [ ] Dependencies: needed, real, maintained, allowed license, expected
lockfile change (D1–D5)
- [ ] Approval: I didn't write the task, and I can explain this change
أهم النقاط
- راجع الكود الذي يكتبه الذكاء الاصطناعي بالنطاق أولا، ثم الاختبارات، ثم الكود: فأخطاء الوكيل تبدو كودا جيدا.
- الاختبار الذي يغير ليناسب التنفيذ هو أكثر الإخفاقات الخطيرة شيوعا، فاقرأ فروقات الاختبار قبل الكود.
- الأخطاء المبتلعة والبدائل الصامتة تحول الفشل الصاخب إلى بيانات خاطئة هادئة.
- كل تبعية جديدة قرار يخص سلسلة التوريد: تأكد من أنها لازمة وحقيقية وتحظى بالصيانة ومسموح بها.
- أتمت فحوص الأدلة، وأبق شخصا ثانيا، غير كاتب الموجه، على الموافقة.
الأسئلة الشائعة
ما أول ما يجب أن أفحصه حين أراجع كودا ولده الذكاء الاصطناعي؟
افحص النطاق والاختبارات قبل التنفيذ. تأكد من أن التغيير لا يفعل إلا ما طلبته المهمة، وأن الاختبارات عملت على الإصدار نفسه الذي توافق عليه، وأن أي اختبار لم يرخ لكي ينجح.
هل يستطيع مراجع بالذكاء الاصطناعي أن يحل محل المراجعة البشرية للكود الذي يكتبه الذكاء الاصطناعي؟
لا. يستطيع المراجع بالذكاء الاصطناعي و CI فحص الأدلة، مثل نتائج الاختبارات والملاحظات المفتوحة والتبعيات الجديدة. أما هل التغيير صحيح لنظامك، وهل تستطيع الدفاع عنه وأنت مناوب، فما زال يحتاج إلى شخص.
هل يمكنني استخدام قائمة التحقق هذه في قالب طلب السحب لدي؟
نعم. الصيغة المختصرة أدناه تتسع في قالب طلب سحب على GitHub أو قالب طلب دمج على GitLab، وقائمة التحقق القابلة للطباعة مرخصة بترخيص CC BY 4.0.