一份Claude Code 使用指南

本文不探讨各家模型哪个好哪个差，但很多思想都是通用的。

常见开发流程

快速获取代码库概览

假设你刚加入一个新项目，需要快速了解其结构。

1. 进入你的目录

cd /path/to/your/project

1. 打开Claude

claude

1. 获得项目概率、深入了解各个组件

> 告诉我这个代码库干了啥？

> 给我解释一下这个项目的架构

> 这里的核心数据模型是啥？

高效修复错误

假设你遇到了错误消息，需要找到并修复其来源。

1. 告诉Claude你的问题

> 在我运行 npm test 时我遇到了个错误：【paste log here】 告诉我哪里出问题了。

1. 请求修复建议

> 告诉我，他们可以怎么修改

1. 根据你的具体分析与需求应用修复

> 好的，更新user.ts支持null检验

Plan Mode

Plan Mode 指示 Claude 通过使用只读操作分析代码库来创建计划，非常适合探索代码库、规划复杂更改或安全地审查代码。在 Plan Mode 中，Claude 使用 AskUserQuestion 来收集需求并在提出计划之前澄清你的目标。

何时使用Plan Mode

简单的说，你在这些情况下最好使用Plan Mode：

• 多步骤实现：当您的功能需要编辑许多文件时
• 代码探索：当您想在更改任何内容之前彻底研究代码库时
• 交互式开发：当您想与 Claude 迭代方向时

示例

1. 开启Plan Mode(使用 Shift + Tab 进行切换)
2. 描述你的需求：

 > 我希望你将整个前端后端现代化：现在只有一个简陋的的测试前端，一些支离破碎的功能性技术验证的后端，无法成系统流程化的进行测试、验证。我希望你解决。

1. Claude在调研后会给你详尽的回复，并问你是要手动接受、全盘接受并自动根据计划推进工作，继续改进还是其他。
2. 进入Accept Edit Mode或者手动批准Claude的后续更改。

引用文件

在使用Claude Code时，很多人习惯于直接将文件拖拽进终端，使用路径的方式进行引用。这样 Claude 需要自己决定是否调用工具去读取文件，且可能需要多轮交互（搜索 → 读取 → 分析）。而使用 @/path/to/file ，文件内容立即被读取并嵌入到你的提示中（如果是目录，则会给出目录内容列表），并且一步到位，Claude 直接看到内容。所以对于文本内容，若文本量在合理范围内直接 @ 是最好的。

Git worktree

假设你需要同时处理多个任务，并在 Claude Code 实例之间完全隔离代码，Git worktree是你最好的选择。

什么是Git worktree

Git worktree 允许你从同一个仓库同时检出多个分支到不同的目录，每个目录都是一个 独立的工作区。这意味着你不再需要为了切换分支而 stash 或 commit手头未完成的工作——只需 git worktree add ../feature-branchfeature-branch，就能在另一个目录里直接开始工作。所有 worktree 共享同一份 .git数据，不会产生额外的克隆开销。它特别适合需要同时在多个分支上开发、做代码对比、或者在长时间运行的构建过程中切到另一个分支继续工作的场景。

创建新的 worktree

# 使用新分支创建新的 worktree
git worktree add ../project-feature-a -b feature-a

# 或使用现有分支创建 worktree
git worktree add ../project-bugfix bugfix-123

在每个 worktree 中运行 Claude Code

# 导航到您的 worktree
cd ../project-feature-a

# 在此隔离环境中运行 Claude Code
claude

在另一个 worktree 中运行 Claude

cd ../project-bugfix
claude

管理你的worktree

# 列出所有 worktrees
git worktree list

# 完成后删除 worktree
git worktree remove ../project-feature-a

管理你的会话

对话是持久的和可逆的。利用这一点！

尽早且经常纠正方向

最好的结果来自紧密的反馈循环。虽然 Claude 有时会在第一次尝试时完美地解决问题，但快速纠正通常会更快地产生更好的解决方案。

• Esc：使用 Esc 键停止 Claude 的中途操作。上下文被保留，所以你可以重定向。
• Esc + Esc 或 /rewind：按 Esc 两次或运行 /rewind 打开 rewind 菜单并恢复之前的对话和代码状态。
• "撤销那个"：让 Claude 恢复其更改。
• /clear：重置不相关任务之间的上下文。具有无关上下文的长会话可能会降低性能。

如果你在一个会话中对同一问题纠正了 Claude 两次以上，上下文会被失败的方法污染。运行

/clear

并使用更具体的提示重新开始，该提示包含你学到的东西。具有更好提示的干净会话几乎总是优于具有累积更正的长会话。

积极管理上下文

当你接近上下文限制时，Claude Code 会自动压缩对话历史，这保留了重要的代码和决策，同时释放空间。在长会话中，Claude 的 context window 可能会被无关的对话、文件内容和命令填满。这可能会降低性能，有时会分散 Claude 的注意力。

