1. 从一条命令行说起Claude Code 到底在解决什么问题第一次接触 Claude Code 的人十有八九会愣一下这不就是个终端里跑的命令行工具吗跟那些带漂亮界面的 AI 编程助手比它凭什么值得单独拿出来聊设计理念我一开始也是这个反应。直到我在一个真实项目里用它连续处理了十几个跨文件的改动才慢慢品出味道来——它压根就没打算做一个“更好用的聊天框”它想解决的是一个更底层的问题当大模型要真正动手改代码时人和模型之间的协作边界应该划在哪里。传统 AI 编程助手的思路基本是“你问我答”。你在编辑器里选中一段代码问它怎么改它给你一段建议你再手动粘贴回去。这个模式在单文件、小改动场景下很顺但一旦涉及“把这个模块的日志规范统一一下涉及七八个文件”这种任务人就成了搬运工来回复制粘贴上下文还得自己维护。Claude Code 的设计出发点就是把这层搬运工作干掉让模型直接在你的项目目录里读文件、改文件、跑命令。所以它的核心关键词其实有三个CLI、Agent、MCP。CLI 是它的形态Agent 是它的行为模式MCP 是它的扩展方式。这三个词串起来就是 Claude Code 的完整设计哲学。它不是一个“工具”而是一个“住在你终端里的协作者”。你给它一个目标它自己去探索代码库、制定计划、执行修改、验证结果。这个过程里你不再是逐字逐句地指挥而是像一个技术负责人在给下属派活——说清楚要什么然后看它怎么做必要时介入纠偏。这篇文章我想聊的就是这套设计理念背后的取舍。为什么是命令行而不是图形界面为什么强调 Agent 而不是简单的函数调用MCP 协议在整个架构里扮演什么角色以及当你想在自己的项目里复现类似思路时哪些坑是必须提前知道的。适合谁看如果你正在做 LLM 应用开发尤其是想让模型真正“动手干活”而不是“动嘴建议”那这些设计取舍对你会有直接参考价值。如果你只是好奇 Claude Code 怎么用前面几节也能帮你建立正确的预期。2. 为什么是 CLI命令行作为 Agent 的天然宿主2.1 图形界面的隐性成本很多人第一反应是都什么年代了还做命令行工具做个 VS Code 插件不好吗这个问题我认真想过也实际对比过几种形态。结论是对于 Agent 类应用图形界面带来的不是便利而是约束。图形界面的本质是一套预设的交互路径。按钮、菜单、面板每一个 UI 元素都对应一个开发者预先想好的操作。这在传统软件里没问题因为操作是有限的、可枚举的。但 Agent 的工作方式是发散的——它可能需要读一个文件、跑一条命令、搜索一段文本、再读另一个文件这个序列是动态生成的你没法提前为它设计按钮。Claude Code 选择 CLI本质上是把“交互界面”这件事交给了最通用的抽象文本输入输出。模型输出一段文本描述它想执行什么操作宿主程序解析这段文本执行对应动作再把结果以文本形式喂回去。这个循环里没有任何 UI 约束模型想干什么就表达什么扩展性天然拉满。提示这也是为什么很多 Agent 框架最终都收敛到“文本协议 工具调用”的模式。UI 是给人看的协议是给模型看的两者混在一起会互相拖累。2.2 终端是开发者的“工作现场”还有一个更实际的原因开发者本来就活在终端里。你跑测试、装依赖、看日志、提交代码哪一样不是在终端里完成的Claude Code 直接扎根在这个环境里意味着它天然能访问你所有的开发工具链。它不需要通过某个中间层去调用 git它直接跑git diff就行它不需要模拟一个终端去跑测试它直接执行npm test就行。这种“同处一个现场”的设计带来的最大好处是上下文的一致性。你在终端里看到的工作目录、环境变量、已安装的工具Claude Code 看到的完全一样。不会出现“插件里跑得好好的一到真实终端就报错”这种割裂感。我在实际使用中特别看重这一点因为 Agent 最怕的就是环境不一致导致的隐性失败——它以为自己在 A 环境实际在 B 环境改出来的东西全是错的。2.3 CLI 带来的可组合性命令行的另一个隐性优势是可组合。Claude Code 可以作为一个命令被其他脚本调用可以把它的输出管道给别的工具可以用 shell 的串起一连串操作。这种 Unix 哲学式的设计让它可以嵌入到已有的自动化流程里而不是要求你为它单独开一个工作流。举个我实际用过的场景我写了一个脚本先用git diff --name-only拿到本次改动的文件列表然后把这个列表作为上下文传给 Claude Code让它针对这些文件做一轮代码审查。整个过程就是几行 shell没有任何“集成”成本。如果 Claude Code 是个图形应用这件事就得靠它自己提供 API 才能做到而 CLI 形态天然就有这个能力。形态扩展方式环境一致性可组合性学习成本CLI文本协议无限扩展与终端完全一致高可管道可脚本中需熟悉命令行IDE 插件受插件 API 限制依赖 IDE 环境低难被外部调用低图形化操作独立 GUI受 UI 框架限制独立环境易割裂极低低但功能受限这张表不是要贬低图形界面而是想说清楚形态选择取决于你要解决什么问题。如果你做的是“帮用户补全一行代码”插件形态更合适如果你做的是“让模型自主完成一个多步骤任务”CLI 几乎是唯一合理的选择。3. Agent 模式的核心从“回答问题”到“完成任务”3.1 Agent 和普通 LLM 调用的本质区别聊 Claude Code 绕不开 Agent 这个词。但 Agent 到底是什么很多人其实说不清楚。我的理解很简单普通 LLM 调用是“输入一段文本输出一段文本”Agent 是“输入一个目标输出一个完成状态”。这个区别听起来小实际影响巨大。普通调用里模型不需要关心自己的输出有没有用它只负责生成看起来合理的内容。Agent 模式里模型必须关心“我做的这件事有没有推进目标”因为它会看到自己操作的后果——文件改错了下一次读回来就是错的命令跑失败了返回的就是错误信息。这种基于反馈的循环是 Agent 和普通调用的分水岭。Claude Code 的 Agent 循环大致是这样的接收用户目标 → 分析当前状态 → 决定下一步动作 → 执行动作 → 观察结果 → 判断是否完成 → 未完成则回到第二步。这个循环里模型既是决策者也是执行者而宿主程序负责提供工具和反馈。3.2 工具调用是 Agent 的手脚Agent 要“动手”就必须有工具。Claude Code 暴露给模型的工具集基本覆盖了开发场景的核心操作读文件、写文件、搜索、执行命令、列目录。这些工具的设计有个共同原则粒度要合适。什么叫粒度合适太粗了不行比如给一个“重构这个模块”的工具模型没法控制具体怎么改太细了也不行比如给一个“在第 37 行第 12 列插入字符”的工具模型得先算半天位置。Claude Code 的工具粒度基本是“文件级”和“命令级”——读整个文件、写整个文件、跑一条命令。这个粒度让模型有足够的控制力又不至于陷入细节泥潭。注意工具粒度是 Agent 设计里最容易踩坑的地方。我见过不少项目把工具做得太细结果模型要完成一个简单任务得调用十几次工具token 消耗爆炸还容易在中途迷失目标。宁可粗一点让模型用多次调用组合出复杂行为。3.3 计划与执行的分离Claude Code 在处理复杂任务时会先输出一个计划再逐步执行。这个设计我觉得特别值得借鉴。计划的价值不在于计划本身而在于它给了人一个介入点。如果模型直接闷头改代码你只能等它改完再看结果发现问题已经晚了。有了计划这一步你可以在它动手之前就看到“它打算怎么干”如果方向不对直接打断重来省下的不只是时间还有被改乱的文件。我在实际使用中凡是涉及三个以上文件的任务都会先看它的计划确认没问题再让它执行。这个习惯帮我避免了好几次“改了一半发现方向错了”的尴尬。从工程角度看计划与执行的分离还有个好处它把一次大决策拆成了多次小决策。模型在每一步执行后都能重新评估而不是一条路走到黑。这种“走走看看”的策略在不确定环境里比“一次性规划到底”要稳健得多。4. MCP 协议Agent 的能力边界如何扩展4.1 MCP 要解决的是什么问题MCP 这个词最近热度很高但很多人对它的理解停留在“又一个协议”。我的看法是MCP 解决的是 Agent 能力的“最后一公里”问题。前面说了Claude Code 内置了一批工具读文件、写文件、跑命令。但真实开发场景里你需要的能力远不止这些。你可能要查数据库、调内部 API、读某个特定格式的配置文件、操作某个专有系统。这些能力如果都塞进 Claude Code 内置工具里那这个工具会变得无比臃肿而且每加一个能力都要改核心代码。MCP 的思路是把能力提供方和 Agent 宿主解耦。你写一个 MCP Server声明你提供哪些工具Claude Code 作为 MCP Client 连上你就能用你的工具。整个过程不需要改 Claude Code 一行代码。这个设计跟 USB 的思路很像——电脑不需要知道每个外设内部怎么工作只要大家都遵守 USB 协议插上就能用。4.2 MCP 的协议结构MCP 协议本身不复杂核心就是几个概念Server、Client、Tool、Resource。Server 是能力提供方Client 是能力使用方比如 Claude CodeTool 是可被调用的操作Resource 是可被读取的数据。通信基于 JSON-RPC传输层可以是标准输入输出也可以是网络连接。这个设计里我觉得最妙的一点是Tool 的描述是自包含的。每个 Tool 都要声明自己的名字、用途、参数结构。Agent 拿到这些描述后自己决定什么时候调用哪个 Tool。这意味着你新增一个 MCP ServerAgent 不需要重新训练或重新配置它读一遍 Tool 描述就知道怎么用了。这种“即插即用”的能力扩展方式是 MCP 最大的价值。{ name: query_database, description: 执行只读 SQL 查询并返回结果, inputSchema: { type: object, properties: { sql: { type: string, description: 要执行的 SQL 语句仅支持 SELECT } }, required: [sql] } }上面是一个典型的 MCP Tool 定义。模型看到这段描述就知道有个叫query_database的工具接受一个sql参数用来查数据库。它会在需要查数据的时候自动调用。整个过程不需要人告诉它“你可以查数据库”它自己从工具列表里发现。4.3 什么时候该用 MCP什么时候不该用MCP 很强但不是所有场景都该上。我的经验判断标准是如果这个能力是通用的、可复用的、跟具体项目解耦的就做成 MCP Server如果是一次性的、跟当前任务强绑定的直接写在提示词或脚本里更省事。举个例子你公司有一套内部的工单系统你想让 Agent 能查工单状态。这个能力多个项目都会用到做成 MCP Server 很合理。但如果你只是这次任务需要读一个特定格式的日志文件写个一次性脚本让 Agent 调用就行没必要为它专门搭个 Server。提示MCP Server 的维护成本不低尤其是当 Tool 数量多起来之后描述写得好不好直接影响模型调用准确率。我见过因为 Tool 描述太模糊模型反复调错工具的情况。描述要写清楚“什么时候用”和“什么时候不用”这比写清楚参数更重要。5. 上下文管理Agent 的隐形战场5.1 为什么上下文是 Agent 的命门Agent 干活的过程本质上是一个不断累积上下文的过程。每读一个文件、每跑一条命令、每做一次修改都会往上下文里塞东西。而模型的上下文窗口是有限的塞满了就得丢东西丢错了就丢掉了关键信息Agent 就开始犯迷糊。Claude Code 在上下文管理上做了不少设计我觉得最核心的一条是按需读取而不是全量加载。它不会一上来就把整个项目读进来而是根据当前任务先看目录结构再决定读哪些文件。这个策略跟人处理陌生代码库的方式很像——先看 README再看目录再挑关键文件深入。5.2 上下文压缩的取舍当上下文快满的时候Claude Code 会做压缩。压缩的本质是“用更少的 token 表达同样的信息”。但压缩是有损的压得越狠丢的信息越多。这里的取舍很微妙压得太少上下文很快又满了压得太多Agent 忘了之前干了什么开始重复劳动或者做出矛盾的操作。我的观察是Claude Code 的压缩策略偏向“保留近期、摘要远期”。最近几轮的操作细节保留得比较完整早期的操作只留一个摘要。这个策略符合 Agent 的工作模式——近期操作跟当前决策最相关远期操作只需要知道“做过什么”就够了。5.3 实操中的上下文控制技巧在实际使用中有几个控制上下文的小技巧很管用。第一任务要拆小。一个任务如果需要读二十个文件不如拆成三个小任务每个任务读六七个文件做完一个再做下一个。这样每个任务的上下文压力都小Agent 也更专注。第二及时清理无关信息。如果 Agent 读了一个跟当前任务无关的大文件可以主动让它“忘掉”这个文件的内容避免占用上下文。第三用文件系统当外部记忆。让 Agent 把中间结果写到文件里需要的时候再读回来比一直放在上下文里更省空间。上下文策略适用场景优点风险全量加载小项目、单文件任务信息完整大项目直接爆窗口按需读取大多数场景节省上下文可能漏读关键文件摘要压缩长任务后期延长可用轮次丢失细节导致误判外部文件记忆多阶段任务上下文压力小文件管理复杂这张表里的策略不是互斥的实际使用中往往是组合着来。我的习惯是任务开始时按需读取任务中期如果上下文吃紧就启用摘要压缩任务后期把关键结论写到文件里为下一阶段做准备。6. 安全边界Agent 动手时的风险控制6.1 为什么 Agent 比聊天模型更需要安全设计聊天模型说错话最多是误导你。Agent 做错事是真的会改坏你的文件、跑错命令、删掉不该删的东西。这个区别决定了 Agent 的安全设计不能照搬聊天模型那套“内容过滤”思路而要从操作权限层面去控制。Claude Code 在这方面的设计核心是人在回路。对于读操作它基本放行因为读不会造成破坏。对于写操作和执行命令它会根据配置决定是否需要确认。这个设计承认了一个现实你没法预判 Agent 所有可能的操作所以只能在关键操作上设卡。6.2 权限分级的设计思路我理解 Claude Code 的权限设计大致分几档只读模式、需确认模式、自动模式。只读模式下 Agent 只能看不能改适合探索性任务需确认模式下每次写操作都要你点头适合敏感项目自动模式下 Agent 自主执行适合你信任它且任务明确的场景。这个分级的关键在于默认值的选择。默认太松新手容易出事默认太紧老手觉得烦。Claude Code 的默认值偏保守我觉得是对的——安全这件事宁可让老手多按几次确认也不能让新手一不小心把项目搞崩。注意不管权限设成什么级别涉及删除文件、强制推送、修改系统配置这类操作永远保持人工确认。我踩过的坑是有一次让 Agent 自动清理临时文件它把范围理解大了差点删掉源码目录。从那以后凡是删除类操作我一律手动确认。6.3 沙盒与隔离除了权限控制隔离是另一层保险。理想情况下Agent 的操作应该在一个受限环境里进行即使它做错了影响范围也可控。Claude Code 支持在容器或虚拟机里运行这样它改坏的东西不会波及宿主机。对于生产环境相关的任务我强烈建议用隔离环境别让 Agent 直接碰真实系统。这个思路其实跟测试环境是一个道理你在测试环境里随便折腾出事了重来就行生产环境必须小心翼翼。Agent 的操作也应该有类似的“测试环境”让它先在里面跑通确认没问题再应用到真实环境。7. 从 Claude Code 看 LLM 应用开发的通用经验7.1 形态选择要服务于任务本质Claude Code 选 CLI 不是因为它酷而是因为 Agent 任务本质上是发散的、多步骤的、需要与环境深度交互的。这个判断逻辑可以迁移到任何 LLM 应用开发上先想清楚你的任务是什么形态再决定产品是什么形态。任务是问答式的聊天界面就够任务是操作式的就得考虑怎么让模型能动手任务是流程式的就得考虑怎么编排多个步骤。我见过不少项目一上来就纠结“用哪个框架”“做什么界面”结果核心的任务流程都没想清楚。形态是果任务是因别搞反了。7.2 工具设计比模型选择更重要很多人把精力花在“选哪个模型”上但实际做下来工具设计对最终效果的影响往往比模型选择更大。同样一个模型工具描述写得清楚调用准确率能差出好几倍。工具的名字、描述、参数结构每一个细节都在影响模型的理解。我的经验是工具描述要像写给一个新同事看的文档。你得说清楚这个工具是干什么的、什么时候用、参数怎么填、有什么限制。别假设模型“应该能猜到”它猜不到。描述里多写一句“仅在 X 情况下使用”可能就避免了一类调用错误。7.3 反馈循环的质量决定 Agent 的上限Agent 的能力上限不取决于模型多聪明而取决于它得到的反馈有多准确、多及时。命令跑失败了返回的错误信息清不清晰文件改错了下一次读回来能不能发现这些反馈的质量直接决定了 Agent 能不能自我纠正。所以在设计 Agent 系统时我会特别关注反馈通道每个工具调用的返回信息是否足够诊断问题错误信息是否包含了修复所需的线索如果反馈太模糊Agent 就只能瞎猜再聪明的模型也救不回来。7.4 别追求全自动追求“恰到好处的介入”最后一条经验也是我觉得最重要的一条Agent 系统的目标不是全自动而是让人在合适的地方介入。全自动听起来很美但实际场景里人往往需要在关键决策点把关。Claude Code 的计划确认、写操作确认都是这种“恰到好处介入”的体现。我在自己的项目里也是这个思路让 Agent 处理它擅长的部分——探索、执行、验证但在方向性决策、高风险操作、模糊需求上留给人来判断。这种人机分工比追求全自动要务实得多也安全得多。8. 一些实操中踩过的坑和对应解法8.1 任务描述太模糊导致 Agent 跑偏最常见的坑就是任务描述太模糊。你说“优化一下这个模块”Agent 可能去改性能也可能去改可读性还可能去重构结构。它不知道你真正想要什么只能猜。我的解法是任务描述里必须包含验收标准。不说“优化模块”而说“把这个模块的响应时间降到 100ms 以内不改动对外接口”。有了明确的验收标准Agent 的行动就有了方向。8.2 上下文污染导致重复劳动第二个坑是上下文污染。Agent 在探索阶段读了一些后来证明无关的文件这些文件的内容一直占着上下文导致它后面做决策时被干扰。解法是在任务阶段切换时主动清理上下文。比如探索阶段结束后明确告诉 Agent“现在进入修改阶段之前读的探索性文件可以忽略”。这个动作看起来小但对 Agent 的专注度提升很明显。8.3 工具调用失败后的死循环第三个坑是工具调用失败后的死循环。Agent 调一个命令失败了它重试又失败再重试来回几次上下文就满了。解法是给工具调用设置重试上限并在连续失败后强制切换策略。比如同一个命令连续失败三次就要求 Agent 停下来分析原因而不是继续重试。这个机制需要在宿主程序层面实现不能指望模型自己意识到“我陷入循环了”。常见问题表现根因解法任务跑偏改的方向跟预期不符任务描述缺验收标准描述里写清楚完成条件重复劳动反复读同一批文件上下文污染阶段切换时清理上下文死循环同一操作反复失败重试缺重试上限宿主层设重试次数限制改坏文件修改范围超出预期权限过松写操作保持人工确认遗漏文件该改的没改探索不充分先让它列改动清单再执行这张表里的问题我在不同项目里基本都遇到过。解法不一定适用于所有场景但思路是通用的Agent 出问题往往不是模型不行而是系统设计没给它足够的约束和反馈。9. 如果想自己复现类似思路从哪里开始如果你看完这些想在自己的项目里做一个类似 Claude Code 的 Agent我的建议是从最小闭环开始。先做一个只能读文件、只能跑只读命令的版本让它能探索代码库、回答“这个功能在哪里实现的”这类问题。这个版本不涉及写操作安全风险低但能帮你把 Agent 循环、工具调用、上下文管理这些核心机制跑通。跑通只读版本后再加写操作但先做成“生成修改建议人工确认后应用”的模式。这个模式比全自动安全又能让你观察 Agent 的修改质量。等你对它的判断有信心了再逐步放开自动执行的范围。MCP 的接入可以放到最后。先把内置工具用好确认 Agent 的核心循环没问题再考虑通过 MCP 扩展能力。一上来就搞一堆 MCP Server容易把简单问题复杂化。最后说个我自己的体会做 Agent 系统最难的不是让模型变聪明而是让系统在模型不够聪明的时候也能稳住。好的 Agent 设计是在模型犯错时能及时发现、能纠正、能把损失控制在可接受范围内。Claude Code 的设计理念里这种“稳健优先”的思路贯穿始终这比它具体用了什么模型、支持了什么功能更值得借鉴。
1. 从一条命令行说起Claude Code 到底在解决什么问题第一次接触 Claude Code 的人十有八九会愣一下这不就是个终端里跑的命令行工具吗跟那些带漂亮界面的 AI 编程助手比它凭什么值得单独拿出来聊设计理念我一开始也是这个反应。直到我在一个真实项目里用它连续处理了十几个跨文件的改动才慢慢品出味道来——它压根就没打算做一个“更好用的聊天框”它想解决的是一个更底层的问题当大模型要真正动手改代码时人和模型之间的协作边界应该划在哪里。传统 AI 编程助手的思路基本是“你问我答”。你在编辑器里选中一段代码问它怎么改它给你一段建议你再手动粘贴回去。这个模式在单文件、小改动场景下很顺但一旦涉及“把这个模块的日志规范统一一下涉及七八个文件”这种任务人就成了搬运工来回复制粘贴上下文还得自己维护。Claude Code 的设计出发点就是把这层搬运工作干掉让模型直接在你的项目目录里读文件、改文件、跑命令。所以它的核心关键词其实有三个CLI、Agent、MCP。CLI 是它的形态Agent 是它的行为模式MCP 是它的扩展方式。这三个词串起来就是 Claude Code 的完整设计哲学。它不是一个“工具”而是一个“住在你终端里的协作者”。你给它一个目标它自己去探索代码库、制定计划、执行修改、验证结果。这个过程里你不再是逐字逐句地指挥而是像一个技术负责人在给下属派活——说清楚要什么然后看它怎么做必要时介入纠偏。这篇文章我想聊的就是这套设计理念背后的取舍。为什么是命令行而不是图形界面为什么强调 Agent 而不是简单的函数调用MCP 协议在整个架构里扮演什么角色以及当你想在自己的项目里复现类似思路时哪些坑是必须提前知道的。适合谁看如果你正在做 LLM 应用开发尤其是想让模型真正“动手干活”而不是“动嘴建议”那这些设计取舍对你会有直接参考价值。如果你只是好奇 Claude Code 怎么用前面几节也能帮你建立正确的预期。2. 为什么是 CLI命令行作为 Agent 的天然宿主2.1 图形界面的隐性成本很多人第一反应是都什么年代了还做命令行工具做个 VS Code 插件不好吗这个问题我认真想过也实际对比过几种形态。结论是对于 Agent 类应用图形界面带来的不是便利而是约束。图形界面的本质是一套预设的交互路径。按钮、菜单、面板每一个 UI 元素都对应一个开发者预先想好的操作。这在传统软件里没问题因为操作是有限的、可枚举的。但 Agent 的工作方式是发散的——它可能需要读一个文件、跑一条命令、搜索一段文本、再读另一个文件这个序列是动态生成的你没法提前为它设计按钮。Claude Code 选择 CLI本质上是把“交互界面”这件事交给了最通用的抽象文本输入输出。模型输出一段文本描述它想执行什么操作宿主程序解析这段文本执行对应动作再把结果以文本形式喂回去。这个循环里没有任何 UI 约束模型想干什么就表达什么扩展性天然拉满。提示这也是为什么很多 Agent 框架最终都收敛到“文本协议 工具调用”的模式。UI 是给人看的协议是给模型看的两者混在一起会互相拖累。2.2 终端是开发者的“工作现场”还有一个更实际的原因开发者本来就活在终端里。你跑测试、装依赖、看日志、提交代码哪一样不是在终端里完成的Claude Code 直接扎根在这个环境里意味着它天然能访问你所有的开发工具链。它不需要通过某个中间层去调用 git它直接跑git diff就行它不需要模拟一个终端去跑测试它直接执行npm test就行。这种“同处一个现场”的设计带来的最大好处是上下文的一致性。你在终端里看到的工作目录、环境变量、已安装的工具Claude Code 看到的完全一样。不会出现“插件里跑得好好的一到真实终端就报错”这种割裂感。我在实际使用中特别看重这一点因为 Agent 最怕的就是环境不一致导致的隐性失败——它以为自己在 A 环境实际在 B 环境改出来的东西全是错的。2.3 CLI 带来的可组合性命令行的另一个隐性优势是可组合。Claude Code 可以作为一个命令被其他脚本调用可以把它的输出管道给别的工具可以用 shell 的串起一连串操作。这种 Unix 哲学式的设计让它可以嵌入到已有的自动化流程里而不是要求你为它单独开一个工作流。举个我实际用过的场景我写了一个脚本先用git diff --name-only拿到本次改动的文件列表然后把这个列表作为上下文传给 Claude Code让它针对这些文件做一轮代码审查。整个过程就是几行 shell没有任何“集成”成本。如果 Claude Code 是个图形应用这件事就得靠它自己提供 API 才能做到而 CLI 形态天然就有这个能力。形态扩展方式环境一致性可组合性学习成本CLI文本协议无限扩展与终端完全一致高可管道可脚本中需熟悉命令行IDE 插件受插件 API 限制依赖 IDE 环境低难被外部调用低图形化操作独立 GUI受 UI 框架限制独立环境易割裂极低低但功能受限这张表不是要贬低图形界面而是想说清楚形态选择取决于你要解决什么问题。如果你做的是“帮用户补全一行代码”插件形态更合适如果你做的是“让模型自主完成一个多步骤任务”CLI 几乎是唯一合理的选择。3. Agent 模式的核心从“回答问题”到“完成任务”3.1 Agent 和普通 LLM 调用的本质区别聊 Claude Code 绕不开 Agent 这个词。但 Agent 到底是什么很多人其实说不清楚。我的理解很简单普通 LLM 调用是“输入一段文本输出一段文本”Agent 是“输入一个目标输出一个完成状态”。这个区别听起来小实际影响巨大。普通调用里模型不需要关心自己的输出有没有用它只负责生成看起来合理的内容。Agent 模式里模型必须关心“我做的这件事有没有推进目标”因为它会看到自己操作的后果——文件改错了下一次读回来就是错的命令跑失败了返回的就是错误信息。这种基于反馈的循环是 Agent 和普通调用的分水岭。Claude Code 的 Agent 循环大致是这样的接收用户目标 → 分析当前状态 → 决定下一步动作 → 执行动作 → 观察结果 → 判断是否完成 → 未完成则回到第二步。这个循环里模型既是决策者也是执行者而宿主程序负责提供工具和反馈。3.2 工具调用是 Agent 的手脚Agent 要“动手”就必须有工具。Claude Code 暴露给模型的工具集基本覆盖了开发场景的核心操作读文件、写文件、搜索、执行命令、列目录。这些工具的设计有个共同原则粒度要合适。什么叫粒度合适太粗了不行比如给一个“重构这个模块”的工具模型没法控制具体怎么改太细了也不行比如给一个“在第 37 行第 12 列插入字符”的工具模型得先算半天位置。Claude Code 的工具粒度基本是“文件级”和“命令级”——读整个文件、写整个文件、跑一条命令。这个粒度让模型有足够的控制力又不至于陷入细节泥潭。注意工具粒度是 Agent 设计里最容易踩坑的地方。我见过不少项目把工具做得太细结果模型要完成一个简单任务得调用十几次工具token 消耗爆炸还容易在中途迷失目标。宁可粗一点让模型用多次调用组合出复杂行为。3.3 计划与执行的分离Claude Code 在处理复杂任务时会先输出一个计划再逐步执行。这个设计我觉得特别值得借鉴。计划的价值不在于计划本身而在于它给了人一个介入点。如果模型直接闷头改代码你只能等它改完再看结果发现问题已经晚了。有了计划这一步你可以在它动手之前就看到“它打算怎么干”如果方向不对直接打断重来省下的不只是时间还有被改乱的文件。我在实际使用中凡是涉及三个以上文件的任务都会先看它的计划确认没问题再让它执行。这个习惯帮我避免了好几次“改了一半发现方向错了”的尴尬。从工程角度看计划与执行的分离还有个好处它把一次大决策拆成了多次小决策。模型在每一步执行后都能重新评估而不是一条路走到黑。这种“走走看看”的策略在不确定环境里比“一次性规划到底”要稳健得多。4. MCP 协议Agent 的能力边界如何扩展4.1 MCP 要解决的是什么问题MCP 这个词最近热度很高但很多人对它的理解停留在“又一个协议”。我的看法是MCP 解决的是 Agent 能力的“最后一公里”问题。前面说了Claude Code 内置了一批工具读文件、写文件、跑命令。但真实开发场景里你需要的能力远不止这些。你可能要查数据库、调内部 API、读某个特定格式的配置文件、操作某个专有系统。这些能力如果都塞进 Claude Code 内置工具里那这个工具会变得无比臃肿而且每加一个能力都要改核心代码。MCP 的思路是把能力提供方和 Agent 宿主解耦。你写一个 MCP Server声明你提供哪些工具Claude Code 作为 MCP Client 连上你就能用你的工具。整个过程不需要改 Claude Code 一行代码。这个设计跟 USB 的思路很像——电脑不需要知道每个外设内部怎么工作只要大家都遵守 USB 协议插上就能用。4.2 MCP 的协议结构MCP 协议本身不复杂核心就是几个概念Server、Client、Tool、Resource。Server 是能力提供方Client 是能力使用方比如 Claude CodeTool 是可被调用的操作Resource 是可被读取的数据。通信基于 JSON-RPC传输层可以是标准输入输出也可以是网络连接。这个设计里我觉得最妙的一点是Tool 的描述是自包含的。每个 Tool 都要声明自己的名字、用途、参数结构。Agent 拿到这些描述后自己决定什么时候调用哪个 Tool。这意味着你新增一个 MCP ServerAgent 不需要重新训练或重新配置它读一遍 Tool 描述就知道怎么用了。这种“即插即用”的能力扩展方式是 MCP 最大的价值。{ name: query_database, description: 执行只读 SQL 查询并返回结果, inputSchema: { type: object, properties: { sql: { type: string, description: 要执行的 SQL 语句仅支持 SELECT } }, required: [sql] } }上面是一个典型的 MCP Tool 定义。模型看到这段描述就知道有个叫query_database的工具接受一个sql参数用来查数据库。它会在需要查数据的时候自动调用。整个过程不需要人告诉它“你可以查数据库”它自己从工具列表里发现。4.3 什么时候该用 MCP什么时候不该用MCP 很强但不是所有场景都该上。我的经验判断标准是如果这个能力是通用的、可复用的、跟具体项目解耦的就做成 MCP Server如果是一次性的、跟当前任务强绑定的直接写在提示词或脚本里更省事。举个例子你公司有一套内部的工单系统你想让 Agent 能查工单状态。这个能力多个项目都会用到做成 MCP Server 很合理。但如果你只是这次任务需要读一个特定格式的日志文件写个一次性脚本让 Agent 调用就行没必要为它专门搭个 Server。提示MCP Server 的维护成本不低尤其是当 Tool 数量多起来之后描述写得好不好直接影响模型调用准确率。我见过因为 Tool 描述太模糊模型反复调错工具的情况。描述要写清楚“什么时候用”和“什么时候不用”这比写清楚参数更重要。5. 上下文管理Agent 的隐形战场5.1 为什么上下文是 Agent 的命门Agent 干活的过程本质上是一个不断累积上下文的过程。每读一个文件、每跑一条命令、每做一次修改都会往上下文里塞东西。而模型的上下文窗口是有限的塞满了就得丢东西丢错了就丢掉了关键信息Agent 就开始犯迷糊。Claude Code 在上下文管理上做了不少设计我觉得最核心的一条是按需读取而不是全量加载。它不会一上来就把整个项目读进来而是根据当前任务先看目录结构再决定读哪些文件。这个策略跟人处理陌生代码库的方式很像——先看 README再看目录再挑关键文件深入。5.2 上下文压缩的取舍当上下文快满的时候Claude Code 会做压缩。压缩的本质是“用更少的 token 表达同样的信息”。但压缩是有损的压得越狠丢的信息越多。这里的取舍很微妙压得太少上下文很快又满了压得太多Agent 忘了之前干了什么开始重复劳动或者做出矛盾的操作。我的观察是Claude Code 的压缩策略偏向“保留近期、摘要远期”。最近几轮的操作细节保留得比较完整早期的操作只留一个摘要。这个策略符合 Agent 的工作模式——近期操作跟当前决策最相关远期操作只需要知道“做过什么”就够了。5.3 实操中的上下文控制技巧在实际使用中有几个控制上下文的小技巧很管用。第一任务要拆小。一个任务如果需要读二十个文件不如拆成三个小任务每个任务读六七个文件做完一个再做下一个。这样每个任务的上下文压力都小Agent 也更专注。第二及时清理无关信息。如果 Agent 读了一个跟当前任务无关的大文件可以主动让它“忘掉”这个文件的内容避免占用上下文。第三用文件系统当外部记忆。让 Agent 把中间结果写到文件里需要的时候再读回来比一直放在上下文里更省空间。上下文策略适用场景优点风险全量加载小项目、单文件任务信息完整大项目直接爆窗口按需读取大多数场景节省上下文可能漏读关键文件摘要压缩长任务后期延长可用轮次丢失细节导致误判外部文件记忆多阶段任务上下文压力小文件管理复杂这张表里的策略不是互斥的实际使用中往往是组合着来。我的习惯是任务开始时按需读取任务中期如果上下文吃紧就启用摘要压缩任务后期把关键结论写到文件里为下一阶段做准备。6. 安全边界Agent 动手时的风险控制6.1 为什么 Agent 比聊天模型更需要安全设计聊天模型说错话最多是误导你。Agent 做错事是真的会改坏你的文件、跑错命令、删掉不该删的东西。这个区别决定了 Agent 的安全设计不能照搬聊天模型那套“内容过滤”思路而要从操作权限层面去控制。Claude Code 在这方面的设计核心是人在回路。对于读操作它基本放行因为读不会造成破坏。对于写操作和执行命令它会根据配置决定是否需要确认。这个设计承认了一个现实你没法预判 Agent 所有可能的操作所以只能在关键操作上设卡。6.2 权限分级的设计思路我理解 Claude Code 的权限设计大致分几档只读模式、需确认模式、自动模式。只读模式下 Agent 只能看不能改适合探索性任务需确认模式下每次写操作都要你点头适合敏感项目自动模式下 Agent 自主执行适合你信任它且任务明确的场景。这个分级的关键在于默认值的选择。默认太松新手容易出事默认太紧老手觉得烦。Claude Code 的默认值偏保守我觉得是对的——安全这件事宁可让老手多按几次确认也不能让新手一不小心把项目搞崩。注意不管权限设成什么级别涉及删除文件、强制推送、修改系统配置这类操作永远保持人工确认。我踩过的坑是有一次让 Agent 自动清理临时文件它把范围理解大了差点删掉源码目录。从那以后凡是删除类操作我一律手动确认。6.3 沙盒与隔离除了权限控制隔离是另一层保险。理想情况下Agent 的操作应该在一个受限环境里进行即使它做错了影响范围也可控。Claude Code 支持在容器或虚拟机里运行这样它改坏的东西不会波及宿主机。对于生产环境相关的任务我强烈建议用隔离环境别让 Agent 直接碰真实系统。这个思路其实跟测试环境是一个道理你在测试环境里随便折腾出事了重来就行生产环境必须小心翼翼。Agent 的操作也应该有类似的“测试环境”让它先在里面跑通确认没问题再应用到真实环境。7. 从 Claude Code 看 LLM 应用开发的通用经验7.1 形态选择要服务于任务本质Claude Code 选 CLI 不是因为它酷而是因为 Agent 任务本质上是发散的、多步骤的、需要与环境深度交互的。这个判断逻辑可以迁移到任何 LLM 应用开发上先想清楚你的任务是什么形态再决定产品是什么形态。任务是问答式的聊天界面就够任务是操作式的就得考虑怎么让模型能动手任务是流程式的就得考虑怎么编排多个步骤。我见过不少项目一上来就纠结“用哪个框架”“做什么界面”结果核心的任务流程都没想清楚。形态是果任务是因别搞反了。7.2 工具设计比模型选择更重要很多人把精力花在“选哪个模型”上但实际做下来工具设计对最终效果的影响往往比模型选择更大。同样一个模型工具描述写得清楚调用准确率能差出好几倍。工具的名字、描述、参数结构每一个细节都在影响模型的理解。我的经验是工具描述要像写给一个新同事看的文档。你得说清楚这个工具是干什么的、什么时候用、参数怎么填、有什么限制。别假设模型“应该能猜到”它猜不到。描述里多写一句“仅在 X 情况下使用”可能就避免了一类调用错误。7.3 反馈循环的质量决定 Agent 的上限Agent 的能力上限不取决于模型多聪明而取决于它得到的反馈有多准确、多及时。命令跑失败了返回的错误信息清不清晰文件改错了下一次读回来能不能发现这些反馈的质量直接决定了 Agent 能不能自我纠正。所以在设计 Agent 系统时我会特别关注反馈通道每个工具调用的返回信息是否足够诊断问题错误信息是否包含了修复所需的线索如果反馈太模糊Agent 就只能瞎猜再聪明的模型也救不回来。7.4 别追求全自动追求“恰到好处的介入”最后一条经验也是我觉得最重要的一条Agent 系统的目标不是全自动而是让人在合适的地方介入。全自动听起来很美但实际场景里人往往需要在关键决策点把关。Claude Code 的计划确认、写操作确认都是这种“恰到好处介入”的体现。我在自己的项目里也是这个思路让 Agent 处理它擅长的部分——探索、执行、验证但在方向性决策、高风险操作、模糊需求上留给人来判断。这种人机分工比追求全自动要务实得多也安全得多。8. 一些实操中踩过的坑和对应解法8.1 任务描述太模糊导致 Agent 跑偏最常见的坑就是任务描述太模糊。你说“优化一下这个模块”Agent 可能去改性能也可能去改可读性还可能去重构结构。它不知道你真正想要什么只能猜。我的解法是任务描述里必须包含验收标准。不说“优化模块”而说“把这个模块的响应时间降到 100ms 以内不改动对外接口”。有了明确的验收标准Agent 的行动就有了方向。8.2 上下文污染导致重复劳动第二个坑是上下文污染。Agent 在探索阶段读了一些后来证明无关的文件这些文件的内容一直占着上下文导致它后面做决策时被干扰。解法是在任务阶段切换时主动清理上下文。比如探索阶段结束后明确告诉 Agent“现在进入修改阶段之前读的探索性文件可以忽略”。这个动作看起来小但对 Agent 的专注度提升很明显。8.3 工具调用失败后的死循环第三个坑是工具调用失败后的死循环。Agent 调一个命令失败了它重试又失败再重试来回几次上下文就满了。解法是给工具调用设置重试上限并在连续失败后强制切换策略。比如同一个命令连续失败三次就要求 Agent 停下来分析原因而不是继续重试。这个机制需要在宿主程序层面实现不能指望模型自己意识到“我陷入循环了”。常见问题表现根因解法任务跑偏改的方向跟预期不符任务描述缺验收标准描述里写清楚完成条件重复劳动反复读同一批文件上下文污染阶段切换时清理上下文死循环同一操作反复失败重试缺重试上限宿主层设重试次数限制改坏文件修改范围超出预期权限过松写操作保持人工确认遗漏文件该改的没改探索不充分先让它列改动清单再执行这张表里的问题我在不同项目里基本都遇到过。解法不一定适用于所有场景但思路是通用的Agent 出问题往往不是模型不行而是系统设计没给它足够的约束和反馈。9. 如果想自己复现类似思路从哪里开始如果你看完这些想在自己的项目里做一个类似 Claude Code 的 Agent我的建议是从最小闭环开始。先做一个只能读文件、只能跑只读命令的版本让它能探索代码库、回答“这个功能在哪里实现的”这类问题。这个版本不涉及写操作安全风险低但能帮你把 Agent 循环、工具调用、上下文管理这些核心机制跑通。跑通只读版本后再加写操作但先做成“生成修改建议人工确认后应用”的模式。这个模式比全自动安全又能让你观察 Agent 的修改质量。等你对它的判断有信心了再逐步放开自动执行的范围。MCP 的接入可以放到最后。先把内置工具用好确认 Agent 的核心循环没问题再考虑通过 MCP 扩展能力。一上来就搞一堆 MCP Server容易把简单问题复杂化。最后说个我自己的体会做 Agent 系统最难的不是让模型变聪明而是让系统在模型不够聪明的时候也能稳住。好的 Agent 设计是在模型犯错时能及时发现、能纠正、能把损失控制在可接受范围内。Claude Code 的设计理念里这种“稳健优先”的思路贯穿始终这比它具体用了什么模型、支持了什么功能更值得借鉴。
解法)
