Hermes Agent 운영 가이드: 프로필·게이트웨이·cron·Kanban 실전 운영법

Hermes를 안정적으로 운영하는 답은 모델을 자주 교체하거나 모든 일을 자동 재시작에 맡기는 데 있지 않다. 책임과 접근 범위가 다른 일은 프로필로 분리하고, gateway는 운영체제가 복구할 수 있는 범위와 사람이 판단해야 할 범위를 구분하며, cron은 시작 시각만 맡기고 재시도·의존성·검토·감사는 Kanban 카드에 남겨야 한다. 이 글은 Hermes Agent v0.18.2를 기준으로 여러 역할과 반복 작업이 함께 돌아가는 환경에서 검증 가능한 운영 규칙을 설명한다. 첫 점검은 hermes status, hermes profile list, hermes gateway status, hermes cron status 순서로 현재 상태를 읽는 일이다. 상태를 모른 채 설정을 덮어쓰거나 서비스를 재시작하면 원래 장애와 새로 만든 장애를 구분할 수 없다. 각 명령의 결과는 정상 문구 하나가 아니라 대상 프로필, 최근 실패, 마지막 변경, 다음 판단의 소유자를 보여 주는 증거로 취급해야 한다. 이 원칙만 지켜도 자동화의 편리함은 유지하면서 권한 혼선, 중복 실행, 설명할 수 없는 복구를 크게 줄일 수 있다.

빠르게 훑어보기

• 프로필은 말투가 아니라 메모리·설정·cron·권한의 경계다. 책임 또는 데이터 범위가 다를 때만 나눈다.
• gateway 장애의 첫 대응은 상태와 로그의 비교다. launchd의 자동 복구 여부를 보기 전에는 재시작하지 않는다.
• cron은 “언제 시작할지”를 맡고, Kanban은 “무엇을 어떤 증거로 끝낼지”를 맡는다.
• 산출물과 테스트가 준비된 build 작업은 리뷰 대기라는 이유만으로 멈추지 않는다. 리뷰는 독립 단계로 다룬다.
• 공개 문서와 로그에는 계정, 개인 경로, 사설 주소, 인증 문자열을 넣지 않는다.

1. 운영 구조를 먼저 나눈다

Hermes는 터미널, 메신저, 정기 실행, 도구 호출, 메모리와 스킬을 하나의 런타임으로 묶는다. 이 기능을 한 프로필에 전부 쌓으면 실패 원인과 권한 경계가 사라진다. 반대로 역할을 너무 잘게 쪼개면 상태가 흩어지고 책임자가 불명확해진다. 실전 기준은 단순하다. 읽어도 되는 데이터, 외부 발신 범위, 실패를 검토하는 사람, 장기 메모리의 성격 중 하나라도 달라지면 분리를 검토한다.

초기 배치는 보통 세 역할이면 충분하다. 조율 역할은 카드와 handoff를 관리한다. 운영 역할은 상태 점검과 검증 증거를 담당한다. 생산 또는 연구 역할은 산출물을 만든다. 독립적인 판정이 필요해질 때만 리뷰 역할을 추가한다. 별명이나 성격보다 “누가 이 변경을 실행할 수 있고 누가 승인할 수 있는가”를 로스터에 적어야 중복 조치가 줄어든다.

hermes profile list
hermes profile show <PROFILE_NAME>
hermes profile create <NEW_PROFILE_NAME>

새 프로필을 만든 직후에는 외부 채널과 정기 실행을 바로 연결하지 않는다. 역할 문서에 목적, 금지 행위, 허용 데이터, 실패 시 handoff 위치를 적고 단발성 작업으로 출력 경계를 확인한다. 동작은 하지만 잘못된 위치에 기록하거나 예상 밖 채널로 발신하는 초기 오류를 이 순서가 막는다.

시나리오: 두 역할이 같은 gateway를 감시한다

두 프로필이 같은 서비스를 감시하면서 모두 재시작 권한을 가지면, 정상 복구 직후 다른 감시자가 오래된 상태를 보고 다시 조치할 수 있다. 이 경우 운영 담당자 한 명만 상태를 바꾸고, 나머지 역할은 시간·관찰 값·이미 확인한 결과만 handoff로 남긴다. 관찰과 조치의 소유자를 분리하면 재시작 로그가 원인을 덮는 경쟁 조건을 피할 수 있다.

2. gateway는 증거를 모은 뒤 조치한다

gateway는 메시지와 에이전트 실행을 잇는 입구다. 프로세스가 존재한다고 연결이 정상인 것은 아니다. 올바른 프로필과 서비스가 실행 중인지, 필요한 플랫폼만 연결됐는지, 복구 정책이 한 곳에만 있는지를 함께 봐야 한다.

