루프 엔지니어링: 에이전트를 부르는 반복을 설계하기

학습 목표: 에이전트에게 직접 prompt를 보내는 대신 prompt · 검증 · 재시도 · 멈춤을 맡는 루프를 설계하고, 루프의 여섯 구성 요소와 모양을 구분하며, 멈춤 조건과 비용 상한을 숫자로 정하고, 흔한 실패 모드를 미리 막을 수 있다.

「AI 엔지니어링의 층: 프롬프트 · 컨텍스트 · 하네스」가 에이전트 한 번의 실행을 둘러싼 층을 다뤘다면, 이 문서는 그 위층, 곧 여러 번의 실행을 누가 어떻게 이어 붙이는가를 다룬다. 루프 엔지니어링은 에이전트에게 prompt를 보내고, 결과를 검증하고, 실패를 되먹여 다시 시도하고, 언제 멈출지 정하는 제어 시스템을 설계하는 일이다. Headless 실행과 예약 실행의 세부는 「Headless · CI · Cloud 실행」, hook과 권한은 「권한 · Sandbox · Hook」, token 단가와 누적 공식은 「AI 토큰 효율화의 원리」에 있으므로 여기서는 루프 관점만 짚는다. 도구와 기능은 2026-09 기준이며, 공식 문서와 소스에서 확인하지 못한 것은 그렇다고 적었다. 달러→원 환산은 1 USD = 1,400원(가정)이다.

핵심 개념

이름과 뿌리

2026-06-07 Peter Steinberger가 X에 "coding agent에게 prompt를 보낼 게 아니라, agent에게 prompt를 보내는 루프를 설계해야 한다"는 취지의 글을 올렸다(검색 결과로 확인, 원문 게시물은 열지 못함). 같은 달 Claude Code를 이끄는 Boris Cherny가 "더 이상 Claude에게 prompt하지 않는다. 루프가 prompt한다. 내 일은 루프를 쓰는 것"이라는 취지로 말했다고 널리 인용되지만, 원본 영상 · 게시물은 확인하지 못했고 2차 출처로만 봤다. 2026-06-08 무렵 Addy Osmani는 에세이 「Loop Engineering」에서 prompt engineering 위에 harness engineering, 그 한 층 위에 loop engineering을 두는 층 구조를 제시했다(검색 결과로 확인, 본문 열지 못함). Harness가 한 번의 실행에서 에이전트가 무엇을 할 수 있는지를 정한다면, loop는 다음에 무엇을 시키고, 무엇으로 합격을 판정하고, 언제 멈추는지를 정한다. 아래층은 「AI 엔지니어링의 층: 프롬프트 · 컨텍스트 · 하네스」에서 다룬다.

• ReAct(Yao 외, 2022-10 arXiv, ICLR 2023): 모델이 추론(thought)과 행동(action)을 번갈아 내고, 환경의 관찰(observation)을 받아 다음 추론에 쓴다. 오늘날 agent가 한 턴 안에서 도구를 부르고 결과를 읽는 inner loop의 원형이다.
• Ralph(Geoffrey Huntley, 2025): agent를 shell의 while 루프 안에서 같은 prompt로 계속 다시 부르는 기법이다. 반복마다 context는 비워지고, 상태는 디스크의 계획 파일과 commit에 남는다. 테스트 · type check · lint가 잘못된 작업을 되돌려 보내는 backpressure 역할을 한다. 핵심은 while :; do cat PROMPT.md | claude ; done 한 줄이다(ghuntley/how-to-ralph-wiggum). 2025-07의 첫 예시가 Amp CLI였다는 것은 검색 결과로만 확인했다. Anthropic 공식 plugin 저장소의 「ralph-loop」는 같은 발상을 shell 대신 Stop hook으로 구현한다. 세션이 끝나려 할 때 hook이 막고 같은 prompt를 다시 넣는다. --max-iterations의 기본값은 무제한이고, README는 이것을 항상 지정하라고 권한다(--completion-promise는 정확한 문자열 일치 하나뿐이기 때문).

여섯 가지 구성 요소

원리

1. 루프의 모양

2. 루프는 verifier보다 나아질 수 없다

Anthropic 「Building effective agents」(2024-12)는 agent가 매 단계 환경에서 ground truth(도구 결과, 코드 실행)를 받아 진행을 판단해야 한다고 쓰고, 한 LLM이 만들고 다른 LLM이 평가해 되먹이는 evaluator-optimizer 흐름을 소개한다. 루프가 "끝났다"고 믿는 근거는 verifier뿐이므로, verifier가 약하면 루프는 빠르게 틀린 답으로 수렴한다. 그래서 결정적 검증(테스트, type check, lint, build)을 먼저 두고, 판단이 필요한 검증은 만든 모델의 추론 이력을 보지 않은 새 context의 reviewer에게 diff와 증거만 주어 맡기며, 가능하면 다른 모델을 쓴다. LLM 평가자는 자기 출력을 알아보고 더 높게 치는 경향(self-preference)이 있고(Panickssery 외, NeurIPS 2024), 같은 모델끼리는 맹점도 겹친다.

