Agent audit

Agent Self-Audit

Системный аудит состояния проекта и качества взаимодействия агента с пользователем.

Связанное: для адресной правки CLAUDE.md см. навыки claude-md-improver и revise-claude-md — этот навык делает мета-аудит и формирует правки, а они применяют изменения в CLAUDE.md прицельно.

Главное правило

Если данных недостаточно для содержательного ответа по блоку — пропусти блок и напиши почему. Пустой блок с пометкой «нет данных» ценнее правдоподобной догадки.

Шаг 0. Режим

Определи из контекста или спроси:

• Полный — все 5 блоков + отчёт + автоприменение. После milestone или рефакторинга.
• Быстрый — блоки 1-2 (документация + ошибки). После продуктивной сессии.
• Точечный — один блок по запросу.

Шаг 1. Сканирование

Собери данные до начала анализа. Окружение — Windows/PowerShell; используй встроенные инструменты Glob/Grep/Read для файлов и PowerShell/git для истории.

Структура и наличие doc-файлов — через Glob:

• *.md в корне, docs/**/*.md.

Свежесть документации (последний коммит каждого doc-файла vs последний коммит проекта). PowerShell:

$docs = 'CLAUDE.md','ARCHITECTURE.md','CHANGELOG.md','ROADMAP.md','README.md'
foreach ($f in $docs) {
  if (Test-Path $f) {
    $info = git log -1 --format='%h %ar' -- $f 2>$null
    Write-Output "$f`: $(if ($info) { $info } else { 'не в git' })"
  } else {
    Write-Output "$f`: отсутствует"
  }
}
Write-Output "Проект: $(git log -1 --format='%h %ar' 2>$null)"

История коммитов:

git log --oneline -20

Паттерны ошибок (fix/revert/hotfix за последние 50 коммитов):

git log --oneline -50 | Select-String -Pattern 'fix|revert|hotfix|oops|bug|broken'

Открытые TODO/FIXME/HACK/XXX — через Grep (output_mode "files_with_matches" или "count"), паттерн TODO|FIXME|HACK|XXX, glob *.{ts,tsx,js,jsx,py,rs,go,md}.

Прочитай содержимое (Read): CLAUDE.md, ARCHITECTURE.md, ROADMAP.md, CHANGELOG.md (последние записи).

Шаг 2. Аудит

Формат для каждой находки:

• Статус: [CRITICAL] / [WARN] / [OK]
• Что: конкретное наблюдение с указанием файла/строки/коммита
• Действие: точная правка (файл, секция, что добавить/удалить/изменить)

---

БЛОК 1: Документация и контекст

Всё, что агент читает в начале сессии, должно отражать реальность.

CLAUDE.md — проверь:

• Объём: > 300 строк → нужна декомпозиция в docs/
• Конфликты: инструкции, которые противоречат друг другу
• Устаревшее: правила, ссылающиеся на удалённые файлы, переименованные модули, старые API. Метод: сравни каждое упоминание файла/функции с реальной кодовой базой
• Пробелы: конвенции, которые видны в коде (паттерны из коммитов), но не записаны
• Приоритизация: есть ли разделение «критичное» vs «рекомендация»

ARCHITECTURE.md — проверь:

• Модули и файлы из описания vs реальная структура (Glob) — совпадают ли
• Зависимости — актуальны ли версии, существуют ли упомянутые пакеты
• Диаграммы (если есть) — отражают ли текущую структуру

ROADMAP — проверь:

• Пункты «в работе» — реально ли они в работе (есть коммиты?)
• Завершённые пункты, не отмеченные как завершённые
• Расхождение между ROADMAP и реальными коммитами последних недель

CHANGELOG — проверь:

• Есть ли записи о последних значимых изменениях (сравни с git log)
• Пропущенные записи → подготовь драфты

Артефакты между сессиями:

• Все ли важные решения текущей сессии зафиксированы
• Нет ли «устных договорённостей», которые потеряются при новой сессии
• Достаточно ли контекста в docs/, чтобы новый агент мог продолжить работу

