Claude Code Loop 쉽게 이해하기

Claude Code의 loop는 에이전트가 멈춤 조건을 만날 때까지 작업을 반복하는 구조입니다. 이 글은 Anthropic의 Getting started with loops 내용을 바탕으로 4가지 loop를 쉬운 말과 실무 예시로 다시 설명합니다. 글을 읽고 나면 프롬프트를 더 길게 쓰는 대신, 어떤 반복을 사람 대신 맡길지 판단할 수 있습니다.

이 글은 2026년 7월 9일 기준으로 Anthropic Claude 블로그의 Getting started with loops와 Claude Code 문서를 참고했습니다. X 게시물은 로그인 없이 본문 전체를 확인하기 어려워, 같은 내용의 공식 Claude 블로그 글을 기준으로 해석했습니다.

왜 이제 프롬프트보다 Loop를 말할까?

AI 코딩 도구를 처음 쓸 때는 대부분 “어떻게 물어보면 좋은 답이 나올까?”를 고민합니다. 그래서 프롬프트를 길게 쓰고, 예시를 붙이고, 원하는 출력 형식을 자세히 적습니다. 이 방식은 여전히 중요하지만, Claude Code 팀이 말하는 핵심은 한 단계 더 나아갑니다.

이제 중요한 질문은 “한 번에 어떤 프롬프트를 잘 쓸까?”가 아니라 “어떤 반복 작업을 에이전트에게 맡길까?”입니다. 코딩 작업은 한 번의 답변으로 끝나지 않는 경우가 많습니다. 코드를 읽고, 수정하고, 테스트하고, 실패하면 다시 고치고, 리뷰 결과를 반영하는 반복이 필요합니다.

Claude Code 팀은 이런 반복을 loop라고 부릅니다. 더 정확히는 에이전트가 어떤 멈춤 조건을 만날 때까지 작업 사이클을 반복하는 구조입니다. 이 정의를 이해하면 “AI가 알아서 해줘”라는 막연한 요청을 “이 조건을 만족할 때까지 반복해줘”라는 검증 가능한 요청으로 바꿀 수 있습니다.

Loop의 핵심 정의

Claude Code 팀의 정의를 쉽게 풀면 다음과 같습니다.

Loop = 에이전트가 작업 사이클을 반복하다가, 멈춤 조건을 만나면 종료하는 구조

여기서 작업 사이클은 보통 다음 흐름입니다.

현재 요청과 코드베이스를 읽습니다.
필요한 변경을 판단합니다.
파일을 수정하거나 명령을 실행합니다.
테스트나 검증 결과를 봅니다.
충분하면 멈추고, 부족하면 다시 반복합니다.

중요한 단어는 멈춤 조건입니다. 멈춤 조건이 없으면 에이전트는 너무 빨리 끝내거나, 반대로 불필요하게 오래 돌 수 있습니다. “좋게 만들어줘”보다 “테스트가 통과할 때까지, 최대 5번만 시도해줘”가 더 좋은 요청입니다.

4가지 Loop 한눈에 보기

Anthropic 글은 Claude Code에서 사용할 수 있는 loop를 크게 네 가지로 나눕니다. 차이는 무엇이 loop를 시작시키는지, 무엇이 loop를 멈추게 하는지, 사람이 어느 부분을 넘기는지입니다.

Loop 유형	사람이 넘기는 것	시작 조건	멈춤 조건	어울리는 작업
Turn-based	검증 일부	사용자의 프롬프트	Claude가 완료 판단	짧고 일회성인 작업
Goal-based	멈춤 조건	사용자의 `/goal` 요청	목표 달성 또는 횟수 제한	성공 기준이 분명한 작업
Time-based	실행 트리거	시간 간격 또는 일정	취소하거나 작업 완료	반복 확인이 필요한 작업
Proactive	프롬프트 자체	이벤트 또는 스케줄	각 작업의 목표 달성	잘 정의된 반복 업무

