Issue Intake Note: разбор тикета

1. Сырой тикет — это ещё не задача

Очень соблазнительно открыть issue, увидеть знакомые слова вроде error, 500, не работает — и сразу попросить Claude «посмотреть и пофиксить». Это очень человеческое желание, особенно когда хочется чувствовать себя продуктивным. Но именно тут и начинается маленькая инженерная катастрофа: кода никто не трогал, а вы уже лечите свою интерпретацию проблемы.

Посмотрите на типичный сырой тикет из Commerce OS:

# Issue #482

Не оформляется заказ, если корзина пустая.
На фронте показывается общая ошибка.
Ожидаем понятное сообщение для пользователя.
Наверное, надо добавить проверку в OrderController.
Скриншот и stack trace приложены.

На первый взгляд всё понятно. Но если вчитаться, быстро становится видно: факты, ожидания и чужая гипотеза о реализации свалены в кучу. Факт — заказ не оформляется. Факт — на фронте общая ошибка. Пожелание — понятное сообщение. А фраза про OrderController — уже не требование, а догадка автора, как именно чинить.

Именно поэтому сырой тикет нельзя считать готовой задачей. Он похож на голосовое в семейном чате: эмоций много, контекст утерян, кто виноват — непонятно. Ваша работа — не «поверить тикету», а аккуратно разобрать его на части. Тогда появляется артефакт для планирования: Issue Intake Note, по сути черновик TASK_SPEC.md, обогащённый контекстом тикета.

Если пропустить этот шаг, Claude почти наверняка начнёт помогать слишком усердно. Он увидит «добавить проверку в OrderController» и побежит менять контроллер, хотя проблема может жить в сервисе, в контракте API или в ожиданиях фронтенда. Fix сделан, коммит красивый, задача понята неправильно.

2. Содержимое issue под разбор

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

Разбор issue удобно держать в такой сетке:

Очень важно заметить: хороший intake почти никогда не бывает «полностью заполненным с самого начала». Если после чтения тикета у вас получился идеально ровный документ без единой assumption и без единого open question, обычно это значит одно из двух: либо тикет писал очень дисциплинированный человек, либо вы поверили слишком быстро.

Например, для нашего issue про пустую корзину пользовательский эффект можно зафиксировать уже сейчас: покупатель не может завершить checkout, интерфейс показывает бесполезную общую ошибку. Это важно, потому что технически баг — это NullPointerException, но с точки зрения бизнеса дело совсем в другом: плохой UX и непонимание, что дальше.

А вот формулировка «должно возвращаться понятное сообщение» уже просит уточнений. Что значит «понятное»? Нужен код ошибки? Ожидаем 400 Bad Request? Логировать как предупреждение? Нормальные open questions, стесняться их не надо.

3. Симптом, причина и «любимое решение автора»

Именно здесь чаще всего и захлопываются логические ловушки. Тикет почти всегда пишет про симптом, иногда — про желаемый результат, а иногда ещё и про «как это точно надо чинить». Свалите всё в одну кучу — получите кашу, из которой рождаются очень уверенные, но очень кривые планы.

Посмотрите на разницу:

Иногда автор тикета, QA или менеджер пишет решение просто потому, что так ему кажется логичным. Это не плохо, это даже полезно — даёт стартовую гипотезу. Но гипотеза — не контракт. Запишете «Добавить проверку в OrderController» как будто это уже требование — и незаметно подмените задачу: вместо «сделать поведение корректным» получится «изменить файл».

В нашем примере нормальная инженерная запись выглядит так:

Симптом: POST /api/orders с пустым items[] приводит к 500.
Кандидат в корневую причину: calculateTotal не обрабатывает empty list.
Статус: гипотеза, требует проверки.

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

Здесь же полезно помнить про ещё одно различие: must-have против nice-to-have. Для пустой корзины must-have — корректный ответ API и понятное поведение. А «заодно улучшить текст ошибки в трёх соседних сценариях» — это уже дополнительное улучшение, которое легко уводит в сторону. Отделяйте сразу.

4. Собираем Issue Intake Note на Commerce OS

Когда тикет уже разобран на составляющие, пора собирать это в документ: короткий, но полезный другому инженеру, ревьюеру и самому Claude. Хороший Issue Intake Note не пересказывает тикет, а превращает его в рабочую инженерную записку, из которой уже можно строить план.

Схема здесь простая:

