신입 개발자의 포트폴리오를 검토하면서 프로젝트에서 가장 해결하기 어려웠던 오류가 무엇인지 질문한 적이 있습니다. 준비생은 개발 과정에서 문제가 많았지만 검색을 통해 대부분 해결했기 때문에 특별히 기록할 만한 경험은 없다고 답했습니다. 그러나 커밋 내역과 작업 노트를 다시 살펴보니 상품 상세 화면에서 간헐적으로 이전 상품의 정보가 나타났던 문제가 있었습니다. 준비생은 처음에 서버가 잘못된 데이터를 반환한다고 생각해 백엔드 담당자에게 API 확인을 요청했지만, 서버 기록에서는 요청받은 상품 ID에 맞는 응답을 정상적으로 보내고 있었습니다.
화면의 네트워크 기록을 비교하자 사용자가 상품을 빠르게 이동할 때 먼저 보낸 요청이 늦게 도착하면서 최신 결과를 덮어쓰는 현상이 확인되었습니다. 준비생은 단순히 요청을 다시 보내는 방식으로 임시 대응했지만 같은 상황이 반복되었습니다. 이후 상품 ID가 변경될 때 이전 요청을 취소하고 현재 화면에서 요청한 상품과 응답의 ID가 일치할 때만 상태를 변경하도록 수정했습니다. 느린 네트워크 환경을 만들어 빠르게 상품을 이동하는 상황을 다시 시험했고, 로딩 상태와 요청 실패 화면도 함께 점검했습니다.
처음에는 기록할 필요가 없다고 생각한 오류였지만 실제로는 가설 설정, 로그 확인, 원인 범위 축소, 코드 수정, 재검증이 모두 포함된 경험이었습니다. 완성된 기능만 보여주는 프로젝트보다 이런 과정이 담긴 자료에서 지원자의 실무적인 사고방식이 더 잘 드러납니다. 디버깅 경험을 포트폴리오에 넣을 때는 버그가 있었다는 사실을 강조하는 것이 아니라 오류원인, 해결과정, 개선결과가 어떻게 이어졌는지 보여줘야 합니다.
보이는 현상과 실제 오류원인을 구분해서 기록해야 합니다
- 화면에 나타난 현상만으로 원인을 단정하지 않아야 합니다
디버깅을 시작할 때 가장 먼저 해야 할 일은 사용자가 본 현상과 개발자가 추정한 원인을 분리하는 것입니다. 저장 버튼을 눌렀는데 화면이 멈췄다는 것은 현상이며, 서버에 문제가 있다는 것은 아직 확인되지 않은 가설입니다. 버튼 이벤트가 실행되지 않았거나 요청 데이터가 잘못되었을 수 있고, 서버는 정상 처리했지만 화면 상태가 갱신되지 않았을 수도 있습니다.
한 팀 프로젝트에서는 회원가입 버튼을 누르면 오류 안내가 표시되지 않은 채 화면이 그대로 멈추는 문제가 발생했습니다. 프런트엔드 담당자는 서버가 응답하지 않는다고 생각했고 백엔드 담당자는 자신의 테스트에서는 정상이라고 답했습니다. 브라우저의 네트워크 기록을 함께 확인해 보니 서버는 중복 이메일에 대해 409 응답과 오류 정보를 보내고 있었습니다. 문제는 화면에서 성공 응답만 처리하고 실패 응답을 사용자에게 표시하지 않은 것이었습니다.
준비생은 서버 장애라는 최초 판단을 수정하고 응답 코드에 따라 입력 오류, 중복 이메일, 일시적인 서버 문제를 구분해 안내하도록 변경했습니다. 수정 후 신규 이메일, 중복 이메일, 잘못된 형식, 서버 연결 실패를 각각 재현해 화면의 동작을 다시 확인했습니다. 이런 기록은 다른 담당자를 탓하지 않고 요청 흐름을 따라 문제를 확인한 경험으로 활용할 수 있습니다.
- 현상은 관찰한 사실만으로 작성하는 것이 좋습니다. 회원가입이 안 되었다는 표현보다 중복 이메일로 가입 버튼을 눌렀을 때 요청은 전송되지만 오류 문구가 화면에 나타나지 않았다고 적으면 재현 조건이 분명해집니다.
- 최초 가설은 정답처럼 쓰지 않아야 합니다. 서버 응답 지연을 의심했지만 네트워크 기록에서 오류 응답이 정상적으로 도착한 것을 확인했다는 식으로 판단이 달라진 근거를 남겨야 합니다.
- 에러 메시지는 검색어가 아니라 확인할 위치를 알려줍니다
오류 문구를 그대로 검색하면 비슷한 해결 방법을 찾을 수 있지만 현재 프로젝트의 원인이 같다고 보장할 수는 없습니다. 에러 메시지에 표시된 파일, 줄 번호, 상태 코드, 예외 종류를 먼저 읽고 어느 단계에서 실패했는지 파악해야 합니다. 검색 결과는 가설을 만드는 참고 자료로 사용하고 실제 적용 여부는 자신의 데이터와 실행 환경에서 확인해야 합니다.
한 백엔드 프로젝트에서는 게시글 저장 시 데이터베이스 제약 조건 오류가 발생했습니다. 준비생은 검색 결과를 보고 칼럼의 빈 값 허용 설정을 바꾸려 했지만 오류 메시지에 표시된 칼럼은 작성자 ID였습니다. 요청 데이터를 확인하니 로그인 정보는 정상적으로 전달되었지만 게시글 객체를 생성하는 과정에서 작성자 값을 연결하지 않은 상태였습니다. 데이터베이스 설정을 완화했다면 오류는 사라질 수 있어도 작성자가 없는 게시글이 저장되는 더 큰 문제가 남을 수 있었습니다.
- 오류를 없앤 설명: 데이터베이스 설정을 수정해 저장 오류를 해결했습니다.
- 원인을 확인한 설명: 오류 메시지에 표시된 작성자 칼럼을 확인하고 요청값과 저장 직전의 데이터를 비교했습니다.
- 판단 과정이 드러나는 설명: 게시글 저장 과정에서 작성자 ID가 비어 있다는 제약 조건 오류가 발생했습니다. 처음에는 데이터베이스 설정 문제를 의심했지만 요청에는 인증 정보가 정상적으로 포함되어 있었습니다. 저장 객체를 만드는 단계에서 사용자 정보가 누락된 것을 확인해 연결 로직을 수정했고, 로그인 사용자와 비로그인 사용자의 요청을 각각 다시 시험했습니다.
- 같은 현상을 만드는 원인이 여러 개일 수 있습니다
화면이 열리지 않는 현상은 서버 중지, 네트워크 설정, 애플리케이션 오류, 데이터베이스 연결 실패 등 여러 이유로 발생할 수 있습니다. 따라서 하나의 가능성에 집중하기보다 요청 흐름을 작은 구간으로 나누어 어디까지 정상인지 확인해야 합니다. 브라우저 요청, 웹 서버 접근 기록, 애플리케이션 로그, 데이터베이스 상태를 순서대로 살펴보면 확인 범위를 줄일 수 있습니다.
실제로 배포된 서비스에서 상품 목록만 빈 화면으로 나타났던 프로젝트가 있었습니다. 개발 환경에서는 정상이라 환경변수 문제를 의심했지만 서버 로그에는 데이터베이스 칼럼을 찾을 수 없다는 오류가 남아 있었습니다. 최근 배포 내용을 확인하니 상품 상태 칼럼을 추가한 코드는 반영되었지만 운영 데이터베이스에는 변경된 구조가 적용되지 않았습니다.
준비생은 누락된 변경을 반영한 뒤 상품 조회뿐 아니라 등록과 수정 기능도 다시 확인했습니다. 이후 배포 절차에 데이터베이스 변경 여부를 확인하는 단계를 추가했습니다. 같은 빈 화면이라는 현상이라도 프런트엔드 상태 문제와 데이터 구조 불일치 문제는 확인 방법이 다르다는 점을 이해한 사례입니다.
가설을 세우고 범위를 줄인 해결과정이 역량을 보여줍니다
- 재현 조건을 찾으면 확인해야 할 범위가 작아집니다
간헐적으로 발생하는 문제는 바로 코드를 수정하기보다 언제 나타나는지부터 찾아야 합니다. 특정 사용자에게만 발생하는지, 특정 데이터에서 나타나는지, 브라우저나 네트워크 환경에 따라 달라지는지 조건을 나누어야 합니다. 재현 조건이 구체적일수록 원인과 관련 없는 코드를 수정할 가능성이 줄어듭니다.
한 예약 서비스에서는 사용자가 결제 버튼을 두 번 빠르게 누르면 동일한 예약이 두 건 생성되는 문제가 있었습니다. 처음에는 데이터베이스 중복 저장 오류라고 생각했지만 한 번만 누른 요청에서는 문제가 발생하지 않았습니다. 준비생은 버튼을 빠르게 연속으로 눌렀을 때 동일한 요청이 두 번 전송되는 상황을 재현했고 서버에서도 두 요청을 모두 정상적인 신규 요청으로 처리하고 있다는 사실을 확인했습니다.
화면에서 첫 요청 이후 버튼을 비활성화하면 반복 클릭은 줄일 수 있었지만 네트워크 재전송이나 외부 요청까지 막을 수는 없었습니다. 팀은 예약을 구분할 수 있는 요청 식별값과 서버 검증을 추가했고 같은 요청이 반복되면 기존 결과를 반환하도록 처리했습니다. 이후 빠른 클릭, 새로고침, 정상적인 별도 예약을 각각 시험했습니다.
- 재현 단계에는 사용한 계정과 데이터, 입력 순서, 실행 환경, 실제 결과가 포함되어야 합니다. 다른 사람이 같은 조건으로 시험할 수 있어야 수정 전후의 차이도 객관적으로 확인할 수 있습니다.
- 간헐적이라는 표현만 남기지 말고 발생 조건의 공통점을 찾아야 합니다. 빠른 연속 입력, 특정 권한, 빈 데이터, 느린 통신처럼 조건을 나누면 확인할 코드와 로그의 범위를 줄일 수 있습니다.
- 가설은 하나씩 검증해야 합니다
오류가 발생했을 때 여러 설정과 코드를 동시에 바꾸면 무엇이 원인이었는지 알기 어렵습니다. 문제가 사라져도 다시 발생했을 때 같은 과정을 반복하게 됩니다. 현재 확인된 사실을 기준으로 가능성을 세우고 하나씩 확인한 뒤 결과를 기록하는 것이 좋습니다.
한 데이터 조회 기능에서는 특정 검색어를 입력했을 때만 서버 오류가 발생했습니다. 준비생은 데이터베이스 연결, 서버 메모리, 검색 쿼리를 동시에 수정하려 했지만 정상 검색어는 문제없이 처리되고 있었습니다. 오류가 발생하는 입력을 비교하니 작은따옴표가 포함된 검색어에서만 실패했고 문자열을 직접 이어 붙여 쿼리를 만드는 코드가 원인이었습니다.
그는 특수문자를 제거하는 임시 처리를 먼저 생각했지만 정상적인 상품명까지 제한할 수 있다는 문제가 있었습니다. 입력값을 쿼리 문자열과 분리해 전달하도록 수정하고 작은따옴표, 공백, 한글, 빈 검색어 조건을 다시 확인했습니다. 이 사례에서는 오류 제거뿐 아니라 안전한 데이터 처리 방식으로 개선한 판단까지 보여줄 수 있습니다.
- 결론만 말한 설명: 검색 오류를 찾아 쿼리를 수정했습니다.
- 순서가 보이는 설명: 정상 검색어와 오류가 발생한 검색어를 비교해 특수문자가 포함된 경우에만 실패한다는 조건을 찾았습니다.
- 문제해결 방식이 담긴 설명: 데이터베이스 연결 문제를 의심했지만 일반 검색은 정상적으로 처리되었습니다. 실패한 입력의 공통점을 비교해 문자열을 직접 결합하는 부분을 찾았고 입력값을 분리해 전달하도록 변경했습니다. 수정 후 다양한 검색어와 빈 값 조건을 다시 시험했으며 이후 데이터베이스 요청 작성 기준을 프로젝트 문서에 추가했습니다.
- 임시 조치와 근본 해결을 구분해야 합니다
오류를 해결하기 위해 서버를 재시작하거나 문제가 되는 데이터를 삭제할 수 있습니다. 이러한 방법은 서비스를 빠르게 정상화하는 데 필요할 수 있지만 원인이 해결된 것은 아닙니다. 포트폴리오에서는 당시 사용한 임시 조치와 이후 원인을 찾아 수정한 내용을 구분해서 작성하는 편이 좋습니다.
한 프로젝트에서 이미지 업로드를 반복하면 서버 저장 공간이 부족해지는 문제가 발생했습니다. 처음에는 오래된 파일을 삭제해 서비스를 다시 실행했지만 며칠 뒤 같은 현상이 반복되었습니다. 저장 경로를 확인하니 사용자가 업로드를 취소하거나 게시글을 삭제해도 임시 파일은 계속 남아 있었습니다. 준비생은 파일 생성과 삭제 흐름을 추적해 실패한 업로드의 임시 파일과 삭제된 게시글의 연결 파일을 정리하도록 수정했습니다.
이후 여러 크기의 파일을 업로드하고 중간에 취소하는 상황, 게시글을 삭제하는 상황을 반복해 저장 공간 변화를 확인했습니다. 단순히 디스크를 비웠다는 내용보다 임시 복구 이후 데이터 생명주기를 확인하고 재발 원인을 제거한 경험으로 설명할 수 있습니다.
수정 전후를 비교한 개선결과가 포트폴리오를 완성합니다
- 오류가 사라졌다는 사실만으로 검증이 끝나지 않습니다
문제가 발생한 조건에서 더 이상 오류가 보이지 않으면 해결되었다고 판단하기 쉽습니다. 그러나 수정 과정에서 정상 기능이 달라졌거나 다른 조건에서 새로운 문제가 생길 수 있습니다. 문제가 나타났던 상황과 정상 상황을 모두 다시 확인해야 합니다.
회원가입 오류를 수정했다면 잘못된 입력이 차단되는지만 볼 것이 아니라 정상 회원가입이 그대로 처리되는지도 확인해야 합니다. 상품 조회 요청 순서를 제어했다면 빠르게 화면을 이동하는 상황과 일반적인 이동, 요청 실패 후 재시도까지 살펴볼 수 있습니다. 관련 기능을 함께 검증한 기록이 있으면 수정으로 인한 부작용까지 고려했다는 사실을 보여줄 수 있습니다.
- 수정 전후는 같은 조건으로 비교해야 합니다. 데이터와 실행 환경이 다르면 변화가 코드 때문인지 다른 요인 때문인지 판단하기 어렵습니다. 재현 단계와 예상 결과를 먼저 남겨두면 비교가 쉬워집니다.
- 정량적인 수치를 사용할 때는 측정 기준을 적어야 합니다. 응답 시간이 줄었다면 몇 건의 데이터와 어떤 환경에서 측정했는지 설명해야 합니다. 단일 측정을 전체 성능 개선으로 과장하지 않는 태도도 중요합니다.
- 재발을 줄이는 장치까지 만들어야 합니다
한 번 해결한 문제가 코드 변경 이후 다시 나타날 수 있습니다. 가능하다면 해당 오류를 확인할 테스트를 추가하고, 자동화하기 어려운 경우에는 배포나 기능 점검 목록에 포함할 수 있습니다. 문서와 로그를 개선하는 것도 재발했을 때 더 빠르게 원인을 찾는 방법입니다.
한 백엔드 프로젝트에서는 주문 취소 시 재고가 복원되지 않는 문제가 발생했습니다. 준비생은 취소 처리 코드에 재고 증가 로직을 추가해 문제를 해결했지만 주문 상태 변경과 재고 반영이 서로 다른 단계에서 처리되고 있었습니다. 중간에 오류가 발생하면 주문은 취소되었지만 재고는 그대로 남을 가능성이 있었습니다.
팀은 두 작업을 하나의 처리 단위로 묶고 어느 한쪽이 실패하면 전체 변경을 되돌리도록 수정했습니다. 정상 취소, 이미 취소된 주문, 재고 변경 실패 상황을 각각 시험하고 테스트로 남겼습니다. 이 경험은 보이는 오류를 고치는 데서 끝나지 않고 데이터 일관성까지 고려한 개선 사례가 됩니다.
- 수정 여부만 적은 설명: 주문 취소 시 재고가 복원되지 않는 문제를 해결했습니다.
- 검증 내용이 포함된 설명: 취소 처리와 재고 복원을 함께 수정하고 정상 취소와 중복 취소 상황을 다시 시험했습니다.
- 재발 방지까지 담긴 설명: 주문 상태만 변경되고 재고가 복원되지 않는 현상을 재현한 뒤 두 작업이 분리되어 있다는 원인을 찾았습니다. 처리 도중 한 작업이 실패하면 데이터가 달라질 수 있어 하나의 단위로 묶고 실패 시 이전 상태로 돌아가도록 수정했습니다. 정상 취소와 이미 처리된 요청, 재고 변경 실패 조건을 테스트로 추가해 이후 변경에서도 확인할 수 있도록 했습니다.
- 포트폴리오에는 판단이 바뀐 지점을 남겨야 합니다
디버깅 기록을 길게 작성한다고 좋은 자료가 되는 것은 아닙니다. 처음 나타난 현상, 재현 조건, 최초 가설, 확인한 로그와 데이터, 실제 원인, 수정 내용, 재검증, 재발 방지 순서로 정리하면 읽는 사람이 과정을 따라가기 쉽습니다. 모든 명령어와 검색 기록을 넣기보다 판단에 영향을 준 근거를 선별해야 합니다.
프런트엔드 개발자라면 상태 변화, 사용자 입력, API 요청과 화면 반영 과정이 중요할 수 있습니다. 백엔드 지원자는 데이터 저장, 인증 처리, 트랜잭션, 오류 응답과 연결된 사례를 우선할 수 있습니다. 클라우드와 인프라 직무라면 서버 접근 경로, 포트, 프로세스 상태, 로그 확인 순서가 더 적합합니다. 같은 오류라도 지원 직무가 확인하려는 역량에 맞게 강조점을 조정해야 합니다.
README에는 문제와 변화가 한눈에 보이도록 대표 사례 두세 개를 정리하고 상세 기록은 별도 문서나 이슈 링크로 연결할 수 있습니다. 면접에서는 전체 내용을 외우기보다 가장 판단이 필요했던 사례를 골라 설명하는 것이 좋습니다. 문제를 빠르게 해결했다는 결론보다 잘못된 가설을 수정하고 근거를 따라 범위를 줄인 과정이 실무 가능성을 더 구체적으로 보여줍니다.
- conclusion
디버깅 경험을 포트폴리오에 넣어야 하는 이유는 프로젝트에 오류가 많았다는 사실을 보여주기 위해서가 아닙니다. 예상과 다른 상황이 발생했을 때 현상과 원인을 구분하고, 로그와 데이터를 근거로 확인 범위를 줄이며, 수정 이후 같은 문제와 관련 기능을 다시 검증할 수 있다는 점을 보여주기 위해서입니다. 완성 화면만 있는 프로젝트보다 판단과 개선 과정이 담긴 자료에서 지원자의 문제해결 방식이 더 분명하게 드러납니다.
지금 자신의 프로젝트를 다시 살펴본다면 가장 어려운 기술을 사용한 부분보다 예상대로 동작하지 않았던 장면을 찾아보는 것이 좋습니다. 당시 처음 의심한 원인은 무엇이었는지, 어떤 에러 문구와 실행 기록을 확인했는지, 정상 상황과 실패 상황의 차이는 무엇이었는지를 적어보세요. 원인을 처음부터 맞히지 못했더라도 새로운 근거를 확인하고 가설을 수정했다면 충분히 좋은 경험이 됩니다.
- 오류의 원인을 정리할 때는 화면에 나타난 현상과 최종적으로 확인한 문제를 구분해야 합니다. 서버 문제라고 추측했다가 화면의 실패 응답 처리 누락을 발견했다면 판단이 바뀐 근거까지 남겨야 합니다.
- 해결 과정을 작성할 때는 검색한 내용보다 직접 검증한 순서를 보여줘야 합니다. 재현 조건을 만들고 로그, 요청값, 데이터 상태를 하나씩 비교한 과정이 있어야 우연히 고친 것이 아니라는 사실을 설명할 수 있습니다.
- 개선 결과에서는 오류가 사라졌다는 결론만 적지 않아야 합니다. 정상 기능과 관련 기능을 다시 점검하고 테스트나 배포 기준을 추가했다면 재발 가능성까지 고려한 경험으로 활용할 수 있습니다.
실제 포트폴리오를 검토하면 기능 목록과 사용 기술은 자세하지만 개발 과정에서 마주친 문제는 한 줄로 줄여놓은 경우가 많습니다. 오류를 짧게 적으면 실패한 모습이 드러난다고 걱정하기 때문입니다. 그러나 면접관은 오류가 전혀 없었던 프로젝트보다 문제가 생겼을 때 무엇부터 확인하는지를 궁금해합니다. 해결되지 않은 문제를 숨기지 않고 현재까지 확인한 범위와 남은 한계까지 설명하는 태도도 신뢰도를 높일 수 있습니다.
대표 사례를 선택해 현상, 재현 조건, 최초 가설, 확인한 근거, 실제 원인, 수정 내용, 재검증, 재발 방지 순서로 정리해 보세요. 이 내용은 이력서에서는 문제해결 성과로 압축할 수 있고, 포트폴리오에서는 구현 과정의 깊이를 보여주며, 면접에서는 기술 경험을 구체적으로 설명하는 근거가 됩니다. 결국 디버깅이 취업 자료로 바뀌는 순간은 오류 문구가 사라졌을 때가 아니라 왜 발생했으며 어떤 기준으로 해결했는지를 다른 사람에게 설명할 수 있게 되었을 때입니다.
