GitHub 워크플로우 설정 | github-workflow

Stats

Actions

Tags

GitHub 워크플로우 설정 | github-workflow

GitHub 워크플로우 설정

프로젝트에 GitHub 기반 개발 워크플로우를 설정합니다.

사용법

/setup                    # 현재 프로젝트에 워크플로우 설정
/setup --force            # 기존 파일 덮어쓰기

워크플로우

Step 1: 현재 상태 확인

ls -la CLAUDE.md WORKFLOW.md .github-workflow.md 2>/dev/null
gh repo view --json nameWithOwner -q '.nameWithOwner' 2>/dev/null || echo "GitHub 저장소 미설정"

Step 2: CLAUDE.md 업데이트

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로 조회

Step 3: WORKFLOW.md 생성

상세 워크플로우 가이드 생성:

# 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

1.2 설계 문서 확인

# 설계 문서 구조 파악
find docs/ -name "*.md" -type f

# 관련 문서 읽기
cat docs/{relevant-doc}.md

2. Plan Mode에서 계획 수립

2.1 컨텍스트 수집

필수 확인 사항:

GitHub 이슈 상세 (있으면)
설계 문서 참조
기존 코드베이스 패턴
CLAUDE.md 개발 지침

# 이슈 상세 조회
gh issue view <number> --json number,title,labels,state,body,milestone

# 이슈 본문에서 추출:
# - 설계 문서 참조 (GitHub URL → 로컬 경로 변환)
# - Acceptance Criteria
# - Blocked by (의존성)

2.2 이슈 본문의 설계 문서 링크 변환

https://github.com/{owner}/{repo}/blob/main/docs/auth.md
→ docs/auth.md

2.3 계획에 포함할 내용

# 구현 계획: {제목}

## 개요
- 이슈: #{number} (있으면)
- 설계 문서: docs/{path}

## 컨텍스트 분석
- 설계 문서 요약
- 기존 코드 패턴

## 구현 Task
### Task 1: {task}
- [ ] 세부 작업

### Task 2: {task}
- [ ] 세부 작업

## 검증 체크리스트
- [ ] Acceptance Criteria 충족
- [ ] 설계 문서 스펙 준수
- [ ] 테스트 통과
- [ ] 빌드 성공

3. GitHub 이슈 생성

3.1 이슈가 없을 때 새로 생성

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 발생)

3.2 이슈를 프로젝트에 연결 + 필드 설정

이슈 생성 후 프로젝트에 추가하고 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 호출 생략

3.3 이슈 본문 템플릿

## 설명
{구현할 내용}

## 📚 설계 문서 참조
- [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} {선행 이슈 제목}

4. 구현 실행

4.1 이슈 상태 업데이트

# 작업 시작 시
gh issue edit <number> --add-label "in-progress"

4.2 도메인별 구현 가이드

도메인	파일 패턴	가이드라인
Frontend	`src/components/`, `.tsx`	React/Next.js, 접근성, 반응형
Backend	`src/routers/`, `.py`	FastAPI, SQLAlchemy, Pydantic
공통	`src/lib/`, `src/utils/`	재사용 가능한 로직

4.3 병렬 실행 (Task tool)

독립 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 실행

4.4 검증

# Frontend
pnpm build && pnpm lint && pnpm test

# Backend
uv run pytest && uv run ruff check .

5. 커밋

5.1 커밋 메시지 형식

feat(scope): 기능 설명

- 변경 사항 1
- 변경 사항 2

Closes #<number>

Prefix 규칙:

feat: 새 기능
fix: 버그 수정
refactor: 리팩토링
docs: 문서
test: 테스트
chore: 기타

5.2 이슈 자동 Close 키워드

커밋 메시지에 포함 시 자동 Close:

Closes #N
Fixes #N
Resolves #N

6. 이슈 Close

6.1 완료 코멘트 작성

gh 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 구현"

6.2 이슈 상태 업데이트

# in-progress 라벨 제거 (Close 시 자동 처리되기도 함)
gh issue edit <number> --remove-label "in-progress"

7. 마일스톤 관리

7.1 마일스톤 이슈 목록

gh issue list --milestone "v1.0" --state open --json number,title,labels

7.2 의존성 분석

이슈 본문의 Blocked by 파싱하여 실행 순서 결정:

의존성 없는 이슈 먼저
의존성 해결된 이슈 순차 실행

7.3 마일스톤 완료

# 모든 이슈 완료 확인
gh issue list --milestone "v1.0" --state open

# 마일스톤 닫기
gh api repos/{owner}/{repo}/milestones/{number} -X PATCH -f state=closed

8. 프로젝트/마일스톤 생성 (초기 설정)

8.1 프로젝트 생성

# 프로젝트 생성
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"

8.2 마일스톤 생성

gh api repos/{owner}/{repo}/milestones \
  -f title="v1.0" \
  -f description="첫 번째 릴리스" \
  -f due_on="2024-03-01T00:00:00Z"

8.3 라벨 생성

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"

8.4 이슈를 프로젝트에 추가

# 이슈 생성 후 프로젝트에 추가
ISSUE_URL=$(gh issue create --title "..." --body "..." | tail -1)
gh project item-add <project-number> --owner "@me" --url "$ISSUE_URL"

캐시 파일 (.github-workflow.md)

형식

---
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'

검증 체크리스트

구현 완료 전 확인:

GitHub Projects Workflows 설정 (권장)

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

Step 5: 결과 확인

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를 참조하여 자동으로 워크플로우를 따릅니다.