# Claude Code 官方教程：提示词编写与 Agent 智能体搭建

> 演讲者：Boris Cherny，Anthropic 工程师，Claude Code 创建者

## Claude Code 简介

Claude Code 是一种新型的 AI 编程助手，与传统的代码补全工具（如 GitHub Copilot）不同，它是一个**全功能的 Agent（智能体）**，可以：

- 构建完整的功能（features）
- 编写整个函数和文件
- 修复整个 bug
- 自动串联使用各种工具

### 核心特性

| 特性 | 说明 |
|------|------|
| **跨 IDE 支持** | 支持 VS Code、Xcode、JetBrains 等所有主流 IDE |
| **跨环境支持** | 可在本地、远程 SSH、Container 等环境中运行 |
| **通用性** | 不需要改变现有工作流程 |
| **无需索引** | 代码留在本地，不上传到远程服务器 |
| **不训练模型** | 不使用用户代码进行训练 |

---

## 入门设置

### 基础配置

安装 Claude Code 后，官方推荐以下设置：

```bash
# 1. 设置终端（获得 Shift+Enter 换行功能）
/terminal setup

# 2. 切换主题
/slash themes  # 可选择 light/dark/zen 主题

# 3. 安装 GitHub App（可选）
# 在任意 GitHub issue 或 PR 中 @Claude）
/install github-app
```

### 工具权限自定义

```bash
# 自定义允许使用的工具集，避免每次都弹出确认
# 这样设置后不需要每次都手动批准工具调用
```

### 语音输入（Mac 用户）

1. 进入系统设置 → Accessibility → Dictation
2. 启用听写功能
3. **双击听写键**即可语音输入提示词

> 这对于编写详细的提示词非常有帮助，可以像与另一个工程师对话一样自然地描述需求。

---

## 第一步：Codebase Q&A（强烈推荐入门方式）

### 为什么从 Q&A 开始

这是 Anthropic 新员工入职培训的第一课：

- **降低学习门槛**：不需要了解任何复杂功能，只需要提问
- **了解 AI 边界**：帮助理解 Claude Code 能做什么、不能做什么
- **无需设置**：无需索引、无需配置，直接开始使用

### 效率提升数据

| 场景 | 传统方式 | 使用 Claude Code Q&A |
|------|---------|---------------------|
| 技术入职培训 | 2-3 周 | **2-3 天** |

### 可以问的问题类型

```text
# 代码使用问题
"How is this particular piece of code used?"
"How do I instantiate this thing?"

# Git 历史问题
"Look through Git history to explain why this function has 15 arguments"
# Claude Code 会自动：
# - 查找这些参数是如何引入的
# - 谁引入了这些更改
# - 当时的背景情况
# - 相关的 commit 和 issue

# GitHub Issues 问题
"Fetch issues related to this feature"
# 可以获取 issue 的上下文信息

# 工作进度查询
"What did I ship this week?"
# Claude Code 会查看 git log，自动总结本周的工作
```

> **重要提示**：Claude Code 理解这些请求**不是通过 System Prompt 指定的**，而是模型本身能力强的体现。

---

## 代码编辑功能

### Agent 工作原理

Claude Code 拥有一个小型工具集，它会自动串联使用这些工具：

1. **Edit files** - 编辑文件
2. **Run bash commands** - 运行命令
3. **Search files** - 搜索文件

### 推荐的代码编辑工作流

```
1. 让 Claude 先思考和规划
2. 让它向你展示计划
3. 征得你同意后再写代码
```

**推荐提示词模板**：

```text
"Before you write code, make a plan. Answer with the plan and ask for my approval before writing code."
```

> 这种方式可以避免"一次性实现3000行功能但完全不是想要的结果"的情况。

### 常见任务提示词

```text
# 自动创建分支、提交代码并推送到远程
"Think for this one. This commit push here."

# Claude Code 会：
# - 自动创建新分支
# - 分析 git history 和 git log 确定提交格式
# - 创建符合项目规范的 commit
# - 推送到远程
# - 创建 Pull Request
```

---

## 工具集成

### Batch 命令工具

**定义自定义 CLI**：

```bash
# 告诉 Claude Code 关于你的 CLI 工具
# Claude 会使用 --help 来了解工具用法

# 如果频繁使用，可以添加到 quilMD 中（持久化保存）
```

### MCP（Model Context Protocol）工具

