# AGENTS.md

## Проектные договоренности

### Публичное API библиотек

- Предпочтителен `non-null` подход.
- Там, где значение живет в Gradle Provider API, возвращается `Provider<T>` (не `null`).
- Там, где lookup синхронный, возвращается `Optional<T>` (не `null`).
- `find*` рассматривается как синоним legacy `get*` (поиск без `fail-fast`).
- `require*` это `find*` + `fail-fast` с понятной ошибкой в месте вызова.
- Для нового API предпочтительны формы `find/require`; новые `get*` по возможности не добавлять.
- Интерфейсы и классы, описывающие модели DSL должны иметь суффикс `Spec` у моделей описывающих уровень сервисов и состояние сценария сборки такого суффикса не должно быть.
- Модель расширения на уровне проекта должна иметь суффикс `Extension`.

### Документация

- документирование кода должно быть на английском языке
- к публичному API
  - описание должно отражать назначение, где используется и какое влияние оказывает на остальные части программы
  - давать небольшое описание концепции, а также краткие примеры
- к приватному API достаточно давать краткую справку о назначении и использовании
- реализацию алгоритмов в коде сопровождать комментариями с пояснениями, тривиальные операции пояснять не требуется.
- документация должна формироваться согласно требованиям по форматированию типа javadoc, jsdoc и т.п., в зависимости от используемых в проекте языках и инструментах.

## Identity-first modeling

Prefer an **identity-first** split between:

- **identity objects** used for discovery and selection
- **stateful/materialized objects** obtained through separate API calls

### Rules

- Objects intended for replayable observation (`all(...)`, similar collection APIs) should be **identity objects**.
- Identity objects must be:
  - cheap to create
  - effectively immutable
  - limited to identity and cheap selection metadata
- Heavy, computed, provider-based, or runtime-bound state must be resolved separately.
- Aggregate content should be accessed through dedicated lookup/materialization APIs.
- Eager observation of identity is acceptable.
- Eager observation of computed state is not.

### Do not

- Do not store heavy computed state inside identity objects.
- Do not store runtime references to foreign domains inside identity objects.
- Do not use custom events when replayable identity registries plus on-demand lookup are sufficient.

### Rule of thumb

**Identity objects contain selection metadata.
Aggregate content is obtained separately, on demand.**