Claude Code 实战指南

Claude Code 是 Anthropic 推出的终端 AI 编程 Agent——直接在你的命令行里工作，能读整个仓库、改代码、跑命令、写测试、自主迭代。和 Codex 同属"AI 编程 Agent"热潮，是 2025 年以来技术圈最火的编程工具话题之一。本文从 Claude Code 特性讲起，覆盖安装登录、交互/非交互用法、权限与工具、claude.md 项目记忆、MCP 扩展、实战任务、与其它 Agent 对比、常见坑，全程带可运行命令。

---

一、Claude Code 是什么

1.1 核心定位

- 终端里的 AI 编程 Agent（不是 IDE 插件）
- 原生跑在 terminal，融入你的 git 工作流
- 能：读仓库、写代码、跑命令、改测试、自主修复
- 上下文感知：记住项目结构、你之前的偏好

场景：
- "这个测试为什么挂" → 它自己查、自己修
- "给接口加个功能" → 改代码 + 测试 + 跑通
- 代码审查、重构、迁移

1.2 与对话式 AI 的区别

聊天（Claude.ai）：只能给建议，不能执行
Claude Code：真的动你的代码库、跑你的命令

---

二、安装与登录

2.1 安装

# 方式一：npm（推荐）
npm install -g @anthropic-ai/claude-code

# 方式二：官方脚本
curl -fsSL https://claude.ai/install.sh | bash

# 验证
claude --version

# Windows：用 WSL 或原生（支持 PowerShell）

2.2 登录

# 交互登录（浏览器授权 Claude 账号）
claude

# 用 API Key（生产/脚本）
export ANTHROPIC_API_KEY=sk-ant-xxxx

# 或订阅（Pro/Max 会员直接用）

注意：
- 免费额度有限，重活建议订阅
- 登录态存在本机配置目录

---

三、基本用法

3.1 启动交互

# 在项目根目录启动
cd /path/to/project
claude

# 然后直接输入任务：
# "检查当前 git 状态，看看有没有未提交的改动，帮我写个 commit message"
# "运行测试，修复失败的"

3.2 交互内常用命令

/help         帮助
/status       当前会话状态/用了多少上下文
/compact      压缩上下文（长会话）
/clear        清空会话
/model        切换模型
/init         生成 claude.md（项目记忆）
/install-mcp  添加 MCP 工具
/prompt       用提示词模板
/quit         退出

3.3 非交互（脚本/CI）

# 一次性任务
claude -p "给 UserService 增加删除用户方法并写测试"

# 带权限：允许读写和跑命令
claude -p "运行 mvn test，修复失败" --permission-mode acceptEdits

# 输出 markdown 结果
claude -p "审查 OrderController 的安全问题" --output-format json

---

四、权限与安全模型

4.1 权限模式

--permission-mode acceptEdits      允许改文件
--permission-mode acceptEdits deny  只改文件不跑命令
--permission-mode bypassPermissions 全放行（慎用）
--permission-mode plan             只规划不动手

默认：交互式逐个询问（命令/写文件都要 y/n）

4.2 权限规则

可以用 .claude/settings.json 配置：
- 放行某些命令（如 npm test）
- 永远拒绝某些命令（rm -rf）
- 允许写特定目录

// .claude/settings.json
{
  "permissions": {
    "allow": [
      "npm test",
      "npm run build",
      "git status",
      "git diff"
    ],
    "deny": [
      "rm -rf *",
      "git push --force"
    ]
  }
}

---

五、claude.md 项目记忆（核心）

5.1 是什么

claude.md = 项目级的"给 AI 看的 README"
告诉 Claude Code：项目怎么跑、什么规范、别踩什么坑

它会在每次会话自动加载 → 让 AI 更懂你的项目

5.2 内容建议

# claude.md

## 项目简介
订单微服务，Spring Boot 3 + MyBatis + MySQL

## 常用命令
- 构建：mvn clean package -DskipTests
- 测试：mvn test
- 启动：mvn spring-boot:run

## 架构约定
- 分层：controller/service/mapper，禁止跨层调用
- 统一返回 Result<T>，业务异常用 BizException
- 日志用 SLF4J + traceId

## 注意事项
- 不要改数据库表结构
- 金额用 BigDecimal，不要用 double
- 新接口必须加单元测试

## 目录说明
- src/main/java：业务代码
- src/main/resources：配置
- docs：设计文档

5.3 生成

# 让 Claude Code 自己生成
claude
/init
# 它会读项目，生成 claude.md

效果：
- 不用每次重复交代项目背景
- 代码风格/约束更一致
- 出错率显著下降

---

六、MCP 扩展

6.1 什么是 MCP

MCP = Model Context Protocol
让 Claude Code 能调用外部工具/数据源：
- 数据库查询
- 文件系统
- 浏览器
- 内部 API

例：加一个"查询订单"的 MCP，Claude 就能直接查库帮你分析

6.2 添加 MCP

claude
/install-mcp

# 或配置文件 .mcp.json
{
  "mcpServers": {
    "my-db": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": { "POSTGRES_CONNECTION": "postgres://..." }
    }
  }
}

