Сначала исследуйте

/opsx:explore — ваш партнёр для обдумывания. Используйте её, когда проблема уже есть, а плана ещё нет. Команда изучает кодовую базу, помогает взвесить варианты и уточнить, чего именно вы хотите, ещё до написания первой строки кода. Когда картина прояснится, она передаст работу команде /opsx:propose.

Если вы усвоите из этой документации только одну привычку, пусть это будет она: если не уверены, сначала исследуйте, а потом формулируйте предложение.

Вот почему это важно. ИИ-ассистенты для программирования полны энтузиазма. Дайте расплывчатый запрос — и они уверенно создадут что-нибудь, но, возможно, не то, что вам нужно. Исследование помогает этого избежать. Это беседа без обязательств, в которой вы вместе с ИИ находите правильный подход, чтобы к моменту подготовки предложения вы предлагали именно то, что нужно.

Когда стоит исследовать

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

• Вы знаете проблему, но не решение. («Страницы работают медленно». «С авторизацией полный беспорядок». «Постоянно появляются дубли заказов».)
• Вы выбираете между подходами и хотите оценить компромиссы с учётом реального кода.
• Вы впервые работаете с кодовой базой и хотите понять, как что-то устроено, прежде чем это менять.
• Требования расплывчаты, и вы хотите уточнить их до принятия обязательств.
• Вам кажется, что объём работы отличается от того, каким он выглядит, и вы хотите определить его реалистично.

Пропускайте исследование, только если уже точно знаете, чего и как хотите. В этом случае сразу переходите к /opsx:propose.

Что команда делает (и чего не делает)

Explore — это диалог, а не генератор.

Команда умеет:

• Читать и искать в кодовой базе, чтобы отвечать на реальные вопросы.
• Сравнивать варианты и описывать компромиссы каждого.
• Рисовать схемы, чтобы сделать проектное решение понятнее.
• Помогать превратить расплывчатую идею в конкретный, реализуемый объём работ.
• Сохранять результаты исследования по вашей просьбе или после вашего согласия: создать каркас изменения с помощью openspec new change и записать указанные вами артефакты планирования либо обновить артефакты существующего изменения.
• Передавать работу команде /opsx:propose, когда вы будете готовы.

Команда не умеет:

• Писать или изменять код. Explore не пишет код ни при каких условиях, в том числе при сохранении результатов исследования.
• Проектировать или редактировать схемы и шаблоны. Их изменение — это отдельная работа, а не обдумывание.
• Самостоятельно создавать изменение или записывать артефакты. Команда ничего не записывает без вашей просьбы или согласия на её предложение; затем она создаёт только согласованные материалы и файлы настройки, необходимые для начала изменения (см. ниже).
• Навязывать сохранение результатов. Команда предлагает сохранить их, когда обсуждение оформилось в план, но решение остаётся за вами.

В этом и смысл. Исследование ничего не стоит и ни к чему вас не обязывает, пока вы сами не решите иначе. Можно изучить три тупиковых варианта, извлечь урок из каждого и только затем предложить тот, который выдержал проверку.

Команда уже доступна

Хорошая новость: /opsx:explore входит в профиль core по умолчанию вместе с командами propose, apply, update, sync и archive. Ничего включать не нужно. Если OpenSpec настроен в проекте, команда explore уже доступна в чате с ИИ. (Как и все команды /opsx:*, её нужно вводить в чате ассистента, а не в терминале. См. Как работают команды.)

Полный пример

Посмотрите, как расплывчатое опасение превращается в чёткое, реализуемое изменение.

Вы: /opsx:explore

ИИ:  Что вы хотели бы исследовать?

Вы: Иногда при оформлении заказа создаются дубликаты. Не знаю почему
    и не понимаю, как безопасно это исправить.

