Спецификация прежде всего
Определите требования до написания кода.
OpenSpecСпецификация-ориентированная разработка для ИИ-ассистентов
Лёгкая спецификация для создания и управления проектами ИИ-ассистентов.
Добро пожаловать. Здесь собрано всё, что связано с OpenSpec.
OpenSpec помогает вам и вашему ИИ-ассистенту договориться о том, что нужно построить, до написания любого кода. Вы описываете изменения, ИИ составляет краткую спецификацию и список задач, вы оба рассматриваете один и тот же план, и затем начинается работа. Больше не нужно обнаруживать на середине процесса, что ИИ построил не то.
Если вы прочитаете только две страницы, прочитайте эти:
/opsx:propose (подсказка: в чате ИИ, а не в терминале). Почти каждый сталкивается с этим хотя бы раз.Вторая страница важнее, чем кажется. OpenSpec состоит из двух частей: командная строка, которую вы запускаете в терминале, и slash-команды, которые вы даёте ИИ-ассистенту. Знание того, что есть что, избавляет от самой распространённой путаницы.
Лучшая привычка, которую стоит выработать в первую очередь: когда вы не уверены, что строить, начните с
/opsx:explore. Это партнёр для размышлений без обязательств, который читает ваш код, взвешивает варианты и превращает размытую идею в конкретный план до создания каких-либо артефактов или кода. Руководство Сначала исследование обосновывает этот подход.
Я совсем новичок. Начните с Быстрого старта, затем просмотрите Основные концепции вкратце. Когда что-то кажется непонятным, FAQ и Глоссарий всегда рядом.
У меня есть проблема, но нет плана. Это самый распространённый случай, и для него есть специальный ответ: Сначала исследование. Используйте /opsx:explore, чтобы обдумать задачу с ИИ, прежде чем что-либо решать.
У меня большая существующая кодовая база. Вам не нужно документировать всё. Использование OpenSpec в существующем проекте показывает, как начать работу с реальным brownfield-кодом, не пытаясь переделать всё сразу.
Я просто хочу, чтобы это заработало. Установите, запустите openspec init, затем прочитайте Как работают команды, чтобы первая slash-команда попала в нужное место. Или передайте настройку вашему ассистенту с помощью промпта для ИИ-установки.
Я учусь на примерах. Страница Примеры и рецепты проходит реальные изменения от начала до конца: небольшая функция, исправление бага, рефакторинг, исследование.
ИИ только что составил план — что дальше? Прочитайте его. Рассмотрение изменений показывает двухминутную проверку, которая ловит ошибку, пока она ещё дёшево, а Написание хороших спецификаций рассказывает, из чего состоит план, достойный утверждения.
Я работаю в команде. OpenSpec в команде показывает, как изменение соотносится с веткой и pull request, и как коллеги рассматривают план до кода.
Я перехожу со старого рабочего процесса. Руководство по миграции объясняет, что изменилось и почему, и гарантирует, что ваша существующая работа в безопасности.
Я хочу адаптировать под процесс моей команды. Настройка охватывает конфигурацию проекта, пользовательские схемы и общий контекст.
Что-то сломалось. Устранение неполадок собирает реальные сбои, с которыми сталкиваются люди, с решениями.
| Документ | Что вы получите |
|---|---|
| Быстрый старт | Установка, инициализация и выполнение первого изменения от начала до конца |
| Сначала исследование | Используйте /opsx:explore, чтобы обдумать идею перед принятием решения |
| Как работают команды | Где выполняются slash-команды, что означает «интерактивный режим», терминал vs чат |
| Основные концепции вкратце | Вся ментальная модель на одной странице: спецификации, изменения, дельты, архив |
| Установка | npm, pnpm, yarn, bun, Nix, промпт для передачи настройки ИИ-ассистенту и как проверить, что всё работает |
| Документ | Что вы получите |
|---|---|
| Рабочие процессы | Общие паттерны и когда использовать каждую команду |
| Примеры и рецепты | Полные walkthrough реальных изменений, готовые к копированию |
| Написание хороших спецификаций | Как выглядят сильные требования и сценарии, и как правильно масштабировать изменение |
| Рассмотрение изменений | Двухминутная проверка составленного плана до написания кода |
| OpenSpec в команде | Как изменения соотносятся с ветками, pull request и ревью |
| Использование OpenSpec в существующем проекте | Внедрение OpenSpec на большой brownfield-кодовой базе |
| Редактирование и итерации изменения | Обновление артефактов, возврат назад, согласование ручных правок |
| Команды | Справочник по всем slash-командам /opsx:* |
| CLI | Справочник по всем командам openspec в терминале |
| Документ | Что вы получите |
|---|---|
| Концепции | Подробное объяснение спецификаций, изменений, артефактов, схем и архива |
| Рабочий процесс OPSX | Почему рабочий процесс гибкий, а не привязан к фазам, плюс подробный разбор архитектуры |
| Глоссарий | Все термины, определённые в одном месте |
| Документ | Что вы получите |
|---|---|
| Настройка | Конфигурация проекта, пользовательские схемы, общий контекст |
| Мультиязычность | Генерация артефактов на языках, отличных от английского |
| Поддерживаемые инструменты | Более 30 ИИ-инструментов, с которыми интегрируется OpenSpec, и куда попадают файлы |
| Обзор сообщества | Проекты и ресурсы, созданные с помощью и для OpenSpec |
| Документ | Что вы получите |
|---|---|
| FAQ | Быстрые ответы на самые частые вопросы |
| Устранение неполадок | Конкретные решения для конкретных сбоев |
| Руководство по миграции | Переход от устаревшего рабочего процесса к OPSX |
| Документ | Что вы получите |
|---|---|
| Хранилища: руководство пользователя | Планируйте в собственном репозитории, когда работа охватывает несколько репозиториев или команд |
| Контракт агента | Машиночитаемые интерфейсы CLI, которыми управляют агенты |
1. Установка npm install -g @fission-ai/openspec@latest
2. Инициализация cd your-project && openspec init
3. Исследование (в чате ИИ) /opsx:explore ← необязательно, но отличная привычка
4. Предложение (в чате ИИ) /opsx:propose add-dark-mode
5. Построение (в чате ИИ) /opsx:apply
6. Архивирование (в чате ИИ) /opsx:archiveШаги 1 и 2 выполняются в терминале. Остальные — в чате вашего ИИ-ассистента. Это разделение — единственное, что стоит запомнить, и Как работают команды объясняет, почему именно так. Шаг 3 необязателен, но начинать с /opsx:explore, когда вы не уверены, — самая ценная привычка.
openspec feedback "your message" — отправляет обратную связь прямо из терминала (открывает issue на GitHub).Нашли в документации что-то неверное, устаревшее или непонятное? Это баг. Создайте issue или PR. Улучшение документации — один из самых ценных вкладов, которые вы можете сделать.