🎯 О чём этот конспект: Разбор OpenSpec — мощного AI-фреймворка для разработки через спецификации. В отличие от хаотичного кодинга, этот инструмент заставляет AI сначала «подумать», составить план (спеку) и только потом внедрять изменения, что критически важно для сложных проектов и рефакторинга UI/UX.

👤 Кому будет полезно: Вайбкодерам и разработчикам, которые устали от галлюцинаций Claude/Cursor в больших проектах и хотят внедрить дисциплину в AI-разработку без потери скорости.

✨ Что получите: Пошаговый алгоритм настройки OpenSpec, методику миграции дизайн-систем с помощью скриншотов и браузерных агентов, а также систему автоматического ведения документации проекта, которая никогда не устаревает.

1. Категории AI-инструментов: Где место OpenSpec

Контекст: Автор разделяет современный AI-стек на три типа: Spec-driven (OpenSpec, GitHub Spec Kit), SDLC Enforcement (Obra, Agent Skills) и Autonomous Pipelines (BMAD, GetDone). OpenSpec относится к первому типу, где спецификация — это главный артефакт. Это лучший подход для вайбкодеров, так как он заставляет четко формулировать требования до написания кода, минимизируя ошибки на поздних этапах.

Выгода: Вы перестаете «кричать в пустоту», когда Claude Code делает не то, что нужно. Спецификация становится общим языком между вами и агентом.

Как применить:

• Шаг 1: Установка — Терминал — Установите пакет глобально или в проект:

npm install -g openspec

• Шаг 2: Инициализация — Терминал — Создайте структуру папок в корне вашего проекта:

openspec init

• Шаг 3: Выбор стратегии — Решите, нужен ли вам жесткий контроль (Spec-driven) или автономность. Для рефакторинга UI OpenSpec идеален.

Результат: Готовый к работе проект с настроенной структурой /openspec для хранения планов и спецификаций.

2. Фаза исследования (Explore) и устранение неопределенности

Контекст: Большинство ошибок происходит из-за того, что AI додумывает детали за вас. Команда explore запускает процесс «размышления», где агент анализирует контекст, находит противоречия в архитектуре и задает уточняющие вопросы до того, как тронет код. Это особенно важно при изменении дизайн-системы или информационной архитектуры.

Выгода: Экономия часов на переделку кода, который был написан на основе неверных предположений AI.

Как применить:

• Шаг 1: Запуск исследования — OpenSpec — Используйте команду для анализа задачи (например, миграции дизайна из Claude Design):

openspec explore "Migrate UI to the new design system from Claude Design screenshots"

• Шаг 2: Ответы на вопросы — Терминал — Агент подсветит «серые зоны» (например, как менять роутинг или токены). Ответьте на них текстом.
• Шаг 3: Получение артефактов — OpenSpec — После исследования вы получите три файла: proposal.md (что и зачем), design.md (как архитектурно) и tasks.md (пошаговый план).

Результат: Полностью согласованный план действий, где AI понимает все нюансы предстоящих изменений.

3. Визуальная валидация через MCP и Chrome

Контекст: Обычные AI-агенты хорошо пишут логику, но часто ошибаются в визуале (отступы, цвета, выравнивание). OpenSpec позволяет интегрировать визуальную проверку. Автор использует Claude Code с флагом Chrome, чтобы агент мог буквально «видеть» результат своей работы через браузер и сравнивать его с макетом.

Выгода: Вы получаете интерфейс, максимально близкий к дизайну (Pixel Perfect), без ручной правки каждого CSS-класса.

Как применить:

• Шаг 1: Подключение MCP — Claude Code — Убедитесь, что у вас подключен Chrome Browser Extension MCP.
• Шаг 2: Запуск с флагом — Терминал — Запустите Claude с доступом к браузеру:

claude code --with-chrome

• Шаг 3: Применение изменений — OpenSpec — Запустите процесс внедрения, указав ID проекта:

openspec apply [project-id]

Результат: Агент сам открывает браузер, проверяет верстку и исправляет ошибки, если они не соответствуют спецификации.

4. Итеративное планирование: New, Continue и Fast Forward

Контекст: OpenSpec предлагает гибкий воркфлоу для больших задач (например, создание бэкенда после фронтенда). Вместо одного гигантского изменения, которое может сломать проект, используется подход «нарезки» (slicing) на мелкие, контролируемые этапы.

Выгода: Высокая надежность при работе с критически важным кодом (бэкенд, базы данных).

Как применить:

• Шаг 1: Создание оболочки — OpenSpec — Начните новую ветку изменений:

openspec new "Build backend for public profiles"

• Шаг 2: Пошаговое продвижение — OpenSpec — Используйте continue для перехода от предложения к спецификации и задачам:

openspec continue

• Шаг 3: Ускорение — OpenSpec — Если план ясен и вы доверяете AI, используйте fast-forward для автоматического прохождения всех этапов:

openspec fast-forward

Результат: Контролируемый процесс разработки, где вы можете вмешаться на любом этапе.

5. Автоматическая документация и архивация (Sync)

Контекст: Главная проблема долгоживущих AI-проектов — документация быстро устаревает. OpenSpec решает это через команду archive и sync. После завершения задачи все изменения синхронизируются с «источником истины» в папке /openspec/specs.

Выгода: У вас всегда есть актуальное описание того, как работает каждая фича (User Stories, сценарии, требования). Если будущие изменения сломают старую логику, OpenSpec подсветит это.

Как применить:

• Шаг 1: Завершение фичи — OpenSpec — После успешного apply выполните архивацию:

openspec archive

• Шаг 2: Синхронизация документации — OpenSpec — Обновите основные спеки проекта:

openspec sync

• Шаг 3: Проверка — Проверьте папку /openspec/specs/, чтобы убедиться, что требования к базе данных или API обновились автоматически.

Результат: «Живая» документация, которая растет вместе с кодом и служит контекстом для будущих промптов.

FAQ

В: Чем OpenSpec принципиально лучше обычного промптинга в Cursor? О: Cursor часто сразу бросается писать код. OpenSpec заставляет создать промежуточный слой — спецификацию. Это как иметь архитектора перед строителями. Для простых задач это лишнее, но для рефакторинга или новых крупных фич это спасает от «каши» в коде.

В: Можно ли использовать OpenSpec вместе с другими инструментами, например Obra? О: Да, автор рекомендует чейнить (сцеплять) инструменты. Например, использовать Obra для создания Git Worktrees и TDD (Test Driven Development), а OpenSpec — для управления общей спецификацией и планом работ.

В: Сколько времени занимает процесс apply для крупного рефакторинга? О: В примере из видео полный рефакторинг UI нескольких страниц занял около 2 часов чистого времени работы агента в автоматическом режиме (или 3-4 часа с ручными подтверждениями).

В: Что делать, если AI в процессе apply пошел не туда? О: Благодаря тому, что у вас есть tasks.md, вы всегда видите, на каком шаге произошел сбой. Вы можете остановить процесс, запустить explore, обсудить проблему и обновить план, не теряя уже сделанную работу.

В: Как OpenSpec помогает избежать «черных лебедей» (непредвиденных багов)? О: Команда sync сравнивает новые изменения с существующими спецификациями. Если вы меняете логику закладок и это противоречит старой спеке, инструмент заставит вас примирить эти изменения (reconcile), предотвращая скрытые поломки.

Конспект создан на основе видео «The Best AI Coding Framework? (OpenSpec)» канала Tone Row. Все права на оригинальный материал принадлежат авторам. Источник: https://youtu.be/nFq4POtqom4