QUALITY_SCORE.md 完全ガイド：エージェントファーストなリポジトリの品質追跡を実装する

QUALITY_SCORE.md 完全ガイド：エージェントファーストなリポジトリの品質追跡を実装する

【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址: https://gitcode.com/gh_mirrors/le/learn-harness-engineering

この文書は、learn-harness-engineering リポジトリが提供する OpenAI アドバンストパック（docs/ja/resources/openai-advanced/）に含まれるrepo-template/docs/QUALITY_SCORE.mdテンプレートを深掘りし、エージェントファーストなリポジトリで「時間とともに強くなるリポジトリ」をどう運用するかを解説する技術ガイドです。読み終えると、評価スケールの設計意図、プロダクトドメイン／アーキテクチャレイヤー／ベンチマーク／単純化ログの4つの追跡表の記入方法、および AGENTS.md や RELIABILITY.md との連携による品質ループの回し方を、実装例つきで理解できます。

QUALITY_SCORE.md とは何か

QUALITY_SCORE.mdは、リポジトリが時間とともに強くなっているか弱くなっているかを追跡するための、リポジトリローカルな品質ダッシュボードです。冒頭の日本語コメントにある通り、このファイルは単なるスナップショットではなく、継続的な評価の記録を蓄積する仕組みとして設計されています。

このファイルの存在意義は、エージェントが「今どのドメインやレイヤーが最も弱いのか」をチャット履歴や人間の記憶に頼らずに発見できるようにすることにあります。Advanced Repo Template のコピー手順（docs/ja/resources/openai-advanced/repo-template/index.md）でも、AGENTS.mdとARCHITECTURE.mdをコピーした後、最初に記入すべき3ファイルのひとつとしてdocs/PRODUCT_SENSE.md、docs/QUALITY_SCORE.md、docs/RELIABILITY.mdが挙げられています。

テンプレートが最適化しているもの

同じ index.md には、このテンプレートが狙っている設計目標が明記されています：

• 永続的なリポジトリローカルコンテキスト
• 巨大な単一指示ファイルではなくプログレッシブディスクロージャー（段階的開示）
• 明示的なプランライフサイクル
• 時間経過による品質追跡
• エージェントと人間の両方にとって読みやすい境界

QUALITY_SCORE.mdはこのうち「時間経過による品質追跡」と「読みやすい境界」を担う中心ファイルです。

評価スケール：A〜D の4段階の意味

テンプレートが定義する評価スケールは以下の4段階です：

このスケールの特徴は、「動くかどうか」だけでなく「読みやすさ」「安定性」「境界の強制」を評価軸に含めている点です。エージェントが次に作業できる状態かを判定するため、コード単体の品質より「エージェント可読性」と「再現性」が重視されています。

追跡表1：プロダクトドメインの健全性

最初の表は、プロダクトをドメイン単位で評価します：

各カラムの記入指針は以下の通りです：

• ドメイン：プロダクト仕様（docs/product-specs/）や設計文書（docs/design-docs/）と対応するドメイン名を入れる。プレースホルダー[domain-a]を実プロジェクトのドメインに置き換えます。
• 評価：A〜D のスケール値。
• 検証：そのドメインが「本当に動作している」ことを示す実行可能な証拠（テストコマンド、ベンチマーク結果など）。コードを目視しただけでは「検証済み」にできません。
• エージェント可読性：新しいエージェントセッションがドキュメントだけでドメインを理解できるか。
• テスト安定性：そのドメインのテストがどの程度フレークせず安定しているか。
• 主要なギャップ：次に着手すべき穴を具体的に記録。
• 最終更新：YYYY-MM-DD 形式の日付。

追跡表2：アーキテクチャレイヤーの境界強制

2つ目の表は、レイヤードアーキテクチャの各層を評価します：

ここで注目すべきは「境界の強制（Boundary Enforcement）」カラムです。レイヤー間の依存ルールが「暗黙の約束」ではなく、リンターやテスト、CI などの機械的チェックで実際に守られているかを記録します。これは、docs/ja/resources/openai-advanced/sops/layered-domain-architecture.mdの SOP が扱う「レイヤードドメインアーキテクチャ」と対応しており、ARCHITECTURE.mdに記載された依存ルールが守られているかを追跡する役割を持ちます。

Types → Services → Runtime → UIの4レイヤーはプレースホルダーです。実際のプロジェクトのレイヤーモデルに合わせて列を追加・変更してください。

追跡表3：ベンチマークスナップショット

3つ目の表は、ハーネス（エージェント支援環境）の改良前後を定量的に比較するための記録です：

