Claude Code三栖环境搭建与首日实战

graph TB
    A[Claude Code] --> B[终端 CLI]
    A --> C[桌面应用<br/>Desktop App]
    A --> D[VS Code 扩展]

    B --> B1[纯键盘操作<br/>适合高级开发者]
    B --> B2[支持 -p 管道模式<br/>适合自动化]
    B --> B3[SSH 远程服务器<br/>无头环境]

    C --> C1[图形界面<br/>适合新手入门]
    C --> C2[无需终端经验<br/>鼠标操作]
    C --> C3[独立运行<br/>不依赖编辑器]

    D --> D1[侧边栏集成<br/>边写边问]
    D --> D2[内嵌终端<br/>图形与命令双模]
    D --> D3[工作区感知<br/>自动读取项目上下文]

    style A fill:#D97706,stroke:#92400E,color:#fff
    style B fill:#2563EB,stroke:#1E40AF,color:#fff
    style C fill:#059669,stroke:#065F46,color:#fff
    style D fill:#7C3AED,stroke:#5B21B6,color:#fff

# macOS / Linux（推荐使用 npm 全局安装）
npm install -g @anthropic-ai/claude-code

# 验证安装
claude --version
# 预期输出类似：1.0.x（版本号随时间更新）

# 方案 A：使用 nvm 管理 Node（推荐）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
source ~/.bashrc
nvm install --lts
nvm use --lts
npm install -g @anthropic-ai/claude-code

# 方案 B：修改 npm 全局路径
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

# 检查当前版本
node --version
# 需要 v18.0.0 或更高

# 使用 nvm 升级
nvm install 20
nvm use 20

# 设置 npm 代理
npm config set proxy http://proxy.company.com:8080
npm config set https-proxy http://proxy.company.com:8080

# 如果有自签名证书
npm config set strict-ssl false  # 仅限内部网络使用

claude login
# 浏览器将自动打开，跳转到 claude.ai 授权页面
# 点击 "Allow" 后终端显示 "Logged in successfully"

# 方法 A：通过环境变量设置
export ANTHROPIC_API_KEY="sk-ant-api03-xxxxx"
# 建议写入 ~/.bashrc 或 ~/.zshrc

# 方法 B：通过交互式登录
claude login --method api-key
# 粘贴你的 API Key

# 企业用户通过 SAML/SSO 认证
claude login --method sso
# 输入你的企业 SSO URL

claude auth status
# 预期输出：
# Logged in as: [email protected]
# Plan: Max 20x
# Token expires: 2026-05-24T08:00:00Z

# macOS（Homebrew Cask）
brew install --cask claude-code

# Linux（AppImage）
wget https://claude.ai/desktop/claude-code-latest.AppImage
chmod +x claude-code-latest.AppImage
./claude-code-latest.AppImage

code --install-extension anthropic.claude-code

{
  "claude-code.enableTelemetry": false,
  "claude-code.model": "sonnet",
  "claude-code.autoCompact": true,
  "claude-code.maxTokens": 8192
}

# 进入你的项目目录
cd ~/projects/my-first-project

# 初始化 Git 仓库（如果还没有）
git init

# 运行 Claude Code 的初始化命令
claude
# 进入交互界面后输入：
/init

# Project: Task Tracker

## Overview
A simple task management CLI tool built with Node.js and TypeScript.

## Tech Stack
- Runtime: Node.js 20+
- Language: TypeScript 5.x
- Package Manager: pnpm
- Testing: Vitest
- Linting: ESLint + Prettier

## Project Structure
- `src/` - Source code
- `src/cli.ts` - CLI entry point
- `src/commands/` - Command handlers
- `src/models/` - Data models
- `tests/` - Test files

## Commands
- Build: `pnpm build`
- Test: `pnpm test`
- Lint: `pnpm lint`
- Run: `pnpm start`

