Chapter 7: Code Review

Code review는 품질 게이트입니다 — 형식적 절차도 아니고, 퍼포먼스도 아니며, 사교적 의례도 아닙니다. Superpowers는 code review를 피드백을 요청하고 받는 것 모두에 대한 명시적인 프로토콜을 갖춘 엄격한 기술 활동으로 취급합니다.

Part 1: Code Review 요청하기

구조가 중요한 이유

구조 없는 code review 요청("이것 리뷰해줄 수 있어요?")은 구조 없는 피드백을 만들어냅니다. Reviewer는 코드가 무엇을 해야 하는지, 어떤 문제를 해결하는지, 어떤 tradeoff가 있었는지 모릅니다. 그 결과는 중요한 문제를 놓치는 표면적인 댓글입니다.

구조화된 요청은 reviewer에게 진정으로 유용한 피드백을 제공하는 데 필요한 모든 것을 줍니다.

Context 준비하기

Reviewer를 파견하기 전에 다음 세 가지 정보를 준비하세요:

WHAT — 이 변경은 무엇을 합니까? 다음을 설명하는 2~4개의 문장을 작성하세요:

해결되는 문제
취한 접근 방식
주요 설계 결정과 그 이유
하지 않는 것과 그 이유

PLAN — 구현 계획은 무엇이었습니까? 이 작업을 안내한 계획에 링크하거나 요약하세요. 이를 통해 reviewer는 구현이 의도와 일치하는지 확인할 수 있습니다.

BASE_SHA → HEAD_SHA — 검토 중인 정확한 commit 범위:

# base 가져오기 (브랜치가 main에서 분기된 곳)
git merge-base main HEAD

# 현재 HEAD 가져오기
git rev-parse HEAD

이렇게 하면 reviewer가 정확히 올바른 diff를 보게 됩니다 — 관련 없는 commit이나 전체 히스토리가 아닙니다.

Reviewer Subagent 파견하기

Context가 준비되면, 다음 구조로 code review subagent를 파견하세요:

REVIEW REQUEST
--------------
WHAT: [변경 사항에 대한 2~4문장 설명]

PLAN: [구현 계획의 링크 또는 요약]

DIFF RANGE: [BASE_SHA]..[HEAD_SHA]

FOCUS AREAS: [선택 사항: 면밀히 검토하고 싶은 특정 영역]

Subagent는 diff를 검사하고, 계획에 대조하여 확인하고, 관련 test를 실행하고, 구조화된 피드백을 반환합니다.

심각도별 Review 피드백 처리하기

모든 피드백이 동일한 긴급도를 갖지는 않습니다. 각 심각도 수준에 따라 다르게 처리하세요:

심각도	정의	조치
Critical	버그, 보안 문제, 데이터 손실 위험, 깨진 contract	완료를 차단합니다. 다른 작업 전에 즉시 fix하세요.
Important	중요한 품질 문제, 누락된 test, 성능 문제	다음 작업 시작 전에 fix하세요. 축적하지 마세요.
Minor	스타일 선호도, 명명 제안, 선택적 개선	기록하세요. 후속 ticket을 만드세요. 현재 PR을 gold-plate하지 마세요.

가장 흔한 실수는 모든 피드백을 동일하게 긴급하게 취급하는 것입니다. Critical 문제는 차단합니다. Minor 문제는 기록됩니다. 이를 혼동하면 사소한 스타일 피드백으로 지연이 발생하거나 실제 버그를 무시하게 됩니다.

Part 2: Code Review 받기

핵심 문제: 형식적 동의

AI agent — 그리고 많은 개발자들 — 은 code review 중 형식적 동의를 하는 경향이 있습니다. 이는 reviewer가 무언가를 제안하면, 구현자가 즉시 "맞습니다! 바로 수정하겠습니다!"라고 말하며 제안이 올바른지 진정으로 평가하지 않고 변경을 하는 것입니다.

형식적 동의는 해롭습니다. 왜냐하면:

작동하는 코드에 잘못된 제안을 적용합니다
Reviewer가 무조건적 compliance를 기대하도록 훈련시킵니다
축적된 나쁜 제안을 통해 시간이 지남에 따라 코드 품질을 저하시킵니다
Review가 실제 문제를 찾아내고 있다는 허위 확신을 줍니다

금지된 표현

다음 표현은 형식적 동의를 나타내며 허용되지 않습니다:

금지된 표현	이유	대신 사용할 표현
"맞습니다!"	평가 없이 검증함	"수정했습니다. X를 Y로 변경했습니다. 이유: [이유]."
"잘 발견하셨어요!"	사교적 칭찬, 내용 없음	"확인했습니다. 문제는 Z였습니다."
"바로 수정하겠습니다"	이해 전에 약속함	"지금 읽어보고 있습니다."
"완전히 이해가 됩니다"	분석 없이 동의함	"우려 사항을 이해합니다. 제 평가는: ..."
"맞습니다, 제가 ~했어야 했는데..."	행동 없는 자기비하	"구현했습니다. 변경된 사항은 다음과 같습니다."

