Claude Code를 사용해 PR(풀 리퀘스트)을 만들 때, UI 변경 사항이라면 변경 전후의 스크린샷도 PR에 포함되어야 할 경우가 있습니다.
기존 GitHub CLI에는 이미지를 업로드할 수 있는 기능이 없었기 때문에, Claude Code가 스크린샷을 찍더라도 PR에 붙일 수 없어 브라우저에서 PR을 열고 직접 드래그 앤 드롭해야 했습니다.
GitHub CLI v2.99.0(2026년 9월 1일 출시)에서 --attach 플래그가 추가되어, 명령어만으로 이미지나 동영상을 PR, Issue, 댓글에 첨부할 수 있게 되었습니다.
이 글에서는 --attach 사용법과 Claude Code에게 매번 스크린샷을 붙이도록 설정하는 CLAUDE.md 설정을 소개합니다.
--attach 사용법
지원되는 명령어
v2.99.0 기준으로, 다음 명령어에 --attach가 추가되었습니다.
| 대상 | 명령어 |
|---|
| Pull Request | gh pr create / gh pr edit |
| Issue | gh issue create / gh issue edit |
| 댓글 | gh pr comment / gh issue comment |
먼저 로컬의 gh 버전을 확인해 봅니다.
gh --version
# Homebrew의 경우
brew upgrade gh
본문 끝에 추가하기
가장 간단한 사용법은 파일을 --attach에 전달하는 것입니다. 업로드된 이미지는 본문의 가장 마지막 부분에 추가됩니다.
gh pr create --title "로그인 화면의 에러 표시를 수정" --body "에러 메시지 위치를 수정했습니다" \
--attach ./after.png
--attach는 반복 지정이 가능하며, 한 번의 명령으로 최대 50개의 파일까지 첨부할 수 있습니다.
gh pr create --attach ./before.png --attach ./after.png
본문의 원하는 위치에 삽입하기
본문에 로컬 경로로 이미지를 작성하고, 같은 경로를 --attach에 전달하면 gh가 업로드된 URL로 자동으로 변경해 줍니다. 변경 전후를 표로 나란히 보여주고 싶을 때 유용합니다.
gh pr create --title "로그인 화면의 에러 표시를 수정" --body-file ./pr-body.md \
--attach ./before.png --attach ./after.png
## 변경 내용
에러 메시지를 입력란 아래에 표시하도록 했습니다.
## 스크린샷
...
PR 본문에서 ./before.png는 https://github.com/user-attachments/assets/... URL로 대체됩니다.
--body-file을 사용할 경우, 본문의 상대 경로는 본문 파일의 디렉터리를 기준으로 해결되며, 찾지 못하면 현재 디렉터리 기준이 됩니다.
alt 텍스트 추가하기
본문에서 참조하지 않은 이미지에는 경로 뒤에 #를 붙여 alt 텍스트를 지정할 수 있습니다. 지정하지 않으면 파일명이 alt 텍스트가 됩니다.
gh pr create --attach './login.png#로그인 에러 발생 시 표시'
본문에서 처럼 참조하는 경우에는, 본문에 작성한 alt 텍스트가 그대로 사용됩니다.
이미 생성된 PR에 추가하기
gh pr edit로 나중에 이미지를 추가할 수 있습니다. 본문을 지정하지 않으면 기존 본문은 그대로 유지되고 끝에 이미지가 추가됩니다.
gh pr edit 123 --attach ./after.png
리뷰에서 지적된 사항을 수정한 후의 화면을 댓글로 남기고 싶다면 gh pr comment를 사용합니다.
gh pr comment 123 --body "지적해주신 여백을 수정했습니다" --attach ./fixed.png
Claude Code에게 매번 스크린샷을 붙이도록 설정하기
gh에 기능이 추가되었더라도, Claude Code가 --attach
항상 사용해 주는 것은 아닙니다.
스크린샷을 찍었더라도, PR 본문은 텍스트만으로 작성되는 경우가 있습니다. 그래서 CLAUDE.md (프로젝트 루트 디렉토리 또는 모든 프로젝트에 공통으로 적용하려면 ~/.claude/CLAUDE.md) 파일에 PR 생성 시 규칙을 작성해 두겠습니다.
## Pull Request 작성
- UI에 변경 사항이 있는 경우, 변경 전후의 스크린샷을 찍어 PR에 첨부한다.
- 스크린샷은 리포지토리 외부(임시 디렉토리 등)에 저장하고 커밋하지 않는다.
...
몇 가지 보충 설명합니다.
스크린샷은 리포지토리 외부에 두기
리포지토리에 스크린샷을 저장하면, Claude Code가 git add -A를 실행할 때 이미지까지 커밋되는 경우가 있습니다. 임시 디렉토리에 저장시키는 것이 가장 안전합니다.
만약 리포지토리 내에 두고 싶다면, 저장 경로의 디렉토리를 .gitignore에 추가해 둡니다.
실패 시 PR을 재작성하지 않도록 하기
gh pr create --attach는 일부 이미지 업로드에 실패하더라도 PR을 생성합니다. 이때 종료 코드는 0이 아니게 되지만, 생성된 PR의 URL은 표준 출력으로 나옵니다.
종료 코드만 보면, Claude Code가 커맨드 실패로 판단하여 gh pr create를 다시 실행할 가능성이 있습니다. 그러면 같은 브랜치에 PR을 만들려고 시도하다 오류가 발생하거나, 상황 확인을 위해 불필요한 상호작용이 늘어날 수 있습니다.
CLAUDE.md의 마지막 항목은 이를 방지하기 위해 추가된 것입니다.
실제로 시도해 본 결과
이 글을 추가하는 PR을 Claude Code에게 만들게 하고, 변경 전후 스크린샷도 첨부하게 했습니다.
Claude Code는 main 브랜치와 기사 브랜치 각각에서 zenn preview를 실행하고, 헤드리스 Chrome으로 미리보기 화면을 촬영했습니다. 그 후, PR 본문을 임시 파일에 작성하여 Before/After 표를 추가하고, 다음 커맨드로 PR을 업데이트했습니다.
gh pr edit 4 --body-file pr-body.md --attach before.png --attach after.png
## 스크린샷 (zenn preview)
| Before | After |
| --- | --- |
...
본문의 ./before.png와 ./after.png는 업로드 후 URL로 대체되어, PR에서는 다음과 같이 표시되었습니다.
Before/After の表で zenn preview のスクショが並んだ PR の本文
스킬을 사용하는 방법도 있다
CLAUDE.md에 작성하는 대신, 이미지 첨부용 스킬을 넣는 방법도 있습니다.
tonkotsuboy 님의 github-upload-image-to-pr은 로컬 이미지를 PR 본문이나 댓글에 삽입하기 위한 스킬입니다.
gh skill install tonkotsuboy/github-upload-image-to-pr github-upload-image-to-pr
# 또는
npx skills add tonkotsuboy/github-upload-image-to-pr
도입 후에는 "이 스크린샷을 PR에 붙여줘"라고 요청하는 것만으로 이미지를 첨부해 줍니다.
gh가 2.99.0 이상이면 --attach를 사용하고, 그보다 오래된 gh나 GitHub Enterprise Server, 또는 쓰기 권한이 없는 경우에는 브라우저를 조작하여 업로드하는 방식으로 전환됩니다.
자신의 환경이 --attach에 대응한다면 CLAUDE.md만으로 충분하며, 대응하지 않는 환경도 다룰 필요가 있다면 스킬을 넣는 식으로 사용처를 구분하는 것이 좋을 것 같습니다.
Codex나 Antigravity CLI에서도 사용 가능
--attach는 gh 커맨드의 기능이므로, Claude Code 외의 코딩 에이전트에서도 동일하게 사용할 수 있습니다.
에이전트가 gh를 실행할 수 있는 환경이라면, Codex나 Antigravity CLI로도 변경 전후 스크린샷을 PR에 첨부하도록 할 수 있습니다. 규칙을 작성하는 파일은 사용하는 에이전트에 맞춰 변경해 주십시오.
Codex나 Antigravity CLI의 경우, AGENTS.md에 본 기사의 CLAUDE.md와 동일한 내용을 작성해 두면 작동합니다.
주의점
- 대상 리포지토리(repository)에 대한 쓰기 권한이 필요합니다.
- GitHub.com 및 GitHub Enterprise Cloud에서 사용할 수 있습니다. GitHub Enterprise Server에서는 사용할 수 없습니다.
- 첨부할 수 있는 것은 이미지와 비디오입니다. 비디오는 플레이어 형태로 표시되며, alt 텍스트를 추가할 수 없습니다.
요약
gh의 --attach 기능을 사용하면 로컬 스크린샷을 명령어만으로 PR(Pull Request)에 첨부할 수 있게 되었습니다.
CLAUDE.md에 PR 생성 규칙을 작성해 두면, Claude Code가 변경 전후 스크린샷이 포함된 상태로 PR을 만들어 줍니다.
Codex나 Antigravity CLI에서도 AGENTS.md에 동일한 규칙을 작성하면 사용할 수 있습니다.
UI 변경 사항을 코딩 에이전트(coding agent)에게 맡기는 경우가 많은 분들에게는 설정해 두면 리뷰가 편리할 것입니다.
Discussion
