Claude 3.5 Sonnet写代码实操秘籍：如何写出让AI一次性跑通的 Prompt（提示词）

让 AI 写代码，最烦的不是它不会写，而是写完跑不起来：少个依赖、参数形状不对、接口名记混，你还得来回追问三四轮。这篇不聊玄学，只讲怎么把一次请求写成结构清楚的任务说明书，包含哪几段必写、什么信号说明该拆成两步、第一次就出错按什么顺序排查。价格和额度相关的问题，直接去站内对应入口看当时的数字。

让 AI 写代码，最烦的不是它不会写，而是写完跑不起来：少个依赖、参数形状不对、接口名记混，你还得来回追问三四轮。这篇不聊玄学，只讲怎么把一次请求写成结构清楚的任务说明书。我会按顺序讲：先看一次跑不通到底卡在哪，再给一套六段式骨架，然后是上下文怎么喂、任务怎么切、形状怎么定、出错按什么顺序查，最后怎么把好用的写法沉淀成自己的模板。

全程只给写法和判据，不编造实测数字。价格、额度、模型版本这类会变的东西，一律写「去站内对应页面看当时的数字」。你照着改一改就能用，重点在结构，不在话术。

先搞清楚：一次跑不通通常不是模型不行

很多人第一反应是「这模型写代码不行」，但把失败的对话翻出来看，八成问题出在提示词侧。最典型的三类：任务范围太大，一次把重构、加功能、改配置全塞进去；运行环境没交代，它默认按自己的习惯选包管理器、按自己的假设定目录；验收标准缺失，它不知道你要什么算通过，于是自由发挥。

范围过大

一次请求里塞了多个独立目标，它顾此失彼，谁都做不完整

环境缺失

没说运行时、包管理器、已有目录结构，它按默认猜，跑起来就对不上

验收缺失

没定义怎么算通过，它按自己理解收尾，输出和你期望错位

怎么区分「它写错了」和「你没说清」？一个简单判据：把同一条需求原样发给另一个同事，他会不会理解偏差？会，那就是提示词问题，改模型没用。但这条判断有个不适用场景——纯粹的算法探索题、需要反复试错的调试场景，本来就不该指望一次成型，那种情况下拆成多轮交互才是正常做法。

一次性跑通的提示词骨架：六段结构

把一次请求想象成写给外包的任务说明书，缺哪段都容易返工。下面这六段是我反复验证过、能覆盖大多数编码场景的骨架，你可以按需删减，但别整体跳段。

1. 角色与约束一句话说清技术栈和边界，比如「用现有项目里的 TypeScript 写法，不要引入新依赖」。版本口径别写死成具体数字，写成「和项目现有版本保持一致」更稳。
2. 输入与输出贴出真实的入参样例和期望的返回样例，比口头描述有效得多。调用方怎么传、你希望拿到什么形状，各给一段代码块。
3. 运行环境交代运行时、包管理器、已有目录结构、哪些文件不要动。特别是「只改这个文件」还是「可新建文件」，写清楚。
4. 边界与异常空值、超时、并发上限、重试策略怎么处理，写出来而不是让它猜。猜错的代价是你后面要重写。
5. 验收方式希望怎么验证：跑哪条命令、看什么输出算通过。有现成测试就说明是否会跑测试。
6. 交付形态整文件替换还是只给 diff，要不要连测试一起写，注释要不要保留，一次说清。

把上下文喂对：给什么、不给什么

上下文不是越多越好。整仓库贴进去只会稀释重点，模型要在噪声里找信号，找错的概率反而上升。原则是：给和这次改动直接相关的东西，无关的全部折叠掉。

• 相关的报错原文——整段贴，别只截一句，堆栈信息里藏着线索
• 接口定义和类型声明——它能不能猜准，取决于你有没有给准
• 长文件只给会被改动的函数上下文，前后无关部分折叠
• 不确定它认不认识的第三方库，直接把用到的函数签名贴出来最省事

反面情况也要知道：有些场景天然不适合把代码全塞进一次对话。比如你需要它理解一个跨越十几个文件的调用链，正确做法是先走检索或分步，而不是硬塞。硬塞的结果通常是它抓住局部忘了全局，改完这里崩那里。

