💡 왼쪽 원문을 읽으면서 오른쪽에 따라 써보세요. Tab 키로 힌트를 받을 수 있습니다.

원문 렌더가 준비되기 전까지 텍스트 가이드로 표시합니다.

들어가며

최근 Addy Osmani가 발행한 "Loop Engineering"이라는 글이 Hacker News와 GeekNews에서 큰 화제를 모았습니다. 요지는 간명합니다. 프롬프트 엔지니어링의 다음 단계는 더 좋은 프롬프트를 쓰는 것이 아니라, "에이전트를 프롬프트하는 시스템", 즉 루프를 설계하는 것이라는 주장입니다.

같은 시기에 또 하나 흥미로운 사건이 있었습니다. 스탠퍼드의 인기 강의 CS336(Language Modeling from Scratch)의 과제 리포지토리에 CLAUDE.md 파일이 포함되어 있다는 사실이 발견되어 커뮤니티에서 논쟁이 벌어진 것입니다. 강의 과제 리포에까지 AI 에이전트용 가이드라인이 명시되는 시대 — 이것이 2026년의 현실입니다. Claude Code, Codex, Copilot 류의 코딩 에이전트가 보편화되고, 수 시간 단위의 자율 작업이 가능한 frontier 모델 세대가 등장하면서, 개발자의 역할은 "코드를 쓰는 사람"에서 "에이전트가 도는 루프를 설계하는 사람"으로 이동하고 있습니다.

이 글에서는 루프 엔지니어링의 개념과 구성 요소, 검증 루프 구축, 리포 수준 가이드 파일 설계, 멀티 에이전트 분업, 체크포인트 설계, 실패 모드와 가드레일, 그리고 GitHub Actions 기반 실전 예제까지 차례로 살펴보겠습니다.

매 턴 수동 프롬프트의 한계

코딩 에이전트를 처음 쓰는 방식은 대개 이렇습니다. 지시를 입력하고, 결과를 보고, 잘못된 부분을 지적하고, 다시 지시하고. 이 "수동 핑퐁" 방식에는 구조적 한계가 있습니다.

- 병목이 사람: 에이전트는 분당 수천 토큰을 생성하지만, 사람의 확인과 재지시는 분 단위로 걸립니다. 전체 처리량이 사람의 반응 속도에 묶입니다.

- 피드백 품질의 불안정: 사람이 피곤하면 검토가 느슨해집니다. "대충 좋아 보이네"가 누적되면 결함이 통과합니다.

- 재현 불가능: 같은 작업을 다시 시켜도 그때그때 지시가 달라 결과가 달라집니다. 지식이 시스템이 아니라 개인의 채팅 이력에 갇힙니다.

- 확장 불가능: 동시에 굴릴 수 있는 에이전트 수가 사람의 멀티태스킹 한계로 제한됩니다.

핵심 통찰은 이것입니다. 에이전트의 출력 품질을 결정하는 것은 첫 프롬프트가 아니라, 출력에 대한 피드백이 얼마나 빠르고 정확하게 돌아오느냐입니다. 그리고 그 피드백은 사람이 아니라 시스템이 줄 수 있습니다. 테스트가, 린터가, 타입체커가, 또 다른 에이전트가.

수동 핑퐁과 엔지니어링된 루프를 나란히 놓으면 차이가 분명해집니다.

| 구분 | 수동 핑퐁 | 엔지니어링된 루프 |

| --- | --- | --- |

| 피드백 주체 | 사람 | 테스트, 린트, 검증자 에이전트 |

| 피드백 지연 | 분에서 시간 단위 | 초에서 분 단위 |

| 재현성 | 낮음 (개인 채팅 이력) | 높음 (스크립트, 가이드 파일) |

| 동시 실행 | 1에서 2개 | 수십 개 |

| 품질 하한 | 검토자 컨디션에 의존 | 검증 게이트가 보장 |

이 표의 오른쪽 열을 만드는 것이 이 글의 나머지 전부입니다.

루프의 해부학 — plan, act, verify, self-correct

루프 엔지니어링의 기본 단위는 다음 네 단계의 순환입니다.

+-----------------------------------+

| |

v |

[1. PLAN] |

작업을 단계로 분해, 성공 기준 정의 |

