概述

本教程面向零基础读者，目标只有一个：在一个下午之内，用 Claude Code 从零做出一个真正能用、能反复用的命令行小工具——"一键整理杂乱文件夹"。

你会学到的不只是 Python 怎么写，而是完整的 AI 编码工作流：怎样把一个模糊的想法变成一句清楚的指令、怎样让 Claude 先出方案再动手、怎样让它自己跑测试、怎样一步步加功能、以及怎样把成果保存下来。学完这四个小时，你将不再"祈祷 AI 给出好结果"，而是像指挥一位程序员同事一样，从容地把需求变成可运行的工具。

适用人群：第一次接触命令行、第一次听说 Claude Code，或装好之后只会打"写个 hello world"的人。

前置条件

• 一台装好 Claude Code 的电脑。如果还没装，先用官方安装方式之一：终端运行 npm install -g @anthropic-ai/claude-code（需要 Node.js 18 以上），或使用原生安装器。装完后在任意目录敲 claude 能进入交互界面即可。
• 会一点 Python 基础语法（知道 import、函数、if 是什么）。完全不会也没关系，因为代码由 Claude 写，你只需要读懂和指挥。
• 一个"乱"的测试目录：随便建个文件夹，丢几张图片、几个 PDF、几个 zip 进去，作为练手的真实素材。
• 心态上准备好一件事：你不写代码，你写需求。

整体思路：从一句话到一个工具

很多人第一次用 Claude Code，会犯同一个错——打一句"帮我写个程序整理文件"，然后得到一段能跑但完全不是你想要的代码。原因不是 AI 笨，而是需求没说清。

本教程的核心方法叫 "需求三件套"：在每一句指令里说清楚三件事——

1. 做什么（功能）
2. 怎么用（怎么运行、输入什么、输出什么）
3. 有哪些约束（用什么语言、要不要保留原件、要不要预览）

下面我们用这个方法，一步步把"一键整理文件夹"这个工具做出来。

flowchart TD
    A[一句话想法] --> B[需求三件套\n功能+用法+约束]
    B --> C[Plan 模式: 让Claude先出方案]
    C --> D{方案满意?}
    D -->|否| C
    D -->|是| E[批准方案, Claude开始写代码]
    E --> F[运行 + 让Claude修Bug]
    F --> G{好用吗?}
    G -->|否| H[加功能迭代: dry-run/复制/日志]
    H --> F
    G -->|是| I[git保存 + 写进CLAUDE.md]
    I --> J[一个可复用的工具]

第一步：建一个干净的项目目录

为什么强调"干净"？因为 Claude Code 启动后，会把当前目录当作它的"工作台"，它会读这个目录里的文件来理解上下文。如果目录里塞满无关的东西，AI 容易被干扰。新手最稳妥的做法是每个小工具开一个独立目录。

打开终端，执行：

mkdir file-organizer
cd file-organizer
claude

预期结果：进入 Claude Code 的交互界面，左下角显示当前模式（通常是 default 普通模式），底部有一个输入框等待你打字。

常见问题：

• 敲 claude 提示命令找不到：说明没装好或没加进 PATH。回到安装步骤检查 Node 版本和全局安装路径。
• 要求登录：首次使用会引导你登录 Anthropic 账号或填 API Key，跟着提示走完即可。

第二步：用"需求三件套"写下第一句指令

不要急着让 AI 动手。我们先让它在 Plan 模式里出方案。先按一次 Shift+Tab，把左下角的模式切换到 Plan Mode（计划模式）。

Plan 模式是新手最好的朋友：在这个模式下，Claude 只读不写——它会把整个目录看一遍，然后给你一份"我打算怎么做"的计划，你点头之后它才会真正创建文件。这样即使它理解偏了，也不会在你的电脑上乱建文件。

进入 Plan 模式后，输入这句结构化需求（而不是"帮我整理文件"）：

我要做一个命令行小工具，功能是把指定目录里散落的文件按扩展名归类，
自动整理到 图片/文档/代码/压缩包 等子文件夹里。

