Урок 15.7. Explore First: продумывание изменения до proposal

Зачем это нужно

С этого урока в модуле начинается блок повседневной практики. Блоки A и B позади: урок 15.2 провел первое изменение по полному циклу, урок 15.3 дал ментальную модель спецификаций и артефактов, уроки 15.5-15.6 - справочники слэш-команд и CLI. Дальше разбирается, как команды сочетаются в реальной работе, и первая тема - /opsx:explore: документация OpenSpec настаивает на нем настолько, что предлагает забрать из всей документации именно эту привычку.

В уроке 15.2 explore уже появлялся как необязательный первый шаг цикла изменения. В обзоре 2.10 он не упоминался вовсе: это рабочая механика инструмента, а не витринная функция. Здесь explore разобран целиком: когда он нужен, что именно делает, чего не делает никогда и как передает эстафету в proposal (предложение об изменении).

Проблема, которую решает explore, знакома каждому, кто работал с coding-агентом. AI-ассистенты нетерпеливы: задайте вопрос расплывчато - и агент уверенно построит что-то, только, возможно, не то, что вам было нужно. Explore - лекарство от этого. Это разговор без ставок, в котором вы и агент вместе находите верное решение, чтобы к моменту proposal предлагать уже проверенную вещь, а не первую пришедшую в голову.

Урок устроен не как справочная строка, а как разбор привычки: сначала критерии «когда explore нужен», потом жесткие границы «что он делает и чего не делает», затем полный пример и правила передачи эстафеты. В уроках 15.8 и 15.9 explore станет элементом готовых workflow-паттернов - здесь он разобран сам по себе.

Основная идея

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

Сам принцип называется Explore First. Если забрать из документации OpenSpec одну привычку, то вот она: не уверены - сначала explore, потом propose. Explore ничего не стоит и ни к чему не обязывает, пока вы сами не скажете иначе. Вы можете исследовать тупиковые варианты, отбросить их - и никто не заставит вас за них отвечать.

Почему это важно, легче всего увидеть на контрасте. Требование, сформулированное наспех («сделай красиво», «почини медленную страницу»), агент исполняет уверенно и буквально - и получает результат, не совпадающий с тем, что было нужно. Explore вставляет между расплывчатой мыслью и обязывающим proposal ступень размышления: сначала диагностика и варианты, потом - обязательства.

Когда нужен explore, а когда - сразу propose

Explore оказывается правильным первым шагом чаще, чем кажется. Ниже - пять сигналов из документации; достаточно одного, чтобы начать с explore вместо propose.

Известна проблема, но неизвестно решение

Классические примеры прямо из документации:

Ни одна из этих формулировок не содержит плана действий - explore его строит: сначала диагноз (что именно медленно, что именно ломается), потом варианты решения, привязанные к вашему коду.

Выбор между подходами

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

Незнакомая кодовая база

Если вы новичок в проекте и должны понять, как что-то устроено, прежде чем это менять, explore читает код и суммирует его устройство. Это дешевле, чем разбираться вручную по файлам, и безопаснее, чем менять вслепую.

Расплывчатые требования

Когда требования еще не заострены, explore помогает уточнить их до того, как вы возьмете обязательства. Расплывчатое требование, прошедшее через proposal, превращается в расплывчатый код; explore дает шанс отловить неточность на стадии разговора.

Сомнения в масштабе

Если вы подозреваете, что работа больше или меньше, чем кажется, explore позволяет оценить масштаб честно, а не оптимистично. Оценка «на глазок» вредит в обе стороны: маленькую задачу раздувают, большую - начинают и бросают на полпути.

Единственный случай пропустить explore

Пропустить explore стоит в одном случае: вы точно знаете и что хотите, и как этого добиться. Тогда переходите сразу к /opsx:propose - справочник команды в уроке 15.5.

Полезно различать формулировку проблемы и формулировку решения - explore работает с первой:

Левая колонка дает агенту пространство для исследования. Правая - заранее обязывает вас ответом, который вы еще не проверили на своем коде. Подробнее об этом - в разделе «Советы для хорошего exploration» ниже.

Что explore делает - и чего не делает

Explore - это разговор, а не генератор. Граница между «делает» и «не делает» проходит по принципу: размышлять - да, обязывать - нет.

