【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址https://gitcode.com/gh_mirrors/le/learn-harness-engineering点击查看免费下载本講義は、AI エージェントが「一度に多くのタスクを起動してどれも最後まで完成しない」というオーバーリーチ過剰着手とアンダーフィニッシュ未完了の問題を定義し、WIP1 の強制・完了の証拠の明示・スコープサーフェスの外部化・検証済み完了率VCRの監視という 4 つの対策を、本リポジトリ内のスコープトラッカー実装scope-tracker.tsとプロジェクト 04 の実ハーネスAGENTS.mdを交えて解説します。読み終えると、エージェントに明確なタスク境界を引くための、そのままコピーして使えるハーネス設計を手に入れられます。コード例: code/ 実践プロジェクト: Project 04. ランタイムフィードバックとスコープ制御Claude Code に「このプロジェクトにユーザー認証を追加して」と頼むと、データベーススキーマの変更を始め、ルートを書き、フロントエンドのコンポーネントを変更し、ついでにエラーハンドリングミドルウェアのリファクタリングまで始めます。2 時間後に確認すると: 12 ファイルが変更され、800 行の新しいコードがあり、エンドツーエンドで動く機能は一つもありません。背に腹は代えられない——この言葉は AI エージェントに特に当てはまります。エージェントには「ついでにもう少しやっておこう」という衝動が生まれつき備わっています。関連するものを見ると、つい道沿いに処理してしまう——醤油を 1 本買いにスーパーに行って、満載のカートを押して出てくるようなものです。問題は、買いすぎた人はお金を無駄にするだけですが、エージェントが同時に多くのことをしようとすると、どれも適切に完了しないということです。Anthropic の「Effective harnesses for long-running agents」エンジニアリングブログは明確に述べています: プロンプトが広すぎると、エージェントは「1 つを先に終わらせる」のではなく「複数のことを同時に始める」傾向があります。OpenAI の Codex エンジニアリングプラクティスも同じことを発見しました——明示的なスコープ制御のないタスクは完了率が急激に低下します。これはモデルの問題ではありません——harness の問題です。あなたが境界を引かなかったのです。注意力は有限のリソースこれは比喩ではなく、数学です。エージェントのコンテキスト容量を C とし、k 個のタスクを同時に起動すると仮定します。各タスクは平均C/kの推論リソースを得ます。C/k が 1 つのタスクを完了するのに必要な最低閾値を下回ると、どれも完了しません。胃袋は有限——10 個の餃子を一度に詰め込んでも全部消化できず、10 回の消化不良になるだけです。Claude Code の実際の行動がそれを物語っています。「ユーザー登録を追加して」と頼むと、次のようにするかもしれません:User モデルを作成する登録ルートを書くメール検証が必要なことに気づき、メールサービスを追加するパスワードのハッシュ化が必要なことに気づき、bcrypt を導入するエラーハンドリングが不統一なことに気づき、グローバルエラーミドルウェアをリファクタリングするテストファイルの構造が乱雑なことに気づき、ディレクトリを再編成する6 ステップ後、すべてが半完成。エンドツーエンドの検証はなく、半完成のコード間に複雑な結合があり、次のセッションで片付けを引き継ぐ者は完全に途方に暮れます。6 つの料理を同時に作るようなもの——すべての料理が鍋に入っているが、どれも皿に盛られていません。すべて焦げます。Anthropic の実験データはこれを直接的に裏付けています: 「小さな次のステップ」戦略WIP1 に相当を使うエージェントは、広範なプロンプトを使うエージェントより37% 高いタスク完了率を示します。さらに興味深いことに、エージェントが生成するコード行数と実際の機能完了率は弱い負の相関があります——より多くのコードを書いた方が、より少ない機能が完了する。背に腹は代えられない、データによる証明です。WIP1 ワークフローオーバーリーチを防ぐ最も基本的な運用フローは次の通りです。一度に 1 つのタスクだけを「進行中」とし、エンドツーエンド検証に合格してから次のタスクを解放します。なぜ WIP1 なのか。推論予算は分割すると劣化します:中核概念本講義で使う 6 つの概念を先に定義しておきます。これらは後の実装パートすべての土台になります。オーバーリーチOverreach: エージェントが 1 つのセッションで最適な数よりも多くのタスクを起動すること。定量化可能——5 つの機能をやってエンドツーエンドで通るものが 0 個ならオーバーリーチです。アンダーフィニッシュUnder-finish: 起動したタスクのうち、エンドツーエンドの検証に通ったタスクの割合が閾値を下回ること。コードは書かれているがテストが通っていないのはアンダーフィニッシュです。WIP 制限Work-in-Progress Limit: カンバン手法由来。核となる考え方: 一度に進行中のタスク数を制限する。エージェントの場合、WIP1 が最も安全なデフォルト——次を始める前に 1 つを完了する。ビュッフェのように——皿に山盛りにせず、1 枚の皿を済ませてから次を取りに行く。完了の証拠Completion Evidence: タスクが「進行中」から「完了」に移行するために満たさなければならない検証可能な条件。これがないと、エージェントは「コードは問題なさそう」を「動作がテストに通る」の代わりに使ってしまいます。スコープサーフェスScope Surface: 各ノードが作業単位で、エッジが依存関係を表す DAG 構造。状態は 4 つに限定:not_started、active、blocked、passing。完了プレッシャーCompletion Pressure: harness が WIP 制限と完了の証拠の要件を通じて加える制約力で、エージェントに新しいタスクを始める前に現在のタスクを完了させるよう強制します。オーバーリーチとアンダーフィニッシュは共生するこれら 2 つの問題は独立していません——互いに増幅し合います。オーバーリーチは注意力を希薄化させ、希薄化された注意力はアンダーフィニッシュを引き起こし、残された半完成のコードがシステムの複雑さを増し、それが次のタスクでのさらなるオーバーリーチを招きます。悪循環です。カンバンの言葉で言えば: リトルの法則はL λ × Wと教えています。仕掛品 L が高すぎる一度に多くのことをやっている場合、各タスクのリードタイム W は必然的に増加します。エージェントにとって、これは各機能が開始から検証済み完了までにより長い時間がかかり、失敗の確率が増大することを意味します。これは人間の世界でも古い問題です——Steve McConnell はRapid Developmentの中で、スコープクリープがプロジェクト失敗の主要因であることを文書化しています。しかし人間には少なくとも「もう十分やった」という直感があります。エージェントにはそれがありません。次のアイデアを生成することはモデルにとってほぼ追加コストなしです——「ついでにこれも直しておきましょう」と書くことはほとんど負担になりません——しかし、追加の変更ごとにエージェントの注意力は希薄化します。ビュッフェで追加の皿ごとの限界コストはほぼゼロですが、胃袋の容量には限界があるようなものです。正しく行う方法1. WIP1 を強制するこれが最も直接的で効果的な方法です。harness の中で、エージェントに明示的に伝えます:いつでも「active」ステータスでよいタスクは 1 つだけ。Claude Code のCLAUDE.mdや Codex のAGENTS.mdに次のように書きます:## Work Rules - Work on one feature at a time - Only start the next feature after the current one passes end-to-end verification - Dont also refactor feature B while implementing feature Aこの「ルールの置き場所」はハーネスの中、つまりエージェントが必ず読む初期化ファイルです。実際の適用例として、プロジェクト 04 のソリューションにある AGENTS.md は## Working Rulesセクションで次のように運用しています:- Work on one feature at a time. - Do not mark a feature complete just because code was added. - Keep changes within the selected feature scope unless a blocker forces a narrow supporting fix. - Do not silently change verification rules during implementation. - Prefer durable repo artifacts over chat summaries.一方、同じプロジェクトのスターター側 AGENTS.md は「Work on one feature at a time」「Runnpm run checkbefore committing」の 2 行だけで、境界を強制する仕組みがありません。比較することで、WIP1 のルールが「書いてあるだけ」か「harness として運用されているか」の差がそのまま成果の差になることが分かります。2. 各タスクに明示的な完了の証拠を定義する完了とは「コードが書かれた」ではなく、「動作検証が通った」です。feature list で、各エントリに検証コマンドが必要です:F01: User Registration Verification: curl -X POST /api/register -d {email:testexample.com,password:123456} | jq .status 201 State: passingこの形式を機械可読な JSON として実装した例が、プロジェクト 01 のソリューションにある feature_list.json です。各機能にdescription動作記述、statuspassなどの状態、evidence検証済みの証拠文、testedAt検証時刻を持たせています:{ id: document-list, name: Document List Panel, description: Left sidebar shows imported documents with empty state message, status: pass, evidence: DocumentList component renders empty state when no documents, shows document cards when data present, testedAt: 2026-03-30T10:05:00Z }evidenceが「コードを書いた」ではなく「実際に検証して観測した結果」を記録している点が、完了の証拠の本質です。プロジェクト 04 の AGENTS.md ではこれを## Definition Of Doneとして明文化しています——「対象の振る舞いが実装されている」「必要な検証が実際に走った」「証拠が最終サマリーかプロジェクト文書に記録された」「リポジトリが標準起動パスから再起動可能」「アーキテクチャチェックが違反ゼロで通る」の 5 条件がすべて満たされたときだけ機能は完了です。3. スコープサーフェスを外部化する機械可読なファイルJSON または Markdownを使って、すべてのタスク状態を記録します。新しいセッションはこのファイルを読むだけで、どのタスクがアクティブか、何が完了とみなされるか、どの検証が通ったかを即座に把握できます。会話の中だけで言及するのでは消えてしまいますが、リポジトリ内に置けばセッションをまたいで永続します。本講義の code/ フォルダには、この考え方を補助する 2 つのテンプレートが用意されています。まずスコープの粒度を設計する例——scope-surface-example.md:# スコープ面の例 タスク - Electron ナレッジアプリにインデックス機能を追加 悪いスコープ - 「インデックス機能を実装」 より良いスコープ - インポートされたドキュメントを解析する - ドキュメントをチャンクに分割する - チャンクメタデータを永続化する - UI にインデックス状況を表示する - 再インデックスアクションを追加する「インデックス機能を実装」のような広いスコープは 1 つの atomic な作業単位ではなく、複数の機能の塊です。これを 5 つの作業単位に分解することで、WIP1 の制約を満たしながら進められるようになります。次に、セッションをまたぐときの引き継ぎを支えるテンプレート——next-task-template.md:# 次のタスクテンプレート - 現在の最優先機能 - なぜこの機能が次なのか - 何が合格とみなされるか - このステップで変更してはならないもの特に最後の「このステップで変更してはならないもの」が重要です。変更禁止範囲を明示することで、オーバーリーチの芽「ついでに直す」を未然に防ぎます。4. 検証済み完了率を監視するharness はVCRVerified Completion Rate 検証済みタスク数 ÷ 起動タスク数を継続的に追跡するべきです。VCR 1.0 のときは新しいタスクの起動をブロックします。VCR はスコープサーフェスの各ノードの状態not_started/active/blocked/passingから機械的に計算できるため、主観が入りません。リポジトリ実装で見るスコープ逸脱の検出講義の code/ フォルダには、スコープ逸脱scope driftを自動検出する実装scope-tracker.ts が TypeScript で用意されています。npx tsxでそのまま実行できます:npx tsx docs/ja/lectures/lecture-07-why-agents-overreach-and-under-finish/code/scope-tracker.ts仕組みは単純です。feature list からactive状態の機能 ID を収集し、変更ログの各行がどの機能に属すると申告しているかを照合して、inScopeスコープ内かを判定します:interface Feature { id: string; name: string; status: active | pending | done; } interface ChangeLogEntry { step: number; file: string; description: string; featureId: string; // The feature this change claims to belong to } function trackScope(featureList: Feature[], changes: ChangeLogEntry[]): ScopeCheckResult[] { const activeFeatures featureList.filter((f) f.status active); const activeIds new Set(activeFeatures.map((f) f.id)); return changes.map((change) ({ step: change.step, file: change.file, description: change.description, featureId: change.featureId, inScope: activeIds.has(change.featureId), activeFeature: activeFeatures.map((f) f.name).join(, ), })); }サンプルデータには、Search endpointF-001をactiveとしたまま、エージェントが Delete endpointF-002や Rate limitingF-003の変更を混入させていく 10 ステップの変更ログが仕込まれています。実行すると、スコープ外の変更がDRIFTとマークされ、最後に「10 件中 4 件がスコープ外」「4 つの機能が触られた」というサマリーが出力されます。トラッカーなしでは黙って進行する機能横断の作業を、機械的に可視化するデモです。この「スコープ逸脱を検出して制約する」考え方を本番規模で適用したのがプロジェクト 04 のソリューションです。そこでは AGENTS.md が 3 層のアーキテクチャ境界を定義し、clean-state-checklist.md がコミット前の健全性チェックビルド・アーキテクチャ・ランタイム・データ整合性・リポジトリ状態の 5 カテゴリとして完了の証拠を強制しています。レイヤー違反はscripts/check-architecture.shが検出し、WIP1 ルールと組み合わせることで「1 つの機能を境界内で完成させる」ことを物理的に支えます。実例: 8 機能 REST API での比較8 つの機能を持つ REST API プロジェクト、2 つの戦略を比較します:ビュッフェモード制約なし: エージェントはセッション 1 で 5 つの機能を同時に起動。12 ファイルにわたり約 800 行を生成。エンドツーエンドテストの合格率:20%——ユーザー登録だけが動作。他の 4 つの機能: データベーススキーマは作成されたが検証ロジックが欠落、ルートは定義されたが誤ったレスポンス形式を返す。6 つの料理を同時に作っているのに、1 つだけかろうじて食べられる状態。セッション 3 の終了までに、8 つの機能のうち3 つしか完了せず。1 枚の皿モードWIP1: エージェントはセッション 1 でユーザー登録のみに取り組む。4 ファイルにわたり約 200 行を生成。エンドツーエンドテスト:100% 合格。クリーンで検証済みの実装をコミット。セッション 4 の終了までに、8 つの機能のうち7 つが完了8 番目は外部依存関係でブロック。結果: 総コード量は少ない800 vs 1200 行が、有効なコードは多い。完了率:87.5% vs 37.5%。一口ずつ食べれば、実際により多く食べられます。重要なポイントWIP1 はエージェント harness のデフォルトの安全設定——1 つ完了させてから次に取りかかる。並列化しようとしない。一口で太ることはできない。完了の証拠は実行可能でなければならない——「コードは問題なさそう」はダメ。「curl が 201 を返す」なら OK。スコープサーフェスはファイルとして外部化する——会話中に言及するだけでなく、リポジトリ内の機械可読形式で記録する。オーバーリーチとアンダーフィニッシュは共生する——片方を解決すればもう片方も解決する。「少なくても完了させる」は常に「多くても半完成で終わる」に勝る——エージェントのコード行数と機能完了率は負の相関。品質が常に量に勝る。演習タスクの原子化: 広範な要件例: 「ユーザー管理システムを実装する」を選び、少なくとも 5 つの原子作業単位に分解する。各単位について: (a) 単一の動作記述、(b) 実行可能な検証コマンド、(c) 依存関係を指定する。分解が WIP1 の制約を満たしているか確認してください。参考になる粒度は scope-surface-example.md です。比較実験: 同じプロジェクトを 2 回実行する——1 回は制約なし、1 回は WIP1 を強制。検証済み完了率、総コード行数、有効コード比率を比較してください。scope-tracker.ts を拡張して、変更ログから逸脱を自動集計すると比較が容易になります。完了の証拠の監査: 最近のエージェント実行の出力を確認し、各コード変更を「完了した動作」「不完全な動作」「スキャフォールディング」に分類する。不完全な動作それぞれについて欠けている検証コマンドを追加してください。next-task-template.md の「何が合格とみなされるか」欄を埋める形で記録すると、次のセッションの完了条件になります。関連リソース本講義の英語版: Lecture 07. Draw Clear Task Boundaries for Agents 中国語版: docs/zh実践プロジェクト: Project 04. ランタイムフィードバックとスコープ制御 — スコープ制御とランタイム観測性を組み合わせた演習次の講義: 講義 08. フィーチャーリストをハーネスのプリミティブにする — feature list を機械可読な制約として使う方法業界背景: Anthropic「Effective harnesses for long-running agents」、OpenAI「Harness Engineering」、David Anderson『Kanban: Successful Evolutionary Change』WIP 制限の古典、Steve McConnell『Rapid Development』スコープクリープとプロジェクト失敗の実証データ赞分享【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址https://gitcode.com/gh_mirrors/le/learn-harness-engineering点击查看免费下载相关推荐プロジェクト 05. 役割分離でエージェントに自分の作業を検証させる — 根拠付き QA と証拠に基づく完了判定の実践プロジェクト 05. 役割分離でエージェントに自分の作業を検証させる — 根拠付き QA と証拠に基づく完了判定の実践 このプロジェクトでは、AI エージェンElectron アーキテクチャルールと End-to-End テスト検証——コンポーネント境界の欠陥を防ぐ agent ワークフロー設計Electron アーキテクチャルールと End to End テスト検証——コンポーネント境界の欠陥を防ぐ agent ワークフロー設計 本稿は、 learnlearn-harness-engineering 講義 01強いモデルは信頼できる実行を意味しない——Harness がエージェントの成否を決めるlearn harness engineering 講義 01強いモデルは信頼できる実行を意味しない——Harness がエージェントの成否を決める 本講義は创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 講義 07：エージェントのタスク境界を設計する——オーバーリーチとアンダーフィニッシュを防ぐ WIP=1・スコープサーフェス・完了の証拠の実践
【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址https://gitcode.com/gh_mirrors/le/learn-harness-engineering点击查看免费下载本講義は、AI エージェントが「一度に多くのタスクを起動してどれも最後まで完成しない」というオーバーリーチ過剰着手とアンダーフィニッシュ未完了の問題を定義し、WIP1 の強制・完了の証拠の明示・スコープサーフェスの外部化・検証済み完了率VCRの監視という 4 つの対策を、本リポジトリ内のスコープトラッカー実装scope-tracker.tsとプロジェクト 04 の実ハーネスAGENTS.mdを交えて解説します。読み終えると、エージェントに明確なタスク境界を引くための、そのままコピーして使えるハーネス設計を手に入れられます。コード例: code/ 実践プロジェクト: Project 04. ランタイムフィードバックとスコープ制御Claude Code に「このプロジェクトにユーザー認証を追加して」と頼むと、データベーススキーマの変更を始め、ルートを書き、フロントエンドのコンポーネントを変更し、ついでにエラーハンドリングミドルウェアのリファクタリングまで始めます。2 時間後に確認すると: 12 ファイルが変更され、800 行の新しいコードがあり、エンドツーエンドで動く機能は一つもありません。背に腹は代えられない——この言葉は AI エージェントに特に当てはまります。エージェントには「ついでにもう少しやっておこう」という衝動が生まれつき備わっています。関連するものを見ると、つい道沿いに処理してしまう——醤油を 1 本買いにスーパーに行って、満載のカートを押して出てくるようなものです。問題は、買いすぎた人はお金を無駄にするだけですが、エージェントが同時に多くのことをしようとすると、どれも適切に完了しないということです。Anthropic の「Effective harnesses for long-running agents」エンジニアリングブログは明確に述べています: プロンプトが広すぎると、エージェントは「1 つを先に終わらせる」のではなく「複数のことを同時に始める」傾向があります。OpenAI の Codex エンジニアリングプラクティスも同じことを発見しました——明示的なスコープ制御のないタスクは完了率が急激に低下します。これはモデルの問題ではありません——harness の問題です。あなたが境界を引かなかったのです。注意力は有限のリソースこれは比喩ではなく、数学です。エージェントのコンテキスト容量を C とし、k 個のタスクを同時に起動すると仮定します。各タスクは平均C/kの推論リソースを得ます。C/k が 1 つのタスクを完了するのに必要な最低閾値を下回ると、どれも完了しません。胃袋は有限——10 個の餃子を一度に詰め込んでも全部消化できず、10 回の消化不良になるだけです。Claude Code の実際の行動がそれを物語っています。「ユーザー登録を追加して」と頼むと、次のようにするかもしれません:User モデルを作成する登録ルートを書くメール検証が必要なことに気づき、メールサービスを追加するパスワードのハッシュ化が必要なことに気づき、bcrypt を導入するエラーハンドリングが不統一なことに気づき、グローバルエラーミドルウェアをリファクタリングするテストファイルの構造が乱雑なことに気づき、ディレクトリを再編成する6 ステップ後、すべてが半完成。エンドツーエンドの検証はなく、半完成のコード間に複雑な結合があり、次のセッションで片付けを引き継ぐ者は完全に途方に暮れます。6 つの料理を同時に作るようなもの——すべての料理が鍋に入っているが、どれも皿に盛られていません。すべて焦げます。Anthropic の実験データはこれを直接的に裏付けています: 「小さな次のステップ」戦略WIP1 に相当を使うエージェントは、広範なプロンプトを使うエージェントより37% 高いタスク完了率を示します。さらに興味深いことに、エージェントが生成するコード行数と実際の機能完了率は弱い負の相関があります——より多くのコードを書いた方が、より少ない機能が完了する。背に腹は代えられない、データによる証明です。WIP1 ワークフローオーバーリーチを防ぐ最も基本的な運用フローは次の通りです。一度に 1 つのタスクだけを「進行中」とし、エンドツーエンド検証に合格してから次のタスクを解放します。なぜ WIP1 なのか。推論予算は分割すると劣化します:中核概念本講義で使う 6 つの概念を先に定義しておきます。これらは後の実装パートすべての土台になります。オーバーリーチOverreach: エージェントが 1 つのセッションで最適な数よりも多くのタスクを起動すること。定量化可能——5 つの機能をやってエンドツーエンドで通るものが 0 個ならオーバーリーチです。アンダーフィニッシュUnder-finish: 起動したタスクのうち、エンドツーエンドの検証に通ったタスクの割合が閾値を下回ること。コードは書かれているがテストが通っていないのはアンダーフィニッシュです。WIP 制限Work-in-Progress Limit: カンバン手法由来。核となる考え方: 一度に進行中のタスク数を制限する。エージェントの場合、WIP1 が最も安全なデフォルト——次を始める前に 1 つを完了する。ビュッフェのように——皿に山盛りにせず、1 枚の皿を済ませてから次を取りに行く。完了の証拠Completion Evidence: タスクが「進行中」から「完了」に移行するために満たさなければならない検証可能な条件。これがないと、エージェントは「コードは問題なさそう」を「動作がテストに通る」の代わりに使ってしまいます。スコープサーフェスScope Surface: 各ノードが作業単位で、エッジが依存関係を表す DAG 構造。状態は 4 つに限定:not_started、active、blocked、passing。完了プレッシャーCompletion Pressure: harness が WIP 制限と完了の証拠の要件を通じて加える制約力で、エージェントに新しいタスクを始める前に現在のタスクを完了させるよう強制します。オーバーリーチとアンダーフィニッシュは共生するこれら 2 つの問題は独立していません——互いに増幅し合います。オーバーリーチは注意力を希薄化させ、希薄化された注意力はアンダーフィニッシュを引き起こし、残された半完成のコードがシステムの複雑さを増し、それが次のタスクでのさらなるオーバーリーチを招きます。悪循環です。カンバンの言葉で言えば: リトルの法則はL λ × Wと教えています。仕掛品 L が高すぎる一度に多くのことをやっている場合、各タスクのリードタイム W は必然的に増加します。エージェントにとって、これは各機能が開始から検証済み完了までにより長い時間がかかり、失敗の確率が増大することを意味します。これは人間の世界でも古い問題です——Steve McConnell はRapid Developmentの中で、スコープクリープがプロジェクト失敗の主要因であることを文書化しています。しかし人間には少なくとも「もう十分やった」という直感があります。エージェントにはそれがありません。次のアイデアを生成することはモデルにとってほぼ追加コストなしです——「ついでにこれも直しておきましょう」と書くことはほとんど負担になりません——しかし、追加の変更ごとにエージェントの注意力は希薄化します。ビュッフェで追加の皿ごとの限界コストはほぼゼロですが、胃袋の容量には限界があるようなものです。正しく行う方法1. WIP1 を強制するこれが最も直接的で効果的な方法です。harness の中で、エージェントに明示的に伝えます:いつでも「active」ステータスでよいタスクは 1 つだけ。Claude Code のCLAUDE.mdや Codex のAGENTS.mdに次のように書きます:## Work Rules - Work on one feature at a time - Only start the next feature after the current one passes end-to-end verification - Dont also refactor feature B while implementing feature Aこの「ルールの置き場所」はハーネスの中、つまりエージェントが必ず読む初期化ファイルです。実際の適用例として、プロジェクト 04 のソリューションにある AGENTS.md は## Working Rulesセクションで次のように運用しています:- Work on one feature at a time. - Do not mark a feature complete just because code was added. - Keep changes within the selected feature scope unless a blocker forces a narrow supporting fix. - Do not silently change verification rules during implementation. - Prefer durable repo artifacts over chat summaries.一方、同じプロジェクトのスターター側 AGENTS.md は「Work on one feature at a time」「Runnpm run checkbefore committing」の 2 行だけで、境界を強制する仕組みがありません。比較することで、WIP1 のルールが「書いてあるだけ」か「harness として運用されているか」の差がそのまま成果の差になることが分かります。2. 各タスクに明示的な完了の証拠を定義する完了とは「コードが書かれた」ではなく、「動作検証が通った」です。feature list で、各エントリに検証コマンドが必要です:F01: User Registration Verification: curl -X POST /api/register -d {email:testexample.com,password:123456} | jq .status 201 State: passingこの形式を機械可読な JSON として実装した例が、プロジェクト 01 のソリューションにある feature_list.json です。各機能にdescription動作記述、statuspassなどの状態、evidence検証済みの証拠文、testedAt検証時刻を持たせています:{ id: document-list, name: Document List Panel, description: Left sidebar shows imported documents with empty state message, status: pass, evidence: DocumentList component renders empty state when no documents, shows document cards when data present, testedAt: 2026-03-30T10:05:00Z }evidenceが「コードを書いた」ではなく「実際に検証して観測した結果」を記録している点が、完了の証拠の本質です。プロジェクト 04 の AGENTS.md ではこれを## Definition Of Doneとして明文化しています——「対象の振る舞いが実装されている」「必要な検証が実際に走った」「証拠が最終サマリーかプロジェクト文書に記録された」「リポジトリが標準起動パスから再起動可能」「アーキテクチャチェックが違反ゼロで通る」の 5 条件がすべて満たされたときだけ機能は完了です。3. スコープサーフェスを外部化する機械可読なファイルJSON または Markdownを使って、すべてのタスク状態を記録します。新しいセッションはこのファイルを読むだけで、どのタスクがアクティブか、何が完了とみなされるか、どの検証が通ったかを即座に把握できます。会話の中だけで言及するのでは消えてしまいますが、リポジトリ内に置けばセッションをまたいで永続します。本講義の code/ フォルダには、この考え方を補助する 2 つのテンプレートが用意されています。まずスコープの粒度を設計する例——scope-surface-example.md:# スコープ面の例 タスク - Electron ナレッジアプリにインデックス機能を追加 悪いスコープ - 「インデックス機能を実装」 より良いスコープ - インポートされたドキュメントを解析する - ドキュメントをチャンクに分割する - チャンクメタデータを永続化する - UI にインデックス状況を表示する - 再インデックスアクションを追加する「インデックス機能を実装」のような広いスコープは 1 つの atomic な作業単位ではなく、複数の機能の塊です。これを 5 つの作業単位に分解することで、WIP1 の制約を満たしながら進められるようになります。次に、セッションをまたぐときの引き継ぎを支えるテンプレート——next-task-template.md:# 次のタスクテンプレート - 現在の最優先機能 - なぜこの機能が次なのか - 何が合格とみなされるか - このステップで変更してはならないもの特に最後の「このステップで変更してはならないもの」が重要です。変更禁止範囲を明示することで、オーバーリーチの芽「ついでに直す」を未然に防ぎます。4. 検証済み完了率を監視するharness はVCRVerified Completion Rate 検証済みタスク数 ÷ 起動タスク数を継続的に追跡するべきです。VCR 1.0 のときは新しいタスクの起動をブロックします。VCR はスコープサーフェスの各ノードの状態not_started/active/blocked/passingから機械的に計算できるため、主観が入りません。リポジトリ実装で見るスコープ逸脱の検出講義の code/ フォルダには、スコープ逸脱scope driftを自動検出する実装scope-tracker.ts が TypeScript で用意されています。npx tsxでそのまま実行できます:npx tsx docs/ja/lectures/lecture-07-why-agents-overreach-and-under-finish/code/scope-tracker.ts仕組みは単純です。feature list からactive状態の機能 ID を収集し、変更ログの各行がどの機能に属すると申告しているかを照合して、inScopeスコープ内かを判定します:interface Feature { id: string; name: string; status: active | pending | done; } interface ChangeLogEntry { step: number; file: string; description: string; featureId: string; // The feature this change claims to belong to } function trackScope(featureList: Feature[], changes: ChangeLogEntry[]): ScopeCheckResult[] { const activeFeatures featureList.filter((f) f.status active); const activeIds new Set(activeFeatures.map((f) f.id)); return changes.map((change) ({ step: change.step, file: change.file, description: change.description, featureId: change.featureId, inScope: activeIds.has(change.featureId), activeFeature: activeFeatures.map((f) f.name).join(, ), })); }サンプルデータには、Search endpointF-001をactiveとしたまま、エージェントが Delete endpointF-002や Rate limitingF-003の変更を混入させていく 10 ステップの変更ログが仕込まれています。実行すると、スコープ外の変更がDRIFTとマークされ、最後に「10 件中 4 件がスコープ外」「4 つの機能が触られた」というサマリーが出力されます。トラッカーなしでは黙って進行する機能横断の作業を、機械的に可視化するデモです。この「スコープ逸脱を検出して制約する」考え方を本番規模で適用したのがプロジェクト 04 のソリューションです。そこでは AGENTS.md が 3 層のアーキテクチャ境界を定義し、clean-state-checklist.md がコミット前の健全性チェックビルド・アーキテクチャ・ランタイム・データ整合性・リポジトリ状態の 5 カテゴリとして完了の証拠を強制しています。レイヤー違反はscripts/check-architecture.shが検出し、WIP1 ルールと組み合わせることで「1 つの機能を境界内で完成させる」ことを物理的に支えます。実例: 8 機能 REST API での比較8 つの機能を持つ REST API プロジェクト、2 つの戦略を比較します:ビュッフェモード制約なし: エージェントはセッション 1 で 5 つの機能を同時に起動。12 ファイルにわたり約 800 行を生成。エンドツーエンドテストの合格率:20%——ユーザー登録だけが動作。他の 4 つの機能: データベーススキーマは作成されたが検証ロジックが欠落、ルートは定義されたが誤ったレスポンス形式を返す。6 つの料理を同時に作っているのに、1 つだけかろうじて食べられる状態。セッション 3 の終了までに、8 つの機能のうち3 つしか完了せず。1 枚の皿モードWIP1: エージェントはセッション 1 でユーザー登録のみに取り組む。4 ファイルにわたり約 200 行を生成。エンドツーエンドテスト:100% 合格。クリーンで検証済みの実装をコミット。セッション 4 の終了までに、8 つの機能のうち7 つが完了8 番目は外部依存関係でブロック。結果: 総コード量は少ない800 vs 1200 行が、有効なコードは多い。完了率:87.5% vs 37.5%。一口ずつ食べれば、実際により多く食べられます。重要なポイントWIP1 はエージェント harness のデフォルトの安全設定——1 つ完了させてから次に取りかかる。並列化しようとしない。一口で太ることはできない。完了の証拠は実行可能でなければならない——「コードは問題なさそう」はダメ。「curl が 201 を返す」なら OK。スコープサーフェスはファイルとして外部化する——会話中に言及するだけでなく、リポジトリ内の機械可読形式で記録する。オーバーリーチとアンダーフィニッシュは共生する——片方を解決すればもう片方も解決する。「少なくても完了させる」は常に「多くても半完成で終わる」に勝る——エージェントのコード行数と機能完了率は負の相関。品質が常に量に勝る。演習タスクの原子化: 広範な要件例: 「ユーザー管理システムを実装する」を選び、少なくとも 5 つの原子作業単位に分解する。各単位について: (a) 単一の動作記述、(b) 実行可能な検証コマンド、(c) 依存関係を指定する。分解が WIP1 の制約を満たしているか確認してください。参考になる粒度は scope-surface-example.md です。比較実験: 同じプロジェクトを 2 回実行する——1 回は制約なし、1 回は WIP1 を強制。検証済み完了率、総コード行数、有効コード比率を比較してください。scope-tracker.ts を拡張して、変更ログから逸脱を自動集計すると比較が容易になります。完了の証拠の監査: 最近のエージェント実行の出力を確認し、各コード変更を「完了した動作」「不完全な動作」「スキャフォールディング」に分類する。不完全な動作それぞれについて欠けている検証コマンドを追加してください。next-task-template.md の「何が合格とみなされるか」欄を埋める形で記録すると、次のセッションの完了条件になります。関連リソース本講義の英語版: Lecture 07. Draw Clear Task Boundaries for Agents 中国語版: docs/zh実践プロジェクト: Project 04. ランタイムフィードバックとスコープ制御 — スコープ制御とランタイム観測性を組み合わせた演習次の講義: 講義 08. フィーチャーリストをハーネスのプリミティブにする — feature list を機械可読な制約として使う方法業界背景: Anthropic「Effective harnesses for long-running agents」、OpenAI「Harness Engineering」、David Anderson『Kanban: Successful Evolutionary Change』WIP 制限の古典、Steve McConnell『Rapid Development』スコープクリープとプロジェクト失敗の実証データ赞分享【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址https://gitcode.com/gh_mirrors/le/learn-harness-engineering点击查看免费下载相关推荐プロジェクト 05. 役割分離でエージェントに自分の作業を検証させる — 根拠付き QA と証拠に基づく完了判定の実践プロジェクト 05. 役割分離でエージェントに自分の作業を検証させる — 根拠付き QA と証拠に基づく完了判定の実践 このプロジェクトでは、AI エージェンElectron アーキテクチャルールと End-to-End テスト検証——コンポーネント境界の欠陥を防ぐ agent ワークフロー設計Electron アーキテクチャルールと End to End テスト検証——コンポーネント境界の欠陥を防ぐ agent ワークフロー設計 本稿は、 learnlearn-harness-engineering 講義 01強いモデルは信頼できる実行を意味しない——Harness がエージェントの成否を決めるlearn harness engineering 講義 01強いモデルは信頼できる実行を意味しない——Harness がエージェントの成否を決める 本講義は创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考