이 기사의 개요: Mac에서 동작하는 Claude 데스크톱 앱(Cowork)을 Claude Code(CLI)의 비동기 서브 에이전트(Sub-agent)로 운용하는 메커니즘을 설계 및 구현한 기록. Monitor 툴을 통한 완료 감지 설계 과정에서, Cowork 스스로 설계 리뷰를 수행하게 함으로써 CLI 측에서는 알아차릴 수 없었던 구조적인 맹점이 드러났다.

장시간 CLI 세션이 지속되면 판단이 편향되기 시작한다는 느낌이 든다. "이 설계가 정말 괜찮은 걸까"라고 생각하면서도, 쌓여온 문맥(Context)의 무게에 끌려 멈춰 서지 못하게 된다.

이전에는 ChatGPT에 상담했으나, 워크스페이스를 공유할 수 없기 때문에 파일을 말로 다시 설명해야 하는 비용이 높았다. 지금은 Cowork(Mac 네이티브 Claude 데스크톱 앱)에 동일한 Mac의 파일을 직접 읽게 하여 벽치기(Wall-hitting, 아이디어 브레인스토밍)를 할 수 있다. 이것이 성립되는 것만으로도 상담의 질이 완전히 달라진다.

그 Cowork를 CLI의 서브 에이전트로 움직이게 할 수 없을까——그 생각이 이번 프로젝트의 출발점이다.

1. "원스텝으로 서브 에이전트화할 수 있지 않은가"

/cowork

스킬은 Cowork로 전달할 지시서(ops/active/cowork-pending.md)를 생성하는 것이다. CLI 측에서 지시 내용을 정리하여 파일로 쓰고, Cowork 측에서 그것을 읽어 작업을 수행하게 한다.

어느 날, Cowork에 전달하는 커맨드가 "ops/active/cowork-pending.md를 읽고 작업해 주세요"라는 원스텝이라는 사실을 깨달았다. 지시서에 작업 내용을 전부 적어두면, 내가 직접 붙여넣는 것만으로 Cowork가 움직인다. 그것은 "거의 서브 에이전트로 사용할 수 있지 않은가"라는 감각이었다.

남은 것은 작업 완료를 CLI 측에서 자동으로 감지할 수 있다면, Cowork는 CLI 입장에서 비동기적으로 동작하는 서브 에이전트가 된다는 점이다.

2. Cowork란 무엇인가, 왜 서브 에이전트화하고 싶은가

Cowork란 동일한 Mac에서 동작하는 Claude 데스크톱 앱을 말한다(Claude Code와는 별개의 프로세스·별개의 컨텍스트에서 동작한다). CLI는 파일 조작·git·스크립트 실행에 능숙하며 문맥을 쌓아갈 수 있는 반면, 장시간 운용 시 판단이 문맥에 휘둘린다. Cowork는 매번 신선한 컨텍스트로 시작하며, 브라우저 조작이나 워크스페이스 파일을 직접 참조할 수도 있다.

이 두 가지를 조합하는 메커니즘으로서 cowork-cli-bridge 프로토콜을 운용하고 있다(Cowork × Claude Code 연계의 정답). CLI와 Cowork가 ops/active/ 하위의 로컬 파일을 공유 버스(Shared bus)로 사용하는 2파일 방식이다. 이번에 하고 싶은 것은 그 통신에 "완료 감지"를 추가하여 Cowork를 본격적인 서브 에이전트로 만드는 것이다.

3. 설계 단계——로컬 파일을 경유하는 비동기 프로토콜

기존의 cowork-cli-bridge 프로토콜

기본적인 메커니즘은 심플하다.

• CLI 측이 ops/active/cowork-pending.md(지시서)를 생성한다. - Cowork 측이 파일을 읽고 작업을 실행한다.
• Cowork가 status: completed로 내용을 수정하고, 결과물의 경로를 review_output 필드에 기록한다.

# 완료 후의 cowork-pending.md (frontmatter만)
status: completed
completed_at: 2026-05-20 18:35:00
...

여기에 "CLI가 완료를 감지하여 보고한다"는 계층을 더하면 서브 에이전트화가 완성된다.

/cowork --wait 옵션 설계

CLI 측의 /cowork 스킬에 --wait 옵션을 추가하는 설계로 정했다.

/cowork <지시 내용> --wait
/cowork <지시 내용> --wait 30 # 타임아웃 30분