flowchart LR
    A[Сырой тикет] --> B[Факты и evidence]
    B --> C[Assumptions и open questions]
    C --> D[Issue Intake Note]

Базовый шаблон выглядит так:

# Заметка о приёме issue

## Проблема
...

## Влияние на пользователя
...

## Известные доказательства
...

## Требования
...

## Предположения
...

## Открытые вопросы
...

## Вне области
...

## Заметки о рисках
...

А вот так этот документ может выглядеть уже в привязке к нашему issue:

# Заметка о приёме issue

## Проблема
POST /api/orders возвращает 500, если items[] пустой.

## Влияние на пользователя
Покупатель не может завершить оформление заказа и получает общую ошибку
без понятного объяснения.

## Известные доказательства
- stack trace указывает на OrderService.calculateTotal
- баг воспроизводится при POST /api/orders с пустым items[]

## Требования
- пользователь получает понятную реакцию на пустую корзину
- backend не падает с 500 в этом сценарии

## Предположения
- ожидаемый статус ответа должен быть 400
- пустая корзина считается невалидным checkout-сценарием

## Открытые вопросы
- нужен ли отдельный код ошибки EMPTY_CART?
- зависит ли фронтенд от текущего формата ошибки?

## Вне области
- редизайн корзины
- изменение логики checkout для непустой корзины

## Заметки о рисках
- изменение контракта ошибки может затронуть frontend

Заметьте: здесь нет ни одного преждевременного технического решения. Мы не написали «менять OrderController» и не притворились, будто знаем корневую причину. Зато есть всё для шага дальше.

И ещё один маленький, но важный нюанс. Assumptions и Open questions — это не «слабое место документа», а наоборот, признак зрелости. Плохой intake скрывает неопределённость. Хороший — честно её показывает.

5. Claude Code как ассистент анализа

На этом этапе Claude Code очень полезен, но только если вы правильно ставите ему задачу. Напишете «посмотри issue и исправь» — он почти наверняка перескочит через этап анализа. А нам сейчас нужно совсем другое: пусть Claude разберёт тикет, но не трогает файлы и не превращает гипотезы в якобы подтверждённые факты.

Удобный запрос может выглядеть так:

Открой issue #482 через issue-tracker.
Не редактируй файлы и не предлагай фикс.
Составь черновик Issue Intake Note.
Явно раздели:
1. подтверждённые факты,
2. assumptions,
3. open questions.
Если в issue есть предложенное решение, пометь его как hypothesis.

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

Если у вас уже есть skill issue-analysis, можно использовать его как стандартную оболочку для такого разбора. Точные команды и способы вызова могут немного отличаться в вашей версии среды, но привычка остаётся той же: подтянуть issue в контекст, собрать черновик intake, потом читать его как инженер, а не как стенограмму святого оракула.

Иногда полезно сделать второй проход свежим взглядом — например, через reviewer-agent. Не для code review, а именно для проверки качества intake:

Проверь черновик Issue Intake Note.
Найди места, где assumption выдана за факт.
Отметь, если не хватает user impact, out of scope или risk notes.
Файлы не редактируй.

Здесь Claude выступает уже не как автор, а как критик. Это хороший паттерн: один AI собирает материал, второй проверяет границы. Но финальное решение всё равно остаётся за вами. Reviewer пишет «Вероятно, нужен статус 400» — это не делает 400 истиной. Это всего лишь повод либо подтвердить дальше, либо зафиксировать как assumption.

Полезно также помнить, что intake — не место для длинного технического расследования. Если Claude начинает расписывать полстраницы про архитектуру сервиса и возможный рефакторинг, мягко верните его обратно: сейчас мы не лечим систему, а наводим порядок во входящем хаосе.

6. Признаки готового к планированию intake

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

Есть и ещё один, почти бытовой тест. Если после чтения Issue Intake Note другому инженеру не хочется спросить «подождите, а что вообще имеется в виду?» — значит, вы уже сильно продвинулись. А если документ читается отдельно от тикета, без беготни глазами туда-сюда, — значит, он действительно работает как входной инженерный артефакт.

В этот момент задача перестаёт быть эмоциональной заметкой в трекере и становится черновиком инженерного контракта. Дальше задача идёт не сразу в план, а в read-only investigation: пройтись по коду, проверить маршрут, тесты и точки изменения, чтобы предположения перестали быть догадками. План появляется уже после этого прохода по фактам.