/audit-rules-file — Аудит файлу правил

Скіл автоматизує щомісячний аудит файлу правил (~/.claude/CLAUDE.md) — замість 13-годинного ручного marathon. Логіка: читаю → triangulation Codex+Gemini → пропоную зміни → юзер дає "ок/ні" на КОЖНУ → backup → apply.

Параметри

• За замовчуванням аудит ціляться на ~/.claude/CLAUDE.md.
• Юзер може передати інший шлях: /audit-rules-file ~/Projects/foo/CLAUDE.md.

Послідовність (виконуй чітко)

Фаза 1 — Read & baseline

1. Прочитай target файл (Read tool).
2. wc -l <path> — поточна довжина у рядках.
3. ls -t <path>.backup-* 2>/dev/null | head -1 — найсвіжіший backup (якщо є).
4. tail -20 <path>.audit-history — дата останнього аудиту.
5. Покажи юзеру: шлях / поточна довжина / поріг 200 / дата останнього backup.

ГАРД «свіжий аудит» (обовʼязковий). Якщо останній аудит був менше 30 днів тому — СТОП перед Фазою 2. Скажи дату й кількість днів і спитай прямо: «Аудит був N днів тому. Vendor'и на вже чистому файлі починають вигадувати проблеми (закон спадної віддачі — перевірено 2026-08-22: з ~20 пропозицій прийнято 3, при цьому Gemini назвав робочий скрипт „милицею“, Codex не дочитав рядок до кінця). Точно запускаємо?» Чекай явне «так». Виняток без питання: файл змінювався після того аудиту (<path> новіший за backup) або юзер сам назвав причину («додав правила», «модель оновилась»).

Фаза 2 — Triangulation (паралельно)

Запусти у ПАРАЛЕЛЬ через Bash:

codex exec --skip-git-repo-check "Прочитай <ABSOLUTE_PATH>. Це global CLAUDE.md для Claude Code (N рядків). Знайди і поверни JSON: {\"duplicates\":[{\"lines\":\"X-Y та A-B\",\"reason\":\"...\"}],\"outdated\":[{\"lines\":\"X-Y\",\"reason\":\"...\"}],\"verbose\":[{\"lines\":\"X-Y\",\"rewrite_to\":\"...\"}],\"wiki_candidates\":[{\"lines\":\"X-Y\",\"suggested_wiki_path\":\"(твоя база знань) Без коментарів, тільки JSON."

gemini --skip-trust -p "<той самий промт>"

ВАЖЛИВО:

• Замінити <ABSOLUTE_PATH> на реальний шлях.
• Gemini не читає файли поза своєю пісочницею (workspace) → перед викликом скопіюй target у поточну робочу папку (cp <ABSOLUTE_PATH> ./audit-target-copy.md), у промті для gemini вказуй ./audit-target-copy.md; після відповіді копію видали. Для codex абсолютний шлях ок.
• Якщо codex або gemini не знайдено в PATH → fallback на тільки Claude self-audit (явно скажи що triangulation неповний).

Фаза 3 — Parse & merge

1. Спарси JSON-відповіді обох vendor: python3 tools/extract-last-json.py <файл-виводу> [ключ] — бере ОСТАННІЙ валідний JSON (codex спершу друкує порожній {"duplicates":[]…} до читання файлу, справжній — у кінці). Невалідний JSON → 1 retry → fallback.
2. Об'єднай у 5 категорій:
   • 🔴 Суперечності — дві секції описують один процес по-різному. НАЙВАЖЛИВІША категорія: агент читає обидві й обирає навмання, причому мовчки. Ознаки — секція, що сама зізнається «ОНОВЛЕННЯ правила вище»; та сама команда рекомендована в одному місці й заборонена в іншому; те саме слово («merge») з різним значенням у різних абзацах. Шукати цілеспрямовано: vendor'и питають про дублі, але суперечності часто пропускають.
   • Дублі — однаковий зміст у різних місцях
   • Застарілі — модель вже знає, або правило про неіснуючу функцію/файл
   • Надто довгі — секція 10+ рядків коли суть у 3
   • Wiki-кандидати — деталі/історія/приклади що краще у Wiki
3. Для кожної пропозиції покажи які vendor погодились (Codex + Gemini → high confidence; тільки один → low).

Фаза 4 — Confirm with user

Звіт зведений:

📊 Знайдено пропозицій: N
  Дублі: X (high X, low Y)
  Застарілі: X
  Надто довгі: X
  Wiki-кандидати: X

Далі по одній пропозиції:

[1/N] Категорія: дублі (high confidence — Codex + Gemini)
Рядки 45-52 та 78-83 — обидва описують one_focus principle.
ДІЯ: видалити 78-83 (залишити 45-52 як canonical).
Твоє ок? (так / ні / детальніше / пропустити)

Чекай явну відповідь юзера на КОЖНУ. Збирай "так"-пропозиції у applied_changes list.

Пакетний режим (виняток): якщо юзер ЗАЗДАЛЕГІДЬ делегував рішення («прийми рішення сам», «зроби і покажи diff в кінці») — не питай «ок?» на кожну: застосуй high-confidence зміни пакетом, сумнівні відхили, у фіналі — повний diff + список відхиленого з причинами. Backup (Фаза 5) обовʼязковий завжди. Пропозиції vendor'ів «винести секцію у Wiki» перевіряй на пастку: Wiki не автозавантажується — правило там помирає; виноси лише довідки, не діючі правила.

Фаза 5 — Backup

ПЕРЕД будь-якою зміною:

cp <path> <path>.backup-audit-$(date +%Y%m%d-%H%M%S)

Покажи юзеру шлях backup (для rollback).

Фаза 6 — Apply

Виконай applied_changes одну за одною через Edit tool. Після кожної — show diff (diff або old→new рядки). Якщо щось ламається посередині → зупинись, покажи юзеру, запропонуй rollback з backup.

Фаза 7 — Verify & report

1. wc -l <path> — нова довжина.
2. Покажи:
   • Було: X рядків → Стало: Y рядків (−Z, −W%)
   • Apply: N з M пропозицій
   • Skipped: N
   • Backup: <path>.backup-audit-...
   • Rollback: cp <backup_path> <path>
3. Запропонуй наступний крок: /wiki-compile для перенесених у Wiki матеріалів (якщо були wiki_candidates).

Якщо triangulation не вдається

Якщо codex або gemini повертає помилку:

1. Покажи юзеру error message.
2. Запропонуй: (a) продовжити з vendor що працює / (b) Claude self-audit (менш надійно) / (c) скасувати.

Проєктний режим (файл усередині репозиторію)

Вмикається, коли target лежить у git-репо, а не в ~/.claude/. Відмінності від глобального аудиту — усі куплені реальними помилками 2026-08-26 на бойовий проєкт.

Замість .backup-* — коміт. Репо вже дає відкат. Перед аудитом переконайся, що target закомічений (git status --short <path> порожній) — інакше нема куди відкочуватись. Кожна прийнята зміна = окремий коміт, щоб її можна було зняти поодинці через git revert.

Винесення до коду, а не у Wiki. Головна перевага проєктного файлу: правило можна покласти поряд із кодом, якого воно стосується — supabase/migrations/CLAUDE.md, src/api/CLAUDE.md. Claude Code підвантажує такий файл, коли читає файли з тієї теки, тож у корені він не з'їдає контекст.

🔴 Але pointer недостатній. Scoped-файл завантажується, лише коли агент читає файл у тій теці. Деплой командою з кореля (supabase functions deploy X) або запис через cat > теки не «читають» — правило не спрацює. Тому: інваріанти, порушення яких ламає прод, лишай у корені (2–3 рядки), а scoped-файл роби розгорнутою версією. Виносити можна процедури й приклади, не запобіжники.

Звірка з AGENTS.md. Якщо в репо є AGENTS.md — Codex і Cursor читають саме його. Після правки CLAUDE.md перевір, чи AGENTS.md не суперечить новій версії. Симлінк доречний, коли зміст однаковий; окремий короткий файл — коли CLAUDE.md переріс 200 рядків.

Гілки. Правка живе лише на поточній гілці. Перевір, що бачать інші: git ls-tree -r --name-only origin/dev -- . | grep CLAUDE.md. Якщо там стара версія — скажи юзеру прямо: правильний текст закону не бачить жодна сесія, крім цієї, і мердж — частина роботи, а не «потім».

Гарди, куплені кров'ю

Перед вирізанням блоку — assert на обидві межі. Не покладайся на пошук за назвою секції: між нею і наступною може лежати ще шість інших.

lines = open(p, encoding='utf-8').read().split('\n')
assert lines[12].startswith('## Початок блоку'), lines[12]
assert lines[92].startswith('## Наступна секція'), lines[92]
out = lines[:12] + new.split('\n') + lines[92:]

Без цього — 216 вирізаних рядків замість 78 (реальний випадок 2026-08-26; врятував git).

Після кожної правки — грепом перевір, що правила на місці. Список ключових рядків складай ДО правки:

for t in "ЖОДНОГО merge" "additive міграції" "alias:dev"; do
  grep -q "$t" CLAUDE.md && echo "  ✓ $t" || echo "  ✗ ВТРАЧЕНО: $t"
done

Не став вказівник у порожнечу. Замінюючи блок на «подробиці у docs/foo.md» — спершу grep цей зміст у тому файлі. Того ж дня обидва вказівники на docs/release-train.md вели у файл, де описаного змісту не було: обґрунтування не перенесли, а видалили.

Не знімай правило на підставі «це ж робить хук». Спершу прочитай код хука. Реальний випадок: 37 рядків прози зняли, бо «хук не дасть забути», а хук бачив лише правки UI-файлів через Edit/Write, блокував один раз за turn і мав документовану фразу-обхід — тобто був сліпий рівно до того інциденту, заради якого правило й писали.

Після аудиту — незалежна перевірка. Файл правил керує поведінкою агента на проді, і помилка в ньому не кидає виняток. /multi-review <path> знаходить те, що не бачить той, хто щойно правив. Сирі виводи рецензентів у репо не класти — вони містять усе, що агент читав дорогою, включно з локальними конфігами.

Anti-patterns (НЕ робити)

• НЕ вирізати блок без assert на обидві межі (див. «Гарди»).
• НЕ виносити у scoped-файл запобіжник, порушення якого ламає прод — тільки процедури.
• НЕ apply без юзерського "ок" на кожну пропозицію (виняток — явно делегований пакетний режим, див. Фазу 4).
• НЕ apply без backup.
• НЕ запускати triangulation на файлі, аудитованому <30 днів тому, без явного «так» (див. гард у Фазі 1) — це палить токени на шум.
• НЕ показувати JSON сирим — переформатовуй у людську мову.
• НЕ йти у спіраль якщо vendor дає невалідний JSON — після 2 retry → fallback.

Tone

Українською, простою мовою (юзер не програміст). Технічний термін → пояснення в 1 реченні.