• 在任务之间频繁使用 /clear 以完全重置 context window
• 当自动压缩触发时，Claude 总结最重要的内容，包括代码模式、文件状态和关键决策
• 为了更好地控制，运行 /compact <instructions>，如 /compact Focus on the API changes
• 在 CLAUDE.md 中自定义压缩行为，使用像 "When compacting, always preserve the full list of modified files and any test commands" 这样的指令，以确保关键上下文在总结中幸存

使用 subagents 进行调查

由于上下文是你的基本约束，subagents 是最强大的可用工具之一。当 Claude 研究代码库时，它读取许多文件，所有这些都会消耗你的上下文。Subagents 在单独的 context windows 中运行并报告摘要：

使用 subagents 去调研这个系统的具体实现，去确定我们是否有可复用代码。

subagent 探索代码库、读取相关文件并报告发现，所有这些都不会使你的主对话变得混乱。

Hooks配置与使用

Hooks 是用户自定义的 shell 命令（或 HTTP 端点、LLM Prompt），在 Claude Code 生命周期的特定节点自动触发执行。Prompt 是”建议”，但 Hooks 是”保证”——每次匹配的事件发生时，它们都会必然执行。

核心事件类型

Hooks 支持多种生命周期事件，以下是最常用的几种：

配置方式

Hooks 在 settings 文件中配置，有三个层级：

• ~/.claude/settings.json — 用户级（全局生效）
• .claude/settings.json — 项目级（提交到 Git）
• .claude/settings.local.json — 本地项目级（不提交）

你也可以直接在 Claude Code 中输入 /hooks 打开交互式管理器。

实用示例

1. 编辑后自动格式化

每次 Claude 编辑或创建文件后，自动运行 Prettier：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|MultiEdit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write \"$CLAUDE_FILE_PATHS\" 2>/dev/null || true"
          }
        ]
      }
    ]
  }
}

2. 阻止修改敏感文件

防止 Claude 写入 .env、生产配置或 .git 目录：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|MultiEdit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "echo '{\"tool_input\":{\"file_path\":\"'\"$CLAUDE_FILE_PATH\"'\"}}' | python3 -c \"import sys,json; d=json.load(sys.stdin); p=d['tool_input']['file_path']; exit(2 if any(x in p for x in ['.env','.git/','production']) else 0)\""
          }
        ]
      }
    ]
  }
}

3. 会话启动时自动加载上下文

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "echo '最近的 Git 日志:' && git log --oneline -5 && echo '---' && echo '当前分支:' && git branch --show-current"
          }
        ]
      }
    ]
  }
}

4. Claude 完成任务后自动运行测试

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "npm test 2>&1 || echo 'Tests failed! Please fix before continuing.' >&2"
          }
        ]
      }
    ]
  }
}

5. 搭配 GitButler 自动管理分支与提交

如果你使用 GitButler，可以让 Hooks 自动管理每个 Claude 会话的代码变更，自动隔离到独立分支：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|MultiEdit|Write",
        "hooks": [{ "type": "command", "command": "but claude pre-tool" }]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|MultiEdit|Write",
        "hooks": [{ "type": "command", "command": "but claude post-tool" }]
      }
    ],
    "Stop": [
      {
        "matcher": "",
        "hooks": [{ "type": "command", "command": "but claude stop" }]
      }
    ]
  }
}

调试与注意事项

• 手动测试：在配置前先手动验证你的 hook 脚本：

  echo '{"tool_name":"test"}' | python3 your_hook.py

• 环境变量：Hooks 运行时可以访问 $CLAUDE_PROJECT_DIR（项目根目录）、$CLAUDE_FILE_PATHS 等环境变量
• 并行执行：所有匹配的 hooks 并行运行，相同的 handler 会自动去重
• 禁用所有 hooks：在 settings 中设置 "disableAllHooks": true 或在 /hooks 菜单中切换
• 安全提醒：Hooks 会在你的机器上执行任意命令，不要随意复制不信任的 hook 脚本

Spec Kit：规格驱动开发

Spec Kit 是 GitHub 开源的规格驱动开发工具包，它的核心思想是：先写规格，再写代码。不是随手丢个 prompt 就让 AI 开始生成代码，而是通过结构化的流程把需求、架构、任务拆解清楚，然后才进入实现阶段。

为什么需要 Spec Kit

传统的 Vibe Coding 模式下，你给 Claude 一句话需求，它就开始写代码。这对于小功能没问题，但当项目复杂到一定程度：

• 需求会漂移，Claude 对”你到底要什么”理解不一致
• 架构决策散落在对话中，无法追溯
• 测试标准和质量检查可能被跳过
• 多次迭代后上下文混乱，代码方向越来越偏

