إنشاء مسارات تطوير ذاتية التشغيل باستخدام ملفات agents.md وskills.md في Antigravity

1. مقدمة

في هذا الدرس التطبيقي حول الترميز، سنوضّح لك كيفية إعداد "فريق تطوير الذكاء الاصطناعي المستقل" الممتع والمستند إلى الذكاء الاصطناعي مباشرةً على جهاز الكمبيوتر باستخدام بيئة تطوير Antigravity المتكاملة. ستنشئ تطبيقًا عمليًا من خلال توجيه أحد المتطلبات خلال دورة حياته الكاملة، بدءًا من المواصفات الفنية وصولاً إلى النشر النهائي، وذلك باستخدام سير عمل قوي skills.md وagents.md.

بدلاً من أن تكون مقيّدًا بحزمة تكنولوجيا معيّنة أو كتابة نصوص برمجية معقّدة لتنظيم Python، سنستخدم أسلوبًا بسيطًا بدون رموز برمجية حيث تتدفّق متطلباتك خلال دورة مبرمَجة تستند إلى ثلاثة مبادئ أساسية في Antigravity:

  1. agents.md: لتحديد أعضاء فريق الذكاء الاصطناعي بدقة (مدير المنتج، والواجهة الأمامية، وضمان الجودة، وتطوير العمليات).
  2. المهارات وملف skills.md: دليل مخصّص تحدّد فيه قدرات فنية قوية وقواعد تسليم العناصر كملفات .md معيارية.
  3. سير العمل (workflows/): لتحديد أوامر مخصّصة تبدأ بشرطة مائلة وتجمع أعضاء فريق الذكاء الاصطناعي معًا بسلاسة في مسار مستقل.

من خلال الجمع بين هذه العناصر الثلاثة بشكلٍ مدمج في Antigravity، ستوجّه Gemini لأتمتة عملية تطوير تطبيق جاهز للإنتاج بالكامل من البداية إلى النهاية.

ما ستتعلمه

  • إعداد Workspace: يمكنك إعداد مشروعك ليفهمه Antigravity بشكل كامل.
  • تحديد الفريق: أنشئ ملف agents.md لتحديد شخصيات الذكاء الاصطناعي المتخصّصة.
  • برمجة المهارات: أنشئ ملفات .md تفصيلية في دليل skills/ لتحديد قواعد فنية صارمة وحلقات إعادة صياغة متكررة.
  • تحديد مهام سير العمل المخصّصة: أنشئ أمر يبدأ بشرطة مائلة /startcycle لتنفيذ مهام سير العمل في الاستوديو آليًا.
  • بدء التفاعل المتسلسل: استخدِم أمرًا واحدًا لتنفيذ خط أنابيب الوكلاء المتعددين بالكامل تلقائيًا وبكفاءة.

ما يمكنك تجربته

  • كيفية فصل هندسة طلبات الذكاء الاصطناعي عن الرمز البرمجي للتطبيق
  • كيفية إنشاء وكيل يتوقف مؤقتًا بشكل نشط لتفسير تعليقات المستخدمين وتعديلاتهم داخل ملفات Markdown التي تم إنشاؤها
  • كيفية بناء مهارات إنشاء الرموز البرمجية ونشرها بشكل ديناميكي وبدون الاعتماد على لغة معيّنة
  • كيفية إنشاء أوامر وحدات ماكرو مخصّصة (مهام سير العمل) في بيئة تطوير متكاملة (IDE) قائمة على الوكلاء

المتطلبات

قبل البدء

بالنسبة إلى أرصدة Google Cloud: لمساعدتك في استخدام Antigravity مع مشاريع Google Cloud، يمكنك تحصيل قيمة أرصدة Google Cloud المجانية باستخدام هذا الرابط. يمكنك اتّباع التعليمات هنا لتفعيل الرصيد وإنشاء مشروع جديد.

  1. تأكَّد من تثبيت بيئة التطوير المتكاملة Antigravity (متوفّرة على antigravity.google).
  2. افتح بيئة التطوير المتكاملة (IDE) في Antigravity وتأكَّد من تهيئة مساحة عمل جديدة ومخصّصة.
  3. يجب أن تكون نافذة طرفية مفتوحة أثناء العمل في وضع "المحرّر".

2. تهيئة مساحة العمل

بما أنّ Antigravity تفهم بشكلٍ أصلي ملفات سير العمل الموضوعة في الدليل .agents، فإنّ إعداد مسار المطوّر المستقل لا يتطلّب سوى إنشاء بعض المجلدات العادية.

