Agent Operable Codebase

Image: AI generated

Один вопрос

Откройте самый длинный файл в вашем проекте. Сколько в нём функций?

Попросите AI-агента изменить одну функцию в этом файле. Агент прочитает файл целиком. Он открыл файл ради одной функции, но получил в нагрузку 19 ненужных.

Здесь начинается проблема.

Код, который читает человек. Код, с которым работает агент

До сих пор код писался для чтения людьми. Хорошие имена переменных, комментарии, документация – всё это для снижения когнитивной нагрузки человека.

В эпоху агентов вопрос меняется. Одинаков ли код, удобный для чтения человеком, и код, удобный для работы агента?

Нет.

Человек прокручивает файл на 2 000 строк, и интуиция подсказывает: «эту часть трогать нельзя». У агента такой интуиции нет. 2 000 прочитанных строк – это 1 950 строк контекстного загрязнения.

Исследования это подтверждают. При смешивании нерелевантной информации производительность AI падает на 30~85%. Даже если ненужные токены – пробелы, производительность снижается. Чем короче контекст, тем лучше – это не интуиция, а результат экспериментов.

Не ставьте робота в офис для людей. Постройте завод, где робот сможет работать.

Три вещи, необходимые агенту

Чтобы агент стабильно работал с кодовой базой, нужны три условия.

1. Должен уметь читать – без шума

Один файл – одна концепция. Имя файла – это имя концепции.

before: read utils.go → 20 функций, 19 не нужны
after:  read check_one_file_one_func.go → 1 функция, именно то, что нужно

filefunc решает эту проблему. 22 структурных правила разделяют код на смысловые единицы. Во фреймворке Hono (star 23k+) 186 файлов были разделены на 626. 4 419 тестов – ни один не сломался. Файлов стало в 3,4 раза больше, но логика не изменилась ни на строку.

«Не станет ли файлов слишком много?» – Агент не открывает каталоги. Он ищет. 500 файлов или 1 000 – одного grep достаточно. Важнее не открыть 295 ненужных, чем взять 5 нужных.

2. Должен уметь проверять – механически

Если изменить функцию без тестов, никто не знает, что сломается. Агент тоже не знает. Попадает в doom loop.

before: 0 тестов, неизвестно, что сломается при изменении
after:  527 функций с тестами, изменение поведения обнаруживается мгновенно

tsma решает эту проблему. Индексирует все функции проекта, обнаруживает наличие тестов, измеряет покрытие и возвращает номера строк непокрытых ветвлений.

Без обратной связи, если попросить LLM писать тесты, покрытие останавливается на 60~70%. Если сообщить «line 41, 44, 70 не покрыты», покрытие достигает 100%. Та же модель. Разница – только в разрешении обратной связи.

В эксперименте с проектом из 527 функций: TODO дошёл до 0. Автономный агент остановился на 40 и объявил «всё готово». С ratchet – 527 из 527.

3. Спецификации должны допускать перекрёстную проверку

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

before: 200 эндпоинтов, согласованность спецификаций проверяет человек
after:  один operationId связывает все слои, машина обнаруживает drift

yongol решает эту проблему. 10 SSOT (OpenAPI, DDL, sqlc, SSaC, Rego, Hurl и др.) связываются через один operationId и перекрёстно проверяются ~287 правилами. user_id – string в OpenAPI, но BIGINT в DDL – такие противоречия между слоями существующие инструменты не ловят.

Одна структура, пронизывающая три инструмента

filefunc, tsma, yongol – независимые инструменты, но у них общая структура.

filefunc:  22 структурных правила → validate → исправить → повторить
tsma:      измерить покрытие → обратная связь по непокрытым ветвлениям → исправить → повторить
yongol:    перекрёстная проверка → обнаружение drift → исправить → повторить

Один и тот же цикл.

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

Symbolic Feedback Loop. Циклическая структура, в которой детерминированный инструмент корректирует вероятностную генерацию LLM. Не AI проверяет AI, а машина проверяет AI.

Дайте мнение – будет льстить. Дайте факт – исправит. Спросите «код нормальный?» – ответит «да, отлично». Скажите «line 41: field name mismatch» – исправит мгновенно. Обратная связь без объекта лести – потому что числа и позиции не являются эмоциями.

От legacy к agent-operable

Не нужно менять существующую кодовую базу за один раз. Это не фундамент с нуля, а сейсмоусиление. Укрепляем здание, не закрывая работающий магазин.

Этап 1 – Сделать читаемым

Начните с самого длинного файла. Запустите filefunc validate и доведите нарушения до 0. Все существующие тесты должны проходить.

Этап 2 – Сделать проверяемым

Повторяйте tsma next. Добавляйте тесты для непокрытых функций, заполняйте непокрытые ветвления. Если агент умирает посередине, прогресс сохраняется. Новый агент запускает tsma next и продолжает.

Этап 3 – Перекрёстная проверка

Внедрите SSOT и запустите yongol validate. Машина ловит противоречия между слоями.

Каждый этап независим. Можно делать этап 2 без этапа 1, или этап 1 без этапа 2. Но когда все три объединяются, диапазон автономной работы агента расширяется скачкообразно.

Смена операционной системы

Agent-operable codebase – это не просто lint или tooling. Это смена операционной системы кодовой базы.

Многие делают поезд быстрее. Более крупные модели, более умные агенты, лучшие промпты.

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

Связанные статьи

• filefunc – Один файл, одна концепция – Конвенция структуры кода, устраняющая контекстное загрязнение LLM с помощью 22 правил
• tsma – Линия обороны от регрессий в legacy-коде – Автоматизация тестирования на основе ratchet: 527 функций до TODO 0
• Почему кодинг-агенты работают и почему ломаются – Структурный анализ Symbolic Feedback Loop
• Топология обратной связи важнее IQ модели – Почему одна и та же модель останавливается на 40 или завершает 527
• whyso – То, что не показывает git blame – Автоматическое извлечение истории изменений по файлам

Источники

• Stanford, “Lost in the Middle: How Language Models Use Long Contexts” (2024) – Производительность падает на 30%+ когда релевантная информация теряется в середине контекста
• Amazon, “Context Length Alone Hurts LLM Performance” (2025) – Производительность падает на 13,9~85% даже если ненужные токены – пробелы
• Эмпирические данные фреймворка Hono – 186 файлов → 626 файлов, все 4 419 тестов пройдены
• Эмпирические данные tsma, 527 функций – PASS 246 (46,7%), DONE 281 (53,3%), TODO 0
• Эксперимент Ratchet Pattern – Автономный агент 40/527 (7,6%) vs ratchet CLI 527/527 (100%)