ivan-igorevich/dc-observatio

Fork 0

Files

T

Дмитрий Соловьев d48ddd2657 Init

2026-05-25 14:23:52 +03:00

13 KiB

Raw Permalink Blame History

AGENTS.md

Назначение

Этот документ задаёт правила работы агента и базовые инженерные правила для изменений в репозитории.

Цель агента:

вносить минимальные, безопасные и ревьюопригодные изменения;
сохранять архитектурные границы;
не ломать существующие контракты без явного запроса;
следовать уже используемым в репозитории паттернам и стилю.

Этот документ не является полным платформенным стандартом для BPM/Kafka. Такие правила вынесены в docs/standards/PLATFORM_STANDARD.md.

Дополнительные обязательные документы

При работе в этом репозитории:

Для изменений, связанных с BPM / Zeebe / Camunda / Kafka / retries / DLQ / compensation / schema evolution, перед изменением кода прочитай docs/standards/PLATFORM_STANDARD.md.
Перед завершением нетривиальных изменений проверь docs/standards/CHECKLIST.md.
Если задача затрагивает только обычный Kotlin/Spring-код без BPM/Kafka-аспектов, достаточно следовать правилам этого AGENTS.md.

Обязательный стиль работы

Перед внесением изменений:

Найди похожую реализацию в том же модуле, сервисе или соседнем слое.
Следуй уже принятому стилю проекта и существующей структуре.
Прочитай полный execution path до редактирования кода.
Держи решение в правильном архитектурном слое.
Сделай минимальное изменение, которое полностью решает задачу.
Обнови или добавь тесты для изменённого поведения.

Для нетривиальных задач:

Кратко определи затронутые модули и файлы.
Явно зафиксируй ключевые допущения, если есть неоднозначность.
Предпочитай самый безопасный и наименее сложный вариант вместо редизайна.

Если требования неоднозначны:

не придумывай редизайн;
сохраняй текущее поведение, если нет явного запроса на его изменение;
явно фиксируй допущения;
предпочитай production safety «красивым» решениям.

Предпочтение в дизайне решения

По умолчанию предпочитай самое простое и понятное решение, которое корректно удовлетворяет текущим требованиям.

Более сложная архитектура, абстракции, дополнительные слои или более общие конструкции допустимы только тогда, когда более простое решение заметно ухудшит хотя бы одно из следующего:

корректность;
понятность и поддерживаемость;
границы ответственности;
тестируемость;
надёжность;
интеграцию с существующей архитектурой.

Не усложняй решение как подготовку к возможным будущим требованиям. Если есть несколько рабочих вариантов, выбирай наименее сложный, который не ухудшает качество решения.

Базовые предположения по стеку

Язык: Kotlin
Framework: Spring Boot
Возможные интеграции:
- REST
- Kafka
- BPM / Zeebe / Camunda 8
- database persistence
- external HTTP/gRPC APIs

Следуй реальной структуре и библиотекам, уже используемым в репозитории. Не вводи новый стиль, если в проекте уже есть устоявшийся.

Архитектурные границы

Ключевой принцип

Сервис владеет доменным состоянием и бизнес-правилами.

Владение по слоям

controller/api -> только transport
application/service/use case -> orchestration внутри границы сервиса
domain -> бизнес-правила, инварианты, решения
repository/adapter/client -> только persistence и внешняя коммуникация

Где нельзя размещать бизнес-логику

Нельзя размещать доменную бизнес-логику в:

controllers
repository implementations
Kafka listeners / consumers
Zeebe workers
external client adapters
BPMN process definitions

Правила Kotlin

Предпочитай явный и читаемый код.
Делай функции небольшими и отражающими намерение.
Предпочитай val вместо var, если мутация не нужна.
Избегай чрезмерно «умных» chain/scope-function конструкций, если они ухудшают читаемость.
Используй понятные имена; не вводи аббревиатуры без необходимости.
Не вводи DSL-подобный или чрезмерно функциональный стиль, если он не доминирует в проекте.
Сохраняй текущий подход проекта к null-safety.
Не заменяй явные ошибки на null-driven control flow.
Предпочитай прямой и понятный код вместо «умных», слишком универсальных или академичных решений.

Правило комментариев для Kotlin/Spring кода

