本教程为零基础读者设计，目标只有一个：在今天结束前，亲手用 Claude Code 在自己的电脑上装好、配好，并驱动它从零写出第一个能真正运行的项目——一个带数据持久化的命令行记账本（ledger）。你将学到 Claude Code 是什么、三种主流安装方式、登录与认证、四层配置体系（Managed / User / Project / Local）、CLAUDE.md 项目记忆、以及如何用自然语言指挥 AI 写代码、跑测试、提交 Git。适合从未用过 AI 编程工具、但会基本命令行操作的同学，预计 60–90 分钟跑完全程。
cd 切目录即可，不需要会写代码——这正是本教程要交给 AI 的部分。没账号的同学先去 claude.com/pricing 开通订阅，再回来继续。本教程的命令在三大平台通用，差别仅在安装那一步。
在动手装之前，先花一分钟建立正确的心智模型，这能让你后面少踩很多坑。
Claude Code 不是又一个"网页版聊天框"，而是一个跑在你本地终端里的 AI 编程代理（agentic coding assistant）。 它和网页聊天框的核心区别有三点：
一句话总结：网页版 Claude 是"嘴"，Claude Code 是"手"。 本教程要教你的，就是怎么指挥这双"手"帮你干活。
打开终端，按你的系统和偏好选一种方式。2026 年官方推荐的是原生安装（Native Install），它不依赖 Node.js，且会在后台自动更新。
方式 A：原生安装（推荐，macOS / Linux / WSL）
curl -fsSL https://claude.ai/install.sh | bash
Windows PowerShell 用户：
irm https://claude.ai/install.ps1 | iex
方式 B：包管理器（适合已有工具链的同学）
macOS（Homebrew）：
brew install --cask claude-code
Windows（WinGet）：
winget install Anthropic.ClaudeCode
Linux 还可用 apt / dnf / apk，详见官方 setup 文档。
方式 C：npm（老牌方式，需要先装 Node.js 18+）
npm install -g @anthropic-ai/claude-code
⚠️ 官方明确提醒：不要用
sudo npm install -g，否则后面会有一堆权限坑。
预期结果：安装完成后，在终端输入：
claude --version
能看到版本号（本文撰写时主线版本约 v2.1.92+），说明安装成功。
常见问题
| 现象 | 原因与解决 |
|---|---|
curl 报 403 或 syntax error near unexpected token '<' |
多半是公司网络代理或镜像拦截了脚本，换个网络或参考 Troubleshoot installation 找替代安装方式 |
PowerShell 里提示 'irm' is not recognized |
说明你其实在 CMD 里，CMD 不认 irm，改用方式 A 里的 Windows CMD 命令 |
| npm 安装后提示全局目录不可写、无法自动更新 | 跑 claude doctor 看建议修复，或干脆改用原生安装 |
装完输 claude 提示 command not found |
新开一个终端窗口让 PATH 生效；仍不行检查 ~/.claude/ 是否生成 |
装好后，任意目录下运行：
claude
首次启动会引导你登录。订阅或 Console 账号会自动打开浏览器，你在网页上确认授权后，终端这边就登录成功了。登录信息会保存在本机，之后不用重复登录。
/login。/status 或 /login 查看；Console 用户可在 console.anthropic.com 的 "Claude Code" 工作区集中看账单。预期结果：终端出现 Claude Code 的提示符界面，顶部显示版本号、当前模型（如 Sonnet 4.6）、当前工作目录。底部是输入框，光标闪烁，等待你下指令。
常见问题
/login 重试一次，或检查系统时间是否准确（时间偏差大会导致鉴权失败）。这是新手最容易跳过、却最值钱的一步。Claude Code 的所有可调参数（权限、环境变量、模型、MCP、钩子）都遵循一套四层配置优先级，从高到低：
flowchart TB
M["Managed 托管配置<br/>企业 IT 下发，不可被覆盖"] --> U
U["User 用户配置<br/>~/.claude/settings.json<br/>对你所有项目生效"] --> P
P["Project 项目配置<br/>.claude/settings.json<br/>随 Git 提交，团队共享"] --> L
L["Local 本地配置<br/>.claude/settings.local.json<br/>仅你本机，默认 gitignore"]
style M fill:#ffd6d6
style L fill:#d6e8ff
对应的文件位置速查表：
| 维度 | 用户级（全局） | 项目级（共享） | 本地级（私有） |
|---|---|---|---|
| Settings | ~/.claude/settings.json |
.claude/settings.json |
.claude/settings.local.json |
| CLAUDE.md 记忆 | ~/.claude/CLAUDE.md |
CLAUDE.md 或 .claude/CLAUDE.md |
CLAUDE.local.md |
| MCP 服务器 | ~/.claude.json |
.mcp.json |
~/.claude.json（按项目） |
| 子代理 | ~/.claude/agents/ |
.claude/agents/ |
— |
新手记住两条就够：
settings.json，不用重启，正在运行的会话立刻生效。我们马上动手建一个最小项目配置。先为本教程创建工作目录：
mkdir ~/ledger && cd ~/ledger
然后直接在 Claude Code 会话里输入（这是你第一次"指挥"它）：
帮我初始化一个 Python 项目骨架：创建 .claude/ 目录，
在里面生成 settings.local.json，预设只读权限白名单允许 ls、cat、python、pytest，
并忽略任何删除操作。
预期结果：Claude Code 会先列出它打算创建/修改的文件，征求你同意（按 y 批准），然后生成类似这样的 .claude/settings.local.json：
{
"permissions": {
"allow": ["Bash(ls:*)", "Bash(cat:*)", "Bash(python:*)", "Bash(pytest:*)"],
"deny": ["Bash(rm:*)"]
}
}
光有配置还不够。你想让 Claude Code 每次都懂你的项目约定（用什么语言、怎么跑测试、命名规范），靠的是 CLAUDE.md。这是一份会被自动注入到每次对话上下文的"项目说明书"。
在会话里继续输入：
生成一份 CLAUDE.md，内容包括：
- 项目名：命令行记账本 ledger
- 技术栈：Python 3，数据用 JSON 文件持久化，禁止引入第三方依赖
- 约定：所有金额以分为单位（整数）存储，展示时再除以 100；中文注释
- 测试：用 pytest，放 tests/ 目录
预期结果：项目根目录出现 CLAUDE.md。从此之后，每次在这个目录启动 claude，它都会"记得"这些约定——你不用每次重复说明。常见问题：发现 Claude 似乎没遵守 CLAUDE.md？检查文件是否在项目根、内容是否用祈使句写清"必须/禁止"，模糊的描述它会更自由发挥。
现在进入高潮。全程你不写一行代码，只负责"提需求 + 审核"。 在会话里分步下指令（一次别贪多，让它一步步来，你看得清）：
指令 1（搭骨架 + 数据层）
实现一个命令行记账本 ledger.py，要求：
1. 用 argparse 接收子命令：add / list / summary / delete
2. 数据存在 data.json，结构 {"entries": [{"id","date","amount","category","note"}]}
3. add：记录一条支出，amount 单位为分；list：列出全部；summary：按 category 汇总金额并打印总支出；delete --id：按 id 删除
4. 给每个函数写中文 docstring
先给我看文件结构和 add 的实现，等我确认再做 summary。
指令 2（测试）
为 add 和 summary 写 pytest 测试，用 tmp_path 隔离 data.json，
覆盖：正常记账、空数据汇总、金额单位转换（输入元转分存储）。
跑一遍 pytest 给我看结果。
指令 3（细节打磨）
list 默认按日期倒序，加 --category 过滤；
summary 把分转成元展示并保留两位小数。
预期结果：Claude Code 会逐个创建 ledger.py、tests/test_ledger.py，并实际跑 pytest 把绿色"all passed"打印给你看。你甚至可以亲自验证一下：
python ledger.py add --amount 12.50 --category 餐饮 --note "午餐"
python ledger.py add --amount 30 --category 交通 --note "打车"
python ledger.py summary
终端应输出类似：
餐饮: 12.50 元
交通: 30.00 元
总支出: 42.50 元
常见问题
pytest 报 command not found：让它装，指令"用 pip 在用户级安装 pytest 再重跑"。Shift+Tab 在权限模式间循环切换（acceptEdits / plan / bypassPermissions 等），新手建议先用默认的逐条确认。最后让 Claude Code 帮你把成果提交：
git init，把 ledger.py、tests/、CLAUDE.md 加入版本控制，
注意别提交 data.json 和 .claude/settings.local.json，
然后写一条规范的中文 commit message 并提交。
它会自动生成 .gitignore、暂存文件、给出 commit message 供你确认。这就是一次完整的代理循环：理解目标 → 调用 Bash/Read/Write 工具 → 观察输出 → 决定下一步 → 达成目标。
跑完上面七步，你的 ~/ledger 应长这样：
flowchart LR
A["~/ledger/"] --> B["ledger.py<br/>主程序：add/list/summary/delete"]
A --> C["CLAUDE.md<br/>项目记忆与约定"]
A --> D[".gitignore"]
A --> E["data.json<br/>运行时生成，已忽略"]
A --> F[".claude/"]
A --> G["tests/"]
F --> F1["settings.local.json<br/>本地权限白名单"]
G --> G1["test_ledger.py<br/>pytest 测试"]
style E fill:#fff3d6
style F1 fill:#d6e8ff
这是一份麻雀虽小五脏俱全的真实工程：有源码、有测试、有配置分层、有项目记忆、有版本控制。你已经踩通了 90% 真实开发者每天用的 Claude Code 工作流。
进阶练习（留作作业）：
export --csv 子命令，导出 CSV。month YYYY-MM 子命令，按月汇总。每做完一项就让它写测试、跑测试、提交一次 commit，形成"需求→实现→验证→提交"的肌肉记忆。
flowchart TD
S1["1. 安装<br/>curl 原生 / brew / npm"] --> S2["2. 首次登录<br/>claude → 浏览器授权"]
S2 --> S3["3. 建项目目录 cd ~/ledger"]
S3 --> S4["4. 配置分层<br/>settings.local.json 权限"]
S4 --> S5["5. 写 CLAUDE.md<br/>项目记忆"]
S5 --> S6["6. 分步下指令造项目<br/>骨架→数据→测试→打磨"]
S6 --> S7["7. 实跑验证<br/>python ledger.py summary"]
S7 --> S8["8. Git 初始化 + 规范提交"]
S8 --> S9{满意?}
S9 -->|否| S6
S9 -->|是| S10["✅ 第一个真实项目上线"]
style S10 fill:#d6ffd6
-p 模式（批量审计 ledger 记录）。python ledger.py summary 看到汇总输出，并完成一次 git commit，即视为通关。本文由「51学通信」原创制作，站长爱卫生（微信：gprshome201101）。动手过程中卡住了？带着报错截图来交流。
[!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 等场景全覆盖。