• ハーネスバリアント：baseline（素の状態）、improved（改良後）、simplified（単純化後）のいずれかを記録します。単純化後に品質が下がったかどうかを判断するための比較軸です。
• 完了率：タスクセットに対する完了の割合。
• リトライ：エージェントが失敗して再試行した回数。多いほどハーネスの指示が不明確であるシグナル。
• レビュー前の欠陥：人間のレビュー前に見つかった欠陥数。ハーネス品質の直接的な指標。

この表は、ハーネスを変更した際に「良くなったか悪くなったか」を印象ではなくデータで判断するために使います。プロジェクト 01（projects/project-01/README.md）が「素の状態 vs 最小ハーネス」の比較を扱っているのに対し、この表はその比較を継続的な回帰測定としてリポジトリに記録し続ける仕組みです。

追跡表4：単純化ログ

4つ目の表は、コンポーネント削除の履歴とその結果を記録します：

• 結果：削除後に品質がdegraded（悪化）したか、unchanged（変わらず）だったか。
• 決定：restore（復元する）かkeep removed（削除を維持）か。

この表は「単純化は第一級の責務」という OpenAI アドバンストパックの設計原則（docs/ja/resources/openai-advanced/index.md）を支えます。単純化は一度きりのイベントではなく、試行錯誤の記録として残すことで、将来のエージェントが「以前このコンポーネントを消して悪化した」という履歴を発見できるようにします。

テンプレート全体の中での役割と連携

AGENTS.md からのルーティング

repo-template/AGENTS.mdは、コード変更前のスタートアップワークフローとして以下を要求します：

1. pwdでリポジトリルートを確認する
2. ARCHITECTURE.mdを読む
3. docs/QUALITY_SCORE.mdを読み、どのドメインやレイヤーが最も弱いかを確認する
4. docs/PLANS.mdを読み、アクティブプランを開く
5. docs/product-specs/の関連仕様を読む
6. 標準ブートストラップと検証パスを実行する
7. ベースライン検証が失敗している場合、スコープ追加前に修復する

つまりQUALITY_SCORE.mdは、エージェントが「どこに手を付けるべきか」を決める最初の入力として設計されています。ルーティングマップではdocs/QUALITY_SCORE.md: プロダクトドメインとレイヤーの健全性と明記されており、短いAGENTS.mdから深いドキュメントへ段階的に開示（プログレッシブディスクロージャー）する構造の要です。

セッション終了時の更新義務

同じ AGENTS.md の「セッションの終了」セクションには、セッションを終える前に：

1. アクティブな実行プランを更新する
2. ドメインやレイヤーに意味のある変更があった場合、docs/QUALITY_SCORE.mdを更新する
3. 先送りした負債はdocs/exec-plans/tech-debt-tracker.mdに記録する
4. 終了したプランはdocs/exec-plans/completed/に移動する
5. 次のアクションが明確な再起動可能な状態でリポジトリを残す

QUALITY_SCORE.mdの更新は「独立したクリーンアップ日」ではなく、通常の作業の一部として行うことが運用ルールです（docs/ja/resources/openai-advanced/index.mdの導入方法にも同旨の記載あり）。

RELIABILITY.md との関係

docs/RELIABILITY.mdは「システムが正常で再起動可能であることをどう証明するか」を定義するファイルで、信頼性ルールとして以下を定めています：

• システムがクリーンに再起動できない場合、機能は完了とみなされない
• ランタイム障害はリポジトリローカルのシグナルから診断可能であるべき
• 繰り返される障害モードが現れた場合、ベンチマークまたはガードレールを追加する
• クリーンアップは信頼性の一部であり、別個の関心事ではない

QUALITY_SCORE.mdの「検証」「テスト安定性」カラムと、RELIABILITY.mdの「ゴールデンジャーニー（反復可能な検証パスと明確な失敗シグナルを持つ主要フロー）」は相互補完関係にあり、品質評価と稼働証明を同じ文書群に閉じ込めています。

実装例：Project 06 の quality-document.md から学ぶ実践パターン

このテンプレートの実運用イメージは、projects/project-06/solution/quality-document.md（キャップストーンプロジェクト「Runtime Observability and Debugging」の品質文書）が具体例として参考になります。同文書では、QUALITY_SCORE.md の「ドメイン」に相当する次元ごとに評価を付与しています：

Overall Grade: Aとして総括され、以下のような証拠（Evidence of Quality）が列挙されています：

• ビルド：npm run checkがクリーンにパス、npm run buildが正しい出力を生成、bash init.shが全ファイルの存在を検証
• ランタイム：構造化 JSON ログが初回起動から出力、インポートがメタデータを作成、バッチ索引が全ドキュメントを処理、Q&A が引用付きで接地回答を返す
• 観測性：すべての IPC チャネル呼び出しがログされる（qa:askは confidence / citationCount / answerLength / durationMs を記録）
• パフォーマンス（サンプルデータ）：ドキュメント3件インポート<200ms、バッチ索引<100ms、引用付きクエリ<300ms、クリーンリセット<20ms

