abc/analysis_claude_code
1
0
Fork 0
mirror of https://github.com/shareAI-lab/analysis_claude_code.git synced 2026-05-06 16:26:16 +08:00
Code Issues Packages Projects Releases Wiki Activity

the model is the agent, the code is the harness

Browse Source 
Comprehensive rewrite establishing the harness engineering narrative
across the entire repository.

README (EN/ZH/JA): added "The Model IS the Agent" manifesto with
historical proof (DQN, OpenAI Five, AlphaStar, Tencent Jueyu),
"What an Agent Is NOT" critique, harness engineer role definition,
"Why Claude Code" as masterclass in harness design, and universe
vision. Consistent framing: model = driver, harness = vehicle.

docs (36 files, 3 languages): injected one-line "Harness layer"
callout after the motto in every session document (s01-s12).

agents (13 Python files): added harness framing comment before
each module docstring.

skills/agent-philosophy.md: full rewrite aligned with harness
narrative.
This commit is contained in:
CrazyBoyM
2026-03-18 01:19:34 +08:00
parent e57ced7d07
commit a9c71002d2
54 changed files with 631 additions and 115 deletions
Download Patch File Download Diff File Expand all files Collapse all files

138
skills/agent-builder/references/agent-philosophy.md
View File

@@ -1,144 +1,154 @@
# The Philosophy of Agents
# The Philosophy of Agent Harness Engineering
> **The model already knows how to be an agent. Your job is to get out of the way.**
> **The model already knows how to be an agent. Your job is to build it a world worth acting in.**
## The Fundamental Insight
## The Fundamental Truth
Strip away every framework, every library, every architectural pattern. What remains?
A loop. A model. An invitation to act.
The agent is not the code. The agent is the model itself - a vast neural network trained on humanity's collective problem-solving, reasoning, and tool use. The code merely provides the opportunity for the model to express its agency.
The agent is not the code. The agent is the model itself -- a vast neural network trained on humanity's collective problem-solving, reasoning, and tool use. The code merely provides the opportunity for the model to express its agency.
## Why This Matters
The code is the harness. The model is the agent. These are not interchangeable. Confuse them, and you will build the wrong thing.
Most agent implementations fail not from too little engineering, but from too much. They constrain. They prescribe. They second-guess the very intelligence they're trying to leverage.
## What an Agent IS
Consider: The model has been trained on millions of examples of problem-solving. It has seen how experts approach complex tasks, how tools are used, how plans are formed and revised. This knowledge is already there, encoded in billions of parameters.
An agent is a neural network -- a Transformer, an RNN, a learned function -- that has been trained, through billions of gradient updates on action-sequence data, to perceive an environment, reason about goals, and take actions to achieve them.
Your job is not to teach it how to think. Your job is to give it the means to act.
A human is an agent: a biological neural network shaped by evolution. DeepMind's DQN is an agent: a convolutional network that learned to play Atari from raw pixels. OpenAI Five is an agent: five networks that learned Dota 2 teamwork through self-play. Claude is an agent: a language model that learned to reason and act from the breadth of human knowledge.
## The Three Elements
In every case, the agent is the trained model. Not the game engine. Not the Dota 2 client. Not the terminal. The model.
### 1. Capabilities (Tools)
## What an Agent Is NOT
Capabilities answer: **What can the agent DO?**
Prompt plumbing is not agency. Wiring together LLM API calls with if-else branches, node graphs, and hardcoded routing logic does not produce an agent. It produces a brittle pipeline -- a Rube Goldberg machine with an LLM wedged in as a text-completion node.
They are the hands of the model - its ability to affect the world. Without capabilities, the model can only speak. With them, it can act.
You cannot engineer your way to agency. Agency is learned, not programmed. No amount of glue code will emergently produce autonomous behavior. Those systems are the modern resurrection of GOFAI -- symbolic rule systems the field abandoned decades ago, now spray-painted with an LLM veneer.
**The design principle**: Each capability should be atomic, clear, and well-described. The model needs to understand what each capability does, but not how to use them in sequence - it will figure that out.
## The Harness: What We Actually Build
**Common mistake**: Too many capabilities. The model gets confused, starts using the wrong ones, or paralyzed by choice. Start with 3-5. Add more only when the model consistently fails to accomplish tasks because a capability is missing.
If the model is the agent, then what is the code? It is the **harness** -- the environment that gives the agent the ability to perceive and act in a specific domain.
### 2. Knowledge (Skills)
```
Harness = Tools + Knowledge + Observation + Action Interfaces + Permissions
```
### Tools: The Agent's Hands
Tools answer: **What can the agent DO?**
Each tool is an atomic action the agent can take in its environment. File read/write, shell execution, API calls, browser control, database queries. The model needs to understand what each tool does, but not how to sequence them -- it will figure that out.
**Design principle**: Atomic, composable, well-described. Start with 3-5. Add more only when the model consistently fails to accomplish tasks because a tool is missing.
### Knowledge: The Agent's Expertise
Knowledge answers: **What does the agent KNOW?**
This is domain expertise - the specialized understanding that turns a general assistant into a domain expert. A customer service agent needs to know company policies. A research agent needs to know methodology. A creative agent needs to know style guidelines.
Domain expertise that turns a general agent into a domain specialist. Product documentation, architectural decisions, regulatory requirements, style guides. Inject on-demand (via tool_result), not upfront (via system prompt). Progressive disclosure preserves context for what matters.
**The design principle**: Inject knowledge on-demand, not upfront. The model doesn't need to know everything at once - only what's relevant to the current task. Progressive disclosure preserves context for what matters.
**Design principle**: Available but not mandatory. The agent should know what knowledge exists and pull what it needs.
**Common mistake**: Front-loading all possible knowledge into the system prompt. This wastes context, confuses the model, and makes every interaction expensive. Instead, make knowledge available but not mandatory.
### Context: The Agent's Memory
### 3. Context (The Conversation)
Context is the thread connecting individual actions into coherent behavior. What has been said, tried, learned, and decided.
Context is the memory of the interaction - what has been said, what has been tried, what has been learned. It's the thread that connects individual actions into coherent behavior.
**Design principle**: Context is precious. Protect it. Isolate subtasks that generate noise (s04). Compress when history grows long (s06). Persist goals beyond single conversations (s07).
**The design principle**: Context is precious. Protect it. Isolate subtasks that generate noise. Truncate outputs that exceed usefulness. Summarize when history grows long.
### Permissions: The Agent's Boundaries
**Common mistake**: Letting context grow unbounded, filling it with exploration details, failed attempts, and verbose tool outputs. Eventually the model can't find the signal in the noise.
Permissions answer: **What is the agent ALLOWED to do?**
## The Universal Pattern
Sandbox file access. Require approval for destructive operations. Enforce trust boundaries between the agent and external systems. This is where safety engineering meets harness engineering.
Every effective agent - regardless of domain, framework, or implementation - follows the same pattern:
**Design principle**: Constraints focus behavior, not limit it. "One task in_progress at a time" forces sequential focus. "Read-only subagent" prevents accidental modifications.
### Task-Process Data: The Agent's Training Signal
Every action sequence the agent executes in your harness is training signal. The perception-reasoning-action traces from real deployments are the raw material for fine-tuning the next generation of agent models. Your harness doesn't just serve the agent -- it can help evolve the agent.
## The Universal Loop
Every effective agent -- regardless of domain -- follows the same pattern:
```
LOOP:
Model sees: conversation history + available capabilities
Model sees: conversation history + available tools
Model decides: act or respond
If act: capability executed, result added to context, loop continues
If act: tool executed, result added to context, loop continues
If respond: answer returned, loop ends
```
This is not a simplification. This is the actual architecture. Everything else is optimization.
This is not a simplification. This is the actual architecture. Everything else is harness engineering -- mechanisms layered on top of this loop to make the agent more effective. The loop belongs to the agent. The mechanisms belong to the harness.
## Designing for Agency
## Principles of Harness Engineering
### Trust the Model
The most important principle: **trust the model**.
Don't try to anticipate every edge case. Don't build elaborate decision trees. Don't pre-specify the workflow.
Don't anticipate every edge case. Don't build elaborate decision trees. Don't pre-specify the workflow.
The model is better at reasoning than any rule system you could write. Your conditional logic will fail on edge cases. The model will reason through them.
**Give the model capabilities and knowledge. Let it figure out how to use them.**
**Give the model tools and knowledge. Let it figure out how to use them.**
### Constraints Enable
This seems paradoxical, but constraints don't limit agents - they focus them.
This seems paradoxical, but constraints don't limit agents -- they focus them.
A todo list with "only one task in progress" forces sequential focus. A subagent with "read-only access" prevents accidental modifications. A response with "under 100 words" demands clarity.
A todo list with "only one task in progress" forces sequential focus. A subagent with read-only access prevents accidental modifications. A context compression threshold keeps history from overwhelming.
The best constraints are those that prevent the model from getting lost, not those that micromanage its approach.
The best constraints prevent the model from getting lost, not micromanage its approach.
### Progressive Complexity
Never build everything upfront.
```
Level 0: Model + one capability
Level 1: Model + 3-5 capabilities
Level 2: Model + capabilities + planning
Level 3: Model + capabilities + planning + subagents
Level 4: Model + capabilities + planning + subagents + skills
Level 0: Model + one tool (bash) -- s01
Level 1: Model + tool dispatch map -- s02
Level 2: Model + planning -- s03
Level 3: Model + subagents + skills -- s04, s05
Level 4: Model + context management + persistence -- s06, s07, s08
Level 5: Model + teams + autonomy + isolation -- s09-s12
```
Start at the lowest level that might work. Move up only when real usage reveals the need. Most agents never need to go beyond Level 2.
Start at the lowest level that might work. Move up only when real usage reveals the need.
## The Agent Mindset
## The Mind Shift
Building agents requires a shift in thinking:
Building harnesses requires a fundamental shift in thinking:
**From**: "How do I make the system do X?"
**To**: "How do I enable the model to do X?"
**From**: "What should happen when the user says Y?"
**To**: "What capabilities would help address Y?"
**To**: "What tools would help address Y?"
**From**: "What's the workflow for this task?"
**To**: "What does the model need to figure out the workflow?"
The best agent code is almost boring. Simple loops. Clear capability definitions. Clean context management. The magic isn't in the code - it's in the model.
**From**: "I'm building an agent."
**To**: "I'm building a harness for the agent."
## Philosophical Foundations
The best harness code is almost boring. Simple loops. Clear tool definitions. Clean context management. The magic isn't in the code -- it's in the model.
### The Model as Emergent Agent
## The Vehicle Metaphor
Language models trained on human text have learned not just language, but patterns of thought. They've absorbed how humans approach problems, use tools, and accomplish goals. This is emergent agency - not programmed, but learned.
The model is the driver. The harness is the vehicle.
When you give a model capabilities, you're not teaching it to be an agent. You're giving it permission to express the agency it already has.
A coding agent's vehicle is its IDE, terminal, and filesystem. A farm agent's vehicle is its sensor array, irrigation controls, and weather data. A hotel agent's vehicle is its booking system, guest channels, and facility APIs.
### The Loop as Liberation
The driver generalizes. The vehicle specializes. Your job as a harness engineer is to build the best vehicle for your domain -- one that gives the driver maximum visibility, precise controls, and clear boundaries.
The agent loop is deceptively simple: get response, check for tool use, execute, repeat. But this simplicity is its power.
The loop doesn't constrain the model to particular sequences. It doesn't enforce specific workflows. It simply says: "You have capabilities. Use them as you see fit. I'll execute what you request and show you the results."
This is liberation, not limitation.
### Capabilities as Expression
Each capability you provide is a form of expression for the model. "Read file" lets it see. "Write file" lets it create. "Search" lets it explore. "Send message" lets it communicate.
The art of agent design is choosing which forms of expression to enable. Too few, and the model is mute. Too many, and it speaks in tongues.
Build the cockpit. Build the dashboard. Build the controls. The pilot is already trained.
## Conclusion
The agent is the model. The code is just the loop. Your job is to get out of the way.
The model is the agent. The code is the harness. Know which one you're building.
Give the model clear capabilities. Make knowledge available when needed. Protect the context from noise. Trust the model to figure out the rest.
You are not writing intelligence. You are building the world intelligence inhabits. The quality of that world -- how clearly the agent can perceive, how precisely it can act, how rich its knowledge -- directly determines how effectively the intelligence can express itself.
That's it. That's the philosophy.
Everything else is refinement.
Build great harnesses. The agent will do the rest.