이미지가 삐져나가는 버그, 처음엔 그냥 넘어갈 뻔했다. 블로그 글을 올리고 나서 멀쩡히 보이는지 확인하는 건 습관이다. 그날도 그냥 훑어보고 있었다.
이미지가 삐져나가는 버그, 눈에 띄는 이상함: 스크린샷 하나가 삐져나가 보였던 이유
본문을 읽다가 뭔가 이상했다. 스크린샷 하나가 오른쪽으로 쏠려 있었다. 다른 이미지들은 멀쩡한데 그것만.
이유는 몰랐다. 그냥 딱 봐도 어색했다. 바로 Claude Code(클로드 코드, AI 기반 코딩 보조 도구)에 말했다. “지금 본문에서 이 이미지만 오른쪽으로 쏠려있어. 사이즈 조절해서 중앙으로 보기 좋게 다시 작성해줘.” 원인 분석보다 고치는 게 먼저였다.
아래가 당시 상태다. 텍스트 컬럼(column, 본문이 들어가는 세로 영역) 오른쪽으로 이미지가 넘쳐 있다.
이렇게 이미지가 본문 영역 밖으로 삐져나오면 레이아웃(layout, 화면 배치 구조) 전체가 깨진 것처럼 보인다. 작은 것 같지만 실제로 읽는 사람 입장에서는 바로 티가 난다.
원인은 간단했다: 업로드 스크립트가 이미지를 줄이지 않고 있었네
원인은 허무했다. 업로드 스크립트(script, 특정 작업을 자동으로 처리하는 코드 파일)가 이미지를 그대로 박아넣고 있었다. 리사이즈(resize, 이미지 크기를 줄이거나 늘리는 작업) 없이. 원본 그대로.
원본 이미지의 가로 크기가 본문 컬럼 폭보다 훨씬 넓었다. 그러니 오른쪽으로 넘칠 수밖에 없다. 알고 나니 별거 아니었다. 근데 이게 지금까지 계속 이렇게 올라가고 있었다는 게 더 문제였다.
이 버그(bug, 코드나 프로그램에서 발생하는 오류) 자체는 금방 고칠 수 있다. 문제는 따로 있다.
버그 수정만으로는 부족한 이유: 같은 실수가 반복되면?
지금 이 이미지만 고치고 끝내면 어떻게 될까. 다음에 글 올릴 때 또 같은 일이 생긴다. 스크립트가 그대로니까.
버그를 발견했을 때 그 버그만 패치(patch, 문제가 생긴 부분만 부분적으로 고치는 것)하고 넘어가는 건 임시방편이다. 원인이 코드 안에 남아 있으면 같은 실수는 반드시 다시 나온다. 타이밍만 다를 뿐이다.
그래서 바로 한 마디 더 붙였다. “처음부터 작성할 때 이런 것 체크해서 최종 마무리해줘.” 재발 방지까지 해야 진짜 끝난 거라고 생각했다.
자동화로 근본 해결하기: 스크립트에 리사이즈 기능 추가하기
수정 방향은 하나였다. 업로드 스크립트 자체를 고치는 것.
이미지를 올릴 때마다 수동으로 크기를 확인하는 건 지속 가능하지 않다. 귀찮으면 빠뜨리게 돼 있다. 그러니 스크립트가 알아서 처리하게 만드는 게 맞다.
Claude Code에 요청해서 업로드 스크립트를 수정했다. 핵심은 두 가지다.
- 새 글을 올릴 때 이미지가 자동으로 본문 폭에 맞게 리사이즈된다.
- 리사이즈된 이미지는 중앙 정렬(center align, 요소를 화면 가운데에 배치하는 것)로 삽입된다.
이제 이미지 크기를 신경 쓰지 않아도 된다. 스크립트가 처리한다. 이게 자동화(automation, 사람이 직접 하던 작업을 코드가 대신 처리하도록 만드는 것)의 의미다. 한 번 제대로 만들어두면 그 다음부터는 신경 끄면 된다.
재발 방지까지: 업로드 후 최종 확인 프로세스 정하기
스크립트를 고치는 것만으로는 완전하지 않다고 봤다. 코드가 제대로 동작하는지 눈으로 확인하는 단계가 없으면 또 다른 문제가 조용히 지나갈 수 있다.
그래서 규칙을 명확히 정했다. Claude Code에 이렇게 못 박았다.
- 이미지는 본문 폭 안에 딱 맞게, 중앙 정렬로 들어가야 한다.
- 업로드 후에는 Claude Code가 직접 최종 확인을 하고, 그 결과를 나한테 컨펌(confirm, 맞는지 확인하고 승인받는 것)받아야 한다.
- 스크린샷으로 실제 화면을 직접 확인하는 것을 기본으로 한다.
코드만 고치고 “됐겠지” 하고 넘어가지 않는다. 반드시 눈으로 확인한다. 이게 기준이다.
이 사례에서 배울 점: 코드만 고치지 말고 프로세스도 함께
이번 건 작은 버그였다. 이미지 하나가 삐져나간 것. 근데 거기서 멈추지 않은 게 핵심이다.
버그를 고치는 건 시작이다. 왜 생겼는지 파악하고, 같은 일이 반복되지 않도록 구조를 바꾸고, 확인 단계까지 만드는 것이 진짜 마무리다.
AI 도구를 쓸 때 “고쳐줘”만 하고 끝내는 사람이 많다. 그러면 똑같은 질문을 다음 달에 또 하게 된다. “왜 또 이러지?” 하면서.
물어봐야 할 건 두 가지다.
- 지금 이걸 어떻게 고치냐.
- 앞으로 이게 안 생기려면 뭘 바꿔야 하냐.
두 번째 질문을 안 하면 첫 번째 질문을 계속 반복한다.
다음에는 업로드 스크립트 전체를 한 번 훑어볼 생각이다. 이미지 말고 다른 곳에서도 비슷한 게 조용히 지나가고 있을 수 있다. 결국 이미지가 삐져나가는 버그 하나가 전체 업로드 파이프라인을 점검하게 만든 셈이다.
비슷한 패턴은 다른 데서도 반복됐다. WPCode로 보안 헤더 추가하다 코드가 깨진 사례도 결국 같은 교훈이었다 — 자동화 도구를 만들 땐 “일단 되는 것”과 “제대로 확인된 것”은 다르다.