# Harness Engineering Guide

> >

- **Type:** Skill
- **Install:** `agentstack add skill-odradekai-harness-engineering-guide-harness-engineering-guide`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [OdradekAI](https://agentstack.voostack.com/s/odradekai)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [OdradekAI](https://github.com/OdradekAI)
- **Source:** https://github.com/OdradekAI/harness-engineering-guide/tree/main/harness-engineering-guide

## Install

```sh
agentstack add skill-odradekai-harness-engineering-guide-harness-engineering-guide
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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** | 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 ( --profile  --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/__audit[.].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):
```

```

#### 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  --quick --profile ` (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/__quick-audit[.].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/`

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [OdradekAI](https://github.com/OdradekAI)
- **Source:** [OdradekAI/harness-engineering-guide](https://github.com/OdradekAI/harness-engineering-guide)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-odradekai-harness-engineering-guide-harness-engineering-guide
- Seller: https://agentstack.voostack.com/s/odradekai
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.