Два мажора, один README, одно демо: два почти бесплатных дизайн-ревью

В сфере искусственного интеллекта произошло заметное событие. mellonis 29 минут назад Два мажора, один README, одно демо: два почти бесплатных дизайн-ревью Средний 6 мин 1. 3K Проектирование и рефакторинг * JavaScript * Программирование * Проектирование API * Качество кода * Мнение Именно работа над документацией вскрыла обе ошибки. Тут есть мета-урок: документация — самое дешёвое дизайн-ревью, которое можно у себя устроить, но это уже тема для другого поста.

Это и есть тот самый «пост», другая статья — и первое, что ей нужно сделать, это поправить тизер. Документация поймала только одну из двух ошибок. Вторую поймал первый настоящий потребитель API, которого я собирал параллельно.

Технические детали

Эти два ревью сработали в паре: документация смотрит на форму API, потребитель — на использование. Вместе они ловят то, чего не видят тесты. Если вы выпускаете что угодно за интерфейсом — библиотеку, CLI, любую сущность за контрактом, — это два ревью, которые вы, скорее всего, не оставляете без внимания.

Напоминание«Три мажора, две ошибки» разбирает движок и v4-API паузы — onStep, onDebugBreak, флаги debug на состояниях. Здесь я опираюсь на неё, не повторяясь слишком. Траектория v4 → v6 включает три брейкинг-мажора: переименование хука, ужесточение семантики halt и схлопывание lifecycle-тиков.

Первые два всплыли в демо. Третий — в документации. Демо: v4 → v5Пока v4 уезжала в релиз, я начал собирать machines-demo — интерактивный отладчик Turing-машины и первый не-тестовый клиент движка.

Отраслевые последствия

Демо — естественный первый потребитель: у него двойная цель. Продуктовая — публичное распространение и демонстрация движка в действии. Техническая — обкатка изменений и проверка концепций на живой API-поверхности.

Обе цели делают разработку демо неотъемлемой частью релизного цикла, а не опциональной добавкой к нему. Демо задействовало оба хука одновременно: onStep заполнял буфер команд для UI-трейса на каждой итерации; onDebugBreak управлял циклом «пауза / продолжение». Но писать его было неудобно, по двум причинам.

Во-первых, after-сработка onDebugBreak приходила с данными предыдущего yield’а — теми же, что предыдущий onStep уже показал. Демо обрабатывало одно и то же дважды, и вопрос «почему два хука для одного события? » задавал не я, а как будто сам код.

Этот прогресс даёт важные сигналы о будущем отрасли, и технологический мир внимательно наблюдает.