قائمة تحقق لتصدير قاعدة كود مُنشأة بالذكاء الاصطناعي لتسليم نظيف

لماذا تفشل المشاريع المُصدرة بعد التسليم

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

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

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

لهذا السبب، تتعلق قائمة التحقق المبنية بالذكاء الاصطناعي للتصدير أساسًا بالوثائق وإمكانية إعادة التشغيل، لا بنقل الملفات فقط. إذا بنيت التطبيق في منصة vibe-coding مثل Koder.ai ثم صدّرت الشيفرة، يحتاج الفريق التالي إلى خريطة: ما الذي يجب ضبطه، ما الذي يجب تشغيله، وماذا يعني أن "يعمل" التطبيق.

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

يجب أيضًا توضيح الملكية. الصانع مسؤول عن جعل الافتراضات مرئية (وثائق، سكربتات، قيم افتراضية آمنة). المتسلم مسؤول عن تكييف المشروع مع بيئته (مدير أسرار، استضافة، قواعد CI أشد صرامة). عندما يعرف الطرفان دوره، يصبح التسليم روتينيًا.

قبل التصدير: اتفق على عقد التسليم

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

اختر لحظة التصدير

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

نقطة التصدير الجيدة عادة هي واحدة من هذه:

• التزام مستقر مع ملاحظة إصدار قصيرة (ما الذي تغيّر، ما الذي يجب اختباره)
• إصدار موسوم (حتى إن كان v0.1.0)
• لقطة منصة (مثل لقطة Koder.ai يمكنك العودة إليها إذا احتاج التصدير للتكرار)

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

قرّر ما الذي يتضمنه التسليم

اكتب جردًا قصيرًا لما يتوقعه المستلم. كن صريحًا بشأن ما هو مُضمّن وما هو غير مُضمّن عمدًا.

ضمّن الأساسيات: شيفرة المصدر (تطبيقات، خدمات، حزم مشتركة)، قوالب التكوين (.env.example)، سكربتات (build, dev, test, migrations, seed)، وملاحظات النشر. أدرج بيانات عيّنة فقط إذا جرى تنظيفها وكانت آمنة.

ثم ثبّت الإصدارات حتى لا تصبح عبارة "تعمل على جهازي" هي المعيار الجديد. سجّل إصدارات وقت التشغيل وسلاسل الأدوات (Node, Go, Flutter, مدير الحزم)، بالإضافة إلى نسخة قاعدة البيانات (الإصدار الرئيسي لـ PostgreSQL مهم).

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

متغيرات البيئة: وثّقها حتى لا يبقى شيء مخفيًا

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

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

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

صيغة بسيطة لكل متغير:

• الاسم: المفتاح بالضبط (نسخ/لصق)
• المعنى: ما يغيره في التطبيق
• مطلوب؟: مطلوب أم اختياري (وماذا يحدث إذا غاب)
• مثال: قيمة مثال آمنة (ليس سرًا حقيقيًا)
• أين يختلف: dev vs staging vs production

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

# Required
APP_ENV=development
PORT=3000
DATABASE_URL=postgres://user:password@localhost:5432/app_dev

# Optional
LOG_LEVEL=info
CORS_ORIGINS=http://localhost:5173

# Environment specific
PUBLIC_BASE_URL=http://localhost:3000

بعض التفاصيل تمنع معظم الالتباس:

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

أشر إلى ما يتغير حسب البيئة. عادةً DATABASE_URL وPUBLIC_BASE_URL تختلف بين dev/staging/production، بينما قد يبقى LOG_LEVEL نفسه. إن صدَّرت من Koder.ai للتحكم أو النشر، تأكد أن الافتراضات المنصة (منافذ، عناوين أساسية، أصول مسموح بها) منعكسة في الوثائق حتى يبقى السلوك متسقًا خارج المنصة.

أخيرًا، اذكر كيف تُحمّل متغيرات البيئة محليًا. إن كان المشروع يتوقع ملف .env، قل أين يقع وما إذا كان التطبيق يقرأه تلقائيًا أو يحتاج أمر/أداة لتحميله.

الأسرار: أبقِها خارج المستودع وسهلة الإعداد

الأسرار هي القيم التي قد تسبب ضررًا إذا سربت: مفاتيح API، كلمات مرور قواعد بيانات، رموز المصادقة، أسرار عملاء OAuth، المفاتيح الخاصة، وأسرار توقيع الويب هوك.

