---
title: "Moonshot Phase Runner 구조 깊게 보기"
slug: "moonshot-phase-runner-deep-dive"
canonicalUrl: "https://moonshotnotes.com/posts/moonshot-phase-runner-deep-dive/"
sourceUrl: "https://moonshotnotes.com/posts/moonshot-phase-runner-deep-dive/"
markdownUrl: "https://moonshotnotes.com/agent/posts/moonshot-phase-runner-deep-dive.md"
language: "ko"
category: "Workflow"
updatedAt: "2026-04-29"
agentTokenEstimate: 1967
---

# Moonshot Phase Runner 구조 깊게 보기

Moonshot Phase Runner의 계획 디렉터리, 상태 파일, 실행 산출물, 검토 게이트를 통해 긴 AI 작업을 안정적으로 운영하는 방법을 정리합니다.

## Agent metadata

- Source: https://moonshotnotes.com/posts/moonshot-phase-runner-deep-dive/
- Markdown: https://moonshotnotes.com/agent/posts/moonshot-phase-runner-deep-dive.md
- Language: ko
- Category: Workflow
- Tags: Phase Runner, Workflow, Automation, QA
- Updated: 2026-04-29
- Estimated tokens: 1967

> **이 글에서 다루는 것 (info)**
>
> 입문 글에서 설명한 단계 기반 작업 흐름을 한 단계 더 내려가서, Moonshot Phase Runner 스킬이 실제로 어떤 구조로 긴 작업을 준비하고 실행하는지 정리합니다.

## 구조 요약

Moonshot Phase Runner는 큰 작업을 바로 구현하지 않습니다. 먼저 작업을 담을 계획 디렉터리를 정하고, 그 안에 있는 마스터 플랜과 단계 문서를 읽습니다. 그다음 현재 상태를 추적하는 파일과 단계별 실행 산출물을 준비한 뒤 실행 루프로 넘깁니다.

겉으로 보면 사용자는 명령 하나를 입력합니다.

```text
/moonshot-phase-runner docs/implementation --autonomous
```

안에서는 아래 흐름이 이어집니다.

```text
요청
-> 계획 디렉터리 결정
-> 마스터 플랜과 단계 문서 확인
-> 상태 파일 준비
-> 실행 산출물 준비
-> 불확실성 확인 또는 autonomous 처리
-> 실행 모드 결정
-> 단계별 실행, 검토, 검증, 기록
-> 모든 실행 가능 단계가 끝나거나 명시적 중단 조건에 도달
```

## 왜 별도 구조가 필요한가

긴 AI 작업에서 어려운 부분은 구현 자체보다 경계 관리입니다. 지금 어느 단계인지, 이전 시도에서 무엇이 실패했는지, 검토를 실제로 했는지, 검증 결과가 다음 시도에 반영됐는지를 계속 추적해야 합니다.

Phase Runner는 이 문제를 말로 된 진행 보고에 맡기지 않습니다. 대신 계획, 상태, 산출물을 분리합니다.

| 영역 | 역할 |
| --- | --- |
| 계획 문서 | 전체 목표와 단계별 범위를 정합니다. |
| 상태 파일 | 어떤 단계가 대기, 진행, 완료, 재시도 상태인지 기록합니다. |
| 실행 산출물 | 각 단계의 계약, QA 결과, 인계 내용, 점수표를 남깁니다. |
| 실행 모드 | 현재 세션에서 조율할지, 별도 루프로 길게 실행할지 정합니다. |
| 게이트 | 검토와 검증 없이 완료로 넘어가지 않게 막습니다. |

이 구조 덕분에 한 번에 끝나지 않는 작업도 이어서 볼 수 있습니다. "지난번에 어디까지 했지?"라는 질문에 답하기 위해 대화 전체를 다시 읽지 않아도 됩니다.

## 사용자가 보는 명령

일반적인 시작점은 아래 명령입니다.

```text
/moonshot-phase-runner
```

계획 디렉터리를 직접 지정하면 더 명확합니다.

