Claude Code从零起步：安装到首个项目交付

graph LR
    A[你输入目标] --> B[Claude Code<br/>规划执行步骤]
    B --> C[读取文件]
    B --> D[编写/修改代码]
    B --> E[运行命令]
    B --> F[运行测试]
    C --> G[检查结果]
    D --> G
    E --> G
    F --> G
    G -->|有问题| B
    G -->|完成| H[交付结果]

# 安装Homebrew（如果没有）
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 安装Node.js
brew install node

# 验证安装
node --version   # 应输出 v20.x.x 或更高
npm --version    # 应输出 10.x.x 或更高

# 使用NodeSource安装Node.js 20 LTS
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# 验证
node --version
npm --version

# 在PowerShell（管理员）中安装WSL2
wsl --install

# 重启后，打开WSL终端（Ubuntu），然后执行Linux安装步骤

# macOS
brew install git

# Linux
sudo apt-get install git

# 验证
git --version   # 应输出 git version 2.x.x

# 初始配置（必须）
git config --global user.name "你的名字"
git config --global user.email "你的邮箱"

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

claude --version
# 应输出类似：Claude Code v1.x.x

graph TD
    A[开始认证] --> B{你有哪种账户?}
    B -->|Claude Pro/Max订阅| C[OAuth登录<br/>claude login]
    B -->|Anthropic API Key| D[环境变量<br/>ANTHROPIC_API_KEY]
    B -->|企业账户| E[SSO/Azure/Bedrock]
    C --> F[✅ 可以开始使用]
    D --> F
    E --> F

claude login

# 1. 在 console.anthropic.com 创建API Key
# 2. 设置环境变量

# macOS/Linux（临时）
export ANTHROPIC_API_KEY="sk-ant-api03-xxxxx"

# macOS/Linux（永久，写入shell配置文件）
echo 'export ANTHROPIC_API_KEY="sk-ant-api03-xxxxx"' >> ~/.zshrc
source ~/.zshrc

# 验证
claude --version

# Azure OpenAI
export CLAUDE_CODE_USE_BEDROCKETC=1

# AWS Bedrock  
export CLAUDE_CODE_USE_BEDROCK=1

# 具体配置参考企业内部文档

# 创建一个测试目录
mkdir ~/claude-hello && cd ~/claude-hello

# 初始化Git（强烈推荐）
git init

# 启动Claude Code
claude

╭──────────────────────────────────────╮
│  Claude Code                          │
│  Model: claude-sonnet-4-6-20250514    │
│  Context: /home/user/claude-hello     │
╰──────────────────────────────────────╯

>

> 你好，请简单介绍你自己，并告诉我你能做什么

graph TB
    subgraph "交互模式（Interactive）"
        A1[输入 claude] --> A2[进入REPL对话]
        A2 --> A3[多轮连续对话]
        A3 --> A4[上下文保持]
    end
    subgraph "单次模式（One-shot）"
        B1[claude -p '任务描述'] --> B2[执行一次]
        B2 --> B3[输出结果并退出]
    end

cd your-project
claude
# 进入交互式对话

claude -p "列出当前目录下所有TypeScript文件并统计代码行数"

┌─ Claude wants to edit src/index.ts ─────────────────────┐
│                                                          │
│  + import express from 'express';                        │
│  + const app = express();                                │
│                                                          │
│  Allow? (y/n/always)                                    │
└──────────────────────────────────────────────────────────┘

cd your-project
claude

> /init

# CLAUDE.md

## 项目概述
一个使用Express.js + TypeScript构建的RESTful API服务。

## 技术栈
- Runtime: Node.js 20 LTS
- Language: TypeScript 5.x
- Framework: Express.js 4.x
- Database: SQLite (开发环境)
- Testing: Vitest

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

## 代码风格
- 使用ESLint + Prettier
- 缩进：2空格
- 命名：camelCase（变量/函数），PascalCase（类/接口）
- 注释：英文注释

## 目录结构
- `src/` — 源代码
- `src/routes/` — 路由定义
- `src/models/` — 数据模型
- `src/middleware/` — 中间件
- `tests/` — 测试文件

## 重要规则
- 所有新代码必须有对应的测试
- API端点必须包含输入验证
- 错误处理使用统一的中介层
- 不要使用any类型

graph TD
    A["~/.claude/CLAUDE.md<br/>（全局，所有项目生效）"] --> B["项目根目录/CLAUDE.md<br/>（项目级，核心）"]
    B --> C["子目录/CLAUDE.md<br/>（目录级，局部覆盖）"]

    style A fill:#e8f4fd,stroke:#2196F3
    style B fill:#fff3e0,stroke:#FF9800
    style C fill:#e8f5e9,stroke:#4CAF50

# 创建项目目录
mkdir ~/task-api && cd ~/task-api

# 初始化Git
git init

# 初始化Node.js项目
npm init -y

claude

> /init

> 我想用Express.js + TypeScript构建一个任务管理API。
> 功能包括：
> 1. 创建任务（POST /tasks）
> 2. 获取所有任务（GET /tasks）
> 3. 获取单个任务（GET /tasks/:id）
> 4. 更新任务（PUT /tasks/:id）
> 5. 删除任务（DELETE /tasks/:id）
> 
> 技术要求：
> - TypeScript
> - Express.js
> - 内存存储（使用Map）
> - 输入验证
> - 错误处理中间件
> - Vitest测试
> 
> 请先安装依赖，然后创建项目结构。