さらに「Verified Against」セクションで、clean-state-checklist.md（30チェックすべてパス）、evaluator-rubric.md（総合 5.0/5）、feature_list.json（15/15 機能が status "pass"）という実行可能な検証証跡へのリンクを張っています。

この例が示す実践パターンは次の通りです：

1. 評価は主観ではなく証拠に紐づける：グレードの横に、どのチェックリスト・ルーブリック・ベンチマークで確認したかを必ず書く。
2. カラムの粒度はプロジェクトに合わせて変える：テンプレートの「ドメイン」を、プロジェクトの機能次元に読み替えて適用してよい。
3. B 評価も正直に残す：Test Coverage が B のように、完全でない次元を残すことで「次に何をすべきか」が見える。

QUALITY_SCORE.md を運用するための実践ステップ

ステップ1：初期記入（リポジトリ立ち上げ時）

Advanced Repo Template のコピー順序（docs/ja/resources/openai-advanced/repo-template/index.md）に従い、AGENTS.mdとARCHITECTURE.mdをルートにコピーし、docs/ツリー全体をコピーしたら、最初にPRODUCT_SENSE.md、QUALITY_SCORE.md、RELIABILITY.mdを記入します。初期状態では全セルが「-」でも構いません。重要なのはフォーマットを決めておくことです。

ステップ2：プレースホルダーの置換

• [domain-a]等を実際のプロダクトドメインに置き換える
• レイヤー表をARCHITECTURE.mdのレイヤーモデルと一致させる
• ベンチマーク表の[baseline / improved / simplified]を実際のハーネスバリアント名に合わせる

ステップ3：作業のたびに更新する

エージェントのワーキングコントラクト（AGENTS.md）にある通り、動作を変更した場合は同じセッションで対応するプロダクト・プラン・信頼性の文書を更新します。品質文書もその例外ではありません。「最終更新」カラムの日付を必ず今日の日付にします。

ステップ4：繰り返すフィードバックは機械的ルールへ昇格

AGENTS.md のワーキングコントラクトには「繰り返しのレビューフィードバックが見られた場合、チャットで再説明するのではなく、機械的なルール、チェック、またはリンターに昇格させる」とあります。QUALITY_SCORE.mdで同じギャップが繰り返し出現するようであれば、それはドキュメント更新ではなくリンターやテストで境界を強制するべきシグナルです。この判断は「境界の強制」カラムに記録されます。

よくある落とし穴と対処

• 一度書いて放置する：QUALITY_SCORE.md は静的スナップショットではなく履歴の蓄積です。日付つきで更新し続けないと、AGENTS.md のスタートアップワークフローが参照する「最も弱い領域」の情報が古くなります。
• 評価だけ書いて証拠を書かない：A〜D のグレードだけ並べても、エージェントは次に何をすべきか判断できません。「検証」「テスト安定性」「主要なギャップ」を具体的に埋めます。
• 単純化ログを付けない：コンポーネントを消した履歴が残っていないと、将来のエージェントが同じ失敗を繰り返します。削除したら必ず結果と決定を記録します。
• 他の文書と矛盾させる：ARCHITECTURE.mdのレイヤー名とQUALITY_SCORE.mdのレイヤー表が食い違うと、エージェントの信頼を損ないます。SOP「目に見えないナレッジをリポジトリにエンコードする」（docs/ja/resources/openai-advanced/sops/encode-knowledge-into-repo.md）の原則「同じ事実が矛盾する複数のファイルに散らばっていない」ことを維持します。

まとめ：QUALITY_SCORE.md がもたらすもの

QUALITY_SCORE.mdは、単なる「品質スコア表」ではなく、エージェントファーストなリポジトリにおける品質のシステム・オブ・レコードです。ドメイン・レイヤー・ベンチマーク・単純化の4つの視点でリポジトリの健全性を時系列で記録し、AGENTS.mdのルーティング層から常に参照されることで、「今どこが弱いか」をチャット履歴なしに発見できる状態を作り出します。

RELIABILITY.md（再起動可能性の証明）、PLANS.mdとexec-plans/（プランライフサイクル）、tech-debt-tracker.md（先送り負債の記録）と組み合わせることで、「作業 → 検証 → 評価更新 → 次の着手点の発見」という品質ループがリポジトリ内部に閉じて回り始めます。Project 06 の quality-document.md が示すように、評価のたびに実行可能な証拠へのリンクを張り、未達の次元を正直に残すことこそが、時間とともに強くなるリポジトリの土台です。

【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址: https://gitcode.com/gh_mirrors/le/learn-harness-engineering