데모는 통과했는데, 연결하자마자 무너졌다
AI 도구를 쓸 때 가장 자주 마주치는 함정은 '각 부품이 작동한다'는 착각이다. Claude Vision API가 코드를 꽤 잘 뽑아내고, JWT 인증 로직도 테스트를 통과하고, RAG 파이프라인도 로컬에선 답을 잘 낸다. 그런데 이 셋을 하나의 흐름으로 이어붙이는 순간—쿠키가 사라지고, 프록시가 요청을 못 보고, 토큰 서브 클레임 타입이 어긋난다. 최근 dev.to에 올라온 세 편의 실전 기록이 이 패턴을 각자 다른 층위에서 정확하게 짚어낸다.
Vision API로 코드 추출기를 만든 경험: 모델보다 프롬프트가 중요하다
튜토리얼 영상에서 코드를 자동으로 뽑아내는 Chrome 확장 프로그램을 Claude Vision API로 구현한 사례(dev.to, Anton Zaharenko)는 Vision 모델 활용에서 가장 실용적인 인사이트를 압축해서 보여준다.
첫째, Vision 모델은 OCR보다 구문에 강하다. 들여쓰기·괄호·키워드 같은 문법 구조를 맥락으로 함께 읽기 때문에, 픽셀 단위로 글자를 인식하는 OCR보다 코드 블록 추출 정확도가 높다. 특히 슬라이드 위 코드와 터미널 스크린샷이 섞인 케이스에서도 스타일 차이를 무시하고 '이건 코드'로 올바르게 분류했다.
둘째, 프롬프트 설계가 모델 선택보다 결과를 더 크게 바꾼다. "코드를 추출해줘"와 "모든 코드 블록을 찾아, 들여쓰기를 보존하고, 터미널 출력과 구분해줘"는 같은 모델에서 전혀 다른 품질을 낸다. 이건 단순한 팁이 아니라 구조적인 문제다. Vision API를 제품 기능으로 쓸 때, 프롬프트 자체가 UX 설계의 일부가 된다는 뜻이다.
셋째, 레이턴시는 1080p 프레임 기준 약 2~3초. 비동기 추출 트리거에는 충분하지만, 실시간 처리엔 적합하지 않다. 이 경계를 명확히 아는 것이 제품 설계의 출발점이다.
Next.js 16 통합 버그: 유닛 테스트가 잡지 못한 다섯 가지
완성된 인증 시스템을 Next.js 16 위에서 실제로 연결했을 때 비로소 드러난 버그 다섯 가지를 기록한 글(dev.to, ShubhraDev)은 '통합 테스트 없이 AI 생성 코드를 믿으면 어떤 일이 생기는가'를 가장 구체적으로 보여주는 사례다.
가장 인상적인 케이스 세 가지만 짚자.
쿠키가 성공을 보고하고 사라졌다. 로그인 후 document.cookie 쓰기는 성공을 반환했고, 직후 확인도 통과했다. 그런데 다음 요청에서 쿠키는 없었다. 원인은 클라이언트가 써야 할 쿠키를 서버가 써야 했던 것. httpOnly: true 플래그를 서버 응답의 Set-Cookie 헤더에 실어 보내는 것으로 해결됐다. 버그 자체보다, 이 버그가 로컬 개발 환경에서 타이밍 의존적으로만 재현된다는 점이 더 무섭다.
router.push는 프록시를 우회한다. Next.js router.push는 클라이언트 사이드 네비게이션이라 실제 HTTP 요청이 발생하지 않는다. 미들웨어 프록시는 그 요청을 아예 볼 수 없다. window.location.href로 풀 리로드를 강제해야 비로소 프록시가 쿠키를 볼 수 있다. 라우팅 추상화 레이어의 경계를 모르면 이 버그는 설명이 안 된다.
Postgres SERIAL 타입이 JWT sub 클레임을 숫자로 만들었다. DB의 정수 PK가 jose 라이브러리에서 숫자 그대로 서명됐고, 타입 가드는 string을 기대했다. 콘솔 로그에선 숫자와 문자열이 동일하게 보여서 디버깅이 더 어려웠다. String(payload.sub) 한 줄이 해법이었지만, 테스트 데이터가 문자열 ID를 쓰는 환경에선 재현조차 안 된다.
이 세 버그의 공통점은 유닛 테스트가 통과했다는 것이다. 각 레이어는 독립적으로 올바르다. 그런데 연결하면 어긋난다.
'AI를 제품으로 쓸 때'와 'AI로 만들 때'는 다른 규율이 필요하다
Wizr AI의 AI 엔지니어링 팀이 정리한 가이드(dev.to)는 이 구분을 가장 명쾌하게 공식화한다. Track 1: AI가 제품 기능일 때와 Track 2: AI가 개발 도구일 때—이 둘은 버즈워드를 공유할 뿐, 요구되는 역량과 실패 패턴이 완전히 다르다.
Track 1에서 핵심 함정은 세 가지다. RAG의 청킹 방식이 검색 품질을 조용히 죽인다. 자율 멀티에이전트는 디버깅 비용이 레이어마다 곱셈으로 늘어난다. 그리고 가장 중요한 것—가드레일은 프롬프트가 아니라 코드에 있어야 한다. 환불 한도나 권한 체크 같은 비즈니스 불변 조건은 모델이 어떤 결정을 내리든 반드시 실행되는 결정론적 코드로 구현해야 한다.
Track 2에서 핵심은 생성은 싸고, 소유는 비싸다는 원칙이다. AI가 50줄을 5초에 만들어도, 그 코드를 리뷰하고 테스트하고 유지보수하는 비용은 사람이 쓴 코드와 같다. 특히 AI가 구현과 테스트를 동시에 생성하면, 버그를 '기대 동작'으로 인코딩하는 테스트가 만들어진다는 경고는 실무에서 자주 간과된다.
세 사례가 함께 가리키는 것: 프로토타입과 제품 사이의 간극은 연결 지점에 있다
Vision API 확장 프로그램, Next.js 통합 버그, AI 애플리케이션 배포 가이드—이 세 사례는 각각 다른 문제를 다루지만 하나의 패턴으로 수렴한다.
AI가 각 부품을 빠르게 만들어주는 것과, 그 부품들이 실제 맥락에서 안정적으로 작동하는 것은 별개의 문제다. Vision API의 프롬프트 설계, 쿠키 쓰기 위치, JWT 타입 강제—이 중 어느 것도 AI가 자동으로 챙겨주지 않는다. 프롬프트 엔지니어링은 제품 UX 설계이고, 통합 디버깅은 경계 지식이며, 가드레일 설계는 아키텍처 판단이다.
빠른 프로토타이핑 → 사용자 검증 → 고도화라는 흐름에서 AI는 프로토타이핑 속도를 확실히 끌어올린다. 하지만 고도화 단계는 여전히 '연결 지점을 직접 이해하는 사람'이 필요하다. Wizr의 체크리스트가 '프로덕션 완성 여부'를 묻는 기준으로 retrieval 인용 출처, 결정론적 가드레일, 버전 관리된 평가 셋을 나열한 이유가 바로 여기 있다.
전망: AI 도구의 성숙도는 연결 품질로 측정된다
앞으로 AI 코딩 도구는 더 빠르게 더 많은 코드를 만들 것이다. 그럼에도 프론트엔드 개발자가 직접 설계해야 하는 영역은 줄어들지 않는다—오히려 이동한다. 개별 기능 구현에서, 그 기능들이 실제 환경에서 어떻게 만나는지를 이해하고 설계하는 쪽으로.
Vision API를 Chrome 확장에 붙일 때 레이턴시 경계를 아는 것, Next.js 라우팅 레이어가 미들웨어를 어떻게 우회하는지 아는 것, RAG의 청킹이 검색 품질에 어떻게 영향을 주는지 아는 것—이것들은 AI가 대신해줄 수 없는 연결 지식이다.
'AI로 빠르게 만든다'는 것의 진짜 의미는, 프로토타입을 빠르게 만드는 것이 아니라 연결 지점을 더 빨리 직접 경험하는 것이다. 세 사례가 공통적으로 증명하는 결론이다.