CLAUDE.md и AGENTS.md: что писать в инструкциях агенту
CLAUDE.md и AGENTS.md полезны, когда они снимают конкретную неопределённость: какую команду запустить, что нельзя менять, где лежит контракт и когда остановиться. Файл с общими пожеланиями агент прочитает, но это не даст проверяемого результата. Хорошая инструкция похожа на короткий рабочий протокол.
Коротко
В начале держат запреты, секреты, опасные операции и критерии остановки.
Команды и пути пишут дословно, а не в виде пожеланий о качестве.
Изменение процесса обновляет инструкцию в том же pull request.
Что действительно нужно агенту
Агенту нужны границы. Укажите каталоги, которые нельзя менять без явного разрешения, команды для адресной проверки, формат коммита, путь к схеме или контракту и условия, при которых работа останавливается. Если команда требует доступ владельца или секрет, напишите это прямо.
Полезны правила для неочевидных исключений. Линтер способен описать форматирование лучше текста, а вот причина странного условия или запрет на трогание миграционного снимка часто видны только тем, кто знает историю проекта. Один короткий факт здесь ценнее страницы принципов.
Настройку самого клиента смотрите в документации Claude Code. Если команда использует несколько агентов, отдельные профили и доступы описывают по инструкции Codex, а ключи не записывают в файлы инструкций.
Из чего собрать CLAUDE.md или AGENTS.md
Рабочая структура может быть короткой:
Критические запреты и данные, которые не открывают.
Разрешённая область изменения и владельцы смежных модулей.
Точные команды проверки с ограничениями нагрузки.
Правила ветки, коммита и ревью.
Внешние действия, для которых требуется подтверждение.
Короткий список ссылок на подробные документы.
Пункты должны отвечать на вопрос «что сделать». Вместо «следите за безопасностью» напишите «не печатайте секрет в вывод команды». Вместо «тестируйте изменения» укажите, какой адресный набор запускать и что считать провалом. Конкретику можно проверить после работы.
Что лучше убрать
Не дублируйте то, что надёжно проверяет конфигурация проекта. Не переносите в файл историю каждой архитектурной дискуссии. Не добавляйте десятки одинаковых запретов разными словами. Такие строки занимают контекст и прячут правила, которые действительно меняют действие агента.
Не кладите туда ключи, пароли, адреса внутренних сервисов и личные контакты. Инструкция часто попадает в историю Git и читается многими инструментами. Для интеграций Relay используйте отдельный ключ на приложение, а его параметры храните в кабинете.
Как проверить соблюдение инструкции
Возьмите одно новое правило с ясной проверкой. Например, запретить запускать полную тестовую матрицу без причины или потребовать записывать путь к контракту в описании изменения. Дайте агенту обычную задачу и посмотрите на фактические команды и дифф.
Нарушение обычно говорит об одной из двух проблем: правило не описывает действие или документ перегружен. Сначала сократите и переформулируйте. Добавить ещё пять абзацев проще, чем исправить текст, но читателю от этого хуже.
Когда обновлять инструкции вместе с кодом
Инструкция меняется вместе с процессом. Новый способ выпуска, новая команда проверки или перенос каталога должны попасть в тот же pull request. На ревью спросите: этот дифф меняет порядок работы агента? Если да, ссылка на обновление CLAUDE.md или AGENTS.md должна быть частью задачи.
Раз в квартал полезен короткий проход: удалите закрытые миграции, проверьте команды, замените битые ссылки, перенесите длинные пояснения в профильную документацию. Станет меньше текста, а не больше. Это хороший результат.
Минимальный тест для инструкции
Создайте задачу, в которой правило действительно должно сработать. Если файл требует адресную проверку, попросите внести маленькую правку и проверьте, какую команду агент выбрал. Если он должен остановиться перед внешним действием, дайте задачу с публикацией или удалением и посмотрите, запросил ли подтверждение.
Тест не должен зависеть от секретов и платной инфраструктуры. Его цель показать связь между строкой инструкции и наблюдаемым результатом. Результат стоит зафиксировать рядом с правилом, если его сложно воспроизвести без контекста команды.
Как разрешать конфликты правил
Инструкции иногда расходятся с текущим кодом или с новым требованием владельца. В таком случае не добавляйте третью противоречивую фразу. Укажите источник правды, обновите старое правило и зафиксируйте решение в одном месте. Агенту важнее ясный приоритет, чем полный архив обсуждений.
Если конфликт нельзя разрешить без владельца, инструкция должна требовать остановки и кратко назвать вопрос. Это защищает от ситуации, где агент выбирает удобную трактовку и коммитит решение, на которое у него не было полномочий.
Нужны ли оба файла одновременно?
Это зависит от клиента и договорённостей команды. Не копируйте содержимое автоматически. Выберите один источник для общих правил или чётко разделите области. Иначе два похожих файла разойдутся, а агент получит конфликтующие инструкции в одной задаче.
Как писать правило о секретах?
Назовите действие и границу: не открывать файл, не печатать значение, не добавлять его в Git и остановиться, если доступ нужен для продолжения. Не вставляйте в пример настоящий формат ключа. Ссылки на хранилище секретов дают отдельно, с нужными правами.
Нужно ли описывать стиль кода словами?
Только если правило не может выразить линтер или форматтер. Конфигурация инструмента остаётся источником правды для обычного стиля. В инструкцию добавляйте исключения, структуру модулей и договорённости, которые нельзя вывести из исходников автоматически.