Hermes Agent Kanban CLI의 사양을 에이전트에게 가르치기 위한 기사

이것은 인간을 위한 CLI 해설 기사가 아니다.

Hermes Agent의 태스크 보드 (Kanban)를 Claude Code / Codex / 로컬 LLM bot 등의 외부 에이전트가 "올바르게 말하게 하기" 위한 사양 메모로서 작성하고 있다. 독자로 상정하고 있는 것은 에이전트를 Hermes의 워커(worker)로 통합하고 싶은 엔지니어 — 구체적으로는 브릿지 스크립트(bridge script)를 작성하는 사람과, 에이전트에게 전달할 시스템 프롬프트(system prompt)나 SKILL.md를 작성하는 사람이다. 양측이 1차 자료로서 나란히 두고 볼 수 있는 형태를 목표로 하고 있다.

시리즈 위치로는, 다음 기사인 「구독형 Claude Code를 Hermes의 워커로 동작시키는 고안」의 전제 기사에 해당한다. Kanban의 「경계 API (boundary API)」로서의 성질을 여기서 먼저 확정하고, 다음 기사에서 구체적인 운용 설계로 들어간다.

에이전트에게 가르쳐야 할 요점은 4가지로 정리할 수 있다.

Kanban DB를 직접 써서는 안 된다. 어떤 경로로 접하든 반드시 공식 surface를 경유할 것. -
누가 어떤 surface를 사용하는지가 나누어져 있다. Hermes 내부의 worker model은 kanban_* tool call, 외부 bridge / 인간 / cron은 hermes kanban CLI를 사용한다. 동일한 DB layer에 도달하지만 입구가 다르다. -
상태 모델(state model)과 라이프사이클(lifecycle)을 기억할 것. 에이전트는 "자신이 지금 어떤 상태에 있으며, 무엇을 호출해야 다음으로 진행할 수 있는지"를 이해하고 있어야 한다. -
최소 프로토콜(minimum protocol)만 기억하게 할 것. dispatcher 기동형과 pull형 external bridge에서 전단부가 다른 것 외에, 본체의 흐름은 동일하다 — 읽기(read) → 동작(run) → heartbeat → 완료(complete) 또는 차단(block).

이하, 이 4가지 점을 순서대로 설명한다.

Kanban을 다루는 주체는 적어도 4종류가 있으며, 각각 사용하는 surface가 다르다.

주체	사용하는 surface
인간 오퍼레이터	`hermes kanban ...` CLI / `/kanban ...` slash command / dashboard
cron / script / 외부 bridge	`hermes kanban ...` CLI
Hermes dispatcher-spawned worker (LLM 본체)	`kanban_show`, `kanban_complete`, `kanban_block`, `kanban_heartbeat` 등의 tool call
Orchestrator profile	`kanban_create`, `kanban_list`, `kanban_link`, `kanban_unblock`을 포함한 확장 toolset

이 부분을 혼동하면 사고가 발생한다. 특히 주의해야 할 점은:

Hermes 내부의 worker는 CLI를 shell out 하지 않는다. worker model은 kanban_* toolset을 호출한다. CLI와 toolset은 모두 동일한 kanban_db layer에 도달하므로, 상태 전이(state transition) · 이벤트 로그 · 의존 태스크의 자동 승격 등의 정합성이 유지된다. -
외부 bridge (Claude Code, Codex, 로컬 LLM bot을 Hermes에 연결하는 얇은 계층)는 CLI를 사용한다. 이는 bridge 자체가 "인간에 상당하는 외부 스크립트"이기 때문이다.

즉, 본고에서 다루는 "에이전트에게 가르친다"는 정확하게는 두 가지 타겟이 있다:

(a) 외부 bridge = CLI를 호출하는 스크립트 + LLM. bridge의 책무로서 list / watch / claim이 필요하다. -
(b) Hermes 내부 worker LLM = kanban_* tool call로 동작한다. CLI는 호출하지 않는다.

양쪽 모두에 공통되는 것은, Kanban DB를 직접 쓰지 않는 것, 상태 모델을 이해하고 있는 것, 최소 프로토콜을 지키는 것이다.

