Claude Code 자동화 워크플로우, 설치만 하고 끝내지 않는 법: 5단계 검증 체크리스트

팀에 새 자동 빨래기를 들였다고 해보자. 버튼을 눌러 돌아가는 소리가 나면 다들 "됐네" 하고 자리를 뜬다. 그런데 빨래가 정말 깨끗하게 나왔는지, 물은 빠졌는지 누가 열어봤나? 자동화 워크플로우를 설치하고 나서 우리가 자주 빠뜨리는 게 딱 이 지점이다. 스크립트가 에러 없이 끝났다고 "작동한다"는 뜻은 아니다.

오늘 다룰 소스는 alirezarezvani/claude-code-github-workflow의 설치 문서(COMPLETE_SETUP.md)다. 이 저장소는 GitHub Actions와 Claude Code를 묶어, 계획을 이슈로 바꾸고 브랜치를 자동으로 만들고 품질 검사를 돌리는 과정을 한 번에 깔 수 있게 만든 복사-붙여넣기형 블루프린트다. 문서 표현대로면 "5분 안에" 설정이 끝나고, 워크플로우 8개, 슬래시 명령 8개, 자율 에이전트 4개가 함께 들어온다.

하지만 이 글이 붙잡는 건 설치가 아니다. 설치 다음에 무엇을 확인해야 깔린 게 진짜 도는지 — 그 검증 절차다. 문서가 따로 "Verification Steps"를 1~5단계로 정리해 둔 이유가 여기 있다.

설치 3줄과 검증은 다른 일이다

문서가 안내하는 빠른 시작은 3줄이다.

git clone https://github.com/alirezarezvani/claude-code-github-workflow.git .github-blueprint
cd .github-blueprint
./setup/wizard.sh

그리고 마지막 한 줄이 핵심이다.

./setup/validate.sh

wizard.sh가 깔아주는 일과 validate.sh가 확인하는 일은 성격이 다르다. 앞은 파일을 놓고 설정을 잡는 작업이고, 뒤는 그 결과가 실제로 동작 가능한 상태인지 점검하는 작업이다. 둘을 한 덩어리로 보면, 마법사가 통과했으니 됐다고 넘기기 쉽다. 여기서 막힌다.

오늘 남길 산출물: 5단계 검증 체크리스트

문서의 Verification Steps를 독자가 손에 쥘 체크리스트로 옮기면 이렇게 된다.

단계	확인 대상	무엇을 보는가
Step 1	파일 구조 검증	워크플로우·명령·설정 파일이 제 위치에 깔렸나
Step 2	부트스트랩 워크플로우	bootstrap.yml이 라벨·검증을 한 번 돌려놓았나
Step 3	이슈→브랜치 흐름	준비된 이슈에서 브랜치가 자동 생성되나
Step 4	품질 검사	lint·타입체크·테스트 게이트가 작동하나
Step 5	(연결 검증)	앞 단계들이 이어져 한 흐름으로 도나

이 표가 오늘 만드는 산출물이다. 설치가 끝났다면 이 다섯 칸을 위에서 아래로 한 번씩 통과시켜 보는 게 검증이다.

따라 하다 막히기 쉬운 지점을 짚자면, 대개 Step 1과 Step 3 사이다. 파일은 깔렸는데(Step 1 통과) 이슈에서 브랜치가 안 생긴다면(Step 3 실패), 중간의 부트스트랩이 라벨을 못 만들었을 가능성을 먼저 본다. 이 블루프린트는 status:ready 같은 라벨을 신호로 브랜치를 만드는 구조이기 때문이다. 라벨이 없으면 흐름이 거기서 끊긴다.

언제 이걸 안 깔아도 되나

도구를 권하기 전에 경계를 분명히 하자. 이 블루프린트는 GitHub Actions와 Claude Code, 그리고 GitHub Projects 보드를 전제로 한다. 혼자 메모처럼 쓰는 저장소거나, CI/CD 파이프라인이 필요 없는 단발성 프로젝트라면 8개 워크플로우는 과하다. 문서 스스로도 대상을 "솔로 개발자, 소규모 팀, 그리고 워크플로우를 정리하려는 기업"으로 적어 두었다. 즉 반복되는 개발 흐름이 있을 때 값이 나오는 도구다.

반대로, 계획→이슈→브랜치→PR→릴리스가 매번 손으로 반복되고 있다면 검증 체크리스트까지 갖춘 이 구성은 살펴볼 만하다.

다음에 확인할 기준 하나

설치했다면, 새 기능을 만들지 말고 위 표의 Step 3 한 칸만 먼저 통과시켜 보자. 이슈 하나에 준비 라벨을 달았을 때 브랜치가 자동으로 생기는지 — 그 한 장면이 도는지가 이 자동화가 살아 있는지 가르는 가장 빠른 신호다. 정확한 단계 설명과 명령은 원문 COMPLETE_SETUP.md에서 직접 확인하면 된다.

용어 알아가기

• GitHub Actions: 저장소에서 정해둔 작업(빌드·테스트·배포 등)을 자동으로 돌려주는 GitHub의 자동화 기능.
• 부트스트랩(bootstrap): 자동화를 처음 한 번 돌려 라벨 생성 등 기본 환경을 잡아두는 초기 설정 단계.
• 품질 게이트(Quality Gate): lint·타입체크·테스트 같은 검사를 통과해야만 다음으로 넘어가게 막아두는 관문.
• 슬래시 명령(Slash Command): /create-pr처럼 빗금으로 시작해 반복 작업을 한 번에 실행하는 명령어.

---

🐦 X에서 더 빠르게: @baegseungh7061
📚 이 시리즈 더 보기: Code 빌드
💌 새 글 알림: X 팔로우 또는 블로그 RSS 구독