TL;DR
커넥션 상한은 요청률을 고정해 부하를 걸고 버린 요청을 집계하면 나옵니다. 커넥션 1개당 REST 상한은 약 9,000 req/s 였습니다.
포화는 꼬리 지연에서 먼저 나타납니다. 중앙값이 움직이는 시점에는 이미 상한을 넘은 뒤입니다.

1. 문제: 상한이 어디인지 나오지 않았습니다

부하를 견디는 구조를 공부하면서 부하가 왔을 때 어디가 먼저 막히는지를 지점별로 보고 있습니다. 이번 지점은 커넥션입니다.

서비스 간 호출을 측정하면서 커넥션 수를 줄여 봤는데 처리량도 지연도 거의 그대로였습니다. 풀이 200개인데 동시 요청이 50건이라 커넥션이 병목에서 멀었기 때문입니다. 그래서 커넥션 예산을 1개로 낮추고 다시 측정했습니다. 이번에는 상한 자체가 나오지 않았습니다.

원인은 부하를 거는 방식에 있었습니다.

동시 사용자 50명으로 걸면 응답이 100 ms 로 늘어난 순간 초당 요청 수도 함께 떨어집니다. 서버가 감당하는 만큼만 부하가 도착하므로 그래프는 평형에 머무릅니다. 상한을 찾으려는 측정에서 부하가 스스로 조절되면 찾을 대상이 없어집니다.

2. 측정

요청률을 고정하고 버린 요청을 집계했습니다

k6 의 실행 모델을 constant-arrival-rate 로 바꿨습니다.

scenarios: {
  openLoop: {
    executor: 'constant-arrival-rate',   // 응답과 무관하게 초당 rate 만큼 요청
    rate: RATE,
    timeUnit: '1s',
    duration: '15s',
    preAllocatedVUs: 50,
    // 응답이 밀려 VU 가 모두 점유되면 k6 가 요청을 보내지 않고
    // dropped_iterations 로 집계한다. 그 값이 과부하 지표가 된다.
    maxVUs: 400,
  },
}

가상 사용자를 400개까지 확보해 두고 그것이 모두 점유되면 k6 는 요청을 보내지 않고 dropped_iterations 로 집계합니다. 서버가 감당하지 못한 양이 부하 도구 쪽에 숫자로 남습니다. 회차가 15초이므로 버린 요청의 모수는 요청률 × 15 입니다.

커넥션만 줄였습니다

커넥션을 병목으로 만드는 방법은 둘입니다. 부하를 올리거나 커넥션을 줄이는 것입니다. 앞을 택하면 CPU 포화와 부하 도구 경합이 함께 들어와 무엇이 막았는지 판정할 수 없습니다. 그래서 요청률 사다리는 그대로 두고 커넥션 예산만 1개로 낮췄습니다.

회차는 구성마다 하나입니다

반복 측정은 하지 않았습니다. 회차마다 서버를 새로 띄우고 워밍업을 본 회차와 분리했지만, 앞선 측정에서 같은 조건이 12% 차이로 나온 적이 있습니다. 그 크기 안쪽 차이는 뒤에서 신호로 읽지 않습니다.

3. 결과

달성 요청률이 목표를 따라가지 못하는 지점이 상한입니다

REST, 커넥션 풀 1개로 요청률을 두 배씩 올린 결과입니다.

6,400 까지는 목표를 거의 그대로 달성합니다. 9,600 에서 8,812 로 미달하고 12,800 을 줘도 9,043 에서 멈춥니다. 커넥션 1개당 REST 상한은 약 9,000 req/s 입니다.

버린 요청이 같은 판정을 뒷받침합니다. 6,400 까지 1% 안쪽이고 9,600 에서 8.1%, 12,800 에서 29% 입니다. 목표를 두 배로 올렸는데 달성은 231 req/s 만 늘고 버린 양은 다섯 배 가까이 됐습니다.

저부하 구간의 p50 이 오히려 큰 것(400 에서 309 µs, 6,400 에서 72 µs)은 회차가 15초로 짧아 워밍업 영향이 남은 것으로 봅니다. 상한 판정에는 쓰지 않았습니다.

꼬리부터 무너집니다

6,400 은 REST 가 목표를 달성한 구간입니다. 같은 회차를 gRPC 와 나란히 놓으면 백분위마다 그림이 달라집니다.

중앙값으로는 두 전송이 같고 REST 가 오히려 조금 빠릅니다. 그런데 p90 에서 2.5배, p95 에서 7.3배로 뒤로 갈수록 벌어집니다.

커넥션이 모자라지는 신호는 꼬리에만 나타납니다. 커넥션 1개에 요청이 순서를 기다리면 대부분은 기다리지 않고 통과하고 일부만 앞의 요청이 끝날 때까지 대기합니다. 그 일부가 백분위 뒤쪽에 쌓입니다.

중앙값이 움직이면 이미 늦었습니다

사다리를 한 칸 올리자 p50 이 72 µs 에서 33.4 ms 로 460배가 됐습니다. 중앙값까지 밀린 상태입니다.

그리고 이 구간에서 REST 는 목표를 달성하지 못했습니다. 중앙값이 나빠졌다면 상한을 이미 넘은 뒤입니다. 상한을 찾으려면 중앙값이 아니라 꼬리와 버린 요청을 봐야 합니다.

풀을 늘리면 처리량은 돌아오고 꼬리는 남습니다

커넥션이 상한이라면 커넥션을 늘리는 것이 첫 선택입니다. 풀을 4개로 올려 12,800 목표를 다시 걸었습니다.

처리량은 돌아옵니다. 12,800 목표에서 12,328 req/s 를 달성하고 중앙값도 118 µs 로 정상입니다. 그런데 p90 이 10.3 ms 로 중앙값의 87배입니다. 중앙값만 걸린 대시보드에서는 정상으로 읽히는 상태입니다.

풀 4개로 9,600 목표를 건 회차도 있습니다. 그쪽 p90 은 18.3 ms 로 요청률이 더 낮은데 12,800 회차보다 나쁩니다. 회차가 하나씩이라 이 역전은 신호로 읽지 않았습니다.

같은 목표를 gRPC 는 커넥션 1개로 처리했습니다. 12,800 에서 12,625 req/s 를 달성하고 버린 요청이 1.4% 입니다. HTTP/2 는 한 커넥션 안에서 스트림을 나눠 동시에 실어 보내므로 동시 요청 수만큼 커넥션이 필요하지 않습니다.

4. 마치며

커넥션을 첫 지점으로 둔 이유는 이 값이 호출자 수만큼 곱해지기 때문입니다. 여러 서비스가 한 서비스로 몰리는 구조에서 호출자가 200개면 풀 4개는 피호출 쪽에서 커넥션 800개입니다. 파일 디스크립터와 소켓 메모리와 로드밸런서 커넥션 한계에 그대로 걸립니다. 단일 인스턴스에서 「풀을 늘리면 된다」로 끝나는 판단이 규모에서 뒤집히는 자리입니다.

측정에서 남는 것은 값이 아니라 판정 순서입니다. 9,000 req/s 는 이 노트북의 이 구성에서 나온 값이고 다른 환경에 그대로 쓰이지 않습니다. 요청률을 고정해 부하를 걸고 달성 요청률과 버린 요청으로 상한을 찾은 뒤 꼬리에서 신호를 읽는 순서는 환경이 바뀌어도 남습니다. 같은 순서를 DB 커넥션이나 스레드 풀에 그대로 적용할 수 있습니다.

범위를 적습니다. 단일 호스트라 왕복 지연이 거의 0이고 데이터 계층이 인메모리라 대기 시간이 짧습니다. 풀 1개는 실무 설정이 아니므로 절대 처리량보다 배수를 봐야 합니다. 회차는 구성마다 하나이고 반복 측정이 없습니다.

전체 측정 설계와 gRPC 를 포함한 9개 지표 비교는 MSA 는 왜 gRPC 를 쓰는가 에 있습니다. 측정 코드는 grpc-vs-rest-lab 에 정리해 두었습니다.

이 글은 Claude와 함께 작업했습니다.

TL;DR
OpenTelemetry 로 요청 단위 식별자를 전파해 오류가 난 지점의 trace_id 하나로 전 구간을 확인합니다.
사람이든 AI 든 같은 값 하나로 들어가므로 로그를 서비스별로 모아 정리할 일이 없습니다.

1. 문제: 요청 하나를 특정할 방법이 없었습니다

고객사마다 클러스터를 구축해 납품하는 B2B 제품을 MSA 구조로 운영하고 있습니다. 요청 하나가 지나는 경로는 이렇습니다.

flowchart LR
  C(["클라이언트"])
  subgraph K8S["Kubernetes 클러스터"]
    direction LR
    GW["gateway"]
    subgraph BE["backend services"]
      direction TB
      S1["service-a"]
      S2["service-b"]
      S3["…"]
    end
  end
  C --> GW --> S1
  S1 --> S2
  S1 --> S3

장애나 문의는 보고를 거쳐 조치로 넘어옵니다. 조치는 에러 로그를 찾는 데서 시작하는데, 여기서 셋에 걸렸습니다.

로그는 아래와 같은 포맷으로 수집됩니다. 같은 시각대에 두 사용자의 요청이 섞여 있습니다.

14:55:52.676 F {"level":"INFO","requestId":"a1f2","module":"gateway","msg":"POST /v1/volumes"}
14:55:52.681 F {"level":"INFO","requestId":"77c0","module":"gateway","msg":"GET /v1/instances"}
14:55:52.694 F {"level":"INFO","requestId":"a1f2","module":"service-a","msg":"volume create accepted"}
14:55:52.755 F {"level":"ERROR","requestId":"a1f2","module":"service-b","msg":"upstream call timeout"}
14:55:52.802 F {"level":"ERROR","module":"service-c","msg":"scheduled cleanup failed"}
14:55:52.913 F {"level":"INFO","requestId":"a1f2","module":"gateway","msg":"500 response"}

오류가 두 건입니다. 넷째 줄은 사용자 요청에서, 다섯째 줄은 스케줄 배치에서 났습니다.

requestId 가 있는데 왜 부족한지를 봅니다. 이 값은 gateway 가 헤더로 실어 주고 각 서비스가 받아서 자기 로그에 기록합니다. a1f2 로 걸러내면 사용자 요청 쪽 줄은 남습니다. 거기까지입니다.

그래서 오류 줄을 찾아도 그 요청이 어디를 거쳐 왔고 어디서 시간을 쓴 것인지는 알 수 없습니다.

2. 해결방안 모색

필요한 것을 먼저 적었습니다

도구를 고르기 전에 조건을 적었습니다. 결과적으로 이 순서가 이후 판단을 전부 결정했습니다.

후보는 셋이었습니다

세 번째는 실제로 해 본 적이 있는 방식입니다.

4년 전에도 같은 조건이었습니다

2022년 삼성카드 통합플랫폼 모니모에서 어뷰징 증적을 만들 때 세 번째 방식을 썼습니다. Spring MDC 로 고객번호를 로그에 주입하고 포맷을 공통화한 뒤 Kibana KQL 템플릿으로 조회했습니다. 동작은 했습니다. 다만 추적 단위가 요청이 아니라 사용자와 기간이었고 서비스를 연결하는 일은 끝까지 사람이 했습니다.

바꿔야 할 것은 단위(사용자 → 요청)와 연결 주체(사람 → 데이터)였습니다.

여기서 OpenTelemetry 를 알게 됐습니다

찾던 것은 “요청 단위 식별자를 정의하고 구현 방식과 무관하게 전파하는 방법” 이었습니다. 그 자리에 이미 규격이 있었습니다.

자체 정의 대신 이 규격을 고른 이유는 유지 주체가 우리가 아니라는 점입니다. OpenTelemetry 는 2026년 5월 CNCF 졸업 프로젝트가 됐고 프로젝트 속도는 쿠버네티스 다음입니다. 우리가 떠나도 규격은 남습니다.

OpenTelemetry 가 다루는 신호는 trace·metric·log 셋입니다. 메트릭은 인프라 팀이 맡고 있어 이번에 적용한 것은 추적성 확보에 필요한 trace 까지입니다.

용어는 셋만 알면 충분합니다.

4년 전에는 이 규격을 몰랐고 수집 계층을 담당하지도 않았습니다. 그래서 식별자도 조회 규칙도 직접 정의했습니다. 구조로는 같은 일인데 누가 그 정의를 유지하는가가 달랐습니다.

3. 적용

trace_id 를 서비스마다 전파했습니다

앱 쪽은 의존성과 설정입니다.

// 트레이스 계측 + OTLP export
implementation 'io.micrometer:micrometer-tracing-bridge-otel'
implementation 'io.opentelemetry:opentelemetry-exporter-otlp'

# 전송할 환경에만 둡니다
management:
  otlp:
    tracing:
      endpoint: http://collector:4318/v1/traces

