Claude Code新手实操：从安装避坑到首个项目交付

# 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

# 重新加载 shell
source ~/.bashrc  # 或 ~/.zshrc

# 安装 Node.js 20 LTS
nvm install 20
nvm use 20

# 验证
node --version  # 应输出 v20.x.x
npm --version   # 应输出 10.x.x

git --version   # 应输出 git version 2.3x+

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

claude --version
# 输出示例：1.0.x

claude

# 设置 API Key
export ANTHROPIC_API_KEY="sk-ant-api03-xxxxxxxxxxxxx"

# 建议写入 shell 配置文件
echo 'export ANTHROPIC_API_KEY="sk-ant-api03-xxxxxxxxxxxxx"' >> ~/.bashrc
source ~/.bashrc

export ANTHROPIC_BASE_URL="https://your-proxy-endpoint.com/v1"
export ANTHROPIC_API_KEY="your-key"

graph TD
    A[启动 Claude Code] --> B{选择权限模式}
    B -->|默认| C[交互确认模式]
    B -->|--dangerously-skip-permissions| D[自动执行模式]
    B -->|--allowedTools| E[白名单模式]

    C --> F{操作类型}
    F -->|读取文件| G[自动允许]
    F -->|写入文件| H[弹窗确认]
    F -->|执行命令| I[弹窗确认]

    D --> J[所有操作自动执行<br/>⚠️ 仅限受信环境]
    E --> K[仅白名单操作自动执行]

{
  "permissions": {
    "allow": [
      "Bash(npm test)",
      "Bash(git status)",
      "Bash(git diff *)",
      "Read(*)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(curl * | bash)"
    ]
  }
}

graph LR
    A["~/.claude/CLAUDE.md<br/>全局配置"] --> B["项目根目录/CLAUDE.md<br/>项目配置"]
    B --> C["子目录/CLAUDE.md<br/>模块配置"]

    style A fill:#e1f5fe
    style B fill:#fff3e0
    style C fill:#e8f5e9

mkdir -p my-first-project && cd my-first-project
git init

# CLAUDE.md

## 项目概述
一个用 Node.js 编写的命令行 TODO 管理工具。

## 技术栈
- 运行时：Node.js 20 LTS
- 语言：JavaScript（ES Module）
- 测试：Vitest
- 无外部依赖

## 常用命令
- 运行：`node src/index.js`
- 测试：`npx vitest`
- 代码风格检查：无（项目简单）

## 项目结构
- `src/index.js` — 入口文件
- `src/todo.js` — TODO 核心逻辑
- `src/storage.js` — 数据持久化
- `tests/` — 测试文件

## 编码规范
- 使用 ES Module（import/export）
- 函数使用驼峰命名
- 优先使用 const，避免 var
- 每个函数不超过 20 行

## 注意事项
- 不要安装额外的 npm 包
- 数据存储在项目根目录的 `.todos.json` 文件中
- 所有用户交互通过 console.log/console readline

claude
> /init

# 非交互模式：执行单个提示词
claude -p "解释这个项目的结构"

# 管道模式：结合 Unix 管道使用
cat error.log | claude -p "分析这段错误日志"

# 指定模型
claude --model sonnet

# 继续上次会话
claude --continue

# 恢复最近一次会话
claude --resume

# 创建项目目录
mkdir -p todo-cli && cd todo-cli
git init

# 创建 package.json
cat > package.json << 'EOF'
{
  "name": "todo-cli",
  "version": "1.0.0",
  "type": "module",
  "main": "src/index.js",
  "scripts": {
    "start": "node src/index.js",
    "test": "npx vitest run"
  }
}
EOF

claude

请帮我创建一个命令行 TODO 管理工具。要求：
1. 支持添加、列出、完成、删除 TODO 项
2. 数据持久化到 .todos.json 文件
3. 使用 ES Module 语法
4. 不使用任何第三方依赖
5. 每个操作有清晰的命令行输出

todo-cli/
├── CLAUDE.md
├── package.json
├── src/
│   ├── index.js      # 入口：解析命令行参数
│   ├── todo.js       # 核心：TODO 增删改查
│   └── storage.js    # 持久化：读写 JSON 文件
├── tests/
│   ├── todo.test.js
│   └── storage.test.js
└── .todos.json       # 运行时生成

import { readFile, writeFile } from 'fs/promises';
import { existsSync } from 'fs';

const FILE_PATH = '.todos.json';

export async function loadTodos() {
  if (!existsSync(FILE_PATH)) {
    return [];
  }
  const data = await readFile(FILE_PATH, 'utf-8');
  return JSON.parse(data);
}

export async function saveTodos(todos) {
  await writeFile(FILE_PATH, JSON.stringify(todos, null, 2), 'utf-8');
}

import { loadTodos, saveTodos } from './storage.js';

export async function addTodo(text) {
  const todos = await loadTodos();
  const newTodo = {
    id: Date.now(),
    text,
    done: false,
    createdAt: new Date().toISOString()
  };
  todos.push(newTodo);
  await saveTodos(todos);
  console.log(`✅ 已添加: ${text} (ID: ${newTodo.id})`);
}

export async function listTodos() {
  const todos = await loadTodos();
  if (todos.length === 0) {
    console.log('📋 暂无 TODO 项');
    return;
  }
  console.log('📋 TODO 列表:');
  todos.forEach(t => {
    const status = t.done ? '✅' : '⬜';
    console.log(`  ${status} [${t.id}] ${t.text}`);
  });
}

export async function completeTodo(id) {
  const todos = await loadTodos();
  const todo = todos.find(t => t.id === Number(id));
  if (!todo) {
    console.log(`❌ 未找到 ID: ${id}`);
    return;
  }
  todo.done = true;
  await saveTodos(todos);
  console.log(`🎉 已完成: ${todo.text}`);
}

