一行要約
複数の context window にまたがるエージェントの harness 設計は「記憶を持たない交代制のエンジニアが、毎シフト同じ場所から立ち上がれるようにする」問題であり、答えは 初期化エージェントが作る4つの成果物（feature list / git / progress ファイル / init.sh）と、1回に1機能だけという規律。
要点
問題設定
Imagine a software project staffed by engineers working in shifts, where each new engineer arrives with no memory of what happened on the previous shift. 交代制で働くエンジニアが担当するソフトウェアプロジェクトを想像してほしい。新しく入る各エンジニアは、前の交代で何が起きたかの記憶をまったく持たない。
Claude の失敗は2つのパターンで現れる。
パターン1（序盤）: 一度に全部やろうとする
the agent tended to try to do too much at once—essentially to attempt to one-shot the app エージェントは一度にやりすぎようとする傾向があった。要するにアプリを一発で書き切ろうとするのである。
実装の途中で context を使い切り、後続のセッションには「半分実装されて文書化されていない機能」が残る。
パターン2（終盤）: 早すぎる勝利宣言
既存の進捗を見て「もう終わっている」と判断してしまう。
解の構造 — エージェントを2種類に分ける
| エージェント | 役割 |
|---|---|
| Initializer agent | 最初のセッションだけを担当し、専用のプロンプトで環境と成果物を用意する |
| Coding agent | 以降のセッションで漸進的に進め、環境をクリーンに保つ |
初期化エージェントが作る4つの成果物
1. feature list（JSON）
ユーザーの初期プロンプトを展開した網羅的な機能要件ファイル。claude.ai のクローンを作る例では 200 以上の機能になった。
粒度の例: “a user can open a new chat, type in a query, press enter, and see an AI response.” — end-to-end で記述するのがポイント。
各機能は passes フィールドを持ち、最初はすべて false。
JSON が Markdown より優れていた理由: the model is less likely to inappropriately change or overwrite JSON files.
さらに強い言葉で守らせる。
It is unacceptable to remove or edit tests because this could lead to missing or buggy functionality. テストを削除したり書き換えたりすることは許されない。機能の欠落やバグにつながりうるからである。
2. 初期の git リポジトリ
3. progress ファイル（claude-progress.txt）
エージェントが何を成し遂げたかを記録する。fresh context window で始めたときに作業の状態を素早く把握するため。
4. init.sh
開発サーバを起動できるスクリプト。
This saves Claude some tokens in every session since it doesn’t have to figure out how to test the code. コードのテスト方法を毎回調べずに済むため、これは毎セッションで Claude のトークンをいくらか節約する。
コーディングエージェントの規律
漸進的に進む（1回に1機能）
Rather than one-shotting implementations, agents work on only one feature at a time. This proved critical to addressing the agent’s tendency to do too much at once. 実装を一発で書き切らせるのではなく、エージェントには一度に1機能だけを担当させる。これはエージェントが一度にやりすぎる傾向に対処するうえで決定的だった。
クリーンな状態を保つ
By “clean state” we mean the kind of code that would be appropriate for merging to a main branch: there are no major bugs, the code is orderly and well-documented. ここで言う「クリーンな状態」とは、main ブランチにマージしても差し支えない種類のコードを指す。重大なバグがなく、コードが整理され、十分に文書化されている状態である。
そのために、説明的なコミットメッセージで git にコミットし、progress ファイルに進捗の要約を書く。これでコードの巻き戻しと復旧が可能になる。
テストする
Claude exhibited a tendency to mark a feature as complete without proper testing, often missing end-to-end failures. Claude には適切なテストを経ずに機能を完了と印す傾向が見られ、エンドツーエンドの失敗を見落とすことが多かった。
ブラウザ自動化ツールを与えると結果が劇的に改善した — コードを読むだけでは明らかでないバグを見つけて直せるようになる。
毎セッションの立ち上がり手順（standardized orientation）
pwdを実行して作業ディレクトリを確認する- git ログと progress ファイルを読んで文脈を得る
- 未完了で最優先の機能を1つ選ぶ
init.shを実行して開発サーバを起動する- 新しい作業を始める前に、基本的な end-to-end テストを走らせる
失敗モードと対策の対応表
| 問題 | Initializer agent 側の対策 | Coding agent 側の対策 |
|---|---|---|
| 早すぎる勝利宣言 | end-to-end の記述を持つ構造化 JSON の feature list を用意する | セッション開始時に feature list を読み、1機能だけに取り組む |
| 環境がバグったまま / 未文書のまま残る | 初期の git リポジトリと progress ファイルを作る | progress ファイルと git ログを読んで始め、baseline テストを走らせ、git コミットと progress 更新で終える |
| 検証せずに完了とマークする | feature list ファイルを用意する | ”passing” とマークする前に、すべての機能を自分で徹底的に検証する |
| アプリの立ち上げに時間を浪費する | init.sh を書く | セッションの冒頭で init.sh を読んで実行する |
Inspiration for these practices came from knowing what effective software engineers do every day. これらの実践の着想は、有能なソフトウェアエンジニアが日々何をしているかを知ることから得られた。
そのまま使える具体例
feature list の1エントリ:
{
"category": "functional",
"description": "New chat button creates a fresh conversation",
"steps": [
"Navigate to main interface",
"Click the 'New Chat' button",
"Verify a new conversation is created",
"Check that chat area shows welcome state",
"Verify conversation appears in sidebar"
],
"passes": false
}典型的なセッションの立ち上がり:
[Assistant] I'll start by getting my bearings and understanding the current state of the project.
[Tool Use] <bash - pwd>
[Tool Use] <read - claude-progress.txt>
[Tool Use] <read - feature_list.json>
[Assistant] Let me check the git log to see recent work.
[Tool Use] <bash - git log --oneline -20>
[Assistant] Now let me check if there's an init.sh script to restart the servers.
<Starts the development server>
[Assistant] Excellent! Now let me navigate to the application and verify that some fundamental features are still working.
<Tests basic functionality>テストを守らせる文言（強い言い方が必要だった）:
It is unacceptable to remove or edit tests because this could lead to missing or buggy functionality.harness が維持する成果物一式:
init.sh # 開発サーバの起動。毎セッションのトークンを節約する
claude-progress.txt # 何をやったかの自由記述メモ
feature_list.json # 機能要件と passes フラグ。JSON なのは上書きされにくいから
.git/ # 巻き戻しとチェックポイント原典で言及されている関連文書
- claude-prompting-best-practices — 複数 context window にまたがるワークフローの6原則（
tests.json、init.sh、git での状態追跡はここと一致する） - effective-context-engineering-for-ai-agents — structured note-taking と compaction
- demystifying-evals-for-ai-agents — この harness が生む feature list はそのまま regression eval になる
- context-windows — 複数セッションにまたがる state artifact の設計
- https://platform.claude.com/docs/en/agent-sdk/overview — Claude Agent SDK
未取得の派生リンク
- https://github.com/anthropics/claude-quickstarts/tree/main/autonomous-coding — この harness の quickstart 実装