Как разобраться в незнакомом проекте

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

Легко начать открывать папки подряд в надежде наткнуться на нужное место. Полезнее сначала понять общую структуру и правила проекта. Они пригодятся и для маленькой правки, и позже, когда вы захотите добавить новую игру: нужно будет выбрать имена файлов, найти им место и проверить результат вместе с Claude Code.

Сначала найдите вход в проект

Начните с дерева файлов в панели IDE и найдите в корне проекта README.md. Это обычный текстовый файл, который кто-то написал для человека, а не для программы: в нём принято коротко объяснять, что за проект перед вами и как его запускать. Правда, иногда внутри только название проекта и надежда, что вы сами во всём разберётесь. Люди ленивые, а README сам себя не напишет :)

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

README может отсутствовать или отстать от кода. Считайте его отправной точкой: сведения о командах и папках нужно сверить с файлами проекта. Если описание обещает одну структуру, а дерево показывает другую, сохраните это как вопрос для проверки.

Что рассказывает дерево папок

Возьмём учебный пример: небольшой браузерный портал с витриной игр, начислением очков и таблицей результатов. Часть его дерева выглядит так:

project/
├── README.md
├── package.json
├── vite.config.js
├── pages/
│   └── leaderboard.html
├── src/
│   ├── leaderboard.js
│   └── reward-flow.js
├── assets/
├── tests/
└── dist/

Даже без единой прочитанной строчки кода дерево уже кое-что подсказывает:

Название папки - подсказка, а не подтверждение. Файл src/leaderboard.js похож на нужный по имени; теперь нужно прочитать его и найти место подключения. Таблица выше описывает ожидаемые роли папок, которые ещё предстоит подтвердить. В частности, наличие tests/ пока ничего не говорит о том, как запускаются проверки.

Отдельно стоит различать исходный код и то, что этим кодом порождено или установлено со стороны. dist/ обычно собирается инструментом сборки из содержимого src/, а папка сторонних зависимостей (часто она называется node_modules/, хотя в примере её нет) вообще не написана людьми из вашей команды. Начинать чтение с них почти всегда бессмысленно: правка там или потеряется при следующей сборке, или относится к чужому коду, который вы не редактируете напрямую. Менеджеры пакетов, установка зависимостей и формат lockfile - отдельный разговор, сюда он не входит.

И ещё: набор папок из примера - не стандарт. В другом проекте страницы могут лежать в public/, а исходники - в app/. Логика поиска останется той же, поменяются только имена.

Правила работы с проектом

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

Ищите договорённости по ссылкам из README. Файл CONTRIBUTING.md, если он есть, обычно объясняет, как вносить изменения. В документации могут быть правила размещения файлов, а в CLAUDE.md - инструкции для агента. У отдельной папки бывает собственный README с уточнениями для её содержимого. Не нужно ожидать весь этот набор в каждом проекте: иногда несколько нужных правил помещаются в корневом README.

Для первой правки достаточно выяснить, какие исходные файлы можно менять, как их здесь называют и размещают, как запускают проект и проверяют результат. Если инструкция запрещает редактировать результат сборки, найдите исходник. Если просит обновлять описание при добавлении страницы, включите это в задачу сразу.

Когда письменного правила нет, посмотрите два-три похожих примера. Для новой игры полезнее изучить соседние игры, чем случайную папку с документацией. Совпадающий способ размещения файлов можно взять за образец, но один старый файл ещё не доказывает, что так устроен весь проект.

Бывает и неприятнее: README отправляет страницы в pages/, а последние игры лежат в другом месте. Здесь полезен конкретный вопрос владельцу проекта: "В инструкции указан pages/, но две новые игры размещены в games/. Куда добавлять следующую?" Не стоит молча выбирать понравившийся вариант или переносить всё дерево ради единообразия.

Правила нейминга файлов и папок

Нейминг - договорённость о названиях. Хорошее имя помогает найти нужный файл в дереве и понять его назначение до открытия. В нашем портале leaderboard.html подсказывает, что это таблица результатов, а page2.html сообщает только чей-то порядковый номер.

У названия есть смысл и форма. Смысл отвечает на вопрос "что здесь лежит?", а форма задаёт регистр букв и разделители слов. Например, страницу ежедневных наград можно назвать несколькими способами:

Это варианты записи, а не рейтинг. Если страницы проекта названы через дефис, новая страница получает имя в том же стиле. При этом разные группы файлов могут иметь разные соглашения: привычное имя README.md не нужно превращать в строчное ради сходства с HTML-страницами. Имена, которые ожидают инструменты, тоже сохраняют.

