GitHub Superpowers: Claude Code에서 설계부터 PR까지 자동 추적하기

작성일: 2026년 2월 4일
카테고리: Claude Code, AI 개발 도구, 프로젝트 관리
키워드: GitHub Superpowers, Claude Code, Issue 자동화, Epic, TDD, Superpowers

요약

GitHub Superpowers는 Superpowers 워크플로우에 GitHub 프로젝트 관리를 통합한 Claude Code 플러그인이다. 설계 문서 작성 시 자동으로 Design Issue를 생성하고, 구현 계획의 Task들을 Epic Issue의 체크리스트로 변환하며, Task 완료 시 체크리스트를 자동 업데이트한다. 코드 작성뿐 아니라 프로젝트 추적까지 자동화하여, "이 커밋이 어떤 이슈였지?" 하고 히스토리를 뒤지는 일을 없앤다.

문제: AI는 코드만 작성한다

AI 코딩 어시스턴트의 일반적인 패턴은 다음과 같다:

요청 → 코드 작성 → 커밋 → (수동) 이슈 업데이트 → (수동) PR 생성

코드 작성은 자동화되었지만, 프로젝트 관리는 여전히 수동이다. GitHub Issue 업데이트를 잊어버리면 나중에 "이게 어떤 이슈랑 연결된 거였지?" 하며 커밋 히스토리를 뒤지게 된다.

Superpowers는 체계적인 개발 방법론(TDD, 브레인스토밍, 서브에이전트)을 제공하지만, GitHub 연동이 없다:

• 설계 문서는 로컬에만 존재
• 구현 진행 상황을 GitHub에서 추적 불가
• 커밋과 이슈의 연결이 수동

해결: GitHub Superpowers

GitHub Superpowers는 Superpowers 워크플로우의 각 단계를 GitHub Issue/PR과 자동 연결한다.

graph TB
    subgraph "Superpowers 워크플로우"
        A[요청]
        B[brainstorming]
        C[design.md]
        D[writing-plans]
        E[impl.md]
        F[creating-issues]
        G[executing-plans]
        H[verification]
    end

    subgraph "GitHub 연동"
        I["Design Issue (#1)"]
        J["Epic Issue (#2)"]
        K[Task 체크리스트]
        L["PR (#3)"]
    end

    A --> B --> C
    C --> I
    C --> D --> E
    E --> F --> J
    J --> K
    F --> G
    G --> K
    G --> H --> L
    L --> I
    L --> J

    style A stroke:#2563eb,stroke-width:2px
    style C stroke:#16a34a,stroke-width:2px
    style E stroke:#16a34a,stroke-width:2px
    style I stroke:#ea580c,stroke-width:2px
    style J stroke:#ea580c,stroke-width:2px
    style L stroke:#dc2626,stroke-width:2px

핵심 자동화

트리거	자동 동작
design.md 저장	Design Issue 생성 + 문서에 Issue 링크 삽입
impl.md 저장	Epic Issue 생성 + Task 체크리스트 변환
Task 완료	Epic 체크리스트 자동 체크
커밋 생성	커밋 메시지에 Issue 참조 자동 추가
PR 생성	Closes #epic, Closes #design 자동 삽입

기능 상세

1. Design Issue 자동 생성

brainstorming 스킬로 설계를 완료하면 design.md가 생성된다. 이때 GitHub에 Design Issue가 자동 생성되고, 문서에 Issue 링크가 삽입된다.

<!-- docs/plans/2026-02-04-user-auth-design.md -->
# User Authentication Design

> GitHub Issue: #42

## Overview
JWT 기반 인증 시스템 설계...

Design Issue는 design 라벨이 자동 부착되어 설계 문서와 구현을 추적할 수 있다.

2. Epic Issue와 Task 체크리스트

impl.md 작성 후 creating-issues 스킬이 자동 실행되어 Epic Issue를 생성한다.

<!-- GitHub Issue #43 -->
# [Epic] User Authentication

## Tasks
- [ ] Task 1: Setup auth module structure
- [ ] Task 2: Implement JWT service
- [ ] Task 3: Create login endpoint
- [ ] Task 4: Add refresh token logic

Closes #42  <!-- Design Issue 참조 -->

Epic Issue는 일반 Issue와 다르게 여러 Task를 체크리스트로 관리한다. 호텔의 체크아웃 목록처럼, 모든 항목이 체크되어야 완료된다.

