Claude Code 深度教程：把命令行变成你的 AI 同事
要理解 Claude Code，先把它和传统的 AI 补全（Copilot 式）区分开。补全是"你敲代码，它猜下一行"，主动权在你，AI 只是个更聪明的输入法。Claude Code 完全不是这个路子——它是一个跑在终端里的 agentic 编码代理：你给它一个目标（比如"把登录接口的空指针异常修掉"），它会自己读代码、定位问题、改文件、跑测试、看报错、再改，循环往复直到任务完成或需要你拍板。官网。
它的本质可以用一个公式概括：大模型大脑 + 一组工具（读写文件 / 跑 Bash / 搜索 / 联网 / 派子代理）+ 一个"观察→思考→行动"的循环。你不再是"用工具写代码"，而是"给一位能读懂你项目的同事派活"。Opus/Fable 系的编码能力加上这套成熟的 agentic 闭环，让它能啃下跨文件重构这种"硬骨头"，也是它在 2026 年被多数横评评为 agentic 编码第一的原因。
1、安装与心智模型
前置条件只有一个：Node.js 18 或以上。一条命令全局安装，然后在任意项目目录启动。
// 1. 全局安装
npm install -g @anthropic-ai/claude-code
// 2. 进入项目并启动
cd ~/code/my-shop-api
claude
// 3. 首次启动引导登录（订阅账号 或 API Key）启动后有三种使用姿态：交互式 REPL（`claude`，最常用）、一次性提问（`claude -p "解释这段逻辑"`，跑完即退）、headless / CI（`claude -p "修复 #1234" --permission-mode acceptEdits`，可嵌进流水线自动产出 diff/PR）。姿态 C 是被很多人忽略的杀手锏——它让"AI 改代码"从手动变成 CI 的一环。
用好它的前提是建立四个心智模型：会话（session）是一次 `claude` 启动，任务做完要及时 `/clear`，否则越长越笨越贵；上下文（context）是它在某步"看得到"的全部信息（对话、读过的文件、命令结果），接近上限会自动 compact，也能 `/compact`、`/clear` 主动管理；工具（tools）是它的"手脚"（读写文件、跑 Bash、Grep/Glob、联网、派子代理），默认每次调用都请你确认；权限（permission）控制它能干什么，是安全核心，第 7 节细讲。
2、CLAUDE.md：给 AI 的"项目交接文档"
如果说有一条建议能立竿见影提升效果，那就是写好 CLAUDE.md。它放在项目根目录，Claude Code 每次启动都自动读取——相当于给新同事的一份"项目交接文档"。它支持分层：项目根的 `CLAUDE.md` 对全仓库生效，子目录可叠加，还有全局 `~/.claude/CLAUDE.md` 放个人偏好。不知道写什么就用 `/init` 让它扫描项目自动生成初版。
该写什么？记住四类：技术栈与架构、常用命令、编码规范、明确的禁忌。
# 项目：my-shop-api（电商后台）
## 技术栈
- Kotlin 1.9 + Spring Boot 3.2 + MySQL 8 + Redis
- ORM 用 Exposed，不要混用 JPA
## 常用命令
- 构建：./gradlew build
- 测试：./gradlew test
- 本地起服务：./gradlew bootRun
## 编码规范
- REST 资源名用复数（/orders 而非 /order）
- Service 层无状态，业务逻辑不写进 Controller
- 改动必须通过 ./gradlew test 再提交
## 禁忌（重要）
- 不要动 legacy/ 目录，那是待下线的老系统
- 不要引入新依赖，需先讨论
- 数据库迁移走 Flyway，禁止手改 schema注意最后那块"禁忌"——这是 CLAUDE.md 价值最高的部分。AI 默认"热心过头"，你不画红线，它可能顺手重构掉你不想动的代码。把"别碰什么"讲清楚，能省掉大量返工。
3、日常三种姿势与 Plan 模式
姿势一：一问一答（咨询/理解）。适合"这段逻辑在干嘛""为什么这里慢"。它读代码后给你解释，不动文件——先让它"看懂"，再让它"动手"。
> src/payment 下退款失败重试 3 次还是抛异常，帮我顺一下调用链
> 指出最可能出问题的两处，先别改姿势二：交互式改造（日常主力）。你说目标，它改代码，你逐文件审 diff。不满意就让它回滚或调整。
> 给 OrderService 加"批量导出订单为 CSV"的方法，
> 复用现有 OrderRepository 查询，大结果集要分页姿势三：headless / 一次性。第 1 节的姿态 C，适合脚本化、CI 化，比如每天凌晨处理一批低优先级 issue。
Plan 模式：遇到跨多文件、风险高、需求模糊的任务，先别让它直接动手，而是让它先调研、产出一份"怎么改、分几步、影响哪些文件"的方案，你确认后再执行——避免"改了 200 行才发现方向错了"的白干。判断标准：改动可能超过 3 个文件，或会动到测试/配置/数据库，就先 Plan；小修小补直接改，别过度流程化。
> 把日志框架从 log4j 迁到 SLF4J，先给我迁移方案，
> 列出要改的文件和顺序，不要直接动手
// 它产出方案 → 你审 → 确认后："按这个方案执行"4、进阶四件套：子代理、Skills、Hooks、自定义命令
子代理（Subagents / Task）：主会话派一个子代理干独立的活，子代理有独立上下文，干完只交结论。最大好处是保护主上下文——大输出搜索交给子代理，主会话不被刷爆。
> 派一个子代理：在 src/ 下找出所有直接 new SimpleDateFormat 的地方，
> 汇总成清单（带文件名和行号）Skills（技能）：把"某类任务的固定套路"封装成可复用技能，按需调用——比如"生成一篇符合规范的博客""给 PR 写标准审查意见"。理解成"教 AI 一门手艺"，写一次到处用。
Hooks：在工具调用的"前/后"自动触发脚本，实现"自动化规矩"。比如每次 Edit 后自动跑 `detekt`、跑 Bash 前拦掉 `rm -rf`。配置写在 settings.json：
// .claude/settings.json —— 每次编辑文件后自动跑 detekt
{
"hooks": {
"PostToolUse": [
{ "matcher": "Edit|Write",
"hooks": [{ "type": "command", "command": "./gradlew detekt --quiet" }] }
]
}
}自定义 slash 命令：把高频流程写成一条命令，比如 `/release` = "跑测试 → 改版本号 → 生成 changelog → 打 tag"，一键触发，适合团队共享标准流程。
5、MCP：让它连上外部世界
Claude Code 默认只能操作本地文件和跑命令。要让它"查 GitHub issue""读数据库""搜网页"，就接 MCP（模型上下文协议）——它把"AI 与外部工具"的连接标准化，配一次处处可用。在项目或全局配置里声明 MCP Server：
// .mcp.json —— 接入 GitHub 与一个本地 SQLite
{
"mcpServers": {
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"]
},
"sqlite": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-sqlite", "--db-path", "./data/app.db"]
}
}
}配好后，你就能在会话里直接说"把 #1234 issue 的描述读给我，然后按它修""查一下 orders 表里昨天失败的订单"，它调用对应 Server 拿数据再行动。不用切应用、不用复制粘贴，这是 agentic 体验质变的一步。
6、权限与安全：别让"同事"闯祸
能跑命令、能改文件，就意味着能闯祸。Claude Code 用"权限模式"控制火力，三档要分清：default（每次敏感操作都问你，最安全，日常默认）、acceptEdits（自动接受文件编辑，跑命令仍问你，适合信任度高的批量改造）、plan（只读只规划，绝不碰文件）。在 settings.json 里还能精确配置"哪些命令放行、哪些拦死"，贯彻最小权限：只读放行提速，写/删/网操作必须确认。
// .claude/settings.json —— 精细权限
{
"permissions": {
"allow": ["Bash(./gradlew test)", "Bash(git status)", "Bash(git diff:*)"],
"deny": ["Bash(rm -rf:*)", "Bash(git push:*)", "Read(./**/.env*)"]
}
}上面这份配置：跑测试和看 git 状态直接放行提速；`rm -rf`、`git push`、读 `.env` 密钥一律拦死。再配合"改动前先开 git worktree"的习惯，基本能把风险控住。
7、端到端实战与常见坑
把前面学的串成一条真实流程。需求：给电商 App 加"收藏商品"功能（加收藏、取消、查列表三个接口）。
// 1. Plan：大改先出方案
> 新增"收藏"功能：Favorite 实体 + Repository + Service + 3 个 REST 端点，
> 参照 Order 的分层写法，先给方案别动手
// 2. 执行（acceptEdits 提速）：按方案改，每个接口带单测
// 3. 验证：它自己跑 ./gradlew test，看报错自动修，循环到全绿
// 4. 审 diff：让它汇总改了哪些已有文件、为什么，你逐文件审
// 5. 收尾：补 KDoc，给 commit message，确认后提交整个过程中你的角色是"审稿人 + 拍板者"，而非"打字员"。常见坑与对策：坑 1 会话越久越笨越贵→ 做完 `/clear`、大搜索派子代理；坑 2 改错文件/乱删→ 开 worktree、deny 拦截、别让它直接 push；坑 3 编造不存在的 API→ 让它"先 Grep 确认再用"、改完强制跑测试、新依赖先禁；坑 4 又慢又贵→ 日常用快档模型、硬骨头再切旗舰；坑 5 不守规范→ 写进 CLAUDE.md（尤其禁忌）、重复违反用 Hook 强制。
// 速查
claude 交互式
claude -p "..." 一次性
/init /clear /compact /model /help 常用命令
权限：default（确认）/ acceptEdits（自动编辑）/ plan（只规划）8、总结
Claude Code 把"大模型"升级成了"会干活的同事"：它能读懂你的项目（靠 CLAUDE.md）、按规范自主推进（靠 agentic 循环）、还能被你用权限和 Hook 拴住（靠工程化配置）。用好它的关键不是"学会所有命令"，而是建立一套配合默契的工作流。
关键要点：
- 它是 agentic 代理不是补全；你的角色是"派活 + 审稿 + 拍板"
- CLAUDE.md 是效果命脉，尤其"禁忌"那段
- 大任务先 Plan，改完必跑测试、必审 diff
- 子代理护上下文、Hook 强规矩、MCP 连外部、权限控火力
最后送一句心法：把它当成一位能力很强、但需要清晰交接和明确边界的同事。你给的项目背景越清楚、红线越明确、反馈越及时，它就越能从"偶尔帮忙"变成"不可替代的搭档"。当你发现自己在"设计意图"上花的时间开始超过"敲代码"时，说明你已经真正用对了 Claude Code。
