Harness Engineering Lesson 8: Core Principles and Anti‑Patterns for Agent Design

Lesson 8 Overview

Combine the first seven lessons' components and discuss when to use each and when not to.

⏱ 13 minutes · 📚 Advanced · 🎯 Principles + checklist

What Remains from Lesson 7

The first seven lessons covered Harness's eight core components – Loop, Tools, Context, Hook, Permissions, Subagent, Skill, and MCP – theoretically allowing you to assemble any Agent.

"The gap between a programmer who can use a framework and an architect who can design one is not tools, but judgment." In this lesson we answer the success criterion: "How to judge an Agent design (what decisions are critical, what is over‑engineering)."

💡 Tip This lesson does not introduce new components; it focuses on methodology rather than mechanisms. Lesson 8 will apply these principles to a real project.

⚠️ Note Due to environment limitations we could not fetch the latest Anthropic official docs. The principles are based on insights from the first seven lessons plus general engineering experience. It is strongly recommended to read "Building Effective Agents" and "Writing Effective Tools for Agents" after the class.

Theme 1: Five Core Principles for Good Agent Design

These principles emerged naturally from the engineering insights of the previous seven lessons.

Principle 1 – Simplicity First

Anthropic clearly distinguishes Workflow and Agent:

"Workflows are predefined code paths orchestrated deterministically. Agents are systems where LLMs dynamically direct their own processes and tool usage."

First question when designing: "Can we solve the task without an Agent?" – If a single prompt or a prompt chain with the LLM API can handle the task, do not introduce Harness Agent. Complexity grows step by step:

Complexity | Mechanism               | Applicable Scenarios                | Example
-----------|------------------------|-------------------------------------|------------------------------
L1         | Single LLM API call    | Translation, rewriting, classification | "Translate this paragraph to English"
L2         | Prompt chain (deterministic steps) | Structured pipeline: summary → extraction → classification → output | "First summarize, then extract key points, finally format as markdown"
L3         | Agent loop (model decides which tool to call) | Tasks requiring external information, cannot be pre‑decomposed | "Research how this codebase implements feature X"
L4         | Multi‑Agent (multiple agents cooperate) | Parallelizable tasks or need isolated context | "Research three code modules in parallel, then aggregate"

💡 Tip Anti‑pattern example: a user asks "Translate this to English" and you build a full Harness Agent with eight built‑in tools, five MCP servers, and ten Skills, only for the model to call the LLM translation on the first round. 99 % of the work is pure overhead. First ask: "Does this task really need an Agent?"

Principle 2 – Transparency to the Model

Lesson 1 established the mental model: "Harness is a state‑machine controller, Claude is the state evaluator." All magic we saw – Compaction, Subagent isolation, MCP forwarding – is implicit to the model. The model only sees "assembled context + tool results".

Do not wrap "model decisions" inside a Harness flow. If a step requires the LLM to decide (e.g., "Does this code have a security risk?"), let the model decide directly instead of writing a fixed rule.

Do not wrap "what the model can do" inside a Harness flow. If the model can summarize a conversation well, don’t run a Hook that executes a script to summarize and then write back.

When designing abstractions, ask: Is this abstraction implicit (inside Harness) or explicit (exposed to the model)? Implicit abstractions cost no tokens; explicit ones require a good description for the model.

💡 Tip Anti‑pattern: using a Bash tool to run a Python summarizer – this moves a task the model is good at into fixed code, breaking the model’s decision flow and adding no token savings.

Principle 3 – Context Is a Scarce Resource

Lesson 4a taught that "200 K is the hard limit, not the budget." Once the main conversation reaches 80 % of the window, model performance degrades. All advanced mechanisms from the first seven lessons essentially manage this scarce resource:

Mechanism          | What Context It Saves
-------------------|----------------------
Compaction (Lesson 4a) | Early dialogue → structured summary
Truncation (Lesson 4a) | Large tool results → store on disk + reference path
Subagent (Lesson 5)    | Intermediate steps of research → isolated in Subagent window
Skill (Lesson 6)       | Knowledge body → load on demand (description stays resident)
Context: fork (Lesson 6) | Action Skill commands → run inside Subagent

💡 Tip Key quote: tokens are more expensive than money. Every time you ask "Does this information really need to go into the main context?" – put what can go into Subagent, load on demand, or store on disk instead of stuffing it all into the main context.

Principle 4 – Description Is the API

This principle appeared repeatedly in the first seven lessons and is the highest‑ROI action in Agent design.

Scenario                | What Description Determines                     | Consequence of Bad Description
------------------------|-----------------------------------------------|-----------------------------------
Tool description (Lesson 3) | Whether the model can call it correctly      | Model passes wrong parameters / calls wrong tool
Subagent description (Lesson 5) | Whether the main Agent will consider it in task X | Subagent is "almost never called"
Skill description (Lesson 6) | Whether the model will auto‑load it in task Y | Skill becomes "effectively dead"
MCP tool description (Lesson 7) | Model's ability to use external tools        | Model bypasses MCP and calls Bash directly