用法：python organize.py <目录路径>，不带参数就整理当前目录。
约束：
1. 用 Python，单文件，不要第三方依赖（只用标准库）。
2. 先做"移动"模式；额外提供一个 --dry-run 参数，只打印会怎么整理、不真的移动。
3. 在终端打印一个简单的整理报告，说明每个类别移了哪些文件。

预期结果：Claude 读完需求（目录是空的，所以它主要在理解你的描述），输出一份计划，大致长这样：

• 创建 organize.py
• 用 pathlib 遍历目录
• 定义一个 扩展名 → 类别 的映射字典
• 写 --dry-run 预览逻辑
• 写 argparse 命令行入口
• 用一个 sample/ 测试目录验证

常见问题：

• 计划里有我不想要的步骤（比如要打包成 exe）：直接在输入框回复"去掉打包那步，其余按计划来"，它会调整。
• 计划太简略：回复"把每个函数的输入输出也写清楚"，让它细化。

第三步：批准方案，看着代码"长"出来

确认计划没问题后，Claude 会请你"退出计划模式以开始实现"。你可以按对应的键确认，或回复"按计划执行"。

接下来你会看到一个让人上瘾的画面：Claude 自己创建 organize.py，逐段写入代码，每写一处都会高亮显示这次改了哪几行。整个过程你不需要敲一行代码，但你要做一件重要的事——读它写的代码。

不要求看懂每一行，但至少看明白三件事：

1. 入口在哪：if __name__ == "__main__": 下面是程序真正开始跑的地方。
2. 分类规则长什么样：那个 CATEGORIES 字典，决定了"什么样的文件被分到哪个文件夹"。
3. 危险操作在哪：找到 shutil.move 这一行——这是真正会移动、删除你文件的地方。看清楚它移动的是哪个变量、移到哪里。

新手必记的安全原则：凡是看到 move、delete、remove、rmtree，眼睛要亮。本工具我们设计了 --dry-run，就是为了让你在真的动文件前，先预演一遍。

常见问题：

• 它写完报错或停住了：可能是它在等你确认一个"需要权限"的操作（比如新建文件）。按提示允许即可。
• 我想改某个分类规则：现在别打断，等它写完跑通再改（下一步）。

第四步：让它自己跑，自己修 Bug

Claude Code 不仅能写代码，还能直接运行代码。这是它和"网页版聊天 AI"最大的区别——它在你电脑上有手。

让它建一个测试目录并跑一遍：

帮我建一个 sample/ 测试目录，放几张假图片(.jpg)、几个文档(.pdf .docx)、一个压缩包(.zip)，
然后分别跑这两个命令并告诉我结果：
  python organize.py sample --dry-run   # 先预览
  python organize.py sample             # 再真正整理
最后确认 sample/ 下确实出现了 图片/文档/压缩包 子文件夹。

预期结果：Claude 创建测试文件，先跑 --dry-run 打印出"会把 a.jpg 移到 图片/、把 b.pdf 移到 文档/……"的预览，然后真正执行，最后用 ls sample/ 给你看结果，确认子文件夹都建出来了。

这是新手最该养成的习惯：把"跑测试"也当成一句话指令交给 Claude，而不是自己手忙脚乱地敲。你只要描述你期望看到什么，它负责跑、负责核对、负责把不符合预期的地方修掉。

常见问题：

• 跑的时候报 ModuleNotFoundError：说明代码里用了第三方库。回复"我只用标准库，把那个依赖换成标准库的实现"。
• 它没真的移动文件：可能是 --dry-run 还开着，或者路径写错。让它打印"实际操作的绝对路径"来排查。
• 移动到了错误的文件夹：检查 CATEGORIES 字典里那个扩展名是否归类正确，让 Claude 加上。

第五步：像点菜一样加功能（迭代）

第一版能跑之后，真正的乐趣才开始。一个好工具是迭代出来的，而不是一次写完的。你可以像点菜一样逐条加需求，每条都用"需求三件套"：

加一个 --copy 参数：默认是"移动"，加上 --copy 就改成"复制"，
原件保留在原位、副本进分类文件夹。给文件名重复的情况加个处理，
避免覆盖。同样先 --dry-run 验证。

