Audit Agent Rules

---
name: audit-agent-rules
description: Audits the agent rules in the current folder (AGENTS.md, nested AGENTS.md files) and the skill descriptions the agent sees at start, then reports what to cut, move or rewrite and edits only after the user says yes. Use on «аудит правил», «проверь AGENTS.md», «почему агент не слушается правил», «проверь скиллы».
---

# Аудит правил агента

Скилл проверяет файлы правил агента в текущей папке и каталог скиллов, который агент видит на старте. Отдаёт отчёт таблицей: что не так и как сделать лучше. Файлы меняет только после «да» человека.

Скилл обычно зовёт человек без опыта в программировании: он ведёт папку с агентом для своей работы. Отчёт пиши простыми словами, на языке человека; термин объясняй один раз через то, что он меняет в работе агента.

## Что проверяется

- `AGENTS.md` в текущей папке и во всех её подпапках. Его читают Claude Code, Codex, Cursor и другие агенты, поэтому аудит строится вокруг него.
- `CLAUDE.md`, `CLAUDE.local.md` и `.claude/rules/` попадают в отчёт одной находкой, если в них свой текст: тогда Claude Code читает одни правила, остальные агенты другие. Разбирать их построчно не нужно.
- Скиллы из `.agents/skills` и `.claude/skills` этой папки (и папок выше до корня git-репозитория), `~/.agents/skills`, `~/.codex/skills`, `~/.claude/skills`.

## Четыре мерила

1. **Каждая строка правил: маршрут, граница или постоянное поведение.**

   | Вид | Что делает | Пример |
   |---|---|---|
   | Маршрут | Ведёт к файлу или скиллу под задачу | «Пост в канал пиши через скилл `telegram-post`» |
   | Граница | Что можно и что нельзя | «`archive/` только читать» |
   | Постоянное поведение | Действует на любой запрос | «Отвечай по-русски, коротко» |

   Строка другого вида уходит из файла: процедура с шагами в скилл или `docs/`, история решений в git, справка в `docs/`, правило одной подпапки во вложенный `AGENTS.md`. Проверка строки: если её удалить, агент ошибётся? Если нет, строка лишняя.

2. **Файл до 200 строк.** Ориентир Anthropic: длинный файл занимает контекст, и агент хуже соблюдает правила. Codex читает все `AGENTS.md` от корня репозитория до папки, где его запустили, в общий бюджет 32 KiB (32 768 байт в UTF-8). Кириллическая буква весит 2 байта. Что не влезло, Codex обрезает и не читает.

3. **`AGENTS.md` работает навигатором.** Детали лежат в своих файлах и скиллах, в правилах остаётся строка-маршрут: «Для X открой Y» или «X пиши через скилл Z». Вложенный `AGENTS.md` агент гарантированно читает только в сессии, начатой в его папке, поэтому у каждого вложенного файла есть маршрут из корневого.

4. **Описание скилла отвечает на вопрос «когда меня брать».** Поле `description` говорит, что скилл делает, и когда его брать или по каким фразам. Оно короткое и не пересекается с описаниями других скиллов. Каталог описаний агент видит на старте целиком, тело скилла читает по требованию. У Codex стартовый список скиллов ограничен 2% окна контекста (8 000 символов, если окно неизвестно): при переборе он сокращает описания, и часть скиллов выпадает из списка. Claude Code обрезает описание одного скилла после 1 536 символов.

## Порядок работы

1. **Замерить.** Запусти сканер из папки этого скилла: `python3 <папка скилла>/scripts/scan.py .` Он только читает и печатает разделы: файлы правил со строками и байтами, `CLAUDE.md` и `.claude/rules`, цепочки Codex, вложенные файлы без маршрута, подсказки по строкам, каталог скиллов, маршруты в никуда. Всё, что он нашёл, кандидаты: каждое срабатывание ты подтверждаешь чтением. Если Python нет, посчитай то же вручную. Готово, когда прочитан весь вывод.

2. **Отделить правила папки от образцов.** Рабочий файл подпапки (правила, по которым агент работает в ней) разбирается построчно. Образец для другой папки (шаблон, раздатка, архив, пример в материалах) идёт в отчёт одной строкой «образец, построчно не разбирал». Агент всё равно подгружает образец, когда работает в его папке; если это мешает, скажи об этом в той же строке.

3. **Разметить строки.** Прочитай корневой `AGENTS.md` и каждый вложенный файл правил целиком. Каждой строке дай вид из мерила 1 или пометку «уходит» с местом назначения по [references/where-lines-go.md](references/where-lines-go.md). Подсказки сканера (история, шаги, код, длинная строка) показывают, куда смотреть первым делом; решение по строке за тобой. Попутно отметь дубли между файлами, противоречия и маршруты на несуществующие файлы, папки и скиллы. В противоречии выбирает человек: в правке назови оба варианта и спроси, какой оставить. Готово, когда размечена каждая строка каждого рабочего файла правил.