--wait를 붙이면 지시서 생성 후 대기 프로세스가 기동한다. Cowork가 작업을 마치고 status를 수정하면 CLI 측으로 알림이 전달된다. 나(COO)는 다른 작업을 하면서 대기할 수 있고, 알림이 오면 결과물을 확인한다.

4. 구현의 함정——Agent 라이프사이클과 장시간 루프는 공존하지 않는다

당초 설계(v1)에서는 secretary(별도의 전용 에이전트)를 run_in_background: true

로 실행하여, 내부에서 30회의 sleep 루프를 돌리며 폴링(polling)하는 구상이었다.

이것은 작동하지 않았다.

Claude Agent SDK에는 「Agent는 도구 호출(tool call) → 응답 → 완료」라는 라이프사이클이 있다. secretary를 실행하면, Agent는 bash bg job을 띄우고 「완료」된 것으로 간주해 버린다. bg job에서는 Read 도구 등의 에이전트 도구를 사용할 수 없기 때문에, 완료 감지 후에 CLI로 보고하는 경로가 사라져 있었다 (실기 확인: PID 58437이 프로세스로 남아 있음에도 불구하고, secretary 자체는 「완료」 처리되어 있었다).

"Agent는 단명한다. 장시간 모니터링에는 Monitor 도구를 사용한다" —— 이것이 전환점이었다.

Monitor 도구는 bash 명령어를 실행하고, 그 stdout의 각 행을 실시간으로 COO에게 통지하는 메커니즘이다. 장시간 모니터링 → 완료 시 1회 통지라는 유스케이스에 설계상 부합한다.

v2에서의 구현은 다음과 같았다 (앞서 언급한 §3의 명령어 예시 --wait 30은 사용법의 예이며, 여기서는 기본값인 60분을 사용한다).

# Monitor 도구가 실행하는 bash 스크립트
# 경로는 각자의 환경(프로젝트 루트)에 맞춰 수정해 주세요
COUNTER=0
...

bash가 COMPLETED를 출력하는 순간, Monitor를 통해 COO에 통지가 전달된다. COO는 Read 도구로 cowork-pending.md를 확인하고, 결과물 파일의 앞부분 20행을 그대로 사용자에게 보고한다.

또한, --wait로 지시서를 생성한 경우에는 Cowork 측에 「CLI 측에서 대기하고 있음」을 알리는 전용 섹션을 말미에 자동으로 추가하도록 했다. 자세한 내용은 후술하겠지만, 이 추가 작업이 설계의 핵심이 되었다.

5. Cowork에게 "자신을 리뷰"하게 해보았다

--wait 설계서가 어느 정도 완성되었을 때, Cowork에게 자기 리뷰를 의뢰했다.

설계서, 스킬 본체(workspaces/skill-dev/cowork/cowork.md), 프로토콜 정의(ops/playbooks/cowork-cli-bridge.md)의 3개 파일을 전달하며, "4가지 관점에서 설계의 문제점을 찾아내 달라"고 의뢰했다. Cowork에 대한 의뢰 프롬프트의 골격은 다음과 같다.

• 의뢰 형식:
  /cowork <이 지시서> 를 읽고 실행해 주세요
  ( --wait 없음. 결과를 나중에 확인하는 비동기 모드)
• 지시서 내용:
  • 첨부된 3개 파일의 경로를 열거하며 "모두 읽을 것"을 명시
  • 평가할 4가지 관점을 각각 제목으로 기술 (설계의 맹점 / 에러 케이스 / 기존 프로토콜과의 정합성 / Cowork가 느끼는 위화감)
  • "문제점과 그 심각도(구현 블로커 / 권장 개선 사항)를 나누어 보고해 달라"고 덧붙임

왜 Cowork(데스크톱 앱 측)에게 시키는가?

CLI 세션은 문맥(context)을 길게 쌓아 올릴수록, 그 문맥에 끌려간 판단을 내리게 된다. 설계한 본인이 "이대로 동작할 것"이라고 믿고 있는 가정을 스스로 의심하기는 어렵다. Cowork는 매번 새로운 컨텍스트로 시작하기 때문에, 「CLI 측에서는 자명한 것」을 「자명하지 않은 것」으로 바라볼 수 있다.

