🎬 Claude Code가 코드베이스 스냅샷 남기게 하기 – gh + Claude Skills로 이슈 단위 코드 관리한 이야기

소개

코딩 에이전트를 본격적으로 사용하면서 생산성은 확실히 올라갔지만, 동시에 새로운 문제가 하나 생겼다 😅
에이전트가 코드를 한 번에 많이, 그리고 꽤 과감하게 수정하다 보니 예상치 못한 에러가 생겼을 때,

“이 상태에서 도대체 어디까지가 정상 코드였지…?”

라는 상황이 자주 발생했다.

특히 작업이 길어질수록 이전 상태로 안전하게 되돌아가기 어렵다는 점이 가장 큰 스트레스였다. 이 문제를 해결하지 않으면 코딩 에이전트를 계속 쓰기 힘들겠다는 생각이 들었다.

진행 방법

Claude Code를 쓰다 보니 한 가지 떠오른 점이 있었다.

• Claude Code는 이미 gh(GitHub CLI) 커맨드를 알고 있다

• 그렇다면 코드를 수정하는 모든 흐름을 GitHub 기준으로 강제하면 어떨까?

그래서 생각한 전략은 단순했다.

👉 GitHub 이슈 = 작업 단위
👉 이슈마다 브랜치 생성
👉 할 일 단위로 커밋 = 코드 스냅샷(빵가루)

이걸 Claude Code가 Claude Skill을 써서 직접 수행하게 만들기로 했다.

---
name: resolve-issue

description: fetch the information about user requested github issue number and process the issue based on the issue's content

---

# 깃허브 이슈 해결하기
너는 지금부터 깃허브 이슈를 해결하는 엘리트 소프트웨어 개발자야. 아규먼트로 깃허브 이슈 고유 숫자를 넘겨주면 이 숫자에 해당되는 Issue를 해결하는 작업을 해줘

## 작업 순서
- **이슈 불러오기**: 깃허브 CLI를 사용해서 이슈를 불러와줘. 제목, 본문, 레이블을 확인하고, 이슈를 정확히 이해해줘.
- **브랜치 세팅하기**: 이슈를 해결할 브랜치를 세팅해줘. dev 브랜치에서 issue-$ISSUE_NUMBER 형태로 새로운 브랜치를 생성 후 작업 진행해줘 (ex: issue-12)
- **코드베이스 분석하기**: 배정된 이슈를 해결하기 위해 알고 있어야 하는 정보를 분석하기 위해 코드 베이스를 분석하고 컨텍스트를 확보해줘. 프로젝트의 방향성을 알기 위해 project_docs/PRD.md도 꼭 읽어야 해. 최대 10개의 서브에이전트를 필요한 만큼 생성해서 독립적으로 코드베이스를 리서치 해줘
- **이슈 해결 계획 세우기**: 취합한 정보를 기반으로 어떻게 이슈를 해결할지 계획을 세워줘. 계획을 세우고 나면 나한테 먼저 확인을 받아야 돼. 계획을 바로 실행하지 말고, 나와 상의하면서 수정 후 실행해야 해
- **이슈 해결하기**: 계획 수립과 수정이 완료되었으면, 차례대로 계획을 실행해줘. 하나의 서브에이전트를 생성해서 작업해줘. 계획의 체크리스트가 하나씩 완료될 때마다 변경 사항들을 commit 메세지와 함께 브랜치에 commit해줘.
- **테스트 작성하기**: 작업한 이슈들을 검증할 수 있는 유닛 테스트를 작성해줘. 엣지 케이스들을 포함해서 80% 이상의 커버리지를 확보할 수 있는 테스트를 작성해줘. 파일별로 독립적인 에이전트를 생성해서 병렬로 작업해줘
- **검증하기**: 테스트, 린트, 빌드를 각각 독립적인 서브에이전트로 실행하고, 문제있는 이슈를 해결해줘
- **PR 생성하기**: 작업관련 된 내용이 포함된 풀 리퀘스트를 작성해줘. PR은 항상 새로운 브랜치를 dev브랜치로 merge 해야돼.

이 Claude Skills가 하는 내용을 요약해보자면,

• gh CLI로 이슈 내용을 직접 읽고 이해하기

• dev 브랜치에서 issue-{번호} 브랜치 자동 생성

• 코드 수정 전에 PRD 문서까지 읽고 맥락 파악

• 작업을 바로 하지 않고, 해결 계획을 먼저 나에게 공유

• 작업은 투두 리스트 기반으로 진행

• ✅ 투두 하나가 끝날 때마다 반드시 커밋 생성

이렇게 해서 Claude Code의 모든 행동이 Git 히스토리에 빵가루처럼 남도록 만들었다.

🧩 실제 작업 흐름

실제 작업은 이런 느낌으로 흘러갔다.

1. 이전 사례글 방식으로 프로젝트 관련 GitHub에 이슈 내용 작성 후 Github 이슈 생성

2. Claude Code에게 이슈 번호 전달

3. Claude Code가:

   • 이슈 전용 브랜치 생성

   • 할 일 목록(todo list) 정리

4. 투두 하나 완료 → 즉시 커밋

5. 다음 투두 진행 → 또 커밋

6. AI가 수정/추가한 코드를 테스트 하고, 문제 없다 판단 되면 main이나 dev 브랜치에 코드 통합

ALT

한국 TV 채널 홈페이지 스크린샷

결과와 배운 점

✅ 코드베이스에 문제가 생겨도 전혀 불안하지 않다

가장 큰 변화는 심리적인 안정감이었다. AI와 함께 코딩하다 보면, AI가 좀 과감하게 코드를 수정하여 에러가 발생하는 경우가 종종 생긴다.

이 스킬을 쓰고 나서 코딩 에이전트가 아무리 과감하게 수정해도,

• 현재 브랜치에서 문제가 생기면?

  • 👉 이전 커밋으로 바로 되돌리기

• 브랜치 자체에서 이슈 트래킹이 되지 않는다면?

  • 👉 dev 브랜치에서 다시 새 브랜치 생성

🔄 코딩 에이전트와 Git의 궁합은 생각보다 훨씬 좋다

이 방식을 쓰면서 느낀 건,

• 코딩 에이전트는 작업 속도를 책임지고

• Git / GitHub은 기억과 복구를 책임진다는 점이었다.

특히 이슈 단위 브랜치 + 투두 단위 커밋은 코딩 에이전트의 단점을 정확히 보완해줬다.

💬 이 방식을 추천하고 싶은 사람

• 코딩 에이전트를 쓰다가 코드가 자주 망가지는 사람

• "어디서부터 잘못됐는지" 추적이 어려운 사람

• AI에게 더 많은 권한을 주고 싶지만 불안한 사람

도움 받은 책

• 요즘 바이브코딩: 클로드 코드 완벽 가이드