Evidence-based Q&A щодо codebase

1. Гарна відповідь — ще не знання

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

Claude Code звучить переконливо навіть там, де даних мало. Не зі зла — широке запитання підштовхує його склеїти правдоподібну історію. Повірите без перевірки — будете лагодити не той модуль і три години шукати баг там, де його немає.

Звідси правило:

Якщо в твердження немає посилання на код, тест, конфіг або вивід команди — це не факт, а гіпотеза.

Це і є evidence-based підхід. Не недовіра до Claude Code, а зміна ролі: він не оракул, а швидкий помічник-дослідник. Шукає, підсумовує, пов’язує шматки проєкту. Джерело істини лишається в репозиторії.

Схема, яку тримайте в голові під час кожного запитання про проєкт:

flowchart TD
    A[Запитання про проєкт] --> B[Відповідь Claude Code]
    B --> C{Є докази?}
    C -- Ні --> D[Вважаємо гіпотезою]
    C -- Так --> E[Відкриваємо файли та перевіряємо]
    E --> F[Фіксуємо підтверджений висновок]

Що пройшло через схему — переносите в CODEBASE_INVENTORY.md. Решта живе як гіпотеза.

Запитайте: «Як у Commerce OS підтверджується повернення грошей?» Відповідь «це робить адміністратор» марна. Корисною вона стане з ланцюжком: маршрут, контролер, перевірка прав, сервісний метод, тест, можливо конфіг із порогом ручного підтвердження. До цього перед вами не знання, а впевнено викладена версія.

2. Докази в codebase

Доказ у репозиторії — конкретна річ, яку можна відкрити очима: файл, метод, тест, конфіг, лог, результат команди. Не «Claude сказав», а «ось місце, де це видно».

Тримайте таку таблицю:

Одного джерела часто мало. @PreAuthorize("hasRole('ADMIN')") — сильний сигнал, але ще краще, коли поруч тест, що перевіряє: не адміністратор отримує 403 Forbidden. Тоді є не лише «так написано», а й «це перевіряється».

Приклад із Commerce OS. У модулі payments/ знайшли контролер:

@PostMapping("/api/orders/{id}/refund")
@PreAuthorize("hasRole('ADMIN')")
public RefundResponse approveRefund(@PathVariable Long id) {
    return refundService.approve(id);
}

Навіть на старті Spring Boot читаються три речі. @PostMapping — маршрут, URL запиту. @PreAuthorize — обмеження за ролями. Виклик refundService.approve(id) — керування переходить у сервіс.

Тест поруч робить висновок надійнішим:

@Test
void approveRefund_rejectsNonAdmin() throws Exception {
    mockMvc.perform(post("/api/orders/42/refund")
            .with(user("ops").roles("SUPPORT")))
           .andExpect(status().isForbidden()); // 403 Заборонено
}

Тепер ви не вгадуєте за анотацією, а бачите: користувач із роллю SUPPORT не підтвердить повернення грошей через цей HTTP-шлях.

Конфіг доповнює картину:

refund:
  manual-approval-threshold: 100   # суми понад 100 потребують ручного підтвердження

Тепер не один доказ, а зв’язка: маршрут, перевірка прав, тест і бізнес-поріг. Так і мисліть під час роботи з чужим проєктом — набір взаємно підтверджувальних слідів, а не один доказ.

3. Запитання до Claude Code без фантазій

Частіше проблема не в тому, що Claude Code помиляється, а в тому, як ви запитали. «Як тут працює auth?» — для моделі це прохання «розкажи щось розумне і швидше». Вона старається. Потім ви стараєтеся зрозуміти, звідки вона це взяла.

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

Порівняйте:

Для Commerce OS гарний запит може виглядати так:

Поясни, як у цьому проєкті підтверджується повернення грошей.
Прослідкуй шлях від HTTP-маршруту до сервісного методу та перевірки прав.
Для кожного кроку вкажи:
- файл і метод
- що саме це доводить
- чи є тести
- які припущення ти зробив
- рівень упевненості: високий / середній / низький
Не редагуй файли.

Тут є кілька важливих деталей. По-перше, запит не про «всю систему платежів», а про один конкретний сценарій. По-друге, ви просите не просто відповідь, а структуру відповіді. По-третє, ви прямо дозволяєте невизначеність: «скажи, що не перевірив». Це дуже корисно. Модель, як і людина, починає думати акуратніше, коли її просять не лише стверджувати, а й позначати межі знання.

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

