Контекст не теряется: 15 промтов для работы с большой кодовой базой и документацией

Вы открываете репозиторий на 400 тысяч строк, и первое, что вы чувствуете — не вдохновение, а лёгкую панику. Где инициализируется конфиг? Почему UserService вызывает LegacyAuthAdapter? Кто и зачем добавил этот TODO от 2019 года? Знакомо? По данным отчёта State of DevOps 2023 (Google Cloud / DORA), высокоэффективные команды тратят на восстановление контекста заметно меньше времени, чем отстающие, и именно эта разница напрямую коррелирует с частотой деплоев и временем восстановления после инцидентов. Проще говоря: скорость команды упирается не в скорость печати, а в скорость понимания.

Хорошая новость: LLM отлично справляются с ролью «второй памяти» — если давать им правильные промты. Плохая новость: запрос «объясни мне этот код» работает ровно никак. Ниже — 15 проверенных промтов для восстановления контекста: от первого знакомства с репозиторием до безопасного рефакторинга legacy-модуля. Каждый — с описанием задачи, готовым текстом и примером применения.

Почему «просто спросить у ChatGPT» не работает

Контекстное окно — не бесконечное. Даже модели с окном в сотни тысяч токенов (см. документацию Anthropic по context windows и OpenAI) теряют точность на длинных входах: исследование «Lost in the Middle» (Liu et al., 2023, arXiv:2307.03172) показало, что модели хуже извлекают информацию из середины длинного контекста. Вывод простой: контекст нужно не «заливать», а структурировать. Промты ниже делают именно это — превращают хаос файлов в сжатые, пригодные для работы ментальные модели.

1. Карта репозитория за один проход

Задача: быстро понять структуру незнакомого проекта.

Ты — senior-инженер, который впервые видит этот репозиторий.
Ниже — вывод `tree -L 3 -I 'node_modules

|.git|dist'`.

Задачи:
1. Определи тип проекта (монорепо/микросервисы/монолит) и стек.
2. Назови 5 директорий, которые критичны для понимания архитектуры, и объясни почему.
3. Укажи, где, скорее всего, лежат: точка входа, конфиги, миграции БД, тесты.
4. Перечисли 3 вопроса, которые нужно задать команде перед первым коммитом.

Формат: markdown-таблица «Путь

| Роль | Почему важно».

<tree>
...вставь сюда вывод tree...
</tree>

