Claude Code Skill로 커밋 메시지 추천 자동화

들어가며

Claude Code를 쓰다 보면 생각보다 자주 반복되는 작업이 있습니다. 그중 하나가 바로 커밋 메시지 정리였습니다. 변경 내용을 보고 Conventional Commits 형식으로 적당한 메시지를 떠올리는 일은 어렵지는 않지만, 맥락을 한 번 더 읽고 정리해야 해서 은근히 흐름을 끊었습니다.

그래서 저는 이 작업을 아예 Claude Code Skill로 분리해 봤습니다. 이번 글은 제가 만든 recommend-commit-message 스킬의 구조를 기준으로, 어떤 문제를 해결하려고 했는지, 어떻게 규칙을 설계했는지, 실제로 어떤 식으로 활용했는지를 공유하는 기록입니다.

참고로 이 스킬은 GitHub에도 공개해뒀습니다. 글을 읽다가 직접 구조를 보고 싶다면 recommend-commit-message Skill 저장소에서 바로 확인할 수 있고, 자신의 프로젝트에 맞게 가져가서 수정해 써도 됩니다.

왜 굳이 Skill로 분리했나

일반 프롬프트로도 “커밋 메시지 추천해줘”는 충분히 할 수 있습니다. 다만 매번 원하는 출력 형식, 언어, 분석 순서, 경고 조건을 다시 설명해야 했고, 결과도 호출할 때마다 조금씩 흔들렸습니다.

반면 Skill로 만들면 반복 규칙을 문서에 고정할 수 있습니다. 한 번 잘 정의해 두면, 그다음부터는 사람이 해야 할 일이 “지금 이 상황에 맞게 호출하기” 정도로 줄어듭니다.

프롬프트로만 처리

매번 조건을 다시 설명해야 하고, 출력 포맷이나 분석 관점이 호출마다 달라질 수 있습니다. 결국 자주 쓰는 작업일수록 손이 더 갑니다.

Skill로 분리

분석 순서, 언어 규칙, 경고 조건, 출력 템플릿을 문서로 고정할 수 있습니다. 호출은 짧아지고 결과는 더 일관됩니다.

제가 만든 스킬의 핵심 구조

이번에 만든 스킬은 staged git 변경사항을 읽고, Conventional Commits 형식의 후보를 2~3개 추천하는 역할에 집중합니다. 중요한 점은 커밋을 직접 실행하지 않는다는 점입니다. 판단은 도와주되 최종 선택은 사람이 하도록 경계를 분명히 뒀습니다.

문서를 보면 단순히 “메시지 추천”만 적은 것이 아니라, 분석 대상과 순서가 꽤 세밀하게 정의되어 있습니다. 저는 이 부분이 Skill의 핵심이라고 생각합니다. 결국 성능 차이는 모델 자체보다도 어떤 문맥을 어떻게 읽히게 설계했는가에서 많이 갈립니다.

1. 출력 언어를 인자로 제어

이 스킬은 $ARGUMENTS로 출력 언어를 바꿀 수 있게 만들었습니다. 기본값은 한국어지만, 영어, 일본어, 중국어, 스페인어, 포르투갈어, 프랑스어, 독일어까지 지정할 수 있게 해뒀습니다.

여기서 재미있는 포인트는 type, scope, Conventional Commits 키워드는 항상 영어로 유지하고, 제목과 본문만 선택한 언어로 쓰도록 분리한 점입니다. 이렇게 해두면 팀 규칙과 읽기 편의성을 동시에 챙길 수 있습니다.

Skill-Recomend-Commit-Message/SKILL.md Markdown

The output language is controlled by $ARGUMENTS:
- No argument or KOR → Korean
- ENG → English
- JPN → Japanese
...

Rule: type, scope, and Conventional Commits keywords
are always in English regardless of language setting.

2. staged/unstaged 상태를 분리해서 다룸

문서의 첫 단계는 git diff --staged 확인입니다. staged 변경사항이 없으면 바로 중단하고, 먼저 git add를 하라고 안내합니다. 반대로 unstaged 변경사항은 git diff로 따로 확인하되, 작업을 멈추지는 않고 마지막에 경고만 붙입니다.

