Изучение рабочих процессов GitHub Spec Kit и необязательных команд

  • 8 мин

GitHub Spec Kit — это набор средств с открытым исходным кодом, который позволяет разрабатывать на основе спецификаций (SDD), интегрируя спецификации с помощниками по программированию ИИ. Прежде чем изучать расширенные функции, давайте рассмотрим основные понятия.

Ознакомьтесь с основами набора спецификаций GitHub

Пакет спецификаций GitHub решает основную проблему разработки с помощью искусственного интеллекта: поддержание контекста и согласованности в нескольких взаимодействиях с помощниками по программированию. Он предоставляет три основных возможности:

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

Основные компоненты

GitHub Spec Kit реализует следующие основные компоненты:

Компонент Цель
specify Интерфейс командной строки (CLI) Инициализирует проекты на основе спецификаций и управляет ими.
Файлы артефактов Markdown constitution.md, spec.md, plan.md, tasks.md стимулируют разработку.
Слэш-команды /speckit.specify, /speckit.plan, /speckit.tasks, /speckit.implement инициируют рабочие процессы GitHub Spec Kit.

Агенты ИИ

GitHub Spec Kit поддерживает следующие агенты ИИ: GitHub Copilot, Claude Code, Cursor, Windsurf, Amazon Q Developer и другие. Каждый агент получает шаблоны, отформатированные для определенного формата запроса, используя те же базовые файлы артефактов.

Переменные среды для отслеживания функций

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

В рабочих процессах на основе Git, GitHub Spec Kit выводит функцию из имени вашей ветви. Если вы находитесь в ветви feature/document-upload, набор спецификаций GitHub автоматически работает с каталогом features/document-upload/ .

Для рабочих процессов, отличных от Git или ручной спецификации компонентов, задайте переменную среды явным образом:

$env:SPECIFY_FEATURE = "001-document-upload"

Этот параметр указывает GitHub Spec Kit на чтение и запись артефактов в каталоге features/001-document-upload/ независимо от ветки Git.

Это отслеживание функций гарантирует, что при вызове /speckit.planИИ считывает правильный spec.md файл для текущей функции, а не смешивает спецификации из разных функций.

Интеграция пакета спецификаций GitHub с рабочими процессами Git

GitHub Spec Kit интегрируется в существующие методики разработки с помощью нескольких механизмов.

Интеграция управления версиями

Все артефакты набора спецификаций GitHub — это обычные markdown-файлы, хранящиеся в репозитории Git. Этот подход дает несколько преимуществ:

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

  • Разработка на основе ветвления: создание функциональных веток, содержащих артефакты спецификации и код реализации. Этот подход сохраняет требования и реализацию синхронизированными и делает проверку кода исчерпывающей — рецензенты видят и то, что вы создаёте (спецификацию), и то, как вы это сделали (код).

  • Рабочий процесс pull request: При отправке pull request на функцию добавьте spec.md, plan.md и tasks.md вместе с изменениями в коде. Рецензенты проверяют, соответствует ли реализация спецификациям и что спецификации соответствуют целям проекта.

Например, если вы реализуете новую функцию, ветвь функций содержит следующее:

  • spec.md определение требований к отправке.
  • plan.md описание архитектуры хранилища Azure Blob.
  • tasks.md перечисление шагов реализации.
  • Исходный код, реализующий функционал.
  • Проверяет соответствие спецификаций.

Эта полная картина обеспечивает тщательную проверку. Если рецензент задаст вопрос о том, почему файлы ограничены 50 МБ, он может ссылаться на spec.md, чтобы увидеть, что это требование возникло в результате обсуждений заинтересованных лиц.

Сценарий интеграции помощника по искусственному интеллекту — GitHub Copilot

GitHub Spec Kit работает с GitHub Copilot через интерфейс чата Visual Studio Code. После запуска specify init --ai copilot инструментарий настраивает рабочую область для распознавания команд /speckit.*.

Когда вы открываете GitHub Copilot Chat и введите /speckit.specify, GitHub Copilot обращается к предопределенным шаблонам из .github/prompts/ каталога. Эти шаблоны помогают структурировать выходные данные ИИ для включения всех необходимых разделов спецификаций: пользовательские истории, условия принятия, функциональные требования, нефункциональные требования и пограничные варианты.

Интеграция удобна— вы не управляете шаблонами вручную. GitHub Spec Kit автоматически обрабатывает загрузку шаблона и внедрение контекста. Ваша задача — предоставить описания функций и ответить на уточняющие вопросы. GitHub Copilot обрабатывает форматирование спецификаций и полноту.

Соглашения о структуре проекта

GitHub Spec Kit упорядочивает артефакты с помощью согласованной структуры каталогов:

my-project/
├── .github/
│   ├── agents/
│   └── prompts/
├── .specify/
│   ├── memory/
│   │   └── constitution.md
│   ├── scripts/
│   └── templates/
├── SourceCode/ 
│   └── ...
├── specs/
│   └── 001-document-upload-feature/
│       ├── plan.md
│       ├── spec.md
│       └── tasks.md

