Урок 5.2. Progressive Context

Зачем это нужно

В прошлом уроке мы собрали context package для одной task. Но в реальной работе не всегда заранее понятно, какие детали понадобятся агенту. Если загрузить все сразу, context раздувается. Если дать слишком мало, агент начнет угадывать.

Progressive Context решает эту проблему: агент сначала получает короткие стабильные правила и текущую задачу, а подробности загружает по мере необходимости.

Это похоже на работу опытного разработчика: он не держит весь репозиторий в голове каждую секунду. Он знает, где находятся документы, patterns и tools, и открывает нужные части, когда задача этого требует.

Главная цель урока - научиться проектировать контекст слоями, чтобы агент двигался от общего к конкретному без giant prompt.

Основная идея

Progressive Context - это подход, при котором агенту доступны не все детали сразу, а уровни информации.

Модель курса:

Level 1: короткие постоянные rules
Level 2: текущая specification
Level 3: файлы текущего модуля
Level 4: skill при необходимости
Level 5: external context через MCP/resources

Каждый уровень отвечает на свой вопрос:

Level	Вопрос
1	Какие stable rules агент должен соблюдать всегда?
2	Какое behavior нужно реализовать сейчас?
3	Как устроен relevant code в этом модуле?
4	Есть ли повторяемая процедура для этой работы?
5	Нужны ли внешние данные, tools или systems?

Прогрессивность означает: сначала дать минимум, затем добавлять следующий слой только при наличии причины.

Ключевые термины

Термин	Значение
Progressive Context	Пошаговая загрузка контекста от стабильных правил к конкретным деталям.
Progressive Disclosure	Принцип: сначала показывать краткое описание, подробности открывать по необходимости.
Context Level	Слой информации с разной стабильностью и назначением.
Trigger	Условие, при котором нужно добавить следующий слой контекста.
Context Budget	Ограниченный объем внимания/context window, который нужно тратить осознанно.
Context Pruning	Удаление или неиспользование нерелевантной информации.
Skill Discovery	Механизм, при котором агент видит description skill и открывает полный skill только при необходимости.
External Resource	Внешний источник данных: docs, database schema, issue tracker, monitoring, API, MCP resource.

Схема Progressive Context

flowchart TD A[Level 1: Always-on rules] --> B[Level 2: Current spec] B --> C[Level 3: Relevant module files] C --> D{Procedure needed?} D -->|Yes| E[Level 4: Skill] D -->|No| F{External data needed?} E --> F F -->|Yes| G[Level 5: MCP / resources] F -->|No| H[Agent execution] G --> H H --> I[Verification]

Слои не всегда идут строго линейно, но порядок помогает не перегружать agent run раньше времени.

Level 1: короткие постоянные rules

Level 1 - это минимальные правила, которые должны быть известны агенту всегда.

Примеры:

- Respect allowed scope.
- Do not introduce dependencies without approval.
- Run verification before claiming completion.
- Preserve architecture boundaries.
- Stop when product behavior is ambiguous.

Свойства Level 1:

короткий;
стабильный;
применим к большинству задач;
не содержит feature-specific requirements;
не содержит длинных объяснений.

Если Level 1 разрастается до десятков страниц, он превращается в giant prompt.

Level 2: текущая specification

Level 2 отвечает за behavior.

Пример:

specs/password-reset/spec.md:
- REQ-003 token expires after 15 minutes
- REQ-004 token can be used only once
- AC-003 consumed token returns TOKEN_USED
- AC-004 expired token returns TOKEN_EXPIRED

Важно: агенту не всегда нужна вся feature spec. Часто достаточно relevant sections.

Для task Validate reset token endpoint не нужно загружать весь UI behavior. Но нужно загрузить token validity behavior.

Level 3: файлы текущего модуля

Level 3 - это relevant code и tests.

Примеры:

src/auth/auth.controller.ts
src/auth/password-reset.service.ts
src/auth/reset-token.repository.ts
tests/auth/password-reset.controller.test.ts

Критерии включения файла:

файл likely needs edit;
файл содержит existing pattern;
файл содержит interface contract;
файл содержит tests for related behavior;
файл нужен для понимания architecture boundary.

