msd-core/docs/ko-KR/COMMANDS.md

GSD Core 명령어 참조

GSD Core의 명령어 참조 — 모든 안정 명령어의 구문, 플래그, 옵션, 예시. 기능 세부 사항은 기능 참조를, 워크플로 안내는 사용자 가이드를, 문서 목록은 README를 참조하세요.

---

명령어 구문

• Claude Code / Copilot / OpenCode / Kilo: /gsd-command-name [args] (하이픈 형식)
• Gemini CLI: /gsd:command-name [args] (콜론 형식 — Gemini는 gsd: 네임스페이스로 명령어를 분류합니다)
• Codex: $gsd-command-name [args]

하이픈 형식과 콜론 형식은 동일한 명령어의 런타임별 표기법입니다. 사용 중인 런타임에 따라 인스톨러가 해당 런타임의 명령어 디렉토리에 올바른 형식을 자동으로 작성합니다.

---

네임스페이스 메타 스킬

v1.40에서 여섯 개의 네임스페이스 라우터가 1단계 진입점으로 제공됩니다. 이를 통해 즉시 스킬 목록을 로드하는 토큰 비용을 낮추면서(라우터 6개에 ~120 토큰 대 86개 스킬 전체 목록에 ~2,150 토큰) 전체 기능을 직접 호출할 수 있습니다. 모델이 네임스페이스를 선택한 후 구체적인 하위 스킬로 라우팅합니다. #2792를 참조하세요.

명령어	라우팅 대상
/gsd-workflow	단계 파이프라인 — discuss / plan / execute / verify / phase / progress
/gsd-project	프로젝트 수명 주기 — 마일스톤, 감사, 요약
/gsd-quality	품질 게이트 — 코드 리뷰, 디버그, 감사, 보안, 평가, UI
/gsd-context	코드베이스 인텔리전스 — 맵, 그래프화, 문서, 학습 내용
/gsd-manage	관리 — config, workspace, workstreams, thread, update, ship, inbox
/gsd-ideate	탐색 및 캡처 — explore, sketch, spike, spec, capture

네임스페이스 스킬은 추가적 방식으로 동작합니다 — 기존의 모든 구체적인 명령어(예: /gsd-plan-phase, /gsd-code-review --fix)는 여전히 직접 호출할 수 있습니다.

---

핵심 워크플로 명령어

/gsd-new-project

심층적인 컨텍스트 수집을 통해 새 프로젝트를 초기화합니다.

플래그	설명
--auto @file.md	문서에서 자동 추출, 대화형 질문 생략

전제 조건: 기존 .planning/PROJECT.md 없음 생성 결과: PROJECT.md, REQUIREMENTS.md, ROADMAP.md, STATE.md, config.json, research/, CLAUDE.md

/gsd-new-project                    # 대화형 모드
/gsd-new-project --auto @prd.md     # PRD에서 자동 추출

---

/gsd-workspace

GSD 워크스페이스 관리 — 리포지토리 복사본과 독립적인 .planning/ 디렉토리를 갖는 격리된 워크스페이스 환경을 생성, 나열, 또는 삭제합니다.

플래그	설명
--new	새 워크스페이스 생성 (--name, --repos 등과 함께 사용)
--list	활성 GSD 워크스페이스 및 상태 나열
--remove <name>	워크스페이스 삭제 및 git 워크트리 정리
--name <name>	워크스페이스 이름 (--new와 함께 사용)
--repos repo1,repo2	쉼표로 구분된 리포지토리 경로 또는 이름 (--new와 함께 사용)
--path /target	대상 디렉토리 (기본값: ~/gsd-workspaces/<name>)
--strategy worktree|clone	복사 전략 (기본값: worktree)
--branch <name>	체크아웃할 브랜치 (기본값: workspace/<name>)
--auto	대화형 질문 생략

사용 사례:

• 멀티 리포지토리: 격리된 GSD 상태로 일부 리포지토리에서 작업
• 기능 격리: --repos .는 현재 리포지토리의 워크트리 생성

생성 결과: WORKSPACE.md, .planning/, 리포지토리 복사본 (워크트리 또는 클론)

/gsd-workspace --new --name feature-b --repos hr-ui,ZeymoAPI
/gsd-workspace --new --name feature-b --repos . --strategy worktree  # 동일 리포지토리 격리
/gsd-workspace --list
/gsd-workspace --remove feature-b

---

/gsd-discuss-phase

계획 수립 전 적응형 질문을 통해 단계 컨텍스트를 수집합니다.

인수	필수	설명
N	아니요	단계 번호 (기본값: 현재 단계)

플래그	설명
--all	영역 선택 생략 — 모든 불확실한 영역을 대화형으로 논의 (자동 진행 없음)
--auto	모든 질문에 권장 기본값 자동 선택
--batch	하나씩이 아닌 일괄 입력을 위한 질문 그룹화
--analyze	논의 중 트레이드오프 분석 추가
--power	미리 준비된 답변 파일로 파일 기반 대량 질문 답변
--assumptions	대화형 세션 없이 단계에 대한 Claude의 구현 가정 표시

전제 조건: .planning/ROADMAP.md 존재 생성 결과: {phase}-CONTEXT.md, {phase}-DISCUSSION-LOG.md (감사 추적)

/gsd-discuss-phase 1                # 단계 1의 대화형 논의
/gsd-discuss-phase 1 --all          # 선택 단계 없이 모든 불확실한 영역 논의
/gsd-discuss-phase 3 --auto         # 단계 3의 기본값 자동 선택
/gsd-discuss-phase --batch          # 현재 단계의 배치 모드
/gsd-discuss-phase 2 --analyze      # 트레이드오프 분석과 함께 논의
/gsd-discuss-phase 1 --power        # 파일로부터 대량 답변
/gsd-discuss-phase 3 --assumptions  # 계획 전 Claude의 가정 표시

---

/gsd-ui-phase

프론트엔드 단계를 위한 UI 디자인 계약을 생성합니다.

인수	필수	설명
N	아니요	단계 번호 (기본값: 현재 단계)

전제 조건: .planning/ROADMAP.md 존재, 해당 단계에 프론트엔드/UI 작업 포함 생성 결과: {phase}-UI-SPEC.md

/gsd-ui-phase 2                     # 단계 2의 디자인 계약

---

/gsd-plan-phase

단계를 리서치, 계획, 검증합니다.

인수	필수	설명
N	아니요	단계 번호 (기본값: 다음 미계획 단계)

