Claude Code对话式开发入门：从安装到首项目交付

需求 → 分析 → 设计算法 → 编写代码 → 调试 → 测试

需求 → 用自然语言描述给 Claude → 审查结果 → 迭代优化

flowchart LR
    A[你的意图] -->|自然语言| B[Claude Code]
    B -->|读取| C[项目文件]
    B -->|执行| D[终端命令]
    B -->|生成| E[代码输出]
    E -->|审查| F{满意?}
    F -->|否| A
    F -->|是| G[提交代码]

    style A fill:#4A90D9,color:#fff
    style B fill:#D97706,color:#fff
    style G fill:#059669,color:#fff

# macOS / Linux
curl -fsSL https://claude.ai/install.sh | sh

# Windows（PowerShell 管理员模式）
irm https://claude.ai/install.ps1 | iex

brew install claude-code

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

claude --version
# 预期输出：Claude Code v2.1.x 或更高版本

claude
# 首次启动会打开浏览器，登录 Anthropic 账户
# 免费 Plan：$5 免费额度
# Pro Plan：$20/月，更高额度
# Max Plan：$100-200/月，最高额度和模型访问

export ANTHROPIC_API_KEY="sk-ant-xxxxx"
claude
# 直接使用 API Key 认证，按 token 计费

cd ~/projects        # 进入你的项目目录（或任何空目录）
claude               # 启动交互式会话

> 你好，请帮我看看当前目录下有什么文件

我来查看当前目录的内容。

[Bash] ls -la /home/user/projects

输出：
total 8
drwxr-xr-x  2 user user 4096 May 26 10:00 .
drwxr-xr-x 18 user user 4096 May 25 09:30 ..

当前目录是空的。你想要创建什么项目？

Claude wants to read file: package.json
[Allow / Deny / Always allow for this project]

flowchart TD
    A[选择模型] --> B{任务复杂度?}
    B -->|简单查询/快速修改| C[Haiku<br/>最快最便宜]
    B -->|日常开发/中等任务| D[Sonnet<br/>速度与质量平衡]
    B -->|架构设计/复杂重构| E[Opus<br/>最强推理能力]

    style C fill:#059669,color:#fff
    style D fill:#D97706,color:#fff
    style E fill:#7C3AED,color:#fff

> 请看看 src/index.js 的内容

> 请创建一个 README.md，内容是项目说明

> 运行 npm test 看看测试是否通过

> 项目里有哪些 TypeScript 文件？

> 哪些文件引用了 express 模块？

flowchart TB
    subgraph "Claude Code 五大工具"
        A[Read<br/>读取文件内容]
        B[Write/Edit<br/>创建/修改文件]
        C[Bash<br/>执行终端命令]
        D[Glob<br/>按模式搜索文件名]
        E[Grep<br/>按内容搜索文件]
    end

    subgraph "你的项目"
        F[源代码文件]
        G[配置文件]
        H[测试文件]
        I[终端/Shell]
    end

    A --> F
    A --> G
    B --> F
    B --> G
    B --> H
    C --> I
    D --> F
    E --> F

    style A fill:#4A90D9,color:#fff
    style B fill:#059669,color:#fff
    style C fill:#D97706,color:#fff
    style D fill:#7C3AED,color:#fff
    style E fill:#DC2626,color:#fff

flowchart BT
    A["~/.claude/CLAUDE.md<br/>全局规则<br/>所有项目生效"] --> B["项目根/CLAUDE.md<br/>项目级规则<br/>团队共享"]
    B --> C["项目根/.claude/CLAUDE.md<br/>同上，放 .claude 目录"]
    C --> D["子目录/CLAUDE.md<br/>模块级规则"]
    D --> E["~/.claude/CLAUDE.local.md<br/>个人本地规则<br/>不提交到 Git"]

    style A fill:#DC2626,color:#fff
    style B fill:#D97706,color:#fff
    style C fill:#D97706,color:#fff
    style D fill:#4A90D9,color:#fff
    style E fill:#059669,color:#fff

# 项目说明
这是一个 [项目名称]，使用 [技术栈]。

# 开发规则
- 使用 TypeScript strict 模式
- 代码注释使用英文
- 提交信息格式：feat/fix/docs: 简短描述

# 常用命令
- 启动开发：npm run dev
- 运行测试：npm test
- 构建项目：npm run build

# 注意事项
- 不要修改 .env 文件
- 测试覆盖率不低于 80%

> 请描述一下当前项目的规则和约束

mkdir quicknote && cd quicknote
git init
claude

