Как написать 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 как исполняемая карта правил репозитория
Маршрут: AGENTS.md как исполняемая карта правил репозитория
Начать с критерия приемки
До выбора инструмента опишите, каким должен быть корневой AGENTS.md, обоснованные локальные дополнения, журнал источников правил, тестовый сценарий, список владельцев и дату пересмотра. Укажите обязательные поля, допустимые отклонения, ответственного и срок. Затем подготовьте структуру репозитория, действующие команды, CI, правила стиля, опасные операции, владельцев подсистем, требования к тестам, секретам, сгенерированным файлам, публикации и локальным инструкциям, не смешивая рабочие факты с демонстрационными примерами.
Проверить сложный случай первым
Сначала выполните сбор реальных правил у владельцев, разделение обязательного и рекомендательного, запись проверяемых команд, указание области действия, создание локальных файлов только при необходимости и пробный проход на типовой задаче на фрагменте с наибольшим риском ошибки. Это быстрее выявит непригодный процесс, чем аккуратный простой пример. Сохраните запрос, настройки, ответ и все ручные исправления.
Провести независимую сверку
Передайте другому участнику однозначность запретов, существование путей и команд, соответствие CI, отсутствие секретов, порядок генерации, требования к грязному дереву, процедуру миграций, область локальных правил и понятность критерия готовности. Не подсказывайте, где находится ошибка: процедура должна сама привести его к исходному доказательству. Зафиксируйте время сверки и причины всех расхождений.
Закрыть работу передачей
Соберите корневой AGENTS.md, обоснованные локальные дополнения, журнал источников правил, тестовый сценарий, список владельцев и дату пересмотра, добавьте журнал решений и перечислите открытые вопросы. Получатель должен понимать, что принято, что исключено и в каких условиях результат нельзя использовать без новой проверки.
Риск ошибки: AGENTS.md как исполняемая карта правил репозитория
Частая ошибка - копировать общий шаблон с несуществующими командами или писать тестируй тщательно без списка проверок. Агент либо теряет время, либо объявляет работу готовой слишком рано. Прогоните инструкцию на реальном небольшом изменении.
Ограничения: AGENTS.md как исполняемая карта правил репозитория
AGENTS.md не заменяет права доступа, CI и защиту веток. Слишком подробный файл быстро устаревает, а расплывчатый оставляет опасные решения модели. Изменение процесса требует синхронного обновления инструкции.
Передача результата: AGENTS.md как исполняемая карта правил репозитория
Команда получает файл в репозитории, владельца пересмотра и ссылку на более подробную документацию. При смене сборки или публикации обновление AGENTS.md входит в критерий готовности процесса.
Коротко
Хороший AGENTS.md сокращает неопределенность: он говорит, где работать, чем проверять результат и чего не касаться. Короткие подтвержденные правила полезнее длинного файла с догадками.