AGENTS.md
42 lines
| 1.8 KiB
| text/x-minidsrc
|
MarkdownLexer
cin
|
r29 | # 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*` по возможности не добавлять. | ||||
|
cin
|
r39 | |||
| ## 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.** | ||||