@rt-tools/agent-kit 0.1.0 → 0.3.0

package/assets/patterns/angular-patterns-state.md

@@ -0,0 +1,94 @@
+---
+name: angular-patterns-state
+kind: pattern
+rule: angular-patterns
+description: Паттерн правила angular-patterns. Брать при объявлении состояния и потоков в классе фронтового каркаса — реактивные входы и выходы, производные значения, состояние службы, долгоживущая подписка с источником действия. Не брать для раскладки файла компонента — это паттерн component-structure-new.
+---
+
+# Состояние и потоки
+
+Паттерн правила `angular-patterns`. Что при этом должно быть верно — закон
+`{{lawsDir}}/frontend-application.md`.
+
+## Когда брать
+
+- Объявляется состояние компонента или службы.
+- Появляется поток, на который надо подписаться.
+- Значение считается из другого значения.
+
+## Реактивные входы и выходы
+
+```typescript
+public readonly data: InputSignal<Item[]> = input.required<Item[]>();
+public readonly isNarrow: InputSignal<boolean | undefined> = input<boolean>();
+public readonly save: OutputEmitterRef<void> = output<void>();
+
+protected readonly myButton: Signal<ElementRef | undefined> = viewChild<ElementRef>('button');
+```
+
+Декораторной формы входов, выходов и запросов к разметке в дереве нет: у неё нет типа, который
+видно в месте использования, и нет реактивности, на которую можно подписаться.
+
+## Производное значение — вычисляемое, а не эффект
+
+```typescript
+✗ effect((): void => { this.count.set(this.items().length); });
+✓ protected readonly count: Signal<number> = computed((): number => this.items().length);
+```
+
+Эффект, кладущий значение в реактивное поле, — это ручной пересчёт, и он рано или поздно
+отстаёт от источника. Геттера в компоненте не заводить: он пересчитывается на каждой
+перерисовке, и цена его не видна ни в одном месте кода.
+
+## Состояние службы
+
+Наружу — только чтение:
+
+```typescript
+@Injectable({ providedIn: 'root' })
+export class DomainStateService {
+    readonly #items: WritableSignal<Item[]> = signal<Item[]>([]);
+
+    public readonly items: Signal<Item[]> = this.#items.asReadonly();
+    public readonly itemCount: Signal<number> = computed((): number => this.#items().length);
+
+    public addItem(item: Item): void {
+        this.#items.update((items: Item[]): Item[] => [...items, item]);
+    }
+}
+```
+
+## Подписка объявляется один раз
+
+Метод действия толкает значение в источник, подписка живёт при создании владельца:
+
+```typescript
+readonly #loadSource: Subject<void> = new Subject<void>();
+readonly #destroyRef: DestroyRef = inject(DestroyRef);
+
+constructor() {
+    this.#loadSource
+        .pipe(
+            switchMap((): Observable<IResult> => this.#api.getList(this.#query())),
+            takeUntilDestroyed(this.#destroyRef)
+        )
+        .subscribe();
+}
+
+protected reload(): void {
+    this.#loadSource.next();
+}
+```
+
+Оператор выбирается по тому, что делать с предыдущим запросом: список берёт последний ответ,
+кнопка не плодит дублей, независимые строки идут параллельно.
+
+## Частые промахи
+
+- **Подписка внутри метода:** правило линтера отбивает, а вместе с ним отбивается и гонка
+  ответов на быстрых нажатиях.
+- **Подписка без гашения:** она переживает владельца и держит уничтоженный экран в памяти.
+- **Поле-поток без суффикса источника:** поток и значение в коде становятся неотличимы.
+- **Параметры конструктора вместо функции внедрения** — везде, включая базовые классы.
+- **Эффект без снятия слежения там, где зависимость не нужна:** он просыпается на каждое чужое
+  изменение.

package/assets/patterns/api-layer-pair.md

