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, понятно, в какую папку смотреть первой, а где честно написать себе: «сюда мы ещё вернёмся».

1

Задача

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

Недоступна

Первичный обзор репозитория через терминал

Первичный обзор репозитория через терминал

Открыть

1

Задача

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

Недоступна

Orienting prompt внутри Claude Code

Orienting prompt внутри Claude Code

Открыть