✅ Summary Key quote: All LLM decisions are built on descriptions. Writing a good description is not "polishing copy"; it is "designing the LLM's cognitive interface" – the same as documenting an API.

Principle 5 – Reversibility First

Lesson 4b introduced six Permission Modes, implicitly embedding this philosophy. default: Ask each time – the most irreversible operation gets the strictest permission, reversible ones get looser. acceptEdits: Automatic batch file edits – reversible (git can roll back). bypassPermissions: Full bypass – only for isolated environments (CI runner, Docker).

Subagent isolation: "worktree": Filesystem isolation – mistakes do not pollute the main workspace.

Design principle: Grade operations by reversibility, then pick the appropriate Harness mechanism:

Reversibility | Example Operations                     | Suggested Mechanism
--------------|----------------------------------------|--------------------
Irreversible  | Delete files, push remote, rm -rf      | Default permission + user confirmation dialog
Reversible but expensive | Large file edits, long tasks, external API writes | Hook interception + audit logging
Reversible and cheap | Read files, lookup docs, run tests    | acceptEdits or auto‑allow

Theme 2: Five Signals of Over‑Engineering

Just as important as good principles is recognizing over‑engineering.

Signal 1 – Premature Abstraction

Symptoms: You wrote ten Skills but only use one; you defined five Subagents but the user only calls a generic one; you registered ten MCP servers but only two are used.

Judgment: Build abstraction only after a concrete need appears. "Maybe we’ll need this later" is usually the start of over‑engineering. When the second demand appears, the code size can be halved.

⚠️ Note Anti‑pattern: "I’ll write eight built‑in Subagents to cover every possible task type." Six months later only the generic one is used; the rest are sunk cost.

Signal 2 – Over‑Delegation (3 Subagents for 1 Task)

Symptoms: You spin up three Subagents to run one task, each looping five rounds, then merge results into the main Agent.

Problem: Subagent isolation incurs overhead (new loop, system prompt, loss of main context). Running three Subagents for a single task costs more than the benefit.

Judgment: Subagents are suitable for high‑frequency stable actions or long processes. A one‑off three‑Subagent solution is better handled by the main Agent.

Signal 3 – Description Bloat

Symptoms: Skill description contains a long paragraph of "what to do + how to do + cautions", stuffing instructions into the description.

Problem: Description lives in the main context, consuming tokens, and dilutes semantic matching. The model’s ability to pick the right tool drops.

Judgment: Keep description focused on 1‑2 common "when‑to‑use" scenarios. Put detailed instructions in the body and load on demand.

Signal 4 – Hook Spaghetti

Symptoms: Using PreToolUse to intercept every Bash call, add logging, regex validation, prompt rewriting – the Harness permission checks are completely bypassed.

Problem: Hooks are meant to insert logic at critical moments, not replace Harness’s built‑in mechanisms (permissions, tool whitelist, bypass modes). Overusing them defeats the layered design.

Judgment: Hooks should handle exceptions (dynamic decisions, audit logs, custom workflows), not rewrite "big rules" (permissions, tool whitelists).

Signal 5 – Reinventing Standards

Symptoms: You implement your own JSON‑RPC, context compression, or permission interception despite existing MCP, Compaction, and permissions mechanisms.

Problem: Re‑implementing discards ecosystem compatibility, maintenance, and community support. Anthropic’s Compaction is kept in sync with model updates; custom scripts become outdated quickly.

Judgment: Before writing anything, ask "Does Harness / the protocol layer already provide this capability?" The answer is usually yes.

Theme 3: Decision Matrix – Five Key Decision Points

Translate the principles into actionable tools. The following matrix shows the most common judgment points when designing an Agent:

Decision Point | Choose A (simpler)                     | Choose B (more complex)                | Heuristic Guidance
---------------|--------------------------------------|----------------------------------------|-------------------
Loop Depth     | Single prompt / Prompt chain         | Agent loop / Multi‑Agent                | If the task needs external info / cannot be pre‑decomposed → Agent; otherwise Workflow
Task Isolation  | Main Agent does it itself            | Delegate to Subagent                   | "Compressible / >10 rounds / can run in parallel" → Subagent; "Frequent back‑and‑forth / cannot compress" → Main Agent
Knowledge Injection | CLAUDE.md (global)                | Skill (on‑demand)                     | "Spans entire session" → Skill; "Project‑wide conventions" → CLAUDE.md
External Integration | Bash script calling API          | MCP Server                            | "Reusable / team‑shared" → MCP; "One‑off shell script" → Bash
Tool Granularity | Large monolithic tool                | Small atomic tool                     | "High‑frequency stable action" → atomic; "Long‑tail operation" → Bash fallback

💡 Tip When designing a new Agent, walk through this decision tree. Each branch corresponds to a component covered in the first seven lessons. After the walk‑through, your design choices have a clear rationale instead of a gut feeling.

Theme 4: Evaluation Checklist – Is Your Agent Design Good Enough?

After completing the design, verify it against the following ten questions. Each ✓ maps to a principle; each ✗ indicates an improvement area:

Can the task be solved with a Workflow / Prompt chain? (Principle 1)

