루프 엔지니어링 (Loop Engineering): agent-runbook을 활용한 에이전트 루프 구축

최근 AI 업계에 또 다른 흥미로운 새로운 용어가 등장했습니다.

루프 엔지니어링 (Loop Engineering).

만약 당신이 AI 분야를 팔로우하고 있다면, 지난 며칠 동안 어디에서나 이 용어를 보았을 것입니다. X(구 트위터) 전반에 퍼져 있고, 다양한 소셜 미디어에서도 나타나며, 꽤 많은 사람들이 단체 채팅방에서도 이에 대해 논의하고 있습니다.

최근 Addy Osmani는 이 개념을 루프 엔지니어링 (Loop Engineering)으로 공식적으로 정리했습니다. 이는 프롬프트 엔지니어링 (Prompt Engineering), 컨텍스트 엔지니어링 (Context Engineering), 하네스 엔지니어링 (Harness Engineering)에 이은 네 번째 엔지니어링입니다.

루프 (Loop)란 무엇일까요? 여기 구체적인 시나리오가 있습니다:

당신에게 16개의 실패하는 테스트가 있는 프로젝트가 있다고 가정해 봅시다. 이전에는 다음과 같이 했을 것입니다: 테스트를 실행하고, 무엇이 실패했는지 확인하고, Claude에게 "이것을 수정해줘"라고 말하고, Claude가 수정하면 다시 테스트를 실행하고, 새로운 문제를 발견하면 다시 무언가를 말하는 방식... 이렇게 왔다 갔다 하며, 당신이 직접 루프를 구동하는 사람(driving the loop)이 됩니다.

루프 엔지니어링 (Loop Engineering)의 핵심 아이디어는 다음과 같습니다: 당신은 더 이상 매 라운드마다 수동으로 루프를 구동하지 않습니다. 당신은 목표(모든 테스트 통과)를 정의하고, 각 라운드에서 할 일(테스트 실행 → 코드 수정)을 정의하며, 제약 조건(테스트 파일 수정 불가)을 정의한 다음, 그대로 놓아둡니다. 시스템은 목표가 달성될 때까지 스스로 작동합니다.

/goal 만으로는 부족합니다

이 시점에서 당신은 이렇게 말할 수도 있습니다: Claude Code에는 이미 /goal 명령어가 있지 않나요? 그냥 /goal "all tests pass"라고 입력하고 끝내면 안 되나요?

겉보기에는 그렇습니다. /goal은 완료 조건(completion condition)을 제공하며, Claude는 만족될 때까지 스스로 작업합니다. 하지만 몇 번 사용해 보면 문제를 발견하게 될 것입니다. 목표는 정의되었지만, 에이전트가 여전히 제대로 작동하지 않는다는 점입니다. 왜냐하면 당신은 에이전트에게 "무엇이 완료된 것으로 간주되는지"만 말했을 뿐, "매 라운드마다 무엇을 해야 하는지"는 말하지 않았기 때문입니다.

/goal "all tests pass" — 이것이 수행하는 작업:

에이전트에게 "이 조건이 충족될 때까지 계속 진행하라"고 지시합니다.
각 라운드가 끝날 때마다, 독립적인 모델이 목표가 충족되었는지 판단합니다.
에이전트는 매 라운드 수행하는 작업에 대해 완전한 자유를 가집니다.

이것이 수행하지 않는 작업:

각 라운드의 내부 구조를 정의하지 않습니다. /goal에서 에이전트는 매 라운드 자신이 원하는 것은 무엇이든 수행합니다. 첫 번째 라운드에서는 테스트 실행 및 코드 수정을 수행하고, 두 번째 라운드에서는 갑자기 리팩터링(refactoring)을 수행하며, 세 번째 라운드에서는 테스트 파일을 수정할 수도 있습니다.
반복 레벨의 제약 조건(iteration-level constraints)이 없습니다. /goal은 종료 조건(termination condition)만 가집니다. "라운드당 하나의 파일만 수정할 것"과 같은 가드레일(guardrail)이 없으며, 에이전트가 범위를 벗어나는 시점을 제어할 수 없습니다.
재사용이 불가능합니다. /goal에 "모든 테스트 통과"라고 입력하면 그 즉시 사라집니다. 다음에 리포지토리(repo)를 바꾸거나 담당자가 바뀌면, 이 모든 것을 다시 입력해야 합니다.
감사가 불가능합니다(Not auditable). 상사가 "이 자동 수정 워크플로우의 로직이 무엇인가요?"라고 물었을 때, /goal을 보여줄 수 없습니다.