@@ -0,0 +1,78 @@
+---
+name: api-layer-pair
+kind: pattern
+rule: api-layer
+description: Паттерн правила api-layer. Брать при заведении или правке слоя обращения к серверу во фронтовом домене — готовые фасад и служба, единственный вход выборки, общий конвертер страницы, типы порядка и отбора при сущности.
+---
+
+# Фасад и служба домена
+
+Паттерн правила `api-layer`. Что при этом должно быть верно — закон
+`{{lawsDir}}/frontend-application.md`.
+
+## Когда брать
+
+- Заводится слой обращения к серверу у нового домена.
+- Список переводится на общую выборку.
+- Появляется новый обработчик, за которым ходит экран.
+
+## Фасад
+
+Принимает запрос контракта, отдаёт ответ контракта, ожидание заворачивает в поток. Ни выборки,
+ни перевода моделей в нём нет:
+
+```typescript
+@Injectable({ providedIn: 'root' })
+export class EntityApiFacade implements IListApiFacade<TListRequest, TListResponse, TItemResponse> {
+    readonly #client: Client<typeof DomainService> = injectClient(DomainService);
+
+    public getList(request: TListRequest): Observable<TListResponse> {
+        return from(this.#client.listItems(request));
+    }
+}
+```
+
+Метод, которого у домена нет, не объявляется: список читают все, правят не все.
+
+## Служба
+
+Принимает доменные модели, отдаёт их же. Тип контракта до стора и шаблона не доходит:
+
+```typescript
+export class EntityApiService implements IListApiService<IEntity.State, ESortProperty, EFilterProperty, IEntity.Draft> {
+    public getList(query: IEntity.Query): Observable<IEntity.ListResult> {
+        return this.#facade
+            .getList({ query: this.#queryMapper.mapTo(query) })
+            .pipe(
+                map((response: TListResponse): IEntity.ListResult =>
+                    convertPaginationApiModelToStateModel((item: TItem): IEntity.State => this.#mapper.mapFrom(item), response)
+                )
+            );
+    }
+}
+```
+
+Выборка — единственный вход: объект, к которому привязан список, род ленты, состояние подписки
+— это условия отбора, и лежат они в её условиях.
+
+## Типы выборки при сущности
+
+```typescript
+export type Query = IList.Query.State<ESortProperty, EFilterProperty>;
+export type ListResult = IList.Result.State<IEntity.State, ESortProperty, EFilterProperty>;
+```
+
+Перечисления порядка и отбора объявляются рядом с сущностью и повторяют набор имён, по которым
+сортирует и отбирает сервер именно этого домена.
+
+## Частые промахи
+
+- **Промежуточный объект между ответом и моделью:** ответ ложится в конвертер целиком.
+- **Выборка из своего запроса вместо применённой из ответа:** умолчание сервера и отброшенное
+  им условие экран иначе не увидит.
+- **Второй вход рядом с выборкой:** отбор, живущий отдельно, не виден ни стору, ни адресу.
+- **Голая строка в поле порядка:** имя, по которому сервер не сортирует, компилируется и падает
+  запросом.
+- **Один класс на две сущности:** подмена источника одной потянет за собой правку другой.
+- **Служба на обещаниях в новом сторе:** основа списочного стора работает потоками.
+- **Своя копия общих переводчиков страницы, порядка и отбора** — её ловит проверка повторов.

package/assets/patterns/browser-verification-measure.md

