Доки против кода: какой контекст использовать для багов, фич и инцидентов

Почему отправка обоих источников часто ухудшает ответы

Давать модели и доки, и код одновременно кажется безопасным. На практике это часто делает ответ менее точным. Модели приходится просеивать лишний материал, прежде чем сосредоточиться на задаче.

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

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

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

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

Меньшая подсказка обычно даёт лучший первый проход. Начинайте с источника, который соответствует задаче. Добавляйте второй источник только если модель сталкивается с реальным пробелом, например отсутствующим намерением, неясными бизнес‑правилами или путями в коде, зависящими от поведения, которого никто не зафиксировал.

Начните с именования задачи

Плохой контекст в ИИ чаще всего появляется ещё до того, как кто‑то прикрепит файл. Команды смешивают баг‑репорт, запрос на фичу, заметку об инциденте и задачу на чистку в одну подсказку — а потом удивляются, почему ответ кажется расплывчатым. Модель не провалилась. Работа была неясной.

Дайте задаче простую метку: баг, фича, инцидент или чистка. Это одно слово меняет то, что модель должна читать и что игнорировать. Баг спрашивает про текущее поведение. Фича — про намерение. Инцидент — про живое состояние. Чистка — про то, что можно удалить, упростить или переименовать без изменения результата.

Потом сформулируйте запрос одной простотой фразой. «Почему скидка пропадает после оформления?» — достаточно. «Добавить региональные правила ценообразования для годовых планов» — достаточно. Если фраза продолжает расти, разделите работу. Одна подсказка должна отвечать на одну вещь.

После этого решите, какой контекст нужен модели. Если вопрос про намерение — используйте доки, продуктовые заметки или записи решений. Если про поведение — используйте код, тесты и недавние изменения. Если про живое состояние — используйте логи, алерты, дашборды и runbooks.

Здесь команды экономят время. Если ваша фраза спрашивает про намерение, модели не нужен половина репозитория. Если про поведение — продуктовая записка мало поможет. Если про живое состояние — старые доки скорее отвлекут.

Удалите все файлы и страницы, которые не помогают ответить на написанную вами фразу. Длинный архитектурный документ не исправит упавший endpoint. Десять исходных файлов не объяснят решение по политике. Во время инцидента логи вчерашнего дня могут быть важнее отточенной спецификации.

Это кажется мелочью, но меняет результат быстро. Чистая подсказка часто сокращает контекст вдвое и даёт ответ, который можно применить.

Для работы с багами сначала читайте код

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

Начинайте с малого. Откройте обработчик, сервис, запрос или UI‑действие, ближайшее к баг‑репорту. Затем откройте тест, покрывающий этот путь, если он есть, и конфиг или feature flag, который может менять поведение. Этот набор часто достаточен, чтобы найти причину без перетаскивания половины репозитория.

Тесты важны, потому что они обнажают предположения. Название теста может говорить «гости могут сохранять черновики», в то время как реализация тихо блокирует гостей при переключении одного флага. Конфиг важен по той же причине. Многие баги — не глубокие логические ошибки, а последствия значения по умолчанию, устаревшего env‑параметра, fallback или одного пропущенного случая в switch.

Хороший набор контекста для бага обычно небольшой:

• падающая функция или компонент
• ближайший тестовый файл
• конфиг, флаги или схема, связанные с этим путем
• самое недавнее изменение, затрагивающее эти файлы

Недавним изменениям стоит уделить дополнительное внимание. Если баг появился на этой неделе, сравните текущий код с последней рабочей версией прежде, чем читать общие дизайн‑доки. Команды часто тратят время на вставку архитектурных заметок в подсказку, когда реальная причина — одно изменённое значение по умолчанию, один null‑случай или одно переименованное поле.

Используйте доки позже, а не сначала. Они помогают подтвердить ожидаемое поведение, когда код и баг‑репорт расходятся. Если доки говорят, что запрос должен округлять в большую сторону, а код — в меньшую, теперь несоответствие имеет значение. Раньше же доки чаще отвлекают.

Держите контекст близко к багу. Если итог суммы при оформлении неверен, отправьте функцию ценообразования, связанные тесты, налоговую конфигурацию и последние коммиты вокруг этой области. Пропустите несвязанные модули, старые планы и дерево всего репозитория. Более узкая подсказка обычно даёт более чистый ответ.

Для фич начинайте с доков

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

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

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

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

Простой пример делает разницу ясной. Допустим, SaaS‑продукт вводит правило триала: пользователи на триале могут приглашать коллег, но только владелец аккаунта может экспортировать данные. Док говорит правило, путь пользователя и критерии успеха. Поиск по коду должен фокусироваться на правах приглашений, проверках экспорта и обработке состояния триала. Вам не нужна вся биллинговая система или все модели аккаунтов.

Перед тем как модель предложит код, задайте один прямой вопрос: сравните доки с выбранными файлами и перечислите пробелы. Это часто выявляет реальную работу. Возможно, эндпоинт проверяет статус плана, но игнорирует роль пользователя. Возможно, acceptance‑заметки упоминают текст на экране, а компонент ещё не рендерит его.

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

Для инцидентов начинайте с runbook и сигналов

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

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

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

Инструменты вроде Sentry, Grafana и Prometheus полезны, потому что дают модели реальные данные для рассуждений. Если rate ошибок подскочил в 14:03, а деплой закончился в 14:01, это имеет значение. Если runbook говорит «сначала проверьте глубину очереди», а очередь нормальна, модель может прекратить гадать и двигаться дальше.