3. 진행 상황 실시간 추적

executing-plans 스킬로 각 Task를 TDD 방식으로 구현할 때마다 Epic Issue의 체크리스트가 자동 업데이트된다.

<!-- Task 2 완료 후 Epic #43 상태 -->
- [x] Task 1: Setup auth module structure
- [x] Task 2: Implement JWT service
- [ ] Task 3: Create login endpoint
- [ ] Task 4: Add refresh token logic

GitHub Issue 페이지에서 프로젝트 진행 상황을 실시간으로 확인할 수 있다.

4. 스택별 패턴

프로젝트 기술 스택에 맞는 best practices 스킬을 제공한다:

스킬	스택	포함 패턴
nextjs-frontend	Next.js	FSD 아키텍처, Zustand, React Query, shadcn/ui
nestjs-backend	NestJS	Hexagonal Architecture, UseCase 패턴, BullMQ
fastapi-backend	FastAPI	Celery, Async 패턴

설치

# 마켓플레이스 추가
/plugin marketplace add junsik/github-superpowers

# 플러그인 설치
/plugin install github-superpowers@github-superpowers-marketplace

초기 설정

/init-github-superpowers

초기 설정 명령어가 수행하는 작업:

• GitHub Labels 생성 (design, epic)
• GitHub Project 생성 (커스텀 필드 포함)
• .github/github-superpowers.json 설정 파일 생성

실제 사용 흐름

1단계: 기능 요청

"사용자 인증 기능을 추가해줘"

Claude가 brainstorming 스킬을 자동 발동하여 소크라테스식 질문을 시작한다:

질문 1: 인증 방식은 JWT vs Session 중 어떤 것을 선호하시나요?
질문 2: OAuth 소셜 로그인이 필요한가요?
질문 3: 2FA가 필요한가요?

2단계: 설계 완료

설계 완료:
- 저장: docs/plans/2026-02-04-user-auth-design.md
- GitHub Issue: #42 (design label)

3단계: 구현 계획

impl.md 작성 완료:
- 저장: docs/plans/2026-02-04-user-auth-impl.md
- GitHub Epic: #43 (4개 Task 체크리스트)

4단계: TDD 구현

Task 1 완료: Setup auth module structure
- 테스트 통과: 3/3
- Epic #43 체크리스트 업데이트 완료

5단계: PR 생성

PR #44 생성 완료
- Title: feat: implement user authentication
- Closes #43, Closes #42

PR이 머지되면 Epic Issue와 Design Issue가 자동으로 Close된다.

워크플로우 원칙

GitHub Superpowers는 다음 원칙을 따른다:

원칙	설명
Test-Driven Development	테스트 먼저, 항상
GitHub as Source of Truth	GitHub Issue로 진행 상태 추적
자동화된 연결	설계 → 구현 → GitHub 자동 연동
Evidence over Claims	성공 선언 전 검증

교훈

1. 프로젝트 관리도 자동화 대상이다

AI 코딩 어시스턴트가 코드만 작성하고 프로젝트 관리는 수동으로 남기면, 시간이 지날수록 "이 코드가 어떤 요구사항이었지?"를 추적하기 어려워진다. 코드와 이슈의 연결을 자동화하면 이 문제가 사라진다.

2. Epic 패턴은 복잡한 기능에 효과적이다

단일 Issue로 관리하기 어려운 기능은 Epic Issue + Task 체크리스트 패턴이 효과적이다. 전체 진행 상황을 한눈에 파악할 수 있고, 각 Task의 완료 여부를 추적할 수 있다.

3. 설계 문서와 구현의 연결이 중요하다

설계 문서가 로컬에만 있으면 "이 설계가 어디에 구현되었지?"를 추적하기 어렵다. Design Issue로 설계를 GitHub에 기록하고, Epic Issue에서 참조하면 설계 → 구현 → 완료의 전체 흐름을 추적할 수 있다.

참고 자료

관련 블로그

• Superpowers 플러그인: Claude Code를 체계적인 개발 파트너로 만드는 방법
• Claude Code GitHub 통합 워크플로우: 200k Context에서 대규모 프로젝트 관리하기

공식 자료

• Superpowers GitHub 저장소
• GitHub Superpowers 저장소