루프 엔지니어링 (Loop Engineering)은 최근 모두가 입에 올리고 있는 문구입니다. 이는 프롬프트 (Prompt), 컨텍스트 (Context), 하네스 (Harness)의 다음 단계에 위치하며, 에이전트 조정 (agent coordination)을 한 단계 더 진전시킵니다.

Google의 Addy Osmani는 얼마 전 이 개념 전체를 공식화한 긴 글을 게시했습니다. 읽어볼 가치가 있습니다. 하지만 그보다 앞서, OpenClaw의 설립자인 Peter Steinberger는 이를 더욱 정확하게 꿰뚫는 말을 했습니다.

"더 이상 코딩 에이전트에게 프롬프트를 입력해서는 안 됩니다. 에이전트에게 프롬프트를 입력하는 루프 (loops)를 설계해야 합니다."

그의 말은, 당신이 매 턴마다 에이전트를 수동으로 운전하는 사람이 되는 것을 멈춰야 한다는 뜻입니다. 대신 시스템을 구축해야 합니다. 시스템이 실행되고, 검사하고, 수정하고, 기록합니다. 당신은 렌치를 돌리는 사람에서 조립 라인을 설계하는 사람으로 변모하는 것입니다.

한 가지 명심해야 할 점은, 운영 (operations)에 있어서 안전이 전부라는 것입니다. 가드레일 (guardrails)과 인간 참여 (human-in-the-loop)가 없다면, 자율적인 루프는 실제적인 피해를 입힐 수 있습니다. 저는 "완전 자동화된" 운영 루프를 선호하지 않으며, 그 이유를 보여드리겠습니다.

이 글에서는 호스트 상태 확인 (host health check) 예시를 사용하여 안전한 운영 루프를 구축하는 과정을 살펴봅니다. 우리가 매일 수행하는 대부분의 일상적인 운영 업무는 이런 방식으로 패키징될 수 있습니다.

루프 엔지니어링 (Loop Engineering)의 분해

루프 엔지니어링을 분해하면 여섯 가지 조각이 나옵니다.

조각	역할
자동화 (Automations)	예약된 또는 조건부 트리거. 루프가 스스로 실행됩니다.
...

Claude Code와 Codex는 이제 이러한 기능의 대부분을 내장하여 출시합니다. 처음부터 직접 만들 필요는 없습니다.

하지만 도구들이 당신을 대신해 해줄 수 없는 조각이 하나 있습니다.

루프의 구조와 제약 조건 (constraints)을 기록하는 것.

물론, 일회성 명령(Claude Code의 /goal과 같은)을 입력할 수는 있습니다. 하지만 거기에는 두 가지 문제가 있습니다.

1. 프롬프트는 빈틈을 남깁니다 (Prompts leave gaps). 라운드당 단계는 몇 번인가요? 완료되었다는 것을 어떻게 알 수 있나요? 단계 간의 핸드오프(hand off)는 어떻게 이루어지나요? 경로를 벗어나지 않게 막는 장치는 무엇인가요? 아무도 당신에게 이러한 것들을 생각하도록 강제하지 않습니다. 그냥 건너뛸 수도 있죠. agent-runbook을 사용하면, 프레임워크가 이 모든 질문에 답하도록 강제합니다. 하나라도 건너뛰면 컴파일러가 당신에게 경고를 보냅니다.

2. 재사용이 불가능합니다 (Not reusable). 한 번 실행하면 끝입니다. 다음 클러스터, 다음 작업자가 오면 처음부터 다시 시작해야 합니다.

당신에게는 루프의 단계, 종료 조건, 그리고 가드레일(guardrails)을 하나의 파일로 변환해 줄 무언가가 필요합니다. 입력하고 잊어버리는 프롬프트가 아니라, 리포지토리(repo)에 커밋하는 계약(contract) 말입니다. 다음 실행, 다음 작업자도 동일한 파일로 동일한 결과를 얻게 됩니다.

