Источники контекста и пакет доказательств

1. Объяснить словами — мало

Первая ошибка, которую вы легко совершите: решить, что главное — «хорошо описать проблему». Лучше, чем «почини что-нибудь», но мало. Claude поймёт цель, выдвинет гипотезу — и начнёт додумывать недостающие факты, а догадка заканчивается ремонтом не той стены.

Оператор Commerce OS пишет: «Иногда возврат оформляется странно». Два возврата? Неверная сумма? При двойном клике? Без фактов Claude работает не с проблемой, а с вашей интонацией.

Для нетривиальной задачи нужен пакет доказательств — факты, на которые опираются и при анализе, и при проверке.

Плохо:
«Почини возвраты. Иногда там что-то ломается».

Лучше:
«В Commerce OS при повторном нажатии на кнопку "Запросить возврат"
иногда создаются два запроса вместо одного. Ниже приложены шаги
воспроизведения, лог сервера, скриншот и список затронутых файлов.
Сначала помоги понять, каких фактов еще не хватает для плана».

Во второй формулировке вы ничего не чините — готовите почву для анализа. Это спасает от диффов «почти правильно, только сломалось ещё в трёх местах».

2. Контекст и evidence — не одно и то же

Контекст — всё, что Claude использует в работе. Evidence — то, что подтверждает ваши утверждения и итоговую корректность. Контекст помогает думать, evidence — доказывать.

Файл компонента, лог, описание бага, тикет — контекст. Evidence внутри него не всё. Доказательная сила у конкретного: шаги воспроизведения, фрагмент лога, падающий тест, скриншот неверного поведения, файл, где оно живёт. Переписка «кажется, проблема в бэкенде» — гипотеза.

Третье слово — шум: нерелевантное в контексте — логи целиком, полрепозитория «на всякий случай», старые гипотезы, чужие скриншоты, устаревшая документация. Claude попытается это переварить, но вежливость модели — не качество результата.

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

3. Из чего собирается пакет

Пакет компактный и отвечает на один вопрос: какие факты нужны для этой задачи. Мелкая проблема — три пункта, баг на стыке фронта и бэка — семь-восемь.

Ниже — удобная таблица, которую можно держать в голове при сборе evidence.

Ключевой момент в том, что bundle всегда собирается под конкретную цель. Если у вас UI-проблема в форме регистрации, огромный серверный лог за сутки почти наверняка лишний. Если у вас дублируется возврат средств, один красивый скриншот интерфейса не спасёт: понадобятся лог запроса, описание воспроизведения и понимание, где проходит вызов на бэкенд.

Есть ещё одна важная привычка: не смешивайте evidence с «всем, что, возможно, когда-нибудь пригодится». Инженерный пакет фактов — это не чулан. Если вы не можете объяснить, зачем конкретный файл или лог попал в bundle, скорее всего, он там пока не нужен.

4. Пример на Commerce OS

Чтобы это не оставалось красивой теорией, давайте приземлимся на наш сквозной проект. Представим, что в Commerce OS оператор поддержки открыл заказ, нажал кнопку «Запросить возврат», интерфейс чуть задумался, и после этого в системе появились два возврата вместо одного. Пользователь не обрадуется, финансист — тем более, а вы внезапно узнаете, что у слова «странно» есть денежный эквивалент.

Если действовать на эмоциях, очень хочется сразу сказать Claude: «Посмотри всё, связанное с refunds, и почини». Но правильнее остановиться и собрать evidence. В хорошем bundle для такой задачи почти наверняка окажутся шаги воспроизведения, скриншот или запись двойного нажатия, лог сервера с двумя запросами, файл кнопки на фронтенде, контроллер или сервис на бэкенде, а ещё похожее место в проекте, где защита от повторного запроса уже есть. Например, в отмене заказа или в повторной отправке письма.

Именно в этот момент полезно завести отдельный файл EVIDENCE_LOG.md. Он не должен быть диссертацией. Его задача — собрать в одном месте факты, которые потом переживут и вашу память, и несколько сообщений в чате, и желание Claude «сейчас быстро всё исправить».

# EVIDENCE_LOG.md

## Задача
При повторном нажатии на кнопку "Запросить возврат" иногда создаются два refund-запроса.

## Воспроизведение
1. Открыть заказ `A-10482`
2. Нажать кнопку два раза подряд
3. В логах появляются две записи на один заказ

## Факты
- фронтенд: `RefundButton.tsx`
- бэкенд: `RefundController.java`
- лог: `logs/refund-duplicate.log`
- похожая защита уже есть в `CancelOrderService.java`

Что здесь важно? Во-первых, файл отвечает на вопрос «что именно не так» без литературных украшений. Во-вторых, в нём уже есть мост между симптомом и кодом. В-третьих, такой файл удобно использовать как чистую точку входа в реализацию: в следующую сессию попадут уже собранные факты, а не вся история расследования.

5. EVIDENCE_LOG.md как рабочий инструмент

