DevOps 문서 작업에서 인공지능(AI)에 인간미를 더하기: 런북(Runbook)을 더 만들기 쉽고 사용하기 편하게 만드는 법

새벽 3시에 나를 속인 런북(Runbook)

새벽 3시 14분, 멈춰버린 OpenStack Neutron 에이전트 때문에 페이저(Pager)가 울렸습니다. 저는 피곤에 지친 엔지니어가 하는 일상적인 행동을 했습니다. 바로 런북(Runbook)을 여는 것이었죠. 하지만 런북은 18개월 전에 이름이 바뀐 서비스를 재시작하라고 지시했고, 404 오류가 뜨는 Grafana 대시보드를 가리켰으며, 두 분기 전에 이미 이전해버린 네트워크 토폴로지(Network Topology)를 가정하고 있었습니다. 그 런북은 단순히 도움이 되지 않는 수준이 아니었습니다. 적극적으로 저를 속이고 있었고, 저는 그 내용을 믿느라 20분을 허비한 뒤에야 포기하고 소스 코드를 읽으러 갔습니다.

이것이 문서화(Documentation)의 진짜 문제입니다. 우리가 문서를 쓰지 않는 것이 아닙니다. 문서를 다 쓰는 순간부터 부패하기 시작한다는 것이 문제입니다. 문서를 최신 상태로 유지하는 비용이 너무 높기 때문에, 문서가 새벽 3시에 누군가를 배신하기 전까지는 아무도 그 비용을 지불하려 하지 않습니다. 팀이 신뢰하지 않는 런북은 런북이 없는 것보다 더 나쁩니다. 런북이 없으면 최소한 스스로 생각하게라도 만들기 때문입니다.

이 지점이 바로 플랫폼 조직(Platform Org)에서 AI가 마케팅 자료에서 제안하는 방식이 아닌, 실제로 제 역할을 다하는 지점입니다. AI가 여러분의 문서를 소유하게 되지는 않을 것입니다. 대신 AI는 해결된 인시던트(Incident), 쉘 히스토리(Shell History) 덩어리, 또는 배포 디프(Deploy Diff)를 구조화된 뼈대로 변환하는 지루한 초안 작성 작업을 수행할 것입니다. 이를 통해 인간 엔지니어는 명령어를 검증하고, 검증되지 않은 부분을 표시하며, 팀원들이 실제로 읽을 수 있도록 로봇 같은 말투를 다듬는 등 정말 중요한 부분에 귀중한 주의력을 집중할 수 있습니다. AI는 초안을 작성합니다. 여러분은 검증하고 승인합니다. 이 차이가 핵심입니다.

왜 AI를 "인간화(Humanizing)"하는 것이 슬로건이 아닌 업무인가

제가 말하는 "AI를 인간화한다"는 의미가 무엇인지 정확히 말씀드리겠습니다. 이 문구는 남용되는 경향이 있기 때문입니다. 저는 독자를 속이기 위해 AI가 사람처럼 들리게 만든다는 뜻이 아닙니다. 편집자이자 기록의 소유자로서 인간이 루프 안에(Human in the loop) 머물게 하고, 유능하지만 영혼 없는 기계의 초안을 동료가 신뢰할 수 있는 무언가로 바꾸는 매력적이지 않은 작업을 수행한다는 의미입니다.

AI가 작성한 문서에서 신뢰를 깨뜨리는 두 가지 요소가 있으며, 이 두 가지 모두 인간의 검토를 통해 수정 가능합니다:

1. 확신에 찬 검증되지 않은 주장 (Unverified claims stated with confidence). LLM은 여러분의 서버에 실제 유닛 이름이 무엇인지와 상관없이 기꺼이 systemctl restart neutron-l3-agent를 실행하라고 말할 것입니다. 모델은 그것을 알지 못합니다. 단지 패턴 매칭 (pattern-matching)을 할 뿐입니다. 따라서 인간의 첫 번째 임무는 안전한 환경에서 모든 명령어를 실행해 보고, 초안이 주장하는 대로 동작하는지 확인하는 것입니다.