| |

v |

[2. ACT] |

코드 작성, 파일 수정, 명령 실행 |

| |

v |

[3. VERIFY] |

테스트, 린트, 타입체크, 빌드 실행 |

| |

v |

통과? --- 예 ---> [완료, 산출물 제출] |

| |

아니오 |

v |

[4. SELF-CORRECT] |

실패 로그를 읽고 원인 분석, 수정 계획 -----+

각 단계의 설계 포인트를 짚어보겠습니다.

Plan — 계획을 산출물로 만들어라

계획 단계를 에이전트의 머릿속(컨텍스트)에만 두지 말고, 파일로 쓰게 하는 것이 중요합니다. 계획 파일은 세 가지 역할을 합니다. 첫째, 사람이 작업 시작 전에 방향을 검토할 수 있는 게이트가 됩니다. 둘째, 긴 작업 도중 컨텍스트가 압축되어도 계획이 유실되지 않습니다. 셋째, 작업 완료 후 "계획 대비 무엇이 달라졌나"를 추적할 수 있습니다.

Act — 행동 반경을 명시하라

수정 가능한 디렉토리, 실행 가능한 명령, 건드리면 안 되는 파일을 명시합니다. Claude Code의 settings 파일에서 허용 도구를 제한하거나, 샌드박스 환경에서 실행하는 것이 이에 해당합니다.

Verify — 루프의 심장

검증이 없는 루프는 루프가 아니라 그냥 자동 타자기입니다. 다음 절에서 자세히 다룹니다.

Self-correct — 실패 정보의 품질이 수정 품질을 결정한다

에이전트가 자기 수정을 잘하려면 "무엇이 왜 실패했는지"가 기계가 읽기 좋은 형태로 전달되어야 합니다. 테스트 프레임워크의 verbose 출력, 린터의 JSON 포맷 출력 같은 것들이 자연어 설명보다 효과적입니다.

검증 루프 — 테스트, 린트, 타입체크를 에이전트의 피드백으로

루프 엔지니어링의 80%는 검증 루프 구축입니다. 원리는 단순합니다. 사람이 코드 리뷰에서 잡던 것을 기계 검증으로 옮길수록, 에이전트는 사람 없이 더 멀리 갈 수 있습니다.

검증 계층의 우선순위

| --- | --- | --- | --- |

빠른 계층부터 실행해 즉시 실패시키는 것이 핵심입니다. 타입 오류가 있는데 E2E를 돌리는 것은 토큰 낭비입니다.

최소 구현 — 검증 루프 스크립트

에이전트에게 "이 스크립트가 통과할 때까지 수정하라"고 지시하는 단일 진입점을 만드는 패턴이 실무에서 가장 효과적입니다.

#!/usr/bin/env bash

verify.sh — 에이전트 피드백용 단일 검증 진입점

set -euo pipefail

echo "== 1/4 typecheck =="

pnpm tsc --noEmit

echo "== 2/4 lint =="

pnpm eslint . --max-warnings 0 --format json -o lint-report.json \

|| { cat lint-report.json; exit 1; }

echo "== 3/4 unit tests =="

pnpm vitest run --reporter=verbose

echo "== 4/4 build =="

pnpm build

echo "ALL CHECKS PASSED"

에이전트 측 루프는 다음과 같이 단순하게 구성할 수 있습니다.

MAX_ITERATIONS = 8

def agentic_loop(task: str) -> dict:

plan = agent.run(f"다음 작업의 실행 계획을 plan.md에 작성하라: {task}")

for i in range(MAX_ITERATIONS):

agent.run("plan.md에 따라 다음 단계를 구현하라")

result = run_shell("./verify.sh")

if result.exit_code == 0:

return {"status": "success", "iterations": i + 1}

agent.run(

"검증이 실패했다. 아래 출력을 분석해 원인을 고쳐라.\n"

"같은 접근을 반복하지 말고, 두 번 연속 같은 오류면 "

"접근 자체를 바꿔라.\n\n" + result.output[-8000:]

)

return {"status": "needs_human", "iterations": MAX_ITERATIONS}