Предположим, для обычных файлов нашего портала договорились использовать английские слова в kebab-case. Тогда snake-preview.png понятнее, чем img3.png: это превью Змейки. Папка game-icons/ говорит о содержимом больше, чем stuff/. Имя leaderboard-final-new.html быстро устареет после следующей правки; для рабочей страницы лучше оставить устойчивое название по назначению.

Выберите один термин для одной сущности. Если игры в проекте называются games, появление папки plays для той же группы заставит читателя выяснять, есть ли между ними разница. Не сокращайте слова до загадок вроде ldrbrd/, если такого сокращения нет в соглашениях проекта.

Точность написания тоже важна. Имя файла и путь к нему должны совпадать, включая регистр: Snake.png и snake.png не стоит считать взаимозаменяемыми. Ошибка может остаться незаметной на одном компьютере и проявиться в другом окружении. В нашем примере договорённость о строчных буквах уменьшает число таких расхождений.

Правила вложенности папок

Имя выбрано. Следующий вопрос - куда положить файл. Вложенная папка полезна, когда она объединяет понятную группу: страницы игр, изображения одной игры, общие иконки. Каждый новый уровень должен помогать найти содержимое.

Представим альтернативный вариант: портал растёт, а все файлы складывают прямо в корень:

project/
├── README.md
├── package.json
├── snake.html
├── tetris.html
├── leaderboard.html
├── snake.js
├── tetris.js
├── snake-preview.png
└── tetris-preview.png

В маленьком примере ещё можно разобраться. Когда игр станет двадцать, страницы, скрипты и картинки будут мешать друг другу. В нашем портале уже есть разделение на pages/, src/ и assets/, поэтому при добавлении игр логично продолжить его. Вот фрагмент возможной структуры после такого добавления:

project/
├── pages/
│   ├── leaderboard.html
│   └── games/
│       ├── snake.html
│       └── tetris.html
├── src/
│   ├── leaderboard.js
│   └── games/
│       ├── snake.js
│       └── tetris.js
└── assets/
    └── games/
        ├── snake/
        │   └── preview.png
        └── tetris/
            └── preview.png

Страницы игр собраны в одной группе, их скрипты - в другой. Название игры связывает файлы между собой. У изображений есть папка конкретной игры, поэтому короткого имени preview.png достаточно: полный путь уже объясняет, чьё это превью. Отдельная папка пригодится и для других изображений той же игры.

Обратная крайность - путь вроде pages/portal/content/browser/games/arcade/snake/screens/main/index.html. Чтобы открыть одну страницу, приходится проходить много уровней, а часть названий почти ничего не добавляет. Если в проекте нет отдельных порталов, экранов и категорий, такая структура создаёт работу без пользы.

Универсального предела "не глубже трёх папок" нет. Проверяйте смысл каждого уровня: что он объединяет и помогает ли отличить эту группу от соседних? Папка с одним файлом иногда нужна по правилам инструмента или проекта. Но создавать её только потому, что "потом здесь может что-нибудь появиться", обычно рано.

Дерево выше иллюстрирует развитие нашего примера. Если в вашем проекте каждая игра уже хранится целиком в своей папке, продолжайте этот способ. Новая игра сама по себе не повод перестраивать остальные.

Где хранить общие и локальные файлы

У Змейки появилось изображение яблока, а у всего портала - общий логотип. Оба файла относятся к картинкам, но используются по-разному. Яблоко нужно одной игре, логотип показывают на витрине, в таблице результатов и на игровых страницах.

Файл одной игры используется только в этой игре. В этом разделе такие файлы называем локальными: речь об области использования, а не о хранении на компьютере или сервере. В нашем варианте дерева яблоко попадёт в assets/games/snake/apple.png. Общий файл нужен нескольким частям; для логотипа можно выделить assets/shared/portal-logo.svg, если такую папку приняли в проекте. Слово shared означает "общий", но само имя папки не даёт файлу никаких особых свойств.

То же различие полезно для стилей и скриптов. Оформление игрового поля Змейки относится к ней, оформление общей шапки - ко всему порталу. При выборе места спросите, кто использует файл сейчас. Не нужно заранее выносить всё в общую папку на случай будущего повторного использования.

И наоборот, копировать один логотип в папку каждой игры неудобно: при замене придётся найти все копии. Если это действительно один общий ресурс, лучше ссылаться на один файл. А два похожих изображения разных игр могут оставаться независимыми: внешнее сходство ещё не означает, что их всегда будут менять вместе.

На схеме к общему логотипу ведут три стрелки, а к изображению яблока - только одна. Поэтому после замены логотипа стоит посмотреть все три страницы, а после замены яблока - Змейку. Перед правкой полезно попросить Claude Code найти, какие файлы ссылаются на ресурс: фактических связей может быть больше, чем видно из названия папки.