endpoint 를 지정한 환경만 전송하고 미지정 환경은 exporter 가 생성되지 않습니다. 게이트를 따로 두지 않아도 다른 환경에 영향이 없는 이유입니다.

구조화 로깅은 Spring Boot 3.4 부터 logging.structured.format 설정만으로 됩니다. 그 이상 버전을 쓰고 있어 로그 포맷과 전송 모두 설정으로 끝났습니다.

인프라 쪽은 조건부 서브차트로 구성했습니다. 로그는 필수이고 트레이스와 Collector 는 게이트로 두어 끄면 렌더링되지 않고 워크로드도 생기지 않습니다.

로그는 JSON 으로 통일했습니다

trace_id 를 실어도 로그가 평문이면 그 값으로 조회할 수 없습니다. 그래서 전 서비스의 로그 포맷을 JSON 으로 통일했습니다.

부수 효과가 하나 있었습니다. 수집기(fluent-bit)가 앱 로그 포맷을 알고 파싱하던 결합이 끊겼습니다. 앱이 구조를 갖춰 내보내면 수집기는 그대로 전달하고 해석은 조회 시점의 몫이 됩니다. 앱이 로그를 바꿀 때마다 수집기 설정을 함께 고치던 일이 없어집니다.

샘플링은 넣지 않았습니다

head 기준 100% 이고 Collector tail 샘플링도 없습니다. tail 샘플링은 트래픽이 많은 환경에서 “다 저장하면 비싸니 에러와 느린 것만 남기는” 장치입니다. 고객사당 트래픽이 크지 않은 우리 서비스에서는 다 저장해도 양이 적어 그 장치가 필요하지 않습니다.

전수 수집이 두 가지를 함께 성립시킵니다.

보존도 같은 이유로 늘렸습니다. 초기 보존이 24시간이었는데 보고와 조치 시작 사이의 시간을 감안하면 짧습니다. 100% 로 2주를 담아도 볼륨 용량 안에 들어오므로 답은 샘플링이 아니라 보존 상향이었습니다.

4. 결과

문제로 적었던 세 가지가 어떻게 됐는지 그대로 대응시킵니다.

JWT 클레임의 회원 번호도 로그 컨텍스트에 싣고 있습니다. 발생 시각과 회원 번호로 요청을 특정하고 거기서 trace_id 로 나머지 구간을 따라갑니다. 4년 전 MDC 로 만든 사용자 추적과 이번 요청 추적이 여기서 합쳐집니다.

분석을 AI 에게 맡길 때 값이 가장 크게 나왔습니다

로그는 Loki 스택으로 수집하고 있어 에이전트에게 조회 권한을 주면 그대로 읽습니다. 추적성을 확보하고 나서 분석 속도가 올라갔고 잘못 판단하는 일이 줄었습니다.

오류가 줄어드는 지점이 여기입니다. 에이전트가 관계를 추측하면 그럴듯한 오답이 나옵니다. 추측할 자리를 없애면 그 오답도 없어집니다.

샘플링을 넣지 않은 판단이 여기서도 작용합니다. 「그 요청은 수집되지 않았습니다」 라는 답이 나오면 맡길 수 있는 범위도 반쪽이 됩니다.

5. 마치며

4년 전에도 같은 문제를 풀었지만 그때는 식별자와 조회 규칙을 직접 정의했습니다. 동작은 했고 성과도 났습니다. 다만 그 정의는 우리 팀 안에서만 통했고 서비스가 늘면 규칙도 같이 늘어나는 구조였습니다.

이번에는 클라우드 네이티브 환경에서 통용되는 표준을 찾아 같은 자리를 채웠습니다. 관측성 수집을 OpenTelemetry 규격에 맞추자 추적성이 따라왔습니다. 같은 문제를 두 번 푸는 동안 달라진 것은 문제 해결 여부가 아니라 그 해법이 조직 밖에서도 통하는가였습니다.

여기까지가 이번에 적용한 범위입니다. 메트릭에서 트레이스로 가는 역추적은 아직 적용하지 않았습니다. exemplar 를 추가하면 지표의 이상 구간에서 바로 그 요청으로 내려갈 수 있습니다. 지금은 로그에서 트레이스로 가는 한 방향입니다.

이 글은 Claude와 함께 작업했습니다.

TL;DR
지침 문서를 영어로 옮겨 토큰을 아끼려다 접었습니다. 문서 파일은 4분의 1이 줄었는데 실제 비용은 1%도 줄지 않았습니다.

• 파일 크기와 실제 비용은 같은 값이 아닙니다. 지침은 세션마다 캐시에 한 번 올라간 뒤 10분의 1 단가로 읽히고 그마저도 전체 컨텍스트의 일부입니다.
• 비용이든 지시 준수든 손댈 곳은 문서의 언어가 아니라 문서에 든 지시였습니다.

지침이 쌓이면서 생긴 질문

Claude Code 에서 쓰는 에이전트 플러그인을 1년 가까이 키워 왔습니다. 스킬이 늘고 규칙이 쌓이면서 마크다운과 JSON 이 63개, 125,311 토큰이 됐습니다. 한국어 글자 비중은 62.5%입니다.

여기서 “지침을 영어로 쓰면 토큰이 준다”는 이야기를 접했습니다. 근거는 명확해 보였습니다. 한국어는 같은 정보를 담을 때 영어의 약 2.36배 토큰을 씁니다. 단어당 토큰 수는 영어가 1.2~1.4, 한국어가 1.5~2.3입니다.

한국어 문서 절반 이상을 영어로 옮기면 절반 가까이 줄어든다는 계산이 나옵니다. 계획도 세웠습니다. 절차와 판정 로직은 영어로 옮기고 사람이 읽는 README 와 설계 문서는 한국어로 남기는 방식입니다.

문서 기준 측정: 25%

옮기기 전에 측정하기로 했습니다. 레포에서 성격이 다른 세 군데를 골라 뜻이 같은 영어로 다시 썼습니다. 조건은 정보량을 줄이지 않는 것입니다. 항목을 빼거나 조건을 뭉뚱그리면 절감이 아니라 삭제이므로, 표·코드·파일 경로를 그대로 두고 문장만 옮겼습니다.

실제로 옮긴 한 항목입니다.

- **GATE 0 (대외비 가드, 필수)**: 퍼블릭 리모트 대상 텍스트(이슈·PR 본문/제목/코멘트,
  커밋 메시지, 릴리즈 노트) 생성 직전 references/confidential-guard.md 적용.
  히트 시 하드 차단. 가이드 단계에서 키워드를 피해 작성하고,
  `scripts/pre-tool-use.mjs` 훅이 최종 재검증한다.

- **GATE 0 (confidentiality guard, required)**: Apply references/confidential-guard.md
  immediately before generating any text bound for a public remote (issue/PR body,
  title, comment; commit message; release note). A hit is a hard block. Write around
  the keywords during the guide step; the `scripts/pre-tool-use.mjs` hook re-checks
  at the end.

103 토큰에서 81 토큰, 21.4% 줄었습니다. 두 파일 경로만 해도 12 토큰이 양쪽에 똑같이 남아 있습니다. 세 군데의 결과입니다.

평균 25%였습니다. 기대했던 50%의 절반입니다.

차이의 원인은 문서 구성에 있었습니다. 2.36배라는 배율은 순수 산문을 옮겼을 때 나오는 값입니다. 지침 문서는 순수 산문이 아닙니다.

표 구분자, 파일 경로, 코드 블록, 명령어, 스킬 이름, 마크다운 문법은 번역 전후 모두 ASCII 로 남습니다. 번역해도 그대로 남는 이 부분이 배율을 끌어내립니다. 여기까지는 기대보다 작을 뿐 방향은 맞았습니다.

파일 크기와 실제 비용의 간격

문제는 25%가 무엇에 대한 25%인가입니다. 파일의 토큰 수는 디스크 위의 값입니다. 실제로 지불하는 것은 요청마다 모델에 들어가는 입력 토큰이고 둘 사이에는 두 단계가 끼어 있습니다.

첫 번째는 로딩 시점입니다. 스킬은 필요할 때만 읽히므로 레포 총량이 그대로 컨텍스트에 올라가지 않습니다. 세션 성격별로 측정했습니다.

콘텐츠 세션 34,403 중 25,572, 그러니까 74%가 문체 규칙 하나였습니다. 그런데 이 파일은 한국어 문장을 판정 대상으로 삼는 규칙 모음입니다. 규칙 본문에 한국어 예시와 정규식이 들어 있어 옮기면 판정 대상은 한국어인데 규칙만 영어가 됩니다. 절감 여지가 가장 큰 파일이 가장 옮기기 어려운 파일이었습니다.

두 번째가 더 컸습니다. 프롬프트 캐싱입니다.

실사용 로그 측정

Claude Code 는 세션 기록을 ~/.claude/projects/ 아래 JSONL 로 남깁니다. 각 어시스턴트 턴에 usage 가 붙어 있고 여기에 캐시 관련 필드가 들어 있습니다.

import json, glob
totals = {"input_tokens": 0, "cache_creation_input_tokens": 0,
          "cache_read_input_tokens": 0, "output_tokens": 0}
turns = 0
for path in glob.glob("~/.claude/projects/<프로젝트>/*.jsonl"):
    for line in open(path, encoding="utf-8"):
        usage = (json.loads(line).get("message") or {}).get("usage")
        if not usage:
            continue
        turns += 1
        for key in totals:
            totals[key] += usage.get(key, 0)

이 프로젝트 디렉토리의 세션 17개, 6,053턴을 집계한 결과입니다.

입력 토큰의 97%가 캐시 읽기였습니다. 단가를 반영해도 입력 비용의 61.6%를 캐시 읽기가 차지합니다. 지침 문서는 세션 시작 시 한 번 캐시에 올라가고 그다음부터는 매 턴 1/10 단가로 읽힙니다.

여기에 컨텍스트 크기까지 더해집니다. 턴당 평균 캐시 읽기가 263,977 토큰이었습니다. 이슈 플로우 지침 17,393은 그 6.6%이고 절감분 4,300은 1.63%입니다. 나머지는 대화 이력, 읽은 파일, 도구 결과입니다.

지침 4,300 토큰은 세션 시작 시 한 번 캐시에 기록되고 이후 모든 턴에서 읽힙니다. 두 경로에 단가를 적용해 전체 입력 비용과 비교했습니다.

캐시 읽기 절감  4,300 × 6,053턴  × 0.1배 =   2,602,790
캐시 생성 절감  4,300 × 17세션   × 2.0배 =     146,200
                                            ----------
                                             2,748,990

전체 입력 비용  109,383 × 1.0
              + 49,759,569 × 2.0
              + 1,597,855,174 × 0.1        = 259,414,038

절감 비율      2,748,990 / 259,414,038     = 1.06%

콘텐츠 세션에도 같은 계산을 적용한 결과입니다.

파일에서 4분의 1을 덜어내도 실제 비용은 100분의 1만 줄어듭니다.

전환을 접은 이유

토큰이 근거였다면 1%로는 부족합니다. 남는 근거는 영어 지시가 더 잘 지켜진다는 쪽이었습니다. 11개 과제를 비교한 연구에서 비모국어(영어) 프롬프트가 평균 1위, 혼용 2위, 모국어 3위로 나옵니다.

이 방향을 레포에 옮기기 전에 확인할 곳이 있었습니다. Anthropic 은 모델 세대가 바뀔 때마다 프롬프트를 어떻게 손볼지 마이그레이션 문서로 공개합니다. 지금 쓰는 세대의 항목을 열어 보니 언어는 목록에 없었습니다.

지시가 지켜지는 정도를 올리려면 언어를 바꾸는 게 아니라 이 목록을 맞추면 됩니다. 삭제 두 건에 추가 두 건이니 지시를 걷어내라는 방향도 아닙니다. 대조해 보니 삭제 대상은 이미 없었고 추가 대상도 들어 있었습니다. 영어 전환으로 기대하던 몫을 다른 경로가 이미 가져간 상태였습니다.

반대로 치르는 비용은 구체적이었습니다. 영어 시스템 프롬프트는 비영어 생성에 대한 통제력이 약해집니다. 응답과 산출물이 전부 한국어인 환경에서는 출력 언어를 따로 고정해야 합니다.

스킬 설명문의 한국어 트리거 키워드는 자연어 라우팅이 스킬을 찾는 단서라 지우면 라우팅이 끊깁니다. 문체 규칙은 앞서 본 이유로 옮길 수 없습니다. 1%를 얻으려고 라우팅·출력 언어·문체 규칙 세 곳에 고장 날 자리를 만드는 셈이었습니다. 전환하지 않기로 했습니다.

남은 판단 기준

이 측정에서 남은 것은 결론보다 판단 기준이었습니다. 언어를 바꾸는 일은 같은 자료를 짧게 만들 뿐 그 자료가 매 턴 실린다는 사실을 바꾸지 않습니다. 비용을 줄이려면 물어야 할 질문은 “이 문서를 짧게 쓸 수 있는가”가 아니라 “이 문서가 매 턴 실릴 값을 하는가”입니다.

