# Git Workflow

> 사용자가 "커밋해줘", "스테이지해줘", "PR 만들어줘", "브랜치 만들어줘", "이거 올려줘", "git 작업 도와줘"라고 할 때 사용하세요. 안전한 git 작업, 커밋 메시지 작성, PR 생성을 위한 표준 절차를 제공합니다. 파괴적 명령은 절대 실행하지 않습니다. Use when this capability is needed.

- Skill: `tomevault-io/git-workflow-24` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/git-workflow-24`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/git-workflow-24/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/git-workflow-24

---


# Git 워크플로우 스킬

이 스킬은 `.claude/rules/30-git-commit.md`를 강제한다. 그 규칙과 충돌하는
어떤 행동도 하지 않는다.

## 커밋 절차

1. **상황 파악(병렬 실행).**
   - `git status` (`-uall` 플래그 금지 — 큰 레포에서 메모리 폭발)
   - `git diff` (스테이지 안 됨)
   - `git diff --staged`
   - `git log --oneline -10` (커밋 메시지 스타일 학습)

2. **변경 분석.**
   - 변경의 본질(feat / fix / docs / refactor / test / chore / perf / build / ci).
   - 비밀이 들어 있을 가능성이 있는 파일(`.env`, `*.pem`, `id_rsa`, `credentials*`)이
     스테이지된 게 있다면 멈추고 사용자에게 경고한다.

3. **메시지 작성.**
   - 제목: 명령형, 72자 이내, 끝에 마침표 없음.
   - 본문: *왜*에 초점. *무엇*은 diff가 보여준다.
   - 깨지는 변경, 이슈 링크, 마이그레이션 노트가 있다면 본문에.

4. **명시적 스테이징과 커밋(병렬).**
   - 파일을 이름으로 `git add path1 path2`. `-A`, `.` 금지.
   - `git commit -m "$(cat <<'EOF' ... EOF)"` 형식의 HEREDOC.
   - 커밋 후 `git status`로 성공 확인(순차).

5. **pre-commit hook 실패 시.**
   - 절대 `--no-verify`로 우회하지 않는다.
   - 절대 *이전* 커밋에 `--amend` 하지 않는다(hook 실패 시 커밋은 만들어지지 않은 상태이므로 `--amend`는 *이전* 커밋을 손상시킨다).
   - 문제를 고치고 다시 스테이지하고 새 커밋을 만든다.

## 문서 동기화 체크 (커밋/PR 전)

코드 변경이 문서와 어긋나면 다음 사람이 잘못된 문서를 믿고 삽질한다.
커밋 또는 PR 생성 전에 아래를 빠르게 점검한다.

**점검 대상 파일:**
```bash
# 프로젝트에 존재하는 문서 파일 확인
ls README* CHANGELOG* CONTRIBUTING* ARCHITECTURE* docs/ 2>/dev/null | head -20
```

**diff와 대조할 항목:**

| diff 내용 | 확인할 문서 |
|---|---|
| 새 CLI 명령·플래그·API 추가 | README의 사용법 섹션 |
| 설치 방법 변경 | README의 Quick start / Install |
| 설정 파일·환경 변수 추가·제거 | README 또는 `.env.example` |
| 디렉토리 구조 변경 | README의 구조 다이어그램 |
| 버전 범프 | CHANGELOG (항목 존재하는지) |
| 기여 절차 변경 | CONTRIBUTING |
| 아키텍처 결정 | `.claude/memory/decisions.md` |

**판단 기준:**

- 문서가 코드와 **이미 일치하면** → 넘어간다. 억지로 업데이트하지 않는다.
- 문서가 **명백히 틀리거나 누락됐으면** → 같은 커밋에 포함하거나 사용자에게 알린다.
- 불확실하면 → 사용자에게 한 줄로 묻는다. 추측으로 문서를 수정하지 않는다.

**이 체크를 건너뛸 수 있는 경우:**

- `chore:`, `test:`, `refactor:` 타입 커밋으로 사용자 노출 동작 변경이 없는 경우.
- 사용자가 명시적으로 "문서는 나중에"라고 말한 경우.

---

## PR 절차

1. 베이스 브랜치와 분기점 이후의 *모든* 커밋을 본다(마지막 커밋만 보지 말 것).
2. **문서 동기화 체크** 실행 — 위 섹션 참고.
3. 제목은 70자 이내로 짧게.
4. 본문은 다음 형식:
   ```markdown
   ## Summary
   - 1~3개의 불릿

   ## Test plan
   - [ ] 검증 항목 1
   - [ ] 검증 항목 2

   ## Docs
   - [ ] 문서 업데이트 완료 / 해당 없음
   ```
5. `gh pr create --title "..." --body "$(cat <<'EOF' ... EOF)"`.
6. 끝나면 PR URL을 사용자에게 돌려준다.

## 절대 금지
- `push --force`(공유 브랜치). 사용자가 명시 요청 시 `--force-with-lease`만 허용.
- `reset --hard` (푸시 안 한 작업이 있는 브랜치).
- 타인 커밋에 `--amend`.
- 사용자가 요청하지 않은 commit / push / PR.
- `git rebase -i`, `git add -i` (인터랙티브 플래그는 이 환경에서 동작하지 않음).

---
> Source: [KirSsuRyu/venom](https://github.com/KirSsuRyu/venom) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-06-16 -->