AI Fix · 자동 PR
이슈 한 건에서 Claude Code 가 PR · Preview · Production 머지까지 주도합니다. 토큰은 Claude Code 구독에서 차감됩니다.
목차
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 가 연결된 환경에서는 한 줄로 트리거합니다.
# 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 로 진행하는 편이 빠릅니다.