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.