Claude Code 에서 루프 시작하기

코딩 에이전트에 프롬프트를 입력하는 대신 "루프(loop)를 설계"하는 것에 대한 논의가 현재 활발히 이루어지고 있습니다. X(트위터)에서 루프가 정확히 무엇인지 파악하는 데 시간을 투자하다 보면 여러 가지 다른 답변을 접하게 됩니다.

Claude Code 팀에서 우리는 루프를 에이전트가 중지 조건이 충족될 때까지 작업 주기를 반복하는 것으로 정의합니다. 다음과 같은 기준에 따라 몇 가지 유형의 루프를 분류합니다:

• 트리거 방식
• 중지 방식
• 사용되는 Claude Code 기본 요소(primitive)
• 각 루프에 가장 적합한 작업 유형

주요 루프 유형, 각각을 사용해야 하는 경우, 그리고 토큰 사용량을 관리하면서 코드 품질을 유지하는 방법을 다루겠습니다. 모든 작업에 복잡한 루프가 필요한 것은 아닙니다. 가장 간단한 솔루션부터 시작하고 이러한 패턴을 선택적으로 사용하세요.

턴 기반 루프 (Turn-based loops)

• 트리거: 사용자 프롬프트
• 중지 조건: Claude가 작업을 완료했거나 추가 맥락이 필요하다고 판단
• 최적 사용처: 정기적인 프로세스나 일정에 포함되지 않은 짧은 작업
• 사용량 관리 방법: 구체적인 프롬프트를 작성하고 스킬(skills)을 활용한 검증을 개선하여 턴 수를 줄임

보내는 모든 프롬프트는 사용자가 각 턴을 지시하는 수동 루프를 시작합니다. Claude가 맥락을 수집하고, 조치를 취하고, 작업을 확인하고, 필요시 반복한 후 응답합니다. 우리는 이를 에이전틱 루프(agentic loop)라고 부릅니다.

예를 들어, Claude에게 좋아요 버튼을 만들어 달라고 요청하면 Claude는 코드를 읽고, 수정하고, 테스트를 실행한 후 작동할 것이라고 믿는 결과물을 반환합니다. 그러면 사용자가 직접 작업을 확인하고 다음 프롬프트를 작성합니다.

수동 검증 단계를 SKILL.md로 인코딩하면 Claude가 자신의 작업을 종단간(end-to-end)으로 더 잘 확인할 수 있습니다. 여기에는 Claude가 결과를 보고, 측정하거나 상호작용할 수 있는 도구나 커넥터가 포함되어야 합니다. 검사가 정량적일수록 Claude가 스스로 검증하기 쉬워집니다.

예를 들어, SKILL.md 파일에 다음과 같이 지정할 수 있습니다:

1---
2name: verify-frontend-change
3description: 모든 UI 변경 사항을 종단간으로 검증한 후 완료 처리
4---
5
6# 프론트엔드 변경 사항 검증
7UI 변경 사항을 편집 성공만으로 완료되었다고 보고하지 마세요. 사람 리뷰어가 하는 방식으로 검증하세요:
8
91. 개발 서버를 시작하고 편집된 페이지를 브라우저에서 엽니다.
10
112. 변경 사항과 직접 상호작용합니다. 새로운 컨트롤(버튼, 입력 필드, 토글)의 경우: 클릭하고, 예상되는 상태 변경을 확인한 후, 이전/이후 스크린샷을 촬영합니다.
12
133. 브라우저 콘솔을 확인합니다: 새로운 오류나 경고가 0개여야 합니다.
14
154. Chrome Devtools MCP를 사용하여 성능 트레이스를 실행하고 Core Web Vitals를 감사합니다.
16
17어느 단계에서든 실패하면 문제를 수정하고 1단계부터 다시 실행하세요 — 부분적으로만 검증된 작업을 넘기지 마십시오.

목표 기반 루프 (Goal-based loop (/goal))

• 트리거: 실시간 수동 프롬프트
• 중지 조건: 목표 달성 OR 최대 턴 수 도달
• 최적 사용처: 검증 가능한 종료 기준이 있는 작업
• 사용량 관리 방법: 구체적인 완료 기준과 명시적인 턴 상한 설정, "5회 시도 후 중지"

