在终端里用过 Claude-Code 的人大概率都经历过一个尴尬场景你给它丢过去一句“帮我改一下登录接口”它忙活半天最后把整个认证模块重写了一遍跑测试还挂了三个。问题通常不在模型变笨了而是你还没掌握 Claude-Code 的提示词工程。这玩意儿和你在网页聊天框里写提示词完全是两码事。网页聊天答错了顶多浪费你三十秒Claude-Code 答错了它动的是你仓库里的真代码。这篇文章我把这段时间用下来的经验整理成一套可以直接上手的提示词工程框架从一个“怎么描述任务”的套路到 CLAUDE.md 这种上下文工程的核心配置再到实战演示和翻车记录给你一次讲透。1. Claude-Code 不是聊天机器人是施工队1.1 它到底在你的电脑上做了什么Claude-Code 不像网页版那样只能一口气生成一大段文字让你自己粘贴。它在终端里启动后是一个能真正操作你代码库的智能体它会搜索文件、读取源码、直接编辑文件、创建新文件甚至能帮你运行测试命令、执行 shell 操作。也就是说它有一双能碰到你磁盘的“手”。这意味着什么意味着你在提示词里说的每句话都有可能变成它对你项目代码的实际修改。我在项目里第一次让它“帮我优化一下登录接口”时它自作主张加了一个我自己都不认识的中间件还顺手改了两个配置文件。那次之后我彻底明白了Prompt Engineering 在 Claude-Code 这里已经不是“让 AI 更懂你”的修辞问题而是“给施工队下任务书”的工程问题。你交给它的不是一道问答题而是一份作业它是要在你的代码上动刀子的。所以使用 Claude-Code 的第一课就是先把角色的脑回路切换过来你不再是对着一个聊天框提问的用户你是给施工队下达任务、验收成果的项目负责人。提示词也不再是“请回答”而是“请执行并且按我的验收标准交付”。1.2 为什么同一套提示词在这里更容易翻车网页聊天里你写“帮我优化一下这段代码”它给你一段优化建议你看完自己贴回去主动权全程在你手里。Claude-Code 场景下同样一句话它会直接把优化后的代码写进文件里——你还没看呢它已经帮你在十几个地方动了刀。我用三个例子说明“敷衍型、模糊型、清晰型”三种指令的差别敷衍型“帮我修一下 bug。”它得从零猜你是哪个 bug后果基本是灾难。模糊型“登录接口有安全问题你优化一下。”它可能会引入限流中间件、改密码存储方案、重写校验逻辑甚至动数据库字段。清晰型“登录接口存在暴力破解风险。请在不改变现有数据库结构的前提下先分析 auth.js 中登录处理逻辑给出限流方案后再动手并补充针对错误密码连续点击的测试用例。”第三种指令里包含了任务目标、边界约束、执行顺序、验收要求这四个维度。你在 Claude-Code 里写提示词本质上是把一套“项目任务书”压缩进几句话里而且是能落地执行的那种不是给人看的愿景描述。2. 上下文工程提示词工程的地基2.1 CLAUDE.md把项目说明书塞进模型脑子大模型提示词工程与上下文工程这两年在圈内早就绑在一起聊了。放在 Claude-Code 场景下上下文工程最典型、最重要的落地方式就是 CLAUDE.md 文件。Claude-Code 在项目里启动后会自动读取当前目录下的 CLAUDE.md把它当作关于这个项目的常驻记忆。你可以把它理解成施工队进场前拿到的那份项目说明书里面写的技术栈、目录结构、代码规范施工队长会始终记住不用你每次重新交代。我见过太多人忽略这个文件导致每次开会话都要重新跟 Claude-Code 讲“这是 Vue3 项目、请用组合式 API、不要在 options API 里加代码”之类的背景。其实把这些固定信息写进 CLAUDE.md 一次后面每一轮对话它都会自动带着这份记忆干活效果完全不在一个量级。一个合理的 CLAUDE.md 至少要覆盖这几个部分技术栈与运行方式框架版本、包管理器、启动命令、测试命令。目录结构说明哪个目录放组件、哪个放业务逻辑、哪个放接口请求。代码风格约定命名规范、禁用 any、路由写法、状态管理规范。明确禁止事项比如“不要修改 migrations 目录下的文件”“不要引入 axios 之外的新请求库”“不要动全局样式”。我项目里实际用过的 CLAUDE.md 大概长这样# 项目说明 这是一个基于 Vue 3 TypeScript Vite 的中台管理系统。 ## 技术栈 - 包管理pnpm - 状态管理Pinia - UI 组件库Element Plus - 请求库axios统一封装在 src/utils/request.ts ## 目录约定 - src/views 放页面组件 - src/components 放通用业务组件 - src/api 放接口定义与后端字段一一对应 - src/hooks 放可复用组合式函数 ## 风格要求 - 组合式 API 优先不新建 options API 组件 - 组件命名使用 PascalCase文件命名使用 kebab-case - 类型必须完整声明禁止 any ## 禁止事项 - 不要修改 src/api 之外的接口定义 - 不要新增第三方依赖除非被明确允许 - 不要修改 vite.config.ts 的代理规则有了这份文件我后续写提示词时根本不用再重复项目背景直接说“给订单列表加一个按状态筛选的组件”就行它自己会结合说明书判断文件放哪、按什么风格写。这份“说明书的编写成本”会在后面每一次交互里被摊薄越用越划算。2.2 文件引用、范围限定与会话管理光有 CLAUDE.md 还不够实时会话里得能灵活地引用具体内容。Claude-Code 支持使用 符号直接引用文件也可以引用整个目录。这相当于施工队长需要看哪张图纸你直接把它递到对方面前而不是让它自己去一堆图纸里翻。我在实际操作里有个习惯涉及跨文件改动时先明确引用核心文件再让 Claude-Code 去读相关依赖。比如让它开发时我会说“先阅读 LoginView.vue 和 utils/request.ts在此基础上实现”。这样它的分析范围就被限定在你指定的文件里避免它到处乱翻——翻得越多误操作的概率越大。会话管理方面同样值得重视。Claude-Code 的上下文窗口是有限的跑过几轮大任务后它会“忘事”。遇到这种情况不要硬撑着继续对话直接用 /clear 清空当前会话然后重新从 CLAUDE.md 中加载记忆。我在长任务中一般会把整个流程分成几步跑先会话一让它分析需求出方案会话二让它写第一个模块会话三让它跑测试修复。每段会话任务专一上下文干净模型的表现会稳定得多。另外提醒一点你要看 Claude-Code 做了什么别只看它回复的文字。我每次都会让它执行完改动后立即展示 git diff没有 diff 的操作我一律视为没写完。把“展示改动”写进提示词里这句话能救你无数次。3. 一套能复用的提示词框架3.1 任务三要素目标、约束、验收我自己在 Claude-Code 里打磨出一套固定句式不管任务大小都往里套。一句话概括每个任务提示词都必须包含目标、约束、验收三个要素。缺一个翻车概率直线上升。目标写清楚要做什么且尽量写最终效果不写实现方式。比如“给注册接口增加防重复提交”是目标。“加一个 Redis 锁”是实现方式你替它把方案想死了反而没空间看它怎么优化。约束明确边界尤其是“不能碰什么”。我吃过太多亏所以在约束里经常写“只允许修改 src/controllers 目录下的文件”“不要改变返回给前端的字段结构”“不要新增依赖”。约束越具体它的小动作越少。验收告诉它“怎么算干完了”。最简单的是让它写完补一个测试跑一遍大一点的改动要求它列出全部改动清单再大一点让它跑完整套测试命令并贴出结果。一个完整的反面案例和正面案例对比反面“后台订单导出功能好像有点问题有空修一下。”正面“后台订单导出功能有三个问题中文文件名导出后乱码、数量超过 5000 条时导出为空、导出按钮无 loading 状态。请在不改动导出数据聚合逻辑的前提下修复这三处。修复后跑一下 export.test.ts 并确认按钮状态逻辑与现有交互组件用法一致。”后者包含了“干什么”“边界是什么”“怎么验收”Claude-Code 拿到手的是一份能直接开工的任务单不再是阅读理解题。3.2 侦察先行先让它出方案再让它动刀很多人的操作习惯是“任务一给就让它直接改代码”这其实是 Claude-Code 提示词工程里风险最大的一步。因为它一旦动手就意味着你的代码库已经被改了后面发现方案不对还得靠 Git 回滚浪费一轮。我的做法是强制加入“侦察阶段”。第一次提示词只描述目标和约束然后在结尾明确写先不要修改任何代码请你阅读相关文件列出改动影响面给出你的实现方案等我确认后再动手。这招在改动规模超过一个文件时极其好用。它相当于让施工队先交一版施工方案给你审批而不是直接抡起锤子砸墙。方案合不合理你一眼就能看出来方向不对就立刻否决代码库毫发无损。我溜过好几次这样的操作过去觉得“多一轮对话很麻烦”现在发现这才是最省时间的方式。一个典型开头大概是这样的“在 src/api/order.ts 中新增一个分页查询订单接口。先不要写代码先阅读该文件和 src/api/request.ts 的封装方式然后给我一份方案说明将影响的文件、接口参数设计和返回结构。确认后你再实现。”3.3 出问题后的纠偏表达公式用了这么久没有不犯错的。关键是 Claude-Code 改错之后你怎么引导它修正。大多数人会直接说“不对不是这样改”这句话对模型的帮助几乎为零——它只知道错了不知道为什么错、错在哪、你期望的正确结果是什么。我总结了一个纠偏公式先说“哪里错了 应该保留什么 具体期望是什么”。打个比方不是“这个按钮太难看了”而是“这个按钮文字间距太挤保留现有圆角样式把 padding 调整为 12px 20px并在 hover 时增加轻微阴影”。拿实际例子说“你这次改坏了搜索逻辑。搜索时应该保留原有的防抖你把它删了另外这个结果是按时间倒序的现在变成正序了。请恢复防抖函数并确保结果排序不变。只修复这两点不要动其他部分。”这种说法模型几乎没有歧义纠偏命中率高到离谱。4. 一次完整任务的实操演示加一个带防重入的按钮状态4.1 第一步给足信息和边界我拿一个实际感受过的场景演示一下完整流程在用户设置页面有个“保存”按钮在用户快速点击时会触发重复提交需要加防重入处理且要考虑按钮在等待时的状态变化。第一轮提示词我这样写“在 UserSettingsView.vue 中保存按钮目前支持连续点击会导致同一表单被重复提交。请先不要修改代码。先阅读该文件的提交逻辑和 src/hooks 目录下已有的钩子函数确认是否已存在可复用的防重入方案。如果没有请给出你的实现方案包括改动文件、函数设计和按钮状态方案。确认无误后再实现。”4.2 第二步审查方案Claude-Code 读完代码后给我的方案大致是在提交函数开头增加一个 isSubmitting 标志位提交期间置为 true结束后重置按钮绑定 loading 属性处理异常时恢复状态避免按钮卡死。它建议将逻辑抽成一个 useSubmitState 的钩子放到 src/hooks 下方便复用。我看了下方案方向没问题但要求它顺带考虑防重入与表单校验的顺序如果校验未通过不应进入 loading 状态。我在提示词里追加了这条约束后方案就完整了。4.3 第三步分步执行与确认我让它先创建 hooks 文件只创建文件、先不接入组件然后跑 TypeScript 检查确认类型无误。它执行完贴出新增文件代码后我再让它接入 UserSettingsView.vue 并运行 lint。这个“先建钩子、再接页面、再跑检查”的顺序保证了每一步之间都有我确认的机会一旦中途方向不对损失最多只是 1 个文件。整个过程的对话记录大概长这样我先新建 hooks/useSubmitState.ts实现通用提交状态管理。Claude-Code已创建代码如下……是否接入组件我接入 UserSettingsView.vue保持表单校验时机不变只替换提交方法。Claude-Code已接入并更新模板中按钮的 loading 状态。改动如下……已运行 pnpm lint 通过。4.4 第四步验收与回归测试最后一步必不可少明确要求它跑测试和展示完整 diff。我会在提示词里写“请运行 pnpm test:unit 和 pnpm lint并列出本次全部改动文件清单和对应修改点。”跑出来后我再用 git diff 把代码过一遍重点看是不是只动了它该动的文件。这一步能拦住九成的意外。很多次 Claude-Code 跑出“全部通过”但不代表逻辑完美diff 里经常能发现它顺手改了别的函数、加了多余的注释、或者改动了一个本来不在任务内的常量。把 diff 检查作为铁律才算真正管住了这支施工队。5. 高频翻车点与排查技巧实录5.1 上下文窗口满了以后它开始“失忆”现象很典型任务做到一半Claude-Code 开始答非所问明明前面确定好的接口字段突然变了或者它反复做同一件事。大概率是上下文撞到顶了。我的处理方式是先看它当前会话足够长时直接 /clear然后重新写一条包含目标、已确定方案、下一步任务的简练提示词。同时把那些“每次都该记住的决策”沉淀进 CLAUDE.md避免每次清空会话都要重新讲一遍基础设定。5.2 它动了一个你没让它动的文件这个现象在本次实践里遇到太多次了。原因通常是提示词里没给权限边界它觉得“相关文件都可以碰”。现在我写任何任务都会在提示词里把“可改文件清单”写清楚必要时候直接说明“不允许修改 src/config 和 migrations 目录”。如果它还是越界就用 --permission-mode 这类运行参数限制它的文件系统权限让它只对特定目录可写。这等于给施工队加了护栏再手滑也只能在允许的范围内手滑。5.3 路径幻觉它“读”了一个不存在的文件还有一次Claude-Code 在方案里写了“已阅读 UserSettingsView.vue”但那文件实际叫 userSettings.vue我一度以为它在骗我。后来才明白它是在根据上下文推测了一个路径。这个问题很好治就是要求它动手前先确认路径。我在提示词里习惯写“如果引用的文件不存在先执行 find 或 ls 定位真实路径再开始阅读”。逼着它跑一下搜索幻觉基本就绝迹了。5.4 大文件被截断改动不完整还有一个高频问题大文件一打开就超出上下文窗口导致它只看到文件前半部分修改时直接把后半段逻辑覆盖了。我现在的做法是让它先定位关键函数、按函数片段处理遇到超大文件时明确要求“只关注 handleSave 函数及其调用处不要输出文件完整内容”。这种“局部视野”策略能大幅减少大文件场景下的误改。下面是我整理的一份问题排查速查表直接照着查就行症状可能原因处理方式改了无关文件缺少权限边界提示词中写明可改文件清单或使用目录权限限制中途“失忆”上下文窗口过满/clear 后重建会话关键决策写入 CLAUDE.md引用了不存在文件路径幻觉强制先执行 ls/find 定位真实路径大文件改动不全上下文截断只针对函数级片段下指令不要求输出全文lint/test 没跑验收条件缺失在提示词中明确要求跑命令并贴结果越改越乱、反复修任务一次下太大拆分任务分步确认后再进行下一步写在最后Claude-Code 的提示词工程核心就一句话把不明确的信息在动手前全部明确。上下文工程管住“它知道的”提示词工程管住“它做的”两者缺一不可。我个人的习惯是在每轮提示词的最后固定加一句“如果任何信息不确定先停下来问我不要自行假设”。这一句话的成本为零但无数次帮我在错误发生前按下了暂停键。大模型工具越强大使用者的表达精度就越值钱这句话放在 Claude-Code 和提示词工程上尤其成立。