agent-runbook: 계약으로서의 루프 작성하기 (Writing Loops as Contracts)

agent-runbook은 GitHub의 오픈 소스 프로젝트입니다: github.com/KnoxOps/agent-runbook. 이 프로젝트의 철학 전체는 한 문장으로 요약됩니다: 프롬프트와 요행이 아니라, 계약으로 에이전트(agent)를 제약하라.

몇 가지 핵심적인 설계 결정 사항이 있습니다.

계약 우선 (Contract-first). 당신은 루프의 단계, 출력(outputs), 의존성(dependencies), 그리고 가드레일(guardrails)을 선언하는 YAML 파일을 작성합니다.

외부 메모리 (External memory). 에이전트의 컨텍스트 (context)는 매 턴마다 초기화됩니다. 에이전트가 지난 라운드에 일어난 일을 기억할 것이라고 기대하는 것은 막연한 기대에 불과합니다. 루프 (loop)는 매 라운드의 출력 (output), 반복 이력 (iteration history), 그리고 전반적인 진행 상황을 파일에 저장합니다. 상태 파일 (status file)은 어떤 단계가 완료되었는지 추적합니다. 반복 로그 (iteration log)는 매 라운드마다 무엇이 수정되었는지 기록합니다. 에이전트는 잊어버리지만, 파일은 잊지 않습니다.

필수 가드레일 (Mandatory guardrails). 프롬프트 (prompt)에 "설정을 건드리지 마세요"라고 쓰는 것은 요청일 뿐입니다. 에이전트는 이를 무시할 수 있습니다. 에이전트 실행 가이드북 (agent-runbook) 가드레일은 강제되는 체크 (checks)입니다. 매 라운드가 끝난 후, 독립적인 검토를 통해 에이전트가 권한을 넘어섰는지 확인합니다. 수정해서는 안 될 파일을 수정했나요? 계획 외의 명령어를 실행했나요? 그렇다면 해당 라운드는 완료된 것으로 간주하지 않습니다.

내장 브레이크 (Built-in brakes). 모든 루프는 무엇이 "완료 (done)" 상태인지를 선언해야 하며, 엄격한 반복 횟수 제한 (iteration cap)을 포함해야 합니다. 루프는 멈춰야 합니다. 영원히 실행되어서는 안 됩니다.

단계 간 통신을 위한 컨텍스트 대신 파일 사용 (Files over context for step communication). 에이전트가 이전 단계에서 무엇을 말했는지 기억할 것이라고 기대하지 마세요. 모든 단계의 출력 (output)은 JSON 스키마 (JSON Schema)를 따릅니다. 다음 단계는 읽는 즉시 이를 검증합니다. 필드 불일치 (field mismatch)가 발생하면 즉시 실패 처리되며, 조용한 데이터 손상 (silent data corruption)은 발생하지 않습니다.

실습: 호스트 상태 점검 루프 (A Host Health Check Loop)

실제 시나리오입니다. 당신은 프로덕션 서버 플릿 (fleet)을 보유하고 있습니다. 디스크, 메모리, 부하 (load), 주요 서비스 등 정기적인 상태 점검 (health checks)이 필요합니다. 문제가 발생했을 때, 에이전트가 자동으로 수정하게 내버려 둘 수는 없습니다. 프로덕션 쓰기 작업 (write operations)에는 인간의 승인이 필요하기 때문입니다.

이 루프의 각 라운드는 다섯 단계로 실행됩니다:

1. 점검 결과에서 가장 치명적인 문제를 선택합니다.
2. SSH로 접속하여 근본 원인 (root cause)을 조사하고 수정 계획 초안을 작성합니다.
3. 계획을 제시하고 승인을 기다립니다.
4. 승인된 수정을 실행합니다.
5. 문제를 확인하기 위해 재점검합니다.

에이전트 실행 가이드북 (Agent Runbook) YAML은 다음과 같은 모습입니다:

name: host-health-loop
description: Ansible 상태 점검을 통한 문제 발견 → 하나씩 수정 (쓰기 작업은 인간의 승인 필요) → 재점검 → 모든 상태가 정상일 때까지 반복 → HTML 보고서 생성

...

YAML을 작성하고, 한 번의 명령으로 컴파일하세요:

python3 -m agent_runbook generate runbook.yaml -o output/

이를 Claude Code나 Codex에 넣으면 바로 실행됩니다.

생성된 SKILL.md는 약 250줄에 달합니다. 다음은 주요 섹션을 요약한 버전입니다 (전체 버전은 여기에서 확인하세요):

---
name: host-health-loop
description: Ansible 상태 점검 (health check) → 수정 (fix) → 재점검 (re-inspect) → 모든 상태가 정상일 때까지 반복 (repeat until all healthy) → HTML 보고서 생성 (HTML report)
...

여기서 핵심은 이렇습니다. 방금 읽으신 그 YAML은 말 그대로 Loop Engineering (루프 엔지니어링)의 여섯 가지 요소를 모두 선언하고 있습니다. 당신이 선언하면, Claude Code나 Codex가 이를 실행합니다.

YAML에서 선언하는 내용
각 단계를 누가 실행할지, 무엇을 할지, 어떤 순서로 할지

Claude Code / Codex가 자동으로 수행하는 내용
선언된 순서대로 에이전트(agents)를 생성하며, 각 에이전트는 격리된 워크트리 (worktree)에서 실행되고 작업 후 정리됨

5라운드, 모두 정상 (All Green)

이 예제는 세 대의 베어메탈 (bare-metal) 머신에서 테스트되었습니다. 초기 점검 결과, 세 대의 호스트 모두에 걸쳐 여러 문제가 발견되었습니다.

첫 번째 라운드는 eval-bare-vm-3에서 진행되었습니다. 루트 디스크 (Root disk) 사용률이 93%였으며, 남은 용량은 1.4G뿐이었습니다. 에이전트가 SSH로 접속하여 원인을 찾아냈습니다: 5.4G 크기의 Docker JSON 로그, /tmp 디렉토리의 4.5G 임시 파일, 215M의 애플리케이션 로그, 약 800M의 컨테이너 캐시 (container cache)였습니다. 승인 후, 에이전트는 Docker 로그를 잘라내고 (truncate), /tmp를 비우고, apt 캐시를 정리하며, journald를 50M로 진공 청소 (vacuum) 하여 정리했습니다. 약 10G의 공간을 확보했습니다. 디스크 사용률은 93%에서 38%로 떨어졌습니다.

다음 몇 번의 라운드에서는 세 대의 머신 전체에서 nginx와 docker가 다운된 상태였습니다. 누군가 수동으로 서비스를 중지한 후 다시 실행하지 않은 상태였습니다. 각 라운드는 다음과 같이 진행되었습니다: 조사 (investigate) → 계획 (plan) → 승인 (approve) → 실행 (execute) → 검증 (verify). 총 5라운드 동안 모든 결과는 정상(green)이었으며, 루프는 스스로 종료되었습니다.

다크 모드 대시보드 HTML 보고서가 생성되었습니다.

모든 쓰기 작업 (write operation)이 승인 과정을 거쳤다는 점에 주목하십시오. 자동 실행은 없었습니다. 사람이 모든 명령어가 실행되기 전에 확인했습니다. 운영 환경 (production)에서는 이 과정을 생략해서는 안 됩니다.

좋은 Ops 루프를 설계하는 방법

적절한 작업을 선택하세요. 좋은 Ops 루프는 검사 결과, 메트릭 (metrics), 상태 확인 엔드포인트 (health check endpoints)와 같은 객관적인 피드백 신호를 가집니다. 각 라운드는 이전 라운드를 기반으로 구축될 수 있습니다. 호스트 상태 확인 (host health checks), 인증서 만료 스캔 (certificate expiry scans), K8s 포드 재시작 루프 (K8s pod restart loops), Prometheus 경고 폭풍 분류 (Prometheus alert storm classification), 로그 이상 패턴 매칭 (log anomaly pattern matching) 등은 모두 훌륭한 후보입니다. 용량 계획 (capacity planning) 및 아키텍처 변경은 전역적인 판단이 필요합니다. 이러한 작업들을 루프에 밀어 넣지 마세요.