يمكنك إعداد مساحة العمل باتّباع الخطوات التالية:

  1. افتح Antigravity IDE.
  2. افتح إدارة العملاء في أي وقت، يمكنك التبديل بين "إدارة العملاء" والمحرّر من خلال الضغط على CMD+E (في أجهزة Mac) أو CTRL+E (في أجهزة Windows)، أو من خلال الزرّين "فتح المحرّر" و"فتح إدارة العملاء" في أعلى يسار شريط القوائم. .
  3. انقر على + فتح مساحة عمل.

لبدء محادثة جديدة في مساحة عمل، اختَر مساحة العمل المطلوبة من علامة التبويب "بدء محادثة" أو انقر على زر علامة الجمع بجانب اسم مساحة العمل في الشريط الجانبي.

45e7241be5552e42.png

  1. انقر على "فتح مساحة عمل جديدة" (Open New Workspace) وأدخِل اسمًا لمساحة العمل skills-codelab واختَر دليلًا محليًا. يضمن ذلك توفّر مجلد جذر محدّد لدى "الوكيل" لإنشاء ملفات بدون إحداث فوضى في المشاريع الأخرى. بعد الانتهاء، انتقِل إلى "طريقة عرض المحرّر" ثم إلى الخطوات (5) و(6) و (7).

d84ba507939a5efc.png

  1. انقر بزر الماوس الأيمن وأنشئ مجلدًا باسم skills-codelab.
  2. أنشئ داخلها مجلّدين: production_artifacts وapp_build.
  3. أنشئ الدليل .agents، ثم أنشئ داخله المجلّدَين workflows وskills.

(بدلاً من ذلك) إذا كنت تفضّل استخدام نافذة الأوامر، يمكنك إنشاء هذه البنية على الفور من خلال تنفيذ الأمر التالي:

mkdir skills-codelab && cd skills-codelab
mkdir -p .agents/workflows .agents/skills
mkdir production_artifacts app_build

تأكَّد من أنّ مجلدك يظهر على النحو التالي:

7234ea48c2b175a7.png

ما هي وظيفة هذه المجلدات الجديدة؟

  • ‫.agents/: هذا دليل خاص يتعرّف عليه Antigravity تلقائيًا. من خلال وضع الملفات هنا، يمكنك توسيع نطاق سلوك الذكاء الاصطناعي المضمّن في Antigravity.
  • ‫skills/: يُستخدَم هذا المجلد لتخزين أدلة تعليمات فنية معيّنة (ملفات .md) خاصة بالذكاء الاصطناعي. يخبر هذا النظام الذكاء الاصطناعي بكيفية تنفيذ مهام معيّنة، مثل كتابة الرموز البرمجية أو نشر التطبيقات، ما يتيح استبدال الطلب الكبير والمربك بخطوات نموذجية.
  • production_artifacts/: هذا هو المجلد المشترك الذي سيضع فيه أعضاء فريقنا الآلي الملفات عمدًا ليقرأها الوكيل التالي.
  • ‫app_build/: مساحة العمل المخصّصة للرمز البرمجي الفعلي للتطبيق. سينشئ وكيل "مهندس Full-Stack" كل الرموز البرمجية (مثل package.json وapp.py ومكوّنات React) ويحفظها مباشرةً في هذا المجلد، ما يؤدي إلى عزل مصدر التطبيق عن تعليمات الذكاء الاصطناعي.

3- تحديد الفريق (agents.md)

أولاً، علينا إخبار Antigravity بمن يعمل على هذا المشروع. بدلاً من الاحتفاظ بالتعليمات في أربعة مجلدات مشاريع متداخلة مختلفة، نركّز على هوية فريقنا. أنشئ ملفًا في .agents/agents.md:

لماذا نحتاج إلى شخصيات مختلفة؟

عندما تطلب من الذكاء الاصطناعي إنشاء تطبيق كامل من البداية، يمكن أن يواجه صعوبة كبيرة إذا أجبرته على أن يكون المصمّم والمبرمج والمختبِر وقائد عملية النشر في الوقت نفسه. من خلال تجميع هذه الأدوار في agents.md، يمكنك منع الذكاء الاصطناعي من الخلط بينها. يركّز مدير المنتج على المتطلبات فقط، ويركّز المهندس على إنشاء الرموز البرمجية فقط، ويركّز فريق ضمان الجودة على إصلاح الأخطاء فقط. يمكنك الاستعانة بخبراء متخصصين في كل مرحلة من مراحل مسار المبيعات.