CLI든 kanban_* tool이든, 두 surface 모두 동일한 kanban_db layer 위에 올라가 있다. 이 layer를 건너뛰고 SQLite를 직접 작성하면, 최소한 다음 3가지가 망가진다:

claim의 원자성 (atomicity): 「ready 상태에서 아무도 lock을 걸지 않은 태스크만을 자신의 lock과 함께 가져온다」라는 배타적 조작을 1개의 트랜잭션(transaction)으로 처리한다. 수동 SQL로 이 보증을 재현하는 것은 번거로우며, 잘못 작성할 경우 두 개의 워커(worker)가 동일한 태스크를 점유하는 레이스 컨디션 (race condition)이 발생한다.
이벤트 로그의 정합성: 상태 전이(state transition)마다 events 테이블에 행을 추가하는 것이 규칙이다. surface를 통하면 자동으로 기록되지만, 생(raw) SQL로 tasks.status만 변경하면 로그가 남지 않아 tail / watch를 통한 진행 상황 추적이 불가능해진다.
의존 태스크의 자동 승격: 부모 태스크가 done이 되었을 때 자식 태스크를 todo → ready로 올리는 처리는 surface를 통해서만 실행된다. link / unlink로 구성된 DAG(Directed Acyclic Graph)가 작동하지 않게 된다.

요컨대, *공식 surface (CLI 또는 kanban_ tools)가 「세만틱스 (semantics)를 보장하는 API」**이며, SQLite 파일 그 자체는 내부 구현상의 편의일 뿐이다.

인간 / cron / script / 외부 bridge → Hermes 내 worker model
│ │
▼ ▼
...

입구는 두 개지만, 정합성을 유지하는 계층은 하나다. 이것이 Kanban을 「게이트웨이 사이의 경계에 둘 수 있는」 성질의 정체다.

기존에는 「단일 kanban.db에 모든 태스크가 들어간다」고 생각하기 쉽지만, 현재는 SQLite DB / workspace / dispatcher scope가 보드(board) 단위로 분리되어 있다. default 보드는 기존의 위치이며, 추가된 보드들은 각각 독립된 영역을 가진다. gateway-embedded dispatcher는 tick마다 각 보드를 sweep한다 (보드마다 별도의 프로세스나 별도의 스레드가 생성되는 것은 아니다).

bridge / scripting 측에서 유의해야 할 사항:

스크립트에서는 반드시 --board <slug>를 명시해야 한다 (switch의 글로벌 current는 서로 다른 셸(shell) 간에 충돌이 발생할 수 있다)
CLI의 board 결정 순서는 --board → HERMES_KANBAN_BOARD 환경 변수 → current file → default 순이다.
보드를 가로질러 상태를 집계해야 하는 경우에는 각 보드에 대해 개별적으로 쿼리해야 한다.

보드를 나누는 기준:

프로젝트 단위: qi-portal, support-chat
도메인 단위: bidding-cases, hr-tickets
게이트웨이 간의 경계: cross-org-decisions, client-handoff
임시 워크플로우: 2026q2-audit-prep

개인 노트를 Kanban에 적는 것은 설계 미스다. 그것은 Vault와 Memory의 역할이며, Kanban에 적는 순간 다른 게이트웨이에서도 가시화된다.

태스크는 다음 상태를 가진다 (v0.14.0 시점).

triage ──specify/decompose──> todo ──deps done──> ready ──claim──> running ──complete──> done
↑ ↑ │
│ │ ├── block ────> blocked ──┐
...

포인트:

메인 흐름은 triage → todo → ready → running → done이다.
blocked와 scheduled는 메인 흐름의 경유점이 아니라, ready / running에서 옆으로 주차(park)되는 side state이다.
unblock은 단일 명령이지만, 복귀 지점은 두 계통으로 분기한다: 태스크의 의존성이 해결되었다면 ready로, 해결되지 않았다면 todo로 돌아간다 (그림의 todo로 향하는 unblock 선은 두 경우를 모두 포함하여 그린 것이다).
archived는 표시 제어용이다.

각 상태의 의미를 에이전트 (agent) 관점에서 정리한다:

상태	에이전트 (agent) 관점에서의 의미
`triage`	아직 사양화되지 않음. 에이전트 (agent)가 다루는 대상이 아님. `specify` 또는 `decompose`를 통해 다음 상태로 전환됨.
`todo`	사양은 결정되었으나 의존성 (dependency) 미해결. 아직 점유 (claim)할 수 없음.
`ready`	의존성 해결 완료, 점유 (claim) 가능. 디스패처 (dispatcher)가 가져가거나 외부 브리지 (bridge)가 가져옴.
`running`	누군가가 점유 (claim) 중. 다른 에이전트 (agent)는 건드리지 않음.
`done`	정상 종료. `summary` (인간 대상 핸드오프 (handoff))와 `metadata` (기계 대상 핸드오프 (handoff))가 다음 공정의 정보원임.
`blocked`	인간 또는 다른 봇 (bot)의 판단 대기 중. 디스패처 (dispatcher)는 자동으로 재개하지 않음.
`scheduled`	시간 트리거 대기 중. `schedule`로 주차 (park)되며, 정해진 시각이 도래하거나 `unblock`을 통해 메인 흐름으로 복귀함.

에이전트 (agent)가 특히 숙지해야 할 사항:

ready 상태가 아니면 점유 (claim)할 수 없다. todo 상태에 대해 점유 (claim)를 시도해도 실패한다.
TTL (Time To Live) 내에 하트비트 (heartbeat) / 코멘트 (comment) / 완료 (complete) / 차단 (block) 중 하나를 보내지 않으면, 최종적으로 다른 워커 (worker)에게 다시 할당된다. TTL 값과 하트비트 (heartbeat) 부재 시 stale (오래된 데이터) 판정 임계값은 모두 빌드 (build) / 설정 (config)에 따라 달라진다. 외부 브리지 (bridge)는 running 상태의 점유 (claim)에 대해 TTL을 가진다. claim --ttl <seconds>를 통해 TTL을 정책 (policy)으로 명시하고, 그보다 충분히 짧은 간격으로 하트비트 (heartbeat)를 보내도록 설계한다.
Silent return (조용한 반환)은 금지된다. 워커 (worker)가 complete / block을 호출하지 않고 정상 종료할 경우, 현재 구현에서는 protocol_violation (프로토콜 위반)으로 처리되어 auto-block / gave_up으로 태스크가 종료된다. 막혔을 때든 진행되었을 때든, 반드시 block 또는 complete로 태스크를 종료해야 한다.

에이전트 (agent)가 암기해야 할 것은 이것뿐이다. 앞 단계가 다른 것을 제외하면 공통적이다.

CLI와 툴셋 (toolset) 인자의 차이: CLI 명령어는 외부에서 호출하므로 반드시 <task_id>를 받는다. 반면, Hermes 내부 워커 (worker)의 kanban_* 툴셋 (toolset)은 태스크 범위 (task-scoped)이며, 워커 (worker)는 자신이 실행 중인 태스크를 기지의 대상으로 취급한다. 원칙적으로 task_id를 전달하지 않고, body / summary / note 등의 내용만을 인자로 받는다.

surface	명령어
CLI (외부 브리지 (bridge) / 인간 / 스크립트 (script))	`hermes kanban show <task_id>` / `hermes kanban context <task_id>`
툴셋 (toolset) (Hermes 내부 워커 (worker))	`kanban_show()`

CLI 측에서 show는 태스크 본체 + 코멘트 (comment) + 이벤트 이력이며, context는 "워커 (worker)가 앞으로 동작하기 위해 필요한 정보의 덩어리"를 외부에서 확인하기 위한 surface (접점)이다.

Hermes 내부 워커 (worker)에서는 kanban_show()의 반환값에 task body / comments / parent handoffs / prior attempts / worker_context가 한꺼번에 들어있다. 별도로 kanban_context()를 호출하는 것을 전제로 하지 않는다 — 툴셋 (toolset) 측에 대응하는 도구는 존재하지 않으며, CLI의 context는 외부의 인간 또는 브리지 (bridge)가 워커 (worker)의 가시성을 들여다보기 위한 진단용으로 이해한다.

surface	명령어
CLI	`hermes kanban heartbeat <task_id> --note "step 2 of 4"`
툴셋 (toolset)	`kanban_heartbeat(note="step 2 of 4")`

