Claude Code 学习笔记:从入门到驾驭 AI 编程 Agent

1. 重新认识 Claude Code：它不是聊天机器人1.1 一句话理解1.2 Claude Code vs AI IDE：不是替代，是互补1.3 能力全景2. 核心机制：Agent Loop 工作原理3. 安装与配置：3步上手3.1 安装方式3.2 首次启动与认证3.3 一招跳过烦人的确认4. 核心命令速查手册4.1 项目管理与初始化4.2 会话控制4.3 核心快捷键5. CLAUDE.md：给 Claude 装上「项目记忆」5.1 核心原则：保持简短5.2 好的 CLAUDE.md 示例结构6. 进阶技巧：让效率翻倍6.1 Plan Mode（计划模式）：磨刀不误砍柴工6.2 MCP 集成：连接外部世界6.3 Subagents（子代理）：专业分工的 AI 助手6.4 Hooks（钩子）：自动化触发器6.5 Git Worktree：并行任务隔离7. 实战 SOP：三套拿来即用的工作流7.1 老项目重构：不破坏线上功能的分步推进7.2 快速迭代：从需求到交付的高效闭环7.3 全新项目研发：从架构决策到 CI/CD8. 上下文管理：防止「答案越来越偏」8.1 核心策略8.2 /compact 可指定压缩策略8.3 Checkpoints（检查点）9. 调试与纠错：5 条黄金法则10. 常见错误与避坑指南11. 总结：用好 Claude Code 的关键心智

导语：很多开发者用了 Claude Code 一段时间后，感觉「好像也没那么神奇」——写的代码时对时错，改着改着把不该动的文件也改了，长时间对话后回答开始偏题。问题其实不在工具本身，而在于缺少一套正确的使用框架。本文从核心概念、安装配置、命令速查、进阶技巧到实战SOP，带你系统掌握 Claude Code。

1. 重新认识 Claude Code：它不是聊天机器人

1.1 一句话理解

Claude Code 是 Anthropic 基于 Claude 模型打造的终端 AI 编程 Agent。它不是一个聊天机器人，也不是代码补全插件——它是一个可以直接操作你代码仓库的 AI 软件工程师。

它能做什么？

• 理解整个代码库（多文件、多语言、多层依赖）

• 自主规划任务，跨文件编写和修改代码

• 执行 Shell 命令、运行测试、验证结果

• 处理 Git 工作流（commit / PR / merge conflict）

• 通过 MCP 协议连接数据库、API 等外部工具

核心认知——角色的转变：你从「写代码的人」变成了「描述需求 + 设定边界 + 审查结果的人」。Claude 越是能干，你越要注意：给清晰的边界和验证标准，是用好它的关键。没有边界，它会改出你不想要的代码；没有验证标准，它不知道什么叫做对。

1.2 Claude Code vs AI IDE：不是替代，是互补

两者互补，不是替代。Cursor 适合精细的逐行操作，Claude Code 适合大任务自动化。很多高阶开发者同时使用两者：Claude Code 负责大块任务，Cursor 负责精细打磨。

1.3 能力全景

Claude Code 的能力范围远超你想象：

2. 核心机制：Agent Loop 工作原理

Claude Code 的核心是一个 Agent Loop（代理循环）。简单来说，它就像一个「总指挥」，负责把「用户意图」「模型大脑」和「执行工具」串成一个完美的闭环：观察 → 思考 → 行动 → 反馈，循环往复直到完成任务。

从架构层面来看，Claude Code 的工作流程如下：

用户输入 → 整合CLAUDE.md规范与对话历史 → QueryEngine发起流式请求→ 解析模型输出的工具调用指令 → 工具分发器检查权限后执行→ 执行结果回传模型 → 如有递归调用则重入引擎 → 输出结果

这个循环让 Claude Code 能够自主做计划、调用工具、根据结果调整策略，直到目标达成。LLM只管「思考」，Harness（线束）工程才是决定 Agent 表现的关键——同样的模型，不同的 Harness，效果差别巨大。Claude Code 正是 Harness 的集大成者。

3. 安装与配置：3步上手

3.1 安装方式

方式一：npm 全局安装

npm install -g @anthropic-ai/claude-code# 国内用户可使用镜像加速npm install -g @anthropic-ai/claude-code --registry=https://registry.npmmirror.com

验证安装：claude --version

方式二：原生安装（无需 Node.js）

• macOS / Linux / WSL：

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

• Windows PowerShell：

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

3.2 首次启动与认证

cd /path/to/your/projectclaude

按提示在浏览器中完成 OAuth 授权，终端会自动缓存令牌，后续无需重复登录。

3.3 一招跳过烦人的确认

刚开始用 Claude Code 最头疼的是每执行一个操作都要点确认。可以在启动时加上参数：

claude --dangerously-skip-permissions

