تعلم كيفية تصدير شفرة المصدر من منصة vibe-coding واستلام ملكية نظيفة: التشغيل محليًا، إعداد CI، إدارة الأسرار، وتجهيز مستودع جاهز للتسليم.

امتلاك الشفرة أكثر من مجرد استلام ملف مضغوط من منصة. يعني أن تكون قادرًا على البناء، التشغيل، التعديل، والشحن دون الحاجة إلى مساحة العمل الأصلية، أزرار خاصة، أو إعدادات مخفية. المشروع الذي تملكه فعليًا يتصرف مثل أي مستودع عادي: زميل جديد يستطيع استنساخه، تشغيله على حاسوب محمول، ونشره عبر خط أنابيب قياسي.
معظم قلق القفل يأتي من نفس الفجوات القليلة:
مفاجأة شائعة أخرى هي أن التطبيق يعمل جيدًا على النسخة المستضافة، لكنه يفشل محليًا لأن متغيرات البيئة، إعداد قاعدة البيانات، أو الأسرار لم تُوثق صراحة.
تصدير نظيف من منصة vibe-coding يجب أن يؤدي إلى أربعة نتائج:
هذا مهم حتى لو لم تخطط لمغادرة المنصة أبدًا. موقف ملكية قوي هو تأمين: يقلل المخاطر، يسهل المراجعات، ويبسط التفاوضات إذا استأجرت وكالة، جمعت تمويلًا، أو غيرت الفرق.
إذا استخدمت Koder.ai، قد يتضمن التصدير تكديسات شائعة مثل تطبيق React للويب، backend بـ Go، PostgreSQL، أو تطبيق Flutter للموبايل. التركيب أقل أهمية من المبدأ: يجب أن تكون كل الأشياء اللازمة للتشغيل مرئية في المستودع، لا محبوسة في بيئة مستضافة.
تخيل مؤسسًا يسلم تطبيقًا لمقاول. "ها هو المستودع" يجب أن يكون كافياً. لا ينبغي للمقاول أن يحتاج إلى الوصول إلى مشروع المنصة الأصلي ليجد عنوان API الأساسي، ينشئ مخطط قاعدة البيانات، أو يتعلم كيفية بناء الواجهة.
بعد التصدير، يجب أن تمتلك مستودعًا عاديًا يمكن فتحه في محرر، تشغيله على اللابتوب، وتسليمه إلى فريق آخر دون الحاجة إلى المنصة الأصلية.
مع مشاريع Koder.ai، غالبًا ما تُطابق النُّسخ الخاصة بالتصدير هياكل مألوفة: تطبيق ويب React، backend بـ Go، وإذا بنيت واحدًا، تطبيق Flutter للموبايل. تختلف أسماء المجلدات، لكن ينبغي أن يجعل المستودع واضحًا مكان كل جزء وكيفية اتصالها.
ابدأ بتحديد نقاط الدخول وسير العمل المقصود. تريد الملف الأول الذي يُشغِّل كل تطبيق، بالإضافة إلى السكربتات التي توضح كيف يجب أن تطوّر وتدير التشغيل.
علامات نموذجية:
package.json بالإضافة إلى مجلد src/ (غالبًا مع main.tsx أو ما شابه)go.mod ومجلد cmd/ أو main.gopubspec.yaml الخاص بـ Flutter وlib/main.dartMakefile يصف كيفية تشغيل كل شيءdocker-compose.yml إذا كان التصدير معدًا للتشغيل كمجموعة خدماتيجب أن تكون التبعيات مثبتة الإصدارات. بالنسبة لجافاسكربت، هذا يعني وجود ملف قفل (package-lock.json, yarn.lock, أو pnpm-lock.yaml). بالنسبة لـ Go، يعني go.mod وgo.sum. غياب ملفات القفل لا يجعل المشروع مستحيل التشغيل، لكنه يصعّب البناء المتكرر.
يجب أن يكون التكوين منفصلًا عن الشفرة. ابحث عن أمثلة مثل .env.example أو config.example.yaml. لا يجب أن ترى أسرارًا حقيقية (مفاتيح API، كلمات مرور الإنتاج) مُرتكبة في التصدير. إذا رأيتها، اعتبرها تسريبًا ودوّرها فورًا.
لعمل قاعدة البيانات، ابحث عن مجلد هجرات (migrations/, db/migrations/) أو ملفات SQL مع طوابع زمنية. في تطبيق Go + PostgreSQL، قد ترى أيضًا مُشغِّل هجرات صغير أو سكربت يطبِّق الهجرات.
فحص سريع للتأكد: حدّد أوامر البناء والتشغيل أولًا (npm run dev, go run, make، وما شابه). إذا كان سكربت يعتمد على أمر مخصّص للمنصة فقط، استبدله بأدوات معيارية قبل أن تعلن استقلالية المستودع.
عامل التصدير كأثر صدور. قبل تشغيل أي شيء، قم بتمرير سريع "هل كل شيء هنا؟". من الأسهل اكتشاف الأجزاء المفقودة الآن بدلًا من بعد أن تبدأ بالتعديلات.
فحص عملي للتمامية هو البحث عن "الجذور" لكل جزء: package.json لتطبيق React، go.mod للـ backend بـ Go، وملفات هجرة/seed لقاعدة PostgreSQL.
أنشئ مستودع Git جديد من المجلد المصدَّر، ثم ارتكب بالضبط ما استلمته قبل إصلاح أي شيء. هذا يمنحك خطًا أساسًا نظيفًا ويجعل التغييرات اللاحقة سهلة المراجعة.
git init
# Optional: set default branch name
# git branch -M main
git add -A
git commit -m "Initial export"
الآن شغّل محليًا بخطوات صغيرة وقابلة للتحقق. ثبّت التبعيات، أنشئ التكوين المحلي، ابدأ قاعدة البيانات أولًا، ثم الـ backend، ثم الـ frontend. أثناء قيامك بذلك، دوّن كل أمر تستخدمه فعليًا. تلك الملاحظات تصبح README الخاص بك.
إليك تسلسل أوامر بسيط يمكنك تكييفه مع هيكل التصدير لديك:
# Frontend
cd web
npm install
npm run dev
# Backend
cd ../server
go mod download
go run ./cmd/server
يمكن للخادم أن يبدأ بينما التطبيق لا يزال معطوبًا. تأكد من أنه يستطيع القراءة والكتابة من البيانات.
اختر فحوصات سريعة تتناسب مع المنتج:
بمجرد أن تحصل على تشغيل محلي يعمل، حوّل ملاحظاتك المؤقتة إلى README.md حقيقي بخطوات قابلة للنسخ: أين تشغل الأوامر، الترتيب لبدء الخدمات، والمتغيرات البيئية المطلوبة.
قد يعمل التصدير، لكنه قد يظل "مولَّدًا" بدلًا من مُمتلك. المستودع الجاهز للتسليم يجعل واضحًا أين تعيش الأشياء، كيف تشغّل المشروع، وكيف تحافظ عليه متسقًا.
ابدأ بتخطيط واضح على مستوى الجذر. الأسماء أقل أهمية من الاتساق.
apps/ للواجهات الموجهة للمستخدم (web, mobile)services/ لواجهات الـ API، العمال، والمهامshared/ للأنواع والمرافق المشتركةinfra/ لقوالب النشر، السكربتات، وأمثلة البيئةdocs/ لملاحظات الهندسة وكتب التشغيلثم أضف مجموعة صغيرة من الملفات التي تقلل التخمين:
README.md مع المتطلبات المسبقة والأوامر الدقيقةCONTRIBUTING.md بقواعد قليلة (الفروع، طلبات السحب، لا أسرار).gitignore لإبقاء ملفات البيئة المحلية ومخرجات البناء خارج Gitاجعل README عمليًا. إذا كان المستودع يتضمن أجزاء متعددة (واجهة React، API بـ Go، PostgreSQL)، اذكر ترتيب البدء وأين يوجد التكوين (مثلاً، "انسخ .env.example إلى .env").
قم بفحص على جهاز جديد: استنسخ في مجلد جديد واتبع README الخاص بك. إذا صدرت من Koder.ai، عامل التصدير كأول التزام لمشروع مستقل جديد، ثم ادعُ الآخرين بعد ذلك.
إعداد محلي جيد يجيب بسرعة على سؤال واحد: هل يستطيع شخص جديد تشغيل التطبيق خلال أقل من 15 دقيقة دون تخمين؟
اختر نهجًا محليًا افتراضيًا وكن صريحًا. التثبيتات المحلية سريعة لمن لديهم الأدوات الصحيحة. الحاويات أكثر اتساقًا عبر الآلات لكنها تضيف عبئًا. إن دعمت كلا الخيارين، ضع واحدًا كافتراضي والآخر كاختياري.
نمط بسيط يعمل جيدًا: صفحة README واحدة، ملف env مثال واحد، وأمر bootstrap واحد.
التزم بملف مثال بقيم مزيفة حتى يعرف الناس ما الذي يجب ضبطه دون تسريب أسرار.
# .env.example (example values only)
APP_ENV=local
PORT=8080
DATABASE_URL=postgres://app_user:app_pass@localhost:5432/app_db?sslmode=disable
JWT_SECRET=change-me
API_BASE_URL=http://localhost:8080
في README، اشرح أين يعيش الملف الحقيقي (مثلاً، "انسخ إلى .env") وأي المتغيرات مطلوبة مقابل اختيارية.
أضف سكربت صغير يشغل الخطوات المملة بالترتيب الصحيح. اجعله مقروءًا.
#!/usr/bin/env bash
set -euo pipefail
cp -n .env.example .env || true
# Backend deps
cd backend
go mod download
# Database: create, migrate, seed
./scripts/db_create.sh
./scripts/db_migrate.sh
./scripts/db_seed.sh
# Frontend deps
cd ../web
npm install
لخطة قاعدة البيانات، وثّق ثلاثة أمور: كيفية إنشاء DB، كيف تُشغّل الهجرات، وكيف تحصل على بيانات seed لبدء واقعي.
أخيرًا، أضف فحص حالة سريع حتى يتمكن الناس من التأكد من أن التطبيق يعمل قبل الاستكشاف اليدوي. نقطة نهاية صغيرة مثل GET /health التي تُرجع "ok" (وتتحقق من اتصال قاعدة البيانات) غالبًا ما تكون كافية.
عند تصدير مشروع، قد تكون الشفرة ملكك، لكن الأسرار يجب أن تبقى خاصة. افترض أن المستودع سيتم مشاركته مع زملاء جدد.
ابدأ بسرد ما يحتاجه التطبيق للتشغيل. لا تُخمن. مرِّر الشفرة بحثًا عن قراءات التكوين (متغيرات بيئة، ملفات تكوين) وتحقق من أي تكاملات فعلتها.
جرد أساسي للأسرار عادةً يشمل بيانات اعتماد قاعدة البيانات، مفاتيح API لجهات خارجية، إعدادات المصادقة (OAuth أو JWT), بيانات التخزين، وأسرار تطبيقية مثل مفاتيح التشفير أو توقيع الويب هوك.
قرر أين يعيش كل سر في كل بيئة. قاعدة جيدة افتراضيًا:
.env مملوك للمطور (غير مُرتكَب)إذا صدرت من منصة دردشة-بناء مثل Koder.ai، افترض أن أي شيء ظهر في الدردشة، السجلات، أو لوحات الإعدادات قد نُسِخ. انقل الأسرار خارج المستودع فورًا.
نهج عملي هو الالتزام بقالب آمن (مثل .env.example)، إبقاء القيم الحقيقية خارج Git (.env في .gitignore)، وحقن أسرار الإنتاج وقت النشر.
إذا كان هناك احتمال أن تكون الأسرار قد تعرضت أثناء التصدير، دوّرها. أعطِ أولوية لكلمات مرور قواعد البيانات، أسرار عملاء OAuth، ومفاتيح توقيع الويب هوك.
أضف بعض الخطوط الحمراء حتى لا يتكرر الموقف: فحص pre-commit لأنماط أسرار واضحة، فحص أسرار في CI، تحميل تكوين صارم يفشل مبكرًا عند غياب متغيرات مطلوبة، واعتماد بيانات اعتماد منفصلة لكل بيئة.
مستند قصير SECRETS.md يساعد في التسليم. اجعله بسيطًا: المتغيرات المطلوبة، أين تُخزن لكل بيئة، ومن يمكنه تدويرها.
بمجرد أن تتولى الملكية، CI هو شبكة الأمان. اجعل النسخة الأولى صغيرة. يجب أن يثبت كل دفع أن المشروع ما زال يبنى، وفحوص أساسية تجتاز، والاختبارات (إن وُجدت) تعمل.
يجب أن يجيب CI عن سؤال واحد بسرعة: "هل هذا التغيير آمن للدمج؟" لمعظم المستودعات، يعني ذلك تثبيت التبعيات، البناء، التدقيق، وتشغيل اختبارات الوحدة.
قسّم الوظائف حسب جزء التطبيق ليكون مصدر الفشل واضحًا:
استخدم التخزين المؤقت، لكن لا تدع الكاش يخفي المشاكل. عندما يفشل الكاش، يجب أن يستمر CI بالعمل، فقط أبطأ.
فضّل أمرًا واحدًا لكل خطوة (make test, npm run test, وما شابه) بحيث يعمل نفس الأمر محليًا وفي CI. هذا يقلل الالتباس ويجعل السجلات أقصر.
شكل مثالي (عدّل الأسماء لمستودعك):
jobs:
web:
steps:
- run: npm ci
- run: npm run lint
- run: npm run build
api:
steps:
- run: go test ./...
- run: go build ./...
بعد استقرار الأساسيات، أضف سير إصدار بسيط: وسم الإصدارات، بناء المخرجات، وتخزينها كآثار CI. حتى لو ما زلت تنشر من منصة اليوم، المخرجات القابلة لإعادة الإنشاء تُسهِّل تغيير المضيف لاحقًا.
تصدير الشفرة هو نصف العمل فقط. النصف الآخر هو التأكد من أن المشروع يتصرف بنفس الطريقة خارج المنصة.
غالبًا ما تعتمد التصديرات على متغيرات بيئة، هجرات، بيانات seed، وخطوات بناء عُنيت بها المنصة. شاشة فارغة أو خطأ في قاعدة البيانات عند التشغيل الأول أمر طبيعي.
قم بتشغيل أساسي قبل تغيير أي شيء: ثبّت التبعيات، ضبط متغيرات البيئة، شغّل الهجرات، وابدأ الخدمات بالترتيب. أصلح ما يلزم فقط لتطابق الإعداد المتوقع.
الحادث الأكثر شيوعًا هو ارتكاب مفاتيح API أو كلمات المرور الحقيقية، عادة عبر نسخة .env أو ملف تكوين مولَّد. ارتكب قوالب فقط. احتفظ بالقيم الحقيقية في بيئتك المحلية أو مخزن أسرار.
ترقية الحزم أو إعادة تنظيم المجلدات فورًا يجعل من الصعب معرفة ما إذا كانت المشكلة من التصدير أم من تغييراتك.
احصل على تشغيل يعمل أولًا، ثم قدّم تحسينات في التزامات صغيرة ومنفصلة.
"يعمل على جهازي" غالبًا ما يأتي من إصدارات أدوات غير مثبتة (Node، Go، Flutter، وحتى مدراء الحزم).
ثبت إصدارات وقت التشغيل في مكان واضح (ملف أو README)، احتفظ بملفات القفل (package-lock, go.sum, pubspec.lock)، وتحقق من الإعداد على جهاز ثاني أو في حاوية نظيفة.
تسقط عمليات التسليم لأن لا أحد يتذكر الخطوة الغريبة المطلوبة لبدء التطبيق. دوِّنها بينما هي لا تزال جديدة: المتغيرات المطلوبة، كيفية تشغيل الهجرات، أين تذهب السجلات، وكيفية إعادة ضبط الحالة المحلية.
فريق من ثلاثة أشخاص يبني بوابة عملاء في Koder.ai: واجهة React، API بـ Go، وقاعدة PostgreSQL. عندما حان وقت تسليمها إلى فريق تطوير خارجي، أرادوا أن يبدو التصدير كمستودع عادي يمكن تشغيله من اليوم الأول.
اليوم 1: صدّروا، أنشأوا مستودع Git جديد، وشغّلوا محليًا. الواجهة بدأت، لكن الـ API فشل لأن متغيرات البيئة مفقودة. لم يخمنوا. قرأوا الشفرة، حدَدوا المفاتيح المطلوبة، وأنشأوا .env.example بقيم نائبة. القيم الحقيقية بقيت في مدير كلمات مرور وملفات .env محلية.
لاحظوا أيضًا أن المنافذ وإعدادات CORS كانت مضبوطة في المنصة لكن تحتاج إعدادًا محليًا. وضعوا قيم افتراضية متوقعة (مثلاً API على 8080 والويب على 3000) حتى تتصرف الأجهزة الجديدة بنفس الشكل.
اليوم 2: أضافوا هجرات وسكربت صغير لseed ينشئ مستخدمًا تجريبيًا وبعض الصفوف. ثم كتبوا README مختصر يغطي المتطلبات، أوامر التشغيل، وكيفية التحقق من العمل (نقطة صحة للـ API وتسجيل دخول تجريبي للواجهة).
اليوم 3: أضافوا سير عمل CI أساسي يشغّل الاختبارات، التدقيق، وبناء للخدمتين على كل طلب سحب. للمسرح، وثقوا خطة بسيطة: بناء الحاويات، ضبط الأسرار في البيئة، تشغيل الهجرات عند النشر، والحفاظ على خيار التراجع.
تسليم جيد عادةً يتضمن مستودعًا يعمل محليًا من استنساخ جديد، .env.example مع ملاحظات حول مكان الأسرار، هجرات وبيانات seed، فحوص CI تفشل سريعًا، ومذكرة نشر قصيرة للمسرح وخيارات التراجع.
قبل أن تعلن انتهاء التصدير، أثبت أن المشروع قادر على العيش خارج المنصة. إذا تمكن مطور آخر من تشغيله دون تخمين، فأنت في وضع جيد.
استخدم قائمة التحقق النهائية هذه:
بعد الفحص التقني، اجعل الملكية صريحة. قرر من يملك تحديثات التبعيات، تغييرات البنية التحتية (قواعد البيانات، الطوابير، DNS)، والإصدارات. إن لم يمتلك أحد هذه الأمور، يفسد المستودع بمرور الوقت حتى لو كان التطبيق يعمل اليوم.
خطّط لفترة تثبيت قصيرة قبل العمل على ميزات كبيرة. يومان إلى خمسة أيام عمل غالبًا كافيان لإصلاح حواف التصدير، تشديد README، وإزالة أخطاء "يعمل على جهازي".
إذا كنت تستخدم Koder.ai (Koder.ai)، تجعل الميزات مثل اللقطات والتراجع من الأسهل التكرار أثناء تشديد المستودع. بمجرد استقرار المستودع، احتفظ بـ Git كمصدر الحقيقة وعامل الصدورات المستقبلية كنقاط تفتيش، لا كالتاريخ الرئيسي.
حدِّد المعلم التالي للتسليم بلغة بسيطة: "أي مطور يمكنه تشغيله في 30 دقيقة." ثم اختبر ذلك بطلب شخص جديد يتبع README على جهاز نظيف. أسئلته تصبح قائمة المهام النهائية لديك.
عامل مفهوم الملكية على أنه الاستقلال: أن تكون قادرًا على بناء وتشغيل وتعديل ونشر التطبيق من مستودع عادي دون الحاجة إلى مشروع المنصة الأصلي، إعدادات واجهة المستخدم الخاصة بالمنصة، أو خطوات بناء مخفية.
اختبار جيد هو: هل يستطيع زميل جديد استنساخ المستودع وتشغيله باستخدام README فقط؟
ابدأ بفحص سريع للتمامية:
package.json, go.mod, pubspec.yaml).package-lock.json, yarn.lock, pnpm-lock.yaml, go.sum).migrations/ أو ما شابه).docker-compose.yml).إذا كان أي شيء مطلوب للتشغيل موصوفًا فقط في واجهة أو دردشة، فاكتبه ونقله إلى المستودع.
افعلها بخطوات صغيرة وقابلة للتحقق:
.env.example → .env.لا تعيد التنظيم فورًا—أثبت أولًا أن المشروع يعمل كما هو، ثم حسِّن في التزامات منفصلة.
لأن البيئة المستضافة عادةً تحتوي على أمور لم تقم بتوثيقها صراحة:
حلّ ذلك بجعل الإعداد مرئيًا: .env.example، سكربتات الهجرة، وREADME بأوامر محددة.
تشغيل الخادم ليس كافيًا—تحقق من تدفق البيانات الفعلي:
إن لم تتمكن من تكرار تغييرات البيانات محليًا reliably، فإعدادك أو هجراتك غير كاملة.
نهج افتراضي آمن:
.env.example بقيم وهمية..env إلى .gitignore.إذا وجدت مفاتيح حقيقية في المستودع، افترض أنها تعرضت وانفذ تدويرًا لها فورًا. ابدأ بأولوية كلمات مرور قواعد البيانات، أسرار OAuth، ومفاتيح توقيع الويب هوك.
اجعل أول نسخة من CI صغيرة ومتطابقة مع الأوامر المحلية:
go test ./... وبناء الـ backend.اجعل CI يستدعي نفس السكربتات التي يُفترض أن يشغّلها المطورون (مثل make test أو npm run build). هذا يقلل من حالات "يعمل محليًا لكن يفشل في CI".
نعم—إذا أردت تسليمًا موثوقًا. إعداد افتراضي جيد يكون:
.env.example يشرح المتغيرات المطلوبة مقابل الاختيارية.هدفك أن يتمكن مطور جديد من تشغيل التطبيق خلال 15–30 دقيقة دون تخمين.
هيكل شائع:
apps/ للواجهات (web, mobile).services/ لواجهات الـ API والعمّالات.shared/ للأنواع والمرافق المشتركة.infra/ لقوالب النشر وأمثلة البيئة.الأسماء الدقيقة أقل أهمية من أن يكون المكان واضحًا لما يعمل أين وكيف تتصل الأجزاء ببعضها.
خطة عملية:
بمجرد الاستقرار، اعتبر Git مصدر الحقيقة وأي صادرات مستقبلية من المنصة كـنقاط تفتيش، لا كالتاريخ الرئيسي.