3. 멈춤 조건은 세 겹으로 건다

하나만 걸면 새어 나간다. 시도 예산(몇 번), 비용 · 시간 예산(얼마, 몇 분), 무진전 감지(같은 실패가 반복되는가)를 함께 건다.

flowchart TD
    G[목표와 완료 기준] --> O[Orient: 기록과 현재 상태 읽기]
    O --> A[Act: 가장 작은 되돌릴 수 있는 변경]
    A --> V{Verifier 통과?}
    V -->|예| D[Done: 증거와 NOT VERIFIED 목록]
    V -->|아니오| R[Record: 결과와 배제한 원인]
    R --> S{같은 실패가 두 번째?}
    S -->|예| H[진단을 다시 세운다]
    S -->|아니오| B{시도 3회 미만이고 예산이 남았나?}
    H --> B
    B -->|예| F[실패 신호를 다음 prompt에 주입]
    F --> O
    B -->|아니오| X[Budget spent: 배제한 원인 보고]
    A -.->|결정 · 권한 · 자격 증명 필요| K[Blocked: 사람 checkpoint]

4. 상태는 context 밖, 디스크에 둔다

긴 루프에서 context는 흐려진다(context rot, 「AI 토큰 효율화의 원리」). 그래서 반복마다 새 context로 시작하고, 이어 가야 할 것은 파일로 넘긴다. Anthropic 「Effective harnesses for long-running agents」(2025-11)는 첫 세션이 환경을 준비하고, 이후 세션은 진행 로그 파일(claude-progress.txt), passes 필드가 있는 JSON 기능 목록, 설명이 붙은 git commit으로 이어 가는 구조를 보여 준다. 같은 글은 agent가 너무 일찍 완료를 선언하고, 테스트 없이 기능을 완료로 표시하는 실패를 관찰했다. 넘겨야 할 기록은 셋이다: 무엇을 했나(commit), 무엇이 남았나(계획 · 진행 파일), 무엇을 배제했나(시도한 원인과 그 결과).

5. 도구로 루프 만들기(2026-09)

/goal은 내부적으로 세션 범위의 prompt 기반 Stop hook이다. 평가자는 도구를 쓰지 않으므로 "테스트가 통과한다"는 조건은 agent가 테스트를 돌려 결과가 대화에 찍혀야 판정된다. 권한 · hook 설정은 「권한 · Sandbox · Hook」, headless 인증과 CI는 「Headless · CI · Cloud 실행」을 따른다. 아래는 세 겹 멈춤 조건을 건 outer loop의 뼈대다.

#!/usr/bin/env bash
set -u
echo "none" > prev-failure.txt
for i in 1 2 3; do                                   # attempt budget
  timeout 20m claude -p "$(cat PROMPT.md)" --permission-mode acceptEdits \
    --allowedTools "Bash(git add *)" "Bash(git commit *)" \
    --max-turns 30 --max-budget-usd 3 --output-format json > "run-$i.json"   # time, turn and cost cap per run
  rc=$?
  [ "$rc" -eq 124 ] && { echo "TIME BUDGET: attempt $i ran past 20m"; exit 3; }
  kind=$(jq -r '.subtype // empty' "run-$i.json" 2>/dev/null)
  case "$rc:$kind" in
    0:*|*:error_max_turns|*:error_max_budget_usd) ;;                             # capped runs still get verified
    *) echo "BLOCKED: claude exited $rc"; exit 4 ;;                              # auth, config or startup failure
  esac
  if npm test > "test-$i.log" 2>&1; then echo "DONE at attempt $i"; exit 0; fi
  { grep -E "FAIL|Error|not ok" "test-$i.log" || tail -n 40 "test-$i.log"; } | head -n 40 > last-failure.txt
  cmp -s last-failure.txt prev-failure.txt && { echo "NO PROGRESS: rethink the diagnosis"; exit 2; }
  cp last-failure.txt prev-failure.txt
done
echo "BUDGET SPENT: see PROGRESS.md for ruled-out causes"; exit 1

