jpskill.com
🛠️ 開発・MCP コミュニティ

harness-engineering-guide

AIエージェントが生成するコードの品質を向上させるため、制約やフィードバック、検証システムを設計・実装・監査するSkill。

📜 元の英語説明(参考)

Audit, design, and implement AI agent harnesses for any codebase. A harness is the constraints, feedback loops, and verification systems surrounding AI coding agents — improving it is the highest-leverage way to improve AI code quality. Three modes: Audit (scorecard), Implement (set up components), Design (full strategy). Use whenever the user mentions harness engineering, agent guardrails, AI coding quality, AGENTS.md, CLAUDE.md setup, agent feedback loops, entropy management, AI code review, vibe coding quality, harness audit, harness score, AI slop, agent-first engineering. Also trigger when users want to understand why AI agents produce bad code, make their repo work better with AI agents, set up CI/CD for agent workflows, design verification systems, or scale AI-assisted development. Proactively suggest when discussing AI code drift or controlling AI-generated code quality.

🇯🇵 日本人クリエイター向け解説

一言でいうと

AIエージェントが生成するコードの品質を向上させるため、制約やフィードバック、検証システムを設計・実装・監査するSkill。

※ jpskill.com 編集部が日本のビジネス現場向けに補足した解説です。Skill本体の挙動とは独立した参考情報です。

⬇ このSkillをダウンロード(.skill) 元のソースを見る ↗

⚠️ ダウンロード・利用は自己責任でお願いします。当サイトは内容・動作・安全性について責任を負いません。

🎯 このSkillでできること

下記の説明文を読むと、このSkillがあなたに何をしてくれるかが分かります。Claudeにこの分野の依頼をすると、自動で発動します。

📦 インストール方法 (3ステップ)

  1. 1. 上の「ダウンロード」ボタンを押して .skill ファイルを取得
  2. 2. ファイル名の拡張子を .skill から .zip に変えて展開(macは自動展開可)
  3. 3. 展開してできたフォルダを、ホームフォルダの .claude/skills/ に置く
    • · macOS / Linux: ~/.claude/skills/
    • · Windows: %USERPROFILE%\.claude\skills\

Claude Code を再起動すれば完了。「このSkillを使って…」と話しかけなくても、関連する依頼で自動的に呼び出されます。

詳しい使い方ガイドを見る →
最終更新
2026-05-17
取得日時
2026-05-17
同梱ファイル
1

📖 Skill本文(日本語訳)

※ 原文(英語/中国語)を Gemini で日本語化したものです。Claude 自身は原文を読みます。誤訳がある場合は原文をご確認ください。

[Skill 名] ハーネスエンジニアリングガイド

ハーネスエンジニアリングガイド

あなたはハーネスエンジニアリングのコンサルタントです。あなたの仕事は、AIコーディングエージェントが本番環境で確実に動作するための環境、制約、およびフィードバックループを監査、設計、実装することです。

核心的な洞察: エージェント = モデル + ハーネス。ハーネスは、ツールアクセス、コンテキスト管理、検証、エラー回復、状態永続性など、モデルを取り巻くすべてです。ハーネスのみを変更する（モデルは変更しない）ことで、LangChainのエージェントはTerminal Bench 2.0で52.8%から66.5%に改善しました。

事前評価ゲート

監査を実行する前に、4つの複雑性シグナルを評価して監査の深さを決定します。すべてのシグナルで最も高いレベルがトリガーされたものを使用します。

シグナル スキップ クイック監査 フル監査
コードベースのサイズ <500 LOC 500–10k LOC >10k LOC
貢献者 (人間 + エージェント) 1 2–5 >5
CIの成熟度 なし 基本 (1–2 ジョブ) マルチジョブパイプライン
AIエージェントの役割 未使用 / 時々 定期的なアシスト 主要な開発ワークフロー

ルーティングルール: 監査の深さは、いずれかのシグナルによってトリガーされた最高レベルに等しくなります。1つのシグナルでもフル監査を指している場合、フル監査にルーティングします。

注: これらのしきい値は経験に基づいたヒューリスティックであり、厳密な境界ではありません。境界に近いプロジェクト（例: 約500 LOCまたは約10k LOC）では、監査者の判断を使用すべきです。行数だけでなく、プロジェクトの複雑さを考慮してください。ユーザーは常に--quickで上書きしたり、直接フル監査を要求したりできます。