```text
/moonshot-phase-runner docs/implementation
```

긴 작업을 중간 질문 없이 계속 밀어붙이고 싶다면 autonomous 모드를 씁니다.

```text
/moonshot-phase-runner docs/implementation --autonomous
```

실행하지 않고 준비만 하고 싶을 때는 prepare-only를 씁니다.

```text
/moonshot-phase-runner docs/implementation --prepare-only
```

현재 대화 세션이 직접 조율하되, 각 실행 시도는 새 맥락에서 분리하고 싶다면 실행 모드를 지정합니다.

```text
/moonshot-phase-runner docs/implementation --execution-mode in-session-coordinator
```

여기서 중요한 점은 Phase Runner가 단순한 계획 작성기가 아니라는 것입니다. prepare-only를 명시하지 않는 한, 기본 동작은 준비 후 실행까지 이어지는 것입니다.

## 계획 디렉터리 결정

Phase Runner는 먼저 어떤 계획 묶음을 실행할지 정합니다. 사용자가 경로를 넘기면 그 경로를 우선합니다. 경로가 없으면 현재 상태 파일에 기록된 활성 계획을 확인하고, 그것도 없으면 기본 구현 계획 디렉터리를 찾습니다.

결정 순서는 대략 이렇게 볼 수 있습니다.

| 우선순위 | 판단 |
| --- | --- |
| 사용자가 지정한 경로 | 가장 먼저 사용합니다. |
| 활성 상태 파일 | 이전 실행이 남긴 현재 계획을 재사용합니다. |
| 기본 구현 계획 | 보통 구현 계획이 모이는 위치를 찾습니다. |
| 단일 후보 | 안전하게 하나만 발견되면 사용합니다. |
| 새 계획 작성 | 안전한 후보가 없으면 계획 작성 단계로 넘어갑니다. |

여러 후보가 있는데 어느 것을 실행해야 할지 불분명하면 멈추고 물어보는 편이 맞습니다. 긴 작업에서 가장 위험한 실수는 엉뚱한 계획을 자신 있게 실행하는 것입니다.

## 계획 문서의 역할

계획 디렉터리 안에는 전체 그림을 설명하는 마스터 플랜과 단계별 문서가 있습니다. 마스터 플랜은 작업의 목적, 범위, 순서를 담고, 단계 문서는 각 라운드에서 실제로 무엇을 바꿀지 더 좁게 정의합니다.

완료된 단계 문서는 활성 목록에서 빠져야 합니다. 그래서 완료된 문서는 닫힌 기록 영역으로 옮겨지고, 상태 파일에는 해당 단계가 어디로 보관됐는지가 남습니다. 이렇게 해야 다음 실행 때 이미 끝난 단계를 다시 후보로 잡지 않습니다.

이 방식은 문서를 단순 기록물이 아니라 실행 대상 목록으로 다루기 위한 장치입니다.

## 상태 파일이 하는 일

Phase Runner의 중심에는 상태 파일이 있습니다. 이 파일은 현재 실행이 어떤 계획을 보고 있는지, 어떤 모드로 실행되는지, 각 단계가 어떤 상태인지, 각 단계의 산출물 경로가 무엇인지 기록합니다.

상태 파일에는 보통 이런 정보가 들어갑니다.

```yaml
masterPlan: "계획 디렉터리의 마스터 플랜"
executionMode: "delegated-terminal 또는 in-session-coordinator"
executionRoot: "단계별 실행 산출물이 모이는 위치"
phases:
  - number: 1
    title: "첫 번째 단계"
    status: pending
    planConfirmed: true
    attempts:
      total: 0
      lastOutcome: pending
    sprintContract: "해당 단계의 실행 계약"
    qaReport: "해당 단계의 QA 결과"
    handoff: "해당 단계의 인계 문서"
```

상태 파일을 보면 "이 작업은 지금 어느 단계인가", "이전 시도는 실패했는가", "다음에 봐야 할 산출물은 무엇인가"를 확인할 수 있습니다. 그래서 긴 작업에서는 최종 답변보다 상태 파일과 산출물이 더 중요한 경우가 많습니다.