场景：
- 接入 PostgreSQL → AI 直接查表做数据分析
- 接入浏览器 → AI 打开页面截图验证
- 接入内部 API → AI 调接口排查

---

七、实战任务

7.1 修测试

claude -p "运行 mvn test，修复所有失败用例，
保持原有逻辑不变，确保全绿" --permission-mode acceptEdits

7.2 加特性

claude -p "给 OrderController 增加取消订单接口：
- 只允许本人取消
- 已支付/已发货不可取消，抛 BizException
- 加 3 个单元测试（成功、非本人、已支付）
跑 mvn test 确认通过"

7.3 迁移/重构

claude -p "把 UserService 拆成 UserQueryService（查询）和
UserCommandService（写操作），保持行为不变，
重构后跑全部测试"

7.4 代码审查

claude -p "审查 src/main 代码：
找出空指针风险、SQL 注入、越权、性能问题，
按严重程度输出报告并给出修复建议" \
  --permission-mode plan

---

八、与其它 Agent 对比

工具	定位	优势	适用
Claude Code	终端 Agent	上下文强、MCP 生态、代码质量好	本地深度开发
OpenAI Codex	云端 Agent	沙箱隔离、CI 集成好	自动化/CI 修复
Cursor	IDE Agent	界面友好、补全+Agent 混合	日常手写为主
Copilot	IDE 补全	轻量、实时补全	边写边补

选型建议：
- 深度重构/复杂 bug → Claude Code
- CI 自动化修复 → Codex 无头
- 日常编码辅助 → Cursor/Copilot

---

九、常见坑速查

现象	原因	解决
改错文件	没先读项目	claude.md + 明确范围
命令卡在确认	权限太严	acceptEdits / allowlist
忘了项目约束	没记忆文件	/init 生成 claude.md
上下文爆了	会话太长	/compact
乱删文件	权限太宽	deny 危险命令
跑偏主题	任务描述模糊	目标+范围+验收
MCP 不生效	配置没加载	检查 .mcp.json
测试没验证	没让它跑	描述里写"跑测试确认"

---

九、CLI 命令速查与效率技巧

9.1 常用命令速查

claude                      # 启动交互
claude -p "任务"            # 一次性任务
claude -p "任务" --output-format json   # 结构化输出
claude -p "任务" --permission-mode acceptEdits   # 允许改文件
claude --resume             # 恢复上次会话
claude --continue           # 继续上次会话
claude --model sonnet       # 切换模型
claude --print              # 只打印结果不交互
claude /init                # 生成 claude.md

9.2 会话管理技巧

- 长会话用 /compact 压缩上下文（防遗忘/超预算）
- 每完成一个任务 /clear，避免串味
- 关联 git：让它在分支上工作，便于回滚
- 复杂任务分步问：先"读代码总结"，再"动手改"

9.3 与 IDE 联动的姿势

1. VS Code + Claude Code 终端并排
2. 写代码在 IDE，让 Claude Code 跑测试/查问题
3. 让 Claude Code 改完，IDE 里 git diff 审查
4. 不要同时开多个 Agent 改同一文件（冲突）

常见场景：
- Claude Code 生成 → 你 review → 手写补关键逻辑
- 让 Claude 先写测试 → 你实现 → Claude 再跑

---

十、自动化脚本与效率工具

10.1 批量跑任务脚本

#!/bin/bash
# 让 Claude Code 处理多个独立任务（分分支跑）
tasks=(
  "给 UserService 补单元测试"
  "审查 OrderController 安全问题"
  "重构 ConfigService 拆分配置"
)
for t in "${tasks[@]}"; do
  git checkout -b "ai-task-$RANDOM"
  claude -p "$t" --permission-mode acceptEdits \
    --output-format json >> claude-output.log
  git add . && git commit -m "AI: $t"
  git checkout main
done

10.2 输出解析（JSON）

# 结构化输出便于脚本处理
claude -p "统计 src 下 TODO 数量，返回 JSON" --output-format json
# {"todo_count": 12, "files": [...]}

10.3 效率建议

- 把重复任务存成提示词文件（/prompt）
- 长任务先让它出计划（plan 模式）再执行
- 团队共享 claude.md 模板（统一约束）
- 关键路径自己写，AI 做外围（测试/文档/样板）
- 每周复盘：哪些任务 AI 提效、哪些反而慢

---

本章小结

Claude Code 的实战主线：安装登录 → 交互（/help /init /compact）→ 权限模型（acceptEdits/bypass）→ claude.md 项目记忆 → MCP 扩展 → 实战四类任务 → 对比选型。核心心法：先 /init 让 AI 懂项目（claude.md 是灵魂）→ 权限默认收着（deny 危险命令、allow 常规命令）→ 任务描述写清验收标准 → 完成后 git diff review。Claude Code 强在"懂你的项目 + 能跑命令自主迭代"，配合 MCP 能打通数据库/浏览器，是从"改代码"升级到"真正参与开发"的 Agent 工具。

第三篇讲 AI 编程助手选型与工作流。

（全文完）