대체 표현은 사실에 집중합니다: 무엇이 변경되었는지, 왜 변경되었는지, 무엇이 검증되었는지.

올바른 응답 패턴

Code review 댓글을 받으면, 이 순서를 정확히 따르세요:

READ → UNDERSTAND → VERIFY → EVALUATE → RESPOND → IMPLEMENT

READ: 참조된 코드나 문서를 포함하여 전체 댓글을 읽으세요. 읽는 동안 응답하지 마세요.

UNDERSTAND: 자신의 말로 reviewer의 우려 사항을 설명할 수 있습니까? 그렇지 않다면, 명확한 질문을 하세요. 의도를 추측하지 마세요.

VERIFY: 실제 코드를 보고 우려 사항이 유효한지 확인하세요. 해당되는 경우 관련 test를 실행하세요. 정신 모델이 아닌 실제 동작을 보세요.

EVALUATE: YAGNI 체크를 적용하세요 (You Aren't Gonna Need It):

이 변경이 현재 요구사항에 필요합니까?
실증된 실제 문제를 해결합니까?
Codebase가 현재 정당화하지 않는 복잡성을 추가합니까?
이것이 합법적인 best practice입니까, 아니면 개인적인 스타일 선호도입니까?

RESPOND: 본능적 동의가 아닌 평가에 기반한 응답을 작성하세요.

IMPLEMENT: 제안이 유효하다면 구현하세요. 유효하지 않다면 추론을 설명하세요.

Reviewer 제안에 대한 YAGNI 체크

"여기에 caching을 추가해야 합니다" 또는 "이것을 generic interface로 추상화해야 합니다"라고 제안하는 reviewer는 옳을 수도 있습니다 — 하지만 YAGNI 테스트를 적용해야 합니다:

현재 요구사항이 실제로 caching을 필요로 합니까? 성능 문제에 대한 측정된 증거가 있습니까?
지금 당장 추상화에 대한 두 개 이상의 구체적인 사용 사례가 있습니까?

답이 아니오라면, 올바른 응답은: "잠재적인 미래 개선 사항으로 기록해두었습니다. 현재 요구사항에는 더 간단한 접근 방식으로 충분합니다. 후속 항목으로 기록했습니다."

유효한 Pushback 시나리오

Review 피드백에 pushback하는 것이 허용될 뿐만 아니라 — 다음과 같은 경우에는 반드시 해야 합니다:

제안이 버그를 도입합니다. 제안된 변경이 잘못된 동작을 만들어내는 이유를 test나 구체적인 예시로 보여주세요.
제안이 확립된 계획을 위반합니다. 구현 계획이 검토되고 승인되었다면, 이탈은 code review 중 일방적인 변경이 아닌 명시적 재승인이 필요합니다.
제안이 scope 밖입니다. 제안이 좋을 수 있지만, 별도의 작업에 속합니다. 지금 구현하면 scope가 확장되고, 배포가 지연되며, 혼합 목적의 commit이 생성됩니다.
제안이 정확성 영향이 없는 스타일 선호도입니다. 스타일 선호도는 linter config에 속하지 code review 피드백에 속하지 않습니다. 자동화할 수 없다면, PR을 차단할 가치가 없을 것입니다.
코드가 올바르다고 검증했으며 reviewer가 틀렸습니다. 증거를 명확하고 존중스럽게 제시하세요. 틀릴 수도 있습니다 — 하지만 반드시 논거를 제시해야 합니다.

Pushback 템플릿

Pushback 시, 이 구조를 사용하세요:

이 제안을 평가했습니다. 제 판단:

CONCERN: [Reviewer의 우려 사항을 정확하게 재서술]
INVESTIGATION: [이를 평가하기 위해 확인한 것]
FINDING: [발견한 것]
DECISION: [구현 / 나중을 위해 기록 / 이유와 함께 동의하지 않음...]
EVIDENCE: [Test 출력, 참조, 또는 구체적인 예시]

이렇게 하면 추론을 감사할 수 있게 되고, review 대화가 사실에 집중하게 됩니다.

요약

잘 수행된 code review는 가장 강력한 품질 도구 중 하나입니다. 형식적 승인이나 compliance 극장으로 잘못 수행된 code review는 시간을 소비하면서 품질을 생산하지 않기 때문에 review가 없는 것보다 나쁩니다.

Superpowers 프로토콜은 review의 양쪽이 엄격하도록 보장합니다: reviewer는 필요한 context를 얻고, 구현자는 사회적 compliance가 아닌 기술적 정직함으로 피드백을 평가합니다.