10. 오래 걸리는 일엔 번호표를 — 백그라운드 작업과 접근성

이번 편이 만지는 곳: 개발의 큐(백그라운드)와 화면, 운영. 오래 걸리는 일을 큐로 빼고 다국어와 접근성을 챙긴다.

문서 100개를 한꺼번에 임베딩하는 데 30초가 걸린다고 해 보자. 이걸 버튼 누른 그 자리에서 처리하면 사용자는 30초 동안 멈춘 화면을 본다. 게다가 프론트를 올린 Vercel 함수는 10초가 지나면 그냥 끊어 버린다. 이번 편의 절반은 그 대기를 없애는 일이고, 나머지 절반은 더 많은 사람이 쓸 수 있게 다국어와 접근성을 챙기는 일이다. 처음 쓰는 Claude Code 기능은 큰 작업을 쪼개 병렬로 돌리는 /batch와 반복 실행하는 /loop, 그리고 예약 실행 개념인 Routines다.

백그라운드 작업 — 오래 걸리는 요리는 번호표를 준다

대량 임베딩이나 리포트 생성처럼 오래 걸리는 일을 요청과 응답 안에서 처리하면 사용자가 멈춰 기다린다. 식당에서 오래 걸리는 요리는 번호표를 주고 따로 만들듯, 이런 작업은 큐와 비동기로 분리하고 진행 상태를 보여 준다. 특히 무거운 일을 요청 안에서 붙들면 백엔드 일꾼이 묶여 다른 요청까지 밀린다. 그래서 이런 작업은 큐(작업 대기열)로 빼 FastAPI 백엔드가 뒤에서 처리한다. 흐름을 한 장으로 보면 이렇다.

다국어와 접근성 — 더 많은 사람이 쓰게

• i18n(internationalization: 국제화)은 화면 텍스트를 코드에 박지 않고 번역 파일로 분리하는 것이다. 날짜와 통화도 지역에 맞춘다.
• a11y(accessibility: 접근성)는 키보드만으로 조작하고, 스크린리더용 라벨과 대체 텍스트를 달고, 색 대비를 충분히 두는 것이다. 코더가 거의 훈련받지 않는 영역이라 스킬로 메운다.

접근성은 눈으로 보고 마우스를 쓰는 사람만 사용자가 아니라는 이야기다. 키보드만 쓰는 사람, 화면을 못 보고 읽어 주는 프로그램을 쓰는 사람도 있다. 버튼에 라벨이 없으면 그분들껜 "이름 없는 버튼"으로 들린다.

스터디 노트 스타일로 한국어 문서 100~300개를 생성하는 스크립트를 만들어
data/docs-bulk/ 에 저장해 줘(주제와 길이를 다양하게). 배치 임베딩 시연용이라 양과 다양성이 중요해.

내려받은 studyqa-docs-bulk.zip(150개)을 풀어, 백그라운드 큐로 나눠 배치 임베딩해 줘.
진행 상태를 보여 주고, 중간에 실패하면 그 문서만 다시 임베딩하게 해 줘.

따라하기 1 — 오래 걸리는 작업을 백그라운드로

업로드한 문서를 임베딩하는 작업은 오래 걸려. 요청과 응답 안에서 하지 말고
백그라운드(큐와 비동기)로 돌리고, 사용자에게는 진행 상태를 보여 줘.
(요청을 막지 않게 큐로 빼고, 프론트의 함수 실행 시간 제한(Vercel 10초)도 고려해 줘.)

작업이 도는 동안 화면이 멈추지 않는지, 진행 상태가 보이는지 본다.

따라하기 2 — /batch로 다국어 병렬 적용

/batch 모든 화면의 하드코딩된 한국어 텍스트를 번역 파일로 분리(i18n)하고
영어 번역을 추가해 줘. 화면별로 나눠 병렬로 처리해.

화면을 하나씩 차례로 고치는 것보다, /batch로 화면별로 쪼개 병렬 처리하면 훨씬 빠르다. 화면마다 작업이 나뉘어 동시에 처리되는지, 텍스트가 코드에서 분리됐는지 본다.

따라하기 3 — 접근성 점검

접근성 스킬로 우리 화면을 점검해 줘. 키보드만으로 모든 기능을 쓸 수 있는지,
이미지에 대체 텍스트와 버튼에 라벨이 있는지, 색 대비가 충분한지.

마우스 없이 키보드만으로(Tab과 Enter) 조작해 본다.

따라하기 4 — 함정 (오늘의 시연)

백그라운드 작업을 일부러 실패시키거나 두 번 실행해 본다. 그때 묻는다. "작업 실패 시 재시도가 있나? 중복 실행 방지는?"

작업 재시도와 멱등성(중복 실행해도 결과가 같음)을 넣어 줘.

띄워서 확인 — 에이전트가 한 일을 검증한다

작업이 끝났다고 잘 짜인 건 아니다. 에이전트는 오래 걸리는 일을 요청 안에서 그냥 돌려 화면을 멈추게 하거나, 실패와 중복을 고려하지 않기 쉽다. 그러니 잘 도는 경우 말고 어긋나는 경우를 본다. 대량 작업 중 화면이 멈추는지, 작업을 두 번 실행하거나 도중에 죽였을 때 어떻게 되는지 직접 만들어 보고, 키보드만으로 끝까지 쓸 수 있는지 확인한다.

대량 처리 작업을 실행해 진행 상태를 보여 주고, 언어를 영어로 전환해 보고,
키보드만으로 핵심 기능을 한 번 통과해 줘.

• 오래 걸리는 작업이 화면을 멈추지 않고 진행 상태를 보이는가?
• 작업 실패 시 재시도와 중복 방지가 있는가?
• 언어 전환이 되는가? (텍스트가 코드에서 분리됨)
• 키보드만으로 핵심 기능을 쓸 수 있는가?

한 겹 더 — 사람이 누르지 않아도 도는 일

Routines로 매일 새벽, 새로 올라온 문서를 자동으로 임베딩하는 예약 작업을 만들어 줘.

사람이 누르지 않아도 정해진 시각에 도는 구조인지 본다. 같은 예약 실행을 한 가지 더 써먹을 수 있다. Supabase 무료 등급은 7일 동안 안 쓰면 프로젝트가 잠드는데, GitHub Actions의 주기적 cron으로 가볍게 접속해 깨워 두면 다주에 걸친 프로젝트가 멈추지 않는다(공개 저장소면 무료).

이제 모든 조각을 하나로 합칠 차례다. 다음 편에서는 전체가 끝에서 끝까지 도는지 통합 점검하고, 발표를 위한 자료까지 준비한다.