Xcode 26.3 + Claude Agent：模型替换、MCP、Skill 与自适应配置

出乎意料，Xcode 26.3 版本中苹果直接提供了对 Claude Code/Codex 的支持。自此，开发者终于可以在 Xcode 中优雅地使用原生 AI Agent 了。这两天我针对新版本进行了一系列尝试，包括配置 MCP、以及编写自适应的 CLAUDE.md。本文将以 Claude Code 为例，分享一些文档之外的技巧。

🛠️ 硬核尝试：手动替换最新模型

Xcode 26.3 RC 自带的 claude 客户端版本为 2.1.14，对应模型 Opus 4.5。但此时此刻，Anthropic 其实已经发布了更强的 Opus 4.6 (v2.1.32)。

能不能让 Xcode 跑上最新模型？

我尝试将 ~/Library/Developer/Xcode/CodingAssistant/Agents/Versions/26.3 目录下的 claude 二进制文件，直接替换为 Anthropic 提供的最新 2.1.32 版本。

结果：在 Xcode 中将 Model 设置为 Opus 后，询问他是什么模型，会返回 4.6。考虑到客户端和模型版本通常是绑定的，这可以看作是一种“非官方升级”方式，让 Xcode 提前享受到 Opus 4.6 的能力。

🔌 为 Xcode 注入 MCP 支持

Xcode 默认会屏蔽开发者在系统全局配置的 MCP (Model Context Protocol)。如果你想让 Xcode 内置的 Agent 使用自定义工具（比如我常用的邮件处理工具），需要修改特定的配置文件。

配置文件路径： ~/Library/Developer/Xcode/CodingAssistant/ClaudeAgentConfig/.claude

配置示例：

JSON

"projects": {
    "/Users/yangxu/Development/DataNoteV3": {
      "mcpServers": {
        "mail": {
          "type": "stdio",
          "command": "/Users/yangxu/myenv/bin/python3",
          "args": ["/path/to/mail_mcp_server.py"],
          "env": { ... }
        }
      },
      "hasTrustDialogAccepted": true
    }
  }

配置后，在 Agent 面板输入 /context 即可验证 MCP 是否加载成功。

🧩 Skill 与 Command 的安装

Xcode 的 Claude Agent 会在以下路径查找扩展脚本：

Skill 查找路径：

~/Library/Developer/Xcode/CodingAssistant/ClaudeAgentConfig/skills
/Library/Application Support/ClaudeCode/.claude/skills

Command 查找路径： ~/Library/Developer/Xcode/CodingAssistant/ClaudeAgentConfig/commands

将脚本文件放入对应目录后，重启 Xcode 即可生效。

⚠️ 注意：

自定义 Command 目前不会出现在 / 的自动补全列表中，但直接输入指令名称即可执行。

查找已安装的 Skill 请使用 find-skill 指令（注意前面无需加 /）。

🔗 使用软连接同步配置

为了统一管理命令行环境与 Xcode 环境的配置，避免维护两份文件，推荐通过创建软连接（Symlink）的方式，将你现有的配置目录映射到 Xcode 的配置路径中：

Bash

# 示例：将本地标准配置的 commands 目录链接到 Xcode Agent 配置中
ln -s ~/.claude/commands ~/Library/Developer/Xcode/CodingAssistant/ClaudeAgentConfig/commands

这样，你在终端环境中对 Command 的更新，Xcode 中也能即时同步（重启后生效）。

🧠 进阶技巧：自适应的 Claude.md

由于我经常在 Xcode 内置 Agent 和 命令行 Claude Code 之间切换，两者的环境差异（特别是编译方式）导致一套 Prompt 很难通用。我采用了一种“环境感知”的策略。

1. 环境自适应

在根目录 CLAUDE.md 中，通过检测环境变量 CLAUDE_CONFIG_DIR 来区分当前是在 Xcode 内部还是在终端：

Markdown

## 🔍 环境自适应

本项目支持两种 Claude 开发环境:
- **Xcode 26.3+ Claude Agent SDK** - 使用 Xcode 内置 MCP 工具
- **Pure Claude Code** - 使用命令行 Claude Code

### 环境检测

通过检查环境变量 `CLAUDE_CONFIG_DIR` 判断当前环境:

- ✅ **包含 `Xcode/CodingAssistant`** → 使用 [CLAUDE-XCODE.md](CLAUDE-XCODE.md) 的配置
  - 示例: `~/Library/Developer/Xcode/CodingAssistant/ClaudeAgentConfig`
- ❌ **不包含或为其他路径** → 使用 [CLAUDE-PURE.md](CLAUDE-PURE.md) 的配置
  - 示例: `~/.config/claude` 或其他标准配置路径

2. 编译感知 (Context Awareness)

在 Xcode 环境下，SPM 的多 Target 结构往往让 AI 感到困惑。我在 CLAUDE-XCODE.md 中加入了 Scheme 检查机制：

Markdown

## 🎯 上下文感知开发规则

### 1. 自动检测上下文

当工作在某个 SPM 模块时:
1. 检查当前文件主要属于哪个模块 (如 `AppShared`, `DataNoteCore`)
2. 检查是否已切换到对应的 Scheme
3. 如未切换,提醒开发者切换到对应 Scheme

**提示模板**:
```
⚠️ 当前上下文主要涉及 [PackageName] 模块
建议切换到 Scheme: [PackageName] 或 [PackageName]Tests
```

### 2. 检查模块级 CLAUDE.md

切换 Scheme 后,检查对应目录是否有模块级配置:
- **文件系统路径**: `Modules/[PackageName]/CLAUDE.md`
- **Xcode 项目路径**: `DataNoteV3/Packages/[PackageName]/CLAUDE.md`
- 如果存在,应结合项目级和模块级指令工作

### 3. 优先使用对应 SPM 的 Scheme

- ✅ 在 `AppShared` 模块开发 → 使用 `AppShared` Scheme
- ✅ 在 `DataNoteCore` 模块开发 → 使用 `DataNoteCore` Scheme
- ✅ 修改持久化层代码 → 使用 `DataNotePersistent` Scheme

写在最后

Xcode 26.3 的这次更新无论是效果还是方向都令人满意。如果能进一步提高代码补全的能力，Xcode 很有希望在 AI 时代重新成为 Swift 开发者的首选 IDE。

未知的惊喜，往往带来更大的快乐。