CODEBASE_INVENTORY.md — карта проекта

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: «Как внутри ориентироваться, чтобы что-то понять или изменить?»

README.md

CODEBASE_INVENTORY.md

На Commerce OS это видно. README скажет: «ecommerce-платформа, backend на Spring Boot, frontend на Next.js» — хватит, чтобы стартовать. Но где обрабатываются возвраты, почему ai-assist/ рискованная — README молчит.

README — входная дверь. Inventory — план здания.

3. Содержимое CODEBASE_INVENTORY.md

Первый inventory тянет в крайности: впихнуть всё подряд или ограничиться тремя строчками. Рабочий — короткий и насыщенный: не пересказывает код, а помогает ориентироваться. Набор разделов стабильный.

./gradlew test

npm run dev

На старте хватит каркаса:

# CODEBASE_INVENTORY.md

## Стек и технологии

## Модули и ответственность

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

## Полезные команды

## Тесты и конфиги

## Карта зависимостей

## Runtime-потоки

## Зоны повышенного риска

## Открытые вопросы

Dependency map и Runtime flows сначала могут быть пустыми — inventory растёт вместе с пониманием проекта. Для нетривиальных утверждений оставляйте короткую ссылку на источник: файл, метод, тест или команду.

В inventory попадают и непонятые части: «не подтверждено, нужно проверить» полезнее выдуманного объяснения.

4. Сборка inventory вместе с Claude Code

Inventory не пишут в одиночку — 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, проект перестаёт быть тёмным лесом.

1

Задача

Claude code, 7 уровень, 2 лекция

Недоступна

Исправление AI-generated inventory с несуществующим модулем

Исправление AI-generated inventory с несуществующим модулем

Открыть

1

Задача

Claude code, 7 уровень, 2 лекция

Недоступна

Сбор сырого материала для inventory через терминал

Сбор сырого материала для inventory через терминал

Открыть