Как написать AGENTS.md для ИИ-агента в проекте
AGENTS.md полезен не как длинное описание всего репозитория, а как короткая рабочая инструкция. Агенту нужны точные команды, расположение важных частей проекта, локальные правила и ясные ограничения. Общие фразы вроде делай качественно не заменяют проверяемых требований.
Что учесть до начала работы
Не копируйте секреты, внутренние адреса и production-доступ в файл инструкций.
Не обещайте команды проверки, которых нет в репозитории или документации проекта.
Что подготовить
Что делать
Определите область действия
Укажите, к какой папке относится файл и есть ли вложенные инструкции. Коротко опишите назначение проекта и не повторяйте документацию, которая уже доступна в репозитории.
Результат: Понятно, где действуют правила и какой результат создает проект.Запишите точные команды
Добавьте команды установки, локального запуска, сборки, lint, проверки типов и тестов. Отделите обязательные проверки от долгих или требующих внешнего сервиса.
Результат: Агент может воспроизвести принятый цикл проверки без подбора команд наугад.Опишите карту проекта
Назовите каталоги исходного кода, тестов, схем, миграций и статических файлов. Для необычной архитектуры поясните направление зависимостей и место для нового кода.
Результат: Изменение попадает в правильный модуль и не дублирует существующую структуру.Зафиксируйте локальные правила
Перечислите принятый стиль, способ обработки ошибок, требования к типам, тестам и именованию. Ссылайтесь на конфигурацию форматтера и линтера, если она является источником правила.
Результат: Правила сформулированы как конкретные ограничения, а не вкусовые пожелания.Ограничьте опасные действия
Явно запретите удаление данных, изменение секретов, production-конфигурации, аналитики и чужих файлов без отдельного запроса. Укажите, когда нужно остановиться и запросить решение.
Результат: Потенциально необратимые действия не считаются обычной частью задачи.Задайте формат завершения
Попросите перечислять измененные файлы, выполненные проверки, известные ограничения и действия, которые не удалось проверить. Не требуйте заявления об успехе без вывода команды.
Результат: Отчет можно сопоставить с diff и журналом проверок.Промпт для черновика AGENTS.md
Подготовь черновик AGENTS.md только по подтвержденным данным ниже. Не придумывай команды, пути и правила. Не добавляй секреты, внутренние адреса и production-доступ. Если сведений не хватает, вставь пометку НУЖНО УТОЧНИТЬ. Назначение проекта: [описание]. Область действия файла: [папка]. Структура: [каталоги и их роли]. Команды установки и запуска: [команды]. Обязательные проверки: [lint, typecheck, тесты, сборка]. Правила кода: [подтвержденные правила]. Запрещенные изменения: [список]. Когда остановиться и спросить: [условия]. Формат отчета: [требования]. Верни компактный Markdown с разделами: область действия, структура, команды, правила изменений, проверки, запреты и отчет. После черновика отдельно перечисли все пометки НУЖНО УТОЧНИТЬ.
Проверка файла инструкций
Что чаще всего портит результат
Копировать весь README
Оставьте только сведения, которые меняют способ работы агента в этой папке.
Писать расплывчатые требования
Замените сделай хорошо на конкретную команду или критерий приемки.
Смешивать правила разных частей монорепозитория
Используйте вложенный AGENTS.md для каталога со своим стеком и командами.
Короткие ответы
Нужно ли перечислять каждый файл проекта?
Нет. Достаточно каталогов и необычных точек входа, которые помогают выбрать правильное место для изменения.
Можно ли хранить команды с токенами в AGENTS.md?
Нет. Укажите имя переменной окружения и безопасный способ получения значения, но не само значение.
AGENTS.md как исполняемая карта правил репозитория
Инструкция агенту должна быть короткой картой обязательных действий, границ и проверок, а не энциклопедией проекта. Начните с области действия файла, команд сборки, допустимых изменений и запретов. Локальные инструкции уточняют корневые, поэтому противоречия устраняют до запуска задачи.
До начала заведите контрольную таблицу: идентификатор материала, версия входа, владелец, обязательный результат, доказательство, статус и дата. Для каждой ручной правки записывайте причину, а промежуточные файлы называйте так, чтобы нельзя было перепутать черновик и принятую версию. Правило остановки тоже задается заранее: критичная ошибка в факте, правах, данных, формате или воспроизводимости возвращает работу на соответствующий этап. После приемки попросите коллегу повторить одну ключевую проверку только по переданному комплекту. Если ему нужна история личного чата или устное пояснение автора, передача еще не завершена. Такой журнал нужен не ради формальности: он показывает реальную стоимость исправлений, не дает потерять ограничение при следующем обновлении и помогает расследовать расхождение без повторения всей работы.
Критерии, которые нужно записать до начала
Контрольный сценарий от входа до приемки
Начать с критерия приемки
До выбора инструмента опишите, каким должен быть корневой AGENTS.md, обоснованные локальные дополнения, журнал источников правил, тестовый сценарий, список владельцев и дату пересмотра. Укажите обязательные поля, допустимые отклонения, ответственного и срок. Затем подготовьте структуру репозитория, действующие команды, CI, правила стиля, опасные операции, владельцев подсистем, требования к тестам, секретам, сгенерированным файлам, публикации и локальным инструкциям, не смешивая рабочие факты с демонстрационными примерами.
Проверить сложный случай первым
Сначала выполните сбор реальных правил у владельцев, разделение обязательного и рекомендательного, запись проверяемых команд, указание области действия, создание локальных файлов только при необходимости и пробный проход на типовой задаче на фрагменте с наибольшим риском ошибки. Это быстрее выявит непригодный процесс, чем аккуратный простой пример. Сохраните запрос, настройки, ответ и все ручные исправления.
Провести независимую сверку
Передайте другому участнику однозначность запретов, существование путей и команд, соответствие CI, отсутствие секретов, порядок генерации, требования к грязному дереву, процедуру миграций, область локальных правил и понятность критерия готовности. Не подсказывайте, где находится ошибка: процедура должна сама привести его к исходному доказательству. Зафиксируйте время сверки и причины всех расхождений.
Закрыть работу передачей
Соберите корневой AGENTS.md, обоснованные локальные дополнения, журнал источников правил, тестовый сценарий, список владельцев и дату пересмотра, добавьте журнал решений и перечислите открытые вопросы. Получатель должен понимать, что принято, что исключено и в каких условиях результат нельзя использовать без новой проверки.
Ошибка, из-за которой результат выглядит надежнее, чем есть
Частая ошибка - копировать общий шаблон с несуществующими командами или писать тестируй тщательно без списка проверок. Агент либо теряет время, либо объявляет работу готовой слишком рано. Прогоните инструкцию на реальном небольшом изменении.
Граница применимости
AGENTS.md не заменяет права доступа, CI и защиту веток. Слишком подробный файл быстро устаревает, а расплывчатый оставляет опасные решения модели. Изменение процесса требует синхронного обновления инструкции.
Что передать следующему участнику
Команда получает файл в репозитории, владельца пересмотра и ссылку на более подробную документацию. При смене сборки или публикации обновление AGENTS.md входит в критерий готовности процесса.
Коротко
Хороший AGENTS.md сокращает неопределенность: он говорит, где работать, чем проверять результат и чего не касаться. Короткие подтвержденные правила полезнее длинного файла с догадками.