การพัฒนาเอเจนต์ ADK ที่ขับเคลื่อนด้วยข้อมูลจำเพาะด้วย Antigravity และ Spec-kit

1. บทนำ

การเพิ่มฟีเจอร์ลงในเอเจนต์ที่มีอยู่ ซึ่งเป็นความสามารถใหม่ที่ใช้ฐานข้อมูล โดยทั่วไปหมายถึงการเขียนโค้ดต้นแบบ การเชื่อมต่อการผสานรวม และการทำให้ทุกอย่างสอดคล้องกับรูปแบบที่มีอยู่ในโค้ดเบสอยู่แล้ว Antigravity เร่งกระบวนการนี้ในทุกขั้นตอน โดยจะวิเคราะห์ฐานของโค้ดเพื่อสร้างบริบทที่ต้องการ สร้างข้อกำหนดที่มีโครงสร้างและแผนการติดตั้งใช้งานเพื่อให้คุณตรวจสอบ และดำเนินการเปลี่ยนแปลงโค้ด ทั้งหมดนี้จะได้รับการแนะนำจากความรู้เกี่ยวกับโดเมนที่ช่วยให้คุณรวบรวมเป็นทักษะที่นำกลับมาใช้ใหม่ได้ และเป็นธรรมนูญของโปรเจ็กต์ที่บังคับใช้หลักการที่ต่อรองไม่ได้ Codelab นี้จะแนะนำวิธีเพิ่มประสิทธิภาพกระบวนทัศน์การพัฒนาที่ขับเคลื่อนด้วยข้อกำหนดของ Antigravity โดยการแนะนำวงจรใหม่เพื่อเพิ่มเอกสารประกอบข้อกำหนดที่อ้างอิง spec-kit อย่างมาก

สิ่งที่คุณจะสร้าง

แอปพลิเคชันเจ้าหน้าที่อำนวยความสะดวกของร้านอาหารที่ทำงานในพื้นที่พร้อมการจองที่เพิ่มเข้ามาผ่านวงจร SDD ที่สมบูรณ์

• การจอง - แขกจองโต๊ะและตรวจสอบการจอง โดยมีเครื่องมือฐานข้อมูล MCP Toolbox ใหม่และตาราง reservations ของ Cloud SQL เป็นข้อมูลสนับสนุน
• (ความท้าทาย) - พัฒนา UI ของตัวแทนของคุณเอง
• (Challenge) – Deploy ไปยัง Google Cloud โดยใช้ความช่วยเหลือจากตัวแทน Antigravity

โค้ดเริ่มต้นมี Agent ADK ที่ใช้งานได้พร้อมการค้นหาเมนู (คีย์เวิร์ด + ความหมายผ่าน MCP Toolbox) และการติดตามค่ากำหนดด้านอาหาร (ผ่าน ToolContext) คุณขยายได้โดยไม่ต้องเขียนโค้ดแอปพลิเคชันด้วยตนเอง เนื่องจาก Antigravity จะจัดการการติดตั้งใช้งานตามข้อกำหนดของคุณ

สิ่งที่คุณจะได้เรียนรู้

• วิธีเริ่มต้นบริบทของโปรเจ็กต์เพื่อให้ Antigravity เข้าใจโค้ดเบสที่มีอยู่
• วิธีสร้างทักษะ Antigravity ที่รวมความรู้เฉพาะด้าน (เช่น รูปแบบ Codelab ของ ADK) เพื่อนำกลับมาใช้ใหม่
• วิธีตั้งค่าธรรมนูญของโปรเจ็กต์ที่เวิร์กโฟลว์ SDD จะตรวจสอบเทียบระหว่างการวางแผนและการวิเคราะห์
• วิธีใช้เวิร์กโฟลว์การพัฒนาที่ขับเคลื่อนด้วยข้อกำหนด (SDD) ใน Antigravity เพื่อเพิ่มฟีเจอร์อย่างเป็นระบบ
• วิธีขยายเอเจนต์ ADK ด้วยเครื่องมือใหม่ที่ใช้ฐานข้อมูลผ่าน MCP Toolbox

ข้อกำหนดเบื้องต้น

• Google Antigravity และ git ติดตั้งในเครื่องของคุณ
• บัญชี Google Cloud ที่เปิดใช้บัญชีสำหรับการเรียกเก็บเงินเวอร์ชันทดลอง
• การทำ Codelab ของ ADK ทั้ง 4 รายการที่จำเป็นก่อนหน้านี้ (หรือความรู้ที่เทียบเท่า) จะช่วยให้เข้าใจบริบทของ Use Case ได้
• การสร้างเอเจนต์ AI ด้วย ADK: พื้นฐาน
• การสร้าง AI Agent ด้วย ADK: การเพิ่มศักยภาพด้วยเครื่องมือ
• การสร้างเอเจนต์ AI แบบถาวรด้วย ADK และ CloudSQL
• ติดตั้งใช้งาน จัดการ และตรวจสอบ Agent ของ ADK ใน Cloud Run
• ฐานข้อมูลในฐานะเครื่องมือ: RAG แบบเอเจนต์ที่มี ADK, MCP Toolbox และ Cloud SQL

2. ตั้งค่าสภาพแวดล้อม

หมายเหตุสำคัญ:

บทแนะนำนี้ต้องใช้โปรเจ็กต์ Google Cloud ที่มีบัญชีสำหรับการเรียกเก็บเงินที่ใช้งานอยู่ หากยังไม่มีบัญชี โปรดทำตามขั้นตอนด้านล่างเพื่อรับบัญชีสำหรับการเรียกเก็บเงินช่วงทดลองใช้ที่ใช้กับบทแนะนำนี้ได้

1. เปิดหน้าต่างที่ไม่ระบุตัวตน
2. หากเข้าร่วมเซสชันเวิร์กช็อป โดยปกติแล้ว URL ของพอร์ทัลการแลกรับข้อเสนอจะระบุไว้ในเซสชันดังกล่าว หรือคุณจะไปที่พอร์ทัลการแลกรับข้อเสนอสำหรับบัญชีการเรียกเก็บเงินแบบทดลองใช้นี้ก็ได้
3. เข้าสู่ระบบโดยใช้บัญชี Gmail ส่วนตัว ( Google Workspace / อีเมลอื่นๆ จะใช้ไม่ได้ )
4. ทำตามวิธีการแลกรับข้อเสนอแบบทีละขั้นตอน

ขั้นตอนนี้จะโคลนที่เก็บเริ่มต้น ตรวจสอบสิทธิ์กับ Google Cloud จัดสรรฐานข้อมูล Cloud SQL และเตรียมสภาพแวดล้อม Antigravity ในเครื่อง

หมายเหตุ: Codelab นี้ทำงานใน Google Antigravity บนเครื่องของคุณทั้งหมด การตั้งค่ารวมถึงการตรวจสอบสิทธิ์ด้วยตนเองโดยใช้gcloud CLI command

