К содержимому
Блог

CLAUDE.md и AGENTS.md: что писать в инструкциях агенту

CLAUDE.md и AGENTS.md: что писать в инструкциях агенту

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

Коротко

  • В начале держат запреты, секреты, опасные операции и критерии остановки.

  • Команды и пути пишут дословно, а не в виде пожеланий о качестве.

  • Изменение процесса обновляет инструкцию в том же pull request.

Что действительно нужно агенту

Агенту нужны границы. Укажите каталоги, которые нельзя менять без явного разрешения, команды для адресной проверки, формат коммита, путь к схеме или контракту и условия, при которых работа останавливается. Если команда требует доступ владельца или секрет, напишите это прямо.

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

Настройку самого клиента смотрите в документации Claude Code. Если команда использует несколько агентов, отдельные профили и доступы описывают по инструкции Codex, а ключи не записывают в файлы инструкций.

Из чего собрать CLAUDE.md или AGENTS.md

Рабочая структура может быть короткой:

  1. Критические запреты и данные, которые не открывают.

  2. Разрешённая область изменения и владельцы смежных модулей.

  3. Точные команды проверки с ограничениями нагрузки.

  4. Правила ветки, коммита и ревью.

  5. Внешние действия, для которых требуется подтверждение.

  6. Короткий список ссылок на подробные документы.

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

Что лучше убрать

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

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

Как проверить соблюдение инструкции

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

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

Когда обновлять инструкции вместе с кодом

Инструкция меняется вместе с процессом. Новый способ выпуска, новая команда проверки или перенос каталога должны попасть в тот же pull request. На ревью спросите: этот дифф меняет порядок работы агента? Если да, ссылка на обновление CLAUDE.md или AGENTS.md должна быть частью задачи.

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

Минимальный тест для инструкции

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

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

Как разрешать конфликты правил

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

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

Нужны ли оба файла одновременно?

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

Как писать правило о секретах?

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

Нужно ли описывать стиль кода словами?

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

Создать отдельный ключ Relay

Готовы подключиться?Войдите в консоль, пополните баланс и создайте API-ключ.