Claude Code에 나만의 커밋·PR 커맨드 만들어 쓴 이야기

도입

커밋 메시지 쓰는 게 매번 귀찮았습니다. 브랜치명에 티켓 번호가 있는지 확인하고, 어떤 접두사를 붙일지 고민하고, 변경 내용을 한 줄로 요약하는 것까지 - 사소하지만 반복되는 작업이었습니다. PR도 마찬가지였습니다. diff를 보면서 리뷰 포인트를 잡고, 라벨을 고르고, 본문 템플릿을 채우는 과정이 매번 똑같이 반복됐습니다.

그래서 Claude Code의 커스텀 커맨드 기능을 이용해서 "커밋"과 "PR 생성" 두 가지를 직접 만들어 쓰고 있습니다. Claude API를 따로 호출하는 파이프라인이 아니라, Claude Code 안에서 마크다운 파일 하나로 규칙을 정의해두면 그 규칙대로 동작하는 방식입니다.

커밋 커맨드와 PR 생성 커맨드의 "제안 → 승인 → 실행" 흐름

핵심 개념: 커맨드 파일 하나가 곧 워크플로 정의

Claude Code의 커스텀 커맨드는 마크다운 파일에 규칙과 실행 순서를 적어두면, 그 문서를 그대로 따라 동작합니다. 별도 스크립트나 API 키 설정 없이, 팀이나 개인의 컨벤션을 문서화하는 감각으로 만들 수 있다는 게 가장 큰 장점이었습니다.

실전 구현: 커밋 커맨드

가장 먼저 만든 건 커밋 메시지를 제안해주는 커맨드입니다. 핵심 규칙은 이렇게 정했습니다.

• 승인 없이는 절대 git commit을 실행하지 않는다
• 커밋 메시지는 한글로 작성한다
• Co-Authored-By 줄은 넣지 않는다
• 브랜치명에 티켓 ID가 있으면(feature/ALTERAI-133 같은 형식) [ALTERAI-133]을 접두사로 붙이고, conventional commit 타입(feat:, fix:)은 쓰지 않는다. 티켓 ID가 없는 브랜치(develop, release/v4.11.0 등)에서만 conventional commit 타입을 붙인다

실행 흐름은 git status, git diff, git log 등을 병렬로 확인한 뒤 브랜치명에서 티켓 ID를 정규식으로 뽑아내고, diff 내용을 바탕으로 50자 이내 커밋 메시지 초안을 제안합니다. 제가 승인하면 그제야 git add(항상 파일을 명시하고 git add -A는 금지)와 git commit을 실행합니다.

실전 구현: PR 생성 커맨드

PR 생성 커맨드는 조금 더 단계가 많습니다.

1. 현재 브랜치와 베이스 브랜치(origin/develop 우선, 없으면 origin/main)를 파악
2. 변경된 파일 목록을 보고 CLAUDE.md에 반영할 항목이 있는지 확인 (Room DB 마이그레이션, Navigation 구조, 모듈 구성 등)
3. 별도의 리뷰 스킬을 부르지 않고, 커맨드 안에서 직접 diff를 읽으며 명백한 버그·삭제된 가드·호출부 영향만 체크
4. 리뷰 결과를 브리핑하고, 수정할지 진행할지 먼저 묻는다
5. 브랜치명 접두사(fix/, feature/, refactor/)로 라벨 후보를 정하고, PR 제목·본문·라벨을 제안
6. 승인 후에만 git push와 gh pr create를 실행

참고: PR 커맨드 안에서 코드 리뷰를 별도 스킬로 부르지 않고 인라인으로 처리하는 데는 지나온 판단 과정이 있습니다. 한때 코드 리뷰를 서브에이전트로 분리해서 쓰다가 다시 지금 방식으로 돌아온 건데, 이 판단 과정은 서브에이전트 운용 이야기와 함께 별도 글로 다룰 예정입니다. 발행되면 이 자리에 링크를 연결하겠습니다.

왜 매번 사용자 승인을 넣었나

두 커맨드 모두 "제안 → 승인 → 실행" 구조를 고정으로 넣었습니다. 다만 두 승인의 목적은 조금 다릅니다.

• 커밋 승인은 메시지가 규격대로 나왔는지 확인하는 용도입니다. 티켓 ID 접두사가 맞는지, conventional commit 타입을 붙여야 하는 브랜치인지 아닌지, 불필요한 줄이 섞이지 않았는지를 커밋되기 전에 한 번 더 보는 것입니다.
• PR 승인은 조금 더 실질적인 결정입니다. 인라인 리뷰에서 나온 이슈를 PR을 올리기 전에 고칠지, 아니면 일단 그대로 올리고 리뷰어에게 넘길지를 제가 직접 판단하기 위한 단계입니다.

실전에서 겪은 점: 커맨드를 매번 명시해서 불러야 했다

처음에는 그냥 "커밋해줘", "PR 올려줘"라고만 말해도 이 커맨드들이 알아서 쓰일 거라 생각했습니다. 실제로는 Claude Code가 커스텀 커맨드를 타지 않고 자체 판단으로 커밋을 진행해버리는 경우가 있었고, 그럴 때 티켓 ID 접두사가 빠지는 등 규칙에서 벗어난 결과가 나왔습니다. 메모리에 관련 규칙을 몇 번이나 저장해뒀는데도 매번 지켜지는 건 아니었습니다.

그래서 지금은 "커밋 스킬 이용해서 커밋해줘", "PR 스킬 이용해서 PR 생성해줘"처럼 커맨드 이름을 직접 언급해서 요청하는 방식으로 쓰고 있습니다. 번거롭긴 하지만, 규칙이 확실히 적용되는 걸 우선하다 보니 정착된 습관입니다.

마무리

커밋·PR 커맨드를 만든 이유는 결국 반복 작업을 줄이면서도 최종 판단은 계속 제가 쥐고 있기 위해서였습니다. 다만 커맨드를 만들어뒀다고 항상 그대로 쓰이는 건 아니라서, 규칙을 문서로 정의하는 것과 그 규칙이 매번 실행되도록 만드는 것은 별개의 문제라는 걸 체감했습니다.

---

[핵심요약] Claude Code 커스텀 커맨드로 커밋 메시지 제안부터 PR 리뷰·생성까지, 매번 승인을 거치는 안전한 자동화 흐름을 만들었지만 커맨드를 명시적으로 불러야 규칙이 지켜졌던 경험까지 정리한 이야기