AI 에이전트 팀의 하루, 그리고 사람이 개입해야 했던 이유

한 줄 요약

버튼을 눌렀을 때 “성공했어요” / “실패했어요” 알림(toast)을 표시하는 기능을 추가했습니다. AI 에이전트 팀이 60개 테스트를 작성하고 통과시켰지만, 사람의 개입 없이는 실제 앱 버그가 그냥 납품됐을 것입니다.

toast가 뭔가요?

웹 앱에서 화면 아래쪽에 잠깐 나타났다가 사라지는 작은 알림입니다. 카카오톡에서 메시지를 보내면 “전송됨”이 뜨는 것, 유튜브에서 재생목록에 추가하면 “저장됨”이 뜨는 것이 toast입니다.

이번 이슈에서 추가한 toast는 4가지 상황입니다.

파이프라인 구성

이번 작업은 세 명의 AI 에이전트가 역할을 나눠 수행했습니다.

노팀장 (개발)  →  이팀장 (코드 리뷰)  →  태요원 (테스트)

각자의 역할은 분명합니다. 노팀장은 코드를 짜고, 이팀장은 코드를 검토하고, 태요원은 실제 동작을 검증합니다. 사람이 전체 흐름을 관리합니다.

테스트 전략: 실제 서버 없이 테스트하기

네트워크 모킹(mocking) 기법을 사용했습니다. 실제 API 서버 대신, Playwright가 중간에서 요청을 가로채 가짜 응답을 돌려줍니다.

브라우저 → API 요청 → [Playwright가 가로챔] → 가짜 성공/실패 응답 → 브라우저

이렇게 하면 실제 서버를 배포하지 않아도, 의도적으로 실패 상황을 만들어 테스트할 수 있습니다.

발견한 버그들

테스트를 진행하면서 버그 네 개가 발견됐습니다. 이 중 하나는 테스트가 통과한 뒤에도 사람이 영상을 직접 보고 나서야 발견됐습니다.

버그 1: toast가 아예 안 보이는 문제 (코드 누락)

toast 코드를 아무리 잘 추가해도 화면에 아무것도 표시되지 않았습니다. 원인은 toast를 화면에 렌더링하는 컨테이너 컴포넌트 자체가 누락되어 있었던 것입니다. 방송국에서 뉴스를 송출하고 있는데 TV 수신기가 없는 상황입니다. <Toaster /> 컴포넌트 한 줄을 추가한 순간 10개 테스트가 동시에 통과됐습니다.

원인: 노팀장이 코드를 작성하고 실제로 화면에서 동작을 확인하지 않았습니다.

버그 2: 알림 허용 팝업이 버튼을 가리는 문제 (테스트 환경 간섭)

Push 알림 허용 여부를 묻는 팝업이 테스트 중에 뜨면서 화면 전체를 덮어버렸습니다. Firefox와 Safari에서 주로 발생했습니다. NEXT_PUBLIC_E2E=true 환경 플래그를 설정해서 테스트 중에는 팝업을 표시하지 않도록 해결했습니다.

버그 3: toast가 BottomNav에 완전히 가려지는 문제 — 1차 (절반 가림)

테스트가 전부 통과한 뒤, 사람이 영상을 직접 확인했습니다. 일정 저장/삭제 페이지에서 toast가 전혀 보이지 않았습니다. 테스트는 toast가 DOM에 존재하는지만 확인했지, 사용자 눈에 보이는지는 검증하지 않았기 때문입니다.

[화면 하단]
┌─────────────────────────────┐
│  toast: "일정이 저장되었..."  │  ← toast (bottom: 24px, 기본값)
└─────────────────────────────┘
┌─────────────────────────────┐
│  AI  스케줄  과제  피드      │  ← BottomNav (fixed, 항상 최상단)
└─────────────────────────────┘

BottomNav가 toast 위에 고정되어 있어 완전히 가렸습니다. offset: 80px로 toast 위치를 올렸지만, 여기서 또 다른 문제가 드러났습니다.

이 버그는 사람이 영상을 육안으로 확인하지 않았다면 발견하지 못했습니다.

버그 4: toast가 BottomNav에 가려지는 문제 — 2차 (모바일 미적용)

1차 수정 후 다시 사람이 테스트 영상을 확인했습니다. 모바일 뷰포트에서는 여전히 toast가 BottomNav 뒤에 숨어 있었습니다.

원인은 sonner 라이브러리의 내부 동작 방식이었습니다. 뷰포트 너비 600px 이하(모바일)에서는 --mobile-offset-bottom이라는 별도 CSS 변수를 사용하는데, 노팀장과 이팀장 모두 이 사실을 확인하지 않았습니다.

실제 측정값 (수정 전):
  Toast bottom: 711px
  BottomNav top: 658px
  → toast가 BottomNav를 53px나 침범

실제 측정값 (수정 후):
  Toast bottom: 647px
  BottomNav top: 658px
  → toast가 BottomNav 위에 11px 여백 확보

mobileOffset= prop을 별도로 추가해서 해결했습니다.

이번 사태의 진짜 원인

노팀장의 문제: 성의 없는 UI/UX 구현

노팀장은 기능 코드를 추가한 뒤 실제로 화면에서 눈으로 확인하지 않았습니다. UI 구현에서 “코드가 동작한다”는 것과 “사용자 눈에 제대로 보인다”는 것은 완전히 다른 문제입니다.

• <Toaster />를 빠뜨린 것: 화면을 한 번만 열어봤어도 즉시 발견됐을 오류
• BottomNav 가림 문제: BottomNav가 있는 레이아웃에 toast를 붙이면 겹친다는 것은 좌표 계산 없이도 예측 가능한 문제
• 모바일 미적용: 라이브러리 문서나 소스를 확인했다면 mobileOffset이 별도 prop임을 알 수 있었음

