一篇文章Claude Code 从入门到入土

Claude Code 是AI 编程代理——你说话,它自己读代码、写代码、跑命令、改 bug、跑测试。不是补全工具(像 Copilot),也不是聊天机器人(像 ChatGPT)。

m0_63237995

147人浏览 · 2026-05-21 16:04:46

m0_63237995 · 2026-05-21 16:04:46 发布

Claude Code 从入门到入土

通用版,适用任何语言/平台项目。VSClient(C++/Qt/Windows)、Python/Go/Web 等多个项目作为对照案例出现。
文档定位:新手到进阶都能直接抄。每章给可复制的命令、prompt 模板、配置片段。
撰写:2026-05-21。模型:Opus 4.7(1M 上下文)。

0. 导航

新手路线(按顺序读)

1 → 2 → 3 → 4 → 5(UI 详解,截图里的每个按钮)→ 6(必学 10 操作)→ 8(prompt 模板)→ 12(CLAUDE.md)

进阶路线

7(命令全表)→ 10(Plan)→ 11(Subagents)→ 12(Hooks)→ 13(MCP)→ 14(记忆)→ 15(CLAUDE.md)→ 16(权限)

全章目录

章	主题	谁该看
1	Claude Code 是什么、能干什么(新手必读)	新手
2	它是怎么工作的(底层模型)	新手
3	新手最容易踩的 10 个坑	新手
4	形态与模型选哪个	全部
5	VS Code 扩展 UI 详解(截图每个按钮)	新手
6	五分钟入门:必学 10 操作	新手
7	斜杠命令 + Skills 全表	全部
8	Prompt 模板库(直接复制)	全部
9	工具能力速览	进阶
10	Plan 模式	进阶
11	Subagents 并行调度	进阶
12	Hooks 实战配置(可复制)	进阶
13	MCP 接入	进阶
14	记忆系统	进阶
15	CLAUDE.md 多语言模板	全部
16	settings.json + 权限多语言模板	进阶
17	上下文管理与省 token	进阶
18	5 套实战流程	全部
19	项目落地案例(C++/Qt、Python、Go、Web)	全部
20	排错 FAQ	全部
21	速查表	全部

1. Claude Code 是什么、能干什么(新手必读)

1.1 一句话定义

Claude Code 是 AI 编程代理——你说话,它自己读代码、写代码、跑命令、改 bug、跑测试。不是补全工具(像 Copilot),也不是聊天机器人(像 ChatGPT)。

1.2 它能干什么(具体例子)

你说	它做
“解释 main.py 这个文件”	读文件 → 总结结构
“把变量 X 改名为 Y,改完跑构建”	grep → 列影响 → Edit → 跑 build
“这个 crash 栈是怎么回事”	读栈 → 定位代码 → 推根因
“加一个登录按钮”	读 UI 代码 → 改 → 实测
“评审我刚改的代码”	`/review` → 列 Critical/Warning/Suggestion
“整个项目的架构是怎样的”	派 Subagent 扫多目录 → 汇总

1.3 它不能干什么

不能	为什么 / 替代
看屏幕(UI 视觉验证)	你得手动测,Claude 只能跑命令验证
知道你的私有 Wiki	装对应 MCP 才能接入
跨会话记得无关项目的事	用记忆/CLAUDE.md 显式持久化
在没有 git 的仓库用 Worktree	先 git init
100% 不出错	失败 2 次必须换思路;改完必须自己验证

1.4 我什么时候不该用它

5 秒能写完的代码(打字比说话还快)
高度涉及视觉判断(像素对齐、配色)——它看不见
完全没接触过的代码区域,你也无法判断对错——容易被忽悠
需要严格法律/合规审查的代码——它会犯错,得人复核

1.5 学习曲线

阶段	时间	状态
完全新手	Day 1-2	用自然语言提问、学会 `@`、`/`、`Esc`
基本上手	第一周	能让它改简单 bug、写测试
熟练	第一月	用 Plan 模式做重构、配 hooks 自动化
进阶	三月+	自定义 Skill、写 MCP、调权限策略

2. 它是怎么工作的(底层模型)

理解这个能帮你预测它的行为。

2.1 一次对话发生了什么

你:"把 X 改名为 Y"
   │
   ▼
Claude(大模型推理)
   │ 决定要做什么
   ▼
调工具(Read / Grep / Edit / Bash...)
   │
   ▼
工具返回结果
   │
   ▼
Claude 看结果 → 继续调工具 / 回复你
   │
   ▼
循环,直到任务完成

每一步你都能在 UI 看见:它读了哪个文件、跑了什么命令、改了哪几行。

2.2 它有"上下文窗口"

简单说:短期记忆是有限的。

Opus 4.7:1M tokens(约 75 万汉字)
装满了会自动压缩(总结早期对话)
跨会话记忆要靠记忆文件 / CLAUDE.md

2.3 工具是它的"手和眼"

工具	类比
Read	翻开一本书
Grep	全书搜关键字
Edit	拿铅笔改一处
Write	撕掉一页重写
Bash	在终端打字
Agent	派助手干活
WebSearch	上网查

它没有视觉,看不到 UI;没有触觉,跑不了真实硬件。

2.4 安全机制

机制	作用
权限弹框	危险操作弹框让你批
`permissions.deny`	写在配置里,直接拦截
Plan 模式	只读探索,不改代码
Hooks	你定义的强制规则
工具结果可见	它做什么你都看得见,可中断

2.5 它会犯什么错

过度自信:不验证就声称"已修复"
小修小补:同一思路改 5 次都不行还在试
造数据:文件没读就说"X 函数在 file:42"——可能不存在
绕弯子:复杂问题给 patch,不挖根因

对策:你要做"质检员",别盲信。失败 2 次必须让它换思路。

3. 新手最容易踩的 10 个坑

坑 1:指令太模糊

错:"帮我看看"
对:"看 src/order.py,告诉我 createOrder 函数的入参校验有没有漏边界情况"

坑 2:不告诉它怎么验证

错:"加个登录功能"
对:"加登录功能。改完跑 pnpm test,然后 pnpm dev 启动,告诉我可以从哪个 URL 测"

坑 3:期望它读心

