Claude Code 实战

最近正式开始使用Claude Code/Codex/Gemini CLI+CC-Switch+API的Agent Coding的方式构建项目。之前是直接用Copilot和Trae这种跟IDE结合更紧密,也提供了编辑文件,浏览目录以及测试命令的功能，但Claude Code明显提供了更好的体验以及更先进的AI编程工程范式。
这里做一些实战总结,主要是Claude Code使用上。

Claude Code 是一个代理编码工具，可以读取你的代码库、编辑文件、运行命令，并与你的开发工具集成。可在终端、IDE、桌面应用和浏览器中使用。Claude Code 是一个由 AI 驱动的编码助手，可帮助你构建功能、修复错误和自动化开发任务。它理解你的整个代码库，可以跨多个文件和工具工作以完成任务。

考虑到国内充值付费问题,使用方式可参考国内丝滑落地 Claude Code/Codex Agent 编程的硬核指南.使用第三方中转站

如何工作

通过Agent循环工作,而这个循环中包含模型推理和工具调用。ClaudeCode提供工具、上下文管理以及执行环境。

模型

执行引擎。在会话期间使用 /model 切换或使用 claude --model <name> 启动。

工具

没有工具，Claude 只能用文本回应。有了工具，Claude 可以采取行动：读取您的代码、编辑文件、运行命令、搜索网络并与外部服务交互.

内置工具通常分为五个类别，每个类别代表不同类型的代理能力。

工具调用时机本质还是利用模型根据提示和沿途学到的内容选择使用哪些。

可以使用 skills 扩展 Claude 知道的内容、使用 MCP 连接到外部服务、使用 hooks 自动化工作流，以及将任务卸载给 subagents。

平台集成

本身可以直接在终端运行，也可以跟VS Code,JetBrains IDEs 结合

事实上，可以通过终端、桌面应用、IDE 扩展、claude.ai/code、远程控制、Slack 和 CI/CD 管道访问 Claude Code。

claude配置主要是两个地方,一个是用户目录,另一个是项目目录

扩展Claude

使用 CLAUDE.md 文件为 Claude 提供持久指令，并让 Claude 通过自动记忆功能自动积累学习内容。

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

Claude Code 读取 CLAUDE.md，而不是 AGENTS.md。如果你的存储库已经为其他编码代理使用 AGENTS.md，创建一个导入它的 CLAUDE.md

  1. 加载时机。在每个会话开始时加载到上下文窗口中。CLAUDE.md 文件无论长度如何都完整加载。
  2. 语法规则。通过@引用，每个 CLAUDE.md 文件目标在 200 行以下；编写具体到足以验证的指令；模块化加载。

自动记忆让 Claude 跨会话积累知识，无需你编写任何内容。Claude 在工作时为自己保存笔记：构建命令、调试见解、架构笔记、代码样式偏好和工作流习惯。Claude 不会每个会话都保存内容。它根据信息在未来对话中是否有用来决定什么值得记住。

本质是存储在~/.claude/projects/<project>/memory/的各种文件,比如

1
2
3
4
5
~/.claude/projects/<project>/memory/
├── MEMORY.md          
├── debugging.md       
├── api-conventions.md 
└── ...

MEMORY.md 的前 200 行或前 25KB（以先到者为准）在每次对话开始时加载。超过该阈值的内容在会话开始时不加载。Claude 在你的会话中读取和写入记忆文件。当你在 Claude Code 界面中看到”Writing memory”或”Recalled memory”时，Claude 正在主动更新或读取 ~/.claude/projects/<project>/memory/。

.claude目录

Claude Code 读取 CLAUDE.md、settings.json、hooks、skills、commands、subagents、rules 和自动内存的位置。

.claude目录包括个人的~/.claude以及项目的.claude.~/.claude 中的文件是个人配置，适用于所有项目。

上下文窗口与prompt caching

运行 /context 以获取按类别的实时分解和优化建议。运行 /memory 以检查在启动时加载了哪些 CLAUDE.md 和自动内存文件。探索上下文窗口查看一个上下文的组成

既然每次跟模型的对话都会重发一些内容, 有哪些方式可以优化以节约成本呢。目前常用的技术还是prompt caching和/compact裁剪

每次在 Claude Code 中发送消息时，它都会发出新的 API 请求。模型在请求之间不记得任何东西，所以 Claude Code 重新发送完整的上下文：系统提示、您的项目上下文、每条先前的消息和工具结果，以及您的新消息。新内容附加在末尾，这意味着每个请求的大部分与前一个请求相同。Prompt caching 是 API 避免重新处理未更改部分的方式。

为了充分利用前缀匹配，Claude Code 组织每个请求，使回合之间很少更改的内容首先出现：

权限模式

每种模式在便利性和监督之间做出不同的权衡。

