Claude Code 完全入门指南

前言

Claude Code 是 Anthropic 官方推出的命令行工具，让你能够在终端中直接与 Claude AI 协作完成软件开发任务。不同于在网页中复制粘贴代码，Claude Code 可以直接读取、编辑你的本地文件，执行命令，甚至帮你提交代码——这一切都在你的控制之下。

本文将从零开始，带你了解 Claude Code 的核心概念，完成基础配置，并开始第一个实践项目。

---

💡 国内访问 Claude和Codex： weelinking - 直连、稳定、不折腾

一、Claude Code 是什么

1.1 核心能力

Claude Code 是一个AI 辅助编程工具，它可以：

• 读取和编辑文件 - 理解你的代码库结构，直接修改源代码
• 执行终端命令 - 运行测试、安装依赖、执行 git 操作
• 搜索代码 - 快速查找文件、函数、类定义
• 生成和重构代码 - 编写新功能、优化现有代码、修复 bug
• 理解上下文 - 记住项目的编码规范和特定约定

1.2 工作模式

Claude Code 通过对话式交互完成任务：

# 启动 Claude Code
claude

# 然后你可以这样提问
You: 帮我在 src/utils.js 中添加一个日期格式化函数
Claude: 我会读取文件，添加函数，并解释实现细节

You: 运行测试看看是否通过
Claude: 我会执行 npm test 并分析结果

1.3 权限控制

重要的是，你始终掌握控制权：

• 所有文件操作都需要你的确认（除非你明确授权）
• 可以配置哪些命令允许自动执行，哪些需要批准
• 支持"只读模式"，让 Claude 只查看代码不修改

---

二、安装与基础配置

2.1 安装 Claude Code

（假设用户已完成安装，此处提供快速参考）

macOS/Linux:

# 使用 npm 安装
npm install -g @anthropics/claude-code

# 验证安装
claude --version

Windows:

# 使用 npm 安装
npm install -g @anthropics/claude-code

# 验证安装
claude --version

💡 国内访问 Claude和Codex： weelinking - 直连、稳定、不折腾

2.2 首次登录

# 启动并登录
claude

# 系统会引导你通过浏览器完成认证
# 选择使用 Claude.ai 账号或 Anthropic Console 账号登录

2.3 验证工作目录

Claude Code 会在你当前所在的目录启动：

# 进入你的项目目录
cd /path/to/your/project

# 启动 Claude Code
claude

启动后，Claude 可以访问这个目录及其子目录下的所有文件。

---

三、核心概念介绍

3.1 配置层级（Settings Hierarchy）

Claude Code 使用多层配置系统，优先级从高到低：

优先级	配置文件位置	作用范围	是否提交到 Git
1	命令行参数	单次会话	-
2	.claude/settings.local.json	当前项目（个人）	❌ 不提交
3	.claude/settings.json	当前项目（团队）	✅ 提交共享
4	~/.claude/settings.json	全局（个人）	-

实用建议：

• 个人偏好 → 放在 ~/.claude/settings.json（如默认模型、语言）
• 团队规范 → 放在 .claude/settings.json（如代码风格、提交规范）
• 临时测试 → 使用 .claude/settings.local.json（不会影响团队）

3.2 CLAUDE.md 文件

CLAUDE.md 是项目的"说明书"，告诉 Claude：

• 项目的架构和组织方式
• 代码规范和最佳实践
• 特定的命名约定
• 常用的开发工作流

示例 CLAUDE.md：

# 项目说明

## 技术栈
- React 18 + TypeScript
- 使用 Vite 作为构建工具
- 使用 Vitest 进行单元测试

## 代码规范
- 所有组件使用函数式组件（不使用类组件）
- Props 必须定义 TypeScript 类型
- 文件名使用 PascalCase（如 UserProfile.tsx）

## 测试规范
- 每个组件必须有对应的 .test.tsx 文件
- 测试文件与组件文件放在同一目录
- 运行测试：npm test

## 提交规范
- 使用 Conventional Commits 格式
- 提交前必须运行 npm run lint

CLAUDE.md 的加载机制：

1. 向上查找（Ancestor Loading） - 启动时自动加载从当前目录到根目录的所有 CLAUDE.md
2. 向下延迟加载（Descendant Loading） - 子目录的 CLAUDE.md 只在访问该目录的文件时加载

实际例子：

/myproject/
├── CLAUDE.md              # 全局规范（启动时加载）
├── frontend/
│   └── CLAUDE.md          # 前端规范（编辑 frontend/ 文件时加载）
└── backend/
    └── CLAUDE.md          # 后端规范（编辑 backend/ 文件时加载）

如果你在 /myproject/ 启动 Claude Code：

• 根目录的 CLAUDE.md 立即加载
• frontend/CLAUDE.md 和 backend/CLAUDE.md 按需加载

3.3 Skills 技能系统

