Claude Code 使用指南

学习如何使用 Claude Code 加速造岛 ZaoDao 项目的开发，提升编码效率。

什么是 Claude Code

Claude Code 是 Anthropic 推出的 AI 编程助手 CLI 工具，能够直接在终端中理解你的代码库、执行代码修改、运行命令，并协助完成复杂的开发任务。它与 IDE（VS Code、JetBrains）深度集成，提供实时的代码建议和自动化操作。

🧠

代码理解

自动分析整个项目结构，理解模块关系与依赖

✏️

智能编码

根据上下文生成、修改和重构代码

🔧

自动化操作

执行 Shell 命令、搜索文件、运行构建

📖

文档驱动

通过 CLAUDE.md 文件定制项目级行为

🛠️

Skills 扩展

通过自定义技能扩展 Claude 能力

🔌

MCP 集成

连接外部工具和数据库

安装与配置

安装

通过 npm 全局安装 Claude Code CLI：

bash
npm install -g @anthropic-ai/claude-code

启动

在项目根目录启动 Claude Code 交互式会话：

bash
# 进入项目目录
cd /opt/scaffold-portal

# 启动 Claude Code
claude

# 恢复上一次会话
claude --continue

# 使用指定模型
claude --model claude-sonnet-4-6

ℹ️ 首次使用

首次运行时，Claude Code 会引导你完成 API Key 配置和认证流程。请确保你拥有有效的 Anthropic 账户。

权限配置

在项目根目录创建 .claude/settings.json 配置权限：

json
{
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(git *)",
      "Read",
      "Edit",
      "Write",
      "Grep"
            ],
    "deny": [
      "Bash(rm -rf *)"
    ],
    "defaultMode": "default"
  }
}

权限模式

  • default — 每个工具首次使用时提示权限
  • acceptEdits — 自动接受文件编辑
  • plan — 只读模式，Claude 只探索不编辑
  • auto — 自动批准带安全检查

Skills 系统

Skills（技能）是扩展 Claude Code 能力的方式，通过编写 SKILL.md 文件定义特定任务的自动化流程。

Skills 存放位置

范围路径生效范围
项目级.claude/skills/<name>/SKILL.md当前项目
个人级~/.claude/skills/<name>/SKILL.md所有项目
企业级通过托管设置部署组织内所有用户

SKILL.md 结构

markdown
---
name: my-skill
description: 自动格式化代码并运行测试
disable-model-invocation: false
allowed-tools: Bash(npm run *) Read Edit
---

当用户请求运行测试时：
1. 检查 git 状态，显示未提交的更改
2. 运行 npm run test
3. 如果测试失败，分析失败原因
4. 建议修复方案

$ARGUMENTS 将包含用户输入的额外参数

动态上下文注入

使用 !`command` 语法在技能激活时执行命令并注入输出：

markdown
当前分支: !`git branch --show-current`
未提交的文件:
```!
git status --short
```

内置 Skills

Claude Code 预装了以下实用技能：

  • /code-review — 审查代码 diff，发现 bug 和改进点
  • /simplify — 等同于 /code-review --fix，自动修复问题
  • /debug — 启用调试日志并排查问题
  • /loop — 定期重复执行任务
  • /claude-api — 加载 Claude API 参考文档
  • /run — 启动并驱动应用程序（v2.1.145+）
  • /verify — 运行应用验证更改（v2.1.145+）

使用 Skills

在会话中输入 /skill-name 调用技能，或直接描述需求，Claude 会自动识别并调用相关技能。

Hooks 自动化

Hooks（钩子）是在特定事件发生时自动执行的命令，可用于代码格式化、测试运行、通知等自动化场景。

Hook 事件类型

事件触发时机
SessionStart会话开始或恢复
UserPromptSubmit用户提交提示前
PreToolUse工具执行前（可阻止）
PostToolUse工具执行成功后
PostToolUseFailure工具执行失败后
StopClaude 完成响应后
FileChanged监视的文件变更时

配置示例

json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write $CLAUDE_FILE_PATH"
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "if": "Bash(rm *)",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.sh"
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "notify-send 'Claude finished'"
          }
        ]
      }
    ]
  }
}

退出码语义

  • 0 — 不做决策，正常流程继续
  • 2 — 阻止当前操作
  • 其他 — 视为错误，忽略 hook

MCP 集成

MCP（Model Context Protocol）是 AI 工具集成的开放标准，让 Claude 能够连接外部工具、数据库和 API。

安装 MCP 服务器

bash
# HTTP 传输（远程服务器）
claude mcp add --transport http notion https://mcp.notion.com/mcp

# 带认证头
claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
  --header "Authorization: Bearer YOUR_GITHUB_PAT"

# Stdio 传输（本地进程）
claude mcp add --transport stdio --env AIRTABLE_API_KEY=KEY airtable \
  -- npx -y airtable-mcp-server

项目级配置

创建 .mcp.json 文件实现团队共享：

json
{
  "mcpServers": {
    "database-tools": {
      "command": "npx",
      "args": ["-y", "@bytebase/dbhub"],
      "env": {
        "DB_URL": "${DATABASE_URL}"
      }
    },
    "remote-api": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    }
  }
}

环境变量扩展

支持 ${VAR} 和 ${VAR:-default} 语法，在 command、args、env、url 和 headers 中均可使用。

