여러분의 앱에는 이미 사용자와 저장된 데이터, 그리고 사람들이 믿고 쓰는 동작이 있습니다. 버그를 고치거나 기능을 추가하려고 개발자를 들일 때는 이런 기존의 약속도 작업의 일부가 됩니다.
저는 현재 시스템과 필요한 변경 사항을 이해하는 것부터 시작합니다. 명확한 예시, 관련 서비스의 전체 구성, 계속 작동해야 하는 것들의 목록이 있으면 큰 도움이 됩니다. 이 가이드에서는 무엇을 준비하면 되는지, 사전 검토에서 무엇을 기대할 수 있는지 설명합니다.
변경 사항을 사용자 행동으로 설명하기
“앱이 느려요”도 출발점으로는 쓸모가 있습니다. 하지만 “휴대폰에서 주문 내역이 많은 고객의 주문 페이지를 열면 몇 초가 걸린다”고 하면 조사할 대상이 분명해집니다. 새 기능이라면 사용자가 무엇을 할 수 있어야 하는지, 지금은 무엇을 할 수 있는지 적어 주세요.
버그라면 재현 단계, 기대한 결과, 실제로 일어난 일을 보내 주세요. 관련이 있어 보이면 기기나 브라우저도 적어 주세요. 짧은 화면 녹화도 도움이 되지만, 공유하기 전에 고객 정보와 개인 메시지는 지워 주세요.
문제가 얼마나 자주 생기는지, 누구에게 영향을 주는지, 우회 방법이 있는지도 알려 주세요. 실제 고객의 결제가 실패하는 문제와 내부 페이지의 화면 깨짐은 대응 방식이 다릅니다.
조사를 시작하기에 충분한 정보를 담은 가상의 버그 보고 예시입니다.
주문 페이지에서 “최근 30일”을 선택한 뒤 검색 결과의 두 번째 페이지를 엽니다. 날짜 필터가 초기화되고 더 오래된 주문이 나타납니다.
기대 결과: 결과 페이지를 넘겨도 날짜 필터가 그대로 선택되어 있어야 합니다.
제 노트북의 Chrome에서 매번 발생합니다. 직원들은 주문 번호로 검색해서 우회할 수 있지만, 최근 주문을 검토하는 데 시간이 더 걸립니다.
현재 시스템의 구성 알려 주기
기술적인 세부 사항을 모두 아실 필요는 없습니다. 아는 부분부터 시작하고, 나머지는 누구에게 물어보면 되는지 알려 주세요.
코드가 어디에 있는지, 저장소의 소유자는 누구인지, 지금 운영 중인 버전은 무엇인지.
애플리케이션이 어디에서 실행되는지, 변경 사항은 지금 어떻게 배포하는지.
사용하는 데이터베이스, 파일 저장소, 외부 서비스.
설치 방법, 자동 검사, 기존 문서.
알려진 문제, 마무리되지 않은 작업, 이 문제를 해결하려 했던 이전의 시도.
이전 개발자나 다른 팀에 질문할 수 있는지 여부.
스테이징 환경(변경 사항을 고객에게 내보내기 전에 시험하는 별도의 사본)이 있다면 접근 방법을 알려 주세요. 없다면 작업에 필요해질 때 마련하는 것을 계획하겠습니다.
기존 링크, 저장된 데이터, 사용자 권한, 외부 연동, 아직 고객 휴대폰에 설치되어 있는 앱 버전처럼 현재 시스템이 지켜야 하는 것도 알려 주세요. 새 화면 하나를 이야기할 때는 쉽게 놓치는 부분입니다.
접근 권한은 초대로 공유하기
저장소, 호스팅, 도메인, 결제 계정의 소유권은 직접 가지고 계세요. 개발자는 각 서비스의 접근 관리 기능으로, 작업에 필요한 권한만 주어 초대하시면 됩니다. 서비스가 지원한다면 사전 검토는 읽기 전용 권한과 테스트 환경으로 시작할 수 있습니다.
비밀번호, 운영 환경 API 키, 고객 데이터 내보내기 파일, 환경 설정 파일 전체를 브리프에 붙여 넣지 마세요. 필요한 비밀 정보를 따로 전달하는 방법은 함께 정하면 됩니다. 문제를 재현하는 데는 실제 고객 데이터에 대한 무제한 접근보다 테스트 계정과 샘플 데이터가 대개 더 유용합니다.
견적 전에 사전 검토의 내용 이해하기
기존 코드에서는 어떻게 실행되는지 확인하고, 관련 동작을 추적하고, 변경이 영향을 줄 수 있는 부분을 파악해야 합니다. 따로 떨어져 보이는 기능도 권한, 결제, 데이터베이스 마이그레이션에 영향을 줄 수 있습니다.
사전 검토의 범위와 조건은 시작하기 전에 합의합니다. 검토 결과 보고서에는 다음 내용이 담겨야 합니다.
무엇을 살펴봤는지, 무엇을 재현할 수 있었는지, 아직 부족한 접근 권한이나 정보는 무엇인지.
권장하는 변경 사항과 고려해 볼 만한 다른 방법.
영향을 받을 수 있는 기존 기능이나 데이터.
작업을 어떻게 확인하고, 릴리스하고, 문제가 생기면 어떻게 되돌릴지.
지금 견적을 낼 수 있는 부분과 추가 조사가 필요한 부분.
새로 만들기 전에 이유 묻기
오래된 코드도 여전히 제 역할을 잘하고 있을 수 있습니다. 다른 프레임워크를 쓰고 싶다거나 새 개발자의 취향과 다르다는 것은 잘 돌아가는 시스템을 교체할 이유로는 약합니다. 대개는 범위를 좁힌 수정, 빠져 있던 테스트 추가, 단계적인 업그레이드가 올바른 변경입니다.
교체가 타당한 경우도 있습니다. 현재 시스템으로는 합리적으로 충족할 수 없는 요구 사항이 무엇인지, 남길 수 있는 부분은 어디인지, 전환은 어떻게 진행할지 물어보세요. 비교할 때는 새 시스템을 만드는 작업뿐 아니라 데이터를 옮기고 기존 동작을 유지하는 작업도 포함해야 합니다.
변경 사항이 사용자에게 전달되는 방식 합의하기
배포하기 전에 변경 사항을 어떻게 테스트할지, 누가 검토할지, 문제가 생기면 어떻게 할지 알고 있어야 합니다. 운영 중인 제품이라면 합의된 릴리스 계획과 되돌릴 방법이 있어야 합니다. 코드를 되돌린다고 데이터 변경까지 되돌려지지는 않을 수 있으므로, 데이터베이스 마이그레이션에는 별도의 계획이 필요합니다.
날짜 필터 예시라면 페이지를 넘겨도 선택이 유지되는지, 다른 필터도 제대로 작동하는지 확인합니다. 수정 사항이 실제 사이트에 반영되기 전에 미리보기에서 그 동작을 직접 확인하실 수 있어야 합니다.
인계할 때는 무엇이 바뀌었는지, 어떻게 확인했는지, 후속 작업은 무엇인지 볼 수 있어야 합니다. 새로운 설치 단계, 설정 변경, 알려진 제약 사항은 문서에 남겨야 합니다.
처음에 보내 주시면 좋은 내용
제품과 사용자에 대해: …
기능 또는 문제와 그 예시: …
계속 작동해야 하는 것: …
코드, 호스팅, 현재 개발자에 대해 알고 있는 것: …
영향, 우선순위, 마감일(있다면): …
문의 양식으로 이런 내용을 먼저 보내 주세요. 도움을 요청하기 전에 프로젝트 전체를 정리하거나 기술 문서를 작성하실 필요는 없습니다.