Не нужно включать весь src/auth/*, если task затрагивает один endpoint и один service method. Лучше дать search instruction, если агенту нужно найти дополнительные references.

Level 4: skill при необходимости

Skill нужен, когда задача является повторяемой процедурой.

Примеры:

create-api-endpoint
create-database-migration
write-regression-test
review-code

Агенту не нужно читать все skills заранее. Достаточно видеть names/descriptions, а полный SKILL.md открывать при trigger.

Пример trigger:

Task asks to add REST endpoint
    ↓
Use create-api-endpoint skill

Skill не должен заменять spec. Он отвечает "как обычно выполнять процедуру", а не "какое behavior нужно реализовать в этой feature".

Level 5: external context через MCP/resources

Level 5 нужен, когда информация или действие находится вне локального context.

Примеры:

- GitHub issue details
- Jira ticket
- database schema
- API documentation
- monitoring logs
- CI results
- browser state
- internal service docs

Level 5 должен быть controlled:

read-only по умолчанию;
scopes;
approval для write/destructive actions;
audit logs;
защита от untrusted content.

Детально tools и MCP будут в модуле 7. В этом уроке важно понять: external context - это отдельный слой, а не часть always-on prompt.

Когда добавлять следующий слой

Ситуация	Добавить
Агент не знает expected behavior	Relevant spec sections
Агент не знает architecture boundary	Architecture constraints/ADR
Агент не знает existing pattern	Relevant code/search results
Задача повторяемая	Relevant skill
Нужны внешние данные	Resource/MCP/tool output
Verification fails непонятно почему	Targeted logs/test output
Product behavior ambiguous	Clarification, not more code

Добавление контекста должно отвечать на конкретный вопрос. Если вы не можете объяснить, зачем добавляете документ, скорее всего, он не нужен.

Как лишний контекст ухудшает решения

Лишний context может вредить по нескольким причинам:

вытесняет важные details из внимания;
создает ложные аналогии;
приносит устаревшие decisions;
увеличивает время и стоимость run;
усложняет review reasoning;
провоцирует agent менять unrelated files.

Пример:

Task:
Добавить unit test для consumed reset token.

Лишний context:
- полный frontend design;
- billing ADR;
- old auth migration notes;
- production incident log про email provider;
- весь README проекта.

Этот context не помогает task. Он повышает вероятность, что агент начнет решать не ту проблему.

Context checklist для разных tasks

API task

Level 1:
- stable rules

Level 2:
- relevant API behavior from spec
- API acceptance criteria

Level 3:
- existing controller
- service interface
- API tests
- error format examples

Level 4:
- create-api-endpoint skill if available

Level 5:
- API docs/schema only if external contract needed

UI task

Level 1:
- stable rules

Level 2:
- UX behavior from spec
- relevant API contract

Level 3:
- existing form component patterns
- API client
- UI tests or stories

Level 4:
- create-ui-form skill if available

Level 5:
- browser inspection only if visual behavior must be checked

Test task

Level 1:
- stable rules

Level 2:
- acceptance criteria

Level 3:
- existing test patterns
- code under test
- fixtures/factories

Level 4:
- write-regression-test skill if available

Level 5:
- CI output only if reproducing CI failure

Практика: выбрать минимальный context

Для каждой task выберите Level 1-5 context.

Tasks:

T1. Добавить request reset API endpoint.
T2. Добавить frontend request reset form.
T3. Добавить regression test для consumed token.

Создайте файл:

labs/05-context/progressive-context-matrix.md

Заполните таблицу:

| Task | Level 1 | Level 2 | Level 3 | Level 4 | Level 5 | Excluded context |
|---|---|---|---|---|---|---|

Для каждого included item напишите короткую причину.

Минимальные требования:

у каждой task минимум 3 included context items;
у каждой task минимум 2 excluded context items;
Level 5 используется только там, где он действительно нужен;
если нужен skill, описан trigger.

Типичные ошибки

Ошибка 1. Сразу открывать все уровни

Progressive Context теряет смысл, если каждый agent run начинается с полного набора документов.

Ошибка 2. Не давать агенту route к подробностям

Агенту нужно знать, где найти детали, если они понадобятся: spec path, ADR path, skill name, resource identifier.

Ошибка 3. Путать skill и spec

Skill описывает процедуру. Spec описывает expected behavior. Они оба могут быть нужны, но отвечают на разные вопросы.

Ошибка 4. Добавлять external context без security boundary

Внешние resources могут быть недоверенными или требовать permissions. Их нельзя смешивать с trusted project rules.

Ошибка 5. Не очищать устаревший context

Если решение изменилось, старые assumptions нужно убрать или пометить deprecated. Иначе агент может использовать их снова.

Критерии готовности

После урока студент должен уметь:

объяснить Progressive Context;
назвать 5 уровней context model курса;
выбрать минимальный контекст для API, UI и test tasks;
определить trigger для подключения skill;
объяснить, когда нужен external context;
указать excluded context и причину исключения.

Краткое резюме

Progressive Context помогает агенту получать информацию слоями. Сначала stable rules и current task, затем relevant spec, relevant code, skill и external resources только при необходимости.

Это снижает context pollution и делает agent run более управляемым. Хорошая система не заставляет модель читать 50 страниц каждый раз. Она дает короткий путь к нужному знанию.

Вопросы для самопроверки

Чем Progressive Context отличается от giant prompt?
Что относится к Level 1 context?
Когда нужно подключать skill?
Почему external context должен быть отдельным слоем?
Как понять, что документ не стоит включать в context package?

Что дальше

В следующем уроке мы разберем project-level instructions: где хранить короткие стабильные правила проекта для разных coding agents и почему rules не должны превращаться в энциклопедию.