git-master

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.

Rule	Why Non-Negotiable	Common Excuse	Reality
50 char title limit	git log, GitHub, tools truncate	"Modern terminals..."	Tools haven't changed. 50 chars.
One logical change	Atomic = reviewable, revertable	"Save my work"	Use branches, not mega-commits
Korean 명사형 종결	Project convention	"I prefer English"	Project rules override preference

</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]".

Good	Bad
feat: 사용자 인증 기능 추가	feat: 사용자 인증 기능 추가함
fix: 결제 오류 수정	fix: 결제 오류 수정했음

Breaking Changes

Changes that break backward compatibility must be marked:

Method	Format	Example
Type with exclamation	type + "!" + message	feat!: API 응답 형식 변경
Footer	BREAKING CHANGE: desc	Write at the end of body

Git Trailers (Optional)

Add trailers at the end of body when needed:

Trailer	Usage
Co-authored-by:	Pair programming
Fixes:	Issue linking (Fixes: #123)
Signed-off-by:	Projects requiring DCO

---

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 — Commit messages describe the change itself.

• Describe what changed, rather than the source of the change (code review, issue number, meeting decision)
• Someone reading git log six months later will not know what "리뷰 P1-3 수정" means
• Record the source/context in the body or a trailer (Fixes #123)

---

Quick Reference

Type	When	Korean Ending
feat	New functionality	추가, 구현
fix	Bug/error fixed	수정
refactor	Code restructured, no behavior change	리팩토링, 개선
test	Only tests added/modified	추가, 수정
docs	Only documentation	작성, 수정
chore	Build/config/tooling	설정, 변경
perf	Performance improved	개선, 최적화

---

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

Changed Files	Action
1-2 files	Likely single commit — verify one logical change
3+ files	Pause and analyze — are there multiple concerns?
10+ files	Strongly consider splitting — multiple concerns are probable

Mandatory Self-Check (3+ Files)

When 3+ files change, you must perform this self-check before committing:

"N개 파일을 M개 커밋으로 만든다."
IF M == 1 AND N >= 3:
  → Is this really one logical change?
  → Can you explain in one sentence why these files must stay together?
  → If you cannot → SPLIT

This is not a numerical formula. 3+ files means "think it through," not "always split." A single commit is justified when logical cohesion is sufficient, as in Example 7 (point accrual: 4 files = 1 commit).

Commit Justification (3+ Files per Commit)

When a commit includes 3 or more files, you must explain why they belong together in one sentence:

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

Valid Reason	Invalid Reason (→ must split)
Implementation + its direct test file	"같은 기능 관련" (vague)
Type definition + its only consumer	"같은 PR에 포함" (not a reason)
Migration + model change (splitting breaks the build)	"함께 변경됨" (not a reason)
Multiple files in a single rename operation	"관련 있어서" (vague)

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:

Signal	Example
Different change types mixed	Bug fix + unrelated refactor
Different domains/modules affected	auth/ change + user/ change with no dependency
Independently revertable parts	Config change that works without the feature using it
Description gets too long	"Fixed X and also added Y and refactored Z"
Different architectural layers	Config + domain + service + test + docs for one feature
Multiple independent changes (even in 1-2 files)	3 review findings each require an independent change → 3 commits

When NOT to Split

Keep as single commit when:

Signal	Example
Truly atomic operation	Renaming a class across 5 files
Tightly coupled pair	DTO definition + the single mapper using it
Cannot exist independently	Interface + its only implementation (in same module)
Single mechanical change	Formatting/linting across many files

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

Test files must be included in the same commit as their corresponding implementation:

Test Pattern	Implementation File
*_test.sh	*.sh
*.test.ts	*.ts
*.spec.ts	*.ts
*Test.kt	*.kt
__tests__/*	Corresponding source

Anti-pattern: Splitting implementation and tests into separate commits. An implementation commit without tests cannot be verified in its intermediate state.

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
  • Functionality vs documentation: "If it defines system behavior, it is functionality; if it provides reference/shared information for human readers, it is documentation"
  • Changes to functional files (SKILL.md, agents/.md, rules/.md, hooks/*) → feat/fix/refactor
  • Changes to documentation files (README.md, API specifications, guides) → docs
• Build/config → chore
• Performance → perf

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

When 3 or more files change, you must output a commit plan before executing any commit:

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)

Do not proceed to commit execution without this output. Skip this step for changes to 1-2 files.

Caution about fix: Changes arising from code review are not all fix. Even for review findings, use feat for new functionality and refactor for structural improvements. Only actual bug/error fixes use fix.

Step 5: Generate Commit Message

MANDATORY Self-Check (Immediately After Drafting the Subject)

Immediately after drafting the subject and before committing, you must check it for invented/opaque labels. If any pattern matches, rewrite and check again. This check enforces anti-pattern 1 (Invented/opaque label ban) of the communication-style rule (rules/communication-style.md). The canonical source of the detection regexes is hooks/lib/label-patterns.sh — git-master does not keep its own copy.

Why this is mandatory: Plan step numbers and AC IDs are clear to the worker viewing the plan, but git log readers cannot access that plan — past violations have required history rewrites to correct them.

When a violating pattern is found:

• Simply remove the token: (Step 12) → delete (when the subject is already self-contained in domain terms)
• Replace the token with domain terms: align RN tooling lockstep with mobile (Step 4) → RN tooling mobile에 정렬
• If traceability is truly needed, move it to a body trailer: Refs: dispenser-monorepo-absorption.md#step-12

Subject rules (NON-NEGOTIABLE):

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

Subject content rule:

The subject's audience is a future git log reader — someone encountering the line six months later or another developer doing code archaeology. The subject must let that reader understand what changed without external context.

Reader model:

What Readers Have	What Readers Do Not Have
The codebase itself	PR description, review thread
commit body / diff	Work session context
Domain knowledge	Internal classification systems (P-ratings, severity labels)
History of other commits	Meeting notes, Slack messages

Validation questions — ask yourself after writing the subject:

1. "Can readers understand what changed from this subject alone?"
2. "Do readers need access to external documents/session context to understand it?"

If 1 is NO or 2 is YES → rewrite.

Common failure patterns (depend on external context):

Pattern	Why It Fails
Review classifications (P0/P1/HIGH/CRITICAL, etc.)	Readers cannot access the classification definitions
Workflow labels (잔여/residual/follow-up)	Session context is needed to know what remains
Process references (리뷰/audit/라운드)	External documents are needed to identify the review/audit
Vague counts (3건/여러 건 alone)	What the count refers to is unclear without the body
Plan step numbers (Step N/Step 7.6/Phase N/Round N)	The external plan is needed to identify which plan's step N
Acceptance criteria IDs (AC M1/H4/(M3))	AC definitions are in an external plan/spec inaccessible to readers

These are clear to you during the work but meaningless to git log readers. Put any needed source/classification/count in the body or a trailer — describe the change itself in domain terms in the subject.

BAD vs GOOD subjects (real examples):

BAD (depends on external context)	GOOD (self-contained, domain terms)
fix: collect-jd P1 스펙 드리프트 3건 정합	fix: ledger filename + canonical path + Gate 5 classification 정합
refactor: SKILL.md HIGH 잔여 3섹션 cross-ref 전환	refactor: SKILL.md Session Lock + Atomic Write + L1/L2 cross-ref 전환
fix: 코드 리뷰 P1/P2 이슈 수정	fix: persistence 저장 시점을 Step 완료 단위로 변경
chore(dispenser): remove per-app husky (AC M1)	chore(dispenser): per-app husky 제거

GOOD subjects directly reveal the changed area (file/module/domain concept) without external documents.

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)

Type	When to Use
feature/	New functionality
fix/	Bug fixes
refactor/	Code restructuring
chore/	Build, config, tooling
docs/	Documentation only
test/	Tests only

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

Mistake	Why It's Wrong	Fix
Multiple features in one commit	Hard to rollback/cherry-pick	Separate by logical unit
Vague messages like "수정함"	Unclear what was changed and why	Describe specific changes
Writing commit messages in English	Project convention violation	Use Korean 명사형 종결
Period at end of title	Unnecessary character	Remove period
Title exceeding 50 characters	Truncated in git log	Keep core message, move details to body
Committing plan.md	Workflow files mixed in	git reset HEAD plan.md
Meta-commit: "리뷰 이슈 수정"	The change is opaque; git log becomes meaningless	Describe the actual change: "저장 시점을 Step 완료 단위로 변경"
Opaque reference: "P1-1, P2-3 반영"	Cannot be decoded without external documents	Put references in the body/trailer and the change itself in the subject
Subjects depending on external context (P1 X, HIGH 잔여 Y, 리뷰 N건)	git log readers cannot access the classification system/session context — meaning is lost	Describe the change itself in domain terms; put classification/context in the body or trailer
Embedding plan-step / AC IDs	git log readers cannot decode them without the plan — tokens meaningful only to the worker	Automatically check with Step 5 MANDATORY Self-Check (canonical patterns: hooks/lib/label-patterns.sh); put traceability in the PR description or trailer

---

When NOT to Use

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