macOS에서는 launchd가 첫 번째 복구 계층이다. 서비스가 비정상 종료했을 때 KeepAlive 정책이 있다면 운영자가 먼저 개입할 필요가 없다. 아래는 상태 변경 없이 서로 다른 층의 신호를 비교하는 점검이다.

hermes gateway status
launchctl list | grep '<SERVICE_LABEL>'
grep -i 'error\|failed' <PROFILE_HOME>/logs/gateway.log | tail -20

첫 줄은 Hermes가 보는 상태, 둘째 줄은 운영체제가 보는 서비스, 셋째 줄은 최근 실패 범주다. 세 증거가 서로 다를 때만 원인을 더 좁힌다. 이미 정상 상태로 복구됐다면 수동 재시작은 하지 않는다. 재시작은 진단 도구가 아니라 상태를 바꾸는 조치다.

시나리오: 응답이 끊겼지만 서비스는 살아 있다

프로세스와 gateway 상태가 모두 살아 있는데 특정 채널만 응답하지 않으면, 전체 재기동보다 연결 범위를 확인해야 한다. 마지막 변경 시각, 해당 채널의 허용된 health 신호, 최근 오류 범주를 비교한다. 전체 gateway를 재시작하면 정상 채널까지 끊기고 관찰 가능한 원인이 사라질 수 있다. 채널별 증거가 부족하면 운영 담당자에게 Signal·So What·Action 형식으로 넘긴다.

시나리오: 변경 뒤 재기동이 필요하다

정책상 권한을 받은 담당자가 원인을 확인한 경우에만 재기동한다. 재기동 전후에 같은 상태 명령을 사용해야 변경 효과를 비교할 수 있다.

hermes gateway status
hermes gateway restart
hermes gateway status

성공 판정은 명령의 종료 상태만으로 내리지 않는다. 재기동 뒤 상태, 연결 로그, 사용자가 실제로 다시 연결됐는지를 각각 확인한다. launchd 환경에서 터미널과 서비스의 실행 경로가 다를 수 있으므로, 서비스 스크립트는 셸 초기화에 기대지 말고 필요한 실행 경로를 명시한다.

3. cron은 얇게, 작업 수명은 Kanban에 둔다

cron은 반복의 시계다. 매일 요약을 시작하거나 변화가 있을 때만 알리는 감시에 적합하다. 그러나 재시도, 의존성, 코드 검토, 빌드 검증, 사람 승인이 필요한 일을 하나의 cron에 모두 넣으면 실패가 숨는다. 규칙은 cron은 시작 시각, Kanban은 목표·증거·후속 판단이다.

다음 질문 중 하나라도 예라면 카드로 옮긴다.

1. 실패 뒤 재시도 또는 검토가 필요한가?
2. 다른 작업이 끝나야 시작하는가?
3. 조용한 실패의 비용이 큰가?
4. 변경 결과를 사람이 추적하거나 승인해야 하는가?

전부 아니라면 멱등적인 watcher처럼 짧은 작업은 cron에 남아도 된다. watcher는 변화가 없을 때 빈 출력으로 끝나고, 새 정보가 있을 때만 메시지를 만들어야 잡음과 비용을 줄일 수 있다.

hermes cron list
hermes cron status
hermes cron run <JOB_ID>

시나리오: 일일 보고서가 성공이라고 말하지만 파일이 없다

stdout의 “완료” 문구는 증거가 아니다. 산출물 작업은 파일 유형, 개수, 크기 또는 갱신 시점을 완료 기록에 남긴다. 최근 결과가 없으면 스케줄러, 입력, 쓰기 권한, 외부 의존성, 모델 고정값을 분리해서 확인한다. 재시도가 중복 발행을 만들 수 있다면 먼저 부작용을 막고 카드로 전환한다.

RESULT=OK
ARTIFACT=<PUBLIC_OR_REDACTED_IDENTIFIER>
FRESHNESS=<UTC_TIMESTAMP>
COUNT=<NUMBER>
NEXT=<NEXT_ACTION_OR_NO_OP>

시나리오: 같은 tick이 두 번 실행된다

발행·알림·외부 쓰기처럼 중복 비용이 있는 작업에는 입력 버전이나 날짜를 포함한 멱등 키가 필요하다. 이미 만든 결과를 다시 만들지 않는지 먼저 확인하고, Kanban seeder라면 같은 날짜·같은 업무가 한 장의 카드로 수렴하게 한다.

hermes kanban create "일일 검증" --assignee <PROFILE_NAME> \
  --idempotency-key "daily-verification-$(date -u +%F)"

실제 실행 전에는 프로필 목록과 기존 카드를 확인한다. 존재하지 않는 담당 이름은 조용히 준비 상태에 남을 수 있으므로, 이름을 추정해 넣지 않는다.

4. Kanban은 작업 이력과 다음 판단을 남긴다

