Context engineering

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

Context engineering отвечает не за длинный prompt, а за отбор: что агенту нужно знать именно для этой задачи, чего он видеть не должен и какие источники считаются авторитетными.

Что входит в слой контекста

Практичный context layer обычно состоит из нескольких типов документов.

Компонент	Для чего нужен
AGENTS.md	Правила работы в репозитории, команды проверки, стиль изменений.
Product docs	Роли пользователей, цели продукта, доменные ограничения.
Architecture docs	Компоненты, boundaries, data flow, важные решения.
Task notes	Локальные уточнения конкретной задачи.
Tool docs	Как запускать local scripts, test runners, deploy tools.
Memory	Стабильные решения, которые не нужно переоткрывать каждый run.

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

Static prefix и trajectory

В agent runtime полезно разделять context на две части.

Часть	Что туда попадает	Как с этим работать
Static prefix	System/developer instructions, tool definitions, стабильные project rules.	Держать стабильным, versioned, коротким и редко менять.
Trajectory	Task messages, agent decisions, tool calls, tool results, checks, retries.	Append-only логировать, сжимать или архивировать по правилам.

Это не только вопрос чистоты. Если каждый run меняет начало prompt — например, вставляет текущий timestamp в system prompt, — многие model/runtime caches становятся бесполезными, latency и cost растут. Динамическое состояние лучше добавлять ближе к концу context как отдельный state block, а не переписывать стабильный prefix.

Для нашего harness это означает:

• AGENTS.md и tool definitions должны быть стабильным слоем;
• task contract и context pack добавляются на run;
• run events и tool results идут в trajectory;
• computed state вроде retry budget, current step, remaining tasks лучше хранить явно, а не заставлять модель каждый раз пересчитывать его из длинного лога.

Status bar для agent run

Для длинных задач полезен небольшой machine-maintained status block. Он не заменяет task contract и не является prose-summary всего run. Его задача — дать модели явное текущее состояние:

task_id: algi-02-clinician-report
step: verification
retry_budget_left: 1
allowed_write_paths: algi/, tests/
open_questions: none
last_check: unit tests passed

Такой block лучше обновлять кодом harness, а не просить model «помнить», сколько retries уже было и какие gates пройдены. Это особенно важно для loops: без явного state agent легко повторяет один и тот же tool call, теряет stop condition или объявляет задачу завершённой раньше времени.

Четыре операции

Записать. Вынести важные решения из чатов и устных договорённостей в docs, task notes и templates.

Выбрать. Для каждого run собрать только релевантные файлы и правила.

Сжать. Длинный документ превратить в decision-oriented summary: что решили, почему, какие constraints.

Изолировать. Не смешивать frontend, backend, mobile, DevOps, product и compliance context без необходимости.

Когда сжимать, а когда изолировать

Compression полезна, но это всегда потеря деталей. Не сжимайте всё подряд. Сначала решите, какой тип информации перед вами:

Информация	Что делать
Architecture decisions, constraints, non-goals	Сохранять явно и почти не сжимать.
Modified files, verification status, rollback notes	Сохранять точно, потому что это нужно reviewer'у и следующему run.
Большие tool outputs	Хранить raw artifact отдельно, в context давать summary + ссылку/путь.
Поисковый шум, навигация, повторяющиеся snippets	Удалять или сжимать агрессивно.
Исследовательская работа sub-agent	Возвращать в main context только conclusion + evidence pointers.

Иногда лучше не сжимать, а изолировать. Если задача «найди в codebase место, где считается clinician summary» генерирует десятки файлов контекста, main agent не обязан видеть весь поиск. Отдайте поиск отдельному sub-agent или deterministic script, а в основной run верните короткий результат: найденные файлы, confidence, что проверено, где остались сомнения.

Context pack для одного run

Для agent-ready задачи соберите compact pack:

• task contract;
• релевантные docs;
• файлы, которые можно менять;
• read-only references;
• domain/security constraints;
• команды проверки;
• известные ловушки;
• правила escalation.

Pack должен быть коротким настолько, чтобы reviewer мог прочитать его перед diff.

Пример из lab-цепочки

Для задачи algi-02-clinician-report достаточно такого context pack:

# Context Pack: ALGI clinician report slice

## Задача
examples/harness-labs/tasks/algi-02-clinician-report.json

## Релевантные файлы
- `specs/pain-diary.bdd.md` — source of truth: сценарий privacy-safe summary
- `AGENTS.md` — правила: без medical claims, stdlib only
- `algi/domain.py` — зона изменения: сюда добавляется clinician_summary
- `tests/test_domain.py` — read-only reference: существующее поведение не ломать

## Доменные ограничения
- В summary нет email, телефонов и полных имён пациентов.
- Формулировки не делают diagnosis/treatment claims.
- Обязателен disclaimer «not medical advice».

## Команды
- Test: `python3 -m unittest discover -s tests`

## Ловушка
- Не менять validate_pain_entry: privacy-логика живёт в summary, а не в валидации.

## Escalation
- Любое ослабление валидации или экспорт patient data -> blocked + human review.

Здесь нет истории проекта, несвязанных документов, секретов и «на всякий случай» приложенных материалов. Каждый пункт отвечает на вопрос конкретного run.

Что сделать руками

Соберите context pack для одной реальной задачи по шаблону. Потом удалите из него всё, без чего агент всё равно сможет выполнить задачу корректно. Это упражнение обычно полезнее, чем добавление ещё одного документа.

На что не соглашаться

• Один глобальный prompt на все типы задач.
• Дублирование устаревших инструкций в нескольких местах.
• Отсутствие приоритета между system, repo, task и user instructions.
• Смешивание product goals, coding style и operational secrets.
• AGENTS.md, который никто не обновляет после изменения процесса.