โคลนที่เก็บเริ่มต้น

เปิดเทอร์มินัลใน Antigravity (หรือเทอร์มินัลของระบบ) โคลนที่เก็บคู่กันและเข้าสู่ไดเรกทอรี

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

เปิดที่เก็บที่โคลนใน Antigravity File->Open Folder->เลือกไดเรกทอรีที่โคลน sdd-adk-agents-agy

นำรีโมตต้นทางออก เวิร์กโฟลว์ SDD จะสร้างกิ่ง Git สำหรับข้อกำหนดฟีเจอร์ การนำรีโมตออกจะช่วยป้องกันการพุชไปยังที่เก็บเริ่มต้นโดยไม่ตั้งใจ

git remote remove origin

สำคัญ: เวิร์กโฟลว์ SDD ใน Codelab นี้ใช้กิ่ง git เพื่อจัดระเบียบข้อกำหนดของฟีเจอร์ การนำรีโมต origin ออกจะช่วยให้สาขาและการคอมมิตในเครื่องยังคงอยู่ในเครื่อง หากต้องการสำรองข้อมูลงาน ให้เพิ่มรีโมตของคุณเองโดยทำดังนี้ git remote add origin <your-repo-url>

ติดตั้งข้อกำหนดเบื้องต้น

เรียกใช้สคริปต์ข้อกำหนดเบื้องต้น โดยจะตรวจสอบ (และติดตั้งหากไม่มี) git, curl, gcloud, uv, Python 3.12 และ MCP Toolbox ดังนี้

bash scripts/setup_prerequisites.sh

หมายเหตุ: การดาวน์โหลดข้อกำหนดเบื้องต้นทั้งหมดจะใช้เวลาสักครู่ ให้เปิดแท็บใหม่เพื่อไปยังส่วนถัดไปขณะรอให้ดาวน์โหลดเสร็จ

ตรวจสอบสิทธิ์ด้วย Google Cloud

เรียกใช้คำสั่งการตรวจสอบสิทธิ์ 2 คำสั่ง ทั้ง 2 อย่างจะเปิดเบราว์เซอร์สำหรับ OAuth

gcloud auth login
gcloud auth application-default login

หมายเหตุ: ในคำสั่ง OAuth ที่ 2 เมื่อระบบแจ้งให้เลือกสิทธิ์ ตรวจสอบตัวเลือกทั้งหมด

หมายเหตุ: ตรวจสอบว่าคุณได้ตรวจสอบสิทธิ์ด้วยอีเมลที่ใช้ในการอ้างสิทธิ์บัญชีสำหรับการเรียกเก็บเงินของช่วงทดลองใช้

เนื่องจากคุณทำงานในพื้นที่กับ Antigravity คุณจึงต้องตรวจสอบสิทธิ์ด้วยตนเอง auth login จะตรวจสอบสิทธิ์ gcloud CLI application-default login ตรวจสอบสิทธิ์ Google Cloud SDK ที่แอปพลิเคชันของคุณใช้ ซึ่งการเรียก Vertex AI ของ ADK และตัวเชื่อมต่อ Python ของ Cloud SQL ต่างก็อาศัยข้อมูลเข้าสู่ระบบเริ่มต้นของแอปพลิเคชัน

ตั้งค่าโปรเจ็กต์ Google Cloud

เขียนตัวแปรตำแหน่งไปยัง .env ก่อนเรียกใช้สคริปต์การตั้งค่าโปรเจ็กต์

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

• GOOGLE_CLOUD_LOCATION=global ใช้สำหรับการเรียก Vertex AI / Gemini API
• REGION=us-central1 ใช้สำหรับ Cloud SQL และโครงสร้างพื้นฐานอื่นๆ ของ GCP

ดาวน์โหลดและเรียกใช้สคริปต์การตั้งค่าโปรเจ็กต์ โดยจะสร้างหรือตรวจสอบโปรเจ็กต์ Google Cloud ที่มีการเรียกเก็บเงินแบบทดลองใช้ และบันทึกรหัสโปรเจ็กต์ไว้ใน .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 อาจใช้เวลาสักครู่ คุณต้องทำขั้นตอนนี้เพียงครั้งเดียวต่อโปรเจ็กต์

จัดสรร Cloud SQL

ตั้งรหัสผ่านฐานข้อมูลและเพิ่มลงใน .env โดยทำดังนี้

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

สำคัญ: รหัสผ่านที่ฮาร์ดโค้ดด้านบนมีไว้เพื่อวัตถุประสงค์ในการสอนเท่านั้น ในสภาพแวดล้อมการใช้งานจริง ให้จัดเก็บข้อมูลเข้าสู่ระบบอย่างปลอดภัยโดยใช้บริการอย่าง Secret Manager และอ้างอิงข้อมูลดังกล่าวในขณะรันไทม์ โดยอย่าส่งข้อมูลลับที่เป็นข้อความธรรมดาไปยังการควบคุมแหล่งที่มา

สร้างอินสแตนซ์ Cloud 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 เป็นระดับขั้นต่ำที่จำเป็นสำหรับการผสานรวม ML ของ Vertex AI แฟล็ก --enable-google-ml-integration ช่วยให้ Cloud SQL เรียกใช้โมเดลการฝังของ Gemini จาก SQL ได้โดยตรง ซึ่งจะขับเคลื่อนฟีเจอร์การค้นหาเชิงความหมาย

หมายเหตุ: คำสั่งนี้ใช้เวลาประมาณ 5 นาทีและจะทำงานในเบื้องหลัง ปล่อยให้ทำงานในแท็บเทอร์มินัลนี้และเปิดแท็บเทอร์มินัลใหม่สำหรับขั้นตอนถัดไป

ติดตั้งการอ้างอิง

เปิดแท็บเทอร์มินัลใหม่ ตรวจสอบว่าคุณยังอยู่ในไดเรกทอรีโปรเจ็กต์ของที่เก็บที่โคลนไว้และโหลดตัวแปรสภาพแวดล้อมอีกครั้ง

source .env

เราจะใช้ uv เป็นเครื่องมือจัดการโปรเจ็กต์ Python uv เป็นเครื่องมือจัดการแพ็กเกจและโปรเจ็กต์ Python ที่รวดเร็วซึ่งเขียนด้วย Rust ( เอกสาร ) Codelab นี้ใช้เพื่อความเร็วและความเรียบง่าย ติดตั้งการอ้างอิง Python ด้วยคำสั่งต่อไปนี้

uv sync

จากนั้นอัปเดตไฟล์ .env ของตัวแทน ADK ด้วยการกำหนดค่าโปรเจ็กต์ของคุณ

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

ตอนนี้เราควรมีที่เก็บตัวแทน ADK เริ่มต้นที่จำเป็นทั้งหมดพร้อมใช้งานแล้ว ตอนนี้มาพูดถึง Antigravity และการพัฒนาที่อิงตามข้อกำหนดในส่วนถัดไปกันในขณะที่รอให้ทุกอย่างพร้อม

