GSD 설치 방법: macOS·Windows·Linux에서 AI 코딩 워크플로 시작하기

GSD Core는 Claude Code·Codex·Cursor 같은 AI 코딩 도구에 프로젝트 계획과 실행 흐름을 넣는 설치형 워크플로 도구다. 2026년 8월 25일 기준 공식 패키지 @opengsd/gsd-core는 macOS, Windows, Linux에서 같은 npx 설치 명령을 제공하고, 설치 마법사에서 실제로 쓸 AI 코딩 도구와 설치 범위를 고르게 한다.

처음에는 운영체제보다 어느 AI 코딩 도구에서 쓸지를 먼저 정하면 된다. 예를 들어 Codex를 고르면 Codex가 읽는 skills·agents·hooks 파일이, Claude Code를 고르면 Claude Code 형식 파일이 설치된다. 저장소의 agents/나 commands/를 직접 복사하지 말고 설치기를 쓰는 이유도 이 형식 변환 때문이다.

GSD는 왜 쓰는 도구인가

GSD는 AI에게 코드를 한 번 시키는 도구가 아니라, 여러 세션과 여러 작업으로 이어지는 개발을 계획·실행·검증의 흐름으로 묶는 프레임워크다. 기능 하나가 요구사항, 조사, 구현, 테스트, 코드 검토를 거쳐야 할 때 AI의 대화 맥락이 길어지면서 앞선 결정이 흐려지는 문제가 생긴다. GSD는 조사·계획·실행 작업을 새 컨텍스트의 하위 에이전트로 나누고, 결정과 진행 상태를 남겨 다음 단계가 이어받게 한다. 공식 README가 말하는 context rot를 줄이려는 방식이다.

GSD Core의 논의, 계획, 실행, 검증, 정리·배포 5단계 흐름 — GSD는 각 단계의 결정과 검증 결과를 다음 단계가 이어서 쓸 수 있게 만든다.

잘 맞는 경우는 기능을 여러 단계로 쪼개야 하는 신규 제품, 이미 있는 저장소를 읽고 안전하게 고쳐야 하는 작업, 구현 뒤 검증과 PR까지 남겨야 하는 팀 작업이다. 반대로 한 줄 설정 수정, 짧은 버그 재현, 문서 한 문단처럼 계획·검증 비용보다 작업 자체가 작은 일에는 GSD 흐름을 열 필요가 없다.

여러 단계가 있는 신규 기능, 기존 저장소 변경, 여러 에이전트 작업에는 GSD 흐름을 권하고 한 줄 설정 변경, 짧은 재현과 조사, 문서 한 문단에는 바로 처리해도 된다는 비교 — GSD가 필요한지는 작업 크기가 아니라, 다음 단계에도 남겨야 할 결정과 검증 기준이 있는지로 판단한다.

설치하면 무엇을 쓸 수 있나

GSD는 Claude Code·Codex·Cursor 같은 런타임에 맞는 명령·skills·agents 설정을 설치한다. 실제 작업은 매 마일스톤마다 다음 다섯 단계로 진행된다.

논의: 구현 전에 바꾸려는 것과 제약을 결정한다.
계획: 조사하고, 작업을 나누고, 실행 순서를 검증한다.
실행: 독립 작업은 새 컨텍스트의 에이전트로 나눠 처리한다.
검증: 만든 결과를 확인하고 실패한 부분은 고친다.
정리·배포: PR과 단계 기록을 남긴 뒤 다음 기능으로 넘어간다.

처음부터 거대한 자동화를 만드는 기능은 아니다. 새 프로젝트는 /gsd-new-project로 요구사항과 첫 계획을 잡고, 기존 저장소는 /gsd-onboard로 구조와 기술 스택을 먼저 파악한 뒤 같은 흐름을 시작한다. 설치 명령보다 이 구분을 먼저 이해해야, GSD가 단순 명령 모음이 아니라 개발 판단을 남기며 AI 작업을 운영하는 방식이라는 점이 보인다.

새 프로젝트는 gsd-new-project로 목표와 첫 단계 계획부터 시작하고 기존 코드베이스는 gsd-onboard로 구조와 바꿀 범위를 먼저 확인하는 두 흐름 — 새 프로젝트와 기존 코드베이스의 시작점은 다르지만, 이후에는 같은 단계별 검증 흐름으로 이어진다.