Step 1: 安装依赖
  $ npm install express
  $ npm install -D typescript @types/express @types/node vitest tsx

Step 2: 创建目录结构
  src/
  ├── index.ts          # 入口文件
  ├── routes/
  │   └── tasks.ts      # 任务路由
  ├── models/
  │   └── task.ts       # 任务模型
  ├── middleware/
  │   └── errorHandler.ts  # 错误处理
  └── types/
      └── index.ts      # 类型定义

Step 3: 编写代码文件

Step 4: 创建测试文件

Step 5: 更新package.json scripts

export interface Task {
  id: string;
  title: string;
  description?: string;
  completed: boolean;
  createdAt: Date;
  updatedAt: Date;
}

export interface CreateTaskInput {
  title: string;
  description?: string;
}

export interface UpdateTaskInput {
  title?: string;
  description?: string;
  completed?: boolean;
}

import { Task, CreateTaskInput, UpdateTaskInput } from '../types';

const tasks = new Map<string, Task>();

export function findAll(): Task[] {
  return Array.from(tasks.values());
}

export function findById(id: string): Task | undefined {
  return tasks.get(id);
}

export function create(input: CreateTaskInput): Task {
  const task: Task = {
    id: crypto.randomUUID(),
    title: input.title,
    description: input.description,
    completed: false,
    createdAt: new Date(),
    updatedAt: new Date(),
  };
  tasks.set(task.id, task);
  return task;
}

export function update(id: string, input: UpdateTaskInput): Task | undefined {
  const task = tasks.get(id);
  if (!task) return undefined;
  Object.assign(task, { ...input, updatedAt: new Date() });
  return task;
}

export function remove(id: string): boolean {
  return tasks.delete(id);
}

> 请运行测试，确保所有测试通过

npm test

 ✓ models/task > create > 应该创建新任务
 ✓ models/task > findAll > 应该返回所有任务
 ✓ models/task > findById > 应该根据ID查找任务
 ✓ models/task > update > 应该更新任务属性
 ✓ models/task > remove > 应该删除任务

 Test Files  1 passed (1)
  Tests  5 passed (5)

> 请启动开发服务器，并测试所有API端点

> 请帮我提交这次的代码，commit message用中文

> 请给任务添加优先级字段（high/medium/low），
> 并添加按优先级筛选的查询参数 ?priority=high

> /compact

> /model

> /cost

# 在settings.json中设置每日/每月费用上限
claude config set --global maxCostPerDay 10    # 每天最多$10
claude config set --global maxCostPerMonth 200  # 每月最多$200

# 如果WSL中无法打开浏览器进行OAuth认证
# 使用API Key方式代替
export ANTHROPIC_API_KEY="sk-ant-api03-xxxxx"

# 如果文件系统性能差
# 把项目放在WSL原生文件系统中（~/projects/）
# 而不是Windows挂载路径（/mnt/c/）

graph TD
    A[✅ 完成本教程<br/>安装+首个项目] --> B[掌握CLAUDE.md<br/>编写高质量项目说明]
    B --> C[学习Slash命令<br/>/init /compact /review]
    C --> D[配置Settings<br/>权限/模型/费用控制]
    D --> E[创建自定义命令<br/>.claude/commands/]
    E --> F[接入MCP服务器<br/>扩展工具能力]
    F --> G[开发Skills<br/>构建可复用工作流]
    G --> H[Agent模式<br/>-p自动化/Hooks]

    style A fill:#4CAF50,color:#fff
    style B fill:#4CAF50,color:#fff
    style C fill:#4CAF50,color:#fff
    style D fill:#FF9800,color:#fff
    style E fill:#FF9800,color:#fff
    style F fill:#2196F3,color:#fff
    style G fill:#2196F3,color:#fff
    style H fill:#9C27B0,color:#fff

sequenceDiagram
    participant D as 开发者
    participant CC as Claude Code
    participant F as 文件系统
    participant G as Git

    D->>CC: cd project && claude
    CC->>F: 读取CLAUDE.md
    F-->>CC: 项目规范加载完成

    D->>CC: "添加用户注册API"
    CC->>F: 读取现有代码
    CC->>CC: 规划实现步骤
    CC->>D: 请求权限：创建 src/routes/auth.ts
    D->>CC: y (允许)
    CC->>F: 写入文件
    CC->>D: 请求权限：创建 tests/auth.test.ts
    D->>CC: y (允许)
    CC->>F: 写入测试文件
    CC->>D: 请求权限：运行 npm test
    D->>CC: y (允许)
    CC->>F: 执行测试命令
    F-->>CC: 5/5 测试通过
    CC->>D: 完成！所有测试通过

    D->>CC: "提交代码"
    CC->>G: git add + git commit
    G-->>CC: 提交成功

    D->>CC: /cost
    CC->>D: 本次会话消耗 15K tokens
    D->>CC: /exit

mkdir ~/todo-cli && cd ~/todo-cli
npm init -y
git init
claude

> 请创建一个Node.js CLI待办事项工具，要求：
> 1. 使用TypeScript
> 2. 命令格式：todo add "买牛奶"、todo list、todo done 1、todo delete 1
> 3. 数据存储在 ~/.todo.json
> 4. 支持彩色终端输出
> 5. 安装所有依赖并确保可以运行

todo add "学习Claude Code"
todo add "写一篇教程"
todo list
# 输出：
# 1. ☐ 学习Claude Code
# 2. ☐ 写一篇教程

todo done 1
todo list
# 输出：
# 1. ✅ 学习Claude Code
# 2. ☐ 写一篇教程