정확도 쪽도 같은 자리로 돌아왔습니다. 매 턴 실리는 자료를 참조 링크 뒤로 보내거나, 모델이 이미 아는 것을 지우거나, 아무것도 바꾸지 않는 지시를 걷어내는 쪽이 양도 크고 고장 위험도 없습니다.

측정의 한계와 재현

두 가지 한계가 있습니다. 세션에서 Anthropic 토크나이저에 접근할 경로가 없어 GPT-4o 계열 토크나이저를 대리 지표로 썼으므로 25%는 근삿값입니다. 표본도 1인 사용 기록 17세션이라 “일반적으로 1%”가 아니라 “이 사용 패턴에서 1%”입니다. 컨텍스트가 264K까지 커지는 패턴이 전제고 짧은 세션 위주라면 지침 비중이 커져 결과가 달라집니다.

집계 코드는 위에 그대로 옮겼습니다. Claude Code 를 쓰고 있다면 자기 프로젝트 디렉토리에 돌려 캐시 읽기 비중과 턴당 컨텍스트를 확인할 수 있습니다. 그 두 값이 저와 다르면 이 글의 1%도 달라집니다.

참고

• Working with Chinese, Japanese, and Korean text in Generative AI pipelines (한국어 약 2.36배)
• Native vs Non-Native Language Prompting: A Comparative Analysis (11개 과제 비교)
• Claude Model Migration Guide (세대별 프롬프트 조정 항목)
• Measuring and Controlling Instruction (In)Stability in Language Model Dialogs (영어 시스템 프롬프트의 비영어 생성 통제력)
• KORMo: Korean Open Reasoning Model for Everyone (토크나이저별 단어당 토큰 수)

이 글은 Claude와 함께 작업했습니다.

문제
MSA 에서 서비스 간 통신을 gRPC 로 두는 이유는 보통 속도로 설명됩니다.
그런데 그 근거로 “7~10배 빠르다”와 “작은 페이로드에서는 차이가 없다”가 함께 돌아다닙니다.

결과
단건 조회에서 gRPC 가 더 느렸습니다. REST 의 0.88배, 가상 스레드 REST 대비 0.76배입니다.
빨라지는 구간은 다건뿐이고 1,000건에서 1.56배입니다.
조건과 무관하게 남은 것은 커넥션 50배 절감과 스키마 계약이었습니다.

범위
측정 환경은 Java 21 · Spring Boot 3.5 입니다. 기준선으로 쓴 가상 스레드가 Java 21 기능이라 스레드 모델 비교는 이 스택에 묶입니다.
위 배수는 DB 를 뺀 인메모리 구성에서 나온 값입니다. 프로토콜 오버헤드의 상한이고 실제 서비스에서는 DB 시간에 묻힙니다.
그래서 gRPC 를 쓸지가 아니라 어떤 조건에서 이득이 남는지를 다룹니다.

1. 속도 때문일까?

MSA 에서 서비스 간 통신을 gRPC 로 두는 이유를 찾으면 대개 속도가 먼저 나옵니다. 그런데 그 근거로 붙는 수치가 “REST 보다 7~10배 빠르다” 와 “작은 페이로드에서는 차이가 없다” 로 나뉩니다. 둘 다 맞는 말이라면 각각 맞는 조건이 서로 다른 것입니다. 그 조건을 모르면 도입 판단이 먼저 읽은 글에 끌려갑니다.

찾아본 결과가 예상과 달랐습니다. gRPC 는 2015년 기술이고 Kubernetes 는 2022년부터 1급으로 다뤘습니다. 그렇게 다룰 이유가 있다는 뜻인데, 10년이 지나도 채택 근거의 수치가 정리되어 있지 않다는 것은 그 이유가 속도만은 아닐 가능성을 뜻합니다. 속도라고 짚을 근거도 헤더와 필드명을 덜 실으니 전송 바이트가 줄어 빠를 것이라는 추측 수준이었습니다.

그래서 두 구성이 어디서 다른지부터 봤습니다.

2. 두 구성의 차이

전송과 직렬화가 짝을 이룬 두 구성입니다. 항목별로 비교해 두면 뒤의 결과가 어디서 오는지 읽힙니다.

커넥션당 1건이 뒤에서 결론을 뒤집는 조건입니다. HTTP/1.1 은 한 커넥션에 요청 하나를 실어 보내고 응답을 기다립니다. 그래서 동시 요청 수만큼 커넥션이 필요합니다. HTTP/2 는 한 커넥션 안에서 스트림을 나눠 동시에 실어 보냅니다.

HTTP/1.1   동시 요청 3건 = 커넥션 3개
  conn 1   [req1] -> [res1]
  conn 2   [req2] -> [res2]
  conn 3   [req3] -> [res3]

HTTP/2     동시 요청 3건 = 커넥션 1개
  conn 1   [req1] -> [res1]   stream 1
           [req2] -> [res2]   stream 2
           [req3] -> [res3]   stream 3

브라우저 직접 호출 불가는 프런트엔드 대면 구간의 제약입니다. gRPC 는 호출 상태(grpc-status 성공·오류 코드)를 HTTP/2 trailer 에 싣는데, trailer 는 본문 뒤에 오는 헤더라 브라우저 fetch 로 읽을 수 없습니다. 그래서 항상 중간 계층(grpc-gateway 같은 변환 계층)이 필요합니다.

확인 대상은 표에서 나왔습니다.

1. 얼마나 빠른가
   페이로드 크기별로 나눠 차이가 커지는 구간과 사라지는 구간을 찾습니다.
2. 무엇이 빠르게 만드는가
   Protobuf 직렬화인지 HTTP/2 다중화인지 구분합니다. 둘을 묶어 두면 “넣었는데 안 빨라졌다”의 원인을 짚을 수 없습니다.

3. 어떻게 측정할까?

측정 조건을 후보와 함께 적습니다. 선택하지 않은 쪽을 밝히지 않으면 결과가 조건에 얼마나 매여 있는지 알 수 없습니다.

두 번째 항목은 실제로 사고가 났던 자리입니다. 부하 도구가 Protobuf 를 동적으로 파싱하는 비용 때문에 “gRPC 가 3.3배 느리다”는 잘못된 결론이 먼저 나왔습니다.

전송만 바꿨다는 근거

헥사고날 아키텍처라 도메인과 유스케이스는 그대로 두고 아웃포트 어댑터만 바꿔 측정했습니다.

public interface ProfileLookupPort {
  Transport transport();          // 이 구현이 담당하는 전송 방식
  LookupResult list(int size);
}

// REST 구현: 선언형 HTTP 클라이언트에 위임
public class ProfileLookupRestPortImpl implements ProfileLookupPort {
  private final ProfileHttpClient profileHttpClient;
  public Transport transport() { return Transport.REST; }
}

// gRPC 구현: 생성된 스텁에 위임
public class ProfileLookupGrpcPortImpl implements ProfileLookupPort {
  private final ProfileServiceGrpc.ProfileServiceBlockingStub profileStub;
  public Transport transport() { return Transport.GRPC; }
}

커넥션 조건을 맞춘 근거

gRPC 채널은 커넥션과 스트림 다중화를 스스로 관리합니다. REST 쪽을 기본 설정으로 두면 gRPC 에만 재사용 이득이 생깁니다. 그래서 양쪽 다 명시했습니다.

// REST: 커넥션 풀 상한을 설정값으로 고정
PoolingHttpClientConnectionManagerBuilder.create()
    .setMaxConnTotal(properties.maxConnections())
    .setMaxConnPerRoute(properties.maxConnections())
    .build();

// gRPC: 채널 하나를 애플리케이션 수명 동안 재사용
ManagedChannelBuilder.forAddress(properties.grpcHost(), properties.grpcPort())
    .usePlaintext()   // 양쪽 모두 평문. TLS 핸드셰이크가 차이에 섞이지 않게
    .build();

4. 페이로드 크기별 결과

Java 21 · 50 VU · 30초 · 단일 호스트(M2 Pro 12코어 · 16GB)입니다. 상류는 호출 측이 측정한 피호출 서비스 왕복 시간입니다. 워밍업은 별도로 실행하고 회차마다 서버를 새로 띄웠습니다. 앞선 부하가 늘려놓은 스레드가 남은 JVM 에서 측정하면 같은 조건이 12% 낮게 나옵니다.

가상 스레드는 OS 스레드를 점유하지 않고 JVM 이 스케줄하는 경량 실행 단위입니다. 같은 동시 요청 50에서 플랫폼 스레드는 38~50개까지 늘어나는데 가상 스레드는 캐리어 12개로 고정됐습니다. 그래서 스레드 수가 병목인 구간에서만 이득이 나옵니다.

9개 지표 중 gRPC 가 6개, 가상 스레드 REST 가 3개에서 우위입니다. 가상 스레드가 우위인 3개는 모두 단건이고, gRPC 가 우위인 6개는 다건 3개와 페이로드 크기에 무관한 3개(커넥션·CPU·전송량)입니다. 플랫폼 스레드 REST 는 한 항목도 없습니다.

배수로 보면 단건은 플랫폼 대비 0.88배, 가상 대비 0.76배입니다. 기준선을 플랫폼으로 잡으면 gRPC 이득이 커 보입니다. 1,000건은 1.56배와 1.57배로 기준선과 무관한데, 직렬화 비용은 스레드 모델로 줄지 않기 때문입니다.

가상 스레드는 단건에서만 이득입니다. 1건에서 처리량 1.15배, 최대 지연 3.4배 개선인데 1,000건에서는 0.99배로 사라집니다. 병목이 스레드 모델에서 직렬화 CPU 로 옮겨가면 손댈 곳이 없습니다.

5. 커넥션이 모자라면 뒤집힌다

앞 회차는 풀 200 에 동시 요청 50 이라 커넥션이 병목에서 멀어서, 50개 대 1개라는 차이가 지연에도 처리량에도 나타나지 않았습니다. 그래서 이번에는 커넥션을 제한한 상태로 비교했습니다. 부하를 올리면 CPU 포화와 도구 경합이 섞이므로 부하는 그대로 두고 커넥션 예산만 양쪽 1개로 낮췄습니다.

부하는 k6 로 걸었고 실행 모델은 요청률 고정입니다. 회차가 15초로 짧아 p99 이상은 표본이 부족하므로 p95 까지만 봅니다.

12,800 목표에서 REST 는 9,043 req/s 에서 멈추고 29% 를 버립니다. 같은 목표를 gRPC 는 커넥션 1개로 12,625 req/s 까지 처리하고 1.4% 만 버립니다. HTTP/2 가 한 커넥션 안에서 스트림을 나눠 동시에 실어 보내므로 동시 요청 수만큼 커넥션이 필요하지 않기 때문입니다.

gRPC 쪽 상한은 이 회차에서 찾지 못했습니다. 12,800 구간에서 피호출 서비스 CPU 가 15초 부하에 15.7초, 코어 하나를 채우는 수준이었습니다. 그 위는 커넥션이 아니라 CPU 에 먼저 막히므로 gRPC 의 커넥션 한계는 이 조건에서 관측되지 않습니다.

차이는 꼬리 지연에서 먼저 나타납니다. 6,400 구간에서 p50 은 거의 같은데(72 대 79 µs) p90 에서 2.5배, p95 에서 7.3배로 뒤로 갈수록 벌어집니다. 중앙값으로는 커넥션 포화를 판정할 수 없습니다.

REST 쪽 요청률 사다리 전체와 상한을 찾는 판정 순서, 풀을 4개로 늘렸을 때 처리량이 돌아와도 남는 꼬리는 부하테스트로 커넥션 상한 찾기 에 따로 정리했습니다.

결론은 우열이 아니라 교환 조건입니다. 같은 처리량을 REST 는 커넥션 4개로, gRPC 는 1개로 냅니다. 커넥션이 싼 환경에서는 풀을 키우면 됩니다. 다만 여러 호출자가 한 서비스로 몰리는 팬인 구조에서는 호출자 인스턴스 수만큼 이 배수가 곱해집니다. 인스턴스가 수백 개면 피호출 쪽 파일 디스크립터와 소켓 메모리와 로드밸런서 커넥션 한계에 그대로 걸립니다.

풀 1개는 실무 설정이 아닙니다. 이 절의 값은 절대 처리량이 아니라 두 전송 사이의 배수로 읽어야 합니다. 그리고 크기 조건과 커넥션 조건은 독립입니다. 응답이 작아도 커넥션이 부족하면 gRPC 가 이깁니다.

6. 크기 이득은 직렬화에서 나온다

4장의 전송량 2.5배 절감이 어디서 나오는지 봅니다. JSON 은 필드명과 구조를 데이터마다 함께 싣고, Protobuf 는 스키마를 양쪽이 공유하니 와이어에 태그 번호와 값만 남습니다.

