本文基于知乎专栏文章《Claude Code 最佳实践指南》整理而成，原文作者为 Alex Hu。本文以适合本仓库的 Markdown 结构重新排版，并保留原文的核心实践脉络，方便个人长期查阅与复用。

原文链接：https://zhuanlan.zhihu.com/p/2009744974980331332

前言

这篇文章的核心目标，不是单纯教你“怎么给 Claude Code 写提示词”，而是帮助你建立一套可长期复用的工作方式：让 Claude 具备上下文、验证能力、明确边界和持续反馈回路。

全文贯穿一个关键约束：Claude 的上下文窗口虽然很大，但并不是无限的。一旦上下文被无效信息、失败尝试或无边界探索填满，输出质量就会明显下降。所以真正的最佳实践，核心不是“更花哨的提示词”，而是更好的上下文管理与工作流设计。

1. 先理解 Claude Code 的工作方式

Claude Code 处理任务时，通常会经历三个阶段：

  1. 收集上下文：读取代码、搜索文件、理解结构；

  2. 采取行动：编辑文件、执行命令、运行测试；

  3. 验证结果：检查测试、构建、截图或脚本输出是否符合预期。

这意味着你和 Claude 的分工非常明确：

  • 你负责提供正确问题、目标、约束和上下文入口；

  • Claude 负责阅读、分析、执行与验证。

在实际使用中，最常见的两个输入方式是：

@：引用上下文

@ 用来把文件、目录或资源注入上下文，例如：

解释 @src/auth.ts 的逻辑
对比 @old-api.ts 和 @new-api.ts
@src/components 的结构是什么？

但要注意：@ 不是越多越好。一次塞进大量文件，只会更快耗尽上下文。精准引用，往往比“全仓库扫一遍”更有效。

!：直接执行命令

! 用来在提示框中执行 Shell 命令，并把结果带回上下文，例如：

! git diff --stat
! npm test 2>&1 | tail -20

它适合快速把构建结果、测试日志、Git 差异等信息喂给 Claude，而不是手工复制大段输出。

2. 验证能力，是效果提升最大的杠杆

原文反复强调一个结论：如果 Claude 能验证自己的工作，结果质量会明显更高。

很多人把 Claude Code 当成“会写代码的聊天机器人”，但更准确的理解应该是：它是一个能读代码、改代码、跑命令、做验证的执行型助手。

如果你不给它验证方式，它就只能“猜”；一旦你给出测试、构建命令、截图对比或明确的验收条件，它就能形成闭环，自我修正。

四种最实用的验证方式

1）给出测试样例

不要只说“写个邮箱校验函数”，而要把输入输出边界一起说清楚。例如：

写一个 validateEmail 函数。
测试用例：
- user@example.com -> true
- invalid -> false
- user@.com -> false
实现后运行测试。

2）UI 修改要配截图或视觉参考

前端任务里，视觉结果本身就是验收标准。与其让 Claude “优化一下页面”，不如给出设计图、截图或现有页面参考，让它最终对比差异。

3）修复问题时要求根因闭环

不要只说“构建挂了，修一下”，而应附上错误信息，并强调修复根本原因，而不是临时屏蔽报错。

4）指定验证命令

例如：

修改认证流程后，运行 npm test -- --testPathPattern auth 验证所有认证测试通过。

这样 Claude 的目标就不再是“改完就算结束”，而是“改完并验证通过才算结束”。

验证驱动开发的建议

在合适的场景下，可以把任务描述写成下面这种顺序：

  1. 先补测试；

  2. 再实现功能；

  3. 再运行测试；

  4. 再运行类型检查或构建；

  5. 最后汇报结果。

这种写法非常适合函数增强、Bug 修复和小型重构。

3. 先探索，再计划，再编码

这是另一个非常实用的原则：不要让 Claude 一上来就写代码。

对于稍复杂的任务，推荐按三个阶段推进：

第一阶段：探索

先让 Claude 只读地查看相关目录、关键模块和依赖关系，目的是确认问题到底在哪里，哪些文件真正相关。

例如：

阅读 /src/auth 目录，了解我们如何处理会话和登录。
同时看看我们如何管理用于密钥的环境变量。

第二阶段：计划

在开始改动前，先让 Claude 输出实现方案：

  • 要改哪些文件；

  • 为什么这样改；

  • 是否存在风险；

  • 需要哪些验证步骤。

先把方案说清楚，再开始编码，能显著减少“方向错了但代码写了很多”的情况。

