Gentle AI — 브랜치 및 PR 스킬은(는) 무엇을 하나요?
사용 시기
다음과 같은 경우 이 스킬을 로드하세요:
- 새로운 수정 또는 기능을 위한 브랜치 생성
- Gentleman-Programming/gentle-ai에서 풀 리퀘스트 열기
- 검토를 위한 변경 사항 준비
중요 규칙
- 모든 PR은 승인된 이슈와 연결되어야 함 — PR 본문에
Closes/Fixes/Resolves #<N>을 포함하고, 해당 이슈에는status:approved가 있어야 합니다. 이를 충족하지 않는 PR은 CI에서 자동으로 거부됩니다. - 일반적인
type:*분류 — CI는 0개 또는 여러 개의 타입 라벨을 거부합니다. 표준 이슈 생성 워크플로 계약을 통해 처리하세요. 즉, 현재 직접적인 인간 명령이 정확한 대상/작업을 바인딩하고, 대상 호스트 기능이 확인되며, 하나의 바운드된 변경과 대상 호스트 읽기백을 사용해야 합니다. 그렇지 않으면 변경 없이 대기합니다. - 보호된 정책 라벨 —
status:approved또는size:exception라벨을 추가/제거하려면 대상 호스트 저장소 관리자 또는 저장소 승인자의 확인된 정책 권한과, 인증된 행위자의 대상 호스트viewerPermission이MAINTAIN또는ADMIN이어야 합니다.size:exception은 추가로 초과 예산에 대한 문서화된 사유가 필요합니다. - 400줄 검토 예산 — PR의 변경된 줄 수(
additions + deletions)를 400줄 이내로 유지하거나,size:exception라벨에 필요한 사유를 문서화하세요. - 자동화된 검사 통과 필수 — 아래 자동화 검사 표를 참조하세요.
Co-Authored-By트레일러 금지 — 커밋에 AI 기여 정보를 절대 추가하지 마세요.- main/master에 강제 푸시 금지 — 보호된 브랜치입니다.
워크플로
1. 이슈에 status:approved 라벨이 있는지 확인
gh issue view <N> --repo Gentleman-Programming/gentle-ai
2. 아래 명명 규칙을 사용하여 main에서 브랜치 생성
3. 스펙과 설계에 따라 변경 구현
4. 로컬에서 검사 실행 (포맷 + 단위 + E2E)
5. Conventional Commits 형식으로 커밋
6. 이슈를 참조하는 PR 열기
→ PR 본문에 정확히 하나의 type:* 결과 선언
→ PR 라벨 변경 전에 표준 이슈 생성 워크플로 계약 사용
→ 템플릿을 사용하여 PR 본문 작성
7. 병합 전에 모든 자동화 검사 통과 필수
브랜치 명명
브랜치 이름은 다음 패턴과 일치해야 합니다:
^(feat|fix|chore|docs|style|refactor|perf|test|build|ci|revert)\/[a-z0-9._-]+$
| 타입 | 예시 |
|---|---|
feat/ | feat/user-login |
fix/ | fix/duplicate-observation-insert |
docs/ | docs/api-reference-update |
refactor/ | refactor/extract-query-sanitizer |
chore/ | chore/bump-bubbletea-v0.26 |
style/ | style/fix-linter-warnings |
perf/ | perf/optimize-catalog-loading |
test/ | test/add-pipeline-coverage |
build/ | build/update-goreleaser-config |
ci/ | ci/add-e2e-docker-job |
revert/ | revert/undo-model-picker-change |
규칙:
- 모두 소문자 사용
- 구분자로 하이픈, 점, 밑줄 사용 (공백, 대문자 없음)
- 설명은 짧고 명확해야 함
PR 본문 형식
PR 본문은 .github/PULL_REQUEST_TEMPLATE.md에 있는 템플릿을 따라야 합니다. 모든 섹션은 필수이며, 선택 사항으로 표시된 경우는 예외입니다.
## 🔗 연결된 이슈
Closes #<N>
## 🏷️ PR 타입
- [ ] `type:bug` — 버그 수정 (이슈를 수정하는 비호환 변경)
- [ ] `type:feature` — 새 기능 (기능을 추가하는 비호환 변경)
- [ ] `type:docs` — 문서만 변경
- [ ] `type:refactor` — 코드 리팩토링 (기능 변경 없음)
- [ ] `type:chore` — 빌드, CI 또는 도구 변경
- [ ] `type:breaking-change` — 호환성 깨는 변경
## 📝 요약
<!-- 이 PR이 수행하는 작업과 이유에 대한 명확한 설명 -->
## 📂 변경 사항
| 파일 / 영역 | 변경 내용 |
|-------------|----------|
| `path/to/file` | 간략한 설명 |
## 🧪 테스트 계획
**단위 테스트**
\`\`\`bash
go test ./...
\`\`\`
**Go 포맷**
\`\`\`bash
go run ./internal/gofmtcheck
\`\`\`
**E2E 테스트** (Docker 필요)
\`\`\`bash
cd e2e && ./docker-test.sh
\`\`\`
- [ ] 단위 테스트 통과 (`go test ./...`)
- [ ] Go 포맷 통과 (`go run ./internal/gofmtcheck`)
- [ ] E2E 테스트 통과 (`cd e2e && ./docker-test.sh`)
- [ ] 로컬에서 수동 테스트 완료
## ✅ 기여자 체크리스트
- [ ] PR이 `status:approved` 라벨이 있는 이슈에 연결됨
- [ ] PR의 변경된 줄 수가 400줄 이내이거나, `size:exception` 사유와 확인된 정책 권한이 문서화됨
- [ ] API 읽기백을 통해 이 PR에 정확히 하나의 적절한 `type:*` 라벨이 있음 확인
- [ ] 단위 테스트 통과 (`go test ./...`)
- [ ] E2E 테스트 통과 (`cd e2e && ./docker-test.sh`)
- [ ] 필요한 경우 문서 업데이트 완료
- [ ] 커밋이 Conventional Commits 형식을 따름
- [ ] 커밋에 `Co-Authored-By` 트레일러가 포함되지 않음
자동화 검사
다음 검사는 모든 PR에서 실행되며, 병합 전에 모두 통과해야 합니다:
| 검사 | 확인 내용 | 해결 방법 |
|---|---|---|
| PR 인지 부하 확인 | PR의 변경된 줄 수가 400줄 이내이거나 size:exception 라벨이 있는지 확인 | PR을 분할하거나, size:exception 사유를 문서화하고 표준 워크플로 작업 전에 정책 권한 확인 |
| 이슈 참조 확인 | PR 본문에 Closes/Fixes/Resolves #N이 포함되어 있는지 확인 | PR 본문에 Closes #<N> 추가 |
이슈에 status:approved 라벨 확인 | 연결된 이슈에 필요한 라벨이 있는지 확인 | 현재 직접 명령과 대상 호스트 기능 권한이 정확한 작업을 승인하는 경우에만 표준 이슈 생성 워크플로 계약 사용; 그렇지 않으면 대기 |
PR에 type:* 라벨 확인 | PR에 정확히 하나의 type:* 라벨이 적용되었는지 확인 | 현재 직접 명령과 대상 호스트 기능이 정확한 작업을 승인하는 경우에만 표준 이슈 생성 워크플로 계약 사용; 그렇지 않으면 대기 |
| 단위 테스트 | go test ./... 통과 확인 | 푸시 전에 실패하는 테스트 수정 |
| Go 포맷 | go run ./internal/gofmtcheck 통과 확인 | 푸시 전에 잘못된 형식의 Go 파일 수정 |
| E2E 테스트 | cd e2e && ./docker-test.sh 통과 확인 | 푸시 전에 실패하는 E2E 시나리오 수정 |
Conventional Commits
커밋 메시지는 다음 패턴과 일치해야 합니다:
^(build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test)(\([a-z0-9\._-]+\))?!?: .+
형식
<type>(<optional-scope>)!: <description>
[optional body]
[optional footer]
허용된 타입
| 타입 | 목적 | PR 라벨 |
|---|---|---|
feat | 새 기능 | type:feature |
fix | 버그 수정 | type:bug |
docs | 문서만 변경 | type:docs |
refactor | 코드 변경 (동작 변경 없음) | type:refactor |
chore | 유지보수, 종속성, 도구 | type:chore |
style | 포맷, 린트 (로직 변경 없음) | type:chore |
perf | 성능 개선 | type:feature |
test | 테스트 추가 또는 업데이트 | type:chore |
build | 빌드 시스템 또는 외부 종속성 | type:chore |
ci | CI 설정 | type:chore |
revert | 이전 커밋 되돌리기 | 되돌린 타입과 일치 |
호환성 깨는 변경
타입/스코프 뒤에 !를 추가하세요:
feat(cli)!: rename --config flag to --config-file
BREAKING CHANGE: the --config flag has been renamed to --config-file.
호환성 깨는 변경은 type:breaking-change 라벨로 매핑됩니다.
예시
feat(tui): add progress bar to installation steps
fix(agent): correct Claude Code detection on macOS
docs: update contributing guide
chore(deps): bump bubbletea to v0.26
refactor(pipeline): extract step executor
style: fix linter warnings in catalog package
perf(system): cache OS detection result
test(installer): add coverage for catalog step execution
build: update goreleaser config for arm64
ci: split unit and e2e test jobs
revert: undo model picker redesign
feat(cli)!: change default config path
명령어
설정
# 시작 전에 이슈가 승인되었는지 확인
gh issue view <N> --repo Gentleman-Programming/gentle-ai
# 브랜치 생성
git checkout main && git pull
git checkout -b fix/<short-description>
로컬 테스트
# 단위 테스트
go test ./...
# Go 포맷
go run ./internal/gofmtcheck
# 단위 테스트 — 특정 패키지
go test ./internal/tui/...
# 단위 테스트 — 자세히
go test -v ./...
# E2E 테스트 (Docker가 실행 중이어야 함)
cd e2e && ./docker-test.sh
PR 열기
gh pr create \
--repo Gentleman-Programming/gentle-ai \
--title "fix(agent): correct Claude Code detection on Linux" \
--body "$(cat <<'EOF'
## 🔗 Linked Issue
Closes #42
## 🏷️ PR Type
- [x] \`type:bug\` — Bug fix (non-breaking change that fixes an issue)
## 📝 Summary
Fixes Claude Code binary detection failing on Linux when HOME is not set.
## 📂 Changes
| File / Area | What Changed |
|-------------|-------------|
| \`internal/agents/claude.go\` | Added HOME env var fallback |
## 🧪 Test Plan
- [x] Unit tests pass (\`go test ./...\`)
- [x] E2E tests pass (\`cd e2e && ./docker-test.sh\`)
- [x] Manually tested locally
## ✅ Contributor Checklist
- [x] PR is linked to an issue with \`status:approved\`
- [x] PR stays within 400 changed lines, or the \`size:exception\` rationale and verified policy authority are documented
- [x] API read-back confirms exactly one appropriate \`type:*\` label on this PR
- [x] Unit tests pass (\`go test ./...\`)
- [x] E2E tests pass (\`cd e2e && ./docker-test.sh\`)
- [x] I have updated documentation if necessary
- [x] My commits follow Conventional Commits format
- [x] My commits do not include \`Co-Authored-By\` trailers
EOF
)"
PR 상태 확인
gh pr checks --repo Gentleman-Programming/gentle-ai <PR-number>
gh pr view --repo Gentleman-Programming/gentle-ai <PR-number>