这两年我用 AI 写代码，最明显的变化不是“代码生成得快了”，而是“脑子的空余时间变多了”。大多数人聊 AI 编程，默认一上来就问“哪个模型最强”，我却更关心一个问题：当一个模型真正能替我顶住那些重复性极强、却又不得不做的事时，我的工作流应该怎么设计，才能让质量不滑坡、思路不跑偏。

这套被我自己命名为 free-claude-code 的提示词与协作工作流，就是我围绕这种想法沉淀下来的实践记录。它不是什么神秘工具，也不是旁门左道，本质是一套“怎么把 Claude 当作一个能随时接手任务的协作工程师来用”的方法论：从环境搭建、上下文投喂、提示词模板、翻车纠错，到把它嵌进团队日常节奏里。这篇文章不是给纯小白看概念科普的，也不是给已经玩出花样的资深用户做进阶演讲的，而是给那些“用过几次对话式 AI，但总感觉没用到点子上”的开发者，提供一个可以照着抄的完整动作清单。

1. 重新定义 free-claude-code：先解决“手脑脱节”这个最痛的环节

我先说一个反直觉的判断：在编码这件事上，AI 最能替你省时间的，根本不是“从零写业务逻辑”那几分钟，而是那些“你明明知道怎么改，却必须一步一步去找、去翻、去补”的碎片时间。我统计过自己某一次迭代周期的工时，核心逻辑开发只占三成，剩下七成消耗在类型对齐、异常处理、旧接口排查、测试数据准备这些环节上。这正是 hand 和 brain 严重脱节的地方：脑子里清楚下一步要什么，手上却必须先做大量准备工作。

free-claude-code 这个名字，我取的是“自由地写代码”的意思，不是说有免费的额度可以薅，而是说当你把一批固定套路交给 Claude 去执行之后，你作为开发者的注意力可以从这些边角料里解放出来，真正聚焦在“这个模块到底该怎么设计”上。我刚开始把它当高级补全工具用，后来发现它能在多轮对话里保持对项目目标的记忆，于是我把整套用法收敛成一条主线：先描述任务背景，再给出当前代码上下文，最后明确验收标准。这三段式的结构，几乎覆盖了我后来所有提示词模板的底子。

什么场景下这套工作流值得引入？我自己的判断标准很简单：任务里面有“可总结的规则”。比如“所有对外接口都要做参数校验并统一返回格式”“所有新增字段必须先下沉到底层模型再逐层向上映射”“所有测试尽量用表格驱动的方式组织”。只要一件任务包含这类规则，它就可以被拆解、被委派、被批量执行。反之，那些需要强烈前因后果判断、需要人为拍板取舍的事情，AI 暂时不该碰，至少现在不该由它替你做决定。

这条边界想清楚之后，我整个使用方式都变了。以前我打开对话窗口的第一句话是“帮我写个 XX 函数”，结果上下文缺失、指定不全，模型只好猜，猜出来的东西也是四不像。现在我的第一句话通常是“这是一个 XXX 脚本，采用 XXX 架构，我要在 XXX 位置加入 XXX 能力，请先列出你的实现计划，等我确认后再动手”。这个差异，本质上是把 AI 从“应答者”变成“协作者”的分水岭。后面几节我讲的每一步，都是围绕这个定位展开的。

2. 搭建编码环境：从接口凭证到编辑器联通的完整路径

这一节几乎是我所有朋友来问“怎么把 Claude 用起来”时，最容易卡住的地方。多数人以为难点在模型本身，其实真正难的是把模型嵌进日常编码环境，让它在你需要的地方出现，而不是每次都要切到网页端重新贴一遍代码。

2.1 前置准备：账号、密钥与环境变量

先说最基本的接口凭证。你需要先从模型服务方的官方控制台申请一个 API Key，这个 Key 会关联你的账号和对应服务的计费方式。不同地区、不同套餐能用的模型规格有差异，开通之前先把官方文档的限额说明看一遍，尤其是每分钟请求次数和上下文长度限制，这两个参数会直接影响后面编码体验的稳定性。申请完 Key，不要硬编码进代码里，我习惯在项目根目录放一个 .env 文件，里面写一行：

ANTHROPIC_API_KEY=sk-ant-xxxx