ИИ:  Изучу процесс оформления заказа...
     [изучает сервис заказов, обработчик вебхуков оплаты и логику
      отправки данных на клиенте]

     Вот что удалось выяснить. Дубликаты могут возникать по двум причинам:

     1. Клиент может отправить запрос дважды (двойное нажатие или повтор
        при медленной сети). Защиты от повторной отправки нет.
     2. Вебхук оплаты может сработать несколько раз, и обработчик
        каждый раз создаёт заказ. Ключа идемпотентности нет.

     Причина № 2 опаснее: из-за неё оплата и выполнение заказа могут
     произойти дважды.

     Есть три способа исправить ситуацию, примерно в порядке надёжности:
     - Ключ идемпотентности для эндпоинта создания заказа (устраняет обе причины)
     - Удаление дубликатов вебхука по идентификатору платёжного намерения (только причина № 2)
     - Защита от повторного нажатия на клиенте (только причина № 1, маскирует настоящую ошибку)

     Поскольку ваш код уже сохраняет идентификатор платёжного намерения,
     ключ идемпотентности потребует небольшого изменения и даст наибольший
     эффект. Подготовить план этой работы?

Вы: Да, давайте добавим ключ идемпотентности.

Вы: /opsx:propose add-order-idempotency-key

ИИ:  Создана папка openspec/changes/add-order-idempotency-key/ с предложением
     и дельта-спецификацией на основе результатов исследования. Можно приступать
     к реализации.

Обратите внимание, что произошло. Вначале было лишь: «что-то не так, и я боюсь это трогать». За двадцать секунд исследования появилась конкретная первопричина, три упорядоченных варианта, рекомендация с учётом существующего кода и чётко определённое изменение. Последующее предложение получилось точным, потому что сначала всё было обдумано.

Передача работы команде propose

Исследование само по себе ничего не архивирует. Когда будете готовы, просто начните изменение, и ИИ перенесёт контекст беседы в его артефакты.

explore  ──►  propose  ──►  apply  ──►  archive
 (обдумать)  (согласовать)  (создать)   (зафиксировать)

Можно попросить обычными словами («давай превратим это в изменение») или сразу выполнить /opsx:propose <name>. В любом случае результаты исследования станут основой предложения, а не пропадут в истории чата.

Можно также попросить explore создать изменение, не выходя из беседы: фраза «начни для этого изменение» создаст каркас папки, а «добавь ещё и предложение» запишет именно те артефакты, которые вы назвали. При создании каркаса также добавляются метаданные самого изменения и недостающие элементы верхнего уровня проекта (openspec/specs/, openspec/changes/archive/, config.yaml).

Результат будет таким же, как при передаче работы команде propose, но есть одно отличие: propose записывает весь набор артефактов, требуемый схемой для перехода к реализации, а сохранение создаёт только указанные вами артефакты.

Если вы используете расширенный набор команд, explore может передать работу команде /opsx:new, чтобы создавать артефакты по одному. См. Рабочие процессы.

Советы для эффективного исследования

• Опишите проблему, а не решение. «Вход в систему кажется медленным» даёт ИИ возможность провести исследование. «Добавь кэш Redis» заранее фиксирует решение, которое вы ещё не проверили.
• Попросите явно сравнить компромиссы. Вопрос «Какие недостатки есть у каждого варианта?» поможет получить более честное сравнение.
• Дайте ИИ сначала изучить код. Лучшее исследование начинается с того, что ИИ действительно смотрит на код, а не гадает. При необходимости укажите область, которую нужно изучить.
• Не страшно отказаться от идеи. Если исследование показало, что идея не стоит усилий, это тоже хороший результат: вы выяснили это с малыми затратами.
• Возвращайтесь к исследованию в ходе изменения. Застряли во время /opsx:apply? Можно отступить, изучить отдельную проблему и продолжить работу.

Честно о компромиссах

Что вы получаете: explore помогает заметить неверный путь в самый дешёвый момент — до того, как вы взяли на себя обязательства. Особенно полезна команда при работе с незнакомым кодом: способность ИИ читать и обобщать устройство системы может сэкономить вам целый день изучения.

Цена: немного терпения. Explore — это диалог, поэтому он медленнее, чем сразу запустить /opsx:propose и надеяться на лучшее. Если вы уже хорошо понимаете задачу, этот дополнительный шаг — лишняя нагрузка, и его можно пропустить.

Практическое правило: чем расплывчатее задача, тем полезнее explore. Чем яснее задача, тем проще сразу перейти к подготовке предложения.

Что дальше

• Команды: /opsx:explore: подробный справочник
• Рабочие процессы: исследование в повседневном цикле
• Примеры и рецепты: подробный пример исследования
• Начало работы: руководство по первому изменению, включая исследование