때로는 단일 턴으로는 충분하지 않습니다, 특히 더 복잡한 작업의 경우. 에이전트는 반복할 수 있을 때 더 잘 수행합니다. /goal을 사용하여 "완료"가 무엇인지 정의하면 Claude가 반복을 계속하도록 할 수 있습니다.

성공 기준을 정의하면 Claude가 "충분히 좋다"고 판단하고 루프를 조기에 종료하지 않습니다. Claude가 중지하려고 할 때마다 평가자 모델이 조건을 확인하고 목표가 달성되거나 사용자가 정의한 턴 수에 도달할 때까지 다시 작업하도록 보냅니다.

이것이 통과한 테스트 수나 특정 점수 임계값 달성과 같은 결정론적 기준이 매우 효과적인 이유입니다.

예를 들어:

1/goal get the homepage Lighthouse score to 90 or above, stop after 5 tries.

시간 기반 루프 (Time-based loop (/loop 및 /schedule))

• 트리거: 지정된 시간 간격
• 중지 조건: 사용자가 취소하거나 작업이 완료됨 (PR 병합, 큐 비움)
• 최적 사용처: 반복적인 작업 또는 외부 환경/시스템과의 인터페이싱
• 사용량 관리 방법: 더 긴 간격 설정 또는 시간 기반이 아닌 이벤트 기반으로 반응

일부 에이전틱 작업은 반복적입니다: 작업은 동일하게 유지되고 입력만 변경됩니다. 예를 들어, 매일 아침 Slack 메시지를 요약하는 것과 같습니다. 다른 작업은 외부 시스템에 의존하며, 간단한 인터페이스 방법은 간격을 두고 확인하고 변경된 사항에 반응하는 것입니다. 예를 들어, 코드 리뷰를 받거나 CI가 실패할 수 있는 PR이 있습니다.

이러한 경우 \/loop``를 사용하여 Claude가 실행되도록 트리거할 수 있으며, 이는 간격을 두고 프롬프트를 다시 실행합니다. 예를 들어:

1/loop 5m check my PR, address review comments, and fix failing CI

