Заметки prompt в репозитории: что сохранять, а что пропускать

Проблема разбросанных инструкций

Команды обычно записывают правила. Проблема — где они это делают.

Одно правило остается в чате. Другое — в старом тикете. Третье живет в чьей‑то памяти после быстрого код‑ревью. Когда работа ускоряется, такая разбросанность приводит к переделкам.

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

Хуже, когда инструкции лежат в местах, которые никто не проверяет в обычной работе. Закрытые чаты, прошлые тикеты, комментарии в PR, личные заметки и старые onboarding‑доки — всё это может хранить часть истории. Ничто не дает полной картины, когда кто‑то пытается быстро внести изменение.

Устаревшие заметки создают другую проблему. Команда переименовала сервис, переместила директорию или убрала библиотеку, а старая инструкция осталась. Тогда человек или AI‑помощник следуют вчерашнему правилу и пишут код, который уже не подходит. Кому‑то приходится это ловить, объяснять и проверять снова. По десяти минуту тут и двадцати минут там быстро складываются.

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

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

Что стоит хранить в репо‑заметках

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

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

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

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

Это ещё важнее, когда команда полагается на AI‑инструкции. Если в репо используется GitLab CI, зависят от Sentry‑дашбордов или используют сгенерированный код и автоматизацию, заметки должны чётко прописывать, что нельзя ломать. Одна строчка вроде do not rename these fields because dashboards depend on them может спасти от сложного отката.

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

Что не стоит оставлять в репо

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

Первое, что нужно исключить — одноразовые инструкции по задаче. Use this temp script for Friday's import или skip test X until Sam is back подходят в чате или тикете. Через месяц такие строки только запутают новичков и будут выглядеть как постоянные правила, хотя были временной заплатой.

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

То же самое про логи чатов. Копирование длинных AI‑разговоров или Slack‑потоков в папки проекта кажется безопасным, но создаёт шум. Никто не должен читать 200 строк переписки, чтобы найти одну инструкцию про именование, тестирование или деплой.

Полезен быстрый фильтр. Оставьте за пределами репо персональные напоминания вроде ask Anna for the old password или remember my local alias. Не храните временные обходы без срока или владельца. Не держите старые споры после принятого решения. Не кладите сырые стенограммы там, где короткая заметка говорит то же самое.

Личная аббревиатура тоже часто создаёт проблемы. Заметки типа use the usual fix или same as last time понятны только автору. Остальные вынуждены догадываться. Репо‑заметки должны помогать новому участнику разобраться в проекте без приватного контекста.

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

Где размещать заметки, чтобы их нашли

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

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

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

Простые имена файлов важнее креативных. README.md, NOTES.md или AI-INSTRUCTIONS.md легко найти и запомнить. Имена вроде ideas-final-v2.md или temporary guidance.md быстро теряются, даже в небольшом репо.

У большинства команд хватает простой структуры:

• одна общая заметка в корне для правил, действующих повсюду
• одна локальная заметка в папке, если у неё есть особые правила сборки, тестов или prompt'ов
• короткие комментарии в коде, когда деталь имеет смысл прямо рядом с реализацией

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

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

Как добавлять prompt‑заметки шаг за шагом

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

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

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

Короткий пример обычно лучше длинных объяснений. In services/billing, keep HTTP handlers thin. Put pricing logic in internal/pricing. — это даёт ясное направление и точное место. Длинный абзац про чистую архитектуру делает меньше пользы.

Будьте точны в границах применения. Если правило касается только миграций — так и скажите. Если оно важно только во время ревью — укажите это. Репо‑заметки проваливаются, когда звучат универсально, но подходят лишь для одного уголка кода.

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

Это весь цикл: заметить повторяющуюся проблему, написать минимально полезное правило, положить его в правильное место и проверить в реальной работе.

Простой пример из небольшой команды

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

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

В папке API они держат заметку с командами тестирования, которые реально запускают перед коммитом. Там также написано, где смотреть логи в локальной разработке и в продакшне. Это экономит время — никто не гадать, появится ли упавший запрос в логах приложения, воркера или шлюза.

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

Эти заметки короткие, потому что короткие заметки читают. Полезная заметка может содержать команду юнит‑тестов для одного сервиса, команду smoke‑проверки для обоих, первое место для поиска логов по auth, jobs или webhooks и правило именования эндпойнтов и полей в ответе.

Что команда не кладёт в репо, тоже важно. Они не вставляют старую историю тикетов, чат‑сводки или длинные объяснения, почему баг #184 случился три месяца назад. Если деталь не поможет в следующей похожей задаче — ей не место в репо‑заметках.

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

Ошибки, из‑за которых заметки устаревают

Заметки быстро устаревают, когда они описывают привычки одного человека вместо реального рабочего процесса команды. Такое случается часто. Кто‑то пишет напоминание своей аббревиатурой, и всем остальным приходится догадываться.

Заметка вроде use the usual review prompt понятна только автору. Она не поможет новому сотруднику, подрядчику или даже тому же автору через три месяца. Если заметка зависит от приватного контекста из Slack, памяти или совещания — она уже слишком слабая.

Старые команды — ещё одна частая проблема. Команды меняют менеджеры пакетов, переименовывают скрипты, перемещают папки или заменяют один AI‑инструмент другим. Заметка остается и продолжает велеть запускать нерабочие команды.

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

Файлы также устаревают, когда в них смешивают стабильные правила, временные задачи и старую историю решений. Всё это должно храниться в разных инструментах. Репо‑заметка должна говорить, что делать сейчас, когда кто‑то снова трогает код.

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

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

Лучшее правило простое: пишите заметку после того, как задача повторилась и команда согласовала правильный способ делать её.

Признаки устаревшей заметки:

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

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

Бычек‑чеклист перед коммитом заметок

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

Короткая проверка перед коммитом спасёт в будущем и сохранит заметки полезными.

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

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

Простой тест хорош: попросите одного человека, не писавшего заметку, воспользоваться ею. Если он остановится с вопросами вроде Which service is this for? или Does this path still exist? — заметка нуждается в доработке. Не нужно идеальных формулировок. Нужны рабочие указания.

Это также помогает с устаревшей историей задач. Репозитории часто собирают строки вроде temporary workaround for last month's deploy issue или keep this until migration ends. Такие строки быстро устаревают. Если заметка не помогает кому‑то выполнить повторяющуюся задачу сейчас — удалите её или переместите туда, где хранится проектная история.

Хорошие заметки просты. Они говорят, что сделать, где сделать и как понять, что всё получилось.

Что делать дальше

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

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

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

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

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

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

Если ваша команда хочет помощи в проектировании такой системы, Oleg Sotnikov at oleg.is консультирует стартапы и небольшие команды по практичным AI‑первым инженерным рабочим процессам. Это может включать в себя, где должны жить репо‑заметки, как они вписываются в код‑ревью и автоматизацию, и как сделать их достаточно короткими, чтобы люди действительно ими пользовались.

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