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`. Правилом это не