GitHub Spec Kit을 사용하여 동일한 사양의 여러 구현 빌드 | Den Delimarsky

분야 AI 일반
, ,
1

#SpecKit 병렬개발 #Git워크트리 #웹개발 #정적사이트생성

핵심 요약

SpecKit의 병렬 구현 기능을 활용하면 하나의 스펙에서 여러 구현 버전을 동시에 개발하고 비교할 수 있습니다. **Git 워크트리(work tree)**를 사용하여 같은 저장소에서 독립적인 브랜치를 별도 폴더로 관리하면서 UI 필터 기능의 다양한 구현 방식(체크박스 vs 토글 버튼)을 동시에 테스트하고 최적의 솔루션을 선택할 수 있습니다. 이 방식은 기존 프로젝트에 새로운 기능을 추가할 때 특히 효과적이며, 실제 Hawaii Diff 프로젝트(하와이 망원경 카메라 뷰 통합 사이트)를 통해 실용적인 워크플로우를 보여줍니다.

SpecKit를 활용한 병렬 구현 워크플로우 가이드

프로젝트 배경: Hawaii Diff

Hawaii Diff는 하와이 빅 아일랜드의 Mauna Kea 관측소에 있는 웹캠 뷰를 통합하는 정적 웹사이트입니다.

기존 문제점

  • 하와이 대학교 힐로 캠퍼스의 Mauna Kea 기상 센터에서 제공하는 여러 웹캠 뷰가 일관성 없는 페이지로 분산되어 있음

  • 다른 카메라 뷰를 보려면 여러 페이지를 넘나들어야 하는 불편함

  • 네비게이션이 어렵고 원하는 방식으로 브라우징하기 힘듦

Hawaii Diff의 솔루션

  • 모든 이미지를 GitHub에 수집하고 통합

  • Hugo를 사용한 정적 사이트 생성으로 현대적인 프론트엔드 제공

  • 헤더 축소, 이전 스냅샷 등의 기능이 정적으로 생성됨

  • WEBP 이미지 포맷 사용으로 성능 최적화 및 저장소 용량 절약

  • GitHub 저장소에 각 망원경/관측소별 폴더 구조로 이미지 저장

새로운 기능 요구사항: 필터 기능 추가

현재 상태의 문제

  • 여러 카메라를 보려면 스크롤을 계속 해야 함

  • 각 카메라를 하나씩 확인해야 하는 비효율적인 방식

원하는 기능

  • 페이지 상단에 필터 기능 추가

  • 이름으로 필터링 가능

  • 방향(direction)으로 필터링 가능

  • 방향 예시: east, northwest, southeast, up, hilo, variable 등

  • Mauna Kea 기상 센터에서 제공하는 방향 표시를 그대로 사용

SpecKit을 활용한 구현 프로세스

1단계: 스펙 생성


speckit specify

프롬프트 입력:


I want to build a filter on the main landing page

that will allow me to search existing telescopes

and allow me to filter by direction.

  • 자동으로 새 브랜치 생성

  • 헬퍼 스크립트가 새 기능을 위한 환경 설정

  • Pull Request 자동 생성

2단계: 스펙 검토

생성된 spec.md 파일 확인:

사용자 설명: 특정 망원경 카메라를 빠르게 찾기

기능 요구사항:

  • 텍스트 검색 입력 제공 필수

  • 실시간으로 카메라 필터링

  • 대소문자 구분 없는 검색

3단계: SpecKit 워크플로우 완료

SpecKit이 자동으로 처리하는 단계:

  1. 명확화(Clarification) - 요구사항 구체화

  2. 계획 수립(Planning) - 구현 계획 작성

  3. 작업 분석(Task Analysis) - 세부 작업 분해

  4. 구현(Implementation) - 실제 코드 작성

생성된 아티팩트:

  • plan.md - 구현 계획서

  • quickstart.md - 빠른 시작 가이드

  • research.md - 리서치 문서

  • spec.md - 스펙 문서

  • tasks.md - 작업 목록

4단계: 작업 구조 확인

단계별 접근 방식:

Phase: Setup

  • Hugo 빌드 검증

  • 사이트 동작 확인

  • 필터 전용 스캐폴딩

기존 프로젝트 vs 새 프로젝트 차이점:

  • 새 프로젝트: Hugo 사이트 초기화, 기본 URL 설정, 테마 설정 등 광범위한 설정

  • 기존 프로젝트: 필요한 검증만 수행하고 새 기능에 집중

User Story for MVP:

  • 검색 기능

  • 필터 기능

  • 기타 핵심 기능들

병렬 구현 워크플로우: Git 워크트리 활용

명확화 단계에서의 선택 사항

clarify.md 파일에서 중요한 결정:

질문: 매칭 결과가 없을 때 카메라 그리드 영역에 무엇을 표시할까?

답변: “Clear all filters” 옵션이 있는 중앙 메시지

질문: 사용자가 방향 필터와 어떻게 상호작용해야 할까?

답변: 내부에 체크박스가 있는 드롭다운 메뉴

대안 구현 탐색의 필요성

체크박스가 있는 드롭다운이 한 가지 접근 방식이지만, 다른 대안들도 탐색하고 싶은 상황입니다.

Git 워크트리 사용법

기본 명령어:


git worktree add -b <new-branch-name> <folder-path> <source-branch>

실제 예시:


git worktree add -b filter-alt ./hawaiidiff-filter-alt 002-I12

효과:

  • 새 브랜치 생성: filter-alt

  • 별도 폴더에 체크아웃: hawaiidiff-filter-alt

  • 원본 브랜치: 002-I12에서 분기

  • 같은 저장소에 연결: 워크트리로 관리됨

Git 워크트리의 장점

기존 방식의 문제점:

  • 폴더를 복사해서 이동

  • 앞뒤로 네비게이션

  • Git 클라이언트가 혼란스러워함

  • 같은 저장소를 여러 번 열어야 함

  • 다르게 이름을 지정해야 함

워크트리 방식의 이점:

  • 같은 워크트리에 연결된 다른 폴더와 브랜치

  • Git 클라이언트(GitHub Desktop)에서 명확하게 구분

  • 깔끔한 관리

  • 효율적인 워크플로우

병렬 구현 실행

첫 번째 구현 (원본):

  • 브랜치: 002-I12

  • 폴더: hawaiidiff

  • 필터 방식: 체크박스가 있는 드롭다운


speckit implement

두 번째 구현 (대안):

폴더 이동:


cd hawaiidiff-filter-alt

VS Code에서 폴더 열기 (두 개의 인스턴스를 나란히 배치)

스펙 수정 요청:


I want to update the filter spec in 002

to make sure that the filters are toggles,

not checkboxes and dropdown

SpecKit의 자동 처리:

  • spec.md 읽기

  • 올바른 참조 확인

  • 올바른 폴더 확인

  • 필요한 변경사항 적용

업데이트된 내용:

  • 명확화 항목 변경: 클릭하여 활성화/비활성화할 수 있는 pill/chip 형태의 토글 버튼

  • plan.md 자동 업데이트

  • data model 파일 업데이트

  • tasks.md 업데이트

명시적 요청:


let's update the tasks to make sure that they reflect the changes to the spec

두 구현 비교 및 테스트

Hugo 서버 실행

첫 번째 구현 (체크박스 버전):


cd hawaiidiff

hugo server
  • 포트: 57305

두 번째 구현 (토글 버전):


cd hawaiidiff-filter-alt

hugo server
  • 포트: 1313 (자동으로 사용 가능한 포트 선택)

브라우저에서 비교

체크박스 버전 (localhost:57305):

  • 텍스트 박스와 방향 드롭다운

  • “Yucca” 검색 가능

  • “East” 방향 필터링 가능

  • “Clear all filters” 기능

  • 필터 결과 없을 때: 박스 형태로 “No cameras match your filter” 메시지 표시

토글 버전 (localhost:1313):

  • 텍스트 박스와 방향 토글 버튼

  • “Yucca” 검색 가능

  • 버튼 클릭으로 필터링

  • 필터 결과 없을 때: 깔끔한 “No cameras match your filters clear all filters” 메시지

