Logo LLM Wiki
Back to Summary

深度解析Claude Code在Prompt_Context_Harness的设计与实践

title 深度解析 Claude Code 在 Prompt / Context / Harness 的设计与实践
type summary
category tech
tags claude-codeprompt-engineeringcontext-engineeringharness-engineeringagentai
created 2026-04-20
source_file 深度解析 Claude Code 在 Prompt _ Context _ Harness 的设计与实践.md

深度解析 Claude Code 在 Prompt / Context / Harness 的设计与实践

公众号: 阿里云开发者 发布时间: 2026-04-20 08:32 原文链接: https://mp.weixin.qq.com/s/YgGW92VBP8s846yzIxjVWQ

核心观点

Claude Code 的卓越表现不仅源于 Claude Opus 4.6 基座模型本身的强大，更得益于其在 Prompt Engineering、Context Engineering 和 Harness Engineering 三个维度上的顶级工程设计。这三大关键阶段分别聚焦于"如何说"、"让AI看什么"以及"构建怎样的运行环境"，层层递进，共同致力于提升大模型在复杂任务中的可靠性与可控性。

要构建一个 95 分的 Agent 系统：直接通过 Prompt Engineering 只能实现 70+ 分，通过 Context Engineering 可以提升到 80~85 分，最后再通过 Harness Engineering 的约束，才能将其提升到 90~95 分。

Prompt Engineering：静态与动态信息的组装

System Prompt 的动态组装过程

Claude Code 的 System Prompt 是一个多层级、动态组装的过程，由多个文件协同工作，最终拼装成一个字符串数组发送给 Claude API。

组装流程：

  1. QueryEngine 发起请求：QueryEngine.ask() → fetchSystemPromptParts() → buildEffectiveSystemPrompt() → query()
  2. 获取三大组件：
    • defaultSystemPrompt：调用 constants/prompts.ts 中的 getSystemPrompt() 构建默认 prompt
    • systemContext：调用 context.ts 获取 Git 状态信息
    • userContext：获取 CLAUDE.md 内容 + 当前日期
  3. 组装默认 System Prompt：分为静态部分和动态部分
  4. 优先级决策：按优先级选择最终 prompt（overrideSystemPrompt > Coordinator prompt > Agent prompt > customSystemPrompt > defaultSystemPrompt）
  5. 注入上下文信息：追加 Git 状态，在用户消息列表最前面插入 CLAUDE.md 和日期
  6. 缓存分块：拆分成缓存友好的块，显式走 KV Cache

静态 Prompt 部分

包含 7 大模块，每个用户都会有这些静态 Prompt：

  1. 身份介绍：告诉 Claude 它是谁，应该做什么
  2. 系统行为规则：输出规则、权限模式、安全防护等
  3. 任务执行指南：编码风格、避免过度工程、不添加未要求的功能
  4. 操作安全守则：考虑可逆性和影响范围，不要随便删东西、推代码
  5. 工具使用指南：优先使用专用工具（Read、Edit、Write）而不是 Bash 命令
  6. 语气和风格：简洁、不用 emoji、引用代码时带行号
  7. 输出效率：要求 Claude 简洁输出，直奔主题

动态 Prompt 部分

在静态 Prompt 和动态 Prompt 之间有一个 __SYSTEM_PROMPT_DYNAMIC_BOUNDARY__ 边界，包含 11 个模块：

  1. 会话特定指导：根据当前会话启用的工具动态生成
  2. 自动记忆：加载用户的持久化记忆文件（MEMORY.md 等）
  3. 环境信息：工作目录、git 仓库、平台、shell、OS 版本、模型信息等
  4. 语言偏好：如果用户设置了语言偏好
  5. 输出风格：如果用户配置了自定义输出风格
  6. MCP 服务器指令：如果有连接的 MCP 服务器提供了使用说明
  7. 临时文件目录：如果启用了 Scratchpad 功能
  8. 函数结果清理：Old tool results 会自动清理
  9. 工具结果总结提示：提醒写下重要信息
  10. 长度锚点：内部版本的长度限制
  11. Token 预算：用户指定 token 目标时显示