표만 보면 조금 추상적입니다. 쉽게 말하면 오른쪽으로 갈수록 사람이 더 많은 부분을 에이전트에게 넘깁니다. 처음에는 “이 작업을 해줘”라고 한 번 요청합니다. 다음에는 “이 조건을 만족할 때까지 해줘”라고 멈춤 조건을 넘깁니다. 더 나아가면 “5분마다 확인해줘”처럼 시작 시점도 넘기고, 마지막에는 “새 이슈가 들어오면 분류하고 처리해줘”처럼 반복 업무 자체를 맡깁니다.

Turn-based Loop: 우리가 이미 쓰고 있던 기본 루프

Turn-based loop는 가장 익숙한 방식입니다. 사용자가 프롬프트를 보내면 Claude가 코드를 읽고, 수정하고, 필요하면 테스트를 실행한 뒤 결과를 돌려줍니다. Claude Code 팀은 이것도 하나의 agentic loop로 봅니다.

예를 들어 다음 요청은 turn-based loop입니다.

회원 가입 화면의 이메일 입력 검증 오류를 고쳐줘.
관련 테스트가 있으면 실행하고 결과를 알려줘.

이 경우 시작 조건은 사용자의 프롬프트입니다. 멈춤 조건은 Claude가 “요청을 완료했다”고 판단하는 순간입니다. 사람은 결과를 읽고, 마음에 들지 않으면 다음 프롬프트를 다시 보냅니다.

Turn-based loop는 짧은 작업에 좋습니다. 버그 하나를 고치거나, 작은 리팩터링을 하거나, 테스트 이름을 정리하는 정도라면 충분합니다. 하지만 “좋아 보일 때까지 반복”이 Claude의 판단에 많이 의존하므로, 중요한 검증은 사람이 직접 확인해야 합니다.

Turn-based를 더 좋게 만드는 방법

Turn-based loop에서 가장 약한 부분은 검증입니다. Claude가 코드를 수정했다고 해서 실제로 제대로 동작한다는 뜻은 아닙니다. 그래서 Anthropic 글은 검증 절차를 SKILL.md 같은 지침으로 인코딩하면 Claude가 스스로 더 많은 확인을 할 수 있다고 설명합니다.

예를 들어 프론트엔드 변경이라면 다음처럼 검증 기준을 명시할 수 있습니다.

UI 변경을 완료했다고 말하기 전에 다음을 확인한다.

- 개발 서버를 실행한다.
- 변경된 화면을 브라우저에서 연다.
- 버튼, 입력, 토글을 직접 조작한다.
- 변경 전후 스크린샷을 확인한다.
- 브라우저 콘솔에 새 오류가 없는지 확인한다.

이런 기준은 프롬프트보다 오래 갑니다. 매번 “테스트도 해줘, 브라우저도 확인해줘”라고 쓰지 않아도, 작업 규칙으로 남겨 둘 수 있기 때문입니다. 결국 좋은 turn-based loop는 프롬프트가 길어서가 아니라, 검증 기준이 코드베이스 안에 남아 있어서 좋아집니다.

Goal-based Loop: 완료 조건을 넘긴다

Goal-based loop는 사용자가 “무엇을 만족하면 끝인지”를 명확히 주는 방식입니다. Claude Code에서는 /goal 같은 형태로 목표를 설정할 수 있습니다. 핵심은 Claude가 임의로 “이 정도면 됐다”고 끝내지 않게 만드는 것입니다.

예를 들어 공식 글의 예시는 Lighthouse 점수를 기준으로 듭니다.

/goal 홈페이지 Lighthouse 점수를 90 이상으로 올려줘. 최대 5번까지만 시도해.

이 요청은 그냥 “성능 개선해줘”보다 훨씬 좋습니다. 성공 기준이 숫자로 보이고, 최대 시도 횟수도 정해져 있기 때문입니다. Claude는 수정하고 측정하고, 부족하면 다시 수정합니다. 목표를 달성하거나 최대 횟수에 도달하면 멈춥니다.

Goal-based loop는 테스트, 점수, 린트, 빌드처럼 기계적으로 확인 가능한 기준이 있을 때 강합니다. 반대로 “더 예쁘게 만들어줘”, “더 좋은 구조로 바꿔줘”처럼 주관적인 기준에는 약합니다. 그런 작업은 먼저 기준을 더 구체화하거나 turn-based로 탐색하는 편이 좋습니다.

