Лучшие правила настройки ИИ-помощника под свой проект
Шесть правил, которые превращают ИИ-помощника из общего инструмента в участника именно вашего проекта: файл правил в репозитории, команды самопроверки, границы и секреты, эталонные примеры вместо описаний стиля, короткие живые правила и договорённость с командой. Разбираем, что писать, где хранить и как поддерживать, чтобы правила работали, а не лежали.
Почему помощник без настройки работает хуже, чем мог бы
Модель знает мир, но не знает ваш проект. Каждая сессия начинается с нуля: помощник не помнит, что ошибки у вас оборачиваются в общий тип, что миграции пишутся только через генератор, что папку с устаревшим кодом трогать нельзя, а тесты запускаются одной конкретной командой. Без этих знаний он подставляет самое распространённое решение из своего опыта и делает это уверенно. Отсюда лишние зависимости, второй способ делать то, что уже делается, и правки, которые приходится откатывать.
Хорошая новость: почти у всех инструментов есть одно и то же средство — файл с правилами в репозитории, который помощник читает в начале работы. У Claude Code это CLAUDE.md, у Codex CLI — AGENTS.md, у Gemini CLI — GEMINI.md, у GitHub Copilot — файл инструкций, у редакторов с ИИ — свои файлы правил. Имена разные, содержание одно, и именно содержание мы разбираем ниже. Порядок в списке — по отдаче на час вложенного времени.
Сквозная мысль та же, что и во всех наших материалах об агентах: помощник ускоряет работу, а отвечает за код человек. Правила нужны не для того, чтобы агенту доверять больше, а для того, чтобы проверять его меньше по мелочам и внимательнее — по существу.
Лучшие правила настройки ИИ-помощника под свой проект
Файл правил в репозитории
один файл в корне, который помощник читает в начале каждой сессии
Самое дешёвое и самое сильное действие. В корень репозитория кладётся файл с правилами проекта, и с этого момента каждая сессия помощника начинается не с нуля, а с того, что вы записали. Что туда писать: два предложения о том, что это за проект; стек и его версии на словах; структура — где лежат модели, обработчики, тесты, миграции; как собрать и запустить; соглашения об ошибках, логировании и именовании; чего не делать. Не больше страницы для начала.
Почему на первом месте. Всё остальное в списке — команды проверки, границы, примеры — живёт в этом же файле или ссылается на него. Он версионируется вместе с кодом, проходит ревью как код и достаётся каждому в команде вместе с репозиторием, а не остаётся в личных настройках одного человека. По сути, это один из документов, без которых проект тонет, только читает его в первую очередь не человек, а помощник.
Минусы. Файл требует поддержки: устаревшее правило вредит сильнее отсутствующего, потому что помощник ему верит. У разных инструментов разные имена файлов, и при нескольких помощниках приходится либо дублировать, либо держать один общий файл и ссылаться на него из остальных. Соблазн переписать туда весь README велик, а длинный файл помощник читает так же плохо, как человек.
- Полчаса на первую версию
- Версионируется и ревьюится как код
- Общий для всей команды
- Устаревшее правило вредит
- Разные инструменты — разные имена файлов
- Легко раздуть до бесполезности
самое сильное правило, потому что все остальные живут внутри него · оценка 9,6
Команды самопроверки
сборка, тесты, линтер и типы — точными командами, с требованием запускать после каждого шага
Помощник, который знает команду запуска тестов, проверяет себя сам; помощник, который её не знает, докладывает «готово» по ощущениям. В файл правил записываются точные команды: как собрать, как прогнать тесты целиком и как — быстрый набор, как запустить линтер и проверку типов. Рядом — требование: после каждого изменения запускать проверку, и правило про падающий тест: объяснить расхождение и ждать решения, а не подгонять ожидание под результат.
Почему второе место. Это единственная проверка, которую помощник не может «убедить». Агенты с замкнутым циклом — написал, запустил, исправил — на проекте с быстрыми тестами работают заметно лучше именно потому, что получают честный сигнал. У Claude Code линтер можно запускать автоматически через хуки после каждой правки файла; у остальных достаточно требования в правилах. Финальная граница — та же проверка в CI, где помощника уже нет.
Минусы. Медленный набор тестов помощник начнёт пропускать, как и человек, — нужен быстрый поднабор для шагов и полный для финала. Нестабильные тесты учат его игнорировать падения. Если тестов нет, правило не работает, и первым делом придётся их завести. И зелёный прогон по-прежнему не заменяет чтение diff.
- Объективный сигнал вместо доклада
- Замкнутый цикл без участия человека
- Настраивается один раз
- Медленные тесты пропускаются
- Нестабильные тесты обесценивают правило
- Без тестов не работает вовсе
правило, которое даёт помощнику честный критерий, а вам — фильтр без усталости · оценка 9,4
Границы и секреты
что помощник не трогает, куда не ходит и чего не видит
Явный список запретов работает лучше общих слов об осторожности. Что обычно попадает в него: папки, которые не редактируются, — применённые миграции, сгенерированный код, сторонние библиотеки; действия, которые не выполняются без вопроса, — добавление зависимостей, удаление тестов, принудительная отправка в git, любые команды с боевыми системами; и то, чего помощник не должен видеть, — файлы с ключами, выгрузки данных, личные заметки. У большинства инструментов есть способ исключить файлы из чтения и ограничить список разрешённых команд.
Почему это отдельное правило. Помощник ищет самый короткий путь к задаче, и иногда он лежит через то, что нельзя трогать. Записанная граница останавливает его там, где здравый смысл человека сработал бы автоматически. А секреты — единственное, что не восстанавливается откатом: процитированный в ответе токен уже утёк.
Минусы. Границы воспринимаются как трение, и их отключают «на минуту». Список запретов легко забыть обновить при появлении нового секрета или новой папки. Исключение файлов не защищает от ключей в переменных окружения той сессии, где работает помощник, — их нужно убирать из окружения, а не из файла правил. И граница в тексте — это просьба, а не замок: настоящие ограничения задаются правами пользователя и песочницей.
- Останавливает короткий путь через запретное
- Защищает то, что не откатывается
- Есть средства исключения и списки команд
- Воспринимается как трение
- Забывают обновлять
- Текст не заменяет права и песочницу
правило, без которого удобство помощника оборачивается доступом к тому, чего нельзя терять · оценка 9,2
Эталонные примеры вместо описаний стиля
покажите модуль, который сделан правильно, вместо прилагательных
«Пиши чистый, читаемый код в стиле проекта» не значит ничего: у помощника своё представление о чистоте. Работает другое: «обработчики делай как в файле с обработчиком заказов, обработку ошибок — как в модуле платежей, тесты — как в тестах на корзину». Модели повторяют образец гораздо точнее, чем следуют описанию, и один хорошо выбранный файл заменяет страницу правил о стиле. Принципы читаемого кода мы собирали в подборке правил, чтобы ваш код читали; здесь важно, что помощнику их нужно показывать, а не рассказывать.
Почему это работает. Пример содержит всё сразу: структуру, именование, обработку ошибок, стиль тестов, границы модуля. Описать это словами длиннее и хуже. К тому же пример уже прошёл ревью, а значит, отражает не мнение одного человека, а договорённость команды.
Минусы. Эталон становится шаблоном, и плохо выбранный пример размножит свои недостатки по всему проекту. После рефакторинга ссылка указывает на устаревший или несуществующий файл. Один пример не покрывает все случаи: для нового типа задачи придётся выбрать новый эталон, и кто-то должен за этим следить.
- Точнее любого описания
- Один файл вместо страницы правил
- Отражает договорённость команды
- Плохой эталон размножается
- Устаревает после рефакторинга
- Не покрывает новые типы задач
правило, которое заменяет спор о стиле ссылкой на файл · оценка 8,9
Короткие живые правила
файл, который читают, а не файл, который есть
Через пару месяцев файл правил превращается в летопись инцидентов: каждая ошибка помощника добавляла строку, ни одна не убиралась. В длинном файле важное тонет в шуме, правила начинают противоречить друг другу, а помощник, как и человек, выполняет из него то, что ближе к началу. Работающий файл короткий, и каждое правило в нём заслужило место реальной ошибкой, которая повторялась.
Как поддерживать. Правило записывается в форме «замечено — делай так»: не «будь аккуратен с датами», а «даты храним в UTC, преобразуем на выходе, смотри модуль отчётов». Раз в месяц или после серии ошибок файл перечитывается: правила, которые давно не срабатывали, убираются; противоречия разрешаются; примеры проверяются на существование. У файла есть владелец — иначе его не будет ни у кого.
Минусы. Это единственное правило из списка, которое требует постоянной дисциплины, а не разовой настройки. Соблазн записать всё «на всякий случай» велик, и удалять правила психологически труднее, чем добавлять. Без владельца файл деградирует за квартал.
- Короткий файл действительно читают
- Каждое правило заслужено ошибкой
- Форма «замечено — делай так» понятна
- Постоянная дисциплина, не разовая настройка
- Удалять труднее, чем добавлять
- Нужен владелец
правило про поддержку, без которого первое правило перестаёт работать за квартал · оценка 8,7
Договорённость с командой о процессе
кто отвечает за код помощника, как его помечают и как ревьюят
Настройка инструмента не заменяет договорённости между людьми. Команде нужно решить несколько вещей вслух: автор отвечает за код, написанный помощником, так же, как за свой, и «это агент так сделал» не аргумент на ревью; ревью кода от помощника не мягче обычного, а скорее строже; помечать ли в описании pull request, что использовался агент, — решает команда, но одинаково для всех; где живёт файл правил и кто его меняет; какие инструменты разрешены и какой код и данные можно отправлять во внешние сервисы, а какие — нет.
Почему это последнее по порядку, но не по важности. Без договорённости правила из файла — мнение того, кто их написал. С ней они становятся частью процесса: их обновляют на ретроспективах, на них ссылаются в ревью, новичок получает их в первый день. Отдельный пункт — данные: код заказчика, персональные данные пользователей и выгрузки из боевых баз не попадают в сторонние сервисы ни в каком виде, и это лучше записать до первого инцидента.
Минусы. Требует встречи и, что труднее, соблюдения. Правила безопасности компании могут отставать от практики команды, и тогда договорённость приходится согласовывать. При смене состава её нужно проговаривать заново. И никакая договорённость не сработает, если код помощника в pull request по факту читают менее внимательно, чем человеческий.
- Правила становятся процессом, а не мнением
- Ответственность названа явно
- Политика по данным записана заранее
- Нужна встреча и соблюдение
- Политики безопасности могут отставать
- При смене состава проговаривать заново
правило, которое превращает файл в репозитории в договорённость между людьми · оценка 8,5
Сравнение по главному
| Правило | Где живёт | Что меняет в работе помощника |
|---|---|---|
| Файл правил в репозитории | корень репозитория, под версионированием | сессия начинается с контекста проекта |
| Команды самопроверки | файл правил, хуки, CI | проверяет себя сам, докладывает по факту |
| Границы и секреты | файл правил, исключения, права | не идёт коротким путём через запретное |
| Эталонные примеры | ссылки на файлы проекта | повторяет образец, а не своё представление |
| Короткие живые правила | ревизия файла, владелец | важное не тонет в шуме |
| Договорённость с командой | ретроспективы, описание процесса | правила читают и обновляют люди |
С чего начать, если правил ещё нет
Первый день — десять строк. Что за проект, стек, где что лежит, как собрать, как запустить тесты, чего не трогать. Не пытайтесь описать всё: файл вырастет сам из реальных ошибок.
Первая неделя — команды и границы. Добавьте точные команды тестов, линтера и проверки типов с требованием запускать после каждого шага. Запишите список запретов: папки, действия, файлы. Уберите ключи из окружения, в котором работает помощник.
Первый эталон. Выберите один модуль, который команда считает образцовым, и один файл тестов. Сошлитесь на них в правилах вместо описания стиля. Если такого модуля нет, это повод его сделать — он пригодится и людям.
Первая ревизия. Через две недели перечитайте файл вместе с командой: что сработало, что помощник продолжает делать неправильно, какие правила ни разу не понадобились. Заодно договоритесь, кто владеет файлом и как помечается код помощника в pull request.
Не ждите, что правила отменят чтение. Хорошо настроенный помощник ошибается реже и по существу, а не по мелочам. Читать его diff всё равно нужно, просто теперь на это уходит внимание, а не раздражение.
Частые вопросы
Один файл правил для всех инструментов или отдельный на каждый?
Содержание одно, поэтому разумно держать один общий файл, а инструменто-зависимые файлы делать короткими и ссылаться из них на общий. Дублирование приводит к тому, что правила расходятся и помощники ведут себя по-разному. Если команда пользуется одним инструментом, вопрос снимается сам.
Насколько длинным должен быть файл правил?
Таким, чтобы человек прочитал его за пару минут: обычно это страница или меньше. Подробности выносятся в отдельные документы, на которые файл ссылается, — описание архитектуры, регламент миграций, эталонные модули. Если файл растёт быстрее, чем из него удаляют, правила перестают работать.
Помощник игнорирует правило. Что делать?
Сначала проверить, что правило однозначно и не спорит с другим: «будь аккуратен» игнорируется всегда, «не добавляй зависимости без вопроса» — почти никогда. Затем переместить его ближе к началу файла и добавить пример. Если правило про безопасность, текстом его не закрыть — нужны права, исключение файлов или песочница.
Нужно ли помечать в pull request, что код написал агент?
Это решает команда, и главное — решить одинаково для всех. Пометка помогает ревьюеру понять, на что смотреть внимательнее: побочные правки, выдуманные API, избыточные заглушки. Но ответственность за код от пометки не меняется: за него отвечает автор pull request, а не инструмент.
Итог
Начните с файла правил в корне репозитория и команд самопроверки — это два действия на час, которые меняют работу помощника сильнее всего. Затем границы и секреты: они защищают то, что не восстанавливается. Эталонные примеры заменят споры о стиле, а короткие живые правила и договорённость с командой не дадут всему этому протухнуть за квартал.
Ни одно из правил не отменяет главного: помощник ускоряет работу, а отвечает за результат человек. Настройка нужна не для того, чтобы читать меньше, а для того, чтобы читать по существу.
Комментарии
0Будьте первым, кто ответит автору.