Technote

AI 활용 실무

런북 초안은 AI가, 명령 검증은 사람이 합니다

생성된 런북은 그럴듯해 보이는 초안입니다. 폴더에 넣기 전에 모든 명령을 실험 환경에서 실행해야 합니다 — 검증되지 않은 런북은 없는 것보다 나쁩니다.

운영 문서가 없어서 곤란했던 경험은 대개 이렇습니다. 새벽에 알림이 오고, 예전에 같은 일을 겪었다는 것은 기억나는데 그때 무엇을 했는지는 기억나지 않습니다. 런북은 그 순간을 위한 문서입니다.

그래서 “런북을 쓰자” 는 결심은 자주 서지만 실제로 써지는 일은 드뭅니다. 급하지 않고, 지루하고, 빈 문서에서 시작하기 때문입니다. AI는 정확히 이 세 가지를 해결합니다 — 다만 초안까지만 해결합니다.

AI가 잘 만드는 것은 런북의 뼈대입니다

런북에는 대체로 정해진 형식이 있습니다. 이 문서를 언제 여는가, 무엇을 먼저 확인하는가, 어떤 조건일 때 어느 갈래로 가는가, 조치 후 무엇으로 복구를 확인하는가, 실패했을 때 어떻게 되돌리는가. 이 형식을 채우는 일은 AI가 빠르고 성실하게 합니다.

특히 잘하는 것이 빠뜨린 항목을 채워 넣는 것입니다. 사람이 쓴 런북에는 “당연한 것” 이 빠집니다 — 어느 서버에 접속하는지, 어떤 권한이 필요한지, 이 작업 전에 무엇을 백업해야 하는지. 당연한 것은 쓰는 사람에게만 당연하고, 새벽에 읽는 사람에게는 당연하지 않습니다. 형식을 알고 있는 AI는 이 칸을 빠뜨리지 않습니다.

또 하나, 흩어진 기록을 문서 형태로 정리하는 일도 잘합니다. 지난 장애의 채팅 로그와 메모를 (식별 정보를 지운 뒤) 주면서 “이 사건을 다음에 겪을 사람을 위한 절차서로 정리해 달라” 고 하면, 산문으로 흩어져 있던 것이 단계 목록이 되어 돌아옵니다.

그럴듯함이 정확히 위험한 이유

문제는 돌아온 문서가 읽기에 완벽하다는 점입니다. 명령에는 그럴듯한 플래그가 붙어 있고, 경로는 표준적으로 보이고, 순서는 합리적입니다. 그런데 그 명령들이 우리 서버에서 실제로 도는지는 아무도 확인하지 않았습니다.

실제로 자주 어긋나는 지점은 정해져 있습니다. 서비스 이름이 다릅니다 — 어떤 배포판은 php-fpm, 어떤 곳은 php8.4-fpm 입니다. 경로가 다릅니다 — 설정 파일과 로그 위치는 배포판과 설치 방식마다 갈립니다. 플래그가 다릅니다 — 같은 이름의 명령이 GNU 판과 BSD 판에서 다른 옵션을 받습니다. 컨테이너 환경이면 호스트에서 실행할지 컨테이너 안에서 실행할지가 통째로 달라집니다.

이 어긋남은 평소에는 무해합니다. 문제는 런북이 읽히는 시점입니다. 사이트가 죽어 있고, 판단력이 떨어져 있고, 문서가 시키는 대로 하려는 순간에 명령이 실패합니다. 그러면 두 가지가 함께 일어납니다 — 시간을 잃고, 그 문서 전체에 대한 신뢰를 잃습니다. 뒤쪽의 맞는 절차까지 버려집니다.

차이는 문장의 품질이 아니라 실행 여부다 — 그리고 그 차이는 장애 중에만 드러난다

검증되지 않은 런북은 없는 것보다 나쁩니다. 런북이 없으면 사람은 처음부터 조심스럽게 확인하며 움직입니다. 런북이 있으면 그것을 믿고 그대로 실행합니다. 신뢰받는 문서에 틀린 명령이 있는 상태가 가장 위험한 조합입니다.

검증 절차 — 초안과 문서 사이에 실행이 있습니다

