অ্যান্টিগ্র্যাভিটি এবং স্পেক-কিট সহ স্পেক-চালিত ADK এজেন্ট ডেভেলপমেন্ট

1. ভূমিকা

একটি বিদ্যমান এজেন্টে বৈশিষ্ট্য যোগ করা - একটি নতুন ডাটাবেস-সমর্থিত ক্ষমতা - সাধারণত বয়লারপ্লেট লেখা, ইন্টিগ্রেশন ওয়্যারিং আপ করা এবং কোডবেসে ইতিমধ্যেই থাকা প্যাটার্নের সাথে সবকিছু সামঞ্জস্যপূর্ণ রাখা বোঝায়। অ্যান্টিগ্র্যাভিটি এই প্রক্রিয়ার প্রতিটি পর্যায়ে ত্বরান্বিত করে: এটি আপনার কোডবেসকে প্রয়োজনীয় প্রেক্ষাপট তৈরি করতে বিশ্লেষণ করে, আপনার পর্যালোচনার জন্য কাঠামোগত স্পেসিফিকেশন এবং বাস্তবায়ন পরিকল্পনা তৈরি করে এবং কোড পরিবর্তনগুলি কার্যকর করে - সবকিছুই ডোমেন জ্ঞান দ্বারা পরিচালিত হয়। এটি আপনাকে পুনর্ব্যবহারযোগ্য দক্ষতা এবং একটি প্রকল্প গঠন হিসাবে ক্যাপচার করতে সহায়তা করে যা অ-আলোচনাযোগ্য নীতিগুলিকে প্রয়োগ করে। এই কোডল্যাবটি স্পেসিফিকেশন ডকুমেন্টেশনকে জোরদার করার জন্য একটি নতুন চক্র প্রবর্তন করে অ্যান্টিগ্র্যাভিটি স্পেক-চালিত ডেভেলপমেন্ট প্যারাডাইমকে সুপারচার্জ করার একটি উপায় প্রবর্তন করে যা স্পেক-কিটকে ব্যাপকভাবে উল্লেখ করে।

তুমি কী তৈরি করবে

একটি স্থানীয়ভাবে চলমান রেস্তোরাঁ কনসির্জ অ্যাপ্লিকেশন যার রিজার্ভেশন বুকিং সম্পূর্ণ SDD চক্রের মাধ্যমে যোগ করা হয়েছে:

• রিজার্ভেশন বুকিং — অতিথিরা টেবিল বুক করেন এবং রিজার্ভেশন চেক করেন, নতুন MCP টুলবক্স ডাটাবেস টুল এবং একটি ক্লাউড SQL reservations টেবিল দ্বারা সমর্থিত।
• (চ্যালেঞ্জ) – এজেন্টের জন্য আপনার নিজস্ব UI তৈরি করুন
• (চ্যালেঞ্জ) – অ্যান্টিগ্র্যাভিটি এজেন্টের সাহায্যে গুগল ক্লাউডে স্থাপন করুন

স্টার্টার কোডটি একটি কার্যকরী ADK এজেন্ট প্রদান করে যার মধ্যে রয়েছে মেনু অনুসন্ধান (MCP টুলবক্সের মাধ্যমে কীওয়ার্ড + সিমেন্টিক) এবং খাদ্যতালিকাগত পছন্দ ট্র্যাকিং (ToolContext এর মাধ্যমে)। আপনি হাতে অ্যাপ্লিকেশন কোড না লিখেই এটি প্রসারিত করতে পারেন — অ্যান্টিগ্রাভিটি আপনার স্পেসিফিকেশনের উপর ভিত্তি করে বাস্তবায়ন পরিচালনা করে।

তুমি কি শিখবে

• অ্যান্টিগ্র্যাভিটি যাতে বিদ্যমান কোডবেস বুঝতে পারে, সেজন্য কীভাবে প্রকল্পের প্রেক্ষাপট বুটস্ট্র্যাপ করবেন
• পুনঃব্যবহারের জন্য ডোমেন জ্ঞান (যেমন, ADK কোডল্যাব প্যাটার্ন) প্যাকেজ করে অ্যান্টিগ্র্যাভিটি দক্ষতা কীভাবে তৈরি করবেন
• পরিকল্পনা এবং বিশ্লেষণের সময় SDD কর্মপ্রবাহের বিরুদ্ধে যাচাই করা প্রকল্পের গঠনতন্ত্র কীভাবে সেট করবেন
• অ্যান্টিগ্র্যাভিটিতে স্পেক-ড্রিভেন ডেভেলপমেন্ট (SDD) ওয়ার্কফ্লো ব্যবহার করে পদ্ধতিগতভাবে বৈশিষ্ট্য যোগ করবেন কীভাবে
• MCP টুলবক্সের মাধ্যমে নতুন ডাটাবেস-সমর্থিত টুল সহ একটি ADK এজেন্টকে কীভাবে প্রসারিত করবেন

পূর্বশর্ত

• আপনার স্থানীয় মেশিনে গুগল অ্যান্টিগ্রাভিটি এবং git ইনস্টল করা হয়েছে
• একটি Google ক্লাউড অ্যাকাউন্ট যার ট্রায়াল বিলিং অ্যাকাউন্ট সক্ষম করা আছে
• চারটি পূর্বশর্ত ADK কোডল্যাব (অথবা সমতুল্য জ্ঞান) এর পূর্ববর্তী সমাপ্তি ব্যবহারের ক্ষেত্রে প্রেক্ষাপট বুঝতে সহায়ক হবে:
• ADK: The Foundation-এর মাধ্যমে AI এজেন্ট তৈরি করা
• ADK-এর মাধ্যমে AI এজেন্ট তৈরি: সরঞ্জামের মাধ্যমে ক্ষমতায়ন
• ADK এবং CloudSQL ব্যবহার করে স্থায়ী AI এজেন্ট তৈরি করা
• ক্লাউড রানে ADK এজেন্ট স্থাপন, পরিচালনা এবং পর্যবেক্ষণ করুন
• একটি টুল হিসেবে ডাটাবেস: ADK, MCP টুলবক্স এবং ক্লাউড SQL সহ এজেন্টিক RAG

2. আপনার পরিবেশ সেট আপ করুন

গুরুত্বপূর্ণ নোট:

এই টিউটোরিয়ালের জন্য একটি সক্রিয় বিলিং অ্যাকাউন্ট সহ একটি Google Cloud Project প্রয়োজন। যদি আপনার এখনও একটি না থাকে, তাহলে এই টিউটোরিয়ালের জন্য ব্যবহার করা যেতে পারে এমন একটি ট্রায়াল বিলিং অ্যাকাউন্ট পেতে নীচের ধাপগুলি অনুসরণ করুন:

1. ছদ্মবেশী উইন্ডো খুলুন
2. যদি আপনি কোনও কর্মশালা অধিবেশনে যোগদান করেন, তাহলে সাধারণত সেশনে রিডেম্পশন পোর্টালের URL প্রদান করা হবে, অন্যথায় আপনি এই ট্রায়াল বিলিং অ্যাকাউন্ট রিডেম্পশন পোর্টালে যেতে পারেন।
3. আপনার ব্যক্তিগত জিমেইল অ্যাকাউন্ট ব্যবহার করে লগ ইন করুন (গুগল ওয়ার্কস্পেস / অন্যান্য ইমেল কাজ করবে না!)
4. ধাপে ধাপে রিডেম্পশন নির্দেশাবলী অনুসরণ করুন

এই ধাপটি স্টার্টার রিপোজিটরি ক্লোন করে, গুগল ক্লাউডের সাথে প্রমাণীকরণ করে, একটি ক্লাউড SQL ডাটাবেস সরবরাহ করে এবং আপনার স্থানীয় অ্যান্টিগ্র্যাভিটি পরিবেশ প্রস্তুত করে।

দ্রষ্টব্য: এই কোডল্যাবটি আপনার স্থানীয় মেশিনে সম্পূর্ণরূপে Google Antigravity তে চলে। সেটআপে gcloud CLI কমান্ড ব্যবহার করে ম্যানুয়াল প্রমাণীকরণ অন্তর্ভুক্ত থাকে।

স্টার্টার রিপোজিটরি ক্লোন করুন

অ্যান্টিগ্রাভিটিতে (অথবা আপনার সিস্টেম টার্মিনাল) একটি টার্মিনাল খুলুন। কম্প্যানিয়ন রেপো ক্লোন করুন এবং ডিরেক্টরিটি প্রবেশ করান:

git clone https://github.com/alphinside/sdd-adk-antigravity-starter.git sdd-adk-agents-agy
cd sdd-adk-agents-agy

অ্যান্টিগ্র্যাভিটিতে ক্লোন করা রিপোজিটরিটি খুলুন। ফাইল -> ফোল্ডার খুলুন -> ক্লোন করা ডিরেক্টরিটি নির্বাচন করুন sdd-adk-agents-agy

আপস্ট্রিম রিমোটটি সরান। SDD ওয়ার্কফ্লোগুলি বৈশিষ্ট্যের নির্দিষ্টকরণের জন্য গিট শাখা তৈরি করে — রিমোটটি সরানোর ফলে দুর্ঘটনাক্রমে স্টার্টার রিপোজিটরিতে ঠেলে দেওয়া রোধ করা হয়:

git remote remove origin

