Greco エージェントハーネス設計 v2.1¶
- 日付: 2026-07-13 / 作成: coordinator (Claude) / 対象: Greco（旧称 waste-link）の AI 開発運用そのもの
- 2026-08-13 改訂: ブランドを Greco へ改名。Linear 退役に伴い、進行管理の参照を Notion + beads へ追随（本文 3 箇所）
- 入力: ①現行ハーネス（v1.14.0〜v1.21.0 を実出荷した実運用機構の棚卸し）②参照3記事（note・masa_wunder）全文（ユーザーのログインセッションで読了・v2.0 の「公開部のみ」から更新）
- 記事1: ループエンジニアリングの本質論（eval-loop の完全実装: 採点設計・Stop hook・状態ファイル・snapshot）
- 記事2: あなたのループは本当に機能しているか（閉ループの検証: live-trial / iter-improve・採点を腐らせない8不変条件）
- 記事3: エージェント共創の設計パターン（akapen / bestofn・人間 judge の差し込み）
1. 定義¶
ハーネス = エージェントを「安全に・高出力で・積み上がる形で」回し続けるための機構一式。 構成は 4 系統: ループ（仕事の回し方）・ゲート（品質と権限の関所）・記憶（学習の恒久化）・復旧（すべて再開可能にする状態設計）。
中核思想（記事1）: プロンプトを打つのではなく、プロンプトを与えるループそのものを設計する。ループの価値は回数ではなく「止め方」で決まる — ①仕事を「採点できる停止条件」に翻訳し（採点設計）、②続行判定を人から機械（決定論的比較）へ渡せたとき、初めてループは無人で品質に収束する。
2. 現状ハーネス（v1）の棚卸し — 実出荷 8 リリースで実証済みの機構¶
トポロジ（記事2の「運転役/被験役の分離」と同型）¶
- Coordinator（Claude）= 運転役: 要件整理 / 設計・spec / dispatch / 監視 / レビュー / verify / PR / リリース / Notion・beads 同期。実装は原則しない（例外: 表示のみの小粒・緊急バグ）。
- Worker（codex CLI）= 被験役: 1機能 = 1 子worktree = 1 codex。orca terminal（= 記事2の tmux 相当: send-keys→
terminal send/ capture→terminal read）で運転。モデル固定はユーザー専権・sub-agent 禁止・commit のみ。 - Human（ユーザー）: main への squash マージ +
human-reviewedラベル・ロードマップ判断・モデル/プラン変更（= D3）。
記事2の指摘どおり、この分離のレバレッジは「高い運転役 1 体 + 安い/並列の被験役」と「本物の環境で本物の成果物が出る」こと。モックでなく実 worktree・実 docker・実 CI で検証している現行構成は記事の推奨と一致する。
ループ（2 階建て・記事1の内側/外側と対応）¶
- 外側ループ = coordinator の「タスクを 1 件ずつ取り出し→dispatch→完了→次へ」+ Monitor によるイベント駆動供給。
- 内側ループ = worker の per-task TDD（RED→GREEN→commit）+ 検証コマンド。
- dispatch: 正典 spec を
.worker-specs/<task>.md、ポインタ 1 行を send。監視: Monitor（bounded・idle/質問/降格/commit 検知で 1 回 emit）。
ゲート階層（内→外）— 記事1の「○×で済む部分は CI でよい」の実装¶
| # | ゲート | 実体 |
|---|---|---|
| G1 | per-task | worker 内 TDD + tsc/lint/当該 test |
| G2 | whole-branch | coordinator が final-verify.sh（CI 同一）を独立再実行（自己認定禁止） |
| G3 | DB 実証 | docker 全 proof（新規だけ流すの禁止） |
| G4 | クロスモデル | maker=codex / checker=Claude。prod-critical migration は敵対的レビュー |
| G5 | CI | security → merge（develop は恒久承認済） |
| G6 | 人間 | main のみ: ラベル + squash。タグ/デプロイ監視は coordinator |
| G7 | リリース QA | 統合 develop で G2+G3 再実行 + delta semgrep + データ移行評価 + open PR 棚卸し |
記憶 / 復旧¶
- memory（Why+How 付き 1 事実 1 ファイル）+ AGENTS.md 不変条件 + beads・Notion 照合。
- 状態は git + scratchpad + memory の 3 層のみ（会話・terminal に状態を持たせない = 記事1「状態は会話でなくファイル」と同義）。
3. 3記事の実践知 → 現行との突き合わせ（全文読了版）¶
| 記事の機構 | 現行対応物 | 判定 |
|---|---|---|
| 内側/外側ループの 2 階建て | coordinator 外側 + worker TDD 内側 | ✅ 同型 |
| 状態はファイル（state.json / turns/） | git commit・.worker-specs・報告 | ✅ 同義（git が turns/ を兼ねる） |
| 続行判定の機械化（Stop hook 整数比較） | verify の exit code・CI 必須チェック | ✅ ○×領域は機械化済み。△ ○×に落ちない質の採点ループは未導入（§4.8 で条件付き採用） |
| 採点する係の 4 契約（fork・基準書換禁止・絶対評価・実物を開く） | クロスモデルレビュー（別モデル・fresh・diff 実読） | ✅ 概ね充足。「基準書換禁止」= テスト/アサーション弱化禁止は実践済み（apportion render テスト再調整時にアサーション不変を明示）→ §4.5 で規律として明文化 |
| グッドハート / 目標ドリフト（毎周依頼文を渡し直す） | dispatch spec に正典 path を毎回明記 | ✅ 実践済み → 明文化 |
| 完了判定 = 成果物が出た ∧ 動作停止（経過時間で判断しない） | Monitor v4 = lastOutputAt 停滞 + git commit 実測 | ✅ 同結論に独立到達 → §4.2 に二条件として明文化 |
| ハーネス自体の smoke test | 無し（監視スクリプトの検証は実測頼み） | ✗ 採用（§4.5） |
| snapshot（git 隠し ref に最良版冷凍） | git commit 履歴（per-task commit が兼ねる） | ✅ 代替済み・追加不要 |
| iter-improve の 8 不変条件（採点を腐らせない） | 部分的（アサーション不変・実走 proof 必須） | ✗→採用: §4.5 に規律として統合 |
| 手順遵守検査（成果は正しいが手順を外した） | 「報告と git 実測の一致」確認 | ✅ 実践済み → チェックリストに明文化 |
| akapen（これでいいか・赤ペン）/ bestofn（どれがいいか・N案選択） | AskUserQuestion（+preview） / spec ユーザーレビュー | △: D2 の実装選択肢として §4.3 に統合。plugin 導入は見送り（既存機構で代替・第三者コード導入は D3） |
| 開催規律（自己検証できるなら開催しない・承認疲れ） | — | ✗ 採用: §4.3 に judge 開催規律を追加 |
4. v2.1 設計¶
4.1 トポロジ（変更なし）¶
v1 のまま。運転役=Claude / 被験役=codex / 人間=D3。並行 luna は資源ガバナ（§4.6）が上限。
4.2 ループ標準形¶
dispatch spec テンプレ（必須節）: 正典 / 済み（触らない）/ これから / 接地（実シンボル列挙）/ 停止点 / 判断等級候補 / 完了報告 / 運用。
受け入れ基準の書き方（記事1の採点設計を適用）:
- あいまい形容詞を数えられる事実へ翻訳する（「読みやすく」→「1文平均60字以下」型）。判定はアルバイトテスト（チェックリストで第三者が○×を付けられるか）。
- ○×に落ちない質（設計の筋・UI の意匠）は「観点 + 重み + 何点はどういう状態か」の形でレビュー観点に渡す（G4 のレビュー prompt に観点列挙）。
- 目標ドリフト対策: 毎 dispatch で正典 spec の path を渡し直す（会話の記憶に依存しない）。
完了判定の二条件（記事2と同結論・明文化): 完了 = 成果物（新 commit / clean tree）∧ 停止（lastOutputAt 停滞）。経過時間だけで完了と判断しない。IDLE だが成果物なし → 調査（self-update / 質問 / 停滞）。
監視 = Monitor v4 標準: lastOutputAt 停滞×6(120s) / 質問 tight regex / composer 行 gpt-5.4 / （必要時）新 commit。sleep ベース bash 監視は禁止。
4.3 判断等級 D0-D3（無断進行ガード）+ judge の差し込み方（記事3）¶
| 等級 | 定義 | 挙動 |
|---|---|---|
| D0 | 慣例・規約で決まる | 黙って既定で進む |
| D1 | 合理的既定があるが好みが分かれる | 既定で進み、完了報告で「既定判断」として一括列挙 |
| D2 | 既定を置けない / 影響が非対称 | 止めて聞く（自案+根拠必須・「どうしますか」禁止） |
| D3 | 人間専権 | main マージ・モデル/プラン変更・本番データ・外部公開・第三者 plugin 導入 |
| D2 の実装は 3 択（記事3の判断規律を採用）: | ||
| - これでいいか（1 案の妥当性）→ AskUserQuestion + preview（テキスト/ASCII モックで足りる分岐）。視覚差分が本質なら HTML モック提示（akapen 型: 現状再現 + 差分注記 + 3±1 問 + お任せ既定=未回答でも自律性を殺さない）。 | ||
| - どれがいいか（語彙が無い選好: 意匠・トーン・命名）→ N 案並列提示から選択（bestofn 型: 同一プロンプト N 回でなく設計軸で多様性を作る。ミニマル/リッチ/実験的 等）。 | ||
| - 開催規律: 正解が一意で自己検証できるなら開催しない（N 案 = N 倍トークン・承認疲れは人をボトルネックに戻す）。手戻りの発生点は「走り出す直前の一瞬」— judge はそこに 1 分だけ置く。 |
4.4 ゲート階層（G1-G7 維持 + G2'/G4'）¶
- G2': coordinator verify は worker 報告があっても必ず独立再実行。
- G4': prod-critical「隣接」（課金プロンプト・認可・schemas）も中間停止点。
4.5 自律改善ラチェット + 採点を腐らせない規律（記事2の 8 不変条件を統合）¶
インシデント 3 点セット（従来）: 即時対処 + 機構修正 + 記憶を同一スライスで。 採点を腐らせない規律（レビュー・検証・ハーネス改善のすべてに適用）: 1. 採点を緩めて点を稼がない — テスト/アサーション/proof/閾値の弱化で緑にすることを禁止（弱化が正当なら D2 でユーザー判断）。 2. 効果判定はまっさらな判定者のみ — 改善の自己申告を信じない。cross-model / fresh レビューで確認。 3. 収束は点数でなく目的達成で判定 — 「verify 緑」でなく「要件を満たしたか」を受け入れ確認する。 4. 再現する弱点は成果物でなく機構（spec テンプレ / 監視 / スクリプト）本体を直す — 改善 1 回分が以後すべてを底上げする側を直す。 5. 1 回の改善は 1-2 か所 — まとめて変えない（効果の切り分け不能を防ぐ）。 6. コミットは採点結果を見てから — 検証前の先回りコミット禁止。 7. 改善役と被験役は別個体 — ハーネスを直した本人の自己評価で閉じない。 8. 実走評価を読み合わせにすり替えない — docker proof・実 CI・実機（dev）で走らせる。「重いから設計書レビューで代替」を禁止。 ハーネス自体の smoke test（新規採用）: 監視スクリプト等のハーネス部品を変更したら、既知シナリオ（idle / 質問 / 降格 / self-update）に対する期待挙動を 1 回実測してから本番投入する。 手順遵守検査: worker の完了報告は必ず git 実測（log/diff/status）と照合（成果は正しいが手順を外した、を検出）。
4.6 資源ガバナ¶
luna 並行 1-2（3 で降格実測）/ 降格は composer 行検知→停止 or ユーザー復帰 / self-update 復旧 / docker 事前確認。コスト読み: eval 型ループは 1 周 = 生成+採点の 2 課金（記事1）— 周回上限（max）を必ず設定し、3 周連続同スコア/同指摘は堂々巡りとして打ち切り、max 到達不合格は「ループより先に採点軸（受け入れ基準）を疑う」。
4.7 復旧性¶
状態 3 層（git / scratchpad / memory）・back-merge リリース標準形（tree==develop 実測）— 変更なし。
4.8 【条件付き採用】eval-loop（採点ループ）の導入基準¶
記事1の eval-loop（採点 JSON・threshold・Stop hook）は○×に落ちない質を無人で収束させる装置。現行のコード開発は G1-G7 の機械○×+1 パスレビューで足りている（記事1自身が「○×で済むなら CI でよい」）。導入するのは:
- 対象: 文書品質（設計書/手順書）・UI 意匠の磨き込み（impeccable 収束）・プロンプト/スキル自体の改善 — 機械○×が書けず、人間レビューを繰り返している領域。
- 形: 採点 JSON は score / breakdown(キー固定) / feedback / passed。score=overall 一致・breakdown キーは周回をまたいで固定（時系列比較・報酬ハッキング対策）・絶対評価・実物を開いて採点・fork（まっさら判定者）。合格点は 90 前後を運用値とし、モデルごとの採点傾向を把握して調整。
- 判定の決定論化: 続行/停止は「score ≥ threshold ∨ iteration ≥ max」の比較のみ（coordinator の気分に委ねない）。
- 導入は必要になった時点で最小実装（このセッションの Monitor + scratchpad state ファイルで組める）。
5. 運用チェックリスト¶
dispatch 前: 正典 spec / 接地シンボル / 受け入れ基準はアルバイトテスト通過形 / D1・D2 候補列挙 / 停止点 / docker 確認 / Monitor v4 対で armed。 worker 完了時: 完了判定の二条件（成果物∧停止）/ 報告と git 実測の照合 / G2' 独立 verify / 全 proof / クロスモデルレビュー / D1 既定判断の一括報告。 リリース時: G7 フル QA / データ移行評価 / back-merge + tree==develop 実測 / CI 緑 → 人間ゲート案内 / タグ + deploy 監視 + worktree 掃除 + Notion・beads 同期。 ハーネス変更時: 採点を腐らせない規律 8 項に照合 / smoke 実測 / 3 点セット（対処+機構+記憶）。
6. 既知の失敗モードと恒久対策（実測台帳）¶
| 失敗モード（実測） | 恒久対策（機構） |
|---|---|
| sleep ベース監視が harness に kill される | Monitor ツールの bounded ループに全面移行 |
| spinner 描画崩れで誤 idle 判定 | lastOutputAt 停滞で判定（+完了は成果物∧停止の二条件） |
| 質問検知の誤発火 | tight regex（末尾 2 行 × 疑問形+coordinator 語） |
| codex 起動直後の self-update 終了 | n=0 idle → terminal 読取 → 同一 terminal 再起動 |
| luna 3 並行で gpt-5.4 へ自動降格 | ガバナ上限 1-2 + composer 行監視 + sub-agent 禁止 |
| per-task 緑でも cross-module drift | per-task tsc/lint + whole-branch 独立 verify |
| 並行 PR の migration 出順ズレ → dev push 失敗 | dev のみ --include-all（#233・prod 厳格維持） |
| squash 発散で release PR が巨大 conflict | back-merge 標準形 + tree==develop 実測 |
| 新 proof の fixture UUID 衝突 | 未使用連続ブロック採番を dispatch spec に明記 |
| Linear と実装の乖離 | リリース毎 + 週次照合（本日 19 件解消） |
| テスト再調整時のアサーション弱化リスク | 規律1「採点を緩めない」+ レビューで弱化有無を必ず確認 |
7. 本書の位置づけ¶
機械的規範は AGENTS.md / memory が正（重複させない）。本書は「なぜこの機構か」を束ねる設計書 + 失敗台帳。変更はインシデント駆動（§4.5）・四半期棚卸し。
8. v2.0 → v2.1 差分（記事全文の反映記録）¶
- §3 を全文読了版の突き合わせ表に置換（「同型と確認」9 件 / 「新規採用」4 件 / 「見送り+理由」2 件）。
- 新規採用: 完了判定の二条件（§4.2）/ 採点を腐らせない規律 8 項 + ハーネス smoke test（§4.5）/ D2 の 3 実装と judge 開催規律（§4.3）/ eval-loop の条件付き導入基準（§4.8）。
- 見送り: akapen/bestofn plugin そのものの導入（既存 AskUserQuestion+preview で代替・第三者 plugin 導入は D3 でユーザー判断）/ git 隠し ref snapshot（per-task commit が代替）。