직렬화가 원인인지 확인하려면 전송 계층이 같고 직렬화만 다른 두 경로가 필요합니다. 2장에서 말한 중간 계층 두 방식이 그 조합입니다. grpc-gateway 는 JSON 으로 변환해 넘기고, grpc-web 은 브라우저가 Protobuf 를 그대로 주고받습니다.

HTTP/2 와 Protobuf 로 통신하고도 마지막에 JSON 으로 직렬화하면 크기 이득이 0 입니다. grpc-gateway 가 그 경우이고, 브라우저 데브툴에서는 REST 와 구별되지 않습니다. protojson 이 int64 를 문자열로 인코딩하기 때문입니다. grpc-gateway 를 쓰는 이유는 성능이 아니라 호환성입니다.

확인한 것은 크기까지입니다. 지연이 HTTP/2 때문인지 Protobuf 때문인지는 구분하지 못했고, 구분하려면 REST 를 h2c(TLS 없는 평문 HTTP/2)로 올린 구성이 하나 더 필요합니다.

7. 그래서 무엇을 고를까?

REST 가 이기는 구간은 하나입니다. 단건 조회에 커넥션이 넉넉할 때이고, 그때는 가상 스레드 설정 한 줄이 gRPC 도입보다 큰 이득을 냅니다. 계약도 배포 단위도 그대로 두고 얻습니다.

나머지 조건은 전부 gRPC 입니다. 응답이 커지거나 커넥션이 부족하거나 대역폭이 비용이 되거나 명세가 자주 바뀌면 그렇습니다. 규모가 커지면 이 조건들이 대체로 함께 오므로, 판단은 도입 여부가 아니라 순서가 됩니다. 단건 위주면 가상 스레드부터 켜고, 호출자가 수백 개로 늘어 커넥션이 병목이 되는 시점에 gRPC 로 옮깁니다.

8. 마치며

MSA 가 서비스 간 통신에 gRPC 를 쓰는 이유는 속도가 아니었습니다. 속도는 조건부고 단건 조회에서는 REST 가 더 빠릅니다. 조건과 무관하게 남은 것은 커넥션 1개가 나르는 양과 컴파일에서 깨지는 계약이었고, 둘 다 서비스가 많고 서로를 부르는 구조에서만 비용으로 드러납니다. gRPC 를 부르는 것은 속도가 아니라 MSA 라는 조건 자체입니다.

남은 한계. 단일 호스트라 왕복 지연이 거의 0 이고 이 조건은 gRPC 에 불리합니다. DB 가 없어 프로토콜 오버헤드의 상한을 본 셈입니다. 커넥션 회차의 풀 1개는 실무 설정이 아닙니다. 그래서 절대 처리량을 인용하지 않고 배수만 씁니다.

더 자세한 내용은 grpc-vs-rest-lab 에 정리해 두었습니다.

이 글은 Claude와 함께 작업했습니다.

TL;DR
여러 Claude Code 플러그인으로 개인 개발 도구를 나눠 만들었는데 늘수록 관리·위임 오류로 번거로워졌습니다.
모델이 발전하고 메인 세션 컨텍스트가 1M 으로 커지자 나눠 둘 이유가 약해져 하나의 작업 비서(ops-agent)로 합쳤습니다. 이제 이슈를 시작한다 하나로 단순해졌습니다.

배경: AI에게 맡기려면 매번 같은 출발선이 필요하다

AI 에게 코드와 문서를 맡기면 반복 작업이 줄어듭니다. 문제는 같은 요청에도 매번 다르게 답하고, 어제 합의한 규칙을 오늘 잊는다는 점입니다. 매번 사람이 교정하면 그 교정이 다시 일이 됩니다. 그래서 일회성 프롬프트로 쓰는 대신, 판단과 규칙을 하네스에 심어 AI 가 매 세션 같은 원칙 위에서 시작하게 만들기로 했습니다.

필요가 생길 때마다 도구를 하나씩 만들었습니다. 각 판단은 그 시점엔 맞았습니다. 모델 컨텍스트가 넉넉하지 않던 때라 도구를 작게 나눠 필요할 때만 불러 쓰는 편이 합리적이었습니다. 범용 도구는 대외 공개를 염두에 두고 회사 내부 로직을 넣지 않았고, 멀티레포와 사내 연동은 각각 별도 플러그인으로 분리했습니다. 4개의 층이 생기게 되었습니다.

org-flow (멀티레포 오케스트레이션)
  └─ flow (단일 레포 이슈 라이프사이클)
       └─ toolkit (사내 도구·시스템 접근)
            └─ provider (환경별 설정)

문제: 겹겹이 쌓을수록 에이전트가 놓친다

org-flow 가 flow 에 위임할 때마다 컨텍스트 전환이 생깁니다. 멀티레포 이슈를 시작하면 내부에서 flow 의 이슈 생성·시작을 호출하고 결과를 검증하고 워크트리 생성 같은 후속 작업을 이어갑니다. 위임 전 가드 설정, 위임 결과 검증, 실패 시 롤백을 LLM 에이전트가 순서대로 기억하고 실행해야 합니다. 층이 하나 늘 때마다 에이전트가 놓칠 수 있는 지점이 늘어납니다.

같은 기간 다른 배치 파이프라인 작업에서 같은 문제를 겪었습니다. 에이전트가 5단계를 수동으로 수행하다 캐시 미기록, 폴백 재삽입 같은 버그가 서너 번 반복됐습니다. 해법은 결정적 로직을 스크립트로 분리하고 불변식 검증을 스크립트에 내장해 에이전트의 개입 구간을 줄이는 데 있었습니다.

전환점: 모델이 발전하자 분리의 근거가 약해졌다

도구를 작게 나눈 근거는 필요할 때만 불러 쓴다였습니다. 모델 컨텍스트가 작은 경우 이 방식이 맞습니다. 그런데 모델이 세대를 거치며 발전하면서 전제가 흔들렸습니다. 체감상 가장 컸던 건 메인 세션이 한 번에 담는 컨텍스트가 1M 으로 늘어난 점입니다. 컨텍스트가 넉넉해지면서 하나의 에이전트가 이슈 플로우, 멀티레포, 검증, 규칙을 담아도 모자라지 않게 됐고 필요한 부분만 인덱스로 지연 로드하면 되는 구조가 된 것입니다.

다만 컨텍스트 하나로 단정하진 않습니다. 같은 기간 모델의 지시 이행·판단 품질도 함께 올라갔고 어느 요인이 결정적이었는지는 딱 잘라 말하기 어렵습니다. 정말 컨텍스트 때문인지는 다음 통합·분리 결정 때 다시 확인할 문제입니다. 분명한 건 방향입니다. 분리로 얻던 작게 유지의 이점은 줄고, 관리 포인트와 위임 오류라는 비용은 남았습니다. 그래서 판단을 다시 했습니다.

나눠 두는 대신, 하나로 합친다.

설계의 실체: 레포 수는 매니페스트가 알고, 도구가 처리한다

합치되, 레포 수처럼 바뀌는 정보는 코드가 아니라 데이터로 밀어냈습니다. org-flow 의 결정적 로직을 스크립트로 분리하고, flow 가 레포 수를 자동 감지해 단일·멀티를 투명하게 처리하도록 흡수했습니다.

이전 · 4층:  org-flow → flow → toolkit → provider
   │
   │ 통합
   ▼
이후 · 2층:  ops-agent(통합) → 사내 연동 어댑터

멀티레포 정보는 프로젝트 매니페스트 project.json 에 레포 수·역할·베이스 브랜치로 둡니다. 매니페스트가 없으면 단일 레포로 동작해 하위 호환을 유지하고, 새 프로젝트는 스킬 문서를 고치는 대신 매니페스트 십여 줄만 작성하면 됩니다.

이슈를 시작한다
  → flow 가 레포 수 자동 감지
  → 매니페스트로 관련 레포 결정
  → 워크트리 스크립트 (브랜치 생성·불변식 검증)
  → 작업 · AI 오케스트레이션
  → 커밋 스크립트 (원격 브랜치·불변식 검증)

결정적 작업은 스크립트로 옮기고, 각 스크립트에 불변식 검증을 내장했습니다. 브랜치나 원격 브랜치가 없으면 스크립트가 중단하므로, 에이전트는 호출하고 결과를 보고할 뿐입니다.

규칙도 세 시점(세션 시작, 편집·응답, 스킬 실행)에 자동으로 걸리게 두었습니다. 가령 표현 가드는 출력을 막는 대신 사전 주입과 사후 통지로 두어, 도구가 판단을 대체하지 않고 판단할 자리만 좁힙니다.

판단: 보조 도구에서 개인 개발 운영 에이전트로

하나로 합친 뒤 도구의 성격이 처음과 달라졌습니다. 처음엔 개발 편의를 돕는 보조 도구(DevEx)였는데, 이슈 플로우, 멀티레포 조정, 검증, 규칙 적용을 하나가 맡으면서 개인 개발을 운영하는 에이전트에 가까워졌습니다. 그래서 이름을 devex 에서 ops-agent 로 바꿨습니다. 단독 플러그인이던 교차 검증 도구도 이 안으로 들어와, 이제 별도 도구가 아니라 하나의 비서가 제공하는 검증 기능입니다. 이 도구는 회사 업무에도 쓰기 때문에 사내 연동은 별도(비공개) 플러그인으로 분리해, 퍼블릭 표면에 사내 정보가 섞이지 않도록 경계를 두었습니다.

지금 규모(1인 개발, 소수 프로젝트)에서는 매니페스트 + 스크립트 + 규칙 하네스로 충분하다고 판단했습니다. 과한 것을 미리 들이지 않았습니다. 정량 지표는 대부분 이슈를 병행하며 만든 것이라 측정이 끝나지 않았고, 검증되지 않은 수치는 적지 않았습니다. 다만 교차 검증 기능은 업무 레포 두 곳에서 타임존·페이지네이션 관련 이슈를 배포 전에 발견했습니다.

가장 큰 변화는 인지 모델입니다. 이슈가 멀티레포냐 단일 레포냐에 따라 org-flow 와 flow 를 구분해 쓰던 것이, 이슈를 시작한다 하나로 단일화됐습니다. 레포가 몇 개인지는 매니페스트가 알고, 도구가 처리합니다. 이 도구를 만들면서 분명해진 것은, AI 를 잘 쓰는 일이 모델을 다루는 일이 아니라 도구와 규칙의 아키텍처를 판단하는 일이라는 점입니다. 그리고 그 판단은 한 번으로 끝나지 않습니다. 처음엔 나누는 게 맞았고 지금은 합치는 게 맞았는데, 그 사이를 가른 건 모델이 발전한 것이고 그중 컨텍스트가 커진 영향이 컸습니다. 모델이 또 달라지면 분리와 통합을 다시 물어야 합니다. AI 는 그 판단을 실어 나르는 도구입니다.

매니페스트 스키마와 스크립트 등 구현 세부는 ops-agent 레포에 공개돼 있습니다.

이 글은 Claude와 함께 작업했습니다.

TL;DR
k8s 멀티테넌시 서비스 오픈 이후 여러 클러스터에 워크로드를 실행해야 하는 요구사항이 발생했습니다.
클러스터별 설정을 늘리는 방법 대신 위임 서비스(delegator)를 두고 k8s 의존을 그 뒤로 분리해, 클러스터를 추가해도 재배포 없이 DB 등록으로 끝나게 했습니다.
대안과 전제, 왜 그렇게 판단했는지는 아래에서 풀어 씁니다.

배경: 애플리케이션이 k8s에 워크로드를 만든다

GPU 워크로드를 쿠버네티스(k8s) 클러스터에서 실행하는 서비스를 개발하고 운영하고 있습니다. 애플리케이션(백엔드)이 컨트롤플레인 역할을 맡아 사용자의 워크로드 생성·관리 요청을 받아 k8s API로 실행합니다. 애플리케이션이 곧 k8s API의 클라이언트입니다.

초기 오픈은 단일 클러스터였습니다. 애플리케이션은 사용자 워크로드와 같은 클러스터 안에 있었고, 그 클러스터의 k8s API 서버와 통신하는 방식이었습니다. 애플리케이션과 API 서버가 같은 네트워크 안에 있어 도달성(요청이 상대에 닿는지)을 신경 쓸 일이 없었습니다.

문제: 단일 클러스터 전제가 깨졌다

오픈 이후 다음 버전을 준비하며 멀티클러스터 요구가 생겼습니다. 애플리케이션이 서로 다른 클러스터의 k8s API와 각각 통신해야 했습니다. “클러스터가 하나”라는 전제, 그 위에 얹혀 있던 “API 서버 주소도 하나”라는 전제가 함께 무너졌습니다.

대안: 설정을 늘릴까, 위임 계층을 둘까

가장 손쉬운 길은 클러스터별 k8s 접속 설정을 애플리케이션에 추가하는 것이었습니다. 클러스터가 적다면 이 방법도 괜찮습니다.