> 我想创建一个命令行笔记工具 quicknote。使用 Node.js 和 TypeScript。
> 功能包括：add、list、search、delete 四个子命令。
> 笔记存储在 ~/.quicknote/notes.json，每条笔记有 id、内容、创建时间。
> 请帮我初始化项目结构，创建 package.json 和 tsconfig.json。

> 请实现 quicknote 的核心功能。入口文件是 src/index.ts。
> 使用 commander 库处理命令行参数，用 chalk 给输出加颜色。

quicknote/
├── src/
│   ├── index.ts        # 入口，命令行解析
│   ├── store.ts        # 数据存储层
│   └── types.ts        # 类型定义
├── package.json
├── tsconfig.json
└── CLAUDE.md

export interface Note {
  id: number;
  content: string;
  createdAt: string;
}

import * as fs from 'fs';
import * as path from 'path';
import { Note } from './types';

const NOTES_DIR = path.join(process.env.HOME || '~', '.quicknote');
const NOTES_FILE = path.join(NOTES_DIR, 'notes.json');

function ensureFile(): void {
  if (!fs.existsSync(NOTES_DIR)) {
    fs.mkdirSync(NOTES_DIR, { recursive: true });
  }
  if (!fs.existsSync(NOTES_FILE)) {
    fs.writeFileSync(NOTES_FILE, JSON.stringify([], null, 2));
  }
}

export function loadNotes(): Note[] {
  ensureFile();
  const data = fs.readFileSync(NOTES_FILE, 'utf-8');
  return JSON.parse(data);
}

export function saveNotes(notes: Note[]): void {
  ensureFile();
  fs.writeFileSync(NOTES_FILE, JSON.stringify(notes, null, 2));
}

export function addNote(content: string): Note {
  const notes = loadNotes();
  const note: Note = {
    id: notes.length > 0 ? Math.max(...notes.map(n => n.id)) + 1 : 1,
    content,
    createdAt: new Date().toISOString(),
  };
  notes.push(note);
  saveNotes(notes);
  return note;
}

export function searchNotes(keyword: string): Note[] {
  return loadNotes().filter(n =>
    n.content.toLowerCase().includes(keyword.toLowerCase())
  );
}

export function deleteNote(id: number): boolean {
  const notes = loadNotes();
  const index = notes.findIndex(n => n.id === id);
  if (index === -1) return false;
  notes.splice(index, 1);
  saveNotes(notes);
  return true;
}

#!/usr/bin/env node
import { Command } from 'commander';
import chalk from 'chalk';
import { addNote, loadNotes, searchNotes, deleteNote } from './store';

const program = new Command();

program
  .name('quicknote')
  .description('一个简单的命令行笔记工具')
  .version('1.0.0');

program
  .command('add <content>')
  .description('添加一条笔记')
  .action((content: string) => {
    const note = addNote(content);
    console.log(chalk.green(`✓ 笔记已添加 [${note.id}] ${note.content}`));
  });

program
  .command('list')
  .description('列出所有笔记')
  .action(() => {
    const notes = loadNotes();
    if (notes.length === 0) {
      console.log(chalk.yellow('暂无笔记'));
      return;
    }
    notes.forEach(note => {
      const time = new Date(note.createdAt).toLocaleString('zh-CN');
      console.log(
        chalk.blue(`[${note.id}]`) + ` ${note.content} ` +
        chalk.gray(time)
      );
    });
  });

program
  .command('search <keyword>')
  .description('搜索笔记')
  .action((keyword: string) => {
    const results = searchNotes(keyword);
    if (results.length === 0) {
      console.log(chalk.yellow(`未找到包含 "${keyword}" 的笔记`));
      return;
    }
    results.forEach(note => {
      console.log(chalk.blue(`[${note.id}]`) + ` ${note.content}`);
    });
  });

program
  .command('delete <id>')
  .description('删除指定ID的笔记')
  .action((id: string) => {
    const success = deleteNote(parseInt(id, 10));
    if (success) {
      console.log(chalk.green(`✓ 笔记 [${id}] 已删除`));
    } else {
      console.log(chalk.red(`✗ 未找到笔记 [${id}]`));
    }
  });

program.parse();

> 请更新 package.json，添加 bin 字段和 build 脚本，
> 然后运行 npm run build 验证编译通过。

{
  "name": "quicknote",
  "version": "1.0.0",
  "bin": {
    "quicknote": "./dist/index.js"
  },
  "scripts": {
    "build": "tsc",
    "dev": "ts-node src/index.ts"
  },
  "dependencies": {
    "commander": "^12.0.0",
    "chalk": "^5.3.0"
  },
  "devDependencies": {
    "typescript": "^5.4.0",
    "@types/node": "^20.0.0",
    "ts-node": "^10.9.0"
  }
}

