Долг не там, где ищут линтеры
Традиционное программное обеспечение накапливает долг в местах, на которые рано или поздно пожалуется компилятор: дублирование логики, устаревшие интерфейсы, недокументированные инварианты. Агентные системы накапливают долг в местах, на которые не жалуется никто. Промпт — это строка. Схема инструмента — это JSON-документ. Соглашение о том, какой агент отвечает за решение, живёт в проектном документе, который никто не читает после второго спринта.
Это не стилистическая проблема. Это структурная проблема. Когда артефакт, определяющий поведение системы, — это нетипизированная, неверсионированная проза, каждое изменение становится молчаливым изменением. Ничего не ломается при сборке. Система продолжает работать. Просто работает иначе, и разница обнаруживается недели спустя, когда нижестоящий агент начинает выдавать результаты, которые выглядят правдоподобно, но ошибочны конкретным, воспроизводимым образом.
Фрагменты промптов, продублированные между агентами с молчаливым расхождением
Распространённый паттерн: общая инструкция, например «всегда указывай исходный документ», копируется в четыре промпта агентов. Шесть недель спустя три из них были отредактированы. Один теперь гласит: «указывай источник, когда он доступен». Другой: «указывай исходный документ, если retrieval прошёл успешно». Четвёртый не изменён. Ни один тест не падает. Агенты, которые указывают источник условно, и агент, который указывает его безусловно, создают разные аудиторские следы, и разница всплывает только тогда, когда кто-то пытается согласовать результаты по всему пайплайну.
Долг — не само дублирование. Дублирование дёшево. Долг — это отсутствие механизма, обнаруживающего расхождение. Общий фрагмент промпта, импортируемый во время сборки, превратил бы расхождение в diff. Скопированный фрагмент делает его невидимым.
Схемы инструментов, которые больше не соответствуют сервису, который они оборачивают
Схема инструмента — это контракт. Когда базовый сервис меняется — поле переименовано, nullable-поле стало обязательным, ошибка возвращается как 200 со статусным полем — схема не обновляется сама. Агент продолжает вызывать инструмент со старой формой. Сервис либо отклоняет вызов, и тогда агент повторяет попытку и сжигает токены, либо принимает его и возвращает что-то, что агент интерпретирует неверно.
Второй случай хуже. Инструмент, который громко падает, — это инструмент, который починят. Инструмент, который тихо падает, выдаёт уверенный, но неверный результат. Это агентный эквивалент функции, возвращающей null вместо исключения.
Недокументированные соглашения о том, какой агент отвечает за какое решение
Мультиагентные системы развивают неявное владение. Один агент решает, когда эскалировать. Другой решает, когда повторять попытку. Третий решает, когда суммировать. Эти решения редко записываются в одном месте. Они возникают из промптов, кода оркестрации и порядка, в котором добавлялись агенты.
Когда вводится новый агент, он не наследует ничего из этого. Он принимает собственные решения, иногда в конфликте с существующим агентом. Конфликт — не баг ни в одном из агентов. Это отсутствующая спецификация. Теперь у системы два владельца одного решения, и его разрешение зависит от порядка выполнения.
Это класс долга, который труднее всего увидеть, потому что он не в каком-то одном артефакте. Он в промежутках между артефактами.
Как сделать его видимым
Лекарство — не писать лучшие промпты. Лекарство — подчинить промпты, схемы и соглашения той же дисциплине, что и код.
Относитесь к промптам как к версионированным артефактам с владельцами и changelog
Промпт должен жить в репозитории, а не в строке базы данных, редактируемой через админ-панель. У него должен быть владелец — команда или роль, а не отдельный человек — и changelog, фиксирующий, что изменилось и почему. Changelog важнее номера версии. Diff промпта без обоснования — это diff промпта, который откатит следующий человек, который его не поймёт.
Версионирование также даёт возможность отката. Когда изменение промпта ухудшает качество результатов, возможность вернуться к проверенной версии — это разница между пятнадцатиминутным исправлением и многодневным расследованием.
Контрактные тесты, проверяющие схемы инструментов против живых эндпоинтов
Схему инструмента следует тестировать так же, как тестируют API-клиент: вызывая реальный эндпоинт и утверждая, что ответ соответствует схеме. Это не unit-тест с моком. Моки кодируют схему в том виде, в каком она была понята на момент написания мока, — а это именно то предположение, которое нужно опровергнуть.
Контрактный тест для схемы инструмента утверждает три вещи: что эндпоинт принимает форму, объявленную схемой; что ответ содержит поля, обещанные схемой; и что ошибки проявляются так, чтобы агент мог на них реагировать. Третье утверждение пропускают чаще всего, и оно важнее всего, потому что агент, не способный отличить временную ошибку от постоянной, будет повторять постоянную ошибку, пока не исчерпает свой бюджет.
Реестр, сопоставляющий каждого агента с его инструментами, областями памяти и путём эскалации
Реестр — единственный источник истины о владении. Для каждого агента он фиксирует: какие инструменты он может вызывать, какие области памяти он может читать и записывать и при каких условиях он эскалирует. Реестр — не документация. Это конфигурация, которую читает слой оркестрации, так что агент не может вызвать инструмент, которым не владеет, или записать в область памяти, которой у него нет.
Это превращает неявное соглашение в принудительное. Компромисс реален: реестр добавляет слой косвенности и бремя поддержки. Каждый новый инструмент требует записи в реестре, и каждая запись в реестре — потенциальная точка отказа, если она разойдётся с кодом. Альтернатива — оставить владение неявным — дешевле до первого конфликтующего решения, после чего стоимость диагностики многократно превышает стоимость реестра.
Правило рефакторинга
Если поведение важно, оно принадлежит коду или схеме, а не прозе внутри промпта.
Это всё правило. Его легко сформулировать и трудно соблюдать, потому что промпты — путь наименьшего сопротивления. Добавить предложение в промпт быстрее, чем добавить поле в схему. Предложение работает сразу. Схема требует миграции, теста и ревью.
Правило — не запрет на прозу. Промптам нужна проза для тона, для фрейминга, для того рода указаний, которые сопротивляются формализации. Правило — это граница: проза — для того, что может меняться, не ломая систему. Схемы и код — для того, что не может.
Полезная проверка: если для поведения вы написали бы тест, оно не принадлежит промпту. Если вы не написали бы для него тест, оно может принадлежать промпту. Тест — это разделительная линия.
Чего это стоит
Честный компромисс: эта дисциплина замедляет первую версию. Версионированный промпт с владельцем и changelog выпустить дольше, чем строку, отредактированную в дашборде. Контрактный тест писать дольше, чем мок. Реестр настраивать дольше, чем соглашение.
Отдача не в первой версии. Она в пятой. Агентные системы, которые дёшево менять, — это системы, где изменение читаемо. Читаемость идёт от артефактов, которые можно диффить, тестировать и которыми можно владеть. Промпты, живущие в дашбордах, дёшевы в написании и дороги в изменении. Промпты, живущие в репозиториях, дороги в написании и дёшевы в изменении. Выбор в том, какую цену платить и когда.
Для команд, запускающих агентные системы в продакшене, релевантный вопрос не в том, существует ли долг. Он существует. Вопрос в том, видим ли он. Фрагмент промпта, молча разошедшийся, — невидимый долг. Фрагмент промпта с версией, владельцем и changelog — видимый долг, а это единственный вид, который можно погасить.
Резюме
Кодовые базы агентов гниют иначе. Компилятор не проверяет промпты, схемы инструментов или соглашения о владении, поэтому долг накапливается без сигнала. Чтобы сделать его видимым, нужно относиться к промптам как к версионированным артефактам, тестировать схемы инструментов против живых эндпоинтов и поддерживать реестр возможностей агентов и путей эскалации. Правило рефакторинга простое: если поведение важно, оно принадлежит коду или схеме, а не прозе внутри промпта. Цена платится вперёд; отдача — при каждом последующем изменении.