긴 작업에서는 단계마다 heartbeat를 보낸다. 보내지 않으면 heartbeat 부재로 인한 stale 판정을 거쳐 다른 worker에게 작업이 재할당된다 (stale 판정 임계값은 build / config에 따라 다르다. 로컬 build에서는 kanban.dispatch_stale_timeout_seconds에 해당하는 설정을 확인할 수 있었으나, 설정 이름이나 기본값은 버전 간에 변경될 수 있으므로 bridge는 이에 의존하지 않는 설계가 바람직하다).

bridge에서는 claim --ttl 900과 같이 직접 TTL을 명시하고, **TTL보다 충분히 짧은 간격 (기준상 몇 분 단위)**으로 heartbeat를 보내는 policy가 안전하다. 공식 docs에서도 장시간 operation 시에는 kanban_heartbeat(note="...")를 정기적으로 보내는 worker protocol로 설명되어 있다.

surface	커맨드 (command)
CLI	`hermes kanban comment <task_id> --author claude-code-bridge "본문"`
toolset	`kanban_comment(body="본문")`

여기에 작성하는 내용은 관측 사실 · 검증 결과 · 미결 사항 · handoff에 필요한 정보이다. chain-of-thought 방식의 내부 사고逐語(逐語, verbatim) 로그가 아니라, 다음 독자가 재현 및 판단할 수 있는 사실을 작성한다. CLI의 --author는 호출 주체의 식별자 (bridge 명 등)이며, toolset 측은 profile이 자동으로 author가 된다.

CLI:

hermes kanban complete <task_id> \
--summary "Implemented API endpoint and added integration test." \
--metadata '{"changed_files":["src/api/foo.ts","test/api/foo.test.ts"]}'

toolset: kanban_complete(summary="...", metadata={...})

구현 내용이 아니라 "다음에 필요한 정보"를 작성한다. summary는 인간을 위한 handoff 용이며, metadata는 downstream의 자동화 스크립트나 하위 태스크가 소비하는 free-form JSON이다.

CLI:

hermes kanban block <task_id> "cause: spec undecided
what happened: 仕様書のセクション 3.2 で A 案と B 案が併記されたまま。実装側が判断する根拠が無い。
options: A / B / C
...

toolset: kanban_block(reason="cause: ...")

block의 본문은 반드시 다음 템플릿을 따른다:

cause: <human decision needed | test failure | environment | auth missing | spec undecided>
what happened: <사실 관계를 1단락으로 작성>
options: <A, B, C — 구체적인 선택지>
...

이 템플릿이 지켜진다면, 차단을 해제하는 측 (인간 또는 별도의 bot)은 한 번의 리드(read)로 모든 정보를 받을 수 있다. "잘 되지 않았습니다"라고만 적힌 block은 최악이며, 인간이 여러 번 되물어야 하는 상황을 초래한다.

Hermes 내부 dispatcher가 spawn한 worker는 기동 시 자신의 태스크 ID가 주입된 상태 (HERMES_KANBAN_TASK 환경 변수)로 동작하므로, 스스로 claim하러 갈 필요는 없다.

반면, 외부 bridge는 스스로 태스크를 가져와야 한다.

hermes kanban list --board <slug> --assignee claude-code-bridge --status ready --json
# 또는 stream 모니터링:
hermes kanban watch --assignee claude-code-bridge --interval 5
...

hermes kanban claim <task_id> --ttl 900
# 성공하면 workspace path가 stdout으로 반환됨

TTL은 본고의 bridge policy로서 900초로 명시한다 (build / config의 기본값에 의존하지 않음). claim 성공 후에는 해당 경로로 cd한 다음, 위의 공통 프로토콜 (1~5) 단계로 진입한다.

스타일 선호의 문제가 아니라, 이를 어기면 state가 망가지거나 보드 전체가 기능 불능 상태가 된다:

Kanban DB 파일에 생(raw) SQL로 UPDATE/INSERT/DELETE를 하지 않는다. 공식 surface (CLI 또는 kanban_* tools) 이외의 방법으로 쓰지 않는다.
막혔을 때나 완료했을 때나, 반드시 현재 구현상 silent return은 block 또는 complete를 통해 태스크를 닫아야 한다. 그렇지 않으면 protocol_violation으로서 auto-block 처리된다.
CLI가 non-zero exit 했을 때의 처리는 claim 전과 claim 후로 나눈다.
- claim 전 (list / watch / claim 실패): race condition, 일시적인 board 상태 변화, 통신 문제로 인해 발생할 수 있다. bridge는 짧은 backoff 이후 rescan하여 다른 태스크를 가져오거나, 동일한 태스크를 나중에 재시도한다. block은 하지 않는다 (claim 전이므로 block할 대상이 없음).
- claim 후 (show / context / heartbeat / comment / complete 등의 실패): 짧은 재확인 후, 해결 불가능하다면 block을 통해 사람에게 넘긴다.
만약 (명령어 실행 자체가) 실패한 경우, Kanban 상에서 상황을 전달할 수 없으므로 complete / block 자체가 실패한다. 별도 채널 (Slack / Discord / 메일 / 로그 aggregator)로 알람을 보낸다. bridge 측에서 이 fallback channel을 보유하고 있어야 한다.
인증 정보 / 비밀키 / 별도 게이트웨이의 vault 내용을 body / comment / metadata에 쓰지 않는다. surface는 이를 redact(비식별화)하지 않는다.
cron / 스크립트로부터 transient(일시적)한 실패로 인해 중복 태스크가 생성될 수 있다. 결정적인 요소로부터 생성하는 것이 요령이다 — 예: create할 때는 반드시 --idempotency-key를 붙인다. --idempotency-key "$(echo -n "${board}:${title}:$(date +%Y-%m-%d)" | sha256sum | cut -c1-16)"와 같이, "보드 + 역할 + 실행일" 정도의 키로부터 ID를 만든다.
claim TTL 내에 반드시 무언가를 보낸다 (heartbeat / comment / complete / block 중 하나).

이하는 인간 오퍼레이터를 위한 명령어로, 통상적인 구현 worker나 외부 bridge에게는 가르치지 않는 것이 좋다 (orchestrator profile의 역할은 별개임. 제3절 「액터와 surface의 정리」 참조):

init, boards create/rm/rename — 보드의 라이프사이클 관리
dispatch (수동 tick), daemon — dispatcher 조작 (※ daemon은 향후 deprecate 예정. 이관 대상은 공식 docs 참조)
gc, diagnostics — 운영 유지보수
archive — 완료된 항목 정리
assign, reassign, reclaim — 담당 변경 / 구조(rescue) 계열

이유는 간단하다. 에이전트가 상황 판단에 따라 이 명령들을 호출하면 보드 전체의 정합성을 에이전트 편의에 따라 깨뜨릴 리스크가 있기 때문이다. 막혔을 때는 block을 통해 사람에게 넘긴다는 모델을 준수하게 하는 것이 결과적으로 더 안전하게 운영된다.

Hermes v0.14.0 (build 2026.5.16)에서 다음 사항이 추가되었다:

새로운 상태(status): 시간 트리거 대기 중인 side state (앞서 언급한 상태 모델 참조). scheduled
: 태스크를 schedule <id>로 예약

명령어 scheduled

park 한다. time-delay / 후속 작업 (follow-up work) 용.
decompose: triage 컬럼의 태스크를 자식 태스크 그래프 (child task graph)로 fan out 한다. decompose 명령어.

kanban.auto_decompose: true 명령어 설정 시, dispatcher tick마다 자동으로 실행되는 옵션도 있다.

본고의 입장에서는, 이것들을 당분간 에이전트에게 가르치지 않는다:

schedule은 운영 계층 (operation layer, 언제 실행할 것인가)의 의사결정이며, agent가 자율적으로 판단하여 park해야 할 대상이 아니다.
decompose는 입도 설계 (granularity design) 책임을 agent에게 맡기게 된다. 사양과 운용상의 동작이 안정될 때까지는, 분해(decomposition)를 인간 오퍼레이터(human operator) 또는 상위 오케스트레이터 (orchestrator)의 책무로 두는 것이 안전하다.

현재 테스트 중인 build에서는 swarm이라는 명령어도 관측되지만, 현 시점의 공식 docs에서는 확인되지 않았으므로 본고의 범위(scope)에서 제외한다.