在会话期间：按 Shift+Tab 循环切换 default → acceptEdits → plan。当前模式显示在状态栏中。并非每种模式都在默认循环中：

  • auto：当您的账户满足 auto mode 要求时出现；循环到 auto 会显示一个选择加入提示，直到您接受它，或选择不，不再询问以从循环中移除 auto
  • bypassPermissions：在您使用 --permission-mode bypassPermissions、--dangerously-skip-permissions 或 --allow-dangerously-skip-permissions 启动后出现；--allow- 变体将模式添加到循环中而不激活它
  • dontAsk：永远不会出现在循环中；使用 --permission-mode dontAsk 设置它

会话管理

会话是与项目目录关联的已保存对话。Claude Code 在您工作时将其本地存储，因此您可以从中断处恢复、分支以尝试不同的方法，或在任务之间切换。每次在一个项目目录启动claude都视为一次独立的会话,在~/.claude/projects/下有不同项目下的若干个会话。

对于会话,可以进行恢复,命名,分支会话,导出以及管理会话内的上下文.

恢复会话通过/resume进行选择,命名通过/rename,管理上下文通过\clear清除以及/compact压缩

实操

扩展能力

  1. 创建commands,在项目中.claude/commands下创建*.md文件

Claude Code 里的 slash commands 大致分四类：

  • Built-in commands：Claude Code 自带的命令，如 /help、/clear、/model
  • Skills 形式的命令：通过 SKILL.md 定义，仍然可以用 /name 调用
  • Plugin commands：安装 plugin 后带来的命令
  • MCP prompts：由 MCP server 暴露出来的命令

*.md文件中包含内容,frontmatter 包含描述,允许的工具等,此外还有工作流程。

  1. 更改memory

包括CLAUDE.md和自动内存.

CLAUDE.md包含内容如下。可以通过/init常见,/memory查看或编辑

  • 哪些目录最重要
  • 哪些规则最容易被忽略
  • 提交前必须做什么
  • 哪些工具是本项目默认用法
  • 哪些文件不要乱动
  • 测试和验证的最低标准

3.skiils

skill可以理解成：

  • 一个带 frontmatter 的 SKILL.md
  • 可附带脚本、模板、参考资料
  • 会被 Claude 自动发现和按需加载
  • 更适合长期复用的工作流能力

skill基本结构

1
2
3
4
5
skill-name/
├── SKILL.md
├── templates/
├── scripts/
└── references/

SKILL.md负责

  • 定义 skill 名称
  • 说明 skill 在什么情况下应该触发

  • 告诉 Claude 该怎么做

  • templates/：输出模板

  • scripts/：辅助脚本
  • references/：参考规则或背景知识

4.subagents

subagents 是 Claude Code 里做复杂任务拆分的关键能力。你可以把它理解成“主 Claude 把某个子任务交给一个更专业、上下文更独立的助手去做”。

subagent 具备这些特点：

  • 有自己的角色定位
  • 有自己的上下文窗口
  • 可以限制可用工具
  • 可以使用单独的 system prompt
  • 适合做任务拆分和专业分工

subagent 文件通常是：

  1. YAML frontmatter
  2. 后面跟 Markdown 形式的 system prompt
1
2
3
4
5
6
---
name: code-reviewer
description: Review recent changes for quality issues
tools: Read, Grep, Glob, Bash
model: inherit
---
  • subagents：主 Claude 委派一个边界清晰的子任务，等它把结果带回来
  • Agent Teams：多个 Claude Code 实例协作，彼此有独立上下文窗口，还能直接通信

本质上是分配一个新角色,它有独立的上下文,职责不同,执行完后能返回结果。

5.mcp使用

如果没有 MCP，Claude 只能基于你提供的上下文回答。
有了 MCP，它可以：

  • 获取实时数据
  • 调用外部工具
  • 访问项目外的信息源
  • 把结果带回当前工作流

MCP 常见应用场景

  • GitHub PR / issue 查询
  • 数据库读写
  • 文件系统访问
  • Slack / Docs / 其他 SaaS 工具集成

在.mcp.json中配置

1
2
3
4
5
6
7
8
9
10
11
{
  "mcpServers": {
    "database": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-database"],
      "env": {
        "DATABASE_URL": "postgresql://user:pass@localhost/mydb"
      }
    }
  }
}

6.hooks

hooks 是 Claude Code 的“事件触发自动化”机制。它允许你在某些时机自动做点事情，例如：

  • 调工具前先检查风险
  • 写完文件后自动格式化
  • 提交前跑测试
  • 结束前记录日志或上下文

可以把 hook 理解成一条规则：

  1. 某个事件发生
  2. 匹配某个工具或场景
  3. 自动执行一个动作

这些动作可以是：

  • shell command
  • HTTP webhook
  • prompt 型判断
  • agent 型评估

hooks 最大的价值，是把“你本来每次都要手动做的检查”变成自动流程。