Claude Code 支持 MCP 工具，可以集成团队已有的各种工具：

1. **告诉 Claude 关于工具的描述**
2. **添加 MCP 服务器配置**
3. Claude 会自动学习和使用这些工具

### 常见工作流

| 工作流 | 适用场景 | 说明 |
|--------|---------|------|
| **探索 → 规划 → 确认 → 写代码** | 复杂功能实现 | 适合需要仔细设计的功能 |
| **写代码 → 运行测试 → 迭代** | UI 开发 | Claude 可以看到测试结果并自我改进 |
| **截图/截图验证** | Web/iOS 开发 | Claude 可以用 Puppeteer 截图并迭代 |

**关键技巧**：给 Claude 一个**反馈工具**（如单元测试、截图验证），它可以自主迭代 2-3 次，通常能得到近乎完美的结果。

---

## 上下文管理（核心功能）

### quilMD 文件

quilMD 是 Claude Code 的特殊配置文件，可以放在多个位置：

| 位置 | 说明 | 是否提交到 Git |
|------|------|---------------|
| 项目根目录 | 所有会话自动读取 | ✅ 应该提交 |
| 本地 `.claude/` 目录 | 仅本地使用 | ❌ 不提交 |
| 嵌套子目录 | 仅在子目录工作时读取 | ✅ 应该提交 |
| 企业根目录 | 企业级配置，所有项目共享 | ✅ 企业管理 |

### quilMD 内容建议

```
# 推荐包含的内容
- 常用的 batch 命令
- MCP 工具配置
- 架构决策
- 重要的文件路径
- 代码风格指南

# 示例内容（Anthropic 实际使用的）
common bash commands: [...]
style guide: [...]
core files: [...]
```

> **保持简短**：quilMD 太长会消耗大量上下文窗口，通常不太有用。

### 企业级配置

```yaml
# 企业配置文件可以包含：
- 全局 s 命令
- 批量权限配置
- URL 黑名单（禁止访问的 URL）
- MCP 服务器配置
- 权限策略
```

**权限管理示例**：

```yaml
# 允许所有员工使用某个测试命令（自动批准）
allowed_commands:
  - test

# 禁止访问的 URL
blocked_urls:
  - https://internal.company.com/confidential
```

### 其他上下文引入方式

| 方式 | 语法 | 说明 |
|------|------|------|
| **@文件路径** | `@path/to/file` | 引入特定文件到上下文 |
| **s 命令** | `/command-name` | 可在主目录或项目中定义 |
| **嵌套 quilMD** | - | 在子目录中自动引入 |
| **# 记住** | `#remember something` | 让 Claude 记住某些偏好 |

---

## 快捷键与实用技巧

### 核心快捷键

| 快捷键 | 功能 |
|--------|------|
| **Shift+Tab** | 切换到**自动接受编辑模式**（建议用于运行测试、迭代时） |
| **Escape** | 停止 Claude 当前操作（安全操作，不会破坏会话） |
| **Escape + Escape** | 返回历史记录 |
| **↑ + F** | 查看完整输出（Claude 上下文窗口中的所有内容） |
| **!** | 进入 batch 模式，输入命令并进入上下文 |
| **#** | 让 Claude 记住某些偏好（会自动更新 quilMD） |

### 常用技巧

**1. 自动接受编辑模式**
```bash
# 适合场景：
# - 知道 Claude 在做正确的事
# - 运行单元测试并迭代
# - 不需要每次都手动批准
```

**2. 让 Claude 记住偏好**
```text
# 如果 Claude 没有正确使用某个工具
# 输入：
#remember always use --verbose flag when running this tool

# Claude 会自动更新 quilMD
```

**3. 批量命令进入上下文**
```bash
# 输入 ! 后跟命令
!docker build -t myapp .
# 命令和输出都会进入 Claude 的上下文窗口
# 适合：
# - 长时间运行的命令
# - 需要 Claude 分析命令输出
```

**4. 会话恢复**
```bash
# 会话结束后，使用 resume 恢复
/claude resume
```

---

## Claude Code SDK

### 基础使用

```bash
# 使用 -p 参数调用 CLI SDK
claude -p "你的提示词"

# 可选参数：
# --allowed-tools: 指定允许使用的工具
# --format: 输出格式（JSON/streaming JSON）
```

### 使用场景

