스마트폰에서 버그 수정을 시작해 인수 검수까지 완료하기: 이미지 링크 사례

Tactic Remote의 게시물 내에서 스크린샷은 정상적으로 보였지만, 원본 이미지를 열기 위한 링크가 페이지 URL로 다시 작성되고 있었습니다. 중국어 문서의 경우 공유 이미지 주소에 /zh-CN/이 추가되는 것을 의미했습니다. 이미지 자체는 존재했지만 링크가 잘못된 상태였습니다.

이것은 스마트폰에서 지시하기에 적절한 규모의 작업입니다. 구체적인 증상이 있고 검사할 변경 사항이 작으며 결과를 직접 확인할 수 있습니다. 또한 AI 지원 작업에서 흔히 발생하는 실수, 즉 처음에 실패했던 구체적인 동작을 확인하기 전에 "수정됨" 상태를 성급하게 받아들이는 문제를 드러내 줍니다.

아래 사례는 이 웹사이트의 실제 수리 작업에서 비롯되었습니다. 우리는 해당 수리 전후에 실제 URL 헬퍼(helper) 함수를 다시 실행했습니다. 과거의 실제 구현과 테스트는 컴퓨터에서 실행되었습니다. 아래의 메시지들은 Tactic Remote를 통해 전송할 수 있는 예시 프롬프트이며 전체 수리가 스마트폰에서 이루어진 대화 녹취록이 아닙니다. iPhone 스크린샷은 회귀 검사에 사용된 실제 이미지 리소스입니다. 코드 편집과 테스트는 iOS 로컬이 아닌 연결된 개발 컴퓨터에서 실행됩니다.

1. 동작, 예상 결과, 작업 범위 보고하기

"이미지들을 고쳐줘"라는 요청은 너무 많은 해석의 여지를 남깁니다. Agent가 정상 작동 중인 리소스를 교체하거나 문서를 다시 작성하거나 모든 언어 라우팅을 바꿀 수 있습니다. 더 나은 첫 메시지는 단일 동작과 계속 작동해야 하는 대상을 명확히 설명합니다.

중국어 iPhone 가이드에서 스크린샷은 표시되지만 원본 이미지를 열 때 잘못된 주소가 사용됩니다. 먼저 해당 링크 동작을 재현하세요. 공유 이미지는 기존 /images/ URL로 열려야 하며, 문서 및 설명서 링크는 계속 선택된 언어를 따라야 합니다. 코드를 편집하기 전에 가장 작은 수정 방안과 회귀 검사를 식별하세요. 문서 본문은 수정하지 말고, 이번 문제와 무관한 변경 사항도 건드리지 마세요.

전송하기 전에 웹사이트 프로젝트를 선택하고 대화의 디렉터리와 브랜치를 확인하세요. Agent가 다른 저장소를 언급하면 코드를 수정하기 전에 바로잡으세요. iPhone 설정 가이드에서 연결 방법을 다루며, 본 사례는 호스트와 대상 프로젝트를 사용할 수 있게 된 이후부터 시작됩니다.

이 보고에서 유용한 구분점은 "이미지는 표시되지만 링크가 변경된다"는 사실입니다. 이미지 요소는 src를 로드하며, 이를 클릭하면 둘러싸고 있는 링크의 href를 따릅니다. 첫 번째 동작만 확인하면 두 번째 동작을 놓치게 됩니다.

2. 패치를 적용하기 전에 실패 예제 요청하기

영향을 받은 리소스는 다음과 같습니다.

/images/editorial/mobile-guides/iphone-chat-mode.png

이전 헬퍼는 해당 파일 주소를 로컬 페이지처럼 취급했습니다. 그 출력 결과는 다음과 같았습니다.

두 버전 모두 위의 원본 이미지 주소를 변경 없이 그대로 반환해야 합니다.

영어 버전도 영향을 받았습니다. 페이지 정규화 과정에서 후행 슬래시가 추가되었기 때문입니다. 쿼리 문자열과 프래그먼트(fragment)가 포함된 이미지 주소에서도 해당 부분이 유실되었습니다. 공유 파일은 페이지 현지화 로직을 완전히 우회해야 했습니다.

원본 파일 주소를 그대로 사용한 로컬 HTTP 검사에서는 200, image/png가 반환되었습니다. 유효하지 않은 /zh-CN/images/...png 주소는 404를 반환했습니다. 이러한 요청은 로컬 후보 빌드를 대상으로 수행되었으며, 과거 프로덕션 환경의 장애나 영향을 받은 방문자 수를 측정한 수치가 아닙니다.

스마트폰에서 유용한 후속 지시는 다음과 같습니다.

실패하는 한 가지 케이스에 대해 입력 URL, 실제 출력, 예상 출력을 보여주세요. 대조군으로 일반 설명서 링크를 포함하세요. 테스트를 통과시키기 위해 예상 결과를 변경하지 마세요.

3. 수정 범위 검토하기

프로덕션 헬퍼는 이미 다운로드 가능한 예제들을 그대로 유지하고 있었습니다. 이번 수정은 동일한 조기 반환(early return) 조건에 공유 이미지를 추가하는 것이었습니다.

- if (href.startsWith('/examples/')) return href
+ if (href.startsWith('/examples/') || href.startsWith('/images/')) return href

페이지 링크는 여전히 기존의 언어 라우팅 함수를 사용합니다. 이는 의도적으로 이 웹사이트의 두 공유 리소스 디렉터리에 연결된 것이며, 마침표가 포함된 모든 URL이 현지화를 우회해야 한다는 규칙이 아닙니다.

