Harness Engineering
Harness = the operating system for AI agents working on your project. Model is CPU, context window is RAM, harness is OS.
Core Principle
Start simple, add complexity only when needed. Every harness component encodes an assumption about what the model can't do alone. Pressure-test these assumptions — they expire as models improve. Build for deletion.
When This Skill Activates
| Signal |
Action |
| Empty/new project |
→ Full project setup (Section 1) |
| User frustrated with agent |
→ Diagnose & fix harness gaps (Section 7) |
| Existing project needs improvement |
→ Assess & incrementally improve |
| Explicit harness question |
→ Reference relevant sections |
Workflow
For New Projects
- Assess — What's the project? Tech stack? Team size? How will agents be used?
- Setup — Create foundational harness files → read
references/01-project-setup.md
- Context — Design information architecture → read
references/02-context-engineering.md
- Constraints — Add guardrails and linters → read
references/03-constraints.md
- Evaluate — Set up feedback loops → read
references/05-eval-feedback.md
- If project involves multi-agent or long tasks → read
references/04-multi-agent.md, references/06-long-running.md
- If agents will run unattended (scheduled tasks, CI loops) → read
references/08-loops.md; if agents should learn across sessions → read references/09-memory.md
For Diagnosis (Agent Not Performing Well)
- Read
references/07-diagnosis.md immediately
- Identify which harness layer is failing
- Apply targeted fix from the relevant reference
For Incremental Improvement
Assess current harness maturity, identify weakest layer, improve one layer at a time.
Harness Layers (Quick Reference)
| Layer |
What |
Reference |
| Project Setup |
AGENTS.md, docs/, directory conventions |
01-project-setup.md |
| Context Engineering |
What info agents see, progressive disclosure, working state |
02-context-engineering.md |
| Constraints & Guardrails |
Linters, type systems, architecture enforcement, safe autonomy |
03-constraints.md |
| Multi-Agent Architecture |
Agent separation, coordination protocols, delegation patterns |
04-multi-agent.md |
| Eval & Feedback |
Testing, grading, GC agents, observability |
05-eval-feedback.md |
| Long-Running Tasks |
Progress tracking, context resets, handoff artifacts |
06-long-running.md |
| Loops |
Verifiers, stop conditions, guardrails, autonomous operation |
08-loops.md |
| Memory |
Cross-session memory, index-then-fetch, consolidation, forgetting |
09-memory.md |
| Diagnosis |
When agents fail — identify root cause in harness, not model |
07-diagnosis.md |
Self-Update Protocol
When you discover a new reusable harness pattern during a project:
- Identify which reference file it belongs to (or if it needs a new one)
- Add the pattern with: what it solves, when to use it, how to implement it
- Keep it concise — no fluff, just the pattern
1---2name: harness-engineering3description: Set up and improve harness engineering (AGENTS.md, docs/, lint rules, eval systems, project-level prompt engineering) for AI-agent-friendly codebases. Triggers on: new/empty project setup for AI agents, AGENTS.md or CLAUDE.md creation, harness engineering questions, making agents work better on a codebase. ALSO triggers when users are frustrated or complaining about agent quality — e.g. 'the agent keeps ignoring conventions', 'it never follows instructions', 'why does it keep doing X', 'the agent is broken' — because poor agent output almost always signals harness gaps, not model problems. Covers: context engineering, architectural constraints, multi-agent coordination, evaluation, long-running agent harness, agent loops (autonomous operation, verifiers, stop conditions), agent memory (cross-session memory, consolidation), and diagnosis of agent quality issues.4---56# Harness Engineering78Harness = the operating system for AI agents working on your project. Model is CPU, context window is RAM, harness is OS.910## Core Principle1112**Start simple, add complexity only when needed.** Every harness component encodes an assumption about what the model can't do alone. Pressure-test these assumptions — they expire as models improve. Build for deletion.1314## When This Skill Activates1516| Signal | Action |17|--------|--------|18| Empty/new project | → Full project setup (Section 1) |19| User frustrated with agent | → Diagnose & fix harness gaps (Section 7) |20| Existing project needs improvement | → Assess & incrementally improve |21| Explicit harness question | → Reference relevant sections |2223## Workflow2425### For New Projects26271. **Assess** — What's the project? Tech stack? Team size? How will agents be used?282. **Setup** — Create foundational harness files → read `references/01-project-setup.md`293. **Context** — Design information architecture → read `references/02-context-engineering.md`304. **Constraints** — Add guardrails and linters → read `references/03-constraints.md`315. **Evaluate** — Set up feedback loops → read `references/05-eval-feedback.md`326. If project involves multi-agent or long tasks → read `references/04-multi-agent.md`, `references/06-long-running.md`337. If agents will run unattended (scheduled tasks, CI loops) → read `references/08-loops.md`; if agents should learn across sessions → read `references/09-memory.md`3435### For Diagnosis (Agent Not Performing Well)36371. Read `references/07-diagnosis.md` immediately382. Identify which harness layer is failing393. Apply targeted fix from the relevant reference4041### For Incremental Improvement4243Assess current harness maturity, identify weakest layer, improve one layer at a time.4445## Harness Layers (Quick Reference)4647| Layer | What | Reference |48|-------|------|-----------|49| **Project Setup** | AGENTS.md, docs/, directory conventions | `01-project-setup.md` |50| **Context Engineering** | What info agents see, progressive disclosure, working state | `02-context-engineering.md` |51| **Constraints & Guardrails** | Linters, type systems, architecture enforcement, safe autonomy | `03-constraints.md` |52| **Multi-Agent Architecture** | Agent separation, coordination protocols, delegation patterns | `04-multi-agent.md` |53| **Eval & Feedback** | Testing, grading, GC agents, observability | `05-eval-feedback.md` |54| **Long-Running Tasks** | Progress tracking, context resets, handoff artifacts | `06-long-running.md` |55| **Loops** | Verifiers, stop conditions, guardrails, autonomous operation | `08-loops.md` |56| **Memory** | Cross-session memory, index-then-fetch, consolidation, forgetting | `09-memory.md` |57| **Diagnosis** | When agents fail — identify root cause in harness, not model | `07-diagnosis.md` |5859## Self-Update Protocol6061When you discover a new reusable harness pattern during a project:62631. Identify which reference file it belongs to (or if it needs a new one)642. Add the pattern with: **what** it solves, **when** to use it, **how** to implement it653. Keep it concise — no fluff, just the pattern
10xchengtu