Claude Code 设计哲学深度解析：从 Prompt 到 Harness 的 Agent 工程实践

🔍 Claude Code 设计哲学深度解析：从 Prompt 到 Harness 的 Agent 工程实践

📌 本文基于对 Claude Code 开源实现的技术分析，聚焦于 Prompt Engineering / Context Engineering / Harness Engineering 三大维度，提炼可复用的 Agent 系统设计方法论。

---

🎯 为什么分析 Claude Code？

Claude Code 作为一个 AI Coding Agent，在完成长程、高复杂度任务时表现令人惊艳。这背后除了 Claude Opus 4.6 基座模型的强大，更关键的是其工程设计的顶级水准：

同样的 Claude API → 直接使用 vs 通过 Claude Code 调用
                    ↓
              效果差距明显

这说明：模型能力只是基础，真正决定 Agent 上限的是系统设计。

本文从三个核心维度拆解 Claude Code 的设计思路，希望能为你构建自己的 Agent 系统提供参考。

---

🧱 一、Prompt Engineering：从"写提示词"到"组装提示词"

1.1 核心认知升级

❌ 误区：写好一段 System Prompt = 做好 Prompt Engineering

✅ 真相：真正的工程体现在动态组装机制------根据身份、任务、环境、约束实时拼接 Prompt

Claude Code 的 Prompt 组装像搭积木：

[静态底座] + [动态积木块] + [边界标记] + [上下文注入] = 最终 System Prompt

1.2 六步组装流程

QueryEngine.ask()
  → fetchSystemPromptParts()     // 并行获取三大组件
  → buildEffectiveSystemPrompt() // 优先级决策
  → query()                      // 发送请求

三大组件：

组件	来源	作用
defaultSystemPrompt	constants/prompts.ts	基础行为规则
systemContext	context.ts	Git 状态等系统信息
userContext	context.ts	CLAUDE.md + 日期

1.3 静态 Prompt 的 7 个核心模块

1️⃣ 身份介绍：你是做什么的 + 安全边界
2️⃣ 系统行为：输出规则/权限模式/安全防护
3️⃣ 任务执行：编码风格/避免过度工程/安全编码
4️⃣ 操作安全：可逆性评估 + 高风险操作确认机制
5️⃣ 工具使用：优先专用工具，而非 Bash 命令
6️⃣ 语气风格：简洁/无 emoji/带行号引用
7️⃣ 输出效率：直奔主题，拒绝废话

🔑 关键细节：

• 内部员工（USER_TYPE === 'ant'）有额外指令
• 输出风格支持用户自定义覆盖
• 所有规则都服务于"让模型行为可预测"

1.4 动态 Prompt 的灵活注入

通过 __SYSTEM_PROMPT_DYNAMIC_BOUNDARY__ 分隔，动态部分包括：

• 会话特定指导（工具启用状态）
• 用户记忆（MEMORY.md）
• 环境信息（平台/模型/路径）
• 语言偏好 & 输出风格
• MCP 服务器指令
• Token 预算控制（支持 "+500k" 等指令）

1.5 缓存友好设计

// splitSysPromptPrefix() 的缓存策略
[
  { text: "静态内容", cacheScope: 'global' },  // ✅ 全局缓存
  { text: "动态内容", cacheScope: null },      // ❌ 不缓存
]

💡 显式标记 KV Cache 边界，显著提升缓存命中率，降低 API 成本

---

🧠 二、Context Engineering：让 Agent"记得住、看得准"

2.1 CLAUDE.md：项目级的"行为规范"

