agent-harness-construction

name	agent-harness-construction
description	Framework for designing quality agents with proper action space and contracts
version	0.1.0
level	3
triggers	["design an agent","agent quality framework","harness construction","agent architecture"]
context_files	["context/project.md","context/decisions.md"]
steps	[{"name":"Define Action Space","description":"Specify granularity and tool allowlist"},{"name":"Establish Observation Contract","description":"Define required fields in tool responses"},{"name":"Design Recovery Contract","description":"Specify error handling and retry logic"},{"name":"Budget Context","description":"Calculate context costs and set limits"},{"name":"Select Architecture Pattern","description":"Choose ReAct, function-calling, or Hybrid"},{"name":"Define Success Metrics","description":"Track completion rate, retries, pass@k, cost per task"}]

Agent Harness Construction Skill

Framework for designing quality agents. Defines contracts, budgets, and measurement before implementation.

What Claude Gets Wrong Without This Skill

Without systematic agent design, agents:

1. Have unclear tool boundaries (too permissive or too restrictive)
2. Return inconsistent response formats (breaks downstream parsing)
3. Fail silently on errors (no recovery strategy)
4. Consume unbounded context (budget overruns)
5. Lack measurable success criteria (can't tell if agent is improving)

Agent harness construction ensures agents are well-specified before deployment.

Four Quality Dimensions

1. Action Space

Defines: What tools can this agent use? At what granularity?

Granularity: Micro (single file/command, high-risk), Medium (edit/read loops, standard dev), Macro (Task/orchestration, complex workflows).

Tool Allowlist Pattern:

tools:
  - Read
  - Grep
  - Glob
disallowedTools:
  - Write
  - Edit
  - Bash

Rule: Start restrictive, expand only when justified. Removing permissions later breaks existing workflows.

2. Observation Contract

Defines: What fields must every tool response include?

Required Fields:

• status: SUCCESS | PARTIAL | FAILURE
• summary: One-line description of what happened
• next_actions: Array of suggested follow-ups
• artifacts: Paths to files created/modified

Why: Enables reliable parsing, orchestrator coordination, and chaining without re-planning. Anti-pattern: raw output with no structure.

3. Recovery Contract

Defines: How does agent handle errors?

Strategies: Retry with backoff (transient errors, max 3), escalate to human (ambiguous/security, max 2 auto-attempts), graceful degradation (optional features unavailable), circuit breaker (3 identical failures = stop).