Skills 是可复用的命令或工作流，类似于自定义的快捷指令。

Skills 存放位置：

位置	路径	作用范围
个人	~/.claude/skills/<skill-name>/SKILL.md	你的所有项目
项目	.claude/skills/<skill-name>/SKILL.md	当前项目
包级别	packages/frontend/.claude/skills/	Monorepo 中的特定包

示例 Skill：

创建 .claude/skills/commit-check/SKILL.md：

---
name: commit-check
description: 提交前检查代码质量
---

# 提交前检查流程

执行以下步骤：

1. 运行 `npm run lint` 检查代码风格
2. 运行 `npm test` 确保测试通过
3. 如果都通过，询问用户是否要提交
4. 如果用户确认，执行 `git add .` 和 `git commit`

使用 Skill：

You: /commit-check
Claude: 我会执行提交前检查流程...

Skills 与 CLAUDE.md 的区别：

特性	CLAUDE.md	Skills
用途	静态知识（规范、约定）	动态命令（工作流）
调用方式	自动加载	手动调用（/skill-name）
内容加载	全文加载	仅描述加载，调用时加载全文

---

四、第一个实践：创建项目级配置

4.1 初始化项目配置

假设你有一个 Node.js 项目，我们来创建配置文件：

步骤 1：创建配置目录

mkdir .claude

步骤 2：创建 CLAUDE.md

创建 .claude/CLAUDE.md 或直接在项目根目录创建 CLAUDE.md：

# 我的 Node.js 项目

## 项目信息
- 这是一个 Express.js 后端 API 项目
- 使用 ES Modules (import/export)
- Node 版本：18+

## 开发规范
- 所有 API 路由定义在 src/routes/
- 数据库模型定义在 src/models/
- 业务逻辑放在 src/services/

## 测试
- 使用 Jest 进行单元测试
- 运行测试：npm test
- 测试覆盖率：npm run test:coverage

## 数据库
- 使用 PostgreSQL
- 迁移文件位于 migrations/
- 运行迁移：npm run migrate

## 环境变量
- 本地开发使用 .env.local（不提交到 Git）
- 生产环境变量配置在部署平台

## 提交规范
- feat: 新功能
- fix: 修复 bug
- refactor: 代码重构
- docs: 文档更新
- test: 测试相关

步骤 3：创建权限配置

创建 .claude/settings.json：

{
  "permissions": {
    "default": "ask",
    "rules": [
      {
        "tool": "Bash",
        "allow": [
          "npm test",
          "npm run lint",
          "git status",
          "git diff"
        ]
      },
      {
        "tool": "Edit",
        "ask": ["*.js", "*.json"]
      }
    ]
  },
  "attribution": {
    "commit": "Co-Authored-By: Claude Sonnet <noreply@anthropic.com>"
  }
}

配置说明：

• "default": "ask" - 默认所有操作都需要询问
• allow 列表 - 这些命令可以自动执行（如运行测试）
• ask 规则 - 编辑 JS 和 JSON 文件时需要确认

4.2 测试配置

启动 Claude Code 并测试：

claude

测试 1：让 Claude 读取 CLAUDE.md

You: 我们的项目使用什么技术栈？
Claude: 根据 CLAUDE.md，这是一个 Express.js 后端 API 项目...

测试 2：测试权限配置

You: 运行测试看看项目状态
Claude: 我会执行 npm test...（自动执行，无需确认）

测试 3：测试文件编辑

You: 在 src/utils.js 添加一个函数
Claude: 我会编辑文件...（弹出确认提示）

---

五、常用命令速查表

5.1 内置命令

命令	功能
/help	显示帮助信息
/clear	清空当前对话历史
/reset	重置会话（保留配置）
/exit	退出 Claude Code
/context	查看当前上下文信息
/plan	进入计划模式（适合复杂任务）

5.2 对话技巧

有效的提问方式：

✅ 明确具体

"在 src/auth.js 中添加 JWT token 验证中间件，使用 jsonwebtoken 库"

✅ 提供上下文

"我们的 API 路由在 routes/ 目录，请添加一个新的 /api/users 路由，
包含 GET 和 POST 方法，使用 Express Router"

✅ 分步骤

"首先读取 package.json 确认依赖，然后创建 User 模型文件"

❌ 避免模糊指令

"优化代码"  // 太宽泛
"修复那个 bug"  // 没有指明哪个 bug
"帮我写个函数"  // 没有说明需求

5.3 权限相关

查看当前权限设置：

You: /context
Claude: [显示当前配置、权限规则、加载的 CLAUDE.md 等]

临时授权：

• 当 Claude 请求权限时，可以选择：
  • Allow once - 本次允许
  • Allow always - 始终允许（会更新配置）
  • Deny - 拒绝本次操作

---

💡 国内访问 Claude和Codex： weelinking - 直连、稳定、不折腾

六、实战案例：第一个完整工作流

场景：为项目添加日志功能

