목록으로

사례 연구

코드보다 개발 환경이 먼저 바뀐다

에이전트가 여러 프로젝트와 브랜치에서 서버를 띄우자 포트와 트래픽을 따라가기 어려워졌다. 서브도메인 라우팅과 터미널 트래픽 인스펙터, 머신 간 peer를 묶은 오픈소스 로컬 프록시 dev-proxy를 만든 과정과, 다중 프로젝트 개발에 맞춰 환경을 다시 만들며 마주친 문제를 정리한다.

포트부터 헷갈리기 시작했다

지난 글에서 개발 원칙이 다른 프로젝트를 함께 운영하는 방법을 다뤘다. 이번 글은 그렇게 개발하다가 만들게 된 도구 이야기다.

AI 에이전트와 일하면서 코드보다 먼저 바뀐 건 개발 환경이었다. 에이전트가 여러 프로젝트와 브랜치에서 동시에 서버를 띄우니 localhost 포트가 금방 늘어났고, 어느 탭이 어느 브랜치의 어느 서비스인지 헷갈리기 시작했다. 에이전트가 띄운 서버에 어떤 요청이 오가는지 한곳에서 보고 싶었지만 그럴 자리가 없었다.

그래서 dev-proxy를 만들었다. 프록시 하나가 모든 프로젝트의 서비스를 서브도메인으로 라우팅하고, 터미널 하나에 HTTP와 WebSocket 트래픽을 모아 보여 준다. MIT 라이선스로 공개했다.

Loading diagram…
접속 경로가 프록시 하나로 모이고 서브도메인이 대상을 가른다. 서비스가 다른 프로젝트나 워크트리, 다른 머신에 있어도 요청은 같은 터미널에서 보인다.

처음에는 프로젝트 하나를 워크트리로 펼쳤다

처음부터 여러 프로젝트를 돌린 건 아니다. 큰 프로젝트 하나를 git worktree로 펼쳐 놓고 여러 에이전트를 붙여 개발하는 실험부터 했다. 그래서 초기 프록시도 워크트리 단위 라우팅부터 만들었다.

워크트리가 늘자 한계가 보였다. 워크트리 파일 크기가 너무 커졌고, 바이너리 파일 충돌도 감당하기 어려웠다. 그래서 개발 방향을 다중 프로젝트로 바꿨다.

그때 만든 워크트리 라우팅은 지금도 남아 있다. 설정에 worktreeConfig를 적어 두면 명령 하나로 워크트리를 만들면서 포트까지 잡아 준다.

dev-proxy worktree create feature-auth
# git worktree add 실행
# 포트 할당: www=4101, data=4102
# .env.local 작성: PORT=4101, DATA_PORT=4102
# post-create 훅 실행: pnpm install

이후 feature-auth--www.example.dev:3000으로 들어온 요청은 4101번 포트로 간다.

portless를 보고도 계속 만든 이유

한창 만들고 있을 때 Vercel Labs에서 portless가 나왔다. 서브도메인 라우팅, 워크트리별 URL, 에이전트 친화적인 CLI까지 내가 풀던 문제를 거의 같은 방식으로 풀고 있었다. Vercel도 같은 고민을 하고 있다는 걸 보고 방향에 확신이 생겼다.

그래도 계속 만든 건 원하는 게 두 가지 더 있어서였다. 라우팅과 트래픽 인스펙터가 한 터미널 안에 있는 것, 그리고 머신 여러 대에 흩어진 서비스를 프록시 하나로 묶는 것. AI 코딩 도구가 전부 CLI로 나오는 걸 보면서 TUI를 직접 만들어 보고 싶기도 했다.

어느 도구가 더 낫다는 이야기는 아니다. 내 환경에 필요한 조건이 그랬다.

에이전트가 읽고 고칠 수 있는 설정

설계하면서 제일 신경 쓴 건 에이전트 친화성이다. 새 프로젝트를 시작할 때 "dev-proxy에 등록해 줘" 한마디로 끝내고 싶었다. 그러려면 에이전트가 어디를 읽고 어디를 고치면 되는지 분명해야 한다. 그래서 프로젝트의 라우트와 워크트리 규칙을 프로젝트 루트의 dev-proxy.config.mjs 하나에 모았다.

/** @type {import('@reopt-ai/dev-proxy').Config} */
export default {
  routes: {
    www: "http://localhost:3001",
    api: "http://localhost:4000",
    "*": "http://localhost:3001",
  },
};

