Этот протокол определяет стандарт для организации файловой структуры любого проекта. Он основан на принципах Чистой Архитектуры (Ports & Adapters), что обеспечивает низкую связанность, высокую тестируемость и понятность кодовой базы. Код должен быть организован по бизнес-назначению, а не по техническому типу. Это позволяет любому разработчику (или другому AI-агенту) быстро понять, за что отвечает каждый компонент системы, и вносить изменения в одном месте, не затрагивая другие. Мы разделяем "что" делает система (домен, сервисы) от "как" она это делает (базы данных, фреймворки). Твоя задача — проектировать файловую структуру как набор независимых слоев с явными границами. Каждый файл и директория должны иметь единственную, четко определенную ответственность. Изолировать чистые, независимые сущности домена, типы данных и бизнес-ошибки. Каждый файл должен содержать одну логическую сущность или тесно связанную группу (например, `user_entity.py`, `order_errors.py`). Этот слой не должен иметь никаких зависимостей от других слоев. Определить контракты (интерфейсы) для взаимодействия с внешним миром без указания реализации. Здесь находятся только абстракции: интерфейсы репозиториев (`i_user_repository.py`), клиентов внешних API, систем уведомлений. Этот слой содержит только объявления, без кода реализации. (Role in Ports & Adapters: Ports) Реализовать сценарии использования (use cases) и оркестрировать бизнес-логику. Сервисы зависят от абстракций (`ports`), а не от конкретных реализаций. Они оперируют доменными сущностями (`entities`). Имена файлов должны отражать бизнес-сценарий (`create_order_service.py`). Предоставить конкретные реализации для исходящих портов и инкапсулировать все взаимодействия с внешним миром (сеть, файловая система, БД). Здесь находятся HTTP-клиенты, коннекторы к базам данных, реализации репозиториев (`gitlab_api_client.py`, `postgres_user_repository.py`). Этот код реализует интерфейсы из слоя `ports`. (Role in Ports & Adapters: Driven Adapters) Определить точки входа в приложение (API-хендлеры, CLI-команды, обработчики событий). Этот слой является "переводчиком" внешних запросов в вызовы внутренних сервисов. Он отвечает за парсинг входящих данных, вызов соответствующего сервиса и форматирование ответа. Бизнес-логика здесь запрещена. (Role in Ports & Adapters: Driving Adapters) Управлять конфигурацией приложения: сборка, валидация и предоставление доступа к настройкам. Этот слой использует `infrastructure` для чтения настроек из окружения или файлов и предоставляет типизированный, валидированный объект конфигурации для остальных частей приложения. Для простых проектов обязательными являются только три слоя: `entities`, `services`, `infrastructure`. В этом случае сервисы могут напрямую зависеть от инфраструктуры. Слой `ports` вводится тогда, когда появляется необходимость иметь несколько реализаций для одного контракта (например, для тестов (`in_memory_repository`) и для прода (`postgres_repository`)) или когда нужно строго отделить бизнес-логику от деталей реализации. Создание общих файлов `types.py`, `models.py` или `schemas.py`, содержащих все типы данных проекта. Это приводит к высокой связанности. Изменение одного типа требует модификации общего файла, затрагивая всю систему. Типы должны находиться в слое `entities` или рядом с модулем, который их использует. Распределяй определения данных по доменной принадлежности. Создание директории `utils` или `helpers` как "свалки" для всего, что не подошло в другие места. Со временем такие директории становятся непредсказуемыми и сложными для навигации. Функция без побочных эффектов может остаться в `utils`, но если она работает с сетью или ФС, ее место — в `infrastructure`. Всегда классифицируй функцию по ее назначению и помещай в соответствующий слой. Обеспечить четкое разделение исходного кода и тестов, сохраняя при этом понятную навигацию. Создай директорию для тестов (например, `tests/` или `__tests__/`) на том же уровне, что и директория с исходным кодом. Внутри этой директории **полностью воспроизведи (отзеркаль)** структуру исходников. Если есть файл `services/user/create_user.py`, то его тест должен находиться в `tests/services/user/test_create_user.py`. Такой подход позволяет мгновенно находить тесты для любого модуля и сразу понимать, какой слой и компонент системы проверяется.