여러 컨텍스트 윈도우에 걸쳐 장기 실행 AI 에이전트가 안정적으로 점진적 진전을 이루도록 돕는 환경 구성, 테스트, 진행 관리 방법을 소개합니다.
AI 에이전트의 역량이 향상됨에 따라 개발자들은 몇 시간, 심지어 며칠에 걸친 작업이 필요한 복잡한 과업을 맡기려는 경우가 늘고 있습니다. 그러나 여러 컨텍스트 윈도우에 걸쳐 에이전트가 일관되게 진전을 이루게 하는 일은 여전히 미해결 문제입니다.
장기 실행 에이전트의 핵심 과제는 개별 세션에서 작업해야 하며, 각각의 새 세션은 이전에 일어난 일을 전혀 기억하지 못한 채 시작한다는 점입니다. 교대 근무를 하는 엔지니어들이 배치된 소프트웨어 프로젝트를 상상해 보세요. 새 엔지니어는 이전 교대 근무에서 무슨 일이 있었는지 전혀 기억하지 못한 채 도착합니다. 컨텍스트 윈도우는 제한되어 있고 대부분의 복잡한 프로젝트는 하나의 윈도우 안에서 완료할 수 없으므로, 에이전트에는 코딩 세션 간의 간극을 메울 방법이 필요합니다.
우리는 Claude Agent SDK가 여러 컨텍스트 윈도우에 걸쳐 효과적으로 작업할 수 있도록 두 가지 해법을 개발했습니다. 첫 실행에서 환경을 설정하는 초기화 에이전트와, 매 세션에서 점진적으로 진전하는 동시에 다음 세션을 위한 명확한 산출물을 남기는 코딩 에이전트입니다. 함께 제공되는 빠른 시작 가이드에서 코드 예제를 확인할 수 있습니다.
Claude Agent SDK는 코딩뿐 아니라 모델이 도구를 사용해 컨텍스트를 수집하고, 계획하고, 실행해야 하는 다른 작업에도 능숙한 강력한 범용 에이전트 하니스입니다. 에이전트가 컨텍스트 윈도우를 소진하지 않고 과업을 수행할 수 있게 하는 압축 같은 컨텍스트 관리 기능을 갖추고 있습니다. 이론적으로는 이러한 구성이라면 에이전트가 임의로 긴 시간 동안 유용한 작업을 계속할 수 있어야 합니다.
그러나 압축만으로는 충분하지 않습니다. 기본 설정 그대로라면 Claude Agent SDK에서 여러 컨텍스트 윈도우에 걸쳐 루프로 실행되는 Opus 4.5 같은 최첨단 코딩 모델조차 “ claude.ai의 복제본을 만들어라”와 같은 고수준 프롬프트만 주어졌을 때 프로덕션 품질의 웹 앱을 구축하는 데 실패합니다.
Claude의 실패는 두 가지 패턴으로 나타났습니다. 첫째, 에이전트는 한 번에 너무 많은 일을 하려는 경향이 있었습니다. 사실상 앱을 단 한 번에 구현하려고 시도한 것입니다. 이 때문에 모델은 구현 도중에 컨텍스트를 소진하는 경우가 많았고, 다음 세션은 기능이 절반만 구현되고 문서화되지 않은 상태에서 시작해야 했습니다. 그러면 에이전트는 무슨 일이 있었는지 추측해야 했고, 기본 앱을 다시 작동하게 하려는 데 상당한 시간을 썼습니다. 다음 에이전트에 항상 완벽히 명확한 지시를 전달하지는 못하는 압축 기능을 사용해도 이런 일은 발생합니다.
두 번째 실패 모드는 프로젝트 후반에 자주 발생했습니다. 일부 기능이 이미 구축된 뒤, 이후 에이전트 인스턴스가 주변을 살펴보고 진전이 이루어졌음을 확인한 다음 작업이 끝났다고 선언하는 것입니다.
이 문제는 두 부분으로 나뉩니다. 첫째, 주어진 프롬프트가 요구하는 모든 기능의 토대를 마련하는 초기 환경을 설정하여, 에이전트가 단계별로 그리고 기능별로 작업할 수 있게 해야 합니다. 둘째, 각 에이전트가 목표를 향해 점진적으로 진전하는 동시에 세션 종료 시 환경을 깨끗한 상태로 남기도록 프롬프트해야 합니다. 여기서 “깨끗한 상태”란 메인 브랜치에 병합하기에 적합한 코드 상태를 뜻합니다. 중대한 버그가 없고, 코드가 정돈되어 잘 문서화되어 있으며, 일반적으로 개발자가 관련 없는 난장판을 먼저 정리할 필요 없이 새 기능 작업을 쉽게 시작할 수 있는 상태입니다.
내부 실험에서는 두 부분으로 된 해법으로 이러한 문제를 해결했습니다.
init.sh 스크립트, 에이전트가 수행한 작업의 로그를 보관하는 claude-progress.txt 파일, 그리고 추가된 파일을 보여 주는 초기 git 커밋이 포함됩니다.여기서 핵심 통찰은 새 컨텍스트 윈도우로 시작할 때 에이전트가 작업 상태를 빠르게 이해할 방법을 찾는 것이었습니다. 이는 git 이력과 함께 claude-progress.txt 파일을 사용해 달성됩니다. 이러한 실천 방식은 효과적인 소프트웨어 엔지니어가 매일 하는 일을 이해하는 데서 영감을 얻었습니다.
업데이트된 Claude 4 프롬프팅 가이드에서는 “맨 처음 컨텍스트 윈도우에 다른 프롬프트를 사용”하는 하니스 구조를 포함해 다중 컨텍스트 윈도우 워크플로를 위한 몇 가지 모범 사례를 소개했습니다. 이 “다른 프롬프트”는 초기화 에이전트에게 이후의 코딩 에이전트가 효과적으로 작업하는 데 필요한 모든 컨텍스트를 갖춘 환경을 설정하도록 요청합니다. 여기에서는 그러한 환경의 몇 가지 핵심 구성 요소를 더 자세히 살펴봅니다.
에이전트가 앱을 한 번에 구현하려 하거나 프로젝트가 완료되었다고 성급하게 판단하는 문제를 해결하기 위해, 초기화 에이전트에게 사용자의 최초 프롬프트를 확장한 종합적인 기능 요구 사항 파일을 작성하도록 프롬프트했습니다. claude.ai 복제 예제에서는 “사용자가 새 채팅을 열고, 질의를 입력하고, 엔터를 누르면 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 명령을 사용해 테스트까지 했지만, 기능이 엔드투엔드로 작동하지 않는다는 점을 인식하지 못했습니다.
웹 앱을 구축하는 경우, Claude는 브라우저 자동화 도구를 사용하고 인간 사용자가 하듯 모든 테스트를 수행하라는 명시적 프롬프트를 받은 뒤에는 대체로 기능을 엔드투엔드로 잘 검증했습니다.
Claude가 claude.ai 복제본을 테스트하면서 Puppeteer MCP 서버를 통해 촬영한 스크린샷.
이러한 종류의 테스트 도구를 Claude에 제공하면 성능이 크게 개선되었습니다. 에이전트가 코드만으로는 명확하지 않은 버그를 식별하고 수정할 수 있었기 때문입니다.
Claude의 시각 기능 및 브라우저 자동화 도구의 한계로 인해 모든 종류의 버그를 식별하기 어렵다는 문제는 여전히 남아 있습니다. 예를 들어 Claude는 Puppeteer MCP를 통해 브라우저 네이티브 경고 모달을 볼 수 없으며, 그 결과 이러한 모달에 의존하는 기능은 버그가 더 많은 경향이 있었습니다.
위의 모든 요소가 갖춰진 상태에서, 각 코딩 에이전트에는 현재 상황을 파악하기 위한 일련의 단계를 수행하도록 프롬프트합니다. 일부는 매우 기본적이지만 여전히 유용합니다.
pwd를 실행해 작업 중인 디렉터리를 확인합니다. 이 디렉터리의 파일만 편집할 수 있습니다.이 접근법은 Claude가 코드를 테스트하는 방법을 알아낼 필요가 없으므로 매 세션에서 토큰을 절약해 줍니다. 또한 초기화 에이전트에게 개발 서버를 실행할 수 있는 init.sh 스크립트를 작성하게 하고, 새 기능을 구현하기 전에 기본적인 엔드투엔드 테스트를 수행하게 하는 것도 도움이 됩니다.
claude.ai 복제본의 경우, 이는 에이전트가 항상 로컬 개발 서버를 시작하고 Puppeteer MCP를 사용해 새 채팅을 시작하고, 메시지를 전송하고, 응답을 받는다는 의미였습니다. 이를 통해 Claude는 앱이 손상된 상태로 남겨졌는지 빠르게 파악하고, 기존 버그를 즉시 수정할 수 있었습니다. 에이전트가 대신 새 기능 구현을 시작했다면 문제를 더 악화시켰을 가능성이 큽니다.
이 모든 점을 고려하면, 일반적인 세션은 다음과 같은 어시스턴트 메시지로 시작합니다.
[Assistant] 먼저 현재 상황을 파악하고 프로젝트의 현재 상태를 이해하겠습니다.
[Tool Use] <bash - pwd>
[Tool Use] <read - claude-progress.txt>
[Tool Use] <read - feature_list.json>
[Assistant] 최근 작업을 확인하기 위해 git 로그를 살펴보겠습니다.
[Tool Use] <bash - git log --oneline -20>
[Assistant] 이제 서버를 다시 시작할 수 있는 init.sh 스크립트가 있는지 확인하겠습니다.
<개발 서버 시작>
[Assistant] 좋습니다! 이제 애플리케이션으로 이동해 몇 가지 기본 기능이 여전히 작동하는지 확인하겠습니다.
<기본 기능 테스트>
[Assistant] 검증 테스트에 따르면 기본 기능이 잘 작동하고 있습니다. 핵심 채팅 기능, 테마 전환, 대화 불러오기, 오류 처리가 모두 올바르게 작동합니다. 이제 다음에 구현해야 할 사항을 이해하기 위해 tests.json 파일을 더 종합적으로 검토하겠습니다.
<새 기능 작업 시작>
에이전트 실패 모드와 해법
| 문제 | 초기화 에이전트 동작 | 코딩 에이전트 동작 |
|---|---|---|
| Claude가 전체 프로젝트의 성공을 너무 일찍 선언합니다. | 입력 명세를 바탕으로 엔드투엔드 기능 설명 목록이 담긴 구조화된 JSON 파일인 기능 목록 파일을 설정합니다. | 세션 시작 시 기능 목록 파일을 읽습니다. 작업을 시작할 단일 기능을 선택합니다. |
| Claude가 버그 또는 문서화되지 않은 진전이 있는 상태로 환경을 남깁니다. | 초기 git 저장소와 진행 메모 파일을 작성합니다. | 진행 메모 파일과 git 커밋 로그를 읽고, 문서화되지 않은 버그를 잡기 위해 개발 서버에서 기본 테스트를 실행하며 세션을 시작합니다. git 커밋과 진행 업데이트를 작성하며 세션을 종료합니다. |
| Claude가 기능을 성급하게 완료로 표시합니다. | 기능 목록 파일을 설정합니다. | 모든 기능을 자체 검증합니다. 신중한 테스트 후에만 기능을 “통과”로 표시합니다. |
| Claude가 앱 실행 방법을 알아내는 데 시간을 써야 합니다. | 개발 서버를 실행할 수 있는 init.sh 스크립트를 작성합니다. | init.sh를 읽으며 세션을 시작합니다. |
장기 실행 AI 에이전트에서 흔히 발생하는 네 가지 실패 모드와 해법을 요약합니다.
이 연구는 모델이 여러 컨텍스트 윈도우에 걸쳐 점진적 진전을 이루도록 하는 장기 실행 에이전트 하니스의 가능한 해법 집합 하나를 보여 줍니다. 그러나 여전히 미해결 질문이 남아 있습니다.
특히 단일 범용 코딩 에이전트가 컨텍스트 전반에서 가장 뛰어난 성능을 보이는지, 아니면 다중 에이전트 아키텍처를 통해 더 나은 성능을 달성할 수 있는지는 아직 분명하지 않습니다. 테스트 에이전트, 품질 보증 에이전트, 코드 정리 에이전트 같은 특화 에이전트가 소프트웨어 개발 수명 주기 전반의 하위 작업을 훨씬 더 잘 수행할 수 있다는 점은 타당해 보입니다.
또한 이 데모는 풀스택 웹 앱 개발에 최적화되어 있습니다. 향후 방향은 이러한 발견을 다른 분야로 일반화하는 것입니다. 예를 들어 과학 연구나 금융 모델링에 필요한 종류의 장기 실행 에이전트 작업에도 이러한 교훈의 일부 또는 전부를 적용할 수 있을 가능성이 큽니다.
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 전반의 여러 팀이 함께 기울인 노력의 결실이며, 특히 코드 RL 및 Claude Code 팀의 기여를 반영합니다. 기여에 관심 있는 지원자는 anthropic.com/careers에서 지원할 수 있습니다.