Context selection: контекст как бюджет

1. «Дай весь проект» делает результат хуже

Раз Claude не видит проект целиком, напрашивается вывод: дать ему всё подряд — весь src/, дневной лог, заметки из тикета, README. Работает наоборот. Лишний контекст конкурирует за внимание модели с важными сигналами: рассуждения теряют точность, diff становится шире и опаснее. Особенно на узких задачах, где нужен аккуратный результат.

Контекст — это бюджет качества. Внимание модели ограничено; чем точнее потратите, тем выше шанс, что Claude увидит нужную причинно-следственную связь, а не уйдёт блуждать. Не максимальный, а достаточный.

Плохо:
"Прочитай весь проект и почини логин."

Лучше:
"Разберите баг с пустым экраном после неверного пароля.
Работайте только с auth-модулем, существующим тестом и фрагментом лога ниже.
Сначала объясните вероятную причину, потом предложите минимальное изменение."

Во втором случае вы не жадничаете — вы заранее сужаете область поиска и защищаете проект от полезного, но опасного размаха.

2. Источники контекста: что помогает, что мешает

Ошибка не в незнании полезных источников, а в неумении отличить полезное от обязательного и лишнего. В сессию валится всё: факт, гипотеза, лог, README, .env, комментарий из тикета двухнедельной давности.

Держите эту таблицу в голове под любую задачу:

Теперь посмотрим на вторую половину картины — что в контекст часто кладут зря.

Здесь есть важный нюанс. Полезные источники не означают, что их нужно давать все сразу. Если вы обновляете документацию по одному endpoint в Commerce OS, вам, скорее всего, не нужны stack trace и лог ошибки. Если вы чините падение при логине, вам почти наверняка нужен лог и reproduction, а вот старый маркетинговый README вообще ни при чём. Источник контекста ценен не сам по себе, а только в связке с задачей.

Очень хороший практический вопрос звучит так: если я уберу этот источник из сессии, Claude станет работать хуже или просто вздохнёт с облегчением? Если ответ ближе ко второму, скорее всего, источник лишний.

3. Контекст — это не доказательство

На этом месте многие начинают путать две разные вещи. Контекст — это то, с чем Claude работает. Доказательство, или evidence, — это то, что подтверждает ваши утверждения и помогает проверить результат. Эти слои пересекаются, но это не одно и то же. Если их не различать, модель очень быстро начинает звучать уверенно там, где на деле просто догадывается.

Представьте короткую запись в вашем EVIDENCE_LOG.md для Commerce OS:

Проблема: после неверного пароля UI показывает белый экран.
Факт: ошибка воспроизводится стабильно.
Доказательства:
- скриншот пустой страницы
- stack trace из браузера
- failing тест AuthFlowTest.invalid_password
Гипотеза:
- возможно, проблема в рендеринге ошибки, а не в SessionService

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

Разница особенно заметна в диалогах такого типа:

Слабый вариант:
"Похоже, SessionService ломает логин. Исправь."

Сильный вариант:
"При неверном пароле UI показывает белый экран.
Ниже stack trace и failing тест.
Проверь, действительно ли проблема в SessionService, прежде чем менять код."

Во втором варианте вы не запрещаете Claude думать. Вы просто не даёте ему принять непроверенную догадку за истину. А это и есть взрослая работа с контекстом.

Полезно запомнить простую формулу. Контекст отвечает на вопрос «с чем работать», а доказательство — на вопрос «почему мы вообще так думаем». Если в сессии есть только первое, ответы будут быстрыми, но шаткими. Если есть только второе без конкретной области кода, ответы будут осторожными, но расплывчатыми. Нужны оба слоя.

4. Отбор контекста: простой порядок действий

Хороший отбор контекста редко начинается с файлов. Он начинается с задачи. Пока вы не понимаете, какой результат вообще нужен, вы не сможете понять, какие материалы реально помогут. Поэтому полезно держаться одного и того же порядка. Он довольно скучный, зато отлично экономит время и нервы.

Вот самый рабочий каркас:

Цель задачи → затронутая область → evidence → ограничения → только потом дополнительные материалы

Можно разложить его в таблицу и пользоваться как мини-проверкой перед началом сессии:

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

Особенно полезен второй шаг — затронутая область. Допустим, вы ещё не знаете точные файлы. Это нормально. Тогда правильное действие — не грузить весь проект, а сначала попросить Claude помочь найти кандидатов на affected area. Например, так:

Найди, какие файлы, классы и тесты, вероятнее всего, отвечают
за обработку ошибки неверного пароля в Commerce OS.
Пока без изменений в коде. Дай только кандидатов и evidence.

Это уже контекстная дисциплина. Вы не изображаете, что знаете всё. Но и не устраиваете модели экскурсию по каждому каталогу проекта.

Есть ещё один важный принцип: дополнительные материалы нужно добавлять не из страха, а по необходимости. Если после первого прохода выяснилось, что нужен ещё один файл с конфигурацией или ещё один test, отлично — добавляете точечно. Контекст не обязан быть идеальным с первой секунды. Он должен расширяться осознанно.

