IDE, термінал і логи як докази

1. Одних файлів уже замало

Код — головне джерело істини. Але між «у коді написано» і «у середовищі виконання сталося» лежить прірва.

У лекції про API_MAP.md ви шукали кінцеві точки, контролери, клієнтів, черги, конфіги й тести. Це статична карта проєкту. Візьмімо Commerce OS: ви знайшли POST /api/orders, побачили OrderController, зрозуміли, який сервіс створює замовлення, знайшли тести. А інтеграційний тест каже: за порожнього email система має повернути 400, але повертає 500. Карта з файлів — це схема, а не поведінка.

Тримайте в голові різницю:

Код показує, як влаштований механізм. Сигнали виконання показують, як він поводився під конкретним введенням, командою і сесією. Ці сигнали і потрібні Claude Code: вони звужують простір припущень. Ви не просите «вгадай, де баг» — ви приносите докази.

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

2. IDE — точний канал контексту, а не просто красивіший редактор

У роботі з Claude Code IDE цінна не красою, а точністю. Вона дає моделі саме той фрагмент, який важливий зараз: конкретний метод, блок умов, рядок у контролері. Це контекст через виділення — selection-as-context.

Розслідуєте баг у Commerce OS: за порожнього email checkout має повернути 400, а приходить 500. Типова помилка — надіслати «перевір, чому замовлення ламається» і дозволити читати весь модуль orders. Це вже не розслідування, а екскурсія районом. Точніше — відкрити OrderController, виділити метод і сказати: «використовуйте виділений код як основний контекст».

@PostMapping("/api/orders")
public ResponseEntity<?> createOrder(@RequestBody CreateOrderRequest request) {
    orderValidator.validate(request);              // за невалідних даних очікуємо 400
    Order order = orderService.create(request);    // зараз десь тут отримуємо 500
    return ResponseEntity.ok(order);
}

Фрагмент працює в зв’язці з точним запитом:

Використовуйте виділений метод як основний контекст.
Ось мета: зрозуміти, чому за порожнього email endpoint повертає 500 замість 400.
Посилайтеся на конкретні рядки і не робіть припущень без evidence.

Запит добрий не формулюванням, а тим, що він вузький: область пошуку обмежена, очікувана поведінка позначена, робота від фактів задана. Claude легше з 12 рядками, ніж із 600.

Другий сильний бік IDE — прив’язка до file:line. Пишете не «дивись OrderController», а OrderController.java:42-46 — і модель не починає обговорювати сусідні методи та архітектуру модуля «про всяк випадок». А «про всяк випадок» — дорогий спосіб забруднити контекст.

3. Термінал: показуйте помилку, а не переповідайте

Баг відтворюється — не пояснюйте його словами, покажіть як факт. Вивід термінала для цього майже ідеальний: там команда, результат, іноді шлях до файлу й натяк на причину.

Замість «замовлення чомусь падає» дайте команду й результат:

./gradlew test --tests OrderControllerTest
# FAILED: expected: <400> but was: <500>
# at OrderControllerTest.createOrder_validationFails(OrderControllerTest.java:73)

З такою вуликою розмова інша:

Ось команда, яка відтворює проблему:
./gradlew test --tests OrderControllerTest

Ось результат:
FAILED: expected: <400> but was: <500>
at OrderControllerTest.createOrder_validationFails(OrderControllerTest.java:73)

Використовуйте це як evidence. Знайдіть мінімальну причину розбіжності.

Корисний не тільки вивід, а й команда, яка його породила. Без команди моделі складніше відновити контекст: це unit-тест? integration? локальний запуск? build? smoke check? Один і той самий текст помилки в різних командах означає різне.

І з міркувань безпеки на старті: перед передачею terminal output перевірте, чи немає там секретів, токенів, внутрішніх URL та інших чутливих даних. AI не «забуває по-людськи» — приносите очищений матеріал.

4. Stack trace — це маршрут до рядка

Stack trace виглядає як прокляття: довгий текст, купа класів, framework internals, пів екрана дужок. Але це одна з найкоротших доріг від симптому до місця поломки.

Увесь trace розбирати не потрібно. Дивіться на тип помилки, потім шукайте перші рядки свого проєкту, а не внутрішні механізми Spring, JUnit або іншого фреймворку:

java.lang.NullPointerException: Cannot invoke "String.trim()" because "customerEmail" is null
    at src/orders/OrderService.create(OrderService.java:51)
    at src/orders/OrderController.createOrder(OrderController.java:45)
    at OrderControllerTest.createOrder_validationFails(OrderControllerTest.java:73)

