Claude Code 实践指南

1. Anthropic 产品体系

claude.ai 是 Claude 的消费级应用（Web/桌面/移动端），提供对话、写作、代码生成等能力。

console.anthropic.com 面向开发者/团队，通过 API Key 将 Claude 接入自有产品、脚本或服务。

注意：订阅计划与 Console/API 是独立产品，API 调用需单独付费。

Claude Code 支持两种登录方式，计费模式不同。

flowchart TD
    A{"使用场景"} -->|"个人日常开发"| B["订阅登录<br/>Claude Pro/Max"]
    A -->|"团队/自动化/重度使用"| C["API Key<br/>Console 计费"]

    B --> D["共享 claude.ai 用量"]
    C --> E["独立按 token 计费"]

    classDef decision fill:#F59E0B,stroke:#D97706,color:#000
    classDef option fill:#4F46E5,stroke:#3730A3,color:#fff
    classDef result fill:#10B981,stroke:#059669,color:#fff

    class A decision
    class B,C option
    class D,E result

订阅登录：消耗 Pro/Max 包含用量，与 claude.ai 共享配额。

API Key 登录：按 token 独立计费，适合大型代码库、并发实例或 CI/CD 场景。

注意：若设置了 ANTHROPIC_API_KEY 环境变量，Claude Code 会优先使用 API Key 计费，而非订阅额度。

2. Claude Code

Claude Code 是 Anthropic 推出的命令行 AI 编程助手，默认集成 Claude 模型，支持切换至兼容的第三方 API 提供商（如 SiliconFlow）。

2.1 安装与卸载

# 官方安装脚本（推荐）
curl -fsSL https://claude.ai/install.sh | bash

# npm 安装
npm install -g @anthropic-ai/claude-code

# 完全卸载
npm uninstall -g @anthropic-ai/claude-code
rm -rf ~/.claude-code ~/.claude
npm cache clean --force
rm -rf ~/.local/state/claude/locks/

2.2 API 提供商切换

Claude Code 支持两种 API 切换方案。

flowchart LR
    subgraph Direct["CC Switch 方案"]
        A1["修改 config.json"] --> A2["重启生效"]
    end

    subgraph Proxy["CCR 方案"]
        B1["代理层转发"] --> B2["无需修改配置"]
    end

    CC["Claude Code"] --> Direct
    CC --> Proxy

    Direct --> API1["第三方 API"]
    Proxy --> API1

    classDef tool fill:#4F46E5,stroke:#3730A3,color:#fff
    classDef method fill:#10B981,stroke:#059669,color:#fff
    classDef api fill:#F59E0B,stroke:#D97706,color:#000

    class CC tool
    class A1,A2,B1,B2 method
    class API1 api

2.2.1 CC Switch

通过修改配置文件切换 API 提供商。

项目地址：https://github.com/farion1231/cc-switch

配置项	说明
配置文件	~/.claude/config.json
API 端点	https://api.siliconflow.cn（无 /v1 后缀）
生效方式	修改后需重启终端或客户端
查看模型	/model 命令

2.2.2 CCR（Claude Code Router）

通过代理层转发请求，无需修改原始配置。

npm install -g @musistudio/claude-code-router
ccr ui    # 启动配置界面
ccr code  # 启动代理

特性	说明
无侵入设计	不修改 Claude Code 配置
API 格式	OpenAI 兼容格式
端点	https://api.siliconflow.cn/v1/chat/completions

2.3 核心功能

2.3.1 项目配置：CLAUDE.md

CLAUDE.md 是 Claude Code 的核心配置文件，作用是在每次会话开始时自动注入项目上下文和编码规范。

/init  # 创建 CLAUDE.md

分层加载机制

CLAUDE.md 支持多层级加载，优先级从高到低：

~/.claude/CLAUDE.md          ← 全局规则（所有项目通用）
  └── /project/CLAUDE.md     ← 项目根目录（团队共享）
        └── /src/CLAUDE.md   ← 子目录（按需加载）

引用外部文件

用 @ 语法引用其他文件，保持主文件精简：

# CLAUDE.md
@docs/coding-conventions.md
@docs/architecture-decisions.md

编写原则

• 总指令数控制在 150-200 条以内，超过后规则容易被忽略
• 关键规则加 IMPORTANT 标记，提升遵守率
• 只写 Claude 无法从代码中推断的内容（测试命令、特定约定、业务规则）
• 不要写通用语言规范或详细 API 文档（链接替代）
• 每隔 2-4 周审查一次，删除过时规则

2.3.2 权限控制

Claude Code 的权限通过 ~/.claude/settings.json 精细配置。

三种权限模式

模式	说明	适用场景
default	敏感操作需确认	新项目/陌生代码库
acceptEdits	自动接受文件修改，其他需确认	日常开发
bypassPermissions	跳过所有确认	受信任的本地环境

粒度化 Allow List

在 settings.json 中按命令类型配置白名单：

{
  "permissions": {
    "defaultMode": "bypassPermissions",
    "allow": [
      "Bash(git:*)",
      "Bash(npm:*)",
      "Bash(go:*)",
      "Bash(grep:*)",
      "WebSearch",
      "mcp__playwright__*"
    ]
  }
}

