AQK — Agent Quality Kit

English · Русский

 █████╗   ██████╗ ██╗  ██╗
██╔══██╗ ██╔═══██╗██║ ██╔╝
███████║ ██║   ██║█████╔╝
██╔══██║ ██║▄▄ ██║██╔═██╗
██║  ██║ ╚██████╔╝██║  ██╗
╚═╝  ╚═╝  ╚══▀▀═╝ ╚═╝  ╚═╝
   обещание без кода возврата — просто предложение

AQK проверяет, что проверки вашего репозитория действительно ловят ошибки. Особенно когда код пишет ИИ-агент.

Зачем

Агент пишет код быстрее, чем вы успеваете его читать. Качество держат проверки: тесты, линтер, конвейер. Но проверка, которая не может провалиться, показывает ту же зелёную галочку, что и рабочая: || true в скрипте, тест без единого утверждения, хук, который никто не поставил, команда из AGENTS.md, которой больше нет.

AQK находит такие проверки. Он подсаживает заведомую ошибку в копию вашего кода, запускает проверки, которые объявил репозиторий, и говорит, какая заметила, а какая промолчала.

Кому и когда

• Вы пишете код с агентом — Claude Code, Codex, Cursor или другим — и хотите, чтобы правила проекта держала машина, а не его память.
• Конвейер зелёный, но вы не уверены, что он что-то ловит.
• Начинаете новый проект и хотите сторожей с первого дня: секреты, отладочная печать, проглоченные ошибки, огромные файлы.
• У вас несколько проектов, и опыт «на чём уже обжигались» должен переезжать между ними.

Работает с любым агентом и без него, на любом языке. Ставить ничего не нужно.

Попробовать за минуту

npx agent-quality-kit doctor    # код уже есть: что проверяется, а что не сторожит никто
npx agent-quality-kit start     # кода ещё нет: поставить сторожей сразу

doctor только читает: не пишет файлов и ничего не отправляет. Вот что он говорит о проекте, где конвейер зелёный, а покраснеть не может ни одна проверка:

✘  test         npm test   ← package.json
   не может провалиться: исход погашен прямо в скрипте — «|| true»
✔  lint         npm run lint   ← package.json
✘  typecheck    npm run typecheck   ← package.json
   ничего не доказывает: всё тело скрипта — печать — «echo 'todo: turn this on'»

У каждой проверки три исхода, а не два: ✔ чисто, ✘ находка в коде, ? сама проверка не смогла — чинить нужно инструмент, а не файл. Отказ написан для агента: в нём сказано, что сделать.

Главные команды

| Команда | Что делает | |---|---| | doctor | осмотр: что объявлено, что не сторожит никто, какой уровень | | doctor --run | запускает объявленные проверки; код возврата — для конвейера | | add <имя> | ставит готового сторожа из каталога | | prove | доказывает, что каждая проверка краснеет на своём образце ошибки | | probe | подсаживает ошибки в копию кода и смотрит, кто их поймает | | report --html | страница для человека: что защищено, лучше или хуже, что поручить агенту | | context | состояние репозитория для агента — до его первого действия |

Поставить насовсем

В конвейер GitHub:

- uses: arsen-ask-lx/[email protected]
  with:
    min: 1   # сборка падает ниже AQK-1 или если упала любая объявленная проверка

Хуком pre-commit:

repos:
  - repo: https://github.com/arsen-ask-lx/Agent_Quality_Kit
    rev: v0.19.0
    hooks:
      - id: aqk

Плагином Claude Code — состояние репозитория попадает агенту в контекст:

/plugin marketplace add arsen-ask-lx/Agent_Quality_Kit
/plugin install aqk@agent-quality-kit

Нужно: Node 18+ и sh (macOS, Linux, WSL; на Windows — Git Bash). Пакет весит ≈0,8 МБ, зависимостей нет. Раз в сутки, и никогда в конвейере, doctor --brief спрашивает у npm номер последней версии; выключается AQK_UPDATE=0. Автообновления нет.

Подробнее

• Полное руководство — все команды, ступени AQK-0…3, как устроены проверки, каталог, как ввести правило в живой проект.
• Каталог сторожей · Журнал шишек · Спецификация
• Как принести свой гейт · Сообщить об ошибке

Лицензия MIT.