Claude Code：把整个仓库交给终端里的 Agent

01

它是什么：住在终端里的「会用你电脑的同事」

Claude Code 是 Anthropic 官方出的 agentic coding 工具，2025 年 2 月以研究预览发布、5 月正式可用。装完之后你的终端里多了一个 claude 命令：它启动后读的是你当前目录这个真实仓库——自己决定先看哪些文件、跑哪些测试、改哪几行，每一步动作都会显示出来等你确认。补全工具猜你想打的下一行代码；Claude Code 接的是「把这个问题修了」「把这个模块的测试补齐」这种任务级指令。

它解决的痛点很具体：改一个 bug 要在编辑器、终端、浏览器之间来回切。有了它，读代码、定位、改文件、跑测试、看日志这一整条链路都发生在一个会话里，而且它的每一步写操作默认要你点头。

适用场景：接手陌生仓库想快速摸清结构、修跨多文件的 bug、批量重构、写测试、跑脚本整理数据。不适合拿它当聊天机器人闲聊——它的一切设计都围绕「对你的文件系统动手」。

它和编辑器插件、网页版不冲突，而是分工：IDE 插件管行内补全和小重构，Claude Code 管跨文件的整段任务，网页版适合异步派活。三者的账号与订阅是同一套，先装 CLI 把核心心智练起来，其他入口都是换壳。

• 适合：接手陌生仓库摸结构；修跨多文件的 bug；批量重构与迁移；给老代码补测试；把重复的整理工作脚本化。
• 不适合：对单文件的行级补全（这是 IDE 插件的活）；需要严格最小权限的陌生环境（先审它的计划再放行）；不想让工具碰文件系统的纯问答。

开发商

Anthropic（官方工具）

发布节奏

2025-02 研究预览 · 2025-05 正式发布

安装渠道

npm / 官方脚本 / Homebrew

运行依赖

npm 方式需 Node.js ≥ 18；脚本装独立二进制

平台

macOS · Linux · Windows（原生/WSL）

计费

Pro/Max 订阅，或 Console API 按量

免费层

无，订阅与 API 均付费

源码

github.com/anthropics/claude-code 公开

02

安装：三条路，选一条走完

推荐 npm 方式——只要机器上有 Node 18+，一条命令搞定，升级也走同一条路。不想装 Node 就用官方脚本（下载独立二进制）；macOS 用户也可以走 Homebrew。

# 需要 Node.js ≥ 18
node --version
npm install -g @anthropic-ai/claude-code

# 装完先确认能跑
claude --version

# 以后升级也走 npm
npm update -g @anthropic-ai/claude-code

# macOS / Linux：下载原生二进制 + 校验，不依赖 Node
curl -fsSL https://claude.ai/install.sh | bash

# 装完重开一个终端再验证
claude --version

# macOS（Homebrew cask）
brew install --cask claude-code

# 升级 / 卸载
brew upgrade --cask claude-code
brew uninstall --cask claude-code

升级与卸载

Claude Code 自带自动更新，也可以手动升级；卸载方式跟着安装渠道走：

# npm 安装的：升级 / 卸载
npm update -g @anthropic-ai/claude-code
npm uninstall -g @anthropic-ai/claude-code

# brew 安装的：
brew upgrade --cask claude-code
brew uninstall --cask claude-code

# 升级后跑一次体检确认无恙
claude doctor

03

登录与第一次使用：OAuth 一条路走通

第一次敲 claude 会进入交互界面并引导登录：走 Anthropic 账号 OAuth，浏览器里授权一次就完事。有 Pro/Max 订阅直接用订阅额度；没有订阅就绑定 Anthropic Console 的 API key 按量计费。两种方式都从同一条登录流程进，选其一即可。

# 启动后按提示走 OAuth（订阅或 API 计费都在这里选）
claude

# 已经进会话了，也可以用斜杠命令
> /login
> /logout    # 换账号或共用机器时清掉凭证

启动即用的四种姿势

# 交互会话，附带一句开场任务
claude "梳理这个项目的入口和目录结构"

# 单次模式：打印结果就退出，适合脚本
claude -p "README 里描述的启动步骤是哪几条"

# 继续上次会话（同目录）
claude -c

# 从历史会话里挑一个恢复
claude -r

• 01

  进仓库再启动

  cd ~/your-project 之后敲 claude。上下文边界就是当前目录，在错误目录启动等于让它盲干。

• 02

  先跑一次 /init

  它会分析代码库并生成 CLAUDE.md 项目记忆文件——以后每次会话自动带上这些约定，省去反复解释。

• 03

  从只读任务开始

  「解释这个模块」「列出所有 API 路由」这类只读请求默认放行；等它展示过几轮输出，再让它动文件。

• 04

  用 /cost 看消耗

  订阅用户看本次会话的用量，API 用户关心钱就直接盯着这条命令，心里有数。

会话与成本：三个习惯

# 一事一会话：干完一件就 /clear，别在一个会话里混五件事
> /clear