БЛОК 2: Повторяющиеся ошибки и guardrails

Анализ git history:

• Коммиты с fix/revert/hotfix за последние 50 коммитов
• Группировка по типу: одинаковые фиксы в разных местах = системная проблема
• Файлы с > 3 фиксами за последние 50 коммитов — кандидаты на рефакторинг

Файлы, чаще всего попадающие в fix-коммиты (PowerShell):

git log --oneline -50 --name-only --pretty=format: |
  Where-Object { $_ -ne '' } |
  Group-Object | Sort-Object Count -Descending |
  Select-Object -First 10 Count, Name

Анализ CLAUDE.md:

• Секции вида «НИКОГДА не...», «ВАЖНО:», «НЕ ЗАБЫВАЙ» — следы прошлых ошибок
• Проверь: работают ли эти guardrails или ошибки продолжаются

Для каждой повторяющейся ошибки выдай:

• Правило для CLAUDE.md (одно предложение, с примером)
• Автоматическую проверку если возможно: lint rule, pre-commit hook, тест, CI check

БЛОК 3: Проактивность

Основываясь на данных (не на догадках):

Из ROADMAP и TODO/FIXME:

• Что следующее в очереди и что можно подготовить заранее
• Какие TODO накопились и требуют приоритизации

Из git log (тренды):

• Области кода, которые активно меняются → будут меняться дальше
• Файлы, которые разрастаются и скоро потребуют рефакторинга
• Устаревшие зависимости

High-leverage шаг:

• Одно конкретное действие для ускорения следующих задач. Не «улучшить тестирование», а «добавить тест на X, этот модуль ломался 3 раза»

БЛОК 4: Калибровка уверенности

Назови прямо:

• Части проекта, которые агент понимает поверхностно (большие файлы не читанные целиком, модули без документации)
• Конвенции, которые нигде не записаны и агент угадывает (стиль тестов? стратегия деплоя? обработка ошибок?)
• Решения без зафиксированного «почему» (код есть, ADR/комментария нет)

Для каждого пробела: конкретный вопрос пользователю или секция для docs/.

БЛОК 5: Связи и инсайты

Только при полном аудите. Требует глубокого контекста.

• Дублирование логики в разных модулях
• Модули с неявными зависимостями (меняешь один — ломается другой)
• Расхождение между заявленными приоритетами и реальной работой
• Паттерны в правках пользователя — что ценит, что переделывает

---

Шаг 3. Отчёт

Сохрани в docs/audit-report-YYYY-MM-DD.md:

# Agent Self-Audit — [дата]
Режим: [полный / быстрый / точечный]

## Сводка
[2-3 предложения]

## CRITICAL
[Находки + действия. Если нет — «нет критичных находок»]

## WARN
[Находки + действия]

## OK
[Кратко]

## Правки к применению
[Нумерованный список: файл → что изменить]

## Вопросы к пользователю
[Для закрытия пробелов из Блока 4]

## Предложения
[Из Блока 3: что подготовить, прототипировать]

Шаг 4. Автоприменение

Спроси: «Готов применить. Варианты:

1. Всё автоматически
2. С подтверждением каждого изменения
3. Только критичные (CRITICAL)»

При применении:

• Каждая правка — отдельное изменение с описанием
• Не удаляй информацию без уверенности — спроси
• После применения обнови отчёт: отметь применённое
• Для прицельной правки CLAUDE.md можно делегировать в claude-md-improver / revise-claude-md

---

Когда предложить аудит проактивно

Предлагай:

• CLAUDE.md не менялся > 10 коммитов
• В сессии > 5 коммитов с крупными изменениями
• Пользователь говорит «мы закончили» / «что дальше»
• Рефакторинг затронул > 3 модулей

Не предлагай:

• Мелкие фиксы, warning'и
• Пользователь в потоке работы
• 1-2 косметических коммита