<!-- title: 零基础装通Claude Code造文件整理器 -->

# 零基础装通 Claude Code：30 分钟造出你的第一个文件整理助手

## 概述

本教程面向**从未用过任何 AI 编程工具**的零基础读者。你将从安装、登录、配置一路走到亲手交付一个真正能跑的命令行项目——一个**文件整理助手**：输入一条命令，它自动把凌乱文件夹里的图片、文档、视频、压缩包按类型归位到对应子目录，并打印一份整理报告。学完你将掌握 Claude Code 的安装、认证、会话、Plan 模式、CLAUDE.md 项目记忆，以及"给需求 → 审计划 → 改代码 → 跑验证"的完整迭代闭环。预计耗时 30 分钟。

## 前置条件

你不需要任何编程经验，但需要先备齐这几样东西：

| 项目 | 说明 | 检查方式 |
|------|------|----------|
| 终端 | macOS 终端、Linux 终端、或 Windows 下的 WSL(Ubuntu) | 打开能输入命令的窗口即可 |
| 代码编辑器 | 推荐VS Code，可实时看文件变化 | 非必需，但强烈建议 |
| Claude 账号 | Pro / Max / Team / Enterprise 订阅，或 Console 账号，或 API Key | 登录 claude.ai 查看订阅状态 |
| 网络 | 安装与首次认证需要联网 | 能访问 claude.ai |
| Git（建议） | 作为"撤销"安全网，开始前先 `git init` | `git --version` |

> 没有订阅？Claude Code 也支持用 API Key 按量计费；Max 套餐（每月 $100–$200）提供更高的速率额度。本教程演示的命令在两种方式下完全一致。

## 第一步：安装 Claude Code（三种方式，任选其一）

Anthropic 官方文档目前**推荐原生安装脚本**（不再强制依赖 npm）。下面三种都来自官方 Quickstart，选你顺手的一种。

### 方式 A：原生安装脚本（官方推荐）

**macOS / Linux / WSL：**

```bash
curl -fsSL https://claude.ai/install.sh | bash
```

**Windows PowerShell：**

```powershell
irm https://claude.ai/install.ps1 | iex
```

**Windows CMD：**

```cmd
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
```

> 若在 CMD 里看到 `The token '&&' is not a valid statement separator`，说明你其实处在 PowerShell 里——切到方式 A 的 PowerShell 那行即可。

### 方式 B：包管理器

```bash
# macOS（已装 Homebrew）
brew install --cask claude-code

# Windows（已装 WinGet）
winget install Anthropic.ClaudeCode
```

### 方式 C：npm 全局安装（经典方式，需 Node.js 18+）

```bash
# 先确认 Node 版本 >= 18
node --version

# 没有 Node？用 nvm 装一份长期支持版
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install --lts

# 安装 Claude Code
npm install -g @anthropic-ai/claude-code
```

**预期结果**：任一方式完成后，终端输入下面命令能看到版本号，即代表安装成功。

```bash
claude --version
# 例如输出：1.0.x (Claude Code)
```

**常见问题与解决：**

| 现象 | 原因 | 解决 |
|------|------|------|
| `command not found: claude` | PATH 没刷新 | 关闭重开终端；或手动把安装目录加入 PATH，再 `source ~/.zshrc` |
| npm 方式报权限错误 `EACCES` | 全局目录无写权限 | 用 `nvm` 管理 Node；或 `sudo` 仅作下策（不推荐） |
| `irm` 命令不识别 | 你其实在 CMD 里 | 用 CMD 那条命令，或改用 WinGet |
| 公司网络拦截 claude.ai | 代理/防火墙 | 配置 `HTTPS_PROXY` 环境变量后再装 |

## 第二步：登录认证

安装好之后第一次运行 `claude`，需要完成身份认证。有两条路：

**路线 1：用浏览器登录（订阅用户最省事）**

```bash
claude
```

回车后会弹出引导，按提示在浏览器里用你的 Claude 账号授权，回到终端即完成登录。也可显式触发：

```bash
claude login
```

**路线 2：用 API Key（无订阅、或想按量计费）**

