왜 스무고개가 시작되나
AI에게 웹앱을 맡겨 본 사람은 익숙한 장면이 있다. 화면에 빨간 글씨가 뜨고, 그걸 캡처해 AI에게 던지고, AI가 코드를 고치고, 또 안 되고, 다시 던진다. 몇 바퀴 돌고 나면 무엇이 원인이었는지도 모른 채 코드가 여기저기 바뀌어 있다.
원인은 실력이 아니라 정보다. 어디가 고장인지 모르는 상태에서 고치라고 하면 AI도 짐작으로 고칠 수밖에 없다. 반대로 고장 난 구간을 한 곳으로 좁혀서 주면, 같은 AI가 한 번에 고친다.
고장 난 구간을 좁히는 데 필요한 건 프로그래밍 실력이 아니다. 브라우저가 이미 답의 절반을 화면에 띄워 두고 있고, 그걸 읽는 규칙은 두 개뿐이다. 앞자리를 보는 것, 그리고 경계를 훑는 것.
상태 코드는 어디서 보나
브라우저에는 개발자 도구가 기본으로 들어 있다. 윈도우는 F12, 맥은 Command + Option + I를 누르면 화면 옆이나 아래에 패널이 열린다. 크롬·엣지·사파리 모두 있고 설치할 것은 없다. 사파리는 설정에서 개발자용 메뉴를 한 번 켜 줘야 한다.
패널 위쪽 탭 중에 두 개만 알면 된다. Console은 프론트엔드 코드(자바스크립트)가 남긴 메시지가 쌓이는 곳이고, Network는 내 화면이 바깥으로 주고받은 요청이 한 줄씩 쌓이는 곳이다. 에러가 났을 때는 Network를 먼저 연다.
Network 탭을 연 채로 문제가 되는 버튼을 다시 누른다. 그러면 목록에 줄이 새로 생긴다. 빨간색으로 표시되거나 Status 열의 숫자가 400·500번대인 줄이 범인이다. 그 줄을 클릭하면 오른쪽에 우리가 보낸 내용(Request)과 서버가 돌려준 내용(Response)이 나온다.
여기서 중요한 건 화면의 에러 문구가 아니라 이 숫자다. 문구는 서비스마다 제각각이지만 숫자는 전 세계 공통 약속이다.
앞자리 하나가 책임 소재를 가른다
상태 코드는 세 자리 숫자인데, 뒤 두 자리는 세부 사유이고 앞자리가 큰 분류다. 앞자리만 봐도 어느 쪽을 봐야 하는지 정해진다.
특히 4와 5의 차이가 실전에서 가장 크다. 4는 요청을 보낸 쪽 잘못이니 내 화면·내 입력값·내 주소를 본다. 5는 요청을 받은 쪽 잘못이니 내 코드를 아무리 고쳐도 소용이 없다.
| 앞자리 | 뜻 | 먼저 볼 곳 |
|---|---|---|
| 2xx | 성공. 요청이 정상 처리됐다 | 에러가 아니다. 화면 표시 로직을 본다 |
| 3xx | 다른 주소로 넘어가라는 안내 | 리다이렉트 설정·주소 |
| 4xx | 요청을 보낸 쪽(내 화면·입력값·권한)의 문제 | 프론트엔드 코드, 보낸 값, 로그인 상태 |
| 5xx | 요청을 받은 서버 쪽의 문제 | 백엔드 로그, 외부 서비스 상태 |
자주 만나는 코드만 추려 보면
숫자를 다 외울 필요는 없다. 실제로 부딪히는 것은 열 개 남짓이고, 각각이 무엇을 확인하라는 신호인지만 알면 된다.
표에서 401과 403의 차이를 눈여겨볼 만하다. 401은 '당신이 누구인지 모르겠다'는 뜻이라 로그인 문제이고, 403은 '누구인지는 알겠는데 그럴 권한이 없다'는 뜻이라 권한 설정 문제다. 개발에서는 앞의 것을 인증, 뒤의 것을 인가라고 부른다.
| 코드 | 뜻 | 보통 할 일 |
|---|---|---|
| 400 | 요청 형식이 잘못됐다 | 보낸 값의 형식·필수 항목 확인 |
| 401 | 누구인지 확인이 안 된다 | 로그인·토큰 만료 확인 |
| 403 | 권한이 없다 | 계정 권한·정책 설정 확인 |
| 404 | 그 주소에 아무것도 없다 | API 주소 오타·경로 확인 |
| 429 | 너무 자주 보냈다 | 잠시 기다렸다 재시도 |
| 500 | 서버가 처리 중 터졌다 | 백엔드 로그 확인 |
| 502 / 503 | 서버 앞단은 살아 있는데 뒤가 응답 없음 | 배포 상태·서버 재시작 확인 |
| 529 | 외부 서비스가 과부하다 | 내 코드 아님. 잠시 후 재시도 |
529는 내 잘못이 아니다
Claude Code나 API를 쓰다 보면 529를 자주 만난다. 앞자리가 5이므로 이건 내 쪽이 아니라 상대 서버 쪽 상황이다. 요청이 몰려 그쪽이 감당하지 못하고 있다는 뜻이고, 흔히 '서버가 터졌다'고 표현한다.
이걸 모르면 멀쩡한 코드를 계속 뜯어고치게 된다. 실제로 가장 흔한 낭비가 여기서 나온다. 5로 시작하는 코드가 보이면 손을 멈추고 잠시 기다렸다 다시 시도하는 것이 정답이다.
다만 5xx라도 내가 만든 백엔드에서 나온 500이라면 그건 내 서버 문제다. 내 서버가 낸 500인지, 외부 서비스가 낸 5xx인지부터 구분한다. 그 구분은 Network 탭에서 그 요청이 어느 주소로 갔는지를 보면 바로 된다.
요청이 지나는 다섯 구간
앞자리로 방향을 잡았으면 이제 위치를 좁힌다. 그러려면 메모 하나를 저장할 때 뒤에서 무슨 일이 일어나는지를 알아야 한다. 웹 서비스는 한 덩어리가 아니라 다음 다섯 구간이 이어 붙은 구조다.
1) 프론트엔드. 사용자에게 보이는 화면이다. 사용자를 기준으로 가장 앞에 있어서 프론트라고 부른다. HTML이 내용을 담고, CSS가 꾸미고, 자바스크립트가 클릭 같은 동작을 처리한다. 브라우저 안에서 돌기 때문에 여기서는 사실상 자바스크립트만 쓸 수 있다.
2) HTTP와 API. 화면과 서버가 대화하는 규격이다. 주소(URL)로 요청을 보내고 응답을 받으며, 주고받는 데이터 형식은 대개 JSON이다. 이 통신 구간을 묶어서 API라고 부른다.
3) 백엔드. 눈에 보이지 않는 처리 담당이다. 요청이 오면 누구인지 확인하고(인증), 그럴 자격이 있는지 보고(인가), 값이 정상인지 검사한 뒤(검증), 실제 규칙을 적용한다.
4) 데이터베이스. 서비스의 기억을 담당한다. 백엔드가 처리한 결과를 표 형태로 저장해 두고, 나중에 다시 꺼낸다.
5) 배포와 인프라. 이 모든 것이 실제로 돌아가는 자리다. 내 컴퓨터에서만 열리는 localhost를 벗어나 남들도 접속할 수 있는 곳에 올리는 과정이다.
용어가 헷갈릴 수 있는 지점이 하나 있다. '서버'는 백엔드 프로그램만 가리키는 말이 아니다. 인프라 관점에서는 그 프로그램이 돌아가는 컴퓨터를 뜻하기도 한다. 백엔드는 그 컴퓨터 위에서 로직을 처리하는 프로그램이라고 보면 된다.
고장은 구간 사이에서 난다
실무에서 문제가 생기는 자리는 대개 구간 안이 아니라 구간과 구간을 잇는 화살표 위다. 느려졌다면 어느 화살표에서 지연된 것이고, 저장이 안 됐다면 어느 화살표에서 끊긴 것이다.
그래서 디버깅은 화살표를 순서대로 짚어 내려가는 일이 된다. 아래 네 단계를 그대로 따라가면 범인이 한 구간으로 좁혀진다.
1단계. 문제가 되는 동작을 다시 재현한다. Network 탭을 연 채로 그 버튼을 다시 누른다.
2단계. 요청이 실제로 나갔는지 본다. 목록에 새 줄이 안 생기면 프론트엔드에서 이미 막힌 것이다. 이때는 Console 탭에 자바스크립트 에러가 찍혀 있는 경우가 많다.
3단계. 나갔다면 상태 코드를 본다. 4xx면 보낸 값·주소·로그인 상태를, 5xx면 백엔드 로그를 본다.
4단계. 백엔드까지 정상이면 데이터베이스에 실제로 값이 들어갔는지 확인한다. 응답은 성공인데 데이터가 없다면 저장 로직이나 트랜잭션 쪽이다.
이 순서를 한 번 익혀 두면 다음 에러부터는 캡처를 던지기 전에 이미 어느 구간인지 알고 시작하게 된다.
AI에게는 이 질문을 먼저 한다
많은 사람이 에러 화면을 붙여 넣고 '고쳐 줘'라고 한다. 그러면 AI는 보이는 증상에 맞춰 코드를 바꾼다. 원인이 다른 구간에 있으면 그 수정은 새로운 문제를 만든다.
대신 위치를 묻는 질문을 먼저 넣는다. 아래 문장은 그대로 복사해 써도 된다.
이 질문의 쓸모는 에러에만 있는 게 아니다. 처음 듣는 기술 용어를 만났을 때도 같은 틀로 물으면, 그 기술이 전체 흐름의 어느 자리에 있는지가 잡힌다. 자리를 알면 나머지 설명이 붙을 곳이 생긴다.
사용자 요청이 프론트엔드 → API → 백엔드 → 데이터베이스로 흐른다고 할 때,
지금 이 에러는 어느 구간에서 발생한 것인지 먼저 판단해 줘.
판단 근거가 되는 상태 코드와 로그도 함께 알려 주고,
확인해야 할 것이 남아 있으면 내가 무엇을 캡처해 오면 되는지 알려 줘.사용자 요청이 프론트엔드 → API → 백엔드 → 데이터베이스로 흐른다고 할 때,
방금 나온 이 기술은 어느 구간에 영향을 주는 기술인지 설명해 줘.
그리고 이 기술을 이해하려면 먼저 알아야 할 개념이 있는지도 알려 줘.모르는 용어가 나오면 지도를 본다
구간을 알아도 그 안의 용어가 계속 새로 나온다. 이럴 때 쓰기 좋은 자료가 roadmap.sh다. 프론트엔드 개발자, 백엔드 개발자처럼 역할별로 '이 순서로 배우면 된다'는 지도를 그림 한 장에 담아 둔 사이트다.
쓰는 법은 간단하다. 해당 로드맵을 열고, 지금 막힌 기술이 그 지도의 어느 단계에 있는지 찾는다. 보라색으로 표시된 항목은 만든 사람이 추천하는, 곧 실무에서 많이 쓰이는 항목이다. 영어로 되어 있어도 그림을 그대로 AI에게 주고 설명을 시키면 된다.
이렇게 하면 용어가 낱개로 쌓이지 않고 지도 위 좌표로 쌓인다. 그게 나중에 검색할 때도, AI에게 물을 때도 훨씬 빠르다.
버그는 0이 되지 않는다
마지막으로 기대치를 하나 조정해 두는 게 좋다. 아무리 숙련된 개발자가 만들어도 버그가 0이 되지는 않는다. AI가 만들어도 마찬가지고, 오히려 더 많이 만들어 낼 수도 있다.
그래서 실제 개발에서 시간이 가장 많이 들어가는 곳은 코드를 처음 쓰는 순간이 아니라 만든 뒤다. 확인하고, 내보내고, 에러가 나면 다시 고치는 반복이 대부분을 차지한다.
결국 필요한 건 버그 없는 코드가 아니라 문제가 생겼을 때 빨리 위치를 찾아내는 방법이다. 앞자리를 읽고, 경계를 훑고, 위치부터 묻는 것. 이 세 가지면 대부분의 스무고개가 끝난다.