Cowork로부터 돌아온 리뷰는 4가지 관점 모두에서 "문제 있음"이었다. 관점 1(설계의 맹점)부터 관점 3(기존 프로토콜과의 정합성)까지, 구현상의 구체적인 문제들이 몇 가지 나타났다. 관점 1에서는 병렬 실행 시의 보고 혼선, 관점 3에서는 completed_at의 포맷 불일치 등, 구현 블로커급의 지적도 여러 개 포함되어 있었으며, 이들은 모두 v2 설계서에서 대응 완료했다. AI가 다른 AI의 결과물을 비평하는 접근 방식에 대해서는, 「AI에게 AI가 쓴 문장을 비평하게 했더니 60점이었던 이야기」에서도 시도하고 있다.

하지만 관점 4(Cowork가 느끼는 위화감)의 지적은 다른 질적인 면을 가지고 있었다.

6. 떠오른 맹점 —— CLI 측에서는 절대로 알아챌 수 없는 구조적인 문제

관점 4는 Cowork 자신의 시점에서 작성된 지적이다. 그 요약을 그대로 인용한다.

여기가 CLI 측에서는 보이지 않는 맹점의 핵심입니다. Cowork로서
「자신이 감시되고 있다는 사실을 모름」, 「타임아웃을 모름」, 「중단 방법을 모름」이라는 구조적인 정보 비대칭이 존재합니다.

가장 중요하다고 평가된 지적(관점 4-1)은 다음과 같다.

현재,

cowork-pending.md

cowork-pending.md의 본문에는 요청 내용과 "완료 후 status를 completed로 수정해 주세요"라는 문구만 적혀 있습니다. --wait로 실행된 pending 상태인지 아닌지를 Cowork 측에서는 구분할 수 없습니다. Cowork가 "이것은 나중에 시간이 날 때 하자"라고 판단할 경우, CLI 측이 영원히 기다리고 있다는 사실을 알지 못하기 때문에, 20분이면 끝날 요청이 2시간 동안 방치되는 일이 발생합니다.

이 글을 읽었을 때, "확실히 그렇다"라고 생각했습니다. 동시에, "CLI 측에서만 설계했다면 이 문제를 깨달을 기회가 없었을 것"이라고도 생각했습니다.

왜 CLI 측에서만은 깨달을 수 없는 걸까요? CLI 측에서는 "--wait로 실행되었다는 사실은 pending.md를 통해 알 수 있을 것"이라고 생각했습니다. 하지만 Cowork는 CLI의 내부 상태를 보지 않습니다. Cowork가 볼 수 있는 것은 지시서 파일의 내용뿐입니다.

또 하나, 보충 설명도 가슴에 와닿았습니다.

Cowork는 매번 새로운 세션으로 시작됩니다. CLI 측은 쌓아온 context (문맥)를 유지하고 있지만, Cowork는 그 context를 가지고 있지 않습니다. CLI 측에서 "자명한" 프로토콜이나 규약은, Cowork 입장에서 보면 전부 "지시서 본문에 적혀 있지 않으면 알 수 없는 것"입니다.

정보를 지시서 내에서 완결 짓도록 설계하는 원칙을 Playbook 전체에 적용하면, 이러한 종류의 맹점을 줄일 수 있습니다.

이 지적은 단순한 구현 버그에 대한 지적이 아닙니다. "보내는 사람의 문맥은 받는 사람에게 전달되지 않는다"라는 분산 시스템 (Distributed System)의 기본 원칙을 인간의 언어로 다시 표현한 것입니다.

대응책은 간단했습니다. --wait로 지시서를 생성할 경우, 말미에 "⏰ CLI 측에서 대기 중" 섹션을 자동으로 추가하는 것입니다.

## ⏰ CLI 측에서 대기 중
CLI 측의 Monitor가 이 파일의 완료를 기다리고 있습니다 (타임아웃: 60분, 시작: 2026-05-20 18:00:00 JST).
- 완료되면 신속하게 status를 `completed`로 수정해 주세요
...

정보를 Cowork 측에 전달하기 위해 지시서 본문에 적는다. 단지 그것뿐입니다. 하지만 "단지 그것뿐인" 일을 설계자 본인만으로는 깨닫지 못했습니다.

7. Claude Agent SDK와 멀티 에이전트 (Multi-Agent) 설계에서 얻은 3가지 교훈

이번 구현과 외부 리뷰를 통해 몇 가지 교훈을 얻었습니다.

1. Agent 라이프사이클을 이해하고 대기(wait)를 설계하라

