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

1- مقدمة

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

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

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

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

ما ستتعلمه

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

ما ستجرّبه

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

ما تحتاج إليه

قبل البدء

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

2. إعداد مساحة العمل

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

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

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

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

45e7241be5552e42.png

  1. انقر على "فتح مساحة عمل جديدة" وسمِّ مساحة العمل 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/: مساحة العمل المخصّصة للرمز البرمجي للتطبيق الفعلي. سينشئ وكيل "مهندس التطوير الشامل" جميع الرموز البرمجية (مثل package.json وapp.py ومكوّنات React) ويحفظها مباشرةً في هذا المجلد، ما يؤدي إلى فصل مصدر التطبيق عن تعليمات الذكاء الاصطناعي.

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

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

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

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

يحل ملف agents.md هذه المشكلة من خلال تركيز الشخصيات المختلفة لفريقك:

  1. مدير المنتج (@pm): يركّز فقط على الصورة الكبيرة. يكتب ملف Technical_Specification.md ويدير عملية الموافقة المتبادلة معك (أنت، الشخص البشري).
  2. مهندس التطوير الشامل (@engineer): لا يهتم بالتخطيط، بل يأخذ مواصفات مدير المنتج ويركّز بالكامل على كتابة رموز برمجية عالية الجودة بأي لغة توافق عليها.
  3. مهندس تأكيد الجودة (@qa): يعمل كشخص جديد يراجع العمل. بدلاً من كتابة ميزات جديدة، يركّز فقط على العثور على التبعيات المفقودة أو أخطاء البنية أو الأخطاء المنطقية في رمز المهندس.
  4. مسؤول DevOps (@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!

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

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

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

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

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

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

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

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

أنشئ .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!

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

يتصرّف الوكيل كمهندس 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، يمكنك تشغيل سير العمل بالكامل بسهولة.

اطلب من 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. يصبح Gemini مهندس تأكيد الجودة، ويصلح أي أخطاء، ويحفظ الرمز النهائي.
  5. أخيرًا، يثبِّت مسؤول DevOps الوحدات بشكل ديناميكي ويعرض التطبيق في متصفحك.

مثال على تشغيل Technical_Specification.md والانتظار للحصول على الموافقات أو التعليقات

11defe4c48e874cc.png

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

b9af07291806ae60.png

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

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

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

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