the model is the agent, the code is the harness

CrazyBoyM · CrazyBoyM · commit a9c71002d2ca · 2026-03-18T01:19:34.000+08:00
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.
diff --git a/README-ja.md b/README-ja.md
diff --git a/README-zh.md b/README-zh.md
diff --git a/README.md b/README.md
diff --git a/agents/__init__.py b/agents/__init__.py
@@ -1,2 +1,3 @@
-# agents/ - Python teaching agents (s01-s12) + reference agent (s_full)
+# agents/ - Harness implementations (s01-s12) + full reference (s_full)
 # Each file is self-contained and runnable: python agents/s01_agent_loop.py
+# The model is the agent. These files are the harness.
diff --git a/agents/s01_agent_loop.py b/agents/s01_agent_loop.py
@@ -1,4 +1,5 @@
 #!/usr/bin/env python3
+# Harness: the loop -- the model's first connection to the real world.
 """
 s01_agent_loop.py - The Agent Loop
 
diff --git a/agents/s02_tool_use.py b/agents/s02_tool_use.py
@@ -1,4 +1,5 @@
 #!/usr/bin/env python3
+# Harness: tool dispatch -- expanding what the model can reach.
 """
 s02_tool_use.py - Tools
 
diff --git a/agents/s03_todo_write.py b/agents/s03_todo_write.py
@@ -1,4 +1,5 @@
 #!/usr/bin/env python3
+# Harness: planning -- keeping the model on course without scripting the route.
 """
 s03_todo_write.py - TodoWrite
 
diff --git a/agents/s04_subagent.py b/agents/s04_subagent.py
@@ -1,4 +1,5 @@
 #!/usr/bin/env python3
+# Harness: context isolation -- protecting the model's clarity of thought.
 """
 s04_subagent.py - Subagents
 
diff --git a/agents/s05_skill_loading.py b/agents/s05_skill_loading.py
@@ -1,4 +1,5 @@
 #!/usr/bin/env python3
+# Harness: on-demand knowledge -- domain expertise, loaded when the model asks.
 """
 s05_skill_loading.py - Skills
 
diff --git a/agents/s06_context_compact.py b/agents/s06_context_compact.py
@@ -1,4 +1,5 @@
 #!/usr/bin/env python3
+# Harness: compression -- clean memory for infinite sessions.
 """
 s06_context_compact.py - Compact
 
diff --git a/agents/s07_task_system.py b/agents/s07_task_system.py
@@ -1,4 +1,5 @@
 #!/usr/bin/env python3
+# Harness: persistent tasks -- goals that outlive any single conversation.
 """
 s07_task_system.py - Tasks
 
diff --git a/agents/s08_background_tasks.py b/agents/s08_background_tasks.py
@@ -1,4 +1,5 @@
 #!/usr/bin/env python3
+# Harness: background execution -- the model thinks while the harness waits.
 """
 s08_background_tasks.py - Background Tasks
 
diff --git a/agents/s09_agent_teams.py b/agents/s09_agent_teams.py
@@ -1,4 +1,5 @@
 #!/usr/bin/env python3
+# Harness: team mailboxes -- multiple models, coordinated through files.
 """
 s09_agent_teams.py - Agent Teams
 
diff --git a/agents/s10_team_protocols.py b/agents/s10_team_protocols.py
@@ -1,4 +1,5 @@
 #!/usr/bin/env python3
+# Harness: protocols -- structured handshakes between models.
 """
 s10_team_protocols.py - Team Protocols
 
diff --git a/agents/s11_autonomous_agents.py b/agents/s11_autonomous_agents.py
@@ -1,4 +1,5 @@
 #!/usr/bin/env python3
+# Harness: autonomy -- models that find work without being told.
 """
 s11_autonomous_agents.py - Autonomous Agents
 
diff --git a/agents/s12_worktree_task_isolation.py b/agents/s12_worktree_task_isolation.py
@@ -1,4 +1,5 @@
 #!/usr/bin/env python3
+# Harness: directory isolation -- parallel execution lanes that never collide.
 """
 s12_worktree_task_isolation.py - Worktree + Task Isolation
 