Пример: для Django-проекта промт сразу подсветит settings/, apps/, manage.py и укажет, что apps/*/migrations — зона риска при рефакторинге моделей.

2. Сжатие файла в «контракт»

Задача: не читать 800 строк, а понять, что модуль обещает наружу.

Проанализируй файл ниже. Верни ТОЛЬКО:
- Публичный API (функции/классы/экспорты) с сигнатурами.
- Побочные эффекты (I/O, сеть, БД, глобальное состояние).
- Внешние зависимости.
- 3 сценария использования в формате «вызов → результат».
Никаких пересказов реализации. Только контракт.

<file path="...">
...
</file>

Пример: для payment_gateway.py вы получите сигнатуры charge(amount, currency), refund(tx_id) и явное предупреждение: «делает сетевой вызов, не идемпотентен без idempotency_key».

3. Трассировка вызова через слои

Задача: понять, как запрос проходит от HTTP до БД.

Ниже — 4 файла: контроллер, сервис, репозиторий, модель.
Построй цепочку вызовов для эндпоинта POST /orders.
Формат: нумерованный список «файл:строка → что происходит → какие данные меняются».
Отметь места, где возможны N+1-запросы или блокировки.

Пример: промт покажет, что OrderService.create() вызывает inventory.reserve() вне транзакции — классический источник гонок при высокой нагрузке.

4. «Объясни как новичку» для legacy-кода

Задача: разобрать непонятный кусок без стыда спросить.

Объясни этот код трём аудиториям:
1. Джуниор: что делает код построчно, простыми словами.
2. Мидл: какие паттерны использованы, какие альтернативы есть.
3. Архитектор: какие компромиссы заложены и какие риски они создают через год.
Затем предложи 2 варианта упрощения без изменения поведения.

Пример: загадочный class Foo(Bar, metaclass=Baz) из чужого фреймворка превращается в понятную схему «динамическая регистрация плагинов».

5. Дифф против документации

Задача: найти расхождения между README и кодом.

Сравни README (ниже) и сигнатуры из кода.
Верни таблицу:

| Утверждение в README | Реальность в коде | Расхождение | Риск |
Укажи устаревшие параметры, удалённые функции и примеры, которые не скомпилируются.

Пример: README обещает client.send(data, retries=3), а в коде retries удалён ещё в v2.0 — типичная причина «работает у меня, падает у клиента».

6. Восстановление истории решения

Задача: понять, почему код написан именно так, а не иначе.

Ниже — вывод `git log --follow -p -- <file>` за последние 2 года (сокращённый).
Восстанови нарратив:
- Какие проблемы решали коммиты?
- Какие решения были откатаны и почему?
- Какие TODO/FIXME остались открытыми?
Формат: таймлайн «дата — проблема — решение — статус».

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

7. Безопасный план рефакторинга

Задача: изменить код, не сломав скрытые зависимости.

Модуль X нужно отрефакторить: <цель>.
Составь план по шагам:
1. Какие тесты должны существовать ДО начала (и чего не хватает).
2. Порядок изменений, при котором система остаётся рабочей после каждого шага.
3. Точки отката.
4. Метрики, по которым поймём, что рефакторинг удался.
Не пиши код — только план.

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

8. Синтез документации из кода

Задача: получить docstring и README там, где их нет.

Для каждой публичной функции в файле сгенерируй docstring в стиле Google.
Включи: назначение, параметры с типами, возвращаемое значение, исключения, пример вызова.
Если поведение неочевидно из кода — пометь [ТРЕБУЕТ ПРОВЕРКИ], не выдумывай.

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

9. Поиск скрытых связей между модулями

Задача: найти неочевидные зависимости перед удалением «мёртвого» кода.

Ниже — список импортов и grep по имени символа `X` по всему репозиторию.
Определи:
- Прямые зависимости.
- Косвенные (через рефлексию, строковые имена, DI-контейнеры, конфиги).
- Динамические вызовы (getattr, importlib, eval).
Вывод: можно ли безопасно удалить X? Если нет — что сломается?

Пример: getattr(module, f"handler_{action}") не находится обычным grep'ом — промт обратит на это внимание.

10. Онбординг-гайд для нового разработчика

Задача: превратить ваши знания в артефакт.

На основе структуры репозитория, README и списка сервисов составь онбординг-гайд на первую неделю:
День 1: что запустить локально (команды).
День 2: как прогонять тесты и где смотреть логи.
День 3: первый безопасный PR — что можно сделать за час.
День 4–5: карта «кто за что отвечает» (по CODEOWNERS и истории коммитов).
Включи ссылки на реальные файлы в репозитории.

Пример: такой гайд сокращает типичные вопросы в чате и снижает bus factor.

11. Разбор инцидента по логам

Задача: восстановить контекст сбоя без паники в 3 часа ночи.

Ниже — фрагмент логов за окно инцидента и последний деплой (diff).
Составь таймлайн:
- Первое аномальное событие.
- Коррелирующие изменения в коде/конфиге.
- Гипотеза первопричины с уровнем уверенности (высокая/средняя/низкая).
- Что проверить в первую очередь.
Не выдавай окончательный вердикт — только гипотезы с доказательствами.

Пример: промт свяжет рост 500-х с изменением в конфиге пула соединений за 12 минут до первого сбоя.

12. Перевод между языками и фреймворками

Задача: миграция модуля без потери смысла.

Переведи модуль с <язык A> на <язык B>, сохранив:
- контракт (сигнатуры и семантику исключений),
- идиоматичность целевого языка,
- комментарии, объясняющие неочевидные решения.
Отдельно перечисли места, где поведение может отличаться (тайминги, типы, обработка null).

Пример: при переносе с Python на Go промт предупредит про разницу в обработке ошибок и отсутствие исключений.

13. Проверка понимания (self-test)

Задача: убедиться, что вы действительно поняли код, а не «прочитали».

На основе файла X составь 10 вопросов на понимание:
- 3 про поток данных,
- 3 про граничные случаи,
- 2 про производительность,
- 2 про безопасность.
К каждому — правильный ответ со ссылкой на строку.

Пример: отличный способ подготовиться к code review, где вас спросят «а что будет, если…».

14. Сжатие документации в шпаргалку

Задача: превратить 40 страниц официальной документации в одностраничник.

Ниже — фрагмент официальной документации <библиотека, версия>.
Сделай шпаргалку:
- 10 самых частых операций с примерами кода.
- 5 подводных камней с указанием раздела, откуда взято.
- Ссылки на конкретные якоря в оригинальной документации.
Не добавляй ничего, чего нет в тексте.

Пример: так удобно держать под рукой актуальный API вместо устаревших статей в блогах.

15. Метакомментарий: «что я упускаю?»

Задача: найти слепые зоны в собственном понимании.

Вот моё текущее понимание системы: <ваше описание в 5–10 предложениях>.
Вот файлы, которые я НЕ смотрел: <список>.
Скажи:
- Какие предположения в моём описании могут быть ложными?
- Какие файлы критично посмотреть в первую очередь и почему?
- Какой вопрос я не задаю, но должен?

Пример: самый недооценённый промт — он превращает LLM из отвечающего в проверяющего.

Как встроить это в рабочий процесс

Промты бесполезны, если лежат в заметках. Три практических правила:

1. Версионируйте промты. Держите их в prompts/ рядом с кодом. Промт — такой же артефакт, как Makefile.
2. Не доверяйте слепо. Любой вывод модели — гипотеза. Проверяйте по коду и тестам. Особенно если речь про безопасность, деньги или данные пользователей.
3. Помните про приватность. Не отправляйте в сторонние сервисы код с секретами, ключами и персональными данными. Используйте локальные модели или корпоративные шлюзы с политикой обработки данных (см. OWASP Top 10 for LLM Applications).

Восстановление контекста — это навык, а не магия. Чем лучше вы умеете задавать вопросы, тем меньше времени тратите на археологию в чужом коде и тем больше — на то, что действительно двигает продукт. Возьмите два-три промта из списка, примените их к текущей задаче и сравните, сколько времени ушло на «въезд» в код. Скорее всего, вернётесь за остальными. А если хотите системно прокачать работу с AI-инструментами для разработки — загляните в материалы asibiont.com/blog, там есть разборы и по промт-инжинирингу, и по инженерным практикам.