2.3.3 常用命令

命令	功能	场景
/init	创建 CLAUDE.md	项目初始化
/compact	压缩对话历史	上下文达 70-80% 时主动触发
/clear	清空对话历史	切换无关任务前
/cost	显示 token 统计	监控 API 成本
/review	代码审查	检查质量和安全问题
/model	查看/切换模型	确认 API 提供商
/tasks	管理后台任务	查看长时间运行任务
/permissions	查看权限配置	预批准常用命令
/btw	侧边提问	临时查询，不进入对话历史
/hooks	查看 Hooks 配置	确认自动化规则

2.3.4 CLI 技巧

输入技巧

# 多行输入：行尾加 \ 后按 Enter
claude> 请分析这个函数，\
        重点关注边界条件

# Ctrl+G：打开系统编辑器编写复杂提示（支持语法高亮）

# ! 前缀：直接执行命令，输出自动进入上下文
!git log --oneline -10

# @ 文件引用：在提示中直接引用文件内容
请优化 @src/main.go 中的错误处理

# 管道输入
cat error.log | claude "帮我分析这个错误"

会话管理

# 非交互模式（适合 CI/CD）
claude -p "运行测试并报告结果" --allowedTools "Bash(npm:*)"

# 恢复上次会话
claude --continue

# 恢复指定会话
claude --resume

# 后台任务
# Ctrl+B 或 /background 将命令移至后台

模型选择

# 计划阶段用 Opus，执行阶段用 Sonnet
/model opusplan  # Plan Mode 用 Opus，其他用 Sonnet

2.4 四大扩展机制

理解四种扩展机制的定位，是用好 Claude Code 的关键：

机制	本质	加载时机	适用场景
CLAUDE.md	每次会话注入的指令	每次会话启动	项目规范、编码约定、常驻规则
Skills	可复用的领域工作流	按需加载（LOD 机制）	特定技术栈指导、可复用流程
Hooks	确定性事件驱动脚本	工具调用前后自动触发	格式化、lint、安全检查（100% 执行）
MCP Servers	外部工具连接器	会话全程可用	集成 Playwright、Figma、数据库

2.4.1 Skills

Skills 是存储在 .md 文件中的结构化工作流，Claude 根据上下文按需加载，不像 CLAUDE.md 那样每次都消耗 token。

配置位置

~/.claude/skills/         ← 全局 Skills
.claude/skills/           ← 项目级 Skills

Skills 文件格式

---
name: code-review
description: 触发条件描述，用于 LOD 匹配
---

# 代码审查工作流
1. 先检查编译错误
2. 再检查逻辑问题
...

使用场景：可复用的调试流程、特定框架的最佳实践、团队标准化工作流。

2.4.2 Hooks

Hooks 在工具调用的生命周期事件上执行 Shell 脚本，100% 确定性执行，不依赖 Claude 的判断。

配置位置：settings.json 的 hooks 字段。

Hook 类型

类型	触发时机
PreToolUse	工具调用前（可阻断）
PostToolUse	工具调用后
Notification	Claude 需要通知用户时
Stop	会话结束时

示例：文件修改后自动格式化

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "gofmt -w $CLAUDE_TOOL_INPUT_PATH 2>/dev/null || true"
          }
        ]
      }
    ]
  }
}

让 Claude 帮你写 Hook：直接描述需求，例如 “ 写一个 Hook，在每次文件编辑后运行 eslint”。

2.4.3 Subagents

Subagents 是独立的 AI 工作进程，拥有自己的上下文窗口，只将结果汇报给主 Agent。

优势：将复杂子任务隔离，避免污染主会话上下文；可并行运行多个 Subagent。

配置位置：~/.claude/agents/ 或 .claude/agents/，每个 .md 文件是一个 Subagent 定义。

适用场景：代码审查、安全审计、测试生成、文档编写、并行调研。

2.4.4 MCP Servers

MCP（Model Context Protocol）是 Claude Code 连接外部工具的标准协议。

# 添加 MCP Server
claude mcp add playwright npx @playwright/mcp@latest

# 查看已配置的 MCP Servers
claude mcp list

常用 MCP：@playwright/mcp（浏览器自动化）、@modelcontextprotocol/server-github（GitHub 操作）、context7（文档检索）。

2.5 插件生态

Claude Code 插件市场提供 100+ 个官方和社区插件，通过 /plugin 命令管理。

/plugin          # 打开插件市场
/reload-plugins  # 重新加载已安装的插件

插件	功能	推荐指数
superpowers	计划模式、并行 Agent、TDD、系统调试、Git Worktree	⭐⭐⭐⭐⭐
feature-dev	7 阶段引导式功能开发工作流	⭐⭐⭐⭐
code-review	4 个并行审查 Agent，分角色审查 PR	⭐⭐⭐⭐
claude-md-management	CLAUDE.md 审计与改进	⭐⭐⭐⭐

2.6 工作流模式

2.6.1 Plan → Implement 模式

