vibe Coding -- 小项目实战

Claude Code 深度使用与进阶技巧

3.4 Claude Code 实战工作流

3.4.1 官方推荐工作流：Explore → Plan → Implement → Commit

Claude Code 的常见推荐工作流可以概括为 四阶段：

1. Explore（探索）：Plan Mode 下读代码、搜引用，搞清楚现状
2. Plan（规划）：出方案、评估边界情况，你审核
3. Implement（实施）：切出 Plan Mode，按方案执行
4. Commit（提交）：生成 commit message，提交

一轮结束后，回到第 1 步开始下个任务。

各阶段详解：

阶段	你该做什么	AI 在做什么	推荐模式
① Explore（探索）	告诉 AI 要改动的区域	读相关文件、grep、跟引用	Plan Mode
② Plan（规划）	让 AI 出详细方案并由你审核	生成计划、评估边界情况	Plan Mode
③ Implement（实施）	切出 Plan Mode 按计划执行	按顺序修改文件、运行构建	Normal / Auto-Accept
④ Commit（提交）	让 AI 生成提交消息并 commit	生成 commit message、可选开 PR	Normal

提示： 为什么要分阶段？ 试想一下这种体验：你说"加个软删除功能"，15 分钟后 AI 改了 14 个文件、动了全局查询过滤器、破坏了 3 个现有接口------你只能一个一个手工回退。这就是不规划直接干的代价。 在 Plan Mode 里多花 5 分钟讨论方案，换来执行阶段节省 30 分钟返工。Plan Mode 的详细用法在 4.9 节 详讲。

3.4.2 项目设置（6个应该习惯性做的动作）

在开始一个新项目之前，完成以下 6 项设置能让后续开发顺利多倍：

Step 1: 项目初始化
  ↓ 描述项目目标 → AI 生成项目骨架
Step 2: 建立 CLAUDE.md（项目上下文）
  ↓ 可运行 `/init` 让 AI 自动生成
Step 3: 配置权限与默认模式
  ↓ .claude/settings.json、复杂项目可默认 plan 模式
Step 4: 功能开发
  ↓ 一次一个功能，逐个 Explore→Plan→Implement
Step 5: 代码审查与测试
  ↓ 用 /review 让 AI 生成测试并跑起来
Step 6: 提交代码
  ↓ git commit 保存进度

3.4.3 完整示例：用 Claude Code 创建一个 Express Hello World API

Step 1：初始化项目

# 创建项目目录
$ mkdir hello-api
$ cd hello-api

# 启动 Claude Code
$ claude

在 Claude Code 的plan mode中输入：

> 我想要使用node.js构建一个前端页面，最后能显示出hello ai coding 几个字，端口号使用3000

AI 会依次执行以下操作（每一步都会请求你确认）：

[Claude Code] 将运行命令: npm init -y
→ 确认？(y/n) y

[Claude Code] 将运行命令: npm install express
→ 确认？(y/n) y

[Claude Code] 将创建文件: app.js
→ 确认？(y/n) y

预期生成的核心代码（app.js）：

// 引入 Express 框架
const express = require('express');

// 创建应用实例
const app = express();

// 定义端口号
const PORT = 3000;

// 定义 GET /hello 路由
app.get('/hello', (req, res) => {
  // 返回 JSON 格式的响应
  res.json({ message: 'Hello AI Coding!' });
});

// 启动服务器
app.listen(PORT, () => {
  console.log(`服务器已启动，访问 http://localhost:${PORT}/hello`);
});

Step 2：运行并验证

在 Claude Code 中输入：

> 请启动这个服务器，然后用 curl 测试 /hello 端点

AI 执行的操作：

[Claude Code] 将运行命令: node app.js
→ 确认？(y/n) y

输出: 服务器已启动，访问 http://localhost:3000/hello

你也可以打开浏览器访问 http://localhost:3000/hello，应该看到：

{
  "message": "Hello AI Coding!"
}

验证：如果浏览器能看到上面的 JSON 响应，恭喜！你用 Claude Code 成功创建了第一个 API！

Step 3：提交代码

> 请帮我初始化 Git 仓库并提交当前代码，commit message 为 "初始化 Express Hello World API"

AI 会执行：

git init
git add .
git commit -m "初始化 Express Hello World API"

3.5 Claude Code 最佳实践

3.5.1 Prompt 编写技巧（针对 Claude Code 场景）

1. 任务描述要具体，不要模糊

 差：帮我做一个登录功能
 好：在 /api/auth/ 目录下创建登录 API：
   - POST /api/auth/login
   - 接受 { email, password }
   - 使用 bcrypt 验证密码
   - 成功返回 JWT token
   - 使用项目已有的 prisma client 查询 User 表

2. 引用已有代码作为参考

 好：参考 /api/bookmarks/route.ts 的风格，
   为 /api/tags/ 创建类似的 CRUD 接口。
   数据模型参见 prisma/schema.prisma 中的 Tag 表。

3. 先让AI制定计划，确认后再执行

 好：我想给书签管理器添加搜索功能。
   请先分析一下需要修改哪些文件，列出计划，
   等我确认后再开始实现。

4. 一次只做一件事

 差：帮我同时添加搜索功能、标签管理、用户认证和导出功能
 好：帮我先实现书签搜索功能。具体需求：
   - 在书签列表页面添加搜索框
   - 支持按标题和描述搜索
   - 搜索时实时过滤结果（前端过滤即可）

3.5.2 上下文管理策略（快速参考）

上面 /compact 详解已覆盖核心操作，这里给你一个快速决策表：

你观察到的情况	是什么问题	该怎么做
响应变慢、质量下降	上下文快满了	/context 看占比 → 高于 60% 就 /compact
AI 开始"遗忘"早期约定	早期信息被挤出窗口	立即 /compact
AI 重复问已回答过的问题	上下文混乱	/clear 开新会话
要切换到完全不同的任务	避免上一个任务的思路污染	/clear 开新会话
想永久记住某条规则	跨会话记忆	/memory 开启 Auto Memory 或写入 CLAUDE.md

