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 — нужен, если результат будет принят как основание для будущих изменений.