💡 원래 devtocash.com에 게시되었습니다 — 이 가이드의 최신 정보가 유지되는 곳입니다. 저는 그곳에서 매주 실무 중심의 DevOps/SRE 심층 분석 글을 작성합니다.

당신의 런북은 이미 에이전트 지침입니다 — 단지 안전하지 않을 뿐입니다

AI 런북 자동화는 "런북을 프롬프트에 붙여넣고 모델이 명령어를 실행하게 두는 것"이 아닙니다. 이것은 번역 작업입니다. 인간의 런북에 있는 각 단계를 **타입화된 도구 (typed tool)**로 전환하는 것입니다. 즉, 에이전트가 자유롭게 호출할 수 있는 진단(diagnostics), 승인 게이트(approval gate) 뒤에 잠겨 있는 복구(remediations), 그리고 에이전트가 증거 없이 승리를 선언할 수 없도록 모든 쓰기 작업에 결합된 검증 체크(verification check)로 만드는 과정입니다. 런북은 새벽 3시에 졸린 인간이 따르는 산문(prose)이 아니라, 동일한 단계와 동일한 순서를 가지며 필사 오류가 훨씬 적은, 에이전트가 오케스트레이션하는 제한된 도구 표면(bounded tool surface)이 됩니다.

이 포스트에서는 실제 런북을 사용하여 엔드 투 엔드(end to end) 전환 과정을 살펴봅니다. 런북을 동사로 해부하고, 이를 매니페스트(manifest)로 인코딩하며, 단계를 도구로 구현하고, 이 둘이 서로 어긋나지 않게 유지하는 방법을 다룹니다. 만약 당신이 이미 좋은 장애 대응 런북 템플릿 (incident runbook template) 형태로 런북을 관리하고 있다면, 대부분의 작업은 기계적인 작업이 될 것입니다.

"런북을 프롬프트에 붙여넣기"가 실패하는 이유

나태한 방식 — 쉘 도구(shell tool)와 함께 runbook.md를 에이전트의 컨텍스트에 쏟아붓는 방식 — 은 네 가지 반복적인 방식으로 실패합니다:

1. 산문은 모호합니다. "영향받은 파드(pods)를 재시작하라"는 어떤 네임스페이스(namespace)인지, 배포(deployment)를 재시작해야 하는지 아니면 파드를 하나씩 삭제해야 하는지, 또는 '영향받았다'가 무엇을 의미하는지 말해주지 않습니다. 인간은 판단으로 빈틈을 채우지만, 모델은 통계적으로 가장 가능성이 높은 kubectl 호출로 채워 넣고, 이것이 잘못된 네임스페이스에서 롤아웃 재시작(rollout restart)을 하게 만드는 방식입니다.
2. 런북이 구식이 됩니다. check dashboards/db-pool이라고 되어 있는 단계는 Grafana 마이그레이션 이전에 작성되었습니다. 인간은 404 오류를 감지하고 적응하지만, 에이전트는

이 패턴은 일반화됩니다. 거의 모든 런북(runbook)은 진단 깔때기(diagnostic funnel), 한두 개의 쓰기 작업(write actions), 그리고 검증(verification)으로 구성됩니다. 진단은 자유롭게 호출 가능한 읽기 전용 도구(read-only tools)가 됩니다. 이는 읽기 전용 kubectl MCP 서버와 동일한 좁은 문 설계(narrow-door design)입니다. 조치(Remediations)는 인간 참여형 승인 게이트(human-in-the-loop approval gate)를 통해 라우팅되는 제안이 됩니다. 검증은 에이전트가 건너뛸 수 없는 코드가 됩니다.

단계 2: 산문이 아닌 매니페스트(manifest)로 인코딩하기

도구 코드를 작성하기 전에, 런북을 기계가 확인할 수 있는 매니페스트(manifest)로 고정하십시오. 이것이 인간이 PR(Pull Request)에서 검토하고 CI(지속적 통합)가 검증하는 산출물(artifact)입니다.

