Claude Code Loop Engineering 가이드: 4가지 Loop와 안전한 자동화 설계

Claude Code의 Loop는 단순히 모델을 오래 실행하는 기능이 아니다. 핵심은 확률적으로 행동하는 AI Agent 주위에 Trigger, Verifier, Success condition, Hard stop, Permission boundary를 배치해 반복 작업을 통제 가능한 시스템으로 만드는 데 있다. 이 글은 Turn-based, Goal-based, Time-based, Proactive Loop의 차이와 실무 설계 원칙을 한 번에 정리한다.

1. Claude Code에서 Loop란 무엇인가

여기서 Loop는 프로그래밍 언어의 for나 while 문이 아니다. Claude Code 팀이 설명하는 Loop는 Agent가 현재 상태를 관찰하고, 행동하고, 결과를 검증한 뒤, 종료 조건이 만족될 때까지 다시 작업하는 실행 구조다.

작업 시작
  ↓
상태와 코드 파악
  ↓
계획 수립
  ↓
코드 수정 또는 도구 실행
  ↓
테스트·검증
  ↓
완료 조건 충족?
  ├─ 아니오: 다음 반복
  └─ 예: 종료 및 결과 보고

Loop를 구분할 때는 다음 네 질문이 유용하다.

1. 무엇이 작업을 시작시키는가?
2. 무엇이 작업을 종료시키는가?
3. 어떤 Claude Code 기능이 반복을 제어하는가?
4. 어떤 종류의 작업에 적합한가?

모든 작업을 복잡한 Loop로 만들 필요는 없다. 한 파일의 오타 수정이나 단순한 이름 변경처럼 결과가 즉시 확인되는 작업에는 일반 프롬프트가 더 효율적이다. Loop는 여러 차례의 관찰·수정·검증이 실제로 필요한 경우에만 선택해야 한다.

2. 네 가지 Loop 유형 비교

이 분류의 핵심은 “AI가 얼마나 똑똑한가”가 아니라 사람이 어떤 제어 책임을 시스템에 넘기는가다. Turn-based에서 사람은 다음 프롬프트를 만들고, Goal-based에서는 완료 판단을 넘기며, Time-based에서는 재실행 시점을 넘긴다. Proactive 단계에서는 작업 발생을 감지하고 적절한 프롬프트를 실행하는 책임까지 시스템으로 이동한다.

3. Turn-based Loop: 검증 절차를 넘긴다

Turn-based Loop는 대부분의 개발자가 Claude Code를 사용하는 기본 형태다.

Human → Claude → Human → Claude

사용자가 요청하면 Claude는 관련 파일을 찾고, 코드를 수정하고, 테스트하고, 결과를 보고한다. 내부적으로는 여러 번의 관찰·행동·검증이 일어날 수 있지만, 다음 작업을 시작하는 권한은 사용자에게 남아 있다.

코드 수정과 기능 완성은 다르다

Claude가 “구현과 테스트를 완료했다”고 보고해도 실제 제품에서는 다음 문제가 남을 수 있다.

• 버튼 클릭 후 상태가 바뀌지 않는다.
• 브라우저 콘솔에 오류가 발생한다.
• 모바일 레이아웃이 깨진다.
• 접근성 속성이 빠져 있다.
• 테스트는 통과하지만 실제 브라우저 흐름은 실패한다.
• 변경과 무관한 파일까지 수정됐다.

따라서 완료 기준은 “코드를 바꿨다”가 아니라 “외부 증거로 동작을 확인했다”여야 한다.

SKILL.md로 검증을 재사용한다

Skill은 반복해서 사용하는 지침과 절차를 SKILL.md에 보관하는 방식이다. Claude가 관련성을 판단해 자동으로 불러오거나 /skill-name으로 직접 실행할 수 있다. 긴 운영 절차를 항상 CLAUDE.md에 넣는 것보다, 필요한 순간에만 Skill을 로드하도록 분리하면 컨텍스트를 더 효율적으로 사용할 수 있다.

---
name: verify-ui-change
description: UI 변경을 완료 처리하기 전에 실제 실행 환경에서 검증한다.
---

# UI 변경 검증

