구조 요약
Moonshot Phase Runner는 큰 작업을 바로 구현하지 않습니다. 먼저 작업을 담을 계획 디렉터리를 정하고, 그 안에 있는 마스터 플랜과 단계 문서를 읽습니다. 그다음 현재 상태를 추적하는 파일과 단계별 실행 산출물을 준비한 뒤 실행 루프로 넘깁니다.
겉으로 보면 사용자는 명령 하나를 입력합니다.
/moonshot-phase-runner docs/implementation --autonomous안에서는 아래 흐름이 이어집니다.
요청-> 계획 디렉터리 결정-> 마스터 플랜과 단계 문서 확인-> 상태 파일 준비-> 실행 산출물 준비-> 불확실성 확인 또는 autonomous 처리-> 실행 모드 결정-> 단계별 실행, 검토, 검증, 기록-> 모든 실행 가능 단계가 끝나거나 명시적 중단 조건에 도달왜 별도 구조가 필요한가
긴 AI 작업에서 어려운 부분은 구현 자체보다 경계 관리입니다. 지금 어느 단계인지, 이전 시도에서 무엇이 실패했는지, 검토를 실제로 했는지, 검증 결과가 다음 시도에 반영됐는지를 계속 추적해야 합니다.
Phase Runner는 이 문제를 말로 된 진행 보고에 맡기지 않습니다. 대신 계획, 상태, 산출물을 분리합니다.
| 영역 | 역할 |
|---|---|
| 계획 문서 | 전체 목표와 단계별 범위를 정합니다. |
| 상태 파일 | 어떤 단계가 대기, 진행, 완료, 재시도 상태인지 기록합니다. |
| 실행 산출물 | 각 단계의 계약, QA 결과, 인계 내용, 점수표를 남깁니다. |
| 실행 모드 | 현재 세션에서 조율할지, 별도 루프로 길게 실행할지 정합니다. |
| 게이트 | 검토와 검증 없이 완료로 넘어가지 않게 막습니다. |
이 구조 덕분에 한 번에 끝나지 않는 작업도 이어서 볼 수 있습니다. "지난번에 어디까지 했지?"라는 질문에 답하기 위해 대화 전체를 다시 읽지 않아도 됩니다.
사용자가 보는 명령
일반적인 시작점은 아래 명령입니다.
/moonshot-phase-runner계획 디렉터리를 직접 지정하면 더 명확합니다.
/moonshot-phase-runner docs/implementation긴 작업을 중간 질문 없이 계속 밀어붙이고 싶다면 autonomous 모드를 씁니다.
/moonshot-phase-runner docs/implementation --autonomous실행하지 않고 준비만 하고 싶을 때는 prepare-only를 씁니다.
/moonshot-phase-runner docs/implementation --prepare-only현재 대화 세션이 직접 조율하되, 각 실행 시도는 새 맥락에서 분리하고 싶다면 실행 모드를 지정합니다.
/moonshot-phase-runner docs/implementation --execution-mode in-session-coordinator여기서 중요한 점은 Phase Runner가 단순한 계획 작성기가 아니라는 것입니다. prepare-only를 명시하지 않는 한, 기본 동작은 준비 후 실행까지 이어지는 것입니다.
계획 디렉터리 결정
Phase Runner는 먼저 어떤 계획 묶음을 실행할지 정합니다. 사용자가 경로를 넘기면 그 경로를 우선합니다. 경로가 없으면 현재 상태 파일에 기록된 활성 계획을 확인하고, 그것도 없으면 기본 구현 계획 디렉터리를 찾습니다.
결정 순서는 대략 이렇게 볼 수 있습니다.
| 우선순위 | 판단 |
|---|---|
| 사용자가 지정한 경로 | 가장 먼저 사용합니다. |
| 활성 상태 파일 | 이전 실행이 남긴 현재 계획을 재사용합니다. |
| 기본 구현 계획 | 보통 구현 계획이 모이는 위치를 찾습니다. |
| 단일 후보 | 안전하게 하나만 발견되면 사용합니다. |
| 새 계획 작성 | 안전한 후보가 없으면 계획 작성 단계로 넘어갑니다. |
여러 후보가 있는데 어느 것을 실행해야 할지 불분명하면 멈추고 물어보는 편이 맞습니다. 긴 작업에서 가장 위험한 실수는 엉뚱한 계획을 자신 있게 실행하는 것입니다.
계획 문서의 역할
계획 디렉터리 안에는 전체 그림을 설명하는 마스터 플랜과 단계별 문서가 있습니다. 마스터 플랜은 작업의 목적, 범위, 순서를 담고, 단계 문서는 각 라운드에서 실제로 무엇을 바꿀지 더 좁게 정의합니다.
완료된 단계 문서는 활성 목록에서 빠져야 합니다. 그래서 완료된 문서는 닫힌 기록 영역으로 옮겨지고, 상태 파일에는 해당 단계가 어디로 보관됐는지가 남습니다. 이렇게 해야 다음 실행 때 이미 끝난 단계를 다시 후보로 잡지 않습니다.
이 방식은 문서를 단순 기록물이 아니라 실행 대상 목록으로 다루기 위한 장치입니다.
상태 파일이 하는 일
Phase Runner의 중심에는 상태 파일이 있습니다. 이 파일은 현재 실행이 어떤 계획을 보고 있는지, 어떤 모드로 실행되는지, 각 단계가 어떤 상태인지, 각 단계의 산출물 경로가 무엇인지 기록합니다.
상태 파일에는 보통 이런 정보가 들어갑니다.
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 결과, 인계 문서를 입력으로 받아 새롭게 시작해야 합니다.
단계 실행 루프
각 단계는 보통 아래 순서로 진행됩니다.
ready/isolate-> execute-> review-> verify-> finish/handoffready/isolate에서는 작업 전제와 격리 상태를 확인합니다. 현재 작업 공간이 안전한지, 필요한 규칙과 계약이 입력에 들어왔는지, 검증 기준이 충분한지 보는 단계입니다.
execute에서는 실제 구현이나 문서 수정이 일어납니다. 테스트 주도 흐름, 구현 실행, 단순화, 빌드 오류 해결, 실패 분석 같은 작업이 여기에 속합니다.
review에서는 결과를 비판적으로 봅니다. 코드 변경이라면 코드 리뷰가 들어가야 하고, 보안이나 접근성, 디자인 기준이 필요한 작업이면 해당 관점의 검토도 포함됩니다.
verify에서는 말이 아니라 증거를 봅니다. 테스트, 빌드, 브라우저 확인, QA 흐름, 완료 검증 같은 근거가 있어야 합니다.
finish/handoff에서는 기록을 닫습니다. 문서를 최신화하고, 세션 기록이나 인계 내용을 남기며, 명시적으로 요청된 경우에만 커밋까지 진행합니다.
완료로 인정하지 않는 것
Phase Runner에서 중요한 규칙은 "부분 완료를 전체 완료처럼 말하지 않는다"입니다. 아래 항목은 유용한 중간 결과일 수 있지만, 그것만으로 종료 조건이 되지는 않습니다.
- 한 단계가 끝났습니다.
- QA 보고서가 만들어졌습니다.
- 인계 문서가 생겼습니다.
- 체크포인트가 남았습니다.
- 문서만 최신화됐습니다.
- 일부 구현이 통과했습니다.
활성 계획 디렉터리에 아직 대기 중이거나 재시도 가능한 단계가 있으면 계속 진행해야 합니다. 검토가 빠졌거나 완료 산출물이 서로 맞지 않아도 끝났다고 말하면 안 됩니다.
정상 종료와 중단 조건
정상 종료는 모든 실행 가능 단계가 완료되고, 상태 파일과 산출물과 검증 결과가 서로 일치할 때 가능합니다. 특히 코드 변경이 있는 단계라면 리뷰와 검증 근거가 닫혀 있어야 합니다.
중단은 아래 상황에서만 자연스럽습니다.
- 사용자가 명시적으로 멈추라고 했습니다.
- 재시도 한도나 하드 블로커에 도달했습니다.
- 위험한 입력 누락이 있어서 계속 진행하면 잘못된 결과가 됩니다.
- 실행 런타임이 더 이상 진행할 수 없습니다.
이 구분이 없으면 긴 작업은 쉽게 "중간 보고를 최종 답변처럼 내는" 문제로 빠집니다.
사용자가 확인하면 좋은 것
Phase Runner를 쓰는 사용자가 모든 내부 파일을 외울 필요는 없습니다. 대신 아래 세 가지만 보면 진행 상황을 꽤 정확히 판단할 수 있습니다.
- 상태 파일에서 현재 단계와 남은 단계가 보인다
- QA 보고서에 통과한 확인과 실패한 확인이 분리되어 있다
- 인계 문서에 다음 시도에서 바로 볼 내용이 남아 있다
작업을 맡길 때는 이렇게 요청하면 좋습니다.
/moonshot-phase-runner docs/implementation --autonomous 모든 단계가 끝날 때까지 진행해줘.단계가 끝날 때마다 QA 결과와 인계 내용을 남기고,검토와 검증 없이 완료로 처리하지 말아줘.현재 세션에서 더 세밀하게 보고 싶다면 이렇게 요청할 수 있습니다.
/moonshot-phase-runner docs/implementation --execution-mode in-session-coordinator 각 시도는 새 맥락에서 진행하고,결과는 변경 파일, 실패한 확인, 다음 조치 중심으로 요약해줘.마무리
Moonshot Phase Runner는 "AI에게 일을 시키는 명령"이라기보다 긴 작업을 잃어버리지 않게 하는 실행 구조에 가깝습니다. 계획 디렉터리는 범위를 잡고, 상태 파일은 현재 위치를 기록하고, 실행 산출물은 재시도와 인계를 가능하게 하며, 검토와 검증 게이트는 성급한 완료 선언을 막습니다.
큰 작업에서 중요한 것은 빠르게 시작하는 것만이 아닙니다. 끝났다고 말할 수 있는 근거를 남기면서 계속 앞으로 가는 것입니다.
댓글
GitHub 계정으로 로그인하면 댓글을 남길 수 있습니다. 댓글은 GitHub Discussions를 통해 운영됩니다.