然后用环境变量注入的方式让客户端读取。这样做的理由很简单：一旦你需要把项目分享、提交、部署，.env 通常都在 .gitignore 里被忽略掉，不会把密钥泄漏进仓库。我见过不止一个人为了方便，把 Key 直接写在配置文件里传上去，结果被自动扫描工具盯上，第二天账单就跑出几十美元的异常费用。

2.2 接入编辑器：CLI 客户端组合常规编辑器

我也不建议只用网页端聊代码，更推荐两种接法：

一是使用官方提供的命令行交互客户端。这种客户端可以在终端里直接读取当前目录的源码树、查看文件内容、执行命令，还能在修改文件时做结构化 diff。你只需要在项目目录下启动，它就能自动感知这是一个什么语言、什么结构的项目，这比你在网页端反复贴“这是我的目录结构”要省力得多。

二是在主流代码编辑器里安装社区维护的 Claude 扩展插件。插件的优势是可以在编辑器内选中代码直接发送给模型，回填时也以 diff 形式展示，体验更顺滑。但社区插件质量参差不齐，我选插件的标准有三条：看是否还在活跃维护、看是否支持自定义 base URL / 代理地址、看提 issue 时作者的响应速度。这三条都满足的，基本可以放心用。

2.3 三个我每次都会微调的运行参数

很多人把一个模型当“开箱即用”的黑盒子，实际编码类任务里，有三个参数值得你手动干预。

第一个是 temperature，也就是随机性。生成代码、补全逻辑这种追求确定性的任务，我通常把 temperature 调到 0.2 左右，甚至更低，避免它发挥“创意”写出一些表面上通顺、实际上不存在的 API 调用。如果你拿它做头脑风暴、设计讨论，再调到 0.7 以上都不为过。

第二个是 max tokens，也就是单次输出上限。像“重写整个文件”这种任务，如果上限设小了，输出会被截断，拿到手的是半截源码。我一般按照源文件体量的三倍来设置上限，保证一次能吐完主体内容，再逐步要求它填充剩余细节。

第三个是上下文窗口。这决定了你在一次会话里能塞进多少代码。长篇大论地贴代码只会浪费空间，我通常只贴两个东西：必须改动的当前函数，和与它有关的函数签名、数据结构定义。这个做法会在下一节详谈。

2.4 第一次跑通：从“能对话”到“在干活”的验收标准

环境搭好之后，第一件事别急着让它写大系统。我的建议是先丢一个小任务进去，比如“把某个目录下的日志输出统一改为 JSON 格式，时间戳带时区”。这里有个很容易被忽略的细节：如果这个任务你至少要 20 分钟，但 Claude 只需要 2 分钟，请先手动做一半再交出去。为什么？因为你对当前代码的领悟，远比对模型的信任更重要。先亲手做一遍，你才会知道“日志输出统一”这件事在这个项目里牵扯了多少个入口，涉及哪些边界场景。带着这些信息再委托任务，你就能在它给出的方案里一眼看出错误。

我第一次跑通完整链路时，给的是一段包含历史包袱的库存扣减代码，需要重构出防超卖逻辑。Claude 花十几秒给出方案，还主动分析了三个潜在竞争条件。那一刻我对“环境是否配好”的定义就不是“能不能弹出 hello”，而是“它是否看得懂我项目里那些别扭的命名规范和隐式依赖”。这个标准很高，但值得。

3. 让它真正看懂你的项目：上下文投喂的四种有效姿势

在编码场景里，模型输出的质量八成取决于上下文投喂质量，而不是模型能力本身。我把踩坑得来的经验整理成四种姿势，按有效性从低到高排列。这套排序不是随便拍的，每一步我都用实际项目的修改任务验证过。

3.1 只丢报错信息，然后坐等

这是新手最常见的用法：把编译器的报错、运行时堆栈直接贴给 Claude，问“怎么修”。它的效果看运气。如果报错信息足够明确，比如“找不到模块 xxx”“类型 ‘string’ 上不存在属性 ‘trim2’”，模型基本能命中。但只要涉及跨文件调用、依赖项不明、初始化顺序问题，单靠报错会导致它频繁开启“猜测模式”，输出一堆看似合理、实际不兼容的修复建议。这类场景的正确姿势，至少要叠加下面第二种。

3.2 报错信息 + 相关代码片段

