10월 4일 게시된 Claude Code 공식 문서의 스킬 안내 페이지(Extend Claude with skills)에는 커밋 전 검증에 관한 설명이 담겨 있습니다. 세션을 시작할 때 verify 또는 simplify라는 이름의 스킬이 있으면, Claude Code의 커밋 지침이 Claude에게 매번 커밋 직전에 그 스킬을 실행하라고 안내합니다. 이 동작에는 Claude Code v2.1.286 이상이 필요합니다.
커밋 직전에 스킬을 부르는 안내
이번 설명의 핵심은 스킬의 이름입니다. 스킬 이름이 verify나 simplify이면 Claude는 커밋하기 직전에 그 스킬을 먼저 실행합니다. 개발자가 따로 명령을 내리지 않아도 커밋 흐름 안에 검사 단계가 들어갑니다.
예외도 있습니다. 문서나 테스트만 바꾼 변경에서는 이 실행을 건너뜁니다. 검사에 드는 시간을 코드 변경에 집중하려는 설계로 읽힙니다.
조직의 입장에서 이 설명은 커밋 전 검사를 사람의 기억에 맡기지 않고 저장소 설정으로 정할 수 있다는 뜻입니다. 다만 이름이 verify라고 해서 모든 스킬이 이 조건을 만족하는 것은 아닙니다.
어떤 스킬이 조건에 해당하는가
문서는 스킬을 어디에서 불러왔는지를 기준으로 삼습니다. 엔터프라이즈, 개인, 프로젝트, 추가 디렉터리 위치에서 불러온 스킬이 조건에 해당합니다. .claude/commands/ 폴더에 같은 이름의 파일을 둔 경우도 해당합니다.
반대로 Claude Code에 기본으로 들어 있는 /verify와 /simplify는 이 안내를 켜지 않습니다. 플러그인으로 설치한 스킬도 마찬가지입니다. claude.ai 계정에서 가져온 스킬 역시 조건에 해당하지 않습니다. 이름이 같아도 출처가 다르면 커밋 전 실행이 일어나지 않습니다.
이 구분은 관리 책임과 이어집니다. 엔터프라이즈 위치는 조직이 정한 검사를 모든 구성원에게 적용하는 경로가 될 수 있습니다. 프로젝트 위치는 저장소마다 다른 검사를 둘 때 알맞습니다. 개인 위치에 둔 스킬은 개발자 한 사람의 습관에 머뭅니다. 스킬을 어느 위치에 둘지 정하는 일은 곧 누가 검사 기준을 관리할지 정하는 일입니다.
안내가 빠지는 경우
스킬이 올바른 위치에 있어도 안내가 빠지는 경우가 있습니다. Claude가 스킬을 호출하지 못하도록 막아 두면 커밋 전 지침도 전달되지 않습니다. 문서는 disable-model-invocation: true 설정을 예로 듭니다.
includeGitInstructions 설정을 끄는 경우도 있습니다. 이 설정을 끄면 커밋 전 검증 안내가 사라집니다. 커밋과 PR에 관한 다른 기본 지침도 함께 사라집니다. 자체 커밋 규칙을 따로 운영하려고 이 설정을 끈 조직이라면, 커밋 전 검사도 함께 빠진다는 점을 알아 두어야 합니다.
두 설정 모두 의도와 다르게 검사를 꺼 버릴 수 있습니다. 설정 파일을 검토할 때 이 두 항목을 함께 살펴보는 것이 좋습니다.
/verify가 남기는 기록과 저장소 루트
기본 /verify는 사용자가 직접 부를 때만 실행됩니다. 오래 걸리는 검사가 언제 시간과 토큰을 사용할지 사용자가 정할 수 있다는 뜻입니다.
/verify에 기록된 절차가 없으면, 이 스킬은 효과가 있었던 방법을 .claude/skills/verify/SKILL.md 파일에 남깁니다. 저장소 루트에 생긴 이 파일은 기본 /verify를 대신합니다. 이 기능에는 Claude Code v2.1.200 이상이 필요합니다.
여기서 두 동작이 이어집니다. 저장소 루트에 기록된 절차는 프로젝트 스킬로 취급됩니다. 그래서 이 파일이 생기면 커밋 직전 실행 조건도 충족됩니다. 처음에는 사용자가 부를 때만 실행되던 검사가, 기록이 남은 뒤에는 커밋마다 실행되는 검사로 바뀌는 셈입니다.
이 변화는 비용과 연결됩니다. 커밋이 잦은 팀이라면 검사 시간과 토큰 사용량이 함께 늘어납니다. 기록된 파일을 저장소에 함께 올릴지, 그 안에 어떤 검사를 담을지 팀이 미리 정해 두어야 합니다.
도입 전에 확인할 것
먼저 버전을 맞춥니다. 커밋 전 실행에는 v2.1.286 이상이 필요합니다. /verify의 기록 기능에는 v2.1.200 이상이 필요합니다. 구성원마다 버전이 다르면 같은 저장소에서도 동작이 달라질 수 있습니다.
다음으로 스킬의 위치를 정합니다. 조직 전체의 기준은 엔터프라이즈 위치에, 저장소별 기준은 프로젝트 위치에 두는 식으로 관리 주체를 나눌 수 있습니다. 플러그인이나 claude.ai 계정의 스킬로는 커밋 전 실행이 일어나지 않는다는 점도 구성원에게 알려야 합니다.
설정 검토도 필요합니다. disable-model-invocation과 includeGitInstructions가 의도와 다르게 지정되어 있지 않은지 확인합니다. 커밋 규칙을 자체적으로 운영한다면 검사를 어디에서 대신할지도 정해 두어야 합니다.
마지막은 교육입니다. 개발자는 문서와 테스트 변경에서 검사가 생략된다는 점을 알아야 합니다. 기록된 /verify가 커밋 흐름에 들어간다는 점도 이해해야 합니다. 커밋 전에 무엇을 확인할지 스킬 파일에 글로 정리하는 역량이 이 기능을 사용하는 첫 단계입니다.

이정민






























