> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qoder.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Better Harness
> Qoder 内蔵エンジニアリングエキスパート——プロジェクトの Harness エンジニアリングを Agent が診断し、弱い箇所を指摘したうえで、ワンクリックで修復タスクを起動できる機能です。
## Agent Harness とは
今日の Coding Agent は要件を読み、コードを書き換え、テストを実行し、Pull Request を提出することさえできます。しかし「多くのことができる」は「うまくやれる」とは限りません。Agent は通常「タスクを理解する → 操作を実行する → 結果を確認する → 調整を続ける」というサイクルを繰り返します。これが Agent Loop です。
本当に信頼できる Loop とは、Agent を動かし続けることではなく、ゴールが何か、触ってはいけない箇所はどこか、結果が正しいかどう判断するか、失敗したらどうするかを Agent に分からせることです。そうでなければ、大量のコードを変更し大量のテストを実行しても、タスクが本当に完了したことを証明できないかもしれません。
これが Loop Engineering と Harness Engineering が解決しようとしていることです。Agent のためにプロジェクトのコンテキスト、関連する開発ツール、検証手法、明確なセーフティ境界を準備し、すべての Loop を確実な納品に近づけます。
Qoder における Loop エンジニアリングは、Rules、Skills、Hooks、MCP 設定、Custom Agents、Plugins、Session Insights などの資産タイプを包含します。
## なぜ Better Harness が必要なのか
良い Loop エンジニアリングを作るのは決して簡単ではありません。書き残されるべきルールが誰かの頭の中にだけある。振り返りで見つかった問題がルールに落ちない。チームの慣習が Slack のスレッドに散らばり、`AGENTS.md` は空のまま。多くのチームには、それをきちんとやりきるための時間も、明確な基準もありません。
Qoder 内部の実践と、Coding Agent・Loop エンジニアリング・ソフトウェア開発領域でコミュニティが蓄積してきたベストプラクティスに基づき、私たちは **Better Harness** をリリースしました。
最新の Qoder では、Better Harness に入ってビジュアルインターフェースから分析を起動し問題を修復することも、`/better-harness` を直接実行することもできます。Agent がタスクを実行する過程を分析し、欠けている・弱い重要要素を特定し、次に何を補強すべきかを明確にします。
## Better Harness の仕組み
Better Harness がチェックするのは、一回の回答の良し悪しではなく、Coding Agent のタスク完遂を支える Harness 全体です。目標とコンテキストは明確か、プロジェクトは実行しやすいか、権限は制御されているか、検証は有効か、納品は安全か、そしてチームと Agent はタスクから継続的に学習できるか。
主要な分析プロセス：
1. **現在の Harness をマッピングする** — 目標、コンテキスト、実行エントリポイント、フィードバック、納品、学習メカニズムを特定する。
2. **ブレークポイントを見つける** — どのリンクにメカニズム、統合、実際の実行、またはエビデンスが欠けているかを説明する。
3. **最小の改善手段を選ぶ** — 問題を最も適切な Rule、Skill、Hook、スクリプト、自動化、または人間のゲートに割り当てる。
4. **修復して再検証する** — 修復範囲を限定し、関連する検証を実行し、`/better-harness` を再実行して Loop が実際に改善されたか確認する。
分析時、Better Harness はメインの分析フローで生データを収集し、3 つの独立した読み取り専用サブ Agent にそれぞれ異なるカテゴリのエビデンスを解釈させます：**Agent カスタマイズ資産**（Rules、Skills、Hooks などの設定が完全で使用可能か）、**実際のタスクセッション記録**（実際のタスクで Agent が何をし、どう結果を出したか）、**プロジェクトのソフトウェアエンジニアリング基盤**（プロジェクトが Agent のワークフローをサポートしているか）。3 カテゴリは独立して収集された後に統合され、結論の相互汚染を防ぎます。
## Better Harness が評価すること
Better Harness は選択したプロジェクトをスキャンし、5 つの観点で分析レポートを生成します。
* **Task Understanding（タスク理解）** — Agent がこのプロジェクトを認識し、タスクをどこから始め、変更範囲をどこまでに抑えるべきかを理解できるか。
* **Controlled Execution（可制御な実行）** — Agent がプロジェクトの指示に従って起動・操作でき、明確な権限と操作範囲の中で作業を完遂できるか。
* **Change Validation（変更検証）** — 各変更に対して lint やテストなどのチェックを実行し、失敗した場合に修正して再検証できるか。
* **Reliable Delivery（確実な納品）** — タスクの結果に検証可能な根拠があり、リスクの高い操作に承認・ロールバック・復旧手段が用意されているか。
* **Learning Capture（学びの蓄積）** — 繰り返し発生する問題が、発見可能で再利用可能なルールや Skill として蓄積され、次の同種タスクで実際に活きているか。
各観点はバーチャートでスコアが表示され、関連する findings の数も示されます。レポートにはプロジェクトの現在の Scope 概要（Rules、Skills、Custom Agents、MCPs、Memories、Hooks）も含まれます。どの提案も **Plan a fix** から Agent にワンクリックで引き渡せます。修復タスクは Quest に流れ、Agent がまずプランを提示し、あなたは通常の Quest タスクと同じように変更を確認できます。
## 使い方
1. 左サイドバー下部の **Better Harness**（Knowledge、Marketplace と並列）をクリックします。
2. 上部にプロジェクトがタブとして表示されます（例：air、maERP、condo、twenty、flow）。タブをクリックして切り替え、**+ Add Project** で新規追加できます。
3. プロジェクトの初回スキャン時、「Understanding your project structure…」と表示され、Agent がモジュール、依存関係、コード構造を読み込みます。進捗は **View in Quest List** から確認できます。
4. レポートが生成されると、概要ページに 5 観点のバーチャートスコア、関連 findings 数、Scope 統計（Rules、Skills、Custom Agents、MCPs、Memories、Hooks）が表示されます。
5. チャートの下に finding カードが一覧表示され、**All Findings / Processed / Pending** タブでフィルタリングできます。各カードには優先度（High/Medium/Low）、タイトル、所属観点が表示されます。
6. カードで **Plan a fix** をクリックすると修復フローが開始されます。不要な提案は **Ignore** をクリックして非表示にできます。
7. **Regenerate** で新しいスキャンを実行、**View Details** で完全レポートページを開けます。
Better Harness は自動でコードを書き換えることはありません。すべての修復は Quest タスクとして表示され、レビュー・ロールバックが可能です。Better Harness は問題を指摘し、プロンプトを準備するだけです。
## 5 つの観点の詳細
Agent が目標、関連コンテキスト、変更範囲を理解しているかを確認します。タスクの方向性と境界が明確になっているかがポイントです。
Agent がプロジェクトの指示どおりに起動・操作でき、明確な権限と操作境界の中でタスクを完遂できるかを確認します。
Agent が今回の変更に対して該当するチェックを実行し、失敗時に修正して再検証できるかを確認します。
タスクの結果に検証可能な根拠があるか、リスクの高い操作に承認・ロールバック・復旧手段があるかを確認します。
繰り返し発生する問題が、発見可能で再利用可能なルール・ワークフロー・ツールとして蓄積され、次の類似タスクで効果が確認できているかを見ます。
## 修復プランを作成する
カードの **Plan a fix** をクリックすると、**Finding Detail** ダイアログが開きます。内容は以下の通りです：
* **Priority** インジケーター（High/Medium/Low）
* **問題タイトル** と所属観点（例：「Repair Plan · Change Validation」）
* **Cause** — 現在の構成にこのギャップがある理由
* **Expected Output** — 修復で達成すべきこと
* **Fix Instructions** — `/harness` で始まる編集可能なプロンプトが事前に入力されています。そのまま使うことも、編集してから確認することもできます。
下部にモデルセレクターと **Start Fix** ボタンがあります。クリックすると修復説明をもとに新しい Quest が作成され、Quest リストから追跡できます。
修復はすべて Quest 経由で実行されるため、Agent の各操作は監査可能かつ取り消し可能です。リポジトリに見えない変更が入り込むことはありません。
特定された改善機会について、ユーザーは **Plan a fix** をクリックするだけで AI が修復プランを生成・実行します。さらに重要なのは、これらの修復は現在のタスクだけに留まらず、Rules、Skills、Memories などの再利用可能な資産として蓄積され、自分自身の Agent Harness を持続的に強化できることです。
## 完全レポートを表示する
概要ページ右上の **View Details** をクリックすると、完全レポートページが開きます。以下のモジュールが含まれます：
* **Agent ワークフロー** — 5 つの観点スコアをノードとして表示するパイプラインビジュアライゼーション。
* **プロジェクト使用量** — 日次アクティビティのヒートマップ、分析済みセッション数、推定アクティブ分数、Skill 使用回数、最も使用された Skills。
* **Prioritized improvements（優先最適化項目）** — すべての finding カードに **Plan AI Fix** と **View details** アクションが付きます。
* **Agent カスタマイズ** — 発見された Loop エンジニアリング資産（Hooks、MCP、Plugins）と対応状況（Rules、Skills、Session Insights、Custom Agents）。
* **証拠と方法** — サンプリング信頼度、ソースギャップ、納品結果など、結論の根拠となるデータ量を示します。
* **長時間セッションのレビュー** — 45 分を超えるセッションを人間のレビュー用にフラグ付けします。
* **セッション観察** — 分析済みセッションから抽出された代表的な観察事項。調査の優先順位付けに使います。
## レポートの再生成
レポートカードには更新時刻（24 時間制、ローカルタイムゾーン）が表示されます。プロジェクトが進化するにつれ、古いレポートの参考価値は下がります。**Regenerate** をクリックすると新しいスキャンが始まり、新しいレポートが既存のものを置き換えます。
次のような場合に再生成をおすすめします。
* レポートに基づいて Loop エンジニアリングの改善をまとめて適用し、スコアの変化を確認したいとき。
* プロジェクト構造が大きく変わったとき（モジュール追加や大規模なリファクタなど）。
* 前回のレポートから 2〜3 週間以上経過したとき。
## すべての Harness を次の能力へ蓄積する
一回の `/better-harness` 分析は終わりではありません。ブレークポイントの発見、修復プランの生成、修復後の新しい Rule・Skill・Hook・スクリプトが Agent のワークサイクルに本当に組み込まれたかの検証を支援します。
さらに重要なのは、再利用に値する経験が個人またはチームの Agent 資産として蓄積され、以降の Loop がより安定し、効率的で、制御可能になることです。今すぐ Qoder で Better Harness に入るか、`/better-harness` を実行して、次に最も補強すべきものを確認してみてください。