يحلّ ملف agents.md هذا المشكلة من خلال تجميع مختلف شخصيات فريقك في مكان واحد:

  1. مدير المنتج (@pm): يركّز فقط على الصورة الكبيرة. يكتبون ملف Technical_Specification.md ويديرون عملية الموافقة المتبادلة معك (المستخدم).
  2. مهندس Full-Stack (@engineer): لا يهتم بالتخطيط، بل يكتفي باتّباع مواصفات مدير المنتج ويركّز بشكل كامل على كتابة رموز برمجية عالية الجودة بأي لغة توافق عليها.
  3. مهندس ضمان الجودة (@qa): يعمل كعين جديدة. وبدلاً من كتابة ميزات جديدة، ينصبّ تركيزهم فقط على العثور على التبعيات الناقصة أو أخطاء البنية أو أخطاء المنطق في رمز المهندس.
  4. الخيار "DevOps Master" (@devops): يركّز بشكل صارم على بيئة وقت التشغيل. ويعرفون كيفية قراءة نافذة الأوامر وتثبيت الحِزم (npm install وpip install) وبدء الخادم المحلي.
# 🤖 The Autonomous Development Team

## The Product Manager (@pm)
You are a visionary Product Manager and Lead Architect with 15+ years of experience.
**Goal**: Translate vague user ideas into comprehensive, robust, and technology-agnostic Technical Specifications.
**Traits**: Highly analytical, user-centric, and structured. You never write code; you only design systems.
**Constraint**: You MUST always pause for explicit user approval before considering your job done. You are highly receptive to user feedback and will enthusiastically re-write specifications based on inline comments.

## The Full-Stack Engineer (@engineer)
You are a 10x senior polyglot developer capable of adapting to any modern tech stack.
**Goal**: Translate the PM's Technical Specification into a beautiful, perfectly structured, production-ready application.
**Traits**: You write clean, DRY, well-documented code. You care deeply about modern UI/UX and scalable backend logic.
**Constraint**: You strictly follow the approved architecture. You do not make assumptions—if the spec says Python, you use Python. You always save your code into the `app_build/` directory.

## The QA Engineer (@qa)
You are a meticulous Quality Assurance engineer and security auditor.
**Goal**: Scrutinize the Engineer's code to guarantee production-readiness.
**Traits**: Detail-oriented, paranoid about security, and relentless in finding edge cases.
**Focus Areas**: You aggressively hunt for missing dependencies in configurations, unhandled promises, syntax errors, and logic bugs. You proactively fix them.

## The DevOps Master (@devops)
You are the elite deployment lead and infrastructure wizard.
**Goal**: Take the final code in `app_build/` and magically bring it to life on a local server.
**Traits**: You excel at terminal commands and environment configurations.
**Expertise**: You fluently use tools like `npm`, `pip`, or native runners. You install all necessary modules seamlessly and provide the local URL directly to the user so they can see the final product!

لاحظ كيف نحدّد الأهداف والسمات والقيود لكل شخصية.

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

يؤدي تنظيم الطلبات بهذه الطريقة إلى تقليل الهلوسة التي قد يقدّمها الذكاء الاصطناعي بشكل كبير ويضمن التزام الوكيل بسير العمل المطلوب بدقة.

تأكَّد من أنّ مجلدك يظهر على النحو التالي:

4. برمجة المهارات المتخصّصة (skills/)

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

1. مهارة المواصفات

تشكّل هذه المهارة نقطة البداية. يستخدم وكيل PM هذه المعلومات لإجراء مقابلة معك وتفصيل التصميم قبل كتابة أي رمز برمجي، ما يمنع إضاعة ساعات في كتابة رموز برمجية قد لا تكون مفيدة.

إنشاء .agents/skills/write_specs.md:

# Skill: Write Specs

## Objective
Your goal as the Product Manager is to turn raw user ideas into rigorous technical specifications and **pause for user approval**.

## Rules of Engagement
- **Artifact Handover**: Save all your final output back to the file system.
- **Save Location**: Always output your final document to `production_artifacts/Technical_Specification.md`.
- **Approval Gate**: You MUST pause and actively ask the user if they approve the architecture before taking any further action.
- **Iterative Rework**: If the user leaves comments directly inside the `Technical_Specification.md` or provides feedback in chat, you must read the document again, apply the requested changes, and ask for approval again!

