Типы записей
Правило, факт, ловушка: три вида знания, различимых по тому, что каждый меняет для того, кто его прочитал.
Типов три, и они отличаются не «жанром», а тем, что меняется для того, кто прочитал запись.
| Тип | Что это меняет для читателя |
|---|---|
| Правило | «Соблюдать всегда» — так решили работать |
| Факт | «Знать, как здесь устроено» — этого никто не выбирал, так есть |
| Ловушка | «Наткнёшься — вот обход» — препятствие и способ его пройти |
Правило
Соблюдать всегда. Норма, которую задал человек: как здесь принято работать.
«Обязательно YAGNI: не делаем «на будущее»» «Отвечаем и комментируем по-русски, имена сущностей — английские» «Не добавлять зависимости без согласования»
Сюда же — принятые решения, если они предписывают, как поступать: «публикуем в апстрим только через PR, потому что…». Причина в теле записи важнее самого решения: без неё через месяц отменённый подход предложат снова.
Правила пишет человек. ИИ правил не заводит: его дело — наблюдения, а не установки. Для модели правило, написанное человеком, — инструкция, а не подсказка.
Факт
Знать, как здесь устроено. То, что не выводится из кода за разумное время — и то, что никто не выбирал: оно просто так есть.
«Это проект по реверс-инжинирингу протокола такого-то» «Модуль отчётов — легаси, его переписывают, крупные правки туда не нужны» «Оплата ходит через внешний шлюз; тестовый стенд — по такому-то адресу, доступ по VPN»
Адреса стендов, дашбордов и документов — тоже факты: они описывают, где что лежит.
Факты пишут и люди, и ИИ.
Ловушка
Наткнёшься — вот обход. Воспроизводимое препятствие вместе со способом его пройти.
«Тесты падают без поднятого окружения: сначала поднять, потом прогонять» «Импорт большого файла отваливается по таймауту — грузить частями»
Ловушки чаще всего пишет ИИ: он на них и наступает. От факта ловушка отличается тем, что несёт действие: не «так устроено», а «если упрётся — сделай так».
Как выбрать за секунду
Спросите себя, что должно произойти в голове у того, кто это прочтёт:
- должен так делать → правило;
- должен это учитывать → факт;
- должен знать обход, если упрётся → ловушка.
Почему типов именно три
Раньше их было пять: были ещё «ссылка» и «договорённость». Обе оказались частными случаями. Адрес стенда — это факт о проекте, а принятое решение — либо правило («делаем так»), либо факт («теперь всё устроено так»). Лишний выбор в форме не добавлял точности, он добавлял сомнение — какой из пяти взять. Три вида, различимых по действию, выбираются без раздумий.