Структура проекта: как разложить файлы, чтобы не путаться

Структура проекта — это то, как файлы и папки разложены в репозитории: где интерфейс, где логика, где работа с базой и настройки. Хорошая структура отвечает на вопрос «где это лежит?» раньше, чем ты успел его задать.

В вайбкод-проектах структура обычно складывается сама: ИИ создаёт файл там, где ему удобно в данный момент, и через пару месяцев в папке components лежат и кнопки, и запросы к базе, и расчёт цены. Работает — до первой правки, которая требует найти все места, где считается цена.

Почему это важно, когда код пишет ИИ

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

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

Папки по слоям или по фичам

Есть два основных подхода.

По слоям — всё одного типа вместе: components/, hooks/, services/, api/, types/. Так устроены многие шаблоны и учебники. Удобно в маленьком проекте, но с ростом каждая фича размазывается по пяти папкам, и чтобы поменять оплату, ты открываешь файлы из всех пяти.

По фичам — всё про одну часть продукта вместе: billing/, profile/, projects/. Внутри фичи уже можно разделять на интерфейс, логику и данные. Поменять оплату — значит работать в одной папке.

Для продуктов больше пары экранов мы советуем фичи сверху, слои внутри. Примерно так:

src/
  features/
    billing/
      ui/          компоненты и страницы
      logic.ts     правила: что можно, сколько стоит
      data.ts      запросы к базе и API
    projects/
      ...
  shared/
    ui/            кнопки, поля, модалки
    lib/           общие утилиты
  config/          чтение переменных окружения
  db/              схема и миграции

Точные названия не важны. Важно, чтобы правило было одно и соблюдалось везде.

Где что живёт

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

Интерфейс. Компоненты показывают данные и сообщают о действиях пользователя. Они не ходят в базу напрямую и не решают, сколько стоит подписка. Общие элементы — кнопки, поля, модальные окна — лежат отдельно от фичей, потому что ими пользуются все.

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

Доступ к данным. Запросы к базе и внешним API — в отдельных модулях с понятными функциями вроде getProjectsForUser(userId). Тогда проверка прав живёт в одном месте, а не повторяется в каждом компоненте с переменным успехом.

Серверное и клиентское. Код, который работает с секретами и базой, должен лежать там, где он гарантированно не попадёт в браузер. Во многих фреймворках это отдельная папка или пометка в файле — узнай, как это устроено у тебя, и соблюдай.

Как переехать, не останавливая работу

Переделывать всё за выходные не надо. Договорись о целевой структуре, запиши её в README и в инструкции для ИИ-ассистента (CLAUDE.md, .cursorrules или аналог). Дальше переноси по одной фиче — обычно начиная с той, которую трогаешь чаще всего. Один перенос — один коммит, без попутных правок логики: так легко проверить, что ничего не сломалось.

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

Признаки, что структура проекта не работает

Ты ищешь файл поиском, а не по дереву папок.
В проекте есть utils.ts на тысячу строк.
Одна и та же логика находится в двух-трёх местах с небольшими отличиями.
Чтобы поменять одну фичу, приходится трогать больше пяти папок.
ИИ регулярно создаёт файлы не там, где ты ожидал.

Коротко

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

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