2. 로봇 같은 말투 (The robotic tone). 기계가 작성한 초안은 마치 준수 사항을 전달하는 메모처럼 읽힙니다. 조심스럽고, 반복적이며, 이상할 정도로 격식을 차리고, "~라는 점을 유의하는 것이 중요합니다 (it is important to note that)"와 같은 표현으로 가득 차 있습니다. 엔지니어들은 이를 즉각적으로 알아차리고 읽기를 중단합니다. 어조와 간결함을 위해 편집하는 것은 허영심이 아닙니다. 사람들이 대충 훑어보고 지나치는 문서는 사용되지 않기 때문입니다. 그러한 정리 작업은 정당하고 가치 있는 업무이며, 바로 이것이 중요한 "인간미를 더하는 (humanizing)" 관점입니다.

이 두 가지 책임을 사람에게 확고히 맡긴다면, AI는 부채를 생성하는 존재가 아니라 승수 효과 (force multiplier)를 내는 도구가 됩니다. 저는 엔지니어가 새벽 3시에 실제로 신뢰하는 런북 (runbooks engineers actually trust at 3am)의 철학에 대해 더 많은 글을 썼지만, 요약하자면 다음과 같습니다: 신뢰는 검증을 통해 구축되며, 검증은 인간의 행위입니다.

트러블슈팅 가이드: 방금 해결한 장애 상황으로부터 초안 작성하기

트러블슈팅 가이드를 작성하기 가장 좋은 시기는 문제를 해결한 직후, 진단 경로가 머릿속에 여전히 생생할 때입니다. 가장 나쁜 시기는 (작성하지 않는) '결코 하지 않는 때'이며, 이는 기본 설정값과 같습니다. AI는 여러분의 터미널에 이미 원재료가 존재하기 때문에 그 간극을 메워줍니다.

제가 사용하는 프롬프트 패턴은 다음과 같습니다. 저는 실제 셸 히스토리 (shell history)와 장애 타임라인을 모델에 쏟아붓고, 매우 엄격하게 제약을 겁니다:

당신은 플랫폼 팀을 위한 내부 트러블슈팅 가이드 (troubleshooting guide)를 초안 작성하고 있습니다. 제가 제공하는 셸 히스토리 (shell history)와 대략적인 장애 타임라인 (incident timeline)을 바탕으로 다음 섹션들을 포함한 가이드를 생성하세요: 증상 (Symptoms), 사전 요구 사항/액세스 (Prerequisites/Access), 진단 단계 (Diagnosis Steps), 해결 방법 (Resolution), 롤백 (Rollback), 검증 (Verification). 반드시 제 히스토리에 있는 명령어를 정확하게 사용하세요. 존재하지 않는 플래그 (flag)나 경로 (path)를 만들어내지 마십시오. 제가 명시적으로 언급하지 않은 내용을 추론한 경우에는, 제가 확인할 수 있도록 해당 줄 앞에 [ASSUMPTION]을 붙이세요. 문장은 간결하게 작성하고, 불필요한 미사여구는 생략하세요.

그 [ASSUMPTION] 지침이 프롬프트에서 가장 중요한 단 한 줄입니다.

전문가 팁: 모델이 입력값에서 확인할 수 없는 모든 사항에 대해 명시적으로 태그를 달도록 항상 강제하세요. LLM (Large Language Model)의 실패 모드 (failure mode)는 자신 있게 빈틈을 채워 넣는 것입니다. 모델이 스스로의 추측을 표시하게 만들면, 보이지 않는 위험을 눈에 보이는 체크리스트로 전환할 수 있습니다. 모든 [ASSUMPTION] 태그는 문서가 배포되기 전에 당신이 직접 확인해야 할 항목이 됩니다. 이 태그들은 편집 과정에서 삭제되지만, 검증 단계 (verification pass)를 이끌어내는 역할을 합니다.