기계가 결정할 수 있도록 "완료" 상태를 작성하세요. "이슈 리스트가 비어 있음"은 좋은 종료 조건입니다. "클러스터가 건강함"은 그렇지 않습니다. 에이전트 (agent)는 파일을 읽거나 명령어를 실행하여 true/false 답변을 얻어야 합니다. 조건을 작성할 때 스스로에게 물어보세요: 스크립트가 이를 한 줄로 결정할 수 있는가? 만약 그렇지 않다면, 당신의 에이전트도 아마 할 수 없을 것입니다.

데이터를 메모리가 아닌 파일을 통해 전달하세요. 한 단계의 출력은 다음 단계의 입력이며, 형식(format)이 제한되어야 합니다. 그래야 실수를 즉시 잡아낼 수 있습니다. 에이전트는 메모리 능력이 매우 떨어집니다. 컨텍스트 (context)가 길어지면 잊어버립니다. 파일은 그렇지 않습니다.

쓰기 작업(Write operations)에는 인간의 게이트(human gate)가 필요합니다. 스테이징 (staging) 환경은 완전히 자동화할 수 있습니다. 하지만 프로덕션 (production) 환경은 그럴 수 없습니다. 승인 단계는 전체 루프를 위한 안전 밸브입니다. 이를 계약(contract)에 명시하세요. 프롬프트 (prompt)에 작성하는 것보다 백 배는 더 신뢰할 수 있습니다.

상한선을 설정하세요. 최대 반복 횟수 (Max iterations)는 목표가 아니라, "무언가 잘못되었다"라고 말해주는 회로 차단기 (circuit breaker)입니다. 건강한 루프는 한계치보다 훨씬 낮은 수준에서 수렴합니다. 만약 상한선에 도달했다면, 어떤 문제가 해결되지 않거나 검사가 계속해서 잘못된 경고 (false-flagging)를 내보내고 있는 것입니다. 이때는 사람이 개입할 시간입니다.

마치며

agent-runbook은 의도적으로 가볍게 설계되었습니다. 이것은 완전한 루프 엔지니어링 (Loop Engineering) 구현체가 아닙니다. 이것은 한 가지 일, 즉 당신의 루프 구조를 선언적 파일 (declarative file)로 작성하는 일을 수행합니다. Claude Code나 Codex가 나머지를 처리합니다.

처음부터 시작할 필요는 없습니다. examples directory에는 런북 파일, 검사 스크립트, 실제 실행에서 얻은 실제 수정 이력을 포함한 전체 호스트 상태 확인 루프가 포함되어 있습니다.

단순한 호스트 상태 확인 (host health checks)만이 아닙니다. 인증서 만료 스캔 (Certificate expiry scans), K8s 노드 상태 확인 (K8s node health checks), 로그 아카이브 정리 (log archival cleanup), 데이터베이스 백업 검증 (database backup verification), 미들웨어 설정 준수 확인 (middleware config compliance checks) 등 — 만약 당신의 운영 (ops) 작업이 "단계(steps) + 계약(contracts) + 의존성(dependencies)"로 분해될 수 있다면, 그것은 루프 (loop)가 될 수 있습니다.

리포지토리는 github.com/KnoxOps/agent-runbook에서 확인할 수 있습니다. 만약 서버에 SSH로 접속하여 문제를 확인하고 수동으로 수정하는 루틴이 있다면 — 그 흐름을 선언문 (declaration) 형태로 작성하여 도구가 실행하도록 해보세요. 그것은 당신보다 더 규율 있게 작동할 것입니다.