## Conventions
- Use snake_case for file names
- Use camelCase for functions and variables
- Use PascalCase for classes and types
- All functions must have JSDoc comments
- Prefer composition over inheritance
- Error handling: use custom error classes

## Do NOT
- Do not use `any` type
- Do not install new dependencies without asking first
- Do not modify package.json directly

graph BT
    A["企业级<br/>~/.claude/settings.json<br/>(最低优先级)"] --> B["用户级<br/>~/.claude/config.yaml"]
    B --> C["项目级<br/>项目根/.claude/settings.json"]
    C --> D["目录级<br/>子目录/CLAUDE.md"]
    D --> E["会话级<br/>运行时命令<br/>(最高优先级)"]

    style A fill:#9CA3AF,color:#fff
    style B fill:#6B7280,color:#fff
    style C fill:#4B5563,color:#fff
    style D fill:#374151,color:#fff
    style E fill:#D97706,color:#fff

claude
> /model opus
# 当前会话切换到 Opus，适合处理复杂任务

> /model sonnet
# 切回 Sonnet 继续日常编码

# 使用 Opus 处理复杂重构
claude --model opus

# 使用 Haiku 处理批量简单修改
claude --model haiku

# 在 ~/.claude/config.yaml 中设置
# 默认使用 Sonnet（推荐平衡选择）
model: sonnet

# 如果预算充裕且追求质量
# model: opus

首周一律使用 Sonnet → 熟悉后再按需切换
                     ↓
日常编码 = Sonnet（80% 时间）
复杂重构 = Opus（15% 时间）
批量修改 = Haiku（5% 时间）

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

# 初始化项目
git init
pnpm init

# 启动 Claude Code
claude

我需要创建一个 TypeScript CLI 任务管理工具，功能包括：
1. 添加任务（task add "写周报"）
2. 列出所有任务（task list）
3. 标记完成（task done 1）
4. 删除任务（task delete 1）
数据用 JSON 文件存储在 ~/.task-tracker/tasks.json。
请帮我搭建完整的项目结构，包括 package.json、tsconfig.json、源码和测试。

task-tracker/
├── CLAUDE.md              # 项目指令文件
├── package.json
├── tsconfig.json
├── src/
│   ├── cli.ts             # CLI 入口
│   ├── commands/
│   │   ├── add.ts         # 添加任务
│   │   ├── list.ts        # 列出任务
│   │   ├── done.ts        # 标记完成
│   │   └── delete.ts      # 删除任务
│   ├── models/
│   │   └── task.ts        # 任务数据模型
│   └── storage.ts         # JSON 存储管理
└── tests/
    ├── add.test.ts
    └── list.test.ts

很好！现在请：
1. 为所有函数添加错误处理
2. 添加 --priority 选项（high/medium/low）
3. 添加 task list --filter done 命令
4. 运行测试确保一切通过

# 构建项目
pnpm build

# 测试运行
pnpm test

# 实际使用
node dist/cli.js add "学习 Claude Code" --priority high
node dist/cli.js add "写项目文档" --priority medium
node dist/cli.js list
# 预期输出：
# #1 [  ] 🔴 学习 Claude Code
# #2 [  ] 🟡 写项目文档

node dist/cli.js done 1
node dist/cli.js list
# 预期输出：
# #1 [✓] 🔴 学习 Claude Code
# #2 [  ] 🟡 写项目文档

# 指定模型
claude --model opus

# 非交互模式（管道输入）
echo "解释这个函数" | claude -p

# 继续上一次对话
claude --continue

# 恢复特定会话
claude --resume <session-id>

# 设置系统提示词
claude --system-prompt "你是一个专注于安全的代码审查专家"

# 仅计划不执行
claude --plan

# 每完成一个大任务后执行
/compact
# Claude 会压缩历史对话，保留关键信息，减少后续每次请求的 token 消耗

# 格式化代码、添加注释等简单任务
claude --model haiku -p "为 src/ 下所有文件添加 JSDoc 注释"

# 继续上一次对话，而不是重新开始
claude --continue