3.5.3 Git 集成最佳实践

在深入 Git 技巧之前，先给你一个直观理解：Git 就是你的"游戏存档系统"。哪怕你不是程序员，只要在用 cc 做项目，Git 都是你的生命线。

想象你玩一个 RPG 游戏：打到 BOSS 前存个档 → 打输了就读档重来 → 打赢了就存新档继续。Git 在项目中就是完全一样的东西：打到一个满意的节点存一档，后面翻车就读档回来。

注意： cc 有不确定性，这不是 bug 是特性 ：cc 不管是写代码还是其他文档操作，都有不确定性------同一个需求问两次，可能得到不同的实现。所以养成一个肌肉记忆：每做完一步就让 cc 存档一步。有 Git 兜底，你才能安心让 cc 去尝试各种方案。

Mac 自带 Git，Windows 让 cc 帮你装。最好建个 GitHub 账号------远程仓库可以让你在其他电脑上拉下存档点继续工作，也方便协作。Git 的下载、安装、登录、提交、回滚，全都可以让 cc 用自然语言帮你完成，比如说：

> 帮我下载 Git 并跟我的 GitHub 账号绑定
> 帮我把现在的代码提交到远程仓库
> 回滚到上一个存档版本

黄金法则：在让AI做大修改之前，先 commit

开发流程：
1. git commit → 保存当前状态（"存档"）
2. 让 AI 实现新功能
3. 测试功能是否正常
   ├── 正常 → git commit → 继续下一个功能
   └── 有问题 → git checkout . → 回到步骤1，换个方式重试

# 实际命令示例

# 1. 开始新功能前，先保存
$ git add . && git commit -m "开始添加搜索功能前的存档"

# 2. 在 Claude Code 中实现功能...
# （如果功能做坏了）

# 3. 回退到存档点
$ git checkout .

# （如果功能做好了）
# 3. 保存新功能
$ git add . && git commit -m "完成搜索功能"

避坑 ：很多初学者不 commit 就让 AI 大改特改，结果改坏了却无法回退。这是AI编程中最常见也最痛苦的失误。"改之前先存档"，记住这句话。

3.5.4 费用控制策略

策略	方法	节省比例
分级使用	简单任务用 Haiku/DeepSeek，复杂任务用 Sonnet	30-50%
精准描述	减少来回修改次数	20-30%
及时 /compact	避免重复发送长上下文	10-20%
使用 /cost 监控	实时了解消耗	-
设置预算上限	Anthropic Console 中设置月度限额	防止超支

> /cost

AI: 当前会话费用统计：
   输入 Token: 15,234
   输出 Token: 8,721
   估算费用: $0.18

3.5.5 大型代码库最佳实践（Anthropic 官方推荐）

以上技巧偏通用。如果你接手的是一个多人协作、几十万行以上的大型代码库，Anthropic 官方在大型代码库实践中给出过多条专门建议。核心矛盾是：即使模型上下文已经很长，真实代码库仍然可能远超窗口上限。前 3 条是纪律，后 3 条是武器。

① 用 /init 自动生成 CLAUDE.md（项目初始化）

第一次在一个新项目里跑 Claude Code，第一件事就是 /init：

> /init

AI 会自动浏览项目目录、识别技术栈、读 README 和关键配置文件，生成一份初版 CLAUDE.md。然后你只要在它的基础上手工补充三类信息：

必补内容	为什么	示例
项目目录地图	让 AI 知道"去哪儿找代码"	认证逻辑在 src/auth/，UI 组件在 src/components/
不要碰的禁区	防止 AI 改坏	不要修改 prisma/migrations/，不要动 vendor/
团队约定	风格统一	所有 API 必须返回 { success, data, error }

提示： CLAUDE.md 是"起点上下文"，不是"全部上下文"。它就像一份给新人的入职手册，AI 看完后再现场探索代码------这正是 Agentic Search 的工作方式（参见 2.2.1 节）。

② 任务粒度要小且聚焦（避免"万能 prompt"）

大型代码库里最害人的就是"一句话扔给 AI 整个大需求"。正确做法：

 反例：帮我重构整个支付模块，加入新风控、新对账、新通知、新报表
 正解：第一步------在 src/payment/risk/ 下抽出风控规则引擎，
       接口签名见 docs/risk-rules.md，先不动调用方代码

经验值：每个 Claude Code 任务 ≤ 涉及 5 个文件 / 200 行代码改动。超过这个量级就该拆。

③ 频繁重置上下文（/clear 是好朋友）

很多新手以为对话越长 AI 越懂自己，这恰恰是大型代码库里最大的坑：

• 上下文里塞的越多，无关代码片段越多，AI 越容易抓错重点
• 上一任务的失败尝试、错路径、错假设，会污染下一个任务

官方建议：

时机	操作	区别
一个独立任务结束（PR 提交后）	/clear	完全清空对话，从零开始
同一任务内对话过长	/compact	压缩历史摘要，保留关键决策
想换条思路重做	退出 claude 重新启动	连状态栏模式都重置

核心心法 ：宁可"多 clear 几次重新介绍背景"，也不要"一直聊一直聊"。每个 /clear 都是给 AI 一次重新聚焦的机会。

④ 复杂任务从 Plan Mode 起手（权限控制）

详见 4.9 节。一句话：陌生代码库或一动牵全身的修改，永远先 /plan 或 Shift+Tab×2，让 AI 在只读模式下先勘探出方案再动手，回退成本几乎为零。

⑤ 用 Skills 与 Subagents 卸载长任务

大型代码库里有些"调研型任务"天生很费 token：

• 找出所有调用了某废弃 API 的地方
• 梳理某个模块的依赖图
• 跨 50 个文件的批量重命名前的影响评估

