# 零基础装通 Claude Code 造番茄钟计时器 ## 概述 本教程带你从零开始：安装 Claude Code、完成首次认证与权限配置、理解配置体系，最后用一句话驱动它为你写出一个**可运行的番茄钟计时器（Pomodoro Timer）**。番茄钟是经典的入门练手项目——它涉及时间逻辑、命令行参数、文件读写、异常处理，正好覆盖编程基础的全部要点，又能在一个文件内跑通，特别适合用来验证"Claude Code 到底能不能干活"。适用人群：完全没用过 Claude Code 的零基础开发者，或刚安装却不知道下一步该做什么的新手。学完后你将掌握安装、认证、配置三件套，并拥有第一个由 AI 生成、自己能读懂改动的真实小工具。 ## 前置条件 | 项目 | 要求 | 说明 | |------|------|------| | 操作系统 | macOS / Linux / Windows | 三端均原生支持 | | Node.js | ≥ 18（推荐 20 LTS） | 原生安装器也需它兜底 | | 网络 | 能访问 Anthropic 服务 | 国内需自备网络通道 | | 账号 | Claude 账号 或 API Key | 二选一即可 | | 终端 | 任意现代终端 | Windows 推荐 WSL2 + Windows Terminal | 零基础同学请先确认命令行能跑 `node -v`。装好 Node 后，本教程剩余部分大约 30 分钟可走完。 --- ## 第一步：安装 Claude Code Claude Code 是 Anthropic 官方推出的、运行在终端里的 AI 编程助手。它直接读写你的本地文件、执行命令、理解整个工程上下文，和"复制粘贴到网页聊天框"的用法有本质区别。 ### 方式一：npm 全局安装（最通用） ```bash npm install -g @anthropic-ai/claude-code ``` **预期结果**：终端打印一串安装日志，结尾没有红色 `ERR!`，回到提示符。 **验证**： ```bash claude --version # 期望输出类似：1.0.x（版本号会持续更新） ``` ### 方式二：原生安装器（无需 Node 的机器） ```bash # macOS / Linux curl -fsSL https://claude.ai/install.sh | bash # Windows (PowerShell) irm https://claude.ai/install.ps1 | iex ``` 原生安装器会把二进制放到固定目录并配好 PATH，适合不想折腾 Node 的机器。 ### 常见问题 - **`command not found: claude`**：npm 全局 bin 目录不在 PATH 里。运行 `npm config get prefix` 查到路径，把它的 `bin` 子目录加入 PATH。 - **`EACCES` 权限错误**：不要用 `sudo` 装 npm 全局包，会引发后续权限混乱。改用 `nvm` 管理 Node，或配置 npm 的全局前缀到用户目录。 - **国内网络超时**：给 npm 设镜像源 `npm config set registry https://registry.npmmirror.com`，但 Claude Code 本体联网仍需能访问 Anthropic 服务。 --- ## 第二步：首次配置与认证 安装完只是装了个壳子，认证之后它才"活"过来。 ### 认证方式 A：浏览器登录（推荐新手） 在任意目录直接输入： ```bash claude ``` 首次启动会进入交互式引导，提示你按回车打开浏览器，登录你的 Claude 账号即可。登录完成后，终端会显示欢迎信息并进入交互模式，光标变成等待你输入的状态。 ### 认证方式 B：API Key（CI / 无头环境） ```bash export ANTHROPIC_API_KEY="sk-ant-xxxxxxxxxxxx" ``` 把这行写进你的 `~/.bashrc` 或 `~/.zshrc`，之后 `claude -p "你好"` 就能直接返回结果，无需浏览器。 ### 第一次试水 进入交互模式后，随便问一句： ``` > 用一句话介绍你自己，并列出你能调用的工具 ``` **预期结果**：Claude 会自我介绍，并列出 Read、Write、Edit、Bash、Grep、Glob 等工具。看到这个列表，说明认证成功、工具链就绪。 --- ## 第三步：理解配置体系（核心概念） 很多人装完直接开干，结果被权限弹窗打断节奏。理解下面三层配置，能让你后续少踩 80% 的坑。 ### 层级 1：`CLAUDE.md` —— 项目记忆 在项目根目录放一个 `CLAUDE.md`，Claude Code 每次启动都会自动读取它。它相当于给 AI 写"项目说明书"。本例可以创建： ```markdown # 番茄钟项目 ## 技术栈 - Python 3，单文件，零依赖 ## 约定 - 默认专注 25 分钟，休息 5 分钟 - 命令行第一个参数指定轮数，默认 4 轮 - 完成的番茄记录追加到 pomodoro.log ``` ### 层级 2：`settings.json` —— 行为开关 配置文件位于 `~/.claude/settings.json`（用户级）或项目内 `.claude/settings.json`（项目级）。一个对新手友好的初始配置： ```json { "permissions": { "allow": ["Bash(npm *)", "Bash(python *)", "Read(*)", "Edit(*)"], "deny": ["Bash(rm -rf *)", "Read(./.env/*)"] }, "env": { "CLAUDE_CODE_MAX_OUTPUT_TOKENS": "4096" } } ``` - `allow`：白名单里的命令**不再弹窗**直接放行，省去反复确认。 - `deny`：黑名单，永远拒绝，防止误删。 - 未匹配的命令走默认的逐次确认流程。 ### 层级 3：权限模式 启动时可切换四种模式，决定了 Claude "自主"的程度： | 模式 | 含义 | 适用场景 | |------|------|----------| | `default` | 写文件/执行命令前逐次问你 | 新手默认，最安全 | | `acceptEdits` | 自动接受文件编辑 | 改代码阶段，提速 | | `plan` | 只规划不执行 | 复杂任务先看方案 | | `bypassPermissions` | 全部放行 | 沙箱/受控环境批量任务 | 新手请老老实实用 `default`。等你熟悉了，再用 `Shift+Tab` 在交互中循环切换模式。 --- ## 第四步：第一个项目——番茄钟计时器 理论够了，动手。番茄钟核心规则：**25 分钟专注 → 5 分钟休息 → 循环 4 轮 → 长休息**。 ### 4.1 建项目目录 ```bash mkdir ~/pomodoro && cd ~/pomodoro ``` ### 4.2 把上面写好的 `CLAUDE.md` 放进去 （见第三步，让 AI 提前知道你的约定） ### 4.3 一句话驱动 Claude Code 写代码 进入目录后启动 Claude： ```bash claude ``` 在交互框里输入这段需求： ``` 用 Python 写一个番茄钟计时器 pomodoro.py： 1. 默认 25 分钟专注、5 分钟休息、4 轮循环 2. 第一个命令行参数可指定轮数 3. 倒计时实时刷新在终端同一行 4. 每完成一个番茄，把日期时间和轮次追加写入 pomodoro.log 5. Ctrl+C 优雅退出，打印"已停止" ``` 按回车，观察它的行为：它会先 `Read` 目录确认环境，再 `Write` 出 `pomodoro.py`，可能还会 `Bash(python pomodoro.py 1)` 跑一轮测试。 ### 4.4 运行验证 退出 Claude（输入 `/exit` 或按两次 `Ctrl+C`），在终端运行： ```bash python3 pomodoro.py 1 ``` **预期结果**：终端显示 `🍅 专注中: 25:00` 并逐秒倒数；25 分钟（测试时可临时把 `WORK_MIN` 改成 1 验证）后切换到 `☕ 休息中`；结束后 `pomodoro.log` 里多出一行记录。 > **小技巧**：第一次完整跑 25 分钟太久，把代码里的 `WORK_MIN=25` 临时改成 `WORK_MIN=1` 验证流程，验证完再让 Claude 改回去——直接说"把专注时长改回 25"即可。 --- ## 第五步：常见问题与解决方案 | 现象 | 原因 | 解决 | |------|------|------| | Claude 每次都弹窗问能不能执行命令 | 权限白名单没配 | 按第三步配 `settings.json` 的 `allow` | | 改完代码它不认账又改回去 | 没写 `CLAUDE.md` 或被旧记忆覆盖 | 明确指令 + 写清项目约定 | | `/` 开头的命令没反应 | 那不是有效 slash 命令 | 输入 `/` 看自动补全列表 | | 终端显示乱码番茄表情 | Windows 终端编码/字体问题 | 换 Windows Terminal + 支持表情的字体 | | 改动太多不敢确认 | 默认模式太谨慎反而慢 | 信任后用 `Shift+Tab` 切 `acceptEdits` | --- ## 实战案例：完整可运行代码 下面是 Claude Code 生成、经人工校对、开箱即用的 `pomodoro.py`。即便你跳过前面的对话过程，把这段代码存成文件也能直接跑： ```python #!/usr/bin/env python3 """番茄钟计时器：25 分钟专注 + 5 分钟休息，默认 4 轮。""" import sys import time from datetime import datetime WORK_MIN = 25 # 专注时长（分钟），调试时可改为 1 BREAK_MIN = 5 # 短休息时长 LONG_BREAK_MIN = 15 # 最后一轮后的长休息 DEFAULT_ROUNDS = 4 LOG_FILE = "pomodoro.log" def countdown(total_seconds, label): """在终端同一行刷新倒计时。""" while total_seconds: mins, secs = divmod(total_seconds, 60) print(f"\r{label}: {mins:02d}:{secs:02d} ", end="", flush=True) time.sleep(1) total_seconds -= 1 print(f"\r{label}: ✅ 完成！ ") def log_session(round_no, total_rounds): """把完成的番茄追加写入日志文件。""" stamp = datetime.now().strftime("%Y-%m-%d %H:%M:%S") with open(LOG_FILE, "a", encoding="utf-8") as f: f.write(f"[{stamp}] 第 {round_no}/{total_rounds} 个番茄完成\n") print(f"📝 已记录到 {LOG_FILE}") def main(): rounds = int(sys.argv[1]) if len(sys.argv) > 1 else DEFAULT_ROUNDS print(f"🍅 番茄钟启动：共 {rounds} 轮，每轮 {WORK_MIN} 分钟专注\n") for i in range(1, rounds + 1): print(f"--- 第 {i}/{rounds} 轮 ---") countdown(WORK_MIN * 60, "🍅 专注中") log_session(i, rounds) if i < rounds: countdown(BREAK_MIN * 60, "☕ 休息中") else: countdown(LONG_BREAK_MIN * 60, "🎉 长休息") print("\n🏆 全部完成，辛苦了！") if __name__ == "__main__": try: main() except KeyboardInterrupt: print("\n\n⏹ 已停止番茄钟，下次加油！") sys.exit(0) ``` **进阶玩法**：让它继续长大——对 Claude 说"给番茄钟加一个 `--stats` 参数，统计今天完成了多少个番茄"，它会读日志、写解析、再加命令行参数解析，全程自动。这就是 Claude Code 的真正价值：**你提需求，它读你的代码、改你的代码、跑你的测试，闭环。** --- ## 工作流程图 ```mermaid flowchart TD A[安装 Node.js] --> B[npm i -g claude-code] B --> C[claude 启动 + 浏览器登录] C --> D[建项目目录 + 写 CLAUDE.md] D --> E[配 settings.json 权限白名单] E --> F[一句话提需求: 写番茄钟] F --> G{Claude 读取目录} G --> H[Write 生成 pomodoro.py] H --> I[Bash 运行测试] I --> J{符合预期?} J -- 否 --> K[对话指正, 迭代] K --> I J -- 是 --> L[完成第一个项目 🎉] ``` 整个链路里，**人只在 D、E、F、J 四个点介入**，其余由 Claude Code 自主完成。这就是"AI 编程助手"与"搜索引擎式问答"的根本区别。 --- ## 延伸阅读 - **官方文档主站**：`docs.anthropic.com/en/docs/claude-code` —— 权威的命令、配置、权限参考，遇到分歧以它为准。 - **交互式 slash 命令**：在 Claude Code 里输入 `/` 查看全部命令（`/help`、`/config`、`/permissions`、`/init` 等），这是最快的"边用边学"路径。 - **`CLAUDE.md` 进阶**：理解项目记忆后，再学 hooks、skills、subagents，会从"能用"跨到"高效用"。本系列后续篇章会逐一覆盖。 --- ## 训练营适用性评估 | 维度 | 评估 | |------|------| | **适合的训练营类型** | 编程零基础入门营、AI 工具上手营、效率提升工作坊 | | **不适合** | 纯算法竞赛营、纯运维/SRE 营（需另配项目） | | **预计教学时长** | 讲授 45 分钟 + 动手实操 60 分钟，合计约 2 课时 | | **学员产出** | 每人一个能跑的番茄钟 + 一份自己的 `CLAUDE.md` 和 `settings.json` | | **考核标准** | 能独立完成安装认证、能解释权限模式区别、能驱动 Claude 迭代一次新功能（如 `--stats`） | | **延伸作业** | 把番茄钟改成"喝水提醒""站立提醒"，或加入桌面通知 | 本教程作为**系列第一课**，定位是"装通 + 跑通 + 建立信心"。完成它后，学员应能独立使用 Claude Code 处理日常小工具开发，为后续 Skills、MCP、Agent 等高阶主题打下地基。 --- ## 参考来源 1. [Claude Code Tutorial for Beginners 2026: From Installation to Building Your First Project — DEV Community](https://dev.to/ayyazzafar/claude-code-tutorial-for-beginners-2026-from-installation-to-building-your-first-project-1lma) — 从安装到第一个项目的完整零基础流程，是本文主线结构的重要参照。 2. [Getting Started with Claude Code in 2026: Setup to First Commit — SeptimLabs](https://septimlabs.com/blog/getting-started-with-claude-code-2026) — 五步上手流程（Install / Auth / CLAUDE.md / First Task / Cost Check），本文认证与配置部分参考其框架。 3. [Claude Code Tutorial 2026: Complete Setup and Workflow Guide — RockB](https://baeseokjae.github.io/posts/claude-code-tutorial-2026/) — 覆盖 memory、skills、hooks、MCP 的完整工作流，为本文延伸阅读提供索引。 4. [Building a Pomodoro Timer with Claude Code — note.com](https://note.com/tsukurun_d7/n/n1698fe2117ce) — 用 Claude Code 一小时做出番茄钟的实战记录，验证了本项目选题的可行性。 5. [Anthropic Claude Code 官方文档](https://docs.anthropic.com/en/docs/claude-code) — 命令、权限、配置的权威来源，所有命令以官方文档为准。 > [!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 等场景全覆盖。