이 구분이 꽤 실용적이었습니다. 실제 커밋 후보를 추천해야 하는 대상은 staged 변경사항이기 때문에 기준은 분명하게 잡고, 동시에 작업 디렉터리에 남아 있는 변경사항도 놓치지 않게 만든 구조입니다.

3. 변경 파일만 보는 게 아니라 프로젝트 맥락까지 읽음

이 스킬에서 제가 특히 신경 쓴 부분은 변경 diff만 읽고 메시지를 짓지 않게 한 것입니다. 프로젝트 스택과 최근 커밋 히스토리도 같이 보도록 넣었습니다.

package.json, build.gradle, Cargo.toml, go.mod, pyproject.toml 같은 파일을 확인해서 기술 스택 힌트를 얻고, git log로 최근 메시지 패턴도 읽습니다. 즉, 지금 바뀐 코드만 보고 추천하는 게 아니라 이 저장소가 원래 어떤 식으로 커밋해왔는지까지 반영하려는 설계입니다.

Step 1 · staged 확인 git diff --staged 결과가 없으면 추천을 중단하고 먼저 stage 하라고 안내합니다.

↓

Step 2 · unstaged 확인 아직 stage 하지 않은 변경이 있으면 마지막에 경고를 붙여 사용자 판단을 돕습니다.

↓

Step 3 · 프로젝트 맥락 분석 빌드 파일, 모듈 구조, 최근 커밋 히스토리를 읽어 scope와 표현 방식을 맞춥니다.

↓

Step 4 · 후보 생성 단일 목적이면 2~3개 후보를, 여러 목적이면 커밋 분리를 제안하며 각각의 후보를 생성합니다.

문서 설계에서 좋았던 부분

이 스킬은 단순히 예시 몇 줄을 적은 문서가 아니라, 모델이 흔들릴 만한 지점을 미리 규칙으로 고정해 둔 문서에 가깝습니다. 특히 좋았던 건 scope 추천 로직, type 선택 가이드, 출력 템플릿을 각각 별도로 정의한 점입니다.

이렇게 분리해 두면 모델이 어느 한 부분에서 애매해져도 다른 규칙이 보정 역할을 해줍니다. 사람이 읽어도 “왜 이런 결과가 나왔는지”를 역추적할 수 있어서, 나중에 스킬을 다듬기도 훨씬 편했습니다.

scope 추천 로직을 단계적으로 정의

문서에는 scope를 정할 때 우선순위가 있습니다. 먼저 Git 히스토리에서 기존 패턴을 확인하고, Android 멀티 모듈이면 모듈 폴더명을 쓰고, 그게 아니면 레이어나 최상위 디렉터리 이름으로 fallback 하도록 했습니다.

이 방식의 장점은 저장소마다 다른 네이밍 문화에 적응할 수 있다는 점입니다. 무조건 파일명만 보고 scope를 짓는 것보다 훨씬 현실적인 결과가 나왔습니다.

1우선

Git 히스토리 우선

이미 팀이나 개인이 쓰고 있는 scope 패턴이 있다면 그 규칙을 먼저 따르게 했습니다. 새 규칙을 발명하기보다 기존 흐름에 붙는 쪽이 안정적입니다.

2구조

모듈/레이어 기반 추론

Android 멀티 모듈이나 Clean Architecture 구조라면 폴더와 파일명에서 feature, layer, service 이름을 읽어 scope 후보로 사용합니다.

3예외

애매하면 생략 가능

scope가 불명확한 프로젝트 전체 변경이라면 억지로 넣지 않도록 했습니다. 없애는 것도 규칙이라는 점이 중요합니다.

type 선택도 파일 경로 패턴으로 힌트를 줌

또 하나 유용했던 부분은 path-based type hint입니다. 테스트 파일이면 test, 문서 파일이면 docs, 워크플로 파일이면 ci처럼 경로 패턴에 따라 기본 힌트를 제공했습니다.

물론 최종 판단은 diff 내용을 봐야 하지만, 이런 힌트가 있으면 모델이 너무 넓은 선택지에서 헤매지 않습니다. 특히 Android 프로젝트처럼 파일 종류가 다양한 경우 체감이 꽤 있었습니다.