Agent에게 대화창에서 변경된 파일 목록과 이 diff를 보여달라고 요청한 다음, 앱에서 제공하는 파일/변경 뷰에서 실제 변경 사항을 검사하세요. 표시된 브랜치와 경로를 선택한 프로젝트와 비교합니다. 응답에서 광범위한 라우팅 재작성을 제안하는 경우, 이 특정 오류에 대해 왜 그것이 필요한지 질문하세요.

과거의 수리는 문서 및 날짜 개선 사항과 함께 커밋되었습니다. 링크 수정 자체는 위의 작은 조건문이지만, 전체 커밋은 한 줄짜리 변경이 아니었습니다. 여러분의 작업에서는 패치를 수락하기 전에 전체 diff를 검토하고 관련 없는 기존 작업을 별도로 고려하세요.

4. "passed"라는 단어만이 아닌 테스트 결과 확인하기

이 사례를 위해 웹사이트의 8개 언어 각각에 대해 6가지 기대치를 실행했습니다.

이는 총 48개의 검사이며 기록된 결과는 다음과 같습니다.

16개의 실패는 8개 언어에 걸친 2개의 이미지 관련 기대치였습니다. 이는 16개의 손상된 문서나 16명의 사용자 또는 16개의 개별 버그를 의미하는 것이 아닙니다. 통과한 대조군이 매우 중요합니다. 모든 링크의 현지화를 단순히 중단하는 패치는 이미지 예제는 고칠 수 있지만 설명서 탐색 기능을 망가뜨리게 됩니다.

실행 가능한 재현 파일 다운로드 후 검토하고 개발 컴퓨터에서 실행해 보세요.

node image-link-regression.mjs

이 스크립트는 Node의 내장 단언문(assertion)을 사용하며 메모리 내에서 실행되고 네트워크 요청이나 파일 변경을 수행하지 않습니다. TypeScript 타입이 제거된 상태에서 수리 전후의 관련 URL 동작을 포함합니다. 그 결과는 저장소의 실제 리비전을 대상으로 별도로 실행한 결과와 일치합니다. 이는 집중된 재현 도구이며 프로젝트의 전체 빌드나 통합 검사를 대체하지는 않습니다.

스마트폰에서 검토한 변경 사항과 연결할 수 있는 증거를 요구하세요.

정확한 명령, 디렉터리, 브랜치 또는 커밋, 종료 상태 코드 및 실패한 단언문을 보고하세요. 완료된 검사와 권장만 하는 검사를 구분하세요. 테스트 후 패치를 편집하는 경우 해당 버전에서 영향을 받는 검사를 다시 실행하세요.

원래 웹사이트 수리 당시에는 저장소의 lint, 프로덕션 빌드 및 SEO 검사도 통과했습니다. 이러한 광범위한 검사는 서로 다른 영역을 다루며, 그 자체만으로 사용자가 브라우저에서 원본 이미지를 열 수 있음을 증명하지는 못합니다.

5. 로컬 미리보기에서 사용자 동작 반복하기

이제 문제를 드러냈던 글로 돌아가세요. 본문 인라인 이미지가 여전히 로드되는지 확인하고, 원본을 열어 오류 페이지가 아닌 이미지인지 확인한 후 글로 돌아옵니다. 일반 설명서 링크도 확인하세요. 영어와 번역된 버전에서, 그리고 좁은 스마트폰 화면 너비에서 이를 반복하세요.

미리보기가 컴퓨터에서 실행 중일 때, 물리적 iPhone에서 연 127.0.0.1 주소는 휴대폰 자체를 가리킨다는 점을 기억하세요. 다른 기기에서 확인하려면 프로젝트의 기존 미리보기 접근 경로를 사용하세요. 데스크톱 브라우저 폭을 휴대폰 너비로 조정하는 것은 유용한 레이아웃 증거가 되지만 물리적 iPhone 테스트를 대신할 수는 없습니다.

6. 명확한 중단점에서 결과 인수하기

이 사례에서 수리된 로컬 사이트는 검사를 통과했으며 로컬 미리보기 검토에서 인수되었습니다. 그 인수는 웹사이트 후보 버전을 대상으로 한 것이었으며 업데이트를 배포하지는 않았습니다. 또한 과거 작업이 전적으로 iPhone에서 조작되었음을 의미하지도 않습니다.

유사한 작업의 경우 최종 메시지는 구체적일 수 있습니다.

로컬 미리보기에서 원본 이미지와 설명서 링크를 확인했습니다. 이 패치와 회귀 검사를 유지하세요. 남아 있는 제한 사항을 요약한 후 배포하거나 추가 변경을 진행하기 전에 중단하세요.

미리보기를 열지 않았다면 남아 있는 사항을 대신 명시하세요. "헬퍼 검사는 통과했으며, 시각적 인수는 아직 보류 중입니다." Agent의 유휴 상태, 초록색 테스트 요약, 눈에 보이는 결과에 대한 여러분의 인수 검수는 서로 다른 질문에 답합니다.

이 사례에서 재사용 가능한 부분은 그 순서에 있습니다. 실패한 동작 설명, 대조군 유지, 정당화되는 최소한의 변경 검사, 해당 버전에 검사 연결, 다음 단계를 결정하기 전 사용자 동작 반복입니다. 개발 컴퓨터가 코드 작업을 처리하는 동안 여러분은 스마트폰으로 이러한 결정을 내릴 수 있습니다. 진행 중에 대화가 응답하지 않으면 동일한 지시를 다시 보내기 전에 연결 및 전달 상태 문제 해결 가이드를 확인하세요.