高效提示工程的秘诀

「帮我改进一下代码。」——二十分钟后 diff 满天飞，测试红了，你仍说不清最初要达成什么。」

第一个会话教会你启动与权限；代理循环教会你工具如何一轮轮执行。本章解决另一件事：你怎么说话，才能让循环朝正确方向转、并在可接受的成本内停下。

Claude Code 不是「问一句答一句」的聊天框，而是能读仓库、跑命令、改文件的代理环境。提示的目标不是写出文学级指令，而是让 Agent 理解意图、能自检、知道何时该探索、何时该动手。官方实践见 Best practices for Claude Code；可复制范例见 Prompt library 与 Common workflows。

与聊天提示的根本区别

维度	网页聊天	Claude Code
工作区	你粘贴什么它看什么	默认当前目录整个 repo
结束条件	一段文字算完成	往往要跑测试、看 diff、迭代多轮
你的角色	提问者	指挥者：定目标、定验收、在权限弹窗处拍板
上下文成本	mainly 对话	对话 + 每次 Read 的文件 + Bash 输出

因此有效提示通常包含四件事，顺序不必死板，但缺了就容易跑偏：

结果：做完后世界应有什么不同。
边界：不能动什么、必须遵守什么模式。
验收：怎样算完成，最好能让 Agent 自己跑一遍。
节奏：现在是只读探索、写计划，还是直接改码。

动手： 把下面两句都发给 Claude，对比行为差异：

优化一下 auth 模块

修复用户登出后会话未清除的问题。先只读查看 src/auth/ 相关文件，写出根因假设，再改代码，最后跑 npm test -- auth 相关用例必须通过。不要改与 auth 无关的文件。

第二句通常更少无关改动，因为结果、范围与验收都写清了。

最高杠杆：让 Agent 能验证自己的工作

官方把这一点称为单点最高杠杆：在提示里带上测试、命令、对比截图或明确通过标准，Agent 才能自主迭代，而不是每错一次都等你肉眼挑刺。

弱提示	强提示
实现一个校验邮箱的函数	写 `validateEmail`，用例：`a@b.com` 为 true、`invalid` 为 false；实现后跑测试并修到全绿
把仪表盘做好看一点	附上设计截图；改完后截图对比，列出差异并修到一致
构建失败了	粘贴完整报错；修到构建通过，不要 suppress 错误，要修根因

与 Plan Mode 的关系：计划阶段也要写清验收标准，批准执行后 Agent 才知道何时该停。

UI 类任务可配合 Claude in Chrome 等能力做视觉对比，机制以你安装版本为准。

先探索、再规划、再实现

大任务若一上来就 Edit，容易解决错问题。推荐四段节奏，与 Plan Mode 和内置 Plan 子代理一致：

探索（只读弄清现状）
    ↓
规划（改哪些文件、什么顺序、风险点）
    ↓
实现（按计划改码 + 自测）
    ↓
提交（commit / PR，可选）

探索

切到 plan 模式或明确要求只读：

阅读 src/auth/ 和配置里与会话相关的部分，说明登录、刷新 token、登出三条路径。
不要修改任何文件。

规划

我要加 Google OAuth。根据刚才的阅读，列出要改的文件、会话流变化和风险。
写成可批准的计划，再请求 ExitPlanMode。

批准前可用 Ctrl+G 在编辑器里直接改计划文本。

实现

按已批准计划实现 OAuth 回调；为 callback handler 写测试；
跑测试套件，失败则修到通过。

何时跳过完整规划

若你能用一句话描述 diff，例如「重命名变量 foo → bar」「给某函数加一行日志」，直接让 Agent 做即可。规划最有价值的情况是：不确定方案、多文件联动、或不熟悉模块。

BMAD：把一条提示写完整

本教程用 BMAD 作自检框架，与官方「结果 + 上下文 + 验收」一致，便于记忆：

字母	含义	你要写什么
Brief	目标	做完后用户/系统可观察的变化，而非「读某文件」
Material	素材	`@` 文件、报错、截图、链接、相关 issue
Action	行动类型	只读 / 规划 / 实现 / 审查 / 并行探索
Detail	细节	禁止项、风格、测试命令、完成定义

示例（修 bug）：

【B】修复登出后会话仍有效的问题。
【M】@src/auth/session.ts @tests/auth.logout.test.ts
     失败日志：<粘贴>
【A】先复现失败测试，再改实现，不要先大范围重构。
【D】只改 auth 相关文件；用项目现有 vitest 命令；修完跑相关测试全绿。

日常不必写四个标签，但发之前心里过一遍这四项，能去掉大量返工。

把上下文给对，而不是给满

上下文窗口是代理循环里最先耗尽的资源。塞满无关文件，模型会更易「忘记」早期的约束。策略是：只给决策所需的信息，其余让 Agent 用工具自己取。

用 `@` 而不是口述路径

@package.json 里哪个 script 适合只跑单个测试文件？

CLI 会注入文件内容，比「请读 package.json」可靠。多文件：@src/a.ts @src/b.ts 对比两者边界。

详见第一个会话。

