Разработка агентов ADK на основе спецификаций с использованием Antigravity и Spec-kit

1. Введение

Добавление новых функций к существующему агенту — например, возможностей, основанных на базе данных — обычно означает написание шаблонного кода, настройку интеграций и поддержание согласованности всего с уже существующими шаблонами в кодовой базе. Antigravity ускоряет каждый этап этого процесса: он анализирует вашу кодовую базу для создания необходимого контекста, создает структурированные спецификации и планы реализации для вашего ознакомления и выполняет изменения кода — всё это под руководством знаний предметной области, которые он помогает вам зафиксировать в виде многократно используемых навыков, и структуры проекта, которая обеспечивает соблюдение незыблемых принципов. Этот практический семинар представляет способ значительно ускорить парадигму разработки, основанной на спецификациях (Spec-driven Development), с помощью нового цикла, который позволит улучшить документацию по спецификациям, активно используя spec-kit.

Что вы построите

Приложение для консьерж-обслуживания ресторанов, работающее локально и позволяющее бронировать столики в соответствии с полным циклом разработки программного обеспечения (SDD):

  • Бронирование столиков — гости бронируют столики и проверяют бронирование, используя новые инструменты базы данных MCP Toolbox и таблицу reservations Cloud SQL.
  • (Задание) – разработайте собственный пользовательский интерфейс для агента.
  • (Задание) – разверните приложение в Google Cloud с помощью агента Antigravity.

Стартовый код предоставляет работающий агент ADK с поиском по меню (по ключевому слову + семантика через MCP Toolbox) и отслеживанием пищевых предпочтений (через ToolContext). Вы можете расширять его без написания кода приложения вручную — Antigravity реализует его в соответствии с вашими требованиями.

404869b603fff6ab.png

Что вы узнаете

  • Как инициализировать контекст проекта, чтобы Antigravity понимал существующую кодовую базу?
  • Как создавать навыки Antigravity, которые позволяют упаковывать знания предметной области (например, шаблоны кодовой лаборатории ADK) для повторного использования.
  • Как определить структуру проекта, которой будут соответствовать рабочие процессы SDD на этапах планирования и анализа?
  • Как использовать рабочие процессы разработки, основанные на спецификации (Spec-Driven Development, SDD), в Antigravity для систематического добавления новых функций.
  • Как расширить функциональность агента ADK с помощью новых инструментов, работающих с базами данных, через MCP Toolbox.

Предварительные требования

2. Настройте свою среду.

На этом этапе выполняется клонирование стартового репозитория, аутентификация в Google Cloud, развертывание базы данных Cloud SQL и подготовка локальной среды Antigravity.

Клонируйте стартовый репозиторий

Откройте терминал в Antigravity (или в терминале вашей системы). Клонируйте репозиторий-спутник и перейдите в следующую директорию:

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

Откройте клонированный репозиторий в Antigravity. Файл -> Открыть папку -> выберите клонированную директорию sdd-adk-agents-agy

Удалите удаленный репозиторий из вышестоящего проекта. В рабочих процессах SDD создаются ветки Git для описания функций — удаление удаленного репозитория предотвращает случайную отправку изменений в стартовый репозиторий:

git remote remove origin

Установите необходимые компоненты.

Запустите скрипт проверки необходимых компонентов. Он проверит наличие (и установит, если отсутствует) git , curl , gcloud , uv , Python 3.12 и MCP Toolbox:

bash scripts/setup_prerequisites.sh

2aa671856eee1085.png

Аутентификация с помощью Google Cloud

Выполните две команды аутентификации. Обе откроют браузер для аутентификации OAuth:

gcloud auth login
gcloud auth application-default login

Поскольку вы работаете с Antigravity локально, аутентификация выполняется вручную. Команда auth login аутентифицирует CLI gcloud . application-default login аутентифицирует SDK Google Cloud, используемые вашим приложением — вызовы Vertex AI из ADK и коннектор Cloud SQL Python используют учетные данные по умолчанию для приложений.

Настройте свой проект в Google Cloud.

Перед запуском скрипта настройки проекта запишите переменные местоположения в файл .env :