판단 기준	문서에서 준 힌트	의도
테스트 파일	*test*, *Spec*, *Test.kt → test	변경 목적을 빠르게 좁히기 위해
문서 파일	*.md, docs/** → docs	코드 수정과 문서 수정을 분리하기 위해
빌드 파일	package.json, *.gradle* → build, chore	의존성/설정 변경을 명확히 드러내기 위해
UI 관련 파일	screens/**, components/** → feat, design	기능 추가와 시각 수정의 경계를 잡기 위해

실제로 써보니 좋았던 점

가장 먼저 느낀 장점은 출력 품질보다 일관성이었습니다. 커밋 메시지는 매번 기막히게 창의적일 필요가 없고, 오히려 저장소 전체에서 톤이 맞는 편이 더 중요합니다. 이 스킬은 바로 그 부분을 잘 해결해줬습니다.

또 하나는 커밋을 나눠야 할 때 도움이 됐다는 점입니다. 문서에 “독립된 목적이 2개 이상이면 split commit을 추천하라”는 규칙을 넣어두니, 단순한 메시지 추천기를 넘어 작업 단위 점검 도구처럼 쓸 수 있었습니다.

Skill를 잘 만들어두면 모델이 더 똑똑해진다기보다, 내가 원하는 작업 기준이 더 분명해집니다. 실제로 체감되는 차이는 대부분 여기서 나옵니다.

이런 식으로 커스텀하는 게 의미 있었던 이유

제가 이번 경험에서 가장 크게 느낀 건 Claude Code Skill의 가치는 “거대한 자동화”보다 “자주 반복되는 작고 애매한 판단을 정리하는 것”에 있다는 점이었습니다. 커밋 메시지 추천은 딱 그런 종류의 작업이었습니다.

개발하면서 반복되지만 매번 설명하기 귀찮은 규칙, 프로젝트마다 조금씩 다른 판단 기준, 팀 혹은 개인의 작업 스타일 같은 것들은 일반 프롬프트보다 Skill 문서에 더 잘 어울립니다. 한번 구조를 잡아두면 이후에는 훨씬 가볍게 재사용할 수 있습니다.

만약 비슷한 고민이 있었다면 글만 읽고 끝내기보다 실제 스킬 문서를 열어보는 편이 더 도움이 됩니다. 제가 사용한 원본은 GitHub의 recommend-commit-message 디렉토리에 올려뒀고, 그대로 참고해도 되고 팀 규칙에 맞게 scope나 type 힌트만 조금 바꿔서 써도 충분합니다.

제가 다음에도 Skill로 빼고 싶은 작업

이번에 해보니 비슷한 결의 작업은 계속 Skill로 분리할 수 있겠다는 확신이 생겼습니다. 예를 들면 PR 설명 생성, 리뷰 체크리스트 정리, 릴리즈 노트 초안 생성 같은 것들이 비슷한 패턴입니다.

공통점은 하나입니다. 정답이 하나로 고정되진 않지만, 좋은 결과를 만드는 판단 기준은 분명히 존재하는 작업이라는 점입니다.

정리하며

이번 recommend-commit-message 스킬은 복잡한 자동화라기보다, 제가 실제로 반복하던 판단 과정을 문서로 외부화한 결과물에 가깝습니다. staged 변경 확인, unstaged 경고, 프로젝트 스택 분석, 히스토리 기반 scope 추천, split commit 제안까지 흐름을 정의해두니 호출이 훨씬 가벼워졌습니다.

Claude Code Skill를 커스텀하게 써본 경험을 한 줄로 정리하면 이렇습니다. 모델에게 일을 잘 시키는 방법은 더 길게 말하는 게 아니라, 반복되는 판단 기준을 구조로 고정하는 것이었습니다.

Summary

• 이번 스킬의 목적은 staged 변경사항을 읽고 Conventional Commits 형식의 커밋 메시지를 안정적으로 추천하는 것이었습니다.
• 핵심 설계 포인트는 출력 언어 제어, staged/unstaged 분리, 프로젝트 스택과 Git 히스토리 분석이었습니다.
• 좋았던 점은 결과가 더 화려해진 것보다, 커밋 메시지 품질과 톤이 일관되게 유지됐다는 점입니다.
• Skill의 진짜 장점은 자주 반복되지만 매번 설명하기 귀찮은 판단 기준을 문서로 고정할 수 있다는 데 있습니다.
• 결론은 Claude Code Skill를 커스텀할수록 모델 활용 경험이 좋아진다기보다, 내가 원하는 작업 방식이 더 선명해진다는 것입니다.