## Instructions
1. **Analyze Requirements**: Deeply analyze the user's initial idea request.
2. **Draft the Document**: Your specification MUST include:
   - **Executive Summary**: A brief, high-level overview.
   - **Requirements**: Functional and non-functional requirements.
   - **Architecture & Tech Stack**: Suggest the absolute best framework (e.g., Python/Django, Node/Express, React/Next.js) for the job and outline the layout/API structure.

   - **State Management**: Briefly outline how data should flow.
3. Save the document to disk.
4. **Halt Execution**: Explicitly ask the user: "Do you approve of this tech stack and specification? You can safely open `Technical_Specification.md` and add comments or modifications if you want me to rework anything!" Wait for their "Yes" or feedback before the sequence continues!

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

2. مهارة إنشاء الحزمة الكاملة

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

إنشاء .agents/skills/generate_code.md:

# Skill: Generate Code

## Objective
Your goal as the Full-Stack Engineer is to write the physical code based entirely on the PM's approved specification.

## Rules of Engagement
- **Dynamic Coding**: You are not limited to HTML/JS. You must write code in the exact language/framework defined in the approved `Technical_Specification.md`.
- **Save Location**: Save all your raw code, accurately retaining necessary folder structures, directly inside `app_build/`.

## Instructions
1. **Read the Spec**: Open and carefully study `production_artifacts/Technical_Specification.md`.
2. **Scaffold Structure**: Generate all core backend and frontend application files.
3. **Output**: Dump your code perfectly into the `app_build/` directory. Do not skip or summarize any code blocks. Ensure all `package.json` or `requirements.txt` files are present.

لا تتضمّن هذه المهارة حزمة محدّدة مسبقًا (مثل Next.js أو Django). ويعتمد بشكل صريح على مجموعة التكنولوجيات الديناميكية التي يختارها مدير المنتج. هذا يعني أنّ مهارة إنشاء الرموز البرمجية الفردية تعمل مع أي إطار عمل وافقت عليه في المواصفات.

3. مهارة التدقيق

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

إنشاء .agents/skills/audit_code.md:

# Skill: Audit Code

## Objective
Your goal as the QA Engineer is to ensure the generated code is perfectly functional natively.

## Rules of Engagement
- **Target Context**: Your focus area is the `app_build/` directory.

## Instructions
1. **Assess Alignment**: Compare the raw code against the approved `Technical_Specification.md`.
2. **Bug Hunting**: Find and fix dependency mismatches, unhandled errors, and logic breaks.
3. **Commit Fixes**: Overwrite any flawed files in `app_build/` with your polished revisions.

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

4. مهارة النشر الديناميكي

تضفي هذه المهارة الحيوية على التطبيق. يحدّد وكيل DevOps نوع التطبيق الذي تم إنشاؤه (Node أو Python أو غير ذلك) وينفّذ بأمان أوامر الوحدة الطرفية اللازمة لتثبيت الوحدات وبدء تشغيل الخادم.

إنشاء .agents/skills/deploy_app.md:

# Skill: Deploy App

## Objective
Your goal as DevOps is to intelligently package the application and fire up a server based on the chosen stack.

## Instructions
1. **Stack Detection**: Inspect the `Technical_Specification.md` and the files in `app_build/` to figure out what stack is being used.

2. **Install Dependencies**: Use your native terminal to navigate into `app_build/` and run `npm install`, `pip install -r requirements.txt`, or whatever is appropriate!

3. **Host Locally**: Execute the appropriate native terminal command (e.g., `npm run dev`, `python3 app.py`) to start a background server.
4. **Report**: Output the clickable localhost link to the user and celebrate a successful launch!

نستفيد من قدرة بيئة التطوير المتكاملة على تنفيذ أوامر الطرفية الأصلية بأمان.

يعمل البرنامج المساعد كمهندس DevOps حقيقي، حيث يحدّد بشكل ديناميكي أمر التثبيت الذي سيتم تنفيذه استنادًا إلى الملفات التي يراها فعليًا في المجلد app_build/.

(اختياري) 5. مهارة نشر Cloud Run

إذا كنت تريد نقل تطبيقك مباشرةً إلى مرحلة الإنتاج بدلاً من تشغيله محليًا فقط، يمكنك إنشاء مهارة نشر بديلة. بما أنّ Antigravity تعمل مباشرةً على جهازك، يمكن للذكاء الاصطناعي استخدام gcloud CLI الذي تمّت مصادقته على جهازك بسلاسة.