걸린 건 클러스터가 계속 늘어난다는 점이었습니다. 여러 리전에 걸친 다양한 환경의 클러스터를 다뤄야 하는 요구사항이 있었습니다. 클러스터가 늘 때마다 kubeconfig·인증·엔드포인트 설정이 코드나 설정 파일에 쌓이면, 애플리케이션이 클러스터 개수와 접속 방식에 직접 결합됩니다. 결합도가 높아집니다.

헥사고날로 도메인을 포트 뒤에 두면 도메인은 k8s·전송 세부에서 분리된 채 유지됩니다. 그러나 애플리케이션이 모든 클러스터의 kubeconfig·자격증명을 직접 쥔다는 사실은 남습니다. 전 클러스터의 자격증명을 한 곳이 보유해 사고 범위가 커지고, 클러스터를 추가하려면 설정 변경과 재배포가 따라옵니다.

그래서 위임 서비스를 뒀습니다. k8s와 직접 통신하는 책임을 위임 서비스로 옮기고 애플리케이션은 “어느 클러스터의 위임 서비스로 보낼지”만 알면 됩니다. 그 주소(클러스터별 위임 서비스 URL)는 DB 설정으로 관리합니다. 클러스터를 추가해도 애플리케이션 재배포 없이 DB 등록으로 끝납니다.

각 클러스터의 자격증명도 애플리케이션이 아니라 해당 위임 서비스가 갖습니다. 어댑터는 클러스터별 k8s 접속 세부가 아니라 위임 서비스 계약 하나만 알면 됩니다. 실행 플랫폼 교체도 같은 구조가 흡수합니다. 당시 GPU 스케줄링을 k8s 대신 docker + Slurm으로 옮기는 안이 검토되고 있었는데, k8s 관련 기능이 위임 서비스 뒤에 모여 있어 실행 플랫폼이 바뀌어도 애플리케이션은 그대로 두고 어댑터만 교체하면 됩니다.

설계의 실체: 포트는 도메인에, 전송은 어댑터에

격리는 코드의 이음새로 드러납니다. 도메인은 포트 인터페이스에만 의존합니다.

// 도메인이 의존하는 포트 (전송·k8s 세부 없음)
public interface RemoteExecutionPort {
  void createWorkload(Workload workload);
  // ...
}

전송(HTTP)은 어댑터에만 있습니다. 어댑터가 clusterId -> delegatorUrl -> client 순서로 대상 위임 서비스를 해석합니다.

// 포트 구현 = 전송 계층
public class RemoteExecutionAdapter implements RemoteExecutionPort {

  private DelegatorClient getClient(ClusterId clusterId) {
    var cluster = clusterQuery.getBy(clusterId);
    return delegatorClientFactory.getClient(URI.create(cluster.delegatorUrl()));
  }
}

동적 baseUrl은 팩토리가 클러스터별로 캐싱합니다.

// 위임 서비스 클라이언트 팩토리
public DelegatorClient getClient(URI baseUrl) {
  Objects.requireNonNull(baseUrl, "baseUrl must not be null");
  var normalizedUrl = normalizeUrl(baseUrl);
  return clientCache.get(normalizedUrl, url -> {
    var restClient = restClientBuilder.baseUrl(url).build();
    // ... HttpServiceProxyFactory 로 DelegatorClient 생성
  });
}

핵심은 여기입니다. 도메인은 RemoteExecutionPort에만 의존하고 전송·주소·k8s 세부는 전부 어댑터 밖에 있습니다. 그래서 전송을 gRPC 스트림이나 브로커로 바꿔도 어댑터를 하나 더 구현할 뿐 도메인 코드는 그대로입니다.

판단: 지금 규모에 맞춘 선택, 미뤄 둔 결정

현 규모(신뢰망 안 소수 클러스터, 동기 명령 중심)에서는 위임 서비스 + 동기 REST + DB 등록으로 충분하다고 판단했습니다. 과한 것(멀티클러스터 서비스 메시, 브로커)을 미리 들이지 않았습니다.

비가역적(irreversible) 결정은 도달성, 곧 어느 쪽이 연결을 여느냐입니다. 지금은 애플리케이션이 위임 서비스로 직접 요청을 보냅니다. 신뢰망 안에선 닿지만, 리전이 갈려 위임 서비스가 방화벽·NAT 뒤로 가면 이 방향이 막혀 위임 서비스가 먼저 연결을 여는 구조로 뒤집어야 합니다.

그래서 이 결정만 포트 뒤에 격리해 두고 멀티리전이 실제 요구가 되는 순간(last responsible moment)까지 미뤘습니다. 그 시점엔 어댑터를 하나 더 구현하면 됩니다. 도메인은 그대로입니다.

“설정만 늘렸다면”과 비교하면 차이가 분명합니다. 설정 증설은 당장은 빠르지만 클러스터 증가와 실행 플랫폼 변경을 코드나 설정에 계속 반영해야 합니다. 위임 서비스는 그 변화를 데이터(DB 등록)와 어댑터 교체 지점으로 모아 도메인이 흔들리지 않게 했습니다.

이 글은 Claude와 함께 작업했습니다.

TL;DR
5분 수집 / 10분 집계 / 일간 집계 미터링 파이프라인을 만들며, 하나의 시스템을 여러 각도에서 바라봤습니다. 순서가 아니라, 각 각도에서 내린 의사결정을 정리합니다.

• 쓰기 경합: 스키마 분리 + @Transactional(readOnly) 라우팅으로 해결.
• 배치 진화: 내장 스케줄러 → CronJob → 이벤트 → 분산, Stage 0→3 청사진 + 전환 시그널.
• 패턴 명명: 적용 패턴에 이름 붙이기(HWM, Tumbling Window, Catch-up, Idempotency).
• 저장 전략: 합리적 UPSERT를 DELETE+INSERT로 통일(YAGNI).

더 깊게 파고든 두 주제(MySQL 파티셔닝, 용량 세 제약 의사결정)는 별도 글로 분리.

0. 배경: 미터링 파이프라인과 기술 스택

운영 중인 클라우드 GPU 서비스의 과금 근거가 되는 사용량 데이터를 빠짐없이 수집·집계해야 했습니다. 설계부터 구현까지 직접 담당했습니다.

Prometheus (GPU/CPU/Memory)
    ↓ 5분 수집
[원천] Pod 단위 저장
    ↓ 10분 집계
[구간] 서비스/Pod 단위
    ↓ 일간 누적
[일간] 서비스/Pod 단위
    ↓
사용자 조회 API

1. 쓰기 경합: 스키마 분리 + 트랜잭션 라우팅

단일 DataSource의 세 가지 문제

서비스 수가 늘면 배치 실행 시간이 길어지고 겹침 확률이 높아집니다. 2년 예측(분기당 50 서비스 증가)으로 약 2억 건이 누적됩니다. 단일 데이터소스로는 한계에 이릅니다.

세 방안 검토

영역 분리 설계

가공은 집계 주기(10분)와 조회 패턴이 겹칠 가능성이 낮아 마스터 하나로 충분하다고 판단했습니다. 원천만 슬레이브로 라우팅합니다.

@Transactional(readOnly) 기반 라우팅

AbstractRoutingDataSource를 확장하여 트랜잭션의 readOnly 속성으로 라우팅합니다.

public class ReadWriteRoutingDataSource extends AbstractRoutingDataSource {
  @Override
  protected Object determineCurrentLookupKey() {
    return TransactionSynchronizationManager
        .isCurrentTransactionReadOnly() ? "slave" : "master";
  }
}

서비스 레이어는 어노테이션만 붙이면 라우팅이 결정됩니다.

@Transactional(value = "sourceTransactionManager", readOnly = true)
public List<SourceMetric> findByRange(Instant from, Instant to) { ... }  // → 슬레이브

@Transactional(value = "sourceTransactionManager")
public void saveAll(List<SourceMetric> instances) { ... }  // → 마스터

원천 영역은 독립된 EntityManagerFactory와 TransactionManager를 둡니다. 가공은 Spring Boot 기본 설정을 그대로 씁니다.

미리 대응한 엣지 케이스

• 슬레이브 복제 지연: 집계 주기(10분)가 수집 주기(5분)보다 길어 자연스러운 버퍼 확보
• 배치 실패 시 빈 구간: 마지막 성공 시점 추적 + 자동 재처리
• 멀티 소스 장애 격리: 소스별 Job 분리
• 데이터 증가 대응: 월별 파티셔닝 + 일정 기간 후 아카이빙

CQRS라고 하면 이벤트 소싱이나 별도 읽기 저장소를 떠올리기 쉽지만, 스키마 분리 + 트랜잭션 라우팅만으로도 쓰기·읽기 독립 이점을 얻을 수 있었습니다. 시스템 규모에 맞는 수준 선택이 더 중요합니다.

2. 배치 진화 청사진: Stage 0 → 3 + 전환 시그널

핵심 원칙은 하나입니다. 전환 시그널이 나타날 때까지 현재 단계를 유지합니다. 미리 과도하게 설계하면 복잡성만 늘어납니다.

Stage 0: 내장 스케줄러 + 상시 서버(현재)

JobRunr BackgroundJobServer가 주기적으로 Job을 폴링합니다. 메서드명이 곧 Job 이름이라 이름을 바꾸면 새 Job으로 인식되어 이력이 단절됩니다. 이 제약은 의도적입니다. Job 이력 일관성이 실패 복구의 기반이기 때문입니다.

@Job  // name 생략 → 메서드명이 Job 이름
public void collectSource() {
    var from = helper.getLastSuccessAt("collectSource");
    var rawData = prometheus.queryRange(query, from, now, "1m");
    sourceRepository.upsertAll(rawData);  // 멱등성 (UPSERT)
}

왜 CronJob이 아니라 상시 서버?

CronJob은 매 실행마다 JVM 기동(~30초)이 실제 작업 시간(~10초)의 3배입니다. 5분마다 이 비용을 내느니 서버를 상시 띄우는 편이 합리적입니다.

상시 서버의 대가는 명확합니다. 하루 약 48분만 실행되고 나머지 23시간 12분은 JobRunr 폴링과 Health Check만 하면서 리소스를 점유합니다.

Stage 1: CronJob + Native Image

상시 점유 → 실행 시에만 리소스. GraalVM Native Image로 기동 ~0.5초, 메모리 128MB로 줄이면 CronJob의 기동 오버헤드 문제가 크게 풀립니다.

대가: JobRunr의 Job 이력 자동 관리가 없으니 별도 BatchStatusRepository로 마지막 성공 시점을 직접 관리합니다.

전환 시그널: 유휴 리소스 비용 > 구현 복잡성 비용

Stage 2: 이벤트 기반(수집과 집계 디커플링)

[CronJob: 수집] → [Message Queue] → [집계 Worker]
                  (수집 완료 이벤트)

소스 종류가 늘면 시간 기반 집계(10:10) 시점에 일부 소스 데이터가 아직 없을 수 있습니다. 이벤트 기반이면 모든 소스 수집 완료 후 집계를 시작합니다.

대가: Exactly-once 처리. Stage 0부터 유지한 멱등성(UPSERT)이 이 지점에서 필요해집니다.

전환 시그널: 소스 종류 3개 이상, 수집-집계 타이밍 이슈 발생

Stage 3: 분산 처리(파티셔닝)

Prometheus는 쿼리당 총 샘플 수를 제한합니다(기본 5천만). 인스턴스 5,000개 + 7일 복구가 필요하면 단일 쿼리로 한계에 도달합니다.

총 샘플 수 = 인스턴스 수 × (시간 범위(분) / step(분))
5,000 × (7일 × 1,440 / 1) = 50,400,000  ← 5천만 초과

미터링은 논리 분할(프로젝트 단위)이 적합합니다. 분할 경계가 과금 단위와 일치하기 때문입니다.

전환 시그널: 단일 Prometheus 쿼리 한계 도달, 처리 시간이 배치 주기 초과

단계를 관통하는 원칙

3. 적용 패턴에 이름 붙이기

배치를 만들면서 “이게 안전하겠다”는 직관으로 결정한 것들이 사실 공식 이름이 있는 패턴이었습니다.

Catch-up vs Backfill

같은 UseCase 메서드의 오버로드로 표현합니다. 비즈니스 능력은 “집계”로 동일하고 트리거 방식만 다르기 때문입니다.

aggregateUsage()                          // Catch-up (자동, 크론 기반 + 누락 구간 복구)
aggregateUsage(AggregateUsageRequest)     // Backfill (수동, 운영자가 기간 지정)

max-recovery-days(7일)와 max-aggregate-range-days(7일) 상한이 무한 백필을 차단합니다.

계층별 멱등성 전략

같은 멱등성 원칙이라도 계층마다 구현이 다릅니다.

이건 4장 전환의 출발점이 됐습니다.

이름을 아는 것의 가치

