自己做agent项目时，为什么工具和提示词写完之后总要重构再重构

最近有朋友来问我他们团队做内部agent代理项目工具写了十几个能跑起来了但后来想加权限没地方加agent中断之后也不知道怎么恢复状态最后只好停下来把工具全部重写了一遍他们花了一个小时写工具花了三周重构工具。我听完就说这条路Claude Code源码里前面给出了答案而且答案还很简单就是两件事工具要协议化提示词要分层。这篇文章我想把这两件事聊清楚再顺带说一下Claude Code里哪些能力是第一版自建代理根本不需要碰的。工具写成散函数以后一定要还债做代理工具最直观的写法就是一堆独立的小功能需要搜索就写一个需要读文件就写一个然后告诉模型说你可以用这些跑起来了。前面这样确实没问题看起来也简单。但等你需要加权限的时候发现每个功能要单独处理根本没有统一入口。等你需要加日志同样的问题。等功能多了要按环境筛选发现完全没有结构支撑。等你中断恢复发现调用记录没有统一格式无法重放。然后就剩下了重构这一条路。这不是我猜的这是那个朋友团队发生的事情。重构之后的结构其实就是一个不完整的工具协议只是绕了一大圈才明白这件事。Claude Code 的做法从第一天就把工具当成「协议对象」Claude Code 没有把工具理解成“一个可以被调用的函数”而是把它理解成“Agent 运行时的等对象”每个工具都必须提供一整套标准信息。简单说一个工具不仅仅是「能被调用」还要说清楚这几件事自己叫什么名字、接受什么样的输入、怎么验证输入是否合法、需要什么权限才能执行、执行结果是什么格式、如果代理中途被打断了该怎么处理。每个工具都按真正的标准来系统层才能做那些有价值的事情。因为所有工具都经过同一个权限检查入口权限系统就不需要分散处理。因为每个工具都声明了自己不是可以并发执行的调度系统就知道哪些工具可以同时运行哪些必须排队需要手动维护白名单。因为所有工具都有统一的摘要输出日志、界面显示、任务全部都有稳定的数据格式可以依赖。工具协议这件事就像盖楼之前打地基前两层看不出利润等盖楼到第五层就全部出来了。Claude Code还在协议里加了一些很多容易项目忽略的能力比如支持工具搜索这样工具多了也能快速找到对的那个支持首轮不完全加载所有工具节省上下文空间支持大结果另存而不是全塞进上下文避免超长输出把对话撑爆。这些都是在统一协议基础上再往上叠的增强没有底层协议这些能力根本没有地方生长。技术扩展Claude Code里Tool.ts定义了统一工具协议每个工具除了核心的call()调用方法之外还需要实现inputSchema输入结构声明、validateInput()输入校验、checkPermissions()权限检查、isReadOnly()相关声明、isConcurrencySafe()并发安全声明、interruptBehavior()中断符号、getToolUseSummary()执行摘要等字段和方法。进阶增强部分包括searchHint支持工具搜索搜索评分shouldDefer/alwaysLoad控制首轮工具加载策略maxResultSizeChars支持大结果落盘替换toAutoClassifierInput()支持自动分类导航preparePermissionMatcher()支持内容级权限规则匹配。对自建代理来说第一版不需要做到这么完整但有几项建议从第一天就有名字、输入结构、调用方法、输入验证、权限检查、是否有、运算符属性、返回结果。就这几项让你在后面加权限、加日志、做恢复的时候不需要推倒重来。提示词不分层功能一多就变成没人敢动的怪物顺着工具再往下聊提示词。很多代理项目的系统提示是很长的文本角色定义、行为约束、工具说明、输出一段格式全部都塞进去。前期也跑得通但等能力多了问题就出来了。改一个约束要在一大段文字里搜搜到了还不确定改了不会影响其他地方。想子代理的提示和主代理的提示混在一起修改子代理要特别小心不要改坏主代理。新加一个工具要记住手动更新系统提示容易漏掉。最后系统提示变成了谁不敢轻易动的怪物。Claude Code把提示词拆成了四层。第一层系统基础提示定义了这个代理是什么、在什么环境下运行、有什么基本约束是最基础最稳定的那部分。第二层系统提示分区把系统基础提示进一步独立的小块每个块单独管理。有的块变化频率低可以缓存起来不用每次重设。有的块每轮要根据当前状态刷新单独拿出来处理。第三层代理提示子代理有自己独立的角色定义不直接复用主代理的提示文本而是单独写好角色再补充当前环境信息再加上约束补充一层构成。第四层工具提示每个工具自己维护自己的使用说明不会硬编码塞进主系统提示里。工具说明放在工具自己那里修改工具说明只需要修改那个工具不影响任何其他位置。然后在执行最终时系统把这几层按顺序组合并且层关系一直保留到执行时不会完成就丢失结构信息。这个结构解决方案不仅仅是可维护性还有服务器效率。主系统提示变化频率低可以缓存。环境信息每轮都要更新不缓存。工具说明按工具加载依次缓存。如果全混在一个大字符串里这种细粒度的存储策略根本做不到每次都要全量重新计算成本高而且慢。技术扩展Claude Code的主系统提示prompts.ts由中的getSystemPrompt()函数组成内容来自多个独立部分包括会话引导、内存、环境信息、输出样式、MCP指令等。systemPromptSections.ts中将部分分为两类systemPromptSection()可存储版本和DANGEROUS_uncachedSystemPromptSection()子代理提示runAgent.ts由中的getAgentSystemPrompt()构成先取agentDefinition.getSystemPrompt()角色定义再调用enhanceSystemPromptWithEnvDetails()提升环境信息。工具提示由每个工具自身的prompt()方法维护以 BashTool 为例说明独立放在BashTool/prompt.ts文件中ToolSearch 功能文本也直接读取这个prompt()做搜索评分。对自建代理第一版建议至少做三层系统基础提示、代理角色提示、工具提示分别独立管理。三层分开之后后面想加分区缓存、想加刷新都有地方往里安装。提示词系统不应该只关注「文案」而应该关注 Agent 架构的部分。克劳德码里有哪些能力第一版根本不用碰Claude Code很优秀但如果你只根据它的功能列表去规划自己的agent项目很容易被带偏。它现在的很多能力是一个已经经历了多轮迭代的成熟产品才会有的而不是第一版就必须有的。多终端入口网页版、桌面版、移动端、远程连接这些是产品覆盖面不是 Agent 内核。平台生态扩展插件系统、技能市场、各种协议对接这些是平台化阶段才认真做的事。高阶协作系统多 Agent 群组调度、超级计划、团队协作模式这些是复杂任务扩展层不是最小可用 Agent的核心。规模化优化、上下折叠压缩、提示词存储精细化、成本追踪细化、全局追踪这些都是规模化上来之后才需要认真处理的问题。不是说这些不重要是说第一阶段就做好这些很容易变成什么都做了一点但是Agent本身并没有跑稳。Claude Code最值得学习的并不是功能齐全但它显然有一个分阶段的构建顺序。先把单代理内核做稳定再把工具、提示词、权限、状态权限系统最后再提升产品化能力。这个顺序比任何功能清单都更值得记住。第一版自建代理这几件事建议从第一天就做对统一工具协议名称、输入结构、调用方法、权限、接口参数、运算符参数、返回结果这几项从第一天起就要统一定义。提示词三层分离系统基础提示、代理提示、工具提示角色各自独立不混在一起。单Agent主循环稳定权限系统接入计划与状态管理中断机制。就这几件事做稳了之后后面要加什么都有地方加。反过来基础没打好功能加得越多系统越难维护。Agent架构这东西本质上是在构建执行基础设施而不是在积累功能。基础设施不够好agent只有三个的时候感觉不出来工具变成三十个、任务变复杂、团队里多了几个人同时改那个时候你会非常明确地等最初那些架构决定到底值不值。Claude Code源码告诉我最重要的一件事大概就是这个重要的不是你实现功能的多少而是这些功能是按什么顺序、用什么结构搭建起来的如果你身边有正在做Agent项目的朋友这篇直接转给他可能会帮他省掉一次重构的麻烦。学AI大模型的正确顺序千万不要搞错了2026年AI风口已来各行各业的AI渗透肉眼可见超多公司要么转型做AI相关产品要么高薪挖AI技术人才机遇直接摆在眼前有往AI方向发展或者本身有后端编程基础的朋友直接冲AI大模型应用开发转岗超合适就算暂时不打算转岗了解大模型、RAG、Prompt、Agent这些热门概念能上手做简单项目也绝对是求职加分王给大家整理了超全最新的AI大模型应用开发学习清单和资料手把手帮你快速入门学习路线:✅大模型基础认知—大模型核心原理、发展历程、主流模型GPT、文心一言等特点解析✅核心技术模块—RAG检索增强生成、Prompt工程实战、Agent智能体开发逻辑✅开发基础能力—Python进阶、API接口调用、大模型开发框架LangChain等实操✅应用场景开发—智能问答系统、企业知识库、AIGC内容生成工具、行业定制化大模型应用✅项目落地流程—需求拆解、技术选型、模型调优、测试上线、运维迭代✅面试求职冲刺—岗位JD解析、简历AI项目包装、高频面试题汇总、模拟面经以上6大模块看似清晰好上手实则每个部分都有扎实的核心内容需要吃透我把大模型的学习全流程已经整理好了抓住AI时代风口轻松解锁职业新可能希望大家都能把握机遇实现薪资/职业跃迁这份完整版的大模型 AI 学习资料已经上传CSDN朋友们如果需要可以微信扫描下方CSDN官方认证二维码免费领取【保证100%免费】