외부 연동 구간에서 커넥션 타임아웃이 터졌다. 요청이 커넥션을 기다리다 타임아웃되고, 클라이언트가 재시도하고, 재시도도 이미 고갈된 풀에서 대기하고, 타임아웃이 더 늘어나고, 재시도가 더 쌓인다. 이 재시도 폭풍(retry storm)1은 적당한 부하를 몇 초 안에 전면 장애로 바꿔놓는다.
원인 자체는 기술적으로 단순한 편이었다. 커넥션 풀 조정, circuit breaker2, 재시도 제한 같은 방어 수단은 알려져 있고, 원인을 알면 완화할 수 있다. 문제는 원인을 아는 데까지 가는 시간이 너무 오래 걸렸다는 거다.
되돌아보니 그 지연의 원인은 기술 부족이 아니었다.
장애 대응은 그때그때 임기응변으로 때우는 영역이 아니다. 탐지부터 사후조치까지 이미 정립된 프로세스가 있고, 이걸 따르지 않으면 기술이 아무리 좋아도 대응은 늘어진다.
장애가 터졌을 때 일어난 일을 복기하면 이렇다.
알림이 왔다. 대시보드를 열었다. 실패율이 튄 걸 확인했다. 그다음 — 누가 어떤 구간을 먼저 확인하는지가 불분명했다. 여러 사람이 각자 판단으로 제각기 구간을 들여다봤다. 누군가는 로그를 뒤졌고, 누군가는 네트워크 상태를 봤고, 누군가는 외부 연동 상태를 확인했다. 서로 뭘 하는지 몰랐고, 같은 구간을 중복으로 보는 사람도 있었고, 정작 봐야 할 구간을 아무도 안 보기도 했다.
Google SRE 책은 이런 상태를 정확히 짚는다 — 비관리 인시던트에서 엔지니어들이 조율 없이 각자 시스템을 변경하는 것을 “freelancing”3이라 부른다. 기술에 몰두한 나머지 상황 인식(situational awareness)을 잃고, 리더십이 현황을 파악하지 못하고, 소통이 끊겨 위임조차 불가능해지는 상태.
오늘 우리가 정확히 그 상태였다.
기술적으로 유능한 엔지니어도 프로세스 구조 없이는 혼란을 만든다. 위기에서 조율(coordination)이 개인의 기술력(individual brilliance)보다 중요하다 — 이건 교과서에서 읽으면 당연한 소리인데, 직접 당하고 나니 다르게 읽힌다.
복기에서 가장 뼈아팠던 지점이 있다. 우리는 장애가 터지자마자 근본 원인을 찾으려 했다. 왜 타임아웃이 났는지, 어느 구간에서 문제가 생겼는지, 커넥션 풀 설정이 문제인지 외부 시스템이 문제인지. 당연한 순서처럼 보인다.
그런데 이게 틀렸다.
원인을 규명하는 동안에도 장애는 계속 확대되고 있었다. 실패한 요청은 계속 재시도되고, 재시도가 풀을 더 밀어내고, 실패율은 올라가고. 원인을 찾는 데 쏟는 시간이 곧 장애가 번지는 시간이었다.
인시던트 대응 라이프사이클에서 “완화(containment)”라는 단계가 따로 있는 이유가 이거다. 완화는 문제를 완전히 고치는 게 아니다. 숨 쉴 공간을 만드는 거다. 트래픽을 일부 우회하든, 재시도를 일시 차단하든, 영향 범위를 격리하든 — 원인 파악 전에 먼저 확산을 멈춰야 한다.
“Containment rarely fixes the problem fully, but it restores breathing space.”
이 한 문장이 오늘 우리에게 필요했던 전부다.
돌이켜보면, 우리가 장애 대응이라고 생각한 건 “알림 받고 → 원인 찾고 → 고친다” 정도였다. 3단계. 실제로는 빠져 있는 단계들이 있었고, 빠진 단계마다 대응이 늦어졌다.
인시던트 대응 라이프사이클은 7단계로 정리된다.4
1. 준비(Preparation). 런북, 역할 분담, 연락 체계를 사전에 정의해두는 단계다. 이게 없으면 장애가 터졌을 때 “분 단위로 중요한 순간에 눈먼 채로 허둥대게”(scramble blindly when minutes matter) 된다. 오늘 우리가 그랬다.
2. 탐지(Detection). 모니터링과 알림이 장애를 잡아내는 단계다. 임계값이 너무 높으면 놓치고, 너무 낮으면 알림 피로에 빠진다. 오늘은 탐지 자체는 됐다 — 실패율 급등 알림이 왔다.
3. 트리아지(Triage). 심각도를 판정하고 역할을 배정하는 단계다. 이게 불명확하면 책임 소재를 논쟁하느라 시간을 쓴다. 오늘은 트리아지가 사실상 없었다. 알림이 오자마자 각자가 각자 판단으로 움직였다.
4. 완화(Containment). 위에서 말한 대로, 확산을 먼저 멈추는 단계다. 오늘 우리가 건너뛴 바로 그 단계다.
5. 해결(Resolution). 근본 원인을 제거하는 단계다. 커넥션 풀 설정 조정, 외부 연동 구간 복구 등. 원인을 알아야 가능하므로, 완화로 시간을 번 뒤에 차분하게 진행해야 한다.
6. 복구(Recovery). 시스템을 정상 상태로 되돌리는 단계다. 여기서 조급하면 같은 장애가 재발한다 — 이른바 “요요 장애(yo-yo outages).”5
7. 사후조치(Postmortem). 무슨 일이 있었고, 왜 일어났고, 다음에 어떻게 막을지를 기록하는 단계다. 이건 별도로 얘기할 만큼 중요한 게 있어서 아래에서 따로 쓴다.
이 7단계를 나열하는 건 쉽다. 문제는 각 단계가 없을 때 실제로 무엇이 늦어지는지를 경험하지 않으면 그냥 목록에 머문다는 거다. 오늘 나는 최소한 준비, 트리아지, 완화 세 단계의 부재가 만드는 지연을 직접 겪었다.
잠깐 기술적인 얘기를 하자면, 결제 시스템에서 커넥션 타임아웃은 단순한 실패보다 나쁘다.
실패는 명확하다. 요청이 거부됐고, 결제가 안 됐다. 사용자에게 안내하면 된다. 그런데 타임아웃은 “결제가 된 건지 안 된 건지 모르는” 상태를 만든다. 요청을 보냈는데 응답을 못 받았으니, 상대 시스템에서 처리됐을 수도, 안 됐을 수도 있다.
이 불확실 상태(indeterminate state)에서 재시도 판단이 어려워진다. 재시도했는데 원래 요청이 사실 성공했었다면? 이중 결제가 된다. 그래서 결제 시스템에는 idempotency key6 같은 안전장치가 필요하다 — 같은 키로 재요청이 오면 재처리하지 않고 저장된 결과를 돌려주는 방식이다.
여기서 장애 대응과 연결된다. 안전장치 없이는 장애 대응 자체가 새로운 장애를 만든다. 타임아웃 장애가 터졌을 때 “재시도하면 되지”라는 판단이, idempotency가 없는 시스템에서는 이중 과금을 만든다. 장애 완화가 더 큰 장애를 만드는 역설.
장애가 끝나고 나면 회고를 한다. 대부분 그렇다. 문제는 회고가 실제 변화로 이어지느냐다.
Google SRE Workbook에 있는 한 문장이 정곡을 찌른다.
“To our users, a postmortem without subsequent action is indistinguishable from no postmortem.” 액션 아이템 없는 회고는 회고가 아니다. 더 흔한 문제는, 액션 아이템이 있지만 실행되지 않는 회고다. “모니터링 강화”, “프로세스 개선” 같은 모호한 항목을 적고 다음 스프린트에 묻히면, 다음 장애 때 똑같은 회고를 쓰게 된다.
실효성 있는 postmortem은 몇 가지 조건이 있다.
그리고 이 모든 것의 전제가 blameless7 문화다.
“사람을 고칠 수 없다. 시스템을 고쳐라 (You can’t ‘fix’ people, but you can fix systems).” 비난 문화에서는 정보가 숨겨진다. 장애의 원인을 사람의 실수에 귀착시키면, 다음부터는 실수를 보고하지 않게 된다. Dan Milstein의 말이 이걸 잘 요약한다 — “Let’s plan for a future where we’re all as stupid as we are today.” 사람의 주의력 향상에 기대는 대책은 대책이 아니다. 런북, 자동 알림, circuit breaker 같은 시스템적 방어가 진짜 대책이다.
오늘의 경험과 리서치를 거쳐, 앞으로 장애 대응에 쓸 파이프라인을 정리했다. 교과서를 베낀 게 아니라, 오늘 뭐가 없어서 늦어졌는지를 기준으로 골랐다.
이 파이프라인이 완성형이라고 생각하지 않는다. 다음 장애 때 이걸 써보고, 안 맞는 부분이 나오면 고칠 거다. 하지만 오늘 확실히 배운 건 하나다.
파이프라인이 없는 상태에서 대응하는 것은, 기술이 부족한 것보다 느리다.
커넥션 타임아웃은 알면 고친다. 하지만 누가 어떤 구간을 먼저 보고, 확산을 언제 멈추고, 원인 규명은 그다음에 하고, 끝나고 나서 뭘 바꿔야 하는지 — 이 흐름이 없으면 “아는 것”이 “고치는 것”으로 연결되지 않는다.
오늘 겪은 장애의 근본 원인은 커넥션 타임아웃이다. 하지만 대응이 늦어진 근본 원인은 파이프라인의 부재다. 기술적 원인은 고쳤다. 이제 프로세스적 원인을 고칠 차례다.
실패한 요청이 재시도되면서 이미 고갈된 자원(커넥션 풀 등)에 더 많은 부하를 얹고, 그 부하가 더 많은 실패와 재시도를 낳는 악순환. Michael Nygard가 Release It!(2007)에서 다룬 문제를 Martin Fowler가 Circuit Breaker 패턴으로 정리했다. — Martin Fowler, “CircuitBreaker” ↩
반복적으로 실패하는 호출 대상에 일정 시간 요청을 차단해 장애가 다른 시스템으로 번지는 걸 막는 패턴. — Martin Fowler, “CircuitBreaker” ↩
인시던트 대응 중 엔지니어들이 서로 조율 없이 각자 판단으로 시스템을 변경하는 상태. Google SRE Book이 비관리 인시던트의 전형적 실패 패턴으로 지목한다. — Google SRE Book, Ch.14 Managing Incidents ↩
Preparation, Detection and Alerting, Triage and Prioritization, Containment, Resolution and Eradication, Recovery, Postmortem and Continuous Improvement. — Rootly, “Incident Response Lifecycle Process” ↩
복구를 서두르다 회귀 모니터링 없이 트래픽을 되돌려 같은 실패 모드가 다시 나타나는 현상. — Rootly, “Incident Response Lifecycle Process” ↩
클라이언트가 요청에 고유 키를 실어 보내고, 서버는 같은 키로 재요청이 오면 재처리 없이 저장된 결과를 그대로 돌려준다. 이 장치가 없으면 타임아웃 뒤의 재시도가 이중 결제로 이어질 수 있다. — DZone, “Art of Idempotency” ↩
인시던트에 관여한 모두가 그 순간 가진 정보로 최선의 판단을 했다고 전제하는 회고 문화. 비난 문화에서는 처벌이 두려워 문제가 드러나지 않는다는 게 핵심 근거다. — Google SRE Book, Ch.15 Postmortem Culture ↩
MTTR(Mean Time to Resolve) — 탐지부터 완전 복구까지 걸리는 총 시간. 관측 가능성, 명확한 역할, 숙달된 런북에 투자한 팀이 개인의 영웅적 대응에 의존하는 팀보다 낮은 MTTR을 기록한다. — PagerDuty, “Best Practices to Reduce MTTR” ↩
정확히는, 지금의 서비스를 설명하지 못하는 문서가 그렇다.
처음부터 틀린 문서는 아니었을 것이다. 만들어질 당시에는 서비스의 구조와 흐름을 제대로 담고 있었을지도 모른다. 그러다 새로운 기능이 추가되고, 책임이 분리되고, 다른 시스템과의 연결이 늘어나는 동안 문서는 작성된 순간에 그대로 머물렀다.
서비스는 가만히 있지 않는다. 운영 과정에서 발견한 문제를 고치고 새로운 요구사항을 받아들이며 계속 개선되고 확장된다.
문서는 그렇지 않다. 코드와 설정은 서비스가 동작하려면 함께 바뀌어야 하지만, 문서는 고치지 않아도 빌드가 깨지지 않고 배포도 막히지 않는다. 그렇게 서비스가 앞으로 나아가는 동안 문서는 현실에서 조금씩 멀어진다.
살아 움직이는 서비스를 설명하려면 문서도 함께 움직여야 한다. 서비스가 바뀌면 문서도 바뀌고, 구조가 달라지면 다이어그램도 다시 그려야 한다. 필요할 때 현재의 모습을 확인할 수 있어야 문서는 쓸모를 유지한다.
문제는 서비스와 문서를 계속 동기화하는 비용이다.
나는 이 비용을 AI로 낮출 수 있는지 확인하기 위해 flowcast를 만들고 있다.
새 서비스를 맡을 때마다 이 문제를 반복해서 만났다. 담당이 정해지고 저장소를 열면 실행 방법은 적혀 있지만, 정작 서비스를 이해할 수 있는 문서는 없었다. 위키에 그림이 남아 있어도 지금 구조와 맞는지 아무도 장담하지 못했다.
문서가 없어도 코드 레벨은 어떻게든 따라갈 수 있다. 클래스와 호출 관계를 좇다 보면, 시간이 걸릴 뿐 서비스가 무슨 일을 하는지는 어느 정도 드러난다. “문서가 없으면 코드가 문서”라는 말이 아주 틀린 건 아니다. 적어도 코드 레벨에서는 그렇다.
문제는 서비스 경계 바깥의 흐름이다. 요청이 어느 존에서 시작해 어떤 게이트웨이와 큐를 거쳐 다른 서비스로 넘어가는지는 코드 한 곳을 읽는다고 나오지 않는다. 설정 파일과 방화벽 규칙, 배포 스크립트, 그리고 “그건 옆 팀에 물어봐야 한다”는 사람의 기억에 흩어져 있다.
게다가 이 흐름에는 여러 사람이 얽혀 있다. 개발자뿐 아니라 인프라 담당자, 다른 서비스 담당자, 그리고 “이 결제가 어디를 거쳐 나가느냐”를 묻는 업무 담당자도 같은 구조를 이해해야 한다. 그래서 모두가 함께 볼 수 있는 그림 한 장이 절실한데, 정작 그 그림을 믿기 어렵다.
그림이 없으면 새로 만들면 된다고 생각했다. 다이어그램을 하나 그려 위키에 올리고 나면 거기서 끝이 아니다. 유지보수가 시작된다.
서비스 경계를 리팩터링하거나 큐를 추가하거나 내부 API 이름을 바꾸면 코드는 달라지지만 위키 속 그림은 그대로 남는다. 누가 일부러 방치해서가 아니다. 그림을 고치는 일은 늘 더 급한 일에 밀린다.
수작업 다이어그램의 진짜 비용은 처음 그릴 때보다 두 번째 수정에서 드러난다. 한 장을 그리는 일은 할 만하다. 구조나 스타일이 바뀌어 여러 장을 다시 손봐야 하면 그때부터 관련된 그림을 하나씩 찾아 같은 작업을 반복하게 된다. 낡은 그림은 이 비용 구조가 만든 결과다.
여기서 생각이 하나 바뀌었다.
다이어그램은 독립된 산출물이 아니라 추적 가능한 근거의 파생물이어야 한다.
근거가 되는 코드나 설정, 원문 없이 떠 있는 그림은 나중에 고치려고 해도 무엇을 기준으로 확인해야 할지 알 수 없다. 확인할 수 없으니 고치기 어렵고, 고치기 어려우니 낡는다. 예쁜 그림 한 장보다 출처를 되짚을 수 있는 그림이 더 중요한 이유다.
그런데 출처를 연결한다고 문제가 끝나는 것은 아니다. 서비스가 바뀔 때마다 사람이 다시 자료를 읽고 그림을 고쳐야 한다면 동기화 비용은 여전히 사람의 몫이다.
문서화가 중요하다는 데 반대하는 사람은 없다. 회고 때마다 나오는 말이고, 다음 일정이 시작되면 먼저 밀리는 항목일 뿐이다.
나도 한동안 개인 시간을 내서 이 간격을 메우려고 했다. 담당 서비스의 흐름을 그려보고, 다른 팀에 물어 빈칸을 채우고, 여러 그림의 스타일을 맞췄다. 그렇게 다 그리고 나면 서비스는 다시 달라져 있었다. 살아 움직이는 서비스를 정지된 그림으로 계속 따라가는 방식에는 한계가 있었다.
그래서 질문을 바꿔보기로 했다.
사람이 문서를 더 열심히 관리하는 대신, AI를 잘 활용해 동기화 비용을 낮출 수는 없을까?
여기서 왜 하필 그림인지도 짚어볼 필요가 있다.
그림이 글보다 기억에 잘 남는다는 것은 인지심리학에서 오래 다뤄진 주제다. dual coding theory는 시각 정보와 언어 정보가 분리되면서도 연결된 체계로 처리된다고 본다. Shepard의 1967년 실험에서는 수백 장의 그림을 다시 봤을 때 알아보는 재인 정확도가 90%대 후반에 이르렀다.
그렇다고 이 결과를 “다이어그램이 복잡한 구조를 더 잘 이해하게 한다”는 주장으로 곧장 옮길 수는 없다. 소프트웨어 아키텍처를 직접 대상으로 한 Heijstek 등의 통제 실험에서는 그래픽과 텍스트 중 어느 쪽도 유의하게 더 효율적이지 않았다. 오히려 텍스트 위주로 본 참가자들이 토폴로지 관련 문항에서 더 높은 점수를 받았다.
그림이 언제나 글보다 나은 것은 아니다. 중요한 것은 표현 수단의 서열이 아니라 정보의 성격에 맞는 표현을 선택하는 일이다. 서비스 사이의 경계와 경로처럼 공간적이고 구조적인 정보는 글만으로 전달하면 독자가 머릿속에서 다시 조립해야 한다. 반대로 잘못 그린 그림은 그럴듯한 오해를 더 빠르게 퍼뜨린다.
그래서 목표는 그림을 많이 만드는 것이 아니다. 근거를 되짚을 수 있고, 변경되면 적은 비용으로 다시 만들 수 있는 그림을 만드는 것이다.
다이어그램을 서비스 변화와 함께 관리하려는 접근은 이미 있다. 그중 하나가 diagrams-as-code다. 그림을 텍스트로 코드 옆에 두고 버전 관리하며 필요할 때 다시 렌더하는 방식이다. C4 model, PlantUML, Mermaid 같은 모델과 도구가 이 계보에 있다.
그림을 PR에서 diff로 확인하고 코드 변경과 함께 갱신한다는 점에서 유지보수 문제에 잘 맞는다. 하지만 내 문제의 절반은 남는다. 그 텍스트를 누군가는 여전히 손으로 써야 하고, 그러려면 그전에 시스템을 이미 이해하고 있어야 한다.
diagrams-as-code가 그림을 관리하는 비용을 낮춘다면, 그보다 앞선 저작 과정에도 AI를 활용해볼 수 있지 않을까. 사람이 코드와 설정, 기존 문서를 매번 처음부터 읽고 흐름을 옮기는 대신 AI가 먼저 자료를 읽어 초안을 만들게 하는 것이다. 사람의 역할은 빈 화면에서 작성하는 쪽에서, AI가 만든 결과의 근거를 확인하고 잘못된 부분을 바로잡는 쪽으로 옮겨간다.
이 접근이 동기화를 자동으로 해결해주지는 않는다. 다만 문서를 다시 만드는 비용을 낮춘다면, 서비스가 바뀔 때 문서를 갱신하는 일을 지금보다 더 자주 시도할 수 있다.
이 가능성을 확인해보기 위해 만들고 있는 것이 flowcast다.
현재 flowcast에서는 확정된 흐름 문서와 명세, 설명, PPT 같은 입력 자료를 다이어그램 단위로 나눈다. 그리고 검토와 수정, 재생성까지 잇는 구조를 시험하고 있다. 에이전트가 자료에서 관계를 추출해 중간 표현을 만들고 다이어그램으로 렌더하는 방식이다. 각 다이어그램에는 근거가 된 원문의 경로를 남겨 검토할 때 출처를 되짚을 수 있게 하려 한다.
flowcast를 처음부터 프로젝트 시각화 도구로 설계한 것은 아니다. 출발점은 내가 실제 프로젝트를 이해하고 설명하는 데 필요했던 그림이었다.
필요한 그림이 하나 생길 때마다 그 관점을 다루는 방법을 별도의 스킬로 만들었다. 지금의 flowcast는 입력을 다이어그램 단위로 나누고, 무엇을 보여줘야 하는지에 따라 이 스킬들을 선택해 연결한다. 하나의 자료에서 여러 그림이 필요하면 각각의 스킬이 맡을 단위로 나눠 동시에 처리한다.
만들면서 프로젝트를 시각화한다는 의미도 조금씩 넓어졌다. 여기서 프로젝트는 일정이나 Issue, WBS 같은 관리 현황을 뜻하지 않는다. 내가 보고 싶은 것은 코드와 설정, 컴포넌트와 인프라, 요청과 데이터가 함께 움직이는 소프트웨어 프로젝트 자체다.
하나의 프로젝트도 질문에 따라 필요한 그림이 달라진다.
| 관점 | 알고 싶은 것 | 스킬 |
|---|---|---|
| 동작 | 요청과 응답이 어떤 순서로 오가는가 | sequence |
| 실행 환경 | 서비스가 어느 존과 인프라를 거치는가 | topology |
| 구성 | 컴포넌트와 포트가 어떻게 연결되는가 | component |
지금 있는 것은 이 셋뿐이다. 소스 구조나 의존성, 데이터 흐름처럼 더 다뤄야 할 관점이 남아 있지만 아직 이름만 붙여둔 단계라 약속처럼 늘어놓지는 않겠다.
위에서 본 시퀀스가 서비스의 동작을 시간순으로 본 것이라면, 실행 환경(topology)과 구성(component)은 다른 질문에 답하는 관점이다. 세 예시는 같은 시스템이 아니라 관점마다 다른 합성 예제이고, flowcast로 그리면 각각 아래처럼 보인다.
세 관점을 직접 움직여 가며 보고 싶다면 flowcast 예제 갤러리에 인터랙티브 버전이 있다.
앞으로도 모든 정보를 한 장에 욱여넣는 거대한 스킬을 만들 생각은 없다. 프로젝트를 이해하면서 생기는 질문마다 적합한 관점을 작은 스킬로 만들고, flowcast가 필요한 관점을 선택하고 조합하게 하는 방향을 생각하고 있다.
아직 스킬로 만들지 않았지만 가장 확인해보고 싶은 관점은 변화다. 코드나 설정이 바뀌었을 때 영향을 받는 흐름과 다이어그램을 찾아내 다시 생성하고, 사람이 변경 내용과 근거를 검토한다. 이것이 된다면 서비스와 문서 사이의 간격을 지금보다 적은 비용으로 줄일 수 있다. 낡은 문서라는 처음의 문제로 그대로 돌아오는 셈이다.
결국 만들고 싶은 것은 그림을 그리는 스킬 하나가 아니다. 소프트웨어 프로젝트를 여러 관점에서 읽고, 프로젝트가 변하면 그 관점도 다시 갱신할 수 있는 시각화 스킬의 집합이다.
물론 AI가 그린 그림을 그대로 믿을 수는 없다. 입력 문서가 이미 낡았을 수도 있고, 코드만으로 드러나지 않는 운영 정보도 있으며, AI가 관계를 잘못 추론할 수도 있다. 사람의 검토와 판단은 여전히 필요하다.
그래서 flowcast는 낡은 문서 문제의 해결책이라고 말할 수 없다. AI를 잘 활용하면 더 적은 비용으로 서비스와 문서 사이의 간격을 줄일 수 있는지, 그 접근이 실제로 쓸 만한지 확인해보려고 만들고 있는 도구다.
각 스킬이 어떤 자료를 읽고, 어떻게 관점을 나누고, 어떤 방식으로 근거를 확인하는지는 다음 편들의 몫으로 남겨둔다. 이번 글에서 세워두고 싶은 출발점은 하나다.
]]>서비스가 살아 움직인다면 문서도 함께 움직여야 한다. 나는 AI가 그 동기화 비용을 얼마나 낮출 수 있는지 확인해보려 한다.
교체 커밋과 CLAUDE.md 변경 이력에 나는 이유를 이렇게 적어뒀다.
Chirpy 저장소는 archived 상태라 유지보수 대신 교체 선택.
이 글은 그 한 줄이 틀렸다는 걸 나중에 알게 된 이야기다. 그 착오 덕분에 “왜 옮겼는가”를 정직하게 다시 쓰면 무엇이 남는지를 짚어본 이야기이기도 하다.
테마를 옮기고 한참 뒤, 이 결정을 글로 정리하려고 저장소 상태를 다시 확인했다. 그런데 방향이 뒤집혀 있었다.
즉 나는 “소스가 죽었으니 옮긴다”고 적어놓고, 실제로는 살아 있는 테마를 떠나 멈춘 테마로 이사했다. 교체의 근거였던 “archived”라는 사실은 떠나온 곳이 아니라 도착한 곳에 붙는 라벨이었다.
이게 이 글에서 제일 하고 싶은 이야기다. 결정 자체가 틀렸다는 게 아니라 — 뒤에서 보겠지만 옮긴 건 여러모로 잘한 일이었다 — 결정을 정당화하려고 갖다 붙인 “검증 가능한 사실”을 검증하지 않고 적었다는 것. changelog에 “저장소가 archived다” 같은 문장을 쓸 때, 그건 취향이나 판단이 아니라 30초면 확인되는 팩트다. 그 30초를 건너뛰면, 미래의 내가 그 기록을 근거로 삼았다가 이렇게 뒤집힌다.
역설적이게도 이 교훈을 가장 확실하게 가르쳐준 건 이 글을 쓰기 위한 리서치 그 자체였다.
가짜 이유를 걷어내고 나면 진짜 동인이 남는다. 그건 “archived”보다 훨씬 정직하고, 훨씬 설득력 있다.
이 블로그의 컨셉은 인사이트다. 절차를 나열하는 튜토리얼이 아니라 “왜 그렇게 판단했는지, 무엇을 배웠는지”를 쓰는 공간. 이 컨셉은 테마를 옮기기 전부터 이미 정해져 있었다. 그런 글에 Chirpy가 제공하는 기능 대부분은 그냥 안 쓰는 무게였다.
교체 커밋 하나의 순증감이 이걸 그대로 보여준다.
+136 / -706 lines
무엇이 사라졌는지가 더 흥미롭다.
_config.yml이 237줄 → 72줄로 줄었다. PWA, comments, analytics, webmaster verification, collections/defaults 같은 Chirpy 전용 블록이 통째로 빠졌다..devcontainer/, .vscode/, tools/run.sh, tools/test.sh 같은 스캐폴딩이 사라졌다.chirpy-static-assets)도 제거했다.여기서 배운 건 조금 반직관적이다. 기능이 많은 걸 버리는 것 자체가 이득이었다. Chirpy가 나빠서가 아니다. 인사이트 블로그라는 목적에는 그 기능들이 대부분 불필요했고, 안 쓰는 기능은 유지보수 면적으로만 남는다. “더 많은 걸 주는 도구”가 항상 더 좋은 선택은 아니라는, 알면서도 자주 잊는 사실을 700줄 삭제로 다시 확인했다.
가장 아팠던 지점은 여기다. 나는 이 작업을 “파일 몇 개 바꾸는 테마 교체”로 생각했는데, 실제로는 배포 파이프라인을 바꾸는 일이었다.
Chirpy는 GitHub Actions로 사이트를 직접 빌드해서 배포했다.
워크플로가 jekyll build로 _site를 만들고, htmlproofer로 검사한 뒤, 그 결과물을 Pages에 올리는 구조다.
Type Theme로 옮기면서 나는 이 방식을 버리고 GitHub Pages 네이티브 빌드(Pages가 알아서 Jekyll을 돌리는 방식)로 전환했다. Actions로 직접 빌드할 이유가 없어졌으니까.
문제는 저장소에 .nojekyll 파일이 그대로 남아 있었다는 것이다.
같은 파일인데 두 배포 모델에서 의미가 정반대다.
_site를 완성해서 넘긴다. 그러니 Pages한테 “여기서 Jekyll 또 돌리지 말고 준 대로 서빙해”라고 말하는 .nojekyll이 맞는 신호다..nojekyll이 “Jekyll 돌리지 마”라고 막아버리니, 소스가 처리되지 않은 채 그대로 노출됐다. 사이트가 깨졌다.결국 별도 hotfix 커밋으로 정리했다.
fix: remove .nojekyll so GitHub Pages legacy build runs Jekyll
교훈은 파일 한 줄보다 크다.
배포 모델을 바꾸면, 이전 모델에서는 옳았던 설정이 새 모델에서는 지뢰가 된다.
.nojekyll은 버그가 아니라 “예전 문맥에서는 정답이었던 것”이다.
파이프라인을 갈아탈 때 위험한 건 새로 추가하는 것보다 이전 파이프라인이 남기고 간 전제들이다.
그것들은 조용히 남아 있다가, 문맥이 바뀐 순간 반대로 작동한다.
앞에서 “archived 테마로 이사했다”는 게 실수처럼 들렸을 수 있다. 하지만 archived라는 사실을 알고 나면, 오히려 그걸 안전하게 다루는 방법이 명확해진다.
원격 테마(remote_theme)를 브랜치 이름으로 추적하면, 그쪽이 언제 바뀌든 내 사이트가 따라 흔들린다.
그래서 재현 가능한 빌드를 위해 세 겹으로 고정했다.
# _config.yml — 테마를 커밋 SHA로 못 박음 (브랜치 추적 X)
remote_theme: rohanchandra/type-theme@c6ec5a69ff7dfe2df193be08515193c72bd4a55d
# Gemfile — github-pages gem 버전 고정
gem "github-pages", "232", group: :jekyll_plugins
여기에 더해 Gemfile.lock을 .gitignore에서 빼고 커밋에 포함시켰다.
테마 SHA, gem 버전, lockfile — 세 개를 동시에 잠근 것이다.
흥미로운 건, archived라는 사실이 이 결정을 오히려 정당화한다는 점이다. 움직이지 않는 테마이기 때문에 특정 커밋에 묶어도 뒤에서 갱신돼 깨질 일이 없다. “죽은 프로젝트에 의존한다”는 리스크를, “죽었으니 절대 안 움직인다”는 안정성으로 뒤집은 셈이다. (다만 이건 보안 패치도 안 온다는 뜻이기도 하다. 원격 테마에 스크립트가 많았다면 다시 고민했을 것이다.)
원격 테마의 몇몇 기본값은 내 상황에 안 맞아서 손을 봐야 했다. 선택지는 둘이었다.
2번을 택했다. 실제로 오버라이드한 건 head.html, header.html, default.html, post.html, page.html, main.scss 정도다.
그리고 이 트레이드오프의 대가(동기화 부담)를 잊지 않으려고 커밋 메시지에 지시문으로 박아뒀다.
Keep theme overrides synchronized if the pinned Type Theme commit is intentionally upgraded.
정답이 있는 선택은 아니었다. 다만 “작은 유지보수 면적 + 명시된 동기화 리스크”가, “포크로 얻는 자유 + 무한 유지보수 면적”보다 이 블로그 규모엔 맞다고 판단했다. 중요한 건 트레이드오프를 고른 것보다, 고른 뒤에 그 대가를 기록으로 남긴 것이다.
/blog라는 접두어가 만든 버그들이 블로그는 user page(user.github.io)가 아니라 project page(user.github.io/blog)다.
즉 baseurl이 /blog다.
그런데 원본 테마의 URL 처리 기본값들은 대체로 user page(baseurl 없음)를 가정하고 있었다.
그 간극에서 같은 종류의 버그가 세 번 터졌다. 전부 “/blog가 한 번 더 붙는” 문제였다.
1. 페이지네이션 경로 중복
# baseurl이 이미 /blog인데 경로에 blog/를 또 넣어 /blog/blog/page2/가 됨
paginate_path: "blog/page:num" # 문제
paginate_path: "/page:num/" # 수정
2. 검색 결과 URL의 이중 슬래시
<!-- baseurl + 앞에 /가 붙은 post.url = /blog//... -->
"{{ site.baseurl }}/{{ post.url }}" <!-- 문제 -->
"{{ post.url | relative_url }}" <!-- 수정 -->
3. 빈 feature image가 홈페이지를 배경으로 요청
feature 이미지가 없는 글에서, 원본 테마는 background-image: url('/blog/')를 깔았다.
빈 값에 baseurl만 남아 사이트 홈페이지 자체를 배경 이미지로 불러오는 요청이 나간 것이다.
page.feature-img가 있을 때만 배경을 지정하도록 오버라이드해서 막았다.
세 버그의 해법이 전부 같은 방향이라는 게 핵심이다.
baseurl을 문자열로 손수 이어 붙이지 말고, relative_url 같은 Jekyll 필터나 명시적 조건에 맡기는 것.
문자열 연결로 URL을 만들면 “붙는다/안 붙는다”의 경계에서 반드시 사고가 난다.
이 버그 클래스는 user page에서는 절대 안 보인다. baseurl이 빈 문자열이라 이중으로 붙어도 티가 안 나니까.
테마를 가져다 쓸 때 그 테마가 어떤 배포 형태를 가정하는지는, 문서가 아니라 이렇게 URL이 깨지고 나서야 드러난다.
여기서 한 판단이 스스로도 의외였다. 글을 한 편도 쓰기 전에 계약 테스트와 CI부터 깔았다.
포스트 6개짜리 픽스처를 만들어 실제로 jekyll build를 돌리고, 생성된 결과물을 단언으로 검증하는 테스트다.
위에서 고친 버그들이 회귀하지 않는지를 실제 빌드 산출물에 대고 확인한다.
# test/site_output_test.rb — 생성된 HTML을 직접 단언
refute_match(%r{"url": "/blog//}, search) # 이중 슬래시 재발 방지
refute_includes about, "background-image: url('/blog/')" # 홈 배경 요청 방지
assert_includes search, 'integrity="sha384-' # 검색 CDN 스크립트 SRI
assert_includes search, 'aria-label="검색"' # 접근성
그리고 이걸 CI로 강제했다. push/PR마다 Ruby 3.4 환경에서 이 테스트가 돈다. 여기서 GitHub Actions의 역할이 바뀌었다는 게 재밌다. 예전엔 Actions가 “배포”를 담당했는데, 이제 배포는 Pages 네이티브가 맡고 Actions는 “빌드 계약을 먼저 검증”하는 게이트가 됐다. 같은 도구, 다른 임무.
콘텐츠가 0개인데 테스트부터 까는 게 과해 보일 수 있다.
하지만 인사이트 블로그의 신뢰는 글 내용에서만 오는 게 아니다.
독자가 링크를 눌렀을 때 사이트가 안 깨지는 것, 페이지네이션이 정상인 것, 검색이 되는 것 — 이 기반이 무너지면 글이 아무리 좋아도 신뢰가 안 쌓인다.
.nojekyll 하나로 사이트가 통째로 깨졌던 경험이 이 판단을 밀어줬다.
곁다리로 하나 더 드러났다.
테마를 교체하며 빌드 exclude 목록을 정리하다가, CLAUDE.md가 정적 파일로 그대로 서빙되고 있었다는 걸 발견했다.
프론트매터 없는 최상위 .md는 Jekyll이 그냥 복사해서 공개 페이지로 노출한다.
exclude에 추가해서 막았지만, 교훈은 그대로다. 빌드 방식이 바뀌면 “무엇이 공개되는가”의 규칙도 같이 바뀐다. 테마 교체는 렌더링만 바꾸는 게 아니라, 노출 경계도 다시 그린다.
테마 하나 옮긴 작업치고 배운 게 많았는데, 정리하면 결국 하나로 모인다.
“왜”를 기록할 때, 그 안에 섞인 “검증 가능한 사실”은 그 자리에서 검증하라. “단일 컬럼이 컨셉에 맞아서”는 판단이라 틀릴 수 없지만, “저장소가 archived라서”는 팩트라서 틀릴 수 있다. 나는 후자를 확인 없이 적었고, 그 한 줄이 이 글 전체를 다시 쓰게 만들었다.
나머지 교훈들도 결이 같다.
.nojekyll)가 새 문맥에서 반대로 작동한다./blog 접두어가 그걸 세 번 가르쳐줬다.다시 한다면 딱 하나를 바꾸겠다. 결정을 changelog에 적는 순간, “이 문장은 판단인가 사실인가”를 한 번 자문하는 것. 사실이라면, 적기 전에 확인하는 30초. 그 30초가 없어서 이 글이 태어났다는 게, 조금 웃기면서도 이 블로그의 컨셉에 가장 잘 맞는 결말인 것 같다.
]]>