해당 프롬프트에 history | grep neutron 명령어 결과와 세 줄짜리 타임라인을 입력하면 다음과 같은 결과가 나옵니다. 이는 완성된 문서가 아니라, 진정으로 훌륭한 시작점 역할을 합니다:

진단 단계 (Diagnosis Steps)

1. 에이전트가 단순히 깜빡거리는 것이 아니라 실제로 다운되었는지 확인: openstack network agent list --agent-type l3 --host compute-04
2. [ASSUMPTION] L3 에이전트 유닛은 neutron-l3-agent입니다. 상태 확인: systemctl status neutron-l3-agent
3. RPC 타임아웃 (timeout) 시그니처를 찾기 위해 에이전트 로그를 추적: journalctl -u neutron-l3-agent --since "10 min ago" | grep -i timeout

해결 방법 (Resolution)

에이전트를 재시작하고 서버에 다시 등록되는지 확인:
systemctl restart neutron-l3-agent && sleep 5 && openstack network agent list --host compute-04

롤백 (Rollback)

[ASSUMPTION] 재시작에 따른 롤백은 필요하지 않습니다. 만약 에이전트가 재등록에 실패하면, 심층 디버깅 (debugging)을 수행하기 전에 라우터를 대기 노드 (standby node)로 페일오버 (failover) 하십시오.

AI가 잘 수행한 점을 주목하십시오. AI는 제 히스토리의 혼란스러운 내용을 깔끔한 진단 흐름 (diagnostic flow)으로 구조화했고, 제가 실제로 실행했던 진짜 명령어들을 추출해냈습니다. AI가 지적한 점도 주목하십시오. AI는 제 유닛 (unit) 이름을 알지 못했기에 태그를 달았습니다. 제가 확인했을 때, 해당 유닛은 문제가 발생한 호스트의 실제 devstack@q-l3.service였습니다. 만약 초안이 이를 확신에 차서 기술했다면 저는 절대 잡아내지 못했을 것입니다. 그 하나의 가정 태그가 도움이 되는 가이드와 거짓을 말하는 가이드를 가르는 차이입니다. 저는 AI를 사용하여 해결된 인시던트로부터 런북 초안 작성하기에 관한 글에서 이 워크플로우에 대해 더 자세히 다룹니다.

사후 분석 (Postmortems): AI는 타임라인을 처리하고, 당신은 비난 없는 문화를 소유합니다

사후 분석 (Postmortems)은 AI의 초안 작성 능력과 판단력의 약점이 모두 극명하게 드러나는 영역입니다. Slack 스레드, 알림 타임스탬프 (alert timestamps), 배포 로그 (deploy logs)로부터 일관된 타임라인을 조립하고 영향 요약 (impact summary) 초안을 작성하는 것과 같은 기계적인 부분은, 사후 분석을 몇 주씩 지연시키는 바로 그 지루한 작업들입니다. AI는 이런 일을 아주 쉽게 처리합니다.

하지만 비난 없는 (blameless) 부분은 단순히 토글로 켜고 끌 수 있는 톤 설정이 아닙니다. 그것은 인간이 책임져야 하는 편집적이고 문화적인 입장입니다. 저는 모델에 가공되지 않은 타임라인을 제공하며 다음과 같이 명시적으로 지시합니다:

비난 없는 (blameless) 사후 분석 초안을 작성하십시오. 시스템이 무엇을 했는지와 어떤 신호 (signals)를 사용할 수 있었는지를 설명하되, 사람이 무엇을 "실패"했는지는 절대 언급하지 마십시오. 모든 인간의 행동을 당시 가용했던 정보에 기반한 합리적인 결정으로 프레임화하십시오. 섹션: 요약 (Summary), 영향 (Impact), 타임라인 (Timeline), 기여 요인 (Contributing Factors), 잘된 점 (What Went Well), 조치 사항 (Action Items). 입력값으로부터 뒷받침할 수 없는 모든 인과 관계 주장에는 [UNVERIFIED]를 표시하십시오.