Открывайте код только после того, как сузите падающую область. Чтение кода слишком рано замедляет триаж, потому что модель начинает объяснять, как система работает, вместо того чтобы понять, почему она сломалась сейчас. Как только вы локализуете вероятный сервис, задачу или обработчик — отправьте маленький фрагмент кода, соответствующий симптому, плюс недавний дифф.

Например, сработал алерт по биллингу и checkout возвращает 500. Отправьте текст алерта, сводку последнего деплоя, несколько платежных логов и runbook биллинга сначала. Если эти сигналы указывают на один webhook‑handler, тогда добавьте этот обработчик и изменённые строки. Это позволит модели сосредоточиться на живой проблеме, а не на всех возможных проблемах.

На первом проходе задавайте узкие вопросы. «Что изменилось? Что нам проверить дальше? Какая самая безопасная точка отката?» обычно дают лучший ответ, чем «Прочитай всё это и найди проблему».

Как выбирать контекст пошагово

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

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

Потом выберите один основной источник:

• Используйте код, когда нужно объяснить поведение, проследить баг или изменить логику.
• Используйте доки, когда нужно понять намерение, объём, правила или поведение для пользователя.
• Используйте runbook или заметки инцидента, когда система падает прямо сейчас и время критично.

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

Добавляйте один вспомогательный источник только если первичный оставил реальный пробел. Если код показывает баг в расчёте налога, но не говорит, какое бизнес‑правило должно применяться, добавьте спецификацию ценообразования. Если дока описывает новую настройку, но не указывает, где она живёт, добавьте соответствующий модуль или API‑хэндлер. Если сработал алерт, а runbook говорит «проверьте отставание очереди», приложите снимок дашборда или недавние логи, но не всю папку сервиса.

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

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

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

Простой пример на баге с ценообразованием

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

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

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

Теперь проверьте политику. В доке сказано «округлять только один раз в конце». Это даёт реальное несоответствие. Код показывает, что система делает сейчас. Дока — что система должна делать.

Модель затем может объяснить баг простыми словами: раннее округление меняет математику, поэтому итог счёта дрейфует на пару центов. Она также может набросать фикc: сохранять полную точность при подсчёте позиций, суммировать неокруглённые значения и округлять только финальную сумму инвойса.

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

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

Частые ошибки команд

Команды часто отправляют слишком много сразу. Копируют целую папку, экспорт вики и кучу старых доков в одну подсказку и просят модель «найти баг». Это обычно портит ответ. Модель тратит ресурсы на мёртвые файлы, устаревшие решения и повторяющиеся объяснения вместо нескольких строк, которые контролируют поведение.

Ещё одна ошибка — пропускать файлы, которые реально формируют runtime‑поведение. Делятся контроллером, API‑роутом или UI‑компонентом, но забывают тест, feature flag, настройку окружения или конфиг ценообразования. Тогда модель заполняет пробелы догадками. Если поведение зависит от плана, региона или типа клиента, конфиг и тесты могут быть важнее ещё одного исходного файла.

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

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

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

Быстрая проверка перед отправкой контекста

Большинство слабых ответов ИИ формируется до того, как модель прочитает хоть один файл. Задача размыта, контекст смешан, и половина материалов лишь добавляет шум. Двухминутная проверка часто даёт больше эффекта, чем добавление 20 лишних страниц.

Сначала сформулируйте один точный вопрос. Если вы не можете уложиться в одно предложение, модель, скорее всего, угадает неправильно. «Почему при ежегодной оплате на checkout показывается месячная сумма?» — ясно. «Проверьте эту систему ценообразования» — нет.

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

• код — когда нужно объяснить текущее поведение или найти баг;
• доки — когда нужно спланировать фичу, подтвердить правила или понять пользовательское поведение;
• runbooks, алерты и трассы — когда идёт живой инцидент.

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

Обрежьте устаревшее или шумное. Старые доки путают модель. Сгенерированные файлы тратят место. Огромные логи без явного сигнала засыпают ту единственную строку, которая важна. Если файл не меняет ответ — уберите его.

Простой тест: спросите у напарника, почему каждый элемент включён. Если он не сможет объяснить это одним коротким предложением, вероятно, его не стоит отправлять.

Вы можете использовать такой пред‑фильтр перед отправкой:

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

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

Следующие шаги для команд, которые хотят чище работать с ИИ

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

Начните с маленького плейбука для трёх типичных задач. Для багов давайте модели падающий тест, сообщение об ошибке, стек‑трэйс и файлы, которые, вероятно, вызвали проблему. Для фич — продуктовую заметку, критерии приёмки и доки, объясняющие ожидаемое поведение. Для инцидентов — runbook, логи, недавние деплои и текущие сервис‑сигналы. Сохраняйте удачные подсказки, помечайте их по типу задачи и переиспользуйте вместо того, чтобы каждый раз всё переписывать.

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

Также полезно раз в месяц просматривать пару реальных подсказок. Выберите один баг, одну фичу и один инцидент. Проверьте, какой контекст присылала команда, что модель упустила и что стоило бы убрать. Через пару итераций паттерны становятся ясны.

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

Если нужна внешняя помощь в настройке, держите её практичной. Oleg Sotnikov, at oleg.is, работает в роли Fractional CTO и стартап‑советника. Он помогает командам строить AI‑first рабочие процессы, lean‑инфраструктуру и правила контекста, подходящие для ежедневной инженерной работы.