这类任务不要让主会话亲自做，而是：

• 派 Subagent：让一个独立的子代理去调研，最后只把结论带回主上下文（Plan Mode 下会自动调用）
• 写成 Skill：把高频调研流程封装成 Skill，每次一键触发（详见第四部分）

这样主会话的上下文窗口尽量留给"看结论、做决策、写代码"这些核心动作。

⑥ 接入 MCP / LSP（给 AI 装上团队协作工具）

一个真正的工程师不是只看代码，还会查 Jira、读 Confluence、连数据库、用 IDE 的"跳到定义"。Claude Code 通过 MCP（Model Context Protocol） 把这些能力接进来：

接入对象	解决什么	典型场景
GitHub MCP	读 PR、Issue、CI 日志	"这个 bug 在 PR #1234 里讨论过，看一下"
数据库 MCP（Postgres / MySQL）	直接查数据	"线上 user 表里有多少条 deleted_at 不为空的"
Jira / Linear MCP	读任务卡	"按 PROJ-123 的需求实现"
LSP（语言服务器）集成	精确跳转、查类型、找引用	等同于 IDE 的"查找所有引用"
Sentry / Datadog MCP	读告警、堆栈	"上一小时的 5xx 错误调一下"

提示： 配置入口 ：.claude/settings.json 中的 mcpServers 字段，或运行 claude mcp add ...。MCP 详细配置在第四部分 3.6 节讲解。

3.5.6 大型代码库最佳实践速查表

实践	命令/入口	何时做	收益
项目初始化	/init + 手工补充	第一次进入项目	让 AI 知道地图与禁区
任务拆分	心法（无命令）	每次提需求前	避免 AI 改坏一大片
上下文重置	/clear / /compact	任务结束 / 上下文过长	避免污染、节省 token
规划优先	/plan 或 Shift+Tab×2	复杂任务起手	先勘探后动手
任务卸载	Subagent / Skill	高频调研类任务	保护主上下文
工具接入	claude mcp add ...	项目初配	让 AI 看见"代码之外"

3.5.7 三个容易被忽视的官方进阶建议

这三点在官方博客里被反复强调，但实际使用中最容易被新手跳过。

1. 在子目录初始化 Claude，别从仓库根目录开始

这点在 monorepo 里反直觉但极重要：

 反例：在 monorepo 根目录下启动
user@monorepo $ claude
# AI 看到三百个服务、上千个包，上下文污染严重

 正解：进入你要改的子目录启动
user@monorepo $ cd services/payment
user@monorepo/services/payment $ claude
# Claude 会自动向上遍历加载所有 CLAUDE.md（根目录的也会加）
# 但工作范围被精准限定在了相关代码区域

配套做法 ：每个子目录都放一份小的 CLAUDE.md，写明该目录专用的测试与 lint 命令。不要让 AI 改了一个服务就去跑整个仓的测试套件------那就等着超时吧。

2. 配置要定期审查（每 3-6 个月）

为当前模型写的指令，在下一代模型上可能适得其反。官方举了两个真实例子：

过期配置	何时有效	为何失效
CLAUDE.md 里要求"每次重构只改一个文件"	老模型需要保持专注	新模型能跨文件协调编辑，这条反而是枷锁
Hook 每次文件写入时跑 p4 edit	Claude 未原生支持 Perforce 时	Claude Code 已原生支持 Perforce，这个 Hook 变多余

提示： 实践建议 ：设个日历提醒，每 3-6 个月、或每次大模型发布后，重读一遍 CLAUDE.md / .claude/settings.json / .claude/hooks / .claude/skills，问三个问题："这条还需要吗？""现在有更好的写法吗？""这条是在弥补哪代模型的缺陷？"
注意： 预警信号 ：如果你觉得 Claude Code 表现到了某个瓶颈怎么也上不去，问题很可能不在模型，而在你的配置没跟上。模型都已经往前跑了，你的 CLAUDE.md 可能还停在三个月前。

3. 团队内应该有个"人"负责 Claude Code（DRI / Agent Manager）

这点是面向团队使用者的，个人开发者可以跳过。Anthropic 观察到：推广最快的组织，都是"先有一小队人把基础设施搭好"才大面积开放的。

规模	必须人选	职责
小团队（< 20 人）	DRI（直接责任人），选一个有兴趣的人选充当	项目级 CLAUDE.md、共享的 Skills、Plugins 选型
中型企业	Agent Manager（半PM 半工程师）	跨团队推行、权限策略、接入安全与合规
大型/金融医疗受监管企业	跨职能工作组	工程 + 安全 + 治理 + 合规代表同桌定义需求与路线图

提示： 为什么重要 ：开发者第一次接触 Claude Code 的体验决定了后面全公司顺不顺推。如果第一次就是"AI 乱改东西"，要翻盘就难了。"野蛮生长"能激发热情，但缺了组织层面的收敛，好实践会变成"部落知识"。

3.5.8 企业级部署三阶段（面向团队负责人）

如果你是要在企业里推广 Claude Code 的人，Anthropic 推荐的路径是：阶段 1 先由小队搭好工具链和规范 → 阶段 2 小范围试点 → 阶段 3 大面积推广。核心原则是"开发者第一次接触就能跑通"，第一印象坏了后面很难翻盘。

3.6 新项目启动套件：5 分钟配好，以后每个项目都不用再教

本节目标：掌握一套可复用的配置模板，新项目打开 Claude Code 就能直接干活

3.6.1 为什么需要启动套件

每个新项目打开 Claude Code，它都像个刚入职的新人------不知道你的技术栈、不知道哪些文件不能碰、不知道你的规范。你得从零教起：

• 改一个 API，Claude 直接在组件文件里写 SQL------它不知道你的数据库操作全在 src/lib/services/ 里，没人告诉过它
• 每执行一个命令弹一次权限确认，一个下午点了 30 次 Allow
• commit message 格式每次都靠临时编

