Moonshot Relay 소개

Workflow · 2026-06-23 · 7분 읽기

AI 코딩 도구를 쓰다 보면 처음에는 감탄이 먼저 나옵니다. 파일을 읽고, 코드를 고치고, 테스트를 실행하고, 설명까지 붙입니다. 예전 같으면 반나절 걸릴 일을 몇 분 안에 밀어붙이는 순간도 있습니다.

그런데 실무에서는 곧 다른 질문이 따라옵니다.

1정말 끝난 건가?2어떤 파일이 바뀌었지?3테스트는 어떤 기준으로 통과한 거지?4다음 사람이 이어받으면 어디서 시작해야 하지?5중간에 실패한 판단은 남아 있나?

이 문제를 반복해서 겪으면서 Moonshot Relay를 만들기 시작했습니다. 이 프로젝트는 Claude Code와 Codex를 위한 workflow harness입니다. 프롬프트 몇 개를 모아둔 저장소라기보다, AI 에이전트가 작업을 시작하고, 진행하고, 검증하고, 다시 이어받는 방식을 하나의 운영 흐름으로 묶는 장치에 가깝습니다.

왜 이런 도구가 필요했나

AI와 함께 코드를 고칠 때 가장 위험한 순간은 실패가 아닙니다. 실패는 대체로 눈에 보입니다. 빌드가 깨지고, 테스트가 실패하고, 브라우저에서 화면이 망가집니다.

더 위험한 순간은 어중간한 성공입니다. 겉으로는 그럴듯합니다. 답변은 자신 있고, 변경 파일도 있고, 설명도 매끄럽습니다. 그런데 실제로 확인해보면 이런 일이 자주 생깁니다.

• 오래된 문서를 기준으로 구현했습니다.
• 테스트를 돌렸다고 말했지만 현재 브랜치 기준이 아니었습니다.
• 빌드는 통과했지만 실제 화면에서 스타일이 깨졌습니다.
• 작업 범위가 중간에 바뀌었는데 기록이 없습니다.
• 다음 세션에서 이어받을 때 맥락을 다시 추적해야 합니다.

이 문제는 모델 성능만으로 해결되지 않습니다. 더 똑똑한 모델도 목표, 권한, 파일 경계, 검증 기준이 흐릿하면 같은 실수를 다른 속도로 반복합니다. 필요한 것은 "더 좋은 답변"보다 "더 좋은 작업 흐름"에 가깝습니다.

Moonshot Relay가 붙잡는 네 가지 순간

Moonshot Relay가 붙잡는 지점은 분명합니다. AI 작업에서 자주 흩어지는 네 가지 순간입니다.

GitHub 저장소의 README도 이 방향을 분명하게 잡고 있습니다. Moonshot Relay는 rules, agents, skills, documentation templates를 관리하고, Claude Code와 Codex에서 재사용 가능한 워크플로우를 설치해 쓰는 구조입니다. 즉, 개별 프롬프트보다 "작업을 운영하는 표면"을 먼저 봅니다.

어떻게 돌아가나

Moonshot Relay는 모델을 대신하는 별도 실행기가 아닙니다. Claude Code나 Codex가 이미 하는 작업 위에 규칙, 스킬, 에이전트, 문서 템플릿을 얹어 작업 순서를 잡아주는 런타임 프로필에 가깝습니다.

저장소 기준으로 보면 원본은 skills/, agents/, rules/, templates/, docs/public/ 같은 루트 디렉터리에 있고, 설치하면 Claude/Codex가 읽을 수 있는 계정 루트나 프로젝트 로컬 프로필로 materialize됩니다. 이때 모든 내부 스킬을 노출하지 않고, 실제 사용자가 직접 고를 수 있는 진입점은 제한합니다.

자주 쓰는 표면은 대략 이렇게 나뉩니다.