错:"这块怎么改更好" (没说"这块"指哪块,也没说目标是性能/可读性/...)
对:"src/api.ts 第 42-58 行,我想让它支持取消请求。怎么改?"

坑 4:不用 `@` / IDE 选中传文件

错:复制 200 行代码粘贴到对话框
对:`@src/foo.py` 或在编辑器选中代码后直接说"这块改成..."

坑 5:让它干自己也不会的事

错:"优化这个慢查询" (你也不知道慢在哪)
对:"先 explain analyze 这个 SQL,然后告诉我哪里慢、怎么改"

坑 6:失败了继续让它"再试试"

失败 2 次必须停。直接说:“这个方向不对,换个思路从 Y 角度重新分析”。

坑 7:改完不让它跑构建

改了不跑构建 = 没改完。要么写到 CLAUDE.md(强制),要么每次说"改完跑 X"。

坑 8:把记忆当万能持久化

跨会话偏好 → 记忆 ✓
自动行为(每次保存自动 format) → 必须用 hooks,记忆没用
项目常识 → CLAUDE.md ✓
当前任务进度 → TodoWrite ✓

坑 9:权限弹框烦就一律允许

危险命令(rm -rf、git push --force、drop database)用 permissions.deny 写死。/fewer-permission-prompts 只整理高频只读命令的白名单。

坑 10:大任务不进 Plan 模式

跨多文件、不确定方案就先进 Plan 模式。让它先研究、出方案、你审批,然后再动。直接干很容易第三步发现路走错了。

4. 形态与模型

4.1 形态怎么选

你是	用
在 IDE 里写代码	VS Code / JetBrains 扩展(本手册主线)
在终端里干活、想脚本化	CLI(`claude`)
不想装东西、临时用	Web(claude.ai/code)
Mac/Win 桌面、长任务	桌面 App

4.2 模型怎么选

任务	模型	何时切
复杂推理、跨文件重构、棘手 bug	Opus 4.7(默认)	不用切
日常加功能、写测试、改 UI	Sonnet 4.6	觉得 Opus 慢且任务不复杂
改错别字、格式化、单文件查询	Haiku 4.5	明显简单的活

切换:/model 或 settings.json。

Fast 模式(/fast)只对 Opus 生效:更快,不降级模型。等不及但不想换 Sonnet 时用。

5. VS Code 扩展 UI 详解(截图每个按钮)

打开 Claude 侧边栏,你会看到一个动作面板(Filter actions... 输入框 + 各类菜单项)。这是核心控制中心,我把里面每一项都讲清楚。

5.1 顶部:Filter actions

筛选下方所有动作项的搜索框。记不住命令名时直接搜关键字(比如 “model”、“clear”)。

5.2 Context 区(上下文管理)

项	干啥	等价快捷键/命令
Attach file…	弹出文件对话框,把任意文件附到对话(可以是项目外的)	对话里 `@` 但范围更广
Mention file from this project…	项目内文件选择器,把文件路径插入消息	对话里输 `@`
Clear conversation	清空当前对话上下文,从零开始	`/clear`
Rewind	回到对话历史的某一轮,之后的全部丢弃(包括已做的工具调用)	类似 git reset

Rewind 用法:

你让 Claude 改代码,改坏了 → Rewind 到改之前那轮 → 重新提指令
注意 Rewind 不撤销已落盘的文件改动,只回滚对话状态。代码改动该手动撤销
适合实验性指令——觉得方向不对就 Rewind 重来,不用一直叠加修正

5.3 Model 区(模型/计算控制)

项	干啥
Switch model…	切换底层模型(Opus / Sonnet / Haiku),等同 `/model`
Effort	推理"用力"程度滑块(Low/Medium/High)。Low 快但浅,High 慢但深
Thinking	开关"扩展思考"。开启后 Claude 会显式做内心独白(内部推理可见),复杂问题更稳
Account & usage…	账号信息 + 当月 token 用量、剩余额度
Toggle fast mode	开关 Fast 模式,等同 `/fast`,只对 Opus 有效

Effort 滑块该怎么调:

任务	Effort
改错别字、单行 bug	Low
日常加功能、改 UI	Medium(默认)
架构决策、复杂重构、根因排查	High

Thinking 开/关怎么选:

何时开	何时关
复杂多步推理(算法、并发 bug)	简单查询
你想看到它的推理过程,验证逻辑	改格式、改名
给重要决策"二次思考"	速度优先

开 Thinking 会增加 token 用量(~30-50%),但显著提升复杂任务质量。

5.4 输入框(底部)

`Queue another message...`(队列消息)

Claude 正在干活时,别打断它——把下一条指令打进这里,排队等当前任务完成自动接上。

适合:你在它跑命令时想到补充要求(例如"改完顺便也跑下 lint")
不适合:发现方向错了——这种要按 Esc 中断,不是排队叠加

左下:`+`(附加)

等同上面的 Attach file。

左下:`☐`(空方块图标)

通常是 plan mode 切换 或 tool autoselect 开关(具体取决于扩展版本)。鼠标悬停看 tooltip。

右下:Edit automatically

关键开关——决定 Claude 改文件时要不要弹框确认。

状态	行为
Edit automatically 开	Edit/Write 自动执行,不弹框(快,但放权大)
Edit automatically 关	每次改文件都弹框让你审 diff(慢,但安全)

新手建议:先关着,前两周每次审 diff,熟悉 Claude 的行为模式。熟练后再开。

右下:`■`(实心方块)= 停止/中断

等同 Esc,中断当前回答。Claude 跑久了卡住时点这个。

5.5 没在截图里但常用的 UI 元素

右上角(扩展窗口顶部)

新会话:开一个全新对话(旧的保留在历史里)
历史:查看过往会话,可恢复

工具调用展开

Claude 跑工具时,UI 会显示一行折叠条 [Read src/foo.py]。点开看完整工具调用 + 返回结果。遇到错误展开看,别瞎猜。

权限弹框

执行需许可的工具时弹出,选项:

Allow once:本次允许
Allow for this session:本会话允许(下次还问)
Always allow:永久允许(写入 settings.json allow)
Deny:拒绝(Claude 会换个方式)

5.6 我的推荐配置(新手起步)