للتصدير، اجعل الأمر بسيطًا: يجب أن يحتوي المستودع على عناصر نائبة فقط، لا على قيم حقيقية. إن كان سر مطلوبًا للتشغيل، ضعه كعنصر نائب واضح في .env.example وفسّر كيف تُولَد قيمة حقيقية.

نمط عملي هو فصل ثلاث أشياء: ملف عيّنة، ملف محلي، ومخزن أسرار لـ CI/النشر. يجب أن يتضمن التصدير العينة، ويتجاهل الملف المحلي، ويوثق كيف يحصل CI/الاستضافة على الأسرار.

أين يجب أن تعيش الأسرار

اختر أسلوبًا واحدًا لكل بيئة والتزم به.

• التطوير المحلي: ملف .env (مضاف إلى .gitignore) يتم تحميله بواسطة التطبيق، أو مدير الأسرار المحلي الخاص بالفريق
• CI: متغيرات الأسرار المشفّرة في مزود CI
• النشر/الاستضافة: تُخزن الأسرار في بيئة الاستضافة وتُحقن وقت التشغيل

مثال: يتضمن المستودع PAYMENTS_API_KEY=replace_me. يولّد المستلم مفتاحه في لوحة مزوّد الخدمة ويضعه في .env المحلي وفي CI. تبقى الشيفرة كما هي.

أضف خطوة تدوير واحدة

التسليم وقت جيد لتدوير الأسرار، خصوصًا إن استُخدمت داخل جلسة منصة مشتركة سابقًا.

• أعد إصدار مفاتيح جديدة للخدمات الخارجية وألغي القديمة.
• أعد ضبط كلمات مرور قواعد البيانات وأي رموز إدارية.
• حدّث أسرار CI والاستضافة أولًا، ثم الملفات المحلية .env.
• أكد أن التطبيق يبدأ، والاختبارات تعمل، وأن المفاتيح القديمة لم تعد صالحة.

إن صدّرت من Koder.ai، اعتبر التصدير بيئة جديدة وأنشئ أسرارًا جديدة للفريق المتلقي.

إعداد التطوير المحلي: اجعل التشغيل الأول مملاً

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

المتطلبات المسبقة (كن دقيقًا)

ضع هذه في أعلى README حتى لا يحتاج أحد لاستنتاجها من رسائل الخطأ:

• ملاحظات عن نظام التشغيل: "مُجرب على macOS وUbuntu" (أضف ملاحظات Windows فقط إن اختبرت)
• إصدارات وقت التشغيل: Node.js (للـ React)، Go (للـ API)، PostgreSQL (للقاعدة)
• أدوات: npm/pnpm/yarn، Make (إن استخدمت)، Docker (فقط إن اعتمدت عليه)

إن بُني المشروع على Koder.ai، لتبقَ إعدادات التشغيل المحلي متوافقة مع ما صدّرتَه (نفس بنية المجلدات، نفس أوامر البدء). لا تفترض "أن PostgreSQL يعمل بالفعل" إلا إذا ذكرت ذلك صراحة.

أوامر التثبيت والتطوير (أمر واحد في كل سطر)

ضع الأوامر بالترتيب الذي يجب أن ينفذه المطور الجديد. اجعلها قابلة للنسخ واللصق:

# 1) Install dependencies
cd web
npm ci

cd ../server
go mod download

# 2) Create your env file
cp .env.example .env

# 3) Start dependencies (if needed)
# e.g., start Postgres locally or via docker compose

# 4) Run the app
cd server
go run ./cmd/api

cd ../web
npm run dev

أضف قسمًا بسيطًا للاختبارات والبناء أسفله مباشرة:

# Tests
cd server && go test ./...
cd web && npm test

# Build
cd web && npm run build
cd server && go build ./...

استكشاف الأخطاء: أبرز أخطاء التشغيل الأول

معظم مشاكل "لا يعمل" تقع ضمن بضعة أقسام:

1. الإصدارات الخاطئة (Node/Go). الأعراض: أخطاء في الاعتمادات أو التجميع. الحل: ثبت الإصدارات الموثقة وأعد تشغيل التثبيت.

2. قيم env مفقودة. الأعراض: إعداد غير معرّف، فشل المصادقة، أخطاء 500. الحل: قارن .env بـ .env.example واملأ القيم المطلوبة.