5. Commerce OS: белый экран после неверного пароля

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

Сначала зафиксируем суть в коротком фрагменте TASK_SPEC.md:

## Цель
Исправить белый экран после неверного пароля.

## Область изменений
Только auth-модуль и связанные тесты.

## Не-цели
Не менять SSO, не трогать payments, не добавлять зависимости.

Уже здесь видно: весь проект нам не нужен, нужен auth-модуль. Значит, в качестве основного контекста подойдут:

• src/auth/LoginController.java
• src/auth/SessionService.java
• src/auth/AuthFlowTest.java
• короткий фрагмент лога или stack trace
• reproduction steps из тикета

А вот что нам точно не нужно на старте:

• payments/
• orders/
• dashboard/
• полный application.log
• production config с секретами
• любая несвязанная документация

Представим, что лог выглядит так:

2026-05-12 10:14:21 ERROR LoginPage
TypeError: cannot read property "message" of null
at renderLoginError (LoginPage.tsx:48)
at handleFailedLogin (LoginController.java:73)

Это уже хорошее evidence: у нас есть наблюдаемое поведение и точка входа в код. Теперь можно собрать сильный запрос для Claude:

Ниже задача и минимальный контекст по багу в Commerce OS.

Задача:
После неверного пароля UI показывает белый экран.

Используйте только:
- src/auth/LoginController.java
- src/auth/SessionService.java
- src/auth/AuthFlowTest.java
- фрагмент лога ниже

Ограничения:
- не менять public API
- не трогать SSO
- не добавлять зависимости

Сначала объясните вероятную причину и укажите,
достаточно ли этого контекста для минимального исправления.

Здесь хорошо вот что. Вы не приказываете «немедленно чинить». Сначала вы проверяете, хватает ли отобранного контекста. Это полезная привычка. Иногда модель честно отвечает: «Нужен ещё один файл». И это отличный результат. Значит, отбор контекста сработал: вы начали с узкого набора и расширяете его только по подтверждённой необходимости.

Если бы вместо этого вы дали весь src/ и лог на тысячу строк, у модели было бы намного больше поводов расползтись. Она могла бы, например, решить, что проблема вообще в глобальном error handler, во фронтенд-слое целиком или в несовпадении формата ошибок между модулями. Теоретически это возможно. Практически для этой задачи — вредно.

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

6. Один Claude, разный контекст для разных задач

Очень полезно увидеть, как отбор контекста меняется вместе с типом задачи. Одна и та же модель, один и тот же проект, но набор контекста будет разным. Это значит, что нельзя выработать один «универсальный пакет» файлов и всегда кормить им сессию. Такой пакет почти гарантированно будет шумным.

Вот простой ориентир на трёх типичных задачах в Commerce OS:

Обратите внимание на вторую строку. Если вы обновляете документацию по refund endpoint, лог ошибки может быть вообще бесполезен. Намного важнее увидеть текущую реализацию контроллера, существующий API test и ту часть документации, которую нужно синхронизировать. Это другая задача, значит и бюджет качества тратится иначе.

Или возьмём небольшую feature: например, добавить понятное сообщение об ошибке в форме логина. Здесь stack trace уже может не понадобиться, если поведение ожидаемое и задача формулируется как UX-улучшение. Зато полезным будет похожий компонент, где ошибки уже оформлены правильно. То есть в контекст пойдёт не лог, а хороший образец из текущего проекта.

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

7. Рабочий шаблон запроса для чистой сессии

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

Вот шаблон, который можно использовать почти без изменений:

Цель:
...

Текущее поведение:
...

Ожидаемое поведение:
...

Используйте как контекст только:
- ...
- ...
- ...

Доказательства:
- ...
- ...
- ...

Ограничения:
- ...
- ...
- ...

Если этого контекста недостаточно, не расширяйте scope сами.
Сначала скажите, какого именно файла или сигнала не хватает и зачем.

Сила этого шаблона не в красоте. Сила в двух привычках, которые он формирует. Во-первых, вы заранее различаете цель, evidence и ограничения. Во-вторых, разрешаете контексту расширяться только по запросу, а не самопроизвольно.

Очень важно, что такой подход не делает вас «жадным» к информации. Иногда Claude действительно нужен ещё один файл. Иногда нужен ещё один test case. Иногда нужен небольшой кусок config. Это нормально. Хороший отбор контекста — не про минимализм любой ценой. Он про осознанное расширение. Сначала вы даёте минимально достаточный набор. Потом, если evidence показывает нехватку, добавляете ещё один слой. Но не раньше.

Если вы начнёте использовать такой шаблон хотя бы на половине задач, быстро заметите приятный эффект. Сессии становятся спокойнее. Ответы — менее расползающимися. Diff — уже не таким широким. А главное, появляется ощущение, что вы не «убеждаете AI не сходить с ума», а просто управляете инженерной работой нормальным взрослым способом. И это, честно говоря, намного приятнее, чем потом полчаса читать, почему для починки логина нужно срочно пересобрать архитектуру мира.