dev3000 실전 가이드: AI 디버깅의 눈 — 웹앱의 모든 순간을 타임라인으로 캡처

AI가 버그를 고치려면 "무슨 일이 있었는지"를 알아야 한다

AI 에이전트가 코드를 작성하는 시대다. Claude Code, Cursor, Copilot — 이제 에이전트가 기능을 구현하고, PR을 열고, 때로는 배포까지 한다.

그런데 버그가 생겼을 때 에이전트에게 "이 버그 고쳐줘"라고 말하면 어떻게 될까?

에이전트는 코드를 본다. 타입을 확인한다. 로직을 추론한다. 하지만 정작 버그가 발생했을 때 무슨 순서로, 어떤 데이터가 흘렀는지는 모른다. 서버에서 어떤 에러가 났는지, 그 직전에 브라우저에서 어떤 이벤트가 발생했는지, 네트워크 요청이 어떤 순서로 날아갔는지 — 이걸 모르면 추론이 아니라 추측이 된다.

dev3000은 이 빈자리를 채운다. 웹앱의 모든 순간을 타임라인으로 캡처해서, 에이전트가 버그의 "현장"을 볼 수 있게 해준다.

dev3000이란

dev3000은 Vercel Labs에서 만든 오픈소스 개발 도구다. 웹 애플리케이션의 실행 과정을 통합 타임라인으로 기록한다.

기존 디버깅 도구들의 문제는 파편화다. 서버 로그는 터미널에, 브라우저 에러는 DevTools 콘솔에, 네트워크 요청은 Network 탭에, 상태 변화는 React DevTools에 흩어져 있다. 버그를 재현하고 원인을 파악하려면 여러 창을 오가며 타임스탬프를 손으로 맞춰야 한다.

dev3000은 이 모든 것을 하나의 피드로 합친다. 같은 타임스탬프 기준으로, 서버에서 일어난 일과 브라우저에서 일어난 일을 나란히 볼 수 있다. 거기에 자동 스크린샷까지 더해서, 사용자가 보던 화면과 그 순간의 기술적 상태를 함께 확인할 수 있다.

핵심 기능: 통합 타임라인의 5가지 레이어

dev3000이 캡처하는 데이터는 다섯 가지 레이어로 구성된다.

1. 서버 로그

Next.js API Routes, Route Handlers, Server Actions — 서버에서 실행되는 모든 코드의 로그가 타임라인에 기록된다. console.log는 물론, 처리되지 않은 예외, 미들웨어 실행 결과까지 포함된다. 기존에는 터미널 창을 계속 보고 있어야 했지만, dev3000을 쓰면 브라우저의 타임라인 피드에서 서버 이벤트를 확인할 수 있다.

2. 브라우저 이벤트

클릭, 폼 제출, 라우트 전환, 컴포넌트 마운트/언마운트 — 사용자 인터랙션과 앱 상태 변화를 기록한다. "버튼을 눌렀더니 안 됐어요" 같은 모호한 버그 리포트 대신, 정확히 어떤 엘리먼트에서 어떤 이벤트가 발생했는지 타임스탬프와 함께 남는다.

3. 콘솔 메시지

브라우저 콘솔의 모든 메시지 — log, warn, error, info — 가 타임라인에 통합된다. DevTools를 열지 않아도, 개발 서버를 실행하는 터미널 창을 전환하지 않아도 된다.

4. 네트워크 요청

API 호출, 정적 에셋 로드, 서드파티 요청까지 네트워크 레이어 전체를 기록한다. 요청 URL, 메서드, 상태 코드, 응답 시간이 타임라인에 찍힌다. 클라이언트가 서버에 요청을 보낸 것과 서버가 실제로 처리한 것 사이의 gap을 시각적으로 확인할 수 있다.

5. 자동 스크린샷

이벤트 발생 시점에 스크린샷을 자동으로 캡처한다. 에러가 발생했을 때 사용자가 실제로 보던 화면이 타임라인에 첨부된다. QA 단계에서 "이 화면에서 에러났어요"를 설명하는 데 쓰던 수고가 사라진다.

AI 에이전트 연동: 컨텍스트가 디버깅의 질을 결정한다

dev3000의 진가는 AI 에이전트와 함께 쓸 때 드러난다.

에이전트에게 버그를 맡길 때 지금까지는 이런 식이었다:

"결제 버튼 클릭하면 에러납니다. 코드 봐주세요."

에이전트는 코드를 읽고, 가능한 원인을 추측하고, 수정을 제안한다. 틀리면 다시. 맞을 때까지 반복. 이 과정에서 여러 번의 대화가 필요하고, 에이전트가 잘못된 방향으로 수정을 시도하는 일도 생긴다.

dev3000이 있으면 다르다:

"결제 버튼 클릭하면 에러납니다. 타임라인 첨부합니다.

