에이전틱 루프의 동작 원리

Claude Code는 한 번 답하고 끝나는 채팅이 아니라, 목표가 끝날 때까지 도구를 쓰고 결과를 보고 다음 행동을 고르는 프로그램입니다. 이 글은 그 순환, 즉 에이전틱 루프가 한 바퀴 돌 때 무슨 일이 일어나는지를 다룹니다. 읽고 나면 왜 먼저 읽는지, 왜 긴 대화에서 판단이 흐려지는지, 어디서 끼어들어야 하는지를 설명할 수 있습니다. 다음 글 「컨텍스트 윈도우 관리」로 이어집니다.

핵심 요약

• 한 번의 루프는 컨텍스트 수집, 작업 수행, 결과 검증의 세 단계이며 작업이 끝날 때까지 반복합니다.
• 모델이 판단하고 도구가 행동합니다. 도구 결과가 다시 모델에 들어가 다음 판단의 재료가 됩니다.
• 모든 도구 결과는 컨텍스트 윈도우에 쌓입니다. 터미널에 한 줄로 보여도 실제로는 수천 토큰입니다.
• 서브에이전트는 별도 컨텍스트에서 일하고 요약만 돌려줍니다.
• 사람은 권한 승인, 중단, 계획 검토, 증거 확인의 네 지점에서 개입합니다.

한 번의 루프에서 일어나는 일

공식 문서는 Claude Code가 작업을 받으면 컨텍스트 수집, 작업 수행, 결과 검증을 거친다고 설명합니다. 세 단계는 앞 단계에서 얻은 정보로 다음 단계를 정하면서 수십 번 이어집니다. "실패하는 테스트를 고쳐 주세요"라고 하면 테스트 실행, 오류 읽기, 관련 파일 검색, 파일 읽기, 편집, 테스트 재실행이 연달아 일어나는 식입니다.

이 순환을 굴리는 부품은 추론을 맡는 모델과 파일을 읽고 명령을 실행하는 도구입니다. Claude Code는 둘을 묶는 에이전트 하네스이며, 우리 8주차 교재의 개발 루프(플랜 모드 → 오토 모드 → 교차 체크 → 반복)는 같은 루프를 사람 쪽에서 본 모습입니다.

왜 "먼저 읽는가"

편집 전에 읽는 것은 습관이 아니라 도구의 규칙입니다. Edit 도구는 정규식이나 유사 매칭 없이 old_string을 new_string으로 정확히 바꾸며, 바꿀 문자열은 파일에 글자 하나 틀림없이 존재하고 정확히 한 번만 나타나야 합니다. 파일 내용을 모르면 이 조건을 만족하는 편집을 만들 수 없습니다. Write 도구도 기존 파일을 덮어쓸 때는 같은 대화에서 먼저 읽었어야 합니다.

검색(Glob·Grep)은 어디를 볼지 좁히고, 읽기는 지금 상태를 확정합니다. 우리 5주차 교재의 황금 문장 "원인 분석 → 최소 수정 → 변경 정리"는 이 순서를 사람이 요청문으로 강제하는 장치입니다.

컨텍스트가 쌓이는 방식

루프의 모든 결과는 컨텍스트 윈도우 하나에 누적됩니다. 시스템 프롬프트, CLAUDE.md, 자동 메모리, 스킬 설명, MCP 도구 이름이 세션 시작 전에 들어가고, 그 위에 내 요청, 읽은 파일 본문, 검색 결과, 명령 출력, Claude의 응답이 쌓입니다. 터미널에는 "Read auth.ts" 한 줄만 보여도 파일 수천 토큰이 그대로 들어갑니다.

한계에 가까워지면 오래된 도구 출력을 먼저 비우고 필요하면 대화를 요약합니다. 초반의 상세 지시는 사라질 수 있으므로 규칙은 CLAUDE.md에 두고 /context로 사용량을 확인합니다.

서브 에이전트로 루프를 나누기

큰 코드베이스 조사는 파일 읽기만으로 컨텍스트를 채웁니다. 서브에이전트에게 맡기면 자기만의 새 컨텍스트에서 읽고 요약만 돌려줍니다. "서브에이전트를 써서 토큰 갱신 흐름을 조사해 줘"처럼 요청하면 되고, model: haiku처럼 가벼운 모델을 지정하면 우리 6주차의 모델 나눠 쓰기(가볍게 쪼개기 → 강하게 구현 → 가볍게 요약)가 루프 안에서 구현됩니다.

사람이 개입해야 하는 지점

1. 권한 승인: 기본 모드에서는 편집과 셸 명령 전에 묻습니다. Shift+Tab으로 default, acceptEdits, plan을 순환합니다.
2. 중단: Esc는 실행 중인 도구 호출을 취소하고 다음 지시를 기다립니다.
3. 계획 검토: 복잡한 작업은 플랜 모드에서 조사와 제안을 먼저 받습니다.
4. 증거 확인: 우리 정지 규칙은 증거입니다. 테스트 출력, 실행 화면, 로그가 있어야 루프가 끝난 것이며, 우리 5주차 QA 체크리스트가 그 타이밍표입니다.

정리

• 루프는 수집·수행·검증의 반복이며 도구 결과가 다음 판단을 정합니다.
• 먼저 읽는 이유는 Edit이 정확 일치 교체이기 때문입니다.
• 규칙은 CLAUDE.md에, 진단은 /context로, 조사는 서브에이전트에.
• 사람은 승인·중단·계획·증거에서 개입합니다.

자주 묻는 질문