규칙은 한 줄입니다. 실행해 보지 않은 명령은 런북에 들어가지 않습니다.

초안과 문서 사이에 실행 단계가 있다 — 이 칸을 건너뛴 문서는 초안일 뿐이다

스크래치 환경은 거창할 필요가 없습니다. 프로덕션과 같은 이미지로 올린 컨테이너 한 벌, 또는 스테이징 서버면 충분합니다. 중요한 것은 프로덕션이 아니라는 것과 망가뜨려도 되는 것입니다. 되돌리는 절차를 검증하려면 일부러 망가뜨려 봐야 하기 때문입니다.

거기서 명령을 하나씩 실행하면서 세 가지를 문서에 반영합니다. 첫째, 실제로 돈 형태로 명령을 고칩니다. 둘째, 성공했을 때의 출력을 그대로 붙여 넣습니다 — 읽는 사람이 “이 화면이 나오면 맞게 간 것” 을 알 수 있어야 합니다. 셋째, 전제 조건을 적습니다: 어느 계정으로, 어느 서버에서, 무엇이 먼저 되어 있어야 하는지.

# 검증 전 초안
systemctl restart php-fpm

# 검증 후 — 서비스명 · 확인 명령 · 되돌리기가 함께
sudo systemctl restart php8.4-fpm
sudo systemctl status php8.4-fpm --no-pager   # active (running) 확인
curl -s -o /dev/null -w "%{http_code}n" https://example.com/

런북에 반드시 들어가는 네 가지

초안을 받았을 때 이 네 칸이 비어 있으면 직접 채웁니다. AI가 자주 빠뜨리는 자리이기도 합니다.

언제 이 문서를 여는가. 문서 제목만으로는 부족합니다. 어떤 알림, 어떤 증상일 때 여는 문서인지 첫 줄에 적어야 급할 때 맞는 문서를 고를 수 있습니다.

되돌리는 방법. 조치가 상황을 악화시켰을 때 원상태로 가는 명령이 짝으로 있어야 합니다. 되돌릴 수 없는 조치라면 그 사실을 굵게 적어 둡니다 — 읽는 사람이 멈출 수 있게.

확인 방법. “재시작한다” 로 끝나는 절차는 절반입니다. 재시작이 실제로 효과가 있었는지 확인하는 명령이나 화면이 함께 있어야 다음 단계로 갈지 판단할 수 있습니다.

에스컬레이션. 이 문서로 해결되지 않으면 누구에게, 어떤 정보를 갖고 연락하는지. 이 칸이 없으면 사람은 문서 끝에서 혼자 계속 시도하게 됩니다.

마지막으로, 런북은 완성되는 문서가 아닙니다. 실제로 쓸 때마다 어긋난 부분이 드러나므로, 장애가 끝난 직후에 문서를 고치는 것까지가 대응 절차입니다. 그때가 기억이 가장 선명한 시점이고, 그때 안 고치면 다음에도 같은 자리에서 걸립니다.

AI를 운영 업무에 쓰는 경계에 대해서는 AI 활용 아카이브에 더 있고, 런북이 실제로 어떤 순서로 읽히는지는 장애 대응 런북 연재가 다룹니다. 절차와 문서까지 포함해 운영 환경을 한 번에 정비하고 싶다면 최적화 지원 사업을 참고하세요.

이 주제의 다른 글

노하우 목록으로

AI 활용 심화

운영 자동화에 AI를 넣는 경계 — 되돌릴 수 있는가

진단 · 요약 · 초안까지는 맡겨도 됩니다. 삭제 · 재시작 · 프로덕션 변경처럼 사람 확인 없이 되돌릴 수 없는 일에서 자동화는 이득보다 비용이 커집니다.

운영 · 관리자 5분 읽기

AI 활용 심화

AI가 만든 코드의 보안 검토 — 자주 나오는 취약 패턴 넷

생성된 코드는 대개 관용적으로 보입니다. 문제는 관용적으로 보이면서 이스케이프 · prepare · 권한 확인 · 경로 검증만 빠져 있는 경우가 반복된다는 점이고, 검토 순서를 정해 두면 짧게 끝납니다.

개발자 6분 읽기

₩270,000 · 신청하기