iOS AI 编程环境配置：Agent、Skill、Rules、Hook、Command

引言

随着 AI 编程助手（如 Claude Code、Cursor及国内IDE）的普及，团队面临一个共同问题：AI 生成的代码风格不一致、忽略项目规范、不了解业务逻辑。

本文将深入介绍 Agent、Skill、Rules、Hook、Command 五大组件的功能、原理和在 iOS 工程中的实战应用。

---

一、功能概述

1.1 Rules：编码规范的"宪法"

定义：Rules 是最基础的约束层，定义了 AI 在任何交互中都应遵守的规则（如编码规范、架构原则）。它类似于项目的"宪法"，始终生效，无需人工触发。

所在位置：

• Claude中项目根目录的CLAUDE.md就是一个全局的规范（通过/memory查看），包含了你对项目的所有"规则"设定；除此之外，还可以在.claude/rules/ 目录下创建多个模块化、按路径生效的规则文件，你可以为网络层、UI 层、数据库层分别设置独立的规则文件，而不必把所有规范塞进一个巨大的 CLAUDE.md 中。
• 其他工具则是使用的标准的agent.md作为规范，CLAUDE.md，也可以配置额外的rules。

iOS 典型配置 （/rules/ios-standards.md）：

# iOS 编码规范

## 命名规范
- 类名：前缀 + PascalCase（如 LLUserManager）
- 变量/方法：camelCase（如 fetchUserInfo）
- 常量：k + PascalCase（如 kMaxRetryCount）
- 私有方法：p_ + camelCase（如 p_handleNetworkError）

## 架构约束
- 使用 MVVM + Combine/SwiftUI
- 禁止在 ViewController 中直接发起网络请求
- 所有闭包必须使用 [weak self] 避免循环引用
- 敏感信息必须存储在 Keychain，禁止 UserDefaults

## 线程安全
- UI 更新必须在主线程
- 网络回调默认在后台线程，需要显式切回主线程

作用：确保 AI 生成的代码符合团队规范，降低 Code Review 成本。

---

1.2 Skills：可复用的"专业技能包"

定义 ：Skills 是封装了特定任务流程的可执行单元，需要通过 /skill 命令手动触发。它擅长执行固定流程的复杂任务。

iOS 典型 Skill （/skills/generate-viper-module/SKILL.md）：

---
name: generate-viper-module
description: 生成符合 VIPER 架构的完整模块代码
---

# VIPER 模块生成器

## 执行流程
1. 询问模块名称和业务描述
2. 自动生成以下文件：
   - {Module}ViewController.swift（视图层）
   - {Module}Presenter.swift（事件处理）
   - {Module}Interactor.swift（业务逻辑）
   - {Module}Router.swift（路由跳转）
3. 根据模块描述自动实现基础业务逻辑
4. 生成单元测试模板
5. 自动添加到 Xcode 项目（需执行后续脚本）