# runbooks/checkout-pool-exhaustion.yaml
id: checkout-pool-exhaustion
trigger:
...

여기서 두 가지 속성이 중요합니다. 모든 tool: 참조는 실제로 존재하는 도구의 이름을 지정해야 합니다(아래 CI에서 이를 강제할 것입니다). 그리고 approval: required는 모델에 대한 정중한 요청이 아니라 _하네스(harness)_가 강제하는 데이터입니다. 실행기(executor)는 LLM이 무엇을 요청하든 승인되지 않은 쓰기 작업을 거부하며, 이는 에이전트 하네스 자체를 인프라로 취급한다는 핵심 아이디어입니다.

단계 3: 단계들을 타입이 지정된 도구(typed tools)로 구현하기

진단은 기존의 관측성 API(observability APIs)를 얇고 경계가 명확한 래퍼(wrapper)로 감싼 것입니다. 이 시리즈의 나머지 부분과 관례를 맞추기 위해 FastMCP를 사용하면 다음과 같습니다.

# runbook_tools.py — checkout-pool-exhaustion을 지원하는 도구들
import os, re, httpx
from fastmcp import FastMCP
...

조치(Remediation) 도구는 성격이 다릅니다. 이들은 아무것도 실행하지 않습니다. 대신 **구조화된 작업 제안(structured action proposal)**을 방출합니다. 이는 타입이 지정된 매개변수를 가진, 알려진 가역적 동사(reversible verbs)의 열거형(enum)입니다. 승인 게이트는 이를 인간에게 보여주고, 서명된 '예'가 확인되면 실제 자격 증명(credentials)을 보유한 별도의 실행기에게 전달합니다.