গুরুত্বপূর্ণ: এই কোডল্যাবের SDD ওয়ার্কফ্লোগুলি বৈশিষ্ট্যের স্পেসিফিকেশনগুলি সংগঠিত করার জন্য git শাখা ব্যবহার করে। origin রিমোট অপসারণ করলে আপনার স্থানীয় শাখা এবং কমিটগুলি স্থানীয় থাকবে তা নিশ্চিত হয়। আপনি যদি আপনার কাজের ব্যাক আপ নিতে চান, তাহলে আপনার নিজস্ব রিমোট যোগ করুন: git remote add origin <your-repo-url>

পূর্বশর্ত ইনস্টল করুন

পূর্বশর্ত স্ক্রিপ্টটি চালান। এটি git , curl , gcloud , uv , Python 3.12, এবং MCP টুলবক্স পরীক্ষা করে (এবং অনুপস্থিত থাকলে ইনস্টল করে):

bash scripts/setup_prerequisites.sh

দ্রষ্টব্য: সমস্ত পূর্বশর্ত ডাউনলোড করতে কিছুটা সময় লাগবে, পরবর্তী বিভাগে যেতে নতুন ট্যাব খুলুন এবং ডাউনলোড শেষ হওয়ার অপেক্ষা করুন।

গুগল ক্লাউডের মাধ্যমে প্রমাণীকরণ করুন

দুটি প্রমাণীকরণ কমান্ড চালান। উভয়ই OAuth এর জন্য একটি ব্রাউজার খুলুন:

gcloud auth login
gcloud auth application-default login

দ্রষ্টব্য: দ্বিতীয় OAuth কমান্ডে, যখন অনুমতি নির্বাচন করতে বলা হবে। সমস্ত বিকল্প পরীক্ষা করুন।

দ্রষ্টব্য: ট্রায়াল বিলিং অ্যাকাউন্ট দাবি করার জন্য আপনি যে ইমেলটি ব্যবহার করেন তা দিয়ে প্রমাণীকরণ নিশ্চিত করুন।

যেহেতু আপনি স্থানীয়ভাবে অ্যান্টিগ্রাভিটি নিয়ে কাজ করছেন, তাই আপনাকে ম্যানুয়ালি প্রমাণীকরণ করতে হবে। auth login gcloud CLI প্রমাণীকরণ করে। application-default login আপনার অ্যাপ্লিকেশন ব্যবহার করে এমন Google Cloud SDK-গুলিকে প্রমাণীকরণ করে — ADK-এর Vertex AI কল এবং Cloud SQL Python সংযোগকারী উভয়ই অ্যাপ্লিকেশন ডিফল্ট শংসাপত্রের উপর নির্ভর করে।

আপনার গুগল ক্লাউড প্রোজেক্ট সেট আপ করুন

প্রজেক্ট সেটআপ স্ক্রিপ্ট চালানোর আগে লোকেশন ভেরিয়েবলগুলিকে .env তে লিখুন:

echo "GOOGLE_CLOUD_LOCATION=global" > .env
echo "REGION=us-central1" >> .env

• GOOGLE_CLOUD_LOCATION=global Vertex AI / Gemini API কলের জন্য ব্যবহৃত হয়।
• REGION=us-central1 ক্লাউড SQL এবং অন্যান্য GCP পরিকাঠামোর জন্য ব্যবহৃত হয়

প্রোজেক্ট সেটআপ স্ক্রিপ্টটি ডাউনলোড করে চালান। এটি ট্রায়াল বিলিং সহ একটি গুগল ক্লাউড প্রোজেক্ট তৈরি করে বা যাচাই করে এবং প্রোজেক্ট আইডিটি .env এ সংরক্ষণ করে এবং তারপর এটি সোর্স করে:

curl -sL https://raw.githubusercontent.com/alphinside/cloud-trial-project-setup/main/setup_verify_trial_project.sh -o setup_verify_trial_project.sh

bash setup_verify_trial_project.sh && source .env

প্রয়োজনীয় API গুলি সক্ষম করুন:

gcloud services enable \
  aiplatform.googleapis.com \
  sqladmin.googleapis.com \
  compute.googleapis.com \
  cloudresourcemanager.googleapis.com

দ্রষ্টব্য: API গুলি সক্রিয় করতে কিছুটা সময় লাগতে পারে। আপনাকে প্রতি প্রকল্পে কেবল একবার এটি করতে হবে।

প্রোভিশন ক্লাউড এসকিউএল

ডাটাবেস পাসওয়ার্ড সেট করুন এবং এটি .env এ যোগ করুন:

export DB_PASSWORD=codelabpassword
echo "DB_PASSWORD=${DB_PASSWORD}" >> .env

গুরুত্বপূর্ণ: উপরের হার্ডকোডেড পাসওয়ার্ডটি শুধুমাত্র টিউটোরিয়ালের উদ্দেশ্যে। একটি উৎপাদন পরিবেশে, সিক্রেট ম্যানেজারের মতো পরিষেবা ব্যবহার করে শংসাপত্রগুলি নিরাপদে সংরক্ষণ করুন এবং রানটাইমের সময় সেগুলি উল্লেখ করুন — কখনও প্লেইনটেক্সট গোপনীয়তাগুলি সোর্স নিয়ন্ত্রণে রাখবেন না।

ক্লাউড SQL ইনস্ট্যান্স তৈরি করুন:

gcloud sql instances create restaurant-db \
  --database-version=POSTGRES_17 \
  --edition=ENTERPRISE \
  --region=${REGION} \
  --availability-type=ZONAL \
  --tier=db-custom-1-3840 \
  --root-password=${DB_PASSWORD} \
  --enable-google-ml-integration \
  --database-flags cloudsql.enable_google_ml_integration=on &

ভার্টেক্স এআই এমএল ইন্টিগ্রেশনের জন্য db-custom-1-3840 টিয়ার হল সর্বনিম্ন প্রয়োজনীয় স্তর। --enable-google-ml-integration ফ্ল্যাগ ক্লাউড এসকিউএলকে সরাসরি এসকিউএল থেকে জেমিনি এম্বেডিং মডেলগুলিকে কল করতে দেয় — এটি সিমেন্টিক সার্চ বৈশিষ্ট্যটিকে শক্তিশালী করে।

দ্রষ্টব্য: এই কমান্ডটি প্রায় ৫ মিনিট সময় নেয় এবং ব্যাকগ্রাউন্ডে চলবে। এই টার্মিনাল ট্যাবে এটি চালু রেখে পরবর্তী পদক্ষেপের জন্য একটি নতুন টার্মিনাল ট্যাব খুলুন ।

নির্ভরতা ইনস্টল করুন

একটি নতুন টার্মিনাল ট্যাব খুলুন। নিশ্চিত করুন যে আপনি এখনও ক্লোনড রেপো প্রজেক্ট ডিরেক্টরিতে আছেন এবং পরিবেশ ভেরিয়েবলগুলি পুনরায় লোড করুন:

source .env

আমরা পাইথন প্রজেক্ট ম্যানেজার হিসেবে uv ব্যবহার করব। uv হল একটি দ্রুত পাইথন প্যাকেজ এবং প্রজেক্ট ম্যানেজার যা Rust ( docs ) ভাষায় লেখা। এই কোডল্যাবটি গতি এবং সরলতার জন্য এটি ব্যবহার করে। পাইথন নির্ভরতা ইনস্টল করুন:

uv sync

তারপর আপনার প্রোজেক্ট কনফিগারেশনের সাথে ADK এজেন্টের .env ফাইলটি আপডেট করুন:

cat > restaurant_concierge/.env <<EOF
GOOGLE_CLOUD_PROJECT=${GOOGLE_CLOUD_PROJECT}
GOOGLE_CLOUD_LOCATION=global
GOOGLE_GENAI_USE_VERTEXAI=True
EOF

এখন, আমাদের প্রয়োজনীয় সমস্ত স্টার্টার ADK এজেন্ট রেপো তৈরি করা উচিত। এখন পরবর্তী বিভাগে অ্যান্টিগ্র্যাভিটি এবং স্পেক-চালিত ডেভেলপমেন্ট সম্পর্কে আরও আলোচনা করা যাক এবং সবকিছু প্রস্তুত হওয়ার জন্য অপেক্ষা করা যাক।

৩. স্টার্টার কোডটি অন্বেষণ করুন এবং স্পেক-চালিত ডেভেলপমেন্ট বুঝুন

এই ধাপটি স্টার্টার কোড কাঠামোর মধ্য দিয়ে যায়, স্পেক-ড্রিভেন ডেভেলপমেন্ট পদ্ধতি প্রবর্তন করে, ডাটাবেস তৈরি করে এবং বেস এজেন্টের কাজ যাচাই করে, আগে আপনি এটি প্রসারিত করতে শুরু করেন।

প্রকল্প কাঠামো

অ্যান্টিগ্রাভিটি এডিটরে ক্লোন করা রেপো প্রজেক্টটি খুলুন এবং ডিরেক্টরি লেআউটটি পর্যালোচনা করুন:

