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* по возможности не добавлять.

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.