[#005] Cursor Background Agents와 Claude Agent SDK로 이슈를 PR 초안까지 올리는 승인형 버그픽스 에이전트 만들기

이번에 만들 것

이번 수업에서는 GitHub issue 본문만 넣으면 조사 agent가 원인 후보를 찾고, fix agent가 patch 초안을 만들고, reviewer agent가 체크리스트를 채운 뒤 마지막 적용은 내가 승인할 때만 넘어가는 승인형 버그픽스 에이전트를 만듭니다. 지난 #004가 데이터를 읽어 도구를 만드는 편이었다면, 이번엔 한 단계 더 가서 AI가 여러 단계를 스스로 굴리게 만져봅니다.

최근 Claude 쪽은 Claude Agent SDK와 memory tool, context editing이 붙었고요, OpenAI 쪽은 Agents SDK와 background mode가 붙었습니다. Cursor는 3.0에서 Agents Window가 나왔고, GitHub Copilot도 cloud agent와 memory까지 갔죠. v0의 clarifying questions, Replit Agent v2까지 보면 다들 같은 방향이라서, 이 패턴을 직접 한 번 손에 익혀두는 게 좋겠더라구요.

준비물

Claude Code가 열리는 로컬 저장소 하나, Cursor 최신 버전, OpenAI API 키가 필요합니다. 지난 #002에서 만든 로컬 웹앱 저장소가 있으면 그대로 써도 되고, 없으면 작은 사이드 프로젝트 저장소면 충분합니다. 버그는 일부러 하나 만들어도 됩니다. 예를 들면 검색이 대소문자를 못 맞춘다든지, 저장 버튼이 두 번 눌리는 식이면 좋아요.

따라하기

Step 1: 저장소 규칙을 먼저 기억시킵니다

Claude Code를 연 뒤 첫 입력에서 규칙 파일부터 만들게 하세요. 여기서 테스트 명령과 금지 범위를 정확히 박아두는 게 중요합니다.

이 저장소를 읽고 승인형 버그픽스 에이전트가 따라야 할 규칙을 CLAUDE.md로 정리해줘. 테스트 명령, 수정하면 안 되는 폴더, PR 설명 형식, 승인 체크리스트를 포함해. 사람이 승인하기 전에는 절대 파일을 덮어쓰지 말라고 적어줘.

정상이라면 `CLAUDE.md`에 실행 명령과 체크리스트가 보입니다. 여기서 테스트 명령을 대충 적으면 안 됩니다. `npm test`처럼 오래 걸리거나 flaky한 명령을 넣으면 뒤 단계에서 계속 흔들립니다.

Step 2: 에이전트 3개짜리 워크플로를 뼈대부터 만듭니다

이제 Claude Code에게 OpenAI Agents SDK 기반 오케스트레이터를 만들게 합니다. 출력은 바로 적용 파일이 아니라 `plan.json`, `patch.diff`, `review.md` 세 개로 고정하세요.

OpenAI Agents SDK로 triage_agent, fix_agent, reviewer_agent 세 개를 가진 승인형 워크플로 앱을 만들어줘. 입력은 issue 텍스트 하나이고, triage는 재현 경로와 의심 파일만, fix는 patch.diff만, reviewer는 승인 전 체크리스트와 위험 요약만 만들게 해줘. tracing을 켜고, 오래 걸리는 테스트는 background 작업으로 돌릴 수 있게 구성해줘.

정상이라면 `agents/` 같은 폴더와 실행 스크립트가 생기고, 추적 로그를 보는 파일이나 안내 문서가 같이 나옵니다. 여기서 fix agent가 곧바로 코드를 수정하게 두면 안 됩니다. 처음엔 반드시 diff까지만 만들게 막아야 합니다.

Step 3: Cursor Background Agent에게 조사만 맡깁니다

Cursor 3.0의 Agents Window나 Background Agent를 열고 같은 저장소에서 조사만 따로 돌립니다. 이 단계는 병렬로 굴리는 맛을 보는 구간입니다.

이 이슈를 조사해줘. 아직 코드는 수정하지 말고, 재현 절차, 원인 후보 3개, 가장 가능성 높은 파일 경로만 남겨줘. 테스트를 돌렸다면 어떤 명령을 썼는지도 적어줘.

이런 결과가 나오면 정상입니다. 수정 커밋 없이 조사 메모만 남고, 파일 경로가 2~5개 안쪽으로 좁혀집니다. 여기서 수정까지 허용하면 cloud agent가 과하게 손대는 경우가 있어서, 조사와 수정을 분리하는 게 훨씬 낫습니다.

Step 4: 사람 승인 화면을 붙입니다

다시 Claude Code로 돌아와 승인 게이트를 만듭니다. 체크박스 세 개가 모두 켜지기 전에는 apply 버튼이 비활성화되게 하세요.

Cursor 조사 결과와 현재 patch.diff를 함께 보여주는 간단한 승인 화면을 만들어줘. 체크 항목은 재현 성공, 테스트 통과, 변경 범위 확인 세 가지로 하고, 세 항목이 모두 true일 때만 apply가 가능하게 해줘. apply 전에는 원본 파일을 건드리지 말아줘.

정상이라면 로컬에서 작은 승인 페이지나 CLI 확인 단계가 생깁니다. 여기서 flaky 테스트를 체크 항목에 넣으면 안 됩니다. 사람이 눌러도 매번 결과가 달라지면 승인 게이트가 의미가 없어집니다.

Step 5: 가짜 이슈로 끝까지 한 번 돌려봅니다

실제 버그를 바로 넣지 말고, 재현이 쉬운 샘플 이슈로 한 바퀴 먼저 도세요.

sample_issue.md를 만들어 검색 입력이 대문자면 결과가 비는 버그를 재현해줘. 워크플로를 끝까지 실행해서 plan.json, patch.diff, review.md를 만든 뒤 승인 전 상태에서 멈춰줘. 내가 승인하면 적용하고 테스트까지 다시 돌려줘.

`plan.json`, `patch.diff`, `review.md`가 순서대로 나오고, 승인 전에는 코드가 그대로면 성공입니다. 승인 후에만 파일이 바뀌고 테스트가 다시 돌면 정상이에요. 첫 실행부터 실서비스 이슈를 넣으면 로그만 길어지고 어디서 꼬였는지 안 보입니다.

직접 해보기

자기 저장소에서 자주 오는 이슈 하나를 골라 같은 구조로 바꿔보세요. 추천 과제는 로그인 폼, 검색, 파일 업로드 중 하나입니다. 세 기능은 재현 문장이 분명해서 triage agent 품질 차이가 바로 보입니다.

결과물 체크

성공 기준은 세 가지입니다. 이슈 텍스트 하나로 조사 메모와 patch.diff가 자동 생성돼야 하고, 승인 전에는 원본 코드가 바뀌지 않아야 하며, 승인 뒤에는 테스트 결과까지 다시 남아야 합니다. 이 셋 중 하나라도 빠지면 아직 에이전트가 아니라 자동 실행 스크립트에 가깝습니다.

다음 편 예고

다음 편에서는 이 승인형 에이전트를 여러 저장소에 붙여서 실제 팀 워크플로처럼 굴려봅니다.