本教程带你从零开始：安装 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 是 Anthropic 官方推出的、运行在终端里的 AI 编程助手。它直接读写你的本地文件、执行命令、理解整个工程上下文，和"复制粘贴到网页聊天框"的用法有本质区别。
npm install -g @anthropic-ai/claude-code
预期结果：终端打印一串安装日志，结尾没有红色 ERR!，回到提示符。
验证：
claude --version
# 期望输出类似：1.0.x（版本号会持续更新）
# 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 config set registry https://registry.npmmirror.com，但 Claude Code 本体联网仍需能访问 Anthropic 服务。安装完只是装了个壳子，认证之后它才"活"过来。
在任意目录直接输入：
claude
首次启动会进入交互式引导，提示你按回车打开浏览器，登录你的 Claude 账号即可。登录完成后，终端会显示欢迎信息并进入交互模式，光标变成等待你输入的状态。
export ANTHROPIC_API_KEY="sk-ant-xxxxxxxxxxxx"
把这行写进你的 ~/.bashrc 或 ~/.zshrc，之后 claude -p "你好" 就能直接返回结果，无需浏览器。
进入交互模式后，随便问一句：
> 用一句话介绍你自己，并列出你能调用的工具
预期结果：Claude 会自我介绍，并列出 Read、Write、Edit、Bash、Grep、Glob 等工具。看到这个列表，说明认证成功、工具链就绪。
很多人装完直接开干，结果被权限弹窗打断节奏。理解下面三层配置，能让你后续少踩 80% 的坑。
CLAUDE.md —— 项目记忆在项目根目录放一个 CLAUDE.md，Claude Code 每次启动都会自动读取它。它相当于给 AI 写"项目说明书"。本例可以创建：
# 番茄钟项目
## 技术栈
- Python 3，单文件，零依赖
## 约定
- 默认专注 25 分钟，休息 5 分钟
- 命令行第一个参数指定轮数，默认 4 轮
- 完成的番茄记录追加到 pomodoro.log
settings.json —— 行为开关配置文件位于 ~/.claude/settings.json（用户级）或项目内 .claude/settings.json（项目级）。一个对新手友好的初始配置：
{
"permissions": {
"allow": ["Bash(npm *)", "Bash(python *)", "Read(*)", "Edit(*)"],
"deny": ["Bash(rm -rf *)", "Read(./.env/*)"]
},
"env": {
"CLAUDE_CODE_MAX_OUTPUT_TOKENS": "4096"
}
}
allow：白名单里的命令不再弹窗直接放行，省去反复确认。deny：黑名单，永远拒绝，防止误删。启动时可切换四种模式，决定了 Claude "自主"的程度：
| 模式 | 含义 | 适用场景 |
|---|---|---|
default |
写文件/执行命令前逐次问你 | 新手默认，最安全 |
acceptEdits |
自动接受文件编辑 | 改代码阶段，提速 |
plan |
只规划不执行 | 复杂任务先看方案 |
bypassPermissions |
全部放行 | 沙箱/受控环境批量任务 |
新手请老老实实用 default。等你熟悉了，再用 Shift+Tab 在交互中循环切换模式。
理论够了，动手。番茄钟核心规则：25 分钟专注 → 5 分钟休息 → 循环 4 轮 → 长休息。
mkdir ~/pomodoro && cd ~/pomodoro
CLAUDE.md 放进去（见第三步，让 AI 提前知道你的约定）
进入目录后启动 Claude：
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) 跑一轮测试。
退出 Claude（输入 /exit 或按两次 Ctrl+C），在终端运行：
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。即便你跳过前面的对话过程，把这段代码存成文件也能直接跑：
#!/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 的真正价值：你提需求，它读你的代码、改你的代码、跑你的测试，闭环。
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 —— 权威的命令、配置、权限参考，遇到分歧以它为准。/ 查看全部命令（/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 等高阶主题打下地基。
[!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 等场景全覆盖。