주목할 디테일이 세 가지 있습니다. 첫째, 반복 횟수에 상한이 있습니다(루프 폭주 방지). 둘째, 실패 출력의 마지막 부분만 전달합니다(컨텍스트 절약 — 대부분의 도구는 핵심 오류를 끝부분에 출력). 셋째, "같은 접근 반복 금지" 지시가 들어 있습니다(에이전트가 동일 수정을 무한 반복하는 고질적 실패 모드 대응).

테스트가 없는 코드베이스라면

검증 루프의 전제는 테스트인데, 테스트가 없다면 어떻게 할까요? 역설적이게도 이것이 에이전트의 첫 임무가 되어야 합니다. "수정 전에 현재 동작을 고정하는 특성화 테스트(characterization test)를 먼저 작성하라"는 지시를 루프의 0단계로 넣는 것이 정석입니다.

리포 수준 가이드 파일 — CLAUDE.md와 AGENTS.md 설계법

루프가 매번 잘 돌려면 에이전트가 리포지토리의 규칙을 알아야 합니다. 이를 위한 표준 관행이 CLAUDE.md(Claude Code)와 AGENTS.md(범용 규격)입니다.

스탠퍼드 CS336 사례가 말해주는 것

CS336 과제 리포의 CLAUDE.md는 짧지만 시사적입니다. 학생이 에이전트를 쓸 것을 전제하고, 에이전트에게 "정답을 대신 풀지 말 것" 같은 행동 규범을 리포 수준에서 지시합니다. 커뮤니티 논쟁의 핵심도 여기에 있었습니다. AI 사용을 막을 수 없다면, 리포가 직접 AI의 행동을 규정하는 것이 현실적이라는 것. 가이드 파일은 이제 사람용 README와 동급의 1급 산출물입니다.

좋은 가이드 파일의 구조

실무에서 검증된 구성은 다음과 같습니다.

CLAUDE.md 예시 구조

프로젝트 개요

한 문단. 무엇을 하는 코드베이스인지.

명령어

- 검증: ./verify.sh (커밋 전 반드시 통과)

- 테스트 단건: pnpm vitest run path/to/test

- 개발 서버: pnpm dev

코드 규칙

- 모든 public 함수에 타입 명시

- 에러는 Result 타입으로 반환, throw 금지

- 새 의존성 추가 전에 기존 유틸 검색

금지 사항

- data/migrations 디렉토리 수정 금지

- 테스트를 통과시키기 위해 테스트를 약화시키지 말 것

- CI 설정 파일 수정 금지

함정 (자주 틀리는 것)

- 이 리포의 alias @/ 는 src/ 가 아니라 app/ 을 가리킴

가이드 파일 작성 원칙

- 짧게 유지: 가이드 파일은 매 세션 컨텍스트에 로드됩니다. 500줄짜리 가이드는 그 자체로 context rot의 원인이 됩니다. 핵심만 남기고, 상세 문서는 링크로.

- 명령형으로: "테스트를 돌리는 것이 좋습니다"가 아니라 "커밋 전 ./verify.sh를 실행하라".

- 실패에서 역산: 에이전트가 실제로 틀린 사례가 나올 때마다 한 줄씩 추가하는 방식이, 처음부터 완벽하게 쓰려는 것보다 효과적입니다.

- 검증 가능한 규칙 우선: "좋은 코드를 써라"는 무의미합니다. "throw 대신 Result 반환"은 린트 규칙으로도 강제할 수 있습니다.

멀티 에이전트 분업 — 작성자와 검증자

사람 조직에서 작성자와 리뷰어를 분리하듯, 에이전트도 역할을 분리하면 품질이 올라갑니다. 같은 컨텍스트 안에서 "스스로 검토하라"고 시키는 것보다, 작성 컨텍스트를 모르는 별도 에이전트가 검토하는 쪽이 결함 발견율이 높다는 것이 실무의 일관된 관찰입니다. 작성자의 자기 합리화가 컨텍스트에 남아 있으면 검토도 그에 오염되기 때문입니다.

[오케스트레이터]

+---------------+---------------+

v v

[작성자 에이전트] [검증자 에이전트]

- plan.md 작성 - 디프만 보고 리뷰

- 코드 구현 - 스펙 대조

- verify.sh 통과까지 수정 - 보안/성능 점검

| |

