better-harness

Better Harness

コーディングエージェントのシステムをレビューします。対象はコンテキスト、実行、制御、フィードバック、学習です。Sessions、プロジェクト、エージェントのアセットは独立させてください。

Step 1: 対象範囲を確定し、エビデンスバンドルを収集する

ルーティング：

• <better-harness-fix-output>：Finding-bound Fix。
• コールバックがなく、先頭が fix、repair、または \u4fee\u590d の場合：Manual Direct Fix。
• レビュー／評価／レポート作成、またはレビューと修正の混在：Step 1。

Skill のパス、../.. を示す <better-harness-root>、サポート対象の <node>、および <node> <better-harness-root>/scripts/better-harness.mjs を示す <cli> を解決します。いずれかの所有者が見つからない場合は停止してください。検索順に従って別のキャッシュやランタイムを選択してはいけません。

絶対パスの対象、判断、受け入れ境界、リスク、ロケール（デフォルトでは依頼の言語）、出力モード、プロバイダー、深度を確定します。クイックでは3項目と7日間、通常では5項目と30日間を使用します。Qoder／Cursor ではデフォルトで永続的な Canvas を使用し、それ以外のレンダリングホストでは HTML を使用します。REPORT_RENDERING に対応していないプロバイダーは、インラインまたはファイルなしでのみ進め、HTML、Markdown、Canvas の出力を作成してはいけません。プロバイダーは個別に扱います。プロジェクト全体のレビューで複数のサポート対象プロバイダーが明示的に許可されている場合を除き、現在のプロバイダーを使用してください。 Qoder プロジェクトの Memory タイトルメタデータは、選択したワークスペースのベースラインの一部です。Memory 本文、Codex Memory、Qoder グローバル Memory、ユーザーホーム、未加工の Session、インストール済みプラグイン、マーケットプレイス、過去のインサイトへのアクセスには、明示的な対象範囲の許可が必要です。

委任の前に、許可されたプロバイダーごとに、バージョン管理されたエビデンスバンドルを1つ収集します。

<cli> harness evidence-bundle --platform <provider> --workspace <target> --cwd <effective-cwd> --language <locale> --depth <quick|normal> --since <window-start> --until <window-end> --format json [--include-memories] [--include-user-home] [--canvas-out <run-dir>/canvas.json]

--canvas-out は、Qoder／Cursor の永続レポートにのみ使用してください。Qoder では、デフォルトのプロジェクト Memory タイトルスキャンを維持します。--include-user-home は、許可されたグローバル Memory／設定やその他のユーザーアセットまで対象を広げます。Codex では、Memory メタデータに --include-memories が必要です。ユーザー／グローバルまたはインストール済み Plugin のメタデータには --include-user-home が必要です。両方の対象範囲が許可されている場合は、両方を適用してください。どちらのフラグも Memory 本文へのアクセスを許可するものではありません。

これはトポロジー、プロバイダー、期間、深度、上限、権限を固定します。委任の前に、bundle.context.topology.target を読み、kind、route、packageRoute（memberRoute または null）を報告してください。プロバイダー間で一致している必要があります。これは sessionEvidence、projectHarness、agentCustomize、およびリードエンベロープを返します。Agent Customize には、1つの共有アセットスナップショットから作成された、範囲が限定された lint、inventory、integrity エンベロープが含まれます。レーン／ステージのステータスとプロバイダーは個別に維持してください。名前が指定されたステージが利用できない、またはエビデンスが失われた場合の診断に限り、個別の session-analysis facts、core-change-watch evidence-pack、coding-agent-practices asset-baseline、または harness analyze コマンドを使用してください。診断出力をバンドルの代わりに使用したり、すべての所有者を再実行したりしてはいけません。Rules、Skills、MCP、Memory、Agents、Hooks、Commands、Workflows、Plugins の件数は、調査のルーティングにのみ使用します。件数がゼロでも多くても、それだけで指摘やスコアを作成してはいけません。プロジェクト Memory がある場合、通常の Qoder レポートでは integrity ステージが利用できないと処理を停止します。欠落したレビューを unobserved 判定に置き換えてはいけません。

プロバイダーが過去のインサイトソースを見つけた場合、またはユーザーが提供した場合、リードは許可されたアーキテクチャ／履歴メモを少数だけ確認できます。一般的なパスだと決めつけたり、検索したりしてはいけません。メモは現在の動作、設定された機能、または有効性の証明にはなりません。