@@ -0,0 +1,83 @@
+---
+name: browser-verification-measure
+kind: pattern
+rule: browser-verification
+description: Паттерн правила browser-verification. Брать, когда вывод о вёрстке надо подкрепить числом — готовые замеры, разбивка вычисленного значения по всем узлам, узкий экран вложенной рамкой, ловушки инструмента снимка экрана. Не брать для подъёма стенда — это паттерн browser-verification-stand.
+---
+
+# Замер вместо взгляда
+
+Паттерн правила `browser-verification`. Что при этом должно быть верно — закон
+`{{lawsDir}}/verifiability.md`.
+
+## Когда брать
+
+- Правилась вёрстка, и надо подтвердить результат.
+- Экран выглядит не так, а искать нечего: поиск по коду отвечает «чисто».
+- Проверяется узкий экран.
+
+## Вывод подкрепляется числом
+
+Вычисленный стиль, прямоугольник элемента, контраст, совпадение центров, попадание в видимую
+область. «Выглядит нормально» результатом проверки не является.
+
+Замер отвечает только на тот вопрос, который задали. Совпадение перечисленных свойств ничего не
+говорит о правиле, которого в списке замера нет. Если исходники образца доступны, расхождение
+ищется чтением, а замер остаётся проверкой результата.
+
+Вид элемента, которого сегодня не видно ни на одном экране, замером не подтверждается, и
+правило о нём остаётся гипотезой.
+
+## Значение, которого в коде нет
+
+Гарнитуру, межстрочный интервал, цвет и оформление элементам формы задаёт браузер, и в дереве
+этих значений нет. Поиск по коду на такой дефект отвечает «чисто», линтер и сборка молчат.
+Ищется разбивкой вычисленного значения по всем узлам страницы, а не замером у пары элементов:
+
+```javascript
+[...document.querySelectorAll('*')].reduce((acc, el) => {
+    const key = getComputedStyle(el).fontFamily;
+    acc[key] = (acc[key] ?? 0) + 1;
+    return acc;
+}, {});
+```
+
+Счёт годится любому наследуемому свойству: смотрится не одно значение, а число узлов с
+неожиданным. Так находятся десятки элементов, набранных не той гарнитурой, — по одному их не
+заметил бы никто.
+
+## Узкий экран
+
+Изменение размера окна не работает, когда браузер в полноэкранном режиме: инструмент рапортует
+успех, ширина не меняется, медиазапросы остаются широкими. Узкие ширины проверяются во
+вложенной рамке нужной ширины — внутри неё запрос ширины считается от рамки, и рамка своей
+толщиной уменьшает внутреннюю ширину.
+
+Правка числа элементов в контейнере — это правка раскладки: она проверяется на узкой ширине, а
+не только кодами ответа.
+
+## Ловушки инструмента снимка экрана
+
+- **Координаты нажатия — координаты снимка, а не страницы.** При широком окне снимок приходит
+  уже, и нажатие по «увиденной» координате уходит мимо, давая ложный сигнал: пересчитывать по
+  фактическому масштабу либо целиться поиском элемента.
+- **Область приближения должна целиком лежать внутри видимой области.**
+- **Между нажатиями обязательно ожидание:** цикл «нажал — прочитал разметку» без него читает
+  состояние до перерисовки и возвращает устаревшие значения.
+- **Выбор браузера протухает.** На длинной проверке это срабатывает посреди работы — не сбой
+  стенда, а повод повторить вызов и продолжить.
+
+## Поведение маршрутизации воспроизводится нажатиями
+
+Подстановка адреса, программный переход и заход по прямой ссылке поднимают приложение заново, и
+накопленного состояния — открытой панели, стража прошлого экрана — у него нет. Чистый проход по
+адресам читается как «дефект не подтверждается».
+
+## Частые промахи
+
+- **Комментарий в конфиге — гипотеза наравне с прочими.** Утверждение о поведении кэша
+  переживает несколько кругов разбора кода и опровергается одним запросом.
+- **Вывод «дефекта нет, это кэш» закрывает разбор**, поэтому принимается только после проверки
+  на чистой сборке.
+- **Дефект в клиентском куске от компиляции до правки выглядит как дефект кода** — признак
+  сборки для разработки — имена файлов без хеша.

package/assets/patterns/browser-verification-stand.md