서브도메인과 로컬 서비스의 대응만 적는다. *는 일치하는 서브도메인이 없을 때 쓰는 기본 경로다.

누가 어느 파일을 고치는지도 나눴다. 전역 설정과 워크트리 상태는 프로젝트 설정 파일과 따로 둔다.

파일내용고치는 쪽
~/.dev-proxy/config.json도메인, 포트, TLS, 프로젝트 목록사람 또는 CLI
dev-proxy.config.mjs프로젝트의 라우트, 워크트리 규칙사람 또는 에이전트
.dev-proxy.worktrees.json워크트리별 포트 맵CLI만

프록시는 설정 파일을 감시해 워크트리 라우팅을 바로 갱신한다. 등록되지 않은 워크트리로 요청이 들어오면 다른 서비스로 넘기지 않고 오프라인 오류 페이지를 보여 준다. 덕분에 엉뚱한 서버의 응답을 정상으로 착각할 일이 줄어든다.

처음 설치도 에이전트에게 맡길 수 있다. 아래 명령으로 스킬을 추가하고 Claude Code에 "setup dev-proxy"라고 말하면 프로젝트 구조를 살펴 라우트를 제안하고 설정 파일을 만든다. 설정이 꼬였을 때는 dev-proxy doctor로 네트워크, DNS, TLS 상태를 점검한다.

npx skills add reopt-ai/dev-proxy

peer로 머신 여러 대를 묶는다

여기서부터는 내 환경에 맞춘 기능이다. 지금은 프로젝트를 병렬로 빌드하느라 로컬 개발 머신을 여러 대 쓴다. peer 기능을 쓰면 다른 머신이 특정 서브도메인을 맡는다.

# peer 머신에서 한 번만 실행한다. 코드를 출력하고 root의 승인을 기다린다
dev-proxy peer join example.dev

# pnpm dev가 도는 동안 studio 서브도메인을 맡는다
dev-proxy peer run studio --port 3001 -- pnpm dev

승인은 root의 TUI에서 한다. 토큰을 손으로 복사할 필요가 없고, 명령이 끝나면 서브도메인 점유도 풀린다.

TLS와 인스펙터, 호스트 이름은 root에 그대로 있다. 그래서 서비스가 다른 머신으로 옮겨 가도 쿠키, OAuth 리다이렉트 URI, CORS 허용 목록을 바꾸지 않아도 된다. 프록시 하나가 여러 대를 묶어 주니 어느 머신에서 뭐가 도는지 신경 쓸 일이 줄었다.

휴대폰에서도 같은 URL로 접속한다

다른 하나는 와일드카드 DNS다. *.dev.example.com이 프록시 머신의 LAN IP를 가리키게 해 두면, 같은 네트워크의 휴대폰과 태블릿에서도 같은 URL로 바로 접속된다. 기기마다 hosts 파일을 고칠 필요가 없다.

개발 중인 프로젝트가 많을 때 여러 모바일 기기로 테스트를 빠르게 돌릴 수 있어서 생각보다 자주 썼다.

모든 요청을 터미널 하나에서 본다

지금 돌고 있는 모든 프로젝트의 요청이 터미널 하나에 흐르니 에이전트가 뭘 호출하고 어디서 막히는지 바로 보인다. 요청마다 메서드, 상태 코드, 크기, 지연 시간이 찍히고 WebSocket 연결 상태도 함께 따라간다. 헤더와 쿠키, 쿼리 파라미터를 열어 보고, 요청을 다시 보내거나 curl 명령으로 복사할 수 있다.

에이전트 친화적인 설계 몇 가지만 챙겼는데, 로컬 프록시 때문에 고민하던 문제가 거의 사라졌다.

TUI는 생각보다 어려웠다

TUI는 Ink와 React로 만들었지만 웹 화면을 만들 때와 감각이 달랐다. 키 입력에 따라 터미널에 동적으로 그려지는 방식을 이해하는 데 시간이 걸렸다. 웹처럼 요소 단위로 나뉘어 있지 않아서 인터페이스 하나를 바꾸면 화면 전체에 영향이 가는 경우가 많았다. 웹에 비해 자동화 테스트 도구가 부족한 것도 컸다.

프록시는 한 조각이었다