Kanban 카드에는 목표, 수용 기준, 담당자, 부모 작업, 코멘트, 실행 이력이 남는다. cron이 카드를 만들고 dispatcher가 준비된 카드를 실행하며, 작업자는 결과와 증거를 남긴다. 이 구조의 목적은 바쁨을 보여 주는 것이 아니라 실패가 어디에서 멈췄고 다음 행동이 무엇인지 보이게 하는 것이다.

hermes kanban show <TASK_ID>
hermes kanban list --mine

작업자는 시작 시 카드 전문과 부모 handoff를 읽고, 전용 작업 공간에서 산출물을 만든다. 긴 실행이면 처리 단계나 검사 수를 heartbeat에 남긴다. 끝났을 때는 변경 파일, 실행한 검증, 종료 상태, 남은 위험을 구조화한다.

시나리오: build는 끝났고 독립 리뷰만 남았다

산출물과 테스트가 준비됐다면 build 단계는 완료한다. 리뷰가 필요하다는 사실은 PR과 리뷰 카드에 남기고, build를 막힌 상태로 두어 후속 의존성을 멈추게 하지 않는다. 다만 이 카드처럼 리뷰 결과 없이는 다음 행동을 결정할 수 없는 경우에는 검토 요청을 명확히 남기고 기다린다. 중요한 것은 “생산 완료”와 “병합 승인”을 같은 상태로 취급하지 않는 것이다.

시나리오: 카드가 ready인데 실행되지 않는다

동시성 부족이라고 먼저 결론 내리지 않는다. 부모 카드가 실제로 완료됐는지, 담당 프로필이 존재하는지, 최근 이벤트에 재실행 방지 사유가 있는지, 열린 변경 요청과 충돌하는지를 차례로 본다. 추측을 늘리기보다 확인한 사실과 아직 확인하지 못한 항목을 구분해야 다음 담당자가 같은 진단을 반복하지 않는다.

handoff 형식

Signal: <관찰한 변화 또는 실패>
So What: <서비스·사용자·후속 작업에 주는 의미>
Action: <다음 담당자가 실행하거나 판단할 한 가지>
Evidence: <검증 명령, 종료 상태, 공개 가능한 산출물 식별자>

이 형식은 오류 로그 전체를 붙이는 대신 다음 판단에 필요한 정보만 남긴다. 원인이 확정되지 않았다면 가설을 사실처럼 쓰지 않는다. 새 정보가 없을 때는 보고를 키우지 않고, 사람의 결정이 필요한 시점에 원인·영향·선택지를 짧게 올린다.

5. 공개 문서와 자격 증명의 경계

운영 가이드는 현실적인 예시가 있어야 하지만 현실의 식별자를 노출해서는 안 된다. 공개 대상 Markdown, 스크린샷, 빌드 로그에는 계정명, 개인 전화번호, 메일 주소, 개인 장비 경로, 사설 네트워크 주소, 채널 식별자, 인증 문자열을 넣지 않는다. 예시는 <PROFILE_HOME>, <SERVICE_LABEL>, <CREDENTIAL_VALUE>, <CHAT_IDENTIFIER>처럼 치환한다.

문서에 치환값이 있다고 해서 검사를 생략할 수는 없다. 발행 전에는 콘텐츠와 생성된 결과물 모두에서 의심되는 값을 찾고, 탐지 규칙은 설명 문구와 분리한다. 단순 문자열 검색은 교육용 문장까지 잡을 수 있으므로 실제 규칙은 허용된 플레이스홀더와 형식 검증을 함께 사용한다. 자격 증명은 검토 가능한 설정과 섞지 않고 전용 저장소 또는 환경 주입 경로에 둔다. 연구·콘텐츠 역할이 운영 credential을 읽을 이유가 없다면 그 접근을 주지 않는 것이 가장 단순한 방어다.

시나리오: 공개 장애 보고를 작성한다

원문 로그를 붙이지 않는다. 관찰한 실패 범주와 복구 여부만 재구성한다. 예를 들어 “연결이 끊겼고 서비스는 실행 중이며 초기화 실패가 관찰됐다”는 정보는 판단에 충분하다. 실제 주소, 계정, 원문 경로가 없어도 운영 담당자는 다음 조치를 결정할 수 있다. 공개 가능한 정보만으로 재현 가능한 판단을 만드는 것이 목표다.

6. 운영 점검 루틴

매일 모든 서비스를 손으로 확인할 필요는 없다. 실패 비용과 변화 빈도에 따라 점검 주기를 다르게 둔다.

일일 점검은 짧아야 지속된다. 이상 징후를 보자마자 설정을 바꾸기보다 실제 장애, 자동 복구 중, 오래된 상태 표시, 사람 판단 대기 중 어디에 속하는지 분류한다. 주간 점검에서는 최근 결과물의 갱신 시점과 카드의 검증 증거를 함께 본다. 월간 점검에서는 사용하지 않는 권한과 같은 조치를 실행할 수 있는 중복 역할을 없앤다.