@@ -0,0 +1,79 @@
+---
+name: browser-verification-stand
+kind: pattern
+rule: browser-verification
+description: Паттерн правила browser-verification. Брать, когда нужен честный стенд — прод-сборка, стенд под настоящим прокси, вход в приложение, разбор того, что висит на порту, стенд серверной стороны с переменными окружения. Не брать для замеров вёрстки — это паттерн browser-verification-measure.
+---
+
+# Честный стенд
+
+Паттерн правила `browser-verification`. Что при этом должно быть верно — закон
+`{{lawsDir}}/verifiability.md`.
+
+## Когда брать
+
+- Проверяется то, чего на сервере разработки не видно: разметка от сервера, локали, кэш,
+  перенаправления, заголовки, размер сборки.
+- Порт отвечает не тем, чего ждали.
+- Нужен вход в приложение.
+
+## Сначала — что отвечает на порту
+
+До первого запроса, а не после непонятного ответа:
+
+```bash
+lsof -nP -iTCP:<порт> -sTCP:LISTEN
+```
+
+На порту регулярно висит собранный артефакт из прошлой сессии: он отвечает успехом на старом
+коде, а заведённого в ветке обработчика у него нет вовсе. Таких процессов бывает несколько, и
+снимать надо все — по идентификатору из вывода, каждый: завершение по шаблону команды не
+попадает ни в один.
+
+## Прод-сборка
+
+Собранный сервер поднимается прямо, а не через сервер разработки: гард ловит запуск сервера
+разработки, пакетные раннеры и статические серверы, а запуск собранного сервера пропускает.
+
+Приложению, отдающему статику, нужен явный базовый адрес — без него стенд отдаёт пустую
+страницу без единой ошибки в консоли. Стенду, на котором нужны отладочные инструменты каркаса,
+нужна сборка для разработки: прод-сборка их не публикует. Выводы о размере сборки и минификации
+на такой сборке делать нельзя.
+
+## Вход в приложение
+
+Сессия кладётся в хранилище браузера ровно в той форме, в какой её читает приложение: значение,
+записанное иначе, приложение молча не увидит. Токен не подписывается руками, а берётся у живого
+сервера входом.
+
+Взять уже открытую сессию нельзя: чтение хранилища чужого профиля блокируется. Оба пути к
+своему стенду упираются в пароль, поэтому остаётся третий — смотреть там, где вход уже сделан.
+Свой стенд нужен, только когда проверяют прод-сборку, базовый адрес или конфиг прокси; чтобы
+просто посмотреть экраны, он не нужен.
+
+## Стенд серверной стороны
+
+Собранный артефакт поднимается на свободном порту, а не на рабочем: на рабочем отвечает сервер
+владельца, и окружение у него не то, которое проверяется.
+
+Переменные окружения задаются в самой команде, по одной на проверяемый случай. Отказ на старте
+— такой же результат проверки, как успешный ответ: приложение, упавшее при сборке зависимостей,
+порт не слушает вовсе, и это видно по списку слушателей, а не по тексту в консоли.
+
+Обработчик зовётся полным именем, как его объявляет контракт. Токен подписывается руками только
+там, где проверяется сама подпись; во всех остальных случаях он берётся у живого сервера входом
+— рукописный скрывает расхождение состава притязаний.
+
+## Стенд под настоящим прокси
+
+Кэш, перенаправления и заголовки живут в конфиге прокси, а не в приложении, и любой вывод о них
+с голого сервера отдачи страниц неверен. Устройство такого стенда — паттерн `testing-e2e`.
+
+## Частые промахи
+
+- **Порт занят чужой сборкой, а ответ читается как дефект ветки.** Сначала список слушателей,
+  потом запрос.
+- **Стенд без явного базового адреса отдаёт пустую страницу** и ни одной ошибки при этом не
+  печатает.
+- **Токен, подписанный руками, скрывает расхождение состава притязаний** — вход берётся у
+  живого сервера.

package/assets/patterns/component-structure-new.md