LLM의 다양한 구현 방식

같은 요구사항에 대해 LLM이 다른 방식으로 구현할 수 있음을 보여줍니다:

  • UI 레이아웃 차이

  • 메시지 표시 방식 차이

  • 스타일링 접근 방식 차이

확장 가능성

더 많은 병렬 구현

2개 이상의 구현 가능:

  • 큰 화면이 있다면 4개, 5개, 심지어 10개까지 가능

  • 각각 다른 워크트리 브랜치로 관리

  • 동시에 비교 및 테스트

자동화 가능성

현재 데모는 압축된 수동 프로세스이지만:

  • 단순한 프로젝트

  • 반복적인 작업

  • 수동 프로세스도 괜찮음

미래의 목표:

  • 자동화된 워크플로우

  • 터미널에서 수동으로 워크트리 명령어를 입력하는 대신 슬래시 명령어 사용

  • 더 부드러운 워크플로우로 실험 속도 향상

  • 더 빠른 이동 가능

SpecKit 업데이트: 브랜치 명명 개선

기존 문제점

  • 브랜치 이름이 비체계적: 예를 들어 002-I12

Pull Request를 통한 개선

  • 템플릿과 스크립트 업데이트

  • 가장 중요: create-new-feature 셸 스크립트 업데이트

새로운 기능:


# short_name 파라미터 추가

short_name="homepage-filter"

  • LLM이 짧은 이름을 생성하여 스크립트에 전달

  • 템플릿이 아닌 LLM이 자동으로 생성

  • 의미 있는 이름 사용: “I want to” 대신 “homepage-filter” 같은 이름

지원 플랫폼:

  • 셸 스크립트

  • PowerShell

실용적인 팁

Git 워크트리 활용

  • 병렬 구현이 필요할 때 Git 워크트리를 사용하면 구원받을 수 있음

  • 폴더 복사보다 훨씬 효율적

  • Git 클라이언트와의 통합이 원활함

기존 프로젝트 업그레이드

  • SpecKit은 신규 프로젝트뿐만 아니라 기존 프로젝트에도 효과적

  • 주말에 만든 프로젝트를 현대적인 프레임워크로 업그레이드

  • 모바일 앱에 기능 추가

  • SpecKit 채널에 기존 프로젝트 업그레이드 관련 동영상 있음

Hugo 빌드 최적화 아이디어

  • 현재: 모든 사진을 한 번에 패키징 (수백 개)

  • 개선 아이디어: 마지막 11개 사진만 사용

  • Cloudflare 호스팅 시 트래픽 비용 절감

환경 변수 설정

  • SpecKit은 환경 변수를 통한 활성 기능 브랜치 지정 지원

  • 새 터미널이 생성될 수 있으므로 명시적으로 지정하는 것이 좋음

주요 학습 포인트

SpecKit의 핵심 가치

  1. 스펙과 기술 세부사항의 분리

  2. 여러 변형 생성 가능

  3. 최선의 구현을 선택하여 메인 브랜치에 병합

  4. 기존 프로젝트에 기능 추가하는 부가적 워크플로우

병렬 개발의 이점

  • 다양한 UI/UX 옵션 탐색

  • 실시간 비교 테스트

  • 최적의 솔루션 선택

  • 빠른 반복 개발

Git 워크트리의 핵심

  • 같은 저장소, 다른 브랜치, 별도 폴더

  • 효율적인 병렬 작업

  • 깔끔한 Git 관리

향후 계획

SpecKit 업데이트

  • 더 많은 업데이트 예정

  • 더 많은 데모와 쇼케이스

  • 실제 사이드 프로젝트를 통한 데모

  • 사용자 피드백 반영

오픈소스 프로젝트

  • GitHub에 호스팅

  • 오픈소스

  • 무료로 사용 가능

  • 질문이나 피드백은 동영상 댓글이나 저장소의 토론에서 가능

Hawaii Diff 사이트

  • 동영상 공개 시점에는 라이브 사이트에서 선택된 필터 구현을 볼 수 있음

  • 지속적인 반복 개발 예정

1개의 좋아요