프리랜딩 셀프 리뷰은(는) 무엇을 하나요?
중요한 변경 사항을 커밋하기 전에 이 체크리스트를 실행하세요. CI가 잡아내기 전에, 아니면 사용자가 발견하기 전에 문제를 잡으세요.
사용 시기
다음 중 하나라도 해당되면 이 스킬을 실행하세요:
- 100줄 이상 코드 변경
- 5개 이상 파일 수정
- 핵심 인프라(executor, storage, main dispatch loops) 건드림
- 새로운 추상화나 공개 API 도입
- 엣지 케이스나 설계 결정에 확신이 없음
빠른 확인:
git diff --stat HEAD | tail -5 # 얼마나 변경되었나요?
git diff --name-only HEAD | wc -l # 몇 개 파일인가요?
건너뛰기 조건
- 사소한 변경 (≤50줄, ≤3개 파일)
- 순수 문서 또는 강의 업데이트
- 테스트 전용 변경 (테스트는 그 자체로 리뷰임)
- 명확하고 범위가 제한된 간단한 한 줄 버그 수정
- 논리 변경 없는 기계적 리팩토링
체크리스트
1. 엣지 케이스
- [ ] null/빈 입력이 처리되었나요?
- [ ] 경계 조건이 테스트되었나요(off-by-one, 빈 리스트, 0)?
- [ ] 동시 접근 또는 경쟁 조건이 고려되었나요?
- [ ] 텍스트 처리 시 유니코드/인코딩 문제를 확인했나요?
2. 오류 경로
- [ ] 모든 예외가 적절한 수준에서 포착되었나요(너무 광범위하지 않게)?
- [ ] 오류 메시지가 유익한가요(무엇이 실패했는지, 왜, 어떻게 해결할지)?
- [ ] 실패 모드가 정상적으로, 조용히 실패하지 않고 처리되나요?
- [ ] `except:`만 사용하거나 오류를 삼키는 경우가 없나요?
3. 테스트 커버리지
- [ ] 중요한 경로에 테스트가 있나요?
- [ ] 위에서 식별한 엣지 케이스에 대한 테스트가 있나요?
- [ ] 테스트가 실제로 실행되고 통과하나요?
- [ ] `pass`나 `...`로 남겨진 테스트 스텁이 없나요?
4. 문서화
- [ ] 독스트링/주석이 현재 동작과 일치하나요?
- [ ] 공개 인터페이스가 변경된 경우 README가 업데이트되었나요?
- [ ] 커밋 메시지에 무엇이 변경되었고 왜 변경되었는지 담겨 있나요?
- [ ] 관련 아키텍처 문서가 여전히 정확한가요?
5. 코드 품질
- [ ] 이름이 명확하고 주변 코드와 일관성 있나요?
- [ ] 명백한 코드 냄새(God 함수, 매직 넘버, 하드코딩된 경로)가 없나요?
- [ ] 파일/패키지의 기존 패턴을 따르나요?
- [ ] 정적 분석/타입 검사가 통과하나요?
원라이너 스모크 테스트
# 커밋 전 실행 (스택에 맞게 조정):
make format && make typecheck && pytest -x -q && echo "✅ 안전하게 배포 가능"
어떤 단계든 실패하면 커밋 전에 수정하세요. 빨간불을 보낼 수 없습니다.
반패턴
| 반패턴 | 해결책 |
|---|---|
| "CI가 잡을 거야" | CI는 최후의 수단일 뿐, 당신의 판단을 대체할 수 없습니다. 먼저 잡으세요. |
| "나중에 테스트를 추가할게" | 나중은 오지 않습니다. 지금 테스트를 작성하거나, 그 공백을 영원히 받아들이세요. |
| "수동 테스트에서는 잘 동작했어" | 수동 테스트는 재현 가능하지 않습니다. 자동화된 테스트를 작성하여 향후 세션에서도 검증할 수 있게 하세요. |
| "오류 메시지는 TODO예요" | TODO 오류 메시지는 TODO 오류 메시지 그대로 배포됩니다. 지금 진짜 메시지를 작성하세요. |
| "코드를 보니 이 케이스를 처리하는 게 분명해" | 테스트되지 않았다면, 미래의 리팩토링이 보이지 않게 깨뜨릴 것입니다. |
이것이 중요한 이유
자율 에이전트는 수정을 피할 만큼 충분히 좋은 출력을 생성하도록 훈련됩니다. 구조화된 리뷰 게이트가 없으면 자율 코드 커밋은 일반적으로 회귀와 엣지 케이스를 잡아내는 인간-인-더-루프 검사를 건너뜁니다. 이 스킬은 그 게이트 역할을 합니다 — 다섯 가지 초점 렌즈를 순차적으로 적용하여 명백한 것이 빠져나가지 않도록 합니다.
그 효과는 누적됩니다: 각 리뷰가 실제 문제를 잡을 때마다 CI 왕복 시간이 절약되고, 사용자 버그가 방지되며, 되돌리기 PR이 필요 없어집니다.
관련 링크
- 셀프 푸시 스킬 — 이 구조적 리뷰를 보완하는 품질/게으름 검사
- 멀티 렌즈 리뷰 스킬 — 중요도가 높은 변경을 위한 심층 병렬 리뷰