FAQ

Hermes 운영을 시작할 때 무엇부터 확인하나

버전, 런타임, 프로필, gateway, cron을 각각 확인한다. hermes --version && hermes status && hermes profile list && hermes gateway status && hermes cron status를 실행하면 현재 상태를 한 번에 훑을 수 있다. 오류가 보이면 다음 명령을 실행하기 전에 어떤 프로필과 구성요소에서 나온 신호인지 기록한다.

프로필은 언제 분리해야 하나

데이터 접근, 외부 발신 권한, 실패 책임, 장기 메모리 범위 중 하나라도 다르면 분리를 검토한다. 먼저 hermes profile list로 현재 프로필을 보고, 새 역할의 책임 문서를 만든 뒤 hermes profile create <NEW_PROFILE_NAME>으로 최소한의 프로필을 만든다. 말투가 다르다는 이유만으로 만들 필요는 없다.

gateway가 응답하지 않으면 바로 재시작해도 되나

아니다. 먼저 hermes gateway status와 launchctl list | grep '<SERVICE_LABEL>'로 자동 복구 여부를 확인한다. 이미 정상 PID가 있으면 재시작하지 말고 최근 오류 범주를 조사한다. 재시작 권한이 명시된 담당자라면 원인 확인 후 hermes gateway restart를 실행하고 다시 상태를 확인한다.

cron과 Kanban은 어떻게 나누나

정기 시각에 시작하는 일은 cron에 둔다. 재시도, 의존성, 리뷰, 산출물 검증, 사람 승인이 하나라도 필요한 일은 Kanban 카드로 넘긴다. 확인은 hermes cron list와 hermes kanban show <TASK_ID>로 시작한다. cron은 얇은 seeder가 되고, 카드가 실행 이력과 증거를 가진다.

cron 작업 이름은 어떻게 붙이나

<PROFILE>-<AREA>-<ACTION>처럼 소유자·업무 영역·행동이 보이게 한다. 이름을 바꾸기 전에는 기존 참조를 조사하고 새 이름을 병행한 뒤 옮긴다. 변경 후에는 hermes cron status로 스케줄러와 마지막 실행을 재확인한다.

Kanban 카드가 리뷰만 남았을 때 어떻게 하나

build 산출물과 테스트가 준비됐다면 build 단계는 완료하고 후속 리뷰를 연다. 사람의 결정 없이는 논리적으로 진행할 수 없는 경우에만 멈춤 상태를 쓴다. 상태를 바꾸기 전 hermes kanban show <TASK_ID>로 부모·자식·최근 실행 요약을 확인한다.

긴 작업의 heartbeat는 언제 남기나

수 분 이상 걸리는 빌드, 대량 검사, 크롤링, 변환 작업에는 진행 증거를 주기적으로 남긴다. heartbeat에는 “작업 중” 대신 처리량이나 단계처럼 판단 가능한 정보를 쓴다. 예를 들어 검증 42/100 완료, 실패 0처럼 적으면 stale 실행과 정상 장기 실행을 구분할 수 있다.

공개 가이드에서 무엇을 치환해야 하나

계정, 개인 경로, 사설 주소, 채널 식별자, 인증 문자열을 전부 치환한다. 예시는 <PROFILE_HOME>이나 <CREDENTIAL_VALUE>를 사용한다. 발행 전에는 생성된 HTML까지 검사하고, 변경 범위는 git diff -- src/content/guides/hermes-operations-guide.md로 확인한다.

설정을 바꾼 뒤 어떤 검증을 하나

설정 형식을 확인한 뒤 실제 명령으로 효과를 본다. gateway 변경이면 hermes gateway status, cron 변경이면 hermes cron status와 필요 시 hermes cron run <JOB_ID>, 프로필 변경이면 hermes profile show <PROFILE_NAME>을 실행한다. 파일만 수정하고 서비스 상태를 추측하지 않는다.

작업이 끝났다는 증거는 무엇인가

사람의 서술이 아니라 산출물과 검증 결과다. 변경 작업이라면 변경 파일, 실행한 검사 명령, 종료 상태, 변경 요청 또는 검토 위치를 남긴다. 자동 작업이라면 결과 파일의 신선도·개수·크기 같은 계약을 남긴다.

참고 자료

• Hermes Agent 공식 문서
• Hermes Cron 기능 문서
• Hermes Kanban 기능 문서
• Hermes Profiles 문서
• Princeton의 GEO 연구: Generative Engine Optimization

변경 이력

• 2026-07-16 · Guide v1.1 · 중복 워크북을 시나리오별 판단 절차로 압축하고, 공개 메타데이터 노출 경로를 제거했다.