От идеи к спецификации вместе с агентом

Агент, которому дали «сделай сервис бронирования переговорок», сделает сервис бронирования переговорок — но свой, а не ваш. Каждое решение, которое вы не приняли, он примет сам, и узнаете вы об этом через неделю. В этом уроке превратим идею «Переговорок» в спецификацию, которую агент будет перечитывать на каждом шаге.

Почему спецификация живёт в репозитории

Для агента существует только то, что он может прочитать. Договорённость в чате или в голове после сжатия контекста или в новой сессии исчезнет. В статье OpenAI о harness engineering это сформулировано жёстко: знания, которых агент не видит в репозитории, для него не существуют.

Поэтому результат урока — два файла в git:

• docs/SPEC.md — что строим и по каким правилам;
• docs/PLAN.md — в каком порядке, срезами.

Шаг 1. Запишите идею как есть

Не полируйте. Десять строк в docs/idea.md честнее, чем красивый документ, придуманный за вас:

# Переговорки

Внутренний сервис брони переговорных для офиса (~70 человек, 4 комнаты).
Сейчас бронируем в общей таблице, постоянно накладки.
Хочу: зайти, увидеть занятость на сегодня и неделю, забронировать слот.
Нельзя забронировать занятое. Отменить можно свою бронь.
Офис-менеджер заводит комнаты (название, вместимость, есть ли экран).
Вход — по корпоративной почте.
Потом: подписка на календарь комнаты, уведомления в мессенджер.

Шаг 2. Интервью в режиме планирования

Документация Codex в разделе best practices советует для неясных задач сначала план: режим планирования включается командой /plan или Shift+Tab. Ещё один приём оттуда же — попросить агента сначала расспросить вас и оспорить допущения.

Запускаем в режиме только чтения — на этом шаге агенту нечего менять:

codex --sandbox read-only --ask-for-approval on-request

/plan Прочитай docs/idea.md. Это идея внутреннего сервиса.
Не пиши код. Проведи со мной интервью: задавай вопросы по 3–5 штук,
начиная с тех, от которых сильнее всего зависит архитектура.
Оспаривай мои допущения, ищи противоречия и пограничные случаи:
время и часовые пояса, одновременные брони, удаление комнат,
увольнение сотрудников, права офис-менеджера.
Когда вопросы кончатся, предложи структуру docs/SPEC.md.

Хорошее интервью вытаскивает то, о чём вы не подумали. В нашем случае агент спросил: с каким шагом бронировать (решили — 15 минут), можно ли бронить на полдня (максимум 4 часа), насколько вперёд (30 дней), что делать с бронями удаляемой комнаты (комнату не удаляем, а архивируем), кто видит названия чужих встреч (все сотрудники — сервис внутренний).

Отвечайте коротко и решайте сами. Если не знаете ответа, так и скажите — пусть вопрос попадёт в раздел открытых.

Шаг 3. Спецификация

Попросите агента собрать ответы в документ и записать его (теперь нужны права на запись, переключите режим через /permissions). Структура, которая хорошо работает для небольшого продукта:

# Переговорки — спецификация v0.1

## Цель
Сотрудник бронирует переговорную за 30 секунд без накладок.

## Роли
- Сотрудник: смотрит расписание, бронирует, отменяет свои брони.
- Офис-менеджер: всё то же + заводит, правит и архивирует комнаты,
  отменяет любые брони.

## Правила
- R1. Слот кратен 15 минутам, длина от 15 минут до 4 часов.
- R2. Бронировать можно с 08:00 до 21:00 по времени офиса (Europe/Moscow),
  не дальше 30 дней вперёд, не в прошлом.
- R3. Две активные брони одной комнаты не пересекаются — даже при
  одновременной отправке формы.
- R4. Отменить можно свою бронь; офис-менеджер — любую.
- R5. Архивная комната не принимает новые брони, старые видны.

## Сценарии и критерии приёмки
- S1. Бронь свободного слота
  Дано: комната «Байкал» свободна 14:00–15:00.
  Когда: сотрудник бронирует 14:00–15:00.
  Тогда: бронь видна в расписании всем сотрудникам.
- S2. Занятый слот
  Дано: 14:00–15:00 занято. Когда: бронируют 14:30–15:30.
  Тогда: отказ с понятным сообщением, бронь не создаётся.

## Не делаем в v1
Повторяющиеся брони, интеграцию с внешними календарями на запись,
мобильное приложение, оплату.

## Открытые вопросы
- Q1. Нужна ли бронь «от имени» другого сотрудника?

Нумерация правил (R1, S2) окупится позже: в промптах, тестах и ревью вы будете ссылаться на «R3», а не пересказывать правило.

Шаг 4. Проверка спецификации

Свежий взгляд полезен и документу. Откройте новую сессию — без истории интервью — и попросите прочитать спецификацию как скептик:

Прочитай docs/SPEC.md как опытный аналитик и тестировщик.
Найди: противоречия между правилами, сценарии без критериев приёмки,
правила, которые нельзя проверить тестом, пропущенные ошибки
(нет сети, двойной клик, истёкшая сессия). Ничего не исправляй —
дай список замечаний с номерами правил.

Часть замечаний будет шумом. Остальное вы вносите сами или поручаете агенту — но решение о том, что принять, за вами.

Шаг 5. План из вертикальных срезов

Последний шаг — разбить работу на срезы. Вертикальный срез проходит через все слои (база, API, интерфейс, тест) и даёт работающую функцию, пусть и маленькую. Подробно — в уроке о первом срезе.

# План

- [ ] 1. Каркас: монорепо, база в Docker, проверки (stack)
- [ ] 2. Срез: список комнат и бронь слота на сегодня, без входа (S1, S2, R1, R3)
- [ ] 3. Вход по корпоративной почте, брони привязаны к сотруднику (R4)
- [ ] 4. Расписание на неделю, отмена брони
- [ ] 5. Управление комнатами для офис-менеджера (R5)
- [ ] 6. Подписка на календарь и уведомления
- [ ] 7. Деплой на стенд и в продакшен

Этот файл агент будет читать в начале каждой сессии и отмечать выполненное.

Что решаете вы, а что агент

Агент хорошо задаёт вопросы, находит пограничные случаи и оформляет документ. Плохо — решает за бизнес: сколько можно бронировать, кто что видит, что отложить. Если в спецификации появилось правило, которого вы не произносили, — это догадка агента. Удалите её или примите осознанно.