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

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

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

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

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

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

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

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

* docs: backfill changeset PR number (#605)

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

---------

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

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

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

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

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

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

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

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

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