最近有朋友来问我，他们团队做内部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%免费】