3. สำรวจโค้ดเริ่มต้นและทำความเข้าใจการพัฒนาที่ขับเคลื่อนด้วยข้อกำหนด

ขั้นตอนนี้จะอธิบายโครงสร้างโค้ดเริ่มต้น แนะนำวิธีการพัฒนาที่ขับเคลื่อนด้วยข้อกำหนด สร้างฐานข้อมูล และยืนยันว่าเอเจนต์พื้นฐานทำงานได้ก่อนที่คุณจะเริ่มขยาย

โครงสร้างโปรเจ็กต์

เปิดโปรเจ็กต์ที่โคลนจากที่เก็บในโปรแกรมแก้ไข Antigravity แล้วตรวจสอบเลย์เอาต์ไดเรกทอรี

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 Agent จะโหลดเครื่องมือทั้งหมดจากเซิร์ฟเวอร์กล่องเครื่องมือและเพิ่มฟังก์ชัน Python 2 รายการ (save_dietary_preference, get_dietary_preferences) ที่ใช้ ToolContext เพื่อจัดการสถานะ
• tools.yaml — คำจำกัดความของเครื่องมือกล่องเครื่องมือ MCP เครื่องมือค้นหาในเมนู 3 รายการ ได้แก่ การค้นหาคีย์เวิร์ด (search_menu) การค้นหาเชิงความหมายผ่าน pgvector (semantic_search_menu) และตัวกรองหมวดหมู่ (get_menu_by_category) ยังไม่มีเครื่องมือการจอง คุณจะเพิ่มเครื่องมือเหล่านั้นในภายหลัง
• server.py — เซิร์ฟเวอร์ FastAPI ขนาดเล็กที่แสดงวิธีเข้าถึง ADK เป็นออบเจ็กต์ FastAPI get_fast_api_app() จาก ADK มีปลายทางในตัว ซึ่งรวมถึง /run_sse สำหรับ API การสตรีม SSE และการจัดการเซสชัน

Antigravity Files

• .agents/skills/adk-agent-development/SKILL.md - ทักษะที่กำหนดค่าไว้ล่วงหน้า ( สร้างโดย Antigravity) ซึ่งมีรูปแบบอ้างอิงแบบย่อจาก Codelab ทั้ง 4 รายการของ ADK ขณะนี้ไม่ได้ใช้งาน (ไม่มี Frontmatter ของ YAML) คุณจะต้องอัปเดตในภายหลัง Antigravity จะโหลดทักษะนี้โดยอัตโนมัติเมื่อตรวจพบงานที่เกี่ยวข้องกับฟีเจอร์เอเจนต์ ADK และตัวอย่างของฟีเจอร์ ซึ่งเป็นความรู้ที่ช่วยแนะนำ Antigravity เมื่อวางแผนฟีเจอร์การจองในภายหลัง
• .agents/skills/repo-research/SKILL.md — ทักษะที่สอน Antigravity เกี่ยวกับวิธีวิเคราะห์ที่เก็บข้อมูลแบบเพิ่มทีละรายการและสร้างเอกสารบริบทของโปรเจ็กต์ที่มีโครงสร้าง โดยจะใช้วิธีการ 4 เฟส ได้แก่ การสแกนพื้นผิว (เฉพาะโครงสร้างไดเรกทอรี) ไฟล์การกำหนดค่าและข้อมูลเมตา จุดแรกเข้าและโมเดลข้อมูล จากนั้นจึงเจาะลึกแบบกำหนดเป้าหมาย โดยแต่ละเฟสจะหยุดและเขียนผลการค้นพบก่อนที่จะไปยังเฟสถัดไป เช่นเดียวกับทักษะ ADK โดยจะไม่มีการใช้งานจนกว่าคุณจะเพิ่ม Frontmatter ของ YAML ในภายหลัง เมื่อเปิดใช้งานแล้ว ให้เรียกใช้เพื่อสร้าง .agents/rules/project-context.md ซึ่งเป็นเอกสารการเริ่มต้นใช้งานที่ครอบคลุมสถาปัตยกรรม การขึ้นต่อรันไทม์ พื้นผิว API และอภิธานศัพท์ของโดเมน

การพัฒนาที่อิงตามข้อกำหนด: ตั้งแต่การวางแผนในตัวของ Antigravity ไปจนถึง SDD ที่มีโครงสร้าง

ผู้ช่วยเขียนโค้ด AI ช่วยให้สร้างโค้ดจากพรอมต์ได้ง่ายๆ ความเสี่ยง: คุณอธิบายฟีเจอร์ในประโยคเดียว ผู้ช่วยเขียนโค้ดหลายร้อยบรรทัด และคุณยอมรับเพราะดูเหมือนจะถูกต้อง บางครั้งเราเรียกวิธีนี้ว่า "Vibe Coding" ซึ่งเป็นการเขียนโค้ดตามความรู้สึก โดยยอมรับหรือปฏิเสธเอาต์พุตตามความเหมาะสม เหมาะสำหรับต้นแบบและสคริปต์ที่ใช้แล้วทิ้ง ซึ่งจะทำให้เกิดปัญหาเมื่อโค้ดเบสเติบโตขึ้น เมื่อฟีเจอร์ต่างๆ มีการโต้ตอบกัน หรือเมื่อคุณกลับมาดูโค้ดในอีกหลายสัปดาห์ต่อมาและไม่สามารถสร้างเหตุผลที่ใช้ในการตัดสินใจขึ้นมาใหม่ได้

การพัฒนาที่ขับเคลื่อนด้วยข้อกำหนด (SDD) จะเพิ่มโครงสร้างให้กับลูปนี้ ก่อนที่จะสร้างโค้ด คุณต้องเขียนข้อกำหนดก่อนว่าฟีเจอร์นี้ทำอะไร ใครเป็นผู้ใช้ และเกณฑ์ความสำเร็จคืออะไร ผู้ช่วย AI จะทำงานตามข้อกำหนดดังกล่าว และคุณก็เช่นกันเมื่อตรวจสอบเอาต์พุตของ AI ข้อกำหนดจะกลายเป็นแหล่งข้อมูลที่เชื่อถือได้เพียงแหล่งเดียวสำหรับเจตนา หากโค้ดแตกต่างจากข้อกำหนด คุณจะเห็นในรีวิว หากข้อกำหนดมีการเปลี่ยนแปลง คุณจะต้องอัปเดตข้อกำหนดก่อน แล้วจึงสร้างใหม่ การตัดสินใจจะได้รับการบันทึกไว้ ไม่ใช่การตัดสินใจแบบฉุกเฉิน