@@ -0,0 +1,98 @@
+---
+name: component-structure-new
+kind: pattern
+rule: component-structure
+description: Паттерн правила component-structure. Брать при заведении или правке файла компонента — порядок свойств декоратора, группировка импортов, раскладка полей класса, договорённости шаблона и якорь для спек. Не брать для состояния и потоков — это паттерн angular-patterns-state.
+---
+
+# Файл компонента
+
+Паттерн правила `component-structure`. Что при этом должно быть верно — закон
+`{{lawsDir}}/frontend-application.md`.
+
+## Когда брать
+
+- Заводится новый компонент.
+- Правится декоратор, список импортов или шаблон существующего.
+
+## Декоратор: порядок свойств
+
+```typescript
+@Component({
+    selector: '<префикс>-component-name', // 1. селектор
+    templateUrl: './component-name.component.html', // 2. шаблон
+    styleUrl: './component-name.component.scss', // 3. стиль, в единственном числе
+    changeDetection: ChangeDetectionStrategy.OnPush, // 4. стратегия перерисовки
+    imports: [
+        // 5. импорты, группами
+        // каркас
+        FormsModule,
+
+        // директивы разметки
+        BlockDirective,
+        ElemDirective,
+
+        // компоненты
+        SomeChildComponent,
+    ],
+    providers: [], // 6. провайдеры
+    host: { class: '<префикс>-component-name' }, // 7. привязки хоста
+})
+export class ComponentNameComponent {
+    readonly #someService: SomeService = inject(SomeService);
+
+    public readonly data: InputSignal<Item[]> = input.required<Item[]>();
+    public readonly save: OutputEmitterRef<void> = output<void>();
+
+    protected readonly items: WritableSignal<Item[]> = signal<Item[]>([]);
+    protected readonly itemCount: Signal<number> = computed((): number => this.items().length);
+}
+```
+
+Группирующие комментарии в импортах обязательны: без них список растёт вперемешку, и первое,
+что в нём теряется, — свои компоненты среди чужих.
+
+## Шаблон
+
+- Самозакрывающиеся теги у компонентов без содержимого.
+- Лишних обёрток нет — корнем работает хост, класс блока приходит его привязкой.
+- Сложный шаблон объявляет блок в корне отдельной директивой.
+- Один компонент в обеих ветках условия — это условная привязка:
+
+```html
+<!-- ✗ -->
+@if (isRangeMode()) {
+<calendar [rangeMode]="true" />
+} @else {
+<calendar [rangeMode]="false" />
+}
+
+<!-- ✓ -->
+<calendar [rangeMode]="isRangeMode()" />
+```
+
+- Прокрутка по документу — средствами маршрутизатора, а не ссылкой на фрагмент: при объявленном
+  базовом адресе браузер разрешает фрагмент относительно него и уходит в полную навигацию.
+
+## Якорь для спек — на каждый интерактивный элемент
+
+```html
+<button qa-dataid="calendar-retry-prices" type="button" (click)="retryPrices.emit()">Повторить</button>
+<div rtElem="grid" qa-dataid="admin-calendar-grid"></div>
+```
+
+- Значение — через дефис, по смыслу элемента, без имени компонента-обёртки.
+- Уникальность — в пределах экрана; повторяющиеся элементы списка носят один якорь и
+  различаются атрибутами данных.
+- Декоративный элемент помечается признаком пропуска на самом теге.
+
+## Частые промахи
+
+- **Чужой префикс селектора** — компонент перестаёт узнаваться как свой.
+- **Множественная форма свойства стилей вместо единственной** — стиль молча не подключается.
+- **Вызов метода в привязке** — отбивается линтером; замена — вычисляемое значение, а там, где
+  оно зависит от контекста шаблона, — чистый преобразователь.
+- **Обёртка, которая существует только чтобы быть контейнером раскладки вокруг всех детей:** её
+  раскладка уезжает на хост.
+- **Глубокий относительный импорт между либами** вместо алиаса.
+- **Своя разметка вместо готового компонента** — правило `reuse-first`.

package/assets/patterns/doc-style-sweep.md

