13 KiB
13 KiB
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 后，官方推荐以下设置：
# 1. 设置终端（获得 Shift+Enter 换行功能）
/terminal setup
# 2. 切换主题
/slash themes # 可选择 light/dark/zen 主题
# 3. 安装 GitHub App（可选）
# 在任意 GitHub issue 或 PR 中 @Claude）
/install github-app
工具权限自定义
# 自定义允许使用的工具集，避免每次都弹出确认
# 这样设置后不需要每次都手动批准工具调用
语音输入（Mac 用户）
- 进入系统设置 → Accessibility → Dictation
- 启用听写功能
- 双击听写键即可语音输入提示词
这对于编写详细的提示词非常有帮助，可以像与另一个工程师对话一样自然地描述需求。
第一步：Codebase Q&A（强烈推荐入门方式）
为什么从 Q&A 开始
这是 Anthropic 新员工入职培训的第一课：
- 降低学习门槛：不需要了解任何复杂功能，只需要提问
- 了解 AI 边界：帮助理解 Claude Code 能做什么、不能做什么
- 无需设置：无需索引、无需配置，直接开始使用
效率提升数据
| 场景 | 传统方式 | 使用 Claude Code Q&A |
|---|---|---|
| 技术入职培训 | 2-3 周 | 2-3 天 |
可以问的问题类型
# 代码使用问题
"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 拥有一个小型工具集，它会自动串联使用这些工具：
- Edit files - 编辑文件
- Run bash commands - 运行命令
- Search files - 搜索文件
推荐的代码编辑工作流
1. 让 Claude 先思考和规划
2. 让它向你展示计划
3. 征得你同意后再写代码
推荐提示词模板：
"Before you write code, make a plan. Answer with the plan and ask for my approval before writing code."
这种方式可以避免"一次性实现3000行功能但完全不是想要的结果"的情况。
常见任务提示词
# 自动创建分支、提交代码并推送到远程
"Think for this one. This commit push here."
# Claude Code 会：
# - 自动创建新分支
# - 分析 git history 和 git log 确定提交格式
# - 创建符合项目规范的 commit
# - 推送到远程
# - 创建 Pull Request
工具集成
Batch 命令工具
定义自定义 CLI：
# 告诉 Claude Code 关于你的 CLI 工具
# Claude 会使用 --help 来了解工具用法
# 如果频繁使用，可以添加到 quilMD 中（持久化保存）
MCP（Model Context Protocol）工具
Claude Code 支持 MCP 工具，可以集成团队已有的各种工具：
- 告诉 Claude 关于工具的描述
- 添加 MCP 服务器配置
- 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 太长会消耗大量上下文窗口，通常不太有用。
企业级配置
# 企业配置文件可以包含：
- 全局 s 命令
- 批量权限配置
- URL 黑名单（禁止访问的 URL）
- MCP 服务器配置
- 权限策略
权限管理示例：
# 允许所有员工使用某个测试命令（自动批准）
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. 自动接受编辑模式
# 适合场景：
# - 知道 Claude 在做正确的事
# - 运行单元测试并迭代
# - 不需要每次都手动批准
2. 让 Claude 记住偏好
# 如果 Claude 没有正确使用某个工具
# 输入：
#remember always use --verbose flag when running this tool
# Claude 会自动更新 quilMD
3. 批量命令进入上下文
# 输入 ! 后跟命令
!docker build -t myapp .
# 命令和输出都会进入 Claude 的上下文窗口
# 适合：
# - 长时间运行的命令
# - 需要 Claude 分析命令输出
4. 会话恢复
# 会话结束后，使用 resume 恢复
/claude resume
Claude Code SDK
基础使用
# 使用 -p 参数调用 CLI SDK
claude -p "你的提示词"
# 可选参数：
# --allowed-tools: 指定允许使用的工具
# --format: 输出格式（JSON/streaming JSON）
使用场景
| 场景 | 示例 |
|---|---|
| CI 集成 | 在持续集成流程中使用 |
| 事件响应 | 处理生产环境问题 |
| 管道处理 | 集成到各种自动化流程 |
| 日志分析 | 读取 GCP bucket 中的日志，Claude 找出有趣的信息 |
| CLI 集成 | 结合 jq 等工具进行数据处理 |
管道示例
# 读取日志文件并分析
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 实现隔离并行 |
并行化方法
# 方法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: 两个原因
- 通用性：Anthropic 员工使用各种 IDE（VS Code、Neovim、Xcode、JetBrains 等），终端是共同的分母
- 未来趋势：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 通过以下方式平衡安全性和效率：
- 只读命令识别：识别哪些命令是只读的
- 静态分析：分析哪些命令可以安全组合
- 分层权限：
- 企业级：统一配置权限
- 项目级：特定项目配置
- 用户级：个人偏好设置
- 黑名单：可以阻止危险命令或 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 先思考和规划
- 给予反馈工具让它迭代改进
- 投入时间配置，回报是巨大的