3. قاعدة البيانات غير متاحة. الأعراض: اتصال مرفوض، "قاعدة البيانات غير موجودة". الحل: شغّل Postgres، تحقق من host/port/user، ونفّذ خطوات تهيئة قاعدة البيانات كما هو مكتوب.

تهيئة قاعدة البيانات: الهجرات، البيانات المبدئية، وإعادة الضبط

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

ماذا توثّق (وما الذي يجب أن يبقى في المستودع)

اكتب أقل عدد خطوات لازمة لإعداد PostgreSQL جديد، وضع الأوامر في سكربتات حيثما أمكن. يجب أن يجيب تسليمك عن أربعة أسئلة:

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

إن كانت لديك سكربتات موجودة (أهداف Makefile، سكربتات شل، أو أوامر task runner)، استخدمها بدلًا من وصف خطوات يدوية. إن لم تكن موجودة، أضف مجموعة صغيرة الآن.

سير تهيئة بسيط وموثوق

حافظ على سير موحّد عبر البيئات (محلي، CI، staging). خط أساس جيد يبدو هكذا:

# 1) Create role + database (example names)
createuser app_user --pwprompt
createdb app_db --owner=app_user

# 2) Apply migrations
# Replace with your repo's migration command
./scripts/migrate up

# 3) Seed minimal demo data
./scripts/seed

بالنسبة للـ seeds، فضّل بيانات بسيطة تعمل على العرض بدل تفريغ مطابق للإنتاج. يجب أن تكون السكربتات قابلة لإعادة التشغيل بأمان (إدخالات idempotent، أو قاعدة "تشغّل فقط على DB فارغة").

بالنسبة لإعادة الضبط، كن صريحًا حول الأمان. يجب أن يستهدف أمر إعادة الضبط التطوير المحلي افتراضيًا فقط. إن وفّرت سكربتًا مدمّرًا، أضف حاجزًا (مثلاً: متطلب CONFIRM_RESET=1، أو التحقق من APP_ENV=development). حدّد أيضًا معنى "إعادة الضبط": حذف وإعادة إنشاء، مسح جداول، أم استعادة لقطة معروفة.

نظافة المستودع: ما الذي يجب أن يكون في المصدر وما الذي لا يجب

يتعثر التسليم عندما يشعر المستودع كأنه درج فوضى. يجب أن يتمكن القادم الجديد من تمييز المهم، والمولد، وأين يغيّر الإعدادات.

التزم بإضافة الأشياء التي تجعل المشروع قابلاً للتكرار: ملفات القفل، ملفات الهجرات، قوالب التكوين الصغيرة مثل .env.example، وأي سكربتات تُهيِّئ التطبيق.

أبقِ الملفات الشخصية، المولدة، أو الحساسة خارج التحكم بالمصدر: ملفات البيئة المحلية، إعدادات المحرر، مخرجات البناء، السجلات، الكاشات، وأي شيء يمنح وصولًا (مفاتيح API، كلمات مرور قواعد البيانات، ملفات حسابات الخدمة).

قاعدة بسيطة: إن تغييره يؤثر على الجميع، فادخله. إن تغيّر بحسب الجهاز أو البيئة، فوثّقه وأبقِه خارج المستودع.

إن أضفت ملاحظة قصيرة عن "أدخل أم تجاهل"، اجعلها موجزة:

• التزم بالنسخ: README, ملفات القفل، الهجرات، سكربتات seed، .env.example
• تجاهل: .env, ملفات الأسرار، مجلدات البناء، السجلات، الكاشات المحلية

أضف خريطة مجلدات قصيرة حتى يكون الهيكل واضحًا دون التنقل. مثال: "/backend خدمة API، /web الواجهة الأمامية، /mobile تطبيق محمول، /db الهجرات والـ seeds، /scripts مساعدات الإعداد."

إن صدّرت من Koder.ai، اعتبر التصدير بداية جلسة تنظيف: احذف الفوضى المولدة، أكد قواعد .gitignore، واكتب خريطة المجلدات.

إعداد CI: اجعل خط الأنابيب قابلاً لإعادة التشغيل

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

قرر ما الذي يجب أن يثبته CI عند كل طلب سحب. معظم الفرق تحتاج مجموعة صغيرة:

• Lint/format
• اختبارات الوحدة
• البناء (تجميع الويب والخادم بنجاح)

الاختبارات التكاملية وخطوات النشر مقبولة أيضًا، لكن فقط إن كانت موثوقة ومحددة بوضوح.

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

اجعل متغيرات env والأسرار صريحة