Что делает

• Читает и ищет по кодовой базе, отвечая на реальные вопросы, а не догадываясь. Это ключевое отличие от «спросить у модели» без контекста: explore смотрит ваш код.
• Сравнивает варианты и называет компромиссы каждого - не только достоинства.
• Рисует диаграммы, делающие замысел наглядным: архитектуру, поток данных, варианты решения.
• Помогает сузить расплывчатую идею до конкретной, реализуемой области работы: от «что-то не так» к «вот эта причина и вот этот план».
• Фиксирует результаты исследования (capture), когда вы просите или принимаете предложение агента: создает каркас изменения через openspec new change, записывает названные вами артефакты планирования - либо обновляет артефакты уже существующего изменения.
• Передает эстафету в /opsx:propose, когда вы готовы перейти от размышления к обязательствам.

Чего не делает

• Не пишет и не меняет код. Никогда и ни на каком пути - включая capture. Размышление о коде и изменение кода - разные стадии.
• Не проектирует и не редактирует ваши схемы артефактов и шаблоны. Их формирование - это уже изменение, а не размышление.
• Не начинает изменение и не пишет артефакты по собственной инициативе. Пока вы не попросите или не согласитесь на предложение агента, не записывается ничего. После согласия записывается ровно то, о чем договорились, плюс служебные файлы, необходимые для старта изменения (они разобраны ниже, в разделе о capture).
• Не подталкивает вас к фиксации. Агент предложит зафиксировать, когда мысль оформится, - но решение всегда остается за вами.

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

Сведем границы в одну таблицу:

Что меняется на диске, а что - нет

Самый частый практический вопрос про explore: «что он создаст в моем репозитории?». Ответ зависит от того, дошли ли вы до capture.

Обычный explore, завершенный без фиксации, не оставляет следов: разговор живет в чате, репозиторий не меняется вообще - ни код, ни openspec/.

После capture по вашей просьбе картина такая:

openspec/
├── changes/
│   └── <имя изменения>/
│       ├── ... ровно те артефакты, которые вы назвали
│       └── ... метаданные изменения (создает каркас)
├── specs/                  ← досоздается, если не было
├── changes/archive/        ← досоздается, если не было
└── config.yaml             ← досоздается, если не было

Существующее содержимое не перезаписывается - досоздается только недостающее. Код остается нетронутым и после capture: его пишет /opsx:apply, не explore.

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

Explore уже установлен

Хорошая новость: /opsx:explore входит в профиль по умолчанию core - рядом с propose, apply, update, sync и archive:

профиль core:  propose  apply  update  sync  archive  explore

Включать ничего не нужно: если OpenSpec установлен и инициализирован в проекте (урок 15.1), explore уже доступен в чате вашего AI-ассистента.

Как и все команды /opsx:*, explore вводится не в терминале, а в чате агента - в том же окне, куда вы обычно пишете «добавь фичу». Это разделение двух интерфейсов - самая частая ошибка первых дней; оно разобрано в уроке 15.4.

Полный пример: от смутного беспокойства до точного изменения

Проследите, как расплывчатое опасение превращается в острое, реализуемое изменение. Диалог переведен; команды, пути и технические термины остаются как есть.

Вы:  /opsx:explore

AI:  What would you like to explore?

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

