self-review

name	self-review
description	구현 완료 후 thinking mode 심층 리뷰 — 즉시 반영 항목을 수정하고 결과를 보고한다. clean pass까지 반복이 필요하면 ralph를 통해 실행한다
user-invocable	true

Self Review

구현 완료 후 thinking mode로 변경 사항을 심층 분석하고 타당한 개선을 코드에 반영한다. 반복 실행이 필요하면 /ralph /self-review로 ralph에 위임한다.

1. 변경 사항 수집

• 인자가 전달되면 (/self-review <base-branch>) 해당 브랜치를 기준점으로 사용한다.
• 인자가 없으면 아래 절차로 기준점을 결정한다.
• git fetch로 remote 상태를 최신화한다. 실패하면 경고를 출력하고 기존 local ref로 진행한다.
• remote tracking branch를 기준점으로 결정한다.
  • git rev-parse --abbrev-ref @{upstream}로 tracking branch를 확인한다.
  • tracking branch가 없으면 git remote show origin | grep 'HEAD branch'로 remote 기본 브랜치를 조회하고, origin/<branch> 형태로 사용한다.
  • 위 방법이 모두 실패하면 사용자에게 base branch를 직접 지정하도록 요청한다.
• git log <base>..HEAD --oneline으로 unpushed commit 목록을 확인한다.
• unpushed commit이 없으면 "리뷰 대상 없음"을 보고하고 즉시 종료한다.
• git diff <base>..HEAD로 push되지 않은 커밋의 전체 변경 범위를 파악한다.
• uncommitted 변경이 있으면 사용자에게 알리고, 리뷰 범위에 포함할지 확인한다. 포함하면 git diff + git diff --staged도 함께 수집한다. 포함하지 않으면 커밋된 변경만 리뷰한다. 리뷰 중 수정 사항을 커밋할 때는 리뷰 수정분만 staging하여 uncommitted 작업이 섞이지 않게 한다.
• 변경된 파일의 전체 내용을 읽는다. diff만으로는 주변 컨텍스트를 놓칠 수 있다. 단, 바이너리 파일, lockfile, 자동 생성물은 제외한다.
• 현재 작업의 scope 문서가 있으면 함께 읽어 scope을 확인한다.

2. 심층 분석 (thinking mode)

extended thinking을 활용하여 다음을 분석한다:

정합성 검증

• 변경된 코드가 호출하는 함수, 의존하는 타입, 참조하는 상수가 실제로 존재하고 올바른지 확인한다.
• 새로 추가된 인터페이스/타입과 기존 구현체 간의 계약이 맞는지 검증한다.
• import 경로, export 누락, 순환 참조를 확인한다.

로직 검증

• 분기가 빠짐없이 처리되는지 확인한다 (switch/if-else 분기의 완전성).
• 에러 경로에서 리소스 정리, 상태 롤백이 올바른지 확인한다.
• 경계 조건 (null, empty, 0, max) 처리를 확인한다.
• 비동기 코드에서 await 누락, 에러 전파 누락을 확인한다.

설계 정합성

• 프로젝트의 architecture 문서가 있으면 계층 책임과 일치하는지 확인한다.
• roadmap / workstream 문서가 있으면 현재 workstream 범위 내인지 확인한다.
• .claude/rules/의 현재 구현 규칙을 위반하지 않는지 확인한다.
• 현재 작업의 scope 문서가 있으면 scope 범위 내인지 확인한다.
• 문서 간 충돌이 있으면 Architecture > Roadmap > Rules > Scope 우선순위를 따른다.
• 모듈 간 의존 방향이 설계 의도와 맞는지 확인한다.

테스트 충분성

• 변경된 로직의 주요 경로와 에러 경로에 대응하는 테스트가 있는지 확인한다.
• 테스트가 구현 세부사항이 아니라 계약/동작을 검증하는지 확인한다.

3. 평가 기준

각 발견 항목을 다음 기준으로 분류한다:

• 즉시 반영: 버그, 누락된 에러 처리, 계약 불일치, 명확한 설계 위반. 코드에 직접 수정을 적용한다.
• 사용자 판단 필요: 설계 트레이드오프, 의도적일 수 있는 선택, scope 경계의 항목. 수정하지 않고 보고만 한다.
• 무시: 이전 리뷰 단계에서 이미 다뤄진 항목, 스타일 선호, 범위 밖 개선 제안. 개별 내용은 보고하지 않되, 건수와 대표 사유는 보고 형식에 포함한다.

4. 수정 적용

• 즉시 반영 항목은 코드를 직접 수정한다.
• 수정 후 프로젝트의 빌드 검증과 테스트를 실행하여 수정이 다른 것을 깨뜨리지 않았는지 확인한다.
• 테스트가 실패하면 원인을 먼저 분류한다:
  • 수정이 원인인 경우: 수정을 되돌리고 사용자 판단 필요로 재분류한다.
  • 기존 flaky 테스트나 환경 문제인 경우: 수정을 유지하고 실패 원인을 보고한다.
• 수정이 완료되면 수정 사항을 commit한다.

5. 중단 기준

다음 중 하나라도 해당하면 push 진행을 중단하고 사용자에게 보고한다:

• 심각도 높은 버그가 발견되고 즉시 반영으로 해결되지 않은 경우 (보안, 데이터 손실, 인증/권한 우회)
• 동일 변경에서 버그가 2개 이상 발견되고 즉시 반영으로 해결되지 않은 경우
• 설계 원칙 위반이 발견된 경우
• 수정 적용 후 빌드 또는 테스트가 실패하고, 단순 수정으로 해결되지 않는 경우
• 동일한 지적이 수렴하지 않고 계속 발생하는 경우 (순환 판단)

6. 보고 형식

리뷰 결과를 사용자에게 다음 형식으로 보고한다:

즉시 반영한 항목

(각 항목: 파일, 변경 내용, 발견 근거. 없으면 없음)

사용자 판단이 필요한 항목

(각 항목: 파일, 지적 내용, 판단을 미룬 이유. 없으면 없음)

무시한 항목

(건수와 대표 사유. 없으면 없음)

리뷰 요약

(전체 변경 품질에 대한 1-2문장 평가)