Джерела контексту і пакет доказів

1. Пояснити словами — замало

Перша помилка, яку ви легко припуститеся: вирішити, що головне — «добре описати проблему». Краще, ніж «полагодь щось», але замало. Claude зрозуміє мету, висуне гіпотезу — і почне додумувати відсутні факти, а здогадка закінчується ремонтом не тієї стіни.

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

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

Погано:
«Полагодь повернення. Інколи там щось ламається».

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

У другому формулюванні ви нічого не лагодите — готуєте ґрунт для аналізу. Це рятує від дифів «майже правильно, тільки зламалося ще в трьох місцях».

2. Контекст і evidence — не одне й те саме

Контекст — усе, що Claude використовує в роботі. Evidence — те, що підтверджує ваші твердження та підсумкову коректність. Контекст допомагає думати, evidence — доводити.

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

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

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

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

Пакет компактний і відповідає на одне запитання: які факти потрібні для цієї задачі. Дрібна проблема — три пункти, баг на стику фронтенду і бекенду — сім-вісім.

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

Ключовий момент у тому, що пакет завжди збирається під конкретну мету. Якщо у вас UI-проблема у формі реєстрації, величезний серверний лог за добу майже напевно зайвий. Якщо у вас дублюється повернення коштів, один гарний скриншот інтерфейсу не врятує: знадобляться лог запиту, опис відтворення і розуміння, де проходить виклик на бекенд.

Є ще одна важлива звичка: не змішуйте evidence з «усім, що, можливо, колись стане у пригоді». Інженерний пакет фактів — це не комора. Якщо ви не можете пояснити, навіщо конкретний файл або лог потрапив до пакета, найімовірніше, він там поки не потрібен.

4. Приклад на Commerce OS

Щоб це не залишалося красивою теорією, давайте приземлимося на наш наскрізний проєкт. Уявімо, що в Commerce OS оператор підтримки відкрив замовлення, натиснув кнопку «Запросити повернення», інтерфейс трохи замислився, і після цього в системі зʼявилися два повернення замість одного. Користувач не зрадіє, фінансист — тим більше, а ви раптово дізнаєтеся, що в слова «дивно» є грошовий еквівалент.

Якщо діяти на емоціях, дуже хочеться одразу сказати Claude: «Подивися все, що повʼязано з refunds, і полагодь». Але правильніше зупинитися і зібрати evidence. У хорошому пакетi для такої задачі майже напевно будуть кроки відтворення, скриншот або запис подвійного натискання, лог сервера з двома запитами, файл кнопки на фронтенді, контролер або сервіс на бекенді, а ще схоже місце в проєкті, де захист від повторного запиту вже є. Наприклад, у скасуванні замовлення або в повторному надсиланні листа.

Саме в цей момент корисно завести окремий файл 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/. Переписка колег у стилі «мені здається, це база гальмує». Скриншоти з трьох різних багів, бо «також щось схоже було». Усе це виглядає як турбота про повноту картини, а насправді розмиває фокус.

Тут корисно ставити собі просте запитання: якщо прибрати цей факт із пакета, стане гірше розуміти проблему або перевіряти рішення? Якщо ні, найімовірніше, це не evidence, а шум.

Іноді цю різницю добре видно навіть у формулюванні запиту.

Зашумлено:
«Ось увесь модуль orders, три старі логи, дамп відповіді API за тиждень
і пʼять скриншотів. Подивіться, що там не так».

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

У другому варіанті в Claude є нормальна робоча поверхня. У першому — відчуття, ніби його попросили «розібратися у всьому житті». А це вже задача не для інструмента, а для літературного роману у трьох томах.

8. Що не кладуть до пакета

Є ще один важливий шар гігієни, який не можна ігнорувати навіть у навчальних задачах. Evidence має бути не лише релевантним, а й безпечним. Якщо бездумно копіювати в журнал усе підряд, дуже легко притягнути туди секрети, токени, особисті дані користувачів, вміст .env або шматки бойових логів, які взагалі не мають блукати між сесіями.

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

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

9. Коли evidence достатньо

На практиці найчастіше запитання — не «як зібрати evidence», а «коли зупинитися». Бо збирати факти можна довго, особливо коли баг неприємний, а проєкт великий. Тут допомагає дуже приземлений критерій: пакет evidence можна вважати достатнім, коли ви вже можете без ворожіння відповісти на кілька опорних запитань: що саме ламається; як це відтворити; де проходить імовірна зона змін; за якими ознаками ми зрозуміємо, що виправлення спрацювало.

Якщо одного з цих стовпів немає, квапитися до реалізації рано. Якщо всі чотири на місці, далі вже не потрібно вдавати детектива довше за необхідне. У вас є робоча основа. Можна переставати збирати усе підряд, зафіксувати пакет у EVIDENCE_LOG.md і рухатися до задачі, яку потім справді вдасться прийняти за фактами, а не за відчуттям «ну тепер ніби виглядає краще».