에이전트를 루프로
일하게 만드는 법
한 번 답하고 끝나는 챗봇이 아니라, 스스로 도구를 들고 여러 번 판단하며 일을 끝내는 에이전트. 그 뒤를 받치는 두 기둥이 루프와 하네스입니다.
프롬프트에서 하네스로
좋은 문장 하나를 다듬던 프롬프트 엔지니어링의 시대에서, 에이전트가 도구를 들고 여러 차례 스스로 판단하게 설계하는 하네스 / 컨텍스트 엔지니어링으로 무게중심이 옮겨갔습니다.
에이전트의 정의
Anthropic은 에이전트를 "도구를 루프로 자율 사용하는 LLM"으로 정의합니다. 명령에서 출발해 스스로 계획하고 움직입니다.
한 번이 아니라 반복
일은 한 번의 응답이 아니라 여러 컨텍스트 창에 걸친 루프로 진행됩니다. 긴 작업일수록 더 그렇습니다.
설계가 곧 성능
그래서 모델 자체만큼 "어떻게 시키느냐(하네스)"가 결과를 좌우합니다. 이것이 지금의 화두입니다.
출처: Anthropic, Building effective agents · Effective context engineering for AI agents
루프, 하네스, 그리고 에이전트
헷갈리는 세 단어를 먼저 정리합니다. 이 셋만 잡으면 나머지는 따라옵니다.
에이전트
도구를 루프로 자율 사용하는 LLM. 각 상호작용이 다음 판단의 맥락이 됩니다(점진적 공개, progressive disclosure).
에이전틱 루프
모델이 도구를 쓰고 → 결과(환경 피드백)를 보고 → 다음 행동을 정하는 반복. 본질은 "도구 + 피드백의 반복"입니다.
하네스
그 루프를 감싸는 범용 비계(scaffolding). 모델을 여러 컨텍스트 창에 걸쳐 루프로 돌려 장기 작업을 수행합니다(예: Claude Agent SDK).
모든 하네스의 최소 단위
복잡해 보여도 출발점은 하나입니다. 바로 증강된 LLM(augmented LLM): 검색·도구·메모리를 갖추고, 그것들을 모델이 직접 제어하는 단위입니다.
질의를 만들고, 도구를 고르고,
무엇을 기억할지 스스로 결정
출처: Anthropic, Building effective agents (the "augmented LLM" building block)
한 사이클을 들여다보기
루프 한 바퀴는 감지 → 사고 → 행동 → 관찰의 반복입니다. 매 단계는 환경에서 ground truth(도구 결과, 코드 실행)를 받아옵니다. 추측이 아니라 사실로 다음을 정합니다.
감지
현재 상태를 읽는다
사고
다음 한 수를 정한다
행동
도구로 변경을 가한다
관찰
결과를 확인하고 되돌아간다
실제 구현(superloop)에서는 한 틱이 이렇게 6단계로 펼쳐집니다:
원장·계약을 읽고 현실(git)과 대조
열린 작업 하나만 선택
가장 작은 올바른 변경
진짜 테스트·빌드·응답으로 확인
추가 전용 로그에 증거와 함께 기록
캐시를 아끼는 간격으로 다음 틱
출처: superloop SKILL.md (tick anatomy)
컨텍스트는 유한한 자원
컨텍스트 엔지니어링이란 추론 중 "최적의 토큰 집합"을 큐레이션하고 유지하는 전략입니다. 프롬프트 엔지니어링의 자연스러운 다음 단계로 불립니다.
컨텍스트 로트
토큰이 늘수록 그 안의 정보를 정확히 회상하는 능력은 떨어집니다. 길다고 좋은 게 아닙니다.
주의 예산
모델은 한정된 attention budget을 가집니다. 새 토큰 하나하나가 그 예산을 깎습니다.
영속 상태
진행 파일(예: progress.txt) + git 히스토리로 상태를 디스크에 남겨야 새 컨텍스트가 복구합니다.
하네스를 이루는 6가지
튼튼한 하네스는 다음 부품의 조합입니다. 처음엔 전부 갖출 필요 없이, 검증과 상한부터 챙기면 됩니다.
도구 호출
모델이 환경과 상호작용하는 손과 발. 함수 호출로 읽고 쓰고 실행합니다.
검증 게이트
테스트·브라우저로 "정말 됐는지" 확인. 없으면 모델은 안 된 것도 완료로 표시합니다.
예산 상한
max_ticks 같은 하드 실링으로 폭주를 막습니다. 상한은 실패가 아니라 안전장치입니다.
재시도 + 백오프
일시 실패만, 지수 백오프로, 횟수 상한 안에서. 영구 오류(400/404)는 재시도하지 않습니다.
영속 상태
컨텍스트 창을 넘어 상태를 보존. 파일 + git이 가장 단순하고 튼튼한 방법입니다.
격리
worktree·샌드박스로 동시 작업이 서로 충돌하지 않게 분리합니다.
실제로는 이렇게 생겼다
추상적인 개념이 실제 도구에서 어떻게 구현되는지 세 가지로 봅니다.
Claude Code
맥락 수집 → 행동 → 결과 검증을 반복하는 코딩 에이전트 루프. 게이트와 권한 모드가 행동을 감쌉니다.
장기 실행 하네스
2-프롬프트 구조: 첫 세션은 환경 셋업(init.sh, 진행 로그, 최초 git 커밋), 이후 세션은 점진 진행 + 다음 세션용 구조화된 업데이트를 남깁니다.
superloop (이 레포)
틱(ORIENT..PACE) + 한 장짜리 루프 계약 + 추가 전용 원장 + 건너뛸 수 없는 합의 게이트.
출처: Anthropic, Effective harnesses for long-running agents · superloop (this repo)
튼튼한 루프의 여섯 규칙
명시적 중단조건
최대 반복 수 같은 stopping condition으로 폭주를 묶습니다. 통제를 유지하는 가장 기본.
검증을 강제한다
E2E 테스트·브라우저 툴을 쥐여줘 "완료" 자칭을 막습니다. 이것만으로 성능이 크게 올랐습니다.
상태를 디스크에 남긴다
진행 파일 + git으로 새 컨텍스트가 언제든 복구할 수 있게 합니다.
쓰기 주체는 하나(owns)
자원마다 단 하나의 루프만 씁니다. 동시에 여러 루프를 안전하게 돌리는 비결.
점진적 자율성
새 루프는 report-only로 시작해 제안만 하고, 신뢰가 쌓이면 write로 승격합니다.
예산 실링
"주말 사이 400달러" 같은 사고를 막는 누적 상한. 상한에 닿으면 깔끔히 멈추고 보고합니다.
출처: Anthropic, Building effective agents · Effective harnesses · superloop loop-contract
자주 밟는 다섯 지뢰
대부분의 루프 사고는 새로운 게 아니라, 아래 다섯 가지의 반복입니다. 왼쪽은 증상, 오른쪽은 처방입니다.
무한 재시도
5xx 응답에 영원히 재시도하며 주말 내내 같은 실패를 갈아댑니다.
횟수 상한 + 지수 백오프
재시도는 일시 실패에만, 약 3회까지. 멱등 연산에만.
컨텍스트 폭주
토큰이 가득 차며 회상이 무너지고 출력이 엉킵니다.
영속 상태 + 큐레이션
상태는 디스크에. 요약·서브에이전트로 필요한 토큰만 남깁니다.
stdin drain
루프 안 자식 프로세스가 stdin을 통째로 먹어 첫 항목만 처리됩니다.
자식에 입력을 끊기
자식 명령에 </dev/null을 연결해 부모의 큐를 지킵니다.
게이트가 큐를 막음
막힌 작업 한 건이 나머지 큐 전체를 멈춰 세웁니다.
실패는 격리
한 단위의 실패·게이트는 격리하고, 큐는 계속 흐르게 합니다.
set -e가 꺼진다
func || rc=$? 안에서는 -e가 꺼져 실패 단계가 조용히 반복됩니다.
반환코드를 명시 검사
실패 경로를 직접 확인하고, 함정마다 실패 테스트를 먼저 만듭니다.
출처: superloop loop-runner-pitfalls.md · Anthropic (stopping conditions)
첫 루프를 위한 5단계
작은 루프를 read-only로
읽고 제안만 하게 시작합니다. 모든 쓰기는 일단 게이트 뒤에 둡니다.
한 장짜리 계약을 쓴다
범위·권한·예산·중단조건·보고처를 한 페이지에 고정합니다. 합의의 기준선.
검증을 코드로 만든다
테스트·빌드·HTTP 응답·읽기전용 DB로 "진짜 됐다"를 증명합니다.
예산과 중단조건을 박는다
max_ticks와 연속 실패 차단기로 폭주를 미리 묶어 둡니다.
신뢰가 쌓이면 write로
일관되게 유용하면 report-only에서 write로 승격합니다. 아니면 다시 내립니다.
여기서부터 깊이 파기
Building effective agents
Effective context engineering for AI agents
Effective harnesses for long-running agents
실사례: superloop-skill (이 레포)
이 가이드의 핵심 주장은 검색 후 3표 적대적 검증(2/3 이상 반박 시 폐기)을 통과한 항목만 실었습니다. 일부는 검증 미완으로 의도적으로 제외했습니다.