ClawPatch — семантический код-ревью на базе ИИ-агентов

Clawpatch — инструмент командной строки (CLI) для код-ревью с помощью агентов для работы с кодом. Он разбивает репозиторий на семантические срезы, передаёт агенту ограниченный контекст каждого среза и сохраняет находки с доказательствами. Исправление, повторная проверка и создание pull request (запроса на слияние) запускаются отдельными явными командами.

Материал актуализирован по официальному сайту, документации, репозиторию и истории релизов 8 сентября 2026 года. Команды и возможности сверены с Clawpatch v0.8.0; отдельный запуск в реальном проекте в рамках подготовки материала не выполнялся.

Что делает Clawpatch

Обычный линтер анализирует отдельные конструкции и файлы. Clawpatch формирует feature records — записи о функциональных единицах проекта: маршрутах, командах, пакетах, библиотеках, тестах и других связанных частях кодовой базы.

Базовый процесс выглядит так:

1. clawpatch init определяет структуру проекта и создаёт локальное состояние в .clawpatch/.
2. clawpatch map строит карту семантических срезов. По умолчанию маппинг детерминирован и не вызывает модель.
3. clawpatch review передаёт выбранные срезы установленному агенту для работы с кодом.
4. Clawpatch проверяет структуру ответа и доказательства, затем сохраняет допустимые находки.
5. clawpatch fix --finding <id> запускает одну явную попытку исправления с настроенной валидацией.
6. clawpatch revalidate --finding <id> повторно проверяет находку на текущем коде.
7. При необходимости clawpatch open-pr --patch <id> создаёт отдельную ветку, коммитит записанные файлы патча, отправляет ветку в удалённый репозиторий и открывает pull request.

Состояние сохраняется между запусками, поэтому большое ревью можно выполнять частями.

Основные возможности

В документации для ответов провайдера перечислены категории находок: bug, security, performance, concurrency, api-contract, data-loss, test-gap, docs-gap, build-release и maintainability.

Для триажа, то есть проверки и приоритизации находок, используются статусы open, fixed, wont-fix, false-positive и uncertain.

Какие проекты поддерживаются

Текущий маппер определяет границы для проектов на следующих языках и платформах:

• Node.js и TypeScript, включая исполняемые записи пакета (package bins), скрипты и распространённые серверные маршруты;
• Next.js с маршрутами app/ и pages/;
• Python, включая Flask, FastAPI, Django, консольные команды, тесты и uv workspaces;
• Ruby и Rails;
• PHP и Laravel;
• Go;
• Rust и Cargo;
• C, C++ и CUDA;
• Java и Kotlin, включая Gradle и Maven;
• .NET;
• SwiftPM;
• скрипты оболочки, файлы workflow для CI и конфигурация проекта.

Сгенерированные каталоги и каталоги, подключённые символическими ссылками, пропускаются. Если эвристического маппинга недостаточно, режимы --source auto и --source agent могут добавить срезы с помощью провайдера.

В версии 0.8.0 появился опциональный флаг --link-http caller:backend. Он добавляет ограниченный контекст между Node-клиентом и Rust-обработчиком, если они используют общее пространство HTTP-путей. По умолчанию связь отключена и постоянные feature records не изменяет.

Установка и первый запуск

Требования: Node.js 22 или новее, Git 2.x и установленный совместимый агент для работы с кодом. Провайдер по умолчанию использует локальный Codex CLI. Для первого ревью выбранный агент должен быть установлен и авторизован.

npm install -g clawpatch

Или через pnpm:

pnpm add -g clawpatch

Минимальный рабочий сценарий:

cd /path/to/repository
clawpatch init
clawpatch map
clawpatch status
clawpatch doctor
clawpatch review --limit 3
clawpatch report

Команда init создаёт каталог .clawpatch/. Команда status покажет найденные срезы, а после ревью report сформирует отчёт по сохранённым находкам. Прогресс выводится в stderr. В командах с --json машиночитаемый результат остаётся в stdout, поэтому его можно передавать следующему шагу автоматизации.

Основные команды

clawpatch init                         # определить проект и создать конфигурацию
clawpatch map                          # построить карту семантических срезов
clawpatch status                       # показать состояние проекта и ревью
clawpatch doctor                       # проверить окружение и провайдера
clawpatch review --limit 10            # проверить очередную группу срезов
clawpatch review --since origin/main   # проверить срезы, затронутые изменениями
clawpatch next                         # выбрать следующую приоритетную находку
clawpatch show --finding <id>          # показать находку и доказательства
clawpatch triage --finding <id>        # изменить статус находки
clawpatch fix --finding <id>           # запустить одну попытку исправления
clawpatch revalidate --finding <id>    # повторно проверить находку
clawpatch report                       # сформировать Markdown-отчёт
clawpatch ci --since origin/main       # выполнить цикл для CI без изменения исходного кода
clawpatch open-pr --patch <id>         # опубликовать записанный патч отдельным PR

Выбор нужных срезов

Для точного набора срезов можно передать файл с одним ID на строку через --feature-list. Пустые строки игнорируются, повторные ID учитываются один раз в порядке первого вхождения.

Флаг нельзя сочетать с --feature, --project, --since и --include-dirty.

Параллельное и выборочное ревью

Пример параллельной обработки:

clawpatch review --limit 12 --jobs 4