```bash
# 注意等号两边不要有空格
export ANTHROPIC_API_KEY="sk-ant-你的密钥"
claude
```

> 想把 Key 固化下来？把上面那行 `export` 加进 `~/.zshrc` 或 `~/.bashrc`，再 `source` 一次即可。

**预期结果**：终端出现交互式对话界面，显示当前目录和输入提示符，说明你已成功进入会话。

**自检命令**（装完/改配置后强烈建议跑一次）：

```bash
claude doctor
```

它会体检安装路径、Node 版本、网络连通性、登录状态，有问题会逐条标红告诉你。

**常见问题：**

| 现象 | 解决 |
|------|------|
| 浏览器没自动打开 | 复制终端里那串 URL，手动粘到浏览器 |
| `claude doctor` 报 401 未授权 | Key 失效或额度用尽，去 Console 重新生成 / 续费 |
| 认证成功但提示速率受限 | 个人额度到了上限；升级到 Max 或换 API Key 计费 |

## 第三步：准备项目"安全网"

新手最怕 AI 乱改文件。**开工前先建目录 + 初始化 Git**，这样任何不满意都能一键回退。这是所有高质量教程都强调的第一守则。

```bash
mkdir my-file-organizer && cd my-file-organizer
git init
touch README.md        # 给一个非空起点，Claude Code 工作得更稳
```

**预期结果**：当前目录变成一个 Git 仓库，且不再是空文件夹。

## 第四步：启动会话与基本姿势

在项目目录里启动 Claude Code：

```bash
claude
```

> 一定要从**项目目录内**启动。若在主目录里跑，它读不到你的项目文件。

进入后先熟悉几条核心命令：

| 命令 / 快捷键 | 作用 |
|--------------|------|
| `/help` | 列出全部命令 |
| `/clear` | 清空当前对话上下文（不删文件） |
| `@文件名` | 把某个文件作为上下文喂给它，如 `@README.md` |
| `Shift + Tab` | 切换 **Plan 模式**（只规划、先不动手） |
| `/quit` 或 `Ctrl + C` | 退出会话 |

**Plan 模式是新手的安全起手式**：按 `Shift+Tab` 切到 Plan，再提需求，Claude Code 会先给你一份"我打算怎么做"的计划，你审核通过后才真正写文件。强烈建议第一次操作就开着它。

## 第五步：写 CLAUDE.md——项目记忆文件

这是 Claude Code 从"还行"变"真好用"的关键。在项目根目录建一个 `CLAUDE.md`，写清项目约定，Claude Code 会在每次会话开始自动读取它，省得你反复交代背景。

你可以直接让 Claude Code 帮你建：

```
在项目根目录创建一个 CLAUDE.md，说明这是一个 Node.js 写的命令行文件整理工具，
技术栈：纯 Node.js 标准库、不依赖第三方包；命令用 npm start 运行。
```

它生成的内容大致长这样（你可自行微调）：

```markdown
# 项目：文件整理助手（file-organizer）

一个纯 Node.js 实现的命令行工具，按扩展名把凌乱目录里的文件归类到子文件夹。

## 技术栈
- Node.js 18+，仅用标准库（fs / path），不引入第三方依赖

## 常用命令
- `node organize.js [目录] [--dry-run]` —— 整理指定目录；--dry-run 为预演模式
- `npm start -- ./messy --dry-run` —— 通过 npm 调用

## 规则
- 所有新函数都写注释
- 处理文件时优先考虑安全性：重名自动加序号，绝不覆盖
- 错误信息要中文、可读
```

> 没写够别担心，CLAUDE.md 是"活文档"——用到哪儿发现新约定就往里加，越用越懂你。

## 第六步：用一句话下需求

切到 Plan 模式（`Shift+Tab`），把需求说清楚——**越具体，产出越可用**。"给我写个整理文件的工具"是差提示；下面这种带行为约束的才是好提示：

```
用 Node.js 标准库写一个文件整理脚本 organize.js：
1. 接收一个目标目录（默认当前目录）作为参数；
2. 扫描该目录下的文件（不递归子目录），按扩展名分类：
   图片/文档/视频/音频/压缩包/代码/其他；
3. 把每类文件移动到同名的子文件夹里；
4. 文件名冲突时自动加 _1、_2 序号，绝不覆盖；
5. 最后打印一份"整理报告"，显示每类移动了多少个；
6. 加一个 --dry-run 预演模式，只打印将要做什么、不真正移动文件。
```

