AI Fix · 자동 PR — QA Note Docs

QA Note 의 AI Fix 는 이슈 상세에서 버튼 한 번으로 Claude Code 가 코드를 직접 수정하고 PR 을 만들어 Preview 까지 띄우는 기능입니다. 이슈에 첨부된 풍부한 메타데이터(스크린샷·콘솔 로그·네트워크 로그·React 트리·DOM 스냅샷)가 그대로 컨텍스트로 전달되므로, 추가 설명 없이도 재현 가능한 수정 계획이 나옵니다.

BYO Claude 원칙

AI Fix 는 BYO Claude (Bring Your Own Claude) 모델로 동작합니다. 모든 토큰 소비는 등록한 Claude Code 구독 또는 Anthropic API 키에서 차감되며, QA Note 가 토큰을 별도로 과금하지 않습니다. QA Note 가 제공하는 것은 컨텍스트 파이프라인(이슈 메타데이터 → MCP → Claude Code) 과 PR 자동 생성 · 결과 추적 인프라뿐입니다.

항목	부담 주체
AI 토큰 비용	Claude Code 구독자 (사용자 본인)
컨텍스트 수집 · 전달	QA Note
PR 생성 · 머지 권한	GitHub App 권한 (사용자가 부여)
Preview 추적	Vercel 통합 (사용자가 연결)

따라서 AI 사용량 한도는 QA Note 플랜이 아니라 Anthropic 측 한도 를 따릅니다. 조직 단위로 Claude Code 시트를 보유한다면 그대로 재사용됩니다.

파이프라인 한눈에 보기

이슈 → PR → Preview → Production 머지의 4 단계로 진행됩니다.

단계	주체	산출물	타임박스
① Issue	리포터 (Chrome Ext / Widget)	스크린샷 + 메타 + MCP 컨텍스트	즉시
② PR	Claude Code	브랜치 + diff + PR #N	≤ 30분
③ Preview	Vercel	Preview URL + 체크 결과	≤ 5분
④ Merge	사람 리뷰 → 머지	`main` 업데이트 + 이슈 자동 클로즈	사람 시간

각 단계의 결과(브랜치 이름·PR 번호·Preview URL·머지 SHA)는 이슈 상세 페이지의 "AI Fix 실행 로그" 섹션에 누적 기록됩니다. MCP 의 get_issue 응답 ai_fix 필드로도 조회 가능합니다.

PLAN / IMPLEMENT 2단계

Claude Code 는 한 방에 코드를 수정하지 않습니다. PLAN 단계에서 수정 계획을 먼저 텍스트로 출력하고, IMPLEMENT 단계에서 실제 diff 를 만듭니다. 사람이 PLAN 만 보고 멈출 수 있도록 분리되어 있습니다.

단계	입력	출력	사용자 개입
PLAN	이슈 메타 + 코드베이스 컨텍스트	수정할 파일 목록 + 변경 요지 + 예상 분량	"Plan only" 시 여기서 종료
IMPLEMENT	PLAN 결과 + 사용자 승인	브랜치 + diff + 커밋 + PR	"Plan + Implement" 시 자동 진행

PLAN 의 텍스트 결과는 이슈 코멘트로 자동 첨부되어, 머지 후에도 의사결정 흔적이 남습니다.

30분 타임아웃

단일 AI Fix 실행의 상한은 30분 입니다. 30분이 지나면 Claude Code 세션이 자동 중단되고, 그 시점까지 만들어진 부분 결과를 PR 로 묶어 제출합니다. 타임아웃 자체는 비정상 종료가 아닌 정상 흐름으로 처리되며, 이슈 상세에 "Timed out · partial result" 마커가 표시됩니다.

타임아웃이 발생한 PR 은 일반 PR 과 동일하게 리뷰 가능하며, 추가 작업이 필요하면 같은 이슈에서 AI Fix 를 다시 트리거할 수 있습니다(이때는 새 브랜치가 만들어집니다).

