From github-workflow
This skill should be used when the user asks to "setup github workflow", "워크플로우 설정", "CLAUDE.md에 워크플로우 추가", "github-workflow 적용", or mentions setting up the GitHub-based development workflow in their project.
How this skill is triggered — by the user, by Claude, or both
Slash command
/github-workflow:setupThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
프로젝트에 GitHub 기반 개발 워크플로우를 설정합니다.
프로젝트에 GitHub 기반 개발 워크플로우를 설정합니다.
/setup # 현재 프로젝트에 워크플로우 설정
/setup --force # 기존 파일 덮어쓰기
ls -la CLAUDE.md WORKFLOW.md .github-workflow.md 2>/dev/null
gh repo view --json nameWithOwner -q '.nameWithOwner' 2>/dev/null || echo "GitHub 저장소 미설정"
CLAUDE.md에 개발 워크플로우 섹션 추가 (기존 내용 유지):
## 개발 워크플로우
이 프로젝트는 **GitHub 기반 개발 워크플로우**를 따릅니다.
**상세 가이드:** [WORKFLOW.md](./WORKFLOW.md)
### 핵심 규칙
1. **Plan Mode 사용**: 구현 전 계획 수립 필수
2. **GitHub 이슈 연동**: 작업은 이슈와 연결
3. **커밋 시 이슈 참조**: `Closes #N` 형식
4. **설계 문서 준수**: `docs/` 폴더의 설계 문서 참조
### 작업 흐름
요청 → Plan Mode → 이슈 생성(필요시) → 구현 → 커밋 → 이슈 Close
### GitHub 컨텍스트
- 캐시 파일: `.github-workflow.md`
- 없으면 `gh` CLI로 조회
상세 워크플로우 가이드 생성:
# GitHub 기반 개발 워크플로우
이 프로젝트는 GitHub Issues/Projects를 활용한 체계적인 개발 워크플로우를 따릅니다.
## 워크플로우 개요
요청 → Plan Mode → 이슈 생성 → 구현 → 커밋 (이슈 참조) → 이슈 Close
---
## 1. 작업 시작 시
### 1.1 GitHub 컨텍스트 확인
```bash
# 캐시 파일 확인 (있으면 사용)
cat .github-workflow.md
# 없으면 gh CLI로 조회
gh repo view --json nameWithOwner,defaultBranchRef
gh issue list --state open
gh api repos/{owner}/{repo}/milestones
# 설계 문서 구조 파악
find docs/ -name "*.md" -type f
# 관련 문서 읽기
cat docs/{relevant-doc}.md
필수 확인 사항:
# 이슈 상세 조회
gh issue view <number> --json number,title,labels,state,body,milestone
# 이슈 본문에서 추출:
# - 설계 문서 참조 (GitHub URL → 로컬 경로 변환)
# - Acceptance Criteria
# - Blocked by (의존성)
https://github.com/{owner}/{repo}/blob/main/docs/auth.md
→ docs/auth.md
# 구현 계획: {제목}
## 개요
- 이슈: #{number} (있으면)
- 설계 문서: docs/{path}
## 컨텍스트 분석
- 설계 문서 요약
- 기존 코드 패턴
## 구현 Task
### Task 1: {task}
- [ ] 세부 작업
### Task 2: {task}
- [ ] 세부 작업
## 검증 체크리스트
- [ ] Acceptance Criteria 충족
- [ ] 설계 문서 스펙 준수
- [ ] 테스트 통과
- [ ] 빌드 성공
REPO=$(gh repo view --json nameWithOwner -q '.nameWithOwner')
BRANCH=$(gh repo view --json defaultBranchRef -q '.defaultBranchRef.name')
gh issue create \
--title "기능 제목" \
--body "## 설명
구현할 내용
## 📚 설계 문서 참조
- [doc.md](https://github.com/${REPO}/blob/${BRANCH}/docs/{path})
## Acceptance Criteria
- [ ] AC 1
- [ ] AC 2
- [ ] AC 3
## 일정
- Start: $(date +%Y-%m-%d)
- Due: YYYY-MM-DD
## Blocked by
- #{number} 선행 이슈 (있으면)" \
--milestone "v1.0" \
--label "backend,priority/high"
IMPORTANT: 설계 문서 링크는 반드시 절대 URL 사용 (상대경로는 404 발생)
이슈 생성 후 프로젝트에 추가하고 Roadmap용 필드를 설정합니다.
# 이슈 URL 저장 (이슈 생성 시)
ISSUE_URL=$(gh issue create --title "..." --body "..." --milestone "v1.0" | tail -1)
# 프로젝트 정보 조회 (.github-workflow.md 캐시 또는 API)
PROJECT_NUM=1 # 캐시에서 가져오거나 gh project list로 조회
# 프로젝트에 이슈 추가
ITEM_ID=$(gh project item-add $PROJECT_NUM --owner "@me" --url "$ISSUE_URL" --format json | jq -r '.id')
# 프로젝트 ID 조회 (필드 편집용)
PROJECT_ID=$(gh project view $PROJECT_NUM --owner "@me" --format json | jq -r '.id')
# 필드 ID 조회
FIELDS=$(gh project field-list $PROJECT_NUM --owner "@me" --format json)
START_DATE_FIELD=$(echo "$FIELDS" | jq -r '.fields[] | select(.name=="Start Date") | .id')
DUE_DATE_FIELD=$(echo "$FIELDS" | jq -r '.fields[] | select(.name=="Due Date") | .id')
PRIORITY_FIELD=$(echo "$FIELDS" | jq -r '.fields[] | select(.name=="Priority") | .id')
# Priority 옵션 ID 조회 (Single Select인 경우)
P1_OPTION=$(echo "$FIELDS" | jq -r '.fields[] | select(.name=="Priority") | .options[] | select(.name | contains("High")) | .id')
# 필드 값 설정
gh project item-edit --project-id $PROJECT_ID --id $ITEM_ID \
--field-id $START_DATE_FIELD --date "2024-02-01"
gh project item-edit --project-id $PROJECT_ID --id $ITEM_ID \
--field-id $DUE_DATE_FIELD --date "2024-02-15"
gh project item-edit --project-id $PROJECT_ID --id $ITEM_ID \
--field-id $PRIORITY_FIELD --single-select-option-id $P1_OPTION
캐시 파일 활용: .github-workflow.md에 project.id, project.fields.* 가 있으면 API 호출 생략
## 설명
{구현할 내용}
## 📚 설계 문서 참조
- [filename.md](https://github.com/{owner}/{repo}/blob/main/docs/{path})
## Acceptance Criteria
- [ ] AC 1
- [ ] AC 2
- [ ] AC 3
## 일정
- Start: YYYY-MM-DD
- Due: YYYY-MM-DD
## Blocked by
- #{number} {선행 이슈 제목}
# 작업 시작 시
gh issue edit <number> --add-label "in-progress"
| 도메인 | 파일 패턴 | 가이드라인 |
|---|---|---|
| Frontend | src/components/, .tsx | React/Next.js, 접근성, 반응형 |
| Backend | src/routers/, .py | FastAPI, SQLAlchemy, Pydantic |
| 공통 | src/lib/, src/utils/ | 재사용 가능한 로직 |
독립 Task는 병렬로:
// Frontend Task
{
"description": "Implement login form",
"subagent_type": "frontend-developer",
"run_in_background": true,
"prompt": "## Task\n로그인 폼 구현\n\n## Context\n- Issue: #12\n- Design: docs/auth.md"
}
// Backend Task (동시 실행)
{
"description": "Implement auth API",
"subagent_type": "backend-developer",
"run_in_background": true,
"prompt": "## Task\n인증 API 구현\n\n## Context\n- Issue: #13\n- Design: docs/api/auth.md"
}
의존성 있는 Task는 순차로:
// TaskOutput으로 완료 대기
{
"task_id": "{task1_id}",
"block": true,
"timeout": 120000
}
// 이후 의존 Task 실행
# Frontend
pnpm build && pnpm lint && pnpm test
# Backend
uv run pytest && uv run ruff check .
feat(scope): 기능 설명
- 변경 사항 1
- 변경 사항 2
Closes #<number>
Prefix 규칙:
feat: 새 기능fix: 버그 수정refactor: 리팩토링docs: 문서test: 테스트chore: 기타커밋 메시지에 포함 시 자동 Close:
Closes #NFixes #NResolves #Ngh issue close <number> --comment "## 구현 완료
### Acceptance Criteria
- [x] AC 1
- [x] AC 2
- [x] AC 3
### 변경 파일
- src/components/LoginForm.tsx
- src/lib/auth.ts
- src/routers/auth.py
### 커밋
- abc1234: feat(auth): 로그인 폼 구현
- def5678: feat(api): 인증 API 구현"
# in-progress 라벨 제거 (Close 시 자동 처리되기도 함)
gh issue edit <number> --remove-label "in-progress"
gh issue list --milestone "v1.0" --state open --json number,title,labels
이슈 본문의 Blocked by 파싱하여 실행 순서 결정:
# 모든 이슈 완료 확인
gh issue list --milestone "v1.0" --state open
# 마일스톤 닫기
gh api repos/{owner}/{repo}/milestones/{number} -X PATCH -f state=closed
# 프로젝트 생성
gh project create --owner "@me" --title "프로젝트명"
# 프로젝트 번호 확인
gh project list --owner "@me"
# 필드 생성
gh project field-create <number> --owner "@me" --name "Start Date" --data-type DATE
gh project field-create <number> --owner "@me" --name "Due Date" --data-type DATE
gh project field-create <number> --owner "@me" --name "Priority" --data-type SINGLE_SELECT \
--single-select-options "P0 - Critical,P1 - High,P2 - Medium,P3 - Low"
gh api repos/{owner}/{repo}/milestones \
-f title="v1.0" \
-f description="첫 번째 릴리스" \
-f due_on="2024-03-01T00:00:00Z"
gh label create "epic" --color "7057FF" --description "Epic 이슈"
gh label create "in-progress" --color "FBCA04" --description "진행 중"
gh label create "backend" --color "1D76DB"
gh label create "frontend" --color "A2EEEF"
gh label create "priority/high" --color "D93F0B"
gh label create "priority/medium" --color "FBCA04"
gh label create "priority/low" --color "0E8A16"
# 이슈 생성 후 프로젝트에 추가
ISSUE_URL=$(gh issue create --title "..." --body "..." | tail -1)
gh project item-add <project-number> --owner "@me" --url "$ISSUE_URL"
---
repository: owner/repo
default_branch: main
project:
title: Project Name
number: 1
id: PVT_xxxxx
fields:
status: PVTSSF_xxxxx
start_date: PVTF_xxxxx
due_date: PVTF_xxxxx
milestones:
v1.0: 1
v1.1: 2
labels:
- backend
- frontend
- in-progress
- priority/high
cached_at: 2026-01-30
---
마일스톤/라벨 변경 시:
# 마일스톤 조회
gh api repos/{owner}/{repo}/milestones --jq '.[] | "\(.title): \(.number)"'
# 라벨 조회
gh label list --json name -q '.[].name'
구현 완료 전 확인:
Project → Settings → Workflows:
| Workflow | 트리거 | 동작 |
|---|---|---|
| Item added | 이슈 추가 시 | Status → "Todo" |
| Item reopened | 이슈 재오픈 시 | Status → "In Progress" |
| Item closed | 이슈 닫힘 시 | Status → "Done" |
| PR merged | PR 머지 시 | Status → "Done" |
### Step 4: .github-workflow.md 캐시 생성
```bash
REPO=$(gh repo view --json nameWithOwner -q '.nameWithOwner' 2>/dev/null)
if [ -n "$REPO" ]; then
DEFAULT_BRANCH=$(gh repo view --json defaultBranchRef -q '.defaultBranchRef.name')
MILESTONES=$(gh api repos/${REPO}/milestones --jq '.[] | " \(.title): \(.number)"' 2>/dev/null || echo " # 없음")
LABELS=$(gh label list --json name -q '.[].name' 2>/dev/null | sed 's/^/ - /' || echo " # 없음")
cat > .github-workflow.md << EOF
---
repository: ${REPO}
default_branch: ${DEFAULT_BRANCH}
milestones:
${MILESTONES}
labels:
${LABELS}
cached_at: $(date +%Y-%m-%d)
---
# GitHub Workflow Cache
GitHub API 호출을 줄이기 위한 캐시 파일입니다.
마일스톤/라벨 변경 시 이 파일을 갱신하세요.
EOF
echo "✅ 캐시 파일 생성"
fi
ls -la CLAUDE.md WORKFLOW.md .github-workflow.md
## 워크플로우 설정 완료
### 생성/업데이트된 파일
- [x] CLAUDE.md - 워크플로우 요약 + WORKFLOW.md 링크
- [x] WORKFLOW.md - 상세 워크플로우 가이드 (350+ 줄)
- [x] .github-workflow.md - GitHub 캐시 (저장소 설정 시)
### 사용 방법
Claude가 CLAUDE.md → WORKFLOW.md를 참조하여 자동으로 워크플로우를 따릅니다.
Guides creation, editing, and verification of skills for AI coding agents using test-driven development with subagent scenarios. Use when authoring or debugging skills.
npx claudepluginhub junsik/claude-plugins --plugin github-workflow