其它输入方式

方式	适用
粘贴截图	UI 报错、设计稿、图表异常
管道 `cat log \| claude -p`	长日志一次性分析
已在 `/permissions` 中允许的 URL	官方文档等；避免每次抓站都弹窗
让 Agent 自己拉	「用 gh issue view 123 读需求再改」

会话级减负

命令	作用	何时用
`/context`	看占用	变慢、变「笨」时
`/compact`	压缩同任务长对话	还要继续同一 bug，但历史太长
`/clear`	清空对话开新题	任务彻底换了
`/btw`	旁路小问题，不进历史	问一句定义，不想污染主任务

/clear 与 /compact： 换功能用 /clear；同一功能查了很久用 /compact。同一会话里对同一问题纠正超过两次仍失败，往往该 /clear 并用更具体的初始提示重来，而不是在长对话里堆修补丁。官方 checkpointing 支持 Esc 连按或 /rewind 回滚对话与代码。

用子代理挡住探索噪声

全库摸底时，主会话易被 Read 结果淹没。委派探索：

用子代理调查 token 刷新实现和是否已有 OAuth 工具函数，只把结论和文件路径列表返回给我。

机制见 SubAgents。原则：高体积中间结果进子代理，主会话留结论与下一步。 窗口快到顶时的 handoff 与 /clear 组合剧本见上下文管理与多代理架构。

提示要具体到什么程度

官方 Best practices 用对比表说明粒度。核心不是越长越好，而是减少歧义。

场景	偏弱	较强
加测试	给 foo.py 加测试	覆盖用户未登录边界；避免 mock 外部 HTTP
问历史	为什么 ExecutionFactory API 这么怪	查该类的 git history 并总结 API 演变
跟现有风格	加一个日历组件	参照首页 HotDogWidget 的模式实现月份选择与翻页；除项目已有库外不引入新依赖
修 bug	修登录 bug	现象：session 超时后登录失败；查 src/auth/ token refresh；先写失败测试再修

何时可以故意模糊： 探索性提问，例如「这个文件你会改进什么」，用来发现你没想到的角度。一旦要动代码，立刻收窄到 BMAD。

描述结果，不必微操每一步

给公开 API 加快照限流，并确保现有测试仍通过

不必列出每个要改的文件名；Agent 会 Glob/Grep。你若已知必须动 src/middleware/rateLimit.ts，再 @ 点名即可。

measurable 完成标准

把主包体积压到 200KB 以下，列出删除了哪些依赖

将 auth 模块单测覆盖率从 62% 提到 80% 以上，只算 src/auth/

数字让「做完」可判定，减少「看起来好了」就停。

研究 → 规划 → 执行 → 审查节奏

与 BMAD、Plan Mode 配套的迭代环：

研究：弄清现状（只读、子代理、提问）
  → 规划：方案与文件列表（plan 模式 / 书面计划）
    → 执行：改码 + 自测（default / acceptEdits）
      → 审查：diff、子代理 review、第二会话 reviewer
        → 未完成则带着新事实回到研究或规划

每一步你可说什么

研究

画出 payment 模块的调用链，从 HTTP 入口到数据库，用列表即可，不改文件。

规划

要把 Stripe webhook 迁到新 SDK。列出受影响文件、迁移顺序、回滚方式，等我批准再改。

执行

按计划执行第 1 步：只改 adapter 层，跑 integration test payment.*

审查

审查 @src/middleware/rateLimiter.ts：边界情况、竞态、与现有中间件风格是否一致。只输出问题清单，不要改文件。

Writer / Reviewer 双会话

官方推荐用两个会话降低「刚写的代码自己审」的盲区：

会话 A（写）	会话 B（审）
实现 API 限流中间件
	审查 @src/middleware/rateLimiter.ts 的边界与风格，不修改文件
根据 B 的反馈修改

用 /rename oauth-migration 给会话起名，便于 claude --resume 找回。

何时一条指令就够

单行修复、明确文件与行号。
你已掌握全部上下文，不需要再探索。
有强验收且范围极小。

Agent 迷茫时的信号

信号	常见原因	你的动作
反复 Read 同一批文件	目标不清	补 B 与 D；或 `/clear` 重写
改了很多无关文件	范围未限	加「只改 X」「不要重构 Y」
测试红了继续乱改	验收未写或太弱	贴失败输出；要求先红后绿
一直「调查」不落地	缺 Action	写明「调查最多 N 个文件后给出计划」
同一错纠正三轮仍失败	上下文污染	`/clear` + 更强初始提示

大功能：让 Claude 先采访你

复杂需求时，可从极简提示开始，让模型用 AskUserQuestion 追问：

我想做：<一两句描述>。用 AskUserQuestion 详细采访我：实现、UI/UX、边界、风险与权衡。
不要问泛泛的问题，聚焦我可能没想到的难点。采访结束后把完整 spec 写到 SPEC.md。

spec 写好后，新开一个会话专门实现，主上下文只服务执行，spec 文件作锚点。

可复用提示模板

以下模板来自 Prompt library 与 Common workflows 的常见模式，请替换尖括号内容。

