А что, если ИИ-агенту проще пересоздать библиотеку, чем чинить её?

Код больше не главный

У разработчиков есть привычка считать код главным артефактом проекта. Документация рядом, тесты рядом, архитектурные заметки где-то в стороне. Авторы работы Design Docs Are All You Need предлагают перевернуть порядок: главным сделать дизайн-документы, а саму библиотеку каждый раз собирать заново силами ИИ-агентов для программирования.

Звучит как провокация. Но речь не про очередной чат-бот поверх репозитория. Авторы решают конкретную проблему: моделирование производительности систем машинного обучения быстро устаревает. Сегодня вы аккуратно описали один тип трансформера и одну схему работы ускорителей. Завтра пришли смеси экспертов, другая схема внимания, новые фазы инференса, другая топология железа — и старая абстракция уже врёт. В таких проектах код часто превращается в слоёный пирог из заплаток.

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

Это разговор о более широкой вещи: что в эпоху ИИ должно жить долго — код или спецификация.

Что предлагают авторы

Авторы описывают библиотеку smart для символического моделирования производительности систем машинного обучения. Но главный предмет статьи — способ её поддерживать.

В основной ветке репозитория почти нет кода. Вместо этого там лежит набор текстовых дизайн-документов. Они связаны в ориентированный ациклический граф: одни документы зависят от других, поэтому генерировать код надо по порядку. Сначала, например, описание топологии железа и численных параметров, потом модели стоимости коллективных операций, затем каталоги моделей.

Дальше в дело вступает пайплайн из ИИ-агентов:

🟠 агенты читают документы и автоматически восстанавливают зависимости между ними

🟣 оркестратор проходит по графу в правильном порядке

🟠 для каждого документа запускается отдельный агент для программирования

🟣 сгенерированный код проходит сверку с эталонными моделями, проверками параметров и тестами

🟠 если что-то не сошлось, человек правит только текст документа, а не код

Смысл в том, что человек больше не правит библиотеку руками. Он редактирует спецификацию на естественном языке. Код — временный продукт сборки.

Авторы даже вводят для этого почти формальное понятие. Когда вы меняете систему поверх старой реализации, появляется долг инкрементальной генерации — долг накопления правок. Новая версия начинает зависеть не только от новой спецификации, но и от старого кода со всеми его компромиссами. Полная пересборка этот долг просто обнуляет.

Почему обычная поддержка кода здесь работает плохо

В статье описана проблема, знакомая многим командам. Есть два источника боли.

Первый — постоянное изменение предметной области. Модели машинного обучения и железо меняются так быстро, что вчерашние удобные абстракции ломаются. Нельзя один раз придумать красивый фреймворк и десять лет спокойно жить.

Второй — ограничения самих ИИ-агентов. Даже если вы активно пользуетесь генерацией кода, модель редко видит всю зрелую кодовую базу сразу. Ей дают куски. Она решает локальную задачу. Из-за этого она может написать правдоподобный фрагмент, который плохо согласуется с общей архитектурой. Если повторять так много раз, структура проекта деградирует.

Авторы предлагают радикальный ответ: хранить ясное текстовое описание системы, разбить его на самодостаточные документы и регулярно прогонять полную пересборку.

Коротко идея выглядит так:

🟣 долг от правок копится при любом инкрементальном обновлении

🟠 контекст ИИ-агента ограничен, поэтому локальные правки часто портят целое

🟣 полная регенерация из документов убирает зависимость от старого кода

🟠 документация становится исполняемой спецификацией

Коротко в цифрах:

🟠 1,5–3 часа занимает полная пересборка библиотеки

🟣 около 100 долларов стоит сборка через API Claude Code

Для академического прототипа или внутреннего инженерного инструмента это уже выглядит как рабочий режим.

Документы должны быть написаны по-другому

Интересная мысль статьи: если вы хотите генерировать систему из текстов, обычные архитектурные заметки не подойдут.

Авторы не ограничиваются общими правилами, тестами и описанием интерфейсов. Они настаивают на другом стиле документации: в ней должны быть пошаговые разобранные примеры. Не просто фраза «all-gather стоит столько-то», а маленькая сценка с числами и промежуточными шагами: на такой-то топологии, при таком размере данных, на узел приходится столько-то связей, значит стоимость считается так-то.

Такие примеры работают как демки внутри текста. Для ИИ-агента это не абстрактная инструкция, а образец того, как именно надо понимать семантику. Если проза оставляет место для двусмысленности, пример её сужает.

Авторы прямо пишут, что в каждом документе, где есть вычисления, нужен якорь сверки: маленький заранее заданный случай с точным ожидаемым результатом. Потом из этого же текста рождается тест.

Здесь документация — уже не пояснение к коду. Это обвязка для генерации, проверки и исправления системы.

Как устроена сама библиотека

Чтобы такой подход работал, мало хорошо писать документы. Нужна ещё минимальная и устойчивая внутренняя модель, которую можно снова и снова порождать из текстов без взрыва сложности.

