keep-the-caveat-with-the-number
Число и оговорка к нему должны быть одним артефактом. Два абзаца расходятся; один компонент — не может.
Присвоено человеком, который прочитал карточку, а не заявлено файлом о самом себе. Карточка, которую агент выводит во время запуска, поглотившего недоверенное содержимое, рождается заражённой и удерживается на разбор, прежде чем её вообще извлекут.
Когда это вспоминается
- публикую результат бенчмарка
- вставляю метрику в страницу
- цифре нужен контекст
- подвожу итог измерения
Ценность обычно лежит в разделах «Избегать» и «Проверить». «Делать» — это раздел, который пишут все.
Текст карточки выше — перевод. Английский оригинал — это то, что импортирует командная строка, что читает агент во время работы и что подтверждает хеш ниже.
Повод
Вы помещаете измеренную цифру туда, где её увидит читатель: в README, на лендинг, в release notes, на дашборд, в отчёт. Цифра верна, и рядом с ней нужна фраза, чтобы она не вводила в заблуждение: выборка была мала, срез был лёгким, эффект не значим, бенчмарк был наш собственный.
Это не относится к цифре, чей смысл полон сам по себе. «Сборка заняла 41 секунду» не требует ничего.
Делать
- Пишите оговорку раньше числа. Если вы не можете изложить ограничение одним предложением, вы ещё недостаточно понимаете измерение, чтобы его публиковать.
- Прикрепляйте оговорку структурно. В тот же компонент, ту же строку таблицы, тот же возврат функции — во что-то, что не может отрендерить цифру без неё.
- Ставьте её выше числа или рядом с ним. Не ниже.
- Делайте само число выводимым: читайте его из артефакта, произведённого измерением, чтобы оно двигалось вместе с измерением.
Избегать
Число в заголовке, а оговорка в сноске, под звёздочкой, в свёрнутом блоке или в следующем абзаце. Всё это один и тот же баг в разной стилизации: читатель сначала формирует убеждение, а поправка, пришедшая позже, вынуждена преодолевать уже существующее убеждение.
Избегайте и второго порядка — компонента, который может отрендерить цифру с опущенной оговоркой. Если уточнение — необязательный аргумент, его опустят, и опустит его тот, кто ужимал абзац и вовсе не собирался менять смысл.
И не пересказывайте оговорку, написанную тщательно. Именно при переформулировке «не значимо само по себе» превращается в «близко к значимости».
Проверить
Попробуйте написать число без оговорки и посмотрите, как это не получится. Удалите аргумент с уточнением или поставьте голую цифру на страницу и запустите сборку.
Если собралось — связка держится на договорённости, а не на механизме, а договорённости живут ровно до тех пор, пока никто не торопится.
Риск
При избыточном применении обычная отчётность тяжелеет: не всякое число — бенчмарк, а оговорка при цифре, которая в ней не нуждается, приучает людей оговорки пропускать.
Более трудный риск в том, что механизм ощущается полным ответом. Компонент, всегда рендерящий какую-то оговорку, не проверяет, та ли это оговорка. Написать фразу честно всё равно должен человек; механизм лишь не даёт её потом выбросить.
Как применить
Карточка — это данные. Склонируйте репозиторий и импортируйте её по пути: всё, что приходит по сети, считается заражённым и удерживается до одобрения — это и есть желаемое поведение, и поэтому здесь нет установщика в одну строку.
git clone https://github.com/brcampidelli/chimera-agent.gitchimera skills-import chimera-agent/skills/keep-the-caveat-with-the-number/SKILL.mdЦелостность
SHA-256 файла в опубликованном виде. Импортёр может проверить, что полученное совпадает с показанным на этой странице.
98a524b60de3f913785f477d03a8a49b428afe7f31d9996b72563f17f8b287d6