1. 개발 서버를 실행한다.
2. 변경된 화면을 브라우저에서 연다.
3. 새 컨트롤을 실제로 조작한다.
4. 기대한 상태 변화가 발생하는지 확인한다.
5. 브라우저 콘솔의 새 오류와 경고를 확인한다.
6. 접근성 및 주요 성능 지표를 점검한다.
7. 실패하면 수정 후 처음부터 다시 검증한다.
8. 실행한 명령, 결과, 스크린샷 등 증거를 보고한다.

좋은 Skill은 추상적인 당부가 아니라 실행 가능한 체크리스트를 담는다. “더 신중하게 검토한다”보다 “npm test가 종료 코드 0인지 확인한다”가 훨씬 강한 규칙이다.

검증 증거의 강도

Claude Code 공식 문서에는 실행 중인 애플리케이션을 확인하는 /run, 변경을 실제 실행 환경에서 검증하는 /verify 같은 bundled Skill도 설명되어 있다. 프로젝트 실행 방식이 복잡하다면 팀 고유의 Skill에 정확한 시작 명령, 환경 변수, 데이터 준비 절차를 기록하는 편이 안전하다.

4. Goal-based Loop: 종료 판단을 넘긴다

Goal-based Loop는 “한 번 더 작업할지”를 사용자가 매번 결정하지 않는다. 사용자는 완료 상태를 정의하고, Claude는 그 조건이 만족될 때까지 여러 Turn을 이어간다.

사용자가 Goal 지정
  ↓
Claude 작업 Turn
  ↓
별도 평가 모델이 완료 조건 확인
  ├─ 미충족: 이유를 다음 Turn에 전달
  └─ 충족: Goal 종료

/goal은 Claude Code v2.1.139 이상에서 사용할 수 있도록 문서화되어 있다. 한 세션에는 하나의 Goal만 활성화할 수 있다.

평가 모델이 실제로 보는 것

매 Turn이 끝나면 별도의 small fast model이 완료 조건과 대화 내용을 보고 충족 또는 미충족을 판단한다. 기본 설정은 Haiku 계열 평가 모델이다. 중요한 제한은 평가 모델이 파일을 직접 읽거나 테스트를 별도로 실행하지 않는다는 점이다.

따라서 작업을 수행한 Claude가 다음 증거를 대화에 명확히 남겨야 한다.

• 실행한 명령
• 테스트 개수와 통과·실패 결과
• 종료 코드
• 빌드 결과
• 변경 파일 목록
• 남아 있는 실패 원인
• 범위 제약을 지켰다는 확인 결과

평가 모델은 “실제로 무슨 일이 있었는가”가 아니라 “대화에 어떤 증거가 드러났는가”를 판단한다.

좋은 Goal의 네 요소

좋은 Goal은 다음 네 요소를 포함한다.

1. 측정 가능한 성공 조건: 테스트 통과, 빌드 성공, 큐 비움, 점수 임계치 달성
2. 검증 방법: 어떤 명령이나 도구로 성공을 증명할지 명시
3. 변경 범위 제약: 수정 가능한 디렉터리, 금지 파일, 허용된 Side effect
4. 강제 종료 조건: 최대 Turn, 최대 시간, 연속 실패 횟수, 권한 오류 시 중단

/goal auth 관련 테스트와 lint가 모두 성공하고,
git diff에는 src/auth와 관련 테스트 파일만 포함되어야 한다.
각 Turn에서 실행 결과와 종료 코드를 보고한다.
최대 12턴 또는 45분에 도달하면 중단하고 남은 실패를 정리한다.

/goal 자체의 핵심 종료 조건은 평가 모델의 성공 판정 또는 사용자의 /goal clear다. Turn·시간 한도를 강제하려면 Goal 조건 안에 명시해야 한다.

좋은 조건과 나쁜 조건

모호한 목표는 너무 빨리 종료되거나 끝없이 개선을 반복할 수 있다.

상태 확인과 중단

• /goal: 활성 조건, 실행 시간, 평가 Turn 수, 토큰 사용량, 최근 평가 이유 확인
• /goal clear: 활성 Goal 중단
• 새 Goal 설정: 기존 Goal 교체
• --resume 또는 --continue: 미완료 Goal 복원 가능

재개 시 조건은 유지되지만 Turn 수, 시간, 토큰 기준선은 초기화될 수 있으므로 Hard stop을 운영 지표와 함께 관리하는 것이 좋다.