요약하자면: /goal은 "에이전트가 멈추지 않게 하는 것"은 해결하지만, "에이전트가 규칙을 따르게 하는 것"은 해결하지 못합니다.

당신에게 필요한 것은 루프의 구조, 제약 조건, 그리고 목표를 기록할 장소입니다. 터미널에 한 번 입력하고 마는 명령어가 아니라, 리포지토리에 커밋(commit)할 수 있고, 이를 전달받은 누구라도 실행하여 동일한 동작을 얻을 수 있는 파일이 필요합니다.

agent-runbook: 루프를 위한 계약 형식 (The Contract Format for Loops)

이것이 바로 agent-runbook이 하는 일입니다.

agent-runbook은 오픈 소스 프로젝트(github.com/KnoxOps/agent-runbook)로, 루프를 실행하는 엔진이 아니라 루프를 위한 **계약 형식 (contract format)**입니다. YAML을 사용하여 "무엇을 반복할지, 언제 멈출지, 각 라운드의 제약 조건은 무엇인지"를 선언하면, 컴파일러가 여러분을 위해 SKILL.md를 생성합니다. 이는 Claude Code 및 Codex를 위한 재사용 가능한 지침 형식이며, 프로젝트에 포함하면 claude --skill 명령으로 직접 호출할 수 있습니다.

루프 단계(loop step)는 세 가지 요소로 구성됩니다:

body: 매 라운드 수행할 작업 (관찰(observe) → 행동(act) → 검증(verify)의 리듬)
goal: 중단 시점 (기계가 검증 가능한 조건이어야 함)
max_iterations: 안전 경계 (이 횟수를 초과하면 설계에 문제가 있음을 의미하며, 토큰 소모를 방지함)

한 가지 더 중요한 요소가 있습니다: quality_check. 이것은 반복(iteration) 수준의 가드레일(guardrail)입니다. 각 라운드가 끝난 후 에이전트가 범위를 벗어났는지(예: 수정해서는 안 될 파일을 수정했는지 등)를 확인합니다. 만약 blocking: true로 설정되어 있다면, 체크에 실패할 경우 해당 라운드는 완료된 것으로 간주되지 않습니다.

실습: 자동 테스트 수정 루프 구축

우리가 agent-runbook을 사용하여 어떻게 에이전트 루프(agent loop)를 구축하는지 보여주는 간단한 예시입니다.

우리는 자동 테스트 수정 (automated test fix) 루프를 구축할 것입니다. 이 루프는 단순하며, 목표는 유닛 테스트(unit test) 통과율 100%입니다. 각 반복(iteration)은 다음 두 단계로만 구성됩니다:

run_tests - 테스트를 실행하고, 어떤 테스트가 여전히 실패하는지 확인합니다.
fix - 발견된 문제를 수정하기 위해 깨끗한 컨텍스트(clean context)를 가진 에이전트를 실행합니다.

그 외에도 우리는 안전 경계인 max_iterations를 정의해야 합니다. 혹시 /goal 명령어를 사용하다가 토큰을 모두 소모해 버린 경험이 있는 독자가 계신가요? max_iterations가 바로 그런 상황을 방지해 줍니다.

다음은 구조화된 YAML로 정의된 전체 런북(runbook)입니다:

name: fix-failing-tests
description: Iteratively fix all failing tests until the test suite is green

...

YAML에서 실행 가능한 SKILL.md로

다음으로 YAML을 Claude Code/Codex가 직접 실행할 수 있는 SKILL.md로 컴파일해야 합니다. 생성 명령어는 간단합니다:

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

생성된 SKILL.md는 다음과 같습니다:

---
name: fix-failing-tests
description: ">-"
...
```json
{
  "task_id": "<input에서 가져온 task_id>",
  "current_step": 0,
  "current_step_id": null,
  "status": "running",
  "steps": {
    "fix_loop": "pending",
    "present": "pending"
  },
  "updated_at": "<ISO 타임스탬프>"
}
```

각 단계가 완료될 때마다 이 파일을 업데이트하세요. 오류가 발생하면 단계 상태(step status)를 `"failed"`로, 전체 `status`를 `"failed"`로 설정하세요.

...
```bash
cd examples/fix-loop && python3 -m pytest tests/ --tb=short 2>&1 | tail -60
```

#### Body Step 2: fix

...

생성된 SKILL.md에는 무엇이 포함되어 있을까요? 이는 YAML에서 선언한 계약(contracts)을 에이전트가 이해할 수 있는 실행 지침으로 변환합니다:

iteration_history (반복 이력): 에이전트가 매 라운드 수행된 작업과 목표 달성 여부를 기록하도록 요구하며, 이를 통해 구조화된 반복 메모리 (iteration memory)를 형성합니다.
goal evaluation (목표 평가): 각 라운드 후의 판단 로직 — 목표 달성 시 중단, 미달성 시 계속, 한도 도달 시 보고를 수행합니다.
progress tracking (진행 상황 추적): task_context.json을 통해 전체 진행 상황을 추적하며, 체크포인트 재개 (checkpoint resume)를 지원합니다.

실행하기: 3라운드 수렴 (3-Round Convergence)

이제 Claude Code에서 이 스킬을 실행하도록 트리거할 수 있습니다:

실행에는 세 번의 반복 (iterations)이 포함되었습니다:

Iteration 1: 계산기(calculator) 수정 → 6개의 실패 항목이 사라짐

Iteration 2: 검증기(validator) 수정 → 5개의 실패 항목이 사라짐

Iteration 3: 포매터(formatter) 수정 → 모두 통과 (all green)

마지막으로, 이것은 우리가 앞서 런북(runbook)에서 정의했던 내용이기도 합니다 — 루프 종료 후 생성되는 fix_report.md입니다:

좋은 루프를 설계하기 위한 핵심 포인트 (Key Points for Designing a Good Loop)

적절한 작업을 선택하세요. 모든 작업이 루프에 적합한 것은 아닙니다. 좋은 루프 작업은 두 가지 특징을 가집니다: 객관적인 피드백 신호(테스트 결과, 린트(lint) 출력, 컴파일 통과 여부)와 이전 라운드를 바탕으로 점진적인 진전을 이룰 수 있는 능력입니다. 테스트 수정, 코드 마이그레이션(code migration), 성능 최적화(performance optimization)는 모두 좋은 후보입니다. 일회성 창의적 결정(아키텍처 선택, 명명 규칙 등)이 필요한 작업은 적합하지 않습니다.
목표를 결정 가능한 종료 상태(decidable end state)로 작성하세요. "pytest exit 0"은 좋은 목표이지만, "더 나은 코드 품질"은 그렇지 않습니다. 에이전트는 도구 출력(tool output)을 통해 스스로 참(true) 또는 거짓(false)을 판단할 수 있어야 하며, 그렇지 않으면 루프는 언제 멈춰야 할지 알 수 없습니다.
본체(body)를 "관찰—실행(observe—act)" 리듬으로 유지하세요. 먼저 스크립트 단계(script steps)를 사용하여 현재 상태를 명확히 확인하고(테스트 실행, 린트 실행), 그다음 에이전트 단계(agent steps)를 사용하여 결정 및 수정을 수행하세요. 에이전트가 한 라운드 안에 관찰, 실행, 검증을 모두 수행하게 하지 마세요. 이를 분리하여 각 단계가 명확한 책임을 갖게 하면, 문제가 발생했을 때 원인을 찾기가 더 쉽습니다.
실패를 위한 탈출구를 마련하세요. max_iterations는 기대하는 라운드 수가 아니라, "이 횟수를 초과한다는 것은 접근 방식에 문제가 있음을 의미한다"라는 안전 밸브(safety valve)입니다. 정상적인 루프는 상한선보다 훨씬 낮은 수준에서 잘 수렴(converge)해야 합니다. 만약 최대 반복 횟수에 도달한다면, 이는 목표가 너무 어렵거나 본체 설계에 결함이 있다는 뜻이며, 인간의 개입이 필요함을 의미합니다.