**预期结果**：Claude Code 会先列出计划（创建哪些文件、分几个函数、怎么分类）。审一遍没问题，批准后它直接写盘。下面是它产出的完整代码（依赖为零，可直接跑）：

```js
#!/usr/bin/env node
// 文件整理助手 organize.js —— 按扩展名把凌乱目录归类到子文件夹
const fs = require('fs');
const path = require('path');

// 分类规则：分类名 -> 包含的扩展名
const RULES = {
  '图片':   ['.jpg', '.jpeg', '.png', '.gif', '.bmp', '.webp', '.svg'],
  '文档':   ['.pdf', '.doc', '.docx', '.txt', '.md', '.xls', '.xlsx', '.ppt', '.pptx', '.csv'],
  '视频':   ['.mp4', '.mov', '.avi', '.mkv', '.flv'],
  '音频':   ['.mp3', '.wav', '.flac', '.aac', '.m4a'],
  '压缩包': ['.zip', '.rar', '.7z', '.tar', '.gz'],
  '代码':   ['.js', '.ts', '.py', '.java', '.c', '.cpp', '.go', '.rs', '.html', '.css', '.json'],
};

// 扩展名 -> 分类名 的反向索引，O(1) 查表
const EXT_TO_CATEGORY = {};
for (const [cat, exts] of Object.entries(RULES)) {
  for (const e of exts) EXT_TO_CATEGORY[e] = cat;
}

function classify(filename) {
  const ext = path.extname(filename).toLowerCase();
  return EXT_TO_CATEGORY[ext] || '其他';
}

function main() {
  const target = path.resolve(process.argv[2] || '.');      // 第一个参数：目录
  const dryRun = process.argv.includes('--dry-run');          // 预演开关

  if (!fs.existsSync(target) || !fs.statSync(target).isDirectory()) {
    console.error(`✗ 目标不是有效目录: ${target}`);
    process.exit(1);
  }

  console.log(`▶ 整理目录: ${target}  ${dryRun ? '(预演模式，不真正移动)' : ''}\n`);

  const moved = {};            // 分类 -> 移动数量
  const skipped = [];          // 未分类文件名
  const entries = fs.readdirSync(target, { withFileTypes: true });

  for (const ent of entries) {
    if (!ent.isFile()) continue;                              // 跳过子目录
    if (ent.name === path.basename(__filename)) continue;     // 跳过脚本自身

    const category = classify(ent.name);
    if (category === '其他') { skipped.push(ent.name); continue; }

    const destDir = path.join(target, category);
    const src = path.join(target, ent.name);

    moved[category] = (moved[category] || 0) + 1;

    if (dryRun) { console.log(`  [预演] ${ent.name} -> ${category}/`); continue; }

    if (!fs.existsSync(destDir)) fs.mkdirSync(destDir);

    // 重名自动加序号：a.png 存在则改为 a_1.png，再存在则 a_2.png……
    let final = path.join(destDir, ent.name), i = 1;
    while (fs.existsSync(final)) {
      const base = path.basename(ent.name, path.extname(ent.name));
      final = path.join(destDir, `${base}_${i}${path.extname(ent.name)}`);
      i++;
    }
    fs.renameSync(src, final);
    console.log(`  ✓ ${ent.name} -> ${category}/`);
  }

  console.log('\n── 整理报告 ────────────────');
  for (const [cat, n] of Object.entries(moved)) console.log(`  ${cat}: ${n} 个`);
  console.log(`  其他(未分类): ${skipped.length} 个`);
  console.log('────────────────────────────');
}

main();
```

> 别担心记不住这些——你只要把上面那段需求说给 Claude Code，它会替你写出来。贴在这里是为了让你能对照、能读懂、能在它基础上继续改。

## 实战案例：从零跑通文件整理助手

### 1. 造一堆"乱文件"用来测试

