🎯 О чём этот конспект: Разбор OpenSpec — опенсорсного фреймворка для управления AI-агентами (Cursor, GitHub Copilot, Windsurf) через спецификации. Вместо хаотичного промптинга предлагается метод «сначала проект, потом код», что исключает галлюцинации AI и поломку архитектуры при масштабировании проекта.
👤 Кому будет полезно: Разработчикам и вайбкодерам, которые столкнулись с тем, что AI начинает «тупить» или переписывать рабочие функции в больших проектах.
✨ Что получите: Пошаговый алгоритм настройки OpenSpec, который превратит ваш AI-агент в дисциплинированного исполнителя, работающего по строгому техническому заданию и отслеживаемому списку задач.
1. Проблема «сырого» промптинга и решение через OpenSpec
Контекст: При работе с Cursor или Claude Code часто возникает ситуация: вы просите добавить фичу, и AI выдает рабочий код, который ломает существующую логику или не соответствует вашему видению архитектуры. Это происходит из-за отсутствия «единого источника правды». OpenSpec решает это через Specification-Driven Development (SDD). В отличие от своего предшественника SpecKit, OpenSpec разделяет текущие спецификации и предлагаемые изменения (папка changes), что позволяет безопасно масштабировать проект без потери контроля.
Выгода: Предсказуемый результат, отсутствие необходимости постоянно исправлять ошибки AI и прозрачный аудит всех изменений.
Как применить:
- Шаг 1: Понимание философии — Примите правило: «Сначала фиксируем намерение (Intent), затем внедряем (Implement)». Никакого кода, пока AI и вы не согласуете спецификацию.
- Шаг 2: Выбор агента — OpenSpec работает как надстройка. Вы можете использовать его с Cursor, Windsurf или VS Code (Copilot).
2. Установка и инициализация окружения
Контекст: OpenSpec — это CLI-инструмент (интерфейс командной строки), который не требует API-ключей или регистрации. Он работает локально и подготавливает структуру папок, которую ваш AI-агент будет использовать как инструкцию.
Выгода: Быстрый старт без затрат на подписки (кроме вашего основного AI-агента).
Как применить:
- Шаг 1: Установка CLI — Убедитесь, что у вас установлен Node.js, и выполните команду в терминале:
npm install -g openspec- Шаг 2: Проверка версии — Убедитесь, что установка прошла успешно:
openspec --version- Шаг 3: Инициализация в проекте — Перейдите в папку вашего проекта и запустите:
openspec init- Шаг 4: Выбор агента — В появившемся меню выберите ваш инструмент (например,
cursorилиgithub-copilot). OpenSpec создаст файлы конфигурации, оптимизированные под конкретный AI.
Результат: В корне проекта появятся файлы agent.md (инструкции для AI) и project.md (контекст проекта).
3. Настройка контекста проекта (Single Source of Truth)
Контекст: Чтобы AI понимал ваш стек (например, Next.js + Tailwind + Supabase), нужно заполнить project.md. OpenSpec автоматизирует этот процесс, предлагая специальный промпт, который заставляет AI проанализировать ваши файлы и задокументировать архитектурные решения.
Выгода: AI перестает предлагать неподходящие библиотеки или паттерны проектирования.
Как применить:
- Шаг 1: Копирование промпта — OpenSpec предоставит шаблон промпта для инициализации контекста.
- Шаг 2: Запуск в AI-чате — Вставьте промпт в ваш AI-агент (например, в Cursor Composer или Copilot Chat):
Read the OpenSpec project.md file and help me fill out all the relevant details about my project: tech stack, architecture preferences, testing approach, and coding standards.- Шаг 3: Верификация — Проверьте обновленный
project.md. Теперь это официальный документ, на который AI будет ссылаться при создании каждой новой функции.
4. Создание предложений по изменениям (Proposals)
Контекст: Вместо команды «сделай страницу задач», вы инициируете процесс предложения. AI создает черновик в папке changes, описывая дизайн, список задач (task list) и спецификации компонентов до написания кода.
Выгода: Вы можете проверить логику реализации до того, как AI изменит файлы проекта.
Как применить:
- Шаг 1: Формирование запроса — Используйте шаблон для запроса фичи:
I want to create an OpenSpec changes proposal for the core task management feature. Include: task creation, project organization, and status tracking.- Шаг 2: Анализ папки
changes— AI создаст файлы:design.md— технический подход.tasks.md— пошаговый план работ.specs/— детальное описание поведения компонентов.
5. Имплементация и мониторинг прогресса
Контекст: Когда спецификация утверждена, вы даете команду на выполнение. AI следует строго по списку задач из tasks.md. Вы можете в реальном времени наблюдать за тем, что делает агент.
Выгода: Полная прозрачность процесса. Если AI отклонится от плана, вы заметите это на раннем этапе.
Как применить:
- Шаг 1: Команда на внедрение — В чате AI напишите:
Implement the feature according to the OpenSpec proposal. Follow the specification exactly and do not add any extra features beyond what was defined.- Шаг 2: Визуализация прогресса — В отдельном терминале запустите команду для отслеживания статуса задач:
openspec viewРезультат: Вы получите интерактивный список задач, где отмечено, что уже готово, что в процессе, а что ожидает выполнения.
OpenSpec: ответы на частые вопросы
В: Чем OpenSpec лучше обычного промпта в Cursor? О: Обычный промпт не имеет структуры. OpenSpec заставляет AI сначала составить план (спецификацию), который вы одобряете. Это исключает ситуацию, когда AI «забывает» старый код или нарушает архитектуру проекта.
В: Нужно ли мне платить за OpenSpec? О: Нет, это бесплатный инструмент с открытым исходным кодом. Вам нужно оплачивать только подписку на ваш AI-агент (например, Cursor или Claude).
В: Можно ли использовать OpenSpec для уже существующих проектов? О: Да. При запуске openspec init в существующем проекте, AI просканирует текущий код и создаст project.md на основе того, что уже написано, помогая стандартизировать дальнейшую разработку.
В: Что делать, если AI предложил плохой дизайн в Proposal? О: Вы просто просите AI отредактировать файлы в папке changes до того, как начнется стадия implement. Это экономит время, так как переписать текстовое описание проще, чем исправлять сотни строк кода.
В: Какие AI-агенты поддерживаются официально? О: На данный момент это GitHub Copilot, Cursor, Windsurf и стандартные CLI-агенты. Список постоянно пополняется через обновления npm-пакета.
Конспект создан на основе видео «OpenSpec: The Future of AI Coding?» канала AI Master. Все права на оригинальный материал принадлежат авторам. Источник: https://www.youtube.com/watch?v=UtZyvtexJRM