echo "GOOGLE_CLOUD_LOCATION=global" > .env
echo "REGION=us-central1" >> .env
  • GOOGLE_CLOUD_LOCATION=global используется для вызовов API Vertex AI / Gemini.
  • 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

Provision Cloud SQL

Установите пароль к базе данных и добавьте его в .env :

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

Создайте экземпляр 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 — это минимальный уровень, необходимый для интеграции Vertex AI ML. Флаг --enable-google-ml-integration позволяет Cloud SQL вызывать модели встраивания Gemini непосредственно из SQL — это обеспечивает работу функции семантического поиска.

Установите зависимости

Откройте новую вкладку терминала. Убедитесь, что вы по-прежнему находитесь в каталоге клонированного репозитория проекта, и обновите переменные среды: 

source .env

В качестве менеджера проектов на Python мы будем использовать uv . uv — это быстрый пакет Python и менеджер проектов, написанный на Rust ( документация ). В этом практическом занятии он используется для повышения скорости и простоты. Установите зависимости 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. Изучите стартовый код и разберитесь в разработке, основанной на спецификациях (Spec-Driven Development).

На этом этапе рассматривается структура начального кода, знакомится с методологией разработки, основанной на спецификациях (Spec-Driven Development), выполняется инициализация базы данных и проверяется работоспособность базового агента перед его расширением.

Структура проекта

Откройте клонированный проект репозитория в редакторе 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 . Агент загружает все инструменты с сервера Toolbox и добавляет две функции Python ( save_dietary_preference , get_dietary_preferences ), которые используют ToolContext для управления состоянием.
  • tools.yaml — определения инструментов MCP Toolbox. Определены три инструмента поиска по меню: поиск по ключевым словам ( search_menu ), семантический поиск с помощью pgvector ( semantic_search_menu ) и фильтр по категориям ( get_menu_by_category ). Инструментов бронирования пока нет — вы добавите их позже.
  • server.py — Минимальный FastAPI-сервер, демонстрирующий, как можно получить доступ к ADK как к объекту FastAPI. get_fast_api_app() из ADK предоставляет встроенные конечные точки, включая /run_sse для потоковой передачи SSE и API управления сессиями.

Файлы об антигравитации

  • .agents/skills/adk-agent-development/SKILL.md — Предварительно настроенный навык (сгенерированный Antigravity), содержащий сжатые шаблоны ссылок из всех четырех учебных модулей ADK. В настоящее время он неактивен (отсутствует метаданные YAML) — вам потребуется обновить его позже. Antigravity автоматически загружает этот навык, когда обнаруживает работу, связанную с функциями агентов ADK и их примерами — именно эти знания помогают Antigravity при планировании функции бронирования в будущем.
  • .agents/skills/repo-research/SKILL.md — навык, обучающий Antigravity поэтапному анализу репозитория и созданию структурированного документа контекста проекта. Он использует 4-этапный подход: поверхностное сканирование (только дерево каталогов), файлы конфигурации и метаданных, точки входа и модели данных, а затем целенаправленный углубленный анализ — на каждом этапе происходит остановка и запись результатов перед переходом к следующему. Как и навык ADK, он неактивен, пока вы не добавите YAML-теги в начало файла. После активации запустите его, чтобы сгенерировать .agents/rules/project-context.md — всеобъемлющий документ для ознакомления, охватывающий архитектуру, зависимости времени выполнения, поверхность API и глоссарий предметной области.

Разработка, основанная на спецификациях: от встроенного в Antigravity планирования до структурированной разработки, основанной на спецификациях.

Искусственный интеллект, используемый в качестве помощника в программировании, упрощает генерацию кода по запросу. Риск: вы описываете функцию одним предложением, помощник пишет сотни строк, и вы принимаете это, потому что это выглядит правильно. Иногда это называют «программированием по ощущениям» — вы управляете процессом интуитивно, принимая или отклоняя результат в зависимости от того, кажется ли он работающим. Это быстро для прототипов и одноразовых скриптов. Но это дает сбой, когда кодовая база разрастается, когда функции взаимодействуют или когда вы возвращаетесь к коду через несколько недель и не можете вспомнить, почему было принято то или иное решение.

b2a0753229d08ef3.png

