PART 5 · Harness & Self-Improvement
Three Design Patterns of Harness
A well-designed Harness speaks a clear pattern language — it is never just a pile of scripts stitched together. Three core patterns account for 90% of the architectural decisions in today's most capable Agent systems.
Pattern 1
1
Workflow Automation
Workflow Automation
Core idea: An Agent is a goal-directed loop — it should never be treated as a one-shot script.
- Plan → Execute → Observe/Test → Improve → Execute again: Every generation round is the starting point for the next optimization round.
- Analyze its own trajectory: A high-quality Agent looks back at what it did in previous rounds, where it failed, and why — then adjusts its strategy to avoid repeating the same Prompt.
- Emphasis on runtime iteration: Improvement happens during Agent execution, not by relying on static templates written by humans in advance. The Agent learns, adapts, and optimizes within each run.
- Failure is a signal, not a termination: Test failures, command errors, and unexpected outputs are all triggers for the Agent to self-correct.
Agent workflow loop: plan → execute → observe → improve → execute again (source: OpenAI Codex Agent Loop)
Design Insight
Don't design an Agent as a one-shot answerer. Give it the ability to audit its own output: automatically analyze why a test failed, auto-fix linter errors, and adjust strategy based on user feedback. This is the essence of workflow automation: building the feedback loop into the system itself.
Pattern 2
2
File System as Persistent Memory
File System as Persistent Memory
Core problem: In long-running Agents, artifacts will quickly overflow the context window.
- Diverse artifact types: Experiment logs, code diffs, paper summaries, error trace records, and full past execution trajectories — all valuable state that cannot fit in context.
- The right Harness approach: Store persistent state in the file system and teach the Agent to read and write on demand. Never try to cram the entire work history into the Prompt.
- File I/O is a core LLM skill: Reading and writing the file system requires no complex external toolchain — it benefits from improvements in the core model. Smarter models manage files more efficiently.
- Structured storage: A well-designed Agent maintains its own scratchpad, todo lists, and experiment records — managing its workspace like a human programmer.
Context vs. File System: What Goes Where?
In context: The current task instructions, immediate tool call results, and the last 2–3 conversation turns — information that needs immediate reference.
In the file system: Historical experiment results, accumulated error logs, summaries of completed subtasks, and long-term strategies and rules — information that needs persistent storage but doesn't need to be in view at all times.
Key principle: Context is working memory; the file system is long-term memory. A good Harness, like the human brain, intelligently moves information between the two.
In the file system: Historical experiment results, accumulated error logs, summaries of completed subtasks, and long-term strategies and rules — information that needs persistent storage but doesn't need to be in view at all times.
Key principle: Context is working memory; the file system is long-term memory. A good Harness, like the human brain, intelligently moves information between the two.
Pattern 3
3
Sub-agent and Backend Jobs
Sub-Agent & Background Jobs
Core idea: When one Agent is not enough, spawn multiple sub-agents to execute in parallel while monitoring long-running background jobs.
- Parent Agent as process manager: Launch subtasks, check logs and progress, cancel failed branches, merge successful results. This is an OS-level mental model.
- Parallelism must be explicit and inspectable: No "fire and forget." The parent Agent must be able to check the status, output, and errors of each sub-agent.
- Persist sub-agent outputs: Each sub-agent's result is stored as a file, log, or status record (not just returned into the parent's context), so execution can be resumed even after interruption.
- Fault tolerance and recovery: Background tasks may time out, crash, or produce low-quality results. The Harness needs retry strategies and graceful degradation mechanisms.
Key Design Trade-off
The core trade-off of the sub-agent pattern: parallelism brings speed, but also complexity. Successful implementations (e.g., Cursor's Task system, Claude Code's subprocess model) all follow the same principle: let each sub-agent work in an isolated sandbox, output to well-defined file paths, and have the parent Agent coordinate by polling file state — no shared memory. This greatly simplifies concurrency control.
Case Study · Coding Agent Harness
Core Tool Interfaces of Leading Coding Agents
Claude Code, Codex, OpenCode, and Cursor — today's most capable coding Agents — all build their Harness around a similar tool set. The table below compares their core interfaces grouped by function:
| Tool Group | Core Capability | Typical Tools |
|---|---|---|
| File System | Read, write, search, and edit files; manage workspace state | Read, Write, Edit, Glob, Grep, StrReplace |
| Shell Execution | Run terminal commands, execute tests, install dependencies | Shell, BashExec, RunCommand |
| I/O | Interact with the user, confirm actions, display results | Ask, UserConfirm, ShowResult |
| External Context | Fetch external information, documents, and API responses | WebFetch, ReadURL, DocSearch |
| Web Search | Search the internet for up-to-date information | WebSearch, BingSearch |
| Artifacts | Generate, manage, and version artifacts | CreateFile, SaveArtifact, VersionControl |
| Backend Processes | Run long-running tasks in background, monitor process status | BackgroundShell, AwaitProcess, Monitor |
| Agent Delegation | Spawn sub-agents, assign parallel tasks, merge results | Task, Subagent, Fork, ParallelRun |
The Harness loop of a coding Agent: from user intent to code delivery, the full orchestration of tool interfaces (source: Lilian Weng, 2026)
Interactive: How the Three Architectures Run
Ready
Plan
Execute
Observe
Improve
↩ Loop
Information loss starts at round 4
All tool returns and history are crammed into context — the window fills up quickly. The Agent starts forgetting early information and output quality degrades sharply.
How the Three Patterns Work Together
Three patterns stack as layers — pick all three, not one
Workflow automation provides the backbone of execution: loop structure and feedback mechanism.
File system memory provides the hard drive for the loop: results of each iteration are never lost, even if context is flushed.
Sub-agent parallelism provides multi-core for the loop: when tasks are decomposable, parallel acceleration replaces serial waiting.
Combined, an Agent gains the capability of iterative optimization × long-term memory × parallel scaling. This is precisely the common architecture of today's most capable coding Agents.
File system memory provides the hard drive for the loop: results of each iteration are never lost, even if context is flushed.
Sub-agent parallelism provides multi-core for the loop: when tasks are decomposable, parallel acceleration replaces serial waiting.
Combined, an Agent gains the capability of iterative optimization × long-term memory × parallel scaling. This is precisely the common architecture of today's most capable coding Agents.
Key Insight: Harness design is not a random assembly of tools. It follows three structural patterns: a goal-directed automation loop (enabling the Agent to self-correct), the file system as long-term memory (breaking through context window limits), and sub-agents for parallel scaling (turning serial bottlenecks into multi-threaded execution). Mastering these three patterns means mastering the architectural language for building production-grade Agent systems.