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段階です評価意味原文の日本語訳実務上の解釈A検証済み、読みやすい、安定、境界が強制されている実装・検証・ドキュメントが揃い、依存ルールなどの境界が機械的チェックやテストで守られている状態B軽微なギャップはあるが動作する主要機能は動くが、テスト不足・ドキュメント欠落・境界違反の萌芽など小さな穴がある状態C部分的に動作、顕著な混乱または不安定性一部しか動かない、または設計意図が読み取れず不安定な状態D壊れている、安全でない、または構造的に不明確ビルド不能、セキュリティ上の問題、構造が破綻している状態このスケールの特徴は、「動くかどうか」だけでなく「読みやすさ」「安定性」「境界の強制」を評価軸に含めている点です。エージェントが次に作業できる状態かを判定するため、コード単体の品質より「エージェント可読性」と「再現性」が重視されています。追跡表1プロダクトドメインの健全性最初の表は、プロダクトをドメイン単位で評価しますドメイン評価検証エージェント可読性テスト安定性主要なギャップ最終更新[domain-a]------[domain-b]------[domain-c]------各カラムの記入指針は以下の通りですドメインプロダクト仕様docs/product-specs/や設計文書docs/design-docs/と対応するドメイン名を入れる。プレースホルダー[domain-a]を実プロジェクトのドメインに置き換えます。評価A〜D のスケール値。検証そのドメインが「本当に動作している」ことを示す実行可能な証拠テストコマンド、ベンチマーク結果など。コードを目視しただけでは「検証済み」にできません。エージェント可読性新しいエージェントセッションがドキュメントだけでドメインを理解できるか。テスト安定性そのドメインのテストがどの程度フレークせず安定しているか。主要なギャップ次に着手すべき穴を具体的に記録。最終更新YYYY-MM-DD 形式の日付。追跡表2アーキテクチャレイヤーの境界強制2つ目の表は、レイヤードアーキテクチャの各層を評価しますレイヤー評価境界の強制エージェント可読性主要なギャップ最終更新Types-----Services-----Runtime-----UI-----ここで注目すべきは「境界の強制Boundary Enforcement」カラムです。レイヤー間の依存ルールが「暗黙の約束」ではなく、リンターやテスト、CI などの機械的チェックで実際に守られているかを記録します。これは、docs/ja/resources/openai-advanced/sops/layered-domain-architecture.mdの SOP が扱う「レイヤードドメインアーキテクチャ」と対応しており、ARCHITECTURE.mdに記載された依存ルールが守られているかを追跡する役割を持ちます。Types → Services → Runtime → UIの4レイヤーはプレースホルダーです。実際のプロジェクトのレイヤーモデルに合わせて列を追加・変更してください。追跡表3ベンチマークスナップショット3つ目の表は、ハーネスエージェント支援環境の改良前後を定量的に比較するための記録です日付ハーネスバリアント完了率リトライレビュー前の欠陥備考YYYY-MM-DD[baseline / improved / simplified]----ハーネスバリアントbaseline素の状態、improved改良後、simplified単純化後のいずれかを記録します。単純化後に品質が下がったかどうかを判断するための比較軸です。完了率タスクセットに対する完了の割合。リトライエージェントが失敗して再試行した回数。多いほどハーネスの指示が不明確であるシグナル。レビュー前の欠陥人間のレビュー前に見つかった欠陥数。ハーネス品質の直接的な指標。この表は、ハーネスを変更した際に「良くなったか悪くなったか」を印象ではなくデータで判断するために使います。プロジェクト 01projects/project-01/README.mdが「素の状態 vs 最小ハーネス」の比較を扱っているのに対し、この表はその比較を継続的な回帰測定としてリポジトリに記録し続ける仕組みです。追跡表4単純化ログ4つ目の表は、コンポーネント削除の履歴とその結果を記録します日付削除されたコンポーネント結果決定YYYY-MM-DD[component][degraded / unchanged][restore / keep removed]結果削除後に品質がdegraded悪化したか、unchanged変わらずだったか。決定restore復元するかkeep removed削除を維持か。この表は「単純化は第一級の責務」という OpenAI アドバンストパックの設計原則docs/ja/resources/openai-advanced/index.mdを支えます。単純化は一度きりのイベントではなく、試行錯誤の記録として残すことで、将来のエージェントが「以前このコンポーネントを消して悪化した」という履歴を発見できるようにします。テンプレート全体の中での役割と連携AGENTS.md からのルーティングrepo-template/AGENTS.mdは、コード変更前のスタートアップワークフローとして以下を要求しますpwdでリポジトリルートを確認するARCHITECTURE.mdを読むdocs/QUALITY_SCORE.mdを読み、どのドメインやレイヤーが最も弱いかを確認するdocs/PLANS.mdを読み、アクティブプランを開くdocs/product-specs/の関連仕様を読む標準ブートストラップと検証パスを実行するベースライン検証が失敗している場合、スコープ追加前に修復するつまりQUALITY_SCORE.mdは、エージェントが「どこに手を付けるべきか」を決める最初の入力として設計されています。ルーティングマップではdocs/QUALITY_SCORE.md: プロダクトドメインとレイヤーの健全性と明記されており、短いAGENTS.mdから深いドキュメントへ段階的に開示プログレッシブディスクロージャーする構造の要です。セッション終了時の更新義務同じ AGENTS.md の「セッションの終了」セクションには、セッションを終える前にアクティブな実行プランを更新するドメインやレイヤーに意味のある変更があった場合、docs/QUALITY_SCORE.mdを更新する先送りした負債はdocs/exec-plans/tech-debt-tracker.mdに記録する終了したプランはdocs/exec-plans/completed/に移動する次のアクションが明確な再起動可能な状態でリポジトリを残す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 の「ドメイン」に相当する次元ごとに評価を付与しています次元評価注記抜粋Build CompileAクリーンなコンパイル、エラー・警告なしFeature CompletenessA15機能すべて実装・パスStructured LoggingAJSON 形式、ログレベル、サービスタグ、全サービスのデータペイロードQA with CitationsA8つの回答パターン、キーワード検索、信頼度スコアPersistenceA全データ型が再起動後も永続Clean State ResetA確認付き完全リセット、べき等Test CoverageBビルド時チェックはパス、ランタイム検証はベンチマークスクリプト経由BenchmarkingAimport/index/query のタイミングを含む完全タスクスイートOverall Grade: Aとして総括され、以下のような証拠Evidence of Qualityが列挙されていますビルドnpm run checkがクリーンにパス、npm run buildが正しい出力を生成、bash init.shが全ファイルの存在を検証ランタイム構造化 JSON ログが初回起動から出力、インポートがメタデータを作成、バッチ索引が全ドキュメントを処理、QA が引用付きで接地回答を返す観測性すべての IPC チャネル呼び出しがログされるqa:askは confidence / citationCount / answerLength / durationMs を記録パフォーマンスサンプルデータドキュメント3件インポート200ms、バッチ索引100ms、引用付きクエリ300ms、クリーンリセット20msさらに「Verified Against」セクションで、clean-state-checklist.md30チェックすべてパス、evaluator-rubric.md総合 5.0/5、feature_list.json15/15 機能が status passという実行可能な検証証跡へのリンクを張っています。この例が示す実践パターンは次の通りです評価は主観ではなく証拠に紐づけるグレードの横に、どのチェックリスト・ルーブリック・ベンチマークで確認したかを必ず書く。カラムの粒度はプロジェクトに合わせて変えるテンプレートの「ドメイン」を、プロジェクトの機能次元に読み替えて適用してよい。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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考