실행 중에는 .moonshot-relay/docs/tasks/, phase-status.yaml, reports/*.json, verification verdict 같은 런타임 산출물이 생길 수 있습니다. 중요한 점은 이 산출물이 제품 코드가 아니라 작업 흔적이라는 점입니다. 코드와 같이 커밋할 자료, 다음 세션이 읽을 기록, 버려야 할 scratch를 구분하는 것도 하네스의 역할입니다.

어떻게 쓰나

가장 단순한 설치는 README의 한 줄 명령입니다.

1npx -y github:munlucky/moonshot-relay install

source checkout에서 직접 설치할 때는 Node installer를 쓸 수 있습니다.

1node bin/moonshot-relay.mjs install --runtime all

설치가 끝나면 Claude Code나 Codex에서 작업 성격에 맞는 진입점을 부르면 됩니다. 예를 들어 기능 하나를 끝까지 맡기고 싶다면 작은 범위에서는 moonshot-orchestrator가 맞습니다.

1moonshot-orchestrator를 사용해서2현재 설정 화면에 알림 토글을 추가해줘.3기존 UI 패턴을 먼저 확인하고,4테스트와 브라우저 확인 결과까지 남겨줘.

작업이 여러 단계로 나뉘고 중간 산출물이 필요하면 moonshot-phase-runner 쪽이 낫습니다.

1moonshot-phase-runner docs/implementation/notification-settings2계획된 phase를 순서대로 진행하고,3각 phase마다 변경 파일, 검증 명령, 남은 리스크를 남겨줘.

여기서 핵심은 명령 이름 자체가 아닙니다. 작업을 맡길 때 목표, 범위, 검증 기준을 같이 주고, 에이전트가 끝났다고 말할 때 실제 변경 파일과 실행 증거를 함께 남기게 만드는 것입니다.

프롬프트 모음과 다른 점

좋은 프롬프트는 여전히 중요합니다. 다만 프롬프트만으로는 긴 작업을 끝까지 통제하기 어렵습니다.

예를 들어 "이 기능 구현해줘"라는 요청은 첫 답변까지는 충분할 수 있습니다. 하지만 실제 작업은 곧 더 많은 질문으로 바뀝니다.

1이 변경은 어느 파일에 들어가야 하지?2기존 패턴과 충돌하지 않나?3테스트는 어디에 추가해야 하지?4브라우저에서 확인해야 하나?5문서도 같이 바뀌어야 하나?6이 상태를 커밋해도 되나?

Moonshot Relay는 이 질문들을 매번 즉흥적으로 다시 만들지 않게 하려는 시도입니다. 작업 유형을 나누고, 필요한 컨텍스트를 확인하고, 실행 단계를 쪼개고, 검증 증거를 요구합니다. 여기서는 답변의 문장보다 작업의 흔적이 더 중요합니다.

실제 사용 장면

Moonshot Relay가 가장 먼저 떠오르는 순간은 "작업이 한 번의 수정으로 끝나지 않을 때"입니다. 예를 들면 이런 요청입니다.

1이 기능을 현재 UI 흐름에 맞춰 추가하고,2관련 한영 문구도 정리하고,3빌드와 브라우저 확인까지 끝내줘.

또는 이런 작업입니다.

현재 구조를 먼저 읽고, 무엇을 바꿀지 계획한 뒤, 작게 구현하고, 검증 결과와 남은 리스크를 남겨줘.

이때 중요한 것은 AI가 빠르게 코드를 쓰는 능력만이 아닙니다. 오히려 다음 질문에 답할 수 있어야 합니다.

• 현재 작업의 완료 기준은 무엇인가?
• 사용자가 원한 범위와 실제 변경 범위가 일치하는가?
• 어떤 검증을 했고, 어떤 검증은 못 했는가?
• 다음 사람이 이어받으면 무엇부터 보면 되는가?

이 질문에 답이 남아 있으면 AI 작업은 개인의 감보다 팀의 프로세스에 가까워집니다.

문서가 아니라 런타임이 필요한 이유

처음에는 문서를 많이 쓰면 해결될 거라고 생각했습니다. 좋은 체크리스트, 좋은 작업 규칙, 좋은 회고 문서를 만들면 충분할 것 같았습니다.

하지만 실제로는 문서만으로 부족했습니다. AI 에이전트는 매번 현재 워크스페이스에서 움직입니다. 브랜치 상태, 테스트 결과, 로컬 서버, 생성된 파일, 바뀐 정책이 모두 현재 시점의 사실입니다. 오래된 문서가 아무리 좋아도 현재 체크아웃과 맞지 않으면 오히려 위험합니다.

그래서 Moonshot Relay는 문서를 버리지 않습니다. 대신 문서가 런타임 작업과 연결되도록 설계합니다. 규칙은 실행 표면에 붙고, 검증은 실제 명령과 결과로 닫히며, 작업 기록은 다음 실행의 입력이 됩니다.

이 관점이 중요합니다. AI 시대의 문서는 "읽어두면 좋은 자료"보다 "에이전트가 다음 행동을 결정할 때 참조하는 운영 계약"에 가까워져야 합니다.

좋은 점과 불편한 점

Moonshot Relay의 가장 큰 장점은 AI 작업의 불안을 줄여준다는 점입니다. 특히 여러 파일을 건드리는 작업에서 효과가 큽니다. 계획, 실행, 검증, 기록이 분리되면 "지금 뭘 하고 있는지"가 보이고, 중간에 방향을 바꾸기도 쉬워집니다.

하지만 불편한 점도 있습니다. 아주 작은 수정에는 과합니다. 오타 하나, 문구 하나, 설정 한 줄을 바꿀 때까지 모든 단계를 거치면 속도가 느려집니다. 또 하네스가 있다고 해서 판단이 자동으로 좋아지는 것도 아닙니다. 잘못된 목표를 고정하면 더 깔끔하게 잘못된 결과가 나올 수 있습니다.

그래서 Moonshot Relay를 만능 자동화로 보지 않습니다. 작은 작업에는 가볍게, 긴 작업에는 엄격하게 쓰는 운영 도구로 봅니다.

경계 사례: 하네스가 있어도 실패하는 순간

Moonshot Relay가 있다고 해서 모든 작업이 자동으로 안전해지지는 않습니다. 특히 아래 상황에서는 하네스를 믿기보다 입력을 다시 정리해야 합니다.

누구에게 맞을까

Moonshot Relay는 이런 사람에게 잘 맞습니다.

• Codex나 Claude Code를 단순 채팅보다 실제 작업 에이전트처럼 쓰는 사람
• 여러 파일, 문서, 테스트, 브라우저 확인이 함께 얽힌 작업을 자주 하는 사람
• AI가 만든 결과를 팀에서 공유하거나 이어받아야 하는 사람
• "작업 완료"를 답변 문장이 아니라 검증 증거로 판단하고 싶은 사람

반대로, AI를 가벼운 코드 스니펫 생성기나 아이디어 메모장으로만 쓴다면 이런 구조가 과할 수 있습니다. Moonshot Relay는 속도를 내기 위한 장치이기도 하지만, 더 정확히는 속도를 냈을 때 생기는 흔들림을 잡기 위한 장치입니다.

바로 따라 해볼 체크리스트

Moonshot Relay를 쓰지 않더라도 아래 기준은 바로 적용할 수 있습니다.

• [ ]AI에게 작업을 맡기기 전에 완료 기준을 한 문장으로 적는다.
• [ ]수정 전에 현재 구조를 읽고 근거를 말하게 한다.
• [ ]검증 명령을 답변이 아니라 실제 실행 결과로 남긴다.
• [ ]실패한 검증과 생략한 검증을 분리해서 기록한다.
• [ ]다음 사람이 이어받을 수 있도록 변경 파일과 남은 리스크를 남긴다.

AI 코딩의 재미는 빠르게 결과가 나오는 데 있습니다. 하지만 오래 쓰게 만드는 힘은 결과를 믿을 수 있게 만드는 데서 나옵니다.

Moonshot Relay는 그 믿음을 프롬프트의 설득력에 맡기지 않고, 작업 흐름과 증거로 남기려는 프로젝트입니다. AI와 함께 일하면서 계속 확인하게 된 결론도 여기에 가깝습니다. AI에게 더 많은 일을 맡기려면, 먼저 일이 끝났다는 말을 더 엄격하게 다뤄야 합니다.

FAQ

Q. Moonshot Relay는 프롬프트 라이브러리인가요?

프롬프트도 포함될 수 있지만 핵심은 작업 운영 방식입니다. 목표를 고정하고, 필요한 컨텍스트를 읽고, 실행과 검증을 분리하고, 다음 세션이 이어받을 수 있게 기록하는 쪽에 가깝습니다.

Q. 혼자 쓰는 개인 프로젝트에도 필요한가요?

혼자 하는 개발 프로젝트일수록 "나중에 다시 보면 알겠지"라고 넘기기 쉽습니다. 그런데 작은 기능 하나만 해도 API 계약, 상태 처리, 테스트, 환경 변수, 로컬 실행 확인이 함께 움직입니다. 배치 작업이나 내부 자동화는 더 쉽게 꼬입니다.

Moonshot Relay가 필요한 순간은 거창한 팀 프로젝트가 아니라, 다음 날 다시 열었을 때 "어디까지 했더라?"가 나오는 순간입니다. 무엇을 바꿨고, 어떤 검증을 했고, 어디를 아직 못 봤는지가 남아 있으면 혼자 하는 작업도 훨씬 덜 흔들립니다.

댓글

GitHub 계정으로 로그인하면 댓글을 남길 수 있습니다. 댓글은 GitHub Discussions를 통해 운영됩니다.