| 场景 | 示例 |
|------|------|
| **CI 集成** | 在持续集成流程中使用 |
| **事件响应** | 处理生产环境问题 |
| **管道处理** | 集成到各种自动化流程 |
| **日志分析** | 读取 GCP bucket 中的日志，Claude 找出有趣的信息 |
| **CLI 集成** | 结合 jq 等工具进行数据处理 |

### 管道示例

```bash
# 读取日志文件并分析
cat large-log-file.log | claude -p "找出异常模式和错误"

# 结合 Git 命令
git status | claude -p "帮我生成提交信息"

# 结合 jq 处理数据
some-api-call | jq '.data' | claude -p "分析这个数据"
```

> Claude Code SDK 本质上是一个**智能化的 Unix 工具**，给一个提示，返回一个 JSON/文本结果。

---

## 并行工作技巧（高级用户）

### 普通用户 vs 高级用户

| 普通用户 | 高级用户 |
|---------|---------|
| 同时运行 1 个 Claude session | 运行多个 SSH 隧道连接的 Claude session |
| 单个仓库工作 | 多个仓库 checkout 同时运行 |
| 顺序完成任务 | 使用 Git worktrees 实现隔离并行 |

### 并行化方法

```bash
# 方法1：多个 terminal tabs
# 打开多个终端，每个运行不同的 Claude session

# 方法2：Git worktrees
git worktree add feature-branch
# 在不同的工作树中并行运行 Claude

# 方法3：SSH 隧道
# 连接到远程机器运行 Claude
```

### 建议

> 尽量**不要同时在一个仓库中运行多个 Claude**，这可能会导致冲突。使用 Git worktrees 实现真正的隔离并行。

---

## Q&A 精选

### Q: 为什么构建 CLI 工具而不是 IDE 插件？

**A: 两个原因**

1. **通用性**：Anthropic 员工使用各种 IDE（VS Code、Neovim、Xcode、JetBrains 等），终端是共同的分母
2. **未来趋势**：AI 模型发展迅速，年底可能人们不再使用传统 IDE，CLI 避免在 UI 层过度投资

### Q: Claude Code 支持多模态吗？

**A: 完全支持，从一开始就支持**

使用方法：
- **拖拽图片**到终端
- **提供文件路径**
- **复制粘贴图片**

典型使用场景：提供一个 UI mock 图片，告诉 Claude "实现这个界面"，然后用 Puppeteer 迭代验证。

### Q: Anthropic 内部如何使用 Claude Code？

- **80%** 的技术员工每天使用 Claude Code
- 包括工程师和研究员
- 研究人员使用 notebook 工具编辑和运行 Jupyter notebooks

### Q: Bash 命令安全性如何处理？

**A: 复杂的三层权限系统**

Claude Code 通过以下方式平衡安全性和效率：

1. **只读命令识别**：识别哪些命令是只读的
2. **静态分析**：分析哪些命令可以安全组合
3. **分层权限**：
   - 企业级：统一配置权限
   - 项目级：特定项目配置
   - 用户级：个人偏好设置
4. **黑名单**：可以阻止危险命令或 URL

---

## 总结：最佳实践路线图

```
┌─────────────────────────────────────────────────────────┐
│                    入门阶段                              │
│  1. 安装 Claude Code                                    │
│  2. 运行 /terminal setup                                │
│  3. 开始 Codebase Q&A（提问、提问、提问）                 │
│  4. 理解 Claude 的能力和边界                            │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│                    进阶阶段                              │
│  1. 学习代码编辑：先规划 → 确认 → 写代码                 │
│  2. 使用 #remember 教 Claude 你的偏好                   │
│  3. 集成团队工具（MCP、自定义 CLI）                      │
│  4. 编写项目 quilMD（共享给团队）                        │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│                    高级阶段                               │
│  1. 配置企业级策略和权限                                 │
│  2. 使用 SDK 集成到 CI/CD 流程                          │
│  3. 使用并行工作流（多个 session、worktrees）            │
│  4. 构建自定义 Agent 解决方案                            │
└─────────────────────────────────────────────────────────┘
```

**核心原则**：

- 从 Q&A 开始，不要急于使用复杂功能
- 给予足够的上下文（quilMD、MCP、工具）
- 让 Claude 先思考和规划
- 给予反馈工具让它迭代改进
- 投入时间配置，回报是巨大的