【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址https://gitcode.com/gh_mirrors/le/learn-harness-engineering点击查看免费下载本ガイドは、OpenAI アドバンストパックdocs/ja/resources/openai-advanced/内のrepo-template/docs/PLANS.mdを軸に、長時間実行されるコーディングエージェントが「リポジトリだけから作業を再開できる」ための実行プランexecution plan管理方法を解説します。プランの作成・更新・完了・アーカイブのライフサイクル、必須セクション、ディレクトリ規約、テックデット追跡、そしてAGENTS.mdとの連携までを、実際のスターターファイル構成に沿って理解し、自プロジェクトへ導入できるようになります。1. PLANS.md の役割なぜ実行プランがリポジトリに必要なのかrepo-templateは「リポジトリをエージェントにとってのシステム・オブ・レコードSystem of Recordにする」という信念core-beliefs.mdに基づいて設計されています。エージェントはチャット履歴を引き継げないため、作業の「現在地」と「次の一手」はすべてリポジトリ上のファイルとして永続化されなければなりません。PLANS.mdは、まさにその永続化を担うポリシー文書です。ファイル自体は短く、実行プランのライフサイクル作成・更新・完了・アーカイブのルールだけを定義しています。具体的な各プランの内容はdocs/exec-plans/配下の個別ファイルに置かれ、PLANS.mdはその運用憲法として機能します。この「短いポリシー個別ファイル」の分離は、AGENTS.mdの「短く保ち、巨大な指示のダンプではなく、記録のシステム文書へのルーティング層として使用する」という設計方針とも一貫しています。AGENTS.mdのスタートアップワークフローでも、コード変更前に「docs/PLANS.mdを読み、作業中のアクティブプランを開く」ことが明示されています。2. プランが必要になる4つの条件PLANS.mdは、以下のいずれかに該当する作業について実行プランの作成を義務付けています。条件具体例1セッションを超える作業複数日にまたがる実装、別セッションでの続行を想定したタスク複数のサブシステムを変更する作業フロントエンド・バックエンド・DBスキーマを横断する変更自明でない検証またはロールアウトリスクがある作業データ移行、破壊的変更、本番ロールバックが必要になり得る作業記録すべき未決定の決定に依存する作業方針が未確定で、後続のエージェントが判断経緯を知る必要がある作業逆に、単一セッション内で完結する単純な変更はプラン不要です。この閾値判断自体が重要で、過剰なプラン作成は文書メンテナンスの負荷を生むため、「境界付けられた1つのタスクが、複数の未完了タスクより優れている」というcore-beliefs.mdの原則とバランスを取ります。3. プランの置き場所とディレクトリ規約PLANS.mdは、プランが置かれる場所を3種類に分類します。場所役割docs/exec-plans/active/現在作業を推進しているプランdocs/exec-plans/completed/将来のエージェントコンテキストのために保持される完了プランdocs/exec-plans/tech-debt-tracker.md先送りされた作業とフォローアップ3.1 active/進行中プランの置き場active/index.mdは、アクティブな実行プランごとに1つのマークダウンファイルを保持することを求めています。推奨ファイル名パターンはYYYY-MM-DD-short-topic.md例2026-09-23-graph-rag-indexing.md重要な要件は、「各アクティブなプランは、新しいエージェントセッションがリポジトリだけから作業を再開できる十分な最新状態であるべき」という点です。これはプラン文書に求められる最大の品質基準であり、進捗ログを常に最新化する運用ルールの根拠となっています。3.2 completed/削除しないアーカイブcompleted/index.mdは、完了したプランを削除せずここに移動することを規定しています。完了プランは「リポジトリのメモリサーフェスmemory surfaceの一部」であり、後のエージェント実行が「コードが現在の状態になっている理由」を理解するための歴史的証拠として機能します。例えば後日「なぜこの設計を採用したのか」を調査するエージェントは、このフォルダのプランから決定の経緯を再発見できます。3.3 tech-debt-tracker.md意図的に先送りした負債の記録tech-debt-tracker.mdは、現実に存在し、認識されており、意図的に先送りされているテクニカルデットの記録に使用します。表形式で以下の列を持ちます日付領域デット先送りの理由リスク次のトリガーYYYY-MM-DD[area][debt][reason][risk][見直し時期]記入例| 2026-09-23 | backend | レガシーAPIのエラーレスポンス形式が統一されていない | 現行クライアントとの互換性維持のため | 新規クライアントがエラー処理を誤る可能性 | 次期メジャーバージョン開発開始時 |このトラッカーのポイントは「気づいていない負債」ではなく「認識済みで意図的に先送りした負債」を記録することです。先送りを隠すのではなく可視化することで、エージェントが将来その負債に遭遇した際に「なぜこうなっているのか」を即座に理解できます。4. プランの必須セクション6項目PLANS.mdは、すべてのプランに以下の6セクションを含めることを要求します。これらは、新しいエージェントがプランだけを読んで作業を再開するために必要な最小限の情報セットです。4.1 目的Purposeこのプランが何を達成するのかを1〜2文で明記します。成果物とその価値を明確にします。4.2 スコープとスコープ外Scope and out-of-scope「やること」と「やらないこと」を両方明示します。スコープ外を明記することで、エージェントが過剰に実装範囲を広げるoverreachのを防ぎます。これはAGENTS.mdのワーキングコントラクト「一度に一つの境界付けられたプランまたはフィーチャースライスから作業する」と対応しています。4.3 検証パスVerification path作業完了とみなすための検証方法を具体的に記述します。AGENTS.mdの完了の定義が「コードの検査だけで作業完了とマークしない。実行可能な証拠が必要である」と定めているように、テスト実行、ベンチマーク、手動確認手順など、実行可能な証拠を伴う検証を列挙します。4.4 リスクとブロッカーRisks and blockers予想される障害、依存関係、解決が必要な前提条件を記録します。ブロッカーはプラン開始時に存在する場合もあれば、作業中に発見される場合もあります。4.5 進捗ログProgress log作業の進行に応じて追記する時系列ログです。「作業が進むにつれてプランを更新する。静的な文章として扱わない」という運用ルールを体現するセクションで、新しいエージェントセッションがリポジトリだけで再開できる最新状態を保ちます。4.6 未決定事項Undecided items現時点で未確定の決定事項を列挙します。「プランが必要な場合」の条件にある「記録すべき未決定の決定に依存する作業」に対応し、判断が下されるまでの経緯を後続エージェントが追跡できるようにします。5. 運用ルールプランを静的な文章にしないPLANS.mdは以下の4つの運用ルールを定めています。1つのアクティブプランには、1つの明確に所有された現在のステップがあるべき複数の並行ステップを持つプランは、次のエージェントが「どこから手をつければよいか」を判断できなくなるため、常に現在のステップを1つに絞ります。作業が進むにつれてプランを更新する進捗ログの追記、完了ステップのマーク、検証結果の記録を怠らない。プランは静的仕様書ではなく、動的な作業記録です。決定が実装の方向を変更した場合、プランに記録する設計変更が発生したら、その決定と理由をプランに残します。これにより「コードが今の形になった理由」がリポジトリ内で検索可能になります。終了したプランはcompleted/に移動する削除ではなくアーカイブ。過去のコンテキストをエージェントが発見できるようにします。6. セッション終了フローとの連携プランのライフサイクル全体図プランのライフサイクルはPLANS.md単独ではなく、AGENTS.mdの「セッションの終了」手順と組み合わせることで完結します。作成PLANS.md の条件判定 → active/YYYY-MM-DD-short-topic.md として配置 → 作業セッションごとに進捗ログを更新動的文書として運用 → 完了検証パスを実行し証拠をリンク → completed/ へ移動削除しない → 先送りした負債は tech-debt-tracker.md に記録 → 次のアクションが明確な再起動可能な状態でリポジトリを残すAGENTS.mdのセッション終了チェックリストは、プラン運用と強く結びついていますアクティブな実行プランを更新するドメインやレイヤーに意味のある変更があった場合、docs/QUALITY_SCORE.mdを更新する債務を先送りした場合、docs/exec-plans/tech-debt-tracker.mdに新しい債務を記録する適切なタイミングで終了したプランをdocs/exec-plans/completed/に移動する次のアクションが明確な再起動可能な状態でリポジトリを残すまたAGENTS.mdの「完了の定義」は、プラン文書との関係を次のように要求していますターゲット動作が実装されている必要な検証が実際に実行された証拠が関連するプランまたは品質文書にリンクされている影響を受ける文書が最新の状態であるリポジトリが標準スタートアップパスからクリーンに再起動できるつまり、検証の実行証拠をプランにリンクして初めて「完了」とみなされます。プランは単なるTODOリストではなく、検証証跡と決定履歴を含む作業の記録システムなのです。7. プランと他ドキュメントの関係性repo-templateでは、プランが孤立せず他の記録文書と相互参照される設計です。AGENTS.mdAGENTS.mdスタートアップ時にPLANS.mdを読んでアクティブプランを開くようエージェントを誘導。ルーティングマップにも「docs/PLANS.md: プランのライフサイクルと実行プランのポリシー」と記載されています。デザインドキュメントdesign-docs/index.mdメンテナンスルールとして「アクティブな実行プランを、それが依存するデザインドキュメントにリンクする」ことを要求。プランの設計判断はdesign-docs/の承認済みドキュメントを参照します。プロダクト仕様product-specs/index.md実装が仕様から逸脱した場合、同じセッションでどちらかを更新します。プランの検証パスは仕様の受け入れ基準と整合させる必要があります。品質スコアdocs/QUALITY_SCORE.mdドメインやレイヤーの健全性を示し、プランの優先順位判断に利用されます。この相互参照構造により、「エージェントがリポジトリ内で事実を発見できない場合、その事実は運用上利用不可能として扱う」というcore-beliefs.mdの原則が守られます。8. 実践テンプレート自リポジトリへの適用例PLANS.mdのルールに従った実行プランのテンプレート例を以下に示します。# [プランタイトル] - 作成日: YYYY-MM-DD - ステータス: アクティブ ## 目的 [このプランが達成することを1〜2文で] ## スコープとスコープ外 - スコープ内: ... - スコープ外: ... ## 検証パス - [ ] ユニットテスト: npm test が全て成功する - [ ] E2E: 主要ユーザーフローを実際に実行する - [ ] 証拠リンク: 結果をこのファイルにリンクする ## リスクとブロッカー - [ ] ブロッカー: ... ## 進捗ログ - YYYY-MM-DD: プラン作成、スコープ確定 - YYYY-MM-DD: [最新の進捗を追記] ## 未決定事項 - [ ] ...決定されたら履歴として残す導入時の注意点として、openai-advancedの index は次のアドバイスを与えていますリポジトリがまだ小規模な場合は、最小ハーネスパックから始めるより強固な構造が必要になったらrepo-template/のファイルを自リポジトリにコピーするAGENTS.mdは短く保ち、より深いドキュメントへのルーターとして扱う品質・信頼性・計画ドキュメントは独立したクリーンアップ日ではなく、通常の作業の一部として更新する生成された成果物と外部参照は明示的に保持し、エージェントがチャット履歴に頼らず見つけられるようにするまた同 index は「このパックは意図的にオピニオネイトされていますが、盲目的にコピーするのではなく、プロジェクトに合わせて適応させるべきです」と明言しており、プラン運用も自チームの作業規模に合わせて調整するのが正しい使い方です。9. まとめPLANS.mdは、エージェントファーストなリポジトリ運用における実行プランの「憲法」です。プランが必要な条件の判定から、active/・completed/・tech-debt-tracker.mdへの配置、6つの必須セクション、そして「動的文書として更新し続ける」運用ルールまでを一貫して定義しています。これにより、どのエージェントセッションもリポジトリだけを読めば「今どこにいて、次に何をすべきか」を正確に把握でき、長期タスクの連続性continuityがリポジトリ自体に保存されます。実際の適用にあたっては、repo-template/docs/PLANS.mdとその配下のexec-plans/active/、exec-plans/completed/、tech-debt-tracker.mdを参照し、AGENTS.mdのセッション開始・終了フローと組み合わせて運用することで、複数セッションにまたがる作業でも「チャット履歴に頼らない再開」を実現できます。赞分享【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址https://gitcode.com/gh_mirrors/le/learn-harness-engineering点击查看免费下载相关推荐learn-claude-code s03 実践ツール実行前に「3ゲートの権限パイプライン」で Agent の安全性を実現するlearn claude code s03 実践ツール実行前に「3ゲートの権限パイプライン」で Agent の安全性を実現する 本文は learn claud示例工程AI Agent人工智能QUALITY_SCORE.md 完全ガイドエージェントファーストなリポジトリの品質追跡を実装するQUALITY_SCORE.md 完全ガイドエージェントファーストなリポジトリの品質追跡を実装する この文書は、 learn harness engineerClaude Code で PR のセキュリティをレビューする /check-security スラッシュコマンド実践ガイドClaude Code で PR のセキュリティをレビューする /check security スラッシュコマンド実践ガイド /check security は教程文档创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考