humanize (hmz)
humanize (hmz, https://github.com/humanfia/humanize, 문서 https://docs.humanfia.ai/humanize/)
는 코딩-에이전트 CLI (claude, codex, agy, ...)를 플로우 내에서 실행합니다: 누가
작업하고, 누가 리뷰하며, 실행이 언제 중단될지를 결정하는 루프입니다. PyPI의 uv 도구입니다 (uv tool install hmz,
~/.local/bin/hmz); hmz update로 업그레이드합니다. hmz만 실행하면 현재
디렉토리에 대한 TUI가 열리고, hmz exec는 플로우를 헤드리스로 실행하며, hmz web은 모든 작업 공간의 실행을
브라우저에서 제공합니다. 0.2.2 기준으로 작성되었습니다. 이 알파 버전은 자주 변경되므로, 이 파일보다 hmz exec --help를
신뢰하세요.
사용자 기본값 (설정에 맞게 편집)
| 설정 | 기본값 |
|---|---|
| 플로우 | rlar: Claude가 구현, Codex가 리뷰 |
| 구현자(actor) | claude/claude-opus-5-5:high |
| 리뷰어(reviewer) | codex/gpt-6.1-sol:high (때로는 :ultra) |
| 예산(budget) | budget.duration=1d, 비용 또는 토큰 상한 없음 |
사용자가 달리 말하지 않거나, 작업 공간에 저장된 기본값(아래 참조)이 없는 한 이것들을 사용하세요. 예산에 대해 묻지 마세요.
hmz exec -f rlar \
-a actor=claude/claude-opus-5-5:high \
-a reviewer=codex/gpt-6.1-sol:high \
-p budget.duration=1d \
--json "$(cat "$TASK")" > "$LOG" 2>&1
워크플로우
- 사전 점검.
~/.hmz/settings.yaml의workspaces:아래에서 디렉토리를 찾습니다. 항목이 있으면, 위의 기본값보다 해당 작업 공간의 플로우, 에이전트, 환경 및 예산을 우선시합니다.- 전달하는 모든 모델과 노력(effort)이
~/.hmz/models/<cli>.json에 존재하는지 확인합니다. hmz는 사양을 사전에 검증하지 않습니다: 잘못된 사양은 해당 사양을 사용하는 첫 번째 턴에서만 실패하므로,rlar에서 잘못된 리뷰어 모델은 구현자의 전체 첫 번째 턴 후에 드러납니다. git status를 확인합니다. hmz 에이전트는 승인 우회하여 실행됩니다. 저장소에 사용자가 생성하지 않은 커밋되지 않은 작업이 있거나, 라이브 시스템(인프라, 배포 스크립트, 자격 증명)을 변경할 수 있는 경우, 그 사실을 말하고 시작하기 전에 git 작업 트리를 제안하세요.
- 작업 파일 쓰기(다음 섹션)를 스크래치패드에 작성하고, 작업이 간단하지 않거나 느슨하게 주어진 경우 사용자에게 보여줍니다.
- 백그라운드에서 실행
run_in_background으로--json을 스크래치패드의 로그로 리디렉션합니다. 실행은 몇 시간에서 며칠까지 걸립니다. 명령어, 작업 파일, 로그 경로, 그리고 확인 방법을 보고하세요: 해당 디렉토리에서hmz를 실행하면 TUI가 실행되고,hmz web도 가능합니다. - 결과 읽기(결과 섹션 참조), 그런 다음 저장소 차이(diff)를 확인하고 완료라고 판단하기 전에 직접 프로젝트의 검사를 실행하세요. 리뷰어의 "완료"는 증거가 아니라 증거 자료입니다.
- 중단. 시작한 백그라운드 작업을 중단하세요. 사용자가 다른 실행을 하고 있는 경우가 많으므로 절대
pkill hmz를 사용하지 마세요.pgrep -af hmz를 검사하고 자신의 PID만 중단하세요. - 재개. 동일한 디렉토리에서 동일한
-f와 함께--resume을 사용합니다(아래 제한 사항 참조).
작업 작성
구현자는 작업만 보고, rlar에서는 리뷰어가 저장소를 작업과 비교하여 평가하므로,
모호한 작업은 끝없는 리뷰 라운드나 조기 "완료"로 이어집니다. 다음을 포함하세요:
- 목표: 단계가 아닌 한두 문장으로 된 결과.
- 먼저 읽기: 작업을 정의하는 파일, 사양 또는 문서(예: OpenSpec 변경, 이슈, 디자인 노트), 에이전트가 다시 발견하지 않도록 합니다.
- 완료 조건: 리뷰어가 확인할 수 있는 구체적인 승인 기준: 통과해야 할 명령어, 유지되어야 할 동작, 달성해야 할 수치.
- 범위 외: 건드리지 말아야 할 것, 사람이 필요한 작업(배포, 푸시, 삭제, 유료 서비스, 라이브 시스템 변경).
- 규칙: 커밋 정책(커밋 또는 커밋하지 않은 상태로 둘지, 메시지 스타일), 로그와 아티팩트를 저장할 위치.
파일에 작성하고 "$(cat "$TASK")"로 전달하거나, 에이전트에게 먼저 파일을 읽도록 지시하세요.
-로 시작하는 작업은 -- 뒤에 옵니다.
명령어 형태
hmz exec -f FLOW -a ROLE=SPEC[,...] [-e ROLE=SPEC[,...]] -p KEY=VALUE[,...] [옵션] 작업
-f: 플로우 이름. 내장 플로우는 기본 이름(rlar)입니다. 사용자 정의 플로우는@user/NAME(from~/.hmz/flows/NAME/)이고 프로젝트의 것은@local/NAME입니다. 또한.,/또는~로 시작하는 경로,git+URL#subdir, 또는 동일한 모듈의 다른 플로우에 대한NAME:OTHER도 가능합니다. 기본 이름은 가장 가까운 것부터 해석되므로 사용자 플로우가 내장 플로우를 가릴 수 있습니다.-a:ROLE=CLI[@PROVIDER]/MODEL[:EFFORT], 플로우가 정의하는 각 에이전트 역할당 하나씩입니다. 플래그를 반복하거나 쉼표로 구분합니다.-e:ROLE=BACKEND[@PROVIDER][/WORKDIR]환경 역할이 있는 플로우용입니다.PROVIDER는 설정에 저장된 런타임이거나, ssh 전용으로 대괄호 안의 호스트입니다:box=ssh@[user@host:22]/abs/path. 제공자가 없으면 이 머신입니다.-p: 플로우 매개변수, 매개변수 유형 또는 JSON으로 구문 분석됩니다.chat을 제외한 모든 플로우는 예산이 필요합니다:budget.duration(1d,2h30m,PT1H),budget.cost(USD),budget.output_tokens.budget.graceful=true는 마지막 턴을 끝내도록 합니다 (또는 하나의 제한에 대해budget.graceful.<limit>).--json: stdout에 NDJSON 이벤트. 결과를 읽을 필요가 있을 때 사용합니다.--resume: 이 플로우의 가장 최근 실행을 여기서 이어받습니다. 플로우를 재개할 수 있는 경우 (ralph_loop및continue_loop는 불가능).rlar를 재개하면 새로운 구현자에게 이전 구현자 세션이 아닌 마지막 리뷰만 전달됩니다.--backup NAME: 설정에 저장된 백업 대상으로 에픽을 백업합니다 (none은 끕니다).--profile-flow/--profile-environment: 실행 추적에 샘플링을 추가합니다. 느린 실행을 진단할 때만 사용하세요.- 실패한 턴은 모든 내장 루프 플로우에서 실행을 종료하므로, 루프가 재시도할 것이라고 기대하지 마세요.
플로우 선택
| 플로우 | 역할 | 사용 시기 |
|---|---|---|
rlar | actor, reviewer | 기본값. 별도 검사가 필요한 작업. 구현자가 한 세션에서 작업하고, 새로운 리뷰어가 각 라운드마다 구현자의 주장에 대해 저장소를 확인하며, 리뷰어가 완료했다고 말할 때 종료됩니다. |
chat | assistant | 한 에이전트, 한 번, 루프 없음 및 예산 없음. 질문과 작은 편집. |
goal | worker | 모델이 충족되었다고 말할 때까지 실행되는 하나의 /goal <작업> 세션. 명확한 기준이 있는 자체 확인 작업. |
continue_loop | agent | 작업을 한 번 보낸 다음, 계속해서 "계속"을 보냅니다. 하나의 컨텍스트에서 긴 작업. |
ralph_loop | agent | 동일한 작업으로 매 라운드마다 새 세션. 진행 상황은 컨텍스트가 아닌 저장소에 있습니다. |
stateful_ralph | agent | 하나의 세션, 작업이 매 라운드마다 다시 전송됩니다. |
flame_chase | first_chaser, second_chaser | 두 에이전트가 새 세션에서 번갈아 가며 작업합니다. |
사용자 플로우는 ~/.hmz/flows/<name>/__init__.py에 있습니다. ls ~/.hmz/flows/로 나열하고
사용하기 전에 역할과 매개변수에 대한 독스트링을 읽으세요. 모든 플로우의 전체 계약을 얻으려면:
~/.local/share/uv/tools/hmz/bin/python -c "import hmz.flows.builtin.rlar as m; print(m.__doc__)".
결과
- 모든 실행은
~/.hmz/epics/<cwd를-슬래시를-대시로-바꾼-경로>/<타임스탬프>/아래의 에픽이며,epic.jsonl에는 요약 이벤트가 포함됩니다:began(플로우, 작업),opened(각 에이전트 세션),usage(비용, output_tokens, 초), 그리고how필드와 함께ended: 플로우의 자체 중지 조건이 충족되면done, 그렇지 않으면stopped(다른 값이 존재할 수 있음). --json로그에는 턴이 실패할 때HarnessUnrecoverable과 같은 오류를 포함한 전체 이벤트 스트림이 있습니다. 실행이 종료된 이유를 알아보려면 그 끝을 읽으세요.usage의 결과, 비용 및 기간, 그리고 자신의 차이 확인을 보고하세요.
설정 참고 사항
- 저장된 런타임은 에이전트 CLI가
harness:로 실행되는 위치를 말합니다 (affinity:는 이전 이름이며 여전히 읽힙니다). 하네스가 설정되지 않은 다른 머신의 런타임은 여기서 CLI를 실행하는 것으로 대체되지 않으므로, 원격 호스트에 CLI가 없을 때harness: local을 설정하세요. /btw에픽에 대한 사이드 질문은btw설정이 에이전트를 지정한 경우에만 작동합니다 (설정 › 일반).hmz web실행 페이지는#/epics/아래에 있습니다.