1. 从一次失败的代码生成说起为什么我的Claude不干活最近在折腾Claude Code想让它帮我重构一个Python数据处理脚本。我按照常规思路写了个挺详细的Prompt“请帮我优化这段代码让它更高效、更Pythonic并添加适当的错误处理。” 结果Claude Code的回复让我有点懵它洋洋洒洒地分析了代码结构指出了几个可以改进的地方比如建议用列表推导式替代循环、使用with语句管理文件句柄……但也就到此为止了。它没有生成任何一行新的、优化后的代码给我只是停留在“建议”层面。这感觉就像你问一个经验丰富的厨师“这道菜怎么做更好吃”他告诉你“火候要足调料要鲜摆盘要美。” 然后呢具体怎么操作锅烧几成热放多少克盐盘子怎么摆没了。对于写代码来说这种“只诊断不开药”的体验效率大打折扣。我当时的第一反应是是不是我的Prompt写得不够好或者Claude Code的能力仅限于此直到我深入研究了它的源码特别是那个至关重要的系统提示词System Prompt才恍然大悟。问题的关键往往不在于用户问了什么而在于你“允许”AI模型做什么。在Claude Code的上下文中这个“允许”的开关很大程度上就藏在系统提示词里关于tools的定义和使用中。简单来说如果没有在系统提示词中明确地、结构化地告诉Claude“嘿你现在是一个代码助手你拥有并使用以下工具来完成任务”那么Claude很可能只会像一个代码评审专家一样进行纯文本的分析和评论而不会主动调用“代码生成”、“代码执行”或“文件读写”这些实质性的工具来产出结果。tools在这里就是赋予AI模型“动手能力”的授权书和工具箱。所以当我们问“为什么Claude Code系统提示词中需要有tools”时我们真正在探讨的是如何将一个强大的、但本质上只能进行文本对话的大语言模型LLM精准地“塑造”并“装备”成一个能实际解决编程问题的智能体Agent。tools就是这个塑造过程中的核心骨架。2. 拆解系统提示词tools如何定义AI的“角色”与“能力”要理解tools的必要性我们得先看看在一个像Claude Code这样的AI编程助手中系统提示词大概长什么样。虽然我们拿不到官方的完整提示词但根据开源社区对类似项目如Cursor的规则、ChatGPT的Code Interpreter的分析以及大模型API如OpenAI的Function Calling Anthropic Claude的Tool Use的设计模式我们可以重构出其核心逻辑。一个典型的、功能完整的代码助手系统提示词绝不会只是一句“你是一个有帮助的AI编程助手”。它会是一个结构化的、多段落的“角色设定剧本”其中关于tools的部分通常是重头戏。这部分内容大致会遵循以下结构2.1 核心能力声明与约束首先系统提示词会开宗明义地定义AI的核心身份和首要任务。例如 “你是一个世界级的软件开发专家专门帮助用户编写、分析、调试和优化代码。你的主要交互模式是理解用户的需求然后使用你被授予的工具来完成任务。”紧接着就是最重要的部分——工具清单。这部分会以非常清晰、无歧义的方式列出AI可以调用的所有tools每个tool都包含工具名称一个唯一的标识符如write_file,execute_code,search_web。工具描述用自然语言详细说明这个工具是干什么的。例如对于execute_code描述可能是“在安全的沙箱环境中执行一段给定的代码并返回执行结果、输出或错误信息。”输入参数定义调用这个工具需要提供哪些信息以及它们的类型和格式。例如write_file工具可能需要file_path(字符串) 和content(字符串) 两个参数。输出说明告诉AI在调用工具后会收到什么格式的反馈。例如“执行成功后你将收到一个包含stdout,stderr,exit_code等字段的JSON对象。”这个清单就是AI的“技能表”。没有它AI就像是一个空有理论知识的学者知道“函数”的概念但不知道如何“定义”一个函数知道“循环”能优化代码但不知道如何“写”出一个循环。2.2tools与“思考-行动”循环的绑定仅仅列出工具还不够。系统提示词必须将tools无缝嵌入到AI的“思考-行动”循环中。它会给出明确的指令例如“当你需要完成一个涉及代码操作的任务时请遵循以下步骤分析需求理解用户到底想要什么是创建新文件、修改现有代码、运行测试还是查找信息。规划行动决定是否需要使用工具以及使用哪个工具。调用工具严格按照工具定义的格式生成一个结构化的调用请求例如一个JSON对象。处理结果等待工具执行完毕并返回结果然后基于结果进行下一步分析或直接向用户汇报。”这个指令将tools从静态的“能力列表”变成了动态的“工作流引擎”。它强制AI从“被动回答问题”转向“主动解决问题”。在我最初那个失败的例子中Claude Code很可能就是因为缺少了这样明确的、绑定到tools的行动指令才只进行了分析而没有生成代码。它可能“知道”自己可以写代码但系统没有“命令”它必须通过调用write_file这个工具来落实这个想法。2.3 安全边界与责任界定tools的另一个关键作用是划定安全边界。代码操作是危险的随意执行未知代码、覆盖重要文件都可能造成严重后果。系统提示词中关于tools的部分会包含严格的安全规则沙箱限制明确告知AIexecute_code工具只在隔离的、无网络、无持久化存储的沙箱中运行。文件范围限制规定read_file和write_file工具只能操作项目工作区内的特定目录禁止访问系统文件。用户确认对于高风险操作如删除文件、安装系统包要求AI必须先向用户解释操作内容并获取明确同意然后再调用工具。这些规则通过tools的接口设计来实现。例如execute_code工具可能根本不提供import os; os.system(‘rm -rf /’)这样的能力。这就在模型能力层面设置了硬性护栏比单纯在文本提示词中说“不要做危险的事”要可靠得多。3. 深入源码视角tools是如何被集成和调度的理解了tools在提示词层面的逻辑后我们进一步深入到模拟的源码实现层面看看tools是如何从一段文本描述变成AI可以实际调用的功能的。这能更深刻地说明为什么它必须是系统提示词的一部分而不是可选项。假设我们在构建一个简化版的“Claude Code”后端服务它的核心组件和工作流如下3.1 工具注册与管理层首先会有一个ToolRegistry工具注册表的类或模块。它的职责是定义每个工具的可调用函数实现真正的功能。为每个工具生成一份工具描述Schema。这份Schema就是最终要放入系统提示词的那段结构化文本。# 伪代码示例工具注册 class CodeExecutionTool: name “execute_python” description “在安全沙箱中执行一段Python代码并返回结果。” parameters_schema { “type”: “object”, “properties”: { “code”: {“type”: “string”, “description”: “要执行的Python代码”}, “timeout”: {“type”: “integer”, “description”: “超时时间(秒)”, “default”: 30} }, “required”: [“code”] } async def call(self, code: str, timeout: int): # 实际调用Docker或安全运行时执行代码的逻辑 result await run_code_in_sandbox(code, timeout) return {“stdout”: result.stdout, “stderr”: result.stderr, “exit_code”: result.exit_code} # 注册工具 tool_registry.register(CodeExecutionTool())当系统启动时ToolRegistry会收集所有注册的工具将它们各自的name,description,parameters_schema整合成一个大的列表。这个列表就是需要动态插入到系统提示词模板中的tools部分。这意味着tools不是手写死的提示词而是由后端代码能力“生成”的声明。如果你新增了一个git_diff工具系统提示词中就会自动多出一项对应的能力描述。这种设计保证了提示词与后端能力的绝对同步。3.2 提示词组装与对话初始化当一个新的对话会话开始时服务端会从ToolRegistry获取最新的工具列表。将这个列表填充到一个预设的系统提示词模板中。这个模板除了包含tools列表还有前面提到的角色定义、工作流指令、安全规则等固定部分。将组装好的完整系统提示词作为第一条“系统消息”发送给大语言模型如Claude-3 Opus。# 伪代码示例组装系统提示词 def build_system_prompt(): base_prompt “”” 你是Claude Code一个顶尖的AI编程助手。你的任务是帮助用户解决编程问题。 你可以使用以下工具来完成任务 {tools_list_placeholder} # 这里会被替换成实际的工具描述JSON数组 你的工作流程是1. 理解问题2. 如需工具则规划调用3. 以指定格式请求调用工具4. 分析工具结果并继续。 严禁执行任何危险操作。文件操作仅限工作区内。 “”” tools_list tool_registry.get_tools_schema() # 获取所有工具的JSON Schema full_prompt base_prompt.replace(“{tools_list_placeholder}”, json.dumps(tools_list, indent2)) return full_prompt至此模型在对话的一开始就被“武装”了关于tools的完整知识。它知道有什么工具、每个工具怎么用、用了之后会得到什么。3.3 模型推理与工具调用循环用户提问后真正的魔法开始了模型生成请求模型基于系统提示词的指引在思考后可能会在回复中输出一个特殊的结构化文本块表明它想调用一个工具。在Anthropic的Claude API中这体现为tool_use类型的消息块。用户请帮我写一个函数计算斐波那契数列。 Claude思考后我需要创建一个Python文件并写入函数代码。我将使用write_file工具。 requested_tool_call { “name”: “write_file”, “arguments”: { “file_path”: “./fibonacci.py”, “content”: “def fibonacci(n):\n if n 1:\n return n\n a, b 0, 1\n for _ in range(n-1):\n a, b b, ab\n return b\n\n# 测试\nif __name__ \“__main__\”:\n for i in range(10):\n print(fibonacci(i))” } } /requested_tool_call后端路由与执行后端服务解析出这个工具调用请求根据name找到ToolRegistry中对应的工具实现即CodeExecutionTool.call方法传入arguments参数并实际执行它。结果返回与继续对话工具执行完成后后端将结果如{“success”: true, “message”: “File written successfully.”}包装成tool_result消息附加到对话历史中再次发送给模型。tool_result { “tool_call_id”: “call_123”, “content”: “文件 ./fibonacci.py 已成功创建。” } /tool_result模型下一步决策模型接收到工具执行结果结合最初的用户问题决定下一步行动是直接给出最终答案“函数已写好保存在fibonacci.py中”还是需要继续调用其他工具比如“现在用execute_python工具运行一下测试看看结果”。这个循环用户输入 - 模型思考并可能请求工具 - 后端执行工具 - 结果返回给模型 - 模型继续思考就是AI智能体的核心。而驱动这个循环的“燃料”和“地图”正是系统提示词中关于tools的完整定义。没有它模型就不知道如何生成那个结构化的requested_tool_call整个循环也就无从开始。4. 对比与延伸没有tools的AI编程助手会怎样为了更凸显tools的价值让我们设想一个没有在系统提示词中明确定义tools的“Claude Code Lite”版本。场景一代码生成任务有tools的Claude Code用户说“创建一个Flask API端点”。Claude理解需求调用write_file工具生成app.py调用execute_python工具安装依赖并运行服务器最后可能还会调用一个虚拟的curl_test工具来验证端点是否正常响应。整个过程是自动化的、可执行的。没有tools的Claude Code Lite用户提出同样请求。Claude可能会回复一段非常漂亮的Flask代码示例甚至附带详细的注释。但它只会以文本形式呈现。用户需要自己手动创建文件、复制代码、在终端运行pip install flask、再执行python app.py。AI的参与止步于“建议”而非“实施”。场景二代码调试任务有tools的Claude Code用户贴出一段报错的代码。Claude可以调用execute_python工具用不同的测试用例实际运行这段代码捕获真实的报错堆栈信息然后基于确切的错误进行分析和修复甚至直接调用write_file工具将修复后的代码写回文件。没有tools的Claude Code LiteClaude只能基于用户粘贴的代码和错误信息文本进行“静态分析”。它无法复现错误无法验证修复方案是否有效。其诊断的准确性和修复的可靠性大打折扣。场景三复杂项目理解有tools的Claude Code用户问“这个项目的主要入口点是哪个文件”Claude可以调用read_file工具遍历项目结构读取package.json、pyproject.toml或main.go等文件综合分析后给出准确答案。没有tools的Claude Code LiteClaude只能依赖用户可能提供的、不完整的项目描述来猜测或者要求用户提供更多文件内容。效率极低。由此可见缺少了toolsAI编程助手就退化成了一个高级的、交互式的代码搜索引擎和文档生成器。它能够进行出色的代码分析和解释但无法形成“感知-决策-行动”的闭环。tools正是连接AI的“大脑”语言模型与“手脚”代码执行环境、文件系统、网络等的桥梁和协议。5. 设计你自己的tools从Claude Code中获得的启示分析Claude Code的设计不仅是为了理解它更是为了启发我们如何设计自己的AI应用。如果你正在基于大模型API构建一个垂直领域的智能体tools的设计是重中之重。以下是一些关键启示和实操建议5.1 工具设计原则原子化与组合性好的工具应该是原子化的每个工具只做一件事并把它做好。例如read_file、write_file、execute_command、search_web都是原子操作。复杂的任务通过组合多个工具调用来完成。这降低了模型的决策难度每次只需选择一个简单工具也使得工具的实现和后端维护更简单。避免设计“瑞士军刀”式的巨无霸工具比如一个handle_project_request工具参数复杂到需要传入整个项目需求。模型很难正确使用它而且一旦出错调试将是一场噩梦。5.2 描述即契约清晰、无歧义的工具Schema工具的描述Schema是模型理解和使用它的唯一依据。编写Schema时要像写API文档一样严谨名称直观calculate_sum比tool_operation_1好得多。描述具体不要说“处理数据”要说“读取指定CSV文件计算第二列的平均值并返回”。参数定义明确指定类型string, integer, boolean, array、是否必需、默认值、枚举值如果有限定。良好的参数约束能极大减少模型调用错误。输出示例如果可能在描述中或通过示例对话展示工具成功调用后的典型返回结果格式。这能帮助模型更好地解析和利用结果。5.3 系统提示词与工具描述的融合艺术工具列表不能孤立地存在。系统提示词的其他部分必须与之紧密配合角色设定要呼应工具能力如果你提供了sql_query工具那么角色描述中就应该强调“你是一个数据分析专家擅长通过SQL从数据库中提取和解读信息”。工作流指令要细化工具使用场景给出具体的思考链示例。例如“当用户询问数据趋势时你应该1. 询问或确认数据库连接信息2. 使用sql_query工具编写并执行查询3. 分析返回的数据集4. 使用generate_chart工具如果有创建可视化或直接用文字总结。”安全规则要针对具体工具对于execute_shell工具要严格规定允许的命令白名单对于send_email工具要规定收件人域名的限制等。5.4 错误处理与鲁棒性在真实场景中工具调用会失败文件不存在、网络超时、权限不足、参数无效……你的系统提示词需要指导模型如何处理这些情况。在提示词中明确告诉模型“如果工具调用失败你会收到一个错误信息。请仔细阅读错误信息判断是用户输入的问题、环境问题还是逻辑问题然后尝试修复例如更正参数或向用户请求更多信息而不是重复相同的失败调用。”后端在返回工具错误结果时信息要足够丰富便于模型诊断。例如不要只返回{“error”: “failed”}而要返回{“error”: “FileNotFoundError”, “detail”: “The file ‘/path/to/data.csv’ does not exist.”}。5.5 一个简单的自建示例文件内容搜索助手假设我们想用Claude API构建一个帮助搜索本地文档内容的助手。我们的工具设计可能如下工具定义后端# tool_schema.py tools_schema [ { “name”: “list_files”, “description”: “列出指定目录下的所有文件和子目录。用于浏览文档库。”, “input_schema”: { “type”: “object”, “properties”: { “directory_path”: {“type”: “string”, “description”: “目录路径默认为根文档库”} } } }, { “name”: “search_in_file”, “description”: “在指定的文本文件中搜索包含某个关键词的行。”, “input_schema”: { “type”: “object”, “properties”: { “file_path”: {“type”: “string”, “description”: “要搜索的文件路径”}, “keyword”: {“type”: “string”, “description”: “搜索关键词”} }, “required”: [“file_path”, “keyword”] } } ]系统提示词组装system_prompt f“”” 你是一个智能文档搜索助手。用户有一个本地文档库你可以通过以下工具帮助用户查找信息 {json.dumps(tools_schema, indent2)} 工作流程 1. 当用户想了解文档库结构时使用list_files工具。 2. 当用户想查找特定内容时先通过对话明确关键词和可能相关的文件然后使用search_in_file工具。 3. 如果搜索无结果可以尝试建议更宽泛或更具体的关键词或者换一个文件搜索。 4. 所有文件操作仅限于预设的文档库路径内禁止访问其他系统路径。 现在开始帮助用户吧。 “””通过这样的设计当用户问“我的文档里有没有关于‘神经网络优化’的内容”时Claude就可以先调用list_files看看有哪些文档然后选择最相关的几个比如deep_learning_notes.md、ai_project_plan.pdf.txt再分别调用search_in_file进行搜索最后将搜索结果整合成一份清晰的报告给用户。整个过程因为有了tools的明确指引变得目标清晰、步骤可控、结果可靠。回过头看最初的那个问题——“为什么Claude Code系统提示词中需要有tools”——答案已经非常清晰。tools是将大语言模型从一位博学的“顾问”转变为一位能干的“执行者”的关键机制。它通过结构化的声明在模型内部建立了对外部世界代码环境、文件系统等的认知模型和操作接口。它定义了AI的“能力范围”规范了AI的“工作流程”并筑牢了AI的“安全边界”。没有tools的系统提示词就像没有工具清单和操作手册的工匠空有一身技艺却无从施展。因此tools不是Claude Code系统提示词的一个可选项而是其作为“智能编程体”得以成立和高效运作的核心基石。理解这一点无论是使用它还是借鉴其思想来构建自己的AI应用都至关重要。