docs: rebrand to GSD Core and restructure docs with Diataxis (#605)
* 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:
90
docs/ko-KR/explanation/context-engineering.md
Normal file
90
docs/ko-KR/explanation/context-engineering.md
Normal file
@@ -0,0 +1,90 @@
|
||||
# 컨텍스트 엔지니어링
|
||||
|
||||
> GSD Core가 존재하는 이유와 해결하고자 하는 문제.
|
||||
|
||||
---
|
||||
|
||||
## 문제: 컨텍스트 부패
|
||||
|
||||
모든 AI 코딩 세션은 새롭게 시작된다. 모델은 질문을 읽고, 추론하고, 답변을 돌려준다. 그러나 하나의 세션이 단 한 번의 교환으로 끝나는 경우는 드물다. 추가 질문을 던지고, 오류 메시지를 붙여넣고, 코드를 반복적으로 개선하며, 모델이 엉뚱한 방향으로 흘러갈 때 방향을 바로잡는다. 각 대화 차례마다 토큰이 컨텍스트 윈도우에 쌓인다 — 모델이 한 번에 "볼 수" 있는 유한한 텍스트 버퍼.
|
||||
|
||||
이 윈도우가 채워지면 미묘한 일이 벌어진다. 모델은 요란하게 실패하지 않는다. 계속해서 답변을 생성한다. 하지만 답변의 품질은 서서히 저하된다. 초반에 주어진 지시 사항이 모델이 집중할 수 있는 범위의 가장자리로 밀려난다. 처음 몇 번의 교환에서 다뤘던 뉘앙스들 — 제시했던 제약 조건, 합의한 아키텍처, 언급했던 엣지 케이스들 — 이 이후에 쌓인 모든 내용과 주의를 경쟁하게 된다. 연구자들은 이를 **컨텍스트 부패(context rot)**라고 부른다.
|
||||
|
||||
컨텍스트 부패는 여러 형태로 나타난다.
|
||||
|
||||
- 모델이 이전에 인정했던 결정들을 모순되게 다루기 시작한다.
|
||||
- 코드 스타일이 세션 초반에 확립한 컨벤션에서 벗어난다.
|
||||
- 계획이 명확하게 명시되었지만 이제 깊이 묻혀버린 요구 사항들을 무시하기 시작한다.
|
||||
- 모델이 20개의 메시지 전에는 정확히 알고 있던 파일 이름이나 함수 시그니처를 환각으로 만들어낸다.
|
||||
|
||||
이것은 모델 버그가 아니다. 긴 시퀀스에서 트랜스포머 어텐션이 작동하는 방식의 근본적인 특성이다. 모델은 "잊어버리는" 것이 아니다 — 인간적 의미에서의 "기억"은 애초에 없었다. 유한한 윈도우 안에서 관련성에 가중치를 부여하고 있으며, 누적된 노이즈로 윈도우가 채워질수록 신호 대 잡음비가 저하된다.
|
||||
|
||||
단순한 대응책은 `/clear`로 세션을 초기화하는 것이다. 그러나 그러면 연속성을 잃는다. 컨텍스트를 다시 설명하고, 관련 파일을 다시 붙여넣고, 제약 조건을 다시 명시해야 한다. 세션이 사실상 제로부터 다시 시작된다.
|
||||
|
||||
---
|
||||
|
||||
## GSD Core의 답: 신선한 컨텍스트 서브에이전트
|
||||
|
||||
GSD Core의 핵심적인 통찰은 코딩 세션에서 이루어지는 작업의 *대부분*이 메인 컨텍스트에서 이루어질 필요가 없다는 것이다. 리서치, 계획 수립, 코드 작성, 검증은 각각 독립적이고 범위가 한정된 작업들이다. 각각을 깔끔하고 신중하게 범위가 지정된 컨텍스트 윈도우로 시작하는 전문화된 서브에이전트에게 넘기고 — 결과를 효율적으로 유지되는 얇은 오케스트레이터에게 보고할 수 있다.
|
||||
|
||||
이것은 컨텍스트 부패를 위한 임시방편이 아니다. 구조적인 해결책이다.
|
||||
|
||||
오케스트레이터 — 메인 세션 — 는 소스 파일을 직접 다루지 않는다. 에이전트를 생성하고, 결과를 수집하며, 공유 상태를 업데이트하고, 다음 단계로 라우팅한다. 오케스트레이터가 스스로 하는 작업이 매우 적기 때문에 컨텍스트 윈도우가 느리고 예측 가능하게 증가한다. 무거운 작업은 각각 신선하게 시작하고, 자신의 작업에 필요한 정확한 컨텍스트만 받고, 완료 시 종료하는 에이전트에서 수행된다.
|
||||
|
||||
실제로 어떤 의미인지 생각해보자. `/gsd-plan-phase`를 실행하면 오케스트레이터는:
|
||||
|
||||
1. 압축된 JSON 컨텍스트 페이로드(프로젝트 요약, 단계 목표, 관련 설정)를 로드한다.
|
||||
2. 200k 토큰의 깨끗한 윈도우로 리서처 에이전트를 생성한다.
|
||||
3. 리서치 출력물과 단계 요구 사항을 가진 플래너 에이전트를 생성한다.
|
||||
4. 실행 전에 계획을 검증하는 계획 검사기 에이전트를 생성한다.
|
||||
|
||||
각 에이전트는 세션의 누적된 이력으로 부담받지 않고, 최대 능력으로 작동한다. 플래너가 `PLAN.md` 파일들을 `.planning/phases/`에 작성할 때, 그 출력물은 내구성 있는 결과물이 된다 — 공유 컨텍스트 윈도우 속에서 깨지기 쉬운 기억이 아니라.
|
||||
|
||||
---
|
||||
|
||||
## 명세 주도 개발과 메타 프롬프팅
|
||||
|
||||
컨텍스트 엔지니어링만으로는 충분하지 않다. 에이전트가 신선하게 시작하더라도 모호한 지시 사항을 받으면 모호한 결과물을 생성한다. GSD Core는 신선한 컨텍스트 서브에이전트와 두 가지 보완적인 원칙을 함께 사용한다.
|
||||
|
||||
**명세 주도 개발**은 모든 단계가 실행 전에 구조화된 결과물을 생성한다는 것을 의미한다. `CONTEXT.md`는 논의 단계의 구현 결정 사항들을 캡처한다. `RESEARCH.md`는 리서처가 발견한 내용을 기록한다. `PLAN.md`는 명시적인 수락 기준을 가진 개별적인 의존성 순서의 작업들로 작업을 분해한다. 실행 에이전트가 파일에 손을 대는 시점에는 긴 대화의 재해석이 아닌 정확한 명세를 가지고 있다.
|
||||
|
||||
**메타 프롬프팅**은 에이전트 정의 자체가 애드혹 지시 사항이 아닌 신중하게 설계된 프롬프트라는 것을 의미한다. `get-shit-done/workflows/`와 `agents/`의 파일들은 작업의 범위를 지정하는 방법, 무엇을 검증해야 하는지, 언제 사람에게 체크포인트를 요청해야 하는지에 대한 소중한 지식을 담고 있다. 사용자는 매 세션마다 이 지식을 다시 설명할 필요가 없다; 그것은 시스템 자체의 프롬프트에 이미 내장되어 있다.
|
||||
|
||||
이 조합은 의도적이다. 신선한 컨텍스트는 각 에이전트가 명확하게 추론하도록 보장한다. 명세 주도 결과물은 각 에이전트가 *올바른* 것에 대해 추론하도록 보장한다. 메타 프롬프팅은 각 에이전트가 *어떻게* 잘 추론해야 하는지 알도록 보장한다.
|
||||
|
||||
---
|
||||
|
||||
## `.planning/`의 역할
|
||||
|
||||
컨텍스트 엔지니어링은 지식이 컨텍스트 리셋을 통해 살아남아야 한다는 것을 요구한다. GSD Core는 이를 위해 파일 시스템을 사용한다. 모든 의미 있는 출력물은 사람이 읽을 수 있는 마크다운 또는 JSON으로 `.planning/`에 작성된다. 이것은 다음을 의미한다.
|
||||
|
||||
- 세션을 다시 시작하거나 모델이 충돌해도 작업이 손실되지 않는다.
|
||||
- 모든 이후 에이전트는 공유 대화 이력에 의존하지 않고 이전 결과물을 직접 읽을 수 있다.
|
||||
- 계획 결과물을 git에 검사, 편집 또는 커밋할 수 있다 — 데이터베이스의 불투명한 상태가 아닌 평문 텍스트이다.
|
||||
|
||||
`STATE.md`는 이 시스템의 중추이다. 프로젝트의 현재 위치(어느 마일스톤, 어느 단계, 어느 계획이 완료되었는지), 활성 결정 사항과 장애물, 진행 지표를 기록한다. 모든 워크플로우가 시작될 때 `STATE.md`를 읽어 방향을 잡는다. 모든 워크플로우가 의미 있는 단계를 완료할 때 `STATE.md`에 다시 기록한다. 에이전트는 기억에 의존하지 않는다; 파일에 의존한다.
|
||||
|
||||
---
|
||||
|
||||
## 트레이드오프
|
||||
|
||||
여기서 트레이드오프에 대한 솔직함이 중요하다.
|
||||
|
||||
**오버헤드.** 단계 루프는 실제 마찰을 야기한다. `/gsd-discuss-phase`, `/gsd-plan-phase`, `/gsd-execute-phase`를 별도의 단계로 실행하는 것은 단순 세션에 "이 기능을 작성해줘"라고 입력하는 것보다 더 많은 경과 시간이 걸린다. 작고 잘 이해된 변경의 경우 그 오버헤드는 정당화되지 않는다.
|
||||
|
||||
**지연.** 신선한 컨텍스트로 여러 서브에이전트를 생성하는 것은 단일 인-컨텍스트 편집보다 느리다. 리서치, 계획 수립, 실행 각각에 왕복 비용이 발생한다.
|
||||
|
||||
**단순한 작업에 대한 의례.** 변수 이름을 바꾸거나, 오타를 수정하거나, 누락된 임포트를 추가해야 할 때 단계 루프는 과도하다. GSD Core는 전체 단계를 필요로 하지 않는 임시 작업을 위해 `/gsd-quick`과 `/gsd-fast`를 제공한다. [빠른 작업 처리하기](../how-to/handle-quick-and-fast-tasks.md)를 참조하라.
|
||||
|
||||
단계 루프는 컨텍스트 부패가 실제 위험인 만큼 복잡한 작업 — 다중 파일 기능, 횡단 관심사 리팩터링, 몇 시간 또는 여러 세션에 걸친 작업 — 에서 그 가치를 발휘한다. 그 외의 경우에는 더 가벼운 기본 도구를 사용하라.
|
||||
|
||||
유용한 경험 법칙: 단일 짧은 프롬프트로 완전히 명시되고 더 이상의 설명 없이 에이전트 한 번의 작업으로 완료될 수 있다면, 단계 루프를 건너뛰어라. 리서치가 필요하거나, 최근에 읽지 않은 파일이 포함되거나, 아직 결정되지 않은 사항에 의존한다면, 단계 루프가 보호해준다.
|
||||
|
||||
---
|
||||
|
||||
## Related
|
||||
|
||||
- [단계 루프](the-phase-loop.md) — 논의 → 계획 → 실행 → 검증 → 출시 사이클이 컨텍스트 엔지니어링을 실천에 옮기는 방법
|
||||
- [다중 에이전트 오케스트레이션](multi-agent-orchestration.md) — 서브에이전트가 생성, 범위 지정, 조율되는 방법
|
||||
- [아키텍처](../ARCHITECTURE.md) — 시스템 아키텍처, 에이전트 모델, 데이터 흐름
|
||||
- [문서 인덱스](../README.md)
|
||||
151
docs/ko-KR/explanation/multi-agent-orchestration.md
Normal file
151
docs/ko-KR/explanation/multi-agent-orchestration.md
Normal file
@@ -0,0 +1,151 @@
|
||||
# GSD Core의 다중 에이전트 오케스트레이션
|
||||
|
||||
> **설명** — 이 문서는 GSD Core가 다중 에이전트 오케스트레이션을 중심으로
|
||||
> 설계된 *이유*와 *구성 요소들이 어떻게 맞물리는지*를 설명한다. 단계별
|
||||
> 가이드가 아니다. 설정에 대해서는
|
||||
> [모델 프로필 설정](../how-to/configure-model-profiles.md)과
|
||||
> [설정 레퍼런스](../CONFIGURATION.md)를 참조하라. 전체 에이전트 목록은
|
||||
> [인벤토리](../INVENTORY.md)를 참조하라.
|
||||
|
||||
---
|
||||
|
||||
## 이 설계가 해결하는 문제
|
||||
|
||||
AI 코딩 에이전트는 저하된다. 모델이 나빠지기 때문이 아니라 *컨텍스트 윈도우가 채워지기* 때문이다. 대화가 길어질수록 초반의 결정들과 코드가 중간 단계들의 노이즈에 밀려나거나 희석된다. 복잡한 작업에서 다섯 번째 파일을 작성할 때쯤 에이전트는 첫 번째 메시지에서 명시된 제약 조건을 이미 잊었을 수도 있다. 이를 *컨텍스트 부패*라고 부르기도 한다.
|
||||
|
||||
GSD Core의 다중 에이전트 설계는 그 문제에 대한 직접적인 대응이다. 하나의 장시간 실행 에이전트가 전체 세션을 담당하는 대신, 얇은 오케스트레이터가 **신선한 200K 토큰 컨텍스트 윈도우**와 *자신의 특정 작업을 수행하는 데 필요한 결과물만* 갖고 시작하는 단수명 전문화 에이전트들을 생성한다. 오케스트레이터 자신은 절대 무거운 작업을 하지 않는다; 컨텍스트를 로드하고, 적합한 에이전트를 생성하고, 결과를 수집하고, `.planning/`의 공유 상태를 업데이트한다.
|
||||
|
||||
---
|
||||
|
||||
## 오케스트레이터 → 에이전트 패턴
|
||||
|
||||
`get-shit-done/workflows/`의 모든 워크플로우는 동일한 형태를 따른다:
|
||||
|
||||
```text
|
||||
오케스트레이터 (워크플로우 .md 파일)
|
||||
│
|
||||
├── 컨텍스트 로드
|
||||
│ gsd-tools.cjs init <workflow> <phase>
|
||||
│ → JSON: 프로젝트 정보, 설정, 상태, 단계 상세
|
||||
│
|
||||
├── 모델 해결
|
||||
│ gsd-tools.cjs resolve-model <agent-name>
|
||||
│ → opus | sonnet | haiku | inherit
|
||||
│
|
||||
├── 전문화 에이전트 생성 (Task/SubAgent 호출)
|
||||
│ ├── 에이전트 정의 (agents/*.md)
|
||||
│ ├── 컨텍스트 페이로드 (init JSON)
|
||||
│ ├── 모델 할당
|
||||
│ └── 도구 권한
|
||||
│
|
||||
├── 결과 수집
|
||||
│
|
||||
└── 상태 업데이트
|
||||
gsd-tools.cjs state update / state patch / state advance-plan
|
||||
```
|
||||
|
||||
오케스트레이터는 의도적으로 얇다. 도메인에 대해 추론하지 않고, 코드를 작성하지 않으며, 다음 단계로 라우팅하는 것 이상으로 결과를 해석하지 않는다. 그 경계는 각 계층의 책임을 명확하게 유지하고 오케스트레이터의 컨텍스트가 도메인 노이즈를 축적하는 것을 방지한다.
|
||||
|
||||
### 에이전트 목록
|
||||
|
||||
GSD Core의 에이전트들은 리서치 → 계획 → 실행 → 검증 파이프라인에 매핑되는 기능 범주로 나뉜다:
|
||||
|
||||
| 범주 | 에이전트 | 일반적인 병렬성 |
|
||||
|---|---|---|
|
||||
| 리서처 | `gsd-project-researcher`, `gsd-phase-researcher`, `gsd-ui-researcher`, `gsd-advisor-researcher` | 4개 병렬 (스택, 기능, 아키텍처, 함정) |
|
||||
| 합성기 | `gsd-research-synthesizer` | 리서처 완료 후 순차적 |
|
||||
| 플래너 | `gsd-planner`, `gsd-roadmapper` | 순차적 |
|
||||
| 검사기 | `gsd-plan-checker`, `gsd-integration-checker`, `gsd-ui-checker`, `gsd-nyquist-auditor` | 순차적, 최대 3번 수정 반복 |
|
||||
| 실행기 | `gsd-executor` | 웨이브 내 병렬, 웨이브 간 순차적 |
|
||||
| 검증기 | `gsd-verifier` | 모든 실행기 완료 후 순차적 |
|
||||
| 매퍼 | `gsd-codebase-mapper` | 4개 병렬 하위 프로브 |
|
||||
| 감사기 | `gsd-ui-auditor`, `gsd-security-auditor` | 순차적 |
|
||||
|
||||
각 에이전트 정의(`agents/*.md`)는 허용된 도구 접근, 목적, 터미널 출력 색상을 선언한다. 파일을 읽고 단일 출력 문서를 작성하기만 하면 되는 에이전트는 정확히 그런 권한만 받는다 — Bash 실행 없음, 광범위한 상태 접근 없음. 그 제약은 의도적이다: 에이전트가 예상치 못하게 행동할 경우 영향 범위를 작게 유지한다.
|
||||
|
||||
전체 31개 에이전트 목록은 [인벤토리](../INVENTORY.md#agents-31-shipped)를 참조하라.
|
||||
|
||||
---
|
||||
|
||||
## 웨이브 기반 병렬 실행
|
||||
|
||||
다중 에이전트 설계의 가장 눈에 띄는 표현은 `/gsd-execute-phase`가 서로 의존관계가 있는 계획들의 집합을 처리하는 방식이다.
|
||||
|
||||
실행기를 생성하기 전에 오케스트레이터는 **웨이브 분석**을 수행한다: 각 `PLAN.md` 파일의 의존성 선언을 읽고 계획들을 웨이브로 그룹화한다. 선언된 의존성이 없는 계획들은 웨이브 1을 형성하고 병렬로 실행된다. 웨이브 1에 의존하는 계획들은 웨이브 2를 형성하고, 계속해서 이어진다.
|
||||
|
||||
```text
|
||||
계획 01 (의존성 없음) ─┐
|
||||
계획 02 (의존성 없음) ─┤─── 웨이브 1 (병렬)
|
||||
계획 03 (의존: 01) ─┤─── 웨이브 2 (웨이브 1 대기)
|
||||
계획 04 (의존: 02) ─┘
|
||||
계획 05 (의존: 03, 04) ─── 웨이브 3 (웨이브 2 대기)
|
||||
```
|
||||
|
||||
웨이브 내 각 실행기는:
|
||||
|
||||
- 신선한 컨텍스트 윈도우(200K 토큰, 또는 지원 모델에서 최대 1M)를 받는다
|
||||
- 담당하는 특정 `PLAN.md`를 받는다
|
||||
- 프로젝트 컨텍스트(`PROJECT.md`, `STATE.md`)를 받는다
|
||||
- 단계 컨텍스트(가용한 경우 `CONTEXT.md`, `RESEARCH.md`)를 받는다
|
||||
- 완료 시 원자적 git 커밋을 생성한다
|
||||
- 만들어진 것을 설명하는 `SUMMARY.md`를 작성한다
|
||||
|
||||
웨이브의 모든 실행기가 완료된 후, 오케스트레이터는 전체 웨이브에 대해 한 번 사전 커밋 훅을 실행한다. 실행기는 여러 에이전트가 병렬로 커밋할 때의 빌드 잠금 경합(예: Rust 프로젝트의 Cargo 잠금 충돌)을 방지하기 위해 `--no-verify`로 커밋한다. 따라서 훅은 커밋당 한 번이 아닌 웨이브당 한 번 실행된다.
|
||||
|
||||
### 병렬 커밋 안전성
|
||||
|
||||
여러 실행기가 동시에 실행될 때 쓰기 충돌을 방지하는 두 가지 메커니즘이 있다:
|
||||
|
||||
1. **`STATE.md`에 대한 원자적 잠금** — `STATE.md`에 대한 모든 쓰기는 `O_EXCL` 원자적 생성을 사용하는 잠금파일(`STATE.md.lock`)을 사용한다. 이는 두 에이전트가 각각 파일을 읽고, 서로 다른 필드를 수정하고, 나중에 쓰는 쪽이 먼저 쓴 쪽의 변경 사항을 덮어쓰는 읽기-수정-쓰기 경합 조건을 방지한다. 오래된 잠금(10초 이상)은 자동으로 지워진다.
|
||||
|
||||
2. **웨이브당 훅 실행** — 각 실행기가 사전 커밋 훅을 독립적으로 실행하는 대신(공유 빌드 결과물에 파일 수준 경합을 유발할 수 있음), 오케스트레이터는 모든 웨이브가 완료된 후 한 번 `git hook run pre-commit`을 실행한다.
|
||||
|
||||
---
|
||||
|
||||
## 대형 윈도우 모델을 위한 적응형 컨텍스트 보강
|
||||
|
||||
표준 200K 컨텍스트 윈도우는 실행기가 단일 집중된 계획을 구현하기에 충분하다. 구성된 `context_window`가 500K 토큰 이상인 경우(예: Opus 4.6 또는 Sonnet 4.6을 1M 클래스 모드로 사용할 때), 오케스트레이터는 자동으로 표준 윈도우에 들어가지 않는 추가 컨텍스트로 서브에이전트 프롬프트를 보강한다:
|
||||
|
||||
- **실행기 에이전트**는 이전 웨이브의 `SUMMARY.md` 파일들과 단계 `CONTEXT.md`/`RESEARCH.md`를 받아 단계 내 교차 계획 인식을 갖는다
|
||||
- **검증기 에이전트**는 모든 `PLAN.md`, `SUMMARY.md`, `CONTEXT.md` 파일들과 `REQUIREMENTS.md`를 받아 이력 인식 검증을 할 수 있다
|
||||
|
||||
이 보강은 `config.json`의 `context_window` 값에 조건부이다. 표준 윈도우 설정에서는 캐시 친화적 순서로 토큰 효율성을 최대화하는 잘린 버전의 프롬프트를 사용한다.
|
||||
|
||||
---
|
||||
|
||||
## 이 설계의 이유 — 컨텍스트 엔지니어링과의 연결
|
||||
|
||||
오케스트레이터 → 에이전트 패턴은 더 광범위한 *컨텍스트 엔지니어링* 접근 방식의 일부로서만 의미가 있다: AI 에이전트의 컨텍스트 윈도우에 들어가는 것이 모델 등급이나 프롬프트 품질만큼 중요하다는 아이디어. 전체 내용은 [컨텍스트 엔지니어링](context-engineering.md)을 참조하라.
|
||||
|
||||
다중 에이전트 오케스트레이션은 두 가지 방식으로 컨텍스트 엔지니어링을 구현한다:
|
||||
|
||||
**컨텍스트 격리.** 각 에이전트는 필요한 것만 받는다. 리서처는 프로젝트 설명과 도메인 질문들을 받는다; 전체 계획 이력은 받지 않는다. 검증기는 모든 계획과 요약을 받는다; 원시 리서치는 받지 않는다. 격리는 각 에이전트의 컨텍스트를 다른 파이프라인 단계들의 노이즈로 희석되지 않고 신호로 밀도 있게 유지한다.
|
||||
|
||||
**세션 간 컨텍스트 위생.** 모든 상태가 사람이 읽을 수 있는 마크다운과 JSON으로 `.planning/`에 저장되기 때문에(에이전트의 컨텍스트 윈도우가 아닌), GSD 워크플로우는 컨텍스트 리셋(`/clear`), 탭 전환, 며칠간의 휴식을 견뎌낸다. 다음 에이전트는 항상 긴 대화의 재구성된 기억이 아닌 영속적이고 검증된 결과물에서 시작한다.
|
||||
|
||||
---
|
||||
|
||||
## 트레이드오프
|
||||
|
||||
다중 에이전트 오케스트레이션은 비용이 없지 않다.
|
||||
|
||||
**조율 오버헤드.** 각 에이전트 생성은 왕복이다: 오케스트레이터가 프롬프트를 형식화하고, 컨텍스트를 넘기고, 서브에이전트가 완료될 때까지 기다리고(일반적으로 1-5분), 결과를 파싱해야 한다. 하나의 컨텍스트에서 작동하는 단일 능력 있는 에이전트는 단순한 작업에서 더 빨리 완료될 것이다. GSD는 의존성이 허용되는 모든 곳에서 병렬성을 기본값으로 만들어 이를 완화한다 — `plan-phase`의 네 리서처들은 순차적이 아닌 동시에 실행된다.
|
||||
|
||||
**실행 중 불투명성.** 서브에이전트가 실행되는 동안 그 작업은 부모 세션에서 보이지 않는다. 실시간 진행 스트림이 없다. 이것은 신선한 컨텍스트 설계의 의도적인 결과이다: 서브에이전트가 자체 컨텍스트 윈도우에서 작동하고 있다. 오케스트레이터는 생성 라인에 활성 표시를 보여줌으로써("서브에이전트에서 실행됨 — 반환될 때까지 출력 없음") 기대치를 설정한다.
|
||||
|
||||
**컨텍스트 스티칭 비용.** 각 에이전트에 적합한 결과물들을 패키징하려면 오케스트레이터가 컨텍스트 페이로드를 조립하고 전송하는 데 토큰을 소비해야 한다. 이것이 격리의 비용이다. `gsd-tools.cjs init` 핸들러는 완전성과 토큰 예산의 균형을 맞추는 JSON 페이로드를 생성하며, 반복 호출에서 캐시에 도달하도록 캐시 친화적 순서를 적용한다.
|
||||
|
||||
**모델 비용 증폭.** Opus 등급으로 다섯 개의 에이전트를 병렬로 실행하는 것은 하나를 실행하는 것보다 더 비용이 많이 든다. 모델 프로필 시스템(`model_profiles.md`, `model-profiles.cjs`에 의해 에이전트별로 해결됨)을 사용하면 덜 중요한 에이전트에 더 저렴한 등급을 할당할 수 있다. `dynamic_routing` 기능은 모든 에이전트를 더 저렴한 등급에서 시작하고 소프트 실패 시에만 에스컬레이션함으로써 비용을 더 줄여준다. 전체 옵션은 [설정](../CONFIGURATION.md)을 참조하라.
|
||||
|
||||
이런 비용의 대가로 이 설계는 *대형 단계에서의 일관된 품질*을 제공한다. 400줄 계획의 열 번째 파일을 작성하는 실행기는 컨텍스트가 신선하기 때문에 저하되지 않는다. 스무 개의 요구 사항을 확인하는 검증기는 처음 열 개를 잊지 않는다. 왜냐하면 대화 이력이 아닌 구조화된 입력으로 모두 받았기 때문이다.
|
||||
|
||||
---
|
||||
|
||||
## Related
|
||||
|
||||
- [컨텍스트 엔지니어링](context-engineering.md) — 이 설계에 동기를 부여하는 상위 원칙
|
||||
- [모델 프로필 설정](../how-to/configure-model-profiles.md) — 에이전트별로 모델 등급을 할당하는 방법
|
||||
- [설정 레퍼런스](../CONFIGURATION.md) — `models`, `model_overrides`, `dynamic_routing`, `context_window`를 포함한 전체 `config.json` 스키마
|
||||
- [인벤토리](../INVENTORY.md) — 권위 있는 에이전트 목록과 워크플로우 목록
|
||||
- [아키텍처](../ARCHITECTURE.md#agent-model) — 오케스트레이터 → 에이전트 패턴과 웨이브 실행 모델의 구현 수준 상세
|
||||
- [문서 인덱스](../README.md)
|
||||
123
docs/ko-KR/explanation/security-model.md
Normal file
123
docs/ko-KR/explanation/security-model.md
Normal file
@@ -0,0 +1,123 @@
|
||||
# GSD Core 보안 모델
|
||||
|
||||
> **설명** — 이 문서는 GSD Core가 현재의 보안 자세를 갖는 *이유*와 *계층들이
|
||||
> 어떻게 맞물리는지*를 설명한다. 모든 훅 파라미터에 대한 레퍼런스가 아니다.
|
||||
> `/gsd-secure-phase` 명령과 옵션에 대해서는 [명령어](../COMMANDS.md)를 참조하라.
|
||||
> 구현 수준의 훅 아키텍처에 대해서는
|
||||
> [아키텍처 § 훅 시스템](../ARCHITECTURE.md#hook-system)을 참조하라.
|
||||
> 조직 전반의 보안 기준선(스캐너 제어, 인시던트 체크리스트, 소유권 모델)에 대해서는
|
||||
> [SECURITY.md](../../../SECURITY.md)를 참조하라.
|
||||
|
||||
---
|
||||
|
||||
## AI 기반 개발에 전용 보안 자세가 필요한 이유
|
||||
|
||||
일반적인 코드 에디터는 사용자를 대신하여 임의의 패키지를 실행하지 않는다. GSD Core는 그렇게 한다. 리서치 → 계획 → 실행 파이프라인은 "패키지 이름 지정"에서 "`npm install <package>` 실행"까지, "계획 결과물 작성"에서 "해당 결과물을 LLM 시스템 프롬프트로 사용"까지의 전체 경로를 자동화한다. 각 자동화 단계는 루프에서 사람을 제거한다 — 그리고 각 제거는 잠재적인 공격 표면이다.
|
||||
|
||||
GSD Core의 보안 모델은 하나의 조직 원칙을 중심으로 구축된다: **심층 방어(defence in depth)**. 어떤 단일 제어도 완벽하다고 가정하지 않는다. 여러 겹치는 계층이 각각 고유한 종류의 위험을 줄이며, 함께 공격 표면을 완전히 제거하지는 않지만 악용하기 상당히 더 어렵게 만든다. 이 문서 끝의 솔직한 요약은 시스템이 방어할 수 없는 것을 설명한다.
|
||||
|
||||
---
|
||||
|
||||
## 계층 1 — 공급망 보호: 패키지 적법성 게이트
|
||||
|
||||
### 위협
|
||||
|
||||
AI 모델은 패키지 이름을 환각한다. 이것은 변두리 실패 모드가 아니다: 2025년 연구에서 AI가 생성한 패키지 참조의 약 20%가 합법적인 패키지와 대응되지 않는 환각된 이름으로 문서화되었다. 그 환각된 이름들의 일부 — 같은 연구에서 약 43% — 는 프롬프트 전반에 걸쳐 일관되게 반복되며, 이는 공격자가 AI 도구들이 일반적으로 생성하는 이름을 관찰하고 악의적인 설치 후 스크립트로 npm, PyPI, 또는 crates.io에 해당 이름들을 선점 등록할 수 있다는 것을 의미한다. 이 기법을 *슬롭스쿼팅(slopsquatting)*이라고 한다.
|
||||
|
||||
슬롭스쿼팅의 교활한 특성은 `npm view`를 통과하는 환각된 이름이 *합법적으로 보인다*는 것이다. 레지스트리 항목은 누군가가 이름을 등록했다는 것만 증명한다 — AI가 말한 것을 패키지가 한다거나, 합법적인 사용자가 있다거나, 설치 스크립트가 안전하다는 것은 증명하지 않는다. 게이트 없이는 환각된 이름이 GSD의 리서처 → 플래너 → 실행기 파이프라인을 통해 감지되지 않고 흐르다가 결국 사용자의 기계에서 `npm install <attacker-package>`로 실행될 것이다.
|
||||
|
||||
### 게이트 작동 방식
|
||||
|
||||
게이트는 세 가지 파이프라인 단계에 걸쳐 작동한다:
|
||||
|
||||
**리서치 단계.** `gsd-phase-researcher`가 외부 패키지를 추천할 때 각 패키지에 대해 `slopcheck install <pkgs> --json`을 실행한다. 결과는 `RESEARCH.md`의 `## Package Legitimacy Audit` 테이블에 작성된다. `[SLOP]`로 태그된 패키지들(높은 신뢰도의 환각 또는 공격자가 등록)은 파일이 저장되기 전에 **`RESEARCH.md`에서 완전히 제거된다**. 이런 패키지들은 절대 플래너에게 도달하지 않는다.
|
||||
|
||||
**계획 단계.** `gsd-planner`는 감사 테이블을 읽는다. `[SUS]`(의심스러움: 최근 등록, 낮은 다운로드 수, 소스 저장소 없음, 또는 인기 있는 패키지와 가까운 명명 패턴)나 `[ASSUMED]`(직접 레지스트리 검증이 아닌 WebSearch에서 출처)로 태그된 모든 패키지에 대해, 플래너는 설치 단계 전에 **`checkpoint:human-verify` 작업을 삽입한다**. 체크포인트에는 레지스트리 페이지로의 직접 링크와 살펴봐야 할 구체적인 항목들이 포함된다: 유지관리자 이력, 이슈 트래커 활동, 의심스러운 설치 스크립트의 부재.
|
||||
|
||||
**실행 단계.** 설치가 실패하면 `gsd-executor`는 **체크포인트를 표시하고 중지한다**. 대체 패키지 이름을 조용히 시도하지 않는다 — 그 자체가 악의적일 수 있다. 이는 실행기 동작의 명시적인 규칙이다(실행기 에이전트 정의의 RULE 3).
|
||||
|
||||
### WebSearch 패키지가 항상 `[ASSUMED]`인 이유
|
||||
|
||||
WebSearch를 통해 발견된 패키지 이름은 `npm view`가 성공하는지 여부에 관계없이 `[ASSUMED]`로 태그된다. 레지스트리에 존재하는 패키지가 설치하기에 안전한 패키지와 같지 않다. `npm view`는 등록을 증명하지, 적법성을 증명하지 않는다. `[ASSUMED]` 태그는 `[SUS]`와 동일한 사람 검증 체크포인트를 트리거하여, 검증되지 않은 웹 검색 추천이 설치 전에 항상 사람의 검토를 받도록 보장한다.
|
||||
|
||||
### 생태계 커버리지
|
||||
|
||||
리서처는 단일 일반 검사 대신 레지스트리별 검증 명령을 사용한다:
|
||||
|
||||
- Node.js: `npm view`
|
||||
- Python: `pip index versions`
|
||||
- Rust: `cargo search`
|
||||
|
||||
이는 2025년 USENIX 연구에 따르면 약 9% 발생률의 교차 생태계 환각을 커버한다 — AI가 실제로 사용 중인 것이 아닌 한 생태계에서는 존재하지만 다른 생태계에서는 없는 패키지를 추천하는 경우.
|
||||
|
||||
### 정상적인 성능 저하
|
||||
|
||||
`slopcheck`을 사용할 수 없는 경우(설치되지 않았거나 리서치 시점에 pip 설치 실패), GSD는 가장 엄격한 폴백을 적용한다: **모든 추천 패키지가 `[ASSUMED]`로 태그되고**, 플래너는 모든 설치에 `checkpoint:human-verify` 작업을 게이트로 건다. 리서치와 계획 수립은 정상적으로 진행된다 — 시스템은 누락된 도구 의존성으로 인해 하드 실패하지 않는다. 이것은 의도적으로 정상 흐름보다 더 엄격하다: slopcheck 사용 불가는 모든 패키지 설치에 사람 체크포인트를 받는다는 것을 의미한다.
|
||||
|
||||
`slopcheck` 도구는 MIT 라이선스이며 pip으로 설치 가능하다. 유지 관리가 중단되더라도 `[ASSUMED]`-게이트 폴백은 사람 체크포인트 커버리지가 유지되도록 보장한다.
|
||||
|
||||
---
|
||||
|
||||
## 계층 2 — 프롬프트 인젝션 방어
|
||||
|
||||
### 위협
|
||||
|
||||
GSD Core는 LLM 시스템 프롬프트가 되는 마크다운 파일을 생성한다. 리서치 파이프라인은 외부 웹 콘텐츠를 읽는다; 계획 파이프라인은 사용자가 제공한 텍스트(`--text-file`, `--prd`)를 통합한다; 실행 파이프라인은 에이전트 컨텍스트로 나중에 다시 읽히는 계획 결과물을 작성한다. 이런 결과물들에 흐르는 사용자가 제어하는 텍스트는 잠재적인 **간접 프롬프트 인젝션** 벡터이다 — 시스템 프롬프트 안에 들어가면 에이전트의 지시 사항을 재정의하거나 정보를 유출하려는 공격자가 제어하는 문자열.
|
||||
|
||||
### 방어 작동 방식
|
||||
|
||||
GSD Core는 세 가지 수준에서 프롬프트 인젝션을 다룬다.
|
||||
|
||||
**입력 유효성 검사(`security.cjs`).** `get-shit-done/bin/lib/security.cjs` 모듈은 중앙 보안 유틸리티이다. 다음을 제공한다:
|
||||
|
||||
- 경로 탐색 방지: 사용자가 제공한 파일 경로(`--text-file`, `--prd`)가 프로젝트 디렉터리 내에서 해결되도록 유효성이 검사되며, macOS의 `/var` → `/private/var` 심링크 해결이 명시적으로 처리된다
|
||||
- 프롬프트 인젝션 탐지: 알려진 인젝션 패턴(역할 재정의, 지시 우회, 시스템 태그 인젝션)이 사용자가 제공한 텍스트에서 계획 결과물에 들어가기 전에 스캔된다
|
||||
- 안전한 JSON 파싱: 제작된 JSON 페이로드를 통한 프로토타입 오염 공격을 방지하는 래퍼
|
||||
- 쉘 인수 유효성 검사: 하위 쉘 명령에 전달되는 인수가 사용 전에 유효성이 검사된다
|
||||
|
||||
**런타임 훅: `gsd-prompt-guard.js`.** 이 훅은 `.planning/` 파일을 대상으로 하는 모든 Write 또는 Edit 호출에서 실행된다. 작성되는 콘텐츠를 `security.cjs`와 동일한 인젝션 패턴으로 스캔한다(독립성을 위해 훅에 직접 인라인된 하위 집합 — 훅은 모듈 경로가 변경되더라도 실행되도록 모듈을 `require()`하지 않는다). 탐지는 **자문적 전용**이다: 훅은 결과를 로그하지만 쓰기를 차단하지 않는다. 이유는 합법적인 계획 쓰기에 대한 오탐지 차단이 이차 스캔 계층에서 놓친 인젝션보다 더 방해가 될 것이기 때문이다.
|
||||
|
||||
**런타임 훅: `gsd-read-injection-scanner.js`.** 이 훅은 모든 Read 도구 호출의 출력에서 실행된다. 방금 읽은 *콘텐츠*를 신뢰할 수 없는 콘텐츠의 주입된 지시 사항으로 스캔한다 — 공격자가 GSD가 에이전트 컨텍스트에 통합하려는 파일에 지시 사항을 내장한 경우를 잡아낸다.
|
||||
|
||||
**CI 스캐너.** `prompt-injection-scan.test.cjs`는 테스트 스위트의 일부로 내장된 인젝션 벡터가 있는지 모든 에이전트, 워크플로우, 명령 파일을 스캔한다. 이는 GSD 소스 자체의 인젝션 시도를 잡아낸다 — 예를 들어 워크플로우 파일을 수정하여 역할 재정의 지시 사항을 추가하는 공급망 공격.
|
||||
|
||||
### 읽기 인젝션 스캐너 vs 프롬프트 가드
|
||||
|
||||
두 훅은 보완적인 표면을 커버한다. `gsd-prompt-guard.js`는 *계획 결과물에 대한 쓰기*를 감시한다 — 심어지는 인젝션을 잡는다. `gsd-read-injection-scanner.js`는 *모든 파일의 읽기*를 감시한다 — 외부 콘텐츠(의존성의 README, 타사 설정 파일, 사용자가 제공한 문서)에서 수집되는 인젝션을 잡는다. 함께 수집 → 저장 → 재독 수명 주기를 괄호로 묶는다.
|
||||
|
||||
---
|
||||
|
||||
## 계층 3 — 저장소 및 의존성 무결성
|
||||
|
||||
GSD의 런타임 동작 상류에서 `open-gsd` 조직은 저장소와 패키지 수준에서 제어를 시행한다. 이것들은 [`docs/security/baseline.md`](../../security/baseline.md)에 완전히 문서화되어 있으며 완전성을 위해 여기에 요약된다.
|
||||
|
||||
**의존성 무결성.** 모든 타사 의존성은 `package-lock.json`을 통해 고정되고 설치 전에 공개된 체크섬에 대해 검증된다. `scripts/check-npm-integrity.cjs` 게이트는 CI 시점에 유효하지 않은 버전, 누락된 패키지, 불필요한 패키지를 탐지한다. 이는 GSD 자체 의존성에 대한 의존성 혼동 및 오타스쿼팅 공격을 완화한다.
|
||||
|
||||
**비밀 스캔.** 모든 커밋과 PR은 하드코딩된 비밀이 있는지 스캔된다. 의도적인 테스트 픽스처는 프로젝트 표준 제외 문법으로 주석을 달아야 한다(주석 형식은 `SECURITY.md` 참조). 주석이 없는 억제는 CI를 실패시킨다.
|
||||
|
||||
**로케일 안전 텍스트 스캔.** 출력 및 사용자 대면 문자열은 유니코드 동형 문자, 양방향 오버라이드 문자, 보이지 않는 유니코드에 대해 스캔된다 — 차이점에서 악의적인 콘텐츠를 숨길 수 있는 CVE-2021-42574("Trojan Source")에 문서화된 공격 클래스.
|
||||
|
||||
---
|
||||
|
||||
## 트레이드오프와 한계
|
||||
|
||||
여기에 설명된 보안 모델은 AI 기반 개발을 위한 공격 표면을 의미 있게 줄인다. 공급망 위험을 제거하지는 않는다.
|
||||
|
||||
**패키지 적법성 게이트가 줄이는 것:** 환각되거나 공격자가 등록한 패키지가 사람 체크포인트 없이 `npm install`에 도달할 확률. `[SLOP]` 게이트는 높은 신뢰도의 나쁜 패키지를 완전히 제거한다; `[SUS]` / `[ASSUMED]` 게이트는 실행 전에 사람 검토를 요구한다. 이는 성공적인 슬롭스쿼팅 공격의 비용을 상당히 높인다.
|
||||
|
||||
**패키지 적법성 게이트가 제거하지 않는 것:** 나중에 손상된 합법적인 패키지(계정 탈취, 자체 트리의 의존성 혼동)는 리서치 시점의 등록 신호를 확인하는 slopcheck에 의해 잡히지 않는다. 잠금 파일과 의존성 무결성 계층의 `npm audit`이 그 공격 클래스에 대한 제어이다.
|
||||
|
||||
**프롬프트 인젝션 방어가 줄이는 것:** 계획 결과물의 사용자가 제어하는 텍스트가 에이전트 지시 사항을 성공적으로 재정의할 확률. 알려진 인젝션 형태에 대한 패턴 매칭은 일반적인 경우를 잡는다; 새로운 탈옥이나 저신호 인젝션은 탐지되지 않고 통과할 수 있다. 자문 전용 자세는 탐지가 로그되지만 차단되지 않는다는 것을 의미한다 — 탐지 시 하드 정지하지 않는 비용으로 워크플로우 연속성을 보존하는 의도적인 선택.
|
||||
|
||||
**프롬프트 인젝션 방어가 제거하지 않는 것:** 알려진 패턴과 일치하지 않는 충분히 창의적인 인젝션, 또는 훅이 커버하지 않는 채널을 통해 도달하는 인젝션(예: 서브에이전트가 문서를 탐색하면서 읽는 의존성의 공개된 README에 주입된 콘텐츠). 심층 방어는 각 계층이 공격을 더 어렵게 만들지, 어떤 단일 계층이 불가능하게 만들지 않는다는 것을 의미한다.
|
||||
|
||||
**취약점 신고.** `https://github.com/open-gsd/gsd-core/security/advisories/new`에서 비공개 GitHub 보안 보고서를 통해 신고하라. 공개 이슈를 열지 말라. 응답 일정과 공개 정책은 [SECURITY.md](../../../SECURITY.md)를 참조하라.
|
||||
|
||||
---
|
||||
|
||||
## Related
|
||||
|
||||
- [명령어](../COMMANDS.md) — 보안 관련 플래그가 있는 `/gsd-secure-phase`와 `/gsd-code-review` 포함
|
||||
- [아키텍처 § 훅 시스템](../ARCHITECTURE.md#hook-system) — 모든 훅, 이벤트 트리거, 안전 속성에 대한 구현 상세
|
||||
- [SECURITY.md](../../../SECURITY.md) — 취약점 신고, 조직 전반 보안 기준선, 비밀 스캔 제외 거버넌스, 의존성 무결성 검증
|
||||
- [문서 인덱스](../README.md)
|
||||
129
docs/ko-KR/explanation/the-phase-loop.md
Normal file
129
docs/ko-KR/explanation/the-phase-loop.md
Normal file
@@ -0,0 +1,129 @@
|
||||
# 단계 루프
|
||||
|
||||
> GSD Core가 작업을 조직하는 방식의 핵심 멘탈 모델.
|
||||
|
||||
---
|
||||
|
||||
## 루프란 무엇인가
|
||||
|
||||
GSD Core는 모든 개발 작업을 반복되는 사이클로 구조화한다.
|
||||
|
||||
```text
|
||||
논의 → (UI 디자인) → 계획 → 실행 → 검증 → 출시
|
||||
```
|
||||
|
||||
모든 작업 단위 — **단계(phase)**라고 부름 — 는 이 순서대로 각 단계를 거친다. 루프는 형식적인 절차가 아니다. 각 단계는 이전 단계 혼자서는 방지할 수 없는 특정 종류의 실패를 막기 위해 존재한다.
|
||||
|
||||
이 문서는 루프가 이런 형태를 갖는 *이유*를 설명한다. 각 단계를 실행하는 방법에 대한 지침은 하단에 링크된 how-to 가이드를 참조하라.
|
||||
|
||||
---
|
||||
|
||||
## 각 단계가 존재하는 이유
|
||||
|
||||
### 논의(Discuss)
|
||||
|
||||
무엇을 만들어야 하는지뿐만 아니라 *어떻게* 만들어야 하는지를 알기 전까지는 계획을 시작할 수 없다. `ROADMAP.md`의 단계 목표는 결과를 설명한다. 논의 단계는 그 결과로 가는 경로를 형성하는 구현 결정 사항들을 캡처한다: 어떤 라이브러리를 사용할지, 오류 처리 전략, 기능이 라우트별인지 전역인지, 엣지 케이스의 동작 방식.
|
||||
|
||||
논의 단계 없이는 플래너가 이런 결정들을 스스로 내려야 한다. 때로는 맞게 추측하기도 한다. 그러나 그럴듯하지만 틀리게 추측하는 경우도 많다 — 일관성은 있지만 실제 선호도와 맞지 않는 계획을 생성한다. 실행이 완료되고 오류를 발견했을 때는 이미 상당한 작업을 되돌려야 하는 상황이 된다.
|
||||
|
||||
논의 단계는 의도적으로 가볍다. 명세 작성 훈련이 아니라 대화이다. 출력물은 단계 디렉터리의 `CONTEXT.md`이다: 플래너, 실행기, 검증기 모두 읽을 수 있는 결정 사항들의 구조화된 기록. 대화는 몇 분이 걸리지만; 수 시간의 재작업을 절약할 수 있다.
|
||||
|
||||
### UI 디자인(선택적)
|
||||
|
||||
시각적 컴포넌트가 있는 단계의 경우, 논의와 계획 사이에 선택적인 `/gsd-ui-phase` 단계가 있다. 코드 작성 전에 레이아웃, 인터랙션, 시각적 동작을 설명하는 디자인 계약인 `UI-SPEC.md`를 생성한다. UI가 복잡하여 디자인의 모호함이 다양한 구현 선택을 만들어낼 만큼 복잡할 때 이 단계를 실행할 가치가 있다. 명확한 디자인 계약은 재구현보다 훨씬 비용이 저렴하다.
|
||||
|
||||
### 계획(Plan)
|
||||
|
||||
계획 단계는 실행에 필요한 리서치, 분해, 구조적 사고를 수행한다. 신선한 컨텍스트 서브에이전트들의 시퀀스로 실행된다: 생태계를 조사하고 `RESEARCH.md`에 결과를 기록하는 리서처, 리서치와 `CONTEXT.md` 모두를 읽어 `PLAN.md` 파일들을 생성하는 플래너, 계획이 완전하고 일관성 있으며 범위 내에 있는지 검증하는 계획 검사기.
|
||||
|
||||
계획에는 무엇이 포함되는가? 각 `PLAN.md`는 작업의 범위가 한정된 단위를 설명한다: 수정할 파일들, 수행할 구체적인 변경 사항들, 완료를 정의하는 수락 기준. 계획들은 병렬 실행이 안전하도록 의존성 웨이브 순서로 정렬된다 — 같은 웨이브의 실행기들은 겹치지 않는 관심사를 다룬다.
|
||||
|
||||
계획 단계는 모호함이 가장 비용이 많이 드는 순간이다. 모호한 계획은 가정을 세우는 실행기를 만든다. 같은 관심사에 대해 서로 다른 가정을 세우는 여러 병렬 실행기들은 충돌을 만든다. 계획 검사기의 임무는 실행 전에 이런 문제들을 잡아내는 것이다.
|
||||
|
||||
### 실행(Execute)
|
||||
|
||||
실행은 계획들을 수행한다. 각 실행기는 자신에게 필요한 것들만 정확히 담긴 신선한 200k 토큰 컨텍스트 윈도우를 받는다: 프로젝트 요약, 단계 컨텍스트, 리서치, 그리고 자신의 작업에 대한 특정 `PLAN.md`. 그 이상은 없다.
|
||||
|
||||
실행기는 코드를 작성하고 원자적으로 커밋한다. 각 커밋은 계획에서 완료된 작업과 대응된다. 병렬 실행기들의 웨이브가 완료되면, 오케스트레이터는 상태를 병합하고 다음 웨이브를 시작한다.
|
||||
|
||||
실행기의 신선한 컨텍스트는 편의를 위한 것이 아니다 — 컨텍스트 부패를 방지하는 메커니즘이다. 180k 토큰의 누적된 세션 이력으로 실행되는 실행기는 저하된 실행기이다. 깨끗하게 시작하고 계획이 필요로 하는 것만 읽는 실행기는 최대 능력으로 작동하는 실행기이다.
|
||||
|
||||
### 검증(Verify)
|
||||
|
||||
모든 실행기가 완료된 후, 검증기 에이전트는 단계 목표, `CONTEXT.md` 결정 사항들, 계획들, 실행 요약들을 읽고 — 만들어진 것이 의도한 것과 일치하는지 확인한다. `VERIFICATION.md`를 생성하고, 불일치가 있으면 대상이 명확한 수정 계획을 생성한다.
|
||||
|
||||
검증은 단순한 테스트가 아니다. 요구 사항 커버리지(모든 REQ-ID가 처리되었는가?), 결정 커버리지(`CONTEXT.md`에 캡처된 결정 사항들이 실제로 구현되었는가?), 전반적인 단계 목표 정렬을 확인한다. 단계는 실행이 오류 없이 완료되었기 때문에 완료되는 것이 아니다. 만들어진 것이 계획된 것이고, 계획된 것이 결정된 것이기 때문에 완료된다.
|
||||
|
||||
### 출시(Ship)
|
||||
|
||||
출시 단계는 풀 리퀘스트를 생성하고 단계 결과물들을 아카이브한다. `STATE.md`가 업데이트되어 단계 완료를 표시한다. 루프가 다음 단계를 위해 다시 시작된다.
|
||||
|
||||
---
|
||||
|
||||
## 마일스톤과 단계
|
||||
|
||||
**마일스톤**은 버전 사이클 — 프로젝트의 의미 있고 릴리스 가능한 증분이다. 이름, 버전 번호, 그리고 무엇을 제공해야 하는지 정의하는 요구 사항들의 집합을 갖는다. 마일스톤은 모든 단계들이 출시되고 요구 사항들이 충족되면 완료된다.
|
||||
|
||||
**단계**는 마일스톤 내의 하나의 작업 단위이다. 단계는 목표, 처리하는 요구 사항들의 집합, 그리고 그것을 구현하는 계획들의 집합을 갖는다.
|
||||
|
||||
이 관계가 중요한 이유는 마일스톤과 단계가 서로 다른 관심 범위를 갖기 때문이다. 마일스톤은 묻는다: "이 버전의 제품은 무엇을 하고, 무엇을 하지 않는가?" 단계는 묻는다: "우리가 다음으로 연구하고, 계획하고, 실행하고, 검증할 수 있는 범위가 한정된 것은 무엇인가?"
|
||||
|
||||
마일스톤 경계는 자연스러운 제품 경계에서 그어진다 — 배포 가능한 API, 작동하는 UI 플로우, 완전한 데이터 모델. 단계 경계는 루프가 다루기 힘들어지지 않고 하나의 루프에서 안전하게 실행될 수 있는 범위의 한계에서 그어진다.
|
||||
|
||||
---
|
||||
|
||||
## 좋은 단계 범위란 무엇인가
|
||||
|
||||
이것은 루프와 관련된 마찰의 가장 일반적인 원인이기 때문에 심층적으로 살펴볼 가치가 있다.
|
||||
|
||||
너무 큰 단계는 그 자체로 리서치 프로젝트가 된다. 플래너는 독립적인 계획들로 분해하는 데 어려움을 겪는다. 이후 웨이브의 실행기들이 이전 웨이브를 기다리며 막힌다. 검증이 대상이 명확한 리뷰보다 전체 감사가 된다. 피드백 사이클이 몇 시간에서 며칠로 늘어나고, 많은 코드가 작성된 후에야 — 근본적인 설계 오류를 발견할 위험이 급격히 높아진다.
|
||||
|
||||
너무 작은 단계는 자연스럽게 함께 속하는 작업을 분할한다. 몇 줄에 불과한 계획 파일들, 몇 분 안에 완료되는 단계들, 실행 비용을 압도하는 계획 오버헤드가 발생한다. 루프가 도움이 되기보다 관료적으로 느껴진다.
|
||||
|
||||
좋은 단계 범위는 다음과 같은 경우이다:
|
||||
|
||||
- 목표가 명백히 사소하지도 않고 의심스럽게 광범위하지도 않은 하나의 문장으로 명시될 수 있다.
|
||||
- 계획에 필요한 리서치가 제한되어 있다 — 생태계 질문들이 다른 단계들이 먼저 완료되는 것에 의존하지 않는 답을 가진다.
|
||||
- 실행이 수십 개가 아니라 소수의 겹치지 않는 계획들로 병렬화될 수 있다.
|
||||
- 검증기가 전체 코드베이스를 읽지 않고도 확인할 수 있는 명확하고 테스트 가능한 완료 정의가 있다.
|
||||
|
||||
구체적으로: "HMAC-SHA256 서명 검증 미들웨어 추가"는 좋은 단계 범위이다. "인증 시스템 구축"은 일반적으로 아니다 — 거의 항상 별도의 단계로 더 잘 처리될 여러 독립적인 관심사들을 포함한다. "README의 오타 수정"은 루프가 가치를 추가하는 임계값 아래이다; 대신 `/gsd-quick`을 사용하라.
|
||||
|
||||
의심스러울 때는 분할하라. 더 작은 단계는 더 빨리 완료되고, 더 자신 있게 검증되고, 설계 결정이 잘못된 것으로 판명될 경우 방향을 수정하기 더 쉽다.
|
||||
|
||||
---
|
||||
|
||||
## `.planning/`이 루프 전반에 걸쳐 상태를 유지하는 방법
|
||||
|
||||
루프는 단일 세션이 아니다. 리서치, 계획 수립, 실행은 그 사이에 컨텍스트 리셋이 있는 여러 세션에 걸쳐 발생할 수 있다. `.planning/` 디렉터리가 이것을 가능하게 한다.
|
||||
|
||||
루프의 모든 단계는 이전 단계에서 생성된 결과물들을 읽고 이후 단계를 위한 결과물들을 작성한다. 논의 단계가 생성하는 CONTEXT.md는 플래너가 실행될 때도 사용 가능하다 — 몇 시간 후 다른 세션에서 실행되더라도. 플래너가 생성하는 PLAN.md 파일들은 실행기가 실행될 때도 사용 가능하다 — 재시작 후에도. 검증기가 작성하는 VERIFICATION.md는 단계를 검토할 때도 사용 가능하다.
|
||||
|
||||
`STATE.md`는 이 모든 것 위에 있는 내비게이션 레이어이다. 프로젝트가 루프의 정확히 어느 위치에 있는지 기록한다: 어느 마일스톤이 활성 상태인지, 어느 단계가 진행 중인지, 어느 계획들이 완료되고 어느 것들이 대기 중인지. 방향을 잡아야 하는 에이전트나 워크플로우는 먼저 `STATE.md`를 읽는다.
|
||||
|
||||
이 파일들의 정확한 구조는 [계획 결과물](../reference/planning-artifacts.md)과 [STATE.md 스키마](../reference/state-md.md)를 참조하라.
|
||||
|
||||
---
|
||||
|
||||
## 루프는 리듬이지 제약이 아니다
|
||||
|
||||
루프를 관료주의로 바라보는 시각이 있다 — 코드를 작성하기 전에 수행해야 하는 일련의 필수 단계들. 그 프레임은 틀렸다.
|
||||
|
||||
루프는 각 단계가 나중에 수정하는 데 실제로 비용이 많이 드는 실패들을 방지하기 때문에 존재한다. 논의는 잘못된 가정 위에서 계획하는 것을 방지한다. 계획은 근본적으로 깨진 설계를 실행하는 것을 방지한다. 검증은 요약 사항을 놓친 작업을 출시하는 것을 방지한다. 이것들은 인위적인 문제가 아니다. 실제 기능 규모에서 AI 보조 개발의 실제 실패 모드들이다.
|
||||
|
||||
루프가 잘 작동할 때 리듬처럼 느껴진다: 각 단계가 이전 단계가 자신의 역할을 했기 때문에 명확한, 집중적이고 범위가 한정된 작업의 박자. 오버헤드는 실재하지만, 전면 부담된다 — 수 시간의 재작업이 아니라 몇 분의 계획으로 지불된다.
|
||||
|
||||
루프가 정당화되는 임계값 아래의 작업을 위해 GSD Core는 더 가벼운 기본 도구들을 제공한다. 단계 루프는 하나의 도구이지, 유일한 도구가 아니다.
|
||||
|
||||
---
|
||||
|
||||
## Related
|
||||
|
||||
- [컨텍스트 엔지니어링](context-engineering.md) — 신선한 컨텍스트 서브에이전트가 루프를 필요하게 만드는 품질 저하를 방지하는 방법
|
||||
- [단계 논의하기](../how-to/discuss-a-phase.md)
|
||||
- [단계 계획하기](../how-to/plan-a-phase.md)
|
||||
- [단계 실행하기](../how-to/execute-a-phase.md)
|
||||
- [검증 및 출시](../how-to/verify-and-ship.md)
|
||||
- [계획 결과물](../reference/planning-artifacts.md)
|
||||
- [STATE.md 스키마](../reference/state-md.md)
|
||||
- [문서 인덱스](../README.md)
|
||||
Reference in New Issue
Block a user