GSD 실전 가이드

서론

이전 글에서 GSD의 핵심 원리인 컨텍스트 엔지니어링, 서브 에이전트 오케스트레이션, 목표 역추적 계획, 원자적 커밋에 대해 깊이 알아보았습니다. 이런 개념들은 우아하게 들리지만, "원리를 이해하는 것"에서 "실제로 프로젝트를 완성하는 것" 사이에는 적지 않은 운영 세부 사항이 있습니다.

이번 글에서는 직접 실습해 보겠습니다. GSD의 완전한 명령어 체계, 설정 옵션, 산출물 파일 구조, 그리고 처음부터 완전한 기능을 납품하는 방법을 배우게 됩니다.

설치 및 설정

설치

npx get-shit-done-cc@latest

설치 프로그램이 다음 사항을 선택하도록 안내합니다:

1. 런타임 — Claude Code, OpenCode, Gemini CLI 또는 전부
2. 위치 — 전역(모든 프로젝트) 또는 로컬(현재 프로젝트)

설치 후 런타임에서 /gsd:help를 입력하여 설치가 성공했는지 확인합니다.

권장: 권한 건너뛰기 모드

GSD는 무마찰 자동화를 위해 설계되었습니다. 다음과 같은 방법으로 Claude Code를 실행하는 것을 권장합니다:

claude --dangerously-skip-permissions

이 플래그를 사용하고 싶지 않다면 .claude/settings.json에서 세밀한 권한을 설정할 수 있습니다.

업데이트

/gsd:update

GSD는 매우 빈번하게 업데이트됩니다(TÂCHES는 거의 매일 15-20회 업데이트를 푸시합니다). 정기적으로 이 명령어를 실행하여 최신 버전을 유지하는 것을 권장합니다.

완전 명령어 참조

GSD의 모든 상호작용은 /gsd: 접두사가 붙은 슬래시 명령어로 이루어집니다. 아래에 기능별로 분류하여 전체 명령어를 나열합니다.

핵심 워크플로우 명령어

이 다섯 가지 명령어가 GSD의 메인 루프를 구성하며, 순서대로 사용합니다.

[N]은 선택적 매개변수를 나타냅니다. 생략하면 시스템이 자동으로 현재 단계를 감지합니다. <N>은 필수 매개변수를 나타냅니다.

마일스톤 관리

단계 관리

Quick Mode 및 도구

세션 및 설정 관리

설정 상세

모델 설정

GSD는 세 가지 모델 설정을 지원하며, /gsd:set-profile로 전환합니다:

핵심 설정

/gsd:settings를 통해 다음 설정을 확인하고 수정할 수 있습니다:

워크플로우 스위치

다음 에이전트는 개별적으로 켜고 끌 수 있으며, 속도와 품질 사이에서 균형을 맞출 수 있습니다:

research와 plan_check를 끄면 속도를 크게 높일 수 있지만, 계획 품질이 낮아질 수 있습니다. 프로젝트에 익숙해진 후에 끄는 것을 고려하는 것이 좋습니다.

산출물 파일 구조

GSD의 모든 상태와 산출물은 .planning/ 디렉토리에 저장됩니다. 이 구조를 이해하면 디버깅과 수동 개입에 도움이 됩니다.

프로젝트 레벨 파일

단계 레벨 파일

각 단계는 다음 파일을 생성합니다 (단계 1을 예로 들면):

디렉토리 구조 예시

.planning/
├── PROJECT.md
├── REQUIREMENTS.md
├── ROADMAP.md
├── STATE.md
├── research/
│   ├── tech-stack.md
│   ├── features.md
│   ├── architecture.md
│   └── pitfalls.md
├── 01-CONTEXT.md
├── 01-RESEARCH.md
├── 01-01-PLAN.md
├── 01-02-PLAN.md
├── 01-01-SUMMARY.md
├── 01-02-SUMMARY.md
├── 01-VERIFICATION.md
├── 01-UAT.md
├── 02-CONTEXT.md
├── 02-RESEARCH.md
├── 02-01-PLAN.md
│   ...
└── todos.md

실전 워크플로우 시연

아래에서는 "블로그 시스템에 댓글 기능 추가"를 예로 들어 초기화부터 납품까지의 전체 흐름을 시연합니다.

Step 1: 프로젝트 초기화

/gsd:new-project

시스템이 계속 질문을 시작합니다:

> 무엇을 구축하고 싶으신가요?
"Next.js 블로그에 댓글 기능을 추가하고 싶습니다. 익명 및 로그인 댓글,
 Markdown 렌더링, 관리자 대시보드를 지원합니다. 기술 스택은 Prisma + PostgreSQL입니다."

설명이 상세할수록 시스템의 추가 질문이 줄어듭니다. TÂCHES의 조언은 다음과 같습니다: 원하는 것을 설명하는 대략적인 비전 문서를 준비하세요 -- 기술 세부 사항을 알 필요는 없습니다.

시스템이 완료되면 네 개의 파일을 산출하고 로드맵 승인을 요청합니다. 승인 후 구축 단계에 진입합니다.

기존 코드베이스가 있으신가요? 먼저 /gsd:map-codebase를 실행하세요. 시스템이 기존 아키텍처와 관례를 분석하며, 이후 new-project가 기존 코드를 기반으로 계획을 수립할 수 있습니다.

Step 2: 논의 단계

/gsd:discuss-phase 1

시스템이 모호한 부분을 식별하고 하나씩 질문합니다:

> 댓글 중첩 수준: 다단계 중첩을 지원할까요, 아니면 1단계 답글만 지원할까요?
> 익명 댓글: 인증 코드가 필요한가요, 아니면 바로 제출할 수 있나요?
> 관리자 대시보드: 일괄 작업이 필요한가요, 아니면 건별 심사인가요?

여기서의 모든 결정이 후속 계획 품질에 직접적으로 영향을 미칩니다. 확실하지 않으면 시스템에게 기본값을 사용하도록 할 수 있지만, 심층적인 논의를 통해 실행 단계에서의 재작업을 크게 줄일 수 있습니다.

Step 3: 계획 단계

/gsd:plan-phase 1

시스템이 수행하는 작업:

1. Prisma + PostgreSQL로 댓글 시스템을 구현하는 방법을 조사합니다
2. 2-3개의 원자적 작업 계획을 생성합니다 (예: 데이터 모델, API 라우트, 프론트엔드 컴포넌트)
3. 계획이 모든 요구사항을 충족하는지 자동 검증합니다

각 계획은 충분히 작아서 완전히 새로운 컨텍스트 윈도우에서 완료할 수 있습니다.

Step 4: 실행 단계

/gsd:execute-phase 1

시스템이 웨이브 단위로 실행을 시작합니다:

• Wave 1 (의존성 없음): 데이터베이스 스키마, Prisma 모델 -- 병렬 실행
• Wave 2 (Wave 1에 의존): API 라우트, 댓글 CRUD -- 병렬 실행
• Wave 3 (Wave 2에 의존): 프론트엔드 댓글 컴포넌트 -- 독립 실행

각 작업은 완전히 새로운 200k tokens 컨텍스트에서 실행되며, 완료 후 독립적으로 git commit됩니다.

Step 5: 검증 단계

/gsd:verify-work 1

시스템이 하나씩 확인하도록 안내합니다:

> ✅ 데이터베이스 테이블이 생성되었습니다
> ✅ API 라우트가 올바른 상태 코드를 반환합니다
> ❓ 블로그 게시물 하단에 댓글 입력란이 보이시나요? [예/아니오/문제 설명]
> ❓ 댓글 제출 후 페이지가 실시간으로 업데이트되나요? [예/아니오/문제 설명]

실패한 항목이 있으면 시스템이 자동으로 진단하고 수정 계획을 생성합니다. /gsd:execute-phase 1을 다시 실행하면 수정이 실행됩니다.

일반적인 운영 시나리오

긴급 단계 삽입: 요구사항이 변경되어 현재 단계 앞에 새 작업을 삽입해야 합니다.

/gsd:insert-phase 2

이후 단계는 자동으로 번호가 재할당됩니다 (기존 Phase 2가 Phase 3이 되고, 이후도 마찬가지입니다).

일시 중지 및 재개: 다른 일을 처리하기 위해 작업을 중단해야 합니다.

/gsd:pause-work    # 현재 상태를 저장합니다
# ... 다른 일을 처리합니다 ...
/gsd:resume-work   # 마지막으로 중단된 위치로 복원합니다

불만족스러운 결과 롤백:

git reset --hard HEAD~3    # 실행 전 상태로 되돌아갑니다

/gsd:remove-phase 2        # 해당 단계의 모든 산출물 파일을 연쇄적으로 삭제합니다

TÂCHES는 라이브 스트리밍에서 이 작업을 여러 번 시연했습니다 -- 마음에 들지 않으면 롤백하고, 깔끔하게 처리합니다.

디버그 워크플로우

