dmitrl-dev/aisecurity/two-stage-review

Two-Stage Code Review

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

Философия

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

1. Соответствие спецификации — делает ли код то, что нужно?
2. Качество кода — хорошо ли написан код?

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

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"];
}

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

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

Для Engine Development

1. Stage 1: Проверить что engine обрабатывает ВСЕ payloads из spec
2. Stage 2: Проверить Clean Architecture, performance, edge cases

Для Shield Components

1. Stage 1: Protocol compliance, API compatibility
2. Stage 2: Memory safety, performance, code style

Anti-patterns

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