การแลกเปลี่ยนนี้เกิดขึ้นจริง โดย SDD จะช้ากว่าการเขียนโค้ดแบบไวบ์ต่อฟีเจอร์ คุณเขียนเอกสารก่อนเขียนโค้ด แต่ผลตอบแทนจะเพิ่มขึ้นเรื่อยๆ การเปลี่ยนแปลงในอนาคตทุกครั้งในโค้ดเบสจะมีบริบท การติดตั้งใช้งานที่ AI สร้างขึ้นทุกครั้งจะมีสัญญาที่ตรวจสอบได้ และคุณสามารถเริ่มต้นใช้งานร่วมกับผู้ทำงานร่วมกัน (มนุษย์หรือ AI) ได้โดยชี้ให้ดูข้อกำหนดแทนที่จะอธิบายการตัดสินใจจากความทรงจำ

Antigravity ทำตามหลักการพัฒนาที่อิงตามข้อกำหนดอยู่แล้ว เมื่อตั้งค่า Agent เป็นโหมดการวางแผน Agent จะสร้างอาร์ติแฟกต์ 2 รายการก่อนที่จะเขียนโค้ด

• แผนการติดตั้งใช้งาน - ภาพรวมของแนวทางเทคนิคที่เสนอ การเปลี่ยนแปลงไฟล์ และการตัดสินใจด้านสถาปัตยกรรม
• รายการงาน - รายการย่อยที่มีโครงสร้างของรายการงาน

Antigravity ขอให้คุณตรวจสอบและอนุมัติอาร์ติแฟกต์เหล่านี้ก่อนดำเนินการ วงจรการวางแผนแล้วจึงนำไปใช้เป็นหัวใจสำคัญของการพัฒนาที่ขับเคลื่อนด้วยข้อกำหนด เนื่องจากข้อกำหนดเป็นตัวนำทางโค้ด ไม่ใช่ในทางกลับกัน

Codelab นี้จะต่อยอดจากพื้นฐานดังกล่าวด้วยเวิร์กโฟลว์ที่มีข้อจำกัดและมีการควบคุมเวอร์ชันโดยอิงตาม spec-kit ซึ่งเป็นเฟรมเวิร์กการพัฒนาที่อิงตามข้อกำหนดจาก GitHub ฟีเจอร์ทุกรายการจะผ่านไปป์ไลน์ที่ตั้งใจไว้ ซึ่งแต่ละอาร์ติแฟกต์จะเป็นเอกสารแบบสแตนด์อโลนที่คุณสามารถตรวจสอบ แก้ไข และติดตามใน git ได้ ไปป์ไลน์มี 2 เฟสที่เป็นตัวเลือกในการตรวจสอบคุณภาพ (ชี้แจงและวิเคราะห์) ซึ่งจะตรวจพบปัญหาได้ก่อนที่จะกลายเป็นปัญหาในการใช้งาน

ระยะ	อาร์ติแฟกต์	Purpose
/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 และนำกลับมาใช้ใหม่ได้ หากการสนทนาถูกขัดจังหวะหรือคุณต้องการกลับมาดูการตัดสินใจในภายหลัง เอกสารข้อกำหนดจะพร้อมให้คุณดูเสมอ ไม่ได้ซ่อนอยู่ในประวัติการแชท

หมายเหตุ: อาร์ติแฟกต์ในตัวของ Antigravity มีความเหนือกว่าใน UI ซึ่งช่วยให้ผู้ใช้แสดงความคิดเห็นเกี่ยวกับอาร์ติแฟกต์ที่สร้างขึ้นได้ ( แม้แต่รูปภาพ!) ) ดังนั้นในบทแนะนำนี้ เราจะแก้ไขพรอมต์ spec-kit เดิมเพื่อผสานรวมกับอาร์ติแฟกต์ในตัวในimplementเฟส

ที่เก็บเริ่มต้นมีเวิร์กโฟลว์ SDD เหล่านี้ใน .agents/workflows/ และเทมเพลตใน .specify/templates/ คุณจะใช้ฟังก์ชันเหล่านี้ในภายหลังเพื่อเพิ่มฟีเจอร์ให้กับเอเจนต์

4. ตั้งค่า Cloud SQL ให้เสร็จสมบูรณ์และตรวจสอบว่า Base Agent ทำงานได้

สลับกลับไปที่แท็บเทอร์มินัลที่คำสั่งสร้าง Cloud SQL กำลังทำงานอยู่ เมื่อเสร็จแล้ว ให้ยืนยันว่าอินสแตนซ์พร้อมใช้งานโดยทำดังนี้

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

หากเอาต์พุตแสดง RUNNABLE ให้ดำเนินการต่อ หากแสดง PENDING_CREATE ให้รอสักครู่แล้วเรียกใช้คำสั่งอีกครั้ง

ให้สิทธิ์เข้าถึง Vertex AI แก่บัญชีบริการ Cloud SQL (จำเป็นสำหรับฟังก์ชันการฝังในฐานข้อมูล)

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 อินสแตนซ์ Cloud SQL restaurant-db ทำงานอยู่ toolbox พร้อมใช้งานใน PATH (ติดตั้งโดย setup_prerequisites.sh) และติดตั้งการขึ้นต่อกันของ Python แล้ว

เริ่มต้นฐานข้อมูล

โหลดตัวแปรสภาพแวดล้อมและเรียกใช้สคริปต์การเริ่มต้นฐานข้อมูลเพื่อสร้างสคีมาและแทรกรายการเมนู 16 รายการ

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.

ซึ่งใช้ฟังก์ชัน embedding() ในตัวของ Cloud SQL (ผ่านส่วนขยาย google_ml_integration) เพื่อเรียกใช้ gemini-embedding-001 โดยตรงจาก SQL ระบบจะจัดเก็บเวกเตอร์ 3072 มิติในคอลัมน์ embedding ของ menu_items โดยไม่จำเป็นต้องใช้โค้ดฝังในฝั่งแอปพลิเคชัน

ทดสอบ Agent พื้นฐาน

เริ่มกล่องเครื่องมือ 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

เปิด UI สำหรับนักพัฒนาแอป ADK โดยทำดังนี้

uv run adk web .

เปิด UI สำหรับนักพัฒนาซอฟต์แวร์ในเบราว์เซอร์ จากนั้นทดสอบเอเจนต์ด้วยพรอมต์ต่อไปนี้

What appetizers do you have?

ตรวจสอบ: เอเจนต์จะค้นหาฐานข้อมูลและแสดงผลรายการในเมนู

I'm vegetarian

ตรวจสอบ: ตัวแทนจะบันทึกค่ากำหนดด้านอาหารไว้ในสถานะของตัวแทน

Can I make a reservation for tomorrow?

ตรวจสอบ: ตัวแทนไม่สามารถจัดการเรื่องนี้ได้ (ยังไม่มีเครื่องมือการจอง)

หยุด UI สำหรับนักพัฒนาแอป ADK โดยกด Ctrl+C 2 ครั้ง ปล่อยให้กล่องเครื่องมือทำงานในเบื้องหลัง คุณจะได้ใช้กล่องเครื่องมืออีกครั้งในภายหลัง

