Анатомия проекта

где что лежит и что можно не открывать

Что это

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

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

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

измерено

weather-bot/
├── .git/                 история, трогать руками не надо
├── .venv/                установленные библиотеки
├── .env                  секреты: токены, пароли
├── .gitignore            что не попадает в git
├── requirements.txt      список зависимостей
├── README.md             с чего начать
├── bot.py                точка входа
├── config.py             чтение настроек
├── db.py                 подключение к базе
├── storage.py            запросы к базе
├── handlers/             обработчики команд
│   ├── __init__.py
│   ├── start.py
│   └── weather.py
├── migrations/           изменения структуры БД
└── tests/                тесты

Что читать, а что нет

Читать	Не читать
точку входа (`bot.py`, `main.py`, `app.py`)	`.venv/`, `node_modules/`, `vendor/`
`README.md`	`.git/`
папки с логикой (`handlers/`, `services/`)	файлы блокировок: `poetry.lock`, `package-lock.json`
`requirements.txt` — чем пользуется проект	сгенерированное: `dist/`, `build/`, `__pycache__/`

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

Как найти точку входа

Три способа, по убыванию скорости:

По имени. main.py, bot.py, app.py, manage.py, index.js, main.dart — в девяти случаях из десяти это она.
По README. Там обычно написана команда запуска, а в ней — имя файла.
Поиском. if __name__ == "__main__" для Python, "scripts" в package.json для JavaScript.

Имена, которые что-то значат

Некоторые названия устойчивы и встречаются во многих проектах:

Имя	Что внутри
`handlers/`, `routes/`, `views/`	что происходит в ответ на действие пользователя
`models/`, `schemas/`	описание данных: какие поля, каких типов
`services/`, `core/`	основная логика, не привязанная к интерфейсу
`utils/`, `helpers/`	мелкие вспомогательные функции
`migrations/`	изменения структуры базы, применяются по порядку
`tests/`	тесты
`static/`, `assets/`	картинки, стили, шрифты

Папка utils/ — особый случай: туда складывают всё, чему не нашлось места. Если она разрослась, это признак, что структуру пора пересматривать.

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

Запрос

Покажи дерево файлов проекта без .venv, .git и __pycache__.
Для каждой папки первого уровня — одна строка,
что в ней лежит.

Когда надо понять, с чего начинать:

Запрос

Я открыл этот проект впервые. Назови три файла, которые
надо прочитать, чтобы понять, как он устроен. По порядку.

И самое практичное — перед постановкой задачи:

Запрос

Мне надо добавить команду /stats. В каких файлах
придётся что-то менять? Пока ничего не пиши.

Ответ на последний вопрос заодно проверяет, правильно ли ИИ понял структуру проекта.

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

Файл .env в git. Проверяется одной строкой: есть ли .env в .gitignore. Если нет — токены уже в истории репозитория.

Логика в точке входа. Если bot.py на пятьсот строк, значит, разделения нет, и проект будет тяжело менять. Для ИИ это тоже плохо: он не сможет работать с частью, не задевая остальное.

Две папки для одного. utils/ и helpers/, services/ и core/ в одном проекте — признак того, что код складывали, не глядя. Спроси у ИИ, чем они отличаются: если он не сможет объяснить, их надо объединять.

Пустая tests/. Папка есть, тестов нет. Значит, при правках никто не узнает, что сломалось (статья 3.9).

Шпаргалка

Читать: точку входа, README, папки с логикой, список зависимостей.
Не читать: всё, что создано инструментом, а не человеком.
Точку входа ищи по имени, по README или по if __name__.
Устойчивые имена: handlers/, models/, services/, migrations/.
Перед задачей спроси у ИИ, какие файлы она затронет.
.env обязан быть в .gitignore.