UI 구현은 “코드가 컴파일된다”가 아니라 “사람이 봤을 때 의도대로 보인다”가 완료 기준입니다.

이팀장의 문제: 표면적 리뷰

이팀장은 코드 변경사항만 검토하고 실제 렌더링 환경에서의 동작을 고려하지 않았습니다. offset=을 추가한 것을 보고 “올렸으니 됐겠지”라고 넘겼습니다. 코드 리뷰는 코드를 읽는 것이지만, UI 관련 변경사항은 라이브러리 동작 방식까지 확인하는 것이 책임 범위입니다.

AI 에이전트의 구조적 한계

이번 사태는 단순한 실수가 아닙니다. AI 에이전트가 가진 구조적 한계가 드러났습니다.

테스트 통과 = 품질 보장이 아닙니다.

테스트는 “toast가 DOM에 있는가”를 확인했습니다. “toast가 사용자 눈에 보이는가”는 확인하지 않았습니다. 에이전트는 테스트가 통과하면 임무 완수로 판단합니다. 하지만 실제 사용자 경험은 DOM 구조와 다릅니다.

에이전트가 확인한 것:  toast가 DOM에 존재한다 ✅
사용자가 경험한 것:   toast가 BottomNav에 가려서 보이지 않는다 ❌

테스트는 구현이 의도대로 동작하는지 검증합니다. 구현 자체가 “일단 돌아가게만” 수준이면, 테스트가 통과해도 사용자는 불편합니다.

사람의 개입이 왜 필요했나

이번 작업에서 사람이 두 번 개입했습니다. 두 번 모두 결정적이었습니다.

1차 개입: 테스트 시나리오 검수

태요원이 테스트 시나리오를 작성한 뒤 사람이 검수했습니다. “DOM에 있는가”만 확인하는 테스트는 사용자 관점의 품질을 보장하지 못합니다. 이 시점에 시나리오를 보완했다면 더 빨리 문제를 잡을 수 있었습니다.

2차 개입: 테스트 영상 검수

60/60 통과 결과가 나왔을 때, 사람이 직접 영상을 재생해서 확인했습니다. 테스트가 통과했는데도 화면에서 toast가 보이지 않는다는 것을 발견했습니다. 이 개입이 없었다면 버그가 있는 코드가 그대로 PR에 포함됐을 것입니다.

AI 에이전트가 본 것:  ✅ 60 passed
사람이 본 것:         ❌ toast가 BottomNav 뒤에 숨어 있음

하네스 엔지니어링에 디자인 가이드가 필요한 이유

이번 버그 4는 예방 가능했습니다. “toast는 항상 BottomNav 위에 위치해야 한다”는 규칙이 디자인 가이드에 명시되어 있었다면, 노팀장이 구현할 때 그리고 이팀장이 리뷰할 때 체크할 기준이 생깁니다.

AI 에이전트는 명확한 기준이 있을 때 잘 동작합니다. “toast를 추가하라”는 요청에는 위치, 지속 시간, 겹침 방지 규칙이 포함되어 있지 않습니다. 에이전트는 라이브러리 기본값을 그대로 사용합니다.

디자인 가이드는 에이전트에게 체크리스트가 됩니다.

파이프라인 역할 위반

이번 작업에서 한 가지 절차 위반도 있었습니다. 버그를 발견한 것은 태요원이었는데, 수정까지 태요원이 직접 했습니다.

올바른 절차:

태요원: 버그 발견 → FAIL 선언 + 원인 명시
    ↓
노팀장: 코드 수정
    ↓
이팀장: 코드 리뷰
    ↓
태요원: 재검증

코드 변경은 노팀장의 역할입니다. 태요원이 수정까지 하면 리뷰 단계가 생략되고, 검증자가 수정자가 되어 독립성이 무너집니다.

6개 브라우저에서 검증하는 이유

같은 코드도 브라우저마다 다르게 동작합니다. 이번에도 Chrome에서는 통과하는 테스트가 Safari에서 실패하는 케이스가 있었고, 데스크탑에서는 정상인 toast가 모바일에서는 가려지는 문제가 있었습니다. 6개 브라우저 검증은 선택이 아닌 필수입니다.

최종 결과

60 passed (49초)

✅ Chromium (Desktop Chrome)   10/10
✅ Firefox                     10/10
✅ WebKit (Desktop Safari)     10/10
✅ Mobile Chrome (Android)     10/10
✅ Galaxy S21 (Android)        10/10
✅ Mobile Safari (iPhone 12)   10/10

총 변경 파일: 8개
총 테스트: 60개 (6 브라우저 × 10 시나리오)
소요 시간: 49초 (전 브라우저 병렬 실행 기준)
발견된 실제 앱 버그: 2건 (BottomNav toast 가림 1차·2차)
사람의 결정적 개입: 2회

결론: AI 에이전트 팀의 가능성과 한계

AI 에이전트는 반복적인 작업, 다양한 시나리오의 테스트 코드 작성, 빠른 버그 수정에서 탁월합니다. 이번에도 60개 테스트 작성과 실행에 걸린 시간은 불과 49초였습니다.

하지만 “동작하는가”와 “제대로 보이는가”를 구분하지 못하는 것이 에이전트의 한계입니다. 테스트가 통과해도 사용자 경험이 깨져 있을 수 있습니다. 이 간극을 메우는 것이 사람의 역할입니다.

그리고 이 간극을 시스템적으로 좁히는 것이 디자인 가이드의 역할입니다. 에이전트가 판단할 수 없는 것을 규칙으로 만들면, 에이전트가 그 규칙을 따를 수 있습니다.

“테스트가 통과한다는 것이 품질을 보장하지 않는다.
사람이 보기 전까지는 아무도 모른다.”