derive-instead-of-transcribing
Всё, что скопировано вручную из другого файла, верно ровно один раз. Если это можно сгенерировать — генерируйте, и роняйте build, когда копия устарела.
Присвоено человеком, который прочитал карточку, а не заявлено файлом о самом себе. Карточка, которую агент выводит во время запуска, поглотившего недоверенное содержимое, рождается заражённой и удерживается на разбор, прежде чем её вообще извлекут.
Когда это вспоминается
- описываю список команд
- копирую значения между проектами
- синхронизирую два файла
- пишу справочную страницу
Ценность обычно лежит в разделах «Избегать» и «Проверить». «Делать» — это раздел, который пишут все.
Текст карточки выше — перевод. Английский оригинал — это то, что импортирует командная строка, что читает агент во время работы и что подтверждает хеш ниже.
Повод
Два места в вашей системе хранят одну и ту же информацию: конфигурация и её документация, схема и клиентские типы к ней, палитра и использующий её сайт, список команд и справочная страница.
Это не относится к случаю, когда вторая копия намеренно другая: курируемое руководство для начинающих не устаревшая копия справочника, это проза с другой задачей.
Делать
- Выберите, что из них источник. Обычно это то, что программа реально читает во время работы.
- Генерируйте второе, коммитя сгенерированный файл, чтобы диффы можно было ревьюить.
- Добавьте шаг CI, который перегенерирует и падает, если закоммиченная копия отличается, с точной командой для запуска в тексте ошибки.
- Штампуйте сгенерированный файл версией или коммитом, из которого он получен, чтобы читатель знал, что именно тот описывает.
Избегать
Держать копию в согласии, помня о ней. Это работает, пока оба файла помещаются в голове одного человека, и кончается на первой же неделе, когда один из них тронет кто-то ещё.
Избегайте и полумеры: генерировать файл, но не ставить на него gate. Артефакт, который перегенерируется иногда, хуже написанного вручную, потому что он несёт авторитет сгенерированного, будучи ровно настолько же протухшим.
И не генерируйте прозу. Справочный материал генерируется хорошо, объяснение — нет, и страница механически развёрнутых описаний полей — это страница, которую никто не читает.
Проверить
Измените источник, не перегенерируйте и запушьте. CI обязан покраснеть и сказать вам, что запустить.
Затем прочтите в сгенерированном файле то, что вы меняли, и убедитесь, что оно там есть: gate доказывает, что файл актуален, а не что генератор захватил интересующее вас поле.
Риск
Сгенерированный артефакт, который никто не может прочесть, обессмысливает затею; если вывод понятен только машине, ему нужен слой отображения, а это ещё код на поддержку.
Есть и цена связанности. Потребитель теперь зависит от формы производителя, и рефакторинг с одной стороны ломает сборку с другой. Обычно в этом и смысл, но это означает, что gate должен быть лёгок в удовлетворении, иначе кто-нибудь отключит его во время постороннего рефакторинга и забудет.
Как применить
Карточка — это данные. Склонируйте репозиторий и импортируйте её по пути: всё, что приходит по сети, считается заражённым и удерживается до одобрения — это и есть желаемое поведение, и поэтому здесь нет установщика в одну строку.
git clone https://github.com/brcampidelli/chimera-agent.gitchimera skills-import chimera-agent/skills/derive-instead-of-transcribing/SKILL.mdЦелостность
SHA-256 файла в опубликованном виде. Импортёр может проверить, что полученное совпадает с показанным на этой странице.
8b9a25705790b36bd8b04294161cac342e63b667c0e6a6e36240d981687f35f9