จุดตรวจสอบ: เอเจนต์พื้นฐานทํางานได้ดี การค้นหาเมนู (คีย์เวิร์ด + ความหมาย) และฟังก์ชันค่ากำหนดด้านอาหารทํางานได้อย่างถูกต้อง คำขอจองไม่สำเร็จเนื่องจากไม่มีเครื่องมือการจอง คุณเข้าใจโครงสร้างโปรเจ็กต์และช่องว่างที่คุณกำลังจะเติมเต็ม

5. Bootstrap Project Context ด้วย Antigravity

ตอนนี้มาจำลองสถานการณ์ด้วยเงื่อนไขที่ "ค่อนข้างใกล้เคียง" กับงานประจำของเรากัน

• ที่เก็บที่มีการจัดการไม่ดี
• README ล้าสมัย
• เอกสารประกอบที่ไม่ได้อัปเดตบ่อย

หมายเหตุ: คุณโชคดีมากหากการแจ้งเตือนนี้ไม่ตรงกับอาการของคุณ

สิ่งแรกที่เรามักจะทำในสถานการณ์เช่นนี้คือการสร้างแผนที่หรือบริบทเกี่ยวกับโปรเจ็กต์ที่เราต้องการให้ Antigravity ทำ ขั้นตอนนี้แสดงตัวอย่างแนวทางในการช่วยให้ Antigravity เข้าใจโค้ดเบสที่มีอยู่ได้อย่างลึกซึ้งโดยการสร้างทักษะที่วิเคราะห์ที่เก็บและสร้างเอกสารบริบทของโปรเจ็กต์

นอกจากนี้ยังกำหนดธรรมนูญของโปรเจ็กต์ ซึ่งเป็นหลักการที่ต่อรองไม่ได้ซึ่งเวิร์กโฟลว์ SDD จะตรวจสอบ ซึ่งจะช่วยให้ Antigravity มีบริบทและข้อจำกัดที่จำเป็นสำหรับรอบ SDD ในภายหลัง

ลำดับชั้นบริบทของ Antigravity

Antigravity ใช้บริบท 3 ระดับ โดยแต่ละระดับมีขอบเขตที่แตกต่างกัน ดังนี้

• กฎ (.agents/rules/): คำสั่งที่ใช้งานได้เสมอ ทุกการสนทนาในพื้นที่ทำงานนี้จะเห็นกฎ ( หากคุณเปิดใช้งาน) ใช้กฎสำหรับบริบททั่วทั้งโปรเจ็กต์ เช่น การตัดสินใจด้านสถาปัตยกรรม มาตรฐานการเขียนโค้ด หรือข้อมูลสแต็กเทคโนโลยี
• ทักษะ (.agents/skills/): ความรู้แบบออนดีมานด์ Antigravity จะโหลดทักษะเมื่องานปัจจุบันตรงกับฟิลด์ description ของทักษะเท่านั้น ใช้ทักษะสำหรับเอกสารอ้างอิงเฉพาะโดเมน
• เวิร์กโฟลว์ (.agents/workflows/): พรอมต์ที่บันทึกไว้ซึ่งทริกเกอร์ด้วยคำสั่ง / ใช้เวิร์กโฟลว์สำหรับกระบวนการแบบหลายขั้นตอนที่ทำซ้ำได้ เช่น ไปป์ไลน์ SDD

หมายเหตุ: ปัจจุบันโปรเจ็กต์มีเวิร์กโฟลว์ (ไปป์ไลน์ SDD) และทักษะ (การพัฒนาเอเจนต์ ADK) แต่ไม่มีกฎ กฎ project-context.md ช่วยให้ Antigravity เข้าใจโค้ดเบสได้อย่างต่อเนื่อง ไม่ว่าจะเป็นเทคโนโลยีที่ใช้ วิธีการจัดระเบียบไฟล์ และสิ่งที่สร้างขึ้นจนถึงตอนนี้

เปิดใช้งานสกิล

ที่เก็บเริ่มต้นมีสกิลที่เขียนไว้ล่วงหน้า 2 รายการใน .agents/skills/ โดยจะมีวิธีการโดยละเอียด แต่จะเริ่มต้นด้วยTODO(codelab)ความคิดเห็นแทนที่จะเป็น Frontmatter ของ YAML ที่จำเป็น หากไม่มี Frontmatter Antigravity จะค้นหาไม่ได้

ทักษะการต้านแรงโน้มถ่วงต้องมีบล็อกส่วนหน้า YAML ที่ด้านบนของไฟล์ที่มี 2 ฟิลด์ดังนี้

• name — ตัวระบุที่ไม่ซ้ำกันสำหรับทักษะ
• description - ข้อมูลสรุปภาษาธรรมชาติที่ Antigravity จะจับคู่เมื่อตัดสินใจว่าจะโหลดทักษะใดสำหรับคำขอที่ระบุ

เปิด

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

ในเครื่องมือแก้ไข แทนที่บรรทัดความคิดเห็น 2 บรรทัดที่ด้านบนด้วย Frontmatter นี้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 มีรูปแบบและตัวอย่างที่ย่อมาจาก Codelab ของ ADK 5 รายการ ได้แก่ โครงสร้างเอเจนต์ ประเภทเครื่องมือ การจัดการสถานะ การติดตั้งใช้งาน

เปิด

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

ในเครื่องมือแก้ไข แทนที่บรรทัดความคิดเห็น 2 บรรทัดที่ด้านบนด้วย Frontmatter นี้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 โดยละเอียด นี่คือตัวอย่างพรอมต์เพื่อวิเคราะห์ที่เก็บ โปรดทราบว่ากฎการอัปเดตแบบเพิ่มทีละรายการนั้นตั้งใจให้เป็นแบบอนุรักษ์นิยม หากบริบทของ Antigravity หมดลงกลางการค้นคว้าหรือการสนทนาถูกขัดจังหวะ ระบบจะบันทึกทุกอย่างที่ค้นพบจนถึงตอนนี้ลงในไฟล์ การเรียกใช้ทักษะอีกครั้งจะทำให้คุณกลับไปทำต่อจากจุดที่ค้างไว้ได้โดยไม่ต้องเริ่มใหม่

คำเตือน การวิเคราะห์ที่เก็บขนาดใหญ่อาจทำให้โควต้าหมดอย่างรวดเร็ว

ตรวจสอบว่าทักษะทั้ง 2 มี Frontmatter ที่ถูกต้อง

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

แต่ละรายการควรแสดงตัวคั่น --- ที่ครอบฟิลด์ name: และ description: หากไม่มีตัวคั่นหรือฟิลด์ Antigravity จะไม่รู้จักทักษะ

โดยระบบจะโหลดทั้ง 2 ทักษะตามความต้องการ ซึ่ง Antigravity จะจับคู่คำขอของคุณกับฟิลด์ description และดึงวิธีการทั้งหมดเมื่อเกี่ยวข้องเท่านั้น