Claude 会修改 organize.py，加上 --copy 分支和重名保护。再点一条：

再加一条规则：遇到无法识别的扩展名，归到一个"其他"文件夹，
而不是忽略。打印报告时把"其他"类也列出来。

每加一条，都让它重新跑测试确认。这种"加一点、验一点"的节奏，远比"一口气提十个需求然后崩盘"要稳。

进阶小贴士：当你改了十几轮、对话越来越长时，Claude 的"记忆"（上下文）会变满，它可能开始忘掉前面的约定。这时敲一个斜杠命令：

• /compact —— 把前面的对话总结压缩，腾出记忆空间但保留要点（推荐在长会话中段使用）。
• /clear —— 清空对话，从干净状态重新开始（适合换一个完全不相干的子任务时用）。
• /cost —— 看看这次会话花了多少 token / 多少钱，心里有数。
• /init —— 让 Claude 扫描这个项目、生成一份 CLAUDE.md 记忆文件，下次启动它就自动知道"这是个文件整理工具、用标准库、入口是 organize.py"。

常见问题：

• 加了新功能后旧功能坏了：这是经典的"回归"。让 Claude"先把刚才的所有改动用一段测试脚本跑一遍回归"。
• 它越改越乱：果断 /clear，把当前 organize.py 的内容贴给它，重新明确约束再继续。

实战案例：完整可运行的 organize.py

下面是按上述流程迭代出来的完整工具。你可以直接拿去跑，也可以让 Claude 照着改。把它存为 organize.py：

#!/usr/bin/env python3
"""一键整理文件夹：按扩展名把散落的文件归入对应子目录。"""
import argparse
import shutil
from pathlib import Path

# 分类规则：类别 -> 扩展名集合（小写）
CATEGORIES = {
    "图片": {".jpg", ".jpeg", ".png", ".gif", ".bmp", ".webp", ".svg"},
    "文档": {".pdf", ".doc", ".docx", ".xls", ".xlsx", ".ppt", ".pptx", ".txt", ".md"},
    "代码": {".py", ".js", ".ts", ".html", ".css", ".json", ".java", ".go", ".sh"},
    "压缩包": {".zip", ".rar", ".7z", ".tar", ".gz"},
    "安装包": {".exe", ".dmg", ".pkg", ".msi", ".apk"},
    "视频": {".mp4", ".mov", ".avi", ".mkv"},
    "音频": {".mp3", ".wav", ".flac", ".aac"},
}

def category_of(ext: str) -> str:
    """根据扩展名返回类别，未命中则归为'其他'。"""
    ext = ext.lower()
    for name, exts in CATEGORIES.items():
        if ext in exts:
            return name
    return "其他"

def organize(target: Path, dry_run: bool = False, move: bool = True) -> dict:
    """遍历 target，按类别归类文件；返回 {类别: [文件名]} 报告。"""
    report = {}
    if not target.is_dir():
        raise SystemExit(f"目录不存在: {target}")
    for item in target.iterdir():
        if not item.is_file():
            continue
        cat = category_of(item.suffix)
        report.setdefault(cat, []).append(item.name)
        if dry_run:
            continue
        dest_dir = target / cat
        dest_dir.mkdir(exist_ok=True)
        dest = dest_dir / item.name
        # 重名保护：遇到 a.txt 已存在就改成 a_1.txt
        if dest.exists():
            i = 1
            while dest.with_name(f"{item.stem}_{i}{item.suffix}").exists():
                i += 1
            dest = dest_dir / f"{item.stem}_{i}{item.suffix}"
        if move:
            shutil.move(str(item), str(dest))
        else:
            shutil.copy2(str(item), str(dest))
    return report

