agentic-harness-patterns

Agentic Harness Patterns

Production AI coding agents are not just an LLM calling tools in a loop. The harness — memory, skills, safety, context control, delegation, and extensibility — is what separates a demo from a production system.

For: Engineers building or extending coding-agent runtimes, custom agents, or advanced multi-agent workflows. Not for: Prompt engineering, model selection, generic software architecture, or LLM API basics.

All principles are distilled from production runtime decisions. Claude Code is used as grounding evidence, not as the only possible implementation.

Choose Your Problem

If you want to...	Read
Make the agent remember and improve over time	Memory
Package reusable workflows and expertise	Skills
Let the agent use tools powerfully but not dangerously	Tools and Safety
Give the agent the right context at the right cost	Context Engineering
Split work across multiple agents without losing control	Multi-agent Coordination
Extend behavior with hooks, background tasks, or startup logic	Lifecycle and Extensibility

Before you start building: Read the Gotchas — these are the non-obvious failure modes that cost the most time.

---

1. Memory

User problem: "My agent forgets corrections and project rules between sessions."

Golden rule: Separate what the agent knows (instruction memory) from what the agent learns (auto-memory) from what the agent extracts (session memory). Each layer has different persistence, trust, and review needs.

When to use: Any agent that operates across multiple sessions or needs to accumulate project-specific knowledge over time.

How it works:

• Instruction memory is curated, hierarchical configuration injected into system context in priority order (org-wide → user → project → local; local wins). This is where project conventions, coding standards, and behavioral rules live. It is human-authored and stable.
• Auto-memory is agent-written persistent knowledge with a type taxonomy (user / feedback / project / reference) and a capped index. Saving is two-step: write a topic file, then update the index. The cap prevents unbounded growth — without cleanup, recent entries silently disappear.
• Session extraction runs as a background agent at session end. It directly writes to auto-memory — topic file then index — following the same two-step save invariant. A mutual-exclusion guard ensures that if the main agent already wrote memory during the turn, the extractor skips entirely. This is the autonomous learning loop.
• Review and promotion audits across all memory layers and proposes cross-layer moves (auto-memory → project conventions, personal instructions, or team memory). It never applies changes autonomously — proposals require explicit user approval.