สร้างบริบทของโปรเจ็กต์

ตรวจสอบว่ามีไดเรกทอรีของกฎอยู่

mkdir -p .agents/rules

ในกล่อง Agent Manager/Chat ของ Antigravity (ในโหมดเอดิเตอร์ ให้กด ctrl + L) ให้เริ่มการสนทนาใหม่ ประเภท:

Research this repository and create a project context document

Antigravity จะจับคู่คำขอของคุณกับทักษะ repo-research และเริ่มวิเคราะห์โค้ดเบสอย่างเป็นระบบ โดยจะอ่านไฟล์การกำหนดค่า ซอร์สโค้ด และเอกสารประกอบ จากนั้นจะป้อนข้อมูลลงในเทมเพลตบริบทของโปรเจ็กต์ด้วยสิ่งที่พบ

เมื่อเสร็จแล้ว ให้เปิด .agents/rules/project-context.md ในตัวแก้ไข โดยมีข้อมูลที่ชัดเจนเกี่ยวกับโปรเจ็กต์ ได้แก่ เทคโนโลยีสแต็ก (Python 3.12, ADK, MCP Toolbox, Cloud SQL), โครงสร้างโปรเจ็กต์, โมเดลข้อมูล (ตาราง menu_items ที่มี pgvector) และการผสานรวมภายนอก

เคล็ดลับ: เอกสารบริบทของโปรเจ็กต์จะขยายขึ้นเมื่อโปรเจ็กต์มีการพัฒนา คุณเรียกใช้ทักษะอีกครั้งเพื่ออัปเดตบริบทด้วยข้อมูลใหม่ที่เพิ่มเข้ามาได้ กฎการอัปเดตแบบเพิ่มจะช่วยให้มั่นใจได้ว่าเนื้อหาที่มีอยู่จะยังคงอยู่ โดยจะมีการเพิ่มเทคโนโลยี เอนทิตี และการผสานรวมใหม่ๆ ไม่ใช่การเขียนทับ

สำหรับการอัปเดตที่เจาะจง ให้ใช้พรอมต์ที่เฉพาะเจาะจง เช่น "ค้นคว้าสคีมาฐานข้อมูลและอัปเดตบริบทของโปรเจ็กต์" หรือ "อัปเดตบริบทของโปรเจ็กต์ด้วยคำจำกัดความเครื่องมือใหม่" การเรียกใช้แต่ละครั้งจะเพิ่มข้อมูลลงในเอกสารที่มีอยู่

กำหนดธรรมนูญของโปรเจ็กต์

เวิร์กโฟลว์ SDD อ้างอิงถึงธรรมนูญของโปรเจ็กต์ที่ .specify/memory/constitution.md ระหว่างการวางแผนและการวิเคราะห์ /speckit.plan เวิร์กโฟลว์จะเรียกใช้ "การตรวจสอบรัฐธรรมนูญ" กับข้อความดังกล่าว และ/speckit.analyze จะแจ้งว่ามีการละเมิดเป็น "วิกฤต" หากปล่อยให้รัฐธรรมนูญเป็นเทมเพลตเปล่าที่มีโทเค็นตัวยึดตำแหน่ง การตรวจสอบเหล่านี้จะไม่มีอะไรให้ตรวจสอบ แผนและการวิเคราะห์จะทำงานโดยไม่มีขอบเขต

รัฐธรรมนูญกำหนดหลักการของโปรเจ็กต์ที่ต่อรองไม่ได้ ที่เก็บนี้เป็นที่เก็บขนาดเล็กที่ดูแลโดยนักพัฒนาซอฟต์แวร์เพียงคนเดียว ดังนั้นรัฐธรรมนูญควรสะท้อนถึงขอบเขตดังกล่าว นั่นคือทำให้เรียบง่าย สอดคล้องกัน และหลีกเลี่ยงการออกแบบที่ซับซ้อนเกินไป

ใน Agent Manager ของ Antigravity ให้เริ่มการสนทนาใหม่ เรียกใช้เวิร์กโฟลว์รัฐธรรมนูญ

/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.

Antigravity จะกรอกเทมเพลตรัฐธรรมนูญด้วยหลักการที่เป็นรูปธรรม กำหนดเวอร์ชัน (1.0.0) และเรียกใช้การตรวจสอบความสอดคล้องในเทมเพลต SDD

ตรวจสอบรัฐธรรมนูญที่สร้างขึ้นที่ .specify/memory/constitution.md ตรวจสอบว่ามีหลักการทั้ง 3 ข้อและระบุไว้อย่างชัดเจน

หมายเหตุ: เราตั้งใจให้รัฐธรรมนูญมีหลักการ 3 ข้อที่กำหนดขอบเขตสำหรับนักพัฒนาแอปเดี่ยว /speckit.constitution เวิร์กโฟลว์รองรับการแก้ไขแบบเพิ่มทีละรายการ เพียงเรียกใช้อีกครั้งโดยใช้หลักการเพิ่มเติม แล้วระบบจะจัดการการควบคุมเวอร์ชันโดยอัตโนมัติ สำหรับโปรเจ็กต์ของทีม คุณจะต้องเพิ่มหลักการสำหรับการตรวจสอบโค้ด วินัยในการทดสอบ การสังเกตการณ์ และการควบคุมเวอร์ชัน API

จุดตรวจสอบ: .agents/rules/project-context.md มีข้อมูลที่ชัดเจนเกี่ยวกับที่เก็บ .agents/skills/repo-research/SKILL.md แสดงการสร้างทักษะด้วยส่วนหน้าของ YAML, คำสั่ง และการแก้ไขข้อขัดแย้ง .specify/memory/constitution.md มีหลักการของโปรเจ็กต์ 3 ข้อที่เวิร์กโฟลว์การวางแผนและการวิเคราะห์จะตรวจสอบ คุณเข้าใจลำดับชั้นของบริบท 3 ระดับ ได้แก่ กฎ (ใช้งานอยู่เสมอ) ทักษะ (ตามความต้องการ) เวิร์กโฟลว์ (คำสั่ง Slash)

6. วงจร SDD - เพิ่มฟีเจอร์การจอง

ขั้นตอนนี้จะอธิบายวงจร SDD ทั้งหมดเพื่อเพิ่มการจองห้องพักไปยังตัวแทนอำนวยความสะดวกของร้านอาหาร คุณจะขับเคลื่อน Antigravity ผ่านแต่ละเฟส ได้แก่ ระบุ ชี้แจง วางแผน งาน วิเคราะห์ และนำไปใช้ โดยสังเกตว่าอาร์ติแฟกต์แต่ละรายการสร้างขึ้นจากอาร์ติแฟกต์ก่อนหน้าอย่างไร ซึ่งเป็นประสบการณ์การเรียนรู้หลักของ Codelab

