제가 함께 일했던 모든 팀은 아무도 신뢰하지 않는 런북 (Runbook)들로 가득 찬 폴더를 가지고 있었습니다. 런북들은 장애 (Incident)가 발생하는 도중이나 직후에, 지쳐 있는 누군가가 다음 사람이 똑같은 고통을 겪지 않기를 바라는 마음으로 작성되었습니다. 작성된 당일에는 정확했습니다. 하지만 시스템은 변했고, 런북은 변하지 않았으며, 그 둘 사이의 간극은 다음 장애가 발생할 때까지 조용히 벌어졌습니다. 결국 당직자 (On-call)는 4단계가 6개월 전에 이름이 바뀐 서비스를 가리키고 있다는 사실을 발견하게 됩니다.

런북의 문제는 사람들이 그것을 작성하지 않아서가 아닙니다. 문제는 런북이 소프트웨어인 척하는 문서 조각이라는 점입니다. 런북은 인간이 압박감 속에서, 즉 인간이 무언가를 완벽하게 수행하기 가장 어려운 바로 그 순간에 완벽하게 실행해야 하는 절차를 설명합니다. 이 형식은 작업에 적합하지 않습니다. 기록할 만큼 중요한 절차라면 스스로 실행할 수 있거나, 적어도 인간이 단계를 수행할 때 스스로의 단계를 점검할 수 있어야 합니다.

Claude Code는 런북을 정적인 텍스트 대신 실행 가능한 아티팩트 (Artifact)로 취급할 수 있게 함으로써 런북에 대한 제 생각을 바꾸어 놓았습니다. 이제 런북은 더 이상 위키 (Wiki) 페이지가 아닙니다. 그것은 스킬 (Skill)이 읽고, 검증하고, 단계를 밟아 나갈 수 있는 구조화된 문서이며, 각 동작 전에 전제 조건 (Preconditions)을 확인하고 각 동작 후에 결과를 확인합니다. 판단이 필요한 결정에는 인간이 개입(Human-in-the-loop)하지만, 지루한 검증 작업은 자동으로 이루어집니다. 워크플로 (Workflow)가 어떻게 구성되었는지 소개합니다.

정적인 런북이 정작 필요할 때 실패하는 이유

정적인 런북은 특정한 방식으로, 그리고 예측 가능한 방식으로 실패합니다. 누군가 읽어보고 고개를 끄덕이는 평온한 검토 시간에는 잘 작동합니다. 하지만 장애가 발생했을 때, 즉 런북을 따르는 사람이 더 이상 현실과 일치하지 않는 단계에 부딪혀 장애 상황 한복판에서 런북을 믿을지 아니면 자신이 파악한 상황을 믿을지 결정해야 할 때 실패합니다.

그 결정은 새벽 3시에 누군가에게 요구할 수 있는 최악의 상황입니다. 그들은 이미 스트레스를 받고 있고, 맥락(context)이 부족하며, 상황을 더 악화시킬까 봐 걱정하고 있습니다. 그들이 쉽게 감지할 수 없는 방식으로 틀렸을지도 모르는 문서를 건네주는 것은, 장애(incident) 자체 위에 불확실성이라는 두 번째 층을 더하는 격입니다. 런북(runbook)은 인지 부하(cognitive load)를 줄여주어야 했습니다. 하지만 대신 그것은 다시 한번 의구심을 갖게 만드는 또 다른 대상이 되어버립니다.

근본적인 원인은 런북이 드리프트(drift, 괴리) 현상을 겪고 있으며, 그 드리프트를 잡아낼 수 있는 것이 아무것도 없기 때문입니다. 코드는 테스트(tests)가 있습니다. 인프라에는 드리프트 탐지(drift detection)가 있습니다. 하지만 런북에는 둘 다 없습니다. 런북은 위키(wiki)에 머물며 자신이 설명하는 시스템으로부터 서서히 멀어지고, 그 괴리를 감지할 수 있는 유일한 탐지기는 다음 장애 상황에서 고통스러운 방식으로 이를 발견하게 되는 인간뿐입니다.

작성된 이후 한 번도 실행되지 않은 런북은 런북이 아닙니다. 그것은 절차에 대한 추측일 뿐이며, 추측은 장애 상황에서 정확히 피해야 할 요소입니다. 런북의 가치는 그것이 얼마나 최근에 작동함이 증명되었느냐에 비례합니다.

아래의 워크플로우(workflow)는 드리프트를 메우고, 런북의 신뢰성을 유지하며, 사람들이 불신하는 문서에서 사람들이 의지할 수 있는 절차로 바꾸기 위해 제가 구축한 것입니다. Claude Code의 기술(skills)이 검증(verification)의 부담을 짊어짐으로써, 인간은 판단(judgment)에 집중할 수 있습니다.