/goal과 권한은 별개다

/goal은 다음 Turn을 자동으로 시작할 뿐 도구 권한을 넓히지 않는다. 파일 쓰기, 테스트 명령, Git 작업이 승인 대상이면 Goal 중에도 승인이 필요할 수 있다.

무인 실행에는 Auto mode를 함께 사용할 수 있지만, Auto mode는 “모든 도구를 무조건 허용”하는 기능이 아니다. 분류기가 파괴적이거나 되돌리기 어렵거나 신뢰 경계 밖을 대상으로 하는 작업을 차단하며, 명시적인 ask와 deny 규칙이 분류기보다 먼저 적용된다.

5. Time-based Loop: 재실행 시점을 넘긴다

Goal-based Loop가 “언제 멈출 것인가”를 다룬다면 Time-based Loop는 “언제 다시 실행할 것인가”를 다룬다. 외부 시스템의 상태가 시간이 지나면서 변하는 작업에 적합하다.

• PR에 새 리뷰가 달렸는지 확인
• CI 또는 배포가 끝났는지 확인
• 장시간 빌드 상태 확인
• 매일 Slack 메시지 요약
• 이슈 큐의 신규 항목 확인

/loop: 현재 세션 안에서 반복 실행

/loop 10m 현재 PR을 확인하고 새 리뷰를 반영하며,
실패한 CI가 있으면 원인을 분석하고 수정한다.

현재 문서에 설명된 주요 형태는 다음과 같다.

/loop는 현재 Claude Code 세션에 종속된다. 컴퓨터와 세션이 실행 중이어야 하며, 새 대화를 시작하면 세션 범위의 작업이 사라진다. 미만료 작업은 --resume 또는 --continue로 복원할 수 있지만, 반복 작업은 기본적으로 생성 후 7일 뒤 만료된다. 놓친 주기를 모두 소급 실행하지도 않는다.

세션 Scheduler에는 Jitter가 적용될 수 있으므로 “정각에 반드시 실행”해야 하는 운영 요구에는 적합하지 않을 수 있다.

/schedule: Anthropic 관리 Cloud Routine

/schedule은 Prompt와 Repository, Connector, Trigger를 묶어 Anthropic 관리 인프라에서 실행하는 Routine을 만든다. 노트북을 닫아도 실행할 수 있고, 공식 문서에서는 Research Preview로 안내한다.

Routine이 지원하는 Trigger는 다음과 같다.

• 반복 일정
• 특정 미래 시점의 일회성 일정
• 인증된 API 호출
• GitHub Pull request 또는 Release 이벤트

하나의 Routine에 여러 Trigger를 연결할 수 있다. 예를 들어 PR Review Routine을 매일 밤 실행하면서 pull_request.opened 이벤트에도 반응하게 만들 수 있다.

/loop와 /schedule 비교

Polling보다 Event가 나은 경우

변경이 드문 PR을 1분마다 확인하면 대부분의 실행은 아무 일도 하지 않고 종료된다. 외부 시스템이 이벤트를 보낼 수 있다면 다음 구조가 더 효율적이다.

CI 실패 또는 PR 업데이트
  ↓
GitHub Trigger 또는 Routine API
  ↓
필요할 때만 Claude 실행

Event 기반 설계는 지연을 줄이고 불필요한 모델 호출과 토큰 소비를 줄인다. Polling이 불가피하면 실제 변경 빈도에 맞춰 간격을 늘리고, 장시간 변화가 없을 때는 Backoff를 적용하는 것이 좋다.

시간 기반 작업의 필수 조건

