Урок 17.11. Ревью кода: запрашиваем и принимаем

Дополнительные источники: https://github.com/obra/superpowers/blob/main/skills/receiving-code-review/SKILL.md, https://github.com/obra/superpowers/blob/main/skills/requesting-code-review/code-reviewer.md

Зачем это нужно

Шестой шаг базового workflow (урок 17.5) — пара скиллов, закрывающая ревью с двух сторон: requesting-code-review (как диспетчеризовать ревьюера) и receiving-code-review (как отвечать на замечания). В курсе ревью — сквозная тема: независимый ревьюер как роль разбирался в уроке 11.3; двухступенчатое ревью задач (соответствие плану → качество кода) — в уроке 17.9. Здесь перевод обоих скиллов и правила, которые они навязывают участникам.

Особенность пары: requesting определяет механику свежего контекста и критичность замечаний; receiving — единственный скилл Superpowers, построенный вокруг коммуникации: как агент (и человек) отвечает на обратную связь, не впадая в перформативное согласие и слепое исполнение.

Основная идея

requesting-code-review: ревьюер — сабагент со свежим контекстом, которому передается точно собранная информация — никогда история вашей сессии. Принцип: «Review early, review often» — ревью рано, ревью часто. Обязательные моменты: после каждой задачи в subagent-driven (урок 17.9), после крупной фичи, перед merge в main.

receiving-code-review: ревью требует технической оценки, а не эмоционального перформанса. Принцип: «Verify before implementing. Ask before assuming. Technical correctness over social comfort» — проверь до исполнения, спроси до предположения; техническая корректность выше социального комфорта.

Запрашиваем: requesting-code-review

Когда ревью обязательно

после каждой задачи в subagent-driven development;
после завершения крупной фичи;
перед merge в main.

Ценно и необязательно: когда застряли (свежий взгляд), перед рефакторингом (бейзлайн), после сложного багфикса.

Как диспетчеризовать

Получить git- SHA:

bash
BASE_SHA=$(git rev-parse HEAD~1)  # или: git merge-base origin/main HEAD
HEAD_SHA=$(git rev-parse HEAD)

Диспетчеризовать сабагента general-purpose по шаблону code-reviewer.md с плейсхолдерами: {DESCRIPTION} (что построено, кратко), {PLAN_OR_REQUIREMENTS} (что должно делать — задача из плана), {BASE_SHA}/{HEAD_SHA} (диапазон коммитов).
Поступить по обратной связи: Critical — чинить немедленно; Important — чинить до продолжения; Minor — заметить на потом; ревьюер неправ — возражать с рассуждением.

Ключевые правила диспетчер-промпта (из таблицы рационализаций скилла):

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

Пример из скилла

[Завершена задача 2: функция верификации]

BASE_SHA=$(git log --oneline | grep "Task 1" | head -1 | awk '{print $1}')
HEAD_SHA=$(git rev-parse HEAD)

[Диспетчеризован ревьюер]
  DESCRIPTION: Added verifyIndex() and repairIndex() with 4 issue types
  PLAN_OR_REQUIREMENTS: Task 2 from docs/superpowers/plans/deployment-plan.md
  BASE_SHA: a7981ec
  HEAD_SHA: 3df7661

[Сабагент вернулся]
  Strengths: Clean architecture, real tests
  Issues:
    Important: Missing progress indicators
    Minor: Magic number (100) for reporting interval
  Assessment: Ready to proceed

→ чинить progress indicators; продолжать к задаче 3

Красные флаги запрашивающего

Никогда: пропускать ревью «потому что просто»; игнорировать Critical; продолжать с неисправленными Important; спорить с верной технической обратной связью. Ревьюер неправ: возражать техническим рассуждением, показать код/тесты, попросить уточнение.

Принимаем: receiving-code-review

Паттерн ответа

WHEN receiving code review feedback:

1. READ: прочитать полностью, не реагируя
2. UNDERSTAND: пересказать требование своими словами (или спросить)
3. VERIFY: проверить против реальности кодовой базы
4. EVALUATE: технически здраво ДЛЯ ЭТОЙ кодовой базы?
5. RESPOND: техническое подтверждение или аргументированное возражение
6. IMPLEMENT: по одному пункту, каждый с тестом

Запрещенные ответы

Никогда: «You're absolutely right!», «Great point!», «Excellent feedback!» (перформатив), «Let me implement that now» (до проверки). Вместо: пересказать техническое требование; задать уточняющий вопрос; возразить с рассуждением; просто начать работать («действия > слова»).

Неясная обратная связь

Если любой пункт неясен — стоп, ничего не исполнять до выяснения: пункты могут быть связаны, частичное понимание = неверная реализация. Пример скилла: «Fix 1-6», вы поняли 1, 2, 3, 6, неясны 4 и 5 — неправильно исполнить понятное и спросить потом; правильно: «Понял пункты 1, 2, 3, 6. Нужны уточнения по 4 и 5 до продолжения».

Источник замечаний решает

От партнера: доверие выше — исполнить после понимания; спросить при неясном scope; без перформатива; к действию.