Разработка, основанная на спецификации (Spec-Driven Development, SDD), добавляет структуру в этот цикл. Прежде чем будет сгенерирован какой-либо код, вы пишете спецификацию: что делает функция, кому она предназначена, каковы критерии успеха. Искусственный интеллект работает на основе этой спецификации — и вы тоже, проверяя его результат. Спецификация становится единственным источником достоверной информации о намерениях. Если код отклоняется от спецификации, вы обнаруживаете это на этапе проверки. Если требования меняются, вы сначала обновляете спецификацию, а затем генерируете код заново. Решения документируются, а не импровизируются.

Компромисс реален: разработка через SDD медленнее на единицу функциональности, чем программирование через Vibe. Вы пишете документацию перед написанием кода. Но выгода накапливается — каждое будущее изменение в кодовой базе имеет контекст, каждая реализация, сгенерированная ИИ, имеет проверяемый контракт, и вы можете привлекать к сотрудничеству (людей или ИИ), указывая им на спецификации, вместо того чтобы объяснять решения по памяти.

Antigravity уже следует принципам разработки, основанной на спецификациях. Когда вы переводите агента в режим планирования , он создает два артефакта еще до написания какого-либо кода:

  • План реализации — обзор предлагаемого технического подхода, изменений в файлах и архитектурных решений. 632169a236bc62cc.png
  • Список задач — структурированное описание рабочих задач.

795e47f4d98ae074.png

Antigravity требует от вас проверки и утверждения этих артефактов перед выполнением. Этот цикл «планирование-затем-реализация» является ядром разработки, основанной на спецификациях: спецификации направляют код, а не наоборот.

Этот практический семинар развивает эту основу, используя продуманный , контролируемый версиями рабочий процесс на основе spec-kit — фреймворка для разработки, ориентированной на спецификации, от 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

Изменения в коде

Выполните задания, отмечая каждое из них.

c0164b540ee0afa1.png

Каждый артефакт сохраняется в виде файла в папке specs/<feature-branch>/ , контролируется системой версий Git и может быть использован повторно. Если обсуждение прерывается или вы хотите вернуться к принятым решениям позже, документы со спецификациями всегда будут доступны — они не будут скрыты в истории чата.

В стартовом репозитории эти рабочие процессы SDD находятся в .agents/workflows/ , а шаблоны — в папке .specify/templates/ . Вы будете использовать их позже для добавления функций в агент.

4. Завершите настройку Cloud SQL и убедитесь в работоспособности базового агента.

Вернитесь на вкладку терминала, где выполняется команда создания экземпляра Cloud SQL. После завершения убедитесь, что экземпляр готов: 

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

Если в выводе отображается RUNNABLE , продолжайте. Если отображается PENDING_CREATE , подождите немного и повторно выполните команду.

Предоставьте учетной записи службы Cloud 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>

Заполните базу данных

Загрузите переменные среды и запустите скрипт инициализации базы данных, чтобы создать схему и добавить 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.

В этом случае используется встроенная функция Cloud SQL embedding() (через расширение google_ml_integration ) для прямого вызова gemini-embedding-001 из SQL. 3072-мерные векторы хранятся в столбце embedding таблицы menu_items — код встраивания на стороне приложения не требуется.

Проверьте базовый агент

Запустите MCP Toolbox в фоновом режиме: 

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: 

uv run adk web .

Откройте пользовательский интерфейс для разработчиков в браузере. Затем протестируйте агента, следуя этим инструкциям: 

What appetizers do you have?

I'm vegetarian

Can I make a reservation for tomorrow?

fc693b9435b93493.png

Остановите пользовательский интерфейс разработчика ADK, дважды нажав Ctrl+C . Оставьте панель инструментов работать в фоновом режиме — она понадобится вам позже.

5. Контекст проекта Bootstrap с использованием Antigravity

Теперь давайте смоделируем ситуацию в условиях, которые «более или менее близки» к нашей повседневной работе:

  • Неэффективно управляемый репозиторий
  • README устарел
  • Документация обновляется нечасто.

В подобных ситуациях первым делом обычно создаётся карта или контекст проекта, с которым мы хотим, чтобы Antigravity работала. На этом этапе показан один из примеров подхода, позволяющего Antigravity глубоко понимать существующую кодовую базу путём создания навыка, который анализирует репозиторий и генерирует документ с контекстом проекта.