第三阶段：编码与验证

确认方案合理后，再执行具体改动，并要求它按计划完成测试、构建或其他校验。

这个流程尤其适合：

  • 多文件修改；

  • 架构调整；

  • 不熟悉代码库时的首次改动；

  • 需求边界不清晰的任务。

4. 复杂需求，最好拆成 Spec / Plan / Tasks

对于稍大的功能，原文推荐将需求拆成三层产物：

  • spec.md：定义要做什么，以及为什么做；

  • plan.md：定义技术方案怎么落地；

  • tasks.md：定义执行顺序，每一步具体改什么。

一个清晰的结构类似这样：

specs/001-feature-name/
├── spec.md
├── plan.md
└── tasks.md

这三层分别解决什么问题

spec.md

回答的是 WHAT / WHY：

  • 用户故事是什么；

  • 验收标准是什么；

  • 边界条件有哪些；

  • MVP 范围是什么。

plan.md

回答的是 HOW：

  • 技术选型；

  • 目录结构；

  • 数据模型；

  • API 设计；

  • 实施阶段和风险。

tasks.md

回答的是 DO：

  • 先改什么；

  • 后改什么；

  • 每一步影响哪个文件；

  • 是否需要测试先行。

这种拆法的好处是：需求、方案和执行不再混在一个提示里，更容易审查，也更容易在多人协作里复用。

5. 提示词不是越长越好，而是越具体越好

文章给出的一个重要建议是：Claude 能推断意图，但不能读心。

比起说“帮我优化一下登录逻辑”，更好的说法是：

  • 指定范围：只看 src/auth/；

  • 指出症状：会话超时后登录失败；

  • 提供参考：按现有刷新 token 的模式实现；

  • 给出约束：不要引入新依赖；

  • 指定验证：先写失败测试，再修复并跑测试。

常见高质量提示结构

一个比较稳妥的提示，通常包含以下信息：

  1. 目标：你要它做什么；

  2. 范围：哪些文件或目录相关；

  3. 约束：不能做什么，或者必须遵循什么；

  4. 参考：现有实现、相似模块或截图；

  5. 验证：用什么方式确认完成。

常见输入方式

除了 @ 和 !，原文还提到几种很实用的输入方式：

  • 粘贴截图或图片，让 Claude 直接理解 UI 问题；

  • 使用管道把日志、git diff 或命令输出喂给 claude -p；

  • 对历史问题使用 git log 或 git blame 追踪演化原因。

这些方式的共同点是：都在帮助 Claude 更快拿到高价值信息，而不是自己盲猜。

6. 环境配置，是长期收益最高的投入

如果说前面的实践是“单次任务如何做得更好”，那环境配置关注的就是：如何让每次会话都自动变得更好。

原文重点提到了几类配置能力：

  • CLAUDE.md

  • 权限管理

  • CLI 工具

  • MCP

  • Hooks

  • Skills

  • 子代理

CLAUDE.md 应该写什么

CLAUDE.md 最适合写 Claude 无法从代码本身推断出来 的东西，例如：

  • 正确的构建与测试命令；

  • 仓库约定；

  • 项目特有架构规则；

  • 易踩坑点；

  • 环境变量或开发环境中的特殊要求。

不适合写的内容包括：

  • 语言本身的通用规范；

  • 大段 API 教程；

  • 从代码里一眼就能看懂的信息；

  • 冗长而模糊的“要写高质量代码”式空话。

权限与工具配置

为了让 Claude 更高效，建议提前准备常用 CLI 工具，例如：

brew install gh
brew install jq
brew install ripgrep

原理很简单：很多外部系统交互，直接走 CLI 比走笨重的上下文解释更省 token，也更稳定。

Hooks、Skills 与子代理

  • Hooks 适合做自动校验、日志过滤和流程钩子；

  • Skills 适合沉淀可重复的工作流；

  • 子代理 适合把探索任务丢到独立上下文里，避免污染主会话。

对团队来说，这几类机制一旦配置好，收益会远高于反复写提示词。

7. 沟通方式，直接决定输出质量

Claude Code 并不要求你掌握花哨的提示工程，但它非常依赖高质量沟通。

像问资深工程师一样提问

如果你刚接手一个项目，可以直接问：

  • 这个模块是怎么工作的？

  • 为什么这里调用的是 foo() 而不是 bar()？

  • 新 API 一般怎么接入？

  • 某个类处理了哪些边界情况？

这类问题非常适合作为入门和理解代码库的方式。