상황이 깨지는 순간을 제가 어떻게 다루는지에 대한 더 넓은 맥락을 알고 싶다면, Claude Code for Incident Response 워크플로우에서 이러한 런북들이 연결되는 더 광범위한 대응 프로세스를 설명하고 있습니다.

구조화 기술 (The Structure Skill)

첫 번째 기술은 자유 형식의 런북을 구조화된 런북으로 변환합니다. 위키 페이지나 대략적인 메모 세트가 주어지면, 모든 단계가 정의된 형태를 갖춘 런북을 생성합니다.

각 단계는 전제 조건 (precondition), 실행 동작 (action), 그리고 검증 (verification)을 포함합니다. 전제 조건은 해당 단계를 안전하게 실행하기 전에 시스템이 반드시 갖추어야 하는 상태를 의미합니다. 실행 동작은 실제로 일어나는 구체적인 행위입니다. 검증은 해당 동작이 의도한 대로 수행되었음을 확인해 주는 관찰 가능한 신호입니다. 이 세 가지가 모두 없는 단계는 불완전한 것으로 간주되며, 스킬 (skill)이 이를 표시합니다.

이러한 구조는 작성자가 자유 형식의 텍스트에서는 건너뛰기 쉬운 절차의 세부 사항들을 깊이 고민하도록 강제합니다. 단락 안에 "워커(worker)를 재시작한다"라고 쓰는 것은 쉽습니다. 하지만 재시작을 안전하게 만드는 전제 조건을 작성하는 것은 더 어렵고, 재시작이 단순히 문제를 반복하는 것이 아니라 실제로 도움이 되었음을 확인하는 검증을 작성하는 것은 훨씬 더 어렵습니다. 이 구조는 작성자가 내용을 채울 수 있는 맥락을 여전히 가지고 있을 때, 그러한 공백들을 수면 위로 드러냅니다.

또한 이 스킬은 각 단계의 의도 (intent)를 포착합니다. 기계적인 동작과 더불어, 해당 단계가 왜 존재하는지, 그리고 이 단계를 건너뛰었을 때 어떤 문제가 발생할지를 기록합니다. 이러한 의도는 런북이 작성자가 예상하지 못한 상황에 직면했을 때, 사람이 올바른 결정을 내릴 수 있게 해주는 핵심 요소가 됩니다.

검증 스킬 (The Validation Skill)

두 번째 스킬은 시간이 지나도 런북의 신뢰성을 유지해 줍니다. 정해진 일정에 따라 각 런북을 훑으며 참조(reference)들이 여전히 유효한지 확인합니다.

모든 런북은 현실 세계에 대한 참조로 가득 차 있습니다. 서비스 이름, 대시보드 링크, 메트릭 쿼리 (metric queries), 설정 키 (config keys), 호스트 그룹 (host groups), 에스컬레이션 연락처 (escalation contacts) 등이 그것입니다. 이러한 참조들은 각각 노후화될 수 있습니다. 검증 스킬은 이를 실제 시스템과 대조하여 더 이상 유효하지 않은 참조들을 보고합니다. 이름이 변경된 서비스, 삭제된 대시보드, 더 이상 존재하지 않는 메트릭, 혹은 퇴사한 온콜 (on call) 담당자 등이 이에 해당합니다.

이 보고서는 정적인 런북에는 결코 없었던 드리프트 탐지기 (drift detector) 역할을 합니다. 장애 상황 중에 사람이 깨진 참조를 발견하는 대신, 검증 스킬은 평온한 화요일에 이를 발견하고 일반적인 유지보수 작업으로 등록합니다. 덕분에 런북은 수정 비용이 저렴할 때 바로 수정될 수 있습니다.

이 스킬은 스스로 참조(references)를 수정하려고 시도하지 않습니다. 런북(runbook)의 자동 수정은 반드시 사람이 의도를 확인해야 하는 종류의 변경 사항입니다. 왜냐하면 서비스 이름이 변경되었다는 것이 해당 단계가 새로운 곳을 가리켜야 함을 의미할 수도 있고, 혹은 해당 단계가 이제 더 이상 필요하지 않음을 의미할 수도 있기 때문입니다. 이 스킬은 드리프트(drift, 차이)를 드러내고 판단은 사람에게 맡깁니다.

검증 실행(validation run)은 커버리지 보고서(coverage report) 역할도 합니다. 이는 어떤 런북이 최근에 검증되었고 어떤 것이 오래되었는지(stale)를 보여주며, 이를 통해 운영 문서가 어디까지 신뢰할 수 있고 어디부터 신뢰할 수 없는지 한눈에 쉽게 파악할 수 있게 해줍니다.

