기술에 익숙하지 않은 친구에게 풀 리퀘스트가 무엇인지 설명하려다 Krispy Kreme 컨베이어 벨트처럼 멍해지는 눈빛을 본 적이 있나요? 이제 AI가 여러분의 레포지토리를 이해할 뿐만 아니라 PR까지 자동으로 열어준다고 상상해 보세요. 2025년에 오신 것을 환영합니다. 여러분의 코드 편집기는 공동 조종사이자 뒷좌석 운전사이자, 제대로 설정하기만 한다면 꽤 괜찮은 인턴이 될 것입니다.
이 가이드에서는 GitHub를 Claude Code에 연결하고 풀 리퀘스트를 자동으로 생성하는 방법을 보여줍니다. 단계별 설정, 실제 워크플로우, 그리고 피해야 할 몇 가지 함정을 통해 "이게 뭐지?"에서 "배포해!"로 넘어갈 것입니다. GitHub를 연결하고, Claude Code가 무슨 일이 일어나고 있는지 확인하게 하고, 알고리즘 악마와 거래한 것 같은 느낌 없이 실제로 병합할 수 있는 PR을 열고 업데이트할 수 있게 할 것입니다.
참고: 여기서는 두 가지 주요 경로를 보게 될 것입니다. Claude Code의 GitHub Actions 통합을 사용하는 방법과 MCP (Model Context Protocol) 서버를 사용하여 Claude에게 GitHub API에 대한 안전하고 범위가 지정된 액세스 권한을 제공하는 방법입니다. 어떤 것을 선택해야 할까요? GitHub에서 바로 플러그 앤 플레이 PR 지원을 원한다면 Actions 경로가 가장 좋습니다. 세분화된 권한으로 로컬에서 채팅 기반 레포지토리 제어를 원한다면 MCP가 강력한 도구입니다.
구축할 내용
- GitHub를 Claude Code에 안전하게 연결합니다.
- Claude가 레포지토리를 분석하고, 변경 사항을 제안하고, PR을 열도록 합니다.
- 리뷰, 라벨, 체크리스트, 심지어 후속 커밋까지 자동화합니다.
- 전체 모노레포 이름을 "final_final_v2"로 바꾸지 않도록 안전 장치를 추가합니다.
이것이 왜 중요할까요?
컨텍스트 전환은 아무도 투표하지 않은 생산성 세금이기 때문입니다. 주니어 개발자가 (컨디션 좋은 날) 기대하는 수준으로 PR을 열 수 있는 AI는 실제로 시간을 절약해줍니다. 인간을 대체하기 위한 것이 아니라 (진정하세요) 엔지니어링의 "아, 상용구" 부분을 대체하기 위한 것입니다.
경로 A: Claude Code GitHub Actions로 PR 자동 생성
하루 종일 GitHub 내부에 살고 있다면 (저희와 함께 하세요), 이 경로는 이슈 및 PR에서 코드를 분석하고, 변경 사항을 제안하고, 심지어 PR을 열거나 업데이트할 수 있는 봇을 제공합니다. 레포지토리에서 바로요.
필요한 것
- 여러분이 제어하는 GitHub 레포지토리 (또는 울지 않고 망가뜨릴 수 있는 브랜치).
- Actions 및 secrets를 구성하기 위한 레포지토리 관리자 액세스 권한.
- Action 또는 워크플로우에 필요한 경우 Claude API 키.
1단계: 레포지토리에서 GitHub Actions 활성화
- 레포지토리 → 설정 → Actions → 일반으로 이동합니다.
- "모든 Actions 및 재사용 가능한 워크플로우 허용"을 활성화합니다 (또는 보안 담당자가 이미 눈치를 주고 있다면 조직에서 승인한 Actions으로 제한).
2단계: Claude Code 워크플로우 추가
선호하는 워크플로우에 따라 트리거를 사용하여 .github/workflows/claude-pr-bot.yml을 만듭니다. 다음은 두 가지 일반적인 패턴입니다.
옵션 1: 이슈 기반 PR
- 특정 라벨 (예: ai-pr)이 있는 이슈를 열면 워크플로우가 실행됩니다.
- 이슈 프롬프트 (예: "다크 모드 토글 추가")를 읽고, 새 브랜치를 만들고, Claude를 사용하여 파일을 편집하고, 커밋을 푸시하고, 자세한 요약과 함께 PR을 엽니다.
옵션 2: 기존 PR에 대한 댓글 기반 편집
- @claude 설정 모달을 리팩터링해 주세요라는 댓글을 달면 워크플로우가 실행됩니다.
- Diff를 분석하고, 변경 사항을 제안하고, PR 브랜치에 업데이트를 푸시합니다.
시작 워크플로우 (개략적인 스케치)
name: Claude PR Bot
on:
issues:
types: .
- 통합 및 사용 사례에 대한 빠른 가이드는 실제 팀에서 자동화할 수 있는 것 (그리고 자동화할 수 없는 것)에 대한 조감도를 제공합니다.
- 시각적인 학습자라면 이 연습에서는 AI PR이 처음부터 끝까지 자동으로 생성되는 모습을 보여줍니다.
경로 B: MCP를 통해 GitHub를 Claude Code에 연결 (로컬 파워 유저용)
Claude가 로컬 레포지토리 컨텍스트 (컴퓨터의 파일, 관리하고 있는 브랜치, 신뢰하는 명령)와 함께 작동하도록 하려면 MCP가 권한 있는 브리지를 제공합니다. 레포지토리의 도어맨이라고 생각하세요. Claude가 열 수 있는 문을 결정합니다.
필요한 것
- MCP 도구를 지원하는 Claude Desktop 또는 IDE 통합.
- 범위를 제한하는 토큰으로 구성된 로컬에서 실행하는 GitHub MCP 서버.
- 정말로 필요한 범위만 있는 개인 액세스 토큰 (PAT) (예: repo:status, public_repo, pull_request write).
1단계: GitHub MCP 서버 가져오기
- 특정 GitHub API 작업 (이슈 검색, 브랜치 생성, PR 열기 등)을 노출하는 공식 오픈 소스 서버가 있습니다. 필요한 것만 활성화하도록 구성할 수 있으므로 AI 혼란을 줄이고 보안을 유지할 수 있습니다. MCP 서버 및 예제에 대한 자세한 내용은 중앙 디렉토리를 확인하세요.
2단계: 서버와 통신하도록 클라이언트 구성
- 클라이언트 구성 파일 (예: AI 앱용 JSON 구성)에서 GitHub MCP 서버를 등록하고, 환경 변수를 통해 토큰을 전달하고, 허용된 레포지토리를 화이트리스트에 추가합니다.
- 프로 팁: 토큰을 구성 파일이 아닌 시스템 키체인 또는 dotenv 파일에 넣으세요. 다음 전체 회의에서 경고의 예가 되지 마세요.
3단계: 도구 표면 영역 테스트
- Claude에게 열린 이슈를 나열하거나, 특정 파일을 읽거나, 브랜치를 만들도록 요청하세요. 명시적으로 허용하지 않은 작업을 수행할 수 없는지 확인하세요.
- 기본 명령을 정상적으로 확인한 후에만 create_pull_request를 활성화해야 합니다.
4단계: Claude가 PR을 제안하고 열도록 합니다.
- 프롬프트 예시: "레포지토리 org/app-frontend에서 새 브랜치 feat/dark-toggle을 만들고, SettingsPanel.tsx에서 다크 모드용 설정 토글을 구현하고, 테스트를 업데이트하고, QA용 체크리스트와 함께 PR을 여세요."
- 서버는 레포지토리 상태를 읽고, 변경 사항을 쓰고 (로컬 파일 도구를 구성한 경우), 브랜치를 푸시하고, 템플릿으로 PR을 열고, 요약을 게시합니다.
솔직히 말해서: 실제로 필요한 안전 장치
- 읽기 전용 드라이 런: Claude가 쓰기 액세스 권한을 갖기 전에 통합 diff (git diff)를 생성하도록 합니다. 직접 확인한 후에 병합하세요.
- 템플릿화된 PR 본문: 위험 참고 사항, 테스트 계획 및 롤아웃 단계를 포함합니다. 봇이 템플릿을 완성하게 하고, 사람이 검토하게 하세요.
- 라벨링 규칙: ai-generated 및 needs-tests와 같은 라벨을 자동으로 적용하여 검색 가능하고 정직하게 유지합니다.
- 브랜치 이름 지정: 브랜치 보호 규칙과 함께 접두사 (ai/ 또는 bot/)가 필요합니다. 로봇에게도 유니폼이 필요합니다.
일화 시간: AI에게 "인증 버그를 수정해 주세요"라고 요청했습니다. 인증을 제거하여 "수정"했습니다. 생산성에는 좋았지만 다른 모든 것에는 끔찍했습니다. 범위를 좁게 유지하고, 프롬프트를 구체적으로 유지하고, CI 테스트를 엄격하게 유지하세요.
제로에서 PR까지: 현실적인 엔드 투 엔드 시나리오
시나리오: React 프로젝트에서 불안정한 디바운스 테스트 수정
- 이슈를 엽니다: "디바운스 유틸: CI에서 200ms 경계에서 불안정합니다." ai-pr로 태그합니다.
- 워크플로우가 트리거됩니다. debounce.ts 및 관련 테스트를 검색합니다.
- Claude는 diff를 제안합니다: jest.useFakeTimers로 타이머를 조정하고, 어설션에 마진을 추가하고, 문서를 업데이트합니다.
- 봇은 제목, 요약, 근거, 테스트 계획 및 위험 평가와 함께 PR을 엽니다.
- Diff를 검토하고, 다시 푸시합니다: "delay=0인 경우의 엣지 케이스입니다."
- @claude delay=0을 즉시 플러시로 처리하고 테스트를 추가하세요라는 댓글을 답니다. 워크플로우가 다시 실행되고 커밋을 푸시합니다.
- CI가 통과됩니다. 스쿼시하고 병합합니다. 어딘가에서 불안정한 테스트가 "졌다"고 외칩니다.
좋은 프롬프트의 모습 (및 피해야 할 것)
- 좋음: "SettingsPanel.tsx에 다크 모드 토글을 추가합니다. localStorage에 유지합니다. SettingsPanel.test.tsx를 업데이트합니다. ESLint 규칙을 따릅니다. /src/ui/ 및 /src/utils/만 수정합니다. 최대 250줄."
안전하게 만들기: 보안 및 규정 준수 빠른 확인
- 토큰 범위: 필요한 경우에만 repo:contents write를 사용합니다. PR 생성에는 pull_request write를 선호합니다.
- 레포지토리 허용 목록: 봇을 단일 레포지토리 또는 조직으로 잠급니다.
- 로깅: 봇이 작업 및 프롬프트를 기록하는지 확인합니다 (비밀 제외). Dockerfile을 "개선"할 때 증거가 필요합니다.
- 브랜치 보호: ai/* 브랜치에 대해 두 명의 인간 승인이 필요합니다.
문제 해결: 봇이 작동하지 않을 때
- 브랜치를 푸시할 수 없습니다: Actions 권한에 contents: write가 있는지, 토큰에 레포지토리 쓰기 액세스 권한이 있는지 확인합니다.
- 빈 PR을 엽니다: 컨텍스트 빌더가 올바른 파일을 전달하지 않습니다. 파일 선택 논리를 강화하세요.
- 큰 레포지토리에서 시간 초과됩니다: 컨텍스트를 변경된 경로 또는 매니페스트로 제한합니다. AI는 우리와 마찬가지로 10GB 모노레포에서 소화 불량을 겪습니다.
- PR 템플릿을 무시합니다: 템플릿이 .github/pull_request_template.md에 있거나 레포지토리 설정에 연결되어 있는지 확인합니다.
어떤 경로를 사용해야 할까요?
- 이슈 또는 댓글에서 PR을 자동으로 생성하는 간단한 방법을 원하고 모든 것이 GitHub에서 발생하는 경우 GitHub Actions를 사용합니다.
- Claude가 로컬 환경에서 또는 매우 구체적인 제어 기능을 사용하여 여러 도구에서 작동하도록 하려면 MCP를 사용합니다.
참고: 워크플로우에 대한 빠른 정상성 검사를 수행하거나 견고한 시작 프롬프트를 생성하려면 Sider.AI가 PR 템플릿 및 안전 장치 프롬프트를 초안하고 실제 레포지토리 스니펫으로 반복하는 데 도움을 줄 수 있습니다. 실제로 코드를 작성하는 의견이 강한 편집자가 있는 것과 같습니다. 그리고 여러분의 책상 의자를 훔치지 않습니다. 복사하고 싶은 일반적인 패턴
- AI PR 라벨 및 CODEOWNERS: 로봇과 논쟁하는 것을 즐기는 리뷰 그룹으로 ai/* PR을 라우팅합니다.
- 단계별 커밋: Claude에게 "물건"이라는 하나의 메가 커밋 대신 명확한 메시지로 작은 원자 커밋을 만들도록 요청하세요.
- 테스트 우선 모드: 워크플로우가 먼저 테스트를 생성하고, CI를 실행한 다음 구현을 생성하도록 합니다. 더 느립니다. 더 좋습니다.
- 병합 후 작업: 문서, 기능 플래그 또는 정리에 대한 후속 이슈를 자동으로 열기 위한 워크플로우를 추가합니다.
빠른 경쟁적 감각 확인
- 일부 사람들은 다른 LLM을 유사한 GitHub 흐름에 연결하고 있습니다. 작동하지만 Claude Code의 코드 추론 능력과 "잘 모르겠습니다"라고 말하는 의지는 추측하고 확인하는 시간을 절약해 줄 수 있습니다. GitHub Actions 통합은 리뷰가 자연스럽게 발생하는 곳에 유지하고, MCP 경로는 파워 유저에게 유연합니다.
10분 설정 체크리스트
- 경로 선택: GitHub Actions (더 빠름) 또는 MCP (더 많은 제어).
- 워크플로우를 추가하거나 MCP 서버를 구성합니다.
- 타이트한 컨텍스트 빌더를 구축합니다: 파일 목록, 제한 및 규칙.
- 먼저 작은 변경 사항으로 테스트합니다. 병합합니다. 축하합니다. PM에게 "처리량을 확장했다"고 말하세요.
유용한 빠른 참조
- Claude Code GitHub Actions 문서 (패턴, 트리거, 예제).
- 비디오 연습: AI 생성 PR 엔드 투 엔드.
- 세분화된 권한 부여 액세스를 위한 GitHub MCP 서버.
- 영감을 얻기 위한 MCP 서버 디렉토리 및 예제.
Stern의 마무리
Claude Code로 PR을 자동화한다고 해서 엔지니어링 팀을 대체할 수는 없습니다. 엔지니어링 팀이 가장 싫어하는 잡무를 대체할 것입니다. 좁은 범위, 명확한 프롬프트 및 엄격한 검토로 시작하세요. 봇이 발판을 처리하는 동안 여러분은 생각을 처리하세요. 그런 다음 덕트 테이프와 꿈으로 앱을 함께 유지하고 있다는 것을 알고 있기 때문에 피하고 있던 utils2.ts 파일을 드디어 삭제하는 것과 같은 재미있는 일로 돌아가세요.
이제 미래의 자신을 조금 덜 심술궂게 만드세요. 봇이 제어 불능 상태가 되면요? 되돌리기 버튼이 어디에 있는지 아시죠.
FAQ
Q1: Claude Code가 풀 리퀘스트를 스스로 열 수 있나요?
예. GitHub Actions 또는 MCP 설정을 사용하면 Claude Code가 브랜치를 만들고, 변경 사항을 푸시하고, 요약 및 체크리스트와 함께 풀 리퀘스트를 열 수 있습니다. 권한을 엄격하게 유지하고 인간 검토를 요구하여 보안을 제거하여 보안을 "최적화"하지 않도록 하세요.
Q2: GitHub를 Claude Code에 연결하는 가장 안전한 방법은 무엇인가요?
최소 범위 토큰, 레포지토리 허용 목록 및 브랜치 보호를 사용하세요. Actions 또는 MCP를 사용하든 드라이 런을 활성화하고 AI 생성 풀 리퀘스트를 병합하기 전에 테스트가 통과해야 합니다.
Q3: AI PR이 전체 모노레포를 건드리지 않도록 어떻게 막을 수 있나요?
허용된 디렉토리 및 파일 매니페스트로 컨텍스트 범위를 지정하고 실행당 파일 수를 제한합니다. 좋은 프롬프트도 도움이 됩니다. 경로 및 크기 제한에 대해 구체적으로 설명하세요.
Q4: AI 풀 리퀘스트가 비어 있거나 품질이 낮은 이유는 무엇인가요?
컨텍스트 빌더가 Claude에게 잘못된 파일 또는 너무 적은 세부 정보를 제공하고 있을 수 있습니다. 명확한 목표, 제약 조건 및 테스트 기대치를 제공하고 2단계 흐름을 고려하세요. 먼저 테스트를 생성한 다음 구현을 생성합니다.
Q5: Claude Code에 GitHub Actions 또는 MCP를 사용해야 할까요?
PR 및 리뷰를 위한 빠르고 레포지토리 기본 자동화를 원한다면 GitHub Actions를 사용하세요. 로컬 제어, 사용자 지정 도구 또는 세분화된 권한이 필요한 경우 MCP는 더 많은 설정과 함께 더 많은 기능을 제공합니다.