默认的 Claude Code 是什么都能做、什么都不知道的通用助手。通用不是好事。

这套配置把"通用"变成"你的项目的专属"。核心思路：把一次性的解释成本，变成可复用的配置文件。4 个文件 + 9 个命令，放到任何项目里就能用。

3.6.2 第一个文件：CLAUDE.md

CLAUDE.md 是 Claude Code 启动时第一个读的文件。写在里面的东西，Claude 在每一次对话里自动遵守。全局 CLAUDE.md 的精简模板：

## 沟通方式
- 默认中文回复；代码、命令、变量名、文件路径保持英文
- 结论先行，简洁直接，不先铺垫背景
- 不谄媚，不夸"这是个很好的问题"，不以"当然可以"开头
- 给真实判断------方案有问题直接指出，发现更好做法主动说明

## Git
- 不自动 `git commit` 或 `git push`，除非我明确要求
- 提交前先展示将要提交的变更摘要
- commit message 使用简洁英文

## 红线操作
以下操作即使在 auto-accept 模式下也必须先问我：
- 删除文件、目录或 git 历史
- 修改 `.env`、密钥、token、证书、CI/CD 配置
- `git push`、`git rebase`、`git reset --hard`、强制推送
- 公开发布（`npm publish`、生产部署等）

项目级的 CLAUDE.md 再加一层：技术栈、目录结构、commit 格式、禁区（如 不要碰 migrations/ 目录）。两个文件叠加，Claude 第一次打开项目就知道------跑测试是 pnpm vitest run 而不是 npm test，数据库操作全在 src/lib/services/ 里。

维护策略：每被 Claude 坑一次，立刻加一条到 CLAUDE.md。过时的规则删掉，内容保持精炼。三个月下来，这个文件就是"这个项目 Claude 犯过的所有错误的预防清单"。最有生产力的一句话是："更新 CLAUDE.md，让这件事不再发生"。

3.6.3 第二个文件：settings.json

用 Claude Code 最烦的就是弹窗。这个文件把"该放行的放行、该锁住的锁住"写死：

{
  "permissions": {
    "allow": [
      "Read", "Glob", "Grep", "Edit", "MultiEdit",
      "Write(src/**)", "Write(tests/**)",
      "Bash(npm *)", "Bash(pnpm *)", "Bash(git status)", "Bash(git diff *)",
      "Bash(git log *)", "Bash(git add *)", "Bash(git commit *)",
      "Bash(cat *)", "Bash(head *)", "Bash(tail *)", "Bash(find *)"
    ],
    "deny": [
      "Read(**/.env*)", "Read(**/*.pem)", "Read(**/*.key)",
      "Read(**/secrets/**)", "Read(**/credentials/**)",
      "Write(**/.env*)", "Write(**/secrets/**)",
      "Write(package-lock.json)", "Write(.github/workflows/*)",
      "Bash(rm -rf *)", "Bash(sudo *)", "Bash(git push *)",
      "Bash(git merge *)", "Bash(git rebase *)",
      "Bash(docker *)", "Bash(curl * | sh)", "Bash(chmod *)"
    ],
    "defaultMode": "acceptEdits"
  }
}

allow 白名单：日常安全操作，不应该每次都问------读文件、写源码、跑测试、git 日常命令。

deny 黑名单 ：安全红线------读 .env、读密钥、rm -rf、sudo、git push。

配完之后：日常操作零弹窗，危险操作自动封堵。

注意 ：allow 按你的工具链改------用 yarn 就加 Bash(yarn *)，用 bun 就加 Bash(bun *)。deny 那几行建议原样留着，它们是安全底线。

3.6.4 第三个文件：.gitignore

除了常规忽略，多加几行保护 AI 工具配置和密钥不被提交到 git：

# AI 工具本地配置
.claude/settings.local.json
.cursor/
.aider*
.continue/
.cody/

# 密钥和凭证
*.pem
*.key
credentials.json
.npmrc
.aws/
.ssh/

注意一个细节 ：.claude/settings.local.json 被 gitignore 了，但 .claude/settings.json 和 .claude/skills/ 没有。意思是------项目配置团队共享，个人偏好（含 API key）自己留着。

3.6.5 第四个：9 个 Slash Command（Skills）

Skills 把你上线前的心理检查清单变成命令------不用再临时想"还有什么没查"，敲个 /，它按你的规矩跑完。每个 Skill 就是一个 Markdown 文件放在 .claude/skills/[名字]/SKILL.md。

9 个 Skill 的完整写法见第五部分。这里快速看三个最核心的：

/review --- 审代码。不看风格，按严重程度排：

• CRITICAL：逻辑错误、空指针、竞态条件、安全漏洞
• WARNING：N+1 查询、缺少错误处理、性能隐患
• INFO：命名、垃圾代码、TODO
• 输出 checklist，结尾总结 "X critical, Y warnings, Z info"

/commit --- 提交代码。自动跑 git status 和 git diff --stat，把改动按逻辑分组，格式遵循 type(scope): description。

/deploy-check --- 上线前检查。按顺序跑：类型检查 → 测试 → lint → 构建 → 搜 console.log → 检查 .env 引用 → 确认没有未提交的改动。全绿才上线。

另外 6 个：/test、/pr、/debug、/refactor、/docs、/security。套路相同------frontmatter 声明 name、description、allowed-tools，后面写检查步骤。

核心价值：写一次，以后每次都是它替你查。详见第四部分完整教程。

3.6.6 三种安装方式

场景	做法
从零开始的新项目	模板复制进去，填入技术栈，第一次 commit 就带着完整配置
已有项目	CLAUDE.md 和 .gitignore 加到根目录，settings.json 合并到现有配置，skills 文件夹拖进去
所有项目通用	settings.json 和 skills 放 ~/.claude/ 全局生效；CLAUDE.md 每个项目单独写

