Discovery в незнайомому репозиторії

1. «Поясни проєкт» — запит, який вас підведе

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

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

Порівняйте два запити.

Погано:
Поясни цей проєкт.

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

У другому варіанті ви задаєте рамку. Claude не вгадує, що для вас важливо, а працює за нею. Для discovery це критично.

2. Що має залишити перша сесія

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

Сирі нотатки тримайте де завгодно — чат, блокнот, scratch-файл. Але робочий результат збирайте одразу в одному місці: це перший шар CODEBASE_INVENTORY.md. Доповнювати його evidence і залежностями простіше, ніж заново склеювати з уривків.

Добра перша сесія залишає короткий чорновик із відповідями бодай на базові запитання.

Можете відповісти на них хоча б у першому наближенні — discovery спрацював. А якщо лишилася тільки фраза «ніби ecommerce на Java, і ще фронт» — отже, ні.

Тримайте в голові схему:

Безпечний старт → перший огляд → перевірка за файлами → уточнення неясностей → чорновик нотаток

Кроку «одразу правити код» у ній немає. І це не випадково.

3. Спочатку безпека, потім цікавість

Перед дослідженням переконайтеся, що ви в правильному місці й не змішуєте discovery з іншим завданням. Звучить очевидно — і саме тут починаються пригоди: людина досліджує один репозиторій, а думає, що відкрила інший. Або після пів дня обговорень багу намагається зрозуміти архітектуру. Це вже не discovery, а археологія.

Звідси перша звичка: discovery — в окремій сесії та в безпечному режимі, де ви нічого не змінюєте. Дослідження і правка коду — різні фази, не склеюйте їх.

Мінімальна перевірка перед стартом:

pwd          # переконуємося, що стоїмо в потрібному каталозі
git status   # дивимося стан робочого каталогу
ls           # бачимо верхній рівень проєкту

Якщо git status показує купу незрозумілих змін — не змішуйте discovery з цим хаосом. Спочатку розберіться, що це, перейдіть у чисту гілку або відкрийте окрему робочу копію. Інакше вчорашнє сміття легко прийняти за частину архітектури.

Ще корисно одразу проговорити Claude межі:

Зараз нічого не змінюємо в проєкті.
Потрібен лише огляд codebase.
Не пропонуй рефакторинг і не редагуй файли.
Спочатку хочемо зрозуміти структуру, команди та точки входу.

Така рамка знижує ризик, що Claude побіжить «допомагати» там, де ви поки просто орієнтуєтеся.

4. Перший прохід: з яких файлів починати

Repo відкрито, ви не втонули в перші дві хвилини — куди дивитися? Правило: не починайте з випадкових класів і не хапайтеся за найдовший файл. Спочатку — те, що описує проєкт згори.

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

У проєкті на кшталт навчального Commerce OS спочатку дивіться сюди.

build.gradle, settings.gradle, gradle/wrapper/

package.json, frontend/package.json

README.md, docker-compose.yml, scripts

src/test, __tests__, команди test

.env.example, application.yml, application.yaml

Перший оглядовий запит будуйте навколо цих точок:

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

На прикладі Commerce OS перший чорновик CODEBASE_INVENTORY.md виглядає приблизно так:

## Чорновик `CODEBASE_INVENTORY.md`

- Backend: Java + Spring Boot (`build.gradle`)
- Frontend: Next.js (`frontend/package.json`)
- Команди: `./gradlew test`, `./gradlew bootRun`, `npm run dev`
- Великі частини: `catalog/`, `orders/`, `payments/`, `support/`, `ai-assist/`
- Неясно: де саме живуть фонові задачі і як запускаються

Це ще не документація. Це робочий блокнот — і в такому вигляді він зараз корисніший за все.

5. Перевіряйте відповідь Claude за реальними файлами

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

Claude пише «backend на Spring Boot» — відкрийте файл збирання і знайдіть плагіни та залежності. «Frontend на Next.js» — гляньте package.json. «Тести через ./gradlew test» — перевірте Gradle wrapper і потрібні задачі.