```bash
# 回到项目根目录，建一个测试用的凌乱文件夹
mkdir -p messy
cd messy
touch photo.jpg avatar.png report.pdf notes.txt song.mp3 clip.mp4 \
      backup.zip hello.js data.json weirdfile.xyz
cd ..
```

### 2. 先预演，看看会发生什么

```bash
node organize.js ./messy --dry-run
```

**预期输出：**

```
▶ 整理目录: /.../my-file-organizer/messy  (预演模式，不真正移动)

  [预演] photo.jpg -> 图片/
  [预演] avatar.png -> 图片/
  [预演] report.pdf -> 文档/
  [预演] notes.txt -> 文档/
  [预演] song.mp3 -> 音频/
  [预演] clip.mp4 -> 视频/
  [预演] backup.zip -> 压缩包/
  [预演] hello.js -> 代码/
  [预演] data.json -> 代码/

── 整理报告 ────────────────
  图片: 2 个
  文档: 2 个
  音频: 1 个
  视频: 1 个
  压缩包: 1 个
  代码: 2 个
  其他(未分类): 1 个
────────────────────────────
```

注意 `weirdfile.xyz` 因为扩展名不在规则里，被归到"其他"，不会被移动——这正是 `--dry-run` 的价值：**先确认无误，再动手**。

### 3. 真正整理一次

```bash
node organize.js ./messy
```

`messy/` 目录现在变成：

```
messy/
├── 图片/   avatar.png, photo.jpg
├── 文档/   notes.txt, report.pdf
├── 音频/   song.mp3
├── 视频/   clip.mp4
├── 压缩包/ backup.zip
├── 代码/   data.json, hello.js
└── weirdfile.xyz          ← 未分类，原地保留
```

### 4. 让 Claude Code 继续增强（演示迭代闭环）

新手常误以为"一次就要完美"。实际上**迭代才是核心技能**——通常需要 3 到 5 轮跟进。试试这些后续指令，每条都展示一种迭代方向：

```
# 迭代①：新增功能——把每次整理结果写成 manifest.json，支持回滚
给 organize.js 增加一个 manifest.json 记录每次移动的 原路径->新路径，
并加一个 --undo 参数，能根据 manifest.json 把文件移回原位。

# 迭代②：配置外置——分类规则搬到单独文件
把 RULES 抽到 rules.json，启动时读取，方便用户自定义扩展名归属。

# 迭代③：可观测性——加日志
每次移动写入 organize.log，格式：[时间] 文件 -> 目标。

# 迭代④：健壮性——加测试
用 Node 内置的 node:test 给 classify() 和重名加序号逻辑各写一组单测。
```

每次它都会给计划 → 你批准 → 它改代码 → 你 `node --test` 或 `--dry-run` 验证。不满意就用一句话告诉它怎么改，或直接 `git checkout .` 全部回退重来。这就是 Claude Code 的标准工作节奏。

### 工作流程图

```mermaid
flowchart TD
    A[安装 claude<br/>claude --version] --> B[登录认证<br/>claude login / API Key]
    B --> C[建目录 + git init<br/>安全网]
    C --> D[启动 claude<br/>Shift+Tab 进 Plan 模式]
    D --> E[写 CLAUDE.md<br/>项目记忆]
    E --> F[下具体需求<br/>列清行为约束]
    F --> G{审计划}
    G -->|不满意| F
    G -->|满意| H[Claude Code 写文件]
    H --> I[--dry-run 预演<br/>node --test 验证]
    I --> J{通过?}
    J -->|否| K[一句话提改进<br/>继续迭代]
    K --> I
    J -->|是| L[git commit<br/>固化成果]
    L --> M[下一轮需求]
    M --> F
```

## 给零基础者的 7 条避坑清单

1. **先 `git init`，再动手。** Git 是你面对 AI 改文件的唯一"撤销键"。
2. **第一次开 Plan 模式。** 先看计划，再批准动手，避免意外改动。
3. **需求写具体。** "整理文件"是差提示；"按扩展名分 6 类、重名加序号、带预演"才是好提示。
4. **接受 3–5 轮迭代。** 一轮没完美是常态，不是失败。
5. **改完先 `--dry-run`、先跑测试。** 永远在"安全模式"下先验证，再动真格。
6. **维护好 CLAUDE.md。** 把它当团队 wiki，越用越省沟通成本。
7. **别一上来就用 `--dangerously-skip-permissions`。** 那会跳过所有确认，新手时期请保持逐项审批。

