برنامه‌ریزی و ساخت برنامه‌ها با افزونه Conductor

۱. مقدمه

در این آزمایشگاه کد، شما یاد خواهید گرفت که چگونه با افزونه Conductor، برنامه‌های نرم‌افزاری را برنامه‌ریزی و بسازید. Conductor یک افزونه متن‌باز ساخته شده توسط گوگل است که ویژگی‌های توسعه مبتنی بر مشخصات مانند برنامه‌ریزی و ردیابی پیاده‌سازی را فعال می‌کند. شما با ساخت یک برنامه "greenfield" به طور کامل از ابتدا شروع خواهید کرد. سپس، با آن به عنوان یک پروژه "brownfield" رفتار خواهید کرد و برای اضافه کردن احراز هویت و ذخیره‌سازی، آن را تکرار خواهید کرد.

کاری که انجام خواهید داد

  • افزونه Conductor را در Antigravity CLI یا Claude Code نصب کنید.
  • با استفاده از قابلیت‌های برنامه‌ریزی و پیاده‌سازی Conductor، یک برنامه وب "Picker Wheel" را از ابتدا بسازید.
  • با افزودن احراز هویت و ذخیره‌سازی با استفاده از Firebase، شخصی‌سازی را به برنامه اضافه کنید

آنچه یاد خواهید گرفت

  • نحوه استفاده از افزونه Conductor برای برنامه‌ریزی، پیاده‌سازی و بررسی یک برنامه "greenfield"
  • نحوه استفاده از افزونه Conductor برای افزودن ویژگی‌ها به یک برنامه "brownfield"

آنچه نیاز دارید

  • یک مرورگر وب مانند کروم
  • یک پروژه گوگل کلود با قابلیت پرداخت صورتحساب
  • نصب Node.js (نسخه ۱۸+ توصیه می‌شود)
  • یک ویرایشگر کد محلی مانند Visual Studio Code
  • یک عامل کدنویسی مانند Antigravity CLI یا Claude Code

۲. قبل از شروع

ایجاد یک پروژه ابری گوگل

  1. در کنسول گوگل کلود ، در صفحه انتخاب پروژه، یک پروژه گوگل کلود را انتخاب یا ایجاد کنید .
  2. مطمئن شوید که صورتحساب برای پروژه ابری شما فعال است. یاد بگیرید که چگونه بررسی کنید که آیا صورتحساب در یک پروژه فعال است یا خیر .

شروع پوسته ابری

Cloud Shell یک محیط خط فرمان است که در Google Cloud اجرا می‌شود و ابزارهای لازم از قبل روی آن بارگذاری شده‌اند.

  1. روی فعال کردن Cloud Shell در بالای کنسول Google Cloud کلیک کنید.
  2. پس از اتصال به Cloud Shell، احراز هویت خود را تأیید کنید: 
    gcloud auth list
  3. تأیید کنید که پروژه شما پیکربندی شده است: 
    gcloud config get project
  4. اگر پروژه شما مطابق انتظار تنظیم نشده است، آن را تنظیم کنید: 
    export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project $PROJECT_ID

فعال کردن APIها

API مدیریت Firebase را در پروژه Google Cloud خود فعال کنید.

gcloud services enable firebase.googleapis.com

فایربیس را به پروژه خود اضافه کنید

رابط خط فرمان فایربیس (Firebase CLI) به صورت پیش‌فرض در کلود شل (Cloud Shell) نصب شده است. از کلود شل، با همان حساب گوگلی که به شما امکان دسترسی به پروژه گوگل کلود را می‌دهد، وارد سیستم شوید. اگر به صورت محلی کار می‌کنید، رابط خط فرمان فایربیس را با دنبال کردن دستورالعمل‌ها نصب کنید.

firebase login

برای اضافه کردن Firebase به پروژه Google Cloud خود، دستور زیر را اجرا کنید:

firebase projects:addfirebase

اگر این اولین باری است که رابط خط firebase را اجرا می‌کنید، به هر سوالی که از شما پرسیده می‌شود پاسخ دهید.

خروج از پوسته ابری

می‌توانید پنجره Cloud Shell را ببندید. در بخش بعدی، محیط محلی شما را پیکربندی خواهیم کرد.

۳. نصب و احراز هویت عوامل کدنویسی CLI

در این مرحله، با نصب و تأیید اعتبار Antigravity CLI یا Claude Code در ویرایشگر کد محلی خود با استفاده از اعتبارنامه‌های Google Cloud خود، محیط توسعه محلی خود را آماده خواهید کرد.

