Claude Code가 PR을 만들 수 있는 이유 - GitHub CLI와 API의 구조부터 이해하기

Claude Code가 PR을 만든다? 어떻게?

AI 코딩 도구를 쓰다 보면 이런 장면을 만납니다. "이 기능 추가하고 PR 올려줘"라고 했더니, Claude Code가 코드를 수정하고, 커밋하고, 새 브랜치에 푸시하고, Pull Request까지 만들어버립니다.

Claude Code 자체에 "PR 생성" 버튼이 있는 걸까요? 아닙니다. 비밀은 훨씬 단순합니다. Claude Code는 터미널 명령어를 실행할 수 있고, 거기에 GitHub CLI(gh)와 GitHub REST API라는 도구가 있습니다.

이 글에서는 그 구조를 처음부터 풀어봅니다.

GitHub API가 먼저다 - 모든 것의 기반

GitHub는 웹사이트만 제공하는 서비스가 아닙니다. REST API를 통해 GitHub의 거의 모든 기능을 프로그램으로 제어할 수 있습니다.

예를 들어 PR을 하나 만들고 싶다면, 다음처럼 HTTP 요청 하나로 끝납니다:

POST https://api.github.com/repos/{owner}/{repo}/pulls

{
  "title": "새 기능 추가",
  "body": "변경 내역 설명",
  "head": "feature/my-branch",
  "base": "main"
}

이 요청을 보내면 GitHub 서버가 PR을 만들고 URL을 돌려줍니다. 브라우저에서 클릭할 필요가 없습니다.

GitHub API가 생긴 이유

GitHub API는 2009년부터 제공됐습니다. 초기에는 단순히 "다른 서비스와 연동"하려는 목적이었습니다. CI/CD 도구가 빌드 결과를 GitHub에 올리거나, 슬랙이 PR 알림을 보내거나, 사내 시스템이 이슈를 자동으로 생성하는 식으로 활용됐습니다.

핵심 철학은 "웹 UI에서 할 수 있는 건 API로도 할 수 있어야 한다"입니다. 결과적으로 레포지토리 생성, 브랜치 관리, 이슈, PR, 코드 리뷰, Actions 트리거까지 API로 가능합니다.

GitHub CLI (gh) - API를 사람이 쓸 수 있게

REST API는 강력하지만 직접 쓰기엔 불편합니다. 매번 curl로 JSON을 만들고, 토큰을 헤더에 붙이고, 응답을 파싱해야 합니다.

2020년 GitHub가 공식 CLI 도구인 gh를 출시한 이유가 여기 있습니다. gh는 GitHub API의 래퍼(wrapper)입니다. 내부적으로 API를 호출하지만, 사람이 쓰기 편한 명령어 형태로 포장해줍니다.

gh로 PR 만들기

# PR 생성 (대화형)
gh pr create

# PR 생성 (옵션 직접 지정)
gh pr create --title "새 기능 추가" --body "변경 내역" --base main

# PR 목록 보기
gh pr list

# 특정 PR 체크아웃
gh pr checkout 42

# PR 머지
gh pr merge 42 --squash

내부적으로 이 명령들은 GitHub REST API를 호출합니다. 하지만 사용자는 JSON 구조나 엔드포인트 URL을 몰라도 됩니다.

gh가 API보다 편한 이유

• 인증 자동 처리: gh auth login 한 번이면 이후 모든 명령에서 자동으로 토큰을 사용합니다.
• 현재 레포 감지: git remote 설정을 읽어서 어느 레포인지 자동 파악합니다.
• 브라우저 연동: gh pr view --web으로 PR을 브라우저에서 바로 열 수 있습니다.
• 터미널 친화적 출력: API는 JSON을 반환하지만, gh는 사람이 읽기 좋은 형태로 출력합니다.

Claude Code가 PR을 만드는 실제 흐름

이제 Claude Code가 PR을 만드는 과정을 단계별로 따라가 봅니다.

# 1. 코드 수정 (Claude Code가 파일 편집)
# src/auth.ts 수정...

# 2. 새 브랜치 생성 및 커밋
git checkout -b feature/add-oauth
git add -A
git commit -m "feat: OAuth 로그인 기능 추가"

# 3. 브랜치 push
git push origin feature/add-oauth

# 4. PR 생성 (gh CLI 활용)
gh pr create \
  --title "feat: OAuth 로그인 기능 추가" \
  --body "## 변경 내역\n- Google OAuth 연동 추가\n- 로그인 페이지 UI 업데이트\n\n## 테스트\n- 로컬에서 OAuth 플로우 확인 완료" \
  --base main \
  --label "enhancement"

각 단계가 다 일반 터미널 명령어입니다. Claude Code가 "PR 생성" 기능을 내장한 게 아니라, 터미널 명령어를 실행할 수 있는 능력 + gh CLI라는 도구의 조합입니다.

Claude Code 공식 플러그인 중 /commit-push-pr 커맨드도 내부적으로 이 흐름을 자동화한 것입니다.

API 직접 호출 방식

gh CLI 없이 GitHub API를 직접 호출하는 방식도 있습니다. 더 세밀한 제어가 필요할 때, 또는 gh가 설치되지 않은 CI 환경에서 유용합니다.

