المشروع الختامي العملي: إضافة ميزة لأداة TODO مصغرة من الصفر وتقديم أول commit
📚 التنقل في السلسلة: شرحت المقالة السابقة 〔33 نقاط استخدام Windows الأساسية〕 وحلت المشاكل التي قد تعيق العمل على نظام Windows مثل المسارات والسطور الجديدة والطرفية وفروق الـ sandbox خطوة بخطوة. لن نتحدث في هذه المقالة عن ميزات جديدة، بل سنقوم بأمر أكثر إثارة: تجميع كل الأجزاء التي تعلمناها في المقالات الثلاثين السابقة لتشغيل آلة متكاملة حقيقية. وتلخص المقالة التالية 〔35 دليل الأوامر والتكوين السريع〕 جميع الأوامر ومفاتيح التكوين المستخدمة في جدول واحد ليكون مرجعًا لك في أي وقت.
أيها الأصدقاء، اليوم ليس درسًا نظريًا، بل سنقوم ببناء شيء مصغر معًا من الصفر.
لدينا أداة بسيطة للغاية لسطر الأوامر — ملف todo.py مكتوب بلغة Python، ويوفر ميزتين فقط: إضافة المهام واستعراضها. وتظهر فيه مشكلة واضحة: المهام التي تتم إضافتها لا يمكن حذفها بعد الانتهاء منها، وتظل قائمة المهام تتراكم وتطول. وسنقوم في هذه المقالة بإضافة ميزة «حذف المهام»، بدءًا من توضيح خلفية المشروع وتفويض المهمة وتحديد الصلاحيات، ووصولاً للتحقق الذاتي وإجراء الـ git commit، لـ نمر بدورة العمل كاملة.
ببساطة، ركزت كل مقالة سابقة على «كيفية استخدام جزء معين» — طريقة كتابة AGENTS.md، أو صياغة الطلبات، أو إعداد الصلاحيات، أو تفويض مهام git. فهم كل جزء على حدة سهل، ولكن عند البدء في عمل حقيقي، قد يشعر الكثيرون بالحيرة حول كيفية ترتيب هذه الأجزاء وربطها معًا. هذه المقالة هي «المخطط الهيكلي للتجميع».
لا نفترض وجود هذا المشروع على جهازك بالفعل. حيث سنقوم في القسم 01 ببناء ملف todo.py خلال دقيقتين، وبعدها يمكنك اتباع الخطوات وتطبيقها معي لرؤية النتائج مباشرة. هذه مقالة للتطبيق العملي وليست مجرد قراءة وفهم — فالقراءة دون تطبيق لا تغني عن التجربة.
بعد قراءة هذه المقالة، ستحصل على:
- دورة تطوير كاملة من الصفر وحتى الـ commit، ترتبط كل خطوة فيها بمقالة سابقة لتصبح جزءًا من ذاكرتك العضلية
- نسخة قابلة للتطبيق من ملف
AGENTS.mdوطلب تفويض كامل للمهمة، مع الأوامر الحقيقية والمخرجات المتوقعة - أسلوب عملي لتوجيه «Codex لتشغيل الاختبارات والتحقق من العمل بنفسه، وعدم التوقف حتى ينجح بالكامل»
- كيفية تفويض عملية الـ
gitcommit لـ Codex مع قيامك أنت بالمراجعة والاعتماد النهائي - جدول مقارنة يوضح «المقالة التي تدعم كل خطوة في دورة العمل الحالية»، لتطبيقه في أي مشروع مستقبلي
⚠️ تعتمد الأوامر والمعلمات والسلوك الافتراضي لاحقًا على مستندات Codex الرسمية؛ وتعتمد أسماء النماذج وواجهة المستخدم على ما يظهر في
codex --helpوالطرفية المحلية لديك، ولا نكتب قيمًا ثابتة في هذا الشرح.
01 إعداد الهدف أولاً: بناء أداة TODO مصغرة في دقيقتين
يجب أن يكون لدينا كود للعمل عليه قبل البدء. سنقوم أولاً بإنشاء هذا المشروع يدويًا — لتدور حوله جميع العمليات اللاحقة.
تشبيه: يشبه هذا إعداد شقة خام قبل البدء في الديكور. دون وجود الجدران، لا يمكن تطبيق أي مخطط تصميم. يمثل ملف todo.py هذا الشقة الخام لدينا، وهو بسيط للغاية ويمكن قراءته في لمحة، ولكنه يحتوي على الأساسيات — البيانات، الوظائف، والمدخل، وهو كافٍ لإضافة وظيفة جديدة (ميزة الحذف).
اختر مجلدًا فارغًا، وأنشئ ملفًا باسم todo.py بالوظائف التالية (يعمل بنفس الطريقة على Mac / Linux / Windows، ويتطلب بيئة Python 3 فقط):
# todo.py
import sys
TODOS = []
def add(item):
TODOS.append(item)
print(f"已添加：{item}")
def list_todos():
if not TODOS:
print("（暂无待办）")
return
for i, item in enumerate(TODOS, 1):
print(f"{i}. {item}")
def main():
if len(sys.argv) < 2:
print("用法：python todo.py [add <内容> | list]")
return
cmd = sys.argv[1]
if cmd == "add":
add(" ".join(sys.argv[2:]))
elif cmd == "list":
list_todos()
else:
print(f"未知命令：{cmd}")
if __name__ == "__main__":
main()بعد إنشاء الملف، شغله للتأكد من أنه يعمل بشكل صحيح:
python todo.py add 买咖啡豆
python todo.py listالمخرجات المتوقعة:
已添加：买咖啡豆
（暂无待办）(Note: we keep the Chinese log output unchanged because it is within code blocks).
لاحظ وجود «طبيعة عمل» هامة هنا — نظرًا لأن كل تشغيل يمثل عملية مستقلة، يتم تفريغ قائمة TODOS في الذاكرة بمجرد انتهاء تشغيل الكود، لذا يظهر الـ list فارغًا عند تشغيله بشكل منفصل. هذا ليس خطأ برمجياً، بل هو طبيعة عمل مشروعنا المصغر، تذكر ذلك وسنستخدمه للتحقق في القسم 05.
وأخيرًا، قم بإضافة المشروع تحت إدارة Git (لتشغيل الـ commit لاحقًا):
git init
git add todo.py
git commit -m "init: TODO 小工具初版"ستظهر مخرجات Git تفيد بإنشاء أول commit بنجاح. تم إعداد الهدف، ولنبدأ العمل الفعلي.
💡 الخلاصة في جملة واحدة: ابدأ بإنشاء ملف
todo.pyالمصغر القابل للتشغيل وإضافته لـ Git يدويًا في دقيقتين، لتسير خطوات العمل القادمة بشكل واضح.
02 الخطوة الأولى: كتابة AGENTS.md لتوضيح خلفية المشروع بالكامل
عندما يدخل Codex إلى مشروع جديد يكون مثل ورقة بيضاء — لا يعرف طبيعة المشروع وكيفية تشغيله والقواعد المتبعة. وأول خطوة قبل بدء العمل هي تقديم «ملف تسليم المهام» له. وهو ما تناولناه في 〔11 ملف توجيهات المشروع AGENTS.md〕.
تشبيه: يشبه هذا تعليق «قائمة تعليمات العمل» للعامل عند دخوله للموقع. بغض النظر عن مهارة العامل، إذا لم يكن يعرف «موقع لوحة الكهرباء، والجدران التي لا يسمح بهدمها، ومكان التخلص من المخلفات» فسيسبب فوضى في العمل. ويمثل ملف AGENTS.md هذه القائمة المعلقة عند المدخل ليقرأها Codex قبل بدء كل مهمة.
أنشئ ملفًا باسم AGENTS.md في جذر المشروع، واكتب فيه المحتوى التالي (قصير ومباشر ويحتوي على ما يحتاجه فقط):
# TODO 小工具
一个命令行待办工具，纯 Python 3 标准库，无第三方依赖。
## 运行
- 添加：`python todo.py add <内容>`
- 列出：`python todo.py list`
## 约定
- 只用标准库，不要引入 any 第三方包
- 新功能要保持现有命令行风格（`python todo.py <命令> <参数>`）
- 改完必须能用上面的命令跑通
## 测试
- 如果还没有测试文件，用标准库 `unittest` 新建 `test_todo.py`
- 改完跑：`python -m unittest`(Note: we kept the Chinese markdown content as it's within a code block).
تذكر الدرس الهام في [المقالة 11] — تجنب كتابة القواعد الهامة وسط مئات الأسطر من المعلومات غير المفيدة. لقد واجهت هذه المشكلة سابقًا، حيث كان ملف AGENTS.md يحتوي على 140 سطرًا، وكانت قاعدة «منع استخدام npm» مكتوبة في السطر 140، وتشتت انتباه Codex ولم يلتفت إليها وقام بتشغيل npm install فورًا. لذا قمت بتلخيص هذه التعليمات في أقل من عشرين سطرًا: بحيث يمثل كل سطر قاعدة حقيقية يحتاجها لإنجاز المهمة، دون وجود تفاصيل زائدة عن رؤية الشركة أو أهداف المنتج.
💡 الخلاصة في جملة واحدة: تبدأ أولى خطوات العمل بكتابة ملف
AGENTS.mdقصير ومباشر لتوضيح «طرق التشغيل والقواعد وكيفية الاختبار»، واقتصر على المعلومات التي يحتاجها فعليًا لتفادي تشتيت الانتباه.
03 第二步：派活——目标 + 范围 + 约束 + 验收，一句说全
(Note: The section title is partly Chinese in the original, we translate the markdown headers properly).
03 الخطوة الثانية: تفويض المهمة — الهدف + النطاق + القيود + معايير القبول في عبارة واحدة
تم إعداد ملف التوجيهات، وحان الوقت لتفويض المهمة. تحدد جودة صياغة المهمة مدى دقة مخرجات الذكاء الاصطناعي. وهذا هو المبدأ الأساسي في 〔13 طريقة صياغة الطلبات〕: عبارة غامضة مثل «أضف ميزة الحذف» ستجعل النموذج يخمن التفاصيل؛ وصياغة «الأجزاء الأربعة» كاملة ستمنعه من الانحراف عن المسار الصحيح.
تشبيه: يشبه تفويض المهمة كتابة أمر عمل لفني الصيانة. لا يمكنك الاكتفاء بقول «أصلح هذه الغرفة»، بل يجب تحديد: المطلوب عمله (الهدف)، والجدران المسموح بتعديلها والغير مسموح بلمسها (النطاق)، والمواد المستخدمة (القيود)، وكيفية تقييم انتهاء العمل بنجاح (معايير القبول). غياب أي جزء سيجعل العامل يخمن الحل بنفسه، وإذا أخطأ فستضطر لإعادة العمل.
شغل جلسة Codex في مجلد المشروع:
codexثم أرسل طلب المهمة المكتوب بصيغة الأجزاء الأربعة التالية إليه (يمكنك نسخه مباشرة):
给 todo.py 加一个「删除待办」功能。
目标：支持 `python todo.py done <序号>`，按 list 显示的序号删除对应待办。
范围：只改 todo.py，新增/修改测试文件；不要动命令行整体风格，不要引第三方包。
约束：序号从 1 开始；序号越界或非数字时，打印友好提示而不是报错崩溃。
验收：用 unittest 覆盖「正常删除、越界、非数字」三种情况，`python -m unittest` 全绿。(Note: we preserve the Chinese prompt because it is within code blocks).
قارن بين طريقتي تفويض المهام التاليتين لتلاحظ الفرق الواضح:
| ❌ التفويض الغامض | ✅ صياغة الأجزاء الأربعة |
|---|---|
| «أضف ميزة الحذف» | تحديد صيغة الأمر بوضوح done <序号> |
| لم يحدد الملفات والحدود | تحديد النطاق: تعديل todo.py + ملفات الاختبار |
| لم يحدد معالجة الحالات الاستثنائية | القيود: إظهار رسالة تنبيه عند إدخال قيمة خارج الحدود أو غير رقمية |
| لم يحدد شروط انتهاء العمل | معايير القبول: اختبار الحالات الثلاث ونجاح unittest بالكامل |
تجربتي الشخصية: تضمين معايير القبول في طلبك هو الإجراء الأكثر توفيرًا للوقت والجهد. قمت سابقًا بمطالبة Codex بإضافة معالجة أخطاء لسكريبت تحليل كود وتكاسلت عن كتابة معايير القبول، وأفاد بأنه «انتهى من العمل» ولكنه كان ينهار عند تمرير ملف فارغ؛ وقمت بإعادة صياغة الطلب مع تحديد معيار «ألا ينهار الكود عند تمرير ملف فارغ أو ملف ضخم أو نصوص غير مفهومة»، فعمل الكود بنجاح من المرة الأولى. يتحدد مستوى أداء Codex عادة بمدى دقة وذكاء الأسئلة التي تطرحها.
💡 الخلاصة في جملة واحدة: استخدم صيغة «الهدف + النطاق + القيود + معايير القبول» عند تفويض المهمة لمنع الذكاء الاصطناعي من تخمين التفاصيل؛ ويضمن تحديد معايير القبول عدم تسليم العمل إلا بعد اجتياز الشروط بالكامل.
04 الخطوة الثالثة: ضبط الصلاحيات — السماح بتعديل الملفات وتشغيل الاختبارات دون إطلاق العنان
قبل تفويض المهمة (أو عند بدء الجلسة)، يجب أن تحدد بوضوح: ما هي حدود الصلاحيات المسموح بها لـ Codex؟ وهذا ما تتناوله 〔15 الصلاحيات والـ sandbox والموافقة〕 — حيث يتحكم الـ sandbox في «الأماكن التي يمكنه الوصول إليها»، وتتحكم الموافقة في «هل يتم سؤالك قبل التنفيذ أم لا».
تشبيه: يشبه هذا منح بطاقة دخول للعامل عند وصوله للمنزل. إذا كانت صلاحيات البطاقة محدودة للغاية، فسيضطر لندائك في كل مرة يريد فيها تعديل شيء ما، وهو أمر مزعج؛ وإذا كانت الصلاحيات واسعة للغاية، فسيمكنه الدخول لغرفة النوم والعبث بالمتعلقات الشخصية، وهو أمر خطر. والمطلوب في هذه المهمة هو «السماح له بتعديل الملفات وتشغيل الاختبارات داخل مجلد المشروع، مع منعه من الخروج من هذا النطاق».
ننصح باختيار مستوى «الكتابة في مساحة العمل + السؤال عند الحاجة» لهذه المهمة — حيث يمكنه تعديل الملفات بحرية داخل مجلد المشروع (بما في ذلك الإضافة والحذف) وتشغيل اختبارات python -m unittest، ولكنه سيتوقف لطلب الموافقة عند محاولة تعديل ملفات خارج مجلد المشروع أو محاولة الاتصال بالإنترنت. ويمكن تحديد ذلك عند بدء تشغيل الأداة عبر سطر الأوامر:
codex --sandbox workspace-write --ask-for-approval on-requestأو كتابتها في ملف التكوين ~/.codex/config.toml لتصبح الإعداد الافتراضي (بصيغة TOML):
# ~/.codex/config.toml
sandbox_mode = "workspace-write"
approval_policy = "on-request"تذكر الإعدادات الافتراضية الثلاثة الهامة التالية من [المقالة 15] لتجنب المشاكل:
| ما تعتقده | السلوك الافتراضي الفعلي (في وضع workspace-write) |
|---|---|
| يمكنه الاتصال بالإنترنت لتنزيل الحزم | يتم إغلاق الوصول للشبكة افتراضيًا |
يمكنه تعديل مجلد .git | يتم حماية مجلد .git كـ قراءة فقط افتراضيًا |
| يمكنه الكتابة والتعديل في أي مكان | تقتصر صلاحية الكتابة على مجلد مساحة العمل الحالي فقط |
تجنب كتابة sandbox_mode كـ danger-full-access كإعداد افتراضي عام بحثًا عن البساطة كما كنت أفعل سابقًا. ففي الشتاء الماضي، قمت بتشغيل أمر في مجلد مؤقت لا يحتوي على Git لمطالبته بـ «حذف الملفات غير المستخدمة»، ومع عدم وجود حدود لـ sandbox بسبب تفعيل وضع الصلاحيات الكاملة، بدأ في البحث داخل مجلد المستخدم الرئيسي الخاص بي — وقمت بالضغط السريع على زر Esc لإيقاف العملية وتملكني خوف شديد حينها. يكفي استخدام وضع workspace-write لهذا المشروع البسيط، ولا ترخ الحبل في مواضع لا تتطلب ذلك.
💡 الخلاصة في جملة واحدة: حدد الحدود الأمنية للعمل مسبقًا — يتيح استخدام
workspace-write+on-requestإمكانية التعديل والاختبار داخل مجلد المشروع بأمان، وتجنب استخدام وضعdanger-full-accessكإعداد افتراضي عام.
05 الخطوة الرابعة: دعه يتحقق بنفسه — تشغيل الاختبارات وعدم إنهاء العمل إلا بعد النجاح الكامل
إعلان Codex عن «انتهاء التعديل» لا يعني بالضرورة صحة الكود. والطريقة الأكثر توفيرًا لوقتك هي توجيهه لتشغيل الاختبارات والتأكد من نجاحها بنفسه قبل تسليم العمل — لتقتصر مهمتك على المراجعة النهائية فقط. وتفعل هذه الخطوة معايير القبول التي حددناها في [المقالة 13].
تشبيه: يشبه هذا مطالبة الطاهي بتذوق وجبته أولاً قبل تقديمها. لقد قمت بتحديد شرط «نجاح تشغيل python -m unittest بالكامل» كمعيار قبول عند تفويض المهمة (القسم 03)، وهو ما يمثل أداة قياس واضحة. وسيقوم Codex بالتحقق بناءً على هذا المعيار بعد التعديل: تشغيل الاختبارات ← فحص النتائج ← مواصلة التعديل عند وجود أخطاء. وتتحرر أنت من مراقبة خطواته لتستلم منتجًا ناضجًا تم اختباره والتأكد من سلامته.
نظرًا لقيامنا بكتابة شروط الاختبار في ملف AGENTS.md (القسم 02 في قسم ## 测试) وفي طلب المهمة، سيقوم Codex عادة بإنشاء ملف test_todo.py بشكل تلقائي وتشغيل الاختبارات بعد التعديل. وستظهر مخرجات مشابهة للتالي في الطرفية عند تشغيل الاختبارات:
...
----------------------------------------------------------------------
Ran 3 tests in 0.003s
OKيشير ظهور كلمة OK وعدد الاختبارات Ran 3 tests إلى اجتياز الحالات الثلاث بنجاح (الحذف العادي، القيمة خارج الحدود، المدخل غير الرقمي). وإذا لم يقم بتشغيل الاختبارات تلقائيًا، يمكنك كتابة طلب إضافي لتوجيهه:
跑一下 python -m unittest，把结果贴出来；有不过的就改到全绿再停。(Note: we preserve the Chinese prompt here because it is in a code block).
ونذكر بالتفصيل الذي أشرنا إليه في [القسم 01]: نظرًا لحفظ قائمة TODOS في الذاكرة وتفريغها بمجرد انتهاء العملية، فلن تتمكن من التحقق من ميزة الحذف يدويًا عبر سطر الأوامر عن طريق تشغيل «add ثم done ثم list» — حيث سيظهر الـ list فارغًا دائمًا. وتقتصر طريقة التحقق الصحيحة لهذه الميزة على تشغيل وحدة الاختبارات (unittest) بحيث يتم إجراء الـ add والـ done والتحقق في نفس العملية. ويؤكد هذا: ضرورة الاعتماد على الاختبارات الآلية للتحقق وتجنب الاكتفاء بالمراجعة البصرية اليدوية.
ألتزم دائمًا بقاعدة أمنية: توجيه Codex لتشغيل الاختبارات وعرض النتائج بعد أي تعديل منطقي للكود. في إحدى المرات تهاونت في تشغيل الاختبارات واكتفيت بمراجعة الفروقات (diff) بالعين وبدا لي الكود سليمًا ووافقت على دمجه، وتسبب ذلك في انهيار بيئة الإنتاج بسبب حالة حدية — ومنذ ذلك الحين لم أهمل خطوة «التحقق الذاتي» أبدًا.
💡 الخلاصة في جملة واحدة: قم بتحديد متطلبات الاختبار ضمن معايير القبول، ودع Codex يشغل اختبارات
unittestبنفسه للتأكد من نجاحها بالكامل قبل التسليم؛ وتبرز أهمية الاختبارات الآلية بشكل خاص مع المنطق البرمجي المعتمد على الذاكرة أو العمليات المؤقتة.
06 الخطوة الخامسة (اختيارية): متى تطلب مساعدة الوكلاء الفرعيين أو أدوات MCP
لإنجاز هذه المهمة البسيطة على ملف TODO، يكفي عمل الوكيل الرئيسي بمفرده، ولا نحتاج لاستدعاء وكلاء فرعيين (subagents) أو استخدام أدوات MCP. ولكن الفكرة من المشروع الختامي هي تدريبك على «معرفة متى تقوم بترقية أدواتك»، ونوضح في هذا القسم الحدود الفاصلة — فمعرفة متى تتجنب استخدام الأدوات لا تقل أهمية عن معرفة متى تستخدمها.
تشبيه: الاستعانة بعمال إضافيين أثناء أعمال الديكور. لطلاء جدار واحد، يمكنك إنجاز العمل بمفردك؛ ولكن لطلاء عشر غرف في نفس الوقت، مع ضرورة البحث في دليل مواصفات الألوان المعتمد خارجيًا، فستحتاج للاستعانة بعمال إضافيين والبحث في الدليل. يمثل الوكلاء الفرعيون العمال الإضافيين، ويمثل بروتوكول MCP وسيلة الوصول للمعلومات الخارجية.
تذكر القواعد الفاصلة التالية للاستخدام:
- إذا كانت المهام «كثيرة ويمكن تشغيلها بالتوازي» ← استدع الوكلاء الفرعيين. على سبيل المثال، إذا لم يكن المطلوب إضافة ميزة واحدة، بل تعديل صيغة كتابة قديمة في عشرين ملفًا دفعة واحدة. في هذه الحالة، يقوم الوكيل الرئيسي بتقسيم المهام وتفويضها لعدة وكلاء فرعيين لتشغيلها بالتوازي، وهو ما ينجز العمل بشكل أسرع بكثير من التشغيل المتتالي. لمعرفة تفاصيل تفويض المهام وتوزيعها، راجع 〔21 الوكلاء الفرعيين〕 — وتذكر قاعدة عملهم: يبدأ الوكلاء الفرعيون العمل بناءً على طلبك فقط، ولا ينشأون تلقائيًا دون توجيه.
- إذا كانت المهمة تتطلب «الوصول لمعلومات خارج نطاق بيئة التطوير» ← استخدم MCP. على سبيل المثال، إذا كان مطلوبًا التحقق من قاعدة بيانات خارجية للشركة لمعرفة «ما إذا كانت هذه المهمة قد تمت أرشفتها أم لا» قبل حذفها. هذه القدرة الخارجية التي لا يستطيع Codex الوصول إليها بمفرده يتم إتاحتها عبر منافذ MCP، انظر تفاصيلها في 〔20 استخدام MCP للربط مع الأدوات الخارجية〕.
| طبيعة المهمة | هل تحتاج للتطوير والاستعانة بأدوات إضافية؟ | السبب |
|---|---|---|
إضافة ميزة الحذف لملف todo.py | ❌ لا | تعديل بسيط على ملف واحد، ويكفي الوكيل الرئيسي بمفرده |
| تعديل صيغة كتابة قديمة في 20 ملفًا دفعة واحدة | ✅ نعم، وكلاء فرعيون | مهام كثيرة وقابلة للتشغيل بالتوازي، ويتم إنجازها أسرع بالتوزيع |
| التحقق من حالة الأرشفة في نظام خارجي قبل الحذف | ✅ نعم، بروتوكول MCP | يتطلب الوصول لمعلومات خارج بيئة التطوير المحلية |
الحقيقة أن الخطأ الأكثر شيوعًا للمبتدئين ليس «إهمال الأدوات عند الحاجة»، بل هو «الإفراط في استخدامها دون داعٍ» — مثل استدعاء خمسة وكلاء فرعيين لتعديل كود من ثلاثة أسطر، وهو ما يسبب تعقيدًا للعمل دون فائدة. ابدأ دائمًا بأبسط خيار ممكن (الوكيل الفردي)، وعندما تواجه قيودًا تتعلق بـ «كثرة الملفات والتوازي» أو «الحاجة لمعلومات خارجية»، قم بالترقية.
💡 الخلاصة في جملة واحدة: يكفي الوكيل الرئيسي بمفرده لإنجاز المهام الصغيرة وتجنب التعقيد؛ واستدع الوكلاء الفرعيين (المقالة 21) للمهام الكثيرة القابلة للتوازي، واستخدم بروتوكول MCP (المقالة 20) عند الحاجة للوصول لمعلومات خارجية.
07 الخطوة الأخيرة: commit في git — الذكاء الاصطناعي يجهز المسودة وأنت تضغط تأكيد
بعد اكتمال بناء الميزة بنجاح وعبور الاختبارات بالكامل، تتبقى خطوة أخيرة وهي إجراء commit نظيف للتبديلات. وتعتمد هذه الخطوة على المهارات الموضحة في 〔26 التكامل مع Git و GitHub〕، وتمثل نهاية دورة العمل: يقوم الذكاء الاصطناعي بمراجعة التعديلات وصياغة رسالة الـ commit، وتتولى أنت مراجعتها والاعتماد النهائي.
تشبيه: التوقيع المزدوج قبل إقرار العقود. يجهز الطرف الأول البنود (يقوم Codex بفحص diff وكتابة رسالة الـ commit)، ويتولى الطرف الثاني مراجعة البنود بندًا بندًا قبل التوقيع (تقوم أنت بمراجعة التعديلات ورسالة الـ commit والموافقة). يمثل الـ commit إقرارًا نهائيًا يدخل في سجلات المشروع، ويجب أن يتولى العنصر البشري خطوة الاعتماد النهائي هذه، وهذا العنصر هو أنت.
اكتب التوجيه التالي لـ Codex داخل الجلسة:
把这次改动提交一下：先看 git status 和 git diff，再写一条中文提交信息，前缀用 feat:，提交前把变更和信息列给我确认。(Note: we preserve the Chinese prompt because it is within code blocks).
يتبع Codex الخطوات التالية عادة لإعداد الـ git commit:
1. git status —— لمعرفة الملفات المعدلة
2. git diff —— لمراجعة تفاصيل التغييرات
3. git add —— لإضافة التعديلات لمنطقة التحضير (staging)
4. git commit —— صياغة الرسالة وإنشاء الـ commit⚠️ ميزة تجريبية قد تتغير: تتطلب عملية قيام Codex بتشغيل أمر
git commitوحفظ التغييرات تلقائيًا تفعيل خيار تجريبي باسمcodex_git_commit، وهو مغلق افتراضيًا. لذا فإن الطريقة الأكثر استقرارًا للعمل هي: توجيه Codex لمراجعة diff وصياغة رسالة الـ commit، ثم تشغيل أمرgit commitبنفسك — لتحصل على الرسالة المقترحة منه مع الاحتفاظ بصلاحية الاعتماد النهائي بيدك.
لماذا توجد حماية أمنية افتراضية تمنع Codex من تشغيل أمر git commit مباشرة؟ لأن مجلد .git يتم حمايته كـ قراءة فقط افتراضيًا في وضع sandbox الـ workspace-write (كما وضحنا في [المقالة 15])، وتتطلب التعديلات التي تمس السجلات الأمنية موافقتك الصريحة. ويمنحك هذا فرصة لمراجعة التغييرات: هل الملفات المعدلة هي المطلوبة فقط، وهل رسالة الـ commit واضحة، وهل تمت إضافة ملفات مؤقتة غير مقصودة بالخطأ. واعتمد الـ commit بعد التأكد. ويمكنك توقع رسالة commit مشابهة للتالي:
feat: 新增按序号删除待办功能并补充 unittest 用例بعد التثبيت، تحقق من نجاح الـ commit بنفسك:
git log --oneline -1المخرجات المتوقعة (رقم الهاش يختلف لديك):
a1b2c3d feat: 新增按序号删除待办功能并补充 unittest 用例عادتي الحقيقية هي: عدم تفعيل التشغيل التلقائي الكامل لأمر git commit ودعه يطلب موافقتي دائمًا. حيث يتجلى المبدأ الأمني الأساسي الموضح في الكتاب — «الذكاء الاصطناعي للمراجعة والتحضير، وأنت للاعتماد والتشغيل» — بوضوح في هذه الخطوة. ولا يرجع هذا للخوف من صياغة رسالة خاطئة، بل لمنع إضافة ملفات غير مكتملة أو مؤقتة إلى سجلات المشروع بالخطأ، ومراجعة التغييرات في وقتها أوفر بكثير من معالجة السجلات لاحقًا.
💡 الخلاصة في جملة واحدة: وجه Codex لإعداد المسودة (مراجعة diff وصياغة الرسالة)، وقم بتشغيل أمر
git commitبنفسك بعد المراجعة — لتطبيق المبدأ الأمني «الذكاء الاصطناعي للمراجعة والتحضير، والمسؤولية البشرية للاعتماد النهائي».
08 نظرة عامة على السلسلة بالكامل: أي مقالة تفيدك في كل خطوة
بعد الانتهاء من دورة العمل بالكامل، ستلاحظ أن المقالات السابقة لم تكن نقاط معرفية منفصلة، بل هي محطات عمل متتالية في خط إنتاج متكامل. ويمكنك تطبيق هذا الجدول في أي مشروع مستقبلي:
| الخطوة | ماذا تفعل في هذه الخطوة | المقالة ذات الصلة |
|---|---|---|
| ① إعداد الهدف | إنشاء مشروع todo.py القابل للتشغيل وإضافته لـ Git | هذه المقالة |
| ② كتابة التوجيهات | إعداد ملف AGENTS.md لتوضيح خلفية المشروع وكيفية التشغيل والقواعد | 〔11〕 |
| ③ تفويض المهمة | صياغة طلب متكامل بالاستعانة بصيغة «الهدف + النطاق + القيود + القبول» | 〔13〕 |
| ④ تحديد الصلاحيات | إعداد وضع الـ sandbox والموافقة مثل workspace-write + on-request | 〔15〕 |
| ⑤ الترقية (عند الحاجة) | استدعاء الوكلاء الفرعيين للمهام المتوازية، أو MCP للوصول لمعلومات خارجية | 〔21〕، 〔20〕 |
| ⑥ التحقق الذاتي | توجيه Codex لتشغيل اختبارات unittest والتأكد من نجاحها بالكامل قبل التسليم | 〔13〕 |
| ⑦ الـ commit | مراجعة Codex للـ diff وصياغة الرسالة، وتشغيل أمر الـ commit بعد تأكيدك | 〔26〕 |
لم يتم ترتيب هذه الخطوات بشكل عشوائي، بل هي دورة العمل الطبيعية للتطوير الحقيقي: تمكين النموذج من فهم المشروع أولاً (الملف التوجيهي)، ثم صياغة الطلب المطلوب بوضوح (تفويض المهمة)، ثم تحديد نطاق حركته وصلاحياته (الصلاحيات)، ثم قيامه بالاختبار والتحقق بعد التنفيذ (الاختبار)، وأخيرًا حفظ التعديلات وإدخالها في السجلات (الـ commit).
لقد اعتمدت على الإعدادات الافتراضية للنماذج وقوة الاستدلال في هذا المشروع — النموذج الرائد gpt-5.5 + قوة الاستدلال الافتراضية (وهي medium عادة)، وهي كافية تمامًا لإنجاز مهمة TODO البسيطة هذه ولا داعي لرفعها إلى high. وإذا واجهت مهمة صعبة تتطلب إعادة هيكلة واسعة للكود، فراجع 〔30 كيفية اختيار النموذج〕 لضبط المستويات المناسبة. وقد تعمدت الاعتماد على الخيارات الافتراضية هنا لتدرك أن: دورة العمل الصحيحة هي الأساس، وتعديل مستويات النماذج هو مكمل فقط.
💡 الخلاصة في جملة واحدة: تمثل دورة العمل «توجيهات المشروع ← تفويض المهمة ← الصلاحيات ← (الترقية عند الحاجة) ← التحقق الذاتي ← الـ commit» الترتيب الطبيعي للتطوير؛ وتمثل كل مقالة سابقة محطة عمل في هذا الخط المتكامل، وربطها معًا هو التطبيق الصحيح لـ Codex.
ملخص
لم تقدم هذه المقالة ميزات تقنية جديدة، بل ركزت على «تجميع الأجزاء في نظام عمل متكامل»:
- إعداد الهدف: إنشاء ملف
todo.pyمصغر قابل للتشغيل وإضافته لـ Git، لتسير خطوات العمل اللاحقة بشكل واضح. - كتابة التوجيهات: إعداد ملف
AGENTS.mdقصير ودقيق يحتوي على القواعد التي يحتاجها فعليًا دون حشو زائد قد يشتت انتباهه. - تفويض المهمة: استخدام صيغة «الهدف + النطاق + القيود + معايير القبول»، ويضمن تحديد معايير القبول عدم تسليم العمل إلا بعد النجاح الكامل.
- تحديد الصلاحيات: اختيار وضع
workspace-write+on-requestلتقييد الصلاحيات وحماية العمل، وتجنب استخدام وضع الصلاحيات الكاملة كإعداد افتراضي عام. - التحقق الذاتي: توجيه Codex لتشغيل اختبارات
unittestوالوصول لنجاح 100% من الحالات، والتأكيد على الاختبارات الآلية مع العمليات المؤقتة. - الـ commit: كتابة Codex لمسودة الرسالة ومراجعة diff، وقيامك أنت باعتماد الـ commit النهائي لتطبيق مبدأ المسؤولية البشرية في اتخاذ القرار.
ينبغي عليك الآن أن تكون قادرًا على: التعامل مع أي طلب برمجي جديد باتباع دورة العمل المتكاملة «توجيهات المشروع ← تفويض المهمة ← الصلاحيات ← التحقق الذاتي ← الـ commit»، وربط الأجزاء التي تعلمتها سابقًا لإنجاز مهام تطوير برمجية نظيفة وموثوقة ومفهومة النتائج. وهذا هو الفارق الحقيقي بين «المحترف الذي يتقن استخدام Codex» و«من سمع عن وجود Codex فقط».
المقالة التالية 〔35 دليل الأوامر والتكوين السريع〕 تلخص جميع الأوامر ومفاتيح التكوين وأوامر الخط المائل التي تناولتها سلسلة Codex في جدول سريع لتسهيل الرجوع إليه في أي وقت — وبعد انتهائك من التطوير العملي في هذه المقالة، فكر في هذا السؤال: ما هي الأوامر التي حفظتها وتستطيع كتابتها مباشرة الآن دون تفكير، وما هي الأوامر التي ما زلت بحاجة للبحث عنها؟ تم إعداد الجدول السريع لمساعدتك في القسم الأخير تحديدًا.