Це вже карта руху: тест викликав контролер, контролер — сервіс, сервіс упав на рядку 51, тому що customerEmail виявився null, а код викликав trim(). Модель не вгадує про «щось із валідацією на фронтенді» — вона бачить реальний шлях виконання.

Відкрийте проблемний метод в IDE — отримаєте зв’язку runtime trace + точковий фрагмент:

public Order create(CreateOrderRequest request) {
    String email = request.customerEmail().trim(); // тут і падаємо за null
    paymentPolicy.check(request);
    return orderRepository.save(new Order(email));
}

Лише код — можете не помітити проблему. Лише trace — знаєте місце падіння, але не бачите сусіднього контексту. Разом — майже завершена інженерна гіпотеза.

Логи середовища виконання працюють так само, навіть без повного stack trace. Видно в логах email=null, а одразу після — creating order: це вже ланка доказового ланцюга. Головне — показувати релевантний фрагмент, а не переповідати словами.

5. Скріншот — теж evidence, якщо є підпис

Дві крайнощі: одні не використовують скриншоти як «нетехнічне», інші прикладають картинку як реліквію і чекають, що вона все пояснить сама. Скріншот корисний, коли проблема в стані інтерфейсу: порожній екран, неправильна помилка, зникла кнопка, накладання елементів, зламана модалка.

Той самий checkout у Commerce OS: користувач вводить порожній email, натискає «Оформити замовлення» і замість помилки валідації отримує порожній екран. «Фронт розвалюється» — замало. Скріншот із коротким підписом — ясніше:

Скріншот: checkout-empty-email.png
Підпис: після кліку по «Оформити замовлення» сторінка не показує помилку валідації, а переходить у порожній екран.

Картинка не замінює логи, тести й trace. Але вона відповідає на питання: що побачив користувач у момент проблеми. Це важливо там, де backend і frontend розходяться: backend чесно повернув 500, а frontend просто очистив екран. Для розслідування це дві різні проблеми — скриншот не дає їх змішати.

Правило просте: у скриншота майже завжди підпис у один-два рядки. Без підпису Claude інтерпретує зображення сам — знову припущення. Із підписом картинка стає доказом.

6. Збираємо невеликий пакет доказів для Claude Code

Для більшості завдань не потрібен гігантський звіт. Достатньо короткого, акуратно зібраного пакета: рівно стільки, щоб Claude Code зрозумів проблему і не потонув у шумі.

Мета:
Зрозуміти, чому POST /api/orders за порожнього email повертає 500 замість 400.

Контекст:
Використовуйте виділений метод OrderController.createOrder як основний контекст.

Команда відтворення:
./gradlew test --tests OrderControllerTest

Результат:
FAILED: expected: <400> but was: <500>
at OrderControllerTest.createOrder_validationFails(OrderControllerTest.java:73)

Stack trace (скорочено):
java.lang.NullPointerException: Cannot invoke "String.trim()" because "customerEmail" is null
at src/orders/OrderService.create(OrderService.java:51)

Скриншот:
checkout-empty-email.png — після кліку сторінка переходить у порожній екран.

Що потрібно від Claude:
Знайти мінімальну причину, послатися на рядки коду і запропонувати найменше виправлення без масштабного рефакторингу.

Зверніть увагу, як тут поєднуються всі вже знайомі нам практики. Є мета з task spec. Є вузький контекст через виділення в IDE. Є команда та її вивід. Є скорочений stack trace. Є візуальне підтвердження з боку інтерфейсу. І є явне прохання не розповзатися в великий рефакторинг. Такий пакет добре працює не лише в поточній сесії, а й тоді, коли ви повертаєтеся до завдання після паузи і не хочете знову переповідати всю історію.

Ця ж звичка дуже корисна і для ваших артефактів на кшталт API_MAP.md. Якщо раніше запис про POST /api/orders спирався лише на контролер і сервіс, то після розслідування ви вже можете прив’язати до нього і докази з середовища виконання: який тест підтверджує поведінку, яка команда відтворює збій, які обмеження знайшлися валідацією. Карта проєкту від цього стає живішою й чеснішою.

У якийсь момент ви помітите цікавий злам. До нього ви просите Claude Code «подумати, що тут не так». Після нього ви приносите йому конкретні докази й просите провести розслідування. І саме в цій точці Claude перестає бути ворожкою з клавіатурою й починає працювати як справжній інженерний помічник.

Такий пакет доказів потрібен не лише для виправлення бага. Ним також зручно уточнювати спірний запис у API_MAP.md, збирати troubleshooting note або чернетку документації і, коли розслідування розростається, виносити широке читання в окреме вікно на кшталт subagent-а, щоб назад повернулася вже коротка перевірна вичавка.