Prompt工程与系统提示词的核心概念与编写技巧

系统提示词是AI应用的灵魂。它决定了AI的行为模式，也从根本上划定了响应质量的上限。这一篇，我们来拆解一下Claude Code在系统提示词这一个环节上，具体是怎么设计、怎么构建的。有些人觉得写提示词就是“写一段话告诉AI做什么”，但到了工程化层面，事情要复杂得多。

先说一个核心结论：一套高效的提示词系统，不是一个文本文件，而是一个完整的优先级管理、动态注入和上下文感知的架构。

1. 系统提示词架构

从代码实现层面来看，Claude Code 的提示词管理做得非常精细。它定义了一个明确的优先级系统，具体分为5层。

1.1 优先级系统

这套优先级设定的逻辑很简单：越定制化的指令，拥有越高的决定权。代码的实现是这样的：

// utils/systemPrompt.ts
export function buildEffectiveSystemPrompt({
  mainThreadAgentDefinition,
  toolUseContext,
  customSystemPrompt,
  defaultSystemPrompt,
  appendSystemPrompt,
  overrideSystemPrompt,
}: SystemPromptConfig): SystemPrompt {
  // 优先级1: Override (最高)
  if (overrideSystemPrompt) {
    return asSystemPrompt([overrideSystemPrompt])
  }
  // 优先级2: Coordinator (多Agent)
  if (toolUseContext.coordinatorSystemPrompt) {
    return toolUseContext.coordinatorSystemPrompt
  }
  // 优先级3: Agent Definition
  if (mainThreadAgentDefinition?.systemPrompt) {
    return mainThreadAgentDefinition.systemPrompt
  }
  // 优先级4: Custom
  if (customSystemPrompt) {
    return asSystemPrompt([customSystemPrompt, ...(appendSystemPrompt ?? [])])
  }
  // 优先级5: Default (最低)
  return asSystemPrompt([defaultSystemPrompt, ...(appendSystemPrompt ?? [])])
}

从这段逻辑可以直观看到：
Override 排在第一位，这是最高级别的强制覆盖，适用于紧急干预或特殊任务。
Coordinator 排第二，主要用于多智能体协作场景，需要统一调度。
Agent Definition 排第三，这是每个智能体自身携带的定义。
Custom 排第四，是用户或系统提供的定制化内容。
Default 排最后，兜底使用通用策略。

这套机制确保在任何条件下，AI都不会出现“无指令可循”的真空状态。

1.2 提示词组成

一个完整的系统提示词，并不是简单的“一堆文字”，它被拆分为五个核心模块：

系统提示词结构
├── 基础身份 (Identity)
│   ├── 角色定义
│   ├── 能力描述
│   └── 工作目录信息
│
├── 工具说明 (Tools)
│   ├── 可用工具列表
│   ├── 工具描述
│   └── 使用示例
│
├── 规则约束 (Rules)
│   ├── 行为规则
│   ├── 禁止事项
│   └── 最佳实践
│
├── 环境信息 (Context)
│   ├── Git状态
│   ├── 项目结构
│   └── 依赖信息
│
└── 动态注入 (Dynamic)
    ├── 内存内容
    ├── 会话状态
    └── 用户偏好

Identity 告诉AI“你是谁”，Tools 告诉AI“你能用什么”，Rules 划定行为边界，Context 提供当前项目的土壤和环境，Dynamic 则根据场景实时注入额外信息。这五个模块的组合，清晰定义了AI在每一个特定会话中的完整画像。

2. 工具提示词生成

工具描述是所有提示词中最容易被忽略，却最容易出问题的环节。描述不清，AI要么不会用工具，要么用错工具。

2.1 工具描述构建

这里采取的方案是“逐项生成描述”。每个工具的描述至少包含以下几个维度：

// 为每个工具生成 AI 可理解的描述
async function buildToolDescription(
  tool: Tool,
  options: ToolDescriptionOptions
): Promise {
  // 1. 基础信息
  let desc = `## ${tool.name}`

  // 2. 工具用途
  const purpose = await getToolPurpose(tool)
  desc += `Purpose: ${purpose}`

  // 3. 输入参数
  desc += `### Input Parameters`
  desc += formatSchemaAsMarkdown(tool.inputSchema)

  // 4. 使用示例
  if (options.includeExamples) {
    desc += `### Examples`
    desc += await generateExamples(tool)
  }

  // 5. 注意事项
  const notes = getToolNotes(tool)
  if (notes.length > 0) {
    desc += `### Notes`
    notes.forEach(note => desc += `- ${note}`)
  }

  return desc
}

关键点在于：
用途要简明扼要，让AI一眼知道这个工具是干什么的。
输入参数必须严格格式化，避免歧义。
示例是让AI理解工具使用场景的最佳手段。
注意事项则是“雷区”提醒，避免误操作。

2.2 Schema 格式化

更进一步，工具的参数Schema会被转为清晰的Markdown格式：

// 将 Zod Schema 转换为 Markdown
function formatSchemaAsMarkdown(schema: z.ZodType): string {
  const shape = getSchemaShape(schema)

  return Object.entries(shape).map(([key, field]) => {
    const type = getZodType(field)
    const required = !field.isOptional()
    const description = field.description ?? "'

    return `- \`${key}\` (${type}${required ? ', required' : ''}): ${description}`
  }).join('\n')
}