Goal-based에 어울리는 기준

좋은 goal은 사람이 봐도 통과 여부를 판단할 수 있어야 합니다. 가능하면 숫자, 테스트 결과, 명령 결과, 체크리스트처럼 확인 가능한 형태가 좋습니다.

좋은 기준	애매한 기준
`bundle exec jekyll build` 성공	블로그가 잘 되게 하기
실패한 테스트 3개를 모두 통과	테스트를 적당히 고치기
Lighthouse Performance 90 이상	화면을 빠르게 만들기
타입 에러 0개	타입을 깔끔하게 정리
리뷰 코멘트 5개 모두 반영	리뷰를 잘 처리

애매한 기준이 나쁘다는 뜻은 아닙니다. 다만 애매한 기준은 loop의 멈춤 조건으로 쓰기 어렵습니다. 그런 경우에는 먼저 Claude에게 “이 작업의 검증 가능한 완료 조건을 제안해줘”라고 요청하고, 사람이 기준을 확정한 뒤 goal-based loop로 넘기는 편이 안전합니다.

Time-based Loop: 주기적으로 확인한다

Time-based loop는 일정 간격으로 같은 작업을 다시 실행하는 방식입니다. Claude Code 글에서는 /loop와 /schedule을 예로 듭니다. /loop는 로컬에서 반복 실행하고, /schedule은 클라우드 루틴처럼 일정에 따라 실행하는 방향으로 설명됩니다.

예를 들어 PR을 올린 뒤 이런 요청을 할 수 있습니다.

/loop 5m 내 PR을 확인해서 리뷰 코멘트를 반영하고, 실패한 CI가 있으면 고쳐줘.

이 loop는 사람이 계속 새로고침하지 않아도 됩니다. 5분마다 PR 상태를 보고, 리뷰나 CI 실패가 있으면 대응합니다. 작업이 외부 시스템의 변화에 의존할 때 유용합니다.

하지만 time-based loop는 간격을 신중하게 정해야 합니다. 30초마다 확인해도 결과가 거의 바뀌지 않는 시스템이라면 토큰과 API 호출만 낭비합니다. 외부 이벤트가 드물게 발생한다면 긴 간격으로 두거나, 가능하면 이벤트 기반으로 트리거하는 편이 좋습니다.

Proactive Loop: 반복 업무를 맡긴다

Proactive loop는 가장 강한 형태입니다. 사람이 실시간으로 프롬프트를 보내지 않아도, 이벤트나 스케줄에 따라 루틴이 실행됩니다. 새 버그 리포트가 들어오면 분류하고, 재현하고, 수정 후보를 만들고, 리뷰까지 요청하는 흐름이 여기에 가깝습니다.

공식 글은 proactive loop를 구성할 때 여러 primitive를 조합할 수 있다고 설명합니다. 예를 들어 /schedule로 새 리포트를 확인하고, /goal로 완료 조건을 정의하고, workflow로 여러 agent를 조율하고, auto mode로 반복 실행하게 만들 수 있습니다.

하지만 이 단계는 가장 조심해야 합니다. Proactive loop는 사람이 넘기는 범위가 넓습니다. 시작 조건, 반복 흐름, 일부 판단, 도구 실행까지 자동화될 수 있습니다. 그래서 먼저 작은 범위에서 파일럿을 돌리고, 실패 사례와 사용량을 관찰한 뒤 확장해야 합니다.

어떤 Loop를 선택해야 할까?

Loop 선택은 “얼마나 멋진 자동화를 만들 수 있는가?”가 아니라 “무엇을 사람 대신 맡겨도 안전한가?”로 판단해야 합니다.

상황	추천 Loop	이유
처음 해보는 기능을 탐색한다	Turn-based	사람이 방향을 자주 조정해야 함
테스트 통과처럼 완료 조건이 분명하다	Goal-based	멈춤 조건을 자동 검증할 수 있음
PR 리뷰나 CI처럼 외부 변화가 늦게 온다	Time-based	주기적으로 확인하는 일이 반복됨
매일 들어오는 이슈를 분류한다	Proactive	반복 업무가 잘 정의되어 있음
권한 변경이나 결제 처리	Workflow 또는 수동 승인	실패 비용이 크고 감사가 필요함