@@ -0,0 +1,100 @@
+---
+name: doc-style-sweep
+kind: pattern
+rule: doc-style
+description: Паттерн правила doc-style. Брать, когда документ накопил список работ и его надо разобрать на действующее и закрытое — признак отбора, обход по утверждениям, сверка с очередью работ, измерение потерь, куда девать доводы за отсрочку и судьба самого файла. Не брать для написания нового текста — это паттерн doc-style-write.
+---
+
+# Разбор документа, накопившего список работ
+
+Паттерн правила `doc-style`. Что при этом должно быть верно — закон
+`{{lawsDir}}/project-documentation.md`, статья о том, что предстоящая работа перечислена в одном
+месте.
+
+## Когда брать
+
+- Документ перечисляет, что осталось сделать, а очередь работ перечисляет то же самое.
+- Файл вырос настолько, что его перестали читать целиком.
+- Планы лежат вперемешку: часть исполнена, часть нет, и по тексту это не различить.
+
+## Признак отбора — один, и он решается до первой правки
+
+**Утверждение остаётся в документе, если править его никто не собирается.** Всё остальное —
+работа, и её место в очереди работ.
+
+| Что нашлось                                             | Куда                                                            |
+| ------------------------------------------------------- | --------------------------------------------------------------- |
+| дыра, которую будут чинить                              | задача; строка из документа уходит                              |
+| дыра, которую решено не чинить                          | остаётся, вместе с причиной                                     |
+| условный отказ («заведём, если случай окажется частым») | остаётся                                                        |
+| вывод разбора, не ставший правилом                      | остаётся                                                        |
+| описание сделанного                                     | удаляется без переноса: о нём говорят закрытые задачи и история |
+| утверждение, разошедшееся с деревом                     | удаляется как протухшее, а не переносится в задачу              |
+
+Спрашивать владельца об этом наборе не нужно — он записан здесь. Спрашивать стоит одно: судьбу
+самого файла, когда в нём не осталось ничего.
+
+## Обход идёт по утверждениям, а не по пунктам
+
+Работа лежит и в прозе: раздел без единого маркера обход по списку не увидит вовсе. Абзац
+судится тем же признаком, что и пункт.
+
+## Номер задачи стоит в нескольких местах
+
+Прежде чем считать «пункты без задачи», надо знать все формы записи — в заголовке, отдельной
+строкой у раздела и в конце пункта. Разбор, знающий одну форму, ошибается молча. **Число,
+полученное разбором текста, сверяется на выборке руками до того, как его называют.**
+
+## Сверка с очередью работ
+
+У пункта есть задача — это ещё не значит, что задача несёт его содержание. Перед удалением
+меряется покрытие: сколько значимых слов пункта встречается в теле его задачи. Пункт, покрытый
+наполовину и меньше, читается глазами и разводится на три исхода:
+
+- живое уточнение, которого в задаче нет, — дописать в тело;
+- другой дефект — завести своей задачей;
+- протухшее — удалить, **не** перенося. Иначе разбор занесёт в задачу ложь.
+
+**Наследование номера от заголовка — предположение, а не факт.** Пункт под заголовком с
+несколькими номерами не принадлежит ни одному из них: привязка проверяется чтением.
+
+## Сделанность читается по дереву
+
+Утверждение о том, что задача не сделана, стареет так же, как любое другое. Проверяется то, о
+чём собираешься сказать «не сделано», — поиском по дереву, а не памятью.
+
+## Доводы за отсрочку — это «чего это стоит»
+
+Раздел «что стоит отложить» переезжает не в архив, а **в тела тех задач, которых он касается**:
+там он и есть оценка цены. В файле он остаётся, только если отсрочка — решение владельца, а не
+предложение разбора. Признак — записанный ответ владельца с датой.
+
+## Ссылки на снятые разделы
+
+Задача, чьё тело ссылается на раздел документа, после разбора ведёт в пустоту, и проверка путей
+этого не видит: она читает файлы репозитория, а не тела задач. Строка снимается тем же заходом.
+
+## Судьба файла
+
+- Осталось незадачное — файл живёт, и его вступление объявляет новый признак отбора.
+- Не осталось ничего, а документ описывал состоявшуюся работу — уезжает в архив.
+- Не осталось ничего, и это был список работ — удаляется.
+
+Разбор целиком — одна задача и одна ветка: делится то, что придётся откатывать порознь, а здесь
+откат общий. Правка кода, найденная по дороге, в эту ветку не идёт — иначе откат разбора унесёт
+починку.
+
+## Что чинится в дереве следом
+
+Документ — не единственное место, обещающее, что работа живёт в нём. Снятое имя вычищается одним
+проходом по всему дереву, включая описания ролей, скилы, README и комментарии в коде.
+
+## Частые промахи
+
+- Обход по маркированным пунктам: половина работы лежит прозой и переживает разбор.
+- «На это есть задача» без чтения её тела: пункт удалён, содержание потеряно.
+- Число пунктов названо владельцу до сверки на выборке.
+- Протухшее утверждение перенесено в задачу и стало действующим указанием.
+- Доводы за отсрочку оставлены в документе: он снова становится вторым списком работ.
+- Разбор поделён на несколько задач «по объёму» — признак деления не объём, а раздельный откат.
+- Архив тронут: он описывает состояние на момент написания и под новые термины не правится.

package/assets/patterns/doc-style-write.md