نصب و احراز هویت رابط خط فرمان آنتی‌گراویتی (Antigravity CLI)

  1. آخرین نسخه Antigravity CLI را نصب کنید . 
    # MacOS and Linux
curl -fsSL https://antigravity.google/cli/install.sh | bash

# Windows Powershell
irm https://antigravity.google/cli/install.ps1 | iex

# Windows CMD
curl -fsSL https://antigravity.google/cli/install.cmd -o install.cmd && install.cmd && del install.cmd
  2. ترمینال خود را مجدداً راه‌اندازی کنید تا agy به PATH شما اضافه شود.
  3. تأیید کنید که نصب‌کننده آخرین نسخه را نصب کرده است. 
    agy --version
  4. با استفاده از اعتبارنامه‌های Google Cloud خود ، احراز هویت کنید .
    • رابط خط فرمان آنتی‌گراویتی (Antigravity CLI) را اجرا کنید. 
      agy
    • وقتی از شما پرسیده شد که روش ورود را انتخاب کنید ، گزینه «استفاده از پروژه Google Cloud» را انتخاب کنید. URL مجوز امن را در یک مرورگر وب باز کنید. با اعتبارنامه تأیید شده خود وارد شوید و احراز هویت را تکمیل کنید. مرورگر یک کد مجوز الفبایی عددی منحصر به فرد را نمایش می‌دهد. این کد را کپی کنید، به ترمینال خود برگردید و آن را در اعلان جایگذاری کنید.
  5. از رابط خط فرمان Antigravity خارج شوید. برای پایان دادن به جلسه‌ی زنده‌ی Antigravity CLI خود، قبل از ادامه، عبارت /exit را در ترمینال CLI تایپ کنید.

نصب و تأیید اعتبار کد کلود

به عنوان یک روش جایگزین، می‌توانید از افزونه Conductor به همراه Claude Code استفاده کنید. در اینجا ما Claude Code را با استفاده از اعتبارنامه‌های Google Cloud شما نصب و احراز هویت خواهیم کرد.

  1. آخرین نسخه کلود کد را نصب کنید .
  2. با استفاده از اعتبارنامه‌های Google Cloud خود ، احراز هویت کنید .
    • کلود کد را شروع کنید. 
      claude
    • برای انتخاب روش ورود، عبارت /login تایپ کنید. گزینه پلتفرم شخص ثالث · Amazon Bedrock، Microsoft Foundry یا Vertex AI و Google Vertex AI را انتخاب کنید. برای تنظیم Google Vertex AI، گزینه Application Default Credentials (google auth) را انتخاب کنید و تنظیمات را طبق دستورالعمل تکمیل کنید.
  3. کلود کد را دوباره راه اندازی کنید .

۴. افزونه Conductor را نصب کنید

Conductor یک افزونه متن‌باز ساخت گوگل است که ویژگی‌های توسعه مبتنی بر مشخصات مانند برنامه‌ریزی و ردیابی پیاده‌سازی را فعال می‌کند.

نصب در Antigravity CLI

  1. افزونه را نصب کنید :
    • رابط خط فرمان ضد جاذبه 
      agy plugins install https://github.com/gemini-cli-extensions/conductor
  2. نصب را تأیید کنید :
    • رابط خط فرمان آنتی‌گراویتی (Antigravity CLI) را اجرا کنید. 
      agy
    • عبارت /conductor ‎ را تایپ کنید تا فهرستی از دستورات مانند /conductor:conductor-setup ‎، /conductor:conductor-new-track ‎، conductor:conductor-implement ‎ و غیره را مشاهده کنید.
  3. از رابط خط فرمان (CLI) خارج شوید . برای پایان دادن به جلسه خط فرمان زنده خود، قبل از ادامه، عبارت /exit در ترمینال تایپ کنید.

نصب در کلود کد

  1. مخزن بازار را ثبت کنید و افزونه Conductor را مستقیماً در جلسه Claude Code خود نصب کنید. 
    /plugin marketplace add gemini-cli-extensions/conductor
/plugin install conductor
/reload-plugin
  2. نصب را تأیید کنید .
    • عبارت /conductor ‎ را تایپ کنید تا فهرستی از دستورات مانند /conductor-setup ‎، conductor-new-track ‎، conductor-implement ‎ و غیره را مشاهده کنید.
  3. از رابط خط فرمان (CLI) خارج شوید . برای پایان دادن به جلسه زنده رابط خط فرمان (CLI) خود، قبل از ادامه، عبارت /exit در ترمینال Claude Code تایپ کنید.

۵. توسعه فضای سبز: چرخ انتخاب