특히 마지막 줄이 중요합니다. 모든 일을 loop로 만들 필요는 없습니다. 결제, 개인정보, 권한, 데이터 삭제처럼 실패 비용이 큰 작업은 자동 loop보다 고정 workflow와 사람 승인이 더 적합합니다. Claude Code loop는 반복을 줄이는 도구이지, 책임을 없애는 도구가 아닙니다.

실전 예제: 블로그 포스트 검증 Loop

이 저장소 같은 Jekyll 블로그를 예로 들어 보겠습니다. 새 포스트를 작성할 때 사람이 반복해서 하는 일은 꽤 많습니다. front matter를 확인하고, 코드 fence를 확인하고, 링크를 확인하고, bundle exec jekyll build를 실행합니다.

이 작업은 goal-based loop로 바꾸기 좋습니다. 완료 조건이 비교적 분명하기 때문입니다.

/goal 새 포스트의 front matter, 코드 fence, 참고 링크, Jekyll build를 모두 확인해줘.
다음 조건을 만족하면 완료로 보고, 최대 3번까지만 수정해.

완료 조건:
- front matter에 layout, title, date, categories, tags가 있다.
- 코드블록은 모두 언어가 있고 fence가 닫혀 있다.
- 참고 링크가 열리는 공식 문서 또는 신뢰 가능한 출처다.
- bundle exec jekyll build가 성공한다.

이 요청에서 좋은 점은 “검증 가능한 완료 조건”이 있다는 것입니다. Claude가 글을 다 썼다고 느끼는 것이 아니라, 실제 명령과 문법 점검을 통과해야 합니다. 또한 최대 3번이라는 제한이 있어서 문제가 해결되지 않을 때 무한히 반복하지 않습니다.

더 발전시키면 이 검증 기준을 블로그 작성 skill로 빼둘 수 있습니다. 그러면 매번 긴 프롬프트를 쓰지 않아도 “블로그 작성 규칙대로 검증해줘”라고 할 수 있습니다.

품질을 지키는 핵심: 검증을 코드화하기

Anthropic 글에서 중요한 메시지 중 하나는 loop의 출력 품질이 주변 시스템에 달려 있다는 점입니다. 에이전트가 똑똑해도 코드베이스가 정리되어 있지 않고, 문서가 오래되었고, 검증 방법이 없으면 좋은 결과가 나오기 어렵습니다.

품질을 지키려면 다음 네 가지가 필요합니다.

코드베이스의 기존 패턴과 규칙이 깨끗해야 합니다.
“좋은 결과”를 판단하는 검증 절차가 있어야 합니다.
최신 문서와 레퍼런스에 접근할 수 있어야 합니다.
필요하면 별도의 리뷰 agent나 사람 리뷰가 있어야 합니다.

여기서 가장 실용적인 시작점은 검증 절차입니다. 테스트 명령, 빌드 명령, 화면 확인 방법, 리뷰 기준을 문서나 skill로 남겨 두면 loop가 같은 기준을 반복해서 사용할 수 있습니다. 문제가 한 번 생겼다면 그 문제만 고치고 끝내지 말고, 다음 loop에서 같은 실수를 줄이도록 규칙을 보강해야 합니다.

토큰과 비용 관리

Loop는 편리하지만 비용을 빠르게 늘릴 수 있습니다. 특히 time-based와 proactive loop는 사람이 지켜보지 않는 동안 계속 실행될 수 있습니다. 그래서 loop를 설계할 때는 기능뿐 아니라 사용량도 함께 설계해야 합니다.

실무에서는 다음 기준을 두는 것이 좋습니다.

작은 작업에는 복잡한 multi-agent workflow를 쓰지 않습니다.
성공 조건과 중단 조건을 구체적으로 적습니다.
큰 루틴은 작은 범위에서 먼저 파일럿으로 실행합니다.
결정적인 작업은 스크립트로 처리하고, 모델에게 매번 추론시키지 않습니다.
외부 시스템 확인 간격은 실제 변경 빈도에 맞춥니다.
실행 횟수, 토큰 사용량, 실패 이유를 주기적으로 봅니다.