@@ -0,0 +1,106 @@
+---
+name: doc-style-write
+kind: pattern
+rule: doc-style
+description: Паттерн правила doc-style. Брать при написании любой прозы проекта — правил, спеков, README, комментариев в коде, тел коммитов, описаний PR. Примеры «так» и «не так» на каждую договорённость о формулировке. Не брать для устройства спека — это правило spec-driven.
+---
+
+# Как формулировать
+
+Паттерн правила `doc-style`. Что при этом должно быть верно — закон
+`{{lawsDir}}/project-documentation.md`.
+
+## Когда брать
+
+- Пишется правило, статья закона, пункт спека или README.
+- Пишется комментарий в коде, тело коммита, описание PR.
+
+## Статья — одна фраза
+
+Сама статья укладывается в одно предложение. Следом — не больше двух предложений о том, что
+сломается иначе, и только если из самой фразы это не видно. Обоснование, у которого была
+альтернатива, идёт в «Ловушки» правила, а не в закон: разросшийся пункт читают по диагонали, а
+закон говорит, что верно, — не почему когда-то выбрали так.
+
+```
+✗ **Взрослых в записи хотя бы один — на любом пути записи, без исключений.** Нижнюю
+  границу держит хранилище: путей записи три, и проверка в одном из них закрывает не все.
+  Верхнюю ограничением хранилища не выразить — она лежит в самой записи и меняется
+  владельцем.
+
+✓ **Взрослых в записи хотя бы один.** Исключений нет.
+✓ **Взрослые и дети не превышают вместимость.**
+```
+
+## Что верно, а не где это держится
+
+«Держит хранилище, а не служба», «проверяется в транзакции», «умолчание колонки», «на трёх
+путях записи из четырёх», имена функций и колонок внутри фразы — это устройство кода. Читателю
+нужно знать, **что** верно.
+
+Место исполнения меняется при первом же переносе, и документ, который его называет, устаревает
+молча. Для него заведён отдельный файл — `implementation.md` рядом с правилом.
+
+Исключение — «Ловушки» правила: там устройство кода называется прямо, потому что ловушка и есть
+место, где на него наступают.
+
+## Без утверждений о будущем
+
+«Не планируется», «не будет», «отдельная задача по запросу» — это намерение владельца, а не
+свойство системы. Что не сделано — да, почему не сделано — да, что не будет сделано никогда —
+нет.
+
+Ошибка беззвучная: сверять утверждение о будущем не с чем, оно проходит любую проверку.
+
+Отсюда же: того, чего нет в документе о продукте, пересказ не утверждает. Домысел при пересказе
+звучит убедительнее исходника — он короче и категоричнее.
+
+## Простыми словами
+
+Афоризмы, метафоры и инверсии затрудняют чтение и ничего не добавляют.
+
+```
+✗ запись о прошлом не должна упираться в правило, появившееся позже
+✗ пустой список без текста и отказ без кнопки выглядят одинаково — как сломанная страница
+
+✓ запись, внесённую владельцем, пропажа события из ленты не снимает
+✓ у пустого списка должен быть текст, у отказа — кнопка повтора
+```
+
+Проверка: прочитать фразу вслух. Если так не говорят — переписать.
+
+## Факт проверяется, а не вспоминается
+
+Перед тем как написать, что код делает то-то, — открыть код и посмотреть. Пересказ по памяти
+выглядит так же уверенно, как проверенное утверждение, и отличить их потом нечем.
+
+Особенно это касается отказов: недостижимый отказ, названный в документе, живёт там годами —
+проверить его читателю нечем.
+
+## Не пересказывать то, у чего есть источник
+
+- типы и поля контракта — ссылкой на сам контракт;
+- колонки и индексы — ссылкой на схему хранилища;
+- числа, которые правит владелец, — только как они применяются;
+- слои и имена классов — правило `lib-layers` и сам код.
+
+## Комментарии в коде
+
+Те же правила. Комментарий отвечает на вопрос «почему так, а не иначе» — если ответ неочевиден.
+Что делает строка, видно из строки.
+
+Многострочный комментарий над каждой функцией — признак того, что объяснение подменило имя.
+Сначала переименовать, потом писать комментарий.
+
+Комментарий, оправдывающий отклонение от правила, держит это отклонение на себе: пока
+объяснение выглядит убедительно, отклонение не трогают. Факт в нём проверяется, когда
+комментарий пишут, и перепроверяется, когда отклонение снимают.
+
+## Частые промахи
+
+- Чужой проект назван в коммите, PR, комментарии или документе. Ни имени репозитория, ни
+  «портировано из», ни ссылок на его файлы — нигде.
+- Число написано по памяти, а не пересчитано командой в том же коммите.
+- Пункт плана вычеркнут по памяти о работе, а не по дереву.
+- Формулировка звучит как заголовок, а не как статья: «работа со скидками» нарушить нельзя,
+  «применяется одна максимальная скидка» — можно.