sdd-adk-agents-agy/
├── .agents/
│   ├── workflows/                 # SDD slash commands (/speckit.*) – manual trigger
│   │   ├── speckit.specify.md
│   │   ├── speckit.clarify.md
│   │   ├── speckit.plan.md
│   │   ├── speckit.tasks.md
│   │   ├── speckit.analyze.md
│   │   ├── speckit.implement.md
│   │   ├── speckit.checklist.md
│   │   └── speckit.constitution.md
│   ├── skills/                   # Antigravity skills (loaded on demand, agent determined)
│   │   ├── adk-agent-development/
│   │   │   ├── SKILL.md     # ADK patterns
│   │   │   └── examples/
│   │   │       ├── basic_agent.py
│   │   │       ├── Dockerfile
│   │   │       ├── server.py
│   │   │       ├── stateful_agent.py
│   │   │       ├── toolbox_agent.py
│   │   │       ├── tools_agent.py
│   │   │       └── tools.yaml
│   │   └── repo-research/
│   │       └── SKILL.md     # Repo analysis 
│   └── rules/               # Always-active context
├── .specify/                # spec-kit SDD templates and memory
│   ├── memory/constitution.md
│   ├── templates/
│   └── scripts/
├── restaurant_concierge/    # ADK agent package
│   ├── __init__.py
│   ├── agent.py             # LlmAgent + ToolContext tools + Toolbox integration
│   └── .env                 # Vertex AI configuration
├── server.py                # FastAPI server wrapping the agent
├── tools.yaml               # MCP Toolbox tool definitions
├── scripts/                 # Setup scripts
└── pyproject.toml

কী ফাইল

এজেন্ট আবেদন ফাইল

• restaurant_concierge/agent.py — মূল এজেন্ট। একটি LlmAgent যা MCP Toolbox ডাটাবেস টুলগুলিকে ToolContext ভিত্তিক খাদ্যতালিকাগত পছন্দ ট্র্যাকিংয়ের সাথে একত্রিত করে। এজেন্টটি Toolbox সার্ভার থেকে সমস্ত টুল লোড করে এবং দুটি Python ফাংশন ( save_dietary_preference , get_dietary_preferences ) যোগ করে যা ToolContext ব্যবহার করে অবস্থা পরিচালনা করে।
• tools.yaml — MCP টুলবক্স টুলের সংজ্ঞা। তিনটি মেনু সার্চ টুল সংজ্ঞায়িত করা হয়েছে: কীওয়ার্ড সার্চ ( search_menu ), pgvector এর মাধ্যমে সিমান্টিক সার্চ ( semantic_search_menu ), এবং ক্যাটাগরি ফিল্টার ( get_menu_by_category )। এখনও কোনও রিজার্ভেশন টুল নেই — আপনি পরে এগুলি যোগ করবেন।
• server.py — একটি ন্যূনতম FastAPI সার্ভার, যা দেখায় কিভাবে আপনি FastAPI অবজেক্ট হিসেবে ADK অ্যাক্সেস করতে পারেন। ADK থেকে get_fast_api_app() বিল্ট-ইন এন্ডপয়েন্ট প্রদান করে যার মধ্যে SSE স্ট্রিমিং এবং সেশন ম্যানেজমেন্ট API গুলির জন্য /run_sse অন্তর্ভুক্ত রয়েছে।

অ্যান্টিগ্র্যাভিটি ফাইল

• .agents/skills/adk-agent-development/SKILL.md — একটি পূর্ব-কনফিগার করা দক্ষতা (Antigravity-generated) যাতে চারটি ADK কোডল্যাব থেকে ঘনীভূত রেফারেন্স প্যাটার্ন রয়েছে। এটি বর্তমানে নিষ্ক্রিয় (YAML ফ্রন্টম্যাটার অনুপস্থিত) - আপনাকে এটি পরে আপডেট করতে হবে। অ্যান্টিগ্রাভিটি যখন ADK এজেন্ট বৈশিষ্ট্য এবং তাদের উদাহরণগুলির সাথে সম্পর্কিত কাজ সনাক্ত করে তখন এই দক্ষতাটি স্বয়ংক্রিয়ভাবে লোড করে - এটি সেই জ্ঞান যা পরবর্তীতে রিজার্ভেশন বৈশিষ্ট্য পরিকল্পনা করার সময় অ্যান্টিগ্রাভিটিকে নির্দেশ করে।
• .agents/skills/repo-research/SKILL.md — একটি দক্ষতা যা অ্যান্টিগ্রাভিটিকে শেখায় কিভাবে একটি রিপোজিটরিকে ক্রমবর্ধমানভাবে বিশ্লেষণ করতে হয় এবং একটি কাঠামোগত প্রকল্প প্রসঙ্গ নথি তৈরি করতে হয়। এটি একটি 4-পর্যায়ের পদ্ধতি ব্যবহার করে: সারফেস স্ক্যান (শুধুমাত্র ডিরেক্টরি ট্রি), কনফিগ এবং মেটাডেটা ফাইল, এন্ট্রি পয়েন্ট এবং ডেটা মডেল, তারপর লক্ষ্যবস্তু গভীর ডাইভ - প্রতিটি ফেজ থামে এবং পরবর্তী ধাপে যাওয়ার আগে ফলাফল লিখে। ADK দক্ষতার মতো, এটি নিষ্ক্রিয় থাকে যতক্ষণ না আপনি পরে YAML ফ্রন্টম্যাটার যোগ করেন। একবার সক্রিয় হয়ে গেলে, .agents/rules/project-context.md তৈরি করতে এটি ব্যবহার করুন — একটি বিস্তৃত অনবোর্ডিং ডকুমেন্ট যা আর্কিটেকচার, রানটাইম নির্ভরতা, API সারফেস এবং ডোমেন শব্দকোষকে অন্তর্ভুক্ত করে।

স্পেক-চালিত উন্নয়ন: অ্যান্টিগ্র্যাভিটির অন্তর্নির্মিত পরিকল্পনা থেকে শুরু করে কাঠামোগত SDD পর্যন্ত

এআই কোডিং অ্যাসিস্ট্যান্ট প্রম্পট থেকে কোড তৈরি করা সহজ করে তোলে। ঝুঁকি: আপনি একটি বাক্যে একটি বৈশিষ্ট্য বর্ণনা করেন, সহকারী শত শত লাইন লেখেন, এবং আপনি এটি গ্রহণ করেন কারণ এটি সঠিক দেখায়। এটিকে কখনও কখনও "ভাইব কোডিং" বলা হয় - আপনি অনুভূতির উপর নির্ভর করে পরিচালনা করেন, এটি কাজ করছে কিনা তার উপর ভিত্তি করে আউটপুট গ্রহণ বা প্রত্যাখ্যান করেন। প্রোটোটাইপ এবং ফেলে দেওয়া স্ক্রিপ্টগুলির জন্য এটি দ্রুত। কোডবেস বৃদ্ধি পেলে, বৈশিষ্ট্যগুলি যখন ইন্টারঅ্যাক্ট করে, অথবা যখন আপনি কয়েক সপ্তাহ পরে কোডটি পুনরায় দেখেন এবং কেন সিদ্ধান্ত নেওয়া হয়েছিল তা পুনর্গঠন করতে পারেন না তখন এটি ভেঙে যায়।

স্পেক-ড্রিভেন ডেভেলপমেন্ট (SDD) এই লুপে কাঠামো যোগ করে। যেকোনো কোড তৈরি করার আগে, আপনাকে একটি স্পেসিফিকেশন লিখতে হবে: বৈশিষ্ট্যটি কী করে, এটি কাকে পরিবেশন করে, সাফল্যের মানদণ্ড কী। AI সহকারী সেই স্পেক থেকে কাজ করে — এবং এর আউটপুট পর্যালোচনা করার সময় আপনিও তাই করেন। স্পেকটি উদ্দেশ্যের জন্য সত্যের একক উৎস হয়ে ওঠে। যদি কোডটি স্পেক থেকে আলাদা হয়, তাহলে আপনি এটি পর্যালোচনায় দেখতে পাবেন। যদি প্রয়োজনীয়তা পরিবর্তন হয়, তাহলে আপনি প্রথমে স্পেকটি আপডেট করেন, তারপর পুনরায় তৈরি করেন। সিদ্ধান্তগুলি নথিভুক্ত করা হয়, উন্নত নয়।

বিনিময়টি বাস্তব: ভাইব কোডিংয়ের তুলনায় SDD প্রতিটি বৈশিষ্ট্যের জন্য ধীর। আপনি কোড লেখার আগে নথি লেখেন। কিন্তু লাভের যোগসূত্র — কোডবেসে ভবিষ্যতের প্রতিটি পরিবর্তনের একটি প্রসঙ্গ থাকে, প্রতিটি AI-উত্পাদিত বাস্তবায়নের একটি পর্যালোচনাযোগ্য চুক্তি থাকে এবং আপনি মেমরি থেকে সিদ্ধান্ত ব্যাখ্যা করার পরিবর্তে স্পেসিফিকেশনগুলি নির্দেশ করে সহযোগীদের (মানব বা AI) অনবোর্ড করতে পারেন।

অ্যান্টিগ্র্যাভিটি ইতিমধ্যেই স্পেক-চালিত ডেভেলপমেন্ট নীতি অনুসরণ করে। যখন আপনি এজেন্টটিকে প্ল্যানিং মোডে সেট করেন, তখন এটি কোনও কোড লেখার আগে দুটি আর্টিফ্যাক্ট তৈরি করে:

• বাস্তবায়ন পরিকল্পনা — প্রস্তাবিত প্রযুক্তিগত পদ্ধতি, ফাইল পরিবর্তন এবং স্থাপত্য সিদ্ধান্তের একটি সারসংক্ষেপ
• কার্য তালিকা — কাজের আইটেমগুলির একটি কাঠামোগত ভাঙ্গন

অ্যান্টিগ্র্যাভিটি আপনাকে এই শিল্পকর্মগুলি বাস্তবায়নের আগে পর্যালোচনা এবং অনুমোদন করতে বলে। এই পরিকল্পনা-তারপর-বাস্তবায়ন লুপটি স্পেক-চালিত উন্নয়নের মূল বিষয়: স্পেসিফিকেশন কোডকে নির্দেশ করে, বিপরীতভাবে নয়।

