Cursor Gateway 구축기(1) — 요청·실행·결과를 연결하는 최소 설계

들어가며

“Cursor 쓰면 코딩이 빨라진다” — 맞아요. 혼자라면.

팀에서는 실행 속도보다 먼저 필요한 게 있어요. 요청이 어디서 왔는지, 지금 어디까지 됐는지, 결과가 어디로 갔는지 — 이게 모두가 볼 수 있는 형태로 남아야 협업이 돌아가니까요.

지난 글에서 “Cursor는 개발에 강하고, OpenClaw는 운영에 강하다. 그래서 둘을 연결하는 Gateway가 필요했다”고 했어요. 오늘은 그 Gateway를 어떻게 만들었는지, 최대한 따라할 수 있는 형태로 정리해볼게요.

1) 우리가 필요했던 건 ‘운영 루프’였어요

Cursor 같은 도구를 처음 도입하면 이렇게 시작해요.

“코드를 더 빨리 짜고 싶다”

그런데 팀이 되면 목표가 달라져요.

요청이 들어오면 실행까지 끊기지 않게 하고 싶다
누가 무엇을 했는지 남기고 싶다
결과를 다음에도 다시 쓸 수 있게 하고 싶다

요청이 문서로 고정되고 → 실행이 이어지고 → 결과가 다시 팀 자산으로 회수되는 구조. 이 루프가 굳어지면, 아무도 “그거 어떻게 됐어요?”를 물어볼 필요가 없어요.

2) Cursor CLI만으로 부족한 이유

Cursor CLI는 실행 도구로서 굉장히 유용해요. 그런데 운영 루프를 만들려고 하면 빈틈이 생겨요.

요청이 들어왔을 때 일관된 형식으로 정리하는 단계가 없어요
실행이 돌아가는 동안 “지금 어디까지?” 같은 상태를 팀이 공유할 수 없어요
끝났을 때 결과를 재사용 가능한 형태로 모으는 단계가 없어요

이 빈틈을 “사람이 더 열심히” 메우는 건 지속이 안 돼요. 그래서 Gateway가 필요했습니다.

3) Gateway가 하는 일은 딱 3가지

Gateway라고 하면 거창하게 들리지만, 기능을 줄이면 단순해요.

1) 실행을 대신 눌러준다

Cursor CLI를 호출해서 작업을 시작한다

2) 결과를 회수한다

실행 결과(로그/변경 요약/파일)를 정해진 위치로 모은다

3) 상태를 전달한다

“요청 접수됨 / 실행 중 / 완료 / 실패” 정도만이라도 외부에서 알 수 있게 한다

이 3가지만 되면 ‘요청→실행→결과’가 끊기지 않아요.

4) 최소 구성 (따라하기 버전)

“완벽한 설계”가 아니라 지금 당장 굴릴 수 있는 설계를 먼저 보여드릴게요.

구성 요소

OpenClaw: 요청을 정리하고 결과를 모으는 팀 운영 허브
Gateway(브리지 서버): 실행·회수·상태 전달
Cursor: 실제 코드 수정/리팩토링/디버깅

흐름 한눈에 보기

요청(사람)
  ↓
요청서(문서로 고정)
  ↓
Gateway가 Cursor 실행
  ↓
코드 변경/검증
  ↓
결과 회수(outbox/문서)
  ↓
다음에 재사용

실전 시나리오: “CORS 에러가 납니다”

요청서 작성: “CORS 에러 / 재현 방법: POST /api/comments 호출 / 완료 조건: 200 응답 / 산출물: outbox에 수정 요약”
Gateway 실행: 요청서를 보고 Cursor CLI 호출, 해당 파일 수정 시작
결과 회수: 수정된 파일 diff + “헤더에 Access-Control-Allow-Origin 추가” 요약을 outbox에 저장
다음 재사용: 같은 에러가 다시 나면 outbox에서 수정 요약을 꺼내서 바로 참고

이 흐름이 한 번 굳어지면, “그 에러 어떻게 고쳤더라?”를 다시 물어볼 필요가 없어요.

5) “요청서”가 먼저인 이유

Gateway 구축에서 사실 제일 중요한 건 서버가 아니라 요청서예요.

요청서는 쉽게 말하면 ‘작업 지시서’예요. 아래 4가지가 없으면, 실행이 아무리 빨라도 협업이 깨져요.

항목	이유
문제: 지금 뭐가 문제인지	없으면 엉뚱한 걸 고쳐요
확인 방법: 어떻게 재현/확인하는지	없으면 “됐는지 어떻게 알아요?” 상황
완료 조건: 뭐가 되면 끝인지	없으면 “어디까지 하면 되나요?” 루프
산출물 위치: 결과를 어디에 남길지	없으면 결과가 사라져요

이걸 문서로 고정해두면, 실행 담당자가 바뀌거나 하루가 지나도 일관된 방식으로 처리할 수 있어요.

6) 실패를 줄이는 체크리스트

Gateway는 “잘 될 때”보다 “안 될 때”가 더 중요해요. 저희가 실제로 체크하는 항목이에요.

실행 전

작업 범위가 한 문장으로 정리돼 있나? — “로그인 버튼 클릭 시 500 에러 수정”처럼 구체적이어야 해요
바꾸면 위험한 곳이 포함돼 있나? — 배포/결제/인증 관련이면 반드시 확인
되돌리는 방법(롤백)이 있나? — git stash, 브랜치, 백업 중 하나는 있어야 해요

실행 중

로그가 남고 있나? — 에러가 나도 로그가 있으면 원인을 찾을 수 있어요
중간에 멈추면 ‘실패’로 표시되나? — 조용히 멈추는 게 제일 위험해요

완료 후

무엇을 바꿨는지 10줄로 설명할 수 있나? — 못 하면 결과를 아직 모르는 거예요
결과 파일/링크가 outbox에 남았나? — 여기 없으면 팀이 재사용 못 해요
다음 사람이 보고 따라할 수 있나? — “왜 이렇게 했는지”가 한 줄이라도 있어야 해요

7) 어디까지 자동화해야 하나요?

욕심을 너무 내면 프로젝트가 산으로 가요. 저희가 추천하는 순서예요.

요청서 포맷 고정 — 가장 먼저. 나머지는 여기서 출발해요
실행 트리거(Gateway) — 요청서가 있어야 Gateway가 뭘 할지 알아요
결과 회수(outbox) — 실행이 됐으면 어디에 남길지
상태 전달 — 최소한 “진행 중/완료/실패”만이라도

이 순서로 가면 작은 성공을 계속 쌓을 수 있어요. 한 번에 다 만들려고 하면 대부분 3번에서 멈춰요.

마무리

지금 당장 시작해보고 싶다면, 서버나 자동화가 없어도 괜찮아요.

가장 자주 반복되는 작업 요청을 하나 고르세요.
요청서 4개 항목(문제 / 확인 방법 / 완료 조건 / 산출물 위치)을 메모 앱에 적어보세요.
다음에 같은 요청이 오면, 그 메모를 기준으로 처리하고 결과를 한 폴더에 남겨보세요.

이 루프가 굳어지는 것만으로 팀이 달라져요.

다음 편에서는 Gateway가 결과를 회수할 때 어떤 포맷을 쓰는지, 실패와 재시도를 어떻게 설계하는지, 팀 충돌을 줄이는 운영 규칙은 어떻게 붙이는지를 정리해볼게요.