\/loop`는 사용자 컴퓨터에서 실행되므로 컴퓨터를 끄면 중지됩니다. \/schedule\`로 루틴을 생성하여 루프를 클라우드로 이동할 수 있습니다.

프로액티브 루프 (Proactive loops)

• 트리거: 이벤트 또는 일정, 실시간 인간 개입 없음
• 중지 조건: 각 작업은 목표가 달성되면 종료됩니다. 루틴 자체는 사용자가 끌 때까지 실행됩니다.
• 최적 사용처: 잘 정의된 반복 작업 스트림: 버그 리포트, 이슈 트리아지, 마이그레이션, 의존성 업그레이드 등
• 사용량 관리 방법: 루틴을 더 작고 빠른 모델로 라우팅하고 판단이 필요한 부분에 가장 강력한 모델 사용

위의 기본 요소들과 자동 모드(auto mode) 및 동적 워크플로우(dynamic workflows)(연구 프리뷰)와 같은 다른 Claude Code 기능을 결합하여 장기 실행 작업을 위한 루프를 구성할 수 있습니다.

예를 들어, 들어오는 피드백을 처리하려면 다음을 사용할 수 있습니다:

1. `/schedule` (연구 프리뷰) - 새 보고서를 확인하는 루틴 실행
2. `/goal` - 완료된 상태 정의 및 스킬(skills) - 검증 방법 문서화
3. 동적 워크플로우 - 각 보고서를 트리아지하고, 수정하고, 수정 사항을 검토하는 에이전트 조율
4. 자동 모드 - 루틴이 허가를 요청하기 위해 멈추지 않고 실행됨

종합하면, 프롬프트는 다음과 같을 수 있습니다:

1/schedule every hour: check the project-feedback channel for bug reports. /goal: don't stop until every report found this run is triaged, actioned, and responded to. When fixing a bug, use a workflow to explore three solutions in parallel worktrees and have a judge adversarially review them.

코드 품질 유지

루프 출력의 품질은 이를 둘러싼 시스템에 달려 있습니다. 시스템을 설계할 때:

• 코드베이스 자체를 깔끔하게 유지하세요: Claude는 코드베이스에 이미 존재하는 패턴과 규칙을 따릅니다.
• Claude가 자신의 작업을 검증할 방법을 제공하세요: 스킬(skills)을 사용하여 사용자와 팀에게 "좋은 상태"가 무엇인지 인코딩하세요.
• 문서에 쉽게 접근할 수 있게 하세요: 프레임워크 및 라이브러리 문서는 최신 모범 사례를 제공합니다.
• 코드 리뷰를 위해 두 번째 에이전트를 사용하세요: 새로운 맥락을 가진 리뷰어는 편향이 적고 주 에이전트의 추론에 영향을 받지 않습니다. 내장된 \/code-review`` 스킬이나 Github용 Code Review를 사용할 수 있습니다.

개별 결과가 기준을 충족하지 못할 때, 개별 문제를 고치는 데 그치지 말고 모든 향후 반복을 위해 시스템을 개선할 수 있도록 인코딩하세요.

토큰 사용량 관리

토큰 사용량을 관리하려면 루프에 명확한 경계가 있어야 합니다:

• 작업에 적합한 기본 요소와 모델을 선택하세요: 작은 작업에 여러 에이전트나 루프가 필요하지 않습니다. 일부 작업은 더 저렴하고 빠른 모델을 사용할 수 있습니다.
• 명확한 성공 및 중지 기준을 정의하세요: "완료"가 무엇인지 구체적으로 정의하여 Claude가 (너무 이르지 않게) 더 빨리 솔루션에 도달할 수 있게 하세요.
• 대규모 실행 전에 파일럿을 진행하세요: 동적 워크플로우는 수백 개의 에이전트를 생성할 수 있습니다. 더 작은 작업 단위에서 먼저 사용량을 가늠하세요.
• 결정론적 작업에는 스크립트를 사용하세요: 스크립트를 실행하는 것이 단계를 추론하는 것보다 저렴합니다. 예를 들어, PDF 스킬은 Claude가 매번 실행하는 양식 작성 스크립트를 제공할 수 있으며, 코드를 매번 새로 유도할 필요가 없습니다.
• 필요한 것보다 더 자주 루틴을 실행하지 마세요: 간격을 모니터링 대상이 변경되는 빈도에 맞추세요.
• 사용량을 검토하세요: \/usage` 명령은 스킬, 하위 에이전트 및 MCP별 최근 사용량을 분석합니다. 인수 없이 \/goal\을 실행하면 지금까지의 턴 수와 토큰 사용량을 보여줍니다. \/workflows\`는 각 에이전트의 토큰 사용량을 보여주며 언제든지 에이전트를 중지할 수 있습니다.

시작하기

요약하자면:

루프 유형

위임하는 것

사용 시기

활용 도구

턴 기반

검증(확인)

탐색하거나 결정할 때

사용자 정의 검증 스킬

목표 기반

중지 조건

완료 상태가 무엇인지 알 때

/goal

시간 기반

트리거

작업이 프로젝트 외부에서 일정에 따라 발생할 때

/loop, /schedule

프로액티브

프롬프트

작업이 반복적이고 잘 정의되어 있을 때

위 모든 것 + 동적 워크플로우

루프를 시작하려면 이미 하고 있는 작업을 살펴보세요. 병목 현상이 발생하는 하나의 작업을 선택하고 어떤 부분을 위임할 수 있을지 물어보세요: 검증 확인을 작성할 수 있나요? 목표가 충분히 명확한가요? 작업이 일정에 따라 들어오나요?

아이디어가 생기면 루프를 실행하고, 어디서 막히거나 과도하게 확장되는지 관찰한 후, 반복하는 것을 두려워하지 마세요.

더 자세한 내용은 병렬 에이전트 실행에 관한 Claude Code 문서와 루프(loop), 일정(schedule), 목표(goal), 동적 워크플로우(dynamic workflows) 페이지를 참조하세요.

이 글은 @delba_oliveira가 작성했습니다.