PROMPT.md에는 "PROGRESS.md와 last-failure.txt를 먼저 읽고, 끝에 배제한 원인을 PROGRESS.md에 적고 commit하라, 테스트 파일은 고치지 마라"를 넣는다. Verifier(npm test)가 agent 밖에서 돈다는 점이 핵심이다. timeout은 시간을 넘기면 124로 끝나고, 스크립트는 이것을 시간 예산 소진으로 본다. --output-format json 결과의 subtype이 error_max_turns나 error_max_budget_usd이면 상한에 걸린 정상 종료로 보고 verifier로 넘어간다(Agent SDK 결과 메시지의 값). 그 밖의 0이 아닌 종료, 특히 run-$i.json이 비었거나 subtype이 없는 경우(인증 · 설정 · 시작 실패)는 verifier를 돌리지 않고 BLOCKED로 끝낸다. 실패 신호는 FAIL · Error · not ok 줄을 쓰고, 그런 줄이 없으면 로그 마지막 40줄로 대신한다.

적용: 이 저장소의 루프

단위 루프: .ai/LOOP.md

이 저장소의 agent 규칙 .ai/LOOP.md는 한 번의 시도를 네 단계로 고정한다. Orient(바꿀 대상과 그 변경이 실제로 닿는지 정하는 관문을 읽는다) → Act(질문을 가를 가장 작은 되돌릴 수 있는 변경) → Verify(실제로 가진 질문에 답하는 가장 싼 검사, 그 질문을 적는다) → Record(결과와, 그 결과가 답하지 않은 것). 시간에 쫓기면 Record가 빠지고, 그러면 세 번의 시도가 같은 시도 세 번이 된다고 경고한다.

이 사이트를 만든 리뷰 루프

이 사이트의 문서는 다음 review loop로 만들어졌다. Writer agent가 초안을 쓰고 → 다른 모델의 적대적 reviewer가 새 context에서 초안을 공격하듯 읽고 지적에 등급을 붙이고 → Fixer가 지적을 고친다. 이것을 3라운드 반복한 뒤, 고친 내용만 다시 보는 수정 확인 패스를 거치고, 마지막에 build · test · 배포를 한다. 라운드 상한(3회)이 시도 예산이고, 수정 확인과 build · test가 최종 verifier이며, merge와 배포가 사람 checkpoint다. .ai/EXECUTION.md는 reviewer에게 요구사항 · 관련 구조 · diff · 테스트와 build 증거 · 리뷰 규칙만 주고 구현자의 추론 이력은 넘기지 않는다고 정한다. 아래는 영역별 실제 기록이다. 출처는 linjingzhu/tech-jeongsu PR #10 설명의 review record 표와, 그 뒤의 3라운드를 기록한 PR #11이다. C = Critical, M = Major, m = Minor이고, 1라운드 수를 적지 않은 영역은 "기록 없음"으로 둔다. "무엇이 바뀌었나"는 AI 06–13 영역만 commit 기록에서 옮겼다.

대부분의 영역은 라운드마다 지적이 줄었지만, AI 06–08의 Critical은 3라운드에서 1건에서 2건으로 늘었다. 이 문서가 가르치는 "같은 종류의 지적이 다시 나온다" 신호다. 중심은 Hook 1(force push 차단 예제)이다. 우회는 1라운드에서 처음 지적됐고, 2 · 3라운드에서 새 형태로 다시 나왔다. 형태를 하나씩 막는 것은 "같은 실패를 파라미터만 바꿔 반복"하는 모양이다. 진단을 바꾼 것은 값을 미리 알 수 없는 인자($, backtick, {})는 값을 따지지 않고 닫힌 쪽으로 막는 규칙이다(2라운드에 $와 backtick, 3라운드에 { · }). 가능한 모든 값을 나열하려는 시도를 그만둔 것이다. Branch protection은 첫 초안부터 agent 바깥의 마지막 방어선으로 적혀 있었고, 3라운드는 branch 삭제를 범위 밖으로 적는 문장만 더했다.

루프 설계 점검표: 시작 전에 정할 것

심화

반복은 token 비용을 곱한다

「AI 토큰 효율화의 원리」의 가정(고정 prefix S = 20,000, 턴마다 Δ = 3,000, 턴당 출력 800, cache 사용, Opus 5.5 · Sonnet 5.5 단가)을 그대로 쓴다. 역할마다 새 세션을 열면 루프 비용은 반복 횟수에 비례하고, 한 세션에 몰아넣으면 이력 재전송 때문에 턴 수의 제곱에 가깝게 는다. Reviewer는 계산 편의상 Sonnet 5.5로 두었다. 다른 벤더 모델이면 그 단가로 바꿔 넣는다.

