agents-md

Навык Sentry agents-md посвящён созданию и поддержке коротких инструкций для coding agents в файлах AGENTS.md и CLAUDE.md. Его цель — оставить в репозитории только actionable-правила, реальные команды и корректную область действия. Источник задаёт ориентир: файл должен занимать меньше 60 строк и ни при каких обстоятельствах не превышать 100. Это не приглашение переписать всю документацию проекта; навык предлагает добавлять только разделы, которые дают неочевидную пользу агенту. Работа начинается с осмотра репозитория до записи. Нужно проверить менеджер пакетов, lock-файлы и манифесты, затем найти реальные команды в package.json, Makefile, task runner и CI. После этого просматриваются README.md, CONTRIBUTING.md, docs, specs, policies, SECURITY.md и .github, а также текущие паттерны кода, тестовая структура, generated-файлы и устаревшие области, которые лучше не трогать. Такой порядок нужен, чтобы AGENTS.md ссылался на существующие правила и команды, а не закреплял догадки. Следующий выбор — область действия. Корневой AGENTS.md задаёт правила для всего репозитория; вложенный файл нужен только поддереву с действительно отличающимися командами или ограничениями. Побеждает ближайший файл инструкций, поэтому узкий документ должен быть короче корневого и не дублировать его целиком. Писать следует минимальный полезный файл, а затем проверить, что каждый указанный путь и команда существуют. Для Claude-compatible entrypoint источник рекомендует создать AGENTS.md в корне и сделать CLAUDE.md символической ссылкой на него, чтобы две копии не расходились. В качестве возможных разделов предлагаются package manager, команды, внешние ссылки и ключевые конвенции. Команды удобно показывать таблицей, если их больше одной: отдельные строки для теста и линтера должны содержать точные пути и исполняемые команды. Во внешних ссылках нужно указывать конкретные документы для setup, архитектуры, API, security, release и policy, если такие файлы уже есть. Для generated-файлов следует написать существующую команду генерации и запретить ручное редактирование, но не пересказывать весь процесс сборки. Правила написания намеренно сдержанные: использовать заголовки, списки и таблицы вместо длинных абзацев; один пункт — одно правило; не повторять конфигурацию линтера, форматтера или typechecker; не перечислять установленные skills и plugins; не добавлять общие лозунги о качестве. Объяснение причины нужно только там, где оно предотвращает вероятную ошибку. Нежелательны приветствия, заключения, welcome-текст, дубли README, расплывчатые ссылки вроде see docs и вложенные AGENTS.md, повторяющие корневой файл. Практический сценарий — перед изменением репозитория обновить инструкцию по фактам, сохранить небольшое число точных правил и проверить, что агент сможет найти команды и документы без чтения лишней копии. Ограничение навыка состоит в том, что он не анализирует сам проект автоматически и не решает за владельца, какие правила действительно нужны: список файлов и команд всё равно надо сверить с текущим состоянием. Если в проекте нет соответствующего CLAUDE.md, отдельная копия не требуется; источник предостерегает именно от divergent-версий.