Spec Kit

Автоматизированный контроль качества спецификаций ПО на базе ИИ

Spec Kit --- система для spec-driven development и автоматической оценки качества кода. Включает два основных инструмента:

1. Spec-Driven Development --- полный цикл от идеи до кода: спецификация, уточнение, планирование, генерация задач, реализация.
2. Quality Loop --- итеративная оценка и улучшение кода по набору правил с 13 шаблонами критериев.

---

Установка через AI-агента (рекомендуется)

Самый быстрый способ --- попросите AI-агента (Claude Code, Cursor, Windsurf) выполнить установку:

Прочитай файл INSTALL.md в этом репозитории и выполни установку SpecKit

AI-агент автоматически:

• Скопирует SpecKit в ~/.claude/spec-kit/
• Создаст структуру директорий для памяти и скиллов
• Настроит команды /speckit.* в Claude Code
• При необходимости установит Ollama для векторной памяти

Полное руководство по установке: INSTALL.md

---

Быстрый старт (ручная установка)

# Клонирование и установка
git clone https://github.com/github/spec-kit.git
cd spec-kit
pip install -r requirements.txt

Цикл разработки (основной workflow)

# В чате Claude Code / Cursor:
/speckit.specify Описание вашей фичи...        # 1. Создать спецификацию
/speckit.clarify                                # 2. Уточнить детали
/speckit.plan Ваш стек и архитектура...         # 3. Создать техплан
/speckit.tasks                                  # 4. Сгенерировать задачи
/speckit.implement                              # 5. Реализовать

Проверка качества кода

/speckit.loop --criteria backend                # Оценить backend-код
/speckit.loop --criteria backend,security       # Несколько шаблонов
/speckit.loop --project-type web-app            # Автовыбор шаблонов

Быстрая фича (< 4 часов)

/speckit.features Добавить endpoint GET /api/users/:id/stats

Подробное руководство с примерами для каждой команды: docs/usage-guide.md

---

Возможности

Разработка через спецификации

Команда	Что делает
/speckit.constitution	Задать принципы проекта
/speckit.specify	Создать спецификацию фичи
/speckit.clarify	Уточнить требования (ИИ задаёт вопросы)
/speckit.plan	Создать технический план
/speckit.tasks	Разбить план на задачи
/speckit.analyze	Проверить согласованность spec/plan/tasks
/speckit.implement	Реализовать задачи
/speckit.features	Быстрая фича за один шаг
/speckit.checklist	Кастомный чеклист

Контроль качества

Команда	Что делает
/speckit.loop	Итеративная оценка и улучшение кода
/speckit.implementloop	Реализация + quality loop

Шаблоны и конфигурация

Команда	Что делает
/speckit.templates	Реестр шаблонов критериев
/speckit.plans	Сохраненные планы и конфигурации loop

Интеграции

Команда	Что делает
/speckit.createagent	Создание AI-агента (полуавтоматический режим)
/speckit.taskstoissues	Экспорт задач в GitHub Issues
/speckit.tobeads	Импорт задач в Beads

---

Скиллы и агенты

SpecKit поддерживает работу с AI-агентами и скиллами из сообщества через SkillsMP (425K+ скиллов).

Поиск и установка готовых скиллов

# Поиск скиллов через SkillsMP API
# (требуется API-ключ, см. INSTALL.md Step 7)

AI-агент может:

1. Найти существующий скилл в SkillsMP по описанию задачи
2. Скачать и установить скилл с автоматической проверкой безопасности
3. Использовать GitHub fallback если SkillsMP недоступен

Создание собственных агентов

/speckit.createagent Описание нужного агента...

Полуавтоматический режим:

1. AI анализирует запрос — определяет тип агента и подходящий шаблон
2. AI генерирует черновик — создаёт AGENTS.md, SOUL.md, USER.md, MEMORY.md
3. Вы просматриваете — подтверждаете или просите изменения
4. AI применяет правки — добавляет навыки, меняет personality, ищет best practices в интернете
5. Сохранение — агент готов к использованию

Пример:

Пользователь: /speckit.createagent Нужен агент для code review Python проектов

AI: Анализирую... Создаю агента на основе шаблона "backend-dev":
    - Роль: Python Code Reviewer
    - Навыки: PEP8, type hints, security patterns, async/await...

    [Показывает сгенерированные файлы]

Пользователь: Добавь проверку на SQL injection и Django

AI: [Обновляет агента, ищет best practices в интернете]
    Готово! Агент сохранён в ~/.claude/agents/python-code-reviewer/

Доступные шаблоны: frontend-dev, backend-dev, fullstack-dev, architect, qa-tester, devops, data-engineer, ml-engineer

Безопасность скиллов (двухуровневая система)

Все скиллы проходят автоматическую проверку перед установкой:

Уровень	Метод	Что проверяет
Level 1	Статический анализ (Python)	Prompt injection, data exfiltration, destructive commands, encoded payloads
Level 2	LLM-обзор	Intent mismatch, contextual threats, authority abuse, obfuscation

Результаты сканирования:

• SAFE — установка разрешена
• BLOCKED — установка заблокирована, файл удалён
• WARNING — требуется подтверждение пользователя

Подробнее: docs/security-scanning.md

---

Шаблоны критериев (13 шт.)

Шаблон	Описание
backend	Backend API и серверная часть
frontend	Frontend UI/UX
security	Безопасность
performance	Производительность
testing	Тесты
api-spec	Спецификация API
database	Схема БД
docs	Документация
config	Конфигурация
infrastructure	Инфраструктура
ui-ux	UI/UX дизайн
live-test	Живое тестирование
code-gen	Генерация кода

---

Конфигурация

Файл .speckit/config.yml в корне проекта:

quality:
  criteria: backend
  max_iterations: 4
  threshold_a: 0.8
  threshold_b: 0.9
  priority_profile: web-app
  gate_preset: production

Подробнее: docs/configuration.md

---

Документация

Документ	Описание
Руководство по использованию	Как и зачем использовать каждую команду (начните здесь)
Установка через AI-агента	Полное руководство по установке
Быстрый старт	Пошаговый пример от идеи до кода
Quality Loop	Архитектура, шаблоны, правила и веса
Конфигурация	Файлы конфигурации, профили, политики
Шаблоны	Реестр шаблонов, смешивание, пресеты
Память агента	3 уровня памяти, векторный поиск
AI-агенты и скиллы	Полуавтоматическое создание агентов, SkillsMP
Безопасность скиллов	Двухуровневая система проверки скиллов

---

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

spec-kit/
├── src/specify_cli/quality/   # Ядро системы качества
│   ├── models.py              # Модели данных
│   ├── rules.py               # Управление правилами
│   ├── evaluator.py           # Оценка качества
│   ├── scorer.py              # Скоринг
│   ├── critique.py            # Генерация критики
│   ├── refiner.py             # Улучшение артефактов
│   ├── loop.py                # Координатор цикла качества
│   └── templates/             # Шаблоны критериев (YAML)
├── templates/commands/        # Шаблоны команд CLI
├── tests/                     # Тесты
├── docs/                      # Документация
└── README.md

---

Разработка

python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -e ".[dev]"
pytest tests/

---

Лицензия

MIT License --- см. LICENSE.

---

Spec Kit --- Spec-Driven Development + Автоматический контроль качества