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

> Структура проекта простыми словами: папки по фичам или по слоям, где держать конфиг, интерфейс, логику и доступ к данным, чтобы ни ты, ни ИИ не терялись.

Published: 2025-06-19 · Source: https://subxcat.com/ru/articles/project-folder-structure · Author: SUBXCAT

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

В вайбкод-проектах структура обычно складывается сама: ИИ создаёт файл там, где ему удобно в данный момент, и через пару месяцев в папке `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 помогает разложить разросшийся проект по полочкам, не останавливая работу над продуктом.