Step 2: 3つの独立したエビデンスパスを実行する

読み取り専用の新しいエージェントを正確に3つ、並行して起動します。Codex では fork_turns: "none" を指定して spawn_agent を使用します。それ以外の場合は、同じブリーフに従ってローカルで個別に実行します。エビデンスエージェントは委任してはいけません。

2.1 セッションのエビデンス

リードは、プロバイダーのラベルが付いた事実のエンベロープを bundle.lanes.sessionEvidence.data から取得します。このデータの本番用コレクターは Sessions Diagnostics によってルーティングされ、 本番用の facts ルートのみを使用します。完全なバンドル、 コレクション参照、デバッグ出力、または生のセッションを Agent 1 に渡してはいけません。

Agent 1 に渡すのは、プロバイダーのラベルが付いた事実のエンベロープ、 Skills がゼロであることを検知するために必要な簡潔な Step 1 のアセット数、 および解決済みのスコープだけにしてください。Session Evidence を読み、 反復手順の需要がスコープに含まれる場合は、Repeated Workflow Discovery も 条件に応じて読むよう指示してください。プロジェクト、設定済みアセット、生のセッション、 または別のブリーフを調べてはいけません。

2.2 プロジェクトハーネスのエビデンス

Agent 2 に渡すのは、対象、スコープを限定した履歴／現在の変更範囲、 bundle.lanes.projectHarness.data、判断、リスク、 およびオーナーの上限だけにしてください。Project Harness Evidence を 読むよう指示してください。Session または Agent Customize の結論を渡してはいけません。

2.3 Agent Customize のエビデンス

Agent 3 に渡すのは、プロバイダーのラベルが付いた lint、インベントリ、 整合性の各エンベロープを含む bundle.lanes.agentCustomize.data、 アセットの権限、判断、リスク、 およびオーナーの上限だけにしてください。Agent Customize Evidence を 読むよう指示してください。決定論的なエンベロープを使用するため、 それらのコマンドを再実行したり、Session／Project の結論を受け取ったりしてはいけません。

各エージェントは、参照ドキュメント内で定められた自由形式の返却要件に従います。通常は候補を3〜5件、 クイックモードでは最大3件、エビデンスが乏しい場合はそれより少なくします。スペシャリストが 最終的な重大度やスコアを割り当てることはありません。

実行中は、リードアナライザーの結果として bundle.lead.data のみを使用します。この バンドルは --include-user-home をアナライザーのグローバル機能境界に対応付けます。 これにより、許可された MCP、Plugin、Skill、Hook、Memory の件数を維持しつつ、 コンテンツの読み取りを許可せず、使用の証明にもなりません。

バンドルが failed の場合、リードレーンが利用できない場合、またはそのデータに evidence か summaryFacts が含まれていない場合は停止してください。クイックモードでは、 partial バンドルが信頼度を下げ、利用できないスペシャリストはすべて明示されたままになります。 通常モードでは、利用できない、または一部のみのスペシャリストレーンがある場合、レポートを作成できません。 このエビデンス収集で委任できるエージェント数は、最大3つです。

ステップ 3：リードによる照合と再評価

各フィールドの役割についてはHarness Findings Inputを、5 つの次元、チェック項目、エビデンスの状態、スコアリング、Learning Capture のルールについてはAgent Work Loopを読んでください。例の内容はすべて置き換えてください。過去のレポート、Memory、recommend files、バリデーターから仕様を推測してはいけません。

照合は 1 回だけ行います。まず、すべての専門エージェントの候補を保持します。同じ対象、観測された結果、担当者、修復経路を持つ候補のみを統合します。より広いテーマを共有していても、独立した結果は保持してください。裏付けのない候補や保留中の候補には、それぞれ作業用の理由を残します。5 件に収めるため、レポートを短くするため、スコアを単純化するため、または 3 つの優先施策に合わせるために、対象となる指摘を削除してはいけません。その後、リードだけが次の作業を行います。

• 結果、原因の連鎖、最小の担当者、エビデンスの境界、確信度、検証担当者を検証します。
• 最終的な重大度と、Agent Work Loop の主要なチェック項目を 1 つ割り当てます。
• 指摘件数とは独立して、各次元のスコアを保守的に算出します。
• 意見の相違と利用できないエビデンスは、確信度を低くして保持します。
• 裏付けのある固有の指摘をすべて記載し、優先施策、修復プロンプト、読者向けの文章を整える前に、最終的な重大度と各次元のスコアを確定します。