# curl로 PR 생성
curl -X POST \
  -H "Authorization: Bearer $GITHUB_TOKEN" \
  -H "Accept: application/vnd.github+json" \
  https://api.github.com/repos/owner/repo/pulls \
  -d '{
    "title": "feat: OAuth 로그인 기능 추가",
    "body": "변경 내역 설명",
    "head": "feature/add-oauth",
    "base": "main"
  }'

Claude Code는 이 방식도 사용할 수 있습니다. 어떤 방법을 쓸지는 환경에 따라 다릅니다. gh가 설치된 개발 환경에서는 gh를 씁니다. CI/CD 파이프라인이나 GitHub Actions 안에서는 API 직접 호출이 더 자연스럽습니다.

GitHub Actions와의 연결 - 자동화가 닫히는 고리

PR 생성에서 끝나지 않습니다. GitHub API와 Actions가 연결되면 자동화의 고리가 완성됩니다.

# .github/workflows/pr-check.yml
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Claude Code 리뷰 실행
        run: |
          # Claude Code가 PR의 변경 내역을 분석하고 코드 리뷰 코멘트 작성
          gh pr review ${{ github.event.number }} \
            --comment \
            --body "자동 코드 리뷰 결과..."
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Claude Code가 PR을 만들면 → GitHub Actions가 자동으로 트리거되고 → CI 테스트, 코드 리뷰, 보안 검사 등이 실행되고 → 결과가 PR에 코멘트로 달립니다. 사람이 개입하는 지점은 최종 머지 승인뿐입니다.

API 덕분에 가능해진 것들

GitHub API와 CLI가 없었다면 Claude Code의 능력은 "코드를 쓰는 것"에서 멈췄을 겁니다. API가 있기 때문에 AI 에이전트가 GitHub 생태계 전체를 제어할 수 있습니다.

이슈 관리

# 이슈 생성
gh issue create --title "버그: 로그인 실패" --body "재현 방법..."

# 이슈에 코멘트 달기
gh issue comment 123 --body "원인 파악 완료, 수정 중"

# 이슈 닫기
gh issue close 123

코드 리뷰

# PR 변경 내역 보기
gh pr diff 42

# 리뷰 코멘트 달기
gh pr review 42 --comment --body "이 부분 null 체크 필요합니다"

# 승인
gh pr review 42 --approve

CI/CD 상태 확인

# PR의 CI 상태 확인
gh pr checks 42

# 실패한 Actions 로그 보기
gh run view --log-failed

AI 에이전트가 이 명령들을 자유롭게 쓸 수 있다는 건, 이슈 확인 → 브랜치 생성 → 코드 수정 → 테스트 → PR 생성 → 리뷰 → 머지까지 전체 개발 사이클을 자동화할 수 있다는 뜻입니다.

"CLI가 AI 친화적"이라는 것의 의미

최근 "AI 에이전트를 위해 CLI를 다시 작성해야 한다"는 논의가 많습니다. GitHub CLI는 이미 이런 관점에서 잘 설계된 도구 중 하나입니다.

• --json 옵션: 거의 모든 gh 명령에 --json을 붙이면 AI가 파싱하기 좋은 JSON으로 출력합니다.
• 예측 가능한 동작: 같은 명령을 실행하면 항상 같은 형태의 결과가 옵니다. AI가 다음 단계를 예측할 수 있습니다.
• 에러 코드: 명령 실패 시 명확한 에러 코드와 메시지를 반환합니다. AI가 실패를 감지하고 재시도 로직을 구성할 수 있습니다.

# AI가 활용하기 좋은 구조화된 출력 예시
gh pr list --json number,title,state,createdAt --limit 10

# 결과:
[
  {
    "number": 42,
    "title": "feat: OAuth 추가",
    "state": "OPEN",
    "createdAt": "2026-03-13T08:00:00Z"
  }
]

실제로 경험해보기

개발 환경에 gh를 설치하고 Claude Code와 함께 써보는 방법은 간단합니다.

# macOS
brew install gh

# Ubuntu/Debian
sudo apt install gh

# 인증
gh auth login

# 이후 Claude Code에서
# "현재 변경 내역으로 PR 만들어줘" 라고 하면
# Claude Code가 gh pr create 명령을 실행합니다

한 번 설정해두면 이후로는 Claude Code가 코드 수정부터 PR 생성까지 알아서 처리합니다.

마치며 - AI 에이전트가 강력해지는 방식

Claude Code의 "PR 생성 능력"은 새로운 마법이 아닙니다. 이미 존재하는 도구들(git, gh, GitHub API)을 조합해서 쓰는 것뿐입니다.

이것이 AI 에이전트가 강해지는 방식입니다. AI 모델 자체의 능력뿐만 아니라, 어떤 도구를 얼마나 잘 활용할 수 있느냐가 실제 능력을 결정합니다.

GitHub CLI와 API가 잘 설계되어 있을수록, Claude Code 같은 AI 에이전트가 더 많은 것을 자동화할 수 있습니다. 반대로 말하면, AI 시대에 소프트웨어가 CLI와 API를 갖추는 것은 선택이 아니라 필수가 되고 있습니다.

"내 서비스에 CLI가 없다면, AI 에이전트가 내 서비스를 제어할 수 없다." - 이게 지금 개발자들이 CLI를 다시 주목하는 이유입니다.

---

이 글은 생성형 AI의 도움을 받아 작성되었습니다. 원본 자료를 기반으로 AI가 초안을 생성하고, 작성자가 검토·편집하였습니다.