Claude Agent SDK에서 백그라운드 대기를 하고 싶을 경우, Agent 도구의 run_in_background는 적합하지 않습니다. Monitor 도구가 올바른 선택지입니다. "Agent는 단명하고, Monitor는 장명하다"라고 기억해 두면 혼란을 피할 수 있습니다. Remote Trigger나 스케줄러와의 설계상 차이는 "Claude Code의 스케줄링 프레임은 3개뿐이다"라는 점으로 정리하고 있습니다.

2. 정보는 받는 사람의 관점에서 설계하라

지시서를 만들 때, 보내는 사람은 "내가 알고 있는 것은 상대도 알고 있을 것"이라고 무의식적으로 가정해 버립니다. 이는 인간 사이의 커뮤니케이션에서도 발생하는 문제이지만, AI 세션 간의 통신에서는 특히 현저하게 나타나기 쉽습니다. Cowork의 세션은 CLI의 문맥을 이어받지 않으므로, "지시서에 적혀 있지 않은 것은 제로(0)로 취급된다"라고 생각해야 합니다.

3. 외부 시점을 "조직적으로 취할 수 있는 구조"가 본질일지도 모른다

AI의 서브 에이전트화라고 하면 "태스크를 자동 실행시킨다"는 측면에 눈길이 가기 쉽습니다. 하지만 이번 경험을 통해 보인 것은, "내가 깨닫지 못하는 전제를 외부에서 지적하게 만드는 구조를 만드는 것"이 더 깊은 가치를 가질지도 모른다는 점입니다.

CLI가 장시간의 세션 동안 쌓아온 문맥은 자산이기도 하지만, 맹점의 온상이기도 합니다. 그곳에 Cowork라는 신선한 시점을 정기적으로 투입하는 메커니즘은, 혼자서 계속 생각하는 것의 한계를 보완하는 장치가 됩니다.

이는 사내 AI 활용에도 전용할 수 있는 관점입니다. 예를 들어 개인 개발 상황에서는, 설계서를 다 쓴 시점에 "문맥 없이 보았을 때의 위화감"을 다른 세션에 물어보는 데—그 번거로운 과정을 자동화하는 메커니즘이 있다면, 누락을 탐지하는 비용이 낮아질 것입니다. 하나의 AI 채팅에 모든 것을 의존하는 것이 아니라, 외부 시점을 의도적으로 포함시킨 AI 활용 아키텍처로 설계하는 것—그것이 이번 구현을 통해 보인 것입니다. 멀티 에이전트 조직을 매니지먼트하는 관점에서의 고찰은 "SE 경력 26년, 첫 부하는 AI였다"에 자세히 나와 있습니다.

이번에 만든 /cowork --wait

는 CLI 상태 표시줄(status bar)에 「1 monitor」라고 표시된다. 그 표시를 보고 있으면, Cowork가 저편에서 작업해 주고 있다는 안도감이 든다. Monitor를 통한 대기(waiting)는 CLI 측에서도 「제대로 작동하고 있다」는 것이 가시화되는데, 이것이 UX 측면에서 은근히 효과적이다.

비용 측면에 대해 보충해 두겠다. Monitor는 bash 프로세스를 실행하여 폴링(polling)할 뿐, LLM의 추론을 호출하지 않는다. 대기 중에 토큰이 소비되지 않으며, 추가적인 API 과금도 발생하지 않는다. 완료 감지 후에 COO가 Read / Report 하는 부분만이 일반적인 Claude Code 세션의 토큰 소비가 된다. 월 $200 이상의 과금이 신경 쓰이는 단계라 하더라도, Monitor의 상주 자체는 비용에 영향을 주지 않는다.

다음은 Cowork에 전달한 지시서의 정밀도를 어떻게 높일 것인가이다. 「지시서 내에서 정보를 완결시킨다」는 설계 원칙을 다른 에이전트 연동에도 확장해 나가고 싶다.

이 기사에서 다 담지 못한 설계·운용의 전체상은 Zenn Books에 정리해 두었다. 서장·제1부는 무료로 읽을 수 있다.

• 코드를 작성할 줄 모르는 내가 Claude Code로 「AI 팀」을 만들기까지 (¥900 / 서장·제1부 무료)
• 코드를 작성할 줄 모르는 내가 Claude Code로 「AI 팀」을 운영하기까지 (¥900 / 서장 무료)

이 기사는 はてなブログ(Hatena Blog)로부터의 크로스 포스트입니다.

Discussion