golem15/msd-core
4
0
Fork 0
Code Issues 1 Pull Requests Actions 3 Packages Projects Releases Wiki Activity

docs: rebrand to GSD Core and restructure docs with Diataxis (#605)

Browse Source 
* chore: wire docs/agents config into AGENTS.md Agent skills section

Add the `## Agent skills` discovery block pointing the engineering
skills at the existing docs/agents/{issue-tracker,triage-labels,domain}.md
files (issue tracker, triage label mapping, single-context domain docs).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* docs: rebrand to GSD Core and restructure docs with Diataxis

Reorganise the root README and docs/ around the Diataxis framework
(tutorials, how-to guides, reference, explanation), add new how-to
guides and schema references (STATE.md / CONTEXT.md / PLAN.md /
planning artifacts), and cross-link the whole set. Update the lone
legacy gsd-build reference to open-gsd; keep internal get-shit-done/
filesystem paths unchanged (directory rename tracked separately in
open-gsd/gsd-core#604). Regenerate the ja-JP, ko-KR, pt-BR and zh-CN
localised trees to mirror the new structure.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* docs: backfill changeset PR number (#605)

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Tom Boucher
2026-06-02 08:13:09 -04:00
committed by GitHub
parent 8c47dcb1c1
commit 3bb2f8f1c5
200 changed files with 46813 additions and 8415 deletions
Download Patch File Download Diff File Expand all files Collapse all files

651
docs/ko-KR/ARCHITECTURE.md
View File

@@ -1,6 +1,6 @@
# GSD 아키텍처
# GSD Core 아키텍처
> 기여자와 고급 사용자를 위한 시스템 아키텍처입니다. 사용자 문서는 [Feature Reference](FEATURES.md) 또는 [User Guide](USER-GUIDE.md)를 참조하세요.
> 기여자와 고급 사용자를 위한 시스템 아키텍처. 사용자 문서는 [기능 레퍼런스](FEATURES.md) 또는 [사용자 가이드](USER-GUIDE.md)를 참조하라.
---
@@ -21,12 +21,12 @@
## 시스템 개요
GSD는 사용자와 AI 코딩 에이전트(Claude Code, Gemini CLI, OpenCode, Kilo, Codex, Copilot, Antigravity, Trae, Cline, Augment Code) 사이에 위치하는 **메타 프롬프팅 프레임워크**입니다. 다음을 제공합니다.
GSD Core는 사용자와 AI 코딩 에이전트(Claude Code, Gemini CLI, OpenCode, Kilo, Codex, Copilot, Antigravity, Trae, Cline, Augment Code) 사이에 위치하는 **메타 프롬프팅 프레임워크**이다. 다음을 제공한다:
1. **컨텍스트 엔지니어링** — 작업별로 AI에게 필요한 모든 것을 제공하는 구조화된 아티팩트
2. **멀티 에이전트 오케스트레이션** — 새로운 컨텍스트 윈도우로 전문화된 에이전트를 생성하는 가벼운 오케스트레이터
3. **명세 주도 개발** — 요구 사항 → 조사 → 계획 → 실행 → 검증 파이프라인
4. **상태 관리** — 세션과 컨텍스트 초기화를 넘나드는 영구적인 프로젝트 메모리
1. **컨텍스트 엔지니어링** — 작업별로 AI에게 필요한 모든 것을 제공하는 구조화된 결과물([컨텍스트 엔지니어링](explanation/context-engineering.md) 참조)
2. **다중 에이전트 오케스트레이션** — 신선한 컨텍스트 윈도우로 전문화된 에이전트를 생성하는 얇은 오케스트레이터([다중 에이전트 오케스트레이션](explanation/multi-agent-orchestration.md) 참조)
3. **명세 주도 개발** — 요구 사항 → 리서치 → 계획 → 실행 → 검증 파이프라인
4. **상태 관리** — 세션과 컨텍스트 리셋 전반에 걸친 영구적인 프로젝트 메모리
```
┌──────────────────────────────────────────────────────┐
@@ -54,8 +54,8 @@ GSD는 사용자와 AI 코딩 에이전트(Claude Code, Gemini CLI, OpenCode, Ki
│ │ │
┌──────▼──────────────▼─────────────────▼──────────────┐
│ CLI TOOLS LAYER │
│ get-shit-done/bin/gsd-tools.cjs │
│ (State, config, phase, roadmap, verify, templates) │
│ gsd-tools.cjs command families + domain modules │
│ command-routing-hub + observability seams │
└──────────────────────┬───────────────────────────────┘
│
┌──────────────────────▼───────────────────────────────┐
@@ -69,36 +69,39 @@ GSD는 사용자와 AI 코딩 에이전트(Claude Code, Gemini CLI, OpenCode, Ki
## 설계 원칙
### 1. 에이전트별 새로운 컨텍스트
### 1. 에이전트별 신선한 컨텍스트
오케스트레이터가 생성하는 모든 에이전트는 새로운 컨텍스트 윈도우(최대 200K 토큰)를 받습니다. 이를 통해 컨텍스트 오염을 방지합니다 — AI가 컨텍스트 윈도우에 누적된 대화로 인해 품질이 저하되는 현상입니다.
오케스트레이터가 생성하는 모든 에이전트는 깨끗한 컨텍스트 윈도우(최대 200K 토큰)를 받는다. 이는 컨텍스트 부패 — AI가 컨텍스트 윈도우를 누적된 대화로 채울 때 발생하는 품질 저하 — 를 제거한다.
### 2. 가벼운 오케스트레이터
### 2. 얇은 오케스트레이터
워크플로우 파일(`get-shit-done/workflows/*.md`)은 무거운 작업을 직접 수행하지 않습니다. 다음 작업만 담당합니다.
- `gsd-tools.cjs init <workflow>`로 컨텍스트를 로드합니다
- 집중된 프롬프트로 전문화된 에이전트를 생성합니다
- 결과를 수집하여 다음 단계로 전달합니다
- 단계 사이에 상태를 업데이트합니다
워크플로우 파일(`get-shit-done/workflows/*.md`)은 무거운 작업을 직접 수행하지 않는다. 오케스트레이터가 하는 것:
- `gsd-tools.cjs init <workflow>`로 컨텍스트 로드
- 집중된 프롬프트로 전문화된 에이전트 생성
- 결과 수집 및 다음 단계로 라우팅
- 단계 사이에 상태 업데이트
### 3. 파일 기반 상태
모든 상태는 `.planning/`에 사람이 읽을 수 있는 Markdown과 JSON으로 저장됩니다. 데이터베이스, 서버, 외부 의존성이 없습니다. 이를 통해 다음이 가능합니다.
- 컨텍스트 초기화(`/clear`) 이후에도 상태가 유지됩니다
- 사람과 에이전트 모두 상태를 확인할 수 있습니다
- 팀 가시성을 위해 git에 커밋할 수 있습니다
모든 상태는 `.planning/`에 사람이 읽을 수 있는 마크다운과 JSON으로 저장된다. 데이터베이스도, 서버도, 외부 의존성도 없다. 이것이 의미하는 바:
- 컨텍스트 리셋(`/clear`) 이후에도 상태가 유지된다
- 사람과 에이전트 모두 상태를 확인할 수 있다
- 팀 가시성을 위해 git에 커밋할 수 있다
### 4. 부재 = 활성화
워크플로우 기능 플래그는 **부재 = 활성화** 패턴을 따릅니다. `config.json`에 키가 없으면 기본값은 `true`입니다. 사용자는 기능을 명시적으로 비활성화하며 기본값을 활성화할 필요가 없습니다.
워크플로우 기능 플래그는 **부재 = 활성화** 패턴을 따른다. `config.json`에 키가 없으면 기본값은 `true`이다. 사용자는 기능을 명시적으로 비활성화하며; 기본값을 활성화할 필요가 없다.
### 5. 심층 방어
여러 레이어가 일반적인 실패 모드를 방지합니다.
- 계획은 실행 전에 검증됩니다 (plan-checker 에이전트)
- 실행은 작업당 원자적 커밋을 생성합니다
- 실행 후 검증은 단계 목표에 대해 확인합니다
- UAT는 최종 게이트로서 사람의 검증을 제공합니다
여러 계층이 일반적인 실패 모드를 방지한다:
- 계획은 실행 전에 검증된다 (plan-checker 에이전트)
- 실행은 작업당 원자적 커밋을 생성한다
- 실행 후 검증은 단계 목표에 대해 확인한다
- UAT는 최종 게이트로서 사람 검증을 제공한다
---
@@ -106,51 +109,121 @@ GSD는 사용자와 AI 코딩 에이전트(Claude Code, Gemini CLI, OpenCode, Ki
### Commands (`commands/gsd/*.md`)
사용자 대면 진입점입니다. 각 파일은 YAML 전문(name, description, allowed-tools)과 워크플로우를 부트스트랩하는 프롬프트 본문을 포함합니다. 명령어는 다음과 같이 설치됩니다.
- **Claude Code:** 커스텀 슬래시 명령어 (`/gsd-command-name`)
- **OpenCode / Kilo:** 슬래시 명령어 (`/gsd-command-name`)
사용자 대면 진입점. 각 파일은 YAML 전문(name, description, allowed-tools)과 워크플로우를 부트스트랩하는 프롬프트 본문을 포함한다. 명령어는 다음과 같이 설치된다:
- **Claude Code:** 커스텀 슬래시 명령어 (하이픈 형식, `/gsd-command-name`)
- **OpenCode / Kilo:** 슬래시 명령어 (하이픈 형식, `/gsd-command-name`)
- **Codex:** Skills (`$gsd-command-name`)
- **Copilot:** 슬래시 명령어 (`/gsd-command-name`)
- **Copilot:** 슬래시 명령어 (하이픈 형식, `/gsd-command-name`)
- **Gemini CLI:** `gsd:` 네임스페이스 하의 슬래시 명령어 (콜론 형식, `/gsd:command-name`) — Gemini는 플러그인 id 아래 모든 커스텀 명령어를 네임스페이스화하므로 설치 경로가 모든 본문 텍스트 참조를 콜론 형식으로 다시 쓴다
- **Antigravity:** Skills
**전체 명령어 수:** 44개
**전체 명령어 수:** 권위 있는 개수와 전체 목록은 [`docs/INVENTORY.md`](INVENTORY.md#commands)를 참조하라.
#### 2단계 계층적 라우팅 (v1.40, [#2792](https://github.com/open-gsd/gsd-core/issues/2792))
열망적 스킬 목록 토큰 비용을 낮게 유지하기 위해 v1.40은 구체적인 하위 스킬 위에 계층화된 여섯 개의 네임스페이스 **메타 스킬** (`gsd-workflow`, `gsd-project`, `gsd-quality`, `gsd-context`, `gsd-manage`, `gsd-ideate` — `commands/gsd/ns-*.md`에서 소싱되지만 호출 가능한 `name:`은 여기 표시된 간단한 형식)을 도입한다. 모델은 평평한 86개 스킬 목록(~2,150 토큰) 대신 6개의 네임스페이스 라우터(~120 토큰)를 보고, 네임스페이스를 선택한 다음 네임스페이스 라우터 본문에 내장된 라우팅 테이블을 통해 구체적인 하위 스킬로 라우팅한다. 네임스페이스 스킬은 **가산적**이다 — 모든 구체적인 명령어는 여전히 직접 호출 가능하다.
라우터 설명은 ~40% 토큰 비용으로 프로세 대비 키워드 밀도 태그가 라우팅에서 더 뛰어나다는 Tool Attention 연구에 따라 도구당 파이프로 구분된 키워드 태그(≤ 60자)를 사용한다.
#### MCP 토큰 예산 상호작용
열망적 스킬 목록은 턴당 반복되는 두 가지 토큰 비용 중 하나이다. 다른 하나는 `.claude/settings.json`의 모든 활성화된 MCP 서버가 주입하는 MCP 도구 스키마이다. 무거운 MCP 서버(브라우저/playwright, Mac-tools, Windows-tools)는 각각 턴당 20k+ 토큰 비용이 들 수 있다 — 종종 `model_profile` 튜닝이 절약하는 것을 압도한다. 토글은 Claude Code 하니스(`.claude/settings.json`의 `enabledMcpjsonServers` / `disabledMcpjsonServers`)에 있으며 GSD 관심사가 아니다. 2단계 라우팅 계층(#2792)과 규율 있는 MCP 활성화를 함께 사용하는 것이 턴당 가장 큰 비용 레버이다. [`docs/USER-GUIDE.md`](USER-GUIDE.md)와 `references/context-budget.md`에서 감사 체크리스트를 참조하라.
### Workflows (`get-shit-done/workflows/*.md`)
명령어가 참조하는 오케스트레이션 로직입니다. 다음을 포함하는 단계별 프로세스를 담습니다.
- `gsd-tools.cjs init`을 통한 컨텍스트 로드
- 모델 해석을 포함한 에이전트 생성 지시
명령어가 참조하는 오케스트레이션 로직. 다음을 포함하는 단계별 프로세스를 담는다:
- `gsd-tools.cjs init` 핸들러를 통한 컨텍스트 로딩
- 모델 해결을 포함한 에이전트 생성 지시
- 게이트/체크포인트 정의
- 상태 업데이트 패턴
- 오류 처리 및 복구
**전체 워크플로우 수:** 46개
**전체 워크플로우 수:** 권위 있는 개수와 전체 목록은 [`docs/INVENTORY.md`](INVENTORY.md#workflows)를 참조하라.
#### 워크플로우를 위한 점진적 공개
워크플로우 파일은 해당 `/gsd-*` 명령어가 호출될 때마다 Claude의 컨텍스트에 그대로 로드된다. 이 비용을 제한하기 위해 `tests/workflow-size-budget.test.cjs`가 시행하는 워크플로우 크기 예산은 #2361의 에이전트 예산을 반영한다:
| 등급 | 파일당 줄 제한 |
|-----------|--------------------|
| `XL` | 1700 — 최상위 오케스트레이터 (`execute-phase`, `plan-phase`, `new-project`) |
| `LARGE` | 1500 — 다단계 플래너 및 대형 기능 워크플로우 |
| `DEFAULT` | 1000 — 집중된 단일 목적 워크플로우 (목표 등급) |
`workflows/discuss-phase.md`는 이슈 #2551에 따라 더 엄격한 <500줄 상한을 유지한다. 워크플로우가 등급을 초과하면 모드별 본문은 `workflows/<workflow>/modes/<mode>.md`로, 템플릿은 `workflows/<workflow>/templates/`로, 공유 지식은 `get-shit-done/references/`로 추출한다. 부모 파일은 현재 호출에 필요한 모드 및 템플릿 파일만 읽는 얇은 디스패처가 된다.
`workflows/discuss-phase/`가 이 패턴의 정규 예시이다 — 부모는 디스패치하고, modes/는 플래그별 동작(`power.md`, `all.md`, `auto.md`, `chain.md`, `text.md`, `batch.md`, `analyze.md`, `default.md`, `advisor.md`)을 담으며, templates/는 해당 출력 파일이 작성될 때만 읽히는 CONTEXT.md, DISCUSSION-LOG.md, checkpoint.json 스키마를 담는다.
### Agents (`agents/*.md`)
다음을 지정하는 전문화된 에이전트 정의 파일입니다.
다음을 지정하는 전문화된 에이전트 정의:
- `name` — 에이전트 식별자
- `description` — 역할과 목적
- `tools` — 허용된 도구 접근 권한 (Read, Write, Edit, Bash, Grep, Glob, WebSearch 등)
- `tools` — 허용된 도구 접근 (Read, Write, Edit, Bash, Grep, Glob, WebSearch 등)
- `color` — 시각적 구분을 위한 터미널 출력 색상
**전체 에이전트 수:** 16개
**전체 에이전트 수:** 33개
### References (`get-shit-done/references/*.md`)
워크플로우와 에이전트가 `@-reference`로 참조하는 공유 지식 문서입니다.
워크플로우와 에이전트가 `@-reference`하는 공유 지식 문서([`docs/INVENTORY.md`](INVENTORY.md#references-41-shipped)에서 권위 있는 개수와 전체 목록 참조):
**핵심 레퍼런스:**
- `checkpoints.md` — 체크포인트 유형 정의 및 상호작용 패턴
- `model-profiles.md` — 에이전트별 모델 티어 할당
- `verification-patterns.md` — 다양한 아티팩트 유형 검증 방법
- `gates.md` — plan-checker와 verifier에 연결된 4가지 정규 게이트 유형 (확인, 품질, 안전, 전환)
- `model-profiles.md` — 에이전트별 모델 등급 할당
- `model-profile-resolution.md` — 모델 해결 알고리즘 문서
- `verification-patterns.md` — 다양한 결과물 유형 검증 방법
- `verification-overrides.md` — 결과물별 검증 재정의 규칙
- `planning-config.md` — 전체 config 스키마 및 동작
- `git-integration.md` — git 커밋, 브랜칭, 히스토리 패턴
- `git-integration.md` — git 커밋, 브랜칭, 이력 패턴
- `git-planning-commit.md` — 계획 디렉터리 커밋 컨벤션
- `questioning.md` — 프로젝트 초기화를 위한 꿈 추출 철학
- `tdd.md` — 테스트 주도 개발 통합 패턴
- `ui-brand.md` — 시각적 출력 포매팅 패턴
- `ui-brand.md` — 시각적 출력 형식 패턴
- `common-bug-patterns.md` — 코드 리뷰 및 검증을 위한 일반적인 버그 패턴
**워크플로우 레퍼런스:**
- `agent-contracts.md` — 오케스트레이터와 에이전트 간의 공식 인터페이스
- `context-budget.md` — 컨텍스트 윈도우 예산 할당 규칙
- `continuation-format.md` — 세션 지속/재개 형식
- `domain-probes.md` — discuss-phase를 위한 도메인별 프로빙 질문
- `gate-prompts.md` — 게이트/체크포인트 프롬프트 템플릿
- `revision-loop.md` — 계획 수정 반복 패턴
- `universal-anti-patterns.md` — 탐지하고 피해야 할 일반적인 안티 패턴
- `artifact-types.md` — 계획 결과물 유형 정의
- `phase-argument-parsing.md` — 단계 인수 파싱 컨벤션
- `decimal-phase-calculation.md` — 소수 하위 단계 번호 매기기 규칙
- `workstream-flag.md` — 워크스트림 활성 포인터 컨벤션
- `user-profiling.md` — 사용자 행동 프로파일링 방법론
- `thinking-partner.md` — 의사 결정 포인트에서의 조건부 thinking partner 활성화
**Thinking 모델 레퍼런스:**
GSD 워크플로우에 thinking 클래스 모델(o3, o4-mini, Gemini 2.5 Pro)을 통합하기 위한 레퍼런스:
- `thinking-models-debug.md` — 디버깅 워크플로우를 위한 thinking 모델 패턴
- `thinking-models-execution.md` — 실행 에이전트를 위한 thinking 모델 패턴
- `thinking-models-planning.md` — 계획 에이전트를 위한 thinking 모델 패턴
- `thinking-models-research.md` — 리서치 에이전트를 위한 thinking 모델 패턴
- `thinking-models-verification.md` — 검증 에이전트를 위한 thinking 모델 패턴
**모듈식 플래너 분해:**
플래너 에이전트(`agents/gsd-planner.md`)는 일부 런타임에서 부과하는 50K 문자 제한 이하로 유지하기 위해 단일 모놀리식 파일에서 핵심 에이전트 + 레퍼런스 모듈로 분해되었다:
- `planner-gap-closure.md` — 갭 클로저 모드 동작 (VERIFICATION.md 읽기, 대상 재계획)
- `planner-reviews.md` — 교차 AI 리뷰 통합 (`/gsd-review`의 REVIEWS.md 읽기)
- `planner-revision.md` — 반복적 개선을 위한 계획 수정 패턴
### Templates (`get-shit-done/templates/`)
모든 계획 아티팩트를 위한 Markdown 템플릿입니다. `gsd-tools.cjs template fill`과 `scaffold` 명령어가 사전 구조화된 파일을 생성하는 데 사용합니다.
모든 계획 결과물을 위한 마크다운 템플릿. `gsd-tools.cjs template fill` / `phase.scaffold`(와 최상위 `scaffold`)가 사전 구조화된 파일을 생성하는 데 사용:
- `project.md`, `requirements.md`, `roadmap.md`, `state.md` — 핵심 프로젝트 파일
- `phase-prompt.md` — 단계 실행 프롬프트 템플릿
- `summary.md` (+ `summary-minimal.md`, `summary-standard.md`, `summary-complex.md`) — 세분화 인식 요약 템플릿
@@ -158,40 +231,60 @@ GSD는 사용자와 AI 코딩 에이전트(Claude Code, Gemini CLI, OpenCode, Ki
- `UI-SPEC.md`, `UAT.md`, `VALIDATION.md` — 전문화된 검증 템플릿
- `discussion-log.md` — 논의 감사 추적 템플릿
- `codebase/` — 브라운필드 매핑 템플릿 (stack, architecture, conventions, concerns, structure, testing, integrations)
- `research-project/` — 조사 출력 템플릿 (SUMMARY, STACK, FEATURES, ARCHITECTURE, PITFALLS)
- `research-project/` — 리서치 출력 템플릿 (SUMMARY, STACK, FEATURES, ARCHITECTURE, PITFALLS)
### Hooks (`hooks/`)
호스트 AI 에이전트와 통합되는 런타임 훅입니다.
호스트 AI 에이전트와 통합되는 런타임 훅:
| 훅 | 이벤트 | 목적 |
|------|-------|---------|
| `gsd-statusline.js` | `statusLine` | 모델, 작업, 디렉터리, 컨텍스트 사용 바 표시 |
| `gsd-context-monitor.js` | `PostToolUse` / `AfterTool` | 잔여 35%/25% 시점에 에이전트 대면 컨텍스트 경고 주입 |
| `gsd-check-update.js` | `SessionStart` | 새 GSD 버전을 백그라운드에서 확인 |
| `gsd-prompt-guard.js` | `PreToolUse` | `.planning/` 쓰기 작업에서 프롬프트 인젝션 패턴 스캔 (권고용) |
| `gsd-workflow-guard.js` | `PreToolUse` | GSD 워크플로우 컨텍스트 외부의 파일 편집 감지 (권고용, `hooks.workflow_guard`로 활성화) |
| `gsd-check-update.js` | `SessionStart` | 백그라운드 업데이트 확인을 위한 포어그라운드 트리거 |
| `gsd-check-update-worker.js` | (헬퍼) | `gsd-check-update.js`가 생성하는 백그라운드 워커; 직접 이벤트 등록 없음 |
| `gsd-prompt-guard.js` | `PreToolUse` | `.planning/` 쓰기에서 프롬프트 인젝션 패턴 스캔 (자문적) |
| `gsd-read-injection-scanner.js` | `PostToolUse` | 신뢰할 수 없는 콘텐츠에서 주입된 지시 사항을 위한 Read 도구 출력 스캔 |
| `gsd-workflow-guard.js` | `PreToolUse` | GSD 워크플로우 컨텍스트 외부의 파일 편집 감지 (자문적, `hooks.workflow_guard`를 통한 옵트인) |
| `gsd-read-guard.js` | `PreToolUse` | 세션에서 아직 읽지 않은 파일에 Edit/Write를 방지하는 자문적 가드 |
| `gsd-session-state.sh` | `PostToolUse` | 쉘 기반 런타임을 위한 세션 상태 추적 |
| `gsd-validate-commit.sh` | `PostToolUse` | 컨벤셔널 커밋 시행을 위한 커밋 검증 |
| `gsd-phase-boundary.sh` | `PostToolUse` | 워크플로우 전환을 위한 단계 경계 감지 |
권위 있는 11개 훅 목록은 [`docs/INVENTORY.md`](INVENTORY.md#hooks-11-shipped)를 참조하라.
### Command Routing Hub (`get-shit-done/bin/lib/command-routing-hub.cjs`)
CJS 명령어 패밀리 라우터는 `CommandRoutingHub`를 통해 디스패치한다. 허브는 no-throw 순수 결과 계약(`hub.dispatch()`는 내부 예외를 잡아 `{ ok: false, kind, ...typedPayload }`를 반환)과 닫힌 런타임 오류 분류(`UnknownCommand`, `InvalidArgs`, `HandlerRefusal`, `HandlerFailure`)를 소유한다. 라우터 어댑터는 얇은 CLI 번역기로 유지된다 — 허브를 구축하고, `dispatch`를 호출하고, 결과를 `output()`/`error()` 호출에 매핑한다. 런타임은 단일 경로이다(이중 런타임 모드 선택 없음). `docs/adr/0174-retire-gsd-sdk-package-boundary.md` 참조.
### CLI Tools (`get-shit-done/bin/`)
17개의 도메인 모듈을 포함하는 Node.js CLI 유틸리티(`gsd-tools.cjs`)입니다.
`get-shit-done/bin/lib/`에 걸쳐 분할된 도메인 모듈을 가진 Node.js CLI 유틸리티(`gsd-tools.cjs`)(권위 있는 목록은 [`docs/INVENTORY.md`](INVENTORY.md#cli-modules-33-shipped) 참조):
| 모듈 | 책임 |
| ---------------------- | --------------------------------------------------------------------------------------------------- |
| `core.cjs` | 오류 처리, 출력 형식, 공유 유틸리티; 계획 헬퍼를 위한 호환성 재내보내기 |
| `planning-workspace.cjs` | 계획 심(`planningDir`, `planningPaths`, 활성 워크스트림 라우팅, `.planning/.lock`) |
| `state.cjs` | STATE.md 파싱, 업데이트, 진행, 메트릭 |
| `phase.cjs` | 단계 디렉터리 작업, 소수 번호 매기기, 계획 인덱싱 |
| `roadmap.cjs` | ROADMAP.md 파싱, 단계 추출, 계획 진행 상황 |
| `config.cjs` | config.json 읽기/쓰기, 섹션 초기화 |
| `verify.cjs` | 계획 구조, 단계 완성도, 레퍼런스, 커밋 검증 |
| `template.cjs` | 변수 치환을 통한 템플릿 선택 및 채우기 |
| `frontmatter.cjs` | YAML 전문 CRUD 작업 |
| `init.cjs` | 각 워크플로우 유형을 위한 복합 컨텍스트 로딩 |
| `milestone.cjs` | 마일스톤 보관, 요구 사항 표시 |
| `commands.cjs` | 기타 명령어 (slug, timestamp, todos, scaffolding, stats) |
| `model-profiles.cjs` | 모델 프로필 해결 테이블 |
| `security.cjs` | 경로 탐색 방지, 프롬프트 인젝션 탐지, 안전한 JSON 파싱, 쉘 인수 검증 |
| `uat.cjs` | UAT 파일 파싱, 검증 부채 추적, audit-uat 지원 |
| `docs.cjs` | 문서 업데이트 워크플로우 초기화, 마크다운 스캔, 모노레포 감지 |
| `workstream.cjs` | 워크스트림 CRUD, 마이그레이션, 세션 범위 활성 포인터 |
| `schema-detect.cjs` | ORM 패턴에 대한 스키마 드리프트 감지 (Prisma, Drizzle 등) |
| `profile-pipeline.cjs` | 사용자 행동 프로파일링 데이터 파이프라인, 세션 파일 스캔 |
| `profile-output.cjs` | 프로필 렌더링, USER-PROFILE.md 및 dev-preferences.md 생성 |
| 모듈 | 역할 |
|--------|---------------|
| `core.cjs` | 오류 처리, 출력 포매팅, 공유 유틸리티 |
| `state.cjs` | STATE.md 파싱, 업데이트, 진행, 메트릭 |
| `phase.cjs` | 단계 디렉터리 작업, 소수 번호 매기기, 계획 인덱싱 |
| `roadmap.cjs` | ROADMAP.md 파싱, 단계 추출, 계획 진행 상황 |
| `config.cjs` | config.json 읽기/쓰기, 섹션 초기화 |
| `verify.cjs` | 계획 구조, 단계 완성도, 참조, 커밋 검증 |
| `template.cjs` | 변수 치환을 포함한 템플릿 선택 및 채우기 |
| `frontmatter.cjs` | YAML 전문 CRUD 작업 |
| `init.cjs` | 각 워크플로우 유형을 위한 복합 컨텍스트 로드 |
| `milestone.cjs` | 마일스톤 보관, 요구 사항 표시 |
| `commands.cjs` | 기타 명령어 (slug, timestamp, todos, scaffolding, stats) |
| `model-profiles.cjs` | 모델 프로필 해석 테이블 |
| `security.cjs` | 경로 탐색 방지, 프롬프트 인젝션 감지, 안전한 JSON 파싱, 셸 인수 검증 |
| `uat.cjs` | UAT 파일 파싱, 검증 부채 추적, audit-uat 지원 |
---
@@ -200,65 +293,81 @@ GSD는 사용자와 AI 코딩 에이전트(Claude Code, Gemini CLI, OpenCode, Ki
### 오케스트레이터 → 에이전트 패턴
```
Orchestrator (workflow .md)
오케스트레이터 (workflow .md)
│
├── Load context: gsd-tools.cjs init <workflow> <phase>
│ Returns JSON with: project info, config, state, phase details
├── 컨텍스트 로드: gsd-tools.cjs init <workflow> <phase>
│ 반환 JSON: 프로젝트 정보, 설정, 상태, 단계 상세
│
├── Resolve model: gsd-tools.cjs resolve-model <agent-name>
│ Returns: opus | sonnet | haiku | inherit
├── 모델 해결: gsd-tools.cjs resolve-model <agent-name>
│ 반환: opus | sonnet | haiku | inherit
│
├── Spawn Agent (Task/SubAgent call)
│ ├── Agent prompt (agents/*.md)
│ ├── Context payload (init JSON)
│ ├── Model assignment
│ └── Tool permissions
├── 에이전트 생성 (Task/SubAgent 호출)
│ ├── 에이전트 프롬프트 (agents/*.md)
│ ├── 컨텍스트 페이로드 (init JSON)
│ ├── 모델 할당
│ └── 도구 권한
│
├── Collect result
├── 결과 수집
│
└── Update state: gsd-tools.cjs state update/patch/advance-plan
└── 상태 업데이트: gsd-tools.cjs state update / state patch / state advance-plan
```
### 에이전트 생성 카테고리
### 주요 에이전트 생성 범주
21개 주요 에이전트의 개념적 생성 패턴 분류. 권위 있는 31개 에이전트 목록(10개 고급/전문화 에이전트 포함: `gsd-pattern-mapper`, `gsd-code-reviewer`, `gsd-code-fixer`, `gsd-ai-researcher`, `gsd-domain-researcher`, `gsd-eval-planner`, `gsd-eval-auditor`, `gsd-framework-selector`, `gsd-debug-session-manager`, `gsd-intel-updater`)은 [`docs/INVENTORY.md`](INVENTORY.md#agents-31-shipped)를 참조하라.
| 범주 | 에이전트 | 병렬성 |
| ---------------- | --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| **Researchers** | gsd-project-researcher, gsd-phase-researcher, gsd-ui-researcher, gsd-advisor-researcher | 4개 병렬 (stack, features, architecture, pitfalls); advisor는 discuss-phase 중 생성됨 |
| **Synthesizers** | gsd-research-synthesizer | 순차적 (리서처 완료 후) |
| **Planners** | gsd-planner, gsd-roadmapper | 순차적 |
| **Checkers** | gsd-plan-checker, gsd-integration-checker, gsd-ui-checker, gsd-nyquist-auditor | 순차적 (검증 루프, 최대 3회 반복) |
| **Executors** | gsd-executor | 웨이브 내 병렬, 웨이브 간 순차적 |
| **Verifiers** | gsd-verifier | 순차적 (모든 실행기 완료 후) |
| **Mappers** | gsd-codebase-mapper | 4개 병렬 (tech, arch, quality, concerns) |
| **Debuggers** | gsd-debugger | 순차적 (대화형) |
| **Auditors** | gsd-ui-auditor, gsd-security-auditor | 순차적 |
| **Doc Writers** | gsd-doc-writer, gsd-doc-verifier | 순차적 (writer 다음 verifier) |
| **Profilers** | gsd-user-profiler | 순차적 |
| **Analyzers** | gsd-assumptions-analyzer | 순차적 (discuss-phase 중) |
| 카테고리 | 에이전트 | 병렬성 |
|----------|--------|-------------|
| **Researchers** | gsd-project-researcher, gsd-phase-researcher, gsd-ui-researcher, gsd-advisor-researcher | 4개 병렬 (stack, features, architecture, pitfalls); advisor는 discuss-phase 중 생성됨 |
| **Synthesizers** | gsd-research-synthesizer | 순차적 (조사자 완료 후) |
| **Planners** | gsd-planner, gsd-roadmapper | 순차적 |
| **Checkers** | gsd-plan-checker, gsd-integration-checker, gsd-ui-checker, gsd-nyquist-auditor | 순차적 (검증 루프, 최대 3회 반복) |
| **Executors** | gsd-executor | 웨이브 내 병렬, 웨이브 간 순차적 |
| **Verifiers** | gsd-verifier | 순차적 (모든 executor 완료 후) |
| **Mappers** | gsd-codebase-mapper | 4개 병렬 (tech, arch, quality, concerns) |
| **Debuggers** | gsd-debugger | 순차적 (대화형) |
| **Auditors** | gsd-ui-auditor | 순차적 |
### 웨이브 실행 모델
`execute-phase` 중 계획은 의존성 웨이브로 그룹화됩니다.
`execute-phase` 중 계획은 의존성 웨이브로 그룹화된다:
```
Wave Analysis:
Plan 01 (no deps) ─┐
Plan 02 (no deps) ─┤── Wave 1 (parallel)
Plan 03 (depends: 01) ─┤── Wave 2 (waits for Wave 1)
Plan 04 (depends: 02) ─┘
Plan 05 (depends: 03,04) ── Wave 3 (waits for Wave 2)
웨이브 분석:
계획 01 (의존성 없음) ─┐
계획 02 (의존성 없음) ─┤── 웨이브 1 (병렬)
계획 03 (의존: 01) ─┤── 웨이브 2 (웨이브 1 대기)
계획 04 (의존: 02) ─┘
계획 05 (의존: 03,04) ── 웨이브 3 (웨이브 2 대기)
```
각 executor는 다음을 받습니다.
- 새로운 200K 컨텍스트 윈도우
각 실행기는 다음을 받는다:
- 신선한 200K 컨텍스트 윈도우 (또는 지원 모델에서 최대 1M)
- 실행할 특정 PLAN.md
- 프로젝트 컨텍스트 (PROJECT.md, STATE.md)
- 단계 컨텍스트 (CONTEXT.md, 사용 가능한 경우 RESEARCH.md)
- 단계 컨텍스트 (CONTEXT.md, 가용한 경우 RESEARCH.md)
### 적응형 컨텍스트 보강 (1M 모델)
컨텍스트 윈도우가 500K+ 토큰인 경우 (Opus 4.6, Sonnet 4.6 같은 1M 클래스 모델), 서브에이전트 프롬프트는 표준 200K 윈도우에 들어가지 않는 추가 컨텍스트로 자동 보강된다:
- **실행기 에이전트**는 이전 웨이브 SUMMARY.md 파일들과 단계 CONTEXT.md/RESEARCH.md를 받아 단계 내 교차 계획 인식 가능
- **검증기 에이전트**는 모든 PLAN.md, SUMMARY.md, CONTEXT.md 파일들과 REQUIREMENTS.md를 받아 이력 인식 검증 가능
오케스트레이터는 config에서 `context_window`를 읽고(`gsd-tools.cjs config-get context_window`) 값이 >= 500,000일 때 조건부로 더 풍부한 컨텍스트를 포함한다. 표준 200K 윈도우에서는 최대 컨텍스트 효율성을 위해 캐시 친화적 순서로 잘린 버전의 프롬프트를 사용한다.
#### 병렬 커밋 안전성
같은 웨이브 내에서 여러 executor가 실행될 때 충돌을 방지하는 두 가지 메커니즘이 있습니다.
같은 웨이브 내에서 여러 실행기가 실행될 때 두 가지 메커니즘이 충돌을 방지한다:
1. **`--no-verify` 커밋** — 병렬 에이전트는 사전 커밋 훅을 건너뜁니다 (빌드 잠금 경쟁을 유발할 수 있음, 예: Rust 프로젝트의 cargo lock 충돌). 오케스트레이터는 각 웨이브 완료 후 `git hook run pre-commit`을 한 번 실행합니다.
2. **STATE.md 파일 잠금** — 모든 `writeStateMd()` 호출은 lockfile 기반 상호 배제를 사용합니다 (`STATE.md.lock`, `O_EXCL` 원자적 생성). 이는 두 에이전트가 STATE.md를 읽고 서로 다른 필드를 수정하면 마지막 작성자가 다른 에이전트의 변경사항을 덮어쓰는 읽기-수정-쓰기 경쟁 조건을 방지합니다. 오래된 잠금 감지(10초 타임아웃)와 지터를 포함한 스핀 대기가 포함됩니다.
1. `--no-verify` 커밋 — 병렬 에이전트는 사전 커밋 훅을 건너뛴다 (빌드 잠금 경합을 유발할 수 있음, 예: Rust 프로젝트의 cargo lock 충돌). 오케스트레이터는 각 웨이브 완료 후 `git hook run pre-commit`을 한 번 실행한다.
2. **STATE.md 파일 잠금** — 모든 `writeStateMd()` 호출은 lockfile 기반 상호 배제를 사용한다(`STATE.md.lock`, `O_EXCL` 원자적 생성). 이는 두 에이전트가 STATE.md를 읽고 서로 다른 필드를 수정하면 마지막 작성자가 다른 에이전트의 변경 사항을 덮어쓰는 읽기-수정-쓰기 경합 조건을 방지한다. 오래된 잠금 감지(10초 타임아웃)와 지터를 포함한 스핀 대기가 포함된다.
---
@@ -267,73 +376,84 @@ Wave Analysis:
### 새 프로젝트 흐름
```
User input (idea description)
사용자 입력 (아이디어 설명)
│
▼
Questions (questioning.md philosophy)
질문 (questioning.md 철학)
│
▼
4x Project Researchers (parallel)
4x 프로젝트 리서처 (병렬)
├── Stack → STACK.md
├── Features → FEATURES.md
├── Architecture → ARCHITECTURE.md
└── Pitfalls → PITFALLS.md
│
▼
Research Synthesizer → SUMMARY.md
리서치 합성기 → SUMMARY.md
│
▼
Requirements extraction → REQUIREMENTS.md
요구 사항 추출 → REQUIREMENTS.md
│
▼
Roadmapper → ROADMAP.md
로드맵퍼 → ROADMAP.md
│
▼
User approval → STATE.md initialized
사용자 승인 → STATE.md 초기화
```
### 단계 실행 흐름
```
discuss-phase → CONTEXT.md (user preferences)
discuss-phase → CONTEXT.md (사용자 선호도)
│
▼
ui-phase → UI-SPEC.md (design contract, optional)
ui-phase → UI-SPEC.md (디자인 계약, 선택적)
│
▼
plan-phase
├── Phase Researcher → RESEARCH.md
├── Planner → PLAN.md files
└── Plan Checker → Verify loop (max 3x)
├── 리서치 게이트 (RESEARCH.md에 미해결 공개 질문이 있으면 차단)
├── 단계 리서처 → RESEARCH.md
│ └── 패키지 적법성 게이트: 모든 패키지에 slopcheck; [SLOP] 제거,
│ [SUS]/[ASSUMED] 플래그; 감사 테이블을 RESEARCH.md에 작성
├── 플래너 (도달 가능성 검사 포함) → PLAN.md 파일
│ └── [ASSUMED]/[SUS] 설치 전에 checkpoint:human-verify 삽입;
│ 설치 포함 계획에 T-{phase}-SC STRIDE 행 추가
├── 계획 검사기 → 검증 루프 (최대 3회)
├── 요구 사항 커버리지 게이트 (REQ-ID → 계획)
└── 결정 커버리지 게이트 (CONTEXT.md `<decisions>` → 계획, 차단 — #2492)
│
▼
execute-phase
├── Wave analysis (dependency grouping)
├── Executor per plan → code + atomic commits
├── SUMMARY.md per plan
└── Verifier → VERIFICATION.md
state planned-phase → STATE.md (계획됨/실행 준비)
│
▼
verify-work → UAT.md (user acceptance testing)
execute-phase (컨텍스트 축소: 잘린 프롬프트, 캐시 친화적 순서)
├── 웨이브 분석 (의존성 그룹화)
├── 계획당 실행기 → 코드 + 원자적 커밋
├── 계획당 SUMMARY.md
└── 검증기 → VERIFICATION.md
└── 결정 커버리지 게이트 (CONTEXT.md 결정 → 출시된 결과물, 비차단 — #2492)
│
▼
ui-review → UI-REVIEW.md (visual audit, optional)
verify-work → UAT.md (사용자 수락 테스트)
│
▼
ui-review → UI-REVIEW.md (시각적 감사, 선택적)
```
### 컨텍스트 전파
각 워크플로우 단계는 이후 단계에 공급되는 아티팩트를 생성합니다.
각 워크플로우 단계는 이후 단계에 공급되는 결과물을 생성한다:
```
PROJECT.md ────────────────────────────────────────────► All agents
REQUIREMENTS.md ───────────────────────────────────────► Planner, Verifier, Auditor
ROADMAP.md ────────────────────────────────────────────► Orchestrators
STATE.md ──────────────────────────────────────────────► All agents (decisions, blockers)
CONTEXT.md (per phase) ────────────────────────────────► Researcher, Planner, Executor
RESEARCH.md (per phase) ───────────────────────────────► Planner, Plan Checker
PLAN.md (per plan) ────────────────────────────────────► Executor, Plan Checker
SUMMARY.md (per plan) ─────────────────────────────────► Verifier, State tracking
UI-SPEC.md (per phase) ────────────────────────────────► Executor, UI Auditor
PROJECT.md ────────────────────────────────────────────► 모든 에이전트
REQUIREMENTS.md ───────────────────────────────────────► 플래너, 검증기, 감사기
ROADMAP.md ────────────────────────────────────────────► 오케스트레이터
STATE.md ──────────────────────────────────────────────► 모든 에이전트 (결정, 차단)
CONTEXT.md (단계별) ────────────────────────────────────► 리서처, 플래너, 실행기
RESEARCH.md (단계별) ───────────────────────────────────► 플래너, 계획 검사기
PLAN.md (계획별) ────────────────────────────────────────► 실행기, 계획 검사기
SUMMARY.md (계획별) ─────────────────────────────────────► 검증기, 상태 추적
UI-SPEC.md (단계별) ────────────────────────────────────► 실행기, UI 감사기
```
---
@@ -344,29 +464,37 @@ UI-SPEC.md (per phase) ───────────────────
```
~/.claude/ # Claude Code (전역 설치)
├── commands/gsd/*.md # 37개 슬래시 명령어
├── skills/gsd-*/SKILL.md # 전역 스킬 (권위 있는 목록: docs/INVENTORY.md)
├── commands/gsd/*.md # 로컬 Claude 설치는 전역 스킬 대신 슬래시 명령어 사용
├── get-shit-done/
│ ├── bin/gsd-tools.cjs # CLI 유틸리티
│ ├── bin/lib/*.cjs # 15개 도메인 모듈
│ ├── workflows/*.md # 42개 워크플로우 정의
│ ├── references/*.md # 13개 공유 참조 문서
│ └── templates/ # 계획 아티팩트 템플릿
├── agents/*.md # 15개 에이전트 정의
├── hooks/
│ ├── gsd-statusline.js # 상태표시줄 훅
│ ├── gsd-context-monitor.js # 컨텍스트 경고 훅
│ └── gsd-check-update.js # 업데이트 확인 훅
│ ├── bin/lib/*.cjs # 도메인 모듈 (권위 있는 목록: docs/INVENTORY.md)
│ ├── workflows/*.md # 워크플로우 정의 (권위 있는 목록: docs/INVENTORY.md)
│ ├── references/*.md # 공유 레퍼런스 문서 (권위 있는 목록: docs/INVENTORY.md)
│ └── templates/ # 계획 결과물 템플릿
├── agents/*.md # 에이전트 정의 (권위 있는 목록: docs/INVENTORY.md)
├── hooks/*.js # Node.js 훅 (statusline, guards, monitors, update check)
├── hooks/*.sh # 쉘 훅 (session state, commit validation, phase boundary)
├── settings.json # 훅 등록
└── VERSION # 설치된 버전 번호
```
다른 런타임의 동등한 경로입니다.
- **OpenCode:** `~/.config/opencode/` 또는 `~/.opencode/`
- **Kilo:** `~/.config/kilo/` 또는 `~/.kilo/`
- **Gemini CLI:** `~/.gemini/`
- **Codex:** `~/.codex/` (명령어 대신 skills 사용)
- **Copilot:** `~/.github/`
- **Antigravity:** `~/.gemini/antigravity/` (전역) 또는 `./.agent/` (로컬)
다른 런타임의 동등한 경로:
- **OpenCode:** `~/.config/opencode/` 전역 또는 `./.opencode/` 로컬
- **Kilo:** `~/.config/kilo/` 전역 또는 `./.kilo/` 로컬
- **Gemini CLI:** `~/.gemini/` 전역 또는 `./.gemini/` 로컬
- **Codex:** `~/.codex/` 전역 또는 `./.codex/` 로컬
- **Copilot:** `~/.copilot/` 전역 또는 `./.github/` 로컬
- **Antigravity:** 자동 감지된 전역 루트 (`~/.gemini/antigravity/`, `~/.gemini/antigravity-ide/`, 또는 `~/.gemini/antigravity-cli/`) 또는 `./.agent/` 로컬
- **Cursor:** `~/.cursor/` 전역 또는 `./.cursor/` 로컬
- **Windsurf:** `~/.codeium/windsurf/` 전역 또는 `./.windsurf/` 로컬
- **Augment Code:** `~/.augment/` 전역 또는 `./.augment/` 로컬
- **Trae:** `~/.trae/` 전역 또는 `./.trae/` 로컬
- **Qwen Code:** `~/.qwen/` 전역 또는 `./.qwen/` 로컬
- **Hermes Agent:** `~/.hermes/` 전역 또는 `./.hermes/` 로컬
- **CodeBuddy:** `~/.codebuddy/` 전역 또는 `./.codebuddy/` 로컬
- **Cline:** `~/.cline/` 전역 또는 프로젝트 루트 `.clinerules` 로컬
### 프로젝트 파일 (`.planning/`)
@@ -378,15 +506,15 @@ UI-SPEC.md (per phase) ───────────────────
├── STATE.md # 살아있는 메모리: 위치, 결정, 차단, 메트릭
├── config.json # 워크플로우 설정
├── MILESTONES.md # 완료된 마일스톤 보관
├── research/ # /gsd-new-project의 도메인 조사
├── research/ # /gsd-new-project의 도메인 리서치
│ ├── SUMMARY.md
│ ├── STACK.md
│ ├── FEATURES.md
│ ├── ARCHITECTURE.md
│ └── PITFALLS.md
├── codebase/ # 브라운필드 매핑 (/gsd-map-codebase에서)
│ ├── STACK.md
│ ├── ARCHITECTURE.md
│ ├── STACK.md # YAML 전문에 `last_mapped_commit` 포함
│ ├── ARCHITECTURE.md # 실행 후 드리프트 게이트를 위한 (#2003)
│ ├── CONVENTIONS.md
│ ├── CONCERNS.md
│ ├── STRUCTURE.md
@@ -395,14 +523,14 @@ UI-SPEC.md (per phase) ───────────────────
├── phases/
│ └── XX-phase-name/
│ ├── XX-CONTEXT.md # 사용자 선호도 (discuss-phase에서)
│ ├── XX-RESEARCH.md # 생태계 조사 (plan-phase에서)
│ ├── XX-RESEARCH.md # 생태계 리서치 (plan-phase에서)
│ ├── XX-YY-PLAN.md # 실행 계획
│ ├── XX-YY-SUMMARY.md # 실행 결과
│ ├── XX-VERIFICATION.md # 실행 후 검증
│ ├── XX-VALIDATION.md # Nyquist 테스트 커버리지 매핑
│ ├── XX-UI-SPEC.md # UI 디자인 계약서 (ui-phase에서)
│ ├── XX-UI-SPEC.md # UI 디자인 계약 (ui-phase에서)
│ ├── XX-UI-REVIEW.md # 시각적 감사 점수 (ui-review에서)
│ └── XX-UAT.md # 사용자 수용 테스트 결과
│ └── XX-UAT.md # 사용자 수락 테스트 결과
├── quick/ # 빠른 작업 추적
│ └── YYMMDD-xxx-slug/
│ ├── PLAN.md
@@ -420,34 +548,60 @@ UI-SPEC.md (per phase) ───────────────────
└── continue-here.md # 컨텍스트 핸드오프 (pause-work에서)
```
### 실행 후 코드베이스 드리프트 게이트 (#2003)
`/gsd-execute-phase` 마지막 웨이브 커밋 후, 워크플로우는 비차단 `codebase_drift_gate` 단계를 실행한다(`schema_drift_gate`와 `verify_phase_goal` 사이). `last_mapped_commit..HEAD` diff를 `.planning/codebase/STRUCTURE.md`와 비교하고 네 종류의 구조적 요소를 집계한다:
1. 매핑된 경로 외부의 새 디렉터리
2. `(packages|apps)/<name>/src/index.*`의 새 배럴 내보내기
3. 새 마이그레이션 파일
4. `routes/` 또는 `api/` 하위의 새 라우트 모듈
집계가 `workflow.drift_threshold`(기본값 3)를 충족하면, 게이트는 제안된 `/gsd-map-codebase --paths …` 명령어와 함께 **경고**하거나(기본값), `gsd-codebase-mapper`를 영향받은 경로로 범위 지정하여 생성함으로써 **자동 재매핑**한다(`workflow.drift_action = auto-remap`). 감지 또는 재매핑의 오류는 로그되고 단계는 계속된다 — 드리프트 감지는 검증을 실패시킬 수 없다.
`last_mapped_commit`는 각 `.planning/codebase/*.md` 파일 상단의 YAML 전문에 있다; `bin/lib/drift.cjs`는 `readMappedCommit`와 `writeMappedCommit` 왕복 헬퍼를 제공한다.
---
## 인스톨러 아키텍처
인스톨러(`bin/install.js`, ~3,000줄)는 다음을 처리합니다.
인스톨러(`bin/install.js`, ~10,700줄)는 다음을 처리한다:
1. **런타임 감지** — 대화형 프롬프트 또는 CLI 플래그 (`--claude`, `--opencode`, `--gemini`, `--kilo`, `--codex`, `--copilot`, `--antigravity`, `--all`)
1. **런타임 감지** — 대화형 프롬프트 또는 CLI 플래그 (`--claude`, `--opencode`, `--gemini`, `--kilo`, `--codex`, `--copilot`, `--antigravity`, `--cursor`, `--windsurf`, `--augment`, `--trae`, `--qwen`, `--hermes`, `--codebuddy`, `--cline`, `--all`)
2. **위치 선택** — 전역(`--global`) 또는 로컬(`--local`)
3. **파일 배포** — commands, workflows, references, templates, agents, hooks 복사
4. **런타임 적응** — 런타임별 파일 내용 변환.
- Claude Code: 그대로 사용
- OpenCode: 명령어/에이전트를 OpenCode 호환 플랫 명령어 + 서브에이전트 형식으로 변환
- Kilo: Kilo 설정 경로로 OpenCode 변환 파이프라인을 재사용
- Codex: commands에서 TOML config + skills 생성
- Copilot: 도구 이름 매핑 (Read→read, Bash→execute 등)
- Gemini: 훅 이벤트 이름 조정 (`PostToolUse` 대신 `AfterTool`)
- Antigravity: Google 모델 등가물을 사용한 skills-first 방식
3. **파일 배포** — commands, skills, workflows, references, templates, agents, hooks 복사
4. **런타임 적응** — 런타임별 파일 내용 변환:
- Claude Code: 그대로 사용
- OpenCode: 명령어/에이전트를 OpenCode 호환 플랫 명령어 + 서브에이전트 형식으로 변환
- Kilo: Kilo 설정 경로로 OpenCode 변환 파이프라인 재사용
- Codex: commands에서 TOML config + skills 생성
- Copilot: 도구 이름 매핑 (Read→read, Bash→execute 등)
- Gemini: 훅 이벤트 이름 조정 (`PostToolUse` 대신 `AfterTool`)
- Antigravity: Google 모델 등가물을 사용한 skills-first
- Cursor: Cursor 규칙 참조를 사용한 skills-first
- Windsurf: Windsurf 규칙 참조를 사용한 skills-first
- Trae: `settings.json` 또는 훅 통합 없이 `~/.trae` / `./.trae`에 skills-first 설치
- Qwen Code: Qwen 브랜드 경로 및 프롬프트 재작성을 사용한 skills-first
- Hermes Agent: `skills/gsd/` 하의 범주 기반 스킬
- CodeBuddy: CodeBuddy 경로 및 프롬프트 재작성을 사용한 skills-first
- Cline: 규칙 기반 통합을 위한 `.clinerules` 작성
- Augment Code: 전체 스킬 변환 및 설정 관리를 사용한 skills-first
5. **경로 정규화** — `~/.claude/` 경로를 런타임별 경로로 교체
6. **설정 통합** — 런타임의 `settings.json`에 훅 등록
7. **패치 백업** — v1.17부터 로컬 수정 파일을 `gsd-local-patches/`에 백업하여 `/gsd-update --reapply`에 사용
8. **매니페스트 추적** — 깔끔한 제거를 위해 `gsd-file-manifest.json` 작성
9. **제거 모드** — `--uninstall`로 모든 GSD 파일, 훅, 설정 제거
설치 시 파일 이동, 오래된 결과물 정리, 설정 재작성, 사용자 데이터 보존은 인스톨러 마이그레이션 모듈이 관리한다. [인스톨러 마이그레이션](../installer-migrations.md)과 [ADR 0008](../adr/0008-installer-migration-module.md)을 참조하라.
마이그레이션 모듈은 레거시 설치에 대한 게이트된 최초 기준선 스캔도 소유하며, 이후 마이그레이션이 무언가를 제거하거나 재작성하기 전에 알려진 런타임 설치 표면을 분류한다.
계획 드리프트 가드(`plan_review.source_grounding`) — 실행 전에 생성된 계획에서 심볼 참조를 라이브 소스에 대해 검증하는 — 는 [ADR 22](../adr/22-plan-drift-guard.md)에 명시되어 있다.
### 플랫폼 처리
- **Windows:** 자식 프로세스에 `windowsHide` 적용, 보호 디렉터리의 EPERM/EACCES 방지, 경로 구분자 정규화
- **WSL:** WSL에서 실행 중인 Windows Node.js를 감지하고 경로 불일치에 대해 경고
- **Docker/CI:** 커스텀 config 디렉터리 위치를 위한 `CLAUDE_CONFIG_DIR` 환경 변수 지원
- **Windows:** 자식 프로세스에 `windowsHide`, 보호 디렉터리에 EPERM/EACCES 방지, 경로 구분자 정규화
- **WSL:** WSL에서 실행 중인 Windows Node.js 감지 및 경로 불일치 경고
- **Docker/CI:** 커스텀 설정 디렉터리 위치를 위한 `CLAUDE_CONFIG_DIR` 환경 변수 지원
---
@@ -456,75 +610,138 @@ UI-SPEC.md (per phase) ───────────────────
### 아키텍처
```
Runtime Engine (Claude Code / Gemini CLI)
런타임 엔진 (Claude Code / Gemini CLI)
│
├── statusLine event ──► gsd-statusline.js
│ Reads: stdin (session JSON)
│ Writes: stdout (formatted status), /tmp/claude-ctx-{session}.json (bridge)
├── statusLine 이벤트 ──► gsd-statusline.js
│ 읽기: stdin (세션 JSON)
│ 쓰기: stdout (형식화된 상태), /tmp/claude-ctx-{session}.json (브리지)
│
├── PostToolUse/AfterTool event ──► gsd-context-monitor.js
│ Reads: stdin (tool event JSON), /tmp/claude-ctx-{session}.json (bridge)
│ Writes: stdout (hookSpecificOutput with additionalContext warning)
├── PostToolUse/AfterTool 이벤트 ──► gsd-context-monitor.js
│ 읽기: stdin (도구 이벤트 JSON), /tmp/claude-ctx-{session}.json (브리지)
│ 쓰기: stdout (additionalContext 경고가 있는 hookSpecificOutput)
│
└── SessionStart event ──► gsd-check-update.js
Reads: VERSION file
Writes: ~/.claude/cache/gsd-update-check.json (spawns background process)
└── SessionStart 이벤트 ──► gsd-check-update.js
읽기: VERSION 파일
쓰기: ~/.claude/cache/gsd-update-check.json (백그라운드 프로세스 생성)
```
### 컨텍스트 모니터 임계값
| 잔여 컨텍스트 | 수준 | 에이전트 동작 |
|-------------------|-------|----------------|
| > 35% | 정상 | 경고 주입 없음 |
| ≤ 35% | WARNING | "복잡한 새 작업 시작을 피하세요" |
| ≤ 25% | CRITICAL | "컨텍스트가 거의 소진됨, 사용자에게 알리세요" |
디바운스: 반복 경고 사이에 5회 도구 사용. 심각도 에스컬레이션(WARNING→CRITICAL)은 디바운스를 우회합니다.
| 잔여 컨텍스트 | 수준 | 에이전트 동작 |
| ----------------- | -------- | --------------------------------------- |
| > 35% | 정상 | 경고 주입 없음 |
| ≤ 35% | WARNING | "복잡한 새 작업 시작 금지" |
| ≤ 25% | CRITICAL | "컨텍스트 거의 소진됨, 사용자에게 알릴 것" |
디바운스: 반복 경고 사이에 5번의 도구 사용. 심각도 에스컬레이션(WARNING→CRITICAL)은 디바운스를 우회한다.
### 안전 속성
- 모든 훅은 try/catch로 감싸여 있으며 오류 시 자동 종료합니다
- 모든 훅은 try/catch로 감싸이며 오류 시 자동 종료한다
- stdin 타임아웃 가드(3초)로 파이프 문제 시 중단 방지
- 오래된 메트릭(60초 이상)은 무시됩니다
- 누락된 브리지 파일은 정상적으로 처리됩니다 (서브에이전트, 새 세션)
- 컨텍스트 모니터는 권고용입니다 — 사용자 선호도를 재정의하는 명령을 내리지 않습니다
- 오래된 메트릭(60초 이상)은 무시된다
- 누락된 브리지 파일은 정상적으로 처리된다 (서브에이전트, 새 세션)
- 컨텍스트 모니터는 자문적이다 — 사용자 선호도를 재정의하는 명령적 명령을 내리지 않는다
### 패키지 적법성 게이트 (v1.42.1)
리서처 → 플래너 → 실행기 파이프라인은 슬롭스쿼팅(악의적인 설치 후 스크립트와 함께 선점 등록된 AI 환각 패키지 이름)에 대한 공급망 게이트를 포함한다.
**위협 모델:** GSD는 "리서처가 패키지를 명명"에서 "실행기가 `npm install`을 실행"까지의 전체 경로를 자동화한다. `npm view`를 통과하는 환각된 이름(등록만 증명, 적법성은 아님)은 이전에는 감지되지 않고 흘러갔을 것이다. AI가 생성한 패키지 참조의 ~20%가 환각되며; 그 이름의 ~43%가 프롬프트 전반에 걸쳐 일관되게 반복되어 선점 등록이 공격자에게 경제적으로 실현 가능하다.
**게이트 계층:**
| 계층 | 컴포넌트 | 동작 |
|-------|-----------|--------|
| 리서치 | `gsd-phase-researcher` | `slopcheck install <pkgs> --json` 실행; `## Package Legitimacy Audit` 테이블을 RESEARCH.md에 작성; RESEARCH.md가 작성되기 전에 `[SLOP]` 패키지 제거 |
| 계획 | `gsd-planner` | 감사 테이블 읽기; `[ASSUMED]` 또는 `[SUS]` 설치 작업 전에 `checkpoint:human-verify` 삽입; `<threat_model>`에 `T-{phase}-SC` STRIDE 공급망 행 추가 |
| 실행 | `gsd-executor` | RULE 3은 패키지 설치를 자동 수정 범위에서 제외; 실패한 설치는 체크포인트로 표시되며 절대 자동 대체하지 않음 |
**클레임 출처 통합:** WebSearch를 통해 발견된 패키지 이름은 `npm view` 결과와 관계없이 `[ASSUMED]`(not `[VERIFIED]`)로 태그된다. 이는 설치 경계에서 출처 태그를 하드 게이트로 시행하여 기존 `[ASSUMED]` / `[VERIFIED]` / `[CITED]` 출처 시스템을 확장한다 — `[ASSUMED]`는 항상 PLAN.md에 `checkpoint:human-verify`를 생성한다.
**생태계 커버리지:** 리서처는 단일 일반 검사 대신 레지스트리별 검증 명령을 사용한다 — `npm view` (Node), `pip index versions` (Python), `cargo search` (Rust). 이는 2025년 USENIX 연구에 문서화된 ~9% 비율의 교차 생태계 환각을 잡는다.
**정상적인 성능 저하:** `slopcheck`를 사용할 수 없으면 모든 추천 패키지가 `[ASSUMED]`로 태그되고 체크포인트로 게이트가 걸린다. 리서치와 계획은 진행된다; 시스템은 누락된 도구 의존성으로 인해 절대 하드 실패하지 않는다.
**외부 의존성:** `slopcheck` (MIT, pip 설치 가능). 유지 관리가 중단되면 `[ASSUMED]`-게이트 폴백이 사람 체크포인트 커버리지를 유지한다.
---
### 보안 훅 (v1.27)
**Prompt Guard** (`gsd-prompt-guard.js`).
- `.planning/` 파일에 Write/Edit 시 트리거됩니다
- 프롬프트 인젝션 패턴을 콘텐츠에서 스캔합니다 (역할 재정의, 지시 우회, system 태그 인젝션)
- 권고용 — 감지를 기록하며 차단하지 않습니다
- 패턴은 훅 독립성을 위해 인라인으로 포함됩니다 (`security.cjs`의 일부)
훅과 가드 계층이 더 광범위한 보안 접근 방식에 어떻게 맞는지에 대한 개념적 개요는 [보안 모델](explanation/security-model.md)을 참조하라.
**Workflow Guard** (`gsd-workflow-guard.js`).
- `.planning/` 외부 파일에 Write/Edit 시 트리거됩니다
- GSD 워크플로우 컨텍스트 외부의 편집을 감지합니다 (활성 `/gsd-` 명령어 또는 Task 서브에이전트 없음)
- 상태 추적 변경을 위해 `/gsd-quick` 또는 `/gsd-fast` 사용을 권고합니다
- `hooks.workflow_guard: true`로 활성화 (기본값: false)
**Prompt Guard** (`gsd-prompt-guard.js`):
- `.planning/` 파일에 Write/Edit 시 트리거
- 프롬프트 인젝션 패턴 스캔 (역할 재정의, 지시 우회, system 태그 인젝션)
- 자문적 전용 — 탐지를 로그하며 차단하지 않음
- 패턴은 훅 독립성을 위해 인라인으로 포함됨 (`security.cjs`의 하위 집합)
**Workflow Guard** (`gsd-workflow-guard.js`):
- `.planning/` 외부 파일에 Write/Edit 시 트리거
- GSD 워크플로우 컨텍스트 외부의 편집 감지 (활성 `/gsd-` 명령어 또는 Task 서브에이전트 없음)
- 상태 추적 변경을 위해 `/gsd-quick` 또는 `/gsd-fast` 사용 권고
- `hooks.workflow_guard: true`를 통한 옵트인 (기본값: false)
---
## 런타임 추상화
GSD는 통합된 명령어/워크플로우 아키텍처를 통해 여러 AI 코딩 런타임을 지원합니다.
GSD는 통합된 명령어/워크플로우 아키텍처를 통해 여러 AI 코딩 런타임을 지원한다.
| 런타임 | 명령어 형식 | 에이전트 시스템 | 설정 위치 |
|---------|---------------|--------------|-----------------|
| Claude Code | `/gsd-command` | Task 생성 | `~/.claude/` |
| OpenCode | `/gsd-command` | Subagent 모드 | `~/.config/opencode/` |
| Kilo | `/gsd-command` | Subagent 모드 | `~/.config/kilo/` |
| Gemini CLI | `/gsd-command` | Task 생성 | `~/.gemini/` |
| Codex | `$gsd-command` | Skills | `~/.codex/` |
| Copilot | `/gsd-command` | 에이전트 위임 | `~/.github/` |
| Antigravity | Skills | Skills | `~/.gemini/antigravity/` |
### 런타임 설치 계약 매트릭스
이 매트릭스는 인스톨러가 오늘 구체화하는 런타임 표면을 설명한다.
마이그레이션별 소유권과 소스 스냅샷은 [인스톨러 마이그레이션](../installer-migrations.md#runtime-configuration-contract-registry)에 있다.
| 런타임 | 전역 루트 | 로컬 루트 | 호출 표면 | 에이전트 표면 | 설정 및 훅 |
| --- | --- | --- | --- | --- | --- |
| Claude Code | `~/.claude` | `./.claude` | 전역 `skills/gsd-*/SKILL.md`; 로컬 `commands/gsd/*.md` | `agents/gsd-*.md` | `settings.json` 훅 및 statusLine 항목 |
| OpenCode | `~/.config/opencode` | `./.opencode` | `command/gsd-*.md` | `agents/gsd-*.md` | `opencode.json` 또는 `opencode.jsonc`; GSD 훅 없음 |
| Kilo | `~/.config/kilo` | `./.kilo` | `command/gsd-*.md` | `agents/gsd-*.md` | `kilo.json` 또는 `kilo.jsonc`; GSD 훅 없음 |
| Gemini CLI | `~/.gemini` | `./.gemini` | `commands/gsd/*.toml` | `agents/gsd-*.md` | `settings.json` 기능 플래그, 훅, statusline |
| Codex | `~/.codex` | `./.codex` | `skills/gsd-*/SKILL.md` | `agents/` 소스 마크다운 + 에이전트별 TOML | `config.toml` `[agents.gsd-*]`, `[features].hooks` (정규; 레거시 별칭 `codex_hooks`는 인식되며 재설치 시 마이그레이션됨, #3566), 훅 테이블 |
| GitHub Copilot | `~/.copilot` | `./.github` | `skills/gsd-*/SKILL.md` 및 `copilot-instructions.md` | `.agent.md` 파일 | GSD 훅 또는 statusline 없음 |
| Antigravity | 자동 감지: `~/.gemini/antigravity`, `~/.gemini/antigravity-ide`, 또는 `~/.gemini/antigravity-cli` | `./.agent` | `skills/gsd-*/SKILL.md` | `agents/gsd-*.md` | GSD가 설치 시 Gemini 스타일 `settings.json` 훅 항목 |
| Cursor | `~/.cursor` | `./.cursor` | `skills/gsd-*/SKILL.md` | `agents/gsd-*.md` | `rules/` 하의 규칙 참조; GSD 훅 없음 |
| Windsurf | `~/.codeium/windsurf` | `./.windsurf` | `skills/gsd-*/SKILL.md` | `agents/gsd-*.md` | `rules/` 하의 규칙 참조; GSD 훅 없음 |
| Augment Code | `~/.augment` | `./.augment` | `skills/gsd-*/SKILL.md` | `agents/gsd-*.md` | GSD 훅 또는 statusline 없음 |
| Trae | `~/.trae` | `./.trae` | `skills/gsd-*/SKILL.md` | `agents/gsd-*.md` | `rules/` 하의 규칙 참조; GSD 훅 없음 |
| Qwen Code | `~/.qwen` | `./.qwen` | `skills/gsd-*/SKILL.md` | `agents/gsd-*.md` | 지원되는 경우 공통 GSD 설정 및 훅 항목 |
| Hermes Agent | `~/.hermes` | `./.hermes` | `skills/gsd/DESCRIPTION.md` 및 `skills/gsd/gsd-*/SKILL.md` | `agents/gsd-*.md` | 지원되는 경우 공통 GSD 설정 및 훅 항목 |
| CodeBuddy | `~/.codebuddy` | `./.codebuddy` | `skills/gsd-*/SKILL.md` | `agents/gsd-*.md` | 지원되는 경우 공통 GSD 설정 및 훅 항목 |
| Cline | `~/.cline` | 프로젝트 루트 | `.clinerules` | 규칙만 | GSD 훅 또는 statusline 없음 |
### 업스트림 계약 소스
런타임 설치 기대는 가용한 경우 기본 문서에 대해 확인된다. 현재 소스 스냅샷은 2026-05-11:
- Claude Code: Anthropic 슬래시 명령어, 설정, 훅, 서브에이전트 문서.
- OpenCode 및 Kilo: OpenCode 설정 문서 및 Kilo 커스텀 서브에이전트 문서.
- Gemini CLI 및 Qwen Code: 명령어/설정 문서; Qwen 명령어 문서는 2026-05-06에 마지막으로 업데이트됨.
- Codex: OpenAI Codex 문서 및 `config-schema.json`; 인스톨러는 에이전트 테이블 형태를 위한 Codex 0.124.0 호환성도 포함.
- Copilot, Cursor, Cline, Augment, Hermes, CodeBuddy: 커스텀 지시, 규칙, 스킬, 설정을 위한 벤더 문서.
- Antigravity, Windsurf, Trae: 소스가 제한된 행. 인스톨러는 현재 호환성 심을 문서화하며, 마이그레이션은 설정을 재작성하기 전에 해당 소스를 새로 고쳐야 한다.
### 추상화 포인트
1. **도구 이름 매핑** — 각 런타임은 고유한 도구 이름을 가집니다 (예: Claude의 `Bash` → Copilot의 `execute`)
2. **훅 이벤트 이름** — Claude는 `PostToolUse`를 사용하고 Gemini는 `AfterTool`을 사용합니다
3. **에이전트 전문** — 각 런타임은 고유한 에이전트 정의 형식을 가집니다
4. **경로 규칙** — 각 런타임은 서로 다른 디렉터리에 설정을 저장합니다
5. **모델 참조** — `inherit` 프로필을 통해 GSD가 런타임의 모델 선택에 위임합니다
1. **도구 이름 매핑** — 각 런타임은 고유한 도구 이름을 가진다 (예: Claude의 `Bash` → Copilot의 `execute`)
2. **훅 이벤트 이름** — Claude는 `PostToolUse`를 사용하고 Gemini는 `AfterTool`을 사용한다
3. **에이전트 전문** — 각 런타임은 고유한 에이전트 정의 형식을 가진다
4. **경로 컨벤션** — 각 런타임은 서로 다른 디렉터리에 설정을 저장한다
5. **모델 참조** — `inherit` 프로필은 GSD가 런타임의 모델 선택에 위임하도록 한다
인스톨러는 설치 시 모든 변환을 처리합니다. 워크플로우와 에이전트는 Claude Code의 네이티브 형식으로 작성되어 배포 중에 변환됩니다.
인스톨러는 설치 시 모든 번역을 처리한다. 워크플로우와 에이전트는 Claude Code의 네이티브 형식으로 작성되어 배포 중에 변환된다.
---
## Related
- [다중 에이전트 오케스트레이션](explanation/multi-agent-orchestration.md)
- [보안 모델](explanation/security-model.md)
- [CLI 도구](CLI-TOOLS.md)
- [문서 인덱스](README.md)

304
docs/ko-KR/CLI-TOOLS.md
View File

@@ -1,38 +1,48 @@
# GSD CLI 도구 레퍼런스
# GSD CLI 도구 참조
> `gsd-tools.cjs`에 대한 프로그래밍 방식 API 레퍼런스입니다. 워크플로우와 에이전트가 내부적으로 사용합니다. 사용자 대면 명령어는 [Command Reference](COMMANDS.md)를 참조하세요.
> `gsd-tools` CLI(`get-shit-done/bin/gsd-tools.cjs`)에 대한 참조입니다. 슬래시 명령 및 사용자 흐름은 [명령 참조](COMMANDS.md)를 확인하세요. [문서 인덱스](README.md)로 돌아가기.
---
## 개요
`gsd-tools.cjs`는 GSD의 약 50개 명령어, 워크플로우, 에이전트 파일에서 반복되는 인라인 bash 패턴을 대체하는 Node.js CLI 유틸리티입니다. config 파싱, 모델 해석, 단계 조회, git 커밋, 요약 검증, 상태 관리, 템플릿 작업을 중앙화합니다.
`gsd-tools.cjs`는 GSD 명령, 워크플로우, 에이전트 전반에 걸쳐 설정 파싱, 모델 해석, 단계 조회, git 커밋, 요약 검증, 상태 관리, 템플릿 작업을 중앙에서 처리합니다.
**위치:** `get-shit-done/bin/gsd-tools.cjs`
**모듈:** `get-shit-done/bin/lib/`의 15개 도메인 모듈
**사용법:**
| | |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **배포 경로** | `get-shit-done/bin/gsd-tools.cjs` |
| **구현** | `get-shit-done/bin/lib/` 아래 20개의 도메인 모듈 (해당 디렉토리가 기준) |
| **상태** | 오케스트레이션, 워크플로우, 자동화를 위한 주요 런타임 명령 인터페이스. |
**사용법 (CJS):**
```bash
node gsd-tools.cjs <command> [args] [--raw] [--cwd <path>]
```
**전역 플래그.**
| 플래그 | 설명 |
|------|-------------|
| `--raw` | 기계 가독형 출력 (JSON 또는 일반 텍스트, 포매팅 없음) |
| `--cwd <path>` | 작업 디렉터리 재정의 (샌드박스 서브에이전트용) |
**전역 플래그 (CJS):**
| 플래그 | 설명 |
| -------------- | ---------------------------------------------------------------------------- |
| `--raw` | 기계 판독 가능한 출력 (JSON 또는 일반 텍스트, 서식 없음) |
| `--cwd <path>` | 작업 디렉토리 재정의 (샌드박스된 서브에이전트용) |
| `--ws <name>` | `.planning/workstreams/<name>` 경로에 대한 워크스트림 컨텍스트 |
---
## State 명령어
## 상태 명령
`.planning/STATE.md`를 관리합니다 — 프로젝트의 살아있는 메모리입니다.
`.planning/STATE.md` — 프로젝트의 살아있는 메모리를 관리합니다.
```bash
# 전체 프로젝트 config + state를 JSON으로 로드
# 전체 프로젝트 설정 + 상태를 JSON으로 불러오기
node gsd-tools.cjs state load
# STATE.md 전문을 JSON으로 출력
# STATE.md 프론트매터를 JSON으로 출력
node gsd-tools.cjs state json
# 단일 필드 업데이트
@@ -41,7 +51,7 @@ node gsd-tools.cjs state update <field> <value>
# STATE.md 내용 또는 특정 섹션 가져오기
node gsd-tools.cjs state get [section]
# 여러 필드를 일괄 업데이트
# 여러 필드 일괄 업데이트
node gsd-tools.cjs state patch --field1 val1 --field2 val2
# 계획 카운터 증가
@@ -53,66 +63,73 @@ node gsd-tools.cjs state record-metric --phase N --plan M --duration Xmin [--tas
# 진행률 바 재계산
node gsd-tools.cjs state update-progress
# 결정 추가
# 결정 사항 추가
node gsd-tools.cjs state add-decision --summary "..." [--phase N] [--rationale "..."]
# 또는 파일에서:
node gsd-tools.cjs state add-decision --summary-file path [--rationale-file path]
# 차단 항목 추가/해결
# 차단 항목 추가/해제
node gsd-tools.cjs state add-blocker --text "..."
node gsd-tools.cjs state resolve-blocker --text "..."
# 세션 연속성 기록
node gsd-tools.cjs state record-session --stopped-at "..." [--resume-file path]
# 단계 시작 — 새로운 단계의 STATE.md 상태/최근 활동 업데이트
node gsd-tools.cjs state begin-phase --phase N --name SLUG --plans COUNT
# 에이전트 발견 가능한 차단 신호 (discuss-phase / UI 흐름에서 사용)
node gsd-tools.cjs state signal-waiting --type TYPE --question "..." --options "A|B" --phase P
node gsd-tools.cjs state signal-resume
```
### State Snapshot
### 상태 스냅샷
전체 STATE.md의 구조화된 파싱 결과입니다.
전체 STATE.md의 구조화된 파싱:
```bash
node gsd-tools.cjs state-snapshot
```
현재 위치, 단계, 계획, 상태, 결정, 차단, 메트릭, 최근 활동을 포함한 JSON을 반환합니다.
반환 JSON 포함 항목: 현재 위치, 단계, 계획, 상태, 결정 사항, 차단 항목, 메트릭, 최근 활동.
---
## Phase 명령어
## 단계 명령
단계를 관리합니다 — 디렉터리, 번호 매기기, 로드맵 동기화.
단계 — 디렉토리, 번호 지정, 로드맵 동기화를 관리합니다.
```bash
# 번호로 단계 디렉터리 찾기
# 번호로 단계 디렉토리 찾기
node gsd-tools.cjs find-phase <phase>
# 삽입을 위한 다음 소수 단계 번호 계산
# 삽입을 위한 다음 소수점 단계 번호 계산
node gsd-tools.cjs phase next-decimal <phase>
# 로드맵에 새 단계 추가 + 디렉터리 생성
# 로드맵에 새 단계 추가 + 디렉토리 생성
node gsd-tools.cjs phase add <description>
# 기존 단계 이후에 소수 단계 삽입
# 기존 단계 뒤에 소수점 단계 삽입
node gsd-tools.cjs phase insert <after> <description>
# 단계 제거, 이후 단계 재번호 매기기
# 단계 제거, 이후 번호 재지정
node gsd-tools.cjs phase remove <phase> [--force]
# 단계 완료 표시, state + roadmap 업데이트
# 단계 완료 표시, 상태 + 로드맵 업데이트
node gsd-tools.cjs phase complete <phase>
# 웨이브와 상태를 포함한 계획 인덱싱
# 웨이브 및 상태와 함께 계획 인덱싱
node gsd-tools.cjs phase-plan-index <phase>
# 필터링을 포함한 단계 목록
# 필터링으로 단계 목록 표시
node gsd-tools.cjs phases list [--type planned|executed|all] [--phase N] [--include-archived]
```
---
## Roadmap 명령어
## 로드맵 명령
`ROADMAP.md`를 파싱하고 업데이트합니다.
`ROADMAP.md` 파싱 및 업데이트.
```bash
# ROADMAP.md에서 단계 섹션 추출
@@ -121,27 +138,27 @@ node gsd-tools.cjs roadmap get-phase <phase>
# 디스크 상태를 포함한 전체 로드맵 파싱
node gsd-tools.cjs roadmap analyze
# 디스크에서 진행률 표 행 업데이트
# 디스크에서 진행 테이블 행 업데이트
node gsd-tools.cjs roadmap update-plan-progress <N>
```
---
## Config 명령어
## 설정 명령
`.planning/config.json`을 읽고 씁니다.
`.planning/config.json` 읽기 및 쓰기.
```bash
# config.json을 기본값으로 초기화
# 기본값으로 config.json 초기화
node gsd-tools.cjs config-ensure-section
# config 값 설정 (점 표기법)
# 설정 값 지정 (점 표기법)
node gsd-tools.cjs config-set <key> <value>
# config 값 가져오기
# 설정 값 가져오기
node gsd-tools.cjs config-get <key>
# 모델 프로필 설정
# 모델 프로파일 설정
node gsd-tools.cjs config-set-model-profile <profile>
```
@@ -150,16 +167,18 @@ node gsd-tools.cjs config-set-model-profile <profile>
## 모델 해석
```bash
# 현재 프로필 기반으로 에이전트 모델 가져오기
# 현재 프로파일 기반으로 에이전트에 대한 모델 가져오기
node gsd-tools.cjs resolve-model <agent-name>
# 반환값: opus | sonnet | haiku | inherit
# 원시 출력은 선택된 모델 ID/티어를 반환합니다.
# JSON 출력은 프로파일도 포함하며, 활성 런타임이 지원하는 경우
# reasoning_effort도 포함합니다.
```
에이전트 이름: `gsd-planner`, `gsd-executor`, `gsd-phase-researcher`, `gsd-project-researcher`, `gsd-research-synthesizer`, `gsd-verifier`, `gsd-plan-checker`, `gsd-integration-checker`, `gsd-roadmapper`, `gsd-debugger`, `gsd-codebase-mapper`, `gsd-nyquist-auditor`
---
## Verification 명령어
## 검증 명령
계획, 단계, 참조, 커밋을 검증합니다.
@@ -167,13 +186,13 @@ node gsd-tools.cjs resolve-model <agent-name>
# SUMMARY.md 파일 검증
node gsd-tools.cjs verify-summary <path> [--check-count N]
# PLAN.md 구조 + 작업 확인
# PLAN.md 구조 + 태스크 확인
node gsd-tools.cjs verify plan-structure <file>
# 모든 계획에 요약이 있는지 확인
node gsd-tools.cjs verify phase-completeness <phase>
# @-참조 + 경로 해석 확인
# @-참조 + 경로 확인
node gsd-tools.cjs verify references <file>
# 커밋 해시 일괄 검증
@@ -188,48 +207,57 @@ node gsd-tools.cjs verify key-links <plan-file>
---
## Validation 명령어
## 유효성 검사 명령
프로젝트 무결성을 확인합니다.
프로젝트 무결성 확인.
```bash
# 단계 번호 매기기, 디스크/로드맵 동기화 확인
# 단계 번호 지정, 디스크/로드맵 동기화 확인
node gsd-tools.cjs validate consistency
# .planning/ 무결성 확인, 선택적으로 복구
# .planning/ 무결성 확인, 선택적 복구
node gsd-tools.cjs validate health [--repair]
# 상태 표시줄 / 훅 호출자를 위한 컨텍스트 창 사용률 조회 (v1.40.0)
node gsd-tools.cjs validate context
# 타입이 지정된 JSON 인터페이스로서의 컨텍스트 사용률 (#455)
node gsd-tools.cjs validate context --json
```
`validate context`는 `utilization`, `status`(60% / 70% 임계값에서 `ok` / `warn` / `critical`), `suggestion` 문자열을 포함한 구조화된 봉투를 출력합니다. 동일한 데이터가 `/gsd-health --context`를 지원합니다.
스크립트 및 테스트 어서션에서 타입이 지정된 IR을 직접 수신하려면 `--json`을 전달하세요.
---
## Template 명령어
## 템플릿 명령
템플릿 선택 및 채우기입니다.
템플릿 선택 및 채우기.
```bash
# 세분화에 따른 요약 템플릿 선택
# 세분성에 따라 요약 템플릿 선택
node gsd-tools.cjs template select <type>
# 변수로 템플릿 채우기
node gsd-tools.cjs template fill <type> --phase N [--plan M] [--name "..."] [--type execute|tdd] [--wave N] [--fields '{json}']
```
`fill`의 템플릿 유형: `summary`, `plan`, `verification`
`fill`에 대한 템플릿 유형: `summary`, `plan`, `verification`
---
## Frontmatter 명령어
## 프론트매터 명령
모든 Markdown 파일에 대한 YAML 전문 CRUD 작업입니다.
Markdown 파일에 대한 YAML 프론트매터 CRUD 작업.
```bash
# 전문을 JSON으로 추출
# 프론트매터를 JSON으로 추출
node gsd-tools.cjs frontmatter get <file> [--field key]
# 단일 필드 업데이트
node gsd-tools.cjs frontmatter set <file> --field key --value jsonVal
# JSON을 전문에 병합
# JSON을 프론트매터에 병합
node gsd-tools.cjs frontmatter merge <file> --data '{json}'
# 필수 필드 검증
@@ -238,9 +266,9 @@ node gsd-tools.cjs frontmatter validate <file> --schema plan|summary|verificatio
---
## Scaffold 명령어
## 스캐폴드 명령
사전 구조화된 파일과 디렉터리를 생성합니다.
미리 구조화된 파일 및 디렉토리 생성.
```bash
# CONTEXT.md 템플릿 생성
@@ -252,15 +280,15 @@ node gsd-tools.cjs scaffold uat --phase N
# VERIFICATION.md 템플릿 생성
node gsd-tools.cjs scaffold verification --phase N
# 단계 디렉터리 생성
# 단계 디렉토리 생성
node gsd-tools.cjs scaffold phase-dir --phase N --name "phase name"
```
---
## Init 명령어 (복합 컨텍스트 로드)
## Init 명령 (복합 컨텍스트 로딩)
특정 워크플로우에 필요한 모든 컨텍스트를 단일 호출로 로드합니다. 프로젝트 정보, config, state, 워크플로우별 데이터를 포함한 JSON을 반환합니다.
하나의 호출로 특정 워크플로우에 필요한 모든 컨텍스트를 로드합니다. 프로젝트 정보, 설정, 상태, 워크플로우별 데이터가 포함된 JSON을 반환합니다.
```bash
node gsd-tools.cjs init execute-phase <phase>
@@ -275,9 +303,13 @@ node gsd-tools.cjs init todos [area]
node gsd-tools.cjs init milestone-op
node gsd-tools.cjs init map-codebase
node gsd-tools.cjs init progress
# 워크스트림 범위 init (`--ws` 플래그)
node gsd-tools.cjs init execute-phase <phase> --ws <name>
node gsd-tools.cjs init plan-phase <phase> --ws <name>
```
**대용량 페이로드 처리:** 출력이 약 50KB를 초과하면 CLI가 임시 파일에 쓰고 `@file:/tmp/gsd-init-XXXXX.json`을 반환합니다. 워크플로우는 `@file:` 접두사를 확인하고 디스크에서 읽습니다.
**대용량 페이로드 처리:** 출력이 ~50KB를 초과하면 CLI가 임시 파일에 쓰고 `@file:/tmp/gsd-init-XXXXX.json`을 반환합니다. 워크플로우는 `@file:` 접두사를 확인하고 디스크에서 읽습니다:
```bash
INIT=$(node gsd-tools.cjs init execute-phase "1")
@@ -286,20 +318,52 @@ if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
---
## Milestone 명령어
## 마일스톤 명령
```bash
# 마일스톤 보관
# 마일스톤 아카이브
node gsd-tools.cjs milestone complete <version> [--name <name>] [--archive-phases]
# 요구 사항을 완료로 표시
# 요구사항을 완료로 표시
node gsd-tools.cjs requirements mark-complete <ids>
# 허용 형식: REQ-01,REQ-02 또는 REQ-01 REQ-02 또는 [REQ-01, REQ-02]
```
---
## 유틸리티 명령어
## 에이전트 스킬
지정된 에이전트 유형에 대한 스킬 블록을 출력합니다.
```bash
# 원시 XML 스킬 블록 출력 (기본값 — 셸 확장에 안전)
node gsd-tools.cjs agent-skills <agent-type>
# 타입이 지정된 JSON 인터페이스 출력 (#455) — { agent_type, block, skills_count }
node gsd-tools.cjs agent-skills <agent-type> --json
```
`--json` 플래그는 구조화된 소비 및 테스트 어서션에 적합한 타입이 지정된 IR 객체를 반환하며, 기본값(플래그 없음)은 워크플로우 셸 확장이 의존하는 원시 XML 출력을 보존합니다.
---
## 스킬 매니페스트
더 빠른 명령 로딩을 위한 스킬 검색 사전 계산 및 캐싱.
```bash
# 스킬 매니페스트 생성 (.claude/skill-manifest.json에 기록)
node gsd-tools.cjs skill-manifest
# 사용자 정의 출력 경로로 생성
node gsd-tools.cjs skill-manifest --output <path>
```
사용 가능한 모든 GSD 스킬과 해당 메타데이터(이름, 설명, 파일 경로, 인수 힌트)의 JSON 매핑을 반환합니다. 반복적인 파일시스템 스캔을 방지하기 위해 설치 프로그램과 세션 시작 훅에서 사용됩니다.
---
## 유틸리티 명령
```bash
# 텍스트를 URL 안전 슬러그로 변환
@@ -309,10 +373,10 @@ node gsd-tools.cjs generate-slug "Some Text Here"
# 타임스탬프 가져오기
node gsd-tools.cjs current-timestamp [full|date|filename]
# 대기 중인 할 일 개수 및 목록
# 보류 중인 할 일 카운트 및 목록
node gsd-tools.cjs list-todos [area]
# 파일/디렉터리 존재 확인
# 파일/디렉토리 존재 여부 확인
node gsd-tools.cjs verify-path-exists <path>
# 모든 SUMMARY.md 데이터 집계
@@ -324,44 +388,112 @@ node gsd-tools.cjs summary-extract <path> [--fields field1,field2]
# 프로젝트 통계
node gsd-tools.cjs stats [json|table]
# 진행률 렌더링
# 진행률 렌더링 (사람이 읽을 수 있는 형태)
node gsd-tools.cjs progress [json|table|bar]
# 할 일 완료 처리
# 타입이 지정된 JSON 인터페이스로서의 진행률 (#455)
node gsd-tools.cjs progress --json
# 할 일 완료
node gsd-tools.cjs todo complete <filename>
# UAT 감사 — 모든 단계에서 미해결 항목 스캔
node gsd-tools.cjs audit-uat
# config 확인을 포함한 git 커밋
node gsd-tools.cjs commit <message> [--files f1 f2] [--amend] [--no-verify]
# 교차 아티팩트 감사 큐 — `.planning/`에서 미해결 감사 항목 스캔
node gsd-tools.cjs audit-open [--json]
# GSD-2 프로젝트를 현재 구조로 역 마이그레이션 (`/gsd-import --from-gsd2` 지원)
node gsd-tools.cjs from-gsd2 [--path <dir>] [--force] [--dry-run]
# 설정 확인과 함께 git 커밋
node gsd-tools.cjs commit <message> [--files f1 f2] [--amend] [--no-verify] [--respect-staged]
```
> **`--no-verify`**: 사전 커밋 훅을 건너뜁니다. 빌드 잠금 경쟁을 피하기 위해 웨이브 기반 실행 중 병렬 executor 에이전트가 사용합니다 (예: Rust 프로젝트의 cargo lock 충돌). 오케스트레이터는 각 웨이브 완료 후 훅을 한 번 실행합니다. 순차 실행 중에는 `--no-verify`를 사용하지 마세요 — 훅이 정상적으로 실행되어야 합니다.
> `--no-verify`: 사전 커밋 훅을 건너뜁니다. 병렬 실행기 에이전트가 웨이브 기반 실행 중에 빌드 잠금 충돌(예: Rust 프로젝트의 cargo lock 경쟁)을 방지하기 위해 사용합니다. 오케스트레이터는 각 웨이브 완료 후 훅을 한 번 실행합니다. 순차 실행 중에는 `--no-verify`를 사용하지 마세요 — 훅이 정상적으로 실행되도록 하세요.
> `--files <paths>` **스테이징 동작**: 기본적으로 `--files`는 커밋 전에 각 명명된 파일에 대해 `git add -- <path>`를 실행합니다. 이렇게 하면 `git add -p`를 통해 설정된 헝크별 스테이징이 덮어쓰여집니다. `--respect-staged`를 전달하면 `git add` 단계를 건너뛰고 요청된 경로 사양 내에서 이미 인덱스에 있는 것만 커밋합니다. 해당 범위 내에서 스테이징된 것이 없으면 명령은 오류 없이 `{ committed: false, reason: 'nothing staged' }`를 반환합니다. 커밋의 후행 `-- <paths>` 경로 사양은 두 모드 모두에서 적용되므로 `--files` 범위 외부에서 스테이징된 파일은 절대 포함되지 않습니다(#3061 불변식).
```bash
# 웹 검색 (Brave API 키 필요)
node gsd-tools.cjs websearch <query> [--limit N] [--freshness day|week|month]
```
---
## Graphify
`.planning/graphs/`에서 프로젝트 지식 그래프를 빌드, 쿼리, 검사합니다. `config.json`에서 `graphify.enabled: true`가 필요합니다([설정 참조](CONFIGURATION.md#graphify-settings) 참조).
```bash
# 지식 그래프 빌드 또는 재빌드
node gsd-tools.cjs graphify build
# 그래프에서 용어 검색
node gsd-tools.cjs graphify query <term>
# 그래프 신선도 및 통계 표시
node gsd-tools.cjs graphify status
# 마지막 빌드 이후 변경 사항 표시
node gsd-tools.cjs graphify diff
# 현재 그래프의 명명된 스냅샷 기록
node gsd-tools.cjs graphify snapshot [name]
```
사용자 대면 진입점: `/gsd-graphify` ([명령 참조](COMMANDS.md#gsd-graphify) 참조).
---
## 모듈 아키텍처
| 모듈 | 파일 | 내보내기 |
|--------|------|---------|
| Core | `lib/core.cjs` | `error()`, `output()`, `parseArgs()`, 공유 유틸리티 |
| State | `lib/state.cjs` | 모든 `state` 하위 명령어, `state-snapshot` |
| Phase | `lib/phase.cjs` | Phase CRUD, `find-phase`, `phase-plan-index`, `phases list` |
| Core | `lib/core.cjs` | `error()`, `output()`, `parseArgs()`, 공유 유틸리티, 호환성 재내보내기 |
| State | `lib/state.cjs` | 모든 `state` 서브명령, `state-snapshot` |
| Phase | `lib/phase.cjs` | 단계 CRUD, `find-phase`, `phase-plan-index`, `phases list` |
| Planning Workspace | `lib/planning-workspace.cjs` | 계획 시임: `planningDir`, `planningPaths`, 활성 워크스트림 라우팅, `.planning/.lock` |
| Roadmap | `lib/roadmap.cjs` | 로드맵 파싱, 단계 추출, 진행률 업데이트 |
| Config | `lib/config.cjs` | Config 읽기/쓰기, 섹션 초기화 |
| Verify | `lib/verify.cjs` | 모든 verification 및 validation 명령어 |
| Config | `lib/config.cjs` | 설정 읽기/쓰기, 섹션 초기화 |
| Verify | `lib/verify.cjs` | 모든 검증 및 유효성 검사 명령 |
| Template | `lib/template.cjs` | 템플릿 선택 및 변수 채우기 |
| Frontmatter | `lib/frontmatter.cjs` | YAML 전문 CRUD |
| Init | `lib/init.cjs` | 모든 워크플로우를 위한 복합 컨텍스트 로드 |
| Milestone | `lib/milestone.cjs` | 마일스톤 보관, 요구 사항 표시 |
| Frontmatter | `lib/frontmatter.cjs` | YAML 프론트매터 CRUD |
| Init | `lib/init.cjs` | 모든 워크플로우를 위한 복합 컨텍스트 로딩 |
| Milestone | `lib/milestone.cjs` | 마일스톤 아카이브, 요구사항 표시 |
| Commands | `lib/commands.cjs` | 기타: slug, timestamp, todos, scaffold, stats, websearch |
| Model Profiles | `lib/model-profiles.cjs` | 프로필 해석 테이블 |
| UAT | `lib/uat.cjs` | 단계 간 UAT/verification 감사 |
| Profile Output | `lib/profile-output.cjs` | 개발자 프로필 포매팅 |
| Model Profiles | `lib/model-profiles.cjs` | 프로파일 해석 테이블 |
| UAT | `lib/uat.cjs` | 교차 단계 UAT/검증 감사 |
| Profile Output | `lib/profile-output.cjs` | 개발자 프로파일 서식 지정 |
| Profile Pipeline | `lib/profile-pipeline.cjs` | 세션 분석 파이프라인 |
| Graphify | `lib/graphify.cjs` | 지식 그래프 빌드/쿼리/상태/diff/스냅샷 (`/gsd-graphify` 지원) |
| Learnings | `lib/learnings.cjs` | 단계/SUMMARY 아티팩트에서 학습 내용 추출 (`/gsd-extract-learnings` 지원) |
| Audit | `lib/audit.cjs` | 단계/마일스톤 감사 큐 핸들러; `audit-open` 헬퍼 |
| GSD2 Import | `lib/gsd2-import.cjs` | GSD-2 프로젝트에서 역 마이그레이션 임포터 (`/gsd-import --from-gsd2` 지원) |
| Intel | `lib/intel.cjs` | 쿼리 가능한 코드베이스 인텔리전스 인덱스 (`/gsd-map-codebase --query` 지원) |
---
## 리뷰어 CLI 라우팅
`review.models.<cli>`는 리뷰어 유형을 코드 리뷰 워크플로우가 호출하는 셸 명령에 매핑합니다. [`/gsd-config --integrations`](COMMANDS.md#gsd-config)를 통해 또는 직접 설정:
```bash
node gsd-tools.cjs config-set review.models.codex "codex exec --model gpt-5"
node gsd-tools.cjs config-set review.models.gemini "gemini -m gemini-2.5-pro"
node gsd-tools.cjs config-set review.models.opencode "opencode run --model claude-sonnet-4"
node gsd-tools.cjs config-set review.models.claude "" # clear — fall back to session model
```
슬러그는 `[a-zA-Z0-9_-]+`에 대해 검증됩니다; 비어 있거나 경로를 포함하는 슬러그는 거부됩니다. 전체 필드 참조는 [`docs/CONFIGURATION.md`](CONFIGURATION.md#code-review-cli-routing)를 참조하세요.
## 시크릿 처리
`/gsd-settings`(`brave_search`, `firecrawl`, `exa_search`)를 통해 설정된 API 키는 `.planning/config.json`에 일반 텍스트로 기록되지만 모든 `config-set` / `config-get` 출력, 확인 테이블, 대화형 프롬프트에서 마스킹(`****<last-4>`)됩니다. 마스킹 구현은 `get-shit-done/bin/lib/secrets.cjs`를 참조하세요. `config.json` 파일 자체가 보안 경계입니다 — 파일시스템 권한으로 보호하고 git에서 제외하세요(`.planning/`는 기본적으로 gitignore됩니다).
---
## 관련 문서
- [명령](COMMANDS.md)
- [설정](CONFIGURATION.md)
- [아키텍처](ARCHITECTURE.md)
- [문서 인덱스](README.md)

1539
docs/ko-KR/COMMANDS.md
View File

File diff suppressed because it is too large Load Diff

493
docs/ko-KR/INVENTORY.md Normal file
View File

@@ -0,0 +1,493 @@
# GSD 출시된 표면 인벤토리
> 출시된 모든 GSD 표면의 공식 목록: 명령어, 에이전트, 워크플로우, 레퍼런스, CLI 모듈, 훅. 광범위 문서(AGENTS.md, COMMANDS.md, ARCHITECTURE.md, CLI-TOOLS.md)와 파일시스템이 다를 경우, 이 파일과 저장소 트리를 진실의 원천으로 취급합니다.
## 이 파일 사용 방법
- 여기의 수량은 v1.36.0 핀 기준 파일시스템에서 도출된 것으로, 릴리스 사이에 변동될 수 있습니다. 최신 수량을 확인하려면 체크아웃에서 `ls commands/gsd/*.md | wc -l`, `ls agents/gsd-*.md | wc -l` 등을 실행하세요.
- 이 파일은 6개 패밀리(에이전트, 명령어, 워크플로우, 레퍼런스, CLI 모듈, 훅) 전반에 걸쳐 출시된 모든 표면을 열거합니다. 광범위 문서는 내러티브 또는 엄선된 하위 집합을 렌더링할 수 있습니다. 파일시스템과 불일치할 경우 이 파일과 디렉터리 목록이 권위 있는 출처입니다.
- v1.36.0 이후 추가된 새 표면은 먼저 여기에 기록된 후 광범위 문서로 전파되어야 합니다. `tests/inventory-counts.test.cjs`, `tests/commands-doc-parity.test.cjs`, `tests/agents-doc-parity.test.cjs`, `tests/cli-modules-doc-parity.test.cjs`, `tests/hooks-doc-parity.test.cjs`, `tests/architecture-counts.test.cjs`, `tests/command-count-sync.test.cjs`의 드리프트 제어 테스트가 파일시스템 대비 수량 및 목록 내용을 고정합니다.
이것은 출시된 모든 GSD Core 표면의 공식 목록입니다. 주제별 탐색은 [문서 색인](README.md)을 참조하세요.
---
## 에이전트 (33개 출시)
전체 목록은 `agents/gsd-*.md`에 있습니다. "주요 문서" 열은 [`docs/AGENTS.md`](AGENTS.md)에서 전체 역할 카드(*primary*), "고급 및 특수 에이전트" 섹션의 짧은 스텁(*advanced stub*), 또는 다루지 않음(*inventory only*)을 표시합니다.
| 에이전트 | 역할 (한 줄) | 생성자 | 주요 문서 |
|-------|-----------------|------------|-------------|
| gsd-project-researcher | 로드맵 생성 전 도메인 에코시스템 조사 (스택, 기능, 아키텍처, 함정). | `/gsd-new-project`, `/gsd-new-milestone` | primary |
| gsd-phase-researcher | 계획 전 특정 단계의 구현 방식 조사. | `/gsd-plan-phase` | primary |
| gsd-ui-researcher | 프론트엔드 단계용 UI 설계 계약 생성. | `/gsd-ui-phase` | primary |
| gsd-assumptions-analyzer | discuss-phase (가정 모드)를 위한 근거 기반 가정 생성. | `discuss-phase-assumptions` 워크플로우 | primary |
| gsd-advisor-researcher | discuss-phase 어드바이저 모드에서 단일 회색 지대 결정을 조사. | `discuss-phase` 워크플로우 (어드바이저 모드) | primary |
| gsd-research-synthesizer | 병렬 조사 결과를 통합 SUMMARY.md로 결합. | `/gsd-new-project` | primary |
| gsd-planner | 태스크 분해 및 목표 역방향 검증이 포함된 실행 가능한 단계 계획 생성. | `/gsd-plan-phase`, `/gsd-quick` | primary |
| gsd-roadmapper | 단계 분해 및 요구사항 매핑이 포함된 프로젝트 로드맵 생성. | `/gsd-new-project` | primary |
| gsd-executor | 원자적 커밋과 편차 처리로 GSD 계획 실행. | `/gsd-execute-phase`, `/gsd-quick` | primary |
| gsd-plan-checker | 계획이 단계 목표를 달성할지 검증 (8개 검증 차원). | `/gsd-plan-phase` (검증 루프) | primary |
| gsd-integration-checker | 단계 간 통합 및 엔드투엔드 플로우 검증. | `/gsd-audit-milestone` | primary |
| gsd-ui-checker | 품질 차원에 대한 UI-SPEC.md 설계 계약 검증. | `/gsd-ui-phase` (검증 루프) | primary |
| gsd-verifier | 목표 역방향 분석을 통한 단계 목표 달성 검증. | `/gsd-execute-phase` | primary |
| gsd-nyquist-auditor | 테스트 생성으로 나이퀴스트 검증 공백 채움. | `/gsd-validate-phase` | primary |
| gsd-ui-auditor | 구현된 프론트엔드 코드의 소급 6-기둥 시각 감사. | `/gsd-ui-review` | primary |
| gsd-codebase-mapper | 코드베이스 탐색 및 구조화된 분석 문서 작성. | `/gsd-map-codebase` | primary |
| gsd-debugger | 영속 상태를 사용하는 과학적 방법론으로 버그 조사. | `/gsd-debug`, `/gsd-verify-work` | primary |
| gsd-user-profiler | 8개 차원에서 개발자 행동 점수 산정. | `/gsd-profile-user` | primary |
| gsd-doc-writer | 프로젝트 문서 작성 및 업데이트. | `/gsd-docs-update` | primary |
| gsd-doc-verifier | 생성된 문서의 사실적 주장 검증. | `/gsd-docs-update` | primary |
| gsd-security-auditor | PLAN.md 위협 모델의 위협 완화 검증. | `/gsd-secure-phase` | primary |
| gsd-pattern-mapper | 새 파일을 가장 가까운 기존 유사체에 매핑; 플래너를 위한 PATTERNS.md 작성. | `/gsd-plan-phase` (조사와 계획 사이) | advanced stub |
| gsd-debug-session-manager | 격리된 컨텍스트에서 전체 `/gsd-debug` 체크포인트-및-연속 루프를 실행하여 메인 컨텍스트를 가볍게 유지. | `/gsd-debug` | advanced stub |
| gsd-code-reviewer | 버그, 보안 문제, 코드 품질 문제에 대해 소스 파일 검토; REVIEW.md 생성. | `/gsd-code-review` | advanced stub |
| gsd-code-fixer | REVIEW.md 결과에 수정 사항을 원자적 수정별 커밋으로 적용; REVIEW-FIX.md 생성. | `/gsd-code-review --fix` | advanced stub |
| gsd-ai-researcher | 선택한 AI 프레임워크의 공식 문서를 구현 준비 가이드로 조사 (AI-SPEC.md §3–§4b). | `/gsd-ai-integration-phase` | advanced stub |
| gsd-domain-researcher | AI 시스템을 위한 도메인 전문가 평가 기준 및 실패 모드 표면화 (AI-SPEC.md §1b). | `/gsd-ai-integration-phase` | advanced stub |
| gsd-eval-planner | AI 단계를 위한 구조화된 평가 전략 설계 (AI-SPEC.md §5–§7). | `/gsd-ai-integration-phase` | advanced stub |
| gsd-eval-auditor | AI 단계 평가 범위의 소급 감사; EVAL-REVIEW.md 생성 (COVERED/PARTIAL/MISSING). | `/gsd-eval-review` | advanced stub |
| gsd-framework-selector | AI/LLM 프레임워크를 점수 산정하고 추천하는 ≤6개 질문의 인터랙티브 결정 매트릭스. | `/gsd-ai-integration-phase` | advanced stub |
| gsd-intel-updater | 쿼리 가능한 코드베이스 지식 베이스로 사용되는 구조화된 인텔 파일(`.planning/intel/*.json`) 작성. | `/gsd-map-codebase --query` | advanced stub |
| gsd-doc-classifier | 단일 계획 문서를 ADR, PRD, SPEC, DOC, UNKNOWN으로 분류; 병렬로 생성되어 문서 코퍼스 처리. | `/gsd-ingest-docs` | advanced stub |
| gsd-doc-synthesizer | 분류된 계획 문서를 우선순위 규칙, 순환 감지, 세 버킷 충돌 보고서로 단일 통합 컨텍스트로 합성. | `/gsd-ingest-docs` | advanced stub |
**커버리지 참고.** `docs/AGENTS.md`는 21개 주요 에이전트에 대한 전체 역할 카드와 12개 고급 에이전트에 대한 간결한 스텁을 제공합니다. 해당 파일의 에이전트 도구 권한 요약은 주요 21개 에이전트만 다루며; 고급 에이전트의 도구 목록은 `agents/gsd-*.md`의 에이전트별 프론트매터에 기록됩니다.
---
## 명령어 (67개 출시)
전체 목록은 `commands/gsd/*.md`에 있습니다. 아래 그룹화는 `docs/COMMANDS.md` 섹션 순서를 반영합니다. 각 행은 명령어 이름, 명령어의 프론트매터 `description:`에서 도출된 한 줄 역할, 소스 파일 링크를 포함합니다. `tests/command-count-sync.test.cjs`가 파일시스템 대비 수량을 고정합니다.
### 네임스페이스 메타 스킬
이 6개의 라우터는 모델이 먼저 선택하는 설명자 전용 항목입니다. 각각의 본문에는 올바른 구체적 하위 스킬을 가리키는 라우팅 테이블이 포함되어 있습니다. 이는 전체 표면에 접근 가능하게 유지하면서 즉시 스킬 목록 토큰 비용을 낮게 유지하기 위한 것입니다. 근거는 [#2792](https://github.com/open-gsd/gsd-core/issues/2792) 참조; 라우팅 테이블은 [#2790](https://github.com/open-gsd/gsd-core/issues/2790) 이후 통합된 표면을 대상으로 합니다.
| 명령어 | 역할 | 소스 |
|---------|------|--------|
| `/gsd-workflow` | 단계 파이프라인 라우터 — discuss / plan / execute / verify / phase / progress. | [commands/gsd/ns-workflow.md](../../commands/gsd/ns-workflow.md) |
| `/gsd-project` | 프로젝트 라이프사이클 라우터 — 마일스톤, 감사, 요약. | [commands/gsd/ns-project.md](../../commands/gsd/ns-project.md) |
| `/gsd-quality` | 품질 게이트 라우터 — 코드 리뷰, 디버그, 감사, 보안, 평가, UI. | [commands/gsd/ns-review.md](../../commands/gsd/ns-review.md) |
| `/gsd-context` | 코드베이스 인텔리전스 라우터 — 맵, 그래프화, 문서, 학습. | [commands/gsd/ns-context.md](../../commands/gsd/ns-context.md) |
| `/gsd-manage` | 관리 라우터 — 설정, 워크스페이스, 워크스트림, 스레드, 업데이트, 출시, 인박스. | [commands/gsd/ns-manage.md](../../commands/gsd/ns-manage.md) |
| `/gsd-ideate` | 탐색 및 캡처 라우터 — 탐색, 스케치, 스파이크, 스펙, 캡처. | [commands/gsd/ns-ideate.md](../../commands/gsd/ns-ideate.md) |
### 핵심 워크플로우
| 명령어 | 역할 | 소스 |
|---------|------|--------|
| `/gsd-new-project` | 심층 컨텍스트 수집 및 PROJECT.md로 새 프로젝트 초기화. | [commands/gsd/new-project.md](../../commands/gsd/new-project.md) |
| `/gsd-workspace` | GSD 워크스페이스 관리 — 격리된 워크스페이스 환경을 생성(`--new`), 목록(`--list`), 또는 제거(`--remove`). | [commands/gsd/workspace.md](../../commands/gsd/workspace.md) |
| `/gsd-discuss-phase` | 계획 전 적응형 질문을 통한 단계 컨텍스트 수집. | [commands/gsd/discuss-phase.md](../../commands/gsd/discuss-phase.md) |
| `/gsd-mvp-phase` | 수직 MVP 슬라이스로 단계 계획 — 사용자 스토리, SPIDR 분할, 이후 plan-phase. | [commands/gsd/mvp-phase.md](../../commands/gsd/mvp-phase.md) |
| `/gsd-spec-phase` | 반증 가능한 요구사항을 담은 SPEC.md를 생성하는 소크라테스식 스펙 정제. | [commands/gsd/spec-phase.md](../../commands/gsd/spec-phase.md) |
| `/gsd-ui-phase` | 프론트엔드 단계용 UI 설계 계약(UI-SPEC.md) 생성. | [commands/gsd/ui-phase.md](../../commands/gsd/ui-phase.md) |
| `/gsd-ai-integration-phase` | 프레임워크 선택, 조사, 평가 계획을 통한 AI 설계 계약(AI-SPEC.md) 생성. | [commands/gsd/ai-integration-phase.md](../../commands/gsd/ai-integration-phase.md) |
| `/gsd-plan-phase` | 검증 루프가 포함된 상세 단계 계획(PLAN.md) 생성. | [commands/gsd/plan-phase.md](../../commands/gsd/plan-phase.md) |
| `/gsd-plan-review-convergence` | 교차 AI 계획 수렴 루프 — HIGH 우려사항이 없을 때까지 리뷰 피드백으로 재계획 (최대 3사이클). | [commands/gsd/plan-review-convergence.md](../../commands/gsd/plan-review-convergence.md) |
| `/gsd-ultraplan-phase` | [BETA] 계획 단계를 Claude Code의 ultraplan 클라우드에 오프로드 — 원격으로 초안 작성, 브라우저에서 검토, `/gsd-import`로 가져오기. Claude Code 전용. | [commands/gsd/ultraplan-phase.md](../../commands/gsd/ultraplan-phase.md) |
| `/gsd-spike` | 일회성 실험으로 아이디어를 빠르게 스파이크; `--wrap-up`으로 결과를 영구 스킬로 패키징. | [commands/gsd/spike.md](../../commands/gsd/spike.md) |
| `/gsd-sketch` | 일회성 HTML 목업을 사용한 UI/설계 아이디어 빠른 스케치; `--wrap-up`으로 결과 패키징. | [commands/gsd/sketch.md](../../commands/gsd/sketch.md) |
| `/gsd-execute-phase` | 웨이브 기반 병렬화로 단계의 모든 계획 실행. | [commands/gsd/execute-phase.md](../../commands/gsd/execute-phase.md) |
| `/gsd-verify-work` | 자동 진단을 포함한 대화형 UAT로 구축된 기능 검증. | [commands/gsd/verify-work.md](../../commands/gsd/verify-work.md) |
| `/gsd-ship` | 검증 후 PR 생성, 리뷰 실행, 병합 준비. | [commands/gsd/ship.md](../../commands/gsd/ship.md) |
| `/gsd-fast` | 하위 에이전트 없이, 계획 오버헤드 없이 인라인으로 사소한 태스크 실행. | [commands/gsd/fast.md](../../commands/gsd/fast.md) |
| `/gsd-quick` | GSD 보장(원자적 커밋, 상태 추적)으로 빠른 태스크 실행, 선택적 에이전트는 생략. | [commands/gsd/quick.md](../../commands/gsd/quick.md) |
| `/gsd-ui-review` | 구현된 프론트엔드 코드의 소급 6-기둥 시각 감사. | [commands/gsd/ui-review.md](../../commands/gsd/ui-review.md) |
| `/gsd-code-review` | 단계에서 변경된 소스 파일을 버그, 보안, 코드 품질 문제에 대해 검토; `--fix`로 결과 자동 적용. | [commands/gsd/code-review.md](../../commands/gsd/code-review.md) |
| `/gsd-eval-review` | 실행된 AI 단계의 평가 범위를 소급 감사; EVAL-REVIEW.md 생성. | [commands/gsd/eval-review.md](../../commands/gsd/eval-review.md) |
### 단계 및 마일스톤 관리
| 명령어 | 역할 | 소스 |
|---------|------|--------|
| `/gsd-phase` | 단계 CRUD — ROADMAP.md에서 단계 추가(기본값), 삽입(`--insert`), 제거(`--remove`), 편집(`--edit`). | [commands/gsd/phase.md](../../commands/gsd/phase.md) |
| `/gsd-add-tests` | UAT 기준 및 구현에 기반한 완료된 단계의 테스트 생성. | [commands/gsd/add-tests.md](../../commands/gsd/add-tests.md) |
| `/gsd-validate-phase` | 완료된 단계의 나이퀴스트 검증 공백을 소급 감사 및 채움. | [commands/gsd/validate-phase.md](../../commands/gsd/validate-phase.md) |
| `/gsd-secure-phase` | 완료된 단계의 위협 완화를 소급 검증. | [commands/gsd/secure-phase.md](../../commands/gsd/secure-phase.md) |
| `/gsd-audit-milestone` | 아카이브 전 원래 의도 대비 마일스톤 완료 감사. | [commands/gsd/audit-milestone.md](../../commands/gsd/audit-milestone.md) |
| `/gsd-audit-uat` | 미완료된 모든 UAT 및 검증 항목의 단계 간 감사. | [commands/gsd/audit-uat.md](../../commands/gsd/audit-uat.md) |
| `/gsd-audit-fix` | 자율 감사-수정 파이프라인 — 문제 찾기, 분류, 수정, 테스트, 커밋. | [commands/gsd/audit-fix.md](../../commands/gsd/audit-fix.md) |
| `/gsd-complete-milestone` | 완료된 마일스톤 아카이브 및 다음 버전 준비. | [commands/gsd/complete-milestone.md](../../commands/gsd/complete-milestone.md) |
| `/gsd-new-milestone` | 새 마일스톤 사이클 시작 — PROJECT.md 업데이트 및 요구사항으로 라우팅. | [commands/gsd/new-milestone.md](../../commands/gsd/new-milestone.md) |
| `/gsd-milestone-summary` | 마일스톤 아티팩트로부터 포괄적인 프로젝트 요약 생성. | [commands/gsd/milestone-summary.md](../../commands/gsd/milestone-summary.md) |
| `/gsd-cleanup` | 완료된 마일스톤에서 누적된 단계 디렉터리 아카이브. | [commands/gsd/cleanup.md](../../commands/gsd/cleanup.md) |
| `/gsd-manager` | 하나의 터미널에서 여러 단계를 관리하는 인터랙티브 커맨드 센터. | [commands/gsd/manager.md](../../commands/gsd/manager.md) |
| `/gsd-workstreams` | 병렬 워크스트림 관리 — 목록, 생성, 전환, 상태, 진행도, 완료, 재개. | [commands/gsd/workstreams.md](../../commands/gsd/workstreams.md) |
| `/gsd-autonomous` | 나머지 모든 단계를 자율적으로 실행 — 단계별 discuss → plan → execute. | [commands/gsd/autonomous.md](../../commands/gsd/autonomous.md) |
| `/gsd-undo` | 안전한 git 되돌리기 — 단계 매니페스트를 사용하여 단계 또는 계획 커밋 롤백. | [commands/gsd/undo.md](../../commands/gsd/undo.md) |
### 세션 및 탐색
| 명령어 | 역할 | 소스 |
|---------|------|--------|
| `/gsd-progress` | 프로젝트 진행도 확인, 컨텍스트 표시, 다음 액션으로 라우팅; `--next`로 자동 진행 또는 `--do`로 자유 형식 태스크 실행. | [commands/gsd/progress.md](../../commands/gsd/progress.md) |
| `/gsd-capture` | 아이디어, 태스크, 메모, 씨앗 캡처 — todo(기본값), `--note`, `--backlog`, `--seed`, 또는 `--list` 미완료 todo. | [commands/gsd/capture.md](../../commands/gsd/capture.md) |
| `/gsd-stats` | 프로젝트 통계 표시 — 단계, 계획, 요구사항, git 메트릭, 타임라인. | [commands/gsd/stats.md](../../commands/gsd/stats.md) |
| `/gsd-pause-work` | 단계 중간에 작업을 일시 중지할 때 컨텍스트 핸드오프 생성. | [commands/gsd/pause-work.md](../../commands/gsd/pause-work.md) |
| `/gsd-resume-work` | 이전 세션에서 전체 컨텍스트 복원으로 작업 재개. | [commands/gsd/resume-work.md](../../commands/gsd/resume-work.md) |
| `/gsd-explore` | 소크라테스식 아이디어 발상 및 라우팅 — 커밋 전 아이디어 심화 검토. | [commands/gsd/explore.md](../../commands/gsd/explore.md) |
| `/gsd-review-backlog` | 백로그 항목 검토 및 활성 마일스톤으로 승격. | [commands/gsd/review-backlog.md](../../commands/gsd/review-backlog.md) |
| `/gsd-thread` | 세션 간 작업을 위한 영속 컨텍스트 스레드 관리. | [commands/gsd/thread.md](../../commands/gsd/thread.md) |
### 코드베이스 인텔리전스
| 명령어 | 역할 | 소스 |
|---------|------|--------|
| `/gsd-map-codebase` | 병렬 매퍼 에이전트로 코드베이스 분석; 경량 스캔은 `--fast`, 인텔 쿼리는 `--query`. | [commands/gsd/map-codebase.md](../../commands/gsd/map-codebase.md) |
| `/gsd-graphify` | `.planning/graphs/`의 프로젝트 지식 그래프 구축, 쿼리, 검사. | [commands/gsd/graphify.md](../../commands/gsd/graphify.md) |
| `/gsd-extract-learnings` | 완료된 단계 아티팩트에서 결정, 교훈, 패턴, 놀라운 점 추출. | [commands/gsd/extract-learnings.md](../../commands/gsd/extract-learnings.md) |
### 리뷰, 디버그 및 복구
| 명령어 | 역할 | 소스 |
|---------|------|--------|
| `/gsd-review` | 외부 AI CLI에서 단계 계획의 교차 AI 피어 리뷰 요청. | [commands/gsd/review.md](../../commands/gsd/review.md) |
| `/gsd-debug` | 컨텍스트 재설정 전반에 걸쳐 영속 상태를 사용하는 체계적 디버깅. | [commands/gsd/debug.md](../../commands/gsd/debug.md) |
| `/gsd-forensics` | 실패한 GSD 워크플로우의 사후 조사 — git, 아티팩트, 상태 분석. | [commands/gsd/forensics.md](../../commands/gsd/forensics.md) |
| `/gsd-health` | 계획 디렉터리 상태를 진단하고 선택적으로 문제 수정. | [commands/gsd/health.md](../../commands/gsd/health.md) |
| `/gsd-import` | 프로젝트 결정에 대한 충돌 감지로 외부 계획 수집. | [commands/gsd/import.md](../../commands/gsd/import.md) |
| `/gsd-inbox` | 프로젝트 템플릿에 대한 모든 열린 GitHub 이슈 및 PR 분류 및 검토. | [commands/gsd/inbox.md](../../commands/gsd/inbox.md) |
### 문서, 프로필 및 유틸리티
| 명령어 | 역할 | 소스 |
|---------|------|--------|
| `/gsd-docs-update` | 코드베이스에 대해 검증된 프로젝트 문서 생성 또는 업데이트. | [commands/gsd/docs-update.md](../../commands/gsd/docs-update.md) |
| `/gsd-ingest-docs` | 혼합 ADR/PRD/SPEC/DOC가 있는 저장소를 스캔하고 분류, 합성, 충돌 보고서로 전체 `.planning/` 설정을 부트스트랩 또는 병합. | [commands/gsd/ingest-docs.md](../../commands/gsd/ingest-docs.md) |
| `/gsd-profile-user` | 개발자 행동 프로필 및 Claude 검색 가능한 아티팩트 생성. | [commands/gsd/profile-user.md](../../commands/gsd/profile-user.md) |
| `/gsd-settings` | GSD 워크플로우 토글 및 모델 프로필 구성. | [commands/gsd/settings.md](../../commands/gsd/settings.md) |
| `/gsd-config` | GSD 설정 구성 — 워크플로우 토글(기본값), 고급 설정(`--advanced`), 통합(`--integrations`), 또는 모델 프로필(`--profile`). | [commands/gsd/config.md](../../commands/gsd/config.md) |
| `/gsd-pr-branch` | `.planning/` 커밋을 필터링하여 깔끔한 PR 브랜치 생성. | [commands/gsd/pr-branch.md](../../commands/gsd/pr-branch.md) |
| `/gsd-surface` | 표면화할 스킬 토글 — 재설치 없이 프로필 적용, 목록 보기, 클러스터 비활성화. | [commands/gsd/surface.md](../../commands/gsd/surface.md) |
| `/gsd-update` | GSD를 최신 버전으로 업데이트; `--sync`로 런타임 간 스킬 동기화 또는 `--reapply`로 로컬 패치 재적용. | [commands/gsd/update.md](../../commands/gsd/update.md) |
| `/gsd-help` | 사용 가능한 GSD 명령어 및 사용 가이드 표시. | [commands/gsd/help.md](../../commands/gsd/help.md) |
---
## 워크플로우 (88개 출시)
전체 목록은 `get-shit-done/workflows/*.md`에 있습니다. 워크플로우는 명령어가 내부적으로 참조하는 얇은 오케스트레이터입니다; 대부분은 최종 사용자가 직접 읽지 않습니다. 아래 행은 각 워크플로우 파일을 역할(`<purpose>` 블록에서 도출)과, 해당하는 경우 호출 명령어에 매핑합니다.
| 워크플로우 | 역할 | 호출자 |
|----------|------|------------|
| `add-backlog.md` | 999.x 번호 체계를 사용하여 ROADMAP.md에 백로그 항목 추가. | `/gsd-capture --backlog` |
| `add-phase.md` | 로드맵의 현재 마일스톤 끝에 새 정수 단계 추가. | `/gsd-phase` (기본값) |
| `add-tests.md` | 완료된 단계의 아티팩트를 기반으로 단위 및 E2E 테스트 생성. | `/gsd-add-tests` |
| `add-todo.md` | 세션 중 발생하는 아이디어나 태스크를 구조화된 todo로 캡처. | `/gsd-capture` (기본값) |
| `ai-integration-phase.md` | 프레임워크 선택 → AI 조사 → 도메인 조사 → 평가 계획을 AI-SPEC.md로 오케스트레이션. | `/gsd-ai-integration-phase` |
| `analyze-dependencies.md` | 파일 겹침 및 의미론적 의존성에 대한 ROADMAP.md 단계 분석; `Depends on` 엣지 제안. | `/gsd-manager --analyze-deps` |
| `audit-fix.md` | 자율 감사-수정 파이프라인 — 감사 실행, 파싱, 분류, 수정, 테스트, 커밋. | `/gsd-audit-fix` |
| `audit-milestone.md` | 단계 검증을 집계하여 마일스톤이 완료 정의를 충족했는지 확인. | `/gsd-audit-milestone` |
| `audit-uat.md` | UAT 및 검증 파일의 단계 간 감사; 우선순위화된 미완료 항목 목록 생성. | `/gsd-audit-uat` |
| `autonomous.md` | 마일스톤 단계를 자율적으로 구동 — 나머지 모두, 범위, 또는 단일 단계. | `/gsd-autonomous` |
| `check-todos.md` | 미완료 todo 목록, 선택 허용, 컨텍스트 로드, 적절한 액션으로 라우팅. | `/gsd-capture --list` |
| `cleanup.md` | 완료된 마일스톤에서 누적된 단계 디렉터리 아카이브. | `/gsd-cleanup` |
| `code-review-fix.md` | gsd-code-fixer를 통해 수정별 원자적 커밋으로 REVIEW.md의 문제 자동 수정. | `/gsd-code-review --fix` |
| `code-review.md` | gsd-code-reviewer를 통한 단계 소스 변경 검토; REVIEW.md 생성. | `/gsd-code-review` |
| `complete-milestone.md` | 출시된 버전을 완료로 표시 — MILESTONES.md 항목, PROJECT.md 발전, 태그. | `/gsd-complete-milestone` |
| `diagnose-issues.md` | UAT 공백 조사 및 근본 원인 찾기를 위한 병렬 디버그 에이전트 오케스트레이션. | `/gsd-verify-work` (자동 진단) |
| `discovery-phase.md` | 적절한 깊이 수준에서 탐색 실행. | `/gsd-new-project` (탐색 경로) |
| `discuss-phase-assumptions.md` | 가정 모드 discuss — 코드베이스 우선 분석을 통한 구현 결정 추출. | `/gsd-discuss-phase` (`discuss_mode=assumptions`일 때) |
| `discuss-phase-power.md` | 파워 유저 discuss — 모든 질문을 JSON 상태 파일 + HTML UI로 사전 생성. | `/gsd-discuss-phase --power` |
| `discuss-phase.md` | 반복적인 회색 지대 토론을 통한 구현 결정 추출. | `/gsd-discuss-phase` |
| `mvp-phase.md` | 수직 MVP 슬라이스로 단계 계획 — 사용자 스토리, SPIDR 분할, 이후 plan-phase. | `/gsd-mvp-phase` |
| `do.md` | 사용자의 자유 형식 텍스트를 가장 적합한 GSD 명령어로 라우팅. | `/gsd-progress --do` |
| `docs-update.md` | 표준 및 수작업 프로젝트 문서 생성, 업데이트, 검증. | `/gsd-docs-update` |
| `edit-phase.md` | ROADMAP.md에서 기존 단계의 임의 필드를 번호와 위치를 유지한 채 인플레이스 편집. | `/gsd-phase --edit` |
| `eval-review.md` | 구현된 AI 단계의 평가 범위에 대한 소급 감사. | `/gsd-eval-review` |
| `execute-phase.md` | 웨이브 기반 병렬 실행으로 단계의 모든 계획 실행. | `/gsd-execute-phase` |
| `execute-plan.md` | 단계 프롬프트(PLAN.md)를 실행하고 결과 요약(SUMMARY.md) 생성. | `execute-phase.md` (계획별 하위 에이전트) |
| `explore.md` | 소크라테스식 아이디어 발상 — 탐색적 질문으로 개발자 안내. | `/gsd-explore` |
| `debug.md` | 체계적 디버깅 — 하위 명령어 라우팅, 세션 생성, gsd-debug-session-manager 위임. | `/gsd-debug` |
| `extract-learnings.md` | 완료된 단계 아티팩트에서 결정, 교훈, 패턴, 놀라운 점 추출. | `/gsd-extract-learnings` |
| `fast.md` | 하위 에이전트 오버헤드 없이 사소한 태스크 인라인 실행. | `/gsd-fast` |
| `forensics.md` | 실패한 워크플로우의 포렌식 조사 — git, 아티팩트, 상태 분석. | `/gsd-forensics` |
| `graduation.md` | 단계 간 반복되는 LEARNINGS.md 항목을 클러스터링하고 HITL 승격 후보 표면화. | `transition.md` (graduation_scan 단계) |
| `health.md` | `.planning/` 디렉터리 무결성 검증 및 실행 가능한 문제 보고. | `/gsd-health` |
| `help.md` | 전체 GSD Core 명령어 참조 표시. | `/gsd-help` |
| `import.md` | 기존 프로젝트 결정에 대한 충돌 감지로 외부 계획 수집. | `/gsd-import` |
| `inbox.md` | 프로젝트 기여 템플릿에 대한 열린 GitHub 이슈 및 PR 분류. | `/gsd-inbox` |
| `ingest-docs.md` | 혼합 계획 문서에 대한 저장소 스캔; 분류, 합성, 충돌 보고서로 `.planning/`에 부트스트랩 또는 병합. | `/gsd-ingest-docs` |
| `insert-phase.md` | 마일스톤 중간에 발견된 긴급 작업을 위한 소수점 단계 삽입. | `/gsd-phase --insert` |
| `list-phase-assumptions.md` | 계획 전 Claude의 단계에 대한 가정 표면화. | `/gsd-discuss-phase --assumptions` |
| `list-workspaces.md` | `~/gsd-workspaces/`에서 찾은 모든 GSD 워크스페이스를 상태와 함께 목록. | `/gsd-workspace --list` |
| `manager.md` | 인터랙티브 마일스톤 커맨드 센터 — 대시보드, 인라인 discuss, 백그라운드 plan/execute. | `/gsd-manager` |
| `map-codebase.md` | 병렬 코드베이스 매퍼 에이전트를 오케스트레이션하여 `.planning/codebase/` 문서 생성. | `/gsd-map-codebase` |
| `milestone-summary.md` | 마일스톤 아티팩트에서 온보딩 및 검토용 마일스톤 요약 합성. | `/gsd-milestone-summary` |
| `new-milestone.md` | 새 마일스톤 사이클 시작 — 프로젝트 컨텍스트 로드, 목표 수집, PROJECT.md/STATE.md 업데이트. | `/gsd-new-milestone` |
| `new-project.md` | 통합 새 프로젝트 플로우 — 질문, 조사(선택), 요구사항, 로드맵. | `/gsd-new-project` |
| `new-workspace.md` | 저장소 워크트리/클론과 독립적인 `.planning/`이 포함된 격리된 워크스페이스 생성. | `/gsd-workspace --new` |
| `next.md` | 현재 프로젝트 상태를 감지하고 다음 논리적 단계로 자동 진행. | `/gsd-progress --next` |
| `node-repair.md` | 실패한 태스크 검증을 위한 자율 수리 오퍼레이터; `execute-plan`에 의해 호출. | `execute-plan.md` (복구) |
| `note.md` | 마찰 없는 아이디어 캡처 — 단일 Write 호출, 단일 확인 줄. | `/gsd-capture --note` |
| `pause-work.md` | 구조화된 `.planning/HANDOFF.json` 및 `.continue-here.md` 핸드오프 파일 생성. | `/gsd-pause-work` |
| `plan-phase.md` | 통합 조사 및 검증 루프로 실행 가능한 PLAN.md 파일 생성. | `/gsd-plan-phase`, `/gsd-quick` |
| `plan-review-convergence.md` | 교차 AI 계획 수렴 루프 — HIGH 우려사항이 없을 때까지 리뷰 피드백으로 재계획. | `/gsd-plan-review-convergence` |
| `plant-seed.md` | 트리거 조건이 포함된 구조화된 씨앗 파일로 미래 지향적인 아이디어 캡처. | `/gsd-capture --seed` |
| `pr-branch.md` | `.planning/` 커밋을 필터링하여 풀 리퀘스트를 위한 깔끔한 브랜치 생성. | `/gsd-pr-branch` |
| `profile-user.md` | 전체 개발자 프로파일링 플로우 오케스트레이션 — 동의, 세션 스캔, 프로필 생성. | `/gsd-profile-user` |
| `progress.md` | 진행도 렌더링 — 프로젝트 컨텍스트, 위치, 다음 액션 라우팅. | `/gsd-progress` |
| `quick.md` | GSD 보장(원자적 커밋, 상태 추적)으로 빠른 태스크 실행. | `/gsd-quick` |
| `reapply-patches.md` | GSD 업데이트 후 로컬 수정 사항 재적용. | `/gsd-update --reapply` |
| `remove-phase.md` | 로드맵에서 미래 단계를 제거하고 후속 단계 번호 재지정. | `/gsd-phase --remove` |
| `remove-workspace.md` | GSD 워크스페이스 제거 및 워크트리 정리. | `/gsd-workspace --remove` |
| `resume-project.md` | 작업 재개 — STATE.md, HANDOFF.json, 아티팩트에서 전체 컨텍스트 복원. | `/gsd-resume-work` |
| `review.md` | 외부 CLI를 통한 교차 AI 계획 리뷰; REVIEWS.md 생성. | `/gsd-review` |
| `scan.md` | 신속한 단일 포커스 코드베이스 스캔 — map-codebase의 경량 대안. | `/gsd-map-codebase --fast` |
| `secure-phase.md` | 완료된 단계에 대한 소급 위협 완화 감사. | `/gsd-secure-phase` |
| `session-report.md` | 세션 보고서 — 토큰 사용량, 작업 요약, 결과. | `/gsd-pause-work --report` |
| `settings.md` | GSD 워크플로우 토글 및 모델 프로필 구성. | `/gsd-settings`, `/gsd-config --profile` |
| `settings-advanced.md` | GSD 파워 유저 설정 구성 — 계획 바운스, 타임아웃, 브랜치 템플릿, 교차 AI 실행, 런타임 설정. | `/gsd-config --advanced` |
| `settings-integrations.md` | 타사 API 키(Brave/Firecrawl/Exa), `review.models.<cli>` CLI 라우팅, 마스킹된(`****<last-4>`) 표시로 `agent_skills.<agent-type>` 주입 구성. | `/gsd-config --integrations` |
| `ship.md` | 검증 후 PR 생성, 리뷰 실행, 병합 준비. | `/gsd-ship` |
| `sketch.md` | 스케치당 2-3개 변형으로 일회성 HTML 목업을 통한 설계 방향 탐색. | `/gsd-sketch` |
| `sketch-wrap-up.md` | 스케치 결과를 큐레이션하고 영구 `sketch-findings-[project]` 스킬로 패키징. | `/gsd-sketch --wrap-up` |
| `spec-phase.md` | 모호성 점수가 포함된 소크라테스식 스펙 정제; SPEC.md 생성. | `/gsd-spec-phase` |
| `spike.md` | 포커스된 일회성 실험을 통한 빠른 실현 가능성 검증. | `/gsd-spike` |
| `spike-wrap-up.md` | 스파이크 결과를 큐레이션하고 영구 `spike-findings-[project]` 스킬로 패키징. | `/gsd-spike --wrap-up` |
| `stats.md` | 프로젝트 통계 렌더링 — 단계, 계획, 요구사항, git 메트릭. | `/gsd-stats` |
| `sync-skills.md` | 교차 런타임 GSD 스킬 동기화 — 런타임 루트 간 `gsd-*` 스킬 디렉터리 비교 및 적용. | `/gsd-update --sync` |
| `transition.md` | 단계 경계 전환 워크플로우 — 워크스트림 확인, 상태 진행. | `execute-phase.md`, `/gsd-progress --next` |
| `ui-phase.md` | gsd-ui-researcher를 통한 UI-SPEC.md 설계 계약 생성. | `/gsd-ui-phase` |
| `ui-review.md` | gsd-ui-auditor를 통한 소급 6-기둥 시각 감사. | `/gsd-ui-review` |
| `ultraplan-phase.md` | [BETA] 계획을 Claude Code의 ultraplan 클라우드에 오프로드; 원격으로 초안 작성 후 `/gsd-import`로 가져오기. | `/gsd-ultraplan-phase` |
| `undo.md` | 안전한 git 되돌리기 — 단계 매니페스트를 사용한 단계 또는 계획 커밋. | `/gsd-undo` |
| `thread.md` | 세션 간 작업을 위한 영속 컨텍스트 스레드 생성, 목록, 닫기, 재개. | `/gsd-thread` |
| `update.md` | 체인지로그 표시와 함께 GSD를 최신 버전으로 업데이트. | `/gsd-update` |
| `validate-phase.md` | 완료된 단계의 나이퀴스트 검증 공백을 소급 감사 및 채움. | `/gsd-validate-phase` |
| `verify-phase.md` | 목표 역방향 분석을 통한 단계 목표 달성 검증. | `execute-phase.md` (실행 후) |
| `verify-work.md` | 자동 진단이 포함된 대화형 UAT — UAT.md 및 수정 계획 생성. | `/gsd-verify-work` |
> **참고:** 일부 워크플로우는 직접적인 사용자 대면 명령어가 없습니다(예: `execute-plan.md`, `verify-phase.md`, `transition.md`, `node-repair.md`, `diagnose-issues.md`) — 이들은 오케스트레이터 워크플로우에 의해 내부적으로 호출됩니다. `discovery-phase.md`는 `/gsd-new-project`의 대체 진입점입니다.
---
## 레퍼런스 (62개 출시)
전체 목록은 `get-shit-done/references/*.md`에 있습니다. 레퍼런스는 워크플로우와 에이전트가 `@-참조`하는 공유 지식 문서입니다. 아래 그룹화는 [`docs/ARCHITECTURE.md`](ARCHITECTURE.md#references-get-shit-donereferencesmd) — 코어, 워크플로우, 씽킹 모델 클러스터, 모듈식 플래너 분해에 일치합니다.
### 코어 레퍼런스
| 레퍼런스 | 역할 |
|-----------|------|
| `checkpoints.md` | 체크포인트 유형 정의 및 상호작용 패턴. |
| `gates.md` | plan-checker 및 verifier에 연결된 4개 표준 게이트 유형(Confirm, Quality, Safety, Transition). |
| `model-profiles.md` | 에이전트별 모델 티어 할당. |
| `model-profile-resolution.md` | 모델 해석 알고리즘 문서. |
| `verification-patterns.md` | 다양한 아티팩트 유형 검증 방법. |
| `verification-overrides.md` | 아티팩트별 검증 재정의 규칙. |
| `planning-config.md` | 전체 설정 스키마 및 동작. |
| `git-integration.md` | Git 커밋, 브랜칭, 히스토리 패턴. |
| `git-planning-commit.md` | 계획 디렉터리 커밋 관례. |
| `questioning.md` | 프로젝트 초기화를 위한 꿈 추출 철학. |
| `tdd.md` | 테스트 주도 개발 통합 패턴. |
| `ui-brand.md` | 시각적 출력 포매팅 패턴. |
| `common-bug-patterns.md` | 코드 리뷰 및 검증을 위한 일반적인 버그 패턴. |
| `debugger-philosophy.md` | `gsd-debugger`가 로드하는 상시 디버깅 원칙. |
| `mandatory-initial-read.md` | 에이전트 프롬프트에 주입되는 공유 필수 읽기 상용구. |
| `project-skills-discovery.md` | 에이전트 프롬프트에 주입되는 공유 프로젝트 스킬 발견 상용구. |
### 워크플로우 레퍼런스
| 레퍼런스 | 역할 |
|-----------|------|
| `agent-contracts.md` | 오케스트레이터와 에이전트 간의 공식 인터페이스. |
| `context-budget.md` | 컨텍스트 윈도우 예산 할당 규칙. |
| `continuation-format.md` | 세션 연속/재개 포맷. |
| `domain-probes.md` | discuss-phase를 위한 도메인별 탐색 질문. |
| `gate-prompts.md` | 게이트/체크포인트 프롬프트 템플릿. |
| `scout-codebase.md` | discuss-phase 스카우트 단계를 위한 단계 유형→코드베이스 맵 선택 테이블(#2551로 추출). |
| `revision-loop.md` | 계획 수정 반복 패턴. |
| `universal-anti-patterns.md` | 감지하고 피해야 할 보편적인 안티패턴. |
| `worktree-path-safety.md` | 워크트리 가드 스위트: HEAD 어설션, cwd-드리프트 센티널(0a단계, #3097), 절대 경로 가드(0b단계, #3099) — `<execution_context>`를 통해 executor 스폰 프롬프트에 로드됨. |
| `artifact-types.md` | 계획 아티팩트 유형 정의. |
| `phase-argument-parsing.md` | 단계 인수 파싱 관례. |
| `decimal-phase-calculation.md` | 소수점 하위 단계 번호 규칙. |
| `workstream-flag.md` | 워크스트림 활성 포인터 관례(`--ws`). |
| `user-profiling.md` | 사용자 행동 프로파일링 감지 휴리스틱. |
| `thinking-partner.md` | 결정 시점에서의 조건부 씽킹 파트너 활성화. |
| `autonomous-smart-discuss.md` | 자율 모드를 위한 스마트 discuss 로직. |
| `ios-scaffold.md` | iOS 애플리케이션 스캐폴딩 패턴. |
| `ai-evals.md` | `/gsd-ai-integration-phase`를 위한 AI 평가 설계 레퍼런스. |
| `ai-frameworks.md` | `gsd-framework-selector`를 위한 AI 프레임워크 결정 매트릭스 레퍼런스. |
| `executor-examples.md` | gsd-executor 에이전트를 위한 작업 예시. |
| `doc-conflict-engine.md` | ingest/import 워크플로우를 위한 공유 충돌 감지 계약. |
| `execute-mvp-tdd.md` | MVP+TDD 하의 execute-phase 런타임 게이트 시맨틱 — 태스크 전 실패 테스트 검증, 단계 말 차단 리뷰. |
| `mvp-concepts.md` | 6개 MVP 관련 레퍼런스 파일에 대한 교차 참조 색인; 각 파일의 목적과 어떤 워크플로우가 로드하는지 매핑. |
| `verify-mvp-mode.md` | MVP 모드 단계를 위한 UAT 프레이밍 규칙 — 사용자 플로우 우선 순서, 지연된 기술적 확인, 사용자 스토리 형식 가드. |
### 스케치 레퍼런스
`/gsd-sketch` 워크플로우 및 그 wrap-up 동반자에 의해 사용되는 레퍼런스.
| 레퍼런스 | 역할 |
|-----------|------|
| `sketch-interactivity.md` | HTML 스케치를 인터랙티브하고 생생하게 만드는 규칙. |
| `sketch-theme-system.md` | 스케치 간 일관성을 위한 공유 CSS 테마 변수 시스템. |
| `sketch-tooling.md` | 모든 스케치에 포함된 플로팅 툴바 유틸리티. |
| `sketch-variant-patterns.md` | 다중 변형 HTML 패턴(탭, 나란히, 오버레이). |
### 씽킹 모델 레퍼런스
씽킹 클래스 모델(o3, o4-mini, Gemini 2.5 Pro)을 GSD 워크플로우에 통합하기 위한 레퍼런스.
| 레퍼런스 | 역할 |
|-----------|------|
| `thinking-models-debug.md` | 디버그 워크플로우를 위한 씽킹 모델 패턴. |
| `thinking-models-execution.md` | 실행 에이전트를 위한 씽킹 모델 패턴. |
| `thinking-models-planning.md` | 계획 에이전트를 위한 씽킹 모델 패턴. |
| `thinking-models-research.md` | 조사 에이전트를 위한 씽킹 모델 패턴. |
| `thinking-models-verification.md` | 검증 에이전트를 위한 씽킹 모델 패턴. |
### 모듈식 플래너 분해
`gsd-planner` 에이전트는 런타임 문자 제한에 맞추기 위해 코어 에이전트와 레퍼런스 모듈로 분해됩니다.
| 레퍼런스 | 역할 |
|-----------|------|
| `planner-antipatterns.md` | 플래너 안티패턴 및 구체성 예시. |
| `planner-chunked.md` | Windows stdio 멈춤 완화를 위한 청크 모드 반환 형식(`## OUTLINE COMPLETE`, `## PLAN COMPLETE`). |
| `planner-gap-closure.md` | 공백 채움 모드 동작(VERIFICATION.md 읽기, 타겟 재계획). |
| `planner-reviews.md` | 교차 AI 리뷰 통합(`/gsd-review`에서 REVIEWS.md 읽기). |
| `planner-revision.md` | 반복적 정제를 위한 계획 수정 패턴. |
| `planner-source-audit.md` | 플래너 소스 감사 및 권한 제한 규칙. |
| `planner-mvp-mode.md` | MVP 모드를 위한 수직 슬라이스 계획 규칙. |
| `planner-human-verify-mode.md` | `workflow.human_verify_mode = end-of-phase`에 대한 규칙: `checkpoint:human-verify` 태스크 방출 억제 및 `<verify><human-check>`를 통한 지연 항목 라우팅. |
| `planner-graphify-auto-update.md` | `load_graph_context`가 기존 부실 주석과 함께 `.last-build-status.json` 자동 업데이트 상태(실행 중 / 실패 / 부실 HEAD)를 표면화하는 방법. `graphify.auto_update`를 통해 옵트인 (#3347). |
| `planner-interface-context.md` | executor를 위한 인터페이스 컨텍스트 규칙 — 기존 코드에서 핵심 인터페이스/타입/익스포트 추출 방법과 다운스트림 계획이 사용할 새 인터페이스 문서화. |
| `skeleton-template.md` | 새 프로젝트 Walking Skeleton(Phase 1 + `--mvp`)을 위해 방출되는 SKELETON.md 템플릿. |
| `user-story-template.md` | MVP 계획을 위한 사용자 스토리 형식 — "As a / I want to / So that" 구조화된 필드. |
| `spidr-splitting.md` | MVP 모드에서 큰 사용자 스토리 처리를 위한 SPIDR 분할 분해 규칙. |
> **하위 디렉터리:** `get-shit-done/references/few-shot-examples/`에는 특정 에이전트에서 참조되는 추가 퓨샷 예시(`plan-checker.md`, `verifier.md`)가 포함되어 있습니다. 이들은 62개 최상위 레퍼런스 수에 포함되지 않습니다.
---
## CLI 모듈 (81개 출시)
전체 목록: `get-shit-done/bin/lib/*.cjs`.
| 모듈 | 책임 |
|--------|----------------|
| `active-workstream-store.cjs` | 워크스트림 소스 우선순위 및 선택(CLI `--ws` > `GSD_WORKSTREAM` 환경 변수 > 저장된 포인터); 이름 검증 및 환경 전파 |
| `adr-parser.cjs` | plan-phase 수집 익스프레스 경로를 위한 ADR 결정 파서; 섹션 동의어 정규화, 상태/결정/범위 펜스 파싱, 상태 거부 게이트 적용 |
| `agent-command-router.cjs` | `gsd-tools agent`를 위한 얇은 CJS 하위 명령어 라우터 어댑터 |
| `artifacts.cjs` | 표준 아티팩트 레지스트리 — 알려진 `.planning/` 루트 파일 이름; `gsd-health` W019 린트에 사용 |
| `audit.cjs` | 감사 디스패치, 열린 감사 세션, 감사 스토리지 헬퍼 |
| `check-command-router.cjs` | `gsd-tools check`를 위한 얇은 CJS 하위 명령어 라우터 어댑터 |
| `cjs-command-router-adapter.cjs` | 매니페스트 기반 CJS 명령어 패밀리 라우터를 위한 공유 호환성 어댑터 |
| `clock.cjs` | 결정론적 잠금 테스트를 위한 주입 가능한 클록 심(now/sleep) |
| `clusters.cjs` | 런타임 표면 모듈을 위한 스킬 클러스터 정의(ADR-0011 Phase 2) |
| `code-review-flags.cjs` | `/gsd:code-review`를 위한 타입 플래그 파서; `parseCodeReviewFlags(argv)` (→ `{ fix, all, auto, depth, files }`) 및 `resolveCodeReviewWorkflow(flags)` (→ `'code-review.md' \| 'code-review-fix.md'`) 내보내기; `--fix`/`--all`/`--auto` 라우팅을 위한 표준 디스패치 심 |
| `command-aliases.cjs` | 매니페스트 기반 패밀리 라우터를 위한 별칭/하위 명령어 메타데이터 |
| `command-arg-projection.cjs` | 명령어 패밀리 라우터 전반에 공유되는 타입 플래그 및 위치 인수 프로젝션 헬퍼 |
| `command-routing-hub.cjs` | 모든 명령어 패밀리 라우터를 위한 모드 결정(SDK vs CJS), 오류 분류, 예외 없음 계약을 집중화하는 순수 결과 디스패치 허브(#3788) |
| `commands.cjs` | 기타 CLI 명령어(슬러그, 타임스탬프, todo, 스캐폴딩, 통계) |
| `config-schema.cjs` | `VALID_CONFIG_KEYS` 및 동적 키 패턴의 단일 진실 소스; 유효성 검사기와 config-schema-docs 패리티 테스트 모두에서 가져옴 |
| `config.cjs` | `config.json` 읽기/쓰기, 섹션 초기화; `config-schema.cjs`에서 유효성 검사기 가져옴 |
| `config-types.cjs` | `model_policy` 설정 블록을 위한 TypeScript 타입 정의 — `ModelPolicyConfig`, `TierEntry`, `RuntimeTiers`; 게시 시 `src/config-types.cts`에서 컴파일됨(ADR-457) |
| `configuration.cjs` | 설정 모듈 — 표준 설정 로딩, 레거시 키 정규화, 기본값 병합, 명시적 온디스크 마이그레이션; SDK 및 CJS 소비자 모두를 위한 진실 소스 |
| `context-utilization.cjs` | `gsd-health --context`를 위한 순수 분류기 — (tokensUsed, contextWindow)를 60%/70% 파단점 임계값에 대한 `{ percent, state }` 트리아지 결과로 변환(#2792) |
| `core.cjs` | 오류 처리, 출력 포매팅, 공유 유틸리티, 런타임 폴백; 계획 워크스페이스 헬퍼를 위한 호환성 재내보내기 |
| `decisions.cjs` | CONTEXT.md `<decisions>` 블록 파싱; 숫자형(D-42) 및 영숫자형(D-INFRA-01) ID 허용; `{id, text, category, tags, trackable}` 반환 |
| `docs.cjs` | 문서 업데이트 워크플로우 초기화, 마크다운 스캔, 모노레포 감지 |
| `drift.cjs` | 실행 후 코드베이스 구조 드리프트 감지기(#2003): 파일 변경을 new-dir/barrel/migration/route 카테고리로 분류하고 `last_mapped_commit` 프론트매터를 왕복 처리 |
| `fallow-runner.cjs` | `/gsd-code-review`를 위한 Fallow 감사 어댑터: 바이너리 해석(`PATH` 이후 `node_modules/.bin`), 실행 가능한 누락 바이너리 오류, 구조적 결과 정규화 |
| `frontmatter.cjs` | YAML 프론트매터 CRUD 작업 |
| `gap-checker.cjs` | 계획 후 공백 분석(#2493): REQUIREMENTS.md + CONTEXT.md 결정 대 PLAN.md 커버리지 보고서(`gsd-tools gap-analysis`) |
| `graphify.cjs` | `/gsd-graphify`를 위한 지식 그래프 빌드/쿼리/상태/비교 |
| `gsd2-import.cjs` | `/gsd-import --from-gsd2`를 위한 외부 계획 수집 |
| `init-command-router.cjs` | `gsd-tools init`을 위한 얇은 CJS 하위 명령어 라우터 어댑터 |
| `init.cjs` | 각 워크플로우 유형을 위한 복합 컨텍스트 로딩 |
| `install-profiles.cjs` | `--minimal` 설치를 위한 설치 프로필 허용 목록 + 스킬 스테이징(#2762); 런타임 설정 디렉터리에 어떤 `gsd-*` 스킬/에이전트가 배치되는지에 대한 단일 진실 소스 |
| `installer-migration-authoring.cjs` | 레코드 메타데이터, 명시적 범위, 소유권 증거, 런타임 계약 인용을 위한 설치 마이그레이션 저작 가드레일 |
| `installer-migration-report.cjs` | 설치/업데이트 통합을 위한 설치 마이그레이션 보고서 프로젝션 및 차단 액션 가드 |
| `installer-migrations.cjs` | 설치 마이그레이션 계획, 아티팩트 분류, 설치 상태 지속성, 저널 적용, 롤백 헬퍼 |
| `intel.cjs` | `/gsd-map-codebase --query` 및 `gsd-intel-updater`를 지원하는 코드베이스 인텔 스토어 |
| `learnings.cjs` | `/gsd-extract-learnings`를 위한 단계 간 학습 추출 |
| `milestone.cjs` | 마일스톤 아카이브, 요구사항 마킹 |
| `model-catalog.cjs` | 공유 모델 카탈로그 JSON에 대한 CJS 어댑터; 모든 CLI 소비자를 위한 표준 런타임 티어 기본값, 에이전트 프로필 맵, 별칭 맵, 라우팅 메타데이터 내보내기 |
| `model-profiles.cjs` | `model-catalog.cjs`에서 파생된 하위 호환 프로필 헬퍼; 더 이상 자체 모델 테이블을 소유하지 않음 |
| `package-identity.cjs` | GSD의 게시된 패키지 좌표(npm 이름, bin 이름, 저장소 슬러그, 체인지로그 URL, 수동 설치 명령어)를 위한 생성된 단일 소스, package.json에서 파생; 업데이트 워커, `check-latest-version`, 설치 프로그램에서 읽음(#498) |
| `phase-command-router.cjs` | `gsd-tools phase`를 위한 얇은 CJS 하위 명령어 라우터 어댑터 |
| `phase-lifecycle.cjs` | 단계 라이프사이클 SDK 핸들러에서 추출된 순수 계산 단계 라이프사이클 헬퍼 |
| `phase.cjs` | 단계 디렉터리 작업, 소수점 번호 체계, 계획 인덱싱 |
| `phases-command-router.cjs` | `gsd-tools phases`를 위한 얇은 CJS 하위 명령어 라우터 어댑터 |
| `plan-scan.cjs` | 플랫 및 중첩 레이아웃에서 계획 및 요약 파일을 감지하는 표준 단계 계획 스캐너(k014) |
| `planning-workspace.cjs` | 계획 경로/워크스트림 심(`planningDir`, `planningPaths`, 활성 워크스트림 라우팅, `.planning/.lock` 오케스트레이션) |
| `project-root.cjs` | 4가지 휴리스틱(자체 `.planning/` 가드, `sub_repos` 설정, `multiRepo` 플래그, `.git` 휴리스틱)을 사용하여 시작 디렉터리에서 프로젝트 루트 해석 |
| `profile-output.cjs` | 프로필 렌더링, USER-PROFILE.md 및 dev-preferences.md 생성 |
| `profile-pipeline.cjs` | 사용자 행동 프로파일링 데이터 파이프라인, 세션 파일 스캔 |
| `prompt-budget.cjs` | 리뷰 프롬프트를 위한 순수 토큰 예산 계산 — 토큰 추정, 결정론적 트림 우선순위 적용(헤드 수축 PROJECT.md, 비례 계획 잘라내기, 컨텍스트/조사/요구사항 삭제, 하드 실패 가드), `review.max_prompt_tokens`를 위한 구조화된 메타데이터 반환(#3081) |
| `review-reviewer-selection.cjs` | `/gsd-review` 기본 리뷰어 정책 및 우선순위를 위한 리뷰어 선택/정규화 헬퍼 |
| `roadmap-command-router.cjs` | `gsd-tools roadmap`을 위한 얇은 CJS 하위 명령어 라우터 어댑터 |
| `roadmap-upgrade.cjs` | 레거시 `Phase N` 항목을 마일스톤 접두사 `Phase M-NN` 관례로 변환하는 마이그레이션 도구; 드라이런 기본값 및 원자적 롤백이 있는 `computeMigrationPlan` + `applyMigration` |
| `roadmap.cjs` | ROADMAP.md 파싱, 단계 추출, 계획 진행도 |
| `runtime-artifact-layout.cjs` | 런타임 아티팩트 레이아웃 모듈 — 지원되는 각 런타임의 아티팩트 디렉터리 형태(명령어, 에이전트, 스킬) 해석; 런타임별 아티팩트 배치를 위한 단일 진실 소스(#3663) |
| `runtime-name-policy.cjs` | 런타임 이름 정규화 정책 — 경로 구성 및 표시에 사용되는 런타임 식별자를 위한 표준 토큰 위생 처리 |
| `runtime-homes.cjs` | 표준 런타임 → 전역 설정/스킬 디렉터리 매핑; Hermes 중첩 레이아웃 및 Cline 규칙 기반 제외를 포함한 15개 런타임에 대한 일급 지원(#3126) |
| `runtime-slash.cjs` | 런타임 인식 슬래시 명령어 포매터 — 사용자 대면 출력 및 영속 아티팩트에서 `/gsd-<cmd>`(스킬 기반 런타임) 및 `$gsd-<cmd>`(codex) 내보내기를 위한 단일 진실 소스(#3584) |
| `schema-detect.cjs` | ORM 패턴 스키마 드리프트 감지(Prisma, Drizzle, Supabase, TypeORM, Payload); `detectSchemaFiles`, `detectSchemaOrm`, `checkSchemaDrift`, `SCHEMA_PATTERNS`, `ORM_INFO` 내보내기 |
| `secrets.cjs` | 통합 키를 위한 시크릿 설정 마스킹 관례(`****<last-4>`); `SECRET_CONFIG_KEYS`, `isSecretKey`, `maskSecret`, `maskIfSecret` 내보내기 |
| `semver-compare.cjs` | 업데이트 확인 훅, 상태라인 개발 설치 감지, 체인지셋 추출 범위 로직에서 사용되는 공유 semver 비교 정책 헬퍼(`compareSemverCore`, 안정적인 트리플릿 검증, 정규화된 튜플 파싱)(#10) |
| `security.cjs` | 경로 순회 방지, 프롬프트 주입 감지, 안전한 JSON/셸 헬퍼 |
| `shell-command-projection.cjs` | 관리형 훅 직렬화를 위한 런타임 인식 셸 명령어 프로젝션: 런타임/플랫폼별 PowerShell 호출 연산자 사용 결정 및 Windows 스크립트 경로 토큰 정규화 |
| `state-command-router.cjs` | `gsd-tools state`를 위한 얇은 CJS 하위 명령어 라우터 어댑터 |
| `state.cjs` | STATE.md 파싱, 업데이트, 진행, 메트릭 |
| `state-document.cjs` | 순수 STATE.md 필드 추출, 교체, 상태 정규화, 진행도 계산 변환 |
| `surface.cjs` | 런타임 표면 모듈 — 설치 시 프로필 마커와 독립적으로 런타임 활성화/비활성화 표면 상태 관리(ADR-0011 Phase 2) |
| `task-command-router.cjs` | `gsd-tools task`를 위한 얇은 CJS 하위 명령어 라우터 어댑터 |
| `template.cjs` | 변수 치환을 통한 템플릿 선택 및 채우기 |
| `uat.cjs` | UAT 파일 파싱, 검증 부채 추적, audit-uat 지원 |
| `ui-safety-gate.cjs` | 셸 없는 단어 경계 UI 토큰 감지기(#3706, #3718); stdin에서 단계 섹션 텍스트를 읽어 0(UI 발견) 또는 1(UI 없음) 종료; GSD 설치 프로그램이 `$RUNTIME_DIR`에 배포하도록 `get-shit-done/bin/lib/`에도 배포 |
| `update-context.cjs` | `/gsd:update`를 위한 순수 설치 컨텍스트 해석기 — update.md bash에서 포팅된 런타임/범위/설정 디렉터리/버전 감지(LOCAL/GLOBAL/UNKNOWN); `gsd-tools update-context` 지원(#498) |
| `validate-command-router.cjs` | `gsd-tools validate`를 위한 얇은 CJS 하위 명령어 라우터 어댑터 |
| `validate.cjs` | 순수 단계 변형 정규화 헬퍼(`phaseVariants`, `buildRoadmapPhaseVariants`, `buildNotStartedPhaseVariants`), W006/W007 확인을 위해 `verify.cjs`에서 사용; I/O 없음, 비동기 없음 |
| `verify-command-router.cjs` | `gsd-tools verify`를 위한 얇은 CJS 하위 명령어 라우터 어댑터 |
| `verify.cjs` | 계획 구조, 단계 완전성, 레퍼런스, 커밋 검증 |
| `workstream-inventory-builder.cjs` | 순수 워크스트림 인벤토리 프로젝션 빌더 |
| `workstream-inventory.cjs` | 공유 워크스트림 인벤토리 프로젝션: 상태 필드, 단계/계획/요약 수, 로드맵 단계 수, 활성 마커 — `workstream-inventory-builder.cjs`에 순수 프로젝션을 위임하는 얇은 오케스트레이터 |
| `workstream-name-policy.cjs` | 표준 워크스트림 이름 검증(`isValidActiveWorkstreamName`, `hasInvalidPathSegment`, `validateWorkstreamName`) 및 슬러그 정규화(`toWorkstreamSlug`) |
| `workstream.cjs` | 워크스트림 CRUD, 마이그레이션, 세션 범위 활성 포인터 |
| `worktree-safety.cjs` | 워크트리 루트 해석 및 비파괴적 가지치기 정책 결정; W017 상태 확인 로직 소유 |
[`docs/CLI-TOOLS.md`](CLI-TOOLS.md)는 이러한 모듈의 하위 집합을 설명할 수 있습니다. 파일시스템과 불일치할 경우 이 테이블과 디렉터리 목록이 권위 있는 출처입니다.
---
## 훅 (14개 출시)
전체 목록: `hooks/`.
| 훅 | 이벤트 | 목적 |
|------|-------|---------|
| `gsd-statusline.js` | `statusLine` | 모델, 태스크, 디렉터리, 컨텍스트 사용량 표시 |
| `gsd-context-monitor.js` | `PostToolUse` / `AfterTool` | 35%/25% 남은 시점에 에이전트 대면 컨텍스트 경고 주입 |
| `gsd-check-update.js` | `SessionStart` | 새 GSD 버전 백그라운드 확인 |
| `gsd-check-update-worker.js` | (worker) | check-update를 위한 백그라운드 워커 헬퍼 |
| `gsd-update-banner.js` | `SessionStart` | GSD 상태라인을 사용하지 않을 때 업데이트 가용성을 표면화하는 옵트인 배너(PR #2795) |
| `gsd-prompt-guard.js` | `PreToolUse` | `.planning/` 쓰기에서 프롬프트 주입 패턴 스캔 (어드바이저리) |
| `gsd-workflow-guard.js` | `PreToolUse` | GSD 워크플로우 컨텍스트 외부의 파일 편집 감지 (어드바이저리, 옵트인) |
| `gsd-read-guard.js` | `PreToolUse` | 읽지 않은 파일에 대한 Edit/Write를 방지하는 어드바이저리 가드 |
| `gsd-read-injection-scanner.js` | `PostToolUse` | 도구 Read 결과에서 프롬프트 주입 패턴 스캔 (v1.36+, PR #2201) |
| `gsd-worktree-path-guard.js` | `PreToolUse` | 워크트리 루트 외부의 절대 경로로 Edit/Write/MultiEdit를 하드 차단 (PR #579, #260) |
| `gsd-session-state.sh` | `PostToolUse` | 셸 기반 런타임을 위한 세션 상태 추적 |
| `gsd-validate-commit.sh` | `PostToolUse` | 컨벤셔널 커밋 적용을 위한 커밋 검증 |
| `gsd-phase-boundary.sh` | `PostToolUse` | 워크플로우 전환을 위한 단계 경계 감지 |
| `gsd-graphify-update.sh` | `PostToolUse` | 메인 HEAD 진행 후 지식 그래프 자동 재빌드 (옵트인, 기본 비활성화 — #3347) |
---
## 유지 관리
- 새 명령어, 에이전트, 워크플로우, 레퍼런스, CLI 모듈, 또는 훅이 출시될 때, 릴리스가 잘리기 전에 해당 섹션을 여기에 업데이트하세요.
- `tests/` 아래의 드리프트 가드 테스트(위의 "이 파일 사용 방법" 참조)는 출시된 모든 파일이 이 인벤토리에 열거되어 있음을 어설트합니다. 일치하는 행이 없는 새 파일은 CI를 실패시킵니다.
- 파일시스템이 `docs/ARCHITECTURE.md` 수량 또는 엄선된 하위 집합 문서(예: `docs/AGENTS.md`의 주요 목록)와 다를 경우, 이 파일이 진실의 원천입니다.
## 관련 문서
- [명령어](COMMANDS.md) — 사용자 대면 명령어 참조
- [아키텍처](ARCHITECTURE.md) — 표면이 어떻게 맞물리는지
- [문서 색인](README.md)

84
docs/ko-KR/README.md
View File

@@ -1,29 +1,69 @@
# GSD Core 문서
GSD Core (Git. Ship. Done.) 문서입니다. GSD Core는 AI 코딩 에이전트를 위한 메타 프롬프팅, 컨텍스트 엔지니어링, 스펙 기반 개발 시스템입니다.
문서는 네 가지 유형으로 구성됩니다. **튜토리얼**은 직접 해보며 배우고, **how-to 가이드**는 특정 작업을 해결하며, **레퍼런스**는 권위 있는 사실을 제시하고, **설명**은 개념과 설계 결정을 탐구합니다.
언어 버전: [English](README.md) · [Português (pt-BR)](pt-BR/README.md) · [日本語](ja-JP/README.md) · [简体中文](zh-CN/README.md) · [한국어](ko-KR/README.md)
언어 버전: [English](../README.md) · [Português (pt-BR)](../pt-BR/README.md) · [日本語](../ja-JP/README.md) · [简体中文](../zh-CN/README.md) · **한국어**
## 문서 목차
---
| 문서 | 대상 독자 | 설명 |
|------|-----------|------|
| [Architecture](ARCHITECTURE.md) | 기여자, 고급 사용자 | 시스템 아키텍처, 에이전트 모델, 데이터 흐름, 내부 설계 |
| [Feature Reference](FEATURES.md) | 전체 사용자 | 요구사항이 포함된 전체 기능 및 함수 문서 |
| [Command Reference](COMMANDS.md) | 전체 사용자 | 모든 명령어의 구문, 플래그, 옵션 및 예제 |
| [Configuration Reference](CONFIGURATION.md) | 전체 사용자 | 전체 설정 스키마, 워크플로우 토글, 모델 프로필, git 브랜칭 |
| [CLI Tools Reference](CLI-TOOLS.md) | 기여자, 에이전트 작성자 | CJS `gsd-tools.cjs` + `gsd-tools.cjs query` 안내 |
| [Agent Reference](AGENTS.md) | 기여자, 고급 사용자 | 18개 전문 에이전트의 역할, 도구, 스폰 패턴 |
| [User Guide](USER-GUIDE.md) | 전체 사용자 | 워크플로우 안내, 문제 해결, 복구 방법 |
| [Context Monitor](context-monitor.md) | 전체 사용자 | 컨텍스트 윈도우 모니터링 훅 아키텍처 |
| [Discuss Mode](workflow-discuss-mode.md) | 전체 사용자 | discuss 단계의 assumptions 모드와 interview 모드 |
## 튜토리얼
## 빠른 링크
- [첫 번째 프로젝트](tutorials/your-first-project.md) — 설치부터 첫 단계 출시까지, 확실한 한 가지 경로
- [기존 코드베이스 온보딩](tutorials/onboarding-an-existing-codebase.md) — 기존 저장소에 GSD Core 적용하기
- **v1.39의 새로운 기능:** `--minimal` 설치 프로파일(콜드 스타트 ≥94% 감소), `/gsd-phase --edit`, 머지 후 빌드 & 테스트 게이트, `review.models.<cli>` 런타임별 리뷰 모델, 워크스트림 설정 상속, 수동 카나리 릴리스 워크플로, 스킬 통합(86 → 59)
- **시작하기:** [README](../README.md) → 설치 → `/gsd-new-project`
- **전체 워크플로우 안내:** [User Guide](USER-GUIDE.md)
- **모든 명령어 한눈에 보기:** [Command Reference](COMMANDS.md)
- **GSD 설정하기:** [Configuration Reference](CONFIGURATION.md)
- **시스템 내부 동작 원리:** [Architecture](ARCHITECTURE.md)
- **기여 또는 확장:** [CLI Tools Reference](CLI-TOOLS.md) + [Agent Reference](AGENTS.md)
---
## How-to guides
- [런타임에 설치하기](how-to/install-on-your-runtime.md) — 지원하는 15개 런타임 각각의 설치 단계
- [단계 논의하기](how-to/discuss-a-phase.md) — 기획 시작 전 구현 결정 사항 정리
- [단계 기획하기](how-to/plan-a-phase.md) — 리서치 실행, 작업 분해, 플랜 품질 검증
- [단계 실행하기](how-to/execute-a-phase.md) — 새 컨텍스트 서브에이전트로 병렬 웨이브 실행
- [검증 및 출시](how-to/verify-and-ship.md) — 완료된 작업 검토, 오류 진단, PR 생성
- [단계 자율 실행하기](how-to/run-phases-autonomously.md) — 무인 단계 실행을 위한 자율 모드 사용
- [빠른 임시 작업 처리](how-to/handle-quick-and-fast-tasks.md) — 단계 루프 외 임시 작업에 `/gsd-quick`과 `/gsd-fast` 활용
- [모델 프로필 설정](how-to/configure-model-profiles.md) — 고품질, 균형, 예산 모델 티어 전환
- [크로스 AI 리뷰 설정](how-to/set-up-cross-ai-review.md) — 주 에이전트가 생성한 코드를 두 번째 AI가 검토하도록 설정
- [워크스트림으로 병렬 작업](how-to/work-in-parallel-with-workstreams.md) — 워크스트림을 사용해 독립적인 작업 라인 동시 실행
- [워크스페이스로 작업 격리](how-to/isolate-work-with-workspaces.md) — 워크스페이스로 실험적이거나 위험한 변경 사항 샌드박스 처리
- [실패한 실행 디버깅](how-to/debug-a-failed-execution.md) — 깨지거나 불완전한 단계 실행 진단 및 복구
- [스파이크와 스케치](how-to/spike-and-sketch.md) — 플랜 확정 전 탐색 작업에 `/gsd-spike`와 `/gsd-sketch` 활용
- [UI 단계 설계](how-to/design-a-ui-phase.md) — 프론트엔드 및 시각적 작업에 UI 단계 루프 활용
- [트래커 이슈로 GSD 구동](how-to/drive-gsd-from-a-tracker-issue.md) — GitHub, Linear, Jira 이슈에서 단계 시작
- [GSD 2에서 마이그레이션](how-to/migrate-from-gsd-2.md) — 기존 GSD 2 프로젝트를 GSD Core로 업그레이드
- [GSD 업데이트](how-to/update-gsd.md) — 설치 프로그램을 재실행해 최신 릴리스 적용
- [복구 및 문제 해결](how-to/recover-and-troubleshoot.md) — 일반적인 문제 해결, 컨텍스트 재구축, 제거
---
## 레퍼런스
- [명령어](COMMANDS.md) — 플래그와 예제가 포함된 모든 명령어
- [설정](CONFIGURATION.md) — 전체 설정 스키마, 모델 프로필, git 브랜칭 전략
- [CLI 도구](CLI-TOOLS.md) — 워크플로우와 에이전트를 위한 `gsd-tools.cjs` 프로그래밍 API
- [기능](FEATURES.md) — 전체 기능 색인
- [인벤토리](INVENTORY.md) — 설치된 스킬과 서피스 맵
- [STATE.md 스키마](reference/state-md.md) — `.planning/STATE.md` 필드별 레퍼런스
- [CONTEXT.md 스키마](reference/context-md.md) — `.planning/phases/<N>/CONTEXT.md` 필드별 레퍼런스
- [PLAN.md 스키마](reference/plan-md.md) — `.planning/phases/<N>/PLAN.md` 필드별 레퍼런스
- [기획 아티팩트](reference/planning-artifacts.md) — 모든 `.planning/` 파일과 역할
---
## 설명
- [컨텍스트 엔지니어링](explanation/context-engineering.md) — 컨텍스트 rot가 형성되는 방식과 GSD Core의 방지 방법
- [단계 루프](explanation/the-phase-loop.md) — 논의 → 기획 → 실행 → 검증 → 출시 사이클의 설계 근거
- [멀티 에이전트 오케스트레이션](explanation/multi-agent-orchestration.md) — 서브에이전트의 생성, 범위 지정, 조율 방식
- [보안 모델](explanation/security-model.md) — 신뢰 경계, 권한, 안전한 자동화
- [아키텍처](ARCHITECTURE.md) — 시스템 아키텍처, 에이전트 모델, 데이터 흐름
- [논의 모드](workflow-discuss-mode.md) — `/gsd-discuss-phase`의 가정 모드와 인터뷰 모드
- [컨텍스트 모니터링](context-monitor.md) — 컨텍스트 창 모니터링 훅 아키텍처
- [이슈 기반 오케스트레이션](issue-driven-orchestration.md) — 기존 프리미티브를 사용해 트래커 이슈로 GSD를 구동하는 레시피
---
## Related
- [루트 README](../README.md) — 랜딩 페이지, 빠른 시작, 문서 개요
- [변경 로그](../../CHANGELOG.md) — 릴리스 이력

1045
docs/ko-KR/USER-GUIDE.md
View File

File diff suppressed because it is too large Load Diff

89
docs/ko-KR/context-monitor.md
View File

@@ -1,32 +1,32 @@
# 컨텍스트 윈도우 모니터
에이전트의 컨텍스트 윈도우 사용량이 높을 때 경고를 주는 post-tool 훅입니다 (Claude Code의 경우 `PostToolUse`, Gemini CLI의 경우 `AfterTool`).
에이전트의 컨텍스트 윈도우 사용량이 높을 때 경고를 주는 post-tool 훅 (Claude Code의 경우 `PostToolUse`, Gemini CLI의 경우 `AfterTool`).
## 문제
상태바(statusline)는 **사용자**에게 컨텍스트 사용량을 보여주지만 **에이전트** 자체는 컨텍스트 한계를 인식하지 못합니다. 컨텍스트가 부족해지면 에이전트는 한계에 부딪힐 때까지 작업을 계속 진행하며 상태가 저장되지 않은 채 작업 도중에 멈출 수 있습니다.
상태바(statusline)는 **사용자**에게 컨텍스트 사용량을 보여주지만 **에이전트** 자체는 컨텍스트 한계를 인식하지 못한다. 컨텍스트가 부족해지면 에이전트는 한계에 부딪힐 때까지 작업을 계속 진행한다 — 상태가 저장되지 않은 채 작업 도중에 멈출 수 있다.
## 동작 방식
1. statusline 훅이 컨텍스트 메트릭을 `/tmp/claude-ctx-{session_id}.json`에 기록합니다.
2. 각 도구 사용 후 context monitor가 해당 메트릭을 읽습니다.
3. 남은 컨텍스트가 임계값 아래로 떨어지면 `additionalContext`로 경고를 주입합니다.
4. 에이전트는 대화에서 경고를 받고 그에 맞게 대응할 수 있습니다.
1. statusline 훅이 컨텍스트 메트릭을 `/tmp/claude-ctx-{session_id}.json`에 기록한다
2. 각 도구 사용 후 context monitor가 해당 메트릭을 읽는다
3. 남은 컨텍스트가 임계값 아래로 떨어지면 `additionalContext`로 경고를 주입한다
4. 에이전트는 대화에서 경고를 받고 그에 맞게 대응할 수 있다
## 임계값
| 레벨 | 남은 비율 | 에이전트 동작 |
|------|-----------|---------------|
|-------|-----------|----------------|
| Normal | > 35% | 경고 없음 |
| WARNING | <= 35% | 현재 작업 마무리, 새로운 복잡한 작업 시작 금지 |
| CRITICAL | <= 25% | 즉시 중단 후 상태 저장 (`/gsd-pause-work`) |
## Debounce
에이전트에게 반복적인 경고가 쌓이는 것을 방지하기 위한 동작입니다.
- 첫 번째 경고는 항상 즉시 발생합니다.
- 이후 경고는 5번의 도구 사용 간격이 필요합니다.
- 심각도 상승 (WARNING → CRITICAL) 시에는 debounce를 우회합니다.
에이전트에게 반복적인 경고가 쌓이는 것을 방지하기 위해:
- 첫 번째 경고는 항상 즉시 발생한다
- 이후 경고는 5번의 도구 사용 간격이 필요하다
- 심각도 상승 (WARNING → CRITICAL) 시에는 debounce를 우회한다
## 아키텍처
@@ -43,7 +43,7 @@ Context Monitor (gsd-context-monitor.js, PostToolUse/AfterTool)
additionalContext -> 에이전트가 경고를 받음
```
브리지 파일은 단순한 JSON 객체입니다.
브리지 파일은 단순한 JSON 객체이다:
```json
{
@@ -56,60 +56,25 @@ additionalContext -> 에이전트가 경고를 받음
## GSD와의 통합
GSD의 `/gsd-pause-work` 명령어는 실행 상태를 저장합니다. WARNING 메시지는 해당 명령어 사용을 권장하며 CRITICAL 메시지는 즉각적인 상태 저장을 지시합니다.
GSD의 `/gsd-pause-work` 명령어는 실행 상태를 저장한다. WARNING 메시지는 해당 명령어 사용을 권장하며 CRITICAL 메시지는 즉각적인 상태 저장을 지시한다.
## 설정
두 훅 모두 `npx @opengsd/gsd-core` 설치 중에 자동으로 등록됩니다.
두 훅 모두 `npx @opengsd/gsd-core` 설치 중에 자동으로 등록된다 — 정상적인 상황에서는 수동 단계가 필요하지 않다. 훅 설정 상세, 임계값 재정의, 수동 등록 예시는 [설정](CONFIGURATION.md)을 참조하라.
- **Statusline** (브리지 파일 기록): settings.json에 `statusLine`으로 등록
- **Context Monitor** (브리지 파일 읽기): settings.json에 `PostToolUse` 훅으로 등록 (Gemini의 경우 `AfterTool`)
`~/.claude/settings.json`에 수동으로 등록하는 방법 (Claude Code):
```json
{
"statusLine": {
"type": "command",
"command": "node ~/.claude/hooks/gsd-statusline.js"
},
"hooks": {
"PostToolUse": [
{
"hooks": [
{
"type": "command",
"command": "node ~/.claude/hooks/gsd-context-monitor.js"
}
]
}
]
}
}
```
Gemini CLI (`~/.gemini/settings.json`)의 경우 `PostToolUse` 대신 `AfterTool`을 사용합니다.
```json
{
"hooks": {
"AfterTool": [
{
"hooks": [
{
"type": "command",
"command": "node ~/.gemini/hooks/gsd-context-monitor.js"
}
]
}
]
}
}
```
간략한 참고: statusline 훅은 `settings.json`에 `statusLine`으로 등록된다; context monitor(`gsd-context-monitor.js`)는 `PostToolUse` 훅으로 등록된다(Gemini CLI의 경우 `AfterTool`). 두 항목 모두 설치 프로그램을 실행한 절대 Node 실행 경로를 사용한다. Windows PowerShell에서는 인용된 실행 경로 앞에 `&`를 붙인다.
## 안전성
- 훅은 모든 동작을 try/catch로 감싸며 오류 발생 시 조용히 종료합니다.
- 도구 실행을 절대 차단하지 않습니다. 모니터에 문제가 생겨도 에이전트 워크플로우가 중단되지 않습니다.
- 60초 이상 된 오래된 메트릭은 무시됩니다.
- 누락된 브리지 파일은 정상적으로 처리됩니다 (서브에이전트, 새 세션 등의 경우).
- 훅은 모든 동작을 try/catch로 감싸며 오류 발생 시 조용히 종료한다
- 도구 실행을 절대 차단하지 않는다 — 모니터에 문제가 생겨도 에이전트 워크플로우가 중단되지 않아야 한다
- 60초 이상 된 오래된 메트릭은 무시된다
- 누락된 브리지 파일은 정상적으로 처리된다 (서브에이전트, 새 세션 등의 경우)
---
## Related
- [아키텍처](ARCHITECTURE.md)
- [설정](CONFIGURATION.md)
- [문서 인덱스](README.md)

90
docs/ko-KR/explanation/context-engineering.md Normal file
View File

@@ -0,0 +1,90 @@
# 컨텍스트 엔지니어링
> GSD Core가 존재하는 이유와 해결하고자 하는 문제.
---
## 문제: 컨텍스트 부패
모든 AI 코딩 세션은 새롭게 시작된다. 모델은 질문을 읽고, 추론하고, 답변을 돌려준다. 그러나 하나의 세션이 단 한 번의 교환으로 끝나는 경우는 드물다. 추가 질문을 던지고, 오류 메시지를 붙여넣고, 코드를 반복적으로 개선하며, 모델이 엉뚱한 방향으로 흘러갈 때 방향을 바로잡는다. 각 대화 차례마다 토큰이 컨텍스트 윈도우에 쌓인다 — 모델이 한 번에 "볼 수" 있는 유한한 텍스트 버퍼.
이 윈도우가 채워지면 미묘한 일이 벌어진다. 모델은 요란하게 실패하지 않는다. 계속해서 답변을 생성한다. 하지만 답변의 품질은 서서히 저하된다. 초반에 주어진 지시 사항이 모델이 집중할 수 있는 범위의 가장자리로 밀려난다. 처음 몇 번의 교환에서 다뤘던 뉘앙스들 — 제시했던 제약 조건, 합의한 아키텍처, 언급했던 엣지 케이스들 — 이 이후에 쌓인 모든 내용과 주의를 경쟁하게 된다. 연구자들은 이를 **컨텍스트 부패(context rot)**라고 부른다.
컨텍스트 부패는 여러 형태로 나타난다.
- 모델이 이전에 인정했던 결정들을 모순되게 다루기 시작한다.
- 코드 스타일이 세션 초반에 확립한 컨벤션에서 벗어난다.
- 계획이 명확하게 명시되었지만 이제 깊이 묻혀버린 요구 사항들을 무시하기 시작한다.
- 모델이 20개의 메시지 전에는 정확히 알고 있던 파일 이름이나 함수 시그니처를 환각으로 만들어낸다.
이것은 모델 버그가 아니다. 긴 시퀀스에서 트랜스포머 어텐션이 작동하는 방식의 근본적인 특성이다. 모델은 "잊어버리는" 것이 아니다 — 인간적 의미에서의 "기억"은 애초에 없었다. 유한한 윈도우 안에서 관련성에 가중치를 부여하고 있으며, 누적된 노이즈로 윈도우가 채워질수록 신호 대 잡음비가 저하된다.
단순한 대응책은 `/clear`로 세션을 초기화하는 것이다. 그러나 그러면 연속성을 잃는다. 컨텍스트를 다시 설명하고, 관련 파일을 다시 붙여넣고, 제약 조건을 다시 명시해야 한다. 세션이 사실상 제로부터 다시 시작된다.
---
## GSD Core의 답: 신선한 컨텍스트 서브에이전트
GSD Core의 핵심적인 통찰은 코딩 세션에서 이루어지는 작업의 *대부분*이 메인 컨텍스트에서 이루어질 필요가 없다는 것이다. 리서치, 계획 수립, 코드 작성, 검증은 각각 독립적이고 범위가 한정된 작업들이다. 각각을 깔끔하고 신중하게 범위가 지정된 컨텍스트 윈도우로 시작하는 전문화된 서브에이전트에게 넘기고 — 결과를 효율적으로 유지되는 얇은 오케스트레이터에게 보고할 수 있다.
이것은 컨텍스트 부패를 위한 임시방편이 아니다. 구조적인 해결책이다.
오케스트레이터 — 메인 세션 — 는 소스 파일을 직접 다루지 않는다. 에이전트를 생성하고, 결과를 수집하며, 공유 상태를 업데이트하고, 다음 단계로 라우팅한다. 오케스트레이터가 스스로 하는 작업이 매우 적기 때문에 컨텍스트 윈도우가 느리고 예측 가능하게 증가한다. 무거운 작업은 각각 신선하게 시작하고, 자신의 작업에 필요한 정확한 컨텍스트만 받고, 완료 시 종료하는 에이전트에서 수행된다.
실제로 어떤 의미인지 생각해보자. `/gsd-plan-phase`를 실행하면 오케스트레이터는:
1. 압축된 JSON 컨텍스트 페이로드(프로젝트 요약, 단계 목표, 관련 설정)를 로드한다.
2. 200k 토큰의 깨끗한 윈도우로 리서처 에이전트를 생성한다.
3. 리서치 출력물과 단계 요구 사항을 가진 플래너 에이전트를 생성한다.
4. 실행 전에 계획을 검증하는 계획 검사기 에이전트를 생성한다.
각 에이전트는 세션의 누적된 이력으로 부담받지 않고, 최대 능력으로 작동한다. 플래너가 `PLAN.md` 파일들을 `.planning/phases/`에 작성할 때, 그 출력물은 내구성 있는 결과물이 된다 — 공유 컨텍스트 윈도우 속에서 깨지기 쉬운 기억이 아니라.
---
## 명세 주도 개발과 메타 프롬프팅
컨텍스트 엔지니어링만으로는 충분하지 않다. 에이전트가 신선하게 시작하더라도 모호한 지시 사항을 받으면 모호한 결과물을 생성한다. GSD Core는 신선한 컨텍스트 서브에이전트와 두 가지 보완적인 원칙을 함께 사용한다.
**명세 주도 개발**은 모든 단계가 실행 전에 구조화된 결과물을 생성한다는 것을 의미한다. `CONTEXT.md`는 논의 단계의 구현 결정 사항들을 캡처한다. `RESEARCH.md`는 리서처가 발견한 내용을 기록한다. `PLAN.md`는 명시적인 수락 기준을 가진 개별적인 의존성 순서의 작업들로 작업을 분해한다. 실행 에이전트가 파일에 손을 대는 시점에는 긴 대화의 재해석이 아닌 정확한 명세를 가지고 있다.
**메타 프롬프팅**은 에이전트 정의 자체가 애드혹 지시 사항이 아닌 신중하게 설계된 프롬프트라는 것을 의미한다. `get-shit-done/workflows/`와 `agents/`의 파일들은 작업의 범위를 지정하는 방법, 무엇을 검증해야 하는지, 언제 사람에게 체크포인트를 요청해야 하는지에 대한 소중한 지식을 담고 있다. 사용자는 매 세션마다 이 지식을 다시 설명할 필요가 없다; 그것은 시스템 자체의 프롬프트에 이미 내장되어 있다.
이 조합은 의도적이다. 신선한 컨텍스트는 각 에이전트가 명확하게 추론하도록 보장한다. 명세 주도 결과물은 각 에이전트가 *올바른* 것에 대해 추론하도록 보장한다. 메타 프롬프팅은 각 에이전트가 *어떻게* 잘 추론해야 하는지 알도록 보장한다.
---
## `.planning/`의 역할
컨텍스트 엔지니어링은 지식이 컨텍스트 리셋을 통해 살아남아야 한다는 것을 요구한다. GSD Core는 이를 위해 파일 시스템을 사용한다. 모든 의미 있는 출력물은 사람이 읽을 수 있는 마크다운 또는 JSON으로 `.planning/`에 작성된다. 이것은 다음을 의미한다.
- 세션을 다시 시작하거나 모델이 충돌해도 작업이 손실되지 않는다.
- 모든 이후 에이전트는 공유 대화 이력에 의존하지 않고 이전 결과물을 직접 읽을 수 있다.
- 계획 결과물을 git에 검사, 편집 또는 커밋할 수 있다 — 데이터베이스의 불투명한 상태가 아닌 평문 텍스트이다.
`STATE.md`는 이 시스템의 중추이다. 프로젝트의 현재 위치(어느 마일스톤, 어느 단계, 어느 계획이 완료되었는지), 활성 결정 사항과 장애물, 진행 지표를 기록한다. 모든 워크플로우가 시작될 때 `STATE.md`를 읽어 방향을 잡는다. 모든 워크플로우가 의미 있는 단계를 완료할 때 `STATE.md`에 다시 기록한다. 에이전트는 기억에 의존하지 않는다; 파일에 의존한다.
---
## 트레이드오프
여기서 트레이드오프에 대한 솔직함이 중요하다.
**오버헤드.** 단계 루프는 실제 마찰을 야기한다. `/gsd-discuss-phase`, `/gsd-plan-phase`, `/gsd-execute-phase`를 별도의 단계로 실행하는 것은 단순 세션에 "이 기능을 작성해줘"라고 입력하는 것보다 더 많은 경과 시간이 걸린다. 작고 잘 이해된 변경의 경우 그 오버헤드는 정당화되지 않는다.
**지연.** 신선한 컨텍스트로 여러 서브에이전트를 생성하는 것은 단일 인-컨텍스트 편집보다 느리다. 리서치, 계획 수립, 실행 각각에 왕복 비용이 발생한다.
**단순한 작업에 대한 의례.** 변수 이름을 바꾸거나, 오타를 수정하거나, 누락된 임포트를 추가해야 할 때 단계 루프는 과도하다. GSD Core는 전체 단계를 필요로 하지 않는 임시 작업을 위해 `/gsd-quick`과 `/gsd-fast`를 제공한다. [빠른 작업 처리하기](../how-to/handle-quick-and-fast-tasks.md)를 참조하라.
단계 루프는 컨텍스트 부패가 실제 위험인 만큼 복잡한 작업 — 다중 파일 기능, 횡단 관심사 리팩터링, 몇 시간 또는 여러 세션에 걸친 작업 — 에서 그 가치를 발휘한다. 그 외의 경우에는 더 가벼운 기본 도구를 사용하라.
유용한 경험 법칙: 단일 짧은 프롬프트로 완전히 명시되고 더 이상의 설명 없이 에이전트 한 번의 작업으로 완료될 수 있다면, 단계 루프를 건너뛰어라. 리서치가 필요하거나, 최근에 읽지 않은 파일이 포함되거나, 아직 결정되지 않은 사항에 의존한다면, 단계 루프가 보호해준다.
---
## Related
- [단계 루프](the-phase-loop.md) — 논의 → 계획 → 실행 → 검증 → 출시 사이클이 컨텍스트 엔지니어링을 실천에 옮기는 방법
- [다중 에이전트 오케스트레이션](multi-agent-orchestration.md) — 서브에이전트가 생성, 범위 지정, 조율되는 방법
- [아키텍처](../ARCHITECTURE.md) — 시스템 아키텍처, 에이전트 모델, 데이터 흐름
- [문서 인덱스](../README.md)

151
docs/ko-KR/explanation/multi-agent-orchestration.md Normal file
View File

@@ -0,0 +1,151 @@
# GSD Core의 다중 에이전트 오케스트레이션
> **설명** — 이 문서는 GSD Core가 다중 에이전트 오케스트레이션을 중심으로
> 설계된 *이유*와 *구성 요소들이 어떻게 맞물리는지*를 설명한다. 단계별
> 가이드가 아니다. 설정에 대해서는
> [모델 프로필 설정](../how-to/configure-model-profiles.md)과
> [설정 레퍼런스](../CONFIGURATION.md)를 참조하라. 전체 에이전트 목록은
> [인벤토리](../INVENTORY.md)를 참조하라.
---
## 이 설계가 해결하는 문제
AI 코딩 에이전트는 저하된다. 모델이 나빠지기 때문이 아니라 *컨텍스트 윈도우가 채워지기* 때문이다. 대화가 길어질수록 초반의 결정들과 코드가 중간 단계들의 노이즈에 밀려나거나 희석된다. 복잡한 작업에서 다섯 번째 파일을 작성할 때쯤 에이전트는 첫 번째 메시지에서 명시된 제약 조건을 이미 잊었을 수도 있다. 이를 *컨텍스트 부패*라고 부르기도 한다.
GSD Core의 다중 에이전트 설계는 그 문제에 대한 직접적인 대응이다. 하나의 장시간 실행 에이전트가 전체 세션을 담당하는 대신, 얇은 오케스트레이터가 **신선한 200K 토큰 컨텍스트 윈도우**와 *자신의 특정 작업을 수행하는 데 필요한 결과물만* 갖고 시작하는 단수명 전문화 에이전트들을 생성한다. 오케스트레이터 자신은 절대 무거운 작업을 하지 않는다; 컨텍스트를 로드하고, 적합한 에이전트를 생성하고, 결과를 수집하고, `.planning/`의 공유 상태를 업데이트한다.
---
## 오케스트레이터 → 에이전트 패턴
`get-shit-done/workflows/`의 모든 워크플로우는 동일한 형태를 따른다:
```text
오케스트레이터 (워크플로우 .md 파일)
│
├── 컨텍스트 로드
│ gsd-tools.cjs init <workflow> <phase>
│ → JSON: 프로젝트 정보, 설정, 상태, 단계 상세
│
├── 모델 해결
│ gsd-tools.cjs resolve-model <agent-name>
│ → opus | sonnet | haiku | inherit
│
├── 전문화 에이전트 생성 (Task/SubAgent 호출)
│ ├── 에이전트 정의 (agents/*.md)
│ ├── 컨텍스트 페이로드 (init JSON)
│ ├── 모델 할당
│ └── 도구 권한
│
├── 결과 수집
│
└── 상태 업데이트
gsd-tools.cjs state update / state patch / state advance-plan
```
오케스트레이터는 의도적으로 얇다. 도메인에 대해 추론하지 않고, 코드를 작성하지 않으며, 다음 단계로 라우팅하는 것 이상으로 결과를 해석하지 않는다. 그 경계는 각 계층의 책임을 명확하게 유지하고 오케스트레이터의 컨텍스트가 도메인 노이즈를 축적하는 것을 방지한다.
### 에이전트 목록
GSD Core의 에이전트들은 리서치 → 계획 → 실행 → 검증 파이프라인에 매핑되는 기능 범주로 나뉜다:
| 범주 | 에이전트 | 일반적인 병렬성 |
|---|---|---|
| 리서처 | `gsd-project-researcher`, `gsd-phase-researcher`, `gsd-ui-researcher`, `gsd-advisor-researcher` | 4개 병렬 (스택, 기능, 아키텍처, 함정) |
| 합성기 | `gsd-research-synthesizer` | 리서처 완료 후 순차적 |
| 플래너 | `gsd-planner`, `gsd-roadmapper` | 순차적 |
| 검사기 | `gsd-plan-checker`, `gsd-integration-checker`, `gsd-ui-checker`, `gsd-nyquist-auditor` | 순차적, 최대 3번 수정 반복 |
| 실행기 | `gsd-executor` | 웨이브 내 병렬, 웨이브 간 순차적 |
| 검증기 | `gsd-verifier` | 모든 실행기 완료 후 순차적 |
| 매퍼 | `gsd-codebase-mapper` | 4개 병렬 하위 프로브 |
| 감사기 | `gsd-ui-auditor`, `gsd-security-auditor` | 순차적 |
각 에이전트 정의(`agents/*.md`)는 허용된 도구 접근, 목적, 터미널 출력 색상을 선언한다. 파일을 읽고 단일 출력 문서를 작성하기만 하면 되는 에이전트는 정확히 그런 권한만 받는다 — Bash 실행 없음, 광범위한 상태 접근 없음. 그 제약은 의도적이다: 에이전트가 예상치 못하게 행동할 경우 영향 범위를 작게 유지한다.
전체 31개 에이전트 목록은 [인벤토리](../INVENTORY.md#agents-31-shipped)를 참조하라.
---
## 웨이브 기반 병렬 실행
다중 에이전트 설계의 가장 눈에 띄는 표현은 `/gsd-execute-phase`가 서로 의존관계가 있는 계획들의 집합을 처리하는 방식이다.
실행기를 생성하기 전에 오케스트레이터는 **웨이브 분석**을 수행한다: 각 `PLAN.md` 파일의 의존성 선언을 읽고 계획들을 웨이브로 그룹화한다. 선언된 의존성이 없는 계획들은 웨이브 1을 형성하고 병렬로 실행된다. 웨이브 1에 의존하는 계획들은 웨이브 2를 형성하고, 계속해서 이어진다.
```text
계획 01 (의존성 없음) ─┐
계획 02 (의존성 없음) ─┤─── 웨이브 1 (병렬)
계획 03 (의존: 01) ─┤─── 웨이브 2 (웨이브 1 대기)
계획 04 (의존: 02) ─┘
계획 05 (의존: 03, 04) ─── 웨이브 3 (웨이브 2 대기)
```
웨이브 내 각 실행기는:
- 신선한 컨텍스트 윈도우(200K 토큰, 또는 지원 모델에서 최대 1M)를 받는다
- 담당하는 특정 `PLAN.md`를 받는다
- 프로젝트 컨텍스트(`PROJECT.md`, `STATE.md`)를 받는다
- 단계 컨텍스트(가용한 경우 `CONTEXT.md`, `RESEARCH.md`)를 받는다
- 완료 시 원자적 git 커밋을 생성한다
- 만들어진 것을 설명하는 `SUMMARY.md`를 작성한다
웨이브의 모든 실행기가 완료된 후, 오케스트레이터는 전체 웨이브에 대해 한 번 사전 커밋 훅을 실행한다. 실행기는 여러 에이전트가 병렬로 커밋할 때의 빌드 잠금 경합(예: Rust 프로젝트의 Cargo 잠금 충돌)을 방지하기 위해 `--no-verify`로 커밋한다. 따라서 훅은 커밋당 한 번이 아닌 웨이브당 한 번 실행된다.
### 병렬 커밋 안전성
여러 실행기가 동시에 실행될 때 쓰기 충돌을 방지하는 두 가지 메커니즘이 있다:
1. **`STATE.md`에 대한 원자적 잠금** — `STATE.md`에 대한 모든 쓰기는 `O_EXCL` 원자적 생성을 사용하는 잠금파일(`STATE.md.lock`)을 사용한다. 이는 두 에이전트가 각각 파일을 읽고, 서로 다른 필드를 수정하고, 나중에 쓰는 쪽이 먼저 쓴 쪽의 변경 사항을 덮어쓰는 읽기-수정-쓰기 경합 조건을 방지한다. 오래된 잠금(10초 이상)은 자동으로 지워진다.
2. **웨이브당 훅 실행** — 각 실행기가 사전 커밋 훅을 독립적으로 실행하는 대신(공유 빌드 결과물에 파일 수준 경합을 유발할 수 있음), 오케스트레이터는 모든 웨이브가 완료된 후 한 번 `git hook run pre-commit`을 실행한다.
---
## 대형 윈도우 모델을 위한 적응형 컨텍스트 보강
표준 200K 컨텍스트 윈도우는 실행기가 단일 집중된 계획을 구현하기에 충분하다. 구성된 `context_window`가 500K 토큰 이상인 경우(예: Opus 4.6 또는 Sonnet 4.6을 1M 클래스 모드로 사용할 때), 오케스트레이터는 자동으로 표준 윈도우에 들어가지 않는 추가 컨텍스트로 서브에이전트 프롬프트를 보강한다:
- **실행기 에이전트**는 이전 웨이브의 `SUMMARY.md` 파일들과 단계 `CONTEXT.md`/`RESEARCH.md`를 받아 단계 내 교차 계획 인식을 갖는다
- **검증기 에이전트**는 모든 `PLAN.md`, `SUMMARY.md`, `CONTEXT.md` 파일들과 `REQUIREMENTS.md`를 받아 이력 인식 검증을 할 수 있다
이 보강은 `config.json`의 `context_window` 값에 조건부이다. 표준 윈도우 설정에서는 캐시 친화적 순서로 토큰 효율성을 최대화하는 잘린 버전의 프롬프트를 사용한다.
---
## 이 설계의 이유 — 컨텍스트 엔지니어링과의 연결
오케스트레이터 → 에이전트 패턴은 더 광범위한 *컨텍스트 엔지니어링* 접근 방식의 일부로서만 의미가 있다: AI 에이전트의 컨텍스트 윈도우에 들어가는 것이 모델 등급이나 프롬프트 품질만큼 중요하다는 아이디어. 전체 내용은 [컨텍스트 엔지니어링](context-engineering.md)을 참조하라.
다중 에이전트 오케스트레이션은 두 가지 방식으로 컨텍스트 엔지니어링을 구현한다:
**컨텍스트 격리.** 각 에이전트는 필요한 것만 받는다. 리서처는 프로젝트 설명과 도메인 질문들을 받는다; 전체 계획 이력은 받지 않는다. 검증기는 모든 계획과 요약을 받는다; 원시 리서치는 받지 않는다. 격리는 각 에이전트의 컨텍스트를 다른 파이프라인 단계들의 노이즈로 희석되지 않고 신호로 밀도 있게 유지한다.
**세션 간 컨텍스트 위생.** 모든 상태가 사람이 읽을 수 있는 마크다운과 JSON으로 `.planning/`에 저장되기 때문에(에이전트의 컨텍스트 윈도우가 아닌), GSD 워크플로우는 컨텍스트 리셋(`/clear`), 탭 전환, 며칠간의 휴식을 견뎌낸다. 다음 에이전트는 항상 긴 대화의 재구성된 기억이 아닌 영속적이고 검증된 결과물에서 시작한다.
---
## 트레이드오프
다중 에이전트 오케스트레이션은 비용이 없지 않다.
**조율 오버헤드.** 각 에이전트 생성은 왕복이다: 오케스트레이터가 프롬프트를 형식화하고, 컨텍스트를 넘기고, 서브에이전트가 완료될 때까지 기다리고(일반적으로 1-5분), 결과를 파싱해야 한다. 하나의 컨텍스트에서 작동하는 단일 능력 있는 에이전트는 단순한 작업에서 더 빨리 완료될 것이다. GSD는 의존성이 허용되는 모든 곳에서 병렬성을 기본값으로 만들어 이를 완화한다 — `plan-phase`의 네 리서처들은 순차적이 아닌 동시에 실행된다.
**실행 중 불투명성.** 서브에이전트가 실행되는 동안 그 작업은 부모 세션에서 보이지 않는다. 실시간 진행 스트림이 없다. 이것은 신선한 컨텍스트 설계의 의도적인 결과이다: 서브에이전트가 자체 컨텍스트 윈도우에서 작동하고 있다. 오케스트레이터는 생성 라인에 활성 표시를 보여줌으로써("서브에이전트에서 실행됨 — 반환될 때까지 출력 없음") 기대치를 설정한다.
**컨텍스트 스티칭 비용.** 각 에이전트에 적합한 결과물들을 패키징하려면 오케스트레이터가 컨텍스트 페이로드를 조립하고 전송하는 데 토큰을 소비해야 한다. 이것이 격리의 비용이다. `gsd-tools.cjs init` 핸들러는 완전성과 토큰 예산의 균형을 맞추는 JSON 페이로드를 생성하며, 반복 호출에서 캐시에 도달하도록 캐시 친화적 순서를 적용한다.
**모델 비용 증폭.** Opus 등급으로 다섯 개의 에이전트를 병렬로 실행하는 것은 하나를 실행하는 것보다 더 비용이 많이 든다. 모델 프로필 시스템(`model_profiles.md`, `model-profiles.cjs`에 의해 에이전트별로 해결됨)을 사용하면 덜 중요한 에이전트에 더 저렴한 등급을 할당할 수 있다. `dynamic_routing` 기능은 모든 에이전트를 더 저렴한 등급에서 시작하고 소프트 실패 시에만 에스컬레이션함으로써 비용을 더 줄여준다. 전체 옵션은 [설정](../CONFIGURATION.md)을 참조하라.
이런 비용의 대가로 이 설계는 *대형 단계에서의 일관된 품질*을 제공한다. 400줄 계획의 열 번째 파일을 작성하는 실행기는 컨텍스트가 신선하기 때문에 저하되지 않는다. 스무 개의 요구 사항을 확인하는 검증기는 처음 열 개를 잊지 않는다. 왜냐하면 대화 이력이 아닌 구조화된 입력으로 모두 받았기 때문이다.
---
## Related
- [컨텍스트 엔지니어링](context-engineering.md) — 이 설계에 동기를 부여하는 상위 원칙
- [모델 프로필 설정](../how-to/configure-model-profiles.md) — 에이전트별로 모델 등급을 할당하는 방법
- [설정 레퍼런스](../CONFIGURATION.md) — `models`, `model_overrides`, `dynamic_routing`, `context_window`를 포함한 전체 `config.json` 스키마
- [인벤토리](../INVENTORY.md) — 권위 있는 에이전트 목록과 워크플로우 목록
- [아키텍처](../ARCHITECTURE.md#agent-model) — 오케스트레이터 → 에이전트 패턴과 웨이브 실행 모델의 구현 수준 상세
- [문서 인덱스](../README.md)

123
docs/ko-KR/explanation/security-model.md Normal file
View File

@@ -0,0 +1,123 @@
# GSD Core 보안 모델
> **설명** — 이 문서는 GSD Core가 현재의 보안 자세를 갖는 *이유*와 *계층들이
> 어떻게 맞물리는지*를 설명한다. 모든 훅 파라미터에 대한 레퍼런스가 아니다.
> `/gsd-secure-phase` 명령과 옵션에 대해서는 [명령어](../COMMANDS.md)를 참조하라.
> 구현 수준의 훅 아키텍처에 대해서는
> [아키텍처 § 훅 시스템](../ARCHITECTURE.md#hook-system)을 참조하라.
> 조직 전반의 보안 기준선(스캐너 제어, 인시던트 체크리스트, 소유권 모델)에 대해서는
> [SECURITY.md](../../../SECURITY.md)를 참조하라.
---
## AI 기반 개발에 전용 보안 자세가 필요한 이유
일반적인 코드 에디터는 사용자를 대신하여 임의의 패키지를 실행하지 않는다. GSD Core는 그렇게 한다. 리서치 → 계획 → 실행 파이프라인은 "패키지 이름 지정"에서 "`npm install <package>` 실행"까지, "계획 결과물 작성"에서 "해당 결과물을 LLM 시스템 프롬프트로 사용"까지의 전체 경로를 자동화한다. 각 자동화 단계는 루프에서 사람을 제거한다 — 그리고 각 제거는 잠재적인 공격 표면이다.
GSD Core의 보안 모델은 하나의 조직 원칙을 중심으로 구축된다: **심층 방어(defence in depth)**. 어떤 단일 제어도 완벽하다고 가정하지 않는다. 여러 겹치는 계층이 각각 고유한 종류의 위험을 줄이며, 함께 공격 표면을 완전히 제거하지는 않지만 악용하기 상당히 더 어렵게 만든다. 이 문서 끝의 솔직한 요약은 시스템이 방어할 수 없는 것을 설명한다.
---
## 계층 1 — 공급망 보호: 패키지 적법성 게이트
### 위협
AI 모델은 패키지 이름을 환각한다. 이것은 변두리 실패 모드가 아니다: 2025년 연구에서 AI가 생성한 패키지 참조의 약 20%가 합법적인 패키지와 대응되지 않는 환각된 이름으로 문서화되었다. 그 환각된 이름들의 일부 — 같은 연구에서 약 43% — 는 프롬프트 전반에 걸쳐 일관되게 반복되며, 이는 공격자가 AI 도구들이 일반적으로 생성하는 이름을 관찰하고 악의적인 설치 후 스크립트로 npm, PyPI, 또는 crates.io에 해당 이름들을 선점 등록할 수 있다는 것을 의미한다. 이 기법을 *슬롭스쿼팅(slopsquatting)*이라고 한다.
슬롭스쿼팅의 교활한 특성은 `npm view`를 통과하는 환각된 이름이 *합법적으로 보인다*는 것이다. 레지스트리 항목은 누군가가 이름을 등록했다는 것만 증명한다 — AI가 말한 것을 패키지가 한다거나, 합법적인 사용자가 있다거나, 설치 스크립트가 안전하다는 것은 증명하지 않는다. 게이트 없이는 환각된 이름이 GSD의 리서처 → 플래너 → 실행기 파이프라인을 통해 감지되지 않고 흐르다가 결국 사용자의 기계에서 `npm install <attacker-package>`로 실행될 것이다.
### 게이트 작동 방식
게이트는 세 가지 파이프라인 단계에 걸쳐 작동한다:
**리서치 단계.** `gsd-phase-researcher`가 외부 패키지를 추천할 때 각 패키지에 대해 `slopcheck install <pkgs> --json`을 실행한다. 결과는 `RESEARCH.md`의 `## Package Legitimacy Audit` 테이블에 작성된다. `[SLOP]`로 태그된 패키지들(높은 신뢰도의 환각 또는 공격자가 등록)은 파일이 저장되기 전에 **`RESEARCH.md`에서 완전히 제거된다**. 이런 패키지들은 절대 플래너에게 도달하지 않는다.
**계획 단계.** `gsd-planner`는 감사 테이블을 읽는다. `[SUS]`(의심스러움: 최근 등록, 낮은 다운로드 수, 소스 저장소 없음, 또는 인기 있는 패키지와 가까운 명명 패턴)나 `[ASSUMED]`(직접 레지스트리 검증이 아닌 WebSearch에서 출처)로 태그된 모든 패키지에 대해, 플래너는 설치 단계 전에 **`checkpoint:human-verify` 작업을 삽입한다**. 체크포인트에는 레지스트리 페이지로의 직접 링크와 살펴봐야 할 구체적인 항목들이 포함된다: 유지관리자 이력, 이슈 트래커 활동, 의심스러운 설치 스크립트의 부재.
**실행 단계.** 설치가 실패하면 `gsd-executor`는 **체크포인트를 표시하고 중지한다**. 대체 패키지 이름을 조용히 시도하지 않는다 — 그 자체가 악의적일 수 있다. 이는 실행기 동작의 명시적인 규칙이다(실행기 에이전트 정의의 RULE 3).
### WebSearch 패키지가 항상 `[ASSUMED]`인 이유
WebSearch를 통해 발견된 패키지 이름은 `npm view`가 성공하는지 여부에 관계없이 `[ASSUMED]`로 태그된다. 레지스트리에 존재하는 패키지가 설치하기에 안전한 패키지와 같지 않다. `npm view`는 등록을 증명하지, 적법성을 증명하지 않는다. `[ASSUMED]` 태그는 `[SUS]`와 동일한 사람 검증 체크포인트를 트리거하여, 검증되지 않은 웹 검색 추천이 설치 전에 항상 사람의 검토를 받도록 보장한다.
### 생태계 커버리지
리서처는 단일 일반 검사 대신 레지스트리별 검증 명령을 사용한다:
- Node.js: `npm view`
- Python: `pip index versions`
- Rust: `cargo search`
이는 2025년 USENIX 연구에 따르면 약 9% 발생률의 교차 생태계 환각을 커버한다 — AI가 실제로 사용 중인 것이 아닌 한 생태계에서는 존재하지만 다른 생태계에서는 없는 패키지를 추천하는 경우.
### 정상적인 성능 저하
`slopcheck`을 사용할 수 없는 경우(설치되지 않았거나 리서치 시점에 pip 설치 실패), GSD는 가장 엄격한 폴백을 적용한다: **모든 추천 패키지가 `[ASSUMED]`로 태그되고**, 플래너는 모든 설치에 `checkpoint:human-verify` 작업을 게이트로 건다. 리서치와 계획 수립은 정상적으로 진행된다 — 시스템은 누락된 도구 의존성으로 인해 하드 실패하지 않는다. 이것은 의도적으로 정상 흐름보다 더 엄격하다: slopcheck 사용 불가는 모든 패키지 설치에 사람 체크포인트를 받는다는 것을 의미한다.
`slopcheck` 도구는 MIT 라이선스이며 pip으로 설치 가능하다. 유지 관리가 중단되더라도 `[ASSUMED]`-게이트 폴백은 사람 체크포인트 커버리지가 유지되도록 보장한다.
---
## 계층 2 — 프롬프트 인젝션 방어
### 위협
GSD Core는 LLM 시스템 프롬프트가 되는 마크다운 파일을 생성한다. 리서치 파이프라인은 외부 웹 콘텐츠를 읽는다; 계획 파이프라인은 사용자가 제공한 텍스트(`--text-file`, `--prd`)를 통합한다; 실행 파이프라인은 에이전트 컨텍스트로 나중에 다시 읽히는 계획 결과물을 작성한다. 이런 결과물들에 흐르는 사용자가 제어하는 텍스트는 잠재적인 **간접 프롬프트 인젝션** 벡터이다 — 시스템 프롬프트 안에 들어가면 에이전트의 지시 사항을 재정의하거나 정보를 유출하려는 공격자가 제어하는 문자열.
### 방어 작동 방식
GSD Core는 세 가지 수준에서 프롬프트 인젝션을 다룬다.
**입력 유효성 검사(`security.cjs`).** `get-shit-done/bin/lib/security.cjs` 모듈은 중앙 보안 유틸리티이다. 다음을 제공한다:
- 경로 탐색 방지: 사용자가 제공한 파일 경로(`--text-file`, `--prd`)가 프로젝트 디렉터리 내에서 해결되도록 유효성이 검사되며, macOS의 `/var` → `/private/var` 심링크 해결이 명시적으로 처리된다
- 프롬프트 인젝션 탐지: 알려진 인젝션 패턴(역할 재정의, 지시 우회, 시스템 태그 인젝션)이 사용자가 제공한 텍스트에서 계획 결과물에 들어가기 전에 스캔된다
- 안전한 JSON 파싱: 제작된 JSON 페이로드를 통한 프로토타입 오염 공격을 방지하는 래퍼
- 쉘 인수 유효성 검사: 하위 쉘 명령에 전달되는 인수가 사용 전에 유효성이 검사된다
**런타임 훅: `gsd-prompt-guard.js`.** 이 훅은 `.planning/` 파일을 대상으로 하는 모든 Write 또는 Edit 호출에서 실행된다. 작성되는 콘텐츠를 `security.cjs`와 동일한 인젝션 패턴으로 스캔한다(독립성을 위해 훅에 직접 인라인된 하위 집합 — 훅은 모듈 경로가 변경되더라도 실행되도록 모듈을 `require()`하지 않는다). 탐지는 **자문적 전용**이다: 훅은 결과를 로그하지만 쓰기를 차단하지 않는다. 이유는 합법적인 계획 쓰기에 대한 오탐지 차단이 이차 스캔 계층에서 놓친 인젝션보다 더 방해가 될 것이기 때문이다.
**런타임 훅: `gsd-read-injection-scanner.js`.** 이 훅은 모든 Read 도구 호출의 출력에서 실행된다. 방금 읽은 *콘텐츠*를 신뢰할 수 없는 콘텐츠의 주입된 지시 사항으로 스캔한다 — 공격자가 GSD가 에이전트 컨텍스트에 통합하려는 파일에 지시 사항을 내장한 경우를 잡아낸다.
**CI 스캐너.** `prompt-injection-scan.test.cjs`는 테스트 스위트의 일부로 내장된 인젝션 벡터가 있는지 모든 에이전트, 워크플로우, 명령 파일을 스캔한다. 이는 GSD 소스 자체의 인젝션 시도를 잡아낸다 — 예를 들어 워크플로우 파일을 수정하여 역할 재정의 지시 사항을 추가하는 공급망 공격.
### 읽기 인젝션 스캐너 vs 프롬프트 가드
두 훅은 보완적인 표면을 커버한다. `gsd-prompt-guard.js`는 *계획 결과물에 대한 쓰기*를 감시한다 — 심어지는 인젝션을 잡는다. `gsd-read-injection-scanner.js`는 *모든 파일의 읽기*를 감시한다 — 외부 콘텐츠(의존성의 README, 타사 설정 파일, 사용자가 제공한 문서)에서 수집되는 인젝션을 잡는다. 함께 수집 → 저장 → 재독 수명 주기를 괄호로 묶는다.
---
## 계층 3 — 저장소 및 의존성 무결성
GSD의 런타임 동작 상류에서 `open-gsd` 조직은 저장소와 패키지 수준에서 제어를 시행한다. 이것들은 [`docs/security/baseline.md`](../../security/baseline.md)에 완전히 문서화되어 있으며 완전성을 위해 여기에 요약된다.
**의존성 무결성.** 모든 타사 의존성은 `package-lock.json`을 통해 고정되고 설치 전에 공개된 체크섬에 대해 검증된다. `scripts/check-npm-integrity.cjs` 게이트는 CI 시점에 유효하지 않은 버전, 누락된 패키지, 불필요한 패키지를 탐지한다. 이는 GSD 자체 의존성에 대한 의존성 혼동 및 오타스쿼팅 공격을 완화한다.
**비밀 스캔.** 모든 커밋과 PR은 하드코딩된 비밀이 있는지 스캔된다. 의도적인 테스트 픽스처는 프로젝트 표준 제외 문법으로 주석을 달아야 한다(주석 형식은 `SECURITY.md` 참조). 주석이 없는 억제는 CI를 실패시킨다.
**로케일 안전 텍스트 스캔.** 출력 및 사용자 대면 문자열은 유니코드 동형 문자, 양방향 오버라이드 문자, 보이지 않는 유니코드에 대해 스캔된다 — 차이점에서 악의적인 콘텐츠를 숨길 수 있는 CVE-2021-42574("Trojan Source")에 문서화된 공격 클래스.
---
## 트레이드오프와 한계
여기에 설명된 보안 모델은 AI 기반 개발을 위한 공격 표면을 의미 있게 줄인다. 공급망 위험을 제거하지는 않는다.
**패키지 적법성 게이트가 줄이는 것:** 환각되거나 공격자가 등록한 패키지가 사람 체크포인트 없이 `npm install`에 도달할 확률. `[SLOP]` 게이트는 높은 신뢰도의 나쁜 패키지를 완전히 제거한다; `[SUS]` / `[ASSUMED]` 게이트는 실행 전에 사람 검토를 요구한다. 이는 성공적인 슬롭스쿼팅 공격의 비용을 상당히 높인다.
**패키지 적법성 게이트가 제거하지 않는 것:** 나중에 손상된 합법적인 패키지(계정 탈취, 자체 트리의 의존성 혼동)는 리서치 시점의 등록 신호를 확인하는 slopcheck에 의해 잡히지 않는다. 잠금 파일과 의존성 무결성 계층의 `npm audit`이 그 공격 클래스에 대한 제어이다.
**프롬프트 인젝션 방어가 줄이는 것:** 계획 결과물의 사용자가 제어하는 텍스트가 에이전트 지시 사항을 성공적으로 재정의할 확률. 알려진 인젝션 형태에 대한 패턴 매칭은 일반적인 경우를 잡는다; 새로운 탈옥이나 저신호 인젝션은 탐지되지 않고 통과할 수 있다. 자문 전용 자세는 탐지가 로그되지만 차단되지 않는다는 것을 의미한다 — 탐지 시 하드 정지하지 않는 비용으로 워크플로우 연속성을 보존하는 의도적인 선택.
**프롬프트 인젝션 방어가 제거하지 않는 것:** 알려진 패턴과 일치하지 않는 충분히 창의적인 인젝션, 또는 훅이 커버하지 않는 채널을 통해 도달하는 인젝션(예: 서브에이전트가 문서를 탐색하면서 읽는 의존성의 공개된 README에 주입된 콘텐츠). 심층 방어는 각 계층이 공격을 더 어렵게 만들지, 어떤 단일 계층이 불가능하게 만들지 않는다는 것을 의미한다.
**취약점 신고.** `https://github.com/open-gsd/gsd-core/security/advisories/new`에서 비공개 GitHub 보안 보고서를 통해 신고하라. 공개 이슈를 열지 말라. 응답 일정과 공개 정책은 [SECURITY.md](../../../SECURITY.md)를 참조하라.
---
## Related
- [명령어](../COMMANDS.md) — 보안 관련 플래그가 있는 `/gsd-secure-phase`와 `/gsd-code-review` 포함
- [아키텍처 § 훅 시스템](../ARCHITECTURE.md#hook-system) — 모든 훅, 이벤트 트리거, 안전 속성에 대한 구현 상세
- [SECURITY.md](../../../SECURITY.md) — 취약점 신고, 조직 전반 보안 기준선, 비밀 스캔 제외 거버넌스, 의존성 무결성 검증
- [문서 인덱스](../README.md)

129
docs/ko-KR/explanation/the-phase-loop.md Normal file
View File

@@ -0,0 +1,129 @@
# 단계 루프
> GSD Core가 작업을 조직하는 방식의 핵심 멘탈 모델.
---
## 루프란 무엇인가
GSD Core는 모든 개발 작업을 반복되는 사이클로 구조화한다.
```text
논의 → (UI 디자인) → 계획 → 실행 → 검증 → 출시
```
모든 작업 단위 — **단계(phase)**라고 부름 — 는 이 순서대로 각 단계를 거친다. 루프는 형식적인 절차가 아니다. 각 단계는 이전 단계 혼자서는 방지할 수 없는 특정 종류의 실패를 막기 위해 존재한다.
이 문서는 루프가 이런 형태를 갖는 *이유*를 설명한다. 각 단계를 실행하는 방법에 대한 지침은 하단에 링크된 how-to 가이드를 참조하라.
---
## 각 단계가 존재하는 이유
### 논의(Discuss)
무엇을 만들어야 하는지뿐만 아니라 *어떻게* 만들어야 하는지를 알기 전까지는 계획을 시작할 수 없다. `ROADMAP.md`의 단계 목표는 결과를 설명한다. 논의 단계는 그 결과로 가는 경로를 형성하는 구현 결정 사항들을 캡처한다: 어떤 라이브러리를 사용할지, 오류 처리 전략, 기능이 라우트별인지 전역인지, 엣지 케이스의 동작 방식.
논의 단계 없이는 플래너가 이런 결정들을 스스로 내려야 한다. 때로는 맞게 추측하기도 한다. 그러나 그럴듯하지만 틀리게 추측하는 경우도 많다 — 일관성은 있지만 실제 선호도와 맞지 않는 계획을 생성한다. 실행이 완료되고 오류를 발견했을 때는 이미 상당한 작업을 되돌려야 하는 상황이 된다.
논의 단계는 의도적으로 가볍다. 명세 작성 훈련이 아니라 대화이다. 출력물은 단계 디렉터리의 `CONTEXT.md`이다: 플래너, 실행기, 검증기 모두 읽을 수 있는 결정 사항들의 구조화된 기록. 대화는 몇 분이 걸리지만; 수 시간의 재작업을 절약할 수 있다.
### UI 디자인(선택적)
시각적 컴포넌트가 있는 단계의 경우, 논의와 계획 사이에 선택적인 `/gsd-ui-phase` 단계가 있다. 코드 작성 전에 레이아웃, 인터랙션, 시각적 동작을 설명하는 디자인 계약인 `UI-SPEC.md`를 생성한다. UI가 복잡하여 디자인의 모호함이 다양한 구현 선택을 만들어낼 만큼 복잡할 때 이 단계를 실행할 가치가 있다. 명확한 디자인 계약은 재구현보다 훨씬 비용이 저렴하다.
### 계획(Plan)
계획 단계는 실행에 필요한 리서치, 분해, 구조적 사고를 수행한다. 신선한 컨텍스트 서브에이전트들의 시퀀스로 실행된다: 생태계를 조사하고 `RESEARCH.md`에 결과를 기록하는 리서처, 리서치와 `CONTEXT.md` 모두를 읽어 `PLAN.md` 파일들을 생성하는 플래너, 계획이 완전하고 일관성 있으며 범위 내에 있는지 검증하는 계획 검사기.
계획에는 무엇이 포함되는가? 각 `PLAN.md`는 작업의 범위가 한정된 단위를 설명한다: 수정할 파일들, 수행할 구체적인 변경 사항들, 완료를 정의하는 수락 기준. 계획들은 병렬 실행이 안전하도록 의존성 웨이브 순서로 정렬된다 — 같은 웨이브의 실행기들은 겹치지 않는 관심사를 다룬다.
계획 단계는 모호함이 가장 비용이 많이 드는 순간이다. 모호한 계획은 가정을 세우는 실행기를 만든다. 같은 관심사에 대해 서로 다른 가정을 세우는 여러 병렬 실행기들은 충돌을 만든다. 계획 검사기의 임무는 실행 전에 이런 문제들을 잡아내는 것이다.
### 실행(Execute)
실행은 계획들을 수행한다. 각 실행기는 자신에게 필요한 것들만 정확히 담긴 신선한 200k 토큰 컨텍스트 윈도우를 받는다: 프로젝트 요약, 단계 컨텍스트, 리서치, 그리고 자신의 작업에 대한 특정 `PLAN.md`. 그 이상은 없다.
실행기는 코드를 작성하고 원자적으로 커밋한다. 각 커밋은 계획에서 완료된 작업과 대응된다. 병렬 실행기들의 웨이브가 완료되면, 오케스트레이터는 상태를 병합하고 다음 웨이브를 시작한다.
실행기의 신선한 컨텍스트는 편의를 위한 것이 아니다 — 컨텍스트 부패를 방지하는 메커니즘이다. 180k 토큰의 누적된 세션 이력으로 실행되는 실행기는 저하된 실행기이다. 깨끗하게 시작하고 계획이 필요로 하는 것만 읽는 실행기는 최대 능력으로 작동하는 실행기이다.
### 검증(Verify)
모든 실행기가 완료된 후, 검증기 에이전트는 단계 목표, `CONTEXT.md` 결정 사항들, 계획들, 실행 요약들을 읽고 — 만들어진 것이 의도한 것과 일치하는지 확인한다. `VERIFICATION.md`를 생성하고, 불일치가 있으면 대상이 명확한 수정 계획을 생성한다.
검증은 단순한 테스트가 아니다. 요구 사항 커버리지(모든 REQ-ID가 처리되었는가?), 결정 커버리지(`CONTEXT.md`에 캡처된 결정 사항들이 실제로 구현되었는가?), 전반적인 단계 목표 정렬을 확인한다. 단계는 실행이 오류 없이 완료되었기 때문에 완료되는 것이 아니다. 만들어진 것이 계획된 것이고, 계획된 것이 결정된 것이기 때문에 완료된다.
### 출시(Ship)
출시 단계는 풀 리퀘스트를 생성하고 단계 결과물들을 아카이브한다. `STATE.md`가 업데이트되어 단계 완료를 표시한다. 루프가 다음 단계를 위해 다시 시작된다.
---
## 마일스톤과 단계
**마일스톤**은 버전 사이클 — 프로젝트의 의미 있고 릴리스 가능한 증분이다. 이름, 버전 번호, 그리고 무엇을 제공해야 하는지 정의하는 요구 사항들의 집합을 갖는다. 마일스톤은 모든 단계들이 출시되고 요구 사항들이 충족되면 완료된다.
**단계**는 마일스톤 내의 하나의 작업 단위이다. 단계는 목표, 처리하는 요구 사항들의 집합, 그리고 그것을 구현하는 계획들의 집합을 갖는다.
이 관계가 중요한 이유는 마일스톤과 단계가 서로 다른 관심 범위를 갖기 때문이다. 마일스톤은 묻는다: "이 버전의 제품은 무엇을 하고, 무엇을 하지 않는가?" 단계는 묻는다: "우리가 다음으로 연구하고, 계획하고, 실행하고, 검증할 수 있는 범위가 한정된 것은 무엇인가?"
마일스톤 경계는 자연스러운 제품 경계에서 그어진다 — 배포 가능한 API, 작동하는 UI 플로우, 완전한 데이터 모델. 단계 경계는 루프가 다루기 힘들어지지 않고 하나의 루프에서 안전하게 실행될 수 있는 범위의 한계에서 그어진다.
---
## 좋은 단계 범위란 무엇인가
이것은 루프와 관련된 마찰의 가장 일반적인 원인이기 때문에 심층적으로 살펴볼 가치가 있다.
너무 큰 단계는 그 자체로 리서치 프로젝트가 된다. 플래너는 독립적인 계획들로 분해하는 데 어려움을 겪는다. 이후 웨이브의 실행기들이 이전 웨이브를 기다리며 막힌다. 검증이 대상이 명확한 리뷰보다 전체 감사가 된다. 피드백 사이클이 몇 시간에서 며칠로 늘어나고, 많은 코드가 작성된 후에야 — 근본적인 설계 오류를 발견할 위험이 급격히 높아진다.
너무 작은 단계는 자연스럽게 함께 속하는 작업을 분할한다. 몇 줄에 불과한 계획 파일들, 몇 분 안에 완료되는 단계들, 실행 비용을 압도하는 계획 오버헤드가 발생한다. 루프가 도움이 되기보다 관료적으로 느껴진다.
좋은 단계 범위는 다음과 같은 경우이다:
- 목표가 명백히 사소하지도 않고 의심스럽게 광범위하지도 않은 하나의 문장으로 명시될 수 있다.
- 계획에 필요한 리서치가 제한되어 있다 — 생태계 질문들이 다른 단계들이 먼저 완료되는 것에 의존하지 않는 답을 가진다.
- 실행이 수십 개가 아니라 소수의 겹치지 않는 계획들로 병렬화될 수 있다.
- 검증기가 전체 코드베이스를 읽지 않고도 확인할 수 있는 명확하고 테스트 가능한 완료 정의가 있다.
구체적으로: "HMAC-SHA256 서명 검증 미들웨어 추가"는 좋은 단계 범위이다. "인증 시스템 구축"은 일반적으로 아니다 — 거의 항상 별도의 단계로 더 잘 처리될 여러 독립적인 관심사들을 포함한다. "README의 오타 수정"은 루프가 가치를 추가하는 임계값 아래이다; 대신 `/gsd-quick`을 사용하라.
의심스러울 때는 분할하라. 더 작은 단계는 더 빨리 완료되고, 더 자신 있게 검증되고, 설계 결정이 잘못된 것으로 판명될 경우 방향을 수정하기 더 쉽다.
---
## `.planning/`이 루프 전반에 걸쳐 상태를 유지하는 방법
루프는 단일 세션이 아니다. 리서치, 계획 수립, 실행은 그 사이에 컨텍스트 리셋이 있는 여러 세션에 걸쳐 발생할 수 있다. `.planning/` 디렉터리가 이것을 가능하게 한다.
루프의 모든 단계는 이전 단계에서 생성된 결과물들을 읽고 이후 단계를 위한 결과물들을 작성한다. 논의 단계가 생성하는 CONTEXT.md는 플래너가 실행될 때도 사용 가능하다 — 몇 시간 후 다른 세션에서 실행되더라도. 플래너가 생성하는 PLAN.md 파일들은 실행기가 실행될 때도 사용 가능하다 — 재시작 후에도. 검증기가 작성하는 VERIFICATION.md는 단계를 검토할 때도 사용 가능하다.
`STATE.md`는 이 모든 것 위에 있는 내비게이션 레이어이다. 프로젝트가 루프의 정확히 어느 위치에 있는지 기록한다: 어느 마일스톤이 활성 상태인지, 어느 단계가 진행 중인지, 어느 계획들이 완료되고 어느 것들이 대기 중인지. 방향을 잡아야 하는 에이전트나 워크플로우는 먼저 `STATE.md`를 읽는다.
이 파일들의 정확한 구조는 [계획 결과물](../reference/planning-artifacts.md)과 [STATE.md 스키마](../reference/state-md.md)를 참조하라.
---
## 루프는 리듬이지 제약이 아니다
루프를 관료주의로 바라보는 시각이 있다 — 코드를 작성하기 전에 수행해야 하는 일련의 필수 단계들. 그 프레임은 틀렸다.
루프는 각 단계가 나중에 수정하는 데 실제로 비용이 많이 드는 실패들을 방지하기 때문에 존재한다. 논의는 잘못된 가정 위에서 계획하는 것을 방지한다. 계획은 근본적으로 깨진 설계를 실행하는 것을 방지한다. 검증은 요약 사항을 놓친 작업을 출시하는 것을 방지한다. 이것들은 인위적인 문제가 아니다. 실제 기능 규모에서 AI 보조 개발의 실제 실패 모드들이다.
루프가 잘 작동할 때 리듬처럼 느껴진다: 각 단계가 이전 단계가 자신의 역할을 했기 때문에 명확한, 집중적이고 범위가 한정된 작업의 박자. 오버헤드는 실재하지만, 전면 부담된다 — 수 시간의 재작업이 아니라 몇 분의 계획으로 지불된다.
루프가 정당화되는 임계값 아래의 작업을 위해 GSD Core는 더 가벼운 기본 도구들을 제공한다. 단계 루프는 하나의 도구이지, 유일한 도구가 아니다.
---
## Related
- [컨텍스트 엔지니어링](context-engineering.md) — 신선한 컨텍스트 서브에이전트가 루프를 필요하게 만드는 품질 저하를 방지하는 방법
- [단계 논의하기](../how-to/discuss-a-phase.md)
- [단계 계획하기](../how-to/plan-a-phase.md)
- [단계 실행하기](../how-to/execute-a-phase.md)
- [검증 및 출시](../how-to/verify-and-ship.md)
- [계획 결과물](../reference/planning-artifacts.md)
- [STATE.md 스키마](../reference/state-md.md)
- [문서 인덱스](../README.md)

218
docs/ko-KR/how-to/configure-model-profiles.md Normal file
View File

@@ -0,0 +1,218 @@
# 모델 프로파일을 설정하는 방법
프로젝트에 적합한 모델 티어 전략을 선택한 다음, 대규모 재정의 블록을 작성하지 않고 개별 에이전트나 전체 페이즈 유형을 조정하세요. 이 가이드는 가장 간단한 방법부터 시작하여 동적 라우팅까지 다룹니다.
---
## 네 가지 프로파일 (`adaptive`와 `inherit` 포함)
`.planning/config.json`에서 `model_profile`을 설정하거나 `/gsd-config --profile <name>`을 사용하세요:
| 프로파일 | 플래너 | 실행자 | 리서처 | 검증자 | 사용 시기 |
|---------|---------|----------|-------------|----------|----------|
| `quality` | Opus | Opus | Opus | Sonnet | 비용보다 품질이 중요한 프로덕션 작업 |
| `balanced` | Opus | Sonnet | Sonnet | Sonnet | 일반 개발 — 기본값 |
| `budget` | Sonnet | Sonnet | Haiku | Haiku | 빠른 프로토타이핑, 비용 민감 환경 |
| `adaptive` | Opus | Sonnet | Sonnet | Sonnet | 런타임 간 자주 전환할 때 사용; 다른 티어와 동일하게 런타임 인식 프로파일로 해결됨 |
| `inherit` | (세션 모델) | (세션 모델) | (세션 모델) | (세션 모델) | 비 Anthropic 프로바이더(OpenRouter, 로컬 모델) — 모든 에이전트가 현재 세션 모델을 따름 |
위 테이블은 대표적인 하위 집합을 보여줍니다. 출시된 33개 에이전트 모두 `sdk/shared/model-catalog.json`에 명시적인 프로파일별 티어 할당이 있습니다. 전체 테이블은 설정 참조의 [모델 프로파일](../CONFIGURATION.md#model-profiles)을 참고하세요.
**명령으로 빠르게 전환:**
```bash
/gsd-config --profile balanced # 일반 개발
/gsd-config --profile budget # 프로토타이핑 또는 고비용 페이즈
/gsd-config --profile quality # 프로덕션 릴리스
/gsd-config --profile inherit # OpenRouter, 로컬 모델
```
**또는 `.planning/config.json` 직접 편집:**
```json
{
"model_profile": "balanced"
}
```
---
## 에이전트별 재정의 (`model_overrides`)
전체 프로파일을 변경하지 않고 단일 에이전트에 다른 티어가 필요한 경우 `model_overrides`를 사용하세요:
```json
{
"model_profile": "balanced",
"model_overrides": {
"gsd-executor": "opus",
"gsd-codebase-mapper": "haiku"
}
}
```
유효한 값: `opus`, `sonnet`, `haiku`, `inherit`, 또는 완전히 정규화된 모델 ID (예: `"openai/o3"`, `"google/gemini-2.5-pro"`).
`model_overrides`는 `.planning/config.json`에서 프로젝트별로 설정하거나 `~/.gsd/defaults.json`에서 전역으로 설정할 수 있습니다. 충돌 시 프로젝트별 항목이 우선하며, 충돌하지 않는 전역 항목은 보존됩니다.
**Codex와 OpenCode의 중요 사항:** 이러한 런타임은 설치 시 해결된 모델을 각 에이전트의 정적 설정에 임베드합니다. `model_overrides` 편집 후 변경 사항이 적용되도록 인스톨러를 다시 실행하세요:
```bash
npx @opengsd/gsd-core@latest --codex --global # 또는 --opencode, --kilo 등
```
---
## 페이즈 유형별 모델 (`models`)
33개 에이전트 이름을 모두 알지 않고도 "기획에는 Opus, 나머지는 Sonnet"을 설정하려면 `models` 블록을 사용하세요. 여섯 가지 페이즈 유형을 티어 별칭으로 매핑합니다:
```json
{
"model_profile": "balanced",
"models": {
"planning": "opus",
"discuss": "opus",
"research": "sonnet",
"execution": "opus",
"verification": "sonnet",
"completion": "sonnet"
}
}
```
페이즈 유형과 해당 에이전트:
| 페이즈 유형 | 포함된 에이전트 |
|---|---|
| `planning` | `gsd-planner`, `gsd-roadmapper`, `gsd-pattern-mapper` |
| `research` | `gsd-phase-researcher`, `gsd-project-researcher`, `gsd-research-synthesizer`, `gsd-codebase-mapper`, `gsd-ui-researcher` |
| `execution` | `gsd-executor`, `gsd-debugger`, `gsd-doc-writer` |
| `verification` | `gsd-verifier`, `gsd-plan-checker`, `gsd-integration-checker`, `gsd-nyquist-auditor`, `gsd-ui-checker`, `gsd-ui-auditor`, `gsd-doc-verifier` |
| `discuss`, `completion` | 예약됨 — 현재 서브에이전트 없음; 향후 호환성을 위해 스키마에서 허용 |
`models` 블록은 티어 별칭만 허용합니다(`opus`, `sonnet`, `haiku`, `inherit`). 완전히 정규화된 모델 ID는 에이전트별 `model_overrides`를 사용하세요.
**`models`와 에이전트별 예외 조합:**
```json
{
"model_profile": "balanced",
"models": {
"research": "sonnet"
},
"model_overrides": {
"gsd-codebase-mapper": "haiku"
}
}
```
5개의 리서치 에이전트 모두 `sonnet`으로 해결되지만, `gsd-codebase-mapper`는 `haiku`로 고정됩니다.
---
## 동적 라우팅 — 기본 저렴하게, 실패 시 에스컬레이션
기본적으로 저렴한 티어를 사용하고 에이전트가 품질 게이트에 실패할 때만 에스컬레이션하려면 `dynamic_routing`을 활성화하세요:
```json
{
"dynamic_routing": {
"enabled": true,
"tier_models": {
"light": "haiku",
"standard": "sonnet",
"heavy": "opus"
},
"escalate_on_failure": true,
"max_escalations": 1
}
}
```
각 에이전트에는 기본 티어(`light`, `standard`, `heavy`)가 있습니다. 첫 번째 시도에서 GSD는 `tier_models[default_tier]`를 선택합니다. 오케스트레이터가 소프트 실패(검증 불확실, 플랜 체크 플래그 등)를 감지하면 한 티어 위로 에이전트를 재실행합니다. `max_escalations`는 총 재시도 횟수를 제한합니다.
이미 `heavy`에 있는 에이전트는 더 이상 에스컬레이션할 수 없습니다.
**동적 해결을 유지하면서 에스컬레이션 끄기:**
```json
{
"dynamic_routing": {
"enabled": true,
"escalate_on_failure": false
}
}
```
결과에 관계없이 모든 시도는 `tier_models[default_tier]`를 사용합니다. 에스컬레이션 동작 없이 명시적 티어-모델 매핑을 원할 때 유용합니다.
`dynamic_routing`은 **기본적으로 비활성화**됩니다. 블록을 생략하거나 `enabled: false`로 설정하면 정적 해결이 유지됩니다.
---
## 비 Anthropic 런타임에서 GSD 사용
Codex, OpenCode, Gemini CLI, 또는 Kilo용으로 GSD를 설치한 경우 인스톨러가 이미 설정에 `resolve_model_ids: "omit"`을 설정했습니다. 이는 GSD가 Anthropic 모델 ID 해결을 건너뛰고 런타임이 자체 기본 모델을 선택하도록 합니다. 기본 사용 시 수동 설정이 필요 없습니다.
**Codex에서 티어별 모델을 원하는 경우:**
```json
{
"runtime": "codex",
"model_profile": "balanced"
}
```
GSD는 각 티어 별칭을 런타임 티어 맵에 정의된 Codex 네이티브 모델 및 추론 노력으로 해결합니다.
**비 Claude 런타임에서 에이전트별 모델 ID를 원하는 경우:**
```json
{
"resolve_model_ids": "omit",
"model_overrides": {
"gsd-planner": "o3",
"gsd-executor": "o4-mini",
"gsd-debugger": "o3"
}
}
```
전체 런타임 인식 프로파일 참조 및 `model_policy` 표면(v1.42에 추가된 프로바이더 중립 프리셋)에 대해서는 [설정 참조 — 모델 프로파일](../CONFIGURATION.md#model-profiles)을 참고하세요.
---
## 해결 우선순위 (높은 것에서 낮은 것 순)
여러 레이어가 적용될 때 해결자는 가장 높은 우선순위 항목을 선택합니다:
```text
1. model_overrides[<agent>] — 에이전트별; 전체 ID; 타겟 예외
2. dynamic_routing.tier_models[<tier>] — 활성화 시; 소프트 실패 시 에스컬레이션
3. models[<phase_type>] — 거친 페이즈 레벨 티어
4. model_profile (에이전트별 열) — 전역 티어 전략
5. 런타임 기본값 — 다른 것이 적용되지 않을 때
```
---
## 올바른 방법 선택
| 원하는 것 | 사용할 것 |
|---|---|
| 모든 에이전트에 단일 티어 전략 | `model_profile` |
| 거친 페이즈 레벨 조정 ("기획에 Opus") | `models.<phase_type>` |
| 에이전트별 정밀도 ("코드베이스 매퍼에 Haiku 강제") | `model_overrides[<agent>]` |
| 특정 에이전트에 완전히 정규화된 모델 ID | `model_overrides[<agent>]: "openai/gpt-5"` |
| 기본적으로 저렴하게, 실패 시만 에스컬레이션 | `dynamic_routing` |
| 모든 에이전트가 세션 모델을 따름 (비 Anthropic 프로바이더) | `model_profile: "inherit"` |
---
## 관련 문서
- [설정 참조](../CONFIGURATION.md)
- [멀티 에이전트 오케스트레이션](../explanation/multi-agent-orchestration.md)
- [명령어 참조](../COMMANDS.md)
- [문서 목차](../README.md)

178
docs/ko-KR/how-to/debug-a-failed-execution.md Normal file
View File

@@ -0,0 +1,178 @@
# 실패한 실행을 디버그하는 방법
**목표:** 페이즈 실행이 실패하거나, 멈추거나, 불완전한 결과를 생성했을 때 — 이미 성공한 작업을 잃거나 반복하지 않고 깔끔하게 복구하고 재개합니다.
**사전 조건:** `/gsd-execute-phase N`을 실행했는데 `VERIFICATION.md` 작성 전에 실행이 중단된 경우, 또는 예상치 못한 출력, 누락된 파일, 멈춘 스피너가 보이는 경우.
---
## 실행이 멈췄는지 실패했는지 감지
복구 조치를 취하기 전에 실제로 무슨 일이 일어났는지 파악합니다.
### "Spawning…"만 표시되고 1~5분 후에도 출력이 없는 경우
이것은 정상 동작이며 멈춤이 아닙니다. GSD 서브에이전트는 격리된 컨텍스트 창에서 실행됩니다. 스폰 라인의 활성 상태 메모가 이를 확인해 줍니다. 세션을 중단하지 마세요.
10분 이상 결과가 없다면 Claude Code 사이드바를 확인하세요. 에이전트 작업이 완료된 것으로 표시되지만 출력이 나타나지 않았다면 컨텍스트 전환에서 결과가 손실되었을 수 있습니다 — 동일한 명령을 다시 실행합니다:
```bash
/gsd-execute-phase 1
```
GSD는 실행자를 디스패치하기 전에 `SUMMARY.md` 파일이 있는지 확인합니다. 이미 `SUMMARY.md`가 있는 플랜은 자동으로 건너뜁니다.
### 실행이 오류 메시지와 함께 파동 중간에 중단된 경우
git 히스토리를 확인하여 어떤 플랜이 성공적으로 커밋되었는지 확인합니다:
```bash
git log --oneline -20
```
작업을 커밋한 플랜은 `feat(01-02): …`와 같은 항목을 가집니다. 커밋이 없는 플랜은 불완전하며 재실행 시 다시 실행됩니다.
### 실행자가 코드를 커밋했지만 SUMMARY.md를 작성하지 않은 경우
GSD는 다음 실행 시 이를 감지하고 세 가지 옵션이 있는 안전 재개 게이트를 표시합니다:
- **수동으로 마무리** — 커밋을 직접 검사하고 `SUMMARY.md`를 작성한 후 재실행합니다.
- **처음부터 재실행** — 새 실행자를 디스패치하기 전에 부분 커밋을 되돌리거나 대체합니다.
- **표시 후 건너뜀** — 이상 현상을 기록하고 계속 진행하되 명시적인 확인이 필요합니다.
---
## 근본 원인 진단
### `/gsd-debug --diagnose` 실행
실행이 잘못된 출력, 스텁 코드, 또는 검증 실패를 생성한 경우 수정을 적용하지 않고 조사만 하는 진단 모드를 사용합니다:
```bash
/gsd-debug --diagnose "Phase 2 executor produced stubs instead of real code"
```
`--diagnose`는 파일을 건드리지 않고 근본 원인에서 멈춥니다. 나중에 조사를 이어갈 수 있도록 `.planning/debug/<slug>.md`에 세션 파일을 생성합니다.
수정도 적용하는 전체 디버그 세션을 시작하려면:
```bash
/gsd-debug "Login middleware not handling 401 correctly after phase 3"
```
GSD는 증상을 수집하고, 과학적 방법을 사용한 구조화된 조사를 실행하며, 수정안을 제안합니다. 설정에서 `tdd_mode: true`가 지정된 경우 수정을 적용하기 전에 실패하는 테스트를 요구합니다.
### 활성 디버그 세션 확인
```bash
/gsd-debug list
```
현재 가설과 다음 조치를 포함한 모든 열린 세션을 표시합니다. 특정 세션을 재개하려면:
```bash
/gsd-debug continue <slug>
```
---
## `/gsd-forensics`로 사후 분석 실행
오류 출력에서 원인이 명확하지 않은 경우 — 예를 들어, 플랜이 존재하지 않는 파일을 참조하거나, 실행이 예상치 못한 결과를 생성하거나, 상태가 손상된 것 같은 경우 — 포렌식 조사를 실행합니다:
```bash
/gsd-forensics "Phase 3 execution stalled after wave 1"
```
GSD는 git 히스토리, `.planning/` 아티팩트 완전성, STATE.md 일관성, 커밋되지 않은 작업, 고아 워크트리를 분석합니다. `.planning/forensics/report-<timestamp>.md`에 구조화된 보고서를 작성하고 권장 복구 단계를 제시합니다.
`/gsd-forensics`는 읽기 전용으로 프로젝트 파일을 절대 수정하지 않습니다.
**감지 항목:**
- **반복 루프** — 짧은 시간 내에 연속적으로 세 개 이상의 커밋에 동일한 파일이 나타남(커밋 메시지가 유사하면 HIGH 신뢰도)
- **누락된 아티팩트** — 페이즈에 커밋이 있지만 `SUMMARY.md`나 `VERIFICATION.md`가 없음
- **방치된 작업** — 커밋되지 않은 변경과 함께 STATE.md가 실행 중간 상태를 표시하고 마지막 커밋이 두 시간 이상 지남
- **충돌 또는 중단** — 커밋되지 않은 변경과 활성 실행 상태 및 고아 워크트리가 결합됨
- **범위 이탈** — 최근 커밋이 현재 페이즈의 예상 파일 집합 밖의 파일을 수정함
---
## 복구 후 실행 재개
근본적인 문제가 해결되면 실행 명령을 다시 실행합니다:
```bash
/gsd-execute-phase 1
```
GSD는 이미 `SUMMARY.md`가 존재하는 플랜을 건너뛰고 나머지 플랜에 대해서만 실행자를 디스패치합니다.
특정 파동만 재실행해야 하는 경우:
```bash
/gsd-execute-phase 1 --wave 2
```
디스패치하기 전에 `.planning/` 무결성을 검증하려면:
```bash
/gsd-execute-phase 1 --validate
```
---
## `/gsd-undo`로 롤백
실행이 전적으로 버리고 싶은 코드를 생성한 경우, 수동 `git revert` 대신 플랜 매니페스트를 사용하여 롤백합니다:
### 단일 플랜 롤백
```bash
/gsd-undo --plan 03-02
```
페이즈 `3`의 플랜 `02`에 대한 모든 커밋을 되돌립니다. GSD는 변경 사항을 작성하기 전에 확인 게이트를 표시합니다.
### 전체 페이즈 롤백
```bash
/gsd-undo --phase 03
```
페이즈 `3`의 모든 커밋을 되돌립니다. GSD는 이후 페이즈가 이 페이즈에 의존하는지 확인하고 진행 전에 경고합니다.
### 최근 커밋에서 대화식으로 선택
```bash
/gsd-undo --last 5
```
가장 최근 GSD 커밋 다섯 개를 표시하고 어떤 것을 되돌릴지 선택할 수 있게 합니다.
---
## 중단 후 세션 컨텍스트 복원
컨텍스트 초기화나 새 세션 후 프로젝트로 돌아온 경우:
```bash
/gsd-resume-work
```
마지막 핸드오프의 전체 세션 컨텍스트(현재 페이즈, 블로커, 실행이 중단된 위치)를 복원합니다.
또는 현재 위치를 확인하고 다음 올바른 단계로 자동 진행하려면:
```bash
/gsd-progress --next
```
---
## 관련 문서
- [페이즈 실행](execute-a-phase.md)
- [복구 및 문제 해결](recover-and-troubleshoot.md)
- [명령 참조](../COMMANDS.md)
- [문서 인덱스](../README.md)

149
docs/ko-KR/how-to/design-a-ui-phase.md Normal file
View File

@@ -0,0 +1,149 @@
# UI 페이즈를 디자인하는 방법
**목표:** 플래너가 작업을 작성하기 전에 간격, 색상, 타이포그래피, 카피라이팅 결정을 확정하는 잠긴 UI 디자인 계약(`UI-SPEC.md`)을 생성하여 실행 중 임의적인 스타일링 선택으로 인한 시각적 불일관성을 방지합니다.
**사전 조건:** `.planning/ROADMAP.md`가 존재해야 합니다. 페이즈에 프론트엔드 또는 UI 작업이 있어야 합니다. 먼저 `/gsd-discuss-phase N`을 실행하는 것을 강력히 권장합니다 — UI 연구자는 `CONTEXT.md`를 읽어 이미 결정된 사항을 다시 묻지 않습니다.
---
## 이 페이즈에 UI 계약이 필요한지 결정
모든 페이즈가 `/gsd-ui-phase`를 필요로 하지는 않습니다. 다음 경우에 사용합니다:
- 페이즈가 새로운 UI 표면(페이지, 흐름, 레이아웃)을 도입할 때
- 여러 컴포넌트를 빌드하며 시각적 일관성이 중요할 때
- 새 프로젝트의 프론트엔드를 시작하며 디자인 시스템 기준선이 필요할 때
- 기존 프로젝트에 중요한 UI 작업을 추가하면서 실행 전에 토큰, 간격, 색상을 확정하고 싶을 때
다음 경우에 건너뜁니다:
- 페이즈가 순전히 백엔드, 인프라, 또는 사용자 대면 출력이 없는 데이터 작업일 때
- 이전 페이즈에서 이미 `UI-SPEC.md`가 존재하고 이 페이즈가 새로운 표면을 도입하지 않고 동일한 시각적 패턴 위에 빌드될 때
확신이 없으면 안전 게이트가 프롬프트를 표시합니다: `workflow.ui_safety_gate`가 활성화된 경우(기본값), `/gsd-plan-phase`는 프론트엔드 작업을 감지했지만 `UI-SPEC.md`가 없을 때 경고하고 먼저 `/gsd-ui-phase`를 실행할지 물어봅니다.
---
## UI 디자인 계약 실행
```bash
/gsd-ui-phase 2
```
페이즈 번호가 지정되지 않으면 GSD Core는 현재 페이즈를 대상으로 합니다.
명령은 두 단계로 실행됩니다:
1. **`gsd-ui-researcher`** — `CONTEXT.md`, `RESEARCH.md`, `REQUIREMENTS.md`에서 기존 결정을 읽고, 디자인 시스템 상태(shadcn `components.json`, Tailwind 설정, 기존 토큰)를 감지하며, 간격, 색상, 타이포그래피, 카피라이팅, 레지스트리 안전성 다섯 영역에 걸쳐 답하지 않은 디자인 질문만 묻습니다.
2. **`gsd-ui-checker`** — 결과로 생성된 `UI-SPEC.md`를 여섯 가지 차원에서 검증합니다. 문제가 발견되면 수정 루프가 플래그된 항목만을 대상으로 연구자를 다시 실행합니다(최대 두 번 반복).
**출력:** `.planning/phases/{phase-dir}/`의 `{padded_phase}-UI-SPEC.md`.
---
## UI-SPEC의 적용 범위
연구자는 다섯 영역에 걸쳐 결정을 확정합니다:
| 영역 | 예시 |
|---|---|
| **간격** | 기본 스케일(4px 또는 8px), 그리드 정렬, 컴포넌트 패딩 |
| **색상** | 기본, 강조, 중립 팔레트; 60/30/10 규칙; 다크 모드 고려 사항 |
| **타이포그래피** | 폰트 패밀리, 크기/굵기 스케일 제약, 제목 계층 구조 |
| **카피라이팅** | CTA 레이블, 빈 상태 메시지, 오류 상태 복사, 로딩 인디케이터 |
| **레지스트리 안전성** | shadcn 컴포넌트 검사 프로토콜(아래 참조) |
체커는 6가지 기둥(각 1~4점 채점)에 대해 스펙을 검증합니다: 카피라이팅, 시각적, 색상, 타이포그래피, 간격, 경험 디자인(로딩/오류/빈 상태 커버리지).
---
## shadcn 초기화
React, Next.js, Vite 프로젝트에서 `components.json`이 없으면 연구자가 shadcn 초기화를 제안합니다. 흐름:
1. `ui.shadcn.com/create`를 방문하여 프리셋(색상, 테두리 반경, 폰트) 구성
2. 프리셋 문자열 복사
3. 실행:
```bash
npx shadcn init --preset <paste>
```
프리셋 문자열은 페이즈와 마일스톤 간에 재현 가능한 GSD Core 계획 아티팩트가 됩니다.
---
## 레지스트리 안전 게이트
서드파티 shadcn 레지스트리는 임의 코드를 주입할 수 있습니다. `workflow.ui_safety_gate`가 활성화된 경우(기본값), 스펙은 비공식 컴포넌트를 설치하기 전에 다음 단계를 요구합니다:
```bash
npx shadcn view <component> # 설치 전 소스 검사
npx shadcn diff <component> # 공식 레지스트리와 비교
```
레지스트리 안전성이 처리되지 않으면 체커가 스펙을 BLOCKED로 표시합니다. 프로젝트에서 shadcn을 사용하지 않거나 대체 검토 프로세스가 있는 경우 `/gsd-settings`를 통해 게이트를 비활성화합니다.
---
## 스케치 결과를 초안으로 활용
이미 `/gsd-sketch --wrap-up`을 실행한 경우, UI 연구자는 `.claude/skills/sketch-findings-[project]/`를 자동으로 로드합니다. 사전 검증된 결정(레이아웃, 팔레트, 타이포그래피, 간격)은 확정된 것으로 처리됩니다 — 연구자가 다시 묻지 않습니다. 실행 시작 시 메모가 표시됩니다:
```text
⚡ Sketch findings detected: .claude/skills/sketch-findings-[project]/SKILL.md
Pre-validated decisions (layout, palette, typography, spacing) should be treated
as locked — not re-asked.
```
`/gsd-ui-phase` 전에 `/gsd-sketch --wrap-up`을 실행하는 주된 이유입니다: 대화식 디자인 탐색을 계약 입력으로 바인딩합니다.
---
## `/gsd-ui-review`로 소급 시각적 감사
`/gsd-ui-review`는 실행 전이 아닌 실행 후에 실행됩니다. UI-SPEC(또는 스펙이 없을 때는 추상적인 6가지 기둥 기준)에 대해 구현된 프론트엔드를 감사하는 데 사용합니다.
```bash
/gsd-ui-review # 현재 페이즈 감사
/gsd-ui-review 3 # 특정 페이즈 3 감사
```
프론트엔드 코드가 있는 모든 프로젝트에서 작동합니다 — GSD 프로젝트 초기화가 필요하지 않습니다.
**검사 항목(6가지 기둥, 각 1~4점 채점):**
1. 카피라이팅 — CTA 레이블, 빈 상태, 오류 상태
2. 시각적 — 초점, 시각적 계층 구조, 아이콘 접근성
3. 색상 — 강조 사용 규율, 60/30/10 준수
4. 타이포그래피 — 폰트 크기와 굵기 제약 준수
5. 간격 — 그리드 정렬, 토큰 일관성
6. 경험 디자인 — 로딩, 오류, 빈 상태 커버리지
**출력:** 점수와 우선순위 상위 세 가지 수정 사항이 포함된 `{padded_phase}-UI-REVIEW.md`. `gsd-browser`와 같은 브라우저 MCP 서버가 구성된 경우 감사는 시각적 증거와 함께 스크린샷도 캡처합니다.
**스크린샷 저장:** 스크린샷은 `.planning/ui-reviews/`에 저장됩니다. 바이너리 파일이 git에 올라가지 않도록 `.gitignore`가 자동으로 생성됩니다. 스크린샷은 `/gsd-complete-milestone` 중에 정리됩니다.
---
## 페이즈 생명주기에서 권장 위치
```text
/gsd-discuss-phase N ← 구현 선호도 확정
/gsd-ui-phase N ← 디자인 계약 확정 (프론트엔드 페이즈)
/gsd-plan-phase N ← 연구 + 계획 (UI-SPEC.md를 컨텍스트로 읽음)
/gsd-execute-phase N ← 병렬 실행
/gsd-verify-work N ← 수동 UAT
/gsd-ui-review N ← 소급 시각적 감사 (선택 사항이지만 권장)
```
`/gsd-ui-phase`는 토론과 계획 사이에 위치합니다. 플래너가 `UI-SPEC.md`를 디자인 컨텍스트로 읽기 때문입니다 — `PLAN.md`의 작업은 스펙이 확정한 간격 토큰, 색상 변수, 카피라이팅 결정을 참조합니다.
---
## 관련 문서
- [스파이크와 스케치](spike-and-sketch.md)
- [페이즈 계획](plan-a-phase.md)
- [명령 참조](../COMMANDS.md)
- [문서 인덱스](../README.md)

158
docs/ko-KR/how-to/discuss-a-phase.md Normal file
View File

@@ -0,0 +1,158 @@
# 페이즈를 논의하는 방법
**목표:** 기획이 시작되기 전에 페이즈에 필요한 구현 결정을 수집합니다. 이를 통해 리서처와 플래너가 다시 질문하지 않고도 작업할 수 있습니다.
**전제 조건:** `.planning/ROADMAP.md`가 존재해야 합니다. 없다면 먼저 `/gsd-new-project`를 실행하세요.
---
## 논의 모드 선택
GSD Core는 두 가지 모드를 제공합니다. 코드베이스에 대한 이해도에 따라 선택하세요.
**구현 방향을 직접 표현하고 싶은 경우** (인터뷰 모드, 기본값):
```bash
/gsd-discuss-phase 2
```
Claude는 페이즈 범위의 모호한 영역을 파악하고, 논의할 항목을 선택하도록 안내한 후 각 영역당 약 4개의 질문을 순서대로 처리합니다.
**코드베이스에 명확한 패턴이 있고 대부분의 질문이 자명한 경우** (가정 모드):
```bash
node gsd-tools.cjs config-set workflow.discuss_mode assumptions
/gsd-discuss-phase 2
```
Claude는 서브에이전트를 통해 관련 코드베이스 파일 5~15개를 읽고, 근거와 신뢰도와 함께 가정을 형성하여 확인 또는 수정을 위해 제시합니다. 일반적으로 15~20번의 상호작용 대신 2~4번의 상호작용으로 처리됩니다.
돌아가려면:
```bash
node gsd-tools.cjs config-set workflow.discuss_mode discuss
```
각 모드의 전체 비교 및 시간을 절약할 수 있는 경우에 대해서는 [논의 모드 설명](../workflow-discuss-mode.md)을 참고하세요.
---
## 선택 단계 없이 모든 모호한 영역 논의
기본적으로 Claude는 모호한 영역을 제시하고 다룰 항목을 묻습니다. 선택 프롬프트 없이 모든 항목을 처리하려면:
```bash
/gsd-discuss-phase 2 --all
```
---
## 간단한 페이즈 빠르게 처리
**페이즈가 충분히 이해된 상태이고 Claude가 질문 없이 권장 기본값을 선택하길 원하는 경우:**
```bash
/gsd-discuss-phase 3 --auto
```
Claude는 모든 질문에 권장 답변을 선택하고 선택 사항을 기록합니다. 결정이 낮은 위험을 가지거나 이전 페이즈에 이미 암시된 페이즈에 사용하세요.
**원격 세션 제약이 있는 경우 (TUI 메뉴 없음):**
```bash
/gsd-discuss-phase 2 --text
```
모든 프롬프트가 대화형 선택기 대신 일반 텍스트 번호 목록으로 렌더링됩니다.
---
## 그룹으로 질문 처리
한 번에 하나씩이 아닌 여러 질문을 동시에 답변하고 싶다면:
```bash
/gsd-discuss-phase 2 --batch
```
Claude는 한 번에 2~5개의 질문을 묶어서 처리합니다.
---
## 각 질문에 트레이드오프 분석 추가
결정하기 전에 옵션 비교표를 원한다면:
```bash
/gsd-discuss-phase 2 --analyze
```
---
## 준비된 파일로 일괄 답변
답변 파일을 미리 준비한 경우 한 번에 모든 결정을 적용하려면:
```bash
/gsd-discuss-phase 1 --power
```
---
## 논의 전에 Claude의 가정 확인
**논의 세션에 앞서 Claude가 무엇을 가정하고 어떻게 행동할지 미리 확인하고 싶은 경우** — 논의 시간을 투자하기 전에 정렬 상태를 검증하는 데 유용합니다:
```bash
/gsd-discuss-phase 3 --assumptions
```
Claude는 가정 사항(코드베이스 근거 및 신뢰도 포함)을 출력하고 종료합니다. CONTEXT.md는 작성되지 않습니다. 출력을 검토한 후 수정이 필요한 경우 일반 논의 또는 가정 모드 세션을 실행하세요.
---
## CONTEXT.md의 내용
논의 모드와 가정 모드 모두 페이즈 디렉터리에 동일한 `{phase}-CONTEXT.md`를 생성합니다. 다운스트림 에이전트(리서처, 플래너, 플랜 체커)는 어떤 모드에서 생성했든 이 파일을 동일하게 읽습니다. 파일은 여섯 개의 섹션으로 구성됩니다:
| 섹션 | 목적 |
|---|---|
| `<domain>` | 페이즈 경계 — 이 페이즈가 무엇을 제공하는지 |
| `<decisions>` | 세션에서 확정된 구현 결정 사항 |
| `<canonical_refs>` | 다운스트림 에이전트가 반드시 읽어야 할 명세, ADR, 문서 |
| `<code_context>` | 재사용 가능한 자산, 패턴, 통합 지점 |
| `<specifics>` | 사용자 참조 및 선호 사항 |
| `<deferred>` | 향후 페이즈를 위해 기록된 아이디어 |
`<canonical_refs>` 섹션은 필수입니다. 논의 중 문서, 명세, ADR을 참조하면 Claude가 즉시 추가하고 이후 질문에 반영하기 위해 읽습니다.
전체 필드 참조는 [CONTEXT.md 스키마](../reference/context-md.md)를 참고하세요.
---
## 결정 사항이 기획에 반영되는 방식
다음에 `/gsd-plan-phase`를 실행할 때 플래너는 CONTEXT.md를 읽어 어떤 결정이 확정되었는지 파악합니다. 이미 답변된 질문은 다시 묻지 않습니다. 리서처는 무엇을 조사해야 할지 알기 위해 먼저 읽습니다.
**`/gsd-plan-phase` 실행 시 CONTEXT.md가 없는 경우**, 컨텍스트 없이 계속하거나(계획은 리서치와 요구 사항만 사용, 설계 선호도 없음) 먼저 `/gsd-discuss-phase`를 실행하는 선택지가 제공됩니다.
---
## PRD 또는 인수 기준 문서가 있는 경우
discuss-phase를 완전히 건너뛰고 바로 기획으로 이동합니다:
```bash
/gsd-plan-phase 1 --prd path/to/prd.md
```
플래너는 PRD에서 CONTEXT.md를 합성하고 모든 요구 사항을 확정된 결정으로 처리합니다.
---
## 관련 문서
- [페이즈 기획](plan-a-phase.md)
- [논의 모드](../workflow-discuss-mode.md)
- [CONTEXT.md 스키마](../reference/context-md.md)
- [문서 목차](../README.md)

176
docs/ko-KR/how-to/drive-gsd-from-a-tracker-issue.md Normal file
View File

@@ -0,0 +1,176 @@
# 트래커 이슈에서 GSD Core를 구동하는 방법
**목표:** 사용자 정의 스크립트나 트래커 통합 없이 GSD Core에 이미 존재하는 명령만으로 단일의 명확히 범위가 정해진 GitHub, Linear, 또는 Jira 이슈를 격리된 워크스페이스에서 병합된 PR까지 전체 GSD 파이프라인을 통해 진행합니다.
**사전 조건:** GSD Core가 설치되어 있어야 합니다. 이슈는 범위가 한정되고, 관찰 가능한 수락 기준이 있으며, 상위 블로커가 없어야 합니다.
이 패턴의 개념과 설계 근거는 [이슈 기반 오케스트레이션 설명](../issue-driven-orchestration.md)을 참조하세요.
---
## 1단계: 이슈를 페이즈에 매핑
트래커 이슈를 열고 `ROADMAP.md`에 어떻게 매핑되는지 결정합니다:
- **이슈가 기존 페이즈와 일치** → 페이즈 번호를 메모하고 2단계로 이동합니다.
- **이슈가 독립적인 새 작업** → 페이즈를 추가합니다:
```bash
/gsd-phase "Description matching the issue title"
```
- **이슈가 긴급하고 기존 페이즈 사이에 삽입해야 함** → 소수점 페이즈 삽입:
```bash
/gsd-phase --insert 3 "Fix: description from issue"
```
트래커 이슈 URL을 복사하세요. 3단계에서 `CONTEXT.md`에 붙여넣어 컨텍스트 압축 후에도 추적 가능성이 유지되도록 합니다.
---
## 2단계: 격리된 워크스페이스 생성
모든 이슈는 자체 워크스페이스를 가집니다 — 독립적인 `.planning/` 디렉터리가 있는 git 워크트리. 부분 작업, 중단된 플랜, 탐색적 커밋은 `main` 밖에 유지됩니다.
```bash
/gsd-workspace --new --name my-issue-slug --repos . --strategy worktree
```
계속하기 전에 워크스페이스 디렉터리로 이동합니다:
```bash
cd ~/gsd-workspaces/my-issue-slug
```
---
## 3단계: 페이즈 논의
계획이 이루어지기 전에 구현 결정을 확정하기 위해 discuss-phase를 실행합니다. 세션이 열리면 트래커 이슈 URL을 토론에 붙여넣어 `CONTEXT.md`에 캡처되도록 합니다.
```bash
/gsd-discuss-phase N
```
GSD는 이슈 범위의 모호성 — 오류 처리, 엣지 케이스, 인터페이스 계약, 기술 선택 — 에 대해 물어봅니다. 귀하의 답변이 다음에 나올 플랜을 형성합니다.
이미 모든 답을 알고 빠르게 진행하고 싶다면:
```bash
/gsd-discuss-phase N --auto
```
---
## 4단계: 페이즈 계획
```bash
/gsd-plan-phase N
```
GSD는 연구 에이전트를 스폰하고, `CONTEXT.md` 결정(이슈 URL 포함)을 읽으며, 원자적인 `PLAN.md` 파일을 생성합니다. 플랜 체커가 저장 전에 각 플랜을 검증합니다.
실행 전에 외부 AI CLI의 동료 검토를 원한다면(중요한 변경에 권장):
```bash
/gsd-review --phase N
/gsd-plan-phase N --reviews
```
또는 HIGH 우려 사항이 없을 때까지 전체 플랜-검토-수렴 루프를 실행합니다:
```bash
/gsd-plan-review-convergence N
```
---
## 5단계: 페이즈 실행
대화식, 페이즈 단위 실행:
```bash
/gsd-execute-phase N
```
모든 나머지 페이즈를 자동으로 실행:
```bash
/gsd-autonomous
```
진행 상황을 보고 페이즈 전반에 걸쳐 작업을 디스패치할 수 있는 대화식 대시보드:
```bash
/gsd-manager
```
세 가지 접근 방식 모두 `STATE.md`를 업데이트하고, 각 작업을 원자적으로 커밋하며, 페이즈 후 검증기를 실행합니다.
---
## 6단계: 작업 검증
```bash
/gsd-verify-work N
```
GSD는 페이즈 목표(트래커 이슈를 반영)의 수락 기준을 하나씩 안내합니다. 무언가 실패하면 GSD가 근본 원인을 진단하고 수정 플랜을 만듭니다. 모든 검사가 통과될 때까지 실행과 검증을 반복합니다.
코드가 올바르게 보여도 `verification_failed`를 블로커로 취급하세요 — 실패는 보통 원래 이슈에서 놓친 수락 기준을 드러냅니다.
---
## 7단계: 검토 및 출시
PR을 열기 전에 코드 검토를 실행합니다:
```bash
/gsd-code-review N
/gsd-code-review N --fix
```
그다음 PR을 생성합니다:
```bash
/gsd-ship N
```
GSD는 계획 아티팩트에서 PR 본문을 조립합니다: 페이즈 목표, 변경 사항 요약, 충족된 요구 사항, 검증 상태, 주요 결정. PR이 병합될 때 트래커 이슈가 자동으로 닫히도록 PR 본문에 `Closes #NNN` 또는 `Fixes #NNN`을 포함하세요(또는 `/gsd-config`를 통해 설정).
---
## 8단계: 후속 작업 캡처
이슈 작업 중 관련 작업을 자주 발견하게 됩니다. 컨텍스트를 잃지 않고 캡처합니다:
```bash
/gsd-capture "Follow-up: description of discovered work" # 할 일로 추가
/gsd-capture --seed "Idea worth a future phase" # 다음 마일스톤을 위해 보존
/gsd-capture --backlog "Not urgent but worth tracking" # 백로그에 저장
```
GSD는 트래커에 자동으로 게시하지 않습니다. 캡처된 후속 작업에서 트래커 이슈를 생성하는 것은 별도의 수동 단계입니다 — 이는 검토 루프에 사람이 참여하도록 유지합니다.
---
## 조건부 처리
| 상황 | 할 일 |
|-----------|-----------|
| 이슈가 매우 작음(오타, 설정 변경) | 워크스페이스 + 논의 + 계획 건너뜀; 대신 `/gsd-quick` 사용 |
| 이슈에 여러 독립적인 하위 작업이 있음 | `/gsd-manager`를 사용하여 플랜 전반에 걸쳐 실행 병렬화 |
| 이슈가 다른 이슈에 의해 차단됨 | 상위 블로커가 해결될 때까지 시작하지 않음; GSD에는 자동 의존성 폴러가 없음 |
| 실행 중간에 이슈 범위가 예상보다 큰 것으로 드러남 | 중단하고, `/gsd-phase --insert N`을 실행하여 하위 페이즈 추가 후 계속 |
| 대화식 논의를 건너뛰고 싶음 | `/gsd-discuss-phase`와 함께 `--auto` 플래그 사용, 또는 프로젝트 전체 자동화를 위해 `workflow.skip_discuss: true` 설정 |
| 여러 이슈가 일관된 릴리즈를 형성 | `/gsd-new-milestone`으로 그룹화하고 `/gsd-autonomous`로 순서대로 실행 |
---
## 관련 문서
- [이슈 기반 오케스트레이션 설명](../issue-driven-orchestration.md)
- [워크스페이스로 작업 격리](isolate-work-with-workspaces.md)
- [검증 및 출시](verify-and-ship.md)
- [문서 인덱스](../README.md)

119
docs/ko-KR/how-to/execute-a-phase.md Normal file
View File

@@ -0,0 +1,119 @@
# 페이즈를 실행하는 방법
**목표:** 기획된 페이즈를 웨이브 기반 병렬 실행으로 처리하고 각 계획을 원자적 git 커밋으로 완료합니다.
**전제 조건:** 페이즈에 최소 하나의 `PLAN.md` 파일이 있어야 합니다. 기획이 아직 완료되지 않았다면 먼저 `/gsd-plan-phase N`을 실행하세요 — [페이즈 기획](plan-a-phase.md)을 참고하세요.
---
## 전체 페이즈 실행
```bash
/gsd-execute-phase 1
```
GSD는 페이즈의 계획 파일을 읽고 의존성 웨이브로 그룹화한 후 계획당 새 실행자 에이전트를 실행합니다. 각 실행자는 다음 웨이브가 시작되기 전에 작업을 원자적으로 커밋합니다.
에이전트가 실행되기 전에 GSD는 웨이브 테이블을 출력합니다:
```
## Execution Plan
Phase 1: Core middleware — 3 plans across 2 wave(s)
| Wave | Plans | What it builds |
|------|----------------|---------------------------|
| 1 | 01-01, 01-02 | Core validation function |
| 2 | 01-03 | Express middleware wrapper |
```
웨이브 1 계획은 병렬로 실행됩니다(각각 독립된 git 워크트리에서). 웨이브 2는 모든 웨이브 1 커밋이 병합될 때까지 기다립니다.
기본 에이전트 조정 모델에 대해서는 [멀티 에이전트 오케스트레이션](../explanation/multi-agent-orchestration.md)을 참고하세요.
---
## 단일 웨이브 실행
예를 들어 웨이브 2로 넘어가기 전 웨이브 1 출력을 검사하고 싶은 경우 `--wave N`을 사용하세요:
```bash
/gsd-execute-phase 1 --wave 2
```
GSD는 웨이브 2 계획만 실행합니다. 먼저 이전 웨이브가 완료되었는지 확인하며, 웨이브 1 계획이 아직 미완료인 경우 이전 웨이브를 먼저 완료하도록 알립니다.
---
## 실행 전 상태 검증
충돌이나 이전 실행이 중단된 후 `.planning/` 디렉터리가 파일 시스템과 동기화되지 않았을 것으로 의심되는 경우 `--validate`를 사용하세요:
```bash
/gsd-execute-phase 1 --validate
```
GSD는 실행자를 실행하기 전에 상태 일관성 검사를 실행합니다. 감지된 드리프트가 보고되며 진행 전에 수락하거나 수정할 수 있습니다.
---
## 중단된 실행 재개
실행이 도중에 중단된 경우(할당량 오류, 네트워크 끊김, 세션 충돌 등) 웨이브 레벨 진행 상황은 보존됩니다. GSD는 각 계획의 `SUMMARY.md` 파일을 확인합니다. 이미 파일이 있는 계획은 재실행 시 자동으로 건너뜁니다:
```bash
/gsd-execute-phase 1
```
GSD는 `SUMMARY.md`가 이미 존재하는 계획을 건너뛰고 첫 번째 미완료 계획에서 재개합니다.
**커밋은 존재하지만 `SUMMARY.md`가 없는 경우**(실행자가 커밋했지만 세션이 종료되기 전 요약을 작성하지 못한 경우), GSD는 안전 재개 게이트를 표시하고 세 가지 옵션을 제공합니다:
- `수동으로 마무리` — 커밋을 검사하고 `SUMMARY.md`를 작성한 후 재실행
- `처음부터 재실행` — 부분 커밋을 되돌리거나 대체한 후 새 실행자 실행
- `표시하고 건너뛰기` — 명시적 확인 하에 이상을 기록하고 진행
체계적인 실패 진단에 대해서는 [실패한 실행 디버그](debug-a-failed-execution.md)를 참고하세요.
---
## 출력 위치
모든 웨이브가 완료되면 페이즈 디렉터리에 다음이 포함됩니다:
```
.planning/phases/01-<name>/
01-01-SUMMARY.md # 계획 01이 구축한 것, 핵심 파일, 편차
01-02-SUMMARY.md
01-03-SUMMARY.md
VERIFICATION.md # 요구 사항별 통과/실패 상태
```
`STATE.md`와 `ROADMAP.md`는 모든 웨이브가 완료되면 자동으로 업데이트됩니다. `VERIFICATION.md`는 페이즈가 완전히 완료된 경우에만 작성됩니다.
Git 히스토리에는 각 실행자의 태스크당 커밋 하나와 오케스트레이터의 추적 커밋이 표시됩니다.
---
## 크로스 AI 실행
`workflow.cross_ai_command`에 설정된 외부 AI CLI(Codex, Gemini 등)에 실행을 위임하려면:
```bash
/gsd-execute-phase 2 --cross-ai
```
설정에 크로스 AI가 활성화된 경우에도 로컬 실행을 강제하려면:
```bash
/gsd-execute-phase 2 --no-cross-ai
```
---
## 관련 문서
- [페이즈 기획](plan-a-phase.md)
- [검증 및 배포](verify-and-ship.md)
- [실패한 실행 디버그](debug-a-failed-execution.md)
- [명령어 참조](../COMMANDS.md)

121
docs/ko-KR/how-to/handle-quick-and-fast-tasks.md Normal file
View File

@@ -0,0 +1,121 @@
# 빠른 작업과 간단한 작업을 처리하는 방법
모든 작업이 페이즈 안에 맞는 것은 아닙니다. GSD는 전체 discuss → plan → execute → verify 루프가 필요 없는 작업을 위한 두 가지 경량 명령을 제공합니다.
전체 페이즈 파이프라인이 오버헤드를 감당할 가치가 있는 경우에 대한 맥락은 [컨텍스트 엔지니어링](../explanation/context-engineering.md)을 참고하세요.
---
## 어떤 명령을 사용할지 결정
| 상황 | 명령 |
|-----------|---------|
| 버그 수정, 소규모 기능 추가, 또는 단일 사소한 수정으로 요약할 수 없는 작업 | `/gsd-quick` |
| 오타 수정, 설정 값 업데이트, `.gitignore` 항목 추가, 또는 ≤ 3개 파일을 터치하고 1분 이내에 완료되는 변경 | `/gsd-fast` |
| 작업에 미지수가 있거나 리서치가 필요하거나 여러 파일을 터치할 경우 | `--research`와 함께 `/gsd-quick` |
**경험 법칙:** 작업이 사소한지에 대해 잠시라도 망설인다면 `/gsd-quick`을 사용하세요. `/gsd-fast`는 범위가 사소하지 않아 보이면 자동으로 `/gsd-quick`으로 리디렉션합니다.
---
## `/gsd-quick` — GSD 보장이 있는 임시 작업
`/gsd-quick`은 전체 페이즈와 동일한 원자적 커밋 및 STATE.md 추적 보장으로 플래너와 실행자를 실행하지만, 페이즈 오버헤드 없이 진행합니다(ROADMAP 항목 없음, discuss-phase 없음, 여러 계획에 걸친 웨이브 조정 없음).
### 기본 사용
```bash
/gsd-quick
```
GSD가 태스크 설명을 묻고 계획 및 실행합니다. 산출물은 `.planning/quick/`에 저장됩니다.
설명을 직접 전달할 수도 있습니다:
```bash
/gsd-quick "Fix the login button not responding on mobile Safari"
```
### 플래그
작업에 필요한 경우 더 많은 품질 파이프라인을 추가하는 플래그를 사용하세요.
| 플래그 | 추가되는 것 |
|------|-------------|
| `--discuss` | 플래너 실행 전 모호한 영역을 표시하고 결정을 `CONTEXT.md`에 캡처하는 경량 사전 기획 논의 |
| `--research` | 집중된 리서치 에이전트가 기획 전에 접근법, 라이브러리, 함정을 조사함 |
| `--validate` | 플랜 체킹(최대 2회 반복) 및 실행 후 검증 |
| `--full` | 위의 모든 것 — `--discuss --research --validate`와 동일 |
플래그는 자유롭게 조합할 수 있습니다:
```bash
/gsd-quick --research --validate # 리서치 + 플랜 체킹 + 검증, 논의 없음
/gsd-quick --discuss # 기획 전 모호한 영역만 표시
/gsd-quick --full # 전체 품질 파이프라인
```
### 플래그 추가 시기
- 작업에 어떻게 접근할지 또는 어떤 라이브러리를 사용할지 확실하지 않을 때 `--research` 추가
- 작업이 중요한 코드 경로를 터치하고 검증자 에이전트가 must-haves를 충족했는지 확인하기를 원할 때 `--validate` 추가
- 작업에 플래너 실행 전 확정하고 싶은 설계 선택이 있을 때 `--discuss` 추가(예: 올바른 오류 처리 동작이 명확하지 않을 때)
- 태스크가 실제로 중요하고 페이즈로 기획하겠지만 ROADMAP에 속하지 않을 때 `--full` 사용
### 빠른 작업 목록 및 재개
```bash
/gsd-quick list # 상태별 모든 빠른 작업 표시
/gsd-quick status my-task-slug # 특정 작업 상태 표시
/gsd-quick resume my-task-slug # 중단된 작업 재개
```
---
## `/gsd-fast` — 인라인 사소한 편집
`/gsd-fast`는 현재 컨텍스트에서 직접 작업을 수행합니다. 서브에이전트, `PLAN.md`, 리서치가 없습니다. 스스로 1분 이내에 할 수 있는 변경에만 적합합니다.
```bash
/gsd-fast "fix typo in README"
/gsd-fast "add .env to .gitignore"
```
설명을 생략하면 GSD가 묻습니다.
`/gsd-fast`는 진행 전에 작업이 실제로 사소한지 확인합니다. 범위가 너무 크다고 판단하면 중단하고 리디렉션합니다:
```text
This looks like it needs planning. Use /gsd-quick instead:
/gsd-quick "your task description"
```
변경 후 `/gsd-fast`는 원자적으로 커밋하고, `.planning/STATE.md`에 `Quick Tasks Completed` 테이블이 있으면 행을 추가합니다.
---
## `/gsd-quick`이 `/gsd-fast`와 다른 점
| 기능 | `/gsd-fast` | `/gsd-quick` |
|------------|------------|--------------|
| 서브에이전트 플래너 | 없음 | 있음 |
| 서브에이전트 실행자 | 없음 | 있음 |
| 리서치 에이전트 | 없음 | 선택 사항 (`--research`) |
| 플랜 체킹 | 없음 | 선택 사항 (`--validate`) |
| 실행 후 검증 | 없음 | 선택 사항 (`--validate`) |
| 논의 단계 | 없음 | 선택 사항 (`--discuss`) |
| 워크트리 격리 | 없음 | 있음 (기본값) |
| 태스크당 원자적 커밋 | 단일 커밋 | 계획 태스크당 하나 |
| STATE.md 추적 | 테이블이 있으면 행 추가 | 항상 업데이트됨 |
| `.planning/quick/` 산출물 | 없음 | 있음 |
핵심 차이는 서브에이전트 격리입니다. `/gsd-quick`은 별도의 컨텍스트 창에서 새 플래너와 실행자를 실행하므로 작업이 적절히 기획되고 커밋이 태스크당 원자적이며 오케스트레이터가 결과를 검증할 수 있습니다. `/gsd-fast`는 현재 컨텍스트 창만 사용하며 이러한 것이 필요하지 않을 만큼 사소한 변경에 의도적으로 제한됩니다.
---
## 관련 문서
- [페이즈 루프](../explanation/the-phase-loop.md)
- [컨텍스트 엔지니어링](../explanation/context-engineering.md)
- [명령어 참조](../COMMANDS.md)
- [문서 목차](../README.md)

291
docs/ko-KR/how-to/install-on-your-runtime.md Normal file
View File

@@ -0,0 +1,291 @@
# GSD Core를 런타임에 설치하는 방법
GSD Core(`@opengsd/gsd-core`)를 매일 사용하는 AI 코딩 런타임에 설치합니다. 이 가이드는 지원되는 각 런타임의 표준 설치 경로를 안내하고, Node.js가 없는 환경에서의 수동 설치 방법도 다룹니다.
**필요 사항:** Node.js 18 이상 및 npm(또는 npx). Node.js가 없는 경우 [Node.js 없이 설치하기](#nodejs-없이-설치하기)로 이동하세요.
---
## 인스톨러가 필요한 이유
GSD Core는 Claude Code의 네이티브 frontmatter 형식으로 에이전트 및 명령 파일을 제공합니다. 각 지원 런타임은 서로 다른 스키마, 디렉터리 구조, 명령 호출 문법을 요구합니다. 인스톨러는 필요한 변환을 수행합니다. 예를 들어 OpenCode용 도구 목록 및 색상 값 변환, Codex용 TOML 에이전트 항목 작성, Gemini CLI용 모든 명령 본문을 하이픈 형식(`/gsd-update`)에서 콜론 형식(`/gsd:update`)으로 재작성합니다.
**`agents/` 또는 `commands/`에서 파일을 직접 복사하지 마세요.** 그렇게 하면 변환을 우회하게 되어 스키마 유효성 검사 오류나 누락된 명령이 발생합니다.
---
## 표준 설치
임의의 디렉터리에서 인스톨러를 실행합니다. 런타임과 전역 설치(모든 프로젝트) 또는 로컬 설치(이 프로젝트만) 여부를 묻습니다.
```bash
npx @opengsd/gsd-core@latest
```
신규 설치 또는 런타임 전환 후 인스톨러를 재실행할 때 필요한 명령은 이것뿐입니다.
---
## 런타임별 설치 방법
### Claude Code
```bash
npx @opengsd/gsd-core@latest --claude --global
```
스킬은 `~/.claude/`에 저장됩니다. 다음 Claude Code 세션에서 `/gsd-*` 슬래시 명령으로 명령이 나타납니다. Claude Code를 재시작하여 적용하세요.
**설치 디렉터리 재정의:**
```bash
CLAUDE_CONFIG_DIR=~/.claude-alt npx @opengsd/gsd-core@latest --claude --global
```
---
### Gemini CLI
```bash
npx @opengsd/gsd-core@latest --gemini --global
```
스킬은 `~/.gemini/`에 저장됩니다. 인스톨러는 모든 명령 본문을 Gemini의 콜론 네임스페이스(`/gsd:update`, `/gsd:config` 등)로 재작성합니다. 설치 후 Gemini CLI를 재시작하세요.
**설치 디렉터리 재정의:**
```bash
GEMINI_CONFIG_DIR=~/.gemini-alt npx @opengsd/gsd-core@latest --gemini --global
```
---
### OpenCode
```bash
npx @opengsd/gsd-core@latest --opencode --global
```
스킬은 `~/.config/opencode/`(XDG) 또는 `~/.opencode/`에 저장됩니다. 인스톨러는 에이전트 frontmatter를 OpenCode 스키마로 변환합니다(`tools:` 필드 제거, 색상 값을 hex로 변환). 변경 내용을 이해하려면 [Node.js 없이 설치하기 — OpenCode 변환](#opencode--필수-변환)을 참고하세요.
**설치 디렉터리 재정의:**
```bash
OPENCODE_CONFIG_DIR=~/.config/opencode-alt npx @opengsd/gsd-core@latest --opencode --global
```
---
### Kilo
```bash
npx @opengsd/gsd-core@latest --kilo --global
```
스킬은 `~/.config/kilo/`(XDG) 또는 `~/.kilo/`에 저장됩니다. OpenCode 스타일의 플랫 마크다운 명령 형식을 사용합니다.
**설치 디렉터리 재정의:**
```bash
KILO_CONFIG_DIR=~/.config/kilo-alt npx @opengsd/gsd-core@latest --kilo --global
```
---
### Codex
```bash
npx @opengsd/gsd-core@latest --codex --global
```
스킬은 `~/.codex/skills/gsd-*/SKILL.md`에 저장됩니다. 에이전트는 `config.toml`에 에이전트별 TOML 항목으로 작성됩니다. 설치 후 Codex를 재시작하거나 `codex --reload`를 실행하세요.
**최소 지원 버전:** Codex CLI 0.130.0. 이전 버전은 추가 스킬 루트 스캔으로 중복 목록이 발생할 수 있습니다.
---
### GitHub Copilot
```bash
npx @opengsd/gsd-core@latest --copilot --global
```
스킬은 `~/.copilot/`에 저장됩니다. GSD는 에이전트 `.md` 파일 및 저장소 지시 파일로 설치됩니다.
**설치 디렉터리 재정의:**
```bash
COPILOT_CONFIG_DIR=~/.copilot-alt npx @opengsd/gsd-core@latest --copilot --global
```
---
### Cursor
```bash
npx @opengsd/gsd-core@latest --cursor --global
```
스킬은 `~/.cursor/`에 저장됩니다. GSD는 스킬, 에이전트, 규칙 참조를 설치합니다.
**설치 디렉터리 재정의:**
```bash
CURSOR_CONFIG_DIR=~/.cursor-alt npx @opengsd/gsd-core@latest --cursor --global
```
---
### Windsurf
```bash
npx @opengsd/gsd-core@latest --windsurf --global
```
스킬은 `~/.codeium/windsurf/`에 저장됩니다. GSD는 스킬, 에이전트, 워크스페이스 규칙을 설치합니다.
**설치 디렉터리 재정의:**
```bash
WINDSURF_CONFIG_DIR=~/.codeium/windsurf-alt npx @opengsd/gsd-core@latest --windsurf --global
```
---
### Cline
Cline은 규칙 기반 통합을 사용합니다. GSD는 슬래시 명령이 아닌 `.clinerules`로 설치됩니다.
```bash
# 전역 설치 (모든 프로젝트)
npx @opengsd/gsd-core@latest --cline --global
# 로컬 설치 (이 프로젝트만)
npx @opengsd/gsd-core@latest --cline --local
```
전역 설치는 `~/.cline/`에 저장됩니다. 로컬 설치는 `./.cline/`에 저장됩니다. 규칙은 Cline에 의해 자동으로 로드되며 커스텀 슬래시 명령은 등록되지 않습니다.
---
### CodeBuddy
```bash
npx @opengsd/gsd-core@latest --codebuddy --global
```
스킬은 `~/.codebuddy/skills/gsd-*/SKILL.md`에 저장됩니다.
---
### Qwen Code
Qwen Code는 Claude Code 2.1.88+와 동일한 오픈 스킬 표준을 사용합니다.
```bash
npx @opengsd/gsd-core@latest --qwen --global
```
스킬은 `~/.qwen/skills/gsd-*/SKILL.md`에 저장됩니다.
**설치 디렉터리 재정의:**
```bash
QWEN_CONFIG_DIR=~/.qwen-alt npx @opengsd/gsd-core@latest --qwen --global
```
---
### Augment Code
```bash
npx @opengsd/gsd-core@latest --augment --global
```
스킬은 `~/.augment/`에 저장됩니다. GSD는 스킬과 에이전트를 설치합니다. 훅 또는 상태 표시줄 소유권은 없습니다.
---
### Antigravity
```bash
npx @opengsd/gsd-core@latest --antigravity --global
```
인스톨러는 Antigravity 설정 디렉터리(`~/.gemini/antigravity`, `~/.gemini/antigravity-ide`, 또는 `~/.gemini/antigravity-cli`)를 자동으로 감지합니다. Gemini 호환 설정 정책을 사용합니다.
**설치 디렉터리 재정의:**
```bash
ANTIGRAVITY_CONFIG_DIR=~/.gemini/antigravity-alt npx @opengsd/gsd-core@latest --antigravity --global
```
---
### Trae
```bash
npx @opengsd/gsd-core@latest --trae --global
```
스킬은 `~/.trae/`에 저장됩니다. GSD는 스킬, 에이전트, 규칙 참조를 설치합니다.
---
## 로컬 설치 vs 전역 설치
위의 모든 예시는 사용자 계정 전체에 GSD를 한 번 설치하는 `--global`을 사용합니다. 단일 프로젝트로 범위를 제한하려면 `--global`을 `--local`로 바꾸세요:
```bash
npx @opengsd/gsd-core@latest --claude --local
```
로컬 설치는 프로젝트 루트의 `.claude/` 디렉터리에 작성됩니다. 둘 다 존재하는 경우 로컬 설치 설정이 전역 설정보다 우선합니다.
---
## 프리릴리스 에디션 설치 (Next / Nightly / Insiders / Preview)
런타임의 프리릴리스 에디션(Windsurf Next, Cursor Nightly, VS Code Insiders, Codex 프리뷰 채널 등)은 인접한 설정 디렉터리에서 읽습니다. 인스톨러 실행 전에 해당하는 `*_CONFIG_DIR` 환경 변수를 설정하세요:
```bash
WINDSURF_CONFIG_DIR=~/.codeium/windsurf-next npx @opengsd/gsd-core@latest --windsurf --global
```
인스톨러 프롬프트에서 해당하는 안정적인 런타임을 선택하세요. GSD는 프리릴리스 에디션을 별도의 명명된 런타임으로 열거하지 않습니다. 이 환경 변수 메커니즘을 통한 지원은 최선의 방식이며 릴리스 CI에서 별도로 테스트되지 않습니다.
---
## Node.js 없이 설치하기
`npx`를 실행할 수 없는 경우(예: Node.js가 없는 Windows 환경), 두 가지 옵션이 있습니다.
**옵션 A — Node.js가 있는 다른 머신 사용.** WSL, Linux VM, CI 러너, Docker 컨테이너 등 Node.js가 있는 어떤 머신이든 사용 가능합니다. 그곳에서 인스톨러를 실행한 후 출력 디렉터리를 대상 머신으로 복사하세요. OpenCode의 경우:
```bash
npx @opengsd/gsd-core@latest --opencode --global
# 그 다음 ~/.config/opencode/agents/ 를 Windows 머신으로 복사
```
**옵션 B — 소스 파일 수동 변환.** 에이전트 소스 파일은 GSD Core 저장소의 `agents/`에 있으며 Claude Code의 네이티브 frontmatter 형식입니다. 각 런타임은 다른 구조를 요구합니다. 런타임별 정확한 필드 변환에 대해서는 사용자 가이드의 [수동 설치 / Node.js 없는 설정](../USER-GUIDE.md#manual-install--no-nodejs-setup)을 참고하세요. OpenCode 변환 전체를 다루며 다른 런타임용 인스톨러의 `convert*Frontmatter` 함수를 안내합니다.
---
## 설치 후
새 명령과 에이전트를 적용하려면 런타임을 재시작하세요. 그런 다음 첫 번째 프로젝트를 시작합니다:
```bash
/gsd-new-project
```
재시작 후 명령을 찾을 수 없다면 설치 디렉터리가 런타임이 기대하는 설정 경로와 일치하는지 확인하세요. 위의 프리릴리스 에디션 섹션에서 가장 흔한 불일치 사례를 다룹니다.
---
## 관련 문서
- [첫 번째 프로젝트](../tutorials/your-first-project.md)
- [GSD Core 업데이트](update-gsd.md)
- [설정](../CONFIGURATION.md)
- [문서 목차](../README.md)

144
docs/ko-KR/how-to/isolate-work-with-workspaces.md Normal file
View File

@@ -0,0 +1,144 @@
# 워크스페이스로 작업을 격리하는 방법
**목표:** 피처 브랜치나 멀티 저장소 작업을 위해 별도의 git 워크트리, 독립적인 `.planning/` 루트, 그리고 선택적으로 여러 저장소를 포함하는 완전히 격리된 GSD 환경을 만듭니다.
**사전 조건:** `git`이 설치되어 있고 저장소가 워크트리를 지원해야 합니다. 멀티 저장소 워크스페이스의 경우 대상 저장소가 로컬 머신에 존재하거나 경로로 접근 가능해야 합니다.
---
## 워크스페이스란
워크스페이스는 하나 이상의 git 워크트리(또는 클론)와 자체 `.planning/` 루트 디렉터리를 결합한 자급자족 환경입니다. 각 워크스페이스에는 다음이 포함됩니다:
- 소스 저장소의 `.planning/`으로부터 **완전히 독립적인** 자체 `.planning/` 디렉터리 — 그 하위 디렉터리가 아님
- 멤버 저장소를 추적하는 자체 `WORKSPACE.md` 매니페스트
- 지정된 저장소의 git 워크트리(기본값) 또는 전체 클론이며 전용 브랜치(기본값: `workspace/<name>`)로 체크아웃됨
워크스페이스는 기본적으로 `~/gsd-workspaces/<name>/` 아래에 위치합니다.
```
~/gsd-workspaces/
└── feature-b/
├── WORKSPACE.md ← 매니페스트
├── .planning/ ← 완전히 독립된 GSD 상태
│ ├── PROJECT.md
│ ├── ROADMAP.md
│ └── ...
├── hr-ui/ ← hr-ui 저장소의 워크트리 또는 클론
└── ZeymoAPI/ ← ZeymoAPI 저장소의 워크트리 또는 클론
```
워크스페이스의 `.planning/`이 소스 저장소와 분리되어 있으므로 소스 저장소에 존재하는 계획 상태와 충돌이나 겹침이 없습니다.
---
## 여러 저장소에 대한 워크스페이스 생성
```bash
/gsd-workspace --new --name feature-b --repos hr-ui,ZeymoAPI
```
GSD는 `~/gsd-workspaces/feature-b/` 내에 `hr-ui`와 `ZeymoAPI`의 워크트리를 생성하고, 각각에서 `workspace/feature-b` 브랜치를 체크아웃하며, `WORKSPACE.md`를 작성하고 `/gsd-new-project`를 위한 빈 `.planning/` 디렉터리를 생성합니다.
위치를 사용자 정의하려면:
```bash
/gsd-workspace --new --name feature-b --repos hr-ui,ZeymoAPI --path /projects/feature-b
```
---
## 현재 저장소에 대한 워크스페이스 생성
단일 저장소에서 피처 브랜치 격리가 필요할 때 — 독립적인 브랜치, 독립적인 `.planning/`, 메인에서의 상태 유입 없음:
```bash
/gsd-workspace --new --name payments-rework --repos .
```
`.`은 GSD에게 현재 저장소의 워크트리를 생성하도록 지시합니다. 워크트리는 `workspace/payments-rework`로 체크아웃됩니다.
워크트리 대신 전체 클론을 강제하려면:
```bash
/gsd-workspace --new --name payments-rework --repos . --strategy clone
```
---
## 브랜치 명시적 지정
```bash
/gsd-workspace --new --name payments-rework --repos . --branch feature/payments-v2
```
`--branch` 플래그는 워크스페이스의 모든 저장소에 대한 브랜치 이름을 설정합니다. 기본값은 `workspace/<name>`입니다.
---
## 대화형 질문 건너뛰기
```bash
/gsd-workspace --new --name payments-rework --repos . --auto
```
GSD는 프롬프트 없이 모든 기본값을 수락합니다.
---
## 워크스페이스 내에서 GSD 초기화
워크스페이스를 생성한 후 그 안으로 이동하고 GSD 프로젝트를 초기화합니다:
```bash
cd ~/gsd-workspaces/feature-b
/gsd-new-project
```
워크스페이스 내의 `.planning/` 디렉터리가 해당 디렉터리에서 실행되는 모든 후속 GSD 명령의 루트입니다. 이것은 소스 저장소에 존재하는 어떠한 `.planning/`과도 완전히 분리되어 있습니다.
---
## 워크스페이스 목록 보기
```bash
/gsd-workspace --list
```
모든 활성 GSD 워크스페이스와 상태를 출력합니다.
---
## 워크스페이스 제거
```bash
/gsd-workspace --remove feature-b
```
GSD는 git 워크트리를 제거하고 워크스페이스 디렉터리를 정리합니다. 이 작업은 원격 저장소에서 브랜치를 삭제하지 않으며 로컬 워크트리와 워크스페이스 디렉터리만 제거합니다.
---
## 워크스트림 대신 워크스페이스를 선택할 때
워크스페이스를 선택할 때:
- **여러 저장소**(예: API 저장소와 함께 출시되는 UI 저장소)를 하나의 GSD 프로젝트 아래서 조율해야 할 때
- 피처별로 자체 브랜치, 잠금 파일, 빌드 아티팩트를 가진 **별도의 git 워크트리**가 필요할 때 — 한 환경에서의 빌드와 의존성 설치가 다른 환경에 영향을 주지 않도록
- 메인 저장소의 `.planning/` 하위 디렉터리가 아닌 **완전히 독립적인 `.planning/` 루트**를 원할 때
- 각 트래커 이슈가 워크스페이스에 매핑되는 이슈 기반 워크플로를 따를 때([트래커 이슈에서 GSD 구동](drive-gsd-from-a-tracker-issue.md) 참조)
[워크스트림](work-in-parallel-with-workstreams.md)을 선택할 때:
- 모든 작업이 **하나의 저장소**에 있고 같은 git 히스토리를 공유할 때
- 서로의 `STATE.md` 파일 간의 컨텍스트 유입 없이 서로 다른 관심 영역(API, UI, 인프라)에 대해 동시에 `/gsd-plan-phase` 또는 `/gsd-discuss-phase`를 실행하고 싶을 때
- 관심사별로 별도의 워크트리가 필요하지 않고 계획 컨텍스트 전환으로 충분할 때
---
## 관련 문서
- [워크스트림으로 병렬 작업](work-in-parallel-with-workstreams.md)
- [트래커 이슈에서 GSD 구동](drive-gsd-from-a-tracker-issue.md)
- [명령 참조](../COMMANDS.md)
- [문서 인덱스](../README.md)

145
docs/ko-KR/how-to/migrate-from-gsd-2.md Normal file
View File

@@ -0,0 +1,145 @@
# GSD-2에서 마이그레이션하는 방법
**목표:** 이전 GSD-2 프로젝트(`.gsd/` 디렉터리 레이아웃)를 GSD Core(`.planning/` 레이아웃)로 이전하고, 선택적으로 저장소에 있는 기존 ADR, PRD, 또는 스펙 문서를 새 계획 구조에 통합합니다.
**사전 조건:** GSD Core가 설치되어 있어야 합니다. GSD-2 프로젝트 디렉터리가 디스크에 있어야 합니다.
---
## 마이그레이션 대상 이해
GSD-2는 `.gsd/` 디렉터리를 계획 루트로 사용했습니다. GSD Core는 `.planning/`을 사용합니다. 마이그레이션은 이를 역전합니다: `.gsd/` 아티팩트를 읽고 모든 GSD Core 명령이 기대하는 표준 `.planning/` 구조로 작성합니다.
| GSD-2에 존재하는 것 | `/gsd-import --from-gsd2`가 생성하는 것 |
|----------------------|-----------------------------------------|
| `.gsd/PROJECT.md` | `.planning/PROJECT.md` |
| `.gsd/ROADMAP.md` | `.planning/ROADMAP.md` |
| `.gsd/STATE.md` | `.planning/STATE.md` |
| `.gsd/phases/` 디렉터리 | `.planning/phases/` 디렉터리 |
| 페이즈 `PLAN.md` 파일 | GSD Core `{NN}-{MM}-PLAN.md` 파일 (이름 변경 적용) |
충돌 감지는 파일이 작성되기 전에 실행됩니다. 대상 디렉터리에 이미 `PROJECT.md`가 있고 가져오는 콘텐츠와 모순되면 마이그레이션은 BLOCKER 게이트에서 중단하고 해결할 충돌 목록을 표시합니다.
---
## 마이그레이션 실행
### 현재 디렉터리 마이그레이션
```bash
/gsd-import --from-gsd2
```
GSD는 현재 작업 디렉터리의 `.gsd/`를 읽고 마이그레이션된 아티팩트를 `.planning/`에 작성합니다.
### 다른 경로에서 마이그레이션
```bash
/gsd-import --from-gsd2 --path ~/projects/old-project
```
GSD-2 프로젝트가 현재 작업 디렉터리가 아닌 경우 `--path`를 사용합니다.
---
## 충돌 해결
충돌 감지에서 블로커가 발견되면 — 예를 들어, 기존 `.planning/PROJECT.md`와 모순되는 GSD-2 기술 스택 선언 — 충돌 보고서를 출력하고 파일을 작성하지 않고 중단합니다.
보고서를 읽고 모순을 해결한 후(소스 문서 또는 기존 계획 아티팩트 편집), `/gsd-import --from-gsd2`를 다시 실행합니다. 마이그레이션은 완전히 통과될 때까지 안전하게 재실행할 수 있습니다.
---
## 외부 플랜 파일 가져오기
전체 GSD-2 프로젝트가 아닌 독립형 플랜 문서(팀 계획 문서, 마크다운 스펙, 내보낸 작업 목록)가 있는 경우 `--from`을 사용합니다:
```bash
/gsd-import --from /tmp/team-plan.md
```
GSD는 동일한 충돌 감지 패스를 수행하고, 콘텐츠를 GSD Core `PLAN.md` 형식으로 변환하며, 플랜 체커로 결과를 검증합니다. 검증 후 대상 파일명과 다음 단계가 표시됩니다.
---
## 기존 문서 통합
저장소에 이미 ADR(아키텍처 결정 기록), PRD, 또는 사양 문서가 있는 경우 마이그레이션 후 `/gsd-ingest-docs`를 사용하여 `.planning/` 구조에 합성합니다:
### 전체 저장소 스캔(모드 자동 감지)
```bash
/gsd-ingest-docs
```
`.planning/`이 이미 있는 경우(예: 방금 실행한 마이그레이션에서) GSD는 기본적으로 병합 모드를 사용합니다 — 기존 내용을 덮어쓰지 않고 가져온 문서와 함께 합성합니다.
### 특정 디렉터리로 범위 지정
```bash
/gsd-ingest-docs docs/
/gsd-ingest-docs docs/adr/
```
### 명시적 우선순위 매니페스트 사용
문서 유형이 혼합되거나 충돌 시 어떤 문서가 우선순위를 가질지 제어하고 싶을 때:
```bash
/gsd-ingest-docs --manifest ingest.yaml
```
매니페스트는 문서당 `{path, type, precedence?}`를 나열하는 YAML 파일입니다. 예상 형태는 [명령 참조](../COMMANDS.md)의 `--manifest` 플래그 설명을 참조하세요.
### 특정 모드 강제
```bash
/gsd-ingest-docs --mode merge # 기존 .planning/에 병합
/gsd-ingest-docs --mode new # 처음부터 부트스트랩 (덮어쓰기)
```
**출력:** `/gsd-ingest-docs`는 항상 세 가지 버킷(자동 해결, 경쟁 변형, 미해결 블로커)이 있는 `INGEST-CONFLICTS.md`를 생성합니다. 모든 인제스트 실행 후 이 파일을 검토하세요. LOCKED vs LOCKED ADR 모순에서만 하드 중단이 발생합니다. 다른 모든 것은 자동으로 버려지지 않고 검토를 위해 표시됩니다.
---
## 마이그레이션된 프로젝트 검증
마이그레이션과 문서 인제스트가 완료되면 프로젝트 상태가 일관성 있는지 확인합니다:
```bash
/gsd-health
/gsd-health --repair
```
`/gsd-health`는 `.planning/` 디렉터리 무결성을 확인하고 드리프트를 보고합니다. `--repair`는 복구 가능한 문제를 자동으로 수정합니다.
그다음 GSD Core가 프로젝트 상태를 읽을 수 있는지 확인합니다:
```bash
/gsd-progress
```
프로젝트가 깔끔하게 이전되었다면 현재 페이즈 상태와 권장 다음 단계가 표시됩니다. 여기서부터 표준 GSD Core 워크플로가 적용됩니다.
---
## 조건부 처리: 마이그레이션 대상과 아닌 것
| 상황 | 할 일 |
|-----------|-----------|
| `.gsd/`가 현재 디렉터리에 있음 | `/gsd-import --from-gsd2` 실행 (`--path` 불필요) |
| `.gsd/`가 다른 디렉터리에 있음 | `--path ~/projects/old-project` 사용 |
| 전체 GSD-2 프로젝트가 아닌 독립형 플랜 문서가 있음 | `/gsd-import --from /path/to/plan.md` 사용 |
| `docs/adr/`에 ADR이 있음 | 마이그레이션 후 `/gsd-ingest-docs docs/adr/` 실행 |
| ADR, PRD, 스펙이 혼합되어 있음 | 저장소 루트에서 `/gsd-ingest-docs` 실행; 자동으로 분류됨 |
| 충돌 감지가 블로커를 보고함 | 나열된 모순을 해결한 후 재실행; 모든 블로커가 해결될 때까지 파일이 작성되지 않음 |
| 마이그레이션 작동 여부 확인이 안 됨 | `/gsd-health`와 `/gsd-progress`를 실행하여 확인 |
| INGEST-CONFLICTS.md에 미해결 블로커가 나열됨 | 영향받는 문서가 계획에 통합되기 전에 수동 해결 필요 |
---
## 관련 문서
- [첫 번째 프로젝트](../tutorials/your-first-project.md)
- [명령 참조](../COMMANDS.md)
- [문서 인덱스](../README.md)

216
docs/ko-KR/how-to/plan-a-phase.md Normal file
View File

@@ -0,0 +1,216 @@
# 페이즈를 기획하는 방법
**목표:** 페이즈 결정 사항과 리서치를 실행 준비가 된 원자적이고 검증 가능한 태스크 계획으로 변환합니다.
**전제 조건:** `.planning/ROADMAP.md`가 존재해야 합니다. `/gsd-discuss-phase`에서 생성된 `{phase}-CONTEXT.md`를 강력히 권장하지만 필수는 아닙니다.
---
## 표준 기획 흐름 실행
```bash
/gsd-plan-phase 2
```
다음 세 단계를 순서대로 실행합니다:
1. **리서치** — `gsd-phase-researcher` 서브에이전트가 도메인을 조사하고 `{phase}-RESEARCH.md`를 작성합니다.
2. **기획** — `gsd-planner` 서브에이전트가 컨텍스트, 리서치, 요구 사항을 읽고 하나 이상의 `{phase}-{N}-PLAN.md` 파일을 작성합니다.
3. **검증** — `gsd-plan-checker` 서브에이전트가 8개 차원에서 계획 품질을 검증하고 품질 게이트를 통과할 때까지 최대 3회의 수정 루프를 실행합니다.
페이즈 번호가 없으면 GSD Core는 로드맵에서 다음 미기획 페이즈를 대상으로 합니다.
---
## 리서치 건너뛰기 또는 강제 실행
**도메인이 익숙하고 새 리서치가 필요 없는 경우:**
```bash
/gsd-plan-phase 3 --skip-research
```
**RESEARCH.md가 이미 존재하지만 강제로 새로 고침하려는 경우:**
```bash
/gsd-plan-phase 3 --research
```
**리서치만 실행하려는 경우** — RESEARCH.md를 작성하고 기획 전 종료:
```bash
/gsd-plan-phase --research-phase 4
```
RESEARCH.md가 이미 존재하면 업데이트, 보기, 또는 건너뛰기 프롬프트가 표시됩니다. 프롬프트 없이 강제 새로 고침하려면:
```bash
/gsd-plan-phase --research-phase 4 --research
```
리서처를 실행하지 않고 기존 RESEARCH.md를 표준 출력으로 출력하려면:
```bash
/gsd-plan-phase --research-phase 4 --view
```
참고: `--research-phase <N>`은 `/gsd-plan-phase`의 플래그입니다. 독립형 리서치 페이즈 명령은 없습니다. 이전의 독립형 리서치 명령은 이 플래그로 대체되었습니다.
---
## 수평 계층 대신 수직 기능 슬라이스로 기획
**기술 계층별이 아닌 기능별 얇은 종단 슬라이스**(UI → API → DB)로 태스크를 구성하려면:
```bash
/gsd-plan-phase 1 --mvp
```
이전 페이즈 요약이 없는 새 프로젝트의 페이즈 1에서 `--mvp`는 프로젝트 스캐폴드, 라우팅, 실제 DB 읽기/쓰기 하나, 실제 UI 인터랙션 하나, 개발 배포를 다루는 `SKELETON.md`도 생성합니다.
플래그 없이 페이즈에 MVP 모드를 지속하려면 ROADMAP.md의 해당 페이즈 항목에 `**Mode:** mvp`를 추가하세요.
---
## 동작 추가 태스크마다 실패하는 테스트 요구
**TDD 적용을 원하는 경우** — 각 동작 추가 태스크는 구현 전 실패하는 테스트로 시작합니다:
```bash
/gsd-plan-phase 1 --tdd
```
`--mvp`와 조합 가능:
```bash
/gsd-plan-phase 1 --mvp --tdd
```
모든 동작 추가 태스크가 RED → GREEN → REFACTOR를 따르는 수직 슬라이스를 생성합니다. 플래너는 적합한 태스크(비즈니스 로직, API 엔드포인트, 데이터 변환)에 `type: tdd`를 적용하고 UI, 설정, 연결 코드에는 표준 `type: execute`를 사용합니다.
TDD 모드는 설정에서도 지속할 수 있습니다:
```bash
node gsd-tools.cjs config-set workflow.tdd_mode true
```
---
## 크로스 AI 리뷰 피드백으로 재기획
**`/gsd-review --phase N`을 실행하여 `REVIEWS.md`가 존재하는 경우:**
```bash
/gsd-plan-phase 3 --reviews
```
플래너는 `REVIEWS.md`를 읽고 피드백을 반영하여 계획을 수정합니다. `--gaps`와 함께 사용할 수 없습니다.
**자동화된 루프를 원하는 경우** — HIGH 우려 사항이 남지 않을 때까지 재기획 및 재검토:
```bash
/gsd-plan-review-convergence 3
```
수렴 루프는 plan → review → replan → re-review 사이클을 기본 최대 3회 실행합니다. 상한선을 변경하려면 `--max-cycles N`을 사용하세요.
---
## 실패한 검증 후 갭 해소
**`VERIFICATION.md`에 미해결 갭이 있고 해당 갭만을 대상으로 재기획하려는 경우:**
```bash
/gsd-plan-phase 3 --gaps
```
리서치는 건너뛰고 플래너는 검증 갭을 직접 읽습니다.
---
## 기획 시작 전 프로젝트 상태 검증
```bash
/gsd-plan-phase 2 --validate
```
리서처를 실행하기 전에 상태 검증을 실행합니다. ROADMAP.md 또는 STATE.md가 최신 상태와 맞지 않다고 의심되는 경우 사용하세요.
---
## 기획 후 외부 바운스 검증 실행
**`workflow.plan_bounce_script`가 설정되어 있고 완성된 계획의 외부 검증을 원하는 경우:**
```bash
/gsd-plan-phase 1 --bounce
```
설정에 바운스가 활성화된 경우에도 건너뛰려면:
```bash
/gsd-plan-phase 1 --skip-bounce
```
---
## 대화형 확인 억제
```bash
/gsd-plan-phase --auto
```
모든 프롬프트를 건너뜁니다. 자동화 파이프라인에 유용합니다. 설정에서 `research_enabled`가 false인 경우 리서치는 건너뜁니다.
---
## 기획 결과물
성공적인 실행은 다음 파일을 생성합니다:
| 파일 | 목적 |
|---|---|
| `{phase}-RESEARCH.md` | 도메인 리서치, 패키지 적법성 감사, 검증 아키텍처 |
| `{phase}-VALIDATION.md` | Nyquist 테스트 매핑 — 계획이 충족해야 할 테스트 케이스 (차원 8) |
| `{phase}-{N}-PLAN.md` | frontmatter, 웨이브 할당, 인수 기준이 포함된 실행 가능한 태스크 계획 |
| `{phase}/SKELETON.md` | 워킹 스켈레톤 (MVP 모드, 새 프로젝트의 페이즈 1에만 해당) |
각 PLAN.md에는 필수 `<read_first>` 및 `<acceptance_criteria>` 필드가 있는 태스크가 포함됩니다. 모든 `<acceptance_criteria>` 항목은 소스 단언, 동작 단언, 테스트 명령, CLI 출력으로 검증 가능합니다. 주관적 표현은 허용되지 않습니다.
전체 필드 참조는 [PLAN.md 스키마](../reference/plan-md.md)를 참고하세요.
### 계획 품질 차원
`gsd-plan-checker`는 실행을 허용하기 전에 8개 차원에서 계획을 검증합니다:
1. 태스크 원자성 — 각 태스크는 단일 관심사
2. 의존성 정확성 — 웨이브 순서가 일관됨
3. 인수 기준 검증 가능성 — 주관적 기준 없음
4. `<read_first>` 완전성 — 수정 중인 파일이 항상 나열됨
5. 구체적인 `<action>` 값 — "~에 맞춰 정렬" 같은 모호한 지시 없음
6. 페이즈 목표에서 파생된 `must_haves`
7. 요구 사항 ID 커버리지 — 모든 페이즈 요구 사항 ID가 최소 하나의 계획에 나타남
8. Nyquist 테스트 매핑 — 계획이 VALIDATION.md의 검증 전략을 다룸
수정 루프는 최대 3회 실행됩니다. 3회 반복 후에도 품질 게이트를 통과하지 못하면 체커가 남은 문제를 수동 검토를 위해 표시합니다.
---
## 닫힌 페이즈 재기획
`status: passed`가 있는 `VERIFICATION.md`가 있는 페이즈는 닫힌 것으로 간주됩니다. 재기획을 시도하면 오류로 중단됩니다. 종료가 잘못된 경우 `--force`로 재정의하세요:
```bash
/gsd-plan-phase 2 --force
```
트랜스크립트와 커밋된 계획 문서에 경고가 기록됩니다.
---
## 관련 문서
- [페이즈 논의](discuss-a-phase.md)
- [페이즈 실행](execute-a-phase.md)
- [PLAN.md 스키마](../reference/plan-md.md)
- [명령어 참조](../COMMANDS.md)

323
docs/ko-KR/how-to/recover-and-troubleshoot.md Normal file
View File

@@ -0,0 +1,323 @@
# 복구 및 문제 해결 방법
**목표:** 조건부 레시피 구조를 사용하여 컨텍스트 손실과 손상된 상태부터 설치 실패와 권한 오류까지 일반적인 문제를 식별하고 수정합니다.
**사전 조건:** GSD Core가 설치되어 있어야 합니다. 설치 문제의 경우 [런타임에 설치](install-on-your-runtime.md)를 참조하세요.
---
## 컨텍스트 및 세션 문제
### 현재 위치를 파악하지 못한 경우
```bash
/gsd-progress
```
모든 상태 파일을 읽고 현재 위치와 다음 할 일을 정확히 알려줍니다.
올바른 다음 단계로 자동 진행하려면:
```bash
/gsd-progress --next
```
### 새 세션을 시작하고 컨텍스트를 복원해야 하는 경우
```bash
/gsd-resume-work
```
마지막 핸드오프의 전체 세션 컨텍스트(현재 페이즈, 계획 결정, 작업이 중단된 위치)를 복원합니다.
### 긴 세션 중 품질이 저하되는 경우
주요 명령 사이에 컨텍스트 창을 초기화합니다:
```bash
/clear
```
그다음 상태를 복원합니다:
```bash
/gsd-resume-work
```
GSD는 새로운 컨텍스트를 중심으로 설계되었습니다. 모든 서브에이전트는 이미 깨끗한 200k 창을 받습니다. 메인 세션은 시간이 지남에 따라 저하됩니다 — 초기화하고 재개하는 것이 올바른 해결책이며 계속 밀어붙이는 것이 아닙니다.
### 중단 전에 컨텍스트를 저장하고 싶은 경우
```bash
/gsd-pause-work
```
현재 위치가 있는 `.planning/HANDOFF.json`을 생성합니다. 세션 후 요약도 `.planning/reports/`에 작성하려면 `--report`를 추가합니다:
```bash
/gsd-pause-work --report
```
---
## 계획 무결성 문제
### `.planning/` 무결성이 불확실한 경우
```bash
/gsd-health
```
오류, 경고, 정보 메모에 걸쳐 상태를 보고합니다:
| 상태 | 의미 |
|--------|---------|
| `HEALTHY` | 모든 예상 아티팩트가 존재하고 올바른 형식 |
| `DEGRADED` | 처리해야 하지만 작업을 계속할 수 있는 경고 |
| `BROKEN` | 실행을 차단하는 심각한 오류 |
일반적인 자동 복구 가능한 문제(오류 E004, E005; 경고 W003, W008):
```bash
/gsd-health --repair
```
누락된 `STATE.md`를 재생성하고, 손상된 `config.json`을 기본값으로 재설정하며, 누락된 구성 키를 추가합니다. `PROJECT.md`나 `ROADMAP.md`를 덮어쓰지 않습니다.
### STATE.md가 존재하지 않는 페이즈를 참조하는 경우
이것은 경고 `W002`를 생성합니다. 상태 CLI를 사용하여 진단하고 복구합니다:
```bash
node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" state validate
```
쓰기 없이 동기화가 변경할 내용 미리 보기:
```bash
node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" state sync --verify
```
동기화 적용:
```bash
node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" state sync
```
이 명령들은 디스크의 실제 프로젝트 상태에서 `STATE.md`를 재구성합니다. 수동 `STATE.md` 편집을 대체합니다.
### "Project already initialised"가 표시되는 경우
`.planning/PROJECT.md`가 이미 있습니다. `/gsd-new-project`는 안전 확인입니다. 정말로 처음부터 다시 시작하고 싶다면 먼저 `.planning/` 디렉터리를 삭제합니다:
```bash
rm -rf .planning/
```
그다음 `/gsd-new-project`를 다시 실행합니다.
### 컨텍스트 창 사용률이 높은 경우
```bash
/gsd-health --context
```
컨텍스트 창 사용률 가드를 프로브합니다. 60%에서 경고, 70%에서 위험. 경고 임계값을 초과한 경우 다음 주요 명령을 시작하기 전에 `/clear`를 실행한 후 `/gsd-resume-work`를 실행합니다.
---
## 실행 문제
### 실행자가 Bash 명령에서 "Permission denied"를 받는 경우
GSD의 `gsd-executor` 서브에이전트는 쓰기 가능한 Bash 접근이 필요합니다. `~/.claude/settings.json`의 `permissions.allow` 아래에 필요한 패턴을 추가합니다. 최소한:
```json
"Bash(git add:*)",
"Bash(git commit:*)",
"Bash(git merge:*)",
"Bash(git checkout:*)"
```
스택별 패턴(Rails, Python, Node, Rust)은 `docs/USER-GUIDE.md`의 "Executor Subagent Gets Permission denied" 섹션의 전체 표를 참조하세요.
프로젝트별 대안: 프로젝트 루트의 `.claude/settings.local.json`에 동일한 블록을 추가합니다.
### 실행이 실패하거나 스텁을 생성하는 경우
플랜이 너무 야심찬지 확인합니다. 플랜에는 최대 두세 개의 작업이 있어야 합니다. 작업이 너무 크면 단일 컨텍스트 창이 안정적으로 생성할 수 있는 것을 초과합니다. 더 작은 범위로 페이즈를 다시 계획합니다:
```bash
/gsd-plan-phase 1
```
무엇이 잘못되었는지에 대한 체계적인 진단은 [실패한 실행 디버그](debug-a-failed-execution.md)를 참조하세요.
### 병렬 실행이 빌드 잠금 오류 또는 사전 커밋 훅 실패를 일으키는 경우
이것은 여러 에이전트가 동시에 빌드 도구를 트리거하여 발생합니다. GSD는 v1.26 이후 이를 자동으로 처리합니다. 오래된 버전이거나 여전히 경합이 보이면 병렬 실행을 비활성화합니다:
```bash
/gsd-settings
```
`parallelization.enabled`를 `false`로 설정합니다.
### 서브에이전트가 실패한 것처럼 보이지만 커밋이 만들어진 경우
무언가가 고장났다고 결론 내리기 전에 git 로그를 확인합니다:
```bash
git log --oneline -10
```
알려진 Claude Code 분류 버그로 인해 작업이 성공했는데도 실패를 보고할 수 있습니다. GSD의 오케스트레이터는 실제 출력을 점검하지만 불일치가 보이면 커밋이 실제 근거입니다.
---
## 플랜 및 페이즈 문제
### 플랜이 의도와 맞지 않거나 잘못 정렬된 경우
계획 전에 `/gsd-discuss-phase N`을 실행합니다. 대부분의 플랜 품질 문제는 `CONTEXT.md`가 방지했을 가정에서 발생합니다:
```bash
/gsd-discuss-phase 1
```
전체 세션을 시작하지 않고 GSD가 현재 어떤 가정을 하는지 보려면:
```bash
/gsd-discuss-phase 3 --assumptions
```
### 실행 후 무언가를 변경해야 하는 경우
`/gsd-execute-phase`를 다시 실행하지 마세요. 대상이 되는 수정에는 `/gsd-quick`을 사용합니다:
```bash
/gsd-quick "Fix the login button not responding on mobile Safari"
```
또는 `/gsd-verify-work N`을 사용하여 UAT를 통해 체계적으로 문제를 식별하고 수정합니다.
### 명령이 "Spawning…"에서 멈춘 것처럼 보이는 경우
기다리세요. GSD 서브에이전트는 별도의 컨텍스트 창에서 실행됩니다. 진행 중일 때는 상위 세션에서 보이지 않습니다. 스폰 라인의 활성 상태 메모가 이것이 예상된 동작임을 확인합니다. 연구 및 계획 에이전트는 일상적으로 1~5분이 걸립니다. 검증 에이전트는 대규모 페이즈에서 더 오래 걸릴 수 있습니다.
세션을 중단하지 마세요. 종료하면 진행 중인 서브에이전트 작업이 버려집니다.
10분 이상 지난 경우 Claude Code 사이드바에서 에이전트 작업이 여전히 활성으로 표시되는지 확인합니다.
---
## 워크플로 상태 문제
### 워크플로가 손상되거나 상태가 일관성이 없어 보이는 경우
```bash
/gsd-forensics
```
또는 설명과 함께:
```bash
/gsd-forensics "Phase 3 execution stalled after wave 1"
```
`/gsd-forensics`는 사후 분석 조사를 실행합니다: git 히스토리 이상 감지, 아티팩트 무결성, STATE.md 일관성, 커밋되지 않은 작업, 고아 워크트리. `.planning/forensics/`에 보고서를 작성하고 권장 복구 단계를 제시합니다. 읽기 전용이며 프로젝트 파일을 절대 수정하지 않습니다.
### 페이즈 또는 플랜을 롤백해야 하는 경우
```bash
/gsd-undo --phase 03 # 페이즈 3의 모든 커밋 롤백
/gsd-undo --plan 03-02 # 페이즈 3의 플랜 02 커밋 롤백
/gsd-undo --last 5 # 가장 최근 GSD 커밋 5개에서 대화식으로 선택
```
`/gsd-undo`는 되돌리기 전에 종속 페이즈를 확인하고 항상 확인 게이트를 표시합니다.
---
## 설치 및 업데이트 문제
### 설치 후 GSD가 인식되지 않는 경우
런타임을 재시작합니다. GSD는 런타임의 명령 디렉터리(예: `~/.claude/commands/gsd/`)에 슬래시 명령을 설치합니다. 대부분의 런타임은 시작 시에만 새 명령을 발견합니다.
문제가 지속되면 설치를 확인합니다:
```bash
npx @opengsd/gsd-core@latest --claude --local
```
런타임별 설치 경로와 문제 해결은 [런타임에 설치](install-on-your-runtime.md)를 참조하세요.
### 업데이트가 로컬 변경 사항을 덮어쓴 경우
v1.17 이후 인스톨러는 로컬에서 수정된 파일을 `gsd-local-patches/`에 백업합니다. 변경 사항을 재적용합니다:
```bash
/gsd-update --reapply
```
### npm을 통한 업데이트가 불가능한 경우
npm 중단이나 네트워크 제한으로 `npx @opengsd/gsd-core`가 실패하는 경우 npm 접근 없이도 작동하는 단계별 수동 업데이트 절차는 `docs/manual-update.md`를 참조하세요.
일상적인 업데이트는 [GSD 업데이트](update-gsd.md)를 참조하세요.
---
## 비용 문제
### 모델 비용이 너무 높은 경우
예산 프로필로 전환합니다:
```bash
/gsd-config --profile budget
```
도메인이 익숙한 경우 설정에서 연구 및 플랜 체크 에이전트를 비활성화합니다:
```bash
/gsd-settings
```
활성화된 MCP 서버도 감사합니다. 활성화된 모든 MCP 서버는 모든 턴에 도구 스키마를 주입합니다. 브라우저 및 플랫폼별 도구는 각각 20k+ 토큰이 소요될 수 있습니다. 현재 페이즈에 필요하지 않은 것은 `.claude/settings.json`에서 비활성화합니다:
```json
{
"disabledMcpjsonServers": ["playwright", "mac-tools"]
}
```
---
## 복구 빠른 참조
| 문제 | 해결책 |
|---------|---------|
| 컨텍스트 손실 또는 새 세션 | `/gsd-resume-work` 또는 `/gsd-progress` |
| 다음 단계를 모름 | `/gsd-progress --next` |
| 페이즈가 잘못됨 | `/gsd-undo --phase NN`, 그다음 다시 계획 |
| 무언가 고장남 | `/gsd-debug "description"` (수정 없이 분석만 하려면 `--diagnose` 추가) |
| STATE.md 동기화 오류 | `state validate` 후 `state sync` |
| `.planning/` 무결성 불확실 | `/gsd-health`, 그다음 `/gsd-health --repair` |
| 워크플로 상태 손상 | `/gsd-forensics` |
| 빠른 대상 수정 | `/gsd-quick` |
| 플랜이 비전과 맞지 않음 | `/gsd-discuss-phase N` 후 다시 계획 |
| 비용이 높아짐 | `/gsd-config --profile budget` 및 `/gsd-settings`에서 에이전트 끄기 |
| 업데이트가 로컬 변경 사항 손상 | `/gsd-update --reapply` |
| 세션 요약 원함 | `/gsd-pause-work --report` |
| 병렬 실행 빌드 오류 | GSD 업데이트 또는 `parallelization.enabled: false` 설정 |
---
## 관련 문서
- [실패한 실행 디버그](debug-a-failed-execution.md)
- [런타임에 설치](install-on-your-runtime.md)
- [명령 참조](../COMMANDS.md)
- [문서 인덱스](../README.md)

124
docs/ko-KR/how-to/run-phases-autonomously.md Normal file
View File

@@ -0,0 +1,124 @@
# 페이즈를 자율적으로 실행하는 방법
남은 모든 페이즈 또는 지정된 범위를 무인으로 실행합니다. GSD가 각 단계마다 직접 진행하지 않아도 discuss → plan → execute를 진행합니다.
자율 실행 중 페이즈 루프가 무엇을 하는지에 대한 배경은 [페이즈 루프](../explanation/the-phase-loop.md)를 참고하세요.
---
## 전제 조건
- `.planning/ROADMAP.md`와 `.planning/STATE.md`가 있는 활성 프로젝트
- 실행하려는 모든 페이즈가 자율 모드로 처리 가능한 상태여야 함 (보류 중 또는 진행 중, 이미 완료되지 않은 것)
- 중요한 설계 결정 사항은 이미 `PROJECT.md`에 있거나 이전 `/gsd-discuss-phase`를 통해 캡처되어 있어야 함 — 자율 모드는 `--interactive`를 사용할 때만 대화형으로 모호한 영역을 표시할 수 있음
---
## 남은 모든 페이즈 실행
```bash
/gsd-autonomous
```
GSD는 `ROADMAP.md`를 읽고, 미완료 페이즈를 번호 순으로 발견하며, 각각에 대해 discuss → plan → execute를 실행합니다. 모든 페이즈가 완료되면 자동으로 마일스톤 생애주기를 실행합니다: audit → complete → cleanup.
---
## 특정 페이즈 범위 실행
`--from`과 `--to`를 사용하여 실행 범위를 지정합니다. 두 플래그 모두 소수 페이즈 번호를 허용합니다(예: `3.1`).
```bash
/gsd-autonomous --from 3 # 페이즈 3, 4, 5 … (이미 완료된 1, 2 건너뜀)
/gsd-autonomous --to 5 # 5까지 포함한 페이즈
/gsd-autonomous --from 3 --to 5 # 정확히 페이즈 3, 4, 5
```
`--to`에 도달하면 마일스톤의 모든 페이즈가 완료되지 않았으므로 생애주기 단계는 건너뜁니다. 완료 배너가 재개 방법을 알려줍니다:
```text
Resume with: /gsd-autonomous --from 6
```
---
## 대화형 논의로 실행
기본적으로 자율 모드는 스마트 논의(배치 테이블 제안)를 사용하여 논의 질문에 자동으로 답변합니다. 계획 및 실행을 메인 컨텍스트 밖으로 유지하면서 설계 질문에 직접 답하고 싶다면:
```bash
/gsd-autonomous --interactive
```
대화형 모드에서:
- `/gsd-discuss-phase`가 인라인으로 실행되어 답변을 기다림
- 기획 및 실행은 백그라운드 에이전트로 실행되므로 현재 페이즈가 구축되는 동안 다음 페이즈를 논의할 수 있음
- 메인 컨텍스트는 가볍게 유지됨 — 논의 대화만 누적됨
---
## 여전히 적용되는 안전 게이트
자율 모드는 GSD의 품질 파이프라인을 우회하지 않습니다. 각 페이즈는 여전히:
- 실행 전 플랜 체커를 실행함
- 실행 후 `VERIFICATION.md`를 읽고 결과에 따라 라우팅함
- 검증 상태가 `human_needed` 또는 `gaps_found`인 경우 일시 중지하고 어떻게 할지 묻음
- 단계가 실패하면 중단하고 옵션 제시 (수정 후 재시도, 페이즈 건너뛰기, 또는 중단)
수동 실행과의 유일한 차이는 `passed` 검증이 자동으로 다음으로 진행된다는 것입니다. 결정이 필요한 경우를 제외하고 페이즈 사이에 프롬프트가 표시되지 않습니다.
패키지 적법성 게이트도 활성 상태로 유지됩니다. 계획에 의심스러운 패키지에 대한 `checkpoint:human-verify` 태스크가 포함된 경우 실행자가 중단하고 체크포인트를 표시합니다. 자율 모드는 플래그된 패키지를 자동으로 설치하지 않습니다.
---
## 자율 모드를 사용하지 않아야 할 때
다음과 같은 경우 `/gsd-autonomous`를 사용하지 마세요:
- **페이즈에 미결된 설계 결정이 있는 경우.** `/gsd-discuss-phase`를 실행하지 않았고 `PROJECT.md`에 선호 사항이 캡처되지 않은 경우, 스마트 논의가 동의하지 않을 수 있는 자율 선택을 합니다. 먼저 대화형으로 논의하거나 `--interactive`를 사용하세요.
- **단일 페이즈를 세밀하게 제어해야 하는 경우.** 하나의 페이즈는 `/gsd-execute-phase N`이 단계별 출력을 제공하고 계속하기 전에 반응할 수 있게 해줍니다. 자율 모드는 대규모 무인 실행을 위해 설계되었습니다.
- **페이즈에 새롭거나 위험도 높은 작업이 있는 경우.** 자율 모드는 차단기가 없는 한 일시 중지를 건너뜁니다. 예상치 못한 상황이 예상되는 페이즈에서는 수동 실행으로 루프에 머무세요.
- **부분 실행 중인 페이즈가 있는 경우.** 자율 모드는 미완료 페이즈를 처리하지만 부분적으로 실행된 웨이브는 재개하지 않습니다. 이미 진행 중인 페이즈를 완료하려면 `/gsd-execute-phase N`을 사용하세요.
실행이 도중에 중단된 경우 [실패한 실행 디버그](debug-a-failed-execution.md)를 참고하여 문제를 진단하세요.
---
## 실행 중 진행 상황 확인
자율 모드는 각 페이즈 전에 진행 상황 배너를 출력합니다:
```text
GSD ► AUTONOMOUS ▸ Phase 3/7: Auth Middleware [████░░░░] 28%
```
세션 도중 실행 상태를 확인해야 한다면 다른 터미널을 열고 실행하세요:
```bash
/gsd-progress
```
---
## 중단 후 재개
자율 모드가 중단된 경우(차단기 프롬프트에서 "자율 모드 중단"을 선택했거나 세션이 중단된 경우), 중단된 곳에서 재개하세요:
```bash
/gsd-autonomous --from 4 # 4를 첫 번째 미완료 페이즈 번호로 교체
```
GSD는 이미 완료된 페이즈를 자동으로 건너뛰므로 실행이 어디서 중단되었는지 확실하지 않은 경우 이전 페이즈 번호에서 재실행해도 안전합니다.
---
## 관련 문서
- [페이즈 실행](execute-a-phase.md)
- [실패한 실행 디버그](debug-a-failed-execution.md)
- [명령어 참조](../COMMANDS.md)
- [문서 목차](../README.md)

159
docs/ko-KR/how-to/set-up-cross-ai-review.md Normal file
View File

@@ -0,0 +1,159 @@
# 크로스 AI 리뷰를 설정하는 방법
**목표:** 계획 리뷰에 참여할 AI 리뷰어를 설정하고, 기획된 페이즈 리뷰를 실행하고, 피드백을 활용하여 HIGH 심각도 우려 사항이 없는 계획으로 수렴합니다.
**전제 조건:** 페이즈가 기획되어 있어야 합니다(`{phase}-PLAN.md` 파일이 `.planning/phases/`에 존재). 최소 하나의 외부 AI CLI가 설치되어 인증되어 있어야 합니다.
---
## 어떤 리뷰어를 사용할지 결정
GSD Core는 Gemini CLI, Claude(별도 세션), Codex CLI, CodeRabbit, OpenCode, Qwen Code, Cursor, Antigravity CLI, Ollama, LM Studio, llama.cpp의 조합으로 리뷰 요청을 라우팅할 수 있습니다.
각 리뷰어는 `PLAN.md` 파일에 대해 동일한 구조화된 프롬프트를 독립적으로 실행합니다. 서로 다른 모델은 서로 다른 맹점을 가지고 있으므로 멀티 리뷰어 합의가 단일 리뷰어보다 더 많은 문제를 발견합니다.
**외부 CLI가 아직 설치되지 않은 경우**, 최소 하나를 설치하세요:
```bash
# Gemini CLI (Google 자격 증명으로 무료)
npm install -g @google/gemini-cli
# Antigravity CLI (Google 자격 증명으로 무료)
curl -fsSL https://antigravity.google/cli/install.sh | bash
# Codex CLI
npm install -g @openai/codex
```
---
## 기본 리뷰어 설정 (선택 사항)
기본적으로 `/gsd-review`는 감지된 모든 CLI를 실행합니다. 프로젝트 기본값으로 하위 집합을 고정하려면:
```bash
/gsd-config --integrations
```
통합 마법사는 API 키, 코드 리뷰 CLI 라우팅, `review.default_reviewers` 목록을 다룹니다. 목록을 플래그 없는 기본값으로 사용하려는 리뷰어로 설정하세요. 예: `["gemini","codex"]`.
또는 `gsd-tools`로 직접 설정하세요:
```bash
gsd config-set review.default_reviewers '["gemini","codex"]'
```
전체 통합 설정 스키마(API 키, 리뷰어별 모델 재정의, 로컬 서버 호스트 주소)에 대해서는 [설정](../CONFIGURATION.md)을 참고하세요.
---
## 리뷰 실행
### 표준 리뷰 (설정된 기본값 또는 감지된 모든 CLI 사용)
```bash
/gsd-review --phase 3
```
GSD는 각 리뷰어를 순서대로 호출하고 구조화된 피드백(요약, 강점, HIGH/MEDIUM/LOW 우려 사항, 제안, 위험 평가)을 수집하여 `.planning/phases/03-.../03-REVIEWS.md`에 결합된 출력을 작성합니다.
### 일회성 실행을 위한 단일 리뷰어 선택
```bash
/gsd-review --phase 3 --gemini
/gsd-review --phase 3 --codex
/gsd-review --phase 3 --cursor
```
명시적 플래그는 해당 실행에 대해 `--all` 기본값과 `review.default_reviewers` 모두를 재정의합니다.
### 모든 사용 가능한 리뷰어를 병렬로 실행
```bash
/gsd-review --phase 3 --all
```
`--all`은 항상 설정을 재정의하고 Ollama, LM Studio, llama.cpp를 포함하여 설정된 모든 로컬 모델 서버를 포함한 전체 감지 집합을 실행합니다.
### 로컬 모델 서버 리뷰어
Ollama 또는 LM Studio를 로컬에서 실행하는 경우 서버에 접근할 수 있을 때 `--all`에 자동으로 포함됩니다. 명시적으로 지정할 수도 있습니다:
```bash
/gsd-review --phase 3 --ollama
/gsd-review --phase 3 --lm-studio
```
기본값(`localhost:11434` / `localhost:1234`)이 적용되지 않는 경우 `/gsd-config --integrations`를 통해 `review.*` 키 아래의 호스트 주소와 모델 선택을 설정하세요.
---
## 리뷰 출력 읽기
`{padded_phase}-REVIEWS.md` 파일에는 다음이 포함됩니다:
- 심각도 분류 우려 사항이 있는 각 리뷰어의 개별 리뷰
- 두 명 이상의 리뷰어가 제기한 우려 사항을 종합한 **합의 요약** 섹션 — 최우선 신호를 보려면 여기서 시작하세요
- 리뷰어들이 의견이 달랐던 영역에 대한 **상이한 견해** 섹션
---
## 피드백을 계획에 반영
출력을 검토한 후 피드백을 반영하여 재기획하세요:
```bash
/gsd-plan-phase 3 --reviews
```
플래너는 `REVIEWS.md`를 읽고 우려 사항을 해소하도록 저장 전에 계획을 조정합니다.
---
## plan–review–replan 루프 자동화
모든 HIGH 심각도 우려 사항이 해결될 때까지 반복하려는 페이즈에는 수렴 루프를 사용하세요:
```bash
/gsd-plan-review-convergence 3
```
`plan-phase → review → replan → re-review` 사이클을 기본 최대 3회 실행합니다. HIGH 우려 사항 수가 0에 도달하면 루프를 종료합니다.
### 특정 리뷰어로 수렴
```bash
/gsd-plan-review-convergence 3 --codex
/gsd-plan-review-convergence 3 --gemini
```
### 모든 리뷰어로 더 높은 사이클 상한으로 수렴
```bash
/gsd-plan-review-convergence 3 --all --max-cycles 5
```
**정체 감지:** HIGH 우려 사항 수가 사이클 전반에 걸쳐 감소하지 않으면 GSD가 경고합니다. 사이클 상한에 도달했지만 HIGH 우려 사항이 남아 있는 경우, 진행하거나 수동으로 검토할지를 묻는 에스컬레이션 게이트가 표시됩니다.
---
## 조건부: 어떤 리뷰어를 선택할지
| 상황 | 권장 방법 |
|-----------|---------------------|
| Gemini CLI가 이미 설치되어 있는 경우 | `--gemini`는 항상 좋은 시작 리뷰어 |
| 무료 멀티 리뷰어 커버리지를 원하는 경우 | `--gemini` + `--agy` (둘 다 Google 자격 증명 사용) |
| OpenAI 중심 프로젝트인 경우 | OpenAI 모델 관점을 위해 `--codex` 추가 |
| GitHub Copilot 모델을 원하는 경우 | `--opencode` 추가 |
| API 비용을 완전히 피하려는 경우 | 로컬 모델로 Ollama를 설정하고 `--ollama` 사용 |
| 릴리스 전 최대 커버리지가 필요한 경우 | `/gsd-plan-review-convergence N --all` |
| 빠르게 반복하며 빠른 피드백을 원하는 경우 | CLI 하나 선택: `/gsd-review --phase N --gemini` |
---
## 관련 문서
- [검증 및 배포](verify-and-ship.md)
- [설정](../CONFIGURATION.md)
- [명령어 참조](../COMMANDS.md)
- [문서 목차](../README.md)

160
docs/ko-KR/how-to/spike-and-sketch.md Normal file
View File

@@ -0,0 +1,160 @@
# 확정 전에 스파이크와 스케치로 검증하는 방법
**목표:** 특정 접근 방식을 페이즈에 확정하기 전에 집중된 실현 가능성 실험(스파이크)과 일회용 HTML 목업을 통한 시각적 방향 탐색(스케치)으로 구현 위험을 줄입니다.
**사전 조건:** 없음. `/gsd-spike`와 `/gsd-sketch`는 자체 저장 디렉터리를 생성하며 초기화된 GSD 프로젝트가 필요하지 않습니다.
---
## 결정: 스파이크, 스케치, 또는 둘 다
| 답하고 싶은 질문… | 사용할 도구 |
|---|---|
| "이 기술적 접근 방식이 실제로 작동할까?" | `/gsd-spike` |
| "이 레이아웃 / 인터랙션 / 시각적 처리가 맞는 느낌인가?" | `/gsd-sketch` |
| "올바른 기술적 접근 방식은 무엇이고, 어떻게 보여야 할까?" | 둘 다, 순서대로: 먼저 스파이크, 그다음 스케치 |
스파이크는 실행 가능한 코드와 VALIDATED / INVALIDATED / PARTIAL 판정으로 이진 실현 가능성 질문에 답합니다. 스케치는 2~3개의 브라우저에서 비교 가능한 HTML 변형으로 시각적 질문에 답합니다. 두 가지는 상호 보완적입니다 — 스파이크는 접근 방식이 구현 가능함을 증명하고, 스케치는 디자인이 구현할 가치가 있음을 증명합니다.
---
## 스파이크 실행
### 대화식 입력(기본값)
```bash
/gsd-spike
```
GSD는 기술적 질문에 대해 물어보고, 이를 **Given / When / Then** 가설로 구성된 2~5개의 독립적인 실험으로 분해하며, 빌드 전에 확인을 요청합니다.
### 아이디어를 직접 제공
```bash
/gsd-spike "can we stream LLM tokens through SSE"
```
### 입력 건너뛰고 즉시 실행
```bash
/gsd-spike --quick "websocket vs SSE latency"
```
`--quick`은 분해 대화를 건너뛰고 인자를 단일 스파이크 질문으로 처리합니다. 질문이 이미 충분히 구체적이어서 세분화 없이 실행할 수 있을 때 사용합니다.
### 각 실험이 생성하는 결과물
`.planning/spikes/NNN-descriptive-name/`의 각 스파이크에는 다음이 포함됩니다:
- 작동하는 코드(의사 코드 아님)
- 코드 작성 전에 작성된 **Given / When / Then** 가설
- 엣지 케이스, 방향 전환, 놀라운 발견을 문서화한 조사 추적
- 증거와 함께 **VALIDATED**, **INVALIDATED**, 또는 **PARTIAL** 판정
- 프론트매터, 실행 방법 지침, 결과가 포함된 `README.md`
모든 스파이크는 `.planning/spikes/MANIFEST.md`에 인덱싱됩니다.
### 결과 패키징
신호가 확보되면 결과를 프로젝트 로컬 스킬로 패키징하여 향후 세션에서 자동으로 로드되도록 합니다:
```bash
/gsd-spike --wrap-up
```
이 명령은 `.claude/skills/spike-findings-[project]/`를 작성합니다. 스킬은 자동으로 발견되어 이후의 `/gsd-sketch`, `/gsd-ui-phase`, `/gsd-plan-phase` 실행에서 로드됩니다 — 명시적으로 참조할 필요가 없습니다.
---
## 스케치 실행
### 분위기 입력(기본값)
```bash
/gsd-sketch
```
GSD는 코드 작성 전에 느낌, 시각적 참조, 핵심 사용자 작업을 탐색하는 짧은 대화를 시작합니다. 한 번에 하나의 질문을 하며 진행 승인을 받을 때만 빌드를 시작합니다.
### 디자인 방향을 직접 제공
```bash
/gsd-sketch "dashboard layout"
```
### 분위기 입력 건너뛰고 즉시 실행
```bash
/gsd-sketch --quick "sidebar navigation"
```
`--quick`은 입력 대화를 완전히 건너뛰고 인자를 디자인 방향으로 사용합니다.
### 비 Claude 런타임(Codex, Gemini CLI 등)
```bash
/gsd-sketch --text "onboarding flow"
```
`--text`는 대화식 프롬프트를 일반 텍스트 번호 목록으로 대체합니다. 런타임이 `AskUserQuestion`을 지원하지 않을 때 사용합니다.
### 각 스케치가 생성하는 결과물
`.planning/sketches/NNN-descriptive-name/`의 각 스케치에는 다음이 포함됩니다:
- 탭 탐색으로 접근 가능한 2~3개의 변형이 있는 `index.html` — 빌드 단계 없이 브라우저에서 직접 열기
- 기능적인 인터랙티브 요소(호버, 클릭, 전환)
- 이전 스파이크 결과의 필드 이름과 데이터 형태를 사용하는 실제에 가까운 콘텐츠
- `.planning/sketches/themes/default.css`의 공유 CSS 변수
- 디자인 질문, 변형, 살펴볼 사항이 포함된 `README.md`
모든 스케치는 `.planning/sketches/MANIFEST.md`에 인덱싱됩니다.
### 우승 디자인 결정 패키징
변형을 선택한 후 시각적 결정을 프로젝트 로컬 스킬로 캡처합니다:
```bash
/gsd-sketch --wrap-up
```
이 명령은 `.claude/skills/sketch-findings-[project]/`를 작성합니다. 스킬은 `/gsd-ui-phase`에 의해 자동으로 가져옵니다 — 사전 검증된 결정(레이아웃, 색상 팔레트, 타이포그래피, 간격)은 확정된 것으로 처리되어 다시 묻지 않습니다.
---
## 통합 흐름: 스파이크 → 스케치 → 페이즈
기술적 실현 가능성과 시각적 방향 모두 불확실할 때 권장하는 순서:
```bash
/gsd-spike "SSE vs WebSocket for real-time feed"
/gsd-spike --wrap-up
/gsd-sketch "real-time feed UI"
/gsd-sketch --wrap-up
/gsd-discuss-phase N
/gsd-plan-phase N
```
스파이크 결과가 스케치에 정보를 제공합니다(실제 데이터 형태, 실제 인터랙션 상태, 현실적인 제약). 두 wrap-up 모두 플래너와 UI 연구자가 자동으로 로드하는 결정을 유지하므로 `/gsd-discuss-phase`나 `/gsd-ui-phase` 중에 선택 사항을 다시 설명할 필요가 없습니다.
---
## 스파이크 또는 스케치가 페이즈에 반영되는 방식
스파이크와 스케치 아티팩트는 수동으로 참조할 필요가 없습니다. GSD는 두 시점에서 자동으로 읽습니다:
1. **`/gsd-sketch`** — 목업 빌드 전에 `.claude/skills/spike-findings-*/`를 로드하여 변형이 증명된 제약(스트리밍 상태, 실제 필드 이름 등)을 반영하도록 함
2. **`/gsd-ui-phase N`** — UI 디자인 계약을 생성하기 전에 `.claude/skills/sketch-findings-*/`를 로드. 사전 검증된 디자인 결정은 확정된 것으로 처리됨
플래너도 `spike-findings-*` 스킬이 있을 때 스파이크 결과를 읽으므로 검증된 기술 선택(어떤 라이브러리, 어떤 프로토콜, 어떤 데이터 형식)이 반복적인 설명 없이 작업 플랜으로 직접 반영됩니다.
---
## 관련 문서
- [UI 페이즈 디자인](design-a-ui-phase.md)
- [페이즈 계획](plan-a-phase.md)
- [명령 참조](../COMMANDS.md)
- [문서 인덱스](../README.md)

120
docs/ko-KR/how-to/update-gsd.md Normal file
View File

@@ -0,0 +1,120 @@
# GSD Core 업데이트 방법
기존 GSD Core 설치를 최신 릴리즈로 업데이트하고, 확정 전에 변경 로그를 미리보고, 업데이트가 덮어쓸 로컬 커스터마이징을 복구합니다.
**필요한 것:** GSD가 설치된 것과 동일한 런타임. 업데이트 명령은 내부적으로 인스톨러를 다시 실행하므로 Node.js와 npx가 필요합니다(원래 설치와 동일한 요구 사항).
---
## 표준 업데이트 경로
AI 런타임 내에서 실행합니다:
```bash
/gsd-update
```
GSD가 수행하는 작업:
1. 설치된 버전과 설치 범위(전역 또는 로컬)를 감지합니다.
2. npm에서 `@opengsd/gsd-core`의 최신 릴리즈를 확인합니다.
3. 변경 로그를 가져와 설치된 버전과 최신 버전 사이의 변경 사항을 표시합니다.
4. 아무것도 건드리기 전에 확인을 요청합니다.
5. GSD 관리 디렉터리 내에서 발견된 사용자 추가 파일을 `gsd-user-files-backup/`에 백업합니다.
6. 인스톨러를 실행합니다(`npx @opengsd/gsd-core@latest --<runtime> --<scope>`).
7. 업데이트 확인 캐시를 초기화하여 상태 표시줄 인디케이터가 재설정됩니다.
8. 로컬에서 수정된 GSD 파일이 `gsd-local-patches/`에 백업되었는지 보고합니다.
새로운 명령과 에이전트를 적용하려면 업데이트 후 런타임을 재시작하세요.
---
## 플래그
| 플래그 | 수행하는 작업 |
|------|--------------|
| `--sync` | 업데이트 후 GSD 레지스트리에서 스킬 동기화 |
| `--reapply` | 업데이트 후 `gsd-local-patches/`에서 로컬에서 수정된 GSD 파일 다시 병합 |
```bash
/gsd-update --sync # 업데이트 및 스킬 동기화
/gsd-update --reapply # 업데이트 및 로컬 패치 재적용
```
---
## 업데이트 전 변경 로그 검토
`/gsd-update`는 확인을 요청하기 *전에* 항상 설치된 버전과 최신 버전 사이의 변경 로그 diff를 표시합니다. GitHub를 별도로 방문할 필요가 없습니다. 출력은 다음과 같습니다:
```text
## GSD Update Available
Installed: 1.39.0
Latest: 1.41.0
### What's New
────────────────────────────────────────────────────────────
[changelog entries for 1.40.0 and 1.41.0]
────────────────────────────────────────────────────────────
Proceed with update? [Yes, update now / No, cancel]
```
변경 로그를 가져올 수 없는 경우(네트워크 접근 없음, npm 중단), 업데이트는 여전히 확인 후 진행됩니다 — 변경 로그 가용성에 의존하지 않습니다.
---
## 로컬 커스터마이징 복구
### GSD 관리 디렉터리에 추가한 파일
GSD가 소유하는 디렉터리 내에 커스텀 파일을 배치한 경우(예: `gsd-` 접두사가 붙은 커스텀 에이전트 또는 `commands/gsd/`에 있는 추가 파일), 인스톨러가 이를 감지하고 해당 디렉터리를 지우기 전에 `gsd-user-files-backup/`에 복사합니다. 업데이트 후 해당 백업 위치에서 수동으로 복원합니다.
GSD 관리 디렉터리 외부에 배치한 파일 — `gsd-` 접두사 없는 커스텀 에이전트, `commands/gsd/` 외부의 커스텀 명령, `CLAUDE.md` 파일, 커스텀 훅 — 은 인스톨러가 절대 건드리지 않습니다.
### 직접 수정한 GSD 파일
GSD가 설치한 파일을 편집한 경우(예: 에이전트의 시스템 프롬프트 수정), 인스톨러는 매니페스트에 대한 해시 비교를 통해 수정을 감지하고 파일을 `gsd-local-patches/`에 백업한 후 새 버전으로 교체합니다. 업데이트 후:
```bash
/gsd-update --reapply
```
이 명령은 새로 설치된 파일에 `gsd-local-patches/`의 수정 사항을 병합합니다.
이전 업데이트 후 `--reapply`를 건너뛰었고 지금 패치를 적용하고 싶다면:
```bash
/gsd-update --reapply
```
이미 최신 버전이면 GSD는 설치 단계를 건너뛰고 바로 패치 재적용으로 진행합니다 — 새 다운로드를 트리거하지 않고도 `--reapply`를 단독으로 실행하는 것이 안전합니다.
---
## npm을 사용할 수 없을 때
npm 중단, 네트워크 제한, 또는 소스 저장소에서 작업 중이어서 `npx @opengsd/gsd-core@latest`가 실패하는 경우 [docs/manual-update.md](../../manual-update.md)의 수동 업데이트 절차를 사용하세요. 해당 문서는 최신 커밋 풀링, hooks dist 빌드, `node bin/install.js` 직접 실행을 다룹니다.
---
## 이미 최신 버전인 경우
`/gsd-update`는 확인 메시지와 함께 조기 종료합니다 — 다운로드 없음, 설치 없음, 재시작 불필요.
---
## 인스톨러 마이그레이션
각 GSD 릴리즈에는 관리 파일을 이름 변경, 이동, 또는 폐기하는 인스톨러 마이그레이션이 포함될 수 있습니다. 마이그레이션 레이어는 새 패키지 페이로드가 작성되기 전에 자동으로 실행됩니다. 수정한 파일에 영향을 주는 마이그레이션은 자동으로 처리되지 않고 확인을 요청합니다. 전체 설계와 런타임 구성 계약 레지스트리는 [docs/installer-migrations.md](../../installer-migrations.md)를 참조하세요.
---
## 관련 문서
- [런타임에 설치](install-on-your-runtime.md)
- [명령 참조](../COMMANDS.md)
- [수동 업데이트](../../manual-update.md)
- [인스톨러 마이그레이션](../../installer-migrations.md)
- [문서 인덱스](../README.md)

124
docs/ko-KR/how-to/verify-and-ship.md Normal file
View File

@@ -0,0 +1,124 @@
# 페이즈를 검증하고 배포하는 방법
**목표:** 실행된 작업에 대해 사용자 인수 테스트를 진행하고, 실패를 진단하여 수정하고, 자동 생성된 본문으로 풀 리퀘스트를 엽니다.
**전제 조건:** 페이즈가 실행되고 `SUMMARY.md` 파일이 존재해야 합니다. 실행이 아직 완료되지 않았다면 [페이즈 실행](execute-a-phase.md)을 참고하세요.
---
## 사용자 인수 테스트 실행
```bash
/gsd-verify-work 1
```
GSD는 페이즈의 `SUMMARY.md` 파일을 읽고, 사용자가 관찰 가능한 결과물을 추출하여 하나씩 안내합니다. 각 체크포인트에서 *예상되는 것*을 제시하고 실제와 일치하는지 묻습니다.
- `yes` / `y` / 빈 값 → 통과, 다음 테스트로 이동
- 그 외 → 문제로 기록됨, 설명에서 심각도 추론
심각도를 직접 분류할 필요가 없습니다. GSD가 표현에서 추론합니다("충돌" → 차단, "작동 안 함" → 주요, "이상해 보임" → 외관상).
진행 상황은 `.planning/phases/01-<name>/01-UAT.md`에 기록되며 `/clear`에서도 유지됩니다. 세션이 중단된 경우 `/gsd-verify-work 1`을 다시 실행하면 GSD가 마지막 체크포인트에서 재개할 것을 제안합니다.
---
## 실패 발견 시: 자동 진단 및 수정 기획
테스트에서 문제가 발견되면 GSD는 자동으로 진행합니다:
1. **근본 원인 진단** — 문제당 하나씩 병렬 디버그 에이전트를 실행하고 근본 원인으로 `UAT.md`를 업데이트합니다.
2. **갭 해소 기획** — 갭 해소 모드에서 `gsd-planner`를 실행하며, 진단이 포함된 `UAT.md`를 읽고 새 `PLAN.md` 파일을 작성합니다.
3. **수정 계획 검증** — `gsd-plan-checker`를 실행하여 계획이 실행 가능한지 확인합니다. 문제가 발견되면 플래너와 체커가 최대 3회 반복합니다.
4. **다음 단계 제시** — 계획이 체커를 통과하면:
```
Plans verified and ready for execution.
`/clear` then `/gsd-execute-phase 1 --gaps-only`
```
제안된 명령을 실행하여 수정을 적용한 후, `/gsd-verify-work 1`을 다시 실행하여 모든 것이 통과하는지 확인하세요.
---
## 모든 테스트 통과 시: 페이즈 배포
모든 UAT 테스트가 통과하면(또는 첫 번째 실행에서 문제가 발견되지 않으면) 페이즈는 `ROADMAP.md`와 `STATE.md`에서 자동으로 완료로 표시됩니다.
```bash
/gsd-ship 1
```
GSD는 사전 점검(검증 상태, 깨끗한 작업 트리, 브랜치, 원격 저장소, `gh` CLI 인증)을 실행하고 브랜치를 푸시한 후 PR을 생성합니다:
```bash
/gsd-ship 1 # 검토 준비된 PR
/gsd-ship 1 --draft # 초안 PR — 더 많은 페이즈가 뒤따를 때 유용
```
PR 본문은 기획 산출물에서 자동으로 조합됩니다:
- `ROADMAP.md`의 페이즈 목표
- `SUMMARY.md` 파일 및 핵심 파일의 계획별 요약
- 처리된 요구 사항 (REQ-ID)
- `VERIFICATION.md`의 검증 상태
- `STATE.md`의 핵심 결정 사항
본문을 수동으로 작성할 필요가 없습니다.
---
## 선택 사항: 배포 전후 코드 리뷰
`/gsd-ship`은 자동으로 코드 리뷰를 실행하지 않지만, 언제든지 추가할 수 있습니다:
**검증 전** (UAT 전에 문제 발견):
```bash
/gsd-code-review 1 # 표준 리뷰
/gsd-code-review 1 --fix # 리뷰 후 Critical + Warning 발견 사항 자동 수정
```
**PR 오픈 후** (병합 전 품질 게이팅):
```bash
/gsd-code-review 1 --depth=deep # 임포트 그래프를 포함한 파일 간 분석
```
주기 초반의 계획 리뷰를 위해 Gemini, Codex 또는 다른 리뷰어를 설정하려면 [크로스 AI 리뷰 설정](set-up-cross-ai-review.md)을 참고하세요.
---
## 선택 사항: 깔끔한 PR 브랜치 생성
브랜치에 리뷰어에게 보여주고 싶지 않은 `.planning/` 커밋이 포함된 경우:
```bash
/gsd-pr-branch # main에 대해 필터링
/gsd-pr-branch develop # develop에 대해 필터링
```
`/gsd-pr-branch`는 코드 변경 사항만 포함된 새 브랜치를 생성합니다. 기획 산출물 커밋은 제외됩니다. 팀의 리뷰 정책에서 기획 노이즈를 제외하는 경우 `/gsd-ship` 전에 실행하세요.
---
## 마일스톤 종료
이것이 마일스톤의 마지막 페이즈였다면 마일스톤 감사를 실행하고 보관하세요:
```bash
/gsd-audit-milestone # 모든 요구 사항이 배포되었는지 확인
/gsd-complete-milestone # 보관, git 태그 생성
```
`/gsd-complete-milestone`은 PR이 병합된 후의 자연스러운 다음 단계입니다. 검증과 배포가 전체 프로젝트 생애주기에 어떻게 적합한지는 [페이즈 루프](../explanation/the-phase-loop.md)를 참고하세요.
---
## 관련 문서
- [페이즈 실행](execute-a-phase.md)
- [크로스 AI 리뷰 설정](set-up-cross-ai-review.md)
- [페이즈 루프](../explanation/the-phase-loop.md)
- [명령어 참조](../COMMANDS.md)

157
docs/ko-KR/how-to/work-in-parallel-with-workstreams.md Normal file
View File

@@ -0,0 +1,157 @@
# 워크스트림으로 여러 영역을 병렬로 작업하는 방법
**목표:** 백엔드 API, 프론트엔드 대시보드, 인프라 등 서로 다른 마일스톤 영역에서 한 영역의 계획 상태가 다른 영역으로 유입되지 않도록 동시 작업을 수행합니다.
**사전 조건:** 활성화된 GSD Core 프로젝트(`.planning/ROADMAP.md` 존재). 없는 경우 먼저 `/gsd-new-project`를 실행하세요.
---
## 워크스트림이란
워크스트림은 단일 코드베이스 내의 독립된 계획 컨텍스트입니다. 각 워크스트림은 독립적인 `STATE.md`, `ROADMAP.md`, `REQUIREMENTS.md`, `phases/` 디렉터리를 포함하는 `.planning/workstreams/<name>/` 서브트리를 가집니다. 코드베이스 자체(소스 코드, git 히스토리, 브랜치)는 모든 워크스트림이 공유합니다.
```
.planning/
├── PROJECT.md ← 공유
├── config.json ← 공유
├── codebase/ ← 공유
└── workstreams/
├── backend-api/
│ ├── STATE.md
│ ├── ROADMAP.md
│ ├── REQUIREMENTS.md
│ └── phases/
└── frontend-dash/
├── STATE.md
├── ROADMAP.md
├── REQUIREMENTS.md
└── phases/
```
워크스트림이 활성화되면 모든 GSD 명령인 `/gsd-progress`, `/gsd-discuss-phase`, `/gsd-plan-phase`, `/gsd-execute-phase`가 해당 워크스트림의 디렉터리에서 읽고 씁니다. 워크스트림을 전환하면 소스 트리를 건드리지 않고 모든 명령이 다른 서브트리로 리디렉션됩니다.
---
## 워크스트림 생성
```bash
/gsd-workstreams create backend-api
```
GSD는 `.planning/workstreams/backend-api/` 아래에 워크스트림 디렉터리를 생성하고 기본 `STATE.md`와 `ROADMAP.md`를 시드합니다. 워크스트림은 자동으로 활성화되지 않으며 명시적으로 전환해야 합니다.
---
## 워크스트림 목록 보기
```bash
/gsd-workstreams list
```
모든 워크스트림과 현재 세션에서 활성화된 워크스트림을 표시합니다.
---
## 워크스트림으로 전환
```bash
/gsd-workstreams switch backend-api
```
이 시점부터 모든 GSD 워크플로 명령은 `backend-api` 컨텍스트에서 동작합니다. 전환은 세션 범위로 적용됩니다. 같은 저장소에서 여러 Claude Code 터미널이 열려 있는 경우, 각 세션은 서로 간섭 없이 서로 다른 활성 워크스트림을 유지할 수 있습니다.
전환 후 일반 페이즈 워크플로를 진행합니다:
```bash
/gsd-discuss-phase 1
/gsd-plan-phase 1
/gsd-execute-phase 1
/gsd-verify-work 1
```
다른 영역에서 작업하려면 두 번째 터미널에서 워크스트림을 전환합니다:
```bash
/gsd-workstreams switch frontend-dash
/gsd-discuss-phase 1
/gsd-plan-phase 1
```
---
## 모든 워크스트림의 진행 상황 확인
```bash
/gsd-workstreams progress
```
워크스트림 간 전환 없이 모든 워크스트림의 페이즈 상태, 현재 위치, 미완료 작업을 포함한 교차 워크스트림 요약을 출력합니다.
단일 워크스트림의 상세 상태 확인:
```bash
/gsd-workstreams status backend-api
```
---
## 워크스트림에서 작업 재개
컨텍스트 초기화나 새 세션 이후 위치를 복원합니다:
```bash
/gsd-workstreams resume backend-api
```
이 명령은 워크스트림을 활성화하고 마지막으로 알려진 위치를 복원합니다. 전환 후 `/gsd-resume-work`를 실행하는 것과 동일합니다.
---
## 완료된 워크스트림 보관
워크스트림의 마일스톤 작업이 완료되면:
```bash
/gsd-workstreams complete backend-api
```
GSD는 워크스트림을 보관 상태로 표시하고 활성 목록에서 제거합니다. 계획 아티팩트는 감사 목적으로 `.planning/workstreams/backend-api/`에 보존됩니다.
---
## 세션 컨텍스트 전환 없이 특정 워크스트림에 명령 실행
세션의 활성 컨텍스트를 변경하지 않고 특정 워크스트림에 대해 하나의 명령을 실행해야 하는 경우 `--ws` 플래그를 사용합니다:
```bash
/gsd-progress --ws frontend-dash
/gsd-plan-phase 2 --ws backend-api
```
`--ws`는 해석 우선순위에서 가장 높은 우선권을 가지며 세션 범위의 포인터를 변경하지 않습니다.
---
## 워크스트림과 워크스페이스 중 선택 기준
워크스트림을 선택할 때:
- 모든 작업이 **동일한 저장소**에 있고 같은 git 히스토리를 공유할 때
- 서로의 `STATE.md`를 덮어쓰지 않고 서로 다른 관심 영역(API, UI, 인프라)을 **동시에** 계획하거나 논의하고자 할 때
- 워크스트림 생성 시 브랜치를 별도로 만들 필요가 없을 때(각 워크스트림의 실행 내에서 일반적으로 브랜칭 가능)
- 전체 git 워크트리 생성 오버헤드가 필요한 격리에 비해 과하다고 느껴질 때
[워크스페이스](isolate-work-with-workspaces.md)를 선택할 때:
- **여러 저장소**(예: `hr-ui`와 `ZeymoAPI`)에서 작업할 때
- 기능별로 **별도의 git 워크트리** 또는 클론이 필요할 때 — 완전히 독립된 브랜치, 잠금 파일, 빌드 아티팩트
- 메인 저장소의 `.planning/` 하위 디렉터리가 아닌 완전히 별도의 `.planning/` 루트로 `/gsd-new-project`를 독립적으로 실행하고자 할 때
---
## 관련 문서
- [워크스페이스로 작업 격리](isolate-work-with-workspaces.md)
- [페이즈 루프](../explanation/the-phase-loop.md)
- [명령 참조](../COMMANDS.md)
- [문서 인덱스](../README.md)

96
docs/ko-KR/issue-driven-orchestration.md Normal file
View File

@@ -0,0 +1,96 @@
# GSD를 사용한 이슈 주도 오케스트레이션
**상태:** 안정적인 워크플로우 가이드
**대상:** GitHub Issues, Linear, Jira 또는 유사한 이슈 트래커에서 작업을 관리하며
GSD의 기존 기본 도구들을 통해 AI 보조 구현을 이끌고자 하는 개발자.
## 이 가이드란 무엇인가
GSD가 이미 제공하는 명령어들을 이슈 트래커 → 워크스페이스 → 계획/실행 → 검증/리뷰 → PR 루프로 조합하는 레시피이다. 문서화만을 위한 것이다. 새로운 명령어도, 데몬도, 트래커 통합도 없다 — 아래 참조된 모든 명령어들은 GSD에 이미 존재한다.
형태는 OpenAI의 오픈 소스 [Symphony 오케스트레이션 레퍼런스](https://openai.com/index/open-source-codex-orchestration-symphony/)([저장소](https://github.com/openai/symphony))에서 영감을 받았다. GSD는 Symphony를 벤더링하거나 래핑하지 않는다. 오케스트레이션 *개념들*이 GSD가 이미 노출하는 기본 도구들에 깔끔하게 매핑된다; 이 가이드는 글루 코드를 작성하거나 GSD의 안전 게이트를 우회하지 않고도 패턴을 채택할 수 있도록 매핑을 명확하게 설명한다.
## 존재 이유
GSD에는 이슈 주도 AI 개발을 위한 구성 요소들이 있다 —
`/gsd-workspace --new`, `/gsd-manager`, `/gsd-autonomous`, `/gsd-verify-work`,
`/gsd-review`, `/gsd-ship`, 그리고 `STATE.md`와 단계 결과물 스위트
— 하지만 사용자 정의 오케스트레이션 스크립트를 작성하지 않고 단일 트래커 이슈에서 이것들을 구동하는 방법을 안내하는 가이드가 없다. 그 가이드 없이는 실패 모드들이 발생한다:
- 과소 사용: 개발자들이 discuss/plan/execute를 수동으로 실행하면서 작업 패턴이 적합할 때도 `/gsd-manager`나 `/gsd-autonomous`에 손을 뻗지 않는다.
- 임시방편 스크립트: 개발자들이 트래커와 `claude` 호출 사이에 임시 쉘 루프를 연결하여 `STATE.md`, 단계 매니페스트, 검증 게이트를 우회한다.
이 가이드는 정규 루프를 발견 가능하게 만든다.
## 개념 매핑
각 행은 Symphony 스타일 오케스트레이션 개념을 GSD가 이미 제공하는 기본 도구에 매핑한다. Symphony 문서, 블로그 게시물, 또는 타사 오케스트레이션 설명을 읽을 때 이 표를 번역 키로 사용하라.
| Symphony 개념 | GSD 기본 도구 |
|---|---|
| `WORKFLOW.md` (최상위 의도) | `ROADMAP.md` (프로젝트 의도), `STATE.md` (라이브 상태), 단계 `CONTEXT.md` (단계별 범위), 단계 `PLAN.md` (실행 가능한 단계) |
| 작업당 격리된 에이전트 워크스페이스 | `/gsd-workspace --new --strategy worktree` |
| 에이전트 디스패치 및 동시성 | `/gsd-manager` (대화형 대시보드), `/gsd-autonomous` (무인) |
| 단계별 계획 및 논의 단계 | `/gsd-discuss-phase` → `/gsd-plan-phase` → `/gsd-execute-phase` |
| 작업 증명 / 테스트 증거 | `/gsd-verify-work` (`/clear` 전반에 걸쳐 지속되는 UAT.md) |
| 적대적 리뷰 | `/gsd-review` (계획의 교차 AI 동료 리뷰) |
| 사람 병합 게이트 | `/gsd-ship` (PR 생성, 선택적 코드 리뷰, 병합 준비) |
| 후속 캡처 | `/gsd-capture`, `/gsd-capture --seed`, `/gsd-new-milestone`, 또는 수동으로 열린 트래커 이슈 |
| 동시성 제어 | Manager / background-agent 의미 (항상 켜진 폴러 없음) |
매핑은 단방향이다: GSD가 안전 게이트(검증, 사람 리뷰, 후속 생성에 대한 명시적 확인)를 소유한다. Symphony의 "지속적 오케스트레이션" 프레이밍은 의도적으로 채택하지 않는다 — [비목표](#비목표) 참조.
## 엔드투엔드 흐름
단일 트래커 이슈에서 엔드투엔드로 실행될 수 있도록 작성된 정규 이슈 → PR 루프. 실행 전에 대괄호 플레이스홀더를 교체하라.
1. **트래커 이슈 선택.** 트래커(GitHub, Linear 등)에서 자율 구현에 충분히 범위가 지정된 이슈 하나를 선택한다 — 범위가 한정되고, 관찰 가능한 수락 기준이 있으며, 실행을 막는 업스트림 의존성이 없는 것.
2. **GSD 단계에 매핑.** 이슈가 `ROADMAP.md`의 기존 단계에 매핑된다면 선택한다. 그렇지 않으면 `/gsd-new-milestone`(관련 이슈들의 새 마일스톤을 위한)을 실행하거나 `/gsd-phase` / `/gsd-phase --insert`를 통해 단계를 열어라. 압축 후에도 추적 가능성이 유지되도록 단계의 `CONTEXT.md`에 트래커 이슈 URL을 캡처하라.
3. **격리된 워크스페이스 생성.** `/gsd-workspace --new --strategy worktree <slug>`를 실행하여 독립적인 `.planning/` 디렉터리를 가진 git worktree를 생성한다. worktree가 안전 경계이다: 모든 탐색, 부분 커밋, 중단된 계획이 `main` 밖에 머문다.
4. **GSD를 통해 discuss → plan → execute 실행.** 워크스페이스 내에서 `/gsd-discuss-phase`로 모호함을 명확히 하고, `/gsd-plan-phase`로 `PLAN.md`를 생성하고, `/gsd-manager`(대화형 대시보드) 또는 `/gsd-execute-phase` / `/gsd-autonomous`(무인)로 구현한다. GSD 외부에서 raw `claude` 호출을 구동하는 것을 피하라 — 그것은 `STATE.md` 업데이트와 단계 매니페스트를 우회한다.
5. **작업 증명 요구.** `/gsd-verify-work`를 실행하여 사용자가 단계의 수락 기준에 대해 UAT를 진행하도록 안내한다. 테스트, 스크린샷, 로그 캡처, 설정 차이가 모두 `UAT.md`에 기록되며, 이것은 `/clear` 전반에 걸쳐 지속되고 검증이 놓친 범위를 표면화할 때 `/gsd-plan-phase --gaps`에 공급된다.
6. **리뷰 및 출시 게이트 통과.** `/gsd-review`를 실행하여 독립적인 AI CLI들로부터 계획의 적대적 동료 리뷰를 받고(모델별 맹점 포착), 그런 다음 `/gsd-ship`을 실행하여 계획 결과물로 구성된 풍부한 본문으로 PR을 열어라. 두 게이트 모두 원격에 도달하기 전에 사람의 결정을 요구한다.
7. **후속 작업 명시적으로 캡처.** 인라인 메모에는 `/gsd-capture`를, 미래 단계가 될 아이디어에는 `/gsd-capture --seed`를, 일관된 후속 작업 그룹에는 `/gsd-new-milestone`을 사용하라. 발견된 후속 작업에서 트래커 이슈를 생성하는 것은 명시적인 사용자 확인이 필요하다 — GSD는 원격 트래커에 자동으로 게시하지 않는다.
PR이 병합되면 루프가 닫힌다. PR 본문의 자동 닫기 키워드들(`Closes #NNN` / `Fixes #NNN`)이 병합 시점에 트래커 이슈를 닫는다.
## 안전 경계
루프는 네 가지 불변성이 구성상 유지되기 때문에 안전하다:
- **격리된 worktree.** 모든 이슈는 `/gsd-workspace --new` worktree에서 실행되므로 부분 작업, 중단된 계획, 탐색적 커밋이 `main`에 절대 닿지 않는다. `gsd-local-patches/`가 worktree의 수동 편집이 업데이트 후에 다시 돌아와야 할 경우의 복구 표면이다.
- **명시적 사람 리뷰.** `/gsd-review`와 `/gsd-ship` 모두 사람 승인을 위해 중지된다. 자동 병합도 실행에서 자동 PR 경로도 없다. 특정 저장소에 대해 사람 게이트를 제거하고 싶다면, 그것은 사용자의 브랜치 보호 / 병합 큐 정책 결정이지 GSD가 사용자 대신 선택하는 것이 아니다.
- **자동 공개 게시 없음.** GSD는 명시적으로 사용자가 시작한 명령어 없이는 트래커 이슈를 열거나, 댓글을 달거나, 닫지 않는다. 후속 캡처는 기본적으로 로컬 결과물(메모, 시드, 마일스톤)에 저장된다; 트래커에 다시 푸시하는 것은 별도의 수동 단계이다.
- **출시 전 검증.** `/gsd-verify-work`의 UAT.md는 `/gsd-ship`이 실행되기 전에 증거를 기록해야 한다. 권장 원칙은 구현이 올바르게 보일 때도 `verification_failed`를 차단제로 취급하는 것이다 — 실패는 일반적으로 불안정한 테스트가 아닌 놓친 수락 기준을 표면화한다.
이 불변성 중 하나라도 우회되면(예: worktree에 직접 `claude`를 실행하거나, `/gsd-verify-work`를 건너뛰거나, 사용자 확인 없이 트래커 API를 통해 이슈 생성을 스크립팅하는 경우), 이 가이드의 보장이 적용되지 않는다.
## 비목표
이 가이드는 의도적으로 다음 중 어느 것도 제안하지 않는다. 코드 리뷰에서 재논의되지 않도록 여기에 나열한다:
- **Symphony 코드 벤더링이나 복사 없음.** GSD는 자체 기본 도구를 재사용한다. 위의 매핑은 개념적이다; 이 저장소에 Symphony 파생 소스가 없다.
- **장시간 실행 데몬 없음.** GSD는 GitHub이나 Linear를 폴링하지 않는다. manager와 autonomous 워크플로우는 데몬이 아닌 background-agent 의미를 통해 동시성을 처리한다.
- **필수 트래커 의존성 없음.** 루프는 트래커 통합 없이도 작동한다. "트래커 이슈" 단계는 *사람 입력*이다 — URL이 `CONTEXT.md`에 들어간다. GSD는 어떤 트래커를 사용하는지, 또는 트래커를 사용하는지에 대해 의견이 없다.
- **검증, 리뷰, 사람 결정 게이트 우회 없음.** `/gsd-autonomous`를 실행할 때도 검증 및 리뷰 게이트가 여전히 실행된다. "autonomous" 레이블은 단계 간 진행을 가리키며, 사람 승인 건너뛰기를 가리키지 않는다.
- **기본 스킬 / 명령어 표면 확장 없음.** 이 가이드에 참조된 모든 명령어들은 이미 존재한다. 이 가이드는 문서 표면이지, 기능 표면이 아니다.
## 가능한 미래 후속 작업
이 루프에 대한 유지관리자 경험이 정당화된다면, 별도의 승인된 개선 사항이 나중에 *최소한의* 트래커 브리지를 추가할 수 있다:
- 하나의 GitHub 또는 Linear 이슈를 GSD 워크스페이스 / 단계로 가져오기.
- `UAT.md` 증거를 소스 이슈의 댓글로 내보내기.
- `/gsd-capture --seed` 출력에서 후속 트래커 이슈 생성.
그 각각은 통합 표면과 지속적인 유지 관리 부담을 추가하기 때문에 자체 개선 제안이 될 것이다. 이 가이드의 범위에서 벗어난다.
## Related
- [단계 루프](explanation/the-phase-loop.md) — 논의 → 계획 → 실행 → 검증 → 출시가 반복되는 사이클로 어떻게 맞물리는지.
- [워크스페이스 how-to](how-to/work-in-parallel-with-workstreams.md) — 병렬 worktree를 생성하고 관리하는 단계별 가이드.
- [문서 인덱스](README.md) — GSD Core 문서의 전체 목차.
- [docs/USER-GUIDE.md](./USER-GUIDE.md) — 위에 참조된 개별 명령어들의 작업 지향 안내서.
- [docs/COMMANDS.md](COMMANDS.md) — `/gsd-*` 명령어의 전체 레퍼런스.
- [docs/FEATURES.md](FEATURES.md) — 기능 수준 역량 매트릭스 (워크스페이스, manager, autonomous, verify, review, ship).
- [docs/ARCHITECTURE.md](ARCHITECTURE.md) — 단계 결과물 수명 주기와 `STATE.md` 메카닉.

148
docs/ko-KR/reference/context-md.md Normal file
View File

@@ -0,0 +1,148 @@
# CONTEXT.md 스키마 참조
페이즈별 `CONTEXT.md`는 `/gsd:discuss-phase` 중 캡처된 구현 결정을 담는 GSD Core의 파일입니다. 이 파일은 리서치 에이전트와 플래닝 에이전트 모두를 위한 주요 업스트림 입력입니다. 이 페이지는 해당 파일의 구조를 설명합니다. [문서 인덱스](../../README.md)를 참조하세요.
---
## 개요
논의 워크플로를 거친 모든 페이즈는 다음 위치에 하나의 `CONTEXT.md`를 생성합니다:
```
.planning/phases/<NN>-<slug>/<NN>-CONTEXT.md
```
예: `.planning/phases/03-post-feed/03-CONTEXT.md`.
이 파일은 `get-shit-done/workflows/discuss-phase.md`의 `write_context`(또는 PRD / ADR 인제스트 익스프레스 경로)에 의해 생성됩니다. 일반적인 운영 중에는 절대로 수동으로 편집하지 않습니다 — discuss-phase 워크플로가 이 파일을 기록하고 다운스트림 에이전트는 이를 봉인된 진실의 원천으로 읽습니다.
---
## 프론트매터
`CONTEXT.md`에는 YAML 프론트매터가 없습니다. 메타데이터는 본문 상단에 인라인으로 위치합니다:
```markdown
# Phase [X]: [Name] - Context
**Gathered:** [ISO date]
**Status:** Ready for planning
```
`Status` 필드는 파일이 처음 기록될 때 항상 `Ready for planning`입니다. 생성 후에는 업데이트되지 않습니다.
---
## 블록 구조
본문은 이름이 붙여진 XML 스타일 블록으로 나뉩니다. 블록은 고정된 순서로 나타나며 다운스트림 에이전트는 줄 번호가 아닌 블록 이름으로 읽습니다.
| 블록 | 목적 | 작성자 | 소비자 |
|---|---|---|---|
| `<domain>` | 페이즈 경계를 명시합니다 — 이 페이즈가 무엇을 전달하고 명시적으로 범위 밖인 것이 무엇인지. 플래닝과 실행 전반에 걸쳐 범위 가드레일을 고정합니다. | `discuss-phase` (ROADMAP.md 페이즈 목표에서) | `gsd-planner`, `gsd-plan-checker` (범위 준수) |
| `<spec_lock>` | `check_spec` 단계에서 `*-SPEC.md`가 발견된 경우에만 존재합니다. 잠긴 요구사항 수와 범위 경계를 나열하며, 에이전트는 전체 요구사항을 위해 `SPEC.md`를 직접 읽도록 안내됩니다. | `discuss-phase` (조건부) | `gsd-planner` (요구사항을 여기서 재읽지 않고 SPEC.md를 읽음) |
| `<decisions>` | 논의에서 캡처된 구현 결정으로 `D-NN` 식별자로 키가 지정됩니다. 카테고리는 고정된 분류법이 아닌 실제로 논의된 내용에서 나옵니다. 사용자가 위임한 영역을 위한 `Claude's Discretion` 하위 섹션을 포함합니다. | `discuss-phase` (대화형 토론) | `gsd-planner` (잠긴 결정은 반드시 구현되어야 함), `gsd-plan-checker` (Dimension 7 준수) |
| `<canonical_refs>` | 이 페이즈와 관련된 모든 spec, ADR, 기능 문서, 또는 설계 문서의 전체 상대 경로. 필수 — 모든 CONTEXT.md에 이 섹션이 있어야 합니다. 에이전트는 플래닝 또는 구현 전에 나열된 파일을 읽어야 합니다. | `discuss-phase` (ROADMAP.md 참조 + 토론 중 사용자 참조 + 코드베이스 스카우트에서 축적) | `gsd-phase-researcher`, `gsd-planner` |
| `<code_context>` | `scout_codebase` 단계에서 발견된 재사용 가능한 자산, 확립된 패턴, 통합 지점. 에이전트가 재구현하는 대신 기존 코드를 활용하도록 안내합니다. | `discuss-phase` (코드베이스 스카우트) | `gsd-planner`, `gsd-phase-researcher` |
| `<specifics>` | 토론 중 캡처된 구체적인 "X처럼 하고 싶다" 참조, 제품 비교, 또는 특정 예시. | `discuss-phase` (자유형 사용자 입력) | `gsd-planner` |
| `<deferred>` | 토론에서 제기되었지만 다른 페이즈에 속하는 아이디어. 잃어버리지 않도록 보존됩니다. todo가 검토되었지만 범위에 포함되지 않은 경우 `Reviewed Todos` 하위 섹션을 포함합니다. | `discuss-phase` (범위 초과 리디렉션) | 자동화된 에이전트가 소비하지 않음; 인간 참조 전용 |
---
## 결정 식별자 형식
`<decisions>`의 모든 결정에는 순차적인 `D-NN` 식별자가 있습니다:
```markdown
### Layout style
- **D-01:** Card-based layout, not timeline or list
- **D-02:** Each card shows: author avatar, name, timestamp, full post content, reaction counts
```
식별자는 페이즈 범위입니다. Phase 3의 `D-01`은 Phase 7의 `D-01`과 관계없습니다. 플랜 체커(Dimension 7)는 모든 `D-NN`이 생성된 플랜의 적어도 하나의 태스크 액션에서 다루어지는지 검증합니다.
---
## 표준 참조
`<canonical_refs>` 블록은 **필수**입니다. 이 블록이 없는 CONTEXT.md를 발견한 에이전트는 CONTEXT.md를 불완전한 것으로 처리하고 경고를 표시합니다. 항목은 주제별로 그룹화되며 전체 상대 경로와 파일이 결정하거나 정의하는 내용에 대한 간략한 설명을 포함합니다:
```markdown
<canonical_refs>
## Canonical References
**Downstream agents MUST read these before planning or implementing.**
### Feed display
- `docs/features/social-feed.md` — Feed requirements, post card fields, engagement display rules
- `docs/decisions/adr-012-infinite-scroll.md` — Scroll strategy decision, virtualisation requirements
### Empty states
- `docs/design/empty-states.md` — Empty state patterns, illustration guidelines
</canonical_refs>
```
프로젝트에 외부 spec이 없는 경우, 섹션은 이를 명시적으로 기술합니다:
```
No external specs — requirements fully captured in decisions above
```
`<decisions>` 안에 흩어진 "ADR-019 참조" 같은 인라인 언급은 불충분합니다. 에이전트는 전용 섹션에 전체 경로가 필요합니다.
---
## 결정 커버리지 게이트 관계
플랜 체커의 **Dimension 7: Context Compliance**는 플래닝 후 커버리지 게이트를 강제합니다:
1. `<decisions>`의 모든 `D-NN` 식별자는 적어도 하나의 플랜 태스크의 `<action>` 또는 근거에 나타나야 합니다.
2. 어떤 태스크도 `<deferred>`에 나열된 것을 구현해서는 안 됩니다(범위 초과).
3. `Claude's Discretion` 영역은 이 확인에서 제외됩니다 — 플래너는 자유롭게 선택할 수 있습니다.
결정이 플랜에 반영된 CONTEXT.md는 준수 상태로 간주됩니다. 결정이 조용히 삭제되거나 부분적으로만 전달된 CONTEXT.md는 **Dimension 7b: Scope Reduction Detection**을 트리거하며, 이는 항상 BLOCKER입니다.
---
## SPEC.md 통합
페이즈를 논의하기 전에 `/gsd:spec-phase`가 실행된 경우, `check_spec` 단계에서 `*-SPEC.md` 파일을 찾아 `<spec_lock>`을 활성화합니다:
```markdown
<spec_lock>
## Requirements (locked via SPEC.md)
**12 requirements are locked.** See `03-SPEC.md` for full requirements, boundaries, and acceptance criteria.
Downstream agents MUST read `03-SPEC.md` before planning or implementing. Requirements are not duplicated here.
**In scope (from SPEC.md):** [copied from SPEC.md Boundaries]
**Out of scope (from SPEC.md):** [copied from SPEC.md Boundaries]
</spec_lock>
```
`<spec_lock>`이 있는 경우, `<decisions>`는 토론에서 나온 구현 결정만 포함합니다 — "무엇을"이 아닌 "어떻게". 요구사항은 두 파일 간에 중복되지 않습니다.
---
## 푸터
모든 CONTEXT.md는 아이덴티티 푸터로 끝납니다:
```markdown
---
*Phase: XX-name*
*Context gathered: [date]*
```
---
## Related
- [PLAN.md 스키마](plan-md.md)
- [Planning artifacts](planning-artifacts.md)
- [Discuss 모드](../../workflow-discuss-mode.md)
- [docs index](../../README.md)

249
docs/ko-KR/reference/plan-md.md Normal file
View File

@@ -0,0 +1,249 @@
# PLAN.md 스키마 참조
플랜별 `PLAN.md`는 GSD Core의 실행 가능한 작업 단위입니다 — 실행기 에이전트에게 무엇을 빌드해야 하고 올바르게 빌드되었는지 어떻게 검증할지를 정확히 알려주는 구조화된 문서입니다. 이 페이지는 해당 파일의 구조를 설명합니다. [문서 인덱스](../../README.md)를 참조하세요.
---
## 개요
플랜은 다음 위치의 페이즈 디렉터리 내에 있습니다:
```
.planning/phases/<NN>-<slug>/<NN>-<PP>-PLAN.md
```
예: `.planning/phases/03-post-feed/03-02-PLAN.md` (Phase 3, Plan 2).
플랜은 `gsd-planner` 에이전트(`/gsd:plan-phase`에 의해 생성됨)가 만들고 `execute-phase`가 소비합니다. 페이즈는 보통 1~4개의 플랜을 포함하며, 페이즈 내의 플랜은 독립적인 작업이 병렬로 실행되도록 실행 웨이브에 할당됩니다.
---
## YAML 프론트매터
모든 PLAN.md는 `---` 구분자 사이의 YAML 프론트매터 블록으로 시작합니다.
### 주석이 달린 예시
```yaml
---
phase: 03-post-feed
plan: 02
type: execute
wave: 2
depends_on: ["03-01"]
files_modified:
- src/components/PostFeed.tsx
- src/components/PostCard.tsx
- src/app/feed/page.tsx
autonomous: true
requirements: ["FEED-01", "FEED-03"]
user_setup: []
must_haves:
truths:
- "User can scroll through posts from followed accounts"
- "Each post shows author avatar, name, timestamp, and content"
- "Empty state appears when no posts exist"
artifacts:
- path: "src/components/PostFeed.tsx"
provides: "Scrollable post list"
min_lines: 40
- path: "src/components/PostCard.tsx"
provides: "Individual post card"
exports: ["PostCard"]
key_links:
- from: "src/components/PostFeed.tsx"
to: "/api/feed"
via: "fetch in useEffect"
pattern: "fetch.*api/feed"
---
```
### 프론트매터 필드 참조
| 필드 | 필수 | 타입 | 목적 |
|---|---|---|---|
| `phase` | 예 | string | 페이즈 식별자, 예: `03-post-feed`. |
| `plan` | 예 | string | 페이즈 내 플랜 번호, 예: `02`. |
| `type` | 예 | `execute` 또는 `tdd` | 표준 플랜의 경우 `execute`; 구현 전에 테스트를 먼저 작성하는 테스트 주도 플랜의 경우 `tdd`. |
| `wave` | 예 | integer | 실행 웨이브. 웨이브 1의 플랜은 병렬로 실행됩니다(의존성 없음). 웨이브 2 이상의 플랜은 이전 웨이브의 모든 플랜이 완료될 때까지 기다립니다. `gsd-planner`가 플래닝 시점에 미리 계산합니다. |
| `depends_on` | 예 | 플랜 ID 배열 | 이 플랜이 기다려야 하는 플랜. 빈 배열 = 웨이브 1. 예: `["03-01"]`은 이 플랜이 Phase 3의 Plan 01 이후에 실행됨을 의미합니다. |
| `files_modified` | 예 | 경로 배열 | 이 플랜이 생성하거나 수정하는 모든 파일. 플랜 체커가 동일 웨이브 파일 충돌을 감지하고 execute-phase가 머지 추적에 사용합니다. |
| `autonomous` | 예 | boolean | 모든 태스크가 `auto` 타입일 때 `true`. 플랜에 인간 상호작용이 필요한 `checkpoint:*` 태스크가 포함된 경우 `false`. |
| `requirements` | 예 | ID 배열 | 이 플랜이 처리하는 ROADMAP.md의 요구사항 ID. 모든 페이즈 요구사항 ID는 적어도 하나의 플랜의 `requirements` 필드에 나타나야 합니다. 빈 배열은 BLOCKER입니다. |
| `user_setup` | 아니오 | 객체 배열 | Claude가 자동화할 수 없는 외부 서비스 설정 단계(계정 생성, 시크릿 검색, 대시보드 구성). 있는 경우, execute-phase가 개발자를 위한 `USER-SETUP.md` 체크리스트를 생성합니다. |
| `must_haves` | 예 | 객체 | 목표 역방향 검증 기준. 아래를 참조하세요. |
---
## `must_haves` 필드
`must_haves`는 페이즈 목표 달성을 위해 관찰 가능하게 참이어야 하는 것을 캡처합니다. 플래닝 중에 도출되며 실행 후 `gsd-verifier` 에이전트가 검증합니다.
### 하위 필드
| 하위 필드 | 타입 | 목적 |
|---|---|---|
| `truths` | string 배열 | 사용자 관점에서의 관찰 가능한 동작. 각각은 검증 가능해야 합니다. 예: `"User can send a message"` (O), `"WebSocket library installed"` (X). |
| `artifacts` | 객체 배열 | 실질적인 구현이 있어야 하는 파일(스텁 불가). |
| `artifacts[].path` | string | 프로젝트 루트에 대한 상대 파일 경로. |
| `artifacts[].provides` | string | 이 파일이 제공하는 기능. |
| `artifacts[].min_lines` | integer (선택) | 스텁이 아닌 것으로 간주되기 위한 최소 행 수. |
| `artifacts[].exports` | string 배열 (선택) | 검증할 예상 이름 있는 export. |
| `artifacts[].contains` | string (선택) | 파일에 나타나야 하는 정규식 또는 리터럴 패턴. |
| `key_links` | 객체 배열 | 아티팩트 간의 중요한 연결 — 시스템이 엔드 투 엔드로 작동하게 하는 배선. |
| `key_links[].from` | string | 소스 파일 또는 컴포넌트. |
| `key_links[].to` | string | 대상 파일, 엔드포인트, 또는 모듈. |
| `key_links[].via` | string | 연결 방법 설명 (예: `fetch in useEffect`, `Prisma query`, `import`). |
| `key_links[].pattern` | string (선택) | 소스에 연결이 존재하는지 검증하기 위한 정규식. |
---
## 본문 구조
프론트매터 이후, 플랜 본문은 실행기 에이전트가 읽는 이름 붙여진 XML 스타일 블록을 사용합니다.
### `<objective>`
플랜이 무엇을 전달하고 프로젝트에서 왜 중요한지를 기술합니다:
```xml
<objective>
Implement the post feed as a scrollable card list.
Purpose: Core display feature for the social feed phase.
Output: PostFeed and PostCard components wired to /api/feed.
</objective>
```
### `<execution_context>`
실행기가 시작 전에 읽는 워크플로 파일을 나열합니다. 항상 execute-plan 워크플로를 포함하며, 플랜에 체크포인트 태스크가 포함된 경우 체크포인트 참조를 추가합니다:
```xml
<execution_context>
@~/.claude/get-shit-done/workflows/execute-plan.md
@~/.claude/get-shit-done/templates/summary.md
</execution_context>
```
### `<context>`
실행기가 읽어야 하는 소스 파일을 참조합니다. 프로젝트 수준 플래닝 문서와 플랜이 복제해야 하는 패턴이나 타입을 가진 소스 파일을 포함합니다. 이전 플랜의 `SUMMARY.md` 파일은 타입이나 공유 결정에 대한 실질적인 의존성이 있는 경우에만 포함됩니다 — 반사적으로 포함하지 않습니다:
```xml
<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/STATE.md
@src/components/UserCard.tsx
</context>
```
### `<tasks>`
하나 이상의 `<task>` 요소를 포함합니다. 모든 태스크 요소는 `type="auto"` 태스크의 경우 `<name>`, `<files>`, `<read_first>`, `<action>`, `<verify>`, `<acceptance_criteria>`, `<done>`을 가져야 합니다.
---
## 태스크 타입
| 타입 | 사용 시점 | 자율성 |
|---|---|---|
| `auto` | 실행기가 독립적으로 할 수 있는 모든 것. | 완전 자율. |
| `checkpoint:human-verify` | 실행 중인 UI 또는 서비스를 인간이 직접 봐야 하는 시각적 또는 기능적 검증. | 실행 일시 중지; 개발자에게 표시; 승인 시 재개. |
| `checkpoint:decision` | 실행 중에 발생하여 개발자 입력이 필요한 구현 선택. | 실행 일시 중지; 옵션 표시; 선택 시 재개. |
| `checkpoint:human-action` | 진정으로 불가피한 수동 단계(계정 생성, 하드웨어 상호작용). 드물게 사용. | 실행 일시 중지; 확인 시 재개. |
체크포인트 태스크가 포함된 플랜은 프론트매터에서 `autonomous: false`로 설정해야 합니다.
---
## `auto` 태스크 구조
```xml
<task type="auto">
<name>Task 1: Create PostCard component</name>
<files>src/components/PostCard.tsx</files>
<read_first>src/components/UserCard.tsx, src/types/post.ts</read_first>
<action>Create PostCard component accepting a Post prop (id, authorId, content, createdAt,
reactionCount). Render author avatar using UserAvatar from UserCard pattern. Show timestamp
using date-fns formatDistanceToNow. Export as named export PostCard.</action>
<verify>npx tsc --noEmit</verify>
<acceptance_criteria>
- src/components/PostCard.tsx exports named export PostCard
- PostCard.tsx contains "reactionCount" prop usage
- npx tsc --noEmit exits 0
</acceptance_criteria>
<done>PostCard renders post content with author and timestamp</done>
</task>
```
### `auto` 태스크의 필수 필드
| 필드 | 규칙 |
|---|---|
| `<files>` | 태스크가 생성하거나 수정하는 모든 파일. 실행기는 이 파일들만 작성합니다. |
| `<read_first>` | 무언가를 건드리기 전에 실행기가 읽어야 하는 파일 — 수정할 파일, 진실의 원천 패턴 파일, 타입이나 규칙을 복제해야 하는 파일. |
| `<action>` | 정확한 식별자, 파일 경로, 함수 서명, 예상 값이 포함된 구체적인 지침. 목표 상태를 지정하지 않고 "X를 Y와 맞추세요"라고 말하지 않습니다. 펜스 코드 블록이나 전체 구현을 포함하지 않습니다. |
| `<verify>` | 태스크가 성공했음을 증명하는 실행 가능한 명령 또는 확인. 통과와 실패를 구분해야 합니다 — `echo "done"`은 유효하지 않습니다. |
| `<acceptance_criteria>` | 검증 가능한 조건: grep으로 검증 가능한 문자열, 명령 종료 코드, 관찰 가능한 동작. 주관적 표현 없음 ("올바르게 보임", "올바르게 구성됨"). |
| `<done>` | 완료된 결과에 대한 짧은 측정 가능한 설명. |
---
## 플랜 품질 차원
`gsd-plan-checker` 에이전트는 실행 시작 전에 12개 차원에 걸쳐 모든 PLAN.md를 검토합니다. BLOCKER 심각도 확인에 실패한 플랜은 수정을 위해 `gsd-planner`에 반환됩니다(최대 3회 반복):
| 차원 | 확인 내용 |
|---|---|
| **1 — 요구사항 커버리지** | ROADMAP.md의 모든 페이즈 요구사항 ID가 적어도 하나의 플랜의 `requirements` 프론트매터 필드에 나타나고 해당 태스크가 있는지. |
| **2 — 태스크 완전성** | 모든 `auto` 태스크에 필수 필드(`<files>`, `<action>`, `<verify>`, `<acceptance_criteria>`, `<done>`)가 있는지. 모호하거나 빈 필드 없음. |
| **3 — 의존성 정확성** | `depends_on` 참조가 유효하고 비순환적이며 웨이브 번호와 일관성이 있는지. 웨이브 N 플랜은 웨이브 < N의 플랜에만 의존합니다. |
| **4 — 키 링크 계획됨** | `must_haves.key_links`의 아티팩트에 배선을 구현하는 해당 태스크가 있는지 — 아티팩트 생성만이 아닌. |
| **5 — 범위 건전성** | 플랜이 컨텍스트 예산 내에 있는지: 플랜당 2–3개 태스크(4개 = 경고, 5개 이상 = BLOCKER), 플랜당 파일 ≤ 8–10개(15개 이상 = BLOCKER). |
| **6 — 검증 도출** | `must_haves.truths`가 구현 세부 사항이 아닌 사용자 관찰 가능한 동작인지. 아티팩트가 truths에 매핑되는지. 키 링크가 중요한 배선을 커버하는지. |
| **7 — 컨텍스트 준수** | CONTEXT.md의 모든 `D-NN` 결정이 적어도 하나의 태스크에서 다루어지는지. 어떤 태스크도 `<deferred>`의 것을 구현하지 않는지. |
| **7b — 범위 축소 감지** | 태스크 액션이 전체 결정 범위를 전달하지 않고 잠긴 결정을 조용히 "v1", "스텁", 또는 "향후 개선"으로 축소하지 않는지. 발견 시 항상 BLOCKER. |
| **7c — 아키텍처 계층 준수** | 태스크가 RESEARCH.md 아키텍처 책임 맵에 따라 올바른 계층에 기능을 할당하는지 (있는 경우). 잘못된 계층의 보안 민감 기능은 BLOCKER. |
| **8 — Nyquist 준수** | `workflow.nyquist_validation`이 활성화되고 RESEARCH.md가 있는 경우, 모든 태스크에 `<automated>` 검증 명령이 있고, 3개 태스크의 연속 구간이 커버리지 없이 없으며, VALIDATION.md가 있는지. |
| **9 — 크로스 플랜 데이터 계약** | 플랜이 데이터 파이프라인을 공유하는 경우, 변환이 호환 가능한지 — 어떤 플랜도 다른 플랜이 원본 형식으로 필요한 데이터를 제거하지 않는지. |
| **10 — CLAUDE.md 준수** | 플랜이 `./CLAUDE.md`의 프로젝트별 규칙, 금지된 패턴, 필수 도구, 보안 요구사항을 존중하는지. |
| **11 — 리서치 해결** | RESEARCH.md가 있는 경우, 플래닝이 진행되기 전에 `## Open Questions` 섹션이 `(RESOLVED)`로 표시되어 있는지. |
| **12 — 패턴 준수** | PATTERNS.md가 있는 경우, 태스크가 각 새로운 또는 수정된 파일에 대해 올바른 유사 패턴을 참조하는지. |
---
## 웨이브 실행 모델
웨이브 번호는 플래닝 중에 미리 계산됩니다. Execute-phase는 플랜을 웨이브 번호별로 그룹화하고 각 웨이브의 플랜을 병렬로 실행합니다:
```
Wave 1: Plan 01, Plan 02, Plan 03 (모두 동시에 실행 — 의존성 없음)
Wave 2: Plan 04 (Wave 1이 완료될 때까지 대기)
Wave 3: Plan 05 (Wave 2가 완료될 때까지 대기)
```
동일한 웨이브 내에서 겹치는 파일을 수정하는 플랜은 동일한 웨이브에 있어서는 안 됩니다 — 플랜 체커의 Dimension 3이 이를 BLOCKER로 플래그합니다.
---
## 플랜 출력
플랜이 성공적으로 실행된 후, 실행기는 다음 위치에 SUMMARY.md를 작성합니다:
```
.planning/phases/<NN>-<slug>/<NN>-<PP>-SUMMARY.md
```
SUMMARY.md는 빌드된 내용의 표준 기록입니다. 동일 페이즈의 후속 플랜은 타입이나 결정에 대한 실질적인 의존성이 있는 경우 이를 참조할 수 있습니다.
---
## Related
- [CONTEXT.md 스키마](context-md.md)
- [Planning artifacts](planning-artifacts.md)
- [Features](../../FEATURES.md)
- [docs index](../../README.md)

225
docs/ko-KR/reference/planning-artifacts.md Normal file
View File

@@ -0,0 +1,225 @@
# Planning artifacts 참조
`.planning/` 디렉터리는 프로젝트를 위한 GSD Core의 공유 메모리입니다. 모든 워크플로가 여기서 읽고 쓰며, 감사 가능한 결정 추적 기록을 남깁니다. 이 페이지는 모든 파일, 그 목적, 그리고 어떤 명령이 생성하거나 소비하는지를 매핑합니다. [문서 인덱스](../../README.md)를 참조하세요.
---
## 디렉터리 구조
```
.planning/
├── PROJECT.md # 프로젝트 아이덴티티와 핵심 가치
├── ROADMAP.md # 마일스톤 + 목표가 있는 페이즈 목록
├── REQUIREMENTS.md # 번호가 매겨진 인수 기준
├── STATE.md # 살아있는 위치 추적기
├── config.json # 워크플로 및 모델 구성
├── MILESTONES.md # 마일스톤 아카이브 (선택)
├── BACKLOG.md # 미뤄진 및 향후 작업 (선택)
├── LEARNINGS.md # 축적된 크로스 페이즈 학습 (선택)
├── DECISIONS-INDEX.md # 이전 결정의 롤링 요약 (선택)
├── METHODOLOGY.md # 재사용 가능한 해석 프레임워크 (선택)
├── HANDOFF.json # 기계가 읽을 수 있는 일시 정지 상태 (임시)
├── codebase/ # 코드베이스 맵 (선택)
│ ├── architecture.md
│ ├── stack.md
│ └── ...
├── intel/ # 쿼리 가능한 심볼 인덱스 (선택, intel.enabled)
│ └── API-SURFACE.md
└── phases/
└── <NN>-<slug>/ # 페이즈당 하나의 디렉터리
├── <NN>-CONTEXT.md # 구현 결정 (discuss-phase)
├── <NN>-DISCUSSION-LOG.md # 사람이 읽을 수 있는 토론 감사 (discuss-phase)
├── <NN>-RESEARCH.md # 기술 리서치 결과 (plan-phase)
├── <NN>-VALIDATION.md # Nyquist 테스트 커버리지 전략 (plan-phase)
├── <NN>-PATTERNS.md # 코드베이스 유사 맵 (plan-phase, 선택)
├── <NN>-<PP>-PLAN.md # 실행 가능한 플랜 (plan-phase, 플랜당 하나)
├── <NN>-<PP>-SUMMARY.md # 실행 기록 (execute-phase, 플랜당 하나)
├── <NN>-VERIFICATION.md # 페이즈 목표 검증 보고서 (verify-phase)
├── <NN>-UAT.md # 지속적인 UAT 세션 상태 (execute-phase)
└── .continue-here.md # 일시 정지 후 재개 지침 (pause-work)
```
---
## 루트 수준 아티팩트
### `PROJECT.md`
| | |
|---|---|
| **목적** | 표준 프로젝트 아이덴티티: 무엇인지, 누구를 위한 것인지, 핵심 가치, 요구사항, 제약 사항, 주요 결정. 제품이 발전함에 따라 프로젝트 생명주기 전반에 걸쳐 업데이트됩니다. |
| **생성자** | `/gsd-new-project` (최초 생성); 결정이 검증됨에 따라 `/gsd-complete-milestone`에 의해 업데이트됩니다. |
| **소비자** | 모든 플래닝 워크플로; `gsd-phase-researcher`, `gsd-planner` (컨텍스트); `discuss-phase` (이전 결정); `gsd-plan-checker` (프로젝트 제약 사항). |
### `ROADMAP.md`
| | |
|---|---|
| **목적** | 목표, 요구사항 ID, 성공 기준, 페이즈별 표준 참조가 있는 마일스톤 및 페이즈 목록. 프로젝트가 무엇을 빌드하고 어떤 순서로 하는지에 대한 단일 진실의 원천. |
| **생성자** | `/gsd-new-project` (최초 생성); `/gsd-phase --insert`와 `/gsd-complete-milestone`에 의해 업데이트됩니다. |
| **소비자** | `/gsd-discuss-phase`, `/gsd-plan-phase`, `/gsd-execute-phase`; 페이즈 정보가 필요한 모든 오케스트레이션 명령; `gsd-planner`, `gsd-plan-checker`, `gsd-phase-researcher`. |
### `REQUIREMENTS.md`
| | |
|---|---|
| **목적** | 프로젝트의 번호가 매겨진 체크 가능한 인수 기준. 각 요구사항은 로드맵 페이즈에 매핑되는 ID(예: `AUTH-01`)를 가집니다. 페이즈가 실행됨에 따라 요구사항을 완료로 표시합니다. |
| **생성자** | `/gsd-new-project` (최초 생성); `execute-phase`에 의해 요구사항이 완료로 표시됩니다. |
| **소비자** | `gsd-planner` (플랜은 모든 페이즈 요구사항 ID를 처리해야 함); `gsd-plan-checker` Dimension 1 (요구사항 커버리지); `discuss-phase` (이전 요구사항). |
### `STATE.md`
| | |
|---|---|
| **목적** | 살아있는 위치 추적기 — 현재 페이즈와 플랜, 진행 지표, 누적된 결정, 세션 연속성 노트. 모든 워크플로 실행 시작 시 읽힙니다. 중요한 작업 이후 업데이트됩니다. |
| **생성자** | `/gsd-new-project` (최초 생성); 모든 페이즈 워크플로, `/gsd-pause-work`, `/gsd-resume-work`에 의해 지속적으로 업데이트됩니다. |
| **소비자** | 모든 오케스트레이션 워크플로; `/gsd-progress`; `/gsd-quick`을 통한 임시 태스크 실행; `gsd-planner` 및 `gsd-phase-researcher` (프로젝트 결정). |
전체 필드 참조는 [STATE.md 스키마](state-md.md)를 참조하세요.
### `config.json`
| | |
|---|---|
| **목적** | 워크플로 구성: 모델 프로파일, 리서치 및 플랜 체커 토글, git 브랜칭 전략, Nyquist 검증, 병렬화 설정, 에이전트별 모델 오버라이드. |
| **생성자** | `/gsd-new-project` (최초 생성); `/gsd-settings` (대화형 편집). |
| **소비자** | 모든 워크플로 및 서브에이전트 — `gsd-tools query config-get`을 통해 초기화 시점에 읽습니다. |
전체 스키마는 [CONFIGURATION](../../CONFIGURATION.md)을 참조하세요.
### `MILESTONES.md` (선택)
| | |
|---|---|
| **목적** | 완료된 마일스톤의 역사적 기록. 각 마일스톤이 종료될 때 채워지며, 무엇이 언제 출시되었는지의 아카이브 스냅샷을 제공합니다. |
| **생성자** | `/gsd-complete-milestone`. |
| **소비자** | `/gsd-audit-milestone`; 인간 검토. |
### `DECISIONS-INDEX.md` (선택)
| | |
|---|---|
| **목적** | 이전 페이즈 CONTEXT.md 파일에서 캡처된 결정의 경계가 있는 롤링 요약. 있는 경우, `discuss-phase`는 최대 세 개의 이전 CONTEXT.md 파일을 개별적으로 읽는 대신 이 단일 파일을 읽어 컨텍스트 예산을 절약합니다. |
| **생성자** | 이전 페이즈 수가 롤링 읽기 임계값을 초과할 때 생성됩니다. |
| **소비자** | `discuss-phase` (`load_prior_context` 단계). |
### `HANDOFF.json` (임시)
| | |
|---|---|
| **목적** | 작업이 중단될 때 기록되는 기계가 읽을 수 있는 일시 정지 상태. 재개 지점, 진행 중인 컨텍스트, 연속 지침을 포함합니다. 정확히 한 번 소비됩니다 — 재개 시. |
| **생성자** | `/gsd-pause-work`. |
| **소비자** | `/gsd-resume-work`. |
---
## 페이즈별 아티팩트
모든 페이즈별 파일은 `.planning/phases/<NN>-<slug>/` 아래에 있으며, 여기서 `NN`은 제로 패딩된 페이즈 번호이고 `slug`는 하이픈으로 연결된 페이즈 이름입니다.
### `<NN>-CONTEXT.md`
| | |
|---|---|
| **목적** | 플래닝 시작 전에 캡처된 구현 결정. 페이즈 경계(`<domain>`), `D-NN` 식별자가 있는 잠긴 결정(`<decisions>`), 표준 문서 참조(`<canonical_refs>`), 기존 코드 인사이트(`<code_context>`), 특정 영감(`<specifics>`), 미뤄진 아이디어(`<deferred>`)를 포함합니다. |
| **생성자** | `/gsd-discuss-phase` (대화형 토론 또는 PRD/ADR 익스프레스 경로). |
| **소비자** | `gsd-phase-researcher` (무엇을 조사할지); `gsd-planner` (잠긴 결정); `gsd-plan-checker` Dimension 7 (컨텍스트 준수). |
전체 필드 참조는 [CONTEXT.md 스키마](context-md.md)를 참조하세요.
### `<NN>-DISCUSSION-LOG.md`
| | |
|---|---|
| **목적** | discuss-phase 세션의 사람이 읽을 수 있는 감사 추적: 논의된 영역, 제시된 옵션, 선택된 항목, 미뤄진 아이디어, Claude의 재량에 맡겨진 항목. 자동화된 워크플로에서 소비되지 않습니다. |
| **생성자** | `/gsd-discuss-phase` (`git_commit` 단계). |
| **소비자** | 인간 검토; 회고. |
### `<NN>-RESEARCH.md`
| | |
|---|---|
| **목적** | 플래닝 전에 생성된 기술 리서치 결과. "이 페이즈를 잘 계획하기 위해 무엇을 알아야 하는가?"에 답합니다 — 도메인 분석, 패턴, 위험, 아키텍처 책임 맵, 검증 아키텍처 섹션(Nyquist 게이트에서 사용)을 포함합니다. |
| **생성자** | `/gsd-plan-phase` (via `gsd-phase-researcher` 에이전트). |
| **소비자** | `gsd-planner` (플래닝 입력); `gsd-plan-checker` Dimension 7c (계층 준수), Dimension 8 (Nyquist), Dimension 11 (리서치 해결); `gsd-pattern-mapper` (파일 목록 소스). |
### `<NN>-VALIDATION.md`
| | |
|---|---|
| **목적** | RESEARCH.md의 `## Validation Architecture` 섹션에서 도출된 Nyquist 영감 검증 전략. 플랜이 지켜야 하는 자동화된 테스트 커버리지 요구사항을 지정합니다. |
| **생성자** | `/gsd-plan-phase` (Step 5.5, `workflow.nyquist_validation`이 활성화되고 RESEARCH.md에 Validation Architecture 섹션이 있는 경우). |
| **소비자** | `gsd-plan-checker` Dimension 8 (Check 8e 게이트 — Nyquist 확인이 진행되기 전에 반드시 존재해야 함); `gsd-verifier`. |
### `<NN>-PATTERNS.md`
| | |
|---|---|
| **목적** | `gsd-pattern-mapper`가 생성한 코드베이스 유사 맵. 이 페이즈에서 생성하거나 수정할 각 파일에 대해, 가장 가까운 기존 유사 파일을 식별하고, 파일의 역할과 데이터 흐름을 분류하며, 구체적인 코드 발췌를 추출합니다. 플래너가 일관된 패턴을 사용하도록 안내합니다. |
| **생성자** | `/gsd-plan-phase` (via `gsd-pattern-mapper` 에이전트, 선택; `workflow.pattern_mapper: false`이면 건너뜀). |
| **소비자** | `gsd-planner` (패턴 안내); `gsd-plan-checker` Dimension 12 (패턴 준수). |
### `<NN>-<PP>-PLAN.md`
| | |
|---|---|
| **목적** | 페이즈 내 단일 작업 단위에 대한 실행 가능한 플랜. YAML 프론트매터(웨이브, 의존성, 파일, 요구사항, `must_haves`), 목표, 컨텍스트 참조, `<read_first>`, `<action>`, `<verify>`, `<acceptance_criteria>` 필드가 있는 XML 구조의 태스크, 검증 기준을 포함합니다. |
| **생성자** | `/gsd-plan-phase` (via `gsd-planner` 에이전트). 플랜당 하나의 파일 — 예: `03-02-PLAN.md`는 Phase 3, Plan 2. |
| **소비자** | `/gsd-execute-phase` (실행기 에이전트가 플랜을 읽고 태스크를 실행); `gsd-plan-checker` (실행 전 품질 검토); `gsd-verifier` (실행 후 검증을 위해 `must_haves`를 읽음). |
전체 필드 참조는 [PLAN.md 스키마](plan-md.md)를 참조하세요.
### `<NN>-<PP>-SUMMARY.md`
| | |
|---|---|
| **목적** | 플랜이 완료된 후 기록된 실행 기록. 빌드된 내용, 플랜과의 편차, 인수 기준에 대한 자가 점검, 페이즈의 의존성 그래프를 문서화합니다. |
| **생성자** | `execute-phase` 실행기 에이전트 (각 플랜 실행 종료 시 기록). |
| **소비자** | `/gsd-progress` (페이즈 상태); `gsd-planner` (후속 플랜이 이전 플랜 출력에 대한 실질적인 의존성이 있는 경우); `milestone-summary`. |
### `<NN>-VERIFICATION.md`
| | |
|---|---|
| **목적** | 페이즈 목표 검증 보고서. 실행 후 모든 플랜의 `must_haves.truths`, `must_haves.artifacts`, `must_haves.key_links`를 실제 코드베이스에 대해 확인합니다. `status: passed | gaps_found | human_needed`를 기록합니다. |
| **생성자** | `/gsd-verify-work` (또는 `/gsd-execute-phase` 내의 verify 단계). |
| **소비자** | `plan-phase` 종료된 페이즈 게이트(`status: passed`인 VERIFICATION.md는 페이즈를 `Complete`로 표시하고 `--force` 없이 재플래닝을 차단함); `/gsd-progress`; 인간 검토. |
### `<NN>-UAT.md`
| | |
|---|---|
| **목적** | 지속적인 UAT 세션 추적. 라이브 UAT 세션 전반에 걸쳐 각 테스트 케이스, 예상 관찰 가능한 동작, 결과, 개발자 응답을 기록합니다. YAML 프론트매터(`status`, `phase`, `source`, 타임스탬프)를 가집니다. |
| **생성자** | `/gsd-audit-uat` (대화형 UAT 세션). |
| **소비자** | `/gsd-audit-uat` (이전 UAT 세션 재개). |
### `.continue-here.md`
| | |
|---|---|
| **목적** | 페이즈 작업이 일시 정지될 때 기록되는 사람이 읽을 수 있는 재개 지침. 재개 에이전트를 위한 컨텍스트를 포함합니다: 중요한 안티패턴, 차단 이슈, 필수 읽기, 재개를 위한 정확한 명령. |
| **생성자** | `/gsd-pause-work`. |
| **소비자** | 페이즈에서 시작하는 모든 워크플로 — `discuss-phase`와 `plan-phase` 모두 진입 시 이 파일을 확인하고, 진행하기 전에 에이전트가 `blocking` 안티패턴을 이해했음을 입증하도록 요구합니다. |
---
## 명명 규칙
| 세그먼트 | 형식 | 예시 |
|---|---|---|
| 페이즈 디렉터리 | `<NN>-<slug>` | `03-post-feed` |
| 페이즈 수준 파일 | `<NN>-<ARTIFACT>.md` | `03-CONTEXT.md` |
| 플랜 수준 파일 | `<NN>-<PP>-<ARTIFACT>.md` | `03-02-PLAN.md` |
| `NN` | 제로 패딩된 페이즈 번호 | Phase 3의 경우 `03` |
| `PP` | 페이즈 내 제로 패딩된 플랜 번호 | Plan 2의 경우 `02` |
`config.json`에 `project_code`가 설정된 경우, 페이즈 디렉터리는 프로젝트 코드를 접두사로 사용합니다: 프로젝트 코드 `CK`, Phase 3의 경우 `CK-03-post-feed`.
---
## Related
- [STATE.md 스키마](state-md.md)
- [CONTEXT.md 스키마](context-md.md)
- [PLAN.md 스키마](plan-md.md)
- [docs index](../../README.md)

201
docs/ko-KR/reference/state-md.md Normal file
View File

@@ -0,0 +1,201 @@
# STATE.md 스키마 참조
`STATE.md`는 GSD Core의 살아있는 프로젝트 메모리 파일입니다 — 프로젝트의 현재 상태, 최근 작업 내역, 그리고 다음에 실행할 명령을 기록하는 단일 Markdown 문서입니다. 이 페이지는 해당 파일의 구조를 설명합니다. [문서 인덱스](../../README.md)를 참조하세요.
---
## 개요
GSD Core가 관리하는 모든 프로젝트는 `.planning/STATE.md`에 하나의 `STATE.md`를 유지합니다. 이 파일은 모든 워크플로 시작 시 읽히고 중요한 작업 이후에 기록됩니다. 파일은 다음 두 부분으로 구성됩니다:
- **YAML 프론트매터** — 상태 표시줄 훅(`parseStateMd`)과 `gsd-tools state` 명령이 사용하는 기계가 읽을 수 있는 필드.
- **Markdown 본문** — 현재 위치, 누적된 맥락, 세션 연속성, 성능 지표를 다루는 사람이 읽을 수 있는 섹션.
파일은 의도적으로 작게 유지됩니다(목표: 100줄 미만). 이 파일은 프로젝트 상태의 요약이며 아카이브가 아닙니다.
---
## YAML 프론트매터
프론트매터는 파일 맨 처음의 `---` 구분자 사이에 위치합니다. `gsd_state_version`과 `status`를 제외한 모든 필드는 선택 사항이며, 데이터를 아직 사용할 수 없는 경우 필드가 없을 수 있습니다.
### 주석이 달린 예시
```yaml
---
gsd_state_version: '1.0'
milestone: v2.0
milestone_name: Code Quality
status: executing
# 페이즈 생명주기 필드 — 모두 선택 사항 (v1.40.0에서 추가, issue #2833)
active_phase: "4.5"
next_action: execute-phase
next_phases: ["4.5"]
progress:
total_phases: 17
completed_phases: 10
total_plans: 84
completed_plans: 47
percent: 59
# syncStateFrontmatter가 기록하는 추가 필드
current_phase: "4"
current_phase_name: Observability
current_plan: "3"
last_updated: "2026-06-01T12:34:56.789Z"
last_activity: "2026-06-01"
stopped_at: "Phase 4 P3 execution complete"
paused_at: null
---
```
### 필드 참조
| 필드 | 타입 | 채워지는 시점 | 목적 |
|---|---|---|---|
| `gsd_state_version` | string (`'1.0'`) | 항상 | 스키마 버전. `syncStateFrontmatter`에 의한 첫 번째 `state.*` 호출 시 기록됩니다. |
| `milestone` | string (예: `v2.0`) | 마일스톤이 구성된 경우 | 프로젝트 설정에서 읽어온 현재 마일스톤 버전. |
| `milestone_name` | string | 마일스톤이 구성된 경우 | 사람이 읽을 수 있는 마일스톤 레이블 (예: `Code Quality`). |
| `status` | string | 항상 | 현재 생명주기 단계. `normalizeStateStatus()`에 의해 정규화됩니다 — [상태 값](#상태-값)을 참조하세요. |
| `active_phase` | string (예: `"4.5"`) | 오케스트레이터 명령이 해당 페이즈에서 실행 중인 경우 | 현재 처리 중인 페이즈 번호. 페이즈 사이에 있을 때는 `null`로 설정됩니다. |
| `next_action` | string | 권장 명령이 있는 유휴 상태일 때 | 다음에 실행할 슬래시 명령: `discuss-phase`, `plan-phase`, `execute-phase`, 또는 `verify-phase`. 오케스트레이터가 실행 중이거나 권장 사항이 없을 때는 `null`로 설정됩니다. |
| `next_phases` | YAML 플로우 배열 (예: `["4.5"]`) | `next_action`과 함께 | `next_action`이 적용되는 페이즈 ID (보통 1–2개 항목). `next_action`과 동일한 조건에서 `null`로 설정됩니다. |
| `progress.total_phases` | integer | 페이즈 데이터를 사용할 수 있는 경우 | ROADMAP.md와 phases 디렉터리에서 파생된 현재 마일스톤의 총 페이즈 수. |
| `progress.completed_phases` | integer | 페이즈 데이터를 사용할 수 있는 경우 | 모든 플랜 요약이 디스크에 존재하는(즉, 모든 플랜이 완료된) 페이즈의 수. |
| `progress.total_plans` | integer | 플랜 파일이 존재하는 경우 | 현재 마일스톤 내 모든 페이즈의 플랜 파일 합계. |
| `progress.completed_plans` | integer | 요약 파일이 존재하는 경우 | 완료된 플랜 요약의 합계 (실행된 플랜당 하나의 SUMMARY.md). |
| `progress.percent` | integer 0–100 | 진행 데이터를 사용할 수 있는 경우 | **페이즈 차원**의 마일스톤 진행도 (`min(completed_plans/total_plans, completed_phases/total_phases)`). 상태 표시줄 진행 막대는 이 필드가 있을 때만 렌더링됩니다 — 필드가 없으면 막대가 표시되지 않습니다. |
| `current_phase` | string | 페이즈가 실행 중인 경우 | 본문 `Current Phase:` 필드에서 추출된 페이즈 번호. |
| `current_phase_name` | string | 페이즈에 이름이 있는 경우 | 본문 `Current Phase Name:` 필드에서 추출된 페이즈 이름. |
| `current_plan` | string | 플랜이 진행 중인 경우 | 본문 `Current Plan:` 필드에서 추출된 플랜 번호. |
| `last_updated` | ISO-8601 타임스탬프 | 항상 (쓰기 시) | 마지막 `syncStateFrontmatter` 호출의 타임스탬프. `realClock.nowIso()`에 의해 기록됩니다. |
| `last_activity` | string | 본문에 설정된 경우 | 본문 `Last Activity:` 필드에서 추출된 마지막 활동 날짜. |
| `stopped_at` | string | 중단점이 기록된 경우 | 마지막으로 완료된 작업의 설명. 아카이브 산문과의 매칭을 피하기 위해 `## Session` 본문 섹션으로 범위가 제한됩니다. |
| `paused_at` | string | 프로젝트가 일시 정지된 경우 | 일시 정지 지점에 대한 자유형 설명. 일시 정지 상태가 아닐 때는 없거나 `null`. |
### 상태 값
`get-shit-done/bin/lib/state-document.cjs`의 `normalizeStateStatus()`는 본문의 원시 텍스트를 다음 표준 값으로 매핑합니다:
| 표준 값 | 매칭되는 텍스트 (대소문자 무관) |
|---|---|
| `discussing` | `discussing`을 포함 |
| `planning` | `planning` 또는 `ready to plan`을 포함 |
| `executing` | `executing`, `in progress`, 또는 `ready to execute`를 포함 |
| `verifying` | `verif`를 포함 |
| `completed` | `complete` 또는 `done`을 포함 |
| `paused` | `paused` 또는 `stopped`를 포함하거나, `paused_at`이 있는 경우 |
| `unknown` | 위 중 해당 없음 |
오케스트레이터 명령이 실행 중일 때의 규칙 (issue #2833)은 생명주기 단계를 `status`에 직접 기록하는 것입니다:
| 명령 | 실행 중 `status` |
|---|---|
| `/gsd-discuss-phase` | `discussing` |
| `/gsd-plan-phase` | `planning` |
| `/gsd-execute-phase` | `executing` |
| `/gsd-verify-work` | `verifying` |
---
## 상태 표시줄 렌더링 장면
`hooks/gsd-statusline.js`의 `formatGsdState()`는 파싱된 프론트매터를 읽고 **첫 번째로 일치하는 장면**을 출력합니다. 새로운 생명주기 필드가 적용되지 않으면 렌더링은 v1.38.x와 바이트 단위로 동일한 원래 형식으로 폴백됩니다.
| 장면 | 트리거 | 표시 예시 |
|---|---|---|
| **1. 페이즈 활성화** | `active_phase`가 채워진 경우 | `v2.0 [██░░░░░░░░] 20% · Phase 4.5 executing` |
| **2. 유휴 상태, 다음 권장** | `active_phase`가 null이고 `next_action`과 `next_phases`가 모두 채워진 경우 | `v2.0 [██░░░░░░░░] 20% · next execute-phase 4.5` |
| **3. 마일스톤 완료** | `percent`가 `100`이거나 `completed_phases == total_phases`인 경우 | `v2.0 [██████████] 100% · milestone complete` |
| **4. 기본 폴백** | 위 중 해당 없음 | `v1.9 Code Quality · executing · ph 1/5` (기존 형식) |
**장면 우선순위:** `active_phase`와 `next_action`이 모두 채워진 경우 장면 1이 우선합니다 — 오케스트레이터가 실행 중이므로 "다음 권장 사항"은 오해의 소지가 있습니다. 이 우선순위는 `formatGsdState()`의 확인 순서로 강제되며 `tests/enh-2833-phase-lifecycle-statusline.test.cjs`의 `"scene priority"` 스위트에서 테스트됩니다.
진행 막대(`[██░░░░░░░░] 20%`)는 프론트매터에 `progress.percent`가 있을 때만 마일스톤 세그먼트에 추가됩니다. 없으면 막대가 표시되지 않습니다.
---
## 프론트매터 파싱 제약 사항
상태 표시줄 훅은 정규식 기반 파싱을 사용합니다(YAML 라이브러리 없음). 따라서 다음 제약 사항이 적용됩니다. 이는 `tests/enh-2833-phase-lifecycle-statusline.test.cjs`에서 테스트됩니다.
1. **프론트매터는 파일의 맨 첫 번째 문자에서 시작해야 합니다.** 주석을 포함한 어떤 것이든 여는 `---` 위에 있으면 매칭이 무효화됩니다. 여는 `---` 줄은 정확히 그것이어야 하며, 후행 공백이 없어야 합니다.
2. **중첩 블록 내의 주석은 지원되지 않습니다.** `progress:` 블록 파서는 다음 줄이 `[ \t]+\w+:`여야 합니다. `progress:`와 첫 번째 키 사이에 `# comment`를 삽입하면 매칭이 깨지고 막대가 사라집니다. 모든 문서는 프론트매터 블록이 아닌 `STATE.md` 본문에 있어야 합니다.
3. **`next_phases`의 기본 형식은 단일 행 플로우입니다.** 파서는 먼저 `next_phases: ["4.5", "4.6"]`을 시도합니다. 블록 시퀀스(`- 4.5\n- 4.6`)도 파싱되지만 상태 표시줄 렌더링에서는 덜 안정적입니다. 정규식 기반 파서를 예측 가능하게 유지하기 위해 `next_phases`에는 단일 행 플로우를 선호하세요. 문서화 목적으로 많은 후보 페이즈를 기록해야 하는 경우, `STATE.md` 본문에 저장하세요.
향후 변경으로 정규식 파서를 완전한 YAML 라이브러리로 교체하면 이 제약 사항을 완화하고 테스트를 업데이트할 수 있습니다.
---
## Markdown 본문 섹션
본문(닫는 `---` 이후의 모든 것)은 `get-shit-done/templates/state.md`의 템플릿을 따릅니다. 표준 섹션은 다음과 같습니다:
### Project Reference
`.planning/PROJECT.md`를 가리킵니다. 다음을 포함합니다:
- **핵심 가치** — `PROJECT.md`의 Core Value 섹션에서 가져온 한 줄짜리 설명.
- **현재 포커스** — 어떤 페이즈가 활성화되어 있는지.
### Current Position
프로젝트의 현재 위치:
| 필드 | 형식 |
|---|---|
| `Phase:` | `X of Y (Phase name)` |
| `Plan:` | `A of B in current phase` |
| `Status:` | 자유 텍스트, 예: `Ready to execute`, `Executing Phase 4`, `Phase complete — ready for verification` |
| `Last activity:` | 핸들러가 기록할 때 ISO 날짜(`YYYY-MM-DD`); 실행기가 작성할 때 서술형 산문 |
| `Progress:` | 시각적 막대, 예: `[████░░░░░░] 40%` |
이 섹션의 `Status:` 및 `Last activity:` 필드는 기존 값이 알려진 템플릿 기본값인 경우 GSD 핸들러에 의해 업데이트됩니다(크누스 불변량: 실행기가 작성한 값은 보존됩니다). 알려진 핸들러 기본값의 전체 목록은 `get-shit-done/bin/lib/state-document.cjs`의 `KNOWN_TEMPLATE_DEFAULTS`에 있습니다.
### Performance Metrics
실행 속도 추적:
- 완료된 총 플랜 수, 플랜당 평균 소요 시간.
- 페이즈별 분석 표(`Phase | Plans | Total | Avg/Plan`).
- 최근 추세: Improving / Stable / Degrading.
각 플랜 완료 후 업데이트됩니다.
### Accumulated Context
**Decisions** — 현재 작업에 영향을 미치는 최근 결정 사항 요약(전체 로그는 `PROJECT.md`에 있음). `gsd-tools state add-decision`을 통해 추가됩니다.
**Pending Todos** — 개수 및 `.planning/todos/pending/`에 대한 참조. `/gsd-capture`를 통해 캡처됩니다.
**Blockers/Concerns** — 미래 작업에 영향을 미치는 문제, 발생한 페이즈 접두사 포함. `gsd-tools state add-blocker`를 통해 추가되고, `gsd-tools state resolve-blocker`를 통해 해결됩니다.
### Session Continuity
즉각적인 세션 재개를 가능하게 합니다:
- `Last session:` — 마지막 세션의 ISO-8601 타임스탬프.
- `Stopped at:` — 마지막으로 완료된 작업의 설명.
- `Resume file:` — `.continue-here*.md` 파일이 있으면 해당 경로, 없으면 `None`.
---
## 하위 호환성
페이즈 생명주기 필드(`active_phase`, `next_action`, `next_phases`, 막대를 위한 `progress.percent`)는 **추가적이며 프로젝트별로 선택 사항**입니다:
- 생명주기 필드가 하나도 채워지지 않은 `STATE.md`는 v1.38.x 및 이전 버전과 **바이트 단위로 동일하게** 렌더링됩니다.
- 생명주기 필드 추가는 선택 사항입니다 — 렌더러는 필드가 없을 때 우아하게 저하됩니다.
- 진행 막대는 `progress` 블록이 있어도 선택 사항입니다: `progress.percent`만 막대를 트리거하고, `total_phases`와 `completed_phases`만으로는 트리거되지 않습니다.
`tests/enh-2833-phase-lifecycle-statusline.test.cjs`의 `formatGsdState #2833 backward compatibility` 테스트 스위트는 이 보장을 고정합니다. 레거시 `STATE.md` 렌더링을 깨는 변경 사항은 스위트에서 실패합니다.
---
## Related
- [Planning artifacts](planning-artifacts.md)
- [Configuration](../../CONFIGURATION.md)
- [The phase loop](../../explanation/the-phase-loop.md)
- [docs index](../../README.md)

226
docs/ko-KR/tutorials/onboarding-an-existing-codebase.md Normal file
View File

@@ -0,0 +1,226 @@
# 기존 코드베이스 온보딩
이 튜토리얼에서는 이미 코드가 있는 저장소에 GSD Core를 도입합니다. 코드베이스를 매핑하고, *추가하려는* 내용을 설명하는 프로젝트를 생성한 다음, 작은 변경 사항에 대한 첫 번째 논의-계획 사이클을 실행합니다. 튜토리얼이 끝나면 GSD Core의 계획 파이프라인이 여러분의 기술 스택, 컨벤션, 그리고 관심사를 파악하게 됩니다 — 이후 계획을 수립할 때마다 이 지식을 활용합니다.
---
## 만들 것
기존 Express 애플리케이션에 `GET /health` 엔드포인트 하나를 추가합니다. 변경 사항이 충분히 작아서 진짜 핵심 교훈, 즉 GSD Core가 계획을 수립하기 전에 코드베이스를 어떻게 학습하는지에 집중할 수 있습니다.
---
## 사전 준비
- **Node.js 18 이상** — `node --version`이 `v18.x.x` 이상을 출력해야 합니다.
- **기존 프로젝트** — 코드가 이미 있는 저장소라면 무엇이든 됩니다. Express일 필요는 없으며, 이 단계들은 어떤 기술 스택에도 적용됩니다.
- **Claude Code** — 저장소 루트에서 열어둡니다.
---
## Step 1 — GSD Core 설치
저장소 루트에서 실행합니다:
```bash
npx @opengsd/gsd-core@latest
```
프롬프트가 표시되면 **Claude Code**와 **local**을 선택합니다. 다음과 같이 표시됩니다:
```text
✓ Installed 86 skills to .claude/commands/
✓ Installed agents to .claude/agents/
✓ GSD Core ready — run /gsd-new-project to start
```
---
## Step 2 — 권한 플래그로 Claude Code 시작
```bash
claude --dangerously-skip-permissions
```
---
## Step 3 — 코드베이스 매핑
프로젝트를 생성하기 전에 GSD Core가 이미 존재하는 것을 학습하도록 합니다. 이 단계가 브라운필드 계획의 정확도를 높이는 핵심입니다.
```text
/gsd-map-codebase
```
GSD Core가 4개의 병렬 매퍼 서브 에이전트를 생성합니다("Spawning 4 parallel codebase mapper agents…" 메시지가 표시되며, 1–5분 소요됩니다. 중단하지 마세요). 각 에이전트는 서로 다른 관심사에 집중합니다:
| 에이전트 | 집중 영역 |
|---------|---------|
| Tech mapper | 기술 스택, 프레임워크, 의존성 |
| Architecture mapper | 패턴, 레이어, 데이터 흐름 |
| Quality mapper | 컨벤션, 테스트 방식 |
| Concerns mapper | 기술 부채, 위험 영역 |
4개 에이전트가 모두 완료되면 다음과 같이 표시됩니다:
```text
Codebase mapping complete.
Created .planning/codebase/:
- STACK.md (47 lines) - Technologies and dependencies
- ARCHITECTURE.md (62 lines) - System design and patterns
- STRUCTURE.md (38 lines) - Directory layout and organisation
- CONVENTIONS.md (55 lines) - Code style and patterns
- TESTING.md (41 lines) - Test structure and practices
- INTEGRATIONS.md (29 lines) - External services and APIs
- CONCERNS.md (33 lines) - Technical debt and issues
```
`.planning/codebase/STACK.md`를 열어봅니다. GSD Core가 실제 파일을 읽어서 감지한 언어, 런타임, 프레임워크 버전, 주요 의존성이 표시됩니다 — 추측이 아닌 실제 데이터를 기반으로 합니다.
`.planning/codebase/CONVENTIONS.md`를 열어봅니다. 소스 코드에서 관찰한 네이밍 컨벤션, 에러 처리 패턴, 코드 스타일 규칙이 표시됩니다. GSD Core가 이 저장소를 위해 생성하는 모든 계획은 이 컨벤션을 자동으로 따릅니다.
`.planning/codebase/CONCERNS.md`를 열어봅니다. 새로운 기능 작업 전에 가장 먼저 읽어야 할 파일입니다 — 계획에 영향을 줄 수 있는 기술 부채와 취약한 영역을 드러냅니다.
---
## Step 4 — 컨텍스트 초기화 후 프로젝트 생성
세션 창을 초기화합니다:
```text
/clear
```
이제 프로젝트를 생성합니다. GSD Core가 이전 단계에서 기존 코드를 발견했으므로, 이미 이것이 브라운필드 프로젝트임을 알고 있습니다. `/gsd-new-project`를 실행하면 기존의 것을 재구성하는 것이 아니라 *추가하는* 것에 집중한 질문을 합니다:
```text
/gsd-new-project
```
GSD Core가 무엇을 만들고 싶은지 묻습니다. 전체 코드베이스에 대한 설명이 아닌 추가하려는 기능으로 답변합니다:
```text
Add a GET /health endpoint to the Express app. It should return
{ "status": "ok", "uptime": <seconds> }. We'll use it for load-balancer
health checks.
```
GSD Core는 소수의 후속 질문을 한 다음 요구사항과 로드맵 생성을 진행합니다. 이미 `ARCHITECTURE.md`와 `STACK.md`를 읽었으므로, 기존 기능을 `PROJECT.md`의 **Validated** 섹션에 자동으로 매핑합니다 — 기존 API 표면을 직접 설명할 필요가 없습니다.
모든 워크플로 설정에서 권장 기본값을 선택합니다.
로드맵 작성 서브 에이전트가 완료되면 제안 로드맵이 표시됩니다. 단일 소규모 변경은 한 단계로 구성됩니다:
```text
Proposed Roadmap
1 phase | 2 requirements mapped | All v1 requirements covered ✓
| # | Phase | Goal | Requirements |
|---|----------------|-----------------------------------------------|--------------|
| 1 | Health endpoint| GET /health returning status and uptime JSON | HLT-01, HLT-02 |
```
로드맵을 승인합니다.
**`.planning/`에 생성되는 파일:**
```text
.planning/
PROJECT.md ← 프로젝트 설명; "Validated"에 기존 기능
REQUIREMENTS.md ← HLT-01, HLT-02
ROADMAP.md ← Phase 1, 상태: pending
STATE.md ← 세션 메모리
config.json ← 워크플로 설정
codebase/ ← Step 3에서 생성된 7개의 맵 파일
```
`.planning/codebase/`는 Step 3에서 이미 생성된 것입니다. `PROJECT.md` 작성 시 GSD Core가 해당 파일들을 읽었기 때문에, 여러분이 직접 설명하지 않아도 Validated 요구사항을 채울 수 있었습니다.
---
## Step 5 — 컨텍스트 초기화 후 Phase 1 논의
```text
/clear
```
```text
/gsd-discuss-phase 1
```
GSD Core가 `CONVENTIONS.md`와 `ARCHITECTURE.md`를 읽었으므로, 질문들이 실제 코드베이스에 근거합니다 — 일반적인 조언이 아닙니다. 다음과 같은 질문을 받을 수 있습니다:
```text
> Your routes are registered in src/routes/index.js. Should the health
endpoint live there, or in a dedicated src/routes/health.js?
A dedicated health.js — keep routes separated.
> Your existing error middleware returns { error: "message" }. Should
/health use the same shape for error responses?
Yes, stay consistent.
> Should uptime be calculated from process.uptime() or a stored start time?
process.uptime() is fine.
```
논의가 끝나면 GSD Core가 다음 파일을 생성합니다:
```text
.planning/phases/01-health-endpoint/CONTEXT.md
```
해당 파일을 열어봅니다. `## Implementation Decisions` 섹션에 여러분의 답변이 기록되어 있습니다. 플래너가 태스크를 하나도 작성하기 전에 이 파일을 읽습니다 — 따라서 파일 배치와 응답 형식에 대한 선호도가 논의뿐 아니라 계획에도 반영됩니다.
---
## Step 6 — Phase 1 계획
```text
/gsd-plan-phase 1
```
4개의 리서치 서브 에이전트가 병렬로 실행됩니다(1–5분). 완료되면 플래너가 `CONTEXT.md`, 리서치 결과, 코드베이스 맵을 읽어 컨벤션에 맞는 태스크 계획을 생성합니다.
**생성되는 파일:**
```text
.planning/phases/01-health-endpoint/
RESEARCH.md ← health 엔드포인트 패턴에 대한 리서치 결과
01-01-PLAN.md ← 태스크: src/routes/health.js 생성
01-02-PLAN.md ← 태스크: src/routes/index.js에 health 라우트 등록
```
`01-01-PLAN.md`를 열어봅니다. `<files>` 태그에 `src/routes/health.js`가 참조되어 있습니다 — 논의에서 지정한 정확한 경로이며, GSD Core가 코드베이스 맵에서 관찰한 라우팅 패턴과 일치합니다. 코드베이스 맵이 실제로 작동하는 모습입니다.
---
## 다음 단계
이제 코드베이스 맵, 논의 결정 기록, 검증된 태스크 계획을 갖춘 프로젝트가 완성되었습니다 — 모두 실제 코드에 근거합니다. 이후 워크플로는 그린필드 프로젝트와 동일합니다:
```text
/gsd-execute-phase 1
/gsd-verify-work 1
/gsd-ship 1
```
앞으로 새로운 기능을 추가할 때마다 구조가 크게 바뀌면 `/gsd-map-codebase`를 다시 실행하여 코드베이스 맵을 최신 상태로 유지합니다.
---
## 배운 내용
- `/gsd-map-codebase`가 4개의 병렬 에이전트를 실행하여 `.planning/codebase/`에 `STACK.md`, `ARCHITECTURE.md`, `CONVENTIONS.md`, `CONCERNS.md`, `STRUCTURE.md`, `TESTING.md`, `INTEGRATIONS.md`를 생성하는 방법.
- 브라운필드 저장소에서 `/gsd-new-project`가 *추가하는* 것에 집중한 질문을 하고 기존 코드에서 Validated 요구사항을 채우는 방법.
- 코드베이스 맵이 `/gsd-discuss-phase`의 모든 질문을 형성하는 방법 — 파일 경로, 패턴, 컨벤션이 실제 코드에서 옵니다.
- 플래너가 `CONTEXT.md`와 `CONVENTIONS.md`를 함께 읽어 저장소 스타일에 맞는 계획을 생성하는 방법.
---
## Related
- [Your first project](your-first-project.md) — 설치부터 PR까지 전체 그린필드 루프
- [Map codebase via Commands](../COMMANDS.md) — `/gsd-map-codebase`의 모든 플래그와 서브커맨드
- [Documentation index](../README.md)

291
docs/ko-KR/tutorials/your-first-project.md Normal file
View File

@@ -0,0 +1,291 @@
# 첫 번째 프로젝트
이 튜토리얼에서는 GSD Core를 설치하고, 간단한 커맨드라인 할 일(to-do) 앱을 처음부터 만들어봅니다 — 하나의 단계(phase), 하나의 PR, 그리고 전체 루프를 경험합니다. 튜토리얼이 끝나면 핵심 단계 루프의 모든 명령어를 최소 한 번씩 실행해보고, 각 명령어가 생성하는 계획 산출물도 확인하게 됩니다.
---
## 만들 것
로컬 JSON 파일에 저장된 할 일 항목을 추가하고, 목록을 보고, 완료 처리할 수 있는 Node.js CLI입니다. 한 세션 안에 완성할 만큼 작고, Node.js 표준 라이브러리만 사용하므로 별도로 설치할 것이 없습니다.
---
## 사전 준비
- **Node.js 18 이상** — `node --version`이 `v18.x.x` 이상을 출력해야 합니다.
- **Claude Code** — 사용하려는 프로젝트 디렉터리에서 열어둡니다.
- 초기 설치를 위한 인터넷 연결.
그 외 도구는 필요하지 않습니다. GSD Core는 다음 단계에서 설치합니다.
---
## Step 1 — GSD Core 설치
프로젝트 디렉터리에서 터미널을 열고 실행합니다:
```bash
npx @opengsd/gsd-core@latest
```
설치 프로그램이 사용 중인 AI 코딩 런타임과 전역 설치 또는 현재 프로젝트 설치 여부를 묻습니다. 지금은 **Claude Code**와 **local**(이 프로젝트에만)을 선택합니다.
다음과 같은 출력이 표시됩니다:
```text
✓ Installed 86 skills to .claude/commands/
✓ Installed agents to .claude/agents/
✓ GSD Core ready — run /gsd-new-project to start
```
프로젝트 안에 `.claude/` 디렉터리가 생성된 것을 확인할 수 있습니다. GSD Core의 명령어와 에이전트가 이곳에 저장됩니다.
> 로컬 vs 전역 설치 이유? 로컬 설치는 이 프로젝트에 스킬 버전을 고정합니다. 전역 설치가 필요하다면 [런타임에 설치하기](../how-to/install-on-your-runtime.md)를 참고하세요.
---
## Step 2 — 권한 플래그로 Claude Code 시작
GSD Core는 파일을 읽고 쓰는 서브 에이전트를 생성합니다. 모든 파일 작업마다 확인을 요청하지 않도록 권한 플래그를 사용해 Claude Code를 시작합니다:
```bash
claude --dangerously-skip-permissions
```
프로젝트 디렉터리에서 Claude Code 프롬프트로 이동됩니다.
---
## Step 3 — 프로젝트 생성
Claude Code 프롬프트에 다음 슬래시 명령어를 입력합니다:
```text
/gsd-new-project
```
GSD Core가 대화를 시작합니다. 먼저 질문을 하나 합니다:
```text
What do you want to build?
```
다음과 같이 입력합니다:
```text
A Node.js CLI tool for managing to-do items. Users run `todo add "buy milk"`,
`todo list`, and `todo done 1`. Items are saved to a local todos.json file.
No external dependencies — Node built-ins only.
```
GSD Core는 몇 가지 후속 질문을 합니다. 자연스럽게 답변하면 됩니다. 계획을 하나도 작성하기 전에 먼저 여러분이 중요하게 생각하는 것을 파악합니다.
질문이 끝나면 도메인 리서치 실행 여부를 묻습니다. 이 정도 규모의 프로젝트는 리서치를 건너뛰어도 됩니다 — 프롬프트가 표시될 때 **Skip research**를 선택합니다.
그런 다음 GSD Core가 워크플로 설정(모드, 세분화 수준, 리서치 에이전트)을 선택하도록 안내합니다. 각 항목마다 권장 기본값을 선택합니다. 이 설정들은 `.planning/config.json`에 저장됩니다.
마지막으로 로드맵 작성 서브 에이전트가 실행됩니다("Spawning roadmapper…" 메시지가 표시되는 것은 정상이며, 약 1분 정도 소요됩니다). 완료되면 GSD Core가 제안 로드맵을 제시합니다. 단일 단계 프로젝트라면 다음과 같이 표시됩니다:
```text
Proposed Roadmap
1 phase | 4 requirements mapped | All v1 requirements covered ✓
| # | Phase | Goal | Requirements |
|---|--------------------|-----------------------------------------|-------------------|
| 1 | Core CLI | add / list / done commands, todos.json | CLI-01 … CLI-04 |
```
**Approve**를 입력해 로드맵을 승인합니다.
**`.planning/`에 생성되는 파일:**
```text
.planning/
PROJECT.md ← 프로젝트 설명과 요구사항
REQUIREMENTS.md ← 모든 v1 기능의 REQ-ID
ROADMAP.md ← Phase 1, 상태: pending
STATE.md ← 세션 메모리, 현재 위치
config.json ← 워크플로 설정
```
지금 `.planning/ROADMAP.md`를 열어 살펴봅니다. Phase 1에는 목표(Goal), 충족해야 할 요구사항 목록, 그리고 성공 기준(Success Criteria) — 실행이 반드시 달성해야 하는 관찰 가능한 동작 — 이 포함되어 있습니다.
---
## Step 4 — 컨텍스트 초기화 후 Phase 1 논의
GSD Core는 새로운 컨텍스트를 기반으로 동작하도록 설계되었습니다. 각 단계를 시작하기 전에 메인 세션 창을 초기화합니다:
```text
/clear
```
그런 다음 Phase 1 논의를 시작합니다:
```text
/gsd-discuss-phase 1
```
GSD Core가 단계 목표를 읽고 구현 방식에 대해 질문합니다. 이는 *무엇을* 만들지가 아닌 *어떻게* 만들지를 결정하는 과정입니다. 예시 대화:
```text
> How should done items be stored — mark them in place or move them?
Mark them in place with a "done" flag.
> Should `todo list` show completed items by default?
No, hide them unless --all is passed.
> Error format when todos.json doesn't exist yet?
Create it silently on first add.
```
논의가 끝나면 GSD Core가 다음 파일을 생성합니다:
```text
.planning/phases/01-core-cli/CONTEXT.md
```
해당 파일을 열어봅니다. `## Implementation Decisions` 섹션에 여러분이 말한 내용이 정확히 기록되어 있습니다. 플래너가 이 파일을 읽으므로, 여기서 결정한 내용이 모든 태스크 계획에 반영됩니다.
---
## Step 5 — Phase 1 계획
```text
/gsd-plan-phase 1
```
4개의 리서치 서브 에이전트가 병렬로 실행됩니다("Spawning 4 researchers…" 메시지가 표시됩니다). 1–5분 정도 소요됩니다. 중단하지 마세요.
완료되면 플래너가 CONTEXT.md와 리서치 결과를 바탕으로 원자적 태스크 계획을 생성합니다. 플랜 검사기가 각 계획이 단계 목표를 달성하는지 확인한 후 저장합니다.
**생성되는 파일:**
```text
.planning/phases/01-core-cli/
RESEARCH.md ← 도메인 리서치 결과
01-01-PLAN.md ← 태스크: todos.json 읽기/쓰기 헬퍼 생성
01-02-PLAN.md ← 태스크: add / list / done 명령어 구현
```
`01-01-PLAN.md`를 열어봅니다. 이름, 관련 파일, 실행 단계, 검증 명령어, 완료 조건이 담긴 `<task>` 블록을 확인할 수 있습니다. `<verify>` 태그에 주목하세요 — GSD Core의 실행기가 코드 작성 후 해당 명령어를 실행합니다.
---
## Step 6 — Phase 1 실행
```text
/gsd-execute-phase 1
```
GSD Core가 계획을 웨이브(독립적인 계획은 병렬로 실행)로 묶고, 계획별로 새로운 200k 컨텍스트 실행기를 생성하며, 각 태스크를 원자적으로 커밋합니다.
다음과 같은 출력이 표시됩니다:
```text
Wave 1 (parallel):
[Executor A] → 01-01-PLAN.md (read/write helpers) ✓ committed
[Executor B] → 01-02-PLAN.md (CLI commands) ✓ committed
[Verifier] Checking codebase against phase goals...
CLI-01 todo add ✓
CLI-02 todo list ✓
CLI-03 todo done ✓
CLI-04 --all flag ✓
Status: PASS
```
**생성되는 파일:**
```text
.planning/phases/01-core-cli/
01-01-SUMMARY.md ← Executor A가 빌드하고 커밋한 내용
01-02-SUMMARY.md ← Executor B가 빌드하고 커밋한 내용
VERIFICATION.md ← REQ 커버리지: PASS
```
이제 CLI를 실행해봅니다:
```bash
node todo.js add "buy milk"
node todo.js add "write tests"
node todo.js list
node todo.js done 1
node todo.js list
```
항목이 나타나고, 완료 처리한 항목 1번이 기본 목록에서 사라지는 것을 확인할 수 있습니다. 이것이 GSD Core가 전달하는 첫 번째 가시적인 결과입니다.
---
## Step 7 — 작업 검증
```text
/gsd-verify-work 1
```
GSD Core가 단계의 성공 기준을 추출하고 하나씩 확인합니다:
```text
[1/3] Can you run `node todo.js add "buy milk"` without errors?
> yes
[2/3] Does `node todo.js list` show only incomplete items by default?
> yes
[3/3] Does `node todo.js done 1` mark item 1 complete and hide it from the default list?
> yes
All 3 checks passed. Phase 1 verified.
```
검사가 실패하면 GSD Core가 근본 원인을 진단하고 수정 계획을 생성합니다. `/gsd-execute-phase 1`을 다시 실행해 수정을 적용한 후, `/gsd-verify-work 1`을 다시 실행합니다.
**생성되는 파일:**
```text
.planning/phases/01-core-cli/UAT.md ← 모든 검사 항목과 결과
```
---
## Step 8 — 배포
```text
/gsd-ship 1
```
GSD Core가 자동 생성된 본문으로 풀 리퀘스트를 생성합니다. PR 본문에는 항상 요약(Summary), 변경 사항(Changes), 요구사항 반영(Requirements Addressed), 검증(Verification), 핵심 결정사항(Key Decisions)이 포함됩니다.
다음과 같이 표시됩니다:
```text
Pull request created: https://github.com/your-org/your-repo/pull/1
Title: feat(phase-1): core CLI — add / list / done commands
```
이것이 하나의 단계(phase)에 대한 아이디어부터 PR 머지까지의 전체 루프입니다.
---
## 배운 내용
- `npx @opengsd/gsd-core@latest`로 GSD Core를 설치하는 방법.
- `/gsd-new-project`가 대화를 통해 `.planning/` 산출물로 뒷받침되는 로드맵으로 전환하는 방법.
- `/gsd-discuss-phase`가 계획 수립 전에 구현 결정사항을 기록하는 방법.
- `/gsd-plan-phase`가 병렬 리서처를 생성하고 원자적 태스크 계획을 만드는 방법.
- `/gsd-execute-phase`가 해당 계획을 병렬 웨이브로 실행하고 각 태스크를 커밋하는 방법.
- `/gsd-verify-work`가 성공 기준을 하나씩 확인하고 필요 시 수정 계획을 생성하는 방법.
- `/gsd-ship`이 검증된 단계를 풀 리퀘스트로 전환하는 방법.
멀티 단계 프로젝트의 경우 각 단계마다 Step 4–8을 반복한 다음, `/gsd-progress --next`를 실행해 GSD Core가 다음 단계를 자동으로 감지하도록 합니다.
---
## Related
- [The phase loop](../explanation/the-phase-loop.md) — 루프가 이런 구조를 가지는 이유
- [How-to guides](../README.md#how-to-guides) — 특정 상황에 대한 태스크 중심 레시피
- [Onboarding an existing codebase](onboarding-an-existing-codebase.md) — 브라운필드 레포에 GSD Core 도입하기

78
docs/ko-KR/workflow-discuss-mode.md
View File

@@ -1,65 +1,75 @@
# Discuss 모드: Assumptions vs Interview
# 논의 모드: 가정 vs 인터뷰
GSD의 discuss 단계는 플래닝 전에 구현 컨텍스트를 수집하는 두 가지 모드를 제공합니다.
GSD Core의 discuss-phase는 계획 전에 구현 컨텍스트를 수집하기 위한 두 가지 모드를 제공한다. 각 모드를 언제 사용해야 하는지 이해하면 더 적은 주고받음으로 확인된 `CONTEXT.md`에 도달할 수 있다.
두 모드 중 하나를 실행하는 단계별 지침은 [단계 논의하기 how-to](how-to/discuss-a-phase.md)를 참조하라.
## 모드
### `discuss` (기본값)
기존의 인터뷰 방식 흐름입니다. Claude가 단계에서 불명확한 영역을 파악하고 선택지를 제시한 뒤 영역당 약 4개의 질문을 합니다. 다음 상황에 적합합니다.
원래의 인터뷰 스타일 흐름. Claude가 단계의 회색 영역을 식별하고 선택을 위해 표시한 다음 영역당 약 네 가지 질문을 한다. 다음 경우에 적합하다:
- 코드베이스가 새로운 초기 단계
- 사용자가 사전에 강한 의견을 표현하고 싶은 단계
- 안내된 대화식 컨텍스트 수집을 선호하는 사용자
- 코드베이스가 새로운 초반 단계
- 사용자가 사전에 표현하고 싶은 강한 의견이 있는 단계
- 가이드된 대화식 컨텍스트 수집을 선호하는 사용자
### `assumptions`
코드베이스 우선 방식의 흐름입니다. Claude가 서브에이전트를 통해 코드베이스를 깊이 분석하고 (관련 파일 5~15개 읽기) 근거가 있는 가정을 도출하여 확인 또는 수정을 위해 제시합니다. 다음 상황에 적합합니다.
코드베이스 우선 흐름. Claude가 서브에이전트를 통해 코드베이스를 깊이 분석하고(관련 파일 5-15개 읽기), 증거를 바탕으로 가정을 형성하며, 확인 또는 수정을 위해 표시한다. 다음 경우에 적합하다:
- 명확한 패턴이 있는 기존 코드베이스
- 인터뷰 질문이 당연하게 느껴지는 사용자
- 빠른 컨텍스트 수집 (~15~20번 대신 ~2~4번의 상호작용)
- 명확한 패턴을 가진 기존 코드베이스
- 인터뷰 질문들이 당연하게 느껴지는 사용자
- 더 빠른 컨텍스트 수집 (~2-4회 상호작용 vs ~15-20회)
## 설정
```bash
# assumptions 모드 활성화
gsd-tools config-set workflow.discuss_mode assumptions
node gsd-tools.cjs config-set workflow.discuss_mode assumptions
# interview 모드로 전환
gsd-tools config-set workflow.discuss_mode discuss
# 인터뷰 모드로 전환
node gsd-tools.cjs config-set workflow.discuss_mode discuss
```
설정은 프로젝트별로 적용되며 `.planning/config.json`에 저장됩니다.
설정은 프로젝트별이다(`.planning/config.json`에 저장). 두 모드 모두가 생성하는 파일의 전체 구조는 [CONTEXT.md 스키마](reference/context-md.md)를 참조하라.
## Assumptions 모드 동작 방식
## Assumptions 모드 작동 방식
1. **Init** — discuss 모드와 동일 (이전 컨텍스트 로드, 코드베이스 스카우트, todo 확인)
2. **심층 분석** — explore 서브에이전트가 단계와 관련된 코드베이스 파일 5~15개를 읽음
3. **가정 제시** — 각 가정에는 다음이 포함됩니다.
- Claude가 할 작업과 그 이유 (파일 경로 인용)
- 가정이 틀렸을 때 발생하는 문제
1. **초기화** — discuss 모드와 동일 (이전 컨텍스트 로드, 코드베이스 스카우트, 할 일 확인)
2. **깊이 분석** — 탐색 서브에이전트가 단계와 관련된 코드베이스 파일 5-15개를 읽음
3. **가정 표시** — 각 가정에 포함:
- Claude가 무엇을 하고 왜 하는지 (파일 경로 인용)
- 가정이 잘못된 경우 무엇이 잘못될 수 있는지
- 신뢰도 수준 (Confident / Likely / Unclear)
4. **확인 또는 수정** — 사용자가 가정을 검토하고 변경이 필요한 항목을 선택
4. **확인 또는 수정** — 사용자가 가정을 검토하고 변경이 필요한 것을 선택
5. **CONTEXT.md 작성** — discuss 모드와 동일한 출력 형식
## 플래그 호환성
| 플래그 | `discuss` 모드 | `assumptions` 모드 |
|--------|----------------|-------------------|
| `--auto` | 권장 답변을 자동으로 선택 | 확인 단계를 건너뛰고 Unclear 항목을 자동으로 처리 |
| `--batch` | 질문을 배치로 묶어서 처리 | 해당 없음 (수정 사항이 이미 배치로 처리됨) |
| `--text` | 일반 텍스트 질문 (원격 세션) | 일반 텍스트 질문 (원격 세션) |
| `--analyze` | 질문별 트레이드오프 표 표시 | 해당 없음 (가정에 근거가 포함됨) |
|------|----------------|-------------------|
| `--auto` | 추천 답변 자동 선택 | 확인 게이트 건너뜀, 불분명 항목 자동 해결 |
| `--batch` | 질문을 배치로 그룹화 | 해당 없음 (수정 사항이 이미 배치 처리됨) |
| `--text` | 텍스트 형식 질문 (원격 세션) | 텍스트 형식 질문 (원격 세션) |
| `--analyze` | 질문당 트레이드오프 테이블 표시 | 해당 없음 (가정에 증거 포함) |
## 출력
두 모드 모두 동일한 6개 섹션을 포함하는 CONTEXT.md를 생성합니다.
- `<domain>` — 단계 범위
- `<decisions>` — 확정된 구현 결정사항
- `<canonical_refs>` — 하위 에이전트가 반드시 읽어야 할 스펙/문서
- `<code_context>` — 재사용 가능한 자산, 패턴, 통합 지점
- `<specifics>` — 사용자 참고 자료 및 선호사항
- `<deferred>` — 향후 단계를 위해 기록된 아이디어
두 모드 모두 동일한 여섯 섹션을 가진 동일한 `CONTEXT.md`를 생성한다:
하위 에이전트(researcher, planner, checker)는 모드에 관계없이 동일하게 이 파일을 사용합니다.
- `<domain>` — 단계 경계
- `<decisions>` — 확정된 구현 결정 사항
- `<canonical_refs>` — 하위 에이전트들이 읽어야 하는 사양/문서
- `<code_context>` — 재사용 가능한 자산, 패턴, 통합 포인트
- `<specifics>` — 사용자 참조 사항과 선호도
- `<deferred>` — 미래 단계를 위해 메모된 아이디어
하위 에이전트들(리서처, 플래너, 검사기)은 어느 모드가 생성했든 관계없이 이 파일을 동일하게 소비한다. 전체 필드 레퍼런스는 [CONTEXT.md 스키마](reference/context-md.md)를 참조하라.
## Related
- [단계 논의하기](how-to/discuss-a-phase.md) — 두 모드 중 하나로 `/gsd-discuss-phase`를 실행하는 단계별 how-to.
- [CONTEXT.md 스키마](reference/context-md.md) — 두 모드 모두가 생성하는 파일의 전체 필드 레퍼런스.
- [단계 루프](explanation/the-phase-loop.md) — 논의가 더 넓은 논의 → 계획 → 실행 → 검증 → 출시 사이클에서 어떻게 맞는지.
- [문서 인덱스](README.md) — GSD Core 문서의 전체 목차.