步骤 1：描述需求

You: 我想为项目添加日志功能。要求：
- 使用 winston 库
- 日志文件保存到 logs/ 目录
- 开发环境输出到控制台，生产环境输出到文件
- 支持不同日志级别（info, warn, error）

步骤 2：Claude 制定计划

Claude: 我会执行以下步骤：
1. 检查 package.json 中是否已安装 winston
2. 如果没有，建议你运行 `npm install winston`
3. 创建 src/utils/logger.js 配置文件
4. 在 CLAUDE.md 中记录日志使用规范

步骤 3：执行并验证

You: 开始吧
Claude: [执行操作...]
完成！已创建 logger.js，使用方法：

import logger from './utils/logger.js';
logger.info('应用启动');
logger.error('发生错误', { error });

步骤 4：更新文档

You: 更新 CLAUDE.md，记录日志的使用规范
Claude: [自动更新 CLAUDE.md...]

---

七、故障排查

7.1 Claude 找不到文件

问题： “我找不到 xxx 文件”

解决方法：

# 确认当前工作目录
pwd

# 使用绝对路径
You: 读取 /Users/yourname/project/src/app.js

# 或使用 ./ 相对路径
You: 读取 ./src/app.js

7.2 权限被拒绝

问题： “我没有权限执行 xxx”

解决方法：

1. 检查 .claude/settings.json 的 permissions 配置
2. 临时授权：在提示时选择 “Allow always”
3. 或使用 viewOnly 模式查看代码：

   {
     "permissions": {
       "default": "viewOnly"
     }
   }
   

7.3 CLAUDE.md 没有被加载

问题： Claude 似乎没有读取项目规范

检查方法：

You: /context
# 查看 "Loaded CLAUDE.md files" 部分

解决方法：

• 确认文件名是 CLAUDE.md（全大写）
• 确认文件位于项目根目录或 .claude/ 目录
• 重启 Claude Code 会话

---

八、下一步学习建议

完成本入门指南后，你可以继续学习：

1. 深入配置 → 阅读《深入理解 Claude Code 配置系统》

   • 学习高级权限控制
   • 配置 Hooks 钩子系统
   • 集成 MCP 工具

2. Monorepo 项目 → 阅读《Monorepo 项目中的 Claude Code 最佳实践》

   • 多包项目的配置策略
   • CLAUDE.md 和 Skills 的组织方式

3. 自动化工作流 → 阅读《Claude Code Hooks 钩子系统实战指南》

   • 提交前自动检查
   • 自定义工作流
   • 与 CI/CD 集成

4. 浏览器自动化 → 阅读《浏览器自动化测试工具选择指南》

   • E2E 测试
   • 性能调试
   • Chrome DevTools 集成

---

九、常见问题 FAQ

Q1: Claude Code 是否会自动修改我的代码？

A: 不会。默认情况下，所有文件编辑都需要你的确认。你可以通过配置 permissions 来决定哪些操作允许自动执行。

Q2: 我的 API Key 会被泄露吗？

A: Claude Code 使用安全的认证机制，API Key 存储在本地配置中，不会被发送到除 Anthropic 服务器之外的任何地方。

Q3: 可以在离线环境使用吗？

A: 不可以。Claude Code 需要联网才能与 Claude AI 通信。

Q4: 支持哪些编程语言？

A: Claude Code 支持几乎所有编程语言，包括但不限于：JavaScript/TypeScript, Python, Java, Go, Rust, C++, Ruby, PHP 等。

Q5: 如何在团队中共享配置？

A: 将 .claude/settings.json 和 CLAUDE.md 提交到 Git 仓库。个人配置使用 .claude/settings.local.json（添加到 .gitignore）。

Q6: Claude Code 会记住之前的对话吗？

A: 会话历史存储在本地，下次启动时可以继续。你可以使用 /clear 清空历史，或使用 /reset 重置会话。

Q7: 如何获取帮助？

A:

• 使用 /help 命令查看内置帮助
• 访问官方文档：https://code.claude.com/docs
• 提交问题：https://github.com/anthropics/claude-code/issues

---

十、总结

本文介绍了 Claude Code 的核心概念和基础使用方法：

✅ 安装与启动 - 了解工作目录和登录流程
✅ 配置层级 - 理解全局配置、项目配置、个人配置的优先级
✅ CLAUDE.md - 编写项目说明书，让 Claude 理解你的项目
✅ Skills 系统 - 创建可复用的命令和工作流
✅ 权限控制 - 掌握安全使用 Claude Code 的方法
✅ 实战演练 - 完成第一个完整的开发任务

现在，你已经具备了使用 Claude Code 的基础能力。开始在你的项目中尝试吧！

---

参考资源

• Claude Code 官方文档
• Claude Code GitHub 仓库
• Claude API 文档
• weelinking - 直连、稳定、不折腾:国内访问 Claude和Codex