AI:  Позвольте копнуть путь оформления заказа...
     [агент читает order service, обработчик payment webhook
     и клиентскую логику отправки заказа]

     Вот что я нашел. Дубликат может возникнуть двумя способами:

     1. Клиент может отправить заказ дважды (двойной клик,
        повторная отправка при медленной сети). Ничто не
        защищает от повтора.
     2. Payment webhook может сработать больше одного раза,
        и обработчик каждый раз создает заказ. Ключ
        идемпотентности (idempotency key) отсутствует.

     Причина #2 - опасная: она может дважды списать деньги
     и дважды исполнить заказ.

     Три способа исправить, примерно по возрастанию надежности:
     - Idempotency key на endpoint создания заказа
       (закрывает обе причины)
     - Дедупликация webhook по payment-intent id
       (закрывает только #2)
     - Debounce на клиенте (закрывает только #1,
       маскирует реальный баг)

     Поскольку ваш код уже хранит payment-intent id, вариант
     с idempotency key - небольшое изменение с максимальной
     отдачей. Составить его план?

Вы:  Да, делаем idempotency key.

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

AI:  Created openspec/changes/add-order-idempotency-key/
     с proposal и delta spec, основанными на том, что мы
     только что нашли. Готово к реализации.

Разбор диалога

Отправная точка - «что-то не так, и я боюсь это трогать». Двадцать секунд исследования превратили ее в следующее:

1. Названные первопричины. Не «духи в машине», а две конкретные механики возникновения дубликата - с оценкой, какая из них опаснее: повторный webhook может дважды списать деньги и дважды исполнить заказ.
2. Три варианта решения, ранжированных по надежности. Для каждого указано, какую причину оно закрывает - и один вариант прямо помечен как маскирующий реальный баг, а не устраняющий его.
3. Рекомендация, привязанная к существующему коду. «Ваш код уже хранит payment-intent id» - поэтому idempotency key именно здесь оказывается небольшим изменением с максимальной отдачей. Это не абстрактное «best practice», а вывод из прочитанного кода.
4. Точное имя изменения. add-order-idempotency-key готово для /opsx:propose - придумывать формулировку заново не нужно.

Связь между причинами и вариантами решения наглядно видна на диаграмме:

Proposal, который следует за таким разговором, получается острым, потому что мышление произошло раньше него: агент создает openspec/changes/add-order-idempotency-key/ с proposal и дельта-спецификацией (delta spec), основанными на том, что только что нашли, - а не на догадках.

Инженерный вывод курса: имя изменения add-order-idempotency-key появилось не из промпта, а из анализа кода. Формулировка задачи «не знаю почему и не знаю, как безопасно» не содержит ни слова о решении - и это правильно: выбор решения остался за вами, но стал осознанным. Заметьте также, что агент честно пометил слабейший вариант («маскирует реальный баг») вместо того, чтобы представить все три равными - именно поэтому стоит просить называть компромиссы вслух.

Передача эстафеты в propose

Explore никуда не архивируется: его результат - сам разговор, а не артефакт. Когда вы готовы, вы просто начинаете изменение, и агент переносит контекст беседы в артефакты.

Скажите обычными словами - «оформим это как изменение» - или выполните /opsx:propose <name> напрямую. В обоих случаях только что выполненное исследование становится основой proposal, а не выброшенным чатом: выводы, названия причин и выбранное решение попадают в артефакты нового изменения.

Capture: фиксация внутри explore

Можно попросить explore зафиксировать изменение, не покидая разговора:

Вы:  Оформи для этого изменение - и запиши proposal.

AI:  [создает каркас openspec/changes/<имя>/ через openspec new change,
     записывает названный артефакт и метаданные изменения]

Фраза вида «оформи для этого изменение» (start a change for this) создает каркас каталога изменения, а «запиши и proposal» (write the proposal too) - записывает ровно те артефакты, которые вы назвали. Каркас при этом создает собственные метаданные изменения и досоздает то, чего проекту не хватает на верхнем уровне: openspec/specs/, openspec/changes/archive/, config.yaml - полный вид разобран выше, в разделе «Что меняется на диске».

Структура артефактов изменения (proposal, design, tasks, specs) разобрана в уроке 15.3; каркас использует именно ее.

Capture или propose: в чем разница

Оба пути ведут в одну точку - у изменения появляются артефакты. Разница одна, но существенная:

Если вы используете расширенный набор команд, explore может передать эстафету не в /opsx:propose, а в /opsx:new - для пошагового создания артефактов. Расширенные пути и их сочетания разобраны в уроке 15.8.

Советы для хорошего exploration

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

Честные компромиссы

Что приобретаете. Explore ловит неверные повороты в самый дешевый из возможных моментов - до того, как вы взяли хоть какое-то обязательство. Он особенно силен в незнакомом коде: способность агента прочитать и суммировать систему экономит вечер ручного археологического копания по файлам.

Чем платите. Терпением. Explore - это разговор, поэтому он медленнее, чем выстрелить /opsx:propose и надеяться. Для работы, которую вы действительно уже понимаете, лишний шаг - чистые издержки, и его следует пропускать.

Два типовых сценария для сравнения:

Задача понятна насквозь:
  /opsx:propose  →  сразу рабочий план
  (explore был бы лишним шагом)

Задача расплывчата:
  /opsx:explore  →  диагноз, варианты, выбор  →  /opsx:propose
  (ошибка ловится в разговоре, а не в коде)

Правило большого пальца: чем расплывчатее задача, тем больше explore окупается. Чем яснее задача, тем больше оснований идти сразу в propose.

Инженерный вывод курса: explore - самая дешевая форма ревью в этом workflow. Пока не написано ни кода, ни обязательных артефактов, ошибка стоит одну итерацию диалога; после /opsx:propose она стоит правки плана; после /opsx:apply - правки кода и спецификаций. Explore не ускоряет каждый отдельный шаг - он снижает цену предотвращенной ошибки на порядок.

Практика

Задание выполняется в тестовом проекте из урока 15.2. Подойдет и любой ваш проект, где есть знакомая досадная проблема без готового решения.

1. Сформулируйте проблему без решения: не «добавь debounce на кнопку отправки», а «иногда форма отправляется дважды». Проверьте себя: в формулировке не должно быть названия конкретного механизма исправления.
2. Введите в чате агента /opsx:explore и опишите проблему.
3. Когда агент предложит варианты, спросите: «какие минусы у каждого варианта?» - и сравните ответ с первым сравнением: стали ли формулировки честнее.
4. Выберите вариант. На предложение зафиксировать результат ответьте отказом и проверьте состояние репозитория: в openspec/changes/ не должно появиться ничего нового.
5. Согласитесь на фиксацию или выполните /opsx:propose <name> - и посмотрите, что появилось на диске.
6. Если просили записать только proposal - проверьте, что кроме него и служебных файлов каркаса (openspec/specs/, openspec/changes/archive/, config.yaml, метаданные изменения) ничего не создано, а код не изменен.
7. Для второго прохода возьмите незнакомую часть собственного проекта: попросите explore объяснить, как она устроена, прежде чем что-либо менять, - это третий сигнал из раздела «Когда нужен explore».

Краткое резюме

/opsx:explore - команда для стадии «проблема есть, плана нет»: агент читает кодовую базу, сравнивает варианты и превращает расплывчатую идею в конкретный план до того, как написан proposal и тем более код.

• Привычка Explore First: не уверены - сначала explore, потом propose; уверены насквозь - сразу /opsx:propose.
• Сигналы для explore: известна проблема, но не решение; выбор между подходами; незнакомый код; расплывчатые требования; сомнения в масштабе работы.
• Explore - разговор, а не генератор: читает код, называет компромиссы, сужает идею; никогда не пишет код и не создает артефакты по собственной инициативе.
• Capture - фиксация по явной просьбе: каркас через openspec new change плюс ровно названные вами артефакты; propose пишет полный набор по схеме.
• Explore входит в профиль core, вводится в чате агента, а не в терминале.
• Чем расплывчатее задача, тем больше выгода от explore; для понятных задач - чистые издержки.

Вопросы для самопроверки

1. Назовите пять ситуаций, в которых explore - правильный первый шаг, и единственную, в которой его стоит пропустить.
2. Что explore никогда не делает, даже когда вы просите о capture?
3. По какой причине и с чьего согласия explore записывает артефакты, и что именно записывается - а что остается за рамками?
4. В чем разница между передачей эстафеты в /opsx:propose и capture внутри explore? Что пишет propose, а что - capture?
5. Почему совет «принесите проблему, а не решение» делает исследование качественнее? Приведите пару плохой и хорошей формулировки.
6. Как связаны расплывчатость задачи и выгода от explore? Когда explore превращается в чистые издержки?

Что дальше

Урок 15.8 - «Workflow-паттерны: когда какую команду применять» - собирает команды в комбинации под типовые ситуации: новая фича, багфикс, рефакторинг, небольшая правка - и показывает, как explore, propose, apply и archive связаны в повседневном цикле. Полные walkthrough-примеры с explore разобраны в уроке 15.9, точный справочник команды - в уроке 15.5.

Источники

• https://github.com/Fission-AI/OpenSpec/blob/main/docs/explore.md