@mcp.tool()
def propose_rollout_restart(reason: str) -> dict:
    """rollout restart를 통해 checkout pool을 재순환(recycling)할 것을 제안합니다.
...

reason 체크는 단순한 눈속임처럼 보일 수 있지만 제 역할을 다합니다. 이는 모델이 쓰기(write) 작업을 제안하기 전에 실제로 진단(diagnostics)을 수행하도록 강제하며, 해당 문자열은 Slack 승인 메시지에 그대로 전달되므로 승인자는 정확한 변경 사항 옆에서 에이전트의 근거를 확인할 수 있습니다.

검증(Verification)은 팀들이 자주 잊어버리는 단계이지만, 자동화를 신뢰할 수 있게 만드는 핵심 단계입니다. 모델이 아닌 일반 코드인 오케스트레이터(orchestrator)는 승인된 작업 후에 매니페스트(manifest)의 verify 블록을 실행하며, 검증을 통과하거나 타임아웃이 발생하여 인간에게 에스컬레이션(escalation)되기 전까지는 인시던트(incident)를 종료하는 것을 거부합니다. 에이전트는 결코 "이제 고쳐졌을 것입니다"라고 멋대로 말할 수 없습니다.

4단계: 모델이 오케스트레이션하게 하되, 즉흥적으로 행동하게 하지 마세요

에이전트의 시스템 프롬프트(system prompt)는 매니페스트의 범위 내로 제한됩니다:

당신은 runbook checkout-pool-exhaustion을 실행하고 있습니다. 제공된 도구만 사용하세요. 단계 순서를 따르십시오. `when` 조건이 거짓(false)인 경우에만 단계를 건너뛰십시오. 만약 진단 결과가 나열된 어떤 복구(remediation) 작업도 지원하지 않거나, 게이트(gate)...

마지막 문장이 중요한 이유는 런북 진단 결과가 로그 텍스트와 메트릭 레이블(metric labels) — 즉, 신뢰할 수 없는 입력(untrusted input)을 반환하기 때문입니다. 그리고 "에스컬레이션이 곧 성공이다"라는 표현이 정직한 프레임워크입니다. 런북은 어제의 인시던트를 인코딩한 것이므로, 새로운 장애가 발생했을 때 올바른 동작은 창의적인 수술을 하는 것이 아니라, 인간에게 명확한 읽기 전용 조사 요약(read-only investigation summary)을 전달하는 것입니다. 그 인계 시점에 에이전트에게 무엇을 제공하느냐가 에이전트 자체의 숙련도를 결정합니다 — on-call 에이전트를 위한 컨텍스트 엔지니어링(context engineering for on-call agents)을 참조하세요.

런북과 도구 사이의 드리프트(drift) 방지하기

오래된 런북은 운영(ops) 분야에서 두 번째로 오래된 문제입니다. 일단 런북이 매니페스트가 되면, 드리프트(drift)는 새벽 3시의 갑작스러운 사고가 아니라 CI 실패로 나타나게 됩니다:

# test_runbook_integrity.py
import yaml, glob
from runbook_tools import mcp
...

세 가지 단언(assertions)을 통해, 이제 그 누구도 승인 플래그(approval flag) 없이 복구 단계(remediation step)를 추가하거나, 삭제된 도구를 참조하거나, 검증(verification)이 없는 런북을 배포할 수 없습니다. 도구를 배포하는 것과 동일한 파이프라인에서 이를 실행하세요.

런북을 작성하게 만든 실제 장애(incidents)로 평가하기

모든 런북은 무언가 고장 났기 때문에 존재하며, 이는 곧 재현 가능한 테스트 케이스(test cases)를 무료로 소유하고 있음을 의미합니다. 에이전트가 실제 장애(live incident)에 개입하기 전에, 원래 장애의 알람(alerts)과 메트릭 스냅샷(metric snapshots)을 에이전트에 대해 재현해 보세요. 에이전트가 깔때기(funnel)를 순서대로 따라가는지, 에러율이 임계값(threshold) 미만일 때 게이트에서 멈추는지, 최근 배포(deploy)가 있을 때만 롤백(rollback)을 제안하는지, 그리고 런북이 다루지 않는 실패 상황을 입력했을 때 깔끔하게 에스컬레이션(escalate)하는지 확인하십시오. 최종 답변뿐만 아니라 도구 호출 시퀀스(tool-call sequence)를 점수화해야 합니다. DevOps AI 에이전트를 위한 평가(evals for DevOps AI agents)에서 제시하는 방법론이 직접적으로 적용되며, 재현된 로그에 의도적으로 심어놓은 인젝션 문자열(injection string) 또한 평가 스위트(suite)에 포함되어야 합니다.

솔직히, 이를 통해 얻는 이점

이런 방식으로 런북 하나를 변환하는 데는 오후 시간 정도면 충분합니다. 이를 통해 누군가 노트북을 열 때가 아니라 알람이 발생한 후 첫 30초 이내에 실행되는 진단(diagnostics), 오타가 방지되고 승인 게이트가 적용된 복구(remediations), 그리고 건너뛸 수 없는 검증(verification)을 얻게 됩니다. 하지만 이것이 아무도 기록하지 않은 장애에 대한 커버리지까지 보장해주지는 않습니다. 에이전트는 당신의 런북 코퍼스(runbook corpus)만큼만 현명하며, 그렇지 않은 척하는 것이야말로 단 한 번의 잘못된 금요일(bad Friday) 이후 당신의 회사에서 자율 복구(autonomous remediation)가 금지되는 경로입니다. 가장 빈도가 높은 런북부터 시작하여, 모든 작성 과정을 게이트 뒤에서 관리하고, 지루하고 반복적인 장애들은 기계가 처리하도록 두십시오.

📌 이 가이드의 최신 버전 — 그리고 DevOps, SRE, Kubernetes, 관측성(observability) 및 클라우드 비용(cloud-cost) 가이드 전체 라이브러리 — 를 devtocash.com에서 확인하세요.