# 上下文涨了先压缩，并指定保留重点
> /compact 保留改了哪些文件和最终结论

# 订阅用户看 /usage，API 用户看 /cost，心里有数
> /cost

会话记录按目录保存，claude -c 和 claude -r 都只对「当前目录」生效——这也是进对目录再启动的另一个理由。重要结论别只留在会话里，让它写进 CLAUDE.md 或导出成 Markdown。另外双击 Esc 可以打开 rewind 菜单，把代码和对话一起回退到之前的检查点，改砸了有后悔药。

跨仓库任务：--add-dir

偶尔会遇到「改 A 仓库要同时看 B 仓库」的场景。启动时额外授权一个目录，会话里就能同时引用两边的文件：

cd ~/your-app
claude --add-dir ~/shared-lib

> 把 shared-lib 里的日期工具迁移成本仓库可直接调用的模块，改完两边测试都跑

会话中途也能用 /add-dir 临时加目录。授权是会话级的，退出即失效——比把两个仓库软链在一起干净得多。

04

核心概念：记忆、权限、扩展机制

CLAUDE.md：项目记忆文件

/init 生成的 CLAUDE.md 是 Claude Code 的「项目交接文档」：构建命令、代码风格、目录结构、踩过的坑都写在这里，每次会话自动读入。层级有三层：仓库根的 CLAUDE.md（随 git 提交，全队共享）、CLAUDE.local.md（个人版，进 .gitignore）、~/.claude/CLAUDE.md（全局，对所有项目生效）。写得越具体越有用——「用 pnpm 不用 npm」「测试跑 vitest」「提交信息用中文」这种一句话，比一大段空话管用。

~/your-project/CLAUDE.md          # 团队共享，随 git 提交
~/your-project/CLAUDE.local.md    # 个人补充，进 .gitignore
~/.claude/CLAUDE.md               # 全局：对所有项目生效

# 记忆文件里还能用 @路径 引入其他文件，拆分维护
# 详见 @./docs/style-guide.md 这类写法

权限模式：Shift+Tab 一键切换

默认模式下，读文件、搜代码自动放行，写文件和跑命令每次弹审批。按 Shift+Tab 会在几个模式之间轮换，每个模式回答同一个问题——「哪些动作不用问你」：

• default：默认档，写文件、跑命令都弹审批。陌生仓库用它。
• acceptEdits：文件编辑自动接受，跑命令仍要批准。自己常维护的仓库用它。
• plan：计划模式，只读地探索并产出方案，不动任何文件。大改动开工前先待在这里。
• bypassPermissions：全部放行，对应 --dangerously-skip-permissions。只留给容器与一次性环境。

计划模式值得单独说一句：大改动前先进 plan 模式让它出方案，你批准了再动手，试错成本最低。

# 会话内随时按 Shift+Tab 轮换模式
# 启动时直接指定
claude --permission-mode plan

# 永久放行某些命令（写进 settings.json）
> /permissions

扩展机制：斜杠命令、hooks、subagents、skills

斜杠命令是操作入口（下一节速查表）；hooks 是生命周期钩子，在「每次要跑 shell 前」「每次编辑文件后」这类时机自动执行你的脚本；subagents 是带独立上下文和提示词的子代理（/agents 管理，定义放在 .claude/agents/），适合让「代码审查员」用自己的视角干活，不污染主对话；skills（.claude/skills/）把一套操作流程封装成可复用的技能，用 /skill-name 调用。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          { "type": "command", "command": "npx prettier --write ." }
        ]
      }
    ]
  }
}

---
name: reviewer
description: 严格的代码审查员，审查完主动汇报问题
tools: Read, Grep, Glob
---

你是一名资深代码审查员。只报告问题，不修改代码；
输出按「严重 / 建议 / 风格」三档分组，每条给出文件与行号。

MCP：把外部工具接进来

通过 Model Context Protocol 可以给它接数据库、浏览器、issue 系统等外部工具：项目级配置写在 .mcp.json 里随仓库共享，/mcp 查看连接状态，claude mcp add 在命令行添加。想让它能看网页、查数据库，走这条路。

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"]
    }
  }
}

# 添加（-- 后面是真正的启动命令）
claude mcp add github -- npx -y @modelcontextprotocol/server-github

# 查看 / 删除
claude mcp list
claude mcp remove github

05

速查表：四个标签页，忘什么搜什么

下面这块表格能搜。忘了某个命令叫什么，直接搜 会话、压缩、权限 之类的关键词。

06

实战：给一个真实仓库修一个跨文件 bug

走一遍完整闭环：计划 → 实现 → 验证 → 审查 → 提交。这个流程可以直接抄到你手头的项目上。

cd ~/your-project
claude

> /init                    # 新仓库先建 CLAUDE.md（做过的跳过）
> 用户反馈登录后 token 过期不会自动刷新。
  先进 plan 模式，读一下 src/auth，给我修复方案

第二步：批准方案，让它动手