## 延伸阅读

- **Claude Code 官方 Quickstart**：最权威的安装与会话指引，本教程安装部分以此为准。
- **官方 Best Practices**：进阶掌握提示、上下文窗口、权限模式的最佳实践。
- **Plan 模式与权限模式文档**：理解只读规划、自动审批、隔离沙箱之间的取舍。
- **CLAUDE.md / 记忆体系文档**：把项目知识固化成 AI 能读取的"团队规范"。
- 做完本课后，建议接着练：给这个工具加 `--undo` 回滚、加 `node:test` 单测、用 Skill 把它封装成一条斜杠命令——这些都是后续中级教程的天然起点。

## 训练营适用性评估

| 维度 | 评估 |
|------|------|
| 适合人群 | 完全零基础、第一次接触 AI 编程工具的学员；转行自学编程者；想快速体验 Claude Code 价值的一线开发者 |
| 训练营类型 | "Claude Code 零基础入门营""AI 编程新手破冰营""办公自动化小工具营" |
| 建议时长 | 引导讲解 15 分钟 + 动手实操 30 分钟 + 迭代挑战 15 分钟，共约 60 分钟一节课 |
| 难度 | ★☆☆☆☆（仅要求会开终端、能照抄命令） |
| 衔接课程 | 可顺接"Skill 开发实战"（把本工具封装为斜杠命令）、"Hooks 实战"（整理前自动备份） |
| 学员成果验收 | 学员能独立装通 Claude Code、跑通整理助手、并完成至少一轮功能迭代（如 manifest 回滚或 rules.json 外置） |

## 参考来源

1. [Claude Code 官方 Quickstart — code.claude.com](https://code.claude.com/docs/en/quickstart) — 安装（原生脚本/Homebrew/WinGet）、登录、首会话、Plan 模式的权威步骤，本教程安装与认证部分以此为准
2. [Claude Code tutorial for beginners — self.md](https://self.md/guides/claude-code-beginners-tutorial/) — Node.js 18+ 与 npm 安装、`claude login`/API Key 双路径、CLAUDE.md 模板的独立教程，补充了认证细节与记忆文件写法
3. [Claude Code for Beginners: Your First Project in 30 Minutes — LOW/CODE](https://www.lowcode.agency/blog/claude-code-first-project-tutorial) — 30 分钟交付首个项目的实操教程，强调 `git init` 安全网、Plan 模式起手、CLAUDE.md 必备、3–5 轮迭代为常态，本教程的迭代闭环与避坑清单大量参考于此
4. [@anthropic-ai/claude-code — npm](https://www.npmjs.com/package/@anthropic-ai/claude-code) — npm 全局安装方式的官方包页面与版本信息

---

> 微信公众号「**字节笔记本**」原创整理 · 专注 Claude Code 与 AI 编程实战，陪你从第一条命令走到第一个上线的工具。

> [!tip] 51学通信知识星球
> **星主：爱卫生**（微信：gprshome201101）——公众号「51学通信」创办者，19 年通信行业运维与讲师经验，著有《GPRS网络信令实例详解》《EPC原理与实践》《5G核心网原理与实践》三本纸质书（各大电商平台有售）。
> **星球定位**：深耕 5G 核心网、IMS、NFV/AI、云原生等 ICT 领域，主打运维岗位与信令分析。
> **当前规模**：5200 篇主题 / 990 个回答，198 元/年。
> **加入福利**：加入星球后请加爱卫生微信，拉您进知识星球年度陪伴与答疑群——不限量回复您的各种问题，另有群内分享。
> **AI 加持**：51学通信知识星球已作为 skill 接入 WorkBuddy，使用 deepseek-4-flash 在海量星球帖子中精准找贴、找视频、找 FAQ 和案例，做总结、找文档和 PPT 等场景全覆盖。

![51学通信知识星球海报-扫码加入](https://wiki.500nian.com/images/zhixingqiu_qrcode.png)