Is each abstraction implicit or explicit? Are explicit ones described well? (Principle 2)

Will the main context exceed 80 % of the window? Are Compaction / Truncation / Subagent fallbacks in place? (Principle 3)

Do all tool / Subagent / Skill / MCP descriptions focus on "when to use me"? (Principle 4)

Are irreversible operations gated by a Prompt confirmation? Are expensive reversible actions audited by a Hook? (Principle 5)

Do you have components written for "future needs" that are never used? (Signal 1)

Are Subagents used only once instead of for high‑frequency stable scenarios? (Signal 2)

Are Skill descriptions concise (1‑2 sentences) rather than long paragraphs? (Signal 3)

Do Hooks only handle exceptions rather than rewrite major rules? (Signal 4)

Did you re‑implement any standard capability that Harness already provides? (Signal 5)

💡 Tip Print the checklist after each design iteration. All ✓ means the design is mature; three or more ✗ indicate clear improvement points.

Theme 5: From "Can Use" to "Can Design"

The first seven lessons taught "how to use Harness" – knowing each component, how to configure, and when it fires.

The mission’s success criterion is "can design Harness" – knowing when NOT to use a component. The gap between the two abilities lies in four dimensions:

Dimension          | Knowing How to Use Harness                | Knowing How to Design Harness
-------------------|-------------------------------------------|-----------------------------------
Component Knowledge| Know the components and can configure them | Know which components should NOT be used
Trade‑off Judgment | Follow default documentation settings      | Customize permissions, isolation, model choice per task
Failure Handling   | Look up docs when errors occur            | Pre‑design retry, rollback, degradation paths
Evolution Ability   | Upgrade with framework versions           | Decide which upgrades are real improvements vs over‑abstraction

✅ Summary Core of this lesson: five principles (simplicity, transparency, context scarcity, description as API, reversibility), five over‑engineering signals, five decision points, a ten‑item checklist, and the insight that knowing when NOT to use a component separates a practitioner from an architect.

Hands‑On: Self‑Audit Your Claude Code

This practical session is different – you don’t write code, you audit your existing setup. Open ~/.claude/ and answer the ten checklist questions:

Simple? Can any task be split into a Workflow?

Transparent? Do any Subagent / Skill / Hook rewrite major rules?

Context? What part of your longest conversation dominates the token budget?

Description quality? Are your Subagent / Skill / MCP descriptions one sentence or a paragraph?

Permission layering? How many permissions.deny entries do you have? Are they grouped by reversibility?

Unused components? Which Skills / MCP servers haven’t been called for a long time?

Subagent usage frequency? How many times per month does each custom Subagent run?

Skill description length? How many exceed 50 characters?

Hook count? Are you intercepting every tool call?

Custom vs standard? Have you written your own JSON‑RPC, context compression, or permission interceptor?

Write down the answers – each ✗ becomes a focus for the next lesson.

Lesson 8 Summary

✅ Summary This lesson’s core: five principles (simplicity, transparency, context scarcity, description as API, reversibility), five over‑engineering signals, five decision points (loop depth, task isolation, knowledge injection, external integration, tool granularity), and a ten‑item checklist to evaluate maturity. Knowing when NOT to use a component is the architect’s watershed.

✅ Summary Meta‑insight: the first seven lessons taught "how to use the eight components" – the basics of carpentry. Lesson 8 teaches "when to use which tool and when to put the hammer down" – the craftsman’s judgment. Anthropic repeatedly stresses the Workflow vs Agent distinction; the real risk is over‑using powerful tools.

Recommended Reading

Anthropic: Building Effective Agents – essential reading on Workflow vs Agent, five workflow modes, and over‑engineering signals.

Anthropic: Writing Effective Tools for Agents – core principles of tool design, echoing this lesson’s "description decides everything".

Anthropic: Effective Context Engineering for AI Agents – complete methodology for handling scarce context.

Potential Follow‑Up Questions

"The five principles sound right, but how do I know which one to apply?"

Don’t treat the principles as prescriptive rules; treat them as checks. After you finish a design, run the ten‑point checklist – each ✗ points to a principle that needs attention. The principles are validation tools, not dogma.

"Anthropic says ‘Agents are new’ – are these principles final?"

They are not immutable laws. Agent engineering evolves quickly, but the five principles stem from timeless software‑engineering ideas (KISS, single responsibility, least privilege) applied to the Agent context. New tools may appear, but the principles will likely remain relevant for years.

"If my checklist is all green, is the design perfect?"

No. The checklist covers necessary conditions, not sufficient ones. It catches common pitfalls, but real‑world performance, user experience, and error recovery still need empirical validation.

"The mission says we can write a minimal Agent with Claude Agent SDK – are eight lessons enough?"

For "can write", yes – you now know how to use each component. For "can write well", you need hands‑on practice. After lesson 9, pick a small real project (e.g., auto‑review PR descriptions, query internal wiki, or turn meeting recordings into structured minutes) and apply what you’ve learned.

💡 Tip Use the decision tree when designing a new Agent – each fork maps to a component from the first seven lessons. Walking the tree gives you a clear rationale for every design choice.