andruha-messages-dialogues-service

Imported from yemeal/andruha-messages-dialogues-service (AGENTS.md). Install upstream with npx skills add yemeal/andruha-messages-dialogues-service. Copyright stays with the author.

AGENTS.md — messages-dialogues-service

Общие правила синхронизируются с docs/agent-guidelines/AGENTS.md в Andruha; этот файл самодостаточен при отдельном checkout. Контекст ниже уточняет действующий механизм, не разрешая массовый рефакторинг.

Работа и согласования

• Отвечай по-русски: сначала результат, затем существенные детали. Перед сложной задачей дай краткий план: поведение, затрагиваемые границы, шаги и проверки.
• До правок прочитай локальные инструкции, README, релевантные CONTEXT.md/ADR и проверь Git status родителя и сервиса. Сохраняй чужие и незавершённые изменения; работай только в согласованной области.
• Прямое поручение разрешает необходимые изменения в его пределах. Рутинные обратимые решения принимай сам; уже полученное согласие повторно не запрашивай.
• Сначала согласуй изменения публичных API, схем БД и сериализованных событий, новые зависимости/инструменты, удаление существующих файлов или публичных интерфейсов, если это ещё не разрешено задачей.
• Аудит заканчивается выводами и конкретным планом; обнаруженные исправления и архитектурный рефакторинг выполняй после одобрения. Независимую разрешённую работу продолжай, пока ждёшь ответа.

Git и доставка

• Каждая фича — отдельная ветка с понятным именем; по умолчанию feat/<краткая-суть>. Основная ветка изменяется через PR. Для независимых репозиториев — отдельные ветки и PR.
• Коммиты атомарны и идут в логическом порядке: одна ответственность, только относящиеся к ней файлы, без смеси фичи и посторонней уборки.
• Conventional Commits: type(scope): description; scope необязателен. Используй feat, fix, refactor, test, docs, chore, build, ci, perf; breaking change обозначай ! или BREAKING CHANGE:.
• Перед коммитом проверь staged diff. Не включай чужие правки, секреты, токены, пароли или приватные ключи, включая тесты. Не переписывай чужую историю и не выполняй разрушительные Git-операции без явного разрешения.

TDD и неприкосновенность тестов

• Для фичи/багфикса используй навыки tdd и pytest-skill, когда применим Python; их примеры не отменяют правила этого файла. Перед новым тестом согласуй проверяемое поведение и публичную границу; уже утверждённого задания/плана достаточно, если они определены в нём.
• Работай вертикальными шагами: один тест поведения → ожидаемый RED → минимальная реализация → GREEN. После GREEN проверь дизайн и сделай разрешённое локальное упрощение, затем повтори затронутые проверки. Не пиши заранее весь набор тестов под предполагаемую реализацию.
• О каждом падении сообщай сразу: команда, конкретный тест, ожидаемое/фактическое поведение, известная причина или явно отмеченная гипотеза.
• Ожидаемый RED нового теста, падающего именно из-за согласованного отсутствующего поведения: сообщи и продолжай реализацию по согласованному плану, не меняя тест.
• Неожиданное падение (включая иной повод RED): останови исправления затронутой области, представь диагностику и запроси одобрение. До ответа допустимы чтение/диагностика и независимая работа, но не изменение production-кода ради этого падения.
• Любые изменения уже написанных тестов — только после одобрения: assertions, fixtures, conftest, helpers, snapshots, перемещения/удаления, skip/xfail и настройки, меняющие набор или смысл проверок. Это относится и к тесту, только что написанному агентом. Не ослабляй проверки ради GREEN; намеренно оставленный пользователем RED сохраняй.
• Тестируй наблюдаемое поведение через публичные интерфейсы: результат, доменную ошибку и состояние после операции. Ожидания бери из требований/независимых примеров, а не из повторения алгоритма. Не привязывай тест к приватным методам и порядку внутренних вызовов.

DDD и гексагональная архитектура

• Используй язык предметной области. Rich Domain Model объединяет состояние и управляющее им поведение; сущность/агрегат сам охраняет свои инварианты. Application координирует сценарий, права, порты и транзакцию; бизнес-правила не дублируются в handlers, HTTP или persistence.
• Зависимости направлены внутрь: entrypoints → application → domain; infrastructure реализует порты внутренних слоёв. Domain не импортирует application, transport, ORM, DI, настройки или внешние клиенты; application не зависит от конкретных адаптеров. Сборка зависимостей — в composition root.
• Pydantic в domain — осознанный выбор проекта. Доменные модели, ORM-модели, транспортные схемы и application DTO имеют разные роли; преобразования выполняй на границах. DTO без поведения допустим, анемичная сущность — нет.
• Корень агрегата контролирует изменения внутри своей границы согласованности. Проверки формата на входе не заменяют доменные инварианты; межагрегатные правила координируй через application/порты и необходимые ограничения хранилища.
• Переиспользуй существующие UoW, репозитории, policies, dispatch, idempotency и outbox. Не вводи второй механизм для уже решённой задачи; межсервисные изменения требуют явной области работ.
• Query не изменяет наблюдаемое бизнес-состояние и не создаёт отсутствующие данные. Command явно выражает изменение; допустим результат выполненного действия (ID/DTO/признак изменения). Не разделяй атомарное действие на небезопасные write/read ради буквального CQS.

