27 يوليو 2025·6 دقيقة
قائمة تحقق لتصدير قاعدة كود مُنشأة بالذكاء الاصطناعي لتسليم نظيف
استخدم قائمة التحقق هذه لتصدير قاعدة الشيفرة وتسليم المشروع بأمان: متغيرات البيئة، الأسرار، الإعداد المحلي، تهيئة قاعدة البيانات، CI، وREADME واضح للتشغيل.
استخدم قائمة التحقق هذه لتصدير قاعدة الشيفرة وتسليم المشروع بأمان: متغيرات البيئة، الأسرار، الإعداد المحلي، تهيئة قاعدة البيانات، CI، وREADME واضح للتشغيل.
تفشل معظم المشاريع المصدرة لسبب بسيط: كانت تعمل داخل المنصة الأصلية حيث كانت الإعدادات الافتراضية، والأسرار، وحالة قاعدة البيانات، وخطوات البناء موجودة بالفعل. بمجرد خروج الشيفرة من تلك الفقاعة، يحتاج المطور التالي إلى تخمين الافتراضات.
التسليم النظيف يعني أن المشروع يمكن استنساخه، وتكوينه، وتشغيله من قبل شخص لم يبنه، على جهاز جديد تمامًا، دون تبادل طويل للرسائل. لا يتطلب ذلك شيفرة مثالية، بل يتطلب جعل الأساسيات صريحة وقابلة للتكرار.
تتعطل عمليات التصدير لنفس المشكلات مرارًا وتكرارًا: إعدادات مخفية، تعامل غير واضح مع الأسرار، خطوات إعداد محلي غامضة، مفاجآت في قاعدة البيانات، وCI يعمل فقط في بيئة واحدة.
لهذا السبب، تتعلق قائمة التحقق المبنية بالذكاء الاصطناعي للتصدير أساسًا بالوثائق وإمكانية إعادة التشغيل، لا بنقل الملفات فقط. إذا بنيت التطبيق في منصة vibe-coding مثل Koder.ai ثم صدّرت الشيفرة، يحتاج الفريق التالي إلى خريطة: ما الذي يجب ضبطه، ما الذي يجب تشغيله، وماذا يعني أن "يعمل" التطبيق.
تركز هذه القائمة على أساسيات التسليم: متغيرات البيئة، الأسرار، إعداد التطوير المحلي، تهيئة قاعدة البيانات، إعداد CI، وREADME عملي "كيفية التشغيل". لا تغطي قرارات المنتج، أو تحسين واجهة المستخدم، أو إعادة تصميم المعمارية.
يجب أيضًا توضيح الملكية. الصانع مسؤول عن جعل الافتراضات مرئية (وثائق، سكربتات، قيم افتراضية آمنة). المتسلم مسؤول عن تكييف المشروع مع بيئته (مدير أسرار، استضافة، قواعد CI أشد صرامة). عندما يعرف الطرفان دوره، يصبح التسليم روتينيًا.
يبدأ التسليم النظيف باتفاق بسيط: ماذا يعني "مكتمل" عندما تغادر الشيفرة المنصة. بدونه، سيختلف الفرق لاحقًا حول السكربتات المفقودة، الاعتمادات المفاجئة، أو أي نسخة كانت هي الحقيقية.
اختر نقطة زمنية واحدة ومستقرة واعتبرها مصدر الحقيقة. التصدير أثناء التغيير هو السبب في الحصول على مستودع يكاد يعمل.
نقطة التصدير الجيدة عادة هي واحدة من هذه:
أضف جملة واحدة تشرح لماذا هذه نقطة التصدير المناسبة. مثال: "تمر جميع التدفقات الأساسية ومخطط قاعدة البيانات نهائي لهذا الإنجاز."
اكتب جردًا قصيرًا لما يتوقعه المستلم. كن صريحًا بشأن ما هو مُضمّن وما هو غير مُضمّن عمدًا.
ضمّن الأساسيات: شيفرة المصدر (تطبيقات، خدمات، حزم مشتركة)، قوالب التكوين (.env.example)، سكربتات (build, dev, test, migrations, seed)، وملاحظات النشر. أدرج بيانات عيّنة فقط إذا جرى تنظيفها وكانت آمنة.
ثم ثبّت الإصدارات حتى لا تصبح عبارة "تعمل على جهازي" هي المعيار الجديد. سجّل إصدارات وقت التشغيل وسلاسل الأدوات (Node, Go, Flutter, مدير الحزم)، بالإضافة إلى نسخة قاعدة البيانات (الإصدار الرئيسي لـ PostgreSQL مهم).
أخيرًا، أدرج المتطلبات المسبقة التي يجب تنفيذها قبل تشغيل أي شيء. اجعلها قصيرة ومحددة: الحسابات المطلوبة، الأدوات المثبتة، المنافذ التي يجب أن تكون حرة، وأي خطوات إعداد لمرة واحدة.
تفشل معظم عمليات التصدير لأن الإعدادات الأساسية لم تُدوَّن. متغيرات البيئة عادةً هي السبب: تعيش خارج المستودع، لذلك عند استنساخ المشروع لا يعلم المطور الجديد ما القيم المتوقعة.
عامل هذا كشرط للتصدير النظيف: يجب أن يكون كل متغير قابلًا للاكتشاف، مشروحًا، وسهل الضبط دون تخمين.
أنشئ مصدرًا واحدًا للحقيقة في README: قائمة بأسماء متغيرات البيئة، ما تتحكم به، ومن أين تأتي القيم. اجعل الشروحات بلغة بسيطة، واذكر أي أمر أمني.
صيغة بسيطة لكل متغير:
جنبًا إلى جنب مع الوثائق، أرسل ملف .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) يتم تحميله بواسطة التطبيق، أو مدير الأسرار المحلي الخاص بالفريقمثال: يتضمن المستودع PAYMENTS_API_KEY=replace_me. يولّد المستلم مفتاحه في لوحة مزوّد الخدمة ويضعه في .env المحلي وفي CI. تبقى الشيفرة كما هي.
التسليم وقت جيد لتدوير الأسرار، خصوصًا إن استُخدمت داخل جلسة منصة مشتركة سابقًا.
.env.إن صدّرت من Koder.ai، اعتبر التصدير بيئة جديدة وأنشئ أسرارًا جديدة للفريق المتلقي.
نجاح التسليم يعني أن مطوّرًا جديدًا يمكنه استنساخ المستودع، تشغيل بضعة أوامر، ورؤية التطبيق يعمل دون تخمين. هدفك هو متطلبات مسبقة متوقعة، ترتيب أوامر واضح، وقسم "كيفية التشغيل" قصير يطابق الواقع.
ضع هذه في أعلى README حتى لا يحتاج أحد لاستنتاجها من رسائل الخطأ:
إن بُني المشروع على 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 ./...
معظم مشاكل "لا يعمل" تقع ضمن بضعة أقسام:
الإصدارات الخاطئة (Node/Go). الأعراض: أخطاء في الاعتمادات أو التجميع. الحل: ثبت الإصدارات الموثقة وأعد تشغيل التثبيت.
قيم env مفقودة. الأعراض: إعداد غير معرّف، فشل المصادقة، أخطاء 500. الحل: قارن .env بـ .env.example واملأ القيم المطلوبة.
قاعدة البيانات غير متاحة. الأعراض: اتصال مرفوض، "قاعدة البيانات غير موجودة". الحل: شغّل Postgres، تحقق من host/port/user، ونفّذ خطوات تهيئة قاعدة البيانات كما هو مكتوب.
عند تصدير مشروع من منصة، غالبًا ما تكون قاعدة البيانات أول شيء يتعطل على جهاز جديد. الهدف بسيط: يجب أن يكون بإمكان الزميل الانتقال من "استنسخت المستودع" إلى "التطبيق يعمل ببيانات حقيقية" دون تخمين.
اكتب أقل عدد خطوات لازمة لإعداد PostgreSQL جديد، وضع الأوامر في سكربتات حيثما أمكن. يجب أن يجيب تسليمك عن أربعة أسئلة:
إن كانت لديك سكربتات موجودة (أهداف 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 قريبة من أوامر التطوير المحلية لتجنب الانحراف. إن كان المحلي make test، فليشغّل CI أيضًا make test. إن لم يكن لديك Makefile، فكّر بإضافة واحد واستخدامه كنقطة دخول مشتركة.
أكثر ما يكسر 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 دقيقة يجب أن تبدو هكذا:
.env.example إلى .env (أو ضبط نفس القيم في شيلها) لكل من web وapi.في تسليم فوضوي، عادةً تواجه ثلاثة معوقات.
أولًا: يقلع التطبيق ثم يتعطل بخطأ غامض "إعداد مفقود". السبب الحقيقي يكون متغير غير موثق مثل 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 حرفيًا. إن اضطررت للاختراع، أصلح الوثائق أو السكربتات حتى لا تضطر لذلك.
فحوصات سريعة تلتقط معظم الإخفاقات:
.env.example موجود، وكل متغير مطلوب مُشرح مع قيم مثال آمنة.الفخاخ الشائعة مملة، ولهذا تُفقد:
الخطوات التالية: عيّن صاحبًا للتحقق من التصدير خلال 24 إلى 48 ساعة، ليس بعد أسابيع. ليجرِ اختبار "الاستنساخ النظيف" ويبلغ عن الفجوات.
إن كنت تبني على Koder.ai (koder.ai)، فاعتبر هذه القائمة جزءًا من سير عملك: استخدم وضع التخطيط لتوثيق مسار التشغيل، التقط لقطات قبل التغييرات الكبيرة، وصدّر الشيفرة بانتظام حتى تبقى حزمة التسليم حديثة.
اختر نقطة مستقرة وعاملها كمصدر الحقيقة.
على الأقل، تضمّن ما يلي:
.env.example ووثائق واضحة عن متغيرات البيئةاستبعد أي شيء حساس أو أي بيانات اعتماد حقيقية.
وثق كل متغير بيئة في مكان واحد (عادة README الجذر) وضمّن .env.example.
لكل متغير، اذكر:
لا تُضمّن الأسرار في المستودع. أدرج نُدل فقط.
نموذج بسيط:
.env.example بقيم replace_me.env (مُضاف إلى .gitignore)وثّق أيضًا كيف تُولَد كل قيمة سرية مطلوبة (مثلاً: «أنشئ سلسلة عشوائية بطول 32+ لـ »).
دوّر أي شيء قد تم مشاركته أو إعادة استخدامه.
ترتيب عملي للدوْرَان:
.env المحليعامل التصدير كبيئة جديدة وابدأ نظيفًا.
اجعل التشغيل الأول "انسخ، ألصق، شغّل":
إذا احتاج المشروع Docker أو Make، اذكر ذلك صراحة—لا تجعل الناس يكتشفون ذلك من رسائل الأخطاء.
نعم—لأن إصدارات PostgreSQL الكبرى وأدوات البناء قد تغير السلوك.
سجّل على الأقل:
ثبّت الإصدارات حيث تستطيع، واطبع الإصدارات في CI لتسهيل تتبع الأخطاء.
زوّد مسار قابل للتكرار من الصفر:
أضف حواجز للأوامر المدمرة (مثلاً: استدراج APP_ENV=development أو متغير تأكيد).
اجعل CI قريبًا من الأوامر المحلية واجعل الإعدادات صريحة.
إذا كانت الهجرات مطلوبة للاختبارات، وثّق إن كانت CI تشغّلها تلقائيًا أو كخطوة صريحة.
قم باختبار "استنساخ نظيف":
إذا اضطررت للاختراق مرة واحدة، أصلح الوثائق أو السكربتات حتى لا تضطر لذلك مجددًا. هذه أسرع طريقة لاكتشاف الافتراضات الخفية من بيئة البناء الأصلية (بما في ذلك منصات vibe-coding مثل Koder.ai).
JWT_SECRET