上一章我们先把问题摊开了。
结论其实很明确：
Claude Code 之所以会“时灵时不灵”，很多时候不是因为它不够强，而是因为它工作时依赖的那套环境没有搭好。
但如果只停在这里，还不够。
因为你接下来一定会碰到一个更根本的问题：
到底什么叫 Agent？
Prompt 到底算哪一层？
Harness 又到底在工程什么？
这几个词，AI 圈天天有人说。
但说实话，绝大多数时候都说得挺乱的。
一旦这个边界不清楚，后面你做的很多工作都会跑偏。
比如：
- 明明该做工作流设计，你却在疯狂堆 prompt
- 明明该做工具分层，你却在写超长 system prompt
- 明明该补验证闭环，你却总想换个更强模型
- 明明该做任务系统，你却还在指望一句 prompt 管住整个开发过程
所以这一章的目标只有一个：
把 Agent、Prompt、Harness 三者的边界彻底讲清楚。
这不是为了学术定义，而是为了让你后面每一个设计决策都不再歪。
一、先说最重要的一句：Agent 不是外面那层代码
这是我最近几年最想反复强调的一句话。
也是最容易被搞反的一句话。
很多人一提到“Agent”，下意识想到的是：
- 工作流编排
- 多步调用
- 工具链
- 调度器
- 任务系统
- 节点图
- 各种 if-else 自动化逻辑
仿佛只要把 LLM API 调用串起来，加点工具、加点判断、加点分支，这个系统就叫 Agent 了。
但如果我们把概念说严格一点，这个理解其实是反过来的。
更准确的说法应该是：
Agent 是模型本身。
模型看到上下文，理解目标，判断下一步要做什么，决定是不是调用工具，决定什么时候停下来。
这些行为，才是 agent 性质的核心。
而你在外面写的那层代码，真正做的事情是：
- 把工具暴露给模型
- 接住模型的 tool call
- 真的去执行
- 把结果喂回模型
- 管上下文
- 管状态
- 管安全边界
这一层当然非常重要。
但它不是 Agent 本身。
它是 Agent 的 工作环境。
这也是为什么我越来越喜欢把它叫作：
Harness。
如果你接受这条边界，后面很多事会突然变简单。
因为你会开始用一种很不一样的方式来看待问题。
不是：
“我要怎么把 Agent 设计得更聪明？”
而是：
“我要怎么把模型放进一个更像样的工作环境里？”
这是两个完全不同的问题。
二、Prompt 很重要，但 Prompt 不是系统
讲到这里，很多人会立刻反问：
“那 prompt 不重要吗？”
当然重要。
但 prompt 的角色，和很多人直觉里想的不一样。
我更愿意把 prompt 理解成：
你给模型的当前任务说明和行为约束表达。
它很像一次任务 briefing。
比如你可以用 prompt 做这些事：
- 告诉模型目标是什么
- 说明这次任务的限制条件
- 指定这轮工作的优先级
- 给出补充背景
- 要求先 plan 再动手
这些都很有价值。
但 prompt 的问题也很明显：
1. Prompt 是一次性的
这一轮说得再清楚，也不代表下一轮、下一个任务、下一个会话还能自动延续。
2. Prompt 很容易越写越长
很多团队最后都会走到一个非常熟悉的方向：
- 这条规则也写进去
- 那个注意事项也写进去
- 再补一个 workflow
- 再补一个常见坑
- 再补一个边界条件
最后 prompt 变成一份臃肿的“全能神谕”，什么都写了，什么都像重点。
3. Prompt 解决不了结构问题
有些问题不是“说清楚一点”就能解决的。
比如：
- 并行改代码为什么会互相污染
- 长会话为什么会断状态
- 验证为什么总是容易被跳过
- 多个角色之间怎么交接
这些都不是 prompt 的能力边界。
所以我现在对 prompt 的态度很明确：
Prompt 是必要的，但它只是系统的一层，不是系统本身。
它像 briefing，不像组织架构。
它像任务说明，不像工作制度。
它像这次开工前的交代，不像整个工程环境。
这也是为什么你会发现，有些人把 prompt 写得特别厉害，但系统一复杂起来，还是会乱。
因为问题不在“这次说得够不够清楚”，而在：
系统里有没有长期约束、有没有工具边界、有没有记忆机制、有没有验证闭环。
这些东西，已经不是 prompt 能单独扛住的了。
三、Harness 真正在工程什么
如果现在再回头看“工作环境”这个词，你会发现它其实有点太轻了。
因为 Harness 不是简单的“外壳”，更不是“几个辅助脚本”。
它真正工程的，是模型如何：
- 看见世界
- 对世界动手
- 记住自己做过什么
- 跟别的工作流协作
- 在风险边界内工作
- 在长任务里不崩
如果拆开说，我现在会把 Harness 至少分成下面几层。
1. 工具层
解决的是：
模型到底能做什么动作？
例如：
- 读文件
- 写文件
- 改文件
- 跑 bash
- 查网页
- 调 MCP
这层决定的是 手和脚。
2. 规则层
解决的是：
哪些线不能越？
例如：
- 不能跳过验证
- 不能乱改配置绕过检查
- 不能在高风险任务里擅自扩大范围
- 不能无缘无故动无关代码
这层决定的是 边界。
3. 技能层
解决的是：
遇到某类任务时，应该按什么套路做？
例如：
- bugfix workflow
- TDD workflow
- code review checklist
- security review checklist
- strategic compact
这层决定的是 方法论。
4. 任务与状态层
解决的是：
现在到底在做什么、做到了哪、后面还有什么？
例如：
- 任务列表
- 阶段划分
- 状态流转
- 会话摘要
- 交接信息
这层决定的是 连续性。
5. 自动化层
解决的是：
哪些动作不该靠记忆，而该自动发生？
例如：
- 编辑后格式化
- 结束时做审计
- compact 前保存状态
- 长命令提醒后台化
这层决定的是 稳定性。
6. 协作层
解决的是：
多个 agent / 多个会话 / 多个工作流之间怎么不撞？
例如：
- subagent
- background task
- task system
- worktree
- handoff
这层决定的是 扩展性。
7. 验证层
解决的是：
什么叫真的完成？
例如：
- build
- typecheck
- lint
- tests
- review
- security review
这层决定的是 可信度。
所以你现在可以把 Harness 暂时理解成一句话：
Harness 就是把一个会推理的模型，接进真实工程世界的那整套环境设计。
四、为什么把边界搞错，会直接导致错误做法
这一段很重要，因为它决定你后面会不会一直在错误方向上修补系统。
1. 把 Prompt 当系统，你就会不断堆提示词
典型表现：
- 什么都想塞进
CLAUDE.md - 什么都想写成 system prompt
- 规则、知识、流程、口味偏好全堆一起
最后得到一个又长又重、优先级还模糊的上下文怪物。
2. 把 Harness 当 Agent，你就会疯狂做流程编排
典型表现：
- 不信模型自己判断
- 用大量硬编码流程替模型做决策
- 把系统写成一棵流程树
结果就是：
- 系统越来越脆
- 新场景越来越难扩展
- 一切都依赖手工维护
3. 把工具问题当模型问题，你就会老想换模型
典型表现：
- 一跑偏就想换 Opus
- 一验证失败就觉得是推理不够深
- 一长任务断链就怪模型记性差
但其实很多时候更准确的解法是：
- 加 planning 入口
- 补 verify 闭环
- 做 session summary
- 引入 worktree 隔离
- 把规则和技能分层
也就是说：
一旦边界没分清，后面所有补救动作都容易补错层。
这就是为什么这一章必须先讲清楚概念。
五、一个更实用的判断方法：这个问题到底该在哪一层解决？
以后你只要碰到 Claude Code 的问题，可以先用这张“归因表”判断一下。
问题 1：它老是扩大修改范围
优先怀疑：
- planning 不够清晰
- rules 不够强
- 当前上下文里噪声太多
不是先怀疑模型不够强。
问题 2：它昨天查过的东西今天又重查
优先怀疑：
- session summary 不存在
- compact 前没有保存状态
- 长期记忆没设计
不是先怀疑它“失忆”。
问题 3：它总说修好了，但验证不过
优先怀疑：
- verify 不是默认路径
- 没有固定验证顺序
- 缺少 review / quality gate
不是先怀疑它“撒谎”。
问题 4：多个会话一并行，代码就互相污染
优先怀疑：
- 没有 worktree 隔离
- 没有任务边界
- 没有 handoff 机制
不是先怀疑并行本身不行。
问题 5：Claude Code 越用越钝
优先怀疑：
- 上下文预算失控
- MCP 太多
- 常驻知识太重
- 没有及时 compact
不是先怀疑模型突然退化。
这张表的意义就在于：
它逼你先找对层，再动手修。
这本身就是 Harness 工程思维。
六、本章交付：Claude Code 问题归因表
这一章的交付物不是配置文件，而是一张思维工具表。
以后你遇到问题，可以先问自己：
| 现象 | 优先怀疑哪一层 |
|---|---|
| 修改范围失控 | 规划层 / 规则层 / 上下文层 |
| 长会话断链 | 记忆层 / 会话层 / compact 策略 |
| 说完成但没通过 | 验证层 / review 层 |
| 并行互相污染 | 任务层 / 工作区层 / 协作层 |
| 越用越钝 | context budget / MCP / 常驻知识设计 |
| 什么都要重新说 | rules / skills / commands 分层缺失 |
这张表的作用很简单：
别一出问题就先怪模型，先看是不是工作环境没搭好。
七、本章小结
这一章我们做的事，其实非常朴素：
我们没有讨论功能，也没有开始写配置。
我们只是先把三件事拆开：
- Agent 是什么
- Prompt 是什么
- Harness 是什么
最后得到的结论很重要：
Agent 是模型本身。 Prompt 是一次任务说明。 Harness 是让模型长期稳定工作的环境。
一旦这三个边界分清，后面很多设计会变得非常顺：
- 为什么要分 rules / skills / commands
- 为什么 planning 要前置
- 为什么 hooks 值钱
- 为什么 memory 和 session summary 必须存在
- 为什么验证不能只靠“顺手跑一下”
下一章开始，我们就不再停留在概念边界，而是正式往前走一步：
Claude Code 的最小内核：Loop、Tools 与 Context。
因为要搭系统，先得知道这个系统最底层到底是怎么动起来的。