만들고 나서 보니 프록시는 다중 프로젝트 개발의 한 조각이었다. 여러 개발을 같은 시점에 돌리려면 빌드, 린트, CI, CD, 로컬 캐싱을 예전과 다른 관점에서 최적화해야 했다. 에이전트가 동시에 수십 번 빌드하고 테스트를 돌리니 병목이 생기지 않는 환경을 준비해야 했다. 예전에는 고민할 일이 없던 이슈도 계속 나왔다.

다중 프로젝트 개발을 시작한다면 다음 질문부터 점검할 수 있다. 내가 측정한 결과가 아니라 점검 항목의 예시다.

영역확인할 질문
라우팅사람과 에이전트가 같은 URL로 같은 서비스를 가리키는가
트래픽에이전트가 보낸 요청과 실패를 한곳에서 볼 수 있는가
빌드·테스트여러 에이전트가 동시에 돌려도 다른 작업을 막지 않는가
린트프로젝트 수가 늘어도 피드백을 기다릴 만한 시간 안에 받는가
CI·CD늘어난 변경량을 파이프라인이 감당하는가
로컬 캐시작업끼리 캐시를 공유해도 결과가 섞이지 않는가

OCLS 루프와의 연결

reopt architecture의 OCLS 루프로 보면 개발 환경도 설계 대상이다.

OCLS 단계이 사례에서 확인한 것
OWN서브도메인 하나를 지금 어느 머신이 맡고 있는가. peer list가 소유자와 연결 상태를 보여 준다
CONTRACT에이전트가 고쳐도 되는 파일과 CLI만 고치는 파일이 나뉘어 있는가
LAYER앱은 할당받은 포트만 알고, 도메인과 TLS, 인스펙터는 프록시가 맡는가
SHARPEN터미널에서 본 호출과 실패가 다음 환경 개선의 근거가 되는가

서브도메인 점유는 책임 분할을 작게 적용한 경우이고, 설정 파일의 경계는 모듈 계약과 같은 문제를 다룬다. 에이전트가 함께 쓰는 자원이라면 코드가 아니어도 누가 무엇을 바꿀 수 있는지 정해 두어야 한다.

이 사례의 한계

이 경험은 내 환경에 묶여 있다. 프로젝트 여럿을 로컬 머신 여러 대에서 돌리는 조건에 맞춰 만들었다. 서비스 하나를 머신 한 대에서 개발한다면 이 정도 구성은 필요 없다.

효과를 수치로 재지도 않았다. 고민이 거의 사라졌다는 말은 체감이고, 도입 전후의 시간이나 오류 수를 비교한 결과가 아니다.

편한 URL에는 설정 비용과 주의할 점이 따른다.

  • 휴대폰에서 접속하려면 와일드카드 DNS와 기기가 신뢰하는 인증서를 준비해야 한다.
  • 공개 DNS를 쓰면 *.dev.example.com이 사설 IP를 가리킨다는 사실을 누구나 조회할 수 있다. 실제 접속은 같은 네트워크의 기기만 가능하다.
  • 사설 IP를 돌려주는 DNS 응답을 막는 공유기도 있어서, 이때는 해당 도메인을 공유기에서 허용해야 한다.
  • 원격 peer는 HTTPS로만 붙고, peer 머신의 앱은 localhost가 아니라 0.0.0.0에서 요청을 받아야 한다.
  • 같은 서브도메인을 여러 머신이 점유하면 마지막 점유가 이긴다. 충돌이 의심되면 peer list로 소유자를 확인한다.
  • 인스펙터로 헤더와 쿠키를 볼 수 있는 만큼, 터미널 화면을 공유하거나 녹화할 때는 인증 정보가 드러나지 않는지 살펴야 한다.

프롬프트 밖에 쓴 시간

AI 코딩 역량이라고 하면 프롬프트를 떠올리기 쉽다. 올해 내 시간의 상당 부분은 이런 환경을 다시 만드는 데 들어갔다. 비슷한 문제를 계속 도구로 만들고 있고, 서비스로도 발전시키고 있다.

dev-proxy는 아래 명령으로 바로 써 볼 수 있다. 코드와 문서는 GitHub 저장소에 있다.

npm install -g @reopt-ai/dev-proxy
dev-proxy init
dev-proxy

태그

dev-proxydeveloper-environmentmulti-projectgit-worktreeOCLS

관련 패턴

  • 책임 분할결과를 소유할 주체와 책임 경계를 명확히 정의한다.
  • 모듈 계약실행 단위의 조건, 권한, 실패 경로를 계약으로 선언한다.