검증에서 문제가 발견되거나 개발 과정에서 버그를 만났을 때, GSD는 전용 디버그 프로세스를 제공합니다.

/gsd:debug 댓글 제출 후 페이지가 실시간으로 업데이트되지 않습니다

시스템이 격리된 디버그 서브 에이전트를 시작하며, 다음과 같은 워크플로우를 따릅니다:

1. 가설 수립 — 문제 설명을 기반으로 여러 가능한 근본 원인 가설을 생성합니다
2. 증거 수집 — 가설을 하나씩 검증하고, 코드, 로그, 네트워크 요청을 확인합니다
3. 해결 — 근본 원인을 파악한 후 수정 방안을 생성합니다

핵심 특성:

• 컨텍스트 격리: 디버그 에이전트는 자체 컨텍스트 윈도우를 가지며, 메인 개발 컨텍스트를 오염시키지 않습니다
• 문서 추적: 전체 조사 과정을 기록하는 독립적인 디버그 문서를 생성합니다
• 수정 계획: 진단이 완료되면 바로 실행할 수 있는 수정 계획을 산출합니다

이것은 메인 컨텍스트에서 직접 디버깅하는 것보다 훨씬 효율적입니다 -- 디버그 정보가 메인 윈도우에 축적되지 않습니다.

실전 경험

TÂCHES의 라이브 스트리밍과 Chase AI의 사용 경험을 종합하여 다음과 같은 실전 조언을 드립니다.

천천히 해야 빨라집니다

TÂCHES는 초기에 GSD를 사용할 때 "빨리빨리빨리"라는 마인드셋이었다고 솔직히 말했지만, 나중에 조사와 논의 단계에 더 많은 시간을 투자하면 실행 단계에서의 재작업이 오히려 줄어든다는 것을 발견했습니다. 새 버전의 GSD에 research-project와 define-requirements 단계가 추가된 것은 바로 실행에 들어가기 전에 방향을 올바르게 잡기 위해서입니다.

"I was definitely when I first started doing things with GSD, I was very much like move fast, move fast, move fast. But I'm just finding that taking these extra steps... I think you're going to really really love to see the results."

—— TÂCHES

단계 사이에 컨텍스트를 정리합니다

TÂCHES의 습관은 각 단계 사이에 clear를 실행하여 메인 컨텍스트를 간결하게 유지하는 것입니다. 그는 Warp 터미널을 사용하며, 각 윈도우를 전체 화면(Command+Shift+Enter)으로 설정하고, 한 윈도우에서 현재 단계를 실행하는 동시에 다른 윈도우에서 다음 단계를 조사합니다.

Token 비용의 절충

GSD의 서브 에이전트 방식은 확실히 Claude Code를 직접 사용하는 것보다 더 많은 token을 소비합니다. 하지만 Chase AI는 강력한 논거를 제시했습니다: "plan twice, prompt once"(두 번 계획하고 한 번 프롬프트)가 "한 번 프롬프트하고 계속 수정"하는 것보다 장기적으로 더 token을 절약합니다. 새로운 컨텍스트에서 한 번에 올바르게 수행하는 것이, 퇴화된 컨텍스트에서 반복적으로 수정하는 것보다 훨씬 효율적이기 때문입니다.

불만족스러울 때의 처리

어떤 단계의 결과가 만족스럽지 않다면, git reset --hard를 실행한 후 /gsd:remove-phase로 해당 단계의 모든 산출물 파일을 연쇄적으로 삭제할 수 있습니다. TÂCHES는 라이브 스트리밍에서 이 작업을 실제로 시연했습니다 -- 어떤 시각적 효과가 마음에 들지 않으면 만족스러운 이전 상태로 바로 롤백하고, 깔끔하게 처리합니다.

To-Do 시스템

/gsd:add-todo로 언제든지 아이디어를 할 일 목록에 기록할 수 있으며, 로드맵을 수정할 필요가 없습니다. 이러한 아이디어는 /gsd:discuss-milestone 시에 꺼내어 다음 마일스톤의 입력으로 활용할 수 있습니다. TÂCHES의 전략은 "먼저 기능을 구현하고, milestone 2에서 UI를 다듬는 것"입니다.

자주 묻는 질문과 모범 사례

모범 사례

상세한 초기 설명을 제공하세요. /gsd:new-project의 품질은 여러분의 입력 품질에 달려 있습니다. 대략적인 비전 문서를 준비하세요 -- 목표, 사용자, 핵심 기능, 알려진 제약을 설명합니다. 설명이 정확할수록 시스템의 추가 질문이 줄어들고 계획이 더 정확해집니다.