推荐做法：settings.json 和 skills 放全局，CLAUDE.md 每个项目单独写。权限和命令不用每个项目配一遍，但项目上下文是独立的。

3.6.7 这套配置是活的

模板最大的意义不是"直接用"，是"以此为起点，让它越长越像你的项目"：

• CLAUDE.md 是活的：Claude 每犯一次错就加一条。记住这句话："更新 CLAUDE.md，让这件事不再发生"
• settings.json 跟着项目长大：新工具来了加 allow，发现新的危险操作加 deny
• Skills 长出自己的版本 ：/review 里加你代码库特有的常见问题，/commit 里写团队的 scope 命名规范
• .gitignore 持续更新：每用一个新工具，看它会不会在本地生成配置文件

三个月后回头看，最初的模板已经被使用习惯磨成了不同的形状。这个变化本身就是价值------你的项目越来越像你，Claude 也越来越懂你。

3.7 Claude Code 常见问题与排查（FAQ）

3.7.1 安装类问题

Q1：安装时报 ENOENT: no such file or directory

• 原因：npm 缓存损坏
• 解决 ：运行 npm cache clean --force，然后重新安装

Q2：安装成功但 claude 命令找不到

• 原因：npm 全局安装路径未加入系统 PATH
• 解决 ：运行 npm config get prefix，将输出的路径加入系统 PATH 环境变量

Q3：Windows 上报"无法加载文件，因为在此系统上禁止运行脚本"

• 原因：PowerShell 执行策略限制
• 解决 ：以管理员身份打开 PowerShell，运行 Set-ExecutionPolicy RemoteSigned

3.7.2 连接/API 类问题

Q4：启动后提示 Invalid API Key

• 原因：API Key 配置错误或过期
• 解决 ：检查环境变量 ANTHROPIC_API_KEY 是否正确设置。用 echo $ANTHROPIC_API_KEY（macOS）或 echo $env:ANTHROPIC_API_KEY（PowerShell）验证

Q5：中转服务配置后连接超时

• 原因：中转服务地址错误或服务不可用
• 解决 ：1. 检查 ANTHROPIC_BASE_URL 是否正确 2. 用浏览器访问中转服务网站确认其正常运行 3. 尝试用 curl 直接测试API连通性

Q6：提示 Rate limit exceeded

• 原因：短时间内发送了太多请求
• 解决：等待 1 分钟后重试。如果频繁出现，考虑升级 API 套餐

3.7.3 使用类问题

Q7：AI 修改了不该改的文件

• 原因：需求描述不够明确，AI自行判断需要修改
• 解决 ：1. 用 git checkout . 撤销修改 2. 重新描述需求，明确指定"只修改 xxx 文件" 3. 在 CLAUDE.md 中注明"不要修改的文件"

Q8：AI 陷入"改A坏B、改B坏A"的循环

• 原因：AI缺乏全局视角，修复一个问题引入新问题
• 解决 ：1. 用 git checkout . 回退到稳定版本 2. 用 /clear 清空对话 3. 重新描述完整的需求，让 AI 一次性考虑所有约束

Q9：对话太长后 AI 开始"遗忘"早期内容

• 原因：上下文窗口接近满载
• 解决 ：使用 /compact 压缩上下文，或开新会话

Q10：AI 生成了一个不存在的npm包或API

• 原因：AI "幻觉"（编造不存在的东西）
• 解决：在使用 AI 推荐的包之前，先到 npmjs.com 搜索确认它是否存在

3.8 自定义斜杠命令（Custom Slash Commands）

你可以创建自己的斜杠命令，将常用操作封装成快捷方式。

在项目根目录创建 .claude/commands/ 目录，然后添加 Markdown 文件：

<!-- .claude/commands/deploy.md -->
# 部署检查清单

请执行以下部署前检查：
1. 运行所有测试：npm test
2. 检查是否有 lint 错误：npm run lint
3. 确认 .env.example 已更新（如果添加了新的环境变量）
4. 构建项目：npm run build
5. 报告所有检查结果

使用方式：

> /deploy

Claude Code 就会按照你定义的步骤执行部署检查。

3.9 Claude Code 使用模式：Plan Mode 与三种权限模式

初学者常问："用 Claude Code 是应该先让它规划整个项目再执行，还是自己分模块逐步让它做？"

答案 ：Claude Code 原生提供了 Plan Mode（规划模式） 。它不是"一种提示词技巧"，而是官方内置的一个只读运行模式，在该模式下 AI 只能分析不能修改，有专门的快捷键与命令可随时切入。

3.9.1 三种运行模式（官方）

Claude Code 内置 三种互斥的运行模式：

模式	行为	适合场景	状态栏提示
Normal（默认）	每次文件修改、命令执行都要你确认	默认、小任务、需要逐步审查	无特殊标记
Auto-Accept（自动接受）	不再询问，直接执行	已计划好的批量任务、可信操作	accept edits on
Plan Mode（规划模式）	全面只读，只能分析、提问、出方案	复杂任务、不熟悉的代码库、架构决策	plan mode on

3.9.2 Plan Mode 能做什么、不能做什么

在 Plan Mode 下，AI 只能调用这些只读工具：

工具	作用
Read	查看文件内容
Glob	按 pattern 查找文件
Grep	用正则在文件内容中搜索
LS	列出目录内容
WebSearch / WebFetch	联网查资料
Task	启动只读子代理去调研
AskUserQuestion	向你提交选项题以澄清需求

严格禁止 ：写入文件、修改文件、运行 shell 命令、运行测试、任何改动项目的动作。这保证你在看到 AI 计划之前，它不会动你项目中的任何一行代码。

提示：Plan Mode 的重点是先探索和规划，暂不修改文件。不同版本可能会用不同的内部检索或子任务机制来辅助调研，不建议把某个内部实现细节当成稳定接口来记。

3.9.3 四种进入 Plan Mode 的方式（重点！）