> 请用 npm link 安装到全局，然后运行 quicknote add "我的第一条笔记" 测试功能。
> 接着运行 quicknote list 确认笔记已保存。

✓ 笔记已添加 [1] 我的第一条笔记

[1] 我的第一条笔记 2026/5/26 14:30:00

> 请为 store.ts 添加单元测试。使用 vitest 框架。
> 测试覆盖：添加笔记、列出笔记、搜索笔记、删除笔记四个场景。

import { describe, it, expect, beforeEach, afterEach } from 'vitest';
import * as fs from 'fs';
import * as path from 'path';
import { addNote, loadNotes, searchNotes, deleteNote } from '../store';

const NOTES_FILE = path.join(
  process.env.HOME || '~', '.quicknote', 'notes.json'
);

describe('Store', () => {
  beforeEach(() => {
    if (fs.existsSync(NOTES_FILE)) {
      fs.unlinkSync(NOTES_FILE);
    }
  });

  it('should add a note', () => {
    const note = addNote('测试笔记');
    expect(note.id).toBe(1);
    expect(note.content).toBe('测试笔记');
    expect(note.createdAt).toBeDefined();
  });

  it('should list all notes', () => {
    addNote('笔记A');
    addNote('笔记B');
    const notes = loadNotes();
    expect(notes).toHaveLength(2);
  });

  it('should search notes by keyword', () => {
    addNote('学习 TypeScript');
    addNote('学习 React');
    addNote('做饭');
    const results = searchNotes('学习');
    expect(results).toHaveLength(2);
  });

  it('should delete a note by id', () => {
    addNote('待删除');
    addNote('保留');
    const deleted = deleteNote(1);
    expect(deleted).toBe(true);
    expect(loadNotes()).toHaveLength(1);
  });

  it('should return false for non-existent id', () => {
    const deleted = deleteNote(999);
    expect(deleted).toBe(false);
  });
});

> 请运行测试，确保全部通过。如果失败请修复。

> npm test

 ✓ src/__tests__/store.test.ts (5)
   ✓ Store > should add a note
   ✓ Store > should list all notes
   ✓ Store > should search notes by keyword
   ✓ Store > should delete a note by id
   ✓ Store > should return false for non-existent id

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

flowchart TD
    A["1. mkdir quicknote && cd quicknote"] --> B["2. git init"]
    B --> C["3. claude 启动会话"]
    C --> D["4. 描述需求：初始化项目"]
    D --> E["5. Claude 创建 package.json"]
    E --> F["6. 描述需求：实现核心功能"]
    F --> G["7. Claude 编写 store.ts + index.ts"]
    G --> H["8. 描述需求：添加测试"]
    H --> I["9. Claude 创建 store.test.ts"]
    I --> J["10. npm test 验证"]
    J --> K{测试通过?}
    K -->|是| L["11. npm link 全局安装"]
    K -->|否| M["12. 让 Claude 修复"]
    M --> J
    L --> N["13. 实际测试 quicknote 命令"]
    N --> O["✓ 项目交付完成"]

    style C fill:#D97706,color:#fff
    style O fill:#059669,color:#fff

# 继续最近的会话
claude --continue

# 恢复指定会话
claude --resume abc123

# 查看历史会话
claude --sessions

Context window usage: 85%. Consider using /compact.

# 查询式使用
claude -p "这个项目的依赖有哪些"

# 管道输入
cat error.log | claude -p "分析这个错误日志的原因"

# 不好
> 优化一下代码

# 好的
> 请把 src/utils.ts 中的 formatDate 函数重构为纯函数，
> 去除对全局变量 timezone 的依赖，改为参数传入。

# 不好
> 帮我实现用户注册、登录、权限管理、个人资料编辑全部功能

# 好的
> 先实现用户注册功能，包含表单验证和密码加密

git add -A && git commit -m "feat: 添加笔记存储功能"

> 请进入 Plan 模式，分析重构数据库层的方案，不要直接修改代码

> 请看看 @src/store.ts 的 addNote 函数，有一个边界条件没有处理

sequenceDiagram
    participant Dev as 开发者
    participant CC as Claude Code
    participant Git as Git 仓库
    participant FS as 文件系统

    Dev->>CC: 描述功能需求
    CC->>FS: 读取相关文件
    CC->>CC: 规划实现方案
    CC->>Dev: 展示计划（Plan 模式）
    Dev->>CC: 确认方案
    CC->>FS: 创建/修改文件
    CC->>Dev: 展示改动
    Dev->>CC: 运行测试
    CC->>FS: npm test
    CC->>Dev: 测试结果
    Dev->>Git: git commit
    Dev->>CC: 下一个需求...