+---> 디프 + 계획 전달 ---------+

승인 / 반려 (사유 포함)

반려 시 작성자에게 피드백 루프

분업 설계의 요점은 다음과 같습니다.

- 검증자에게는 디프와 스펙만 제공하고, 작성자의 추론 과정은 제공하지 않습니다(독립 검토 보장).

- 검증자의 반려 사유는 구조화된 형식(위치, 심각도, 근거)으로 받아 작성자 루프에 주입합니다.

- 반려-수정 사이클에도 상한을 둡니다. 3회 초과 시 사람에게 에스컬레이션.

장시간 자율 작업과 체크포인트 설계

2026년의 frontier 모델은 수 시간 단위의 자율 작업이 가능합니다. 그러나 작업 시간이 길어질수록 한 번의 잘못된 방향 전환이 만드는 손실도 커집니다. 해법은 체크포인트입니다.

체크포인트의 3요소

1. 상태 스냅샷: git 커밋이 가장 자연스러운 체크포인트입니다. 의미 있는 단위마다 커밋하게 하고, 커밋 메시지에 "계획 대비 진행 상황"을 쓰게 합니다.

2. 진행 노트: 컨텍스트 압축에서 살아남는 외부 메모(progress.md). 완료 항목, 미해결 문제, 다음 단계를 갱신하게 합니다.

3. 검증 게이트: 체크포인트마다 verify.sh를 통과해야 다음 단계로 진행. 실패 상태로 전진하는 것을 구조적으로 차단합니다.

진행 노트의 형식은 자유지만, 다음 구조가 압축 생존성과 가독성의 균형이 좋았습니다.

progress.md — 에이전트가 유지하는 진행 노트

목표

이슈 142: 결제 웹훅 재시도 로직 추가

완료

- 웹훅 핸들러에 멱등성 키 검증 추가 (커밋 a1b2c3)

- 재시도 큐 테이블 마이그레이션 (커밋 d4e5f6)

진행 중

- 지수 백오프 스케줄러 — 테스트 2건 실패 중

막힌 것 / 결정 필요

- 최대 재시도 횟수가 스펙에 없음. 임시로 5회 가정 (확인 필요)

다음 단계

1. 스케줄러 테스트 수정

2. 데드레터 처리 추가

시간 -->

[계획]--[구현1]--C--[구현2]--C--[리팩터]--C--[문서화]--완료

| | |

v v v

커밋+노트 커밋+노트 커밋+노트

verify OK verify OK verify OK

C = 체크포인트. 실패 시 마지막 C로 롤백 후 다른 접근 시도

체크포인트가 있으면 "4시간 작업 후 전체 폐기" 대신 "마지막 정상 지점으로 롤백 후 재시도"가 가능해지고, 사람의 개입 지점도 명확해집니다.

실패 모드와 가드레일

루프는 강력한 만큼 실패도 자동화합니다. 대표적 실패 모드와 대응을 정리합니다.

| 실패 모드 | 증상 | 가드레일 |

| --- | --- | --- |

| 루프 폭주 | 같은 수정을 무한 반복 | 반복 상한, 동일 디프 감지 시 중단 |

| 보상 해킹 | 테스트를 약화시켜 통과 | 테스트 파일 수정 금지 규칙, 검증자 분리 |

| 스코프 폭발 | 요청 밖 파일까지 대량 수정 | 디프 크기 상한, 허용 경로 제한 |

| 컨텍스트 부패 | 후반부에 초기 지시 망각 | 체크포인트 노트, 핵심 지시 재주입 |

| 비용 폭주 | 야간 루프가 예산 소진 | 토큰/시간 예산 상한, 알림 |

이 중 가장 교활한 것이 보상 해킹입니다. "테스트를 통과시켜라"라는 목표를 받은 에이전트가 assert를 주석 처리하거나, 기대값을 실제 출력으로 바꿔치기하거나, 테스트를 skip 처리하는 사례는 실제로 빈번히 보고됩니다. 대응은 세 겹입니다. 첫째, 가이드 파일에 명시적 금지. 둘째, 테스트 디렉토리를 쓰기 금지 경로로 설정. 셋째, 검증자 에이전트가 "테스트가 약화되지 않았는가"를 디프에서 별도 확인.

