AI Agent 从”能工作”到”真正好用”，中间隔着一套完整的架构思维。这篇文章整理了我们在实践中的观察和思考。

引言

Claude Code 证明了一件事：一个能访问 bash 和文件系统的大语言模型，以循环方式运行直到目标达成，就能独立完成复杂的多步骤任务——包括重构代码库、整理文件、管理工作流。

更意外的发现是：一个好的编码 Agent，本质上也是一个好的通用 Agent。驱动 Claude Code 重构代码库的那套架构，同样可以让它帮你整理下载文件夹、管理待读文章、或者跑自动化流程。

软件的设计逻辑正在发生根本变化。功能可以不再是你逐行写出来的代码，而是你描述的目标，交给带工具的 Agent 在循环中去执行，直到达成。

Dan Shipper 在 Every 上把这套思路系统化为”Agent-native 架构”。这篇指南已经影响了大量的开发者，从独立开发者到团队，都在重新思考软件应该怎么被构建。

一、为什么传统架构不够用

你做了一个 SaaS 产品，用户可以在界面里新建项目、上传文件、修改设置。听起来功能完整。但如果用户说：”帮我整理一下这个项目的笔记，按主题分组，再把相关的文件放到对应文件夹里。”

传统 SaaS 的应对方式：你得专门写一段代码来处理这个需求，部署上线，用户才能用它。而且这个过程每增加一个”整理”的变体，大概率还需要再改代码。

问题在于：你只能为用户预先设想到的功能买单。超出设计范围的需求，就永远在 backlog 里排队。

Agent-native 架构的思路完全不同。它不是替用户”执行”你写好的工作流，而是让 Agent 理解用户的意图，用工具组合去完成目标。你写出的是能力基元，功能是 Agent 在运行中涌现出来的。

二、Agent-native 的核心原则

1. 工具对等

用户能在 UI 里做的任何事，Agent 都应该能通过工具完成。

这是整座大厦的地基。如果存在只能用户在界面上操作而 Agent 做不到的事情，那 Agent-native 架构就立不起来。随便挑一个 UI 操作，问自己：Agent 能用工具完成它吗？如果你回答不了，那你的架构就有问题。

2. 原子化工具

工具应该是不可再分的基元。功能不是写在代码里的，而是在提示词里描述的目标，由 Agent 反复执行工具去达成。

看两种做法：

不推荐的做法：

工具：classify_and_organize_files(files)→ 要改变行为，你需要重构代码判断逻辑打进了工具里，灵活性受限

推荐的做法：

工具：read_file, write_file, move_file, bash提示词：”整理 downloads 文件夹……”→ 要改变行为，你编辑提示词就行Agent 带着判断去追求结果，灵活性大得多

想给产品加一个”每周回顾”功能？那只不过是一条新提示词：

“Review files modified this week. Summarize key changes. Based on the project state, suggest three priorities for next week.”

你描述了一个目标，Agent 循环直到完成它。你不需要事先设计这个功能。

3. 涌现能力发现

传统产品迭代靠发布新代码。Agent-native 应用不需要。改进通过积累上下文和优化提示词发生。状态跨会话持久化，提示词可以推送给所有用户，用户自己也能修改。

这意味着你不需要猜测用户想要什么功能。观察用户让 Agent 做什么，当模式出现时，用特定领域工具或提示词去优化。你不是在预设，而是在发现。

4. 上下文与提示词迭代

Agent 跨会话维护状态。知道什么文件存在、用户做了什么、什么方法有效。

提示词优化分为多层。开发者级更新推送给所有用户。用户级定制允许用户自己调整。进阶版本让 Agent 基于反馈自行调整提示词，这还在探索中，需要安全护栏、审批关卡、检查点、回滚路径。

5. 文件优先

Agent 天然擅长处理文件。Claude Code 之所以有效，就是因为 bash 加文件系统是经过最长时间验证的 Agent 接口。

文件系统作为接口的好处很直接。用户可以查看 Agent 创建了什么、编辑它、移动它、删除它，没有黑箱。导出和备份都很简单，用户拥有自己的数据。配合云同步，Agent 的工作在所有设备上可见，不需要额外建服务器。

一个朴素的标准：如果一个人通过查看你的文件结构能理解发生了什么，Agent 应该也能。

三、从原则到实践：三个真实案例

理论听起来不错，落地是另一回事。下面三个案例来自不同团队，用的都是同一套思路。

案例一：Cora——从程序员到指挥家

Kieran Klaassen 是 Cora 的负责人，一个 AI 邮件助手。过去两个月他写的每行代码都是 AI 生成的，不是 AI 辅助，是 AI 写的。Claude Code 开了他 100% 的 pull request，他已经几周没手打过函数，上线速度反而更快了。

真实场景：Cora 的后台任务队列突然不干活了，队列不断膨胀，应用经常崩溃。代码看起来没问题，日志也看不出异常，Claude Code 一开始也束手无策。

Kieran 换了个思路。他对 Claude Code 说：如果你查不出原因，问题可能出在生产环境上。然后让 Agent 去读 Ruby gem 的源代码。Claude Code 一行一行翻阅了几千行第三方代码，找到了开发环境下根本发现不了的问题。生产环境中任务队列用了不同的名字，就像包裹被送到了错误的仓库。

这个 bug 如果让人来查，要花几个小时翻不熟悉的代码。Claude Code 把它变成了协作。AI 做调研，人做判断。

更关键的是工作方式的转变。Kieran 的屏幕上同时跑着多个 Claude Code 实例，每个在不同的 git 分支上干不同的活。他说自己从程序员变成指挥家了。他不再想文件和函数，而是想功能和结果。重要的不是怎么写代码，而是怎么描述目标、怎么审核输出。

