Чек-лист контекста для задачи Coding Agent

Зачем агенту пакет контекста

Репозиторий показывает, как система устроена, но не объясняет, почему. Цена доставки, контракт с мобильным приложением, решение про флаги выкатки и урок прошлого инцидента живут вне кода. Если этого знания нет в контексте, агент его придумает: уверенно и правдоподобно.

Я проверил это на одной задаче: добавить в сервис доставки самовывоз из пунктов выдачи. Условие A: задача и репозиторий. Условие B: то же самое плюс пакет из 8 коротких документов, около 520 слов.

Флаг выкатки и правило возврата в условии A не появились ни разу из трёх, в условии B были в каждом прогоне: этих знаний в коде нет вообще. Быстрее и дешевле контекст агента не сделал, прогоны B шли от 4,5 до 9 минут против 4 до 7 минут у A. Он изменил другое: насколько код соответствует задаче.

Честно об ограничениях: 6 прогонов (3 и 3), один синтетический репозиторий, одна модель, проверки писал я сам. Это демонстрация механизма, а не бенчмарк.

Чек-лист: что положить в пакет контекста

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

Сколько класть

Минимально достаточно. В эксперименте на одну задачу хватило 8 документов и около 520 слов, меньше двух страниц текста. Требования уместились в 6 строк, решение по выкатке в 3 предложения, инцидент в абзац.

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

Шаблон пакета контекста

Восемь разделов, как в эксперименте. Примеры строк взяты из той же задачи про самовывоз в учебном сервисе доставки shipline; замените их своими. Строка про ссылки в начале нужна для прослеживаемости: ревьюер видит не догадку, а источник решения.

# Пакет контекста: PROD-2291, самовывоз из пунктов выдачи

Собран: 2026-09-20. Кто собрал: ответственный за модуль доставки.
Для агента: прочитай пакет до кода. Каждое решение, которое следует
из пакета, помечай ссылкой на раздел или документ (PRD-5, ADR-011).

## 1. Требования (PRD-pickup, владелец: продукт)
1. Стоимость 99 ₽. Бесплатно при сумме товаров от 3000 ₽.
2. Срок 2 дня.
3. Вес заказа до 15 кг и не больше лимита пункта (max_weight_g).
4. Вариант показывается, только если в городе есть активный пункт.
5. Без выбранного пункта выбор доставки невозможен.
6. Незабранный за 7 дней заказ возвращается, доставка не возвращается.
Приёмка: каждое правило покрыто тестом.

## 2. Контракт API (api-contracts v3.4)
- code: pickup_point; поля DeliveryOption: code, title, price, eta_days.
- Ошибки 422: pickup_point_required, pickup_point_unavailable.
- Изменения только аддитивные, поля не переименовывать.

## 3. Архитектура
- Слои: api, application, domain. Зависимости только сверху вниз.
- Способ доставки: класс в domain/delivery/, регистрация в registry.py.
- Сборка зависимостей: app.py.

## 4. Архитектурные решения
- ADR-003 (принято, 2024-03): домен не зависит от инфраструктуры,
  внешние данные только через порт в домене и адаптер в adapters/.

## 5. Выкатка
- ADR-011 (принято, 2025-02): флаг delivery_<code>, по умолчанию выключен.
  Включение по регионам после стенда и согласования с поддержкой.

## 6. Безопасность
- Никаких сетевых вызовов к партнёрам в пути запроса клиента:
  данные о пунктах из таблицы partner_pickup_points.
- Внешняя сеть только через adapters/http_gateway.py.
- Никаких токенов и адресов партнёрских API в коде.

## 7. Инциденты
- INC-2025-031: экспресс-доставку не добавили в DELIVERY_FEE_REFUNDABLE,
  возвраты падали 2 дня. Правило: у нового способа доставки есть
  правило возврата и тест на него.

## 8. Инженерные правила
- Деньги только Money (копейки), никаких float.
- Каждое бизнес-правило из требований покрыто тестом.
- Новый способ доставки: реестр, флаг выкатки, правило возврата, тесты API.

Как пользоваться

1. 1 Возьмите одну задачу Пакет собирается под задачу, а не под систему. Выпишите компоненты, которые она затрагивает: например, модуль доставки и возвраты.
2. 2 Пройдите чек-лист по группам Для каждой группы найдите действующий документ по этим компонентам. Нет документа, значит, это знание живёт в чьей-то голове: запишите его в две-три строки.
3. 3 Сократите до минимально достаточного Для каждого документа назовите решение в задаче, которое от него зависит. Не получается назвать, уберите документ. Отменённое и документы без владельца не кладите.
4. 4 Соберите пакет по шаблону и передайте агенту Попросите агента ссылаться на раздел пакета в каждом решении, которое из него следует. На ревью это превращает вопрос «почему так» в ссылку на источник.