단계 사이에 컨텍스트를 정리하세요. 각 단계를 완료한 후 clear 또는 /compact를 실행하여 메인 컨텍스트 윈도우를 간결하게 유지합니다. TÂCHES의 습관은 메인 컨텍스트를 30-40% 수준으로 유지하는 것입니다.

먼저 Quick Mode로 테스트하세요. 확실하지 않은 작은 기능의 경우, 먼저 /gsd:quick으로 시험해 보세요. 효과가 좋으면 정식 로드맵에 포함시킵니다.

기존 프로젝트에는 먼저 map-codebase를 실행하세요. 기존 코드베이스에서 GSD를 사용하기 전에 먼저 /gsd:map-codebase를 실행하세요. 시스템이 기술 스택, 아키텍처, 관례를 분석하며, 이후의 계획이 기존 코드에 더 적합하게 됩니다.

FAQ

Q: GSD는 어떤 런타임을 지원하나요?

A: Claude Code, OpenCode, Gemini CLI입니다. 설치 시 개별 또는 전부를 선택할 수 있습니다.

Q: Quick Mode와 전체 모드의 차이점은 무엇인가요?

A: Quick Mode는 GSD의 기본 보장(원자적 커밋, 상태 추적)을 제공하지만, 조사, 계획 검증, 검증 단계를 건너뜁니다. 버그 수정, 작은 기능, 설정 변경 등 완전한 계획이 필요하지 않은 작업에 적합합니다.

Q: 실행 중에 일시 중지할 수 있나요?

A: 가능합니다. /gsd:pause-work가 현재 상태를 STATE.md에 저장합니다. 다음에 /gsd:resume-work를 실행하면 시스템이 마지막으로 중단된 위치에서 계속합니다.

Q: token 비용을 어떻게 제어하나요?

A: 세 가지 방법이 있습니다 -- (1) budget 설정으로 전환: /gsd:set-profile budget; (2) research 또는 plan_check 에이전트 끄기; (3) 간단한 작업에 /gsd:quick 사용.

Q: GSD를 Ralph과 함께 사용할 수 있나요?

A: 가능합니다. GSD와 Ralph은 서로 다른 문제를 해결합니다 -- GSD는 계획과 구조화된 실행을 담당하고, Ralph은 자율 순환 실행을 담당합니다. GSD의 new-project와 plan-phase로 완전한 계획을 생성한 후, 인간의 개입이 필요 없는 단계에 대해 Ralph 순환을 사용하여 실행할 수 있습니다.

Q: 다중 협업은 어떻게 하나요?

A: .planning/ 디렉토리를 Git에 커밋할 수 있습니다. 여러 사람이 각자 다른 단계를 실행하고 Git으로 결과를 병합할 수 있습니다. 다만 동일한 단계를 동시에 실행하는 것은 피하는 것이 좋습니다.

요약

GSD의 핵심 가치는 복잡성을 시스템 안에 숨기고, 사용자에게는 단순함을 남기는 것입니다. 몇 가지 명령어만 있으면 됩니다 -- new-project, discuss-phase, plan-phase, execute-phase, verify-work -- 시스템이 뒤에서 모든 컨텍스트 관리, 서브 에이전트 오케스트레이션, 품질 검증을 처리합니다.

설치부터 납품까지, GSD는 명확한 경로를 제공합니다: 원하는 것을 설명 -> 구현 세부 사항 논의 -> 원자적 계획 생성 -> 병렬 실행 -> 산출물 검증. 매 단계마다 여러분이 개입할 기회가 있고, 매 단계마다 파일로 기록됩니다.

이것은 "버튼 하나를 누르면 끝"이라는 마법이 아닙니다. 이것은 여러분의 참여가 필요하지만 대부분의 인지 부담을 대신 져주는 시스템입니다. TÂCHES가 말했듯이: 여러분은 고위 프로젝트 매니저이고, GSD는 여러분의 실행 팀입니다.

추가 읽을거리:

• GSD 심층 분석 — 핵심 원리, 워크플로우와 기술 아키텍처
• Ralph Wiggum 심층 분석 — Context Rot과 Ralph 방법론
• snarktank/ralph 실전 가이드 — Ralph의 설치, PRD 작성과 실전
• 규격 주도 개발이란 — Vibe Coding에서 규격 주도 개발로의 패러다임 전환
• Speckit 실전 가이드 — Speckit 명령어 상세와 완전한 사례