最极端的情况出现在他精疲力竭的时候。他用的一个 prompt 是：我脑子已经转不动了，但问题是这个。然后让 Claude Code 接手实现细节。

案例二：Devin——独立完成软件工程任务

Devin 是 Cognition Labs 推出的 AI 软件工程师。Devin 有自己独立的 Shell、代码编辑器和浏览器，一个完整的沙箱开发环境。它能规划并执行需要成千上万次决策的工程任务。

在 SWE-bench（一个要求 Agent 解决真实 GitHub issue 的基准）上，Devin 正确解决了 13.86% 的问题，远超之前 1.96% 的最佳水平。更重要的是，Devin 是在没有人类指定具体文件的情况下完成的，而其他模型都被告知了需要修改哪些文件。

Devon 能做的事包括：

• 阅读一篇博客文章后，学会使用一个全新的技术栈来运行计算机视觉模型

• 端到端构建并部署一个网页应用

• 自主发现并修复代码库中的 bug

• 在只给了一个 GitHub issue 链接的情况下，完成所有上下文收集和修复工作

每个步骤中，Devin 实时汇报进度、接受反馈、在需要时与人讨论设计方案。它不是一次性调用的，它在循环中运行，直到任务完成。

案例三：Dan Shipper 的 Reader——一个阅读助手背后的 Agent 架构

Dan Shipper 用这套架构构建了 Reader，一个 AI 阅读助手。核心不是预设的高亮或收藏功能，而是 Agent 在后台持续运行，理解用户正在读什么。

用户说”帮我总结一下这一章的关键论点”，Agent 读取文件内容，生成摘要。用户说”找一下上周提到拿破仑战役的那段内容”，Agent 导航到相关章节，定位内容，返回结果。用户说”把这篇和之前那篇关于图赫尔主义的文章做个对比”，Agent 读取两篇文章，分析异同。

这些功能在 Reader 上线时没有一个是被设计出来的。它们来自 Agent 原子化能力和灵活提示词的组合。

Reader 在真实用户手中产生了大量 Dan 和他的团队没有预料到的用法。他们观察用户让 Agent 做什么，发现新模式，再反过来优化提示词和工具集。

四、什么不是 Agent-native

这套架构很好，但也很容易被误解。以下是几种常见的”看起来像 Agent-native，实际不是”的做法：

Agent 作为搜索框。Agent 弄清楚用户想要什么，然后调一个函数返回结果，这只用到了 Agent 很小一部分能力。

Agent 作为薄 API 封装。你用传统方式构建功能，然后暴露给 Agent 调用。Agent 只能做你的功能已经能做的事，没有涌现能力，没有组合创新。

过度约束工具输入。严格的枚举类型、各层验证，这防止了 Agent 做你未预料到的事。你精心设计的防护恰恰扼杀了 Agent native 最宝贵的特性。

代码处理路径，Agent 只是执行者。传统软件在代码里处理边缘情况。Agent native 让 Agent 用判断来处理边缘情况。如果主流路径都写死在代码里，Agent 的价值就大打折扣。

一个简单的检验标准：向 Agent 描述一个结果，在你的产品领域范围内，但你没有为此构建特定功能。它能不能在循环中运行直到成功，自己找出完成的方法？如果能，你构建了 Agent native 的东西。如果不能，你的架构太受限了。

五、值得注意的实现细节

从基元到领域工具

以纯基元开始：bash、文件操作、基本存储。先证明架构能跑通，观察 Agent 实际需要什么。随着模式浮现，再逐步添加领域特定工具。

领域工具是快捷方式，不是关卡。除非有特定原因需要限制访问，比如安全、数据完整性，Agent 仍应能用底层基元处理边缘情况。默认是开放的，加限制应该是一个有意识的选择。

Agent 和用户共享同一个空间

Agent 和用户在同一个数据空间工作，而不是各自的沙箱。用户可以随时检查和修改 Agent 的工作，Agent 可以在用户创建的内容基础上继续构建。不需要同步层，没有数据孤岛。有特定需求时才用沙箱，比如安全原因，或者防止关键数据被误操作。

实时反馈，没有静默操作

Agent 的每一步操作，UI 都应该立即反馈。用户在界面上应该能看到 Agent 在想什么、正在用什么工具、结果是什么。任何在用户不知情的情况下发生的操作，都是设计缺陷。

完成信号

Agent 需要一个显式的方式来表明做完了。不要靠启发式方法去猜。

success 代表继续，error 代表继续重试，complete 代表停止循环。完成和成功失败是分开的。工具可以成功并停止循环，也可以失败并继续以恢复。

六、这条路通向哪里

Agent-native 架构不只是另一种技术选型。它改变的是你构建软件的方式。

你不是在提前想象每一个功能，而是在构建一个有能力的根基，然后从用户的实际使用中学习。你不是在猜用户想要什么，而是观察他们让 Agent 做什么。功能改进不一定要发代码，改提示词就够了。你的软件能处理你没有显式设计过的需求。

Kieran 说了一句很到位的话：你不是在做工作本身了，你是在指导工作。从程序员变成指挥家，从写代码变到描述目标。

对于创业团队来说，这意味着更快的学习速度、更低的试错成本、更灵活的产品形态。对于成熟团队来说，这意味着重新思考软件应该怎么被构建这个根本问题。

这轮变化才刚刚开始。那些从 Agent-native 角度重新理解自己产品的人，会走得更快。

这篇文章参考了 Dan Shipper 的 Agent native 架构指南，以及 Cora、Devin、Reader 等团队的实践案例。