1. Розмову потрібно перетворювати на артефакт
Розмова з Claude про новий codebase здається майже розв’язанням: він підсумовує структуру, перелічує модулі, каже, де що лежить. Але все це живе всередині сесії. Сесії закінчуються й засмічуються — через кілька днів залишається відчуття розумної наради без протоколу.
Тому discovery треба фіксувати у файлі — щоб наступне запитання до проєкту починалося не з нуля. CODEBASE_INVENTORY.md — робоча карта місцевості: де логіка, як запускати, де тести, що не чіпати без підготовки, що ви ще не зрозуміли.
flowchart TD
A[Discovery по репозиторію] --> B[Запитання з evidence]
B --> C[Чернетка CODEBASE_INVENTORY.md]
C --> D[Перевірка файлів і команд]
D --> E[Робоча карта проєкту]
Без файлу завтра ви знову запитаєте: «А де обробка замовлень?» З inventory відкрили файл і за хвилину відновили картину.
2. README.md і CODEBASE_INVENTORY.md: колеги
Inventory легко сплутати з README. Але README відповідає: «Що це і як підняти?» Inventory: «Як усередині орієнтуватися, щоб щось зрозуміти або змінити?»
| Артефакт | Головне запитання | Для кого корисний насамперед | Що в ньому зазвичай є |
|---|---|---|---|
|
Що це за проєкт і як його запустити? | Новий розробник, зовнішній читач, рев’юер репозиторію | призначення проєкту, швидкий старт, залежності, базові команди |
|
Як цей проєкт влаштований ізсередини і де що шукати? | Розробник, який досліджує або змінює код | модулі, відповідальність частин системи, точки входу, тести, конфіги, небезпечні зони, відкриті запитання |
На Commerce OS це видно. README скаже: «ecommerce-платформа, backend на Spring Boot, frontend на Next.js» — досить, щоб стартувати. Але де обробляються повернення, чому ai-assist/ ризикована — README мовчить.
README — вхідні двері. Inventory — план будівлі.
3. Зміст CODEBASE_INVENTORY.md
Перший inventory тягне в крайності: запхати все підряд або обмежитися трьома рядками. Робочий — короткий і насичений: не переказує код, а допомагає орієнтуватися. Набір розділів стабільний.
| Розділ | Що ви туди записуєте | Приклад для Commerce OS |
|---|---|---|
| Стек і технології | Мови, основні фреймворки, база даних | Java 25, Spring Boot, React, Next.js, PostgreSQL |
| Модулі та їхня відповідальність | Великі папки і за що кожна відповідає | orders/ — кошик, оформлення, статуси |
| Точки входу | Звідки стартує застосунок або окремі потоки | HTTP-контролери, frontend entry, фонові задачі |
| Корисні команди | Як запустити, зібрати й протестувати проєкт | |
| Тести | Де лежать тести і що покривають | backend integration tests, frontend tests |
| Конфіги | Які конфігураційні файли важливі | application.yml, .env.example, frontend config |
| Зони підвищеного ризику | Що змінювати особливо обережно | payments/, migrations/, чутливі інтеграції |
| Відкриті запитання | Що поки незрозуміло і потребує перевірки | звідки береться confidence score в ai-assist/ |
На старті вистачить каркаса:
# CODEBASE_INVENTORY.md
## Стек і технології
## Модулі та відповідальність
## Точки входу
## Корисні команди
## Тести і конфіги
## Мапа залежностей
## Потоки виконання
## Зони підвищеного ризику
## Відкриті запитання
Dependency map і Runtime flows спочатку можуть бути порожніми — inventory зростає разом із розумінням проєкту. Для нетривіальних тверджень залишайте коротке посилання на джерело: файл, метод, тест або команду.
В inventory потрапляють і незрозумілі частини: «не підтверджено, потрібно перевірити» корисніше за вигадане пояснення.
4. Збірка inventory разом із Claude Code
Inventory не пишуть наодинці — Claude корисний. Але тільки якщо тримаєте звичку з минулого заняття: кожне важливе твердження спирається на файл, тест або команду. Інакше він напише гладкий текст, що не збігається з кодом.
Рухайтеся в три проходи:
| Прохід | Що робимо | Що отримуємо |
|---|---|---|
| Перший | Просимо Claude зібрати чернетку за структурою | Швидкий огляд проєкту |
| Другий | Перевіряємо спірні місця за файлами і командами | Підтверджені факти |
| Третій | Скорочуємо формулювання і додаємо ризик-зони | Робочий навігаційний артефакт |
Запит першого проходу:
Допоможи зібрати чернетку CODEBASE_INVENTORY.md для цього репозиторію.
Потрібні розділи:
- стек і основні технології
- модулі та їхня відповідальність
- точки входу
- корисні команди запуску і тестів
- тести і конфіги
- зони підвищеного ризику
- відкриті запитання
Для кожного важливого твердження вкажи файл або команду, на яку ти спираєшся.
Якщо щось не перевірено — познач як "не підтверджено".
Пиши коротко: це навігаційна карта, а не переказ коду.
Результат не приймайте за готовий файл. Відкрийте згадані файли, запустіть команди. Написав, що backend стартує через Gradle, — перевірте. Назвав payments/ зоною ризику — переконайтеся, що там повернення та інтеграції з платіжним провайдером. Докази не зберігайте: достатньо посилань.
Claude збирає каркас, ви перетворюєте його на карту. Inventory зростає з перевіреного контексту.
5. Перша робоча версія для Commerce OS
Давайте подивимося на першу живу версію для Commerce OS. Довгою їй бути не потрібно: файл на шість екранів перестає бути навігацією.
# CODEBASE_INVENTORY.md
## Стек і технології
- Backend: Java 25, Spring Boot, Gradle Wrapper (`build.gradle`)
- Frontend: React + Next.js, Node.js (`frontend/package.json`)
- Сховище: PostgreSQL (`docker-compose.yml`, `application.yml`)
## Модулі та відповідальність
- `catalog/` — товари, категорії, пошук (`catalog/`)
- `orders/` — кошик, оформлення замовлення, статуси (`orders/`)
- `payments/` — оплата, повернення, інтеграція з PSP (`payments/`, `RefundController.java`)
- `support/` — тікети, відповіді, ескалації (`support/`)
- `ai-assist/` — класифікація тікетів і підказки оператору (`ai-assist/`, `application.yml`)
Файл описує відповідальність модулів, а не переказує класи. Напишете «OrderService.java містить placeOrder, cancelOrder…» — отримаєте каталог методів, який не читають.
Команди:
./gradlew bootRun # запуск backend у режимі розробки
./gradlew test # запуск backend-тестів
npm run dev # запуск frontend у режимі розробки
npm test # запуск frontend-тестів
Секція команд часто найкорисніша: через тиждень ви не пам’ятаєте, як стартував проєкт, а тут усе в одному місці.
Секцію тестів і конфігів фіксуйте стисло:
## Тести і конфіги
- backend-конфіг: `src/main/resources/application.yml`
- frontend-налаштування: `frontend/package.json`, `next.config.*`
- основні backend-тести лежать поруч із backend-модулями (`src/test`)
- частина поведінки `ai-assist/` покрита слабо, потрібно уточнювати за кодом і тестами (`ai-assist/`, `src/test`)
Останній рядок не вдає, що все зрозуміло, — він чесно позначає зону невизначеності.
6. Зони ризику і відкриті запитання — цінна частина файлу
Головне в inventory — не перелічити модулі, а зафіксувати що тут небезпечно і що ви поки не зрозуміли. Це економить час, коли ви повернетеся змінювати код, а не досліджувати.
## Зони підвищеного ризику
- `payments/` — повернення, статуси платежів, ризик подвійного списання (`payments/RefundController.java`, `payments/RefundService.java`)
- `migrations/` — змінювати тільки після перевірки і review (`migrations/`)
- `ai-assist/` — частина поведінки залежить від конфігів і покрита тестами не повністю (`ai-assist/`, `src/main/resources/application.yml`)
Запис попереджає: сюди не можна з настроєм «зараз швиденько підчистимо». Особливо в payments/ — гроші, статуси платежів, повернення: ціна помилки висока.
Відкритих запитань не соромтеся. Вони означають, що ви не вигадали відповіді там, де даних не вистачило.
## Відкриті запитання
- звідки `ai-assist/` отримує confidence score — не підтверджено, потрібен пошук за `git grep "confidence"`
- де описана політика retry для повернень у `payments/` — поки не знайдено, перевірити `git grep "retry" payments/`
- чи є окремий фоновий потік перерахунку метрик окрім основного HTTP-шляху — не підтверджено, дивитися `jobs/` і планувальники
Такі записи — золото: завтра не згадуєте болісно «там було щось незрозуміле, а що саме — забув». Inventory працює як зовнішня пам’ять проєкту — і для Claude, і для вашого мозку.
7. Inventory не має стати марним сувеніром
Головна небезпека — писати inventory «надто правильно»: красиво, відполіровано й марно. Шлях у цю пастку — сплутати навігацію з переказом коду: почнете перелічувати класи й методи — файл продублює репозиторій.
Погано:
- `OrderService.java` містить 14 методів для обробки замовлення, зокрема
`placeOrder`, `cancelOrder`, `recalculateDiscount`, `notifyCustomer`...
Добре:
- `orders/` — кошик, оформлення замовлення, статуси та історія замовлення
Другий коротший і відповідає на запитання «куди йти за замовленнями?». Перший лише створює ілюзію деталізації.
Друга пастка — змішувати факти й здогадки без маркування. Не впевнені — пишіть прямо: «ймовірно», «не підтверджено». У великих codebase проєкт майже ніколи не зрозумілий повністю, і inventory це визнає.
І головне: inventory — живий артефакт. Дізналися про новий модуль — додали. Знайшли приховану точку входу — уточнили. Зона ризику розпливчаста — переписали.
Перша версія може бути короткою. Але якщо вона відповідає на три запитання — де шукати, як запускати і що небезпечно змінювати — inventory уже працює. А коли додадуться dependency map і runtime flows, проєкт перестає бути темним лісом.
ПЕРЕЙДІТЬ В ПОВНУ ВЕРСІЮ