Количество рабочих процессов (workers) по умолчанию равно половине доступных CPU-ядер и ограничено диапазоном от 1 до 10. Максимум для --jobs — 10. Частоту начала обращений к провайдеру можно ограничить флагом --rate-limit-per-minute или переменной CLAWPATCH_RPM в скользящем 60-секундном окне.

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

clawpatch clean-locks --stale-only

Она сохраняет живые локальные блокировки и блокировки с других хостов. Команда status показывает активные блокировки и количество lock-файлов.

Подключение агентов и провайдеров

Clawpatch не обращается к API моделей напрямую. Он запускает установленные инструменты для работы с кодом или CLI-агенты. Авторизация, транспорт модели и выполнение остаются на стороне выбранного инструмента.

Провайдер по умолчанию — локальный Codex CLI. Актуальный репозиторий также указывает:

• агентов, совместимых с ACP, через ACPX;
• Claude Code;
• Grok Build;
• OpenCode;
• Pi;
• экспериментальную интеграцию Cursor Agent.

Единой панели, которая одновременно опрашивает несколько провайдеров, пока нет.

Безопасность и границы автоматизации

• review и revalidate запрашивают у провайдера режим только для чтения (read-only).
• fix требует ID конкретной находки и по умолчанию отказывается работать с грязным исходным рабочим деревом Git (worktree).
• Попытка исправления сохраняет список изменённых файлов и результаты проверок.
• fix сам по себе не делает коммит и не отправляет изменения в удалённый репозиторий.
• Создание ветки, коммита и pull request требует отдельной команды open-pr.
• Clawpatch не сливает pull request.
• Ответы провайдера проходят проверку JSON-схемой и проверку доказательств по текущему содержимому файлов.
• Ограничения песочницы зависят от выбранного агента. Перед работой с недоверенным репозиторием нужно отдельно проверить его разрешения и режим изоляции.

Полезные сценарии

Ревью изменений перед слиянием

Задача: проверить изменения ветки до слияния.

Условие: ветка содержит изменения относительно origin/main.

Действие:

clawpatch review --since origin/main
clawpatch report

Наблюдаемый результат: отчёт ограничивается семантическими срезами, связанными с изменёнными owned files или context files. Если подходящих срезов нет, команда завершается без находок.

Ограничение: результат остаётся анализом агента и требует инженерного триажа.

Проверка в GitHub Actions

Задача: выполнять единый цикл проверки в CI.

Условие: GitHub Actions запускает Clawpatch в репозитории и передаёт базовую ссылку для сравнения.

Действие:

clawpatch ci --since origin/main --limit 20 --jobs 4 --output clawpatch-report.md

Наблюдаемый результат: появляется файл clawpatch-report.md; при наличии GITHUB_STEP_SUMMARY туда также добавляется краткое резюме.

Ограничение: цикл не изменяет исходный код, но не заменяет обязательные тесты и ручное ревью.

Исправление одной подтверждённой находки

Задача: применить исправление одной находки после проверки доказательств.

Условие: доказательства и состояние рабочего дерева проверены.

Действие:

clawpatch show --finding <id>
clawpatch fix --finding <id>
clawpatch revalidate --finding <id>
git diff

Наблюдаемый результат: одна записанная попытка патча, результаты настроенных проверок и diff для ручной оценки.

Ограничение: если проверки не настроены или провайдеру нельзя доверять запись, автоматический fix лучше не использовать.

Ревью большого монорепозитория частями

Задача: проверять большой монорепозиторий контролируемыми группами.

Условие: карта срезов уже построена, а корректность нескольких feature records проверена вручную.

Действие:

clawpatch map
clawpatch review --limit 10 --jobs 4
clawpatch status

Наблюдаемый результат: состояние сохраняется в .clawpatch/, поэтому следующий запуск продолжит работу.

Ограничение: полезность зависит от качества маппинга. Перед масштабным ревью проверьте, что в срезы попали правильные точки входа, тесты и границы доверия.

Как проверить результат

После первого запуска проверьте четыре наблюдаемых признака:

1. В .clawpatch/ появились конфигурация и записи проекта.
2. clawpatch status показывает найденные feature records.
3. После review в состоянии появились записи запуска и, если проблемы обнаружены, findings.
4. clawpatch report создаёт читаемый отчёт, а режим --json оставляет машиночитаемый результат в stdout.

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

Ограничения

• Качество ревью зависит от выбранного агента, маппинга и доступного контекста.
• Контекст ограничен. В конфигурации по умолчанию используются maxContextFiles: 24, maxOwnedFiles: 12 и maxFindingsPerFeature: 10.
• Параллельный запуск может упереться в квоты или ограничения агента; для этого предусмотрен rate limit.
• Автоматическая проверка доказательств снижает число выдуманных ссылок на код, но не устраняет ложные выводы.
• Поддержки панели для нескольких провайдеров пока нет.
• Опциональная проверка публикации npm-пакетов (registryVerifier.enabled) передаёт координаты пакета публичному реестру, поэтому по умолчанию отключена.

Официальные ссылки

• Сайт Clawpatch
• Репозиторий openclaw/clawpatch
• Документация
• Руководство по код-ревью
• Конфигурация
• История релизов

Следующий шаг

Для организации долговременного контекста агентов для работы с кодом пригодится руководство AGENTS.md / SESSION_NOTES — проектная память для coding-агентов

Если вы выбираете процесс агентного ревью для команды, полезно заранее определить границы доступа, обязательные проверки и порядок принятия патчей.

Если захотите обсудить, как это применить у себя или в команде — пишите в Telegram @pimenov