এই কোডল্যাবটি স্পেক-কিটের উপর ভিত্তি করে একটি মতামতযুক্ত , সংস্করণ-নিয়ন্ত্রিত কর্মপ্রবাহের মাধ্যমে সেই ভিত্তিটিকে আরও এগিয়ে নিয়ে যায় - GitHub থেকে একটি স্পেসিফিকেশন-চালিত ডেভেলপমেন্ট ফ্রেমওয়ার্ক। প্রতিটি বৈশিষ্ট্য একটি ইচ্ছাকৃত পাইপলাইনের মধ্য দিয়ে যায় যেখানে প্রতিটি শিল্পকর্ম একটি স্বতন্ত্র নথি যা আপনি git এ পর্যালোচনা, সম্পাদনা এবং ট্র্যাক করতে পারেন। পাইপলাইনে দুটি ঐচ্ছিক গুণমান-গেট পর্যায় (স্পষ্টীকরণ এবং বিশ্লেষণ) অন্তর্ভুক্ত রয়েছে যা বাস্তবায়ন সমস্যা হওয়ার আগে সমস্যাগুলি ধরে ফেলে:

পর্যায়	শিল্পকর্ম	উদ্দেশ্য
/speckit.specify	spec.md	কী তৈরি করবেন তা নির্ধারণ করুন (ব্যবহারকারী-মুখী, প্রযুক্তি-অজ্ঞেয়বাদী)
/speckit.clarify (ঐচ্ছিক)	আপডেট করা হয়েছে spec.md	অনির্দিষ্ট ক্ষেত্রগুলি চিহ্নিত করুন, লক্ষ্যযুক্ত স্পষ্টীকরণ প্রশ্ন জিজ্ঞাসা করুন, উত্তরগুলিকে স্পেসিফিকেশনে আবার এনকোড করুন
/speckit.plan	plan.md , data-model.md , research.md	ডিজাইন করুন কিভাবে এটি তৈরি করবেন (প্রযুক্তিগত পদ্ধতি, ডেটা মডেল, গবেষণা)
/speckit.tasks	tasks.md	পরিকল্পনাটিকে সুশৃঙ্খল, কার্যকর পদক্ষেপে ভাগ করুন
/speckit.analyze (ঐচ্ছিক)	বিশ্লেষণ প্রতিবেদন	বাস্তবায়নের আগে ঝুঁকি, ফাঁক, বা অনুপস্থিত প্রান্তের ক্ষেত্রে কাজগুলি পর্যালোচনা করুন।
/speckit.implement	কোড পরিবর্তন	প্রতিটি কাজ টিক চিহ্ন দিয়ে সম্পাদন করুন।

প্রতিটি আর্টিফ্যাক্ট specs/<feature-branch>/ তে একটি ফাইল হিসেবে, git তে সংস্করণ-নিয়ন্ত্রিত এবং পুনঃব্যবহারযোগ্য অবস্থায় থাকে। যদি কোনও কথোপকথন বাধাগ্রস্ত হয় বা আপনি পরে সিদ্ধান্তগুলি পুনর্বিবেচনা করতে চান, তাহলে স্পেসিফিকেশন ডকুমেন্টগুলি সর্বদা সেখানে থাকে — চ্যাট ইতিহাসে চাপা পড়ে না।

দ্রষ্টব্য: UI-তে অ্যান্টিগ্র্যাভিটি বিল্ট-ইন আর্টিফ্যাক্টের শ্রেষ্ঠত্ব রয়েছে যা ব্যবহারকারীকে জেনারেট করা আর্টিফ্যাক্টের উপর মন্তব্য করতে সক্ষম করে (এমনকি ছবি!)। তাই এই টিউটোরিয়ালে আমরা implement পর্যায়ে বিল্ট-ইন আর্টিফ্যাক্টের সাথে একীভূত করার জন্য মূল spec-kit প্রম্পটটি পরিবর্তন করব।

স্টার্টার রেপোতে .agents/workflows/ এ এই SDD ওয়ার্কফ্লো এবং .specify/templates/ এ টেমপ্লেটগুলি অন্তর্ভুক্ত রয়েছে। এজেন্টে বৈশিষ্ট্যগুলি যোগ করার জন্য আপনি পরে এগুলি ব্যবহার করবেন।

৪. ক্লাউড এসকিউএল সেটআপ সম্পূর্ণ করুন এবং বেস এজেন্ট কার্যকরী নিশ্চিত করুন

টার্মিনাল ট্যাবে ফিরে যান যেখানে ক্লাউড SQL তৈরি কমান্ড চলছে। এটি সম্পন্ন হওয়ার পরে, ইনস্ট্যান্সটি প্রস্তুত কিনা তা যাচাই করুন:

gcloud sql instances describe restaurant-db --format="value(state)"

যদি আউটপুট RUNNABLE দেখায়, তাহলে এগিয়ে যান। যদি এটি PENDING_CREATE দেখায়, তাহলে কিছুক্ষণ অপেক্ষা করুন এবং কমান্ডটি পুনরায় চালান।

ক্লাউড SQL পরিষেবা অ্যাকাউন্টকে Vertex AI-তে অ্যাক্সেস দিন (ইন-ডাটাবেস এম্বেডিং ফাংশনের জন্য প্রয়োজনীয়):

SERVICE_ACCOUNT=$(gcloud sql instances describe restaurant-db --format="value(serviceAccountEmailAddress)")

gcloud projects add-iam-policy-binding $GOOGLE_CLOUD_PROJECT \
  --member="serviceAccount:$SERVICE_ACCOUNT" \
  --role="roles/aiplatform.user" \
  --quiet

ডাটাবেস তৈরি করুন:

gcloud sql databases create restaurant_db --instance=restaurant-db

তুমি আউটপুটটি এভাবে দেখতে পাবে

Creating Cloud SQL database...done.
Created database [restaurant_db].
instance: restaurant-db
name: restaurant_db
project: <your-project-id>

চেকপয়েন্ট: আপনার .env ফাইলে GOOGLE_CLOUD_PROJECT , GOOGLE_CLOUD_LOCATION , REGION এবং DB_PASSWORD রয়েছে। ক্লাউড SQL ইনস্ট্যান্স restaurant-db চলছে। আপনার PATH-তে toolbox উপলব্ধ ( setup_prerequisites.sh দ্বারা ইনস্টল করা)। পাইথন নির্ভরতা ইনস্টল করা আছে।

ডাটাবেস তৈরি করুন

আপনার পরিবেশ ভেরিয়েবল লোড করুন এবং স্কিমা তৈরি করতে ডাটাবেস সিড স্ক্রিপ্টটি চালান এবং ১৬টি মেনু আইটেম সন্নিবেশ করুন:

source .env
uv run python scripts/seed_db.py

প্রত্যাশিত আউটপুট:

Creating extensions...
Creating menu_items table...
Inserting 16 menu items...
Seeded 16 menu items.
Done.

শব্দার্থিক অনুসন্ধানের জন্য ভেক্টর এম্বেডিং তৈরি করুন:

uv run python scripts/generate_embeddings.py

প্রত্যাশিত আউটপুট:

Generating embeddings for 16 menu items...
Generated embeddings for 16 menu items.

এটি ক্লাউড SQL এর বিল্ট-ইন embedding() ফাংশন ( google_ml_integration এক্সটেনশনের মাধ্যমে) ব্যবহার করে SQL থেকে সরাসরি gemini-embedding-001 কল করে। 3072-মাত্রিক ভেক্টরগুলি menu_items এর embedding কলামে সংরক্ষণ করা হয় — কোনও অ্যাপ্লিকেশন-সাইড এম্বেডিং কোডের প্রয়োজন হয় না।

বেস এজেন্ট পরীক্ষা করুন

ব্যাকগ্রাউন্ড প্রক্রিয়া হিসেবে MCP টুলবক্স শুরু করুন:

set -a; source .env; set +a # Export env variables to child process
toolbox --tools-file tools.yaml --address 127.0.0.1 --port 5000 &

টুলবক্সটি HTTP এর মাধ্যমে ডাটাবেস টুল পরিবেশন করে। এজেন্টটি http://127.0.0.1:5000 এ এর ​​সাথে সংযোগ স্থাপন করে।

ADK ডেভেলপার UI শুরু করুন:

uv run adk web .

আপনার ব্রাউজারে Dev UI খুলুন। তারপর, এই প্রম্পটগুলি ব্যবহার করে এজেন্টটি পরীক্ষা করুন:

What appetizers do you have?

পরিদর্শন: এজেন্ট ডাটাবেস অনুসন্ধান করে এবং মেনু আইটেমগুলি ফেরত দেয়

I'm vegetarian

পরিদর্শন করুন: এজেন্ট খাদ্যতালিকাগত পছন্দকে এজেন্ট অবস্থার উপর সংরক্ষণ করে

Can I make a reservation for tomorrow?

পরিদর্শন করুন: এজেন্ট এটি পরিচালনা করতে পারছে না (কোনও রিজার্ভেশন টুল এখনও বিদ্যমান নেই)

Ctrl+C দুবার চেপে ADK ডেভেলপার UI বন্ধ করুন। টুলবক্সটি ব্যাকগ্রাউন্ডে চলতে দিন — আপনি পরে আবার এটি ব্যবহার করতে পারবেন।

