Claude Code 零基础入门：从安装到第一个项目

# macOS（推荐 Homebrew）
brew install node@20

# Linux / WSL2（推荐 nvm）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
source ~/.bashrc
nvm install 20
nvm use 20

# 验证
node --version   # 应显示 v20.x.x
npm --version    # 应显示 10.x.x

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

added 1 package in 12s
1 package is looking for funding

claude --version
# 输出示例：2.1.56

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

# 重新安装
npm install -g @anthropic-ai/claude-code

claude auth login

✓ Authentication successful. Logged in as [email protected]

# 临时设置（仅当前终端会话有效）
export ANTHROPIC_API_KEY="sk-ant-xxxxx"

# 永久设置（写入 shell 配置文件）
echo 'export ANTHROPIC_API_KEY="sk-ant-xxxxx"' >> ~/.bashrc
source ~/.bashrc

claude -p "你好，请用一句话介绍你自己"

# 进入项目目录
mkdir ~/my-todo-app && cd ~/my-todo-app

# 启动 Claude Code
claude

# 单次提问
claude -p "解释当前目录的 package.json 中的依赖关系"

# 管道输入
cat src/app.ts | claude -p "为这个文件添加单元测试"

# 指定输出格式
claude -p "列出 src/ 下所有文件" --output-format json

# 设置费用上限
claude -p "重构这个函数" --max-budget-usd 0.50

flowchart TD
    A[启动 claude] --> B{选择模式}
    B -->|交互式| C[REPL 界面]
    B -->|管道式| D["claude -p 命令"]

    C --> E[描述需求]
    E --> F[Claude 分析代码]
    F --> G[读取文件/执行命令]
    G --> H[生成代码修改]
    H --> I{用户确认}
    I -->|接受| J[变更生效]
    I -->|拒绝| K[调整需求]
    K --> E

    D --> L[输出结果到 stdout]

    J --> M["/compact 压缩上下文"]
    M --> E

    style A fill:#e1f5fe
    style J fill:#c8e6c9
    style I fill:#fff9c4

cd ~/my-todo-app
claude

/init

# Todo App

## 技术栈
- 语言：TypeScript
- 运行时：Node.js 20
- 测试：Vitest
- 无框架，纯 Node.js 实现

## 项目结构
- src/index.ts — 主入口
- src/todo.ts — Todo 核心逻辑
- src/storage.ts — 存储层
- tests/ — 测试文件

## 编码规范
- TypeScript strict 模式
- 函数式风格优先
- 所有公共函数必须有 JSDoc 注释
- 错误处理：throw Error，不返回 null

## 常用命令
- `npm run dev` — 启动开发模式
- `npm test` — 运行测试
- `npm run build` — 编译 TypeScript

mkdir -p .claude

{
  "permissions": {
    "allow": [
      "Bash(git:*)",
      "Bash(npm:*)",
      "Bash(node:*)",
      "Bash(npx:*)",
      "Bash(ls:*)",
      "Bash(cat:*)",
      "Bash(mkdir:*)",
      "Read",
      "Glob",
      "Grep"
    ],
    "deny": [
      "Bash(rm -rf:*)",
      "Bash(git push --force:*)"
    ]
  }
}

flowchart BT
    A["~/.claude/settings.json<br/>（用户全局配置）"] --> B[".claude/settings.json<br/>（项目共享配置，提交到 Git）"]
    B --> C[".claude/settings.local.json<br/>（项目本地配置，不提交 Git）"]

    style C fill:#c8e6c9
    style B fill:#fff9c4
    style A fill:#e1f5fe

帮我初始化一个 TypeScript + Node.js 项目，使用 Vitest 作为测试框架。
项目名为 todo-app，需要包含 package.json、tsconfig.json、vitest.config.ts。

创建 src/todo.ts，实现 Todo 类，需要支持以下功能：
1. 添加任务（add）—— 参数：title (string)，返回 TodoItem
2. 完成任务（complete）—— 参数：id (number)，返回 boolean
3. 删除任务（remove）—— 参数：id (number)，返回 boolean  
4. 列出所有任务（list）—— 返回 TodoItem[]
5. 按状态筛选（filter）—— 参数：completed (boolean)，返回 TodoItem[]

TodoItem 接口：{ id: number, title: string, completed: boolean, createdAt: Date }
每个方法需要 JSDoc 注释。

创建 src/storage.ts，实现 JsonStorage 类：
- 构造函数接收文件路径（默认 ./data/todos.json）
- save(items: TodoItem[]): void —— 写入 JSON 文件
- load(): TodoItem[] —— 读取 JSON 文件，文件不存在返回空数组
- 使用 fs/promises 进行异步文件操作

创建 src/index.ts，实现命令行交互界面：
- 使用 readline/promises 读取用户输入
- 支持命令：add <title>, done <id>, rm <id>, list, filter <done|pending>, quit
- 启动时从存储加载已有任务
- 每次操作后自动保存
- 优雅的错误处理和退出

