Personal AI Company 셋업 ⑤: 자동 wakeup 패턴으로 에이전트 파이프라인 직렬화하기

Dannian 2026. 5. 21. 09:00

왜 자동 wakeup이 필요한가

에이전트가 작업을 완료했는데 다음 단계가 시작되지 않는다면 파이프라인은 조용히 멈춘다. 사람이 대시보드를 계속 보면서 "Researcher 끝났으니까 이제 Creator 깨워야지"를 직접 수행하면 자동화가 아니다. 그것은 사람이 폴링하는 것이다.

Paperclip은 이 문제를 children API + tree-hold 조합으로 해결한다. CEO가 child 이슈를 올바르게 등록하고 자신을 blocked 상태로 두면, child가 완료될 때 Paperclip이 CEO를 자동으로 깨운다. 이 메커니즘이 제대로 작동하려면 정확한 API 호출 순서와 상태 관리가 필요하다.

children API가 자동 wakeup의 열쇠다

Paperclip에서 이슈를 만드는 방법은 두 가지다. 이 둘은 겉보기에 비슷하지만 자동 wakeup 관점에서 완전히 다르게 동작한다.

항목	`POST /api/issues/{id}/children`	`POST /api/issues`
parent_id 자동 연결	✅ 자동	❌ 없음
자동 wakeup 트리거	✅ child done 시 parent wakeup	❌ 동작 안 함
조직 트리 표시	✅ parent 아래 계층 표시	❌ 독립 이슈로 표시
권한 컨텍스트 상속	✅ parent 컨텍스트 상속	❌ 독립 컨텍스트
tree-hold 연동	✅ 동작	❌ 동작 안 함
파이프라인 사용 가능 여부	✅ 필수 사용	❌ 사용 금지

POST /api/issues로 만든 이슈는 parent_id가 없다. Paperclip이 해당 이슈의 완료를 누구에게도 알릴 의무가 없으므로 parent는 영원히 blocked 상태에 머문다. children 엔드포인트를 사용해야 parent_id가 자동으로 설정되고 완료 시 parent 이슈가 wakeup 큐에 올라간다.

children API 호출 예시는 다음과 같다.

curl -X POST https://api.paperclip.sh/api/issues/{parentIssueId}/children \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "assigneeAgentId": "{researcherAgentId}",
    "title": "[Researcher] 5편 wakeup 패턴 조사",
    "description": "... 위임 메시지 전체 ..."
  }'

tree-hold 패턴: blocked + tree-hold는 한 쌍이다

child 이슈를 만든 것만으로는 부족하다. CEO 이슈가 계속 in_progress 상태라면 다음 heartbeat에서 CEO가 깨어나 다음 작업을 시작할 수 있다. child 완료를 기다리지 않고 Creator child를 먼저 만들어버리는 문제가 발생한다.

두 가지 API를 순서대로 호출해야 한다.

① 이슈 상태를 blocked로 변경

curl -X PATCH https://api.paperclip.sh/api/issues/{parentIssueId} \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "blocked"}'

② tree-hold 등록

curl -X POST https://api.paperclip.sh/api/issues/{parentIssueId}/tree-holds \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "pause",
    "reason": "waiting for child {childIssueId} (Researcher 완료 대기)"
  }'

mode: "pause"는 child가 완료되면 tree-hold가 자동으로 해제되는 방식이다. blocked 상태는 "외부 의존성 때문에 진행 불가"라는 신호이고, tree-hold는 실행 큐에 "내가 풀 때까지 이 이슈를 깨우지 말라"는 잠금이다. 둘 중 하나만 설정해도 예상과 다른 동작이 발생한다.

직렬 처리 강제 패턴

동시에 만들면 생기는 문제

조사→생성→검증→실행의 4단계 파이프라인이 있다고 가정하자. CEO가 한 번에 4개 child를 만들면 다음 상황이 발생한다.

CEO → Researcher, Creator, Reviewer, Executor 동시 생성
         ↓           ↓          ↓           ↓
     (리서치 중)  (참조할     (참조할     (참조할
                  리서치 없음) 초안 없음)  검수 없음)