方案里的每一条都可以质疑——直接回复「第 2 步换成 X」比事后返工便宜。涉及大范围的改动，动手前先开个分支，改砸了整体回退：

git checkout -b fix/token-refresh

# 方案确认后切回默认模式，按 Shift+Tab 即可
> 按刚才的方案改，改完跑 npm test，全绿再停

# 它会：改相关文件 → 自己跑测试 → 汇报结果
> /diff                     # 亲眼过一遍它改了什么

第三步：换个视角审查

> /review                  # 让它审查当前改动
> 按审查意见修完，然后帮我写一条符合仓库风格的 commit message

第四步：把审查交给 subagent，主对话保持干净

审查会产生大量「读代码」的上下文，全塞进主对话很浪费。第 04 节定义过 reviewer 子代理，这里派上用场——它的会话独立，只把结论带回主线：

> 用 reviewer 子代理审查 src/auth 的改动，只报告问题不改代码
> /agents                # 查看和管理已定义的子代理

第五步：把这次踩的坑沉淀回 CLAUDE.md

修完一件事，花一分钟把新约定写进记忆文件，下次会话就不用再教一遍：

> 把「token 刷新必须走 src/auth/refresh.ts 的统一入口」
  这条约定追加到 CLAUDE.md，保持原有格式

一次性任务的脚本化

# 不进交互界面，拿结果就走——适合 CI 或批处理
claude -p "把 CHANGELOG.md 里最近三条版本号整理成 JSON 数组输出" \
  --output-format json

# CI 里做个检查：新代码里不许出现 TODO
claude -p "git diff 里有没有新增 TODO？只回答 yes 或 no"

CI 里跑注意两点：凭证用环境变量注入的方式（以官方 CI 文档为准），并且任务描述里写清「只输出结论」——打印模式的输出会被程序消费，啰嗦的排版是负担。

07

避坑：四个最常见的翻车点

下面四个坑覆盖了新手问题的绝大多数。每一个都给出自检动作，照做即可绕开。

坑一：上下文越长，回答越慢越飘

一个会话里连干五件事，token 涨上去了，质量也会掉。模型开始忘记开头说过的约定、重复问已经确认过的问题，就是征兆。对策是把大任务拆会话：一件事做完就 /clear，接着干下一件；必须延续的用 /compact 保留修改了哪些文件和结论 指定保留重点。

坑二：一上来就 --dangerously-skip-permissions

这个开关等于把「能不能删文件、能不能跑任意命令」的判断权全交出去。它有真实用途（容器、CI、一次性虚拟机），但放在你天天用的开发机上就是在赌。养成习惯：陌生仓库用默认模式，自己的常维护仓库用 acceptEdits，plan 模式留给大重构。高频放行的命令应该固化成规则，而不是每次手点：

{
  "permissions": {
    "allow": [
      "Bash(npm run test:*)",
      "Edit(src/**)"
    ],
    "deny": [
      "Read(.env)"
    ]
  }
}

坑三：CLAUDE.md 写成散文，等于没写

记忆文件的常见死法：团队里谁都能往里加两句，半年后变成一篇没人读的内部维基。定期用 /memory 打开修剪——删掉过期的、合并重复的、把长段落改成条目。

# 反面教材：全是愿景
这是一个现代化的项目，我们追求高质量代码……

# 正面教材：全是可执行约定
- 包管理用 pnpm，禁止 npm install
- 测试：pnpm test（vitest），改 src/ 后必须跑
- 提交信息用中文，格式：模块: 动作

记忆文件是给模型看的操作手册，不是给人看的 README。条目式、命令式、有「禁止」字样，效果远好于成段的介绍文字。

坑四：终端按键没反应

Shift+Enter 换行、图片粘贴这些快捷键跟终端模拟器强相关。iTerm2、WezTerm、Ghostty、Kitty 原生支持 Shift+Enter；Apple Terminal 这类不支持的，会话里跑一次让它帮你配置：

> /terminal-setup    # 为当前终端写入换行键绑定，配置完重启会话

Windows 上粘贴图片用 Alt+V（iTerm2 用 Cmd+V）。实在不对劲，claude doctor 加上换一个现代终端，能解决绝大多数「按了没反应」。

08

进阶方向与官方资源

• code.claude.com/docs — 官方文档总站：快速上手、CLI 参考、斜杠命令、设置全在这。
• Interactive mode — 快捷键与输入模式的权威清单（本页快捷键表出自这里）。
• Slash commands — 全部斜杠命令的官方清单。
• Common workflows — 官方的常见工作流合集，值得逐条过。
• github.com/anthropics/claude-code — 官方仓库：更新日志、示例、issue 区。
• Settings 文档 — settings.json 的权限规则、hooks、环境变量完整写法。
• Subagents 文档 — 自定义子代理的定义格式与调度方式。
• Hooks 文档 — 生命周期钩子的事件名与配置示例。
• MCP 集成 — 接入外部 MCP 服务器（数据库、浏览器、issue 等）。

09

收尾：照着勾一遍

0 / 5