당신의 에이전트가 3D 모델을 내보내고, 셰이더를 고치고, 배포 빌드를 돌린다. 명령은 전부 성공으로 끝나고 오류 한 줄 없다. 그런데 화면에는 아무것도 없다. 에이전트는 "오류가 없으니 코드는 맞다"고 보고 엉뚱한 곳을 판다. 이 글은 그 착각을 막는 검사에 관한 것이다.
오류가 없는데 결과가 비는 일은 왜 생기나
처리 단계는 실패해도 예외 대신 빈 결과를 낼 수 있으므로, 단계마다 결과물이 실제로 있는지를 개수·픽셀·표식 값으로 재고 0 이면 실패로 멈춰야 한다.
도구가 빈 결과를 정상으로 내는 데는 흔한 이유 세 가지가 있다.
- 기본값이 조건부다. 옵션이 "어떤 조건일 때만 담는다"로 되어 있으면, 조건이 안 맞는 파이프라인에서는 아무 말 없이 빠진다
- 오류를 삼키는 층이 있다. 라이브러리가 오류를 잡아 콘솔 한 줄로만 내보내거나, 경고로만 남기고 계속 간다
- 자원이 넘치면 조용히 버린다. 브라우저·런타임이 상한을 넘은 것을 오류 없이 거둬 간다
실제로 어떤 모양으로 오나
한 3D 웹 프로젝트에서(2026-09) 서로 다른 도구 다섯 곳이 같은 모양으로 실패했다.
- 내보내기: 3D 도구의 glTF 내보내기는 기본값이 "머티리얼이 정점 색을 참조할 때만 정점 색을 담는다"다. 머티리얼을 안 쓰는 파이프라인에서는 정점 색이 빠진 파일이 오류 없이 나왔다(내보내기 설명서에 옵션이 있다)
- 컴파일: 셰이더 함수 하나의 인자에 동적 값을 넣자 WebGPU 쪽 셰이더 컴파일이 실패했는데, 라이브러리가 오류 범위(error scope)로 잡아 삼키는 바람에 화면만 비었다. 같은 코드가 WebGL2 에서는 멀쩡했다
- 자동 처리: AI 로 만든 메시에 자동 뼈 가중치를 걸자 경고 한 줄만 남기고 가중치 0 개로 끝났다. 겹친 정점이 원인이었고, 병합하니 정점이 1/3 로 줄었다
- 자원 상한: 작은 미리보기마다 WebGL 캔버스를 만들자 브라우저가 맥락 상한(대략 16개)을 넘긴 가장 오래된 것, 곧 메인 장면을 오류 없이 버렸다(WebGL 명세의 맥락 손실)
- 배포 빌드: 개발용 계기판을 채우는 코드 경로에서 값을 빌려 쓴 기능이, 배포 빌드에서는 그 값이 늘 0 이라 영영 안 켜질 뻔했다
반대 방향도 있다. 바뀐 범위만 올리려고 "빈 범위"를 넘기자 라이브러리가 그것을 "범위 없음 = 전부"로 읽어 버퍼 전체를 매번 올렸다. 오류도, 화면 이상도 없이 전송량만 수 MB 씩 샜다. 비어야 할 것이 꽉 차는 것도 같은 부류다 — 숫자로 재야만 보인다.
어떤 숫자로 재나
"결과물이 있다"는 단계마다 다른 숫자로 잰다. 쇼핑몰의 상품 이미지 변환, 블로그의 정적 빌드, 사내 데이터 내보내기에도 그대로 옮겨진다.
- 파일·데이터: 꼭 있어야 할 칸·채널·행의 수. 내보낸 3D 파일에 정점 색 속성이 있는가, 변환된 CSV 에 행이 0 이 아닌가
- 자동 처리: 결과의 개수. 가중치가 붙은 정점 수, 생성된 썸네일 수, 분류된 항목 수가 0 보다 큰가
- 화면: 그려진 픽셀. 캔버스에서 바탕색이 아닌 픽셀의 비율이 문턱을 넘는가
- 배포 조건: 기능이 실제로 한 번 발동하는가. 개발 모드가 아니라 배포 설정으로 돌린 시험에서 확인한다
- 양: 올린 바이트, 보낸 요청 수가 예상 범위 안인가 — 0 만이 아니라 너무 큰 것도 잡는다
표식 값을 심으면 무엇이 좋아지나
있는지 없는지만 보면 "빠졌다"는 알지만 "뒤바뀌었다"나 "변형됐다"는 모른다. 그래서 입력에 알려진 값을 하나 심어 두고 출력에서 그 값을 확인한다. 정점 색의 한 채널에 늘 0.5 를 심어 두면, 로더에서 그 채널을 읽는 것만으로 누락·채널 뒤바뀜·색공간 변환을 한 번에 가린다. 데이터 내보내기라면 맨 끝에 알려진 시험 행 하나, 이메일 템플릿이라면 알려진 자리표시자 하나가 같은 일을 한다.
에이전트에게 줄 지침
도구가 성공으로 끝나도, 결과물이 있다는 것을 숫자로 확인하기 전에는 다음 단계로 가지 않는다.
- 단계마다 "결과물이 있다"를 재는 숫자 하나를 정한다(칸·행·정점 수, 그려진 픽셀 비율, 발동 횟수, 전송 바이트).
- 그 숫자가 0 이거나 예상 범위를 벗어나면 실패로 멈추고 보고한다. 경고 출력도 같이 읽는다.
- 가능하면 입력에 알려진 표식 값을 심고, 출력에서 그 값이 그대로인지 확인한다.
- 화면이 비면 코드를 고치기 전에, 어느 단계의 숫자가 처음 0 이 되는지부터 찾는다.
확인 목록
- 내보내기·변환 단계마다 꼭 있어야 할 칸의 존재를 검사한다
- 자동 처리 단계의 결과 개수를 찍고 0 이면 멈춘다
- 렌더 결과를 픽셀 비율로 재는 시험이 하나 있다
- 개발 전용 경로에 기대는 기능이 배포 설정에서도 발동하는지 시험한다
- 전송량처럼 "너무 많음"도 예상 범위로 잰다
- 표식 값을 입력에 심어 출력까지 따라간다