Python и доменная модель

• Python 3.14+: T | None, list[T], dict[K, V], tuple[T, ...], Self, Annotated; не добавляй legacy Optional, Union, List, Dict. Соблюдай типы; Any, cast и подавление диагностики не подменяют контракт и валидацию.
• Переиспользуй базовые классы: DomainModel — без идентичности (включая Value Objects); Entity — id, created_at; MutableEntity — ещё updated_at; VersionedMutableEntity — ещё version для OCC. Применяй только нужный уровень; существующие отличия перечислены в контексте сервиса.
• Всегда валидное состояние: создание, фабрики, восстановление и доменные операции сохраняют инварианты. Межполевые инварианты выражай в @model_validator(mode="after"), локальные ограничения — типами/полями; валидаторы детерминированы, без I/O и побочных изменений.
• Изменяй сущность только явными доменными методами через существующий _apply_changes(now=..., ...) или указанный локальный эквивалент. Сначала проверь полное кандидатное состояние, затем примени бизнес-поля, время и версию вместе. При любой ошибке исходное состояние полностью неизменно; временно невалидное состояние с последующим rollback не является нормой.
• Иммутабельность по умолчанию: Value Objects — неизменяемые значения с фабриками create/from_*; изменяемые сущности закрывают прямую запись полей. frozen=True не замораживает вложенные list/dict: используй неизменяемые контейнеры и защищённые вложенные модели.
• Не обходи инварианты через чужие _private-поля, reflection, monkey-patching, __dict__ или object.__setattr__. Низкоуровневая замена состояния допустима только внутри существующего проверенного базового механизма; вызывающий код использует доменный метод.
• Обычные model_construct() и model_copy(update=...) обходят валидацию; не используй их для изменения/восстановления домена. Проверенный override, который действительно валидирует, допустим. model_validate(existing_instance) может не перепроверить объект; validate_assignment не гарантирует атомарность сложного перехода.
• Defaults Pydantic объявляй только через Field(default=...) или Field(default_factory=...); обеспечь их валидацию (validate_default=True). T | None само по себе не задаёт default. Форму с default внутри Annotated проверяй выбранным type checker: он может считать поле обязательным.
• Совместимая со статическим анализом запись, сохраняющая default внутри Field: foo: Annotated[str | None, Field(description="...")] = Field(default=None). Исходная форма foo: Annotated[str | None, Field(default=None, description="...")] допустима при подтверждённой поддержке инструментами; старые модели массово не переписывай.
• Время — timezone-aware UTC; naive datetime отклоняй, допустимый offset нормализуй в UTC на границе. Используй app.domain.clock.utc_now() либо существующий локальный clock, передавай now явно для детерминизма; не получай текущее время внутри проверки инвариантов.
• Новые бизнес-ID — uuid.uuid7(); версию входящего UUID проверяй, когда это требует контракт. Сохраняй полученную идентичность при восстановлении/replay; не генерируй новый ID для того же действия.
• OCC: домен управляет версией по контракту изменения, репозиторий атомарно проверяет ожидаемую версию при записи и сообщает конфликт. Один счётчик в модели не обеспечивает защиту от конкурентных обновлений.

Организация pytest

• Новые тесты размещай по уровню и предметной области: tests/unit/domain/<область>/, tests/unit/application/<сценарий>/, tests/unit/infrastructure/<адаптер>/; взаимодействия компонентов — tests/integration/<граница>/, сквозные сценарии — tests/e2e/<сценарий>/, если этот уровень уже введён. Создавай только нужные каталоги; существующие тесты без согласия не перемещай.
• Domain unit проверяет реальные модели без БД/сети; application unit использует простые fakes портов. Integration проверяет настоящий адаптер/хранилище, транзакции, сериализацию и конкурентные гарантии. HTTP-тест с подменённым хранилищем не доказывает работу с реальной БД.
• Fixtures располагай в ближайшем conftest.py, выбирай минимальный scope и обеспечивай teardown. Используй parametrize для независимых примеров, понятные имена/IDs и только зарегистрированные markers; async-режим бери из конфигурации проекта.
• Тесты быстрые, изолированные и воспроизводимые: фиксируй время/идентификаторы через предусмотренные порты, не полагайся на порядок, общие внешние данные, реальные задержки или случайные значения. Моки/fakes — на внешних границах, не внутри тестируемого поведения.
• Для доменных изменений проверяй успешный переход, отказ при нарушении инварианта и неизменность состояния при отказе; для значимого persistence — реальные ограничения/OCC. Покрытие проверяет полноту сценариев, процент сам по себе не доказывает качество.