diff --git a/agents/s_full.py b/agents/s_full.py
@@ -1,4 +1,5 @@
 #!/usr/bin/env python3
+# Harness: all mechanisms combined -- the complete cockpit for the model.
 """
 s_full.py - Full Reference Agent
 
diff --git a/docs/en/s01-the-agent-loop.md b/docs/en/s01-the-agent-loop.md
@@ -3,6 +3,8 @@
 `[ s01 ] s02 > s03 > s04 > s05 > s06 | s07 > s08 > s09 > s10 > s11 > s12`
 
 > *"One loop & Bash is all you need"* -- one tool + one loop = an agent.
+>
+> **Harness layer**: The loop -- the model's first connection to the real world.
 
 ## Problem
 
diff --git a/docs/en/s02-tool-use.md b/docs/en/s02-tool-use.md
@@ -3,6 +3,8 @@
 `s01 > [ s02 ] s03 > s04 > s05 > s06 | s07 > s08 > s09 > s10 > s11 > s12`
 
 > *"Adding a tool means adding one handler"* -- the loop stays the same; new tools register into the dispatch map.
+>
+> **Harness layer**: Tool dispatch -- expanding what the model can reach.
 
 ## Problem
 
diff --git a/docs/en/s03-todo-write.md b/docs/en/s03-todo-write.md
@@ -3,6 +3,8 @@
 `s01 > s02 > [ s03 ] s04 > s05 > s06 | s07 > s08 > s09 > s10 > s11 > s12`
 
 > *"An agent without a plan drifts"* -- list the steps first, then execute.
+>
+> **Harness layer**: Planning -- keeping the model on course without scripting the route.
 
 ## Problem
 
diff --git a/docs/en/s04-subagent.md b/docs/en/s04-subagent.md
@@ -3,6 +3,8 @@
 `s01 > s02 > s03 > [ s04 ] s05 > s06 | s07 > s08 > s09 > s10 > s11 > s12`
 
 > *"Break big tasks down; each subtask gets a clean context"* -- subagents use independent messages[], keeping the main conversation clean.
+>
+> **Harness layer**: Context isolation -- protecting the model's clarity of thought.
 
 ## Problem
 
diff --git a/docs/en/s05-skill-loading.md b/docs/en/s05-skill-loading.md
@@ -3,6 +3,8 @@
 `s01 > s02 > s03 > s04 > [ s05 ] s06 | s07 > s08 > s09 > s10 > s11 > s12`
 
 > *"Load knowledge when you need it, not upfront"* -- inject via tool_result, not the system prompt.
+>
+> **Harness layer**: On-demand knowledge -- domain expertise, loaded when the model asks.
 
 ## Problem
 
diff --git a/docs/en/s06-context-compact.md b/docs/en/s06-context-compact.md
@@ -3,6 +3,8 @@
 `s01 > s02 > s03 > s04 > s05 > [ s06 ] | s07 > s08 > s09 > s10 > s11 > s12`
 
 > *"Context will fill up; you need a way to make room"* -- three-layer compression strategy for infinite sessions.
+>
+> **Harness layer**: Compression -- clean memory for infinite sessions.
 
 ## Problem
 
diff --git a/docs/en/s07-task-system.md b/docs/en/s07-task-system.md
@@ -3,6 +3,8 @@
 `s01 > s02 > s03 > s04 > s05 > s06 | [ s07 ] s08 > s09 > s10 > s11 > s12`
 
 > *"Break big goals into small tasks, order them, persist to disk"* -- a file-based task graph with dependencies, laying the foundation for multi-agent collaboration.
+>
+> **Harness layer**: Persistent tasks -- goals that outlive any single conversation.
 
 ## Problem
 
diff --git a/docs/en/s08-background-tasks.md b/docs/en/s08-background-tasks.md
@@ -3,6 +3,8 @@
 `s01 > s02 > s03 > s04 > s05 > s06 | s07 > [ s08 ] s09 > s10 > s11 > s12`
 
 > *"Run slow operations in the background; the agent keeps thinking"* -- daemon threads run commands, inject notifications on completion.
+>
+> **Harness layer**: Background execution -- the model thinks while the harness waits.
 
 ## Problem
 
diff --git a/docs/en/s09-agent-teams.md b/docs/en/s09-agent-teams.md
@@ -3,6 +3,8 @@
 `s01 > s02 > s03 > s04 > s05 > s06 | s07 > s08 > [ s09 ] s10 > s11 > s12`
 
 > *"When the task is too big for one, delegate to teammates"* -- persistent teammates + async mailboxes.
+>
+> **Harness layer**: Team mailboxes -- multiple models, coordinated through files.
 
 ## Problem
 
diff --git a/docs/en/s10-team-protocols.md b/docs/en/s10-team-protocols.md
@@ -3,6 +3,8 @@
 `s01 > s02 > s03 > s04 > s05 > s06 | s07 > s08 > s09 > [ s10 ] s11 > s12`
 
 > *"Teammates need shared communication rules"* -- one request-response pattern drives all negotiation.
+>
+> **Harness layer**: Protocols -- structured handshakes between models.
 
 ## Problem
 
diff --git a/docs/en/s11-autonomous-agents.md b/docs/en/s11-autonomous-agents.md
@@ -3,6 +3,8 @@
 `s01 > s02 > s03 > s04 > s05 > s06 | s07 > s08 > s09 > s10 > [ s11 ] s12`
 
 > *"Teammates scan the board and claim tasks themselves"* -- no need for the lead to assign each one.
+>
+> **Harness layer**: Autonomy -- models that find work without being told.
 
 ## Problem
 
diff --git a/docs/en/s12-worktree-task-isolation.md b/docs/en/s12-worktree-task-isolation.md
@@ -3,6 +3,8 @@
 `s01 > s02 > s03 > s04 > s05 > s06 | s07 > s08 > s09 > s10 > s11 > [ s12 ]`
 
 > *"Each works in its own directory, no interference"* -- tasks manage goals, worktrees manage directories, bound by ID.
+>
+> **Harness layer**: Directory isolation -- parallel execution lanes that never collide.
 
 ## Problem
 
diff --git a/docs/ja/s01-the-agent-loop.md b/docs/ja/s01-the-agent-loop.md
@@ -3,6 +3,8 @@
 `[ s01 ] s02 > s03 > s04 > s05 > s06 | s07 > s08 > s09 > s10 > s11 > s12`
 
 > *"One loop & Bash is all you need"* -- 1つのツール + 1つのループ = エージェント。
+>
+> **Harness 層**: ループ -- モデルと現実世界を繋ぐ最初の接点。
 
 ## 問題
 
diff --git a/docs/ja/s02-tool-use.md b/docs/ja/s02-tool-use.md
@@ -3,6 +3,8 @@
 `s01 > [ s02 ] s03 > s04 > s05 > s06 | s07 > s08 > s09 > s10 > s11 > s12`
 
 > *"ツールを足すなら、ハンドラーを1つ足すだけ"* -- ループは変わらない。新ツールは dispatch map に登録するだけ。
+>
+> **Harness 層**: ツール分配 -- モデルが届く範囲を広げる。
 
 ## 問題
 
diff --git a/docs/ja/s03-todo-write.md b/docs/ja/s03-todo-write.md
@@ -3,6 +3,8 @@
 `s01 > s02 > [ s03 ] s04 > s05 > s06 | s07 > s08 > s09 > s10 > s11 > s12`
 
 > *"計画のないエージェントは行き当たりばったり"* -- まずステップを書き出し、それから実行。
+>
+> **Harness 層**: 計画 -- 航路を描かずにモデルを軌道に乗せる。
 
 ## 問題
 
diff --git a/docs/ja/s04-subagent.md b/docs/ja/s04-subagent.md
@@ -3,6 +3,8 @@
 `s01 > s02 > s03 > [ s04 ] s05 > s06 | s07 > s08 > s09 > s10 > s11 > s12`
 
 > *"大きなタスクを分割し、各サブタスクにクリーンなコンテキストを"* -- サブエージェントは独立した messages[] を使い、メイン会話を汚さない。
+>
+> **Harness 層**: コンテキスト隔離 -- モデルの思考の明晰さを守る。
 
 ## 問題
 
diff --git a/docs/ja/s05-skill-loading.md b/docs/ja/s05-skill-loading.md
@@ -3,6 +3,8 @@
 `s01 > s02 > s03 > s04 > [ s05 ] s06 | s07 > s08 > s09 > s10 > s11 > s12`
 
 > *"必要な知識を、必要な時に読み込む"* -- system prompt ではなく tool_result で注入。
+>
+> **Harness 層**: オンデマンド知識 -- モデルが求めた時だけ渡すドメイン専門性。
 
 ## 問題
 
diff --git a/docs/ja/s06-context-compact.md b/docs/ja/s06-context-compact.md
@@ -3,6 +3,8 @@
 `s01 > s02 > s03 > s04 > s05 > [ s06 ] | s07 > s08 > s09 > s10 > s11 > s12`
 
 > *"コンテキストはいつか溢れる、空ける手段が要る"* -- 3層圧縮で無限セッションを実現。
+>
+> **Harness 層**: 圧縮 -- クリーンな記憶、無限のセッション。
 
 ## 問題
 
diff --git a/docs/ja/s07-task-system.md b/docs/ja/s07-task-system.md
@@ -3,6 +3,8 @@
 `s01 > s02 > s03 > s04 > s05 > s06 | [ s07 ] s08 > s09 > s10 > s11 > s12`
 
 > *"大きな目標を小タスクに分解し、順序付けし、ディスクに記録する"* -- ファイルベースのタスクグラフ、マルチエージェント協調の基盤。
+>
+> **Harness 層**: 永続タスク -- どの会話よりも長く生きる目標。
 
 ## 問題
 
diff --git a/docs/ja/s08-background-tasks.md b/docs/ja/s08-background-tasks.md
@@ -3,6 +3,8 @@
 `s01 > s02 > s03 > s04 > s05 > s06 | s07 > [ s08 ] s09 > s10 > s11 > s12`
 
 > *"遅い操作はバックグラウンドへ、エージェントは次を考え続ける"* -- デーモンスレッドがコマンド実行、完了後に通知を注入。
+>
+> **Harness 層**: バックグラウンド実行 -- モデルが考え続ける間、Harness が待つ。
 
 ## 問題
 
diff --git a/docs/ja/s09-agent-teams.md b/docs/ja/s09-agent-teams.md
@@ -3,6 +3,8 @@
 `s01 > s02 > s03 > s04 > s05 > s06 | s07 > s08 > [ s09 ] s10 > s11 > s12`
 
 > *"一人で終わらないなら、チームメイトに任せる"* -- 永続チームメイト + 非同期メールボックス。
+>
+> **Harness 層**: チームメールボックス -- 複数モデルをファイルで協調。
 
 ## 問題
 
diff --git a/docs/ja/s10-team-protocols.md b/docs/ja/s10-team-protocols.md
@@ -3,6 +3,8 @@
 `s01 > s02 > s03 > s04 > s05 > s06 | s07 > s08 > s09 > [ s10 ] s11 > s12`
 
 > *"チームメイト間には統一の通信ルールが必要"* -- 1つの request-response パターンが全交渉を駆動。
+>
+> **Harness 層**: プロトコル -- モデル間の構造化されたハンドシェイク。
 
 ## 問題
 
diff --git a/docs/ja/s11-autonomous-agents.md b/docs/ja/s11-autonomous-agents.md
@@ -3,6 +3,8 @@
 `s01 > s02 > s03 > s04 > s05 > s06 | s07 > s08 > s09 > s10 > [ s11 ] s12`
 
 > *"チームメイトが自らボードを見て、仕事を取る"* -- リーダーが逐一割り振る必要はない。
+>
+> **Harness 層**: 自律 -- 指示なしで仕事を見つけるモデル。
 
 ## 問題
 
diff --git a/docs/ja/s12-worktree-task-isolation.md b/docs/ja/s12-worktree-task-isolation.md
@@ -3,6 +3,8 @@
 `s01 > s02 > s03 > s04 > s05 > s06 | s07 > s08 > s09 > s10 > s11 > [ s12 ]`
 
 > *"各自のディレクトリで作業し、互いに干渉しない"* -- タスクは目標を管理、worktree はディレクトリを管理、IDで紐付け。
+>
+> **Harness 層**: ディレクトリ隔離 -- 決して衝突しない並列実行レーン。
 
 ## 問題
 
diff --git a/docs/zh/s01-the-agent-loop.md b/docs/zh/s01-the-agent-loop.md
@@ -3,6 +3,8 @@
 `[ s01 ] s02 > s03 > s04 > s05 > s06 | s07 > s08 > s09 > s10 > s11 > s12`
 
 > *"One loop & Bash is all you need"* -- 一个工具 + 一个循环 = 一个智能体。
+>
+> **Harness 层**: 循环 -- 模型与真实世界的第一道连接。
 
 ## 问题
 
diff --git a/docs/zh/s02-tool-use.md b/docs/zh/s02-tool-use.md
@@ -3,6 +3,8 @@
 `s01 > [ s02 ] s03 > s04 > s05 > s06 | s07 > s08 > s09 > s10 > s11 > s12`
 
 > *"加一个工具, 只加一个 handler"* -- 循环不用动, 新工具注册进 dispatch map 就行。
+>
+> **Harness 层**: 工具分发 -- 扩展模型能触达的边界。
 
 ## 问题
 
diff --git a/docs/zh/s03-todo-write.md b/docs/zh/s03-todo-write.md
@@ -3,6 +3,8 @@
 `s01 > s02 > [ s03 ] s04 > s05 > s06 | s07 > s08 > s09 > s10 > s11 > s12`
 
 > *"没有计划的 agent 走哪算哪"* -- 先列步骤再动手, 完成率翻倍。
+>
+> **Harness 层**: 规划 -- 让模型不偏航, 但不替它画航线。
 
 ## 问题
 
diff --git a/docs/zh/s04-subagent.md b/docs/zh/s04-subagent.md
@@ -3,6 +3,8 @@
 `s01 > s02 > s03 > [ s04 ] s05 > s06 | s07 > s08 > s09 > s10 > s11 > s12`
 
 > *"大任务拆小, 每个小任务干净的上下文"* -- 子智能体用独立 messages[], 不污染主对话。
+>
+> **Harness 层**: 上下文隔离 -- 守护模型的思维清晰度。
 
 ## 问题
 
diff --git a/docs/zh/s05-skill-loading.md b/docs/zh/s05-skill-loading.md
@@ -3,6 +3,8 @@
 `s01 > s02 > s03 > s04 > [ s05 ] s06 | s07 > s08 > s09 > s10 > s11 > s12`
 
 > *"用到什么知识, 临时加载什么知识"* -- 通过 tool_result 注入, 不塞 system prompt。
+>
+> **Harness 层**: 按需知识 -- 模型开口要时才给的领域专长。
 
 ## 问题
 
diff --git a/docs/zh/s06-context-compact.md b/docs/zh/s06-context-compact.md
@@ -3,6 +3,8 @@
 `s01 > s02 > s03 > s04 > s05 > [ s06 ] | s07 > s08 > s09 > s10 > s11 > s12`
 
 > *"上下文总会满, 要有办法腾地方"* -- 三层压缩策略, 换来无限会话。
+>
+> **Harness 层**: 压缩 -- 干净的记忆, 无限的会话。
 
 ## 问题
 
diff --git a/docs/zh/s07-task-system.md b/docs/zh/s07-task-system.md
@@ -3,6 +3,8 @@
 `s01 > s02 > s03 > s04 > s05 > s06 | [ s07 ] s08 > s09 > s10 > s11 > s12`
 
 > *"大目标要拆成小任务, 排好序, 记在磁盘上"* -- 文件持久化的任务图, 为多 agent 协作打基础。
+>
+> **Harness 层**: 持久化任务 -- 比任何一次对话都长命的目标。
 
 ## 问题
 
diff --git a/docs/zh/s08-background-tasks.md b/docs/zh/s08-background-tasks.md
@@ -3,6 +3,8 @@
 `s01 > s02 > s03 > s04 > s05 > s06 | s07 > [ s08 ] s09 > s10 > s11 > s12`
 
 > *"慢操作丢后台, agent 继续想下一步"* -- 后台线程跑命令, 完成后注入通知。
+>
+> **Harness 层**: 后台执行 -- 模型继续思考, harness 负责等待。
 
 ## 问题
 
diff --git a/docs/zh/s09-agent-teams.md b/docs/zh/s09-agent-teams.md
@@ -3,6 +3,8 @@
 `s01 > s02 > s03 > s04 > s05 > s06 | s07 > s08 > [ s09 ] s10 > s11 > s12`
 
 > *"任务太大一个人干不完, 要能分给队友"* -- 持久化队友 + JSONL 邮箱。
+>
+> **Harness 层**: 团队邮箱 -- 多个模型, 通过文件协调。
 
 ## 问题
 
diff --git a/docs/zh/s10-team-protocols.md b/docs/zh/s10-team-protocols.md
@@ -3,6 +3,8 @@
 `s01 > s02 > s03 > s04 > s05 > s06 | s07 > s08 > s09 > [ s10 ] s11 > s12`
 
 > *"队友之间要有统一的沟通规矩"* -- 一个 request-response 模式驱动所有协商。
+>
+> **Harness 层**: 协议 -- 模型之间的结构化握手。
 
 ## 问题
 
diff --git a/docs/zh/s11-autonomous-agents.md b/docs/zh/s11-autonomous-agents.md
@@ -3,6 +3,8 @@
 `s01 > s02 > s03 > s04 > s05 > s06 | s07 > s08 > s09 > s10 > [ s11 ] s12`
 
 > *"队友自己看看板, 有活就认领"* -- 不需要领导逐个分配, 自组织。
+>
+> **Harness 层**: 自治 -- 模型自己找活干, 无需指派。
 
 ## 问题
 
diff --git a/docs/zh/s12-worktree-task-isolation.md b/docs/zh/s12-worktree-task-isolation.md
diff --git a/skills/agent-builder/references/agent-philosophy.md b/skills/agent-builder/references/agent-philosophy.md

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,5 @@`
`1`	`1`	`#!/usr/bin/env python3`
	`2`	`+# Harness: the loop -- the model's first connection to the real world.`
`2`	`3`	`"""`
`3`	`4`	`s01_agent_loop.py - The Agent Loop`
`4`	`5`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,5 @@`
`1`	`1`	`#!/usr/bin/env python3`
	`2`	`+# Harness: tool dispatch -- expanding what the model can reach.`
`2`	`3`	`"""`
`3`	`4`	`s02_tool_use.py - Tools`
`4`	`5`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,5 @@`
`1`	`1`	`#!/usr/bin/env python3`
	`2`	`+# Harness: planning -- keeping the model on course without scripting the route.`
`2`	`3`	`"""`
`3`	`4`	`s03_todo_write.py - TodoWrite`
`4`	`5`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,5 @@`
`1`	`1`	`#!/usr/bin/env python3`
	`2`	`+# Harness: context isolation -- protecting the model's clarity of thought.`
`2`	`3`	`"""`
`3`	`4`	`s04_subagent.py - Subagents`
`4`	`5`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,5 @@`
`1`	`1`	`#!/usr/bin/env python3`
	`2`	`+# Harness: on-demand knowledge -- domain expertise, loaded when the model asks.`
`2`	`3`	`"""`
`3`	`4`	`s05_skill_loading.py - Skills`
`4`	`5`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,5 @@`
`1`	`1`	`#!/usr/bin/env python3`
	`2`	`+# Harness: compression -- clean memory for infinite sessions.`
`2`	`3`	`"""`
`3`	`4`	`s06_context_compact.py - Compact`
`4`	`5`