GSD Core가 설치하는 것은 무엇인가

GSD는 코드를 자동으로 한 번에 완성하는 앱이 아니라, AI 코딩 도구 안에 계획·실행·검증 단계를 위한 명령과 에이전트 설정을 넣는다. 공식 문서는 새 프로젝트를 시작하는 흐름과 기존 저장소를 분석해 시작하는 흐름을 각각 제공한다. 설치가 끝난 뒤 AI 코딩 도구를 다시 열면, 그 도구의 명령 입력창에서 GSD 워크플로를 시작할 수 있다.

같은 GSD라도 설치 대상에 따라 파일 모양과 위치가 달라진다. Codex 전역 설치는 ~/.codex/skills/와 ~/.codex/agents/에 설정을 두고, 프로젝트 범위 설치는 현재 폴더의 .codex/에 둔다. 그래서 다른 런타임용 폴더를 복사해 가져오는 대신 설치 마법사에서 런타임을 고르는 편이 안전하다.

사전 조건: 세 OS에서 먼저 확인할 한 줄

현재 공식 패키지 1.11.0의 package.json은 Node.js >=24.0.0과 npm >=10.0.0을 지정한다. macOS Terminal, Windows PowerShell, Linux Bash에서 먼저 아래 명령을 실행해 v24 이상인지 확인한다. npx는 npm에 포함되어 있으므로 별도 전역 설치가 필요 없다.

node --version
npm --version

macOS: Terminal을 열고 위 두 줄을 실행한다.
Windows: PowerShell을 열고 위 두 줄을 실행한다.
Linux: Bash 등 사용하는 셸을 열고 위 두 줄을 실행한다.

Node 버전이 24보다 낮으면 Node.js를 먼저 올린 뒤 새 터미널을 열어 다시 확인한다. GSD의 공식 이슈 #3838은 node가 PATH에 없거나 필요한 라이브러리가 없을 때 검증 hook이 조용히 작동을 멈출 수 있다고 기록한다. 설치 메시지만 보고 끝내지 말고 node --version이 새 터미널에서도 출력되는 상태를 먼저 만든다.

macOS·Windows·Linux에서 GSD 설치하기

세 운영체제 모두 아래 한 줄이 공식 기본 설치 명령이다. 실행하면 설치기가 런타임과 범위를 질문한다. 개인 컴퓨터의 모든 프로젝트에서 쓸 때는 전역(global), 현재 프로젝트 하나에서만 쓸 때는 로컬(local)을 선택한다.

npx @opengsd/gsd-core@latest

빈 폴더에서 npx GSD Core Codex 로컬 설치를 실행해 71개 skills, 34개 agent 역할 설정, Codex hooks가 생성된 실제 출력 — 실제 로컬 설치 출력입니다. 설명용 모조 터미널이 아니라 이 환경에서 실행한 결과의 핵심 줄을 그대로 옮겼습니다.

질문을 건너뛰고 Codex용 설치를 바로 지정하려면 아래처럼 쓴다. --global은 사용자 계정 전체, --local은 현재 프로젝트 폴더 범위다. 로컬 설치는 반드시 대상 프로젝트 폴더로 이동한 뒤 실행한다.

# Codex를 모든 프로젝트에서 사용
npx @opengsd/gsd-core@latest --codex --global

# Codex를 현재 프로젝트에서만 사용
npx @opengsd/gsd-core@latest --codex --local

# Claude Code를 모든 프로젝트에서 사용
npx @opengsd/gsd-core@latest --claude --global

Codex는 설치 뒤 다시 시작하거나 codex --reload를 실행한다. Claude Code도 새 세션을 열어야 새 명령을 읽는다. 설치 방식에 따라 명령 표기가 다르다. Codex 설치기의 안내는 $gsd-new-project이고, Claude Code의 기본 설치 경로는 /gsd-new-project 같은 슬래시 명령을 쓴다.

설치 뒤 첫 사용: 새 프로젝트와 기존 프로젝트

