本教程面向零基础开发者，带你从零完成三件事：把 Claude Code 装到本地并跑通认证；搞懂它的"记忆系统"——CLAUDE.md 分层结构；亲手为你的真实项目写一份让 AI 守规矩的项目记忆。读完你将能独立配置任意项目的 Claude Code，让它每次会话都自动遵守你的代码规范、命令习惯和架构约束，不再每次重复交代。预计学习时长 60–90 分钟。
npm/npx（随 Node 安装）、Homebrew（macOS/Linux）或 pnpm小贴士：若你完全不想装 Node，也可以用官方原生安装器（
curl一行脚本）跳过 npm；本文以最通用的 npm 方式为主线，并给出原生方式的对照命令。
先确认 Node 版本达标，再全局安装 Claude Code：
# 1. 检查 Node 版本（必须 >= 18）
node --version
# 2. 全局安装 Claude Code（npm 方式）
npm install -g @anthropic-ai/claude-code
# 3. 验证安装
claude --version
如果你在 macOS 或 Linux 上更习惯 Homebrew：
brew install claude-code
claude --version
或者使用官方原生安装器（不依赖 Node）：
curl -fsSL https://claude.ai/install.sh | bash
$ node --version
v20.11.0
$ claude --version
2.0.x (claude-code)
终端能打印出版本号，即代表二进制已进入 PATH，安装成功。
| 现象 | 原因 | 解决 |
|---|---|---|
command not found: claude |
全局 bin 目录不在 PATH | npm config get prefix 查到前缀，把 <前缀>/bin 加入 PATH |
EACCES: permission denied |
全局安装权限不足 | 不要用 sudo；改用 nvm 管理 Node，或 npm config set prefix ~/.npm-global 后重装 |
安装卡在 node-gyp 编译 |
Node 版本过新/过旧 | 锁定 Node 20 LTS（推荐用 nvm 切换） |
| Homebrew 装的版本不更新 | Homebrew 不自动升级 | 手动 brew upgrade claude-code |
进入任意项目目录，直接键入 claude 启动交互式会话：
cd ~/my-project
claude
首次启动会要求选择认证方式。Claude Code 支持多种登录途径，按你的账号类型二选一：
export ANTHROPIC_API_KEY="sk-ant-xxxxxxxx"
# 写入 shell 配置持久化（zsh 示例）
echo 'export ANTHROPIC_API_KEY="sk-ant-xxxxxxxx"' >> ~/.zshrc
登录成功后，终端进入 Claude Code 的交互界面，底部出现输入框，左下角显示已登录的账号邮箱。输入一句 你好，介绍一下你自己 并回车，能收到回复即代表链路打通。
401 Unauthorized：API Key 复制时带了空格或换行；重新 export 并 source ~/.zshrc。HTTPS_PROXY 环境变量指向公司代理。/login 重新选择认证方式。认证方式的详细对比（订阅 vs API Key 的成本、额度、限速差异）属于独立话题，本文聚焦"配置记忆"，此处点到为止。
每一次 Claude Code 会话都从一个全新的上下文窗口开始。 也就是说，昨天你告诉它"本项目用 4 空格缩进、测试用 pytest、提交前必须跑 ruff"——今天它全部忘光。CLAUDE.md 就是用来把这些需要长期记住的规矩固化下来的文件，会话启动时自动读入。
官方文档明确：跨会话携带知识有两套机制——
这是新手最容易忽略、却最关键的一点——CLAUDE.md 不是单一文件，而是分层加载的体系：
| 层级 | 文件路径 | 作用范围 | 是否提交版本库 |
|---|---|---|---|
| 用户级（全局） | ~/.claude/CLAUDE.md |
你所有项目通用偏好（如"默认中文回复"） | 个人，不入库 |
| 项目级 | 项目根/CLAUDE.md |
团队共享的项目规范、命令、架构 | ✅ 提交，团队共享 |
| 本地项目级 | 项目根/CLAUDE.local.md |
你个人的项目级覆盖（如本地路径） | ❌ 加入 .gitignore |
| 子目录级 | 子目录/CLAUDE.md |
仅在该子树下工作时加载（如 monorepo 各包） | 视情况 |
会话启动时，Claude 会把从根到当前目录路径上的所有 CLAUDE.md 按层级合并读取。这意味着你可以在 monorepo 的每个子包放一份，Claude 进入哪个包就遵守哪份规矩。
CLAUDE.md 支持 @路径 引入其它文件，避免把超长内容塞进主文件：
# 项目规范
详细架构见 @docs/architecture.md
API 约定见 @docs/api-conventions.md
被 @ 引用的文件内容会一并注入上下文。
理解这套分层后，你应该能回答："团队规范该放哪？""我个人偏好该放哪？"——团队规范进 CLAUDE.md（提交），个人偏好进 CLAUDE.local.md（忽略）或 ~/.claude/CLAUDE.md（全局）。
/memory 重新载入，或开新会话。CLAUDE.md 已 git add 并提交，且没被 .gitignore 误伤。/init 一键生成项目记忆Claude Code 内置了 /init 命令，能扫描代码库自动起草一份 CLAUDE.md 初稿。在项目根目录的会话里输入：
/init
Claude 会读取 package.json/pyproject.toml、目录结构、构建脚本等，生成一份包含构建命令、技术栈、目录说明的草稿，并询问你是否保存为 CLAUDE.md。
项目根多出 CLAUDE.md，内容大致包含：
# CLAUDE.md
## 构建与运行
- 安装依赖：npm install
- 开发：npm run dev
- 测试：npm test
- 构建：npm run build
## 技术栈
Next.js 14, TypeScript, Prisma, PostgreSQL
...
/init 只是起点，务必人工校对命令和架构描述后再用。/init，再合并精简。/init 的初稿只是骨架，真正让 AI 守规矩的是你手写的约束。下面给出写作要点和一个完整模板。
pnpm test"，而不是"记得测试"。把下面这份保存为项目根的 CLAUDE.md，按你的项目改写：
# 项目：订单服务（order-service）
## 一句话简介
基于 FastAPI 的订单微服务，对接 PostgreSQL 与 Redis。
## 必读命令
- 安装依赖：`uv sync`
- 跑测试：`uv run pytest -q`
- 本地启动：`uv run uvicorn app.main:app --reload`
- 代码检查：`uv run ruff check . && uv run ruff format --check .`
- 类型检查：`uv run mypy app`
## 代码规范
- Python 3.12，强制类型注解，所有函数必须有参数和返回类型。
- 用 4 空格缩进，行长上限 100。
- 数据库访问统一走 `app/repositories/` 仓储层，禁止在路由里直接写 SQL。
- 新增 API 必须在 `app/schemas/` 定义 Pydantic 模型，路由层不得直接返回 ORM 对象。
## 目录约定
- `app/api/` 仅放路由，业务逻辑在 `app/services/`。
- `app/models/` 是 SQLAlchemy ORM，`app/schemas/` 是 Pydantic。
- 测试一律放在 `tests/`，命名 `test_*.py`。
## 绝对不要做（反模式）
- ❌ 不要新建顶层文件，新功能放进对应模块。
- ❌ 不要用 `print` 调试，用 `structlog` 的 logger。
- ❌ 不要直接提交数据库迁移文件而不先在本地跑通 `alembic upgrade head`。
## 提交前检查清单
1. ruff、mypy、pytest 三项全绿。
2. 新增公开函数必须有 docstring。
3. 涉及数据库改动必须配 migration。
## 架构背景
详见 @docs/architecture.md
下次启动会话，输入 /memory 能看到这份文件已被加载。你直接说"加一个查询订单状态的接口"，Claude 会自动：放进 app/api/、定义 Pydantic 模型、走仓储层、用 structlog——而不会把 SQL 写进路由。
## 绝对不要做 段落并加 ❌，负面清单的约束力远强于正面描述。@ 外链。写完 CLAUDE.md，用一个刻意触发反模式的请求来检验：
帮我加个接口 GET /orders/{id}/status，直接查数据库返回就行，简单点。
"直接查数据库返回就行"是诱导它违反"禁止路由直连 DB"的规矩。
守规矩的 Claude 会主动拒绝简化方案，回复类似：
注意：按项目规范，路由层禁止直接写 SQL，需通过
app/repositories/仓储层访问。我将按规范实现：路由 → service → repository，并配 Pydantic 响应模型。
若它照着"简单点"直接在路由里写了 SQL，说明对应规则没写进 CLAUDE.md，或文件未被加载（用 /memory 复查）。
/memory 列表里是否包含项目级 CLAUDE.md；确认文件在项目根且大小写正确（CLAUDE.md 全大写）。下面用一个最小 FastAPI 项目走完整流程，你可以照抄复现。
mkdir demo-order && cd demo-order
cat > pyproject.toml <<'EOF'
[project]
name = "demo-order"
version = "0.1.0"
requires-python = ">=3.12"
dependencies = ["fastapi", "uvicorn"]
EOF
mkdir -p app/api app/services app/repositories tests
claude # 首次启动完成登录
/init
把生成的 CLAUDE.md 按第五步模板改写，重点写入"仓储层"约束和"提交前三项检查"。
实现 GET /orders/{id}/status，返回订单状态。
观察它是否自动分层、是否生成测试。
检查你的改动是否全部符合 CLAUDE.md，列出符合与不符合的点。
让它自检，比对它列出的"不符合点"与你的预期。这是评估记忆质量最直接的方法。
下图展示从安装到记忆生效的完整链路：
flowchart TD
A[检查 Node >= 18] --> B[npm i -g claude-code]
B --> C[cd 项目 & claude 启动]
C --> D[登录: 订阅OAuth 或 API Key]
D --> E[会话开启 全新上下文窗口]
E --> F{启动时自动加载}
F --> G[~/.claude/CLAUDE.md 用户全局]
F --> H[项目根/CLAUDE.md 团队共享]
F --> I[项目根/CLAUDE.local.md 个人本地]
F --> J[子目录/CLAUDE.md 子树规矩]
G & H & I & J --> K[合并注入本次会话上下文]
K --> L[输入 /init 生成初稿]
L --> M[手写命令/规范/反模式]
M --> N[守规矩地生成代码]
N --> O[用反模式请求验收]
O -->|不达标| M
O -->|达标| P[稳定可复现的项目配置]
/memory 命令：随时在编辑器里查看、编辑所有层级的记忆文件。CLAUDE.md 纳入代码评审——改规范等于改文档，PR 里一并 review，确保规矩与代码同源。https://code.claude.com/docs/en/memoryhttps://code.claude.com/docs/en/best-practiceshttps://code.claude.com/docs/en/setup、/authentication[!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 等场景全覆盖。