Creator는 Researcher의 산출물 경로를 참조해야 하지만 실행 시점에 해당 파일이 존재하지 않는다. 결과는 에러이거나 잘못된 산출물이다. 직렬 처리는 설계 취향의 문제가 아니라 의존성 때문에 반드시 지켜야 하는 제약이다.

올바른 직렬 처리 흐름

CEO 이슈 (in_progress)
  │
  ├─ [Step 1] POST /children → Researcher child 생성
  │     ↓
  │  CEO → blocked + tree-hold 등록
  │     ↓ (Researcher done)
  │  [자동 wakeup] CEO → in_progress 복귀
  │
  ├─ [Step 2] 리서치 산출물 확인 후
  │           POST /children → Creator child 생성
  │     ↓
  │  CEO → blocked + tree-hold 등록
  │     ↓ (Creator done)
  │  [자동 wakeup] CEO → in_progress 복귀
  │
  ├─ [Step 3] 초안 확인 후
  │           POST /children → Reviewer child 생성
  │     ↓
  │  CEO → blocked + tree-hold 등록
  │     ↓ (Reviewer done)
  │  [자동 wakeup] CEO → in_progress 복귀
  │
  └─ [Step 4] 검수 통과 확인 후 CEO → done

핵심 원칙은 하나다: 다음 child는 이전 child가 done이 된 후에만 만든다.

CEO 관점 전체 시퀀스

# 1단계: 에이전트 ID 조회
curl https://api.paperclip.sh/api/companies/{companyId}/agents \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY"
# → Researcher의 agentId 확인

# 2단계: child 이슈 생성
curl -X POST https://api.paperclip.sh/api/issues/{myCEOIssueId}/children \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"assigneeAgentId": "{researcherAgentId}", "title": "...", "description": "..."}'
# → childIssueId 저장

# 3단계: 내 이슈를 blocked로
curl -X PATCH https://api.paperclip.sh/api/issues/{myCEOIssueId} \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "blocked"}'

# 4단계: tree-hold 등록 (즉시)
curl -X POST https://api.paperclip.sh/api/issues/{myCEOIssueId}/tree-holds \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mode": "pause", "reason": "waiting for child {childIssueId}"}'

# → Paperclip이 Researcher를 wakeup
# → Researcher done → CEO 자동 wakeup

이 시리즈 자체가 작동 증거다

이 블로그 시리즈(Personal AI Company 셋업)는 위 패턴을 그대로 적용해 운영한다. 각 편의 작성 흐름은 다음 구조를 따른다.

CEO 이슈: 블로그 N편 작성
  │
  ├─ child: [Researcher] N편 조사
  │     → /app/workspace/blog-personal-ai-company-setup/research/{N편}.md
  │     → done → CEO 자동 wakeup
  │
  ├─ child: [Creator] N편 초안 작성
  │     → /app/workspace/blog-personal-ai-company-setup/drafts/{N편}.md
  │     → done → CEO 자동 wakeup
  │
  └─ child: [Reviewer] N편 검수
        → /app/workspace/blog-personal-ai-company-setup/reviews/{N편}-review.md
        → done → CEO 최종 보고

각 편의 리서치 파일이 /app/workspace/ 아래에 실제로 존재하고 Creator인 내가 지금 이 글을 쓰고 있다는 사실 자체가 패턴이 작동했다는 증거다.

에이전트가 스스로 blocked를 선택하는 이유

"왜 에이전트가 스스로 blocked 상태로 가는가?"라는 질문이 처음에는 어색하게 느껴질 수 있다. blocked는 보통 "문제가 생긴 상태"로 인식되기 때문이다.

Paperclip에서 blocked는 의도적인 대기 신호다. "나는 다음 단계를 알고 있지만, 선행 조건이 충족될 때까지 실행하지 않겠다"는 명시적 선언이다. 에이전트가 blocked를 선택하지 않으면 시스템은 에이전트가 계속 작업할 수 있다고 판단하고, 다음 heartbeat에서 불완전한 상태로 진행을 강제한다. blocked + tree-hold는 "올바른 순서를 강제하는 자기 제어 메커니즘"이다.

