LOOPS.md: Field Notes on Agents That Run for Days

This file exists because most agent systems die not from a weak model but from a weak harness. The model can write code; the model can review code; the model can verify its own output against a rubric it agreed to ten minutes ago. What it cannot do, on its own, is decide when to stop, when to restart, and where to write the result. That is the work of the loop.

この記事の核心的な判断はこうです。agent システムが失敗するのは、モデルが弱いからではなく、モデルを走らせる harness が弱いからであることが多い。モデルはコードを書き、コードをレビューし、rubric に照らして出力を検証できます。しかし、いつ止めるか、いつ再起動するか、結果をどこに書くかは、自分では判断できません。それらはすべて loop の責務です。

The pattern in this note treats the loop as a first-class object: roles are separated, state lives on disk, contracts are negotiated between agents before the first line of code is written, and the harness is read like a stack trace whenever something goes wrong.

ここでの鍵は、loop を第一級のオブジェクトとして扱うことです。役割を分離し、状態はディスクに書き、コードを書き始める前に contract を交渉し、問題が起きたら stack trace を読むように harness と生のプロセスを読みます。

agentic loops, Claude Code, harness design, generator-evaluator pattern, sprint planning, file-system state, contract negotiation, trace reading, deletable scaffolding.

これらは記事のテーマ索引語であり、本文の論証ではありません。記事が扱う技術範囲を読者が素早く判断するためのものです。agent ループ、コード agent、harness 設計、generator-evaluator パターン、タスク分解、ファイルシステム上の状態、契約の交渉、trace の読解、そして削除可能な足場です。

A prompt is a thing you type once and forget. A loop is a thing that runs while you sleep. The unit of leverage stopped being the prompt the moment models became good enough to follow a procedure without supervision; what matters now is the procedure.

prompt は一度入力して忘れるもの。loop はあなたが寝ている間も走り続けるものです。モデルが十分に賢くなり、監督なしで手順に従えるようになった時点で、本当にレバレッジを生むのは一行の prompt ではなく、手順そのものになりました。

The loop is short: gather, reason, act, verify, repeat.

最小のループは、情報を集める、推論して判断する、行動する、結果を検証する、繰り返す、です。

Three roles, three context windows, three system prompts. A planner that turns a vague human sentence into a sprint spec and never touches code. A generator that writes everything and is forbidden from grading its own work. An evaluator that reads diffs, launches playwright, plays the app, and is told from the first message that the code is broken and its job is to prove it.

三つの役割、三つのコンテキストウィンドウ、三つの system prompt。planner は人間の曖昧な一文を sprint spec に変えますが、コードには触れません。generator は成果物を作りますが、自分の作品を評価してはいけません。evaluator は diff を読み、Playwright を走らせ、実際に app を操作し、最初から「コードは壊れているはずだ、それを証明するのが自分の仕事だ」という姿勢で臨みます。

Mixing the roles is the most common failure I see; the model becomes sycophantic the moment it grades itself, and the loop quietly converges on slop.

最もよくある失敗は役割の混合です。モデルは自分で自分に点をつけた瞬間に、迎合的で甘く、自己正当化しやすくなります。loop 全体が静かに低品質な結果へ収束していきます。

Before the generator writes a single line, it proposes what done looks like and the evaluator pushes back. The two argue via markdown files on disk until they agree on a checklist of testable assertions.

generator は最初の一行を書く前に、「完了とはどういう状態か」を提案します。evaluator は反論と補足を担当します。両者はディスク上の Markdown ファイルを通じて交渉し、テスト可能な断言のチェックリストがまとまるまで続けます。

Twenty-seven criteria is a reasonable size for a small app; ten is usually too few and the evaluator rubber-stamps. The original spec from the planner is the boundary, but the contract is what gets graded.

小さな app なら、27 個の criteria が妥当な規模です。10 個では通常少なすぎて、evaluator は形式的に通してしまいがちです。planner の元の spec が境界を定めますが、実際に採点されるのは contract です。

Context windows lie. They compact, they rot, they hide what you said an hour ago behind a summary you did not write. A file on disk does not lie.

context window は圧縮され、腐り、以前の情報を隠します。ディスク上のファイルのほうが安定しています。長いタスクでは、モデルのコンテキストだけに頼ってはいけません。

Keep feature_list.json, progress.md, contract.md, and an append-only log.md with ## [YYYY-MM-DD] op | title entries.

