슬래시 명령어: 무의미한 커밋은 이제 그만

Source: Dev.to

제가 Claude Code에서 가장 많이 사용하는 기능 중 하나는 슬래시 명령어입니다.
모든 개발자가 갖추어야 할 명령어는 /commit입니다. 이 명령어는 많은 개발자들이 공유하는 습관—심지어 경험 많은 개발자들조차도—을 정리해 줍니다. /commit은 커밋 입력창을 명확하게 만들고, 팀 전체가 일관된 방식으로 커밋을 작성하게 됩니다.

저는 언제나 커밋 메시지에 신경을 써 왔습니다. 하지만 신경을 쓰는 개발자라도 피곤한 금요일이나 대규모 리팩터링 중에 "fixes" 같은 간단한 메시지나 일반적인 "update"가 레포에 섞여 들어갈 수 있습니다. 이렇게 되면 저장소는 몇 달이 지나도 아무도 해독할 수 없는 잡음 층을 쌓아가게 됩니다.

슬래시 명령어란?

슬래시 명령어는 Claude Code에만 국한된 것이 아닙니다. OpenCode, Codex CLI, Aider, Continue와 같은 도구들도 자체 명령어를 연결할 수 있게 해줍니다. 형식과 트리거는 다르지만 아이디어는 동일합니다: 짧은 키 입력 하나로 한 번 작성한 긴 프롬프트를 실행합니다.

Claude Code 구현

Claude Code에서는 슬래시 명령어가 단순히 Markdown 파일입니다:

파일이 존재하면 /가 바로 가기로 작동합니다. 파일의 front‑matter에 description이 들어 있고, 본문은 명령을 호출했을 때 에이전트가 읽는 프롬프트입니다.

DSL도, SDK도, 플러그인 매니페스트도 없습니다.
Markdown 파일 입력 → 슬래시 명령어 출력.

커밋 문제

좋은 에이전트를 루프에 두어도, 단순히 "commit my changes" 를 실행하면 어느 정도는 통과하지만 완벽하지는 않습니다:

• 에이전트가 하나의 타입만 선택하고, 작업 가능한 제목 줄을 작성한 뒤, 관련 없는 변경 사항들을 하나의 커밋에 묶어 버립니다.
• 아무것도 하지 않는 것보다는 낫지만, 더 나은 방법이 있습니다.

원하는 워크플로우

1. 변경 사항을 읽고 도메인별로 그룹화합니다.
2. 각 그룹에 대해 괜찮은 메시지를 작성하고, Conventional Commits 사양을 따릅니다.
3. 커밋하면 안 되는 파일(예: 생성된 파일, lockfile 등)은 건너뜁니다.

/commit – 나의 슬래시 명령

아래는 커밋을 깔끔하고 일관되게 유지하기 위해 만든 슬래시 명령입니다.

---
description: "모든 변경 사항을 분석하고 논리적 그룹으로 커밋합니다."
---

# 커밋

이 파일을 ~/.claude/commands/commit.md(또는 프로젝트별 위치) 에 두고 /commit 으로 호출하세요.

실행 시 명령은 다음을 수행합니다:

1. 작업 트리에서 변경 사항을 스캔합니다.
2. 논리적 도메인(예: feat, fix, docs) 별로 수정 내용을 그룹화합니다.
3. 각 그룹에 대해 Conventional Commit 메시지를 생성합니다.
4. 해당 파일들을 git add 로 추가하고 커밋을 생성합니다.

프롬프트 본문에 추가 로직(예: 사용자 정의 무시 패턴, 인터랙티브 확인, CI 파이프라인 연동 등)을 자유롭게 확장하세요.

단계 1: 변경 사항 조사

• bin/commit-survey를 실행하여 파일 목록과 분류를 확인합니다.
• 변경 사항에 대한 추가 맥락이 필요하면 주요 파일의 diff를 읽어보세요.

Step 2: 변경 사항 그룹화

--- classified --- 출력을 시작점으로 사용하고, 논리적인 커밋으로 다듬으세요.

그룹화 전략

• 도메인/기능별 – 예: 인증 관련 변경을 모두 함께.
• 계층별 – 예: 모델 테스트, 컨트롤러 테스트.
• 유형별 – 예: 모든 설정 변경, 모든 의존성 업데이트.

참고: [skip]에 나열된 파일은 커밋해서는 안 됩니다. 파일에 대해 확신이 서지 않으면 스킵하세요.

Step 3 – 각 그룹 커밋

각 그룹마다 stage + commit을 한 번에 수행합니다:

git add  && git commit -m ""

커밋 순서는 가장 독립적인 것부터 가장 의존적인 것까지:

1. Config / tooling 변경을 먼저
2. 소스‑코드 변경
3. 테스트 변경
4. 생성된 파일을 마지막에

세 단계로 구성된 엔진

