목차
이 글은 Anthropic 엔지니어링 블로그에 2025년 11월 26일 게재된 “Effective harnesses for long-running agents” 를 읽고, 내용을 정리한 글입니다. 원문: https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents
한 줄로 말하면 #
에이전트에 며칠짜리 일을 시키려면, 교대 근무자에게 남겨주는 ‘인수인계 노트’를 시스템에 박아둬야 한다.
어떤 문제를 해결하려 했나 #
claude.ai와 비슷한 클론을 만들겠다고 가정해봅시다. 기능 200개짜리 프로젝트입니다. 한 세션에 다 못 끝나고 며칠은 가야 해요.
문제는, 에이전트는 세션마다 기억이 사라진다는 점입니다.
1일차: “로그인 만들고, 채팅 UI 시작, 사이드바 절반 완성” 2일차: (다 잊은 상태) “어디서부터 시작하지?” → 처음부터 다시 보거나, 이미 한 일을 또 함
원문이 진단한 두 가지 실패 모드:
- 원샷 문제(One-shotting): 한 번에 다 끝내려 하다가 컨텍스트 다 쓰고 망가진 상태로 종료
- 조기 승리 선언: 진행 상황만 훑어보고 “거의 다 됐네, 끝!” 선언
해결책은 단순합니다. 사람 교대 근무자에게 주는 인수인계 문서를 에이전트용으로 만들어 주자.
해결책: 하네스(Harness) #
1. 두 에이전트 구조 — 초기화 에이전트 + 작업 에이전트 #
초기화 에이전트(딱 한 번 실행):
init.sh— 개발 서버 띄우는 스크립트claude-progress.txt— 작업 기록용 빈 파일- 기능 목록 JSON — 200개 기능을 잘게 쪼개
passes: false로 초기화 - 초기 git 커밋 — 기준점 확보
작업 에이전트(매 세션 실행):
- 한 번에 기능 하나만 작업
- 끝낼 때마다 코드베이스를 머지 가능한 깨끗한 상태로 두기
- 세션 시작 시 진행 상황 읽고, 기존 기능이 잘 돌아가는지 먼저 확인
2. 기능 목록(Feature List)이라는 ‘진실의 원천’ #
[
{
"name": "로그인 폼 UI",
"steps": [...],
"passes": false // 작업 에이전트가 통과 시 true로만 바꿈
},
...
]핵심 규칙: 에이전트는 passes만 바꿀 수 있고, 기능을 삭제·수정할 수 없습니다. “테스트를 지우거나 고치는 건 절대 금지” — 그래야 누락이나 버그를 숨기지 못합니다.
이 한 가지 규칙으로 “조기 승리 선언” 실패 모드가 차단됩니다.
3. 상태 회복용 세 가지 산출물 #
새 세션은 항상 이 세 개를 먼저 읽고 시작합니다.
| 산출물 | 역할 |
|---|---|
| Git 히스토리 | 의미 있는 커밋 메시지로 흐름 파악 |
| 진행 파일 | 완료한 작업 자유 서술 요약 |
| 기능 목록 | 남은 작업의 정확한 상태 |
추가로 Claude는 Puppeteer 같은 브라우저 자동화 도구로 실제 사용자처럼 E2E 테스트를 돌립니다. 그저 코드가 컴파일된다고 끝이 아니라, 진짜로 동작하는지 눈으로 확인하는 거예요.
핵심 결론 #
며칠 가는 자율 작업을 시키려 할 때 사람들은 본능적으로 “더 똑똑한 모델이 필요하다"고 생각합니다. 이 글의 답은 다릅니다.
“장기 작업이 실패하는 이유가 모델 능력인 줄 알았는데, 사실은 인수인계 구조가 없는 게 문제였다.”
사람 팀이 교대로 일할 때 필요한 것 — 명확한 인수인계 문서, 잘게 쪼갠 작업, 이전 작업이 멀쩡한지 확인하는 절차 — 그게 에이전트에게도 똑같이 필요합니다.
내 작업에 적용한다면 #
시나리오 1 — 일반적인 데이터 분석 과정 #
며칠~몇 주 가는 분석 프로젝트도 같은 문제를 겪습니다. 어제 무슨 가설로 무슨 분석을 했는지 기억이 안 나죠.
[Before — 인수인계 없는 분석]
주말 지나고 노트북 열면 "어제까지 뭐 했지?"
→ 같은 분석 반복, 새 가설 잊음
[harness 패턴 적용]
[초기화]
- progress.md (자유서술 기록 파일)
- hypotheses.json (가설 목록, status: open/confirmed/rejected)
- 분석 환경 셋업 스크립트
[매 세션 시작 시]
- progress.md, hypotheses.json 먼저 읽기
- 어제 만든 차트/모델이 여전히 잘 돌아가는지 확인
- 한 번에 가설 하나씩만 검증
[세션 종료 시]
- 결과·결정사항을 progress.md에 짧게 누적
- 가설 상태 업데이트
- 코드는 깨끗한 상태로 커밋핵심: 장기 분석의 일관성은 “매 세션마다 진실을 다시 만나는 절차” 에 달려 있습니다.
시나리오 2 — 웹 사이트를 자동으로 운영할 때 #
운영도 며칠 단위 작업이 흔합니다. 마이그레이션, 대규모 리뉴얼, 콘텐츠 시리즈 발행 등.
[Before — 한 번에 다 하려다 실패]
"콘텐츠 100편 자동 발행 시작"
→ 도중에 컨텍스트 폭발, 절반은 망가진 상태
[harness 패턴 적용]
[초기화 에이전트]
- content-list.json (글 100편 목록, status: pending/draft/review/published)
- ops-progress.md (운영 기록)
- 빌드/배포 스크립트
[작업 에이전트]
- 한 세션 = 한 글만 처리
- 종료 시 사이트가 깨지지 않은 상태인지 자동 점검
- E2E 테스트로 실제 페이지 열어 검증
[규칙]
- content-list.json의 글 항목은 status만 변경 가능
- 글을 지우거나 합치는 행위 금지핵심: 장기 운영의 안정성은 “진행 파일 + 잘게 쪼갠 작업 단위 + E2E 검증” 세 가지 인수인계 구조에서 옵니다. 한 번에 다 하려 하지 마세요.
Anthropic 엔지니어링 블로그를 오래된 순서대로 읽고 정리합니다.
