🎯 О чём этот конспект: Разбор 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

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

FAQ

В: Чем 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