## 실행 산출물 네 가지

각 단계에는 실행을 이어가기 위한 산출물이 준비됩니다. 이름은 개발자스럽지만 역할은 명확합니다.

| 산출물 | 역할 |
| --- | --- |
| SPRINT_CONTRACT.md | 이번 단계에서 지켜야 할 범위, 규칙, 검증 기준을 정합니다. |
| QA_REPORT.md | 무엇을 확인했고 무엇이 실패했는지 기록합니다. |
| HANDOFF.md | 다음 시도나 다음 작업자가 이어서 볼 내용을 남깁니다. |
| SCORECARD.md | 완료 여부를 감으로 판단하지 않도록 점검 항목과 판정을 둡니다. |

이 네 가지는 단계 실행의 기억 장치입니다. 특히 재시도가 필요한 작업에서는 `QA_REPORT.md`와 `HANDOFF.md`가 중요합니다. 실패 이유와 다음 조치가 남아 있어야 같은 실수를 반복하지 않습니다.

`SCORECARD.md`는 "대충 괜찮다"를 막는 장치입니다. 목표 점수나 필수 항목이 충족되기 전에는 기본적으로 재시도 판정을 유지하는 식으로 완료 선언을 보수적으로 만듭니다.

## 불확실성 처리

Phase Runner는 모든 작업을 무조건 밀어붙이지 않습니다. 사용자가 `--autonomous`를 주지 않았다면 계획을 검토하면서 모호한 부분을 찾고 질문할 수 있습니다.

예를 들어 아래 같은 정보가 빠져 있으면 질문 대상이 됩니다.

- 어느 화면까지 수정해야 하는지 불명확합니다.
- 기존 데이터를 보존해야 하는지 알 수 없습니다.
- 검증 기준이 테스트인지 브라우저 확인인지 정해지지 않았습니다.
- 실패했을 때 재시도할지 멈출지 기준이 없습니다.

반대로 `--autonomous`를 주면 질문을 줄이고 스스로 합리적인 결정을 내려 진행합니다. 다만 autonomous는 아무렇게나 진행한다는 뜻이 아닙니다. 계획과 산출물에 결정 근거를 남기면서 앞으로 가는 모드에 가깝습니다.

## 실행 모드 두 가지

Phase Runner의 실행 모드는 크게 두 가지입니다.

| 모드 | 쓰임 |
| --- | --- |
| delegated-terminal | 별도 실행 루프를 통해 긴 작업을 끊기지 않고 진행할 때 적합합니다. |
| in-session-coordinator | 현재 대화 세션이 조율하되 각 시도를 분리해서 관리할 때 적합합니다. |

`delegated-terminal`은 긴 자율 실행에 더 가깝습니다. 계획을 준비한 뒤 dispatcher와 agent loop가 실행을 이어갑니다. 사용자가 "끝까지 진행해줘"라고 기대할 때 더 잘 맞습니다.

`in-session-coordinator`는 현재 세션이 조율자 역할을 합니다. 다만 이 모드에서도 구현 시도는 같은 대화 맥락에 질질 끌려가면 안 됩니다. 각 시도는 단계 문서, 실행 계약, 최신 QA 결과, 인계 문서를 입력으로 받아 새롭게 시작해야 합니다.

## 단계 실행 루프

각 단계는 보통 아래 순서로 진행됩니다.

```text
ready/isolate
-> execute
-> review
-> verify
-> finish/handoff
```

`ready/isolate`에서는 작업 전제와 격리 상태를 확인합니다. 현재 작업 공간이 안전한지, 필요한 규칙과 계약이 입력에 들어왔는지, 검증 기준이 충분한지 보는 단계입니다.

`execute`에서는 실제 구현이나 문서 수정이 일어납니다. 테스트 주도 흐름, 구현 실행, 단순화, 빌드 오류 해결, 실패 분석 같은 작업이 여기에 속합니다.