理解陌生模块

我要接手 <模块路径>。先只读：入口、对外 API、测试位置、与 <相邻模块> 的依赖。
用不超过 15 条 bullet 总结，并标出 3 个最大风险点。不要改文件。

写测试

为 @<文件> 补充测试，覆盖：<场景1>、<场景2>。
遵循 @<已有测试文件> 的风格。跑 <单测命令>，失败则修到通过。

安全审查

用只读子代理审查 @<路径> 最近变更：注入、鉴权、密钥泄露、不安全数据处理。
按严重度列出问题与行号，不要改文件。

重构

把 <旧模式> 重构为 <新模式>，范围仅限 <目录>。
每改一组文件就跑 <测试命令>；保持对外行为不变；不要顺手改格式无关文件。

生成或更新 CLAUDE.md

分析本仓库构建、测试、目录约定。更新 CLAUDE.md：只写 Agent 无法从代码猜到的内容，控制在 200 行内。
不要写冗长教程；用 @README.md @package.json 作事实来源。

从 issue 到 PR

用 gh 查看 issue <编号>，实现修复，跑 lint 与测试，写 conventional commit，开 PR 并链上 issue。

稳定重复的流程应升级为 Skills 的 SKILL.md，而不是每次粘贴整段。

提示写不下时：放进哪里

内容	放提示	CLAUDE.md	Skills	Hooks
本次任务目标与验收	✅
每条会话都要遵守的命令、目录规范	可简短重复	✅
长流程、偶尔用的 checklist			✅
每次 Edit 后必须跑 formatter				✅
禁止动 `.env`	可写	✅		✅ deny

CLAUDE.md 过长会导致规则被忽略；流程性内容迁到 Skills。必须 deterministic 的步骤用 Hooks。

与扩展能力配合

不必把所有技巧写进一条提示，环境配置承担「默认值」：

/init + CLAUDE.md：持久事实，减少重复解释。见 CLAUDE.md 编写与维护。
/permissions、auto mode、sandbox：减少弹窗打断。见安装与配置。
Skills：/deploy 类可重复流程。
SubAgents：大探索、并行调研。
MCP：issue、数据库、浏览器等外部系统，见 MCP。
CLI 工具 gh、jq：比让模型拼 raw API 更省上下文。

提示负责这次任务；配置负责每个会话的默认行为。

常见反模式

反模式	后果	改法
厨房sink会话	上下文混杂多个无关任务	任务切换就 `/clear`
同一问题反复纠正	失败尝试占满窗口	两次失败后 `/clear` 重写提示
只描述步骤不描述结果	Agent 走完步骤但未解决问题	写 B 与验收
一次塞十个大目标	都做一点都不完成	拆会话或拆阶段
微观管理每步工具	失去 Agent 探索能力	写验收，让路径自选
无验证就合并	看起来对的坏代码	测试、lint、review 写进提示
无限「调查」	读几百文件撑爆上下文	收窄范围或子代理
CLAUDE.md 百科全书	规则被忽略	删减；细节进 Skills
批准所有「不再询问」	误操作面扩大	只 allow 具体命令模式

决策边界：这条提示够好吗

发之前快速自检：

Brief：别人能否判断做完没有？
Material：关键文件、报错、截图是否已 @ 或粘贴？
Action：现在是只读、规划还是可改码？
Detail：禁止项、测试命令、范围是否写明？
Verify：Agent 能否自己跑命令证明完成？

适合长提示： 多文件、高风险、需对齐规范。
适合短提示： 范围极小、验收明确、你已掌握上下文。
适合升级 Skill： 同一粘贴块每周出现三次以上。
适合开新会话： spec 已写在文件里，实现阶段要干净上下文。

调试与失败模式

症状	可能原因	下一步
不跑测试就宣布完成	提示无验收	补「修完跑 X，贴输出」
改法与项目风格不符	未指参照	`@` 同类文件「按此模式」
计划获批后仍乱探	未切出 plan 或未写「按计划」	批准后再发实现提示
越改越偏	上下文太长	`/compact` 或 `/clear`
总问你已经说过的事	CLAUDE.md 缺失或过长	`/init` 或精简记忆
审查遗漏明显 bug	单会话自审	第二会话或子代理 review

用量与窗口见 /cost、/context；更系统的成本与幻觉应对见局限性与应对。

继续读下一章之前

试着回答：

为什么「带测试的提示」比「写更长步骤」杠杆更高？
/clear 与 /compact 分别解决什么问题？
BMAD 里哪一项最常被你省略而导致返工？
什么情况下应开第二个会话做审查？

自检清单：

用同任务对比过「模糊提示」与「带验收的提示」
完成过一次 explore → plan → implement 分段
用过 @ 引用与「请读某文件」并感受差异
在迷茫时用过 /clear 或子代理减负
能说出一条提示与 CLAUDE.md、Skill 的分工

上一章：上下文管理与多代理架构 · 下一章：完整实战工作流——把本章方法论落到代码理解、调试、重构、新功能与协作提交的端到端路径上。