Структура папок

решения, которые потом не переделать

Что это

Структура папок — это архитектура из статьи 13.1, записанная в файловой системе. Её главная ценность не в красоте, а в том, что она отвечает на вопрос «куда положить новый код» без обсуждения. Пока ответа нет, каждый новый кусок ложится туда, где оказался курсор.

Для работы с ИИ у структуры есть вторая, не менее важная роль: это то, что ты называешь в запросе. «Добавь в app/services/weather.py» — запрос, на который можно получить предсказуемый ответ. «Добавь функцию погоды» — приглашение выдумать структуру заново.

Как выглядит в коде

Два способа раскладывать, и оба правильные

По типам кода — всё однотипное вместе:

app/
├── models/        что хранится
├── services/      что происходит
├── routes/        что видно снаружи
└── utils/

По возможностям — всё, что относится к одной теме, вместе:

app/
├── weather/       модель, логика и экран погоды
├── users/         модель, логика и экраны пользователей
└── shared/

Выбор между ними — не вкусовщина, а ответ на вопрос «что чаще меняется целиком»:

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

Чего делать не надо — мешать оба способа. Папка models/ рядом с папкой weather/, внутри которой свои модели, — это не компромисс, а два ответа на один вопрос. Новый код после этого можно положить в оба места.

Что переделывается дорого

Не все решения равны. Эти три стоят того, чтобы подумать над ними в первый день:

1. Граница между слоями. Если логика и работа с базой изначально перемешаны, разделить их потом — это переписать почти всё. Обратно, из разделённого сделать смешанное, никто никогда не просит.

2. Имя корневого пакета. Оно попадает в каждый импорт проекта. Менять — значит менять каждый файл. Не app и не src, если проект когда-нибудь станет пакетом: своё, короткое, понятное.

3. Место данных. Решение «пока сложим в JSON» живёт дольше, чем планировалось (статья 13.3).

Остальное — имена папок, порядок файлов, где лежат тесты — переделывается за полчаса и не стоит долгих раздумий.

Размер файла

Ориентир, который работает: один файл — одна причина меняться. Если файл приходится открывать и когда меняется формат ответа API, и когда меняется внешний вид экрана — в нём два разных файла.

Числовой ориентир — 300–500 строк. Не правило, а сигнал: дошло до тысячи — скорее всего, внутри прячутся два файла.

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

Чего быть не должно

app/
├── utils.py          ← 900 строк всего подряд
├── helpers.py        ← то же самое, но другое
├── main_v2.py        ← прошлая версия, вдруг пригодится
├── test.py           ← не тест, а «попробовать»
└── new/              ← переписываем, но старое пока оставим

Каждая строка здесь — отложенное решение. utils и helpers — это «потом разложу». main_v2 и new/ — «потом удалю». Ни то, ни другое не происходит, зато в каждом запросе к ИИ приходится объяснять, какие файлы настоящие.

Старое не хранится рядом с новым: для этого есть git (статья 5.1).

Как сказать ИИ

Вот структура моего проекта:
<дерево папок>

Я добавляю возможность: <какую>.
Скажи, в какие файлы ляжет код и какие файлы придётся
изменить. Новые файлы называй по моей схеме.
Код пока не пиши.

Этот запрос стоит делать привычкой: он занимает минуту и снимает самую частую причину беспорядка — код, положенный не туда.

Структура проекта: <дерево>.
Правила: models ничего не импортирует, services импортирует
models, routes импортируют services.
Проверь по этим правилам файл, который ты сейчас написал.

У меня файл на 900 строк: <содержимое или описание>.
Предложи, на какие файлы его разбить и по какому признаку.
Для каждого — одна фраза, за что он отвечает.
Переносить код пока не надо.

В проекте есть utils.py, в котором всё подряд.
Разложи его содержимое по существующим папкам.
Для каждой функции скажи, куда и почему.
Если что-то действительно общее — оставь, но назови точнее.

На что смотреть

ИИ предложил новую папку рядом с существующей. helpers/ при живом services/, db/ при живом models/. Признак того, что структуру не назвали в запросе.

Смешаны две раскладки. models/ и weather/ в одной папке.

utils растёт. Каждая функция, положенная туда, — отложенное решение.

Файлы с версиями в имени. main_v2, app_new, index_final. Для этого есть git.

Тесты вперемешку с кодом. Отдельная папка tests/ рядом, а не файл test.py в каждой папке.

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

Шпаргалка