给子 Agent 分配任务的 Prompt

Multi-Agent 架构中，Agent 之间的通信是一个难题。Claude Code 在 AgentTool 里的 Prompt 教主 Agent 怎么使用 AgentTool 来派遣子 Agent，包括：

  • 有哪些下属（Agent 列表）
  • 什么时候该自己干、什么时候该委派（When NOT to use）
  • 怎么写工作说明（Writing the prompt）
  • 反模式警告

Context Engineering：引导、压缩和记忆

CLAUDE.md 项目说明

CLAUDE.md 是给 Claude Code 写的"项目说明书"和"行为规范"，内容会被注入到 System Prompt 中，作为对话的第一条消息，用 标签包裹，优先级很高。

四种路径：

  • 个人通用偏好类：~/.claude/CLAUDE.md，全局人设，跨项目生效
  • 项目共享规范：项目根目录下的 CLAUDE.md，团队协作基石，提交到 Git
  • 个人私有指令：CLAUDE.local.md，不该公开但必需的上下文，不提交到 Git
  • 按文件类型分类的规则：.claude/rules/*.md 目录，按文件类型或业务领域进行拆分

三层渐进式压缩体系

按照激进程度递增，在"保留关键信息"与"节省 token 成本"之间找到平衡：

Layer 1: MicroCompact（微压缩）

  • 无 LLM 调用，纯规则驱动，极致轻量
  • 定义可压缩工具白名单（Bash、Read、Grep、Glob 等）
  • 对涉及核心状态变更的操作（Edit、Write）完整保留
  • 图片内容统一按 2000 token 估算
  • 两条执行路径：基于时间的路径（超时间阈值的旧消息截断）和基于缓存的路径（KV Cache 边界外压缩）

Layer 2: Session Memory Compact（会话记忆压缩）

  • 基于已有会话记忆进行替换，零额外推理成本
  • 触发门槛：Token 数 ≥ 10,000 且文本消息条数 ≥ 5 条
  • 压缩上限：单次最大压缩 40,000 token
  • 将符合条件的旧消息替换为会话记忆摘要，保留最近几轮消息

Layer 3: Full LLM Compact（完全压缩）

  • 调用 LLM 生成结构化摘要，精度最高但成本也最高
  • 强制模型遵循严格的 9 段式结构化模板：Primary Request and Intent、Key Technical Concepts、Files and Code Sections、Errors and fixes、Problem Solving、All user messages、Pending Tasks、Current Work、Optional Next Step
  • 隐式思维链（Implicit CoT）优化：要求模型在 标签内进行全面推理，然后在 标签中输出结果，程序剥离 块，只保留纯净摘要
  • 反工具调用保护：严厉禁止模型在压缩过程中调用任何工具

自动压缩触发机制

设定安全缓冲水位线（AUTOCOMPACT_BUFFER_TOKENS = 13,000），当上下文窗口剩余空间低于这个阈值时，自动介入判断。分级回退策略：

  • 首选快速路径：首先尝试 Session Memory Compact
  • 降级重型路径：如果 SM Compact 不满足条件或压缩后仍无法满足要求，回退到 Full LLM Compact

Memdir 结构化记忆系统

Memdir 将记忆明确拆解为四种核心类型：

  • User（用户级）：记录用户的个人偏好、操作习惯及特定指令风格
  • Feedback（反馈级）：存储模型行为的修正记录和历史纠错案例
  • Project（项目级）：固化项目层面的技术选型、架构决策和约束条件
  • Reference（参考级）：沉淀通用的文档片段和代码模式

记忆加载与检索

  • loadMemoryPrompt 作为记忆加载的主入口，扫描记忆目录按类型归类整理，应用预算限制，动态裁剪记忆内容
  • LLM-in-the-loop 的检索策略：使用 Sonnet 模型充当"图书管理员"，对候选记忆进行语义相关性判断，强制约束只返回最多 5 条最相关的记忆

Harness Engineering：环境、约束与控制

Harness Engineering 是在大模型之外构建一套外部的运行环境与约束机制，通过接口（Interface）、钩子（Hooks）、护栏（Guardrails）等手段，约束、引导、检验、评估 Agent 的行为。

系统级强提醒引导

System Reminder 动态注入机制

  • wrapInSystemReminder 函数将所有需要注入系统的元信息统一包裹在 ... 标签中
  • 应用场景：用户上下文初始化（CLAUDE.md、当前日期）、工具结果反馈、钩子反馈、周期性任务与能力描述
  • 集成到消息规范化流程 normalizeMessagesForAPI 中，标准化、可复用

六大系统内置 Agent Tool

1. General-Purpose Agent：万能打工人

  • 工具权限：tools: ['*']，拥有所有工具的使用权限
  • 不指定模型：使用系统默认的子 Agent 模型
  • System Prompt 简洁：把活干完，别镀金，也别干一半就跑
  • 典型使用场景：搜索关键词、跨文件调查、执行多步骤的研究任务

2. Explore Agent：代码库侦察兵

  • 速度优先的只读搜索专家
  • 严格只读：禁止创建、修改、删除任何文件
  • 使用 Haiku 模型：小、快、便宜
  • 不加载 CLAUDE.md：omitClaudeMd: true
  • 强调效率：尽可能多地并行调用工具
  • 可指定搜索的"彻底程度"：quick、medium、very thorough

3. Plan Agent：软件架构师

  • 制定实施方案
  • 严格只读：不能修改任何文件
  • 继承父模型：用和主 Agent 一样的聪明模型
  • 结构化输出：计划、步骤、关键文件、权衡
  • 工作流程：理解需求 → 深入探索代码库 → 设计解决方案 → 详细规划

4. Verification Agent：质量检验官

最精妙、提示词最长的一个，体现 Harness Engineering 精髓。

五种设计哲学：

  1. 红蓝对抗：你的工作不是确认代码能跑——而是想办法把它搞崩
  2. 不要随便给 PASS：避免验证逃避（Verification Avoidance）和被前 80% 迷惑（Seduced by the First 80%）
  3. 严格的权限控制：只能看，不能改。唯一例外是可以往 /tmp 写临时测试脚本
  4. 按变更类型分类的验证策略：前端变更、后端/API、CLI/脚本、基础设施、Bug 修复、数据库迁移、重构、移动端
  5. 反偷懒话术：拆穿 AI 常见的自我开脱话术（代码看起来是对的、实现者的测试已经通过了、这大概没问题等）

5. Claude Code Guide Agent：Claude Code 使用说明书

  • 知识领域：Claude Code CLI、Claude Agent SDK、Claude API
  • 使用 Haiku 模型
  • 权限模式 dontAsk：不需要向用户请求权限
  • 动态上下文注入：System Prompt 会动态包含自定义技能、Agent、MCP 服务器配置和用户设置

6. Statusline Setup Agent：状态栏安装

  • 只有两个工具：Read 和 Edit
  • 使用 Sonnet 模型
  • 橙色标识：表示"装修中"
  • 知道怎么转换 PS1：能把 Shell 的 PS1 变量转成 Claude Code 的 statusLine 配置

7. Fork Sub Agent：隐藏的第七人

  • 主 Agent 的"分身"，继承完整对话历史
  • 共享 Prompt Cache：fork 出来的子进程和父进程共享 prompt cache
  • 严格的输出格式：以 Scope: 开头，报告控制在 500 字以内
  • 防止递归 fork：通过检测 标签阻止子进程再 fork
  • Worktree 隔离：可以在独立的 git worktree 中运行

设计思考：

  • Token 成本：Explore、Guide 都用 Haiku，比 Opus 便宜很多
  • 安全隔离：通过禁用工具实现"最小权限原则"
  • 上下文管理：子 Agent 的工具输出不会污染主 Agent 的上下文窗口
  • 并行效率：Verification Agent 在后台运行，不阻塞用户

精细化的安全体系

Permission Engine：规则的精细化权限控制

  • 定义清晰的"三行为模型"：Allow（自动允许）、Deny（自动拒绝）、Ask（请求确认）
  • 多源规则配置，优先级覆盖机制：settings.json → CLI 参数 → 命令行规则 → session 规则

Sandbox Isolation：操作系统原型的沙箱隔离

  • 基于 bubblewrap (bwrap) 构建轻量级沙箱
  • 文件系统隔离：只读挂载根目录和白名单目录机制
  • 网络与进程隔离：独立的 Network 和 PID 命名空间
  • 用户权限降级：强制以非 root 用户身份运行
  • 智能决策逻辑：检测命令特征，按需隔离

异步生成器驱动的主循环

主循环被重构为一个 async function*（异步生成器），带来四个维度的质的飞跃：

  1. 流式处理与实时反馈：通过 yield 关键字，逐步推送中间状态
  2. 协作式控制：调用者拥有对执行流的"暂停/恢复"权
  3. 优雅的取消机制：支持 return() 方法，优雅地终止当前迭代
  4. 有状态的上下文维持：在多次 yield 之间维护局部变量和运行时状态

六步 Pipeline：

  1. 消息预处理 Pipeline：对输入消息进行清洗、格式化及元数据注入
  2. 大模型 API 调用
  3. 响应解析与规划
  4. 工具执行与安全校验
  5. 结果产出：通过 yield 抛给上层调用者
  6. 终止条件检查

错误重试与恢复策略：

  • 上下文超长保护：启动三级压缩机制
  • 输出截断自动续写：最多 3 次自动重试，发送 continue 指令
  • 网络波动平滑处理：指数退避重试算法

可编程的钩子拦截机制

在 hooks.ts 中实现了一个庞大的钩子系统，覆盖 20+ 种关键事件类型：

  • 工具生命周期：PreToolUse、PostToolUse、ToolError
  • 会话生命周期：SessionStart、SessionEnd、SessionPause、SessionResume
  • 消息生命周期：PreSampling、PostSampling、UserPromptSubmit
  • 文件操作：PreFileEdit、PostFileEdit、PreFileWrite、PostFileWrite

钩子的强大之处：

  • 阻断执行：返回 { "blocked": true, "reason": "..." } 可直接熔断高危操作
  • 动态篡改：通过 { "input": {...} } 或 { "output": {...} } 实时修正工具的输入参数或清洗输出结果
  • 反馈注入：利用 { "message": "..." } 向对话流中插入系统提示或用户通知
  • 超时保护：全局常量 TOOL_HOOK_EXECUTION_TIMEOUT_MS（默认 10 分钟），超时强制终止

有趣的彩蛋

Caffeinate——给电脑灌咖啡，防止休眠

  • 利用 macOS 内置命令 caffeinate 阻止电脑休眠
  • 只阻止空闲休眠，5 分钟后自动退出
  • 每 4 分钟重启一次 caffeinate 进程，确保持续生效

Anti-Distillation：反蒸馏，防止模型被"偷学"

  • 假的工具注入：设置 anti_distillation: ['fake_tools']，在数据里投毒
  • 输出格式的蒸馏抵抗：精简输出模式，隐藏详细工具调用链，丢弃 Thinking Content

Undercover Mode：卧底模式

  • Anthropic 的内部员工为公共/开源项目贡献代码时，隐藏 AI 身份
  • 禁止出现"Claude Code"、"Co-Authored-By"、任何模型代号

Dogfooding 内部吃狗粮模式

  • 通过 process.env.USER_TYPE === 'ant' 区分内部和外部用户
  • "ant" 是 Anthropic 的缩写，内部员工使用各种内部功能

用户情绪辱骂处理：AI 也知道你在骂它

  • 用正则表达式匹配用户输入中的负面关键词
  • 检测到用户在骂人后，弹出反馈调查，邀请分享对话记录

荒诞的加载动词：让等待变得有趣

  • 一百多个疯狂的动词列表中随机选择：Boondoggling（做无意义的工作）、Flibbertigibbeting（话唠）、Discombobulating（把人搞迷糊）、Lollygagging（磨洋工）、Canoodling（卿卿我我）、Prestidigitating（变魔术）等

Buddy System：养个电子宠物

  • 用 /buddy 命令"孵化"一个专属电子宠物
  • 十几种宠物：猫、鸭子、企鹅、水蜥、仙人掌、蘑菇、chonk（胖墩）
  • 由用户 ID 通过 Mulberry32 伪随机数生成器确定性生成，同一个用户永远得到同一只宠物
  • 稀有度系统：common（60%）、uncommon（25%）、rare（10%）、epic（4%）、legendary（1%）
  • 五大属性：DEBUGGING（调试能力）、PATIENCE（耐心）、CHAOS（混乱值）、WISDOM（智慧）、SNARK（毒舌）
  • 骨骼（Bones）和灵魂（Soul）：骨骼确定性生成不存储，灵魂由 AI 模型生成存储在配置中

关键概念

关联页面

代码块

QueryEngine 发起请求

javascript 
QueryEngine.ask()
  → fetchSystemPromptParts()     // 获取默认 prompt + 用户上下文 + 系统上下文
  → buildEffectiveSystemPrompt() // 根据优先级选择最终 prompt
  → query()                      // 发送到 API

System Prompt 数组结构

javascript 
返回的数组结构：
[
  // ===== 静态部分（可全局缓存）=====
  getSimpleIntroSection(),        // 身份介绍
  getSimpleSystemSection(),       // 系统行为规则
  getSimpleDoingTasksSection(),   // 任务执行指南
  getActionsSection(),            // 操作安全守则
  getUsingYourToolsSection(),     // 工具使用指南
  getSimpleToneAndStyleSection(), // 语气和风格
  getOutputEfficiencySection(),   // 输出效率要求

  // ===== 边界标记 =====
  "__SYSTEM_PROMPT_DYNAMIC_BOUNDARY__",  // 缓存边界线

  // ===== 动态部分（每个用户/会话不同）=====
  session_guidance,          // 会话特定指导
  memory,                    // 自动记忆
  ant_model_override,        // 内部模型覆盖
  env_info_simple,           // 环境信息
  language,                  // 语言偏好
  output_style,              // 输出风格
  mcp_instructions,          // MCP 服务器指令
  scratchpad,                // 临时文件目录
  frc,                       // 函数结果清理
  summarize_tool_results,    // 工具结果总结提示
  numeric_length_anchors,    // 长度锚点（内部版）
  token_budget,              // Token 预算
  brief,                     // KAIROS 简报
]

优先级决策

markdown 
优先级从高到低：
1. overrideSystemPrompt  — 强制覆盖（如循环模式下使用）→ 直接返回，忽略一切
2. Coordinator prompt    — 协调器模式激活时的专用 prompt
3. Agent prompt          — 用户定义的 Agent 的 prompt（替换默认）
4. customSystemPrompt    — 通过 --system-prompt 参数传入的自定义 prompt
5. defaultSystemPrompt   — 上面第3步构建的标准 prompt
另外：appendSystemPrompt 始终追加到最后（除非 override 模式）

缓存分块

javascript 
打包后的结构：
[
  { text: "x-anthropic-billing-header: ...", cacheScope: null },    // 归属头（永不缓存）
  { text: "You are Claude Code...",          cacheScope: 'org' },   // 前缀
  { text: "静态内容（边界前）",                cacheScope: 'global' }, // 全局缓存
  { text: "动态内容（边界后）",                cacheScope: null },    // 不缓存
]

Full LLM Compact 结构化模板

markdown 
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
← Back to Summary