Конспект: OpenSpec: Полный гид по Spec-Driven разработке для AI-агентов — VibCoderZ - VibeCoderz

Загрузка...

🎯 О чём этот конспект: Разбор OpenSpec — легковесного инструмента для управления процессом разработки через спецификации (Spec-Driven Development). Инструмент решает проблему «потери контекста» в длинных чатах с AI и экономит токены, разбивая задачу на четкие документы, предложения по изменениям (proposals) и атомарные задачи.

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

✨ Что получите: Вы научитесь структурировать разработку так, чтобы AI-агент (например, Claude Code) работал по строгому плану, не галлюцинировал и успешно внедрял сложные фичи (графики, экспорт данных, темы оформления) с первой попытки.

1. Концепция Spec-Driven Development в OpenSpec

Контекст: При обычном промптинге требования часто «замыливаются» в истории чата, а AI тратит лишние токены на перечитывание всего контекста. OpenSpec внедряет методологию из трех шагов: черновик предложения (Draft), ревью задач (Review) и имплементация (Implement). Это превращает расплывчатые идеи в структурированные Markdown-файлы, которые служат «картой» для AI-агента. Такой подход минимизирует баги и позволяет четко отслеживать прогресс выполнения каждой подзадачи.

Выгода: Экономия токенов до 40-60% за счет передачи только нужного контекста и повышение точности выполнения сложных инструкций.

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

Шаг 1: Инициализация проекта — В терминале вашего проекта (например, Vite + React) выполните команду для создания структуры OpenSpec.
Шаг 2: Выбор агента — Выберите AI-инструмент, который вы используете (например, claude-code).
Шаг 3: Настройка окружения — OpenSpec создаст файл agent.md и папку .openspec/, где будут храниться все инструкции.

# Инициализация OpenSpec в корне проекта
npx openspec init

Результат: В проекте появится файл agent.md (инструкции для AI) и openspec/project.md (описание стека и конвенций).

2. Создание и управление предложениями по изменениям (Change Proposals)

Контекст: Вместо того чтобы просить AI «сделай мне инструмент для графиков», вы создаете Change Proposal. Это отдельная папка внутри .openspec/, которая содержит описание конкретной фичи и список задач. Это позволяет изолировать разработку разных функций и даже работать над несколькими фичами параллельно, не смешивая контекст.

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

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

Шаг 1: Заполнение деталей проекта — Попросите AI-агента заполнить основной файл проекта на основе текущего кода.
Шаг 2: Создание предложения — Используйте команду для описания новой фичи. Например, создание инструмента для построения графиков с поддержкой тем.
Шаг 3: Ревью задач — Проверьте созданный файл tasks.md. Если там есть лишние шаги (например, ненужные тесты), попросите AI их удалить.

# Пример команды для создания предложения внутри чата с агентом
/openspec add "Создать инструмент для построения столбчатых диаграмм с редактированием легенды, цветов и переключением тем"

Результат: Создана папка с файлами proposal.md (описание) и tasks.md (чек-лист), по которым агент будет работать.

3. Имплементация и мониторинг прогресса

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

Выгода: Прозрачный процесс разработки и возможность визуально подтвердить завершение каждого этапа.

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

Шаг 1: Запуск выполнения — Используйте команду apply, чтобы агент начал кодить по списку задач.
Шаг 2: Мониторинг — В отдельном окне терминала запустите визуализатор прогресса.
Шаг 3: Завершение — После выполнения всех задач проверьте результат в приложении.

# Запуск выполнения задач
/openspec apply
 
# Просмотр прогресса в реальном времени
npx openspec view
 
# Список всех активных изменений и количество задач
npx openspec list

Результат: Полностью реализованная фича с обновленным статусом в tasks.md.

4. Итеративное улучшение и архивация

Контекст: После реализации первой версии часто требуются правки (багфиксы или улучшения). OpenSpec позволяет архивировать выполненные задачи, чтобы они не занимали место в активном контексте, и создавать новые точечные предложения для исправлений. Это поддерживает чистоту проекта на протяжении всего цикла разработки.

Выгода: Чистый контекст для AI-агента, отсутствие «мусорных» файлов в активной работе.

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

Шаг 1: Архивация выполненного — Перенесите завершенную фичу в архив.
Шаг 2: Создание точечных правок — Создайте новые предложения для конкретных багов (например, исправить позицию легенды или улучшить разрешение экспорта).
Шаг 3: Параллельная работа — Вы можете создать несколько предложений одновременно и переключаться между ними.

# Архивация завершенного предложения
/openspec archive
 
# Создание предложения на исправление конкретного бага
/openspec add "Исправить позицию легенды: при выборе 'bottom' легенда должна уходить вниз"

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

FAQ

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

В: Какие AI-агенты поддерживаются? О: На данный момент лучше всего работает с Claude Code и Open Code. Список поддерживаемых агентов постоянно расширяется, так как инструмент активно развивается Fishian AI.

В: Можно ли использовать OpenSpec на уже существующем проекте? О: Да. При инициализации и первом заполнении project.md агент просканирует ваш текущий стек и файлы, чтобы адаптировать спецификации под существующий код.

В: Как OpenSpec экономит токены? О: Он не отправляет всю историю чата при каждом запросе. Агент фокусируется только на файле tasks.md и proposal.md текущей задачи, что значительно сокращает объем передаваемого текста.

В: Что делать, если AI неправильно составил список задач? О: Вы можете вручную отредактировать файл tasks.md в VS Code или промптом попросить агента: «Обнови задачи, убери пункт с интеграционными тестами и добавь шаг по оптимизации SVG».

Конспект создан на основе видео «OpenSpec: Spec-Driven Development Tool» канала Fishian. Все права на оригинальный материал принадлежат авторам. Источник: https://www.youtube.com/watch?v=cQv3ocbsKHY