管理命令

bash
claude mcp list          # 列出所有服务器
claude mcp get github     # 获取服务器详情
claude mcp remove github  # 移除服务器
/mcp                       # 会话内检查服务器状态

记忆系统

Claude Code 的记忆系统通过多层级的 CLAUDE.md 文件和自动记忆功能实现项目上下文的持久化。

记忆层级

类型位置目的共享范围
企业策略/etc/claude-code/CLAUDE.md组织级规则所有用户
项目记忆./CLAUDE.md团队共享指令团队（通过版本控制）
用户记忆~/.claude/CLAUDE.md个人偏好仅自己

导入系统

使用 @path/to/import 语法导入其他文件：

markdown
# 项目约定

@docs/coding-standards.md
@~/.claude/personal-preferences.md

自动记忆

Claude 会自动记录有价值的洞察（模式、偏好、修正）到自动记忆中，跨会话保持一致性。使用 /memory 命令管理记忆文件。

快速添加记忆

在输入开头使用 # 可快速添加记忆：

交互示例
> # 这个项目的 API 端点都返回统一的 { code, data, msg } 结构

Claude 会提示你选择要存储到哪个记忆文件。

斜杠命令

Claude Code 提供丰富的斜杠命令，以下是常用命令列表：

/help显示帮助信息
/clear清除对话历史
/compact压缩上下文释放空间
/diff交互式查看未提交更改
/context可视化上下文使用情况
/config打开设置界面
/permissions管理权限规则
/memory编辑 CLAUDE.md 和记忆
/skills列出可用技能
/hooks查看 hook 配置
/mcp管理 MCP 服务器
/usage显示成本和配额
/status显示版本和状态
/fast切换快速模式
/plan进入计划模式

命令别名

  • /reset、/new — 等同于 /clear
  • /continue、/resume — 恢复会话
  • /settings — 等同于 /config
  • /stats、/cost — 等同于 /usage

IDE 集成

VS Code

  • 在扩展市场搜索 "Claude Code" 并安装
  • 集成了终端支持和差异查看
  • 当前选择和标签页内容自动共享给 Claude
  • Lint 和类型错误自动共享

JetBrains

  • 支持的 IDE：IntelliJ IDEA、PyCharm、WebStorm、PhpStorm、GoLand 等
  • 快捷启动：Cmd+Esc（Mac）或 Ctrl+Esc（Windows/Linux）
  • 文件引用快捷键：Cmd+Option+K（Mac）或 Alt+Ctrl+K（Linux/Windows）
  • 配置路径：Settings > Tools > Claude Code [Beta]

⚠️ 远程开发注意事项

对于远程开发环境，插件必须安装在远程主机上。WSL 环境可能需要配置防火墙规则或镜像网络模式。

常用工作流

1. 添加新模块

在 Claude Code 中描述你想要添加的业务模块：

prompt 示例
在 moduleRegistry.ts 中添加一个新的业务模块 "report"（报表），
它依赖 common 和 system 模块，对应 /opt/scaffold/scaffold-server/scaffold-report 目录。

Claude Code 会自动：

  • 读取 moduleRegistry.ts 了解现有模块结构
  • 按照相同模式添加新模块定义
  • 更新依赖关系
  • 检查前端模块选择器是否需要同步更新

2. 修复 Bug

prompt 示例
下载生成的 ZIP 文件中 POM 的 module 列表包含了未选中的模块，
帮我排查 cropper.ts 和 pomTransformer.ts 中的过滤逻辑。

3. 添加 API 端点

prompt 示例
添加一个 GET /api/generator/templates 端点，
返回可用的项目模板列表，参考现有 download.post.ts 的风格。

4. 前端组件开发

prompt 示例
在 ModuleSelector 组件中增加一个搜索框，
支持按模块名称过滤，参考现有 ModuleCard 的样式风格。

常见问题

Claude Code 可以修改哪些文件？

Claude Code 可以读取和编辑项目中的所有文件，但每次修改都需要你的确认（除非你在配置中预先授权）。对于危险操作（如删除文件、Git push），Claude Code 会额外提醒你确认。

如何让 Claude Code 遵循项目的编码风格？

CLAUDE.md 中已记录了项目的编码约定。你也可以在对话中补充说明，例如："按照 ModuleCard.vue 的现有风格来写"。Claude Code 会自动参考相邻代码的格式。

对话太长导致响应变慢怎么办？

使用 /compact 命令压缩上下文，或使用 /clear 开启新对话。对于新的独立任务，建议开启新会话以保持上下文的清晰度。

如何在团队中共享 Claude Code 配置？

将项目根目录的 CLAUDE.md 文件纳入版本控制，这样团队成员都能使用一致的项目上下文。个人偏好配置（如权限设置）放在 .claude/settings.json 中，该文件应加入 .gitignore。

Skills 和 Hooks 有什么区别？

Skills 是用户主动调用的可重用技能（/skill-name），而 Hooks 是在特定事件自动触发的自动化操作。Skills 用于扩展 Claude 能力，Hooks 用于实现确定性自动化流程。

如何查看和管理 MCP 服务器状态？

在 Claude Code 会话中输入 /mcp 查看所有已配置服务器的连接状态。使用 claude mcp list、claude mcp get <name>、claude mcp remove <name> 管理服务器。

📚 更多资源