Hermes Agent Kanban — 멀티 에이전트 작업을 위한 영속 코디네이션

Tony Simons(@tonysimons_)가 정리한 hermes-agent Kanban 운영기. “에이전트 하나”는 잘못된 작업 단위이며, 작업이 길어지고 병렬·검토·복구가 필요해지는 순간부터는 보드·계약·영수증(receipts) 기반의 영속 코디네이션이 필요하다는 주장이다.

한 줄 요약

컨텍스트 윈도우는 매니저가 아니라 한계가 있는 상자일 뿐이다. 긴 작업을 거대한 단일 채팅 안에서 돌리면 결국 “context soup”(잘 포맷된 메모리 누수)가 된다. 해법은 더 똑똑한 프롬프트가 아니라, 상태를 기록하는 보드와 작업 계약, 그리고 검증 가능한 기록이다.

핵심 개념: 왜 보드인가

• 보드(Boards) 는 워크스트림을 격리한다.
• 태스크(Tasks) 는 상태를 들고 다닌다.
• 프로파일(Profiles) 은 워커의 형태(역할)를 정의한다 — 스티커가 아니라 상태 경계(state boundary).
• 부모 링크(Parent links) 는 순서를 정의한다.
• 워크스페이스(Workspaces) 는 파일이 어디에 떨어질지 결정한다.
• Runs / Logs / Events 는 영수증이다 — “누가, 무엇을, 얼마나 오래, 무슨 말을 남기고 끝냈는지”의 추적 흔적.

“Receipts beat vibes.” 대시보드는 워커가 죽었어도 살아 있는 것처럼 보이게 만든다. 그래서 상태를 추측하지 말고 직접 끌어와 확인한다.

보드와 태스크 만들기

가장 단순하게 시작한다. --default-workdir로 보드에 “집”을 주면 산출물이 유령 스크래치 더미로 사라지지 않는다.

hermes kanban boards show
hermes kanban boards switch hermes-kanban-field-manual
hermes kanban boards create hermes-kanban-field-manual \
  --switch \
  --default-workdir /home/tony/projects/hermes-kanban-field-manual

작업은 끝낼 수 있을 만큼 작고, 검증할 수 있을 만큼 명확하게 만든다. 작업을 연쇄(chain)할 때는 --json으로 태스크 id가 스크롤백에 묻히지 않게 한다.

hermes kanban create "Survey the source notes" \
  --assignee hkg-researcher \
  --workspace dir:/home/tony/projects/hermes-kanban-field-manual \
  --max-runtime 30m \
  --json

• 요청이 아직 모호하면 --triage로 분류함에 넣는다 (스펙이 필요한 단계).
• 작업은 실제지만 사람의 결정이 먼저 필요하면 --initial-status blocked.
• --max-runtime은 장식이 아니다. 빠른 패스는 300(초), 실제 서베이는 30m, 초안/리뷰 게이트는 2h도 이상하지 않다. 폭주 태스크가 영원히 자리를 차지하는 것을 막는다.

작은 계약이 거대한 프롬프트를 이긴다

서베이 먼저, 초안 나중이 패턴이다. 서베이 태스크는 사실을 모으고, 초안 태스크는 그것을 글로 바꾸고, 리뷰 태스크는 핸드오프를 점검한다. 어느 것도 프로젝트 전체를 다시 논쟁하지 않는다.

hermes kanban create "Draft the article from the survey" \
  --assignee hkg-writer \
  --parent <survey-task-id> \
  --workspace dir:/home/tony/projects/hermes-kanban-field-manual \
  --max-runtime 2h \
  --json

• --parent는 생성 시점의 의도 — 의존성을 이미 알 때 깨끗한 경로로 그래프를 태생부터 만든다.
• hermes kanban link <parent_id> <child_id>는 복구 모드 — 두 태스크가 이미 존재하거나 오래된 그래프를 다시 꿰맬 때 쓴다.
• 워커 형태가 다르면 하나의 프로파일에 모든 스킬을 욱여넣지 말고 별도 프로파일을 만든다.

운영 리듬: Claim → Block/Schedule → Promote → Complete → Archive

hermes kanban claim <task_id> --ttl 900               # TTL은 소유권이 아니라 리스(lease)
hermes kanban block <task_id> "Need the source notes before drafting"
hermes kanban schedule <task_id> "Waiting on answer at 3 PM"
hermes kanban promote <task_id> "Survey complete, drafting can start" --json
hermes kanban complete <task_id> \
  --summary "Drafted article-v5 from review notes" \
  --metadata '{"changed_files":["drafts/article-v5.md"],"tests_run":0,"decisions":["..."]}'