项	推荐值
Model	Opus 4.7
Effort	Medium
Thinking	关(熟悉后再开)
Fast mode	关
Edit automatically	关(前两周审 diff)

熟练后:

项	推荐值
Effort	简单 Low,日常 Medium,棘手 High(动态调)
Thinking	复杂任务前开
Edit automatically	开(配合好的 deny 规则保底)

6. 五分钟入门:必学 10 操作

1. @file 路径补全          引用文件进上下文
2. /help                  查所有命令
3. /init                  给项目生成 CLAUDE.md(第一天必做)
4. /clear                 切大主题前清空上下文
5. /compact               上下文快满时压缩
6. /review                改完代码自查
7. /memory                看记了什么
8. # 内容                 加跨会话记忆
9. Esc                    中断 Claude
10. /fewer-permission-prompts   减少权限弹框

最常见的 3 个操作:

改代码:直接说"在 X 文件把 Y 改成 Z"
找代码:“找所有用到 X 的地方”
改完后:“跑构建确认下”

7. Prompt 模板库(直接复制改)

实用经验:给 Claude 的指令越具体,质量越高。下面是验证过有效的模板。

3.1 改代码类

改名(单符号横跨工程)

把 <旧名> 改名为 <新名>。
1. 先 grep 全工程列出所有出现位置(包括字符串、注释、生成代码引用)
2. 排除生成产物目录 <build/dist/...>
3. 列影响清单给我审,通过后再动
4. 改完跑 <构建命令>

加新功能

在 <模块/文件> 里加 <功能描述>。
约束:
- 复用现有 <某工具函数/某基类>,不要新造
- 风格遵循同文件其他 <方法/类>
- 国际化文本走 <tr()/i18n.t()/...>
- 加 1 个最小单元测试
改完跑 <构建> + <测试命令>

修 bug

症状:<贴具体表现>
触发:<怎么复现>
错误日志/栈:<贴>

要求:
- 不要急着改,先定位根因
- 列出可能原因 + 你倾向哪个 + 为什么
- 我确认方向后再改
- 改完给出回归测试方案

3.2 探索类

摸清模块

解释 <文件/目录> 的职责。我要知道:
- 入口在哪
- 关键数据流(谁调谁,流向)
- 跟外部模块的边界(依赖谁,谁依赖它)
- 容易踩的坑
不要复述代码,直接讲结构。控制在 300 字内。

找东西

在 <目录1> 和 <目录2> 里找:<目标>
输出格式:每行一条 file:line — 一句话说明
不要解释找的过程,只给结果。

大型重构前调研

我打算把 <X> 重构为 <Y>。
派 Explore agent 并行做:
1. 列所有调用点
2. 列依赖此 X 的下游模块
3. 找已有的、可复用的相似抽象
完成后给我汇总,然后进 plan 模式出方案。

3.3 评审类

提交前自查

/review
重点看:
- 是否有遗漏的边界情况
- 是否破坏现有调用方
- 命名是否与项目其他地方一致
- 是否引入新依赖(尽量避免)

安全敏感改动

/security-review
我刚改了 <鉴权/IO/序列化/SQL> 相关代码。
特别检查:注入、越权、泄密、未校验输入。

3.4 控制类(让 Claude 行为更合心意)

让它别废话

回答用 100 字内 + 不要复述我的问题 + 不要末尾总结。

让它先问再做

开始前先问我 3 个最关键的问题,不要假设。

让它对照参考实现

按 <某文件/某类> 的风格写。先 Read 它,然后参照它的:
- 命名风格
- 错误处理方式
- 注释密度

让它停止反复 patch

你已经试了 2 次同类修改都没解决根本问题。
停下,**换一个完全不同的方向**重新分析根因。

8. 斜杠命令 + Skills 全表

命令	用	何时用
`/help`	帮助	忘命令
`/clear`	清空对话	切大主题
`/compact`	压缩历史	上下文 80%+
`/config`	配置面板	改主题模型
`/model`	切模型	临时省钱
`/fast`	Opus 加速	Opus 慢
`/memory`	记忆	看/编辑
`/agents`	子代理管理	自定义 agent
`/init`	生成 CLAUDE.md	项目 Day 1
`/review`	评审改动	提交前
`/security-review`	安全审查	改完敏感代码
`/simplify`	复审精简	觉得啰嗦
`/update-config`	改 settings.json	加权限/hooks
`/keybindings-help`	改快捷键	自定义热键
`/fewer-permission-prompts`	减权限弹框	用了一周后
`/loop <interval> <cmd>`	循环跑	监控 CI

9. 工具能力速览

Claude 自动调用,你只需了解能力边界:

工具	能	不能 / 注意
Read	读文本/PDF/图/Notebook	不能读目录,大文件用 offset/limit
Edit	精确替换	old_string 必须唯一,缩进必须一致
Write	写整文件	已存在文件必须先 Read,>50 行分块
Glob	文件名匹配	只列路径不读内容
Grep	ripgrep 内容搜索	字面量花括号要转义 `\{\}`
Bash	跑命令	Win 用 bash 语法,长任务后台化
Agent	派子代理	子代理无主对话上下文
TodoWrite	任务清单	同时只 1 个 in_progress
WebSearch	搜网页	仅美国
WebFetch	抓 URL	认证页面失败,GitHub 用 gh CLI

坑速查:

Win 路径用正斜杠 e:/path/to/file,带空格双引号包
CRLF vs LF 不一致 → Edit 易失败 → 项目统一为 LF
Tab vs 空格混用 → Edit 易失败 → 重读看清再改
不要让 Claude 用 Bash 跑 find/grep/cat/sed,有专用工具

10. Plan 模式

6.1 一句话:只读探索 + 方案审批

适合:多文件改、架构决策、不确定方案。
不适合:改错别字、单行改动。

6.2 触发与退出

操作	方式
进入	UI 切换 / "先做计划"指令 / Claude 主动
退出	Claude 调 `ExitPlanMode` 等审批 / 你说"退出 plan"

6.3 进入后会发生什么

Claude 派 ≤3 个 Explore agent 并行搜代码
派 1 个 Plan agent 出方案
用 AskUserQuestion 澄清歧义
写 ~/.claude/plans/<task>.md(唯一可写文件)
ExitPlanMode 等你点同意

