最近Claude Code大火，火的原因不简单是Vibe编程神器本身，更重要的是它正在重新定义智能体的开发范式，过去利用胶水代码或者拖拉拽方式构建的传统（面向过程)智能体，或将被那种只需要描述结果，交给持续循环运行达成目标的Agent原生智能体所颠覆。
Claude Code配合恰到好处的的插件、Skills等机制证明了一个好的编程智能体就是一个好的通用智能体。让智能体重构代码库的架构，同样能让它整理文件、管理阅读列表或自动化工作流程。
近日，Dan Shipper与Claude联合发布的《Agent-Native Architecture》技术指南，详述了这种全新的智能体构建方式，提出Agent原生架构的五大核心原则和一些值得探讨的细节。
五大核心原则
1. 对等性（Parity）
用户能通过UI完成的操作，智能体都应该能通过工具实现。
这是基础原则。没有它，其他都免谈。确保智能体拥有能完成UI所有功能的工具。
测试方法：选择任何UI操作，智能体能完成吗？
2. 粒度（Granularity）
工具应该是原子性基础功能，特性则是智能体通过循环操作达成的结果。
工具是基础能力，特性是提示词中描述的结果，由配备工具的智能体循环运行直到达成。
判断标准：改变行为时你是在编辑提示词还是重构代码？
3. 可组合性（Composability）
有了原子工具和对等性，你就能通过编写新提示词创造新功能。
想要"周报"功能？只需一个提示词："回顾本周修改的文件，总结关键变化。基于未完成项目和临近截止日期，建议下周三个优先级。"
智能体使用list_files、read_file和它的判断能力。你描述了结果，智能体循环直到达成。
4. 涌现能力（Emergent Capability）
智能体能完成你没有明确设计的任务。
运作循环：
-
用原子工具和对等性构建 -
用户要求你没预料到的功能 -
智能体组合工具来完成，或失败后暴露差距 -
观察请求模式 -
添加领域工具或提示词优化常见模式 -
重复
测试标准：它能处理你领域内的开放式请求吗？
5. 自我改进（Self-improvement）
Agent原生应用通过累积上下文和提示词优化而改进，无需发布代码。
累积上下文：状态通过上下文文件跨会话保持
开发者级优化：为所有用户发布更新的提示词
用户级定制：用户为自己的工作流修改提示词
文件作为通用接口
关键洞察是"文件作为通用接口"的设计理念。在传统软件中，API承担系统间通信工作。在智能体原生架构中，文件成为更自然的交互媒介。
为什么选择文件？
智能体天然擅长：智能体已经了解cat、grep、mv、mkdir，文件操作是它们最熟练的基础功能。
用户可见：用户能看到智能体创建了什么，可以编辑、移动、删除。没有黑盒。
便携性强：导出轻松，备份轻松，用户拥有自己的数据。
跨设备同步：在移动端配合iCloud，所有设备共享同一文件系统。智能体的工作出现在各处，无需构建服务器。
自文档化：/projects/acme/notes/比SELECT * FROM notes WHERE project_id = 123更易理解。
目录结构设计
Documents/
├── AgentCheckpoints/ # 临时文件
│ └── {sessionId}.checkpoint
├── AgentLogs/ # 调试日志
│ └── {type}/{sessionId}.md
└── Research/ # 用户工作区
└── books/{bookId}/
├── full_text.txt
├── notes.md
└── agent_log.md上下文注入模式
# Context
## Who I Am
Reading assistant for the Every app.
## What I Know About This User
- Interested in military history and Russian literature
- Prefers concise analysis
## What Exists
- 12 notes in /notes
- three active projects
## Recent Activity
- User created "Project kickoff" (two hours ago)
## My Guidelines
- Don't spoil books they're reading
- Use their interests to personalize insights智能体在每次会话开始时读取这个文件，随着状态变化更新它——无需代码变更的便携工作记忆。
移动端的独特机遇与挑战
机遇
文件系统支持：智能体能自然使用文件，采用在其他地方同样有效的基础功能。
丰富的设备上下文：围墙花园的访问权限。健康数据、位置、照片、日历——桌面端或网页端不存在的上下文。
本地应用：每个人都有自己的应用副本。应用可以自我修改、自我分叉、按用户演化。
应用状态同步：通过iCloud，所有设备共享同一文件系统。智能体的工作出现在所有设备上——无需服务器。
挑战
智能体是长时间运行的，移动应用却不是。
智能体可能需要30秒、5分钟或1小时来完成任务。但iOS会在几秒钟不活动后将应用置于后台，可能完全终止应用以回收内存。
这需要精心设计：
检查点机制：保存状态以免丢失工作
恢复功能：中断后从离开的地方继续
后台执行：明智使用iOS给予的有限时间
本地vs云端：决定什么在本地运行vs什么需要服务器
检查点和恢复实现
struct AgentCheckpoint: Codable {
let agentType: String
let messages: [[String: Any]]
let iterationCount: Int
let taskListJSON: String?
let customState: [String: String]
let timestamp: Date
}
func isValid(maxAge: TimeInterval = 3600) -> Bool {
Date().timeIntervalSince(timestamp) < maxAge
}检查点时机：应用后台化时、每次工具结果后、长操作期间定期保存
恢复流程：
-
loadInterruptedSessions()扫描检查点目录 -
按isValid(maxAge:)过滤 -
显示恢复提示 -
恢复消息并继续智能体循环 -
关闭时删除检查点
高级模式：动态能力发现
传统的静态映射问题：
// 为50种数据类型构建50个工具
read_steps()
read_heart_rate()
read_sleep()
// 添加新指标时...需要代码变更
// 智能体只能访问你预期的内容动态能力发现：
// 两个工具处理一切
list_available_types() → 返回 ["steps", "heart_rate", "sleep", ...]
read_data(type) → 读取任何发现的类型
// 添加新指标时...智能体自动发现
// 智能体能访问你构建时不知道的功能这是粒度原则的逻辑结论。你的工具变得如此原子化，以至于能处理你构建时不知道存在的类型。
适用场景：
-
你希望智能体拥有完整用户级访问权限的外部API（HealthKit、HomeKit、GraphQL端点） -
随时间添加新能力的系统 -
你希望智能体能做API支持的任何事情
实现模式详解
共享工作空间
智能体和用户应该在同一数据空间中工作，而不是独立的沙盒。
UserData/
├── notes/ ← 智能体和用户都在此读写
├── projects/ ← 智能体可以整理，用户可以覆盖
└── preferences.md ← 智能体读取，用户可以编辑好处：
-
用户可以检查和修改智能体的工作 -
智能体可以基于用户创建的内容构建 -
无需同步层 -
完全透明
这应该是默认选择。只有在特定需求时才使用沙盒（安全性、防止关键数据损坏）。
智能体执行模式
完成信号：智能体需要明确的方式说"我完成了"。不要通过启发式检测完成。
struct ToolResult {
let success: Bool
let output: String
let shouldContinue: Bool
}
.success("Result") // 继续
.error("Message") // 继续（重试）
.complete("Done") // 停止循环模型层级选择：不是所有智能体操作都需要相同的智能水平。
|
|
|
|
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
智能体到UI通信
当智能体行动时，UI应该立即反映。聊天集成的事件类型：
enum AgentEvent {
case thinking(String) // → 显示为思考指示器
case toolCall(String, String) // → 显示正在使用的工具
case toolResult(String) // → 显示结果（可选）
case textResponse(String) // → 流式传输到聊天
case statusChange(Status) // → 更新状态栏
}关键原则：没有静默操作。智能体的变化应该立即可见。
静默的智能体感觉像坏了。可见的进度建立信任。
产品层面的影响
渐进式披露
简单开始但无限强大。基础请求立即生效。高级用户可以向意想不到的方向推进。
Excel是典型例子：购物清单或财务模型，同一个工具。Claude Code也有这种特质。界面保持简单；能力随需求扩展。
-
简单入口：基础请求无学习成本即可生效 -
可发现的深度：用户探索时发现新能力 -
无上限：高级用户推向你未预期的方向
潜在需求发现
构建强大基础。观察用户要求智能体做什么。将出现的模式形式化。你在发现，而非猜测。
传统产品开发：想象用户需要什么，构建它，看看是否正确。
智能体原生产品开发：构建强大基础，观察用户要求智能体做什么，将出现的模式形式化。
当用户要求智能体做某事并成功时，这是信号。当他们要求但失败时，这也是信号——揭示了你工具或对等性的差距。
反模式警告
常见的非完全智能体原生方法
使用这些方法不一定错误，但它们与Agent原生架构倡导有所不同。
智能体作为路由器：智能体分析用户想要什么，然后调用正确的函数。智能体的智能被用来路由，没有用来行动。
先构建应用，再添加智能体：你用传统方式构建功能，然后将它们暴露给智能体。智能体只能做你的功能已经能做的事情。
请求/响应思维：智能体获得输入，做一件事，返回输出。这错过了循环：智能体获得要实现的结果，操作直到完成。
防御性工具设计：你过度约束工具输入。严格的枚举，每层都有验证。这是安全的，但阻止了智能体做你没有预料到的事情。
代码中的快乐路径，智能体只是执行：传统软件在代码中处理边缘情况。Agent原生让智能体用判断处理边缘情况。
具体反模式实例
智能体执行你的工作流，没有追求结果：你编写了逻辑，智能体只是调用它。决策存在于代码中，没有在智能体判断中。
工作流形状的工具：analyze_and_organize将判断打包到工具中。将其分解为原语，让智能体组合它们。
孤立的UI操作：用户可以通过UI做某事，但智能体无法实现。解决方法：维护对等性。
上下文饥饿：智能体不知道存在什么。用户说"整理我的笔记"，智能体不知道有笔记。解决方法：在系统提示中注入可用资源和能力。
启发式完成检测：通过启发式检测智能体完成是脆弱的。解决方法：要求智能体通过完成工具明确信号完成。
成功标准检查清单
架构层面
-
[ ] 对等性：智能体能实现用户通过UI能做的任何事情 -
[ ] 粒度：工具是原子性原语；领域工具是快捷方式，没有门控作用 -
[ ] 可组合性：可以通过编写新提示词添加新功能 -
[ ] 涌现能力：智能体能完成你没有明确设计的任务 -
[ ] 行为修改方式：改变行为意味着编辑提示词，避免重构代码
实现层面
-
[ ] 系统提示包含可用资源和能力：智能体知道当前环境中存在什么 -
[ ] 共享数据空间：智能体和用户在同一个数据空间中工作 -
[ ] 实时反馈：智能体的行动立即在UI中反映 -
[ ] 完整的CRUD能力：每个实体都有完整的创建、读取、更新、删除能力 -
[ ] 动态能力发现：在适当情况下，外部API使用动态能力发现 -
[ ] 明确的完成信号：智能体明确表示完成
产品层面
-
[ ] 渐进式披露：简单请求立即生效，无需学习成本 -
[ ] 无限扩展：高级用户可以将系统推向意想不到的方向 -
[ ] 需求发现：通过观察用户要求智能体做什么来了解用户需求 -
[ ] 合理的批准机制：批准要求与风险和可逆性相匹配
移动端
-
[ ] 检查点/恢复机制：处理应用中断 -
[ ] iCloud优先存储：带本地回退的云存储策略 -
[ ] 后台执行：明智使用有限的后台时间
终极测试
向智能体描述一个在你应用领域内但你没有构建特定功能的结果。
智能体能想办法完成它吗？能在循环中操作直到成功吗？
如果能，你构建的就是Agent原生的。
如果不能，你的架构过于受限。
这个测试的核心在于验证涌现能力。真正的Agent原生应用不仅能执行预编程的功能，还能通过组合现有工具来解决新问题。这种能力的存在表明你给了智能体足够的原子工具和判断空间，让它能够应对未预期的需求。
小结
Claude Code可以说是一个被名字耽误的通用智能体产品，过去的智能体开发方法或将被颠覆，分析它的设计理念，以及学习构建智能体的方法可以说是与时俱进，赢在2026年。