Читаемый и простой код

• Пиши код как связный текст: понятные произносимые имена, небольшие функции с одной задачей и одним уровнем абстракции (SLAP). Сохраняй стиль проекта; не дроби код ради произвольного лимита строк.
• KISS/YAGNI: минимальный дизайн для текущего поведения, без speculative features, преждевременной универсальности и лишнего boilerplate. DRY: один источник бизнес-правила; похожий синтаксис не всегда означает одну абстракцию.
• SOLID: одна причина изменения (S); расширение через устойчивые точки вариативности (O); соблюдение контрактов подтипами (L); небольшие интерфейсы клиентов (I); зависимость от портов, а не реализаций (D). Полиморфизм, Factory/Strategy/Policy/Adapter применяй для конкретной необходимости.
• Комментарии объясняют бизнес-причину, компромисс алгоритма или внешнее ограничение. Непонятное «что» исправляй именованием и структурой; docstrings публичных контрактов сохраняй полезными.
• Boy Scout Rule действует внутри задачи и разрешённых файлов: убирай внесённые debug/неиспользуемые импорты/мёртвый и закомментированный код, не расширяя область и не нарушая согласования удаления или изменения тестов.
• Явно обрабатывай ожидаемые ошибки, сохраняй причину при переводе между слоями; неожиданные ошибки не проглатывай и не превращай в успех. Проверяй недоверенные данные на границах; не раскрывай секреты в логах/исключениях.
• Make it work → make it right → make it fast: сначала корректное поведение, затем разрешённое упрощение; оптимизация — после измерения, с сохранением контракта и проверок.

Проверка и завершение

• Точные команды и версии бери из конфигурации сервиса и CI. Во время реализации запускай целевые проверки; перед завершением изменения кода — formatter/linter, type checker и обязательные unit/integration-проверки проекта. Для документации без изменения поведения достаточно относящихся к ней проверок.
• Готовность кода: обязательные проверки прошли, formatter/linter/type checker не выдают ошибок и warnings. Проверяй без автоправки защищённых тестов и подавления диагностики; существующие проблемы сообщай отдельно, соблюдая границы согласования.
• Интеграции запускай с реальными изолированными зависимостями и нужными миграциями/настройками. Недоступная инфраструктура, collection, skip/xfail и ожидаемый RED не считаются прохождением тестов.
• Заверши отчётом: что изменено, какие команды прошли, какие проверки упали/пропущены/не запускались и что блокирует завершение. Не заявляй зелёный CI, готовую интеграцию или закрытый PR без проверки соответствующего результата.

Контекст: messages-dialogues-service

• Предметная область: долговременное состояние диалогов, сообщений и receipts. Учётные данные, профили, байты медиа, соединения, presence/typing и доставка онлайн принадлежат другим границам.
• Текущая реализация — Python 3.14/FastAPI с Pydantic и uv: HTTP health, lifecycle, request ID, logging/settings. Доменные модели, business use cases и persistence ещё не реализованы; подключение Cassandra или брокера не следует из архитектурного плана.
• Начни с README.md, src/app/entrypoints/http/main.py, core/settings.py и затрагиваемого пакета. domain, application/services, application/ports, infrastructure — границы будущей реализации; entrypoints/messaging пока каркас.
• Общая иерархия доменных классов и clock — стандарт для новой доменной работы, а не описание существующих файлов. Вводи только нужные базовые классы/порты в рамках согласованного сценария; не копируй модель соседнего bounded context.
• Тесты сейчас проверяют техническую HTTP-основу: tests/unit и tests/integration/test_http_bootstrap.py. Новые тесты сообщений/диалогов раскладывай по domain/application/adapter; health 200 не доказывает работоспособность переписки.

Команды и проверки

Команды ниже выполняются из корня этого сервиса.

uv sync --frozen
uv run prek run --all-files
uv run pytest tests/unit -q -x
uv run pytest tests/integration -q -x

• uv sync --frozen — подготовка окружения; для установки Git hooks используй uv run prek install. Источники команд: pyproject.toml, prek.toml, .github/workflows/ci.yml.

• prek включает проверки Ruff, форматирования, ty --error-on-warning и гигиены файлов. Перед общим прогоном проверь, что хуки не изменят защищённые тесты; при риске запускай проверки без автоправок и сообщи ограничение.

• CI дополнительно проверяет unit/integration с branch coverage ≥ 80%, зависимости, секреты и Docker smoke. Сверяй обязательные команды с текущим workflow; локальный запуск pytest не заменяет результат CI.

• При работе из Andruha используй scripts/codex-service.py по docs/codex-environment.md родителя; при отдельном checkout — команды выше. Старые примеры poetry run в исторических документах не меняют текущий выбор uv.

• Текущий integration bootstrap не требует БД/брокера. Для будущего реального адаптера добавляй подготовку только согласованных зависимостей и отдельные проверки persistence.