Эта структура отделяет артефакты спецификации от кода реализации, сохраняя их в одном репозитории. Функции нумеруются последовательно (001, 002, 003) для отслеживания порядка разработки.

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

Поддержка непрерывного рабочего процесса

GitHub Spec Kit поддерживает итеративную разработку с помощью цепочки команд. После создания начальных спецификаций их можно постепенно уточнить:

  1. Создайте начальную спецификацию: /speckit.specify.
  2. Определение пробелов: /speckit.clarify
  3. Обновите спецификацию на основе ответов.
  4. Создание плана реализации: /speckit.plan
  5. Проверка согласованности: /speckit.analyze.
  6. Создание задач: /speckit.tasks.
  7. Реализуйте постепенно: /speckit.implement.

В любой момент, если требования изменяются, можно вернуться к более ранним этапам, обновить артефакты и повторно создать подчиненные артефакты. Если заинтересованные лица изменили свое мнение о ограничениях размера файла после создания задач, вы обновляете spec.md, повторно создайте plan.md, чтобы отразить архитектурные последствия, повторно создайте tasks.md с обновленными шагами проверки, а затем обновите код реализации.

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

Использование необязательных команд улучшения пакета спецификаций GitHub

Помимо основных команд рабочего процесса GitHub Spec Kit предоставляет необязательные команды, которые повышают качество спецификаций и согласованность.

Использование /speckit.clarify для проведения анализа пробелов

Команда /speckit.clarify анализирует спецификацию, чтобы определить неоднозначность, отсутствующие сведения и неуверенные пограничные случаи. После создания начальной спецификации вызовите эту команду, чтобы ИИ задавать уточняющие вопросы.

ИИ проверяет спецификацию и создает такие вопросы, как:

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

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

Это интерактивное уточнение перехватывает проблемы до начала реализации. Это как если бы опытный аналитик проверяет вашу спецификацию и указывает на что вы не обратили внимание.

Используйте /speckit.analyze для проверки согласованности

Команда /speckit.analyze выполняет проверку согласованности между артефактами. Он проверяет, что план соответствует всем требованиям спецификации, что задачи охватывают все элементы плана и что всё согласуется с конституцией.

Выполните эту команду после создания plan.md и tasks.md, но перед началом реализации. ИИ определяет несоответствия:

  • "План предлагает использовать PostgreSQL, но для конституции требуется База данных SQL Azure".
  • "Спецификация требует ведения журнала аудита, но план не описывает реализацию ведения журнала".
  • "Список задач исключает сценарии миграции базы данных, упомянутые в плане".

Каждая обнаруженная несогласованность — это проблема, которая будет отображаться во время реализации или проверки кода. Перехват их во время этапа анализа предотвращает повторную работу.

Использование /speckit.checklist для проверки качества

Команда /speckit.checklist создает настраиваемые контрольные списки качества на основе спецификации. Эти контрольные списки помогают проверить полноту требований, ясность и согласованность, как тесты, подобные "модульным тестам для английской прозы".

ИИ анализирует спецификацию и создает контрольный список вопросов проверки:

  • "Есть ли у каждой истории пользователя соответствующие критерии принятия?"
  • "Все сценарии ошибок задокументированы с определенными сообщениями об ошибках?"
  • "Нефункциональные требования включают измеримые критерии успешности?"
  • "Указаны ли все внешние зависимости явным образом?"

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

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

Применение пакета спецификаций GitHub к различным сценариям разработки

Набор спецификаций GitHub поддерживает различные сценарии разработки, помимо создания новых функций с нуля.

Разработка Гринфилда

Для новых проектов, начиная с нуля, GitHub Spec Kit отлично преобразует высокоуровневое видение продукта в конкретную реализацию. Начните с /speckit.constitution чтобы установить принципы проекта, а затем используйте /speckit.specify для каждой особенности при итеративной разработке приложения.

Этот сценарий является основным вариантом использования GitHub Spec Kit— рабочий процесс был разработан для разработки 0–1, где вы создаете то, что еще не существует.

Улучшение Браунфилда

Для существующих приложений можно использовать набор спецификаций GitHub для добавления новых функций при сохранении согласованности с существующей базой кода. Ваша конституция документирует существующие архитектурные шаблоны и ограничения. Новые спецификации функций ссылались на эти установленные шаблоны.

При добавлении функции отправки документов на существующий портал сотрудников спецификация подтверждает существующую интерфейсную часть React, серверную часть .NET и инфраструктуру Azure. В плане показано, как новая функция интегрируется с текущей архитектурой, а не предлагает отдельную реализацию.

Рефакторинг и модернизация

Пакет спецификаций GitHub может направлять усилия по рефакторингу, рассматривая требуемое конечное состояние как спецификацию. Вы задокументируете, что должен достичь рефакторинг кода (те же функции с улучшенной структурой), создать план для рефакторингового подхода и создать задачи для добавочных изменений.

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

Исследовательская разработка

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

Вы можете создать один план с помощью Хранилище BLOB-объектов Azure и другой с помощью Файлы Azure, оба из одной и той же спецификации загрузки. Реализуйте оба варианта, сравнивайте результаты и выбирайте лучший подход на основе фактического опыта, а не предположений.

Сводка

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