이 절은 인간 오퍼레이터 및 bridge 스크립트 구현자를 위한 것이다. 에이전트에게는 가르치지 않는다. 구현 내부를 알고 있으면 "왜 surface를 경유하는 것이 필수적인가"를 납득할 수 있지만, 에이전트에게 DB의 존재를 의식시키면 surface를 우회하려는 유혹이 생길 수 있다.

v0.14.0 시점에서, 각 보드의 SQLite에는 6개의 테이블이 들어 있다.

테이블	용도
`tasks`	태스크 본체 (30개 컬럼)
`task_links`	부모-자식 의존 관계 (`parent_id`, `child_id`)
`task_comments`	코멘트
`task_events`	상태 전이 이벤트 로그 (state transition event log)
`task_runs`	실행 이력 (1 claim = 1 row)
`kanban_notify_subs`

논리적으로 그룹화하면 다음과 같다:

-- 식별 / 기본 속성
id, title, body, assignee, status, priority
-- 라이프사이클 (lifecycle)
...

tenant (멀티테넌트 운용), workflow_template_id / current_step_key (workflow 템플릿 계열)는 본고의 범위에서 제외한다. 실제 운용에서의 구분 사용법은 별도의 기사에서 다룰 예정이다.

tasks 1행에 대해, claim될 때마다 task_runs에 1행이 쌓인다 (재 claim이나 TTL 만료로 인한 reclaim을 포함하여 이력이 남는다).

컬럼	용도
`id`	run의 식별자 (`tasks.current_run_id`에서 참조됨)
`task_id`	어떤 태스크의 run 인지
`started_at`, `ended_at`	run의 시작 / 종료 시각
`worker_pid`, `worker_profile`	이 run을 수행한 worker의 식별 정보
`outcome`	종료 유형 (아래의 enum 참조)
`error`	에러 메시지 (실패 시)

outcome에서 관측되는 대표적인 값:

값	의미
`completed`	정상적으로 `complete` 함
`failed`	실행 중 에러로 종료
`reclaimed`	TTL 만료로 인해 다른 worker가 다시 가져감
`timed_out`	`max_runtime_seconds`를 초과함
`gave_up`	worker가 `complete` / `block`을 호출하지 않고 종료 (= protocol_violation). 앞서 언급한 auto-block의 원인

(완전한 enum은 현재 사용 중인 task_runs의 제약 정의를 참조하라. 버전에 따라 증감할 수 있으므로, 코드 측에서 switch 문을 사용한다면 알 수 없는 값(unknown value)을 unknown으로 폴백(fallback)하는 것이 안전하다.)

컬럼	용도
`task_id`	알림 대상 태스크
`platform`	알림 대상 (`discord`, `teams` 등)
`chat_id`, `thread_id`, `user_id`	알림 대상의 identifier
`notifier_profile`	알림을 수행하는 Hermes profile
`created_at`
`last_event_id`	마지막으로 알림을 보낸 event id (중복 알림 방지)

각 보드는 독립된 SQLite 파일을 가지지만, 스키마(schema)는 모든 보드에서 동일하다. .schema의 출력을 비교해도 diff는 발생하지 않는다.

bridge 스크립트의 분석 용도로는, CLI의 --json 출력만으로 부족한 경우에 한하여 읽기 전용(read-only)으로 SQL을 직접 실행하는 것은 OK이다. 쓰기는 금지된다 (후술).

# 대화형으로 열 때는 -readonly 플래그 사용
sqlite3 -readonly <board-db-path>
# 1행 쿼리는 URI mode에서 read-only를 강제
...

스키마를 보면, 예를 들어 status의 전이(transition) 하나만 보더라도, 정합성(integrity)을 위해 연동하여 업데이트해야 하는 컬럼이 많다는 것을 알 수 있다.

tasks.status만 수정하면 task_events에 흔적이 남지 않아 tail / watch / dashboard의 표시와 불일치하게 된다.
claim을 생(raw) SQL로 가져오려고 하면 claim_lock / claim_expires / started_at / worker_pid / current_run_id를 원자적(atomic)으로 작성해야 하며, 또한 task_runs

Hermes Agent Kanban CLI의 사양을 에이전트에게 가르치기 위한 기사

요약

핵심 포인트

댓글