# 在 ~/.claude/config.yaml 中
maxTokensPerRequest: 4096    # 限制单次输出
contextWindow: 100000         # 限制上下文窗口

# API 用户查看成本
/cost
# 输出类似：
# Session cost: $0.42
# Input tokens: 12,450
# Output tokens: 3,280

# 订阅用户查看用量
/usage
# 显示当前周期已用量和剩余额度

# 环境变量方式（推荐）
export HTTP_PROXY=http://proxy.company.com:8080
export HTTPS_PROXY=http://proxy.company.com:8080

# 或在 ~/.claude/config.yaml 中配置
proxy:
  url: http://proxy.company.com:8080
  noProxy: localhost,127.0.0.1,internal.company.com

# 指定自定义 CA 证书
export NODE_EXTRA_CA_CERTS=/path/to/company-ca.crt
export SSL_CERT_FILE=/path/to/company-ca.crt

api.anthropic.com        # API 调用
cdn.anthropic.com        # 资源下载
claude.ai                # OAuth 认证
sentry.io                # 错误上报（可选）

flowchart LR
    A[启动 Claude Code] --> B{选择界面}
    B -->|日常开发| C[VS Code 扩展]
    B -->|复杂任务| D[终端 CLI]
    B -->|快速提问| E[桌面应用]

    C --> F[/init 初始化项目]
    D --> F
    E --> F

    F --> G[编写 CLAUDE.md]
    G --> H[开始编码任务]

    H --> I{任务复杂度?}
    I -->|简单| J[使用 Sonnet]
    I -->|复杂| K[使用 Opus + /plan]

    J --> L[迭代开发]
    K --> L

    L --> M[/compact 压缩上下文]
    M --> N[/cost 检查成本]
    N --> O{还有任务?}
    O -->|是| H
    O -->|否| P[提交代码]

    style A fill:#D97706,color:#fff
    style B fill:#2563EB,color:#fff
    style I fill:#7C3AED,color:#fff
    style P fill:#059669,color:#fff

# 检查是否全局安装
npm list -g @anthropic-ai/claude-code

# 检查 PATH 是否包含 npm 全局路径
echo $PATH | grep npm
# 如果没有，添加到 ~/.bashrc：
export PATH="$(npm config get prefix)/bin:$PATH"

# 清除旧的认证信息重新登录
claude logout
claude login

# 如果使用 API Key
unset ANTHROPIC_API_KEY  # 先清除环境变量
claude login             # 重新 OAuth 登录

# 1. 检查网络延迟
ping api.anthropic.com

# 2. 降低模型（Opus → Sonnet）
/model sonnet

# 3. 压缩上下文
/compact

# 4. 检查是否超出速率限制
/usage

sequenceDiagram
    participant D as 桌面应用
    participant V as VS Code 扩展
    participant T as 终端 CLI

    Note over D: 上午：项目规划
    D->>D: 描述 API 需求<br/>生成 CLAUDE.md

    Note over V: 下午：编码实现
    V->>V: 在编辑器中<br/>边写代码边问 Claude
    V->>V: 选中代码 → 行内修改
    V->>V: 侧边栏审查生成的代码

    Note over T: 傍晚：自动化测试
    T->>T: claude --model sonnet<br/>运行测试并修复失败
    T->>T: claude -p "检查覆盖率" < pipeline

    Note over V: 晚上：代码审查
    V->>V: /review 全面审查
    V->>V: 确认后 git commit

# 上午：桌面应用中描述需求（图形界面更直观）
# → 自动生成 CLAUDE.md 和项目骨架

# 下午：VS Code 中编码
# → 在编辑器中选中代码，右键 "Ask Claude"
# → Claude 在行内显示修改建议，一键接受

# 傍晚：终端中运行测试
claude --model sonnet --continue
> 运行所有测试并修复失败的用例

# 晚上：提交前的最终审查
claude /review
# → Claude 检查所有变更，提出改进建议