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がレビュー |
| アクター | claude/claude-opus-5-5:high |
| レビュアー | codex/gpt-6.1-sol:high（場合により:ultra） |
| 予算 | 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:でディレクトリを確認します。エントリがある場合は、そのフロー、エージェント、環境、予算を上記のデフォルトよりも優先します。- 渡すすべてのモデルと努力レベルが
~/.hmz/models/<cli>.jsonに存在することを確認します。hmzは事前に仕様を検証しません。間違ったものは、それを使用する最初のターンでのみ失敗するため、rlarの間違ったレビューモデルはアクターの最初のターン全体が終わった後に表面化します。 git statusを確認します。hmzエージェントは承認をバイパスして実行されます。リポジトリに自分が作成していない未コミットの作業がある場合、またはライブシステム（インフラストラクチャ、デプロイスクリプト、認証情報）を変更する可能性がある場合は、その旨を伝え、開始前にgitワークツリーを提案します。
- タスクファイルの作成（次のセクション）をスクラッチパッドに作成し、タスクが重要でない場合や大まかに与えられた場合は、ユーザーに表示します。
- バックグラウンドで起動し、
run_in_backgroundと--jsonをスクラッチパッドのログにリダイレクトします。実行時間は数時間から数日です。コマンド、タスクファイル、ログパス、および監視方法（そのディレクトリでhmzを実行するとTUIが開く、またはhmz web）を報告します。 - 結果を読み取り（「結果」を参照）、リポジトリの差分を確認し、プロジェクトのチェックを自分で実行してから完了と判断します。レビュアーの「完了」は証拠であり、証明ではありません。
- 停止 自分が開始したバックグラウンドタスクを停止します。ユーザーは他の実行を同時に行っていることが多いため、ベア
pkill hmzは絶対に行わないでください。pgrep -af hmzで確認し、自分のPIDのみを停止します。 - 再開 同じディレクトリで同じ
-fを指定して--resumeを使用します（以下の制限あり）。
タスクの作成
アクターはタスクのみを認識し、rlarではレビュアーがリポジトリをタスクと照らし合わせて判断するため、曖昧なタスクは無限のレビューラウンドや時期尚早の「完了」につながります。以下を含めてください：
- 目標: 手順ではなく、1〜2文で結果を記述します。
- 最初に読む: 作業を定義するファイル、仕様、またはドキュメント（例：OpenSpecの変更、Issue、設計メモ）。エージェントがこれらを再発見するのを防ぎます。
- 完了条件: レビュアーが確認できる具体的な受け入れ基準：成功する必要があるコマンド、満たすべき動作、達成すべき数値。
- 対象外: 触れてはいけないもの、および人間による対応が必要なアクション（デプロイ、プッシュ、削除、有料サービス、ライブシステムの変更）。
- 規約: コミットポリシー（コミットするかしないか、メッセージスタイル）、ログや成果物の配置場所。
ファイルに書き込み、"$(cat "$TASK")"で渡すか、エージェントに最初にファイルを読むよう指示します。-で始まるタスクは--の後に続けます。
コマンド形式
hmz exec -f フロー -a ロール=仕様[,...] [-e ロール=仕様[,...]] -p キー=値[,...] [オプション] タスク
-f: フロー名。ビルトインはベア名（rlar）、ユーザー自身のものは@user/NAME（~/.hmz/flows/NAME/から）、プロジェクトのものは@local/NAMEです。また、.、/、~で始まるパス、git+URL#サブディレクトリ、または同じモジュール内の別のフローを示すNAME:OTHERも指定可能。ベア名は最も近いものから解決されるため、ユーザーフローがビルトインをシャドウできます。-a:ロール=CLI[@プロバイダー]/モデル[:努力レベル]、フローが定義するエージェントロールごとに1つ。フラグを繰り返すかカンマ区切りで指定します。-e:ロール=バックエンド[@プロバイダー][/作業ディレクトリ]、環境ロールを持つフロー用。プロバイダーは設定に保存されたランタイム、または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: NDJSONイベントをstdoutに出力。結果を読み取る必要がある場合に使用します。--resume: ここでのこのフローの最新の実行を再開します（フローが再開可能な場合。ralph_loopとcontinue_loopは再開不可）。rlarの再開では、新しいアクターは最後のレビューのみを受け取り、古いアクターセッションは受け取りません。--backup NAME: エピックを設定に保存されたバックアップ先にバックアップします（noneでオフ）。--profile-flow/--profile-environment: 実行のトレースにサンプリングを追加します。遅い実行を診断する場合にのみ使用します。- ビルトインのループフローでは、失敗したターンは実行を終了します。ループが再試行することを前提にしないでください。
フローの選択
| フロー | ロール | 使用場面 |
|---|---|---|
rlar | actor、reviewer | デフォルト。個別のチェックが必要な作業。アクターが1つのセッションで作業し、新しいレビュアーが各ラウンドでアクターの主張に対してリポジトリをチェックし、レビュアーが完了と言ったら終了します。 |
chat | assistant | 1つのエージェント、1回の実行、ループなし、予算なし。質問や小さな編集。 |
goal | worker | モデルが達成したと判断するまで実行される1回の/goal <タスク>セッション。明確な基準による自己チェック作業。 |
continue_loop | agent | タスクを1回送信し、その後「続行」を送信し続けます。1つのコンテキストでの長時間の作業。 |
ralph_loop | agent | 毎ラウンド新しいセッションで同じタスクを実行。進行状況はリポジトリに保存され、コンテキストには保存されません。 |
stateful_ralph | agent | 1つのセッション、毎ラウンドタスクを再送信。 |
flame_chase | first_chaser、second_chaser | 2つのエージェントが新しいセッションで交代で動作します。 |
ユーザーフローは~/.hmz/flows/<name>/__init__.pyにあります。ls ~/.hmz/flows/で一覧表示し、使用前にdocstringでロールとパラメータを確認してください。任意のフローの完全な契約を取得するには：~/.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（コスト、出力トークン、秒数）、およびended（終了理由を示すhowフィールド：フローの停止条件が満たされた場合はdone、それ以外はstopped、他の値も存在する可能性があります）。 --jsonログには完全なイベントストリームが含まれ、ターンが失敗した場合のHarnessUnrecoverableなどのエラーも含まれます。その末尾を読んで、実行が終了した理由を確認します。- 結果、
usageからのコストと期間、および自分自身の差分チェックを報告します。
設定に関する注意
- 保存されたランタイムは、
harness:（affinity:は古い名前で、引き続き読み取られます）でエージェントCLIが実行される場所を示します。別のマシン上のランタイムでハーネスが設定されていない場合、ここでCLIを実行するフォールバックは行われないため、リモートホストにCLIがない場合はharness: localを設定します。 - エピックへの
/btwサイド質問は、btw設定がエージェントを指定している場合にのみ機能します（設定 › 一般）。 hmz webの実行ページは#/epics/以下にあります。