agent-runbook: 단순한 루프 그 이상

제가 개발 중인 AI 제품 때문에, SRE(Site Reliability Engineers)를 위한 오류가 최대한 발생하지 않는(as-error-free-as-possible) 다수의 장기 실행 DevOps 스킬(skills)을 자주 작성해야 합니다. 디버깅 과정에서 저는 종종 두 가지 유형의 문제에 직면합니다. 하나는 에이전트가 지침을 따르지 않는 경우입니다. 예를 들어, 서비스만 재시작하라고 명령했는데 설정을 변경해 버리는 식입니다. 다른 하나는 복잡한 다단계 스킬(multi-step skill) 내에서 에이전트가 설정된 규범에 따라 협업하지 않는 경우로, 이전 단계의 출력을 다음 단계에서 전혀 읽지 못하거나, 읽더라도 형식이 잘못된 경우입니다.

이러한 문제들을 바탕으로 저는 agent-runbook을 개발했습니다. 이는 계약 기반(contract-based)의 스킬 생성 도구로, 생성된 SKILL.md를 Claude Code/Codex 생태계에 통합된 스킬로 직접 사용할 수 있습니다.

그 핵심 철학은 다음과 같습니다: 프롬프트(prompts)에 의존하며 최선의 결과를 기대하는 대신, 계약(contracts)을 사용하여 에이전트의 협업을 제약하는 것입니다.

구체적으로는 다음과 같습니다:

에이전트 우선 (Agent first) — 오케스트레이터(orchestrator)와 실행자(executor) 모두를 위해 컨텍스트(context)가 깨끗해야 합니다. 따라서 agent-runbook에서 정의되는 모든 단계는 type: agent로 정의하는 것을 권장합니다 (물론 다른 단계 유형도 허용됩니다).
컨텍스트보다 파일 (Files over context) — 단계들은 LLM 컨텍스트 창(context window)에 의존하지 않고, JSON Schema를 사용하는 파일을 통해 통신합니다. 이러한 파일들을 기반으로 각 단계의 현재 작업 진행 상황이 쉽게 유실되지 않으며, 작업이 완료된 후 실제로 예상대로 작동했는지 확인할 수 있어 에이전트가 만들어내는 "이미 완료했습니다"와 같은 환각(hallucination)을 최소화할 수 있습니다.
컴파일 타임 검증 (Compile-time validation) — 에이전트가 실행되기도 전에 다음 사항들을 확인합니다: DAG(Directed Acyclic Graph)에 사이클이 있는지, 스키마 참조(schema references)가 존재하는지, 각 단계의 입력에 상위 단계의 대응하는 출력이 있는지 등을 확인합니다. 설정이 잘못되었다면 컴파일 단계에서 에러를 발생시키므로, 작업 중간까지 가서 문제를 발견할 필요가 없습니다.
체크포인트 및 재개 (Checkpoint & Resume) — 긴 작업이 충돌(crash)한 후에도 체크포인트(checkpoint)에서 재개할 수 있으며, 처음부터 다시 시작할 필요가 없습니다.
선언적 오케스트레이션 (Declarative orchestration) — YAML을 통해 단계(step) 간의 위상 관계(topological relationships), 입출력 계약(input/output contracts), 품질 게이트(quality gates)를 선언하면, 컴파일러가 에이전트가 실행 가능한 SKILL.md를 생성합니다. 로직은 프롬프트의 문구가 아닌 계약(contracts)에 담겨 있습니다.

Loop는 이 기반 위에 추가된 단계 유형입니다. 작업에 반복(iteration)이 필요한 경우, 동일한 계약 기반 접근 방식(contract-based approach)을 사용하여 루프의 본문(body), 목표(goal), 제약 조건(constraints)을 정의하십시오.