Это также закладывает основу для проекта — не подлежащие обсуждению принципы, которым соответствуют рабочие процессы SDD. В совокупности это дает Antigravity контекст и ограничения, необходимые для последующих циклов SDD.

Иерархия контекста антигравитации

В теории антигравитации используются три уровня контекста, каждый из которых имеет свой масштаб:

  • Правила ( .agents/rules/ ): Постоянно активные инструкции. Они видны в каждом диалоге в этом рабочем пространстве (если вы их активировали). Используйте правила для контекста всего проекта, например, для принятия архитектурных решений, соблюдения стандартов кодирования или получения информации о технологическом стеке.
  • Навыки ( .agents/skills/ ): Знания по запросу. Antigravity загружает навык только тогда, когда текущая задача соответствует полю description навыка. Используйте навыки для получения справочных материалов по конкретной предметной области.
  • Рабочие процессы ( .agents/workflows/ ): Сохраненные подсказки, запускаемые командами / . Используйте рабочие процессы для повторяющихся многоэтапных процессов, таких как конвейер SDD.

Активируйте навыки

В стартовом репозитории находятся два предварительно написанных навыка в папке .agents/skills/ . Они содержат подробные инструкции, но начинаются с комментариев TODO(codelab) вместо обязательного YAML-текста. Без текста в начале Antigravity не сможет их обнаружить.

Для использования навыков антигравитации требуется блок метаданных YAML в начале файла, содержащий два поля:

  • name — уникальный идентификатор навыка
  • description — краткое описание на естественном языке, с которым Antigravity сопоставляет информацию при принятии решения о том, какой навык загрузить для конкретного запроса.

Открыть

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

Открыть

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

Убедитесь, что оба навыка имеют корректную метатегу: 

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

В каждом поле должны быть разделители --- окружающие поля name: и description: :. Если разделители или поля отсутствуют, Antigravity не распознает навык.

Оба навыка загружаются по запросу — Antigravity сопоставляет ваш запрос с полем description и подтягивает полные инструкции только тогда, когда это необходимо.

Сгенерируйте контекст проекта.

Убедитесь, что каталог с правилами существует: 

mkdir -p .agents/rules

В окне «Менеджер агентов/Чат» игры 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 ) и внешние интеграции.

9949388b3e1f401a.png

Установить устав проекта

В процессе планирования и анализа рабочие процессы SDD используют структуру проекта, расположенную по адресу .specify/memory/constitution.md . Рабочий процесс /speckit.plan выполняет проверку структуры проекта, а /speckit.analyze помечает нарушения как КРИТИЧЕСКИЕ. Если структура проекта оставлена ​​в виде пустого шаблона с заполнителями, этим проверкам нечего будет сравнивать — планы и анализы выполняются без каких-либо ограничений.

В уставе определены не подлежащие обсуждению принципы проекта. Это небольшой репозиторий, поддерживаемый одним разработчиком, поэтому устав должен отражать его масштаб — всё должно быть просто, последовательно и избегать излишнего усложнения.

В менеджере агентов 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 . Убедитесь, что три принципа присутствуют и четко сформулированы.

276113749cd30834.png

6. Цикл SDD — Добавление функции резервирования

На этом этапе описывается полный цикл разработки программного обеспечения (SDD) для добавления функции бронирования столиков в ресторан. Вы управляете Antigravity на каждом этапе — уточнение, планирование, задачи, анализ, реализация — наблюдая, как каждый результат основывается на предыдущем. Это основной учебный процесс в рамках практического занятия.

Укажите характеристику

В менеджере агентов 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 задает уточняющие вопросы, отвечайте на них, основываясь на описании функции, приведенном выше.

Спецификация фокусируется на ЧТО и ПОЧЕМУ, а не НА КАК. Она описывает пользовательский опыт («Гости могут забронировать номер, указав свое имя, количество человек в группе, дату и время») без упоминания таблиц SQL, tools.yaml или API ADK. Детали реализации будут рассмотрены на этапе планирования.

Просмотрите сгенерированную спецификацию по адресу specs/<branch-name>/spec.md . Убедитесь, что она отражает функциональные требования и критерии успеха.