⚠️ 注意：这个模式叫「危险模式」是有原因的！建议在测试项目或完全信任 Claude 时使用，生产环境请谨慎。

4. 核心命令速查手册

4.1 项目管理与初始化

/init 是每个项目必做的第一步。运行后 Claude 会扫描你的代码库，生成 CLAUDE.md 文件——这是 Claude 的「项目手册」，包含项目结构、构建和测试命令、代码规范和架构决策。有了它，Claude 后续的所有操作都会更符合你的项目实际。

4.2 会话控制

4.3 核心快捷键

5. CLAUDE.md：给 Claude 装上「项目记忆」

如果说指令是让 Claude 动起来的「方法」，那么 CLAUDE.md 就是赋予它「灵魂」和「记忆」的核心。

5.1 核心原则：保持简短

• 控制在 60 行以内，硬上限 300 行

• LLM 能可靠遵循约 150-200 条指令，Claude Code 系统提示已占用约 50 条

• 只放 Claude 可能忽略的信息：构建命令、测试命令、分支命名规范、架构决策

• 能从代码推断的内容不要写进去

• 规则太多？拆分到 .claude/rules/ 目录下按需加载

• 关键规则用标签包裹，防止被忽略

5.2 好的 CLAUDE.md 示例结构

## 工作流- 每次代码变更后运行 `npm test`- 每个任务创建新分支，绝不直接提交到 main- 使用 Conventional Commits（feat:, fix:, refactor:, docs:）- 每次提交前运行 `eslint . --fix`- 完成后通过 `gh pr create` 创建 PR## 技术栈- Node.js 18+, Express 4.x, PostgreSQL 16- 测试：Jest + React Testing Library- 认证：JWT + bcrypt## 核心服务- /services/billing.py — 所有支付逻辑集中在这里，不要创建并行代码- /services/auth.py — JWT + refresh token 模式- /lib/db.ts — 统一数据库实例入口## 代码规范- 所有 API 返回 { data, error, meta } 格式- 异常统一使用 AppError 类- 数据库查询必须显式选择字段，禁止 select *## 不要触碰- /legacy/payments/ — 已弃用，Q3 移除- /auth/oauth.py — SSO 上线前冻结

【最佳实践】：每次纠正 Claude 的错误后，加上一句「把这条更新到 CLAUDE.md 里」。长期坚持下来，这份文档会变成一份不断进化的最佳实践指南。CLAUDE.md 的本质是训练数据的本地化定制，你喂什么样的规则，它就变成什么样的助手。

6. 进阶技巧：让效率翻倍

6.1 Plan Mode（计划模式）：磨刀不误砍柴工

任何复杂任务，都应该从 Plan Mode 开始。按 Shift+Tab 两次进入计划模式，Claude 只研究和规划，不写代码。确认计划后再切换回正常模式执行。

官方推荐流程：探索 → 规划 → 实现 → 提交

这让 Claude 先给出完整的技术方案，你用人类工程师的视角 review 一遍，确认无误后再开始编码——比写到一半发现方向错了推倒重来，省下大量时间。

6.2 MCP 集成：连接外部世界

MCP（Model Context Protocol）是 Claude Code 连接外部工具的标准化协议。通过 MCP，Claude Code 可以直接连接：

• 数据库：PostgreSQL、MySQL 等

• API 服务：GitHub、Jira、Slack 等

• 知识库：企业文档、项目管理工具

• 安全服务：代码扫描、合规检查

Claude Code 已支持远程 MCP 服务器的流式 HTTP 连接，无需手动进行本地服务器设置即可集成外部工具和资源。

6.3 Subagents（子代理）：专业分工的 AI 助手

Subagents 是 Claude Code 中的专业化 AI 助手，每个子代理拥有独立上下文窗口、专属系统提示词和受限工具集。当主会话遇到匹配描述的任务时，会自动委托给相应子代理独立执行，完成后汇报结果。子代理与主会话上下文隔离，有效防止「上下文污染」。

三大内置子代理：

创建自定义子代理：在 .claude/agents/ 目录下放入 .md 文件即可。例如创建一个安全审查代理：

---name: security-reviewerdescription: 审查代码安全漏洞，专注认证、注入、权限风险tools: Read, Grep, Globmodel: sonnetmemory: project---你是资深安全审计工程师。每次审查时，先读取历史审计记录，再扫描目标代码，最后按严重程度（Critical / High / Medium / Low）分类输出。

运行 /agents 命令可以管理所有子代理。

6.4 Hooks（钩子）：自动化触发器

Hooks 是让 Claude Code 真正「可编程」的功能。它们是 shell 命令或 LLM 提示词，在 Claude Code 生命周期中的特定时刻自动触发。

三种 Hook 类型：

14 个生命周期事件中常用的 4 个：

实际应用示例：

• 每次编辑文件后自动运行 ESLint

• 拦截对 migrations/ 目录的写入操作

