/agentic-harness-patterns

name: agentic-harness-patterns
description: >-
  Harness patterns for coding agents — memory, permissions, context
  engineering, delegation, skills, hooks, bootstrap.
when_to_use: >-
  Triggers on: harness engineering, tool safety, permission pipeline,
  agent memory, memory persistence, delegation pattern, context budget,
  bootstrap sequence, skill runtime, hook lifecycle, tool orchestration,
  agent harness, context engineering.
license: MIT

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](#1-memory) | | Package reusable workflows and expertise | [Skills](#2-skills) | | Let the agent use tools powerfully but not dangerously | [Tools and Safety](#3-tools-and-safety) | | Give the agent the right context at the right cost | [Context Engineering](#4-context-engineering) | | Split work across multiple agents without losing control | [Multi-agent Coordination](#5-multi-agent-coordination) | | Extend behavior with hooks, background tasks, or startup logic | [Lifecycle and Extensibility](#6-lifecycle-and-extensibility) |

**Before you start building:** Read the [Gotchas](#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.

**Start here:** Define your memory layers (instruction, auto, extraction). Implement the two-step save invariant (topic file, then index). Add background extraction only after the core write path is stable.

> **In Claude Code:** Use `/remember` to audit and promote auto-memory entries across layers.

**Tradeoffs:**

• More memory layers = richer recall but higher maintenance burden. Without periodic pruning, index caps cause silent data loss.
• Session extraction adds latency at session end but dramatically improves cross-session learning.

**Go deeper:** [references/memory-persistence-pattern.md](references/memory-persistence-pattern.md)

---

2. Skills

**User problem:** "I want my agent to reuse workflows and domain knowledge without re-explaining them every time."

**Golden rule:** Skills are lazy-loaded instruction sets, not eagerly injected prompts. Discovery must be cheap (metadata only); the full body loads only on activation.

**When to use:** Any agent that needs reusable, composable workflows activating on matching user intent.

**How it works:**

• **Discovery** is budget-constrained: the agent sees a compact listing of all available skills (name, description, and when-to-use hint concatenated per entry), each hard-capped at a fixed character limit, with the total capped at roughly 1% of the context window. Front-load your trigger language — tails get truncated.
• **Loading** is lazy: only metadata enters the always-on context. The full skill body loads only when the skill activates, keeping idle token cost near zero.
• **Execution** can be inline (shared context) or isolated (forked sub-agent with its own token budget). Isolation prevents a heavy skill from exhausting the parent's context.
• **Sources** can be bundled, user-installed, or dynamically loaded from plugins. Deduplication by canonical path prevents the same skill from appearing twice across overlapping source directories.

**Start here:** Choose a metadata format (frontmatter recommended). Implement two-phase discovery: cheap listing at startup, lazy body loading on invocation. Set a per-entry character cap before your catalog grows.

**Tradeoffs:**

• Lazy loading saves tokens but adds one round-trip of latency on first activation.
• Forked execution provides isolation but loses access to the parent's accumulated context.

**Go deeper:** [references/skill-runtime-pattern.md](references/skill-runtime-pattern.md)

---

3. Tools and Safety

**User problem:** "I want my agent to use tools powerfully, bu