6.4 计划文件该长什么样

# <任务标题>

## Context
为什么做、问题来源、预期结果

## 方案
1. 改 <file:line> 加 X
2. 改 <file:line> 改 Y
3. ...

## 关键文件
- src/foo.py:42-58
- src/bar.py:103

## 复用
- 已存在的 utils.parseDate() at src/utils.py:12

## 风险/回滚
- 风险:可能影响 X
- 回滚:`git revert <commit>` 或手动还原 N 处

## 验证
- 跑 pytest tests/foo
- 手动:启动服务,curl /api/x,期望返回 {...}

6.5 计划被拒绝的两种处理

方式一:局部调整
"方案的第 2 步不对,改成 Z 那种做法,其他保留"

方式二:推倒重来
"方向不对,从 Y 角度重新研究,之前的扔了"

11. Subagents 并行调度

7.1 三种类型

类型	工具	用
`Explore`	只读	找代码、定位、回答"X 在哪"
`Plan`	只读 + 思考	设计方案
`general-purpose`	全工具	真要写代码,可后台

7.2 并行的关键技巧

同一条消息派多个 agent = 真并行,分两条消息 = 串行。

快做法(并行,~6 秒):
  "找 X 的引用 + 找 Y 的初始化路径 + 找 Z 的所有实现"
  → Claude 一条消息派 3 个 Explore

慢做法(串行,~18 秒):
  "找 X 的引用"
  (等 6 秒)
  "找 Y..."

7.3 给子代理的 prompt 必须自包含

子代理没有主对话历史。所以 prompt 必须写明:

目标:要找什么 / 要设计什么
范围:哪些目录 / 哪些文件不看
格式:输出多长 / 什么形式
背景:已知什么、试过什么、为什么这么做

模板:

任务:<具体目标>
范围:<目录列表>
排除:<不看的目录>
背景:<为什么做这个、已知什么>
格式:<输出形式>,<字数限制>

7.4 何时派 vs 不派

场景	派吗
单文件、知道路径	不派,直接 Read
单关键字搜索	不派,直接 Grep
跨多目录、不确定	派 Explore
开放问题(架构是怎样的)	派 Explore
设计方案	派 Plan
长时间分析/构建	派 general-purpose 后台

12. Hooks 实战配置(直接复制改)

Hooks 是 harness 执行的强制自动化(Claude 不能不跑)。配在 ~/.claude/settings.json 或 <project>/.claude/settings.json 的 hooks 段。

8.1 事件总览

事件	触发	典型用途
`PreToolUse`	工具调用前	拦截危险命令、改参数
`PostToolUse`	工具调用后	自动跑 lint/format
`UserPromptSubmit`	用户发消息前	注入额外上下文
`Stop`	Claude 回答完	提示音、桌面通知
`SubagentStop`	子代理结束	子代理结果后处理
`SessionStart` / `SessionEnd`	会话起止	初始化/清理

8.2 配置:改完代码自动 format

Python(black)

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'f=\"${file_path}\"; [[ \"$f\" == *.py ]] && black -q \"$f\"'"
          }
        ]
      }
    ]
  }
}

JS/TS(prettier)

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'f=\"${file_path}\"; [[ \"$f\" =~ \\.(js|ts|jsx|tsx)$ ]] && npx prettier -w \"$f\"'"
          }
        ]
      }
    ]
  }
}

Go(gofmt)

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "bash -c '[[ \"${file_path}\" == *.go ]] && gofmt -w \"${file_path}\"'" }
        ]
      }
    ]
  }
}

C++(clang-format,Windows PowerShell)

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "powershell -c \"if ('${file_path}' -match '\\.(cpp|h|hpp|cc)$') { clang-format -i '${file_path}' }\""
          }
        ]
      }
    ]
  }
}

Rust(rustfmt)

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "bash -c '[[ \"${file_path}\" == *.rs ]] && rustfmt \"${file_path}\"'" }
        ]
      }
    ]
  }
}

8.3 配置:Claude 答完发声/通知

Windows 蜂鸣

{
  "hooks": {
    "Stop": [
      { "hooks": [
        { "type": "command", "command": "powershell -c \"[console]::beep(800,150)\"" }
      ]}
    ]
  }
}

macOS 系统通知

{
  "hooks": {
    "Stop": [
      { "hooks": [
        { "type": "command", "command": "osascript -e 'display notification \"Claude done\" with title \"Claude Code\"'" }
      ]}
    ]
  }
}

Linux(libnotify)

{
  "hooks": {
    "Stop": [
      { "hooks": [
        { "type": "command", "command": "notify-send 'Claude Code' 'Done'" }
      ]}
    ]
  }
}

8.4 配置:危险命令拦截

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'echo \"${tool_input.command}\" | grep -qiE \"(rm -rf /|drop database|truncate.*table|git push.*--force|git reset --hard)\" && echo BLOCK || echo ALLOW'"
          }
        ]
      }
    ]
  }
}

返回 BLOCK 时 harness 拦截。这是 permissions.deny 的补充——deny 是规则匹配,这里能写更复杂的逻辑。

8.5 配置:每次提交注入分支/状态

{
  "hooks": {
    "UserPromptSubmit": [
      { "hooks": [
        {
          "type": "command",
          "command": "bash -c 'echo \"[git: $(git branch --show-current 2>/dev/null) | $(git status --porcelain 2>/dev/null | wc -l) changes]\"'"
        }
      ]}
    ]
  }
}

每次你发消息前,这条会先注入一条上下文行(分支名 + 改动数),Claude 就知道当前 git 状态。

8.6 配置:改完代码自动跑测试

Python(pytest 影响范围)

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'f=\"${file_path}\"; if [[ \"$f\" == *src/*.py ]]; then test_file=\"tests/test_$(basename $f)\"; [[ -f \"$test_file\" ]] && pytest -x \"$test_file\" 2>&1 | tail -20; fi'"
          }
        ]
      }
    ]
  }
}

Go(改完跑包内测试)

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c '[[ \"${file_path}\" == *.go ]] && go test $(dirname \"${file_path}\")/... 2>&1 | tail -20'"
          }
        ]
      }
    ]
  }
}