4. Формат відповіді, який зручно перевіряти

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

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

Шаблон може бути таким:

## Твердження
...

## Докази
- файл:
- метод / маршрут:
- тест / команда:

## Що це доводить
...

## Припущення / не перевірено
...

## Рівень упевненості
високий / середній / низький

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

Ось як може виглядати заповнений фрагмент за нашим прикладом із refund:

## Твердження
HTTP-підтвердження refund доступне лише користувачу з роллю ADMIN.

## Докази
- `payments/RefundController.java`, метод `approveRefund(...)`
- анотація `@PreAuthorize("hasRole('ADMIN')")`
- тест `payments/RefundControllerTest#approveRefund_rejectsNonAdmin`

## Що це доводить
Маршрут `POST /api/orders/{id}/refund` захищений за роллю ADMIN,
а користувач із роллю SUPPORT отримує 403.

## Припущення / не перевірено
Не перевірено фонові jobs і внутрішні batch-процеси, які можуть обходити HTTP-шлях.

## Рівень упевненості
Високий для HTTP-маршруту, середній для всієї системи повернень.

Зверніть увагу, як змінюється якість відповіді. Вона перестає бути «модель розповіла історію» і стає робочою нотаткою інженера. І ось таку нотатку вже зручно зберігати в свої чернетки, передавати колезі або використовувати пізніше, коли ви повернетеся до цього модуля проєкту.

Такий формат зручний ще й тому, що з нього легко винести короткий запис у CODEBASE_INVENTORY.md: саме твердження, один-два маркери джерела і чесну межу впевненості. Повний чат туди тягнути не потрібно.

5. Користь assumptions і confidence у відповіді

На цьому місці багато новачків думають приблизно так: «Ну так, звісно, ще просити в моделі рівень упевненості... Може, їй ще чай запропонувати?» Звучить трохи занудно, але на практиці це один із найкорисніших прийомів. Коли ви просите Claude Code явно виписати assumptions, тобто припущення, і confidence, тобто рівень упевненості, ви фактично змушуєте його відділяти перевірене від домисленого.

Це дуже важливо, бо в чужому проєкті повно місць, де код натякає на одне, а реальна поведінка виявляється трохи іншою. Назва методу може бути оманливою. Конфіг може бути застарілим. Тестів може не бути. Маршрут може існувати, але не використовуватися фронтендом. Без явного маркування невизначеності все це змішується в один упевнений текст.

Зручно тримати в голові таку просту шкалу:

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

Гарна формулювання запиту може бути такою:

Якщо ти не знайшов прямого доказу, не видавай здогадку за факт.
Окремо переліч:
1. що підтверджено,
2. що припускається,
3. що потрібно відкрити або запустити для перевірки.

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

6. Відповідь і код розходяться: перепровіряємо

Найцікавіший момент починається тоді, коли Claude Code сказав одне, а ви відкрили файл і побачили інше. У новачка в цей момент зазвичай дві крайності: або «модель тупує, все пропало», або «мабуть, я не так зрозумів код, нехай модель має рацію». Обидві реакції не дуже корисні. Реакція інженера спокійніша: чудово, у нас є конфлікт, отже, потрібно уточнити область твердження.

Наприклад, Claude каже: «Refund може підтверджувати лише ADMIN». Ви відкриваєте проєкт і знаходите ще якийсь RefundApprovalJob. Усе, паніка? Ні. Перше запитання тепер не «хто помилився», а «про який саме шлях ішлося». Можливо, Claude описав лише HTTP-маршрут, а ви знайшли фонову обробку. Це не обов’язково суперечність: іноді це просто дві різні точки входу в одну бізнес-галузь.

У таких випадках краще переходити від загальних запитань до уточнювальних. Наприклад:

Ти описав HTTP-шлях підтвердження refund.
Тепер перевір, чи є в проєкті інші шляхи підтвердження:
background jobs, scheduled tasks, internal service calls або batch-процеси.
Для кожного варіанта вкажи файл і ступінь упевненості.

За потреби підключайте і команди. Вивід команди — це теж evidence, і інколи дуже корисний. Наприклад:

git grep "approveRefund"                 # шукаємо всі згадки підтвердження повернення
git grep "manual-approval-threshold"     # шукаємо, де використовується поріг ручного підтвердження
./gradlew test --tests "*RefundControllerTest"  # проганяємо точкові тести щодо повернень