4. **Проверить маршруты.** Для каждого вложенного `AGENTS.md` найди в корневом строку, которая к нему ведёт. Сканер ищет в тексте путь вида `папка/AGENTS.md`: найденная строка должна быть маршрутом и называть задачу, а маршрут, который называет только папку, проверь глазами. Цепочку Codex больше 32 768 байт назови с местом обрезки.

5. **Проверить каталог описаний.** Сверь сумму символов с 8 000: у модели с большим окном бюджет больше, но сумма в разы выше 8 000 значит, что Codex сокращает описания. Прочитай каждое описание: есть ли «что делает» и «когда брать». Пары из таблицы похожих описаний прочитай и реши, пересекаются ли они по задаче. Отдельно отметь копии одного скилла в нескольких папках и битые ссылки. Скиллы плагинов и встроенные скиллы сканер не видит: напиши это одной строкой в отчёте.

6. **Отчёт.** По шаблону ниже. Сначала то, чего агент не видит совсем (обрезка Codex, нет маршрута, два набора правил), потом строки не своего вида, потом скиллы. В таблице до 15 строк с самым большим эффектом, остальное коротко в «Ещё». Скилл из домашней папки помечай «общий для всех папок».

7. **Спросить «Переписать?».** Дальше ничего не меняй, пока человек не ответил «да» или не назвал номера строк таблицы.

8. **Переписать.** До первой правки сохрани исходники: в git-репозитории проверь, что изменения человека закоммичены или он согласен работать поверх них; без git скопируй файлы в `rules-backup-ГГГГ-ММ-ДД/`. Переноси по [references/where-lines-go.md](references/where-lines-go.md). Каждая уходящая строка появляется в новом месте до удаления из старого. Скиллы в домашней папке (`~/…`) общие для всех папок человека: правь их, только если он назвал их в ответе. Скилл из плагина не правь, предложи отключить плагин.

9. **Перемерить и проверить смоуком.** Запусти сканер снова и покажи числа «было → стало». Попроси человека открыть новую сессию агента в этой папке и спросить: «Не открывая файлов, назови правило из AGENTS.md про <тема>». Для вложенного файла новую сессию открывают в его подпапке. Для скилла человек пишет фразу из описания и смотрит, взял ли агент нужный скилл. Агент не назвал правило: найди, почему оно не доходит, и почини.

## Шаблон отчёта

```markdown
**Итог.** Файлов правил: 4, строк: 312, байт: 21 480. Самая длинная цепочка Codex: 21 480 из 32 768 байт. Скиллов в каталоге: 23, описания: 9 100 символов при ориентире Codex 8 000.

| # | Где | Что не так | Мерило | Что сделать |
|---|---|---|---|---|
| 1 | `docs/AGENTS.md` | Из корня нет маршрута: агент, запущенный в корне, этих правил не видит | 3 | В корневой `AGENTS.md` строку «Правила документации: `docs/AGENTS.md`» |
| 2 | `AGENTS.md:40–58` | Процедура из 9 шагов: как выпускать пост | 1 | В скилл `post`; в файле строка «Пост выпускай через скилл `post`» |
| 3 | `AGENTS.md:12` | История: «решили на созвоне 12.03» | 1 | Удалить, история в git |
| 4 | скилл `report` и `weekly-report` | Описания про одно: «отчёт за неделю» | 4 | `report` оставить для разовых отчётов, `weekly-report` для недели; переписать оба |

Ещё: `CLAUDE.md` в корне со своим текстом, Claude Code и Codex читают разные правила. Скиллы плагинов не проверял.

Переписать? Ответь «да», номерами строк таблицы или «нет».
```

Каждая строка таблицы называет файл и строку, проблему простыми словами, номер мерила и конкретную правку: куда перенести или как переписать. Строка без конкретной правки или вопроса с вариантами в отчёт не идёт.

## Границы

- До «да» скилл только читает.
- Новых правил от себя в файл не добавляй: аудит переносит и переписывает то, что уже есть. Если правила явно не хватает, предложи его отдельной строкой отчёта.
- Глобальные файлы правил харнесов (`~/.claude/CLAUDE.md`, `~/.codex/AGENTS.md`) упомяни в отчёте, если они длинные или спорят с правилами папки; правь их только по прямой просьбе.
- Жёсткий запрет, который нельзя доверить модели (не пушить, не удалять), предложи поставить в настройки агента; строка в файле правил остаётся пояснением.

## Источники

- Anthropic, память и файлы правил: https://code.claude.com/docs/en/memory
- Anthropic, лучшие практики Claude Code: https://code.claude.com/docs/en/best-practices
- Anthropic, скиллы Claude Code: https://code.claude.com/docs/en/skills
- OpenAI, AGENTS.md в Codex: https://learn.chatgpt.com/docs/agent-configuration/agents-md
- OpenAI, скиллы Codex: https://learn.chatgpt.com/docs/build-skills
- Anthropic, Agent Skills: https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills