Merge pull request #1350 from ITlearning/feat/korean-docs-translation
docs: add complete Korean (ko-KR) documentation — 12 translated files
This commit is contained in:
Tom Boucher
@@ -41,7 +41,7 @@ npx get-shit-done-cc@latest
|
||||
|
||||
**Amazon, Google, Shopify, Webflow 엔지니어들이 신뢰합니다.**
|
||||
|
||||
[왜 만들었나](#왜-만들었나) · [작동 방식](#작동-방식) · [명령어](#명령어) · [왜 효과적인가](#왜-효과적인가) · [사용자 가이드](docs/USER-GUIDE.md)
|
||||
[왜 만들었나](#왜-만들었나) · [작동 방식](#작동-방식) · [명령어](#명령어) · [왜 효과적인가](#왜-효과적인가) · [사용자 가이드](docs/ko-KR/USER-GUIDE.md)
|
||||
|
||||
</div>
|
||||
|
||||
@@ -252,7 +252,7 @@ claude --dangerously-skip-permissions
|
||||
|
||||
**생성 파일:** `{phase_num}-CONTEXT.md`
|
||||
|
||||
> **가정 모드:** 질문보다 코드베이스 분석을 선호하나요? `/gsd:settings`에서 `workflow.discuss_mode`를 `assumptions`로 설정하세요. 시스템이 코드를 읽고 하려는 것과 이유를 제시한 다음 틀린 부분만 수정을 요청합니다. [논의 모드](docs/workflow-discuss-mode.md) 참조.
|
||||
> **가정 모드:** 질문보다 코드베이스 분석을 선호하나요? `/gsd:settings`에서 `workflow.discuss_mode`를 `assumptions`로 설정하세요. 시스템이 코드를 읽고 하려는 것과 이유를 제시한 다음 틀린 부분만 수정을 요청합니다. [논의 모드](docs/ko-KR/workflow-discuss-mode.md) 참조.
|
||||
|
||||
---
|
||||
|
||||
@@ -613,7 +613,7 @@ lmn012o feat(08-02): create registration endpoint
|
||||
|
||||
## 설정
|
||||
|
||||
GSD는 프로젝트 설정을 `.planning/config.json`에 저장합니다. `/gsd:new-project` 중에 설정하거나 나중에 `/gsd:settings`로 업데이트할 수 있습니다. 전체 config 스키마, 워크플로우 토글, git 브랜칭 옵션, 에이전트별 모델 분석은 [사용자 가이드](docs/USER-GUIDE.md#configuration-reference)를 참조하세요.
|
||||
GSD는 프로젝트 설정을 `.planning/config.json`에 저장합니다. `/gsd:new-project` 중에 설정하거나 나중에 `/gsd:settings`로 업데이트할 수 있습니다. 전체 config 스키마, 워크플로우 토글, git 브랜칭 옵션, 에이전트별 모델 분석은 [사용자 가이드](docs/ko-KR/USER-GUIDE.md#configuration-reference)를 참조하세요.
|
||||
|
||||
### 핵심 설정
|
||||
|
||||
|
||||
@@ -8,7 +8,7 @@
|
||||
|
||||
**Solves context rot — the quality degradation that happens as Claude fills its context window.**
|
||||
|
||||
[**English**](README.md) | [**Português**](README.pt-BR.md) | [**简体中文**](docs/zh-CN/README.md) | [**日本語**](docs/ja-JP/README.md) | [**한국어**](README.ko-KR.md)
|
||||
[**English**](README.md) | [**Português**](README.pt-BR.md) | [**简体中文**](docs/zh-CN/README.md) | [**日本語**](docs/ja-JP/README.md) | [**한국어**](docs/ko-KR/README.md)
|
||||
|
||||
[](https://www.npmjs.com/package/get-shit-done-cc)
|
||||
[](https://www.npmjs.com/package/get-shit-done-cc)
|
||||
|
||||
428
docs/ko-KR/AGENTS.md
Normal file
428
docs/ko-KR/AGENTS.md
Normal file
@@ -0,0 +1,428 @@
|
||||
# GSD 에이전트 레퍼런스
|
||||
|
||||
> 18개의 전문화된 에이전트 — 역할, 도구, 생성 패턴, 관계를 모두 포함합니다. 아키텍처 맥락은 [Architecture](ARCHITECTURE.md)를 참조하세요.
|
||||
|
||||
---
|
||||
|
||||
## 개요
|
||||
|
||||
GSD는 멀티 에이전트 아키텍처를 사용합니다. 가벼운 오케스트레이터(워크플로우 파일)가 전문화된 에이전트를 새로운 컨텍스트 윈도우로 생성합니다. 각 에이전트는 집중된 역할, 제한된 도구 접근 권한을 가지며 특정 결과물을 생성합니다.
|
||||
|
||||
### 에이전트 카테고리
|
||||
|
||||
| 카테고리 | 수 | 에이전트 |
|
||||
|----------|-------|--------|
|
||||
| Researchers | 3 | project-researcher, phase-researcher, ui-researcher |
|
||||
| Analyzers | 2 | assumptions-analyzer, advisor-researcher |
|
||||
| Synthesizers | 1 | research-synthesizer |
|
||||
| Planners | 1 | planner |
|
||||
| Roadmappers | 1 | roadmapper |
|
||||
| Executors | 1 | executor |
|
||||
| Checkers | 3 | plan-checker, integration-checker, ui-checker |
|
||||
| Verifiers | 1 | verifier |
|
||||
| Auditors | 2 | nyquist-auditor, ui-auditor |
|
||||
| Mappers | 1 | codebase-mapper |
|
||||
| Debuggers | 1 | debugger |
|
||||
|
||||
---
|
||||
|
||||
## 에이전트 상세
|
||||
|
||||
### gsd-project-researcher
|
||||
|
||||
**역할:** 로드맵 생성 전에 도메인 생태계를 조사합니다.
|
||||
|
||||
| 속성 | 값 |
|
||||
|----------|-------|
|
||||
| **생성 주체** | `/gsd:new-project`, `/gsd:new-milestone` |
|
||||
| **병렬성** | 4개 인스턴스 (stack, features, architecture, pitfalls) |
|
||||
| **도구** | Read, Write, Bash, Grep, Glob, WebSearch, WebFetch, mcp (context7) |
|
||||
| **모델 (balanced)** | Sonnet |
|
||||
| **생성물** | `.planning/research/STACK.md`, `FEATURES.md`, `ARCHITECTURE.md`, `PITFALLS.md` |
|
||||
|
||||
**기능.**
|
||||
- 최신 생태계 정보를 위한 웹 검색
|
||||
- 라이브러리 문서를 위한 Context7 MCP 통합
|
||||
- 조사 문서를 디스크에 직접 작성 (오케스트레이터 컨텍스트 부하 감소)
|
||||
|
||||
---
|
||||
|
||||
### gsd-phase-researcher
|
||||
|
||||
**역할:** 계획 수립 전에 특정 단계의 구현 방법을 조사합니다.
|
||||
|
||||
| 속성 | 값 |
|
||||
|----------|-------|
|
||||
| **생성 주체** | `/gsd:plan-phase` |
|
||||
| **병렬성** | 4개 인스턴스 (project-researcher와 동일한 집중 영역) |
|
||||
| **도구** | Read, Write, Bash, Grep, Glob, WebSearch, WebFetch, mcp (context7) |
|
||||
| **모델 (balanced)** | Sonnet |
|
||||
| **생성물** | `{phase}-RESEARCH.md` |
|
||||
|
||||
**기능.**
|
||||
- CONTEXT.md를 읽어 사용자 결정에 맞게 조사 방향을 설정합니다
|
||||
- 특정 단계 도메인의 구현 패턴을 조사합니다
|
||||
- Nyquist 검증 매핑을 위한 테스트 인프라를 감지합니다
|
||||
|
||||
---
|
||||
|
||||
### gsd-ui-researcher
|
||||
|
||||
**역할:** 프론트엔드 단계를 위한 UI 디자인 계약서를 생성합니다.
|
||||
|
||||
| 속성 | 값 |
|
||||
|----------|-------|
|
||||
| **생성 주체** | `/gsd:ui-phase` |
|
||||
| **병렬성** | 단일 인스턴스 |
|
||||
| **도구** | Read, Write, Bash, Grep, Glob, WebSearch, WebFetch, mcp (context7) |
|
||||
| **모델 (balanced)** | Sonnet |
|
||||
| **색상** | `#E879F9` (fuchsia) |
|
||||
| **생성물** | `{phase}-UI-SPEC.md` |
|
||||
|
||||
**기능.**
|
||||
- 디자인 시스템 상태 감지 (shadcn components.json, Tailwind config, 기존 토큰)
|
||||
- React/Next.js/Vite 프로젝트를 위한 shadcn 초기화 제안
|
||||
- 아직 답변되지 않은 디자인 계약 질문만 질의합니다
|
||||
- 서드파티 컴포넌트에 대한 레지스트리 안전 게이트를 적용합니다
|
||||
|
||||
---
|
||||
|
||||
### gsd-assumptions-analyzer
|
||||
|
||||
**역할:** 단계에 대한 코드베이스를 심층 분석하고 증거, 신뢰 수준, 오류 시 결과를 포함한 구조화된 가정을 반환합니다.
|
||||
|
||||
| 속성 | 값 |
|
||||
|----------|-------|
|
||||
| **생성 주체** | `discuss-phase-assumptions` 워크플로우 (`workflow.discuss_mode = 'assumptions'`인 경우) |
|
||||
| **병렬성** | 단일 인스턴스 |
|
||||
| **도구** | Read, Bash, Grep, Glob |
|
||||
| **모델 (balanced)** | Sonnet |
|
||||
| **색상** | Cyan |
|
||||
| **생성물** | 결정문, 증거 파일 경로, 신뢰 수준을 포함한 구조화된 가정 |
|
||||
|
||||
**핵심 동작.**
|
||||
- ROADMAP.md 단계 설명과 이전 CONTEXT.md 파일을 읽습니다
|
||||
- 단계 관련 파일(컴포넌트, 패턴, 유사 기능)을 코드베이스에서 검색합니다
|
||||
- 증거 기반 가정 형성을 위해 가장 관련성 높은 소스 파일 5~15개를 읽습니다
|
||||
- 신뢰 수준을 분류합니다. Confident(코드에서 명확), Likely(합리적 추론), Unclear(여러 방향 가능)
|
||||
- 외부 조사가 필요한 항목을 표시합니다 (라이브러리 호환성, 생태계 모범 사례)
|
||||
- 티어에 따라 출력을 조정합니다. full_maturity(3~5개 영역), standard(3~4개), minimal_decisive(2~3개)
|
||||
|
||||
---
|
||||
|
||||
### gsd-advisor-researcher
|
||||
|
||||
**역할:** discuss-phase 어드바이저 모드에서 단일 회색 지대 결정을 조사하고 구조화된 비교 표를 반환합니다.
|
||||
|
||||
| 속성 | 값 |
|
||||
|----------|-------|
|
||||
| **생성 주체** | `discuss-phase` 워크플로우 (ADVISOR_MODE = true인 경우) |
|
||||
| **병렬성** | 복수 인스턴스 (회색 지대당 하나) |
|
||||
| **도구** | Read, Bash, Grep, Glob, WebSearch, WebFetch, mcp (context7) |
|
||||
| **모델 (balanced)** | Sonnet |
|
||||
| **색상** | Cyan |
|
||||
| **생성물** | 5열 비교 표 (Option / Pros / Cons / Complexity / Recommendation)와 근거 단락 |
|
||||
|
||||
**핵심 동작.**
|
||||
- Claude의 지식, Context7, 웹 검색을 사용하여 할당된 단일 회색 지대를 조사합니다
|
||||
- 실질적으로 실행 가능한 옵션만 제시합니다 — 형식적인 대안은 포함하지 않습니다
|
||||
- Complexity 열은 영향 범위와 위험을 사용합니다 (시간 추정치는 사용하지 않음)
|
||||
- 권장 사항은 조건부로 제시합니다 ("Rec if X", "Rec if Y") — 단일 승자 순위는 없습니다
|
||||
- 티어에 따라 출력을 조정합니다. full_maturity(성숙도 신호 포함 3~5개 옵션), standard(2~4개), minimal_decisive(2개 옵션, 결정적 권장 사항)
|
||||
|
||||
---
|
||||
|
||||
### gsd-research-synthesizer
|
||||
|
||||
**역할:** 병렬 조사자들의 출력을 통합된 요약으로 합칩니다.
|
||||
|
||||
| 속성 | 값 |
|
||||
|----------|-------|
|
||||
| **생성 주체** | `/gsd:new-project` (4개 조사자 완료 후) |
|
||||
| **병렬성** | 단일 인스턴스 (조사자 이후 순차적) |
|
||||
| **도구** | Read, Write, Bash |
|
||||
| **모델 (balanced)** | Sonnet |
|
||||
| **색상** | Purple |
|
||||
| **생성물** | `.planning/research/SUMMARY.md` |
|
||||
|
||||
---
|
||||
|
||||
### gsd-planner
|
||||
|
||||
**역할:** 작업 분류, 의존성 분석, 목표 역방향 검증을 포함한 실행 가능한 단계 계획을 생성합니다.
|
||||
|
||||
| 속성 | 값 |
|
||||
|----------|-------|
|
||||
| **생성 주체** | `/gsd:plan-phase`, `/gsd:quick` |
|
||||
| **병렬성** | 단일 인스턴스 |
|
||||
| **도구** | Read, Write, Bash, Glob, Grep, WebFetch, mcp (context7) |
|
||||
| **모델 (balanced)** | Opus |
|
||||
| **색상** | Green |
|
||||
| **생성물** | `{phase}-{N}-PLAN.md` 파일 |
|
||||
|
||||
**핵심 동작.**
|
||||
- PROJECT.md, REQUIREMENTS.md, CONTEXT.md, RESEARCH.md를 읽습니다
|
||||
- 단일 컨텍스트 윈도우에 맞는 크기의 2~3개 원자적 작업 계획을 생성합니다
|
||||
- `<task>` 요소를 포함한 XML 구조를 사용합니다
|
||||
- `read_first`와 `acceptance_criteria` 섹션을 포함합니다
|
||||
- 계획을 의존성 웨이브로 그룹화합니다
|
||||
|
||||
---
|
||||
|
||||
### gsd-roadmapper
|
||||
|
||||
**역할:** 단계 분류 및 요구 사항 매핑을 포함한 프로젝트 로드맵을 생성합니다.
|
||||
|
||||
| 속성 | 값 |
|
||||
|----------|-------|
|
||||
| **생성 주체** | `/gsd:new-project` |
|
||||
| **병렬성** | 단일 인스턴스 |
|
||||
| **도구** | Read, Write, Bash, Glob, Grep |
|
||||
| **모델 (balanced)** | Sonnet |
|
||||
| **색상** | Purple |
|
||||
| **생성물** | `ROADMAP.md` |
|
||||
|
||||
**핵심 동작.**
|
||||
- 요구 사항을 단계에 매핑합니다 (추적성)
|
||||
- 요구 사항으로부터 성공 기준을 도출합니다
|
||||
- 단계 수에 대한 세분화 설정을 준수합니다
|
||||
- 커버리지를 검증합니다 (모든 v1 요구 사항이 단계에 매핑됨)
|
||||
|
||||
---
|
||||
|
||||
### gsd-executor
|
||||
|
||||
**역할:** 원자적 커밋, 이탈 처리, 체크포인트 프로토콜로 GSD 계획을 실행합니다.
|
||||
|
||||
| 속성 | 값 |
|
||||
|----------|-------|
|
||||
| **생성 주체** | `/gsd:execute-phase`, `/gsd:quick` |
|
||||
| **병렬성** | 복수 (웨이브 내 병렬, 웨이브 간 순차적) |
|
||||
| **도구** | Read, Write, Edit, Bash, Grep, Glob |
|
||||
| **모델 (balanced)** | Sonnet |
|
||||
| **색상** | Yellow |
|
||||
| **생성물** | 코드 변경사항, git 커밋, `{phase}-{N}-SUMMARY.md` |
|
||||
|
||||
**핵심 동작.**
|
||||
- 계획당 새로운 200K 컨텍스트 윈도우를 사용합니다
|
||||
- XML 작업 지시를 정확히 따릅니다
|
||||
- 완료된 작업마다 원자적 git 커밋을 수행합니다
|
||||
- 체크포인트 유형을 처리합니다. auto, human-verify, decision, human-action
|
||||
- SUMMARY.md에 계획 이탈을 보고합니다
|
||||
- 검증 실패 시 노드 복구를 실행합니다
|
||||
|
||||
---
|
||||
|
||||
### gsd-plan-checker
|
||||
|
||||
**역할:** 실행 전에 계획이 단계 목표를 달성할 수 있는지 검증합니다.
|
||||
|
||||
| 속성 | 값 |
|
||||
|----------|-------|
|
||||
| **생성 주체** | `/gsd:plan-phase` (검증 루프, 최대 3회 반복) |
|
||||
| **병렬성** | 단일 인스턴스 (반복적) |
|
||||
| **도구** | Read, Bash, Glob, Grep |
|
||||
| **모델 (balanced)** | Sonnet |
|
||||
| **색상** | Green |
|
||||
| **생성물** | 구체적인 피드백을 포함한 PASS/FAIL 판정 |
|
||||
|
||||
**8가지 검증 차원.**
|
||||
1. 요구 사항 커버리지
|
||||
2. 작업 원자성
|
||||
3. 의존성 순서
|
||||
4. 파일 범위
|
||||
5. 검증 명령어
|
||||
6. 컨텍스트 적합성
|
||||
7. 누락 감지
|
||||
8. Nyquist 준수 (활성화된 경우)
|
||||
|
||||
---
|
||||
|
||||
### gsd-integration-checker
|
||||
|
||||
**역할:** 단계 간 통합 및 엔드투엔드 흐름을 검증합니다.
|
||||
|
||||
| 속성 | 값 |
|
||||
|----------|-------|
|
||||
| **생성 주체** | `/gsd:audit-milestone` |
|
||||
| **병렬성** | 단일 인스턴스 |
|
||||
| **도구** | Read, Bash, Grep, Glob |
|
||||
| **모델 (balanced)** | Sonnet |
|
||||
| **색상** | Blue |
|
||||
| **생성물** | 통합 검증 보고서 |
|
||||
|
||||
---
|
||||
|
||||
### gsd-ui-checker
|
||||
|
||||
**역할:** 품질 차원에 대해 UI-SPEC.md 디자인 계약서를 검증합니다.
|
||||
|
||||
| 속성 | 값 |
|
||||
|----------|-------|
|
||||
| **생성 주체** | `/gsd:ui-phase` (검증 루프, 최대 2회 반복) |
|
||||
| **병렬성** | 단일 인스턴스 |
|
||||
| **도구** | Read, Bash, Glob, Grep |
|
||||
| **모델 (balanced)** | Sonnet |
|
||||
| **색상** | `#22D3EE` (cyan) |
|
||||
| **생성물** | BLOCK/FLAG/PASS 판정 |
|
||||
|
||||
---
|
||||
|
||||
### gsd-verifier
|
||||
|
||||
**역할:** 목표 역방향 분석을 통해 단계 목표 달성 여부를 검증합니다.
|
||||
|
||||
| 속성 | 값 |
|
||||
|----------|-------|
|
||||
| **생성 주체** | `/gsd:execute-phase` (모든 executor 완료 후) |
|
||||
| **병렬성** | 단일 인스턴스 |
|
||||
| **도구** | Read, Write, Bash, Grep, Glob |
|
||||
| **모델 (balanced)** | Sonnet |
|
||||
| **색상** | Green |
|
||||
| **생성물** | `{phase}-VERIFICATION.md` |
|
||||
|
||||
**핵심 동작.**
|
||||
- 작업 완료 여부가 아닌 단계 목표에 대해 코드베이스를 확인합니다
|
||||
- 구체적인 증거를 포함한 PASS/FAIL 결과를 제공합니다
|
||||
- `/gsd:verify-work`가 처리할 문제를 기록합니다
|
||||
|
||||
---
|
||||
|
||||
### gsd-nyquist-auditor
|
||||
|
||||
**역할:** 테스트를 생성하여 Nyquist 검증 누락을 채웁니다.
|
||||
|
||||
| 속성 | 값 |
|
||||
|----------|-------|
|
||||
| **생성 주체** | `/gsd:validate-phase` |
|
||||
| **병렬성** | 단일 인스턴스 |
|
||||
| **도구** | Read, Write, Edit, Bash, Grep, Glob |
|
||||
| **모델 (balanced)** | Sonnet |
|
||||
| **생성물** | 테스트 파일, 업데이트된 `VALIDATION.md` |
|
||||
|
||||
**핵심 동작.**
|
||||
- 구현 코드는 절대 수정하지 않습니다 — 테스트 파일만 수정합니다
|
||||
- 누락당 최대 3번 시도합니다
|
||||
- 구현 버그는 사용자에게 에스컬레이션으로 표시합니다
|
||||
|
||||
---
|
||||
|
||||
### gsd-ui-auditor
|
||||
|
||||
**역할:** 구현된 프론트엔드 코드에 대한 사후 6기둥 시각적 감사를 수행합니다.
|
||||
|
||||
| 속성 | 값 |
|
||||
|----------|-------|
|
||||
| **생성 주체** | `/gsd:ui-review` |
|
||||
| **병렬성** | 단일 인스턴스 |
|
||||
| **도구** | Read, Write, Bash, Grep, Glob |
|
||||
| **모델 (balanced)** | Sonnet |
|
||||
| **색상** | `#F472B6` (pink) |
|
||||
| **생성물** | 점수를 포함한 `{phase}-UI-REVIEW.md` |
|
||||
|
||||
**6가지 감사 기둥 (1-4점 채점).**
|
||||
1. 카피라이팅
|
||||
2. 시각적 요소
|
||||
3. 색상
|
||||
4. 타이포그래피
|
||||
5. 간격
|
||||
6. 경험 디자인
|
||||
|
||||
---
|
||||
|
||||
### gsd-codebase-mapper
|
||||
|
||||
**역할:** 코드베이스를 탐색하고 구조화된 분석 문서를 작성합니다.
|
||||
|
||||
| 속성 | 값 |
|
||||
|----------|-------|
|
||||
| **생성 주체** | `/gsd:map-codebase` |
|
||||
| **병렬성** | 4개 인스턴스 (tech, architecture, quality, concerns) |
|
||||
| **도구** | Read, Bash, Grep, Glob, Write |
|
||||
| **모델 (balanced)** | Haiku |
|
||||
| **색상** | Cyan |
|
||||
| **생성물** | `.planning/codebase/*.md` (7개 문서) |
|
||||
|
||||
**핵심 동작.**
|
||||
- 읽기 전용 탐색과 구조화된 출력
|
||||
- 문서를 디스크에 직접 작성합니다
|
||||
- 추론 불필요 — 파일 내용에서 패턴 추출
|
||||
|
||||
---
|
||||
|
||||
### gsd-debugger
|
||||
|
||||
**역할:** 영구 상태를 활용한 과학적 방법으로 버그를 조사합니다.
|
||||
|
||||
| 속성 | 값 |
|
||||
|----------|-------|
|
||||
| **생성 주체** | `/gsd:debug`, `/gsd:verify-work` (실패 시) |
|
||||
| **병렬성** | 단일 인스턴스 (대화형) |
|
||||
| **도구** | Read, Write, Edit, Bash, Grep, Glob, WebSearch |
|
||||
| **모델 (balanced)** | Sonnet |
|
||||
| **색상** | Orange |
|
||||
| **생성물** | `.planning/debug/*.md`, 지식 베이스 업데이트 |
|
||||
|
||||
**디버그 세션 생명주기.**
|
||||
`gathering` → `investigating` → `fixing` → `verifying` → `awaiting_human_verify` → `resolved`
|
||||
|
||||
**핵심 동작.**
|
||||
- 가설, 증거, 제거된 이론을 추적합니다
|
||||
- 컨텍스트 초기화 이후에도 상태가 유지됩니다
|
||||
- 해결됨으로 표시하기 전에 사람의 검증이 필요합니다
|
||||
- 해결 시 영구 지식 베이스에 추가합니다
|
||||
- 새 세션 시작 시 지식 베이스를 참조합니다
|
||||
|
||||
---
|
||||
|
||||
### gsd-user-profiler
|
||||
|
||||
**역할:** 8가지 행동 차원에 걸쳐 세션 메시지를 분석하여 점수화된 개발자 프로필을 생성합니다.
|
||||
|
||||
| 속성 | 값 |
|
||||
|----------|-------|
|
||||
| **생성 주체** | `/gsd:profile-user` |
|
||||
| **병렬성** | 단일 인스턴스 |
|
||||
| **도구** | Read |
|
||||
| **모델 (balanced)** | Sonnet |
|
||||
| **색상** | Magenta |
|
||||
| **생성물** | `USER-PROFILE.md`, `/gsd:dev-preferences`, `CLAUDE.md` 프로필 섹션 |
|
||||
|
||||
**행동 차원.**
|
||||
커뮤니케이션 스타일, 결정 패턴, 디버깅 접근 방식, UX 선호도, 벤더 선택, 불만 요인, 학습 스타일, 설명 깊이.
|
||||
|
||||
**핵심 동작.**
|
||||
- 읽기 전용 에이전트 — 추출된 세션 데이터를 분석하며 파일을 수정하지 않습니다
|
||||
- 신뢰 수준과 증거 인용을 포함한 점수화된 차원을 생성합니다
|
||||
- 세션 기록이 없는 경우 설문지 대체 방식을 사용합니다
|
||||
|
||||
---
|
||||
|
||||
## 에이전트 도구 권한 요약
|
||||
|
||||
| 에이전트 | Read | Write | Edit | Bash | Grep | Glob | WebSearch | WebFetch | MCP |
|
||||
|-------|------|-------|------|------|------|------|-----------|----------|-----|
|
||||
| project-researcher | ✓ | ✓ | | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
|
||||
| phase-researcher | ✓ | ✓ | | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
|
||||
| ui-researcher | ✓ | ✓ | | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
|
||||
| assumptions-analyzer | ✓ | | | ✓ | ✓ | ✓ | | | |
|
||||
| advisor-researcher | ✓ | | | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
|
||||
| research-synthesizer | ✓ | ✓ | | ✓ | | | | | |
|
||||
| planner | ✓ | ✓ | | ✓ | ✓ | ✓ | | ✓ | ✓ |
|
||||
| roadmapper | ✓ | ✓ | | ✓ | ✓ | ✓ | | | |
|
||||
| executor | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | | |
|
||||
| plan-checker | ✓ | | | ✓ | ✓ | ✓ | | | |
|
||||
| integration-checker | ✓ | | | ✓ | ✓ | ✓ | | | |
|
||||
| ui-checker | ✓ | | | ✓ | ✓ | ✓ | | | |
|
||||
| verifier | ✓ | ✓ | | ✓ | ✓ | ✓ | | | |
|
||||
| nyquist-auditor | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | | |
|
||||
| ui-auditor | ✓ | ✓ | | ✓ | ✓ | ✓ | | | |
|
||||
| codebase-mapper | ✓ | ✓ | | ✓ | ✓ | ✓ | | | |
|
||||
| debugger | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | |
|
||||
| user-profiler | ✓ | | | | | | | | |
|
||||
|
||||
**최소 권한 원칙.**
|
||||
- Checker는 읽기 전용입니다 (Write/Edit 없음) — 평가만 하며 수정하지 않습니다
|
||||
- Researcher는 웹 접근 권한을 가집니다 — 최신 생태계 정보가 필요하기 때문입니다
|
||||
- Executor는 Edit 권한을 가집니다 — 코드를 수정하지만 웹 접근은 없습니다
|
||||
- Mapper는 Write 권한을 가집니다 — 분석 문서를 작성하지만 Edit은 없습니다 (코드 변경 없음)
|
||||
527
docs/ko-KR/ARCHITECTURE.md
Normal file
527
docs/ko-KR/ARCHITECTURE.md
Normal file
@@ -0,0 +1,527 @@
|
||||
# GSD 아키텍처
|
||||
|
||||
> 기여자와 고급 사용자를 위한 시스템 아키텍처입니다. 사용자 문서는 [Feature Reference](FEATURES.md) 또는 [User Guide](USER-GUIDE.md)를 참조하세요.
|
||||
|
||||
---
|
||||
|
||||
## 목차
|
||||
|
||||
- [시스템 개요](#system-overview)
|
||||
- [설계 원칙](#design-principles)
|
||||
- [컴포넌트 아키텍처](#component-architecture)
|
||||
- [에이전트 모델](#agent-model)
|
||||
- [데이터 흐름](#data-flow)
|
||||
- [파일 시스템 구조](#file-system-layout)
|
||||
- [인스톨러 아키텍처](#installer-architecture)
|
||||
- [훅 시스템](#hook-system)
|
||||
- [CLI 도구 레이어](#cli-tools-layer)
|
||||
- [런타임 추상화](#runtime-abstraction)
|
||||
|
||||
---
|
||||
|
||||
## 시스템 개요
|
||||
|
||||
GSD는 사용자와 AI 코딩 에이전트(Claude Code, Gemini CLI, OpenCode, Codex, Copilot, Antigravity) 사이에 위치하는 **메타 프롬프팅 프레임워크**입니다. 다음을 제공합니다.
|
||||
|
||||
1. **컨텍스트 엔지니어링** — 작업별로 AI에게 필요한 모든 것을 제공하는 구조화된 아티팩트
|
||||
2. **멀티 에이전트 오케스트레이션** — 새로운 컨텍스트 윈도우로 전문화된 에이전트를 생성하는 가벼운 오케스트레이터
|
||||
3. **명세 주도 개발** — 요구 사항 → 조사 → 계획 → 실행 → 검증 파이프라인
|
||||
4. **상태 관리** — 세션과 컨텍스트 초기화를 넘나드는 영구적인 프로젝트 메모리
|
||||
|
||||
```
|
||||
┌──────────────────────────────────────────────────────┐
|
||||
│ USER │
|
||||
│ /gsd:command [args] │
|
||||
└─────────────────────┬────────────────────────────────┘
|
||||
│
|
||||
┌─────────────────────▼────────────────────────────────┐
|
||||
│ COMMAND LAYER │
|
||||
│ commands/gsd/*.md — Prompt-based command files │
|
||||
│ (Claude Code custom commands / Codex skills) │
|
||||
└─────────────────────┬────────────────────────────────┘
|
||||
│
|
||||
┌─────────────────────▼────────────────────────────────┐
|
||||
│ WORKFLOW LAYER │
|
||||
│ get-shit-done/workflows/*.md — Orchestration logic │
|
||||
│ (Reads references, spawns agents, manages state) │
|
||||
└──────┬──────────────┬─────────────────┬──────────────┘
|
||||
│ │ │
|
||||
┌──────▼──────┐ ┌─────▼─────┐ ┌────────▼───────┐
|
||||
│ AGENT │ │ AGENT │ │ AGENT │
|
||||
│ (fresh │ │ (fresh │ │ (fresh │
|
||||
│ context) │ │ context)│ │ context) │
|
||||
└──────┬──────┘ └─────┬─────┘ └────────┬───────┘
|
||||
│ │ │
|
||||
┌──────▼──────────────▼─────────────────▼──────────────┐
|
||||
│ CLI TOOLS LAYER │
|
||||
│ get-shit-done/bin/gsd-tools.cjs │
|
||||
│ (State, config, phase, roadmap, verify, templates) │
|
||||
└──────────────────────┬───────────────────────────────┘
|
||||
│
|
||||
┌──────────────────────▼───────────────────────────────┐
|
||||
│ FILE SYSTEM (.planning/) │
|
||||
│ PROJECT.md | REQUIREMENTS.md | ROADMAP.md │
|
||||
│ STATE.md | config.json | phases/ | research/ │
|
||||
└──────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 설계 원칙
|
||||
|
||||
### 1. 에이전트별 새로운 컨텍스트
|
||||
|
||||
오케스트레이터가 생성하는 모든 에이전트는 새로운 컨텍스트 윈도우(최대 200K 토큰)를 받습니다. 이를 통해 컨텍스트 오염을 방지합니다 — AI가 컨텍스트 윈도우에 누적된 대화로 인해 품질이 저하되는 현상입니다.
|
||||
|
||||
### 2. 가벼운 오케스트레이터
|
||||
|
||||
워크플로우 파일(`get-shit-done/workflows/*.md`)은 무거운 작업을 직접 수행하지 않습니다. 다음 작업만 담당합니다.
|
||||
- `gsd-tools.cjs init <workflow>`로 컨텍스트를 로드합니다
|
||||
- 집중된 프롬프트로 전문화된 에이전트를 생성합니다
|
||||
- 결과를 수집하여 다음 단계로 전달합니다
|
||||
- 단계 사이에 상태를 업데이트합니다
|
||||
|
||||
### 3. 파일 기반 상태
|
||||
|
||||
모든 상태는 `.planning/`에 사람이 읽을 수 있는 Markdown과 JSON으로 저장됩니다. 데이터베이스, 서버, 외부 의존성이 없습니다. 이를 통해 다음이 가능합니다.
|
||||
- 컨텍스트 초기화(`/clear`) 이후에도 상태가 유지됩니다
|
||||
- 사람과 에이전트 모두 상태를 확인할 수 있습니다
|
||||
- 팀 가시성을 위해 git에 커밋할 수 있습니다
|
||||
|
||||
### 4. 부재 = 활성화
|
||||
|
||||
워크플로우 기능 플래그는 **부재 = 활성화** 패턴을 따릅니다. `config.json`에 키가 없으면 기본값은 `true`입니다. 사용자는 기능을 명시적으로 비활성화하며 기본값을 활성화할 필요가 없습니다.
|
||||
|
||||
### 5. 심층 방어
|
||||
|
||||
여러 레이어가 일반적인 실패 모드를 방지합니다.
|
||||
- 계획은 실행 전에 검증됩니다 (plan-checker 에이전트)
|
||||
- 실행은 작업당 원자적 커밋을 생성합니다
|
||||
- 실행 후 검증은 단계 목표에 대해 확인합니다
|
||||
- UAT는 최종 게이트로서 사람의 검증을 제공합니다
|
||||
|
||||
---
|
||||
|
||||
## 컴포넌트 아키텍처
|
||||
|
||||
### Commands (`commands/gsd/*.md`)
|
||||
|
||||
사용자 대면 진입점입니다. 각 파일은 YAML 전문(name, description, allowed-tools)과 워크플로우를 부트스트랩하는 프롬프트 본문을 포함합니다. 명령어는 다음과 같이 설치됩니다.
|
||||
- **Claude Code:** 커스텀 슬래시 명령어 (`/gsd:command-name`)
|
||||
- **OpenCode:** 슬래시 명령어 (`/gsd-command-name`)
|
||||
- **Codex:** Skills (`$gsd-command-name`)
|
||||
- **Copilot:** 슬래시 명령어 (`/gsd:command-name`)
|
||||
- **Antigravity:** Skills
|
||||
|
||||
**전체 명령어 수:** 44개
|
||||
|
||||
### Workflows (`get-shit-done/workflows/*.md`)
|
||||
|
||||
명령어가 참조하는 오케스트레이션 로직입니다. 다음을 포함하는 단계별 프로세스를 담습니다.
|
||||
- `gsd-tools.cjs init`을 통한 컨텍스트 로드
|
||||
- 모델 해석을 포함한 에이전트 생성 지시
|
||||
- 게이트/체크포인트 정의
|
||||
- 상태 업데이트 패턴
|
||||
- 오류 처리 및 복구
|
||||
|
||||
**전체 워크플로우 수:** 46개
|
||||
|
||||
### Agents (`agents/*.md`)
|
||||
|
||||
다음을 지정하는 전문화된 에이전트 정의 파일입니다.
|
||||
- `name` — 에이전트 식별자
|
||||
- `description` — 역할과 목적
|
||||
- `tools` — 허용된 도구 접근 권한 (Read, Write, Edit, Bash, Grep, Glob, WebSearch 등)
|
||||
- `color` — 시각적 구분을 위한 터미널 출력 색상
|
||||
|
||||
**전체 에이전트 수:** 16개
|
||||
|
||||
### References (`get-shit-done/references/*.md`)
|
||||
|
||||
워크플로우와 에이전트가 `@-reference`로 참조하는 공유 지식 문서입니다.
|
||||
- `checkpoints.md` — 체크포인트 유형 정의 및 상호작용 패턴
|
||||
- `model-profiles.md` — 에이전트별 모델 티어 할당
|
||||
- `verification-patterns.md` — 다양한 아티팩트 유형 검증 방법
|
||||
- `planning-config.md` — 전체 config 스키마 및 동작
|
||||
- `git-integration.md` — git 커밋, 브랜칭, 히스토리 패턴
|
||||
- `questioning.md` — 프로젝트 초기화를 위한 꿈 추출 철학
|
||||
- `tdd.md` — 테스트 주도 개발 통합 패턴
|
||||
- `ui-brand.md` — 시각적 출력 포매팅 패턴
|
||||
|
||||
### Templates (`get-shit-done/templates/`)
|
||||
|
||||
모든 계획 아티팩트를 위한 Markdown 템플릿입니다. `gsd-tools.cjs template fill`과 `scaffold` 명령어가 사전 구조화된 파일을 생성하는 데 사용합니다.
|
||||
- `project.md`, `requirements.md`, `roadmap.md`, `state.md` — 핵심 프로젝트 파일
|
||||
- `phase-prompt.md` — 단계 실행 프롬프트 템플릿
|
||||
- `summary.md` (+ `summary-minimal.md`, `summary-standard.md`, `summary-complex.md`) — 세분화 인식 요약 템플릿
|
||||
- `DEBUG.md` — 디버그 세션 추적 템플릿
|
||||
- `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)
|
||||
|
||||
### Hooks (`hooks/`)
|
||||
|
||||
호스트 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`로 활성화) |
|
||||
|
||||
### CLI Tools (`get-shit-done/bin/`)
|
||||
|
||||
17개의 도메인 모듈을 포함하는 Node.js CLI 유틸리티(`gsd-tools.cjs`)입니다.
|
||||
|
||||
| 모듈 | 역할 |
|
||||
|--------|---------------|
|
||||
| `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 지원 |
|
||||
|
||||
---
|
||||
|
||||
## 에이전트 모델
|
||||
|
||||
### 오케스트레이터 → 에이전트 패턴
|
||||
|
||||
```
|
||||
Orchestrator (workflow .md)
|
||||
│
|
||||
├── Load context: gsd-tools.cjs init <workflow> <phase>
|
||||
│ Returns JSON with: project info, config, state, phase details
|
||||
│
|
||||
├── Resolve model: gsd-tools.cjs resolve-model <agent-name>
|
||||
│ Returns: opus | sonnet | haiku | inherit
|
||||
│
|
||||
├── Spawn Agent (Task/SubAgent call)
|
||||
│ ├── Agent prompt (agents/*.md)
|
||||
│ ├── Context payload (init JSON)
|
||||
│ ├── Model assignment
|
||||
│ └── Tool permissions
|
||||
│
|
||||
├── Collect result
|
||||
│
|
||||
└── Update state: gsd-tools.cjs state update/patch/advance-plan
|
||||
```
|
||||
|
||||
### 에이전트 생성 카테고리
|
||||
|
||||
| 카테고리 | 에이전트 | 병렬성 |
|
||||
|----------|--------|-------------|
|
||||
| **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` 중 계획은 의존성 웨이브로 그룹화됩니다.
|
||||
|
||||
```
|
||||
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)
|
||||
```
|
||||
|
||||
각 executor는 다음을 받습니다.
|
||||
- 새로운 200K 컨텍스트 윈도우
|
||||
- 실행할 특정 PLAN.md
|
||||
- 프로젝트 컨텍스트 (PROJECT.md, STATE.md)
|
||||
- 단계 컨텍스트 (CONTEXT.md, 사용 가능한 경우 RESEARCH.md)
|
||||
|
||||
#### 병렬 커밋 안전성
|
||||
|
||||
같은 웨이브 내에서 여러 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초 타임아웃)와 지터를 포함한 스핀 대기가 포함됩니다.
|
||||
|
||||
---
|
||||
|
||||
## 데이터 흐름
|
||||
|
||||
### 새 프로젝트 흐름
|
||||
|
||||
```
|
||||
User input (idea description)
|
||||
│
|
||||
▼
|
||||
Questions (questioning.md philosophy)
|
||||
│
|
||||
▼
|
||||
4x Project Researchers (parallel)
|
||||
├── Stack → STACK.md
|
||||
├── Features → FEATURES.md
|
||||
├── Architecture → ARCHITECTURE.md
|
||||
└── Pitfalls → PITFALLS.md
|
||||
│
|
||||
▼
|
||||
Research Synthesizer → SUMMARY.md
|
||||
│
|
||||
▼
|
||||
Requirements extraction → REQUIREMENTS.md
|
||||
│
|
||||
▼
|
||||
Roadmapper → ROADMAP.md
|
||||
│
|
||||
▼
|
||||
User approval → STATE.md initialized
|
||||
```
|
||||
|
||||
### 단계 실행 흐름
|
||||
|
||||
```
|
||||
discuss-phase → CONTEXT.md (user preferences)
|
||||
│
|
||||
▼
|
||||
ui-phase → UI-SPEC.md (design contract, optional)
|
||||
│
|
||||
▼
|
||||
plan-phase
|
||||
├── Phase Researcher → RESEARCH.md
|
||||
├── Planner → PLAN.md files
|
||||
└── Plan Checker → Verify loop (max 3x)
|
||||
│
|
||||
▼
|
||||
execute-phase
|
||||
├── Wave analysis (dependency grouping)
|
||||
├── Executor per plan → code + atomic commits
|
||||
├── SUMMARY.md per plan
|
||||
└── Verifier → VERIFICATION.md
|
||||
│
|
||||
▼
|
||||
verify-work → UAT.md (user acceptance testing)
|
||||
│
|
||||
▼
|
||||
ui-review → UI-REVIEW.md (visual audit, optional)
|
||||
```
|
||||
|
||||
### 컨텍스트 전파
|
||||
|
||||
각 워크플로우 단계는 이후 단계에 공급되는 아티팩트를 생성합니다.
|
||||
|
||||
```
|
||||
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
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 파일 시스템 구조
|
||||
|
||||
### 설치 파일
|
||||
|
||||
```
|
||||
~/.claude/ # Claude Code (전역 설치)
|
||||
├── commands/gsd/*.md # 37개 슬래시 명령어
|
||||
├── 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 # 업데이트 확인 훅
|
||||
├── settings.json # 훅 등록
|
||||
└── VERSION # 설치된 버전 번호
|
||||
```
|
||||
|
||||
다른 런타임의 동등한 경로입니다.
|
||||
- **OpenCode:** `~/.config/opencode/` 또는 `~/.opencode/`
|
||||
- **Gemini CLI:** `~/.gemini/`
|
||||
- **Codex:** `~/.codex/` (명령어 대신 skills 사용)
|
||||
- **Copilot:** `~/.github/`
|
||||
- **Antigravity:** `~/.gemini/antigravity/` (전역) 또는 `./.agent/` (로컬)
|
||||
|
||||
### 프로젝트 파일 (`.planning/`)
|
||||
|
||||
```
|
||||
.planning/
|
||||
├── PROJECT.md # 프로젝트 비전, 제약, 결정, 진화 규칙
|
||||
├── REQUIREMENTS.md # 범위 지정된 요구 사항 (v1/v2/범위 외)
|
||||
├── ROADMAP.md # 상태 추적을 포함한 단계 분류
|
||||
├── STATE.md # 살아있는 메모리: 위치, 결정, 차단, 메트릭
|
||||
├── config.json # 워크플로우 설정
|
||||
├── MILESTONES.md # 완료된 마일스톤 보관
|
||||
├── research/ # /gsd:new-project의 도메인 조사
|
||||
│ ├── SUMMARY.md
|
||||
│ ├── STACK.md
|
||||
│ ├── FEATURES.md
|
||||
│ ├── ARCHITECTURE.md
|
||||
│ └── PITFALLS.md
|
||||
├── codebase/ # 브라운필드 매핑 (/gsd:map-codebase에서)
|
||||
│ ├── STACK.md
|
||||
│ ├── ARCHITECTURE.md
|
||||
│ ├── CONVENTIONS.md
|
||||
│ ├── CONCERNS.md
|
||||
│ ├── STRUCTURE.md
|
||||
│ ├── TESTING.md
|
||||
│ └── INTEGRATIONS.md
|
||||
├── phases/
|
||||
│ └── XX-phase-name/
|
||||
│ ├── XX-CONTEXT.md # 사용자 선호도 (discuss-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-REVIEW.md # 시각적 감사 점수 (ui-review에서)
|
||||
│ └── XX-UAT.md # 사용자 수용 테스트 결과
|
||||
├── quick/ # 빠른 작업 추적
|
||||
│ └── YYMMDD-xxx-slug/
|
||||
│ ├── PLAN.md
|
||||
│ └── SUMMARY.md
|
||||
├── todos/
|
||||
│ ├── pending/ # 캡처된 아이디어
|
||||
│ └── done/ # 완료된 할 일
|
||||
├── threads/ # 영구 컨텍스트 스레드 (/gsd:thread에서)
|
||||
├── seeds/ # 미래 지향적 아이디어 (/gsd:plant-seed에서)
|
||||
├── debug/ # 활성 디버그 세션
|
||||
│ ├── *.md # 활성 세션
|
||||
│ ├── resolved/ # 보관된 세션
|
||||
│ └── knowledge-base.md # 영구 디버그 학습 내용
|
||||
├── ui-reviews/ # /gsd:ui-review의 스크린샷 (gitignored)
|
||||
└── continue-here.md # 컨텍스트 핸드오프 (pause-work에서)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 인스톨러 아키텍처
|
||||
|
||||
인스톨러(`bin/install.js`, ~3,000줄)는 다음을 처리합니다.
|
||||
|
||||
1. **런타임 감지** — 대화형 프롬프트 또는 CLI 플래그 (`--claude`, `--opencode`, `--gemini`, `--codex`, `--copilot`, `--antigravity`, `--all`)
|
||||
2. **위치 선택** — 전역(`--global`) 또는 로컬(`--local`)
|
||||
3. **파일 배포** — commands, workflows, references, templates, agents, hooks 복사
|
||||
4. **런타임 적응** — 런타임별 파일 내용 변환.
|
||||
- Claude Code: 그대로 사용
|
||||
- OpenCode: 에이전트 전문을 `name:`, `model: inherit`, `mode: subagent`로 변환
|
||||
- Codex: commands에서 TOML config + skills 생성
|
||||
- Copilot: 도구 이름 매핑 (Read→read, Bash→execute 등)
|
||||
- Gemini: 훅 이벤트 이름 조정 (`PostToolUse` 대신 `AfterTool`)
|
||||
- Antigravity: Google 모델 등가물을 사용한 skills-first 방식
|
||||
5. **경로 정규화** — `~/.claude/` 경로를 런타임별 경로로 교체
|
||||
6. **설정 통합** — 런타임의 `settings.json`에 훅 등록
|
||||
7. **패치 백업** — v1.17부터 로컬 수정 파일을 `gsd-local-patches/`에 백업하여 `/gsd:reapply-patches`에 사용
|
||||
8. **매니페스트 추적** — 깔끔한 제거를 위해 `gsd-file-manifest.json` 작성
|
||||
9. **제거 모드** — `--uninstall`로 모든 GSD 파일, 훅, 설정 제거
|
||||
|
||||
### 플랫폼 처리
|
||||
|
||||
- **Windows:** 자식 프로세스에 `windowsHide` 적용, 보호 디렉터리의 EPERM/EACCES 방지, 경로 구분자 정규화
|
||||
- **WSL:** WSL에서 실행 중인 Windows Node.js를 감지하고 경로 불일치에 대해 경고
|
||||
- **Docker/CI:** 커스텀 config 디렉터리 위치를 위한 `CLAUDE_CONFIG_DIR` 환경 변수 지원
|
||||
|
||||
---
|
||||
|
||||
## 훅 시스템
|
||||
|
||||
### 아키텍처
|
||||
|
||||
```
|
||||
Runtime Engine (Claude Code / Gemini CLI)
|
||||
│
|
||||
├── statusLine event ──► gsd-statusline.js
|
||||
│ Reads: stdin (session JSON)
|
||||
│ Writes: stdout (formatted status), /tmp/claude-ctx-{session}.json (bridge)
|
||||
│
|
||||
├── PostToolUse/AfterTool event ──► gsd-context-monitor.js
|
||||
│ Reads: stdin (tool event JSON), /tmp/claude-ctx-{session}.json (bridge)
|
||||
│ Writes: stdout (hookSpecificOutput with additionalContext warning)
|
||||
│
|
||||
└── SessionStart event ──► gsd-check-update.js
|
||||
Reads: VERSION file
|
||||
Writes: ~/.claude/cache/gsd-update-check.json (spawns background process)
|
||||
```
|
||||
|
||||
### 컨텍스트 모니터 임계값
|
||||
|
||||
| 잔여 컨텍스트 | 수준 | 에이전트 동작 |
|
||||
|-------------------|-------|----------------|
|
||||
| > 35% | 정상 | 경고 주입 없음 |
|
||||
| ≤ 35% | WARNING | "복잡한 새 작업 시작을 피하세요" |
|
||||
| ≤ 25% | CRITICAL | "컨텍스트가 거의 소진됨, 사용자에게 알리세요" |
|
||||
|
||||
디바운스: 반복 경고 사이에 5회 도구 사용. 심각도 에스컬레이션(WARNING→CRITICAL)은 디바운스를 우회합니다.
|
||||
|
||||
### 안전 속성
|
||||
|
||||
- 모든 훅은 try/catch로 감싸여 있으며 오류 시 자동 종료합니다
|
||||
- stdin 타임아웃 가드(3초)로 파이프 문제 시 중단 방지
|
||||
- 오래된 메트릭(60초 이상)은 무시됩니다
|
||||
- 누락된 브리지 파일은 정상적으로 처리됩니다 (서브에이전트, 새 세션)
|
||||
- 컨텍스트 모니터는 권고용입니다 — 사용자 선호도를 재정의하는 명령을 내리지 않습니다
|
||||
|
||||
### 보안 훅 (v1.27)
|
||||
|
||||
**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는 통합된 명령어/워크플로우 아키텍처를 통해 6개의 AI 코딩 런타임을 지원합니다.
|
||||
|
||||
| 런타임 | 명령어 형식 | 에이전트 시스템 | 설정 위치 |
|
||||
|---------|---------------|--------------|-----------------|
|
||||
| Claude Code | `/gsd:command` | Task 생성 | `~/.claude/` |
|
||||
| OpenCode | `/gsd-command` | Subagent 모드 | `~/.config/opencode/` |
|
||||
| Gemini CLI | `/gsd:command` | Task 생성 | `~/.gemini/` |
|
||||
| Codex | `$gsd-command` | Skills | `~/.codex/` |
|
||||
| Copilot | `/gsd:command` | 에이전트 위임 | `~/.github/` |
|
||||
| Antigravity | Skills | Skills | `~/.gemini/antigravity/` |
|
||||
|
||||
### 추상화 포인트
|
||||
|
||||
1. **도구 이름 매핑** — 각 런타임은 고유한 도구 이름을 가집니다 (예: Claude의 `Bash` → Copilot의 `execute`)
|
||||
2. **훅 이벤트 이름** — Claude는 `PostToolUse`를 사용하고 Gemini는 `AfterTool`을 사용합니다
|
||||
3. **에이전트 전문** — 각 런타임은 고유한 에이전트 정의 형식을 가집니다
|
||||
4. **경로 규칙** — 각 런타임은 서로 다른 디렉터리에 설정을 저장합니다
|
||||
5. **모델 참조** — `inherit` 프로필을 통해 GSD가 런타임의 모델 선택에 위임합니다
|
||||
|
||||
인스톨러는 설치 시 모든 변환을 처리합니다. 워크플로우와 에이전트는 Claude Code의 네이티브 형식으로 작성되어 배포 중에 변환됩니다.
|
||||
367
docs/ko-KR/CLI-TOOLS.md
Normal file
367
docs/ko-KR/CLI-TOOLS.md
Normal file
@@ -0,0 +1,367 @@
|
||||
# GSD CLI 도구 레퍼런스
|
||||
|
||||
> `gsd-tools.cjs`에 대한 프로그래밍 방식 API 레퍼런스입니다. 워크플로우와 에이전트가 내부적으로 사용합니다. 사용자 대면 명령어는 [Command Reference](COMMANDS.md)를 참조하세요.
|
||||
|
||||
---
|
||||
|
||||
## 개요
|
||||
|
||||
`gsd-tools.cjs`는 GSD의 약 50개 명령어, 워크플로우, 에이전트 파일에서 반복되는 인라인 bash 패턴을 대체하는 Node.js CLI 유틸리티입니다. config 파싱, 모델 해석, 단계 조회, git 커밋, 요약 검증, 상태 관리, 템플릿 작업을 중앙화합니다.
|
||||
|
||||
**위치:** `get-shit-done/bin/gsd-tools.cjs`
|
||||
**모듈:** `get-shit-done/bin/lib/`의 15개 도메인 모듈
|
||||
|
||||
**사용법:**
|
||||
```bash
|
||||
node gsd-tools.cjs <command> [args] [--raw] [--cwd <path>]
|
||||
```
|
||||
|
||||
**전역 플래그.**
|
||||
| 플래그 | 설명 |
|
||||
|------|-------------|
|
||||
| `--raw` | 기계 가독형 출력 (JSON 또는 일반 텍스트, 포매팅 없음) |
|
||||
| `--cwd <path>` | 작업 디렉터리 재정의 (샌드박스 서브에이전트용) |
|
||||
|
||||
---
|
||||
|
||||
## State 명령어
|
||||
|
||||
`.planning/STATE.md`를 관리합니다 — 프로젝트의 살아있는 메모리입니다.
|
||||
|
||||
```bash
|
||||
# 전체 프로젝트 config + state를 JSON으로 로드
|
||||
node gsd-tools.cjs state load
|
||||
|
||||
# STATE.md 전문을 JSON으로 출력
|
||||
node gsd-tools.cjs state json
|
||||
|
||||
# 단일 필드 업데이트
|
||||
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
|
||||
|
||||
# 계획 카운터 증가
|
||||
node gsd-tools.cjs state advance-plan
|
||||
|
||||
# 실행 메트릭 기록
|
||||
node gsd-tools.cjs state record-metric --phase N --plan M --duration Xmin [--tasks N] [--files N]
|
||||
|
||||
# 진행률 바 재계산
|
||||
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 Snapshot
|
||||
|
||||
전체 STATE.md의 구조화된 파싱 결과입니다.
|
||||
|
||||
```bash
|
||||
node gsd-tools.cjs state-snapshot
|
||||
```
|
||||
|
||||
현재 위치, 단계, 계획, 상태, 결정, 차단, 메트릭, 최근 활동을 포함한 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`를 파싱하고 업데이트합니다.
|
||||
|
||||
```bash
|
||||
# ROADMAP.md에서 단계 섹션 추출
|
||||
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`을 읽고 씁니다.
|
||||
|
||||
```bash
|
||||
# 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>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 모델 해석
|
||||
|
||||
```bash
|
||||
# 현재 프로필 기반으로 에이전트 모델 가져오기
|
||||
node gsd-tools.cjs resolve-model <agent-name>
|
||||
# 반환값: opus | sonnet | haiku | inherit
|
||||
```
|
||||
|
||||
에이전트 이름: `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 명령어
|
||||
|
||||
계획, 단계, 참조, 커밋을 검증합니다.
|
||||
|
||||
```bash
|
||||
# SUMMARY.md 파일 검증
|
||||
node gsd-tools.cjs verify-summary <path> [--check-count N]
|
||||
|
||||
# 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>
|
||||
|
||||
# 커밋 해시 일괄 검증
|
||||
node gsd-tools.cjs verify commits <hash1> [hash2] ...
|
||||
|
||||
# must_haves.artifacts 확인
|
||||
node gsd-tools.cjs verify artifacts <plan-file>
|
||||
|
||||
# must_haves.key_links 확인
|
||||
node gsd-tools.cjs verify key-links <plan-file>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Validation 명령어
|
||||
|
||||
프로젝트 무결성을 확인합니다.
|
||||
|
||||
```bash
|
||||
# 단계 번호 매기기, 디스크/로드맵 동기화 확인
|
||||
node gsd-tools.cjs validate consistency
|
||||
|
||||
# .planning/ 무결성 확인, 선택적으로 복구
|
||||
node gsd-tools.cjs validate health [--repair]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 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`
|
||||
|
||||
---
|
||||
|
||||
## Frontmatter 명령어
|
||||
|
||||
모든 Markdown 파일에 대한 YAML 전문 CRUD 작업입니다.
|
||||
|
||||
```bash
|
||||
# 전문을 JSON으로 추출
|
||||
node gsd-tools.cjs frontmatter get <file> [--field key]
|
||||
|
||||
# 단일 필드 업데이트
|
||||
node gsd-tools.cjs frontmatter set <file> --field key --value jsonVal
|
||||
|
||||
# JSON을 전문에 병합
|
||||
node gsd-tools.cjs frontmatter merge <file> --data '{json}'
|
||||
|
||||
# 필수 필드 검증
|
||||
node gsd-tools.cjs frontmatter validate <file> --schema plan|summary|verification
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Scaffold 명령어
|
||||
|
||||
사전 구조화된 파일과 디렉터리를 생성합니다.
|
||||
|
||||
```bash
|
||||
# CONTEXT.md 템플릿 생성
|
||||
node gsd-tools.cjs scaffold context --phase N
|
||||
|
||||
# UAT.md 템플릿 생성
|
||||
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 명령어 (복합 컨텍스트 로드)
|
||||
|
||||
특정 워크플로우에 필요한 모든 컨텍스트를 단일 호출로 로드합니다. 프로젝트 정보, config, state, 워크플로우별 데이터를 포함한 JSON을 반환합니다.
|
||||
|
||||
```bash
|
||||
node gsd-tools.cjs init execute-phase <phase>
|
||||
node gsd-tools.cjs init plan-phase <phase>
|
||||
node gsd-tools.cjs init new-project
|
||||
node gsd-tools.cjs init new-milestone
|
||||
node gsd-tools.cjs init quick <description>
|
||||
node gsd-tools.cjs init resume
|
||||
node gsd-tools.cjs init verify-work <phase>
|
||||
node gsd-tools.cjs init phase-op <phase>
|
||||
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
|
||||
```
|
||||
|
||||
**대용량 페이로드 처리:** 출력이 약 50KB를 초과하면 CLI가 임시 파일에 쓰고 `@file:/tmp/gsd-init-XXXXX.json`을 반환합니다. 워크플로우는 `@file:` 접두사를 확인하고 디스크에서 읽습니다.
|
||||
|
||||
```bash
|
||||
INIT=$(node gsd-tools.cjs init execute-phase "1")
|
||||
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
|
||||
# 텍스트를 URL 안전 슬러그로 변환
|
||||
node gsd-tools.cjs generate-slug "Some Text Here"
|
||||
# → 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 데이터 집계
|
||||
node gsd-tools.cjs history-digest
|
||||
|
||||
# SUMMARY.md에서 구조화된 데이터 추출
|
||||
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]
|
||||
|
||||
# 할 일 완료 처리
|
||||
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]
|
||||
```
|
||||
|
||||
> **`--no-verify`**: 사전 커밋 훅을 건너뜁니다. 빌드 잠금 경쟁을 피하기 위해 웨이브 기반 실행 중 병렬 executor 에이전트가 사용합니다 (예: Rust 프로젝트의 cargo lock 충돌). 오케스트레이터는 각 웨이브 완료 후 훅을 한 번 실행합니다. 순차 실행 중에는 `--no-verify`를 사용하지 마세요 — 훅이 정상적으로 실행되어야 합니다.
|
||||
|
||||
```bash
|
||||
# 웹 검색 (Brave API 키 필요)
|
||||
node gsd-tools.cjs websearch <query> [--limit N] [--freshness day|week|month]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 모듈 아키텍처
|
||||
|
||||
| 모듈 | 파일 | 내보내기 |
|
||||
|--------|------|---------|
|
||||
| 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` |
|
||||
| Roadmap | `lib/roadmap.cjs` | 로드맵 파싱, 단계 추출, 진행률 업데이트 |
|
||||
| Config | `lib/config.cjs` | Config 읽기/쓰기, 섹션 초기화 |
|
||||
| Verify | `lib/verify.cjs` | 모든 verification 및 validation 명령어 |
|
||||
| Template | `lib/template.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` | 개발자 프로필 포매팅 |
|
||||
| Profile Pipeline | `lib/profile-pipeline.cjs` | 세션 분석 파이프라인 |
|
||||
933
docs/ko-KR/COMMANDS.md
Normal file
933
docs/ko-KR/COMMANDS.md
Normal file
@@ -0,0 +1,933 @@
|
||||
# GSD 명령어 레퍼런스
|
||||
|
||||
> 전체 명령어 문법, 플래그, 옵션, 사용 예시를 다룹니다. 기능 상세 설명은 [Feature Reference](FEATURES.md)를 참고하세요. 워크플로우 안내는 [User Guide](USER-GUIDE.md)를 참고하세요.
|
||||
|
||||
---
|
||||
|
||||
## 명령어 문법
|
||||
|
||||
- **Claude Code / Gemini / Copilot:** `/gsd:command-name [args]`
|
||||
- **OpenCode:** `/gsd-command-name [args]`
|
||||
- **Codex:** `$gsd-command-name [args]`
|
||||
|
||||
---
|
||||
|
||||
## 핵심 워크플로우 명령어
|
||||
|
||||
### `/gsd:new-project`
|
||||
|
||||
심층 컨텍스트 수집을 통해 새 프로젝트를 초기화합니다.
|
||||
|
||||
| 플래그 | 설명 |
|
||||
|--------|------|
|
||||
| `--auto @file.md` | 문서에서 자동으로 정보를 추출하고 대화형 질문을 건너뜁니다 |
|
||||
|
||||
**사전 조건:** `.planning/PROJECT.md`가 존재하지 않아야 합니다.
|
||||
**생성 파일:** `PROJECT.md`, `REQUIREMENTS.md`, `ROADMAP.md`, `STATE.md`, `config.json`, `research/`, `CLAUDE.md`
|
||||
|
||||
```bash
|
||||
/gsd:new-project # 대화형 모드
|
||||
/gsd:new-project --auto @prd.md # PRD에서 자동 추출
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `/gsd:new-workspace`
|
||||
|
||||
격리된 워크스페이스를 생성합니다. 저장소 복사본과 독립적인 `.planning/` 디렉터리가 포함됩니다.
|
||||
|
||||
| 플래그 | 설명 |
|
||||
|--------|------|
|
||||
| `--name <name>` | 워크스페이스 이름 (필수) |
|
||||
| `--repos repo1,repo2` | 쉼표로 구분된 저장소 경로 또는 이름 |
|
||||
| `--path /target` | 대상 디렉터리 (기본값: `~/gsd-workspaces/<name>`) |
|
||||
| `--strategy worktree\|clone` | 복사 전략 (기본값: `worktree`) |
|
||||
| `--branch <name>` | 체크아웃할 브랜치 (기본값: `workspace/<name>`) |
|
||||
| `--auto` | 대화형 질문을 건너뜁니다 |
|
||||
|
||||
**사용 사례.**
|
||||
- 멀티 저장소: 격리된 GSD 상태로 일부 저장소만 작업합니다.
|
||||
- 기능 격리: `--repos .`는 현재 저장소의 worktree를 생성합니다.
|
||||
|
||||
**생성 파일:** `WORKSPACE.md`, `.planning/`, 저장소 복사본 (worktree 또는 clone)
|
||||
|
||||
```bash
|
||||
/gsd:new-workspace --name feature-b --repos hr-ui,ZeymoAPI
|
||||
/gsd:new-workspace --name feature-b --repos . --strategy worktree # 동일 저장소 격리
|
||||
/gsd:new-workspace --name spike --repos api,web --strategy clone # 전체 클론
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `/gsd:list-workspaces`
|
||||
|
||||
활성 GSD 워크스페이스와 상태를 목록으로 표시합니다.
|
||||
|
||||
**스캔 위치:** `~/gsd-workspaces/`에서 `WORKSPACE.md` 매니페스트를 탐색합니다.
|
||||
**표시 항목:** 이름, 저장소 수, 전략, GSD 프로젝트 상태
|
||||
|
||||
```bash
|
||||
/gsd:list-workspaces
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `/gsd:remove-workspace`
|
||||
|
||||
워크스페이스를 제거하고 git worktree를 정리합니다.
|
||||
|
||||
| 인수 | 필수 여부 | 설명 |
|
||||
|------|----------|------|
|
||||
| `<name>` | 예 | 제거할 워크스페이스 이름 |
|
||||
|
||||
**안전 장치:** 저장소에 커밋되지 않은 변경사항이 있으면 제거를 거부합니다. 이름 확인이 필요합니다.
|
||||
|
||||
```bash
|
||||
/gsd:remove-workspace feature-b
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `/gsd:discuss-phase`
|
||||
|
||||
계획 수립 전에 구현 결정사항을 캡처합니다.
|
||||
|
||||
| 인수 | 필수 여부 | 설명 |
|
||||
|------|----------|------|
|
||||
| `N` | 아니오 | 페이즈 번호 (기본값: 현재 페이즈) |
|
||||
|
||||
| 플래그 | 설명 |
|
||||
|--------|------|
|
||||
| `--auto` | 모든 질문에 추천 기본값을 자동으로 선택합니다 |
|
||||
| `--batch` | 질문을 하나씩 처리하는 대신 일괄 입력 방식으로 그룹화합니다 |
|
||||
| `--analyze` | 토론 중 트레이드오프 분석을 추가합니다 |
|
||||
|
||||
**사전 조건:** `.planning/ROADMAP.md`가 존재해야 합니다.
|
||||
**생성 파일:** `{phase}-CONTEXT.md`, `{phase}-DISCUSSION-LOG.md` (감사 추적)
|
||||
|
||||
```bash
|
||||
/gsd:discuss-phase 1 # 페이즈 1 대화형 토론
|
||||
/gsd:discuss-phase 3 --auto # 페이즈 3 기본값 자동 선택
|
||||
/gsd:discuss-phase --batch # 현재 페이즈 일괄 모드
|
||||
/gsd:discuss-phase 2 --analyze # 트레이드오프 분석 포함 토론
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `/gsd:ui-phase`
|
||||
|
||||
프론트엔드 페이즈를 위한 UI 설계 계약을 생성합니다.
|
||||
|
||||
| 인수 | 필수 여부 | 설명 |
|
||||
|------|----------|------|
|
||||
| `N` | 아니오 | 페이즈 번호 (기본값: 현재 페이즈) |
|
||||
|
||||
**사전 조건:** `.planning/ROADMAP.md`가 존재해야 하며 해당 페이즈에 프론트엔드/UI 작업이 포함되어야 합니다.
|
||||
**생성 파일:** `{phase}-UI-SPEC.md`
|
||||
|
||||
```bash
|
||||
/gsd:ui-phase 2 # 페이즈 2 설계 계약 생성
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `/gsd:plan-phase`
|
||||
|
||||
페이즈를 조사하고 계획하며 검증합니다.
|
||||
|
||||
| 인수 | 필수 여부 | 설명 |
|
||||
|------|----------|------|
|
||||
| `N` | 아니오 | 페이즈 번호 (기본값: 다음 미계획 페이즈) |
|
||||
|
||||
| 플래그 | 설명 |
|
||||
|--------|------|
|
||||
| `--auto` | 대화형 확인을 건너뜁니다 |
|
||||
| `--research` | RESEARCH.md가 있어도 재조사를 강제합니다 |
|
||||
| `--skip-research` | 도메인 조사 단계를 건너뜁니다 |
|
||||
| `--gaps` | 갭 보완 모드 (VERIFICATION.md를 읽고 조사를 건너뜁니다) |
|
||||
| `--skip-verify` | 계획 검증 루프를 건너뜁니다 |
|
||||
| `--prd <file>` | discuss-phase 대신 PRD 파일을 컨텍스트로 사용합니다 |
|
||||
| `--reviews` | REVIEWS.md의 교차 AI 리뷰 피드백으로 재계획합니다 |
|
||||
|
||||
**사전 조건:** `.planning/ROADMAP.md`가 존재해야 합니다.
|
||||
**생성 파일:** `{phase}-RESEARCH.md`, `{phase}-{N}-PLAN.md`, `{phase}-VALIDATION.md`
|
||||
|
||||
```bash
|
||||
/gsd:plan-phase 1 # 페이즈 1 조사 + 계획 + 검증
|
||||
/gsd:plan-phase 3 --skip-research # 조사 없이 계획 (익숙한 도메인)
|
||||
/gsd:plan-phase --auto # 비대화형 계획 수립
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `/gsd:execute-phase`
|
||||
|
||||
페이즈의 모든 계획을 웨이브 기반 병렬화로 실행하거나 특정 웨이브만 실행합니다.
|
||||
|
||||
| 인수 | 필수 여부 | 설명 |
|
||||
|------|----------|------|
|
||||
| `N` | **예** | 실행할 페이즈 번호 |
|
||||
| `--wave N` | 아니오 | 페이즈 내 Wave `N`만 실행합니다 |
|
||||
|
||||
**사전 조건:** 페이즈에 PLAN.md 파일이 있어야 합니다.
|
||||
**생성 파일:** 계획별 `{phase}-{N}-SUMMARY.md`, git 커밋, 페이즈가 완전히 완료되면 `{phase}-VERIFICATION.md`
|
||||
|
||||
```bash
|
||||
/gsd:execute-phase 1 # 페이즈 1 실행
|
||||
/gsd:execute-phase 1 --wave 2 # Wave 2만 실행
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `/gsd:verify-work`
|
||||
|
||||
자동 진단을 포함한 사용자 인수 테스트(UAT)를 수행합니다.
|
||||
|
||||
| 인수 | 필수 여부 | 설명 |
|
||||
|------|----------|------|
|
||||
| `N` | 아니오 | 페이즈 번호 (기본값: 마지막 실행된 페이즈) |
|
||||
|
||||
**사전 조건:** 페이즈가 실행되어 있어야 합니다.
|
||||
**생성 파일:** `{phase}-UAT.md`, 문제 발견 시 수정 계획
|
||||
|
||||
```bash
|
||||
/gsd:verify-work 1 # 페이즈 1 UAT
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `/gsd:next`
|
||||
|
||||
다음 논리적 워크플로우 단계로 자동으로 이동합니다. 프로젝트 상태를 읽고 적절한 명령어를 실행합니다.
|
||||
|
||||
**사전 조건:** `.planning/` 디렉터리가 존재해야 합니다.
|
||||
**동작 방식.**
|
||||
- 프로젝트 없음 → `/gsd:new-project` 제안
|
||||
- 페이즈 토론 필요 → `/gsd:discuss-phase` 실행
|
||||
- 페이즈 계획 필요 → `/gsd:plan-phase` 실행
|
||||
- 페이즈 실행 필요 → `/gsd:execute-phase` 실행
|
||||
- 페이즈 검증 필요 → `/gsd:verify-work` 실행
|
||||
- 모든 페이즈 완료 → `/gsd:complete-milestone` 제안
|
||||
|
||||
```bash
|
||||
/gsd:next # 다음 단계 자동 감지 및 실행
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `/gsd:session-report`
|
||||
|
||||
작업 요약, 결과, 예상 리소스 사용량을 포함한 세션 보고서를 생성합니다.
|
||||
|
||||
**사전 조건:** 최근 작업이 있는 활성 프로젝트
|
||||
**생성 파일:** `.planning/reports/SESSION_REPORT.md`
|
||||
|
||||
```bash
|
||||
/gsd:session-report # 세션 종료 후 요약 생성
|
||||
```
|
||||
|
||||
**보고서 포함 내용.**
|
||||
- 수행된 작업 (커밋, 실행된 계획, 진행된 페이즈)
|
||||
- 결과 및 산출물
|
||||
- 블로커 및 결정 사항
|
||||
- 예상 토큰/비용 사용량
|
||||
- 다음 단계 권장사항
|
||||
|
||||
---
|
||||
|
||||
### `/gsd:ship`
|
||||
|
||||
완료된 페이즈 작업으로부터 자동 생성된 본문이 포함된 PR을 만듭니다.
|
||||
|
||||
| 인수 | 필수 여부 | 설명 |
|
||||
|------|----------|------|
|
||||
| `N` | 아니오 | 페이즈 번호 또는 마일스톤 버전 (예: `4` 또는 `v1.0`) |
|
||||
| `--draft` | 아니오 | 초안 PR로 생성합니다 |
|
||||
|
||||
**사전 조건:** 페이즈 검증 완료 (`/gsd:verify-work` 통과), `gh` CLI 설치 및 인증
|
||||
**생성 파일:** 계획 아티팩트 기반의 풍부한 본문이 포함된 GitHub PR, STATE.md 업데이트
|
||||
|
||||
```bash
|
||||
/gsd:ship 4 # 페이즈 4 출시
|
||||
/gsd:ship 4 --draft # 초안 PR로 출시
|
||||
```
|
||||
|
||||
**PR 본문 포함 내용.**
|
||||
- ROADMAP.md의 페이즈 목표
|
||||
- SUMMARY.md 파일의 변경사항 요약
|
||||
- 처리된 요구사항 (REQ-ID)
|
||||
- 검증 상태
|
||||
- 핵심 결정사항
|
||||
|
||||
---
|
||||
|
||||
### `/gsd:ui-review`
|
||||
|
||||
구현된 프론트엔드의 6개 기둥 기반 시각적 감사를 소급하여 수행합니다.
|
||||
|
||||
| 인수 | 필수 여부 | 설명 |
|
||||
|------|----------|------|
|
||||
| `N` | 아니오 | 페이즈 번호 (기본값: 마지막 실행된 페이즈) |
|
||||
|
||||
**사전 조건:** 프론트엔드 코드가 있는 프로젝트 (독립 실행 가능, GSD 프로젝트 불필요)
|
||||
**생성 파일:** `{phase}-UI-REVIEW.md`, `.planning/ui-reviews/`에 스크린샷
|
||||
|
||||
```bash
|
||||
/gsd:ui-review # 현재 페이즈 감사
|
||||
/gsd:ui-review 3 # 페이즈 3 감사
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `/gsd:audit-uat`
|
||||
|
||||
모든 미완료 UAT 및 검증 항목에 대한 교차 페이즈 감사를 수행합니다.
|
||||
|
||||
**사전 조건:** UAT 또는 검증이 포함된 페이즈가 하나 이상 실행되어 있어야 합니다.
|
||||
**생성 파일:** 사람이 직접 수행하는 테스트 계획이 포함된 분류된 감사 보고서
|
||||
|
||||
```bash
|
||||
/gsd:audit-uat
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `/gsd:audit-milestone`
|
||||
|
||||
마일스톤이 완료 정의를 충족했는지 검증합니다.
|
||||
|
||||
**사전 조건:** 모든 페이즈가 실행되어 있어야 합니다.
|
||||
**생성 파일:** 갭 분석이 포함된 감사 보고서
|
||||
|
||||
```bash
|
||||
/gsd:audit-milestone
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `/gsd:complete-milestone`
|
||||
|
||||
마일스톤을 아카이브하고 릴리스 태그를 생성합니다.
|
||||
|
||||
**사전 조건:** 마일스톤 감사 완료 권장
|
||||
**생성 파일:** `MILESTONES.md` 항목, git 태그
|
||||
|
||||
```bash
|
||||
/gsd:complete-milestone
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `/gsd:milestone-summary`
|
||||
|
||||
팀 온보딩 및 리뷰를 위해 마일스톤 아티팩트로부터 포괄적인 프로젝트 요약을 생성합니다.
|
||||
|
||||
| 인수 | 필수 여부 | 설명 |
|
||||
|------|----------|------|
|
||||
| `version` | 아니오 | 마일스톤 버전 (기본값: 현재/최신 마일스톤) |
|
||||
|
||||
**사전 조건:** 완료되었거나 진행 중인 마일스톤이 하나 이상 있어야 합니다.
|
||||
**생성 파일:** `.planning/reports/MILESTONE_SUMMARY-v{version}.md`
|
||||
|
||||
**요약 포함 내용.**
|
||||
- 개요, 아키텍처 결정사항, 페이즈별 분석
|
||||
- 핵심 결정사항 및 트레이드오프
|
||||
- 요구사항 충족 현황
|
||||
- 기술 부채 및 지연 항목
|
||||
- 신규 팀원을 위한 시작 가이드
|
||||
- 생성 후 대화형 Q&A 제공
|
||||
|
||||
```bash
|
||||
/gsd:milestone-summary # 현재 마일스톤 요약
|
||||
/gsd:milestone-summary v1.0 # 특정 마일스톤 요약
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `/gsd:new-milestone`
|
||||
|
||||
다음 버전 사이클을 시작합니다.
|
||||
|
||||
| 인수 | 필수 여부 | 설명 |
|
||||
|------|----------|------|
|
||||
| `name` | 아니오 | 마일스톤 이름 |
|
||||
| `--reset-phase-numbers` | 아니오 | 새 마일스톤을 Phase 1부터 시작하고 로드맵 작업 전에 기존 페이즈 디렉터리를 아카이브합니다 |
|
||||
|
||||
**사전 조건:** 이전 마일스톤이 완료되어 있어야 합니다.
|
||||
**생성 파일:** 업데이트된 `PROJECT.md`, 새 `REQUIREMENTS.md`, 새 `ROADMAP.md`
|
||||
|
||||
```bash
|
||||
/gsd:new-milestone # 대화형 모드
|
||||
/gsd:new-milestone "v2.0 Mobile" # 이름이 지정된 마일스톤
|
||||
/gsd:new-milestone --reset-phase-numbers "v2.0 Mobile" # 마일스톤 번호를 1부터 재시작
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 페이즈 관리 명령어
|
||||
|
||||
### `/gsd:add-phase`
|
||||
|
||||
로드맵에 새 페이즈를 추가합니다.
|
||||
|
||||
```bash
|
||||
/gsd:add-phase # 대화형 — 페이즈를 설명합니다
|
||||
```
|
||||
|
||||
### `/gsd:insert-phase`
|
||||
|
||||
소수점 번호 체계를 사용하여 페이즈 사이에 긴급 작업을 삽입합니다.
|
||||
|
||||
| 인수 | 필수 여부 | 설명 |
|
||||
|------|----------|------|
|
||||
| `N` | 아니오 | 이 페이즈 번호 다음에 삽입합니다 |
|
||||
|
||||
```bash
|
||||
/gsd:insert-phase 3 # 페이즈 3과 4 사이에 삽입 → 3.1 생성
|
||||
```
|
||||
|
||||
### `/gsd:remove-phase`
|
||||
|
||||
미래 페이즈를 제거하고 이후 페이즈 번호를 재정렬합니다.
|
||||
|
||||
| 인수 | 필수 여부 | 설명 |
|
||||
|------|----------|------|
|
||||
| `N` | 아니오 | 제거할 페이즈 번호 |
|
||||
|
||||
```bash
|
||||
/gsd:remove-phase 7 # 페이즈 7 제거, 8→7, 9→8 등으로 재번호
|
||||
```
|
||||
|
||||
### `/gsd:list-phase-assumptions`
|
||||
|
||||
계획 수립 전 Claude의 예상 접근 방식을 미리 확인합니다.
|
||||
|
||||
| 인수 | 필수 여부 | 설명 |
|
||||
|------|----------|------|
|
||||
| `N` | 아니오 | 페이즈 번호 |
|
||||
|
||||
```bash
|
||||
/gsd:list-phase-assumptions 2 # 페이즈 2 가정 사항 확인
|
||||
```
|
||||
|
||||
### `/gsd:plan-milestone-gaps`
|
||||
|
||||
마일스톤 감사에서 발견된 갭을 보완하는 페이즈를 생성합니다.
|
||||
|
||||
```bash
|
||||
/gsd:plan-milestone-gaps # 각 감사 갭에 대한 페이즈 생성
|
||||
```
|
||||
|
||||
### `/gsd:research-phase`
|
||||
|
||||
심층 에코시스템 조사만 수행합니다 (독립 실행 — 일반적으로 `/gsd:plan-phase`를 사용하세요).
|
||||
|
||||
| 인수 | 필수 여부 | 설명 |
|
||||
|------|----------|------|
|
||||
| `N` | 아니오 | 페이즈 번호 |
|
||||
|
||||
```bash
|
||||
/gsd:research-phase 4 # 페이즈 4 도메인 조사
|
||||
```
|
||||
|
||||
### `/gsd:validate-phase`
|
||||
|
||||
Nyquist 검증 갭을 소급하여 감사하고 보완합니다.
|
||||
|
||||
| 인수 | 필수 여부 | 설명 |
|
||||
|------|----------|------|
|
||||
| `N` | 아니오 | 페이즈 번호 |
|
||||
|
||||
```bash
|
||||
/gsd:validate-phase 2 # 페이즈 2 테스트 커버리지 감사
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 탐색 명령어
|
||||
|
||||
### `/gsd:progress`
|
||||
|
||||
상태와 다음 단계를 표시합니다.
|
||||
|
||||
```bash
|
||||
/gsd:progress # "지금 어디 있나? 다음은 무엇인가?"
|
||||
```
|
||||
|
||||
### `/gsd:resume-work`
|
||||
|
||||
마지막 세션의 전체 컨텍스트를 복원합니다.
|
||||
|
||||
```bash
|
||||
/gsd:resume-work # 컨텍스트 초기화 또는 새 세션 후 실행
|
||||
```
|
||||
|
||||
### `/gsd:pause-work`
|
||||
|
||||
페이즈 중간에 중단할 때 컨텍스트 핸드오프를 저장합니다.
|
||||
|
||||
```bash
|
||||
/gsd:pause-work # continue-here.md 생성
|
||||
```
|
||||
|
||||
### `/gsd:manager`
|
||||
|
||||
하나의 터미널에서 여러 페이즈를 관리하는 대화형 명령 센터입니다.
|
||||
|
||||
**사전 조건:** `.planning/ROADMAP.md`가 존재해야 합니다.
|
||||
**동작 방식.**
|
||||
- 시각적 상태 표시기가 포함된 모든 페이즈 대시보드
|
||||
- 의존성과 진행 상황에 따른 최적 다음 작업 추천
|
||||
- 작업 디스패치: discuss는 인라인으로 실행되고 plan/execute는 백그라운드 에이전트로 실행됩니다
|
||||
- 하나의 터미널에서 여러 페이즈를 병렬로 처리하는 파워 유저를 위해 설계되었습니다
|
||||
|
||||
```bash
|
||||
/gsd:manager # 명령 센터 대시보드 열기
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `/gsd:help`
|
||||
|
||||
모든 명령어와 사용 가이드를 표시합니다.
|
||||
|
||||
```bash
|
||||
/gsd:help # 빠른 레퍼런스
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 유틸리티 명령어
|
||||
|
||||
### `/gsd:quick`
|
||||
|
||||
GSD 보증을 갖춘 임시 작업을 실행합니다.
|
||||
|
||||
| 플래그 | 설명 |
|
||||
|--------|------|
|
||||
| `--full` | 계획 검사 (2회 반복) + 실행 후 검증 활성화 |
|
||||
| `--discuss` | 경량 사전 계획 토론 |
|
||||
| `--research` | 계획 전 집중 조사자 스폰 |
|
||||
|
||||
플래그는 조합하여 사용할 수 있습니다.
|
||||
|
||||
```bash
|
||||
/gsd:quick # 기본 빠른 작업
|
||||
/gsd:quick --discuss --research # 토론 + 조사 + 계획
|
||||
/gsd:quick --full # 계획 검사 및 검증 포함
|
||||
/gsd:quick --discuss --research --full # 모든 선택적 단계 포함
|
||||
```
|
||||
|
||||
### `/gsd:autonomous`
|
||||
|
||||
남은 모든 페이즈를 자율적으로 실행합니다.
|
||||
|
||||
| 플래그 | 설명 |
|
||||
|--------|------|
|
||||
| `--from N` | 특정 페이즈 번호부터 시작합니다 |
|
||||
|
||||
```bash
|
||||
/gsd:autonomous # 남은 모든 페이즈 실행
|
||||
/gsd:autonomous --from 3 # 페이즈 3부터 시작
|
||||
```
|
||||
|
||||
### `/gsd:do`
|
||||
|
||||
자유 형식 텍스트를 적절한 GSD 명령어로 라우팅합니다.
|
||||
|
||||
```bash
|
||||
/gsd:do # 원하는 작업을 설명합니다
|
||||
```
|
||||
|
||||
### `/gsd:note`
|
||||
|
||||
마찰 없는 아이디어 캡처 — 노트 추가, 목록 조회, 또는 노트를 할 일로 승격합니다.
|
||||
|
||||
| 인수 | 필수 여부 | 설명 |
|
||||
|------|----------|------|
|
||||
| `text` | 아니오 | 캡처할 노트 텍스트 (기본값: 추가 모드) |
|
||||
| `list` | 아니오 | 프로젝트 및 전역 범위의 모든 노트 목록 |
|
||||
| `promote N` | 아니오 | N번 노트를 구조화된 할 일로 변환 |
|
||||
|
||||
| 플래그 | 설명 |
|
||||
|--------|------|
|
||||
| `--global` | 노트 작업에 전역 범위 사용 |
|
||||
|
||||
```bash
|
||||
/gsd:note "Consider caching strategy for API responses"
|
||||
/gsd:note list
|
||||
/gsd:note promote 3
|
||||
```
|
||||
|
||||
### `/gsd:debug`
|
||||
|
||||
지속적인 상태를 유지하는 체계적인 디버깅을 수행합니다.
|
||||
|
||||
| 인수 | 필수 여부 | 설명 |
|
||||
|------|----------|------|
|
||||
| `description` | 아니오 | 버그 설명 |
|
||||
|
||||
```bash
|
||||
/gsd:debug "Login button not responding on mobile Safari"
|
||||
```
|
||||
|
||||
### `/gsd:add-todo`
|
||||
|
||||
나중을 위한 아이디어나 작업을 캡처합니다.
|
||||
|
||||
| 인수 | 필수 여부 | 설명 |
|
||||
|------|----------|------|
|
||||
| `description` | 아니오 | 할 일 설명 |
|
||||
|
||||
```bash
|
||||
/gsd:add-todo "Consider adding dark mode support"
|
||||
```
|
||||
|
||||
### `/gsd:check-todos`
|
||||
|
||||
보류 중인 할 일 목록을 표시하고 작업할 항목을 선택합니다.
|
||||
|
||||
```bash
|
||||
/gsd:check-todos
|
||||
```
|
||||
|
||||
### `/gsd:add-tests`
|
||||
|
||||
완료된 페이즈에 대한 테스트를 생성합니다.
|
||||
|
||||
| 인수 | 필수 여부 | 설명 |
|
||||
|------|----------|------|
|
||||
| `N` | 아니오 | 페이즈 번호 |
|
||||
|
||||
```bash
|
||||
/gsd:add-tests 2 # 페이즈 2 테스트 생성
|
||||
```
|
||||
|
||||
### `/gsd:stats`
|
||||
|
||||
프로젝트 통계를 표시합니다.
|
||||
|
||||
```bash
|
||||
/gsd:stats # 프로젝트 지표 대시보드
|
||||
```
|
||||
|
||||
### `/gsd:profile-user`
|
||||
|
||||
Claude Code 세션 분석을 통해 8개 차원(커뮤니케이션 스타일, 의사결정 패턴, 디버깅 접근 방식, UX 선호도, 벤더 선택, 불만 유발 요인, 학습 스타일, 설명 깊이)으로 개발자 행동 프로필을 생성합니다. Claude의 응답을 개인화하는 아티팩트를 생성합니다.
|
||||
|
||||
| 플래그 | 설명 |
|
||||
|--------|------|
|
||||
| `--questionnaire` | 세션 분석 대신 대화형 설문지를 사용합니다 |
|
||||
| `--refresh` | 세션을 재분석하고 프로필을 재생성합니다 |
|
||||
|
||||
**생성 아티팩트.**
|
||||
- `USER-PROFILE.md` — 전체 행동 프로필
|
||||
- `/gsd:dev-preferences` 명령어 — 모든 세션에서 선호도를 로드합니다
|
||||
- `CLAUDE.md` 프로필 섹션 — Claude Code에 의해 자동으로 인식됩니다
|
||||
|
||||
```bash
|
||||
/gsd:profile-user # 세션 분석 및 프로필 구축
|
||||
/gsd:profile-user --questionnaire # 대화형 설문지 대체 방법
|
||||
/gsd:profile-user --refresh # 새로운 분석으로 재생성
|
||||
```
|
||||
|
||||
### `/gsd:health`
|
||||
|
||||
`.planning/` 디렉터리의 무결성을 검사합니다.
|
||||
|
||||
| 플래그 | 설명 |
|
||||
|--------|------|
|
||||
| `--repair` | 복구 가능한 문제를 자동으로 수정합니다 |
|
||||
|
||||
```bash
|
||||
/gsd:health # 무결성 검사
|
||||
/gsd:health --repair # 검사 및 수정
|
||||
```
|
||||
|
||||
### `/gsd:cleanup`
|
||||
|
||||
완료된 마일스톤의 누적된 페이즈 디렉터리를 아카이브합니다.
|
||||
|
||||
```bash
|
||||
/gsd:cleanup
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 진단 명령어
|
||||
|
||||
### `/gsd:forensics`
|
||||
|
||||
실패하거나 멈춘 GSD 워크플로우에 대한 사후 조사를 수행합니다.
|
||||
|
||||
| 인수 | 필수 여부 | 설명 |
|
||||
|------|----------|------|
|
||||
| `description` | 아니오 | 문제 설명 (생략 시 프롬프트로 입력) |
|
||||
|
||||
**사전 조건:** `.planning/` 디렉터리가 존재해야 합니다.
|
||||
**생성 파일:** `.planning/forensics/report-{timestamp}.md`
|
||||
|
||||
**조사 항목.**
|
||||
- Git 히스토리 분석 (최근 커밋, 멈춤 패턴, 시간 간격)
|
||||
- 아티팩트 무결성 (완료된 페이즈에 대한 예상 파일)
|
||||
- STATE.md 이상 및 세션 히스토리
|
||||
- 커밋되지 않은 작업, 충돌, 방치된 변경사항
|
||||
- 최소 4가지 이상 유형 검사 (멈춤 루프, 누락된 아티팩트, 방치된 작업, 충돌/중단)
|
||||
- 실행 가능한 발견사항이 있으면 GitHub 이슈 생성 제안
|
||||
|
||||
```bash
|
||||
/gsd:forensics # 대화형 — 문제 입력 프롬프트
|
||||
/gsd:forensics "Phase 3 execution stalled" # 문제 설명과 함께 실행
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 워크스트림 관리
|
||||
|
||||
### `/gsd:workstreams`
|
||||
|
||||
마일스톤의 서로 다른 영역에 대한 동시 작업을 위한 병렬 워크스트림을 관리합니다.
|
||||
|
||||
**서브커맨드.**
|
||||
|
||||
| 서브커맨드 | 설명 |
|
||||
|------------|------|
|
||||
| `list` | 상태와 함께 모든 워크스트림 목록 (서브커맨드 없을 경우 기본값) |
|
||||
| `create <name>` | 새 워크스트림 생성 |
|
||||
| `status <name>` | 특정 워크스트림의 상세 상태 |
|
||||
| `switch <name>` | 활성 워크스트림 설정 |
|
||||
| `progress` | 모든 워크스트림의 진행 상황 요약 |
|
||||
| `complete <name>` | 완료된 워크스트림 아카이브 |
|
||||
| `resume <name>` | 워크스트림의 작업 재개 |
|
||||
|
||||
**사전 조건:** 활성 GSD 프로젝트
|
||||
**생성 파일:** `.planning/` 하위의 워크스트림 디렉터리, 워크스트림별 상태 추적
|
||||
|
||||
```bash
|
||||
/gsd:workstreams # 모든 워크스트림 목록
|
||||
/gsd:workstreams create backend-api # 새 워크스트림 생성
|
||||
/gsd:workstreams switch backend-api # 활성 워크스트림 설정
|
||||
/gsd:workstreams status backend-api # 상세 상태 확인
|
||||
/gsd:workstreams progress # 교차 워크스트림 진행 상황 개요
|
||||
/gsd:workstreams complete backend-api # 완료된 워크스트림 아카이브
|
||||
/gsd:workstreams resume backend-api # 워크스트림 작업 재개
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 설정 명령어
|
||||
|
||||
### `/gsd:settings`
|
||||
|
||||
워크플로우 토글 및 모델 프로필의 대화형 설정을 합니다.
|
||||
|
||||
```bash
|
||||
/gsd:settings # 대화형 설정
|
||||
```
|
||||
|
||||
### `/gsd:set-profile`
|
||||
|
||||
프로필을 빠르게 전환합니다.
|
||||
|
||||
| 인수 | 필수 여부 | 설명 |
|
||||
|------|----------|------|
|
||||
| `profile` | **예** | `quality`, `balanced`, `budget`, 또는 `inherit` |
|
||||
|
||||
```bash
|
||||
/gsd:set-profile budget # 예산 프로필로 전환
|
||||
/gsd:set-profile quality # 품질 프로필로 전환
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 브라운필드 명령어
|
||||
|
||||
### `/gsd:map-codebase`
|
||||
|
||||
병렬 매퍼 에이전트를 사용하여 기존 코드베이스를 분석합니다.
|
||||
|
||||
| 인수 | 필수 여부 | 설명 |
|
||||
|------|----------|------|
|
||||
| `area` | 아니오 | 특정 영역으로 매핑 범위를 제한합니다 |
|
||||
|
||||
```bash
|
||||
/gsd:map-codebase # 전체 코드베이스 분석
|
||||
/gsd:map-codebase auth # 인증 영역에 집중
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 업데이트 명령어
|
||||
|
||||
### `/gsd:update`
|
||||
|
||||
변경 로그 미리보기와 함께 GSD를 업데이트합니다.
|
||||
|
||||
```bash
|
||||
/gsd:update # 업데이트 확인 및 설치
|
||||
```
|
||||
|
||||
### `/gsd:reapply-patches`
|
||||
|
||||
GSD 업데이트 후 로컬 수정사항을 복원합니다.
|
||||
|
||||
```bash
|
||||
/gsd:reapply-patches # 로컬 변경사항 병합
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 빠른 인라인 명령어
|
||||
|
||||
### `/gsd:fast`
|
||||
|
||||
서브에이전트나 계획 오버헤드 없이 간단한 작업을 인라인으로 실행합니다. 오타 수정, 설정 변경, 소규모 리팩터링, 누락된 커밋에 적합합니다.
|
||||
|
||||
| 인수 | 필수 여부 | 설명 |
|
||||
|------|----------|------|
|
||||
| `task description` | 아니오 | 수행할 작업 (생략 시 프롬프트로 입력) |
|
||||
|
||||
**`/gsd:quick`의 대체가 아닙니다.** 조사, 다단계 계획 또는 검증이 필요한 작업에는 `/gsd:quick`을 사용하세요.
|
||||
|
||||
```bash
|
||||
/gsd:fast "fix typo in README"
|
||||
/gsd:fast "add .env to gitignore"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 코드 품질 명령어
|
||||
|
||||
### `/gsd:review`
|
||||
|
||||
외부 AI CLI를 통한 페이즈 계획의 교차 AI 동료 리뷰를 수행합니다.
|
||||
|
||||
| 인수 | 필수 여부 | 설명 |
|
||||
|------|----------|------|
|
||||
| `--phase N` | **예** | 리뷰할 페이즈 번호 |
|
||||
|
||||
| 플래그 | 설명 |
|
||||
|--------|------|
|
||||
| `--gemini` | Gemini CLI 리뷰 포함 |
|
||||
| `--claude` | Claude CLI 리뷰 포함 (별도 세션) |
|
||||
| `--codex` | Codex CLI 리뷰 포함 |
|
||||
| `--all` | 사용 가능한 모든 CLI 포함 |
|
||||
|
||||
**생성 파일:** `{phase}-REVIEWS.md` — `/gsd:plan-phase --reviews`에서 사용 가능
|
||||
|
||||
```bash
|
||||
/gsd:review --phase 3 --all
|
||||
/gsd:review --phase 2 --gemini
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `/gsd:pr-branch`
|
||||
|
||||
`.planning/` 커밋을 필터링한 깔끔한 PR 브랜치를 생성합니다.
|
||||
|
||||
| 인수 | 필수 여부 | 설명 |
|
||||
|------|----------|------|
|
||||
| `target branch` | 아니오 | 기본 브랜치 (기본값: `main`) |
|
||||
|
||||
**목적:** 리뷰어에게 GSD 계획 아티팩트가 아닌 코드 변경사항만 표시합니다.
|
||||
|
||||
```bash
|
||||
/gsd:pr-branch # main을 기준으로 필터링
|
||||
/gsd:pr-branch develop # develop을 기준으로 필터링
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `/gsd:audit-uat`
|
||||
|
||||
모든 미완료 UAT 및 검증 항목에 대한 교차 페이즈 감사를 수행합니다.
|
||||
|
||||
**사전 조건:** UAT 또는 검증이 포함된 페이즈가 하나 이상 실행되어 있어야 합니다.
|
||||
**생성 파일:** 사람이 직접 수행하는 테스트 계획이 포함된 분류된 감사 보고서
|
||||
|
||||
```bash
|
||||
/gsd:audit-uat
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 백로그 및 스레드 명령어
|
||||
|
||||
### `/gsd:add-backlog`
|
||||
|
||||
999.x 번호 체계를 사용하여 백로그 파킹 롯에 아이디어를 추가합니다.
|
||||
|
||||
| 인수 | 필수 여부 | 설명 |
|
||||
|------|----------|------|
|
||||
| `description` | **예** | 백로그 항목 설명 |
|
||||
|
||||
**999.x 번호 체계**는 백로그 항목을 활성 페이즈 순서 밖에 유지합니다. 페이즈 디렉터리가 즉시 생성되므로 해당 항목에 대해 `/gsd:discuss-phase`와 `/gsd:plan-phase`를 사용할 수 있습니다.
|
||||
|
||||
```bash
|
||||
/gsd:add-backlog "GraphQL API layer"
|
||||
/gsd:add-backlog "Mobile responsive redesign"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `/gsd:review-backlog`
|
||||
|
||||
백로그 항목을 검토하고 활성 마일스톤으로 승격합니다.
|
||||
|
||||
**항목별 작업:** 승격 (활성 순서로 이동), 유지 (백로그에 남김), 제거 (삭제).
|
||||
|
||||
```bash
|
||||
/gsd:review-backlog
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `/gsd:plant-seed`
|
||||
|
||||
트리거 조건이 있는 미래 지향적인 아이디어를 캡처합니다. 적절한 마일스톤 시점에 자동으로 표면화됩니다.
|
||||
|
||||
| 인수 | 필수 여부 | 설명 |
|
||||
|------|----------|------|
|
||||
| `idea summary` | 아니오 | 시드 설명 (생략 시 프롬프트로 입력) |
|
||||
|
||||
시드는 컨텍스트 부식 문제를 해결합니다. 아무도 읽지 않는 Deferred의 한 줄짜리 메모 대신, 시드는 전체 WHY, 언제 표면화할지, 세부 내용에 대한 단서를 보존합니다.
|
||||
|
||||
**생성 파일:** `.planning/seeds/SEED-NNN-slug.md`
|
||||
**사용처:** `/gsd:new-milestone` (시드를 스캔하여 일치 항목 제시)
|
||||
|
||||
```bash
|
||||
/gsd:plant-seed "Add real-time collaboration when WebSocket infra is in place"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `/gsd:thread`
|
||||
|
||||
교차 세션 작업을 위한 지속적인 컨텍스트 스레드를 관리합니다.
|
||||
|
||||
| 인수 | 필수 여부 | 설명 |
|
||||
|------|----------|------|
|
||||
| (없음) | — | 모든 스레드 목록 |
|
||||
| `name` | — | 이름으로 기존 스레드 재개 |
|
||||
| `description` | — | 새 스레드 생성 |
|
||||
|
||||
스레드는 여러 세션에 걸쳐 이어지지만 특정 페이즈에 속하지 않는 작업을 위한 경량 교차 세션 지식 저장소입니다. `/gsd:pause-work`보다 가볍습니다.
|
||||
|
||||
```bash
|
||||
/gsd:thread # 모든 스레드 목록
|
||||
/gsd:thread fix-deploy-key-auth # 스레드 재개
|
||||
/gsd:thread "Investigate TCP timeout in pasta service" # 새 스레드 생성
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 커뮤니티 명령어
|
||||
|
||||
### `/gsd:join-discord`
|
||||
|
||||
Discord 커뮤니티 초대 링크를 엽니다.
|
||||
|
||||
```bash
|
||||
/gsd:join-discord
|
||||
```
|
||||
342
docs/ko-KR/CONFIGURATION.md
Normal file
342
docs/ko-KR/CONFIGURATION.md
Normal file
@@ -0,0 +1,342 @@
|
||||
# GSD 설정 레퍼런스
|
||||
|
||||
> 전체 설정 스키마, 워크플로우 토글, 모델 프로필, git 브랜칭 옵션입니다. 기능에 대한 맥락은 [Feature Reference](FEATURES.md)를 참조하세요.
|
||||
|
||||
---
|
||||
|
||||
## 설정 파일
|
||||
|
||||
GSD는 프로젝트 설정을 `.planning/config.json`에 저장합니다. `/gsd:new-project` 실행 시 생성되며 `/gsd:settings`를 통해 업데이트할 수 있습니다.
|
||||
|
||||
### 전체 스키마
|
||||
|
||||
```json
|
||||
{
|
||||
"mode": "interactive",
|
||||
"granularity": "standard",
|
||||
"model_profile": "balanced",
|
||||
"model_overrides": {},
|
||||
"planning": {
|
||||
"commit_docs": true,
|
||||
"search_gitignored": false
|
||||
},
|
||||
"workflow": {
|
||||
"research": true,
|
||||
"plan_check": true,
|
||||
"verifier": true,
|
||||
"auto_advance": false,
|
||||
"nyquist_validation": true,
|
||||
"ui_phase": true,
|
||||
"ui_safety_gate": true,
|
||||
"node_repair": true,
|
||||
"node_repair_budget": 2,
|
||||
"research_before_questions": false,
|
||||
"discuss_mode": "discuss",
|
||||
"skip_discuss": false,
|
||||
"text_mode": false
|
||||
},
|
||||
"hooks": {
|
||||
"context_warnings": true,
|
||||
"workflow_guard": false
|
||||
},
|
||||
"parallelization": {
|
||||
"enabled": true,
|
||||
"plan_level": true,
|
||||
"task_level": false,
|
||||
"skip_checkpoints": true,
|
||||
"max_concurrent_agents": 3,
|
||||
"min_plans_for_parallel": 2
|
||||
},
|
||||
"git": {
|
||||
"branching_strategy": "none",
|
||||
"phase_branch_template": "gsd/phase-{phase}-{slug}",
|
||||
"milestone_branch_template": "gsd/{milestone}-{slug}",
|
||||
"quick_branch_template": null
|
||||
},
|
||||
"gates": {
|
||||
"confirm_project": true,
|
||||
"confirm_phases": true,
|
||||
"confirm_roadmap": true,
|
||||
"confirm_breakdown": true,
|
||||
"confirm_plan": true,
|
||||
"execute_next_plan": true,
|
||||
"issues_review": true,
|
||||
"confirm_transition": true
|
||||
},
|
||||
"safety": {
|
||||
"always_confirm_destructive": true,
|
||||
"always_confirm_external_services": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 핵심 설정
|
||||
|
||||
| 설정 | 타입 | 옵션 | 기본값 | 설명 |
|
||||
|------|------|------|--------|------|
|
||||
| `mode` | enum | `interactive`, `yolo` | `interactive` | `yolo`는 결정을 자동 승인하고 `interactive`는 각 단계에서 확인을 요청합니다. |
|
||||
| `granularity` | enum | `coarse`, `standard`, `fine` | `standard` | 단계 수를 조절합니다. `coarse` (3~5), `standard` (5~8), `fine` (8~12) |
|
||||
| `model_profile` | enum | `quality`, `balanced`, `budget`, `inherit` | `balanced` | 각 에이전트의 모델 티어입니다. ([Model Profiles](#model-profiles) 참조) |
|
||||
|
||||
> **참고:** `granularity`는 v1.22.3에서 `depth`에서 이름이 변경되었습니다. 기존 설정은 자동으로 마이그레이션됩니다.
|
||||
|
||||
---
|
||||
|
||||
## 워크플로우 토글
|
||||
|
||||
모든 워크플로우 토글은 **키가 없으면 활성화** 패턴을 따릅니다. 설정에서 키가 없으면 기본값은 `true`입니다.
|
||||
|
||||
| 설정 | 타입 | 기본값 | 설명 |
|
||||
|------|------|--------|------|
|
||||
| `workflow.research` | boolean | `true` | 각 단계 플래닝 전 도메인 조사 |
|
||||
| `workflow.plan_check` | boolean | `true` | 플랜 검증 루프 (최대 3회 반복) |
|
||||
| `workflow.verifier` | boolean | `true` | 실행 후 단계 목표 대비 검증 |
|
||||
| `workflow.auto_advance` | boolean | `false` | discuss → plan → execute를 중단 없이 자동으로 연결 |
|
||||
| `workflow.nyquist_validation` | boolean | `true` | plan 단계 리서치 중 테스트 커버리지 매핑 |
|
||||
| `workflow.ui_phase` | boolean | `true` | 프론트엔드 단계를 위한 UI 디자인 계약서 생성 |
|
||||
| `workflow.ui_safety_gate` | boolean | `true` | plan 단계에서 프론트엔드 단계에 대해 /gsd:ui-phase 실행 여부 확인 |
|
||||
| `workflow.node_repair` | boolean | `true` | 검증 실패 시 자율적 태스크 복구 |
|
||||
| `workflow.node_repair_budget` | number | `2` | 실패한 태스크당 최대 복구 시도 횟수 |
|
||||
| `workflow.research_before_questions` | boolean | `false` | 토론 질문 후가 아닌 전에 리서치 실행 |
|
||||
| `workflow.discuss_mode` | string | `'discuss'` | `/gsd:discuss-phase`의 컨텍스트 수집 방식을 제어합니다. `'discuss'` (기본값)는 질문을 하나씩 합니다. `'assumptions'`는 코드베이스를 먼저 읽고 신뢰도 수준이 있는 구조화된 가정을 생성하여 틀린 부분만 수정하도록 요청합니다. v1.28에서 추가 |
|
||||
| `workflow.skip_discuss` | boolean | `false` | `true`로 설정하면 `/gsd:autonomous`가 discuss 단계를 완전히 건너뛰고 ROADMAP 단계 목표로부터 최소한의 CONTEXT.md를 작성합니다. 개발자 선호사항이 PROJECT.md/REQUIREMENTS.md에 모두 캡처된 프로젝트에 유용합니다. v1.28에서 추가 |
|
||||
| `workflow.text_mode` | boolean | `false` | AskUserQuestion TUI 메뉴를 일반 텍스트 번호 목록으로 대체합니다. TUI 메뉴가 렌더링되지 않는 Claude Code 원격 세션 (`/rc` 모드)에 필요합니다. discuss 단계에서 `--text` 플래그로 세션별 설정도 가능합니다. v1.28에서 추가 |
|
||||
|
||||
### 권장 프리셋
|
||||
|
||||
| 시나리오 | mode | granularity | profile | research | plan_check | verifier |
|
||||
|---------|------|-------------|---------|----------|------------|----------|
|
||||
| 프로토타이핑 | `yolo` | `coarse` | `budget` | `false` | `false` | `false` |
|
||||
| 일반 개발 | `interactive` | `standard` | `balanced` | `true` | `true` | `true` |
|
||||
| 프로덕션 릴리스 | `interactive` | `fine` | `quality` | `true` | `true` | `true` |
|
||||
|
||||
---
|
||||
|
||||
## 플래닝 설정
|
||||
|
||||
| 설정 | 타입 | 기본값 | 설명 |
|
||||
|------|------|--------|------|
|
||||
| `planning.commit_docs` | boolean | `true` | `.planning/` 파일을 git에 커밋할지 여부 |
|
||||
| `planning.search_gitignored` | boolean | `false` | 광범위한 검색에 `--no-ignore`를 추가하여 `.planning/`을 포함 |
|
||||
|
||||
### 자동 감지
|
||||
|
||||
`.planning/`이 `.gitignore`에 포함되어 있으면 config.json 설정과 무관하게 `commit_docs`가 자동으로 `false`로 설정됩니다. 이는 git 오류를 방지합니다.
|
||||
|
||||
---
|
||||
|
||||
## 훅 설정
|
||||
|
||||
| 설정 | 타입 | 기본값 | 설명 |
|
||||
|------|------|--------|------|
|
||||
| `hooks.context_warnings` | boolean | `true` | context monitor 훅을 통해 컨텍스트 윈도우 사용 경고 표시 |
|
||||
| `hooks.workflow_guard` | boolean | `false` | GSD 워크플로우 컨텍스트 밖에서 파일 편집이 발생할 때 경고 ((`/gsd:quick` 또는 `/gsd:fast` 사용 권고)) |
|
||||
|
||||
프롬프트 주입 방지 훅 (`gsd-prompt-guard.js`)은 항상 활성화되며 비활성화할 수 없습니다. 워크플로우 토글이 아닌 보안 기능입니다.
|
||||
|
||||
### 플래닝 비공개 설정
|
||||
|
||||
플래닝 아티팩트를 git에서 제외하려면 다음과 같이 설정합니다.
|
||||
|
||||
1. `planning.commit_docs: false` 및 `planning.search_gitignored: true` 설정
|
||||
2. `.planning/`을 `.gitignore`에 추가
|
||||
3. 이미 추적 중인 경우: `git rm -r --cached .planning/ && git commit -m "chore: stop tracking planning docs"`
|
||||
|
||||
---
|
||||
|
||||
## 병렬화 설정
|
||||
|
||||
| 설정 | 타입 | 기본값 | 설명 |
|
||||
|------|------|--------|------|
|
||||
| `parallelization.enabled` | boolean | `true` | 독립적인 플랜을 동시에 실행 |
|
||||
| `parallelization.plan_level` | boolean | `true` | 플랜 수준에서 병렬화 |
|
||||
| `parallelization.task_level` | boolean | `false` | 플랜 내 태스크를 병렬화 |
|
||||
| `parallelization.skip_checkpoints` | boolean | `true` | 병렬 실행 중 체크포인트 건너뜀 |
|
||||
| `parallelization.max_concurrent_agents` | number | `3` | 동시 실행 가능한 최대 에이전트 수 |
|
||||
| `parallelization.min_plans_for_parallel` | number | `2` | 병렬 실행을 시작하기 위한 최소 플랜 수 |
|
||||
|
||||
> **Pre-commit 훅과 병렬 실행:** 병렬화가 활성화되면 executor 에이전트는 빌드 잠금 경합(예: Rust 프로젝트의 cargo lock 충돌)을 피하기 위해 `--no-verify`로 커밋합니다. 오케스트레이터는 각 wave가 완료된 후 훅을 한 번 검증합니다. STATE.md 쓰기는 동시 쓰기 충돌을 방지하기 위해 파일 수준 잠금으로 보호됩니다. 커밋마다 훅을 실행해야 한다면 `parallelization.enabled: false`로 설정하세요.
|
||||
|
||||
---
|
||||
|
||||
## Git 브랜칭
|
||||
|
||||
| 설정 | 타입 | 기본값 | 설명 |
|
||||
|------|------|--------|------|
|
||||
| `git.branching_strategy` | enum | `none` | `none`, `phase`, 또는 `milestone` |
|
||||
| `git.phase_branch_template` | string | `gsd/phase-{phase}-{slug}` | phase 전략의 브랜치 이름 템플릿 |
|
||||
| `git.milestone_branch_template` | string | `gsd/{milestone}-{slug}` | milestone 전략의 브랜치 이름 템플릿 |
|
||||
| `git.quick_branch_template` | string 또는 null | `null` | `/gsd:quick` 태스크를 위한 선택적 브랜치 이름 템플릿 |
|
||||
|
||||
### 전략 비교
|
||||
|
||||
| 전략 | 브랜치 생성 | 범위 | 병합 시점 | 적합한 경우 |
|
||||
|------|------------|------|----------|------------|
|
||||
| `none` | 없음 | 해당 없음 | 해당 없음 | 개인 개발, 단순 프로젝트 |
|
||||
| `phase` | `execute-phase` 시작 시 | 단일 단계 | 단계 완료 후 사용자가 병합 | 단계별 코드 리뷰, 세밀한 롤백 |
|
||||
| `milestone` | 첫 번째 `execute-phase` 시 | milestone 내 모든 단계 | `complete-milestone` 시 | 릴리스 브랜치, 버전별 PR |
|
||||
|
||||
### 템플릿 변수
|
||||
|
||||
| 변수 | 사용 가능한 템플릿 | 예시 |
|
||||
|------|------------------|------|
|
||||
| `{phase}` | `phase_branch_template` | `03` (0 패딩) |
|
||||
| `{slug}` | 두 템플릿 모두 | `user-authentication` (소문자, 하이픈) |
|
||||
| `{milestone}` | `milestone_branch_template` | `v1.0` |
|
||||
| `{num}` / `{quick}` | `quick_branch_template` | `260317-abc` (quick 태스크 ID) |
|
||||
|
||||
quick 태스크 브랜칭 예시:
|
||||
|
||||
```json
|
||||
"git": {
|
||||
"quick_branch_template": "gsd/quick-{num}-{slug}"
|
||||
}
|
||||
```
|
||||
|
||||
### Milestone 완료 시 병합 옵션
|
||||
|
||||
| 옵션 | Git 명령어 | 결과 |
|
||||
|------|-----------|------|
|
||||
| Squash merge (권장) | `git merge --squash` | 브랜치당 단일 클린 커밋 |
|
||||
| Merge with history | `git merge --no-ff` | 모든 개별 커밋 보존 |
|
||||
| Delete without merging | `git branch -D` | 브랜치 작업 폐기 |
|
||||
| Keep branches | (없음) | 나중에 수동으로 처리 |
|
||||
|
||||
---
|
||||
|
||||
## Gate 설정
|
||||
|
||||
워크플로우 중 확인 프롬프트를 제어합니다.
|
||||
|
||||
| 설정 | 타입 | 기본값 | 설명 |
|
||||
|------|------|--------|------|
|
||||
| `gates.confirm_project` | boolean | `true` | 확정 전 프로젝트 세부사항 확인 |
|
||||
| `gates.confirm_phases` | boolean | `true` | 단계 분류 확인 |
|
||||
| `gates.confirm_roadmap` | boolean | `true` | 진행 전 로드맵 확인 |
|
||||
| `gates.confirm_breakdown` | boolean | `true` | 태스크 분류 확인 |
|
||||
| `gates.confirm_plan` | boolean | `true` | 실행 전 각 플랜 확인 |
|
||||
| `gates.execute_next_plan` | boolean | `true` | 다음 플랜 실행 전 확인 |
|
||||
| `gates.issues_review` | boolean | `true` | 수정 플랜 생성 전 이슈 검토 |
|
||||
| `gates.confirm_transition` | boolean | `true` | 단계 전환 확인 |
|
||||
|
||||
---
|
||||
|
||||
## 안전성 설정
|
||||
|
||||
| 설정 | 타입 | 기본값 | 설명 |
|
||||
|------|------|--------|------|
|
||||
| `safety.always_confirm_destructive` | boolean | `true` | 파괴적 작업(삭제, 덮어쓰기) 확인 |
|
||||
| `safety.always_confirm_external_services` | boolean | `true` | 외부 서비스 상호작용 확인 |
|
||||
|
||||
---
|
||||
|
||||
## 훅 설정
|
||||
|
||||
| 설정 | 타입 | 기본값 | 설명 |
|
||||
|------|------|--------|------|
|
||||
| `hooks.context_warnings` | boolean | `true` | 세션 중 컨텍스트 윈도우 사용 경고 표시 |
|
||||
|
||||
---
|
||||
|
||||
## 모델 프로필
|
||||
|
||||
### 프로필 정의
|
||||
|
||||
| 에이전트 | `quality` | `balanced` | `budget` | `inherit` |
|
||||
|---------|-----------|------------|----------|-----------|
|
||||
| gsd-planner | Opus | Opus | Sonnet | Inherit |
|
||||
| gsd-roadmapper | Opus | Sonnet | Sonnet | Inherit |
|
||||
| gsd-executor | Opus | Sonnet | Sonnet | Inherit |
|
||||
| gsd-phase-researcher | Opus | Sonnet | Haiku | Inherit |
|
||||
| gsd-project-researcher | Opus | Sonnet | Haiku | Inherit |
|
||||
| gsd-research-synthesizer | Sonnet | Sonnet | Haiku | Inherit |
|
||||
| gsd-debugger | Opus | Sonnet | Sonnet | Inherit |
|
||||
| gsd-codebase-mapper | Sonnet | Haiku | Haiku | Inherit |
|
||||
| gsd-verifier | Sonnet | Sonnet | Haiku | Inherit |
|
||||
| gsd-plan-checker | Sonnet | Sonnet | Haiku | Inherit |
|
||||
| gsd-integration-checker | Sonnet | Sonnet | Haiku | Inherit |
|
||||
| gsd-nyquist-auditor | Sonnet | Sonnet | Haiku | Inherit |
|
||||
|
||||
### 에이전트별 재정의
|
||||
|
||||
전체 프로필을 변경하지 않고 특정 에이전트만 재정의할 수 있습니다.
|
||||
|
||||
```json
|
||||
{
|
||||
"model_profile": "balanced",
|
||||
"model_overrides": {
|
||||
"gsd-executor": "opus",
|
||||
"gsd-planner": "haiku"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
유효한 재정의 값: `opus`, `sonnet`, `haiku`, `inherit`, 또는 완전히 정규화된 모델 ID (예: `"openai/o3"`, `"google/gemini-2.5-pro"`).
|
||||
|
||||
### 비 Claude 런타임 (Codex, OpenCode, Gemini CLI)
|
||||
|
||||
비 Claude 런타임에 GSD를 설치하면 인스톨러가 자동으로 `~/.gsd/defaults.json`에 `resolve_model_ids: "omit"`을 설정합니다. 이로 인해 GSD는 모든 에이전트에 빈 model 파라미터를 반환하며 각 에이전트는 런타임에 설정된 모델을 사용합니다. 기본 사용 시 추가 설정은 필요하지 않습니다.
|
||||
|
||||
에이전트마다 다른 모델을 사용하려면 런타임이 인식하는 완전히 정규화된 모델 ID로 `model_overrides`를 사용합니다.
|
||||
|
||||
```json
|
||||
{
|
||||
"resolve_model_ids": "omit",
|
||||
"model_overrides": {
|
||||
"gsd-planner": "o3",
|
||||
"gsd-executor": "o4-mini",
|
||||
"gsd-debugger": "o3",
|
||||
"gsd-codebase-mapper": "o4-mini"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
의도는 Claude 프로필 티어와 동일합니다. 추론 품질이 가장 중요한 플래닝과 디버깅에는 더 강력한 모델을 사용하고 플랜에 추론이 이미 포함된 실행과 매핑에는 저렴한 모델을 사용합니다.
|
||||
|
||||
**접근 방식 선택 기준.**
|
||||
|
||||
| 시나리오 | 설정 | 효과 |
|
||||
|---------|------|------|
|
||||
| 비 Claude 런타임, 단일 모델 | `resolve_model_ids: "omit"` (인스톨러 기본값) | 모든 에이전트가 런타임 기본 모델 사용 |
|
||||
| 비 Claude 런타임, 계층형 모델 | `resolve_model_ids: "omit"` + `model_overrides` | 지정된 에이전트는 특정 모델 사용, 나머지는 런타임 기본값 사용 |
|
||||
| Claude Code + OpenRouter/로컬 프로바이더 | `model_profile: "inherit"` | 모든 에이전트가 세션 모델을 따름 |
|
||||
| Claude Code + OpenRouter, 계층형 | `model_profile: "inherit"` + `model_overrides` | 지정된 에이전트는 특정 모델 사용, 나머지는 상속 |
|
||||
|
||||
**`resolve_model_ids` 값.**
|
||||
|
||||
| 값 | 동작 | 사용 시점 |
|
||||
|----|------|----------|
|
||||
| `false` (기본값) | Claude 별칭 반환 (`opus`, `sonnet`, `haiku`) | 네이티브 Anthropic API를 사용하는 Claude Code |
|
||||
| `true` | 별칭을 전체 Claude 모델 ID로 매핑 (`claude-opus-4-0`) | 전체 ID가 필요한 API를 사용하는 Claude Code |
|
||||
| `"omit"` | 빈 문자열 반환 (런타임이 기본값 선택) | 비 Claude 런타임 (Codex, OpenCode, Gemini CLI) |
|
||||
|
||||
### 프로필 철학
|
||||
|
||||
| 프로필 | 철학 | 사용 시점 |
|
||||
|--------|------|----------|
|
||||
| `quality` | 모든 의사결정에 Opus, 검증에 Sonnet | 할당량 여유가 있을 때, 중요한 아키텍처 작업 |
|
||||
| `balanced` | 플래닝에만 Opus, 나머지는 Sonnet | 일반 개발 (기본값) |
|
||||
| `budget` | 코드 작성에 Sonnet, 리서치/검증에 Haiku | 대용량 작업, 덜 중요한 단계 |
|
||||
| `inherit` | 모든 에이전트가 현재 세션 모델 사용 | 동적 모델 전환, **비 Anthropic 프로바이더** (OpenRouter, 로컬 모델) |
|
||||
|
||||
---
|
||||
|
||||
## 환경 변수
|
||||
|
||||
| 변수 | 용도 |
|
||||
|------|------|
|
||||
| `CLAUDE_CONFIG_DIR` | 기본 설정 디렉토리 재정의 (`~/.claude/`) |
|
||||
| `GEMINI_API_KEY` | context monitor가 훅 이벤트 이름을 전환하기 위해 감지 |
|
||||
| `WSL_DISTRO_NAME` | 인스톨러가 WSL 경로 처리를 위해 감지 |
|
||||
|
||||
---
|
||||
|
||||
## 전역 기본값
|
||||
|
||||
향후 프로젝트를 위한 전역 기본값으로 설정을 저장할 수 있습니다.
|
||||
|
||||
**위치:** `~/.gsd/defaults.json`
|
||||
|
||||
`/gsd:new-project`가 새 `config.json`을 생성할 때 전역 기본값을 읽어 초기 설정으로 병합합니다. 프로젝트별 설정은 항상 전역 설정보다 우선합니다.
|
||||
1290
docs/ko-KR/FEATURES.md
Normal file
1290
docs/ko-KR/FEATURES.md
Normal file
File diff suppressed because it is too large
Load Diff
29
docs/ko-KR/README.md
Normal file
29
docs/ko-KR/README.md
Normal file
@@ -0,0 +1,29 @@
|
||||
# GSD 문서
|
||||
|
||||
Get Shit Done (GSD) 프레임워크의 종합 문서입니다. GSD는 AI 코딩 에이전트를 위한 메타 프롬프팅, 컨텍스트 엔지니어링, 스펙 기반 개발 시스템입니다.
|
||||
|
||||
언어 버전: [English](README.md) · [Português (pt-BR)](pt-BR/README.md) · [日本語](ja-JP/README.md) · [简体中文](zh-CN/README.md) · [한국어](ko-KR/README.md)
|
||||
|
||||
## 문서 목차
|
||||
|
||||
| 문서 | 대상 독자 | 설명 |
|
||||
|------|-----------|------|
|
||||
| [Architecture](ARCHITECTURE.md) | 기여자, 고급 사용자 | 시스템 아키텍처, 에이전트 모델, 데이터 흐름, 내부 설계 |
|
||||
| [Feature Reference](FEATURES.md) | 전체 사용자 | 요구사항이 포함된 전체 기능 및 함수 문서 |
|
||||
| [Command Reference](COMMANDS.md) | 전체 사용자 | 모든 명령어의 구문, 플래그, 옵션 및 예제 |
|
||||
| [Configuration Reference](CONFIGURATION.md) | 전체 사용자 | 전체 설정 스키마, 워크플로우 토글, 모델 프로필, git 브랜칭 |
|
||||
| [CLI Tools Reference](CLI-TOOLS.md) | 기여자, 에이전트 작성자 | 워크플로우 및 에이전트를 위한 `gsd-tools.cjs` 프로그래매틱 API |
|
||||
| [Agent Reference](AGENTS.md) | 기여자, 고급 사용자 | 15개 전문 에이전트의 역할, 도구, 스폰 패턴 |
|
||||
| [User Guide](USER-GUIDE.md) | 전체 사용자 | 워크플로우 안내, 문제 해결, 복구 방법 |
|
||||
| [Context Monitor](context-monitor.md) | 전체 사용자 | 컨텍스트 윈도우 모니터링 훅 아키텍처 |
|
||||
| [Discuss Mode](workflow-discuss-mode.md) | 전체 사용자 | discuss 단계의 assumptions 모드와 interview 모드 |
|
||||
|
||||
## 빠른 링크
|
||||
|
||||
- **v1.28의 새로운 기능:** Forensics, milestone 요약, workstream, assumptions 모드, UI 자동 감지, manager 대시보드
|
||||
- **시작하기:** [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)
|
||||
842
docs/ko-KR/USER-GUIDE.md
Normal file
842
docs/ko-KR/USER-GUIDE.md
Normal file
@@ -0,0 +1,842 @@
|
||||
# GSD 사용자 가이드
|
||||
|
||||
워크플로우, 문제 해결, 설정에 대한 상세 레퍼런스입니다. 빠른 시작 설정은 [README](../README.md)를 참고하세요.
|
||||
|
||||
---
|
||||
|
||||
## 목차
|
||||
|
||||
- [워크플로우 다이어그램](#워크플로우-다이어그램)
|
||||
- [UI 설계 계약](#ui-설계-계약)
|
||||
- [백로그 및 스레드](#백로그-및-스레드)
|
||||
- [워크스트림](#워크스트림)
|
||||
- [보안](#보안)
|
||||
- [명령어 레퍼런스](#명령어-레퍼런스)
|
||||
- [설정 레퍼런스](#설정-레퍼런스)
|
||||
- [사용 예시](#사용-예시)
|
||||
- [문제 해결](#문제-해결)
|
||||
- [복구 빠른 레퍼런스](#복구-빠른-레퍼런스)
|
||||
|
||||
---
|
||||
|
||||
## 워크플로우 다이어그램
|
||||
|
||||
### 전체 프로젝트 생명주기
|
||||
|
||||
```
|
||||
┌──────────────────────────────────────────────────┐
|
||||
│ NEW PROJECT │
|
||||
│ /gsd:new-project │
|
||||
│ Questions -> Research -> Requirements -> Roadmap│
|
||||
└─────────────────────────┬────────────────────────┘
|
||||
│
|
||||
┌──────────────▼─────────────┐
|
||||
│ FOR EACH PHASE: │
|
||||
│ │
|
||||
│ ┌────────────────────┐ │
|
||||
│ │ /gsd:discuss-phase │ │ <- Lock in preferences
|
||||
│ └──────────┬─────────┘ │
|
||||
│ │ │
|
||||
│ ┌──────────▼─────────┐ │
|
||||
│ │ /gsd:ui-phase │ │ <- Design contract (frontend)
|
||||
│ └──────────┬─────────┘ │
|
||||
│ │ │
|
||||
│ ┌──────────▼─────────┐ │
|
||||
│ │ /gsd:plan-phase │ │ <- Research + Plan + Verify
|
||||
│ └──────────┬─────────┘ │
|
||||
│ │ │
|
||||
│ ┌──────────▼─────────┐ │
|
||||
│ │ /gsd:execute-phase │ │ <- Parallel execution
|
||||
│ └──────────┬─────────┘ │
|
||||
│ │ │
|
||||
│ ┌──────────▼─────────┐ │
|
||||
│ │ /gsd:verify-work │ │ <- Manual UAT
|
||||
│ └──────────┬─────────┘ │
|
||||
│ │ │
|
||||
│ ┌──────────▼─────────┐ │
|
||||
│ │ /gsd:ship │ │ <- Create PR (optional)
|
||||
│ └──────────┬─────────┘ │
|
||||
│ │ │
|
||||
│ Next Phase?────────────┘
|
||||
│ │ No
|
||||
└─────────────┼──────────────┘
|
||||
│
|
||||
┌───────────────▼──────────────┐
|
||||
│ /gsd:audit-milestone │
|
||||
│ /gsd:complete-milestone │
|
||||
└───────────────┬──────────────┘
|
||||
│
|
||||
Another milestone?
|
||||
│ │
|
||||
Yes No -> Done!
|
||||
│
|
||||
┌───────▼──────────────┐
|
||||
│ /gsd:new-milestone │
|
||||
└──────────────────────┘
|
||||
```
|
||||
|
||||
### 계획 에이전트 조정
|
||||
|
||||
```
|
||||
/gsd:plan-phase N
|
||||
│
|
||||
├── Phase Researcher (x4 parallel)
|
||||
│ ├── Stack researcher
|
||||
│ ├── Features researcher
|
||||
│ ├── Architecture researcher
|
||||
│ └── Pitfalls researcher
|
||||
│ │
|
||||
│ ┌──────▼──────┐
|
||||
│ │ RESEARCH.md │
|
||||
│ └──────┬──────┘
|
||||
│ │
|
||||
│ ┌──────▼──────┐
|
||||
│ │ Planner │ <- Reads PROJECT.md, REQUIREMENTS.md,
|
||||
│ │ │ CONTEXT.md, RESEARCH.md
|
||||
│ └──────┬──────┘
|
||||
│ │
|
||||
│ ┌──────▼───────────┐ ┌────────┐
|
||||
│ │ Plan Checker │────>│ PASS? │
|
||||
│ └──────────────────┘ └───┬────┘
|
||||
│ │
|
||||
│ Yes │ No
|
||||
│ │ │ │
|
||||
│ │ └───┘ (loop, up to 3x)
|
||||
│ │
|
||||
│ ┌─────▼──────┐
|
||||
│ │ PLAN files │
|
||||
│ └────────────┘
|
||||
└── Done
|
||||
```
|
||||
|
||||
### 검증 아키텍처 (Nyquist 레이어)
|
||||
|
||||
plan-phase 조사 단계에서 GSD는 코드 작성 전에 각 페이즈 요구사항에 대한 자동화된 테스트 커버리지를 매핑합니다. 이를 통해 Claude의 실행자가 작업을 커밋할 때 몇 초 안에 검증할 수 있는 피드백 메커니즘이 이미 갖춰져 있습니다.
|
||||
|
||||
조사자는 기존 테스트 인프라를 감지하고 각 요구사항을 특정 테스트 명령어에 매핑하며 구현 시작 전에 생성해야 할 테스트 스캐폴딩을 식별합니다 (Wave 0 작업).
|
||||
|
||||
계획 검사기는 이를 8번째 검증 차원으로 적용합니다. 작업에 자동화된 검증 명령어가 없는 계획은 승인되지 않습니다.
|
||||
|
||||
**출력:** `{phase}-VALIDATION.md` — 해당 페이즈의 피드백 계약.
|
||||
|
||||
**비활성화:** 테스트 인프라가 중요하지 않은 빠른 프로토타이핑 페이즈에서는 `/gsd:settings`에서 `workflow.nyquist_validation: false`로 설정하세요.
|
||||
|
||||
### 소급 검증 (`/gsd:validate-phase`)
|
||||
|
||||
Nyquist 검증 도입 전에 실행된 페이즈나 전통적인 테스트 스위트만 있는 기존 코드베이스의 경우 커버리지 갭을 소급하여 감사하고 보완할 수 있습니다.
|
||||
|
||||
```
|
||||
/gsd:validate-phase N
|
||||
|
|
||||
+-- Detect state (VALIDATION.md exists? SUMMARY.md exists?)
|
||||
|
|
||||
+-- Discover: scan implementation, map requirements to tests
|
||||
|
|
||||
+-- Analyze gaps: which requirements lack automated verification?
|
||||
|
|
||||
+-- Present gap plan for approval
|
||||
|
|
||||
+-- Spawn auditor: generate tests, run, debug (max 3 attempts)
|
||||
|
|
||||
+-- Update VALIDATION.md
|
||||
|
|
||||
+-- COMPLIANT -> all requirements have automated checks
|
||||
+-- PARTIAL -> some gaps escalated to manual-only
|
||||
```
|
||||
|
||||
감사자는 구현 코드를 수정하지 않으며 테스트 파일과 VALIDATION.md만 수정합니다. 테스트에서 구현 버그가 발견되면 사용자가 처리할 수 있도록 에스컬레이션으로 표시됩니다.
|
||||
|
||||
**사용 시점:** Nyquist가 활성화되기 전에 계획된 페이즈를 실행한 후 또는 `/gsd:audit-milestone`에서 Nyquist 준수 갭이 발견된 후에 사용합니다.
|
||||
|
||||
### 가정 토론 모드
|
||||
|
||||
기본적으로 `/gsd:discuss-phase`는 구현 선호도에 대한 개방형 질문을 합니다. 가정 모드는 이를 역전시킵니다. GSD가 먼저 코드베이스를 읽고 페이즈를 어떻게 구축할지에 대한 구조화된 가정을 제시한 후 수정사항만 요청합니다.
|
||||
|
||||
**활성화:** `/gsd:settings`에서 `workflow.discuss_mode`를 `'assumptions'`로 설정합니다.
|
||||
|
||||
**작동 방식.**
|
||||
1. PROJECT.md, 코드베이스 매핑, 기존 관례를 읽습니다.
|
||||
2. 구조화된 가정 목록을 생성합니다 (기술 선택, 패턴, 파일 위치).
|
||||
3. 가정을 확인, 수정 또는 확장하도록 제시합니다.
|
||||
4. 확인된 가정으로 CONTEXT.md를 작성합니다.
|
||||
|
||||
**사용 시점.**
|
||||
- 코드베이스를 잘 아는 숙련된 개발자
|
||||
- 개방형 질문이 속도를 저해하는 빠른 반복 개발
|
||||
- 패턴이 잘 확립되고 예측 가능한 프로젝트
|
||||
|
||||
전체 discuss-mode 레퍼런스는 [docs/workflow-discuss-mode.md](workflow-discuss-mode.md)를 참고하세요.
|
||||
|
||||
---
|
||||
|
||||
## UI 설계 계약
|
||||
|
||||
### 배경
|
||||
|
||||
AI 생성 프론트엔드가 시각적으로 일관성이 없는 이유는 Claude Code의 UI 능력이 부족해서가 아닙니다. 실행 전에 설계 계약이 존재하지 않았기 때문입니다. 공유 간격 척도, 색상 계약, 또는 카피라이팅 기준 없이 구축된 다섯 개의 컴포넌트는 다섯 가지 약간씩 다른 시각적 결정을 만들어냅니다.
|
||||
|
||||
`/gsd:ui-phase`는 계획 전에 설계 계약을 확정합니다. `/gsd:ui-review`는 실행 후 결과를 감사합니다.
|
||||
|
||||
### 명령어
|
||||
|
||||
| 명령어 | 설명 |
|
||||
|--------|------|
|
||||
| `/gsd:ui-phase [N]` | 프론트엔드 페이즈를 위한 UI-SPEC.md 설계 계약 생성 |
|
||||
| `/gsd:ui-review [N]` | 구현된 UI의 6개 기둥 기반 시각적 감사 소급 수행 |
|
||||
|
||||
### 워크플로우: `/gsd:ui-phase`
|
||||
|
||||
**실행 시점:** `/gsd:discuss-phase` 이후, `/gsd:plan-phase` 이전 — 프론트엔드/UI 작업이 포함된 페이즈.
|
||||
|
||||
**흐름.**
|
||||
1. CONTEXT.md, RESEARCH.md, REQUIREMENTS.md에서 기존 결정사항을 읽습니다.
|
||||
2. 디자인 시스템 상태를 감지합니다 (shadcn components.json, Tailwind 설정, 기존 토큰).
|
||||
3. shadcn 초기화 게이트 — React/Next.js/Vite 프로젝트에 없으면 초기화를 제안합니다.
|
||||
4. 아직 답변되지 않은 설계 계약 질문만 묻습니다 (간격, 타이포그래피, 색상, 카피라이팅, 레지스트리 안전).
|
||||
5. 페이즈 디렉터리에 `{phase}-UI-SPEC.md`를 작성합니다.
|
||||
6. 6개 차원에 대해 검증합니다 (카피라이팅, 시각, 색상, 타이포그래피, 간격, 레지스트리 안전).
|
||||
7. BLOCKED인 경우 수정 루프 (최대 2회 반복).
|
||||
|
||||
**출력:** `.planning/phases/{phase-dir}/`의 `{padded_phase}-UI-SPEC.md`
|
||||
|
||||
### 워크플로우: `/gsd:ui-review`
|
||||
|
||||
**실행 시점:** `/gsd:execute-phase` 또는 `/gsd:verify-work` 이후 — 프론트엔드 코드가 있는 모든 프로젝트.
|
||||
|
||||
**독립 실행:** 모든 프로젝트에서 작동하며 GSD 관리 프로젝트가 아니어도 됩니다. UI-SPEC.md가 없으면 추상적인 6개 기둥 기준으로 감사합니다.
|
||||
|
||||
**6개 기둥 (각 1-4점 평가).**
|
||||
1. 카피라이팅 — CTA 레이블, 빈 상태, 오류 상태
|
||||
2. 시각 — 초점, 시각적 계층, 아이콘 접근성
|
||||
3. 색상 — 강조 사용 규율, 60/30/10 준수
|
||||
4. 타이포그래피 — 폰트 크기/굵기 제약 준수
|
||||
5. 간격 — 그리드 정렬, 토큰 일관성
|
||||
6. 경험 디자인 — 로딩/오류/빈 상태 커버리지
|
||||
|
||||
**출력:** 점수와 상위 3개 우선 수정사항이 포함된 페이즈 디렉터리의 `{padded_phase}-UI-REVIEW.md`
|
||||
|
||||
### 설정
|
||||
|
||||
| 설정 | 기본값 | 설명 |
|
||||
|------|--------|------|
|
||||
| `workflow.ui_phase` | `true` | 프론트엔드 페이즈를 위한 UI 설계 계약 생성 |
|
||||
| `workflow.ui_safety_gate` | `true` | plan-phase가 프론트엔드 페이즈에서 /gsd:ui-phase 실행을 유도합니다 |
|
||||
|
||||
두 설정 모두 부재 시 활성화 패턴을 따릅니다. `/gsd:settings`에서 비활성화할 수 있습니다.
|
||||
|
||||
### shadcn 초기화
|
||||
|
||||
React/Next.js/Vite 프로젝트에서 `components.json`이 없으면 UI 조사자가 shadcn 초기화를 제안합니다. 흐름은 다음과 같습니다.
|
||||
|
||||
1. `ui.shadcn.com/create`를 방문하여 프리셋을 구성합니다.
|
||||
2. 프리셋 문자열을 복사합니다.
|
||||
3. `npx shadcn init --preset {paste}`를 실행합니다.
|
||||
4. 프리셋은 전체 디자인 시스템(색상, 테두리 반경, 폰트)을 인코딩합니다.
|
||||
|
||||
프리셋 문자열은 GSD의 1급 계획 아티팩트가 되어 페이즈와 마일스톤에 걸쳐 재현 가능합니다.
|
||||
|
||||
### 레지스트리 안전 게이트
|
||||
|
||||
서드파티 shadcn 레지스트리는 임의의 코드를 주입할 수 있습니다. 안전 게이트는 다음을 요구합니다.
|
||||
- `npx shadcn view {component}` — 설치 전 검사
|
||||
- `npx shadcn diff {component}` — 공식 버전과 비교
|
||||
|
||||
`workflow.ui_safety_gate` 설정 토글로 제어됩니다.
|
||||
|
||||
### 스크린샷 저장
|
||||
|
||||
`/gsd:ui-review`는 Playwright CLI를 통해 `.planning/ui-reviews/`에 스크린샷을 캡처합니다. 바이너리 파일이 git에 포함되지 않도록 `.gitignore`가 자동으로 생성됩니다. 스크린샷은 `/gsd:complete-milestone` 실행 시 정리됩니다.
|
||||
|
||||
---
|
||||
|
||||
## 백로그 및 스레드
|
||||
|
||||
### 백로그 파킹 롯
|
||||
|
||||
활성 계획에 아직 준비되지 않은 아이디어는 999.x 번호 체계를 사용하여 백로그에 보관하며 활성 페이즈 순서 밖에 유지됩니다.
|
||||
|
||||
```
|
||||
/gsd:add-backlog "GraphQL API layer" # Creates 999.1-graphql-api-layer/
|
||||
/gsd:add-backlog "Mobile responsive" # Creates 999.2-mobile-responsive/
|
||||
```
|
||||
|
||||
백로그 항목은 전체 페이즈 디렉터리를 얻으므로 `/gsd:discuss-phase 999.1`로 아이디어를 더 탐구하거나 준비가 되면 `/gsd:plan-phase 999.1`을 사용할 수 있습니다.
|
||||
|
||||
`/gsd:review-backlog`으로 **검토 및 승격**합니다 — 모든 백로그 항목을 표시하고 승격 (활성 순서로 이동), 유지 (백로그에 남김), 또는 제거 (삭제)를 선택할 수 있습니다.
|
||||
|
||||
### 시드
|
||||
|
||||
시드는 트리거 조건이 있는 미래 지향적인 아이디어입니다. 백로그 항목과 달리 시드는 적절한 마일스톤 시점에 자동으로 표면화됩니다.
|
||||
|
||||
```
|
||||
/gsd:plant-seed "Add real-time collab when WebSocket infra is in place"
|
||||
```
|
||||
|
||||
시드는 전체 WHY와 언제 표면화할지를 보존합니다. `/gsd:new-milestone`은 모든 시드를 스캔하여 일치 항목을 제시합니다.
|
||||
|
||||
**저장 위치:** `.planning/seeds/SEED-NNN-slug.md`
|
||||
|
||||
### 지속적인 컨텍스트 스레드
|
||||
|
||||
스레드는 여러 세션에 걸쳐 이어지지만 특정 페이즈에 속하지 않는 작업을 위한 경량 교차 세션 지식 저장소입니다.
|
||||
|
||||
```
|
||||
/gsd:thread # List all threads
|
||||
/gsd:thread fix-deploy-key-auth # Resume existing thread
|
||||
/gsd:thread "Investigate TCP timeout" # Create new thread
|
||||
```
|
||||
|
||||
스레드는 `/gsd:pause-work`보다 가볍습니다. 페이즈 상태나 계획 컨텍스트가 없습니다. 각 스레드 파일에는 목표, 컨텍스트, 참조, 다음 단계 섹션이 포함됩니다.
|
||||
|
||||
스레드가 성숙해지면 페이즈(`/gsd:add-phase`)나 백로그 항목(`/gsd:add-backlog`)으로 승격할 수 있습니다.
|
||||
|
||||
**저장 위치:** `.planning/threads/{slug}.md`
|
||||
|
||||
---
|
||||
|
||||
## 워크스트림
|
||||
|
||||
워크스트림을 사용하면 상태 충돌 없이 여러 마일스톤 영역을 동시에 작업할 수 있습니다. 각 워크스트림은 독립적인 `.planning/` 상태를 가지므로 워크스트림 간 전환 시 진행 상황이 덮어쓰이지 않습니다.
|
||||
|
||||
**사용 시점:** 서로 다른 관심 영역(예: 백엔드 API와 프론트엔드 대시보드)에 걸친 마일스톤 기능을 독립적으로 계획, 실행 또는 토론하면서 컨텍스트 혼합 없이 작업하고 싶을 때 사용합니다.
|
||||
|
||||
### 명령어
|
||||
|
||||
| 명령어 | 목적 |
|
||||
|--------|------|
|
||||
| `/gsd:workstreams create <name>` | 격리된 계획 상태로 새 워크스트림 생성 |
|
||||
| `/gsd:workstreams switch <name>` | 활성 컨텍스트를 다른 워크스트림으로 전환 |
|
||||
| `/gsd:workstreams list` | 모든 워크스트림과 활성 워크스트림 표시 |
|
||||
| `/gsd:workstreams complete <name>` | 워크스트림을 완료로 표시하고 상태 아카이브 |
|
||||
|
||||
### 작동 방식
|
||||
|
||||
각 워크스트림은 자체 `.planning/` 디렉터리 하위 트리를 유지합니다. 워크스트림을 전환하면 GSD가 활성 계획 컨텍스트를 교체하여 `/gsd:progress`, `/gsd:discuss-phase`, `/gsd:plan-phase` 및 기타 명령어가 해당 워크스트림의 상태로 동작합니다.
|
||||
|
||||
이는 `/gsd:new-workspace`(별도 저장소 worktree를 생성)보다 가볍습니다. 워크스트림은 동일한 코드베이스와 git 히스토리를 공유하지만 계획 아티팩트를 격리합니다.
|
||||
|
||||
---
|
||||
|
||||
## 보안
|
||||
|
||||
### 심층 방어 (v1.27)
|
||||
|
||||
GSD는 LLM 시스템 프롬프트가 되는 마크다운 파일을 생성합니다. 즉 계획 아티팩트로 유입되는 사용자 제어 텍스트는 잠재적인 간접 프롬프트 인젝션 벡터입니다. v1.27에서 중앙화된 보안 강화가 도입되었습니다.
|
||||
|
||||
**경로 순회 방지.**
|
||||
모든 사용자 제공 파일 경로(`--text-file`, `--prd`)는 프로젝트 디렉터리 내에서 해석되는지 검증합니다. macOS `/var` → `/private/var` 심볼릭 링크 해석을 처리합니다.
|
||||
|
||||
**프롬프트 인젝션 감지.**
|
||||
`security.cjs` 모듈은 사용자 제공 텍스트가 계획 아티팩트에 입력되기 전에 알려진 인젝션 패턴(역할 재정의, 지시 우회, 시스템 태그 인젝션)을 스캔합니다.
|
||||
|
||||
**런타임 훅.**
|
||||
- `gsd-prompt-guard.js` — `.planning/`에 대한 Write/Edit 호출에서 인젝션 패턴 스캔 (항상 활성, 권고만)
|
||||
- `gsd-workflow-guard.js` — GSD 워크플로우 컨텍스트 밖의 파일 편집 시 경고 (`hooks.workflow_guard`로 선택적 활성화)
|
||||
|
||||
**CI 스캐너.**
|
||||
`prompt-injection-scan.test.cjs`는 모든 에이전트, 워크플로우, 명령어 파일에서 내장된 인젝션 벡터를 스캔합니다. 테스트 스위트의 일부로 실행됩니다.
|
||||
|
||||
---
|
||||
|
||||
### 실행 웨이브 조정
|
||||
|
||||
```
|
||||
/gsd:execute-phase N
|
||||
│
|
||||
├── Analyze plan dependencies
|
||||
│
|
||||
├── Wave 1 (independent plans):
|
||||
│ ├── Executor A (fresh 200K context) -> commit
|
||||
│ └── Executor B (fresh 200K context) -> commit
|
||||
│
|
||||
├── Wave 2 (depends on Wave 1):
|
||||
│ └── Executor C (fresh 200K context) -> commit
|
||||
│
|
||||
└── Verifier
|
||||
└── Check codebase against phase goals
|
||||
│
|
||||
├── PASS -> VERIFICATION.md (success)
|
||||
└── FAIL -> Issues logged for /gsd:verify-work
|
||||
```
|
||||
|
||||
### 브라운필드 워크플로우 (기존 코드베이스)
|
||||
|
||||
```
|
||||
/gsd:map-codebase
|
||||
│
|
||||
├── Stack Mapper -> codebase/STACK.md
|
||||
├── Arch Mapper -> codebase/ARCHITECTURE.md
|
||||
├── Convention Mapper -> codebase/CONVENTIONS.md
|
||||
└── Concern Mapper -> codebase/CONCERNS.md
|
||||
│
|
||||
┌───────▼──────────┐
|
||||
│ /gsd:new-project │ <- Questions focus on what you're ADDING
|
||||
└──────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 명령어 레퍼런스
|
||||
|
||||
### 핵심 워크플로우
|
||||
|
||||
| 명령어 | 목적 | 사용 시점 |
|
||||
|--------|------|----------|
|
||||
| `/gsd:new-project` | 전체 프로젝트 초기화: 질문, 조사, 요구사항, 로드맵 | 새 프로젝트 시작 시 |
|
||||
| `/gsd:new-project --auto @idea.md` | 문서에서 자동 초기화 | PRD나 아이디어 문서가 준비된 경우 |
|
||||
| `/gsd:discuss-phase [N]` | 구현 결정사항 캡처 | 계획 전 구축 방식을 결정할 때 |
|
||||
| `/gsd:ui-phase [N]` | UI 설계 계약 생성 | discuss-phase 이후, plan-phase 이전 (프론트엔드 페이즈) |
|
||||
| `/gsd:plan-phase [N]` | 조사 + 계획 + 검증 | 페이즈 실행 전 |
|
||||
| `/gsd:execute-phase <N>` | 병렬 웨이브로 모든 계획 실행 | 계획이 완료된 후 |
|
||||
| `/gsd:verify-work [N]` | 자동 진단을 포함한 수동 UAT | 실행 완료 후 |
|
||||
| `/gsd:ship [N]` | 검증된 작업으로 PR 생성 | 검증 통과 후 |
|
||||
| `/gsd:fast <text>` | 계획을 완전히 건너뛰는 인라인 간단 작업 | 오타 수정, 설정 변경, 소규모 리팩터링 |
|
||||
| `/gsd:next` | 상태 자동 감지 및 다음 단계 실행 | 언제든 — "다음에 무엇을 해야 하나?" |
|
||||
| `/gsd:ui-review [N]` | 6개 기둥 기반 시각적 감사 소급 수행 | 실행 또는 verify-work 이후 (프론트엔드 프로젝트) |
|
||||
| `/gsd:audit-milestone` | 마일스톤이 완료 정의를 충족했는지 검증 | 마일스톤 완료 전 |
|
||||
| `/gsd:complete-milestone` | 마일스톤 아카이브 및 릴리스 태그 생성 | 모든 페이즈 검증 완료 시 |
|
||||
| `/gsd:new-milestone [name]` | 다음 버전 사이클 시작 | 마일스톤 완료 후 |
|
||||
|
||||
### 탐색
|
||||
|
||||
| 명령어 | 목적 | 사용 시점 |
|
||||
|--------|------|----------|
|
||||
| `/gsd:progress` | 상태 및 다음 단계 표시 | 언제든 -- "지금 어디 있나?" |
|
||||
| `/gsd:resume-work` | 마지막 세션의 전체 컨텍스트 복원 | 새 세션 시작 시 |
|
||||
| `/gsd:pause-work` | 구조화된 핸드오프 저장 (HANDOFF.json + continue-here.md) | 페이즈 중간에 중단할 때 |
|
||||
| `/gsd:session-report` | 작업 및 결과가 포함된 세션 요약 생성 | 세션 종료 시, 이해관계자 공유 시 |
|
||||
| `/gsd:help` | 모든 명령어 표시 | 빠른 레퍼런스 |
|
||||
| `/gsd:update` | 변경 로그 미리보기와 함께 GSD 업데이트 | 새 버전 확인 시 |
|
||||
| `/gsd:join-discord` | Discord 커뮤니티 초대 링크 열기 | 질문이나 커뮤니티 참여 시 |
|
||||
|
||||
### 페이즈 관리
|
||||
|
||||
| 명령어 | 목적 | 사용 시점 |
|
||||
|--------|------|----------|
|
||||
| `/gsd:add-phase` | 로드맵에 새 페이즈 추가 | 초기 계획 후 범위가 늘어날 때 |
|
||||
| `/gsd:insert-phase [N]` | 긴급 작업 삽입 (소수점 번호 체계) | 마일스톤 중간의 긴급 수정 시 |
|
||||
| `/gsd:remove-phase [N]` | 미래 페이즈 제거 및 재번호 | 기능 범위 축소 시 |
|
||||
| `/gsd:list-phase-assumptions [N]` | Claude의 예상 접근 방식 미리 확인 | 계획 전 방향 검증 시 |
|
||||
| `/gsd:plan-milestone-gaps` | 감사 갭을 위한 페이즈 생성 | 감사에서 누락 항목이 발견된 후 |
|
||||
| `/gsd:research-phase [N]` | 심층 에코시스템 조사만 수행 | 복잡하거나 익숙하지 않은 도메인 |
|
||||
|
||||
### 브라운필드 및 유틸리티
|
||||
|
||||
| 명령어 | 목적 | 사용 시점 |
|
||||
|--------|------|----------|
|
||||
| `/gsd:map-codebase` | 기존 코드베이스 분석 | 기존 코드에서 `/gsd:new-project` 실행 전 |
|
||||
| `/gsd:quick` | GSD 보증을 갖춘 임시 작업 | 버그 수정, 소규모 기능, 설정 변경 |
|
||||
| `/gsd:debug [desc]` | 지속적인 상태를 유지하는 체계적인 디버깅 | 문제가 발생했을 때 |
|
||||
| `/gsd:forensics` | 워크플로우 실패에 대한 진단 보고서 | 상태, 아티팩트, git 히스토리가 손상된 것 같을 때 |
|
||||
| `/gsd:add-todo [desc]` | 나중을 위한 아이디어 캡처 | 세션 중에 생각이 날 때 |
|
||||
| `/gsd:check-todos` | 보류 중인 할 일 목록 | 캡처된 아이디어 검토 시 |
|
||||
| `/gsd:settings` | 워크플로우 토글 및 모델 프로필 설정 | 모델 변경, 에이전트 토글 시 |
|
||||
| `/gsd:set-profile <profile>` | 빠른 프로필 전환 | 비용/품질 트레이드오프 변경 시 |
|
||||
| `/gsd:reapply-patches` | 업데이트 후 로컬 수정사항 복원 | 로컬 편집이 있는 상태에서 `/gsd:update` 이후 |
|
||||
|
||||
### 코드 품질 및 리뷰
|
||||
|
||||
| 명령어 | 목적 | 사용 시점 |
|
||||
|--------|------|----------|
|
||||
| `/gsd:review --phase N` | 외부 CLI를 통한 교차 AI 동료 리뷰 | 실행 전 계획 검증 시 |
|
||||
| `/gsd:pr-branch` | `.planning/` 커밋을 필터링한 깔끔한 PR 브랜치 | 계획 없는 diff로 PR 생성 전 |
|
||||
| `/gsd:audit-uat` | 모든 페이즈의 검증 부채 감사 | 마일스톤 완료 전 |
|
||||
|
||||
### 백로그 및 스레드
|
||||
|
||||
| 명령어 | 목적 | 사용 시점 |
|
||||
|--------|------|----------|
|
||||
| `/gsd:add-backlog <desc>` | 백로그 파킹 롯에 아이디어 추가 (999.x) | 활성 계획에 준비되지 않은 아이디어 |
|
||||
| `/gsd:review-backlog` | 백로그 항목 승격/유지/제거 | 새 마일스톤 전 우선순위 결정 시 |
|
||||
| `/gsd:plant-seed <idea>` | 트리거 조건이 있는 미래 지향적인 아이디어 | 미래 마일스톤에서 표면화되어야 할 아이디어 |
|
||||
| `/gsd:thread [name]` | 지속적인 컨텍스트 스레드 | 페이즈 구조 밖의 교차 세션 작업 |
|
||||
|
||||
---
|
||||
|
||||
## 설정 레퍼런스
|
||||
|
||||
GSD는 프로젝트 설정을 `.planning/config.json`에 저장합니다. `/gsd:new-project` 중에 설정하거나 나중에 `/gsd:settings`로 업데이트할 수 있습니다.
|
||||
|
||||
### 전체 config.json 스키마
|
||||
|
||||
```json
|
||||
{
|
||||
"mode": "interactive",
|
||||
"granularity": "standard",
|
||||
"model_profile": "balanced",
|
||||
"planning": {
|
||||
"commit_docs": true,
|
||||
"search_gitignored": false
|
||||
},
|
||||
"workflow": {
|
||||
"research": true,
|
||||
"plan_check": true,
|
||||
"verifier": true,
|
||||
"nyquist_validation": true,
|
||||
"ui_phase": true,
|
||||
"ui_safety_gate": true,
|
||||
"research_before_questions": false,
|
||||
"discuss_mode": "standard",
|
||||
"skip_discuss": false
|
||||
},
|
||||
"resolve_model_ids": "anthropic",
|
||||
"hooks": {
|
||||
"context_warnings": true,
|
||||
"workflow_guard": false
|
||||
},
|
||||
"git": {
|
||||
"branching_strategy": "none",
|
||||
"phase_branch_template": "gsd/phase-{phase}-{slug}",
|
||||
"milestone_branch_template": "gsd/{milestone}-{slug}",
|
||||
"quick_branch_template": null
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 핵심 설정
|
||||
|
||||
| 설정 | 옵션 | 기본값 | 제어 대상 |
|
||||
|------|------|--------|----------|
|
||||
| `mode` | `interactive`, `yolo` | `interactive` | `yolo`는 결정을 자동 승인하고 `interactive`는 각 단계에서 확인합니다 |
|
||||
| `granularity` | `coarse`, `standard`, `fine` | `standard` | 페이즈 세분화: 범위를 얼마나 세밀하게 나눌지 (3-5, 5-8, 또는 8-12 페이즈) |
|
||||
| `model_profile` | `quality`, `balanced`, `budget`, `inherit` | `balanced` | 각 에이전트의 모델 티어 (아래 표 참고) |
|
||||
|
||||
### 계획 설정
|
||||
|
||||
| 설정 | 옵션 | 기본값 | 제어 대상 |
|
||||
|------|------|--------|----------|
|
||||
| `planning.commit_docs` | `true`, `false` | `true` | `.planning/` 파일을 git에 커밋할지 여부 |
|
||||
| `planning.search_gitignored` | `true`, `false` | `false` | 광범위한 검색에 `--no-ignore`를 추가하여 `.planning/` 포함 |
|
||||
|
||||
> **참고:** `.planning/`이 `.gitignore`에 있으면 설정 값에 관계없이 `commit_docs`는 자동으로 `false`가 됩니다.
|
||||
|
||||
### 워크플로우 토글
|
||||
|
||||
| 설정 | 옵션 | 기본값 | 제어 대상 |
|
||||
|------|------|--------|----------|
|
||||
| `workflow.research` | `true`, `false` | `true` | 계획 전 도메인 조사 |
|
||||
| `workflow.plan_check` | `true`, `false` | `true` | 계획 검증 루프 (최대 3회 반복) |
|
||||
| `workflow.verifier` | `true`, `false` | `true` | 페이즈 목표에 대한 실행 후 검증 |
|
||||
| `workflow.nyquist_validation` | `true`, `false` | `true` | plan-phase 중 검증 아키텍처 조사 및 8번째 plan-check 차원 |
|
||||
| `workflow.ui_phase` | `true`, `false` | `true` | 프론트엔드 페이즈를 위한 UI 설계 계약 생성 |
|
||||
| `workflow.ui_safety_gate` | `true`, `false` | `true` | plan-phase가 프론트엔드 페이즈에서 /gsd:ui-phase 실행을 유도합니다 |
|
||||
| `workflow.research_before_questions` | `true`, `false` | `false` | 토론 질문 이후가 아닌 이전에 조사를 실행합니다 |
|
||||
| `workflow.discuss_mode` | `standard`, `assumptions` | `standard` | 토론 방식: 개방형 질문 vs. 코드베이스 기반 가정 |
|
||||
| `workflow.skip_discuss` | `true`, `false` | `false` | 자율 모드에서 discuss-phase를 완전히 건너뜁니다. ROADMAP 페이즈 목표에서 최소한의 CONTEXT.md를 작성합니다 |
|
||||
|
||||
### 훅 설정
|
||||
|
||||
| 설정 | 옵션 | 기본값 | 제어 대상 |
|
||||
|------|------|--------|----------|
|
||||
| `hooks.context_warnings` | `true`, `false` | `true` | 컨텍스트 윈도우 사용량 경고 |
|
||||
| `hooks.workflow_guard` | `true`, `false` | `false` | GSD 워크플로우 컨텍스트 밖의 파일 편집 시 경고 |
|
||||
|
||||
익숙한 도메인에서 페이즈를 빠르게 진행하거나 토큰을 절약할 때 워크플로우 토글을 비활성화하세요.
|
||||
|
||||
### Git 브랜칭
|
||||
|
||||
| 설정 | 옵션 | 기본값 | 제어 대상 |
|
||||
|------|------|--------|----------|
|
||||
| `git.branching_strategy` | `none`, `phase`, `milestone` | `none` | 브랜치 생성 시점과 방법 |
|
||||
| `git.phase_branch_template` | 템플릿 문자열 | `gsd/phase-{phase}-{slug}` | phase 전략의 브랜치 이름 |
|
||||
| `git.milestone_branch_template` | 템플릿 문자열 | `gsd/{milestone}-{slug}` | milestone 전략의 브랜치 이름 |
|
||||
| `git.quick_branch_template` | 템플릿 문자열 또는 `null` | `null` | `/gsd:quick` 작업의 선택적 브랜치 이름 |
|
||||
|
||||
**브랜칭 전략 설명.**
|
||||
|
||||
| 전략 | 브랜치 생성 | 범위 | 적합한 경우 |
|
||||
|------|------------|------|------------|
|
||||
| `none` | 생성 안 함 | N/A | 개인 개발, 간단한 프로젝트 |
|
||||
| `phase` | 각 `execute-phase` 시 | 페이즈당 하나의 브랜치 | 페이즈별 코드 리뷰, 세분화된 롤백 |
|
||||
| `milestone` | 첫 `execute-phase` 시 | 모든 페이즈가 하나의 브랜치 공유 | 릴리스 브랜치, 버전별 PR |
|
||||
|
||||
**템플릿 변수:** `{phase}` = 0 패딩된 번호 (예: "03"), `{slug}` = 소문자 하이픈 이름, `{milestone}` = 버전 (예: "v1.0"), `{num}` / `{quick}` = 빠른 작업 ID (예: "260317-abc").
|
||||
|
||||
빠른 작업 브랜칭 예시:
|
||||
|
||||
```json
|
||||
"git": {
|
||||
"quick_branch_template": "gsd/quick-{num}-{slug}"
|
||||
}
|
||||
```
|
||||
|
||||
### 모델 프로필 (에이전트별 분류)
|
||||
|
||||
| 에이전트 | `quality` | `balanced` | `budget` | `inherit` |
|
||||
|----------|-----------|------------|----------|-----------|
|
||||
| gsd-planner | Opus | Opus | Sonnet | Inherit |
|
||||
| gsd-roadmapper | Opus | Sonnet | Sonnet | Inherit |
|
||||
| gsd-executor | Opus | Sonnet | Sonnet | Inherit |
|
||||
| gsd-phase-researcher | Opus | Sonnet | Haiku | Inherit |
|
||||
| gsd-project-researcher | Opus | Sonnet | Haiku | Inherit |
|
||||
| gsd-research-synthesizer | Sonnet | Sonnet | Haiku | Inherit |
|
||||
| gsd-debugger | Opus | Sonnet | Sonnet | Inherit |
|
||||
| gsd-codebase-mapper | Sonnet | Haiku | Haiku | Inherit |
|
||||
| gsd-verifier | Sonnet | Sonnet | Haiku | Inherit |
|
||||
| gsd-plan-checker | Sonnet | Sonnet | Haiku | Inherit |
|
||||
| gsd-integration-checker | Sonnet | Sonnet | Haiku | Inherit |
|
||||
|
||||
**프로필 철학.**
|
||||
- **quality** -- 모든 의사결정 에이전트에 Opus를 사용하고 읽기 전용 검증에 Sonnet을 사용합니다. 할당량이 충분하고 작업이 중요할 때 사용합니다.
|
||||
- **balanced** -- 아키텍처 결정이 이루어지는 계획에만 Opus를 사용하고 나머지는 Sonnet을 사용합니다. 합당한 이유로 기본값입니다.
|
||||
- **budget** -- 코드를 작성하는 모든 것에 Sonnet을 사용하고 조사 및 검증에 Haiku를 사용합니다. 대량 작업이나 덜 중요한 페이즈에 사용합니다.
|
||||
- **inherit** -- 모든 에이전트가 현재 세션 모델을 사용합니다. 동적으로 모델을 전환할 때 (예: OpenCode `/model`) 또는 예상치 못한 API 비용을 방지하기 위해 비Anthropic 공급자 (OpenRouter, 로컬 모델)와 함께 Claude Code를 사용할 때 적합합니다. 비Claude 런타임 (Codex, OpenCode, Gemini CLI)의 경우 설치 프로그램이 자동으로 `resolve_model_ids: "omit"`을 설정합니다 — [비Claude 런타임](#비claude-런타임-codex-opencode-gemini-cli-사용)을 참고하세요.
|
||||
|
||||
---
|
||||
|
||||
## 사용 예시
|
||||
|
||||
### 새 프로젝트 (전체 사이클)
|
||||
|
||||
```bash
|
||||
claude --dangerously-skip-permissions
|
||||
/gsd:new-project # Answer questions, configure, approve roadmap
|
||||
/clear
|
||||
/gsd:discuss-phase 1 # Lock in your preferences
|
||||
/gsd:ui-phase 1 # Design contract (frontend phases)
|
||||
/gsd:plan-phase 1 # Research + plan + verify
|
||||
/gsd:execute-phase 1 # Parallel execution
|
||||
/gsd:verify-work 1 # Manual UAT
|
||||
/gsd:ship 1 # Create PR from verified work
|
||||
/gsd:ui-review 1 # Visual audit (frontend phases)
|
||||
/clear
|
||||
/gsd:next # Auto-detect and run next step
|
||||
...
|
||||
/gsd:audit-milestone # Check everything shipped
|
||||
/gsd:complete-milestone # Archive, tag, done
|
||||
/gsd:session-report # Generate session summary
|
||||
```
|
||||
|
||||
### 기존 문서로 새 프로젝트 시작
|
||||
|
||||
```bash
|
||||
/gsd:new-project --auto @prd.md # Auto-runs research/requirements/roadmap from your doc
|
||||
/clear
|
||||
/gsd:discuss-phase 1 # Normal flow from here
|
||||
```
|
||||
|
||||
### 기존 코드베이스
|
||||
|
||||
```bash
|
||||
/gsd:map-codebase # Analyze what exists (parallel agents)
|
||||
/gsd:new-project # Questions focus on what you're ADDING
|
||||
# (normal phase workflow from here)
|
||||
```
|
||||
|
||||
### 빠른 버그 수정
|
||||
|
||||
```bash
|
||||
/gsd:quick
|
||||
> "Fix the login button not responding on mobile Safari"
|
||||
```
|
||||
|
||||
### 휴식 후 재개
|
||||
|
||||
```bash
|
||||
/gsd:progress # See where you left off and what's next
|
||||
# or
|
||||
/gsd:resume-work # Full context restoration from last session
|
||||
```
|
||||
|
||||
### 릴리스 준비
|
||||
|
||||
```bash
|
||||
/gsd:audit-milestone # Check requirements coverage, detect stubs
|
||||
/gsd:plan-milestone-gaps # If audit found gaps, create phases to close them
|
||||
/gsd:complete-milestone # Archive, tag, done
|
||||
```
|
||||
|
||||
### 속도 vs 품질 프리셋
|
||||
|
||||
| 시나리오 | Mode | Granularity | Profile | Research | Plan Check | Verifier |
|
||||
|---------|------|-------------|---------|----------|------------|---------|
|
||||
| 프로토타이핑 | `yolo` | `coarse` | `budget` | 끄기 | 끄기 | 끄기 |
|
||||
| 일반 개발 | `interactive` | `standard` | `balanced` | 켜기 | 켜기 | 켜기 |
|
||||
| 프로덕션 | `interactive` | `fine` | `quality` | 켜기 | 켜기 | 켜기 |
|
||||
|
||||
**자율 모드에서 discuss-phase 건너뛰기:** PROJECT.md에 선호도가 이미 충분히 캡처된 `yolo` 모드에서 실행할 때 `/gsd:settings`에서 `workflow.skip_discuss: true`로 설정하세요. 이렇게 하면 discuss-phase를 완전히 우회하고 ROADMAP 페이즈 목표에서 파생된 최소한의 CONTEXT.md를 작성합니다. PROJECT.md와 관례가 충분히 포괄적이어서 토론이 새로운 정보를 제공하지 않을 때 유용합니다.
|
||||
|
||||
### 마일스톤 중간 범위 변경
|
||||
|
||||
```bash
|
||||
/gsd:add-phase # Append a new phase to the roadmap
|
||||
# or
|
||||
/gsd:insert-phase 3 # Insert urgent work between phases 3 and 4
|
||||
# or
|
||||
/gsd:remove-phase 7 # Descope phase 7 and renumber
|
||||
```
|
||||
|
||||
### 멀티 프로젝트 워크스페이스
|
||||
|
||||
격리된 GSD 상태로 여러 저장소나 기능을 병렬로 작업합니다.
|
||||
|
||||
```bash
|
||||
# Create a workspace with repos from your monorepo
|
||||
/gsd:new-workspace --name feature-b --repos hr-ui,ZeymoAPI
|
||||
|
||||
# Feature branch isolation — worktree of current repo with its own .planning/
|
||||
/gsd:new-workspace --name feature-b --repos .
|
||||
|
||||
# Then cd into the workspace and initialize GSD
|
||||
cd ~/gsd-workspaces/feature-b
|
||||
/gsd:new-project
|
||||
|
||||
# List and manage workspaces
|
||||
/gsd:list-workspaces
|
||||
/gsd:remove-workspace feature-b
|
||||
```
|
||||
|
||||
각 워크스페이스는 다음을 포함합니다.
|
||||
- 자체 `.planning/` 디렉터리 (원본 저장소와 완전히 독립)
|
||||
- 지정된 저장소의 git worktree (기본값) 또는 클론
|
||||
- 멤버 저장소를 추적하는 `WORKSPACE.md` 매니페스트
|
||||
|
||||
---
|
||||
|
||||
## 문제 해결
|
||||
|
||||
### "Project already initialized"
|
||||
|
||||
`.planning/PROJECT.md`가 이미 존재하는데 `/gsd:new-project`를 실행했습니다. 이것은 안전 검사입니다. 처음부터 다시 시작하려면 먼저 `.planning/` 디렉터리를 삭제하세요.
|
||||
|
||||
### 긴 세션 중 컨텍스트 저하
|
||||
|
||||
주요 명령어 사이에 컨텍스트 윈도우를 지우세요: Claude Code에서 `/clear`를 사용합니다. GSD는 새로운 컨텍스트를 기반으로 설계되었습니다 — 모든 서브에이전트는 깨끗한 200K 윈도우를 받습니다. 메인 세션의 품질이 저하되면 지우고 `/gsd:resume-work` 또는 `/gsd:progress`를 사용하여 상태를 복원하세요.
|
||||
|
||||
### 계획이 잘못되거나 맞지 않는 경우
|
||||
|
||||
계획 전에 `/gsd:discuss-phase [N]`을 실행하세요. 대부분의 계획 품질 문제는 `CONTEXT.md`가 있었다면 방지할 수 있었던 가정을 Claude가 세우기 때문에 발생합니다. `/gsd:list-phase-assumptions [N]`을 실행하여 계획에 동의하기 전에 Claude가 무엇을 하려는지 확인할 수도 있습니다.
|
||||
|
||||
### 실행이 실패하거나 스텁을 생성하는 경우
|
||||
|
||||
계획이 너무 야심차지 않은지 확인하세요. 계획에는 최대 2-3개의 작업이 있어야 합니다. 작업이 너무 크면 단일 컨텍스트 윈도우에서 안정적으로 처리할 수 있는 범위를 초과합니다. 더 작은 범위로 재계획하세요.
|
||||
|
||||
### 현재 위치를 잃어버린 경우
|
||||
|
||||
`/gsd:progress`를 실행하세요. 모든 상태 파일을 읽고 현재 위치와 다음에 할 일을 정확히 알려줍니다.
|
||||
|
||||
### 실행 후 변경이 필요한 경우
|
||||
|
||||
`/gsd:execute-phase`를 다시 실행하지 마세요. 목표를 정확히 수정하려면 `/gsd:quick`을 사용하거나 UAT를 통해 체계적으로 문제를 식별하고 수정하려면 `/gsd:verify-work`를 사용하세요.
|
||||
|
||||
### 모델 비용이 너무 높은 경우
|
||||
|
||||
예산 프로필로 전환하세요: `/gsd:set-profile budget`. 도메인이 익숙하다면 (또는 Claude에게 익숙하다면) `/gsd:settings`에서 조사 및 plan-check 에이전트를 비활성화하세요.
|
||||
|
||||
### 비Claude 런타임 사용 (Codex, OpenCode, Gemini CLI)
|
||||
|
||||
비Claude 런타임용으로 GSD를 설치했다면 설치 프로그램이 이미 모든 에이전트가 런타임의 기본 모델을 사용하도록 모델 해석을 구성했습니다. 수동 설정이 필요하지 않습니다. 구체적으로 설치 프로그램은 config에 `resolve_model_ids: "omit"`을 설정하여 GSD가 Anthropic 모델 ID 해석을 건너뛰고 런타임이 자체 기본 모델을 선택하도록 합니다.
|
||||
|
||||
비Claude 런타임에서 에이전트별로 다른 모델을 할당하려면 런타임이 인식하는 완전한 자격을 갖춘 모델 ID와 함께 `.planning/config.json`에 `model_overrides`를 추가하세요.
|
||||
|
||||
```json
|
||||
{
|
||||
"resolve_model_ids": "omit",
|
||||
"model_overrides": {
|
||||
"gsd-planner": "o3",
|
||||
"gsd-executor": "o4-mini",
|
||||
"gsd-debugger": "o3"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
설치 프로그램은 Gemini CLI, OpenCode, Codex에 대해 `resolve_model_ids: "omit"`을 자동으로 구성합니다. 비Claude 런타임을 수동으로 설정하는 경우 직접 `.planning/config.json`에 추가하세요.
|
||||
|
||||
전체 설명은 [Configuration Reference](CONFIGURATION.md#non-claude-runtimes-codex-opencode-gemini-cli)를 참고하세요.
|
||||
|
||||
### 비Anthropic 공급자와 함께 Claude Code 사용 (OpenRouter, 로컬)
|
||||
|
||||
GSD 서브에이전트가 Anthropic 모델을 호출하는데 OpenRouter나 로컬 공급자를 통해 비용을 지불하고 있다면 `inherit` 프로필로 전환하세요: `/gsd:set-profile inherit`. 이렇게 하면 모든 에이전트가 특정 Anthropic 모델 대신 현재 세션 모델을 사용합니다. `/gsd:settings` → Model Profile → Inherit도 참고하세요.
|
||||
|
||||
### 민감하거나 비공개 프로젝트에서 작업하는 경우
|
||||
|
||||
`/gsd:new-project` 중에 또는 `/gsd:settings`에서 `commit_docs: false`로 설정하세요. `.planning/`을 `.gitignore`에 추가하세요. 계획 아티팩트는 로컬에 유지되며 git에 절대 포함되지 않습니다.
|
||||
|
||||
### GSD 업데이트가 로컬 변경사항을 덮어쓴 경우
|
||||
|
||||
v1.17부터 설치 프로그램이 로컬로 수정된 파일을 `gsd-local-patches/`에 백업합니다. 변경사항을 다시 병합하려면 `/gsd:reapply-patches`를 실행하세요.
|
||||
|
||||
### 워크플로우 진단 (`/gsd:forensics`)
|
||||
|
||||
워크플로우가 명확하지 않은 방식으로 실패할 때 — 계획이 존재하지 않는 파일을 참조하거나 실행이 예상치 못한 결과를 생성하거나 상태가 손상된 것 같을 때 — `/gsd:forensics`를 실행하여 진단 보고서를 생성하세요.
|
||||
|
||||
**검사 항목.**
|
||||
- Git 히스토리 이상 (고아 커밋, 예상치 못한 브랜치 상태, rebase 아티팩트)
|
||||
- 아티팩트 무결성 (누락되거나 잘못된 계획 파일, 끊어진 교차 참조)
|
||||
- 상태 불일치 (실제 파일 존재 여부 대비 ROADMAP 상태, 설정 드리프트)
|
||||
|
||||
**출력:** 발견사항과 권장 수정 단계가 포함된 `.planning/forensics/`의 진단 보고서.
|
||||
|
||||
### 서브에이전트가 실패한 것 같지만 작업이 완료된 경우
|
||||
|
||||
Claude Code 분류 버그에 대한 알려진 해결 방법이 있습니다. GSD의 오케스트레이터 (execute-phase, quick)는 실패를 보고하기 전에 실제 출력을 현장 확인합니다. 실패 메시지가 표시되었지만 커밋이 이루어진 경우 `git log`를 확인하세요 — 작업이 성공했을 수 있습니다.
|
||||
|
||||
### 병렬 실행으로 인한 빌드 잠금 오류
|
||||
|
||||
병렬 웨이브 실행 중에 pre-commit 훅 실패, cargo lock 경합, 또는 30분 이상의 실행 시간이 발생한다면 여러 에이전트가 동시에 빌드 도구를 실행하기 때문입니다. GSD는 v1.26부터 이를 자동으로 처리합니다 — 병렬 에이전트는 커밋에 `--no-verify`를 사용하고 오케스트레이터가 각 웨이브 후 한 번 훅을 실행합니다. 이전 버전을 사용하는 경우 프로젝트의 `CLAUDE.md`에 다음을 추가하세요.
|
||||
|
||||
```markdown
|
||||
## Git Commit Rules for Agents
|
||||
All subagent/executor commits MUST use `--no-verify`.
|
||||
```
|
||||
|
||||
병렬 실행을 완전히 비활성화하려면: `/gsd:settings` → `parallelization.enabled`를 `false`로 설정합니다.
|
||||
|
||||
### Windows: 보호된 디렉터리에서 설치 충돌
|
||||
|
||||
Windows에서 설치 프로그램이 `EPERM: operation not permitted, scandir`으로 충돌하는 경우 OS 보호 디렉터리 (예: Chromium 브라우저 프로필) 때문입니다. v1.24부터 수정되었으니 최신 버전으로 업데이트하세요. 해결 방법으로 설치 프로그램을 실행하기 전에 문제가 되는 디렉터리를 임시로 이름을 변경하세요.
|
||||
|
||||
---
|
||||
|
||||
## 복구 빠른 레퍼런스
|
||||
|
||||
| 문제 | 해결 방법 |
|
||||
|------|----------|
|
||||
| 컨텍스트 손실 / 새 세션 | `/gsd:resume-work` 또는 `/gsd:progress` |
|
||||
| 페이즈가 잘못됨 | 페이즈 커밋에 `git revert` 후 재계획 |
|
||||
| 범위 변경 필요 | `/gsd:add-phase`, `/gsd:insert-phase`, 또는 `/gsd:remove-phase` |
|
||||
| 마일스톤 감사에서 갭 발견 | `/gsd:plan-milestone-gaps` |
|
||||
| 무언가 고장남 | `/gsd:debug "description"` |
|
||||
| 워크플로우 상태 손상 의심 | `/gsd:forensics` |
|
||||
| 빠른 목표 수정 | `/gsd:quick` |
|
||||
| 계획이 비전과 맞지 않음 | `/gsd:discuss-phase [N]` 후 재계획 |
|
||||
| 비용이 높아짐 | `/gsd:set-profile budget` 및 `/gsd:settings`에서 에이전트 비활성화 |
|
||||
| 업데이트가 로컬 변경사항 파괴 | `/gsd:reapply-patches` |
|
||||
| 이해관계자를 위한 세션 요약 필요 | `/gsd:session-report` |
|
||||
| 다음 단계를 모르겠음 | `/gsd:next` |
|
||||
| 병렬 실행 빌드 오류 | GSD 업데이트 또는 `parallelization.enabled: false` 설정 |
|
||||
|
||||
---
|
||||
|
||||
## 프로젝트 파일 구조
|
||||
|
||||
참고로 GSD가 프로젝트에 생성하는 파일 구조입니다.
|
||||
|
||||
```
|
||||
.planning/
|
||||
PROJECT.md # Project vision and context (always loaded)
|
||||
REQUIREMENTS.md # Scoped v1/v2 requirements with IDs
|
||||
ROADMAP.md # Phase breakdown with status tracking
|
||||
STATE.md # Decisions, blockers, session memory
|
||||
config.json # Workflow configuration
|
||||
MILESTONES.md # Completed milestone archive
|
||||
HANDOFF.json # Structured session handoff (from /gsd:pause-work)
|
||||
research/ # Domain research from /gsd:new-project
|
||||
reports/ # Session reports (from /gsd:session-report)
|
||||
todos/
|
||||
pending/ # Captured ideas awaiting work
|
||||
done/ # Completed todos
|
||||
debug/ # Active debug sessions
|
||||
resolved/ # Archived debug sessions
|
||||
codebase/ # Brownfield codebase mapping (from /gsd:map-codebase)
|
||||
phases/
|
||||
XX-phase-name/
|
||||
XX-YY-PLAN.md # Atomic execution plans
|
||||
XX-YY-SUMMARY.md # Execution outcomes and decisions
|
||||
CONTEXT.md # Your implementation preferences
|
||||
RESEARCH.md # Ecosystem research findings
|
||||
VERIFICATION.md # Post-execution verification results
|
||||
XX-UI-SPEC.md # UI design contract (from /gsd:ui-phase)
|
||||
XX-UI-REVIEW.md # Visual audit scores (from /gsd:ui-review)
|
||||
ui-reviews/ # Screenshots from /gsd:ui-review (gitignored)
|
||||
```
|
||||
115
docs/ko-KR/context-monitor.md
Normal file
115
docs/ko-KR/context-monitor.md
Normal file
@@ -0,0 +1,115 @@
|
||||
# 컨텍스트 윈도우 모니터
|
||||
|
||||
에이전트의 컨텍스트 윈도우 사용량이 높을 때 경고를 주는 post-tool 훅입니다 (Claude Code의 경우 `PostToolUse`, Gemini CLI의 경우 `AfterTool`).
|
||||
|
||||
## 문제
|
||||
|
||||
상태바(statusline)는 **사용자**에게 컨텍스트 사용량을 보여주지만 **에이전트** 자체는 컨텍스트 한계를 인식하지 못합니다. 컨텍스트가 부족해지면 에이전트는 한계에 부딪힐 때까지 작업을 계속 진행하며 상태가 저장되지 않은 채 작업 도중에 멈출 수 있습니다.
|
||||
|
||||
## 동작 방식
|
||||
|
||||
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를 우회합니다.
|
||||
|
||||
## 아키텍처
|
||||
|
||||
```
|
||||
Statusline Hook (gsd-statusline.js)
|
||||
| 기록
|
||||
v
|
||||
/tmp/claude-ctx-{session_id}.json
|
||||
^ 읽기
|
||||
|
|
||||
Context Monitor (gsd-context-monitor.js, PostToolUse/AfterTool)
|
||||
| 주입
|
||||
v
|
||||
additionalContext -> 에이전트가 경고를 받음
|
||||
```
|
||||
|
||||
브리지 파일은 단순한 JSON 객체입니다.
|
||||
|
||||
```json
|
||||
{
|
||||
"session_id": "abc123",
|
||||
"remaining_percentage": 28.5,
|
||||
"used_pct": 71,
|
||||
"timestamp": 1708200000
|
||||
}
|
||||
```
|
||||
|
||||
## GSD와의 통합
|
||||
|
||||
GSD의 `/gsd:pause-work` 명령어는 실행 상태를 저장합니다. WARNING 메시지는 해당 명령어 사용을 권장하며 CRITICAL 메시지는 즉각적인 상태 저장을 지시합니다.
|
||||
|
||||
## 설정
|
||||
|
||||
두 훅 모두 `npx get-shit-done-cc` 설치 중에 자동으로 등록됩니다.
|
||||
|
||||
- **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"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 안전성
|
||||
|
||||
- 훅은 모든 동작을 try/catch로 감싸며 오류 발생 시 조용히 종료합니다.
|
||||
- 도구 실행을 절대 차단하지 않습니다. 모니터에 문제가 생겨도 에이전트 워크플로우가 중단되지 않습니다.
|
||||
- 60초 이상 된 오래된 메트릭은 무시됩니다.
|
||||
- 누락된 브리지 파일은 정상적으로 처리됩니다 (서브에이전트, 새 세션 등의 경우).
|
||||
@@ -0,0 +1,699 @@
|
||||
# 초기화 시 new-project config 완전 구체화
|
||||
|
||||
> **에이전트 작업자를 위한 안내:** 필수 하위 기술: superpowers:subagent-driven-development(권장) 또는 superpowers:executing-plans를 사용하여 이 계획을 작업 단위로 구현하세요. 단계는 체크박스(`- [ ]`) 형식으로 진행 상황을 추적합니다.
|
||||
|
||||
**목표:** `/gsd:new-project`가 `.planning/config.json`을 생성할 때, 파일에 사용자가 선택한 6개 키만이 아닌 모든 유효한 기본값이 포함되도록 하여 개발자가 소스 코드를 읽지 않고도 모든 설정을 확인할 수 있게 합니다.
|
||||
|
||||
**아키텍처:** 새 프로젝트의 전체 config에 대한 단일 진실 공급원으로서 `config.cjs`에 단일 JS 함수 `buildNewProjectConfig(cwd, userChoices)`를 추가합니다. CLI 명령어 `config-new-project`로 노출합니다. 부분적인 JSON을 인라인으로 작성하는 대신 이 명령어를 호출하도록 `new-project.md` 워크플로우를 업데이트합니다.
|
||||
|
||||
**기술 스택:** Node.js/CommonJS, 기존 gsd-tools CLI, 테스트에는 `node:test`.
|
||||
|
||||
---
|
||||
|
||||
## 배경: 현재 상태
|
||||
|
||||
`new-project.md` Step 5는 이 부분적인 config를 작성합니다(AI가 템플릿을 채움):
|
||||
|
||||
```json
|
||||
{
|
||||
"mode": "...", "granularity": "...", "parallelization": "...",
|
||||
"commit_docs": "...", "model_profile": "...",
|
||||
"workflow": { "research", "plan_check", "verifier", "nyquist_validation" }
|
||||
}
|
||||
```
|
||||
|
||||
런타임에 `loadConfig()`가 자동으로 해석하는 누락된 키들:
|
||||
|
||||
- `search_gitignored: false`
|
||||
- `brave_search: false` (또는 환경 감지 시 `true`)
|
||||
- `git.branching_strategy: "none"`
|
||||
- `git.phase_branch_template: "gsd/phase-{phase}-{slug}"`
|
||||
- `git.milestone_branch_template: "gsd/{milestone}-{slug}"`
|
||||
|
||||
처음부터 존재해야 하는 전체 config:
|
||||
|
||||
```json
|
||||
{
|
||||
"mode": "yolo|interactive",
|
||||
"granularity": "coarse|standard|fine",
|
||||
"model_profile": "balanced",
|
||||
"commit_docs": true,
|
||||
"parallelization": true,
|
||||
"search_gitignored": false,
|
||||
"brave_search": false,
|
||||
"git": {
|
||||
"branching_strategy": "none",
|
||||
"phase_branch_template": "gsd/phase-{phase}-{slug}",
|
||||
"milestone_branch_template": "gsd/{milestone}-{slug}"
|
||||
},
|
||||
"workflow": {
|
||||
"research": true,
|
||||
"plan_check": true,
|
||||
"verifier": true,
|
||||
"nyquist_validation": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 파일 맵
|
||||
|
||||
| 파일 | 액션 | 목적 |
|
||||
|------|--------|---------|
|
||||
| `get-shit-done/bin/lib/config.cjs` | 수정 | `buildNewProjectConfig()` + `cmdConfigNewProject()` 추가 |
|
||||
| `get-shit-done/bin/gsd-tools.cjs` | 수정 | `config-new-project` case 등록 + usage 문자열 업데이트 |
|
||||
| `get-shit-done/workflows/new-project.md` | 수정 | Steps 2a + 5: 인라인 JSON 작성을 CLI 호출로 교체 |
|
||||
| `tests/config.test.cjs` | 수정 | `config-new-project` 테스트 스위트 추가 |
|
||||
|
||||
---
|
||||
|
||||
## 작업 1: config.cjs에 `buildNewProjectConfig`와 `cmdConfigNewProject` 추가
|
||||
|
||||
**파일.**
|
||||
|
||||
- 수정: `get-shit-done/bin/lib/config.cjs`
|
||||
|
||||
- [ ] **Step 1.1: 실패하는 테스트 먼저 작성**
|
||||
|
||||
`tests/config.test.cjs`에 추가(`config-get` 스위트 뒤, `module.exports` 앞):
|
||||
|
||||
```js
|
||||
// ─── config-new-project ──────────────────────────────────────────────────────
|
||||
|
||||
describe('config-new-project command', () => {
|
||||
let tmpDir;
|
||||
|
||||
beforeEach(() => {
|
||||
tmpDir = createTempProject();
|
||||
});
|
||||
|
||||
afterEach(() => {
|
||||
cleanup(tmpDir);
|
||||
});
|
||||
|
||||
test('creates full config with all expected top-level and nested keys', () => {
|
||||
const choices = JSON.stringify({
|
||||
mode: 'interactive',
|
||||
granularity: 'standard',
|
||||
parallelization: true,
|
||||
commit_docs: true,
|
||||
model_profile: 'balanced',
|
||||
workflow: { research: true, plan_check: true, verifier: true, nyquist_validation: true },
|
||||
});
|
||||
const result = runGsdTools(['config-new-project', choices], tmpDir);
|
||||
assert.ok(result.success, `Command failed: ${result.error}`);
|
||||
|
||||
const config = readConfig(tmpDir);
|
||||
|
||||
// 사용자 선택값 확인
|
||||
assert.strictEqual(config.mode, 'interactive');
|
||||
assert.strictEqual(config.granularity, 'standard');
|
||||
assert.strictEqual(config.parallelization, true);
|
||||
assert.strictEqual(config.commit_docs, true);
|
||||
assert.strictEqual(config.model_profile, 'balanced');
|
||||
|
||||
// 기본값이 구체화되었는지 확인
|
||||
assert.strictEqual(typeof config.search_gitignored, 'boolean');
|
||||
assert.strictEqual(typeof config.brave_search, 'boolean');
|
||||
|
||||
// git 섹션에 세 가지 키가 모두 존재하는지 확인
|
||||
assert.ok(config.git && typeof config.git === 'object', 'git section should exist');
|
||||
assert.strictEqual(config.git.branching_strategy, 'none');
|
||||
assert.strictEqual(config.git.phase_branch_template, 'gsd/phase-{phase}-{slug}');
|
||||
assert.strictEqual(config.git.milestone_branch_template, 'gsd/{milestone}-{slug}');
|
||||
|
||||
// workflow 섹션에 네 가지 키가 모두 존재하는지 확인
|
||||
assert.ok(config.workflow && typeof config.workflow === 'object', 'workflow section should exist');
|
||||
assert.strictEqual(config.workflow.research, true);
|
||||
assert.strictEqual(config.workflow.plan_check, true);
|
||||
assert.strictEqual(config.workflow.verifier, true);
|
||||
assert.strictEqual(config.workflow.nyquist_validation, true);
|
||||
});
|
||||
|
||||
test('user choices override defaults', () => {
|
||||
const choices = JSON.stringify({
|
||||
mode: 'yolo',
|
||||
granularity: 'coarse',
|
||||
parallelization: false,
|
||||
commit_docs: false,
|
||||
model_profile: 'quality',
|
||||
workflow: { research: false, plan_check: false, verifier: true, nyquist_validation: false },
|
||||
});
|
||||
const result = runGsdTools(['config-new-project', choices], tmpDir);
|
||||
assert.ok(result.success, `Command failed: ${result.error}`);
|
||||
|
||||
const config = readConfig(tmpDir);
|
||||
assert.strictEqual(config.mode, 'yolo');
|
||||
assert.strictEqual(config.granularity, 'coarse');
|
||||
assert.strictEqual(config.parallelization, false);
|
||||
assert.strictEqual(config.commit_docs, false);
|
||||
assert.strictEqual(config.model_profile, 'quality');
|
||||
assert.strictEqual(config.workflow.research, false);
|
||||
assert.strictEqual(config.workflow.plan_check, false);
|
||||
assert.strictEqual(config.workflow.verifier, true);
|
||||
assert.strictEqual(config.workflow.nyquist_validation, false);
|
||||
// 선택하지 않은 키에 대해서도 기본값이 존재해야 함
|
||||
assert.strictEqual(config.git.branching_strategy, 'none');
|
||||
assert.strictEqual(typeof config.search_gitignored, 'boolean');
|
||||
});
|
||||
|
||||
test('works with empty choices — all defaults materialized', () => {
|
||||
const result = runGsdTools(['config-new-project', '{}'], tmpDir);
|
||||
assert.ok(result.success, `Command failed: ${result.error}`);
|
||||
|
||||
const config = readConfig(tmpDir);
|
||||
assert.strictEqual(config.model_profile, 'balanced');
|
||||
assert.strictEqual(config.commit_docs, true);
|
||||
assert.strictEqual(config.parallelization, true);
|
||||
assert.strictEqual(config.search_gitignored, false);
|
||||
assert.ok(config.git && typeof config.git === 'object');
|
||||
assert.strictEqual(config.git.branching_strategy, 'none');
|
||||
assert.ok(config.workflow && typeof config.workflow === 'object');
|
||||
assert.strictEqual(config.workflow.nyquist_validation, true);
|
||||
});
|
||||
|
||||
test('is idempotent — returns already_exists if config exists', () => {
|
||||
// 첫 번째 호출: 생성
|
||||
const choices = JSON.stringify({ mode: 'yolo', granularity: 'fine' });
|
||||
const first = runGsdTools(['config-new-project', choices], tmpDir);
|
||||
assert.ok(first.success, `First call failed: ${first.error}`);
|
||||
const firstOut = JSON.parse(first.output);
|
||||
assert.strictEqual(firstOut.created, true);
|
||||
|
||||
// 두 번째 호출: 멱등성
|
||||
const second = runGsdTools(['config-new-project', choices], tmpDir);
|
||||
assert.ok(second.success, `Second call failed: ${second.error}`);
|
||||
const secondOut = JSON.parse(second.output);
|
||||
assert.strictEqual(secondOut.created, false);
|
||||
assert.strictEqual(secondOut.reason, 'already_exists');
|
||||
|
||||
// config 변경되지 않음
|
||||
const config = readConfig(tmpDir);
|
||||
assert.strictEqual(config.mode, 'yolo');
|
||||
assert.strictEqual(config.granularity, 'fine');
|
||||
});
|
||||
|
||||
test('auto_advance in workflow choices is preserved', () => {
|
||||
const choices = JSON.stringify({
|
||||
mode: 'yolo',
|
||||
granularity: 'standard',
|
||||
workflow: { research: true, plan_check: true, verifier: true, nyquist_validation: true, auto_advance: true },
|
||||
});
|
||||
const result = runGsdTools(['config-new-project', choices], tmpDir);
|
||||
assert.ok(result.success, `Command failed: ${result.error}`);
|
||||
|
||||
const config = readConfig(tmpDir);
|
||||
assert.strictEqual(config.workflow.auto_advance, true);
|
||||
});
|
||||
|
||||
test('rejects invalid JSON choices', () => {
|
||||
const result = runGsdTools(['config-new-project', '{not-json}'], tmpDir);
|
||||
assert.strictEqual(result.success, false);
|
||||
assert.ok(result.error.includes('Invalid JSON'), `Expected "Invalid JSON" in: ${result.error}`);
|
||||
});
|
||||
|
||||
test('output JSON has created:true on success', () => {
|
||||
const choices = JSON.stringify({ mode: 'interactive', granularity: 'standard' });
|
||||
const result = runGsdTools(['config-new-project', choices], tmpDir);
|
||||
assert.ok(result.success, `Command failed: ${result.error}`);
|
||||
const out = JSON.parse(result.output);
|
||||
assert.strictEqual(out.created, true);
|
||||
assert.strictEqual(out.path, '.planning/config.json');
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
- [ ] **Step 1.2: 실패하는 테스트 실행하여 실패 확인**
|
||||
|
||||
```bash
|
||||
cd /Users/diego/Dev/get-shit-done
|
||||
node --test tests/config.test.cjs 2>&1 | grep -E "config-new-project|FAIL|Error"
|
||||
```
|
||||
|
||||
예상 결과: 모든 `config-new-project` 테스트가 "config-new-project is not a valid command" 또는 유사한 오류로 실패합니다.
|
||||
|
||||
- [ ] **Step 1.3: config.cjs에 `buildNewProjectConfig`와 `cmdConfigNewProject` 구현**
|
||||
|
||||
`get-shit-done/bin/lib/config.cjs`에서 `validateKnownConfigKeyPath` 함수 뒤(약 35번째 줄)와 `ensureConfigFile` 앞에 다음을 추가하세요:
|
||||
|
||||
```js
|
||||
/**
|
||||
* 새 프로젝트의 완전히 구체화된 config를 빌드합니다.
|
||||
*
|
||||
* 다음 우선순위 순서로 병합합니다:
|
||||
* 1. 하드코딩된 기본값
|
||||
* 2. ~/.gsd/defaults.json의 사용자 수준 기본값(있는 경우)
|
||||
* 3. userChoices (new-project 중 사용자가 명시적으로 선택한 설정)
|
||||
*
|
||||
* 일반 객체를 반환합니다 — 파일을 직접 작성하지 않습니다.
|
||||
*/
|
||||
function buildNewProjectConfig(cwd, userChoices) {
|
||||
const choices = userChoices || {};
|
||||
const homedir = require('os').homedir();
|
||||
|
||||
// Brave Search API 키 가용성 감지
|
||||
const braveKeyFile = path.join(homedir, '.gsd', 'brave_api_key');
|
||||
const hasBraveSearch = !!(process.env.BRAVE_API_KEY || fs.existsSync(braveKeyFile));
|
||||
|
||||
// 사용 가능한 경우 ~/.gsd/defaults.json에서 사용자 수준 기본값 로드
|
||||
const globalDefaultsPath = path.join(homedir, '.gsd', 'defaults.json');
|
||||
let userDefaults = {};
|
||||
try {
|
||||
if (fs.existsSync(globalDefaultsPath)) {
|
||||
userDefaults = JSON.parse(fs.readFileSync(globalDefaultsPath, 'utf-8'));
|
||||
// 더 이상 사용되지 않는 "depth" 키를 "granularity"로 마이그레이션
|
||||
if ('depth' in userDefaults && !('granularity' in userDefaults)) {
|
||||
const depthToGranularity = { quick: 'coarse', standard: 'standard', comprehensive: 'fine' };
|
||||
userDefaults.granularity = depthToGranularity[userDefaults.depth] || userDefaults.depth;
|
||||
delete userDefaults.depth;
|
||||
try {
|
||||
fs.writeFileSync(globalDefaultsPath, JSON.stringify(userDefaults, null, 2), 'utf-8');
|
||||
} catch {}
|
||||
}
|
||||
}
|
||||
} catch {
|
||||
// 잘못된 전역 기본값 무시
|
||||
}
|
||||
|
||||
const hardcoded = {
|
||||
model_profile: 'balanced',
|
||||
commit_docs: true,
|
||||
parallelization: true,
|
||||
search_gitignored: false,
|
||||
brave_search: hasBraveSearch,
|
||||
git: {
|
||||
branching_strategy: 'none',
|
||||
phase_branch_template: 'gsd/phase-{phase}-{slug}',
|
||||
milestone_branch_template: 'gsd/{milestone}-{slug}',
|
||||
},
|
||||
workflow: {
|
||||
research: true,
|
||||
plan_check: true,
|
||||
verifier: true,
|
||||
nyquist_validation: true,
|
||||
},
|
||||
};
|
||||
|
||||
// 세 단계 병합: hardcoded <- userDefaults <- choices
|
||||
return {
|
||||
...hardcoded,
|
||||
...userDefaults,
|
||||
...choices,
|
||||
git: {
|
||||
...hardcoded.git,
|
||||
...(userDefaults.git || {}),
|
||||
...(choices.git || {}),
|
||||
},
|
||||
workflow: {
|
||||
...hardcoded.workflow,
|
||||
...(userDefaults.workflow || {}),
|
||||
...(choices.workflow || {}),
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* 명령어: 새 프로젝트를 위한 완전히 구체화된 .planning/config.json을 생성합니다.
|
||||
*
|
||||
* 사용자가 선택한 설정을 JSON 문자열로 받습니다(/gsd:new-project 중 명시적으로
|
||||
* 구성한 키들). 나머지 키들은 하드코딩된 기본값과 선택적 ~/.gsd/defaults.json에서 채워집니다.
|
||||
*
|
||||
* 멱등성: config.json이 이미 존재하면 { created: false }를 반환합니다.
|
||||
*/
|
||||
function cmdConfigNewProject(cwd, choicesJson, raw) {
|
||||
const configPath = path.join(cwd, '.planning', 'config.json');
|
||||
const planningDir = path.join(cwd, '.planning');
|
||||
|
||||
// 멱등성: 기존 config를 덮어쓰지 않음
|
||||
if (fs.existsSync(configPath)) {
|
||||
output({ created: false, reason: 'already_exists' }, raw, 'exists');
|
||||
return;
|
||||
}
|
||||
|
||||
// 사용자 선택값 파싱
|
||||
let userChoices = {};
|
||||
if (choicesJson && choicesJson.trim() !== '') {
|
||||
try {
|
||||
userChoices = JSON.parse(choicesJson);
|
||||
} catch (err) {
|
||||
error('Invalid JSON for config-new-project: ' + err.message);
|
||||
}
|
||||
}
|
||||
|
||||
// .planning 디렉토리가 존재하는지 확인
|
||||
try {
|
||||
if (!fs.existsSync(planningDir)) {
|
||||
fs.mkdirSync(planningDir, { recursive: true });
|
||||
}
|
||||
} catch (err) {
|
||||
error('Failed to create .planning directory: ' + err.message);
|
||||
}
|
||||
|
||||
const config = buildNewProjectConfig(cwd, userChoices);
|
||||
|
||||
try {
|
||||
fs.writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf-8');
|
||||
output({ created: true, path: '.planning/config.json' }, raw, 'created');
|
||||
} catch (err) {
|
||||
error('Failed to write config.json: ' + err.message);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`config.cjs` 하단의 `module.exports`에 `cmdConfigNewProject`도 추가하세요.
|
||||
|
||||
- [ ] **Step 1.4: 테스트 실행하여 통과 확인**
|
||||
|
||||
```bash
|
||||
cd /Users/diego/Dev/get-shit-done
|
||||
node --test tests/config.test.cjs 2>&1 | tail -20
|
||||
```
|
||||
|
||||
예상 결과: 모든 `config-new-project` 테스트가 통과합니다. 기존 테스트도 계속 통과합니다.
|
||||
|
||||
- [ ] **Step 1.5: 커밋**
|
||||
|
||||
```bash
|
||||
cd /Users/diego/Dev/get-shit-done
|
||||
git add get-shit-done/bin/lib/config.cjs tests/config.test.cjs
|
||||
git commit -m "feat: add config-new-project command for full config materialization"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 작업 2: gsd-tools.cjs에 `config-new-project` 등록
|
||||
|
||||
**파일.**
|
||||
|
||||
- 수정: `get-shit-done/bin/gsd-tools.cjs`
|
||||
|
||||
- [ ] **Step 2.1: gsd-tools.cjs의 switch에 case 추가**
|
||||
|
||||
`config-get` case 뒤(약 401번째 줄)에 다음을 추가하세요:
|
||||
|
||||
```js
|
||||
case 'config-new-project': {
|
||||
config.cmdConfigNewProject(cwd, args[1], raw);
|
||||
break;
|
||||
}
|
||||
```
|
||||
|
||||
178번째 줄의 usage 문자열도 `config-new-project`를 포함하도록 업데이트하세요:
|
||||
|
||||
현재: `...config-ensure-section, init`
|
||||
변경: `...config-ensure-section, config-new-project, init`
|
||||
|
||||
- [ ] **Step 2.2: CLI 등록 스모크 테스트**
|
||||
|
||||
```bash
|
||||
cd /Users/diego/Dev/get-shit-done
|
||||
node get-shit-done/bin/gsd-tools.cjs config-new-project '{"mode":"interactive","granularity":"standard"}' --cwd /tmp/gsd-smoke-$(date +%s)
|
||||
```
|
||||
|
||||
예상 결과: `{"created":true,"path":".planning/config.json"}` (또는 유사한 형태)가 출력됩니다.
|
||||
|
||||
정리: `rm -rf /tmp/gsd-smoke-*`
|
||||
|
||||
- [ ] **Step 2.3: 전체 테스트 스위트 실행**
|
||||
|
||||
```bash
|
||||
cd /Users/diego/Dev/get-shit-done
|
||||
node --test tests/config.test.cjs 2>&1 | tail -10
|
||||
```
|
||||
|
||||
예상 결과: 모두 통과합니다.
|
||||
|
||||
- [ ] **Step 2.4: 커밋**
|
||||
|
||||
```bash
|
||||
cd /Users/diego/Dev/get-shit-done
|
||||
git add get-shit-done/bin/gsd-tools.cjs
|
||||
git commit -m "feat: register config-new-project in gsd-tools CLI router"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 작업 3: config-new-project를 사용하도록 new-project.md 워크플로우 업데이트
|
||||
|
||||
**파일.**
|
||||
|
||||
- 수정: `get-shit-done/workflows/new-project.md`
|
||||
|
||||
이것이 핵심 변경사항입니다. 두 곳을 업데이트해야 합니다:
|
||||
|
||||
- **Step 2a** (auto 모드 config 생성, 약 168–195번째 줄)
|
||||
- **Step 5** (대화형 모드 config 생성, 약 470–498번째 줄)
|
||||
|
||||
- [ ] **Step 3.1: Step 2a(auto 모드) 업데이트**
|
||||
|
||||
Step 2a에서 config.json을 생성하는 블록을 찾으세요:
|
||||
|
||||
```markdown
|
||||
Create `.planning/config.json` with mode set to "yolo":
|
||||
|
||||
```json
|
||||
{
|
||||
"mode": "yolo",
|
||||
"granularity": "[selected]",
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
```
|
||||
|
||||
인라인 JSON 작성 지침을 다음으로 교체하세요:
|
||||
|
||||
```markdown
|
||||
Create `.planning/config.json` using the CLI (fills in all defaults automatically):
|
||||
|
||||
```bash
|
||||
mkdir -p .planning
|
||||
node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" config-new-project "$(cat <<'CHOICES'
|
||||
{
|
||||
"mode": "yolo",
|
||||
"granularity": "[selected: coarse|standard|fine]",
|
||||
"parallelization": [true|false],
|
||||
"commit_docs": [true|false],
|
||||
"model_profile": "[selected: quality|balanced|budget|inherit]",
|
||||
"workflow": {
|
||||
"research": [true|false],
|
||||
"plan_check": [true|false],
|
||||
"verifier": [true|false],
|
||||
"nyquist_validation": [true|false],
|
||||
"auto_advance": true
|
||||
}
|
||||
}
|
||||
CHOICES
|
||||
)"
|
||||
```
|
||||
|
||||
The command merges your selections with all runtime defaults (`search_gitignored`, `brave_search`, `git` section), producing a fully-materialized config.
|
||||
|
||||
```
|
||||
|
||||
- [ ] **Step 3.2: Step 5(대화형 모드) 업데이트**
|
||||
|
||||
Step 5에서 config.json을 생성하는 블록을 찾으세요:
|
||||
|
||||
```markdown
|
||||
Create `.planning/config.json` with all settings:
|
||||
|
||||
```json
|
||||
{
|
||||
"mode": "yolo|interactive",
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
```
|
||||
|
||||
다음으로 교체하세요:
|
||||
|
||||
```markdown
|
||||
Create `.planning/config.json` using the CLI (fills in all defaults automatically):
|
||||
|
||||
```bash
|
||||
mkdir -p .planning
|
||||
node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" config-new-project "$(cat <<'CHOICES'
|
||||
{
|
||||
"mode": "[selected: yolo|interactive]",
|
||||
"granularity": "[selected: coarse|standard|fine]",
|
||||
"parallelization": [true|false],
|
||||
"commit_docs": [true|false],
|
||||
"model_profile": "[selected: quality|balanced|budget|inherit]",
|
||||
"workflow": {
|
||||
"research": [true|false],
|
||||
"plan_check": [true|false],
|
||||
"verifier": [true|false],
|
||||
"nyquist_validation": [true|false]
|
||||
}
|
||||
}
|
||||
CHOICES
|
||||
)"
|
||||
```
|
||||
|
||||
The command merges your selections with all runtime defaults (`search_gitignored`, `brave_search`, `git` section), producing a fully-materialized config.
|
||||
|
||||
```
|
||||
|
||||
- [ ] **Step 3.3: 워크플로우 파일이 올바르게 읽히는지 확인**
|
||||
|
||||
```bash
|
||||
cd /Users/diego/Dev/get-shit-done
|
||||
grep -n "config-new-project\|config\.json\|CHOICES" get-shit-done/workflows/new-project.md
|
||||
```
|
||||
|
||||
예상 결과: `config-new-project` 2회 등장(단계당 하나씩), config 생성을 위한 인라인 JSON 템플릿 없음.
|
||||
|
||||
- [ ] **Step 3.4: 커밋**
|
||||
|
||||
```bash
|
||||
cd /Users/diego/Dev/get-shit-done
|
||||
git add get-shit-done/workflows/new-project.md
|
||||
git commit -m "feat: use config-new-project in new-project workflow for full config materialization"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 작업 4: 검증
|
||||
|
||||
- [ ] **Step 4.1: 전체 테스트 스위트 실행**
|
||||
|
||||
```bash
|
||||
cd /Users/diego/Dev/get-shit-done
|
||||
node --test tests/ 2>&1 | tail -30
|
||||
```
|
||||
|
||||
예상 결과: 모든 테스트가 통과합니다(회귀 없음).
|
||||
|
||||
- [ ] **Step 4.2: 수동 엔드투엔드 검증**
|
||||
|
||||
`new-project.md`가 새 프로젝트에서 수행하는 작업을 시뮬레이션합니다:
|
||||
|
||||
```bash
|
||||
# 새로운 프로젝트 디렉토리 생성
|
||||
TMP=$(mktemp -d)
|
||||
cd "$TMP"
|
||||
|
||||
# Step 1 시뮬레이션: init new-project가 반환하는 내용
|
||||
node /Users/diego/Dev/get-shit-done/get-shit-done/bin/gsd-tools.cjs init new-project --cwd "$TMP"
|
||||
|
||||
# Step 5 시뮬레이션: 전체 config 생성
|
||||
node /Users/diego/Dev/get-shit-done/get-shit-done/bin/gsd-tools.cjs config-new-project '{
|
||||
"mode": "interactive",
|
||||
"granularity": "standard",
|
||||
"parallelization": true,
|
||||
"commit_docs": true,
|
||||
"model_profile": "balanced",
|
||||
"workflow": {
|
||||
"research": true,
|
||||
"plan_check": true,
|
||||
"verifier": true,
|
||||
"nyquist_validation": true
|
||||
}
|
||||
}' --cwd "$TMP"
|
||||
|
||||
# 파일에 예상되는 12개 키가 모두 있는지 확인
|
||||
echo "=== Generated config.json ==="
|
||||
cat "$TMP/.planning/config.json"
|
||||
|
||||
# 정리
|
||||
rm -rf "$TMP"
|
||||
```
|
||||
|
||||
예상 출력: `mode`, `granularity`, `model_profile`, `commit_docs`, `parallelization`, `search_gitignored`, `brave_search`, `git`(3개 하위 키), `workflow`(4개 하위 키)가 있는 config.json — 총 12개 최상위 키(또는 `git`과 `workflow`를 단일 키로 계산하면 10개).
|
||||
|
||||
- [ ] **Step 4.3: 멱등성 확인**
|
||||
|
||||
```bash
|
||||
TMP=$(mktemp -d)
|
||||
CHOICES='{"mode":"yolo","granularity":"coarse"}'
|
||||
|
||||
node /Users/diego/Dev/get-shit-done/get-shit-done/bin/gsd-tools.cjs config-new-project "$CHOICES" --cwd "$TMP"
|
||||
FIRST=$(cat "$TMP/.planning/config.json")
|
||||
|
||||
# 두 번째 호출은 no-op이어야 함
|
||||
node /Users/diego/Dev/get-shit-done/get-shit-done/bin/gsd-tools.cjs config-new-project "$CHOICES" --cwd "$TMP"
|
||||
SECOND=$(cat "$TMP/.planning/config.json")
|
||||
|
||||
[ "$FIRST" = "$SECOND" ] && echo "IDEMPOTENT: OK" || echo "IDEMPOTENT: FAIL"
|
||||
rm -rf "$TMP"
|
||||
```
|
||||
|
||||
예상 결과: `IDEMPOTENT: OK`
|
||||
|
||||
- [ ] **Step 4.4: loadConfig가 새 형식을 올바르게 읽는지 확인**
|
||||
|
||||
```bash
|
||||
TMP=$(mktemp -d)
|
||||
node /Users/diego/Dev/get-shit-done/get-shit-done/bin/gsd-tools.cjs config-new-project '{
|
||||
"mode":"yolo","granularity":"standard","parallelization":true,"commit_docs":true,
|
||||
"model_profile":"balanced",
|
||||
"workflow":{"research":true,"plan_check":false,"verifier":true,"nyquist_validation":true}
|
||||
}' --cwd "$TMP"
|
||||
|
||||
# loadConfig는 plan_check(중첩된 workflow.plan_check로)를 올바르게 읽어야 함
|
||||
node /Users/diego/Dev/get-shit-done/get-shit-done/bin/gsd-tools.cjs config-get workflow.plan_check --cwd "$TMP"
|
||||
# 예상: false
|
||||
|
||||
node /Users/diego/Dev/get-shit-done/get-shit-done/bin/gsd-tools.cjs config-get git.branching_strategy --cwd "$TMP"
|
||||
# 예상: "none"
|
||||
|
||||
rm -rf "$TMP"
|
||||
```
|
||||
|
||||
- [ ] **Step 4.5: 최종 전체 테스트 스위트 + 커밋**
|
||||
|
||||
```bash
|
||||
cd /Users/diego/Dev/get-shit-done
|
||||
node --test tests/ 2>&1 | grep -E "pass|fail|error" | tail -5
|
||||
```
|
||||
|
||||
예상 결과: 모두 통과, 0개 실패.
|
||||
|
||||
---
|
||||
|
||||
## 부록: 업스트림용 PR 설명
|
||||
|
||||
```
|
||||
feat: materialize all config defaults at new-project initialization
|
||||
|
||||
**문제:**
|
||||
`/gsd:new-project`는 온보딩 중 사용자가 명시적으로 선택한 6개 키만으로
|
||||
`.planning/config.json`을 생성합니다. 5개의 추가 키
|
||||
(`search_gitignored`, `brave_search`, `git.branching_strategy`,
|
||||
`git.phase_branch_template`, `git.milestone_branch_template`)는
|
||||
런타임에 `loadConfig()`가 자동으로 해석하지만 디스크에는 기록되지 않습니다.
|
||||
|
||||
이로 인해 두 가지 문제가 발생합니다:
|
||||
1. **발견성**: 소스 코드를 읽지 않고는 `git.branching_strategy`를
|
||||
확인하거나 이해할 수 없습니다 — config에 표시되지 않습니다.
|
||||
2. **암묵적 확장**: `/gsd:settings` 또는 `config-set`이 처음으로 config에
|
||||
기록할 때도 해당 키들이 추가되지 않습니다. config는 유효한 구성의
|
||||
일부만 반영합니다.
|
||||
|
||||
**해결책:**
|
||||
`gsd-tools.cjs`에 `config-new-project` CLI 명령어를 추가합니다. 이 명령어는:
|
||||
- 사용자가 선택한 값을 JSON으로 받습니다.
|
||||
- 모든 런타임 기본값(환경 감지 `brave_search` 포함)과 병합합니다.
|
||||
- 완전히 구체화된 config를 한 번에 작성합니다.
|
||||
|
||||
하드코딩된 부분 JSON 템플릿을 작성하는 대신 이 명령어를 호출하도록
|
||||
`new-project.md` 워크플로우(Steps 2a와 5)를 업데이트합니다. 기본값은 이제
|
||||
정확히 한 곳에 있습니다: `config.cjs`의 `buildNewProjectConfig()`.
|
||||
|
||||
**이 접근이 보수적인 이유:**
|
||||
- `loadConfig()`, `ensureConfigFile()`, 또는 읽기 경로에는 변경 없음
|
||||
- 새로운 config 키 도입 없음
|
||||
- 의미적 변경 없음 — 시스템이 이미 자동으로 해석하던 동일한 값들
|
||||
- 완전한 하위 호환성: `loadConfig()`는 이전 부분 형식(기존 프로젝트)과
|
||||
새로운 전체 형식을 모두 계속 처리합니다.
|
||||
- 멱등성: `config-new-project`를 두 번 호출해도 안전합니다.
|
||||
- 새로운 사용자 대면 플래그 없음
|
||||
|
||||
**이것이 발견성을 개선하는 이유:**
|
||||
처음으로 `.planning/config.json`을 여는 개발자는 이제
|
||||
`git.branching_strategy: "none"`을 확인하고 GSD 소스를 읽지 않고도
|
||||
브랜칭이 가능하고 구성 가능하다는 것을 즉시 이해할 수 있습니다.
|
||||
```
|
||||
@@ -0,0 +1,185 @@
|
||||
# 멀티 프로젝트 워크스페이스 (`/gsd:new-workspace`)
|
||||
|
||||
**Issue:** #1241
|
||||
**Date:** 2026-03-20
|
||||
**Status:** Approved
|
||||
|
||||
## 문제
|
||||
|
||||
GSD는 작업 디렉토리당 하나의 `.planning/` 디렉토리에 종속되어 있습니다. 20개 이상의 하위 저장소가 있는 모노저장소 스타일 설정에서 여러 독립 프로젝트를 사용하는 사용자나 동일한 저장소에서 피처 브랜치 격리가 필요한 사용자는 수동 클론 및 상태 관리 없이 병렬 GSD 세션을 실행할 수 없습니다.
|
||||
|
||||
## 해결책
|
||||
|
||||
**물리적 워크스페이스 디렉토리**를 생성, 나열, 제거하는 세 가지 새로운 명령어입니다 — 각각은 저장소 복사본(git worktree 또는 클론)과 독립적인 `.planning/` 디렉토리를 포함합니다.
|
||||
|
||||
이것은 두 가지 사용 사례를 다룹니다:
|
||||
- **멀티 저장소 오케스트레이션(A):** 상위 디렉토리에서 여러 저장소에 걸친 워크스페이스
|
||||
- **피처 브랜치 격리(B):** 현재 저장소의 worktree를 포함하는 워크스페이스(`--repos .`인 경우 A의 특수 케이스)
|
||||
|
||||
## 명령어
|
||||
|
||||
### `/gsd:new-workspace`
|
||||
|
||||
저장소 복사본과 자체 `.planning/`이 있는 워크스페이스 디렉토리를 생성합니다.
|
||||
|
||||
```
|
||||
/gsd:new-workspace --name feature-b --repos hr-ui,ZeymoAPI --path ~/workspaces/feature-b
|
||||
/gsd:new-workspace --name feature-b --repos . --strategy worktree # 동일 저장소 격리
|
||||
```
|
||||
|
||||
**인수.**
|
||||
|
||||
| 플래그 | 필수 여부 | 기본값 | 설명 |
|
||||
|------|----------|---------|-------------|
|
||||
| `--name` | 예 | — | 워크스페이스 이름 |
|
||||
| `--repos` | 아니오 | 대화형 선택 | 쉼표로 구분된 저장소 경로 또는 이름 |
|
||||
| `--path` | 아니오 | `~/gsd-workspaces/<name>` | 대상 디렉토리 |
|
||||
| `--strategy` | 아니오 | `worktree` | `worktree`(가볍고 .git 공유) 또는 `clone`(완전히 독립) |
|
||||
| `--branch` | 아니오 | `workspace/<name>` | 체크아웃할 브랜치 |
|
||||
| `--auto` | 아니오 | false | 대화형 질문 건너뛰고 기본값 사용 |
|
||||
|
||||
### `/gsd:list-workspaces`
|
||||
|
||||
워크스페이스 매니페스트를 위해 `~/gsd-workspaces/*/WORKSPACE.md`를 스캔합니다. 이름, 경로, 저장소 수, GSD 상태(PROJECT.md 존재 여부, 현재 페이즈)가 있는 표를 표시합니다.
|
||||
|
||||
### `/gsd:remove-workspace`
|
||||
|
||||
확인 후 워크스페이스 디렉토리를 제거합니다. worktree 전략의 경우 먼저 각 멤버 저장소에 대해 `git worktree remove`를 실행합니다. 저장소에 커밋되지 않은 변경사항이 있으면 거부합니다.
|
||||
|
||||
## 디렉토리 구조
|
||||
|
||||
```
|
||||
~/gsd-workspaces/feature-b/ # 워크스페이스 루트
|
||||
├── WORKSPACE.md # 매니페스트
|
||||
├── .planning/ # 독립적인 GSD 계획 디렉토리
|
||||
│ ├── PROJECT.md # (사용자가 /gsd:new-project를 실행한 경우)
|
||||
│ ├── STATE.md
|
||||
│ └── config.json
|
||||
├── hr-ui/ # 소스 저장소의 git worktree
|
||||
│ └── (workspace/feature-b 브랜치의 저장소 내용)
|
||||
└── ZeymoAPI/ # 소스 저장소의 git worktree
|
||||
└── (workspace/feature-b 브랜치의 저장소 내용)
|
||||
```
|
||||
|
||||
주요 속성.
|
||||
- `.planning/`은 개별 저장소 내부가 아닌 워크스페이스 루트에 있습니다.
|
||||
- 각 저장소는 워크스페이스 루트 아래의 피어 디렉토리입니다.
|
||||
- `WORKSPACE.md`는 루트에 있는 유일한 GSD 전용 파일입니다(`.planning/` 외).
|
||||
- `--strategy clone`의 경우 동일한 구조이지만 저장소는 전체 클론입니다.
|
||||
|
||||
## WORKSPACE.md 형식
|
||||
|
||||
```markdown
|
||||
# Workspace: feature-b
|
||||
|
||||
Created: 2026-03-20
|
||||
Strategy: worktree
|
||||
|
||||
## Member Repos
|
||||
|
||||
| Repo | Source | Branch | Strategy |
|
||||
|------|--------|--------|----------|
|
||||
| hr-ui | /root/source/repos/hr-ui | workspace/feature-b | worktree |
|
||||
| ZeymoAPI | /root/source/repos/ZeymoAPI | workspace/feature-b | worktree |
|
||||
|
||||
## Notes
|
||||
|
||||
[사용자가 이 워크스페이스의 목적에 대한 컨텍스트를 추가할 수 있습니다]
|
||||
```
|
||||
|
||||
## 워크플로우
|
||||
|
||||
### `/gsd:new-workspace` 워크플로우 단계
|
||||
|
||||
1. **설정** — `init new-workspace` 호출, JSON 컨텍스트 파싱
|
||||
2. **입력 수집** — `--name`/`--repos`/`--path`가 제공되지 않으면 대화형으로 질문합니다. 저장소의 경우 cwd의 하위 `.git` 디렉토리를 옵션으로 표시합니다.
|
||||
3. **유효성 검사** — 대상 경로가 존재하지 않거나 비어 있음. 소스 저장소가 존재하고 git 저장소임.
|
||||
4. **워크스페이스 디렉토리 생성** — `mkdir -p <path>`
|
||||
5. **저장소 복사** — 각 저장소에 대해.
|
||||
- Worktree: `git worktree add <workspace>/<repo-name> -b workspace/<name>`
|
||||
- Clone: `git clone <source> <workspace>/<repo-name>`
|
||||
6. **WORKSPACE.md 작성** — 소스 경로, 전략, 브랜치가 있는 매니페스트
|
||||
7. **.planning/ 초기화** — `mkdir -p <workspace>/.planning`
|
||||
8. **/gsd:new-project 제안** — 새 워크스페이스에서 프로젝트 초기화를 실행할지 사용자에게 질문
|
||||
9. **커밋** — commit_docs가 활성화된 경우 WORKSPACE.md의 원자적 커밋
|
||||
10. **완료** — 워크스페이스 경로와 다음 단계 출력
|
||||
|
||||
### Init 함수(`cmdInitNewWorkspace`)
|
||||
|
||||
다음을 감지합니다.
|
||||
- cwd의 하위 git 저장소(대화형 저장소 선택을 위해)
|
||||
- 대상 경로가 이미 존재하는지 여부
|
||||
- 소스 저장소에 커밋되지 않은 변경사항이 있는지 여부
|
||||
- `git worktree`를 사용할 수 있는지 여부
|
||||
- 기본 워크스페이스 기본 디렉토리(`~/gsd-workspaces/`)
|
||||
|
||||
워크플로우 게이팅을 위한 플래그가 포함된 JSON을 반환합니다.
|
||||
|
||||
## 오류 처리
|
||||
|
||||
### 유효성 검사 오류(생성 차단)
|
||||
|
||||
- **대상 경로가 존재하고 비어 있지 않음** — 다른 이름/경로 선택 제안과 함께 오류
|
||||
- **소스 저장소 경로가 존재하지 않거나 git 저장소가 아님** — 실패한 저장소를 나열하는 오류
|
||||
- **`git worktree add` 실패**(예: 브랜치가 이미 존재) — `workspace/<name>-<timestamp>` 브랜치로 폴백, 그것도 실패하면 오류
|
||||
|
||||
### 정상적인 처리
|
||||
|
||||
- **소스 저장소에 커밋되지 않은 변경사항** — 경고하되 허용(worktree는 브랜치를 새로 체크아웃하며 작업 디렉토리 상태를 복사하지 않음)
|
||||
- **멀티 저장소 워크스페이스에서 부분 실패** — 성공한 저장소로 워크스페이스를 생성하고 실패를 보고하며 부분적인 WORKSPACE.md 작성
|
||||
- **`--repos .`(현재 저장소, 케이스 B)** — 디렉토리 이름 또는 git remote에서 저장소 이름 감지, 하위 디렉토리 이름으로 사용
|
||||
|
||||
### Remove-Workspace 안전성
|
||||
|
||||
- **워크스페이스 저장소에 커밋되지 않은 변경사항** — 제거를 거부하고 변경사항이 있는 저장소 출력
|
||||
- **Worktree 제거 실패**(예: 소스 저장소가 삭제됨) — 경고하고 디렉토리 정리를 계속 진행
|
||||
- **확인** — 워크스페이스 이름을 직접 입력하는 명시적 확인 필요
|
||||
|
||||
### List-Workspaces 엣지 케이스
|
||||
|
||||
- **`~/gsd-workspaces/`가 존재하지 않음** — "No workspaces found"
|
||||
- **WORKSPACE.md는 있지만 내부 저장소가 사라짐** — 워크스페이스를 표시하되 저장소를 누락으로 표시
|
||||
|
||||
## 테스팅
|
||||
|
||||
### 단위 테스트(`tests/workspace.test.cjs`)
|
||||
|
||||
1. `cmdInitNewWorkspace`가 올바른 JSON 반환 — 하위 git 저장소 감지, 대상 경로 유효성 검사, git worktree 가용성 감지
|
||||
2. WORKSPACE.md 생성 — 저장소 표, 전략, 날짜가 있는 올바른 형식
|
||||
3. 저장소 발견 — cwd 하위 항목에서 `.git` 디렉토리 식별, git 디렉토리가 아닌 디렉토리와 파일 건너뜀
|
||||
4. 유효성 검사 — 비어 있지 않은 기존 대상 경로 거부, git이 아닌 소스 경로 거부
|
||||
|
||||
### 통합 테스트(동일 파일)
|
||||
|
||||
5. Worktree 생성 — 워크스페이스 생성, 저장소 디렉토리가 유효한 git worktree인지 확인
|
||||
6. Clone 생성 — 워크스페이스 생성, 저장소가 독립적인 클론인지 확인
|
||||
7. 워크스페이스 나열 — 두 개의 워크스페이스 생성, 나열 출력에 둘 다 포함되는지 확인
|
||||
8. 워크스페이스 제거 — worktree로 워크스페이스 생성, 제거, 정리 확인
|
||||
9. 부분 실패 — 유효한 저장소 하나 + 유효하지 않은 경로 하나, 유효한 저장소만으로 워크스페이스 생성
|
||||
|
||||
모든 테스트는 임시 디렉토리를 사용하고 완료 후 정리합니다. 기존 `node:test` + `node:assert` 패턴을 따릅니다.
|
||||
|
||||
## 구현 파일
|
||||
|
||||
| 컴포넌트 | 경로 |
|
||||
|-----------|------|
|
||||
| 명령어: new-workspace | `commands/gsd/new-workspace.md` |
|
||||
| 명령어: list-workspaces | `commands/gsd/list-workspaces.md` |
|
||||
| 명령어: remove-workspace | `commands/gsd/remove-workspace.md` |
|
||||
| 워크플로우: new-workspace | `get-shit-done/workflows/new-workspace.md` |
|
||||
| 워크플로우: list-workspaces | `get-shit-done/workflows/list-workspaces.md` |
|
||||
| 워크플로우: remove-workspace | `get-shit-done/workflows/remove-workspace.md` |
|
||||
| Init 함수 | `get-shit-done/bin/lib/init.cjs`(`cmdInitNewWorkspace`, `cmdInitListWorkspaces`, `cmdInitRemoveWorkspace` 추가) |
|
||||
| 라우팅 | `get-shit-done/bin/gsd-tools.cjs`(init switch에 case 추가) |
|
||||
| 테스트 | `tests/workspace.test.cjs` |
|
||||
|
||||
## 설계 결정
|
||||
|
||||
| 결정 | 근거 |
|
||||
|----------|-----------|
|
||||
| 논리적 레지스트리 대신 물리적 디렉토리 | 파일 시스템이 진실 공급원 — GSD의 기존 cwd 기반 감지 패턴과 일치 |
|
||||
| 기본 전략으로 Worktree | 가볍고(.git 오브젝트 공유) 생성이 빠르며 정리가 쉬움 |
|
||||
| 워크스페이스 루트에 `.planning/` | 개별 저장소 계획으로부터 완전한 격리를 제공. 각 워크스페이스는 독립적인 GSD 프로젝트 |
|
||||
| 중앙 레지스트리 없음 | 상태 드리프트 방지. `list-workspaces`가 파일 시스템을 직접 스캔 |
|
||||
| A의 특수 케이스로서 케이스 B | `--repos .`는 동일한 메커니즘을 재사용하므로 특별한 피처 브랜치 코드 불필요 |
|
||||
| 기본 경로 `~/gsd-workspaces/<name>` | `list-workspaces`가 스캔할 예측 가능한 위치, 소스 저장소 외부에 워크스페이스 유지 |
|
||||
65
docs/ko-KR/workflow-discuss-mode.md
Normal file
65
docs/ko-KR/workflow-discuss-mode.md
Normal file
@@ -0,0 +1,65 @@
|
||||
# Discuss 모드: Assumptions vs Interview
|
||||
|
||||
GSD의 discuss 단계는 플래닝 전에 구현 컨텍스트를 수집하는 두 가지 모드를 제공합니다.
|
||||
|
||||
## 모드
|
||||
|
||||
### `discuss` (기본값)
|
||||
|
||||
기존의 인터뷰 방식 흐름입니다. Claude가 단계에서 불명확한 영역을 파악하고 선택지를 제시한 뒤 영역당 약 4개의 질문을 합니다. 다음 상황에 적합합니다.
|
||||
|
||||
- 코드베이스가 새로운 초기 단계
|
||||
- 사용자가 사전에 강한 의견을 표현하고 싶은 단계
|
||||
- 안내된 대화식 컨텍스트 수집을 선호하는 사용자
|
||||
|
||||
### `assumptions`
|
||||
|
||||
코드베이스 우선 방식의 흐름입니다. Claude가 서브에이전트를 통해 코드베이스를 깊이 분석하고 (관련 파일 5~15개 읽기) 근거가 있는 가정을 도출하여 확인 또는 수정을 위해 제시합니다. 다음 상황에 적합합니다.
|
||||
|
||||
- 명확한 패턴이 있는 기존 코드베이스
|
||||
- 인터뷰 질문이 당연하게 느껴지는 사용자
|
||||
- 빠른 컨텍스트 수집 (~15~20번 대신 ~2~4번의 상호작용)
|
||||
|
||||
## 설정
|
||||
|
||||
```bash
|
||||
# assumptions 모드 활성화
|
||||
gsd-tools config-set workflow.discuss_mode assumptions
|
||||
|
||||
# interview 모드로 전환
|
||||
gsd-tools config-set workflow.discuss_mode discuss
|
||||
```
|
||||
|
||||
설정은 프로젝트별로 적용되며 `.planning/config.json`에 저장됩니다.
|
||||
|
||||
## Assumptions 모드 동작 방식
|
||||
|
||||
1. **Init** — discuss 모드와 동일 (이전 컨텍스트 로드, 코드베이스 스카우트, todo 확인)
|
||||
2. **심층 분석** — explore 서브에이전트가 단계와 관련된 코드베이스 파일 5~15개를 읽음
|
||||
3. **가정 제시** — 각 가정에는 다음이 포함됩니다.
|
||||
- Claude가 할 작업과 그 이유 (파일 경로 인용)
|
||||
- 가정이 틀렸을 때 발생하는 문제
|
||||
- 신뢰도 수준 (Confident / Likely / Unclear)
|
||||
4. **확인 또는 수정** — 사용자가 가정을 검토하고 변경이 필요한 항목을 선택
|
||||
5. **CONTEXT.md 작성** — discuss 모드와 동일한 출력 형식
|
||||
|
||||
## 플래그 호환성
|
||||
|
||||
| 플래그 | `discuss` 모드 | `assumptions` 모드 |
|
||||
|--------|----------------|-------------------|
|
||||
| `--auto` | 권장 답변을 자동으로 선택 | 확인 단계를 건너뛰고 Unclear 항목을 자동으로 처리 |
|
||||
| `--batch` | 질문을 배치로 묶어서 처리 | 해당 없음 (수정 사항이 이미 배치로 처리됨) |
|
||||
| `--text` | 일반 텍스트 질문 (원격 세션) | 일반 텍스트 질문 (원격 세션) |
|
||||
| `--analyze` | 질문별 트레이드오프 표 표시 | 해당 없음 (가정에 근거가 포함됨) |
|
||||
|
||||
## 출력
|
||||
|
||||
두 모드 모두 동일한 6개 섹션을 포함하는 CONTEXT.md를 생성합니다.
|
||||
- `<domain>` — 단계 범위
|
||||
- `<decisions>` — 확정된 구현 결정사항
|
||||
- `<canonical_refs>` — 하위 에이전트가 반드시 읽어야 할 스펙/문서
|
||||
- `<code_context>` — 재사용 가능한 자산, 패턴, 통합 지점
|
||||
- `<specifics>` — 사용자 참고 자료 및 선호사항
|
||||
- `<deferred>` — 향후 단계를 위해 기록된 아이디어
|
||||
|
||||
하위 에이전트(researcher, planner, checker)는 모드에 관계없이 동일하게 이 파일을 사용합니다.
|
||||
Reference in New Issue
Block a user