إنشاء .agents/skills/deploy_cloud_run.md:

# Skill: Deploy to Cloud Run

## Objective
Your goal as DevOps is to package the application into a container and deploy it to Google Cloud Run.

## Instructions
1. **Verify Environment**: Ensure the necessary files for the chosen tech stack are in `app_build/`.
2. **Containerize**: Use the IDE terminal to navigate to `app_build/` and run `gcloud run deploy --source .`. 
3. **Configure**: If prompted by the CLI tool, automatically select the default region and allow unauthenticated invocations so the web app is public.
4. **Report**: Output the live production Google Cloud Run URL to the user!

5- تحديد أمر مخصّص يبدأ بشرطة مائلة

ما هي وظيفة الأمر المخصّص الذي يبدأ بشرطة مائلة؟

من خلال حفظ هذا الملف النصي داخل .agents/workflows/ ، يمكنك تسجيل أمر جديد تمامًا مباشرةً في واجهة الدردشة في Antigravity.

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

إنشاء .agents/workflows/startcycle.md:

---
description: Start the Autonomous AI Developer Pipeline sequence with a new idea
---

When the user types `/startcycle <idea>`, orchestrate the development process strictly using `.agents/agents.md` and `.agents/skills/`.

### Execution Sequence:
1. Act as the **Product Manager** and execute the `write_specs.md` skill using the `<idea>`.
   *(Wait for the user to explicitly approve the spec. If the user provides feedback or adds comments directly to the Markdown file, act as the PM again to re-read and revise the document. Loop this step until they type "Approved").*
2. Shift context, act as the **Full-Stack Engineer**, and execute the `generate_code.md` skill.
3. Shift context, act as the **QA Engineer**, and execute the `audit_code.md` skill.
4. Shift context, act as the **DevOps Master**, and execute the `deploy_app.md` skill.

تأكَّد من أنّ مجلدك يظهر على النحو التالي:

de21eeb6012ddbcd.png

6. لنبدأ التفاعل المتسلسل!

بعد تحديد فريقك وقواعدك رسميًا في Antigravity، يمكنك بدء سير العمل بالكامل بدون عناء.

Prompt Antigravity:

  1. في مربّع محادثة "أداة إدارة العملاء"، اكتب / لفتح قائمة الأوامر المخصّصة. اختَر startcycle أو اكتبه.
  2. قدِّم فكرتك:
/startcycle "I need a fast, real-time chat application for customer support on my ecommerce website."

الاسترخاء والتعاون:

  1. يصبح Gemini مدير المنتج، ويضع مسودة مواصفات قوية، ويطلب موافقتك.
  2. افتح Technical_Specification.md في محرّر بيئة التطوير المتكاملة (IDE)، وأضِف بعض الملاحظات (مثل "لنستخدِم لغة Python بدلاً من Node")، واطلب من الوكيل إعادة صياغتها. سيتم تعديل الملف تلقائيًا.
  3. بعد الموافقة على الطلب، ينقل Gemini السياق تلقائيًا إلى "مهندس"، ويستخدم المواصفات المُعتمدة لكتابة الرمز البرمجي للخادم الخلفي أو الواجهة الأمامية.
  4. يصبح مهندس تأكيد الجودة، ويصلح أي أخطاء، ويحفظ الرمز النهائي.
  5. أخيرًا، يقوم DevOps Master بتثبيت الوحدات بشكل ديناميكي وعرض التطبيق في متصفحك.

مثال على تنفيذ Technical_Specification.md وانتظار الموافقات أو التعليقات

11defe4c48e874cc.png

بعد موافقة المستخدم على الطلب، يبدأ مسار العمل بأكمله.

b9af07291806ae60.png

7. الملخّص والخطوات التالية

تهانينا! لقد تعلّمت كيفية إدخال "حلقات التكرار التعاوني" وإنشاء تطبيقات ديناميكية كاملة الميزات في مسار آلي يعتمد على وكيل.

في هذا الدرس التطبيقي حول الترميز، تناولنا ما يلي:

  • كيفية ربط شخصيات الذكاء الاصطناعي باستخدام .agents/agents.md
  • إنشاء حلقات إعادة صياغة تعاونية داخل .agents/skills/write_specs.md لكي يقرأ الوكيل تعليقاتك المضمّنة بتنسيق Markdown
  • تم إنشاء مهارات ديناميكية .md تكتب الرموز البرمجية في أي إطار عمل (Python وReact) استنادًا إلى المواصفات المعتمدة.