Зачем это нужно
В модуле 4 мы научились превращать approved spec и architecture constraints в task graph. Теперь возникает следующий вопрос: какой контекст должен получить агент для выполнения одной task?
Наивный ответ:
Дадим агенту весь репозиторий, все документы и длинный prompt.
Проблема в том, что большой контекст не равен хорошему контексту. Он может содержать шум, устаревшие решения, нерелевантные файлы, противоречивые заметки и слишком много деталей, которые отвлекают от текущего проверяемого результата.
Context Engineering - это дисциплина сборки нужного контекста для конкретной agent task. Не больше и не меньше.
Главная цель урока - научиться собирать context package для agent run так, чтобы агент видел source of truth, ограничения, relevant code и verification, но не тонул в giant prompt.
Основная идея
Правильный контекст загружается слоями:
Always-on rules
+
Current specification
+
Current task
+
Relevant code
+
Relevant skill
+
Required MCP resources
Эти слои решают разные задачи.
| Слой | Зачем нужен |
|---|---|
| Always-on rules | Короткие стабильные ограничения проекта. |
| Current specification | Что именно должно работать. |
| Current task | Какой один результат нужно получить сейчас. |
| Relevant code | Где находится существующая реализация и patterns. |
| Relevant skill | Как выполнить повторяемую процедуру. |
| Required resources/tools | Где получить внешние данные или выполнить проверку. |
Context Engineering не означает "втиснуть максимум информации". Он означает "дать агенту минимальный достаточный набор для надежного действия".
Ключевые термины
| Термин | Значение |
|---|---|
| Context | Информация, доступная модели в текущем run: instructions, task, files, tool outputs, history. |
| Context Engineering | Управляемая сборка, обновление и очистка контекста для agent task. |
| Giant Prompt | Большой prompt, который пытается заменить specification, architecture, rules, examples и task plan одновременно. |
| Context Package | Подготовленный набор входных данных для одной Agent Task. |
| Always-on Rules | Короткие стабильные правила, которые агент должен соблюдать постоянно. |
| Task-specific Context | Информация, нужная только для текущей task. |
| Relevant Code | Файлы и фрагменты кода, которые влияют на текущую задачу. |
| Context Pollution | Шум, устаревшие детали и нерелевантная информация в контексте. |
| Source of Truth | Актуальный файл или система, где зафиксировано утвержденное знание. |
Почему giant prompt не масштабируется
Giant prompt часто появляется из хорошего намерения: разработчик хочет помочь агенту и добавляет "все важное".
Типичный giant prompt:
Ты senior engineer. Вот 30 правил проекта, описание архитектуры,
история решений, куски старого обсуждения, весь spec, весь README,
несколько stack traces, список задач и просьба реализовать endpoint.
Проблемы:
- важные constraints теряются среди шума;
- старые решения могут конфликтовать с новыми;
- агент не понимает, что является source of truth;
- context window тратится на нерелевантные детали;
- сложно обновлять и проверять такой prompt;
- каждый новый prompt становится уникальным и неповторяемым.
Giant prompt - это часто симптом отсутствия структуры в репозитории. Если нет spec.md, design.md, tasks.md, ADR и rules, разработчик пытается компенсировать это одним длинным сообщением.
Схема context assembly
Контекст собирается от задачи, а не от всего репозитория. Сначала вопрос "что нужно сделать сейчас?", потом "какая информация нужна для этого одного результата?".
Что должно быть always-on
Always-on context должен быть коротким и стабильным. Его задача - задавать базовое поведение агента.
Примеры always-on rules:
- Respect existing architecture boundaries.
- Do not modify files outside allowed scope without stopping.
- Run specified verification commands before claiming completion.
- Do not introduce new dependencies without explicit approval.
- Never store secrets in repository.
Что не должно быть always-on:
- полная история проекта;
- все requirements всех features;
- длинные API contracts;
- временные решения текущей task;
- большие code examples;
- logs старых failures;
- secrets.
Always-on rules должны помещаться в голову агента без борьбы за внимание.
Что должно быть task-specific
Task-specific context меняется от задачи к задаче.
Для task Validate reset token endpoint нужен один набор.
Для task Add frontend request reset form нужен другой.
Пример task-specific context:
Current task:
TASK AUTH-017 Validate reset token endpoint.
Spec sections:
- REQ-003 token expires after 15 minutes
- REQ-004 token is single-use
- AC-003 consumed token returns TOKEN_USED
- AC-004 expired token returns TOKEN_EXPIRED
Architecture:
- Controller calls AuthService
- Controller must not access database
Relevant code:
- src/auth/auth.controller.ts
- src/auth/password-reset.service.ts
- tests/auth/password-reset.controller.test.ts
Verification:
- npm test -- password-reset.controller.test.ts
Нерелевантный context:
- UI reset form implementation
- billing architecture
- all project ADRs
- old production incident transcript
- unrelated auth provider migration notes
Как выбирать relevant code
Relevant code - это не "все файлы похожей директории". Это файлы, которые отвечают на вопросы:
- где находится existing pattern;
- какие interfaces нужно использовать;
- какие tests уже есть;
- какие ошибки могут возникнуть;
- какие files likely need edit.
Для coding agent полезен порядок:
1. Read task.
2. Read spec/design references.
3. Search for existing patterns.
4. Read files most likely to change.
5. Read adjacent tests.
6. Only then edit.
Если агент сначала редактирует, а потом ищет patterns, риск drift выше.
Context package для Password Reset task
Пример:
Context Package: TASK AUTH-017
Goal:
Добавить endpoint проверки reset token.
Always-on rules:
- Respect allowed scope.
- Do not add dependencies without approval.
- Return evidence: changed files, commands, exit codes, AC status.
Source of truth:
- specs/password-reset/spec.md: REQ-003, REQ-004, AC-003, AC-004
- docs/architecture/adr/ADR-001-password-reset-token-storage.md
- docs/architecture/constraints.md: controller/service/repository layering
Task:
- specs/password-reset/tasks.md: TASK AUTH-017
Relevant code:
- src/auth/auth.controller.ts
- src/auth/password-reset.service.ts
- src/auth/reset-token.repository.ts
- tests/auth/password-reset.controller.test.ts
Constraints:
- Controller calls service.
- Do not access database from controller.
- Do not expose raw token.
- Do not modify frontend.
Verification:
- npm test -- password-reset.controller.test.ts
Stop conditions:
- Need database schema change.
- Existing service API does not support validation.
- Spec conflict found.
Такой package гораздо надежнее, чем "прочитай все и сделай endpoint".
Context quality checklist
Перед запуском agent task проверьте:
[ ] Есть один current task
[ ] Есть ссылка на approved spec
[ ] Есть relevant AC/REQ
[ ] Есть architecture constraints
[ ] Есть allowed scope
[ ] Есть do-not-modify list
[ ] Есть relevant code или search instruction
[ ] Есть verification command
[ ] Нет нерелевантных длинных logs
[ ] Нет устаревших assumptions
[ ] Нет secrets
[ ] Есть stop conditions
Если context package не проходит checklist, task лучше уточнить до запуска.
Практика: собрать минимальный контекст
Возьмите task:
TASK AUTH-017:
Добавить endpoint проверки reset token.
Создайте файл:
labs/05-context/context-package-auth-017.md
Заполните:
# Context Package: AUTH-017
## Current task
## Always-on rules
## Spec sections
## Architecture constraints
## Relevant code
## Relevant tests
## Skills needed
## Tools/resources needed
## Verification
## Stop conditions
## Explicitly excluded context
Минимальные требования:
- не больше 10 always-on rules;
- не больше 5 source documents;
- каждый included file должен иметь причину;
- минимум 3 excluded context items;
- минимум 3 stop conditions.
Типичные ошибки
Ошибка 1. Загружать весь репозиторий
Больше файлов не означает больше понимания. Нужны relevant files и search strategy.
Ошибка 2. Смешивать source of truth и transcript
Если решение важно, оно должно жить в spec/ADR/tasks, а не только в истории разговора.
Ошибка 3. Класть временную task logic в always-on rules
Rules должны быть стабильными. Task-specific детали должны жить в task context.
Ошибка 4. Не указывать stop conditions
Agent должен знать, когда остановиться, а не расширять scope.
Ошибка 5. Добавлять context без причины
Каждый документ и файл в context должен отвечать на вопрос: "какое решение или действие он помогает выполнить?"
Критерии готовности
После урока студент должен уметь:
- объяснить, что такое Context Engineering;
- отличить giant prompt от context package;
- собрать слои context для одной Agent Task;
- выбрать relevant code и excluded context;
- сформулировать stop conditions;
- использовать context quality checklist перед запуском агента.
Краткое резюме
Context Engineering заменяет giant prompt управляемой сборкой контекста. Агенту нужен не весь проект, а правильный набор: stable rules, current spec, current task, relevant code, relevant skill и необходимые tools/resources.
Качество контекста напрямую влияет на качество результата. Хороший context package снижает drift, уменьшает шум и делает agent run проверяемым.
Вопросы для самопроверки
- Почему giant prompt плохо масштабируется?
- Что должно быть always-on, а что task-specific?
- Как выбрать relevant code для task?
- Зачем явно указывать excluded context?
- Какие stop conditions нужны для coding agent?
Что дальше
В следующем уроке мы разберем Progressive Context: как загружать информацию слоями и давать агенту доступ к подробностям только тогда, когда они действительно нужны.