1. 멱등성: 같은 이벤트를 여러 번 받아도 중복 댓글, 중복 PR, 중복 배포가 생기지 않아야 한다.
2. 처리 상태: 마지막 처리 Event ID, Commit SHA, Review Comment ID 등을 기록해야 한다.
3. 종료 상태: PR merge·close, Queue empty, Deploy success·rollback처럼 종료를 판정할 수 있어야 한다.
4. 쓰기 범위: 댓글 허용, Merge 금지, claude/* Branch만 Push 등 Side effect를 제한해야 한다.
5. 실패 처리: 외부 서비스 장애, 인증 만료, Rate limit, 권한 부족 시 재시도와 Escalation 규칙이 필요하다.

6. Proactive Loop: 작업 발견과 오케스트레이션을 넘긴다

Proactive Loop는 하나의 명령이 아니라 여러 기능을 결합한 상시 자동화 아키텍처다.

Trigger
+ Goal
+ Skills
+ Dynamic Workflow
+ Auto mode
+ Repository·Connector·Browser·CI 도구

사람이 실시간으로 프롬프트를 입력하지 않아도 새 작업이 감지되고, 처리되고, 검증되고, 결과가 보고된다.

예: 버그 피드백 자동 처리

GitHub Issue 또는 Slack 피드백 수신
  ↓
중복·우선순위·재현 가능성 분류
  ↓
재현 테스트 생성
  ↓
후보 해결책 탐색
  ↓
선택한 해결책 구현
  ↓
독립 Review Agent가 반례 탐색
  ↓
테스트·빌드·보안 검증
  ↓
Draft PR과 결과 보고

구성 요소별 책임은 다음과 같다.

Dynamic Workflow와 Worktree

Dynamic Workflow는 Claude가 작성한 JavaScript 오케스트레이션 Script를 Runtime이 실행하는 구조다. 일반 Subagent 호출에서는 Claude가 Turn마다 다음 Agent를 선택하지만, Workflow에서는 Loop, 병렬 처리, 분기, 중간 결과 저장이 Script로 이동한다.

Workflow Script
  ├─ Agent A: 요구사항 분석
  ├─ Agent B: 테스트 설계
  ├─ Agent C: 구현 후보 탐색
  ├─ Agent D: 보안 검토
  └─ Judge: 증거 기반 비교

중간 결과가 메인 대화 Context가 아니라 Script 변수에 남기 때문에 대규모 작업을 더 재현 가능하게 조직할 수 있다. 현행 문서에는 동시에 최대 16개 Agent, 실행당 최대 1,000개 Agent라는 Runtime 한도가 명시되어 있으나, 제품 Preview 단계의 제한은 바뀔 수 있다.

여러 구현 후보를 동시에 시험해야 한다면 Git Worktree로 작업 공간을 분리할 수 있다.

repo/
worktree-solution-a/
worktree-solution-b/
worktree-solution-c/

각 Agent가 독립 Branch와 디렉터리에서 작업하면 같은 파일을 동시에 덮어쓰는 문제를 줄일 수 있다. Judge Agent는 요구사항 충족, 테스트 결과, 회귀 위험, 변경 범위, 복잡도, 성능, 보안, 기존 아키텍처와의 일관성을 기준으로 후보를 비교해야 한다.

더 많은 Agent가 항상 좋은 것은 아니다

병렬성이 없는 작업에 Agent 수만 늘리면 비용과 지연이 증가한다. 여러 Agent가 같은 잘못된 가정을 공유하면 오류가 확대될 수도 있다.

Dynamic Workflow가 적합한 경우는 다음과 같다.

• 수백 파일에 같은 변환을 적용하는 Migration
• 코드베이스 전체의 보안·품질 Audit
• 독립적인 여러 관점의 Plan 비교
• 많은 항목을 분할 처리하고 교차 검증해야 하는 Research
• 한 Agent의 Context에 모든 중간 결과를 담기 어려운 작업

작은 버그 수정, 한 파일 리팩터링, 단순 테스트 추가에는 일반 Turn-based Loop나 /goal이 더 낫다.

7. Loop에서 코드 품질을 유지하는 시스템

Loop 결과의 품질은 모델 자체뿐 아니라 모델 주변의 검증 시스템에 크게 좌우된다.

7.1 코드베이스를 정돈한다

Claude는 기존 코드의 패턴을 강하게 따라간다. 오래된 API, 중복 구현, 불명확한 테스트 구조, 거대한 모듈, 일관되지 않은 예외 처리 규칙이 있으면 Loop가 그 문제를 빠르게 복제할 수 있다.

필수 기반은 다음과 같다.

• Formatter와 lint
• 명확한 디렉터리와 모듈 경계
• 신뢰할 수 있는 Unit·Integration·E2E Test
• 사용 중인 API와 Deprecated API의 구분
• 프로젝트별 개발 규칙
• 재현 가능한 Build·Dev 환경

7.2 변경 유형별 Definition of Done을 만든다

이 기준은 Prompt에 매번 길게 반복하기보다 Skill, Hook, Script, CI Rule로 고정하는 편이 좋다.

7.3 최신 문서와 정확한 버전을 제공한다

Loop는 잘못된 가정을 여러 차례 반복할 수 있다. 프로젝트에서 사용하는 정확한 Version, 공식 문서, 내부 Architecture 문서, API 명세, Migration Guide, 승인된 예제를 쉽게 찾게 해야 한다.

7.4 구현 Agent와 Review Agent를 분리한다

구현한 Agent는 이미 선택한 설계와 추론에 영향을 받는다. 새 Context의 Review Agent는 다음 질문을 더 독립적으로 던질 수 있다.

• 테스트를 약화시켜 통과시킨 것은 아닌가?
• 범위 밖 파일을 바꾸지 않았는가?
• 보안 경계가 깨지지 않았는가?
• 실패 경로와 경계값 테스트가 빠지지 않았는가?
• 기존 기능에 회귀가 생기지 않았는가?

Review Prompt는 “좋은 점을 요약하라”보다 “구현이 틀렸다는 가정에서 반례를 찾고, 각 지적에 재현 증거를 붙여라”처럼 작성하는 편이 효과적이다.

7.5 개별 실패를 시스템 개선으로 연결한다

같은 오류가 반복되면 해당 결과만 수정해서는 안 된다. 실패 유형이 재발하기 어렵도록 다음 중 하나를 바꿔야 한다.

• Regression Test 추가
• Skill 검증 절차 강화
• CLAUDE.md 규칙 추가
• Hook 또는 lint Rule 추가
• 권한 Deny Rule 추가
• Goal의 완료 조건 강화
• Review Checklist 보완

좋은 Loop Engineering은 한 번의 실패를 고치는 작업이 아니라 그 종류의 실패가 다시 나오기 어려운 시스템을 만드는 작업이다.

8. Token과 비용 관리

Loop 비용은 단일 Prompt보다 크게 증가할 수 있다.

총비용 ≈
메인 Agent Turn 비용
+ Goal 평가 비용
+ Subagent 비용
+ Workflow 반복 비용
+ 도구 결과를 읽는 Context 비용
+ 시간 기반 실행 빈도

정확한 과금은 Plan, Model, Provider에 따라 다르지만 비용 구조를 결정하는 원리는 동일하다.

비용을 줄이는 실무 원칙

1. 작은 작업에는 Loop를 쓰지 않는다. 오타, 이름 변경, 한 파일의 타입 오류는 단일 Turn으로 처리한다.
2. 성공 조건과 Hard stop을 함께 둔다. 성공, 최대 Turn, 최대 시간, 연속 실패, 권한 오류를 모두 고려한다.
3. 대규모 Workflow는 작은 범위에서 시험한다. 5개 파일, 한 디렉터리, 일부 Issue로 비용과 품질을 검증한 뒤 확대한다.
4. 결정론적 작업은 Script로 처리한다. AST 치환, JSON 변환, Formatting, 고정 양식 생성은 검증된 Script가 더 저렴하고 재현 가능하다.
5. Polling 주기를 실제 변경 빈도에 맞춘다. 가능하면 Event Trigger를 사용한다.
6. 진행 중 사용량을 관찰한다. /usage, /goal, /workflows에서 Skill·Subagent·MCP·Turn·Token 사용량을 확인한다.
7. 같은 오류가 반복되면 계속 재시도하지 않는다. 연속 실패 한도를 두고 사람에게 Escalation한다.

Model과 Effort는 다른 레버다

• Model은 기본 추론 능력과 해결 가능한 문제의 범위를 바꾼다.
• Effort는 읽는 파일 수, 사용하는 도구 수, 검증의 폭, 여러 단계 작업을 얼마나 끝까지 밀어붙이는지를 바꾼다.

Claude가 필요한 파일과 테스트를 모두 확인했지만 판단 자체가 계속 틀리면 더 강한 Model이 필요할 수 있다. 반대로 중요한 파일을 읽지 않거나 테스트를 건너뛰거나 리팩터링을 중간에 끝냈다면 Effort를 높이는 편이 더 적절할 수 있다.

9. 권한과 안전 경계

Proactive Loop에서 가장 위험한 설계는 Agent에게 넓은 권한을 주고, 성공 조건과 중단 조건을 느슨하게 두는 것이다.

Auto mode는 일반 권한 Prompt를 줄이지만, 되돌리기 어렵거나 파괴적이거나 신뢰 경계 밖을 대상으로 하는 Tool call은 분류기가 차단할 수 있다. 또한 명시적인 permissions.ask와 permissions.deny는 Auto mode보다 우선한다.

권한 계층 예시

대화에서 “Push하지 마라”고 한 번 말하는 것보다 영구 ask·deny Rule로 고정하는 편이 안전하다. Context 압축이나 세션 변경으로 대화 규칙이 약해질 수 있기 때문이다.

Cloud Routine은 실행마다 Repository를 새로 Clone하고 연결된 GitHub·Connector 권한으로 동작한다. 다음 범위를 최소화해야 한다.

• 접근 가능한 Repository와 Branch
• 허용된 Network Domain
• 사용할 Connector
• 환경 변수와 Secret
• 외부 시스템 쓰기 권한
• PR 생성·Push·Merge 범위

Routine 실행 목록의 “정상 종료” 상태는 Infrastructure 오류 없이 Session이 끝났다는 뜻일 수 있으며, 업무 목표가 성공했다는 보장은 아니다. Transcript, Test evidence, 생성된 Diff를 별도로 검토해야 한다.

10. 개발 프로젝트용 Loop 설계 템플릿

다음 YAML은 실제 Claude Code 문법이 아니라 설계 검토용 Template이다.

trigger:
  type: manual | interval | schedule | github_event | api_event

scope:
  repositories:
    - target-repository
  allowed_paths:
    - src/**
    - tests/**
  prohibited_paths:
    - production/**
    - secrets/**

task:
  objective: 변경하거나 처리할 목표
  input: 새로 들어오는 Issue, Event, File 또는 상태

verification:
  commands:
    - unit-test
    - integration-test
    - lint
    - build
  runtime_checks:
    - browser-interaction
    - console-errors
    - accessibility
  evidence:
    - command-output
    - exit-code
    - test-summary
    - screenshots

success:
  condition: 참과 거짓으로 판정 가능한 완료 상태

stop:
  max_turns: 12
  max_duration_minutes: 45
  max_consecutive_failures: 3
  stop_on_permission_error: true
  escalate_on_external_outage: true

side_effects:
  idempotency_key: event-id-or-commit-sha
  allow_branch_push: claude/*
  require_human_for_merge: true
  require_human_for_deploy: true

review:
  independent_agent: true
  adversarial_review: true

observability:
  report_progress: true
  report_token_usage: true
  report_changed_files: true
  report_remaining_failures: true

가장 중요한 항목은 프롬프트 문장 자체보다 다음 다섯 가지다.

Trigger
Verifier
Success condition
Hard stop
Permission boundary

11. 어떤 Loop를 선택해야 하는가

선택 순서는 “가장 강력한 기능”이 아니라 “목표를 달성하는 가장 단순한 제어 구조”를 기준으로 해야 한다.

12. 안전한 도입 순서

1. 사람이 반복해서 확인하는 병목 업무 하나를 고른다.
2. 먼저 검증 절차를 Skill, Script, CI로 만든다.
3. Turn-based 방식에서 검증 품질을 안정화한다.
4. 완료 상태가 명확하면 /goal을 붙인다.
5. 외부 상태를 기다려야 할 때만 /loop를 사용한다.
6. 장기 실행이 필요하면 /schedule Routine으로 옮긴다.
7. 멱등성, 권한, 비용이 검증된 뒤에만 Dynamic Workflow와 Proactive Loop로 확장한다.

13. 자주 발생하는 오해

결론

Loop Engineering은 AI를 오래 실행시키는 기술이 아니라, AI가 틀렸을 때 스스로 발견하고, 비용 한도 안에서 수정하며, 위험한 지점에서는 멈추도록 만드는 제어 시스템 설계다.

LLM은 탐색, 추론, 구현, 예외 분석, 대안 비교에 강하다. 시스템은 실행 시점, 변경 범위, 검증 방법, 종료 기준, 비용 한도, 승인 경계를 담당해야 한다. 이 역할 분담이 명확할수록 Claude Code 자동화는 단순한 코드 생성 도구를 넘어 재현 가능하고 감사 가능한 개발 운영 시스템에 가까워진다.