name: git-master description: Use when committing changes to git or naming branches. Triggers include "commit", "커밋", "git commit", "finalize changes", "save to git", "commit my work", "branch name", "브랜치 이름", "what should I name this branch".

Git Master

Analyze code changes and generate Korean commit messages following project conventions. Also applies branch naming conventions when naming new branches.

"A good commit makes history easy to read. A bad commit turns git log into a graveyard."

<Critical_Constraints>

The Iron Law

NO COMMIT WITHOUT:
1. Single logical change (or properly split)
2. Message ≤ 50 characters
3. Subject comprehensible to git log readers without external context

Violating the letter of these rules IS violating the spirit.

There are no exceptions. User preference does not override project rules.

Non-Negotiable Rules

These are RULES, not guidelines. This project enforces them strictly.

</Critical_Constraints>

Workflow Files: NEVER COMMIT

These files are workflow artifacts, not implementation deliverables:

# ALWAYS unstage these before committing:
git reset HEAD plan.md 2>/dev/null || true
git reset HEAD research.md 2>/dev/null || true
git reset HEAD docs/specs/ 2>/dev/null || true

Why?

• plan.md: Worker updates separately after commit
• research.md: Research artifact, not code
• docs/specs/*: Input documents, never modified

If user says "I always commit plan.md with my code" → Refuse. Project rules.

Best Practice Additions (Industry Standard)

Imperative Mood

Commit messages should be written in imperative mood. The message should complete the sentence: "If applied, this commit will [your message]".

Breaking Changes

Changes that break backward compatibility must be marked:

Git Trailers (Optional)

Add trailers at the end of body when needed:

Core Principle

One commit = One logical change

• Separate unrelated changes (atomic commits)
• Title must be within 50 characters, core message only
• WHY goes in body (optional)
• Many files ≠ many commits — logical cohesion decides (see Atomic Commit Splitting)

Product, Not Process — 커밋 메시지는 변경 자체를 설명한다.

• 변경의 출처(코드 리뷰, 이슈 번호, 회의 결정)가 아니라 무엇이 바뀌었는지 기술
• 6개월 뒤 git log를 읽는 사람은 "리뷰 P1-3 수정"이 무슨 뜻인지 모른다
• 출처/맥락은 body나 trailer(Fixes #123)에 기록

Quick Reference

Process Steps

Step 1: Analyze Changes

git status
git diff
git diff --staged

For each changed file, categorize:

• What domain/feature is affected?
• What is the main change?
• Are there multiple logical changes? → Split!

Atomic Commit Splitting

"Separate each logical change into a separate patch." — Linux Kernel Documentation

"If you make a single change to numerous files, group those changes into a single patch." — Linux Kernel Patch Philosophy

File count is a TRIGGER for analysis, NOT a splitting rule.

Split Analysis Trigger

Mandatory Self-Check (3+ Files)

3+ 파일 변경 시 커밋 전 반드시 자가 점검:

"N개 파일을 M개 커밋으로 만든다."
IF M == 1 AND N >= 3:
  → 정말 하나의 논리적 변경인가?
  → 각 파일이 함께여야 하는 이유를 한 문장으로 쓸 수 있는가?
  → 쓸 수 없으면 → SPLIT

이것은 수치 공식이 아니다. 3+ 파일이면 "생각을 거치라"는 것이지, "반드시 분할하라"는 것이 아니다. Example 7(포인트 적립 4파일 = 1커밋)처럼 논리적 응집성이 충분하면 단일 커밋이 정당하다.

Commit Justification (3+ Files per Commit)

하나의 커밋에 3개 이상 파일이 포함될 때, 왜 함께인지 한 문장으로 기술해야 한다:

"이 커밋은 [파일들]을 포함한다. 이유: [구체적 이유]"

IMPORTANT: One feature ≠ one commit. A feature may contain multiple logical changes (config, domain, service, test, docs). Each independently meaningful layer is a separate commit. However, a single atomic operation (e.g., renaming across 10 files) IS one commit.

When to Split

Split when ANY of these are true:

When NOT to Split

Keep as single commit when:

Grouping Strategy (when splitting)

Commit in this order (dependency-first):

1. Config/Build — dependencies, build settings
2. Infrastructure — refactoring, API changes
3. Source/Logic — business logic, features
4. Tests — related test code
5. Documentation — README, docs

Splitting Rules

Each split commit must:

• Be independently meaningful (not "part 1 of 3")
• Have its own proper commit message
• Leave the codebase in a buildable state
• Be revertable without breaking other commits

Test-Implementation Pairing

테스트 파일은 반드시 대응하는 구현체와 같은 커밋에 포함한다:

Anti-pattern: 구현과 테스트를 별도 커밋으로 분리하는 것. 테스트 없는 구현 커밋은 중간 상태에서 검증 불가능하다.

Step 2: Verify No Workflow Files

git diff --staged --name-only | grep -E "^(plan\.md|research\.md|docs/specs/)"

If any match → Unstage them before proceeding.

Step 3: Determine Commit Type

• New functionality → feat
• Bug/error fixed → fix
• Code restructured without behavior change → refactor
• Only tests → test
• Only docs → docs
  • 기능 vs 문서 판단: "시스템 동작을 정의하면 기능, 인간 독자를 위한 참조/공유 정보면 문서"
  • 기능적 파일 (SKILL.md, agents/.md, rules/.md, hooks/*) 변경 → feat/fix/refactor
  • 문서 파일 (README.md, API 명세서, 가이드) 변경 → docs
• Build/config → chore
• Performance → perf

Step 4: Output Commit Plan (3+ Files — BLOCKING)

3개 이상 파일 변경 시, 커밋을 실행하기 전에 반드시 커밋 계획을 출력한다:

COMMIT PLAN
───────────
변경 파일: N개
계획 커밋 수: M개

COMMIT 1: type: 제목
  - path/to/file1
  - path/to/file1_test
  Justification: 구현체 + 직접 테스트

COMMIT 2: type: 제목
  - path/to/file2
  Justification: 독립적 설정 변경

실행 순서: Commit 1 → Commit 2
(의존성 순서: Config → Source → Test → Docs)

이 출력 없이 커밋 실행으로 넘어가지 않는다. 1-2개 파일 변경은 이 단계를 건너뛴다.

fix 타입 주의: 코드 리뷰에서 나온 변경이 전부 fix는 아니다. 리뷰 지적이라도 새 기능이면 feat, 구조 개선이면 refactor. 실제 버그/오류 수정만 fix.

Step 5: Generate Commit Message

Subject rules (NON-NEGOTIABLE):

• Korean (한국어)
• Max 50 characters ← ENFORCED, not a guideline
• 명사형 종결 (e.g., "추가", "수정", "삭제", "구현", "개선")
• No period at end

Subject content rule:

제목의 독자는 미래의 git log 독자다 — 6개월 뒤 또는 다른 개발자가 코드 archaeology 중에 만나는 줄. 제목은 그 독자가 외부 맥락 없이 무엇이 바뀌었는지 이해할 수 있어야 한다.

독자 모델:

검증 질문 — 제목을 쓴 후 자문:

1. "독자가 이 제목만 보고 무엇이 바뀌었는지 이해하는가?"
2. "독자가 외부 문서/세션 맥락에 접근해야만 의미를 알 수 있는가?"

1번이 NO 또는 2번이 YES면 → rewrite.

자주 실패하는 패턴 (외부 맥락에 의존):

이들은 작업 중인 본인에게는 명확하지만 git log 독자에게는 의미 없다. 출처/분류/카운트가 필요하면 body 또는 trailer로 — 제목은 변경 자체를 도메인 용어로 기술.

BAD vs GOOD subjects (실제 사례):

GOOD 제목들은 외부 문서 없이도 변경 영역(파일/모듈/도메인 개념)이 직접 보인다.

If subject > 50 chars:

1. Identify the ONE core change
2. Remove unnecessary words
3. Move details to body
4. Do NOT commit with > 50 chars

Body rules (when needed):

• Blank line between subject and body
• Wrap at 72 characters
• Explain WHY, not WHAT

Footer rules (when needed):

• Blank line between body and footer
• BREAKING CHANGE: description for breaking changes
• Fixes #123 for issue references
• Co-authored-by: Name <email> for pair programming

See references/commit-conventions.md for complete format.

Step 6: Execute Commit

git add .
git reset HEAD plan.md 2>/dev/null || true
git reset HEAD research.md 2>/dev/null || true
git reset HEAD docs/specs/ 2>/dev/null || true

# Verify staged files
git diff --staged --name-only

# Commit
git commit -m "$(cat <<'EOF'
type: 한국어 제목 50자 이내
EOF
)"

Step 7: Return Result

## Commit Result
- **Hash**: [7-char hash]
- **Type**: [feat/fix/refactor/etc.]
- **Message**: [full commit message]
- **Files**: [count] files changed

Branch Naming Convention

Format: <type>/<description> (kebab-case, English)

Examples: feature/user-auth, fix/login-redirect, refactor/api-middleware, chore/update-deps

Rules:

• All lowercase, words separated by hyphens
• Description is English, concise (2-4 words)
• No special characters except hyphens

Edge Cases

No changes: Return "Warning: No changes to commit. Working tree is clean."

Message too long: NEVER just "accept" a long message. Shorten it.

Mixed types: Use primary type, mention secondary in body.

User insists on violation: Explain why you cannot comply. Offer alternatives.

Large cohesive change (10+ files): Analyze by concern. One feature ≠ one commit. Split by architectural layer (config, source, test, docs) unless the change is a single atomic operation (e.g., rename).

Examples

See examples.md for commit message examples.

Common Mistakes

When NOT to Use

• Uncommitted changes in unrelated files → Stash or separate commit
• No actual changes → Nothing to commit