이와 동일한 아이디어가 절차(procedures)가 아닌 코드에 어떻게 적용되는지 알고 싶다면, Claude Code for Dependency Management에서 사용된 접근 방식은 계속해서 변하는 대상(moving target)을 제어하기 위해 유사한 지속적 검증 루프(continuous verification loop)를 사용합니다.

실행 스킬 (The Execution Skill)

세 번째 스킬은 실제 장애 상황(incident) 동안 사람이 런북을 따라갈 수 있도록 안내합니다. 이 스킬은 구조화된 런북을 읽고 절차를 한 번에 한 단계씩 실행합니다.

각 단계 이전에, 스킬은 실제 시스템(live system)을 대상으로 전제 조건(precondition)을 확인합니다. 만약 전제 조건이 충족되지 않으면, 스킬은 맹목적으로 진행하는 대신 실행을 멈추고 무엇을 발견했는지 설명합니다. 이것이 바로 정적인 런북이 제공할 수 없는 안전 속성(safety property)입니다. 압박감을 느끼는 사람은 전제 조건 확인을 건너뛸 수 있지만, 스킬은 그러지 않습니다.

스킬은 상태를 변경하는 모든 작업에 대해 사람의 확인을 거친 후에만 액션을 실행합니다. 정보를 수집하는 읽기 전용(read only) 단계의 경우, 자동으로 진행하고 결과를 제시합니다. 재시작, 스케일링(scale), 페일오버(fail over) 또는 그 외 시스템을 변형(mutate)시키는 단계의 경우, 액션을 제시하고 사람이 승인할 때까지 기다립니다. 이러한 구분은 정보 수집과 같은 지루한 작업에서는 사람을 배제하면서도, 중대한 결정에 대해서는 사람이 통제권을 유지할 수 있게 합니다.

각 단계가 끝날 때마다, 해당 스킬(skill)은 검증(verification)을 실행하고 예상된 신호가 나타났는지 여부를 보고합니다. 만약 검증에 실패하면, 스킬은 중단되고 불일치 사항을 표면화합니다. 실패한 검증을 통과하여 진행되는 런북(runbook)은 작은 문제를 큰 문제로 키우는 런북이며, 이 스킬은 그러한 행위를 거부하도록 설계되었습니다.

전체 실행 과정은 타임스탬프(timestamps)와 함께 로그(log)로 기록됩니다. 장애 상황(incident)이 종료되면, 이 로그는 무엇이, 언제 수행되었는지, 그리고 각 단계에서 시스템의 상태가 어떠했는지를 보여주는 정확한 기록이 됩니다. 해당 기록은 사후 분석(postmortem)의 기초 자료가 되며, 런북을 개선하기 위한 증거가 됩니다.

피드백 스킬 (The Feedback Skill)

네 번째 스킬은 런북이 사용된 후 루프(loop)를 닫습니다. 이 스킬은 실행 로그를 가져와 실제로 일어난 일과 런북이 예상했던 일을 비교합니다.

모든 실제 실행은 런북에 대한 테스트입니다. 만약 특정 단계가 예상보다 오래 걸렸거나, 검증이 모호했거나, 혹은 사람이 공백을 메우기 위해 임기응변을 해야 했다면, 피드백 스킬이 이를 포착합니다. 출력 결과는 책상 앞에 앉아 누군가가 상상한 내용이 아니라, 실제로 일어난 사실에 근거하여 런북에 제안되는 일련의 개선 사항들입니다.

제안된 사항들은 다른 모든 변경 사항과 마찬가지로 검토 과정을 거칩니다. 사람이 이를 수용할지 여부를 결정하며, 이를 통해 런북은 사용될수록 퇴보하는 대신 사용될 때마다 개선됩니다. 이것이 바로 중요한 역전(inversion)입니다. 정적인(static) 런북은 시스템이 변경될 때마다 악화되지만, 피드백을 포착하는 실행 가능한(executable) 런북은 실행될 때마다 더 좋아집니다.

또한 피드백 스킬은 자주 사용되는 런북을 표시(flag)합니다. 왜냐하면 자주 사용되는 런북은 시스템에 대한 신호이기 때문입니다. 만약 특정 절차가 매주 실행된다면, 그 근본적인 문제는 해당 절차가 다시는 필요하지 않도록 수정할 가치가 있을 가능성이 높습니다. 런북 사용 데이터는 노고(toil)를 완전히 제거할 수 있는 자동화 기회들을 가리킵니다.

워크플로가 실제로 작동하는 방식

