<!-- title: 零基础装通并造首个记账本 -->

# Claude Code 入门篇：从安装到造出你的第一个命令行记账本

## 概述

本教程为零基础读者设计，目标只有一个：**在今天结束前，亲手用 Claude Code 在自己的电脑上装好、配好，并驱动它从零写出第一个能真正运行的项目——一个带数据持久化的命令行记账本（ledger）**。你将学到 Claude Code 是什么、三种主流安装方式、登录与认证、四层配置体系（Managed / User / Project / Local）、CLAUDE.md 项目记忆、以及如何用自然语言指挥 AI 写代码、跑测试、提交 Git。适合从未用过 AI 编程工具、但会基本命令行操作的同学，预计 60–90 分钟跑完全程。

## 前置条件

- **一台能联网的电脑**：Windows（建议装 Git for Windows 或使用 WSL）、macOS、或 Linux 均可。
- **基本终端操作能力**：会打开终端、`cd` 切目录即可，不需要会写代码——这正是本教程要交给 AI 的部分。
- **一个 Anthropic 账号**：以下任一其一即可：
  - Claude 订阅（Pro / Max / Team / Enterprise）——**最推荐**，开箱即用；
  - Claude Console 账号（[console.anthropic.com](https://console.anthropic.com/)，预付费额度、按量计费）；
  - 企业云：Amazon Bedrock / Google Vertex AI / Microsoft Foundry。
- **可选**：Python 3.8+（本教程项目用 Python 实现，没有也没关系，Claude Code 会帮你判断和安装）。

> 没账号的同学先去 [claude.com/pricing](https://claude.com/pricing) 开通订阅，再回来继续。本教程的命令在三大平台通用，差别仅在安装那一步。

---

## 正文

### 第一步：理解 Claude Code 到底是什么

在动手装之前，先花一分钟建立正确的心智模型，这能让你后面少踩很多坑。

**Claude Code 不是又一个"网页版聊天框"，而是一个跑在你本地终端里的 AI 编程代理（agentic coding assistant）。** 它和网页聊天框的核心区别有三点：

1. **它能看到你的真实项目文件**：你在哪个目录启动它，它就能读取、理解那个目录下的全部代码，不需要你手动复制粘贴。
2. **它能动手改文件**：经你授权后，它可以直接创建、编辑、删除文件，还能执行终端命令（跑测试、装依赖、git 操作）。
3. **它有一个"代理循环（agentic loop）"**：你给它一个目标，它会自己分解步骤、调用工具、观察结果、再决定下一步，而不是只回一句话。

一句话总结：**网页版 Claude 是"嘴"，Claude Code 是"手"。** 本教程要教你的，就是怎么指挥这双"手"帮你干活。

### 第二步：安装 Claude Code（三选一）

打开终端，按你的系统和偏好选一种方式。**2026 年官方推荐的是原生安装（Native Install）**，它不依赖 Node.js，且会在后台自动更新。

**方式 A：原生安装（推荐，macOS / Linux / WSL）**

```bash
curl -fsSL https://claude.ai/install.sh | bash
```

Windows PowerShell 用户：

```powershell
irm https://claude.ai/install.ps1 | iex
```

**方式 B：包管理器（适合已有工具链的同学）**

macOS（Homebrew）：

```bash
brew install --cask claude-code
```

Windows（WinGet）：

```powershell
winget install Anthropic.ClaudeCode
```

Linux 还可用 `apt` / `dnf` / `apk`，详见官方 setup 文档。

**方式 C：npm（老牌方式，需要先装 Node.js 18+）**

```bash
npm install -g @anthropic-ai/claude-code
```

> ⚠️ 官方明确提醒：**不要用 `sudo npm install -g`**，否则后面会有一堆权限坑。

**预期结果**：安装完成后，在终端输入：

```bash
claude --version
```

能看到版本号（本文撰写时主线版本约 v2.1.92+），说明安装成功。

**常见问题**

| 现象 | 原因与解决 |
| --- | --- |
| `curl` 报 `403` 或 `syntax error near unexpected token '<'` | 多半是公司网络代理或镜像拦截了脚本，换个网络或参考 [Troubleshoot installation](https://code.claude.com/docs/en/troubleshoot-install) 找替代安装方式 |
| PowerShell 里提示 `'irm' is not recognized` | 说明你其实在 CMD 里，CMD 不认 `irm`，改用方式 A 里的 Windows CMD 命令 |
| npm 安装后提示全局目录不可写、无法自动更新 | 跑 `claude doctor` 看建议修复，或干脆改用原生安装 |
| 装完输 `claude` 提示 command not found | 新开一个终端窗口让 PATH 生效；仍不行检查 `~/.claude/` 是否生成 |

### 第三步：首次登录认证

装好后，任意目录下运行：

```bash
claude
```

首次启动会引导你登录。**订阅或 Console 账号**会自动打开浏览器，你在网页上确认授权后，终端这边就登录成功了。登录信息会保存在本机，之后不用重复登录。

- 想换账号或重新认证：在 Claude Code 会话内输入 `/login`。
- 想查看当前登录状态、剩余额度：输入 `/status` 或 `/login` 查看；Console 用户可在 console.anthropic.com 的 "Claude Code" 工作区集中看账单。

**预期结果**：终端出现 Claude Code 的提示符界面，顶部显示**版本号、当前模型（如 Sonnet 4.6）、当前工作目录**。底部是输入框，光标闪烁，等待你下指令。

**常见问题**

- 浏览器没自动弹出来：复制终端里打印的那段 URL，手动粘到浏览器打开。
- 登录后还是提示未认证：`/login` 重试一次，或检查系统时间是否准确（时间偏差大会导致鉴权失败）。

### 第四步：认识配置体系——决定 Claude Code"长什么样"

这是新手最容易跳过、却最值钱的一步。Claude Code 的所有可调参数（权限、环境变量、模型、MCP、钩子）都遵循一套**四层配置优先级**，从高到低：

```mermaid
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/` | — |

**新手记住两条就够：**

1. **个人习惯放 User，团队约定放 Project，临时实验放 Local**。
2. Claude Code 会**监听这些文件并热加载**——你改了 `settings.json`，不用重启，正在运行的会话立刻生效。

我们马上动手建一个最小项目配置。先为本教程创建工作目录：

```bash
mkdir ~/ledger && cd ~/ledger
```

然后直接在 Claude Code 会话里输入（这是你第一次"指挥"它）：

```text
帮我初始化一个 Python 项目骨架：创建 .claude/ 目录，
在里面生成 settings.local.json，预设只读权限白名单允许 ls、cat、python、pytest，
并忽略任何删除操作。
```

**预期结果**：Claude Code 会先列出它打算创建/修改的文件，征求你同意（按 `y` 批准），然后生成类似这样的 `.claude/settings.local.json`：

```json
{
  "permissions": {
    "allow": ["Bash(ls:*)", "Bash(cat:*)", "Bash(python:*)", "Bash(pytest:*)"],
    "deny": ["Bash(rm:*)"]
  }
}
```

### 第五步：用 CLAUDE.md 给项目装上"记忆"

光有配置还不够。你想让 Claude Code 每次都懂你的项目约定（用什么语言、怎么跑测试、命名规范），靠的是 `CLAUDE.md`。这是一份会被自动注入到每次对话上下文的"项目说明书"。

在会话里继续输入：

```text
生成一份 CLAUDE.md，内容包括：
- 项目名：命令行记账本 ledger
- 技术栈：Python 3，数据用 JSON 文件持久化，禁止引入第三方依赖
- 约定：所有金额以分为单位（整数）存储，展示时再除以 100；中文注释
- 测试：用 pytest，放 tests/ 目录
```

**预期结果**：项目根目录出现 `CLAUDE.md`。从此之后，每次在这个目录启动 `claude`，它都会"记得"这些约定——你不用每次重复说明。**常见问题**：发现 Claude 似乎没遵守 CLAUDE.md？检查文件是否在项目根、内容是否用祈使句写清"必须/禁止"，模糊的描述它会更自由发挥。

### 第六步：实战——驱动 Claude Code 造出记账本

现在进入高潮。**全程你不写一行代码，只负责"提需求 + 审核"。** 在会话里分步下指令（一次别贪多，让它一步步来，你看得清）：

**指令 1（搭骨架 + 数据层）**

```text
实现一个命令行记账本 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（测试）**

```text
为 add 和 summary 写 pytest 测试，用 tmp_path 隔离 data.json，
覆盖：正常记账、空数据汇总、金额单位转换（输入元转分存储）。
跑一遍 pytest 给我看结果。
```

**指令 3（细节打磨）**

```text
list 默认按日期倒序，加 --category 过滤；
summary 把分转成元展示并保留两位小数。
```

**预期结果**：Claude Code 会逐个创建 `ledger.py`、`tests/test_ledger.py`，并实际跑 `pytest` 把绿色"all passed"打印给你看。你甚至可以亲自验证一下：

```bash
python ledger.py add --amount 12.50 --category 餐饮 --note "午餐"
python ledger.py add --amount 30 --category 交通 --note "打车"
python ledger.py summary
```

终端应输出类似：

```text
餐饮: 12.50 元
交通: 30.00 元
总支出: 42.50 元
```

**常见问题**

- 它跑 `pytest` 报 `command not found`：让它装，指令"用 pip 在用户级安装 pytest 再重跑"。
- 它写的金额直接存了元：说明没遵守 CLAUDE.md 的单位约定，提醒它"按 CLAUDE.md，金额存分"，它会自我修正。
- 想让它别每次都问权限：按 `Shift+Tab` 在权限模式间循环切换（acceptEdits / plan / bypassPermissions 等），新手建议先用默认的逐条确认。

### 第七步：用 Git 收尾并理解代理循环

最后让 Claude Code 帮你把成果提交：

```text
git init，把 ledger.py、tests/、CLAUDE.md 加入版本控制，
注意别提交 data.json 和 .claude/settings.local.json，
然后写一条规范的中文 commit message 并提交。
```

它会自动生成 `.gitignore`、暂存文件、给出 commit message 供你确认。**这就是一次完整的代理循环**：理解目标 → 调用 Bash/Read/Write 工具 → 观察输出 → 决定下一步 → 达成目标。

---

## 实战案例：完整项目目录

跑完上面七步，你的 `~/ledger` 应长这样：

```mermaid
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 工作流。

**进阶练习（留作作业）**：

1. 让 Claude Code 加一个 `export --csv` 子命令，导出 CSV。
2. 加一个 `month YYYY-MM` 子命令，按月汇总。
3. 给记账本套一个最简 FastAPI HTTP 接口（开始接触 MCP 与外部集成的雏形）。

每做完一项就让它写测试、跑测试、提交一次 commit，形成"需求→实现→验证→提交"的肌肉记忆。

---

## 工作流程全景图

```mermaid
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
```

---

## 延伸阅读

- **官方快速上手**：[Quickstart - Claude Code Docs](https://code.claude.com/docs/en/quickstart) —— 本文安装与登录步骤的权威来源。
- **安装与系统配置详解**：[Setup](https://code.claude.com/docs/en/setup) —— npm 权限问题、自动更新通道、Linux 包管理器等。
- **配置体系全表**：[Settings](https://code.claude.com/docs/en/settings) —— 四层优先级、热加载、可用字段速查。
- **CLAUDE.md 与项目记忆**：[Memory](https://code.claude.com/docs/en/memory) —— 如何写一份让 AI 永久懂你项目的记忆文件。
- **新手最佳实践**：[Best practices](https://code.claude.com/docs/en/best-practices) —— 提示词写法、分步下指令的官方建议。
- **社区入门教程（2026）**：[Claude Code Tutorial for Beginners – Complete 2026 Guide](https://codewithmukesh.com/blog/claude-code-for-beginners/) —— 另一份视角的图文版新手指南。
- **从安装到首个项目（dev.to）**：[Claude Code Tutorial for Beginners 2026](https://dev.to/ayyazzafar/claude-code-tutorial-for-beginners-2026-from-installation-to-building-your-first-project-1lma) —— 补充案例。

---

## 训练营适用性评估

- **适合的训练营类型**：AI 编程启蒙营、企业研发提效入门营、高校"AI×软件工程"实训营、零基础转码训练营的第一课。
- **预计教学时长**：**90 分钟**（含动手）。讲授 25 分钟（心智模型 + 四层配置），动手 50 分钟（装→登→配→造 ledger），答疑 15 分钟。
- **难度定位**：⭐⭐（满分 5 星）。无需编程基础，但需要会开终端。
- **可扩展模块**：可无缝衔接到本系列后续课程——Skills 开发（把"记账"封装成技能）、MCP 服务器（把 ledger 暴露成模型工具）、Headless `-p` 模式（批量审计 ledger 记录）。
- **验收标准**：学员能独立跑通 `python ledger.py summary` 看到汇总输出，并完成一次 git commit，即视为通关。

---

## 参考来源

1. [Quickstart - Claude Code Docs](https://code.claude.com/docs/en/quickstart) — Anthropic 官方快速上手，安装、登录、首条指令、常用命令速查表。
2. [Settings - Claude Code Docs](https://code.claude.com/docs/en/settings) — 官方配置体系，Managed/User/Project/Local 四层优先级与文件位置表。
3. [Setup - Claude Code Docs](https://code.claude.com/docs/en/setup) — 安装方式（原生/Homebrew/WinGet/apt/dnf/apk/npm）、自动更新、权限问题排查。
4. [Best practices - Claude Code Docs](https://code.claude.com/docs/en/best-practices) — 官方新手最佳实践，分步下指令、让 AI 先探索代码等建议。
5. [Claude Code Tutorial for Beginners – Complete 2026 Guide](https://codewithmukesh.com/blog/claude-code-for-beginners/) — 社区图文版新手教程，覆盖 install、CLAUDE.md、首个项目。

> 本文由「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 等场景全覆盖。

![51学通信知识星球海报-扫码加入](https://wiki.500nian.com/images/zhixingqiu_qrcode.png)