Claude Code 完全指南：从零开始掌握 AI 编程助手

本指南适合对象：完全零基础的初学者、希望系统学习 Claude Code 的开发者、想要最大化利用 AI 辅助编程效率的技术人员。阅读时间：预计 20-30 分钟完整阅读，实操学习 2-3 天。文档版本：基于 Claude Code v2.1.x（2026年5月）目录Claude Code 完全指南：从零开始掌握 AI 编程助手第一章：什么是 Claude Code？——写在最前面的话1.1 一个真实的场景1.2 Claude Code 的本质定义1.3 Claude Code 能做什么？1.4 一个关键概念：智能体模式（Agentic Mode）1.5 Claude Code 的核心数据第二章：Claude Code 的诞生背景与发展历程2.1 为什么需要 Claude Code？2.2 发展历程时间线2.3 Claude Code 的设计哲学第三章：Claude Code vs 其他 AI 编程工具大比拼3.1 主流 AI 编程工具概览3.2 详细对比分析Claude Code vs GitHub CopilotClaude Code vs CursorClaude Code vs ChatGPT3.3 选择建议第四章：环境准备与安装配置4.1 系统要求4.2 安装 Claude Code4.3 登录认证4.4 订阅计划对比4.5 IDE 集成安装第五章：第一次启动 Claude Code——Hello World 实战5.1 启动 Claude Code5.2 你的第一个任务5.3 与 Claude Code 交互的基本规则5.4 退出和保存会话第六章：核心概念深度解析6.1 工具系统（Tools）6.2 上下文窗口（Context Window）6.3 项目感知（Project Awareness）6.4 记忆系统第七章：CLAUDE.md 文件——让 Claude 了解你的项目7.1 什么是 CLAUDE.md？7.2 快速生成 CLAUDE.md7.3 CLAUDE.md 的结构重要注意事项第八章：斜杠命令（Slash Commands）完全手册8.1 什么是斜杠命令？8.2 会话管理命令/clear — 清空上下文/compact — 压缩上下文/branch — 分支会话/rewind — 回滚到之前状态/history — 查看会话历史8.3 设置与配置命令/init — 初始化项目/model — 切换 AI 模型/memory — 管理记忆/permissions — 权限设置/cost — 查看费用/usage — 查看使用统计8.4 代码质量命令/simplify — 简化代码/review — 代码审查/test — 运行测试8.5 项目管理命令/doctor — 项目健康检查/batch — 批量任务/release-notes — 生成发布说明/team-onboarding — 生成团队入职指南8.6 MCP 相关命令8.7 自定义斜杠命令第九章：上下文管理与记忆系统9.1 理解 Claude Code 的信息架构9.2 高效的文件引用方式9.3 在会话中管理上下文的策略9.4 自动记忆系统详解9.5 多会话状态保持第十章：Plan Mode（计划模式）——让 AI 先思考后行动10.1 为什么需要 Plan Mode？10.2 如何使用 Plan Mode10.3 Plan Mode 实战案例10.4 PRD（产品需求文档）驱动开发第十一章：MCP（模型上下文协议）——无限扩展 Claude Code 的能力11.1 什么是 MCP？11.2 MCP 的工作原理11.3 安装 MCP 服务器11.4 MCP 的 Scope（作用域）11.5 实战：使用 GitHub MCP11.6 实战：使用数据库 MCP11.7 推荐的 MCP 服务器清单11.8 MCP 工具搜索（懒加载优化）第十二章：Hooks（钩子）系统——自动化你的工作流12.1 什么是 Hooks？12.2 Hooks 的事件类型12.3 Hooks 的配置方式12.4 实用 Hooks 配置案例12.5 完整的 settings.json 配置示例12.6 使用 /less-permission-prompts 减少权限提示第十三章：Skills（技能）系统——可复用的 AI 能力模块13.1 Skills 是什么？13.2 Skills 的文件结构13.3 SKILL.md 的结构XSS 防护身份验证检查IDOR（不安全的直接对象引用）输出格式高风险操作的处理删除列/表修改列类型迁移前的检查清单第十四章：子代理与多智能体协作14.1 什么是子代理？14.2 为什么需要多代理？14.3 多代理工作流的实际使用14.4 代理团队（Agent Teams）14.5 自定义子代理（Subagents）第十五章：权限管理与安全配置15.1 Claude Code 的权限模型15.2 权限配置文件15.3 权限模式（Permission Mode）15.4 CI/CD 环境中的安全配置15.5 敏感信息保护15.6 审计日志第十六章：实战项目案例——用 Claude Code 构建一个完整应用16.1 项目目标16.2 第一步：初始化项目16.3 第二步：设置 CLAUDE.md16.4 第三步：设计数据库16.5 第四步：实现认证功能16.6 第五步：让 Claude 自己验证16.7 第六步：完善文章功能16.8 完整项目回顾第十七章：高级技巧与最佳实践17.1 提示词工程（Prompt Engineering）17.2 高效的调试工作流17.3 Git 集成最佳实践17.4 代码审查自动化17.5 测试驱动开发（TDD）与 Claude Code17.6 多语言项目处理第十八章：性能优化与成本控制18.1 理解 Token 计费18.2 降低成本的策略18.3 监控使用量18.4 Context Window 的高效利用第十九章：常见问题与故障排除19.1 安装相关问题19.2 认证相关问题19.3 上下文和性能问题19.4 MCP 连接问题19.5 代码质量问题19.6 Windows 特有问题第二十章：学习路径与进阶资源20.1 初学者学习路径（第1-2周）20.2 中级使用者学习路径（第2-4周）20.3 高级使用者学习路径（第4-8周）20.4 推荐学习资源20.5 构建自己的 Claude Code 工作流结语：拥抱 AI 辅助开发时代附录：常用命令速查表会话管理配置与设置监控与诊断MCP 管理代码质量CLI 启动参数附录：CLAUDE.md 模板禁止事项重要注意事项a/a第一章：什么是 Claude Code？——写在最前面的话1.1 一个真实的场景想象这样一个场景：你是一名开发者，接到了一个任务——需要在一个有 50 个文件、3000 行代码的 Node.js 项目里，把所有的数据库调用从同步改成异步，同时不破坏任何现有的业务逻辑，还要补充对应的单元测试。传统方式：打开 IDE，一个文件一个文件地看，一处一处地改，改完了还要手动跑测试，花了整整两天。使用 Claude Code 之后：打开终端，输入：claude "把这个项目里所有的数据库调用改成 async/await 形式，补充对应的测试，确保所有测试通过"然后你去泡了杯咖啡，回来的时候——Claude Code 已经：自动读取了所有相关文件分析了项目结构和依赖关系制定了修改计划逐文件进行了改造运行了测试并修复了问题提交了一个干净的 Git commit这不是科幻。这就是Claude Code正在做的事情。1.2 Claude Code 的本质定义Claude Code是 Anthropic 公司开发的终端原生 AI 编程助手，它建立在 Claude 大语言模型之上（Claude 4 系列），能够以智能体（Agentic）方式运行，主动读取代码、执行命令、修改文件，完成复杂的多步骤编程任务。与传统的代码补全工具（如早期的 GitHub Copilot）不同，Claude Code 不是在你打字的时候给你建议几行代码——它是一个能独立思考、主动行动、理解整个项目全貌的AI 软件工程师。1.3 Claude Code 能做什么？让我们具体列举一下 Claude Code 的核心能力：代码理解与分析读取并理解整个项目的文件结构分析代码依赖关系和调用链识别代码中的 bug、性能问题、安全漏洞解释复杂代码逻辑，用人话说清楚代码生成与修改根据自然语言描述生成新功能重构现有代码（不改变行为，优化结构）批量修改多个文件补充注释和文档执行与验证运行 shell 命令（git、npm、pip 等）执行测试并根据测试结果自动修复运行构建流程搜索文件内容（grep、find 等）项目管理创建新项目脚手架管理 Git 操作（commit、branch、merge）读写配置文件生成项目文档1.4 一个关键概念：智能体模式（Agentic Mode）这是理解 Claude Code 的关键。普通 AI 聊天工具（如 ChatGPT 网页版）的工作模式是：你说 → AI 回答 → 你说 → AI 回答 → ...（永远是一问一答）Claude Code 的工作模式是：你下达任务 → AI 制定计划 → AI 自主执行步骤1 → AI 自主执行步骤2 → AI 自主执行步骤N → AI 报告结果在这个过程中，Claude Code 会：主动决定需要读哪些文件主动决定需要执行哪些命令根据执行结果调整策略循环迭代直到任务完成这就像你雇了一个实习生，告诉他"帮我把这个功能做出来"，然后他自己想办法去做——而不是需要你每一步都告诉他具体怎么操作。1.5 Claude Code 的核心数据发布时间：2025年2月测试版，2025年5月正式发布上下文窗口：200,000 tokens（相当于约 15 万汉字）年化营收：截止2025年11月已达10亿美元运行平台：macOS、Windows、Linux、VS Code 插件、JetBrains 插件、Web 界面、iOS Appa/a第二章：Claude Code 的诞生背景与发展历程2.1 为什么需要 Claude Code？要理解 Claude Code 的价值，我们先来看看它解决了什么问题。问题一：AI 聊天工具的"复制粘贴地狱"在 Claude Code 出现之前，开发者使用 AI 编程的典型工作流是：把代码复制到 ChatGPT/Claude 网页让 AI 修改把修改后的代码复制回 IDE发现问题，重复以上步骤这种"复制粘贴地狱"极其低效，尤其是当你需要修改多个文件的时候。问题二：IDE 插件的上下文限制GitHub Copilot 等 IDE 插件虽然方便，但它们主要做的是"代码补全"——根据当前光标位置预测你要写什么。它们无法理解整个项目，无法主动行动，无法自己跑测试。问题三：大型任务的协调成本对于"重构整个认证系统"这样的大型任务，即使有 AI 辅助，人工协调的成本依然很高——你需要把任务拆解，逐步指导 AI，检查每一步的结果。Claude Code 的出现正是为了解决这些问题：让 AI 直接在你的开发环境中工作，自主完成复杂任务。2.2 发展历程时间线2025年2月 ── Claude Code 内测版发布，仅限邀请制 2025年5月 ── Claude Code 正式公开发布（GA） 2025年8月 ── 引入 MCP（模型上下文协议）深度集成 2025年11月 ── 年化营收突破10亿美元，VS Code 插件发布 2025年12月 ── 引入 Skills（技能）系统 2026年2月 ── Sonnet 4.6 成为默认模型，支持 100万 token 上下文（测试版） 2026年4月 ── 多代理协作（Agent Teams）功能发布 2026年5月 ── v2.1.131 版本，目前最新版2.3 Claude Code 的设计哲学Anthropic 在设计 Claude Code 时遵循了几个核心原则：原则一：终端优先（Terminal-First）选择终端而不是 IDE 插件作为主要界面，是因为终端是开发者最通用的工作环境，它不依赖特定的 IDE，可以在任何地方运行，而且天然地支持脚本化和自动化。原则二：可信赖的大上下文（Trusted Large Context）Claude Code 会读取你的整个项目，这不是噱头——它需要大上下文才能理解你的项目结构、依赖关系、编码风格，从而做出正确的决定。原则三：人类监督（Human Oversight）Claude Code 在执行"危险操作"（如删除文件、执行 shell 命令）前会请求许可，不会默默地做可能造成损失的事情。原则四：透明可审计（Transparent Auditable）Claude Code 的所有操作都会显示在终端里，你可以随时看到它在做什么、为什么这么做。a/a第三章：Claude Code vs 其他 AI 编程工具大比拼3.1 主流 AI 编程工具概览目前市场上主要的 AI 编程工具有：工具类型主要界面核心优势Claude Code终端 AI 助手终端/CLI大上下文、智能体模式、理解整个项目GitHub CopilotIDE 插件VS Code/JetBrains代码补全、低门槛、IDE 集成CursorAI IDE独立编辑器VS Code 体验、多文件编辑ChatGPT/GPT-4对话 AI网页/API头脑风暴、概念探索ClineVS Code 插件VS Code开源、可定制Aider终端工具终端/CLI开源、轻量3.2 详细对比分析Claude Code vs GitHub CopilotGitHub Copilot 的优势：安装简单，直接在 VS Code/JetBrains 中使用实时代码补全，打字时就能看到建议与 GitHub 生态深度集成价格相对较低（个人版约 $10/月）Claude Code 的优势：上下文窗口是 Copilot 的 25 倍以上（200K vs ~8K）可以理解并修改整个项目，而不只是当前文件可以自主运行测试、执行命令更擅长复杂推理和架构决策结论：两者并不对立。很多开发者同时使用两者——Copilot 负责日常打字补全，Claude Code 负责复杂任务。Claude Code vs CursorCursor 的优势：完整的 IDE 体验（VS Code 的超集）对不熟悉终端的开发者更友好内置聊天、代码补全、多文件编辑Claude Code 的优势：不绑定特定 IDE，任何终端都能用智能体模式更强（可以自主完成更复杂的任务）可以通过 MCP 连接各种外部工具和服务更适合服务器、CI/CD 等无 GUI 环境结论：如果你喜欢 IDE 操作，Cursor 是好选择；如果你是终端党，或者需要在服务器/CI 环境中使用 AI，Claude Code 更合适。Claude Code vs ChatGPTChatGPT 的优势：无需安装，打开浏览器就能用适合探索性的问答和学习支持图片、文件上传Claude Code 的优势：直接在你的项目里工作，无需复制粘贴可以自主执行多步骤任务可以读取整个项目目录结论：想聊天讨论方案用 ChatGPT，想让 AI 真正干活用 Claude Code。3.3 选择建议刚入门，想体验 AI 编程：先从 GitHub Copilot 开始，门槛最低中级开发者，想提升效率：Claude Code + GitHub Copilot 组合高级开发者，处理大型项目：Claude Code 是核心工具喜欢 IDE 界面，不想用终端：Cursor 是最好的替代追求开源和可定制性：考虑 Cline 或 Aidera/a第四章：环境准备与安装配置4.1 系统要求在安装 Claude Code 之前，请确认你的环境满足以下要求：操作系统：macOS 10.15 (Catalina) 或更高版本Windows 10/11（需要 WSL2 或 PowerShell）Linux（Ubuntu 18.04+ 或其他主流发行版）必要依赖：Node.js 18 或更高版本（这是最重要的依赖）npm（Node.js 自带）Git（用于版本控制操作）网络连接（需要访问 Anthropic API）检查 Node.js 版本：node --version # 输出应该是 v18.x.x 或更高 npm --version # 输出应该是 9.x.x 或更高如果没有安装 Node.js，可以通过以下方式安装：macOS（推荐使用 Homebrew）：# 先安装 Homebrew（如果没有的话） /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" # 安装 Node.js brew install nodeWindows（推荐使用 nvm-windows）：# 下载并安装 nvm-windows # 访问 https://github.com/coreybutler/nvm-windows/releases # 下载 nvm-setup.exe 安装 # 安装 Node.js nvm install 20 nvm use 20Linux（推荐使用 nvm）：# 安装 nvm curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash # 重启终端，然后： nvm install 20 nvm use 204.2 安装 Claude Code安装非常简单，一行命令搞定：npm install -g @anthropic-ai/claude-code-g的含义：全局安装（global），这样你在任何目录下都可以使用claude命令。安装完成后，验证安装是否成功：claude --version # 输出类似：claude-code 2.1.1314.3 登录认证Claude Code 需要 Anthropic 账号才能使用。运行以下命令进行登录：claude首次运行时，Claude Code 会提示你选择认证方式：方式一：使用 Claude.ai 账号（推荐初学者）如果你已有 Claude.ai 的订阅（Pro、Max、Team 或 Enterprise），可以直接使用账号登录。打开显示的 URL，在浏览器中完成授权，然后回到终端继续。方式二：使用 Anthropic API Key如果你是开发者，想通过 API 使用：访问 https://console.anthropic.com创建账号并生成 API Key在 Claude Code 的登录提示中粘贴 API Key设置环境变量（可选，推荐）：# macOS/Linux - 添加到 ~/.bashrc 或 ~/.zshrc export ANTHROPIC_API_KEY="sk-ant-api03-..." # Windows PowerShell $env:ANTHROPIC_API_KEY = "sk-ant-api03-..."4.4 订阅计划对比计划月费默认模型适合人群Pro$20Sonnet 4.6个人开发者Max$100-200Opus 4.7重度用户Team$25/人Sonnet 4.6小团队Enterprise定价Opus 4.7大企业API按使用量自选开发者/集成4.5 IDE 集成安装除了纯终端使用，Claude Code 还提供了 IDE 插件：VS Code 插件：打开 VS Code按Ctrl+Shift+X（或Cmd+Shift+Xon Mac）打开扩展市场搜索 "Claude Code"点击安装安装后，你可以直接在 VS Code 的终端里使用claude命令，或者通过侧边栏的 Claude Code 面板与 AI 交互。JetBrains 插件（IntelliJ、PyCharm、WebStorm 等）：打开 Settings（Ctrl+Alt+S）进入 Plugins → Marketplace搜索 "Claude Code"安装并重启 IDEa/a第五章：第一次启动 Claude Code——Hello World 实战5.1 启动 Claude Code打开终端，切换到你的项目目录：cd /path/to/your/project claude或者直接带任务启动：claude "帮我创建一个 Hello World 的 Node.js 应用"Claude Code 启动后，你会看到一个交互式界面，顶部显示：当前项目路径当前使用的模型当前会话的 token 用量和成本5.2 你的第一个任务让我们从一个简单的任务开始，感受 Claude Code 的工作方式。任务：创建一个简单的待办事项（Todo）应用在 Claude Code 的提示符下输入：请帮我创建一个简单的命令行待办事项应用，用 Node.js 实现。 要求： 1. 可以添加待办事项 2. 可以列出所有待办事项 3. 可以标记完成 4. 数据保存到本地 JSON 文件然后按 Enter 发送。观察 Claude Code 的工作过程：Claude Code 的响应过程（示意）： 1. [分析] 理解任务要求... 2. [规划] 制定实现方案... - 创建 todo.js 主文件 - 创建 todos.json 数据文件 - 实现 add/list/complete 命令 3. [执行] 创建 todo.js... ✓ 文件已创建 4. [执行] 创建 package.json... ✓ 文件已创建 5. [验证] 运行测试命令... $ node todo.js list ✓ 运行成功创建出来的todo.js可能长这样：const fs = require('fs'); const path = require('path'); const DATA_FILE = path.join(__dirname, 'todos.json'); // 读取待办事项数据 function loadTodos() { if (!fs.existsSync(DATA_FILE)) { return []; } const data = fs.readFileSync(DATA_FILE, 'utf8'); return JSON.parse(data); } // 保存待办事项数据 function saveTodos(todos) { fs.writeFileSync(DATA_FILE, JSON.stringify(todos, null, 2)); } // 添加待办事项 function addTodo(title) { const todos = loadTodos(); const newTodo = { id: Date.now(), title: title, completed: false, createdAt: new Date().toISOString() }; todos.push(newTodo); saveTodos(todos); console.log(`✅ 已添加：${title}`); } // 列出所有待办事项 function listTodos() { const todos = loadTodos(); if (todos.length === 0) { console.log('📭 暂无待办事项'); return; } console.log('📋 待办事项列表：'); todos.forEach((todo, index) = { const status = todo.completed ? '✓' : '○'; console.log(` ${index + 1}. [${status}] ${todo.title}`); }); } // 标记完成 function completeTodo(index) { const todos = loadTodos(); const todo = todos[index - 1]; if (!todo) { console.log('❌ 未找到该待办事项'); return; } todo.completed = true; saveTodos(todos); console.log(`✅ 已完成：${todo.title}`); } // 命令行参数处理 const [,, command, ...args] = process.argv; switch (command) { case 'add': addTodo(args.join(' ')); break; case 'list': listTodos(); break; case 'complete': completeTodo(parseInt(args[0])); break; default: console.log('用法：'); console.log(' node todo.js add 待办事项'); console.log(' node todo.js list'); console.log(' node todo.js complete 编号'); }5.3 与 Claude Code 交互的基本规则规则一：用自然语言描述需求不需要用技术语言，直接说你想要什么结果：❌ 不好的方式：请用 async/await 重构函数，返回 PromiseTodoItem[] 类型 ✅ 好的方式：把 loadTodos 函数改成异步的，支持 TypeScript规则二：提供足够的上下文越详细越好：❌ 不够详细：帮我写个登录功能 ✅ 详细版本：帮我写一个用户登录功能，使用 JWT token 认证， 密码需要 bcrypt 加密，登录成功后返回 token， 失败了返回具体的错误信息规则三：分步确认对于复杂任务，可以先让 Claude 制定计划，确认后再执行：请先告诉我你打算怎么做，等我确认后再开始修改代码规则四：使用"等我说可以再开始"来控制节奏如果你不确定 Claude 的计划，可以让它先停下来：先不要动代码，告诉我你的修改方案，我看看有没有问题5.4 退出和保存会话退出 Claude Code：按Ctrl+C输入/exit或/quit会话历史：Claude Code 会自动保存会话记录，你可以通过/history查看历史，或者用claude --resume恢复上一个会话。a/a第六章：核心概念深度解析6.1 工具系统（Tools）Claude Code 之所以能"真正干活"，是因为它拥有一系列工具（Tools），这些工具让它可以与你的系统交互。主要的内置工具包括：工具名功能Read读取文件内容Write写入/修改文件Bash执行 shell 命令Glob列出匹配的文件列表Grep在文件中搜索文本Edit精确编辑文件的特定部分TodoRead读取 Claude 的内部任务列表TodoWrite修改 Claude 的内部任务列表示例：Claude Code 如何使用工具当你说"找出项目里所有包含 console.log 的地方"，Claude Code 的内部逻辑是：思考：用户想找 console.log，我应该用 Grep 工具 ↓ 调用：Grep("console.log", ".", {recursive: true}) ↓ 结果：找到了 23 个文件中的 47 处 console.log ↓ 回应：我找到了以下位置... [列出清单]权限控制：Claude Code 不会不经通知就执行危险操作。默认情况下，执行 Bash 命令前会询问你是否允许。6.2 上下文窗口（Context Window）上下文窗口是 Claude Code 一次性能"记住"的信息量。Claude Code 的上下文窗口：200,000 tokens什么是 token？Token 是语言模型处理文本的基本单位。大致换算：1 个英文单词 ≈ 1-2 个 token1 个汉字 ≈ 1-2 个 token200,000 tokens ≈ 约 15 万汉字 ≈ 一本中等厚度的书上下文里装了什么？[系统指令] [CLAUDE.md 文件内容] [会话历史：你的输入 + Claude 的回答] [Claude 读取的文件内容] [工具调用的结果]上下文用满了怎么办？当上下文快满时（超过 70-80%），你有两个选择：/compact命令：压缩上下文（保留关键信息，丢弃细节）/clear命令：清空上下文，重新开始经验法则：0-50% 使用量：正常工作50-70% 使用量：留意上下文70-90% 使用量：使用/compact90%+ 使用量：必须使用/compact或/clear6.3 项目感知（Project Awareness）这是 Claude Code 与普通 AI 聊天工具最大的区别之一。当你在项目目录启动 Claude Code 时，它会自动：扫描项目结构（文件和目录列表）读取CLAUDE.md文件（如果存在）读取package.json、pyproject.toml等配置文件理解项目使用的技术栈这让它能够做出符合项目规范的决策，而不是给出通用的、可能不适合你项目的方案。类比：就像一个新来的员工，入职第一天先把项目文档读一遍，了解项目背景，而不是直接开始写代码。6.4 记忆系统Claude Code 有多种形式的"记忆"：1. 会话内记忆（短期记忆）当前会话的完整对话历史会话结束后消失2. CLAUDE.md 记忆（长期规则记忆）写在项目的CLAUDE.md文件里每次启动都会读取用于存储项目规范、编码规则等3. 自动记忆（Auto Memory）Claude Code 会从会话中自动总结并保存重要信息存储在~/.claude/projects/project/memory/目录下次启动时会加载4. 上下文文件（按需加载）使用/load命令或@文件名语法引用文件根据需要随时加载a/a第七章：CLAUDE.md 文件——让 Claude 了解你的项目7.1 什么是 CLAUDE.md？CLAUDE.md是 Claude Code 的"项目说明书"。把它放在项目根目录，Claude Code 每次启动时都会自动读取它，就像新员工入职读项目文档一样。它的作用：告诉 Claude 这个项目是什么规定编码规范和风格定义项目特有的术语和约定指定需要遵守的规则没有 CLAUDE.md 的结果：Claude 可能会做出不符合你项目风格的决定，比如用你不用的库、写不符合你团队规范的代码。有了 CLAUDE.md 的结果：Claude 就像一个熟悉你项目的老员工，一上来就知道该怎么做。7.2 快速生成 CLAUDE.mdClaude Code 提供了一个快捷命令来生成初始的 CLAUDE.md：# 在项目根目录运行 claude # 然后输入： /initClaude Code 会扫描你的项目，自动生成一个初始的 CLAUDE.md 文件。7.3 CLAUDE.md 的结构一个完整的 CLAUDE.md 文件通常包含以下部分：# 项目名称 ## 项目概述 这是一个电商平台的后端 API，使用 Node.js + Express + PostgreSQL 构建。 ## 技术栈 - **运行时**：Node.js 20+ - **框架**：Express.js 4.x - **数据库**：PostgreSQL 15 - **ORM**：Prisma - **认证**：JWT - **测试框架**：Jest ## 项目结构src/ ├── controllers/ # 控制器层（路由处理） ├── services/ # 业务逻辑层 ├── repositories/ # 数据访问层 ├── models/ # 数据模型 ├── middlewares/ # 中间件 ├── utils/ # 工具函数 └── tests/ # 测试文件## 编码规范 ### 命名约定 - 文件名：camelCase（如 userService.js） - 类名：PascalCase（如 UserService） - 函数名：camelCase（如 getUserById） - 常量：UPPER_SNAKE_CASE（如 MAX_RETRY_COUNT） - 数据库字段：snake_case（如 user_id） ### 代码风格 - 使用 2 个空格缩进 - 使用单引号 - 函数必须有 JSDoc 注释 - 异步函数必须使用 async/await，不使用回调 - 错误处理必须使用 try/catch，不能 swallow errors ### API 设计规范 - RESTful 风格 - 统一响应格式：{ success: boolean, data: any, message: string } - 错误响应包含错误码：{ success: false, error: { code: string, message: string } } - 路由版本号：/api/v1/... ## 开发流程 ### 添加新功能的标准流程 1. 先写单元测试（TDD） 2. 实现功能 3. 确保所有测试通过 4. 更新 API 文档 ### 禁止事项 - 不要直接在 main 分支提交 - 不要在代码里写硬编码的配置（用环境变量） - 不要在未经审核的情况下删除数据库表 ## 常用命令 ```bash npm run dev # 启动开发服务器 npm run test # 运行测试 npm run test:watch # 监视模式运行测试 npm run lint # 代码检查 npm run migrate # 运行数据库迁移重要注意事项数据库连接信息在 .env 文件中，不要提交到 git生产环境部署需要运行 npm run migrate新增的 API 接口必须在 API_DOCS.md 中更新文档### 7.4 CLAUDE.md 的分层体系 CLAUDE.md 不只是一个文件，它是一个**分层系统**：~/.claude/CLAUDE.md ← 全局配置（对所有项目生效） ↓ /project/CLAUDE.md ← 项目根目录配置 ↓ /project/src/CLAUDE.md ← 子目录配置（仅对该目录生效） ↓ /project/src/api/CLAUDE.md ← 更深层的配置**实际应用场景**： - `~/.claude/CLAUDE.md`：放个人的编码偏好、常用缩写、喜欢的库 - `/project/CLAUDE.md`：放项目整体规范 - `/project/src/api/CLAUDE.md`：放 API 层特有的规则 ### 7.5 CLAUDE.md 的最佳实践 **技巧一：用具体例子代替模糊描述** ```markdown # ❌ 模糊的描述 写好的代码 # ✅ 具体的例子 函数必须有 JSDoc 注释，格式如下： /** * 根据 ID 获取用户信息 * @param {string} userId - 用户 ID * @returns {PromiseUser|null} 用户对象，不存在时返回 null */ async function getUserById(userId) { ... }技巧二：列出"不要做什么"## 禁止事项 - 不要使用 moment.js（用 dayjs 代替） - 不要使用 var（使用 const 或 let） - 不要直接访问数据库（必须通过 Repository 层）技巧三：提供常用命令## 开发命令 - 运行测试：`npm test` - 格式化代码：`npm run format` - 检查代码：`npm run lint`技巧四：说明项目特有术语## 术语表 - SKU：商品的特定规格，如"红色XL号T恤" - SPU：同类商品的统称，如"T恤" - 库存扣减：用户下单时减少库存的操作a/a第八章：斜杠命令（Slash Commands）完全手册8.1 什么是斜杠命令？在 Claude Code 的交互界面中，输入/开头的命令叫做斜杠命令（Slash Commands）。这些是 Claude Code 内置的快捷操作，类似于操作系统的快捷键。输入/后按 Tab 或继续输入，可以看到所有可用命令的列表。8.2 会话管理命令这些命令用于管理当前的对话会话：/clear— 清空上下文/clear清空整个会话历史和上下文。适用于：切换到完全不同的任务上下文已经混乱，需要重新开始节省 token 用量⚠️注意：清空后无法恢复会话内容（但文件修改不会撤销）/compact— 压缩上下文/compact # 或指定保留的内容 /compact 保留所有关于认证系统的讨论压缩上下文，保留关键信息，丢弃不重要的细节。适用于：上下文使用量达到 70-80%想继续当前任务但需要释放空间/branch— 分支会话/branch创建当前会话的分支，可以在不影响主会话的情况下尝试不同方案。/rewind— 回滚到之前状态/rewind # 或按 Esc 两次唤出回滚菜单回滚到之前的状态。2026版新增了两种模式：仅回滚代码：撤销文件修改，保留对话历史完全回滚：同时撤销代码修改和对话历史实际场景：让 Claude 尝试了一种方案，结果不好，用/rewind回到方案实施之前重新来过。/history— 查看会话历史/history显示当前会话的完整对话历史。8.3 设置与配置命令/init— 初始化项目/init扫描当前项目并自动生成CLAUDE.md文件。新项目必做的第一步。