اکنون که محیط شما راه‌اندازی شده است، یک برنامه جدید را از ابتدا خواهید ساخت. شما یک "Picker Wheel" ایجاد خواهید کرد - یک برنامه وب سبک که برای انتخاب یک گزینه تصادفی می‌چرخد.

زمینه محصول را تنظیم کنید

  1. یک دایرکتوری پروژه جدید ایجاد کنید و به آن بروید . اکنون ما روی یک پروژه در دایرکتوری picker-wheel کار می‌کنیم. این دایرکتوری را ایجاد کنید و به آن بروید. 
    mkdir picker-wheel
cd picker-wheel
  2. شروع رابط خط فرمان آنتی‌گراویتی (Antigravity CLI) . یک جلسه رابط خط فرمان جدید را از دایرکتوری پروژه خود با رابط خط فرمان آنتی‌گراویتی یا کد کلود (Claude Code) شروع کنید. 
    # Antigravity CLI
agy

# Claude Code
claude
    • وقتی از شما پرسیده شد «آیا به فایل‌های این پوشه اعتماد دارید؟»، گزینه Trust folder (انتخابگر چرخ) را انتخاب کنید.
  3. مقداردهی اولیه Conductor . دستور setup را برای ایجاد چارچوب پروژه و راه‌اندازی محیط Conductor اجرا کنید. 
    # Antigravity CLI
/conductor:conductor-setup

# Claude Code
/conductor-setup
  4. دستورالعمل‌های تعاملی را دنبال کنید . دستورالعمل‌های تعاملی که می‌بینید دقیقاً با این مثال‌ها مطابقت ندارند. برای آشنایی با گردش کار Conductor، روی یک طرح ساده‌تر تمرکز کنید.
    • هدف محصول : یک برنامه وب که یک چرخ گردان قابل تنظیم را برای انتخاب یک مورد تصادفی از یک لیست نمایش می‌دهد.
      • مخاطب هدف → عموم مردم
      • تعامل → برای چرخش، ضربه بزنید/کلیک کنید
      • سفارشی‌سازی → پایه
      • پلتفرم → دسکتاپ-اولویت
    • دستورالعمل‌های محصول : تولید خودکار.
    • پشته فنی :
      • زبان‌ها → TypeScript/JavaScript - ایده‌آل برای وب فول‌استک
      • رابط کاربری → Vue.js - رابط‌های وب شهودی
      • بک‌اند → Express.js - بک‌اند سریع Node
      • پایگاه داده → هیچکدام - نیازی به پایگاه داده نیست
    • گردش کار : استاندارد
    • الزامات محصول :
      • داستان‌های کاربر → گزینه‌های قابل تنظیم، نمایش واضح برنده
      • ویژگی‌های کلیدی → فهرست گزینه‌های قابل ویرایش، رنگ‌های تصادفی
      • محدودیت‌ها → فقط سمت کلاینت، عملکرد بالا
      • غیرعملکردی → پوشش تست بالا، TypeScript و Vue.js، طراحی واکنش‌گرا
    Conductor فایل‌های زمینه را در دایرکتوری conductor/ ایجاد می‌کند.

ایجاد یک آهنگ جدید

یک «تراک» در Conductor نشان دهنده یک ویژگی یا یک واحد کاری است.

  1. با استفاده از /conductor-new-rack یک مسیر جدید شروع کنید . ممکن است conductor بر اساس زمینه محصول، یک مسیر اولیه پیشنهاد دهد. همچنین می‌توانید مسیر خودتان را پیشنهاد دهید یا از conductor بخواهید که یک مسیر پیشنهاد دهد.
  2. طرح تولید شده را بررسی کنید . .Conductor یک index.md ، یک spec.md و یک plan.md در داخل conductor/tracks/{track-id}/ ایجاد خواهد کرد. لحظه‌ای وقت بگذارید و آنها را بخوانید. اگر همه چیز خوب به نظر برسد، Conductor از شما می‌خواهد که فایل‌های تنظیمات اولیه را ذخیره و کامیت کنید.

پیاده سازی مسیر

  1. شروع پیاده‌سازی .
    # Antigravity CLI
/conductor:conductor-implement

# Claude Code
/conductor-implement
    اکنون کنداکتور روی طرح کار خواهد کرد و کد پروژه را خواهد نوشت.
  2. تأیید برنامه . در طول مرحله پیاده‌سازی، Conductor از شما می‌خواهد که برنامه را به صورت دستی آزمایش کنید. به عنوان مثال، از شما می‌خواهد که سرور وب محلی را باز کنید، برنامه را در مرورگر خود پیش‌نمایش کنید و تغییرات را تأیید کنید. پس از اتمام پیاده‌سازی، باید یک چرخ انتخابگر کاربردی را مشاهده کنید. کاربرد چرخ جمع کننده
  3. پیاده‌سازی را بررسی کنید . به عنوان آخرین مرحله، می‌توانید از Conductor بخواهید پیاده‌سازی را بررسی کند. این ابزار باید کد منبع را بررسی کند، مستندات پروژه را همگام‌سازی کند و مسیر را بایگانی کند. 
    # Antigravity CLI
