Словарь ИИ-кодинга¶
Перевод AI Coding Dictionary Мэтта Покока: словарь агентной разработки простым языком. Заголовки даны по-русски, английское имя термина сохранено — именно его вы встретите в инструментах и документации.
Кодинг с ИИ легко принять за занятие только для специалистов. Необъяснённый жаргон. Странные сбои. Счета, которые не сходятся с объёмом работы.
На деле базовые правила игры можно выучить за один день. После этого работа перестаёт быть угадайкой.
Почему деградирует контекст? Почему счёт такой большой? Почему один и тот же промпт ведёт себя по-разному от дня к дню?
У каждого вопроса есть ясный ответ, если знать слова, которыми его задавать.
Для этого и нужен словарь. Лексикон ИИ-кодинга, переведённый на понятный язык.
Модель¶
Шестнадцать терминов о том, что такое модель, из чего она состоит и как за неё платят.
ИИ¶
AI. Подвижная метка, а не технология. «ИИ» не называет фиксированную вещь так, как модель или токен. Слово указывает на то, что компьютеры недавно и впечатляюще научились делать. Сейчас оно указывает на большие языковые модели. Раньше указывало на совсем другие вещи:
| Эпоха | Что значило «ИИ» |
|---|---|
| 1950-е | Символьные рассуждения: пруверы теорем, программы для шашек. |
| 1960–70-е | Символьные программы на правилах: ELIZA, SHRDLU. |
| 1980-е | Экспертные системы: тысячи рукописных правил «если — то», кодирующих человеческую экспертизу. |
| 1990-е | Поиск по дереву игры: Deep Blue обыгрывает Каспарова (1997). Исследователи вообще избегали слова «ИИ». |
| 2000-е | Статистическое машинное обучение: спам-фильтры, рекомендательные системы. Продавали как «машинное обучение», не как «ИИ». |
| 2010-е | Глубокое обучение: распознавание изображений (AlexNet, 2012), AlphaGo (2016). |
| 2020-е | Большие языковые модели: ChatGPT (2022) сделал «ИИ» синонимом чат-ботов. |
Указатель сдвигается по известному механизму, который иногда называют эффектом ИИ: как только приём начинает работать надёжно, его переименовывают — это «всего лишь» поиск, «всего лишь» статистика, — и «ИИ» уезжает к следующей нерешённой задаче. Наблюдение старое. Бертрам Рафаэль сформулировал его в 1971 году: «ИИ — собирательное имя для задач, которые мы ещё не умеем нормально решать на компьютере». Версия Ларри Теслера, около 1979 года: «Интеллект — это всё, чего машины ещё не делали».
Поэтому разговоры об ИИ так часто идут мимо друг друга. Утверждение вроде «ИИ не умеет рассуждать» или «ИИ раздут» несёт скрытую метку времени: речь может идти об экспертных системах, о классификаторах изображений 2010-х или о языковой модели прошлого месяца, и каждая отсылка поддерживает свой вывод. Когда обсуждение ИИ буксует, обычно помогает заменить слово на точный термин: модель, harness, агент, контекст, который ей дали.
Избегать: «ИИ» в любом техническом утверждении — называйте ту часть, которую имеете в виду. «ИИ-кодинг» как имя практики нормален; «ИИ галлюцинирует» — нет.
Пример:
«Техдир хочет знать, справится ли ИИ с очередью триажа.»
«Сначала переведите это в постановку. Она имеет в виду языковую модель в harness с доступом к системе тикетов. Само по себе „ИИ“ — не спецификация.»
Модель¶
Model. Параметры. Без состояния: делает предсказание следующего токена и больше ничего. «Claude Opus 4.x» и «GPT-5.x» — это модели. Сама по себе модель не умеет ничего агентного: её нужно поместить в harness.
Модель не читает файлы, не запускает команды, не ходит в интернет и не помнит вчерашний день. Она принимает токены и предсказывает токены на выходе, один раз на каждый запрос к провайдеру. Всё, что ощущается как работа агента — выбор инструментов, чтение результатов, цикл до конца задачи, — это harness, который оркестрирует много таких предсказаний подряд.
Провайдеры выпускают модели уровнями: большая — самая умная, но медленная и дорогая; меньшие — быстрее и дешевле, но слабее. Выбор уровня — настоящее решение: тяжёлая модель для планирования и сложной отладки, лёгкая для механических правок. Harness позволяет переключаться посреди сессии.
Строгость в слове обостряет диагноз. «Модель плохо справляется» — конкретное утверждение. Та же модель в другом harness или с другим контекстом часто ведёт себя совсем иначе. Прежде чем винить модель, проверьте, что ей дали: большинство разочаровывающих ответов восходит к контексту или harness, а не к параметрам.
Пример:
«Стоит ли сменить модель с Sonnet на Opus на шаге планирования?»
«Попробуйте. Но на этой задаче основную работу делает harness. Смена модели не поможет, если неверны системный промпт и инструменты.»
Параметры¶
Parameters. Числа внутри модели — часто миллиарды, — настроенные во время обучения. Всё, что модель «знает», живёт в них. Обучение их задаёт; инференс использует их без изменений. Их также называют весами.
Механически параметры превращают вход в выход. Предсказание следующего токена — гигантское вычисление: токены из контекстного окна проходят через параметры, и на выходе появляется предсказание следующего токена. Внутри модели нет базы фактов и нет таблицы подстановки кода — только эти числа, устроенные так, что вычисление склонно давать полезный выход. Факты, которые модель может процитировать из обучения, например API стандартной библиотеки, — это параметрическое знание: оно хранится в параметрах, а не извлекается откуда-то ещё.
Важно усвоить: после обучения параметры заморожены. Ничто в сессии их не меняет — ни ваша поправка, ни показанная кодовая база, ни ошибка, на которой она «учится». Каждая сессия работает на тех же числах. Поэтому модель без состояния, её встроенное знание обрывается на границе знаний, а всё специфичное для проекта должно приходить через контекст. Параметры меняются только новым обучением, и по сути получается другая модель.
Пример:
«Можно дообучить её на нашей кодовой базе?»
«Это обновит параметры — после этого модель уже другая. Для одного проекта почти всегда дешевле загрузить кодовую базу как контекст, чем переобучать.»
Обучение¶
Training. Процесс, который задаёт параметры модели: ей показывают огромные объёмы текста и подкручивают параметры, чтобы улучшить предсказание следующего токена. Разовый дорогой процесс, который делает провайдер модели. Сюда входят и предобучение (основной прогон), и постобучение (поздние доводки вроде следования инструкциям и безопасности). На уровне этого словаря различие неважно.
Механизм — повторение в масштабе: показать модели отрезок текста, попросить предсказать следующий токен, сдвинуть параметры к тому, каким токен был на самом деле, и повторить на триллионах токенов. Ничего не хранится как факты или правила. Всё, что модель «знает», — побочный эффект того, что она лучше предсказывает, сжатый в параметры как параметрическое знание.
Два следствия важны каждый день. Обучение заканчивается в какой-то момент времени, поэтому у модели есть граница знаний: она не видела версию библиотеки, на которую вы обновились в прошлом месяце. И обучение — не то, что можете сделать вы. Если модель не знает вашу кодовую базу, ваши соглашения или внутренние API, лекарство никогда не «научить модель». Лекарство — положить этот материал в контекст, единственный вход, который вы контролируете.
Пример:
«Можно сделать так, чтобы она знала наш внутренний API?»
«Через обучение — нет. Это процесс на месяцы у провайдера модели. Загрузите документацию API в контекст. Это рычаг, который у вас реально есть.»
Инференс¶
Inference. Запуск обученной модели, чтобы получить выход. Именно это происходит на каждом запросе к провайдеру. Параметры остаются фиксированными; модель просто делает предсказание следующего токена по данному контексту. Дёшево относительно обучения, но тарифицируется за токен и составляет основную стоимость использования модели.
Жизнь модели делится на две фазы:
| Фаза | Когда | Что делает | Параметры |
|---|---|---|---|
| Обучение | Один раз, до релиза | Получает параметры из обучающего корпуса | Записываются |
| Инференс | Каждый раз, когда моделью пользуются | Прогоняет замороженные параметры по вашему контексту и порождает токены | Только чтение |
Ничто, что вы делаете во время инференса, не записывается обратно в параметры. Поэтому поправка, которую вы внесли сегодня, не прилипает к завтрашнему дню. Модель, которая повторяет ту же ошибку в следующей сессии после того, как вы тщательно объяснили исправление, вас не проигнорировала: она неспособна учиться на этом обмене. Модель без состояния. Непрерывность должна приходить снаружи — из контекстного окна или системы памяти.
Тот же механизм объясняет счёт. Каждый запрос прогоняет модель по всему контексту, поэтому стоимость растёт вместе с входными и выходными токенами, а агент, который делает десятки вызовов инструментов, платит за инференс на каждом круге. Размер контекста — вопрос и стоимости, и качества.
Пример:
«Почему счёт растёт с использованием, а не выглядит как фиксированная лицензия?»
«Вы платите за инференс. Каждый запрос к провайдеру гоняет модель на его железе. Обучение уже произошло, но стоимость инференса копится на каждый запрос, а один ход может развернуться в много запросов, когда вызываются инструменты.»
Усилие¶
Effort. Регулятор того, сколько рассуждений модель делает перед ответом. Задаётся на каждый запрос к провайдеру и управляет длиной размышления, которое модель проходит, прежде чем начать писать видимый ответ. Это размышление порождается во время инференса, как и всё остальное. Harness часто его прячет, но это настоящая работа модели.
Больше усилия — дороже и медленнее. Рассуждение испускается как токены и тарифицируется как выходные токены, даже если вы их не видите, и порождается по одному токену. Поднять усилие — удлинить ожидание ответа и увеличить счёт. Обмен: больше обдумывания против скорости и стоимости.
Большинство harness показывают усилие короткой лестницей:
| Уровень | Для чего |
|---|---|
| Низкий | Механические правки, поиски, хорошо заданные изменения с одним ясным путём. |
| Средний | Обычный кодинг, типичное значение по умолчанию. |
| Высокий | Хитрые баги, проектные решения, многошаговые планы. |
| Максимум | Самые трудные задачи, где неверный ответ дорого откатывать. |
Ошибка режет в обе стороны. Слишком низкое усилие на трудной задаче даёт уверенный поверхностный ответ, который пропустил нужное рассуждение: читается нормально и ошибочен так, что это всплывёт позже. Максимум на переименовании в одну строку — долгое размышление, которое не даст ничего сверх самого низкого уровня.
Подбирайте усилие к задаче, а не к сессии. Поднимайте его на той части, которую действительно трудно обдумать, и опускайте на механической работе вокруг.
Пример:
«Оно снова портит этот фикс конкурентности. Я объяснил трижды.»
«Поднимите усилие. Это баг, тяжёлый на рассуждение, и на настройке по умолчанию модель не думает достаточно долго, прежде чем зафиксировать подход.»
Токен¶
Token. Атомарная единица, которую модель читает и пишет. Примерно размером со слово, но не точно: частые слова — один токен, редкие или длинные дробятся на несколько. Размер контекстного окна, стоимость и задержка считаются в токенах.
Текст становится токенами через токенизатор: фиксированный словарь из десятков тысяч фрагментов, выученный до обучения, который режет любой вход на последовательность записей словаря. Модель никогда не видит символы или слова. Каждый кусок текста на входе превращается в токены, а предсказание следующего токена выдаёт выход по одному токену.
Ориентир: токен — около трёх четвертей английского слова, так что тысяча токенов — примерно 750 слов. Код менее предсказуем: частые ключевые слова и идиомы токенизируются компактно, а сгенерированные идентификаторы, хеши, блобы base64 и минифицированный вывод дробятся на много токенов на «слово». Закономерность: текст, который часто встречался в материале токенизатора, получает короткие эффективные коды; текст, которого там не было, рубится на мелкие куски. Хеш вроде a3f9c2e1 нигде не встречался, поэтому распадается на много токенов, а function — один. Поэтому небольшой на вид файл, полный необычных строк, может занять удивительную долю контекстного окна.
Токен — единица, в которой меряется всё остальное. Стоимость — за токен: провайдеры отдельно тарифицируют входные и выходные токены. Скорость — токены в секунду, потому что выход порождается по одному токену. Контекстное окно — фиксированное число токенов, так что число токенов в файлах решает, сколько влезет.
Избегать: «слово». Границы токенов не совпадают с границами слов, а токены в секунду и токены на доллар — единицы, которые реально важны.
Пример:
«Насколько большим получится этот промпт?»
«Прогоните через токенизатор. Схема компактная, но ключи JSON странные, так что они распадутся на больше токенов, чем кажется.»
Предсказание следующего токена¶
Next-token prediction. То, что модель на самом деле делает. По контексту она семплирует один следующий токен, дописывает его и запускается снова. Любой выход — предложение, вызов инструмента, файл на тысячу строк — собирается по одному токену. Другого режима работы у модели нет.
Каждый шаг устроен одинаково: токены в контекстном окне проходят через параметры, те выдают вероятность каждого токена словаря — этот очень вероятен следующим, тот менее. Один токен семплируется из этих вероятностей, дописывается, и цикл идёт снова с чуть более длинным контекстом. Этот семплинг — причина, почему один и тот же промпт даёт разный выход на разных запусках: недетерминизм встроен в механизм, а не наложен сверху как баг.
Если держать этот механизм в голове, странное поведение объясняется. Модель никогда не проверяет, истинен ли токен, прежде чем его выдать — только вероятен ли он. Это корень галлюцинации. Она фиксирует каждый токен по ходу, так что уверенно звучащее первое предложение может увести весь остальной ответ. И поскольку выходные токены порождаются строго по одному, скорость генерации задаёт пол того, как быстро может работать любой агент.
Пример:
«Как агент „решает“ вызвать инструмент?»
«Никак. Это предсказание следующего токена до самого дна. Вызов инструмента — просто структурированная строка, которую harness вытаскивает из потока выхода.»
Недетерминизм¶
Non-determinism. Один и тот же вход может дать разный выход. Запустите модель дважды с одинаковым контекстом — и можете получить два разных ответа: иногда другое слово, иногда совсем другой подход. Для этого в вашем коде ничего не должно меняться.
Это свойство того, как модели порождают текст и как провайдеры обслуживают запросы. Во время инференса модель строит распределение вероятностей возможных следующих токенов, и один семплируется из него — обычно с долей случайности намеренно, потому что всегда брать самый вероятный токен даёт повторяющийся текст хуже по качеству. Один иначе семплированный токен в начале ответа меняет каждый токен после него. Так одно другое слово становится совсем другим подходом. Обслуживание на стороне провайдера добавляет ещё вариацию: запросы батчатся на общем железе, и крошечные отличия чисел с плавающей точкой между батчами могут перевесить близкий выбор между двумя токенами. Настройки, которая всё это выключит, нет.
Ждите разброса результатов агента на одной и той же задаче. Большинство ответов попадает в разумный колокол качества — поэтому недетерминизм вообще терпим, — но хвосты настоящие: в одни дни модель кажется острой, в другие — будто потеряла нить. Та же задача, разные броски кубика. Два практических следствия. Повтор — законная стратегия: неудачная попытка — одна выборка из распределения, и свежая попытка той же задачи может просто лечь лучше. И проверка важнее, чем с детерминированными инструментами: нельзя один раз протестировать поведение агента и рассчитывать, что оно повторится, поэтому автоматические проверки должны ловить плохие выборки.
Не превращайте это в сюжет. Люди — машины поиска паттернов, и череда плохих прогонов может ощущаться как доказательство, что «модель на этой неделе стала хуже». Обычно это просто распределение.
Пример:
«Claude сегодня ужасен. Они выкатили версию хуже?»
«Скорее нет. Выход модели недетерминирован. На одной задаче будут хорошие и плохие дни. Попробуйте завтра, прежде чем искать причину.»
Провайдер модели¶
Model provider. Тот, кто отдаёт модель для инференса. Обычно удалённый сервис (Anthropic, OpenAI, Google), но может быть и локальным: Ollama, LM Studio, llama.cpp на вашей машине. Harness сам модель не запускает; он просит провайдера.
Провайдеру принадлежит машина: параметры живут на его железе, и каждый запрос к провайдеру — это harness, который отправляет токены по сети и получает предсказания обратно. Поэтому провайдер — источник целого класса проблем, которые ошибочно приписывают модели или harness: лимиты частоты, деградация мощности, простои живут здесь. Когда агент встаёт посреди сессии или падает на каждом ходе, страница статуса провайдера стоит проверки раньше всего остального.
Провайдер также задаёт коммерческие условия: цену за токен для входа и выхода, скидки префиксного кеша и то, какие модели вообще доступны. Провайдер и создатель модели могут быть разными компаниями: Bedrock, Vertex и OpenRouter отдают чужие модели.
Локальные провайдеры меняют возможности на контроль: модели, которые влезают на ваше железо, намного меньше фронтирных, но ничего не покидает машину и нет счёта за токен.
Пример:
«Можно запустить это офлайн для клиента в изолированной сети?»
«Смените провайдера модели на локальный — Ollama или llama.cpp на их машине. Harness всё равно: он просто бьёт в другой endpoint.»
Harness¶
Harness. Всё вокруг модели, что превращает её в агента: инструменты, системный промпт, управление контекстным окном, разрешения, хуки. Claude.ai и Claude Code работают на одной модели, но ведут себя по-разному, потому что их harness различаются.
Сама модель делает одно: принимает текст и выдаёт текст. Она не может прочитать файл, запустить команду или помнить прошлый ход. Всё это поставляет harness. Он собирает контекст для каждого запроса к провайдеру, исполняет вызовы инструментов, которые просит модель, возвращает результаты, хранит историю сессии, спрашивает разрешение перед рискованными действиями и решает, когда компактизировать. Цикл агента — модель предлагает, harness исполняет, повтор — крутит harness.
Это важно для диагноза. Когда поведение различается между двумя продуктами или между вчера и сегодня, переменная часто не модель, а harness. Другой системный промпт, другой набор инструментов, изменённое разрешение по умолчанию или новая стратегия управления контекстом меняют поведение без всякого изменения модели. И именно в harness живёт большая часть вашей конфигурации: файлы AGENTS.md, настройки разрешений и хуки — инструкции harness, а не модели.
Примеры: Claude Code, Cursor, Codex CLI — и Claude.ai, который скорее чатовый harness, чем кодовый.
Пример:
«Та же модель. Почему Claude Code правит файлы, а Claude.ai только отвечает на вопросы?»
«Разные harness. У Claude Code есть инструменты файловой системы, другой системный промпт и слой разрешений. Модель здесь не переменная.»
Запрос к провайдеру¶
Model provider request. Один круг от harness к провайдеру модели. Harness отправляет текущий контекст; провайдер возвращает один ответ (вызов инструмента или финальный ответ). Одно сообщение пользователя может породить много запросов, если агент вызывает инструменты: каждый результат запускает следующий запрос.
Каждый запрос несёт всё: системный промпт, весь разговор до сих пор, каждый результат инструмента. Модель без состояния, поэтому провайдер ничего не хранит между запросами: сороковой запрос заново отправляет то, что отправил тридцать девятый, плюс ещё один результат инструмента. Префиксный кеш существует, чтобы это повторение было по карману.
Запрос — также единица биллинга. Входные токены, выходные токены и скидки кеша считаются на запрос. Поэтому безобидный на вид вопрос может стоить удивительно много: стоимость пропорциональна не вашему сообщению, а числу запросов, умноженному на размер контекста, который каждый из них несёт.
Стоит отделять запрос от хода. Ход — один обмен с вами, и один ход — «почини падающий тест» — разворачивается в цепочку запросов:
| Запрос | Модель возвращает | Harness затем |
|---|---|---|
| 1 | Вызов инструмента: запустить тесты | Запускает их, дописывает вывод падения |
| 2 | Вызов инструмента: прочитать файл теста | Дописывает содержимое файла |
| 3 | Вызов инструмента: прочитать исходник | Дописывает содержимое файла |
| 4 | Вызов инструмента: править исходник | Применяет правку, дописывает результат |
| 5 | Вызов инструмента: снова запустить тесты | Запускает их, дописывает успешный вывод |
| 6 | Финальный ответ: «исправлено, тесты зелёные» | Показывает его вам |
Шесть запросов на один ход, и каждый заново отправляет весь контекст. Когда вы думаете, куда ушли токены, считайте запросы, а не ходы.
Пример:
«Один вопрос сжёг сорок тысяч токенов?»
«Посмотрите на вызовы инструментов: двенадцать grep, восемь чтений, четыре правки. Каждый результат порождает ещё один запрос к провайдеру, и префикс всей сессии отправляется заново каждый раз.»
Входные токены¶
Input tokens. Токены, которые harness отправляет на каждом запросе к провайдеру: системный промпт, история разговора, результаты инструментов, всё, что модель читает, прежде чем писать. Тарифицируются дешевле выходных токенов, потому что их дешевле обрабатывать.
В ИИ-кодинге входные токены составляют большую часть счёта. Модель без состояния, поэтому каждый ход заново отправляет всю сессию как вход: первое сообщение, каждый ответ, каждый результат инструмента с тех пор. Вход пятидесятого хода содержит предыдущие сорок девять. Один запрос к провайдеру может породить несколько сотен выходных токенов, но заново отправить сто тысяч входных токенов накопленной истории.
Префиксный кеш снижает стоимость: история, которая точно совпадает с прошлым запросом, тарифицируется как дешёвые кеш-токены, а не как вход по полной цене. Если вход всё ещё бьёт по счёту, лекарство — уменьшить то, что отправляется заново: очистка или компактизация между задачами.
Пример:
«Счёт высокий, а агент почти ничего не пишет.»
«Это входные токены: каждый ход заново отправляет всю сессию. Без префиксного кеша вы платите за историю на каждом запросе.»
Выходные токены¶
Output tokens. Токены, которые модель порождает в ответ. Тарифицируются дороже входных — часто примерно в пять раз, — потому что их дороже считать.
Считается всё, что модель пишет: проза, которую вы читаете, код, который она выдаёт, вызовы инструментов и любое расширенное размышление перед ответом. Последнее удивляет: токены рассуждения тарифицируются как выход, даже когда harness их часто не показывает, а повышение усилия тратит их больше.
Выходные токены также задают темп сессии. Модель читает вход быстро, но порождает выход по одному токену, так что когда ход ощущается медленным, почти всегда пишется выход, а не читается вход. Долгое ожидание обычно значит, что идёт длинный ответ.
Пример:
«Сессия рефакторинга жжёт кредит, хотя входы маленькие.»
«Агент переписывает целые файлы вместо патчей. Выходные токены стоят примерно в пять раз дороже входа. Пусть он выдаёт правки — и счёт упадёт.»
Префиксный кеш¶
Prefix cache. Хранилище на стороне провайдера, которое позволяет соседним запросам не пересчитывать общий префикс. Когда начало запроса совпадает с началом недавнего — тот же системный промпт, та же история до какой-то точки, — провайдер переиспользует прошлую работу и тарифицирует эти токены как кеш-токены по гораздо более низкой ставке.
Кеш окупается, потому что сессии растут только дописыванием. Каждый запрос заново отправляет всю историю как входные токены, и в обычной сессии история меняется только в конце: каждый запрос — предыдущий плюс несколько новых сообщений. Провайдер один раз обрабатывает длинное общее начало, сохраняет результат и продолжает с того места, где префикс кончился. Без кеша сессия на 50 ходов платила бы за повторную обработку первого хода пятьдесят раз.
Кеши также истекают. Сколько запись остаётся тёплой, зависит от провайдера — обычно минуты, не часы. Оставьте сессию без дела дольше окна, и следующий запрос один раз пересоберёт префикс по полной цене, прежде чем кеширование возобновится. Это в основном забота авторов harness; для пользователя видимый эффект в том, что запросы после долгой паузы стоят дороже предыдущих.
Пример:
«Почему счёт подскочил на середине сессии?»
«Harness начал вставлять текущее время в системный промпт на каждом ходе. Префиксный кеш ломается на первом изменённом токене, поэтому каждый запрос после этого тарифицировался по полной ставке.»
Кеш-токены¶
Cache tokens. Входные токены, которые провайдер закешировал с прошлого запроса, чтобы не обрабатывать их заново. Когда соседние запросы делят префикс, провайдер переиспользует работу через префиксный кеш и тарифицирует закешированную часть по гораздо более низкой ставке. Рычаг, который делает длинные сессии доступными по цене. Без него каждый ход заново платит за всю историю.
Причина в том, как тарифицируются сессии. Модель без состояния, поэтому каждый запрос заново отправляет весь разговор — системный промпт, каждое сообщение, каждый результат инструмента — как входные токены. К пятидесятому ходу каждый запрос несёт пятьдесят ходов истории, и вы платили бы полную ставку за всё это каждый раз. Кеш меняет арифметику: токены, которые провайдер уже обработал в идентичном префиксе, тарифицируются как кеш-токены, часто в десять раз дешевле входа или ещё дешевле. На длинной сессии большая часть отправляемого — кеш-токены, и счёт остаётся вменяемым.
Пример показывает, когда токены кешируются. Каждая буква — блок содержимого разговора; каждый запрос отправляет разговор до текущего момента:
| Запрос отправляет | Закешировано | По полной ставке | Почему |
|---|---|---|---|
AB | ничего | AB | Первый запрос — не с чем сравнивать |
ABC | AB | C | AB — точный префикс предыдущего запроса |
ABCD | ABC | D | Префикс всё ещё цел |
AXCD | A | XCD | Правка сменила B на X; совпадение обрывается там |
Кеш хрупок конкретным образом: он совпадает по точным префиксам. Если что-то меняется раньше в разговоре — harness переставляет содержимое, обновляется метка времени, сдвигается представление файла, — кеш промахивается с этой точки, и всё после неё тарифицируется по полной входной ставке. Кеши также истекают после нескольких минут бездействия, так что сессия, возобновлённая после долгой паузы, один раз заново платит за историю. Когда стоимость сессии прыгает без очевидной причины, сравните кеш-токены с входными в отчёте об использовании: сломанный кеш виден там первым.
Пример:
«Стоимость длинных сессий зверская — восемь долларов за рефакторинг.»
«Проверьте кеш-токены. Если harness переставляет системный промпт или файлы между ходами, префикс ломается, и вы платите полную входную ставку на каждом запросе.»
Сессии, контекстные окна и ходы¶
Восемь терминов о том, где живёт состояние и что модель вообще видит.
Без состояния¶
Stateless. Не переносит информацию вперёд. Модель без состояния между запросами к провайдеру: каждый запрос заново отправляет всё контекстное окно, потому что другого способа что-то увидеть у модели нет. Агент по умолчанию без состояния между сессиями: новая сессия начинается пустой, без следа предыдущих. Парный термин — с состоянием.
Сама модель без состояния навсегда: её параметры заморожены после обучения, и ничто во время инференса их не меняет. Модель не учится на ваших поправках, не помнит, что ей говорили то же самое вчера, и не «узнаёт» вас — как бы разговор это ни ощущался. Ощущение непрерывности внутри сессии изготовлено harness: он хранит транскрипт и отправляет его заново с каждым запросом. Модель не помнит разговор; она перечитывает его.
Практическое следствие: если что-то должно помниться между сессиями, это нужно записать туда, откуда агент прочитает это обратно. Для этого и нужны файлы AGENTS.md, системы памяти и артефакты передачи — файлы, которые загружаются в контекст будущих сессий и стоят вместо памяти, которой у модели нет. Когда агент снова делает ошибку, которую вы уже исправляли, вопрос не в том, почему он не научился — он не может, — а в том, куда записать эту поправку, чтобы каждая будущая сессия её прочитала.
Пример:
«Почему оно забывает соглашение каждый раз, когда я очищаю сессию?»
«Модель без состояния — новая сессия начинается пустой. Если это нужно перенести, запишите в AGENTS.md или в файл памяти, который harness грузит в начале сессии.»
Контекст¶
Context. Релевантная информация, к которой агент имеет доступ прямо сейчас. Абстрактное существительное: не сырой вход, который видит модель (это контекстное окно), и не текущая история (это сессия), а то, что агент знает и что относится к задаче. «Загрузить что-то в контекст» значит сделать это частью этого набора. «Инженерия контекста» — дисциплина его курирования.
Три термина разделяются чисто:
| Термин | Что называет |
|---|---|
| Контекст | Информация, релевантная задаче, которая сейчас есть у агента |
| Контекстное окно | Буквальная последовательность токенов, которую модель видит на запрос |
| Сессия | Текущий разговор, который хранит harness |
Разделение важно, потому что контекст — мера качества, а не количества. Контекстное окно может быть почти полным, а контекст — бедным: тысячи токенов устаревшего вывода инструментов, и ничего про задачу. Оно может быть почти пустым, а контекст — отличным: одно определение типа, на котором держится задача.
Большинство повседневных сбоев восходит к контексту. Когда агент выдумывает API, противоречит решению или угадывает схему, первый вопрос — что было в контексте в тот момент. Обычно нужный факт так и не загрузили или его похоронила деградация внимания. Лекарство — кураторство: загружать то, что нужно задаче, и не пускать то, что не нужно.
Пример:
«Оно всё выдумывает поля, которых нет в типе.»
«Файл типа не в контексте. Оно читает места вызова и угадывает. Сначала прочитайте определение.»
Контекстное окно¶
Context window. Всё, что модель видит на каждом запросе к провайдеру. Конечное, своё у каждой модели и единственная поверхность, через которую модель что-либо воспринимает.
Это одна последовательность токенов: системный промпт, разговор до сих пор, каждый результат инструмента, который harness вернул обратно. Если что-то есть в этой последовательности, модель может этим пользоваться. Если нет — модель не знает, что оно существует: ни ваша кодовая база, ни файл, который вы правили вчера, ни инструкция трёх сессий назад. Всё вне окна нужно внести, обычно через вызов инструмента, прежде чем оно на что-то повлияет.
Конечность значит, что окно заполняется. Каждый ход дописывает ещё: ваши сообщения, ответы модели, результаты инструментов. Длинная сессия в конце концов упрётся в предел, и понадобятся компактизация или очистка. Это также значит, что всё в окне конкурирует: каждый загруженный токен — на один меньше для остального, а ненужное содержимое всё равно занимает внимание модели. Практическая позиция — относиться к окну как к бюджету: грузить то, что нужно задаче, остальное оставлять снаружи.
Избегать: «память». Контекстное окно — рабочее состояние и не переживает сессии. Память — отдельное понятие поверх.
Пример:
«Можно просто вставить весь монорепозиторий в промпт?»
«Контекстное окно — 200 тысяч токенов, это примерно пятая часть репозитория. Возьмите файлы, которых касается задача, остальное оставьте за вызовом инструмента.»
С состоянием¶
Stateful. Переносит информацию вперёд. Сессия имеет состояние между ходами: контекст копится по ходу сессии, поэтому длинные сессии сползают в тупую зону. Агента можно сделать имеющим состояние между сессиями, добавив систему памяти, которая сохраняет информацию в среду и загружает её в начале будущих сессий. Модель никогда не имеет состояния; любая видимая непрерывность — это harness, который заново подаёт контекст. Парный термин — без состояния.
Где живёт состояние на каждом слое:
| Слой | Есть состояние? | Как |
|---|---|---|
| Модель | Никогда | Параметры заморожены; она видит только то, что в каждом запросе |
| Сессия | Между ходами | Harness дописывает каждое сообщение и результат инструмента в контекст |
| Harness | Между сессиями | Файлы памяти, AGENTS.md, артефакты передачи — записаны и позже загружены |
| Среда | Всегда | Файлы остаются, идёт сессия или нет |
Состояние каждого слоя построено перечитыванием того, что хранится слоем ниже: сессия ощущается непрерывной, потому что harness заново отправляет историю сообщений модели без состояния, а агент помнит между сессиями, потому что harness заново грузит файлы из среды. В самой модели состояние никогда не хранится.
Состояние нужно не всегда. Всё, что перенесено вперёд, влияет на то, что будет дальше, поэтому неверное допущение в начале сессии тоже переносится. Очистка — намеренный акт выбросить состояние сессии и начать с того, что записано.
Пример:
«Оно вспомнило мои предпочтения со вчера. Значит, модель их выучила?»
«Нет. Агент имеет состояние, потому что harness записал их в файл памяти и загрузил в начале сессии. Сама модель вчерашнего не видела.»
Агент¶
Agent. Модель в harness с инструментами, системным промптом и контекстным окном, которая обменивается ходами с пользователем. Claude Code — агент. Cursor — агент. Claude.ai — агент. Агент — то, с чем вы на самом деле говорите: модель в движении, настроенная под цель.
В отличие от большинства терминов этого словаря, «агент» не называет механическую деталь. Модель — файл параметров; harness — программа, на которую можно указать. Агент — ни то ни другое: это единица, к которой вы обращаетесь. Люди постоянно очеловечивают ИИ, и агент — очеловеченная единица: то, чему вы делегируете, то, что читает сообщение и отвечает, то «оно» в «оно снова сломало сборку». Когда вы говорите, что агент что-то сделал, вы имеете в виду, что это сделали модель плюс harness, но обращаетесь к сочетанию как к одному действующему лицу.
Идея старше этой волны ИИ. Программные агенты — программы, которым делегируют цель и которые действуют от вашего имени, — существуют столько же, сколько существует ИИ.
Избегать: «ИИ», «бот». Слишком расплывчато: скрывает, имеете ли вы в виду параметры или собранную в harness вещь.
Пример:
«Какого агента ты используешь для миграции?»
«Локально Claude Code, для UI — Cursor. Под ними одна модель, разные harness.»
Системный промпт¶
System prompt. Инструкции, которые harness приписывает в начало каждого запроса к провайдеру. Постоянный бриф агента: кто он, как себя вести, какие инструменты может вызывать, каким соглашениям следовать. Обычно стабилен на протяжении сессии.
Системный промпт пишет вендор harness, а не вы, и в кодовых harness он большой — часто десятки тысяч токенов правил поведения, описаний инструментов и обработки краевых случаев. Всё это оплачивается как входные токены на каждом ходе. Ваши собственные постоянные инструкции едут рядом: файлы вроде AGENTS.md загружаются рядом с системным промптом в начале сессии, так что модель читает бриф вендора и ваш вместе, ещё до вашего сообщения.
Поскольку он одинаков на каждом запросе, он образует начало префиксного кеша. Отчасти поэтому harness держат его фиксированным на всю сессию, а не правят по ходу.
Модели обучены ставить системный промпт выше сообщений пользователя. Поэтому когда агент настаивает на соглашении, о котором вы не просили, или формат выхода не удаётся стряхнуть, он обычно слушается системного промпта, а ваше сообщение проигрывает спор. Некоторые harness настраиваются: дают полный доступ к системному промпту, так что можно прочитать, что агенту на самом деле говорят, и изменить это.
Пример:
«Два harness, одна модель, совершенно разное поведение на одном промпте.»
«Разные системные промпты. Один настроен на короткие правки кода, другой — на объяснения. Расхождение живёт там, ещё до того, как приходит ваше сообщение.»
Сессия¶
Session. Один ограниченный прогон взаимодействия с агентом. Начинается пустой, копит сообщения, результаты инструментов и прочитанные файлы и заканчивается, когда её очищают, закрывают или компактизируют в свежую сессию. Сессия — то, что наполняет контекстное окно: если окно — коробка, сессия — то, что медленно её заполняет. Работа, которая не влезает в одно окно, должна быть разрезана по сессиям.
История сообщений сессии — рабочая память агента. Модель без состояния, поэтому всё, что она будто помнит — что вы просили, что сказали тесты, что она решила три хода назад, — лежит в истории сообщений и отправляется заново с каждым запросом к провайдеру. Чего нет в сессии, для агента не существует.
Эта память кончается вместе с сессией. Новая сессия начинается с нуля: агент, который в конце вчерашней сессии хорошо знал кодовую базу, сегодня утром не знает ничего из этого. Что переживает сессию — файловая система. Файлы, записанные в одной сессии, может прочитать следующая. На этом держатся передачи, системы памяти и AGENTS.md.
Вы выбираете, где сессия кончается. Всё в сессии влияет на каждый следующий ход, так что несвязанные задачи в одной сессии оставляют осадок, который окрашивает следующий ответ. Одна задача на сессию держит контекст релевантным; конец задачи — естественная точка очистки.
Пример:
«Как долго одна сессия может идти, пока не развалится?»
«Зависит от работы. Сосредоточенный рефакторинг остаётся острым дольше, чем открытое исследование. Когда сессия раздувается, передайте или компактизируйте, не продавливайте.»
Ход¶
Turn. Одно сообщение пользователя плюс всё, что агент делает в ответ, пока не вернёт управление пользователю. Содержит один или несколько запросов к провайдеру — много, если агент вызывает инструменты. Уточняющий вопрос закрывает ход; ваш ответ открывает следующий. Иерархия: сессия > ход > запрос к провайдеру.
Ход стоит называть, потому что его длина — решение агента, а не ваше. Вы отдаёте одно сообщение; агент решает, сколько вызовов инструментов сцепить, прежде чем уступить. Ход может быть ответом в одно предложение или двадцатью минутами чтения, правок и запуска тестов. Это одно свойство с двух сторон: длинные ходы делают возможной работу AFK, и длинные ходы — то место, где без присмотра всё идёт не так. К моменту, когда агент уступает, он мог далеко уйти от того, что вы имели в виду.
Ход — также естественная единица управления. Всё внутри хода происходит без вас; промежутки между ходами — где вы перенаправляете. Большинство harness смягчают это: можно прервать ход, остановить агента и перенаправить его, или набрать сообщение, пока он работает, — его прочитают, когда ход завершится. Если вас раз за разом не устраивает, где ходы заканчиваются, обычно помогает просить ходы меньше: сначала план, по одному шагу. Автономия меняется на более частые щели, в которые можно вмешаться.
Пример:
«Один ход занял две минуты?»
«Внутри этого хода было четырнадцать вызовов инструментов, и каждый — отдельный запрос к провайдеру. Задержка складывается, прежде чем агент наконец вернёт управление вам.»
Инструменты и среда¶
Десять терминов о том, как агент видит мир и меняет его.
Среда¶
Environment. Мир, на который действует агент: всё вне harness, что агент воспринимает через результаты инструментов и меняет через вызовы инструментов. Harness запускает агента; среда — то, в чём агент работает. Файл вроде AGENTS.md живёт в среде; harness — то, что загружает его в контекстное окно. Файловая система — самый частый вид среды, но не единственный: база данных, удалённый API, сессия браузера тоже могут быть средой.
Агент видит среду, только когда смотрит. Всё, что он знает о среде, пришло через результат инструмента, так что его картина — набор снимков, каждый точен в момент съёмки. Если файл изменился после того, как агент его прочитал — вы правите его руками, шаг сборки его перегенерировал, — агент продолжает рассуждать по устаревшей копии, пока что-то не заставит перечитать. Агент, который уверенно описывает файл, уже не похожий на это, обычно в такой ситуации: среда сдвинулась, снимок — нет.
Среда — также слой, который сохраняется, единственный, который всегда имеет состояние. Контекст сессии исчезает, когда сессия кончается, но файлы, записанные в среду, остаются для следующей сессии. На этом держатся системы памяти, артефакты передачи и AGENTS.md. Всё, что агент должен знать завтра, должно оказаться в среде.
Вы решаете, насколько среда велика. Песочница её сжимает и ограничивает, до чего агент может дотянуться. Добавление инструмента её расширяет и подключает базу или API. Что внутри границы — то агент может воспринимать и менять; всего вне границы для агента не существует. Насколько среда устроена так, чтобы поддерживать работу агента, — это AX кодовой базы.
Избегать: называть «средой» рантайм или сам harness. Harness — обёртка, среда — рабочее пространство.
Пример:
«Агент не видит схему staging-базы.»
«Подключите её к среде: дайте инструмент psql только на чтение staging. Harness в порядке, ему просто не на что действовать.»
Файловая система¶
Filesystem. Дерево файлов и каталогов, из которого агент читает, в которое пишет и внутри которого исполняет. Вид среды по умолчанию для кодового агента. AGENTS.md, навыки, исходный код, скрипты сборки и конфиги инструментов живут в файловой системе. Когда harness «стартует в вашем проекте», он направляет агента на файловую систему.
Агент касается её только через вызовы инструментов: прочитать файл, записать файл, выполнить команду оболочки. Ничего на диске нет в контекстном окне, пока вызов инструмента это не загрузит. Поэтому агент может работать в репозитории, который намного больше окна: файловая система держит всё, контекст — только то, что прочитала текущая задача. Некоторые harness по умолчанию грузят в окно имена файлов текущего каталога — не содержимое, только дерево. Они работают как указатели контекста: агент видит, что существует, и читает нужные файлы.
И она общая с вами. Файлы, которые правит агент, — те же, что вы открываете в редакторе и смотрите в diff git. Файловая система — общее рабочее пространство, где вы ревьюите сделанное агентом.
Пример:
«Почему оно не подхватывает мой AGENTS.md?»
«Оно работает с другой файловой системой: песочница смонтировала родительский каталог, а не корень проекта. Перенаправьте harness.»
Инструмент¶
Tool. Функция, которую harness открывает агенту для вызова: Read, Write, Bash, Search. Инструменты — то, как агент воспринимает среду и действует на неё: он не видит среду иначе как через результаты инструментов и не меняет её иначе как через вызовы инструментов. Каждый вызов стоит лишнего запроса к провайдеру, потому что результат должен вернуться к модели, прежде чем она решит, что делать дальше.
Инструменты, с которыми поставляется большинство кодовых агентов:
| Инструмент | Что делает |
|---|---|
| Read | Возвращает содержимое файла как результат инструмента |
| Write | Создаёт или правит файл в файловой системе |
| Bash | Запускает команду оболочки и возвращает её вывод |
| Search | Ищет файлы или текст по шаблону по всей кодовой базе |
Инструмент задаётся тремя вещами: именем, описанием того, что он делает, и схемой параметров. Harness отправляет эти определения модели с каждым запросом, и модель выбирает инструмент так же, как порождает всё остальное, — записывая токены, в этом случае структурированный вызов с аргументами. Модель сама ничего не исполняет; harness читает вызов, запускает функцию и отправляет результат обратно.
Список инструментов задаёт, что агент может делать. Способная модель с узким набором инструментов — узкий агент: он прогонит всё через то, что есть. Поэтому агенты так сильно опираются на Bash: оболочка — один инструмент, который достаёт до большей части системы. Чтобы чисто дать агенту возможность, добавьте для неё инструмент. MCP — стандарт подключения инструментов извне harness.
Определения инструментов занимают контекст на каждом запросе, так что большой набор имеет постоянную стоимость ещё до любого вызова. Много похоже описанных инструментов ухудшает выбор нужного.
Пример:
«Может ли агент запрашивать staging напрямую?»
«Добавьте в harness инструмент psql только на чтение staging. Без инструмента для этого агент слеп ко всему вне файловой системы.»
Вызов инструмента¶
Tool call. Выход модели, который называет инструмент и его аргументы. Просто структурированный текст. Сам по себе он ничего не делает; harness должен его прочитать и исполнить. Порождается моделью в одном запросе к провайдеру.
Жизненный цикл вызова инструмента:
| Шаг | Кто | Что происходит |
|---|---|---|
| 1 | Модель | Узнаёт, какие инструменты есть, из описаний в системном промпте |
| 2 | Модель | Испускает вызов — имя инструмента плюс аргументы, обычно JSON, — и останавливается |
| 3 | Harness | Разбирает вызов и сверяет его с режимом разрешений |
| 4 | Harness | Исполняет, если разрешено |
| 5 | Harness | Отправляет исход обратно как результат инструмента в следующем запросе |
Один ход работы агента — обычно много таких кругов, сцепленных вместе.
Поскольку вызов порождается предсказанием следующего токена, как и всё остальное, он может быть неверным так же, как любой выход модели: путь, которого нет, флаг, которого у команды нет, аргументы правдоподобные, а не правильные. Harness исполняет написанное, а не задуманное: путь с опечаткой не падает мягко, он правит не тот файл.
Пример:
«Оно сказало, что запустило тесты, но метки времени файлов не изменились.»
«Посмотрите транскрипт: оно правда испустило вызов инструмента или только описало запуск? Вызов порождает модель, но если harness его не исполнил, ничего не произошло.»
Результат инструмента¶
Tool result. То, что harness отправляет обратно после исполнения вызова инструмента: содержимое файла, вывод команды, ошибка. Единственный вид агента на среду. Возвращается к модели в следующем запросе к провайдеру, где модель решает, что с ним делать. Вызов и результат — два конца одного обмена, оба внутри одного хода.
Жизненный цикл результата инструмента:
| Шаг | Кто | Что происходит |
|---|---|---|
| 1 | Harness | Исполняет вызов: запускает команду, читает файл |
| 2 | Harness | Захватывает исход: вывод, содержимое или ошибку |
| 3 | Harness | Дописывает его в контекст как сообщение |
| 4 | Harness | Отправляет весь контекст провайдеру в следующем запросе |
| 5 | Модель | Читает результат и решает: ещё один вызов или финальный ответ |
Результат остаётся в контексте до конца сессии. Результаты инструментов обычно составляют основную массу контекста кодовой сессии: каждое чтение файла, каждый прогон тестов, каждый поиск ложится целиком и продолжает занимать токены ещё долго после того, как перестал быть полезен. Несколько крупных результатов — подробный лог тестов, сгенерированный файл, прочитанный целиком, — могут подтолкнуть сессию к краю контекстного окна быстрее, чем сам разговор.
Поскольку результат — всё, что видит модель, у неё нет способа проверить среду за ним. Если вывод обрезали, команда тихо упала или harness вернул ошибку вместо содержимого, модель рассуждает из того, что ей дали. Когда картина системы у агента кажется неверной, смотрите результаты инструментов: где-то в транскрипте есть результат, который говорит иное, чем вы знаете как истину.
Пример:
«Оно рассуждает о файле так, будто он пустой.»
«Результат инструмента вернулся как отказ в доступе, а не как содержимое. Модель видела только строку ошибки. Другого способа увидеть файл у неё нет.»
MCP¶
Model Context Protocol. Протокол подключения внешних серверов инструментов к harness: так агент получает инструменты сверх тех, с которыми harness поставляется. Агент никогда «не вызывает MCP»; он вызывает инструмент, а harness так вышло, что получил этот инструмент от MCP-сервера. Протокол также открывает ресурсы (данные только для чтения) и промпты (переиспользуемые шаблоны), но основное применение — поставка инструментов.
Протокол решает задачу интеграции. Без стандарта каждому harness нужна была бы своя интеграция с Linear, своя со Slack, своя с базой — написанная и поддерживаемая отдельно. С MCP интеграция пишется один раз как сервер, и любой совместимый harness может ей пользоваться. Harness подключается к серверу, сервер объявляет, какие инструменты предлагает, и эти инструменты становятся доступны агенту рядом со встроенными.
Цена платится контекстом. Каждый инструмент, который объявляет сервер, приходит как определение — имя, описание, схема параметров, — а модель может вызывать только инструменты, о которых знает. Наивный подход грузит все определения в контекстное окно заранее: поставьте несколько щедрых серверов, и сессия начинается с тысяч токенов схем инструментов ещё до того, как вы что-то набрали, тратя бюджет внимания на инструменты, которые задача никогда не использует.
Многие harness теперь смягчают это поиском инструментов: вместо полных определений контекст держит указатель контекста на доступные инструменты. Агент ищет инструмент по имени или назначению и грузит определение, только когда оно нужно. Если ваш harness так не делает, авансовая стоимость остаётся, и стоит включать только те серверы, которые проекту реально нужны.
Пример:
«Агенту нужно читать тикеты из Linear.»
«Настройте harness на MCP-сервер Linear: он открывает API Linear как инструменты, которые агент может вызывать. Не придётся писать свои обёртки.»
Запрос разрешения¶
Permission request. То, что harness показывает пользователю перед исполнением вызова инструмента, который не одобрен заранее. Модель порождает вызов; вместо немедленного запуска harness останавливается и спрашивает. Одобрите — он выполнится; откажите — harness сообщит отказ модели как результат инструмента. Механизм, которым harness ставит человека в контур для рискованных или чувствительных действий.
Жизненный цикл запроса разрешения:
| Шаг | Кто | Что происходит |
|---|---|---|
| 1 | Модель | Порождает вызов инструмента |
| 2 | Harness | Сверяет его с режимом разрешений и сохранёнными одобрениями |
| 3 | Harness | Уже одобрено: исполняет сразу. Иначе: останавливается и показывает запрос |
| 4 | Пользователь | Одобряет один раз, одобряет на остаток сессии или отказывает |
| 5 | Harness | Исполняет вызов или отправляет отказ обратно как результат инструмента |
Отказ направляет агента. Модель читает отказ как любой другой результат и реагирует: пробует другой подход или спрашивает, что вы предпочитаете. Большинство harness позволяют приложить к отказу сообщение, и тогда запрос становится точкой управления: «не так, используй скрипт миграции» приходит ровно в момент, когда модель решает, что делать дальше.
Цена в том, что каждый запрос — синхронное ожидание вас. Агент сидит заблокированным, пока вы не ответите. Это нормально, пока вы смотрите, и проблема, когда нет: агент, который постоянно поднимает запросы, нельзя оставить работать AFK. Режим разрешений — регулятор: какие вызовы идут свободно, какие сначала спрашивают. В идеале песочница делает безопасным расширить свободный набор.
Пример:
«Оно десять минут висело на запросе разрешения. Я был на встрече.»
«Это цена человека в контуре. Одобрите заранее безопасные инструменты, чтобы запрос срабатывал только на действительно рискованных вызовах.»
Режим разрешений¶
Permission mode. Срез режима агента, который задаёт ограничения: какие вызовы инструментов поднимают запрос разрешения, а какие идут сами. Исходное назначение систем режимов, до того как harness начали навешивать сверху ещё и поведенческие инструкции.
Harness поставляют лестницу таких режимов:
| Режим | Чтения | Записи и оболочка | Типичное применение |
|---|---|---|---|
| Только чтение / план | Само | Заблокированы | Исследование, планирование, ревью |
| По умолчанию | Само | Спросить | Повседневная работа под присмотром |
| Автоправки | Само | Правки сами, оболочка спрашивает | Доверенные репозитории, механические изменения |
| «Yolo» / полный автомат | Само | Само | Песочницы, прогоны AFK |
Выбор ступени — обмен безопасности на прерывания, и оба провала ощущаются. Слишком туго — и вы становитесь узким местом: агент останавливается каждые несколько секунд на безвредных чтениях, вы жмёте «одобрить» на автомате, и одобрения перестают что-либо значить. Штампование — худшее из обоих миров: все прерывания и никакой защиты. Слишком свободно — и агент правит файлы и запускает команды, которые вы хотели бы увидеть сначала.
Свободный конец наиболее защитим внутри песочницы, где радиус поражения плохого вызова инструмента ограничен. Вне её большинство людей останавливаются на автоодобрении чтений и держат человека в контуре для всего необратимого.
Пример:
«Оно останавливалось на каждом grep и полностью убило прогон AFK.»
«Ослабьте режим разрешений для инструментов только на чтение, спрашивайте на записях и оболочке. Большинство запросов разрешений в исследовательской сессии — шум.»
Режим агента¶
Agent mode. Пресет, который задаёт, как агент работает в рантайме: связывает режим разрешений с поведенческими инструкциями, впрыснутыми в системный промпт. Примеры: режим по умолчанию, который спрашивает на рискованных вызовах; режим плана, который блокирует правки и направляет агента к исследованию; режим принятия правок, который одобряет правки сам; режим обхода разрешений (в просторечии режим YOLO), который одобряет всё сам. Можно переключать посреди сессии.
Связка отличает режим от голой настройки разрешений. Режим разрешений — только ограничения: он решает, какие вызовы инструментов проходят. Одни ограничения дают агента, который хочет править, но не может: предлагает запись, получает блок и пробует иначе. Впрыснутые инструкции убирают само желание: режим плана не просто блокирует правки, он говорит агенту, что тот в фазе планирования, так что он читает, спрашивает и предлагает, а не упирается в ограничения. Ограничения и направление смотрят в одну сторону.
На практике режим меняют по мере того, как меняется доверие по ходу задачи. Одна задача может пройти несколько режимов: план, пока подход ещё формируется; спрашивающий режим по умолчанию для первых тонких правок; принятие правок, когда агент показал, что понял изменение; обход для прогона AFK внутри песочницы. Смена режима ничего не стоит: разговор продолжается ровно с того места, с новыми разрешениями и новыми инструкциями. Если вы одобряете каждый запрос, не читая, режим поставлен туже вашего реального доверия. Если вы раз за разом отклоняете правки, он поставлен свободнее.
Термины вендоров: Claude Code называет это «режимами разрешений», Codex — «режимами одобрения». Оба названия старше, чем связка с поведением.
Пример:
«Оно всё правит файлы, когда мне нужен только план.»
«Переключитесь в режим плана: он заблокирует записи и останется в исследовании.»
«А для прогона AFK позже?»
«Режим обхода, но только внутри песочницы.»
Песочница¶
Sandbox. Изолированная среда, внутри которой работает агент: контейнер, виртуальная машина, эфемерная файловая система или оболочка с урезанными правами. Ограничивает радиус поражения действий агента: даже если агент запускает разрушительные команды или тянет что-то вредоносное, ущерб остаётся внутри. Подложка безопасности, которая делает практичной работу AFK.
Песочница и режим разрешений решают одну задачу с противоположных концов. Разрешения спрашивают до того, как действие выполнится; песочница ограничивает, до чего действие может дотянуться, если оно всё же выполнится. Разрешения требуют, чтобы вы были в контуре: каждый запрос — прерывание, и сессия, которая спрашивает постоянно, едва автономна. Песочница тратит инфраструктуру вместо внимания: чем сильнее изоляция, тем меньше вопросов нужно задавать.
Изоляция бывает разной силы:
| Уровень | Что это | Что сдерживает |
|---|---|---|
| Ограниченная оболочка | Изоляция на уровне ОС вокруг каждой команды | Записи вне проекта, доступ в сеть |
| Контейнер | Свежая файловая система, без смонтированных учётных данных, выбрасывается после | Всё, что агент делает со своей машиной |
| ВМ / облако | Отдельная машина целиком, часто её даёт сам harness | Всё, включая побеги на уровне ядра |
Чего не сдерживает ни одна песочница: действия, которые законно её покидают. Агент с вашими учётными данными git может пушить; агент с доступом в сеть может звать продовые API. Сначала решите, что пересекает границу, и только потом — какой толщины её делать.
Пример:
«Хочу оставить его на ночь в режиме обхода разрешений, но к этому не готов.»
«Посадите его в песочницу: свежий контейнер, без учётных данных, без выхода в сеть. Худший случай — он снесёт свою файловую систему, и вы выбросите контейнер.»
Режимы отказа¶
Девять терминов о том, почему уверенный ответ оказывается неверным.
Сикофантия¶
Sycophancy. Уверенно соглашающийся выход модели. Причина в обучении: модель сформировали так, чтобы она предпочитала ответы, которые нравятся людям, а людям чаще нравится согласие, чем когда им говорят, что они неправы. Поэтому модель выучила, что согласие вознаграждается, даже когда согласие неверно.
Проявляется как:
- Сдаётся под нажимом — отменяет верный ответ, когда вы говорите «ты уверен?».
- Хвалит плохой вход — соглашается, что ваш сломанный план блестящий, ещё до разбора.
- Смещённая рамка — ревью уходит в плюс, когда вы даёте понять, что написали это сами, и в минус, когда даёте понять, что написал кто-то другой. Тот же артефакт, другой вердикт.
- Подражание — возвращает вам ваши ошибки как подтверждение.
Диагностический тест: сказала бы модель это без вашего направления? Если изменились только тон или рамка, это сикофантия, а не настоящий сдвиг анализа.
Как исправить: спрячьте предпочтения. Формулируйте промпты нейтрально: «разбери этот код», а не «этот код хорош?».
Избегать: называть сикофантией любой неверный ответ, который вам приятен. Без диагностического теста у термина не больше цены, чем у слова «неверно».
Пример:
«Оно сказало, что план рефакторинга выглядит отлично, потом я спросил „ты уверен?“ — и оно всё откатило.»
«Классическая сикофантия: сначала согласилось, потому что вы звучали уверенно, потом сдалось, потому что вы звучали сомневающимся. Качество плана не изменилось, изменился ваш тон. Очистите сессию и спросите снова, не сигналя ни в ту, ни в другую сторону.»
Галлюцинация¶
Hallucination. Уверенно неверный выход модели. Два вида с разными причинами и разными лекарствами:
| Вид | Что идёт не так | Причина | Лекарство |
|---|---|---|---|
| Фактичность | Выдуманные или неверные факты о мире: функции, которой нет, неверная сигнатура API, фальшивая ссылка | Дыры параметрического знания, часто за границей знаний | Загрузить нужное контекстное знание |
| Верность | Выход уходит от загруженного контекстного знания, инструкций пользователя или собственных прежних рассуждений модели | Деградация внимания; хуже в тупой зоне | Очистить или компактизировать |
Предсказание следующего токена порождает беглый выход независимо от того, реален ли факт под ним. У модели нет внутреннего сигнала, что она чего-то не знает, поэтому выдуманный метод приходит в том же уверенном регистре, что и верный. Галлюцинированный код правдоподобен по построению: он выглядит так, как API выглядел бы, если бы существовал. Именно поэтому он проскакивает беглый просмотр и падает только при запуске.
Нужно знать, какой вид перед вами, потому что лекарство одного ухудшает другое. Фактичность — недостающее знание: лекарство — добавить контекст, документацию, определения типов, файл. Верность — знание есть, но проигрывает борьбу за внимание: лекарство — убрать контекст. Примите верность за фактичность, вставите ещё документации, контекст вырастет, и дрейф станет хуже. Когда агент ошибается, сначала проверьте, была ли верная информация уже в контексте, и только потом решайте, какая это проблема.
Избегать: «галлюцинация» как голый синоним «неверно». Без имени вида у термина нет диагностической цены.
Пример:
«Оно выдумало метод parseAsync у схемы.»
«Фактичность или верность?»
«Метод есть в документации, которую я вставил. Оно просто перестало её читать после сорокового хода.»
«Тогда верность. Компактизируйте и загрузите заново, не добавляйте ещё документации.»
Параметрическое знание¶
Parametric knowledge. То, что модель «знает» из обучения, хранимое в её параметрах. Заморожено в момент обучения: модель не видит собственные параметры и не обновляет их. Деталь теряется при сжатии: миллиарды фактов втискиваются в фиксированное число параметров, и редкие размываются. Источник беглости на частых темах и выдумок на редких. Парный термин — контекстное знание.
Параметрическое знание не хранится как факты. Обучение никогда не даёт модели базу, в которой можно искать. Оно подкручивает параметры, пока модель хорошо предсказывает текст, и модель, которая хорошо предсказывает текст о теме, ведёт себя так, будто тему знает. Насколько знание надёжно, следует за тем, как часто что-то встречалось в обучающих данных: тема с миллионами примеров воспроизводится точно, тема с горсткой примеров — модель угадывает по тому, как выглядят похожие темы. Воспроизведение и угадывание для модели — один процесс, поэтому она не отличает, какой из них сейчас делает. Выдуманный ответ приходит с той же беглостью, что и верный. Галлюцинация — это модель, которая угадала неверно.
Параметрическое знание ещё и стареет. Параметры перестают меняться на границе знаний, поэтому библиотеки, вышедшей или переименованной после этой даты, в них нет, а изменившийся API помнится в старой форме.
Для обеих дыр — слишком редкое и слишком свежее — лекарство одно: знание нельзя добавить в параметры, его нужно подать как контекстное.
Пример:
«Оно пишет безупречный React и выдумывает методы нашего внутреннего SDK.»
«React плотно сидит в параметрическом знании — миллионы обучающих примеров. Вашего SDK там нет, поэтому модель дорисовывает правдоподобные формы. Загрузите документацию SDK в контекст.»
Граница знаний¶
Knowledge cutoff. Дата, после которой у модели нет параметрического знания. Библиотеки, API и события после границы — ловушки для выдумок, если их документация не загружена как контекстное знание. У каждого релиза модели своя граница.
Граница существует из-за того, как делают модели: обучение запекает снимок текста в параметры, и после этого параметры заморожены. Модель не знает, что у её знания есть край. Спрошенная о чём-то за границей, она не отказывается, а экстраполирует из ближайшего, что знает. Поэтому ловушка тихая: код, написанный против старой версии библиотеки, выглядит правдоподобно, часто компилируется и падает на тех частях, которые изменились.
Лекарство всегда одно: внести актуальную информацию в контекст. Загрузите changelog, укажите на определения типов установленной версии или дайте агенту прочитать документацию из сети. Всё, что в контексте, перевешивает «ничего в параметрах».
Пример:
«Оно всё пишет синтаксис SDK v3, а мы на v5.»
«v5 вышла после границы знаний. Загрузите changelog v5 как контекстное знание, иначе оно продолжит выдумывать из более старой параметрической версии.»
Контекстное знание¶
Contextual knowledge. Факты, которые агент может прочитать прямо из контекста сейчас: задача пользователя, файлы, которые агент прочитал, результаты инструментов, содержимое AGENTS.md, загруженное в начале сессии. Парный термин к параметрическому знанию: параметрическое вспоминается из параметров, контекстное читается из окна. Галлюцинации гораздо реже, когда агент работает из контекстного знания: ответ прямо перед ним, а не вытащен из размытой памяти.
Из двух видов знания только контекстное в вашей власти. Параметры заморожены, поэтому единственный способ дать модели знание, которого ей не хватает, — внутренний SDK, библиотеку после границы знаний, решение, принятое вчера, — положить его в контекст. Большая часть практической работы ИИ-кодинга сводится к этому: положить нужные факты перед моделью в момент, когда они ей нужны.
Когда контекстное и параметрическое знание конфликтуют, обычно побеждает контекстное. Вставьте актуальную документацию API, и модель следует ей, а не устаревшей памяти о старом API. Старая версия всё же может просачиваться, особенно глубоко в длинной сессии. Если агент возвращается к устаревшему паттерну, хотя документация загружена, это параметрическое знание протекает мимо контекстного. Помогает повторить поправку или подвинуть её ближе к работе.
В отличие от параметрического, контекстное знание чего-то стоит в использовании. Всё, загруженное в окно, тратит токены и конкурирует за бюджет внимания модели, так что «загрузить больше» автоматически не лучше. Цель — релевантные факты в окне, а не все факты.
Берите этот термин, только когда противопоставляете его параметрическому знанию. В остальных случаях говорите просто контекст.
Избегать: «рабочая память». Контекстное знание — то, что в окне сейчас; система памяти — то, что вносит в него содержимое между сессиями. Разный масштаб, не смешивайте.
Пример:
«Почему оно попадает в API, когда я вставляю документацию, и выдумывает, когда не вставляю?»
«С документацией это контекстное знание: чтение со страницы. Без неё — параметрическое, и редкие эндпоинты размываются.»
Отношение внимания¶
Attention relationship. Предсказывая каждый токен, модель учитывает каждый другой токен в контексте: какие-то сильно, какие-то едва. Пара двух токенов — отношение внимания, и осмысленные пары («она» с «Сара» или вызов getUser() с определением function getUser) влияют друг на друга сильнее, чем несвязанные. В контексте из N токенов порядка N² таких отношений.
В парах живёт видимое понимание модели. Она разрешает местоимение, потому что отношение внимания между «она» и «Сара» сильно. Она вызывает функцию с верными аргументами, потому что работу делает отношение между местом вызова и определением, которое она прочитала раньше. Ничего из этого не ищется в таблице: оно заново считается на каждом запросе к провайдеру, для каждой пары.
Цифру N² стоит подержать в голове, потому что она растёт быстрее интуиции:
| Размер контекста | Пары (~N²) |
|---|---|
| 1 000 токенов | ~1 миллион |
| 10 000 токенов | ~100 миллионов |
| 100 000 токенов | ~10 миллиардов |
Каждая пара считается больше одного раза. У моделей несколько голов внимания — точные числа фронтирных моделей не опубликованы, но пятьдесят–сто — разумная оценка, — и каждая голова считает свою версию каждого отношения. Так что каждая пара в таблице выше продублирована по головам. Пар очень много.
Для любой данной задачи имеет значение лишь малое число этих отношений. Пара между вашей инструкцией и кодом, которым она управляет, — одна из горстки тех, что считаются; почти всё остальное в пуле — шум. И растут они с разной скоростью: важные отношения остаются примерно постоянными, а весь пул растёт квадратично с размером контекста. На 1 000 токенов нужная пара — одна на миллион; на 100 000 — одна на десять миллиардов. Это арифметика под бюджетом внимания, а деградация внимания — то, как это ощущается, когда важным отношениям достаётся слишком тонкая доля.
Пример:
«Оно путает два символа user в diff. Похоже, мы в тупой зоне.»
«Да. Отношение внимания между каждым местом вызова и его объявлением борется с другим: та же форма токена, разные привязки. Переименуйте один — и пары станут острее.»
Бюджет внимания¶
Attention budget. У каждого токена конечный запас влияния, который он распределяет по остальному контексту. Сильное влияние на одно отношение оставляет меньше для остальных. Бюджет на токен и не растёт, когда растёт контекст. Поэтому длинные сессии разбавляют.
Думайте о сигнале и шуме. Ваша инструкция — сигнал фиксированной громкости; каждый другой токен в контекстном окне — конкурирующий звук. Инструкция не становится тише: она всё ещё там, символ в символ. Но по мере роста контекста комната вокруг неё громче, и отношение сигнала к шуму падает. Инструкция, которая была самым громким на 10 тысячах токенов контекста, на 150 тысячах — фоновый гул. Это механизм за деградацией внимания: модель не забывает, сигнал теряется в шуме.
Симптом читается как непослушание: агент согласился с ограничением в начале и потом от него уходит, а повторная вставка ограничения помогает лишь ненадолго. Причина не в инструкции, а во всём остальном в окне, что с ней конкурирует.
Что вы контролируете — то, что попадает в контекст. Содержимое, которое не служит задаче, не нейтрально: это шум поверх всего, что служит. Держите окно небольшим, очищайте, когда накопленный контекст перестаёт окупаться, и заново формулируйте важные ограничения, а не рассчитывайте, что раннее упоминание удержится само.
Пример:
«Почему оно игнорирует схему, которую я вставил наверху?»
«Мы уже глубоко в тупой зоне. Бюджет внимания каждого токена фиксирован, а контекст всё рос. Сигнал на схеме теперь конкурирует с тысячами более новых токенов.»
Деградация внимания¶
Attention degradation. По мере роста сессии бюджет внимания каждого токена размазывается по большему числу конкурентов. Сигнал на любом одном осмысленном отношении сжимается; шум из нерелевантного контекста набивается внутрь. Та же модель, те же параметры — просто больше ртов с одной тарелки. Причина эффекта умной зоны и тупой зоны.
Проявляется как модель, которая становится хуже посреди сессии: ограничения, которым она следовала час, начинают сползать, она переспрашивает то, что ей уже сказали, пишет код, который игнорирует файл, прочитанный раньше. В модели ничего не изменилось. Единственная переменная — по какому объёму контекста она теперь распределяет внимание.
Это постепенно, и поэтому трудно поймать изнутри сессии. Нет ошибки и нет порога; каждый ход лишь чуть хуже предыдущего, и к моменту, когда промахи очевидны, вы уже какое-то время в тупой зоне.
Восстановление — убрать контекст, а не добавить ещё. Повторная вставка проигнорированной инструкции добавляет ещё одного конкурента в то же тесное окно и помогает лишь ненадолго. Что работает: очистить и загрузить заново только то, что нужно задаче, или компактизировать, или передать свежей сессии. Падающее следование инструкциям читайте как сигнал о длине контекста, а не о модели.
Пример:
«Оно глубоко в тупой зоне: выдумывает дженерики, которых нет в файле типа.»
«Деградация внимания. Определения типов всё ещё в контексте, но сигнал на них погребён под всем, что мы добавили с тех пор. Очистите и загрузите заново.»
Умная зона¶
Smart zone. В начале сессии агент в «умной зоне»: острый, сосредоточенный, вспоминает хорошо. По мере роста сессии он сползает в «тупую зону»: небрежнее, забывчивее, больше ошибок и больше галлюцинаций верности. Та же модель, тот же harness — просто больше контекста. Ощущаемый эффект деградации внимания. На фронтирных моделях тупая зона часто начинается около 125–150 тысяч токенов, хотя это спорно. Очищайте или компактизируйте, когда сессия раздувается; не продавливайте.
Спад постепенный, и его легко пропустить. Нет сообщения об ошибке и нет видимой границы; агент просто начинает работать чуть хуже, потом заметно хуже. Частые признаки: забывает инструкцию двадцати ходов назад, повторяет ошибку, которую уже исправлял, или уверенно утверждает то, чему контекст противоречит. Поскольку скольжение гладкое, обычная реакция — продавить и объяснить заново, что добавляет ещё контекста и ухудшает проблему.
Зоны не следуют за пределом контекстного окна. Сессия может быть глубоко в тупой зоне, когда большая часть окна ещё свободна: предел — то место, где harness отказывается продолжать, но качество падает задолго до этого. Планируйте вокруг умной зоны, а не вокруг окна. Практический бюджет задачи — токены, внутри которых агент работает хорошо, а не токены, которые он технически может удержать.
Умная зона — бюджет, и несвязанная работа его тратит. Каждая задача в сессии съедает токены, так что вторая задача в той же сессии начинается ближе к тупой зоне. Одна задача на сессию даёт каждой задаче самую острую часть сессии. Когда одна задача больше одной умной зоны, разрежьте её: передайте или компактизируйте на естественной границе и дайте следующему куску свежую сессию.
Пример:
«Первые три компонента оно сделало отлично и только что изуродовало четвёртый.»
«Вы вышли из умной зоны: та же модель, просто уже глубоко в тупой. Компактизируйте и загрузите план заново — следующий компонент ляжет.»
Передачи¶
Девять терминов о том, как перенести работу из одной сессии в другую.
Очистка¶
Clearing. Конец текущей сессии и старт свежей. Следующее сообщение начинается с пустой сессии и пустого контекстного окна. Обычно это делает пользователь.
Очистка — лекарство от загрязнённого контекста. Сессия копит всё: неудачные попытки, неверные ходы, устаревшие результаты инструментов, брошенные планы. Модель перечитывает всё это на каждом ходе, и плохая история тянет новую работу. Глубоко в длинной сессии агент становится расплывчатее и менее послушным: ясно данные инструкции игнорируются, качество сползает, и подталкивание «работай лучше» не помогает, потому что шум, через который он бредёт, всё ещё в его контексте. Очистка убирает шум.
Очистка не стирает разговор. Большинство harness хранят историю сессий на вашем компьютере, так что транскрипт всё ещё можно прочитать или возобновить. Пропало рабочее состояние агента: модель без состояния, поэтому новая сессия не знает ничего из того, что знала старая. Если в сессии есть решения или прогресс, которые понадобятся следующей, сначала пусть агент напишет артефакт передачи, а новую сессию начните, указав на него.
Сравните с компактизацией, которая сворачивает сессию в новый контекст, а не начинает с пустого. Очистка — более тупой инструмент: ничего не переносится, включая мусор.
Пример:
«Оно зациклилось на падающем тесте.»
«Просто очистите: свежая сессия с документом плана и файлом теста. Нет смысла бороться с существующим контекстом.»
Передача¶
Handoff. Перенос контекста агента из одной сессии в другую. Механизм переноса бывает разным: письменный артефакт передачи, сводка в памяти (компактизация) и другие. Отличается от очистки, где переноса нет вовсе. Причины разные: смена роли (планировщик → исполнитель), запуск прогона AFK, веер на параллельные сессии или освобождение места в контекстном окне.
Принимающая сессия начинает с нулевого контекста: модель без состояния, и ничего из старой сессии новой не видно. Всё, что нужно следующей сессии, должно быть перенесено явно; остальное пропадает. «Нет обратного пути» — ограничение, которое задаёт форму переноса: новая сессия не может спросить старую, что та имела в виду, поэтому перенесённый материал должен стоять сам по себе.
| Механизм | Форма | Свойства |
|---|---|---|
| Артефакт передачи | Файл в среде | Можно прочитать и поправить, прежде чем от него что-то зависит; переиспользуется многими сессиями |
| Компактизация | Сводка в контекстном окне | Автоматически и дёшево; труднее проверить; кормит одного преемника |
Видимый провал плохой передачи — повторный спор: новая сессия заново открывает решения, которые старая уже закрыла, потому что перенос записал, что решили, но не почему. Судите передачу по тому, что с ней могла бы сделать сессия с нулевым контекстом.
Пример:
«Сессия планирования тяжелеет. Продолжать?»
«Сделайте передачу. Запишите решения в документ, очистите, начните реализацию в свежей сессии, которая читает из него.»
Первичный источник¶
Primary source. Источник истины в исходной форме: код, транскрипт разговора, сырой лог, настоящий ответ API. Не рассказ о вещи, а сама вещь. Парный термин — вторичный источник.
Если вы хотите знать, что делает кодовая база, код — первичный источник. Документация, схема архитектуры и README — описания её: точные в момент написания и с тех пор живущие по своему расписанию. Когда агент уверенно утверждает неверное о проекте, вопрос в том, из какого источника он работал. Агент, который прочитал документ, наследует устаревание документа. Агент, который прочитал код, читает текущую истину.
Цена не даёт первичным источникам быть умолчанием. Загрузка одного в контекстное окно дорога: весь файл, весь транскрипт, каждый токен тарифицируется как вход и конкурирует за бюджет внимания. За эту цену вы получаете полноту: никто заранее не отфильтровал своим суждением, что было важно. Сводка прошлого месяца не может содержать деталь, которая оказалась важной сегодня; первичный источник всё ещё может.
Тянитесь к первичному источнику, когда важна точность: точная сигнатура, настоящая ошибка, строка, которая бросает. Большая часть управления контекстом — решать, когда платить за первичный источник, а когда хватит вторичного.
Пример:
«Агент говорит, что логика ретраев отступает экспоненциально, а я вижу, как она долбит эндпоинт.»
«Оно прочитало это из дизайн-дока. Укажите на сам модуль ретраев. Когда важно поведение, работайте из первичного источника.»
Вторичный источник¶
Secondary source. Рассказ о первичном источнике, на шаг в стороне: документация, описывающая код; сводка, описывающая транскрипт; отчёт, описывающий результаты поиска. Дешевле загрузить в контекстное окно, чем источник, который он описывает, и с потерями по построению: тот, кто писал, решил, что важно, и всё, что он выбросил, невидимо читателю, у которого есть только сводка.
Большая часть инженерии контекста — изготовление вторичных источников. Компактизация превращает историю сессии в сводку, которая сеет следующую сессию. Субагент сжигает свой контекст на шумном поиске и возвращает короткий отчёт. Артефакт передачи сжимает решения сессии в документ, который читает следующая. Системы памяти дистиллируют выученное сессией в заметки. Каждый делает один обмен: верность на запас места.
Вторичные источники ломаются двумя способами. Они с потерями: сводка компактизации потеряла решение по схеме, отчёт не упомянул краевой случай. И они дрейфуют: первичный источник меняется, а рассказ не следует, так что документация описывает архитектуру прошлого квартала с уверенностью этого. Когда агент действует по вторичному источнику, который сломался любым из способов, он уверенно работает из неверной информации. Лекарство — отправить его обратно к первичному источнику.
Ни один из провалов не делает вторичные источники ошибкой. Контекстное окно конечно, первичные источники дороги; без сводок, отчётов и документов передачи ничего крупного не влезает. Навык — знать, какие детали переживут потерю, и сверяться с первичным источником, когда деталь не переживёт. Хорошо сделанный вторичный источник несёт указатель контекста обратно к оригиналу: сводка называет транскрипт, из которого вышла, документ называет файл, который описывает. Когда рассказа недостаточно, читатель идёт по указателю, а не работает из потери.
Пример:
«Документ передачи говорит, что авторизация готова, а новая сессия всё находит сломанное обновление токена.»
«Документ — вторичный источник: прошлая сессия записала, во что верила, а не что истинно. Пусть новая сессия запустит тесты авторизации и доверится первичному источнику.»
Артефакт передачи¶
Handoff artifact. Документ, который служит механизмом переноса для передачи: одна сессия пишет его в среду, другая читает. Спецификации, тикеты и документы планов — все артефакты передачи.
Зачем его писать: модель без состояния, поэтому ничего в сессии не переживает её очистку. Решения, ограничения, недописанные планы — всё уходит вместе с контекстом, который их держал. Среда сохраняется. Запись важного состояния в файл переносит его туда, откуда следующая сессия может прочитать его обратно.
Артефакт — вторичный источник: рассказ о работе сессии, а не сама работа. Поэтому он достаточно мал, чтобы ввести свежую сессию в курс, и поэтому же может её ввести в заблуждение: он записывает, во что верила пишущая сессия, и всё, что она опустила или поняла неверно, невидимо читателю. Где утверждение важно, следующая сессия должна сверить его с первичным источником — кодом, тестами, — а не унаследовать.
Хороший артефакт написан для чтения в сессию с нулевым контекстом. Конкретные пути файлов, а не «тот файл, который мы обсуждали». Что решили и почему, чтобы следующая сессия не спорила заново. Что сделано и что осталось. Помогает сказать пишущей сессии, куда артефакт направляется: «напиши документ передачи для свежей сессии, которая ничего не знает об этой работе».
Альтернативный механизм переноса — компактизация, которая сворачивает в памяти. У артефакта два преимущества: он лежит на диске, где его можно прочитать и поправить, прежде чем от него что-то зависит, и его можно переиспользовать — одна спецификация может ввести в курс пять параллельных сессий.
Пример:
«Как разделить это между планирующим агентом и исполняющим?»
«Пусть планировщик напишет артефакт передачи: пути файлов, решения, ограничения. Сессия исполнителя открывается указателем на артефакт и работает из него как из брифа.»
Спецификация¶
Spec. Артефакт передачи, описывающий работу на много сессий: что строится, а не как каждая сессия делает свою долю. Меняется по мере работы. Состоит из тикетов.
Спецификация существует, потому что сессии одноразовые, а большая работа — нет. Всё, что требует больше одного контекстного окна усилий, нуждается в доме вне контекста: где-то в среде агента, что переживает очистку, будь то файл в репозитории, issue на GitHub или трекер, до которого агент может дотянуться. Спецификация — этот дом: цель, ограничения, уже принятые решения и список тикетов со статусом. Любая свежая сессия может её прочитать и знать, где стоит работа, не наследуя накопленный шум прошлой сессии.
Спецификации бывают узнаваемых стилей, в основном унаследованных от того, как команды уже записывают вещи. Документ требований к продукту (PRD) склоняется к пользовательскому «что» и «зачем»: возможности, поведение, критерии приёмки. Дизайн-док или RFC склоняется к техническому: выбранный подход, отвергнутые альтернативы, компромиссы. На малом конце обычный plan.md с чеклистом тикетов делает ту же работу для фичи на несколько сессий. Стиль важен меньше, чем роль: для агента каждое из них — одно и то же, долговечная формулировка намерения, которую он читает в начале каждой сессии.
Пример:
«Стоит ли делать всё это одной сессией?»
«Нет. Оформите как спецификацию: разбейте на тикеты, каждый гоняйте в своей сессии. Попытка сделать всё в одном контексте упрётся в тупую зону ещё до середины.»
Тикет¶
Ticket. Артефакт передачи, который ограничивает одну сессию работы. Стоит сам по себе или висит на спецификации как один из её детей. Тикеты могут блокировать соседние тикеты и быть ими заблокированы, так что порядок работы выпадает из графа зависимостей, а не из линейного плана.
Определяющее ограничение — размер: одна сессия. Тикет должен быть завершаем, прежде чем сессия выскользнет из умной зоны, и это ограничение проверяемо. Если сессии на ваших тикетах регулярно деградируют до конца работы, тикеты слишком большие: режьте. Если каждая сессия тратит большую часть контекста на подготовку и потом делает пять минут работы, они слишком маленькие: сливайте.
Хороший тикет написан для читателя без другого контекста. Цель, критерии приёмки и указатели контекста на нужные файлы и решения — достаточно, чтобы сессия начала работать, не выводя заново то, что знала прошлая.
Граф зависимостей ещё и открывает параллелизм. Независимые тикеты — листья графа — могут идти каждый в своей сессии одновременно. Это рабочий способ гонять несколько агентов сразу. В фабрике ПО отметка тикета как готового сама является триггером, который стартует его сессию.
Пример:
«С чего начать спецификацию миграции?»
«Посмотрите граф тикетов: смена схемы блокирует бэкфилл, бэкфилл блокирует переключение API. Возьмите лист и гоните на нём сессию.»
Компактизация¶
Compaction. Передача, сделанная в памяти: история прошлой сессии сворачивается, и сводка сеет свежую сессию. С потерями по замыслу: транскрипт — первичный источник, сводка — вторичный. Деталь меняется на запас места. Запускается вручную пользователем или автоматически через автокомпактизацию.
Механизм: контекстное окно конечно, и длинная сессия его заполняет — каждый результат инструмента, каждое чтение файла, каждый неверный ход остаётся в истории. Когда становится тяжело, harness просит модель свернуть сессию, выбрасывает исходную историю и сеет свежую сессию сводкой. Чего не попало в сводку, в контексте больше нет. Некоторые harness смягчают это: держат старый транскрипт на диске и оставляют в сводке указатель контекста на него. Вторичный источник ссылается на первичный, так что деталь, потерянную сводкой, можно вернуть, перечитав оригинал.
Сводку пишет модель, поэтому её можно промптить. «Сохрани решения по схеме» делает порождённый артефакт намереннее. Время тоже важно: компактизируйте на границе фазы, когда план уже устоялся, а не посреди задачи.
Сравните с очисткой, которая бросает всё и начинает с холода: компактизация пытается перенести существенное, очистка ставит на то, что существенное уже записано где-то лучше.
Пример:
«Контекст тяжелеет, а проход тестов ещё впереди.»
«Компактизируйте до старта. Запишите в промпт сводки, что должно выжить, чтобы новая сессия сохранила решения по схеме и сбросила исследование.»
Автокомпактизация¶
Autocompact. Компактизация, которую harness запускает сам, когда контекстное окно приближается к заполнению.
Harness следит, насколько полно окно. Когда оно пересекает порог — часто около 80 процентов, — он останавливается, просит модель свернуть сессию до текущего момента и сеет свежую сессию сводкой. Работа продолжается так, будто ничего не случилось.
Кроме того, что случилось. Компактизация с потерями, а автокомпактизация — с потерями в момент, который вы не выбирали. Ручная компактизация происходит на границе фазы, когда вы можете сказать модели, что сохранить. Автокомпактизация стреляет посреди задачи, когда бы ни сработал порог, — возможно, на середине рефакторинга, и сводка сама решает, какие из ваших решений стоило сохранить. Классический симптом: агент уверенно продолжает, но тихо забыл ограничение, которое вы установили час назад, и вы замечаете это, только когда его работа начинает этому противоречить.
Защита — не дать ей выстрелить. Следите за индикатором контекста и компактизируйте вручную на естественной границе или записывайте решения в документ плана или артефакт передачи на диске, где никакая сводка их не потеряет. Большинство harness также позволяют настроить буфер: сдвинуть порог раньше или позже или выключить автокомпактизацию совсем, чтобы вы сами решали, сколько запаса держать до срабатывания.
Пример:
«Оно как будто не помнит, что мы решили про схему раньше.»
«Между ходами сработала автокомпактизация: ранние решения свернули, и мы, видимо, что-то потеряли. Загрузите документ плана заново или в следующий раз компактизируйте вручную, чтобы контролировать, что сохранится.»
Память и направление¶
Шесть терминов о том, как агент помнит между сессиями и как не забивать окно.
Система памяти¶
Memory system. Система, которая пытается сделать агента имеющим состояние между сессиями. Во время сессии сохраняет информацию в среду и в начале будущих сессий загружает её обратно в контекстное окно, так что агент несёт непрерывность дальше, чем пользователь очищает сессию.
У системы памяти две половины. Путь записи: во время сессии агент записывает выученное — предпочтение, которое вы назвали, факт о проекте — как файлы в среде. Путь чтения: в начале сессии harness загружает эти файлы или их индекс обратно в контекстное окно. Многие harness поставляют свою систему памяти — /memory в Claude Code одна из них, — но её можно собрать и самим: каталог заметок плюс инструкция в AGENTS.md к нему обращаться.
Действуют те же обмены, что у любого всегда загружаемого содержимого. Воспоминания копятся, поэтому большинство систем грузят индекс в одну строку и оставляют тела за указателями контекста, а не вставляют всё целиком. И воспоминания — вторичные источники, так что они дрейфуют: факт, записанный в марте, загружается с той же уверенностью в июне, после того как проект ушёл дальше. Системе памяти нужна обрезка, как и AGENTS.md.
Пример:
«Мне снова и снова приходится говорить, что мы на Postgres, а не на MySQL.»
«Подключите систему памяти: на первом ходе пишите выученное в файловую систему, в начале сессии загружайте обратно. Сама модель без состояния; слой памяти подделывает непрерывность.»
AGENTS.md¶
AGENTS.md. Файл в среде, который harness загружает в контекстное окно в начале сессии. Постоянный бриф проекта агенту. Соглашение между разными harness; у некоторых есть и свой вариант (у Claude Code это CLAUDE.md).
Поскольку он грузится сам, это один из способов не повторяться между сессиями. Модель без состояния: поправка, данная в одной сессии, в следующей пропала, и вы снова говорите каждой свежей сессии, что проект на pnpm, что тесты запускаются с определённым флагом, что каталог сгенерирован и его нельзя трогать. Когда вы поправили агента в одном и том же дважды, эта поправка — кандидат в строку AGENTS.md.
Подходящее содержимое — всё, чего агент не выведет из кода: команды сборки и тестов, соглашения, которые кодовая база не делает очевидными, жёсткие ограничения («никогда не правь сгенерированный клиент»). Коротко и декларативно: это бриф, а не документация.
Обмен в том, что всё в нём загружено всегда. Инструкции копятся, большинство из них нерелевантны любой данной задаче, и длинный AGENTS.md и стоит токенов, и разбавляет сам себя: чем больше инструкций в контексте, тем менее надёжно модель следует любой одной.
Избегать: класть в AGENTS.md то, что должно раскрываться постепенно. Всё в нём платит цену токенами на каждом ходе, в каждой сессии, нужна эта сессия этому или нет. Гайд по стилю может стоять за навыком или указателем контекста. В AGENTS.md держите строки, которые применимы везде.
Пример:
«Почему каждая сессия начинается с уже сожжённых 4 тысяч токенов?»
«Проверьте AGENTS.md: кто-то вставил туда весь гайд по стилю вместо того, чтобы спрятать его за навыком.»
Прогрессивное раскрытие¶
Progressive disclosure. Загрузка только того контекста, который агенту нужен прямо сейчас, с указателями контекста на остальное. Заимствовано из дизайна интерфейсов, где это значит показывать пользователю только элементы, нужные текущей задаче, а остальное прятать за кликом.
Приём существует, потому что контекст стоит дважды. Каждый токен, загруженный заранее, тарифицируется как входные токены на каждом ходе, и каждый токен тратит бюджет внимания, нужен он агенту или нет. AGENTS.md, набитый полным гайдом по стилю, ранбуком деплоя и соглашениями базы, делает агента хуже во всём этом сразу: инструкции, важные для текущей задачи, разбавлены теми, что не важны. Признак — агент, который игнорирует правила, про которые вы знаете, что они в его контексте: они там, но погребены.
Прогрессивное раскрытие переворачивает это. Держите всегда загружаемый слой маленьким: предложение на тему и указатель, где живёт деталь. Агент читает гайд по стилю, когда пишет компонент, ранбук деплоя — когда деплоит, и ни то ни другое — когда чинит тест. Навыки — паттерн, встроенный в harness: короткое описание загружено каждую сессию, полные инструкции — только когда сработали.
Пример:
«Стоит ли вывалить весь гайд по стилю в AGENTS.md?»
«Нет, прогрессивное раскрытие. Сошлитесь на гайд как на навык, который агент грузит, когда ему действительно нужно писать компонент. AGENTS.md платит цену токенами на каждом ходе.»
Указатель контекста¶
Context pointer. Упоминание в одном документе, которое указывает на другой, чтобы агент втягивал его в контекстное окно только когда задача этого требует. Единица, из которой собрано прогрессивное раскрытие.
Указатель вместо вставки содержимого нужен из-за цены. Указатель — одна строка в контекстном окне. Документ за ним может быть на тысячи токенов, но эти токены ничего не стоят, пока агент по указателю не пойдёт. Вставьте ранбук на 2 000 токенов в AGENTS.md, и каждая сессия за него платит; замените на «процесс деплоя: см. internal/deploy.md», и грузят его только сессии, которые деплоят. Агент следует указателю вызовом инструмента, когда задача совпадает.
Чтобы указатель работал, нужны две части: стабильный путь и достаточно описания, чтобы агент понял, когда по нему стоит идти. Голый путь — указатель, следовать которому у агента нет причины; «см. internal/deploy.md» без намёка, что внутри, пропускает сессия, которой это было нужно. Пишите строку так, чтобы она совпадала с тем, как задачи являются: «релиз, деплой или откат — сначала прочитай internal/deploy.md».
Указатели повсюду, стоит присмотреться: строки в AGENTS.md, описания навыков (harness грузит описание, тело навыка ждёт за ним), имена файлов в листинге каталога, ссылки между документами.
Указатель может также привязать вторичный источник обратно к первичному, из которого тот выведен: сводка компактизации называет исходный транскрипт, документ называет исходный файл, который описывает. Потери вторичного источника становятся восстановимыми: когда сводки оказывается мало, агент идёт по указателю и читает оригинал, а не работает из того, что сводка сохранила.
Избегать: «ссылка» — слишком сухо и не передаёт, что следование втягивает ещё контекст. «Портал» — слишком цветисто.
Пример:
«AGENTS.md раздувается.»
«Большая часть должна быть указателями контекста, а не содержимым. Всегда включённые правила оставьте в тексте; ранбук деплоя и гайд по стилю превратите в навыки и оставьте вместо них указатель.»
Навык¶
Skill. Обучаемая возможность, собранная как единица: инструкции и ресурсы, чтобы хорошо делать одну задачу. Лежит в среде, пока указатель контекста не втянет её в контекстное окно под текущую задачу. Единица прогрессивного раскрытия в harness.
Навыки — открытый стандарт, описанный на agentskills.io. Его изначально разработала Anthropic, и с тех пор его приняли большинство крупных harness, так что навык, написанный один раз, работает в них всех. Формат — папка, в которой:
- файл
SKILL.md: метаданные (как минимум имя и описание) плюс сами инструкции; - по желанию скрипты, которые агент может запустить;
- по желанию шаблоны и справочный материал, на которые указывают инструкции.
В контексте по умолчанию сидят только имя и описание. Когда задача агента совпадает, он грузит остальное. До тех пор навык почти не занимает места: предложение-два токенов, какого бы размера ни были полные инструкции.
Это отличает навыки от AGENTS.md, который грузится в каждую сессию независимо от задачи. Навык читается, когда возникает определённый вид работы — релиз, каркас нового сервиса, написание миграции, — и игнорируется в остальное время.
Избегать: «инструмент». Инструмент — то, что агент вызывает; навык — инструкции, которые он читает.
Пример:
«Куда положить ранбук деплоя?»
«Как навык: агент грузит его, только когда задача связана с деплоем. В AGENTS.md он жёг бы токены на каждом ходе ради того, чем мы пользуемся раз в неделю.»
Субагент¶
Subagent. Агент, которого порождает другой агент через вызов инструмента. Работает в своей сессии со своим контекстным окном и возвращает один результат инструмента. Отличается от передачи: родитель специально ждёт возврата, у передачи обратного пути нет. Не может порождать дальнейших субагентов — дерево глубиной в один уровень. Субагенты существуют, чтобы изолировать контекст, а не чтобы собирать иерархии.
Смысл — держать шумную работу вне контекста родителя. Широкий поиск или долгое чтение файлов порождает страницы результатов инструментов, большинство из которых важны лишь столько, сколько нужно, чтобы найти ответ. Если гонять это внутри родителя, всё останется в его контексте до конца сессии. Если внутри субагента, шум заполняет одноразовое окно, и в контекст родителя ложится только финальный отчёт. Отчёт — вторичный источник: родитель получает рассказ субагента о найденном, а не сырые результаты, так что всё, что отчёт опустил, родителю невидимо.
Субагенты ещё и идут параллельно: родитель может выпустить несколько сразу по независимым кускам работы.
Пример:
«Результаты grep раздувают мой контекст.»
«Породите субагента на поиск: он сожжёт своё контекстное окно на шуме и вернёт два пути файлов, которые вам на самом деле нужны.»
Паттерны работы¶
Тринадцать терминов о том, как люди и агенты делят работу.
Человек в контуре¶
Human-in-the-loop. Рабочий паттерн, в котором один или несколько людей работают в паре с агентом во время сессии: ревьюят, перенаправляют или сотрудничают в реальном времени. Человек присутствует и включён, а не только накладывает ограничения на отдельные действия.
Контраст — с работой AFK, где агент идёт без присмотра, а вы судите результат потом. Человек в контуре значит ловить проблемы, пока они ещё дёшевы: вы видите, что агент тянется не к тому файлу, неверно читает требование или сворачивает в тупик, и перенаправляете одной фразой, а не обнаруживаете двадцать минут уверенной работы, построенной на этой ошибке. Агенты ненадёжно знают, когда сбились с пути; оставленные одни, они склонны давить вперёд, а не остановиться и спросить.
Какой паттерн подходит, зависит от работы. Хорошо заданные, низкорисковые, легко проверяемые задачи подходят AFK. Задачи неоднозначные, необратимые или такие, где готовый результат трудно ревьюить — миграция схемы, хитрое проектное решение, всё, что касается прода, — подходят тому, чтобы остаться в контуре. Суждение по сути такое: насколько дорог неверный ход и как поздно вы его поймаете.
Часть работы в контуре по природе, потому что ваши реакции — вход. Гриллинг работает, только если вы там, чтобы отвечать на вопросы; прототипирование работает, только если вы там, чтобы реагировать на артефакт.
Оставаться в контуре стоит вашего внимания, а это дефицитный ресурс. Часть того, чтобы становиться лучше с агентами, — безопасно выносить больше работы из контура: планами, автоматическими проверками и человеческим ревью в конце вместо присмотра на всём протяжении. Фабрика ПО идёт дальше и стартует сессии от триггеров, так что даже запуск работы не требует вас.
Пример:
«Гонять это AFK ночью?»
«Нет, миграция схемы — держите человека в контуре. Хочу видеть каждый шаг и вмешаться, если оно выберет не ту колонку для бэкфилла.»
AFK¶
AFK. Away from keyboard, «не у клавиатуры». Рабочий паттерн, в котором пользователь стартует сессию и оставляет агента работать без присмотра. Множитель пропускной способности ИИ-кодинга: много сессий AFK могут идти параллельно, пока вы спите, едите или делаете другое. Чтобы это было безопасно, обычно нужны разрешающий режим разрешений и песочница.
Когда вас нет, агент иначе обходится с неоднозначностью. Пока вы смотрите, неоднозначное решение всплывает вопросом, и вы отвечаете; когда вы ушли, агент выбирает умолчание и идёт дальше, и каждое следующее решение строится на этой догадке. Характерный провал — вернуться к часам законченной уверенной работы, построенной на неверном выборе первых десяти минут. Работа не небрежная: она связная, просто связная про неверную вещь.
Раз вы не можете дать вход во время прогона, дайте его до и после. До: снимите неоднозначность заранее — сессией гриллинга, письменной спецификацией, — чтобы агенту осталось меньше дыр, которые он заполнит сам. Во время: автоматические проверки и автоматическое ревью стоят вместо внимания, которого вы не даёте, и быстро падают на том, что ловится механически. После: прогон кончается чем-то, что можно ревьюить, — пул-реквестом, а не уже слитыми изменениями. AFK не убирает человеческое ревью; оно откладывает всё ревью на конец, и поэтому то, что приходит в конец, должно стоить ревью. Поэтому же AX важнее всего в прогонах AFK: когда никто не смотрит, среда — единственная опора агента.
Избегать: «фоновый агент». Центр на машине («работает в фоне»), а не на человеческом паттерне («пользователь ушёл»). AFK называет факт, который важен: пользователь не смотрит.
Пример:
«Гоняю это AFK: три агента в песочнице на рефакторинг, пул-реквесты смотрю утром.»
«Да. Файловая система только на чтение, без сети.»
Автоматическая проверка¶
Automated check. Детерминированная верификация, которая выполняется в среде: тесты, проверка типов, линтеры, сборка, хуки перед коммитом. Прошёл или нет, без суждения. Сигнал, по которому агент может поправить себя, никого не привлекая. Хлопучий тест — сломанная проверка, а не «не проверка»: автоматические проверки детерминированы по замыслу.
Самопоправка работает как цикл. Агент делает изменение, запускает проверку как вызов инструмента, и вывод падения ложится в его контекстное окно: ошибка типа с файлом и строкой, упавшее утверждение с ожидаемым и фактическим. Этого достаточно, чтобы агент починил проблему и запустил проверку снова, по кругу, пока не пройдёт, без человека в контуре. Детерминизм делает цикл заслуживающим доверия: один и тот же код всегда даёт один вердикт, так что «прошло» что-то значит. Хлопучая проверка это отравляет: агент «чинит» код, который был в порядке, или ретраит мимо настоящей поломки.
Поэтому хорошие проверки — большая часть AX кодовой базы. Агент в репозитории со строгими типами, быстрым набором тестов и линтером ловит большую часть своих ошибок, прежде чем вы их увидите; агент в репозитории, где этого нет, отгружает то, что произвёл. Разница важнее всего в прогонах AFK, где проверки — единственная верификация во время прогона. Но проверка ловит только то, что утверждает: зелёные проверки значат, что заявленные свойства держатся, а не что код верен. Дыры формы суждения — то, для чего нужны автоматическое ревью и человеческое ревью.
Избегать: «петля обратной связи» и «обратное давление» — оба сваливают проверки в одну кучу с ревью. Избегать: «тест». Тесты — автоматические проверки, но не все автоматические проверки — тесты.
Пример:
«Агент всё отгружает сломанный код в прогонах AFK.»
«Какие автоматические проверки подключены в песочнице?»
«Только юнит-тесты.»
«Добавьте проверку типов и линтер: он поправит себя по ним ещё до того, как пул-реквест появится.»
Автоматическое ревью¶
Automated review. Агент, который ревьюит работу другого агента, часто с другой моделью или другим системным промптом. Недетерминировано: он формирует суждение. Может идти где угодно: до слияния на пул-реквесте, задним числом по истории коммитов, посреди сессии как субагент. LLM-как-судья в CI — автоматическое ревью, а не автоматическая проверка. Категорию решает, что делает утверждение, а не где оно выполняется.
Разделение с рабочим агентом — то, что заставляет это работать. Просьба к агенту, который написал код, отревьюить собственную работу даёт очень мало: сессия, которая породила баг, содержит и рассуждение, которое его породило, и агент читает собственные выводы обратно как подтверждение. Ревьюер со свежим контекстным окном этой привязанности лишён: он видит diff так, как увидел бы посторонний, а ревью на этом и держится. Другая модель или системный промпт специально для ревью обостряет это дальше: другие слепые пятна и промпт, суженный до того, что вам реально важно (безопасность, контракты API, производительность), а не расплывчатое «поищи проблемы».
Оно встаёт между другими слоями ревью. Автоматические проверки детерминированы и ловят то, что можно утверждать механически; человеческое ревью дорого и масштабируется хуже всего. Автоматическое ревью посередине: ловит проблемы формы суждения — вводящее в заблуждение имя функции, пропущенный краевой случай — по машинной цене. Поскольку оно недетерминировано, может пропустить вещи и поднять не-проблемы. Относитесь к нему как к фильтру, который поднимает пол, прежде чем посмотрит человек, а не как к ограничению, которое заменяет человека.
Избегать: «ИИ-ревью» и «ревью агентом» — слишком расплывчато, чтобы отличить от самого рабочего агента.
Пример:
«С прогонов AFK приходит слишком много плохих пул-реквестов.»
«Добавьте шаг автоматического ревью до слияния: другая модель, отдельный системный промпт, суженный до безопасности и изменений контрактов.»
Человеческое ревью¶
Human review. Пользователь читает код, который произвёл агент, и формирует о нём суждение. Чтение diff или изменённых файлов считается; чтение описания агента того, что он сделал, не считается: рассказ — не артефакт. Описание — вторичный источник, написанный стороной, которую ревьюят; diff — первичный источник, и ревью значит его читать.
Агенты поднимают объём производимого кода, так что ревью становится узким местом. Полезная идея — складывать разные стратегии ревью слоями. Автоматические проверки ловят механические отказы, автоматическое ревью ловит те, что можно описать, а человеческое ревью оставлено для того, что можете судить только вы: то ли это изменение, подходит ли подход кодовой базе, должно ли это существовать вообще.
Ревью дешевле раньше. Прочитать план до начала работы или небольшой diff на середине — минуты; раскапывать готовую ветку после прогона AFK — дольше. Где поставить точку ревью — решение про человека в контуре, а не запоздалая мысль.
Избегать: одного «код-ревью». Оно двусмысленно между человеческим и автоматическим.
Пример:
«Я отревьюил выход AFK по-человечески.»
«Ты читал diff или только сводку?»
«Diff. Сводка говорила, что удалён мёртвый код. Оказалось, функцию вызывали из сгенерированного файла.»
Вайб-кодинг¶
Vibe coding. Рабочий паттерн, в котором пользователь принимает код агента без человеческого ревью. Diff считается непрозрачным: важно, ведёт ли себя программа, а не что внутри. Автоматическое ревью и автоматические проверки при этом могут идти; вайб-кодинг о них молчит.
Термин от Андрея Карпатого, который ввёл его в начале 2025 года: вы «полностью отдаётесь вайбу» и «забываете, что код вообще существует» — описываете, чего хотите, принимаете, что вернулось, и судите, запустив.
Вайб-кодинг меняет осмотр на скорость. Чтение diff обычно самый медленный шаг в работе, которую ведёт агент, так что отказ от него снимает главное узкое место. Для кода, чьи отказы дёшевы — прототипы, разовые скрипты, внутренние инструменты, — это разумный обмен. Риск растёт вместе со сроком жизни кода и ставками.
Цена приходит позже. Изменения в вайбе копятся в кодовую базу, которую никто не читал, а проверялось только поведение. Поэтому всё, чего поведение не показывает — секрет, записанный в логи, пропущенный краевой случай, тихо неверная обработка данных, — уезжает незамеченным. Первый раз, когда кто-то отлаживает систему, — первый раз, когда кто-то читает код. Когда человеческого ревью нет, какая бы автоматическая верификация ни осталась — тесты, типы, автоматическое ревью, — это единственные ограничения, через которые проходит код. Та же позиция, применённая к целой кодовой базе или её части, чьи изменения приходят из фабрики ПО, — это тёмная фабрика.
Избегать: «вайб-кодинг» как синоним «низкокачественного ИИ-кодинга». Термин называет позицию ревью, а не получившийся код.
Пример:
«Ты читал, что оно поменяло в потоке авторизации?»
«Завайбкодил: логин всё ещё работает, это всё, что я проверил.»
«Прочитай diff до пуша. Вайб на авторизации — так секреты утекают в логи.»
Концепция дизайна¶
Design concept. Общее понимание того, что строится, удерживаемое вместе пользователем и агентом, но отдельное от любого актива. Термин Брукса (The Design of Design): разговор, артефакты передачи и код — активы, которые пытаются схватить концепцию дизайна или к ней прийти, но ни один из них ею не является. Качество концепции дизайна ощущается через качество разговора, который её построил.
Термин называет зазор за знакомым раздражением: агент пишет ровно то, что вы просили, и это всё равно неверно. Обычная причина — вы сами ещё не до конца поняли, чего хотите. Концепция дизайна не была закончена в вашей голове: промпт схватил части, которые вы проработали, и молчал о тех, которые нет. Агент заполнил эти молчания своими допущениями, потому что выравниваться было не с чем. Ничего не сломалось. Общей концепции дизайна не было, потому что ещё не было целой, которой можно поделиться.
Общую концепцию дизайна узнаёшь так же, как с коллегой: другая сторона начинает отвечать на вопросы, которые вы ещё не задали, так, как ответили бы вы. До тех пор работа — разговор, гриллинг — его намеренная версия, — а слишком ранняя спецификация просто фиксирует рассогласование в более долговечном активе. Концепция дизайна ещё и двигается, пока вы учитесь; активы отстают, поэтому спецификация, верная пониманию прошлой недели, всё ещё может сбить сессию этой.
Пример:
«Оно пишет ровно то, что я просил, и это всё равно неверно.»
«У вас ещё нет общей концепции дизайна: оно заполняет дыры допущениями. Продолжайте говорить, пока отмена, возвраты и частичное исполнение не сойдутся между вами, и только потом давайте ему писать спецификацию.»
Гриллинг¶
Grilling. Приём, которым вместе с агентом вырабатывают концепцию дизайна: агент сократически опрашивает пользователя, по одному решению за раз, и на каждое предлагает рекомендуемый ответ. Замедляет рывок к готовому плану: никакой артефакт передачи не пишется, пока концепция не стабилизируется.
Приём существует, потому что агенты заполняют дыры молча. Попросите написать спецификацию из промпта в две строки, и агент не остановится на решениях, которые вы не приняли: он выберет умолчания и впишет их. Результат выглядит законченным, а догадки неотличимы от выборов, так что вы обнаруживаете их поздно: на ревью или когда построенная фича обрабатывает краевой случай способом, который вы никогда не выбирали. Гриллинг переворачивает это: вместо угадывания агент обязан спросить.
Это приём человека в контуре: ваши ответы — вход. Когда на вопрос нельзя ответить в разговоре — нужно увидеть вещь, — переключайтесь на прототипирование.
Пример:
«Оно сразу пошло писать спецификацию и ошиблось в логике отмены.»
«Сначала гриллинг: пусть спросит про частичные отмены, возвраты и сроки, прежде чем что-то фиксировать в документе. Дешевле снять это в разговоре, чем в коде.»
Прототипирование¶
Prototyping. Агент строит быструю грубую версию чего-то, когда разговора слишком мало по точности и нужен настоящий артефакт, о котором можно говорить.
Гриллинг снимает проектные решения в разговоре. Разговор дёшев, но низкоточен: на некоторые вопросы нельзя ответить словами — как ощущается взаимодействие, эргономична ли форма API в настоящем вызывающем коде, работает ли раскладка на настоящих объёмах данных. Опрос упирается в вопрос, и честный ответ — «не знаю, надо увидеть». Дальше обсуждение ходит по кругу. Вместо этого пусть агент построит вещь, посмотрите на неё и вернитесь в разговор с ответом.
Агенты снижают цену построения, и поэтому это практично. Грубая версия, на макет которой раньше уходил день, теперь занимает минуты, так что это стоит делать регулярно. Это приём человека в контуре: прототип существует, чтобы вы на него реагировали.
Обычно одним взглядом не заканчивают. Итерируйте на прототипе: реакция, просьба об изменении, снова реакция. Каждый круг снимает ещё одно решение на настоящем артефакте, с более высокой точностью, чем позволяет разговор.
Прототип не обязан быть целиком на скорую руку. Куски, которые вы на самом деле оцениваете, можно строить в качестве продакшена, так что когда решение встанет, компонент или API, на который вы реагировали, можно перенести в настоящую кодовую базу. Поэтому прототипирование — существенный материал, на который может ссылаться спецификация.
Пример:
«Мы полчаса спорим, мастер должен быть одной страницей или тремя шагами.»
«Слова это не решат. Пусть агент прототипирует оба. Прокликаем и поймём за пять минут.»
DX¶
DX. Developer experience, опыт разработчика: насколько кодовая база и её инструментарий облегчают людям делать хорошую работу. Хороший DX — быстрая обратная связь, ясные сообщения об ошибках, документация, которая отвечает на вопрос, который у вас на самом деле есть, и установка, которая срабатывает с первой попытки. Термин намного старше ИИ-кодинга; в этом словаре он в основном как контраст к AX.
DX — взаимодействие человека и кодовой базы, и ничего больше. Главное различие двух аудиторий в том, что люди имеют состояние, а агенты без состояния. Человек выучивает кодовую базу один раз и несёт это знание в каждый следующий день, поэтому плохой DX переживаем: медленный CI обходят, копя пуши; отсутствующую документацию — одним вопросом в Slack; путаную структуру — запоминая, где что лежит. Обходы копятся, и команда оказывается продуктивной в кодовой базе, которая с ней борется.
Агенты встречают ту же кодовую базу без этого накопления. Без состояния между сессиями, агент заново учит кодовую базу каждый раз: ему помогают быстрый набор тестов и ясные сообщения об ошибках, но всё, что он понял вчера, пропало, если не было записано в среду, которую агент воспринимает только через результаты инструментов. Этот зазор и называет AX: части DX, которые выживают, когда разработчик — агент, плюс заботы, которых у людей нет, например держать контекстное окно свободным.
Перекрытие значит, что вложения в DX часто улучшают AX даром: строгие типы, быстрые тесты и предсказуемая структура помогают обоим. Расхождение значит, что не всегда: красивый документ онбординга помогает человеку неделю и агенту никак, если до него нельзя дотянуться из AGENTS.md.
Пример:
«Наш DX в порядке: новички продуктивны за неделю.»
«Продуктивны, потому что кто-то сидит с ними эту неделю. Агенту этой недели не дают; AX проверяйте отдельно.»
AX¶
AX. Agent experience, опыт агента: насколько среда устроена так, чтобы агент хорошо работал в кодовой базе. Обращённый к агенту аналог DX. Когда один и тот же агент хорошо работает в одном репозитории и плохо в другом — та же модель, тот же harness, — разница обычно в AX. Инстинкт — винить модель или переписывать промпт; лекарство чаще в репозитории.
У хорошего AX три главных измерения:
| Измерение | Как выглядит хороший AX |
|---|---|
| Автоматические проверки | Быстрые детерминированные автоматические проверки — типы, тесты, линтеры, — по которым агент поправляется сам, без человека |
| Архитектура | Кодовая база, по которой агент ориентируется, не читая всё: предсказуемая структура, много поведения за маленькими интерфейсами, имена, которые говорят, что вещи делают |
| Свободный контекст | AGENTS.md, навыки и инструменты держатся тощими, так что большая часть контекстного окна свободна под задачу, и агент остаётся в умной зоне, а не тонет |
AX и DX пересекаются — хорошие проверки и чистая архитектура помогают обеим аудиториям, — но расходятся. Люди терпят племенное знание, медленный CI и «спроси Сару про модуль биллинга»; агенты не могут. Агентам не помогают подсказки IDE и красивые дашборды; им нужны отказы текстом в результате инструмента. У кодовой базы может быть хороший DX и плохой AX.
Избегать: считать AX синонимом DX. Аудиториям нужны разные вложения.
Пример:
«Агент пишет отличный код в репозитории API и мусор во фронтенде.»
«В репозитории API строгие типы и быстрый набор тестов; во фронтенде нет ни того ни другого и сорок всегда загруженных навыков. Это зазор AX, а не проблема модели.»
Фабрика ПО¶
Software factory. Система работы, в которой сессии агента стартуют триггеры — созданный issue, расписание, падение CI, конец другой сессии, — а не человек. Поэтому больше работы идёт AFK, а человеческое внимание тратится на оставшиеся решения человека в контуре.
Без фабрики каждая сессия начинается, потому что её кто-то начал. Даже полностью AFK-работа ждёт, пока человек откроет сессию, укажет её на тикет и запустит. Команды хотят отгружать больше, чем это позволяет. Фабрика убирает человека из старта сессий и не обязательно из чего-либо ещё.
Частые триггеры и сессии, которые они стартуют:
| Триггер | Какую сессию стартует | Пример |
|---|---|---|
| Создан или помечен issue | Исследование, фикс бага, реализация | Issue с меткой ready-for-agent получает сессию, которая открывает пул-реквест |
| Расписание (cron) | Повторяющееся обслуживание | Одно правило линтера чинится за ночь |
| Падение CI или алерт мониторинга | Диагноз, попытка фикса | Падающая сборка на main получает сессию, которая находит ломающий коммит и предлагает фикс |
| Конец другой сессии | Последующая работа | Пул-реквест, открытый одним агентом, запускает автоматическое ревью, чьи комментарии запускают сессию доработки |
Фабрике не обязательно покрывать весь процесс разработки. Одна cron-задача, которая гоняет один вид сессии и открывает один ревьюимый пул-реквест, — уже фабрика. Начинать с малого полезно: узкая петля даёт маленькие похожие пул-реквесты, и их ревью показывает, насколько петле можно доверять, прежде чем её расширять.
Люди могут сидеть где угодно в фабрике: писать и метить issue, которые стартуют сессии, одобрять план до начала реализации, делать человеческое ревью до слияния. Какие из этих решений остаются человеческими — главный вопрос дизайна. Кодовая база или её часть, где никто из людей не ревьюит выход фабрики, — тёмная фабрика.
Пример:
«Кто починил все нарушения no-floating-promises?»
«Фабрика. Cron берёт одно правило линтера за ночь и открывает пул-реквест. Я только ревьюю его утром.»
Тёмная фабрика¶
Dark factory. Кодовая база или её часть, где код пишет фабрика ПО, и ни один человек его не читает. Человеческого ревью нет. Люди всё ещё могут писать issue, которые стартуют работу. Но код, который выходит, никто не читает. Имя от фабрик «без света» (lights-out), которые делают вещи без людей в цехе.
Тёмная фабрика — вайб-кодинг для области кода, а не для одного изменения. Когда вы вайб-кодите, вы выбираете не читать изменение, которое сами попросили. Но вы знаете, что изменение существует. В тёмной фабрике команда делает этот выбор один раз, для всей области. После этого никто не просит каждое изменение и не видит его. Изменения приходят со скоростью, с которой триггеры стартуют новую работу.
Проблема видна, когда что-то ломается. Вы не знаете, что изменилось, потому что изменения никто не читал. Приходится отлаживать код, которого никто в команде не читал. Причина может быть в любом из многих изменений, и каждое прошло проверки.
Автоматические проверки и автоматическое ревью — единственные ограничения. Если они проблему не находят, проблема уходит в код.
Избегать: называть кодовую базу «тёмной» только потому, что её фабрика работает, когда никто не смотрит. Если сессии агента идут AFK, а человек ревьюит их пул-реквесты, это фабрика ПО. Это не тёмная фабрика.
Пример:
«Кто поменял логику ретраев в сервисе биллинга? Никто в команде не помнит.»
«Сервис биллинга — тёмная фабрика. Агенты сливают все изменения, которые проходит CI. Это изменение никто не читал.»
Источник: AI Coding Dictionary, Мэтт Покок. Репозиторий: mattpocock/dictionary-of-ai-coding.