Spec Kit 通过强制你在写代码前先想清楚来解决这些问题。它让规格成为开发的中心——驱动实现、检查清单和任务分解。

安装

# 安装 Specify CLI（需要 Python 和 uv）
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git

# 创建新项目（指定 Claude Code 作为 AI 后端）
specify init my-project --ai claude

# 或在现有项目中初始化
cd your-existing-project
specify init --here --ai claude

# 验证安装
specify check

核心工作流程

Spec Kit 提供了五个核心斜线命令，构成一条完整的开发流水线：

/speckit.constitution → /speckit.specify → /speckit.plan → /speckit.tasks → /speckit.implement

Phase 0：/speckit.constitution — 建立项目宪法

定义项目的核心原则和开发准则，比如代码质量标准、测试要求、性能预算等。

> /speckit.constitution 专注于代码质量、测试覆盖、用户体验一致性和性能要求

Phase 1：/speckit.specify — 撰写详细规格

描述你要构建的内容，包括需求、用户故事和验收标准。

> /speckit.specify 构建一个任务管理应用，支持用户认证、实时协作和移动端适配

这一步会生成 spec.md 文件，包含详细的功能需求、数据实体和成功标准。

Phase 1.5（可选）：/speckit.clarify — 澄清模糊需求

如果规格中有模糊的地方，用这个命令让 Claude 进行结构化提问：

> /speckit.clarify 每个示例项目应包含 5-15 个随机分布在不同完成状态的任务，确保每个阶段至少有一个任务

Phase 2：/speckit.plan — 制定技术计划

提供技术方向，让 Claude 生成详细的实施计划：

> /speckit.plan 使用 React + Vite 构建前端，Tailwind CSS 做样式，SQLite 做本地存储

输出包括技术选型、数据模型设计、API 契约、项目结构等。

Phase 3：/speckit.tasks — 生成任务清单

基于计划自动生成结构化、可执行的任务列表，按依赖顺序排列。

Phase 4：/speckit.implement — 执行实现

按照任务清单开始编码，遵循 TDD 原则（先写测试，再写实现）。

> /speckit.implement

辅助命令

使用 Subagent 实现全自动流水线

如果你想让 Claude Code 一句话跑完整个流程，可以搭配 subagent 使用。在 .claude/agents/ 下创建一个 spec-kit agent，让它自动依次执行各个 /speckit.* 命令：

---
name: spec-kit-feature-agent
description: 使用 spec-kit 全流程完成一个功能需求
---

这样，你只需一句话：

> 使用 spec-kit，完成一个用户评论系统的需求

Claude 就会自动走完 constitution → specify → plan → tasks → implement 的完整流程。

何时使用 / 不使用 Spec Kit

适合使用的场景：

• 从零开始构建新项目或添加重大功能
• 需求复杂、涉及多个模块的长期项目
• 团队协作，需要统一的规格文档
• 你希望 Claude 有序地、端到端地完成工作

不适合使用的场景：

• 修复一个小 bug
• 微调一个小功能
• 快速原型验证
• 项目已经很成熟，只需要局部改动

最后的一些建议

CLAUDE.md 是你的项目记忆

CLAUDE.md 文件会在每次会话开始时自动加载到 Claude 的上下文中。把你的项目约定、代码规范、常用命令、架构决策都写在里面：

# 项目概览
## 架构
- 前端: Next.js 14 + TypeScript
- 后端: Node.js + Express
- 数据库: PostgreSQL + Prisma ORM

## 常用命令
- `npm run dev` — 启动开发服务器
- `npm run test` — 运行测试
- `npm run lint` — 代码检查

## 代码规范
- 使用 TypeScript strict mode
- 组件不超过 200 行
- 公共函数添加 JSDoc 注释
- 优先使用成熟的库，不要自己造轮子

## 压缩策略
当 compacting 时，始终保留已修改文件的完整列表和所有测试命令。

权限管理

Claude Code 在执行需要写入或运行命令时会请求权限。根据你的信任程度选择：

• 逐个批准：默认模式，最安全
• Accept Edit Mode：自动批准编辑但保留对命令的控制，适合你信任 Claude 的修改方向时
• -dangerously-skip-permissions：跳过所有权限提示，仅在自动化和 CI/CD 场景下使用

组合使用的最佳实践

将本文介绍的各种工具组合起来，一个高效的开发流程可能是这样的：

1. Git worktree 隔离工作环境 → 每个功能一个目录
2. CLAUDE.md 提供项目上下文 → Claude 一上来就知道该怎么做
3. Spec Kit 驱动复杂需求 → 先规格后代码
4. Plan Mode 辅助设计阶段 → 充分调研再动手
5. Hooks 保障代码质量 → 自动格式化、自动测试、阻止危险操作
6. Subagents 处理调研任务 → 不污染主会话上下文
7. 频繁 /clear 保持干净上下文 → 干净上下文 > 长对话