장시간 실행 에이전트를 위한 효과적인 하네스 구성법

AI 에이전트의 역량이 높아지면서, 개발자들은 에이전트에게 수 시간, 나아가 수일이 걸리는 복잡한 작업을 맡기기 시작했습니다. 하지만 여러 컨텍스트 윈도우에 걸쳐 에이전트가 꾸준히 진전을 이루도록 하는 문제는 아직 해결되지 않았습니다.

장시간 실행 에이전트의 핵심 난제는, 에이전트가 불연속적인 세션 단위로 작업해야 하며, 새 세션이 시작될 때마다 이전 세션의 기억이 완전히 사라진다는 점입니다. 교대 근무를 하는 엔지니어 팀을 떠올려 보세요. 새로 투입되는 엔지니어가 이전 교대 근무자가 무엇을 했는지 전혀 모르는 상황과 같습니다. 컨텍스트 윈도우에는 한계가 있고, 대부분의 복잡한 프로젝트는 단일 윈도우 안에서 완료할 수 없으므로, 코딩 세션 간의 연속성을 확보할 수단이 필요합니다.

이 문제를 해결하기 위해, Claude Agent SDK가 여러 컨텍스트 윈도우에 걸쳐 효과적으로 작업할 수 있도록 두 가지 접근 방식을 개발했습니다. 첫 번째 실행에서 환경을 설정하는 초기화 에이전트(initializer agent), 그리고 매 세션마다 점진적으로 진전을 이루면서 다음 세션을 위한 명확한 산출물을 남기는 코딩 에이전트(coding agent)입니다. 코드 예제는 함께 제공되는 퀵스타트에서 확인할 수 있습니다.

장시간 실행 에이전트 문제

Claude Agent SDK는 코딩은 물론, 도구를 활용한 맥락 수집·계획·실행이 필요한 다양한 작업에 능숙한 범용 에이전트 하네스입니다. 컴팩션(compaction)과 같은 컨텍스트 관리 기능을 갖추고 있어, 컨텍스트 윈도우를 소진하지 않으면서 작업을 계속할 수 있습니다. 이론적으로는, 이 구조만으로도 에이전트가 임의로 긴 시간 동안 유용한 작업을 수행할 수 있어야 합니다.

그러나 컴팩션만으로는 부족합니다. Claude Agent SDK 위에서 Opus 4.5 같은 최신 코딩 모델을 여러 컨텍스트 윈도우에 걸쳐 반복 실행하더라도, "claude.ai 클론을 만들어 줘"처럼 고수준 프롬프트만 주면 프로덕션 수준의 웹 앱을 완성하기 어렵습니다.

Claude의 실패는 두 가지 패턴으로 나타났습니다. 첫 번째로, 에이전트가 한 번에 너무 많은 것을 하려는 경향, 즉 앱 전체를 한 번에 완성하려는 시도입니다. 이렇게 되면 구현 도중 컨텍스트가 소진되어, 다음 세션에서는 기능이 절반만 구현되고 문서화도 안 된 상태로 시작하게 됩니다. 결국 에이전트가 이전 상황을 추측해야 하고, 기본적인 앱 동작을 복구하는 데만 상당한 시간을 소모합니다. 컴팩션을 사용하더라도 다음 에이전트에게 항상 명확한 지시가 전달되지는 않기 때문에 이 문제가 발생합니다.

두 번째 실패 유형은 주로 프로젝트 후반부에 나타났습니다. 일부 기능이 이미 구현된 뒤, 이후 세션의 에이전트가 주변을 둘러보고 진전이 있었다는 사실만 확인하곤 작업이 끝났다고 판단해 버리는 것입니다.

이 문제는 두 부분으로 나눌 수 있습니다. 먼저, 주어진 프롬프트가 요구하는 모든 기능의 토대를 마련하는 초기 환경을 구성해, 에이전트가 단계별·기능별로 작업할 수 있도록 해야 합니다. 다음으로, 각 에이전트가 목표를 향해 점진적으로 진전을 이루면서, 세션이 끝날 때 환경을 깔끔한 상태로 남기도록 프롬프트해야 합니다. "깔끔한 상태"란 메인 브랜치에 병합해도 될 수준의 코드를 의미합니다. 주요 버그가 없고, 코드가 정돈되어 있으며 문서화가 잘 되어 있어서, 다른 개발자가 별도의 정리 작업 없이 바로 새 기능 개발에 착수할 수 있는 상태입니다.

내부 실험 과정에서 이러한 문제를 해결하기 위해 두 가지 접근 방식을 도입했습니다.

1. 초기화 에이전트: 첫 번째 에이전트 세션에서는 초기 환경 설정을 지시하는 전용 프롬프트를 사용합니다. 여기서 init.sh 스크립트, 에이전트의 작업 이력을 기록하는 claude-progress.txt 파일, 그리고 추가된 파일을 보여주는 초기 git 커밋을 생성합니다.
2. 코딩 에이전트: 이후 모든 세션에서는 모델에게 점진적으로 진전을 이룬 뒤, 구조화된 업데이트를 남기도록 요청합니다.¹