为 src/todo.ts 编写完整的单元测试，放在 tests/todo.test.ts 中。
测试用例需要覆盖：
- 添加任务
- 完成任务（正常和 id 不存在的情况）
- 删除任务（正常和 id 不存在的情况）
- 列出所有任务
- 按状态筛选
- 自增 ID 的正确性

import { describe, it, expect } from 'vitest';
import { Todo } from '../src/todo';

describe('Todo', () => {
  let todo: Todo;

  beforeEach(() => {
    todo = new Todo();
  });

  it('should add a task', () => {
    const item = todo.add('Learn Claude Code');
    expect(item.id).toBe(1);
    expect(item.title).toBe('Learn Claude Code');
    expect(item.completed).toBe(false);
  });

  it('should auto-increment IDs', () => {
    todo.add('Task 1');
    todo.add('Task 2');
    const items = todo.list();
    expect(items).toHaveLength(2);
    expect(items[1].id).toBe(2);
  });

  it('should complete a task', () => {
    todo.add('Task 1');
    const result = todo.complete(1);
    expect(result).toBe(true);
    expect(todo.list()[0].completed).toBe(true);
  });

  it('should return false for non-existent id on complete', () => {
    const result = todo.complete(999);
    expect(result).toBe(false);
  });

  it('should remove a task', () => {
    todo.add('Task 1');
    const result = todo.remove(1);
    expect(result).toBe(true);
    expect(todo.list()).toHaveLength(0);
  });

  it('should filter by status', () => {
    todo.add('Task 1');
    todo.add('Task 2');
    todo.complete(1);
    const completed = todo.filter(true);
    const pending = todo.filter(false);
    expect(completed).toHaveLength(1);
    expect(pending).toHaveLength(1);
  });
});

运行测试，确保全部通过

 ✓ tests/todo.test.ts (6 tests) 12ms
   ✓ Todo > should add a task
   ✓ Todo > should auto-increment IDs
   ✓ Todo > should complete a task
   ✓ Todo > return false for non-existent id
   ✓ Todo > remove a task
   ✓ Todo > filter by status

 Test Files  1 passed (1)
 Tests       6 passed (6)

编译并运行应用，测试添加几个任务

npm run build    # 编译 TypeScript
node dist/index.js

flowchart LR
    A[对话开始] --> B[上下文逐渐增长]
    B --> C{接近上限?}
    C -->|否| B
    C -->|是| D["/compact 压缩"]
    D --> E[保留关键信息]
    E --> F[释放 token 空间]
    F --> B

    G[".claudeignore"] -.->|排除无关文件| B
    H["CLAUDE.md"] -.->|提供持久上下文| B
    I["Memory 系统"] -.->|跨会话记忆| B

    style D fill:#fff9c4
    style G fill:#ffcdd2
    style H fill:#c8e6c9
    style I fill:#e1bee7

node_modules/
dist/
*.min.js
*.map
package-lock.json
data/

# ❌ 模糊
帮我修复 bug

# ✅ 精准
@src/todo.ts 第 42 行的 complete 方法有个 bug：
当 id 不存在时应该抛出错误而不是返回 false。请修复。

# 交互模式中
/model opus

# 非交互模式
claude -p "解释这段代码" --model haiku

# 交互模式中查看当前会话费用
/cost

# 非交互模式设置费用上限
claude -p "重构这个函数" --max-budget-usd 1.00

{
  "permissions": {
    "allow": [
      "Bash(git status:*)",       // 允许 git status 的任何参数
      "Bash(npm test:*)",          // 允许 npm test 的任何参数
      "Bash(npm run lint:*)",      // 允许 npm run lint 的任何参数
      "Read",                      // 允许读取任何文件
      "Glob",                      // 允许文件模式匹配
      "Grep"                       // 允许内容搜索
    ],
    "deny": [
      "Bash(rm -rf:*)",            // 禁止 rm -rf
      "Bash(git push --force:*)",  // 禁止强制推送
      "Bash(git reset --hard:*)"   // 禁止硬重置
    ]
  }
}

flowchart TD
    subgraph 准备阶段
        A[安装 Claude Code] --> B[认证登录]
        B --> C[创建项目目录]
        C --> D["运行 /init 生成 CLAUDE.md"]
    end

    subgraph 开发阶段
        D --> E[描述需求]
        E --> F[Claude 读取项目文件]
        F --> G[Claude 生成代码方案]
        G --> H{审查方案}
        H -->|确认| I[代码写入文件]
        H -->|修改需求| E
        I --> J[运行测试验证]
        J --> K{测试通过?}
        K -->|是| L[继续下一个功能]
        K -->|否| M[让 Claude 修复]
        M --> J
        L --> E
    end

    subgraph 维护阶段
        L --> N["/compact 压缩上下文"]
        N --> O["/cost 检查费用"]
        O --> P[提交 Git]
        P --> Q[下一个任务]
    end

    style A fill:#e1f5fe
    style I fill:#c8e6c9
    style K fill:#fff9c4
    style M fill:#ffcdd2