harness-engineering-zh

Harness Engineering

Harness = the operating system provided for the AI Agent working in the project. The Model is the CPU, the Context window is the RAM, and the Harness is the operating system.

Core Principles

Start simple, and only add complexity when necessary. Every Harness component represents an assumption that the model cannot complete the task independently. Stress-test these assumptions — as model capabilities improve, these assumptions will fail. Build for "deletion".

When to Activate This Skill

Signal	Action
Empty project/New project	→ Perform full project setup (Section 1)
User feels frustrated with the Agent	→ Diagnose and fix missing Harness (Section 7)
Existing project needs improvement	→ Evaluate and improve incrementally
Clear Harness problem	→ Refer to the relevant section

Workflow

For a new project

1. Assess — What is the project? Tech stack? Team size? How will the Agent be used?
2. Setup — Create the foundational Harness files → Read references/01-project-setup.md
3. Context — Design the information architecture → Read references/02-context-engineering.md
4. Constraints — Add guardrails and Linters → Read references/03-constraints.md
5. Evaluate — Set up feedback loops → Read references/05-eval-feedback.md
6. If the project involves multiple Agents or long tasks → Read references/04-multi-agent.md, references/06-long-running.md
7. If the Agent will run unattended (scheduled tasks, CI loops) → Read references/08-loops.md; if you want the Agent to understand better over time across sessions → Read references/09-memory.md

For diagnosis (Agent performing poorly)

1. Immediately read references/07-diagnosis.md
2. Identify which layer of the Harness has the problem
3. Apply targeted fixes from the relevant reference documentation

For incremental improvement

Assess the current maturity of the Harness, identify the weakest layer, and improve one layer at a time.

Harness Layers (Quick Reference)

Layer	Contents	Reference Documentation
Project Setup	AGENTS.md, docs/, directory conventions	01-project-setup.md
Context Engineering	Information the Agent sees, 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, collaboration protocols, delegation patterns	04-multi-agent.md
Eval & Feedback	Testing, scoring, GC Agent, observability	05-eval-feedback.md
Long-Running Tasks	Progress tracking, Context resets, deliverables	06-long-running.md
Loops	Validators, stop conditions, guardrails, autonomous operation	08-loops.md
Memory	Cross-session memory, index-then-fetch, memory consolidation, forgetting	09-memory.md
Diagnosis	When an Agent fails — identify the root cause in the Harness, not the model	07-diagnosis.md

Self-Update Protocol

When you discover a new reusable Harness pattern in a project:

1. Identify which reference file it belongs to (or whether a new file is needed)
2. Add the pattern, including: whatproblemit solves,whento use it, and how toimplementit
3. Keep it concise — reject fluff, keep only the pattern