writes = S + (N-1)*D ; reads = N*S + D*N*(N-1)/2 - writes
writer   Opus 5.5,   N=30: 107,000*$5   + 1,798,000*$0.20 + 24,000*$20 = $1.3746
reviewer Sonnet 5.5, N=10:  47,000*$2.5 +   288,000*$0.20 +  8,000*$10 = $0.2551
fixer    Opus 5.5,   N=15:  62,000*$5   +   553,000*$0.20 + 12,000*$20 = $0.6606
3 rounds + fix check = 1.3746 + 3*(0.2551 + 0.6606) + 0.2551 = $4.3768

리뷰 루프는 한 번 쓰기의 약 3.2배지만, 같은 일을 한 세션에 쌓으면 그보다 약 1.8배 더 든다. 상한이 없는 루프는 여기에 반복 횟수만큼 곱해진다. 「AI 토큰 효율화의 원리」의 과제당 비용 = 시도당 비용 ÷ 성공률도 그대로 적용된다. Verifier가 약해 성공률을 과대평가하면 과제당 비용은 과소평가된다. /goal 평가는 small fast model로 과금되며 공식 문서는 본 작업 대비 대개 무시할 수준이라고 한다.

실패 모드

루프를 남의 소프트웨어나 서비스를 대상으로 돌린다면, 시작 전에 법적 경계부터 「리버스 엔지니어링: 법과 합법적 활용」에서 확인한다.

흔한 오해

• "루프를 돌리면 결국 맞는다." 루프는 verifier가 말하는 쪽으로 수렴한다. Verifier가 약하면 틀린 답으로 빠르게 수렴한다.
• "한 번 더 돌리면 된다." 같은 실패가 두 번이면 진단이 틀린 것이다. 세 번째 시도보다 배제한 원인 목록이 더 값지다.
• "Reviewer도 같은 모델이면 충분하다." 자기 출력을 선호하는 편향과 공통 맹점이 있다. 새 context와 다른 모델이 기본이다.
• "/loop와 /goal은 같은 것이다." /loop는 시간 간격으로, /goal은 조건이 참이 될 때까지 다음 턴을 시작한다. 세션 밖에서 돌려야 하면 Routines를 쓴다.
• "긴 한 세션이 여러 짧은 세션보다 싸다." 이력 재전송은 턴 수의 제곱에 가깝게 는다. 기록을 디스크에 두고 새 세션으로 끊는 편이 대개 싸고 정확하다.

자기 점검 질문

1. 지금 쓰는 작업 하나에서 완료 기준을 기계가 판정할 수 있는 한 문장으로 적어 보라. 그 문장을 약하게 만드는 가장 쉬운 변경은 무엇이고, 어떻게 막겠는가?
2. 세 겹의 멈춤 조건(시도, 비용 · 시간, 무진전)을 위 shell loop에서 각각 어느 줄이 맡는가? timeout이 124로 끝나면 스크립트는 어떻게 하는가?
3. Review loop에서 같은 종류의 지적이 세 라운드 연속 나오면, fixer에게 무엇을 다르게 시키겠는가?
4. Writer N = 30, reviewer N = 10, fixer N = 15로 리뷰를 2라운드만 하고 수정 확인을 생략하면 비용은 얼마인가(위 가정 그대로)?
5. /goal의 평가자가 파일을 직접 읽지 않는다는 사실은 완료 조건을 쓰는 방법을 어떻게 바꾸는가?

참고 자료

• Run prompts on a schedule · Keep Claude working toward a goal · Automate actions with hooks — Claude Code Docs, 2026-09-29 확인
• Automate work with routines · Run Claude Code programmatically · CLI reference — Claude Code Docs, 2026-09-29 확인
• openai/codex codex-rs/exec/src/cli.rs, codex-rs/utils/cli/src/shared_options.rs — OpenAI, 2026-09-29 확인
• Building effective agents(2024-12-19) · Effective harnesses for long-running agents(2025-11-26) — Anthropic Engineering, 2026-09-29 확인
• ghuntley/how-to-ralph-wiggum · anthropics/claude-plugins-official plugins/ralph-loop — GitHub, 2026-09-29 확인
• Ralph Wiggum as a "software engineer" — Geoffrey Huntley, 2025 · Peter Steinberger의 X 게시물 — 2026-06-07 · Loop Engineering — Addy Osmani, 2026-06(O'Reilly Radar 게재본 있음). 모두 2026-09-29 검색 결과로 확인
• ReAct: Synergizing Reasoning and Acting in Language Models — Yao 외, 2022-10, ICLR 2023, 2026-09-29 검색 결과로 확인
• Recent Frontier Models Are Reward Hacking — METR, 2025-06-05 · LLM Evaluators Recognize and Favor Their Own Generations — Panickssery 외, NeurIPS 2024. 둘 다 2026-09-29 검색 결과로 확인