正确的上手段是：在贴报错之前，先描述这个代码在什么流程中执行，再贴出涉及的那一段核心函数与相邻调用关系。比如你想修一个“数据库连接泄漏”的问题，至少要给它看连接在何处被创建、在何处被关闭、异常路径里有没有走 finally 或者 with 块。只贴报错不贴上下文，模型只能靠统计规律推算；贴上上下文，它才能基于真实控制流找问题。

我在给上下文的时候，会在待修改文件之外，额外提供一个“stub 上下文”文件，里面只保留相关类型的定义、函数签名和关键注释，把无关代码全部摘除。这样既保证信息够用，又不至于把几千行代码一股脑倒进去浪费窗口。

3.3 结构化任务简报：用一段人在交付任务时会说的话开头

到了某个阶段你会发现，真正好用的上下文不是“代码”，而是“任务简报”。我会在输入框里写三段式内容：背景是什么，目标是什么，限制条件是什么。

背景：order 服务里现有扣减库存逻辑是直接操作数据库字段，存在并发覆盖风险。 目标：改为基于 Redis 预扣 + 异步对账的流程，对外接口保持兼容。 限制：不允许引入额外的消息队列组件，Redis 可用；技术栈不允许用 Lua 脚本。 请先给出改造方案，再逐步落到代码。

这种简报看起来简单，但作用非常大。它帮助模型在动手前先建立一个“问题空间”，而不是拿到一段代码就开始改。我在实际测试里发现，给完整简报后的方案，与只给代码片段后的方案相比，出现“方向性错误”的概率明显下降；而且后续多轮对话里，模型更容易记得你为什么要这么改，而不是只记得改了什么。

3.4 多轮迭代：让对话保持一个不断修正的“工程记忆”

编码任务很少一轮对话就能结束，更常见的是：你给它看脚本，它给出方案；你调整需求，它改一版；你测出边界问题，它再打一个补丁。每一轮修改都会产生新的上下文。我的习惯是，当对话轮次超过六轮之后，不再继续在旧会话里改，而是新建一条会话，把“上一轮结论摘要 + 最新完整代码”作为新会话的上下文重新粘贴。

为什么这么做？因为长对话早期的错误假设会留在上下文中，后面模型越走越偏，很难回到正轨。我整理过一张对比表，记录同样一个重构任务在不同上下文条件下的结果：

四列对比下来，结论很清晰：时间应该花在前期简报和上下文组织上，而不是在后期的反复纠错里。

4. 四个拿来即用的提示词模板，覆盖最值钱的编码场景

在编码辅助这件事上，最常见的做法是让 AI “帮我写”代码，但真正能沉淀成工作流的，是几个不用动脑、随手能套的提示词模板。我自己保留了四个最常使用的类型，全部经过实际项目迭代打磨，现在分享给你。

4.1 代码审查模板：先找问题，再谈改法

让 Claude 做代码审查跟人做审查不一样。人很容易本能地去挑风格问题，而 Claude 更擅长做两件事：按规则扫描和按可能性评估风险。我给它的审查提示词是这样：

请对以下代码做一次严格的 code review，按严重程度列出问题： 1. 功能性缺陷：是否会导致报错、死循环、数据错误？ 2. 并发/资源问题：是否存在竞态、泄漏、未释放的资源？ 3. 可维护性问题：命名、结构、重复代码、隐藏耦合。 4. 边界条件：空数组、极端数值、超时、不存在的文件。 对每条问题，请先引用具体代码行，再说明影响场景，最后给出修复建议。 只有在你确认没有更严重问题时，才提供改后代码。

这个模板的关键句是最后一句：“只有在你确认没有更严重问题时，才提供改后代码。” 不加这句话时，模型容易被“展示修复能力”的冲动带偏，先改代码再理由，结果是问题清单被淹没在代码 diff 里，可读性很差。加上这句话之后，它会更像一个保守的审查者。

4.2 调试排错模板：限制排查范围，给出验证条件

排查 bug 最糟糕的情况，是让 AI 在完全开放的代码空间里自由联想，那样它会把 500 个行号全怀疑一遍。我现在的排查模板是：

代码运行时报错如下：[粘贴堆栈/日志]。 我已经怀疑问题可能出现在以下两个方向：[A 假设] / [B 假设]。 请基于代码上下文，验证这两个方向哪个成立，并给出可观测的实验方法。 如果两个方向都不成立，再提出新的怀疑方向。