📁 四种配置路径，覆盖不同场景：
├─ ~/.claude/CLAUDE.md          # 个人全局偏好
├─ /project/CLAUDE.md           # 项目共享规范（提交 Git）
├─ /project/CLAUDE.local.md     # 个人私有指令（不提交）
└─ /project/.claude/rules/*.md  # 按文件类型细分规则

🎯 设计启示：

Agent 的配置文件设计，必须与产品定位深度绑定。

Claude Code（Coding Agent）→ 关注项目规范

OpenClaw（个人助理）→ 关注用户画像+记忆+工具

2.2 三层渐进式压缩体系

层级	名称	触发条件	核心策略	成本
L1	MicroCompact	工具输出过长	规则截断 + 白名单	⭐ 极低
L2	Session Memory	Token≥10k + 消息≥5	复用已有摘要	⭐⭐ 低
L3	Full LLM Compact	前两层不足	LLM 生成结构化摘要	⭐⭐⭐ 高

🔧 L3 的 9 段式摘要模板（关键！）

1. Primary Request and Intent
2. Key Technical Concepts  
3. Files and Code Sections
4. Errors and fixes
5. Problem Solving
6. All user messages
7. Pending Tasks
8. Current Work
9. Optional Next Step

🛡️ 两个防幻觉技巧：

1. 隐式 CoT ：要求先在 <analysis> 中推理，再输出 <summary>（系统自动剥离 analysis）
2. 反工具调用：明确禁止压缩时调用任何工具，防止副作用

2.3 Memdir：结构化记忆系统

🗂️ 四类记忆，各司其职：
├─ User      # 用户偏好/习惯
├─ Feedback  # 纠错记录/避坑指南  
├─ Project   # 技术选型/架构决策
└─ Reference # 通用文档/代码模式

加载策略：

loadMemoryPrompt()
  → 扫描记忆目录 → 按类型归类 → 应用预算裁剪 → 格式化注入

智能检索 ：当记忆库过大时，用 Sonnet 模型做语义相关性判断，最多返回 5 条，平衡召回率与成本。

---

⚙️ 三、Harness Engineering：让 Agent"可控地做"

🎯 Harness = 马具。核心使命：确保模型可控地执行复杂任务

3.1 System Reminder：动态引导机制

// 所有系统注入信息统一包裹
<system-reminder>
  CLAUDE.md 内容 / 日期 / 工具结果 / Hook 反馈...
</system-reminder>

✅ 价值：

• 显式隔离"用户输入"与"系统指令"，避免模型混淆
• 标准化注入流程，降低格式混乱导致的幻觉风险
• 支持全生命周期动态挂载（初始化/工具反馈/周期任务）

3.2 六大内置 Agent：分工协作的"特种部队"

Agent	核心职责	关键设计	适用场景
General	万能执行者	tools: ['*'] + 简洁 Prompt	多步骤研究任务
Explore	代码侦察兵	只读 + Haiku 模型 + 并行搜索	快速代码探索
Plan	软件架构师	继承主模型 + 结构化输出	大工程方案设计
Verification	质量检验官	🔴 红蓝对抗思维 + 严格权限	代码验证/防偷懒
Guide	使用说明书	查官方文档 + Haiku 模型	回答"怎么用"问题
Statusline	终端配置员	仅 Read/Edit + Sonnet 模型	状态栏个性化

🎯 Verification Agent 的 5 大设计哲学（精华！）

1️⃣ 红蓝对抗：你的任务不是确认"能跑"，而是想办法"搞崩它"
2️⃣ 拒绝敷衍：禁止"看起来对"、"大概没问题"等模糊判断
3️⃣ 权限最小化：只能读，不能改（/tmp 除外）
4️⃣ 分类验证策略：前端/后端/CLI/数据库...各有专用检查流程
5️⃣ 反话术库：预设 10+ 种 AI 偷懒话术，逐一拆穿

3.3 安全体系：规则 + 沙箱双重防护

🔐 Permission Engine（规则层）
├─ Allow：低风险操作自动放行
├─ Deny：高危操作直接阻断  
└─ Ask：中等风险请求用户确认
    ↓
📦 Sandbox Isolation（系统层，Linux）
├─ 文件系统：只读挂载 + 白名单
├─ 网络/进程：独立命名空间
└─ 权限：非 root 运行

3.4 异步生成器主循环：可观测、可干预、高可用

async function* queryLoop() {
  while(true) {
    // 1. 消息预处理 → 2. LLM 调用 → 3. 响应解析
    // 4. 工具执行+安全校验 → 5. yield 中间状态 → 6. 终止检查
    
    // 内置错误恢复：
    // - prompt-too-long → 自动触发三级压缩
    // - max-output-tokens → 自动 continue 续写
    // - 网络波动 → 指数退避重试
  }
}

✨ 四大优势：

1. 流式反馈：实时推送"正在思考..."等状态
2. 协作控制：外部可随时暂停/恢复执行流
3. 优雅取消：收到信号后清理资源，避免状态不一致
4. 状态维持：yield 间完美保持局部变量

3.5 钩子（Hook）系统：可编程的"干预点"

🪝 覆盖 20+ 关键事件：
├─ 工具生命周期：PreToolUse / PostToolUse / ToolError
├─ 会话生命周期：SessionStart / SessionPause / SessionEnd
├─ 消息生命周期：PreSampling / UserPromptSubmit
└─ 文件操作：PreFileEdit / PostFileWrite / ...

Hook 的三种干预能力：

// 1. 阻断高危操作
{ "blocked": true, "reason": "检测到敏感路径" }

// 2. 动态修正参数/结果
{ "input": { "path": "/safe/path" } }

// 3. 注入反馈消息
{ "message": "⚠️ 该操作需要二次确认" }

⚠️ 安全兜底：全局超时控制（默认 10 分钟），防止外部脚本拖垮主进程

---

🎁 彩蛋时间：严肃工程中的"人情味"

Claude Code 在专业之外，还藏着一堆有趣设计：

彩蛋	实现思路	设计价值
☕ Caffeinate	macOS 防休眠命令 + 5 分钟自动退出	保障长任务不中断，且安全可回收
🎭 Anti-Distillation	注入假工具定义 + 精简输出模式	防止模型行为被"蒸馏"复制
🕵️ Undercover Mode	commit 时自动隐藏 AI 身份	满足内部员工贡献开源项目需求
😤 情绪检测	正则匹配负面关键词 + 反馈邀请	把用户挫败转化为产品改进机会
🎪 荒诞加载词	100+ 随机动词（Hullaballooing...）	让等待过程变得有趣
🐾 Buddy System	UserID 确定性生成电子宠物 + 稀有度系统	增强用户粘性与情感连接

💡 这些"非必要"功能，恰恰体现了 技术产品的人文温度------让用户在高效协作中感受到乐趣。

---

📋 总结：构建 95 分 Agent 的方法论

🎯 目标：让 Agent 稳定、高效、可控地完成复杂长程任务

🧱 三层架构，层层递进：

┌─────────────────────────────┐
│  Prompt Engineering (70分)   │
│  • 模块化组装 + 动态注入      │
│  • 缓存友好 + 优先级决策      │
└─────────┬───────────────────┘
          ▼
┌─────────────────────────────┐
│  Context Engineering (+15分) │
│  • CLAUDE.md 分级配置         │
│  • 三层压缩 + 结构化记忆      │
└─────────┬───────────────────┘
          ▼
┌─────────────────────────────┐
│  Harness Engineering (+10分) │
│  • system-reminder 引导机制  │
│  • 多 Agent 分工 + 安全体系  │
│  • 异步生成器 + Hook 干预    │
└─────────────────────────────┘

🔑 三个核心启示：

1. 从"写提示词"到"设计组装机制"

   Prompt 工程的核心不是文案，而是如何根据上下文动态构建最优指令

2. 上下文管理是长程任务的命门

   没有压缩和记忆，再强的模型也会在长对话中"失忆"。分层压缩 + 结构化记忆是必选项

3. Harness 决定 Agent 的生产级可用性

   安全校验、钩子干预、错误恢复...这些"看不见"的工程细节，才是 Demo 与产品的分水岭

---

🚀 最后思考 ：

在"用大模型"到"用好大模型"的转型期，工程能力的重要性正在超越模型本身 。

Claude Code 的实践告诉我们：一个优秀的 Agent 系统，是 Prompt 设计、上下文管理、运行约束三者协同的产物。

希望这些方法论，能帮你构建出属于自己的"95 分 Agent"。

---

https://mp.weixin.qq.com/s/YgGW92VBP8s846yzIxjVWQ
本文分析基于公开技术信息，仅供学习交流。如有疏漏，欢迎指正讨论。 🙏