bin/commit-survey

Step 1 은 파일을 분류하는 스크립트를 호출합니다. 에이전트에게 git status, git diff 를 실행하고 그 출력을 파싱하도록 요청하는 대신(매 실행마다 토큰을 소모함), 짧은 Ruby 스크립트가 한 번만 분류를 수행하고 예측 가능한 결과를 반환합니다.

Ruby 헬퍼 (≈ 22 줄)

SKIP_PATTERNS = %w[.env credentials master.key tasks.md notes.txt scratch .claude/]

BUCKETS = {
  "skip"   => ->(path) { SKIP_PATTERNS.any? { |pat| path.include?(pat) } },
  "test"   => ->(path) { path.start_with?("test/") },
  "db"     => ->(path) { path.start_with?("db/") },
  "config" => ->(path) { path.start_with?("config/", "Gemfile", ".rubocop", "Procfile", "Rakefile") },
  "docs"   => ->(path) { path.start_with?("docs/", "README") || path.end_with?(".md") },
  "app"    => ->(_)     { true }
}

paths   = `git status --porcelain`.lines(chomp: true).map { |l| l[3..] }
grouped = BUCKETS.keys.to_h { |b| [b, []] }

paths.each do |path|
  bucket = BUCKETS.find { |_, matcher| matcher.call(path) }.first
  grouped[bucket] << path
end

BUCKETS.each_key do |bucket|
  files = grouped[bucket]
  puts "[#{bucket}] #{files.empty? ? "(none)" : files.join(", ")}"
end

• skip이 먼저 실행되므로 비밀 및 메모가 절대 스테이징되지 않습니다.
• 나머지 버킷은 프로젝트에 맞게 조정할 수 있습니다(예: Phoenix 앱은 lib/, priv/repo/migrations/, assets/ 를, Next.js 앱은 pages/, app/, public/, prisma/ 를 추가).

더러운 레포지토리에서 스크립트를 실행하면 다음과 같은 결과가 나옵니다:

--- unstaged ---
 M config.toml
 M templates/index.html

--- untracked ---
content/blog/_index.md
content/blog/post.md

--- classified ---
[skip]   (none)
[test]   (none)
[db]     (none)
[config] config.toml
[docs]   content/blog/_index.md, content/blog/post.md
[app]    templates/index.html

이제 에이전트는 다음과 같은 구체적인 커밋을 만들 수 있습니다:

• chore(config): bump zola version
• feat(templates): add language toggle
• feat(blog): bootstrap section

하나의 포괄적인 커밋 대신에 이렇게 각각의 목적에 맞는 커밋을 생성합니다.

실행 중

/commit을 입력하면 Claude가:

1. bin/commit-survey를 실행하고 출력을 읽습니다.
2. 추가 컨텍스트가 필요한 파일들의 diff를 읽습니다.
3. 각 그룹을 Conventional Commits 메시지와 함께 스테이징하고 커밋합니다.
4. .env 및 기타 비밀 파일은 조용히 건너뜁니다.

전체 과정은 약 30 초가 걸리며 깔끔하고 범위가 지정된 커밋을 생성합니다.

실제 예시 (블로그 포스트)

실행 전 설문 결과:

[skip]   (none)
[test]   (none)
[db]     (none)
[config] config.toml
[docs]   content/blog/slash-commands-no-more-bad-commits.md,
         content/blog/slash-commands-no-more-bad-commits.pt-br.md
[app]    sass/_predefined.scss, sass/style.scss

/commit 결과:

feat(blog): add slash commands post in EN and pt‑br
chore(config): drop syntax theme, switch to monochrome code blocks
style(sass): apply osaka jade palette and bump body font

세 개의 커밋이 각각 명확한 범위를 가집니다.

직접 만들기

1. 위 스크립트를 복사합니다.
2. ~/.claude/commands/commit.md (전역) 또는 .claude/commands/commit.md (프로젝트‑로컬) 로 저장합니다.
3. 버킷 패턴을 여러분의 스택에 맞게 조정합니다.

다른 반복 작업을 위한 유사한 슬래시‑명령어를 만들 수 있습니다: /changelog, /release, /pr-draft, /deploy 등. 각 명령은 채팅에서 입력할 단계들을 담은 마크다운 파일일 뿐입니다.

마무리

작은 헬퍼 스크립트와 맞춤형 Claude 슬래시 명령만 있으면 AI가 일상적인 Git 작업을 신뢰성 있게 처리할 수 있습니다. 더 이상 일반적인 “update” 커밋이 없습니다—각 커밋은 마크다운 파일에 인코딩한 의도를 반영합니다.

Sources

• Conventional Commits 1.0.0
• Claude Code custom commands docs
• OpenCode
• OpenAI Codex CLI
• Aider
• Continue

원래는 guilherme44.com에 게시되었습니다.