예를 들어 PDF 양식을 채우는 작업이라면, 매번 Claude에게 코드를 새로 생각하게 하는 것보다 검증된 스크립트를 실행하게 하는 편이 저렴하고 안정적입니다. 모델은 모든 일을 직접 해결하는 존재가 아니라, 어떤 도구를 언제 쓸지 연결하는 조정자로 두는 편이 좋습니다.

자주 하는 실수와 주의사항

Loop를 쓰면 자동으로 품질이 좋아진다고 믿는다

Loop는 반복을 자동화할 뿐입니다. 검증 기준이 약하면 잘못된 작업도 반복됩니다. “테스트 통과”, “빌드 성공”, “리뷰 기준 충족”처럼 확인 가능한 기준을 먼저 만들어야 합니다.

멈춤 조건을 애매하게 둔다

“좋아질 때까지”, “괜찮을 때까지” 같은 조건은 loop에 적합하지 않습니다. Claude가 너무 빨리 끝내거나 너무 오래 돌 수 있습니다. 횟수, 점수, 테스트, 체크리스트처럼 종료 기준을 명확히 해야 합니다.

처음부터 proactive loop로 간다

Proactive loop는 강력하지만 실패 범위도 큽니다. 먼저 turn-based로 작업을 이해하고, goal-based로 완료 조건을 검증하고, time-based로 반복 확인을 해 본 뒤 확장하는 편이 좋습니다.

사람이 해야 할 판단까지 넘긴다

결제, 권한, 개인정보, 장애 대응처럼 책임이 큰 작업은 사람이 판단해야 합니다. Agent는 근거를 정리하고 후보를 제안할 수 있지만, 실행 권한은 정책과 승인 절차 뒤에 있어야 합니다.

deterministic work를 모델에게 계속 맡긴다

항상 같은 방식으로 처리되는 작업은 스크립트가 더 낫습니다. 포맷팅, 파일 목록 생성, 정적 검사, 단순 변환은 모델이 추론하기보다 명령이나 스크립트로 실행하는 편이 안정적입니다.

바로 적용하는 작은 시작

Claude Code loop를 처음 적용한다면 거창한 자동화보다 작은 작업 하나를 고르는 편이 좋습니다. 예를 들어 “PR 리뷰 코멘트를 반영하고 CI를 통과시키기”는 좋은 시작점입니다. 외부 변화가 있고, 완료 조건이 비교적 분명하며, 사람이 최종 diff를 리뷰할 수 있기 때문입니다.

다음 템플릿을 작업 전에 작성해 보세요.

반복시키고 싶은 작업:

Loop 유형:

시작 조건:

멈춤 조건:

최대 시도 횟수:

검증 명령:

사람 승인이 필요한 조건:

실패 시 남길 정보:

이 템플릿은 단순하지만 loop 설계의 핵심을 담고 있습니다. 시작 조건과 멈춤 조건이 비어 있으면 아직 loop로 만들 준비가 덜 된 것입니다. 검증 명령이 없으면 결과를 믿기 어렵고, 사람 승인 조건이 없으면 위험한 작업까지 자동화될 수 있습니다.

결론 및 도움말

Claude Code 팀이 말하는 loop의 핵심은 “프롬프트를 더 잘 쓰자”가 아니라 “반복 작업의 시작 조건과 멈춤 조건을 설계하자”입니다. Turn-based는 짧은 일회성 작업, goal-based는 검증 가능한 목표, time-based는 주기적 확인, proactive는 잘 정의된 반복 업무에 어울립니다.

처음부터 큰 자동화를 만들 필요는 없습니다. 지금 사람이 반복해서 확인하는 작은 작업 하나를 고르고, 어떤 부분을 넘길지 정해 보세요. 검증 기준과 중단 조건이 분명할수록 loop는 더 안전하고 쓸모 있는 개발 도구가 됩니다.