모델은 중립적인 언어를 사용하는 데 있어 80%까지 도움을 줄 것입니다. 나머지 20%, 즉 온콜 (on-call) 엔지니어가 당연히 알고 있었어야 했다는 뉘앙스를 미묘하게 암시하는 문장을 잡아내는 것은 매번 인간의 몫입니다. 비난 없는 글쓰기 (Blameless writing)는 하나의 기술이며, 편집 단계가 바로 그 기술을 적용하는 지점입니다. 사람들이 실제로 읽는 사후 분석 (postmortem)과 파일에 저장된 채 잊혀지는 사후 분석을 구분하는 기준을 아직 내재화하지 못했다면, 사람들이 실제로 읽는 비난 없는 사후 분석에 대한 이 분석 내용을 살펴볼 가치가 있습니다.

전문가 팁: AI가 작성한 조치 사항 (Action Items)을 감독 없이 그대로 두지 마십시오. 모델은 책임감 있게 들리면서도 아무도 책임지게 만들지 않는, 그럴듯해 보이는 해결책("모니터링 추가", "문서화 개선" 등)을 생성하는 것을 좋아합니다. 실제 조치 사항에는 담당자, 마감일, 그리고 검증 가능한 완료 정의 (definition of done)가 있어야 합니다. 그것은 리더십의 결정이지, 텍스트 생성 작업이 아닙. 초안이 생성한 모든 모호한 항목을 삭제하고, 사람이 실제로 수행하기로 동의한 내용으로 교체하십시오.

하지만 그 보상은 확실합니다. 타임라인과 영향 요약 (impact summary)을 작성하는 데 하루의 대부분을 쓰는 대신 10분 만에 초안을 작성할 수 있게 되면, 모두가 다음 장애를 처리하러 떠나버려 방치되는 대신 세부 사항이 생생할 때 실제로 사후 분석이 작성됩니다.

SOP: 지식이 문밖으로 나가기 전에 암묵지 (Tribal Knowledge)를 기록하라

표준 운영 절차 (SOP, Standard operating procedures)는 시니어 엔지니어 한 명의 머릿속에만 온전히 존재할 가능성이 가장 높은 문서들입니다. 클러스터 인증서를 어떻게 교체하는지, 유지보수를 위해 노드를 어떻게 드레인 (drain) 하는지, 상태 (state)를 고아로 만들지 않고 새로운 Terraform 워크스페이스를 생성하는 정확한 절차 등이 이에 해당합니다. 그러한 지식은 버스 지수 (bus-factor) 리스크이며, 이를 기록하는 일은 항상 더 시급한 업무에 밀려왔습니다.

AI는 활성화 에너지 (activation energy)를 충분히 낮추어, 더 이상 (기록 작업을) 포기하지 않게 만듭니다. 저는 대략적인 텍스트 파일에 절차를 소리 내어 설명하며 기록합니다. 불완전한 문장, 명령어 조각, 제가 기억하는 주의 사항 (gotchas) 등을 적으면, 모델이 이 난잡한 내용을 번호가 매겨진 단계, 전제 조건 (prerequisites), 그리고 명확한 "...하면 완료되었습니다" 식의 검증 기준 (verification criteria)을 포함한 구조화된 표준 운영 절차 (SOP)로 변환해 줍니다.

여기서 주의해야 할 점은 SOP가 단순히 명령어뿐만 아니라 _정책 (policy)_을 인코딩한다는 것입니다. AI는 당신의 단계를 아름답게 포맷팅할 수는 있지만, 당신의 변경 관리 (change-management) 규칙을 알지 못하기 때문에 이를 위반하는 결과물을 만들어낼 수도 있습니다. 따라서 SOP에 대한 인간의 검토는 두 가지 계층을 확인하는 과정입니다. 명령어가 정확한가, 그리고 이 절차가 우리가 실제로 운영하기로 되어 있는 방식에 부합하는가? 모델은 당신의 조직도나 변경 심의 위원회 (change board)를 볼 수 없지만, 당신은 볼 수 있습니다.