새로운 런북(runbook)은 보통 사고 발생 직후 기억이 생생할 때 작성된 거친 메모 형태로 시작됩니다. 구조화(structure) 기술은 이 메모를 전제 조건(preconditions), 실행 단계(actions), 그리고 검증(verifications)을 포함하는 구조화된 런북으로 변환합니다. 이후 사람이 이를 검토하며 구조화 과정에서 드러난 빈틈을 채웁니다.

그 시점부터 검증(validation) 기술이 정해진 일정에 따라 런북을 점검하고, 드리프트(drift, 설정 이탈)가 발생하면 이를 유지보수 작업으로 등록합니다. 덕분에 누군가 확인해야 한다는 사실을 기억하지 않아도 런북은 시스템과 일치된 상태를 유지합니다. 이전에는 다음 사고가 터질 때까지 숨어있던 드리프트가 이제는 일상적인 티켓(ticket)으로 나타납니다.

사고가 발생하면, 당직자(on-call)는 실행(execution) 기술을 통해 런북을 구동합니다. 이 기술은 전제 조건을 확인하고, 단계를 밟아 나가며, 결과를 확인하고, 모든 과정을 기록합니다. 사람은 판단을 내리고 상태를 변경하는 동작을 승인하며, 기술은 확인 작업을 처리합니다.

사고가 종료된 후, 피드백(feedback) 기술은 실제 실행 내용과 런북을 비교하여 개선 사항을 제안합니다. 런북은 조금씩 더 나아지며, 다음에 이를 실행할 사람은 이전보다 더 정확한 절차를 물려받게 됩니다. 수많은 사이클을 거치면서 런북 라이브러리는 사람들이 실제로 신뢰할 수 있는 절차 세트가 됩니다. 최근에 반복적으로 작동함이 증명되었기 때문입니다.

이 워크플로가 나의 실무에 가져온 변화

첫 번째 변화는 런북이 더 이상 부식되지 않는다는 점입니다. 검증 루프(validation loop)가 비용이 적게 들 때 드리프트를 잡아내기 때문에, 라이브러리에는 더 이상 사고 발생 시 터질 지뢰가 남아있지 않습니다. 이제 제가 런북을 열 때, 그것이 지난 사이클 내에 실제 시스템을 바탕으로 검증되었다는 것을 알기에 신뢰할 수 있습니다.

두 번째 변화는 사고를 대하는 느낌입니다. 스스로 전제 조건을 확인하는 구조화된 런북을 따라가는 것은, 위키 페이지를 읽으며 요행을 바라는 것보다 근본적으로 훨씬 차분한 경험입니다. 기술이 검증에 대한 불안감을 대신 짊어짐으로써, 사람은 4단계가 여전히 유효한지 고민하는 대신 실제 문제 자체에 집중할 수 있는 자유를 얻게 됩니다.

세 번째 변화는 런북 (runbook) 라이브러리가 운영상의 노고 (operational toil)를 보여주는 지도가 되었다는 점입니다. 실행 기술 (execution skill)에서 얻은 사용 데이터는 어떤 절차들이 빈번하게 실행되는지를 정확히 보여주며, 바로 그 절차들이 자동화를 통해 없애버릴 가치가 있는 것들입니다. 런북은 단순한 문서에 머물지 않고, 온콜 (on-call) 순번을 더 평온하게 만들어 줄 작업들의 우선순위 목록이 되었습니다.

네 번째 변화는 문화적입니다. 런북이 신뢰할 수 있고 사용함에 따라 개선된다면, 사람들은 더 많은 런북을 작성하게 됩니다. 왜냐하면 런북을 작성하는 것이 더 이상 시간이 지나면 부식될 뿐인, 보상 없는 문서화 작업이 아니기 때문입니다. 인센티브가 마침내 올바른 방향을 가리키게 되면서 라이브러리는 성장합니다.

제가 Claude Code를 사용하여 프로덕션 시스템을 운영하는 방식에 대한 전체적인 모습은, DEV.to의 전체 시리즈에서 확인할 수 있습니다. 해당 시리즈는 장애 대응 (incident response)부터 의존성 관리 (dependency management), 런북 자동화에 이르기까지 제가 의존하는 모든 워크플로우를 다룹니다.

FAQ

이것이 인간 온콜 (on-call) 담당자를 대체하나요?

아니요, 그럴 의도도 아닙니다. 이 기술은 검증과 지루한 작업들을 처리합니다. 인간은 판단을 내리고, 상태를 변경하는 모든 작업을 승인하며, 런북이 작성자가 예견하지 못한 상황에 직면했을 때 무엇을 할지 결정합니다. 목표는 인간이 압박감 속에서 서투르게 수행하는 장애 대응의 부분을 제거하는 것이지, 인간이 잘 수행하는 부분을 제거하는 것이 아닙니다.