Issue #317 — 사후 분석 리포트

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

비동기 버튼 toast 피드백 구현 · 전 브라우저 검증 · 에이전트 한계 분석

노팀장 · 개발 이팀장 · 리뷰 태요원 · 테스트 사람 · 검수

Background

무엇을 만들었나: Toast 알림

버튼을 눌렀을 때 "성공했어요" / "실패했어요"를 화면 아래에 표시하는 기능.
카카오톡 "전송됨", 유튜브 "저장됨"이 같은 방식입니다.

상황	성공 메시지	실패 메시지
이미지 업로드	이미지가 업로드되었습니다	이미지 업로드 실패. 다시 시도해 주세요
제출 취소	제출이 취소되었습니다	제출 취소 실패. 다시 시도해 주세요
프로필 저장	프로필이 저장되었습니다	저장 실패. 다시 시도해 주세요
일정 저장/삭제	일정이 저장/삭제되었습니다	저장/삭제 실패. 다시 시도해 주세요

Pipeline

AI 에이전트 3인 파이프라인

노팀장 · 개발

이슈를 분석하고 코드를 구현합니다. 기능이 동작하도록 만드는 것이 목표입니다.

이팀장 · 리뷰

변경된 코드를 검토합니다. 문제가 없으면 APPROVE, 있으면 REJECT합니다.

태요원 · 테스트

실제로 동작하는지 검증합니다. 6개 브라우저에서 자동 테스트를 실행합니다.

노팀장 (코드 작성) → 이팀장 (리뷰) → 태요원 (테스트)
↑ ↑
REJECT시 재작업 FAIL시 재작업

★ 사람 — 시나리오 검수 · 영상 검수 · 최종 판단

Test Strategy

실제 서버 없이 테스트하기: 네트워크 모킹

Playwright가 API 요청을 가로채 가짜 응답을 돌려줍니다.
실제 배포 없이도 성공·실패 상황을 의도적으로 만들 수 있습니다.

// 성공 시나리오: POST /api/events → 200
await page.route("**/api/events*", async (route) => {
  if (route.request().method() === "POST") {
    route.fulfill({ status: 200, body: JSON.stringify({ data: { id: "evt-001" } }) });
  }
});

// 실패 시나리오: POST /api/events → 500
await page.route("**/api/events*", async (route) => {
  if (route.request().method() === "POST") {
    route.fulfill({ status: 500 }); // 서버 오류 시뮬레이션
  }
});

6개 브라우저 × 10개 시나리오 = 60개 테스트

Test Results — Screenshots

테스트 영상에서 캡처한 실제 화면

✅ 이미지 업로드 성공 · Chrome

❌ 이미지 업로드 실패 · Chrome

✅ 프로필 저장 성공 · Firefox

✅ 제출 취소 · iPhone 12

Bugs Found

발견된 버그 1, 2 — 에이전트가 스스로 수정

버그 1: <Toaster /> 누락

toast 신호는 보내고 있었지만 화면에 렌더링하는 컨테이너가 없었습니다.

방송국은 뉴스를 송출하는데 TV 수신기가 없는 상황.

원인 노팀장이 실제 화면을 한 번도 열어보지 않음.

컴포넌트 한 줄 추가 → 10개 테스트 동시 통과.

버그 2: 알림 팝업 간섭

Push 알림 허용 팝업이 테스트 중에 화면을 덮어버렸습니다.
Firefox, Safari에서 주로 발생.

해결 NEXT_PUBLIC_E2E=true 환경 플래그로 테스트 중 팝업 비활성화.

테스트 환경과 실제 환경의 간섭을 분리하는 전형적인 사례.

두 버그의 공통점

노팀장이 구현 후 실제로 화면을 열어봤다면 즉시 발견됐을 오류들입니다. "코드가 작성됐다"와 "화면에서 동작한다"는 다릅니다.

The Critical Bug

버그 3: BottomNav가 toast를 가리다 — 1차 발견

60/60 테스트 통과 직후, 사람이 직접 영상을 열어봤습니다.
toast가 화면에 전혀 보이지 않았습니다.

[화면 하단] ┌─────────────────────────────────┐ │ toast: "일정이 저장되었습니다" │ ← bottom: 24px (라이브러리 기본값) └─────────────────────────────────┘ ┌─────────────────────────────────┐ │ AI 스케줄 과제 피드 │ ← BottomNav (fixed, z-50, 52px) └─────────────────────────────────┘

테스트가 확인한 것

toast가 DOM에 존재한다 ✅
테스트 통과.

사용자가 경험한 것

toast가 BottomNav 뒤에 숨어 전혀 보이지 않는다 ❌