[서버 로그: POST /api/payment → 500 Internal Server Error] [네트워크: fetch() → status 500, duration 234ms] [브라우저 이벤트: button#checkout click → React error boundary triggered] [콘솔: TypeError: Cannot read properties of undefined (reading 'amount')] [스크린샷: 에러 직전 화면]"

에이전트는 이제 추측이 아닌 추론을 한다. 어떤 순서로 어떤 일이 벌어졌는지 알기 때문에, 수정 방향이 처음부터 정확해진다.

실제로 dev3000은 Claude, GPT-4 같은 LLM에 타임라인 데이터를 구조화된 형태로 전달하는 것을 목표로 설계됐다. 단순히 개발자가 보는 대시보드가 아니라, 에이전트가 읽을 수 있는 컨텍스트 소스로 기능한다.

설치 및 사용

dev3000은 npm 패키지로 제공된다. 설치는 간단하다.

npm install dev3000

Next.js 프로젝트에 통합하는 방법:

// next.config.js
const { withDev3000 } = require('dev3000');

module.exports = withDev3000({
  // 기존 Next.js 설정
});

개발 서버를 실행하면 dev3000 대시보드가 별도 포트(기본 3001)에서 시작된다. 앱을 사용하면서 발생하는 모든 이벤트가 실시간으로 타임라인에 쌓인다.

설정 없이 바로 동작하는 것이 dev3000의 설계 철학이다. 서버 로그 캡처를 위한 별도 SDK 초기화, 브라우저 이벤트 등록을 위한 컴포넌트 래핑 — 이런 것들이 필요 없다. withDev3000 래퍼 하나로 전체 레이어가 자동으로 연결된다.

스크린샷 기능을 활성화하려면 Playwright 또는 Puppeteer가 필요하다:

npm install dev3000 playwright

설정 파일에서 스크린샷 트리거 조건을 지정할 수 있다. 에러 발생 시 자동 캡처, N초마다 주기적 캡처, 특정 라우트 진입 시 캡처 등 다양한 옵션을 지원한다.

1인 개발자를 위한 활용 시나리오

혼자 개발하는 사람에게 dev3000이 특히 유용한 세 가지 상황이 있다.

재현하기 어려운 버그

"가끔 결제가 실패해요"라는 유저 신고를 받았다고 하자. 개발 환경에서는 재현이 안 된다. dev3000을 켜두면 유저가 경험한 실패 세션의 타임라인이 그대로 남는다. 재현을 위한 시간을 쓰지 않아도, 이미 일어난 버그의 컨텍스트가 보존된다.

에이전트 QA 위임

1인 개발자는 QA를 혼자 해야 한다. dev3000을 실행한 상태에서 새 기능을 빠르게 테스트하고, 타임라인을 에이전트에게 넘기면 에이전트가 이상 징후를 찾아낸다. "이 타임라인에서 성능 병목이나 에러 가능성 있는 부분 찾아줘"라는 식이다.

배포 전 회귀 테스트

Playwright E2E 테스트와 dev3000을 함께 실행하면 테스트가 실행되는 동안의 전체 타임라인이 기록된다. 테스트가 실패했을 때 왜 실패했는지 타임라인으로 바로 확인할 수 있다. 테스트 실패 메시지만 보고 원인을 추적하는 것보다 훨씬 빠르다.

다른 디버깅 도구와의 차이

비슷한 카테고리의 도구들과 비교해보자.

Sentry, Datadog 같은 에러 모니터링 도구는 에러 발생 후 사후 분석에 초점이 맞춰져 있다. 프로덕션 환경에서 발생한 에러를 수집하고 알림을 보내는 것이 주 용도다. dev3000은 개발 단계에서 실시간으로 타임라인을 보여주는 도구다.

Chrome DevTools는 강력하지만 클라이언트 사이드에 한정된다. 서버에서 무슨 일이 일어나는지 DevTools만으로는 볼 수 없다. dev3000은 서버와 클라이언트를 통합한다.

Winston, Pino 같은 서버 로거는 서버 이벤트를 잘 기록하지만 브라우저 이벤트와의 연결이 없다. dev3000은 두 세계를 하나의 타임라인으로 합친다.

차별점은 명확하다. dev3000은 AI 에이전트에게 컨텍스트를 제공하기 위해 설계된 도구다. 인간 개발자가 보기 좋은 시각화도 있지만, 구조화된 데이터를 에이전트가 소비할 수 있는 형태로 출력하는 것이 핵심 가치다.

Vercel Labs와 오픈소스

dev3000은 Vercel Labs 프로젝트다. Vercel이 자사 플랫폼에 통합하기 위해 만든 실험적 도구들을 Labs라는 이름 아래 오픈소스로 공개한다.

GitHub에서 1K+ stars를 달성했다는 것은 이미 실제 사용자들이 있다는 의미다. 아직 1.0 릴리즈 전이라 API가 변경될 수 있지만, 핵심 기능은 안정적으로 사용할 수 있는 수준이다.

Vercel 플랫폼을 쓰지 않아도 된다. Next.js 프로젝트라면 Vercel 배포 여부와 관계없이 로컬 개발 환경에서 dev3000을 사용할 수 있다. Remix, SvelteKit 지원도 로드맵에 있다.

에이전트와 함께 디버깅하는 시대

AI 에이전트가 코드를 작성하는 것은 이미 일상이 됐다. 다음 단계는 에이전트가 버그도 고치는 것이다.

그런데 에이전트가 버그를 잘 고치려면, 에이전트가 버그를 잘 볼 수 있어야 한다. 코드만 보여주는 것으로는 부족하다. 버그가 발생한 맥락 — 어떤 순서로 어떤 데이터가 흘렀는지, 서버와 클라이언트에서 동시에 어떤 일이 있었는지 — 를 구조화된 형태로 제공해야 한다.

dev3000은 바로 그 컨텍스트를 만든다. 1인 개발자가 혼자 QA하고, 에이전트에게 디버깅을 위임하고, 프로덕션 배포 전에 문제를 잡아낼 수 있게 해주는 도구다.

아직 초기 단계지만, 방향은 맞다. 디버깅도 에이전트에게 맡기는 시대가 오고 있다. dev3000은 그 전환을 준비하는 도구다.

npm install dev3000

설치하고, 개발 서버 켜고, 다음 버그를 에이전트와 함께 잡아보자.