# AGENTS.md

이 저장소에서 작업하는 코딩 에이전트(Codex 포함)는 아래 Git 규칙을 반드시 준수합니다.
이 문서는 에이전트 작업 품질(일관된 브랜치/커밋 히스토리, 리뷰 용이성)을 위해 존재합니다. :contentReference[oaicite:2]{index=2}

---

## 1) Branch Naming Rules

### 1.1 기본 규칙
- 브랜치는 **소문자** + **하이픈(-)** 조합을 기본으로 합니다.
- 포맷은 아래 카테고리별 규칙을 따릅니다.

### 1.2 카테고리별 브랜치 규칙
- feature : `feature/<기능요약>` (예: `feature/login`)
- bugfix : `bugfix/<버그요약>` (예: `bugfix/login-redirect`)
- refactor : `refactor/<리팩터요약>` (예: `refactor/order-service-split`)
- chore : `chore/<작업요약>` (예: `chore/bump-deps`)
- docs : `docs/<문서요약>` (예: `docs/api-guide`)
- test : `test/<테스트요약>` (예: `test/order-e2e`)
- ci : `ci/<파이프라인요약>` (예: `ci/github-actions`)
- experiment : `experiment/<실험요약>` (예: `experiment/loki-labeling`)
- infra : `infra/<인프라요약>` (예: `infra/nginx-proxy`)
- release : `release-<버전>` (예: `release-1.2`)
- hotfix : `hotfix-<버전>` (예: `hotfix-1.2.1`)

### 1.3 브랜치 생성/전환 정책(에이전트)
- 작업 시작 시, 현재 브랜치가 `main/master` 등 보호 브랜치라면
  **규칙에 맞는 새 브랜치를 생성**해서 그 브랜치에서만 작업합니다.
- 브랜치 생성이 필요한데 사용자가 이미 브랜치명을 지정하지 않았다면:
  - 변경 의도를 3~5 단어로 요약해 위 규칙으로 브랜치명을 제안하고,
  - 사용자가 “그대로 진행”이라고 하면 생성합니다.

(브랜치 네이밍을 카테고리로 시작하는 방식은 널리 쓰이는 관례입니다. :contentReference[oaicite:3]{index=3})

---

## 2) Commit Message Convention

### 2.1 형식
- 커밋 메시지 헤더(제목)는 다음 형식을 따릅니다.
- 커밋 메시지는 **한글로 작성**합니다.

`<type>: <제목>`

예: `feat: 회원가입 기능 추가`

> 이 형식은 Conventional Commits의 `<type>: <description>` 구조와 호환됩니다. :contentReference[oaicite:4]{index=4}

### 2.2 type 목록
- `feat`: 새로운 기능 추가
- `fix`: 버그 수정
- `docs`: 문서 수정
- `style`: 코드 포맷팅, 세미콜론 누락 등 기능에 영향 없는 변경
- `refactor`: 코드 리팩토링(기능 변화 없음)
- `perf`: 성능 개선
- `test`: 테스트 코드 추가/수정
- `chore`: 빌드/설정/의존성 등 기타 변경

### 2.3 제목/본문 작성 규칙
- 제목(첫 줄)은 변경을 한 문장으로 요약합니다.
- 본문은 **필요할 때만** 추가합니다(복잡한 의도/대안/트레이드오프가 있을 때).
- 본문은 **한 줄당 72자 이하로 줄바꿈**합니다. (여러 Git 도구에서 가독성을 높이기 위한 일반 권장 사항입니다. :contentReference[oaicite:5]{index=5})

권장 본문 템플릿:
- Why: 왜 변경했는지
- What: 무엇을 변경했는지(핵심만)
- Notes: 영향/마이그레이션/리스크

예시:
```

feat: 회원가입 기능 추가

Why: 이메일 기반 회원가입 요구사항 반영
What: /signup API, validation, DTO 추가
Notes: 기존 로그인 플로우 영향 없음

```

---

## 3) When to Commit (에이전트 커밋 타이밍)

에이전트는 “논리적으로 독립된 변경 단위”마다 커밋합니다.

- ✅ 커밋해야 하는 경우
  - 기능/버그/리팩터링이 **사용자 관점에서 완료**되었고,
  - 최소한의 검증(빌드/테스트/린트 중 가능한 범위)이 끝났으며,
  - `git diff`가 “하나의 목적”으로 설명 가능한 상태

- ❌ 커밋을 나누어야 하는 경우
  - 포맷팅(style) 변경과 기능 변경이 섞여있음 → 커밋 분리
  - 리네이밍/대규모 이동과 로직 변경이 섞여있음 → 커밋 분리
  - 실험(experiment) 코드와 제품 코드가 섞여있음 → 커밋 분리 또는 실험 브랜치로 격리

---

## 4) Safety / Git Operations Policy (중요)

- 에이전트는 **`git add` / `git commit` 까지 수행**할 수 있습니다.
- 단, 아래 작업은 **사용자가 명시적으로 요청한 경우에만** 수행합니다:
  - `git push`
  - 원격 브랜치 생성/삭제
  - 태그 생성, 릴리즈 생성
  - rebase/force-push 같은 히스토리 재작성

- 커밋 전 필수 체크
  - `git status`로 변경 범위를 확인
  - 불필요한 파일(빌드 산출물, secrets, local config 등)이 포함되지 않도록 확인
  - 커밋 메시지가 위 컨벤션(`<type>: <제목>`)을 만족하는지 확인

---

## 5) PR/리뷰를 위한 최소 품질 기준

- 변경 사항이 작동/빌드 가능한 상태여야 합니다.
- 가능하다면 관련 테스트를 추가/수정하고, 최소한 기존 테스트가 깨지지 않도록 합니다.
- 문서 변경(docs)이면 해당 문서 경로/목차 일관성을 유지합니다.

---

## 6) Quick Reference

### Branch examples
- `feature/login`
- `bugfix/login-redirect`
- `refactor/order-service-split`
- `chore/bump-deps`
- `docs/api-guide`
- `test/order-e2e`
- `ci/github-actions`
- `experiment/loki-labeling`
- `infra/nginx-proxy`
- `release-1.2`
- `hotfix-1.2.1`

### Commit examples
- `feat: 회원가입 기능 추가`
- `fix: 로그인 리다이렉트 오류 수정`
- `refactor: 주문 서비스 분리`
- `chore: 의존성 버전 업데이트`
- `docs: API 가이드 보강`
- `test: 주문 E2E 테스트 추가`
- `ci: GitHub Actions 파이프라인 개선`