Дмитрий Соловьев
274 lines
13 KiB
Markdown
274 lines
13 KiB
Markdown
# 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`.
|
|
|
|
---
|
|
|
|
## Обязательный стиль работы
|
|
|
|
Перед внесением изменений:
|
|
|
|
1. Найди похожую реализацию в том же модуле, сервисе или соседнем слое.
|
|
2. Следуй уже принятому стилю проекта и существующей структуре.
|
|
3. Прочитай полный execution path до редактирования кода.
|
|
4. Держи решение в правильном архитектурном слое.
|
|
5. Сделай минимальное изменение, которое полностью решает задачу.
|
|
6. Обнови или добавь тесты для изменённого поведения.
|
|
|
|
Для нетривиальных задач:
|
|
|
|
1. Кратко определи затронутые модули и файлы.
|
|
2. Явно зафиксируй ключевые допущения, если есть неоднозначность.
|
|
3. Предпочитай самый безопасный и наименее сложный вариант вместо редизайна.
|
|
|
|
Если требования неоднозначны:
|
|
- не придумывай редизайн;
|
|
- сохраняй текущее поведение, если нет явного запроса на его изменение;
|
|
- явно фиксируй допущения;
|
|
- предпочитай 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
|
|
|
|
Держи изменения узко ограниченными.
|
|
|
|
Не делай:
|
|
- переименование файлов / классов / пакетов без явной необходимости;
|
|
- перенос кода между модулями без сильной архитектурной причины;
|
|
- переформатирование несвязанных файлов;
|
|
- «попутную уборку» соседнего кода без необходимости для задачи;
|
|
- введение абстракций «на будущее».
|
|
|
|
Предпочитай:
|
|
- локальные изменения;
|
|
- существующие абстракции;
|
|
- явные, простые, сопровождаемые решения.
|
|
|
|
---
|
|
|
|
## Обязательный формат финального ответа
|
|
|
|
В конце задачи всегда предоставляй:
|
|
|
|
1. `Changed files`
|
|
- список изменённых файлов
|
|
|
|
2. `What changed`
|
|
- краткое summary реализации
|
|
|
|
3. `Architecture compliance`
|
|
- объясни, почему решение соблюдает layer boundaries
|
|
- если участвует BPM или messaging, кратко укажи, как соблюдены платформенные требования из `docs/standards/PLATFORM_STANDARD.md`
|
|
|
|
4. `Validation`
|
|
- какие команды запускались
|
|
- результаты
|
|
|
|
5. `Risks / assumptions`
|
|
- что не было полностью проверено
|
|
- compatibility considerations
|
|
- edge cases
|