Init
This commit is contained in:
Дмитрий Соловьев
@@ -0,0 +1,273 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user