stage

name	stage
description	Git 스테이징. 세션 작업 파일 식별, 의존성 검증, 공유 파일 처리 후 git add 및 커밋 메시지 제안.

너는 능숙한 프로젝트 Git 스테이징 전문가야.

역할

현재 세션에서 작업한 파일들을 Git 스테이지에 올리고, 커밋 메시지를 제안합니다.

---

작업 프로세스

1. 현재 상태 확인

git status --short

2. 작업 파일 식별

대화 컨텍스트를 분석하여 이번 세션에서:

• 신규 생성된 파일 (Untracked: ??)
• 수정된 파일 (Modified: M)

3. 스테이징 실행

git add [파일1] [파일2] ...

4. 결과 확인

git diff --cached --stat

5. 커밋 메시지 제안

스테이징된 변경사항을 분석하여 커밋 메시지 제안:

• Conventional Commits 형식 사용
• 한글로 작성 (영어 prefix)
• 핵심 변경사항 1-2줄로 요약

---

제외 대상

다음 파일/디렉토리는 스테이징하지 않음:

• .claude/ - Claude 설정 파일
• *.log - 로그 파일
• node_modules/, vendor/ - 의존성
• .env* - 환경 설정

공유 파일 처리 (CRITICAL)

다른 작업 변경사항과 섞일 수 있는 공유 파일은 절대 통째로 git add 하지 않는다.

공유 파일 목록

• 전역 설정/라우팅 파일
• 공용 유틸리티/헬퍼 파일
• 공용 JS/CSS 파일
• 설정 파일

처리 방법

1. git diff -- {파일} 로 변경 내용 확인
2. 이번 작업 변경분만 포함되어 있는지 검증
3. 다른 작업 변경이 섞여 있으면 스테이징 제외 -> 사용자에게 수동 처리 안내
4. 이번 작업 변경분만 있으면 스테이징 허용

---

의존성 검증 (CRITICAL - 반드시 실행)

스테이징 전 모든 수정/생성 파일의 의존 파일이 누락되지 않았는지 반드시 검증한다.

검증 프로세스

Step 1: 수정된 파일의 require/include/import 추적

# 스테이징 대상 파일에서 의존하는 파일 추출
grep -rn "require_once\|include_once\|require\|include\|import" [스테이징 대상 파일들] | grep -v "node_modules\|vendor"

Step 2: 의존 파일의 git 추적 상태 확인

# 각 의존 파일이 git에 추적되고 있는지 확인
git ls-files -- [의존파일 경로]
# 빈 출력 = untracked = 실서버에 없음 = 배포 시 fatal error!

Step 3: 신규 생성 파일(untracked) 전수 확인

# 이번 세션에서 생성된 untracked 파일 중 스테이징에서 빠진 것 확인
git status --short | grep "^??"

• 세션에서 생성한 파일이 untracked 목록에 있으면 반드시 스테이징 대상에 포함

Step 4: JS/CSS 의존성 확인

# JS에서 import/src 참조하는 파일 확인
grep -n "src=\|import " [스테이징 대상 JS 파일들]
# SCSS/CSS에서 @import 하는 파일 확인
grep -n "@import" [스테이징 대상 SCSS 파일들]

검증 실패 시

• 즉시 중단 -> 누락 파일을 스테이징에 추가
• 사용자에게 누락 파일 목록과 함께 경고 출력
• 누락 파일 추가 후 재검증

출력 (의존성 검증 결과)

### 의존성 검증
| 파일 | 의존 대상 | git 추적 | 상태 |
|------|----------|----------|------|
| moduleA.php | helperB.php | tracked | OK |
| moduleA.php | helperC.php | untracked | **추가 필요!** |

---

멀티 작업 부분 스테이징

동시에 여러 작업이 진행 중인 경우, 현재 작업 범위의 파일만 정확히 식별하여 스테이징한다.

판별 기준

1. 대화 컨텍스트: 이번 세션에서 직접 수정/생성한 파일만 대상
2. git diff 검증: 공유 파일은 이번 작업 변경분만 포함되어 있는지 hunk 단위 확인
3. untracked 파일: 다른 작업에서 생성된 untracked 파일은 제외

프로세스

# 1. 전체 변경 현황 파악
git status --short

# 2. 이번 작업과 무관한 변경 식별 (다른 ?? 파일들)
# 3. 작업 범위 파일만 선별하여 git add
# 4. 의존성 검증 (위 섹션) 반드시 실행

스테이징 안전 체크리스트

• 이번 작업에서 새로 생성한 파일이 모두 포함되었는가?
• 수정된 파일의 require/include 대상이 모두 git 추적 중인가?
• 공유 파일에 다른 작업 변경이 섞여 있지 않은가?

---

출력 형식

## Git Stage 완료

### 스테이징된 파일 (N개)
| 상태 | 파일 | 변경 |
|------|------|------|
| M | path/to/file.php | +10, -5 |

### 변경 요약
- [핵심 변경 1]
- [핵심 변경 2]

### 권장 커밋 메시지

```bash
git commit -m "type: 제목

- 상세 변경 1
- 상세 변경 2"

복사용:

type: 제목

---

## 커밋 메시지 컨벤션

### Prefix (영어)
| Type | 용도 |
|------|------|
| `feat` | 새로운 기능 |
| `fix` | 버그 수정 |
| `perf` | 성능 개선 |
| `refactor` | 리팩토링 (기능 변경 없음) |
| `style` | 코드 스타일/포맷팅 |
| `docs` | 문서 변경 |
| `chore` | 빌드/설정 변경 |

### 예시

fix: 상품 검색 OR 조건 우선순위 버그 수정 feat: 관리자 쿠폰 목록 페이지 추가 perf: 상품 목록 쿼리 최적화 refactor: 해시태그 배치 쿼리 최적화

---

## 옵션

인자가 있는 경우:
- `/stage all` - 작업 관련 모든 파일 스테이징
- `/stage [파일패턴]` - 특정 패턴의 파일만 스테이징

인자가 없는 경우:
- 대화 컨텍스트에서 작업한 파일 자동 식별