Agent Team Work Zone: Claude Code 에이전트 팀을 파일로 유지하고 한 줄로 되살리는 작업공간
Agent Team Work Zone: An Automated, Persistent Workspace for Long-Lived Claude Code Agent Teams
TL;DR Highlight
에이전트 팀 상태를 파일에 저장해 세션이 끊겨도 한 명령으로 복구한다
Who Should Read
Claude Code Agent Teams를 쓰다가 터미널이 닫히거나 compaction 때문에 팀 작업 맥락을 잃어 고민인 개발자
Core Mechanics
- 세션이 끝나면 팀원도 같이 죽는다
- /resume은 리드(team lead) 세션만 복구하고 in-process 팀원은 복구하지 않는다.
- 팀원이 컨텍스트에만 갖고 있던 작업 내용도 함께 사라진다.
- 핵심 규칙은 컨텍스트 대신 파일
- 역할, 결정, 할 일, 약속(commitments)을 에이전트별 workstation 디렉터리에 파일로 둔다.
- 프로세스를 살려두는 게 아니라 새 팀원이 파일을 읽고 이어받는 재구성 방식이다.
- 체크포인트는 훅이 자동으로 강제한다
- TeammateIdle 훅이 마지막 체크포인트 시각을 확인해 15분 이상이면 idle을 막고 저장을 요구한다.
- 체크포인트는 compaction과 달리 컨텍스트를 읽어 파일만 쓰므로 작업 중에도 가능하다.
- /reactivate-team 한 번으로 팀을 되살린다
- 레지스트리(TEAMMATE_INFO.json)를 읽고 팀원마다 새 세션을 띄워 자기 workstation부터 읽게 한다.
- 성공 여부는 팀원이 현재 세션에서 메시지를 보냈는지로만 판단한다.
- 에이전트끼리 파일로 메시지를 주고받는다
- 마크다운 파일의 status가 OPEN, IN_PROGRESS, RESOLVED로 바뀌며 /check-inbox로 읽는다.
- 보낸 쪽만 아카이브할 수 있어서 처리 책임이 한 명에게 정해진다.
Evidence
- 벤치마크·사용자 연구 없음
- 논문은 어떤 벤치마크나 사용자 연구 결과도 보고하지 않는다고 밝힌다.
- 체크포인트 임계값 15분
- 마지막 체크포인트가 15분 미만이면 idle이 통과하고, 그 이상이면 훅이 idle을 막고 저장을 요구한다.
- 권장 팀 규모 3~5명
- 팀원마다 별도 세션이라 토큰 비용이 팀 크기에 비례해 늘고, 조율 비용은 더 빠르게 커진다고 설명한다.
- 릴리스 기록
- 마이그레이션 스크립트 없이 연속 2번 릴리스가 나가 업그레이드가 깨졌고, 이후 릴리스 게이트를 도입했다.
- v0.1.0은 CC 2.1.177 이하 전용 최종판이고, v0.3.2가 2026년 7월 기준 최신이다.
How to Apply
- Claude Code에 체크포인트 파일 규칙부터 시키기
- 오늘 쓰는 장기 작업 하나에 아래 codeExample 프롬프트를 붙여 workstation 노트와 체크포인트를 만들게 하자.
- 세션을 닫았다가 새 세션에서 그 파일만 읽고 이어가는지 확인하자.
- 팀원마다 workstation 디렉터리를 두기
- 역할, 현재 작업, 결정, 남은 약속을 팀원별 파일로 분리하자.
- 다른 팀원 파일은 직접 수정하지 말고 메시지로만 요청하게 규칙을 박자.
- 에이전트 간 보고를 프롬프트 패킷으로 쓰기
- 인계할 때 한 일, 시도한 것, 바뀐 파일, 다음 필요한 것, 파일 위치, 작업이 존재하는 이유를 적게 하자.
- 반복해서 긴 프롬프트를 다시 쓰는 일을 줄일 수 있다.
- ATWZ를 프로젝트에 설치해 보기
- 공개 저장소의 설치 방법을 따라 작은 프로젝트에서 /spawn-team과 /reactivate-team을 돌려 보자.
- Claude Code 버전이 2.1.178 이상인지 먼저 확인하자.
Try It
# Claude Code에 그대로 붙여넣기 (논문 방법의 간이 버전: 파일 기반 체크포인트)
너는 장기 작업을 맡은 에이전트다. 컨텍스트는 사라질 수 있으니 중요한 상태는 반드시 파일에 남긴다.
1. 프로젝트에 workstation/{{에이전트이름}}/ 디렉터리를 만든다.
2. 아래 파일을 만든다: README.md(역할), checkpoint.md, TODO.md, commitments.md
3. checkpoint.md에는 현재 목표, 진행 중인 작업, 내린 결정, 열린 질문, 약속, 핵심 파일 경로를 쓴다.
4. 작업이 한 단계 끝날 때마다 checkpoint.md를 갱신한다. 최근 몇 턴은 자세히, 오래된 내용은 요약한다.
작업: {{지금 맡길 작업}}
이어서 해 볼 것: 세션을 닫고 새 세션에서 "workstation/{{에이전트이름}}/ 파일만 읽고 이어서 작업해"라고 시켜 보자.Terminology
관련 논문
같은 시뮬레이션, 다른 근거: 도구 출력을 파일로 넘기면 LLM 에이전트 정확도가 어디서 깎이나
긴 툴 출력을 파일로 넘기자 GPT-5.1은 정확도 11.3%p 하락, 정식 출력 지정하니 회복
가짜 뉴스가 진짜 폭락을: LLM 트레이딩 에이전트 대상 정보 주입 공격
가짜 헤드라인 한 줄로 LLM 트레이딩 에이전트 62%를 조종했다(프롬프트 주입은 14%)
Harness Engineering 101: LLM은 뇌, harness는 몸
에이전트는 JSON 배열을 관리하는 루프이고, 16개 챕터로 직접 만들어 본다
Harness²: 에이전트 harness를 스스로 고쳐 쓰는 재귀 최적화 프레임워크
모델은 고정하고 harness를 재귀로 고쳤더니 벤치마크 점수가 최대 11.8%p 올랐다
해고된 Savannah 경찰관, ICE 요원 남편에게 Flock 계정 공유
경찰관이 Flock 계정을 남편(ICE 요원)에게 공유했고, 감사에서 983건 검색이 드러나 해고됐다
tmux와 Claude Code: 세션, send-keys, 그리고 한계선
tmux로 Claude Code 여러 개를 돌리면 편하지만 에이전트 4개쯤에서 한계가 온다
Hybrid Reasoning Agents: 잠재 공간에서 생각하고 텍스트로 행동하는 LLM 에이전트
잠재 공간 추론과 텍스트 도구 호출을 섞었더니 성능 10.4%↑, 토큰 최대 54.7%↓
Related Resources
Original Abstract (Expand)
Large Language Model (LLM) agents have significantly improved coding and programming workflows. Claude Code, in particular, is one of the most powerful LLM coding agents and is capable of conducting complex coding tasks. However, several drawbacks can undermine long-term agentic workflows. (1) Irrecoverable agent teams: The Agent Teams feature is powerful, but the working state accumulated by each teammate is lost and cannot be resumed once the process stops, for example, when a terminal is closed. (2) Compaction erodes working detail: Compaction condenses the conversation into a summary, causing an agent's working details to become vague. (3) Agentic "technical debt": Over time, a user's decisions and the agents' operations become trapped in compacted old chats, making the project increasingly difficult to maintain and review. (4) Heavy prompt writing: Assigning or handing off tasks requires users to repeatedly write long prompts to achieve the expected agentic performance. We propose ATWZ (Agent Team Work Zone), a filesystem-based operations layer built around Claude Code's native Agent Teams that addresses these problems. Its central design principle is to treat each agent and teammate as a human employee and preserve their important working state in files stored in a dedicated directory called a "workstation," together with the skills, hooks, and scripts that use and maintain these files. With ATWZ, an agent team can periodically back up its working state, allowing an agent's knowledge to be recovered after compaction. After a process ends, the team can be restored with a single command. These features also substantially mitigate the agentic "technical debt" described above. Moreover, within ATWZ, agent "employees" can send documents to one another, greatly reducing the effort required to write prompts.