ドラフトの作成前にFindings Quality Gatesを読み、適格性、一貫性、プライバシー、アセット、候補の昇格、修復プロンプトに関するチェックを直接適用してください。手順やナレッジに関する需要が繰り返し見られる場合は、Asset Demand Reconciliationも読んでください。

新しいレポートではsummary.suggestionsを作成しないでください。候補となる提案を通常のLow指摘に昇格できるのは、すべての指摘に適用される結果、担当者、エビデンス、出力、検証担当者、修復プロンプトの各ゲートを満たす場合に限ります。満たさない場合は、作業用の照合結果で保留にしてください。

指摘と各次元のスコアを確定した後、エビデンスと依頼された成果から、サポートトラックを 1 つだけ選択します。括弧内の範囲はユーザージャーニー上のラベルであり、スコアのしきい値ではありません。

• Bootstrap（0 -> 1）： 初期ガイダンスが明示的に求められている場合、または保持された指摘から、基礎となるナビゲーション、検証、リスク対応の経路が欠けていることが明らかな場合。
• Operationalize（1 -> 60）： 関連する仕組みは存在するものの、保持された指摘から、通常の作業に組み込まれていないか、成果につながる形で実行されていないことが明らかな場合。
• Optimize（60 -> 100）： 十分に揃った Session エビデンスに、繰り返し発生する目標または摩擦について、比較可能な個別の Task Episode が少なくとも 2 件含まれている場合。
• Undetermined： トラックの選択に必要なエビデンスを利用できない場合。

選択したトラックのみを読みます。Bootstrap Support、Operationalize Support、またはOptimize Supportを参照してください。トラックが形作ることのできるのは、すでに裏付けのある指摘に関する優先施策、修復プロンプト、読者向けの文章で、それぞれ最大 3 件です。指摘の追加、重大度の変更、次元スコアの再評価、レポートフィールドの追加、エビデンスや変更権限の拡大をしてはいけません。

永続的なレポートを作成する場合は、3 つのエビデンスエージェントが完了してからfindings.jsonのドラフトを作成してください。4 つ目のレビューエージェントを起動してはいけません。リードは品質ゲートを 1 回適用し、適格な指摘をすべて保持したうえで、レンダリング前に機械検証の失敗を修正します。

レポート出力 — ステップ 4：承認済みレポートをレンダリングする

インライン分析では何も書き込みません。リードのチェックに合格したら、ドラフトを唯一の最終版 findings.json として扱い、レンダリングして一度だけ検証します。

Qoder/Cursor: <mode>=<provider>-canvas; <host-root>=<target>/.<provider>/better-harness
Other providers: <mode>=html; <host-root>=<target>/.<provider>/better-harness
<cli> harness render --findings <run-dir>/findings.json --mode <mode> --out <host-root> --run-dir <run-dir> --target <target> --validate --json

Qoder/Cursor の分析では隣接する canvas.json が管理されます。summaryFacts を findings にコピーしないでください。HTML ではアナライザーの summaryFacts をそのまま保持します。status: pass の場合にのみ成功とみなし、レンダリング結果で報告された正確なパスを返してください。Canvas、Markdown、HTML を手書きしないでください。

最後に、簡潔な一文を記載します：<count> 件の指摘。 [レポートを開く](<renderer-path>)。 レンダラーが報告したプライマリレポートにリンクしてください。インラインコードのパス、ディレクトリのみのパス、出力ファイルの一覧は返さないでください。

ステップ 5：フォローアップ

• 指摘に紐づく修正には Finding-bound Fix を使用します。別個の独立した修正後エージェントは、検証済みの指摘の状態と Repair Progress を更新できます。Loop Effectiveness の評価は、比較可能な後続の Task Episodes まで保留します。
• 使用状況やモデルに関する質問には、session-analysis usage-summary を一度だけ使用します。
• 作業を繰り返す場合は、 Loop Discovery を通じて続行します。
• ルート：Agent Customize、 Core Change Watch、 Report Routing、 Source Review。

永続的なルートが認めるのは、そのホストルート内でレンダラーが所有する成果物だけです。その他の作成、有効化、変更、クリーンアップ、スケジューリング、外部への書き込み、ハイリスクなアクセスには、タスク固有の権限が必要です。所有者または値が未解決の場合は、再開条件を示して停止してください。代替の成果物を捏造したり、内部バリデーターを調べたりしないでください。