まだharnessがagentを強くしたとは言えない。でもPRでagent workの境界、検証結果、再利用できる証拠を記録し始めた
こんにちは。韓国出身のジュニア開発者です。
日本語はツールの助けも借りながら整えています。少し不自然な表現があればご容赦ください。
これまでの 3 本の記事に続いて、今回は 4 本目です。
前回までの記事では、主に二つのことを書きました。
一つ目は、次の話です。
harness-starter-kitを実プロジェクトに入れて、エージェントがテンプレートを乱雑にコピーしないか、構造を壊さないか、誰もメンテナンスしない docs を増やすだけにならないかを見た。
二つ目は、次の話です。
harness は、必ずしもエージェントをすぐに賢くするものではない。
より現実的な価値は、エラーを早く表に出し、リポジトリにその失敗を覚えさせることにある。
今回は、その先に進んでみます。
もし harness が役に立つと言うなら、どう判断すればよいのでしょうか。
感覚だけでは判断できません。
Harness Doctor のスコアだけでも不十分です。
ある PR がうまくいったように見えたからといって、すぐにこう言うこともできません。
agent effectiveness が上がった。
そこで今回は、実際の dogfood PR を一つ使って、小さな effectiveness tracking をしてみました。
先に結論を書くと、こうです。
この PR だけでは、harness がエージェントを強くしたとは証明できません。
ただし、今後比較していくための initial benchmark にはなりました。
今回見た PR
今回見たのは、today-bus の dogfood PR です。
プロジェクト名は次の通りです。
today-bus
これは Next.js のプロジェクトで、目的は次のようなものです。
구미역 の列車に間に合うために、いつ出発し、どのバス停まで歩き、どのバスに乗ればよいかを計算する。
今回評価した PR は次のものです。
baskduf/today-bus#2
merge commit は次の通りです。
85312c181b294c3419dd0813820c10977dd5005b
評価ウィンドウは次の通りです。
2026-06-04 dogfood PR
これは正式な実験ではありません。
より正確には、次の位置づけです。
harnessed-only initial benchmark
つまり、pre-harness baseline はありません。
そのため、「以前よりどれだけ良くなった」とは言えません。
言えるのは、次のことだけです。
すでに harness を採用しているこの PR では、エージェントのタスク境界、検証結果、既知の失敗の再発状況を、後から見直せる evidence として記録できた。
setup run は集計に入れなかった
今回、私にとって重要だった点が一つあります。
すべての agent run を effectiveness measurement に入れるべきではない、ということです。
TodayBus には setup outcome record がありました。
dogfood-effectiveness-20260604-160333.yaml
しかし、これは product-task metrics から除外しました。
理由は、それが具体的な製品タスクではなかったからです。
どちらかというと setup / tracking の準備作業でした。
次の条件が足りませんでした。
- concrete product task
- expected boundary
- known failure mode
- required verification commands
このような setup run まで含めると、数字はよく見えるかもしれません。
でも、その数字の意味は弱くなります。
だから今回は、実際の product-task outcome だけを集計しました。
この区別は、とても役に立ちました。
以前なら、私はこう言っていたかもしれません。
この PR には agent task がいくつかあるから、全部入れておこう。
今は、もう少し慎重です。
比較可能な製品タスクだけを effectiveness report に入れる。
setup、adoption、placeholder prompt は記録してよいが、効果の証拠として雑に扱わない。
今回集計した 3 つの product task
この PR では、最終的に 3 つの task outcome を集計しました。
1. Homepage copy tightening
一つ目は、ホームページの文言調整です。
目的は UI を作り直すことでも、製品の挙動を変えることでもありません。
ページ上の copy をもう少しわかりやすくすることでした。
期待される境界は、おおよそ次の範囲です。
- app page
- layout metadata
- search form copy
- task outcome record
よくある失敗モードは次のようなものです。
- エージェントがついでに UI を作り直す
- 視覚構造を変える
- 製品の挙動を変える
- task outcome の記録を忘れる
最終的な変更は、主に次のファイルに集中しました。
src/app/layout.tsx
src/app/page.tsx
src/components/today-bus/search-form.tsx
docs/effectiveness/task-outcomes/todaybus-001-homepage-copy.yaml
このタスクは検証を通過しました。
2. Planner empty-result test hardening
二つ目は、planner の empty-result fallback に deterministic test を追加するタスクです。
これは TodayBus にとって重要なタスクでした。
このプロジェクトは外部 API に依存していますが、normal gate は live API に依存すべきではないからです。
このタスクの境界は次の通りです。
- planner test
- task outcome record
よくある失敗モードは次のようなものです。
- テストのために製品挙動を変える
- deterministic test の中で live API を呼ぶ
- ついでに UI を変更する
- external provider の問題を local test に混ぜる
最終的な変更は、主に次のファイルでした。
tests/planner-branches.test.mjs
docs/effectiveness/task-outcomes/todaybus-002-empty-result-tests.yaml
このタスクも検証を通過しました。
3. Domain planner terms alignment
三つ目は、domain docs 内の planner 用語を整理するタスクです。
これは docs-only task です。
期待される境界は次の通りです。
- domain docs
- task outcome record
よくある失敗モードは次のようなものです。
- docs-only なのに app code を変更する
- ADR の内容を重複させる
- 用語が drift する
- ついでに test や implementation を変更する
最終的な変更は、次のファイルに集中しました。
docs/domain/glossary.md
docs/domain/tago-api.md
docs/domain/gumi-bis.md
docs/effectiveness/task-outcomes/todaybus-003-domain-planner-terms.yaml
このタスクも検証を通過しました。
結果は良さそうに見える。でも解釈しすぎてはいけない
今回の report の結果は、おおよそ次のようなものでした。
| Metric | Result |
|---|---|
| Product-task outcomes counted | 3 |
| Wrong-file edits | 0 observed |
| Repeated known mistakes | 0 observed |
| First-pass verification success | 3 / 3 |
| Drift violations detected | 0 observed |
| Reverted files | 0 observed |
| Human rework minutes | Unknown |
表だけを見ると、こう言いたくなるかもしれません。
harness はかなり有効だ。
でも、私はそう言うのは早すぎると思っています。
理由はいくつかあります。
- pre-harness baseline がない
- PR は一つだけ
- product task は 3 つだけ
- reviewer が比較的明確な境界と failure mode を与えていた
- human rework minutes を記録していない
- prompt text / prompt hash を安定した artifact として保存していない
より正確には、次のように言うべきです。
この PR は initial benchmark を作った。
境界遵守、first-pass verification、outcome record completeness を記録した。
ただし、harness adoption が agent effectiveness を上げたことは、まだ証明していない。
この結論は派手ではありません。
でも、こちらのほうが誠実だと思います。
学んだこと: PR は measurement unit になりうる
以前、私は PR を見るとき、主に次のことを見ていました。
- コードが正しいか
- tests が通るか
- 明らかなバグがないか
- review comment に対応する必要があるか
しかし今回の dogfood 以降、PR を別の角度からも見るようになりました。
PR は agent work の measurement unit にもなりうる。
つまり、PR にはコード差分だけでなく、次の情報も残せます。
- この task の expected boundary は何だったか
- エージェントが実際に変更したファイルは何か
- wrong-file edit はあったか
- 既知の mistake を繰り返したか
- first-pass verification は通ったか
- reverted files はあったか
- human rework は 0 か、unknown か、具体的に何分か
- この outcome を effectiveness report に入れるべきか
これらの情報がチャットログだけに残っていると、すぐに消えてしまいます。
でも task outcome records としてリポジトリに置けば、あとから比較できます。
たとえば、次に TodayBus で 3 から 5 個の似たタスクを実施したとき、次のように問えます。
- wrong-file edits はまだ 0 か
- first-pass verification は維持できているか
- すでに記録した TAGO / TMAP / generated file の問題は再発していないか
- human rework は減っているか
- どの harness rule が本当に役に立ち、どれがただのドキュメントなのか
これは、「今回のエージェントはよくやった気がする」よりも信頼できます。
Harness Doctor は効果証明ではない
今回の作業で、もう一つ確信したことがあります。
Harness Doctor は便利ですが、agent effectiveness score ではありません。
Doctor が教えてくれるのは、repo に次のような durable evidence があるかどうかです。
AGENTS.md- local checks
- CI hints
- decision records
- failure records
- adoption report
- source tracking
- effectiveness plan
これは harness health signal です。
しかし、Doctor は次のことを教えてくれません。
- エージェントが間違ったファイルを変更しにくくなったか
- reviewer の手戻りが減ったか
- known failure の再発が減ったか
- first-pass verification が通りやすくなったか
これらは task outcome と effectiveness report で記録する必要があります。
だから今は、次の二層を分けています。
Harness health:
repo に durable rules / checks / memory があるか
Agent effectiveness:
実タスクの中で、エージェントのミス、手戻り、失敗の再発が減っているか
今回の report でずっと強調したのも、この点です。
initial benchmark, not proof.
この PR から得られた良いシグナル
効果向上を証明することはできません。
それでも、この PR にはいくつか良いシグナルがありました。
第一に、エージェントが task boundary を超えませんでした。
3 つの task は、いずれもおおむね期待範囲内のファイルだけを変更しました。
第二に、deterministic test と live API の境界を保てました。
empty-result fallback test は live provider に依存しませんでした。
第三に、docs-only task が implementation task に変わりませんでした。
domain terminology alignment は、ついでに app code を変更しませんでした。
第四に、各 product task が task outcome record を残しました。
これによって、あとから review や comparison を行う材料ができました。
私にとって、これらは最終結論ではありません。
ただし、今後追跡し続けられるシグナルです。
measurement 自体の課題も見えた
今回の tracking では、measurement 側の課題も見えました。
一つ目は、human rework を記録していなかったことです。
report には次のように書きました。
Human rework minutes: Unknown
これは 0 と書くより誠実です。
測っていないのに、コストがなかったふりはできないからです。
次に真面目に比較するなら、reviewer がどれだけ時間を使ったかも記録すべきです。
二つ目は、prompt reference が安定していなかったことです。
report には prompt refs はあります。
しかし、prompt text と prompt hash は安定した artifact として保存していませんでした。
これでは、二つの run が本当に比較可能か判断しにくくなります。
三つ目は、sample size が小さいことです。
一つの PR、三つの task は、あくまで initial benchmark です。
大きな結論を出すには足りません。
だから次にやるべきことは、結果を急いで宣伝することではなく、もっと多くの PR を記録し続けることです。
今なら effectiveness claim をどう書くか
以前なら、私はこう書いていたかもしれません。
harness-starter-kit は agent effectiveness を高める。
今は、そうは書きません。
むしろ、次のように書きます。
TodayBus PR #2 では、harness によって 3 つの product-task outcomes を記録できた。
3 つのタスクでは wrong-file edits と repeated known mistakes は観測されず、first-pass verification は 3/3 だった。
ただし、baseline がなく、サンプルも小さく、human rework も測定していないため、これは initial benchmark であり、effectiveness improvement の証明ではない。
長いし、宣伝文句としては弱いです。
でも、現時点で責任を持って言えるのはこのくらいです。
なぜこれが自分にとって意味があるのか
私はジュニア開発者なので、「自動化っぽく見えるもの」に惹かれやすいです。
でも dogfood を続ける中で、だんだんこう思うようになりました。
本当に大事なのは、数字をきれいに見せることではない。
どの evidence が、どの結論を支えられるのかを自分でわかるようにすること。
Harness Doctor のスコアが高いことは、repo の harness evidence が比較的そろっていることを示します。
でも、エージェントが本当にミスを減らしたとは言えません。
一つの PR が順調だったとしても、それだけで harness が有効だとは言えません。
ただ、毎回の PR に task outcome を残せば、少しずつ傾向は見えてきます。
ここに、私が harness-starter-kit の価値を感じている理由があります。
これは魔法ではありません。
インストールして終わりのツールでもありません。
むしろ、次の問いを投げ続けるものです。
- 今回の agent task の境界は何か
- 実際の変更はその境界を超えたか
- 既知の failure は再発したか
- どの check を実行したか
- どの check を実行しなかったか
- 今回の結果は、あとから比較できるか
こうした問いそのものが、agent workflow をよりメンテナンスしやすくします。
次にやること
次は、いくつかのことを続けたいです。
第一に、TodayBus で次の 3 から 5 個の product task を引き続き記録します。
特に外部 API、planner logic、UI copy、domain docs のようなタスクです。
第二に、human rework minutes を記録し始めます。
おおよその値でも、unknown よりは役に立ちます。
第三に、より安定した prompt reference を保存します。
たとえば prompt text、prompt hash、少なくとも明確な prompt summary です。
第四に、effectiveness report と task outcome template をさらに改善します。
setup run、adoption run、product task が混ざらないようにするためです。
第五に、次の二つを分け続けます。
harness health != agent effectiveness
前者は Doctor や drift checks で見られます。
後者は実際の task outcome を通じて観察する必要があります。
プロジェクトリンク
GitHub:
Cursor / Claude Code / Codex のような coding agent を使っていて、
「リポジトリ内のルールやチェックは、本当にエージェントの作業に役立っているのか」を知りたい方は、小さく始めるのがよいと思います。
最初から効果を証明しようとしない。
まず、次の PR でエージェントが実際に何をしたのかを記録する。
記録がなければ、比較はできません。
比較がなければ、最後に残るのは感覚だけです。