플래그	설명
--auto	대화형 확인 생략
--research	RESEARCH.md가 있어도 강제 재리서치
--skip-research	도메인 리서치 단계 생략
--research-phase <N>	리서치 전용 모드: 단계 <N>에 대한 리서처 생성, RESEARCH.md 작성, 계획자 이전에 종료. 삭제된 독립형 리서치 명령어 대체 (#3042).
--view	리서치 전용 수정자: --research-phase와 함께 사용하면 기존 RESEARCH.md를 stdout으로 출력하고 종료 (생성 없음).
--gaps	갭 보완 모드 (VERIFICATION.md 읽기, 리서치 생략)
--skip-verify	계획 검사기 검증 루프 생략
--prd <file>	컨텍스트로 discuss-phase 대신 PRD 파일 사용
--ingest <path-or-glob>	컨텍스트 합성을 위해 discuss-phase 대신 ADR 파일 사용
--ingest-format <auto|nygard|madr|narrative>	--ingest에 대한 선택적 ADR 파서 형식 재정의
--reviews	REVIEWS.md의 크로스 AI 리뷰 피드백으로 재계획
--validate	계획 시작 전 상태 검증 실행
--bounce	계획 후 외부 계획 바운스 검증 실행 (workflow.plan_bounce_script 사용)
--skip-bounce	설정에서 활성화되어 있어도 계획 바운스 생략
--mvp	수직 MVP 모드 — 계획자가 수평 레이어 대신 기능 슬라이스(UI→API→DB)로 작업을 구성합니다. 이전 단계 요약이 없는 새 프로젝트의 단계 1에서는 SKELETON.md(Walking Skeleton)도 생성합니다. ROADMAP.md에 **Mode:** mvp를 추가하여 단계별로 지속시킬 수 있으며, 플래그 없이 자동으로 --mvp가 적용됩니다.
--tdd	TDD 모드 — 계획자가 동작 추가 작업에 type: tdd를 적용하여 각 작업이 실패하는 테스트로 시작하도록 합니다. --mvp와 조합 가능: --mvp --tdd는 모든 동작 추가 작업이 red-green으로 시작하는 수직 슬라이스를 생성합니다.

전제 조건: .planning/ROADMAP.md 존재 생성 결과: {phase}-RESEARCH.md, {phase}-{N}-PLAN.md, {phase}-VALIDATION.md; Walking Skeleton 모드 실행 시 {phase}/SKELETON.md

리서치 전용 모드 (--research-phase <N>):

• 수정자 없음: RESEARCH.md가 이미 있으면 update / view / skip 프롬프트.
• --research 사용: 강제 새로 고침 — 프롬프트 없이 리서처를 무조건 재생성.
• --view 사용: 기존 RESEARCH.md를 stdout으로 출력, 생성 없음. RESEARCH.md가 없으면 오류 발생.

패키지 적법성 게이트 (v1.42.1): 리서처가 외부 패키지를 추천하면 각 패키지에 대해 slopcheck install <pkg> --json을 실행하고 레지스트리, 출시일, 다운로드 수, 소스 리포지토리, slopcheck 판정이 담긴 ## Package Legitimacy Audit 테이블을 RESEARCH.md에 작성합니다. 판정:

• [SLOP] — 패키지가 RESEARCH.md에서 완전히 제거; 계획자에게 전달되지 않음
• [SUS] — 패키지 플래그 지정; 계획자가 설치 작업 전에 checkpoint:human-verify 삽입
• [OK] — 패키지 승인; 체크포인트 없음

WebSearch에서 가져온 패키지는 [ASSUMED]([VERIFIED]가 아님)로 태그되며 [SUS]와 동일하게 처리됩니다 — 설치 전에 사람 체크포인트가 필요합니다. slopcheck를 설치할 수 없는 경우 추천된 모든 패키지는 [ASSUMED]로 태그되고 게이트 처리됩니다.

전체 체크포인트 형식, 판정 테이블, 문제 해결 방법은 사용자 가이드의 패키지 적법성 게이트를 참조하세요.

/gsd-plan-phase 1                              # 단계 1 리서치 + 계획 + 검증
/gsd-plan-phase 3 --skip-research              # 리서치 없이 계획 (친숙한 도메인)
/gsd-plan-phase --auto                         # 비대화형 계획 수립
/gsd-plan-phase 2 --validate                   # 계획 전 상태 검증
/gsd-plan-phase 1 --bounce                     # 계획 + 외부 바운스 검증
/gsd-plan-phase 2 --ingest docs/adr/0010.md   # 컨텍스트 합성을 위한 ADR 익스프레스 경로
/gsd-plan-phase 2 --ingest 'docs/adr/00*.md' --ingest-format auto
/gsd-plan-phase --research-phase 4             # 단계 4만 리서치 (RESEARCH.md 있으면 프롬프트)
/gsd-plan-phase --research-phase 4 --view      # 기존 RESEARCH.md 출력, 생성 없음
/gsd-plan-phase --research-phase 4 --research  # 강제 리서치 새로 고침, 프롬프트 없음
/gsd-plan-phase 1 --mvp                        # 단계 1의 수직 슬라이스 계획
/gsd-plan-phase 1 --mvp --tdd                  # 수직 슬라이스 + 동작 추가 작업당 실패 테스트

---

/gsd-plan-review-convergence

크로스 AI 계획 수렴 루프 — HIGH 우려사항이 없어질 때까지 리뷰 피드백으로 재계획. plan-phase → review → replan → re-review 사이클을 실행합니다(기본 최대 3 사이클). 계획 및 리뷰를 위한 격리된 에이전트를 생성하고, 오케스트레이터가 루프 제어, HIGH 우려사항 카운팅, 정체 감지, 에스컬레이션을 처리합니다.

인수 / 플래그	필수	설명
N	예	계획 및 리뷰할 단계 번호
--codex / --gemini / --claude / --opencode	아니요	단일 리뷰어 선택
--all	아니요	구성된 모든 리뷰어를 병렬로 실행
--max-cycles N	아니요	사이클 상한 재정의 (기본값 3)

종료 동작: HIGH 카운트가 0이 되면 루프 종료. 사이클 간 HIGH 카운트가 감소하지 않을 때 정체 감지 경고. --max-cycles에 도달해도 HIGH 우려사항이 남아 있으면 에스컬레이션 게이트가 계속 진행하거나 수동 리뷰를 요청합니다.

/gsd-plan-review-convergence 3                    # 기본 리뷰어, 3 사이클
/gsd-plan-review-convergence 3 --codex            # Codex 전용 리뷰
/gsd-plan-review-convergence 3 --all --max-cycles 5

---

/gsd-ultraplan-phase

[BETA] 계획 단계를 Claude Code의 ultraplan 클라우드로 오프로드; 브라우저에서 리뷰하고 가져오기. 계획이 원격으로 작성되는 동안 터미널은 자유롭게 유지됩니다; 브라우저에서 인라인 댓글을 리뷰한 후 /gsd-import를 통해 최종 계획을 .planning/으로 가져옵니다.

플래그	필수	설명
N	예	원격으로 계획할 단계 번호

격리: 업스트림 ultraplan 변경이 핵심 계획 파이프라인에 영향을 미치지 않도록 /gsd-plan-phase와 의도적으로 분리됩니다.

/gsd-ultraplan-phase 4                  # 단계 4의 계획을 오프로드

---

/gsd-execute-phase

웨이브 기반 병렬화로 단계의 모든 계획을 실행하거나 특정 웨이브만 실행합니다.

인수	필수	설명
N	예	실행할 단계 번호
--wave N	아니요	단계에서 웨이브 N만 실행
--validate	아니요	실행 시작 전 상태 검증 실행
--cross-ai	아니요	외부 AI CLI에 실행 위임 (workflow.cross_ai_command 사용)
--no-cross-ai	아니요	설정에서 크로스 AI가 활성화되어 있어도 로컬 실행 강제

전제 조건: 단계에 PLAN.md 파일 존재 생성 결과: 계획당 {phase}-{N}-SUMMARY.md, git 커밋, 단계가 완전히 완료되면 {phase}-VERIFICATION.md

패키지 설치 실패 (v1.42.1): 계획의 설치 단계가 실패하면 실행자는 checkpoint:human-verify를 표시하고 중지합니다. 비슷한 이름의 대안을 자동으로 설치하지 않습니다. 이는 의도적인 동작입니다 — 패키지 이름을 자동으로 대체하는 것은 슬로프스쿼팅이 확산되는 방식이기 때문입니다. 레지스트리 페이지에서 패키지를 확인한 후 체크포인트에 응답하세요.

/gsd-execute-phase 1                # 단계 1 실행
/gsd-execute-phase 1 --wave 2       # 웨이브 2만 실행
/gsd-execute-phase 1 --validate     # 실행 전 상태 검증
/gsd-execute-phase 2 --cross-ai     # 단계 2를 외부 AI CLI에 위임

---

/gsd-verify-work

자동 진단이 포함된 사용자 인수 테스트.

인수	필수	설명
N	아니요	단계 번호 (기본값: 마지막 실행 단계)

전제 조건: 단계가 실행됨 생성 결과: {phase}-UAT.md, 문제 발견 시 수정 계획

브라우저 기반 UAT의 경우 구성된 브라우저 MCP 서버를 사용하세요. 현재 Open GSD 컴패니언은 gsd-browser(gsd-browser mcp)이며, 결정론적 탐색, 버전 관리된 참조, 어설션, 스크린샷, 시각적 비교, 녹화, 사용자 인수 기능을 제공합니다. 이미 구성되어 있는 레거시 Playwright MCP 서버도 계속 사용할 수 있습니다.

/gsd-verify-work 1                  # 단계 1의 UAT

---

---

/gsd-ship

완성된 단계 작업으로부터 자동 생성된 본문으로 PR을 생성합니다.

인수	필수	설명
N	아니요	단계 번호 또는 마일스톤 버전 (예: 4 또는 v1.0)
--draft	아니요	초안 PR로 생성

전제 조건: 단계 검증 완료 (/gsd-verify-work 통과), gh CLI 설치 및 인증됨 생성 결과: 계획 아티팩트로부터 풍부한 본문이 포함된 GitHub PR, STATE.md 업데이트

/gsd-ship 4                         # 단계 4 배포
/gsd-ship 4 --draft                 # 초안 PR로 배포

PR 본문 포함 내용:

• ROADMAP.md의 단계 목표
• SUMMARY.md 파일의 변경사항 요약
• 반영된 요구사항 (REQ-ID)
• 검증 상태
• 주요 결정 사항
• ship.pr_body_sections에서 선택적으로 구성된 PRD 스타일 섹션

커스텀 PR 본문 섹션에 대한 온보딩, 예시, 검증 규칙은 Custom PR Body Sections를 참조하세요.

---

/gsd-ui-review

구현된 프론트엔드의 소급 6개 기둥 시각적 감사.

인수	필수	설명
N	아니요	단계 번호 (기본값: 마지막 실행 단계)

전제 조건: 프로젝트에 프론트엔드 코드 포함 (독립형으로 작동, GSD 프로젝트 불필요) 생성 결과: {phase}-UI-REVIEW.md, .planning/ui-reviews/의 스크린샷

더 풍부한 시각적 증거를 위해 gsd-browser 또는 다른 브라우저 MCP 서버와 함께 사용하면 감사에서 스크린샷, 상태, 콘솔/네트워크 컨텍스트, 재현 가능한 상호작용 단계를 캡처할 수 있습니다.

/gsd-ui-review                      # 현재 단계 감사
/gsd-ui-review 3                    # 단계 3 감사

---

/gsd-audit-uat

모든 미해결 UAT 및 검증 항목의 크로스 단계 감사.

전제 조건: 최소 한 단계가 UAT 또는 검증과 함께 실행됨 생성 결과: 사람 테스트 계획이 포함된 분류된 감사 보고서

/gsd-audit-uat

---

/gsd-audit-milestone

마일스톤이 완료 정의를 충족했는지 검증합니다.

전제 조건: 모든 단계 실행됨 생성 결과: 갭 분석이 포함된 감사 보고서

/gsd-audit-milestone

---

/gsd-complete-milestone

마일스톤 아카이브, 릴리스 태그 생성.

전제 조건: 마일스톤 감사 완료 (권장) 생성 결과: MILESTONES.md 항목, git 태그

/gsd-complete-milestone

---

/gsd-milestone-summary

팀 온보딩 및 리뷰를 위한 마일스톤 아티팩트로부터 포괄적인 프로젝트 요약을 생성합니다.

인수	필수	설명
version	아니요	마일스톤 버전 (기본값: 현재/최신 마일스톤)

전제 조건: 최소 하나의 완료 또는 진행 중인 마일스톤 생성 결과: .planning/reports/MILESTONE_SUMMARY-v{version}.md

요약 포함 내용:

• 개요, 아키텍처 결정, 단계별 분석
• 주요 결정 사항 및 트레이드오프
• 요구사항 커버리지
• 기술 부채 및 연기된 항목
• 새 팀원을 위한 시작 가이드
• 생성 후 대화형 Q&A 제공

/gsd-milestone-summary                # 현재 마일스톤 요약
/gsd-milestone-summary v1.0           # 특정 마일스톤 요약

---

/gsd-new-milestone

다음 버전 사이클을 시작합니다.

인수	필수	설명
name	아니요	마일스톤 이름
--reset-phase-numbers	아니요	새 마일스톤을 단계 1부터 시작하고 로드맵 작성 전에 이전 단계 디렉토리 아카이브

전제 조건: 이전 마일스톤 완료 생성 결과: 업데이트된 PROJECT.md, 새 REQUIREMENTS.md, 새 ROADMAP.md

/gsd-new-milestone                  # 대화형
/gsd-new-milestone "v2.0 Mobile"    # 이름 있는 마일스톤
/gsd-new-milestone --reset-phase-numbers "v2.0 Mobile"  # 마일스톤 번호를 1부터 재시작

---

단계 관리 명령어

/gsd-phase

ROADMAP.md의 단계에 대한 CRUD — 단일 통합 명령어로 단계 추가, 삽입, 삭제 또는 편집.

플래그	설명
(없음)	현재 마일스톤 끝에 새 정수 단계 추가
--insert <N>	단계 N 다음에 소수 단계(예: 3.1)로 긴급 작업 삽입
--remove <N>	향후 단계 삭제 및 이후 단계 번호 재정렬
--edit <N>	기존 단계의 모든 필드를 인플레이스로 편집
--force	진행 중이거나 완료된 단계 편집 허용 (--edit와 함께 사용)

전제 조건: .planning/ROADMAP.md 존재 생성 결과: 업데이트된 ROADMAP.md

/gsd-phase "Add authentication system"          # 설명과 함께 새 단계 추가
/gsd-phase --insert 3 "Fix auth race condition" # 단계 3과 4 사이에 삽입 → 3.1 생성
/gsd-phase --remove 7               # 단계 7 삭제, 8→7, 9→8 등으로 번호 재정렬
/gsd-phase --edit 5                 # 단계 5의 모든 필드 편집
/gsd-phase --edit 5 --force         # 진행 중이거나 완료된 경우에도 단계 5 편집

---

/gsd-mvp-phase

단계에 대한 안내형 MVP 계획 — 사용자 스토리를 입력받고, SPIDR 분할 확인을 실행하고, ROADMAP.md에 **Mode:** mvp를 작성한 후 /gsd-plan-phase에 위임합니다 (로드맵 필드를 통해 MVP 모드를 자동 감지).

인수	필수	설명
N	예	MVP 모드로 전환할 단계 번호 (정수 또는 2.1과 같은 소수)

플래그	설명
--force	in_progress 또는 completed 단계 전환 허용

전제 조건: 단계가 ROADMAP.md에 이미 존재해야 합니다 (/gsd-new-project, /gsd-phase, 또는 /gsd-phase --insert를 통해 생성). 이 명령어는 새 단계를 생성하지 않습니다 — 기존 단계를 전환합니다.

동작: 구조화된 사용자 스토리를 수집하고, 형식을 검증하고, SPIDR 분할 확인을 실행하고, 단계의 ROADMAP.md 섹션에 **Goal:**과 **Mode:** mvp를 작성한 후 /gsd-plan-phase <N>에 위임합니다. 안내는 MVP 단계 계획 방법을 참조하세요.

Walking Skeleton: 이전 단계 요약이 없는 새 프로젝트의 단계 1에서 --mvp(또는 mode: mvp)가 사용될 때 자동으로 트리거됩니다. 계획자는 PLAN.md와 함께 SKELETON.md를 생성합니다.

생성 결과: 업데이트된 ROADMAP.md, 그 후 /gsd-plan-phase의 모든 아티팩트; Walking Skeleton 모드 실행 시 SKELETON.md.

/gsd-mvp-phase 1                    # 단계 1의 MVP 계획
/gsd-mvp-phase 2.1                  # 소수 단계의 MVP 계획
/gsd-mvp-phase 3 --force            # 진행 중이어도 단계 3 전환

---

/gsd-validate-phase

Nyquist 검증 갭을 소급하여 감사하고 보완합니다.

인수	필수	설명
N	아니요	단계 번호

/gsd-validate-phase 2               # 단계 2의 테스트 커버리지 감사

---

탐색 명령어

/gsd-progress

상태, 다음 단계를 표시하고 자동으로 다음 논리적 워크플로 단계로 진행합니다. 프로젝트 상태를 읽고 적절한 조치를 결정합니다.

플래그	설명
--next	수동 경로 선택 없이 다음 논리적 워크플로 단계로 자동 진행
--do "task description"	자유 형식 의도를 분석하고 가장 적합한 GSD 명령어로 디스패치
--forensic	표준 보고서 후 6개 검사 무결성 감사 추가 (STATE 일관성, 고아 핸드오프, 연기된 범위 드리프트, 메모리 플래그 보류 작업, 블로킹 할일, 커밋되지 않은 코드)

자동 라우팅 동작 (--next):

• 프로젝트 없음 → /gsd-new-project 제안
• 단계 논의 필요 → /gsd-discuss-phase 실행
• 단계 계획 필요 → /gsd-plan-phase 실행
• 단계 실행 필요 → /gsd-execute-phase 실행
• 단계 검증 필요 → /gsd-verify-work 실행
• 모든 단계 완료 → /gsd-complete-milestone 제안

/gsd-progress                       # "현재 어디에 있나? 다음은?" 자동 라우팅 포함
/gsd-progress --next                # 자동으로 다음 단계로 진행
/gsd-progress --do "fix the auth bug"  # 자유 형식 의도를 최적의 GSD 명령어로 디스패치
/gsd-progress --forensic            # 표준 보고서 + 무결성 감사

/gsd-resume-work

마지막 세션에서 전체 컨텍스트를 복원합니다.

/gsd-resume-work                    # 컨텍스트 재설정 또는 새 세션 후

/gsd-pause-work

단계 도중 중단할 때 컨텍스트 핸드오프를 저장합니다.

플래그	설명
--report	커밋, 파일 변경, 단계 진행 상황을 캡처한 세션 후 요약을 .planning/reports/에 생성

/gsd-pause-work                     # continue-here.md 생성
/gsd-pause-work --report            # continue-here.md + 세션 보고서 생성

/gsd-manager

하나의 터미널에서 여러 단계를 관리하기 위한 대화형 명령 센터.

전제 조건: .planning/ROADMAP.md 존재 동작:

• 시각적 상태 표시기와 함께 모든 단계의 대시보드
• 의존성과 진행 상황을 기반으로 최적의 다음 조치 추천
• 작업 디스패치: discuss는 인라인으로 실행, plan/execute는 백그라운드 에이전트로 실행
• 하나의 터미널에서 단계 간 작업을 병렬화하는 파워 유저를 위해 설계
• manager.flags 설정을 통한 단계별 패스스루 플래그 지원 (설정 참조)

/gsd-manager                        # 명령 센터 대시보드 열기
/gsd-manager --analyze-deps         # 병렬 실행 전 ROADMAP 단계의 의존성 관계 스캔

체크포인트 하트비트 (#2410):

백그라운드 execute-phase 실행은 모든 웨이브 및 계획 경계에서 [checkpoint] 마커를 내보내므로 Claude API SSE 스트림이 다중 계획 단계에서 Stream idle timeout - partial response received를 트리거할 만큼 오래 유휴 상태가 되지 않습니다. 형식은 다음과 같습니다:

[checkpoint] phase {N} wave {W}/{M} starting, {count} plan(s), {P}/{Q} plans done
[checkpoint] phase {N} wave {W}/{M} plan {plan_id} starting ({P}/{Q} plans done)
[checkpoint] phase {N} wave {W}/{M} plan {plan_id} complete ({P}/{Q} plans done)
[checkpoint] phase {N} wave {W}/{M} complete, {P}/{Q} plans done ({ok}/{count} ok)

백그라운드 단계가 도중에 실패하면 [checkpoint]에 대해 트랜스크립트를 grep하여 마지막으로 확인된 경계를 확인하세요. 관리자의 백그라운드 완료 핸들러는 에이전트가 오류로 종료될 때 이 마커를 사용하여 부분 진행 상황을 보고합니다.

관리자 패스스루 플래그:

.planning/config.json의 manager.flags에서 단계별 플래그를 구성합니다. 이 플래그는 각 디스패치된 명령어에 추가됩니다:

{
  "manager": {
    "flags": {
      "discuss": "--auto",
      "plan": "--skip-research",
      "execute": "--validate"
    }
  }
}

---

/gsd-help

요청한 수준에서 GSD 명령어를 표시합니다. 기본값은 화면 하나에 맞습니다; --full은 전체 참조; <topic>은 특정 섹션으로 바로 이동합니다.

/gsd-help                           # 한 페이지 개요 (기본값)
/gsd-help --brief                   # 주요 명령어의 ~10줄 요약
/gsd-help --full                    # 전체 참조 (모든 명령어, 모든 플래그)
/gsd-help <topic>                   # 하나의 섹션만 (예: /gsd-help debug)
/gsd-help --brief <topic>           # 압축된 범위 지정 조회 — 시그니처 + 한 줄 요약

전체 별칭 테이블은 get-shit-done/workflows/help/modes/topic.md를 참조하세요. 알 수 없는 주제는 인식된 목록을 출력합니다.

---

유틸리티 명령어

/gsd-explore

소크라테스식 아이디어 발상 세션 — 탐색 질문을 통해 아이디어를 안내하고, 선택적으로 리서치를 생성한 후 적절한 GSD 아티팩트(노트, 할일, 시드, 리서치 질문, 요구사항 또는 새 단계)로 출력을 라우팅합니다.

인수	필수	설명
topic	아니요	탐색할 주제 (예: /gsd-explore authentication strategy)

/gsd-explore                        # 개방형 아이디어 발상 세션
/gsd-explore authentication strategy  # 특정 주제 탐색

---

/gsd-undo

안전한 git 되돌리기 — 의존성 확인 및 확인 게이트를 통해 단계 매니페스트를 사용하여 GSD 단계 또는 계획 커밋 롤백.

플래그	필수	설명
--last N	(세 가지 중 하나 필수)	대화형 선택을 위한 최근 GSD 커밋 표시
--phase NN	(세 가지 중 하나 필수)	단계의 모든 커밋 되돌리기
--plan NN-MM	(세 가지 중 하나 필수)	특정 계획의 모든 커밋 되돌리기

안전성: 되돌리기 전 의존하는 단계/계획 확인; 항상 확인 게이트 표시.

/gsd-undo --last 5                  # 최근 GSD 커밋 5개에서 선택
/gsd-undo --phase 03                # 단계 3의 모든 커밋 되돌리기
/gsd-undo --plan 03-02              # 단계 3의 계획 02 커밋 되돌리기

---

/gsd-import

외부 계획 파일을 GSD 계획 시스템에 수집하고, 작성 전에 PROJECT.md 결정과의 충돌을 감지합니다.

플래그	필수	설명
--from <filepath>	예 (--from-gsd2와 중 하나)	가져올 외부 계획 파일 경로
--from-gsd2	예 (--from과 중 하나)	GSD-2 (.gsd/) 프로젝트를 GSD v1 (.planning/) 형식으로 역 마이그레이션
--path <dir>	아니요	--from-gsd2 사용 시: GSD-2 프로젝트 디렉토리 경로 (기본값: 현재 디렉토리)

처리: 충돌 감지 → 해결 프롬프트 → GSD PLAN.md로 작성 → gsd-plan-checker를 통한 검증

/gsd-import --from /tmp/team-plan.md    # 외부 계획 가져오기 및 검증
/gsd-import --from-gsd2                # GSD-2에서 v1으로 마이그레이션 (현재 디렉토리)
/gsd-import --from-gsd2 --path ~/old-project  # 다른 경로에서 마이그레이션

---

/gsd-ingest-docs

리포지토리의 기존 ADR, PRD, SPEC, 문서에서 .planning/ 설정을 부트스트랩하거나 병합합니다. 병렬 분류(gsd-doc-classifier)와 우선순위 규칙 및 순환 감지를 통한 합성(gsd-doc-synthesizer)을 실행합니다. 세 가지 버킷 충돌 보고서(INGEST-CONFLICTS.md: 자동 해결됨, 경쟁 변형, 미해결 차단자)를 생성하고 LOCKED 대 LOCKED ADR 모순에서 하드 블록합니다.

인수 / 플래그	필수	설명
path	아니요	스캔할 대상 디렉토리 (기본값: 리포지토리 루트)
--mode new|merge	아니요	자동 감지 재정의 (기본값: .planning/ 없으면 new, 있으면 merge)
--manifest <file>	아니요	문서당 {path, type, precedence?}를 나열하는 YAML 파일; 휴리스틱 분류 재정의
--resolve auto	아니요	충돌 해결 모드 (v1: auto만; interactive는 예약됨)

제한: v1은 호출당 최대 50개 문서. 공유 충돌 감지 계약을 references/doc-conflict-engine.md로 추출하며, /gsd-import도 이를 사용합니다.

/gsd-ingest-docs                            # 리포지토리 루트 스캔, 모드 자동 감지
/gsd-ingest-docs docs/                      # docs/ 아래만 수집
/gsd-ingest-docs --manifest ingest.yaml     # 명시적 우선순위 매니페스트

---

/gsd-quick

GSD 보장을 통해 애드혹 작업을 실행합니다.

플래그	설명
--full	완전한 품질 파이프라인 활성화 — 논의 + 리서치 + 계획 확인 + 검증
--validate	계획 확인(최대 2회 반복) + 실행 후 검증만; 논의 또는 리서치 없음
--discuss	가벼운 사전 계획 논의
--research	계획 전 집중 리서처 생성

세분화된 플래그는 조합 가능합니다: --discuss --research --validate는 --full과 동일합니다.

서브커맨드	설명
list	상태와 함께 모든 빠른 작업 나열
status <slug>	특정 빠른 작업의 상태 표시
resume <slug>	슬러그로 특정 빠른 작업 재개

/gsd-quick                          # 기본 빠른 작업
/gsd-quick --discuss --research     # 논의 + 리서치 + 계획
/gsd-quick --validate               # 계획 확인 + 검증만
/gsd-quick --full                   # 완전한 품질 파이프라인
/gsd-quick list                     # 모든 빠른 작업 나열
/gsd-quick status my-task-slug      # 빠른 작업 상태 표시
/gsd-quick resume my-task-slug      # 빠른 작업 재개

/gsd-autonomous

나머지 모든 단계를 자율적으로 실행합니다.

플래그	설명
--from N	특정 단계 번호부터 시작
--to N	특정 단계 번호 완료 후 중지
--interactive	사용자 입력과 함께 간소화된 컨텍스트

/gsd-autonomous                     # 나머지 모든 단계 실행
/gsd-autonomous --from 3            # 단계 3부터 시작
/gsd-autonomous --to 5              # 단계 5까지 실행
/gsd-autonomous --from 3 --to 5     # 단계 3부터 5까지 실행

/gsd-debug

지속적인 상태로 체계적인 디버깅.

인수	필수	설명
description	아니요	버그 설명

플래그	설명
--diagnose	진단 전용 모드 — 수정 시도 없이 조사

서브커맨드:

• /gsd-debug list — 상태, 가설, 다음 조치와 함께 모든 활성 디버그 세션 나열
• /gsd-debug status <slug> — 에이전트를 생성하지 않고 세션의 전체 요약(증거 수, 제거 수, 해결책, TDD 체크포인트) 출력
• /gsd-debug continue <slug> — 슬러그로 특정 세션 재개 (현재 포커스 표시 후 계속 에이전트 생성)
• /gsd-debug [--diagnose] <description> — 새 디버그 세션 시작 (기존 동작; --diagnose는 수정 적용 없이 근본 원인에서 중지)

TDD 모드: .planning/config.json에서 tdd_mode: true일 때, 디버그 세션은 수정을 적용하기 전에 실패하는 테스트를 작성하고 검증해야 합니다 (red → green → done).

/gsd-debug "Login button not responding on mobile Safari"
/gsd-debug --diagnose "Intermittent 500 errors on /api/users"
/gsd-debug list
/gsd-debug status auth-token-null
/gsd-debug continue form-submit-500

/gsd-add-tests

완료된 단계에 대한 테스트를 생성합니다.

인수	필수	설명
N	아니요	단계 번호

/gsd-add-tests 2                    # 단계 2의 테스트 생성

/gsd-stats

프로젝트 통계를 표시합니다.

/gsd-stats                          # 프로젝트 메트릭 대시보드

/gsd-profile-user

8개 차원(커뮤니케이션 스타일, 결정 패턴, 디버깅 접근법, UX 선호도, 벤더 선택, 불만 유발 요인, 학습 스타일, 설명 깊이)에 걸친 Claude Code 세션 분석으로 개발자 행동 프로필을 생성합니다. Claude의 응답을 개인화하는 아티팩트를 생성합니다.

플래그	설명
--questionnaire	세션 분석 대신 대화형 설문지 사용
--refresh	세션 재분석 및 프로필 재생성

생성 아티팩트:

• USER-PROFILE.md — 전체 행동 프로필
• CLAUDE.md 프로필 섹션 — Claude Code에 의해 자동 검색

/gsd-profile-user                   # 세션 분석 및 프로필 구축
/gsd-profile-user --questionnaire   # 대화형 설문지 대안
/gsd-profile-user --refresh         # 새 분석에서 재생성

/gsd-health

.planning/ 디렉토리 무결성을 검증합니다. --context 사용 시 컨텍스트 창 활용 가드를 60% / 70% 임계값에 대해 탐색합니다 (v1.40.0 추가, #2792).

플래그	설명
--repair	복구 가능한 문제 자동 수정
--context	컨텍스트 창 활용 탐색; 60%에서 경고, 70%에서 심각

/gsd-health                         # 무결성 확인
/gsd-health --repair                # 확인 및 수정
/gsd-health --context               # 컨텍스트 활용 트리아지

/gsd-cleanup

완료된 마일스톤에서 누적된 단계 디렉토리를 아카이브하고 업스트림이 삭제된 로컬 브랜치를 정리합니다.

동작: 아카이브할 단계 디렉토리의 드라이런 요약(.planning/phases/에서 .planning/milestones/v{X.Y}-phases/로 이동)과 업스트림이 없어진 로컬 브랜치(git fetch --prune으로 정리)를 표시합니다. 변경 사항 작성 전 확인이 필요합니다. 현재 체크아웃된 브랜치는 절대 정리되지 않습니다.

/gsd-cleanup

---

스파이킹 및 스케칭 명령어

/gsd-spike

구현 방식을 확정하기 전에 2–5개의 집중된 실현 가능성 실험을 실행합니다. 각 실험은 Given/When/Then 프레임으로 실행 가능한 코드를 생성하고 VALIDATED / INVALIDATED / PARTIAL 판정을 반환합니다.

인수	필수	설명
idea	아니요	조사할 기술적 질문 또는 접근법
--quick	아니요	입력 대화 건너뜀; idea 텍스트를 직접 사용
--wrap-up	아니요	완료된 스파이크 결과를 재사용 가능한 프로젝트 로컬 스킬로 패키징

생성 결과: 코드, 결과, README가 포함된 .planning/spikes/NNN-experiment-name/; .planning/spikes/MANIFEST.md --wrap-up 생성 결과: .claude/skills/spike-findings-[project]/ 스킬 파일

/gsd-spike                              # 대화형 입력
/gsd-spike "can we stream LLM tokens through SSE"
/gsd-spike --quick websocket-vs-polling
/gsd-spike --wrap-up                    # 결과를 재사용 가능한 스킬로 패키징

---

/gsd-sketch

구현을 확정하기 전에 일회용 HTML 목업을 통해 디자인 방향을 탐색합니다. 직접 브라우저 비교를 위해 디자인 질문당 2–3개의 변형을 생성합니다.

인수	필수	설명
idea	아니요	탐색할 UI 디자인 질문 또는 방향
--quick	아니요	분위기 입력 건너뜀; idea 텍스트를 직접 사용
--text	아니요	텍스트 모드 대안 — 대화형 프롬프트를 번호 목록으로 대체 (비 Claude 런타임용)
--wrap-up	아니요	채택된 스케치 결정을 재사용 가능한 프로젝트 로컬 스킬로 패키징

생성 결과: .planning/sketches/NNN-descriptive-name/index.html (2–3개의 대화형 변형), README.md, 공유 themes/default.css; .planning/sketches/MANIFEST.md --wrap-up 생성 결과: .claude/skills/sketch-findings-[project]/ 스킬 파일

/gsd-sketch                             # 대화형 분위기 입력
/gsd-sketch "dashboard layout"
/gsd-sketch --quick "sidebar navigation"
/gsd-sketch --text "onboarding flow"    # 비 Claude 런타임
/gsd-sketch --wrap-up                   # 채택된 스케치를 스킬로 패키징

---

진단 명령어

/gsd-forensics

실패한 GSD 워크플로에 대한 사후 조사 — 무엇이 잘못되었는지 진단합니다.

인수	필수	설명
description	아니요	문제 설명 (생략 시 프롬프트)

전제 조건: .planning/ 디렉토리 존재 생성 결과: .planning/forensics/report-{timestamp}.md

조사 범위:

• Git 기록 분석 (최근 커밋, 정체 패턴, 시간 공백)
• 아티팩트 무결성 (완료된 단계에 예상되는 파일)
• STATE.md 이상 및 세션 기록
• 커밋되지 않은 작업, 충돌, 포기된 변경사항
• 최소 4가지 이상 유형 확인 (정체 루프, 누락된 아티팩트, 포기된 작업, 충돌/중단)
• 실행 가능한 결과가 있는 경우 GitHub 이슈 생성 제안

/gsd-forensics                              # 대화형 — 문제에 대한 프롬프트
/gsd-forensics "Phase 3 execution stalled"  # 문제 설명과 함께

---

/gsd-extract-learnings

완료된 단계 작업에서 재사용 가능한 패턴, 안티패턴, 아키텍처 결정을 추출합니다.

인수	필수	설명
N	예	학습 내용을 추출할 단계 번호

플래그	설명
--all	모든 완료된 단계에서 학습 내용 추출
--format	출력 형식: markdown (기본값), json

전제 조건: 단계가 실행됨 (SUMMARY.md 파일 존재) 생성 결과: .planning/learnings/{phase}-LEARNINGS.md

추출 내용:

• 아키텍처 결정 및 근거
• 잘 작동한 패턴 (향후 단계에서 재사용 가능)
• 발생한 안티패턴과 해결 방법
• 기술별 인사이트
• 성능 및 테스트 관찰

/gsd-extract-learnings 3                    # 단계 3에서 학습 내용 추출
/gsd-extract-learnings --all                # 모든 완료된 단계에서 추출

---

워크스트림 관리

/gsd-workstreams

다양한 마일스톤 영역에서 동시 작업을 위한 병렬 워크스트림을 관리합니다.

서브커맨드:

서브커맨드	설명
list	상태와 함께 모든 워크스트림 나열 (서브커맨드 없을 때 기본값)
create <name>	새 워크스트림 생성
status <name>	하나의 워크스트림에 대한 상세 상태
switch <name>	활성 워크스트림 설정
progress	모든 워크스트림에 걸친 진행 요약
complete <name>	완료된 워크스트림 아카이브
resume <name>	워크스트림에서 작업 재개

전제 조건: 활성 GSD 프로젝트 생성 결과: .planning/ 아래의 워크스트림 디렉토리, 워크스트림별 상태 추적

/gsd-workstreams                    # 모든 워크스트림 나열
/gsd-workstreams create backend-api # 새 워크스트림 생성
/gsd-workstreams switch backend-api # 활성 워크스트림 설정
/gsd-workstreams status backend-api # 상세 상태
/gsd-workstreams progress           # 크로스 워크스트림 진행 개요
/gsd-workstreams complete backend-api  # 완료된 워크스트림 아카이브
/gsd-workstreams resume backend-api    # 워크스트림에서 작업 재개

---

설정 명령어

/gsd-settings

워크플로 토글과 모델 프로필의 대화형 설정. 질문은 여섯 개의 시각적 섹션으로 그룹화됩니다:

• 계획 — 리서치, 계획 검사기, 패턴 매퍼, Nyquist, UI 단계, UI 게이트, AI 단계
• 실행 — 검증기, TDD 모드, 코드 리뷰, 코드 리뷰 깊이 (조건부 — 코드 리뷰가 켜져 있을 때만), UI 리뷰
• 문서 및 출력 — 커밋 문서, 논의 건너뜀, 워크트리
• 기능 — Intel, Graphify
• 모델 및 파이프라인 — 모델 프로필, 자동 진행, 분기
• 기타 — 컨텍스트 경고, 리서치 Q

모든 응답은 gsd-tools query config-set을 통해 해결된 프로젝트 설정 경로(일반 설치의 경우 .planning/config.json, 워크스트림이 활성화된 경우 .planning/workstreams/<active>/config.json)에 병합되며 관련 없는 키는 보존됩니다. 확인 후 사용자는 전체 설정 객체를 ~/.gsd/defaults.json에 저장할 수 있으므로 향후 /gsd-new-project 실행이 동일한 기준으로 시작됩니다.

/gsd-settings                       # 대화형 설정

/gsd-config

GSD 설정을 대화형으로 구성합니다 — 워크플로 토글, 고급 노브, 통합, 모델 프로필 — 단일 통합 명령어로.

플래그	설명
(없음)	일반적인 토글: 모델, 리서치, plan_check, 검증기, 분기
--advanced	파워 유저 노브: 계획 조정, 타임아웃, 브랜치 템플릿, 크로스 AI 실행, 런타임/출력
--integrations	서드파티 API 키, 코드 리뷰 CLI 라우팅, 에이전트 스킬 주입
--profile <name>	빠른 프로필 전환: quality, balanced, budget, 또는 inherit

--advanced 섹션:

섹션	키
계획 조정	workflow.plan_bounce, workflow.plan_bounce_passes, workflow.plan_bounce_script, workflow.subagent_timeout, workflow.inline_plan_threshold
실행 조정	workflow.node_repair, workflow.node_repair_budget, workflow.auto_prune_state
논의 조정	workflow.max_discuss_passes
크로스 AI 실행	workflow.cross_ai_execution, workflow.cross_ai_command, workflow.cross_ai_timeout
Git 커스터마이징	git.base_branch, git.phase_branch_template, git.milestone_branch_template
런타임 / 출력	response_language, context_window, search_gitignored, graphify.build_timeout

모든 응답은 gsd-tools query config-set을 통해 관련 없는 키를 보존하며 병합됩니다. API 키는 모든 출력에서 마스킹됩니다 (****<last-4>).

/gsd-config                         # 일반적인 대화형 설정
/gsd-config --advanced              # 파워 유저 노브 (6섹션 프롬프트)
/gsd-config --integrations          # API 키, 리뷰 CLI 라우팅, 에이전트 스킬
/gsd-config --profile budget        # 예산 프로필로 전환
/gsd-config --profile quality       # 품질 프로필로 전환

전체 스키마와 기본값은 CONFIGURATION.md를 참조하세요.

/gsd-surface

재설치 없이 표시되는 스킬 토글 — 프로필 적용, 나열, 또는 클러스터 비활성화.

서브커맨드	설명
list	활성화 및 비활성화된 클러스터와 스킬 표시
status	list + 토큰 비용 요약의 별칭
profile <name>	baseProfile 작성 및 스킬 재스테이징
disable <cluster>	비활성화 목록에 클러스터 추가 및 재스테이징
enable <cluster>	비활성화 목록에서 클러스터 제거 및 재스테이징
reset	표면 델타 삭제; 설치 시 프로필로 복원

/gsd-surface list                   # 현재 표면 표시
/gsd-surface profile standard       # 표준 프로필로 전환
/gsd-surface disable utility        # 유틸리티 클러스터 비활성화
/gsd-surface reset                  # 설치 시 프로필 복원

---

브라운필드 명령어

/gsd-map-codebase

병렬 매퍼 에이전트로 기존 코드베이스를 분석합니다. --fast로 빠른 단일 에이전트 스캔을 하거나, --query로 기존 인텔을 검색합니다.

인수	필수	설명
area	아니요	특정 영역으로 매핑 범위 제한
--fast	아니요	빠른 단일 포커스 평가 — 4개의 병렬 에이전트 대신 하나의 매퍼 에이전트를 생성 (경량 대안)
--query <term>	아니요	.planning/intel/의 쿼리 가능한 코드베이스 인텔 파일 검색 (intel.enabled: true 필요)

플래그	설명
--focus tech|arch|quality|concerns|tech+arch	--fast 모드의 포커스 영역 (기본값: tech+arch)

생성 결과: .planning/codebase/ 분석 문서 (전체 모드); .planning/codebase/의 대상 문서 (--fast); 인텔 쿼리 결과 (--query)

/gsd-map-codebase                   # 전체 코드베이스 분석 (4개 병렬 에이전트)
/gsd-map-codebase auth              # auth 영역에 집중
/gsd-map-codebase --fast            # 빠른 기술 + 아키텍처 개요 (1 에이전트)
/gsd-map-codebase --fast --focus quality  # 품질 및 코드 건강도만
/gsd-map-codebase --query authentication  # 인텔에서 용어 검색

/gsd-graphify

.planning/graphs/에 저장된 프로젝트 지식 그래프를 구축, 쿼리, 검사합니다. config.json에서 graphify.enabled: true로 옵트인 (설정 참조 참조); 비활성화된 경우 명령어가 활성화 힌트를 출력하고 중지합니다.

서브커맨드	설명
build	지식 그래프 구축 또는 재구축 (graphify update .를 인라인으로 실행하고 .planning/graphs/ 새로 고침)
query <term>	그래프에서 용어 검색
status	그래프 신선도 및 통계 표시
diff	마지막 빌드 이후의 변경사항 표시

생성 결과: .planning/graphs/ 그래프 아티팩트 (노드, 에지, 스냅샷)

/gsd-graphify build                 # 지식 그래프 구축 또는 재구축
/gsd-graphify query authentication  # 그래프에서 용어 검색
/gsd-graphify status                # 신선도 및 통계 표시
/gsd-graphify diff                  # 마지막 빌드 이후의 변경사항 표시

프로그래밍 방식 접근: node gsd-tools.cjs graphify <build|query|status|diff|snapshot> — CLI 도구 참조 참조.

gsd-tools intel api-surface

/gsd-map-codebase가 구축한 .planning/intel/api-map.json 인덱스를 .planning/intel/의 사람이 읽을 수 있는 API-SURFACE.md로 렌더링합니다. config.json에서 intel.enabled: true로 게이팅되며; Intel이 비활성화된 경우 명령어가 활성화 힌트를 출력하고 종료합니다. 출력 경로는 항상 .planning/intel/API-SURFACE.md — --out 또는 --format 플래그가 없습니다. api-map.json이 없거나 비어 있으면 명령어는 여전히 명시적인 "불완전" 배너와 함께 파일을 작성하므로 소비자가 침묵을 "아무것도 없음"으로 혼동하지 않습니다.

생성 결과: .planning/intel/API-SURFACE.md

node gsd-tools.cjs intel api-surface              # api-map.json → API-SURFACE.md 렌더링

API-SURFACE.md 출력은 소스 파일별로 그룹화된 내보낸 심볼(함수, 클래스, 데코레이터, 상수)을 서명과 감지된 가시성과 함께 나열합니다. plan_review.source_grounding_authority가 intel로 설정된 경우 계획 드리프트 가드는 api-surface 렌더러를 호출하는 대신 api-map.json을 직접 읽습니다.

---

AI 통합 명령어

/gsd-ai-integration-phase

AI 시스템 구축을 포함하는 단계에 대한 AI-SPEC.md 디자인 계약을 생성합니다. 대화형 결정 매트릭스를 제공하고, 도메인별 장애 모드와 평가 기준을 표시하며, 프레임워크 추천, 구현 지침, 평가 전략이 담긴 AI-SPEC.md를 생성합니다.

생성 결과: 단계 디렉토리의 {phase}-AI-SPEC.md

생성 에이전트: 3개의 병렬 전문 에이전트: domain-researcher, framework-selector, ai-researcher, eval-planner

/gsd-ai-integration-phase              # 현재 단계의 마법사
/gsd-ai-integration-phase 3           # 특정 단계의 마법사

---

/gsd-eval-review

실행된 AI 단계의 평가 커버리지를 감사하고 EVAL-REVIEW.md 개선 계획을 생성합니다. /gsd-ai-integration-phase가 생성한 AI-SPEC.md 평가 계획에 대한 구현을 확인합니다. 각 평가 차원을 COVERED/PARTIAL/MISSING으로 점수를 매깁니다.

전제 조건: 단계가 실행되었고 AI-SPEC.md가 있음 생성 결과: 결과, 갭, 개선 지침이 담긴 {phase}-EVAL-REVIEW.md

/gsd-eval-review                       # 현재 단계 감사
/gsd-eval-review 3                     # 특정 단계 감사

---

업데이트 명령어

/gsd-update

변경 로그 미리보기와 함께 GSD를 업데이트하고, 선택적으로 스킬을 동기화하거나 로컬 패치를 재적용합니다.

플래그	설명
--sync	업데이트 후 GSD 레지스트리에서 스킬 동기화
--reapply	업데이트 후 로컬 수정사항(패치) 복원

/gsd-update                         # 업데이트 확인 및 설치
/gsd-update --sync                  # 업데이트 및 스킬 동기화
/gsd-update --reapply               # 업데이트 및 로컬 패치 재적용

---

코드 품질 명령어

/gsd-code-review

버그, 보안 취약점, 코드 품질 문제에 대해 단계 동안 변경된 소스 파일을 검토합니다. --fix를 사용하여 검토 후 결과를 자동 수정합니다.

인수	필수	설명
N	예	검토할 변경사항이 있는 단계 번호 (예: 2 또는 02)
--depth=quick|standard|deep	아니요	검토 깊이 수준 (workflow.code_review_depth 설정 재정의). quick: 패턴 매칭만 (~2분). standard: 언어별 검사를 통한 파일별 분석 (~5–15분, 기본값). deep: 임포트 그래프와 호출 체인을 포함한 크로스 파일 분석 (~15–30분)
--files file1,file2,...	아니요	명시적 쉼표 구분 파일 목록; SUMMARY/git 범위 지정을 완전히 건너뜀
--fix	아니요	검토 후 자동 문제 수정 — REVIEW.md를 읽고, 수정자 에이전트를 생성하고, 각 수정을 원자적으로 커밋
--fix --all	아니요	수정 범위에 Info 결과 포함 (기본값: Critical + Warning만)
--fix --auto	아니요	수정 + 재검토 반복 루프, 최대 3회 반복

전제 조건: 단계가 실행되었고 SUMMARY.md 또는 git 기록이 있음 생성 결과: 심각도별 분류된 결과가 포함된 {phase}-REVIEW.md; --fix 사용 시 {phase}-REVIEW-FIX.md 생성 에이전트: gsd-code-reviewer 에이전트; --fix 사용 시 gsd-code-fixer 에이전트

선택적 구조적 사전 통과: code_quality.fallow.enabled를 true로 설정하면 에이전트 검토 전에 fallow를 실행합니다. GSD는 {phase}/FALLOW.json을 작성하고 REVIEW.md에 Structural Findings (fallow) 섹션을 포함합니다. code_quality.fallow.scope와 code_quality.fallow.profile로 범위와 프로필을 설정합니다.

/gsd-code-review 3                          # 단계 3의 표준 검토
/gsd-code-review 2 --depth=deep             # 딥 크로스 파일 검토
/gsd-code-review 4 --files src/auth.ts,src/token.ts  # 명시적 파일 목록
/gsd-code-review 3 --fix                    # 검토 후 Critical + Warning 결과 수정
/gsd-code-review 3 --fix --all             # 검토 후 Info 포함 모든 결과 수정
/gsd-code-review 3 --fix --auto            # 검토, 수정, 깨끗해질 때까지 재검토 (최대 3회 반복)

---

/gsd-audit-fix

자율 감사-수정 파이프라인 — 감사를 실행하고, 결과를 분류하고, 테스트 검증으로 자동 수정 가능한 문제를 수정하고, 각 수정을 원자적으로 커밋합니다.

플래그	설명
--source <audit>	실행할 감사 (기본값: audit-uat)
--severity high|medium|all	처리할 최소 심각도 (기본값: medium)
--max N	수정할 최대 결과 수 (기본값: 5)
--dry-run	수정 없이 결과 분류 (분류 테이블 표시)

전제 조건: 최소 한 단계가 UAT 또는 검증과 함께 실행됨 생성 결과: 테스트 검증이 포함된 수정 커밋; 분류 보고서

/gsd-audit-fix                              # audit-uat 실행, medium+ 문제 수정 (최대 5개)
/gsd-audit-fix --severity high             # 고심각도 문제만 수정
/gsd-audit-fix --dry-run                   # 수정 없이 분류 미리보기
/gsd-audit-fix --max 10 --severity all     # 모든 심각도의 최대 10개 문제 수정

---

빠른 & 인라인 명령어

/gsd-fast

서브에이전트 없이 사소한 작업을 인라인으로 실행합니다 — 계획 오버헤드 없음. 오타 수정, 설정 변경, 소규모 리팩토링, 빠뜨린 커밋에 사용합니다.

인수	필수	설명
task description	아니요	할 일 (생략 시 프롬프트)

/gsd-quick의 대안이 아닙니다 — 리서치, 다단계 계획, 또는 검증이 필요한 작업에는 /gsd-quick을 사용하세요.

/gsd-fast "fix typo in README"
/gsd-fast "add .env to gitignore"

---

/gsd-review

외부 AI CLI로부터 단계 계획의 크로스 AI 동료 검토.

인수	필수	설명
--phase N	예	검토할 단계 번호

플래그	설명
--gemini	Gemini CLI 검토 포함
--claude	Claude CLI 검토 포함 (별도 세션)
--codex	Codex CLI 검토 포함
--coderabbit	CodeRabbit 검토 포함
--opencode	OpenCode 검토 포함 (GitHub Copilot을 통해)
--qwen	Qwen Code 검토 포함 (Alibaba Qwen 모델)
--cursor	Cursor 에이전트 검토 포함
--agy / --antigravity	Antigravity CLI 검토 포함 (Google 자격증명으로 무료)
--ollama	Ollama 서버 검토 포함
--lm-studio	LM Studio 서버 검토 포함
--llama-cpp	llama.cpp 서버 검토 포함
--all	사용 가능한 모든 리뷰어 포함 (CLI + 로컬 모델 서버)

기본 리뷰어 동작 (플래그 없음):

• review.default_reviewers가 설정되지 않은 경우, /gsd-review는 감지된 모든 리뷰어를 실행합니다 (현재 기본 동작).
• review.default_reviewers가 설정된 경우, /gsd-review는 해당 하위 집합만 실행합니다 (예: ["gemini","codex"]).
• --all은 항상 설정을 재정의하고 전체 감지된 집합을 실행합니다.
• 명시적 플래그 (예: --cursor)는 해당 실행에 대해 --all과 설정 기본값 모두를 재정의합니다.

생성 결과: {phase}-REVIEWS.md — /gsd-plan-phase --reviews에서 사용 가능

# 플래그 없는 /gsd-review 실행을 위한 프로젝트 기본 리뷰어 설정
gsd config-set review.default_reviewers '["gemini","codex"]'

/gsd-review --phase 2             # 설정에서 gemini+codex 실행
/gsd-review --phase 3 --all
/gsd-review --phase 2 --gemini
/gsd-review --phase 2 --cursor    # 일회성 재정의

---

/gsd-pr-branch

.planning/ 커밋을 필터링하여 깨끗한 PR 브랜치를 생성합니다.

인수	필수	설명
target branch	아니요	베이스 브랜치 (기본값: main)

목적: 리뷰어는 GSD 계획 아티팩트가 아닌 코드 변경사항만 봅니다.

/gsd-pr-branch                     # main 기준으로 필터링
/gsd-pr-branch develop             # develop 기준으로 필터링

---

/gsd-secure-phase

완료된 단계의 위협 완화를 소급하여 검증합니다.

인수	필수	설명
phase number	아니요	감사할 단계 (기본값: 마지막 완료 단계)

전제 조건: 단계가 실행되어야 합니다. 기존 SECURITY.md 여부와 관계없이 작동합니다. 생성 결과: 위협 검증 결과가 포함된 {phase}-SECURITY.md 생성 에이전트: gsd-security-auditor 에이전트

세 가지 운영 모드:

1. SECURITY.md 존재 — 기존 완화 감사 및 검증
2. SECURITY.md 없지만 PLAN.md에 위협 모델 있음 — 아티팩트에서 생성
3. 단계 미실행 — 안내와 함께 종료

/gsd-secure-phase                   # 마지막 완료 단계 감사
/gsd-secure-phase 5                 # 특정 단계 감사

---

/gsd-docs-update

코드베이스에 대한 검증을 통해 프로젝트 문서를 생성하거나 업데이트합니다.

인수	필수	설명
--force	아니요	보존 프롬프트 건너뜀, 모든 문서 재생성
--verify-only	아니요	기존 문서의 정확성 확인, 생성 없음

생성 결과: 최대 9개의 문서 파일 (README, 아키텍처, API, 시작하기, 개발, 테스트, 설정, 배포, 기여) 생성 에이전트: gsd-doc-writer 에이전트 (문서 유형당 하나), 그 후 사실 검증을 위한 gsd-doc-verifier 에이전트

각 문서 작성자는 코드베이스를 직접 탐색합니다 — 환각된 경로나 오래된 서명 없음. 문서 검증자는 라이브 파일시스템에 대한 주장을 확인합니다.

/gsd-docs-update                    # 대화형으로 문서 생성/업데이트
/gsd-docs-update --force            # 모든 문서 재생성
/gsd-docs-update --verify-only      # 기존 문서만 검증

---

작업 캡처 및 백로그 명령어

/gsd-capture

아이디어, 작업, 노트, 시드를 적절한 대상으로 캡처합니다. 기본 모드는 구조화된 할일을 추가하며; 플래그는 특수화된 캡처 워크플로로 라우팅합니다.

플래그	설명
(없음)	나중 작업을 위한 구조화된 할일로 캡처
--note [text]	마찰 없는 노트 — 추가, 나열 (--note list), 또는 승격 (--note promote N)
--backlog <description>	999.x 번호 체계를 사용하여 백로그 주차장에 추가
--seed [idea summary]	트리거 조건이 있는 미래 지향적 아이디어 캡처
--list	보류 중인 할일 나열 및 작업할 항목 선택
--global	전역 범위 사용 (노트 작업용)

백로그: 999.x 번호 체계는 활성 단계 시퀀스 외부에 항목을 유지합니다; 단계 디렉토리는 즉시 생성되므로 /gsd-discuss-phase와 /gsd-plan-phase가 작동합니다. 시드: 전체 WHY, 언제 표시할지, 이동 경로를 보존합니다 — /gsd-new-milestone이 사용합니다.

생성 결과: .planning/todos/ (기본값), 노트 파일 (--note), ROADMAP.md 백로그 섹션 (--backlog), .planning/seeds/SEED-NNN-slug.md (--seed)

/gsd-capture "Consider adding dark mode support"   # 할일 추가
/gsd-capture --note "Caching strategy idea"        # 빠른 노트
/gsd-capture --note list                           # 모든 노트 나열
/gsd-capture --note promote 3                      # 노트 3을 할일로 승격
/gsd-capture --backlog "GraphQL API layer"         # 백로그에 추가
/gsd-capture --seed "Add real-time collaboration when WebSocket infra is in place"
/gsd-capture --list                                # 할일 탐색 및 실행

---

/gsd-review-backlog

백로그 항목을 검토하고 활성 마일스톤으로 승격합니다.

항목당 조치: 승격 (활성 시퀀스로 이동), 유지 (백로그에 남김), 삭제.

/gsd-review-backlog

---

/gsd-thread

크로스 세션 작업을 위한 지속적인 컨텍스트 스레드를 관리합니다.

인수	필수	설명
(없음) / list	—	모든 스레드 나열
list --open	—	상태가 open 또는 in_progress인 스레드만 나열
list --resolved	—	상태가 resolved인 스레드만 나열
status <slug>	—	특정 스레드의 상태 표시
close <slug>	—	스레드를 해결됨으로 표시
name	—	이름으로 기존 스레드 재개
description	—	새 스레드 생성

스레드는 여러 세션에 걸쳐 작업하지만 특정 단계에 속하지 않는 작업을 위한 경량 크로스 세션 지식 저장소입니다. /gsd-pause-work보다 더 가볍습니다.

/gsd-thread                         # 모든 스레드 나열
/gsd-thread list --open             # 열린/진행 중인 스레드만 나열
/gsd-thread list --resolved         # 해결된 스레드만 나열
/gsd-thread status fix-deploy-key   # 스레드 상태 표시
/gsd-thread close fix-deploy-key    # 스레드를 해결됨으로 표시
/gsd-thread fix-deploy-key-auth     # 스레드 재개
/gsd-thread "Investigate TCP timeout in pasta service"  # 새 스레드 생성

---

로드맵 관리 명령어

roadmap validate

마일스톤 접두사 일관성을 포함한 구조적 무결성에 대해 ROADMAP.md를 검증합니다.

전제 조건: .planning/ROADMAP.md 존재 생성 결과: 검증 보고서; 오류 또는 경고 시 비제로로 종료

node gsd-tools.cjs roadmap validate

---

roadmap upgrade --convention milestone-prefixed

레거시 Phase N ID를 마일스톤 접두사 Phase M-NN 규칙으로 마이그레이션합니다.

플래그	필수	설명
--convention milestone-prefixed	예	마이그레이션할 대상 규칙
--apply	아니요	디스크에 변경사항 작성 (기본값: 드라이런만)

전제 조건: .planning/ROADMAP.md 존재 생성 결과: 드라이런 diff (기본값) 또는 인플레이스 ROADMAP.md 재작성 (--apply)

node gsd-tools.cjs roadmap upgrade --convention milestone-prefixed         # 드라이런
node gsd-tools.cjs roadmap upgrade --convention milestone-prefixed --apply  # 적용

---

상태 관리 명령어

state validate

STATE.md와 실제 파일시스템 간의 드리프트를 감지합니다.

전제 조건: .planning/STATE.md 존재 생성 결과: STATE.md 필드와 파일시스템 현실 간의 드리프트를 보여주는 검증 보고서

node gsd-tools.cjs state validate

---

state sync [--verify]

디스크의 실제 프로젝트 상태에서 STATE.md를 재구성합니다.

플래그	설명
--verify	드라이런 모드 — 작성 없이 제안된 변경사항 표시

전제 조건: .planning/ 디렉토리 존재 생성 결과: 파일시스템 현실을 반영한 업데이트된 STATE.md

node gsd-tools.cjs state sync             # 디스크에서 STATE.md 재구성
node gsd-tools.cjs state sync --verify    # 드라이런: 작성 없이 변경사항 표시

---

state planned-phase

plan-phase 완료 후 상태 전환을 기록합니다 (계획됨/실행 준비).

플래그	설명
--phase N	계획된 단계 번호
--plans N	생성된 계획 수

전제 조건: 단계가 계획됨 생성 결과: 계획 후 상태가 포함된 업데이트된 STATE.md

node gsd-tools.cjs state planned-phase --phase 3 --plans 2

---

커뮤니티 명령어

커뮤니티 훅

.planning/config.json에서 hooks.community: true로 게이팅된 선택적 git 및 세션 훅. 명시적으로 활성화하지 않으면 모두 무작동(no-op)입니다.

훅	목적
gsd-validate-commit.sh	git 커밋 메시지에 Conventional Commits 형식 강제
gsd-session-state.sh	세션 상태 전환 추적
gsd-phase-boundary.sh	단계 경계 확인 강제

다음으로 활성화:

{ "hooks": { "community": true } }

---

커뮤니티 초대

GSD Discord 커뮤니티에 참여하려면 GSD README의 링크를 방문하거나 /gsd-help를 실행하고 거기에 표시된 Discord 링크를 따르세요.

---

기여: 스킬 설명 표준

스킬 설명(commands/gsd/*.md 프론트매터의 description: 필드)은 모든 세션의 시스템 프롬프트에 삽입됩니다. 세션당 오버헤드를 낮게 유지하기 위해 설명은 ≤ 100자이어야 하며 argument-hint:에 이미 있는 플래그 문서를 중복해서는 안 됩니다.

린트 게이트가 예산을 강제합니다:

npm run lint:descriptions

이 검사는 tests/skill-frontmatter-contract.test.cjs를 통해 npm test의 일부로도 실행됩니다.

---

관련 항목

• 설정 참조
• CLI 도구 참조
• 기능 참조
• 문서 목록