От внешних ревьюеров — пять проверок до исполнения: технически верно для этой кодовой базы? ломает существующую функциональность? есть причина текущей реализации? работает на всех платформах/версиях? понимает ли ревьюер полный контекст? Похоже на ошибку — возразить с рассуждением. Не можете проверить — сказать: «Не могу проверить без X. Исследовать / спросить / продолжать?» Конфликт с прежними решениями партнера — остановиться и обсудить с ним.

Проверка YAGNI для «профессиональных» фич

Предложение «сделать по-нормальному» (метрики с базой, фильтрами, CSV-экспортом) — сначала grep по кодовой базе: эндпоинт не вызывается — «Убрать его (YAGNI)?»; вызывается — реализовывать нормально. Правило скилла от партнера: «Вы и ревьюер оба подчиняетесь мне. Если фича не нужна — не добавлять ее».

Порядок исполнения много-пунктовых замечаний

выяснить все неясное — сначала;
потом в порядке: блокирующие (ломает, безопасность) → простые (опечатки, импорты) → сложные (рефакторинг, логика);
каждый фикс — с индивидуальным тестом;
проверить отсутствие регрессий.

Когда возражать

Возражать, когда: предложение ломает существующую функциональность; ревьюер не знает полного контекста; нарушает YAGNI (неиспользуемая фича); технически неверно для стека; есть причины совместимости/легаси; конфликтует с архитектурными решениями партнера. Как: техническое рассуждение вместо защиты; конкретные вопросы; ссылка на работающие тесты/код; партнер — если вопрос архитектурный.

Отдельное правило: «Если вам некомфортно возражать вслух — назовите этот дискомфорт и сообщите партнеру о проблеме, которую увидели. Он оценит честность».

Подтверждение верных замечаний

✅ "Fixed. [Что изменилось]"
✅ "Good catch - [конкретная проблема]. Fixed in [место]."
✅ [Просто починить и показать в коде]

❌ "You're absolutely right!"   ❌ "Great point!"
❌ "Thanks for catching that!"  ❌ благодарности любого вида

Почему без благодарностей: «Actions speak. Just fix it. Код сам показывает, что вы услышали замечание». Поймали себя на «Thanks» — удалить и назвать фикс. Возражали и оказались неправы: констатировать фактом и чинить («Verified this and you're correct. My initial understanding was wrong because <причина>. Fixing»), без длинных извинений и защиты.

Ответы в GitHub

Ответы на инлайн-комментарии ревью — в треде комментария (gh api repos/{owner}/{repo}/pulls/{pr}/comments/{id}/replies), не как топ-уровневый комментарий PR.

Связь с циклом исполнения

Пара скиллов замыкает контур с уроком 17.9: ревью задачи возвращает находки → контроллер не «спорит», а adjudирует по правилам receiving; Critical/Important входят в цикл фиксов; Minor — в журнал для финального триажа. Финальное ревью ветки (урок 17.9) диспетчеризуется по requesting на самой способной модели; находки финального волны обрабатываются по правилам receiving — с проверкой YAGNI и возражениями на ложные находки.

Практика

Возьмите открытый PR коллеги (или свой старый коммит) и составьте замечания, классифицировав их Critical/Important/Minor. Проверьте: каждое ли замечание — о поведении и доказуемо, а не о вкусе?
Найдите в этом же диффе одно замечание, на которое «неправильный» агент ответил бы перформативно («Great point!»). Напишите правильный ответ по паттерну: пересказ → проверка → вердикт.
Сымитируйте YAGNI-проверку: предложите «профессиональную» фичу к диффу и прогоните grep — вызывается ли код, который она улучшает?

Краткое резюме

Ревью в Superpowers — пара скиллов. requesting-code-review: ревьюер — свежий сабагент с точно собранным контекстом (никогда — история сессии); Critical чинится немедленно, Important — до продолжения; координатор не ревьюит инлайн. receiving-code-review: техническая проверка вместо перформатива — прочитать, пересказать, проверить, оценить, ответить технически; неясное — стоп до выяснения; YAGNI-проверка «профессиональных» предложений; благодарности заменены фиксами.

Обязательные моменты ревью: после каждой задачи, после крупной фичи, перед merge.
Порядок много-пунктовых замечаний: блокирующие → простые → сложные, каждый фикс с тестом.
Возражать — техническим рассуждением; неправы после возражения — констатировать фактом и чинить.

Вопросы для самопроверки

Почему ревьюеру запрещено передавать историю сессии? Что теряет ревьюер, а что сохраняет координатор?
Какие три класса критичности и как с каждым поступает агент? Какой класс блокирует переход к следующей задаче?
Опишите шесть шагов паттерна приема замечаний. Почему «Let me implement that now» — запрещенный ответ?
Почему неясный пункт останавливает исполнение всех пунктов, включая понятные?
Что такое YAGNI-проверка «профессиональных» предложений и какой инструмент ее выполняет?
Как правильно «благодарить» за верное замечание по скиллу? Обоснуйте правило.

Что дальше

Все задачи реверьюены, замечания закрыты — седьмой, завершающий шаг базового workflow: урок 17.12 разбирает finishing-a-development-branch: верификация, опции интеграции и очистка рабочего дерева.

Источники

https://github.com/obra/superpowers/blob/main/skills/requesting-code-review/SKILL.md