为什么非要这么做？因为Zod Schema对AI来说是“机器语言”，必须转译成AI能快速解析的自然语言格式。否则，AI在理解参数类型和必填约束时，它的误差率会显著上升。

3. 动态上下文注入

这是普通提示词方案和工程化提示词方案之间，最大的分水岭。静态提示词只能应对简单场景，动态注入才是迈向专业化的关键。

3.1 环境信息收集

系统会自动感知当前项目的环境信息，并实时整合到提示词中：

// 收集当前环境信息
async function collectEnvironmentContext(): Promise {
  const cwd = getCwd()

  return {
    // 工作目录
    workingDirectory: cwd,

    // Git 信息
    git: {
      isRepo: await getIsGit(),
      branch: await getCurrentBranch(),
      status: await getGitStatus(),
      remoteUrl: await getRemoteUrl(),
    },

    // 项目信息
    project: {
      name: getProjectName(cwd),
      type: detectProjectType(cwd),
      dependencies: await getDependencies(cwd),
      scripts: await getPackageScripts(cwd),
    },

    // 系统信息
    system: {
      platform: process.platform,
      nodeVersion: process.version,
      shell: process.env.SHELL,
    },
  }
}

3.2 上下文格式化

收集完环境信息后，系统会将这些内容格式化为结构化提示词，嵌入到AI的上下文中：

// 格式化上下文为提示词
function formatContextAsPrompt(context: EnvironmentContext): string {
  return `## Current Environment

Working Directory: ${context.workingDirectory}

${context.git.isRepo ? `### Git Status
Branch: ${context.git.branch}
Status: ${context.git.status}` : "Not a git repository'}

### Project
Name: ${context.project.name}
Type: ${context.project.type}

### System
Platform: ${context.system.platform}
Node: ${context.system.nodeVersion}`
}

这里的“动态”二字体现在哪里？
举个例子：AI在执行代码前，可以通过注入的Git状态判断当前是否在分支上，有无未提交的改动；通过环境信息确认当前操作系统的兼容性。无需用户额外说明，AI就已经掌握了上下文。

4. 内存系统集成

4.1 记忆注入

更进一步的，系统还会调用内存功能，在提示词中注入与当前查询相关的历史记忆：

// 从内存系统注入相关记忆
async function injectMemoryContext(
  query: string,
  sessionId: SessionId
): Promise {
  const memories = await queryMemories(query, { limit: 5 })

  if (memories.length === 0) {
    return ''
  }

  return `## Relevant Memories

${memories.map(m => `- ${m.content}`).join('\n')}`
}

这样做的好处很明显：AI不需要从头理解全局，历史经验会变成上下文的一部分。如果用户之前有过偏好设置或某些特定的决策记录，AI能够“回想”起来。

4.2 项目记忆

项目级别还存在一个CLAUDE.md文件，相当于给AI的“项目手册”。
系统会读取这份说明书，合并到提示词里：

// 从 CLAUDE.md 注入项目记忆
async function injectProjectMemory(): Promise {
  const claudeMd = await readClaudeMd()

  if (!claudeMd) {
    return ''
  }

  return `## Project Documentation

${claudeMd}`
}

也就是说，项目中如果有约定的编码规范、命名习惯、目录结构原则，AI从一开始就能读到。无需用户每次重复。

5. Proactive 模式

5.1 主动模式设计

普通提示词模式下，AI是被动响应者——用户问什么，它答什么。
但Proactive模式改变了这个局面。系统会动态增强提示词，赋予AI“主动预判”的能力：

// 主动模式的提示词增强
function enhanceForProactiveMode(
  systemPrompt: SystemPrompt,
  context: ToolUseContext
): SystemPrompt {
  if (!context.isProactiveMode) {
    return systemPrompt
  }

  const proactiveInstructions = `## Proactive Mode Instructions

You are operating in proactive mode. This means you should:

1. **Anticipate needs**: Think about what the user might want to do next
2. **Take initiative**: Don't wait for explicit instructions
3. **Stay within scope**: Focus on the current task
4. **Report progress**: Keep the user informed

### Autonomy Level
${context.autonomyLevel ?? 'medium'}

### Task Scope
${context.taskScope ?? 'general assistance'}`

  return appendToSystemPrompt(systemPrompt, proactiveInstructions)
}

这里有一个巧妙的平衡：AI要主动，但不能越界。所以指令中明确了“Stay within scope”和“Autonomy Level”，也就是给AI划定了一个可以自主行动，但必须受控的边界。

6. 最佳实践总结

6.1 提示词设计原则

6.2 常见陷阱

1. 过长提示词——信息过多反而会稀释关键指令，同时影响响应速度。
2. 模糊指令——AI最怕的不是复杂，而是“说一半，留一半”，行为会变得不可预测。
3. 静态提示词——完全不适应上下文变化的提示词，在动态工程场景中几乎没有价值。
4. 缺乏示例——不给例子，AI的理解成本直线上升。

下一篇，我们会进入多Agent系统与协作的深度拆解，看看Claude Code如何实现多个智能体协同完成复杂任务。