1. 从“补全代码”到“交付功能”重新理解 Claude 写代码这件事很多人第一次听说“用 Claude 写全部代码”脑子里浮现的画面是打开一个聊天窗口敲一句“帮我写个登录页面”然后复制粘贴。这种用法确实存在但它和真正把 Claude 当作主力开发工具是两件完全不同的事。前者是把模型当成一个高级搜索引擎后者是把模型当成一个能读项目、能改文件、能跑命令、能提交 PR 的协作方。差别不在模型本身而在你给它搭的“工作环境”和“约束规则”。我自己从最早用聊天窗口贴代码到后来把 Claude 接进终端、接进编辑器、让它直接操作仓库中间踩的坑基本都集中在三个地方上下文怎么给、权限怎么控、结果怎么验。这三个问题不解决模型再强也只能当玩具解决了它才可能承担真实项目里 60% 到 80% 的重复性编码工作。这篇文章不打算复述官方文档而是把“工程师到底怎么用 Claude 写代码”拆成可复现的环节从安装和接入方式的选择到AGENTS.md这类上下文文件的写法再到让它改代码、跑测试、提 PR 的完整链路最后讲清楚哪些活绝对不能交给它、哪些坑我踩过之后再也不碰。适合已经会写代码、但还没把大模型真正嵌进日常开发流的人看也适合刚开始接触 Claude Code 这类工具、想知道“别人到底怎么用”的读者。需要先说明一点下面提到的具体命令、配置和文件结构一部分来自我自己的实践一部分是基于这类工具常见设计做的合理推断。不同版本、不同接入方式会有差异重点是理解背后的思路而不是死记某一条命令。2. 接入方式的选择终端、编辑器还是桌面端2.1 三种形态各自解决什么问题Claude 写代码的接入方式目前主流是三类终端里的命令行工具、编辑器插件、以及独立的桌面客户端。它们不是互相替代的关系而是对应不同的工作场景。终端形态最大的优势是离仓库最近。你在项目根目录启动它能直接读到当前目录的文件树、git状态、甚至最近的提交记录。对于“改一个函数、跑一下测试、看 diff”这种高频小循环终端形态的延迟最低也最容易和现有的npm、pytest、make等命令串起来。缺点是交互界面朴素长对话回溯不如图形界面方便。编辑器插件解决的是边看边改的问题。你在文件里选中一段代码直接让它解释、重构、补测试改动以 diff 形式呈现在编辑器里接受或拒绝都在同一个窗口完成。它适合“我已经知道要改哪里只是懒得手写”的场景。但插件对项目全局的理解通常弱于终端形态因为它拿到的上下文往往局限于当前打开的文件。桌面客户端则更像一个独立的工作台适合做跨仓库的调研、写文档、整理需求或者在不方便开终端的环境里做原型验证。它的短板是和本地文件系统的联动不如前两者直接很多时候还是要靠复制粘贴。我的建议是主力用终端形态编辑器插件做补充桌面端留给非编码任务。不要一上来就三个都装先把一个用顺再按需扩展。2.2 安装前必须确认的环境前提在动手安装之前有几个环境问题必须先确认否则后面会卡在莫名其妙的地方。第一是Node.js 版本。这类命令行工具大多基于 Node 生态分发版本过低会直接报错。建议用当前 LTS 版本安装前先跑node -v确认。如果机器上有多个项目依赖不同 Node 版本用版本管理工具切换不要硬改全局。第二是系统权限和虚拟化相关提示。在部分系统上首次启动会提示需要启用某些平台组件这属于正常的运行环境要求按提示开启即可。如果公司电脑有安全策略限制提前和 IT 确认别装到一半被拦。第三是网络与鉴权。无论用哪种接入方式都要先解决“模型怎么调用”的问题。有的走官方账号登录有的走 API Key有的接第三方兼容接口。这里有个原则鉴权信息只放在环境变量或专用配置里绝不写进代码仓库。我见过有人把 Key 直接写进AGENTS.md或者提交到 git这是典型的自找麻烦。正确的做法是本地用.env文件并加入.gitignoreCI 环境用密钥管理服务注入。第四是先在一个小仓库里试。不要拿公司核心项目当试验田。找一个自己的练手项目或者新建一个空仓库把安装、启动、第一次对话跑通再考虑迁移到真实项目。2.3 第一次启动后该做的三件事装完之后别急着让它写业务代码先做三件小事建立信任。第一件让它描述当前仓库结构。问一句“这个项目的目录结构是怎样的入口文件在哪”看它能不能准确读出来。如果它答得含糊说明上下文没接上先解决这个问题。第二件让它做一个只读操作。比如“找出所有没有被引用的导出函数”或者“列出最近三次提交改动了哪些文件”。只读操作不会破坏任何东西但能验证它是否真的能访问仓库信息。第三件让它改一个无关紧要的文件比如给某个工具函数补一行注释然后你自己看 diff。这一步是建立“它改的东西我会检查”的习惯后面所有操作都建立在这个习惯上。这三件事做完你基本就知道当前这套配置的能力边界在哪了。3. AGENTS.md 到底该写什么把隐性规则变成显性约束3.1 为什么需要一个上下文文件模型每次对话都是“失忆”的它不知道你的项目用什么框架、命名规范是什么、哪些目录不能碰、测试怎么跑。如果每次都要在对话里重复这些信息效率极低而且容易漏。AGENTS.md这类文件的作用就是把这些每次都要说的规则固化下来让模型在开始工作前自动读取。它本质上是一份“给 AI 看的项目说明书”。写得好模型第一次输出就八九不离十写得差你就要在每一轮对话里反复纠正。我见过太多人抱怨“模型不听话”其实问题出在规则根本没写清楚。3.2 必须写进去的四类信息一份能用的AGENTS.md至少覆盖四类内容。第一类是项目定位和技术栈。用两三句话说明这个项目是干什么的、用什么语言和框架、依赖管理工具是什么。比如“这是一个基于 Node 的 CLI 工具用 TypeScript 编写包管理用 pnpm测试用 vitest”。这几句话能让模型在生成代码时自动匹配技术栈而不是给你写一段 Python。第二类是目录约定和禁区。明确哪些目录是源码、哪些是生成产物、哪些绝对不能改。比如“src/是源码dist/是构建产物不要手动改migrations/下的文件一旦提交不要修改”。禁区写清楚能避免很多灾难性操作。第三类是编码规范和命令。包括命名风格、导入顺序、注释语言以及最关键的——怎么跑测试、怎么跑 lint、怎么构建。把命令写进去模型就能自己验证改动而不是改完就交差。这一条是区分“能用”和“好用”的关键。第四类是协作规则。比如“每次改动前先说明计划”“不要一次改超过三个文件”“提交信息用中文还是英文”。这些规则决定了你和模型的协作节奏。下面是一个简化示例实际项目按需增删# 项目说明 这是一个内部使用的数据处理 CLITypeScript Node 20包管理用 pnpm。 # 目录约定 - src/ 源码所有改动只在这里 - tests/ 测试文件新增功能必须补测试 - dist/ 构建产物禁止手动修改 - config/ 配置文件改动前先确认 # 常用命令 - 安装依赖pnpm install - 跑测试pnpm test - 类型检查pnpm typecheck - 构建pnpm build # 协作规则 - 改动前先用一句话说明计划 - 单次改动不超过 3 个文件 - 提交信息用中文格式类型: 简述3.3 写 AGENTS.md 最容易犯的三个错第一个错是写得太长。有人把整个架构文档塞进去几千字结果模型每次都要消耗大量上下文去读真正有用的规则反而被淹没。原则是只写“每次都需要知道”的信息详细的架构文档放单独文件需要时再引用。第二个错是规则模糊。“代码要写得优雅”“注意性能”这种话等于没写。要写成可执行的判断标准比如“函数超过 50 行就拆分”“避免在循环里做数据库查询”。第三个错是写完就不管。项目在变规则也要跟着变。我习惯每次发现模型重复犯同一个错就回头往AGENTS.md里补一条。这个文件是活的不是一次性作业。提示如果你的项目已经有README或贡献指南不要直接复制过来。AGENTS.md面向的是模型要更简洁、更命令化去掉所有面向人类的客套话。4. 让它真正改代码从单文件到跨文件重构的实操链路4.1 单文件改动的标准流程单文件改动是最基础的场景但流程不对照样出问题。我的标准流程是四步说计划、看 diff、跑测试、再提交。第一步先让它说计划。不要直接说“帮我改这个函数”而是说“我想让这个函数支持超时参数你先说说打算怎么改”。模型会给出一个方案你看一眼有没有跑偏。这一步花不了几秒钟但能挡掉大部分方向性错误。第二步让它改然后你自己看 diff。不要因为它说“已完成”就信了。重点看三件事有没有动到不该动的文件、有没有引入新的依赖、逻辑是不是真的符合你的预期。我遇到过模型为了“顺手优化”把无关代码也改了的情况diff 一看就发现。第三步跑测试。如果项目有测试让它自己跑如果没有至少跑一下类型检查和 lint。这一步是底线不能省。第四步确认无误再提交。提交信息可以让它生成但你要过一眼。4.2 跨文件重构怎么控制风险跨文件重构是模型最容易翻车的地方。它可能改了一个函数的签名却漏掉了三个调用点或者重命名了一个模块却忘了更新导入路径。控制风险的核心是缩小单次改动范围并且让它在改之前先列出影响面。具体做法是先让它“找出所有引用了这个函数的地方”确认清单完整然后让它“按这个清单逐个修改每改完一个文件停下来等我确认”。不要一次性说“把整个项目里所有用到这个函数的地方都改了”那样你根本来不及检查。另一个技巧是用 git 分支隔离。每次让它做大改动之前先开一个新分支。改完如果不对直接丢弃分支不影响主线。这个习惯救过我很多次。还有一个细节跨文件改动时让它先改被依赖的底层再改上层调用。顺序反了的话中间状态会有一堆编译错误很难判断是模型改错了还是顺序问题。4.3 测试和验证环节不能省模型生成的代码最大的问题不是“写不出来”而是“看起来对但实际有边界问题”。比如它写的解析函数正常输入没问题遇到空值就崩。这类问题只有跑测试才能发现。我的做法是让它改代码的同时补测试。在AGENTS.md里写清楚“新增功能必须补测试”它就会在改完之后顺手写几个用例。这些用例不一定完美但至少覆盖了主路径。然后你自己再补几个边界用例。如果项目测试覆盖率本来就低可以先让它“为这个模块补一批测试覆盖主要分支”跑通之后再动业务代码。这样你手里就有一张安全网后面改动心里有底。注意不要完全信任模型写的测试。它有可能写出“永远通过”的假测试比如断言写得太宽松或者干脆没断言。跑完之后扫一眼测试内容确认它真的在验证行为。5. 从改代码到提 PR把重复劳动交给它把判断留给自己5.1 让它生成 PR 描述和提交信息写 PR 描述是典型的重复劳动而且模型做得不差。它能读 diff、读提交记录然后总结出“改了什么、为什么改、怎么验证”。我的做法是让它生成初稿然后自己改两处补充业务背景和删掉它过度自信的表述。提交信息同理。约定好格式之后让它按格式生成你过一眼就行。这里有个小技巧在AGENTS.md里写清楚提交信息的格式和语言它就会一直遵守不用每次提醒。5.2 自动化检查该挂在哪一环真正高效的用法是把模型接进 CI 流程的前置环节而不是替代 CI。比如在提交前让它跑一遍 lint 和类型检查把明显问题挡在本地CI 里该跑的测试、构建、安全扫描一个都不能少。我见过有人让模型“自己判断能不能合并”这是危险的。模型的判断不能替代 CI 的硬性检查。正确的分工是模型负责生成和初步验证CI 负责最终把关。5.3 哪些 PR 绝对不要让模型碰有几类改动我的原则是模型可以参与讨论但不能直接提交。第一类是涉及鉴权、加密、支付的代码。这类逻辑一旦出错后果不是“功能不可用”而是“数据泄露”或“资金损失”。模型可以帮你读代码、解释逻辑但最终改动必须人工写、人工审。第二类是数据库迁移脚本。迁移一旦执行就很难回滚模型对生产数据状态的理解有限让它生成迁移脚本风险太高。第三类是删除操作。无论是删文件、删表还是删字段都要人工确认。模型对“这个字段还有没有在用”的判断经常不准。第四类是依赖升级。大版本升级往往涉及破坏性变更模型可能只改了表面调用没处理深层兼容问题。这四类之外的日常业务代码、工具函数、测试、文档基本都可以放心交给它。6. 踩过的坑和踩完之后总结的规矩6.1 上下文给太多和给太少都会出问题刚开始用的时候我习惯把整个项目都塞给它觉得信息越多越好。结果发现模型反而抓不住重点改出来的东西东一榔头西一棒子。后来改成按需给上下文改哪个模块就只让它读那个模块和直接依赖效果明显好转。反过来上下文给太少也不行。有一次我只说“改一下这个函数”没告诉它这个函数被哪些地方调用结果它改了签名上层全炸了。所以现在的习惯是改之前先让它自己找出调用点把影响面摸清楚再动手。6.2 模型“自信地犯错”是最难防的模型最危险的地方不是它说“我不会”而是它用非常肯定的语气给出错误答案。比如它说“这个 API 支持某某参数”实际上根本不支持或者说“我已经处理了所有边界情况”实际上漏了空数组。防这个的办法只有一个关键结论必须自己验证。它说某个库有某个方法你去文档确认它说改完了你去看 diff它说测试通过了你去看测试输出。不要因为它语气肯定就跳过验证。6.3 密钥泄露这件事必须从流程上堵死用大模型写代码密钥泄露是真实存在的风险。模型可能会把你的 Key 写进示例代码、写进注释、甚至写进它生成的配置文件。一旦这些内容被提交就等于公开了。我的做法是三层防护第一层所有密钥只放环境变量代码里只引用变量名第二层.gitignore里把.env、*.key、config.local.*全部排除第三层提交前用工具扫一遍 diff确认没有硬编码的密钥。第三层可以用现成的密钥扫描工具也可以写个简单的正则检查。还有一点不要在对话里粘贴真实密钥。如果非要让模型帮你调试鉴权逻辑用占位符代替真实值调试完再换回去。6.4 别让它一次改太多这是我最深刻的教训。有一次我让它“重构整个数据处理模块”它一口气改了十几个文件结果中间状态根本没法验证最后只能全部回滚重来。现在的规矩是单次改动不超过三个文件超过就拆成多轮。每轮改完、验证完、提交完再开始下一轮。慢是慢一点但可控。而且拆成小步之后出问题容易定位回滚成本也低。7. 我现在的日常用法和几条硬规矩用到现在我的日常流程基本固定下来了。早上开工先让它读一遍昨天的提交记录总结一下进度然后按任务清单逐个处理每个任务走“说计划、改代码、跑测试、提交”的循环遇到不确定的 API 用法让它先查再写写完之后自己过一遍 diff确认没问题再推。几条硬规矩我基本不会破鉴权、支付、迁移、删除这四类代码模型只读不写。任何改动必须自己看 diff不看不算完成。密钥永远不进代码也不进对话。单次改动不超过三个文件超了就拆。AGENTS.md持续维护发现重复错误就补规则。这套用法下来重复性的编码工作确实省了很多时间但判断和把关的责任一点没少。模型是个很好的执行者但它不是责任人。代码最终署的是你的名字该看的、该验的、该拒的一样都不能省。如果你刚开始用建议先从一个小项目、一个模块试起把上面这套流程跑顺再逐步扩大范围。别一上来就想着“全自动”那大概率会翻车。先把协作节奏建立起来效率自然就上来了。