hermes kanban archive <task_id>

• claim --ttl: 워커가 사라지면 클레임이 만료되어 유령처럼 매달리지 않는다.
• block은 실패가 아니라 “사람 입력이 의존성”이라는 깔끔한 인정.
• schedule은 “시간이 의존성”일 때. 사람 대기와 시계 대기는 다르다.
• promote --force는 의도적으로 의존성을 무시할 때만 — 지렛대(crowbar)지 라이프스타일이 아니다.
• complete의 summary는 사람용, metadata는 다운스트림 워커와 미래의 나를 위한 핸드오프.

영수증으로 상태 확인하기

무언가 이상하면 추측하지 말고 상태를 끌어온다.

hermes kanban show <task_id> --json      # 태스크·코멘트·이벤트
hermes kanban runs <task_id> --json      # 실제 시도 여부
hermes kanban log <task_id> --tail 4000  # 워커 출력 마지막 청크
hermes kanban tail <task_id>             # 변하는 중이면 이벤트 스트림 추적

그리고 카드가 running이라고 해도 살아 있다는 증거는 아니므로, 실제 프로세스를 확인한다.

pgrep -af 'hermes.*kanban.*<task_id>'
ps aux | grep 'hermes.*kanban' | grep '<task_id>'

보드는 running인데 살아 있는 프로세스가 없고 runs에 정상 시도가 없으면 — 스테일 락이거나 죽은 워커다. UI와 철학 논쟁하지 말고 회수한다.

hermes kanban reclaim <task_id> --reason "stale lock, no live process"

오후를 잡아먹는 세 가지 멍청한 실패

1. 잘못된 보드(wrong board) — 셸 하나가 옛 보드를 가리키고 있어서 작업이 엉뚱한 큐에 떨어진다. boards show로 위치를 확인하고 boards switch <slug>로 의도적으로 전환한다.
2. 스크래치 유령(scratch ghost) — 워커는 끝났는데 산출물이 아무도 안 보는 scratch에 떨어진다. dir:<absolute-path>와 보드 기본 워크스페이스로 파일이 사람이 열어볼 수 있는 곳에 있게 한다.
3. 스테일 락(stale lock) — 카드는 running, 로그는 멈췄고, 프로세스 테이블은 비었다. 영수증으로 구분한 뒤 회수한다.

상태 단어를 섞으면 시스템이 아니라 미신 기계(superstition machine)를 돌리는 셈이다:

• Triage = 스펙이 아직 모호함
• Blocked = 사람의 결정이 빠짐
• Scheduled = 시간이 의존성
• Running = 지금 프로세스가 살아 있음

보드를 쓸 때 vs 채팅으로 끝낼 때

작고 일회성인 작업(한 번의 조회, 빠른 수정, help-text 확인)은 보드가 오버헤드일 뿐이다. 다음 중 하나라도 필요하면 보드를 쓴다:

• 병렬 워크스트림 / 리뷰 게이트 / 크래시 복구 / 영속 핸드오프 / 전문 프로파일 / 셸이 죽어도 살아남아야 하는 상태 / 몇 시간~며칠에 걸친 작업

운영자가 여전히 판단을 소유한다

에이전트는 작업을 수행하고, 범위를 추천하고, 계약을 이행하고, 깔끔하게 핸드오프할 수 있다. 하지만 브리프·시퀀싱·보드를 쓸 가치가 있는지는 결정하지 못한다 — 그것은 사람의 몫이다. 이는 한계가 아니라 설계다. Hermes Kanban은 한 에이전트를 더 똑똑하게 만드는 것이 아니라, 에이전트와 사람으로 이뤄진 팀을 덜 취약하게 만드는 시스템이다.

해석

이 글은 2026-04-19-anatomy-of-agent-harness·harness에서 다룬 “하네스 = 에이전트 외부의 상태·조율 계층”이라는 주장을, Kanban이라는 구체적 운영 도구로 보여주는 실전기다. 2026-04-30-hermes-ecosystem-map의 Hermes 생태계 중 작업 조율(orchestration) 축에 해당하며, moc-ai-agents-orchestration에서 다루는 장기 실행·영속 상태 문제(→ 2026-05-05-long-running-agents)에 대한 도구적 해답이다.

Related

• hermes-agent
• 2026-04-30-hermes-ecosystem-map
• moc-ai-agents-orchestration
• harness
• 2026-05-05-long-running-agents
• moc-ai-agents