Agent Instruction Surfaces

Четыре вопроса до выбора файла

1. Когда это знание нужно? Всегда, при работе с определёнными путями, только в процедуре или только в побочной задаче.
2. Что должно пережить compaction? Постоянная норма, повторно загружаемая процедура или только итог изолированного исследования.
3. Насколько обязательно соблюдение? Совет модели, маршрутизация контекста или детерминированный запрет.
4. Кто должен видеть промежуточную работу? Основная сессия либо отдельный контекст, возвращающий только результат.

Матрица поверхностей

Названия реализаций различаются между harness, но роли устойчивы:

Матрица описывает механику Claude Code на сентябрь 2026 года, поэтому конкретное поведение загрузки помечено volatile. Общий принцип не зависит от продукта: чем уже область применимости, тем позже должно раскрываться знание (Context Layers).

Выбор по типу требования

• Факт, который нужен почти в каждой задаче, — в корневую карту.
• Ограничение, связанное с путём или типом файла, — в path-scoped rule.
• Последовательная процедура с человеческим управлением — в skill.
• Побочная работа, промежуточные результаты которой загрязнят основную сессию, — в subagent.
• «Всегда сделать X» или «никогда не делать Y», если нарушение реально опасно, — в детерминированный hook/permission, а не в прозу.
• Если проблему можно убрать стандартной структурой проекта, предпочтительнее Convention Over Instruction.

Особенно важно различать skill и subagent. Skill сохраняет процедуру в основном потоке, где её можно направлять. Subagent покупает изоляцию: его инструментальные следы не входят в родительский контекст, возвращается только ограниченный результат. Вопрос выбора звучит так: понадобится ли основной сессии сам промежуточный вывод или только заключение?

Окупаемость subagent — не номер шага

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

Отсюда проверяемые условия:

• подзадача самодостаточна и имеет собственный критерий завершения;
• родителю нужен итог, а не повторное чтение найденных файлов и логов;
• итоговая сводка заметно меньше скрытой траектории и содержит ссылки на evidence;
• права и модель исполнителя уже, чем у родителя, если задача это допускает;
• в общем бюджете учитываются токены обоих окон, а не только очищенный контекст оркестратора.

Если планирование, реализация и тестирование постоянно используют одни и те же детали, делегирование создаёт повторный retrieval и пересказ. Тогда основная сессия дешевле и надёжнее, даже если у неё уже было несколько tool calls (Context Compaction, Bounded Tool Output).

Авторитет не равен надёжности

Высокое место в prompt hierarchy повышает вероятность следования, но не превращает текст в границу безопасности. Запрет в system prompt всё равно остаётся вероятностным и уязвимым к конфликтам, длинной сессии и prompt injection. Обязательная политика исполняется вне модели (Agent Harness).

У hooks тоже два класса. Команда, HTTP/MCP-вызов и проверка кода могут запускаться детерминированно; hook, который вызывает LLM для решения, детерминирован только по факту запуска, но не по вердикту. Смешивать эти гарантии нельзя.

Нерелевантность заразна внутри файла

Цена постоянно загруженного слоя обычно считается токенами: каждая строка платится во всех задачах. Есть вторая цена, и она неприятнее, потому что бьёт не по бюджету, а по исполнению.

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

Это объясняет, почему правило «в постоянно загруженном слое остаётся только то, цена отсутствия чего выше постоянной цены контекста» работает лучше, чем следует из одной экономии: оно убирает не расход, а помеху.

Третья поверхность: условная применимость внутри всегда загруженного файла

Матрица выше предлагает выбор между «загружено всегда» и «раскрывается по совпадению задачи». Между ними есть промежуточный приём: текст остаётся в постоянно загруженном файле, но размечается условием применимости — обёрткой вида «это важно, если выполняешь такую-то работу». Разметка даёт явный признак релевантности вместо общей оговорки и при этом не требует вызова инструмента, чтобы знание обнаружить.

Приём стоит между двумя другими по цене и по надёжности:

• основание, применимое почти ко всякой задаче — карта проекта, команды сборки, назначение репозитория, — остаётся без разметки;
• доменное руководство, нужное для определённого вида работы, размечается условием;
• знание, которое велико или нужно редко, по-прежнему выносится в отдельную процедуру.

Условие обязано быть узким. «Если пишешь или меняешь любой код» равносильно отсутствию условия: под него попадает всё, и признак релевантности перестаёт что-либо различать. Работающая формулировка называет конкретный вид работы — «добавляешь или меняешь импорты», «создаёшь новый файл», — и на одно правило приходится одно условие, а не общая шапка над списком из десяти.

