Two-Stage Code Review

Адаптировано из Superpowers для SENTINEL DevKit

Философия

Традиционный code review смешивает две разные задачи:

• Соответствие спецификации — делает ли код то, что нужно?

• Качество кода — хорошо ли написан код?

Смешивание ведёт к пропуску ошибок. Разделяем на два прохода.

Stage 1: Spec Compliance Review

Фокус

• Реализует ли код ВСЕ требования из спецификации?

• Нет ли пропущенных edge cases?

• Соответствует ли поведение acceptance criteria?

Checklist

• Все требования из spec покрыты
• Все acceptance criteria выполнимы
• Edge cases из spec обработаны
• Error states соответствуют spec
• API contracts соблюдены

НЕ проверяем на этом этапе

• Naming conventions

• Code style

• Performance optimizations

• Refactoring opportunities

Stage 2: Code Quality Review

Фокус

• Читаемость и maintainability

• Соответствие паттернам проекта

• Performance considerations

• Security implications

Checklist

• Clean Architecture соблюдена
• Нет code smells (God objects, long methods)
• Naming понятное и консистентное
• Error handling корректный
• Нет security anti-patterns
• Тесты читаемые и независимые

Workflow (DOT)

digraph two_stage_review { rankdir=TB; node [shape=box, style=rounded];

start [label="Code Ready for Review"];
stage1 [label="Stage 1: Spec Compliance\n(Reviewer A)"];
stage1_fail [label="Spec Issues Found", style=filled, fillcolor=salmon];
stage2 [label="Stage 2: Code Quality\n(Reviewer B or same)"];
stage2_fail [label="Quality Issues Found", style=filled, fillcolor=salmon];
fix [label="Fix Issues", style=filled, fillcolor=lightyellow];
approved [label="✅ Approved", style=filled, fillcolor=lightgreen];

start -> stage1;
stage1 -> stage1_fail [label="FAIL"];
stage1 -> stage2 [label="PASS"];
stage1_fail -> fix;
stage2 -> stage2_fail [label="FAIL"];
stage2 -> approved [label="PASS"];
stage2_fail -> fix;
fix -> stage1 [label="re-review"];

}

Когда использовать

Ситуация Two-Stage?

Новый engine ✅ Да

Bugfix ⚠️ Stage 1 минимальный

Refactoring ⚠️ Stage 2 основной

Security-критичный код ✅ Да + Security Audit

Интеграция с SENTINEL

Для Engine Development

• Stage 1: Проверить что engine обрабатывает ВСЕ payloads из spec

• Stage 2: Проверить Clean Architecture, performance, edge cases

Для Shield Components

• Stage 1: Protocol compliance, API compatibility

• Stage 2: Memory safety, performance, code style

Anti-patterns

❌ Смешивание стадий — "код работает, но naming плохой" на Stage 1 ❌ Пропуск Stage 1 — "код красивый, наверное работает"

❌ Один reviewer на обе стадии без паузы — свежий взгляд важен