여기서 핵심 통찰은, 새로운 컨텍스트 윈도우로 시작하는 에이전트가 현재 작업 상태를 빠르게 파악할 수 있는 방법을 찾는 것이었습니다. claude-progress.txt 파일과 git 히스토리의 조합이 이를 가능하게 합니다. 이러한 방식은 우수한 소프트웨어 엔지니어들이 매일 실천하는 습관에서 영감을 받았습니다.

환경 관리

최근 업데이트된 Claude 4 프롬프팅 가이드에서, 다중 컨텍스트 윈도우 워크플로에 대한 모범 사례를 공유했습니다. 여기에는 "첫 번째 컨텍스트 윈도우에만 별도의 프롬프트를 사용하는" 하네스 구조가 포함됩니다. 이 "별도의 프롬프트"는 초기화 에이전트에게 이후 코딩 에이전트가 효과적으로 작업하는 데 필요한 모든 컨텍스트를 갖춘 환경을 구성하도록 요청합니다. 아래에서는 이러한 환경의 주요 구성 요소를 더 깊이 살펴봅니다.

기능 목록

에이전트가 앱을 한 번에 완성하려 하거나, 프로젝트가 완료되었다고 조기에 판단하는 문제를 해결하기 위해, 초기화 에이전트에게 사용자의 초기 프롬프트를 확장한 포괄적인 기능 요구사항 파일을 작성하도록 프롬프트했습니다. claude.ai 클론 예제에서는 "사용자가 새 채팅을 열고, 질문을 입력하고, Enter를 누르면 AI 응답이 표시된다"와 같은 항목으로 200개 이상의 기능이 작성되었습니다. 이 기능들은 모두 초기에 "실패" 상태로 표시해, 이후 코딩 에이전트가 전체 기능의 완성 모습을 명확히 파악할 수 있게 했습니다.

{
    "category": "functional",
    "description": "New chat button creates a fresh conversation",
    "steps": [
      "Navigate to main interface",
      "Click the 'New Chat' button",
      "Verify a new conversation is created",
      "Check that chat area shows welcome state",
      "Verify conversation appears in sidebar"
    ],
    "passes": false
  }

코딩 에이전트에게는 이 파일을 수정할 때 passes 필드의 상태 값만 변경하도록 프롬프트하며, "테스트를 삭제하거나 수정하는 행위는 기능 누락이나 버그로 이어질 수 있으므로 절대 허용되지 않습니다"와 같은 강한 어조의 지시를 사용합니다. 여러 실험을 거쳐, 이 파일의 형식으로 JSON을 채택했습니다. Markdown 파일에 비해 모델이 JSON 파일의 내용을 부적절하게 변경하거나 덮어쓸 가능성이 낮기 때문입니다.

점진적 진행

이러한 초기 환경 스캐폴딩이 갖춰진 상태에서, 코딩 에이전트에게 한 번에 하나의 기능만 작업하도록 지시했습니다. 이 점진적 접근 방식은 에이전트가 한꺼번에 모든 것을 하려는 경향을 해소하는 데 결정적이었습니다.

점진적 방식을 도입한 후에도, 코드 변경 후 환경을 깔끔한 상태로 유지하는 것이 여전히 중요합니다. 실험 결과, 모델에게 진행 상황을 서술적인 커밋 메시지와 함께 git에 커밋하고, 진행 파일에 요약을 기록하도록 요청하는 것이 가장 효과적이었습니다. 이를 통해 모델은 git을 활용해 잘못된 코드 변경을 되돌리고, 정상 동작하는 코드 상태를 복구할 수 있었습니다.

이러한 접근 방식은 효율성도 높여주었습니다. 에이전트가 이전 상황을 추측하거나, 기본적인 앱 동작 복구에 시간을 낭비할 필요가 없어졌기 때문입니다.

테스트

마지막으로 관찰된 주요 실패 유형은, Claude가 적절한 테스트 없이 기능을 완료로 표시하는 경향이었습니다. 명시적으로 프롬프트하지 않으면, Claude는 코드 변경 후 유닛 테스트나 개발 서버에 대한 curl 명령어로 테스트를 수행하면서도, 기능이 end-to-end로 동작하지 않는다는 사실을 인지하지 못했습니다.

웹 앱 개발의 경우, 브라우저 자동화 도구를 사용하고 실제 사용자처럼 테스트하라고 명시적으로 프롬프트하면, Claude는 대체로 end-to-end 기능 검증을 잘 수행했습니다.

이러한 테스트 도구를 제공하자 성능이 크게 향상되었습니다. 코드만 봐서는 발견하기 어려운 버그를 에이전트가 직접 식별하고 수정할 수 있었기 때문입니다.

