# AI Agents Md Maintenance > Используй, когда нужно создать, изменить или стабилизировать `AGENTS.md` и соседние машинные инструкции без конфликтов и лишней нагрузки на контекст. - Skill: `mekras/ai-agents-md-maintenance` (Agent Skill, multi-file: 7 files) - Install (CLI): `npx skillmds@latest add mekras/ai-agents-md-maintenance` - Raw SKILL.md: https://api.skillmd.com/api/skills/mekras/ai-agents-md-maintenance/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: mekras (https://skillmd.com/u/mekras) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/mekras/ai-agents-md-maintenance --- # Навык: сопровождение AGENTS.md Перед существенной правкой источника истины получи `ai-work-control/full`; используй переданные границы и не повторяй контроль. Используй этот навык для создания и изменения `AGENTS.md` как основной машинной точки входа в проект и для согласования соседних instruction-файлов, которые читает конкретная обвязка, например `CLAUDE.md`. Цель — получить инструкции, которые агент сможет стабильно применить в реальной задаче: понять область действия, выбрать правильные команды, не нарушить границы проекта и не потратить лишний контекст. ## Когда применять Применяй навык, если нужно: - создать новый `AGENTS.md`; - добавить или обновить `CLAUDE.md` и другие соседние instruction-файлы, если они нужны конкретной обвязке и должны ссылаться на `AGENTS.md`; - изменить существующий `AGENTS.md` после изменения структуры, команд, инструментов, процесса разработки или правил проекта; - сократить перегруженный `AGENTS.md`; - разделить один файл на корневой и вложенные инструкции; - устранить конфликт между несколькими файлами инструкций; - повысить стабильность применения инструкций после провала агента; - подготовить содержательное изменение, которое затем должен проверить `ai-audit-agents-md`. Не применяй навык для чистой проверки без редактирования. Для этого используй `ai-audit-agents-md`. ## Границы - Создание, изменение и сопровождение `AGENTS.md` остаются в одном навыке, потому что используют один рабочий цикл: определить цепочку инструкций, область действия, содержание, конфликты и проверку результата. - Проверка остаётся отдельным навыком `ai-audit-agents-md`, потому что у неё другой выход: независимый отчёт о проблемах, а не изменение файлов. - После существенного изменения `AGENTS.md` инициируй `ai-audit-agents-md` как контрольный этап. ## Обязательный порядок 1. Собери контур инструкций: все `AGENTS.md`, `AGENTS.override.md`, `CLAUDE.md` и соседние файлы инструкций, которые могут участвовать в цепочке. 2. Определи задачу изменения: какое поведение агента должно измениться, какой риск закрывается и в каком файле должно жить правило. 3. Определи, читает ли используемая обвязка не только `AGENTS.md`. Если да, не дублируй правила вручную без причины: предпочитай тонкую связку с `AGENTS.md`, например файл `CLAUDE.md` с текстом `@AGENTS.md` или символьную ссылку `CLAUDE.md -> AGENTS.md`, если это допустимо в проекте. Если используется несколько instruction-файлов одновременно, явно снижай риск конфликтов и не полагайся на стабильный порядок их слияния. 4. Раздели уровни: корневой `AGENTS.md`, вложенные инструкции, профильные навыки, README и справочные документы. 5. Оставь в `AGENTS.md` только операционные указания: команды, ограничения, Git-правила, проектные соглашения, условия применения и форматы результата. 6. При создании или содержательной переработке `AGENTS.md` используй устойчивый общий каркас разделов, чтобы файлы разных проектов оставались узнаваемыми для людей. Не навязывай пустые разделы: если проекту не нужен раздел, пропусти его или оставь ближайший по смыслу. 7. Обеспечь в `AGENTS.md` наличие правил про границу изменений и явно выбранную политику работы с Git. Сначала сохрани существующую политику проекта или используй вариант, который пользователь выбрал в `ai-setup-project`. Если политика индекса Git ещё не определена, не выбирай её молча: верни открытое решение в маршрут настройки проекта. Варианты и точные границы описаны в `references/content-guidelines.md`. 8. Не перетирай осознанно изменённые пользователем решения о границе правок, добавлении в индекс Git, commit или push. Меняй такие правила только если пользователь прямо попросил обновить именно их или если они внутренне противоречат другим действующим инструкциям; противоречие сначала назови в отчёте. 9. Сформулируй инструкции так, чтобы агент мог действовать без догадки: обязательность, условия, команды, пути, причины и точки подтверждения. 10. Стабилизируй иерархию: вложенные файлы уточняют область, а не молча отменяют корневой процесс. 11. Проверь стоимость контекста: удали повторы, общие советы, дубли README и длинные справки без рабочей пользы. 12. Если разделяешь инструкции между корнем и вложенным файлом, отдельно перечитай итоговое содержание: в корне не должны остаться локальные команды, пути, переменные окружения и дубли README, которые ты заявил как перенесённые или удалённые. 13. Проверь результат: ссылки, команды, отсутствие секретов, отсутствие конфликтов, сценарий применения и добавление новых файлов в Git по правилам проекта. ## Что читать дополнительно - `references/maintenance-checklist.md` — детальный чек-лист сопровождения `AGENTS.md` и порядок проверки результата. - `references/content-guidelines.md` — критерии хорошего операционного описания и типичные ошибки содержания. ## Формат результата Результат применения навыка должен содержать: - изменённые или созданные файлы инструкций; - если создан или обновлён `CLAUDE.md` либо другая соседняя точка входа — почему выбран именно `@AGENTS.md`, символьная ссылка или отдельный файл; - краткое обоснование, какие проблемы закрывает изменение; - список перенесённых или удалённых фрагментов, если были выносы; - ограничения и недостающий контекст; - выбранную или сохранённую политику Git либо открытое решение, если политика ещё не определена; - проверку применимости результата; - рекомендацию, нужна ли независимая проверка через `ai-audit-agents-md`. ## Ошибки применения Ошибкой считается: - создать большой `AGENTS.md` без реальной задачи применения; - смешать документацию для человека и машинные инструкции; - записать непроверенную гипотезу как действующее правило; - добавить общие советы вместо конкретных команд и условий; - расширить корневой файл локальными правилами подкаталога; - убрать правило без понимания, какой риск оно закрывало; - оставить конфликт между файлами инструкций; - не проверить результат через `ai-audit-agents-md` после существенной правки. ## Связь с другими навыками - `ai-audit-agents-md` — независимая проверка качества `AGENTS.md` после создания или изменения. - `ai-work-control` — обязателен перед изменениями, которые становятся источником истины проекта. - `ai-data-collection` — полезен, если нужно собрать факты о командах, структуре и реальных провалах до проектирования инструкции. - `ai-work-result-evaluation` — нужен, если результат будет принят как основание для будущих изменений.