Claude Codeでハーネスエンジニアリングしてみた
※ サムネは妻が書いたファンアート
Claude Codeのハーネスエンジニアリングでandymori, Laura day romance, TOMOOのボーカルの特徴を分析してみた
前の記事でチラッと「試してみた」と書いたハーネスエンジニアリング、 思った以上におもしろかったのでもうちょい詳しく書きます。
今回はソフトの内容とか解析結果ではなく、ハーネス組んだ感想を書きます。
結論はある程度大きいソフトの開発ではハーネス組むのが当たり前になるだろうということ。
そもそも何を作ったの
趣味で音楽音源のボーカル解析ソフトを作ろうとした。 Laura day romanceのライブが良さすぎて、井上花月やandymoriの小山田壮平の声の特徴を分析したくなった。
それ自体の話は別記事にするとして、今回のテーマは ハーネスをどうやって作ったか。
アプリ自体の話ではなく、ハーネスでClaudeたちが仕事を回す仕組みを作った話。
ハーネスとは
前記事の繰り返しになるけど一応。
詳しい人が聞いたら怒るかもしれないけど、わいの理解はこう：
フローやゲートを明示的に設定して、AIが自己改善ループを回せるようにする仕組み
AgentTeamがClaudeに「いい感じにやっといて」するのに対して、 ハーネスは「お前はここまでやれ、次はこいつに渡せ、ここで止まれ」という設計図を人間が書く。
たとえるなら
- AgentTeam = 社員に「この案件よろしく」って丸投げ
- ハーネス = 業務フローを社内規定として文書化して回させる
...とClaudeが言っている。でかい開発だと後者が主流になっているので試してみることに。
組んだハーネスの全体像
[Claude メインエージェント] ← CEO
│
├─ 要件定義フェーズ (@pm)
│ pm ──► interviewer ──► 要件定義.md
│ ▲ │ Write
│ │ [要修正] ▼
│ └──── 最大5回 hook → Codex → codex_review.md
│
└─ 実装フェーズ (@impl_pm)
impl_pm ──► impl_agent ──► Codex ──► src/
▲ │
│ [要修正] impl_reviewer
└──── 最大5回 ◄── impl_review.md
│ [OK]
└──► qa_tester → PASS → 完了
└ FAIL → bug_triage
サブエージェントは全部で10個。 ぱっと見多いけど、それぞれの責務は一個だけ。
| エージェント | 役割 |
|---|---|
| pm | 要件定義フェーズの指揮官 |
| interviewer | ユーザーへのインタビュー・要件定義.md 執筆 |
| reviewer | 要件定義レビュー（手動トリガー用） |
| impl_pm | 実装フェーズの指揮官 |
| impl_agent | Codex に実装タスクを投げる |
| impl_reviewer | Codex に実装レビューをさせる |
| qa_tester | 実データでの E2E テスト |
| bug_triage | テスト失敗時の分類・ルーティング |
| docs_creator | README/GUIDE の初回作成 |
| docs_manager | リリース時のドキュメント更新 |
でこのハーネスは全部ClaudeとPlan Modeで対話しながら作った。 こんなことしたくて、こんな役割必要だよね？と相談しながら作る感じ。
あとはClaudeがSubagentsを勝手に作ってくれる
要件定義フェーズの仕組み
hookが自動でCodexを呼ぶ
ここが一番「おっ」ってなったポイント。
インタビュアー（interviewer）が 要件定義.md を書き込んだ瞬間、
.claude/settings.json に仕込んだ PostToolUse フック が自動で発火する。
// .claude/settings.json
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write",
"hooks": [
{
"type": "command",
"command": "bash scripts/run_codex_review.sh"
}
]
}
]
}
}
run_codex_review.sh がCodex CLIを叩いて、Codexが要件定義をレビューして codex_review.md に結果を出力。
PMがその結果を読んで「OK / 要修正 / 袋小路」を判定して、修正が必要なら interviewer に差し戻す。 これを最大5回まわす。
まじで人間は何もしなくていい。勝手にClaudeとCodexが喧嘩しているのを眺めるだけ
袋小路判定
レビューの判定に「袋小路」という概念を入れた。
Codexが要件定義に対して「技術選定どうするの」「ライブラリは何使うの」みたいな 仕様じゃなくて実装の話をしてきたとき、それ以上ループを回しても意味がない。
そういうときは「袋小路」と判定して、フィードバックを無視して強制承認。
これがないとCodexが永遠に指摘してくるのできつい。
実装フェーズの仕組み
impl_status.md で状態を永続管理
実装フェーズは impl_pm が impl_status.md というファイルで状態を管理している。
# 実装ステータス
## ループ履歴
- Iteration 1: STFT特徴量抽出 → [要修正]
- 未解決指摘: pyin の有声区間率が未実装
- Iteration 2: pyin追加 → [OK]
## 未解決指摘
（現在なし）
これがないと Claude はループを回すたびに「さて何をするんでしたっけ」ってなる。 ファイルに書いておくことで、何度ループが回っても文脈が引き継がれる。
Codex が実装 / Codex がレビューする二段構成
実装も impl_agent 経由でCodexがやる。
レビューも impl_reviewer 経由でCodexがやる。
「同じCodexに実装とレビューさせるの意味あるの」と思うかもしれないけど、
--ephemeral フラグの有無でセッションを分けているのでちゃんとフラットな視点でレビューしてくれる。
実装は codex exec（--ephemeral なし、src/ に書き込む）
レビューは codex exec --ephemeral（使い捨てセッション、impl_review.md を出力するだけ）
5回ループしても解決しなかったら
要件定義フェーズは「強制承認」するけど、実装フェーズは 強制承認しない。
コードに問題があるのに承認してリリースするのはアカンので、
5回到達した時点で impl_status.md に「要ユーザー判断」と記録して人間に判断を委ねる。
これ、要件定義と実装で判断を変えているのは意識的な設計。要件定義は「そこそこでGO」でいいけど、実装は動かないとダメなので。
バグトリアージの分類が便利
qa_testerがE2Eテストで失敗したとき、bug_triage が原因を分類してルーティングしてくれる。
| 種別 | 例 | ルーティング先 |
|---|---|---|
| A: 環境問題 | ImportError / venv 未有効化 | Claude メインエージェント |
| B: 依存関係 | Demucs クラッシュ / ffmpeg 不在 | Claude メインエージェント |
| C: API エラー | RateLimitError / ネットワーク | Claude メインエージェント |
| D: コードバグ | AttributeError / 出力ファイル欠落 | codex:rescue に委譲 |
| E: 仕様バグ | ファイル名が要件と違う / CLI 挙動不一致 | impl_pm に差し戻し |
上から順に評価して最初に一致したやつを採用するシンプル設計。
環境系は人間が直さないといけない（A/B/C）、コードバグはCodexに投げる（D）、仕様の問題なら最初からやり直し（E）という棲み分け。
やってみてよかったこと
*責務が明確なので「誰を改善すればいいか」わかる
interviewer の出力がおかしかったら interviewer.md を書き換える。
Codex のレビューがズレていたら run_codex_review.sh のプロンプトを直せばいい（Claudeの治してもらう）。
自動で回るのが快適
要件定義フェーズ、hookを仕込んでから @pm よろしく って一声かけるだけで
インタビュー → 要件定義.md 作成 → Codex レビュー → 修正 → また Codex レビュー
が勝手に動き始める。毎回レビューしてくれって言わなくていい
CodexとClaudeの使い分けが捗る*
Subagentsにどっちで動かすか記載するだけ。CodexでやりたかったのにClaudeにやらせちゃったみたいなことが減る
よくなかったこと
コンテキスト食い過ぎ
いつもの3倍くらい食っている体感。サブエージェントがそれぞれ別コンテキストを持っているので、 情報が共有されるときにトークンが嵩む。
時間かかる
全部直列で動くので、要件定義5ループ＋実装5ループとか回ると普通に数十分かかる。Codexが遅い。
ClaudeとCodexが喧嘩し始める
これはおもろい
Claude (pm) が「要件定義OKです、承認します」と言ったのに
Codex (reviewer) が「まだ不完全です、修正が必要です」と返して
Claude が「でもわたしはOKと判断しました」
Codex 「いいえ修正してください」
みたいな小競り合いが発生する。人かよ。PM（Claude）の判定ロジックをしっかり書かないと収拾つかない。
まとめ
ハーネスエンジニアリング、面倒なセットアップが最初に必要だけど、 一度回り始めると「ちゃんと意味があるな」と思えた。
- 要件定義でCodexに毎回ツッコミさせるのは正直ちゃんと機能している
- hookで自動発火するのはやばい（良い意味で）
- 袋小路判定がないと無限ループになるので必須
次は実装したソフト本体の話を書きます。
Laura day romanceのライブに行ってきた話を書いたがそこからがっつりハマっている。 ライブのセトリ順にプレイリストを作って聞いている。
恋人へとか何光年?も良いな。けどLaura day romance「祝祭」好きすぎないか？ andymoriの1984の「ファンファーレと熱狂」みたいな、非日常な言葉なんだけど、ギリ日常的な感じもある ざわッとする言葉だよね
めちゃくちゃバズっている記憶があったし、多分好きな系統だろうにCD音源聴いてほーんと思っていたkurayamisaka。 ちょっとジャンキーなライブ音源聴いたら見事ハマりました。 おじさんは追いつくのが大変だ。
