A production-grade AI coding assistant is not just a "large model + tool-calling loop." The loop itself is simple.Harness — memory, skills, safety, context control, delegation, extensibility — are what make an Agent reliable, safe, and able to run at scale.
Suitable for: Engineers who are building or scaling AI Agent runtimes, custom Agents, or advanced multi-Agent workflows. Not suitable for: Prompt engineering, model selection, general software architecture, LLM API getting started.
All principles are distilled from production-grade runtime decisions. Claude Code serves as empirical evidence, not the only implementation.
Choose your problem
| You want to... | Read |
|---|---|
| Make the Agent remember and continuously improve across sessions | Memory system |
| Package reusable workflows and specialized knowledge | Skills system |
| Let the Agent use tools powerfully but not dangerously | Tools and safety |
| Give the Agent the right context at a reasonable cost | Context engineering |
| Split work across multiple Agents without losing control | Multi-Agent coordination |
| Extend behavior through Hooks, background tasks, or startup logic | Lifecycle and extensibility |
Before you start building: First read Pitfall Guide — these are the least intuitive but most time-consuming failure modes.
1. Memory system
User pain point: "My Agent forgets all corrections and project rules by the next conversation."
Golden rule: Distinguish between what the Agent knows(instruction memory), what the Agent learns(automatic memory), and what the Agent extracts(session memory). The three layers differ in persistence, trust level, and review requirements.
Applicable scenarios: Any Agent that runs across sessions or needs to continuously accumulate project knowledge.
How it works:
- Instruction memory is manually curated, layered configuration injected into system context by priority (organization level → user level → project level → local level; local first). Project coding standards and behavior rules live here. It is written by humans and remains stable.
- Automatic memory is persistent knowledge written autonomously by the Agent, with a type taxonomy (user / feedback / project / reference) and a capped index. Writing is a two-step operation: first write the topic file, then update the index. The cap prevents unbounded growth — without cleanup, new entries are silently truncated.
- Session extraction runs as a background Agent at the end of a session. It writes directly to automatic memory — first the topic file, then the index — following the same two-step save invariant. A mutex ensures that if the main Agent has already written memory in the current turn, the extractor skips entirely. This is the autonomous learning loop.
- Review and promotion Audit all memory layers and propose cross-layer moves (auto memory → project spec, personal settings, or team memory). It never applies changes autonomously — proposals require explicit user approval.
Start here: Define your memory layers (instructions, auto, extracted). Implement the two-step save invariant (topic file first, then index). Add background extraction only after the core write path is stable.
In Claude Code: Use
/rememberto audit and promote auto memory entries across layers.
Trade-offs:
- More memory layers = richer recall but higher maintenance burden. Without periodic cleanup, index caps cause silent data loss.
- Session extraction adds latency at session end, but greatly improves cross-session learning.
Deep reading: references/memory-persistence-pattern.md
2. Skills system
User pain point: "I want the Agent to reuse workflows and domain knowledge without re-explaining them every time."
Golden rule: Skills are lazily loaded instruction sets, not prompts injected immediately. Discovery must be cheap (metadata only); full content is loaded only on activation.
When to use: Any Agent that needs reusable, composable workflows activated by matching user intent.
How it works:
- Discovery is budget-constrained: the Agent sees a compact list of all available skills (name, description, trigger hints concatenated together), each hard-capped at a fixed character count, with the total limited to about 1% of the context window. Put trigger keywords first — anything after will be truncated.
- Loading is lazy: only metadata enters the always-on context. Full skill content is loaded only on activation, with near-zero idle token cost.
- Execution can be inline (shared context) or isolated (fork a sub-Agent with its own token budget). Isolation prevents heavy skills from exhausting the parent context.
- Source can be built-in, user-installed, or dynamically loaded from plugins. Deduplicate by canonical path to prevent the same skill from appearing twice in overlapping source directories.
Start here: Pick a metadata format (frontmatter recommended). Implement two-phase discovery: a cheap list at startup, lazy content loading on invocation. Set per-item character caps before the directory grows.
Trade-offs:
- Lazy loading saves tokens but adds a round of latency on first activation.
- Fork execution provides isolation but loses context the parent has already accumulated.
Deep reading: references/skill-runtime-pattern.md
3. Tools and security
User pain point: "I want the Agent to use tools powerfully, but not dangerously."
Golden rule: Fail-closed by default. Tools are serial and gated unless explicitly marked concurrency-safe and passed through 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 not read-only by default unless the developer actively marks them otherwise. This prevents accidental parallel execution of state-changing operations.
- Concurrency classification is per-invocation, not per-tool-type: the same tool is safe for some inputs and unsafe for others. The runtime splits a batch of tool calls into contiguous groups — safe calls execute in parallel, and any unsafe call starts a serial segment.
- Permission Pipeline evaluates rules from multiple sources in strict priority order, covering config files (user, project, local, flags, policy), CLI arguments, command-level rules, and session grants. The evaluator is stateful — it tracks denial counts, transforms patterns, and updates state as side effects.
- Handler Dispatch varies by execution environment: interactive (human prompt), automated (orchestrator), or asynchronous (Swarm Agent). The same permission rules feed different approval interfaces.
Start here: Make every tool call pass through a permission gate. Default to fail-closed (deny/ask). Before enabling any auto-approve mode, first add exemption-free rules for protected paths.
In Claude Code: Use
/update-configto configure permission rules and Hooks.
Trade-offs:
- Fail-closed defaults mean new tools are safe out of the box, but developers must proactively mark concurrency safety — forgetting to mark a read-only tool silently reduces throughput.
- Multi-source permission layering is powerful but hard to debug when rules conflict.
Further reading: references/tool-registry-pattern.md | references/permission-gate-pattern.md
4. Context Engineering
User pain point: "My Agent sees too much, too little, or the wrong thing."
Golden rule: Treat context as a budget to manage, not a trash can. Every token in the window must earn its place through one of four operations: select, write back, compress, isolate.
When to apply: Any Agent that degrades in performance over long sessions, whose delegated work pollutes the parent context, or that starts slowly due to eager loading.
How it works:
- Select — load on demand, don't load everything at once. Use three levels of progressive disclosure: metadata (always present, cheap), instructions (loaded when activated), resources (loaded on demand). Memoize expensive context builders and invalidate only at known change points — don't be reactive.
- Write back — context is not read-only. The Agent writes information back to persistent storage: automatic memory entries, background extraction output, task state, permission rules. The write-back loop is the key to turning a stateless tool caller into a learning system.
- Compress — long sessions exhaust the window. Reactive compaction summarizes old turns mid-session, preserving recent context while reclaiming budget. Mark snapshot data as snapshots so the model knows to re-fetch the current state.
- Isolate — delegated work must not pollute the parent context. Orchestrator workers inherit zero context (only an explicit prompt). Fork children inherit the full context but are limited to a single level (cannot recursively fork). Filesystem-level isolation (worktree) gives the Agent its own working copy.
Start here: Audit your current per-turn context cost. Add hard caps to every variable-length block. Before enabling any compression, first add truncation recovery pointers (telling the model which tool to call to get the full output).
Trade-offs:
- Aggressive caching reduces latency but carries staleness risk — every change point must explicitly clear the cache, otherwise the model uses stale data for the rest of the session.
- Progressive disclosure saves tokens but means the model cannot reason about a skill's full capabilities before it is activated.
Further reading: references/context-engineering-pattern.md(index) | select | compress | isolate
5. Multi-Agent Coordination
User pain point: "I want parallelism, specialization, and coordination, but not chaos."
Golden rule: The coordinator must synthesize itself and cannot delegate understanding. "Based on your findings, fix it" is an anti-pattern — the coordinator should digest worker results into a precise spec, then dispatch implementation.
When to use: When a task is too large for a single Agent, when parallel exploration is needed, or when you want persistent specialized teammates.
How it works:
Three delegation modes serve different task shapes:
| Mode | Context sharing | Suited for |
|---|---|---|
| Coordinator | None — worker starts from scratch | Complex multi-stage tasks (research → synthesis → implementation → verification) |
| Fork | All — child inherits parent history | Fast parallel splits that share already-loaded context |
| Swarm | Peer-shared task list | Long-running independent workflows |
Key constraints:
- Fork is single-layer only — recursive forking exponentially amplifies context cost.
- Swarm teammates cannot spawn other teammates — the roster is flat, preventing uncontrolled growth.
- Results arrive asynchronously; fire-and-forget registration returns an ID immediately, and the parent can continue working.
Start here: Choose one delegation mode and implement it fully before considering hybrid modes. Write each sub-Agent prompt as a self-contained document. Add a synthesis step between research and implementation workers — this is where the coordinator creates value.
Coordinator mode implementation checklist:
- Define a staged workflow: research → synthesis → implementation → verification
- Write a self-contained prompt for each worker (do not say "based on your findings")
- Filter each worker's toolset to give it only what it needs
- Decide continue vs. new strategy: continue if context overlaps, always create new for the verification stage
Trade-offs:
- Coordinator is the safest but slowest — each stage waits for the previous stage to finish.
- Fork is the fastest but only one layer, sharing the full context cost of the parent.
- Swarm is the most flexible but hardest to coordinate — peers can only communicate through a shared task list.
Further reading: references/agent-orchestration-pattern.md
6. Lifecycle and Extensibility
User pain point: "I need Hooks, background tasks, and a clean startup sequence."
Golden rule: Extensibility is an injection point, not an inheritance hierarchy. Hooks attach side effects at lifecycle moments; tasks track asynchronous work with a strict state machine; Bootstrap initializes in dependency order through memoized stages.
When to use: When you need to extend Agent behavior without modifying core code, track long-running background work, or structure initialization for multiple entry modes.
How it works:
- Hook Attach side effects at defined lifecycle moments (before/after tool execution, prompt submission, Agent start/stop). Trust is all-or-nothing: when the workspace is untrusted, all Hooks are skipped — not just the suspicious ones. Session-level Hooks are temporary and are cleaned up when the session ends.
- Long-running work Tracked via a typed state machine. Each unit of work has a typed-prefixed ID, a strict lifecycle (running → completed / failed / killed), and disk-backed output. Reclamation is two-phase: disk is cleared immediately at the terminal state, and memory is lazily cleared only after the parent receives notification.
- Bootstrap Structure initialization into dependency-ordered, memoized phases. The trust boundary — the moment the user grants authorization — is the key inflection point: security-sensitive subsystems (telemetry, secret environment variables) must not be activated before trust is established. Multiple entry modes (CLI, server, SDK) share the same Bootstrap path with different entry points.
Start here: Route all Hooks through a single dispatch point. Implement trust gating before adding any external Hook types. Register cleanup handlers at init time, not at the point of use.
In Claude Code: Use
/update-configto configure Hooks (before/after tool execution, prompt submission).
Trade-offs:
- All-or-nothing Hook trust is simple but coarse — one untrusted Hook disables the entire extension system.
- Disk-backed task output keeps memory constant but adds I/O latency proportional to concurrent units of work.
Further reading: references/hook-lifecycle-pattern.md | references/task-decomposition-pattern.md | references/bootstrap-sequence-pattern.md
Pitfall guide
Non-intuitive designs that violate these principles cause bugs:
-
Concurrency classification is per-call, not per-tool-type. The same tool is safe for some inputs and unsafe for others. Do not assume a tool's concurrency behavior is static — decide at runtime per call.
-
Permission evaluation has side effects. Permission checkers track denial counts, switch modes, and update state. Do not treat it as a pure query function.
-
Most asynchronous work skips the "pending" state. In practice, units of work are registered directly as "running". Do not build a UI that assumes every unit of work starts as pending.
-
Fork children cannot fork. Recursion protection maintains a single-level invariant. The Fork tool remains in the child's tool pool (for prompt cache sharing) but is blocked at call time.
-
Context builders are memoized but manually invalidated. Adding a context source without adding the corresponding invalidation point causes the model to see stale data throughout the session.
-
The memory index has a hard cap. Entries exceeding the cap are silently truncated. Without periodic cleanup, new entries become invisible.
-
The skill list budget is tight. Descriptions are concatenated and character-limited per entry. Put the most distinctive trigger language first — the rest will be truncated.
-
Hook trust is all-or-nothing. When the workspace is untrusted, the entire Hook system is disabled, not just individual suspicious Hooks.
-
A tool's default permission is "allow". Tools that do not implement custom permission logic delegate entirely to the rule-based system. Only override when tool-specific gating (path ACLs, quotas, etc.) is needed.
-
Reclamation requires notification. A terminal work unit may only be GC'd after the parent receives the completion signal. Reclaiming before notification creates a race, and the parent will never read the result.
This skill does not apply to
This skill is about the harness around the Agent , not:
- Prompt engineering or system prompt design
- Model selection or fine-tuning
- General software architecture (MVC, microservices)
- Chat UI or conversational interfaces
- LLM API integration basics
If your question is about the model itself rather than the system around the model, this skill does not apply.