graph TB subgraph Methods"进入 Plan Mode 的 4 种方式" direction TB M1"① 快捷键：Shift+Tab ×2\
（Windows 某些终端用 Alt+M）" M2"② 斜杠命令：/plan\
（Claude Code v2.1.0+）" M3"③ 启动参数：claude --permission-mode plan" M4"④ 默认配置：.claude/settings.json\
permissions.defaultMode = 'plan'" end

图：进入 Plan Mode 的四种方式，从临时到永久

方式一：键盘快捷键 Shift+Tab（最常用）

在 Claude Code 会话中连按两次 Shift + Tab：

第一次 Shift+Tab → 切到 Auto-Accept Mode（状态栏： accept edits on）
第二次 Shift+Tab → 切到 Plan Mode     （状态栏： plan mode on）
第三次 Shift+Tab → 切回 Normal Mode

注意： Windows 用户注意 ：某些 Windows 终端（如部分 PowerShell 配置）上 Shift+Tab 只能在 Normal/Auto-Accept 间切换，跳过了 Plan Mode。请改用 Alt + M 切入 Plan Mode；该问题在官方 Issue 中已标记为已知问题。

方式二：会话中输入 /plan 命令（v2.1.0+）

Claude Code v2.1.0 之后支持直接在提示符中输入斜杠命令：

> /plan

会话会立即切入 Plan Mode。特别适合"继续聊到一半发现需要规划"的场景。

方式三：启动时直接进 Plan Mode

如果你明确知道本次是复杂任务，可以从启动就进入 Plan Mode：

# 交互式
claude --permission-mode plan

# 无头模式（可用于 CI / 脚本）
claude --permission-mode plan -p "分析认证模块并提出优化建议"

方式四：设为项目默认模式

如果某个项目你一直希望默认"先规划后执行"，可以在项目根的 .claude/settings.json 中配置：

{
  "permissions": {
   "defaultMode": "plan"
  }
}

以后只要在该项目目录下运行 claude，就会默认进 Plan Mode。

3.9.4 推荐的完整工作流

推荐的使用顺序：

claude --permission-mode plan      ← 进 Plan Mode
  ↓ Phase 1：Explore  ------ "读一下 src/auth 目录，了解现有认证逻辑"
  ↓ Phase 2：Plan    ------ "请出详细计划：需改哪些文件、按什么顺序、边界情况是什么"
  ↓ 你审核计划，反复打磨满意为止
Shift+Tab → Auto-Accept Mode  ← 切出 Plan Mode
  ↓ Phase 3：Implement ------ "按上述计划实施"
  ↓ Phase 4：Commit   ------ "生成提交信息并 commit"

实践建议：复杂任务优先从 Plan Mode 开始。先让 AI 探索和设计，再进入实现阶段，通常能减少返工。

3.9.5 何时用 Plan Mode、何时不用

作者推荐的一句话准则：

"如果你能用一句话说清期望的 diff，就不用规划；如果你说不清，就先规划。"

任务类型	推荐模式	原因
新项目从零开始	Plan Mode 优先	需要整体架构考量
添加复杂功能（认证、订阅、软删除）	Plan Mode 优先	一动动一片，回退成本高
修复一个明确的 Bug	Normal	范围明确、目标清晰
重命名函数、调整变量	Normal	diff 可以一句话说清
大型重构、跨文件迁移	Plan Mode 优先	要评估影响范围
批量生成类似代码（根据已有计划）	Auto-Accept	计划已出，执行阶段别被打断
阅读、了解陌生代码库	Plan Mode	本身就是只读场景

核心原则："简单任务直接做，复杂任务先规划"。不确定时，选 Plan Mode 总是更安全。

3.9.6 另一种变体：Opus Plan + Sonnet Implement

Claude Code 还提供了 --model opusplan 别名，它会：

• 用 Opus（推理能力更强、成本较高）作为规划阶段的模型
• 用 Sonnet（代码快、成本低）作为执行阶段的模型

claude --model opusplan

这是一种**"用贵模型思考、用便宜模型动手"的成本优化策略**，适合复杂任务。

3.9.7 快捷决策树

graph TB Start{"你的任务是什么？"} Start -->|"复杂项目<br/>多文件协调"| PlanMode Start -->|"简单任务<br/>目标明确"| DirectMode subgraph PlanMode" Plan Mode（推荐）" direction TB P1"Shift+Tab×2 或 /plan" --> P2"Explore + Plan" P2 --> P3"审核计划" P3 --> P4"切出后执行" end subgraph DirectMode" Normal Mode" direction TB D1"一句话描述需求" --> D2"逐项确认" D2 --> D3"AI 逐步应用" end PlanMode --> Result" 交付结果" DirectMode --> Result

图：决策树------复杂任务走 Plan Mode，简单任务走 Normal Mode

3.10 案例实操：Web 记账工具（finance-cli）------ 热身练习

这是一个用 Claude Code 从零构建的 Python Web 项目。在开始复杂的 Mini Mall 之前，先用这个小项目熟悉一下开发流程和 /plan 功能。

3.10.1 项目简介

我们要做一个带 Web 界面的记账工具，在浏览器里记录和查看日常开销。核心功能：

• 添加账目：金额、分类、日期、备注------在网页表单里填写
• 查看列表：按月份和分类筛选，表格展示所有记录
• 分类统计：柱状图 + 统计表，一目了然
• 删除记录：输入 ID 即可删除

技术栈 ：Python + Streamlit （Web 界面框架）+ sqlite3（数据库，Python 自带，零配置）

选择 Streamlit 的原因是它只用 Python 代码就能做出漂亮的 Web 界面，不需要学 HTML/CSS/JavaScript。你写的每一行都是 Python，Streamlit 自动把它变成网页。

项目结构（4 个文件，不到 350 行代码）：