1. 의사소통이 정확해집니다: “HWM 기반 Incremental Load” 한 문장으로 줄어듭니다
2. 선택지가 보입니다: “Incremental Load” 안에 HWM 외에도 Snapshot Diff, CDC가 있습니다
3. 검색이 됩니다: “Catch-up pattern batch”로 정확한 사례·베스트 프랙티스를 찾을 수 있습니다

4. 저장 전략 통일: UPSERT → DELETE + INSERT(YAGNI)

UPSERT 선택의 합리성

미터링 배치 설계 초기 INSERT ... ON DUPLICATE KEY UPDATE 선택 근거는 명확했습니다.

• 멱등성: 동일 키 재수집해도 중복 없음
• 동시성 안전: 유니크 키 제약으로 충돌 감지
• 패턴 검증: 시계열 배치 모범 사례

AI 딥리서치도, 다른 시스템 사례도, UPSERT가 맞다는 결론이었습니다.

전환점: 팀원 자문

리뷰에서 팀원 자문 결과가 리서치와 달랐습니다.

합리적인 설계였지만 우리 규모에서는 오버 엔지니어링이었습니다.

AI에게 아무리 딥리서치를 시키고 다른 사례를 봐도 이런 결론은 나오지 않았습니다. “~2,000 Pod 상한의 B2B2C GPU 서비스에서 5인이 유지보수합니다”라는 맥락은 어떤 리서치에도 다뤄지지 않습니다. 이 판단은 서비스 맥락을 이해하는 팀원에게서 나왔습니다.

쿼리 비용 비교

ON DUPLICATE KEY UPDATE는 행마다 유니크 키 존재 여부를 확인합니다. 내부 SELECT가 반드시 1건 발생합니다. JDBC batch로 1회 왕복에 전송해도 마찬가지입니다.

UPSERT (N건):      내부 SELECT × N + INSERT/UPDATE × N = 2N 연산
DELETE+INSERT:     range DELETE × 1 + batch INSERT × 1 = 2 연산

Pod별 원천 수집(5분 주기, 하루 288회)이 누적됩니다.

실측 성능 차이는 현재 규모에서 밀리초 단위입니다. 소규모에서는 체감되지 않습니다.

성능이 비슷하다면 더 단순한 쪽이 이깁니다. 5인 팀에서 JDBC 하드코딩 SQL 관리 비용은 성능 이점을 상회합니다.

파이프라인 전체 통일

모든 단계가 같은 패턴입니다.

repository.deleteAllBy...(from, to);    // 1. 범위 삭제
repository.createAll(entities);          // 2. saveAll (DELETE + INSERT)

핵심 변경은 다음과 같습니다.

교훈: 합리적 설계 ≠ 올바른 설계

일반론으로 옳은 결정이 특정 맥락에서는 오버 엔지니어링이 됩니다. 돌이켜보면 YAGNI 위배였습니다. 현재 필요하지 않은 동시성 보호를 미리 설계한 것이 비용이 되었습니다. 그 경계를 판단하는 것은 코드가 아니라 사람입니다.

회고: 하나의 시스템을 여러 각도에서

배치 시스템 설계의 핵심 역량은 적정 설계 선택이라고 생각합니다. 다음 단계로의 전환 시점을 판단하는 능력이 정확한 청사진보다 중요합니다.

돌아보면 이 프로젝트에서 남은 건 개별 해법보다, 하나의 시스템을 쓰기 경합·진화·패턴·저장이라는 여러 각도에서 바라본 경험입니다. 한 각도에 매몰되지 않으려 한 시도였습니다.

이 시스템에서 더 깊게 다룬 두 주제는 별도 글로 분리했습니다.

• 데이터 증가 대응의 구체적 구현: MySQL 파티셔닝 도입기(JPA 복합 키 전환부터 시간 독립 DDL까지)
• 용량 설계의 근거: 어디까지 견뎌야 하는가: 미터링 용량을 세 가지 제약으로 역산한 의사결정

이 글은 Claude와 함께 작업했습니다.

TL;DR
1편: 사용자 도메인 인증서를 HTTP-01 + ACME4j 로 자동 발급. 헥사고날 + 상태 머신 + 4개 CronJob 으로 발급·갱신·재시도·타임아웃을 다 잡았습니다.
2편: 1년 뒤 와일드카드 인증서 갱신을 Docker certbot 과 호스트 DNS Handler 의 파일 기반 IPC + Jenkins 격월 크론으로 끝까지 자동화했습니다.
1편의 ACME 학습이 2편 자동화의 판단 기반이 됐습니다. 2편은 AI 에 코드 위임을 했지만, 엣지 케이스는 1편의 운영 경험에서만 나왔습니다.

0. 배경: 두 가지 인증서 과제

운영 중인 앱 배포 플랫폼은 두 종류의 인증서를 다룹니다.

• 플랫폼 와일드카드: *.platform.com. 모든 사용자 서비스가 공유. 90일 주기 갱신 필요
• 사용자 개별 도메인: my-service.example.com 같은 사용자 자신의 도메인. 도메인 연결 시점에 자동 발급되어야 함

두 과제가 다른 시점에 나왔습니다. 사용자 도메인 자동 발급은 BE 구현 8주 (2024 말). 와일드카드 갱신 자동화는 1년 뒤 운영 자동화 (2026 초). 1편의 학습이 2편의 설계 기반이 됐고, 2편에서는 AI 협업으로 구현 속도를 크게 끌어올렸습니다.

1. Let’s Encrypt 와 ACME 프로토콜

Let’s Encrypt 는 무료 SSL 인증서를 자동 발급하는 CA. 핵심은 도메인 소유권 검증이고, ACME 프로토콜이 그 검증을 표준화한 메커니즘입니다.

Challenge 유형

와일드카드는 DNS-01 만 가능 (HTTP-01 은 호스트 단위라 와일드카드와 호환되지 않습니다).

Rate Limits (이후 구현에 직접 영향)

이 제한이 배치 스케줄과 재시도 전략을 결정한 핵심 입력이었습니다.

certbot 으로 먼저 학습

본격적인 BE 구현 전에 certbot CLI 로 발급 과정을 직접 돌렸습니다.

certbot certonly --manual \
  --preferred-challenges dns \
  -d "*.platform.com"

certbot 이 TXT 레코드 값을 알려주면 DNS 에 수동으로 추가하고 확인. 이 학습에서 두 가지를 알게 됐습니다.

1. 와일드카드는 DNS-01 필수. 사용 중인 클라우드 DNS 서비스에는 certbot 공식 플러그인이 없어 수동 발급이 유일 방법이었음 (이게 2편의 자동화 동기가 됐습니다)
2. 사용자 도메인은 HTTP-01 이 적합. 사용자 DNS 를 플랫폼이 직접 제어할 수 없으니 HTTP 응답 기반이 자동화에 유리

2. 1편: 사용자 도메인 BE 구현 (HTTP-01 + ACME4j)

헥사고날 모듈 구조

cert/
├── api/        # 공유 인터페이스 (UseCase, Command, Event)
├── core/       # 비즈니스 로직 (도메인, 서비스, 포트, 어댑터)
├── server/     # REST API + 이벤트 구독
├── verifier/   # HTTP-01 토큰 응답 서비스 (사용자 도메인 트래픽 수신)
├── job/        # 배치 CronJob
└── client/     # 외부 서비스용 클라이언트

도메인 포트와 어댑터 매핑.

상태 머신 설계

발급은 즉시 완료되지 않습니다. 도메인 검증·ACME 통신·인증서 생성 여러 단계에서 실패할 수 있으니 상태 머신이 필요했습니다.

[서비스 등록] → APPLICATION → PROCESSING → SUCCESS → (갱신 시) APPLICATION
                  ▲              │
                  │              ▼
                  └── FAILURE_REAPPLICATION (재시도)
                       └→ PROCESSING → FAILURE_EXIT (최대 시도 초과)

Rich Domain 패턴

Certificate 엔티티가 상태 전이 로직과 외부 호출을 내부에 캡슐화합니다. 서비스 레이어는 도메인에 메시지만 전달하면 됩니다.

public class Certificate {
    // 발급 시작: APPLICATION → PROCESSING
    public void issueStart(Duration jobExpectDuration) {
        this.issuanceAttemptCount += 1;
        this.issuanceStatus = PROCESSING;
        this.jobRunExpectAt = ZonedDateTime.now().plus(jobExpectDuration);
    }

    // 발급 처리: 도메인이 직접 Output Port 호출
    public IssueProcessResponse issueProcess(IssueProcessRequest req) {
        var issuerPort = req.issuerPort();
        try {
            var data = issuerPort.issue(this);   // ACME4j 통신
            this.issuanceStatus = SUCCESS;
            this.issuedAt = data.issuedAt();
            this.expiredAt = data.expiredAt();
            this.publicKey = data.publicKey();
            this.privateKey = data.privateKey();
            this.jobRunExpectAt = this.expiredAt.minus(req.renewalExpectDuration());
            return new IssueProcessResponse(true);
        } catch (Exception e) {
            // 재시도 또는 최종 실패 처리
            return new IssueProcessResponse(false);
        }
    }
}

상태 전이 검증은 CertificateValidator 가 담당. APPLICATION 이 아닌 인증서에 issueStart() 를 호출하면 예외가 납니다.

ACME4j 발급 흐름

CertificateIssuerPortImpl.issue()
  ├─ Acme4jService.createOrder(도메인)
  ├─ Acme4jService.createChallenge(주문)
  ├─ VerifierFeign.saveChallengeToken()    ─── Verifier 에 토큰 저장
  ├─ Acme4jService.triggerChallenge()       ─── Let's Encrypt 가 Verifier 로 검증 요청
  │     └─ GET /.well-known/acme-challenge/{token}
  ├─ Acme4jService.createCertificate()
  └─ VerifierFeign.deleteChallengeToken()  ─── 토큰 정리 (finally)

Verifier 의 토큰 저장은 인메모리 HashMap. 처음엔 임베디드 Redis 를 적용했지만 토큰의 일회성 특성을 보고 HashMap 으로 단순화. 어댑터로 격리되어 있어 교체가 짧았습니다.

4개 CronJob 으로 생명주기 관리

발급 Job 은 Rate Limit 을 따릅니다.

public void issueAll() {
    List<Certificate> targets = repository.findAllIssueTargetLimit(
        ACCOUNT_SPEC.getMaxCharge()  // 시간당 10건
    );
    for (Certificate cert : targets) {
        cert.issueStart(...);
        try {
            domainVerifyPort.verifyServiceLink(cert.getDomain());
        } catch (DomainVerifyServiceNotLinkedException e) {
            handleDomainLinkFailure(cert);
            continue;
        }
        certificateJobAsync.issueProcessAsync(cert);  // @Async
    }
}

실전 이슈 5가지

설계부터 QA 까지 약 8주. 일정 산정은 18.5MD (3.7주) 였지만 설계 시간과 엣지 케이스 대응이 두 배 이상 갔습니다. 설계에 시간을 더 쓰면 구현이 빨라진다는 걸 체감했습니다.

3. 2편: 와일드카드 갱신 운영 자동화 (1년 뒤)

수동 갱신의 한계

플랫폼 와일드카드 (*.platform.com) 의 갱신이 90일마다 수동이었습니다.

1. certbot 으로 DNS-01 발급 (수동 TXT 설정)
2. 4개 클러스터에 인증서 적용 (kubectl patch / YAML 수정 / git push)
3. 환경별 검증 (브라우저에서 하나씩)

회당 1~2시간. 게다가 동일 도메인 세트 재발급 제한 (주당 5회) 으로 실수하면 7일 대기. 자동화 목표는 “사람 개입 없는 격월 크론”.

DNS-01 자동화: Docker certbot + 호스트 DNS Handler IPC

DNS Plus 에 certbot 공식 플러그인이 없으니 --manual-auth-hook 으로 API 를 직접 호출해야 합니다. certbot 을 Docker 로 실행하면 환경 격리·재현성을 얻지만, DNS API 호출에 필요한 curl·jq 는 호스트에 있습니다. 파일 기반 IPC 로 분리.

[Docker certbot]                    [호스트 DNS Handler]
     │                                     │
     ├── auth-hook 실행                     │
     │   ├── request 파일 생성 ────────→    │
     │   │   (DOMAIN, VALIDATION)          │
     │   │                                 ├── DNS API 호출 (TXT 레코드 설정)
     │   │                                 ├── DNS 전파 폴링 (8.8.8.8, 3초 간격)
     │   ← done 파일 감지 ←────────────    ├── done 파일 생성
     │   └── certbot 검증 진행              │

설계 포인트 3가지.

1. 파일 통신: Docker 볼륨 마운트로 /certbot-comm 공유
2. challenge 값 누적: *.platform.com 과 platform.com 은 같은 TXT 레코드 사용. 도메인별 challenge 파일에 값을 누적하여 한 번의 API 호출로 전체 업데이트
3. DNS 전파 폴링: 고정 대기 대신 Google DNS 폴링으로 실제 전파 확인. 대기 시간 최소화

