Роли агентов и 3-слойная модель review

1. Граница роли важнее списка возможностей

Когда роль, триггер запуска, формат результата и stop conditions уже собраны, самое время проверить их на первой по-настоящему рабочей специализации. Ею почти всегда оказывается reviewer: узкий, чтобы не расползтись в «агента на всё», и полезный, чтобы сразу встроиться в review-процесс.

Когда вы впервые настраиваете агента, очень хочется думать в духе «а давайте дадим ему побольше инструментов, чтобы был полезнее». Мысль естественная, но именно с неё начинается хаос — роль расползается, ответственность за ней. На выходе не reviewer, не tester и не debugger, а очень инициативный знакомый, который обещал посмотреть diff, а к вечеру уже переписал полпроекта.

У роли агента есть четыре простые опоры: что он читает, что запускает, что пишет и где обязан остановиться. Не определена хоть одна — у вас не роль, а расплывчатое пожелание. «Это reviewer-агент» — недостаточно, пока эти четыре оси не заданы явно.

Именно поэтому граница роли начинается не со слов «умеет делать review», а со слов «не имеет права править код». Сначала периметр, потом таланты. Иначе агент решит, что он не просто ревьюер, а ревьюер, разработчик, архитектор и, если дать ещё пять минут, немного психотерапевт вашего репозитория.

В контексте нашего Workflow Kit это особенно важно. Файл agents/reviewer.md нужен не ради красивой папки .claude/agents/, а как предсказуемый артефакт: человек открывает его и сразу видит — агент не внедряет изменения, не спорит со scope, не «чинит заодно» стиль и соседние модули. Одна работа: проверить diff и вернуть findings.

2. Четыре базовые роли агентов

Чтобы не собирать каждого нового агента с нуля, полезно иметь базовые шаблоны ролей. В курсе их четыре: reviewer, tester, debugger и documenter — не «все возможные агенты мира», а четыре понятных каркаса, из которых потом удобно собирать почти всё остальное. И здесь очень помогает смотреть на них не через красивые названия, а через оси read, run, write, stop.

Теперь давайте переведём таблицу на человеческий язык. reviewer проверяет: соответствует ли diff задаче, не вылез ли за scope, есть ли evidence, не потеряны ли edge cases. Дайте право редактировать код — и он смешивает автора и проверяющего.

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

debugger нужен, когда вы ещё не уверены, в чём причина ошибки. Начал «заодно рефакторить модуль, раз уж разбирался» — вышел из роли. Его результат: root cause, evidence и минимальный план исправления, а не архитектурное обновление века.

documenter многим кажется самой безобидной ролью — и в этом ловушка. Без опоры на код документация становится красивым вымыслом. Он пишет только то, что подтверждается командами, файлами и реальным поведением системы.

Ниже — короткий пример findings от reviewer-агента для PR в Commerce OS:

severity: medium
file: payments/RefundService.java:48
evidence: есть проверка статуса заказа, но нет проверки роли оператора
suggested_action: добавить guard и целевой тест на доступ

Хороший результат роли всегда выглядит именно так: коротко, проверяемо, без драмы и без внезапного «я уже всё починил».

3. Схема роли: read, run, write, stop

На предыдущей лекции вы уже разбирали тело инструкции как контракт. Сейчас полезно посмотреть на то же самое чуть более технологично: четыре опоры описывают любую роль и ложатся на reviewer, tester и любую будущую специализацию без магии и без литературных талантов. Откройте agents/reviewer.md из Workflow Kit не как frontmatter, а как схему обязанностей:

read: diff, related files, tests
run: only safe local checks, если они разрешены текущей конфигурацией
write: nothing
stop: if diff is too broad or touches a sensitive area

Точные названия tools и capability IDs зависят от текущего интерфейса /agents — держите в голове не список букв, а границу роли.

Здесь особенно важны две вещи. Ось write пуста — у reviewer нет права писать. И последняя строка инструкции не декоративная: Остановись, если diff слишком широк — не вежливая просьба, а инженерное правило. Не пропишете — агент будет «полезным» до конца и начнёт комментировать всё подряд, включая то, что пора отправить на декомпозицию.

Новички часто совершают одно и то же доброе, но вредное действие: выдают reviewer write-доступ «на случай мелких правок». Сегодня опечатка, завтра форматирование, послезавтра «слегка улучшил» условие в бизнес-логике — и это уже не reviewer, а тихий соавтор diff. Маленькое неудобство честнее удобного агента. С другими ролями так же: tester пишет только в тестовые файлы, documenter только в docs. Теряете ось write — роль течёт; теряете stop conditions — течёт долго.

Но этой схемы мало, чтобы понять место reviewer-а в процессе: она описывает только саму роль. Дальше нужна ещё одна координата — кто смотрит на доказательства и на каком gate решает, идти ли дальше. Тесты, сборка, lint, логи остаются осью доказательств.

4. Трёхслойная модель review

До этого момента мы говорили о ролях как будто они существуют сами по себе. Но в реальной разработке агент не висит в вакууме — он встраивается в review-процесс команды. Здесь работает простая 3-слойная модель, и отвечает она не «чем проверяем», а «кто и когда вправе сказать: идём дальше».