The Critical Bug — Act 2

버그 3: 수정했는데 또 가려진다

노팀장이 offset을 올렸고, 이팀장이 APPROVE했습니다.
하지만 사람이 다시 영상을 확인하니 모바일에서 여전히 가려져 있었습니다.

// 노팀장의 1차 수정 — 데스크탑에서는 동작, 모바일에서는 미적용
<Toaster offset={{ bottom: 80 }} />

// 실제 측정값 (Mobile Chrome, 393px 뷰포트)
Toast bottom: 711px > BottomNav top: 658px → ❌ 겹침

// 원인: sonner는 600px 이하에서 --mobile-offset-bottom 별도 사용
// offset prop은 데스크탑 CSS 변수만 설정함

// 노팀장의 2차 수정
<Toaster offset={{ bottom: 80 }} mobileOffset={{ bottom: 80 }} />
Toast bottom: 647px < BottomNav top: 658px → ✅ 정상

Before / After

수정 전후 비교

수정 전 — BottomNav에 가림

→

수정 후 — BottomNav 위에 정상 표시

Root Cause Analysis

이번 사태의 진짜 원인:
에이전트의 구조적 한계

노팀장의 문제

UI 구현 후 실제 화면을 열어보지 않음.

· <Toaster /> 빠뜨림
· BottomNav 겹침 미예측
· 모바일 뷰포트 미확인

"코드가 컴파일된다"를
"화면이 의도대로 보인다"로 착각.

이팀장의 문제

코드 라인만 검토, 실제 렌더링 환경 미고려.

· sonner 라이브러리 내부 동작 미확인
· "offset 올렸으니 됐겠지" 표면 리뷰
· 모바일 CSS 변수 분기 미발견

UI 변경 리뷰는 라이브러리 동작까지 포함해야 함.

에이전트의 공통 맹점

에이전트는 "동작하는가"를 확인합니다. "사람 눈에 제대로 보이는가"는 확인하지 않습니다.
테스트가 통과해도 사용자 경험이 깨져 있을 수 있습니다. 이 간극을 메우는 것이 사람의 역할입니다.

Human in the Loop

사람이 개입한 두 번,
두 번 모두 결정적이었다

1차 개입: 시나리오 검수

태요원이 테스트 시나리오를 작성한 뒤 사람이 검수했습니다.

"DOM에 있는가"만 확인하는 테스트는 사용자 관점의 품질을 보장하지 못합니다.

이 시점에 위치 검증을 요구했다면 더 빨리 잡을 수 있었습니다.

2차 개입: 영상 검수

60/60 통과 결과를 받고 사람이 직접 영상을 재생했습니다.

테스트가 통과했는데도 toast가 보이지 않는다는 것을 발견했습니다.

이 개입이 없었다면 버그가 있는 코드가 그대로 PR에 포함됐습니다.

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

Design Guide as Engineering Spec

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

이번 버그는 예방 가능했습니다. 규칙이 있었다면 에이전트가 따랐을 것입니다.

가이드 없을 때

노팀장 → "toast 추가 완료"
이팀장 → "코드 이상 없음, APPROVE"

체크 기준이 없으니 에이전트는
라이브러리 기본값을 그대로 사용.

→ 버그가 프로덕션에 나감.

가이드 있을 때

가이드: "toast는 BottomNav(52px + safe area) 위에 위치할 것. 모바일 뷰포트 별도 확인 필수."

노팀장 → 가이드 체크 후 mobileOffset 설정
이팀장 → 가이드 대비 구현 검토

→ 구현 단계에서 버그 차단.

디자인 가이드 = 에이전트의 체크리스트

에이전트는 명확한 기준이 있을 때 잘 동작합니다. "어디에 어떻게 보여야 한다"는 규칙을 명시하면, 에이전트가 구현 단계에서 스스로 검증할 수 있습니다. 디자인 가이드는 에이전트의 판단 오류를 보완하는 가드레일입니다.

Conclusion

에이전트의 가능성과 한계,
그리고 사람의 역할

60

자동 테스트

49초

전 브라우저 실행

2

사람의 결정적 개입

2

모바일 실제 앱 버그

에이전트가 잘하는 것

반복적인 테스트 코드 작성 · 다양한 시나리오 병렬 실행 · 빠른 버그 수정 구현

에이전트가 못하는 것

"동작하는가"와 "제대로 보이는가"를 구분하는 것 · 사용자 시각으로 결과를 판단하는 것

"테스트가 통과한다는 것이 품질을 보장하지 않는다.
사람이 보기 전까지는 아무도 모른다." — 태요원, 이슈 #317 사후 분석

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