원본 글 Anthropic의 Effective harnesses for long-running agents를 보고 정리한 내용.

We developed a two-fold solution to enable the Claude Agent SDK to work effectively across many context windows:

1. an initializer agent that sets up the environment on the first run
   예시 : Survey the existing codebase / Write feature_list.json / Write init.sh / Write claude-progress.txt / Initial commit
2. coding agent that is tasked with making incremental progress in every session, while leaving clear artifacts for the next session.
   예시 : Get your bearings (Collect non-passed feature list) / Pick the lowest-priority unverified item / For each verification item: Diagnose → Fix → Re-test / Test suite requirements for verification items V003–V006 / Pipeline verification procedures / Commit after each verified item / Update claude-progress.txt

클로드의 실패가 나타나는 2가지 유형

1. 에이전트가 한 번에 너무 많은 일을 하려고 하는 경우. One-shot으로 앱을 개발하려는 시도.
   실행 과정에서 모델이 컨텍스트를 벗어나도록 한다. 다음 세션이 절반 정도 실패한 상태의 구현에서 시작하게 됨. 기본 앱을 다시 실행하도록 고치는데 매우 많은 시간을 할애하게 됨. 이런 방식이 Compaction 에서도 발생하게 됨.
2. 프로젝트 이후에 발생하는 유형. 어떤 기능들이 이미 빌드된 뒤, 나중에 작업을 하는 에이전트는 이 진척을 보고 작업 완료를 선언하게 됨.
   이는 문제를 2가지 부분으로 분할함.
   a. 프롬프트를 통해 요구하는 모든 기능들의 기반이 되는 설정들을 구성해야 한다. 그래야 에이전트가 단계적으로 각 기능들을 작업할 수 있기 때문임.
   b. 그리고 각 에이전트가 점진적인 진척을 이루어나가면서 Clean State 상태로 환경을 남겨두도록 해야 한다. 여기서 Clean state란 Main branch에 병합하기 적절한 상태로 치명적인 버그도 없고, 연관성 없는 코드 덩어리 등을 정리할 필요 없이 개발자가 새로운 기능 개발에 쉽게 착수할 수 있는 일반적인 상태를 의미한다.

Anthropic의 경우 이러한 문제를 2가지 부분의 솔루션으로 해결하였음.

1. Initializer agent : 모델에게 초기 환경을 구성하도록 특화된 프롬프트를 실행하는 에이전트를 의미함. init.sh 스크립트와 claude-progress.txt 파일과 최초의 git commit이 무엇이 추가 되어야 하는지를 보여줌. 즉, 이러한 초기 구성을 제공하는 것이 역할이다.
2. Coding agent : 모든 차후의 세션들은 모델에게 점진적으로 프로젝트를 만들어갈 것을 요구함. 그리고 각 세션의 결과는 구조화된 갱신을 남기게 된다.

여기서 찾을 수 있는 핵심은 에이전트가 새로운 컨텍스트 윈도우에서 작업 상태를 빠르게 이해하도록 하는 것이다. 이때 claude-progress.txt 파일을 이용하고 부가적으로 git history를 이용한다.

환경 관리

Claude 4 프롬프팅 가이드를 참고..
베스트 프랙티스 사례에서도 최초 프롬프트는 향후 에이전트들이 효율적으로 일할 수 있도록 환경을 구성하도록 한다. 이러한 구성요소는 무엇이 있는가?

1. Feature List
   에이전트에게 종합적인 기능 요구사항을 파일에 작성하도록 한다. 이런 종류의 초기 기능 요구사항들은 모두 초기 상태가 failing이다. 향후 에이전트들이 이를 통해 현재 구현 안되거나 테스트 안된 기능들을 파악한다.