아직 몇 가지 한계는 남아 있습니다. Claude의 비전 능력과 브라우저 자동화 도구의 제약으로 인해 모든 종류의 버그를 잡아내기는 어렵습니다. 예를 들어, Claude는 Puppeteer MCP를 통해 브라우저 네이티브 alert 모달을 볼 수 없어, 이러한 모달에 의존하는 기능은 상대적으로 버그가 많았습니다.

작업 파악

위의 모든 요소가 갖춰진 상태에서, 각 코딩 에이전트는 현재 상황을 파악하기 위해 일련의 단계를 수행하도록 프롬프트됩니다. 기본적인 단계도 있지만, 여전히 효과적입니다.

1. pwd를 실행해 작업 중인 디렉터리를 확인합니다. 이 디렉터리 내의 파일만 수정할 수 있습니다.
2. git 로그와 진행 파일을 읽어 최근 작업 내용을 파악합니다.
3. 기능 목록 파일을 읽고, 아직 완료되지 않은 기능 중 우선순위가 가장 높은 항목을 선택합니다.

이 접근 방식은 매 세션마다 Claude의 토큰을 절약해 줍니다. 코드 테스트 방법을 스스로 파악할 필요가 없기 때문입니다. 또한 초기화 에이전트에게 개발 서버를 실행하는 init.sh 스크립트를 작성하게 하고, 새 기능 구현 전에 기본적인 end-to-end 테스트를 실행하도록 하는 것이 효과적입니다.

claude.ai 클론의 경우, 에이전트가 항상 로컬 개발 서버를 시작하고 Puppeteer MCP를 사용해 새 채팅을 열고, 메시지를 보내고, 응답을 받는 과정을 거쳤습니다. 이를 통해 앱이 비정상 상태로 남겨졌는지 빠르게 확인하고, 기존 버그를 즉시 수정할 수 있었습니다. 만약 에이전트가 이 확인 없이 바로 새 기능을 구현하기 시작했다면, 문제는 오히려 악화되었을 것입니다.

이 모든 것이 적용된 일반적인 세션은 다음과 같은 어시스턴트 메시지로 시작됩니다.

[Assistant] I'll start by getting my bearings and understanding the current state of the project.
[Tool Use] <bash - pwd>
[Tool Use] <read - claude-progress.txt>
[Tool Use] <read - feature_list.json>
[Assistant] Let me check the git log to see recent work.
[Tool Use] <bash - git log --oneline -20>
[Assistant] Now let me check if there's an init.sh script to restart the servers.
<Starts the development server>
[Assistant] Excellent! Now let me navigate to the application and verify that some fundamental features are still working.
<Tests basic functionality>
[Assistant] Based on my verification testing, I can see that the fundamental functionality is working well. The core chat features, theme switching, conversation loading, and error handling are all functioning correctly. Now let me review the tests.json file more comprehensively to understand what needs to be implemented next.
<Starts work on a new feature>

향후 과제

이번 연구는 장기 실행 에이전트 하네스에서 모델이 여러 컨텍스트 윈도우에 걸쳐 점진적으로 진행할 수 있도록 하는 하나의 해결책을 제시합니다. 다만, 여전히 풀어야 할 과제가 남아 있습니다.

가장 주목할 만한 질문은, 범용 코딩 에이전트 하나가 모든 상황에서 최적의 성능을 내는지, 아니면 멀티 에이전트 아키텍처를 통해 더 나은 성과를 달성할 수 있는지입니다. 테스트 에이전트, QA 에이전트, 코드 정리 에이전트 같은 전문화된 에이전트가 소프트웨어 개발 라이프사이클의 세부 작업을 더 효과적으로 수행할 수 있다는 추론은 충분히 합리적입니다.

또한 이번 데모는 풀스택 웹 앱 개발에 최적화되어 있습니다. 향후에는 이러한 발견을 다른 분야로 확장하는 것이 중요한 방향이 될 것입니다. 여기서 얻은 교훈의 일부 또는 전부는 과학 연구나 금융 모델링 등 장기 실행이 필요한 에이전트 기반 작업에도 적용할 수 있을 것으로 보입니다.

감사의 글

작성: Justin Young. David Hershey, Prithvi Rajasakeran, Jeremy Hadfield, Naia Bouscal, Michael Tingley, Jesse Mu, Jake Eaton, Marius Buleandara, Maggie Vo, Pedram Navid, Nadine Yasser, Alex Notov에게 기여에 대한 특별한 감사를 전합니다.

이 연구는 Claude가 장기간 자율적으로 소프트웨어 엔지니어링을 안전하게 수행할 수 있도록 기여한 Anthropic 내 여러 팀, 특히 code RL 팀과 Claude Code 팀의 공동 노력으로 이루어졌습니다. 관심 있는 분들의 지원을 환영하며, anthropic.com/careers에서 지원할 수 있습니다.

각주

1. 여기서 이들을 별도의 에이전트로 지칭하는 이유는 초기 사용자 프롬프트가 서로 다르기 때문입니다. 시스템 프롬프트, 도구 세트, 전체 에이전트 하네스는 동일합니다.