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

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.

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

---

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

---

3. Tools and Safety

User problem: "I want my agent to use tools powerfully, but not dangerously."

Golden rule: Default to fail-closed. Tools are serial and gated unless explicitly marked safe for concurrency and approved by the permission pipeline.

When to use: Any agent runtime that needs tool registration, concurrency control, or permission gating.

How it works:

• Registration uses fail-closed defaults: tools are non-concurrent and non-read-only unless the developer opts in. This prevents accidental parallel execution of state-mutating operations.
• Concurrency classification is per-call, not per-tool: the same tool can be safe for some inputs and unsafe for others. The runtime partitions a batch of tool calls into consecutive groups — safe calls run in parallel, any unsafe call starts a serial segment.
• Permission pipeline evaluates rules from multiple sources in strict priority order spanning settings files (user, project, local, flag, and policy), CLI arguments, command-scoped rules, and session grants. The evaluator is stateful — it tracks denials, transforms modes, and updates state as a side effect.
• Handler dispatch varies by execution environment: interactive (human prompt), automated (coordinator), or async (swarm agent). The same permission rules feed different approval surfaces.

Start here: Route every tool call through one permission gate. Default to fail-closed (deny/ask). Add bypass-immune rules for protected paths before shipping any auto-approve mode.

In Claude Code: Use /update-config to configure permission rules and hooks.

Tradeoffs:

• Fail-closed defaults mean new tools are safe out of the box, but developers must actively opt into concurrency — forgetting to flag a read-only tool as concurrent-safe silently degrades throughput.
• Multi-source permission layering is powerful but hard to debug when rules from different sources conflict.

Go deeper: references/tool-registry-pattern.md | references/permission-gate-pattern.md

---

4. Context Engineering

User problem: "My agent either sees too much, too little, or the wrong thing."

Golden rule: Treat context as a budget, not a dump. Every token in the window should earn its place through one of four operations: select, write, compress, or isolate.

When to use: Any agent whose performance degrades in long sessions, whose delegated work pollutes the parent context, or whose startup is slow due to eager context loading.

How it works:

• Select — Load context just-in-time, not all-at-once. Use progressive disclosure with three tiers: metadata (always present, cheap), instructions (loaded on activation), resources (loaded on demand). Memoize expensive context builders and invalidate only at known mutation points — not reactively.
• Write — Context is not read-only. The agent writes back to persistent storage: auto-memory entries, background extraction outputs, task state, permission rules. The write-back loop is what turns a stateless agent into a learning system.
• Compress — Long sessions exhaust the window. Reactive compaction summarizes older turns mid-session, preserving recent context while reclaiming budget. Mark snapshot data as snapshots so the model knows to re-fetch for current state.
• Isolate — Delegated work must not pollute the parent's context. Coordinator workers start with zero context inheritance (only the explicit prompt). Fork children inherit full context but are single-level (no recursive forks). Filesystem-level isolation (worktrees) gives an agent its own working copy.

Start here: Audit your current context cost per turn. Apply hard caps to every variable-length block. Add truncation recovery pointers (tell the model which tool to call for full output) before enabling any compression.

Tradeoffs:

• Aggressive caching reduces latency but creates staleness risk — every mutation point must explicitly clear the cache, or the model operates on stale data for the remainder of the session.
• Progressive disclosure saves tokens but means the model can't reason about a skill's full capabilities until it's activated.

Go deeper: references/context-engineering-pattern.md (index) | select | compress | isolate

---