สำคัญ Antigravity เป็นผู้ช่วย AI ซึ่งอาร์ติแฟกต์ที่สร้างขึ้น (ข้อกำหนด แผน งาน โค้ด) อาจแตกต่างจากที่บทแนะนำนี้อธิบาย ชื่อไฟล์ สคีมา SQL ที่แน่นอน และโครงสร้างโค้ดอาจแตกต่างกัน ซึ่งเป็นเรื่องปกติและเป็นส่วนหนึ่งของการทำงานร่วมกับการพัฒนาที่ AI ช่วย เวิร์กโฟลว์ SDD ช่วยให้คุณตรวจสอบอาร์ติแฟกต์ทุกรายการก่อนที่จะกลายเป็นโค้ด ดังนั้นโปรดใช้ดุลยพินิจในการยอมรับ แก้ไข หรือสร้างเอาต์พุตใหม่หากไม่ตรงกับความคาดหวัง

ระบุฟีเจอร์

ใน Agent Manager ของ Antigravity ให้เริ่มการสนทนาใหม่ พิมพ์/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").

Antigravity สร้างกิ่งก้านฟีเจอร์ สร้างเอกสารข้อกำหนด และเรียกใช้การตรวจสอบคุณภาพ หาก Antigravity ถามคำถามเพื่อขอคำชี้แจง ให้ตอบคำถามตามคำอธิบายฟีเจอร์ด้านบน

หมายเหตุ: หลังจากระบุรายละเอียดเสร็จแล้ว Antigravity อาจแสดงการส่งต่อ เช่น "สร้างแผนทางเทคนิค" หรือ "ชี้แจงข้อกำหนดของข้อกำหนด" ซึ่งเป็นคิวสำหรับเวิร์กโฟลว์เฟสถัดไป (/speckit.plan หรือ /speckit.clarify)

ข้อกำหนดจะเน้นที่ "อะไร" และ "ทำไม" ไม่ใช่ "อย่างไร" โดยอธิบายประสบการณ์ของผู้ใช้ ("แขกสามารถจองได้โดยระบุชื่อ จำนวนคน วันที่ และเวลา") โดยไม่ต้องพูดถึงตาราง SQL, tools.yaml หรือ API ของ ADK รายละเอียดการใช้งานจะอยู่ในระยะการวางแผน

ตรวจสอบข้อกำหนดที่สร้างขึ้นที่ specs/<branch-name>/spec.md ตรวจสอบว่าข้อกำหนดดังกล่าวครอบคลุมข้อกำหนดด้านฟังก์ชันการทำงานและเกณฑ์ความสำเร็จ

ชี้แจงข้อกำหนด (ไม่บังคับ)

เรียกใช้เวิร์กโฟลว์การชี้แจงเพื่อระบุและแก้ไขพื้นที่ที่ระบุไม่ชัดเจนในข้อกำหนด

/speckit.clarify

Antigravity จะสแกนข้อกำหนดเพื่อหาความคลุมเครือ เกณฑ์การยอมรับที่ขาดหายไป และข้อกำหนดที่ระบุไม่ครบ โดยจะถามคำถามที่มุ่งเน้นการชี้แจง ซึ่งแต่ละคำตอบจะตอบได้ด้วยการเลือกหรือวลีสั้นๆ ระบบจะเข้ารหัสคำตอบของคุณกลับไปในข้อกำหนดโดยตรง ซึ่งจะช่วยให้ข้อกำหนดมีความแม่นยำมากขึ้นก่อนที่จะเริ่มวางแผน

เคล็ดลับ: ขั้นตอนการชี้แจงไม่บังคับ แต่เราขอแนะนำให้ใช้กับฟีเจอร์ที่ซับซ้อน สำหรับสเปคที่ไม่ซับซ้อน ให้ข้ามไปที่การวางแผนโดยตรง

วางแผนการติดตั้งใช้งาน

เรียกใช้เวิร์กโฟลว์การวางแผน

/speckit.plan

Antigravity สร้างแผนทางเทคนิคผ่าน 2 เฟส ดังนี้

1. ระยะการวิจัย - แก้ไขสิ่งที่ยังไม่ทราบเกี่ยวกับโค้ดเบสที่มีอยู่ สร้าง research.md
2. ช่วงออกแบบ - สร้าง data-model.md (คำจำกัดความของเอนทิตีการจอง) และอัปเดต project-context.md

Antigravity ควรใช้ทักษะ adk-agent-development ในระหว่างการวางแผน ตรวจสอบอาร์ติแฟกต์ที่สำคัญ

• specs/<branch-name>/plan.md - แนวทางด้านเทคนิค: ไฟล์ที่จะแก้ไข รูปแบบที่ต้องทำตาม
• specs/<branch-name>/data-model.md — คำจำกัดความของเอนทิตีการจอง (คอลัมน์ ประเภท ความสัมพันธ์)
• specs/<branch-name>/research.md — การตัดสินใจและเหตุผล

สร้างงาน

เรียกใช้เวิร์กโฟลว์ของงาน

/speckit.tasks

Antigravity จะแบ่งแผนออกเป็นรายการงานที่เรียงตามลำดับใน 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

Antigravity จะตรวจสอบรายการงานกับข้อกำหนดและแผน โดยมองหางานที่อาจขัดแย้งกัน หรือช่องว่างระหว่างข้อกำหนดของข้อกำหนดกับงานที่วางแผนไว้ แก้ไขปัญหาร้ายแรงก่อนที่จะนำไปใช้

เคล็ดลับ: ขั้นตอนการวิเคราะห์จะมีประโยชน์มากที่สุดเมื่อรายการงานยาวหรือฟีเจอร์เกี่ยวข้องกับระบบย่อยหลายระบบ สำหรับฟีเจอร์ที่เฉพาะเจาะจง เช่น การจอง การสแกนอย่างรวดเร็วก็เพียงพอแล้ว

7. ใช้งาน

เรียกใช้เวิร์กโฟลว์การติดตั้งใช้งาน

/speckit.implement

Antigravity จะนำเสนอแผนการติดตั้งใช้งานขั้นสุดท้ายและอาร์ติแฟกต์ของงาน ตรวจสอบและอนุมัติเพื่อดำเนินการต่อ

เคล็ดลับ: คุณแสดงความคิดเห็นในวิดีโอได้โดยตรง การดำเนินการนี้จะทำได้ด้วยอาร์ติแฟกต์ Antigravity ในตัวเท่านั้น

Antigravity จะดำเนินการตามงานและทำเครื่องหมายแต่ละงานเมื่อเสร็จสิ้น เมื่อเสร็จแล้ว ระบบจะแสดงคำแนะนำแบบทีละขั้นที่สมบูรณ์

ทดสอบการเปลี่ยนแปลงโค้ด

หลังจากติดตั้งใช้งานเสร็จแล้ว ให้ยืนยันว่ามีการเปลี่ยนแปลงคีย์ ชื่อไฟล์และเนื้อหาที่แน่นอนอาจแตกต่างกันไป แต่ควรมีรูปแบบเหล่านี้เหมือนใน 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ข้อมูลที่มีอยู่จะยังคงอยู่)