export async function deleteTodo(id) {
  const todos = await loadTodos();
  const index = todos.findIndex(t => t.id === Number(id));
  if (index === -1) {
    console.log(`❌ 未找到 ID: ${id}`);
    return;
  }
  const removed = todos.splice(index, 1)[0];
  await saveTodos(todos);
  console.log(`🗑️ 已删除: ${removed.text}`);
}

import { addTodo, listTodos, completeTodo, deleteTodo } from './todo.js';

const [,, command, ...args] = process.argv;

async function main() {
  switch (command) {
    case 'add':
      if (!args.length) {
        console.log('用法: node src/index.js add <待办事项>');
        break;
      }
      await addTodo(args.join(' '));
      break;
    case 'list':
      await listTodos();
      break;
    case 'done':
      await completeTodo(args[0]);
      break;
    case 'delete':
      await deleteTodo(args[0]);
      break;
    default:
      console.log('用法: node src/index.js <add|list|done|delete> [参数]');
  }
}

main().catch(console.error);

# 添加 TODO
node src/index.js add "学习 Claude Code 安装"
# 输出：✅ 已添加: 学习 Claude Code 安装 (ID: 1748600000000)

node src/index.js add "完成第一个项目"
node src/index.js add "写 CLAUDE.md"

# 列出所有
node src/index.js list
# 📋 TODO 列表:
#   ⬜ [1748600000000] 学习 Claude Code 安装
#   ⬜ [1748600000001] 完成第一个项目
#   ⬜ [1748600000002] 写 CLAUDE.md

# 完成 TODO
node src/index.js done 1748600000000
# 🎉 已完成: 学习 Claude Code 安装

# 删除 TODO
node src/index.js delete 1748600000002
# 🗑️ 已删除: 写 CLAUDE.md

请为 todo.js 和 storage.js 编写 Vitest 单元测试，覆盖所有核心功能。

npx vitest run
# ✓ tests/storage.test.js (3 tests)
# ✓ tests/todo.test.js (5 tests)
#
# Tests  8 passed (8)

graph LR
    A[新会话开始] --> B[阶段任务1]
    B --> C["/compact 压缩"]
    C --> D[阶段任务2]
    D --> E["/compact 压缩"]
    E --> F[阶段任务3]

    style C fill:#fff9c4
    style E fill:#fff9c4

/cost
# Session cost: $0.42 (127K input tokens, 3.2K output tokens)

# ❌ 错误
cd ~ && claude

# ✅ 正确
cd ~/projects/my-app && claude

node_modules/
dist/
.env
.todos.json
*.log

请为 src/auth.js 添加 JWT 认证功能：

需求：
- 登录接口接收用户名和密码
- 验证成功后返回 JWT token
- token 有效期 24 小时
- 包含刷新 token 机制

约束：
- 使用 Node.js 内置 crypto 模块
- 不要引入额外依赖
- 添加错误处理
- 编写对应的单元测试

@src/index.js 这个文件中的路由配置有问题，
当访问 /api/unknown 时返回 500 而不是 404，
请修复并添加对应的测试。

# 第一轮
请创建一个基本的 Express 服务器，包含健康检查接口

# 第二轮（在 Claude 完成后）
添加用户 CRUD 接口，使用内存数组暂存数据

# 第三轮
将数据存储从内存数组切换到 JSON 文件持久化

# 第四轮
为所有接口编写集成测试

flowchart TB
    subgraph 准备阶段
        A[安装 Node.js + npm] --> B[npm install -g @anthropic-ai/claude-code]
        B --> C[配置认证：API Key 或 OAuth]
    end

    subgraph 项目初始化
        C --> D[cd my-project && git init]
        D --> E[claude 启动]
        E --> F["/init 生成 CLAUDE.md"]
        F --> G[审查并修改 CLAUDE.md]
    end

    subgraph 开发循环
        G --> H[描述需求]
        H --> I{Claude 生成方案}
        I --> J[审查方案]
        J -->|不满意| K[调整提示词]
        K --> H
        J -->|满意| L[确认代码变更]
        L --> M[运行测试验证]
        M -->|测试失败| N[告诉 Claude 修复]
        N --> H
        M -->|测试通过| O["/compact 压缩上下文"]
        O --> P{还有新任务?}
        P -->|有| H
        P -->|无| Q["/cost 检查消耗"]
    end

    subgraph 收尾
        Q --> R[git commit 提交]
        R --> S[Ctrl+D 退出]
    end

    style A fill:#e3f2fd
    style F fill:#fff3e0
    style O fill:#e8f5e9
    style R fill:#fce4ec

# 原因：npm 全局目录权限不足
# 解法：使用 nvm 管理 Node.js，避免 sudo
nvm install 20
npm install -g @anthropic-ai/claude-code

# 检查网络连接
curl -I https://api.anthropic.com

# 如果在国内，需要配置代理
export HTTPS_PROXY=http://your-proxy:port

# 或使用国内 API 代理服务
export ANTHROPIC_BASE_URL=https://your-proxy.com/v1

# 1. 确认 CLI 可用
claude --version

# 2. 重新安装扩展
# VS Code → 扩展 → 搜索 Claude Code → 卸载 → 重装

# 3. 检查输出面板
# 查看 → 输出 → 选择 Claude Code 查看日志

graph TD
    A[✅ 本文：入门安装与首个项目] --> B[Skill 开发实战]
    A --> C[CLAUDE.md 六层配置]
    A --> D[Token 成本优化]
    B --> E[MCP 服务器开发]
    C --> F[多 Agent 并行编排]
    D --> G[CI/CD 自动化集成]
    E --> H[企业级工具链构建]