8.7 调试 Hooks

不生效:重启 Claude Code 会话
看不到输出:hooks 输出在 UI 看不见,重定向到日志:>> /tmp/claude-hooks.log 2>&1
Win 引号问题:把命令拆成脚本文件,command 调脚本路径
占位符:${file_path} ${tool_input.command} 等,具体可用变量看 Anthropic 文档

13. MCP 接入

9.1 是什么

MCP(Model Context Protocol)= 外部工具/数据源的标准接入协议。装好后 Claude 多出 mcp__<server>__<tool> 形式的工具,用法与内置工具一样。

9.2 配置位置

~/.claude/settings.json 的 mcpServers 段:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "ghp_xxx" }
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "e:/projects"]
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://user:pass@host/db"]
    }
  }
}

9.3 高价值 MCP 推荐

服务器	干什么	谁该装
github / gitlab	issue / PR / 代码搜索	用 GitHub/GitLab 的人
filesystem	沙箱化文件系统访问	想限制 Claude 可见目录
postgres / sqlite	直接查数据库	后端开发
browser / puppeteer	浏览器自动化	前端 / 端到端测试
linear	issue 追踪	用 Linear 的团队
slack	发消息读频道	团队协作
memory(社区)	知识图谱式记忆	跨会话复杂上下文

9.4 排查

工具不出现:重启会话,看 VS Code “Claude” 输出面板日志
鉴权失败:检查 env 里 token
npx 慢:第一次启动会下载 server,慢正常,之后有缓存

14. 记忆系统

10.1 路径

~/.claude/projects/<project-id>/memory/
├── MEMORY.md                    索引,自动加载,200 行截断
├── user_<name>.md               你是谁
├── feedback_<name>.md           协作偏好
├── project_<name>.md            项目背景
└── reference_<name>.md          外部资源

<project-id> 是项目路径转义形式:e:\projects\foo → e--projects-foo。

10.2 四类该记什么

类型	例子
user	用户是 10 年 Python 老手,新接触 Rust
feedback	用户讨厌长篇总结,要求每次 ≤200 字
feedback	用户认可"一个 PR 打包多个相关改动"的做法,反对碎片化
project	项目 6 月 GA,5 月底功能冻结,新需求要老板批
reference	bug 在 Jira PROJ,oncall 看 grafana.internal/d/api

关键:feedback 不光记纠错,也要记确认(用户说"对就这样")。否则 Claude 只学到"避免 X",学不到"鼓励 Y"。

10.3 不要记的

不记	原因
代码规范、目录结构	读代码就知道
git 历史	git log 知道
调试方案	代码已修
当前进度	用 TodoWrite
CLAUDE.md 已有的	重复

10.4 记忆文件格式

---
name: short-kebab-slug
description: 一句话描述
metadata:
  type: feedback
---

规则本身

**Why:** 用户给的理由(过去事故 / 强偏好)
**How to apply:** 何时 / 哪里触发

10.5 用法

让记下来:  #内容    或   "记一下:..."
看记了啥:  /memory
不让用:    "这次不要用记忆"
忘掉:      "忘了关于 X 的记忆"

10.6 记忆 vs CLAUDE.md vs hooks

需求	用
跨项目个人偏好	全局 CLAUDE.md `~/.claude/CLAUDE.md`
单项目规范	项目 CLAUDE.md(入仓)
个人协作风格	记忆
强制自动行为	hooks
永远不允许某操作	settings 的 permissions.deny

15. CLAUDE.md 多语言模板

<project>/CLAUDE.md = 项目知识档案,每次进项目自动加载。入仓共享。

11.1 通用结构(任何语言)

# <项目名>

<一句话项目定位>

## 技术栈
- 语言/框架/版本
- 数据库/中间件
- 部署目标平台

## 构建/运行
- 安装依赖:<命令>
- 跑开发:<命令>
- 构建产物:<命令>
- 跑测试:<命令>
- 跑 lint:<命令>

## 目录约定
- src/ ...
- test/ ...
- (重点:每个目录的职责一句话)

## 代码风格
- 缩进/行尾
- 命名约定
- 注释密度
- 错误处理风格

## 不要碰
- 第三方代码目录
- 生成产物目录
- 配置敏感目录

## 常用排查
- 症状 X → 通常是 Y,看 Z

## 关键模块导航
- <模块> at <path> — 一句话职责

11.2 Python / Django 模板

# MyApp

电商订单后端,Django 4.2 + DRF + Postgres。

## 技术栈
- Python 3.11(pyenv 管理)
- Django 4.2 + DRF 3.14
- Postgres 15 / Redis 7
- pytest + pytest-django

## 构建/运行
- 装依赖:`uv sync`(用 uv,不用 pip)
- 跑开发:`python manage.py runserver`
- 跑测试:`pytest -x --reuse-db`
- 跑 lint:`ruff check . && ruff format --check .`
- 改 model 后:`python manage.py makemigrations && migrate`

## 目录
- `apps/orders/` 订单(本次主要工作区)
- `apps/payments/` 支付集成
- `core/` 共享 utils、middleware

## 风格
- 函数签名带 type hints,返回也要标
- 用 `from __future__ import annotations`
- ORM 查询尽量 `.only()` / `.select_related()` 防 N+1
- API view 用 DRF ViewSet,不用 FBV

## 不要碰
- `migrations/` 自动生成,不手编辑
- `.venv/`、`__pycache__/`

## 排查
- 测试连不上 DB → 检查 .env 里的 TEST_DATABASE_URL
- migration 冲突 → makemigrations --merge

11.3 Go 模板

# orderd

订单微服务,Go 1.22 + gRPC + Postgres。

## 构建
- `go build ./cmd/orderd`
- 跑测试:`go test ./...`
- 跑 lint:`golangci-lint run`
- 生成 proto:`buf generate`

## 目录
- `cmd/orderd/main.go` 入口
- `internal/order/` 业务逻辑
- `internal/store/` DB 层(sqlc 生成)
- `proto/` protobuf 定义

## 风格
- 错误返回 `fmt.Errorf("...: %w", err)` 包装,不要丢
- 不用全局变量,依赖注入
- context.Context 第一参数
- table-driven 测试