{
    "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 뿐이다. 다음과 같은 프롬프트가 사용되어야 한다.

|  “It is unacceptable to remove or edit tests because this could lead to missing or buggy functionality.”

JSON이 마크다운 파일보다 부적절한 수정이 이루어질 확률이 더 낮은 결과를 보여주었다.

2. Incremental progress
   초기 환경 스캐폴딩이 제공된 다음 각 반복에서 coding agent는 한 번에 한 기능을 담당하여 개발하게 된다. 이러한 단계적인 접근 방식이 에이전트가 한 번에 너무 많은 일을 하려는 것을 방지하는데 매우 중요한 역할을 한다.
   한 번 이렇게 단계적으로 수행하게 되면, 모델이 코드를 수정한 뒤 환경을 Clean state로 남겨두는 것이 매우 중요해진다.
   이러한 행동을 유도하는 가장 좋은 방법은 모델에게 수행한 내용을 기반으로 git commit을 하게 하고, claude-progress.txt 파일에 한 내용을 적게 하는 것이다. 이렇게 하면 모델이 git revert를 사용하여 나쁜 코드 변경을 제거하고 작업 상태를 회복시킬 수 있다.
   이런 명확한 기록이 에이전트가 이전에 발생한 일들을 추측하지 않아도 되기 때문에 매우 유용하다.

3. Testing
   최종적인 중요한 실패의 유형 중 하나는 Claude가 적절한 테스트 없이 기능을 완성했다고 표시하는 것이다. 명시적인 프롬프팅없이 Claude는 코드를 수정하고 단위 테스트나 cURL을 사용하여 테스트했지만, 이러한 기능이 전체적으로 제대로 작동하지 않는다는 사실을 인지하지 못하는 경우가 많았다.
   Web App을 빌드하는 경우, 명시적으로 브라우저 자동화 도구를 사용하여 인간이 일으킬 수 있는 모든 행위들을 테스트하도록 프롬프트 작성했고 Calude는 거의 잘 수행했다.

   Claude에게 이런 테스팅 도구를 제공하는 것은 성능을 극적으로 높일 수 있는 방법이다. 따라서 코드 외에도 이런 에러를 발견할 수 있는 방법이 제공되어야 한다.
   (Puppeteer MCP Server 같은 것들.)

   Claude의 시각적 능력이나 브라우저 자동화 도구가 애초에 버그를 발견하기 어렵게 되어 있는 경우는 여전히 한계이다.
   예를 들어 Claude는 브라우저 네이티브 경고 모달을 Puppeteer MCP를 통해 볼 수가 없다.
   그리고 이러한 모달에 의존하는 기능은 결과적으로 버그가 더 많이 발생하는 경향이 있었다.

이해시키기.

위 모든 사항들이 충족되면, 모든 코딩 에이전트는 다음과 같은 일련의 문장들을 통해 실행되도록 프롬프트된다.

Prompt	Description
1. Run pwd to see the directory you’re working in. You’ll only be able to edit files in this directory.	현재 작업 디렉토리를 확인하고 이곳의 파일만 수정하라.
2. Read the git logs and progress files to get up to speed on what was recently worked on.	git logs와 Progress 파일을 확인하고 최근 발생한 일들에 대해 이해하라.
3. Read the features list file and choose the highest-priority feature that’s not yet done to work on.	기능 목록 파일을 읽고 현재 완료되지 않은 가장 높은 우선순위의 기능을 선택하라.

이렇게 하면 에이전트가 코드를 어떻게 테스트해야하는지 알아내도 되지 않아서 토큰을 아낄 수 있다. 그리고 이런 방식은 Initializer agent가 개발 서버를 실행하기 위한 init.sh를 작성하거나 새 기능을 구현하기 전 기초적인 End-to-End 테스트를 해볼 수 있도록 돕는다.

예를 들어서 에이전트가 항상 로컬 개발 서버를 실행하고, Puppeteer MCP로 새로운 chat을 사용하도록 하고, 메세지를 보낸 뒤 응답을 확인하는 것들을 수행하게 한다. 이런 방식으로 Claude가 애플리케이션이 마지막으로 오류 상태에서 종료되었는지 체크할 수 있게 된다. 그리고 즉각적으로 존재하는 버그를 수정하게 한다.
만약 에이전트가 이런 행동을 하지 않고 새로운 기능을 개발하게 된다면, 문제를 더 심각하게 만들 수 있다.

이러한 점을 잘 보여주는 예시는 다음과 같다. 다음 어시스턴트 메세지를 출력하게 했다.

[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>