หมายเหตุ: Antigravity อาจสร้างสคริปต์การย้ายข้อมูลแยกต่างหาก (เช่น scripts/create_reservations.py) แทนการอัปเดต seed_db.py ตรวจสอบ git diff --name-only เพื่อดูสคริปต์ใหม่ใน scripts/ แล้วเรียกใช้สคริปต์เหล่านั้นแทน

หากทุกอย่างเป็นไปด้วยดีจนถึงตอนนี้ เราจะทดสอบฟีเจอร์ใน UI สำหรับนักพัฒนาซอฟต์แวร์ของตัวแทน ADK ได้ รีสตาร์ทกล่องเครื่องมือเพื่อรับคำจำกัดความของเครื่องมือใหม่ใน tools.yaml หยุดกระบวนการ Toolbox ที่มีอยู่ แล้วเริ่มกระบวนการใหม่โดยทำดังนี้

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

เปิด UI สำหรับนักพัฒนาแอป ADK โดยทำดังนี้

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?

ตรวจสอบ: เอเจนต์ควรแสดงรายการการจองที่คุณเพิ่งทำ

ตอนนี้ให้หยุด UI สำหรับนักพัฒนาแอป ADK โดยกด Ctrl+C 2 ครั้ง

จุดตรวจสอบ: เอเจนต์จัดการการจองและการค้นหาการจอง คุณได้ทำวงจร SDD ทั้งหมดแล้ว ได้แก่ ระบุ → ชี้แจง → วางแผน → งาน → วิเคราะห์ → นำไปใช้ → ทดสอบ แต่ละเฟสจะสร้างอาร์ติแฟกต์ที่กำหนดเวอร์ชันไว้ใน specs/<branch-name>/

8. ชาเลนจ์ (ไม่บังคับ)

ตอนนี้คุณก็ทราบเวิร์กโฟลว์ SDD ทั้งหมดแล้ว ลองทดสอบดู

• เรียกใช้รอบ SDD ที่ 2 เพื่อสร้างอินเทอร์เฟซแชทบนเว็บสำหรับเจ้าหน้าที่อำนวยความสะดวกของร้านอาหาร โดยครั้งนี้ไม่ต้องมีคำแนะนำแบบทีละขั้นตอน
• ทำให้เอเจนต์ใช้งานได้กับ Cloud Run สำหรับสถานการณ์การใช้งานจริง

คำแนะนำ

• โปรเจ็กต์ไม่มีเฟรมเวิร์กส่วนหน้า Antigravity ควรเสนอ HTML/CSS/JS แบบดั้งเดิม หากแนะนำ React หรือคล้ายกัน ให้แนะนำให้ใช้แบบเรียบง่าย (หลักการ "ทำให้เรียบง่าย" ของรัฐธรรมนูญควรครอบคลุมเรื่องนี้)
• เซิร์ฟเวอร์ ADK จะแสดง /run_sse สำหรับการสตรีมและ /apps/{app_name}/users/{user_id}/sessions สำหรับการจัดการเซสชัน Antigravity จะค้นพบสิ่งเหล่านี้จากบริบทของโปรเจ็กต์
• หลังจากติดตั้งใช้งานแล้ว ให้เริ่มเซิร์ฟเวอร์ด้วย uv run uvicorn server:app --host 0.0.0.0 --port 8080 (ไม่ใช่ adk web) เพื่อให้การติดตั้งไฟล์แบบคงที่ทำงานได้
• ทดสอบที่ http://localhost:8080/static/index.html
• Codelab อ้างอิงแสดงวิธีติดตั้งใช้งานและคงเอเจนต์ ADK ไว้แล้ว โปรดอ้างอิง Antigravity ถึง Codelab นี้

9. ยินดีด้วย

คุณได้ขยายตัวแทน ADK ของเจ้าหน้าที่อำนวยความสะดวกในร้านอาหารด้วยการจองที่นั่งผ่านเวิร์กโฟลว์ SDD ของ Antigravity โดยไม่ต้องเขียนโค้ดแอปพลิเคชันด้วยตนเอง

สิ่งที่คุณสร้าง

• ตัวแทน ADK ของเจ้าหน้าที่อำนวยความสะดวกในร้านอาหารที่มีการค้นหาเมนู การค้นหาเชิงความหมาย การติดตามค่ากำหนดด้านอาหาร และการจอง
• ทักษะ Antigravity สำหรับการค้นคว้าข้อมูลในที่เก็บที่สร้างและดูแลเอกสารบริบทของโปรเจ็กต์
• ธรรมนูญของโปรเจ็กต์ที่บังคับใช้หลักการที่ต่อรองไม่ได้ในระหว่างการวางแผนและการวิเคราะห์
• วงจร SDD ที่สมบูรณ์ซึ่งแสดงเวิร์กโฟลว์ระบุ → ชี้แจง → วางแผน → งาน → วิเคราะห์ → นำไปใช้

สิ่งที่คุณได้เรียนรู้

• วิธีใช้เวิร์กโฟลว์การพัฒนาที่ขับเคลื่อนด้วยข้อกำหนดใน Antigravity เพื่อเพิ่มฟีเจอร์ลงในโค้ดเบสที่มีอยู่ได้อย่างเป็นระบบ
• วิธีสร้างทักษะ Antigravity ที่รวมความรู้เฉพาะด้านเพื่อนำไปใช้ซ้ำในการสนทนา
• วิธีเริ่มต้นบริบทของโปรเจ็กต์เพื่อให้ Antigravity ตัดสินใจอย่างมีข้อมูลเกี่ยวกับการเลือกสถาปัตยกรรม รูปแบบ และเทคโนโลยี
• วิธีตั้งค่าธรรมนูญของโปรเจ็กต์ที่เวิร์กโฟลว์ SDD ตรวจสอบ
• วิธีขยายเอเจนต์ ADK ด้วยเครื่องมือใหม่ที่ใช้ฐานข้อมูลผ่าน MCP Toolbox

ล้างข้อมูล

หยุดกระบวนการที่ทำงานในเครื่อง (กล่องเครื่องมือ):

pkill -f toolbox 2>/dev/null

ลบอินสแตนซ์ Cloud SQL เพื่อหลีกเลี่ยงการเรียกเก็บเงินอย่างต่อเนื่อง โดยทำดังนี้

gcloud sql instances delete restaurant-db --quiet

หากต้องการ คุณสามารถลบทั้งโปรเจ็กต์ได้โดยทำดังนี้

gcloud projects delete $GOOGLE_CLOUD_PROJECT

สำคัญ: คุณยกเลิกการลบนี้ได้ในระยะเวลาที่จำกัดโดยใช้คำสั่ง gcloud projects undelete ${GOOGLE_CLOUD_PROJECT}