`review`에서는 결과를 비판적으로 봅니다. 코드 변경이라면 코드 리뷰가 들어가야 하고, 보안이나 접근성, 디자인 기준이 필요한 작업이면 해당 관점의 검토도 포함됩니다.

`verify`에서는 말이 아니라 증거를 봅니다. 테스트, 빌드, 브라우저 확인, QA 흐름, 완료 검증 같은 근거가 있어야 합니다.

`finish/handoff`에서는 기록을 닫습니다. 문서를 최신화하고, 세션 기록이나 인계 내용을 남기며, 명시적으로 요청된 경우에만 커밋까지 진행합니다.

## 완료로 인정하지 않는 것

Phase Runner에서 중요한 규칙은 "부분 완료를 전체 완료처럼 말하지 않는다"입니다. 아래 항목은 유용한 중간 결과일 수 있지만, 그것만으로 종료 조건이 되지는 않습니다.

- 한 단계가 끝났습니다.
- QA 보고서가 만들어졌습니다.
- 인계 문서가 생겼습니다.
- 체크포인트가 남았습니다.
- 문서만 최신화됐습니다.
- 일부 구현이 통과했습니다.

활성 계획 디렉터리에 아직 대기 중이거나 재시도 가능한 단계가 있으면 계속 진행해야 합니다. 검토가 빠졌거나 완료 산출물이 서로 맞지 않아도 끝났다고 말하면 안 됩니다.

## 정상 종료와 중단 조건

정상 종료는 모든 실행 가능 단계가 완료되고, 상태 파일과 산출물과 검증 결과가 서로 일치할 때 가능합니다. 특히 코드 변경이 있는 단계라면 리뷰와 검증 근거가 닫혀 있어야 합니다.

중단은 아래 상황에서만 자연스럽습니다.

- 사용자가 명시적으로 멈추라고 했습니다.
- 재시도 한도나 하드 블로커에 도달했습니다.
- 위험한 입력 누락이 있어서 계속 진행하면 잘못된 결과가 됩니다.
- 실행 런타임이 더 이상 진행할 수 없습니다.

이 구분이 없으면 긴 작업은 쉽게 "중간 보고를 최종 답변처럼 내는" 문제로 빠집니다.

## 사용자가 확인하면 좋은 것

Phase Runner를 쓰는 사용자가 모든 내부 파일을 외울 필요는 없습니다. 대신 아래 세 가지만 보면 진행 상황을 꽤 정확히 판단할 수 있습니다.

- [x] 상태 파일에서 현재 단계와 남은 단계가 보인다
- [x] QA 보고서에 통과한 확인과 실패한 확인이 분리되어 있다
- [x] 인계 문서에 다음 시도에서 바로 볼 내용이 남아 있다

작업을 맡길 때는 이렇게 요청하면 좋습니다.

```text
/moonshot-phase-runner docs/implementation --autonomous

모든 단계가 끝날 때까지 진행해줘.
단계가 끝날 때마다 QA 결과와 인계 내용을 남기고,
검토와 검증 없이 완료로 처리하지 말아줘.
```

현재 세션에서 더 세밀하게 보고 싶다면 이렇게 요청할 수 있습니다.

```text
/moonshot-phase-runner docs/implementation --execution-mode in-session-coordinator

각 시도는 새 맥락에서 진행하고,
결과는 변경 파일, 실패한 확인, 다음 조치 중심으로 요약해줘.
```

## 마무리

Moonshot Phase Runner는 "AI에게 일을 시키는 명령"이라기보다 긴 작업을 잃어버리지 않게 하는 실행 구조에 가깝습니다. 계획 디렉터리는 범위를 잡고, 상태 파일은 현재 위치를 기록하고, 실행 산출물은 재시도와 인계를 가능하게 하며, 검토와 검증 게이트는 성급한 완료 선언을 막습니다.

큰 작업에서 중요한 것은 빠르게 시작하는 것만이 아닙니다. 끝났다고 말할 수 있는 근거를 남기면서 계속 앞으로 가는 것입니다.