Привет Хабр!
Недавно начал активно использовать инструмент GitHub SpecKit, который превращает хаотичные промпты при разработке в чёткие структурированные документы для AI-агентов. Я пробовал писать код с использованием LLM и был недоволен как нейросеть пишет код. Придерживался мнения что проще самому написать код, чем играть в генерацию кода. Те, кто уже баловался вайб-кдингом знают, как нейросеть начинает фантазировать/галлюцинировать и гонять по кругу ошибки в перемешку с фантазиями и не существующими методами. Но SpecKit приятно удивил ?
Тестировал этот инструмент две недели, делал с ним новый проект и внедрил в существующий. Провёл два стрима на эту тему:
И ребята из комьюнити попросили структурировать информацию. Планировал набросать шпаргалку, но информации много, и работа потихоньку выросла в полноценную статью.
В чём суть GitHub SpecKit?
Вкратце: вместо того чтобы закидывать задачи агенту и героически искать ошибки в полурандомном коде (кто знает, тот знает), вы сначала создаёте детальные спецификации. Эти спецификации становятся источником правильного контекста для нейросети. Она чётко понимает, что делать и за счет этого фантазирует меньше.
Теория красивая. А что на практике? Давайте разбираться.
Установка GitHub SpecKit
Что нужно перед установкой
Git
Python 3.11+ (установится автоматически через UV)
AI-агент (Cursor, Claude Code, GitHub Copilot и т.д.)
Установка на Windows
Шаг 1: Установите UV
Откройте PowerShell от администратора:
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
Шаг 2: Перезапустите терминал
Закройте и откройте PowerShell заново.
Шаг 3: Проверьте установку
uv --version
Должна отобразиться версия UV (например, uv 0.9.6).
Шаг 4: Создайте проект
# Создать в текущей директории
uvx --from git+https://github.com/github/spec-kit.git specify init .
Шаг 5: Выберите агента и тип скриптов в диалоге
Установка на macOS
Шаг 1: Установите UV
curl -LsSf https://astral.sh/uv/install.sh | sh
Шаг 2: Перезагрузите shell
source ~/.zshrc
# или просто закройте и откройте терминал
Шаг 3: Проверьте
uv --version
Шаг 4: Создайте проект
uvx --from git+https://github.com/github/spec-kit.git specify init .
Шаг 5: Выберите агента и тип скриптов в диалоге
Альтернатива: ручная загрузка
Если проблемы с UV — качайте файлы напрямую.
Шаг 1: Перейдите на https://github.com/github/spec-kit/releases/latest
Шаг 2: Скачайте нужный архив:
spec-kit-template-[agent]-powershell-*.zip— Windowsspec-kit-template-[agent]-bash-*.zip— macOS/Linux
Где [agent] — ваш AI-агент (claude, cursor, copilot).
Шаг 3: Распакуйте в корень проекта
# Linux/macOS
unzip spec-kit-template-*.zip -d /path/to/your/project
# Windows PowerShell
Expand-Archive spec-kit-template-*.zip -DestinationPath C:\path\to\your\project
Шаг 4: Инициализируйте Git
git init
git add .
git commit -m "Initial commit with SpecKit"
Проверка установки
1. Откройте AI-агент в папке проекта
# Для Claude Code
claude .
2. Проверьте команды
В списке команд должны быть доступны (введите '/'):
/speckit.constitution/speckit.specify/speckit.clarify/speckit.plan/speckit.tasks/speckit.analyze/speckit.implement
3. Проверьте структуру
your-project/
├── .specify/
│ ├── memory/
│ ├── scripts/
│ └── templates/
├── .claude/
│ └── commands/
└── specs/
Готово! Переходим к практике.
Команды SpecKit
1. /speckit.constitution — “ДНК проекта”
Файл: .specify/memory/constitution.md
Это самый важный файл. Конституция — набор принципов, от которых AI не должен отступать. Все остальные команды зависят от неё.
По умолчанию SpecKit оформляет файлы на английском. Но можно написать инструкцию в Claude.md чтобы файлы спецификации оформлялись на русском.
Что включать в Constitution
1. Архитектурные принципы
Стиль архитектуры (Feature-Sliced Design, Clean Architecture, Microservices)
Паттерны проектирования, которые вы используете
2. Технические ограничения
Языки и их версии (TypeScript, PHP 8.2+, строгая типизация)
Обязательные инструменты (ESLint, Prettier, PHPStan)
Запрещённые библиотеки или подходы
Требования к совместимости
3. Стандарты качества кода
SOLID принципы, DRY, KISS
Стандарты именования (camelCase, snake_case)
Максимальная длина функций/классов
Требования к комментариям и документации
4. Тестирование
Какие тесты обязательны (unit, integration, e2e)
Coverage требования (если есть)
Test-Driven Development подход (если используете)
Стратегия тестирования (AAA pattern, Given-When-Then)
5. Git и коммиты
Стратегия коммитов (один коммит на таску, conventional commits)
Формат commit message
Стратегия бранчей
Требования к PR
6. UX/Accessibility
Стандарты доступности (WCAG AA/AAA)
Поддержка устройств (mobile-first, responsive)
Производительность (Core Web Vitals)
7. Security и Privacy
Требования безопасности
Обработка персональных данных
Compliance (GDPR, и т.д.)
Best Practices
1. Начните с минимума
Не пытайтесь предусмотреть всё. Я начал с 5 ключевых принципов для приложения публикации в Telegram, остальное добавил когда столкнулся с проблемами.
/speckit.constitution
1. Python FastAPI + Vue.js + TypeScript
2. Telegram Bot API для публикации
3. Markdown конвертер с проверкой синтаксиса
4. Токены хранить в переменных окружения
5. Один коммит = одна таска
2. Для существующих проектов — дайте команду проанализировать существующую кодовую базу
/speckit.constitution
Проанализируй текущий код и создай constitution на его основе.
3. Обновляйте по мере роста проекта
Constitution — живой документ! Когда понимаете, что забыли важный принцип — добавляйте.
Типичные ошибки
** Слишком общие формулировки**
"Код должен быть качественным" — что это значит для AI?
** Не переборщите с тестами**
Можете потратить все токены на написание тестов. Поэтому подумайте что конкретно лучше покрыть тестами. С другой стороны - тесты это отличный способ отладки приложения с LLM. Нужна золотая середина.
Лайфхаки
Хак 1: Используйте ChatGPT для генерации первого драфта constitution.
Хак 2: В репозитории SpecKit есть примеры — берите за основу и адаптируйте под свой проект.
Хак 3: Если в компании есть coding standards — превратите их в constitution один раз, используйте во всех проектах.
2. /speckit.specify — Что нужно построить
Сердце Spec-Driven Development. Здесь описываете ЧТО и ЗАЧЕМ, игнорируя технические детали. Думайте как продуктовый менеджер и пользователь проекта, а не как разработчик.
Файл: specs/001-feature-name/spec.md
Главный принцип: "What" и "Why", никакого "How"
** Правильно:**
Пользователь пишет текст в редакторе, видит превью для Telegram
и публикует одним кликом. Система автоматически конвертирует
в markdown формат Telegram и исправляет ошибки форматирования.
Неправильно:
Используй python-telegram-bot для API, храни черновики в Redis,
парси markdown через mistune, публикуй через sendMessage endpoint.
Технические детали — в /speckit.plan!
Что автоматически делает /speckit.specify
Создаёт ветку с автоматической нумерацией (001-telegram-publisher, 002-markdown-editor)
Генерирует spec.md по шаблону:
Feature Overview: Краткое описание, что за проект(фича в проекте) делаем и зачем он нужен
User Stories: Описания сценариев использования и взаимодействия пользователей с проектом. Формат: "Как [роль], я хочу [действие], чтобы [цель]
Functional Requirements: Подробный перечень действий и поведения, которые должен поддерживать проект. Конкретные, измеримые требования
Success Criteria: Условия, при выполнении которых проект считается успешно реализованным.
Key Entities: Важные объекты или элементы данных, задействованные в проекте
Assumptions: Предварительные условия или ограничения, принятые при разработке проекта
Создаёт чек-листы для проверки качества
Типичные ошибки
Ошибка 1: Технические детали в specify
Неправильно:
Используй FastAPI для backend, PostgreSQL для хранения постов,
Redis для очереди.
Правильно:
Пользователи могут сохранять черновики постов. Система
автоматически сохраняет изменения. При публикации пост
отправляется в Telegram через Bot API.
Ошибка 2: Слишком общее описание
Неправильно:
Приложение для постинга в Telegram с удобным интерфейсом.
Ошибка 3: Нечёткие критерии
Неправильно:
- Приложение должно быть быстрым
- Редактор удобным
- Публикация надёжной
Правильно:
- Превью обновляется < 100ms после ввода символа
- Публикация поста < 2 секунд
- Автосохранение каждые 30 секунд
- Retry при ошибке API: 3 попытки с интервалом 5 секунд
- Markdown конвертация без потери форматирования
Best Practices
1. Пишите для человека, не для машины
Ваш коллега, не знакомый с проектом, должен понять что вы хотите построить.
2. Будьте максимально подробны
Чем детальнее опишете — тем меньше вопросов и переделок потом.
3. Используйте "ДОЛЖНА/МОЖЕТ/НЕ ДОЛЖНА"
Система ДОЛЖНА:
- Сохранять черновики автоматически каждые 30 секунд
- Показывать ошибки форматирования понятным языком
Система МОЖЕТ:
- Предлагать исправление типичных ошибок markdown
Система НЕ ДОЛЖНА:
- Публиковать без явного подтверждения от пользователя
4. Разделяйте MVP и будущие фичи
MVP (минимальный запуск):
- Markdown редактор с превью
- Публикация в один канал Telegram
- Автосохранение черновиков
- Исправление базовых ошибок форматирования
Версия 2.0:
- Публикация в несколько ресурсов
- Шаблоны постов
- История публикаций
Версия 3.0:
- Отложенная публикация по расписанию
- Аналитика просмотров
Лайфхаки
Хак 1: User Story Mapping
Визуализируйте путь пользователя (может быть несколько):
Путь пользователя при создании поста:
1. Подключить Telegram бот →
2. Написать текст в редакторе →
3. Увидеть превью как в Telegram →
4. Исправить ошибки форматирования →
5. Нажать "Опубликовать" →
6. Увидеть пост в канале
Хак 2: Используйте ChatGPT для первого драфта
Опишите идею ChatGPT примерно так:
Мне нужно сделать приложение для публикации в Telegram через Bot API.
Пользователь пишет текст в markdown редакторе, видит превью,
система автоматически исправляет ошибки форматирования.
Создай детальную спецификацию включая:
- Все основные функции
- Edge cases
- Success criteria
- User stories
Используй конкретные примеры.
Затем отредактируйте результат, добавьте свои детали и скормите /speckit.specify.
Что дальше?
После создания спецификации:
Прочитайте сами — откройте файл spec.md - всё понятно? Нет противоречий?
Запустите
/speckit.clarify— SpecKit задаст уточняющие вопросы (не обязательно, но рекомендую)Переходите к
/speckit.plan— технологии обсуждаются именно там
Важно: Спецификация — живой документ. Если в процессе разработки что-то меняется — обновляйте spec.md и пересоздавайте план.
3. /speckit.clarify — Уточнение требований
Команду, которую многие пропускают — и напрасно! После создания спецификации агент анализирует её и задаёт вопросы, о которых вы сами не подумали.
Файл: specs/001-telegram-publisher/clarify.md
? Зачем нужна clarify?
Проблема любой спецификации — мы не знаем, что мы не знаем. Кажется, что всё продумано, но стоит начать разработку — выползают десятки вопросов:
А если Telegram Bot API недоступен?
А как обрабатывать некорректный markdown?
А что делать с очень длинными постами (>4096 символов)?
А как обрабатывать rate limiting от Telegram?
Clarify находит эти слепые зоны ДО начала разработки.
? Как работает clarify
Запуск:
/speckit.clarify
Нейросеть анализирует вашу спецификацию и генерирует список вопросов, сгруппированных по категориям:
Authentication & Authorization — авторизация и права
Data Validation & Limits — валидация и лимиты
Error Handling — обработка ошибок
Edge Cases — крайние случаи
Performance & Scale — производительность
Security & Privacy — безопасность
API Integration — особенности интеграций
Для каждого вопроса SpecKit заботливо даст вам готовые варианты ответов. Можете использовать их, ну или свой вариант написать.
Что происходит после ваших ответов?
После каждого ответа нейросеть:
Обновляет spec.md — добавляет новые требования
Дополняет Key Entities — если появились новые сущности
Расширяет Success Criteria — добавляет критерии
Создаёт заметки для plan.md — технические детали
Типичные ошибки
Ошибка 1: Пропустить clarify
Многие думают "у меня и так всё продумано" и идут сразу в plan.
Последствия: Обнаруживаете дыры в спецификации уже в процессе разработки. Приходится мучится и дополнять код с нейросетью. Или вручную.
Поэтому всегда запускайте clarify, даже если уверены что всё учли.
Ошибка 2: Отвечать "не знаю" или "потом решим"
Нейросеть не может работать с неопределённостью. Точнее - она придумает всё что не вы не указали на свой вкус. И зачастую это совсем не то что вы себе представляете.
Правильно: Если не знаете — потратьте 5 минут на исследование. Погуглите, посмотрите как делают конкуренты. Заодно и сами прокачаетесь.
Ошибка 3: Игнорировать "скучные" вопросы про безопасность
Безопасность нельзя "потом добавить".
Правильно: Уделите особое внимание вопросам про:
Валидацию данных
Хранение токенов
Права доступа
Rate limiting
XSS/CSRF защиту
Best Practices
1.Отвечайте подробно
Плохо:
Q: Как обрабатывать длинные посты?
→ B) Показать ошибку
Хорошо:
Q: Как обрабатывать длинные посты?
→ Показывать предупреждение в редакторе при превышении лимита.
Предложить варианты решения:
1. Сократить текст вручную
2. Разбить на несколько постов автоматически
3. Сохранить как черновик для редактирования
Лайфхаки
Хак 1: ChatGPT для подготовки ответов
Если не знаете как ответить. Закидываете вопросы отдельный в чат с нейросетью и исследуете. Или прямо у агента просите разъяснений.
Хак 2: Запускайте clarify после больших изменений
Если обновили spec.md вручную — запустите clarify снова.
Что дальше?
Спецификация теперь детальная и продуманная можно переходить к техническому планированию. Или еще создать чек-листы для самопроверки.
4. /speckit.checklist — Чек-листы качества
Опциональная команда. Создаёт детальные чек-листы для самопроверки спецификации по разным аспектам.
Файлы создаются: specs/001-telegram-publisher/checklists/[тема]-checklist.md
Зачем нужны чек-листы?
После clarify кажется, что всё продумано. Но чек-листы — это структурированная проверка по конкретным критериям качества. Они находят то, что упустили и clarify, и вы.
Аналогия: Clarify — это интервью с умным коллегой. Checklist — это аудит по стандартам качества.
Как использовать checklist
Синтаксис:
/speckit.checklist [тема]
Доступные темы:
UX (User Experience)
/speckit.checklist UX
Security
/speckit.checklist Security
Performance
/speckit.checklist Performance
Accessibility
/speckit.checklist Accessibility
SEO (если релевантно)
/speckit.checklist SEO
Testing
/speckit.checklist Testing
Любая кастомная тема
/speckit.checklist Mobile-First Design
/speckit.checklist Data Privacy GDPR
/speckit.checklist API Design Best Practices
Нейросеть адаптирует чек-лист под вашу тему.
Что внутри чек-листа?
Каждый чек-лист — это серия вопросов с чекбоксами для проверки.
Типичные ошибки
** Ошибка 1: Создать чек-лист и не использовать его**
Многие создают чек-лист, пробегаются глазами и идут дальше. Это бесполезно.
Правильно:
Создайте чек-лист
Честно ответьте на каждый пункт
Для каждого ❌ — дополните спецификацию
Перезапустите checklist и убедитесь что теперь все ✅
Best Practices
1. Создавайте минимум 2 чек-листа
Рекомендую обязательные темы:
UX — для всех проектов
Security — для всех проектов с пользовательским вводом
Лайфхаки
Хак 1: Создайте "Master Checklist"
После нескольких проектов у вас накопится опыт. Создайте один большой чек-лист, который включает:
Самые частые проблемы
Ваши слабые места (что вы обычно забываете)
Специфику вашей ниши Применяйте его к каждому новому проекту перед запуском
/speckit.plan.
Хак 2: Используйте чек-листы для code review
Когда нейросеть генерирует код, пройдитесь по чек-листам и проверьте:
Реализованы ли все пункты из Security checklist?
Соблюдены ли все требования Performance checklist?
Что дальше?
Спецификация теперь максимально детальная и проверенная по всем критериям качества. Пора переходить к техническому планированию!
5. /speckit.plan — Технический план
Это момент, когда абстрактное описание "что нужно" превращается в конкретный план "как это сделать". Нейросеть анализирует спецификацию и создаёт конкретный технический план с выбором стека, архитектурой и реализацией.
Что делает команда plan?
Plan — это мост между "что нужно построить" и "какой код писать". Здесь решаются все технические вопросы:
Какой стек использовать?
Как организовать архитектуру?
Какие библиотеки подключить?
Как структурировать код?
Какие API endpoints создать?
Как спроектировать базу данных?
Создаются файлы:
specs/001-telegram-publisher/plan.md— детальный план разработкиspecs/001-telegram-publisher/research.md— исследование технологийspecs/001-telegram-publisher/database-schema.md— схема базы данныхspecs/001-telegram-publisher/api-documentation.yaml— OpenAPI спецификация (если есть API)specs/001-telegram-publisher/quickstart.md— инструкции для быстрого старта
Как использовать plan
Способ 1: С указанием стека (рекомендуется)
/speckit.plan
Backend: Python FastAPI + TypeScript
Frontend: Vue.js 3
UI: Tailwind CSS + shadcn-vue
Редактор: Markdown редактор с live preview
Telegram: python-telegram-bot
База данных: PostgreSQL
Кэш: Redis для очереди публикаций
Деплой: Docker
Способ 2: Без указания стека
/speckit.plan
Нейросеть сама предложит оптимальный стек на основе заполненной спецификации.
Что внутри plan.md?
Plan.md — это исчерпывающий технический документ. Вот основные секции:
1. Technology Stack (Стек технологий)
Детальное описание всех технологий с обоснованием выбора.
2. Project Architecture (Архитектура проекта)
Описание структуры проекта:
src/
├── backend/
│ ├── api/ # FastAPI endpoints
│ ├── services/ # Telegram, Markdown converter
│ ├── models/ # Database models
│ └── utils/ # Helpers
├── frontend/
│ ├── components/ # Vue компоненты
│ │ ├── Editor/ # Markdown редактор
│ │ └── Preview/ # Telegram превью
│ ├── stores/ # Pinia stores
│ └── api/ # API client
└── shared/
└── types/ # TypeScript типы
3. Database Schema
Подробная схема базы данных с индексами.
4. API Endpoints
Детальная спецификация API.
5. Implementation Details
Специфичные детали реализации проекта на основе заполненной спецификации.
Типичные ошибки
Ошибка 1: Принять план не глядя
Проблема: План может содержать неоптимальные решения или излишнюю сложность.
Правильно: Внимательно изучите минимум "Technology Stack" и "Architecture". Если что-то не нравится — можете изменить сами или через диалог с агентом.
Ошибка 2: Не обновлять plan.md в ходе разработки
Проблема: Вы меняете стек в процессе разработки, но plan.md остаётся старым. Потом нейросеть на /speckit.implement следует устаревшему плану.
Правильно: Каждое изменение стека/архитектуры → обновление plan.md.
Ошибка 3: Пытаться запомнить всё из плана
Используйте plan.md как справочник. И открываете по мере необходимости:
Забыли структуру API? → Открыли "API Specification"
Не помните как называется таблица? → Открыли "Database Schema"
Best Practices
1. Читайте план критически
Не принимайте на веру всё что сгенерировала нейросеть. Задавайте вопросы:
Почему выбран именно этот фреймворк?
Нужна ли такая сложная архитектура?
Можно ли проще?
2. Запросите альтернативы для ключевых решений
Ты предложил PostgreSQL для БД. Какие альтернативы есть?
Сравни PostgreSQL vs SQLite vs MongoDB для этого проекта.
Плюсы/минусы каждого варианта.
Лайфхаки
Хак 1: Используйте ChatGPT для review плана
Скопируйте план в ChatGPT:
Вот технический план проекта: [вставляете plan.md]
Проанализируй:
1. Есть ли переусложнения?
2. Где могут быть bottleneck'и?
3. Какие риски ты видишь?
4. Что можно упростить для MVP?
Что дальше?
План готов! Теперь нужно разбить его на конкретные задачи!
6. /speckit.tasks — Разбивка на задачи
Критически важная команда. Она превращает огромный технический план в последовательность мелких выполнимых задач.
Файл создаётся: specs/001-telegram-publisher/tasks.md
Зачем нужна команда tasks?
После /speckit.plan у вас есть детальный план на 50+ страниц. Круто, но с чего начать? Что делать первым? Что вторым?
Tasks решает эту проблему:
Разбивает план на конкретные задачи
Определяет правильную последовательность
Группирует задачи по фазам
Оценивает сложность каждой задачи
Важно: Разработчики SpecKit недавно полностью переработали генерацию задач. Теперь фокус на быстром получении MVP.
Как использовать tasks
Синтаксис:
/speckit.tasks
Команда без параметров - тут можно передохнуть). Она берёт plan.md и автоматически генерирует структурированный список задач.
Что происходит:
Анализирует технический план
Выявляет dependencies между задачами
Определяет критический путь (что нужно сделать ОБЯЗАТЕЛЬНО для MVP)
Группирует задачи по фазам
Оценивает сложность (простая / средняя / сложная)
Структура tasks.md
Tasks.md сгруппирован по фазам разработки (обычно получается 5-7 фаз).
Каждая задача содержит:
ID (T001, T002...)
Маркер Critical ⭐️ (если это must-have для MVP)
Сложность (простая/средняя/сложная)
Время (оценка) - обычно тут сильно преувеличено.
Описание (что нужно сделать)
Acceptance Criteria (как проверить что готово)
Files to create (какие файлы создать)
Dependencies (какие задачи должны быть выполнены до этой)
Мой опыт работы с tasks
Что я понял:
больше половины задач — это "nice to have", не MVP
реализация MVP тестировать работу приложения в то время как агент будет продолжать его писать
Детальное описание каждой задачи экономит тонны времени
Типичные ошибки при работе с tasks
Ошибка 1: Игнорировать Dependencies
Проблема: Пытаетесь сделать T022 (Подключить публикацию в Telegram), не сделав T012 (Настроить Bot API). Естественно, не работает.
Правильно:
Следуйте порядку задач
Проверяйте Dependencies перед началом задачи
Если хотите сделать задачу вне очереди — убедитесь что все dependencies выполнены
Ошибка 2: Не обновлять tasks.md
Проблема: Вы решили изменить архитектуру в процессе, но tasks.md остался старым. Нейросеть на /speckit.implement следует устаревшему плану.
Правильно:
Если изменили подход — обновите соответствующие задачи
Добавляйте новые задачи, если появились
Помечайте выполненные задачи как DONE
Best Practices для tasks
1. Работайте строго по фазам
Не прыгайте между фазами. Закончили Phase 1 полностью → переходите к Phase 2.
Почему: Каждая фаза — логически завершённый блок. Если перепрыгивать — легко что-то упустить.
2. Создавайте отдельные Git ветки для фаз
3. Каждая задача = один коммит
git commit -m "T005: Create Markdown Editor Component
- Add editor with syntax highlighting
- Configure live preview
- Implement auto-save
Closes T005"
Следуйте формату из Constitution! Если там прописано "один коммит на таску" — делайте именно так.
Лайфхаки
Разбивайте сложные задачи
Если задача кажется слишком большой — попросите нейросеть разбить её:
Задача T014 слишком сложная. Разбей её на 5-7 под-задач,
каждая должна быть выполнима за 30-60 минут.
Что дальше?
У вас есть чёткий план действий. Но перед тем как начать implement — очень полезно запустить:
/speckit.analyze
Эта команда найдёт проблемы, конфликты и несоответствия во всех созданных спецификациях. Лучше исправить их сейчас, чем в процессе разработки!
7. /speckit.analyze — Поиск проблем
Это самая недооценённая команда во всём SpecKit. И самая важная с точки зрения экономии времени.
Файл создаётся: specs/001-telegram-publisher/analysis.md
Зачем нужна команда analyze?
После создания спецификации, плана и задач кажется, что всё идеально. Но часто есть скрытые проблемы:
Конфликты между требованиями
Несоответствия между spec и plan
Технические невозможности
Упущенные edge cases
Нереалистичные оценки
Противоречия в dependencies
Analyze — это AI-аудит всех созданных документов. Как опытный тимлид, который ревьюит ваш проект перед стартом разработки.
Как использовать analyze
Синтаксис:
/speckit.analyze
Команда без параметров. Она читает все файлы в specs/001-telegram-publisher/ и ищет проблемы.
Что анализируется:
spec.md— спецификацияplan.md— технический планtasks.md— задачиdatabase-schema.md— схема БДapi-documentation.yaml— API docsconstitution.md— конституция проекта (из.specify/memory/)
Типичные ошибки
Ошибка 1: Пропустить analyze и сразу идти в implement
Последствия:
Обнаружите проблемы в процессе разработки
Придётся переделывать уже написанный код
Трата времени и мотивации
Правильно:
Analyze — обязательный шаг перед implement. Даже если уверены что всё идеально.
Ошибка 2: Игнорировать Critical проблемы
"Ну это мелочь, потом исправлю" — знакомо?
Проблема: Critical issues названы так не просто так. Они блокируют функциональность или создают серьёзные риски.
Правильно:
Все Critical — исправлять до начала разработки.
Ошибка 3: Исправлять проблемы "на глаз", не обновляя документы
Нашли проблему, мысленно решили "буду делать по-другому", но не обновили spec/plan/tasks.
Проблема: Нейросеть на implement будет следовать старым документам.
Правильно:
Каждое исправление → обновление соответствующего файла → повторный analyze.
Ошибка 4: Не запускать analyze повторно после правок
После исправления проблем могут появиться новые (из-за изменений).
Правильно:
Запускайте analyze несколько раз до "No critical issues found".
Best Practices
1. Запускайте analyze минимум 2 раза
Первый раз: После создания всех спецификаций
Второй раз: После исправления критичных проблем
Лайфхаки
Хак 1: Попросите AI объяснить проблему подробнее
Если не понимаете какую-то Issue:
Issue H001 — не понял.
Объясни на примере: что конкретно может пойти не так?
Приведи сценарий шаг за шагом.
Хак 2: Попросите AI предложить решение
Как лучше всего исправить C003?
Предложи 3 варианта с плюсами и минусами каждого.
Что дальше?
Все проблемы исправлены. Спецификации чистые. План детальный. Задачи разбиты. Конфликтов нет.
Пора кодить!
8. /speckit.implement — Реализация
Финальная и самая мощная команда. Она берёт все созданные спецификации и начинает писать код.
Важно: Это не генерация кода в одно нажатие. Это управляемый процесс разработки, где вы контролируете каждый шаг.
Как работает implement?
Implement читает:
Constitution (незыблемые правила)
spec.md (что нужно построить)
plan.md (как это реализовать)
tasks.md (последовательность действий)
analysis.md (известные проблемы)
И начинает последовательно выполнять задачи, создавая код.
Варианты использования implement
Вариант 1: Всё сразу (не рекомендуется)
/speckit.implement
Нейросеть попытается выполнить максимум задач за одну сессию. Проблема: контекстное окно быстро переполняется, качество кода падает.
Вариант 2: По фазам (рекомендуется)
/speckit.implement Phase 1
Выполняет только задачи из Phase 1. После завершения — новая сессия для Phase 2.
/speckit.implement Phase 1-2
Выполняет задачи из Phase 1 и Phase 2.
Вариант 3: Конкретные задачи
/speckit.implement T001, T002, T003
Выполняет только указанные задачи (удобно для фиксов).
Важный момент: Implement — это не "сделай всё за меня". Это работа вместе с AI. Вы контролируете процесс, проверяете результаты, просите исправить проблемы.
Типичные ошибки
Ошибка 1: Запустить implement без analyze
Последствия: Нейросеть будет следовать проблемным спецификациям. Код придётся переделывать.
Правильно: Всегда analyze → исправление проблем → implement.
Ошибка 2: Пытаться сделать всё за одну сессию
Последствия: Переполнение контекста, галлюцинации, плохой код.
Правильно: Работайте по фазам или даже по отдельным задачам. Заодно токены сэкономите!
Ошибка 3: Не тестировать результаты после каждой фазы
"Сделаю все 6 фаз, потом протестирую" — рецепт катастрофы.
Проблема: Баг в Phase 1 может сломать Phase 2, 3, 4... Найдёте только в конце и придётся всё переделывать.
Правильно: Phase 1 → тест → Phase 2 → тест → и так далее.
Ошибка 4: Принимать код не глядя
"Нейросеть сгенерировала — значит работает" — опасное заблуждение.
Правильно: Всегда читайте сгенерированный код. Хотя бы бегло.
Ошибка 5: Не коммитить после каждой фазы
Проблема: Что-то сломалось, но вы не помните что работало до этого.
Агент может если чтото пошло не так получить код из предыдущего коммита.
А лучше всё это указать при формировании спецификации.
Best Practices для implement
1. Одна фаза = одна сессия чата
Не пытайтесь делать несколько фаз в одной сессии. Контекст загрязняется.
Workflow:
Новая сессия чата
/speckit.implement Phase 1Ждёте завершения
Тестируете результат
Коммитите
Закрываете сессию (/clear)
Новая сессия →
/speckit.implement Phase 2
2. Просите объяснений для сложного кода
Если сгенерированный код непонятен:
Объясни что делает эта функция в MarkdownConverter.py строки 45-78.
Почему использован regex здесь? Какую проблему он решает?
Лайфхаки
Хак 1: Параллельная разработка (если знаете что делаете)
Пока нейросеть делает Phase 3 (backend), вы можете в другом терминале попросить:
/speckit.implement Phase 4: T019, T020
Создай только frontend компоненты редактора.
Backend endpoints пока не готовы — используй mock data.
Итоговый вывод
GitHub SpecKit — это не волшебная пилюля для вайбкодеров, но мощный инструмент при правильном использовании.
Для кого SpecKit идеален:
Небольшие и средние проекты (до 50 файлов)
Проекты где важна чистая архитектура
Solo-разработчики
Обучение (понять как строить проекты правильно)
Когда SpecKit избыточен:
Быстрые прототипы ("просто показать идею")
Очень маленькие проекты (1-5 файлов)
Проекты где скорость > качество
Когда SpecKit проблематичен:
Большие legacy проекты (нужно создавать спеки для всего)
Очень сложные проекты (1000+ файлов)
Я буду использовать SpecKit для новых проектов! Там где не хочу писать код сам)
Ключевые выводы:
Clarify — не пропускайте. Она находит то, о чём вы не подумали.
Checklist — перестраховка. UX, Security — обязательны.
Plan — критически проверяйте. Не принимайте на веру, упрощайте для MVP.
Tasks — фокус на Critical. 70% задач — это nice-to-have, а не MVP.
Analyze — спасает от переделок. Лучше потратить час на исправление спеков, чем день на переписывание кода.
Implement — работайте по фазам. Одна фаза = одна сессия. Между этапами обязательно делайте /clear чтобы уменьшать объём контекста для уменьшения галлюцинаций и экономии токенов.
Тестируйте результаты работы. После каждой фазы.