## 概述 本教程面向**零基础开发者**，带你从零完成三件事：把 Claude Code 装到本地并跑通认证；搞懂它的"记忆系统"——`CLAUDE.md` 分层结构；亲手为你的真实项目写一份让 AI 守规矩的项目记忆。读完你将能独立配置任意项目的 Claude Code，让它每次会话都自动遵守你的代码规范、命令习惯和架构约束，不再每次重复交代。预计学习时长 60–90 分钟。 --- ## 前置条件 - 一台 macOS、Linux 或 Windows（WSL2）机器，能联网 - **Node.js 18 或更高版本**（Claude Code 以 npm 包分发，强依赖 Node 运行时） - 一个包管理器：`npm`/`npx`（随 Node 安装）、`Homebrew`（macOS/Linux）或 `pnpm` - 一个 Anthropic 账号——可以是 **Claude Pro/Max 订阅**，也可以是 **Anthropic Console 的 API Key**（按量计费） - 一个用来练手的真实项目目录（没有也行，教程末尾会带你建一个最小示例） > 小贴士：若你完全不想装 Node，也可以用官方原生安装器（`curl` 一行脚本）跳过 npm；本文以最通用的 npm 方式为主线，并给出原生方式的对照命令。 --- ## 第一步：环境检查与安装 ### 操作说明 先确认 Node 版本达标，再全局安装 Claude Code： ```bash # 1. 检查 Node 版本（必须 >= 18） node --version # 2. 全局安装 Claude Code（npm 方式） npm install -g @anthropic-ai/claude-code # 3. 验证安装 claude --version ``` 如果你在 macOS 或 Linux 上更习惯 Homebrew： ```bash brew install claude-code claude --version ``` 或者使用官方原生安装器（不依赖 Node）： ```bash curl -fsSL https://claude.ai/install.sh | bash ``` ### 预期结果 ```text $ 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` 启动交互式会话： ```bash cd ~/my-project claude ``` 首次启动会要求选择认证方式。Claude Code 支持多种登录途径，按你的账号类型二选一： - **Claude 订阅用户（Pro/Max）**：选浏览器登录（Browser OAuth），会弹出浏览器完成 Anthropic 账号授权，回终端即登录成功。 - **API Key 用户**：在 [Anthropic Console](https://console.anthropic.com/) 创建 Key，设为环境变量： ```bash export ANTHROPIC_API_KEY="sk-ant-xxxxxxxx" # 写入 shell 配置持久化（zsh 示例） echo 'export ANTHROPIC_API_KEY="sk-ant-xxxxxxxx"' >> ~/.zshrc ``` ### 预期结果 登录成功后，终端进入 Claude Code 的交互界面，底部出现输入框，左下角显示已登录的账号邮箱。输入一句 `你好，介绍一下你自己` 并回车，能收到回复即代表链路打通。 ### 常见问题与解决 - **浏览器没自动弹出**：复制终端里打印的 URL 手动粘贴到浏览器。 - **`401 Unauthorized`**：API Key 复制时带了空格或换行；重新 `export` 并 `source ~/.zshrc`。 - **公司代理/防火墙拦截**：设置 `HTTPS_PROXY` 环境变量指向公司代理。 - **想切换账号**：在会话中输入 `/login` 重新选择认证方式。 > 认证方式的详细对比（订阅 vs API Key 的成本、额度、限速差异）属于独立话题，本文聚焦"配置记忆"，此处点到为止。 --- ## 第三步：理解 CLAUDE.md 记忆系统（核心概念） ### 为什么需要 CLAUDE.md **每一次 Claude Code 会话都从一个全新的上下文窗口开始。** 也就是说，昨天你告诉它"本项目用 4 空格缩进、测试用 `pytest`、提交前必须跑 `ruff`"——今天它全部忘光。`CLAUDE.md` 就是用来把这些**需要长期记住的规矩**固化下来的文件，会话启动时自动读入。 官方文档明确：跨会话携带知识有两套机制—— 1. **CLAUDE.md 文件**：你亲手写的指令（本文重点）。 2. **自动记忆（auto memory）**：Claude 在协作中自动沉淀的学习笔记（进阶，可按需开启）。 ### CLAUDE.md 的四层分层结构 这是新手最容易忽略、却最关键的一点——`CLAUDE.md` 不是单一文件，而是**分层加载**的体系： | 层级 | 文件路径 | 作用范围 | 是否提交版本库 | |---|---|---|---| | **用户级（全局）** | `~/.claude/CLAUDE.md` | 你所有项目通用偏好（如"默认中文回复"） | 个人，不入库 | | **项目级** | `项目根/CLAUDE.md` | 团队共享的项目规范、命令、架构 | ✅ 提交，团队共享 | | **本地项目级** | `项目根/CLAUDE.local.md` | 你个人的项目级覆盖（如本地路径） | ❌ 加入 `.gitignore` | | **子目录级** | `子目录/CLAUDE.md` | 仅在该子树下工作时加载（如 monorepo 各包） | 视情况 | 会话启动时，Claude 会把**从根到当前目录路径上**的所有 `CLAUDE.md` 按层级合并读取。这意味着你可以在 monorepo 的每个子包放一份，Claude 进入哪个包就遵守哪份规矩。 ### @导入语法 `CLAUDE.md` 支持 `@路径` 引入其它文件，避免把超长内容塞进主文件： ```markdown # 项目规范 详细架构见 @docs/architecture.md API 约定见 @docs/api-conventions.md ``` 被 `@` 引用的文件内容会一并注入上下文。 ### 预期结果 理解这套分层后，你应该能回答："团队规范该放哪？""我个人偏好该放哪？"——团队规范进 `CLAUDE.md`（提交），个人偏好进 `CLAUDE.local.md`（忽略）或 `~/.claude/CLAUDE.md`（全局）。 ### 常见问题与解决 - **改了 CLAUDE.md 不生效**：当前会话不会热重载；输入 `/memory` 重新载入，或开新会话。 - **团队成员 clone 后没规矩**：确认 `CLAUDE.md` 已 `git add` 并提交，且没被 `.gitignore` 误伤。 --- ## 第四步：用 `/init` 一键生成项目记忆 ### 操作说明 Claude Code 内置了 `/init` 命令，能扫描代码库自动起草一份 `CLAUDE.md` 初稿。在项目根目录的会话里输入： ``` /init ``` Claude 会读取 `package.json`/`pyproject.toml`、目录结构、构建脚本等，生成一份包含构建命令、技术栈、目录说明的草稿，并询问你是否保存为 `CLAUDE.md`。 ### 预期结果 项目根多出 `CLAUDE.md`，内容大致包含： ```markdown # CLAUDE.md ## 构建与运行 - 安装依赖：npm install - 开发：npm run dev - 测试：npm test - 构建：npm run build ## 技术栈 Next.js 14, TypeScript, Prisma, PostgreSQL ... ``` ### 常见问题与解决 - **生成的初稿不准**：`/init` 只是起点，务必人工校对命令和架构描述后再用。 - **大型 monorepo 扫描慢**：先在子包目录运行 `/init`，再合并精简。 --- ## 第五步：手写一份高质量 CLAUDE.md `/init` 的初稿只是骨架，真正让 AI 守规矩的是你**手写的约束**。下面给出写作要点和一个完整模板。 ### 写作四原则 1. **写命令，别写形容词**——给"跑测试用 `pnpm test`"，而不是"记得测试"。 2. **写反模式（不要做什么）**——AI 最容易在边界处犯错，明确禁止比正面鼓励更有效。 3. **保持精简**——它每次会话都全文读入，越长越费 token、越容易稀释重点。 4. **随项目演进**——架构变了、命令换了，及时更新。 ### 完整模板（Python 后端项目示例） 把下面这份保存为项目根的 `CLAUDE.md`，按你的项目改写： ```markdown # 项目：订单服务（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 写进路由。 ### 常见问题与解决 - **AI 仍违反规范**：把禁止项从正文挪到独立 `## 绝对不要做` 段落并加 ❌，负面清单的约束力远强于正面描述。 - **规则太多导致响应变慢**：精简到 50 行以内，长内容用 `@` 外链。 --- ## 第六步：验证 Claude 是否真的守规矩 ### 操作说明 写完 `CLAUDE.md`，用一个**刻意触发反模式**的请求来检验： ``` 帮我加个接口 GET /orders/{id}/status，直接查数据库返回就行，简单点。 ``` "直接查数据库返回就行"是诱导它违反"禁止路由直连 DB"的规矩。 ### 预期结果 守规矩的 Claude 会**主动拒绝**简化方案，回复类似： > 注意：按项目规范，路由层禁止直接写 SQL，需通过 `app/repositories/` 仓储层访问。我将按规范实现：路由 → service → repository，并配 Pydantic 响应模型。 若它照着"简单点"直接在路由里写了 SQL，说明对应规则没写进 `CLAUDE.md`，或文件未被加载（用 `/memory` 复查）。 ### 常见问题与解决 - **验证不通过**：检查 `/memory` 列表里是否包含项目级 `CLAUDE.md`；确认文件在项目根且大小写正确（`CLAUDE.md` 全大写）。 - **想临时关掉某条规矩**：在会话里口头覆盖即可，无需改文件；要永久关再编辑文件。 --- ## 实战案例：30 分钟为一个真实项目配通记忆 下面用一个最小 FastAPI 项目走完整流程，你可以照抄复现。 ### 1. 建项目骨架 ```bash 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 ``` ### 2. 安装并启动 Claude Code ```bash claude # 首次启动完成登录 ``` ### 3. 在会话内生成并打磨记忆 ``` /init ``` 把生成的 `CLAUDE.md` 按第五步模板改写，重点写入"仓储层"约束和"提交前三项检查"。 ### 4. 让它实现第一个功能 ``` 实现 GET /orders/{id}/status，返回订单状态。 ``` 观察它是否自动分层、是否生成测试。 ### 5. 验收 ``` 检查你的改动是否全部符合 CLAUDE.md，列出符合与不符合的点。 ``` 让它**自检**，比对它列出的"不符合点"与你的预期。这是评估记忆质量最直接的方法。 --- ## 工作流程总览 下图展示从安装到记忆生效的完整链路： ```mermaid 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[稳定可复现的项目配置] ``` --- ## 进阶：自动记忆与团队协作 - **自动记忆（auto memory）**：在 settings 中开启后，Claude 会在协作中把"学到的"项目知识自动沉淀，跨会话累积。适合大型项目渐进式沉淀，但要定期审查避免噪音。 - **`/memory` 命令**：随时在编辑器里查看、编辑所有层级的记忆文件。 - **团队落地**：把 `CLAUDE.md` 纳入代码评审——改规范等于改文档，PR 里一并 review，确保规矩与代码同源。 --- ## 延伸阅读 - 官方记忆文档（最权威）：`https://code.claude.com/docs/en/memory` - 官方最佳实践：`https://code.claude.com/docs/en/best-practices` - 官方安装与认证：`https://code.claude.com/docs/en/setup`、`/authentication` - 进阶主题（后续轮次）：Skills 开发、MCP 服务器、Hooks 与自动化、上下文管理与性能优化 --- ## 参考来源 1. [How Claude remembers your project — Claude Code Docs](https://code.claude.com/docs/en/memory) — 官方对 CLAUDE.md 分层记忆与 auto memory 的权威说明 2. [Best practices for Claude Code — Claude Code Docs](https://code.claude.com/docs/en/best-practices) — 官方从环境配置到规模化使用的最佳实践 3. [Advanced setup / Authentication — Claude Code Docs](https://code.claude.com/docs/en/setup) — 安装方式（npm/Homebrew/原生）与多种认证途径 4. [CLAUDE.md Best Practices: Project Memory for Claude Code — Nekter](https://www.nekter.ai/blog/2026-04-16-claude-md-best-practices-project-memory) — CLAUDE.md 内容结构与写作要点实战总结 5. [Claude Code CLAUDE.md Guide: Project Instructions That Work — JD Hodges](https://www.jdhodges.com/blog/claude-code-claudemd-project-instructions/) — 项目指令落地经验与反例 --- ## 训练营适用性评估 - **适合训练营类型**：Claude Code / AI 编程入门营、企业 AI 研效训练营第一期、"AI 代码助手落地"工作坊。本主题是所有后续进阶（Skills、MCP、Hooks）的地基，建议作为**第一天的必修课**。 - **预计教学时长**：讲授 45 分钟 + 动手实验 45 分钟（含为真实项目配通 CLAUDE.md 并完成验收）。 - **学员产出物**：一个配置完整、经反模式验收通过的项目记忆文件，可作为后续课程持续使用的沙盒项目。 - **前置与衔接**：本课之前无需任何 Claude Code 经验；之后自然衔接"权限驯服""Agent 循环""Skills 开发"等专题。 > [!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 等场景全覆盖。