機能一覧、進捗ファイル、受け入れ協定、そして追記のみで履歴を書き換えないログファイルを保持します。こうしておけば、agent がクラッシュしたり、session が切り替わったり、コンテキストを失ったりしても、ファイルを読んで状態を復元できます。

Counter-intuitively, the best behavior I see from current frontier models is the willingness to throw everything away and start over when a run goes sideways.

やや直感に反しますが、現在の強いモデルの良い振る舞いのひとつは、一回の実行が逸れたときに、あるものを捨てて最初からやり直そうとすることです。

Insert a human only when the contract itself is wrong, not when the build is.

人間が介入すべきなのは contract 自体が間違っているときだけです。build が壊れているだけなら、loop 自身に修復、再起動、再検証をさせるべきです。

Taste is gradable if you write it down. Four axes, weighted: design, originality, craft, functionality. Calibrate on three reference sites the evaluator is told are good and three it is told are slop.

センスも採点できます。前提は書き出すことです。デザイン、独創性、仕上げ、機能性の四つの軸に重みをつけ、良い参考例を三つ、悪い参考例を三つ使って evaluator を校正します。

The model will not invent taste; it will only converge toward the taste you described. The whole game is writing the rubric carefully enough that converging toward it is what you actually wanted.

モデルはセンスをゼロから発明しません。あなたが記述したセンスに向かって収束するだけです。鍵は rubric を十分に正確に書き、モデルがその方向へ最適化したときに得られるものが、まさにあなたの欲しいものになるようにすることです。

Every debugging insight I have about agent loops came from reading the raw transcript, not from running another experiment.

agent loop に関するデバッグの洞察は、生の実行記録を読むことから得られたものであり、闇雲にもう一度実験を回すことからではありません。

This is the same muscle as reading a stack trace; the difference is that the trace is written in English and most of it is the model talking to itself. Skip this step and you are tuning by vibe.

これは stack trace を読むのと同じ能力です。長い実行記録の中から、問題がどこで起き始めたかを見つけること。違いは、agent の trace が英語で書かれていて、その大半がモデルの独り言であることだけです。このステップを飛ばすなら、感覚でパラメータをいじっているのと同じです。

The harness exists to compensate for the model. As the model improves, half of what you wrote last quarter becomes overhead.

harness が存在するのは、モデルの能力不足を補うためです。モデルが進歩するにつれ、前の四半期に書いた補助構造の半分は余計な負担になるかもしれません。

Context resetting between sessions was load-bearing for one model generation and dead weight for the next; sprint decomposition was the only thing keeping a four-hour build coherent and is now a constraint on a model that holds two hours in one head.

session 間でコンテキストをリセットすることは、前世代のモデルには荷重を支える構造だったかもしれませんが、次世代のモデルには死荷重かもしれません。sprint decomposition はかつて四時間のビルドの一貫性を保っていましたが、モデルが一つのコンテキスト内で二時間分のタスク状態を保持できるようになった今、過度な分解はむしろ制約になり得ます。

The harness that grows monotonically is a harness you have stopped reading.

harness が単調に増えるだけで何も削らないなら、あなたはもうそれを真剣に見直していないということです。

When coding stops being the bottleneck, planning becomes the bottleneck. When planning is solved, verification becomes the bottleneck. When verification is automated, taste becomes the bottleneck.

coding がボトルネックでなくなると、planning がボトルネックになります。planning が解決すると verification がボトルネックになり、verification が自動化されると taste がボトルネックになります。

The whole point of the loop is to make the next bottleneck visible.

loop の意義は、物事を一度で完璧に終わらせることではなく、現在最大の制約を露わにし、次のボトルネックを見えるようにすることです。

agent の結果が良くないとき、やり直しを直接求める代わりに、まずこれを送ります：

まだやり直さないでください。先ほどの完全なプロセスに基づいて、読みやすい監査レポートを作成してください：1. 私の元の要求は何でしたか？2. あなたが最初に私の要求から逸れたのはどこですか？3. そのときどんな誤った仮定をしましたか？4. どの検証をしなかった、または弱すぎましたか？5. どの失敗を無視、軽視、または自己正当化しましたか？6. やり直すなら、contract にどの項目を追加・変更すべきですか？最後に次の周回の最小限の変更提案だけを出し、直接実行しないでください。