Сегодня нас интересует прежде всего Layer 1 — именно здесь живёт reviewer-агент текущего уровня. Пока diff перед глазами, контекст свежий, откат дешёвый, он ловит грубые проблемы до того, как изменение уедет в дорогие слои. Полезно представить это как лестницу:

flowchart TD
    D[Локальный diff] --> L1[Layer 1: локальный review]
    L1 --> L2[Layer 2: gate и автоматические проверки]
    L2 --> L3[Layer 3: team approval]

Модель из трёх слоёв полезна даже новичку. Нет Layer 1 — сырые изменения уходят сразу в дорогую часть процесса. Нет Layer 2 — технический барьер на совести людей. Нет Layer 3 — чувствительные решения проходят потому, что «вроде всё зелёное». Локальный reviewer — не весь review, а первый, самый быстрый и дешёвый слой. Он не притворяется Layer 2 и Layer 3: не утверждает релиз, не заменяет командное решение, не ставит финальную печать. Скромнее — и потому надёжнее.

5. Review и verification: различия

Здесь действительно легко всё смешать: рядом оказываются review-слои и уже знакомая verification-ось. Но задачи у них разные — review-слои нужны как карта места reviewer в процессе, verification отвечает за сами доказательства. Давайте аккуратно разведём это, пока суп не убежал.

Мнемоника короткая:

L + число — это verification.
Layer + число — это review.

На примере Commerce OS это выглядит так. Допустим, вы чините возврат средств. Verification говорит — запусти регрессионный тест, проверь целевой сценарий, убедись, что сборка цела. Review говорит другое — сначала локально прочитай diff, потом пропусти через технический gate, а если задета чувствительная финансовая логика, финальное решение за человеком.

То есть verification — доказательства, review — ворота. reviewer-агент Layer 1 не подменяет тесты: он проверяет, что доказательства есть, подходят к задаче и что diff не делает вид, будто всё проверено, когда на деле проверено полтора сценария и два молитвенных жеста над терминалом. Это различие на самом деле очень освобождает: перестаёте требовать от него «и найди баги, и сам всё проверь, и реши, можно ли в prod» — и честная роль оказывается лучше универсального комбайна, который умеет всё, но не отвечает ни за что.

6. Layer 1: специализации одного reviewer

Когда базовая reviewer-роль стала понятной, возникает следующий соблазн: а давайте создадим отдельного агента на каждый случай жизни. reviewer-security, reviewer-performance, reviewer-tests, reviewer-architecture, reviewer-db, reviewer-frontend и парочку на тяжёлый понедельник. Технически возможно, методически — не всегда. Гораздо полезнее думать о них как о специализациях одной reviewer-роли.

Смысл здесь очень практичный: один базовый шаблон reviewer, а фокус задаётся инструкцией, вариацией description или дополнительным контекстом. Иначе .claude/agents/ превращается в маленький зоопарк, где половина агентов отличается на одну фразу, а вторая забыла, зачем её создавали.

В Commerce OS это хорошо видно на одном и том же diff. security reviewer посмотрит, не обошли ли проверку прав при возврате средств. performance reviewer заметит лишний запрос в цикле. test quality reviewer спросит, почему нет теста на повторный запрос возврата. Не три механики — три пары очков у одного локального reviewer-слоя. Хотите оформить специализацию файлом — она компактна:

---
name: reviewer-security
description: Read-only reviewer focused on auth, secrets and input validation
tools: [read, grep, run_static_analysis]
---

Но это всё ещё Layer 1 reviewer. Он не превращается в службу безопасности компании — смотрит на тот же diff под более узким углом.

7. agents/reviewer.md как живой артефакт

Самая полезная мысль финала этой лекции очень простая: агент — не «настройка в продукте», а живой артефакт команды. Его читают, ревьюят, обновляют и иногда честно упрощают. agents/reviewer.md хорош ровно настолько, насколько помогает пройти Layer 1 review быстрее и аккуратнее, без ложного чувства безопасности.

Когда кодовая база меняется, должен меняться и агент. Появились в Commerce OS новые чувствительные зоны — reviewer должен знать, где они. Устали от ложных срабатываний на мелком стиле — ужмите инструкцию. Diff постоянно слишком широкие — проблема не в reviewer, а в размере задач. Хороший агент не лечит организационные болезни магией — он делает их виднее.

Поэтому относитесь к agents/reviewer.md как к шаблону PR, чек-листу релиза или CLAUDE.md: часть рабочего процесса, а не священный текст. И держите его на своём месте в модели: это Layer 1, самый быстрый и дешёвый слой, а не gate и не team approval. Reviewer-агент ловит грубые риски по свежему diff и передаёт материал дальше — он не заменяет ни автоматические проверки, ни решение владельца зоны. Знает свою границу — экономит команде дорогие слои review; притворяется всем сразу — даёт ложное чувство безопасности. Ясная роль на понятном слое: ровно этого мы от него и хотим.