msd-core/docs/ko-KR/explanation/the-phase-loop.md

단계 루프

GSD Core가 작업을 조직하는 방식의 핵심 멘탈 모델.

---

루프란 무엇인가

GSD Core는 모든 개발 작업을 반복되는 사이클로 구조화한다.

논의 → (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를 읽는다.

이 파일들의 정확한 구조는 계획 결과물과 STATE.md 스키마를 참조하라.

---

루프는 리듬이지 제약이 아니다

루프를 관료주의로 바라보는 시각이 있다 — 코드를 작성하기 전에 수행해야 하는 일련의 필수 단계들. 그 프레임은 틀렸다.

루프는 각 단계가 나중에 수정하는 데 실제로 비용이 많이 드는 실패들을 방지하기 때문에 존재한다. 논의는 잘못된 가정 위에서 계획하는 것을 방지한다. 계획은 근본적으로 깨진 설계를 실행하는 것을 방지한다. 검증은 요약 사항을 놓친 작업을 출시하는 것을 방지한다. 이것들은 인위적인 문제가 아니다. 실제 기능 규모에서 AI 보조 개발의 실제 실패 모드들이다.

루프가 잘 작동할 때 리듬처럼 느껴진다: 각 단계가 이전 단계가 자신의 역할을 했기 때문에 명확한, 집중적이고 범위가 한정된 작업의 박자. 오버헤드는 실재하지만, 전면 부담된다 — 수 시간의 재작업이 아니라 몇 분의 계획으로 지불된다.

루프가 정당화되는 임계값 아래의 작업을 위해 GSD Core는 더 가벼운 기본 도구들을 제공한다. 단계 루프는 하나의 도구이지, 유일한 도구가 아니다.

---

Related

• 컨텍스트 엔지니어링 — 신선한 컨텍스트 서브에이전트가 루프를 필요하게 만드는 품질 저하를 방지하는 방법
• 단계 논의하기
• 단계 계획하기
• 단계 실행하기
• 검증 및 출시
• 계획 결과물
• STATE.md 스키마
• 문서 인덱스