配置位置

  • ~/.claude/settings.json：用户级，对所有项目生效
  • .claude/settings.json：项目级，适合团队共享
  • .claude/settings.local.json：本地项目配置，不建议提交
  • plugin 内的 hooks/hooks.json

一般结构

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
  "hooks": {
    "EventName": [
      {
        "matcher": "ToolPattern",
        "hooks": [
          {
            "type": "command",
            "command": "your-command-here",
            "timeout": 60
          }
        ]
      }
    ]
  }
}

hooks有匹配工具,类型,执行的命令等

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
"hooks": {
   "SessionStart": [
     {
       "matcher": "startup",
       "hooks": [
         {
           "type": "command",
           "command": "python .claude/hooks/session-start.py",
           "timeout": 30
         }
       ]
     },
     {
       "matcher": "clear",
       "hooks": [
         {
           "type": "command",
           "command": "python .claude/hooks/session-start.py",
           "timeout": 30
         }
       ]
     },
     {
       "matcher": "compact",
       "hooks": [
         {
           "type": "command",
           "command": "python .claude/hooks/session-start.py",
           "timeout": 30
         }
       ]
     }
   ],
   "PreToolUse": [
     {
       "matcher": "Task",
       "hooks": [
         {
           "type": "command",
           "command": "python .claude/hooks/inject-subagent-context.py",
           "timeout": 30
         }
       ]
     },
     {
       "matcher": "Agent",
       "hooks": [
         {
           "type": "command",
           "command": "python .claude/hooks/inject-subagent-context.py",
           "timeout": 30
         }
       ]
     }
   ],
   "UserPromptSubmit": [
     {
       "hooks": [
         {
           "type": "command",
           "command": "python .claude/hooks/inject-workflow-state.py",
           "timeout": 15
         }
       ]
     }
   ]
 },

7.plugins

anthropics/claude-plugins-official

plugin 通常会组合这些内容：

  • commands
  • skills
  • subagents
  • hooks
  • .mcp.json
  • 辅助脚本与模板

所以它特别适合：

  • 团队统一工作流
  • 跨项目复用
  • 把一套最佳实践做成可分发单元

plugin配置如下

1
2
3
4
5
6
7
8
9
10
11
my-plugin/
├── .claude-plugin/
│   └── plugin.json
├── commands/
├── agents/
├── skills/
├── hooks/
├── .mcp.json
├── scripts/
├── templates/
└── docs/

8.checkpoints

可以把 checkpoint 理解成当前会话状态的快照，通常包括：

  • 对话消息
  • 文件改动
  • 工具使用历史
  • 会话上下文

当你需要回退时，就使用 rewind 返回到某个 checkpoint。Claude Code 会自动创建 checkpoints，所以你不需要手动先“存档”才能用。

常见有这些：

  1. Restore code and conversation：代码和对话都回退
  2. Restore conversation：只回退对话
  3. Restore code：只回退代码
  4. Summarize from here：从这一点开始压缩总结，释放上下文窗口
  5. Never mind：取消
1
2
3
4
先让 Claude 改
→ 如果结果好，继续
→ 如果不满意，/rewind
→ 换一种实现路线

这在这些任务里尤其好用：

  • UI 重构
  • API 重构
  • auth / permission 变更
  • 大批量文档整理

9.高级功能

权限模式

通过--dangerously-skip-permissions切换到bypassPermissions,可以通过shift+tab切换,也可以通过claude --permission-mode plan.也可以通过\config配置。

claude -p输出模式适合shell脚本以及CI/CD等人物。此外还有后台任务\background让耗时任务后台跑，不阻塞当前会话.

10.CLI功能

CLI 常见会和这些配置一起使用：

  • --model
  • --fallback-model
  • --effort
  • --settings
  • --append-system-prompt

示例：

1
2
3
claude --model opus "design a caching strategy"
claude -p --fallback-model sonnet "summarize this diff"
claude --append-system-prompt "Always explain tradeoffs" "review this plan"

工具与权限相关 flags

  • --permission-mode
  • --dangerously-skip-permissions
  • --allowedTools
  • --disallowedTools
  • --tools

学习资料

  1. Claude Code: A Highly Agentic Coding Assistant - DeepLearning.AI
  2. Spec-Driven Development with Coding Agents - DeepLearning.AI
  3. lhfer/claude-howto-zh-cn: Claude Code 中文全面上手指南。基于 luongnv89/claude-howto 本土化重写，面向中国小白用户，保留命令与配置兼容性，并附学习路径与本地化校验护栏。
  4. Claude Code 权限配置 | 菜鸟教程
  5. Claude Code Docs
  6. Trellis 技术分享资料：大模型科普与 AI Coding 框架 | Koi’s Blog
  7. 让 Claude Code 在你睡觉时持续运行：完整实战指南 · 唐巧的博客
  8. claude->/powerup