أكثر ما يكسر CI هو اعتماده على إعدادات مخفية. أضف قسمًا صغيرًا "متغيرات CI" في README يسرد الأسماء الدقيقة التي يتوقعها CI. فصل التكوين العام عن الأسرار.

أمثلة أسماء (عدّلها وفقًا للمكدس): APP_ENV, DATABASE_URL, PORT, JWT_SECRET, S3_BUCKET, STRIPE_API_KEY. في CI، يجب أن تأتي الأسرار من مخزن أسرار CI، لا من ملفات مُلتزِمة بالمستودع. بالنسبة لباكند Go + Postgres (شائع في تصديرات Koder.ai)، أشر ما إذا كانت الهجرات تُشغّل تلقائيًا أو تتطلب خطوة صريحة.

احمِ عمليات الدمج بواسطة فحوصات الحالة

قرر أي فحوصات مطلوبة قبل الدمج وسجلها. "lint + اختبارات وحدة + بناء" عادةً كافٍ. إن أضفت وظائف اختيارية (كالـ mobile builds)، احتفظ بها غير حاجزة ما لم تكن ضرورية بالفعل.

اجعل مخرجات CI سهلة التصحيح: اطبع إصدارات الأدوات وافشل برسائل واضحة. أضف التخزين المؤقت بعد استقرار خط الأنابيب.

سيناريو تسليم مثالي: من الاستنساخ إلى تشغيل التطبيق

تحصل Maya على مشروع مُصدّر من Koder.ai. الإعداد نموذجي: تطبيق React للواجهة، API بـ Go، وقاعدة بيانات PostgreSQL. يجب أن تكون قادرة على استنساخه والحصول على شاشة عمل دون تخمين.

أول 30 دقيقة يجب أن تبدو هكذا:

1. استنساخ المستودع وفتح README الجذر.
2. نسخ .env.example إلى .env (أو ضبط نفس القيم في شيلها) لكل من web وapi.
3. تشغيل PostgreSQL (محليًا أو في Docker) وإنشاء قاعدة بيانات فارغة.
4. تشغيل الهجرات والـ seeds للحصول على مجموعة بدء معروفة.
5. تشغيل الـ backend ثم الـ frontend، وفتح التطبيق في المتصفح.

في تسليم فوضوي، عادةً تواجه ثلاثة معوقات.

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

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

ثالثًا: كل شيء يعمل لكن الواجهة الأمامية تشير إلى المنفذ الخطأ. Maya تفتح localhost:3000 لكن الـ API يتوقع localhost:8080 أو تمنع CORS الطلبات. هنا تساعد القيم الافتراضية المتسقة: مكان واحد لضبط WEB_PORT, API_PORT, وAPI_BASE_URL مع README يذكر عناوين URL المحلية المتوقعة.

قائمة نهاية: فخاخ شائعة وخطوات تالية

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

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

فحوصات سريعة تلتقط معظم الإخفاقات:

• README يحتوي على مسار "كيفية التشغيل" واحد قابل للنسخ واللصق لتطوير محلي، وقسم قصير "كيفية الاختبار".
• .env.example موجود، وكل متغير مطلوب مُشرح مع قيم مثال آمنة.
• تهيئة قاعدة البيانات تعمل من البداية للنهاية: إنشاء DB، تشغيل الهجرات، seed اختياري، وأمر إعادة ضبط.
• CI يعمل على عدّّاد نظيف ويتطابق مع الأوامر المحلية.
• يمكن لمطور جديد أن يُجري تغييرًا صغيرًا، يشغل الاختبارات، ويرى النتيجة في التطبيق.

الفخاخ الشائعة مملة، ولهذا تُفقد:

• خطوات لمرة واحدة مخفية لم تُدرج في الوثائق
• README يطابق بنية مجلدات أو أسماء أوامر قديمة
• قيم مضمّنة صلبة (عناوين API، أعلام ميزات، مفاتيح) مدمجة في الشيفرة بدلًا من التكوين
• أسرار مُشتركة شفهيًا دون مسار إعداد آمن وواضح
• CI يمر بسبب اعتماده على أرشيفات مخزنة مؤقتًا أو خدمات محلية

الخطوات التالية: عيّن صاحبًا للتحقق من التصدير خلال 24 إلى 48 ساعة، ليس بعد أسابيع. ليجرِ اختبار "الاستنساخ النظيف" ويبلغ عن الفجوات.

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