## 不要碰
- `internal/store/sqlc/` sqlc 生成
- `proto/gen/` buf 生成

11.4 TypeScript / React 模板

# webapp

订单管理前端,React 18 + TypeScript + Vite。

## 构建
- 装依赖:`pnpm install`(只用 pnpm)
- 跑开发:`pnpm dev`(端口 5173)
- 构建:`pnpm build`
- 跑测试:`pnpm test`(vitest)
- 跑 lint:`pnpm lint`

## 目录
- `src/components/` 通用组件
- `src/features/<x>/` 按功能切片(组件+hook+API)
- `src/api/` 后端调用,基于 tanstack-query
- `src/lib/` 工具

## 风格
- 优先函数组件 + hooks
- 状态优先 useState/useReducer,跨组件用 zustand
- API 调用一律 useQuery/useMutation,不要直接 fetch
- 严格 TS,no any

## 不要碰
- `dist/`、`node_modules/`
- 自动生成的 `*.gen.ts`

11.5 Rust 模板

# rustsvc

REST 服务,Axum + Tokio + sqlx。

## 构建
- `cargo build`
- 跑:`cargo run --bin server`
- 测试:`cargo test`
- lint:`cargo clippy -- -D warnings`
- format:`cargo fmt`

## 目录
- `src/bin/server.rs` 入口
- `src/handlers/` HTTP 处理
- `src/domain/` 业务实体
- `src/infra/` DB / 外部服务

## 风格
- 用 `anyhow::Result` 在边界,内部用具体 error 类型
- async fn 默认,不阻塞 runtime
- 不要 unwrap,边界用 `?`,真 panic 用 `expect("reason")`

## 不要碰
- `target/`、`Cargo.lock`(改了报告我)

11.6 C++ / Qt 模板(VSClient 风格)

# VSClient

视频会议客户端,Qt 5.15 + C++17,Windows 平台。

## 工作目录
- `e:/HIIKEngineeringcode/VSClient/`         主工程
- `e:/HIIKEngineeringcode/VideoComponents/`  共享组件
- `e:/HIIKEngineeringcode/broadcast.c/`      底层 C 库

## 构建
- 调试:`qmake -r CONFIG+=debug && nmake`
- 发布:`msbuild VSClient.sln /p:Configuration=Release /p:Platform=x64`
- 翻译:`lupdate VSClient.pro && lrelease VSClient.pro`

## 工具链
- Qt 5.15.2(`C:/Qt/5.15.2/msvc2019_64`)
- MSVC 2019
- 环境变量 `QTDIR` 必须设

## 风格
- 行尾 LF,不 CRLF
- 信号槽用新语法 `connect(s, &S::sig, r, &R::slot)`
- 文本 `tr("...")` 包裹
- C++17,慎用 std::filesystem
- include 顺序:Qt → 项目 → 标准库

## 不要碰
- `code/3rdparty/`     第三方库
- `code/build/`        构建产物
- `code/translations/*.qm`  自动生成
- `*.user`             VS 用户配置

## 排查
- moc 报错:`qmake -r` 重新生成 Makefile
- 信号槽不触发:检查新旧语法没混用
- 翻译不生效:`lrelease` 跑了吗

11.7 维护建议

新项目 Day 1 跑 /init 起草,然后手动改
大架构变化后 review 一次
不要写易过时的细节(具体函数签名)
入仓共享,所有人协作一致
多层级:子目录可单独有 CLAUDE.md(src/payments/CLAUDE.md),叠加在项目根上

11.8 全局 `~/.claude/CLAUDE.md`(个人偏好)

# 我的偏好

## 输出
- 中文回复,代码标识符英文
- ≤200 字直接答,长任务再展开
- 不要末尾总结,我能读 diff
- 不要复述我的问题

## 工具
- Win + git-bash,bash 语法
- 编辑器 VS Code

## 风格
- 不写废话注释
- 边界做防御,内部信任
- 失败 2 次必须换思路,不要小修小补

16. settings.json + 权限多语言模板

12.1 三层配置文件(覆盖优先级:低 → 高)

层	路径	用途
用户全局	`~/.claude/settings.json`	跨所有项目
项目共享	`<project>/.claude/settings.json`	团队共享,入仓
个人本地	`<project>/.claude/settings.local.json`	个人覆盖,gitignore

合并规则:对象深合并,数组拼接。

12.2 用户全局模板(通用)

{
  "model": "claude-opus-4-7",
  "fastMode": false,
  "theme": "dark",
  "permissions": {
    "allow": [
      "Read(**)", "Glob(**)", "Grep(**)",
      "Bash(ls:*)", "Bash(pwd)", "Bash(echo:*)",
      "Bash(git status:*)", "Bash(git diff:*)",
      "Bash(git log:*)", "Bash(git branch:*)", "Bash(git show:*)"
    ],
    "deny": [
      "Bash(rm -rf:*)", "Bash(rm -r:*)",
      "Bash(git push --force:*)", "Bash(git reset --hard:*)",
      "Bash(git clean -f:*)", "Bash(git branch -D:*)",
      "Read(**/.env*)", "Read(**/secrets/**)",
      "Read(**/*.key)", "Read(**/*.pem)",
      "Write(**/.env*)"
    ],
    "ask": [
      "Bash(git push:*)", "Bash(git commit:*)",
      "Bash(npm install:*)", "Bash(pip install:*)",
      "Bash(curl:*)", "WebFetch(**)"
    ]
  }
}

12.3 各语言追加片段

Python

{ "permissions": { "allow": [
  "Bash(python:*)", "Bash(pytest:*)", "Bash(ruff:*)",
  "Bash(mypy:*)", "Bash(uv run:*)", "Bash(black:*)",
  "Edit(src/**)", "Edit(tests/**)"
], "deny": ["Edit(.venv/**)", "Edit(**/migrations/**)"] }}

Go

{ "permissions": { "allow": [
  "Bash(go build:*)", "Bash(go test:*)", "Bash(go mod:*)",
  "Bash(golangci-lint:*)", "Bash(buf:*)",
  "Edit(internal/**)", "Edit(cmd/**)"
], "deny": ["Edit(vendor/**)", "Edit(**/proto/gen/**)"] }}