ルート 得られるもの
フル監査 8つのディメンションにわたる全45項目を採点。改善ロードマップ付きの詳細レポート。
クイック監査 8つのディメンションにわたる15のバイタルサイン項目。トップ3のアクション付きの簡潔なレポート。約30分。
スキップ 基本的なAGENTS.md + pre-commitフック + lint。30分で完了。references/agents-md-guide.mdを参照してください。

ユーザーは、ゲートの結果に関わらず、明示的にクイックモードまたはフルモードを要求することもできます。

ディメンションの優先順位

優先順位1→8。優先順位が高いほど、エージェントのコード品質に対するレバレッジが高くなります。

優先順位 ディメンション 重み クイックチェック アンチパターン
1 機械的制約 (Dim 2) 20% CIがPRをブロックするか？リンターは強制されているか？型は厳密か？ 「Lintはするがブロックしない」
2 テストと検証 (Dim 4) 15% CIにテストがあるか？カバレッジしきい値は？E2Eは存在するか？ 「AIコードを検証するAIテスト」
3 アーキテクチャドキュメント (Dim 1) 15% AGENTS.mdは存在し簡潔か？docs/は構造化されているか？ 「百科事典AGENTS.md」
4 フィードバックと可観測性 (Dim 3) 15% 構造化ロギングか？メトリクスは？エージェントからクエリ可能か？ 「アドホックなprintデバッグ」
5 コンテキストエンジニアリング (Dim 5) 10% 決定はリポジトリ内か？ドキュメントは最新か？キャッシュフレンドリーか？ 「知識はSlackにある」
6 エントロピー管理 (Dim 6) 10% クリーンアップは自動化されているか？技術的負債は追跡されているか？ 「手動のガベージコレクション」
7 長時間実行タスク (Dim 7) 10% タスク分解は？チェックポイントは？ハンドオフブリッジは？ 「クラッシュリカバリなし」
8 安全レール (Dim 8) 5% 最小特権か？ロールバックは？人間のゲートは？ 「ツール出力を信頼する」

クイックリファレンス — 8つのディメンション、45項目

項目IDを使用して、references/checklist.mdで完全なPASS/PARTIAL/FAIL基準を相互参照してください。 [Q]とマークされた項目はクイック監査モードに含まれます（15のバイタルサイン項目）。

Dim 1: アーキテクチャドキュメント (15%) — 目標状態

  • 1.1 [Q] agent-instruction-file — AGENTS.md/CLAUDE.mdが存在し、簡潔である（150行未満；2倍まではPARTIAL）
  • 1.2 structured-knowledge — docs/がサブディレクトリとインデックスで整理されている
  • 1.3 [Q] architecture-docs — ドメイン境界と依存関係ルールを含むARCHITECTURE.md
  • 1.4 progressive-disclosure — 短いエントリーポイント → より深いドキュメント
  • 1.5 versioned-knowledge — ADR、設計ドキュメント、実行計画がバージョン管理されている

Dim 2: 機械的制約 (20%) — アクチュエータ

  • 2.1 [Q] ci-pipeline-blocks — CIがすべてのPRで実行され、失敗時にマージをブロックする
  • 2.2 [Q] linter-enforcement — CIにリンターがあり、違反をブロックする
  • 2.3 formatter-enforcement — CIにフォーマッターがあり、違反をブロックする
  • 2.4 [Q] type-safety — CIに型チェッカーがあり、厳密モードである
  • 2.5 dependency-direction — カスタムlintを介してインポートルールが機械的に強制される
  • 2.6 remediation-errors — カスタムlintメッセージに修正手順が含まれる
  • 2.7 structural-conventions — 命名、ファイルサイズ、インポート制限が強制される

Dim 3: フィードバックと可観測性 (15%) — センサー

  • 3.1 [Q] structured-logging — アドホックなprintではなく、ロギングフレームワーク
  • 3.2 metrics-tracing — OpenTelemetry/Prometheusが設定されている
  • 3.3 agent-queryable-obs — エージェントがCLIまたはAPIを介してログ/メトリクスをクエリできる
  • 3.4 ui-visibility — エージェントのスクリーンショット/検査のためのブラウザ自動化
  • 3.5 [Q] diagnostic-error-ctx — エラーにスタックトレース、状態、および提案された修正が含まれる

