golem15/msd-core
3
0
Fork 0
Code Issues Pull Requests Actions 4 Packages Projects Releases Wiki Activity
Files
9e2ef2c94dea3f1267deba570c9a423fb38c2f85
msd-core/docs/ko-KR/USER-GUIDE.md
Colin cd5db1f8db test(suites): seed security/slow/integration suites via measured retags 
Renames (git mv) with all references updated (ci-test-scope RULES,
windows-parity allowlist, test-file-count allowlist, docs in 6 locales):

- 5 scanner tests -> *.security.test.cjs — the 'Run security tests' CI step
  ran zero files since the suite taxonomy landed; it is now honest.
- graphify-auto-update -> *.slow.test.cjs (36s, slowest file in the suite;
  e2e gsd-tools spawns) — runs on full-matrix lanes and push to next.
- installer-migration-install-integration -> *.integration.test.cjs
  (13s; an integration test by its own name).

Coverage gate measured after retags: 88.55% lines (gate 70%).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-06-09 23:50:41 -04:00

888 lines
44 KiB
Markdown
Raw Blame History

# GSD 사용자 가이드
GSD Core의 설명형 동반 가이드 — 여기서 방향을 잡은 후 전용 문서로 이동하세요.
> **GSD Core의 문서는 [Diataxis](https://diataxis.fr) 방식으로 구성되어 있습니다.**
> 목적별 탐색: [튜토리얼](README.md#tutorials) · [사용 방법 가이드](README.md#how-to-guides) · [레퍼런스](README.md#reference) · [설명](README.md#explanation) · [문서 인덱스](README.md)
---
## 목차
- [슬래시 명령어 형식](#슬래시-명령어-형식-하이픈-vs-콜론)
- [네임스페이스 라우팅 입문](#네임스페이스-라우팅-입문-gsdnamespace-v140)
- [프로젝트 생명주기 개요](#프로젝트-생명주기-개요)
- [워크플로우 다이어그램](#워크플로우-다이어그램)
- [UI 설계 계약](#ui-설계-계약)
- [스파이킹 및 스케칭](#스파이킹--스케칭)
- [백로그 및 스레드](#백로그--스레드)
- [워크스트림 및 워크스페이스](#워크스트림--워크스페이스)
- [보안](#보안)
- [사용 예시](#사용-예시)
- [문제 해결](#문제-해결)
- [복구 빠른 참조](#복구-빠른-참조)
- [프로젝트 파일 구조](#프로젝트-파일-구조)
- [관련 문서](#관련-문서)
GitHub / Linear / Jira 이슈에서 GSD를 직접 구동하는 방법은
[이슈 기반 오케스트레이션](issue-driven-orchestration.md) 가이드를 참조하세요 —
트래커 이슈를 workspace → discuss → plan → execute → verify → review → ship
루프에 매핑하는 레시피이며, 기존 GSD 프리미티브를 활용합니다.
---
## 슬래시 명령어 형식 (하이픈 vs 콜론)
GSD는 지원되는 모든 런타임에 **동일한 스킬 세트**를 제공하지만, 두 가지 슬래시 형식이 존재합니다:
- **하이픈 형식** — `/gsd-command-name` — Claude Code, Copilot, OpenCode, Kilo, Cursor, Windsurf, Augment, Antigravity, Trae에서 사용됩니다.
- **콜론 형식** — `/gsd:command-name` — **Gemini CLI 전용**입니다. Gemini는 모든 플러그인 명령어를 플러그인 ID 아래에 네임스페이스로 묶으므로, `--gemini` 설치 시 설치 경로가 본문 텍스트 참조와 명령어 파일을 모두 콜론 형식으로 재작성합니다.
직접 선택할 필요는 없습니다 — 설치 프로그램이 각 런타임의 명령어 디렉터리에 올바른 형식을 작성합니다. Gemini 터미널에서 안내를 따를 때는 각 슬래시 명령어를 읽을 때 `gsd` 뒤의 하이픈을 콜론으로 대체하세요.
## 네임스페이스 라우팅 입문 (`gsd:<namespace>`, v1.40)
v1.40은 계층적 라우팅의 1단계 진입점으로 여섯 개의 **네임스페이스 메타스킬**을 제공합니다 — 이 스킬들은 열심히 스킬 목록을 나열하는 토큰 비용을 낮게 유지합니다(6개 라우터에 ~120 토큰 vs 86개 스킬 평면 목록에 ~2,150 토큰). 모든 구체적인 서브스킬은 여전히 직접 호출할 수 있습니다. 각 네임스페이스 라우터의 본문에는 사용자의 의도를 올바른 구체적 서브스킬로 매핑하는 라우팅 테이블이 포함되어 있습니다.
| 네임스페이스 | 라우터 | 라우팅 대상 |
|-----------|--------|-----------|
| 단계 파이프라인 | `/gsd-workflow` | discuss / plan / execute / verify / phase / progress |
| 프로젝트 생명주기 | `/gsd-project` | milestones, audits, summary |
| 품질 게이트 | `/gsd-quality` | code review, debug, audit, security, eval, ui |
| 코드베이스 인텔리전스 | `/gsd-context` | map, graphify, docs, learnings |
| 관리 | `/gsd-manage` | config, workspace, workstreams, thread, update, ship, inbox |
| 탐색 및 캡처 | `/gsd-ideate` | explore, sketch, spike, spec, capture |
네임스페이스 라우터를 직접 입력할 필요는 거의 없습니다. 이들의 가치는 모델이 올바른 서브스킬을 찾는 데 사용하는 라우팅 레이어에 있습니다 — 시스템 프롬프트가 86개 대신 6개 항목을 나열할 수 있도록 존재합니다. 구체적인 명령어를 이미 알고 있다면(예: `/gsd-plan-phase`) 직접 호출하세요.
---
## 프로젝트 생명주기 개요
GSD 핵심 루프는 **discuss → plan → execute → verify → ship**이며, 단계별로 반복됩니다. 전체 단계별 안내 — 출력 예시, 생성되는 파일, 사용 가능한 모든 플래그 포함 — 는 전용 튜토리얼에 있습니다.
[첫 번째 프로젝트](tutorials/your-first-project.md)를 참조하세요.
새 마일스톤 시작 전 기존 코드베이스를 온보딩하는 방법은 [기존 코드베이스 온보딩](tutorials/onboarding-an-existing-codebase.md)을 참조하세요.
**한눈에 보는 관련 플래그:**
| 플래그 | 명령어 | 사용 시점 |
| ---- | ------- | ----------- |
| `--auto` | `/gsd-new-project` | 대화형 질문을 건너뛰고 PRD 파일에서 가져오기 |
| `--research` | `/gsd-quick` | 임시 작업에 리서치 에이전트 추가 |
| `--validate` | `/gsd-quick` | 계획 검사 및 실행 후 검증 추가 |
| `--chain` | `/gsd-discuss-phase` | 중단 없이 discuss → plan → execute 자동 연결 |
| `--skip-research` | `/gsd-plan-phase` | 도메인이 이미 익숙할 때 리서치 에이전트 건너뛰기 |
| `--draft` | `/gsd-ship` | 검토 준비 대신 초안 PR 생성 |
모든 플래그가 포함된 전체 명령어 레퍼런스는 [`docs/COMMANDS.md`](COMMANDS.md)를 참조하세요. 구성 옵션(모델 프로필, 워크플로우 에이전트, git 브랜치)은 [`docs/CONFIGURATION.md`](CONFIGURATION.md)를 참조하세요.
---
## 워크플로우 다이어그램
### 전체 프로젝트 생명주기
```text
┌──────────────────────────────────────────────────┐
│ NEW PROJECT │
│ /gsd-new-project │
│ Questions -> Research -> Requirements -> Roadmap│
└─────────────────────────┬────────────────────────┘
│
┌──────────────▼─────────────┐
│ FOR EACH PHASE: │
│ │
│ ┌────────────────────┐ │
│ │ /gsd-discuss-phase │ │ <- Lock in preferences
│ └──────────┬─────────┘ │
│ │ │
│ ┌──────────▼─────────┐ │
│ │ /gsd-ui-phase │ │ <- Design contract (frontend)
│ └──────────┬─────────┘ │
│ │ │
│ ┌──────────▼─────────┐ │
│ │ /gsd-plan-phase │ │ <- Research + Plan + Verify
│ └──────────┬─────────┘ │
│ │ │
│ ┌──────────▼─────────┐ │
│ │ /gsd-execute-phase │ │ <- Parallel execution
│ └──────────┬─────────┘ │
│ │ │
│ ┌──────────▼─────────┐ │
│ │ /gsd-verify-work │ │ <- Manual UAT
│ └──────────┬─────────┘ │
│ │ │
│ ┌──────────▼─────────┐ │
│ │ /gsd-ship │ │ <- Create PR (optional)
│ └──────────┬─────────┘ │
│ │ │
│ Next Phase?────────────┘
│ │ No
└─────────────┼──────────────┘
│
┌───────────────▼──────────────┐
│ /gsd-audit-milestone │
│ /gsd-complete-milestone │
└───────────────┬──────────────┘
│
Another milestone?
│ │
Yes No -> Done!
│
┌───────▼──────────────┐
│ /gsd-new-milestone │
└──────────────────────┘
```
### 계획 에이전트 조정
```text
/gsd-plan-phase N
│
├── Phase Researcher (x4 parallel)
│ ├── Stack researcher
│ ├── Features researcher
│ ├── Architecture researcher
│ └── Pitfalls researcher
│ │
│ ┌──────▼──────┐
│ │ RESEARCH.md │
│ └──────┬──────┘
│ │
│ ┌──────▼──────┐
│ │ Planner │ <- Reads PROJECT.md, REQUIREMENTS.md,
│ │ │ CONTEXT.md, RESEARCH.md
│ └──────┬──────┘
│ │
│ ┌──────▼───────────┐ ┌────────┐
│ │ Plan Checker │────>│ PASS? │
│ └──────────────────┘ └───┬────┘
│ │
│ Yes │ No
│ │ │ │
│ │ └───┘ (loop, up to 3x)
│ │
│ ┌─────▼──────┐
│ │ PLAN files │
│ └────────────┘
└── Done
```
### 검증 아키텍처 (나이퀴스트 레이어)
계획 단계 리서치 시, GSD는 코드 작성 전에 자동화된 테스트 커버리지를 각 단계 요구사항에 매핑합니다. 리서처는 기존 테스트 인프라를 감지하고, 각 요구사항을 특정 테스트 명령어에 매핑하며, 구현 시작 전에 생성해야 할 테스트 스캐폴딩(Wave 0 작업)을 식별합니다. 계획 검사기는 이를 8번째 검증 차원으로 적용합니다: 작업에 자동화된 검증 명령어가 없는 계획은 승인되지 않습니다.
**출력:** `{phase}-VALIDATION.md` — 단계의 피드백 계약.
**비활성화:** 테스트 인프라가 초점이 아닌 빠른 프로토타이핑 단계에서는 `/gsd-settings`에서 `workflow.nyquist_validation: false`로 설정하세요.
### 소급 검증 (`/gsd-validate-phase`)
나이퀴스트 검증이 생기기 전에 실행된 단계, 또는 전통적인 테스트 슈트만 있는 기존 코드베이스에 대해 소급 감사 및 커버리지 간격을 채우세요:
```text
/gsd-validate-phase N
|
+-- Detect state (VALIDATION.md exists? SUMMARY.md exists?)
|
+-- Discover: scan implementation, map requirements to tests
|
+-- Analyze gaps: which requirements lack automated verification?
|
+-- Present gap plan for approval
|
+-- Spawn auditor: generate tests, run, debug (max 3 attempts)
|
+-- Update VALIDATION.md
|
+-- COMPLIANT -> all requirements have automated checks
+-- PARTIAL -> some gaps escalated to manual-only
```
감사자는 구현 코드를 수정하지 않으며, 테스트 파일과 VALIDATION.md만 수정합니다. 테스트에서 구현 버그가 발견되면, 처리할 에스컬레이션으로 표시됩니다.
### 가정 논의 모드
기본적으로 `/gsd-discuss-phase`는 구현 선호도에 대한 개방형 질문을 합니다. 가정 모드는 이를 반전합니다: GSD가 먼저 코드베이스를 읽고, 단계 구축 방법에 대한 구조화된 가정을 표시하며, 수정 사항만 요청합니다.
**활성화:** `/gsd-settings`를 통해 `workflow.discuss_mode`를 `'assumptions'`으로 설정하세요.
전체 discuss 모드 레퍼런스는 [docs/workflow-discuss-mode.md](workflow-discuss-mode.md)를 참조하세요.
### 결정 커버리지 게이트
discuss 단계는 `<decisions>` 블록 아래 CONTEXT.md에 구현 결정을 번호 매긴 글머리로 캡처합니다(`- **D-01:** …`). 두 개의 게이트는 해당 결정이 계획과 배포된 코드에 반영되도록 보장합니다.
**계획 단계 번역 게이트 (차단).** 계획 후, GSD는 추적 가능한 모든 결정이 최소한 하나의 계획의 `must_haves`, `truths`, 또는 본문에 나타날 때까지 단계를 계획된 것으로 표시하기를 거부합니다.
**검증 단계 유효성 검사 게이트 (비차단).** 검증 중에 GSD는 추적 가능한 각 결정에 대해 계획, SUMMARY.md, 수정된 파일, 최근 커밋 메시지를 검색합니다. 누락된 항목은 경고 섹션으로 VERIFICATION.md에 기록되며, 검증 상태는 변경되지 않습니다.
**결정 제외.** `<decisions>` 내부의 `### Claude's Discretion` 제목 아래로 이동하거나 태그를 지정하세요: `- **D-08 [informational]:** …`, `- **D-09 [folded]:** …`, `- **D-10 [deferred]:** …`.
**게이트 비활성화.** `.planning/config.json`에서 `workflow.context_coverage_gate: false`로 설정하세요(또는 `/gsd-settings`를 통해). 기본값은 `true`입니다.
### 실행 웨이브 조정
```text
/gsd-execute-phase N
│
├── Analyze plan dependencies
│
├── Wave 1 (independent plans):
│ ├── Executor A (fresh 200K context) -> commit
│ └── Executor B (fresh 200K context) -> commit
│
├── Wave 2 (depends on Wave 1):
│ └── Executor C (fresh 200K context) -> commit
│
└── Verifier
├── Check codebase against phase goals
├── Test quality audit (disabled tests, circular patterns, assertion strength)
│
├── PASS -> VERIFICATION.md (success)
└── FAIL -> Issues logged for /gsd-verify-work
```
---
## UI 설계 계약
AI가 생성한 프런트엔드가 시각적으로 일관되지 않은 이유는 Claude Code가 UI에 능숙하지 않아서가 아니라, 실행 전에 설계 계약이 존재하지 않았기 때문입니다. `/gsd-ui-phase`는 계획 전에 설계 계약을 고정하고, `/gsd-ui-review`는 실행 후 결과를 감사합니다.
전체 워크플로우, 구성, shadcn 초기화, 레지스트리 안전 게이트는 [UI 단계 설계](how-to/design-a-ui-phase.md)를 참조하세요.
**빠른 참조:**
| 명령어 | 설명 |
| -------------------- | -------------------------------------------------------- |
| `/gsd-ui-phase [N]` | 프런트엔드 단계를 위한 UI-SPEC.md 설계 계약 생성 |
| `/gsd-ui-review [N]` | 구현된 UI의 소급 6-기둥 시각 감사 |
| 설정 | 기본값 | 설명 |
| ------------------------- | ------- | ----------------------------------------------------------- |
| `workflow.ui_phase` | `true` | 프런트엔드 단계를 위한 UI 설계 계약 생성 |
| `workflow.ui_safety_gate` | `true` | 계획 단계에서 프런트엔드 단계에 대해 /gsd-ui-phase 실행 유도 |
---
## 스파이킹 및 스케칭
계획 전에 기술적 타당성을 검증하려면 `/gsd-spike`를, 설계 전에 시각적 방향을 탐색하려면 `/gsd-sketch`를 사용하세요. 두 명령어 모두 `.planning/`에 아티팩트를 저장하고 마무리 동반 명령어를 통해 프로젝트 스킬 시스템과 통합됩니다.
전체 워크플로우와 흐름 다이어그램은 [스파이크 및 스케치](how-to/spike-and-sketch.md)를 참조하세요.
**일반적인 흐름:**
```bash
/gsd-spike "SSE vs WebSocket" # Validate the approach
/gsd-spike --wrap-up # Package learnings
/gsd-sketch "real-time feed UI" # Explore the design
/gsd-sketch --wrap-up # Package decisions
/gsd-discuss-phase N # Lock in preferences (now informed by spike + sketch)
/gsd-plan-phase N # Plan with confidence
```
---
## 백로그 및 스레드
### 백로그 파킹 랏
활성 계획에 준비되지 않은 아이디어는 999.x 번호를 사용하여 백로그에 넣어 활성 단계 순서 외부에 보관합니다.
```bash
/gsd-capture --backlog "GraphQL API layer" # Creates 999.1-graphql-api-layer/
/gsd-capture --backlog "Mobile responsive" # Creates 999.2-mobile-responsive/
```
백로그 항목은 전체 단계 디렉터리를 갖추므로, `/gsd-discuss-phase 999.1`로 아이디어를 더 탐색하거나 준비가 되면 `/gsd-plan-phase 999.1`을 사용할 수 있습니다.
**검토 및 승격**은 `/gsd-review-backlog`으로 합니다 — 모든 백로그 항목을 표시하고 승격(활성 순서로 이동), 유지(백로그에 남기기), 제거(삭제) 중 선택할 수 있습니다.
### 씨드
씨드는 트리거 조건이 있는 미래 지향적 아이디어입니다. 백로그 항목과 달리, 씨드는 적절한 마일스톤이 도래하면 자동으로 표시됩니다.
```bash
/gsd-capture --seed "Add real-time collab when WebSocket infra is in place"
```
`/gsd-new-milestone`은 모든 씨드를 스캔하고 매칭 항목을 표시합니다. **저장소:** `.planning/seeds/SEED-NNN-slug.md`
### 지속적 컨텍스트 스레드
스레드는 여러 세션에 걸쳐 있지만 특정 단계에 속하지 않는 작업을 위한 경량 세션 간 지식 저장소입니다.
```bash
/gsd-thread # List all threads
/gsd-thread fix-deploy-key-auth # Resume existing thread
/gsd-thread "Investigate TCP timeout" # Create new thread
```
스레드가 성숙해지면 단계(`/gsd-phase`) 또는 백로그 항목(`/gsd-capture --backlog`)으로 승격할 수 있습니다. **저장소:** `.planning/threads/{slug}.md`
---
## 워크스트림 및 워크스페이스
워크스트림과 워크스페이스 모두 격리를 제공하지만, 수준이 다릅니다.
**워크스트림**은 동일한 코드베이스와 git 히스토리를 공유하지만 계획 아티팩트를 격리합니다 — 더 가볍고, 여러 마일스톤 영역을 동시에 작업할 때 적합합니다. [워크스트림으로 병렬 작업](how-to/work-in-parallel-with-workstreams.md)을 참조하세요.
**워크스페이스**는 자체 `.planning/`을 가진 별도의 리포지토리 워크트리를 생성합니다 — 더 무겁고, 피처 브랜치 또는 멀티 리포지토리 격리에 적합합니다. [워크스페이스로 작업 격리](how-to/isolate-work-with-workspaces.md)를 참조하세요.
| 명령어 | 목적 |
| ---------------------------------- | ---------------------------------------------------- |
| `/gsd-workstreams create <name>` | 격리된 계획 상태로 새 워크스트림 생성 |
| `/gsd-workstreams switch <name>` | 활성 컨텍스트를 다른 워크스트림으로 전환 |
| `/gsd-workstreams list` | 모든 워크스트림과 활성 상태 표시 |
| `/gsd-workstreams complete <name>` | 워크스트림을 완료로 표시하고 상태 아카이브 |
```bash
# Workspace example — feature branch isolation
/gsd-workspace --new --name feature-b --repos .
cd ~/gsd-workspaces/feature-b
/gsd-new-project
/gsd-workspace --list
/gsd-workspace --remove feature-b
```
---
## 보안
### 심층 방어 (v1.27)
GSD는 LLM 시스템 프롬프트가 되는 마크다운 파일을 생성합니다. 즉, 계획 아티팩트로 유입되는 사용자 제어 텍스트는 잠재적인 간접 프롬프트 인젝션 벡터입니다. v1.27은 중앙화된 보안 강화를 도입했습니다:
**경로 순회 방지:** 모든 사용자가 제공한 파일 경로(`--text-file`, `--prd`)는 프로젝트 디렉터리 내에서 확인됩니다. macOS `/var` → `/private/var` 심볼릭 링크 확인이 처리됩니다.
**프롬프트 인젝션 감지:** `security.cjs` 모듈은 사용자가 제공한 텍스트가 계획 아티팩트에 들어가기 전에 알려진 인젝션 패턴을 스캔합니다.
**런타임 훅:**
- `gsd-prompt-guard.js` — `.planning/`에 대한 Write/Edit 호출에서 인젝션 패턴 스캔 (항상 활성, 자문 전용)
- `gsd-workflow-guard.js` — GSD 워크플로우 컨텍스트 외부에서 파일 편집 시 경고 (`hooks.workflow_guard`를 통한 옵트인)
**CI 스캐너:** `prompt-injection-scan.security.test.cjs`는 모든 에이전트, 워크플로우, 명령어 파일에서 삽입된 인젝션 벡터를 스캔합니다.
---
### 패키지 적법성 게이트 (v1.42.1)
AI 코딩 도구는 패키지 이름을 환각합니다. 공격자는 npm, PyPI, crates.io에 악성 포스트 인스톨 스크립트가 포함된 그 이름을 미리 등록합니다 — 이를 *슬롭스쿼팅*이라 합니다. v1.42.1은 이것이 셸에 도달하기 전에 차단하는 3계층 게이트를 추가합니다.
**RESEARCH.md에서** — 외부 패키지를 권장하는 모든 단계에는 `## Package Legitimacy Audit` 테이블이 포함됩니다:
```markdown
## Package Legitimacy Audit
| Package | Registry | Age | Downloads | Source Repo | slopcheck | Disposition |
|---------|----------|-----|-----------|-------------|-----------|-------------|
| express | npm | 13 yrs | 100M+/wk | github.com/expressjs/express | [OK] | Approved |
| some-new-util | npm | 3 days | 47 | none | [SLOP] | REMOVED |
| api-bridge | npm | 6 mo | 1.2k/wk | github.com/user/api-bridge | [SUS] | Flagged |
```
`[SLOP]` 패키지는 RESEARCH.md에서 완전히 제거되며 계획자에게 도달하지 않습니다.
**PLAN.md에서** — `[SUS]` 또는 `[ASSUMED]` 패키지는 설치 전에 `checkpoint:human-verify` 작업을 트리거합니다.
**실행 중** — 설치가 실패하면 실행자는 체크포인트를 표시하고 자동으로 대안을 시도하지 않고 중단합니다.
**슬롭체크 판정:**
| 판정 | 의미 | GSD 조치 |
|---------|---------|------------|
| `[OK]` | 모든 적법성 검사 통과 | 진행 — 체크포인트 없음 |
| `[SUS]` | 의심스러운 신호 | 표시됨; 계획자가 `checkpoint:human-verify` 추가 |
| `[SLOP]` | 고신뢰 환각 | RESEARCH.md에서 제거; 계획자에게 도달하지 않음 |
슬롭체크를 수동으로 설치하려면:
```bash
pip install slopcheck
# verify: slopcheck install express --json
```
---
## 코드 리뷰 워크플로우
단계 실행 후 UAT 전에 구조화된 코드 리뷰를 실행하세요. 전체 워크플로우는 [크로스 AI 리뷰 설정](how-to/set-up-cross-ai-review.md)을 참조하세요.
```bash
/gsd-code-review 3 # Review all changed files in phase 3
/gsd-code-review 3 --depth=deep # Deep cross-file review
/gsd-code-review 3 --fix # Fix Critical + Warning findings atomically
/gsd-code-review 3 --fix --auto # Fix and re-review until clean (max 3 iterations)
/gsd-audit-fix # Audit + classify + fix (medium+ severity, max 5)
```
리뷰 단계는 실행 후, UAT 전에 삽입됩니다:
```text
/gsd-execute-phase N -> /gsd-code-review N -> /gsd-code-review N --fix -> /gsd-verify-work N
```
---
## 명령어 및 구성 레퍼런스
- **명령어 레퍼런스:** 모든 안정적 명령어의 플래그, 서브명령어, 예시는 [`docs/COMMANDS.md`](COMMANDS.md)를 참조하세요.
- **구성 레퍼런스:** 전체 `config.json` 스키마, 모델 프로필 테이블, git 브랜치 전략, 보안 설정은 [`docs/CONFIGURATION.md`](CONFIGURATION.md)를 참조하세요.
- **Discuss 모드:** 인터뷰 vs 가정 모드는 [`docs/workflow-discuss-mode.md`](workflow-discuss-mode.md)를 참조하세요.
---
## 사용 예시
### 새 프로젝트 (전체 사이클)
```bash
claude --dangerously-skip-permissions
/gsd-new-project # Answer questions, configure, approve roadmap
/clear
/gsd-discuss-phase 1 # Lock in your preferences
/gsd-ui-phase 1 # Design contract (frontend phases)
/gsd-plan-phase 1 # Research + plan + verify
/gsd-execute-phase 1 # Parallel execution
/gsd-verify-work 1 # Manual UAT
/gsd-ship 1 # Create PR from verified work
/gsd-ui-review 1 # Visual audit (frontend phases)
/clear
/gsd-progress --next # Auto-detect and run next step
...
/gsd-audit-milestone # Check everything shipped
/gsd-complete-milestone # Archive, tag, done
/gsd-pause-work --report # Generate session summary
```
### 기존 문서로 새 프로젝트
```bash
/gsd-new-project --auto @prd.md # Auto-runs research/requirements/roadmap from your doc
/clear
/gsd-discuss-phase 1 # Normal flow from here
```
### 기존 코드베이스
```bash
/gsd-map-codebase # Analyse what exists (parallel agents)
/gsd-new-project # Questions focus on what you're ADDING
# (normal phase workflow from here)
```
**실행 후 드리프트 감지 (#2003).** 매 `/gsd-execute-phase` 후, GSD는 단계가 `.planning/codebase/STRUCTURE.md`를 오래되게 만들 만큼 충분한 구조적 변경을 도입했는지 확인합니다. 다음으로 동작을 변경할 수 있습니다:
```bash
/gsd-settings workflow.drift_action auto-remap # remap automatically
/gsd-settings workflow.drift_threshold 5 # tune sensitivity
```
### 계획 드리프트 가드
**기본 활성화.** 계획 드리프트 가드(`plan_review.source_grounding: true`)는 계획 검토 중에 실행되며, 계획에 인용된 모든 심볼 — 데코레이터, 클래스, 함수, CLI 플래그 — 이 검토 시점에 실제로 소스 트리에 존재하는지 확인합니다. 이는 실행 에이전트가 실행되기 전에 환각된 이름을 잡아냅니다.
**감지 대상:**
- 소스에 존재하지 않는 PLAN.md 단계에서 참조된 함수
- 계획 작성 이후 이름이 변경되거나 제거된 클래스 또는 데코레이터 이름
- 인수 파서에 정의되지 않은 계획의 CLI 플래그
- 아무 파일로도 확인되지 않는 구현 단계에서 인용된 모듈 경로
**needs-acknowledgement 동작.** 가드가 누락된 심볼을 발견하면, 하드 차단 대신 계획 검토 출력에 `needs-acknowledgement` 알림을 표시합니다. 승인 후 진행하거나(심볼이 의도적으로 새로운 것일 수 있음) 계획 수정을 요청할 수 있습니다. 가드는 계획을 자동으로 거부하지 않으며 — 사람의 결정을 위한 신호를 표시합니다.
**인텔 없이 작동.** 기본적으로 가드는 `grep`/`ripgrep`을 사용하여 소스 파일을 검색합니다 — 사전 인덱싱이 필요하지 않습니다. `intel.enabled: true`로 `/gsd:map-codebase`를 실행했다면 `plan_review.source_grounding_authority: intel`로 설정하여 더 빠른 사전 빌드 `api-map.json` 인덱스를 사용하세요.
```bash
# Enable/disable (default: on)
/gsd-settings plan_review.source_grounding true
/gsd-settings plan_review.source_grounding false
# Switch resolver authority
/gsd-settings plan_review.source_grounding_authority grep # live grep (default)
/gsd-settings plan_review.source_grounding_authority intel # pre-indexed api-map.json
```
프로젝트 설정 시(`/gsd:new-project`가 워크플로우 선호도 중 질문) 또는 `/gsd:settings`를 통해 언제든지 전환 가능합니다(계획 섹션 → 드리프트 가드).
### 빠른 버그 수정
```bash
/gsd-quick
> "Fix the login button not responding on mobile Safari"
```
### 휴식 후 재개
```bash
/gsd-progress # See where you left off and what's next
# or
/gsd-resume-work # Full context restoration from last session
```
### 릴리스 준비
```bash
/gsd-audit-milestone # Check requirements coverage, detect stubs
/gsd-complete-milestone # Archive, tag, done
```
### 속도 vs 품질 프리셋
| 시나리오 | 모드 | 세분화 | 프로필 | 리서치 | 계획 검사 | 검증기 |
| ----------- | ------------- | ----------- | ---------- | -------- | ---------- | -------- |
| 프로토타이핑 | `yolo` | `coarse` | `budget` | off | off | off |
| 일반 개발 | `interactive` | `standard` | `balanced` | on | on | on |
| 프로덕션 | `interactive` | `fine` | `quality` | on | on | on |
**자율 모드에서 discuss 단계 건너뛰기:** `yolo` 모드로 실행할 때는 `/gsd-settings`를 통해 `workflow.skip_discuss: true`로 설정하세요.
### 마일스톤 중간 범위 변경
```bash
/gsd-phase # Append a new phase to the roadmap (default mode)
/gsd-phase --insert 3 # Insert urgent work between phases 3 and 4
/gsd-phase --remove 7 # Descope phase 7 and renumber
/gsd-phase --edit 4 # Edit any field of phase 4 in place
```
---
## 문제 해결
포괄적인 문제 해결 가이드는 [복구 및 문제 해결](how-to/recover-and-troubleshoot.md)을 참조하세요. 가장 일반적인 문제들이 아래에 요약되어 있습니다.
### 프로그래밍 방식 CLI (`gsd-tools query` vs `gsd-tools.cjs`)
자동화를 위해서는 등록된 서브명령어와 함께 **`gsd-tools query`**를 사용하세요([CLI-TOOLS.md — SDK 및 프로그래밍 방식 액세스](CLI-TOOLS.md#sdk-and-programmatic-access)와 QUERY-HANDLERS.md 참조). 레거시 `node $HOME/.claude/get-shit-done/bin/gsd-tools.cjs` CLI도 계속 지원됩니다.
### STATE.md 동기화 오류
```bash
node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" state validate # Detect drift
node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" state sync --verify # Preview changes
node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" state sync # Reconstruct STATE.md
```
### "Spawning..." 이후 명령어가 멈춘 것처럼 보일 때
GSD 서브에이전트는 별도의 컨텍스트 창에서 실행됩니다 — 진행 중에는 부모 세션에서 보이지 않습니다. 세션을 중단하지 마세요. 결과를 기다리세요; 리서치 및 계획 에이전트는 일반적으로 1~5분이 소요됩니다.
### 긴 세션 중 컨텍스트 저하
주요 명령어 사이에 컨텍스트 창을 지우세요: Claude Code에서 `/clear`. GSD는 새로운 컨텍스트를 중심으로 설계되었습니다 — 모든 서브에이전트는 새로운 200K 창을 받습니다. 지운 후 상태를 복원하려면 `/gsd-resume-work` 또는 `/gsd-progress`를 사용하세요.
### 계획이 잘못되거나 정렬되지 않은 것 같을 때
계획 전에 `/gsd-discuss-phase [N]`을 실행하세요. 대부분의 계획 품질 문제는 `CONTEXT.md`가 방지했을 가정을 Claude가 만들어서 발생합니다.
### 실행 실패 또는 스텁 생성
계획이 너무 야심 찼는지 확인하세요. 계획에는 최대 2~3개의 작업이 있어야 합니다. 더 작은 범위로 재계획하세요.
### 현재 위치를 놓쳤을 때
`/gsd-progress`를 실행하세요. 모든 상태 파일을 읽고 정확히 어디에 있는지, 다음에 무엇을 해야 하는지 알려줍니다.
### 모델 비용이 너무 높을 때
예산 프로필로 전환하세요: `/gsd-config --profile budget`. 도메인이 익숙하다면 `/gsd-settings`를 통해 리서치 및 계획 검사 에이전트를 비활성화하세요.
### 단계별 모델 비용 조정 (`models`) — v1.40에서 추가됨
`.planning/config.json`에 `models` 블록을 추가하세요:
```json
{
"model_profile": "balanced",
"models": {
"planning": "opus",
"discuss": "opus",
"research": "sonnet",
"execution": "opus",
"verification": "sonnet",
"completion": "sonnet"
}
}
```
에이전트별 예외가 필요한가요? 옆에 `model_overrides`를 추가하세요 — `models`보다 우선합니다:
```json
{
"models": { "research": "sonnet" },
"model_overrides": {
"gsd-codebase-mapper": "haiku"
}
}
```
전체 매핑 테이블과 해결 우선순위 규칙은 [단계 유형별 모델](CONFIGURATION.md#per-phase-type-models-models--added-in-v140)을 참조하세요.
### `dynamic_routing`으로 기본 저렴한 비용 — v1.40에서 추가됨
```json
{
"dynamic_routing": {
"enabled": true,
"tier_models": {
"light": "haiku",
"standard": "sonnet",
"heavy": "opus"
},
"escalate_on_failure": true,
"max_escalations": 1
}
}
```
전체 에이전트 → 티어 매핑은 [동적 라우팅](CONFIGURATION.md#dynamic-routing-with-failure-tier-escalation-dynamic_routing--added-in-v140)을 참조하세요.
### 턴당 비용을 줄이기 위해 MCP 서버 정리
`model_profile` 또는 `models.<phase_type>`을 조정하기 전에, 하네스에서 어떤 **MCP 서버**가 활성화되어 있는지 감사하세요. 활성화된 모든 MCP 서버는 모든 턴에 도구 스키마를 주입합니다 — 대형 서버는 각각 20k+ 토큰을 소비할 수 있습니다.
이것은 **하네스 설정**이며, GSD 설정이 아닙니다. 토글은 `.claude/settings.json`에 있습니다:
```json
{
"enabledMcpjsonServers": ["context7"],
"disabledMcpjsonServers": ["playwright", "mac-tools"]
}
```
긴 단계 전 빠른 감사:
- 이 단계에 UI 작업이 없는데 브라우저/playwright 도구가 활성화되어 있나요?
- 필요하지 않은 플랫폼별 도구가 활성화되어 있나요?
- 다른 프로젝트에서 사용하던 프로젝트별 MCP가 여기서도 활성화되어 있나요?
비활성화된 서버는 이후 모든 턴에서 스키마를 제거합니다. MCP 정리는 `model_profile` 조정과 **복합**됩니다 — 두 레버는 가산적이며, MCP 절약은 오케스트레이터가 생성하는 모든 서브에이전트에서 즉시 나타납니다.
전체 감사, 하네스 레퍼런스, `model_profile`과의 구성 노트는 번들된 `context-budget.md` 레퍼런스의 [MCP 도구 스키마 비용](../../get-shit-done/references/context-budget.md#mcp-tool-schema-cost-harness-concern)을 참조하세요.
### 비 Claude 런타임 사용 (Codex, OpenCode, Gemini CLI, Kilo)
> **Codex CLI 최소 지원 버전: `0.130.0`** (이슈 [#3562](https://github.com/open-gsd/gsd-core/issues/3562)).
비 Claude 런타임용으로 GSD를 설치했다면, 설치 프로그램이 이미 모델 해석을 구성했습니다. 수동 설정이 필요하지 않습니다 — `resolve_model_ids: "omit"`이 자동으로 설정되어 GSD가 Anthropic 모델 ID 해석을 건너뛰고 런타임이 자체 기본 모델을 선택하도록 합니다.
비 Claude 런타임에서 다른 모델을 할당하려면:
```json
{
"resolve_model_ids": "omit",
"model_overrides": {
"gsd-planner": "o3",
"gsd-executor": "o4-mini",
"gsd-debugger": "o3"
}
}
```
#### 하나의 구성 변경으로 Claude에서 Codex로 전환 (#2517)
```json
{
"runtime": "codex",
"model_profile": "balanced"
}
```
[런타임 인식 프로필](CONFIGURATION.md#runtime-aware-profiles-2517)을 참조하세요.
### 수동 설치 / Node.js 없는 설정
GSD 설치 프로그램을 실행할 수 없다면, `agents/`의 소스 파일을 직접 사용할 수 없습니다 — 이는 Claude Code의 네이티브 frontmatter 형식입니다. OpenCode의 경우 두 가지 변환이 필요합니다:
| 필드 | GSD 소스 형식 | OpenCode 유효 형식 | 조치 |
|---|---|---|---|
| `tools:` | `Read, Bash, Grep` (콤마 문자열) | frontmatter 필드가 아님 | `tools:` 줄 전체 제거 |
| `color:` | 일반 CSS 색상 이름 | 16진수 또는 OpenCode 의미 이름 | 16진수로 변환하거나 제거 |
**대안:** Node.js가 있는 모든 머신에서 설치 프로그램 실행:
```bash
npx @opengsd/gsd-core@latest --opencode --global
```
### Cline용 설치
```bash
npx @opengsd/gsd-core --cline --global # applies to all projects
npx @opengsd/gsd-core --cline --local # this project only
```
### CodeBuddy용 설치
```bash
npx @opengsd/gsd-core --codebuddy --global
```
### Qwen Code용 설치
```bash
npx @opengsd/gsd-core --qwen --global
```
### 프리릴리스 에디션 설치
설치 프로그램 실행 전에 런타임의 `*_CONFIG_DIR` 환경 변수를 프리릴리스 디렉터리로 설정하세요:
```bash
WINDSURF_CONFIG_DIR=~/.codeium/windsurf-next npx @opengsd/gsd-core@latest --windsurf --global
```
**지원 런타임의 환경 변수 레퍼런스:**
| 런타임 | 안정 기본값 | 재정의 환경 변수 |
|---|---|---|
| Claude Code | `~/.claude` | `CLAUDE_CONFIG_DIR` |
| Gemini CLI | `~/.gemini` | `GEMINI_CONFIG_DIR` |
| OpenCode | `XDG_CONFIG_HOME/opencode` | `OPENCODE_CONFIG_DIR` |
| Codex | (Codex CLI에 따름) | `--config-dir` 플래그 |
| Copilot | `~/.copilot` | `COPILOT_CONFIG_DIR` |
| Cursor | `~/.cursor` | `CURSOR_CONFIG_DIR` |
| Windsurf | `~/.codeium/windsurf` | `WINDSURF_CONFIG_DIR` |
| Antigravity | 자동 감지 | `ANTIGRAVITY_CONFIG_DIR` |
| Augment | `~/.augment` | `AUGMENT_CONFIG_DIR` |
| Trae | `~/.trae` | `TRAE_CONFIG_DIR` |
| Qwen Code | `~/.qwen` | `QWEN_CONFIG_DIR` |
| Kilo | `~/.config/kilo` | `KILO_CONFIG_DIR` |
| CodeBuddy | `~/.codebuddy` | `CODEBUDDY_CONFIG_DIR` |
| Cline | `~/.cline` | `CLINE_CONFIG_DIR` |
### 비 Anthropic 프로바이더와 Claude Code 사용
`inherit` 프로필로 전환하세요: `/gsd-config --profile inherit`. 이렇게 하면 모든 에이전트가 현재 세션 모델을 사용합니다.
### 민감/비공개 프로젝트 작업
`/gsd-new-project` 중 또는 `/gsd-settings`를 통해 `commit_docs: false`로 설정하세요. `.planning/`을 `.gitignore`에 추가하세요.
### GSD 업데이트가 로컬 변경사항을 덮어씀
v1.17부터 설치 프로그램은 로컬에서 수정된 파일을 `gsd-local-patches/`에 백업합니다. 변경사항을 다시 병합하려면 `/gsd-update --reapply`를 실행하세요.
### npm을 통해 업데이트할 수 없음
단계별 수동 업데이트 절차는 [docs/manual-update.md](../manual-update.md)를 참조하세요.
### 워크플로우 진단 (`/gsd-forensics`)
워크플로우가 명확하지 않은 방식으로 실패하면 `/gsd-forensics`를 실행하여 git 히스토리 이상, 아티팩트 무결성, 상태 불일치를 포함한 진단 보고서를 생성하세요. 출력은 `.planning/forensics/`로 이동합니다.
### 실행기 서브에이전트가 Bash 명령어에서 "Permission denied" 발생
`~/.claude/settings.json`에 필요한 패턴을 추가하세요. 모든 스택에 필요한 핵심 패턴:
```json
"Bash(git add:*)",
"Bash(git commit:*)",
"Bash(git merge:*)",
"Bash(git worktree:*)",
"Bash(git rebase:*)",
"Bash(git reset:*)",
"Bash(git checkout:*)",
"Bash(git switch:*)",
"Bash(git restore:*)",
"Bash(git stash:*)",
"Bash(git rm:*)",
"Bash(git mv:*)",
"Bash(git fetch:*)",
"Bash(git cherry-pick:*)",
"Bash(git apply:*)",
"Bash(gh:*)"
```
**프로젝트별 권한:** `~/.claude/settings.json` 대신 프로젝트 루트의 `.claude/settings.local.json`에 동일한 `permissions.allow` 블록을 추가하세요.
### 병렬 실행으로 빌드 잠금 오류 발생
GSD는 v1.26부터 이를 자동으로 처리합니다. 이전 버전을 사용 중이라면 프로젝트의 `CLAUDE.md`에 다음을 추가하세요:
```markdown
## Git Commit Rules for Agents
All subagent/executor commits MUST use `--no-verify`.
```
병렬 실행을 완전히 비활성화하려면: `/gsd-settings` → `parallelization.enabled`를 `false`로 설정하세요.
---
## 복구 빠른 참조
| 문제 | 해결책 |
| ------------------------------------ | ------------------------------------------------------------------------ |
| 컨텍스트 손실 / 새 세션 | `/gsd-resume-work` 또는 `/gsd-progress` |
| 단계가 잘못됨 | 단계 커밋을 `git revert`한 후 재계획 |
| 범위 변경 필요 | `/gsd-phase` (기본), `/gsd-phase --insert`, 또는 `/gsd-phase --remove` |
| 무언가 고장남 | `/gsd-debug "description"` (수정 없이 분석만 하려면 `--diagnose` 추가) |
| STATE.md 동기화 오류 | `state validate` 후 `state sync` |
| 워크플로우 상태가 손상된 것 같음 | `/gsd-forensics` |
| 빠른 목표 수정 | `/gsd-quick` |
| 계획이 비전과 맞지 않음 | `/gsd-discuss-phase [N]` 후 재계획 |
| 비용이 높아짐 | `/gsd-config --profile budget` 및 `/gsd-settings`로 에이전트 끄기 |
| 업데이트가 로컬 변경사항을 손상시킴 | `/gsd-update --reapply` |
| 이해관계자를 위한 세션 요약 필요 | `/gsd-pause-work --report` |
| 다음 단계를 모름 | `/gsd-progress --next` |
| 병렬 실행 빌드 오류 | GSD 업데이트 또는 `parallelization.enabled: false` 설정 |
---
## 프로젝트 파일 구조
```text
.planning/
PROJECT.md # Project vision and context (always loaded)
REQUIREMENTS.md # Scoped v1/v2 requirements with IDs
ROADMAP.md # Phase breakdown with status tracking
STATE.md # Decisions, blockers, session memory
config.json # Workflow configuration
MILESTONES.md # Completed milestone archive
HANDOFF.json # Structured session handoff (from /gsd-pause-work)
research/ # Domain research from /gsd-new-project
reports/ # Session reports (from /gsd-pause-work --report)
todos/
pending/ # Captured ideas awaiting work
done/ # Completed todos
debug/ # Active debug sessions
resolved/ # Archived debug sessions
spikes/ # Feasibility experiments (from /gsd-spike)
NNN-name/ # Experiment code + README with verdict
MANIFEST.md # Index of all spikes
sketches/ # HTML mockups (from /gsd-sketch)
NNN-name/ # index.html (2-3 variants) + README
themes/
default.css # Shared CSS variables for all sketches
MANIFEST.md # Index of all sketches with winners
codebase/ # Brownfield codebase mapping (from /gsd-map-codebase)
phases/
XX-phase-name/
XX-YY-PLAN.md # Atomic execution plans
XX-YY-SUMMARY.md # Execution outcomes and decisions
CONTEXT.md # Your implementation preferences
RESEARCH.md # Ecosystem research findings
VERIFICATION.md # Post-execution verification results
XX-UI-SPEC.md # UI design contract (from /gsd-ui-phase)
XX-UI-REVIEW.md # Visual audit scores (from /gsd-ui-review)
ui-reviews/ # Screenshots from /gsd-ui-review (gitignored)
```
---
## 관련 문서
- [문서 인덱스](README.md)
- [명령어](COMMANDS.md)
- [구성](CONFIGURATION.md)
- [단계 루프](explanation/the-phase-loop.md)
Reference in New Issue View Git Blame Copy Permalink