/conductor:conductor-review

# Claude Code
/conductor-review

۶. تکرار براونفیلد: شخصی‌سازی را اضافه کنید

حالا به سراغ توسعه‌ی «brownfield» خواهید رفت. برنامه‌ی وب picker wheel را از بخش قبل بهبود خواهید بخشید تا کاربران وارد شده بتوانند پیکربندی‌های picker wheel خود را ذخیره و بازیابی کنند.

یک مسیر شخصی‌سازی ایجاد کنید

  1. در مثال «brownfield» زیر، از Firebase برای احراز هویت و ذخیره‌سازی استفاده خواهیم کرد. مهارت‌های Firebase را نصب کنید تا Conductor بتواند از آن استفاده کند.
  2. عامل CLI خود را شروع کنید . یک جلسه CLI جدید شروع کنید. 
    # Antigravity CLI
/new

# Claude Code
/new
  3. یک مسیر جدید شروع کن . یک مسیر جدید شروع کن. 
    # Antigravity CLI
/conductor:conductor-new-track "I want users to be able to log in to their
accounts and save their picker wheel configurations."

# Claude Code
/conductor-new-track "I want users to be able to log in to their accounts
and save their picker wheel configurations."
  4. دستورالعمل‌های تعاملی را دنبال کنید . دستورالعمل‌های تعاملی که می‌بینید دقیقاً با این مثال‌ها مطابقت ندارند. برای آشنایی با گردش کار Conductor، روی یک طرح ساده‌تر تمرکز کنید.
    • هدف ردیابی :
      • ارائه دهنده مجوز → مجوز فایربیس
      • پیکربندی‌های ذخیره‌شده → گزینه‌های چرخ
      • ذخیره سازی داده ها → فایر استور
      • رابط کاربری ورود به سیستم Firestore → روکش مودال
    Conductor فایل‌های زمینه‌ای را برای یک مسیر جدید در داخل conductor/tracks/{track-id} ایجاد می‌کند.
  5. طرح تولید شده را مرور کنید . لحظه‌ای وقت بگذارید و فایل‌های index.md ، spec.md و plan.md را در داخل conductor/tracks/{track-id}/ بخوانید.
  6. پیاده‌سازی . اگر همه چیز خوب به نظر می‌رسد، می‌توانید پیاده‌سازی را شروع کنید. 
    # Antigravity CLI
/conductor:conductor-implement

# Claude Code
/conductor-implement
  7. برنامه خود را تأیید کنید . دوباره بارگیری کنید. باید یک برنامه به‌روزرسانی‌شده را ببینید.چرخ انتخابگر با ورود به سیستم

این کد طلایی برای پیاده‌سازی مرجع است. برای شروع صحیح برنامه، باید پروژه Firebase خود را در .firebaserc و پیکربندی‌های Firebase خود را در firebase.ts ارائه دهید.

۷. تمیز کردن

برای جلوگیری از هزینه‌های مداوم برای حساب Google Cloud خود، منابع ایجاد شده در طول این codelab را حذف کنید.

پروژه Firebase و پروژه Google Cloud را حذف کنید

ساده‌ترین راه برای پاکسازی، حذف کامل پروژه است.

  1. در کنسول گوگل کلود ، پروژه‌ای که ایجاد کرده‌اید را انتخاب کنید.
  2. روی حذف کلیک کنید.

از طرف دیگر، اگر می‌خواهید پروژه را نگه دارید اما منابع را حذف کنید:

  1. حذف پایگاه داده Firestore : به Firebase Console > Firestore بروید و پایگاه داده را حذف کنید.
  2. حذف احراز هویت : به کنسول فایربیس > روش ورود به سیستم احراز هویت بروید، گوگل را غیرفعال کنید.

۸. تبریک

تبریک! شما با موفقیت از افزونه Conductor در عامل‌های کدنویسی انتخابی خود (Antigravity CLI یا Claude Code) برای ساخت یک برنامه وب از ابتدا و سپس تکرار آن با ویژگی‌های پیچیده‌ای مانند احراز هویت و ادغام پایگاه داده استفاده کرده‌اید.

مراحل بعدی