Неделя 3. Контекст-инжиниринг и специализация ролей

🧭 Где мы: LLM → [Context / State] → Tools → Runtime / Orchestration → Policy / Permissions → Evaluation / Observability.

Вспомни прошлую неделю

1. Назови три Core topology patterns из Week 2.
2. Какой паттерн использует твой Capstone и где происходит handoff?

Материал

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

Это только один из четырёх типичных отказов — и все четыре лечатся не «лучшим промптом», а тем, что модель получает на конкретном шаге:

Так выглядит context engineering — проектирование того, какая информация доступна модели на каждом конкретном шаге. Контекст — не только промпт. В него входят инструкции системы и разработчика, история диалога, состояние задачи, определения инструментов и результаты их вызовов, найденные документы, внешние данные, ограничения и разрешения.

Артефакт — сохранённый результат шага: подтверждение path:line, diff, вывод теста, решение человека. Дальше по тексту артефакты не пересказывают, а цитируют по ссылке, чтобы следующий этап мог открыть их и проверить.

Два важных уточнения:

• Права обеспечивает не текст. Инструкция «не меняй чужие файлы» в промпте — это пожелание. Разрешения реально применяет runtime и policy: инструмент просто не получит доступ.
• Контекст — это внимание, а не объём. Длинная история чата не заменяет управляемое состояние: модель теряет релевантное в шуме.

State (состояние) — структурированный список уже известных фактов о прогрессе: критерии приёмки, найденные path:line, результаты тестов, что уже изменено, какой сейчас этап. Он передаётся между ролями вместо истории переписки.

Вместо передачи всего репозитория используйте Just-in-Time Context:

%%{init: {"flowchart": {"useMaxWidth": false, "nodeSpacing": 28, "rankSpacing": 22, "wrappingWidth": 460}, "themeVariables": {"fontSize": "14px"}}}%%
flowchart TD
  A["агент видит, чего не хватает"] --> B["read / search tool"] --> C["фрагмент с источником"] --> D["state и evidence обновлены"] --> E["workflow продолжается"]

Например, repo analyst сначала получает issue, критерии и разрешённые пути, затем находит определения и тесты и передаёт implementer-у только подтверждённые path:line, нужные фрагменты и открытые вопросы. Так state связывает найденный контекст с задачей, не превращаясь в копию всей истории.

Coding agent чаще ошибается не из-за «слабого промпта», а потому что не получил нужный контракт, файлы, тесты или ограничение scope. Подавайте контекст слоями:

1. цель и критерии приёмки;
2. repo-specific правила и формат;
3. только релевантные файлы/фрагменты;
4. краткие результаты предыдущих ролей с evidence;
5. разрешения текущего этапа.

Шаблон роли planner

Ты — issue planner. Не редактируй файлы и не придумывай устройство репозитория.

Issue:
{issue}

Правила проекта:
{project_rules}

Верни JSON по схеме:
{
  "acceptance_criteria": ["..."],
  "unknowns": ["..."],
  "files_to_inspect": ["..."],
  "files_maybe_to_change": ["..."],
  "test_plan": ["..."],
  "risk_level": "low|medium|high",
  "needs_human_approval": true
}

Если критерий неоднозначен или изменение затрагивает данные/безопасность/API,
остановись со статусом needs_input.

Шаблон роли repo analyst

Ты — read-only аналитик репозитория. Файлы не меняй и команды не запускай.

Исследуй только эти пути:
{allowed_paths}

Issue и критерии:
{issue_and_acceptance}

Верни:
- найденные определения с path:line и коротким подтверждающим фрагментом;
- связи с вызывающим кодом и тестами;
- что осталось неизвестным;
- какие пути нужно исследовать дальше.

Не делай вывод о содержимом файла, которого не видел. Не предлагай широкую
перепись архитектуры, если минимальное изменение решает issue.

Шаблон роли reviewer

Ты — независимый reviewer diff. Код не меняй.

Issue/критерии:
{issue}

Diff:
{diff}

Результаты тестов:
{test_results}

На каждое замечание верни:
severity, file:line, нарушение, доказательство, сценарий отказа, уверенность.
Не сообщай о проблемах, которых нельзя подтвердить diff или тестом.
Отдельно напиши критерии, которые не удалось проверить.

Практика

Обязательное ядро: на одном issue проверьте, помогает ли передача path:line evidence и типизированного результата по сравнению со свободным текстом.

Короткое упражнение (5 минут): возьмите issue из Repo Triage и составьте два входа analyst-у: полный текст README и истории либо минимальный контекст из issue, критериев, разрешённых путей и найденных фрагментов. Сравните релевантность evidence и объём переданного контекста.

Расширение: меняйте по одному параметру — размер контекста, подробность роли, формат результата — и сравните качество с ростом токенов. Промпты держите версионированными файлами.

Расширение: retrieval как инструмент. Тот же приём в коде — ingestion, chunking, embeddings, vector search и отказ отвечать без источника — разобран в RAG-лабораторной; найденные фрагменты считаются недоверенными данными с источником, как и любой вывод инструмента.

Проверь себя

1. Вспомни кратко: что такое State, Context и Evidence?
2. Чем State отличается от всей истории диалога?
3. Какое решение Capstone уже опирается на path:line evidence?

✅ Definition of Done

• Различать State, Context и Evidence на примере одного шага Capstone.
• Собрать для роли контекст из задачи, нужных фрагментов и источников вместо всей истории чата.
• Сверить переданный path:line с файлом и сравнить его пользу со свободным пересказом.
• Обнаружить устаревшее или неподкреплённое evidence и не передавать его дальше как факт.

Навигация