Docker 내부 auth-hook 은 /bin/sh 호환 (certbot 공식 이미지에 bash 없음).

4개 클러스터 배포

플랫폼은 Dev / Prod 환경에 각각 IDC (베어메탈) 와 매니지드 K8s 두 클러스터씩, 총 4개. 인증서 하나를 각각 다른 방식으로 적용합니다.

IDC 가 ArgoCD 관리 밖에 있는 이유는 sync 시 인증서가 이전 버전으로 롤백되기 때문. 매니지드 클러스터는 로드밸런서 annotation 에 인증서를 직접 포함하므로 yq 로 annotation 만 교체합니다.

kubectl context 이식성

로컬 (macOS) 과 Jenkins 서버에서 context 이름이 달라 스크립트가 깨졌습니다. 추상화로 해결.

resolve_context() {
    case "$1" in
        alpha-idc)
            local_name="platform-alpha-idc"
            jenkins_name="dev-idc"
            ;;
    esac
    if kubectl config get-contexts "$local_name" &>/dev/null; then
        echo "$local_name"
    else
        echo "$jenkins_name"
    fi
}

스크립트가 실행 환경을 자동 감지. 로컬 테스트와 Jenkins 실행이 같은 스크립트를 씁니다.

Jenkins 파이프라인: 파라미터 매트릭스

발급과 배포를 독립 제어.

이 매트릭스로 다양한 시나리오 대응.

• 발급 테스트만: ISSUE=STAGING, DEPLOY=NONE
• Alpha 먼저 검증: ISSUE=PRODUCTION, DEPLOY=ALPHA
• Alpha 확인 후 Real: ISSUE=NONE, DEPLOY=REAL
• 정기 갱신: ISSUE=PRODUCTION, DEPLOY=ALL

크론 트리거 (격월 1일 정오 KST).

triggers { cron('0 12 1 */2 *') }

크론 실행 감지 시 ISSUE=PRODUCTION, DEPLOY=ALL 자동 설정. 배포 결과는 메신저 webhook 으로 알림.

엣지 케이스 3가지

4. 1년의 학습 차이와 AI 협업

1편에서는 certbot 과 DNS-01 의 동작 원리를 이해하기 위해 8주를 투자했습니다. 그 경험이 있었기에 2편에서 “무엇을 자동화해야 하는지”, “어디서 문제가 생길 수 있는지” 를 판단할 수 있었고, AI 에게 올바른 방향을 제시할 수 있었습니다.

2편의 자동화에서는 스크립트와 Jenkins 파이프라인 코드 작성을 AI 에 위임했고, 본인은 전체 플로우 설계와 의사결정에 집중했습니다. 결과적으로 1편보다 훨씬 짧은 시간에 운영 수준의 자동화에 도달했습니다.

다만 엣지 케이스 (Staging → Production 충돌, Docker root 권한, DNS 전파 폴링 같은 디테일) 은 AI 가 처음부터 알려주지 않습니다. 실제로 한 번 겪어봐야 발견되는 종류입니다. 1편의 운영 경험이 그 발견의 토대였습니다.

회고: 깊이가 자동화 품질을 만든다

도구 (certbot, ACME4j, Jenkins) 는 시간이 흐르며 바뀝니다. 바뀌지 않는 것은 그 도구가 어떤 제약 위에서 동작하는지 를 이해하는 깊입니다. Rate Limit, DNS 전파, 권한 모델, 환경별 적용 방식. 이 제약을 모르고 만든 자동화는 갱신 한 번에 무너집니다. 1편의 8주가 비싸 보였지만 2편에서 회수됐습니다.

AI 가 코드를 빠르게 생성해주는 시대에는, 어떤 사람의 자동화가 더 단단한가가 더 잘 드러납니다. 답은 단순합니다. “어떤 상황에서 실패할 수 있는가” 를 아는 사람의 자동화가 단단합니다.

이 글은 Claude와 함께 작업했습니다.

TL;DR
uvx 는 PyPI 패키지를 격리 환경에서 실행하는 명령(=uv tool run). 자바의 jbang 자리에 가깝습니다.
배포는 pyproject.toml 의 [project.scripts] 와 uv build/uv publish, GitHub Actions 의 validate→publish 2단계로 자동화합니다.
함정 하나: uvx 는 requires-python 을 의도적으로 무시합니다. 사용자 환경 Python 이 낮으면 setup.sh 에서 --python 플래그를 자동 부여하는 것으로 막습니다.

1. 왜 uvx 인가

claude-slack-to-notion MCP 플러그인을 배포하면서 uvx 를 처음 접했습니다. MCP 공식 문서가 Python 서버 실행 방법으로 uvx 를 “recommended” 로 명시하고, Anthropic 공식 MCP 서버인 mcp-server-git 도 uvx 기반으로 배포됩니다. 사실상 Python MCP 플러그인의 표준 경로였습니다.

자바 개발자라서 처음엔 낯설었습니다. 대응표를 만들어보니 이해가 빨라졌습니다.

명령어만 다르고 하는 일은 거의 같습니다.

uvx 의 정의

uvx 는 uv tool run 의 별칭. PyPI 패키지를 격리된 가상환경에서 실행하는 명령입니다. Node 의 npx 와 같은 자리.

임시 실행 파일은 ~/.cache/uv/, 영구 설치는 ~/.local/share/uv/tools/ 에 저장. MCP 서버처럼 매 세션마다 실행되는 경우에도 캐시 재사용으로 체감 성능 차이는 없습니다.

설치와 기본 사용

# macOS
brew install uv

# pip (범용)
pip install uv

# curl (Linux/macOS)
curl -LsSf https://astral.sh/uv/install.sh | sh

uvx ruff check .                        # 임시 실행
uvx ruff@0.3.0 check .                  # 특정 버전
uvx --from 'ruff>0.2.0,<0.3.0' ruff .   # 버전 범위 (--from 필수)
uvx --from httpie http                  # 패키지명 ≠ 커맨드명
uvx --with mkdocs-material mkdocs build # 추가 의존성

--from 은 패키지 이름과 실행 커맨드 이름이 다를 때 또는 버전 범위 연산자를 쓸 때 필요.

2. PyPI 배포: pyproject.toml 의 진입점

uvx 로 실행 가능한 패키지를 만들려면 두 가지가 필요합니다. PyPI 에 배포된 패키지, 그리고 진입점이 정의된 pyproject.toml.

실제 프로젝트 핵심 발췌:

[project]
name = "slack-to-notion-mcp"
version = "0.1.0"
requires-python = ">=3.10"
dependencies = [
    "slack_sdk>=3.27.0",
    "notion-client>=2.2.0",
    "mcp[cli]>=1.0.0",
]

# uvx 가 실행할 커맨드 정의 (핵심)
[project.scripts]
slack-to-notion-mcp = "slack_to_notion.mcp_server:main"

[project.scripts] 가 핵심. uvx slack-to-notion-mcp 를 실행했을 때 어떤 Python 함수가 호출될지 여기서 정의합니다. 자바의 MANIFEST.MF Main-Class 자리. 형식은 커맨드명 = "모듈.경로:함수명".

빌드와 배포:

uv version 1.0.0           # 버전 지정
uv version --bump minor    # 자동 bump
uv build                   # dist/ 에 wheel + sdist
uv publish                 # PyPI 배포

uv build 산출물:

wheel 의 핵심은 사용자 환경에서 빌드를 제거하는 것. PyPI 자체는 빌드하지 않고 GitHub Actions 같은 곳에서 빌드한 결과물을 저장하는 저장소입니다 (Maven Central, npm registry 와 같은 자리).

Git 직접 실행 대안 검토

uvx 는 PyPI 없이도 실행할 수 있습니다.

uvx --from git+https://github.com/user/repo slack-to-notion-mcp

PyPI 배포가 빠지니 매력적으로 보였습니다. 검토 후 기각:

1. 비표준: Anthropic 공식 MCP 서버 포함 Python 도구는 거의 모두 PyPI 로 배포. Git 직접 실행은 Python 진영의 일반적 배포 방식이 아님
2. 매번 소스 빌드: wheel 이 아닌 소스를 받으므로 사용자 환경에서 매번 빌드. wheel 의 존재 이유가 이 빌드를 제거하기 위함
3. 보안 서명 불가: PyPI Trusted Publishing(OIDC) 은 빌드 환경을 검증. Git 직접 실행에는 이런 서명 체계가 없음

대안을 검토해봐야 “왜 PyPI 를 쓰는가” 에 답이 명확해집니다.

3. MCP 플러그인 연결: .mcp.json

PyPI 에 배포된 패키지는 .mcp.json 한 블록으로 연결됩니다.

{
  "mcpServers": {
    "slack-to-notion": {
      "command": "uvx",
      "args": ["slack-to-notion-mcp"],
      "env": {
        "SLACK_BOT_TOKEN": "${SLACK_BOT_TOKEN}",
        "SLACK_USER_TOKEN": "${SLACK_USER_TOKEN}",
        "NOTION_API_KEY": "${NOTION_API_KEY}",
        "NOTION_PARENT_PAGE_ID": "${NOTION_PARENT_PAGE_ID}"
      }
    }
  }
}

mcp-server-git 도 "command": "uvx", "args": ["mcp-server-git"] 동일 구조.

uvx 기반 MCP 서버의 장점:

1. 사용자 환경 설정 불필요: uvx 가 가상환경·의존성을 모두 처리
2. 버전 고정 가능: args 에 "slack-to-notion-mcp@0.2.0" 명시
3. 의존성 격리: 사용자 프로젝트 Python 환경과 충돌 없음
4. 업데이트 간편: 설정의 버전 번호만 변경

4. GitHub Actions 자동화: validate → publish → auto-tag

처음에는 수동 uv publish. 태그 v0.2.0 인데 pyproject.toml 이 0.1.9 로 올라간 버전 불일치 사고 한 번을 겪고 자동화로 갔습니다.

