guide: граница со спекой переписана на тест наблюдаемости вердикта

- «что против как» на пограничных правилах не работает: capability
  проверяется снаружи работающей системы, конвенция — только в исходном
  тексте, и отсюда расходятся направление, распространение и шкала
- добавлен признак для спорного случая: обязательство перед внешним
  потребителем — в спеку, зависимость автора следующего патча — в конвенцию
This commit is contained in:
av
2026-07-27 08:57:35 +03:00
parent 9c86d9f2de
commit 7fb60828db
+21 -3
View File
@@ -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`. Правилом это не