リポジトリのハーネスエンジニアリング成熟度を診断する
OpenAI「Harness engineering: leveraging Codex in an agent-first world」に基づき、 対象リポジトリのハーネスエンジニアリング成熟度を 4つの柱 + ボーナス(計24項目/72点満点) で診断する。
例: /harness-eval /path/to/repo または /harness-eval
以降、対象リポジトリのパスを $REPO と表記する。
エージェントに適切な情報を適切なタイミングで提供できているか。 実効性の観点: エージェントがそのドキュメントを読んで、実際にプロジェクト固有の正しい判断ができるか。汎用的なテンプレートのコピペでは実効性は低い。
| # | 項目 | スコア3(実効的) | スコア2(機能的) | スコア1(形式的) | スコア0(未実装) |
|---|---|---|---|---|---|
| 1.1 | エージェント指示ファイル | プロジェクト固有のアーキテクチャ決定・禁止パターン・コマンド体系が的確に記載され、エージェントの判断に直接影響する内容 |
| 存在し基本情報はあるが、プロジェクト固有の判断に必要な情報が不足 |
| 存在するが汎用的な内容のコピペ、または内容が実態と乖離 |
| なし |
| 1.2 | 指示の簡潔さ(目次型) | 〜100行以内で要点を押さえ、詳細は別ファイルへのポインタで段階的にアクセスできる | 存在するが長大(200行超)でコンテキストを圧迫、またはポインタなし | 1ファイルに全部詰め込みでエージェントが重要情報を見落としやすい | なし |
| 1.3 | 構造化ドキュメント | docs/に設計判断の「なぜ」、API仕様、アーキテクチャの制約が整理され、エージェントが実装判断に使える | docs/はあるが内容が古い・不完全で、エージェントが誤った判断をするリスクがある | READMEに少し書いてある程度で、エージェントの実装判断には不十分 | なし |
| 1.4 | 段階的情報開示 | 概要→詳細の階層が明確で、エージェントが必要な深さまで自力で辿れる | 一部階層化されているが、リンク切れや構造の不整合がある | フラットな構造で、エージェントが情報を探すのに苦労する | なし |
| 1.5 | リポジトリ内完結 | エージェントの実装判断に必要な情報がすべてリポジトリ内にある | 大半はあるが、重要な設計判断やドメイン知識の一部が外部依存 | コーディング規約・設計判断など重要情報がSlack/Notion等の外部にある | ほぼ外部依存 |
エージェントの誤りを機械的に防止する仕組みがあるか。 実効性の観点: 「〜してください」という依頼ではなく、機械的に違反を検出・ブロックできるか。エージェントが実際に犯しうるミスを防いでいるか。
| # | 項目 | スコア3(実効的) | スコア2(機能的) | スコア1(形式的) | スコア0(未実装) |
|---|---|---|---|---|---|
| 2.1 | リンター/フォーマッター | プロジェクトの技術スタックに適した厳格な設定で、エージェントの典型的ミスを実際に検出できる | 設定はあるがルールが緩く、エージェントのミスを見逃す | 最低限のデフォルト設定のみで、プロジェクト固有の問題を検出できない | なし |
| 2.2 | カスタムリントルール | プロジェクト固有のアーキテクチャ違反(禁止import、必須パターン等)を機械的に検出する | 一部カスタムルールはあるが、カバー範囲が限定的 | 標準ルールのみで、プロジェクト固有の制約は検出できない | なし |
| 2.3 | 依存関係レイヤリング | レイヤー定義がありリンター/CIで機械的に強制。違反するとビルドが通らない | レイヤー定義はあるが強制が不完全(一部のみ、または文書だけ) | 暗黙の慣習のみで、エージェントが違反しても検出されない | なし |
| 2.4 | 構造テスト | ArchUnit的なテストでアーキテクチャ不変条件を自動検証し、エージェントの構造破壊を防ぐ | 一部の構造検証はあるが網羅性が不十分 | なし | なし |
| 2.5 | Pre-commit / CI ゲート | pre-commit hook + CI の両方で自動検出し、違反コードがマージされない | CIのみ or hookのみ(片方のフィードバックループが欠落) | 手動実行のみで、エージェントが自動的にフィードバックを受けられない | なし |
| 2.6 | テストスイート | ビジネスロジック・エッジケースを的確にカバーし、エージェントが自分の変更の正しさを検証できる | テストはあるがカバー範囲が偏っている(UIのみ、happy pathのみ等) | テストが少数でエージェントの実装ミスを検出する力が弱い | ほぼなし |
| 2.7 | 型システム/スキーマ | strict mode + 境界でのバリデーション(Zod/Pydantic/Freezed等)で、エージェントの型ミスをコンパイル時に検出 | 型はあるが strict でなく、エージェントが不正な型を通せる余地がある | 部分的に型があるが、重要な境界で型安全性が確保されていない | 型なし |
PR単位のCIでは検知できない、コードベース全体の経時的な劣化を検知し是正する仕組みがあるか。 柱2との違い: 柱2はPR CIでエージェントのミスを防ぐ仕組み(防御的)。柱3はPRが来なくても、または複数PRの積み重ねで発生する全体的な劣化を能動的に検知・修正する仕組み。
| # | 項目 | スコア3(実効的) | スコア2(機能的) | スコア1(形式的) | スコア0(未実装) |
|---|---|---|---|---|---|
| 3.1 | ドキュメント整合性検証 | エージェント指示ファイル(CLAUDE.md/rules等)とコードの実態の乖離を定期的に自動検出し、修正まで繋げる仕組みがある | 手動レビューやPR時に確認する運用がある | なし | なし |
| 3.2 | 定期全体スキャン | unused code/files、品質メトリクスの推移、依存の陳腐化など、PR単位では見えない全体的劣化を定期スキャンで検知している | 一部のスキャン(Renovate等の依存更新)はあるが、コード品質全体の定期スキャンはない | なし | なし |
| 3.3 | 能動的修正 | 検知した劣化に対して自動修正PR生成、またはIssue→エージェント連携で是正まで繋げるフィードバックループが閉じている | 検知はするが修正は手動。または修正PRは出すがレビュー/マージが滞っている | 検知のみで修正の道筋がない | なし |
補足: 以下の項目はスコア対象外だが、改善提案のアドバイスとして記載する
柱3の議論の中でよく挙がるが、実際にはPR CIや柱2で対応すべき項目。もしこれらが未整備の場合、柱2のスコアが低くなっているはずであり、改善提案で「CIの品質ゲートを厚くすべき」としてアドバイスする:
エージェントの作業フローが構造化され、自己検証とエスカレーションの仕組みがあるか。 実効性の観点: ワークフローが定義されているだけでなく、エージェントが実際にそのフローに従って品質の高い成果物を出せるか。形だけのスキル定義は低スコア。
| # | 項目 | スコア3(実効的) | スコア2(機能的) | スコア1(形式的) | スコア0(未実装) |
|---|---|---|---|---|---|
| 4.1 | 構造化ワークフロー定義 | Plan→Work→Review等のフローが定義され、各段階で品質ゲートが機能している | フロー定義はあるが品質ゲートが不十分、または一部の段階が形骸化 | スキル/ワークフロー定義はあるが内容が汎用的で、プロジェクト固有の品質担保に繋がっていない | なし |
| 4.2 | セッション/状態管理 | progress file, git log等でエージェントが前回の作業状態を正確に引き継ぎ、中断→再開できる | git履歴はあるが明示的な状態管理がなく、引き継ぎの精度が低い | 毎回ゼロから開始で、作業の重複や見落としが発生しうる | なし |
| 4.3 | 自己検証メカニズム | テスト実行・スクリーンショット・observability等で、エージェントが自分の変更の正しさを多角的に検証できる | テストはあるが検証手段が限定的(単一の検証方法のみ) | 手動確認のみで、エージェントが自力で品質を判断できない | なし |
| 4.4 | ガードレール | hooks/CI等で破壊的操作(secrets書き込み、force-push、本番DB操作等)を機械的にブロックする | 一部の操作のみ防止(設定ファイルで明示) | AGENTS.md等で「やるな」と記載のみで機械的強制なし | なし |
| 4.5 | エスカレーション/Human-in-the-loop | エージェントが行き詰まった時の判定基準と人間への通知・介入フローが定義され機能している | フローは定義されているが判定基準が曖昧、または通知が不十分 | 人間が気づいて介入する運用のみ(エージェント側からの通知なし) | なし |
実効性の観点: エージェントが実際に使いやすく、品質向上に寄与するインフラか。
| # | 項目 | スコア3(実効的) | スコア2(機能的) | スコア1(形式的) | スコア0(未実装) |
|---|---|---|---|---|---|
| B.1 | 枯れた技術の選択 | エージェントが正確に扱える安定技術で統一され、ドキュメント・学習データが豊富 | 大半は安定技術だが、一部でエージェントが苦手な新しいAPI/フレームワークを使用 | 最先端フレームワーク依存でエージェントの生成精度が低下しがち | 不安定な技術多数 |
| B.2 | エージェント専用ツール | テストランナー・スクリーンショット取得・フィルタ付き実行等、エージェントの作業効率を実際に上げるツールがある | 一部支援ツールはあるが、エージェントが本当に必要とする場面をカバーしきれていない | ツールはあるが使いにくい、またはエージェントの実際のニーズと合っていない | なし |
| B.3 | エラーメッセージの改善 | リンター/CIのエラーに具体的な修正手順がエージェントのコンテキストに注入される | 人間向けに分かりやすいエラーメッセージで、エージェントも参考にできる | エラーメッセージが最小限で、エージェントが修正方法を推測する必要がある | スタックトレースのみ |
| B.4 | ディレクトリ構造の規約 | 一貫した命名規則・構造が文書化され、新規ファイル追加時にエージェントが迷わない | 慣習的に一貫しているが文書化されておらず、エージェントがパターンを推測する必要がある | 構造がバラバラでエージェントが間違った場所にファイルを作りがち | なし |
対象は $REPO(引数があればそのパス、なければカレントディレクトリ)。
以下の4つのサブエージェントを Explore エージェント(very thorough)で並列起動する。
担当: 柱1(1.1〜1.5)のスコアリングに必要な情報を全て収集する。
ファイル探索:
CLAUDE.md, AGENTS.md, .cursorrules, .github/copilot-instructions.md, .agents/**/*, .claude/**/*, .codex/**/* の存在確認docs/, doc/, documentation/ ディレクトリの存在と全構造中身の精査(実効性判断のため必須):
担当: 柱2(2.1〜2.7)のスコアリングに必要な情報を全て収集する。
設定ファイル精査:
.eslintrc*, .prettierrc*, ruff.toml, pyproject.toml, biome.json, analysis_options.yaml, dcm*.yaml)を全て読み、ルールの厳格さを判断tsconfig.json / analysis_options.yaml の strict 設定を確認.pre-commit-config.yaml, .husky/, .lefthook.yml を読み、何が hookで実行されるか確認CI設定精査:
.github/workflows/ 配下の全ワークフローファイルを読み、何がチェックされるか・どのトリガーで実行されるか確認.gitlab-ci.yml, Jenkinsfile 等も探索greptile.json等の設定ファイルを読み、定義されたルールの内容と強制力を評価するテスト精査:
jest.config*, vitest.config*, pytest.ini, テスト用 pubspec.yaml)を確認型システム精査:
担当: 柱4(4.1〜4.5)のスコアリングに必要な情報を全て収集する。
ワークフロー精査:
.claude/skills/, .agents/skills/, .codex/skills/ 配下のスキル定義を全て読み、各スキルの目的・品質ゲート・実効性を判断.claude/agents/, .agents/agents/ 配下のエージェント定義を全て読み、ワークフローの段階性を確認WORKFLOW.md, Plans.md 等のワークフロー定義の有無と内容状態管理精査:
*progress*, *status*, goals/)の有無ガードレール精査:
.claude/settings.json, .claude/settings.local.json を読み、permissions/hooks設定を確認エスカレーション精査:
担当: 柱3(3.1〜3.5)+ ボーナス(B.1〜B.4)のスコアリングに必要な情報を全て収集する。 加えて、このエコシステムで利用可能な品質管理ツール・手法の調査も行う。
Phase 1: エコシステムの品質管理ツール調査(WebSearchで実施)
Entropy Managementの3段階(基準定義→ドリフト検知→是正)を実現するために、 そのリポジトリの技術スタックで実際に利用可能なツール・機能をWebSearchで調査する。
調査する観点:
init baseline(Flutter)、ESLint --cache(JS/TS)、SonarQube品質ゲート、ruff baseline(Python)dart fix --apply(Flutter)、eslint --fix(JS/TS)、ruff check --fix(Python)、cargo fix(Rust)check-unused-code(Flutter)、knip(JS/TS)、vulture(Python)、cargo-udeps(Rust)gh pr createこの調査結果を、Entropy Managementのスコアリングと改善提案に活用する。 「仕組みがない」で終わるのではなく、「このエコシステムにはXというツールがあり、Y機能でドリフト検知が可能だが、導入されていない」という具体的な指摘を出す。
Phase 2: 既存の品質管理の精査
品質管理精査:
オブザーバビリティ精査:
自動化精査:
schedule: トリガー)を全て読み、何が定期実行されるか確認インフラ精査:
scripts/, tools/, .mise-tasks/ 等のカスタムスクリプトを全て読み、エージェント支援に役立つか判断Phase 3: ギャップ分析
Phase 1(利用可能なツール)とPhase 2(既に導入済みのもの)の差分を明確にする。 「このエコシステムでは○○が可能だが、このリポジトリでは導入されていない」をリストアップする。 このギャップがEntropy Managementの改善提案の根拠になる。
各24項目を 0〜3の4段階 でスコアリングする。
| スコア | 表示 | 意味 |
|---|---|---|
| 3 | 🟢 | 実効的 — エージェントの自律的な品質向上に実際に寄与している |
| 2 | 🟡 | 機能的 — 仕組みはあり一定の効果があるが、カバー範囲や精度に改善余地がある |
| 1 | 🟠 | 形式的 — 仕組みは存在するが、実効性が低い(形だけ、内容が薄い、的外れ等) |
| 0 | 🔴 | 未実装 — 該当する仕組みが存在しない |
最重要原則: 存在ではなく実効性を評価する
このスキルのゴールは「AIエージェントが自律的に品質の良い成果物を出すための仕組みが整っているか」を判定すること。 形だけ真似していても実効性がなければスコアは低くなる。以下の判定ルールに従うこと。
判定ルール:
実効性チェックの具体例:
| 観察 | 判定 |
|---|---|
| CLAUDE.mdが200行あるが、内容が一般的なコーディングマナーのコピペ | 🟠 1 — 形式的。プロジェクト固有の判断に寄与しない |
| CLAUDE.mdが80行だが、そのプロジェクトのアーキテクチャ決定・禁止パターン・コマンド体系が的確に記載 | 🟢 3 — エージェントの判断・行動に直接影響する |
| テストが100件あるが全てスナップショットテスト | 🟠 1 — 形式的。エージェントの実装ミスを検出する力が弱い |
| テストが30件だがビジネスロジック・エッジケースを的確にカバー | 🟡 2〜🟢 3 — エージェントの自己検証に実効的 |
| カスタムリントルールが10個あるが全て「変数名をcamelCaseにする」系 | 🟠 1 — フォーマッターで済む内容で、アーキテクチャ保護になっていない |
| カスタムリントルールが3個だが「特定レイヤーからの禁止import」を検出 | 🟢 3 — アーキテクチャの崩壊を機械的に防いでいる |
レポートには 素点(均一配点) と 重み付きスコア の両方を表示する。
全項目を等しく0〜3点で合算する。最大78点。 シンプルで直感的。各項目の達成度をフラットに把握するのに向く。
柱ごとに重みを掛けて合算する。エージェント主導の開発で実際に効いてくる重要度の差を反映する。
| 柱 | 重み | 根拠 |
|---|---|---|
| Context Engineering | ×1.0 | 入口として必須だが、整備は比較的容易。CLAUDE.md作成は数時間で可能 |
| Architectural Constraints | ×1.2 | 基盤。OpenAI「制約がなければ速度は出るが崩壊する」。リンター・型・CIが機械的にミスを防ぐ |
| Entropy Management | ×1.5 | PR CIでは検知できない全体的劣化の検知・是正。項目数は少ないが1項目あたりの重要度が高い。自動化しないと人間が掃除係になる |
| Agent Workflow | ×1.0 | 重要だが比較的新しい概念。記事群でも具体的な定義は確立途上 |
| ボーナス | ×0.8 | あると良いが必須ではない。エージェント専用ツールや枯れた技術選択は補助的要素 |
重み付き最大点: 78.3点(15×1.0 + 21×1.2 + 9×1.5 + 15×1.0 + 12×0.8)
レベル判定は 重み付きスコアの達成率 で行う。 重みにより、Entropy Managementを軽視しているリポジトリは正当にスコアが下がり、 Architectural Constraintsが充実しているリポジトリは正当に評価される。
| レベル | 重み付き達成率 | 説明 |
|---|---|---|
| Level 3: Full Harness | 76%+ | 4柱すべてが機能し、エージェントが自律的に開発・検証・修正できる状態。ワークフロー定義、機械的制約、自動品質管理、エスカレーションが揃っている |
| Level 2: Structured Harness | 48〜75% | Context EngineeringとArchitectural Constraintsの基盤があり、エージェントが安全に作業できる。ただしEntropy ManagementやAgent Workflowに欠落がある |
| Level 1: Basic Harness | 24〜47% | エージェント指示やリンター等の最低限の仕組みはあるが、機械的強制や自動修正の仕組みが不足している |
| Level 0: No Harness | 0〜23% | エージェントが作業するための仕組みがほぼ整備されていない |
スコアリング結果を元に、「自分(エージェント)がこのリポジトリで自律的に作業する場合」の視点で総合評価を行う。
必ず確認した事実のみに基づいて記述し、推測を入れない。
以下の4観点で評価する:
さらに「逸脱リスクマップ」として、具体的リスク・根拠・影響度・既存の防御を表にまとめる。
Top 5 の優先改善アクションを選定する。
選定原則(安易な提案を排除する):
各アクションに必ず含める:
Step 5 で作成した改善提案を、別の Agent(general-purpose)を起動して独立レビューさせる。 診断を行ったエージェントのバイアス(自分が出した提案を正当化する傾向)を排除するため、 別コンテキストで改善提案の妥当性を検証する。
レビューエージェントへの指示:
以下を渡してレビューを依頼する:
Phase 1: 技術スタックの深い理解を取得する(レビュー前に必須)
レビューエージェントは、提案を評価する前に以下を実施する:
この調査結果を踏まえた上で、各提案の実現可能性と実効性を評価する。 フレームワークの知識が浅い状態で「〜すべき」と指摘してはならない。
Phase 2: レビューの評価軸(ハーネスエンジニアリングの本質に基づく)
各改善提案について、以下の2つの問いに答えさせる:
問い1: この提案を実装すると、エージェントが自律的に逸脱なくコーディングを進められるようになるか?
問い2: この提案を実装すると、エージェントが自律的に品質を修正し続けられるようになるか?
各提案に対して以下を判定:
| 判定 | 意味 |
|---|---|
| 採用 | 両方の問いにYes。実装すべき |
| 条件付き採用 | 一方にYesだが、提案内容の修正が必要。修正内容を具体的に指摘 |
| 却下 | 両方にNo、または実現可能性に問題あり。却下理由を具体的に記述 |
| 代替提案 | 同じ問題に対してより実効的な解決策がある。代替案を具体的に提示 |
レビューは3ループ回す。
ループ1: 改善提案の初稿をレビューエージェントに渡す。採用/条件付き/却下/代替の判定を受ける。 ループ2: ループ1の結果を反映した修正版を、同じレビューエージェントにSendMessageで再度レビューさせる。修正が適切か、新たな問題がないかを確認。 ループ3: ループ2の結果を反映した最終版を、再度レビュー。全提案が「採用」になるまで磨く。3ループ目で「条件付き」以上なら最終版として採用する。
3ループ完了後、最終版の改善提案をレポートに反映する。
以下のフォーマットでレポートファイルに保存する。
.claude/harness-eval-report.md.claude/harness-eval-report-{リポジトリ名}.md
(対象リポジトリへの書き込みは行わない)# Harness Engineering 成熟度レポート
## 対象リポジトリ: {リポジトリ名}
## 診断日: {YYYY-MM-DD}
---
## サマリー
### 素点(均一配点)
| 柱 | スコア | 最大 | 達成率 |
|----|--------|------|--------|
| 1. Context Engineering | X/15 | 15 | XX% |
| 2. Architectural Constraints | X/21 | 21 | XX% |
| 3. Entropy Management | X/9 | 9 | XX% |
| 4. Agent Workflow | X/15 | 15 | XX% |
| B. エージェント対応インフラ | X/12 | 12 | XX% |
| **合計** | **X/72** | **72** | **XX%** |
### 重み付きスコア(レベル判定に使用)
| 柱 | 素点 | 重み | 重み付き | 最大 | 達成率 |
|----|------|------|---------|------|--------|
| 1. Context Engineering | X/15 | ×1.0 | X.X | 15.0 | XX% |
| 2. Architectural Constraints | X/21 | ×1.2 | X.X | 25.2 | XX% |
| 3. Entropy Management | X/9 | ×1.5 | X.X | 13.5 | XX% |
| 4. Agent Workflow | X/15 | ×1.0 | X.X | 15.0 | XX% |
| B. エージェント対応インフラ | X/12 | ×0.8 | X.X | 9.6 | XX% |
| **合計** | **X/72** | | **X.X** | **78.3** | **XX%** |
> **重みの根拠:** Architectural Constraints(×1.2)はエージェントの誤りを機械的に防ぐ基盤、Entropy Management(×1.5)はエージェント開発で最も軽視されがちだが長期的に最重要(OpenAI「技術的負債は高金利ローン」)、ボーナス(×0.8)は補助的要素のため低め。
### 成熟度レベル: Level X - {レベル名}(重み付き達成率 XX%)
---
## 詳細評価
### 柱1: Context Engineering(何を見せるか) — X/15
| # | 項目 | スコア | 現状 | 改善提案 |
|---|------|--------|------|----------|
| 1.1 | エージェント指示ファイル | {emoji} | {観察結果} | {改善提案 or "-"} |
| 1.2 | 指示の簡潔さ(目次型) | {emoji} | {観察結果} | {改善提案 or "-"} |
| 1.3 | 構造化ドキュメント | {emoji} | {観察結果} | {改善提案 or "-"} |
| 1.4 | 段階的情報開示 | {emoji} | {観察結果} | {改善提案 or "-"} |
| 1.5 | リポジトリ内完結 | {emoji} | {観察結果} | {改善提案 or "-"} |
### 柱2: Architectural Constraints(何を防ぐか) — X/21
| # | 項目 | スコア | 現状 | 改善提案 |
|---|------|--------|------|----------|
| 2.1 | リンター/フォーマッター | {emoji} | {観察結果} | {改善提案 or "-"} |
| 2.2 | カスタムリントルール | {emoji} | {観察結果} | {改善提案 or "-"} |
| 2.3 | 依存関係レイヤリング | {emoji} | {観察結果} | {改善提案 or "-"} |
| 2.4 | 構造テスト | {emoji} | {観察結果} | {改善提案 or "-"} |
| 2.5 | Pre-commit / CI ゲート | {emoji} | {観察結果} | {改善提案 or "-"} |
| 2.6 | テストスイート | {emoji} | {観察結果} | {改善提案 or "-"} |
| 2.7 | 型システム/スキーマ | {emoji} | {観察結果} | {改善提案 or "-"} |
### 柱3: Entropy Management(何を修正させるか) — X/9
PR CIでは検知できない、コードベース全体の経時的な劣化を検知・是正する仕組み。
| # | 項目 | スコア | 現状 | 改善提案 |
|---|------|--------|------|----------|
| 3.1 | ドキュメント整合性検証 | {emoji} | {観察結果} | {改善提案 or "-"} |
| 3.2 | 定期全体スキャン | {emoji} | {観察結果} | {改善提案 or "-"} |
| 3.3 | 能動的修正 | {emoji} | {観察結果} | {改善提案 or "-"} |
**スコア対象外のアドバイス:**
以下はPR CIや柱2で対応すべき項目だが、未整備の場合はここで改善提案として記載する:
- 品質基準の定義(MUST/FORBIDDENルール等) → 柱2のリンター設定根拠
- オブザーバビリティ(ログ/メトリクスへのアクセス) → ボーナスのエージェント支援ツール
- PR CIでの全体スキャン(unused code検出等) → 柱2のCIゲート強化
#### Entropy Management ギャップ分析
##### A. 導入済みだが活用できていない機能
既にリポジトリに導入されているツールの、未活用の機能。導入コストが低く即効性が高い。
| ツール | 未活用の機能 | 現状 | 活用方法 |
|--------|-----------|------|---------|
| {既に入っているツール名} | {そのツールの未活用機能} | {現状どう使われているか} | {どう活用すれば品質ドリフト検知/是正に使えるか} |
##### B. 導入を推奨するツール
このエコシステムで利用可能だが未導入のツール。
**推奨基準:** pub.dev/npm/PyPI等でのダウンロード数・メンテナンス状況・コミュニティでの採用実績をWebSearchで確認済みのもののみ記載。実績が不明確なツールは記載しない。
| ツール | 機能 | 採用実績 | 導入効果 |
|--------|------|---------|---------|
| {ツール名} | {Entropy Management上の役割} | {ダウンロード数/stars/採用企業等の客観的根拠} | {導入するとEntropy Managementのどの項目がどう改善されるか} |
### 柱4: Agent Workflow(どう作業させるか) — X/15
| # | 項目 | スコア | 現状 | 改善提案 |
|---|------|--------|------|----------|
| 4.1 | 構造化ワークフロー定義 | {emoji} | {観察結果} | {改善提案 or "-"} |
| 4.2 | セッション/状態管理 | {emoji} | {観察結果} | {改善提案 or "-"} |
| 4.3 | 自己検証メカニズム | {emoji} | {観察結果} | {改善提案 or "-"} |
| 4.4 | ガードレール | {emoji} | {観察結果} | {改善提案 or "-"} |
| 4.5 | エスカレーション/Human-in-the-loop | {emoji} | {観察結果} | {改善提案 or "-"} |
### ボーナス: エージェント対応インフラ — X/12
| # | 項目 | スコア | 現状 | 改善提案 |
|---|------|--------|------|----------|
| B.1 | 枯れた技術の選択 | {emoji} | {観察結果} | {改善提案 or "-"} |
| B.2 | エージェント専用ツール | {emoji} | {観察結果} | {改善提案 or "-"} |
| B.3 | エラーメッセージの改善 | {emoji} | {観察結果} | {改善提案 or "-"} |
| B.4 | ディレクトリ構造の規約 | {emoji} | {観察結果} | {改善提案 or "-"} |
---
## 次レベルへのロードマップ
現在の成熟度レベルから次のレベルに到達するために必要な項目を差分表示する。
**注意:** ここに記載する項目は全て、そのリポジトリの技術スタックで実現可能であることを確認済みのもののみ。実現手段が不明確な項目は記載しない。またコンテキスト増大等のトレードオフも考慮し、本当にエージェントの自律性向上に寄与するもののみ記載する。
### 現在: Level X → 次: Level Y(必要スコア: +Z点)
**未達成で最もインパクトの大きい項目:**
| # | 項目 | 現スコア | 目標スコア | ギャップ | 改善内容 |
|---|------|---------|-----------|---------|---------|
| {#} | {項目名} | {現在} | {目標} | +{差分} | {何をすればよいか} |
| ... | ... | ... | ... | ... | ... |
**最短ルート:** 上記のうち {N} 項目を改善すれば Level Y に到達可能。
---
## 優先改善アクション(Top 5)
| # | 項目 | 難易度 | 効果 | 概要 |
|---|------|--------|------|------|
| 1 | {項目名} | 低/中/高 | 大/中/小 | {概要} |
| 2 | ... | ... | ... | ... |
| 3 | ... | ... | ... | ... |
| 4 | ... | ... | ... | ... |
| 5 | ... | ... | ... | ... |
### アクション1: {項目名}
**現状の問題:**
{問題の説明}
**実装手順:**
1. {具体的な手順}
2. ...
(アクション2〜5も同様のフォーマット)
---
## 改善提案レビュー結果(3ループ)
別エージェントによる独立レビュー。各提案を「エージェントが自律的に逸脱なくコーディングを進められるか」「エージェントが自律的に品質を修正し続けられるか」の2軸で評価。技術スタック調査を実施した上で判定。
### ループ1: 初回レビュー
| # | 提案 | 判定 | レビューコメント |
|---|------|------|----------------|
| 1 | {提案名} | 採用/条件付き/却下/代替 | {レビューコメント} |
| ... | ... | ... | ... |
### ループ2: 修正版レビュー
ループ1のフィードバックを反映した修正版に対するレビュー。
| # | 提案 | 判定 | 変更点とコメント |
|---|------|------|----------------|
| ... | ... | ... | ... |
### ループ3: 最終レビュー
| # | 提案 | 最終判定 | コメント |
|---|------|---------|---------|
| ... | ... | ... | ... |
{最終版で残った条件・注意事項があればここに記載}
---
## エージェント自律性の総合評価
スコアの数字だけでは見えない、「このリポジトリでエージェントが実際に自律的・継続的に品質の良い成果物を出せるか」を、確認した事実に基づいて総合的に評価する。
### エージェントとして自分が作業する視点での評価
以下の観点で、診断で確認した事実を根拠に記述する。推測は入れない。
#### 1. 正しい実装判断ができるか
- エージェント指示ファイルやドキュメントから、アーキテクチャ判断・パターン選択・禁止事項を正しく読み取れるか
- 情報が不足している場合、どの判断で逸脱しそうか(具体的に指摘)
#### 2. 間違った時に気づけるか
- リンター・CI・テストで、エージェントの典型的なミス(レイヤー違反、型エラー、ビジネスロジックの誤り)がどの段階で検出されるか
- 検出できない(すり抜ける)ミスのパターンは何か
#### 3. 品質を維持し続けられるか
- 時間経過とともにコード品質が劣化するリスクはどこにあるか
- ドキュメントとコードの乖離、テストの形骸化、アーキテクチャの崩壊が起きた時に検知・修正する仕組みがあるか
#### 4. 行き詰まった時に適切に対処できるか
- エージェントが判断できない状況(仕様の曖昧さ、未知のエラー、複数の正解がある設計判断)に遭遇した時、エスカレーションの手段があるか
- 黙って間違った判断をしてしまうリスクはどこにあるか
### 逸脱リスクマップ
確認した事実から、エージェントが逸脱しやすいポイントを具体的にリストアップする。
| リスク | 根拠(確認した事実) | 影響度 | 現状の防御 |
|--------|---------------------|--------|-----------|
| {具体的な逸脱リスク} | {スキャンで確認した事実} | 高/中/低 | {既存の対策 or "なし"} |
| ... | ... | ... | ... |
### 総合所見
上記の4観点と逸脱リスクを踏まえ、このリポジトリでエージェントが自律的に作業する場合の現実的な期待値を3〜5文で述べる。「何ができて、何ができないか」を明確にする。
---
## 参考
- OpenAI「Harness engineering: leveraging Codex in an agent-first world」
https://openai.com/index/harness-engineering/
- Anthropic「Effective harnesses for long-running agents」
https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents
- Mitchell Hashimoto「My AI adoption journey」
https://mitchellh.com/writing/my-ai-adoption-journey
- Chachamaru127/claude-code-harness
https://github.com/Chachamaru127/claude-code-harness
- Martin Fowler「Harness Engineering」
https://martinfowler.com/articles/exploring-gen-ai/harness-engineering.html