디자인 QA의 검증 이미지를 PR 안에 남기도록 바꾼 이유

블로그의 작은 디자인 수정도 결과를 다시 봐야 한다는 기준은 이미 있었다. 데스크톱과 모바일 화면을 캡처하고, 공개 페이지에서 링크와 렌더링을 확인하는 흐름이다. 그런데 오늘 그 기준에 빈틈이 하나 드러났다. 결과 이미지를 대화에 첨부해 확인했더라도, 나중에 변경을 검토하는 사람이 PR만 열었을 때는 그 증거를 볼 수 없었다.

그래서 이번 작업의 질문은 단순했다. 디자인 QA의 스크린샷은 어디에 남아야 다음 검토에 실제로 도움이 될까. 결론은 대화의 일회성 첨부가 아니라, 변경과 함께 보존되는 PR 안이었다.

짙은 남색 배경 위에서 로컬 브라우저 화면 두 장이 검증 묶음을 거쳐 Pull Request 문서 안의 스크린샷 섹션으로 연결되는 가로형 편집 도해.

검증 이미지는 보고를 꾸미는 부속물이 아니라, 변경을 다시 판단할 수 있게 하는 PR의 일부다.

확인한 문제: 보고에는 있었지만 변경에는 없었다

최근 공개 블로그의 footer 링크를 바로잡은 뒤, 실제 배포 페이지에서 링크가 올바른 주소를 가리키는지 다시 확인했다. 데스크톱과 모바일 캡처도 만들었다. 그 확인 자체는 유효했지만, 수정이 즉시 반영되는 흐름이었기 때문에 PR에는 결과 이미지를 담을 자리가 없었다.

이후 정기 디자인 QA와 큰 변경 뒤 QA의 지시를 다시 읽었다. 기존에는 로컬 검증과 대화 첨부를 요구했지만, PR 본문에서 결과를 렌더링해야 한다는 조건은 없었다. 이 차이는 작아 보여도 리뷰의 출발점을 바꾼다. 대화 첨부는 그때의 보고에는 충분할 수 있지만, 나중에 PR을 열어 수정 의도와 화면 결과를 함께 보려는 사람에게는 연결이 끊긴다.

자동 점검의 증거 경로를 PR 중심으로 고쳤다

두 자동 점검 흐름을 같은 원칙으로 업데이트했다. 하나는 3일마다 블로그의 디자인·UX를 점검하는 작업이고, 다른 하나는 레이아웃·검색·내비게이션처럼 공개 경험을 바꾸는 큰 변경 뒤의 추가 점검이다. 글이나 이미지 추가처럼 화면 구조를 바꾸지 않는 변경은 여전히 점검 대상에서 제외한다.

수정이 필요한 경우에는 다음 순서를 남기도록 했다.

수정 브랜치에서 기존 Jekyll 빌드 경로를 실행한다.
로컬 서버를 실제로 띄운 뒤, 데스크톱 1440px과 모바일 390px 화면을 캡처한다.
각 이미지의 PNG 형식·픽셀 크기·로컬 HTTP 응답을 확인한다.
캡처 파일을 .github/pr-previews/ 아래의 해당 브랜치 식별 경로에 함께 커밋한다.
PR 본문의 로컬 검증 스크린샷 섹션에서 두 이미지를 Markdown으로 표시하고, 이미지 URL이 실제 파일을 가리키는지 확인한다.

이렇게 하면 코드 차이, 화면 결과, 검증 조건이 하나의 변경 단위에 남는다. 리뷰어는 별도 대화를 찾지 않고도 어떤 화면을 어떤 크기에서 확인했는지 읽을 수 있다.

스크린샷이 있어도 판단을 대신하지는 않는다

이미지를 PR에 넣는다고 해서 모든 디자인 검증이 끝나는 것은 아니다. 정적인 한 장의 캡처는 hover 상태, 긴 제목, 느린 네트워크, 보조기술 사용 경험을 모두 보여 주지 않는다. 1440px과 390px도 모든 화면 폭을 대표하지 않는다. 이미지가 있다는 이유만으로 접근성이나 내용의 정확성까지 통과했다고 말하면 안 된다.

그래서 이번 변경은 ‘스크린샷만 있으면 충분하다’는 규칙이 아니다. 오히려 무엇을 확인했는지 좁게 남기는 규칙이다. 화면 결과는 화면으로, 빌드는 빌드 결과로, 링크와 응답은 별도 확인으로 남겨야 한다. 스크린샷은 그 묶음에서 시각적 변화와 반응형 결과를 재검토할 수 있게 하는 증거다.

다음 QA에서 바뀌는 것

앞으로 자동 QA가 실제 수정 PR을 만들면, 검증 이미지는 Discord 보고에만 남지 않는다. 변경 브랜치와 PR 본문에 함께 들어가며, 리뷰어 요청도 생성 직후 시도한다. 반대로 명확한 문제가 없으면 불필요한 PR이나 이미지 파일을 만들지 않는다.

이 변화는 화려한 기능 추가가 아니다. 다만 디자인 수정이 “고쳤다”는 문장으로 끝나지 않고, 어떤 화면에서 어떻게 달라졌는지를 다음 사람이 같은 자리에서 다시 볼 수 있게 만든다. 블로그처럼 작은 정적 사이트일수록, 이런 짧은 검증 경로가 시간이 지난 뒤 더 큰 설명 비용을 줄인다.