Складні команди не потрібні, вистачає простих:

cat build.gradle            # дивимося backend-стек і залежності
cat frontend/package.json   # дивимося frontend-стек і scripts
./gradlew tasks             # перевіряємо, які Gradle-команди реально доступні
npm run                     # дивимося доступні frontend-скрипти

Тримайте під рукою таблицю переперевірки.

Тільки не впадайте в іншу крайність — читати поспіль усе. Discovery не марафон «хто більше файлів відкриє». Ви підтверджуєте ключові орієнтири: що на мапі не намальовано аеропорт посеред озера.

6. Точки входу і великі модулі Commerce OS

Стек і команди ясні — наступне запитання: де в проєкту вхідні двері. entry point, точка входу, звучить страшніше, ніж є: це місце, звідки система стартує або куди приходить основний потік роботи. Для backend — головний файл застосунку. Для frontend — стартова сторінка або кореневий компонент. Для HTTP — контролери й маршрути. Поки важливі двері, а не весь шлях коридорами.

Логічна мапа модулів Commerce OS:

commerce-os/
  catalog/
  orders/
  payments/
  customers/
  support/
  ai-assist/
  dashboard/
  admin/
  api/
  jobs/

За назвами видно: проєкт доменний, а не «папка src і купа всього». Великі відповідальності зазвичай читаються вже на рівні верхніх модулів.

Запит на пошук точок входу робіть уже вужчим і точнішим, ніж перший огляд:

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

Нотатки доповняться приблизно так:

## Точки входу

- Backend startup: файл з `@SpringBootApplication`
- Frontend startup: `frontend/package.json` і стартова сторінка застосунку
- HTTP API: контролери в `api/` і доменних модулях
- Background jobs: директорія `jobs/`
- Тести: backend `src/test`, frontend `__tests__` або test scripts

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

7. Відкриті запитання — це результат, а не провал

Найкорисніша звичка discovery — чесно записувати незрозуміле. Не замазувати «ну загалом ясно», а фіксувати білі плями. Це open questions, відкриті запитання: не проблема для термінового вирішення, а позначка «знання ще не підтверджене».

Ви можете соромитися таких записів — здається, огляд має бути гладким і повним. Навпаки: гладкий огляд без відкритих запитань частіше просто вдає повний. Справжній discovery майже завжди залишає хвіст неясностей.

По Commerce OS після першого проходу залишається, наприклад, таке:

## Відкриті запитання

- Звідки `ai-assist` отримує confidence score?
- Де налаштовується retry-логіка в `payments`?
- Чи є єдина команда, яка підіймає backend і frontend разом?
- Які тести покривають повернення грошей?

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

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

Відкрите запитання — це не слабкість огляду. Це чесна межа поточного розуміння.

8. Чорновик CODEBASE_INVENTORY.md після першої сесії

До кінця першої нормальної сесії залишається короткий, але живий файл. Сирі нотатки живуть у чаті або блокноті, але постійна версія — одна: CODEBASE_INVENTORY.md. Спочатку груба, і це нормально. Відкриєте repo завтра — не почнете з нуля.

Каркас чорновика:

# CODEBASE_INVENTORY.md

## Стек
- Backend:
- Frontend:
- DB:

## Як запускати
- Backend:
- Frontend:
- Тести:

## Великі частини проєкту
- ...
- ...

## Точки входу
- ...
- ...

## Мапа залежностей
- ...

## Runtime-потоки
- ...

## Що поки неясно
- ...
- ...

Розділи Dependency map і Runtime flows поки майже порожні. Вони потрібні не для краси, а щоб увесь перший зріз проєкту жив в одному файлі, а не розповзався по кількох чорновиках.

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

Добрий discovery не дає ілюзії «я знаю весь проєкт». Він дає річ практичнішу: ви більше не стоїте в тумані. Є перший шар CODEBASE_INVENTORY.md, зрозуміло, в яку папку дивитися першою, а де чесно написати собі: «сюди ми ще повернемося».