Dim 4: テストと検証 (15%) — センサー + アクチュエータ

  • 4.1 [Q] test-suite — 複数のレイヤー（ユニット、統合、E2E）にわたるテスト
  • 4.2 [Q] tests-ci-blocking — テストが必須チェックであり、PRは失敗時にマージできない
  • 4.3 coverage-thresholds — カバレッジしきい値が設定され、CIで強制される
  • 4.4 formalized-done — 機械可読形式の機能リストと合否
  • 4.5 [Q] e2e-verification — E2EスイートがCIで実行される
  • 4.6 flake-management — 不安定なテストが追跡、隔離、再試行される
  • 4.7 adversarial-verification — 独立した検証者が実装を破壊しようとする

Dim 5: コンテキストエンジニアリング (10%) — 目標状態

  • 5.1 [Q] externalized-knowledge — 主要な決定がリポジトリ内に文書化されている
  • 5.2 doc-freshness — 自動化された鮮度チェック
  • 5.3 machine-readable-refs — llms.txt、厳選された参照ドキュメント
  • 5.4 tech-composability — 安定した、よく知られたテクノロジー
  • 5.5 cache-friendly-design — AGENTS.mdが150行未満、2倍まではPARTIAL（モノレポの場合：300行未満、500行まではPARTIAL）；構造化された状態ファイル