চেকপয়েন্ট: বেস এজেন্ট কাজ করে — মেনু অনুসন্ধান (কীওয়ার্ড + শব্দার্থিক) এবং খাদ্যতালিকাগত পছন্দগুলি সঠিকভাবে কাজ করে। কোনও রিজার্ভেশন সরঞ্জাম না থাকায় রিজার্ভেশন অনুরোধগুলি ব্যর্থ হয়। আপনি প্রকল্পের কাঠামো এবং আপনি যে শূন্যস্থান পূরণ করতে চলেছেন তা বুঝতে পারেন।

৫. অ্যান্টিগ্র্যাভিটি সহ বুটস্ট্র্যাপ প্রকল্পের প্রসঙ্গ

এবার, আসুন এমন একটি শর্ত দিয়ে জিনিসগুলিকে অনুকরণ করি যা আমাদের দৈনন্দিন কাজের "একটু কাছাকাছি":

• ভালোভাবে পরিচালিত নয় এমন সংগ্রহস্থল
• README অপ্রচলিত
• যেসব ডকুমেন্টেশন ঘন ঘন আপডেট করা হয় না

দ্রষ্টব্য: যদি এটি আপনার অবস্থার প্রতিফলন না করে তবে নিজেকে খুব ভাগ্যবান মনে করুন।

এই ধরণের পরিস্থিতিতে আমরা প্রথমেই যা করতে চাই তা হল অ্যান্টিগ্রাভিটি যে প্রকল্পে কাজ করুক সেই প্রকল্পের একটি মানচিত্র বা প্রেক্ষাপট তৈরি করা। এই ধাপে অ্যান্টিগ্রাভিটিকে একটি বিদ্যমান কোডবেস সম্পর্কে গভীর ধারণা দেওয়ার একটি পদ্ধতির উদাহরণ দেখানো হয়েছে, যেখানে একটি দক্ষতা তৈরি করা হয়েছে যা সংগ্রহস্থল বিশ্লেষণ করে এবং একটি প্রকল্প প্রেক্ষাপট নথি তৈরি করে।

এটি প্রকল্পের গঠনতন্ত্রও স্থাপন করে — যে অ-আলোচনাযোগ্য নীতিগুলির বিরুদ্ধে SDD কর্মপ্রবাহ বৈধ। একসাথে, এগুলি অ্যান্টিগ্র্যাভিটিকে পরবর্তীতে SDD চক্রের জন্য প্রয়োজনীয় প্রেক্ষাপট এবং সীমাবদ্ধতা প্রদান করে।

অ্যান্টিগ্র্যাভিটি প্রসঙ্গ শ্রেণিবিন্যাস

অ্যান্টিগ্র্যাভিটি তিনটি স্তরের প্রেক্ষাপট ব্যবহার করে, প্রতিটির একটি ভিন্ন পরিধি রয়েছে:

• নিয়ম ( .agents/rules/ ): সর্বদা-সক্রিয় নির্দেশাবলী। এই কর্মক্ষেত্রের প্রতিটি কথোপকথনে সেগুলি দেখা যাবে (যদি আপনি এটি সক্রিয় করে থাকেন)। প্রকল্প-ব্যাপী প্রেক্ষাপটের জন্য নিয়মগুলি ব্যবহার করুন যেমন স্থাপত্য সিদ্ধান্ত, কোডিং মান, বা প্রযুক্তি স্ট্যাক তথ্য।
• দক্ষতা ( .agents/skills/ ): চাহিদা অনুযায়ী জ্ঞান। অ্যান্টিগ্র্যাভিটি কেবল তখনই একটি দক্ষতা লোড করে যখন বর্তমান কাজটি দক্ষতার description ক্ষেত্রের সাথে মেলে। ডোমেন-নির্দিষ্ট রেফারেন্স উপাদানের জন্য দক্ষতা ব্যবহার করুন।
• ওয়ার্কফ্লো ( .agents/workflows/ ): / কমান্ড দিয়ে ট্রিগার করা সংরক্ষিত প্রম্পট। SDD পাইপলাইনের মতো পুনরাবৃত্তিযোগ্য বহু-পদক্ষেপ প্রক্রিয়ার জন্য ওয়ার্কফ্লো ব্যবহার করুন।

দ্রষ্টব্য: প্রকল্পটিতে বর্তমানে কর্মপ্রবাহ (SDD পাইপলাইন) এবং একটি দক্ষতা (ADK এজেন্ট ডেভেলপমেন্ট) রয়েছে কিন্তু কোনও নিয়ম নেই। একটি project-context.md নিয়ম অ্যান্টিগ্রাভিটিকে কোডবেস সম্পর্কে অবিচল ধারণা দেয় — কোন প্রযুক্তি ব্যবহার করা হচ্ছে, ফাইলগুলি কীভাবে সংগঠিত করা হচ্ছে, এখন পর্যন্ত কী তৈরি করা হয়েছে।

দক্ষতা সক্রিয় করুন

স্টার্টার রেপোতে .agents/skills/ তে দুটি পূর্বে লিখিত দক্ষতা অন্তর্ভুক্ত রয়েছে। এগুলিতে বিস্তারিত নির্দেশাবলী রয়েছে তবে প্রয়োজনীয় YAML ফ্রন্টম্যাটারের পরিবর্তে TODO(codelab) মন্তব্য দিয়ে শুরু করুন। ফ্রন্টম্যাটার ছাড়া, অ্যান্টিগ্র্যাভিটি সেগুলি আবিষ্কার করতে পারে না।

অ্যান্টিগ্র্যাভিটি দক্ষতার জন্য ফাইলের শীর্ষে দুটি ক্ষেত্র সহ একটি YAML ফ্রন্টম্যাটার ব্লক প্রয়োজন:

• name — দক্ষতার জন্য একটি অনন্য শনাক্তকারী
• description — একটি প্রাকৃতিক ভাষার সারাংশ যা অ্যান্টিগ্র্যাভিটির সাথে মিলে যায় যখন কোনও প্রদত্ত অনুরোধের জন্য কোন দক্ষতা লোড করতে হবে তা নির্ধারণ করা হয়।

খোলা

.agents/skills/adk-agent-development/SKILL.md

এডিটরে । উপরের দুটি TODO(codelab) মন্তব্য লাইন এই ফ্রন্টম্যাটার দিয়ে প্রতিস্থাপন করুন:

---
name: adk-agent-development
description: Comprehensive guide for building, developing, and deploying AI agents using Google's Agent Development Kit (ADK) with Gemini models, covering agent creation, tools, state management, persistence, deployment, and database integration via MCP Toolbox.
---

দ্রষ্টব্য: ADK এজেন্ট ডেভেলপমেন্ট দক্ষতায় পাঁচটি ADK কোডল্যাব থেকে ঘনীভূত প্যাটার্ন এবং উদাহরণ রয়েছে — এজেন্ট কাঠামো, টুলের ধরণ, অবস্থা ব্যবস্থাপনা, স্থাপনা

খোলা

.agents/skills/repo-research/SKILL.md

এডিটরে । উপরের দুটি TODO(codelab) মন্তব্য লাইন এই ফ্রন্টম্যাটার দিয়ে প্রতিস্থাপন করুন:

---
name: repo-research
description: Analyze a repository's structure, technologies, and patterns to create or update a project context document. Use when asked to research, analyze, or understand a codebase.
---

নোট: repo-research SKILL.md বিস্তারিতভাবে পড়ুন। এটি আপনার সংগ্রহস্থল বিশ্লেষণ করার জন্য একটি উদাহরণ প্রম্পট, মনে রাখবেন যে ক্রমবর্ধমান আপডেট নিয়মগুলি ইচ্ছাকৃতভাবে রক্ষণশীল। যদি অ্যান্টিগ্র্যাভিটির প্রসঙ্গ গবেষণার মাঝখানে শেষ হয়ে যায় বা কথোপকথন ব্যাহত হয়, তাহলে এখন পর্যন্ত আবিষ্কৃত সবকিছু ইতিমধ্যেই ফাইলে সংরক্ষিত থাকে। দক্ষতা পুনরায় ব্যবহার করলে অগ্রগতি না হারিয়ে সেখান থেকে শুরু হয় যেখানে এটি শেষ হয়েছিল।

সাবধান! একটি বড় সংগ্রহস্থল বিশ্লেষণ করলে আপনার কোটা দ্রুত শেষ হয়ে যেতে পারে!

উভয় দক্ষতার বৈধ ফ্রন্টম্যাটার আছে কিনা তা যাচাই করুন:

head -4 .agents/skills/adk-agent-development/SKILL.md
head -4 .agents/skills/repo-research/SKILL.md

প্রতিটিতে --- ডিলিমিটার মোড়ানো name: এবং description: ক্ষেত্রগুলি দেখানো উচিত। যদি ডিলিমিটার বা ক্ষেত্রগুলি অনুপস্থিত থাকে, তাহলে অ্যান্টিগ্র্যাভিটি দক্ষতা চিনতে পারবে না।

উভয় দক্ষতাই চাহিদা অনুযায়ী লোড করা হয়েছে — অ্যান্টিগ্র্যাভিটি আপনার অনুরোধের সাথে description ক্ষেত্রের সাথে মেলে এবং শুধুমাত্র প্রাসঙ্গিক হলেই সম্পূর্ণ নির্দেশাবলী ব্যবহার করে।

প্রকল্পের প্রেক্ষাপট তৈরি করুন