finance-cli/
├── pyproject.toml        # 项目配置和依赖声明
└── finance/            # Python 包
   ├── __init__.py        # 空文件，标记为 Python 包
   ├── models.py         # 数据结构定义（dataclass）
   ├── database.py        # SQLite 建表 + 增删查 + 统计
   └── web.py            # Streamlit Web 界面入口

提示：你不需要手动创建这些文件。后面每一步都会告诉你如何用 Claude Code 来生成它们。

3.10.2 第 1 步：用 /plan 做架构设计

在终端中创建项目目录，启动 Claude Code：

cd ~/ai-coding-projects
mkdir finance-cli && cd finance-cli
claude

告诉 AI 你的需求（注意：直接输入自然语言即可，不需要特殊格式）：

我要做一个 Python Web 记账工具，功能包括：
- 添加账目（金额、分类、日期、备注）------在网页表单里填写
- 查看列表（按月份和分类筛选）------表格展示
- 删除账目------输入 ID 删除
- 分类统计------柱状图 + 统计表

技术栈用 Python + streamlit + sqlite3。
预设 6 个分类：餐饮、交通、购物、娱乐、居住、其他。
我是编程新手，请先出方案再动手。

Claude Code 会进入 Plan Mode（Shift+Tab 两次或输入 /plan），提出几个问题确认你的需求（比如"你是新手还是老手？"、确认技术选型），然后生成一份包含以下内容的架构方案：

• 数据库表设计（categories 表 + records 表）
• 项目文件结构
• 每个文件的职责说明
• 实现步骤顺序

审核方案确认无误后，告诉 AI "可以开始执行"。

提示 ：这就是第三部分讲的 Plan Mode------先让 AI 出方案，人审核后再动手。对于新手来说，这能避免 AI "一顿操作猛如虎，一看结果全白费"。

3.10.3 第 2 步：环境准备

在 Claude Code 中输入：

请帮我创建 pyproject.toml，声明项目信息和依赖：
- 项目名：finance-cli
- Python 版本要求：>=3.10
- 依赖：streamlit

AI 会生成 pyproject.toml，内容如下：

[project]
name = "finance-cli"
version = "0.1.0"
description = "个人记账 Web 应用"
requires-python = ">=3.10"
dependencies = [
    "streamlit>=1.42",
]

然后创建虚拟环境并安装依赖：

# 创建虚拟环境（隔离本项目依赖，不影响系统 Python）
python -m venv venv

# 激活虚拟环境
# Windows：
venv\Scripts\activate
# macOS / Linux：
source venv/bin/activate

# 安装依赖
pip install -e .

提示 ：pip install -e . 中的 -e 表示"可编辑模式"（editable）。这意味着你改了代码不需要重新安装。Streamlit 安装后就可以启动 Web 服务了。

3.10.4 第 3 步：数据模型（models.py）

在 Claude Code 中继续输入：

请创建 finance/models.py，定义数据模型：
1. DEFAULT_CATEGORIES 列表：餐饮、交通、购物、娱乐、居住、其他
2. Category 类（用 @dataclass），字段：id、name
3. Record 类（用 @dataclass），字段：id、amount、category_id、record_date、note、created_at、category_name（运行时填充，非数据库字段）

AI 生成的 finance/models.py：

from dataclasses import dataclass

# 预设的 6 个默认分类，用户首次使用时自动创建
DEFAULT_CATEGORIES = ["餐饮", "交通", "购物", "娱乐", "居住", "其他"]


@dataclass
class Category:
   """分类模型"""
   id: int
   name: str


@dataclass
class Record:
   """一笔账目的模型"""
   id: int
   amount: float
   category_id: int
   record_date: str     # 格式: YYYY-MM-DD
   note: str = ""
   created_at: str = ""

   # 展示时可以带上分类名称（不从数据库来，运行时填充）
   category_name: str = ""

提示 ：@dataclass 是 Python 的一个装饰器，它会自动帮你生成 __init__ 等方法 ，省去大量样板代码。你只需声明字段名和类型就行。默认值（如 note: str = ""）表示这个字段可以不传，默认为空字符串。

3.10.5 第 4 步：数据库层（database.py）

在 Claude Code 中输入：

请创建 finance/database.py，实现数据库操作层：
1. 数据库文件放在 ~/.finance-cli/data.db（用户主目录下）
2. init_db() --- 创建 categories 表和 records 表 + 写入 6 个默认分类
3. add_record(amount, category_name, date, note) --- 插入一笔账目，分类不存在时报错
4. list_records(month, category_name) --- 查询账目，支持按月份和分类筛选
5. delete_record(record_id) --- 删除一笔账
6. get_stats(month) --- 按分类统计支出（总金额、笔数）

要求：使用 sqlite3（Python 标准库），查询结果用 JOIN 关联分类名。

AI 生成的 finance/database.py 核心函数：

import sqlite3
import os
from finance.models import DEFAULT_CATEGORIES, Record

DB_DIR = os.path.join(os.path.expanduser("~"), ".finance-cli")
DB_PATH = os.path.join(DB_DIR, "data.db")


def _get_conn():
   """获取数据库连接"""
   os.makedirs(DB_DIR, exist_ok=True)
   conn = sqlite3.connect(DB_PATH)
   conn.row_factory = sqlite3.Row  # 让查询结果可以像字典一样取值
   return conn


def init_db():
   """初始化数据库：建表 + 写入默认分类"""
   conn = _get_conn()
   cursor = conn.cursor()

   cursor.execute("""
      CREATE TABLE IF NOT EXISTS categories (
         id INTEGER PRIMARY KEY AUTOINCREMENT,
         name TEXT NOT NULL UNIQUE
      )
   """)

   cursor.execute("""
      CREATE TABLE IF NOT EXISTS records (
         id INTEGER PRIMARY KEY AUTOINCREMENT,
         amount REAL NOT NULL,
         category_id INTEGER NOT NULL,
         record_date TEXT NOT NULL,
         note TEXT DEFAULT '',
         created_at TEXT DEFAULT (datetime('now', 'localtime')),
         FOREIGN KEY (category_id) REFERENCES categories(id)
      )
   """)

   for cat_name in DEFAULT_CATEGORIES:
      cursor.execute(
         "INSERT OR IGNORE INTO categories (name) VALUES (?)", (cat_name,)
      )

   conn.commit()
   conn.close()