def main():
    p = argparse.ArgumentParser(description="一键整理杂乱文件夹")
    p.add_argument("path", nargs="?", default=".", help="要整理的目录，默认当前目录")
    p.add_argument("--dry-run", action="store_true", help="只预览，不实际移动/复制")
    p.add_argument("--copy", action="store_true", help="复制而非移动（保留原件）")
    args = p.parse_args()

    mode = "预览(dry-run)" if args.dry_run else ("复制" if args.copy else "移动")
    print(f"目标目录: {Path(args.path).resolve()}")
    print(f"模式: {mode}\n")

    report = organize(Path(args.path), dry_run=args.dry_run, move=not args.copy)

    if not report:
        print("目录里没有需要整理的文件。")
        return
    for cat, files in sorted(report.items()):
        print(f"[{cat}] ({len(files)} 个)")
        for f in files:
            print(f"   - {f}")
    print(f"\n共整理 {sum(len(v) for v in report.values())} 个文件。")

if __name__ == "__main__":
    main()

三种用法速查：

python organize.py ~/Downloads --dry-run   # 先看一眼会怎么整，最安全
python organize.py ~/Downloads             # 真正移动整理
python organize.py ~/Downloads --copy      # 复制整理，原件不动

跑完你会得到一份清晰的报告：

目标目录: /home/me/Downloads
模式: 预览(dry-run)

[图片] (2 个)
   - trip.jpg
   - cat.png
[文档] (1 个)
   - invoice.pdf
[其他] (1 个)
   - weird.xyz

共整理 4 个文件。

把它存进 ~/bin/ 或别名一下，以后每次"下载文件夹又满了"，一行命令就能收拾干净。这就是你用 Claude Code 做出的第一个真正属于自己、每天都在用的工具。

工作流程回顾

flowchart LR
    subgraph 你负责
      A1[把想法写成\n需求三件套] --> A2[读Claude的计划\n点头或纠正]
      A2 --> A3[读危险操作\nmove/delete]
      A3 --> A4[描述期望结果\n让它跑测试]
    end
    subgraph Claude负责
      B1[理解需求] --> B2[出计划/写代码]
      B2 --> B3[运行+核对]
      B3 --> B4[按反馈修复]
    end
    A1 -.-> B1
    A2 -.-> B2
    A4 -.-> B3
    A4 -.-> B4

记住这张图的分工：你出需求和质量判断，Claude 出代码和执行。新手最大的转变，就是从"我自己写"切换到"我描述清楚、我来验收"。

延伸阅读

• Claude Code 官方 Quickstart：最权威的安装与首跑流程，遇到环境问题先查这里。
• Claude 帮助中心《Your first day in Claude Code》：15 分钟从安装到完成第一个 AI 协助任务，与本教程互补。
• builder.io《How to Use Claude Code》：专门讲"为什么大多数人打一句模糊指令只得到平庸结果"，与本教程的"需求三件套"理念一致。
• 做完本工具后，下一步可以学 CLAUDE.md 记忆文件（用 /init 生成）和 斜杠命令，让你的工具可以被 Claude 长期记住和复用。

训练营适用性评估

• 适合的营型：企业内训"AI 编程入门营"、高校"AI 工具实战"选修课、开发者社区的周末工作坊。零基础友好，产出明确（一个人人能用的工具），成就感强。
• 预计教学时长：约 3–4 小时。其中 30 分钟讲工作流与"需求三件套"、2 小时动手从计划到迭代、30 分钟拓展（/init、/compact、git 保存）、30 分钟答疑。
• 学员产出：每人带走一个可运行的 organize.py，以及一套可迁移到任何后续项目的"AI 编码方法论"。
• 进阶衔接：本教程是入门篇；之后可自然过渡到 Skill 开发、MCP 工具构建、自动化批处理等专题。

参考来源

1. Quickstart — Claude Code Docs — 官方快速上手，安装与终端 CLI 首跑权威流程。
2. Your first day in Claude Code — Claude Help Center — 官方"第一天"指引，15 分钟完成首个 AI 协助任务。
3. How to Use Claude Code (Beginner Guide) — builder.io — 重点讲解"模糊指令为何得不到好结果"，呼应本文的需求描述方法。
4. Claude Code Tutorial for Beginners 2026 — dev.to — 2026 年版从安装到首项目的完整 walkthrough。
5. Claude Code: Complete Guide From Beginner to Power User 2026 — theneuron.ai — 涵盖上下文堆叠、Plan 模式、并行会话等进阶工作流，供学完本篇后延伸。

[!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 等场景全覆盖。