이 레포가 무엇을 하는 물건인가.
AI 코딩 에이전트는 똑똑한 신입과 같다. 시키면 코드를 쏟아내지만, 대화가 길어지면 점점 헛소리를 하고, 새 창을 열면 어제 합의한 내용을 다 잊는다. GSD는 그 신입에게 ① 무엇을 만들지 적은 스펙, ② 잡일을 대신 처리하는 비서 에이전트팀, ③ 결과를 반드시 검증하는 검수 라인을 붙여 준다. 그래서 "되긴 됐는데 믿을 수가 없는" 결과 대신 깨끗한 git 히스토리로 검증까지 끝난 작업이 나온다.
조금 더 정확히 말하면, GSD(Get Shit Done)는 Claude Code를 비롯한 15종 코딩 에이전트 위에 얹는 메타 프롬프트 · 컨텍스트 엔지니어링 · 스펙 주도 개발(spec-driven development) 시스템이다. 코드를 직접 짜는 새 AI가 아니라, 기존 에이전트가 일하는 "방식"을 통제하는 얇은 운영 레이어다. npx 한 줄로 설치하면 /gsd-* 형태의 명령(슬래시 커맨드 또는 스킬)이 깔리고, 그 명령들이 정해진 절차대로 하위 에이전트들을 부려 일을 시킨다.
핵심 한 줄은 README의 마지막 문장이 잘 요약한다 — "Claude Code는 강력하다. GSD는 그것을 신뢰할 수 있게 만든다(makes it reliable)." 즉 GSD의 정체성은 '더 똑똑한 AI'가 아니라 '규율과 절차'다.
트렌딩 이유 · 경쟁(SpecKit·Taskmaster 등) 대비 장점.
2025~2026년 "바이브 코딩"(느낌대로 시키는 AI 코딩)이 유행하면서 모두가 같은 한계를 만났다 — 긴 작업은 AI가 중간에 무너지고, 결과를 믿을 수 없다. 그래서 스펙 주도 개발 도구(GitHub spec-kit, OpenSpec, Taskmaster 등)가 쏟아졌는데, 실사용자들이 "이것들 다 써봤지만 GSD가 가장 결과가 좋았다"고 입을 모으면서 한 해 동안 ★ 6만 개 이상을 모았다. Amazon·Google·Shopify·Webflow 엔지니어들이 쓴다는 점도 신뢰를 더했다.
| 비교 항목 | 그냥 바이브 코딩 | GSD의 접근 |
|---|---|---|
| 맥락 관리 | 한 창에서 계속 → 품질 붕괴 | 무거운 일은 새 컨텍스트의 하위 에이전트에게 |
| 기억 | 창을 닫으면 리셋 | 파일(.planning/)에 영속 저장, 다음 세션이 읽음 |
| 검증 | "돌아가면 됐지" | 계획 검사 + 원자 커밋 + 검증 + 사람 UAT |
| 병렬성 | 한 번에 하나씩 | 의존성 없는 계획을 병렬 웨이브로 동시 실행 |
| 적용 범위 | 특정 도구 종속 | 설치기가 15종 런타임으로 변환 배포 |
AI에게 큰 기능을 통째로 시키면, 컨텍스트가 차면서 앞 결정을 잊고, 중간에 만든 가짜 함수를 호출하고, "테스트가 통과한다"고 거짓 보고를 한다. 사람이 일일이 다시 확인해야 하니 결국 시간이 더 든다.
큰일을 단계(phase)로 쪼개고, 각 계획은 깨끗한 200K 컨텍스트의 실행자가 처리하며, 작업마다 원자 커밋을 남기고, 끝나면 검증 에이전트가 목표 대비 결과를 대조한다. 사람은 마지막에 "진짜 동작하나"만 확인하면 된다.
또 하나 차별점은 "덜 보여주기"로 토큰을 아끼는 설계다. v1.40부터 86개 스킬을 한 번에 나열(약 2,150토큰)하는 대신 6개 네임스페이스 라우터(약 120토큰)만 모델에 노출하는 2단계 계층 라우팅을 도입했다. 매 턴 토큰을 깎는 이런 디테일이 "오버엔지니어링 없이 그냥 일이 된다"는 평가를 만든다.
트렌딩에 잡힌 원본 gsd-build/get-shit-done은 현재 README에 "이 저장소는 더 이상 활성 개발처가 아니다"라고 적고 후속 저장소를 가리킨다. 후속이라고 주장하는 저장소는 open-gsd/get-shit-done-redux로 분기 후 open-gsd/gsd-core로 이름 변경(두 레포가 아니라 하나의 레포가 리네임된 것)됐으며, 유지보수 팀은 "이전 상류(upstream)에 신뢰·소유권 문제와 밈코인 러그풀(meme-coin rug-pull) 사건이 얽혀 있었다"고 공개적으로 밝히며 갈라져 나왔다고 설명한다.
이건 코드 품질과 별개의 공급망·거버넌스 이슈다. 실제로 설치할 땐 어떤 npm 패키지(@opengsd/gsd-core)와 어떤 저장소를 신뢰할지 본인이 직접 확인해야 한다. 역설적이게도 GSD 자체가 "AI가 지어낸 가짜 패키지 설치"를 막는 기능을 핵심으로 내세우는데(§4 참고), 그 정신을 사용자에게도 똑같이 요구하는 셈이다.
"프롬프트 묶음"처럼 보이지만 실제로는 설치기·CLI·훅·테스트가 도는 소프트웨어다.
GSD의 흥미로운 점은 핵심 자산이 코드가 아니라 마크다운이라는 것이다. 에이전트·워크플로·명령은 전부 .md 프롬프트 파일이고, 그것을 각 런타임에 맞게 변환·배포·운영하는 "기계 장치" 부분만 JavaScript/TypeScript다. 그래서 언어 비중이 JS 73% · TS 26% · Shell 0.4%로 나오지만, 정작 제품의 영혼은 프롬프트 텍스트에 있다.
| 레이어 | 기술 | 역할 |
|---|---|---|
| 핵심 자산 | Markdown 프롬프트 (agents/·commands/·workflows/·references/) | 에이전트·명령·절차·공용 지식을 글로 정의. |
| 설치기 | Node.js + bin/install.js (~1만700줄) | 15종 런타임 감지 → 프롬프트를 각 포맷으로 변환 배포. |
| CLI 도구 | CommonJS gsd-tools.cjs + bin/lib/*.cjs | 상태·계획·로드맵·설정 파싱 등 결정적(deterministic) 잡일. |
| 라우팅 | command-routing-hub.cjs | 예외를 던지지 않고 {ok:false,...} 결과를 돌려주는 단일 디스패처. |
| 훅 | Node.js .js + Shell .sh (13종) | 상태줄·컨텍스트 경고·업데이트 체크·보안 가드. |
| 패키지 | npm @opengsd/gsd-core · @opengsd/gsd-sdk | 설치 진입점 + 프로그래밍용 SDK 디스패치. |
| 테스트 | Vitest (vitest.config.ts) + 사이즈 예산 테스트 | 워크플로/에이전트 파일 줄수 상한까지 자동 검사. |
| 릴리스 | Changesets (.changeset/) · CodeRabbit | 버전·체인지로그 관리, AI 코드리뷰. |
| 선택 의존 | slopcheck (pip) · fallow (Rust/npm) | 가짜 패키지 탐지 · 구조적 코드 리뷰 사전검사. |
.md 파일들이 전부 메타 프롬프트다. 요리로 치면 음식이 아니라 레시피와 주방 운영 매뉴얼을 쓰는 일..cjs(구식 require 방식)를 쓰는 건, 다양한 런타임/Node 버전에서 의존성 없이 확실히 도는 호환성을 노린 선택이다.먼저 5층 구조 한 장, 그다음 "새 기능 하나"가 흐르는 길을 끝까지 따라가 본다.
GSD의 핵심 구조는 "얇은 오케스트레이터가 깨끗한 에이전트를 부린다"로 요약된다. 사용자가 /gsd-* 명령을 치면, 명령은 워크플로(절차서)를 읽고, 워크플로는 직접 일하지 않고 전문 에이전트를 새 컨텍스트로 소환한다. 모든 상태는 데이터베이스가 아니라 프로젝트 폴더의 .planning/ 마크다운에 쌓이므로, 창을 닫아도(/clear) 기억이 살아남는다.
GSD의 사용 경험은 명령 6개로 압축된다. 각 명령은 "딱 한 가지"만 한다.
| 단계 | 명령 | 하는 일 |
|---|---|---|
| ① 초기화 | /gsd-new-project | 질문 → 리서치 → 요구사항 → 로드맵. (기존 코드면 /gsd-map-codebase 먼저) |
| ② 논의 | /gsd-discuss-phase 1 | 이 단계의 회색지대(레이아웃·API 모양·에러 처리)를 미리 결정. |
| ③ 계획 | /gsd-plan-phase 1 | 리서치 → 계획 → 검증 루프. 각 계획은 새 컨텍스트로 처리 가능한 크기로. |
| ④ 실행 | /gsd-execute-phase 1 | 계획을 병렬 웨이브로 실행, 작업마다 원자 커밋. |
| ⑤ 검증 | /gsd-verify-work 1 | 만들어진 것을 점검, 깨진 건 진단된 수정 계획으로. |
| ⑥ 배포 | /gsd-ship 1 | 검증된 단계로 PR 생성 → /gsd-complete-milestone로 마무리. |
가장 핵심인 execute-phase가 어떻게 도는지, 곁가지를 빼고 해피 패스만 따라가 보자.
여기서 이 프로젝트 특유의 "정상적인 모양새" 세 가지를 짚어두면 코드가 덜 낯설다. 첫째, 워크플로는 절대 직접 일하지 않는다 — 컨텍스트만 로드하고, 에이전트를 소환하고, 결과를 다음 단계로 넘긴다(얇은 오케스트레이터 원칙). 둘째, 설정이 없으면 켜진 것으로 본다(absent = enabled) — 사용자는 끄고 싶은 것만 명시한다. 셋째, 방어를 여러 겹 둔다 — 계획 검사·원자 커밋·실행 후 검증·사람 UAT가 차례로 거름망 역할을 한다.
--no-verify로 pre-commit 훅을 건너뛰고 웨이브 종료 후 1회만 돌리며, ② STATE.md 갱신은 O_EXCL 원자 생성 락파일로 상호배제한다(읽기-수정-쓰기 경쟁 방지)..planning/의 사람이 읽을 수 있는 마크다운/JSON에 둔다. 덕분에 ① 컨텍스트 리셋에도 살아남고, ② 사람과 에이전트가 똑같이 들여다보고, ③ git에 커밋해 팀이 공유할 수 있다.GSD에서 가장 영리한 보안 설계는 슬롭스쿼팅(slopsquatting) 방어다. AI는 존재하지 않는 패키지 이름을 그럴듯하게 지어내곤 하는데(AI가 추천한 패키지의 약 20%가 환각), 공격자가 그 이름을 미리 등록해 악성 설치 스크립트를 심어두면 "AI 추천 → 자동 npm install"의 자동화 경로가 통째로 뚫린다.
여기서 핵심은 npm view로 "등록되어 있음"을 확인하는 것만으로는 안전이 증명되지 않는다는 통찰이다. 그래서 웹 검색으로 알아낸 패키지는 결과와 무관하게 [ASSUMED]로 태깅되고, 설치 경계에서 반드시 사람 확인 체크포인트를 만든다. npm·pip·cargo 등 생태계별 검증 명령을 따로 쓰는 것도 디테일이다.
"코드 저장소"가 아니라 "프롬프트 + 그것을 배포하는 기계"의 구조.
저장소(gsd-build/get-shit-done)와 설치 후 내 컴퓨터(~/.claude/)의 구조를 나눠 보면 이해가 빠르다. 저장소의 agents/·commands/는 Claude Code 포맷의 원본 프롬프트이고, 설치기가 이를 각 런타임 포맷으로 변환해 배포한다.
| 경로 | 역할 |
|---|---|
agents/*.md | 리서처·플래너·실행자·검증자 등 33개 전문 에이전트의 역할·도구·색을 정의. |
get-shit-done/workflows/ | 각 /gsd-* 명령의 절차. 직접 일하지 않고 에이전트를 소환하는 얇은 오케스트레이터. |
get-shit-done/references/ | 게이트·체크포인트·모델 프로파일 등 61종 공용 지식. 워크플로·에이전트가 @로 참조. |
bin/install.js | 15종 런타임을 감지해 프롬프트를 각 포맷으로 변환·배포하는 약 1만700줄짜리 설치기. |
bin/lib/*.cjs | STATE.md·ROADMAP.md 파싱, 설정, 검증, 보안 등 결정적 잡일을 맡는 도메인 모듈. |
.planning/ (사용자 프로젝트) | 실제 작업 시 생기는 영속 상태: PROJECT/REQUIREMENTS/ROADMAP/STATE + phases/. |
이 레포에서 진짜 배울 만한 것 + 어느 파일을 보면 되는지.
메인 컨텍스트를 비워 두고 무거운 일을 새 컨텍스트의 하위 에이전트로 떠넘기는 발상, 그리고 86개 스킬을 6개 라우터로 줄이는 2단계 라우팅은 컨텍스트 예산을 의식한 설계의 교과서다. get-shit-done/references/context-budget.md와 ARCHITECTURE.md의 "Adaptive Context Enrichment"를 보자.
워크플로(절차) ↔ 에이전트(일꾼)를 분리하고, 의존성 웨이브로 병렬 실행하는 패턴은 그대로 실무에 가져다 쓸 수 있다. agents/gsd-executor.md(일꾼 프롬프트)와 workflows/execute-phase(웨이브 오케스트레이션)를 짝지어 읽으면 구조가 한눈에 들어온다.
모든 상태를 마크다운에 두면서도, 병렬 에이전트의 STATE.md 동시 쓰기를 O_EXCL 락파일 + 스테일 락 감지로 막는다. 가벼운 동시성 제어를 실제 제품 코드로 보는 좋은 예 — bin/lib/state.cjs의 writeStateMd() 락 로직.
Claude Code 포맷으로만 작성한 프롬프트를, 설치 시점에 도구명(Bash→execute)·훅 이벤트명(PostToolUse→AfterTool)·프론트매터·경로를 자동 변환해 OpenCode·Gemini·Codex 등으로 뿌린다. 설치기 어댑터 패턴의 실전 사례 — bin/install.js의 convertClaudeToOpencodeFrontmatter.
"리서처가 패키지를 추천 → 실행자가 자동 설치"라는 위협 모델을 명확히 정의하고, 출처 태깅([VERIFIED]/[ASSUMED]/[SLOP])을 설치 경계의 하드 게이트로 강제한다. AI 에이전트에 안전장치를 넣는 설계 — ARCHITECTURE.md의 "Package Legitimacy Gate".
워크플로가 에이전트를 부르는 핵심 연결은 개념적으로 이렇게 단순하다(개념 예시 — 복사용 아님):
// 오케스트레이터(워크플로)가 하는 일은 결국 이 4줄의 반복
gsd-tools.cjs init execute-phase 1 // 컨텍스트 로드(JSON)
gsd-tools.cjs resolve-model gsd-executor // 모델 결정(opus/sonnet/haiku)
spawn-agent agents/gsd-executor.md +context // 새 컨텍스트로 일꾼 소환
gsd-tools.cjs state advance-plan // 결과를 STATE.md에 반영순수 소프트웨어 — 특별한 하드웨어는 필요 없다.
| 항목 | 요구사항 |
|---|---|
| Node.js / npm | 설치기(npx) 실행에 필요. Windows + OpenCode 등 Node 없는 환경은 수동 설치 경로 제공. |
| 호스트 런타임 | Claude Code · OpenCode · Gemini CLI · Kilo · Codex · Copilot · Cursor · Windsurf 등 15종 중 하나. |
| Codex 최소버전 | Codex CLI 0.130.0+ (스킬 디스커버리 경로 변경 반영). |
| OS | macOS · Windows · Linux (설치기가 경로·권한·WSL 차이를 처리). |
| 모델 | 품질/균형/예산 프로파일로 에이전트별 모델 지정. 1M급 모델(Opus 4.6·Sonnet 4.6)이면 컨텍스트 자동 강화. |
| 선택 도구 | slopcheck(pip, 패키지 검증) · fallow(Rust/npm, 구조 리뷰) — 없으면 안전한 폴백. |
설치는 사실상 npx @opengsd/gsd-core@latest 한 줄이면 끝이다. 설치기가 런타임과 전역/로컬 여부를 물어보고 알아서 깐다. GSD는 자동화를 위해 만들어졌으므로 claude --dangerously-skip-permissions로 권한 확인을 건너뛰고 돌리는 것을 권장한다. 주의: 이 옵션은 에이전트가 확인 없이 명령을 실행한다는 뜻이니, 신뢰하는 프로젝트에서만 쓰고 §2의 저장소/패키지 출처 확인을 함께 챙기자.
손으로 한 사이클을 돌려봐야 구조가 몸에 붙는다.
빈 폴더에서 GSD를 설치하고 /gsd-new-project로 "할 일 메모 웹앱" 같은 작은 아이디어를 넣어 본다. 질문→로드맵까지 받은 뒤 1단계를 discuss→plan→execute→verify→ship로 끝까지 돌려, 6단계 루프의 감을 잡는다.
한 단계를 돌린 뒤 .planning/을 열어 PROJECT.md · ROADMAP.md · STATE.md와 phases/01-*/의 CONTEXT/RESEARCH/PLAN/SUMMARY/VERIFICATION이 어떻게 연결되는지 본다. "AI의 기억이 결국 평범한 마크다운"임을 체감하는 게 목표.
.planning/config.json에서 mode를 interactive↔yolo로, 모델 프로파일을 quality↔budget로 바꿔 보고, parallelization.enabled를 껐다 켜며 실행 속도·토큰·품질이 어떻게 달라지는지 비교한다.
agents/gsd-executor.md(일꾼 프롬프트)와 workflows/execute-phase(오케스트레이션)를 나란히 펼쳐, "오케스트레이터가 무엇을 주고 무엇을 기대하는가"라는 에이전트 계약(agent-contracts.md)을 직접 추적한다.
같은 GSD를 Claude Code와 OpenCode(또는 Codex) 두 곳에 설치하고, 변환된 명령/에이전트 파일의 프론트매터·경로 차이를 비교한다. bin/install.js의 변환 함수가 무엇을 바꿔치기하는지 코드로 확인하면 "한 번 쓰고 여러 곳에 배포"의 실체가 보인다.
GSD를 발판으로 "AI 에이전트 엔지니어링" 전반을 익히는 4주 계획.
| 주차 | 주제 | 학습 자료 |
|---|---|---|
| 1주차 | 스펙 주도 개발 & 6단계 루프 체득 | 공식 USER-GUIDE + 실습 1·2 |
| 2주차 | 멀티에이전트 오케스트레이션 패턴 | docs/ARCHITECTURE.md · agents/ · workflows/ |
| 3주차 | 컨텍스트 엔지니어링 & 토큰 예산 | references/context-budget.md · 2단계 라우팅(#2792) |
| 4주차 | 크로스 런타임 추상화 & 공급망 보안 | bin/install.js · Package Legitimacy Gate |
| +α | 내 워크플로를 GSD 스타일로 설계해보기 | Claude Agent SDK · MCP 명세 · spec-kit 비교 |
본문에 나온 용어 빠른 참조.
| 컨텍스트 로트 | 대화가 길어지며 LLM 답변 품질이 떨어지는 현상. GSD의 1순위 타깃. |
| 메타 프롬프트 | AI에게 답이 아니라 "일하는 방식"을 지시하는 상위 프롬프트. |
| 스펙 주도 개발 | 코드 전에 요구사항·로드맵·계획 문서를 먼저 합의하고 구현하는 방식. |
| 오케스트레이터 | 직접 일하지 않고 전문 에이전트를 소환·조율하는 얇은 워크플로. |
| 웨이브 실행 | 계획을 의존성으로 묶어 병렬/순차로 실행하는 단위. |
| 원자 커밋 | 작업 한 건 = 커밋 한 개. 깨끗한 git 히스토리와 되돌리기 용이성. |
| .planning/ | 프로젝트별 영속 상태가 쌓이는 마크다운/JSON 폴더(파일 기반 상태). |
| STATE.md | 현재 위치·결정·블로커가 담긴 "살아있는 기억". 락으로 동시 쓰기 보호. |
| absent = enabled | 설정 키가 없으면 기능이 켜진 것으로 보는 기본값 정책. |
| 슬롭스쿼팅 | AI가 환각한 가짜 패키지명을 공격자가 선점해 악성코드를 심는 공급망 공격. |
| UAT | User Acceptance Testing. 사람이 "진짜 동작하나"를 확인하는 최종 게이트. |
| 크로스 런타임 | 한 번 작성한 프롬프트를 설치 시점에 15종 코딩 에이전트 포맷으로 변환 배포. |
@opengsd/get-shit-done-redux에서 리네임, deprecated)