不要微管理 how，多说清楚 what

尤其是修 Bug 时，与其命令式地告诉 Claude 每一步该怎么做，不如把目标、错误信息和约束说清楚，让它自己决定排查路径。

例如：

这是 Slack 上报告的 bug：[粘贴 bug thread]。Fix it.

或者：

Go fix the failing CI tests.

看起来简单，但前提是你已经提供了足够可验证的上下文。

沟通时最常见的误区

  • 一次给太多互不相关的任务；

  • 同一个错误反复纠正却不清会话；

  • 只说“优化一下”，不说目标；

  • 只说“有 bug”，不给错误信息；

  • 不提供参考实现，让 Claude 猜风格。

改进方向也很明确：缩小范围、补充约束、说明原因、给出示例。

8. 会话管理，本质上是在管理上下文成本

上下文是 Claude Code 最关键的资源。很多效率问题，归根结底不是模型不够聪明，而是上下文已经被低质量信息占满。

两个非常实用的经验

1）尽早打断和纠偏

如果它开始走偏，不要放任它继续读几十个文件再说。应尽快停止、回退、重新限定范围。

2）修正两次后，就该 /clear

这是全文里非常值得记住的一条：如果你已经纠正 Claude 两次，说明上下文里可能已经充满了错误路径和失败尝试。这时与其继续缝补，不如清空会话，用更好的提示重新开始。

提高上下文效率的做法

  • 禁用不需要的 MCP；

  • 优先使用 CLI，而不是让 Claude解释一大段外部系统信息；

  • 提示尽量具体，不做无边界探索；

  • 控制 CLAUDE.md 长度，把低频规则移到 Skills；

  • 用 Hooks 预处理超长日志，只保留关键部分。

9. 进阶玩法：自动化、并行与 Worktree

当你已经能比较熟练地使用单会话后，下一步就是把 Claude 从“单个助手”变成“可编排的生产力系统”。

多会话并行

多会话的价值不只是更快，更重要的是上下文隔离。

比如：

  • 一个会话负责开发；

  • 一个会话负责代码审查；

  • 一个会话负责补测试；

  • 一个会话负责验证或复盘。

这种 Writer / Reviewer 模式，能显著降低“自己刚写完就自己审自己”的偏差。

Worktree 并行开发

文章推荐为不同任务使用独立 Git Worktree，例如：

claude --worktree feature-auth
claude --worktree bugfix-123
claude --worktree add-tests

这样每个 Claude 会话都有独立工作目录，减少互相干扰，也方便随时保留或丢弃实验性改动。

Headless 与自动化

当你使用 claude -p 时，本质上是在把 Claude 变成一个可编程函数。它非常适合：

  • CI 中的自动检查；

  • pre-commit 流程；

  • 定时分析任务；

  • 批量审查或总结工作。

长时间运行任务的安全边界

原文也提醒，长时间任务可以配合后台代理、Stop Hook 或更细致的权限策略，但像 --dangerously-skip-permissions 这类模式，依然只适合在可信或隔离环境下使用。

10. 团队落地时最容易踩的坑

文章最后一部分很适合团队负责人或技术负责人参考。

常见反模式

1）没有共享标准

每个人都各配一套，最后团队无法积累。解决方式是沉淀共享的 CLAUDE.md 模板、权限策略和常用 Skills。

2）过度标准化

把 CLAUDE.md 写成几百行“组织宪法”，结果谁都不看，Claude 也抓不住重点。标准化应只覆盖真正关键的内容，比如构建命令、安全边界和必要流程。

3）盲目全员推广

如果没有试点就全面推开，通常会因为工作流还不成熟而引发反感。更好的方式是：先让 2～3 个成员试点一周，沉淀模板、修正规则，再逐步扩展。

结语

如果把全文压缩成一句话，那就是：

Claude Code 的最佳实践，不是让 AI 替你“神奇地写代码”，而是把它放进一套清晰、可验证、可回退、可复用的工程工作流里。

你给它的不是越多越好，而是越准确越好；你追求的也不是“它会不会写”，而是“它能不能在正确上下文里完成并证明自己做对了”。

对个人开发者来说，最值得优先落地的三件事是：

  1. 给任务加上明确验证；

  2. 复杂任务先探索再计划；

  3. 持续瘦身上下文，把共性规则沉淀到 CLAUDE.md、Hooks 和 Skills 中。

只要这三点做扎实，Claude Code 的体验通常会提升一个量级。

参考链接