## 概述 本教程面向**零基础**读者，目标只有一个：在一个下午之内，用 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. **有哪些约束**（用什么语言、要不要保留原件、要不要预览） 下面我们用这个方法，一步步把"一键整理文件夹"这个工具做出来。 ```mermaid 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 容易被干扰。新手最稳妥的做法是每个小工具开一个独立目录。 打开终端，执行： ```bash 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`： ```python #!/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() ``` **三种用法速查**： ```bash 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 做出的第一个**真正属于自己、每天都在用**的工具。 --- ## 工作流程回顾 ```mermaid 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](https://code.claude.com/docs/en/quickstart) — 官方快速上手，安装与终端 CLI 首跑权威流程。 2. [Your first day in Claude Code — Claude Help Center](https://support.claude.com/en/articles/14552382-your-first-day-in-claude-code) — 官方"第一天"指引，15 分钟完成首个 AI 协助任务。 3. [How to Use Claude Code (Beginner Guide) — builder.io](https://www.builder.io/blog/how-to-use-claude-code) — 重点讲解"模糊指令为何得不到好结果"，呼应本文的需求描述方法。 4. [Claude Code Tutorial for Beginners 2026 — dev.to](https://dev.to/ayyazzafar/claude-code-tutorial-for-beginners-2026-from-installation-to-building-your-first-project-1lma) — 2026 年版从安装到首项目的完整 walkthrough。 5. [Claude Code: Complete Guide From Beginner to Power User 2026 — theneuron.ai](https://www.theneuron.ai/explainer-articles/claude-code-guide-how-to-use-it%20/) — 涵盖上下文堆叠、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 等场景全覆盖。