JS/TS

{ "permissions": { "allow": [
  "Bash(pnpm:*)", "Bash(npx:*)", "Bash(node:*)", "Bash(vitest:*)",
  "Edit(src/**)", "Edit(tests/**)"
], "deny": ["Edit(node_modules/**)", "Edit(dist/**)", "Edit(.next/**)", "Edit(**/*.gen.ts)"] }}

C++/Qt(VSClient)

{
  "env": { "QTDIR": "C:/Qt/5.15.2/msvc2019_64" },
  "permissions": {
    "allow": [
      "Bash(qmake:*)", "Bash(nmake:*)", "Bash(msbuild:*)",
      "Bash(lupdate:*)", "Bash(lrelease:*)",
      "Edit(code/**)", "Edit(test/**)"
    ],
    "deny": [
      "Edit(code/3rdparty/**)", "Edit(code/build/**)",
      "Edit(**/*.user)", "Edit(**/*.qm)"
    ]
  }
}

Rust

{ "permissions": { "allow": [
  "Bash(cargo build:*)", "Bash(cargo test:*)", "Bash(cargo run:*)",
  "Bash(cargo clippy:*)", "Bash(cargo fmt:*)",
  "Edit(src/**)", "Edit(tests/**)"
], "deny": ["Edit(target/**)"] }}

12.4 权限 DSL 语法

Tool(子模式)         精确匹配
Tool(子模式:*)       前缀(任意参数)
Tool(*)              任何参数

工具维度:

Bash(<命令前缀>:*)
Read/Edit/Write/Glob/Grep(<glob>)
WebFetch(<URL 模式>)
mcp__<server>__<tool>

优先级:deny > ask > allow。

12.5 用过几天后,自动整理

/fewer-permission-prompts

扫历史,自动写入项目 settings。能省一大半弹框。

17. 上下文管理与省 token

13.1 窗口

模型	窗口
Opus 4.7	1M tokens
Sonnet 4.6	200K
Haiku 4.5	200K

13.2 自动压缩

接近 80% 时 harness 自动总结早期对话 + 保留最近原文。压缩后 Claude 重读最近文件状态校验位置,不凭摘要继续干。

13.3 省 token 5 招

不要 @ 整个目录 → 引用具体文件
大搜索派 Subagent → 子代理用自己窗口
切大主题前 /clear → 旧上下文价值小就扔
长对话定期 /compact → 主动管理
简单任务切 Sonnet/Haiku → 便宜 4-5x

13.4 prompt caching

重复内容自动命中缓存(5 分钟 TTL)。同一会话连续读同一文件,后续不重复扣费。

13.5 跨会话保留 vs 不保留

保留	不保留
记忆	对话历史
CLAUDE.md	TodoWrite
计划文件	Worktree(除非 keep)
settings.json
调度任务(durable)

18. 5 套实战流程

A. 小修复(1 文件 ≤5 行)

直接说"在 X 把 Y 改成 Z"。不进 Plan、不派 agent。

B. 中型特性(2-5 文件)

"在 <模块> 加 <功能>。
约束:复用 <现有工具>,风格跟 <参考文件>,加 1 个测试。
改完跑 <构建>。"

C. 大型重构

进 Plan 模式
派 2-3 Explore 并行扫
Plan agent 出方案
AskUserQuestion 澄清
写计划文件 → ExitPlanMode 审批
分多次提交,每步跑构建

D. 故障排查

"症状:<贴> | 触发:<怎么复现> | 栈:<贴>
要求:不要急着改,先列可能根因,我确认方向再动。"

失败 2 次后强制换方向,不要小修小补。

E. 代码评审

/review            通用
/security-review   敏感(认证/IO/SQL)
/simplify          找重复/过度抽象

19. 项目落地案例

15.1 C++/Qt(VSClient,Windows)

非 git 仓库。改一个 Q_OBJECT 类牵动:.h / .cpp / moc / connect / .ts / .ui。

标准指令:

改 <类> 的 <方法>:
1. 先 grep 全工程列影响(.h/.cpp/.ui/.ts/connect)
2. 列清单给我,我审完再改
3. 改完跑 qmake -r && nmake 2>&1 | tail -50

特殊:

改 Q_OBJECT 必须 qmake -r 重生成 Makefile
Worktree 不可用(非 git),改前手动备份
跨目录(VSClient + VideoComponents + broadcast.c)派 3 个 Explore 并行

15.2 Python / Django

改 <model>:
1. makemigrations 看生成的 migration
2. 跑 pytest -x apps/<x>/tests/
3. ruff check

特殊:ORM 性能用 .only() / .select_related() 防 N+1;migration 不手编辑。

15.3 Go 微服务

改 <handler>:加表驱动测试 → go test ./internal/<x>/... → golangci-lint run

特殊:错误必须 %w 包装;改 proto 跑 buf generate;改 sqlc 查询跑 sqlc generate。

15.4 Web(React/TS)

加 <组件>:src/features/<x>/ 切片 → useQuery 不直接 fetch → pnpm test → 浏览器实测

特殊:UI 改完必须实测(Claude 不能看屏幕);强 TS 不要 any;pnpm 锁版本。

15.5 通用规则(任何项目)

Day 1:/init 起草 CLAUDE.md
第一周:/fewer-permission-prompts
每次改完:跑构建/测试,不跑就是没改完
失败 2 次:换思路
大改动:进 Plan 模式

20. 排错 FAQ

Q1 权限弹框过多

/fewer-permission-prompts,或手动加 permissions.allow。

Q2 Claude 总忘事

跨会话忘 → 记忆;项目常识 → CLAUDE.md;强制行为 → hooks。

Q3 上下文爆掉

/compact、派 Subagent 隔离、/clear。

Q4 子代理跑偏

prompt 写明:范围 + 输出格式 + 字数 + 是研究还是写代码。

Q5 Windows 路径报错

正斜杠 e:/path、空格双引号、绝对路径不用 cd 拼。

Q6 同一问题反复出错

失败 2 次必须停下分析根因。直接说:“换思路,不要继续这个方向”。