4ea3f72f9dfb4d35.png

Уточните спецификацию (необязательно)

Запустите рабочий процесс уточнения, чтобы выявить и устранить недостаточно определенные области в спецификации: 

/speckit.clarify

Система Antigravity сканирует спецификацию на наличие неоднозначностей, отсутствующих критериев приемки и недостаточно определенных требований. Она задает целенаправленные уточняющие вопросы, на каждый из которых можно ответить коротким предложением или фразой. Ваши ответы напрямую встраиваются в спецификацию, что делает ее более точной до начала планирования.

Спланируйте реализацию

Запустите процесс планирования: 

/speckit.plan

Разработка технического плана для проекта «Антигравитация» осуществляется в два этапа:

  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 — принятые решения и обоснование

d9996ccbb3211078.png

Сгенерировать задачи

Запустите рабочий процесс задач. 

/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

Задачи организованы по этапам: Настройка → Основы → Пользовательские истории → Доработка. Просмотрите список задач, чтобы понять, что будет создано и изменено.

9fcdb822d8279ddf.png

Анализ задач (необязательно)

Запустите рабочий процесс анализа, чтобы проверить задачи на наличие рисков и пробелов: 

/speckit.analyze

Antigravity проверяет список задач на соответствие спецификации и плану, выявляя недостающие граничные случаи, задачи, которые могут конфликтовать, или несоответствия между требованиями спецификации и запланированной работой. Устраните критические проблемы до начала реализации.

7. Внедрить

Запустите рабочий процесс внедрения: 

/speckit.implement

Компания Antigravity представляет окончательный план реализации и документ с описанием задачи. Рассмотрите и утвердите его для продолжения работы.

adc1e3d098bd1638.png

306448e70f61ab51.png

Antigravity выполняет задания, отмечая каждое выполненное. После завершения отобразится полное пошаговое руководство.

48cc7752817a54c7.png

Проверьте изменения в коде.

После завершения внедрения убедитесь, что внесены все ключевые изменения. Точные имена файлов и их содержимое могут отличаться, но должны присутствовать следующие шаблоны, как в 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,
...

Изменения должны затронуть скрипт базы данных начальных данных, давайте попробуем его выполнить. 

source .env
uv run python scripts/seed_db.py

Обновленный скрипт должен создать таблицу reservations , если она еще не существует. Вы должны увидеть сообщение, подтверждающее создание новой таблицы (существующие данные menu_items сохраняются).

Если до этого момента все пройдет успешно, мы можем протестировать функцию в пользовательском интерфейсе разработчика агента ADK. Перезапустите Toolbox, чтобы применить новые определения инструментов из tools.yaml . Остановите любой существующий процесс Toolbox, а затем запустите новый: 

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

Запустите пользовательский интерфейс разработчика 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?

d9815389df37ed1a.png

f38a944851e28c29.png

Теперь остановите пользовательский интерфейс разработчика ADK, дважды нажав Ctrl+C .

8. Задания (необязательно)

Теперь вы знаете весь рабочий процесс SSD. Проверьте его на практике:

  • Запустите второй цикл SDD для создания веб-чата для консьержа ресторана — на этот раз без пошаговых инструкций.
  • Разверните агент в 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 .
  • В приведенных примерах уже показано, как развернуть и сохранить агент ADK, укажите ссылки на Antigravity!

9. Поздравляем!

Вы расширили функциональность агента ADK для консьерж-сервиса ресторана, добавив функцию бронирования — полностью с помощью рабочих процессов SDD от Antigravity, без написания кода приложения вручную.

То, что ты построил

  • Сервис консьерж-услуг для ресторанов ADK, включающий поиск по меню, семантический поиск, отслеживание диетических предпочтений и бронирование столиков.
  • Навык Antigravity для поиска информации в репозиториях, который генерирует и поддерживает документ с контекстом проекта.
  • Устав проекта, обеспечивающий соблюдение не подлежащих обсуждению принципов на этапах планирования и анализа.
  • Полный цикл SDD, демонстрирующий рабочий процесс: определение → уточнение → планирование → задачи → анализ → внедрение

Что вы узнали

  • Как использовать рабочие процессы разработки, основанные на спецификациях (Spec-Driven Development), в 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