name: PyPI 배포
on:
  push:
    tags: ["v*"]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/setup-uv@v4
      - name: 태그-버전 일치 확인
        run: |
          TAG_VERSION="${GITHUB_REF_NAME#v}"
          PKG_VERSION=$(uv run python -c "
          import tomllib
          with open('pyproject.toml', 'rb') as f:
              print(tomllib.load(f)['project']['version'])
          ")
          if [ "$TAG_VERSION" != "$PKG_VERSION" ]; then
            echo "::error::태그($TAG_VERSION)와 pyproject.toml 버전($PKG_VERSION)이 불일치"
            exit 1
          fi
      - run: uv sync --extra dev && uv run pytest tests/ -v

  publish:
    needs: validate
    runs-on: ubuntu-latest
    permissions:
      id-token: write
    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/setup-uv@v4
      - run: uv build
      - run: uv publish
        env:
          UV_PUBLISH_TOKEN: $

핵심 설계는 validate → publish 2단계 분리. 태그 버전과 pyproject.toml 버전이 다르면 배포 전에 실패합니다.

인증 방식:

신규 프로젝트라면 처음부터 Trusted Publisher 권장.

auto-tag.yml: 태그까지 자동화

pyproject.toml 버전이 변경되어 main 에 머지되면 태그를 자동 생성하는 워크플로우.

name: Auto Tag
on:
  push:
    branches: [main]
    paths: ["pyproject.toml"]

jobs:
  tag:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          token: $
      - name: 버전 읽기 + 태그 생성
        run: |
          VERSION=$(grep -m1 '^version' pyproject.toml | sed 's/.*= *"\(.*\)"/\1/')
          TAG="v$VERSION"
          if git ls-remote --tags origin "$TAG" | grep -q "$TAG"; then
            echo "태그 $TAG 이미 존재: 스킵"
          else
            git config user.name "github-actions[bot]"
            git config user.email "github-actions[bot]@users.noreply.github.com"
            git tag "$TAG" && git push origin "$TAG"
          fi

함정 하나: GITHUB_TOKEN 대신 AUTO_TAG_PAT 을 써야 합니다. GITHUB_TOKEN 으로 생성한 태그는 다른 워크플로우를 트리거하지 않습니다 (GitHub 의 무한 루프 방지 정책).

이제 손이 닿는 곳은 pyproject.toml 의 버전 수정뿐.

PR 머지 (pyproject.toml version 변경 포함)
  → auto-tag.yml: 태그 자동 생성
    → pypi-publish.yml: validate + PyPI 배포

5. 함정: uvx 는 requires-python 을 무시한다

v0.2.0 배포 후 “Python 3.9 쓰는 사람한테는 왜 안 되지?” 라는 질문을 받았습니다. pyproject.toml 에 requires-python = ">=3.10" 을 기재했으니 3.9 사용자는 설치 단계에서 막힐 거라고 생각했습니다. 틀렸습니다.

설치는 됐고, 실행도 됐고, 동작이 이상했습니다.

uv 공식 문서

“will ignore non-global Python version requests like .python-version files and the requires-python value”

requires-python 무시. .python-version 무시. 버그가 아니라 의도된 설계. GitHub 이슈 #8206, #14958 에서 이미 논의된 내용입니다.

자바 관점에서 보면 이게 얼마나 낯선지 설명이 됩니다. Maven 에서 <java.version>11</java.version> 을 pom.xml 에 두면 JDK 8 로 빌드하려는 순간 컴파일 에러가 납니다. uvx 는 그 체크 자체를 안 합니다.

uvx 의 Python 선택 우선순위

1. --python 플래그 (명시적 지정)
2. UV_PYTHON 환경변수
3. uv 가 관리하는 Python (~/.local/share/uv/python/)
4. 시스템 PATH 의 Python

requires-python 은 이 목록에 없습니다.

uvx vs uv run 의 결정적 차이

uv run 은 프로젝트 맥락이 있고, uvx 는 도구 격리 실행에 집중합니다. 자바로 비유하면 ./gradlew run 과 jbang script.java 의 차이.

해결: setup.sh 에서 자동 처리

방법은 두 가지. 사용자에게 uvx --python 3.10 slack-to-notion-mcp 를 안내하거나, setup.sh 에서 자동 처리. 후자 선택.

# Python 버전 확인 (3.10 미만이면 --python 3.10 자동 부여)
PYTHON_TOO_OLD=false
if [[ -n "$PYTHON_CMD" ]]; then
  PYTHON_VERSION=$($PYTHON_CMD -c \
    "import sys; print(f'{sys.version_info.major}.{sys.version_info.minor}')")
  PYTHON_MAJOR=$(echo "$PYTHON_VERSION" | cut -d. -f1)
  PYTHON_MINOR=$(echo "$PYTHON_VERSION" | cut -d. -f2)
  if [[ "$PYTHON_MAJOR" -lt 3 ]] || \
     { [[ "$PYTHON_MAJOR" -eq 3 ]] && [[ "$PYTHON_MINOR" -lt 10 ]]; }; then
    PYTHON_TOO_OLD=true
  fi
else
  PYTHON_TOO_OLD=true
fi

if [[ "$PYTHON_TOO_OLD" == "true" ]]; then
  claude mcp add slack-to-notion ... -- uvx --python 3.10 slack-to-notion-mcp
else
  claude mcp add slack-to-notion ... -- uvx slack-to-notion-mcp
fi

시스템 Python 이 3.10 이상이면 그대로, 미만이면 --python 3.10 을 자동으로 붙입니다. --python 3.10 지정 시 uv 가 자동으로 Python 3.10 을 찾거나 다운로드합니다.

requires-python 은 지우지 않습니다. pip install 사용자에게는 작동하고 PyPI 메타데이터 표시에도 쓰입니다. uvx 에서만 무시될 뿐.

회고: 생태계가 다르면 안전장치도 다르다

Java 에서는 Maven/Gradle 이 JDK 버전을 강제합니다. 버전 불일치는 빌드 도구가 막아줍니다. 그래서 pom.xml 에 버전을 쓰면 끝이라고 생각했습니다. Python uvx 에서는 그렇지 않습니다. 도구 실행 맥락에서는 설계 의도상 프로젝트 메타데이터를 보지 않습니다.

알고 나면 간단한 이유가 있고 모르면 “왜 안 되지?” 에서 한참 헤맵니다. 새 생태계로 옮길 때 가장 비싼 비용은 그 차이를 발견하는 시간입니다.

uvx 로 한 사이클을 돌면서 얻은 것:

동작하는 코드에 만족하지 않고 왜 그 방식인지 파고들면 새 생태계의 골격이 빠르게 보입니다.

이 글은 Claude와 함께 작업했습니다.

TL;DR
Chirpy 테마는 SEO 기본기·OG 태그·sitemap·robots.txt·JSON-LD를 자동 생성하므로 추가 설정이 거의 없습니다.
GEO 대응도 새 기법보다 누락된 기본기(JSON-LD author, llms.txt, last_modified_at) 보완이 핵심이었습니다.
Giscus 댓글은 _config.yml 13줄, 커스텀 도메인은 *.github.io 의 GSC 사이트맵 인식 한계를 즉시 해소했습니다.

1. SEO: Chirpy가 이미 다 하고 있었다

블로그를 시작하고 SEO를 점검했습니다. 메타태그·OG·sitemap·robots.txt·JSON-LD 를 직접 설정해야 한다고 생각했는데 결론은 대부분 이미 되어 있었습니다.

Chirpy 테마는 두 플러그인을 기본 의존성으로 포함합니다.

별도 설치한 적 없지만 Gemfile.lock 에 이미 포함되어 있습니다. front matter 에 title·date·description 만 쓰면 나머지는 전부 자동입니다.

점검 결과

GSC 등록은 _config.yml 한 줄

GSC 에서 HTML 메타 태그 인증을 선택하면 받은 content 값을 _config.yml 한 줄에 명시하면 끝.

webmaster_verifications:
  google: abc123xyz

배포하면 모든 페이지의 <head> 에 인증 태그가 자동 주입됩니다. 인증 후 좌측 메뉴 → Sitemaps → sitemap.xml 입력 → 제출. jekyll-sitemap 이 이미 파일을 생성하므로 URL 만 등록하는 절차입니다.

인증 태그는 영구 유지해야 합니다. 삭제하면 수개월 후 소유권이 취소될 수 있습니다.

2. GEO: 새 기법보다 누락된 기본기

요즘IT 콘텐츠 AX 실험기 에서 GEO(Generative Engine Optimization) 를 접했습니다. AI 검색엔진(Claude·Gemini·ChatGPT 등) 이 콘텐츠를 인용하도록 최적화하는 전략.

근거 점검

바로 적용하기 전에 학술적 근거부터 확인했습니다. IIT Delhi·Princeton 의 “GEO: Generative Engine Optimization” (ACM KDD 2024) 가 10,000개 쿼리로 9가지 전략을 테스트했습니다.

Yext 의 6.8M 인용 분석(2025.10) 에 따르면 AI Overviews URL 과 Google 1위 결과의 중복률은 4.5%에 불과. SEO 와 GEO 는 별개입니다.

다만 SandboxSEO 가 GEO 논문 방법론을 비판한 지점도 유효합니다. 상위 3개 전략이 모두 새 정보를 추가하는 방식이라 GEO 효과인지 단순 콘텐츠 양 증가 효과인지 구분할 수 없다는 지적, 그리고 AI 플랫폼의 인용 변동성이 월 40~60% 라는 점.

개념은 유효하나 수치 효과는 회의적으로 봐야 합니다.

발견한 누락: JSON-LD author

실제 출력을 확인하니 이랬습니다.

{ "@type": "BlogPosting", "headline": "...", "datePublished": "...", "dateModified": "..." }

author 와 publisher 가 없었습니다. _config.yml 에 author 필드가 없었기 때문. SEO·GEO 양쪽 모두에서 기본 누락이었습니다.

저비용 적용 3가지

대규모 구조 변경은 근거 대비 투자가 과합니다. 저비용으로 SEO/GEO 공통 기본기만 보완했습니다.

(1) _config.yml 에 author 와 logo 추가

author: idean3885
logo: /assets/img/favicons/favicon-96x96.png

jekyll-seo-tag 가 author → Person, logo → publisher.Organization 으로 JSON-LD 를 채웁니다.

(2) llms.txt 추가 (llmstxt.org 규격, 루트 배치)

# idean3885.github.io
> 개발자의 기술적 탐구, 방법론의 진화, 운영 노하우와 의사결정의 기록.

## 카테고리
- 개발 기록: 프로젝트 경험기, 도구 적응기
- 기술 노하우: 운영 경험 기반 실전 지식

(3) last_modified_at 수정 규칙

포스트 수정 시 front matter 에 last_modified_at 을 기재. jekyll-seo-tag 가 이 값을 JSON-LD dateModified 에 반영합니다. 웹에는 안 보이지만 검색엔진·AI 에는 freshness 신호로 작용.

Chirpy 자체가 이미 GEO 친화적

조사하면서 놀란 점. Chirpy 테마와 기존 작성 규칙이 이미 GEO 권장 패턴과 상당히 겹칩니다.

“새로운 최적화 기법”보다 기본기를 먼저 챙기는 것이 답이었습니다.

3. Giscus 댓글: 13줄 설정 + App 설치 함정

“정적 페이지인데 댓글이 어떻게 되지?” 가 첫 반응이었습니다. 알아보니 Giscus (GitHub Discussions 기반 위젯) 가 답.

동작 원리

브라우저 → Giscus iframe → GitHub OAuth2 → GraphQL API → Discussions

GitHub 저장소의 Discussions 탭을 댓글 저장소로 사용. 정적 HTML 자체는 변하지 않고 클라이언트가 GitHub API 로 직접 통신합니다. Git 커밋 로그에 댓글이 남지 않고 댓글 100개가 달려도 코드에 영향이 없습니다.

비용은 전부 0원 (GitHub Discussions·Giscus·OAuth2·GraphQL API).

Chirpy 설정 (13줄)

Chirpy 는 Giscus 를 기본 지원합니다. _config.yml 에 두 가지만 추가.

defaults:
  - scope: { path: "", type: posts }
    values:
      layout: post
      comments: true    # false → true

comments:
  provider: giscus
  giscus:
    repo: idean3885/idean3885.github.io
    repo_id: R_kgDORQ49gw
    category: General
    category_id: DIC_kwDORQ49g84C59HT
    mapping: pathname
    lang: ko
    input_position: bottom
    reactions_enabled: 1

repo_id·category_id 는 giscus.app 에서 자동 발급. mapping: pathname 은 포스트 URL 경로별로 Discussion 스레드를 자동 생성.

빠뜨리기 쉬운 함정

배포 후 첫 시도에서 이 에러가 떴습니다.

오류 발생: giscus is not installed on this repository

_config.yml 외에 Giscus GitHub App 설치가 추가로 필요. 설치 후 새로고침하면 정상 동작합니다.

4. 커스텀 도메인: *.github.io 의 GSC 사이트맵 함정

GEO 점검 시점에서 모든 기술 인프라가 정상이었는데 정작 GSC 사이트맵이 2개월간 “읽을 수 없음” 이었습니다.

모든 점검 통과

모든 항목이 정상이었습니다. XML namespace 단순화, jekyll-sitemap 자동 생성 교체, 수동 색인 요청, 결과는 같았습니다.

원인: *.github.io 도메인 자체

Chirpy 이슈 트래커 #2658 에서 같은 현상이 보고되어 있었습니다. *.github.io 에서 GSC 사이트맵 인식이 실패하는 알려진 문제. 커스텀 도메인을 연결하면 즉시 해결된다는 것이 확인된 해결책.

도메인 선택: .dev vs .me

용도 확장성을 고려했습니다. 블로그 외에 개인 서비스용 서브도메인 계획이 있었습니다.

idean.me 선택. 연 $4 차이(.dev 대비) 로 10년이면 $40, 유연성 대비 저렴한 투자.

연결 절차

Cloudflare 에서 도메인 구매 → DNS 에 CNAME 추가 (Proxy status 는 반드시 DNS only 회색 구름, GitHub Pages SSL 발급에 필요) → GitHub Pages Settings 에서 Custom domain 입력 + Enforce HTTPS → _config.yml 의 url 변경 → 루트에 CNAME 파일.

기존 idean3885.github.io 접근은 자동으로 blog.idean.me 로 301 리다이렉트. 이미 공유된 링크는 깨지지 않습니다.

결과

2개월간 기술적 원인을 파고들었지만 답은 도메인에 있었습니다.

5. GA4 추가: 검색 노출 너머의 행동 데이터

사이트맵이 해소되면서 색인이 시작될 시점에 방문자 행동 분석도 같이 추가했습니다.

Chirpy 는 GA4 를 내장 지원. _config.yml 에 측정 ID 한 줄이면 gtag.js 가 자동 삽입됩니다.

analytics:
  google:
    id: G-HRWXK11B6L

페이지뷰·스크롤 90% 도달·이탈 클릭 같은 기본 이벤트가 자동 수집됩니다.

회고: Chirpy 운영의 핵심은 “이미 된 것을 확인하기”

4편의 운영기를 한 글로 묶으면서 가장 일관된 발견은 “Chirpy 가 이미 하고 있는 것이 많다” 였습니다. SEO 도, GEO 의 절반도, 댓글 위젯도, GA4 도 테마가 들고 있습니다. 운영자가 하는 일은 누락된 한 두 가지를 채우는 것과 도메인 같은 장기 의사결정입니다.

다음 과제는 OG 이미지 자동화와 카테고리별 큐레이션 페이지입니다. 운영을 단순화할수록 글쓰기에 시간이 더 갑니다.

이 글은 Claude와 함께 작업했습니다.