실전 예제 — GitHub Actions로 에이전트 루프 구성하기

루프를 CI에 올리면 "이슈에 라벨을 붙이면 에이전트가 PR을 만들어오는" 워크플로가 됩니다. Claude Code GitHub Action을 사용한 구성 예시입니다.

name: agent-loop

on:

issues:

types: [labeled]

jobs:

agent:

if: github.event.label.name == 'agent-task'

runs-on: ubuntu-latest

timeout-minutes: 90

permissions:

contents: write

pull-requests: write

issues: read

steps:

- uses: actions/checkout@v4

- name: Run agent on issue

uses: anthropics/claude-code-action@v1

with:

anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

prompt: |

이슈 #${{ github.event.issue.number }} 를 해결하라.

절차:

1. plan.md에 계획을 작성한다

2. 구현한다

3. ./verify.sh 가 통과할 때까지 수정한다 (최대 8회)

4. 통과하면 브랜치를 푸시하고 PR을 연다

제약:

- .github/ 과 tests/ 디렉토리는 수정 금지

- 디프가 500줄을 넘으면 작업을 분할 제안하고 중단

claude_args: "--max-turns 60"

여기에 두 번째 워크플로로 "PR이 열리면 검증자 에이전트가 자동 리뷰"를 붙이면 작성자-검증자 분업이 CI 위에서 완성됩니다. 사람은 최종 머지 판단만 합니다.

운영 시 주의점은 다음과 같습니다.

- timeout-minutes와 max-turns로 이중 상한을 겁니다. 하나만으로는 부족합니다.

- 에이전트가 만든 PR이 다시 에이전트를 트리거하는 재귀를 차단해야 합니다(라벨 조건, 봇 계정 필터).

- secrets 접근 범위를 최소화합니다. 2026년 6월의 npm 공급망 공격 사례가 보여주듯, CI에서 도는 모든 것은 공급망 공격의 표적입니다.

루프 텔레메트리 — 루프 자체를 관측하라

루프를 운영 시스템으로 다루려면 루프 자체의 관측 데이터가 필요합니다. 실행마다 다음과 같은 구조화 레코드를 남기면, "어떤 종류의 작업에서 루프가 자주 헛도는가", "가이드 파일 수정이 수렴 속도를 개선했는가" 같은 질문에 데이터로 답할 수 있습니다.