Что проверить при переносе и переименовании

Файл можно переименовать за секунду, но его прежнее имя уже может быть записано в ссылках и настройках. Перенос меняет ещё и положение относительно других файлов. Поэтому наведение порядка в дереве - такая же правка проекта, как изменение содержимого страницы.

Возьмём отдельный пример переноса: страницу pages/snake.html переместили в pages/games/snake.html. Скрипт остался на месте, в src/games/snake.js. В этом примере относительный путь считается от адреса HTML-страницы. После переноса подключение нужно изменить:

<!-- В pages/snake.html до переноса -->
<script src="../src/games/snake.js" type="module"></script>

<!-- В pages/games/snake.html после переноса -->
<script src="../../src/games/snake.js" type="module"></script>

Каждый фрагмент ../ поднимает путь на одну папку выше. Теперь из games/ нужно выйти в pages/, затем в корень и только оттуда перейти в src/. Сам скрипт не изменился, а старый путь к нему уже неверен.

Есть и ссылки в обратную сторону: карточка игры на витрине по-прежнему может вести на старый адрес страницы. Перед переносом найдите упоминания прежнего пути по проекту. После переноса обновите нужные ссылки, подключения, настройки сборки и примеры в документации. Для переименованного скрипта также проверьте импорты - записи, через которые другие скрипты его подключают.

IDE может обновить часть ссылок автоматически, но результат всё равно нужно просмотреть. Не всякий путь записан одной строкой: иногда адрес собирается из имени папки и имени файла. Поэтому поиск старого имени помогает найти зависимости, а запуск нужного сценария помогает заметить пропущенные.

Как проверить результат правки

Сначала найдите в документации проекта команды запуска, сборки и проверок. Если это проект с package.json, сопоставьте инструкцию с его разделом scripts. Названия команд зависят от проекта; наличие папки tests/ не подсказывает само по себе, что именно запускать. Если инструкция отсутствует, уточните способ проверки, а не подставляйте знакомую команду наугад.

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

Успешная сборка полезна, но не заменяет эти действия: ссылка на старый адрес может остаться и в собранном проекте. Запишите, что получилось проверить, а что пока нет. Например: "Сборка прошла, Змейка открывается с витрины и запускается; отображение на узком экране не проверялось".

Наконец, просмотрите список изменённых файлов. Для добавления одной игры ожидаемы её файлы и правка витрины. Переименованные папки других игр или массовая перезапись картинок требуют объяснения. Этот просмотр занимает меньше времени, чем поиск неожиданной поломки позже.

Как передать правила Claude Code

Просьба "добавь игру аккуратно" оставляет агенту слишком много решений. Полезнее назвать задачу и попросить сначала изучить договорённости. Путь к новой игре должен следовать устройству проекта, а не случайному предпочтению агента.

Постоянные, проверенные правила можно записать в CLAUDE.md. Для нашего учебного портала фрагмент мог бы выглядеть так:

## Файлы и папки
- Обычные файлы и папки называем английскими словами в kebab-case.
  Принятые имена README.md и CLAUDE.md сохраняем.
- Страницы игр лежат в pages/games/, скрипты игр - в src/games/.
- Ресурсы одной игры лежат в assets/games/<game-name>/.
- Общие изображения портала лежат в assets/shared/.
- При переносе или переименовании обновляем ссылки на файл
  и относительные пути внутри него.

## Проверка
- Команды запуска и проверки берём из README.md.
- Новую игру открываем с витрины и проверяем её запуск.
- После изменения общего ресурса проверяем использующие его страницы.

Это пример согласованных правил, не универсальный шаблон дерева. Прежде чем записывать похожий блок у себя, сверьте пути и команды с реальными файлами. Если агент только предположил назначение папки, попросите его показать основания; не превращайте предположение в постоянную инструкцию.

Теперь задача на добавление игры может звучать так:

Нужно добавить в портал игру memory-match по приложенному описанию.
Прочитай README.md, CLAUDE.md и инструкции папок, которых коснётся задача.
Посмотри, как размещены файлы двух существующих игр.
Предложи имена и пути для новой страницы, скрипта и изображений.
Укажи, какой файл витрины нужно изменить, и как проверить результат.
Если инструкции расходятся с устройством проекта, задай вопрос.
Сначала покажи план, дождись согласования, затем вноси правки.

В плане уже можно оценить конкретные решения: куда попадёт игра, какие файлы станут общими, не затронет ли работа соседние страницы. После правки попросите перечислить изменённые файлы и выполненные проверки. Вам будет проще сопоставить результат с тем, что вы согласовали.