maintaining-agent-instructions

Contents

• Обзор
• Требования
• Установка
• Структура
• Цикл аудита
• Разработка

Обзор

Skill — процедурный аудитор конфигурации агента, устроенный вокруг трёхшагового цикла с проверяемым артефактом на каждой границе: механическая инвентаризация скриптом, обход находок по стабильным ID, количественная самопроверка отчёта против той же инвентаризации перед тем, как что-либо показать пользователю.

Репозиторий можно использовать как:

• Готовый инструментарий — скопировать/симлинкнуть в .claude/skills/ или .cursor/skills/ целевого проекта и вызывать явно («проведи аудит .claude/rules и skills»), без дополнительной настройки;
• Референс архитектуры — как пример skill'а, который вместо «прочитай чек-лист и вынеси вердикт» строит вокруг чек-листа ID-систему с автоматической сверкой охвата (verify_id_coverage.py) — решение проблемы «асимметрии рвения» при обходе десятков файлов;
• Отправную точку — скопировать структуру (SKILL.md + references/
  • scripts/) под собственный многошаговый аудит/ревью-skill и заменить чек-лист и скрипты инвентаризации/сверки под свою предметную область.

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

Механизм	Файлы
Инструкции верхнего уровня	AGENTS.md, CLAUDE.md/CLAUDE.local.md
Правила	.claude/rules/*.md, .cursor/rules/*.mdc
Skills	.claude/skills//.cursor/skills/ — SKILL.md + bundle-файлы
Субагенты	.claude/agents//.cursor/agents/, включая memory-frontmatter
Конфигурация инструмента	MCP (.mcp.json/.cursor/mcp.json), hooks (settings.json/.cursor/hooks.json), ignore-файлы
Прочее	output styles, workflows, plugin-манифесты

Вне области — продуктовые (нефайловые) механизмы Claude (Projects, Custom Instructions, Artifacts, Computer Use) и инициализация набора файлов инструкций с нуля в пустом репозитории (для этого — встроенный /init).

Требования

• Claude Code или Cursor (skill читает форматы обоих инструментов).
• Python 3.9+ — для scripts/discover_inventory.py, scripts/verify_id_coverage.py и scripts/check_coverage.py (только стандартная библиотека, внешних зависимостей нет).

Установка

Skill сам по себе — самостоятельный git-репозиторий, не пакет для менеджера пакетов. Клонировать прямо в .claude/skills/ (или .cursor/skills/) целевого проекта:

git clone <URL-этого-репозитория> .claude/skills/maintaining-agent-instructions

Без git — скопировать каталог целиком тем же путём.

Структура

SKILL.md                         точка входа: шаги аудита, чек-лист прогресса
references/
  audit-checklist.md             обходной чек-лист (разделы A–P, ID-система)
  agent-config-research.md       обоснование, точные поля frontmatter, лимиты
  id-report-examples.md          образцы полного отчёта по ID
scripts/
  discover_inventory.py          Шаг 0: рекурсивная инвентаризация → manifest.tsv
  check_coverage.py              Шаг 0.5: сверка manifest с журналом покрытия прошлых раундов
  verify_id_coverage.py          Шаг 2: сверка отчёта против manifest (0 расхождений)

SKILL.md — единственный файл, который харнесс сканирует автоматически (frontmatter name/description для триггера); references/ и scripts/ подгружаются по явной ссылке из него, а не всегда.

Цикл аудита

1. Инвентаризация (discover_inventory.py) — рекурсивный обход дерева репозитория на любой глубине вложенности, не только корень; печатает manifest.tsv (тип + путь), включая синтетические (missing)-строки там, где отсутствие защитного файла (например, .cursorignore) — само по себе находка. 1.5. Сверка с журналом покрытия (check_coverage.py) — если в аудируемом репозитории уже есть история прошлых прогонов (.claude/AUDIT-COVERAGE.tsv), делит manifest.tsv на «никогда не проверялись» / «изменились с прошлого прохода» / «устарели (чек-лист вырос)» / «актуальны» — судейского разбора на шаге 2 требуют только первые две категории.
2. Обход и находки — каждый файл из manifest.tsv проверяется по audit-checklist.md целиком; у крупных репозиториев чтение делегируется субагентам партиями ≤8 файлов. Каждый проверяемый факт получает стабильный ID (A1, F4, G10, …) и явный вердикт — не общая фраза на файл или раздел.
3. Самопроверка (verify_id_coverage.py) — сверяет черновик отчёта против того же manifest.tsv: ловит пропущенные файлы, пропущенные отдельные ID внутри файла, дубли и вердикты не по чек-листу. Ненулевой exit code — аудит не завершён.
4. Подтверждение и применение — полный список находок с готовыми исправлениями показывается пользователю; правки применяются только после явного подтверждения, без повторного придумывания решения на этом шаге.

Разработка

Оба reference-файла (audit-checklist.md, agent-config-research.md) читаются выборочно по разделу из оглавления, не целиком — при добавлении нового проверяемого ID синхронизировать три места: сам чек-лист, TYPE_MAP/SECTION_MAX в verify_id_coverage.py и, если меняется состав инвентаризуемых типов файлов, classify() в discover_inventory.py. verify_id_coverage.py --checklist при каждом запуске сверяет SECTION_MAX с фактическим числом пунктов в audit-checklist.md и падает на рассинхроне.