নিয়ম ডিরেক্টরি বিদ্যমান আছে তা নিশ্চিত করুন:

mkdir -p .agents/rules

অ্যান্টিগ্র্যাভিটির এজেন্ট ম্যানেজার/চ্যাট বক্সে (এডিটর মোডে ctrl + L টিপুন), একটি নতুন কথোপকথন শুরু করুন। টাইপ করুন:

Research this repository and create a project context document

অ্যান্টিগ্র্যাভিটি আপনার অনুরোধকে repo-research দক্ষতার সাথে মেলায় এবং কোডবেসকে পদ্ধতিগতভাবে বিশ্লেষণ শুরু করে। এটি কনফিগারেশন ফাইল, সোর্স কোড এবং ডকুমেন্টেশন পড়ে, তারপর প্রকল্পের প্রসঙ্গ টেমপ্লেটটি তার ফলাফল দিয়ে পূর্ণ করে।

সম্পূর্ণ হয়ে গেলে, এডিটরে .agents/rules/project-context.md খুলুন। এতে প্রকল্প সম্পর্কে সুনির্দিষ্ট তথ্য রয়েছে: প্রযুক্তি স্ট্যাক (পাইথন 3.12, ADK, MCP টুলবক্স, ক্লাউড SQL), প্রকল্পের কাঠামো, ডেটা মডেল ( pgvector সহ মেনু_আইটেম টেবিল), এবং বহিরাগত ইন্টিগ্রেশন।

টিপস: প্রকল্পের প্রেক্ষাপট ডকুমেন্টটি প্রকল্পের বিকশিত হওয়ার সাথে সাথে বৃদ্ধি পায়। আপনি নতুন সংযোজন সহ প্রেক্ষাপট আপডেট করার দক্ষতাটি পুনরায় চালাতে পারেন। ক্রমবর্ধমান আপডেট নিয়মগুলি নিশ্চিত করে যে বিদ্যমান সামগ্রী সংরক্ষণ করা হয়েছে - নতুন প্রযুক্তি, সত্তা এবং ইন্টিগ্রেশনগুলি সংযুক্ত করা হয়েছে, ওভাররাইট করা হয়নি।

লক্ষ্যযুক্ত আপডেটের জন্য, নির্দিষ্ট প্রম্পট ব্যবহার করুন: "ডাটাবেস স্কিমা গবেষণা করুন এবং প্রকল্পের প্রসঙ্গ আপডেট করুন" অথবা "নতুন সরঞ্জাম সংজ্ঞা সহ প্রকল্পের প্রসঙ্গ আপডেট করুন।" প্রতিটি আমন্ত্রণ বিদ্যমান নথিতে যোগ করে।

প্রকল্পের গঠনতন্ত্র নির্ধারণ করুন

পরিকল্পনা এবং বিশ্লেষণের সময় SDD ওয়ার্কফ্লোগুলি .specify/memory/constitution.md এ একটি প্রকল্প গঠনতন্ত্রের উল্লেখ করে। /speckit.plan ওয়ার্কফ্লো এর বিরুদ্ধে একটি "সংবিধান পরীক্ষা" চালায় এবং /speckit.analyze লঙ্ঘনগুলিকে CRITICAL হিসাবে চিহ্নিত করে। যদি গঠনতন্ত্রটি প্লেসহোল্ডার টোকেন সহ একটি ফাঁকা টেমপ্লেট হিসাবে রেখে দেওয়া হয়, তবে এই চেকগুলির বিরুদ্ধে যাচাই করার মতো কিছুই নেই - পরিকল্পনা এবং বিশ্লেষণগুলি রেলিং ছাড়াই চলে।

সংবিধানে অ-আলোচনাযোগ্য প্রকল্প নীতিমালা সংজ্ঞায়িত করা হয়েছে। এটি একটি ছোট রেপো যা একজন একক বিকাশকারী দ্বারা রক্ষণাবেক্ষণ করা হয়, তাই সংবিধানে সেই সুযোগটি প্রতিফলিত করা উচিত - জিনিসগুলি সহজ, সামঞ্জস্যপূর্ণ রাখা এবং অতিরিক্ত প্রকৌশল এড়ানো।

অ্যান্টিগ্র্যাভিটির এজেন্ট ম্যানেজারে, একটি নতুন কথোপকথন শুরু করুন। সংবিধানের কর্মপ্রবাহ চালান:

/speckit.constitution This is a small restaurant concierge ADK agent maintained by one developer. Set 3 principles: (1) All database operations go through MCP Toolbox tool definitions in tools.yaml — no raw SQL in Python code, no ORM. (2) Session state uses ADK ToolContext — no custom state management, no external state stores. (3) Keep it simple — follow existing file and naming conventions exactly.

অ্যান্টিগ্র্যাভিটি সংবিধান টেমপ্লেটকে সুনির্দিষ্ট নীতি দিয়ে পূর্ণ করে, একটি সংস্করণ (1.0.0) বরাদ্দ করে এবং SDD টেমপ্লেট জুড়ে একটি ধারাবাহিকতা পরীক্ষা চালায়।

তৈরি করা সংবিধানটি .specify/memory/constitution.md ওয়েবসাইটে পর্যালোচনা করুন। তিনটি নীতি উপস্থিত এবং স্পষ্টভাবে বিবৃত আছে কিনা তা যাচাই করুন।

দ্রষ্টব্য: সংবিধানটি ইচ্ছাকৃতভাবে একজন একক ডেভেলপারের জন্য নির্ধারিত 3টি নীতিতে রাখা হয়েছে। /speckit.constitution কর্মপ্রবাহ ক্রমবর্ধমান সংশোধনী সমর্থন করে — অতিরিক্ত নীতির সাথে এটি আবার চালায় এবং এটি স্বয়ংক্রিয়ভাবে সংস্করণ পরিচালনা করে। একটি টিম প্রকল্পের জন্য, আপনি কোড পর্যালোচনা, পরীক্ষার শৃঙ্খলা, পর্যবেক্ষণযোগ্যতা এবং API সংস্করণের জন্য নীতিগুলি যুক্ত করতে পারেন।

চেকপয়েন্ট: .agents/rules/project-context.md রিপোজিটরি সম্পর্কে সুনির্দিষ্ট তথ্য রয়েছে। .agents/skills/repo-research/SKILL.md YAML ফ্রন্টম্যাটার, নির্দেশাবলী এবং দ্বন্দ্ব সমাধানের মাধ্যমে দক্ষতা তৈরির প্রদর্শন করে। .specify/memory/constitution.md এ তিনটি প্রকল্প নীতি রয়েছে যা পরিকল্পনা এবং বিশ্লেষণ কর্মপ্রবাহের বিরুদ্ধে বৈধ। আপনি তিন-স্তরের প্রেক্ষাপট শ্রেণিবিন্যাস বুঝতে পারেন: নিয়ম (সর্বদা-সক্রিয়), দক্ষতা (চাহিদা অনুযায়ী), কর্মপ্রবাহ (স্ল্যাশ কমান্ড)।

৬. এসডিডি সাইকেল — রিজার্ভেশন বৈশিষ্ট্য যোগ করুন

এই ধাপটি রেস্তোরাঁর কনসিয়ারজ এজেন্টের সাথে রিজার্ভেশন বুকিং যোগ করার জন্য একটি সম্পূর্ণ SDD চক্রের মধ্য দিয়ে যায়। আপনি প্রতিটি ধাপে অ্যান্টিগ্রাভিটি পরিচালনা করেন — নির্দিষ্ট করুন, স্পষ্ট করুন, পরিকল্পনা করুন, কাজ করুন, বিশ্লেষণ করুন, বাস্তবায়ন করুন — প্রতিটি শিল্পকর্ম পূর্ববর্তীটির উপর কীভাবে তৈরি হয় তা পর্যবেক্ষণ করুন। এটি কোডল্যাবের মূল শেখার অভিজ্ঞতা।

গুরুত্বপূর্ণ! অ্যান্টিগ্র্যাভিটি একটি এআই সহকারী — এর তৈরি আর্টিফ্যাক্টগুলি (স্পেসিফিকেশন, প্ল্যান, টাস্ক, কোড) এই টিউটোরিয়ালে বর্ণিত থেকে আলাদা হতে পারে। ফাইলের নাম, সঠিক এসকিউএল স্কিমা এবং কোড কাঠামো ভিন্ন হতে পারে। এটি প্রত্যাশিত এবং এআই-সহায়তাপ্রাপ্ত ডেভেলপমেন্টের সাথে কাজ করার অংশ। এসডিডি ওয়ার্কফ্লো নিশ্চিত করে যে আপনি প্রতিটি আর্টিফ্যাক্ট কোডে পরিণত হওয়ার আগে পর্যালোচনা করেন, তাই আপনার প্রত্যাশার সাথে মেলে না এমন যেকোনো আউটপুট গ্রহণ, পরিবর্তন বা পুনরুত্পাদন করার জন্য আপনার বিচারবুদ্ধি ব্যবহার করুন।

বৈশিষ্ট্যটি নির্দিষ্ট করুন

অ্যান্টিগ্র্যাভিটির এজেন্ট ম্যানেজারে, একটি নতুন কথোপকথন শুরু করুন। বৈশিষ্ট্যের বর্ণনা সহ /speckit.specify ওয়ার্কফ্লো কমান্ডটি টাইপ করুন:

/speckit.specify Add reservation booking capability to the restaurant concierge agent. Guests should be able to make a table reservation by providing their name, party size, date, and time. They should also be able to check existing reservations. The agent should confirm reservation details before booking and handle special requests (e.g., "window seat", "birthday celebration").

অ্যান্টিগ্র্যাভিটি একটি বৈশিষ্ট্য শাখা তৈরি করে, একটি স্পেসিফিকেশন ডকুমেন্ট তৈরি করে এবং গুণমান যাচাইকরণ চালায়। যদি অ্যান্টিগ্র্যাভিটি স্পষ্টীকরণের প্রশ্ন উপস্থাপন করে, তাহলে উপরের বৈশিষ্ট্য বর্ণনার উপর ভিত্তি করে তাদের উত্তর দিন।

দ্রষ্টব্য: স্পেসিফিকেশন সম্পন্ন করার পর, অ্যান্টিগ্র্যাভিটি "বিল্ড টেকনিক্যাল প্ল্যান" অথবা "স্পেক রিকোয়ারমেন্ট স্পষ্ট করুন" এর মতো হ্যান্ডঅফ উপস্থাপন করতে পারে। এগুলি পরবর্তী ওয়ার্কফ্লো পর্যায়ের ( /speckit.plan অথবা /speckit.clarify ) ইঙ্গিত দেয়।

স্পেসিফিকেশনটি WHAT এবং WHY - HOW নয় - এর উপর ফোকাস করে। এটি SQL টেবিল, tools.yaml , অথবা ADK API উল্লেখ না করে ব্যবহারকারীর অভিজ্ঞতা বর্ণনা করে ("অতিথিরা তাদের নাম, পার্টির আকার, তারিখ এবং সময় প্রদান করে একটি রিজার্ভেশন বুক করতে পারেন")। বাস্তবায়নের বিবরণ পরিকল্পনা পর্যায়ে আসে।

specs/<branch-name>/spec.md ওয়েবসাইটে জেনারেট করা স্পেসিফিকেশন পর্যালোচনা করুন। যাচাই করুন যে এটি কার্যকরী প্রয়োজনীয়তা এবং সাফল্যের মানদণ্ড ক্যাপচার করে।

স্পেসিফিকেশন স্পষ্ট করুন (ঐচ্ছিক)

স্পেসিফিকেশনে অনির্দিষ্ট এলাকাগুলি সনাক্ত এবং সমাধান করতে স্পষ্টীকরণ কর্মপ্রবাহ চালান:

/speckit.clarify

অ্যান্টিগ্র্যাভিটি স্পেকটিকে অস্পষ্টতা, অনুপস্থিত গ্রহণযোগ্যতার মানদণ্ড এবং অনির্দিষ্ট প্রয়োজনীয়তার জন্য স্ক্যান করে। এটি লক্ষ্যযুক্ত স্পষ্টীকরণ প্রশ্ন জিজ্ঞাসা করে — প্রতিটির উত্তর একটি সংক্ষিপ্ত নির্বাচন বা বাক্যাংশ দিয়ে দেওয়া হয়। আপনার উত্তরগুলি সরাসরি স্পেকের মধ্যে এনকোড করা হয়, যা পরিকল্পনা শুরু করার আগে এটিকে আরও সুনির্দিষ্ট করে তোলে।

টিপস: স্পষ্টীকরণের ধাপটি ঐচ্ছিক কিন্তু জটিল বৈশিষ্ট্যের জন্য সুপারিশ করা হয়। সহজ স্পেসিফিকেশনের জন্য, সরাসরি পরিকল্পনায় চলে যান।

বাস্তবায়নের পরিকল্পনা করুন

পরিকল্পনা কর্মপ্রবাহ চালান:

/speckit.plan

অ্যান্টিগ্র্যাভিটি দুটি পর্যায়ের মাধ্যমে একটি প্রযুক্তিগত পরিকল্পনা তৈরি করে:

1. গবেষণা পর্যায় — বিদ্যমান কোডবেস সম্পর্কে অজানা সমস্যার সমাধান করে, research.md তৈরি করে।
2. ডিজাইন ফেজ — data-model.md (রিজার্ভেশন সত্তা সংজ্ঞা) তৈরি করে এবং project-context.md আপডেট করে।

পরিকল্পনার সময় অ্যান্টিগ্র্যাভিটির জন্য adk-agent-development দক্ষতা ব্যবহার করা উচিত। মূল শিল্পকর্মগুলি পর্যালোচনা করুন:

• specs/<branch-name>/plan.md — প্রযুক্তিগত পদ্ধতি: কোন ফাইলগুলি পরিবর্তন করতে হবে, কোন প্যাটার্নগুলি অনুসরণ করতে হবে
• specs/<branch-name>/data-model.md — রিজার্ভেশন সত্তার সংজ্ঞা (কলাম, প্রকার, সম্পর্ক)
• specs/<branch-name>/research.md — গৃহীত সিদ্ধান্ত এবং যুক্তি

কাজ তৈরি করুন

টাস্ক ওয়ার্কফ্লো চালান

/speckit.tasks

অ্যান্টিগ্র্যাভিটি পরিকল্পনাটিকে specs/<branch-name>/tasks.md তে একটি ক্রমানুসারে টাস্ক তালিকায় বিভক্ত করে। টাস্কগুলি আইডি, অগ্রাধিকার মার্কার এবং ফাইল পাথ সহ একটি কঠোর চেকলিস্ট ফর্ম্যাট অনুসরণ করে, উদাহরণস্বরূপ:

- [ ] [T001] [P] Create reservations table schema in scripts/seed_db.py
- [ ] [T002] [P] Add create_reservation tool to tools.yaml
- [ ] [T003] [P] Add list_reservations tool to tools.yaml
- [ ] [T004] [P] Update agent instruction in restaurant_concierge/agent.py

কাজগুলি পর্যায়ক্রমে সংগঠিত করা হয়: সেটআপ → ফাউন্ডেশনাল → ব্যবহারকারীর গল্প → পোলিশ। কী তৈরি এবং পরিবর্তন করা হবে তা বুঝতে টাস্ক তালিকাটি স্ক্যান করুন।

কাজ বিশ্লেষণ করুন (ঐচ্ছিক)

ঝুঁকি এবং ফাঁকগুলির জন্য কাজগুলি পর্যালোচনা করতে বিশ্লেষণ কর্মপ্রবাহ চালান:

/speckit.analyze

অ্যান্টিগ্র্যাভিটি স্পেক এবং পরিকল্পনার সাথে টাস্ক লিস্ট পরীক্ষা করে, মিসিং এজ কেস, সাংঘর্ষিক কাজ, অথবা স্পেকের প্রয়োজনীয়তা এবং পরিকল্পিত কাজের মধ্যে ফাঁক খুঁজে বের করে। বাস্তবায়নের আগে গুরুত্বপূর্ণ সমস্যাগুলি সমাধান করুন।

টিপস: বিশ্লেষণ ধাপটি সবচেয়ে কার্যকর যখন কাজের তালিকা দীর্ঘ হয় অথবা বৈশিষ্ট্যটি একাধিক সাবসিস্টেমকে স্পর্শ করে। রিজার্ভেশন বুকিংয়ের মতো একটি ফোকাসড বৈশিষ্ট্যের জন্য, একটি দ্রুত স্ক্যান যথেষ্ট।

৭. বাস্তবায়ন

বাস্তবায়ন কর্মপ্রবাহ চালান:

/speckit.implement

অ্যান্টিগ্র্যাভিটি একটি চূড়ান্ত বাস্তবায়ন পরিকল্পনা এবং কার্য নিদর্শন উপস্থাপন করে। এটি পর্যালোচনা করুন এবং এগিয়ে যাওয়ার জন্য অনুমোদন করুন।

টিপস: আপনি সরাসরি এতে মন্তব্য করতে পারেন! এটি শুধুমাত্র অ্যান্টিগ্র্যাভিটি বিল্ট-ইন আর্টিফ্যাক্ট দিয়ে করা যেতে পারে।

অ্যান্টিগ্র্যাভিটি কাজগুলো সম্পাদন করে, প্রতিটি কাজ সম্পন্ন করার সাথে সাথে টিক চিহ্ন দেয়। এটি সম্পন্ন হলে, এটি সম্পূর্ণ ওয়াকথ্রু উপস্থাপন করবে।

কোড পরিবর্তনগুলি পরীক্ষা করুন

বাস্তবায়ন সম্পন্ন হওয়ার পর, মূল পরিবর্তনগুলি করা হয়েছে কিনা তা যাচাই করুন। সঠিক ফাইলের নাম এবং বিষয়বস্তু ভিন্ন হতে পারে, তবে এই প্যাটার্নগুলি tools.yaml এবং agent.py এর মতো উপস্থিত থাকা উচিত:

# Verify reservation tools were added to tools.yaml
grep -i "reservation" tools.yaml

তুমি এরকম কিছু আউটপুট দেখতে পাবে

...
get_reservations_by_name:
      Retrieve all reservations for a guest by their name. Uses case-insensitive
      SELECT id, guest_name, party_size, reservation_datetime, special_requests, created_at
      FROM reservations
      ORDER BY reservation_datetime DESC
...

এবং agent.py এর জন্য

# Verify agent instruction was updated
grep -i "reservation" restaurant_concierge/agent.py

# Check what files changed
git diff --name-only

হয়তো তুমি এরকম পরিবর্তন খুঁজে পাবে

...
- **Table Reservations**: Help guests book a table or check their existing reservations.
## Reservation Booking Rules
When a guest wants to make a reservation, collect ALL of the following before confirming:
**IMPORTANT**: Before calling `book_reservation`, you MUST:
- Only call `book_reservation` after the guest says "yes" or "confirm"
## Checking Reservations
When a guest asks to check their reservations:
- Use `get_reservations_by_name` to find their bookings
        book_reservation,
...

দ্রষ্টব্য: যদি grep ফাইলের যেকোনো একটির সাথে কোনও মিল না ফেরায়, তাহলে বাস্তবায়নে ভিন্ন নামকরণ ব্যবহার করা হতে পারে। পরিবর্তনের সম্পূর্ণ সেট দেখতে এবং সংরক্ষণ-সম্পর্কিত যুক্তি যোগ করা হয়েছে কিনা তা যাচাই করতে git diff পরীক্ষা করুন।

পরিবর্তনগুলি বীজ ডাটাবেস স্ক্রিপ্টকে প্রভাবিত করবে, আসুন এটি কার্যকর করার চেষ্টা করি।

source .env
uv run python scripts/seed_db.py

যদি আপডেট করা স্ক্রিপ্টটি ইতিমধ্যেই বিদ্যমান না থাকে, তাহলে reservations টেবিলটি তৈরি করা উচিত। আপনি নতুন টেবিল তৈরি হয়েছে তা নিশ্চিত করে আউটপুট দেখতে পাবেন (বিদ্যমান menu_items ডেটা সংরক্ষিত আছে)।

দ্রষ্টব্য: অ্যান্টিগ্রাভিটি seed_db.py আপডেট করার পরিবর্তে একটি পৃথক মাইগ্রেশন স্ক্রিপ্ট (যেমন, scripts/create_reservations.py ) তৈরি করে থাকতে পারে। scripts/ এ যেকোনো নতুন স্ক্রিপ্টের জন্য git diff --name-only চেক করুন এবং পরিবর্তে সেগুলি চালান।

যদি সবকিছু এই পর্যায়ে ঠিকঠাক থাকে, তাহলে আমরা ADK এজেন্ট Dev UI-তে বৈশিষ্ট্যটি পরীক্ষা করতে পারি। tools.yaml এ নতুন টুল সংজ্ঞাগুলি পেতে টুলবক্সটি পুনরায় চালু করুন। বিদ্যমান যেকোনো টুলবক্স প্রক্রিয়া বন্ধ করুন, তারপর একটি নতুন শুরু করুন:

pkill -f toolbox 2>/dev/null
toolbox --tools-file tools.yaml --address 127.0.0.1 --port 5000 &

ADK ডেভেলপার UI শুরু করুন:

uv run adk web .

আপনার ব্রাউজারে http://localhost:8000 খুলুন এবং এই প্রম্পটগুলি দিয়ে পরীক্ষা করুন:

I'd like to book a table for 4 people on Friday at 7pm under the name Timmy

পরিদর্শন করুন: এজেন্টকে রিজার্ভেশনের বিবরণ নিশ্চিত করতে হবে এবং এটি তৈরি করতে হবে।

Do I have any upcoming reservations?

পরিদর্শন করুন: এজেন্টকে আপনার করা রিজার্ভেশনের তালিকা তৈরি করতে হবে।

এখন, Ctrl+C দুবার চেপে ADK ডেভেলপার UI বন্ধ করুন।

চেকপয়েন্ট: এজেন্ট রিজার্ভেশন বুকিং এবং লুকআপ পরিচালনা করে। আপনি একটি সম্পূর্ণ SDD চক্র সম্পন্ন করেছেন: নির্দিষ্ট করুন → স্পষ্ট করুন → পরিকল্পনা → কাজ → বিশ্লেষণ → বাস্তবায়ন → পরীক্ষা। প্রতিটি ধাপে specs/<branch-name>/ তে একটি সংস্করণযুক্ত আর্টিফ্যাক্ট তৈরি করা হয়েছে।

৮. চ্যালেঞ্জ (ঐচ্ছিক)

এখন তুমি সম্পূর্ণ SDD ওয়ার্কফ্লো জানো। এটি পরীক্ষা করে দেখো:

• রেস্তোরাঁর কনসিয়ারজের জন্য একটি ওয়েব চ্যাট ইন্টারফেস তৈরি করতে দ্বিতীয় SDD চক্র চালান — এবার ধাপে ধাপে নির্দেশিকা ছাড়াই।
• উৎপাদন পরিস্থিতির জন্য আপনার এজেন্টকে ক্লাউড রানে মোতায়েন করুন।

ইঙ্গিত

• এই প্রকল্পের কোনও ফ্রন্টএন্ড ফ্রেমওয়ার্ক নেই। অ্যান্টিগ্র্যাভিটির ভ্যানিলা HTML/CSS/JS প্রস্তাব করা উচিত — যদি এটি React বা অনুরূপ প্রস্তাব করে, তাহলে এটিকে সরলতার দিকে ঠেলে দিন (আপনার সংবিধানের "কিপ ইট সিম্পল" নীতিটি এটি ধরা উচিত)।
• ADK সার্ভার স্ট্রিমিংয়ের জন্য /run_sse এবং সেশন পরিচালনার জন্য /apps/{app_name}/users/{user_id}/sessions এক্সপোজ করে। অ্যান্টিগ্র্যাভিটি প্রকল্পের প্রেক্ষাপট থেকে এগুলি আবিষ্কার করে।
• বাস্তবায়নের পরে, সার্ভারটি uv run uvicorn server:app --host 0.0.0.0 --port 8080 ( adk web নয়) চালান যাতে স্ট্যাটিক ফাইল মাউন্ট কাজ করে।
• http://localhost:8080/static/index.html এ পরীক্ষা করুন।
• রেফারেন্স কোডল্যাবগুলি ইতিমধ্যেই দেখায় যে কীভাবে ADK এজেন্ট স্থাপন এবং টিকিয়ে রাখতে হয়, এর জন্য অ্যান্টিগ্র্যাভিটি রেফারেন্স দিন!

9. অভিনন্দন!

আপনি একজন রেস্তোরাঁর কনসিয়ারজ ADK এজেন্টকে রিজার্ভেশন বুকিং দিয়ে সাহায্য করেছেন — সম্পূর্ণরূপে অ্যান্টিগ্রাভিটির SDD ওয়ার্কফ্লো দিয়ে, হাতে আবেদন কোড না লিখেই।

তুমি যা তৈরি করেছো

• মেনু অনুসন্ধান, শব্দার্থিক অনুসন্ধান, খাদ্যতালিকাগত পছন্দ ট্র্যাকিং এবং রিজার্ভেশন বুকিং সহ একজন রেস্তোরাঁ কনসির্জ ADK এজেন্ট
• রেপো গবেষণার জন্য একটি অ্যান্টিগ্র্যাভিটি দক্ষতা যা একটি প্রকল্পের প্রসঙ্গ নথি তৈরি এবং রক্ষণাবেক্ষণ করে।
• একটি প্রকল্প গঠনতন্ত্র যা পরিকল্পনা এবং বিশ্লেষণের সময় অ-আলোচনাযোগ্য নীতিগুলি প্রয়োগ করে
• একটি সম্পূর্ণ SDD চক্র যা নির্দিষ্টকরণ → স্পষ্টীকরণ → পরিকল্পনা → কার্যাবলী → বিশ্লেষণ → কর্মপ্রবাহ বাস্তবায়ন প্রদর্শন করে।

তুমি যা শিখেছো

• অ্যান্টিগ্র্যাভিটিতে স্পেক-ড্রিভেন ডেভেলপমেন্ট ওয়ার্কফ্লো কীভাবে ব্যবহার করে একটি বিদ্যমান কোডবেসে পদ্ধতিগতভাবে বৈশিষ্ট্য যুক্ত করবেন
• কথোপকথন জুড়ে পুনঃব্যবহারের জন্য ডোমেন জ্ঞান প্যাকেজ করার জন্য অ্যান্টিগ্র্যাভিটি দক্ষতা কীভাবে তৈরি করবেন
• কীভাবে প্রকল্পের প্রেক্ষাপট বুটস্ট্র্যাপ করবেন যাতে অ্যান্টিগ্র্যাভিটি স্থাপত্য, নিদর্শন এবং প্রযুক্তি পছন্দ সম্পর্কে সচেতন সিদ্ধান্ত নেয়
• SDD কর্মপ্রবাহের সাথে বৈধতা যাচাই করে এমন একটি প্রকল্প গঠনতন্ত্র কীভাবে সেট করবেন
• MCP টুলবক্সের মাধ্যমে নতুন ডাটাবেস-সমর্থিত টুল সহ একটি ADK এজেন্টকে কীভাবে প্রসারিত করবেন

পরিষ্কার করা

যেকোনো চলমান স্থানীয় প্রক্রিয়া বন্ধ করুন (টুলবক্স):

pkill -f toolbox 2>/dev/null

চলমান চার্জ এড়াতে ক্লাউড SQL ইনস্ট্যান্সটি মুছে ফেলুন:

gcloud sql instances delete restaurant-db --quiet

ঐচ্ছিকভাবে, সম্পূর্ণ প্রকল্পটি মুছে ফেলুন:

gcloud projects delete $GOOGLE_CLOUD_PROJECT

গুরুত্বপূর্ণ: আপনি gcloud projects undelete ${GOOGLE_CLOUD_PROJECT} এই কমান্ডটি ব্যবহার করে সীমিত সময়ের জন্য এই ডিলিট অপারেশনটি পূর্বাবস্থায় ফেরাতে পারেন।