这是处理非平凡任务的标准流程：

Shift+Tab 进入 Plan Mode（只读）
  → Claude 探索代码库、提出实现方案
  → Ctrl+G 在编辑器中修改计划
  → Shift+Tab 退出 Plan Mode
  → Claude 按计划实现
  → 运行测试验证

Plan Mode 下 Claude 只读不写，适合复杂变更前的对齐确认。

2.6.2 多 Agent 协作与模型分层

不同复杂度的任务分配不同模型，兼顾质量与成本：

flowchart LR
    Task["复杂任务"] --> Haiku["Haiku\n筛选/校验/简单转换"]
    Task --> Sonnet["Sonnet\n执行/总结/合规检查"]
    Task --> Opus["Opus\n架构设计/深度 Bug 分析"]

    classDef cheap fill:#10B981,stroke:#059669,color:#fff
    classDef mid fill:#4F46E5,stroke:#3730A3,color:#fff
    classDef expensive fill:#F59E0B,stroke:#D97706,color:#000

    class Haiku cheap
    class Sonnet mid
    class Opus expensive

实际案例：代码审查命令使用 Haiku 判断 PR 是否需要审查，Sonnet 生成摘要和合规检查，Opus 负责 Bug 深度分析。

2.6.3 上下文管理

上下文窗口是最核心的约束。不同填充阶段行为差异显著：

填充比例	影响
< 70%	正常
70-85%	精度下降
> 85%	幻觉增加，响应变差

最佳实践：

• 主动 /compact：在 70-80% 时手动触发，优于 95% 的自动压缩
• 定向压缩：/compact 重点保留已修改的文件列表和测试命令
• 任务隔离：切换无关任务前用 /clear，不要在一个会话里混杂多个项目
• HANDOFF.md 模式：长任务中途记录进度和下一步，方便新会话接续

2.6.4 Writer/Reviewer 模式

用于需要客观视角的代码质量保证：

• 会话 A：实现功能
• 会话 B：用全新上下文审查（无对自己代码的偏见）

2.6.5 批量操作模式

# 对多个文件并行处理
cat filelist.txt | xargs -I{} claude -p "重构 {} 中的错误处理" \
  --allowedTools "Edit,Read" \
  --output-format json

--allowedTools 在无人值守的批量操作中至关重要，防止意外执行危险命令。

2.7 成本优化

主动压缩上下文

/compact 的时机比自动压缩早 15-25%，能显著降低后续请求的 token 消耗。压缩时可附加焦点提示：

/compact 保留：已修改文件列表、当前 Bug 复现步骤、未完成的 TODO

模型分层

Subagent 和 Hook 任务尽量用 Haiku，只在需要深度推理时用 Opus：

Haiku  ≈ $0.25/M tokens  → 筛选、校验、格式检查
Sonnet ≈ $3/M tokens     → 常规编码、重构
Opus   ≈ $15/M tokens    → 架构设计、复杂 Bug

Skills Vs CLAUDE.md

• CLAUDE.md：每次会话都加载，只放常驻规则
• Skills：按需加载，放领域知识和专项工作流（如 “Go 重构指南 “）

将低频使用的大块内容从 CLAUDE.md 移入 Skills，可节省每次会话的 token 消耗。

缩小调查范围

# 差：宽泛描述
"调查认证系统的问题"

# 好：精确路径
"调查 src/auth/token_refresh.go 中的 token 刷新逻辑"

精确的路径描述减少 Claude 读取无关文件的 token 消耗。

实时监控

/cost  # 显示当前会话 token 消耗和费用

2.8 常见反模式

反模式	症状	解决方案
厨房水槽会话	在一个会话里混杂多个无关任务	切换任务前 /clear
反复纠错	同一问题纠正超过 2 次	停止纠错，/clear 后重新描述问题
CLAUDE.md 过长	规则条数超过 200，Claude 开始忽略部分规则	精简到可执行指令，删除 Claude 能推断的内容
跳过验证	实现看起来合理就接受，没有运行测试	每次实现后提供测试/截图进行验证
无限探索	用 “ 调查整个系统 “ 类提示，导致读取大量无关文件	限定具体路径，或用 Subagent 隔离调研
过度依赖单一会话	不用 /clear，一个会话做所有事	独立任务用独立会话，保持上下文干净

3. 稳定使用

3.1 家庭带宽 IP

参考：https://www.liuvv.com/p/546fae42.html

3.2 Fuclaude

资源	链接
介绍	https://linux.do/t/topic/131611
教程	https://linux.do/t/topic/131669
文档	https://wiki.linux.do/AI/Fuclaude/SessionToken
登录	https://demo.fuclaude.com/new

4. 参考资料

• https://claudecode.tangshuang.net/
• https://claude.com/blog/claude-code-plugins
• https://claude.com/blog/using-claude-md-files
• https://github.com/hesreallyhim/awesome-claude-code
• https://x.com/oran_ge/status/2005419365450252425
• https://www.builder.io/blog/claude-code-tips-best-practices
• https://github.com/farion1231/cc-switch
• https://github.com/musistudio/claude-code-router