• 提交前自动生成 Conventional Commits 消息

• 危险命令拦截并推送飞书通知

6.5 Git Worktree：并行任务隔离

通过 Git Worktree 技术，可以在同一个代码仓库同时开启多个独立的 Claude 会话，每个会话拥有隔离的分支工作区。这意味着不同的开发任务之间互不干扰，彻底解决会话重叠带来的代码冲突风险。

实战配置：同时开启 3-5 个 worktree，每个跑着独立的 Claude 会话：

• Worktree A：专攻新功能开发

• Worktree B：Review 和调试

• Worktree C：处理技术债务

• Worktree D：数据分析（只看日志和跑查询）

这种物理隔离让每个 Claude 会话的上下文都异常清晰，再也不用担心任务之间互相干扰。

# 创建 worktree 并切换git worktree add -b feature-payment ../worktrees/feature-payment# 在新 worktree 中启动 Claude Codecd ../worktrees/feature-payment && claude

7. 实战 SOP：三套拿来即用的工作流

7.1 老项目重构：不破坏线上功能的分步推进

① 让 Claude 先分析项目结构 → ② 制定重构计划（Plan Mode）→ ③ 在 worktree 隔离环境执行 → ④ 逐模块验证测试通过→ ⑤ 合并前做完整回归测试 → ⑥ 通过 PR 合并到主线

关键原则：每次只重构一个模块，验证通过再继续；使用独立的 worktree 避免污染主线。

7.2 快速迭代：从需求到交付的高效闭环

① 用自然语言描述需求 → ② 让 Claude 用 AskUserQuestion 采访你补充细节→ ③ 生成可执行的规格文档 → ④ Plan Mode 确认技术方案→ ⑤ 并行 worktree 开发 → ⑥ Claude 自动生成 commit message → ⑦ 创建 PR

关键原则：采访后开新会话执行，避免采访对话污染上下文；每次代码变更后必须运行测试。

7.3 全新项目研发：从架构决策到 CI/CD

① 与 Claude 讨论技术选型和架构方案 → ② 生成 CLAUDE.md 项目规范→ ③ 搭建项目骨架和目录结构 → ④ 逐功能开发（每次一个 worktree）→ ⑤ 配置 CI/CD 流水线 → ⑥ 编写测试 → ⑦ 部署上线

关键原则：先规划再实现，架构决策要人类确认；每个功能独立分支，通过 PR 合并。

8. 上下文管理：防止「答案越来越偏」

8.1 核心策略

研究发现：一个 40 条消息覆盖 3 个功能的会话，比 3 个各 15 条消息的独立会话更慢、更不准确。为新任务开启新对话，只加载与该任务相关的文件。

8.2 /compact 可指定压缩策略

/compact focusing on API changes        # 聚焦 API 变更/compact keep test-related history       # 保留测试相关历史/compact keep error resolution           # 保留错误解决历史

8.3 Checkpoints（检查点）

Claude Code 每次操作都会自动创建检查点——可以独立回滚对话或代码，跨会话持久化。注意：它不是 Git 的替代品。

9. 调试与纠错：5 条黄金法则

法则 1：粘贴 bug，说 "fix"把错误信息粘贴给 Claude，说一个字："fix"。不要指导怎么修，不要猜测原因，不要指定解决方案。Claude 的调试能力比想象中强，你管得越多越容易带偏。直接让 Claude 修的成功率 80%+。

法则 2：两次失败 = /clear同一个问题修正超过两次，开新会话重新开始。上下文污染会持续降低性能。

法则 3：走偏了？Esc Esc 回滚按两次 Esc 直接回滚到上一个检查点，不要在同一污染上下文中纠正偏差。

法则 4：要求重写而不是修补当 Claude 给出能工作但不优雅的方案时，说："知道你现在知道的一切，抛弃这个方案，实现优雅的解决方案"。重写版本通常比修补版本好得多。

法则 5：让 Claude 先采访你给出简单需求描述，让 Claude 用 AskUserQuestion 工具采访你——它能发现你忽略的边缘情况。采访后务必开新会话执行。

10. 常见错误与避坑指南

11. 总结：用好 Claude Code 的关键心智

Claude Code 不是魔法，而是放大器——它放大你的工程能力，也放大你的工程习惯。工具上限由模型能力决定，下限由你的使用方法决定。

核心心法归结为四句话：

1. 角色转变：你从「写代码」变成「描述需求 + 设定边界 + 审查结果」

2. 先规划后执行：复杂任务永远从 Plan Mode 开始

3. 保持上下文干净：一个任务一个会话，50% 就压缩

4. 善用专业分工：Subagents 做专一的事，Worktree 隔离不同任务

最后借用 Claude Code 团队的一句话：「使用 Claude Code 没有唯一的正解——那些技巧不是圣经，而是指南。关键是理解背后的逻辑，找到最适合自己的工作流。」

参考资料