def add_record(amount: float, category_name: str, date: str, note: str = "") -> int:
   """添加一笔账目，返回新记录的 ID"""
   conn = _get_conn()
   cursor = conn.cursor()

   # 先查分类 ID
   cursor.execute("SELECT id FROM categories WHERE name = ?", (category_name,))
   row = cursor.fetchone()
   if row is None:
      conn.close()
      raise ValueError(f"未知分类：{category_name}。可用分类：{', '.join(DEFAULT_CATEGORIES)}")

   category_id = row["id"]
   cursor.execute(
      "INSERT INTO records (amount, category_id, record_date, note) VALUES (?, ?, ?, ?)",
      (amount, category_id, date, note)
   )
   new_id = cursor.lastrowid
   conn.commit()
   conn.close()
   return new_id

其余三个函数（list_records、delete_record、get_stats）的结构类似，完整代码约 150 行（见项目源码 finance/database.py）。

提示 ：注意 add_record 在查不到分类时会抛出 ValueError 并给出明确提示 ，告诉用户哪些分类可用。这种"尽早报错、给出清晰信息"的习惯在编程中非常重要。数据库用 ? 占位符传参，防止 SQL 注入攻击。

3.10.6 第 5 步：Web 界面（web.py）

在 Claude Code 中输入：

请创建 finance/web.py，实现 Streamlit Web 界面：
1. 页面配置：标题"个人记账助手"，宽屏布局
2. 侧边栏导航：三个选项------添加记录、账目列表、分类统计
3. "添加记录"页：金额输入框、分类下拉框、日期选择器、备注输入框、提交按钮
4. "账目列表"页：月份和分类筛选、表格展示所有记录、底部显示合计
5. "分类统计"页：统计表（分类、笔数、合计、占比）+ 柱状图
6. 启动时自动调用 init_db() 确保数据库存在

AI 生成的 finance/web.py 关键部分：

import streamlit as st
import pandas as pd
from datetime import date

from finance.database import init_db, add_record, list_records, delete_record, get_stats
from finance.models import DEFAULT_CATEGORIES

# 页面配置
st.set_page_config(page_title="个人记账助手", layout="wide")
init_db()

# 侧边栏导航
menu = st.sidebar.radio("导航", ["添加记录", "账目列表", "分类统计"])

# "添加记录" 页面
if menu == "添加记录":
    st.header("添加一笔账目")
    amount = st.number_input("金额（元）", min_value=0.01, value=35.0, step=0.5)
    category = st.selectbox("分类", DEFAULT_CATEGORIES)
    record_date = st.date_input("日期", value=date.today())
    note = st.text_input("备注（可选）", placeholder="例如：外卖")

    if st.button("记录这笔账", type="primary"):
        record_id = add_record(amount, category, record_date.isoformat(), note)
        st.success(f"已记录 #{record_id}：{category} {amount:.2f} 元")

# "账目列表" 页面
elif menu == "账目列表":
    st.header("账目列表")
    records = list_records()
    if not records:
        st.info("暂无记录")
    else:
        # 构建表格并展示
        df = pd.DataFrame([{
            "ID": r.id, "日期": r.record_date,
            "分类": r.category_name, "金额": f"{r.amount:.2f}",
            "备注": r.note
        } for r in records])
        st.dataframe(df, use_container_width=True, hide_index=True)

完整代码见项目源码 finance/web.py，约 130 行。

提示 ：Streamlit 的魔法在于------你写的 st.button()、st.selectbox()、st.dataframe() 这些 Python 函数调用，会自动变成网页上的按钮、下拉框、表格。你不需要写一行 HTML 或 CSS，Streamlit 帮你处理了所有前端细节。这就是为什么它特别适合初学者。

3.10.7 第 6 步：启动并验证

激活虚拟环境后，启动 Streamlit：

# 激活虚拟环境
# Windows：venv\Scripts\activate
# macOS/Linux：source venv/bin/activate

# 启动 Web 服务
streamlit run finance/web.py

浏览器会自动打开 http://localhost:8501。如果没自动打开，手动访问这个地址即可。

你会看到一个完整的 Web 界面：

• 左侧侧边栏有三个导航选项
• 点击「添加记录」→ 填写金额、选择分类、选择日期、输入备注 → 点击按钮，记录成功
• 点击「账目列表」→ 看到所有记录以表格展示，可按月份和分类筛选
• 点击「分类统计」→ 看到柱状图和统计表

验证清单：

• 添加一条「餐饮 35.5 元」的记录
• 添加一条「交通 120 元」的记录
• 在账目列表中看到这两条记录
• 分类统计中有对应的柱状图
• 删除一条记录，列表刷新后该记录消失

验证：如果以上操作都能正常完成，恭喜！你完成了一个带 Web 界面的记账工具。试试关掉浏览器再打开 ------ 数据还在，因为 SQLite 已经把数据持久化到文件里了。

3.10.8 项目总结

文件	职责	代码量
pyproject.toml	项目配置和依赖声明	~10 行
finance/models.py	数据结构定义	~25 行
finance/database.py	SQLite 建表 + 增删查 + 统计	~150 行
finance/web.py	Streamlit Web 界面入口	~130 行

总共 不到 350 行代码 ，你就拥有了一个带 Web 界面的记账工具。数据库文件自动创建在 C:\Users\你的用户名\.finance-cli\data.db（Windows）或 ~/.finance-cli/data.db（macOS/Linux），不会丢失。