给上下文的三条边界：；1. 这次会被改动的代码，完整给；；2. 改动会牵动的调用方，给签名和用法；；3. 其余无关代码，一行都不给。

任务切分：什么活该一次给，什么活必须拆

不是所有需求都适合一次请求。判断标准其实很简单：你能不能在一段话里把先后顺序讲清楚。讲得清，可以一次给；讲不清，说明你自己还没想明白，模型更想不明白。

拆开之后有个坑要避开：接口契约必须提前说好。函数名、参数、返回结构先定下来，再分头实现，否则拼起来对不上，返工量比一次给还大。这一步做完，各部分之间才有接缝可言。

把「随便写」变成「按这个形状写」

自然语言描述结构最不稳定，你说「返回一个对象包含用户信息」，它可能给你三种不同字段名。解决办法是把参数结构和返回结构直接写成代码块示例，让它照着填。这和结构化输出的通用原则是一回事：用形状约束，而不是用形容词描述。

• 参数、返回结构用代码块给示例，别用「大概长这样」这种说法
• 团队约定一次说清：命名风格、错误处理方式、日志格式，比逐条纠正省事
• 要求它先复述理解再写代码，能在动笔前暴露理解偏差
• 反复出现格式跑偏时，考虑用函数调用或严格模式约束，而不是继续加修饰词

这里有个判断标准：如果你发现自己在反复用「请确保」「务必」「一定要」这类词，说明约束没写成结构。形容词加得越多，说明前面的形状定义越弱。真正稳的写法是给一个能照抄的骨架，而不是一遍遍强调重要性。

第一次没跑通：按这个顺序排查

出错别急着重开，先按顺序过一遍，绝大多数问题能定位到具体环节。

1. 第一步：查约束是否被漏看它是不是忽略了你交代的约束。是的话，把约束补进提示词的对应段落，而不是在对话里口头纠正——口头纠正下次不会记住。
2. 第二步：给报错分类环境缺失、类型不符、逻辑错误，三类改法完全不同。环境问题补依赖和命令，类型问题改形状定义，逻辑问题才需要重新描述算法。
3. 第三步：决定追问还是重开小范围修正可以继续同一段对话。涉及大范围改动、或者对话已经来回好几轮越改越乱时，重建上下文更快。
4. 第四步：把修正回填模板每次修完，回头看看这类错误是不是第二次出现了。是的话，说明你的模板缺项，补进去而不是记在心里。

第三条的判据值得单独说：同一段对话里改动超过两三次还没收敛，通常不是模型的问题，是上下文里已经混进了错误假设。这时候重开一段、只带正确信息，往往一次就过。

同一类错误出现第二次，就不是模型的锅，是模板缺了那一项。

把有效的写法沉淀成自己的模板

一次跑通之后别急着关掉，花两分钟把这次用的提示词存下来。按任务类型分几套：写新函数、改现有逻辑、写测试、修 bug，各自固定段落。下次直接改内容，不用从零想结构。

• 模板里留空位而不是写死内容，避免直接套用却忘了换环境信息
• 每次跑通后补一句「这次为什么顺」，比记一堆抽象原则有用
• 模板按任务类型分，别指望一套打天下
• 任务性质变了就别硬套，模板是省事工具不是流程枷锁

什么时候该放弃模板？当你发现自己在为一个新场景反复删改模板里的段落时，说明这个场景需要的是新模板，不是旧模板的变体。硬套的结果是每次都要绕一圈才能说清需求。

配额、模型版本与价格去哪核对

写法和结构可以照这篇做，但涉及具体数字的部分必须看当时的真实情况。模型能力、版本说明这类会变的信息，去站内模型库按当时的说明核对，别照搬别人几周前的描述。

• 模型能力和版本说明，到 /models 按当时的资料核对
• 额度与套餐的折算口径按你实际用的入口看，不同渠道算法不一样
• 要对比不同渠道单价，用 /price-watch 和站内换算工具跑一遍，比手动估算靠谱
• 想知道某个中转站靠不靠谱，去 /sites 看检测结果

为什么强调「当时的数字」？因为价格、额度、可用模型都在变，任何写死的数字过一阵就不准了。你真正要带走的不是某个数值，而是去哪里查、怎么核对的方法。