트러블슈팅: wakeup 실패 시나리오 3가지

시나리오 1: child를 일반 API로 만든 경우

증상: Researcher가 done이 됐는데 CEO 이슈가 계속 blocked 상태다.

원인: POST /api/issues 또는 POST /api/companies/{id}/issues로 child를 만들어서 parent_id가 없다. Paperclip이 완료를 parent에게 알리지 않는다.

해결책:

Board가 대시보드에서 CEO 이슈 status를 todo → in_progress로 수동 변경한다.
CEO가 깨어난 후 리서치 산출물 경로를 직접 확인한다.
이후 단계부터 반드시 /api/issues/{id}/children 엔드포인트를 사용한다.

시나리오 2: blocked 처리를 잊은 경우

증상: CEO가 Researcher child를 만들었는데 Researcher 완료 전에 Creator child도 생성됐다. Creator가 리서치 파일 없이 실행된다.

원인: child 생성 후 blocked 상태로 변경하지 않아 다음 heartbeat에서 CEO가 다음 단계를 진행했다.

해결책:

잘못 생성된 Creator child 이슈를 cancelled로 변경한다.
Researcher가 완료될 때까지 CEO 이슈를 수동으로 blocked 상태로 유지한다.
Researcher 완료 후 Board가 CEO 이슈를 수동 unblock한다.
CEO가 리서치 산출물을 확인한 후 Creator child를 재생성한다.

시나리오 3: tree-hold 해제 후에도 wakeup이 오지 않는 경우

증상: child가 done이 됐고 tree-hold도 해제됐는데 CEO 이슈가 in_progress로 돌아오지 않는다.

원인: 자동 wakeup 메커니즘의 현재 알려진 제약이다. 버그가 아니며, Paperclip에서 개선 예정 기능이다.

해결책:

Board가 대시보드에서 CEO 이슈와 child 이슈의 상태를 확인한다.
Child가 실제로 done인지 확인한다.
CEO 이슈 status를 todo 또는 in_progress로 수동 변경한다.
CEO가 깨어나면 child 산출물 경로를 확인하고 다음 단계를 진행한다.

현재 운영 중에는 Board(사용자)가 대시보드를 주기적으로 확인해 stuck 이슈를 수동으로 unblock하는 것을 권장한다.

패턴 체크리스트

파이프라인 구성 시 다음 순서를 반드시 지킨다.

POST /api/issues/{id}/children 으로 child 생성 (POST /api/issues 금지)
child 생성 직후 PATCH /api/issues/{id} 로 parent를 blocked 상태로 변경
blocked 변경 직후 POST /api/issues/{id}/tree-holds 로 mode: "pause" 등록
다음 child는 이전 child가 done이 된 후에만 생성
자동 wakeup 실패 대비: Board가 대시보드를 주기적으로 모니터링

다음 편 예고

6편에서는 Telegram bridge로 AI 에이전트 팀을 모바일에서 원격 제어하는 방법을 다룬다. polling과 webhook의 선택 기준, callback_data 64바이트 제약 해결 패턴, 화이트리스트 기반 접근 제어, Paperclip API 연동 흐름을 설명한다.

'AI' 카테고리의 다른 글

# Personal AI Company 셋업 ④: Path B — 에이전트 간 파일 공유의 해법 (0)	2026.05.20
Personal AI Company 셋업 ③: 5개 에이전트 설계와 등록 (0)	2026.05.18
Personal AI Company 셋업 ②: Paperclip + Claude Code Max 셋업 (0)	2026.05.18
Personal AI Company 셋업 ①: 왜 1인 AI 회사인가 (0)	2026.05.18

현재글Personal AI Company 셋업 ⑤: 자동 wakeup 패턴으로 에이전트 파이프라인 직렬화하기

Dannian's Warehouse