这个模板的好处是逼自己先形成假设，再把 AI 当作“证伪伙伴”而不是“答案机器”。在真实项目中，让 AI 验证一个已经成型的方向，比让它从零开始猜，准确率要高一截。我经常遇到这种情况：我怀疑是缓存过期问题，Claude 看完上下文后回复“这个方向不成立，问题在序列化逻辑，因为缓存 key 在写入和读取时长度不一致”，然后我按照它的方向加一行日志，立刻复现。

4.3 重构模板：先出迁移影响清单，再动手改动

重构最大的风险不是写代码，而是不知道哪些调用点会被影响。我让 Claude 参与重构时，绝不直接说“帮我重构”，而是先要求它交付一份影响清单。

我要把 [模块 A] 的 [方法 B] 重构为体系：入口参数不变，但内部改用 [设计思路 C]。 请先完成两件事： - 在项目目录中搜索所有调用 B 的代码位置，逐一分析调用点是否需要修改； - 给出重构后的代码，并在注释中标记每个业务语义差异点。 确认无误后，再开始修改对应文件。

这个顺序满足了人类开发者最朴素的焦虑：先知道灾难半径，再按下确认按钮。实际操作中，我把“调用点搜索”交给插件自动化完成，但会让 Claude 分析调用点语义，避免替换后出现“参数没变但逻辑语义完全变化”的事故。

4.4 测试生成模板：把验收条件变成可执行断言

写测试这件事，AI 比大多数人类开发者在“覆盖边界”这件事上强得多。我给它的测试生成模板长这样：

下面是函数 [函数签名] 和它的实现代码。请生成一组单元测试，要求： 1. 覆盖 happy path、边缘值、错误输入、异常抛出四类场景； 2. 每个用例必须包含一个明确的断言意图，如“空列表输入时，返回值应为 0”； 3. 不要 mock 掉被测函数内部需要验证的逻辑； 4. 每个测试用例必须能独立运行，不能依赖执行顺序。

我从这个模板得到的收益不只是“测试数量变多”，而是“测试的意图变得可被评审”。因为每一条例都带了一句人类可读的断言说明，我哪怕不想细读全部代码，也能快速发现“这里少测了负数输入”“这里没覆盖超时分支”。

4.5 模板之外，还有一个必须遵守的底线

这些模板之所以有效，共同点是它们都给了模型两个东西：明确的任务边界，和明确的验证条件。反过来，如果你的提示词只是“帮我优化一下”，那模型会默认选择“重命名变量 + 调整格式 + 加几个注释”这种无效努力。它不蠢，只是你没有告诉它“优化”在这个代码里具体指什么。模板的作用，就是替你把“优化”翻译成“安全性、可读性、可测试性”这些可以被审视的指标。

5. 翻车现场与纠偏手法：Claude 参与编码时常见的四种失效模式

再好的模板也有失灵的时候。这一节我想专门讲讲排错的过程，因为我看过太多人把模型输出的第一版代码当成最终方案贴进仓库，结果上线前三天开始连环爆雷。我把自己踩过的坑按失效模式拆成四类，每一类都附上当时的排查思路和最终的处理手段。

5.1 失效模式一：AI 版“刻舟求剑”——用过时 API 造新代码

某次做一个小工具，需要读取历史数据文件并做格式转换。Claude 在处理文件解析时，频繁引用了老版本才存在的类名和方法名，编译时直接报“module has no attribute”。我当时没有马上否定模型，而是沿着一条非比寻常的排查思路走了一遍。

我先让它重新读一遍项目的依赖配置文件，确认当前锁定版本；再让它从依赖包源码里搜索目标类是否真实存在。结果发现它完全用统计概率在“猜”这个库某个新版本里的接口，而不是去读源码。从那以后，凡是涉及第三方库调用的生成代码，我必在验收条件里加一条：“代码中涉及的所有第三方 API，必须从本地安装的包源码或类型声明中核实，不能凭记忆生成。”这样等于强行切断了它最常见的幻觉来源。

5.2 失效模式二：硬编假设，明明没找到东西却假装已经有结果

另一个具有迷惑性的场景，是 Claude 在处理文件路径时“假性成功”。比如我让它查找某个配置文件并修改参数，它在不知道文件是否存在的状况下，会理所当然地生成一段以该文件存在为前提的代码，甚至在路径不存在的情况下也可以自我圆场。后来的排查方式比较原始：我先自己在终端执行find命令确认路径真实存在，再用 wake 的方式把路径返还给它，并要求它在代码开头加一个存在性校验；如果文件不存在，直接报出清晰错误。这在工程项目里看起来很小，却能避免一系列“本地能跑，服务器上崩”的幽灵问题。