저는 매번 뼈대를 다시 쓰지 않도록 이러한 초안 작성용 프롬프트 (drafting prompts)를 작은 라이브러리로 관리합니다. 효과적인 프롬프트들을 수집하고 재사용하는 것이 생산성 향상의 절반을 차지하는데, 초안의 품질은 프롬프트의 품질에 따라 결정되기 때문입니다.

배포 및 릴리스 문서: Diff에서 직접 초안 작성하기

배포 문서에는 독특한 장점이 있습니다. 바로 신뢰할 수 있는 원천 (source of truth)이 구조화되어 있고 기계가 읽을 수 있는 형태라는 점입니다. PR diff, Terraform plan, Helm values 변경 사항 등은 AI가 직접 읽을 수 있는 정밀한 산출물 (artifacts)이며, 이는 초안이 기억이 아닌 사실로부터 시작됨을 의미합니다.

릴리스 노트와 배포 런북 (runbook)을 위한 저의 워크플로우는 다음과 같습니다. diff 또는 terraform plan 출력값을 모델에 전달하고, 사전 점검 (pre-flight checks), 적용 절차 (apply procedure), 영향 범위 (blast radius), 롤백 (rollback), 그리고 배포 후 검증 (post-deploy verification)을 포함하는 배포 가이드를 요청합니다. 입력값이 구체적이기 때문에 환각 (hallucination) 발생률이 급격히 떨어집니다. 모델은 무엇이 변했는지 추측하는 것이 아니라, 그것을 읽고 있는 것이기 때문입니다.

사전 점검 (Pre-flight Checks)

• 대상 워크스페이스(workspace) 확인: terraform workspace show 결과가 prod-us-east로 반환됨.
• [ASSUMPTION] 이 계획은 2개의 노드를 추가하고 ASG(Auto Scaling Group) 시작 템플릿(launch template)을 수정합니다; 삭제(destroy)되는 리소스는 없습니다. 적용(apply)하기 전에 terraform plan을 다시 실행하여 삭제될 리소스가 0개인지 확인하십시오.

롤백 (Rollback)

시작 템플릿 변경 사항은 버전별로 관리됩니다. 롤백하려면 ASG가 이전 템플릿 버전을 가리키도록 설정하고 인스턴스 새로고침(instance refresh)을 트리거하십시오. terraform destroy를 실행하지 마십시오.

이 단계에서도 인간은 영향 범위(blast radius)에 대한 주장을 검증합니다. "삭제되는 리소스 없음"과 같은 문구는 프로바이더(provider) 업그레이드로 인해 특정 필드가 조용히 강제 재생성(force-new)되기 전까지는 사실이지만, 이를 잘못 읽는 순간 일상적인 배포는 장애(outage)로 변합니다. AI는 구조화되고 대체로 정확한 초안을 빠르게 제공하며, 여러분은 위험한 부분을 직접 눈으로 확인합니다. 이를 실제 파이프라인에 연결하는 방법에 대한 더 자세한 내용은 저의 2026년 AI를 활용한 런북 자동화 가이드에서 도구 사용법을 처음부터 끝까지 다룹니다.

편집 단계가 신뢰를 구축하는 지점입니다

저는 사람들이 흔히 건너뛰는 부분에 대해 이야기하며 마무리하고 싶습니다. 왜냐하면 그 부분이 실제로 여러분의 문서가 사용될지 여부를 결정하기 때문입니다. 명령어가 검증되고 가설(assumptions)이 해결되고 나면, 여전히 여러분의 손에는 기계가 만든 듯한 문서가 남아 있습니다. 유능하고 구조적이지만, 약간은 생동감이 없는 문서 말입니다. 지나치게 말을 아끼고, 뻔한 내용을 반복하며, 엔지니어의 눈을 흐릿하게 만드는 평이하고 지나치게 격식적인 말투를 띠고 있습니다.