ハーネスを組む

今回は私が使っている Claude Code の開発環境について語ります。
個人事業主でありながらこれまでと変わらない、いやこれまでよりも速くバグの少ない開発を行うために組んでいる「ハーネス」の概要を説明します。
ハーネスとは日本語で「馬具」のことで本来は馬を操るためのものですが、AIをうまく操作するという意味でハーネスという言葉が使われています。

ここに至るまでにそれなりに時間がかかりました。
これで行けそうだ、という感覚が持てるまで、試行錯誤して約4カ月。
Claudeに出会ってから、曲りなりに自分でアプリ開発してみて、困った部分を調べたりyoutubeで先行して実践している人のノウハウを取り入れてみたり。それに、Anthropic公式の設定ノウハウと現状のハーネスの内容をClaudeに比較させて壁打ちしたり。

以下でざっくりとした流れを説明します。

全体像

Claude Code を立ち上げて、まず「チーフ」と会話します。
私が話す相手はこのチーフだけです。
チーフは依頼の重さを決めて、必要なら部下にあたるサブAgentに回します。
サブAgentが作って、確かめて、最後に数字つきの報告が戻ってきます。
基本的には止まらずに自走します。

完了報告を受け取り私にボールが来た段階で、次に私自身が動かしてテストを行います。
そこで問題点が判明したら、また私がチーフにボールを投げます。
これを繰り返します。

ベースの開発と、通り一遍の機械的なテストまでは、Claude Code に任せてやってくれる形です。

内容の程度により、動きを変えています。

「軽」の動き

文言や定数を直すだけのような簡単な依頼事項の場合です。
1ファイルで済んで、ロジックは触らない類のもの。

これはチーフが自分で読んで、直して、確認して、1行で報告して終わり。
サブAgentを呼ぶと無駄にトークンを消費するだけなので、簡単なものはチーフだけで完結させます。
でも影響範囲を考えて大きくなりそうだったら、そこで手を止めてチーフが「通常」に切り替えたりもします。

「通常」の動き

何らかの機能追加をする場合はほとんどはこのパターンです。
お客さん用ではなく、デモアプリなどの自分用の場合はトークン節約でほぼこのハーネスを使います。

まずはチーフが実装Agentに頼みます。
このとき「何を報告してほしいか」を先に並べて渡します。
実装Agentは要件に従って実装して、その後自分でもテストをした上でテストAgentに引き渡します。
作った本人とは違うメンバーにテストしてもらう感じです。
テストAgentは、あらかじめ設定されたテストパターンに従ってテストをします。それに加えてパターンにないものは追加でテストします。
変えたところと変えていないところが壊れていないかの両方を確認します。
バグが出たら実装Agentに差し戻します。
ただし延々と繰り返されても困るので、差し戻しは2回まで。

それでも残ったものは「残課題」として報告させて、そこで終わります。
デプロイの資材や共通部品、認証まわりを触ったときは、動かすテストに加えて、コードを読む検証も足します。

報告は「動きました」という報告だけではなく、件数や時間など数値を提示してもらいます。
ホントに？と聞くのが面倒なのでエビデンスも添えてもらう形です。

途中でDBの構造変更など大きめの変更が必要だと判断したら、私に確認してから「重」に引き上げます。

「重」の動き

DBの構造、認証、外部システムとの連携、セキュリティ、新しい画面やAPI一式。アプリに着手した初回や、重ための機能追加はこのパターンです。
OKを出すと、チーフがこれまで兼任していた設計を、設計Agentが専任で行います。

DB・画面・APIを設計してから実装Agentへ投げます。
そこから先は「通常」と同じ流れで、画面を通しで操作するテスト（E2E：End-to-End）と、テストに抜けがないかの確認を行います。
テストで設計そのものの問題が判明したら、実装Agentではなく設計Agentに戻します。

過去の失敗は台帳に残すようにしていて、同じ種類が3回たまったら、設計Agentの段階で次回以降考慮するように見直します。

記録

どの重さでも、節目ごとに進捗Agentが記録を付けます。ログです。
指示を受けた直後、実装完了、テスト完了、バグ発見のタイミング。
何をやったのかを後から追えるように。

開発とは別の部分ですが、Claude Codeに「今日の日報書いて」と指示すると、今日どんな開発を行ったのかはこの記録のファイルを Claude Code が参照して書き起こしています。

最後は私の手でテスト

フローでは省いていますが、これはあくまでも Claude Code の開発構造だけのことで、この後に私が動作確認を行って初めて完成です。
私がテストをした上で発覚した問題点は、状況とスクショを添えてチーフに戻します。原因の調査と変更の方針が決まったら、そこからまた上記のハーネスが回ります。

この形が必ずしも完成形ではないと思っていますが、納品しても問題ないレベルのアプリが作れるところまでは達しています。

おわりに

ClaudeがOpus4.8になったときには、途中で止まってしまう不具合に多々直面し、モデルをOpus4.7に下げて運用したり、最近Claudeのモデルが4.xから5.xに上がった際には、トークン消費が増えたので指示をそぎ落とす形でメンテしています。

何かいつもと違うな、と感じたときにはハーネスの見直しが必要かどうかを Claude Code と壁打ちします。
今のところは週間制限を突破するほどのトークン消費はそこまで起こっていません。残してももったいないので、余るくらいならFableを多用します。

今週は週間制限ギリギリまで使ったので、連休中に見直してみようかと思っています。モデルのエフォートを下げてみるとか。

今日はここまで。