Комментарии обязательны там, где они реально помогают сопровождению кода:

для публичных функций и публичных контрактов, если их назначение неочевидно из сигнатуры;
для сложных бизнес-правил, инвариантов и ограничений;
для retry / compensation / idempotency / transactional логики;
для неочевидных решений, важных допущений и edge cases;
для переменных и локальных вычислений только тогда, когда без комментария намерение неясно.

Не нужно комментировать каждую переменную или каждую функцию механически. Комментарии должны объяснять цель и reasoning, а не пересказывать синтаксис.

Плохой комментарий:

// increment counter

Хороший комментарий:

// Хранит количество уже выполненных попыток доставки для этой операции, чтобы retry-логика могла определить, нужно ли повторить обработку или отправить сообщение в DLQ.

Правила Spring Boot

Контроллеры должны оставаться тонкими.
Контроллеры должны только:
- принимать и валидировать вход;
- маппить transport-модели;
- вызывать application/service layer;
- возвращать response.
Бизнес-правила не должны жить в контроллерах.
Репозитории не должны содержать бизнес-решения.
Transaction boundaries должны находиться в service/application layer, если модуль уже не использует другой устоявшийся паттерн.
Не выполняй долгий remote I/O внутри DB-транзакций без явной необходимости текущего дизайна.
Переиспользуй существующий стиль Spring-конфигурации, properties, beans, mappers и utilities.

Правила API и error handling

Сохраняй публичные REST/gRPC контракты, если явно не запрошено иное.
Переиспользуй существующий response/error format.
Переиспользуй текущий validation style.
Держи backward compatibility в фокусе.
Если контракт меняется, обнови тесты и nearby examples/docs.
Не используй broad try/catch, скрывающий ошибки.
Не проглатывай исключения.
Не делай silent downgrade ошибок в дефолтные значения.
Следуй существующему exception mapping pattern.
Держи error handling явным и удобным для дебага.
Избегай дублирующих шумных логов для одного и того же failure path.

Правила observability

Для важных бизнес-флоу сохраняй или улучшай:

structured logging;
metrics;
tracing/correlation;
operation identifiers.

Если меняется Kafka/BPM/external integration logic:

сохрани или добавь correlation identifiers;
сохрани или добавь operation_id, где это релевантно;
логируй достаточно для дебага retries, duplicates и compensations;
никогда не логируй секреты или sensitive payloads.

Правила тестирования

Всегда обновляй тесты, если меняется поведение.

Добавляй или обновляй unit tests, если меняются:

business rules;
branching logic;
validation;
idempotency behavior;
retry/compensation behavior.

Добавляй или обновляй integration tests, если меняются:

Spring wiring;
controller behavior;
persistence behavior;
Kafka behavior;
Zeebe worker behavior;
transaction behavior;
external integration behavior.

Каждое bug fix-изменение по возможности должно сопровождаться regression test.

Validation commands

Сначала предпочитай самый маленький релевантный прогон, потом более широкий.

Типичные команды:

./gradlew test
./gradlew ktlintCheck
./gradlew build

Если в репозитории есть module-specific команды, используй их, когда это уместно.

Если команда не была запущена:

точно укажи, какая именно команда не запускалась;
объясни почему;
опиши остаточный риск.

Правила контроля scope

Держи изменения узко ограниченными.

Не делай:

переименование файлов / классов / пакетов без явной необходимости;
перенос кода между модулями без сильной архитектурной причины;
переформатирование несвязанных файлов;
«попутную уборку» соседнего кода без необходимости для задачи;
введение абстракций «на будущее».

Предпочитай:

локальные изменения;
существующие абстракции;
явные, простые, сопровождаемые решения.

Обязательный формат финального ответа

В конце задачи всегда предоставляй:

Changed files
- список изменённых файлов
What changed
- краткое summary реализации
Architecture compliance
- объясни, почему решение соблюдает layer boundaries
- если участвует BPM или messaging, кратко укажи, как соблюдены платформенные требования из docs/standards/PLATFORM_STANDARD.md
Validation
- какие команды запускались
- результаты
Risks / assumptions
- что не было полностью проверено
- compatibility considerations
- edge cases

13 KiB Raw Permalink Blame History