Для этого в smart используется очень компактное промежуточное представление операций. Базовая сущность — операция, которая знает:

🟠 свои входы и выходы

🟣 символьную стоимость по вычислениям, памяти и коммуникации

🟠 таблицу занятости ресурсов по тактам

🟣 параметры, которые позволяют собрать из операций графы и циклы

Ключевая идея в том, что это представление рекурсивное. Операция может быть листом, а может быть подграфом или циклом с телом. За счёт этого из небольшого набора кирпичиков можно описывать и отдельную матричную операцию на TPU, и большой фрагмент модели вроде внимания.

Важный момент: все размеры и формулы держатся символически через SymPy. То есть библиотека не сразу подставляет числа, а строит выражения в виде формул. Например, длина последовательности, размер блока, число узлов в сетке — всё это переменные. Один раз построили модель, потом быстро подставляете разные значения и прогоняете тысячи конфигураций.

Такой подход даёт два режима работы:

🟣 быстрый режим — грубая аналитическая свёртка для больших прогонов по множеству точек

🟠 медленный режим — более детальное расписание с учётом ресурсов и зависимостей

Первый нужен, когда вы хотите исследовать пространство вариантов. Второй — когда быстрый прогон показал интересную точку и теперь нужно понять, что там происходит на уровне расписания.

Отдельно решена распределённость. Авторы стараются не расставлять коллективные операции вручную везде, где можно. Вместо этого тензоры получают аннотации о шардировании, а нужные all-gather или reduce-scatter выводятся автоматически из раскладки данных и результата операции. Явно задаются только те коллективные операции, которые действительно меняют раскладку между измерениями.

Почему здесь важна именно минимальность

Во многих системах проблема не в том, что документации мало. Проблема в том, что сама предметная модель слишком тяжёлая. Если у вас десятки исключений, специальных случаев и исторических напластований, ИИ-агент будет стабильно путаться, а полная пересборка не спасёт.

Авторы делают ставку на минимальный набор ортогональных абстракций. Алгоритмическая часть собирает граф из операций. Системная часть назначает цену листовым операциям под конкретное железо. Если меняется внимание, вы трогаете один слой документов. Если меняется межсоединение или параметры TPU, другой.

Для областей, где спецификация меняется быстрее кода, это выглядит разумно. Вы хотите, чтобы долгоживущим объектом была чётко выписанная модель предметной области.

Что показали на практике

Авторы не ограничились общей идеей. Они пишут, что текущая версия smart состоит примерно из 50 дизайн-документов и около 9000 строк текстовой спецификации. Это покрывает топологию TPU, модели стоимости коллективных операций, численные детали, планировщики и каталоги передовых модельных семейств: плотные модели, смеси экспертов, варианты внимания, а также модели для робототехники и визуально-языковых задач.

Главная практическая проверка — библиотека, собранная заново агентами, воспроизводит вручную проверенные эталонные модели с точностью до округления. Среди примеров есть и модель обслуживания DeepSeek-V3 на части TPU-пода.

Здесь важно другое: текстовая спецификация оказалась достаточной, чтобы восстановить рабочий инструмент без ручной правки кода как основного процесса.

Выжимка по результатам:

🟠 около 50 документов вместо основной кодовой базы

🟣 около 9000 строк спецификации на естественном языке

🟠 1,5–3 часа на полную пересборку

🟣 около 100 долларов за полную сборку через API

🟠 совпадение с ручными эталонами до погрешности округления

Что это меняет для инженерии

У статьи есть более широкий смысл. Она предлагает смотреть на программную систему как на регулярно пересобираемый продукт из спецификации, если выполняются три условия:

🟣 предметная область быстро меняется

🟠 ИИ-агенты уже умеют стабильно писать такие модули

🟣 стоимость полной пересборки ниже, чем стоимость жизни с техническим долгом

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

Но есть и скрытое требование. Такой подход требует гораздо более точного мышления в документах. Если вы написали расплывчатую спецификацию, агент сгенерирует расплывчатую систему. Если вы не умеете формулировать инварианты и примеры, пересборка будет регулярно давать сбои.

То есть статья не про магию «код сам напишется». Она про то, что центр тяжести разработки смещается в спецификацию, пайплайн регенерации и проверки.

Вывод

Если вы строите инструменты для быстро меняющихся ИИ-систем, документация может стать основным исходником, а код — пересобираемым артефактом. В таких задачах это иногда выгоднее, чем бесконечно наращивать старую реализацию.

Подход smart держится на трёх вещах:

🟠 самодостаточные дизайн-документы вместо разрозненных заметок

🟣 пошаговые примеры и якоря сверки внутри каждого документа

🟠 минимальное символическое представление, которое переживает смену моделей и железа

Из этого вырастает другой режим разработки. Человек редактирует смысл. ИИ-агенты восстанавливают реализацию. Тесты и эталонные расчёты отсекают ошибки. Если спецификация меняется каждую неделю, такой цикл может оказаться практичнее привычной ручной эволюции кодовой базы.