From 7fb60828db5af59449d73dc3720bfbb712755cf4 Mon Sep 17 00:00:00 2001 From: Anton Vakhrushev Date: Mon, 27 Jul 2026 08:57:35 +0300 Subject: [PATCH] =?UTF-8?q?guide:=20=D0=B3=D1=80=D0=B0=D0=BD=D0=B8=D1=86?= =?UTF-8?q?=D0=B0=20=D1=81=D0=BE=20=D1=81=D0=BF=D0=B5=D0=BA=D0=BE=D0=B9=20?= =?UTF-8?q?=D0=BF=D0=B5=D1=80=D0=B5=D0=BF=D0=B8=D1=81=D0=B0=D0=BD=D0=B0=20?= =?UTF-8?q?=D0=BD=D0=B0=20=D1=82=D0=B5=D1=81=D1=82=20=D0=BD=D0=B0=D0=B1?= =?UTF-8?q?=D0=BB=D1=8E=D0=B4=D0=B0=D0=B5=D0=BC=D0=BE=D1=81=D1=82=D0=B8=20?= =?UTF-8?q?=D0=B2=D0=B5=D1=80=D0=B4=D0=B8=D0=BA=D1=82=D0=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - «что против как» на пограничных правилах не работает: capability проверяется снаружи работающей системы, конвенция — только в исходном тексте, и отсюда расходятся направление, распространение и шкала - добавлен признак для спорного случая: обязательство перед внешним потребителем — в спеку, зависимость автора следующего патча — в конвенцию --- GUIDE.md | 24 +++++++++++++++++++++--- 1 file changed, 21 insertions(+), 3 deletions(-) diff --git a/GUIDE.md b/GUIDE.md index 98b9722..b24872d 100644 --- a/GUIDE.md +++ b/GUIDE.md @@ -30,13 +30,31 @@ prefix: META - `docs/adr/` — **решение**, принятое однажды и постфактум («почему выбрали Authelia, а не Keycloak»). Запись неизменяема. -- `docs/specs/` и OpenSpec, где они есть, — **что** система делает, - наблюдаемое поведение как контракт. Конвенция — **как** написан код; - в спеки она не переносится, это не capability. +- `docs/specs/` и OpenSpec, где они есть, — контракт наблюдаемого поведения. + Конвенция в спеки не переносится: это не capability. - `docs/drafts/` — оперативная хроника и черновики, «что собираюсь сделать». - `docs/conventions/` — **правило на будущее**, применяемое многократно. Живой документ: правится, когда договорённость меняется. +Со спекой конвенцию путают чаще прочего, а «что против как» на границе не +работает. Разводит их то, **где наблюдается вердикт**. У capability он виден +снаружи работающей системы: подали вход, получили выход, совпало или нет. У +конвенции — только в исходном тексте: снаружи не различить, обёрнута ошибка +или проглочена и по какому признаку выбран уровень записи. + +Отсюда расходится остальное. Спека едет за системой — изменилось поведение, +меняется контракт; конвенция ведёт код, и факт «в приложении уже иначе» +аргументом не считается (META-5), а утверждений о состоянии репозитория в ней +нет вовсе (META-4). Спека принадлежит одной системе; конвенция ездит копиями +и потому знает про темы, слои и локальную часть. Capability бинарна — +реализована или нет; у конвенции есть ступени и постоянный список отступлений +(META-13). Спеку пишут до кода, конвенцию — на третий раз (META-2). + +Пограничное правило разбирается признаком внешнего потребителя. Формат логов, +который собирает чужой агрегатор, — обязательство перед кем-то снаружи, и +место ему в спеке. Если от правила зависит только автор следующего патча — +это конвенция. + ## Оформление Имя файла повторяет имя темы: `app-directories.md`. Правилом это не