Когда разработчик впервые слышит «сделай отдельный Markdown-файл», он иногда начинает страдать заранее. Кажется, будто сейчас появится ещё один ритуал ради ритуала. Но у EVIDENCE_LOG.md есть очень практический смысл: он переводит разрозненные наблюдения в форму, с которой можно работать повторно. Сегодня вы собираете факты. Через час на его основе формулируете более сильный TASK_SPEC.md. Сам TASK_SPEC.md обычно хранит только краткую выжимку и ссылку на EVIDENCE_LOG.md, а не дублирует его целиком. Завтра по этому же файлу другой человек понимает, что вообще происходило. Это не бюрократия — это упаковка мысли.

Удобно держать простое правило: EVIDENCE_LOG.md хранит факты и открытые вопросы задачи, а TASK_SPEC.md — короткий контракт на изменение. Один поддерживает другой, но не дублирует его построчно.

Важно, что EVIDENCE_LOG.md — файл на одну задачу, а не дневник всего проекта. Если в нём оказывается полжизни репозитория, значит, вы ведёте не лог задачи, а археологию. Хороший журнал короткий, жёстко связан с проблемой и помогает ответить на четыре вопроса: что ломается, как это воспроизвести, где вероятная зона изменений и чем потом проверять результат.

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

Хороший EVIDENCE_LOG.md ещё и дисциплинирует разговор с Claude. Когда факты лежат в одном месте, вам проще сказать: «Вот данные. Сначала помоги найти пробелы, а не редактируй код». В таком режиме Claude обычно работает заметно аккуратнее.

6. Claude — уточняющий, а не исправляющий

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

Например, можно писать так:

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

В такой формулировке есть сразу две хорошие вещи. Первая — жёсткая граница «не редактируй код». Вторая — просьба не гадать, а назвать пробелы в доказательной базе. Это резко снижает риск, что Claude радостно побежит «помогать» на основе полуфактов.

На этом шаге полезно сделать паузу и отдельно зафиксировать собранное. Для крупной задачи этого уже достаточно, чтобы следующая сессия реализации стартовала от уже собранного evidence, а не от длинной переписки с боковыми гипотезами. У вас остаётся компактный документ, который можно дать Claude, себе или ревьюеру без пересказа всей истории расследования.

7. Полезного контекста становится слишком много

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

Самые частые источники шума легко узнать. Огромный лог за полдня, хотя баг воспроизводится на одном конкретном запросе. Десять файлов «рядом», хотя реально проблема сидит в двух. Устаревшая документация из папки old/. Переписка коллег в духе «мне кажется, это база тормозит». Скриншоты из трёх разных багов, потому что «тоже что-то похожее было». Всё это выглядит как забота о полноте картины, а на деле размывает фокус.

Здесь полезно задавать себе простой вопрос: если убрать этот факт из bundle, станет ли хуже понимать проблему или проверять решение? Если нет, скорее всего, это не evidence, а шум.

Иногда эту разницу хорошо видно даже в формулировке запроса.

Шумно:
«Вот весь модуль orders, три старых лога, дамп ответа API за неделю
и пять скриншотов. Посмотри, что там не так».

Чище:
«Вот шаги воспроизведения, лог одного неудачного запроса, скриншот
неверного состояния и три файла, где проходит обработка возврата.
Сначала скажи, каких фактов еще не хватает».

Во втором варианте у Claude есть нормальная рабочая поверхность. В первом — ощущение, будто его попросили «разобраться во всей жизни». А это уже задача не для инструмента, а для литературного романа в трёх томах.

8. Что в пакет не кладут

Есть ещё один важный слой гигиены, который нельзя игнорировать даже в учебных задачах. Evidence должен быть не только релевантным, но и безопасным. Если бездумно копировать в журнал всё подряд, очень легко притащить туда секреты, токены, личные данные пользователей, содержимое .env или куски боевых логов, которые вообще не должны гулять по сессиям.

Хорошая практика здесь простая: в evidence попадают только те данные, которые реально нужны для анализа и проверки, и только в очищенном виде. Если в логе есть токен, его надо замаскировать. Если в запросе есть личный e-mail клиента, чаще всего достаточно фиктивного значения или частичного скрытия. Если проблема связана с конфигом, почти всегда можно показать безопасный фрагмент или .env.example, а не настоящий секрет.

Это, кстати, ещё один аргумент в пользу отдельного EVIDENCE_LOG.md. Когда факты собираются в файл осознанно, вы чаще замечаете, что именно копируете. А вот в режиме «насыпал всё в чат» секреты утекают удивительно быстро и очень буднично. Потом обычно наступает тот неловкий момент, когда приходится делать вид, будто вы всегда и хотели заняться срочной санитарной обработкой логов.

9. Когда evidence достаточно

На практике самый частый вопрос не «как собрать evidence», а «когда остановиться». Потому что собирать факты можно долго, особенно если баг неприятный, а проект большой. Здесь помогает очень земной критерий: пакет evidence можно считать достаточным, когда вы уже можете без гадания ответить на несколько опорных вопросов: что именно ломается; как это воспроизвести; где проходит вероятная зона изменений; по каким признакам мы поймём, что исправление сработало.

Если одного из этих столбов нет, спешить в реализацию рано. Если все четыре на месте, дальше уже не нужно изображать детектива дольше необходимого. У вас есть рабочая основа. Можно переставать собирать всё подряд, фиксировать bundle в EVIDENCE_LOG.md и двигаться к задаче, которую потом действительно получится принять по фактам, а не по ощущению «ну теперь вроде выглядит лучше».