## 代码模板示例
```swift
// {Module}Presenter.swift
protocol {Module}PresenterProtocol: AnyObject {
    func viewDidLoad()
    func didTapConfirm()
}

class {Module}Presenter: {Module}PresenterProtocol {
    weak var view: {Module}ViewProtocol?
    var interactor: {Module}InteractorProtocol?
    var router: {Module}RouterProtocol?
    
    func viewDidLoad() {
        // 自动生成初始化逻辑
    }
}

作用：让 AI 能够批量生成符合架构规范的模块代码，效率提升 10 倍。

---

1.3 Agents：交互式"任务专家"

定义：Agents 是能进行多轮对话的子任务处理单元。当主任务需要深入分析、确认需求时，主会话会委托给 Agent 处理。

iOS 典型 Agent （.claude/agents/code-discovery.md）：

---
name: code-discovery
description: 代码逻辑梳理专家，负责分析遗留代码并提出疑问
tools: Read, Grep, Bash, Write
---

# 代码发现 Agent

## 职责
- 分析指定模块的代码逻辑
- 标注不清晰或有问题的代码段
- **主动向用户提问确认理解**

## 工作流程
1. 读取目标代码文件
2. 绘制调用关系图和数据流
3. 列出所有疑问点：
   - 这段重试逻辑的预期间隔是多少？
   - 这个金额计算是否考虑了精度问题？
   - 这个闭包是否会造成循环引用？
4. 等待用户确认后继续深入
5. 输出结构化分析报告

使用示例：

# 主会话中
你: /task code-discovery 分析 PaymentViewController.swift 的内存泄漏问题

# Agent 开始交互
Agent: 我发现了 3 个可能的内存泄漏点：
       1. 网络回调闭包未使用 [weak self]
       2. Timer 未在 deinit 中 invalidate
       3. NotificationCenter 未移除观察者
       请问这些是预期的设计吗？
你: 1 和 2 是问题，3 可以忽略（全局监听）
Agent: 明白了，我将生成修复方案...

作用：处理需要人类确认的复杂任务，避免 AI 盲目执行。

---

1.4 Hooks：确定性的"安全护栏"

定义 ：Hooks 是系统层面的钩子，在 AI 执行特定操作（如写文件、运行命令）前后自动触发。与 Rules 不同，Hooks 一定会执行，不会被 AI "遗忘"。

iOS 典型 Hook （.claude/hooks/pre-commit-check.sh）：

#!/bin/bash
# 在 AI 执行 Write/Edit 后触发，检查代码格式

input=$(cat)
file_path=$(echo "$input" | jq -r '.tool_input.file_path')

# 只检查 Swift 文件
if [[ "$file_path" == *.swift ]]; then
    # 运行 SwiftLint 自动修复
    swiftlint autocorrect --path "$file_path"
    
    # 检查是否有循环引用风险（捕获 self 未使用 weak）
    if grep -q "self\." "$file_path" && ! grep -q "\[weak self\]" "$file_path"; then
        echo "⚠️  警告：检测到可能的循环引用" >&2
        # 可以选择 exit 2 阻止操作
    fi
fi

exit 0

配置文件 （.claude/settings.json）：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "bash .claude/hooks/pre-commit-check.sh"
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "if": "tool_input.command matches 'pod (install|update)'",
        "hooks": [
          {
            "type": "command",
            "command": "echo '⚠️ 正在执行 CocoaPods 操作，请稍候...'"
          }
        ]
      }
    ]
  }
}

作用：强制执行团队规范，防止 AI 产生危险操作或格式问题。

---

1.5 Commands：快捷的"自定义指令"

定义 ：Commands 是预定义的快捷指令，用于简化常用操作。用户只需输入 /command-name 即可触发复杂的工作流。

iOS 典型 Commands （.claude/commands/review-pr.md）：

---
name: review-pr
description: 审查当前 PR 的代码变更
---

# PR 代码审查

## 执行步骤
1. 运行 `git diff main...HEAD` 获取变更
2. 逐文件分析：
   - 检查命名规范是否符合 iOS 标准
   - 检查是否有内存泄漏风险
   - 检查是否添加了必要的单元测试
3. 生成审查报告：
   - 🔴 严重问题（必须修复）
   - 🟡 警告（建议修复）
   - 🔵 优化建议
4. 输出 Markdown 格式报告

使用示例：

你: /review-pr

AI: 正在审查 PR #123...
     
     🔴 严重问题：
     - PaymentVC.swift:42 存在循环引用（闭包未使用 weak self）
     
     🟡 警告：
     - NetworkManager.swift:15 硬编码了 API URL，建议使用配置文件
     
     🔵 优化建议：
     - UserCell.swift:23 可以优化图片加载性能

作用：让常用复杂操作简化为一个命令，降低使用门槛。

---

1.6 MCP（Model Context Protocol）

MCP（Model Context Protocol） 是 Anthropic 推出的开放协议，用于连接 AI 与外部数据源、工具和服务。比如：github、figma、飞书文档等都有对应的工具。

场景例子：自动根据 Firebase Crashlytics 修复 Bug：

配置 Firebase MCP：

claude mcp add firebase -- npx @modelcontextprotocol/server-firebase \
  --project-id=my-ios-app

使用流程：

你: 根据最新的 Crashlytics 错误，修复崩溃问题

Claude: 正在查询 Firebase Crashlytics...
       发现 Top 1 崩溃：NSInvalidArgumentException
       位置：PaymentViewController.swift:42
       原因：传入的 orderId 为 nil
       
       正在修复...
       [自动生成修复代码]
       
       ✅ 已创建 PR #456，请 Review

1.7 Memory：AI 的"长期记忆"

每个 会话都从一个全新的上下文窗口开始。两种机制可以跨会话传递知识：

• CLAUDE.md 或agent.md文件：你自己编写的指令，为 会话 提供持久上下文
• 自动记忆： AI根据你的更正和偏好编写的笔记

场景例子：记住团队的编码偏好

初始对话：

你: 我不喜欢用 guard 做参数校验，我喜欢用 if 提前 return
Claude: 明白了，我会记住这个偏好。
       [自动写入记忆：用户偏好 if 而非 guard]

下次会话：

你: 实现一个 validateEmail 函数
Claude: [检索记忆：用户偏好 if 而非 guard]
       
       func validateEmail(_ email: String) -> Bool {
           if email.isEmpty { return false }
           if !email.contains("@") { return false }
           return true
       }
       
       ✅ 已按你的偏好使用 if 提前 return

二、实现原理

2.1 Rules 的实现机制

用户输入 → 加载 Rules 文件 → 注入 System Prompt → AI 推理 → 输出
                ↓
        .claude/rules/*.md
        (glob 匹配规则)

原理 ：Claude Code 在启动时会扫描 .claude/rules/ 目录，将所有 .md 文件内容附加到系统提示词（System Prompt）的末尾。由于系统提示词在整个会话中固定不变，Rules 中的约束会持续生效。

关键参数：

• globs：指定规则应用的 file pattern（如 **/*.swift）
• alwaysApply：设为 true 时强制生效

2.2 Skills 的实现机制

用户输入 /skill-name 
    ↓
解析对应的 SKILL.md 文件
    ↓
提取 frontmatter（name, description）
    ↓
将 SKILL.md 正文作为子任务 Prompt
    ↓
AI 按步骤执行（可能调用工具）
    ↓
返回结果给用户

原理 ：Skills 本质上是"Prompt 模板 + 执行步骤"的封装。当用户触发 /skill 时，Claude Code 会：

1. 读取 SKILL.md 的 frontmatter 获取元数据
2. 将正文内容作为额外的系统指令注入
3. AI 严格按照步骤执行（工具调用、代码生成等）

2.3 Agents 的实现机制

主会话: /task agent-name "任务描述"
    ↓
创建子会话（独立上下文）
    ↓
加载 agent-name.md 作为 System Prompt
    ↓
Agent 执行工具调用，与用户交互
    ↓
完成后返回摘要给主会话

原理 ：Agents 是独立的会话实例 ，拥有自己的上下文窗口和工具权限。主会话通过 /task 命令启动 Agent，Agent 执行完后将结果写回文件或返回摘要，主会话再继续。

关键特性：

• 隔离性：Agent 不会污染主会话上下文
• 持久化：对话历史保存在 .claude/agent-memory-local/ 中
• 多轮交互：Agent 可以主动向用户提问

2.4 Hooks 的实现机制

工具执行请求（如 Write 文件）
    ↓
PreToolUse Hook 触发
    ├─ 执行脚本 → exit 0（放行）/ exit 2（阻止）
    ↓
实际执行工具
    ↓
PostToolUse Hook 触发
    ├─ 执行脚本（异步或同步）
    ↓
返回结果给用户

原理 ：Hooks 是 Claude Code 内置的事件系统，通过监听工具生命周期实现。当特定事件（如 PreToolUse、PostToolUse）触发时，系统会：

1. 准备 JSON 格式的上下文数据
2. 通过 stdin 传递给 Hook 脚本
3. 根据脚本的退出码决定后续行为
4. exit 0 继续执行，exit 2 阻止并返回错误

2.5 Commands 的实现机制

用户输入 /command-name
    ↓
扫描 .claude/commands/*.md
    ↓
匹配 name 字段
    ↓
将 Markdown 正文作为临时指令
    ↓
AI 执行并返回

原理：Commands 是 Skills 的轻量化版本，区别在于：

• Commands 通常不包含复杂的多步骤流程，而是单次快捷操作
• Commands 的 frontmatter 更简单（只需 name 和 description）
• Commands 执行后不会修改会话状态

2.6 MCP的实现机制

MCP 采用 客户端-服务器架构，AI编程工具 作为 MCP Client，通过标准 JSON-RPC 协议与 MCP Server 通信。

graph LR A[Agentic Coding客户端] -->|JSON-RPC| B[MCP Server] B -->|Tool 调用| C[数据库/API/文件] C -->|数据返回| B B -->|结构化结果| A

2.7 Memory的实现机制

Memory 的核心是向量数据库 + RAG（检索增强生成） ：

graph TD A[用户对话] --> B{Claude 判断} B -->|重要信息| C[提取记忆条目] C --> D[向量化存储] E[新对话开始] --> F[加载记忆向量] F --> G[相似度检索] G --> H[注入 System Prompt] H --> I[Claude 获得上下文]

记忆的写入触发条件：

• 用户明确说"记住..."
• 用户重复强调某个偏好（如"我不喜欢用 guard"）
• 重要的架构决策（如"我们决定改用 SwiftUI"）
• 项目特定的约定（如"网络层使用 Moya"）

记忆的读取时机：

• 每个新会话开始时
• 当 AI 判断需要历史信息时
• 执行特定任务（如 /memory 命令）

---

三、应用场景举例

3.1 场景一：接手 5 年前的 Objective-C 遗留代码

问题：代码无注释、命名混乱、架构过时（MVC + 庞大 ViewController）。

解决方案：

1. 创建 Code Discovery Agent：

# 分析 LegacyCodeAgent
- 读取指定文件
- 列出所有未使用的变量、方法
- 标注违反现行规范的地方
- 输出迁移建议（Swift + MVVM）

2. 配合 Rules 约束：

## 旧代码迁移规则
- 新增代码必须使用 Swift
- 禁止在旧 VC 中添加新逻辑
- 每个迁移模块必须达到 80% 测试覆盖率

3. 执行流程：

/task analyze LegacyPaymentVC.m
# Agent 输出 47 个问题点...
/skill migrate-to-swift LegacyPaymentVC
# 自动生成 Swift 版本的 ViewModel + View
/hook post-migration-check # 自动运行 SwiftLint

---

3.2 场景二：多团队协作的组件化开发

问题：基础组件团队、业务团队使用不同规范，AI 经常生成违规代码。

解决方案：

1. 分层 Rules：

.claude/rules/
├── base/           # 全项目通用（命名、格式）
│   └── swift-style.md
├── module/         # 组件化规范
│   └── component-api.md
└── team/           # 业务团队定制
    └── payment-team.md (globs: "Modules/Payment/**/*.swift")

2. Hooks 自动检查：

{
  "PostToolUse": {
    "matcher": "Write|Edit",
    "command": ".claude/hooks/check-module-boundary.sh"
  }
}

脚本检测是否有业务代码直接调用基础组件的私有 API，违反则阻止提交。

3. 效果：Code Review 通过率从 60% 提升至 95%。

---

3.3 场景三：AI 辅助的自动化测试生成

问题：团队测试覆盖率仅 30%，手动补充工作量大。

解决方案：

1. 创建 Test Generation Skill：

# generate-xctest
1. 读取源文件，提取所有 public 方法
2. 分析输入参数类型和返回值
3. 生成 XCTestCase 模板：
   - 正常情况测试
   - 边界值测试
   - 错误处理测试
4. 自动添加到测试 Target

2. 配合 Hook 自动触发：

{
  "PostToolUse": {
    "matcher": "Edit",
    "if": "file_path matches 'Sources/.*\\.swift'",
    "hooks": [{
      "type": "command",
      "command": "auto-generate-tests.sh"
    }]
  }
}

3. 成果：3 周内测试覆盖率提升至 78%，发现 12 个隐藏 Bug。

---

四、总结与最佳实践

组件	何时使用	典型场景
Rules	需要永久约束时	编码规范、架构约束
Skills	流程固定、可复用	生成模块、自动化重构
Agents	需要多轮确认	分析遗留代码、需求澄清
Hooks	需要强制执行	安全检查、自动格式化
Commands	单次快捷操作	PR 审查、运行测试

最佳实践建议：

1. 80% 规范用 Rules，保持简洁
2. 复杂工作流封装为 Skills，提升复用性
3. 危险操作前置 Hook 检查，确保安全
4. Agent 只用于需要人类判断的任务
5. 将配置提交到 Git，团队共享

配置好这套体系后，AI 编程助手将不再是"只会写代码的工具"，而是真正理解项目上下文、遵守团队规范的"虚拟团队成员"。

---

参考资料

• Claude Code 官方文档：docs.anthropic.com/claude-code
• iOS 编码规范参考：github.com/raywenderli...
• SwiftLint：github.com/realm/Swift...
• # 团队知识沉淀：通过 Qoder 积累项目专属的开发模式