Q7 Claude 改了不该改的

加 permissions.deny,优先级最高。

Q8 hooks 不触发

重启会话;检查 JSON;命令重定向到日志确认调用。

Q9 输出太长

prompt 加 “≤200 字”;用列表;派 Subagent。

Q10 Claude 不主动跑构建

写到 CLAUDE.md:“改完 X 必须跑 Y”。

Q11 模型变慢

/fast、/model claude-sonnet-4-6、/compact。

Q12 多人协作记忆冲突

记忆本地不共享,团队共享用 CLAUDE.md。

Q13 Claude 卡在工具调用

Esc 中断,问"刚才在干什么、为什么卡住"。

Q14 拒绝某工具后 Claude 重试

明确说:“不要再用 X,用 Y 替代”。

Q15 项目第一次进入,Claude 说不知道

跑 /init。或:“读 README + 主入口文件,建立认知”。

21. 速查表

命令

基础:  /help /clear /compact /config
模型:  /model /fast
项目:  /init /review /security-review /simplify
配置:  /update-config /keybindings-help /fewer-permission-prompts
记忆:  /memory  #内容
代理:  /agents
调度:  /loop <interval> <cmd>

输入符号

@   引用文件      /   命令/skill      #   加记忆
Esc 中断          Shift+Enter 换行

配置文件位置

~/.claude/settings.json              全局
~/.claude/CLAUDE.md                  全局偏好
~/.claude/keybindings.json           快捷键
~/.claude/projects/<id>/memory/      记忆
~/.claude/plans/                     计划
~/.claude/skills/<name>/SKILL.md     自定义 Skill
<project>/.claude/settings.json      项目共享
<project>/.claude/settings.local.json 个人本地
<project>/CLAUDE.md                  项目知识

决策树

任务来了
├── 1 文件 ≤5 行 ─────→ 直接说改
├── 单文件加东西 ────→ 让 Claude 写 + 跑构建
├── 多文件改动 ──────→ 进 Plan 模式
│   └── 不确定方案 ──→ 派 Explore 并行探索
├── 故障排查 ────────→ 贴错误,让 Claude 推根因
└── 提交前 ──────────→ /review

黄金法则

指令具体:文件路径、行号、目标、约束都给
失败 2 次换思路,不要小修小补
改完跑构建,不跑就是没改完
大改进 Plan,小改直接干
大搜派 Subagent,主上下文要省

https://edu.csdn.net/learn/39067/627173?utm_source=2019755004

汇聚全球AI编程工具，助力开发者即刻编程。

更多推荐

DeepSeek官方推荐的DeepCode，值不值得装？一次性讲清楚！

AI编程社区

2026 主流 AI 编码全景对比表

AI编程社区

【从零学Vibe Coding】第六章：主流 Vibe Coding 工具大全

本文系统梳理了2025年主流AI编程工具的特点与适用场景。重点介绍了6款工具：Cursor（深度整合AI的IDE）、GitHub Copilot（GitHub生态插件）、Claude Code（终端AI工程师）、ChatGPT（综合思考伙伴）、Windsurf（强调代理协作的IDE）和Trae（激进的多Agent IDE）。通过对比表格和决策树，帮助开发者根据自身需求选择工具：新手建议从ChatG

AI编程社区

所有评论(0)

查看更多评论

m0_63237995

@m0_63237995

已为社区贡献1条内容

一篇文章Claude Code 从入门到入土

m0_63237995

Claude Code 从入门到入土

0. 导航

新手路线(按顺序读)

进阶路线

全章目录

1. Claude Code 是什么、能干什么(新手必读)

1.1 一句话定义

1.2 它能干什么(具体例子)

1.3 它不能干什么

1.4 我什么时候不该用它

1.5 学习曲线

2. 它是怎么工作的(底层模型)

2.1 一次对话发生了什么

2.2 它有"上下文窗口"

2.3 工具是它的"手和眼"

2.4 安全机制

2.5 它会犯什么错

3. 新手最容易踩的 10 个坑

坑 1:指令太模糊

坑 2:不告诉它怎么验证

坑 3:期望它读心

坑 4:不用 @ / IDE 选中传文件

坑 5:让它干自己也不会的事

坑 6:失败了继续让它"再试试"

坑 7:改完不让它跑构建

坑 8:把记忆当万能持久化

坑 9:权限弹框烦就一律允许

坑 10:大任务不进 Plan 模式

4. 形态与模型

4.1 形态怎么选

4.2 模型怎么选

5. VS Code 扩展 UI 详解(截图每个按钮)

5.1 顶部:Filter actions

5.2 Context 区(上下文管理)

5.3 Model 区(模型/计算控制)

5.4 输入框(底部)

Queue another message...(队列消息)

左下:+(附加)

左下:☐(空方块图标)

右下:Edit automatically

右下:■(实心方块)= 停止/中断

5.5 没在截图里但常用的 UI 元素

右上角(扩展窗口顶部)

工具调用展开

权限弹框

5.6 我的推荐配置(新手起步)

6. 五分钟入门:必学 10 操作

7. Prompt 模板库(直接复制改)

3.1 改代码类

改名(单符号横跨工程)

加新功能

修 bug

3.2 探索类

摸清模块

找东西

大型重构前调研

3.3 评审类

提交前自查

安全敏感改动

3.4 控制类(让 Claude 行为更合心意)

让它别废话

让它先问再做

让它对照参考实现

让它停止反复 patch

8. 斜杠命令 + Skills 全表

9. 工具能力速览

10. Plan 模式

6.1 一句话:只读探索 + 方案审批

6.2 触发与退出

6.3 进入后会发生什么

6.4 计划文件该长什么样

6.5 计划被拒绝的两种处理

11. Subagents 并行调度

7.1 三种类型

7.2 并行的关键技巧

7.3 给子代理的 prompt 必须自包含

7.4 何时派 vs 不派

12. Hooks 实战配置(直接复制改)

坑 4:不用 `@` / IDE 选中传文件

`Queue another message...`(队列消息)

左下:`+`(附加)

左下:`☐`(空方块图标)

右下:`■`(实心方块)= 停止/中断

11.8 全局 `~/.claude/CLAUDE.md`(个人偏好)