5.3 失效模式三：视野局限在单文件，改一处伤及全局

那次改动是给一套积分系统加一个“老用户补发”的功能。我只把积分发放函数所在文件发给了 Claude，结果它兴高采烈地在函数内部加了一个新的循环处理补发明细，完全没意识到当月流水表结构里有个不为人知的唯一索引约束，后面旁路入账会有主键冲突。这个问题实质上出在我给的上下文太窄，模型只看到一平方米的地板，当然不知道隔壁房间已经铺好了线缆。

修正路径有两条。第一条是死板但稳妥：在任务简报里补齐“所有与积分流水相关的表结构与既有索引约束，以及可能调用到本函数的其他入口”，让模型自己体会影响面。第二条是治本的：不要一次性让它改正式代码，而是要求它先给“改动方案 + 影响文件清单”，等你在清单上签字确认后，它再动手。这两步路径走完，单文件幻觉基本绝迹。

5.4 失效模式四：被早期错误假设带偏，多轮修正仍原地打转

有一次让 Claude 帮忙设计一个批量导入的幂等机制。第一轮它误判了幂等键的选择粒度，认为应该用“用户 ID + 文件批次号”做唯一键，后面每轮修改都服务于这个不靠谱的假设，越补越复杂，像打补丁的补丁。我一开始没有发现，因为每一轮的输出看起来都有道理；后来把会话记录翻出来，才发现它始终没有质疑过最初那句“用批次号做幂等键”的判断。

类似这种问题的纠偏方式，是主动在对话里插入一次“重新审题”指令。我会直接问它：“请回到最初的需求，重新评估幂等键的选择是否合理，从数据正确性角度指出，用当前键可能出现什么重复或漏数据问题。”这一问，它立刻意识到批次号在不同批次间可能重复，从而主动切换成“业务流水号 + 用户 ID”的组合。后来我也习惯了：任何超过三轮的对话，至少安排一次“重新审题”的复盘，不要让对话惯性决定需求方向。

这四种失效模式有一个共同特点：它们都不是模型“不聪明”，而是它没法替你把真实世界的约束带进对话里。你能做的，就是主动把约束给它，同时每到一个阶段做一次方向校验。

6. “free” 的真正含义：把 Claude 嵌入工作流之后，我的几条长期体会

最后我想聊点务虚的。前面讲的都是具体操作，但能不能真正把这套流程用出价值，取决于你如何定义这条路。

先说协作习惯上的变化。以前我审查代码，看的是“这个函数边界是否安全”“这个异常是否会被吞掉”，现在我审查 AI 生成的代码时，顺序完全不同：先看上下文是否完整，再看方案是否贴合需求，最后才看代码细节。三遍下来，要花的时间没有少多少，但整体质量稳定性高了一截。因为代码本身的细节错误，AI 下一步就能帮你改掉，但方案层面的方向错误，你是没法通过让它改一行两行代码来救回来的。

再说怎么把单次成果沉淀成团队资产。我会定期把用到次数最多、效果最稳的提示词模板存进项目库的prompts/目录下，文件名就是场景名，比如review-core-logic.md、generate-import-validation-tests.md。新同事接手陌生模块时，先读模板目录，再读代码，上手速度明显比对着代码硬啃快。这种做法收益最大的不是省时间，而是让“调用 Claude 辅助开发”从一个神秘的个人技巧，变成了团队里可以被讨论、被改进的常规动作。

还有一个建议：别让 AI 代码直接进主干。我自己现在的流程是，Claude 的产出先落在临时分支，接下来做三件事：跑一遍静态检查工具、写一个覆盖主要分支的单元测试、再人工阅读一遍核心逻辑。这三步流程，从单次任务上看来是“浪费”的，但从长期看，它才是“free”的底气所在。因为只有你敢说这段代码“我按我的标准验收过了”，你才敢在后续修改中放心地继续委托给它。

于是，回到标题。free-claude-code 的自由，从来不是指“使用是免费的”，而是指“你不再需要亲手去应付那些细枝末节，可以把时间留给真正需要判断力的地方”。对这种自由的理解越深，你设计提示词、组织上下文、安排验收步骤的方式就会越顺畅。反正我自己是越用越省心，少操了很多原本必须操的心。