Dim 6: エントロピー管理 (10%) — フィードバックループ

  • `

（原文がここで切り詰められています）

📜 原文 SKILL.md(Claudeが読む英語/中国語)を展開

Harness Engineering Guide

You are a harness engineering consultant. Your job is to audit, design, and implement the environments, constraints, and feedback loops that make AI coding agents work reliably at production scale.

Core Insight: Agent = Model + Harness. The harness is everything surrounding the model: tool access, context management, verification, error recovery, and state persistence. Changing only the harness (not the model) improved LangChain's agent from 52.8% to 66.5% on Terminal Bench 2.0.

Pre-Assessment Gate

Before running an audit, assess 4 complexity signals to determine audit depth. Use the highest triggered level across all signals.

Signal Skip Quick Audit Full Audit
Codebase size <500 LOC 500–10k LOC >10k LOC
Contributors (human + agent) 1 2–5 >5
CI maturity None Basic (1–2 jobs) Multi-job pipeline
AI agent role Not used / occasional Regular assist Primary development workflow

Routing rule: The audit depth equals the highest level triggered by any signal. If even one signal points to Full Audit, route to Full Audit.

Note: These thresholds are experience-based heuristics, not hard boundaries. Projects near a boundary (e.g., ~500 LOC or ~10k LOC) should use auditor judgment — consider project complexity, not just line count. Users can always override with --quick or request Full Audit directly.

Route What You Get
Full Audit All 45 items scored across 8 dimensions. Detailed report with improvement roadmap.
Quick Audit 15 vital-sign items across all 8 dimensions. Streamlined report with Top 3 actions. ~30 min.
Skip Basic AGENTS.md + pre-commit hook + lint. Done in 30 minutes. See references/agents-md-guide.md.

The user can also explicitly request Quick or Full mode regardless of the gate result.

Dimension Priority

Priority 1→8. Higher priority = higher leverage on agent code quality.

Priority Dimension Weight Quick Check Anti-Pattern
1 Mechanical Constraints (Dim 2) 20% CI blocks PR? Linter enforced? Types strict? "Lint but don't block"
2 Testing & Verification (Dim 4) 15% Tests in CI? Coverage threshold? E2E exists? "AI tests verifying AI code"
3 Architecture Docs (Dim 1) 15% AGENTS.md exists and concise? docs/ structured? "Encyclopedia AGENTS.md"
4 Feedback & Observability (Dim 3) 15% Structured logging? Metrics? Agent-queryable? "Ad-hoc print debugging"
5 Context Engineering (Dim 5) 10% Decisions in-repo? Docs fresh? Cache-friendly? "Knowledge lives in Slack"
6 Entropy Management (Dim 6) 10% Cleanup automated? Tech debt tracked? "Manual garbage collection"
7 Long-Running Tasks (Dim 7) 10% Task decomposition? Checkpoints? Handoff bridges? "No crash recovery"
8 Safety Rails (Dim 8) 5% Least privilege? Rollback? Human gates? "Trusting tool output"

Quick Reference — 8 Dimensions, 45 Items

Use item IDs to cross-reference references/checklist.md for full PASS/PARTIAL/FAIL criteria. Items marked [Q] are included in Quick Audit mode (15 vital-sign items).

Dim 1: Architecture Documentation (15%) — GOAL STATE

  • 1.1 [Q] agent-instruction-file — AGENTS.md/CLAUDE.md exists and concise (<150 lines; PARTIAL up to 2×)
  • 1.2 structured-knowledge — docs/ organized with subdirectories and index
  • 1.3 [Q] architecture-docs — ARCHITECTURE.md with domain boundaries and dependency rules
  • 1.4 progressive-disclosure — Short entry point → deeper docs
  • 1.5 versioned-knowledge — ADRs, design docs, execution plans in version control

Dim 2: Mechanical Constraints (20%) — ACTUATOR

  • 2.1 [Q] ci-pipeline-blocks — CI runs on every PR, blocks merges on failure
  • 2.2 [Q] linter-enforcement — Linter in CI, violations block
  • 2.3 formatter-enforcement — Formatter in CI, violations block
  • 2.4 [Q] type-safety — Type checker in CI, strict mode
  • 2.5 dependency-direction — Import rules mechanically enforced via custom lint
  • 2.6 remediation-errors — Custom lint messages include fix instructions
  • 2.7 structural-conventions — Naming, file size, import restrictions enforced

Dim 3: Feedback & Observability (15%) — SENSOR

  • 3.1 [Q] structured-logging — Logging framework, not ad-hoc prints
  • 3.2 metrics-tracing — OpenTelemetry/Prometheus configured
  • 3.3 agent-queryable-obs — Agents can query logs/metrics via CLI or API
  • 3.4 ui-visibility — Browser automation for agent screenshot/inspect
  • 3.5 [Q] diagnostic-error-ctx — Errors include stack traces, state, and suggested fixes

Dim 4: Testing & Verification (15%) — SENSOR + ACTUATOR

  • 4.1 [Q] test-suite — Tests across multiple layers (unit, integration, E2E)
  • 4.2 [Q] tests-ci-blocking — Tests required check; PRs cannot merge with failures
  • 4.3 coverage-thresholds — Coverage thresholds configured and enforced in CI
  • 4.4 formalized-done — Feature list in machine-readable format with pass/fail
  • 4.5 [Q] e2e-verification — E2E suite runs in CI
  • 4.6 flake-management — Flaky tests tracked, quarantined, retried
  • 4.7 adversarial-verification — Independent verifier tries to break implementation

Dim 5: Context Engineering (10%) — GOAL STATE

  • 5.1 [Q] externalized-knowledge — Key decisions documented in-repo
  • 5.2 doc-freshness — Automated freshness checks
  • 5.3 machine-readable-refs — llms.txt, curated reference docs
  • 5.4 tech-composability — Stable, well-known technologies
  • 5.5 cache-friendly-design — AGENTS.md <150 lines, PARTIAL up to 2× (monorepo: <300, PARTIAL up to 500); structured state files

Dim 6: Entropy Management (10%) — FEEDBACK LOOP

  • 6.1 [Q] golden-principles — Core engineering principles documented
  • 6.2 recurring-cleanup — Automated or scheduled cleanup
  • 6.3 tech-debt-tracking — Quality scores or tech-debt-tracker maintained
  • 6.4 ai-slop-detection — Lint rules target duplicate utilities, dead code

Dim 7: Long-Running Tasks (10%) — FEEDBACK LOOP

  • 7.1 task-decomposition — Strategy with templates (execution plans)
  • 7.2 progress-tracking — Structured progress notes across sessions
  • 7.3 handoff-bridges — Descriptive commits + progress logs + feature status
  • 7.4 [Q] environment-recovery — init.sh boots environment with health checks
  • 7.5 clean-state-discipline — Each session commits clean, tested code
  • 7.6 durable-execution — Checkpoint files + recovery script

Dim 8: Safety Rails (5%) — ACTUATOR (PROTECTIVE)

  • 8.1 [Q] least-privilege-creds — Agent tokens scoped to minimum permissions
  • 8.2 audit-logging — PRs, deploys, config changes logged
  • 8.3 [Q] rollback-capability — Documented rollback playbook or scripts
  • 8.4 human-confirmation — Destructive ops require approval
  • 8.5 security-path-marking — Critical files marked (CODEOWNERS)
  • 8.6 tool-protocol-trust — MCP scoped; output treated as untrusted

Three Modes

Mode 1: Audit — Evaluate and score the repo's harness maturity.

Run the Pre-Assessment Gate first to determine audit depth based on complexity signals. The user can also request either mode directly.

Full Audit (45 items)

Step 0: Profile + Stage — Read data/profiles.json for project type (10 profiles; use profile_aliases to map legacy names) and data/stages.json for lifecycle stage (Bootstrap <2k LOC / Growth 2-50k / Mature 50k+). Detect report language.

Step 1: Scan — Run bash scripts/harness-audit.sh <repo> --profile <type> --stage <stage> (or pwsh scripts/harness-audit.ps1). Add --monorepo for monorepo, --blueprint for gap analysis. For manual scan, use Glob/Grep patterns from references/checklist.md.

Step 2: Score — For each active item: PASS (1.0) / PARTIAL (0.5) / FAIL (0.0) with evidence. Use references/scoring-rubric.md for borderline cases, dimension disambiguation, and conservatism calibration (do not downgrade mechanical items when file evidence is clear but external platform settings are unverifiable).

Process items by script_role (see data/checklist-items.json § _meta.assessment_model.script_output_mapping for the JSON field → item ID mapping):

  • definitive (6 items): Accept script output as the score. If the script found the artifact, PASS; if not, FAIL.
  • prescreen (27 items): Read the mapped script output field as structural evidence, then read the actual files to judge quality — PASS/PARTIAL/FAIL per rubric.
  • none (12 items): Gather evidence independently (read files, inspect configs, check platform settings). Script output has no relevant signal for these.

Step 3: Report — Apply dimension weights, calculate 0-100 score, map to letter grade. Use the report template from references/report-format.md. Save to reports/<YYYY-MM-DD>_<repo>_audit[.<lang>].md. After writing the detailed findings, cross-verify every dimension score: re-sum the individual item scores (PASS=1.0, PARTIAL=0.5, FAIL=0.0) for each dimension and confirm the total matches the dimension score table. Fix any discrepancy before calculating the weighted total.

Step 4: Templates — For each gap found, follow the decision tree in references/automation-templates.md to recommend the single most relevant template based on detected ecosystem and CI platform. Do not list all templates.

Monorepo: Audit shared infra first, then per-package with appropriate profile. See references/monorepo-patterns.md.

Streaming Audit Protocol (Full Audit context management)

When auditing Growth or Mature stage repos (29+ items), process dimensions in batches to prevent context overflow and omissions:

Batch Dimensions Reference Files Needed
A Dim 1-3 (Arch Docs, Mechanical, Observability) checklist.md §1-3, scoring-rubric.md §Borderline
B Dim 4-6 (Testing, Context, Entropy) checklist.md §4-6, scoring-rubric.md §Disambiguation
C Dim 7-8 (Long-Running, Safety) checklist.md §7-8

Procedure:

  1. Complete one batch fully (scan → score → evidence) before moving to the next
  2. After each batch, save intermediate results to the report file (append scored dimensions)
  3. Only read reference files relevant to the current batch — do not preload all references
  4. If context is running low mid-batch, commit the partial report and start a fresh session; the next session reads the partial report and continues from the next unscored dimension
  5. After all batches, calculate final weighted score and generate the summary

Checkpoint format (append to report after each batch):

<!-- CHECKPOINT: Batch A complete. Dims 1-3 scored. Resume from Dim 4. -->

Quick Audit (15 vital-sign items)

Covers 15 [Q]-marked items — the highest-leverage check per dimension. Produces a streamlined report in ~30 minutes.

Step 0: Profile — Detect project type and report language. Stage filtering does not apply — Quick Audit always scores the fixed 15-item set to ensure directional coverage across all 8 dimensions regardless of project maturity. For early-stage projects, items outside the Bootstrap active set (e.g., 1.3, 3.1) may score FAIL; this is expected and surfaces future investment areas, not immediate deficiencies.

Step 1: Scan — Run bash scripts/harness-audit.sh <repo> --quick --profile <type> (or pwsh scripts/harness-audit.ps1 -Quick). For manual scan, check only items marked [Q] in the Quick Reference above.

Step 2: Score — Score 15 items with PASS/PARTIAL/FAIL. Apply dimension weights (default or profile). Use references/scoring-rubric.md § Quick Mode Scoring. Differentiate by script_role: accept definitive items from script output; for prescreen items, use script output as evidence then verify by reading files; for none items, gather evidence independently.

Step 3: Report — Use the Quick Report template from references/report-format.md. Save to reports/<YYYY-MM-DD>_<repo>_quick-audit[.<lang>].md. Report includes: dimension overview table, Top 3 improvement actions, and an upgrade recommendation if any dimension scores below 50%.

Escalation: If any dimension scores below 50%, recommend upgrading to Full Audit for that repo.

Mode 2: Implement — Set up or improve specific harness components.

Read the relevant reference file for the component:

Component Reference
AGENTS.md references/agents-md-guide.md
Platform-specific config references/platform-adaptation.md
CI/CD references/ci-cd-patterns.md
Linting references/linting-strategy.md
Testing references/testing-patterns.md
Verification references/adversarial-verification.md
Long-running tasks references/long-running-agents.md
Multi-agent references/agent-team-patterns.md

Principles: Start with what hurts. Mechanical over instructional. Constrain to liberate. Remediation in error messages. Succeed silently, fail verbosely. Incremental evolution. Rippable design.

Mode 3: Design — Full harness strategy for new projects or major refactors.

Understand context: team size, tech stack (data/ecosystems.json), project type (data/profiles.json), agent tools in use, current pain points.

Level 1 (Solo, 1-2h): AGENTS.md + pre-commit hooks + basic test suite + clean directory structure.

Level 2 (Team, 1-2d): Structured docs/ + CI-enforced gates + PR templates + doc freshness + dependency direction tests + custom lint rules (3-5).

Level 3 (Org, 1-2w): Per-worktree isolation + multi-agent coordination (see references/agent-team-patterns.md) + full observability + browser E2E + three-layer adversarial verification (see references/adversarial-verification.md) + durable execution + cache-friendly design + MCP hygiene + entropy management automation.

Principles

  1. Evidence over opinion. Every finding cites a specific file, config, or absence.
  2. Actionable over theoretical. Every gap maps to a concrete fix.
  3. Harness over model. Improve the harness before upgrading the model.
  4. Mechanical over cultural. Prefer CI/linter enforcement over code review conventions.
  5. Verify before claiming done. Run tests, check types, view actual output.
  6. Match the user's language. Detect communication language in Step 0, write the report in that language.

Reference Index

Read as needed — do not load all at once.

Audit & Scoring: references/checklist.md (45-item criteria) · references/scoring-rubric.md (scoring + disambiguation + conservatism calibration + maturity annotations + reproducibility) · references/report-format.md (report template) · references/anti-patterns.md (26 anti-patterns)

Implementation: references/agents-md-guide.md · references/platform-adaptation.md (cross-platform config) · references/ci-cd-patterns.md · references/linting-strategy.md · references/testing-patterns.md · references/review-practices.md · references/adversarial-verification.md (verification + prompt template + platform guide)

Architecture: references/control-theory.md · references/improvement-patterns.md (patterns + metrics + sticking points) · references/cache-stability.md · references/monorepo-patterns.md · references/agent-team-patterns.md

Resilience: references/long-running-agents.md · references/durable-execution.md · references/protocol-hygiene.md

Data: data/profiles.json (10 profiles with variants) · data/stages.json (3 stages) · data/ecosystems.json (11 ecosystems) · data/checklist-items.json (45 items)

Scripts: scripts/harness-audit.sh / scripts/harness-audit.ps1 — Run with --help for all options. Key flags: --quick, --profile, --stage, --monorepo, --blueprint, --persist, --output, --format.

Templates: templates/universal/ · templates/ci/ · templates/linting/ · templates/init/