在 Xcode 中与智能体协作开发

一句话判断

Xcode 27 的编码智能体 (Coding agents) 终于从“只会补全代码的打字员”变成了“能读懂祖传代码并自己拆包分发的包工头”。

这场 Session 讲了什么

以前我们在 Xcode 里用 AI，基本就是选中几行代码让它重构，或者让它写个正则。一旦涉及到跨文件、跨模块的需求，AI 就成了瞎子。Xcode 27 彻底改变了这个局面。现在的智能体拥有全局视野，它能通过 Apple Document Search 查阅框架文档，还能把你接手的新项目扒个底朝天，自动生成架构文档 (Architecture documents)。

对独立开发者和经常要接手“屎山”代码的团队来说，这简直是救命稻草。你不再需要花三天时间去理清一个陌生项目的数据流，直接让智能体给你画个流程图并生成 Markdown 知识库。更狠的是它的编排 (Orchestrate) 能力，你只需丢给它一个“把整个 App 做无障碍适配”的高层指令，它会自动拆解任务，唤醒多个子智能体 (Sub-agents) 并行干活。

值得深挖的点

架构文档 (Architecture Documents)：把 AI 的“脑补”变成团队资产

Apple 这次最聪明的设计，不是让 AI 写代码更快，而是让 AI 的“阅读理解”可复用。以前我们用第三方 AI 工具聊完一个复杂的项目结构，关掉对话框，AI 的上下文就丢了，下次还得重新消耗巨量 Token 去扫库。

Xcode 27 引入了架构文档机制。当你让智能体探索项目时，它会把数据模型、视图层级、核心数据流整理成 Markdown 文件，直接塞进你的工程目录里。这解决了 AI 开发最大的痛点：上下文遗忘。下次你或你的同事开启新对话，智能体会优先读取这些架构文档，瞬间“恢复记忆”。

不过这里的 Trade-off 很明显：代码改了，文档没更新怎么办？Apple 目前的方案是依赖智能体在修改代码时顺便更新文档，但在大型项目中，这极易导致文档和代码脱节。实战中，最好把架构文档纳入 Code Review 的强制检查项，或者写个 CI 脚本定期让智能体重新生成。

子智能体 (Sub-agents) 编排：告别“改了一处崩了全局”

当你让 AI 去做“全局本地化”或者“全面接入 SwiftData”这种大活时，单线程的 AI 往往会因为上下文窗口爆炸而开始胡言乱语，或者改了 A 文件忘了 B 文件。

Xcode 27 的编排模式让主智能体变成了项目经理。它接收高层目标后，会自己去发现需要的工具，然后 spawn 出多个子智能体并行处理。比如一个子智能体专门改 Info.plist，另一个专门扫 Swift 文件抽离硬编码字符串。这极大提高了执行速度，也避免了单一上下文被无关细节污染。

但这也有个坑：多个子智能体如果同时修改同一个文件（比如都在改 App.swift），极大概率会产生合并冲突 (Merge conflicts)。Apple 在演示中轻描淡写地略过了这点，但在实际业务中，你必须在 Prompt 里明确划定各个子智能体的“势力范围”，禁止它们跨界修改。

代码片段

1. 用内联注释 (Inline annotations) 精准控制 UI 微调

场景：在 SwiftUI 中，用自然语言描述 UI 修改意图，让智能体直接定位修改，而不是在聊天框里扯皮。

struct WorkoutInsightsView: View {
    var body: some View {
        VStack {
            // @agent: 把这里的柱状图换成折线图，并且加上平滑曲线效果，颜色用 accentColor
            Chart(workouts) { workout in
                BarMark(
                    x: .value("日期", workout.date),
                    y: .value("消耗", workout.calories)
                )
            }
            
            // @agent: 这里加一个 Summary 卡片，显示本周平均消耗，样式参考 SettingsView 里的卡片
            Text("本周数据")
        }
    }
}

坑：内联注释只适合局部微调。如果你在这里写“重构整个页面的状态管理”，智能体会把整个文件改得面目全非。

2. 引导智能体读取自定义架构文档

场景：在开启复杂任务前，强制智能体先读取你沉淀的架构文档，避免它瞎猜项目结构。

<!-- Architecture.md -->
# 项目架构指南

## 数据层
- 所有网络请求必须通过 `NetworkService` 单例发起。
- 数据库操作统一使用 `Repository` 模式，禁止在 View 中直接调用 SwiftData 的 `ModelContext`。

## 视图层
- 复杂列表必须使用 `List` 配合 `.id()` 优化，禁止在 `ScrollView` 里套 `ForEach`。

<!-- @agent: 在实现新的“历史记录”功能时，严格遵守上述架构规范，先输出实现计划，我确认后再写代码 -->

坑：架构文档不要写成废话文学。AI 对“保持代码整洁”这种话免疫，你必须给出具体的规则（如“禁止在 View 中直接调用 ModelContext”）。

最佳实践

已有项目的迁移策略：别一上来就让智能体重构核心逻辑。先让它跑一遍 Explore 流程，生成项目的架构文档。人工 Review 这些文档，修正 AI 理解错的地方，把这份文档作为后续 AI 协作的“基准线”。
新项目的采用建议：把智能体当成一个记忆力很好但缺乏业务常识的 Junior 开发。使用 Plan mode (计划模式) 让它先出方案，你通过 Queued messages (排队消息) 实时纠偏，确认架构没问题了再让它动手写代码。
实战避坑：千万别在聊天框里发几百字的长篇大论。把需求拆碎，利用 Xcode 的 Preview 和 Test 工具做闭环验证。AI 改完一步，立刻跑一次测试，别等它改完十个文件再跑，那时候报错你都找不到是哪一步引入的。

还有什么值得关注

图片附件 (Image attachments) 辅助设计：可以直接把 Figma 截图或者手绘草图拖进 Xcode 聊天框，智能体能看懂设计意图并生成高度还原的 SwiftUI 代码，比用嘴描述“左边留白 20，圆角 12”高效得多。
Apple Document Search 集成：智能体现在能直接查阅 Apple 官方文档，这意味着它写出的 API 调用终于不再是基于过时训练数据的幻觉了，新框架的采纳率会大幅提升。
Realistic previews (真实预览)：在迭代 Swift Charts 等复杂 UI 时，智能体生成的预览不再是占位符，而是带有模拟真实数据的渲染图，所见即所得的体验更连贯。