새로 만드는 프로젝트라면 빈 폴더를 AI 코딩 도구로 열고 GSD의 새 프로젝트 명령을 실행한다. Codex에서는 설치기가 안내한 $gsd-new-project를 입력한다. 기존 코드가 있는 폴더라면 공식 문서의 온보딩 흐름처럼 먼저 GSD를 해당 프로젝트에 로컬 설치하고, 기존 코드베이스를 읽는 명령을 시작한다. 이 구분이 중요한 이유는 새 프로젝트에는 요구사항과 첫 단계 계획이 필요하고, 기존 프로젝트에는 현재 기술 스택과 폴더 구조를 먼저 파악하는 작업이 필요하기 때문이다.

설치 완료 화면에서 “skills”와 “agents”가 설치됐다는 줄을 찾는다. 이 둘은 AI 코딩 도구가 읽을 명령 묶음과 역할별 설정이다. 파일 수가 화면에 보인다고 해서 바로 코드 변경을 맡기기보다, 첫 명령에서 프로젝트 목표와 바꾸지 말아야 할 조건을 구체적으로 입력하고 결과를 검토하는 습관이 필요하다.

로컬에서 확인한 Codex 설치 결과

이 환경의 Node.js v22.23.0과 npm 10.9.8에서 빈 폴더에 npx --yes @opengsd/gsd-core@latest --codex --local을 실행했습니다. 패키지 메타데이터는 Node.js >=24.0.0을 지원 조건으로 선언하지만, 이 실행은 중단되지 않고 .codex/에 71개 skills, 34개 agent 역할 설정, hooks를 생성했습니다.

이는 Node 22를 지원 환경으로 보증한다는 뜻은 아닙니다. 새 설치와 팀 표준은 공식 지원 조건인 Node 24 이상으로 맞추고, 이미 Node 22 환경이 있다면 실제 설치 뒤 생성 파일과 Codex 동작을 확인해야 합니다.

실제 GSD Codex 로컬 설치 뒤 생성된 .codex 폴더의 agents, skills, hooks, config.toml, manifest 파일 구조 — 로컬 설치는 현재 저장소의 `.codex/` 아래에 런타임별 작업 자산을 둡니다.

자주 막히는 지점과 해결법

Node 버전 경고가 나온다. node --version이 v24 이상인지 확인하고, Node를 바꾼 뒤에는 새 터미널을 연다. GSD 이슈 #3838은 Node를 찾지 못한 상태가 검증 기능을 정상 동작처럼 보이게 만들 수 있음을 보여 준다.
macOS 또는 Linux에서 fnm으로 Node를 바꾼 뒤 hook이 실패한다. GSD 이슈 #3704는 fnm이 실제 Node 경로를 버전 폴더로 풀어 기록해, 이전 Node 버전을 제거하면 관리 hook이 사라진 경로를 가리킬 수 있다고 설명한다. which node와 node -p "process.execPath"로 현재 경로를 확인하고, 이전 버전을 지우기 전에는 GSD 릴리스와 이슈의 수정 상태를 확인한다.
Windows에서 병렬 실행 뒤 기록이 빠진 것처럼 보인다. GSD 이슈 #3780은 같은 프로젝트에서 두 실행기가 동시에 windows append를 호출할 때 한 기록이 누락될 수 있다고 보고한다. 같은 저장소에서 병렬 실행을 썼다면 .planning/WINDOWS.md의 기록을 확인한 뒤 다음 단계나 ship 판단을 한다.

설치가 제대로 됐는지 검증하는 방법

새 터미널에서 node --version이 v24 이상인지 확인한다.
AI 코딩 도구를 다시 열거나 해당 도구의 reload 명령을 실행한다.
Codex라면 빈 폴더에서 $gsd-new-project를 입력해 새 프로젝트 흐름이 열리는지 확인한다. Claude Code라면 /gsd-new-project를 입력한다.
프로젝트 범위 설치를 선택했다면 현재 폴더에 해당 런타임의 설정 폴더가 생겼는지 확인한다. Codex 로컬 설치라면 .codex/skills/와 .codex/agents/가 대상이다.

출처: open-gsd/gsd-core 공식 README · 공식 런타임별 설치 문서 · 공식 첫 프로젝트 튜토리얼 · 공식 package.json · 이슈 #3838 · 이슈 #3704 · 이슈 #3780