3-버튼 매트릭스

이슈 상세 페이지에서 사용자가 누르는 버튼은 3 종입니다.

버튼	Claude Code 가 하는 일	토큰 부담	복구 경로
Plan only	수정 계획만 텍스트로 작성	낮음 (계획 길이에 비례)	Plan 만 보고 사람이 직접 구현
Plan + Implement	PLAN → 브랜치 생성 → diff 커밋 → PR 생성	중~높음 (수정 범위에 비례)	PR 에서 변경사항 리뷰 · revert
Custom prompt	사용자 지정 프롬프트로 실행	프롬프트에 따라	PR 이 생성되면 동일 revert

Custom prompt 는 이슈 컨텍스트는 자동 주입하되, 추가 지시를 자유 텍스트로 덧붙이는 모드입니다. 예: "테스트 코드까지 추가해줘", "기존 디자인 토큰만 사용해줘".

Vercel 연동 전제

AI Fix 의 Preview 자동 추적 기능을 사용하려면 프로젝트에 Vercel 통합이 활성화되어 있어야 합니다. 통합이 없으면 PR 까지는 정상 생성되지만 Preview URL 이 이슈에 첨부되지 않습니다.

설정 경로: /settings/projects/[projectId]/integrations/vercel

연결되면 PR 이 생성되는 즉시 Vercel 이 Preview 배포를 시작하고, 체크 결과(빌드 성공/실패·체크 URL)가 webhook 으로 QA Note 에 도달해 이슈에 자동 첨부됩니다.

결과 추적 — Preview → Production

PR 머지 이후의 Production 배포까지가 AI Fix 의 추적 범위입니다.

PR 이 main 으로 머지됨
Vercel 이 Production 배포를 시작 (vercel build && vercel deploy --prod)
배포 결과(성공/실패·배포 URL·SHA)가 이슈에 자동 첨부됨
성공 시 이슈 상태가 resolved 로 자동 전환 (옵션)
실패 시 이슈 상태는 그대로 유지되고, 알림이 발송됨

자동 상태 전환 옵션은 프로젝트 설정에서 끌 수 있습니다(/settings/projects/[projectId]/automation).

코드 예시

이슈 상세 페이지의 "AI Fix · Plan + Implement" 버튼을 클릭하거나, MCP 가 연결된 환경에서는 한 줄로 트리거합니다.

bash

# Claude Code 에서 이슈 permalink 로 직접 호출
claude-code "https://qanote.app/i/abc-42 를 수정해줘"

내부적으로 Claude Code 는 resolve_by_url MCP 도구로 이슈 컨텍스트를 가져온 뒤, GitHub App 권한으로 새 브랜치를 만들고 PR 을 제출합니다.

트러블슈팅

Claude Code 가 응답하지 않음

Anthropic 측 토큰 한도 초과 여부를 먼저 확인합니다. Claude Code 콘솔에서 사용량 확인 가능합니다.
이슈 컨텍스트가 너무 큰 경우(스크린샷 5장 + DOM 500KB + 네트워크 로그 50건) 일부 메타데이터가 잘립니다. 이슈에 "context truncated" 마커가 표시됩니다.

PR 생성 실패

GitHub App 권한이 만료되었거나 repo 접근 권한이 회수된 경우입니다. 프로젝트의 /settings/ai-fix 화면에서 재연결합니다.
같은 이슈에서 만든 기존 브랜치가 충돌하는 경우, 새 실행은 자동으로 -2, -3 접미사를 붙여 회피합니다.

타임아웃 발생

부분 결과 PR 이 생성되면 그대로 리뷰하면 됩니다. 추가 변경이 필요하면 같은 이슈에서 AI Fix 를 다시 트리거합니다.
타임아웃이 반복되는 경우 PLAN 단계만 실행해 수정 범위를 줄인 뒤, 사람이 분할 PR 로 진행하는 편이 빠릅니다.