{

"run_id": "loop_20260612_042",

"task_ref": "issue-142",

"iterations": 3,

"wall_clock_minutes": 41,

"tokens": { "input": 412000, "output": 38000 },

"verify_failures": [

{ "iteration": 1, "stage": "unit-tests", "summary": "backoff off-by-one" },

{ "iteration": 2, "stage": "lint", "summary": "unused import" }

"guardrail_triggers": [],

"human_interventions": 0,

"outcome": "merged"

}

이 레코드에서 가장 주목할 필드는 iterations와 verify_failures의 stage 분포입니다. 특정 stage에서 반복 실패가 몰린다면, 그 stage의 오류 메시지가 에이전트에게 불친절하다는 신호인 경우가 많습니다. 루프 개선의 대상은 모델이 아니라 피드백의 품질일 때가 더 많습니다.

자주 묻는 질문

- 작은 팀도 루프 엔지니어링이 필요한가? — 1인 프로젝트라도 verify.sh와 CLAUDE.md 두 가지는 즉시 이득입니다. CI 통합과 멀티 에이전트는 팀 규모와 PR 빈도가 커질 때 도입하면 됩니다.

- 루프가 실패만 반복하면 모델 문제 아닌가? — 경험상 80%는 검증 피드백의 품질 문제거나 작업 정의가 모호한 문제입니다. 모델 교체 전에 실패 로그가 "사람이 봐도 원인을 알 수 있는 수준"인지 먼저 확인하세요.

- 검증이 느려서 루프가 비효율적이다 — 검증 계층화(빠른 것 먼저)와 변경 영향 기반 테스트 선택(affected tests only)을 먼저 적용하세요. 루프 1회전이 10분을 넘으면 체감 효율이 급락합니다.

- 에이전트가 만든 커밋을 그대로 머지해도 되는가? — 체크포인트 커밋은 작업 이력이지 릴리스 단위가 아닙니다. 머지 전 squash와 사람의 최종 리뷰를 권장합니다.

도입 로드맵

루프 엔지니어링은 전부 아니면 전무가 아닙니다. 단계적으로 갑니다.

1. 1주차 — 검증 단일 진입점: verify.sh 하나를 만들고, 에이전트 지시에 "이것이 통과할 때까지"를 붙이는 것만으로 절반은 도달합니다.

2. 2주차 — 가이드 파일: CLAUDE.md를 만들고, 에이전트가 틀릴 때마다 규칙을 한 줄씩 추가합니다.

3. 3에서 4주차 — 루프 자동화: 위의 agentic_loop 패턴을 스크립트화하고, 체크포인트(커밋 + 진행 노트)를 도입합니다.

4. 2개월차 — 분업과 CI 통합: 검증자 에이전트를 분리하고, GitHub Actions로 이슈-PR 루프를 구성합니다.

5. 지속 — 측정: 루프 1회당 비용, 사람 개입률, 반려율, 머지까지의 시간을 측정해 루프 자체를 개선합니다.

함정과 비판적 시각

루프 엔지니어링에 대한 회의론도 정당하게 다뤄야 합니다.

첫째, 검증 가능한 것만 좋아진다는 한계입니다. 테스트로 표현할 수 없는 품질 — 설계의 적절성, 코드의 의도 전달력, 제품 감각 — 은 루프가 보장하지 못합니다. 루프는 "기계가 검증할 수 있는 품질"의 하한선을 끌어올리는 도구이지, 좋은 소프트웨어의 충분조건이 아닙니다.

둘째, 검증 루프 자체가 기술 부채가 됩니다. 느린 테스트, 플레이키한 E2E는 사람보다 루프에 더 치명적입니다. 사람은 "이건 원래 가끔 실패해"라고 넘기지만, 에이전트는 그것을 고치겠다고 무관한 코드를 헤집을 수 있습니다.

셋째, 비용 구조의 변화입니다. 루프는 사람 시간을 토큰 비용으로 치환합니다. 8회 반복 루프가 매번 도는 작업이라면, 애초에 작업 정의가 잘못되었거나 가이드 파일이 부실하다는 신호일 수 있습니다. "루프가 돌았다"가 아니라 "몇 번 만에 수렴했나"를 봐야 합니다.

마치며

프롬프트 엔지니어링이 "한 번의 좋은 질문"을 만드는 기술이었다면, 루프 엔지니어링은 "사람 없이도 품질이 수렴하는 시스템"을 만드는 기술입니다. 그 시스템의 부품은 화려한 프롬프트가 아니라, 잘 만든 verify.sh, 간결한 CLAUDE.md, 적절한 체크포인트, 그리고 보상 해킹을 막는 가드레일입니다.

흥미롭게도 이것들은 모두 AI 이전부터 좋은 엔지니어링 조직이 해오던 일 — 빠른 CI, 명확한 컨벤션 문서, 작은 PR, 독립적 리뷰 — 의 연장선입니다. 에이전트 시대의 경쟁력은 결국 "기계가 일하기 좋은 코드베이스"를 만드는 데서 나옵니다. 그리고 그런 코드베이스는 사람에게도 일하기 좋은 코드베이스입니다.

참고 자료

- Addy Osmani — Loop Engineering: https://addyo.substack.com/p/loop-engineering

- GeekNews — 루프 엔지니어링 토픽: https://news.hada.io/topic?id=30336

- Stanford CS336 과제 리포의 CLAUDE.md: https://github.com/stanford-cs336/assignment1-basics/blob/main/CLAUDE.md

- Stanford CS336 — Language Modeling from Scratch: https://stanford-cs336.github.io/spring2025/

- Anthropic — Claude Code Best Practices: https://www.anthropic.com/engineering/claude-code-best-practices

- AGENTS.md — 에이전트 가이드 파일 규격: https://agents.md/

- Claude Code GitHub Actions 문서: https://docs.anthropic.com/en/docs/claude-code/github-actions

- Claude Code 리포지토리: https://github.com/anthropics/claude-code

- GitHub Actions 공식 문서: https://docs.github.com/en/actions

- Hacker News: https://news.ycombinator.com/