📚 编程进阶教程站

第 18 章 · 高级技巧与最佳实践 ​

本章目标：掌握让 Claude Code 输出质量翻倍的提示技巧——精确指令、任务拆解、上下文优化与幻觉验证，形成个人高效工作流。

18.1 精确指令：模糊是万恶之源 ​

"给搜索功能加个分页"——这句话对人类同事来说也许够用，但对 agent 来说充满歧义：游标分页还是偏移量？每页多少条？要不要高亮？

text
❌ 模糊指令：
> 修复这个 bug

✅ 精确指令：
> tests/auth.test.ts 中 test_expired_token_refresh 失败了。
> 错误信息是 "JWT expired before verification"。
> 问题可能出在 src/auth/token.ts 的 verifyToken 函数没有处理
> clock skew。请先运行 npm test -- auth 确认失败，再定位并修复。

精确指令的三要素：目标文件、期望行为、验证方式。三者齐备时 Claude 一次通过率显著提升。

18.2 任务拆解：Plan Mode 与渐进交付 ​

面对复杂任务，直接让 Claude "一口气做完"往往中途跑偏。更好的做法是两阶段工作流：

阶段一：只读规划 ​

按 Shift+Tab 切换到 Plan Mode（或用 /model 选 opus 提升规划质量）。此模式下 Claude 只能读取文件和搜索，不能写入：

text
> 我想把 src/utils.js 拆分成多个模块文件。
> 先分析当前结构，提出拆分方案，不要动任何代码。

（Claude 输出方案：建议拆成 format.ts / validate.ts / api.ts ...）

阶段二：逐步执行 ​

确认方案后退出 Plan Mode，按计划逐条执行：

text
> 方案不错。先做第一步：把 formatDate 和 parseDate 移到 date.ts，
> 更新所有 import，然后运行 npm test 确认没有破坏。

为什么有效

Plan Mode 强制模型在动手前完成全局思考；逐步执行让你在每个检查点纠偏。两者结合将大型重构的失败率从"听天由命"降到"可控迭代"。

18.3 上下文优化技巧 ​

保持 CLAUDE.md 精简 ​

CLAUDE.md 是常驻上下文，每一行都消耗 token。最佳实践：

markdown
# CLAUDE.md — 控制在 ~100 行以内

## 技术栈
- Node 20 + TypeScript strict
- 测试: vitest, 运行 `npm test`
- Lint: `npm run lint` (ESLint + Prettier)

## 硬性约束
- 不引入新依赖除非明确讨论过
- API 响应格式必须用 Zod schema 校验
- 所有公开函数必须有 JSDoc 注释

## 常见命令
- 构建: npm run build
- 单测: npx vitest run <file>

详细文档放 docs/ 目录，在 CLAUDE.md 里写一句"架构细节见 docs/architecture.md"，让 agent 按需读取。

及时清理上下文 ​

切换到不相关的新任务时，执行 /clear 而不是继续堆积历史。旧任务的上下文不仅浪费 token，还会污染新任务的输出（模型可能混淆两个任务的需求）。

定向引用而非泛泛而谈 ​

text
❌ "项目里有个处理用户认证的模块，帮我看看"
✅ "看 src/auth/middleware.ts 第 40 行附近的 verifySession 函数"

精确引用让 agent 直接命中目标文件，省去探索时间。

18.4 幻觉识别与验证方法 ​

LLM 天生倾向于"给出一个听起来合理的答案"。Claude Code 也不例外——它可能调用不存在的 API、编造配置项名称、或者声称测试已通过但实际上根本没跑。

验证三板斧 ​

第一板斧：让它跑命令

text
> 你说已经修复了 bug。运行 npm test -- auth 并贴出完整输出。

如果 Claude 声称修改了代码，要求它展示 diff 或运行测试来证明。永远不要仅凭口头声明就接受"已完成"。

第二板斧：交叉验证 API 引用

当 Claude 使用你不熟悉的库 API 时，让它展示来源：

text
> 你用了 zod.string().cuid2() 这个方法。请打开 node_modules/zod
> 的类型定义确认这个方法存在。

或者自己花 10 秒查一下官方文档——这比调试幻觉代码省一小时。

第三板斧：TDD 防护网

先写测试再让 Claude 实现，是最可靠的防幻觉手段：

bash
# 你自己写好测试（定义"正确"的标准）
npx vitest generate src/utils/date.test.ts

# 让 Claude 实现直到全部通过
claude "实现 src/utils/date.ts 使所有 vitest 用例通过。不许修改测试文件。"

如果 Claude 偷偷改测试来"通过"，diff 一眼就能看出来。

18.5 个人工作流模板 ​

综合以上技巧，一个高效的日常循环：

text
1. /clear                          ← 干净起点
2. 精确描述任务（含文件路径+验证方式）
3. Shift+Tab 进入 Plan Mode        ← 大任务先规划
4. 确认方案 → 逐条执行             ← 每步带验证命令
5. 要求运行测试并展示输出           ← 幻觉防护
6. git diff 审查变更               ← 最终把关
7. /compact 或 /clear              ← 释放上下文

本章小结 ​

  • 精确指令三要素：目标文件、期望行为、验证方式；
  • Plan Mode 先规划后执行的"两阶段"模式大幅降低大任务跑偏率；
  • CLAUDE.md 保持精简，详细内容外链让 agent 按需加载；
  • 幻觉验证三板斧：跑命令证伪、交叉验证 API、TDD 防护网；
  • 任务切换时 /clear 是最被低估的好习惯。

🧪 随堂测验

点击你认为正确的选项。答错时会展示正确答案与原因解析。

1. 以下哪条指令最符合"精确指令"原则？

2. Plan Mode（Shift+Tab）的核心价值是什么？

3. 防止 Claude Code 幻觉的最可靠方法是？

4. 为什么推荐在 CLAUDE.md 中写"详细文档见 docs/architecture.md"？

🛠️ 动手实践 ​

  1. 找一个你最近让 Claude 做的任务，重写为包含"目标文件+期望行为+验证方式"三要素的精确指令，对比一次通过率的差异。
  2. 对一个中型重构任务使用 Plan Mode 两阶段流程，记录规划阶段的方案与最终实际执行的偏差。
  3. 故意问 Claude 一个不存在的 API 方法（如"用 lodash 的 deepFreezeAll 函数…"），观察它是否会编造用法，然后练习用交叉验证法纠正它。

下一章：团队协作规范