Навіть якщо ви поки не дуже впевнені в консольних командах, логіка тут проста. git grep — це швидкий пошук по проєкту. Він допомагає не сперечатися на відчуттях, а перевірити, скільки взагалі місць у коді пов’язано з цією поведінкою. А тести показують, яка поведінка реально закріплена в проєкті.

Дуже корисна навичка — просити Claude Code не «передумати гарно», а «перезібрати висновок на основі нових даних». Тобто не: «Ти помилився, виправ відповідь», а: «Ось додатковий файл, онови висновок і розділи підтверджене від непідтвердженого». Це вже не суперечка з моделлю, а спільне розслідування.

7. Скрізний приклад Commerce OS: refund

Давайте тепер зберемо все разом на одному цілісному прикладі. Уявімо, що ви розбираєте Commerce OS і хочете зрозуміти, хто саме може підтверджувати повернення грошей. Це реалістичне запитання: воно стосується прав доступу, платежів і ризикових операцій. Отже, гарна відповідь без доказів тут особливо небезпечна.

Ви починаєте не з «Як тут влаштовані платежі взагалі?», а з вузького запитання:

Поясни, як у Commerce OS підтверджується повернення грошей.
Сфокусуйся лише на ручному підтвердженні refund.
Для кожного кроку покажи:
- маршрут або точку входу
- файл і метод
- перевірку прав
- наявність тестів
- що залишилося неперевіреним
Не редагуй файли.

Припустімо, Claude Code відповідає, що знайшов payments/RefundController.java, маршрут POST /api/orders/{id}/refund, анотацію @PreAuthorize("hasRole('ADMIN')"), виклик refundService.approve(id) і тест approveRefund_rejectsNonAdmin. Уже непогано. Але на цьому ми не зупиняємося й відкриваємо ключові місця.

По-перше, дивимося контролер:

@PostMapping("/api/orders/{id}/refund")
@PreAuthorize("hasRole('ADMIN')")
public RefundResponse approveRefund(@PathVariable Long id) {
    return refundService.approve(id);
}

Це дає нам одразу три факти. Є конкретний HTTP-маршрут. Є обмеження за роллю. Є сервіс, куди переходить бізнес-логіка. По-друге, дивимося тест:

@Test
void approveRefund_rejectsNonAdmin() throws Exception {
    mockMvc.perform(post("/api/orders/42/refund")
            .with(user("ops").roles("SUPPORT")))
           .andExpect(status().isForbidden()); // 403 Заборонено
}

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

refund:
  manual-approval-threshold: 100   # суми понад 100 потребують ручного підтвердження

Після цього ваш уже перевірений висновок може виглядати так:

## Твердження
Ручне підтвердження refund через HTTP-маршрут доступне лише ADMIN.

## Докази
- `payments/RefundController.java` → `POST /api/orders/{id}/refund`
- `@PreAuthorize("hasRole('ADMIN')")`
- `payments/RefundControllerTest#approveRefund_rejectsNonAdmin`
- `application.yml` → `refund.manual-approval-threshold: 100`

## Що це доводить
HTTP-шлях підтвердження захищений роллю ADMIN,
а повернення грошей понад 100 проходять через ручне підтвердження.

## Неперевірено
Не вивчено background jobs і внутрішні сервісні виклики поза HTTP-маршрутом.

## Рівень упевненості
Високий для HTTP-сценарію, середній для всієї підсистеми refund.

І ось у цей момент у вас з’являється не просто «відповідь від AI», а інженерний шматок знання. Його можна використовувати далі. На нього можна спиратися в розмові з командою. Його можна покласти в робочі нотатки. І найголовніше — ви розумієте, звідки він узявся.

Із цього моменту ставлення до запитань про codebase помітно змінюється. Ви більше не питаєте Claude Code «що тут відбувається?» у надії, що він виявиться електронним шаманом. Ви ставите дослідницьке запитання, вимагаєте докази, дозволяєте невизначеність і перевіряєте критичні шматки очима.

Робота з AI перестає бути ворожінням і починає дуже нагадувати нормальну інженерну практику. А підтверджені висновки потім спокійно лягають у CODEBASE_INVENTORY.md: не весь діалог цілком, а коротке твердження з помітками на джерело і з записом, що ще не перевірено.