Оговорка о статусе приёма: он опирается на предположение о том, как модель взвешивает разметку в промпте, и не измерен. Проверяется он тем же способом, что любое другое требование к поведению — прогоном при постановке, которая правилу не помогает (Instruction Compliance Measurement). Конкретная форма разметки к тому же привязана к обвязке и живёт ровно столько же, сколько её системный промпт.

Бюджет инструкций складывается по всем поверхностям сразу

У модели есть предел числа инструкций, которым она следует устойчиво. Называемая величина — порядка 150–200 для моделей фронтира, и обращаться с ней надо как с ориентиром: цифра приводится в пересказе поста со ссылкой на исследование, сама работа не опознана, и здесь она не проверялась.

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

Симптом превышения имеет узнаваемый вид: «волшебные слова». Это когда обнаруживается, что определённая формулировка вдруг заставляет поведение появиться, и её начинают беречь как находку. Правильное прочтение обратное — это не удачный приём, а сообщение об ошибке: правило уже записано, но до него не доходит очередь, и работать оно начинает только от усиления. Один разработчик такого промпта сообщает, что при его монолитной версии около половины пользователей получали от агента план без обязательных по инструкции уточняющих вопросов; величина заявлена автором и не проверялась.

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

Отсюда практическое следствие для выбора поверхности: дробление по стадиям — тоже способ удалить инструкцию, наравне с превращением её в проверку или в умолчание инструмента (Convention Over Instruction). И отсюда же — почему счётчик инструкций полезнее счётчика строк: сто строк примеров расходуют бюджет иначе, чем сто строк императивов.

Самая сильная поверхность — не файл, а код репозитория

Матрица выше перечисляет файлы. Практик, живущий в большой агентски написанной кодовой базе, называет поверхность, которая сильнее всех объявленных: «здесь так принято». Уже лежащий в репозитории код влияет на агента сильнее умений и корневого файла — и причина не в объёме, а в жанре: файл инструкций предписывает, а код показывает, и показанное выигрывает у предписанного.

Два следствия, и оба наблюдаемы.

Плохое компаундится. Каждая следующая сессия принимает существующий код за норму и воспроизводит его, поэтому дефект, внесённый однажды, становится местным стандартом без единого решения его таковым сделать. Это и есть механизм за уже измеренной деградацией: инструкция «пиши чисто» сдвигает начальный уровень, но следующая сессия читает не инструкцию, а результат предыдущей (Agent First Repository).

Вместо переиспользования копятся дубли. Форма отказа называется точно: «восемь чуть разных дублей одного функционала — девятому проще родиться, чем найтись существующему». Обратить на это внимание стоит потому, что выглядит это как проблема стиля, а является проблемой поиска: агент не отказался переиспользовать, он не нашёл. Файлом инструкций такое не чинится в принципе — чинится оснасткой навигации по коду и обязательным шагом «поискать существующее» до генерации (Agent Retrieval Policy).

Практический вывод для выбора поверхности: правило, противоречащее коду, проигрывает коду. Поэтому у дорогого правила есть более дешёвая альтернатива, чем усиление формулировки, — привести в порядок тот участок кода, на который агент смотрит как на образец (Convention Over Instruction).

Гигиена поверхности

• у постоянно загруженного файла есть владелец и регулярный review;
• считается не только объём слоя, но и число императивов в нём — бюджет общий на все поверхности;
• устаревшая компенсация ограничения модели удаляется после повторной проверки на новом поколении;
• процедура выносится из корневого файла, а не дублируется;
• требования безопасности имеют машинное принуждение;
• trigger skills проверяется отдельно от качества самой процедуры, и проверяется замером, а не предположением (Instruction Compliance Measurement);
• после compaction проверяется, какие поверхности harness загружает заново, а какие теряет.

Фиксированный предел вроде «не больше 200 строк» — эвристика конкретного продукта. Инвариант другой: в постоянно загруженном слое остаётся только знание, цена отсутствия которого выше постоянной цены контекста.

Связано с

• Agent First Repository — корневой файл как карта, а не энциклопедия
• Agent Harness — мягкий и жёсткий контуры исполнения
• Context Layers — когда разные слои попадают в prompt
• Convention Over Instruction — как вообще удалить инструкцию
• Tool Catalog — описание инструмента как ещё одна поверхность управления поведением
• Instruction Compliance Measurement — как проверить, что выбранная поверхность действительно принуждает